# ADR-0002 — Design documents are living snapshots, published as this site's Maintain track (/docs/maintain/adr/ADR-0002-living-design-documentation)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** [ADR-0012](./ADR-0012-every-page-is-mdx.mdx) (decision 4: every page is
  MDX); [ADR-0011](./ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx) (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/`

## Context [#context]

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.

## Decision [#decision]

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 considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Published with the site, now `content/docs/maintain/` | The site documents itself with its own tooling; one content tree; search, Markdown and `llms.txt` cover the design docs too | Design documents, including the threat model, are public | Chosen by the owner |
| B — A separate `docs/` folder outside the content | Internal notes stay off the site | Two folders called "docs"; the design docs get none of the site's features | Rejected by the owner |
| C — Changelog-style design docs | History visible inline | Readers must reconstruct the current state | Rejected |

## Consequences [#consequences]

**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 invariants [#content-invariants]

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

## Security considerations [#security-considerations]

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 notes [#implementation-notes]

- [x] `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).
- [x] `content/docs/maintain/_templates/` holds the templates.
- [x] `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 implementation [#docs-to-update-on-implementation]

- [x] `content/docs/maintain/adr/index.mdx` — status on approval.