@nurix/etna 0.19.19 → 0.19.21

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

@@ -0,0 +1,65 @@
+# docs/structure.md (Authority Map)
+
+Truth document. Use for: defining which folder owns which topic and how docs are maintained.
+
+```
+---
+harness-version: 1.0.0
+---
+
+# Documentation Structure
+
+> This file is the entry point for understanding the docs folder.
+> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
+
+## Authority Map
+
+Each topic has one canonical location. Read from here, not from plans or changelogs.
+
+| Topic | Authority | Key Files |
+| ----- | --------- | --------- |
+| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
+| System overview | `docs/architecture/` | system-design.md |
+| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
+| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
+| API surface | `docs/architecture/` | api.md |
+| Security | `docs/architecture/` | security.md |
+| Feature behavior | `docs/features/` | {key files} |
+| Setup & development | `docs/operations/` | {key files} |
+| Environment / config surface | `docs/operations/` | environment.md |
+| Testing strategy | `docs/tests/` | strategy.md |
+| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
+| Change records | `docs/history/changelog/` | Individual entries |
+| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
+| Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
+| Backlog | `docs/history/` | backlog.md |
+
+## The Two Natures
+
+Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
+
+- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
+- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
+- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
+
+## Folder Rules
+
+- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
+- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
+- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
+- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
+- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
+- `docs/history/changelog/`: Records. Append-only.
+- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
+- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
+- `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
+- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
+
+## Health Log
+
+<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
+| Date | Review Summary |
+| ---- | -------------- |
+| {today} | Initial baseline — v{harness-version} structure established |
+```

package/data/harnesses/code/skills/documentation/templates/system-overview.md

@@ -0,0 +1,32 @@
+# System Overview (docs/architecture/system-design.md)
+
+Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
+
+Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+
+```
+# System Overview
+
+## What this is
+
+{Two or three sentences: what the system does, for whom, in what environment it runs.}
+
+## Subsystem map
+
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Frontend │────▶│   API    │────▶│    DB    │
+└──────────┘     └──────────┘     └──────────┘
+{One box per subsystem; label the arrows with the contract that crosses them.}
+
+- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+
+## Key flows
+
+{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+
+## Where the truth lives
+
+| Area | Canonical doc |
+| ---- | ------------- |
+| {area} | [{doc}](path) |
+```

package/data/harnesses/code/skills/documentation/templates/testing-strategy.md

@@ -0,0 +1,29 @@
+# Testing Strategy (docs/tests/strategy.md)
+
+Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
+
+Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+
+```
+# Testing Strategy
+
+## Levels
+
+| Layer | Runner | Lives in | Covers |
+| ----- | ------ | -------- | ------ |
+| Unit / integration | {runner} | `tests/` | {what} |
+| E2E | {runner} | `e2e/` | {what} |
+
+## Running
+
+- `{pm} test` — the whole unit suite (CI gate)
+- `{pm} run test:e2e` — {when to run}
+
+## Deliberately untested
+
+- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
+
+## Adding a test
+
+1. {Where the file goes, what it's named, where fixtures live}
+```

package/data/harnesses/discover/.prettierignore

@@ -10,3 +10,9 @@ yarn.lock
 
 # Harness-managed agent/skill definitions (installed under .claude/)
 .claude
+
+# Source catalogs — authored markdown; prettier collapses template/example blocks
+skills
+rules
+agents
+harness

package/data/harnesses/discover/CLAUDE.md

@@ -4,6 +4,8 @@ This is the **policy** half of the `discover` harness. The plugin ships the capa
 
 A run is five modes, in order: **Discovery → Ingestion → Evaluation → Cartography → Self-correction.** The main session drives all five — Ingestion and Evaluation fan out parallel sub-agents (dispatch each via the Agent/Task tool with `model: opus`); Cartography re-enters the live product (the browser singleton) to walk + screenshot it and may fan out doc-drafting sub-agents; a sub-agent cannot spawn further sub-agents.
 
+**Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline. (Ingestion is the sanctioned application: each dimension is large and independent, so its collectors are fanned out deliberately, never by reflex.)
+
 ---
 
 ## Access is a capability vector (the front gate)
@@ -43,7 +45,7 @@ Agent name = dimension name. ⚠ = gated (needs user authorization before dispat
 - **It exists** → tooling was already reviewed here — skip straight to Mode 1. **Never re-prompt in the same folder.**
 - **It's absent** → run the one-time check:
   1. Read [`tooling-recommendations.md`](tooling-recommendations.md) (beside this file at the project root) — the Tier 1 (clean) and Tier 2 (gated) tool lists + the AVOID list.
-  2. **Validate what's already installed before recommending anything** — `command -v <tool>` per recommended tool (`npm ls -g <pkg>` for the Node libraries that ship no binary, e.g. `chrome-remote-interface`). Detection only — install nothing yourself.
+  2. **Validate what's already installed before recommending anything** — `command -v <tool>` per recommended tool (`npm ls -g <pkg>` for the Node libraries that ship no binary, e.g. `chrome-remote-interface`). Detection only — nothing is installed at this step.
   3. **Recommend only the missing tools**, grouped **clean** (safe to install freely — offer the Tier-1 one-paste block) vs **gated** (first-party / user-owned / opt-in — surface the command but **never run it for the user**; these need the user in the loop). Never suggest anything on the AVOID list. If nothing is missing, say so in one line.
   4. **Write `.claude/discover-tooling.json`** so the harness never asks again in this folder:
      ```json
@@ -130,16 +132,15 @@ For spec-writing, integration planning, and competitive analysis — **not** cre
 
 Output lives under the **resolved corpus root** (default `research/`; chosen per Mode 1 step 0):
 
-```
-<corpus>/<target>/                  ← default corpus root: research/
-├── 00-scope-verdict.md            ← Discovery: accept/narrow/redirect/refuse
-├── 00-recon-plan.md               ← Discovery: access_grade + scope + dimension plan
-├── dimensions/<dim>/{_summary.md, raw/}   ← Ingestion (session & wire-capture also: captures/, curls.md)
-├── dimensions/session/captures/screens/   ← Cartography: redacted per-surface screenshots (+ _index.md)
-├── evaluation/{technology-architecture, product-features, data-model-api-surface, competitive-positioning}.md   ← Evaluation
-├── evaluation/{information-architecture, ux-flows, feature-coverage}.md   ← Cartography (Mode 4)
-├── README.md                      ← Evaluation: run story + headline findings
-└── 05-self-correction-proposal.md ← Self-correction (Mode 5): proposed harness fixes (approval-gated)
-```
+| Artifact (under `<corpus>/<target>/`) | Written by | Contents |
+| --- | --- | --- |
+| `00-scope-verdict.md` | Discovery | accept / narrow / redirect / refuse |
+| `00-recon-plan.md` | Discovery | `access_grade` + scope + dimension plan |
+| `dimensions/<dim>/{_summary.md, raw/}` | Ingestion | per-dimension collection (`session` & `wire-capture` also: `captures/`, `curls.md`) |
+| `dimensions/session/captures/screens/` | Cartography | redacted per-surface screenshots (+ `_index.md`) |
+| `evaluation/{technology-architecture, product-features, data-model-api-surface, competitive-positioning}.md` | Evaluation | the four rollups |
+| `evaluation/{information-architecture, ux-flows, feature-coverage}.md` | Cartography (Mode 4) | the three cartography artifacts |
+| `README.md` | Evaluation | run story + headline findings |
+| `05-self-correction-proposal.md` | Self-correction (Mode 5) | proposed harness fixes (approval-gated) |
 
 Cloned repos live in `source/<target>/`. Provenance is the "self-aware" layer: each collector records _how_ it was obtained; Evaluation weights claims by it. Detailed shapes live in the rules.

package/data/harnesses/discover/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "discover",
   "name": "discover",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json",
     "tooling-recommendations.md"
   ],
-  "digest": "4e7fa848fe93"
+  "digest": "3b747e869c3a"
 }

