The project's decision log: short, dated, immutable records of structural decisions. They answer "why is it like this?" months later, and prevent settled discussions from being reopened without knowing they were settled.

Two kinds, same format:

ADR (Architecture Decision Record) — technical choices: ADR-NNN-slug.md
PDR (Product Decision Record) — product direction and scope: PDR-NNN-slug.md

The current rules distilled from these records live in VISION.md (product identity + posture) and design-principles.md (engineering practices). Records are the memory; those pages are the law.

Rules

Records are immutable. Reversing a decision means writing a new record and marking the old one Superseded by ADR-NNN in its Status line — never editing history.
Write it in the same PR. A design that resolves an open structural question ships with its record. Half a page, written while the context is loaded — not a documentation session later.
Keep it to half a page. Four sections: Context, Decision, Alternatives considered, Consequences. If it needs more, link an issue or doc for the depth.
Number sequentially within each prefix (ADR-005 comes after ADR-004, independent of PDRs).

Template

# ADR-NNN: <Title>

- **Status**: Accepted | Superseded by ADR-NNN
- **Date**: YYYY-MM
- **Related**: #issue, other records

## Context
What was the situation and the forces at play? (2-5 sentences)

## Decision
What we decided, stated as a rule someone can follow.

## Alternatives considered
What else was on the table and why it lost. (bullets)

## Consequences
What this makes easier, what it makes harder, what to watch. (bullets)

Index

Record	Title	Status
ADR-001	SurrealDB as the database	Accepted
ADR-002	Delegate platform/media support to focused external libraries	Accepted
ADR-003	Migrate the UI from Streamlit to Next.js	Accepted
ADR-004	Long-running work runs on background workers	Accepted
ADR-005	Releases pass a risk-based confidence process, gated on the real image	Accepted
ADR-006	Migration granularity follows merge granularity, not release granularity	Accepted
PDR-001	Single-user first; don't preclude multi-user	Accepted
PDR-002	Provider-agnostic core by default	Accepted