@nurix/etna 0.20.34 → 0.20.36

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

@@ -1,87 +1,86 @@
 ---
 name: documentation
-description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. 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."
+description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. Genre registry, templates and 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.
+This skill writes one document at a time: the genre registry says what kind of document it is, a template gives its shape, the style guide its prose, and `doc-lint` checks the mechanical half. It does not baseline, audit or reconcile a repo's doc tree; that is the `maintenance` agent, which calls this skill once per document it scaffolds.
 
-Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). A diagram sits beside the prose and never replaces it: ASCII for structure at rest, mermaid for behaviour over time (`references/style-guide.md` § Diagrams). 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.
+## Load order
 
----
-
-## Where a file's documentation lives
+1. This file.
+2. Your genre's row in [`templates/Readme.md`](templates/Readme.md) § Registry, then the template that row names.
+3. [`references/style-guide.md`](references/style-guide.md) § The model and § Labels before writing prose; the rest of it only for the section you are writing.
+4. [`references/frontmatter.md`](references/frontmatter.md) when you write or change frontmatter keys beyond `type:` and `description:`.
+5. Only for their own tasks: [`references/untemplated.md`](references/untemplated.md) (no registry row fits), [`references/instruction-style.md`](references/instruction-style.md) (instruction files), [`references/source-comments.md`](references/source-comments.md) (source-file comments), [`references/examples.md`](references/examples.md) (worked good and bad examples).
 
-**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`references/frontmatter.md`](references/frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+---
 
-**Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
+## Writing one document
 
-| The claim is | What it earns |
-| --- | --- |
-| Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
-| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
-| History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
+1. **Find the genre.** Match the request against § Routing, then read that genre's registry row: nature, `type:`, location, required keys, required sections. No row fits ⇒ `references/untemplated.md`.
+2. **Find the existing document.** If a document on the topic already exists, extend it; a second document on one topic is drift. If the file is a frozen record (a plan at `Complete` or `Abandoned`, a committed changelog entry, an executed runbook), never edit it: write a new dated record that links back.
+3. **Place and name it** at the registry's location. `docs/structure.md` is the placement authority for anything the registry leaves open.
+4. **Write it from the template.** Keep the template's section names exactly; omit optional sections with nothing real to say. Write the body from the outside in (style guide § Shape), every heading and bold label a noun phrase, every sentence after a label third person. In a truth document, every sentence is present tense (§ The three natures).
+5. **Write the frontmatter.** `type:` from the registry, `description:` in at most 300 characters saying what the document settles and where its boundary sits, then the genre's required keys (`references/frontmatter.md` for each key's rules).
+6. **Run the lint** from the repo root on the repo-relative path: `node <skill>/scripts/doc-lint.mjs docs/features/sign-in.md` (or `--changed`). Fix every `[block]` finding; read every `[warn]` and fix it unless the judgment it flags is genuinely yours. A disable takes bare rule ids, `<!-- doc-lint-disable: id -->`, alone on its own line for the whole file with the reason in a second comment on the next line, or at the end of one line for that line only.
+7. **Edit, don't append, on a substantive change to an existing truth document.** Keep its section shape, shed any history narration, progress marker or stale tripwire in the sections you touch, bump `last-reviewed:`, update `objects:` if what it designs changed, and remove any retired key on the way through.
 
-**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+---
 
-**The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
+## The three natures
 
-**Never convert a booby trap into a one-liner.** A comment whose subject is a danger on an edge that looks safe — a pinned dependency's limitation, a measurement that justifies a narrow allowlist, a two-clock interaction — is load-bearing where it sits, because the reader who needs it is mid-edit and will not go looking. Compress it if it rambles; do not relocate it. The tell is that the comment names a version, a measurement, or a condition under which it expires.
+Every document is exactly one of three things, and the registry names which for every genre. Decide before writing a word: every other rule follows from the split.
 