package/data/harnesses/discover/tooling-recommendations.md

@@ -1,13 +1,13 @@
 # Tooling recommendations — what to install to improve capture & synthesis
 
-> The `discover` harness reads this file on **first run** (Step 0 in [`CLAUDE.md`](CLAUDE.md)): it detects which of these tools are already on the host, recommends only the **missing** ones (the gated ones only with you in the loop), and records the result in `.claude/discover-tooling.json` so it never re-prompts in this folder. Nothing here is installed automatically — the harness recommends, you decide.
+> The `discover` harness reads this file on **first run** (Step 0 in [`CLAUDE.md`](CLAUDE.md)): it detects which of these tools are already on the host, recommends only the **missing** ones (the gated ones only with the user in the loop), and records the result in `.claude/discover-tooling.json` so it never re-prompts in this folder. Nothing here is installed automatically — the harness recommends, the user decides.
 
 The host almost always arrives strong on languages and package managers (node, pnpm, python, uv, cargo, gh, jq, ripgrep) but **bare on capture/analysis tooling** — the tools below are what turn a shallow capture into a deep one.
 
 ## How to read this
 
 - **clean** — passive / local-only; always in-bounds. Install freely.
-- **gated** — fine, but only **first-party / user-owned / opt-in** (you install the CA, you route _your own_ client, you own the keys). mitmproxy, websocat, CDP, subfinder/tlsx, frida-on-your-own-device.
+- **gated** — fine, but only **first-party / user-owned / opt-in** (the user installs the CA, routes _their own_ client, owns the keys). mitmproxy, websocat, CDP, subfinder/tlsx, frida on the user's own device.
 - **avoid** — crosses the harness bright line (active scanning / exploitation / third-party packet capture). Listed so they're _not_ added by reflex.
 
 The harness is for **spec-writing / integration / competitive analysis** — passive or first-party only, respect TOS/robots. No tool below changes that; the gated ones just need the user in the loop.
