@nurix/etna 0.20.26 → 0.20.27

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

@@ -1,115 +1,195 @@
+<!-- doc-lint-disable: date-in-truth-doc, history-narration, stale-tripwire, progress-marker, temporal-hedge, predecessor-frame, status-glyph -->
+<!-- reason: the style authority quotes the forbidden constructions verbatim in its ❌ columns; each match is an example of what not to write. -->
+
 # Documentation Style Guide
 
-Writing rules for clear, maintainable documentation.
+This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it. [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean; each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections of this guide are enough to write a correct document; the sections after them are the detail each principle unfolds into, and a reader who stops early holds a coarse picture that is still true.
 
----
+## The model
 
-## Function Documentation
+A document is read by a person who wants to understand something or to act on it, and it is scanned more often than it is read. Every rule below follows from eight principles; later sections cite them by number.
 
-### Signature Format
+### Principles
 
-```markdown
-### `functionName(param1, param2, options)`
+1. **Two natures:** every document is a truth document (what is, now, rewritten in place) or a record (what happened, dated and frozen). A truth document never narrates history and a record is never edited to match the present, because a reader must be able to trust each without the other.
+2. **The outside-in shape:** an explaining document opens on the question it answers and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser the next section completes.
+3. **The stability test:** a sentence that would have to change when a function is renamed, a file moves, a route, column, error code or cookie attribute changes, or a constant is retuned without the design changing belongs to the code, which the code graph computes on demand (`docs/architecture/systems/knowledge-layer.md`), and not to the document. A copy typed into a document is at best a duplicate of the code and at worst a stale one.
+4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose.
+5. **Noun-phrase labels, third-person sentences:** every heading and every bold bullet label names something and contains no finite verb, so it carries no tense, person or voice. The sentence after a label is third person, present tense, active, with the actor as its subject.
+6. **A body scanned by people, a footer for the agent:** an owning document is bullets under noun-phrase headings, tables wherever the cases are parallel states, code named only where a person types or sees it or at a cross-cutting seam, and a closing "For the agent" footer that holds pointers, never an inventory.
+7. **Self-contained, never padded:** the body reads whole without opening another file, restating the one sentence of context a borrowed concept needs and citing the authority for the rest. Length is a signal of a document that has let mechanism in, never a target.
+8. **Depth per genre:** doctrine stops at decisions and reasons, a system at behaviour across packages, a package at its public contract, a feature runs deepest at its end in Promises, and a reference document or runbook keeps full detail because the detail is its content.
 
-**Goal:** One-line purpose
+## The genres
 
-**Input:**
+Every genre takes the same shape (principle 2) and the same labels (principle 5); what differs is how deep it may go.
 
-- `param1` (type) - Description
-- `param2` (type, optional) - Description
+| Genre | Nature | Deepest layer | Excluded |
+| --- | --- | --- | --- |
+| Doctrine (`docs/architecture/common/`) | Truth | The decisions behind each part and the reasons for them | Any mechanism. A doctrine document describes no code |
+| System (`docs/architecture/systems/`) | Truth | The machine's behaviour across packages: the order it runs in, sequence and state diagrams at role level, the invariant at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps, tables and columns, routes |
+| Package (`docs/architecture/packages/`) | Truth | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout, the build's steps, which file holds what |
+| Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |
+| Reference (API reference, environment registry) | Truth | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
+| Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point |
+| Record (plan, changelog entry, journal, memory) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
 
-**Output:** `{ field1, field2 }`
+- **Owning documents:** feature, package and system are the three genres that carry `owns:`. They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them.
+- **Doctrine:** the same shape and labels as an owning document, with no `owns:` and no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
+- **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents).
+- **Indexes:** a folder's `Readme.md` describes directories, never files; the root README follows `templates/root-readme.md`. Both take § Labels.
 
-**Side Effects:** State updates, API calls, etc.
-```
+## Shape — the model first, the detail after
 
-### Parameter Rules
+Every truth document a person reads to understand something is written from the outside in (principle 2). The failure this prevents is a document written at one density from its first word: an inventory table before the reader knows what is being inventoried, and the principles that summarize it arriving last, where nobody reads them.
 
-- Name + type + one-line purpose
-- Mark optional params with `(type, optional)`
-- Nest object properties:
-  ```markdown
-  - `options` (object) - Configuration
-    - `options.retry` (boolean) - Enable retries
-    - `options.timeout` (number) - Timeout in ms
-  ```
+### The layers
 
-### Return Values
+1. **The question and its boundary:** the first paragraph says what question this document answers, and which neighbouring documents answer the questions next to it. No addresses, file paths or configuration in it.
+2. **The model:** what the thing is, in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere, numbered, each with its reason, so later sections cite them ("principle 3").
+3. **The parts:** one table or diagram placing every part in the model, then how the parts relate: what they share, where they meet, what keeps them apart.
+4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with why the part exists, never with how it is built.
+5. **The genre's deepest layer:** the row for the genre in § The genres, and nothing deeper.
 
-Always specify:
+### The stability test
 
-- Type: `Array<Object>`, `boolean`, `{ merged, changes }`
-- Shape for objects/arrays
-- Meaning: "True if sync successful"
+The test (principle 3) decides what a sentence may say. These survive it:
 
----
+- **Reasons:** why the design is this way, and what would break otherwise.
+- **Invariants:** what must hold everywhere.
+- **Decisions:** the choice made, and the alternative a reader would reach for.
+- **Promises:** what a person or a test can check.
+- **Cross-component contracts:** what no single file shows, such as two clients that must classify the same answer identically.
+- **Decided-but-unbuilt intent:** what the code cannot reveal because it does not yet do it, wrapped in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->` in plain words. A design decided *against* carries no marker.
 
-## State Documentation
+The authority split (principle 4) is stated in the opening of any document whose readers include agents, so a reader who finds the code and the document disagreeing knows which way to resolve it.
 
-### When to Document State
+### Diagrams and length by layer
 
-✅ Do:
+- **A diagram's layer:** at the model and parts layers a diagram names roles ("the browser", "the auth service"), never a URL, a header or a file. A diagram drawn from the code's names belongs to the code graph.
+- **Length as a signal:** a document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about three hundred lines has usually let mechanism in; the per-genre expectations are each template's.
 
-- Redux persistence (localStorage, IndexedDB)
-- Database schemas
-- API request/response shapes
+## Labels
 
-❌ Don't:
+A heading, and the bold label that leads a bullet, is a noun phrase (principle 5). It names something. It never contains a finite verb, so it carries no tense, no person and no voice; the sentence that says what happens comes after the label, never inside it.
 
-- Component-level state
-- Derived/computed state
-- Temporary UI state
+A clause used as a label is the recurring defect. Once a label has a verb it has to pick a tense ("What *was* decided" is past tense in a present-tense document), a person ("*You* already belong…") and a voice ("was decided" is passive). A noun phrase has none of these, so it cannot be wrong in any of them.
 
-### Format
+| ❌ Clause | Grammar | ✅ Noun phrase |
+| --- | --- | --- |
+| "How it works" | wh-clause, present tense | Flows |
+| "What was decided" | wh-clause, passive voice, past tense | Decisions |
+| "What it promises" | wh-clause | Promises |
+| "Why it exists" | wh-clause | Scope, or nothing: its content is a decision |
+| "Where a person lands" | wh-clause, third person | Landing |
+| "Asking who you are" | gerund clause, second person | Identity check |
+| "You already belong to an organization:" | declarative sentence, second person | Organization member: |
+| "Run `nustack login`." | imperative sentence | `nustack login`: |
+| "NuStack checks identity; it does not own it" | two declarative clauses | Identity: checked, not owned |
+
+- **Format:** `**Label:** sentence`. The bold label ends in a colon, then one or two plain sentences follow: "**Dead grant:** the stored item is deleted, and the person is prompted to sign in."
+- **The label's job:** it names the case, the thing or the decision; the sentence says what happens. "**Unclaimed domain:** user gets a private organization…", never "**Nobody claims your domain:** …".
+- **Reach:** the rule applies at every depth: `##`, `###` and `####` headings, table header cells, and the bold lead of every bullet or numbered item, in every document this guide governs.
+- **Exemptions:** the goal line and running prose are full sentences. A heading whose text is itself the checkable claim (a behavioural checklist's section, an acceptance criterion) is content, not a label, and keeps its sentence, because the assertion is what the reader came for.
+- **Lint:** `doc-lint` warns `clause-label` on a heading or bold label in an owning or doctrine document that opens with a wh-word or a personal pronoun, or that ends in a full stop.
+
+## Voice
+
+The sentence after a label, and every sentence of running prose, describes the product to whoever reads it; it does not address the reader.
+
+- **Person and tense:** third person, present tense, active voice. The subject is the actor (user, machine, CLI, server, the organization): "**Organization user:** user lands in their existing organization", never "you land in the organization you already belong to". `doc-lint` warns `second-person` on "you" or "your" outside quoted copy, in an owning or doctrine document.
+- **Quoted interface copy:** keeps its own wording, including its "you", because the product does address its user. Quote it exactly, in quotation marks.
+- **Concision:** "Merges server data with local changes by version", never a sentence that restates its own subject twice. A function or a command is described by what it does ("Fetches data from the server", "Returns an array"), never by what it "is used to" do and never in the passive ("an array is returned").
+- **Bold:** marks a bullet's label or a defined term's first appearance, never a noun mid-sentence.
+- **Em-dash:** a budget of one per paragraph, never a joint between clauses.
+- **Terms of art:** introduced in plain words the first time they appear, the term itself in parentheses where a reader will meet it elsewhere.
+- **Inline code:** every identifier, filename, command, flag, environment variable and config key a document names is in backticks. Where a document may name code at all is § Owning documents — the body and the footer and § Reference documents.
+- **Decoration:** ❌ / ✅ only inside banned/blessed lists and comparison tables, never as general decoration; no emoji in headings.
+
+## Owning documents — the body and the footer
+
+A feature, package or system document is scanned more than read (principle 6). It takes the shape (§ Shape — the model first, the detail after) and the labels (§ Labels) above, and these rules.
+
+### Sections
+
+| Genre | Sections, in order |
+| --- | --- |
+| Feature | Goal line · Scope · Flows · Decisions · Promises · Gaps · For the agent |
+| System | Opening paragraph (the machine defined) · Scope · Flow · Decisions · Promises · Gaps · For the agent |
+| Package | Identity line · Goal line · Scope · Ownership · Usage · Decisions · Promises · Gaps · For the agent |
 
-````markdown
-**Frontend (at persistence):**
+Nothing else. "Why it exists" is retired; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
 
-```json
-{
-  "activeField": "value"
-  // "deprecated": null  // UNUSED: dead key; kept so old persisted state rehydrates
-}
-```
+### The body
 
-**Storage:** localStorage key `state_key`
+- **The opening:** the goal is the first paragraph under the title, after the one identity line a package carries. No plan link and no routing line above it.
+- **Bullets:** each section is bullets under a noun-phrase heading; each bullet is a bold noun-phrase label, a colon, then one or two plain sentences saying what happens, what is decided or what is promised.
+- **Tables:** a table replaces the bullets wherever the cases are parallel states, such as each refusal and the exact message it shows. Its header cells are noun phrases.
+- **Paragraphs:** right for the goal, for a system's opening definition, and for a doctrine's model that needs an argument. Everywhere else, a paragraph is bullets that have not been cut yet.
+- **Code in the body:** named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to from the feature's own files: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Written once, by name, where the narrative leaves the feature. Everything else is a plain name: "the device registry", "the sign-off page", "the mirror". `doc-lint` warns `body-identifier` past three identifiers in a section.
+- **Flows:** describe behaviour, never mechanism. A flow bullet says that a forgotten machine comes back on its next call, never which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's.
+- **Promises:** the deepest section of a feature document: every state, edge case and refusal, and the exact wording where the wording is promised, each checkable by a person or a test. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+- **Gaps:** a gap the code does not close is one bullet under Gaps, or a backlog row. It is never a ledger row inside another section, and never a temporal hedge.
 
-**Backend:**
+### The footer
 
-```ts
-export const table = pgTable('table', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-  // old: text('old'),  // UNUSED: dead column; nothing reads it
-});
-```
-````
+"For the agent" is a set of pointers, never an inventory. It holds four things:
 
-### Mark Unused Keys
+1. **Objects:** each with a one-line definition.
+2. **Code roots:** directories where the graph should start.
+3. **Seams:** the cross-cutting seams, by name.
+4. **Checklist and neighbours:** the checklist, and the neighbouring documents with a purpose for each.
 
-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):
+A feature adds its pages, because an address is what a person points at; a package adds its commands, because those are its public contract. Tables, routes, symbol rosters and file lists belong in the footer no more than in the body; the footer obeys the stability test like every other line, and a footer that grows with every function is the inventory moved down the page.
 
-```json
-{
-  "active": [],
-  // "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility
-}
-```
+## The Two Natures — tense and history
 
----
+Every document is a truth document or a record (principle 1); `SKILL.md` § The Two Natures gives the split, the folders and the lifecycle. The tense rules follow directly.
 
-## ASCII Diagrams
+- **Truth documents:** everything outside `docs/history/`, `docs/research/` and `docs/memory/` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records.
+- **The one bridge:** an Architecture Decision's **Decision Changelog** tail carries that decision's dated revision history while its body stays current-truth-only; head is truth, tail is provenance. No other truth document carries a dated line, apart from the frontmatter's tooling keys and a dated path inside a link or code span, which cites a record rather than claiming a date. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail.
+- **Records:** 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.
 
-### When to Use
+| ❌ Historical narration (a record's) | ✅ Present-tense fact (the truth document's) |
+| --- | --- |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "Built 2026-06-14; shipped + verified 2026-06-13." | "The session runs as an outer loop of turns over the agent loop." |
+| "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets every workflow definition." |
+| "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "The MCP client runtime, started by the agent trigger." |
+| "Build Sequence phases 0–4 are complete." | Nothing; progress lives in the plan or backlog record |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing; delete or repoint the stale references and state only the present design |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
+
+- **Dates and progress:** nothing about *when* something shipped, was verified, folded or was removed, and no completion markers: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a record's job (the plan, the backlog). `doc-lint` blocks `date-in-truth-doc`, `history-narration` and `progress-marker`, and warns `status-glyph`.
+- **Stale-reference tripwires:** never "X is gone — treat references to X as stale"; that is a redirect document compressed into one sentence. Delete or repoint every stale reference instead (`stale-tripwire`, and `redirect-doc` for the file-sized version).
+- **Version and phase framing:** no bare `v1`/`v2` label, no "Phase 1/2", no "the old X", no "supersedes the earlier". There is one design; describe it without its predecessors (`predecessor-frame`). 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:** "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 (`temporal-hedge`).
+- **A published artifact's version surface:** release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`), because that is the artifact's public contract. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`.
+- **Record citations:** by what the record is, never by when it was. `Provenance: AD-002` points to the decision rationale; "decided in AD-002 and shipped 2026-06-13" states a date the reader must now carry. `the dev reset runbook` links to the file; "the 2026-09-13 reset" goes stale at the second reset.
+- **Routing and index documents:** point only to truth documents as a topic's authority. A "read first" row whose target is a plan or changelog entry is a redirect-for-history; repoint it or drop it. An index *of the records themselves* (a History section listing `plans/`, `changelog/`) is sanctioned.
+- **A changed system:** the change-story goes to `docs/history/` as a changelog entry, and the truth document simply becomes correct in present tense. The diff is never narrated in place.
+- **A moved decision:** an edit, never a new document. The AD's affected sections are rewritten to the new truth and the revision appended to its Decision Changelog; no parallel document, no old choice narrated in the body.
+
+Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
+
+## Self-contained documents and the link surface
+
+Instruction files stay lean because an agent pays for them on every load (`instruction-style.md`); a document is read on demand, so it carries what its reader needs to understand the page (principle 7).
 
-- Data flows
-- System architecture
-- Component interactions
-- Process flows
+- **Completeness:** the one or two sentences of context a borrowed concept needs are restated where it is used, because a reader forced mid-paragraph into a second document loses the thread of the first.
+- **Restatement and citation:** a changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
+- **Inline links:** the minimum that action requires. A link mid-prose is right only where the reader must go there to act on this page, which includes a Scope section's "Not here" pointers.
+- **The closing link surface:** every other sister document belongs in the document's one closing section: "For the agent" (its neighbours line) in an owning or doctrine document, "Related" elsewhere. Deep relative paths (`../../../../…`) are fragile, since a folder move breaks every one, so they are confined to that block; body mentions use the plain name ("the boundary skill", "`structure.md`").
 
-**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.
+## Diagrams
 
-### Pattern
+Structure at rest is ASCII; behaviour over time is mermaid. A file tree, an on-disk layout, a load-class split, a wireframe: box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow, a data flow: mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
+
+- **Documents only:** a diagram belongs in a document read on demand (a feature, system or doctrine document, a procedure). Instruction files never carry one; they load on every turn or invocation, and a sentence or a table carries the same information at a fraction of the tokens.
+- **Prose as the account:** a diagram restates structure for a reader who scans; a reader who greps must still find everything in the text. In an owning document the flow bullets are the account and the diagram sits beside them, never in their place.
+- **Role level:** at the model and parts layers a diagram names roles, never a URL, a header or a file (§ Shape — the model first, the detail after).
+
+### ASCII
 
 ```
 ┌─────────────────────────────────────────┐
@@ -126,56 +206,23 @@ Always comment deprecated/unused fields. The annotation states why the field is
 └─────────────────────────────────────────┘
 ```
 
-### Characters
-
-- Boxes: `┌─┐│└┘├┤┬┴┼`
-- Arrows: `───▶` `◀───` `│▼` `│▲`
-- Width: ~70 chars max
-
-### UI Wireframes
+- **Characters:** boxes `┌─┐│└┘├┤┬┴┼`; arrows `───▶` `◀───` `│▼` `│▲`.
+- **Width:** about 70 characters at most.
+- **Wireframes:** a screen layout carries its page and tab above the frame (`**Page:** /path/:id`, `**Tab:** Tab Name`), `[text]` for a clickable button or badge, `[i]` for an icon followed by its label or count, `v` / `^` for an expand or collapse indicator, and one frame per UI state (collapsed, expanded).
 
-For screen layouts (not data flows), use these conventions:
-
-```
-**Route:** `path/:id`
-**Tab:** Tab Name
-
-┌────────────────────────────────────┐
-│ Title   [i]3                [Button]│
-│ [i]Label   [Tag1][Tag2][+Add]       │
-└────────────────────────────────────┘
-```
+### Mermaid
 
-- `[text]` = clickable button/badge
-- `[i]` = icon (followed by label or count)
-- `v` / `^` = expand/collapse indicator
-- Show each UI state (collapsed/expanded) as separate diagrams
-- Include Route/Tab context above wireframe
-
----
-
-## Mermaid Diagrams
-
-**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
-
-**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
-
-### When to Use
-
-| Diagram | Use for |
+| Diagram | Purpose |
 | --- | --- |
-| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
-| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
-| `flowchart` | A process with branches, gates, or fan-out |
-| `timeline` | A dated lineage, in records only — never in a truth document |
+| `sequenceDiagram` | Who calls whom in what order: a session turn, a hand-off between components |
+| `stateDiagram-v2` | Modes with transitions: a workflow, a record's lifecycle |
+| `flowchart` | A process with branches, gates or fan-out |
+| `timeline` | A dated lineage, in records only, never in a truth document |
 
-### Rules
-
-- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
-- **Labels under 8 words**, no trailing punctuation.
-- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
-- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
-- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
+- **Size:** at most 7 participants and 15 interactions per diagram. Past that, split it; an unreadable diagram is worse than the bullets it restates.
+- **Labels:** under 8 words, no trailing punctuation.
+- **Direction:** declared on every flowchart (`flowchart TD` / `LR`) so the render is stable.
+- **Styling:** none. No `style`, no `classDef`, no theme overrides; rendering is the reader's, and the source stays portable across GitHub, Obsidian and a plain editor.
 
 ```
 flowchart LR
@@ -185,243 +232,72 @@ flowchart LR
   D --> E[Implement]
 ```
 
----
+## Headings and layout
 
-## Code Examples
+- **Hierarchy:** one H1, the document's title; `##` for major sections, `###` for subsections, `####` sparingly.
+- **Fixed section names:** an owning document's `##` headings are its template's, bare and identical across every document of the genre (`## Scope`, `## Promises`, `## For the agent`), because readers and tooling find them by name.
+- **Retrieval keys:** search and agents retrieve a section out of context, where a bare `### Failures` reads identically across every document. A generic `###` heading, and every heading in an untemplated document, is qualified by its topic (`### Sign-in failures`, `### Merge rules — data sync`) so it stands alone when retrieved. A short document whose H1 disambiguates can keep bare headings.
+- **Sentence case:** headings are sentence case; a product, a proper name or a named concept (`The Two Natures`) keeps its own casing.
+- **No hard-wrapped prose:** a paragraph is one line in the source (`.prettierrc.json` keeps `proseWrap: never`); the renderer wraps it.
+- **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § The Two Natures).
+- **No file rosters:** a file list belongs in no document. The ownership index and the code graph answer "which file" for every genre, and a folder index describes directories, never files.
+- **The reference-document layout:** a document that is not an owning genre and whose content is the contract itself (an API reference, an environment registry, a procedure's appendix) opens on its goal, as a `**Goal:**` line or one sentence, and proceeds straight to its contract or procedure sections:
 
-### Rules
+```markdown
+# [Title]
 
-- Under 15 lines
-- Show contracts, not implementations
-- Use pseudocode for algorithms
+**Goal:** One-line purpose
 
-✅ Good:
+## [Contract or procedure sections]
 
-```javascript
-// Critical: Balanced brace matching
-function extract(json) {
-  // Track brace depth
-  // Ignore braces inside strings
-  // Return complete objects only
-}
+[Signatures, shapes, steps: the content the reader came for]
 ```
 
-❌ Bad: Full 50-line implementation
-
-(Worked example: [`examples.md`](examples.md) Example 1.)
-
----
-
-## Writing Style
-
-### Voice
-
-Use imperative/active:
-
-- ✅ "Fetches data from server"
-- ✅ "Returns array of objects"
-- ❌ "This function is used to fetch"
-- ❌ "An array is returned"
-
-### When Prose Adds Value
-
-Prose is valuable for context that contracts can't capture:
-
-| Use Prose For | Example |
-| --- | --- |
-| Section intros | "When the editor mounts, `useAppInit` is called with the `appId` from URL." |
-| 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[]`." |
-| 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
-
-- Describing WHAT code does (use signatures instead)
-- Step-by-step flows (use diagrams instead)
-- Structured comparisons (use tables instead)
-
-### Conciseness
-
-One line when possible:
-
-- ✅ "Merge server data with local changes using version-based conflict resolution"
-- ❌ "This function takes the data from the server and also takes the local data..."
+## Reference documents
 
-### Tables
+A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol nowhere but its footer, and then only as a seam.
 
-Use for structured info:
+### Function signatures
 
 ```markdown
-| Parameter | Type   | Description    |
-| --------- | ------ | -------------- |
-| `data`    | object | Fresh from API |
-| `local`   | object | Current state  |
-```
-
----
-
-## Self-Contained Documents & References
-
-Two verbosity regimes, split by who pays for the words. **Instruction files** (`CLAUDE.md`, rules, agents, skill prose) load into an agent's context on every turn or invocation — they stay lean, per [`instruction-style.md`](instruction-style.md). **Documents** are read on demand, by humans and agents alike — they are written **verbose and self-contained**, and the cost of a reader hopping files exceeds the cost of extra words on the page.
-
-- **The body reads whole without opening another file.** Restate the one or two sentences of context a borrowed concept needs, right where it's used — a reader forced mid-paragraph into a second document loses the thread of the first.
-- **Restate for readability, cite for authority — never fork the fact.** A changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs to be understood and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
-- **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
-- **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
-
-## Shape — the model first, the detail after
-
-Every truth document a person reads to understand something — doctrine, system, package, feature — is written **from the outside in**. It opens on the model and adds detail in layers, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser that only the next section makes sense of. The failure this prevents is a document written at one density from its first word: an inventory table before the reader knows what is being inventoried, and the principles that summarize it arriving last, where nobody reads them.
-
-**The layers, in order:**
-
-1. **The question and its boundary.** The first paragraph says what question this document answers, and which neighbouring documents answer the questions next to it. No addresses, file paths or configuration in it.
-2. **The model.** What the thing is in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere — numbered, each with its reason, so later sections can cite them ("principle 3").
-3. **The parts.** One table or diagram that places every part in the model, then how the parts relate: what they share, where they meet, and what keeps them apart.
-4. **Each part in turn.** For each part, the decisions it rests on and why. Each section opens with why the part exists, not with how it is built.
-5. **The genre's deepest layer**, from the table below, and nothing deeper.
-
-**The stability test decides what a sentence may say.** Ask whether the sentence would have to change if a function were renamed, a file moved, a route, column, cookie attribute or error code changed, or a constant was retuned without the design changing. If it would, it fails. The fact belongs to the code, and the code graph computes it on demand (`docs/architecture/systems/knowledge-layer.md`). A copy typed here is at best a duplicate of the code and at worst a stale one, which misleads the next agent more than no document would. It also has to be found and re-edited on every change to the code beneath it.
-
-These survive the test:
-
-- **Reasons.** Why the design is this way, and what would break otherwise.
-- **Invariants.** What must hold everywhere.
-- **Decisions and the alternatives a reader would reach for.**
-- **Promises a person or a test can check.**
-- **Contracts that span components no single file shows.** For example, two clients that must classify the same answer identically.
-- **Decided-but-unbuilt intent.** The code cannot reveal what it does not yet do.
-
-**The code is the authority on *what*; the document is the authority on *why*.** A document that disagrees with the code about what happens is simply stale, and the code wins. A disagreement about why, or about an invariant, is a defect to raise with the owner, because one of the two is wrong on purpose. State this in the opening of any document whose readers include agents.
-
-**Each genre has its own deepest layer.** The shape above is common to every genre; how far down a genre may go differs:
-
-| Genre | Deepest layer | Stops before |
-| --- | --- | --- |
-| Doctrine (`architecture/common/`) | The decisions behind each part, and the reasons for them | Any mechanism. A doctrine document describes no code |
-| System (`architecture/systems/`) | How the machine behaves across packages: sequence and state diagrams, the invariants at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps; tables and columns; routes |
-| Package (`architecture/packages/`) | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout; the build's steps; which file holds what |
-| Feature (`features/`) | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, wording where the wording is promised. **This genre runs deepest toward its end**, because a promise is checked by a person or a test, not computed from code | Columns, routes, guards, functions, files |
-| Reference (API reference, environment registry) | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
-| Operations procedure, runbook | The exact commands, in order | Nothing. The detail is the point |
-
-**A diagram belongs to a layer.** At the model and parts layers it names roles ("the browser", "the auth service"), never a URL, a header or a file. A diagram drawn from the code's names belongs to the code graph.
-
-**Length is a signal, not a target.** A document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about three hundred lines has usually let mechanism in.
-
-## Documents are read by people; the footer is for the agent
-
-A document that explains something — a doctrine, an owning document (feature, package, system) — is prose a person reads top to bottom. It takes the shape above (§ Shape — the model first, the detail after). The rules:
-
-- **The body is plain English.** It says what the thing is, why it is shaped that way, how a person meets it, and what it promises. Bullets and tables are for enumerable facts only — never for an argument, a decision or a promise. No sentence shape repeats down a list; a section whose entries share one shape is rewritten as paragraphs.
-- **Name code only where the graph would not lead a reader there.** The code graph answers what a feature's own files call, so those names add nothing. What it cannot answer from the feature's files is the seam that runs the other way: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Write that reference by name, once, where the narrative leaves the feature. Everything else is a plain name — "the device registry", "the sign-off page", "the mirror".
-- **A term of art is introduced in plain words the first time it appears.**
-- **Bold marks a defined term's first appearance at most** — never a noun mid-sentence. An em-dash is a budget, one per paragraph, not a joint between clauses.
-- **A gap the code does not close is one Known gaps paragraph, or a backlog row.** Never a ledger row inside the body, never a temporal hedge.
-- **The first line under the title is the goal.** No plan link, no routing line above it.
-- **The footer, "For the agent", is a set of pointers, not an inventory.** It holds four things:
-  1. The objects, with a one-line definition each.
-  2. The code roots, as directories, where the graph should start.
-  3. The cross-cutting seams, by name.
-  4. The checklist, and the neighbouring documents with a purpose for each.
-
-  A feature adds its pages, because an address is what a person points at. A package adds its commands, because those are its public contract. Tables, routes, symbol rosters and file lists do not belong in the footer any more than in the body. The footer obeys the stability test (§ Shape) like every other line, and a footer that grows with every function is the inventory moved down the page.
-- **"How it works" is narrative, not mechanism.** It says that a forgotten machine comes back on its next call, not which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's.
-
-The Mechanics rules below ("inline-code every identifier", "bold assertion — explanation") bind instruction files and operations procedures, not doctrine or the owning genres.
-
----
-
-## The Two Natures — Tense & History
-
-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). 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.
-
-Strip this language from truth documents:
-
-| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
-| --- | --- |
-| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
-| "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 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 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
+### `functionName(param1, param2, options)`
 
