@nurix/etna 0.18.15 → 0.18.17

package/data/harnesses/mobile/CLAUDE.md

@@ -1,19 +1,17 @@
 # Agent Instructions
 
-This file defines how AI agents (Claude, GPT, etc.) should work on this project. **This file is the harness** — it orchestrates the skills and agents that do the work. There is no separate "harness skill."
+This file defines how AI coding agents — any vendor, any runtime — should work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if your runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a default your runtime may have built in — in a conflict, the rule here wins.
 
 ---
 
-## Bootstrap
+## Maintenance
 
-> A missing `docs/structure.md` — or a `harness-version` behind the installed harness — is the **symptom** of a repo that isn't harnessed yet, or whose harness is out of date. Don't reconcile it by hand. Drive the **reconcile chain** — you (the main session) own it, because `maintenance` is a sub-agent that can't run skills or spawn sub-agents:
->
-> 1. Invoke **`maintenance`** (`"baseline this repo"` / `"reconcile the harness"`). It auto-selects **baseline mode** from the missing/behind `harness-version`, reconciles `docs/`, stamps the version, then hands back.
-> 2. If it hands back with a follow-up (typically the module proposal), re-invoke it to finish.
->
-> Then continue. Each component's internals live in the component, not here.
+Invoke the `maintenance` agent whenever you judge the docs need it — not just at first setup. Standing triggers: a missing `docs/structure.md`, a `harness-version` marker behind the installed version, docs contradicting code, unowned source paths, or drift you notice while working. Don't reconcile any of these by hand:
 
-This is the only step that runs **before** the harness exists; everything below assumes a reconciled repo.
+1. Invoke `maintenance` ("baseline this repo" / "reconcile the harness" / "docs health"). It auto-selects its mode — baseline when the version marker is missing or behind, coherence audit otherwise — then hands back.
+2. If it hands back with a follow-up (typically the module proposal), re-invoke it to finish.
+
+A repo with no `docs/structure.md` isn't reconciled yet — run the baseline before applying anything below. Runtimes without sub-agent dispatch: read `.claude/agents/maintenance.md` and execute its procedure inline. Each component's internals live in the component, not here.
 
 ---
 
@@ -21,14 +19,14 @@ This is the only step that runs **before** the harness exists; everything below
 
 - Read **[`docs/structure.md`](docs/structure.md)** for the documentation map and folder authority (architecture, features, operations)
 - Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
-- Ignore **[`README.md`](README.md)** – it's for human reference only
+- Prefer `docs/` over `README.md` — docs/ is canonical for agents; check the README only when docs/ lacks a setup detail
 - Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
 
 ---
 
 ## Mobile (React Native + Expo)
 
-This is the **mobile** harness — `code`'s governance plus RN + Expo conventions. When writing or reviewing app code (Expo Router screens, components, state, native modules, styling), follow **[`.claude/rules/react-native.md`](.claude/rules/react-native.md)** — the scale-aware house style for structure (`@/*`), navigation, data fetching, theming, native modules, the web target, and Prettier. The workspace rules (`general`, `nomenclature`, `typescript`) still apply.
+This is the **mobile** harness — `code`'s governance plus RN + Expo conventions. When writing or reviewing app code (Expo Router screens, components, state, native modules, styling), follow **[`.claude/rules/react-native.md`](.claude/rules/react-native.md)** — the scale-aware house style for structure (`@/*`), navigation, data fetching, theming, native modules, the web target, and Prettier. The workspace rules (`general`, `nomenclature`, `typescript`, `testing`) still apply.
 
 ---
 
@@ -38,38 +36,69 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 | Mode | Enter when | Implemented by | Exits to |
 | --- | --- | --- | --- |
