ADR-0002 — Design documents are living snapshots, published as this site's Maintain track

• Status: Approved
• Date: 2026-10-31
• Deciders: P@puncoz
• Approved by: P@puncoz
• Approved on: 2026-11-01
• Supersedes: —
• Superseded by: ADR-0012 (decision 4: every page is MDX); ADR-0011 (decision 5, in part: Archify diagrams are embedded from sandboxed HTML, with the Mermaid version kept)
• Design documents: content/docs/maintain/index.mdx, content/docs/maintain/meta.json, every directory index.mdx, content/docs/maintain/_templates/

ContextCopy Anchor Link

This repository is a documentation site, so "documentation" means two different things here:

• Package and project documentation: the pages readers come for. It is the product.
• Documentation about the site: why it is built the way it is, and how it works.

The second kind serves two further jobs:

• Decisions need a permanent, ordered record of why.
• Design documents (flows, data flows, access rules, the threat model) must match the code at all times. A document that describes an old version is worse than none, because it is believed.

The owner decided on 2026-10-31 that the site's own documentation is published on the site, rather than kept in a separate docs/ folder outside the content. ADR-0015 then made the site a catalogued project like any other, slug docs, so this documentation is that project's Maintain track.

DecisionCopy Anchor Link

1. The site's own documentation is the Maintain track of the project docs, content/docs/maintain/, published at /docs/maintain (ADR-0015).
2. Three kinds of document:
   • content/<slug>/, except content/docs/maintain/ — package and project documentation, written and updated within the approved content conventions and the invariants in AGENTS.md §6.
   • content/docs/maintain/adr/ — immutable once approved; superseded, never rewritten.
   • Everything else under content/docs/maintain/ — living snapshots of the site as it stands, edited in place. No revision tables, no "previously X, now Y", no strikethrough. What is no longer true is deleted. Git and ADRs hold the history.
3. Typed directories: app-flow/, prd/, architecture/, erd/, dfd/, state/, sequence/, api/, rbac/, security/, each with an index.mdx of its conventions, and _templates/ with a starting point for each. Which ones a change requires is the table in AGENTS.md §8.
4. Pages are Markdown (.md) with a frontmatter title and no # heading; links between them are relative file paths.
5. Diagrams are Mermaid in fenced blocks: flows, sequences, state machines, ERDs and screen wireframes. No binary or externally hosted images. Rendering them as diagrams on the site is a separate decision (a new dependency).
6. An implementation is not complete while a design document contradicts it.
7. Skill-generated specs and plans go into these directories (usually the ADR and its design documents), not into a skill's own folder layout.

Options consideredCopy Anchor Link

ConsequencesCopy Anchor Link

Positive

• A reader finds the current system in the design docs, the reasons in ADRs, and the packages in the rest of the site — all in one place, searchable.

Negative / accepted trade-offs

• Everything here is public: the threat model, the audit checklist and the secrets inventory (variable names, never values). Accepted with this decision.
• Mermaid shows as code on the site until a renderer is adopted.

Content invariantsCopy Anchor Link

§6.1 applies here as everywhere: nothing about a private project goes into these pages.

Security considerationsCopy Anchor Link

These pages are published on every surface (AGENTS.md §6.1), so they must never hold a secret value, a private project's details, or an unfixed vulnerability's exploit path. A finding that is not yet fixed is reported to the owner, not written here, until it is fixed. content/docs/maintain/security/ follows the living-snapshot rule, so the threat model and secrets inventory are kept accurate rather than historical.

Implementation notesCopy Anchor Link

• content/docs/maintain/ with meta.json, index.mdx and each directory index.mdx; content/docs/meta.json catalogues the site as project docs (ADR-0015).
• content/docs/maintain/_templates/ holds the templates.
• AGENTS.md §8 states the three kinds, the page format and the "write before building" table.
• Tests: none — verified by bunx next build compiling every page.

Approved as written on 2026-11-01, by the owner's choice. Decision 4 was already superseded by ADR-0012 and decision 5 in part by ADR-0011; diagrams are made with Archify, with their Mermaid version kept, by the owner's standing choice in AGENTS.md §8.

Docs to update on implementationCopy Anchor Link

• content/docs/maintain/adr/index.mdx — status on approval.