----
+| | **Truth** | **Record** | **Queue** |
+| --- | --- | --- | --- |
+| States | How the system is, now | What happened | Work not done yet |
+| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` | A fixed name: `backlog.md`, `journal.md` |
+| On change | Body rewritten in place | Frozen at its terminal status | A row appended, or a resolved row deleted |
+| Read to | Act correctly today | Trace provenance, diagnose, audit | Pick up the next piece of work |
 
-## Present tense, always
+The guarantees break on mixing: a reader holding a truth document must never need history to interpret it, a reader holding a record must trust it was never rewritten, and a reader holding a queue must trust that every row in it is still open.
 
-**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.
+- **Truth documents narrate no history.** When the system changes, the change-story goes to a changelog entry and the truth document simply becomes correct. Write as if the current design had always been the plan.
+- **Records are never edited to match the present.** A completed plan stays wrong in hindsight; a scope change gets a new dated record that links back.
+- **Queue rows are resolved by deletion.** A finished backlog item, a landed journal fact, a drained bookkeeping row is deleted, never marked done; the plan or changelog entry that did the work is the record.
+- **One bridge: an Architecture Decision's Decision Changelog.** For a decision, the journey is part of the reasoning, so an AD ends with a dated, append-only tail while its body stays current. No other truth document carries dated history.
 
-| ❌ Strip this | ✅ Write this |
+| ❌ Strip this from a truth document | ✅ 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 |
+| "Build Sequence phases 0–4 are complete." | Nothing; progress lives in the plan or backlog |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing; fix the references and 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 and history.
-
-**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The three exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail on a truth document.
+- **Dates:** a truth document carries no dated line. The exceptions are closed: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:`, `harness-version:`), an AD's Decision Changelog, and a dated path inside a link or code span, which cites a record rather than claiming a date.
+- **Citing a record:** by what it is, never by when it was. "The dev reset runbook" linked to the file stays true; "the 2026-09-13 reset" goes stale at the second reset.
+- **Verification stamps:** "Driven 2026-09-13 · PASS" in a checklist is a dated event. The section states what must be true and which suite test guards it; that someone drove it belongs to the changelog entry of the unit that drove it.
 
-**Cite a record by what it is, never by when it was.** `the dev reset runbook` links to the file; "the 2026-09-13 reset" states a date the reader must now keep in their head and that goes stale as soon as a second reset happens. The link carries the date in its path, where it belongs, and the prose stays true forever.
-
-**A verification stamp is a record, not a status line.** "Driven 2026-09-13 · PASS" in a behavioural checklist is the clearest instance of this defect: it reads as documentation and is actually a dated event. The section states what must be true and which suite test guards it; *that* somebody drove it on a Tuesday belongs to the changelog entry of the unit that drove it, and staleness is then visible from something that re-checks itself — a pin that runs in CI — rather than from a date nobody re-stamped. A section with no automated guard says so in its trace, which is a stronger signal than an old date, because it cannot silently become wrong.
-
-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. Two invocation traps: the disable comment takes **bare rule ids only** — prose inside the comment silently breaks the parse, so put the reason in a second comment beside it — and the script grades truth-vs-record scope by matching `docs/(history|research|memory)/` against **the path string it is given**, so always hand it a repo-root-relative path; linting a record from inside its own folder grades it as a truth document.
+The full strip-list and the record-side rules: `references/style-guide.md` § The Two Natures — tense and history.
 
 ---
 
-## The Two Natures
-
-Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
-
-| | **Truth document** | **Record** |
-| --- | --- | --- |
-| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
-| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
-| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
-| Read to | Act correctly today | Trace provenance, diagnose, audit |
-| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
+## Truth documents
 