@@ -27,7 +27,7 @@ cargo install htmlq
 uv tool install trafilatura && uv tool install griffe
 # Node global (JS/TS surface + bundle de-obfuscation + spec lint)
 npm i -g webcrack source-map-explorer @arethetypeswrong/cli publint @electron/asar typescript @stoplight/spectral-cli
-# Headless browser for JS-rendered docs/marketing (clean — your own headless instance)
+# Headless browser for JS-rendered docs/marketing (clean — the user's own headless instance)
 npm i -g playwright && npx playwright install chromium
 ```
 
@@ -53,26 +53,26 @@ npm i -g playwright && npx playwright install chromium
 
 ## Tier 2 — install when a run needs them (gated: first-party / passive-care)
 
-The capture lanes. In-bounds **only** for your own session / first-party clients / passive sources.
+The capture lanes. In-bounds **only** for the user's own session / first-party clients / passive sources.
 
 ```bash
 brew install mitmproxy websocat grpcurl subfinder tlsx testssl jadx apktool
 npm i -g chrome-remote-interface get-graphql-schema
-# one-time, user-run: expose a CDP port on your own Chrome (closes the WS-frame blind spot)
+# one-time, user-run: expose a CDP port on the user's own Chrome (closes the WS-frame blind spot)
 #   open -na "Google Chrome" --args --remote-debugging-port=9222
