@nurix/etna 0.20.35 → 0.20.37

package/data/harnesses/etna/skills/documentation/templates/non-goals.md

@@ -1,11 +1,16 @@
-# Non-Goals (docs/architecture/non-goals.md)
+# Non-goals (docs/architecture/non-goals.md)
 
 Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
 
-```
+```markdown
+---
+type: non-goals
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Non-Goals
 
 Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
 
-- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+- **{Non-goal}:** {why it's excluded}. Revisit if: {the trigger that would reopen it}.
 ```

package/data/harnesses/etna/skills/documentation/templates/operations-procedure.md

@@ -1,14 +1,19 @@
-# Operations Procedure (docs/operations/{procedure}.md)
+# Operations procedure (docs/operations/{procedure}.md)
 
 Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
 
-A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **migration runbook** (record, `templates/migration-runbook.md`). The test: will someone run this again next month? Yes → operations. No → runbook.
 
 Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
 
 If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
 
-```
+```markdown
+---
+type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # {Procedure Name}
 
 **Goal:** What this procedure accomplishes, one line.

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

@@ -1,4 +1,4 @@
-# Package Documentation (docs/architecture/packages/{package}.md)
+# Package documentation (docs/architecture/packages/{package}.md)
 
 Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.
 
@@ -6,7 +6,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 
 **A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.
 
-**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. The one enumerable fact it declares is the ownership table: which subtrees other documents speak for.
+**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. Which subtrees narrower documents speak for is computed from their headers, never tabled here.
 
 **Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.
 
@@ -15,7 +15,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 | Section | When |
 | --- | --- |
 | `Scope` | required. Why the package is its own unit, who consumes it, and what it deliberately does not hold |
-| `Ownership` | required, as one line or a table |
+| `Ownership` | required, as one line |
 | `Usage` | required |
 | `Decisions` | once any choice was made that the code cannot explain |
 | `Promises` | required |
@@ -49,11 +49,7 @@ owns: ["packages/{name}/**"]                     # transitional — the residual
 
 ## Ownership
 
-This document is the residual owner of `packages/{name}/**`. Claimed at higher specificity:
-
-| Subtree | Stated and owned by |
-| --- | --- |
-| `src/{machine}/**` | [{system}](../systems/{system}.md) |
+This document is the residual owner of `packages/{name}/**`; a subtree whose files' headers name a system or feature document is that document's.
 
 ## Usage
 
@@ -77,7 +73,7 @@ This document is the residual owner of `packages/{name}/**`. Claimed at higher s
 - **Commands and exports:** {…} — the public contract
 - **Code root:** `packages/{name}/`
 - **Seams:** {…} by name
-- **Checklist:** `tests/{package}.md`
+- **Checklist:** `docs/tests/{package}.md`
 - **See also:** {neighbour}: {why}
 
 No file lists or symbol rosters — those are the graph's.

package/data/harnesses/etna/skills/documentation/templates/plan.md

@@ -8,7 +8,7 @@ The `boundary` skill parses the **Proposed Changes** sections to check boundary
 
 **Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
 
-The **`Gates:`** line carries two machine-read segments. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
+The **`Gates:`** line carries one machine-read segment. The compliance hook greps **`Boundary:`** and blocks implementation edits inside the plan's scope until it reads `passed`: `Boundary: pending` has no verdict yet and `Boundary: blocked` is a verdict against coding, so both wall. The `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; a blocked plan folds the amendments and re-runs the skill. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
@@ -51,12 +51,11 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Doc Obligations
 
 <!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
-     them against the injected ownership index. Hand-authored: this is a lookup, not research.
-     Amendable while the plan is open; discharged at Completion. -->
+     them against the injected ownership index. Hand-authored: this is a lookup, not research. Amendable while the plan is open; discharged at Completion. -->
 
-| Doc | Claim that changes | `owns:` still accurate? | Outcome |
+| Doc | Claim that changes | Still the owning doc? | Outcome |
 | --- | --- | --- | --- |
-| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — the document the changed files' headers should name | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
 
 **"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
 
@@ -69,12 +68,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Test Obligations
 
 <!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
-     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the
-     verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the
-     plan is open. Do not hand-author. NEVER put a pipe in a ledger cell, escaped or not — the
-     compliance hook splits rows on `|` at a fixed column index with no unescaping, so a
-     markdown-legal `\|` shifts every later cell and the wall blocks a row that is in fact
-     discharged. Write "`install` or `update`", not "`install \| update`". -->
+     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the plan is open. Do not hand-author. A literal pipe in a cell is written `\|`; an unescaped one adds a column and shifts every later cell. Prefer "`install` or `update`" to escaping. -->
 
 ## Open Questions
 

package/data/harnesses/etna/skills/documentation/templates/protected-files.md

@@ -1,10 +1,15 @@
-# Protected Files
+# Protected files
 
 Truth document. Use for: documenting critical files that need approval before modification.
 
 This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
 
-```
+```markdown
+---
+type: protected-files
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Protected Files
 
 Critical files requiring approval before modification.

package/data/harnesses/etna/skills/documentation/templates/root-readme.md

@@ -1,4 +1,4 @@
-# Project Root README (/README.md)
+# Project root README (/README.md)
 
 Truth document. Use for: the repository root `/README.md`. It opens outward — what the product does, for whom, and where it runs, in a user's terms — then turns inward for the team and coding agents: what state the repo is in, how it works, what its parts are and what must not break, then routes every other question into `docs/`. The outward part comes first because it is what a stranger reads; the inward part is longer because it is what the team uses. **It hosts nothing it can link to.** It is distinct from `docs/README.md`, which describes the folders of the docs tree, and from `CLAUDE.md` / `AGENTS.md`, the standing rules an agent loads. It points at both and restates neither.
 
@@ -13,7 +13,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 5. **State.** Optional: a one-line blockquote, present only while something repo-wide is true that a newcomer must know (frozen, mid-migration, mid-breaking-change on `dev`). It links the plan or runbook that owns the change. Say here which units publish and where, if any do.
 6. **The main path.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
 7. **Repository map.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
-8. **Rules that bite.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
+8. **Load-bearing rules.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
 9. **Destinations.** An intent-to-destination table. Its last row is the one for agents.
 10. **Everyday commands.** Optional. At most four commands run on every change, ending at the gate a push must pass. First-run commands are never here.
 
@@ -31,11 +31,11 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 ### Writing rules
 
-- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Rules that bite read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
+- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Load-bearing rules read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
 - **Every section is either a fact the reader acts on or a link.** If a section needs a paragraph, it needs a doc.
 - **One H1, then H2 sections, in plain Markdown.** Sentence-case headings, no emoji, no HTML layout, and no `#` comment lines inside code blocks (they parse as H1s).
 - **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
-- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
+- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md`, `AGENTS.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
 - **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
 - **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc the index resolves for that path. When the two disagree the index wins, and the Map row is fixed in the same change.
 - **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
@@ -90,7 +90,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 {One sentence each for the top folders that are not packages — `registry/`, `scripts/`, `docs/` — with their owning doc.} Where every doc lives: [docs/structure.md](docs/structure.md).
 
-## Rules that bite
+## Load-bearing rules
 
 {One sentence saying these are stated here and argued in the documents they point at.}
 

package/data/harnesses/etna/skills/documentation/templates/security-overview.md

@@ -1,10 +1,15 @@
-# Security Overview (docs/architecture/security.md)
+# Security overview (docs/architecture/security.md)
 
 Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
 
 Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
-```
+```markdown
+---
+type: security-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Security Overview
 
 ## Assets
@@ -13,7 +18,7 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Trust boundaries
 
-- {Boundary} — {what crosses it, and what checks the crossing} 
+- **{Boundary}:** {what crosses it, and what checks the crossing} 
 
 ## Controls
 
@@ -23,5 +28,5 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Accepted risks
 
-- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+- **{Risk knowingly carried}:** accepted because {reason}; owner: {who}. Revisit if: {trigger}.
 ```

package/data/harnesses/etna/skills/documentation/templates/setup.md

@@ -4,7 +4,7 @@ Truth document, operations genre (`type: operations`). Use for: **the one-time p
 
 It is distinct from `local-development.md`, the daily loop: watch modes, resetting state, per-package traps, the inner test cycle. Setup runs once per machine. Local development runs every session. Setup ends by handing off to it, and neither copies the other. Deploying is `deployment.md`.
 
-Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **Verify**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
+Required: **Goal**, **Stack**, **Prerequisites**, **Installation**, **First run**, **Verification**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
 
 ### Writing rules
 
@@ -32,7 +32,7 @@ description: "{at most 300 characters: what this document settles and where its
 
 **Goal:** take a fresh machine from clone to a verified first run of {what runs: e.g. "the product Worker on :{port} and the web shell on :{port}, signed in as the dev fixture"}. Done once per machine; the daily loop is [`local-development.md`]({local-development}.md).
 
-{Optional audience fork: "Only running {the CLI / one package}? Stop after Install and see [`{procedure}`]({path})."}
+{Optional audience fork: "Only running {the CLI / one package}? Stop after Installation and see [`{procedure}`]({path})."}
 
 ## Stack
 
@@ -59,7 +59,7 @@ Why these were chosen: [{system overview}](../architecture/{overview}.md).
 
 - **{Trap}:** {what a fresh clone hits and the one command that clears it, e.g. `git lfs install`, `git submodule update --init`}.
 
-## Install
+## Installation
 
 \`\`\`bash
 git clone {url} && cd {repo}
@@ -103,7 +103,7 @@ The contract is [`{example file or typed Env}`](../../{path}). Read it before co
 
 4. Open `{http://localhost:port}` and {sign in as `{seeded user}` / reach `{first screen}`}.
 
-## Verify
+## Verification
 
 - `{curl -fsS http://localhost:{port}/{health}}` returns `200` {and `{body}`}.
 - `{doctor or status command}` reports {expected}. ← keep whichever exists
@@ -130,9 +130,9 @@ The baseline scaffolds `docs/operations/setup.md` when it is missing and the rep
 
 - **Stack:** from the workspace manifests, one row per layer.
 - **Prerequisites:** from the pinning files.
-- **Install and First run:** from the root README's getting-started block (if one exists) and the root scripts.
+- **Installation and First run:** from the root README's getting-started block (if one exists) and the root scripts.
 - **Environment files:** from every `*.example` / `.dev.vars.example` in the workspace.
-- **Verify:** from a health route, a doctor command or the test script.
+- **Verification:** from a health route, a doctor command or the test script.
 
 It leaves Common failures empty until a failure is root-caused, and it drops every section it cannot fill concretely.
 

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

@@ -1,13 +1,18 @@
-# System Overview (docs/architecture/system-design.md)
+# 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.
+Required: **Purpose**, **Subsystem map**. Optional: Key flows, Sources of truth.
+
+```markdown
+---
+type: system-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # System Overview
 
-## What this is
+## Purpose
 
 {Two or three sentences: what the system does, for whom, in what environment it runs.}
 
@@ -18,13 +23,13 @@ Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the tr
 └──────────┘     └──────────┘     └──────────┘
 {One box per subsystem; label the arrows with the contract that crosses them.}
 
-- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+- **{Subsystem}:** what it owns, in one line. → [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.}
+{At most two or three mermaid flow diagrams, at role level, for the flows everything else hangs off: request lifecycle, auth, the core domain operation.}
 
-## Where the truth lives
+## Sources of truth
 
 | Area | Canonical doc |
 | ---- | ------------- |

package/data/harnesses/etna/skills/documentation/templates/system.md

@@ -1,4 +1,4 @@
-# System Documentation (docs/architecture/systems/{system}.md)
+# System documentation (docs/architecture/systems/{system}.md)
 
 Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.
 
@@ -69,7 +69,7 @@ owns:                                            # transitional — region globs
 - **Objects:** {…}
 - **Code roots:** {…} — directories, one per package the machine spans
 - **Seams:** {…} by name
-- **Checklist:** `tests/{system}.md`
+- **Checklist:** `docs/tests/{system}.md`
 - **See also:** {neighbour}: {why}
 
 No tables, routes or symbol rosters — those are the graph's.

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

@@ -1,10 +1,15 @@
-# Testing Strategy (docs/tests/strategy.md)
+# Testing strategy (docs/architecture/common/testing.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.
+Required: **Levels**, **Commands**. Optional: Deliberately untested, New tests.
+
+```markdown
+---
+type: testing-strategy
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # Testing Strategy
 
 ## Levels
@@ -14,7 +19,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 | Unit / integration | {runner} | `tests/` | {what} |
 | E2E | {runner} | `e2e/` | {what} |
 
-## Running
+## Commands
 
 - `{pm} test` — the whole unit suite (CI gate)
 - `{pm} run test:e2e` — {when to run}
@@ -23,7 +28,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 
 - {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
 
-## Adding a test
+## New tests
 
 1. {Where the file goes, what it's named, where fixtures live}
 ```

package/data/harnesses/etna/skills/documentation/templates/ux-behavior.md

@@ -1,9 +1,20 @@
-# UX Behavior — template
+# UX behavior (docs/features/{surface}-ux.md)
 
 **Truth document.** States what a person sees and can do on a surface, and what the surface promises never to do. Present tense, like every truth document.
 
 **`type: ux`**, plus `status:` and `objects:` — the objects the surface presents (`references/frontmatter.md`). The doctrine it answers to (the state vocabulary, the routing doctrine, the information architecture) is named in its Purpose for people and computed through shared objects for tooling.
 
+```yaml
+---
+type: ux
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+status: active                    # draft until the surface it decides is built
+objects: [workspace, run]         # the objects the surface presents
+owns:                             # transitional, only when this document speaks for the surface's components (references/frontmatter.md)
+  - packages/{pkg}/src/{surface}/**
+---
+```
+
 **Why this genre exists.** A feature doc (LLD) states what a feature is, how its data flows, and which contracts it honours — all of which stay plausibly true through a rewrite of the surface. Nothing else in the repo states what a person *observes*. So a change to the wire lands, the interface absorbs it, and the absorption reads as maintenance: no test fails, no lint fires, no document is contradicted. This document is the thing a silent change contradicts.
 
 **Not a test plan.** `docs/tests/{feature}.md` records that behavior was driven and holds `Pinned:` traces; this document *decides* the behavior it later verifies. Written after the code, it is a transcript. Write it first.
@@ -15,9 +26,7 @@
 | One surface's — a panel, an editor, a dialog | `docs/features/{surface}-ux.md`; its component files' headers name it |
 | Cross-cutting — routing, information architecture, the state vocabulary every surface obeys, presentation of streams | `docs/architecture/` — owns no code, like every architecture doc |
 
-**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **coordinated edits** row instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component yet, its header names this one.
-
-That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The coordinated-edit row is the weaker of the two bindings; prefer the header pointer wherever no document speaks for the component yet.
+**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **See also** line under For the agent instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component, its header names this one; prefer that header pointer, because the See also line is the weaker binding. A document nothing implicates rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent.
 
 ---
 
@@ -56,7 +65,7 @@ What moves the surface between states, and who causes each move — the person,
 
 ## Optional sections
 
-**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately not yet made, so an implementer knows what to ask rather than guessing.
+**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately left open, so an implementer knows what to ask rather than guessing.
 
 ## Rules