-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.
+- **Intent and promises; facts are the graph's.** An owning document (feature, package, system) says why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact (a table's columns, which function writes which column, which route sits behind which guard, which file holds what) is the code's, and a hand-typed copy is wrong the day the code moves. `doc-lint` blocks the retired mechanism sections (`mechanism-section`) and an owning document with no `objects:`.
+- **Read by people, pointed at by the footer.** Sharp bullets under noun-phrase headings, each a bold label, a colon, one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam; every other pointer in the closing **For the agent** footer (style guide § Owning documents — the body and the footer).
+- **The stability test.** A sentence that would change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document on *why* (style guide § Shape).
+- **Unbuilt work has one home per kind.** Decided design the code does not yet do sits in the body, wrapped in an `UNBUILT` marker; a shortfall in what is built is one bullet under Gaps; the work that would close either is a backlog row, which the document never tracks (style guide § The stability test).
+- **No empty stubs.** Omit a section with nothing real to say. Write "None" only where the absence is itself information, such as a plan's Cross-Module Contracts Affected.
+- **No redirect documents.** Moving a document deletes the old file and repoints every inbound link; a "Moved to X" stub rots and creates false search hits.
 
-- **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.
-- **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 the `maintenance` agent's **Health Log** lives in `docs/history/health-log.md`, an append-only record. The AD body stays current-truth-only; the tail carries the dates. No other truth document carries dated history. `docs/structure.md` is harness-owned — written whole by the installer, never edited by hand or by a skill; only its `harness-version` frontmatter is stamped, by the `maintenance` agent.
-- **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
-- **Every document describes itself.** Its frontmatter carries `description:` — at most 300 characters, one or two present-tense sentences saying what the document settles and where its boundary sits (`references/frontmatter.md` § `description:`). That is the per-file account an index would otherwise keep, so an index names no file and no record: not a link, not a filename, not an ID row such as `AD-010`. A folder is browsed with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a truth document or folder index without one (`description-missing`), one over 300 characters (`description-length`), and an index row that names a file or record (`index-names-records`).
-- **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.)
+### Indexes and descriptions
 
-**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).
+- **Every document describes itself** in its `description:`, so a folder is browsed with `grep -m1 '^description:' <folder>/*.md` and no index keeps a row per file.
+- **A folder's `Readme.md` describes the folder:** what it holds, who reads it, how its files are named. No file list, no tree (`docs/structure.md` holds the one tree), no record IDs such as `AD-010`. Nothing appends to an index when a sibling file is added; the changelog guide, `docs/history/CHANGELOG.md`, is no exception.
+- **The links an index may carry:** a sibling folder's `Readme.md`, the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `history/journal.md`, `history/health-log.md`, `memory/main.md`), and the root `CLAUDE.md` and `AGENTS.md`. `doc-lint` blocks the rest under `docs/` as `index-lists-files`, a drawn tree as `index-file-tree`, a named file or record as `index-names-records`.
+- **Routing documents point at truth.** A "read first" row names the topic's truth document, never a plan or changelog entry. An index of the records themselves (a History section naming `plans/` and `changelog/`) is sanctioned.
 
-**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document is the authority on *why*, and a disagreement on *why* is a defect to raise. **Every heading and every bold bullet label is a noun phrase** — it names; it has no verb, so it carries no tense, person or voice ("Decisions", never "What was decided"; "Organization user:", never "You already belong to an organization:"), and the sentence after it is third person ("user lands…", never "you land…"). The layers, the test, the label rule and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after, and § Labels.
+### Ownership today
 
-**No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
-
-**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
+A document names the objects it designs in `objects:`, and a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge today: the transitional `owns:` region glob on each feature, package, system and surface-owning UX document, the narrower glob winning. Write the header pointer anyway, so the scan can switch to it and to the object closure without a second pass over the code. Where a repository has no `docs/architecture/systems/knowledge-layer.md`, this skill and `references/frontmatter.md` are the whole authority on document–code edges. `docs/structure.md` is harness-owned: the installer writes it, and the `maintenance` agent stamps only its `harness-version`.
 
 ---
 
@@ -89,99 +88,49 @@ The two guarantees are complementary and both break on mixing: a reader holding
 
 | 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 |
