design

# Design ## Workflow 1. Read the request, repository instructions, relevant code, and linked material. 2. Resolve choices that would change behavior, interfaces, data, errors, security, operations, or tests. Ask only questions whose answers materially change the design. Recommend an answer when asking. 3. Write `docs/<feature-slug>/design.md` using the shape below. Keep it short and omit sections that do not apply. 4. Run the review pass. Fix what you can. List the rest under Open questions. 5. Stop for human review. Do not plan or implement. ## Document shape ```markdown # <Title> ## What and why The problem, who it affects, and what changes once this ships. Plain prose. ## How it works Walk one real case from start to finish. Name the thing that arrives, what handles it, what gets written down, and what the user sees. A reader should be able to picture the system running before they read any requirements. ## Decisions For each choice that could reasonably have gone another way: what you chose, what you rejected, and what it costs. One short paragraph each. Skip the choices nobody would argue about. ## Invariants Numbered statements that must hold at all times. These are what a reviewer checks a diff against, so keep them short and testable. ## Requirements - Observable behavior and constraints. ## Interfaces and data APIs, commands, events, schemas, config, compatibility, or migration. ## Naming and identity How every durable name or ID is derived, what happens w...