-# mobile-only, your own device + opt-in:  uv tool install frida-tools
+# mobile-only, the user's own device + opt-in:  uv tool install frida-tools
 ```
 
 | Tool | Unlocks | Ethics note |
 | --- | --- | --- |
 | **mitmproxy** | decode full HTTPS + WebSocket flows of any **first-party** client (CLI/desktop/mobile/SDK) — wire-capture rung 3 keystone | user installs CA + routes _their own_ client only |
-| **chrome-remote-interface** | raw CDP client → `Network.webSocketFrameReceived`/`Created`, SSE, full bodies — **captures the on-load WS frames the browser MCP's HTTP-only `read_network_requests` drops** | your own logged-in session |
+| **chrome-remote-interface** | raw CDP client → `Network.webSocketFrameReceived`/`Created`, SSE, full bodies — **captures the on-load WS frames the browser MCP's HTTP-only `read_network_requests` drops** | the user's own logged-in session |
 | **websocat** | curl-for-WebSockets: connect/frame/replay/hexdump a realtime endpoint outside the browser | first-party endpoint |
 | **grpcurl** | list services + invoke RPCs via gRPC server reflection → readable op/message catalog | first-party endpoint |
 | **get-graphql-schema** | introspect a first-party GraphQL endpoint → full SDL | first-party endpoint |
 | **subfinder / tlsx / testssl.sh** | passive CT/DNS subdomain breadth + structured TLS posture (vs hand-rolled crt.sh + openssl text) | passive aggregation; respect rate limits |
 | **jadx / apktool** | decompile Android `.apk`/`.dex` → Java + decode `AndroidManifest`/resources (capability map) | public binary, read EULA |
-| **frida-tools** | cert-pinning bypass to capture **your own** mobile client's wire | your own device + opt-in only |
+| **frida-tools** | cert-pinning bypass to capture **the user's own** mobile client's wire | the user's own device + opt-in only |
 
 **The single biggest unlock** for realtime targets: `chrome-remote-interface` + a Chrome `--remote-debugging-port` + `websocat` + `mitmproxy` together give `session`/`wire-capture` a real WebSocket/SSE capture path, instead of a client-side-remount workaround. The browser-MCP `read_network_requests` is HTTP-only — that's _why_ a realtime tap comes back empty until the remount trick.
 
@@ -86,7 +86,7 @@ Out-of-bounds for a spec-writing/competitive-analysis harness — listed so they
 - **`nuclei`** — template-based remote vuln scanning.
 - **`sqlmap`** — injection/exploitation.
 - **`amass` (active mode)** — active DNS brute-forcing (its _passive_ mode overlaps subfinder; prefer subfinder).
-- **third-party `mitmproxy`, `frida` on devices you don't own, `socat` as a public relay** — third-party traffic interception is the line this harness will not cross.
+- **third-party `mitmproxy`, `frida` on devices the user doesn't own, `socat` as a public relay** — third-party traffic interception is the line this harness will not cross.
 
 These stay absent by design; the recon ethics depend on it.
 
@@ -116,4 +116,4 @@ These stay absent by design; the recon ethics depend on it.
 - **`webcrack` needs Node 22.** Its hard dependency `isolated-vm` is a native (node-gyp) addon that fails to build against Node 26 (and `--omit=optional` doesn't help — the dep is non-optional). If it won't install, run it under a Node 22 LTS shim (`npx -y webcrack@latest …` in a Node-22 env), or lean on the already-clean `source-map-explorer` (the preferred `source-map-reassembly` path whenever the SPA ships `.map` files) + `ast-grep`. De-obfuscation of a _no-maps, minified_ bundle is the only gap this leaves.
 - **`chrome-remote-interface` is a library, not a CLI** — it installs as a Node module and is invoked from a script, not a shell binary. Detect it with `npm ls -g chrome-remote-interface`, not `command -v`.
 - **`pipx` is typically absent; use `uv tool install`** for Python CLIs (uv is present) — simpler than adding pipx.
-- **`playwright` is clean** (your own headless instance) and unblocks JS-rendered docs/marketing for `docs`+`website` without contending for the gated `session` Chrome.
+- **`playwright` is clean** (the user's own headless instance) and unblocks JS-rendered docs/marketing for `docs`+`website` without contending for the gated `session` Chrome.

package/data/harnesses/discussion/.prettierignore

@@ -10,3 +10,9 @@ yarn.lock
 
 # Harness-managed agent/skill definitions (installed under .claude/)
 .claude
+
+# Source catalogs — authored markdown; prettier collapses template/example blocks
+skills
+rules
+agents
+harness

package/data/harnesses/discussion/CLAUDE.md

@@ -19,3 +19,7 @@ Strictly separated — never mix them:
 **The operator layer**: `metadata/lessons/` — read `DIGEST.md` at session start alongside the routing files; it is **prior, not canon** (its reading-protocol block governs). Everything else under `lessons/` (append-only `log/`, `forecasts.md`) loads on demand only. The `lessons-maintenance` agent (instruction set: `metadata/lessons/distillation.md`) runs **only during user sessions** — spawn it in the background when the `metadata/ops/` cursor falls a session behind.
 
 The rules are the method — portable, abstract, generic examples; nothing depends on any local topic. Live exemplars are reached through `metadata/TOPICS.md`. Workspace-local method notes go to `metadata/method-changelog.md`; the harness itself is versioned by `.claude/harness.json` and documented in the etna forge (`docs/architecture/harness/discussion/`).
+
+## Fan-out
+
+**Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline.

package/data/harnesses/discussion/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "discussion",
   "name": "discussion",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "51812973828b"
+  "digest": "fa5d8b4fa816"
 }

package/data/harnesses/etna/.prettierignore

@@ -10,3 +10,9 @@ yarn.lock
 
 # Harness-managed agent/skill definitions (installed under .claude/)
 .claude
+
+# Source catalogs — authored markdown; prettier collapses template/example blocks
+skills
+rules
+agents
+harness

package/data/harnesses/etna/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Instructions
 
-This repo is **etna — the forge** where every Nurix harness is authored: skills, agents, rules, and harness definitions, composed into plugins and shipped to consumer repos by the `@nurix/etna` CLI. Working here means editing **authoring artifacts** — almost all markdown, plus the CLI and hook scripts (ESM JS) — not application source. etna has no `src/` app, no database, and no runtime API of its own; the code-project scaffolding you may expect (schema, wire contracts, a test suite) mostly doesn't apply, and where a rule below would in a normal repo, it's reframed for the forge.
+This repo is **etna — the forge** where every Nurix harness is authored: skills, agents, rules, and harness definitions, composed into plugins and shipped to consumer repos by the `@nurix/etna` CLI. Working here means editing **authoring artifacts** — almost all markdown, plus the CLI and hook scripts (ESM JS) — not application source. etna has no `src/` app, no database, and no runtime API of its own; the usual code-project scaffolding (schema, wire contracts, a test suite) mostly doesn't apply, and where a rule below would in a normal repo, it's reframed for the forge.
 
 etna governs itself with the **`etna`** harness — deliberately forked from the **`code`** harness it ships, so a capability added to `code` (a new mode, a new agent) never silently lands in the forge's own governance. Rules marked **[override]** deliberately replace a Claude Code default; the rule here wins.
 
@@ -8,7 +8,7 @@ etna governs itself with the **`etna`** harness — deliberately forked from the
 
 ## Maintenance
 
-Invoke the `maintenance` agent whenever you judge the docs need it — not just at first setup: a `harness-version` marker behind the installed version, docs contradicting the components they describe, unowned source paths, or drift you notice while working. Never reconcile these by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Each component's internals live in the component, not here.
+Invoke the `maintenance` agent whenever the docs look like they need it — not just at first setup: a missing `docs/structure.md` (the repo isn't reconciled — baseline before applying anything below), a `harness-version` marker behind the installed version, docs contradicting the components they describe, unowned source paths, or drift noticed while working. Never reconcile these by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Each component's internals live in the component, not here.
 
 ---
 
@@ -23,7 +23,7 @@ Invoke the `maintenance` agent whenever you judge the docs need it — not just
 
 ## Authoring & Distribution
 
-etna authors the components it also runs and ships, so **three copies of every component exist** — know which you are editing:
+etna authors the components it also runs and ships, so **three copies of every component exist** — know which copy an edit lands in:
 
 | Copy | Where | Role |
 | --- | --- | --- |
@@ -31,7 +31,7 @@ etna authors the components it also runs and ships, so **three copies of every c
 | **Dogfood** | `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, `.claude/hooks/` (git-tracked) | The subset the `etna` harness installs on itself — the copy this repo actually runs this session. |
 | **Shipped bundle** | `packages/cli/data/harnesses/*/` (git-tracked build artifact, regenerated by `packages/cli/scripts/build-data.js`) | Generated — never hand-edit. |
 
