Architecture decisions
Accepted records lock a newer instruction that is already live. Proposed records are recommended resolutions of an ambiguity. The product owner has not confirmed a Proposed record.
Questions only the owner can answer are in open-questions.md. The plan proceeds with the recommended answer in each row.
| ID | Title | Status | Decision |
|---|---|---|---|
| ADR-0001 | Product name and routes | Accepted | The UI name is markdown-kb. Pages are /{project}/{page-path} (for example /guide/docs/layout). /docs and /ledger redirect into the guide project. There is no space segment. |
| ADR-0002 | Sign-in and roles | Accepted | The first release has no auth. The four roles, and direct save for Owner and Editor, are the later target. |
| ADR-0003 | Storage | Accepted | The first release reads content/ at build time and stores drafts in localStorage. |
| ADR-0004 | Editor model | Accepted | Preview is the default. Editing is a block editor in the reading column. Source is a full-page editor. Command-/ or Control-/ switches between them. Edit turns editing on from preview and off from editing or source. Inline live preview is a later F09 option. |
| ADR-0005 | Reading type | Accepted | Body text is 17px with line-height 1.7. The column is capped at 760px, which binds, so the text is 696px wide. |
| ADR-0006 | Surfaces | Accepted | Surfaces are solid fills, and the hairline borders between them are removed. |
| ADR-0007 | Radius | Accepted | Radii are 12px controls, 10px outline rows, 18px blocks, 20px dialogs, 8px inline code, and 6px mark. |
| ADR-0008 | Right panel | Accepted; outline surface superseded by ADR-0037 | The third column is a full-height outline only, and the title row and status line use the page color. |
| ADR-0009 | Modals | Accepted | Settings, share, search, and shortcut help are dialogs. Editing and review flows are not. |
| ADR-0010 | Sharing | Accepted | "Anyone with the link" sets Can view or Can edit as the starting mode and grants no rights. |
| ADR-0011 | Phones | Accepted | Phones stay readable, editing works, the split stacks at 900px, and coarse-pointer targets are at least 44px. |
| ADR-0012 | Slug derivation | Proposed | A title becomes an ASCII slug of at most 80 characters, with -2, -3, … on collision. |
| ADR-0013 | Filename patterns | Proposed | Patterns allow only {date} and {slug}, and editing date rewrites the path in that save. |
| ADR-0014 | Ledger file types | Proposed | Schema files use type: schema. space.md and agents.md are type: doc at fixed paths. |
| ADR-0015 | Schema file errors | Proposed | A broken schema file fails schema_invalid, does not load, and that type then fails type_unknown. |
| ADR-0016 | required_when grammar | Proposed | required_when is equality on exactly one other field. Any other shape fails schema load. |
| ADR-0017 | Pinned version target | Proposed | [[slug@7]] returns the earliest revision with version 7, and later saves do not move the pin. |
| ADR-0018 | Rename and existing links | Superseded by ADR-0035 | Only a human renames. Other files are not rewritten, and links to the old slug are link_broken. |
| ADR-0019 | Links to archived documents | Proposed | A link to an archived document still resolves. link_broken is only a missing slug. |
| ADR-0020 | Embed depth and cycles | Proposed | Three transclusions render. A fourth level or a cycle shows a link and a fixed sentence, plus embed_broken. |
| ADR-0021 | Proposal edit matches | Proposed | Each find must match exactly once, in order, or the submission is rejected and no proposal is created. |
| ADR-0022 | Three-way merge of frontmatter | Proposed | Merge the whole file as lines. Do not reorder YAML keys or merge list items as a set. |
| ADR-0023 | Diff block alignment | Proposed | Pair same-type blocks in order when word-set Jaccard is at least 0.5. |
| ADR-0024 | Keymap scopes | Proposed | C and E depend on scope: dialog, editor, review, document, then global. |
| ADR-0025 | OAuth grant rate limits | Proposed | Each OAuth grant has the same 60/min, 30 proposals/hour, and 20 open-proposal limits as one API key. |
| ADR-0026 | Baseline value | Proposed | The baseline is the mean of concluded experiments on that harness, and deltas and arrows use that mean. |
| ADR-0027 | Repeated experiments on a chart | Proposed | Each concluded experiment is its own point, ordered by date then slug. |
| ADR-0028 | get_context token budget | Proposed | A token is 4 UTF-8 bytes. The pack is at most 6000 tokens, and the lowest-priority blocks drop first. |
| ADR-0029 | Search score | Proposed | Title matches rank first, then recency, then slug. score is 1 or 0. |
| ADR-0030 | History restore | Proposed | Restore appends a new revision with message Restore, checked against the schemas loaded now. |
| ADR-0031 | Task ticks in view mode | Proposed | A direct save toggles one checkbox and writes a revision with message Tick task. |
| ADR-0032 | Import batch outcome | Proposed | Each file is all or nothing. A mixed batch saves the valid files and does not roll them back. |
| ADR-0033 | Export and re-import identity | Proposed | Identical means the same UTF-8 bytes, including line endings and YAML key order. |
| ADR-0034 | Accessibility | Proposed | The bar is WCAG 2.2 Level AA, with a fixed focus order and a named Editing or Preview state. |
| ADR-0035 | Link targets and rename | Accepted | A wiki target is a page path or a unique file name, with an optional label. Rename and move rewrite links. link_broken is a target that does not resolve. |
| ADR-0036 | Settings sections | Accepted | Settings has General, Appearance, Editor, Agents, Keyboard, and About. Each holds only controls that change behavior, or state shown nowhere else. |
| ADR-0037 | Paper design direction | Accepted | The Paper file is the target look: a cobalt gradient primary, display type for names, a floating outline card, and faint text raised to pass AA. See specs/design.md. |
Gaps with no ADR
These section 2.3 gaps do not change behavior, so they have no record.
- Delta versus baseline, and the property-header arrows, use the baseline value. ADR-0026 sets that value.
- "Never hard-deleted" already has a rule: archive, do not delete. A legal-deletion path would be new scope.
- The performance numbers are already set (Inbox within 2 seconds, search under 100 ms, an agent flow under 10 seconds). Missing percentiles and a test environment do not change those limits.
- Success metrics need measurement queries. Defining a query does not change product behavior.
- Empty screens already teach in one line with one action, and loading states are already skeletons of the layout. That behavior is not limited to the Inbox.