@nurix/etna 0.20.25 → 0.20.26

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

@@ -0,0 +1,174 @@
+# Hand-over (`docs/history/handovers/YYYY-MM-DD-{slug}.md`)
+
+Record. Use for: the account an **unattended or multi-session build** leaves the person who owns it — written by the orchestrating session as its last act, before the owner's first decision, read in one sitting. It is a **decision queue, an undo manual and a resume file**, in that order: is it done · what must I decide today · what escaped the repository and how do I undo it · can I see it working · what was decided for me and how do I overturn it · what is red and whose it is. Everything below the divider is for the next session, not the owner. It is not a pull-request description (which argues for a diff), not a changelog entry (which carries refinement context) and not a plan (which is frozen). It is mutable while `status: open` — a successor that re-proves a state line corrects it in place and appends one Timeline row — and **freezes when the owner has acted on § 1 (`status: accepted`)**; a correction after that is a new dated hand-over linking back. Raw artefacts (plans, hand-offs, notes) live in a same-named folder beside it.
+
+Required: **Verdict**, **Decide today**, **Live-world ledger** (even when empty), **See it work**, **Decided for you**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Left alone, Discoveries, Debt, Cost, Timeline.
+
+**Reading order is act → verify → understand.** Owner half, ~20 minutes: Verdict (1) · § 1 (2) · § 2 (2) · § 3 (10, at the product) · § 4 (3) · § 5–6 (2). Successor half, read when the job arrives: § 8–14 (~10).
+
+````markdown
+---
+type: handover
+status: {open | accepted}
+date: {YYYY-MM-DD}
+as_of: {YYYY-MM-DDTHH:MM±TZ}
+as_of_commit: {sha}                # every § 9 claim is true of THIS commit and no other
+verdict: {done | done-needs-calls | partial | stopped-at-budget | failed}
+decide_today: {N}   irreversible_acts: {N}   decisions: {N}   red_mine: {N}   open_loops: {N}
+deployed:
+  - { plane: {dev|staging|production}, artifact: {name}, version: "{id}", by: {automatic|manual}, verify: "{command}" }
+prs:
+  - { n: {N}, base: {branch}, state: {open|draft|merged}, action: "{what the owner does}" }
+---
+
+# Hand-over — {what was built}, {YYYY-MM-DD}
+
+**{VERDICT TOKEN}.** {One sentence in the product's words: what exists and what a person can now do.}
+
+| | |
+| --- | --- |
+| Built | {N} units · {N} plans · ledger rows {N}, discharged {N}, blocked {N} |
+| Proof | {N} tests pass / {N} fail — on `{sha}`, verified {HH:MM} |
+| Decide today | **{N}** — § 1 |
+| Touched the live world | **{N}** acts, **{N}** you cannot undo — § 2 |
+| Red | {N} mine · {N} pre-existing · {N} environment — § 5 |
+| See it work | {N} min — § 3 |
+| Taken alone | {N} decisions, {N} stops filed of {N} — § 4 |
+
+**Start here:** `{the one command that brings the reader's machine to the state everything below describes}`
+**If you only act on one thing:** {act} — by {YYYY-MM-DD}, or {consequence}.
+
+## 1. Decide today
+
+| # | Decision or act | Why today | If you say nothing | Decide by | Do it (exact) | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | {one line, no mechanism} | {what a week costs} | {the outcome silence produces} | {date} | `{command}` / {PR link} / {UI path} | `{path:line · sha · PR}` |
+
+## 2. Live-world ledger
+
+Everything that left the repository, hardest to undo first. Verified {HH:MM}.
+
+| # | Act (past tense, dated) | Target (system + id) | Command | Reversible | Undo — exact | Evidence / backup + expiry |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | {what was done, {YYYY-MM-DD HH:MM}} | {named system} | `{exact}` | {no / with loss / yes} | `{command}` or {runbook path} — {or "forward only: …"} | {artefact · where · when it expires} |
+
+**Did not happen, and the proof:** {claim} — `{command}`.
+
+## 3. See it work in ten minutes
+
+**Before you start:** `{command}` · **Sign in as:** {who} · **Total:** {N} min
+
+| # | Do (URL → click) | You should see | It proves | If not |
+| --- | --- | --- | --- | --- |
+| 1 | {url} → {action} | {an observable a person can be wrong about} | {unit from § 6} | {§ 5 row, or "file it — new"} |
+
+## 4. Decided for you
+
+Each was taken because waiting would have stopped the run. Sorted by cost to reverse.
+
+| # | I decided | Instead of | Why | Authority | Landed at | Overturn — exact | If you say nothing | Hardens when |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| D-1 | {the ruling} | {the alternative, fairly} | {the constraint} | {owner said so HH:MM "…" / auto-ruled as recommended / taken alone — by {agent · model}} | `{file:line}` | `{edit or command}` | {default} | {event} |
+
+*Bulk: {N} per-plan questions ruled `as recommended, overturnable` — index at `{path}`. Only rows costing more than one commit to reverse are listed.*
+
+## 5. Red board
+
+| What's red | Where | Mine? | Proof | Blocks | Next step + owner |
+| --- | --- | --- | --- | --- | --- |
+| {test or command} | `{file:line}` | {mine / pre-existing / environment} | `{the command or stash that settled it}` | {what it stops, or nothing} | {act} — {who} |
+
+## 6. What was built
+
+| Unit | What it does for a person | Landed | Proof |
+| --- | --- | --- | --- |
+| {name} | {one clause, behaviour before mechanism} | {branch · PR · release} | {suite + counts, or "driven only", or empty} |
+
+## 7. Left alone
+
+| Thing | State | Why untouched |
+| --- | --- | --- |
+
+---
+
+*Everything above is for the owner. Everything below is for the next session.*
+
+## 8. Proof
+
+| Unit | Promise (clause) | Code @ | Pinned @ | Independent? | Rows p/o/b | Gap |
+| --- | --- | --- | --- | --- | --- | --- |
+| {plan} | {ruling n — five words} | `{sha7}` | `{sha7}` | {yes / **no — {who did both}**} | {n}/{n}/{n} | {G-n / —} |
+
+| # | Claim that is not proven | Why | What would prove it | Sev |
+| --- | --- | --- | --- | --- |
+| G-1 | {stated as the build would state it} | {blocked row / never driven / self-authored pin / no suite on this head / not recorded} | `{exact command}` | P{0-3} |
+
+## 9. State
+
+Present tense; every row true of `as_of_commit`, and every row re-provable by its own command.
+
+| Repo · branch | HEAD | vs upstream | Working tree | Worktrees | Re-prove |
+| --- | --- | --- | --- | --- | --- |
+
+| Plane | Artifact | Version | Deployed by | Re-prove |
+| --- | --- | --- | --- | --- |
+
+| Store | Env | Last destructive act | Backup + expiry | Re-prove |
+| --- | --- | --- | --- | --- |
+
+| Process / connection / token | Where | State | Check or stop |
+| --- | --- | --- | --- |
+
+## 10. Open loops
+
+| # | Loop | Whose | Next command or ask | Blocked by | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| L-1 | {present tense} | {session / owner / external} | `{command}` or {the question, with the default in force} | {id / —} | `{path:line}` |
+
+## 11. Discoveries — do not pay for these twice
+
+| # | Trap | The truth | Cost paid | Guard |
+| --- | --- | --- | --- | --- |
+| X-1 | {what it looks like from outside} | {present-tense fact} | {hours / runs} | `{command}` or `none — {what would hold it}` |
+
+## 12. Debt and can wait
+
+| # | What | Why not now | Re-open when | Parked at |
+| --- | --- | --- | --- | --- |
+| T-1 | {one line} | {the ruling} | {a trigger, not a date} | `{backlog row · issue · path:line}` |
+
+## 13. Cost
+
+**Wall-clock:** {Nh Nm} ({start} → {end}) · **unattended:** {Nh} · **Agents:** {N} · **Tokens:** {N | unmeasured — {what would measure it}} · **Rework:** {what was thrown away} · **Stops filed:** {N} of {N}
+
+## 14. Artefacts & mandate
+
+| Path | Holds | Volatile | Safe to delete after |
+| --- | --- | --- | --- |
+
+**Corpus:** {tracked at `{path}` @ {sha} | **UNTRACKED at `{path}` — {what would durably hold it}**}
+**May, alone:** {one line each} · **Must file or ask:** {one line each} · **Never:** {one line each}
+
+## 15. Timeline
+
+<!-- Append only. Never rewritten. -->
+
+- {YYYY-MM-DD HH:MM} — {event} (`{sha7}` / PR #{n})
+````
+
+## Field rules
+
+- **Verdict (≤14 lines).** One token from the closed set — `DONE` · `DONE, NEEDS YOUR CALLS` · `PARTIAL` · `STOPPED AT BUDGET` · `FAILED` — first in the body; a paragraph before it is a format violation. The scoreboard is always the same seven rows in that order, and a zero is written `0` — `Touched the live world: 0` is one of the most valuable lines the file can carry. `Start here` is exactly one command.
+- **§ 1 Decide today (≤7 rows).** Owner-only acts, sorted by cost of deferral descending. `Do it (exact)` is a command, a link or a literal UI path — `git revert -m 1 {sha}`, never "revert the merge". `If you say nothing` is mandatory and honest. **A decision has an alternative and belongs in § 4; an act outside the repository with no alternative is a chore and belongs here.**
+- **§ 2 Live-world ledger.** Required even when empty — `none — nothing left the repository`, with the command that proves it. Sorted hardest-to-undo first, never chronologically. `Reversible` takes three values: `no` states what now exists in the world, `with loss` names what is lost, `yes` carries the command. An act reversible only forward (redeploy, reseed, a superseding publish) is `no`, and the forward path goes in `Undo`. A backup states its expiry; copying a volatile backup somewhere durable is row 1 of § 1.
+- **§ 3 See it work (≤6 steps, ≤10 min).** Every `You should see` is an observable a person can be wrong about — a number, a named control, a status code — never "the page loads". It is the only check the owner performs with his own eyes rather than on the build's word.
+- **§ 4 Decided for you (≤10 rows).** Sorted by cost to reverse. `Authority` takes exactly three values — the owner said so (with the words and the time) · auto-ruled as recommended · taken alone — recorded per decision, never per run: it is the distinction an unattended run exists to preserve. `Overturn` is an edit or a command. `Hardens when` names the event after which reversal stops being cheap. A ruling with no reversal path is a constraint, not a decision — it moves to § 12.
+- **§ 5–7.** One home per fact: a red appears in § 5 even when a decision caused it, and the decision cites the row. `Mine?` is proved by the command or stash in `Proof`; `mine` is the default when no proof is offered. § 6 leads with behaviour, not plan slugs. § 7 exists so an owner scanning the repository does not mistake somebody else's branch for the run's debris.
+- **§ 8 Proof.** **An unproven claim is an empty cell, never a sentence** — prose has no empty cell to scan for. `Independent?` reads `no` whenever one agent authored both the code and its pin, or found, fixed and pinned the same defect, and names who. Ledger counts are parsed from the plan, never quoted from an agent's summary, so `blocked` cannot hide inside "discharged". Every `G-n` names the command that would close it.
+- **§ 9 State.** Present tense; a claim that cannot be re-proved by its `Re-prove` command does not belong here — it moves to § 15 as a dated event. Volatile things (`/tmp`, pid files, ports, tokens, browser connections) declare a lifetime and the command that makes them durable.
+- **§ 10–12.** A loop is a runnable command or a named question, never a noun phrase and never "investigate"; one needing a person's judgment states the question and the default in force. A discovery is a present-tense fact with a guard — "Workers Builds does not fire on a `dev` merge", not "we found that it didn't"; `none — {what would hold it}` is an honest guard that feeds the backlog. Debt names where it now lives, so this file can be deleted without losing it.
+- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would have measured it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
+- **Ids are stable and run-global** — `D-`, `G-`, `L-`, `X-`, `T-` — so a PR comment or a successor cites a row instead of re-describing it. A withdrawn row keeps its id and states what disproved it.
+- **Evidence is an address that outlives the run** — `path:line`, a 7-char sha, a PR number, a URL, or a command. A branch name is not a pointer; a `/tmp` log is not evidence — copy it into the record folder first.
+- **Blanket claims are banned.** "All suites green", "every ledger discharged", "nothing was deployed" carry a count and the sha they are true of, or they become a `G-n` row.
+- **The last act before showing the file is a contradiction pass**: the scoreboard against § 2, § 6 against § 1, every count against its source, every `{…}` resolved. An unresolved placeholder in an action cell is a defect of the same class as a broken command.

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

@@ -1,6 +1,6 @@
 # Operations Procedure (docs/operations/{procedure}.md)
 
-Truth document. Use for: any **recurring** procedure — setup, development, deployment, maintenance. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
+Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
 
 A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
 

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

@@ -1,131 +1,65 @@
 # Package Documentation (docs/architecture/packages/{package}.md)
 
-Truth document. Use for: **one workspace package — what it is and how it behaves**. One file per package, named for the package's folder (`packages/cli/` → `docs/architecture/packages/cli.md`). It states the package's own machinery: its manifest and published identity, its build and entry point, its source layout, and every behavior of its tree that no system or feature document claims.
+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 package document is the residual owner of its own tree.** Its `owns:` is the whole package glob — `["packages/{name}/**"]` — and that glob is the *broadest* claim anything makes on those paths, so it loses to every narrower one. A system document naming `packages/{name}/src/server/runs/**` wins those files by specificity; a feature document naming `packages/{name}/src/surfaces/apps/**` wins those. What is left after every narrower claim is what this document describes, and it describes that exhaustively. **The residual claim is a promise of completeness, not of scope**: a package document with nothing left after the systems and features have claimed their subtrees is still owed — the manifest, the build, the entry, the layout, the test wiring and the deploy shape are always residual.
+**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.
 
-**Two rules bind the glob.** Neither genre may claim a path another document claims at **equal specificity** — equal-specificity overlap is an ownership conflict to resolve before either document ships, not a duplication to live with. And every glob **matches at least one file on disk** at `status: active`; a projected glob is permitted only at `draft`, and is confirmed when the document flips.
+**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.
 
-**How this differs from its neighbours.** A **feature** document covers one capability or one page a person names, and owns that surface's globs. A **system** document covers one machine that spans packages, and owns the subtrees that machine is made of. A **package** document covers one unit of distribution — a manifest, a build, a binary or a bundle — and owns what is left of it. The unit is the package boundary, so if the subject you are writing about does not stop at a `package.json`, it is not this genre. Route it: one screen → feature; one machine crossing two packages → [system](system.md).
+**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 vs optional.** Required in every package document: the **frontmatter**, the **opening** (title, identity line, what the package is), the **ownership boundary** (what this document does not describe and which document does), at least one **behavior section**, **Files**, and **Related**. Everything else is optional — include a section only when the package has something real to put in it. A package with no test wiring of its own gets no verification section; a package that nothing else in the repo consumes says so in one line rather than growing a Consumers section. A short accurate document beats a full skeleton with empty headings.
-
-Package documents run long because they are exhaustive over their residue — roughly 150 to 600 lines is the working range, and the top of that range is a package holding an application, not a document that has lost discipline.
+**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.
 
 ```yaml
 ---
-owns: ["packages/{name}/**"]                      # required — the whole package tree, one glob; the residual claim
-keywords: [package-name, binary, build, entry]    # required — discovery terms: the npm name, the binary, the surfaces
-status: active                                    # required — active | draft | deprecated
-applies: [docs/architecture/common/api.md]         # optional — cross-cutting doctrine this package is BOUND by (obligation, not a bibliography); omit when none
-type: package                                     # required tooling key — genre stamp; preserve on edits, never narrate
+type: package
+status: active
+objects: [nustack cli, device credential]        # required — the objects this package designs or ships
+owns: ["packages/{name}/**"]                     # required until the graph computes ownership — the residual claim
+applies: [docs/architecture/common/api.md]       # optional
 ---
 ```
 
-> A package document carries no `module:` — a package is already a bounded unit, and a second label
-> for the same boundary is a thing to keep in sync for nothing. `last-reviewed:` is optional and,
-> like `type:`, is tooling metadata: preserve it, never narrate it.
-
 ```
 # {package-path} — {the one-line role}
 
-**Package:** `@scope/name` · **Ships as:** {a public npm package with one binary `x` / a private
-source-first workspace package / a Worker on {domain}} · **Source:** `packages/{name}`
-
-{One paragraph: what this package is and the job it does in the product. Name what it holds that
-nothing else does, and what it deliberately does not hold. Written for someone who has not opened
-the folder.}
-
-{One paragraph: the ownership boundary. This document is the residual owner of `packages/{name}/**`;
-these subtrees are claimed at higher specificity by these documents and are pointed at, not
-restated. Where the routing is more than a sentence, make it the table below instead.}
+**Package:** `@scope/name` · **Ships as:** {…} · **Source:** `packages/{name}`
 
-{Optional, and worth its line whenever the body names paths: "Paths below are relative to
-`packages/{name}/` unless they name another package."}
+{One sentence: the job this package does in the product, for whom.}
 
-## What is built and what is not
+## Why it exists
 
-{Optional — required in substance whenever some of the tree does not run. State plainly which
-halves exist and which do not, with the source evidence for each claim, and say what a reader who
-runs the unbuilt half will actually observe. A package whose subject as a whole does not run is
-`status: draft` and says so here; a scoped gap in a working package stays `active` and takes an
-UNBUILT marker at the section that describes the gap.}
+{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.}
 
-## Ownership — packages/{name}
+## Ownership
 
-{Optional — use the table form when more than two documents claim subtrees of this package.}
-
-**The package glob is the residual claim.** A system or feature document's `owns:` is more specific
-and wins by specificity, so this document describes only what none of them claims, and points to
-each for the rest.
-
-| Path | What it is |
-| --- | --- |
-| `src/index.ts` | {the residue: the entry, the dispatch, the layout} |
+This document is the residual owner of `packages/{name}/**`. Claimed at higher specificity:
 
 | Subtree | Stated and owned by |
 | --- | --- |
 | `src/{machine}/**` | [{system}](../systems/{system}.md) |
-| `src/surfaces/{x}/**` | [{feature}](../../features/{feature}.md) |
 
-## {Behavior sections — named for this package's own machinery}
+## How it is used
 
-{The body. There is no fixed section list, and inventing one would be a lie: what a CLI owes
-(commands, the store, the on-ramp) and what a UI package owes (the host port, the frame, the route
-zones, the component pool) share no headings. Name each section for the thing it describes and
-order them the way a reader meets them — identity and build first, then the surface, then what it
-writes, then how it is verified. Prefer a table wherever the content is a roster (commands, routes,
-exports, bindings, environment variables); prefer prose wherever the content is a rule and its
-reason. State mechanisms and contracts, never pasted implementations.}
+{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.}
 
-## Tests
+## What was decided
 
-{Optional. What proves this package, and what each suite pins — a `Suite | Pins` table, or the
-commands a reader runs. A package whose verification is a build check names the check instead
-(`## Checks`, `## Build and test`); a package with no suite of its own says so in one line in the
-build section and carries no heading here.}
+{Themed paragraphs.}
 
-## Files
+## What it promises
 
-| Path | Role |
-| --- | --- |
-| `packages/{name}/package.json` | {the manifest: the bin, the exports, the scripts} |
-| `packages/{name}/src/index.ts` | {the entry} |
+{What a consumer can rely on and what the package refuses; checkable sentences, grouped.}
 
-{One row or bullet per file this document owns, with what it holds — the roster a reader uses to go
-from the document to the code. Close with the inverse where it helps: "Read here, owned elsewhere:"
-naming the paths the body describes but another document claims.}
+## Known gaps
 
-## Related
+{One paragraph, only when needed.}
 
-- [`{system}.md`](../systems/{system}.md) — {why a reader of this document would open that one}
-- [`{other-package}.md`]({other-package}.md) — {the seam between the two}
-- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this package answers to}
-```
-
-### The identity line
+## For the agent
 
-The bolded `·`-separated run under the title is what a reader checks first, and it answers three
-questions no body section should have to: **what is this called** on the registry or in the
-workspace, **how does it ship** (a public tarball, a private source-first package, a deployed
-Worker, a signed installer), and **where is its source**. A package that ships two artifacts names
-both. Add a `**Crate:**` or `**Deploys as:**` term where the package has one; drop any term that
-would restate the title.
+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
 
-Where the package holds code for a design that is decided and not built — or a surface whose other
-half does not exist — wrap the prose in a marker so the gap is machine-findable and its evidence
-travels with it:
-
-```
-<!-- UNBUILT:START — {what is decided, where it is decided (an AD or an owner ruling), and the
-source evidence that it is not built: the file that does not exist, the route that is not mounted,
-the binding that is not declared} -->
-{the prose describing the unbuilt half}
-<!-- UNBUILT:END -->
-```
-
-**A design that was decided *against* carries no marker.** A marker means the work is owed and
-absent; using one for a rejected design turns the register of debt into a register of opinions.
-Say in prose that it is not built and not owed, and name the decision that settled it.
+`<!-- UNBUILT:START — {…} -->` … `<!-- UNBUILT:END -->` around the prose for a decided, unbuilt half; a design decided *against* carries no marker.

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

@@ -1,104 +1,142 @@
-# Project Root README
+# Project Root README (/README.md)
 
-Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
+Truth document. Use for: the repository root `/README.md`. It opens outward — what the product does, for whom, and where it runs, in a user's terms — then turns inward for the team and coding agents: what state the repo is in, how it works, what its parts are and what must not break, then routes every other question into `docs/`. The outward part comes first because it is what a stranger reads; the inward part is longer because it is what the team uses. **It hosts nothing it can link to.** It is distinct from `docs/README.md`, which describes the folders of the docs tree, and from `CLAUDE.md` / `AGENTS.md`, the standing rules an agent loads. It points at both and restates neither.
 
-### Strategy
+### What it carries
 
-The root README answers, in order:
+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. **What is this?** — one to two sentences, no marketing claims
-2. **What do I get if I install it?** — capability families
-3. **What's it built on?** — terse stack list with versions
-4. **How do I run it?** — the three or four scripts that matter
-5. **How is it laid out?** — directory tree, one-liner per significant folder
-6. **How do I extend it?** — numbered contribution checklist
-7. **What state is it in?** — pre-publish, beta, stable, internal
+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.
+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.
+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.
+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.
 
-Skip any section that doesn't apply. Don't pad to fill the template.
+### What it leaves out
+
+| Left out | Lives in |
+| --- | --- |
+| Getting started, install, prerequisites, env files, first run, troubleshooting | `docs/operations/setup.md` |
+| Stack: technologies, what each is for, where its version is pinned | `docs/operations/setup.md` § Stack. Why it was chosen goes in `docs/architecture/` |
+| Directory or file tree | `docs/structure.md`, the only tree |
+| Daily loop, watch modes, per-package traps | `docs/operations/local-development.md` |
+| Contributing procedure, branch model, commit rules | `CLAUDE.md` and `docs/operations/` |
+| Feature list, news, "what's new", roadmap, changelog | `docs/features/`, `docs/history/` |
+| Badges, logos, images, screenshots, social links, sponsors, hand-written TOC, license text, superlatives | Nowhere. The outward sections are plain prose too. Agents cannot read them and the team does not need them. License is one line or absent |
 
 ### Writing rules
 
-- **Sentence-case headings.** "Getting started", not "Getting Started".
-- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
-- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
-- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
-- **Directory tree as a code block**, not a nested markdown list.
-- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
-- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
-- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
+- **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.
+- **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.
+- **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".
+- **State rules, don't argue them.** One line each. The reasoning lives in the linked doc, and agent process rules stay in `CLAUDE.md`.
+- **Commands come from the repo.** Detect the package manager from the lockfile (`pnpm-lock.yaml` gives pnpm, `yarn.lock` gives yarn, otherwise npm). Use only scripts that exist, each with a trailing comment saying what it does.
 
 ### Template
 
 ```markdown
-# {package-name}
+# {Project name}
 
-{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
+{Two or three sentences in a user's terms: what the product is, where it runs, what using it is like.}
 
-## What's in the box
+## What it does
 
-- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
-- **{Family 2}** — {what's in it.}
-- **{Family 3}** — {what's in it.}
+{The core loop as a person meets it: what they bring, what the product does, what they get back and what record it leaves.}
 
-The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
+{What surrounds the loop: the capabilities a team needs to run it, named plainly.}
 
-## Stack
+{How it follows the person across surfaces: CLI, desktop, integrations, agents' doors.}
 
-- {Framework} {version} · {Language} {version}
-- {Build tool} {version}
-- {Other load-bearing deps}
+{Who it is for, and what it deliberately is not.}
 
-## Getting started
+## Where it runs
 
-\`\`\`bash
-{pm} install
-{pm} run dev        # what it does (port, URL)
-{pm} run build      # what it does
-{pm} run preview    # what it does (omit if not applicable)
-\`\`\`
+{Addresses; distributed artifacts and where they publish; where identity comes from; whether a self-hosted edition exists.}
 
-{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
+---
 
-## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
+The rest of this page is for the team and for coding agents working in this repository. {What lives in this repo and what lives elsewhere.} {One sentence: the sections below route every other question into docs/.}
 
-{Brief description of the dev/runtime surface.}
+> **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
 
-| {Thing}              | {What it shows / does} |
-| -------------------- | ---------------------- |
-| `{route or command}` | {description}          |
+## How it works
 
-## Layout
+1. **{Stage}**: {what happens, naming the mechanism only where it explains the step}.
+2. **{Stage}**: {…}.
+3. **{Stage}**: {where state lives}.
+4. **{Stage}**: {the outbound effect: what is written, deployed or returned}.
 
-\`\`\`
-src/
-├── {entry-file}        # {purpose}
-├── {folder}/           # {purpose}
-│   └── ...
-└── {folder}/           # {purpose}
-\`\`\`
+{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
+
+{One or two sentences: the workspace shape and where each unit's design document lives.}
 
-## Adding a {primary unit}
+| Path | Role | Owning doc |
+| --- | --- | --- |
+| [`{packages/unit}/`]({packages/unit}/) | {one line: what it is and who consumes it} | [{doc}](docs/architecture/packages/{unit}.md) |
+| [`{packages/unit}/`]({packages/unit}/) | {one line} | [{doc}]({path}) |
+| [`{top-folder}/`]({top-folder}/) | {one line; "generated" or "reference only" where true} | — |
 
-1. {Drop the source under the right family/folder.}
-2. {Re-export from the public surface.}
-3. {Wire into the playground / example app / test harness so reviewers can see it render.}
-4. {Document any divergence from upstream in `docs/{...}`.}
+{One sentence each for the top folders that are not packages — `registry/`, `scripts/`, `docs/` — with their owning doc.} Where every doc lives: [docs/structure.md](docs/structure.md).
 
-## Styling ← optional; replace with whichever cross-cutting concern matters most
+## Rules that bite
 
-{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
+{One sentence saying these are stated here and argued in the documents they point at.}
 
-## Status
+- **{Invariant}**: {the rule, one line}. → [{source}]({path})
+- **{Boundary}**: `{path}` is the only {public | published} surface; everything else is internal.
+- **{Never-edit paths}**: `{path}` is {generated by `{command}` | protected}; edit {the source} instead.
+- **Not here:** {a non-goal stated as a refusal}.
 
-{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}
+## Where to go
 
-## License
+| I want to… | Go to |
+| --- | --- |
+| 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) |
+| Understand the design | [docs/architecture/](docs/architecture/) |
+| Change a feature | [docs/features/](docs/features/), found through the ownership index |
+| Change a contract ({db schema · wire envelope · auth · events · env}) | [{contract doc}]({path}), boundary-checked before the change |
+| Ship or release | [docs/operations/{deployment}.md](docs/operations/{deployment}.md) |
+| Place a new doc | [docs/structure.md](docs/structure.md) · [docs/README.md](docs/README.md) |
+| See what changed and what is open | [CHANGELOG](docs/history/CHANGELOG.md) · [backlog](docs/history/backlog.md) |
+| Work here as a coding agent | [CLAUDE.md](CLAUDE.md) ([AGENTS.md](AGENTS.md) for other runtimes): load before any edit |
 
-{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
+## Everyday commands
+
+\`\`\`bash
+{pm} {typecheck}     # {what it checks}
+{pm} {test}          # {the unit suite, from a cold shell}
+{pm} {gate}          # {what a change must pass before it is pushed}
+\`\`\`
+
+`{pm} --filter <unit> run` lists a unit's own scripts.
+
+{License, one line, e.g. "UNLICENSED, internal use only."} ← optional
 ```
 
 ### Baseline scaffolding behavior
 
-The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
+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.
+- **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.
+
+It drops every section it cannot fill concretely.
 
-**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.
+**It never overwrites an existing root README.** If one is present, even sparse or outdated, the baseline leaves it untouched and raises a `note:` row proposing the reshape. Reshaping is a separate, explicit request. When it runs, each removed section moves in the same change: getting-started, install and env content and the Stack go to `docs/operations/setup.md`, a drawn tree becomes the Map (the tree itself stays in `structure.md`), and a contributing checklist goes to `docs/operations/`. Nothing is deleted without a home.