@nurix/etna 0.19.20 → 0.19.22

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/code/skills/workflow-mapper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-mapper
-description: Discover and document all major workflows in a codebase by tracing call chains from user action to database/external system. Produces mermaid sequence diagrams and markdown documentation. Use when the user asks to map workflows, trace flows, document sequences, understand how features work end-to-end, or generate architecture diagrams. Triggers on "map workflows", "trace workflows", "workflow diagram", "sequence diagram", "how does X work end-to-end", "document flows", "codebase workflows", "how does this feature work", "trace the request flow", "show me the call chain", "what happens when a user does X", "end-to-end flow".
+description: "Discover and document a codebase's major workflows by tracing call chains from user action to database or external system — produces mermaid sequence diagrams and markdown. Triggers on 'map workflows', 'trace flows', 'sequence diagram', or 'how does X work end-to-end'."
 ---
 
 # Workflow Mapper Skill

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

@@ -45,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
@@ -132,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.11",
+  "version": "0.1.12",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json",
     "tooling-recommendations.md"
   ],
-  "digest": "3b981c0284cc"
+  "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/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "f974d08469e5"
+  "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 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 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. 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.
 
 ---
 

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.10",
+  "version": "1.1.11",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "3f4d8edde6db"
+  "digest": "3e3243936008"
 }

package/data/harnesses/etna/skills/boundary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boundary
-description: Boundary diagnostic for implementation plans. Given a plan file, reads the source the plan touches, identifies the cross-cutting contracts it participates in — db schema, wire envelope, auth, events, env/config, … — where editing one side silently breaks the other, and reports whether the planned changes would violate any of them, severity-ranked, with suggested amendments and a pass/block verdict. Read-only; the report lands in chat. Also runs against a diff or named code area. Triggers on "boundary check", "check this plan", "what could break", "will this break anything", "is it safe to rename this column/endpoint/event", "who uses this", "impact analysis", "/boundary".
+description: "Boundary diagnostic for implementation plans. Reads the source a plan touches, finds the cross-cutting contracts it joins (db schema, wire envelope, auth, events), and reports violations with a pass/block verdict. Read-only; also runs on a diff. Triggers on 'boundary check', 'what could break'."
 ---
 
 # Boundary Diagnostic

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Thinking-partner session for designing large-scale software changes. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document, a prior session folder of any format, or a one-shot brain dump); drip-sized asks are redirected. The facilitator owns the conversation and appends everything to an untracked ops ledger; the brainstorm twin agent owns the working surface (thesis / forks / ledger / state / fragments), dispatched at gates — start, on demand, pause, stop — and paired-logged; a detector script owns mechanical integrity. Stop always triggers convergence, a user-approved harvest manifest, a uselessness test, and the folder's move to docs/history/brainstorms/, where the user decides: delete or commit.
+description: "Thinking-partner session for designing large-scale software changes. Invoked ONLY by `/brainstorm start` and `/brainstorm stop` — never on phrases like 'let's plan' or 'let's design'. Entry needs a basis (a reference doc, prior session folder, or brain dump); drip-sized asks are redirected."
 argument-hint: "start | stop"
 ---