geneseed 3.1.1 → 3.1.3

package/docs/extending.md

@@ -1,6 +1,5 @@
 # Extending — what it costs to change this tool
 
-`docs/limits.md` is the standing answer to *"what does this tool not prove about itself?"*.
 This file is its companion: **"what does it cost to add one thing?"** — one invariant, one
 doctrine rule, one skill, one plugin, one hook verb, one doc page, one theme, one screen.
 
@@ -33,7 +32,7 @@ Three seams, and almost every question about "where do I edit?" resolves to one
 Two rules follow from the table and they cause most of the surprises:
 
 - **Nothing propagates by itself.** A bundle is a *render*. Editing `src/` changes nothing on any
-  machine until something re-emits (`js/emit.mjs:362` re-fingerprints, `js/status.mjs:80`
+  machine until something re-emits (`js/build/emit.mjs:362` re-fingerprints, `js/inspect/status.mjs:80`
   reports the drift).
 - **`docs/web/` is data, `web/src/` is code.** A new documentation page is one file and no
   rebuild. A new screen is a new hashed chunk and a mandatory `web/dist` commit.
@@ -47,14 +46,14 @@ three-tier split added — `{N_ONTOLOGY}` (the ontology's sections), `{N_PACKS}`
 packs). `{N_LAWS}` is the **invariant** count and nothing else; there is deliberately no token
 meaning "the whole constitution", because `proseMirrorProblems` holds README and `SHIPPED.md`
 prose to that same number and a token that quietly meant something wider would put the docs and
-the gate at odds with no way to re-bless either.
+the gate at odds.
 
 ⚠ **Only a `kind: "concept"` page is substituted.** A `markdown`-kind page renders `{N_PACKS}`
 literally, on the screen, as those nine characters.
 
 Typing a literal number into a `docs/web` page is caught by `proseMirrorProblems`. The README
 badges and prose, and the `N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written
-exceptions — and each has its own arm in `js/doctor.mjs` (`countTableProblems` walks the five
+exceptions — and each has its own arm in `js/inspect/doctor.mjs` (`countTableProblems` walks the five
 badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` holds the prose).
 
 ---
@@ -94,9 +93,10 @@ cd web && npm ci && npm run lint && npm run format:check && npm test && npm run
 
 Notes that matter:
 
-- The root `package.json` has **no `scripts` key**, and no pre-commit hook, Makefile or justfile
-  exists either. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run by
-  hand with the glob above.
+- The root `package.json` has exactly one script, `lint`, and no pre-commit hook, Makefile or
+  justfile exists. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run
+  by hand with the glob above. `npm ci` once per clone installs the devDependencies `lint` needs
+  — it pulls no runtime dependency, because there are none.
 - `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N ≥ 500`)
   because `node --test` over a glob that matches nothing prints `# tests 0` and **exits 0**. Node's
   default reporter changed between majors, which is how a green 1043-test suite once reported zero.
@@ -166,7 +166,7 @@ Five files, none of them a count. This is the slot most new material belongs in,
 on purpose so that the invariant slot stays scarce.
 
 1. `src/doctrines/<pack>.md` — **append** `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}` plus
-   the body. Two gates in `constitutionProblems` (`js/doctor.mjs`) sit on this: the pack named in
+   the body. Two gates in `constitutionProblems` (`js/inspect/doctor.mjs`) sit on this: the pack named in
    the *heading* is what addresses the rule (not the filename, so a rule filed in the wrong file is
    reported rather than silently renamed), and ids must run **contiguously from 1**, so appending
    at the end is the only place `n` is free. Packs are numbered independently — nothing outside
@@ -179,7 +179,7 @@ on purpose so that the invariant slot stays scarce.
 3. Seed the fourteen themes:
 
    ```bash
-   node bin/geneseed.mjs --sync-themes
+   node bin/build-driver.mjs --sync-themes
    ```
 
    ⚠ Four spellings of this command are in circulation and two of them fail — `doctor`'s own tip
