Design roadmap
The plan for this site itself: what Design is, the decisions behind it, and what's built versus still ahead. Kept here so Design documents its own direction.
What it is
One place to understand — and eventually to shape — how Tally works,
unifying what was scattered across TIPs/, specs/,
plan/ and GLOSSARY.md into a cross-linked,
text-first HTML site. Those folders have since been folded in and removed;
TIPs/ remains as the Markdown source the TIP pages are built
from. Each page reads cleanly as raw source
(for a human or an AI) and renders as a paged, navigable doc site — the
GraphEditor readme.html pattern, generalised to a whole
multi-document project.
Decisions made
- Name: Design. Covers system design (what the docs are) and the authoring/tooling future, without a later rename.
- Many standalone HTML pages at
design/*.html, tied together by a shared shell; CSS/JS/manifest tucked underdesign/assets/. - HTML is the source — no Markdown+render step. Chosen for flexibility while the shape of the whole system is still emerging, and to keep the eventual in-browser editor simple (one format).
- Text-first + progressive enhancement. Content lives in the markup; JS only adds the topbar + sidebar. JS off = a plain readable page.
- Status convention carried over from GraphEditor: implemented planned proposal reference.
- Migrate incrementally, don't block on merges. Bring
existing docs in as-is, tag their status, cross-link, and reconcile
conflicts in place. Hand-written
plan/notes are preserved for their original rationale even where parts have aged.
Status
| Piece | State |
|---|---|
| Shell (topbar, sticky sidebar TOC, status system) | implemented |
| Overview + Glossary pages | implemented |
| Glossary terms linkable (stable anchors) | implemented |
TIPs migrated in (built from TIPs/*.md) | implemented |
| Plan & specs imported, sources removed | implemented |
| Specs reconciled against the code | implemented |
| Project-anatomy groups + collapsing nav | implemented |
GraphEditor opened from a page's data-files | implemented |
Served at /design alongside the landing site | implemented |
| Cross-linking prose → glossary terms, sitewide | proposal |
| In-browser editing | proposal |
Absorb GraphEditor under design/graph/ | proposal |
Phasing
- Static site. Done. Shell built, docs migrated
and reconciled, cross-linked, served at
/design, andCLAUDE.mdpoints here. - In-browser editor. Edit a page's prose and save. The hard part is persistence: File System Access API for a local author, or an authenticated write endpoint when deployed. The editing UI (contenteditable on the semantic blocks) is the easy part. Deferred.
- Absorb GraphEditor under
design/graph/, sharing the shell, so a spec page can deep-link to the live dependency graph and back.
Drift, and how it gets caught
Consolidation surfaces existing inconsistencies — that's a feature. The first sweep (2026-09-09) closed these:
- Two glossaries merged into
one;
GLOSSARY.mdis now a pointer to it. - Duplicated data-model pages collapsed into
Data storage, which now names
data-model.tsas the authority rather than restating it. - Superseded crypto — the specs still described bare Schnorr signatures and AES-GCM envelopes; both were replaced by TIP-006's authorship proofs and NIP-44.
- Dropped TURN — removed from the docs that still assumed it.
What keeps recurring is transcription: a page that copies a field table, a constant, or a duration out of the code will drift, every time. The habit that works is to state the intent and the invariant here and name the file that holds the value. Reconciled pages carry a "reconciled against the code on <date>" line so the next reader knows how much to trust the detail.
Open questions
- Do specs/plan/TIPs keep their own identities as sections, or dissolve into one flat topic list?
- How far does
README.mdshrink? It now points into Design for the concepts, but the split between "repo front door" and "the docs" is still drawn by hand. - Editor persistence model for the deployed case (auth + conflict).