# Documentation Structure

> This file is the entry point for understanding the docs folder.
> The `harness-version` frontmatter field is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile. This seeded copy ships without the field: its absence is what tells the first session the repo has not been baselined yet.

## Authority Map

Each topic has one canonical location. Read from here, not from plans or changelogs.

| Topic | Authority | Key Files |
| ----- | --------- | --------- |
| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
| System overview | `docs/architecture/` | system-design.md |
| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
| API surface | `docs/architecture/` | api.md |
| Security | `docs/architecture/` | security.md |
| Feature behavior | `docs/features/` | one `kebab-case.md` doc per feature |
| UX behavior — one surface | `docs/features/` | `{surface}-ux.md`, `type: ux` |
| UX behavior — cross-cutting (routing, information architecture, stream presentation) | `docs/architecture/` | `type: ux`, owns no code |
| Product specification (PRD, personas, journeys, information architecture) | `docs/architecture/` | prd.md, personas.md, journeys.md, information-architecture.md |
| Acceptance criteria | `docs/acceptance/` | one `kebab-case.md` doc per capability, `AC-n` keyed assert lines |
| Setup & development | `docs/operations/` | setup.md |
| Environment / config surface | `docs/operations/` | environment.md |
| Testing strategy | `docs/tests/` | strategy.md |
| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
| Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
| Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
| Backlog | `docs/history/` | backlog.md |

## The Two Natures

Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.

- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.

## Folder Rules

- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
- `docs/acceptance/`: Acceptance-criteria documents — one per capability, stating the promises the
  built product must keep as `AC-n` keyed assert lines that verification surfaces parse as claims.
  Written at specification time, before implementation; carries frontmatter (`type:`, `status:`)
  like every generated doc. Keys are stable once published — a criterion is retired by marking it,
  never by renumbering. Distinct from `docs/tests/`: acceptance criteria state what the product
  promises up front; the checklists in `docs/tests/` are the verification gate's own driving
  scripts, authored and maintained at the gate.
- **UX behavior** (`type: ux`) is placed by **scope, never by medium** — there is no `docs/ui/`.
  One surface's observable behavior is a feature concern and lives beside its LLD as
  `docs/features/{surface}-ux.md`; routing, information architecture, and the presentation
  contracts every surface obeys are whole-product concerns the interface merely renders, so they
  live in `docs/architecture/` and own no code. The genre exists because an LLD states what a
  feature *is* — which stays plausibly true through a rewrite of the surface — while nothing else
  states what a person *observes*, so a wire change lands, the interface absorbs it, and the
  absorption reads as maintenance. This document is what such a change contradicts. It **decides**
  behavior and is written before the code; the `docs/tests/` checklist only verifies it afterwards.
- `docs/tests/`: Behavioral checklists — the verification gate's driving scripts, one per feature (`docs/tests/{feature}.md`). **Each carries `type: checklist` and `verifies:`** — the feature or UX doc whose promises it proves. That edge is what makes a checklist reachable: a same-named file is a coincidence a resolver cannot trust, so without `verifies:` nothing implicates the checklist when its subject changes and it rots undetected. The inverse — which checklists cover a feature — is generated and injected, never listed in the feature doc.
- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
- `docs/history/changelog/`: Records. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
- `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
- `docs/history/backlog.md`: Open work items — a drain queue: append on discovery, delete when done (the changelog entry or plan that did the work is the record).

## Health Log

<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
| Date | Review Summary |
| ---- | -------------- |