@@ -216,13 +216,10 @@ a defect.
 Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions:
 
 - `--footprint` defaults to **lean**, and lean keeps only the heading plus the first sentence
-  (`terseBlocks` in `js/render.mjs`). A clause added to the second paragraph is invisible in the
+  (`terseBlocks` in `js/build/render.mjs`). A clause added to the second paragraph is invisible in the
   default build. Amend the first sentence, or the amendment does not exist for most installs. The
   same is true of a doctrine rule; it is **not** true of the ontology, which ships whole at both
   footprints.
-- ⚠ **Rule I is frozen.** `LEX_I` is one of seven theme keys recorded byte-for-byte in the
-  primitives corpus (§5.2). Retitling Rule I in any theme reddens a snapshot that cannot be
-  re-blessed.
 
 ### 2c — Adding an INVARIANT
 
@@ -231,7 +228,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
 
 1. `src/laws/universal.md` — **append** `### {{LAW}} <roman> — {{LEX_<roman>}}` plus the body.
    Never insert: the `{{LAW}}` cross-references counted above live all over `src/`, plus hardcoded
-   citations in `js/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference
+   citations in `js/hosts/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference
    against the canon**. Renumbering silently rewires every one of them.
 2. `themes/_TEMPLATE.json` — add `LEX_<roman>` in template order. Gated, as in §2a step 2:
    `constitutionProblems` holds `LEX_I..LEX_IX` as an **equality** across all fifteen files (the
@@ -239,7 +236,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
    arm exists because the renumber left `LEX_XXII`, `LEX_XXIII`, `LEX_XXIV` and `LEX_XXXVI` behind
    in every file and parity was silent — they were absent from nowhere.
 3. `--sync-themes`, then restyle all fourteen by hand (§2a step 3).
-4. `LAW_CLASS` in `js/inventory.mjs` — one of the six in `LAW_CLASSES` beside it.
+4. `LAW_CLASS` in `js/inspect/inventory.mjs` — one of the six in `LAW_CLASSES` beside it.
 5. `LAW_META` in `web/src/pages/Laws.jsx` — same class, plus the one-line Principle. Note the map
    is keyed by **arabic** number where `universal.md` heads with a Roman numeral. **This copy
    exists nowhere else**; a rule absent here renders with a blank description. It is why that one
@@ -271,13 +268,13 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 1. `src/doctrines/<pack>.md`, opening with its lead line — `**{{PACK_<NAME>}}** — how … .` A pack
    file `PACK_ORDER` names but cannot read, or one carrying no `### {{DOCTRINE}} <pack> <n>`
    heading at all, is a refusal.
-2. `PACK_ORDER` in `js/checkout.mjs` — the registration, and the render order. It is **narrative,
+2. `PACK_ORDER` in `js/build/source.mjs` — the registration, and the render order. It is **narrative,
    not alphabetical** (craft → rigor → ops → process); discovery sorts alphabetically and the
    renderer refuses a `.md` under `src/doctrines/` that `PACK_ORDER` does not name, rather than
    skipping it.
 3. `PACK_<NAME>` in `themes/_TEMPLATE.json` and all fourteen voices. Unlike `DOC_*`, this family is
    held only by `themeParityProblems` — presence, across the voices, template excluded.
-4. `DOCTRINE_BLURBS` in `js/setup.mjs` — the one-line description an installer sees in the wizard,
+4. `DOCTRINE_BLURBS` in `js/maintain/setup.mjs` — the one-line description an installer sees in the wizard,
    and the only place a pack is ever explained to them. Missing entries fall back to the bare name.
 5. `harness.config.json` if the pack should be on by default; `constitutionProblems` refuses a
    `doctrines` array naming a pack this checkout does not ship.
@@ -286,7 +283,7 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 
 ## 3 — Adding a SKILL or an AGENT
 
-**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/emit.mjs`) *aborts the
+**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/emit.mjs`) *aborts the
 build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
 nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs:265` proves a refused
 emit leaves the prior install intact.
@@ -299,20 +296,20 @@ emit leaves the prior install intact.
    Gated both ways: a row with no file, and a file with no row.
 3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
    an unstyled placeholder.
-4. **Skills only** — `SKILL_CLASS` in `js/inventory.mjs`. Gated both ways, inside
+4. **Skills only** — `SKILL_CLASS` in `js/inspect/inventory.mjs`. Gated both ways, inside
    `countTableProblems`, which matters because the runtime fallback is silent: an unclassified
    skill renders as `build`.
 5. `registry.json` — a row keyed `skills/<name>` or `agents/<name>` with `status` ∈
    {`experimental`, `approved`, `deprecated`}, a semver `version`, a non-blank `owner`, an ISO
    `added`, and `last_verified: ""`. **This is the most forgettable step**: four hand-typed fields,
-   and the gate fires in both directions (`js/doctor.mjs:388-436`).
+   and the gate fires in both directions (`js/inspect/doctor.mjs:388-436`).
 6. `README.md` — the badge, the `**🤖 Agents** (N)` / `**🛠 Skills** (N)` count, and for a skill the
    `·`-separated name in the 🛠 row (that enumeration is gated two ways, unlike the laws' one).
 7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
 8. `doctor --all`, then the suite.
 
 **A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
-`VENDORED_SKILL_DIRS` (`js/native.mjs:37` — the literal is frozen in
+`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:37` — the literal is frozen in
 `tests/unit/authoring_gates.test.mjs:312`), write a `VENDOR.md` carrying `**Upstream:**`,
 `**Commit:**` (a 40-hex commit, never a moving branch) and `**License:**`, add the registry row —
 and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top level.
@@ -320,14 +317,13 @@ and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top le
 Two traps worth knowing before you write the spec:
 
 - **The word "Read-only" anywhere in an agent spec locks its emit.** It is a bare substring test
-  (`js/native.mjs:148`). The escape hatch is an explicit `<!-- bash: allow -->` marker, which
+  (`js/hosts/native.mjs:148`). The escape hatch is an explicit `<!-- bash: allow -->` marker, which
   re-opens bash on all three hosts.
 - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
   `web/src/pages/Skills.jsx:19` mirrors `SKILL_CLASS` with nothing comparing them (contrast
   `LAW_META`, which *is* cross-checked). Inventing a new *category* means editing that file —
   which drags in the `web/dist` rebuild — and an unknown category renders as Build with no warning.
 
-Adding a spec reddens no recording: none of the surviving snapshots contains a skill or agent name.
 
 ---
 
@@ -358,8 +354,8 @@ No `registry.json` row, no `package.json` edit — `files[]` ships `adapters/` w
 
 ⚠ **Read §5 first. A fifth hook verb has no green path today.**
 
-The mechanical part: implement `cmd<Verb>` in `js/hooks.mjs`; wire the command string in
-`claudeHookGroups` (`js/settings.mjs:434`, spelled `` `${run} <verb> …` `` — the gate scrapes that
+The mechanical part: implement `cmd<Verb>` in `js/hosts/hooks.mjs`; wire the command string in
+`claudeHookGroups` (`js/hosts/settings.mjs:434`, spelled `` `${run} <verb> …` `` — the gate scrapes that
 shape); add the entry to `bin/geneseed-hook.mjs:43` `VERBS` with **exactly two-space indent**; add
 a row to `js/cli-table.json` with a help string over 20 characters.
 
@@ -381,6 +377,55 @@ the page renders, wrong, with nothing red.
 
 ---
 
+## 4bis — Adding a RUNTIME DEPENDENCY
+
+**Short answer: you vendor it, or you do not add it.** A dependency arrives as tracked source under
+`js/vendor/<name>/`, imported by relative path, landing in the same `git merge --ff-only` as the
+code that imports it. It never comes from a registry at install time. `tests/unit/dependency_policy.test.mjs`
+gates this, and its header carries the long form.
+
+This is not conservatism. The npm route is *unbuildable* here, for three reasons that were measured
+rather than assumed:
+
+1. **Every fixture would die at module load.** `copyCheckout` lists the tree with
+   `git ls-files --cached --others --exclude-standard`, which honours `.gitignore`, and
+   `.gitignore` ignores `/node_modules/`. The copy is written outside the repository, under the OS
+   temp root, and the product is run out of it as a real child process — so Node's upward resolver
+   walk starts in temp and finds nothing. Eleven test files build such a copy. And this is not a
+   fixture defect to work around: a user's fresh `git clone` has no `node_modules` either. **The
+   fixture is that clone.** Giving the fixture something the real install lacks makes it stop
+   reproducing the failure it exists to catch.
+
+2. **The clone channel cannot install, and it is the only channel that would need to.** `geneseed
+   update` is `git pull` + rebuild. `npm ci` deletes `node_modules` before refetching, so a blocked
+   download leaves an install whose CLI cannot start — the one outcome the update must never
+   produce. `npm install` writes the tracked `package-lock.json`, so `preflight()`'s
+   `git status --porcelain` then reports a dirty tree and the *next* update refuses with "You have
+   local changes": a self-poisoning update. Meanwhile npm/npx installs already resolve
+   `dependencies` at install time and need nothing from us. There is no overlap between the channel
+   that would need a sync step and the channel where one could work.
+
+3. **The hook path pays per tool call.** `bin/geneseed-hook.mjs` loads on every tool call of every
+   agent session (~14 ms). A relative import costs no resolver walk; a bare one does.
+
+What vendoring costs, by contrast, is almost nothing: `files[]` already carries `js/` and the
+manifest partition already carries the `js/` prefix row, so a vendored subtree costs **zero**
+manifest lines and zero partition lines. The existing doctor gate already covers a bad drop, because
+`runDoctor` validates the pulled tree in a fresh interpreter before the rebuild.
+
+**The one exception, and it is not a loophole.** `adapters/` does not run in this tool's process — it
+ships into OpenCode's. A module the *host* provides is resolvable there and nowhere else, so
+reaching for one is legitimate. But it must be a **guarded dynamic import with a working degraded
+path**, never a static one: an older host that lacks it would otherwise fail the whole plugin at
+load instead of losing one capability. `geneseed-workflow.js`'s `@opencode-ai/plugin` is the shape
+to copy. The allow-list in the gate is two-sided — an entry nothing imports fails as loudly as an
+import nothing declares.
+
+**Before proposing one at all, price it.** At the time this was written there were 463 import
+specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the host-provided
+exception above. The invariant already held; it had simply never been written down. A library that
+would delete fewer lines than its vendored source adds is not a saving.
+
 ## 5 — The four things that are genuinely hard
 
 These are not checklist items. They are structural, and each one should be settled *before* the
@@ -398,34 +443,24 @@ already exempted a named `NATIVE` list; the hook half exempted nothing — so a
 failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
 correctly forbids deleting cells to pass.
 
-Both halves now filter through the same `NATIVE` list, and the reverse check refuses an
-exemption for a verb neither entry point carries. The argument is in `docs/declined.md` — the
-short version is that the reason those verbs have no cell (*the reference had nothing to compare
-against*) is the same reason a verb postdating the reference has none, so it is one exemption,
-not two. Nothing measurable was lost: the hook verb set is pinned twice more, from editable
-sources, twelve lines above.
-
-**To add a hook verb today:** implement `cmd<Verb>` in `js/hooks.mjs`, wire the string in
-`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then name the verb in
-`NATIVE` in **both** `tests/unit/hook_cli.test.mjs` and `tests/snapshot/cli_help.test.mjs` (they
-read each other's source, so one alone fails) and give it an absolute unit gate.
-
-### 5.2 ⚠ Seven theme keys are frozen byte-for-byte
+`NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
+than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
+carries — so a name that stops meaning anything fails rather than sitting there.
 
-`tests/__snapshots__/primitives/{posix,win32}.json` record `theme_preview` and `theme_flair`
-answers for all fourteen themes **and the template**. Those probes read the live `themes/*.json`
-at replay time, which pins:
+**To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
+`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
+absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
+to stay in step; there is one copy now, so there is nothing to keep in step.
 
-| Probe | Frozen keys |
-|---|---|
-| `theme_preview` | `TAGLINE`, `LOADED_SIGIL`, `VOICE`, **`LEX_I`**, `BENEDICTION` |
-| `theme_flair` | `ACCENT`, `BANNER` |
+### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
 
-Editing any of those, in any theme, reddens a snapshot with **no re-bless path**. Adding a *new*
-law is safe (only `LEX_I` is recorded). Restyling an existing theme's tagline or banner is not.
+Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
+be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
+red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
+cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
 
-This was proven, not inferred: prefixing `marvin.json`'s `TAGLINE` turned
-`tests/snapshot/pure_snapshot.test.mjs` red at `case 1275`.
+Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
+detection and nothing checks it.
 
 ### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
 
@@ -434,7 +469,7 @@ anything owns **every** install's hooks. Emitting from a git worktree or a temp
 repoint the shim at that disposable path; removing the worktree then killed hooks for every
 install on the machine.
 
-**`hookPrefix` now refuses the claim** (`js/settings.mjs`, `ephemeralCheckout`): an emit whose
+**`hookPrefix` now refuses the claim** (`js/hosts/settings.mjs`, `ephemeralCheckout`): an emit whose
 checkout is under the OS temp root, or is a linked git worktree (`.git` is a *file*), leaves a
 shim that still resolves exactly as it is and wires the emitted hooks to it anyway. The bundle it
 writes is byte-identical to a normal emit — the install simply keeps running the durable
@@ -463,37 +498,30 @@ remains the cheapest thing to run.
 Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
 stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
 
-### 5.4 ⚠ A snapshot red is a finding, not a step
+### 5.4 ✅ Expected values are written out — resolved 2026-08-23
 
-Everything left under `tests/__snapshots__/` — the primitives, the 26 help texts, and the small
-pure-function recordings — was produced by an implementation that no longer exists. There is no
-`--record`. A change that moves a recorded byte leaves two honest options: revert it, or argue in
-writing (in `docs/declined.md`) that the recording was wrong. `docs/limits.md` carries the full
-argument and the measurement that licensed retiring the three larger corpora.
+This section used to say that a snapshot red was a finding rather than a step: the recordings under
+`tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
+and a change that moved a recorded byte left only two honest options — revert it, or argue in
+writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
+blocks a change, move the logic to the nearest caller that is not frozen*.
 
-**A worked example, from the session that wrote this file.** Closing a real defect — three count
-gates that go green when you *delete* the sentence they check — turned the primitives corpus red
-at `case 371`: `proseMirrorProblems` is a recorded pure function, the recording holds a case that
-passes an empty `shipped` string and expects `[]`, and the new absence arm answered otherwise.
-Both obvious moves are wrong. Re-blessing is impossible. Abandoning the fix leaves a gate failing
-open. The third move is the one to reach for: **the presence check moved up one level, into
-`countTableProblems`, which is not recorded** — where it reads better anyway, beside the code that
-already knows whether the file could be opened. The rule that falls out: *when a frozen recording
-blocks a change, look for the nearest caller that is not frozen.* Check with
+**None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
+only way back to them), and every expected value now lives in the test file that asserts it, above
+a sentence saying which decision it pins. The rule is correspondingly ordinary:
 
-```bash
-node -e "const j=require('./tests/__snapshots__/primitives/win32.json');console.log([...new Set(j.cases.map(c=>c.fn))].join('\n'))"
-```
+> **Change the expectation and the sentence that explains it in the same commit, and say why in
+> the message.**
 
-The concrete consequence for evolution: **editing the help text or the flags of any of the 26
-recorded CLI verbs is a frozen surface.** New verbs have a path (`NATIVE`); changes to old ones
-do not. `docs/limits.md:311-316` names this cluster as the one open standing decision.
+A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
+the cost that keeps the tables honest, and far cheaper than the one it replaced.
 
-The CLI surface is the most expensive thing in the repo to change, because four hand-written
-equalities converge on it: `js/cli-table.json`'s 29-command count (`tests/unit/cli_table.test.mjs:67`),
-the 5-entry hidden-argument list (`tests/snapshot/cli_help.test.mjs:219`), the 25-subparser count
-(`tests/unit/docs.test.mjs:193`), and the 26 unblessable help fixtures. Plus
-`tests/unit/docs.test.mjs:554`, which validates every fenced `geneseed <verb> <flags>` line in
+The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
+text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
+`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
+holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
+29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
+`tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
 `README.md`, `SETUP.md`, `QUICKSTART.md` and `SHIPPED.md` against the table.
 
 ---
@@ -511,12 +539,12 @@ only, at best, on its presence.
 | The README keyword enumerations | `README.md`, `docs/web/rules.md` | nothing |
 | The plugin capability enumeration | `docs/web/model.md` | nothing (the number substitutes; the list does not) |
 | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
-| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/setup.mjs`, `js/anim.mjs` | nothing — missing entries fall back silently |
+| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
 | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
 | `adapters/claude-code/settings.json` | — | nothing compares it to what the emitter writes; **it is already divergent** |
 | `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
 | The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs:54` | a hand-transcribed measurement |
-| Stale docblock counts | `js/themes.mjs:62` ("137 values" → 140), `js/render.mjs:116` ("145 tokens" → 148) | nothing |
+| Stale docblock counts | `js/build/themes.mjs:62` ("137 values" → 140), `js/build/render.mjs:116` ("145 tokens" → 148) | nothing |
 
 ---
 
@@ -555,7 +583,7 @@ answer.
 5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
    tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
    named as `cli`, which was removed).
-6. **A claim that was simply false.** `js/render.mjs` said `--theme` is validated against
+6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
    `choices` before anything renders, which is why its own refusal read as an unreachable nicety.
    It is not in `choicesFor`; that refusal is the only one there is, on every path.
 7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
@@ -563,7 +591,7 @@ answer.
    Plus a skip message naming a `record-corpus` CI job that no longer exists.
 8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
    URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
-   `geneseed upgrade v1.0.0 # pin to a tag`, which `js/update.mjs` prints is IGNORED.
+   `geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
 9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
    the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
    a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
@@ -662,9 +690,9 @@ stop a change today, and all of them cost a contributor a wrong turn until they
    and today nothing warns you before the snapshot goes red.
 4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
    `adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
-5. **Consider a `scripts` block in the root `package.json`.** There is currently no single command
-   that runs what CI runs; every contributor reassembles the five by hand from this file. A
-   `verify` script is three lines and makes §1 executable rather than descriptive.
+5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
+   config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
+   chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
 
 The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
 deliberately keeps tables and prose hand-written and gates them from the source tree. The

package/docs/web/exclusions.md

@@ -3,7 +3,7 @@ group: concepts
 order: 9
 title: "Sovereign repos (exclusions)"
 kind: "concept"
-link: {"hash": "#/harnesses", "label": "Manage in Harnesses →"}
+link: {"hash": "#/harness", "label": "Manage in Harness →"}
 ---
 A **sovereign repo** is a folder where every GLOBAL harness install goes fully dormant: hooks stay silent and the global preamble (`AGENT.md`/`CLAUDE.md`) is never loaded there. A repo that ships its own agent config you don't want a global harness layered onto is the usual case.
 

package/docs/web/footprint.md

@@ -29,7 +29,7 @@ Neither setting hides text from the agent; they hide it from *every turn*.
 It's set-and-forget — stored in the `.geneseed-footprint` marker, preserved across every rebuild, identical on every host (OpenCode, Claude Code, Bob, Copilot). Changing it re-emits the install.
 
 - **Settings** — the **Footprint** toggle flips the current install (full ⇄ lean) and rebuilds it in place.
-- **Harnesses tab** — a per-harness dropdown sets it for any one install independently, then **Apply**.
+- **Harness tab** — on an active install, a per-harness dropdown sets it for that install independently, then **Apply**. On a host that is not installed yet, it is step 2 of **Install…**.
 - **Setup / re-theme wizard** — asks for footprint alongside voice, posture, mode, and doctrine packs.
 - **CLI** — `geneseed-build --footprint lean` (with any `--emit`).
 

package/docs/web/foreman-mode.md

@@ -3,7 +3,7 @@ group: concepts
 order: 12
 title: "Foreman mode"
 kind: "concept"
-link: {"hash": "#/harnesses", "label": "Set the mode in Harnesses →"}
+link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
 ---
 **Mode** is the session's *operating* register — how work gets executed — one of four build-time dials, beside posture (the *relationship* register), [doctrine packs](#/docs/setup-choices) (which practice rules bind) and footprint (how much of the constitution loads inline). Two modes ship, set at build time so the choice holds steady instead of drifting mid-session, and preserved across every rebuild and re-theme.
 
@@ -24,7 +24,7 @@ Because the crew runs apart from the conversation, the session stays responsive
 
 Set-and-forget, stored beside the install and preserved across rebuilds and re-themes:
 
-- **Harnesses tab** — the per-install **Mode** dropdown (beside Voice, Footprint, and Posture), then **Apply**.
+- **Harness tab** — on an active install, the per-install **Mode** dropdown (beside Voice, Footprint, and Posture), then **Apply**. On a host that is not installed yet, the same four choices are steps inside **Install…**.
 - **Setup / re-theme wizard** — asks for mode alongside voice, posture, doctrine packs, and footprint.
 - **CLI** — `geneseed-build --mode foreman`; switch back with `--mode direct`.
 

package/docs/web/themes-author.md

@@ -3,7 +3,7 @@ group: extend
 order: 1
 title: "Write a new theme"
 kind: "concept"
-link: {"hash": "#/themes", "label": "Open the theme gallery →"}
+link: {"hash": "#/harness", "label": "Open the voice gallery →"}
 ---
 A theme is one JSON file under `themes/` declaring voice tokens only: `BANNER`, `TAGLINE`, `LOADED_SIGIL`, `VOICE`, the core nouns (`ONTOLOGY`/`LAW(S)`/`DOCTRINE(S)`/`AGENT(S)`/`SKILL(S)`/`MEMORY`/`NOTEBOOK`/`WIKI`), the section intros `INTRO_*`, the epigraphs `EPI_*`, the `BENEDICTION`, the `ROAST_PERSONA`, and `DESC_*` blurbs. Copy `themes/neutral.json` and edit. `geneseed build --theme yours` renders it; `doctor` checks for missing tokens.
 

package/docs/web-ui.md

@@ -50,12 +50,17 @@ The left rail mirrors the harness's own shape:
 
 | Group | Views |
 | --- | --- |
-| **🧬 Harness** | Dashboard · Activity · Constitution · Rules · Profile · Skills · Agents · Library · Docs · Graph |
-| **🔧 Maintain** | Changes · Doctor |
-| **🎨 Configure** | Harnesses · Themes · Settings |
-| **ℹ️ About** | About |
+| *(ungrouped)* | Dashboard |
+| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Docs · Graph |
+| **🩺 Care** | Activity · Changes · Doctor |
+| **🎨 Setup** | Harness · Settings |
 
-A global **Spotlight** search lives in the topbar — press <kbd>/</kbd> to focus it, type
+Above the index sits a **vitals** card — the germination ring, drift, the doctor's verdict
+and how long ago the harness was built — so those four facts are on screen from every page.
+It is hidden where the rail collapses to icons (≤960px) and returns with the phone drawer.
+
+A global **Spotlight** search lives in the topbar — press <kbd>/</kbd> to focus it (or
+<kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd>, which also works from inside a text field), type
 to jump to any agent, skill, doc, spec, MCP server, or constitutional rule — the `laws`
 catalog it indexes is the whole constitution, so an ontology section, an invariant and a
 doctrine rule are all reachable by name; <kbd>↑</kbd>/<kbd>↓</kbd> to
@@ -129,32 +134,39 @@ streams the output of background jobs and keeps their history across reloads.
   theme, parity, links, authoring gates, drift), grouping any problems per check. Re-run
   on demand.
 
-### 🎨 Configure
-
-- **Harnesses** (`#/harnesses`) — every detected install (host × scope), one row each,
-  with per-row **Voice**, **Footprint**, **Posture**, and **Mode** pickers plus
-  Install/Apply, an on/off switch, and remove. **Posture** is the relationship register
-  (peer/mentor/expert/assistant/artisan — default **peer**); **Mode** is the operating
-  register (direct/foreman — default **direct**; foreman triages tasks into isolated
-  pipelines instead of working every one itself). Both are orthogonal to voice and to
-  each other, picked here or via the setup wizard, and preserved across every rebuild.
-  "Deploy to folder…" and "Rebuild all" apply to the whole set. An **Excluded folders**
-  card (shown once a global install exists) manages sovereign repos — folders where every
-  global harness goes dormant (hooks stay silent, the global preamble never loads);
-  add or remove one here, the web mirror of `harness exclude add|remove|list`.
-- **Themes** (`#/themes`) — a gallery of the shipped voices (name, tagline, sigil, accent
-  glow). **Apply** a voice to rebuild the deployed harness in that theme; the current one
-  is marked.
+### 🎨 Setup
+
+- **Harness** (`#/harness`) — this machine's own install first (path, voice, footprint,
+  and when it was built), then the **Voice** reference, then every detected install.
+  `#/harnesses` and `#/themes` both still resolve here, so old links and bookmarks keep
+  working.
+  - The **Voice** card is the former Themes tab, kept as a REFERENCE rather than a second
+    control: a collapsed row that opens to every shipped voice with its tagline, the
+    deployed one pinned first and marked. It is the one place you can read what a voice
+    sounds like — the per-install picker below is a list of bare names. Applying happens
+    there, per install, beside that install's own footprint, posture and mode; a gallery at
+    the top of the page could only ever act on one of them.
+  - **Every install** lists each detected install (host × scope), one row each. An
+    ACTIVE row carries per-row **Voice**, **Footprint**, **Posture** and **Mode**
+    pickers plus **Apply**, an on/off switch, and remove; a host that is NOT installed
+    yet shows a single **Install…** that discloses the same four choices as steps.
+    **Posture** is the relationship register (peer/mentor/expert/assistant/artisan —
+    default **peer**); **Mode** is the operating register (direct/foreman — default
+    **direct**; foreman triages tasks into isolated pipelines instead of working every
+    one itself). Both are orthogonal to voice and to each other, picked here or via the
+    setup wizard, and preserved across every rebuild.
+  - "Deploy to folder…" and "Rebuild all" apply to the whole set. An **Excluded folders**
+    card (shown once a global install exists) manages sovereign repos — folders where every
+    global harness goes dormant (hooks stay silent, the global preamble never loads);
+    add or remove one here, the web mirror of `harness exclude add|remove|list`.
 - **Settings** (`#/settings`) — a **Console direction** picker (the visual flavour of the
   console) with a **Dashboard layout** control (Auto follows each theme's designed Status
-  lens; Cultivar / Greenhouse / Operator force one regardless of skin), the install snapshot
-  (deployed/target/theme/version/memory store), a Maintenance card (PATH link/unlink,
-  uninstall), an offline package download, and server controls (Stop). Build, update, and MCP
-  wiring live in the Harnesses tab.
-
-### ℹ️ About
-
-- **About** (`#/about`) — project + creator credits and the source link.
+  lens; Cultivar / Greenhouse / Operator / Journal force one regardless of skin), the
+  install snapshot (deployed/target/theme/version/memory store), a Maintenance card (PATH
+  link/unlink, uninstall), an offline package download, server controls (Stop), and the
+  **About** colophon — project + creator credits and the source link, folded in from the
+  retired `#/about` tab (which still resolves here). Build, update, and MCP wiring live in
+  the Harness tab.
 
 ## Rebuilding the UI
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.1.1"
+  "version": "3.1.3"
 }