@nurix/etna 0.18.23 → 0.18.25

package/data/harnesses/mobile/skills/documentation/references/templates.md

@@ -1,1091 +0,0 @@
-# Documentation Templates
-
-Templates for all documentation needs. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template below names its nature.
-
----
-
-## docs/README.md (Documentation Root)
-
-Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
-
-```
-# {Project Name} Documentation
-
-Technical documentation for {project description}.
-
-> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
-
----
-
-## Quick Links
-
-| Document                          | Description                          |
-| --------------------------------- | ------------------------------------ |
-| [Structure](structure.md)         | Documentation entry point and rules  |
-| [Setup](operations/setup.md)      | Installation and configuration guide |
-
----
-
-## Architecture
-
-System design, steering docs, and standing decisions — the truth layer.
-
-- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
-- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
-- [glossary.md](architecture/glossary.md) - Project vocabulary
-- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
-- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
-{list other architecture docs — api.md, security.md — when present}
-
----
-
-## Features
-
-Living reference docs for implemented features (how things currently work).
-
-- [feature-name.md](features/feature-name.md) - Feature description
-{list all feature docs}
-
----
-
-## Operations
-
-How to run, develop, and deploy.
-
-- [setup.md](operations/setup.md) - Installation and configuration guide
-{list all operations docs — environment.md when present}
-
----
-
-## History
-
-The records — everything dated, frozen, or append-only.
-
-- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [changelog/](history/changelog/) - Individual changelog entries
-- [plans/](history/plans/) - Implementation plans (frozen at completion)
-- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
-- [research/](history/research/) - Deep-research artifacts (one folder per topic)
-- [backlog.md](history/backlog.md) - Tracked work items and technical debt
-
----
-
-## Contributing
-
-See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
-```
-
----
-
-## docs/structure.md (Authority Map)
-
-Truth document. Use for: defining which folder owns which topic and how docs are maintained.
-
-```
----
-harness-version: 1.0.0
----
-
-# Documentation Structure
-
-> This file is the entry point for understanding the docs folder.
-> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
-
-## Authority Map
-
-Each topic has one canonical location. Read from here, not from plans or changelogs.
-
-| Topic | Authority | Key Files |
-| ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
-| System overview | `docs/architecture/` | system-design.md |
-| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
-| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
-| API surface | `docs/architecture/` | api.md |
-| Security | `docs/architecture/` | security.md |
-| Feature behavior | `docs/features/` | {key files} |
-| Setup & development | `docs/operations/` | {key files} |
-| Environment / config surface | `docs/operations/` | environment.md |
-| Testing strategy | `docs/tests/` | strategy.md |
-| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
-| Change records | `docs/history/changelog/` | Individual entries |
-| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
-| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
-| Brainstorm design records | `docs/research/{topic}-brainstorming/` (active) → `docs/history/brainstorms/{topic}/` (harvested) | state.md + pillars/ |
-| Backlog | `docs/history/` | backlog.md |
-
-## The Two Natures
-
-Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
-
-- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
-- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
-- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
-
-## Folder Rules
-
-- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
-- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
-- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
-- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
-- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
-- `docs/history/changelog/`: Records. Append-only.
-- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
-- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
-- `docs/research/{topic}-brainstorming/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the committed Brainstorming-Mode session for a topic (`state.md` + `pillars/`), written by the `brainstorm` skill. An active session lives under `docs/research/`; on close + harvest it **moves** to `docs/history/brainstorms/` and is **kept** as the provenance the truth layer distils from. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest copies its conclusions into `architecture/`/`history/`. Retire a topic's folder by hand only when the design line is dead. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
-- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
-
-## Health Log
-
-<!-- Updated by maintenance agent -->
-| Date | Review Summary |
-| ---- | -------------- |
-| {today} | Initial baseline — v{harness-version} structure established |
-```
-
----
-
-## Code-Path Ownership
-
-**Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See **Frontmatter Derivation** in `SKILL.md` for turning code into `owns:` globs.
-
----
-
-## Scaffold Files (create if missing)
-
-These standard files must exist after every baseline. Create them with these scaffolds if the repo doesn't already have them.
-
-### docs/history/CHANGELOG.md
-
-```
-# Changelog
-
-All notable changes to {Project Name} will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-
----
-
-## [Unreleased]
-
-{entries added here as work proceeds}
-
----
-
-## Links
-
-- [Setup Guide](../operations/setup.md)
-- [Architecture](../architecture/)
-
----
-
-## How to Update This Changelog
-
-1. Create a dated change file in `docs/history/changelog/`:
-   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
-
-2. Update this CHANGELOG.md with a high-level summary linking to the detail file
-
-3. Follow Keep a Changelog categories:
-   - **Added** for new features
-   - **Changed** for changes in existing functionality
-   - **Deprecated** for soon-to-be removed features
-   - **Removed** for now removed features
-   - **Fixed** for bug fixes
-   - **Security** for security improvements
-```
-
-### docs/history/backlog.md
-
-```
-# Backlog
-
-Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
-
----
-
-## Format
-
-- **[P0]** Description — discovered by [plan-name or agent-name]
-
----
-
-## P0 — Critical
-
-{items here}
-
-## P1 — High
-
-{items here}
-
-## P2 — Medium
-
-{items here}
-
-## P3 — Low
-
-{items here}
-```
-
-### docs/memory/index.md
-
-```
----
-type: cross-session-learnings
-description: Shared knowledge accumulated across agent sessions. All agents should consult and update this file.
----
-
-# Cross-Session Learnings
-
-## Documentation Baseline
-
-- **Baselined:** {today}
-- **Structure:** v{harness-version} (architecture, features, operations, history, memory; + tests/ when present)
-- **Spec version:** v{harness-version}
-<!-- v{harness-version} resolves to the installed harness version — read it from `.claude/harness.json` (`version`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
-
-## Learnings
-
-{Agents append learnings here as they discover gotchas, patterns, and architecture notes}
-```
-
-### docs/memory/main.md
-
-```
----
-type: project-memory
-owner: main-agent
-description: Project-wide patterns and conventions confirmed in this codebase. Project facts only — user-centric facts go in ~/.claude/.
----
-
-# Main Agent — Project Memory
-
-Append entries below, oldest at bottom. Format:
-
-## YYYY-MM-DD — {topic}
-
-{1-3 line fact, with file paths or references where relevant}
-
----
-
-## {today} — Baseline
-
-Memory file initialized during documentation baseline.
-```
-
----
-
-## Feature Documentation — the LLD (docs/features/{feature}.md)
-
-Truth document. Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap. The body always describes the feature as it currently is; the journey lives in the linked plan and changelog entries.
-
-**Required vs optional.** Four things are required in every feature doc: the frontmatter, **Goal**, **Background**, and **Files** — plus **Current Behavior** once research or implementation exists (at Draft it's the pre-feature baseline; at Active it's how the feature works today). Every other section is optional: include it only when the feature has something real to put in it (no Redux → no Redux section; no risks worth naming → no Risks section). A **minimal form** is sanctioned for small features: frontmatter + Goal + a short how-it-works section + Files. A two-screen doc that is accurate beats a full-template doc with empty sections.
-
-The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.
-
-```yaml
----
-owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
-module: billing                                  # optional — single bounded-context label; omit if cross-cutting
-keywords: [invoice, pdf]                         # required — discovery terms
-status: active                                   # required — active | draft | deprecated
-last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
----
-```
-
-> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.
-
-```
-# {Feature Name}
-
-<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
-**Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->
-
-## Goal
-
-One sentence. What this feature accomplishes, in user-facing terms.
-
-## Goals & Non-Goals
-
-**In scope**
-- Bullet 1
-- Bullet 2
-
-**Out of scope**
-- Bullet 1
-
-## Background
-
-Why this feature exists. The user need, the business trigger, the constraint that pushed it above the line. One paragraph.
-
-(For Product-level work, also include: problem statement, key hypotheses, open questions.)
-
-## Approach
-
-High-level shape of the solution. ASCII diagram if it helps. Implementation specifics belong in the plan.
-
-## Affected Modules
-
-(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
-
-| Module | Path | Role in this feature |
-|--------|------|----------------------|
-
-## Conventions to Follow
-
-(From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
-
-## Current Behavior
-
-(From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
-
-## Ownership Conflicts
-
-(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
-
-| Conflicting doc | Overlapping path(s) | Resolution |
-|-----------------|---------------------|------------|
-
-## Architecture
-
-[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]
-
-## Key Functions
-
-### `functionName(param1, param2)`
-**Goal:** What it accomplishes
-**Input:**
-- `param1` (type) - Description
-- `param2` (type) - Description
-**Output:** Return type and shape
-**Side Effects:** DB writes, API calls, state updates
-
-### `hookName(config)`
-**Goal:** What it provides
-**Returns:** `{ data, loading, error }`
-**Triggers:** On mount, on change, manual
-
-## State
-
-**Frontend (at persistence):**
-{
-  "data": [],
-  "changes": { "added": [], "updated": [], "removed": [] }
-  // "cache": {}  // UNUSED: Deprecated
-}
-
-**Storage:** localStorage `app_state`
-
-**Backend:**
-model Resource {
-  id        String   @id
-  data      Json
-  // oldField String?  // UNUSED: Legacy
-}
-
-**API Shape:**
-{ "status": 1, "data": {...} }
-
-## Redux (if applicable)
-
-**Slice:** `sliceName`
-
-**Actions:**
-- `setData(payload)` - Replace all data
-- `upsertItem(item)` - Add or update single item
-
-**Selectors:**
-- `selectAll(state)` → `Array<Item>`
-- `selectById(state, id)` → `Item | undefined`
-
-## Files
-
-- `src/path/to/main.js` - Core logic
-- `src/path/to/hooks.js` - React hooks
-
-## Open Questions
-
-- Question — who decides, by when
-- (Resolved questions: fold the resolution into Background.)
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
-```
-
-### Section evolution
-
-Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
-
-| When | Sections written | Source |
-| --- | --- | --- |
-| Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
-| Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
-
-Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
-
----
-
-## Changelog
-
-Record. Use for: recording code changes with function-level detail. Entries are frozen once written — they describe the change as it shipped, and are never edited to match later reality.
-
-Change categories follow the Keep a Changelog vocabulary — **Added / Changed / Deprecated / Removed / Fixed / Security** — the same six the master `CHANGELOG.md` scaffold instructs. Include only the categories that apply; all six share the same bullet shape (function/file, then detail lines).
-
-```
-# YYYY-MM-DD - [Title]
-
-## Summary
-
-Brief description of what changed and why.
-
-## Changes
-
-### Added
-- `newFunction(params)` in `path/to/file.js`
-  - Purpose: What it does
-  - Used by: Where it's called
-
-### Changed
-- `existingFunction()` in `path/to/file.js`
-  - Changed: What's different
-  - Reason: Why it changed
-  - Migration: What callers must do
-
-### Removed
-- `oldFunction()` from `path/to/file.js`
-  - Replaced by: `newFunction()`
-
-### Fixed
-- `buggyFunction()` in `path/to/file.js`
-  - Bug: What was wrong, when it manifested
-  - Fix: What changed
-
-(Deprecated / Security follow the same shape.)
-
-## Breaking Changes
-
-⚠️ **[Change description]**
-- Old: Previous behavior
-- New: Current behavior
-- Impact: What breaks
-- Migration: How to fix
-
-## Migration Steps
-
-- [ ] Step 1
-- [ ] Step 2
-
-## Verified
-
-- What was exercised end-to-end and the observed result — real runs, real fixtures, measured timings
-- A future agent diagnosing a regression starts from this evidence
-
-## Files Changed
-
-- `src/path/file1.js` - Core changes
-- `src/path/file2.js` - Supporting updates
-```
-
----
-
-## Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
-
-Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
-
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
-
-```
-# {Feature Name}
-
-**Status:** Draft | In Progress | Complete | Abandoned
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
-**Started:** YYYY-MM-DD
-**Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
-
-## Background
-
-Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.
-
-## Proposed Changes
-
-### New Files
-
-- `src/path/new-file.js` — purpose
-
-### Modified Files
-
-- `src/path/existing.js` — what changes and why
-
-### New Entities / State
-
-- `entities.foo` — new Redux slice / DB table / persisted shape
-- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)
-
-### API Changes
-
-- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
-- `PUT /api/bar` — request shape changes; see Migration
-
-### Cross-Module Contracts Affected
-
-- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
-- "None" is a valid answer and means the `boundary` check will pass cleanly
-
-## Implementation Steps
-
-1. Concrete, ordered, testable
-2. Each step ends with something verifiable
-3. ...
-
-## Done Criteria
-
-- [ ] Implementation complete and verified
-- [ ] Affected docs updated (use the injected ownership index to find them)
-- [ ] Changelog entry created in `docs/history/changelog/`
-- [ ] Plan marked `Status: Complete`, **Completed:** date filled
-
-## Open Questions
-
-- Question — who decides, by when
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
-```
-
----
-
-## Operations Procedure (docs/operations/{procedure}.md)
-
-Truth document. Use for: any **recurring** procedure — setup, development, deployment, maintenance. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
-
-A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
-
-Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
-
-If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
-
-```
-# {Procedure Name}
-
-**Goal:** What this procedure accomplishes, one line.
-
-## Preconditions
-
-- Access, tools, or state required before starting — exact versions, env vars, credentials location
-
-## Steps
-
-1. One action per step, exact command in a code block
-2. Note expected output where it disambiguates success from failure
-
-## Verification
-
-- The observable end state that confirms it worked — exact check commands, not "it should work now"
-
-## Troubleshooting
-
-- Symptom → cause → fix (append entries as failures are root-caused)
-
-## Rollback
-
-- How to undo, and when undo stops being possible
-```
-
----
-
-## Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
-
-Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
-
-Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.
-
-```
-# Migration: {Title}
-
-**Goal:** What this migration accomplishes and why it runs now, one or two lines.
-**Executes against:** {environment / database / system}
-
-## Preconditions
-
-- Backups taken, feature flags set, access confirmed — exact checks
-
-## Steps
-
-1. One action per step, exact command in a code block
-2. Note expected output where it disambiguates success from failure
-
-## Verification
-
-- The observable end state that confirms success — exact check commands
-
-## Rollback
-
-- How to undo, and the point of no return
-
-## Outcome
-
-<!-- Stamped once, immediately after execution; the file freezes with it. -->
-**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
-```
-
----
-
-## Protected Files
-
-Truth document. Use for: documenting critical files that need approval before modification.
-
-This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
-
-```
-# Protected Files
-
-Critical files requiring approval before modification.
-
-## File List
-
-# Category 1 - Description
-path/to/critical/file1.js
-path/to/critical/file2.js
-
-# Category 2 - Description
-path/to/another/file.js
-
-## Risk Summary
-
-| Category   | Risk if Broken  |
-|------------|-----------------|
-| Category 1 | Specific impact |
-| Category 2 | Specific impact |
-
-## Why Protected
-
-### Category 1: [Name]
-
-**Purpose:** What these files do, one or two lines
-**Owning doc:** [docs/features/{feature}.md] — canonical reference for how this code works
-**Invariants:**
-- The behavior that must not break, stated as a constraint (not a function tour)
-- Important point 2
-```
-
----
-
-## Architecture Decision (AD)
-
-Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance.
-
-### One subject per AD
-
-The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one.
-
-### When to write an AD
-
-Write an AD when **all three** apply:
-
-1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation
-2. Alternatives were genuinely considered and rejected
-3. Future maintainers will ask "why is it this way?"
-
-Don't write an AD for:
-
-- Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`)
-- Routine implementation choices with no rejected alternatives
-- Anything you'd be happy reversing without ceremony
-
-### Lifecycle
-
-`Proposed` → `Accepted` → `Deprecated`
-
-Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
-
-### Naming
-
-`AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused.
-
-### Structure
-
-Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
-
-### Template
-
-```markdown
----
-title: "AD-NNN: Short title in sentence case"
-status: Accepted # Proposed | Accepted | Deprecated
-created: YYYY-MM-DD
-last-updated: YYYY-MM-DD # bump on every revision
-decision-owner: Name
-reviewers: [] # optional
-tags: [ad]
----
-
-# AD-NNN: Short Title
-
-## Decision
-
-[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
-
-## Context
-
-[The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.]
-
-## Consequences
-
-**Positive:**
-
-- [What becomes easier]
-
-**Negative:**
-
-- [What becomes harder, what we accept reluctantly]
-
-**Risks:**
-
-- [Second-order effects you can already see, with mitigations if known]
-
-<!-- Optional sections below. Include only when warranted by the decision's weight. -->
-
-## Decision Drivers
-
-[Hard non-negotiables vs. strong levers. Include when alternatives exist and the criteria aren't self-evident from Context.]
-
-## Options Considered
-
-| Option       | Pros | Cons | Outcome               |
-| ------------ | ---- | ---- | --------------------- |
-| **Option A** | …    | …    | **CHOSEN**            |
-| Option B     | …    | …    | Eliminated — [reason] |
-
-## Deep Comparison
-
-[Honest framing of the strongest alternative(s). Include when the table doesn't make the reasoning obvious. State the *real* reason each was rejected — not a strawman.]
-
-## Architecture in Detail
-
-[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.]
-
-## Open Questions
-
-1. **[Question]** — _Default_: [stated default until resolved].
-
-## References
-
-- [External link or cross-reference]
-
-## Decision Changelog
-
-<!-- The provenance tail — append-only, newest first. One entry per revision: what changed, the trigger, the previous choice, and the plan that implemented it. Added on the first revision; the initial acceptance is the last entry. -->
-
-- YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].)
-- YYYY-MM-DD — Initial decision accepted. Implemented by [plan link].
-```
-
-### Rules
-
-- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
-- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
-- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
-- **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
-- **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
-- **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
-- No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
-- Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.
-
----
-
-## System Overview (docs/architecture/system-design.md)
-
-Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
-
-Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
-
-```
-# System Overview
-
-## What this is
-
-{Two or three sentences: what the system does, for whom, in what environment it runs.}
-
-## Subsystem map
-
-┌──────────┐     ┌──────────┐     ┌──────────┐
-│ Frontend │────▶│   API    │────▶│    DB    │
-└──────────┘     └──────────┘     └──────────┘
-{One box per subsystem; label the arrows with the contract that crosses them.}
-
-- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
-
-## Key flows
-
-{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
-
-## Where the truth lives
-
-| Area | Canonical doc |
-| ---- | ------------- |
-| {area} | [{doc}](path) |
-```
-
----
-
-## Domain Model (docs/architecture/domain-model.md)
-
-Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
-
-Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
-
-```
-# Domain Model
-
-## Entities
-
-| Entity | What it is | State lives in |
-| ------ | ---------- | -------------- |
-| {Entity} | {one line} | {table / slice / service} |
-
-## Relationships
-
-- {EntityA} 1—N {EntityB} — {the meaning of the link}
-- {EntityB} N—N {EntityC} via {join} — {meaning}
-
-## Lifecycle states
-
-{Only for entities with real state machines.}
-
-- **{Entity}**: draft → active → archived — {what moves it between states}
-
-## Invariants
-
-- {A relationship or state rule that must always hold, stated as a constraint}
-```
-
----
-
-## Glossary (docs/architecture/glossary.md)
-
-Truth document. Use for: the project's vocabulary — one name per concept, one line per name. Alphabetical. When the code uses a different name than the docs, record it in **In code** so readers can bridge; one concept never gets two doc names.
-
-```
-# Glossary
-
-| Term | Meaning | In code |
-| ---- | ------- | ------- |
-| {Term} | {one-line definition} | `{identifier}` |
-```
-
----
-
-## Non-Goals (docs/architecture/non-goals.md)
-
-Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
-
-```
-# Non-Goals
-
-Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
-
-- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
-```
-
----
-
-## API Reference (docs/architecture/api.md)
-
-Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
-
-Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
-
-```
-# API Reference
-
-## Conventions
-
-- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
-- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500
-
-## {Resource group}
-
-| Method | Path | Purpose | Auth | Owning doc |
-| ------ | ---- | ------- | ---- | ---------- |
-| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
-```
-
----
-
-## Environment Registry (docs/operations/environment.md)
-
-Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
-
-**Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
-
-```
-# Environment Registry
-
-Every variable the code reads. `.env.example` mirrors this list.
-
-| Variable | Purpose | Required | Where set | Secret |
-| -------- | ------- | -------- | --------- | ------ |
-| `DATABASE_URL` | {one line} | yes / default: `{value}` | local `.env` / CI / prod | yes |
-```
-
----
-
-## Security Overview (docs/architecture/security.md)
-
-Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
-
-Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
-
-```
-# Security Overview
-
-## Assets
-
-- {What's worth protecting — data classes, credentials, tenant isolation}
-
-## Trust boundaries
-
-- {Boundary} — {what crosses it, and what checks the crossing} 
-
-## Controls
-
-| Control | Protects against | Implemented in |
-| ------- | ---------------- | -------------- |
-| {control} | {threat} | `{file/module}` |
-
-## Accepted risks
-
-- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
-```
-
----
-
-## Testing Strategy (docs/tests/strategy.md)
-
-Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
-
-Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
-
-```
-# Testing Strategy
-
-## Levels
-
-| Layer | Runner | Lives in | Covers |
-| ----- | ------ | -------- | ------ |
-| Unit / integration | {runner} | `tests/` | {what} |
-| E2E | {runner} | `e2e/` | {what} |
-
-## Running
-
-- `{pm} test` — the whole unit suite (CI gate)
-- `{pm} run test:e2e` — {when to run}
-
-## Deliberately untested
-
-- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
-
-## Adding a test
-
-1. {Where the file goes, what it's named, where fixtures live}
-```
-
----
-
-## Project Root README
-
-Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
-
-### Strategy
-
-The root README answers, in order:
-
-1. **What is this?** — one to two sentences, no marketing claims
-2. **What do I get if I install it?** — capability families
-3. **What's it built on?** — terse stack list with versions
-4. **How do I run it?** — the three or four scripts that matter
-5. **How is it laid out?** — directory tree, one-liner per significant folder
-6. **How do I extend it?** — numbered contribution checklist
-7. **What state is it in?** — pre-publish, beta, stable, internal
-
-Skip any section that doesn't apply. Don't pad to fill the template.
-
-### Writing rules
-
-- **Sentence-case headings.** "Getting started", not "Getting Started".
-- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
-- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
-- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
-- **Directory tree as a code block**, not a nested markdown list.
-- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
-- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
-- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
-
-### Template
-
-```markdown
-# {package-name}
-
-{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
-
-## What's in the box
-
-- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
-- **{Family 2}** — {what's in it.}
-- **{Family 3}** — {what's in it.}
-
-The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
-
-## Stack
-
-- {Framework} {version} · {Language} {version}
-- {Build tool} {version}
-- {Other load-bearing deps}
-
-## Getting started
-
-\`\`\`bash {pm} install {pm} run dev # what it does (port, URL) {pm} run build # what it does {pm} run preview # what it does (omit if not applicable) \`\`\`
-
-{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
-
-## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
-
-{Brief description of the dev/runtime surface.}
-
-| {Thing}              | {What it shows / does} |
-| -------------------- | ---------------------- |
-| `{route or command}` | {description}          |
-
-## Layout
-
-\`\`\` src/ ├── {entry-file} # {purpose} ├── {folder}/ # {purpose} │ └── ... └── {folder}/ # {purpose} \`\`\`
-
-## Adding a {primary unit}
-
-1. {Drop the source under the right family/folder.}
-2. {Re-export from the public surface.}
-3. {Wire into the playground / example app / test harness so reviewers can see it render.}
-4. {Document any divergence from upstream in `docs/{...}`.}
-
-## Styling ← optional; replace with whichever cross-cutting concern matters most
-
-{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
-
-## Status
-
-{Pre-publish, beta, stable, internal-only. State what's stable and what's still moving — readers should know whether the API can be relied on.}
-
-## License
-
-{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
-```
-
-### Baseline scaffolding behavior
-
-The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
-
-**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.