-### Headers
+**Goal:** One-line purpose
 
-```markdown
-# Document Title (H1 - once)
+**Input:**
 
-## Major Section (H2)
+- `param1` (type) - Description
+- `param2` (type, optional) - Description
 
-### Subsection (H3)
+**Output:** `{ field1, field2 }`
 
-#### Detail (H4 - sparingly)
+**Side effects:** State updates, API calls, etc.
 ```
 
-**Headings are retrieval keys.** Search and agents retrieve sections out of context, and a bare `## State` reads identically across every feature doc. In long docs, qualify generic headings with the feature name — `## State — invoice-pdf`, `### Merge rules — data sync` — so a section stands alone when retrieved. Short docs whose H1 disambiguates can keep bare headings.
+- **Parameters:** name, type and one-line purpose; `(type, optional)` marks an optional parameter; an object's properties nest beneath it (`options.retry` (boolean), `options.timeout` (number)).
+- **Return values:** type (`Array<Object>`, `boolean`, `{ merged, changes }`), shape for objects and arrays, and meaning ("true when the sync succeeded").
+- **Parameter tables:** `| Parameter | Type | Description |` where the parameters are many and parallel.
 
-### Standard Layout
+### State at persistence points
 
-An owning document (feature, system, package) takes its shape from its template — Goal · Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent — and a doctrine document from `templates/doctrine.md` — the question · The model · The parts · one section per part · For the agent. Neither is ever a code tour: no Architecture, Key Functions, State or Files section (§ Shape — the model first, the detail after; § Documents are read by people). The layout below is for a **reference document** that is not an owning genre — an API reference, an environment registry, a procedure's appendix — where a signature or a file list is the content itself:
-
-```markdown
-# [Title]
+- **Documented state:** what crosses a persistence boundary: a persisted store's shape (localStorage, IndexedDB), a database schema, a request or response shape.
+- **Undocumented state:** component-level state, derived or computed state, temporary UI state.
+- **Format:** the persisted shape as a `json` block with its storage key beneath (`**Storage:** localStorage key `state_key``), the schema as the code that declares it.
+- **Unused keys:** a deprecated field keeps a `// UNUSED:` comment stating 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): `// "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility`.
 
