@nurix/etna 0.19.19 → 0.19.21

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

@@ -1,13 +1,30 @@
 ---
 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 (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 or revise an architecture decision (an AD), (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 a one-shot migration runbook, (11) write a steering doc (system overview, domain model, glossary, non-goals, security overview, testing strategy), (12) catalog the API surface or the environment/config registry, or (13) 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", "AD", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD", "glossary", "domain model", "runbook", "API reference".
+description: Invoke BEFORE creating or substantively editing ANY markdown doc. Templates + style authority for technical docs — LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent.
 ---
 
 # Technical Documentation Skill
 
 **This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
-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.
+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 stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+
+---
+
+## Present tense, always
+
+**A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
+
+| ❌ Strip this | ✅ Write this |
+| --- | --- |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — fix the references; state only the present design |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
+
+The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
+
+The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch.
 
 ---
 
@@ -25,10 +42,10 @@ Every document is exactly one of two things. Decide which before writing a word
 
 The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
 
-- **Truth documents never narrate history.** No migration/fold stories, no dated "shipped/verified on YYYY-MM-DD" markers, no "was X → now Y" journeys, no provenance asides ("ex-`@nurix/X`, folded 2026-06-12"). When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Truth documents never narrate history** — the § Present tense, always rule above, applied to this nature. When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
-- **The one bridge — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog**: the single sanctioned dated-history section inside a truth document, because for a decision the journey (what each revision reversed, and what triggered it) is part of the reasoning. The AD body stays current-truth-only; the tail carries the dates and links to the plans that implemented each revision. No other truth document carries dated history.
-- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents — never to a plan or changelog entry as the "read first" source.
+- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and `docs/structure.md` ends with the maintenance agent's **Health Log** (tooling-stamped audit rows, the structural cousin of `last-reviewed:`). In both, the body stays current-truth-only; the tail carries the dates. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
 **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.
 
@@ -36,51 +53,43 @@ The two guarantees are complementary and both break on mixing: a reader holding
 
 ---
 
-## Decision Tree
-
-```
-User request
-    │
-    ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
-    │
-    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
-    │
-    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
-    │
-    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
-    │
-    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
-    │
-    ├─ "Add to protected files" ───────▶ Protected Files Template
-    │
-    ├─ "Record/revise architecture
-    │    decision" ────────────────────▶ AD Template (one per subject; revisions update it in place)
-    │
-    ├─ "System at a glance" ───────────▶ System Overview Template
-    │
-    ├─ "Domain model / glossary /
-    │    non-goals" ───────────────────▶ Steering Templates
-    │
-    ├─ "Catalog the API surface" ──────▶ API Reference Template
-    │
-    ├─ "Document env vars / config" ───▶ Environment Registry Template
-    │
-    ├─ "Security / threat model" ──────▶ Security Overview Template
-    │
-    ├─ "Testing strategy" ─────────────▶ Testing Strategy Template
-    │
-    ├─ "Recurring procedure/setup" ────▶ Operations Procedure Template
-    │
-    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
-    │
-    ├─ "Create/update root README" ────▶ Project Root README Template
-    │
-    ├─ "Create/update plan" ───────────▶ Plan Template (record)
-    │
-    ├─ "Update existing doc" ──────────▶ Preserve existing structure
-    │
-    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
-```
+## Routing
+
+| Request | Route |
+| --- | --- |
+| Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
+| Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
+| Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
+| Create/update changelog | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record) |
+| Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
+| Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
+| System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |
+| Domain model | [`templates/domain-model.md`](templates/domain-model.md) |
+| Glossary | [`templates/glossary.md`](templates/glossary.md) |
+| Non-goals | [`templates/non-goals.md`](templates/non-goals.md) |
+| Catalog the API surface | [`templates/api-reference.md`](templates/api-reference.md) |
+| Document env vars / config | [`templates/environment-registry.md`](templates/environment-registry.md) |
+| Security / threat model | [`templates/security-overview.md`](templates/security-overview.md) |
+| Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
+| Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
+| Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
+| Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |
+| Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
+| Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
+| Update existing doc | § Editing an existing doc (below) |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
+
+---
+
+## Editing an existing doc
+
+"Substantive" = anything beyond typo, link, or formatting fixes. On a substantive edit:
+
+1. **Determine the nature first.** A frozen record (a `Status: Complete`/`Abandoned` plan, a changelog entry, an executed runbook) is never edited — write a new dated record that links back.
+2. **Preserve structure, not violations.** Keep the doc's existing section shape, but every section touched sheds history narration, progress markers, and stale tripwires on the way through (§ Present tense, always).
+3. **Stamp and re-derive.** A substantive feature-doc update bumps `last-reviewed:`; if the documented scope moved, update `owns:` ([`references/frontmatter.md`](references/frontmatter.md)).
 
 ---
 
@@ -104,62 +113,7 @@ User request
 
 ## Frontmatter Derivation
 
-When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
-
-### When to run
-
-- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the Feature template, project its `owns:` globs
-- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
-
-### How to derive the frontmatter
-
-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)
-
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
-
-| Doc references                       | Glob                      |
-| ------------------------------------ | ------------------------- |
-| Multiple files under one directory   | `src/feature/**`          |
-| Specific files in a shared directory | List each file explicitly |
-| A single entry-point file            | The exact file path       |
-
-Glob each pattern against the codebase; drop any that match nothing.
-
-**2. `module:`**
-
-The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
-
-**3. `keywords:` & `status:`**
-
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
-
-A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
-
-### Rules
-
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
-- Use glob patterns for directories, explicit paths for individual files. Don't list paths that don't exist in the codebase.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
-
----
-
-## Co-Authoring Workflow
-
-For docs that don't match templates:
-
-**Stage 1: Context Gathering**
-
-- Ask: Audience? Purpose? Existing format?
-- Have user dump all context, then ask 5-10 clarifying questions
-
-**Stage 2: Structure & Draft**
-
-- Propose section structure, draft section by section
-- User indicates changes (don't edit directly — learn their style)
+A feature doc carries ownership frontmatter — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required), optional `last-reviewed:`. Deriving it from code and keeping it accurate is [`references/frontmatter.md`](references/frontmatter.md) — every feature-doc create or update, and the `maintenance` agent's baseline pass, route there.
 
 ---
 
