@nurix/etna 0.18.10 → 0.18.11

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

@@ -0,0 +1,894 @@
+# 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
+- [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.
+```
+
+---
+
+## 2. docs/structure.md (Authority Map)
+
+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 `harness-manager` agent 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) | `docs/routing.md` | File-Pattern Routes |
+| System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
+| Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
+| 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 |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
+| 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/routing.md`: The single hand-maintained map from code paths (and keywords) to the canonical doc and module for each. Code ownership lives here, not in feature-doc frontmatter. Update it whenever you add/move/delete a doc or move/rename owned source.
+- `docs/features/`: Living reference for implemented features. Carry **no** ownership frontmatter — a feature doc's code paths are declared by its row(s) in `docs/routing.md`. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is the only frontmatter a doc may carry.)
+- `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/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `docs/routing.md` patterns (the Module column groups routes into modules). 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/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 `routing.md` row, no 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/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 |
+```
+
+---
+
+## 2.5 docs/routing.md (Code-Path Ownership Map)
+
+Use for: the single hand-maintained map from code paths (and keywords) to the canonical doc + module. This is the source of truth for code ownership — feature docs carry no ownership frontmatter. Scaffold it once any feature doc owns code.
+
+```
+# Routing
+
+The single map from code paths (and keywords) to the doc that is canonical for them, and the module each belongs to. The source of truth for code-path ownership — feature docs carry no ownership frontmatter. Read this before touching unfamiliar code, then read the mapped doc.
+
+> **One canonical doc per path.** When two patterns match the same path, the **narrower** pattern wins; an equal-specificity overlap is a conflict — resolve it before merging. Hand-maintained — there is no generator. Keep it in sync when you add/move/delete a doc or move/rename owned source.
+
+## File-Pattern Routes
+
+| Pattern | Module | Canonical Doc | Memory |
+| ------- | ------ | ------------- | ------ |
+| `src/auth/**` | auth | features/login.md | memory/main.md |
+| `src/billing/**` | billing | modules/billing/features/invoicing.md | — |
+
+- **Pattern** — the narrowest glob covering the files the doc is canonical for. A doc may have several rows.
+- **Module** — the declared module the pattern belongs to, or `—` if the repo is flat (no module declared). Grouping rows by this column is how a module is tied to code.
+- **Canonical Doc** — the one doc to read before changing matching files (`features/…` when flat, `modules/{m}/features/…` when the module is declared).
+- **Memory** — the `docs/memory/` file with domain knowledge for this area, or `—`.
+
+## Keyword Routes
+
+| Keyword / topic | Canonical Doc |
+| --------------- | ------------- |
+| auth, login, SSO, refresh | features/login.md |
+
+## Top-Level Folders
+
+| Folder | Purpose | Doc |
+| ------ | ------- | --- |
+| `src/` | {what lives here} | {doc} |
+
+## How to Add a Route
+
+1. Add/extend a **File-Pattern Routes** row — narrowest pattern that doesn't overlap an existing row at equal specificity; set its Module (or `—`).
+2. Add keyword row(s) for discoverability.
+3. When you move/rename owned source, update the matching pattern(s) here — this map is hand-maintained.
+```
+
+---
+
+## 3. Code-Path Ownership & Anchors
+
+**Ownership.** A feature doc is the canonical reference for the code paths mapped to it in `docs/routing.md` (File-Pattern Routes). Feature docs declare ownership through their routing row(s), **not** through frontmatter. To find what a doc owns, read its rows in `routing.md`; to find the doc for a path, match the path against the patterns there (narrower wins). See the **routing-map derivation** in `SKILL.md` for turning code into routing rows.
+
+**Anchors (optional — the only frontmatter a living doc may carry).** A doc may carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
+
+```yaml
+---
+anchors:
+  - "qmd query: feature-name persistence shape"
+---
+```
+
+`anchors` is 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. `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/architecture/`, and `docs/operations/`.
+
+---
+
+## 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; + modules/, 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. -->
+
+## 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 **§11 Memory inbox entry** for its format.
+
+---
+
+## 5. 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
+---
+anchors: # optional — the only frontmatter a feature doc may carry; see §3
+  - "qmd query: wire envelope invariants"
+---
+```
+
+> This doc carries **no** ownership frontmatter. Declare the code paths it owns as File-Pattern Routes row(s) in `docs/routing.md` (§2.5) — projected at Draft, confirmed at Active.
+
+```
+# {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 `docs/routing.md` patterns 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; `docs/routing.md` row(s) confirmed against real code | Main agent (from actual code) |
+
+Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
+
+---
+
+## 6. 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
+```
+
+---
+
+## 7. 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 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 touches (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 `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
+```
+
+---
+
+## 8. 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
+```
+
+---
+
+## 9. Architecture Decision Record (ADR)
+
+Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/history/adr/` — an ADR is a **historical decision record**, not the deployed-design source of truth (which lives in `docs/architecture/`). When the design later changes, update `docs/architecture/` and write a new superseding ADR; never rewrite a shipped 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.
+
+---
+
+## 10. 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.
+
+---
+
+## 11. 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.