<!-- Generated by /app-init. Downstream project owns this file after generation. -->
<!-- Framework will NOT overwrite this file on re-deploy. -->
<!-- Ref: AGENTS.md §Document Lifecycle Governance -->

# Documentation Index

> **Naming Axiom**: One topic, one canonical file. Before creating any new `.md` file in `docs/`, verify no existing file covers the same domain (`ls docs/<subdir>/`). If a canonical file exists, write a pointer, not a copy.

## Retrofit Note

If your project already has a `docs/README.md`, keep that file and merge these headings into it manually. Treat this template as merge-safe retrofit guidance, not as a replacement request. The framework must not require deleting or regenerating downstream-owned docs just to adopt the taxonomy.

## Document Types & Canonical Paths

| Type | Path | Status | Lifecycle | Owner Workflow |
|---|---|---|---|---|
| Domain Doc (Synthesis) | `docs/architecture/<domain>.md` | `living` | Created by `/app-init`; read by `/bootstrap`; rewritten only by `/govern-docs --restructure` | `/govern-docs` |
| Domain Doc (Decision Log) | `docs/architecture/<domain>.log.md` | `living` | Created on first `/ship` consolidation; append-only | `/ship` |
| Feature Spec | `docs/specs/<feature>.md` | `draft → frozen → shipped` | Created by `/spec`; frozen on approval; shipped by `/ship` | `/spec`, `/ship` |
| ADR | `docs/adr/ADR-NNN-<name>.md` | `accepted` | Created by `/adr` or `/app-init`; immutable once accepted | `/adr` |
| Product Backlog | `docs/specs/_product-backlog.md` | `living` | Created by `/spec-intake`; updated throughout product lifecycle | `/spec-intake`, `/ship` |
| Review Snapshot | `docs/reviews/<YYYY-MM-DD>-<scope>.md` | `snapshot` | Created by `/audit`; findings MUST route to canonical Domain Docs | `/audit` |
| Guide | `docs/guides/<topic>.md` | `living` | Created manually or by `/govern-docs` | varies |

## Directory Purposes

### `docs/architecture/`
Living Domain Documents. Each file describes how one domain of the system works **right now**.
- L1 Synthesis (`<domain>.md`): Current effective design principles. Hard cap: 150 lines. What agents read at bootstrap.
- L2 Decision Log (`<domain>.log.md`): Append-only chronological decisions. Never deleted. Agents read only for traceability.

### `docs/specs/`
Feature specifications and product backlog.
- `_product-backlog.md`: Living feature inventory.
- `<feature>.md`: Lifecycle — `draft` (in progress) → `frozen` (approved, locked) → `shipped` (delivered).
- Frozen specs: require unfreeze approval to modify. Shipped specs: historical reference only — read Domain Doc L1 for current design.

### `docs/adr/`
Architecture Decision Records. Immutable once accepted. Superseded by a new ADR, never deleted.

### `docs/reviews/`
Temporal audit and review snapshots. These are **historical records**, not canonical truth.
- Conclusions MUST be routed to `docs/architecture/` (via `/ship` Knowledge Consolidation) or `docs/specs/` (via spec amendment).
- Review snapshots MUST NOT be treated as design authority.

### `docs/guides/`
Usage guides, tutorials, and runbooks. Living documents, owned by the project team.

## Amendment Rules

| Situation | Rule |
|---|---|
| Spec is `draft` | Edit directly |
| Spec is `frozen`, pre-ship | Unfreeze (requires user approval via §4.2 protocol), edit, re-freeze |
| Spec is `shipped` | Create NEW spec with `File Relationship: EXTENDS <old-spec>` |
| Domain Doc L1 | Only `/govern-docs --restructure` may rewrite |
| Domain Doc L2 | Append-only via `/ship` Knowledge Consolidation |
| ADR | Never modify — create superseding ADR |
