# docs/

Documentation hub for the `template-vertical` monorepo. **Start here if you landed at `docs/` directly.**

For the project entry point, see [`../CLAUDE.md`](../CLAUDE.md) (humans + agents) and [`../AGENTS.md`](../AGENTS.md) (package map + boundary rules).

---

## Resolving terminology

[`glossary.md`](./glossary.md) — **canonical vocabulary** for every cross-cutting term used in this repo (feature, use case, manifest, conformance, slice, coverage band, dispatch, etc.). When in doubt about what a term means _here_, check the glossary first.

---

## How the documentation is organised

```
docs/
├── glossary.md                 # canonical vocabulary
├── architecture/               # design + invariants (rarely changes)
│   ├── overview.md             # high-level architecture summary
│   ├── vertical-feature-spec.md  # canonical feature design spec
│   ├── dependency-flow.md      # workspace + import-graph reference
│   ├── template-tiers.md       # must-have vs optional core packages
│   ├── agent-first-workflow-and-conformance.md  # workflow + 5-gate design
│   ├── data-flow-explainer.html         # interactive (single-file)
│   ├── di-explainer.html                # interactive (single-file)
│   ├── feature-conformance-explainer.html  # interactive (single-file)
│   └── audit-and-compliance-explainer.html # interactive (single-file)
├── decisions/                  # ADRs (durable design decisions)
│   └── adr-001..adr-020.md     # 20 ADRs, numbered in order accepted
├── guides/                     # day-to-day how-to docs
│   ├── runbook.md              # ← first time? read this end-to-end
│   ├── conformance-quickref.md
│   ├── coverage.md             # 4-layer coverage cookbook (ADR-020)
│   ├── releasing.md            # release-please workflow + CHANGELOG cookbook (ADR-021)
│   ├── tdd-workflow.md
│   ├── testing-strategy.md
│   ├── adding-a-feature.md           # manual path
│   ├── scaffolding-a-feature.md      # generator path (preferred)
│   ├── scaffolding-core-package.md
│   ├── scaffolding-core-ui-component.md
│   ├── events-and-jobs.md      # requires `gen core-package events`
│   ├── realtime.md             # requires `gen core-package realtime`
│   ├── audit-and-compliance.md # requires `gen core-package audit`
│   ├── frontend-work-shape.md
│   └── infrastructure-work-shape.md
└── work/                       # local task system (PRD → Epic → Story → Task)
    ├── README.md               # work-folder layout + PRD lifecycle
    ├── _state.json             # derived index (orchestrator-managed)
    ├── prds/<date>-<slug>.prd.md  # PRDs
    └── <epic-slug>/...         # one folder per epic
```

## Document types

| Type                    | Where                    | Purpose                                          | Lifetime                                 |
| ----------------------- | ------------------------ | ------------------------------------------------ | ---------------------------------------- |
| **Glossary**            | `glossary.md`            | One sentence per term; flagged ambiguities       | Long-lived                               |
| **Architecture**        | `architecture/`          | Design invariants, system shape                  | Long-lived                               |
| **ADR**                 | `decisions/adr-NNN-*.md` | Single decision: context → choice → consequences | Long-lived                               |
| **Guide**               | `guides/`                | How-to, reference, troubleshooting               | Updated as features evolve               |
| **PRD**                 | `work/prds/*.prd.md`     | Implementation seed for one epic                 | `draft → in-review → approved → shipped` |
| **Epic / Story / Task** | `work/<epic>/...`        | Workflow artifacts                               | Created → in-progress → done             |

## When to put what where

- **A new architectural decision** (events, audit, instrumentation choices, etc.) → ADR. Number is `001 + max(existing)`.
- **A new how-to** (cookbook, troubleshooting, "how do I do X") → guide.
- **A new vocabulary term** that's cross-cutting → glossary, alphabetically grouped.
- **A new initiative** (multi-task feature work) → PRD seed. The decomposer refuses to run on `draft` — flip to `approved` after human review. `pnpm work prd-ship <id>` auto-flips to `shipped` on epic completion.
- **A new interactive diagram** → drop a single-file HTML at `architecture/<name>-explainer.html`; cross-link from the other explainers + from `architecture/overview.md`'s Interactive explainers section.

## See also

- [`../CLAUDE.md`](../CLAUDE.md) — entry point for agents
- [`../AGENTS.md`](../AGENTS.md) — package map + boundary rules + agent-driven development overview
- [`../README.md`](../README.md) — project-level README

## Conventions

- **Markdown over HTML** unless the doc is genuinely interactive (the 4 architecture HTMLs).
- **Reference ADRs by ID** (`ADR-NNN`) rather than path so renames don't break links.
- **Cross-reference paths sparingly** — they rot. Prefer naming the doc (e.g. "see the coverage guide").
- **Don't duplicate** — if two docs describe the same thing, consolidate or pick a single source of truth and link from the other.
- **Date PRDs + ADRs** in the file name (`YYYY-MM-DD` prefix for PRDs) and in their frontmatter.
- **Each ADR cites at least one related ADR** when extending or building on prior decisions.