# Genre registry

Every fact about a genre lives in one row of the table below: its template, its nature, its `type:` value, where it lives, the frontmatter keys it must carry and the sections it must have. `SKILL.md`, the `maintenance` agent and the shipped `docs/structure.md` name genres and defer here for these facts, and `scripts/doc-lint.mjs` reads this table to check them. The column order is a contract: the lint parses the table, and `packages/cli/tests/scripts/genreRegistry.test.mjs` in the forge fails when a row stops parsing or a template stops agreeing with it.

## The three natures

| Nature | Holds | Changes by | Dates | Ends |
| --- | --- | --- | --- | --- |
| `truth` | What is true now | Rewritten in place, present tense; no history in the body (an AD's Decision Changelog tail is the one bridge) | Frontmatter tooling keys only | Deleted, or `status: deprecated`, when its subject is gone |
| `record` | What happened | Written while live, then frozen at its terminal status; never edited after | In the filename or header | Never; it is the archive |
| `queue` | Work not done yet | Rows appended at the end and deleted when resolved, drained or promoted; nothing else is edited | Per row, as row metadata | Never; an empty queue is the healthy state |

## Registry

| Genre | Template | Nature | `type:` | Location | Required keys | Required sections |
| --- | --- | --- | --- | --- | --- | --- |
| Feature | [feature.md](feature.md) | truth | `feature` | `docs/features/{feature}.md` | `type` `description` `status` `objects` | Scope · Promises · For the agent |
| Package | [package.md](package.md) | truth | `package` | `docs/architecture/packages/{package}.md` | `type` `description` `status` `objects` | Scope · Ownership · Usage · Promises · For the agent |
| System | [system.md](system.md) | truth | `system` | `docs/architecture/systems/{system}.md` | `type` `description` `status` `objects` | Scope · Flow · Promises · For the agent |
| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/doctrine/{concern}.md` | `type` `description` `status` `objects` | Principles · Terms · Related documents |
| Playbook | [playbook.md](playbook.md) | truth | `playbook` | `docs/architecture/playbooks/{subject}.md` | `type` `description` `status` `objects` | Purpose · Related documents |
| Architecture decision | [architecture-decision.md](architecture-decision.md) | truth | `architecture-decision` | `docs/architecture/decisions/AD-NNN-{subject}.md` | `type` `title` `description` `status` `last-updated` | Decision · Context · Consequences |
| UX behavior | [ux-behavior.md](ux-behavior.md) | truth | `ux` | `docs/features/{surface}-ux.md` | `type` `description` `status` `objects` | Purpose · Anatomy · States · Affordances · Promises · Transitions |
| System overview | [system-overview.md](system-overview.md) | truth | `system-overview` | `docs/architecture/system-design.md` | `type` `description` | — |
| Domain model | [domain-model.md](domain-model.md) | truth | `domain-model` | `docs/architecture/domain-model.md` | `type` `description` | — |
| Glossary | [glossary.md](glossary.md) | truth | `glossary` | `docs/architecture/glossary.md` | `type` `description` | — |
| Non-goals | [non-goals.md](non-goals.md) | truth | `non-goals` | `docs/architecture/non-goals.md` | `type` `description` | — |
| Security overview | [security-overview.md](security-overview.md) | truth | `security-overview` | `docs/architecture/security.md` | `type` `description` | — |
| Testing strategy | [testing-strategy.md](testing-strategy.md) | truth | `testing-strategy` | `docs/architecture/doctrine/testing.md` | `type` `description` | — |
| API reference | [api-reference.md](api-reference.md) | truth | `api-reference` | `docs/architecture/api.md` | `type` `description` | — |
| Environment registry | [environment-registry.md](environment-registry.md) | truth | `environment-registry` | `docs/operations/environment.md` | `type` `description` | — |
| Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | truth | `checklist` | `docs/tests/{feature}.md` | `type` `description` `verifies` | — |
| Acceptance criteria | [acceptance-criteria.md](acceptance-criteria.md) | truth | `acceptance-criteria` | `docs/acceptance/{capability}.md` | `type` `description` `status` | — |
| Setup | [setup.md](setup.md) | truth | `operations` | `docs/operations/setup.md` | `type` `description` | Installation · First run · Verification |
| Operations procedure | [operations-procedure.md](operations-procedure.md) | truth | `operations` | `docs/operations/{procedure}.md` | `type` `description` | Steps · Verification |
| Implementation map | [implementation-map.md](implementation-map.md) | truth | `implementation-map` | `docs/operations/implementation-map.md` | `type` `description` | Waves · Active wave |
| Protected files | [protected-files.md](protected-files.md) | truth | `protected-files` | `docs/operations/protected-files.md` | `type` `description` | — |
| Docs index | [docs-readme.md](docs-readme.md) | truth | `docs-readme` | `docs/README.md` | `type` `description` | — |
| Folder index | — | truth | `folder-index` | `docs/{folder}/Readme.md` | `type` `description` | — |
| Changelog guide | [changelog-index.md](changelog-index.md) | truth | `changelog-guide` | `docs/history/CHANGELOG.md` | `type` `description` | — |
| Root README | [root-readme.md](root-readme.md) | truth | — | `README.md` | — | — |
| Plan | [plan.md](plan.md) | record | — | `docs/history/plans/YYYY-MM-DD-{slug}.md` | — | Background · Proposed Changes · Doc Obligations · Implementation Steps · Test Obligations |
| Changelog entry | [changelog-entry.md](changelog-entry.md) | record | — | `docs/history/changelog/YYYY-MM-DD-{three-words}.md` | — | — |
| Migration runbook | [migration-runbook.md](migration-runbook.md) | record | — | `docs/history/migrations/YYYY-MM-DD-{slug}.md` | — | — |
| Hand-over | [handover.md](handover.md) | record | `handover` | `docs/history/handovers/YYYY-MM-DD-{slug}.md` | `type` `description` `status` | — |
| Health log | — | record | — | `docs/history/health-log.md` | — | — |
| Deep research | — | record | `research` | `docs/history/research/{topic}/` | — | — |
| Brainstorm session | — | record | `brainstorm` | `docs/research/{topic}-brainstorm/` | — | — |
| Issue | — | record | `issue` | `docs/operations/issues/YYYY-MM-DD-{slug}.md` | — | — |
| Triage dossier | — | record | `triage` | `docs/operations/triage/YYYY-MM-DD-{slug}.md` | — | — |
| Release note | — | record | — | `docs/operations/release-notes/YYYY-MM-DD-vX.Y.Z.md` | — | — |
| Backlog | [backlog.md](backlog.md) | queue | — | `docs/history/backlog.md` | — | — |
| Journal | [journal.md](journal.md) | queue | — | `docs/history/journal.md` | — | — |
| Bookkeeping | [bookkeeping.md](bookkeeping.md) | queue | — | `docs/operations/bookkeeping.md` | — | — |
| Project memory | [memory-main.md](memory-main.md) | queue | `project-memory` | `docs/memory/main.md` | `type` `description` | — |
| Agent memory | — | queue | `agent-memory` | `docs/memory/{agent}.md` | — | — |

- **`type:` values:** a genre's `type:` value is the one its template's skeleton carries, and two genres may share one (setup and operations procedure are both `operations`). A dash means the genre carries no frontmatter, or carries none it must have. A value this table does not name is reported by the lint as `type-unknown`.
- **Locations:** `{name}` is one kebab-case path segment, `YYYY-MM-DD` a date, `AD-NNN` a zero-padded number. A location is where the genre lives in a repository that uses it; a folder nothing uses is absent.
- **Required sections:** the `##` headings every document of the genre carries, by name; the template states the optional ones and when each is written. A dash means the template's sections are guidance, not a fixed set. The lint checks them on truth documents; a plan's are checked by the hooks that read it.
- **Rows without a template:** each is written by its own tool (the `maintenance` agent's Health Log, the `brainstorm` skill, the deep-research and `triage` packs, a release pipeline) and is listed so its nature and place are settled here too.

## Ownership

Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written alongside it so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).

## Baseline scaffolds

The `maintenance` agent's baseline creates these when missing, from their templates: the docs index, the changelog guide, the backlog, project memory, setup (when the repo has a lockfile and a runnable root script; never a second first-run document) and the root README (never overwriting one). `docs/structure.md` is not among them: the installer ships it whole and overwrites it on every refresh.