geneseed 3.1.1 → 3.1.2

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/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.2"
 }

package/js/README.md

@@ -0,0 +1,203 @@
+# `js/` — the module map
+
+Fifty-six modules in seven folders. This page is the address book: **what each one owns**, and
+**which file to open first** for a given task. It is not documentation of behaviour — every module
+has a docblock for that, and the docblock is the thing to read before editing.
+
+`tests/unit/module_map.test.mjs` keeps this page honest: a module with no row here, or a row naming
+a module that does not exist, is a test failure. `geneseed doctor` reports the same thing.
+
+---
+
+## The shape
+
+```
+bin/geneseed-cli.mjs     the `geneseed` CLI — 20+ verbs, may NOT spawn
+bin/geneseed-hook.mjs    the hook entry — 4 verbs, loads on EVERY tool call (~14 ms)
+bin/build-driver.mjs     `geneseed-build` — the generator's flags and emit targets
+
+js/build/     src/ + themes/  →  rendered text  →  a bundle  →  a per-host install
+js/hosts/     where it stops being a renderer and touches the machine
+js/inspect/   the read-only half: doctor, status, diff, validate, catalog
+js/lib/       primitives, every one a deliberate divergence from the Node default
+js/maintain/  lifecycle verbs that change an install that already exists
+js/ui/        what it prints at a terminal
+js/web/       the `geneseed web` console
+```
+
+Dependency direction is one-way: `lib/` ← everything; `build/` ← `hosts/`; `inspect/` and `web/`
+read what `build/` produced. Nothing in `lib/` imports anything above it.
+
+---
+
+## `js/build/` — the generator
+
+Turns the checkout's `src/` + `themes/` into rendered text, writes that into a bundle, and emits it
+as a per-host install at project or global scope.
+
+| module | owns |
+|---|---|
+| `source.mjs` | Where the SOURCE is: `ROOT`/`SRC`/`THEMES`/`CONFIG`, `PACK_ORDER`, rule ids, the cfg object |
+| `render.mjs` | The pure text pipeline: theme load, `INCLUDE` inlining, CATALOG blocks, `{{TOKENS}}`, dest paths |
+| `bundle.mjs` | `build` — render a theme into a bundle dir, plus the source-completeness refusal. Sits UNDER both emits |
+| `emit-claude.mjs` | The Claude/Bob/Copilot emit — the render half plus the settings + CLAUDE.md managed-block wire |
+| `emit-opencode.mjs` | The OpenCode emits — a project's `.opencode/` and the global config dir. Deliberate twin of the above |
+| `emit-common.mjs` | Constants, tree walkers, and the three writers BOTH global emits share. Decides no host |
+| `stubs.mjs` | Write-once seed files: context, wiki, rules, excludes, profile, `.gitignore`, memory/notebook indexes |
+| `version.mjs` | The release marker: fingerprint the sources, read/compare/write an install's version, warn on downgrade |
+| `generate.mjs` | CLI verbs `build`, `prompt`, `theme`, `rebuild-all` — the thin face over `bin/build-driver.mjs` |
+| `catalog.mjs` | `geneseed catalog` — prints the shipped roster. Classifies nothing itself |
+| `themes.mjs` | Maintainer-only `--sync-themes`: inserts `_TEMPLATE.json`'s missing keys into the committed themes |
+
+**Before editing:** `render.mjs` writes nothing, and its output is what every emit target
+serialises — a change there is visible in all 14 themes at once. `emit-claude.mjs`'s
+wire half edits files the **user** co-owns — get its prior-claim pruning wrong and you delete
+someone's own settings keys. `emit-opencode.mjs` is shaped as a twin on purpose: a change that
+lands on one host and not the other is the historical defect here, so edit both or neither.
+`stubs.mjs` bodies are compared byte-for-byte by a recording — editing prose in one is a product
+change. `themes.mjs` rewrites hand-written files in the repo, and `git diff` is where you would
+find out about a slip.
+
+## `js/hosts/` — touching the machine
+
+Resolving each host tool's config directories, writing host-native agents and skills into files the
+user co-owns, and the hook verbs those emitted configs then run.
+
+| module | owns |
+|---|---|
+| `hosts.mjs` | The four host config dirs (opencode/claude/bob/copilot), plus `resolvePath`/`expanduser` |
+| `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `learn` |
+| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
+| `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
+| `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
+| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture and mode |
+| `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
+| `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
+
+**Before editing:** `hooks.mjs` **is the hook path** — the verdict travels as JSON on stdout and
+every arm exits 0, so one stray printed byte turns a blocking gate silently permissive, and anything
+imported here is paid on every tool call. `hosts.mjs` is shared by the generator, the CLI and the
+hook path, so it must stay free of `child_process`. `installs.mjs` reads through `readMaybe`, which
+folds CRLF — a bare `readFileSync` here is a bug.
+
+## `js/inspect/` — the read-only half
+
+Everything that inspects an already-built or already-deployed harness and reports on it.
+
+| module | owns |
+|---|---|
+| `doctor.mjs` | The `geneseed doctor` **driver** only: picks themes, runs the checks, prints the verdict |
+| `checks-build.mjs` | Gates over what the build PRODUCED: links, tokens, theme parity, OpenCode colours, bundle drift |
+| `checks-repo.mjs` | Gates over the repo's own records: `registry.json`, committed secrets, the hook shim, vendored pins |
+| `checks-authoring.mjs` | Self-consistency: law/doctrine metadata, constitution numbering, the counts README and the web quote |
+| `scan.mjs` | The shared walk/sort/strip/test primitives all three `checks-*` use. Owns no judgement itself |
+| `validate.mjs` | The `--validate-only` verb: renders a sandbox, scans it for tokens and dead links, own exit contract |
+| `inventory.mjs` | The one catalog walk and its taxonomy tables, read by status, the TUI and the web console |
+| `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
+| `diff.mjs` | `geneseed diff` — what a deployed install has that a fresh render of `src/` does not |
+| `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json`; `hooks.mjs` only reads it |
+| `registry.mjs` | `installs.json` under XDG — the persistent deploy-root list `rebuild-all` re-emits into |
+
+**Before editing:** every check returns an array of problem strings, empty when clean — and since
+deleting any check leaves a clean run **byte-identical**, each one is gated by a PLANTED FAULT, not
+by a comparison. `scan.mjs`'s `TOKEN_RE` must stay in step with `render.mjs`'s. `registry.mjs`
+swallows its own errors on purpose: a registry hiccup must never fail a build.
+
+## `js/lib/` — the primitives
+
+Zero dependencies. **Every function here exists because the Node default is wrong for this tool** —
+each one's docblock says which default, and why. Change a rule and you change what the tool writes
+into files users have committed, so change the test that states it in the same commit.
+
+| module | owns |
+|---|---|
+| `fs.mjs` | All disk and stdout/stderr writes. The single owner of the `\n` → `os.linesep` translation |
+| `json.mjs` | The int/float-preserving parser (`JsonNumber`) plus every dumps/repr renderer |
+| `paths.mjs` | Case folding, ordering, containment, spelling, PATH lookup — the platform-shaped rules |
+| `text.mjs` | String primitives: `codePointLength`, `WHITESPACE`, `parseIntStrict`, `percentDecode` |
+| `udiff.mjs` | `geneseed diff`'s own difflib clone — the alignment IS the printed hunks — plus `splitLines` |
+| `proc.mjs` | One constant: the `windowsHide` flag every spawn in `js/` must reuse |
+
+**Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
+float `1.0` into one double, and that value gets written into a user's file. Do not swap in a diff
+library for `udiff.mjs`: it is not Myers, ties resolve to the earliest match. Every function in
+`paths.mjs` branches on `process.platform`, so green on one OS proves nothing about the other.
+
+## `js/maintain/` — lifecycle
+
+Verbs that change an install that already exists, as opposed to rendering one.
+
+| module | owns |
+|---|---|
+| `update.mjs` | `upgrade`/`sync-self`/`bootstrap` — git pull, doctor gate, rebuild, each via a respawn |
+| `setup.mjs` | The install wizard, and the CLI's only synchronous stdin readers (`ask`/`confirm`/`askChoice`) |
+| `uninstall.mjs` | Removes or disables an install: manifest-driven reversal, plus stash deactivate/reactivate |
+| `migrate.mjs` | `geneseed migrate` — all-or-nothing re-emit moving installs onto the npm install shape |
+| `memory.mjs` | `geneseed memory list|rm` — CLI-side fact deletion, twin of the web DELETE endpoint |
+
+**Before editing:** `update.mjs` is the one module that MUST spawn rather than import — the code on
+disk is replaced mid-run, so an in-process call would validate the *old* source and then render it.
+`setup.mjs` is the whole program's stdin layer, not just setup's. `memory.mjs` hard-unlinks user
+facts with no archive path.
+
+## `js/ui/` — the terminal
+
+| module | owns |
+|---|---|
+| `cli.mjs` | The whole CLI surface as data (`js/cli-table.json`) plus `--help` rendering and text wrapping |
+| `menu.mjs` | Entry points for a bare `geneseed` and for `menu` — the web-vs-terminal fork |
+| `tui.mjs` | The `tui` verb plus the panel's pure layout half: display width, glyphs, fit/truncate, rows |
+| `anim.mjs` | Per-theme install ASCII art and its line animation — the only ANSI-emitting file here |
+
+**Before editing:** there is no argument-parser *definition* in the code — every verb, flag, default
+and help string lives in `js/cli-table.json`, and the table IS the parser. Most of `tui.mjs`'s
+exports have no caller inside it: they are the curses-free half of a panel that does not exist.
+
+## `js/web/` — the console
+
+A dependency-free localhost HTTP daemon that serves the built React UI from `web/dist` and exposes
+the deployed harness as JSON.
+
+| module | owns |
+|---|---|
+| `server.mjs` | `serve()`/`cmdWeb`: UI-build precheck, socket bind, token mint, daemon record wiring |
+| `routes.mjs` | Route DECLARATION only: the `POST_ROUTES` table and the ported/unported/declined sets |
+| `handler.mjs` | One function per request: dispatch, gzip, Host/CSRF guards, static SPA fallback |
+| `api.mjs` | `WebState` plus every GET read endpoint; owns `STATE_ROUTES`, `PREFIX_ROUTES`, `NotFound` |
+| `actions.mjs` | The mutating endpoints — rules, profile, memory, MCP, excludes — plus install/deploy argv |
+| `daemon.mjs` | Detached web start/stop/status/restart, the `.geneseed-web.json` record, and `openUrl` |
+| `jobs.mjs` | `JobManager` and the action→argv table. The only module here that spawns job children |
+| `docs.mjs` | The Docs tab: the `docs/web/` page registry, `?harness=` filtering, the five page kinds |
+| `graph.mjs` | `/api/graph` alone — the agent/skill/law cross-link matrix built from rendered bodies |
+| `activity.mjs` | The `activity/` session files: pid-liveness prune, list, detail, and the on/off flag |
+
+**Before editing:** `makeHandler(state, jm, token, dist, holder)`'s arity is load-bearing — three
+test call sites construct one directly and drive it without a socket. Four of `routes.mjs`'s
+exported sets are deliberately EMPTY and must stay declared: each is half of a partition test.
+`graph.mjs` contains a literal NUL byte, so `grep`/`ripgrep` treat it as binary and skip it.
+
+---
+
+## Where do I add…
+
+| I want to | open first | then |
+|---|---|---|
+| a doctrine rule | `src/doctrines/<pack>.md` — APPEND, ids run contiguously | `docs/extending.md` §2a — five files, `--sync-themes`, restyle 14 voices by hand |
+| a law (invariant) | `src/laws/universal.md` — **APPEND, never insert** | `docs/extending.md` §2c. Amend the FIRST sentence: lean footprint keeps nothing else |
+| a skill or an agent | `src/skills/<name>.md` or `src/agents/<name>.md` | `docs/extending.md` §3 — eight steps. Write the FILE before the table row or the build aborts |
+| a doctor check | `js/inspect/checks-{build,repo,authoring}.mjs` | register with `ran(...)` in `doctor.mjs`, then a PLANTED FAULT in `tests/unit/harness.test.mjs` |
+| a web endpoint | GET → `js/web/api.mjs`; POST → `js/web/actions.mjs` | declare it in `js/web/routes.mjs`; the partition test probes the real handler |
+| a CLI verb | `js/cli-table.json` — the table IS the parser | the `VERBS` row in `bin/geneseed-cli.mjs`, the row count in `cli_table.test.mjs`, `NATIVE` in **two** test files |
+| a hook verb | `js/hosts/hooks.mjs` | `claudeHookGroups` in `settings.mjs`, `VERBS` in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
+| a console doc page | `docs/web/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
+| an OpenCode plugin | `adapters/opencode/plugins/geneseed-<name>.js` | `docs/extending.md` §4a — the `geneseed-` prefix is mechanically load-bearing |
+| to change a `js/lib/` primitive | `tests/fixtures/pure_probe.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |
+
+---
+
+## Known debris
+
+* **`js/hosts/settings.mjs` carries a private second copy of Python's whitespace class**, duplicating
+  `WHITESPACE` in `js/lib/text.mjs`. `text.mjs` is the owner.
+* **`web/src/pages/Skills.jsx`'s `SKILL_CATS` is a fourth, ungated copy of the skill taxonomy** —
+  nothing compares it to `SKILL_CLASS`, and an unknown category renders as Build with no warning.