# ADR 0001: Record Architecture Decisions
Audience: AI coding agents first.

## Status
Accepted.

## Context
This repo has load-bearing boundaries: account registry, shared state, health cache, routing, device auth, and tray UI.

If those boundaries drift, future changes become guesswork. A flat glossary is not enough. The repo needs a separate decision log that says what the architecture is, what changed it, and what stays stable.

## Decision
- Use `docs/adr/` for architecture decisions.
- Use one file per decision.
- Use zero-padded numeric prefixes for ordering.
- Put the decision title in the filename slug.
- Keep `CONTEXT.md` as the domain glossary only.
- Keep specs in `docs/specs/` as proposals and design contracts.
- Write an ADR when a change affects a boundary, ownership, persistence layout, process contract, or external interface.
- Prefer one ADR per decision. Do not bundle unrelated choices into one record.

## Consequences
- Future agents can find the decision trail without reading commit history.
- Reviews can check the decision instead of reconstructing it from code.
- Specs stay focused on design. `CONTEXT.md` stays focused on vocabulary.
- More docs to maintain, but only for decisions that matter.

## Anti-patterns
- Do not bury architecture decisions in comments or commit messages.
- Do not turn an ADR into a spec dump.
- Do not duplicate the glossary inside ADRs.
- Do not create a new architectural boundary without recording the reason.

## Checks
- A reader can say, in one sentence, what this ADR system is for.
- A reader can tell when a new ADR is required.
- A reader can tell where to look for vocabulary versus decisions versus proposals.