-**Goal:** One-line purpose
+### Code examples
 
-## [Contract or procedure sections]
+- **Size:** under 15 lines.
+- **Content:** a contract, never an implementation; pseudocode for an algorithm, with the invariants as comments and the body left out.
+- **Placement:** a reference document, a procedure, or a package's Usage section, where the code is a command a person types. A feature or system document carries no function body.
 
-[Signatures, shapes, steps — the content the reader came for]
+```javascript
+// Critical: balanced brace matching
+function extract(json) {
+  // Track brace depth
+  // Ignore braces inside strings
+  // Return complete objects only
+}
 ```
 
-A file roster belongs in no document: the ownership index and the code graph answer "which file" for every genre.
-
----
-
-## Summary
-
-| Aspect     | Rule                            |
-| ---------- | ------------------------------- |
-| Functions  | Signatures in reference docs only — an owning document names a symbol in its footer |
-| Parameters | Type + purpose                  |
-| Returns    | Type + shape                    |
-| State      | Persistence points only         |
-| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
-| Code       | Under 15 lines, contracts only  |
-| Voice      | Imperative/active               |
-| Mechanics  | Instruction files and procedures: inline-code identifiers, bold-assertion bullets. Doctrine and owning documents: plain prose, pointers in the footer |
-| Shape      | The model first, the detail after; every sentence passes the stability test; each genre stops at its deepest layer (§ Shape) |
-| Length     | Concise; a paragraph is one line — never hard-wrap prose (`.prettierrc.json` keeps `proseWrap: never`) |
+Worked example: [`examples.md`](examples.md) Example 1.