@@ -167,6 +121,9 @@ 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, operations procedure, migration runbook, protected files, AD, steering docs (system overview, domain model, glossary, non-goals, security, testing strategy), API reference, environment registry, project root README templates |
+| `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
+| `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |
+| `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |

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

@@ -21,11 +21,15 @@ function mergeData(server, local, changes) { const result = {}; const serverMap
 ```markdown
 ### `mergeData(serverData, localData, changes)`
 
-**Goal:** Merge server data with local changes **Input:**
+**Goal:** Merge server data with local changes
+
+**Input:**
 
 - `serverData` (array) - Fresh from API
 - `localData` (array) - Current state
-- `changes` (object) - `{ added, updated, removed }` **Output:** `{ merged: array, conflicts: array }`
+- `changes` (object) - `{ added, updated, removed }`
+
+**Output:** `{ merged: array, conflicts: array }`
 
 **Merge Rules:**
 
@@ -61,11 +65,22 @@ const [items, setItems] = useState([]);
 ```markdown
 ## State
 
-**Frontend (at persistence):** { "data": [], "changes": { "added": [], "updated": [], "removed": [] } // "cache": {} // UNUSED: Deprecated }
+**Frontend (at persistence):**
+
+{
+  "data": [],
+  "changes": { "added": [], "updated": [], "removed": [] }
+  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
+}
 
 **Storage:** localStorage `app_state`
 
-**Backend:** model Item { id String @id data Json }
+**Backend:**
+
+export const items = pgTable('items', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+});
 ```
 
 ---
@@ -144,9 +159,23 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 ```markdown
 ## Data Flow
 
-┌─────────────────────────────────────────┐ │ DATA SYNC │ ├─────────────────────────────────────────┤ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │Server│────▶│Merge │────▶│Redux │ │ │ │ API │ │ │ │Store │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ │ ▼ │ │ Version Check │ │ │ └─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load **Version Rule:** Match → local wins, Mismatch → server wins
+┌─────────────────────────────────────────┐
+│               DATA SYNC                 │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌──────┐     ┌──────┐     ┌──────┐    │
+│   │Server│────▶│Merge │────▶│Redux │    │
+│   │ API  │     │      │     │Store │    │
+│   └──────┘     └──────┘     └──────┘    │
+│        │                                │
+│        ▼                                │
+│   Version Check                         │
+│                                         │
+└─────────────────────────────────────────┘
+
+**Trigger:** `useAppInit()` on page load
+
+**Version Rule:** Match → local wins, Mismatch → server wins
 ```
 
 ---
@@ -191,6 +220,52 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 
 ---
 