-| **Brainstorming** | explicit ask; or a user utterance challenges a loaded pillar headline → name the brushed principle and offer `/brainstorm start` (no auto-entry) | `brainstorm` agent + skill | Spec, Plan, or close + harvest |
-| **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
-| **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
+| **Brainstorming** | explicit ask (`/brainstorm start`); or the user brings a large piece of work — a new system, a feature with many unknowns — most users don't know this mode exists, so recommend it: name what makes the work big and offer a session; or a user utterance contradicts a recorded design principle (a pillar) → name the principle and offer a session. Never auto-enter. | `brainstorm` agent + skill | LLD, Plan, or close + harvest |
+| **LLD** (low-level design) | new feature work | `lld-mode` agent + `documentation` skill | Plan |
+| **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
+
+> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: kept records live under `docs/brainstorm/`, harvested doctrine under `docs/architecture/`. Runtimes without slash commands: read `.claude/skills/brainstorm/SKILL.md` and follow it inline. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
+
+**On Plan Completion:**
+
+1. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
+2. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
+3. The `boundary` skill must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
 
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `status: active`, extending it with how-it-works sections and confirming its `owns:` globs against the actual code; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); a brainstorm session is written to a **kept** record at `docs/brainstorm/{topic}/` (committed, one subfolder per topic), and on close harvest distils its conclusions by scope — doctrine, glossary, non-goals, and information-architecture changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md` — leaving the `docs/brainstorm/{topic}/` record in place as the provenance. Open questions block close.
+**On Brainstorm Close** (a separate procedure — when a brainstorm session ends, not when a plan completes):
+
+- The session record lives at `docs/brainstorm/{topic}/` (committed, one subfolder per topic) and stays in place as provenance.
+- Harvest conclusions by scope: doctrine, glossary, non-goals, information-architecture changes → `docs/architecture/`; decisions → `docs/architecture/adr/`; backlog items → `docs/history/backlog.md`.
+- Open questions block close.
 
 ---
 
-## Context Routing
+## Ownership, Boundaries & Documentation
+
+These three mechanisms work in tandem to keep the repo self-updating and to prevent half-finished changes: **ownership** routes you to the canonical doc before you touch code, the **boundary** check reads both sides of every contract your change participates in so you can't ship one side of it, and **documentation** updates close the loop so the next session inherits the truth. Skipping any leg breaks the other two.
+
+### Ownership — route before you edit
+
+Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
 
 Before modifying code in an unfamiliar area:
 
-1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning feature doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — see Bootstrap.)
-2. If `qmd` is installed, run `qmd query --format json -c <collection> "<topic>"` (repeat `-c` to span this repo's collections; `qmd collection list` names them) for semantic recall over the indexed docs — prefer it when entering an unfamiliar area; absent ⇒ skip.
-3. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
-4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes.
+1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map. Match your path or topic (its `keywords:`) to the owning feature doc and read it before changes. (If no index appears in your context: either the repo isn't reconciled — see Maintenance — or your runtime doesn't inject context at session start; then derive it by scanning the `owns:` frontmatter of every doc in `docs/features/`.)
+2. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes.
+
+The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the LLD before proceeding.
+
+### Boundaries — check while you change
+
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them — the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script reads. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source on every run (its `references/mechanisms.md` defines the failure mechanisms; the technology packs under `references/packs/` carry stack specifics), so nothing is persisted that could go stale.
+
+**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source, traces the consumers on the other side, and reports severity-ranked violations with suggested amendments and a pass/block verdict — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code (db schema, wire envelopes, auth, events, env/config), run the same diagnostic scoped to the diff.
+
+### Documentation — close the loop
+
+- **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if your runtime defaults to never creating documentation files unprompted.
+- After plan completion **[override]**: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` — no confirmation needed. Include `Commits:` if multi-commit. Non-plan changes (refactors, fixes, API changes): prompt first.
+- When you move or rename source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
+- `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
-For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
+> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here. Runtimes that can't invoke them natively: read the component file — `.claude/agents/<name>.md`; for skills, `.claude/skills/<name>/SKILL.md` plus any `references/` it points to — and follow it inline.
 
 ---
 
 ## Project Memory
 
-Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
+Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in the runtime's user-level memory store, if it has one (untracked; paths in Runtime Notes).
 
 | File | Owner | Contents |
 | --- | --- | --- |
 | `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
 | `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
-| `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
+| Runtime user-level memory (paths in Runtime Notes) | The runtime's auto-memory system | User preferences, role, communication style, cross-project habits |
 
-**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: _is this true of this project, or true of this user?_ Project facts → `docs/memory/`. User facts → `~/.claude/`.
+If your runtime records memories automatically, override its default location for project-relevant facts. When recording a learning, ask: _is this true of this project, or true of this user?_ Project facts → `docs/memory/`. User facts → the runtime's user-level store. Runtimes without auto-memory: apply the same test when deciding where to write a learning.
 
 `docs/memory/main.md` is created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
 
