Maintainer documentation
How this site is built and decided: a map of its decisions, design documents and security documents, and what lives where.
How this site is built and decided: its decisions, design documents and security documents.
Each directory's index.mdx holds its own conventions. The rules behind this layout are
ADR-0002.
This is the Maintain track of the project docs, this site itself. Packages, libraries and other
projects each have their own folder, content/<slug>/, published at /<slug>.
Three kinds of document
| Kind | Directory | Changes how |
|---|---|---|
| Package and project documentation | content/<slug>/, one folder per package or project | The product. Written and updated within the approved content conventions and the invariants in AGENTS.md §6. |
| Decisions | adr/ | Immutable once approved. A change of mind is a new ADR that supersedes the old one. |
| Design documents | everything else here | Living snapshots. Describe the site as it stands right now, edited in place. What is no longer true is deleted, not annotated. |
How they relate:
Directories
| Directory | Holds | Required when |
|---|---|---|
adr/ | Architecture Decision Records and their index | Every feature and functional change (ADR-0001) |
app-flow/ | The flow and screen wireframes, Mermaid and Archify, one file per feature | Any ADR that changes something a person sees (ADR-0008) |
prd/ | Requirements and user stories | Any reader-facing feature |
architecture/ | High-level design | A new module, content source, build step or external integration |
erd/ | Persisted data | The first ADR that stores data creates erd/system.mdx |
dfd/ | Data flow diagrams with trust boundaries | Data crosses a trust boundary or reaches an external system |
state/ | State machines | An entity with more than two states, or guarded / timed transitions |
sequence/ | Sequence diagrams | Multi-actor, async, or retrying flows |
api/ | Route handler and endpoint contracts | Anything another client or system calls |
rbac/ | Access matrices | Visibility depends on who the reader is |
security/ | Threat model, data classification, secrets, audit checklist | Always kept accurate; per-feature analyses when warranted |
_templates/ | A starting point for each document type | — |
Agent skills are not part of this project. They are tooling for contributors, vendored in
.claude/agent-skills/ outside content/, so they are never published: INDEX.md routes
tasks to skills and SOURCES.md records provenance
(ADR-0009).
Conventions for every design document
- Frontmatter
title, no#heading; then the header:Status,Last updated,Related ADRs. - Snapshot, not changelog: no revision tables, no "previously", no strikethrough.
- Every diagram is Mermaid and Archify together: flowcharts, sequences, state machines,
ERDs and screen wireframes (
block-beta) are a Mermaid fence inside a<Diagram>, with the Archify files indiagrams/<project-slug>/. The page shows the Archify view; the page's Markdown carries the Mermaid (ADR-0022,AGENTS.md§8). No binary or externally hosted images. - Sample values are invented, never a real person's name, a client's name, a real token or a private project's details.
- Links between documents are relative and start with
./or../(./adr/index.mdx), so the site resolves them to page URLs and they still work on GitHub. - Start from
_templates/. If unsure whether a document is required, write it.