@nurix/etna 0.1.3 → 0.2.0

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

@@ -0,0 +1,901 @@
+# 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.
+
+```
+# Documentation Structure
+
+> This file is the entry point for understanding the docs folder.
+
+## Authority Map
+
+Each topic has one canonical location. Read from here, not from plans or changelogs.
+
+| Topic | Authority | Key Files |
+| ----- | --------- | --------- |
+| System architecture | `docs/architecture/` | {key files} |
+| Feature behavior | `docs/features/` | {key files} |
+| 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 technical decisions. Update when cross-cutting concerns change.
+- `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 — 6-folder 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
+---
+```
+
+- `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
+
+---
+
+## 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:** 6-folder (architecture, features, operations, history, memory, tests)
+
+## 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.
+```
+
+### docs/OWNERSHIP_INDEX.md
+
+```
+# Ownership Index
+
+Auto-generated by the maintenance agent (Step 0). Do not edit by hand.
+
+**Generated:** {today}
+
+| Doc | Owns | Touches | Depends On |
+|-----|------|---------|------------|
+| [features/{name}.md](features/{name}.md) | `glob1`, `glob2` | `path` | `doc1`, `doc2` |
+
+## Unowned Docs
+
+{Feature docs missing frontmatter, listed here so they can be backfilled}
+```
+
+---
+
+## 5. docs/operations/guardrails.md (Cascading Failure Boundaries)
+
+Use for: documenting contracts, shapes, and coupling points where a change in one module silently breaks another. Created during baseline audit. Updated when new cross-module contracts are discovered.
+
+### What belongs in guardrails
+
+A guardrail is something where **the failure is silent and crosses module boundaries**. The developer working in module A has no reason to know that 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 guardrail.
+
+**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 guardrails — 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 guardrails
+
+### How to research guardrails
+
+When creating or updating `docs/operations/guardrails.md`, use sub-agents to 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.
+
+### Template
+
+```markdown
+# Guardrails
+
+Things that silently break across modules if touched wrong. Each section explains what the contract is, where it's consumed, and what goes wrong if violated.
+
+---
+
+## 1. [Contract Name]
+
+[One-line description of what this contract governs.]
+
+### The contract
+
+[Describe the shape, format, or protocol. Show code if it's a data shape.]
+
+### Where it's consumed
+
+[Table or list of every file/module that depends on this contract.]
+
+### What breaks if violated
+
+[Specific failure modes. "Silent data loss", "lookup returns undefined", "pipeline hangs", etc.]
+
+### Checklist (if applicable)
+
+[Step-by-step list of files to touch when extending this contract. Mark which steps cause silent failures if skipped.]
+
+---
+
+## N. [Next Contract]
+
+...
+
+---
+
+## Reference: [Shapes / Enums / Defaults]
+
+[Put stable reference material (store shapes, entity defaults, API envelopes) at the bottom. These support the guardrails above but aren't guardrails themselves.]
+```
+
+---
+
+## 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
+---
+```
+
+```
+# {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 `introspect` skill parses the **Proposed Changes** sections to check guardrail 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 guardrails (from `docs/operations/guardrails.md`) this plan touches by name
+- "None" is a valid answer and means introspect 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.