+## Example 6: Stripping history from a truth doc
+
+The move agents fumble: deleting narration is only half the job — the story must land in a record.
+
+### ❌ Bad: The journey narrated in place
+
+```markdown
+## Export Pipeline
+
+The exporter was extracted from the legacy `reports` worker (2026-06-02) and
+now lives in `src/export/`. Phases 0–2 of the rewrite are complete; streaming
+output is not yet implemented. Treat any reference to `reports/export.js` as
+stale — it was superseded by `src/export/run.js`.
+```
+
+### ✅ Good: Present-tense truth doc + a dated record carrying the story
+
+The feature doc states only what is:
+
+```markdown
+## Export Pipeline
+
+`src/export/run.js` renders every export format from one job queue. Output is
+buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
+```
+
+And the change-story goes to `docs/history/changelog/2026-06-02-export-extraction.md`:
+
+```markdown
+# 2026-06-02 — Export pipeline extracted
+
+## Summary
+
+Extracted export logic from the `reports` worker into `src/export/`.
+
+## Changes
+
+### Removed
+
+- `reports/export.js` — replaced by `src/export/run.js`; all callers repointed.
+```
+
+**Why it works:** the truth doc needs no archaeology to act on; the dates, the predecessor, and the supersession live in a frozen record; the unbuilt part is a backlog pointer, not a "not yet" hedge; and no stale-reference tripwire survives because the references themselves were fixed.
+
+---
+
 ## Quick Comparison
 
 | Aspect     | Bad                  | Good                        |
@@ -200,4 +275,5 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 | Flows      | Prose paragraphs     | ASCII diagrams              |
 | Changelogs | "Updated X"          | Function names + migrations |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
+| History    | Narrated in the doc  | Present-tense doc + dated record |
 | Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/etna/skills/documentation/references/frontmatter.md

@@ -0,0 +1,44 @@
+# Frontmatter Derivation — feature-doc ownership
+
+Load when: creating a feature doc, updating one whose documented scope moved, or running a baseline/reconcile pass over many docs.
+
+When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
+
+## When to run
+
+- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
+- **New feature doc** — when creating a doc via the [Feature template](../templates/feature.md), project its `owns:` globs
+- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
+
+## How to derive the frontmatter
+
+A feature doc's ownership 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)
+
+Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
+
+| Doc references                       | Glob                      |
+| ------------------------------------ | ------------------------- |
+| Multiple files under one directory   | `src/feature/**`          |
+| Specific files in a shared directory | List each file explicitly |
+| A single entry-point file            | The exact file path       |
+
+Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
+
+**2. `module:`**
+
+The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
+
+**3. `keywords:` & `status:`**
+
+`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+
+A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
+
+## Rules
+
+- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
+- Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
+- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.

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

@@ -11,10 +11,16 @@ Writing rules for clear, maintainable documentation.
 ```markdown
 ### `functionName(param1, param2, options)`
 
-**Goal:** One-line purpose **Input:**
+**Goal:** One-line purpose
+
+**Input:**
 
 - `param1` (type) - Description
-- `param2` (type, optional) - Description **Output:** `{ field1, field2 }` **Side Effects:** State updates, API calls, etc.
+- `param2` (type, optional) - Description
+
+**Output:** `{ field1, field2 }`
+
+**Side Effects:** State updates, API calls, etc.
 ```
 
 ### Parameter Rules
@@ -62,34 +68,33 @@ Always specify:
 ```json
 {
   "activeField": "value"
-  // "deprecated": null  // UNUSED: Remove in v3
+  // "deprecated": null  // UNUSED: dead key; kept so old persisted state rehydrates
 }
 ```
-````
 
 **Storage:** localStorage key `state_key`
 
 **Backend:**
 
-```sql
-model Table {
-  id   String @id
-  data Json
-  // old String?  // UNUSED: Legacy
-}
+```ts
+export const table = pgTable('table', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+  // old: text('old'),  // UNUSED: dead column; nothing reads it
+});
 ```
-
 ````
 
 ### Mark Unused Keys
 
-Always comment deprecated/unused fields:
+Always comment deprecated/unused fields. The annotation states why the field is dead _now_ — never where it went, what replaced it, or when it will be removed (no "Remove in v3", no "Migrated to newField"; that is history narration, § The Two Natures below):
+
 ```json
 {
   "active": [],
-  // "legacy": {}  // UNUSED: Migrated to newField
+  // "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility
 }
-````
+```
 
 ---
 
@@ -102,6 +107,8 @@ Always comment deprecated/unused fields:
 - Component interactions
 - Process flows
 