@@ -85,44 +114,38 @@ When implementing a plan, if you discover work that is important but outside the
 
 ---
 
-## Doc Ownership
-
-Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. A living doc may additionally carry an optional `anchors:` block (a qmd drift tripwire, not ownership).
-
-The spec-mode agent checks for ownership conflicts during research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the spec before proceeding.
-
----
-
-## Boundaries
-
-A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
-
-**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
-
-> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
-
----
-
-## Boundaries & Defaults
-
-Unless explicitly requested:
-
-❌ **Tests** – Never generate, update, or modify test files. ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies. ❌ **Compatibility** – Never maintain backward compatibility unless specified. ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks. ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself. ✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session. ✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches. ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior. ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one. ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
+## Guardrails & Defaults
+
+Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
+
+- ✅ **Tests — suite-first.** Tests ship with every change to product code or behavior, built as one maintained suite, never as one-off scripts:
+  - **Location**: all tests live in the repo's canonical test tree — `tests/`, or the framework convention the repo already uses (detect, don't invent). Mirror the source structure: `src/modules/auth/session.ts` → `tests/modules/auth/session.test.ts`. Never create test files at the repo root or scattered next to scratch scripts.
+  - **One framework — never chosen ad hoc**: use the runner the repo already has (detect from its config); if the repo has none, use the stack's framework named in the testing rule (`.claude/rules/testing.md`) and wire it up as the repo's canonical test command before writing the first test. Never introduce a second framework beside an existing one.
+  - **Shared plumbing**: fixtures, factories, and helpers live in `tests/helpers/` (or the suite's existing shared location) and are reused; duplicated setup across test files is a defect to refactor, not a pattern to follow.
+  - **What gets tests**: a new feature ships with tests for the behavior its LLD promises; a bug fix ships with a regression test that fails before the fix and passes after.
+  - **Discipline**: run the affected part of the suite before declaring work complete and report results honestly. When an LLD or plan intentionally changes behavior, updating the affected tests to the new contract is part of the change — the ban is on weakening, skipping, or deleting a test to mask a failure you can't explain.
+  - **Throwaway checks are not tests**: temporary verification scripts go to scratch space and are deleted, never committed into the test tree.
+- ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
+- ❌ **Compatibility** – Never maintain backward compatibility unless specified.
+- ❌ **Branches & Worktrees [override]** – Never self-create git branches or worktrees; commit straight to the checked-out branch. This deliberately replaces any built-in "branch first when on the default branch" default — do not branch unless the user asks. Exception: when the user asks for a pull request, creating the branch the PR requires counts as being asked — create that branch **before** committing the PR's changes.
+- ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
+- ✅ **Browser Automation** – If your runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or you are an agent that can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
+- ✅ **Delegate at scale** – If your runtime supports sub-agent dispatch: offload large, independent, or parallelizable work (broad research, audits, multi-file implementation) to sub-agents; keep small, well-understood edits in the main session — a dispatch whose context hand-off costs more than the work itself is waste. Dispatch prompts must be self-contained (the sub-agent sees none of your conversation); parallelize independent dispatches. Let dispatches inherit the session's model unless your runtime supports tier selection and the task clearly wants one — a stronger tier for judgment-heavy work, a cheaper tier for mechanical fan-out (concrete tier names live in Runtime Notes, never in rules). No dispatch mechanism ⇒ do the work inline yourself.
+- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
+- ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
 
 ---
 
 ## File Structure
 
-- Add file path at top of each file: `// src/modules/example.js - Module for handling user authentication`
-- Add a 1-line function description as a comment above each function: `// Extract JWT token from request based on endpoint type`
+- Add a file-path header comment at the top of each source file, in the file's native comment syntax — `// src/modules/example.js - Module for handling user authentication` (JS/TS), `# scripts/sync_users.py - …` (Python/shell/YAML), `-- db/seed/init.sql - …` (SQL). Place it below any shebang line; skip formats with no comment syntax (JSON, lockfiles) and generated files.
+- Add a 1-line description above each function whose purpose isn't fully evident from its name and signature: `// Extract JWT token from request based on endpoint type`. A comment that restates the name is noise. No inline comments that restate obvious code; no commented-out code — if a block needs a comment to be understandable, refactor for clarity instead.
 
 ---
 
-## Documentation
-
-`docs/structure.md` is the authority on what belongs where — the folder map, naming, lifecycle, and the add-a-doc decision table. Read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
+## Runtime Notes
 
-Maintenance triggers (act on these without re-reading `structure.md`):
+Everything above is runtime-neutral. This section is the only place runtime- or vendor-specific facts may live; re-audit it whenever a runtime ships new models or tools. Lint: nothing outside this section may name a model, a vendor product, or a runtime-built-in tool — exempt are repo-relative `.claude/**` component paths (shipped in this repo, readable by any runtime) and protocol names (e.g. MCP).
 
-- After plan completion: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` (no confirmation; include `Commits:` if multi-commit). Non-plan changes (refactors, fixes, API changes): prompt first.
-- When you move or rename source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
+- **Claude Code**: sub-agent dispatch is the Agent tool; sub-agents cannot run skills, spawn sub-agents, or reliably hold the browser connection (the "can't hold the browser connection" condition the Browser Automation guardrail refers to) — browser work is Chrome CDP ("Claude in Chrome"), main session only. The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). If pinning dispatch tiers: strong tier (opus-class) for judgment-heavy work, fast tier (sonnet-class) for mechanical fan-out — tier names go stale, re-check on model releases.
+- **Runtimes without native component support** (AGENTS.md readers, etc.): read `.claude/agents/<name>.md` and each skill's `.claude/skills/<name>/SKILL.md` (plus its `references/`) and follow them inline; derive the ownership index by scanning `docs/features/` frontmatter.

package/data/harnesses/mobile/agents/{spec-mode.md → lld-mode.md}

@@ -1,33 +1,33 @@
 ---
-name: spec-mode
-description: Specification researcher for Feature and Product workflows. Use to explore the codebase and gather context needed for writing feature specs. Returns research findings — does not write files.
+name: lld-mode
+description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
 model: inherit
 skills:
   - documentation
 ---
 
-# Spec Mode Agent
+# LLD Mode Agent
 
-You are a specification researcher. Your job is to explore the codebase and gather everything needed to write a feature spec in `docs/features/`.
+You are an LLD researcher. Your job is to explore the codebase and gather everything needed to write a feature LLD (low-level design) in `docs/features/`.
 
-You do NOT write the spec — you return structured research that the main agent uses to write it.
+You do NOT write the LLD — you return structured research that the main agent uses to write it.
 
 ## Before Starting
 
 First, understand the documentation landscape:
 
 1. Read `./docs/structure.md` to understand the documentation structure
-2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
-3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
-4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
+2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
+3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
+4. Read 1-2 existing feature LLDs in `./docs/features/` to calibrate format and depth
 5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
-This tells you what already exists, what's adjacent, how detailed the spec should be, and what code paths are already owned.
+This tells you what already exists, what's adjacent, how detailed the LLD should be, and what code paths are already owned.
 
 ## What You Research
 
-1. **Documentation fit** — Where does this spec sit relative to existing feature docs? Does it extend an existing spec or need a new one?
+1. **Documentation fit** — Where does this LLD sit relative to existing feature docs? Does it extend an existing one or need a new doc?
 2. **Existing patterns** — Find related features, similar implementations, and conventions in the codebase
 3. **Affected modules** — Identify what files, routes, components, and data flows are relevant
 4. **Current state** — Understand how the system works today in the area being specified
@@ -38,13 +38,13 @@ This tells you what already exists, what's adjacent, how detailed the spec shoul
 
 Structure your findings as:
 
-- **Documentation context**: Existing specs that relate, whether to create new or update existing, suggested filename
+- **Documentation context**: Existing feature LLDs that relate, whether to create new or update existing, suggested filename
 - **Related patterns**: What similar things exist in the codebase and where
 - **Affected modules**: Files, routes, components that will be involved
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
-- **Risks or concerns**: Anything the spec should address or call out
+- **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.
 

package/data/harnesses/mobile/agents/maintenance.md

@@ -80,6 +80,8 @@ For each changed file:
 - If no glob matches → flag as **unowned**.
 - If an owner exists → compare last-modified dates (`git log -1 --format="%ci" -- <path>`), flag docs where code changed more recently (14-day threshold).
 
+**Audit priority.** Rank the docs to inspect by their `last-reviewed:` frontmatter (optional key): never-stamped first, then oldest-first. A doc reviewed last week rarely needs a re-read; one never stamped is the likeliest to have drifted.
+
 ### Step 4: Check architecture & backlog
 
 **Unowned paths.** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across the `owns:` globs; do not assume `src/`) against the `owns:` map. Report directories no `owns:` glob covers.
@@ -97,6 +99,8 @@ For each stale doc:
 - If drift is clear (renamed function, new export, changed props) → update the doc directly.
 - If drift is ambiguous (major refactor, unclear intent) → backlog it.
 
+For each feature doc you verified accurate or updated this pass, stamp `last-reviewed:` in its frontmatter with today's date (add the key if absent). Never write review dates into the body — it's frontmatter metadata only.
+
 For unowned code paths:
 
 - Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).
@@ -108,20 +112,6 @@ For unowned code paths:
 1. Update `docs/structure.md` Health Log with today's date and summary.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
-4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence _is_ the dedupe, so never backlog it.
-5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance ∩ the doc's `owns:` globs strong, entities ∩ declared ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence _is_ the dedupe, so never backlog the proposal.
-
-### Step 7: Refresh index (optional, skip-if-absent)
-
-If the `qmd` binary is available (`command -v qmd`), re-run `qmd embed -c <collection>` once per `{repo}-*` collection (`{repo}` = the repo's directory name; `qmd collection list` shows the registered set — skip any absent) so the local docs index reflects the files this pass touched. Scope every run with `-c` — the qmd index is global (`~/.cache/qmd/` holds every repo's collections), so a bare `qmd embed` would re-embed unrelated repos' collections. If `qmd` is absent, skip silently — it's never required.
-
-### Step 8: Check anchor drift (optional, skip-if-absent)
-
-If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required. `anchors:` is a qmd-only tooling key; with no qmd it is inert.
-
-This catches **doc-area drift** — the subject the doc abstracts moving or vanishing from the indexed corpus. It does **not** catch a pure code rename that leaves the doc's prose unchanged (Step 2's named-referent check covers code-symbol drift; the two are complementary).
-
-Glob `docs/features/**/*.md`, `docs/architecture/**/*.md`, and `docs/operations/**/*.md` for docs carrying `anchors:` frontmatter. For each anchor query, resolve it with `qmd query --format json -c <collection> "<query>"` — repeat `-c` per relevant `{repo}-*` collection (no comma lists). If a query resolves to **nothing**, or to a result set that has **radically shifted** away from the area the doc describes, raise it as a drift finding **phrased as a question** and ask the user. On **yes**, dispatch the remediation sub-agent (the same yes-branch as Step 5). On **decline or no action**, append it to `docs/history/backlog.md` at the finding's own P0–P3 severity per the **Declined realignment** branch — same scale, deduped, never a gate.
 
 ---
 
@@ -148,7 +138,7 @@ docs/
 │   ├── changelog/         # Individual entries
 │   ├── plans/             # Implementation plans (Status field required)
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # inbox/ (captured-lessons queue), facts/ (distilled cards), index.md, main.md, {agent}.md
+├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
 └── tests/                 # Optional, author-maintained — create only if test docs exist
 ```
 
@@ -189,26 +179,11 @@ Scaffold missing mandated files **by calling the `documentation` skill for each
 
 - `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
-Scaffold `docs/memory/facts/` so the distilled tier has a home from day one: the `session-reflect` hook appends session lessons to the per-actor inbox at `docs/memory/inbox/{actor}.md` (not a scaffold — created mechanically on first reflection), and the `distiller` digests that queue down into fact-cards under `docs/memory/facts/`, consuming the entries it digests.
-
 ### Step B4 — Stamp the version
 
 Write `harness-version: <installed version>` (the semver from `.claude/harness.json`) into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker (no `epoch`, no `docs/memory/index.md` "is-baselined" check).
 
-### Step B5 — Register the qmd retrieval lens (optional, skip-if-absent)
-
-Strictly optional and guarded on the binary — if `command -v qmd` finds nothing, **skip this entire step silently** (no error, no behavior change) and carry one advisory line into the hand-back: _"qmd not installed — semantic retrieval unavailable; the generated ownership index + `keywords:` discovery are active."_ The index is a **local rebuildable lens** — data stays in git; never commit index artifacts, and never use `qmd init` (the default global index keeps the repo clean).
-
-If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd hard-codes the `**/*.md` pattern and has no exclude flag, so a `docs/`-root collection would sweep the consumable inbox queue at `docs/memory/inbox/` into the index (the inbox's entries are deleted on digestion, leaving dangling index entries). Register **per indexable subtree** (skip absent ones; `{repo}` = the repo's directory name; an existing name/path no-ops — treat as success):
-
-- `qmd collection add docs/features --name {repo}-features`
-- `qmd collection add docs/architecture --name {repo}-architecture`
-- `qmd collection add docs/operations --name {repo}-operations`
-- `qmd collection add docs/memory/facts --name {repo}-facts` (never `docs/memory` as a whole)
-
-Then `qmd context add` per registered collection and `qmd embed -c <name>` per collection (always scope with `-c`; a bare `qmd embed` re-embeds every repo's collections). This augments discovery; it never supersedes the `owns:`-glob ownership resolution.
-
-### Step B6 — Module proposal
+### Step B5 — Module proposal
 
 Modules are **labels, declared, never inferred from physical layout**. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` already names.
 

package/data/harnesses/mobile/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "mobile",
   "name": "mobile",
-  "version": "1.0.3",
+  "version": "1.1.2",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "3266253aa63b"
+  "digest": "bc67c99bb1c5"
 }

package/data/harnesses/mobile/hooks/hooks.json

@@ -11,29 +11,6 @@
           }
         ]
       }
-    ],
-    "SessionEnd": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-reflect.mjs\"",
-            "async": true
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-recall.mjs\""
-          }
-        ]
-      }
     ]
   }
 }

package/data/harnesses/mobile/rules/testing.md

@@ -0,0 +1,25 @@
+# Testing
+
+Framework choice is never ad hoc and never the user's problem mid-task: detect the stack, use its row. If the repo already has a runner, that runner wins — never introduce a second framework beside it.
+
+## Frameworks by stack
+
+No alternatives. Just use these.
+
+| Stack | Unit / integration | Component | E2E | HTTP mocking | Don't use |
+| --- | --- | --- | --- | --- | --- |
+| Node + Vite / React (web) | vitest | @testing-library/react (+ @testing-library/user-event, happy-dom) | @playwright/test | msw | jest, mocha, jasmine, cypress, enzyme |
+| Express APIs | vitest | — | supertest against the app instance | msw (outbound calls) | jest, chai-http |
+| React Native / Expo | jest via the jest-expo preset | @testing-library/react-native | maestro | msw | detox, enzyme |
+| Cloudflare Workers | vitest + @cloudflare/vitest-pool-workers | — | @playwright/test against `wrangler dev` | msw | jest |
+| Rust | `cargo test` (built-in) | — | — | — | — |
+
+All npm packages at `latest`. Fake data comes from `@ngneat/falso` (the repo standard — never faker/chance).
+
+## Conventions
+
+- **Suite, not scripts.** Tests live in the canonical test tree (`tests/`, mirroring `src/`), named `<subject>.test.ts`. Shared fixtures, factories, and helpers live in `tests/helpers/`. The harness `CLAUDE.md` Tests guardrail carries the full suite-first policy; this rule owns only the technology choices.
+- **Wire the canonical command.** `"test"` in package.json runs the whole unit suite (`vitest run`); e2e runs under `"test:e2e"`. A repo where `pnpm test`/`npm test` doesn't run the suite is misconfigured.
+- **Unit and E2E trees stay separate.** Vitest/Jest suites in `tests/`; Playwright/Maestro suites in `e2e/` with their own config — never mixed into the unit runner's glob.
+- **No test doubles for what you own.** Prefer real instances — in-memory SQLite for drizzle, the actual Express app via supertest — over mocks; mock only true externals (network via msw, time via the runner's fake timers).
+- **Determinism.** No real network, no real time, no shared mutable state between tests; every test must pass alone and in any order.

package/data/harnesses/mobile/skills/brainstorm/SKILL.md

@@ -102,7 +102,7 @@ The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mi
 
 The background reconciler that replaces ceremony with consistency. **One sync in flight at a time; queue at most one behind it.**
 
-**When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent (read/write access to the session folder only). Exception at any complexity: the `stop` sync's self-containment pass always dispatches the context-free agent — an inline reader with full conversational context cannot cold-read, because it already knows every undefined term.
+**When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent **on Opus** (`model: "opus"` — pillar reconciliation is quality-critical, so never a smaller model; and never the main-loop frontier model, whose session budget belongs to the conversation), with read/write access to the session folder only. Exception at any complexity: the `stop` sync's self-containment pass always dispatches the context-free agent — an inline reader with full conversational context cannot cold-read, because it already knows every undefined term.
 
 **The filing checklist — before every dispatch.** The sync agent cannot see the conversation, so the orchestrator runs the transcript-side half itself, immediately before dispatching: list your substantive contributions since the last sync — analyses, diagnoses, recommendations with reasoning, definitions, rejections — and file any that aren't on disk (evidence note, decision rationale, glossary line, rejected entry). Only then dispatch. A sync dispatched over unfiled substance audits an incomplete record and stamps it green.
 

package/data/harnesses/mobile/skills/brainstorm/exit-artifacts.md

@@ -58,5 +58,5 @@ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}
 
 **Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
 conclusions, but the record stays committed as their provenance: a traceable source for every published
-headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the
-`distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
+headline, and the seed the next `/brainstorm start` on this topic resumes from. Retire a topic's folder
+by hand only when the design line is truly dead.

package/data/harnesses/mobile/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance), or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
 ---
 
 # Technical Documentation Skill
@@ -9,9 +9,11 @@ description: Template & generator library for technical docs — the skill agent
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
+**No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
+
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
-**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans, ADRs); `docs/memory/` is the agent's dated log and is likewise exempt. A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
+**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans); `docs/memory/` is the agent's dated log and is likewise exempt, and an ADR's **Decision Changelog** section is the one sanctioned dated-history section inside an active doc (the ADR body itself stays current-truth-only). A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
 
 ---
 
@@ -22,7 +24,7 @@ User request
     │
     ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
     │
-    ├─ "Document feature/module" ──────▶ Module Template
+    ├─ "Document feature/module (LLD)" ▶ Module Template
     │
     ├─ "Create/update changelog" ──────▶ Changelog Template
     │
@@ -34,6 +36,8 @@ User request
     │
     ├─ "Record architecture decision" ─▶ ADR Template
     │
+    ├─ "Document a procedure/setup" ───▶ Operations Procedure Template
+    │
     ├─ "Create/update root README" ────▶ Project Root README Template
     │
     ├─ "Create/update plan" ───────────▶ Plan Template
@@ -66,7 +70,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ### How to derive the frontmatter
 
-A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required).
+A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
 
 **1. `owns:`** (the path scope)
 
@@ -119,6 +123,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, protected files, ADR, project root README templates |
 | `references/style-guide.md` | Writing rules, formatting conventions |
 | `references/examples.md` | Good vs bad documentation examples |

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

@@ -105,7 +105,7 @@ Replaced change-tracking merge with version-based conflict resolution.
   - Purpose: Single-pass merge with change detection
   - Returns: `{ merged, changes }`
 
-### Modified
+### Changed
 
 - `useDataSync()` in `src/hooks/useDataSync.js`
   - Changed: Now compares versions before merge

package/data/harnesses/mobile/skills/documentation/references/style-guide.md

@@ -222,7 +222,7 @@ Use for structured info:
 
 ## Tense & History
 
-**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans, ADRs). (`docs/memory/` is the agent's own dated log and is likewise exempt from this rule.)
+**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans). Two sanctioned exceptions: `docs/memory/` is the agent's own dated log, and an ADR's **Decision Changelog** section carries that decision's dated revision history (the rest of the ADR body stays current-truth-only).
 
 Strip this language from active docs:
 
@@ -257,6 +257,8 @@ Rules:
 #### Detail (H4 - sparingly)
 ```
 
+**Headings are retrieval keys.** Search and agents retrieve sections out of context, and a bare `## State` reads identically across every feature doc. In long docs, qualify generic headings with the feature name — `## State — invoice-pdf`, `### Merge rules — data sync` — so a section stands alone when retrieved. Short docs whose H1 disambiguates can keep bare headings.
+
 ### Standard Layout
 
 ```markdown