These documents preserve architecture, constraints, and rationale that code and tests cannot explain by themselves. Treat implementation and tests as the source of current behavior.

Choose the smallest durable record

internal/design/<area>/: architecture, subsystem, or feature design owned by the author.
internal/decisions/: one tactical choice and its tradeoffs.
rfc/: a proposal requiring wider approval, especially public API or hard-to-reverse product direction.
.agents/plans/: temporary implementation notes; delete before merge or extract durable rationale here.

Skip a record for ordinary implementation detail, inventories, status logs, or information already clear from source and tests.

Layout

Area	Contents
`element/`	Custom-element architecture
`i18n/`	Locale and translation architecture
`media/`	Media model architecture
`site/`	Documentation-site decisions
`spf/`	Streaming framework architecture, conventions, feature registry, and use-case compositions
`ui/`	Component and interaction designs

Put new records in an area directory. Add a new area only when at least two durable records are likely; otherwise use the nearest existing area.

Status

Status	Meaning
`draft`	Proposed or still under active design
`decided`	Choice made; implementation may follow
`active`	Living convention, index, or registry maintained with the code
`partial`	Registry feature or use case is partly implemented
`implemented`	Shipped; retained for rationale and stable contracts
`superseded`	Replaced; link the successor
`reference`	Prior art or research, not a status claim

Minimal format

---
status: decided
date: YYYY-MM-DD
---

# Title

## Decision

## Context

## Alternatives considered

## Rationale

Use a different structure for a living reference or registry, but keep frontmatter and make the document's authority clear.

Maintenance

Link current source and tests; do not copy APIs, schemas, or file inventories.
When implementation lands, collapse the record to durable rationale, constraints, consequences, and source pointers; remove speculative mechanics and current-behavior inventories.
When a record becomes wrong, update it, mark it superseded with a successor, or delete it if no rationale remains.
Keep implemented records only when their constraints, alternatives, or tradeoffs still help future changes.

Use write-design-doc for a design or decision record and write-rfc for wider proposals.