Architecture Decision Records (ADR)

ADRs capture **one** durable architectural decision: context, decision, consequences, and alternatives. They are smaller in scope than [RFCs](../rfcs/README.md)

Purpose

ADRs capture one durable architectural decision: context, decision, consequences, and alternatives. They are smaller in scope than RFCs.

ADR Mode is manual opt-in only unless a durable decision has already been made and needs to be recorded. Do not start normal UI, docs, copywriting, Storybook, mock data, or app incubation tasks by writing an ADR.

Where ADRs Live

Location	Use
`docs/platform/architecture/decisions/NNNN-*.md`	Canonical for accepted platform decisions (already in use)
`docs/development/adr/0000-template.md`	Template for new ADRs

Existing records (do not duplicate):

When adding ADR 0004+, create docs/platform/architecture/decisions/0004-short-title.md using the template below (filename may drop numeric prefix in docs site slug per sync rules).

Status

Proposed    — under discussion
Accepted    — current truth
Deprecated  — no longer recommended
Superseded  — replaced by another ADR

When to Write an ADR

Choosing between two stable technical options (e.g. Query vs Zustand for remote data).
Recording a boundary future agents must not violate.
Closing an RFC with a single long-lived decision.
The user explicitly asks for ADR-first or decision-record work.

Do not write an ADR for every small patch.

Examples (conceptual)

Remote data uses TanStack Query; OS local UI state uses Zustand.
API worker uses Hono + OpenAPI at the edge.
Apps must not deep-import apps/os-shell internals.
Moments media uses object storage (R2), not Postgres bytea — Planned until implemented.

Template

Copy 0000-template.md.