-- **Keep source and dogfood in sync.** When you edit a component etna dogfoods, mirror the change into its `.claude/` copy in the same change — otherwise the skill this session runs diverges from the one you authored.
+- **Keep source and dogfood in sync.** When a dogfooded component's source changes, mirror the edit into its `.claude/` copy in the same change — otherwise the skill this session runs diverges from the authored one.
 - **A component edit ships.** On push to `dev`, CI fingerprints the payload, patch-bumps, and publishes to the marketplace and `@nurix/etna` npm — reaching every consumer repo. Weigh catalog edits with that blast radius in mind. The pipeline authority is **[`docs/architecture/distribution.md`](docs/architecture/distribution.md)** — link, don't restate.
 
 ---
@@ -60,20 +60,20 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 ## Ownership, Boundaries & Documentation
 
-These three mechanisms keep the repo self-updating: **ownership** routes you to the canonical doc before you touch a component, the **boundary** check reads both sides of every contract your change participates in so you can't ship one side of it, and **documentation** closes the loop so the next session inherits the truth. Skipping any leg breaks the other two.
+These three mechanisms keep the repo self-updating: **ownership** routes an edit to the canonical doc before the component is touched, the **boundary** check reads both sides of every contract a change participates in so one side never ships alone, and **documentation** closes the loop so the next session inherits the truth. Skipping any leg breaks the other two.
 
-### Ownership — route before you edit
+### Ownership — route before editing
 
