@nurix/etna 0.20.26 → 0.20.28

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

@@ -22,6 +22,7 @@ When a draft wants to be both — the current state *and* the story of getting t
 ## 3. Shape it
 
 - **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
 - **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
@@ -30,7 +31,7 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 ## 4. Write it in the house style
 
-`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); imperative/active voice; code examples under 15 lines showing contracts, not implementations; ASCII diagrams in docs only; inline-code every identifier, filename, command, and config key.
+`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); third-person, present-tense, active sentences after noun-phrase labels (§ Voice, § Labels); diagrams in documents only, beside the prose and never in its place (§ Diagrams); signatures, state shapes and code examples under 15 lines in reference documents only (§ Reference documents).
 
 ## 5. With a human in the loop — the co-authoring workflow
 

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -17,7 +17,7 @@ const RULES = [
   { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
   // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and structure.md\'s Health Log tail' },
+  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and a dated path inside a link or code span' },
 ];
 
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
@@ -134,7 +134,7 @@ function lintFile(path, findings) {
         const target = m[1];
         if (/^[a-z]+:\/\//.test(target) || SCAFFOLD.test(target)) continue;
         // The repo-root README routes by intent (templates/root-readme.md): its Map names owning package and system
-        // docs, its Where-to-go rows name procedures and rules. Individual feature docs stay off it — the ownership index finds them.
+        // docs, its Destinations rows name procedures and rules. Individual feature docs stay off it — the ownership index finds them.
         if (isRootReadme && /(^|\/)docs\/(architecture\/(packages|systems|common)\/|operations\/)[^/]+\.md$|(^|\/)\.claude\/rules\/[^/]+\.md$/.test(target)) continue;
         if (isRootReadme && /(^|\/)docs\/features\/[^/]+\.md$/.test(target)) { findings.push({ path, n, severity: 'warn', id: 'root-readme-feature-link', message: `root README links an individual feature doc (\`${target}\`) — point at docs/features/ and let the ownership index find it`, excerpt: line.trim().slice(0, 90) }); continue; }
         findings.push({ path, n, severity: 'block', id: 'index-lists-files', message: `index links an individual document (\`${target}\`) — name the folder and how its files are named; \`ls\` is the roster`, excerpt: line.trim().slice(0, 90) });
@@ -177,37 +177,53 @@ function lintFile(path, findings) {
     if (!/^objects:/m.test(fm)) findings.push({ path, n: 1, severity: 'block', id: 'objects-missing', message: 'owning document names no `objects:` — the product objects it designs are its edge into the graph and its discovery terms' });
   }
 
-  // The body of an owning document is read by people; its "For the agent" footer is the reference
-  // surface (style-guide § Documents are read by people). These three warn, never block: a seam
-  // reference is allowed in the body, and the judgment of which identifier is a seam is the author's.
+  // The body of an owning document is scanned by people; its "For the agent" footer holds the pointers
+  // (style-guide § Owning documents — the body and the footer). Body identifiers warn, never block: a seam reference
+  // is allowed in the body, and the judgment of which identifier is a seam is the author's.
   if (isOwningDoc) {
-    const OLD_SHAPE = /^##\s+(Background|Decisions|Promises|Objects|Related)\s*$/;
     const footerAt = lines.findIndex(({ line }) => /^##\s+For the agent\b/.test(line));
     const body = footerAt === -1 ? lines : lines.slice(0, footerAt);
     let section = null; // proseLines already dropped the frontmatter and the fences
     const sections = [];
     for (const { n, line } of body) {
       if (/^##\s+/.test(line)) {
-        if (!disabled.has('old-shape-section') && OLD_SHAPE.test(line)) findings.push({ path, n, severity: 'warn', id: 'old-shape-section', message: 'second-shape heading — the owning genres now read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent', excerpt: line.trim() });
-        section = { n, title: line.replace(/^##\s+/, '').trim(), bullets: 0, lines: 0, ids: 0, boldRun: 0, maxRun: 0 };
+        section = { n, title: line.replace(/^##\s+/, '').trim(), ids: 0 };
         sections.push(section);
         continue;
       }
-      if (!section || !line.trim()) { if (section) section.boldRun = 0; continue; }
-      section.lines++;
-      const isBullet = /^\s*[-*]\s+/.test(line);
-      if (isBullet) section.bullets++;
-      if (/^\s*[-*]\s+\*\*/.test(line)) { section.boldRun++; section.maxRun = Math.max(section.maxRun, section.boldRun); } else section.boldRun = 0;
+      if (!section) continue;
       for (const m of line.matchAll(/`([^`]+)`/g)) {
         const t = m[1];
+        // What a person types or sees is the feature's surface, not code: a page path, a flag, an environment variable, a command.
+        if (/^\/[a-z]|^--?[a-z]|^[A-Z][A-Z0-9_]+(=\S*)?$|^[a-z][\w-]* [a-z-]/.test(t)) continue;
         if (/[\/]|\.(ts|tsx|mjs|js|md|json|sql)$|_|\(|^[a-z]+[A-Z]|^[A-Z][a-z]+[A-Z]|^(GET|POST|PUT|PATCH|DELETE) /.test(t)) section.ids++;
       }
     }
     for (const s of sections) {
-      if (/^(Ownership|Known gaps)$/.test(s.title)) continue;
-      if (!disabled.has('body-identifier') && s.ids > 3) findings.push({ path, n: s.n, severity: 'warn', id: 'body-identifier', message: `${s.ids} code identifiers in a body section — the body names code only at a cross-cutting seam (a middleware, gate, hook, store); the rest is plain names in prose, with identifiers in "For the agent"`, excerpt: s.title });
-      if (!disabled.has('list-not-prose') && s.bullets >= 4 && s.bullets / s.lines > 0.6) findings.push({ path, n: s.n, severity: 'warn', id: 'list-not-prose', message: 'a body section that is a list — a decision, a promise or an explanation is prose; a list is for genuinely parallel one-liners', excerpt: s.title });
-      if (!disabled.has('formula-run') && s.maxRun >= 3) findings.push({ path, n: s.n, severity: 'warn', id: 'formula-run', message: 'three or more bold-led bullets in a row — the "**X** — over Y, because Z" formula reads as a ledger; write the decisions as themed paragraphs', excerpt: s.title });
+      if (/^(Ownership|Gaps|Known gaps)$/.test(s.title)) continue;
+      if (!disabled.has('body-identifier') && s.ids > 3) findings.push({ path, n: s.n, severity: 'warn', id: 'body-identifier', message: `${s.ids} code identifiers in a body section — the body names code only where a person types or sees it, or at a cross-cutting seam (a middleware, gate, hook, store); the rest is plain names, with pointers in "For the agent"`, excerpt: s.title });
+    }
+  }
+
+  // A heading or a bold bullet label names; it never says. A label with a finite verb drags in a tense,
+  // a person and a voice ("What was decided", "You already belong to…"), so a label opening with a
+  // wh-word or a personal pronoun, or ending in a full stop, is a clause (style-guide § Labels).
+  const isLabelledDoc = isOwningDoc || (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/architecture\/common\/[^/]+\.md$/.test(path));
+  if (isLabelledDoc && !disabled.has('clause-label')) {
+    const CLAUSE = /^(how|what|why|where|when|who|which|whose|you|your|we|our|i|it)\b|\b(you|your)\b|\.$/i;
+    for (const { n, line } of lines) {
+      const heading = /^#{2,4}\s+(.+?)\s*$/.exec(line);
+      const bold = /^\s*[-*]\s+\*\*(.+?)\*\*/.exec(line);
+      const label = heading ? heading[1] : bold ? bold[1].replace(/:$/, '').trim() : null;
+      if (!label || /^For the agent$/i.test(label)) continue;
+      if (CLAUSE.test(label.replace(/`[^`]*`/g, 'X'))) findings.push({ path, n, severity: 'warn', id: 'clause-label', message: 'a heading or bold label written as a clause — a label is a noun phrase with no verb, tense or person ("Decisions", not "What was decided"; "Organization member:", not "You already belong to an organization:")', excerpt: label.slice(0, 90) });
+    }
+    // The sentences after a label describe the product in the third person; quoted interface copy keeps its own "you".
+    if (!disabled.has('second-person')) {
+      for (const { n, line } of lines) {
+        const bare = line.replace(/`[^`]*`/g, '').replace(/\*\*[^*]+\*\*/g, 'X').replace(/\*"[^"]*"\*|\*[^*]+\*|"[^"]*"/g, '');
+        if (/\b(you|your|yours|yourself)\b/i.test(bare)) findings.push({ path, n, severity: 'warn', id: 'second-person', message: 'second person in a truth document — the sentence after a label is third person ("user lands…", never "you land…"); quoted interface copy is exempt', excerpt: line.trim().slice(0, 90) });
+      }
     }
   }
 }

package/data/harnesses/code/skills/documentation/templates/doctrine.md

@@ -9,16 +9,15 @@ Truth document. Use for **one concern the platform handles everywhere**: authent
 - the frontmatter
 - the opening (the question, the boundary, and the authority sentence)
 - **The model**, ending in numbered principles, each with its reason
-- **The parts**: one table or diagram placing every part in the model, then how the parts relate
+- **The parts**: one table or diagram placing every part in the model, then their relations
 - **one section per part**
 - **For the agent**
 
 **Optional:**
 
 - an `UNBUILT` block for decided-but-unbuilt intent
-- **Related**
 
-Nothing else. Expect one hundred and fifty to three hundred lines; past that, mechanism has usually crept in.
+Nothing else: the neighbouring documents live in **For the agent**, the one closing link surface (`references/style-guide.md` § Self-contained documents and the link surface). Expect one hundred and fifty to three hundred lines; past that, mechanism has usually crept in.
 
 ```yaml
 ---
@@ -37,31 +36,31 @@ objects: [principal, credential, device grant]   # recommended — the concepts
 
 ## The model
 
-### {What the platform owns here, and what it delegates}
+### {The ownership boundary, as a noun phrase — e.g. "Identity: checked, not owned"}
 
-{The one framing fact a reader needs before anything else — e.g. "NuStack checks identity; it does not own it". Plain words, no addresses.}
+{The one framing fact a reader needs before anything else. Plain words, no addresses.}
 
-### {The parties or parts}
+### {The participants, as a noun phrase — e.g. "Callers"}
 
-{Who or what participates, in a short list of one-liners — each named in plain words first, its term of art in parentheses.}
+{Who or what participates: one bullet each, a bold noun-phrase label in plain words, its term of art in parentheses, then one line.}
 
-### {The axis that organizes them}
+### {The organizing axis, as a noun phrase — e.g. "Proof checking"}
 
-{The one or two dimensions every part is placed on — e.g. "who issued the proof decides how it is checked". A small table is right here.}
+{The one or two dimensions every part is placed on. A small table is right here.}
 
-### The principles
+### Principles
 
-{Numbered invariants that hold across every part. Each one sentence of rule plus its reason. Later sections cite them by number.}
+{Numbered invariants that hold across every part, each a bold noun-phrase label, then the rule and its reason in a sentence or two. Later sections cite them by number.}
 
-## {The parts} — e.g. "The credential families"
+## {The parts, as a noun phrase — e.g. "Credential families"}
 
-{One table: each part placed on the model's axes. Then "How the parts relate": what they share, where they meet, what keeps them apart, and the order in which they are tried — each as a bold-led paragraph with its reason. A role-level diagram (mermaid) where the relationships are a flow.}
+{One table: each part placed on the model's axes. Then a "Relations" subsection: what they share, where they meet, what keeps them apart, and the order in which they are tried — each a bullet with a bold noun-phrase label and its reason. A role-level diagram (mermaid) where the relationships are a flow.}
 
-## {Each part, one section per part} — e.g. "How each family works"
+## {The parts in depth, as a noun phrase — e.g. "Families in depth"}
 
-### {A part, named for who meets it} — e.g. "A person in a browser"
+### {One part, named for who meets it — e.g. "Browser person", "Trusted system"}
 
-{Why the part exists, then the decisions it rests on, each with its reason, citing principles by number. A sequence diagram at role level where the part is a flow. Detail that a person or test can check is welcome; detail that only restates the code is not.}
+{One line on why the part exists, then the decisions it rests on as bullets — a bold noun-phrase label, then the reason — citing principles by number. A sequence diagram at role level where the part is a flow. Detail that a person or test can check is welcome; detail that only restates the code is not.}
 
 ## For the agent
 

package/data/harnesses/code/skills/documentation/templates/feature.md

@@ -1,12 +1,31 @@
 # Feature Documentation (docs/features/{feature}.md)
 
-Truth document. Use for: every feature in `docs/features/` — something a person points at: an address, a command family, a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
+Truth document. Use for every feature in `docs/features/`: something a person points at, such as an address, a command family or a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
 
-**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Documents are read by people). The body is plain English a newcomer reads top to bottom: what the thing is, why it is shaped that way, how a person meets it, what it promises. Every computable fact — columns, vocabularies, foreign keys, writers, routes, guards, codes, files — is the code graph's (`docs/architecture/systems/knowledge-layer.md`); a hand-typed copy is the defect this genre removes. The only code the body names is 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, a shared store. Everything else by plain name. Identifiers the graph cannot find from the roots live in the footer.
+**A feature document is sharp, bulleted and actionable** (`references/style-guide.md` § Labels; § Shape — the model first, the detail after). A reader scans it rather than reads it:
 
-**A feature document runs deepest toward its end** (`references/style-guide.md` § Shape — the model first, the detail after). The opening and Why it exists are the model; How it works is the journey; **What it promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism: a promise reads "a removed membership shows a panel, not a redirect, because nothing can restore it", never which route answers it.
+- **Headings and bullet labels are noun phrases.** For example `Flows`, `Organization member`, `Dead grant` — never a clause like "How it works" or "You already belong to an organization".
+- **Each bullet is a bold label, then one or two third-person sentences** saying what happens: "**Organization user:** user lands in their existing organization", never "you land…".
+- **Flows carry the journey; Decisions carry the reasons; Promises run deepest.**
 
-**Required:** the frontmatter, the goal line, **Why it exists**, **How it works**, **What it promises**, **For the agent**. **What was decided** once any choice was made the code cannot explain. **Known gaps** only when there is one. Nothing else — `doc-lint` blocks the retired mechanism sections (`mechanism-section`) and warns on identifiers in the body (`body-identifier`), on a section that is a list rather than prose (`list-not-prose`), and on three bold-led bullets in a row (`formula-run`). Forty to a hundred and twenty lines.
+Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is 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.
+
+**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+
+**Sections:**
+
+| Section | When |
+| --- | --- |
+| Frontmatter | required |
+| Goal line | required |
+| `Scope` | required |
+| `Flows` | required |
+| `Decisions` | once any choice was made that the code cannot explain |
+| `Promises` | required |
+| `Gaps` | only when there is one |
+| `For the agent` | required |
+
+Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-section`), and warns on code identifiers in the body (`body-identifier`), on a heading or bullet label written as a clause (`clause-label`), and on "you" outside quoted copy (`second-person`).
 
 ```yaml
 ---
@@ -24,36 +43,53 @@ applies: [docs/architecture/common/security.md]  # optional — doctrine this su
 
 {One sentence: what this lets a person do.}
 
-## Why it exists
+## Scope
 
-{The need, the trigger, the constraint; what it is deliberately not for and why. Prose, one or two paragraphs. An AD is cited by number for the reasoning it holds, never restated.}
+- **Covers:** {the surfaces, commands and journeys this document owns}
+- **Bound by:** {the doctrine documents it applies, each with what it settles}
+- **Not here:** {the neighbouring features a reader might expect here, each linked}
 
-## How it works
+## Flows
 
-{The feature as a person meets it, start to finish, present tense, plain words: what they see, what happens, what refuses them and what they are told. Introduce each term of art the first time. Name code only at a cross-cutting seam — "every request passes the organization gate before this page is reached (`requireAuth`)" — and nothing else. No columns, routes, guards, functions, files or diagrams: that is the graph's.}
+### {Entry point or situation, as a noun phrase — e.g. "Browser", "Terminal", "Landing", "Sign-out"}
 
-## What was decided
+- **{Noun-phrase label — e.g. "Signed-out visitor", "Claimed domain", "`nustack login`"}:** {what the user does or meets, and what happens. One or two sentences, third person, present tense — "user lands…", never "you land…".}
+  - {a sub-case, only where the parent genuinely branches}
 
-{The choices the code cannot explain, as two to four themed paragraphs. A rejected alternative is named only where a reader would reach for it. No formula; no bullet per decision.}
+## Decisions
 
-## What it promises
+- **{The decision as a noun phrase — e.g. "Single entry, no sign-up", "Unsigned organization cookie"}:** {why, in one or two sentences, and the alternative a reader would reach for if it matters.}
 
-{The guarantees and refusals a person or a test can check, grouped by theme, as short paragraphs — or a short list only where the items are genuinely parallel one-liners. Positive where possible. This is the deepest section: each state, edge case and refusal the person can meet, and the wording where it is promised. A table of states is right when the states are genuinely parallel.}
+## Promises
 
-## Known gaps
+### {Theme as a noun phrase — e.g. "Sign-in failures", "Gate outcomes", "Terminal grant states"}
 
-{One paragraph, only when the code does not keep something the document would otherwise promise. What is missing and what it would take; the backlog row carries the rest.}
+{A table where the cases are parallel states — | Situation | What the person sees | — carrying the exact wording where the wording is promised. Bullets otherwise:}
+
+- **{Noun-phrase label}:** {the guarantee or refusal, checkable by a person or a test.}
+
+## Gaps
+
+- **{Noun-phrase label}:** {what the code does not keep, and what closing it would take. The backlog row carries the rest.}
 
 ## For the agent
 
-Objects: {object} — {one plain-words line}; {object} — {…}. Pages {`/…`}. Code roots {`packages/…/src/…/`} — directories, where the graph should start. Seams {`name`} only where the roots would not lead to them. Checklist `tests/{feature}.md`. See also {neighbour} ({why}), {neighbour} ({why}). No tables, routes or symbol rosters — those are the graph's.
+- **Objects:** {object}: {one plain line}; {object}: {…}
+- **Pages:** {`/…`}
+- **Commands:** {`nustack …`}
+- **Code roots:** {`packages/…/src/…/`}, directories where the graph should start
+- **Seams:** {`name`}, only where the roots would not lead to them
+- **Checklist:** `tests/{feature}.md`
+- **See also:** {neighbour}: {why}
+
+No tables, routes or symbol rosters — those are the graph's.
 ```
 
 ### Lifecycle
 
 | When | What is written |
 | --- | --- |
-| `status: draft` (design) | goal, Why it exists, What was decided, What it promises (with gaps named), For the agent; the LLD research goes to the plan |
-| `status: active` | How it works written from the shipped surface; `owns:` confirmed against real code |
+| `status: draft` (design) | goal, Scope, Decisions, Promises (with gaps named), For the agent; the LLD research goes to the plan |
+| `status: active` | Flows written from the shipped surface; `owns:` confirmed against real code |
 
 A feature whose code is gone is deleted, or `status: deprecated` with its footer pointing at what replaced it.

package/data/harnesses/code/skills/documentation/templates/handover.md

@@ -80,7 +80,7 @@ Each was taken because waiting would have stopped the run. Sorted by cost to rev
 
 ## 6. What was built
 
-| Unit | What it does for a person | Landed | Proof |
+| Unit | Role for a person | Landed | Proof |
 | --- | --- | --- | --- |
 | {name} | {one clause, behaviour before mechanism} | {branch · PR · release} | {suite + counts, or "driven only", or empty} |
 

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

@@ -2,13 +2,27 @@
 
 Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.
 
-**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Documents are read by people). A package document tells a person what the package is for, why it is its own unit, how it ships and to whom, how it is meant to be used, and what its consumers can rely on. Its manifest, build, entry, internal layout and test wiring are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a roster here.
+**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Owning documents — the body and the footer). A package document tells a person what the package is for, why it is its own unit, how it ships and to whom, how it is meant to be used, and what its consumers can rely on. Its manifest, build, entry, internal layout and test wiring are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a roster here.
 
-**A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in How it is used. It stops before internal layout, build steps and which file holds what.
+**A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.
 
 **A package document is the residual owner of its own tree.** Its `owns:` is the whole package glob — the broadest claim on those paths, so it loses to every narrower system or feature claim. The one enumerable fact it declares is the ownership table: which subtrees other documents claim.
 
-**Required:** the frontmatter, the identity line, the goal line, **Why it exists**, **Ownership** (one paragraph or a table), **How it is used**, **What it promises**, **For the agent**. **What was decided** once any choice was made the code cannot explain. **Known gaps** only when there is one. Nothing else — the feature template's lint rules apply. Forty to a hundred and twenty lines.
+**Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.
+
+**Sections:** the frontmatter, the identity line and the goal line are required. Then:
+
+| Section | When |
+| --- | --- |
+| `Scope` | required. Why the package is its own unit, who consumes it, and what it deliberately does not hold |
+| `Ownership` | required, as one line or a table |
+| `Usage` | required |
+| `Decisions` | once any choice was made that the code cannot explain |
+| `Promises` | required |
+| `Gaps` | only when there is one |
+| `For the agent` | required |
+
+Nothing else. The feature template's lint rules apply. Forty to a hundred and twenty lines.
 
 ```yaml
 ---
@@ -27,9 +41,11 @@ applies: [docs/architecture/common/api.md]       # optional
 
 {One sentence: the job this package does in the product, for whom.}
 
-## Why it exists
+## Scope
 
-{Why it is its own unit, what it holds that nothing else does, what it deliberately does not hold, who consumes it, how and when it ships. Prose.}
+- **Role:** {what it holds that nothing else does}
+- **Consumers:** {who consumes it, and how and when it ships}
+- **Not here:** {what it deliberately does not hold, and where that lives}
 
 ## Ownership
 
@@ -39,27 +55,34 @@ This document is the residual owner of `packages/{name}/**`. Claimed at higher s
 | --- | --- |
 | `src/{machine}/**` | [{system}](../systems/{system}.md) |
 
-## How it is used
+## Usage
 
-{What a person or another package does with it, in plain words — install, run, import, call — and what they see. Terms introduced on first use. Code named only at a seam.}
+- **{Noun-phrase label — e.g. "Install", "`nustack login`", "Import"}:** {what a person or another package does with it, and what they see. The public contract (commands, flags, exports) belongs here.}
 
-## What was decided
+## Decisions
 
-{Themed paragraphs.}
+- **{The decision as a noun phrase}:** {why.}
 
-## What it promises
+## Promises
 
-{What a consumer can rely on and what the package refuses; checkable sentences, grouped.}
+- **{Noun-phrase label}:** {what a consumer can rely on, or what the package refuses; checkable.}
 
-## Known gaps
+## Gaps
 
-{One paragraph, only when needed.}
+- **{Noun-phrase label}:** {what is missing and what it would take.}
 
 ## For the agent
 
-Objects: {…}. Commands {…} and exports {…} — the public contract. Code root `packages/{name}/`. Seams {…} by name. Checklist `tests/{package}.md`. See also {neighbour} ({why}). No file lists or symbol rosters — those are the graph's.
+- **Objects:** {…}
+- **Commands and exports:** {…} — the public contract
+- **Code root:** `packages/{name}/`
+- **Seams:** {…} by name
+- **Checklist:** `tests/{package}.md`
+- **See also:** {neighbour}: {why}
+
+No file lists or symbol rosters — those are the graph's.
 ```
 
 ### Marking what is decided and unbuilt
 
-`<!-- UNBUILT:START — {…} -->` … `<!-- UNBUILT:END -->` around the prose for a decided, unbuilt half; a design decided *against* carries no marker.
+`<!-- UNBUILT:START — {…} -->` … `<!-- UNBUILT:END -->` around the bullets for a decided, unbuilt half; a design decided *against* carries no marker.

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

@@ -7,14 +7,14 @@ Truth document. Use for: the repository root `/README.md`. It opens outward —
 Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onward the inward page. Skip any section the repo cannot fill truthfully. Never pad it, and never leave a stub.
 
 1. **Identity.** The H1 plus two or three sentences in a user's terms: what the product is, where it runs, and what using it is like.
-2. **What it does.** Two to four paragraphs, outward-facing: the core loop as a person meets it, what surrounds that loop, how the product follows the person across its surfaces, and who it is for, closing with what it deliberately is not. Plain words, no feature roster, no superlatives.
-3. **Where it runs.** One paragraph: the addresses, the distributed artifacts and where they are published, where identity comes from, and whether a self-hosted edition exists.
+2. **Capabilities.** Two to four paragraphs, outward-facing: the core loop as a person meets it, what surrounds that loop, how the product follows the person across its surfaces, and who it is for, closing with what it deliberately is not. Plain words, no feature roster, no superlatives.
+3. **Deployment.** One paragraph: the addresses, the distributed artifacts and where they are published, where identity comes from, and whether a self-hosted edition exists.
 4. **The turn.** A rule and one paragraph saying the rest is for the team and agents, with the scope line: what lives in this repo and what lives elsewhere.
 5. **State.** Optional: a one-line blockquote, present only while something repo-wide is true that a newcomer must know (frozen, mid-migration, mid-breaking-change on `dev`). It links the plan or runbook that owns the change. Say here which units publish and where, if any do.
-6. **How it works.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
-7. **What is in the repository.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
+6. **The main path.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
+7. **Repository map.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
 8. **Rules that bite.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
-9. **Where to go.** An intent-to-destination table. Its last row is the one for agents.
+9. **Destinations.** An intent-to-destination table. Its last row is the one for agents.
 10. **Everyday commands.** Optional. At most four commands run on every change, ending at the gate a push must pass. First-run commands are never here.
 
 ### What it leaves out
@@ -31,11 +31,11 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 ### Writing rules
 
-- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — How it works and Rules that bite read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
+- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Rules that bite read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
 - **Every section is either a fact the reader acts on or a link.** If a section needs a paragraph, it needs a doc.
 - **One H1, then H2 sections, in plain Markdown.** Sentence-case headings, no emoji, no HTML layout, and no `#` comment lines inside code blocks (they parse as H1s).
 - **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
-- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Where-to-go row needs it. Never list individual feature docs: the ownership index finds them.
+- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
 - **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
 - **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc that the index's `owns:` globs resolve to. When the two disagree the index wins, and the Map row is fixed in the same change.
 - **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
@@ -49,7 +49,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 {Two or three sentences in a user's terms: what the product is, where it runs, what using it is like.}
 
-## What it does
+## Capabilities
 
 {The core loop as a person meets it: what they bring, what the product does, what they get back and what record it leaves.}
 
@@ -59,7 +59,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 {Who it is for, and what it deliberately is not.}
 
-## Where it runs
+## Deployment
 
 {Addresses; distributed artifacts and where they publish; where identity comes from; whether a self-hosted edition exists.}
 
@@ -69,7 +69,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 > **State:** {one line: what is in flux right now; which units publish where} → [{plan or runbook}](docs/history/{plans|migrations}/{file}.md) ← optional; delete when the flux ends
 
-## How it works
+## The main path
 
 1. **{Stage}**: {what happens, naming the mechanism only where it explains the step}.
 2. **{Stage}**: {…}.
@@ -78,7 +78,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 {Optional, one sentence naming the seam everything passes through, e.g. "Every client reaches data through `{path}`; nothing else talks to the database."} The full account: [{system overview}](docs/architecture/{overview}.md).
 
-## What is in the repository
+## Repository map
 
 {One or two sentences: the workspace shape and where each unit's design document lives.}
 
@@ -99,9 +99,9 @@ The rest of this page is for the team and for coding agents working in this repo
 - **{Never-edit paths}**: `{path}` is {generated by `{command}` | protected}; edit {the source} instead.
 - **Not here:** {a non-goal stated as a refusal}.
 
-## Where to go
+## Destinations
 
-| I want to… | Go to |
+| Intent | Destination |
 | --- | --- |
 | Set up a machine and run it the first time | [docs/operations/setup.md](docs/operations/setup.md) |
 | Work on it day to day | [docs/operations/{local-development}.md](docs/operations/{local-development}.md) |
@@ -130,12 +130,12 @@ The rest of this page is for the team and for coding agents working in this repo
 
 The baseline **does** scaffold `/README.md` when it is missing, and it fills each section from the repo:
 
-- **Identity, What it does, Where it runs:** from the product charter and vision documents under `docs/architecture/common/` (what the product is, the core loop, who it is for), the package manifests (what publishes where), and the deploy config (addresses). Written in a user's terms; where the charter is missing, the baseline writes Identity only and raises a `note:` row for the rest.
-- **How it works:** from the system overview.
+- **Identity, Capabilities, Deployment:** from the product charter and vision documents under `docs/architecture/common/` (what the product is, the core loop, who it is for), the package manifests (what publishes where), and the deploy config (addresses). Written in a user's terms; where the charter is missing, the baseline writes Identity only and raises a `note:` row for the rest.
+- **The main path:** from the system overview.
 - **Map:** from the workspace globs and the ownership index.
 - **Rules:** from `docs/operations/protected-files.md` and the architecture doctrine.
 - **Commands:** from the lockfile and the root scripts.
-- **Where to go:** only the rows whose targets exist.
+- **Destinations:** only the rows whose targets exist.
 
 It drops every section it cannot fill concretely.
 

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

@@ -1,6 +1,6 @@
 # Setup (docs/operations/setup.md)
 
-Truth document, operations genre (`type: operations`). Use for: **the one-time path from a fresh machine to a first verified run.** It covers what the repo is built on, prerequisites, install, env files, local services, the first commands, proof that it works, and the failures a fresh clone hits. There is **one per repo**, always named `setup.md`, and it is a mandated scaffold. The root README's only setup content is a Where-to-go row linking it.
+Truth document, operations genre (`type: operations`). Use for: **the one-time path from a fresh machine to a first verified run.** It covers what the repo is built on, prerequisites, install, env files, local services, the first commands, proof that it works, and the failures a fresh clone hits. There is **one per repo**, always named `setup.md`, and it is a mandated scaffold. The root README's only setup content is a Destinations row linking it.
 
 It is distinct from `local-development.md`, the daily loop: watch modes, resetting state, per-package traps, the inner test cycle. Setup runs once per machine. Local development runs every session. Setup ends by handing off to it, and neither copies the other. Deploying is `deployment.md`.
 

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

@@ -2,13 +2,26 @@
 
 Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.
 
-**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Documents are read by people). A system document explains a machine to a person: what it is for, why it is split where it is split, how it behaves from the outside, what it guarantees at the far end, what re-drives it when it stalls. Its stages, tables, routes, frames, bindings and files are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a hand-typed tour. The body names code only at a cross-cutting seam another machine or feature would not find from its own files.
+**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Owning documents — the body and the footer). A system document explains a machine to a person: what it is for, why it is split where it is split, how it behaves from the outside, what it guarantees at the far end, what re-drives it when it stalls. Its stages, tables, routes, frames, bindings and files are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a hand-typed tour. The body names code only at a cross-cutting seam another machine or feature would not find from its own files.
 
 **A system document's deepest layer is the machine's behaviour across packages** (`references/style-guide.md` § Shape — the model first, the detail after): the order it runs in, the sequence and state diagrams at role level, the invariant that holds at each place where parts meet, and what re-drives a stall. That layer is earned because no single file shows a cross-package flow. It stops before per-function steps, tables, columns and routes.
 
 **A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of, narrower than the package glob. Two documents never claim a path at equal specificity; every glob matches a file on disk at `status: active`.
 
-**Required:** the frontmatter, the opening paragraph (the machine defined in its first sentence, what enters, what it leaves behind), the **boundary paragraph** (what this document does not decide, and which document does — subjects with owners, never bare links), **Why it exists**, **How it works**, **What it promises**, **For the agent**. **What was decided** once any choice was made the code cannot explain. **Known gaps** only when there is one. Nothing else — the lint rules of the feature template apply. Sixty to a hundred and sixty lines.
+**Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). The opening paragraph defines the machine; everything after it is bullets under noun-phrase headings, each bullet a bold noun-phrase label followed by one or two sentences.
+
+**Sections:** the frontmatter and the opening paragraph (the machine defined in its first sentence, what enters, what it leaves behind) are required. Then:
+
+| Section | When |
+| --- | --- |
+| `Scope` | required. What this document does not decide, and which document does — subjects with owners, never bare links |
+| `Flow` | required |
+| `Decisions` | once any choice was made that the code cannot explain, including why this is one machine and not two |
+| `Promises` | required |
+| `Gaps` | only when there is one |
+| `For the agent` | required |
+
+Nothing else. The lint rules of the feature template apply. Sixty to a hundred and sixty lines.
 
 ```yaml
 ---
@@ -27,33 +40,42 @@ applies:                                         # optional — decisions and do
 
 {The machine defined in its first sentence — bold the term — then what it takes in, what it leaves behind, and what a reader sees at the far end. Plain words.}
 
-{The boundary paragraph: what this document does not decide and which document does.}
+## Scope
 
-## Why it exists
+- **Covers:** {what this machine decides}
+- **Not here:** {subject} — {owning document}; {subject} — {owning document}
 
-{Why this is one machine and not two, what it deliberately is not, the constraint that shaped it.}
+## Flow
 
-## How it works
+### {Stage as a noun phrase — e.g. "Intake", "Settlement", "Re-drive"}
 
-{The machine's behaviour from the outside, in the order it runs, in plain words: what starts it, what it does at each step as a person would describe it, what it writes that outlives it, what re-drives it, what it refuses. Terms of art introduced on first use. Code named only at a seam.}
+- **{Noun-phrase label}:** {what starts it or what it does at this step, as a person would describe it; what it writes that outlives it; what it refuses.}
 
-## What was decided
+{A role-level sequence or state diagram where the stages cross packages.}
 
-{Themed paragraphs; alternatives named only where a reader would reach for them.}
+## Decisions
 
-## What it promises
+- **{The decision as a noun phrase}:** {why; the alternative only where a reader would reach for it.}
 
-{Checkable guarantees and refusals, grouped; what holds at the far end; what a stalled run gets.}
+## Promises
 
-## Known gaps
+- **{Noun-phrase label}:** {a checkable guarantee or refusal; what holds at the far end; what a stalled run gets.}
 
-{One paragraph, only when needed.}
+## Gaps
+
+- **{Noun-phrase label}:** {what is missing and what it would take.}
 
 ## For the agent
 
-Objects: {…}. Code roots {…} — directories, one per package the machine spans. Seams {…} by name. Checklist `tests/{system}.md`. See also {neighbour} ({why}). No tables, routes or symbol rosters — those are the graph's.
+- **Objects:** {…}
+- **Code roots:** {…} — directories, one per package the machine spans
+- **Seams:** {…} by name
+- **Checklist:** `tests/{system}.md`
+- **See also:** {neighbour}: {why}
+
+No tables, routes or symbol rosters — those are the graph's.
 ```
 
 ### Marking what is decided and unbuilt
 
-Where a stage is decided and not built, wrap its prose in `<!-- UNBUILT:START — {what, where decided, the evidence it is not built} -->` … `<!-- UNBUILT:END -->` and say in What it promises what runs instead. A design decided *against* carries no marker.
+Where a stage is decided and not built, wrap its bullets in `<!-- UNBUILT:START — {what, where decided, the evidence it is not built} -->` … `<!-- UNBUILT:END -->` and say under Promises what runs instead. A design decided *against* carries no marker.