Four kinds of document, four different questions.
| Directory | Answers | Audience |
|---|---|---|
architecture.md |
What are the components, dependencies and runtime flows? | Anyone learning the app or changing its structure |
runbooks/ |
How do I operate it under pressure? | Whoever is on the host at 03:00 |
decisions/ |
Why is it shaped this way? | Anyone about to "simplify" a rule |
schema/ |
What is actually in the database? | Generated — never hand-edited (#417) |
releasing.md |
How do I cut and deploy a release? | Maintainer |
plans/ |
What was intended, at the time? | Provenance only — not current documentation |
Elsewhere in the repo:
| Where | What |
|---|---|
../README.md |
What Cluckwork is, and running it |
../CONTRIBUTING.md |
Local development, tests, branches, commits |
runbooks/aspire-local-development.md |
Local Aspire stack, persistence and safe reset |
runbooks/simulation-fixture-on-a-dev-database.md |
Bulk fixture data in a local debug database (Compose or Aspire) |
../AGENTS.md |
The canonical rule set — every invariant, for humans and coding agents |
../SECURITY.md |
Reporting a vulnerability; what CI enforces |
../specs/product/ |
Product & technical spec, phase plan, glossary |
../deploy/README.md |
Compose topology, caching, rollout ordering |
../web/README.md |
SPA development |
../tools/simulation/README.md |
Load, E2E and simulation harnesses |
Also here: security/ — the log-redaction policy. Every planning
record under plans/ carries a banner saying so on its own first
screen, because that is where a search result drops you.
A rule lives in one place, compressed, and links to the rest:
- the rule and the consequence of breaking it →
AGENTS.md; - the narrative that earned it — what shipped, which review round found it,
what the wrong fix was → a record in
decisions/; - the procedure a human follows → a
runbooks/entry with a drill; - the command a newcomer needs →
README.mdorCONTRIBUTING.md.
Copying a paragraph into a second file creates two copies that drift, and drift here has already produced contradicting statements of the same guarantee. Link instead.