-Which doc is canonical for which paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (path globs — the only ownership key, pointing at `skills/**`, `harness/**`, `packages/cli/**`, …), an optional `module:` label, `keywords:`, and `status:`. Path → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and own nothing; operations docs describe procedures.
+Which doc is canonical for which paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (path globs — the only ownership key, pointing at `skills/**`, `harness/**`, `packages/cli/**`, …), an optional `module:` label, `keywords:`, and `status:`. Path → 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 its components 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 own nothing; operations docs describe procedures.
 
 Before modifying a component in an unfamiliar area:
 
-1. Consult the **injected ownership index** — the `glob → doc · module · keywords · status` map. Match your path or topic to the owning feature doc and read it first. (No index in context ⇒ the repo isn't reconciled — see Maintenance.)
+1. Consult the **injected ownership index** — the `glob → doc · module · keywords · status` map. Match the path or topic to the owning feature doc and read it first. (No index in context ⇒ the repo isn't reconciled — see Maintenance.)
 2. If a `docs/memory/` file exists for the area, 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. Resolve them in the LLD before proceeding.
 
-### Boundaries — check while you change
+### Boundaries — check while changing
 
 etna has no db schema, wire envelope, or auth of its own — the `boundary` skill's stack mechanisms describe the contracts of the **rules etna ships**, checked in the consumer's repo, not here. etna's **own** live contracts are authoring and distribution ones, each with no static link between the two sides:
 
@@ -86,9 +86,10 @@ Invoke the `boundary` skill after a plan is approved and before its first implem
 
 ### Documentation — close the loop
 
+- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md` (truth documents present-tense; history only in records). Instruction files — `CLAUDE.md`, rules, agents, skills — follow [`docs/architecture/writing-style.md`](docs/architecture/writing-style.md) instead.
 - **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work.
 - 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): prompt first.
-- When you move or rename a component: update the `owns:` globs of the feature doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
+- When moving or renaming a component: update the `owns:` globs of the feature doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
 - `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; one canonical source per topic, link don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
 > 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.
@@ -111,11 +112,11 @@ Override the auto-memory default for project-relevant facts. When recording a le
 
 ## Out-of-Scope Discovery
 
-When implementing a plan, if you discover work that is important but outside the current plan's scope:
+When a plan's implementation surfaces work that is important but outside the plan's scope:
 
 - Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
 - Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
-- Do NOT ask permission. Just append and mention it in your response.
+- Do NOT ask permission. Just append and mention it in the reply.
 
 ---
 
@@ -128,8 +129,8 @@ When implementing a plan, if you discover work that is important but outside the
 - ❌ **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 replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
 - ❌ **Protected Files** — before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` or that file itself.
-- ✅ **Browser Automation** — Claude in Chrome / CDP browser tools only when the user explicitly asks.
-- ✅ **Delegate at scale** — offload large, independent, or parallelizable work (broad research, audits, multi-file sweeps) to sub-agents with self-contained prompts; keep small, well-understood edits inline. Sub-agents can run skills and spawn their own sub-agents; keep work that needs the user's voice or the browser in the main session.
+- ✅ **Browser Automation** — Claude in Chrome / CDP browser tools: use freely when useful, no need to ask first.
+- ✅ **Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline.
 - ⚠️ **Plans** — created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Abandoned`, frozen — never edited. If scope changes after completion, write a new dated plan linking back.
 - ⚠️ **Tool Issues** — if any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool, command, and error to the user so they can fix the underlying library.
 
@@ -148,4 +149,4 @@ For real code (the CLI under `packages/`, hook scripts):
 
 ## Runtime Notes
 
-etna runs in Claude Code. Sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot hold the browser connection (browser work is 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`). Dispatch tiers: mechanical fan-out pins the fast tier (sonnet-class); a user-requested judgment-heavy dispatch takes the strong tier (opus-class) — tier names go stale, re-check on model releases.
+etna runs in Claude Code. Sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot hold the browser connection (browser work is 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`). Dispatch tiers: mechanical fan-out runs on the cheapest capable tier; a user-requested second opinion takes the strongest — pick by capability at dispatch, since model names go stale.

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

@@ -180,7 +180,7 @@ On approval, execute: create the folder structure; move/fold/merge/delete per th
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `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**).
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 

package/data/harnesses/etna/codex/agents/maintenance.toml

@@ -177,7 +177,7 @@ On approval, execute: create the folder structure; move/fold/merge/delete per th
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `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**).
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "dbc9b25ecc8f"
+  "digest": "8834d630e6dc"
 }