@nurix/etna 0.15.6 → 0.15.8

package/data/harnesses/code-fable/skills/documentation/references/templates.md

@@ -0,0 +1,942 @@
+# Documentation Templates
+
+Templates for all documentation needs.
+
+---
+
+## 1. docs/README.md (Documentation Root)
+
+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, patterns, and technical decisions.
+
+- [system-design.md](architecture/system-design.md) - High-level system architecture
+{list all architecture docs}
+
+---
+
+## 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}
+
+---
+
+## History
+
+Everything frozen or append-only.
+
+- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
+- [changelog/](history/changelog/) - Individual changelog entries
+- [plans/](history/plans/) - Historical implementation plans
+- [backlog.md](history/backlog.md) - Tracked work items and technical debt
+
+---
+
+## Contributing
+
+See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
+```
+
+---
+
+## 2. docs/structure.md (Authority Map)
+
+Use for: defining which folder owns which topic and how docs are maintained.
+
+```
+---
+harness-version: 12
+---
+
+# 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 `harness-manager` agent owns it and stamps the installed design epoch on every reconcile.
+
+## Authority Map
+
+Each topic has one canonical location. Read from here, not from plans or changelogs.
+
+| Topic | Authority | Key Files |
+| ----- | --------- | --------- |
+| System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
+| Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
+| Cross-module contracts | `docs/boundaries/` | one file per boundary (maintained by the `boundary` skill) |
+| Declared modules (bounded contexts) | `docs/modules/{m}/` | `features/` + `pillars/` |
+| Setup & development | `docs/operations/` | {key files} |
+| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
+| Change records | `docs/history/changelog/` | Individual entries |
+| Backlog | `docs/history/` | backlog.md |
+
+## Document Lifecycle
+
+Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update → Changelog Entry
+
+- Plans freeze at completion — never updated to reflect current code
+- Changelogs summarize + link to feature docs — no duplicated schemas
+- Feature docs are the living reference — updated when code changes
+
+## Folder Rules
+
+- `docs/features/`: Living reference for implemented features. Each spec includes YAML frontmatter with `owns`, `touches`, `depends_on` fields declaring code ownership.
+- `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). Update when cross-cutting concerns change.
+- `docs/boundaries/`: Horizontal typed application boundaries — one file per cross-module contract. Generated/maintained by the `boundary` skill; read before touching a shape it defines.
+- `docs/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `owns` globs. Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`. Worth declaring at ≥2 genuine bounded contexts; a single-context app stays flat under `docs/features/`.
+- `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
+- `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
+- `docs/history/changelog/`: Historical. Append-only.
+- `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 |
+```
+
+---
+
+## 3. Feature Ownership Frontmatter
+
+Use for: every feature doc in `docs/features/`. Declares which source files this doc is authoritative for.
+
+```yaml
+---
+owns:
+  - src/feature-name/**
+  - app/feature-name/**
+touches:
+  - src/shared/utils/feature-helper.js
+depends_on:
+  - docs/architecture/system-design.md
+anchors:
+  - "qmd query: feature-name persistence shape"
+---
+```
+
+- `owns`: Glob patterns for files this feature doc is the canonical reference for
+- `touches`: Files this feature interacts with but doesn't own
+- `depends_on`: Other docs that must be read for full context
+- `anchors` (optional): A list of qmd queries (or `#docid`s) that re-resolve to the code/facts this doc abstracts as they move; anchors are retrieval context plus a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, nothing auto-rewrites from an anchor result, and the doc's prose stays the human-owned abstraction. They detect **doc-area drift** (the subject moving or vanishing from the corpus), not a pure code rename — the query also matches the doc's own prose, so a rename that leaves the text unchanged won't shift the result; code-symbol drift is the maintenance named-referent check's job, and anchors complement it rather than replace it. Resolved via `qmd query --format json -c <collection>` against this repo's collections; absent qmd ⇒ anchors are inert (no error). Never required on any doc. The feature and boundary templates ship the exemplar, but `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/boundaries/`, `docs/architecture/`, and `docs/operations/` — so the convention and the check stay one mental model.
+
+---
+
+## 4. 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; + boundaries/, modules/, tests/ when present)
+- **Spec version:** v{harness-version}
+<!-- v{harness-version} resolves to the installed design epoch — read it from `.claude/harness.json` (`epoch`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
+
+## Knowledge Tiers
+
+Memory is a gradient — volume falls, signal rises, one hop down each tier. Tiers describe themselves here even before they fill:
+
+- **Inbox** (`docs/memory/inbox/`) — per-actor queue of session lessons, written by the `session-reflect` hook at session end and consumed by the distiller on digestion. Transient by design, rarely read directly.
+- **Fact-cards** (`docs/memory/facts/`) — distilled, provenance-linked atomic facts, written by the distiller (`facts` mode) from inbox entries and resurfaced at prompt time by the `prompt-recall` hook.
+- **This index** — the curated read tier: the learnings list below, distilled from the colder tiers and hand-appended.
+
+## 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.
+```
+
+> The per-actor memory **inbox** (`docs/memory/inbox/`) is *not* a baseline scaffold — the `session-reflect` hook creates it mechanically on the first reflected session. See **§12 Memory inbox entry** for its format.
+
+---
+
+## 5. Boundary File (docs/boundaries/{boundary}.md)
+
+> **This skill does not generate boundaries.** Typed-boundary generation is owned by the **`boundary`** skill (`generate` mode), which detects the stack + IA and applies its boundary taxonomy (`references/boundary-taxonomy.md`) to emit typed files. The baseline does **not** scaffold `docs/boundaries/` — `/boundary generate` runs right after the baseline ("baseline boundaries"). This section is the generic **boundary-file template** plus the guidance for *recognizing* what deserves a boundary.
+
+### What deserves a boundary
+
+A boundary is a **horizontal, cross-module contract** where the failure is silent and crosses module boundaries — the developer in module A has no reason to know module B will break. No import error, no runtime exception — just wrong behavior.
+
+Test: "If an agent edits this while working on a single feature, could it silently break something in a different feature?" If yes, it's a boundary.
+
+**Include:**
+
+- **Shared state shapes** — Redux store slices, persisted state, global context. Any shape that multiple modules read. Document every key, its type, and what reads it. Call out which slices are persisted and how rehydration handles shape changes (e.g., new fields become `undefined` for existing users).
+- **Entity registration checklists** — When adding a new entity/resource type requires touching N files across N modules to avoid silent data loss. List every file and what breaks if skipped.
+- **Cross-entity references by value** — When entity A stores entity B's identifier (slug, name, ID) as a plain value with no referential integrity. Document which fields reference what, and that renaming the target never propagates to the source.
+- **Format contracts** — When two systems produce identifiers in different formats (e.g., server returns `[a-z0-9]+`, client generates `[a-z0-9_]+`). Document both formats, where each is used, and what breaks on mismatch (e.g., lookup by key returns `undefined`, key-splitting logic produces wrong matches).
+- **Cross-module string coupling** — Action types, event names, status enums, or document type strings referenced by raw string literal instead of imported constant. List every file that hard-codes the string and what breaks if the source is renamed.
+- **Pipeline ordering dependencies** — Multi-step pipelines where Step N assumes Step N-1 has already written data to shared state. Document the implicit dependency and what happens if ordering changes (silent quality degradation vs. hard failure vs. hang).
+- **Completion signal contracts** — When modules communicate via return values, status fields, or Redux state transitions. Document the expected shape/type (e.g., `Promise<boolean>`, status enum values) and what happens if the contract changes (e.g., returning `undefined` instead of `true` causes permanent "failed" status).
+- **Host/plugin contracts** — Config objects consumed by a framework/host where some fields are validated and others aren't. Document which fields are unvalidated and what breaks silently if they change.
+- **Persistence shape safety** — How the persistence layer handles schema evolution. Document what happens when you add, remove, or rename a field in persisted state (e.g., no migration → stale data, new fields default to `undefined`).
+
+**Exclude:**
+
+- Module-internal architecture (well-encapsulated, no cross-module blast radius)
+- Authentication/authorization flows (behind adapters, feature code doesn't touch them)
+- Hook taxonomies and API reference (useful docs, but not boundaries — they don't cause cascading failures)
+- Networking details (WebSocket, HTTP client setup) — unless the event routing has cross-module string coupling
+- Feature folder conventions and code style (conventions, not breakage vectors)
+- Anything where failure produces an import error, a clear runtime exception, or a visible UI error — those are self-diagnosing and don't need a boundary
+
+### How to research a boundary
+
+When mapping a boundary (the `boundary` skill's `generate`/`create` job — this guidance is shared), investigate:
+
+1. **Shared state consumers** — For each Redux slice/context, find all files that read from it. Flag any file reading a slice it doesn't own (cross-module dependency).
+2. **String-coupled actions** — Grep for Redux action type strings referenced as raw strings rather than imported constants. These are invisible breakage points.
+3. **Entity lifecycle** — For each entity type, trace the full lifecycle: creation → change tracking → save payload → API → server. Identify every file that must be touched to support a new entity type.
+4. **Identifier format mismatches** — Compare how identifiers are generated (server vs. client) and how they're used as keys. Look for format divergence.
+5. **Pipeline data dependencies** — For multi-step processes, check what each step reads from shared state and what previous step wrote it. Test: "If I reorder these steps, does it fail loudly or silently?"
+6. **Persistence rehydration** — Check what reconciler is used, whether transforms exist, and what happens to existing users when a persisted shape changes.
+
+### Generic boundary-file template
+
+One file per boundary in `docs/boundaries/`. The `boundary` skill emits typed files using its boundary taxonomy; this is the generic fallback shape.
+
+```markdown
+---
+anchors:                    # optional — see §3 frontmatter reference
+  - "qmd query: store slice rehydration fallback"
+---
+
+# {Boundary Name}
+
+[BOUNDARY: {type} · {severity}]   <!-- type from the Application Boundary Scale; severity CRITICAL | HIGH | MED | LOW -->
+
+**Bounds:** {module A} ↔ {module B}   <!-- which modules sit on each side -->
+
+## Shape
+<!-- `transcribe`: a synthesized contract with no single code home (composed store tree, API envelope, the IA entity model, tenancy) — written inline, canonical here.
+     `point`: a self-locating shape (DB schema, route table) — a `file:line` pointer + invariants. Never copy a self-locating shape; it rots on the next change.
+     greenfield/pre-code `point` (contract decided, no code yet — e.g. boundary generate after a brainstorm): there's no file:line to point at, so instead (a) record the decided conventions inline here, (b) add a `planned <path>` line naming where the canonical source will land (e.g. `planned packages/api/src/db/schema.ts`), and (c) mark this row `point*` in the README index. Converts to (or gains) a real file:line pointer when the module lands. README index footnote: "* point-mode boundary whose pointer lands at implementation". -->
+
+## Invariants
+<!-- The rules that must hold across the boundary. -->
+
+## Blast radius
+<!-- What breaks, and where, if an invariant is violated. -->
+
+## Safe-change checklist
+<!-- Ordered steps to change this contract without silent breakage. Mark steps that fail silently if skipped. -->
+```
+
+---
+
+## 6. Feature Documentation (docs/features/{feature}.md)
+
+Use for: every feature in `docs/features/`. The same file persists from design (Status: Draft) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap.
+
+The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to spec-mode's return shape. The orchestrator drops spec-mode's findings into those slots without restructuring.
+
+```yaml
+---
+owns:
+  - src/feature-name/**     # projected at Draft, confirmed at Active
+touches:
+  - src/shared/state/feature.js
+depends_on:
+  - docs/features/related-feature.md
+anchors:                    # optional — see §3 frontmatter reference
+  - "qmd query: wire envelope invariants"
+---
+```
+
+```
+# {Feature Name}
+
+**Status:** Draft | Active   <!-- Draft: in design or in flight. Active: implemented and maintained. -->
+**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 spec-mode research) Files, routes, components, slices this feature involves. Group by module.
+
+| Module | Path | Role in this feature |
+|--------|------|----------------------|
+
+## Conventions to Follow
+
+(From spec-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 spec-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 spec-mode research) Existing feature docs whose `owns` or `touches` overlap with the projected scope. Resolve per row 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 | spec-mode agent |
+| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; frontmatter `owns`/`touches` confirmed against real code | Main agent (from actual code) |
+
+Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
+
+---
+
+## 7. Changelog
+
+Use for: recording code changes with function-level detail.
+
+```
+# 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
+
+### Modified
+- `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()`
+
+## Breaking Changes
+
+⚠️ **[Change description]**
+- Old: Previous behavior
+- New: Current behavior
+- Impact: What breaks
+- Migration: How to fix
+
+## Migration Steps
+
+- [ ] Step 1
+- [ ] Step 2
+
+## Files Changed
+
+- `src/path/file1.js` - Core changes
+- `src/path/file2.js` - Supporting updates
+```
+
+---
+
+## 8. Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
+
+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 `boundary` skill (`check` mode) parses the **Proposed Changes** sections to check boundary impact. 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 boundaries (from `docs/boundaries/`) this plan touches by name
+- "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 `docs/routing.md` 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
+```
+
+---
+
+## 9. Protected Files
+
+Use for: documenting critical files that need approval before modification.
+
+```
+# 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 |
+
+## Critical Logic
+
+### Category 1: [Name]
+
+**Purpose:** What these files do
+
+**Key Functions:**
+
+| Function   | Input | Output | Purpose        |
+|------------|-------|--------|----------------|
+| `func1()`  | Type  | Type   | What it does   |
+| `func2()`  | Type  | Type   | What it does   |
+
+**Critical Behavior:**
+- Important point 1
+- Important point 2
+```
+
+---
+
+## 10. Architecture Decision Record (ADR)
+
+Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/`.
+
+### When to write an ADR
+
+Write an ADR 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 did we do it this way?"
+
+Don't write an ADR 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` → `Superseded by ADR-NNN`
+
+ADRs are **immutable after acceptance**. If the decision changes, write a new ADR that supersedes it. Update only the old ADR's `status` frontmatter field — never its body.
+
+### Naming
+
+`ADR-NNN-short-title.md` — three-digit zero-padded number, kebab-case title. Numbers are assigned sequentially across the project and never reused.
+
+### Structure
+
+Three sections are required: **Decision**, **Context**, **Consequences**. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
+
+### Template
+
+```markdown
+---
+title: "ADR-NNN: Short title in sentence case"
+status: Accepted              # Proposed | Accepted | Deprecated | Superseded by ADR-NNN
+date: YYYY-MM-DD
+decision-owner: Name
+reviewers: []                 # optional
+supersedes:                   # optional, e.g., ADR-005
+tags: [adr]
+---
+
+# ADR-NNN: Short Title
+
+## Decision
+
+[One paragraph, active voice. "We will…" Lead with the answer.]
+
+## Context
+
+[The forces in play. What is the problem? Why does it need a decision now? Technical, political, social, and project-local pressures.]
+
+## 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*.]
+
+## Implementation Plan
+
+| Phase | Scope | Duration |
+|---|---|---|
+| 1 | … | … |
+
+## Open Questions
+
+1. **[Question]** — *Default*: [stated default until resolved].
+
+## Acknowledgements
+
+[Credit reviewers; name what they corrected. Include when reviewers materially shaped the doc.]
+
+## References
+
+- [External link or cross-reference]
+```
+
+### Rules
+
+- One decision per ADR. If you find yourself describing two decisions, split into two ADRs.
+- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
+- 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.
+- When superseding, set the old ADR's `status: "Superseded by ADR-NNN"` and the new ADR's `supersedes: ADR-OLD`.
+- The body is frozen at `Accepted`. Corrections to facts that were wrong at the time get a new ADR; typos and formatting fixes are fine.
+
+---
+
+## 11. Project Root README
+
+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 §1). 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.
+
+---
+
+## 12. Memory inbox entry (docs/memory/inbox/{actor}.md)
+
+Use for: the capture tier of the knowledge gradient — the durable lessons of each session (corrections, root-caused failures, decisions with rationale, discovered constraints), reflected by the `session-reflect` hook at session end. It is the raw input to distillation: `distiller facts` digests entries into fact-cards and **consumes** them, so the file holds exactly what is undigested.
+
+### File grain
+
+One file **per actor**: `docs/memory/inbox/{actor}.md`. `actor` is `git config user.name` lowercased and kebab-slugged; fall back to `$USER`, then `agent`. Two actors write to different files, so the inbox is **append-only without merge conflicts** — no shared file to contend over, no lock, no last-writer-wins.
+
+### File header
+
+Written once, on the first entry:
+
+```
+# Memory inbox — {actor}
+Session lessons awaiting distillation — appended by the session-reflect hook, consumed by `distiller facts`.
+```
+
+### Entry shape
+
+One block per reflected session, at most 6 bullets. Each bullet is one complete, self-contained sentence tagged `[project]` (true of the repo or its tooling) or `[user]` (true of the user) — the tag routes it at distillation: project facts → `docs/memory/facts/`, user facts → user-level memory.
+
+```
+## YYYY-MM-DD HH:MM · session <id> · {repo}@{branch}
+- [project] <one self-contained sentence, names and identifiers spelled out>
+- [user] <one self-contained sentence>
+```
+
+### Examples
+
+```
+## 2026-06-08 22:26 · session bc06c4fc · etna@dev
+- [project] The read_network_requests Chrome CDP tool only captures after its first call — arm it, trigger traffic, then read.
+- [user] jane-doe prefers minimal fixes over defensive machinery; fail loudly instead of engineering around a problem.
+```
+
+### Rules
+
+- **Hooks append, the distiller consumes.** A digested entry block is deleted by `distiller facts`; nothing else edits or reorders the file. A human may hand-append a lesson in the same shape — it rides the same queue.
+- **Sessions are deduped by id.** The reflect hook skips a session whose id already appears in the file (SessionEnd re-fires on resume).
+- **Secrets are redacted on write.** The privacy filter replaces secret shapes with `[redacted:{kind}]` (e.g. `[redacted:api-key]`, `[redacted:bearer]`, `[redacted:pem]`) before any line is appended — never paste a raw token in by hand either.
+- **Don't curate here.** Promotion to fact-cards and `docs/memory/main.md` happens at distillation; the inbox stays a transient queue.