-| Document a workspace package (`docs/architecture/packages/{package}.md`) | [`templates/package.md`](templates/package.md) — the **residual** owner of `packages/{name}/**`: its manifest, build, entry, layout and every behavior no system or feature doc claims at higher specificity |
-| Document one concern the platform handles everywhere (`docs/architecture/common/{concern}.md`) — authentication, storage, the API protocol | [`templates/doctrine.md`](templates/doctrine.md) — the design and its principles, no mechanism; owns no code, and the surfaces bound by it are the ones that design or touch the objects it governs |
-| Document one system spanning packages (`docs/architecture/systems/{system}.md`) | [`templates/system.md`](templates/system.md) — one machine end to end, the objects it owns or moves. Not a screen — a system doc written as a giant feature doc is the mistake it prevents |
-| Create/update changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record — one per unit of work; carries the refinement fields, frozen inside its commit, distilled by the `retro` agent) |
-| 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) |
-| What a person sees and can do on a surface (UX behavior) | [`templates/ux-behavior.md`](templates/ux-behavior.md) — decides observable behavior BEFORE the code; per-surface in `docs/features/{surface}-ux.md` owning the component globs, cross-cutting in `docs/architecture/`. Not the checklist, which only verifies it |
-| Behavioral checklist for one feature (`docs/tests/{feature}.md`) | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md) — the verification gate's driving script, and the source its suite tests are drawn from |
-| Acceptance criteria for one capability (`docs/acceptance/{capability}.md`) | [`templates/acceptance-criteria.md`](templates/acceptance-criteria.md) — the promises the built product must keep, as stable `AC-n` keyed assert lines verification surfaces parse as claims |
-| Machine setup / first run / stack (one per repo, `docs/operations/setup.md`) | [`templates/setup.md`](templates/setup.md) |
+| Baseline / reconcile docs | `maintenance` agent (baseline mode); it calls this skill per template |
+| Document a feature (LLD) | [`templates/feature.md`](templates/feature.md) |
+| Document a feature's data flow or state | The feature doc's Flows (behaviour) and Promises (guarantees); a persisted shape belongs in the API reference (style guide § State at persistence points); component and transient state are not documented |
+| Document a workspace package | [`templates/package.md`](templates/package.md), the residual owner of `packages/{name}/**` |
+| Document one concern the platform handles everywhere (authentication, storage, the API protocol) | [`templates/doctrine.md`](templates/doctrine.md): design and principles, no mechanism, owns no code |
+| Document one system spanning packages | [`templates/system.md`](templates/system.md): one machine end to end, never a giant feature doc |
+| Record or revise an architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md): one AD per subject, revised in place |
+| Create or update a changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record; frozen inside its commit; no row in `CHANGELOG.md`) |
+| Create or update a plan | [`templates/plan.md`](templates/plan.md) (record) |
+| Steering docs: system overview, domain model, glossary, non-goals, security, testing strategy | The registry row's template |
+| Catalog the API surface / the environment variables | [`templates/api-reference.md`](templates/api-reference.md) / [`templates/environment-registry.md`](templates/environment-registry.md) |
+| What a person sees and can do on a surface | [`templates/ux-behavior.md`](templates/ux-behavior.md): decides observable behavior before the code; not the checklist, which only verifies it |
+| Behavioral checklist for one feature | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md): the verification gate's driving script |
+| Acceptance criteria for one capability | [`templates/acceptance-criteria.md`](templates/acceptance-criteria.md): stable `AC-n` lines |
+| Machine setup, first run, stack | [`templates/setup.md`](templates/setup.md), one per repo |
 | Recurring procedure (develop, deploy, rotate, diagnose) | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