+**Docs only.** Diagrams belong in documents read on demand (feature docs, ADs, operations). Instruction files — `CLAUDE.md`, rules, agent definitions, `SKILL.md` prose — never carry them: they load on every turn or every invocation, and a table or a sentence carries the same information at a fraction of the tokens.
+
 ### Pattern
 
 ```
@@ -168,6 +175,8 @@ function extract(json) {
 
 ❌ Bad: Full 50-line implementation
 
+(Worked example: [`examples.md`](examples.md) Example 1.)
+
 ---
 
 ## Writing Style
@@ -191,7 +200,7 @@ Prose is valuable for context that contracts can't capture:
 | Non-obvious behavior | "The hook always fetches fresh data. There is no caching or version checking." |
 | Design rationale | "Why parallel fetches? Each entity type is independent, reducing load time." |
 | Edge cases | "If created then deleted before save, it's removed from `added[]` without adding to `removed[]`." |
-| Current limitations | "This hook is not currently integrated into the main flow." |
+| Limitations, stated as facts | "`useAppInit` is standalone — nothing in the mount path calls it." |
 | Usage context | "Used to show 'Unsaved' badge, warn before navigation, enable save buttons." |
 
 ### When to Avoid Prose
@@ -224,7 +233,7 @@ Use for structured info:
 
 Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
 
-**Truth documents 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 journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Two sanctioned exceptions: `docs/memory/` is the agent's own dated ledger, and an AD's **Decision Changelog** tail carries that decision's dated revision history (the AD body stays current-truth-only — head is truth, tail is provenance).
+**Truth documents 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 journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Three sanctioned exceptions: `docs/memory/` is the agent's own dated ledger; an AD's **Decision Changelog** tail carries that decision's dated revision history; and `docs/structure.md`'s **Health Log** tail carries the maintenance agent's tooling-stamped audit rows. In both tail bridges the body stays current-truth-only — head is truth, tail is provenance.
 
 **Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
 
@@ -236,16 +245,31 @@ Strip this language from truth documents:
 | "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
 | "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
 | "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record; the doc describes what exists |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — delete or repoint the stale references; state only the present design |
 | "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
 
 Rules:
 
-- **No dates in truth documents** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **No dates and no progress narration in truth documents.** Nothing about _when_ something shipped, was verified, folded, or was removed — and no completion markers either: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a **record's** job (the plan, the backlog); a truth document describes what exists, as if it had always been so.
+- **No stale-reference tripwires.** Never write "X is gone — treat references to X as stale"; that is a redirect doc compressed into one sentence. Delete or repoint every stale reference instead (same rule as the **No redirect docs** rule in `SKILL.md` § The Two Natures) and state only the present fact.
+- **No version or phase framing.** A bare `v1`/`v2` as a label, "Phase 1/2", "the old X", "supersedes the earlier" — there is one design; describe it without its predecessors. (A version naming an external present-tense fact stays: a schema literal like `design-tokens/v2`, a dependency pin like `@0.14.0`.)
+- **Temporal hedges are progress markers in prose.** "currently", "not yet", "still", "for now" smuggle a ⏳ into a truth document — state the fact without the hedge ("the hook is standalone; nothing in the mount path calls it") and let the backlog record carry the intention.
+- **A published artifact's own version surface is external fact.** Release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`) — that is the artifact's public contract, not the doc narrating its own past. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`.
 - **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to truth documents.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row.
+- **Routing/index docs point only to truth documents as a topic's authority.** A row whose "read first" target for a topic is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned: that indexes records, it doesn't route a topic.)
 - **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
 - **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
 
+Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
+
+---
+
+## Mechanics
+
+- Inline-code every identifier, filename, command, and config key.
+- Bullet rules take the form "**bold assertion** — explanation."
+
 ---
 
 ## Structure
@@ -309,7 +333,8 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows             |
+| Diagrams   | ASCII for all flows — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
+| Mechanics  | Inline-code identifiers; bold-assertion bullets |
 | Length     | Concise, one line when possible |

package/data/harnesses/etna/skills/documentation/references/untemplated.md

@@ -0,0 +1,38 @@
+# Writing an Untemplated Document
+
+Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".
+
+A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.
+
+## 1. Decide the nature — truth or record
+
+Every document is exactly one (`SKILL.md` § The Two Natures). Ask: *when reality changes, is this file rewritten, or is it frozen?*
+
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § Present tense, always.
+- Frozen or append-only → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+
+When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
+
+## 2. Place and name it
+
+- `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
+- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
+- A new topic *folder* gets a `Readme.md` landing page that introduces and indexes it.
+
+## 3. Shape it
+
+- **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
+- **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
+- **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
+- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the files.
+
+## 4. Write it in the house style
+
+`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); imperative/active voice; code examples under 15 lines showing contracts, not implementations; ASCII diagrams in docs only; inline-code every identifier, filename, command, and config key.
+
+## 5. With a human in the loop — the co-authoring workflow
+
+**Stage 1 — context gathering.** Ask: audience? purpose? existing format to match? Have the user dump all the context they hold, then ask 5–10 clarifying questions before proposing anything.
+
+**Stage 2 — structure & draft.** Propose the section structure from §1–3 above, then draft section by section. The user indicates changes — learn their style from their edits; don't silently rewrite them.