docs-and-adrs

# Documentation and ADRs ## Overview Document decisions, not just code. The most valuable documentation captures the *why*: the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase. ## When to Use - Making a significant architectural decision - Choosing between competing approaches - Adding or changing a public API - Shipping a feature that changes user-facing behavior - Onboarding new team members (or agents) to the project - When you find yourself explaining the same thing repeatedly **When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes. ## Architecture Decision Records (ADRs) Read `references/adrs.md` when making a significant architectural decision (framework/library choice, data model, auth strategy, API architecture, or any expensive-to-reverse choice) — it has the "When to Write an ADR" checklist, the ADR template, and the lifecycle states. ## Inline Documentation Read `references/inline-comments.md` when writing or reviewing inline code comments — it has the why-not-what rule with before/after examples and the gotcha-documentation pattern. ## API Documentation Read `references/api-documentation.md` when adding or changing a public API — it has the TypeScrip...