-| Cold-start build order (implementation map) | [`templates/implementation-map.md`](templates/implementation-map.md) — authored by the executing session at build start, updated in place as waves complete |
-| Capture mid-execution knowledge (`docs/history/journal.md`) | [`templates/journal.md`](templates/journal.md) (record — append-only; a row resolves by landing in its owning doc) |
-| Bookkeeping work queue (`docs/operations/bookkeeping.md`) | [`templates/bookkeeping.md`](templates/bookkeeping.md) — machine-read row grammar; appended by hooks and sessions, drained by the `bookkeeper` agent, walled at Stop and commit |
-| One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
-| Hand-over at the end of an unattended or multi-session build (`docs/history/handovers/YYYY-MM-DD-{slug}.md`) | [`templates/handover.md`](templates/handover.md) (record) — a decision queue, an undo manual and a resume file: a verdict token and scoreboard, the acts only the owner can take today, everything that left the repository with its exact undo, a ten-minute path to seeing it work, every ruling taken on the owner's behalf with its authority and how to overturn it; then the successor half — proof, state re-provable by command, open loops, discoveries |
-| Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
-| Create/update root README (outward opening in a user's terms, then orientation and routing for the team and agents — no install, stack, tree or chrome) | [`templates/root-readme.md`](templates/root-readme.md) |
-| Scaffold a standard doc (docs index, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file; `structure.md` is the installer's, never scaffolded |
-| Derive or update a document's frontmatter (`objects:`, the header pointers, the transitional `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) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
-| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/playbooks/skills/`, chapters `00`–`13`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
-| **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 objects it designs changed, update `objects:`, and remove any retired key on the way through ([`references/frontmatter.md`](references/frontmatter.md)).
-
----
-
-## Naming & Lifecycle
-
-| Document | Nature | Name | Lifecycle |
-| --- | --- | --- | --- |
-| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
-| Package | Truth | `{package-folder}.md` | Living; `status:` as the feature doc |
-| System | Truth | `{machine}.md` | Living; `status:` as the feature doc |
-| Doctrine | Truth | `{concern}.md` | Living; `status:` `draft` → `active` |
-| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
-| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
-| API reference / environment registry | Truth | fixed names | Living |
-| Operations procedure | Truth | `kebab-case.md` | Living |
-| Protected files | Truth | `protected-files.md` | Living |
-| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
-| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
-| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
-| Research | Record | in progress: `docs/research/{topic}/` · harvested: `docs/history/brainstorms/{topic}/` | Frozen at harvest |
-| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
-
----
-
-## Frontmatter
-
-**Frontmatter is compulsory on every document this skill authors**: `type:` (the genre) on every document, plus its genre's keys. There is no frontmatter-less genre. The keys follow the knowledge layer (`docs/architecture/systems/knowledge-layer.md` § Documents and code), and this skill stays in step with it:
-
-- **`objects:` is a document's edge into the graph:** the product objects it designs, by their register names. Feature, system, package, doctrine and UX documents carry it, with `type:` and `status:`; a feature may add `module:`.
-- **The code's edge is the source file's header pointer:** authored on the code's side, naming the document that holds the file's fuller account. Which document speaks for a path is computed from the pointers and the object closure, never typed into the document.
-- **`owns:` is transitional:** region globs only, kept solely because the harness's ownership scan still reads it, and removed everywhere in the change that switches the scan. Never a list of files.
-- **`applies:` is retired:** a document's governing doctrine is computed through the objects both name, and its Scope section names it for people.
-- **`verifies:` stays on a behavioral checklist:** the document whose promises it proves.
-
-Keys by genre, each key's rules, the retired keys, and the one rule the graph rests on (declare once, at the consuming end; generate every inverse) are [`references/frontmatter.md`](references/frontmatter.md). Every document create or update, and the `maintenance` agent's baseline pass, route there.
+| Cold-start build order | [`templates/implementation-map.md`](templates/implementation-map.md), written by the executing session at build start |
+| Capture a mid-execution fact / log doc-sync debt / log open work | [`templates/journal.md`](templates/journal.md) / [`templates/bookkeeping.md`](templates/bookkeeping.md) / [`templates/backlog.md`](templates/backlog.md) (queues) |
+| One-shot migration | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
+| Hand-over at the end of an unattended or multi-session build | [`templates/handover.md`](templates/handover.md) (record) |
+| Protected files | [`templates/protected-files.md`](templates/protected-files.md) |
+| Root README | [`templates/root-readme.md`](templates/root-readme.md): outward opening, then orientation and routing |
+| Scaffold a standard doc (docs index, changelog guide, backlog, memory) | The registry's § Baseline scaffolds |
+| Frontmatter keys (`objects:`, `verifies:`, the transitional `owns:`) | [`references/frontmatter.md`](references/frontmatter.md) |
+| Source-file comments: what stays, what moves to a doc, proving a sweep | [`references/source-comments.md`](references/source-comments.md) |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md): every-load prose stays lean; the present-tense rule still applies |
+| Author or restructure a skill | The skill-authoring field guide in the etna repo (`nurixlabs/etna`), `docs/playbooks/skills/`. No etna checkout ⇒ ask the user for access, or proceed from first principles with `references/instruction-style.md` governing the prose |
+| No template matches | [`references/untemplated.md`](references/untemplated.md) |
 
 ---
 
 ## Resources
 
-| File | Use For |
+| File | Use for |
 | --- | --- |
-| `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` | The writing-style authority: the eight principles, depth per genre, the outside-in shape and stability test, noun-phrase labels and third-person voice, the owning document's body and footer, the two-natures tense rules, diagrams, headings, reference-document detail |
-| `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
-| `references/frontmatter.md` | Frontmatter by genre, in step with the knowledge layer: `objects:`, the header pointer, the transitional `owns:`, the retired `applies:`, `verifies:` |
-| `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 |
-| `scripts/source-lint.mjs` | Mechanical checks over source **comments** (header path identity, the added-line comment ratio, narration, shouting) — run `--changed` before finishing any change that writes source |
-| `scripts/comment-strip.mjs` | The proof a comment sweep changed no executable code: strips comments from two revisions and diffs what is left. Exit 0 is the claim; exit 1 names the file and the first diverging line |
+| `templates/Readme.md` | The genre registry: every genre's nature, `type:`, location, required keys and sections; `doc-lint` reads it |
+| `templates/` | One template per genre the registry names |
+| `references/style-guide.md` | The prose authority: the eight principles, depth per genre, the outside-in shape and stability test, labels and voice, owning documents, tense, diagrams, reference documents |
+| `references/frontmatter.md` | Each frontmatter key's rules, the transitional `owns:`, the retired keys |
+| `references/instruction-style.md` | The style for instruction files |
+| `references/untemplated.md` | Writing a document no template covers, and co-authoring one with a person |
+| `references/source-comments.md` | Source-file comments, and the scripts that check them |
+| `references/examples.md` | Good and bad documentation, side by side |
+| `scripts/doc-lint.mjs` | Mechanical checks over written docs: tense and history, dates, redirect stubs, frontmatter, the registry's keys and sections, index shape, owning-document body |
+| `scripts/source-lint.mjs` | Mechanical checks over source comments; run `--changed` before finishing any change that writes source |
+| `scripts/comment-strip.mjs` | Proof that a comment sweep changed no executable code |

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

@@ -6,7 +6,7 @@ Good vs bad examples showing the key differences.
 
 ## Example 1: Function Documentation
 
-### ❌ Bad: Full Implementation
+### Bad: Full Implementation
 
 ```markdown
 ### mergeData
@@ -16,7 +16,7 @@ function mergeData(server, local, changes) { const result = {}; const serverMap
 
 **Problems:** Will become obsolete, focuses on HOW not WHAT.
 
-### ✅ Good: Contract Only
+### Good: Contract Only
 
 ```markdown
 ### `mergeData(serverData, localData, changes)`
@@ -42,7 +42,7 @@ function mergeData(server, local, changes) { const result = {}; const serverMap
 
 ## Example 2: State Documentation
 
-### ❌ Bad: State Everywhere
+### Bad: State Everywhere
 
 ```markdown
 ## Component State
@@ -60,10 +60,12 @@ const [items, setItems] = useState([]);
 
 **Problems:** Documents transient state, repeats shapes.
 
-### ✅ Good: Persistence Points Only
+### Good: Persistence Points Only, in the API reference
+
+Persisted shapes live in the API reference (`docs/architecture/api.md`), never in a feature document, where `## State` is a retired mechanism section.
 
 ```markdown
-## State
+## Persisted shapes — items
 
 **Frontend (at persistence):**
 
@@ -87,7 +89,7 @@ export const items = pgTable('items', {
 
 ## Example 3: Changelog
 
-### ❌ Bad: Vague
+### Bad: Vague
 
 ```markdown
 # 2025-01-05 - Updates
@@ -103,52 +105,25 @@ export const items = pgTable('items', {
 - Various files in src/
 ```
 
-### ✅ Good: Function-Level Detail
+### Good: Behavior First, Refinement Context Kept
 
 ```markdown
-# 2025-01-05 - Version-Based Merge
-
-## Summary
-
-Replaced change-tracking merge with version-based conflict resolution.
-
-## Changes
-
-### Added
-
-- `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
-  - Purpose: Single-pass merge with change detection
-  - Returns: `{ merged, changes }`
-
-### Changed
-
-- `useDataSync()` in `src/hooks/useDataSync.js`
-  - Changed: Now compares versions before merge
-
-### Removed
-
-- `deriveChanges()` from `src/utils/derive.js`
-  - Replaced by: Logic in `mergeAndDerive()`
-
-## Breaking Changes
-
-⚠️ **Merge behavior changed**
-
-- Old: Local changes always preserved
-- New: Local preserved only if versions match
-
-## Files Changed
-
-- `src/hooks/useDataSync.js`
-- `src/utils/merge.js`
-- `src/utils/derive.js` (deleted)
+# 2025-01-05 · data-sync — Local edits survive a sync only when versions match
+
+- **Ask:** "stop silently overwriting my offline edits — I'd rather see a conflict than lose work"
+- **Iterations:** 2 · rejected: last-write-wins by timestamp, because device clocks drift and the newer-looking write lost real edits
+- **Skills:** documentation@3.18.0 — survived
+- **Change:** sync now keeps a local edit only when its base version matches the server's, and surfaces a conflict otherwise, because a stale local copy was overwriting newer server state. Merge and change detection run in one pass (`mergeAndDerive`)
+- **Discovered:** two tabs on one device share a version counter, so a conflict between them never surfaces [source: runtime-discovery]
+- **Class:** data · resilience
+- **Pin:** `tests/sync/merge.test.ts` — version-mismatch keeps the server copy and reports the conflict
 ```
 
 ---
 
 ## Example 4: Flow
 
-### ❌ Bad: Mechanism narrated in a paragraph
+### Bad: Mechanism narrated in a paragraph
 
 ```markdown
 ## Data Flow
@@ -158,12 +133,12 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 
 **Problems:** names a hook, a function and a store that a rename would invalidate (the stability test); runs parallel cases together in one paragraph; gives a scanning reader no label to land on; "Data Flow" is a retired mechanism section.
 
-### ✅ Good: Labelled bullets, a role-level diagram beside them
+### Good: Labelled bullets, a role-level diagram beside them
 
 ````markdown
 ## Flows
 
-### Page load
+### Page load — item sync
 
 - **Fresh data:** the page fetches the server's copy and the local copy on every load; nothing is cached between visits.
 - **Matching versions:** local changes win and are kept.
@@ -186,7 +161,7 @@ sequenceDiagram
 
 ## Example 5: Architecture Decision revision
 
-### ❌ Bad: Supersession chain
+### Bad: Supersession chain
 
 ```
 docs/architecture/decisions/
@@ -197,7 +172,7 @@ docs/architecture/decisions/
 
 **Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
 
-### ✅ Good: One subject, updated in place
+### Good: One subject, updated in place
 
 ```
 docs/architecture/decisions/
@@ -228,7 +203,7 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 
 The move agents fumble: deleting narration is only half the job — the story must land in a record.
 
-### ❌ Bad: The journey narrated in place
+### Bad: The journey narrated in place
 
 ```markdown
 ## Export Pipeline
@@ -239,7 +214,7 @@ 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
+### Good: Present-tense truth doc + a dated record carrying the story
 
 The feature doc states only what is:
 
@@ -253,17 +228,15 @@ 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.
+# 2026-06-02 · export — Export runs as its own pipeline, outside the reports worker
+
+- **Ask:** "exports shouldn't stall the reports queue"
+- **Iterations:** 1 · rejected: none
+- **Skills:** none used
+- **Change:** export jobs run in their own pipeline under `src/export/`, so a slow export no longer holds a reports slot; every caller of the old worker entry is repointed
+- **Discovered:** none
+- **Class:** architecture · performance
+- **Pin:** none — candidate: a queue test that a long export leaves report jobs flowing
 ```
 
 **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.
@@ -277,7 +250,7 @@ Extracted export logic from the `reports` worker into `src/export/`.
 | Code       | Full implementations | Signatures + contracts      |
 | State      | Every occurrence     | Persistence points only     |
 | Flows      | Paragraphs naming functions | Labelled bullets in plain words, a role-level diagram beside them |
-| Changelogs | "Updated X"          | Function names + migrations |
+| Changelogs | "Updated X"          | Behavior first, then the ask, rejections and what running it taught |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
 | History    | Narrated in the doc  | Present-tense doc + dated record |
 | Length     | Padded with mechanism | The genre's own expectation; length is a signal, never a target |

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

@@ -2,11 +2,11 @@
 
 Load when: creating a document that carries frontmatter, updating one whose subject moved, or running a baseline or reconcile pass over many documents.
 
-This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect.
+This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect; where a repository carries no such design, this file is the authority.
 
 ## The model
 
-A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document.
+A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document. The harness's ownership scan reads one edge today, the transitional `owns:` region glob (§ `owns:`); principles 2 and 3 are the edges it switches to, and the header pointer is written now so the switch needs no second pass over the code.
 
 ### Principles
 
@@ -30,14 +30,14 @@ A document names the product objects it designs. Every other edge between a docu
 | Acceptance criteria | `type`, `description`, `status` |
 | Every other genre | `type`, `description`, plus its template's own keys |
 
-Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), and `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal). Sessions preserve them on edits and never narrate or inject them. The `maintenance` agent stamps `type:` where it is missing.
+Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal), `last-updated:` (an Architecture Decision's revision stamp, bumped with each Decision Changelog entry) and `harness-version:` (stamped on `docs/structure.md` by the `maintenance` agent). Sessions preserve them on edits, stamp `last-reviewed:` and `last-updated:` where their genre says so, and never narrate them. The `maintenance` agent stamps `type:` where it is missing.
 
 ## Keys
 
 ### `description:`
 
 - **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
-- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry's one-line summary is its row in `CHANGELOG.md`). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole; `docs/operations/bookkeeping.md`, which the hooks write from a fixed header; and a tree a generator owns (`docs/dna/`, the product-dna skill's). A release note under `docs/operations/release-notes/` is a record, frozen at publication.
+- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry has none: its heading line is its summary). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole; `docs/operations/bookkeeping.md`, which the hooks write from a fixed header; and a tree a generator owns (`docs/dna/`, the product-dna skill's). A release note under `docs/operations/release-notes/` is a record, frozen at publication.
 - **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
 - **Upkeep:** an edit that changes what a document settles updates its description in the same edit.
 
@@ -50,7 +50,7 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 ### `status:`
 
-- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents.
+- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents. An Architecture Decision keeps its own lifecycle, `Proposed`, `Accepted` or `Deprecated` (`templates/architecture-decision.md`).
 
 ### `module:`
 
@@ -72,8 +72,8 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 | Key | Retired because | What replaces it |
 | --- | --- | --- |
-| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section names its governing doctrine and what each settles |
-| `keywords:` | An object's name and aliases are its discovery terms | `objects:` |
+| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section (a UX document's Purpose) names its governing doctrine and what each settles |
+| `keywords:` | An object's name and aliases are its discovery terms | `objects:`. The ownership scan still shows a document's `keywords:` in the index when it names no `objects:`, so removing the key without adding `objects:` empties that entry |
 | A file-level `owns:` list | The header pointers and the object closure compute it | Region globs only, until the scan switches (above) |
 
 An edit to a document that carries a retired key removes the key in the same edit.