geneseed 3.1.1 → 3.1.2

package/CHANGELOG.md

@@ -6,7 +6,74 @@ labels in `harness.config.json`. The canonical identity of an *installed* harnes
 is the source fingerprint in `.geneseed-version` (see `geneseed version`), not this
 label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
-## [Unreleased]
+## [3.1.2] — 2026-08-24
+
+### Changed
+
+
+- **`js/` is now domain folders, not a flat drawer.** The tree splits into `build/`, `hosts/`,
+  `inspect/`, and `main/`, and the four largest modules split with it: `server.mjs` into
+  routes / handler / daemon / server, `emit.mjs` into common / stubs / version / bundle,
+  `doctor.mjs` into scan plus three check groups, and `fs.mjs` into fs / json / paths / text.
+  The Node generator driver is renamed to `bin/build-driver.mjs`; the `geneseed-build` bin name
+  is unchanged, so nothing on an installed harness has to move.
+
+  **No emitted byte moves.** The 261-cell corpus replays identical across all 14 themes, which
+  is the whole warrant for a reorganization this size — 151 files, 8502 insertions, 6481
+  deletions, and zero observable difference for anyone who installed 3.1.1.
+
+- **Docs point at the code that exists.** A module map and front door in `js/README.md`, with a
+  doctor arm that keeps them honest; 201 stale paths repointed in prose, the 35 split-module
+  pointers resolved, and 69 docblock claims corrected where the code had stopped supporting
+  what the comment promised. The vestigial `emit.mjs` is deleted.
+
+- **The Python-era `py` identifier prefix is retired**, and `js/ bin/ tests/ adapters/` are now
+  linted — the half of the tree that never was.
+
+
+- **Two of "the four things that are genuinely hard" are resolved rather than rewritten.**
+  `docs/extending.md` §5.2 — seven theme keys pinned byte-for-byte, so restyling a tagline was a
+  red gate — and §5.4 — *a snapshot red is a finding, not a step*. Theme text is free to edit,
+  and a red test is a step again. Editing a CLI verb's help text or flags is an ordinary edit.
+
+- **The standing rule is now "expected values are written out, not recorded"**: change the
+  expectation and the sentence that explains it in the same commit, and say why in the message.
+
+### Added
+
+
+- **A gate on how a runtime dependency may enter**: vendored under `js/vendor/<name>/` as tracked
+  source behind a relative import, never installed. Fixtures run from the OS temp root and cannot
+  resolve a bare specifier, and neither can a fresh `git clone`; devDependencies are unaffected.
+
+### Removed
+
+
+- **The recorded corpora, and the notion of a corpus with them.** `tests/__snapshots__/` held
+  2.6 MB of transcripts taken from the CPython reference before it was deleted, replayed by
+  `tests/snapshot/`. With no recorder left they could never be re-blessed, so a red run could
+  only ever mean *you changed something*, never *you broke something* — and every deliberate
+  change to emitted text arrived as a red gate. The 1381-cell retirement of 2026-08-17 had
+  already made the argument; this finishes it.
+
+  **What they owned is now written out.** `wrapText`, `dwidth` and `formatHelp` had zero unit
+  coverage — the recordings were their only gate — so `tests/unit/text_layout.test.mjs` states
+  their rules explicitly and renders all 29 verbs. The JSONC, Windows-PATH and token-report
+  tables moved inline; `sync_themes` became an owned fixture with plain-text expectations. The
+  "corpus contains what it is named for" gates went with them: when the apostrophe is visible in
+  the file, nothing has to assert it is there.
+
+  Recoverable at tag `corpus-reference-v3.1.2`. Nothing can regenerate them.
+
+- **Three migration statistics.** "N of the M subcommands run from Node", "0 commands have no
+  Node twin", and a native-verb list duplicated across two files purely so each could police the
+  other. A migration percentage is not a fact about a finished tool. The durable property under
+  the first two — every declared verb is dispatched by an entry point — is now asserted directly.
+
+- **`golden.mjs --against`**, which could not have worked since the emit corpus was retired, and
+  `orphanCheck`, `narrowingReason` and `tests/helpers/snapshot_io.mjs` with it. The three
+  surviving modes are all self-comparisons.
+
 
 ## [3.1.1] — 2026-08-21
 

package/DESIGN.md

@@ -35,7 +35,7 @@ vault or a specific tool's hooks.
      names (`ONT_TELOS`, `ONT_EVIDENCE`, `ONT_DECISIONS`, `ONT_CONDUCT`), a few rare
      technical nouns (`Context`, `Scripts`, `Charter`), and the folder names (`laws/`,
      `ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/` via `DIR_*`).
-     These live in the `STRUCTURE` map in `js/render.mjs` and are laid on top of every
+     These live in the `STRUCTURE` map in `js/build/render.mjs` and are laid on top of every
      render, so a theme can never move a path, a link, or a heading number. No theme file
      defines a `DIR_*` or an `ONT_*` key, and none may: an ontology citation spells the
      section on both sides (`{{ONTOLOGY}}: {{ONT_TELOS}}`), so heading and reference move
@@ -102,7 +102,7 @@ vault or a specific tool's hooks.
      Rules, `I`..`IX`, headed `### {{LAW}} <roman> — {{LEX_<roman>}}`.
    - **Doctrines** (`src/doctrines/{craft,rigor,ops,process}.md`) — *how work is done
      here*. Practice rules addressed by pack and number, cited as `Doctrine process 5`.
-     `PACK_ORDER` (`js/checkout.mjs`) fixes the order craft → rigor → ops → process, which
+     `PACK_ORDER` (`js/build/source.mjs`) fixes the order craft → rigor → ops → process, which
      is narrative and deliberately not alphabetical.
 
    **The Ontology and the Invariants are never toggleable** — every build carries both,
@@ -128,7 +128,7 @@ vault or a specific tool's hooks.
    repeal one; a user rule outranks a doctrine rule outright; nothing outranks an
    invariant. And an always-on tier may never cite a toggleable one — a `--doctrines craft`
    build would otherwise ship an invariant pointing at text its `AGENT.md` does not
-   contain — so `constitutionProblems` (`js/doctor.mjs`) refuses a `{{DOCTRINE}}` token
+   contain — so `constitutionProblems` (`js/inspect/checks-authoring.mjs`) refuses a `{{DOCTRINE}}` token
    anywhere under `src/ontology/` or `src/laws/`.
 
    The bar for a **new invariant** is the highest in the tree: universal (it binds *every*
@@ -146,9 +146,9 @@ vault or a specific tool's hooks.
    |---|---|---|---|
    | body | append to `src/laws/universal.md` — never insert; nothing resolves a cross-reference against the canon | append to `src/doctrines/<pack>.md`, `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}`; ids must run contiguously from 1 | a new `src/doctrines/<pack>.md` with its `**Name** — lead line` |
    | themed title | `LEX_<roman>` in all 15 theme files | `DOC_<PACK>_<n>` in all 15 theme files | `PACK_<NAME>` in all 15, plus each rule's `DOC_*` |
-   | class | `LAW_CLASS` in `js/inventory.mjs`, one of the six in `LAW_CLASSES` | **none** — a doctrine rule's class *is* its pack, and there is no second taxonomy over it | — |
+   | class | `LAW_CLASS` in `js/inspect/inventory.mjs`, one of the six in `LAW_CLASSES` | **none** — a doctrine rule's class *is* its pack, and there is no second taxonomy over it | — |
    | console copy | a `LAW_META` row in `web/src/pages/Laws.jsx` (keyed by arabic number) | a `DOCTRINE_META` row in the same file (keyed `<pack>.<n>`) | one `DOCTRINE_META` row per rule |
-   | registration | the numeral is the registration | the number is the registration | the pack name in `PACK_ORDER`, `js/checkout.mjs` |
+   | registration | the numeral is the registration | the number is the registration | the pack name in `PACK_ORDER`, `js/build/source.mjs` |
    | renumber risk | high — appending is the only safe move | none — packs are numbered independently | none |
    | counts | README badge + the `N universal laws` prose, `SHIPPED.md`'s triple, the web onboarding copy | **none** — the console spends the `N_PACKS` / `N_PACKS_ACTIVE` / `N_DOCTRINE_RULES` count tokens, all computed at request time | none, same reason |
    | changelog | `CHANGELOG.md` | `CHANGELOG.md` | `CHANGELOG.md` |
@@ -160,7 +160,7 @@ vault or a specific tool's hooks.
    synonym. `--sync-themes` writes the template's placeholder and only *prints* which keys
    to restyle; a shipped placeholder passes every gate.
 
-   Almost all of it is gated, across six named checks in `js/doctor.mjs` —
+   Almost all of it is gated, across six named checks in `js/inspect/checks-build.mjs` —
    `themeParityProblems` (key parity across the voices), `lawMetaProblems` and
    `doctrineMetaProblems` (the console's Principle column, in both directions),
    `constitutionProblems` (pack numbering and filing, `LEX_I..LEX_IX` as an *equality*, the
@@ -195,11 +195,11 @@ theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
 | Notebook | `src/notebook/` | `notebook/` | the agent's sovereign space — any medium, seed-once charter the agent may rewrite; only `.gitignore` re-asserted |
 | Posture | `src/postures/` | inlined into `AGENT.md` | how much ceremony the agent brings to a task |
 | Mode | `src/modes/` | inlined into `AGENT.md` | the working axis (solo, foreman, …) — orthogonal to posture |
-| Context | `js/emit.mjs` | `context.json` | empty per-repo manifest, written once and never overwritten; git-ignore it |
+| Context | `js/build/stubs.mjs` | `context.json` | empty per-repo manifest, written once and never overwritten; git-ignore it |
 | Themes | `themes/*.json` | — | token → label maps; `themes/opencode/` is a separate colour system |
 | Release label | `harness.config.json` | `.geneseed-version` | the theme and the human-readable version the driver reads; the canonical identity is the source fingerprint, not this string |
 | Lifecycle | `registry.json` | — | maintainer-side status/version/owner per agent and skill; never rendered into a bundle |
-| Generator | `bin/geneseed.mjs` (`geneseed-build`) | — | substitution + `<!-- INCLUDE: -->` inlining, and the nine `--emit` targets |
+| Generator | `bin/build-driver.mjs` (`geneseed-build`) | — | substitution + `<!-- INCLUDE: -->` inlining, and the nine `--emit` targets |
 | CLI, as data | `js/cli-table.json` | — | the owned document the entry point parses its own argv from |
 | Automation | `bin/geneseed-cli.mjs` (`geneseed`) | — | 25 verbs — `build` / `doctor` / `status` / `prompt` / `diff` / `setup` / `web` / `upgrade` / … |
 | Hooks | `bin/geneseed-hook.mjs` (`geneseed-hook`) | — | the four verbs an emitted `settings.json` invokes: `context` / `git-gate` / `rule-gate` / `learn` |
@@ -212,28 +212,28 @@ theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
 - Unknown tokens are left visible (debugging aid); `doctor` flags them.
 - Node built-ins only; no third-party dependencies, ever. (`package.json` carries neither a
   `dependencies` nor a `devDependencies` key, and a test asserts it.)
-- **`js/settings.mjs` is the half of the emit that edits files you co-own** — the
+- **`js/hosts/settings.mjs` is the half of the emit that edits files you co-own** — the
   `settings.json` / `opencode.json` merges, JSONC parsing, the hook shim and the managed
   CLAUDE.md block. It is a separate module because every function in it reconciles
   Geneseed's claim with content Geneseed did not write, and because eleven of its names are
-  driven by the *runtime* as well as by an emit (`js/mcp.mjs` uses ten of them
+  driven by the *runtime* as well as by an emit (`js/hosts/mcp.mjs` uses ten of them
   for deactivate, remerge, reactivate and uninstall; `exclude` and `doctor` use the rest).
-  Its dependency closure points one way only: nothing in it calls into `js/render.mjs` or
-  `js/emit.mjs`. Keep it that way — that closure is what makes it a unit.
+  Its dependency closure points one way only: nothing in it calls into `js/build/render.mjs` or
+  `js/build/bundle.mjs`. Keep it that way — that closure is what makes it a unit.
 - **Every emit runs five stages in one order: `RENDER* → WIRE* → PRUNE → MANIFEST →
-  VERIFY`.** RENDER writes files Geneseed owns wholesale; WIRE is `js/settings.mjs`
+  VERIFY`.** RENDER writes files Geneseed owns wholesale; WIRE is `js/hosts/settings.mjs`
   reconciling files you co-own; PRUNE removes what the previous manifest owned and this
   emit no longer produces; MANIFEST records both; VERIFY re-reads the merge to confirm it
   stuck. WIRE must precede MANIFEST because wiring is what fills the `managed` record the
   manifest stores, and no RENDER may follow a WIRE because a render writes wholesale a file
   a wire has just reconciled. `tests/unit/emit_phase_order.test.mjs` fails the build if any of
   the nine emits drifts out of that order, or if a new file-mutating routine in
-  `js/settings.mjs` is called from an emit without being classified. RENDER and WIRE now run
+  `js/hosts/settings.mjs` is called from an emit without being classified. RENDER and WIRE now run
   in the *same process* — the seam that once spawned a second runtime per emit is gone — so
   the render and wire dispatchers stay two separate functions and two separate statements on
   purpose: that shape is the only thing left for the walker to check, and a gate refuses an
   emit whose sequence has lost its WIRE.
-  `bin/geneseed.mjs`'s `main()` is classified too, as the one stage no per-emit gate can see: it
+  `bin/build-driver.mjs`'s `main()` is classified too, as the one stage no per-emit gate can see: it
   writes the `.geneseed-emit` / `-footprint` / `-theme` markers and the install-registry
   record *after* every emit returns, and nothing that reconciles a file you co-own may run
   there, because there is no manifest to record the claim and no teardown able to undo it.

package/README.md

@@ -93,7 +93,7 @@ Both launchers are thin shims over the Node CLI: they need `node` (22.3+) on `PA
 
 Node ≥ 22.3 is the entire dependency list. Every subcommand, all four hooks, every web-console endpoint and both generators run from it, and every commit runs the whole unit suite plus `doctor --all` across every theme × host × footprint, on Linux and Windows both. So an install needs no second interpreter — not for the harness, and not for anything it ships. (Until 2026-08-17 the generator's output was also replayed byte for byte against recordings taken from the Python implementation. Those were retired — see [`docs/limits.md`](docs/limits.md) for the measurement that licensed it and the coverage it cost.)
 
-- **0 commands have no Node twin**: 25 of the 25 subcommands, and all four hook verbs, answer from the Node entry points. `catalog`, `mcp` and `memory` are Node-native faces the CLI table declares on top of that roster. There is no full-screen browse panel — `geneseed tui` and `geneseed menu` are verbs that refuse it by name and print the command list instead, off a terminal as well as on one.
+- **One runtime, no second one to install**: every command and all four hook verbs answer from the Node entry points. `catalog`, `mcp` and `memory` are console-facing verbs the CLI table declares alongside them. There is no full-screen browse panel — `geneseed tui` and `geneseed menu` are verbs that refuse it by name and print the command list instead, off a terminal as well as on one.
 - **Nothing you install needs an interpreter.** The `token-report` skill is a script rather than prose, and it ships as `scripts/token_report.mjs`, run with `node`; `daydream` and `herdr` hand their inline code to `node -e`. So **every bundle carries** nothing that needs one: no Python file, and no skill that shells out to an interpreter, on any host, theme or footprint. Three tests freeze that — one scans every tracked file for inline code handed to an interpreter, one globs the bundle source, and one replays the report script over seeded transcripts for all four hosts and compares the bytes.
 - **`upgrade` / `update` / `sync-self` / `bootstrap` are for a git checkout.** They `git pull` the install's own origin. From an npm install they stop before touching anything and name `npm install -g geneseed@latest` as the update instead.
 

package/SETUP.md

@@ -100,7 +100,7 @@ hand? Pick a path below.
 > **Every `geneseed-build …` below is the generator.** `npm install -g geneseed` puts it
 > on your `PATH`; without installing anything, `npx -p geneseed geneseed-build --emit
 > opencode-global` is the same command. From a checkout it is
-> `node bin/geneseed.mjs` with the same flags. Every commit re-emits with it across every
+> `node bin/build-driver.mjs` with the same flags. Every commit re-emits with it across every
 > theme × host × footprint combination and checks the result with `doctor --all`, on Linux
 > and Windows both. Until 2026-08-17 that output was also compared byte for byte against
 > recordings taken from the Python implementation; those were retired, and `docs/limits.md`

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical pointers, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.1.0**.
+> string. Current label: **3.1.2**.
 
 > **Spec status audit (2026-06-15).** Every dated spec authored before today was
 > verified against the source tree and confirmed implemented (code + tests + docs);

package/bin/{geneseed.mjs → build-driver.mjs}

@@ -20,7 +20,7 @@
  * `js_cfg()` (_build_core.py:199) always sends `structure` and `capabilityLinkRe`, because
  * the Python originals are module-level names that TESTS MUTATE — `_OWNED` membership
  * asked one level out. This driver has no Python module to mutate, so it sends neither and
- * `js/render.mjs:215`'s `cfg.structure ?? STRUCTURE` and `js/emit.mjs:680`'s
+ * `js/build/render.mjs:215`'s `cfg.structure ?? STRUCTURE` and `js/build/bundle.mjs`'s
  * `cfg.capabilityLinkRe ? ... : <default>` take their right-hand branches for the first
  * time. Those two fallbacks have been dead code since they were written — always
  * overridden by the driver that always supplies them. P4 is what makes them live.
@@ -36,35 +36,36 @@ import {
 } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import {
-  build, emitOpencodeRender, emitOpencodeGlobalRender, emitClaudeRender, phaseLog,
-} from '../js/emit.mjs';
-import { settingsIntegrityCheck } from '../js/settings.mjs';
-import { writeText, parseJson, jsonDumpsIndent, withPyNewlines } from '../js/lib/fs.mjs';
+import { build, phaseLog } from '../js/build/bundle.mjs';
+import { emitClaudeRender } from '../js/build/emit-claude.mjs';
+import { emitOpencodeRender, emitOpencodeGlobalRender } from '../js/build/emit-opencode.mjs';
+import { settingsIntegrityCheck } from '../js/hosts/settings.mjs';
+import { writeText, withPlatformNewlines } from '../js/lib/fs.mjs';
+import { parseJson, jsonDumpsIndent } from '../js/lib/json.mjs';
 // P5c moved these out of this file: `bin/geneseed-cli.mjs` needs the same four resolvers to
 // find a global install, and a resolver that decides WHERE a driver writes is the last thing
 // that should exist twice. golden.py's 259 cells are what made the move safe to attempt.
 import {
-  GLOBAL_MANIFEST, pyResolve, opencodeConfigDir, claudeConfigDir, bobConfigDir,
+  GLOBAL_MANIFEST, resolvePath, opencodeConfigDir, claudeConfigDir, bobConfigDir,
   copilotConfigDir,
-} from '../js/hosts.mjs';
+} from '../js/hosts/hosts.mjs';
 
 // P5d moved these out of this file for the reason P5c moved the host resolvers: `harness
 // status` renders to count, so `bin/geneseed-cli.mjs` needs the same checkout paths and the
 // same cfg. golden.py's 259 cells all build one, which is what made the move safe.
 import {
-  ROOT, CONFIG, THEMES, discoverNames, makeCfg, PACK_ORDER, knownRuleIds,
-} from '../js/checkout.mjs';
+  ROOT, CONFIG, discoverNames, makeCfg, PACK_ORDER, knownRuleIds,
+} from '../js/build/source.mjs';
 
 // P5f moved these, for the same arithmetic a third time: `harness rebuild-all` reads the
 // registry to find every install it must re-emit, and a CLI verb may not reach into a driver
-// for a reader. See js/registry.mjs.
-import { registryRecord, registryRoots } from '../js/registry.mjs';
+// for a reader. See js/inspect/registry.mjs.
+import { registryRecord, registryRoots } from '../js/inspect/registry.mjs';
 
 // P2. `--sync-themes` crossed into its own module rather than into this file: it is 90 lines
 // of textual surgery over committed files with a corpus of its own, and it is the half of the
 // maintainer pair that needs nothing this driver is banned from having.
-import { syncThemes } from '../js/themes.mjs';
+import { syncThemes } from '../js/build/themes.mjs';
 
 /** The nine `--emit` choices, in build.py:337-338's order. */
 const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global',
@@ -95,24 +96,24 @@ const NATIVE_CATALOG = { opencode: true, claude: true, bob: false, copilot: fals
 /** `_build_render.resolve_out` — absolute, or relative to the CURRENT WORKING DIRECTORY
  *  (not to ROOT), so the harness renders straight into any repository.
  *
- *  EXPORTED IN P5i because `js/setup.mjs` became its second caller: `_setup_summary_lines`
+ *  EXPORTED IN P5i because `js/maintain/setup.mjs` became its second caller: `_setup_summary_lines`
  *  names the AGENT.md a bundle emit just wrote, and it names it by the same resolution the
  *  emit used. Copying the one line would be a second owner of the rule that a bare `Harness`
  *  follows the invocation and not the checkout — which is what
  *  `build/the-bundle-follows-cwd-not-the-checkout` exists to gate.
  *
- *  `pyResolve` AND NOT `path.resolve`, and the difference is the whole reason `pyResolve`
+ *  `resolvePath` AND NOT `path.resolve`, and the difference is the whole reason `resolvePath`
  *  exists: the reference ends in `.resolve()`, which canonicalises — 8.3 short names expanded
  *  on Windows, symlinks followed on POSIX, the filesystem's own casing — where `path.resolve`
- *  only normalises `.`/`..`. Nine `pyResolve` call sites had the rule and this one did not.
+ *  only normalises `.`/`..`. Nine `resolvePath` call sites had the rule and this one did not.
  *  It is invisible on a machine whose paths are already canonical, which is every machine
  *  this ran on until GitHub's Windows runner handed it a `C:\\Users\\RUNNER~1\\...` and the
  *  two CLIs printed the same directory under two different names — a 70-byte difference in a
  *  line compared BYTE for byte by `test_the_two_entry_points_agree_on_stdout_BYTES`. The
- *  argument to `pyResolve` is made absolute first so its `expanduser` cannot fire: the
+ *  argument to `resolvePath` is made absolute first so its `expanduser` cannot fire: the
  *  reference does not expand `~` here, and a bare `~` is a legal directory name. */
 export function resolveOut(raw) {
-  return pyResolve(path.resolve(process.cwd(), raw));
+  return resolvePath(path.resolve(process.cwd(), raw));
 }
 
 /**
@@ -218,7 +219,7 @@ function choicesFor() {
  * carrier, and a marker whose contents depend on argument order is one that compares unequal
  * to itself. Validation is against DISCOVERY, not `PACK_ORDER`, so the refusal names the
  * packs the checkout actually has; a discovered pack missing from `PACK_ORDER` is a
- * different fault and `js/render.mjs` refuses the whole build for it.
+ * different fault and `js/build/render.mjs` refuses the whole build for it.
  */
 /**
  * `--exclude-rules "process 7,craft 3"` (or `process.7`) -> the cfg's exclusion array.
@@ -357,11 +358,11 @@ function parseArgs(argv, defaults) {
  * hand-rolled copy would have its own `--target` alias, its own `choices` lists and its own
  * `-h`, and `test_the_help_text_names_every_flag_the_reference_takes` gates only this one.
  *
- * `withPyNewlines` because the refusal and `-h` paths WRITE: called from `bin/geneseed.mjs`
+ * `withPlatformNewlines` because the refusal and `-h` paths WRITE: called from `bin/build-driver.mjs`
  * they sit inside `main`'s funnel, and called from the CLI binary they would not.
  */
 export function parseDriverArgs(argv) {
-  return withPyNewlines(() => parseArgs(argv, configDefaults()));
+  return withPlatformNewlines(() => parseArgs(argv, configDefaults()));
 }
 
 function choice(flag, value, allowed) {
@@ -441,7 +442,7 @@ function die(code, msg) {
  * re-emit, which is P10's migration arriving five phases early.
  *
  * EXPORTED SINCE P6i, because the emitter is no longer its only caller.
- * `js/uninstall.mjs`'s `remergeClaudeHooks` re-merges the canonical hooks when a disabled
+ * `js/maintain/uninstall.mjs`'s `remergeClaudeHooks` re-merges the canonical hooks when a disabled
  * Claude install is turned back on, and `mergeClaudeSettings` refuses to guess the pair —
  * correctly. There is exactly one right answer on this side and it is this function, so the
  * second caller imports it rather than restating two lines that must never drift: a
@@ -464,14 +465,14 @@ export function hookRunnerEntry() {
  * through `_build_core._claude_config_dir`, an `_OWNED` name precisely because the suite
  * redirects it at a sandbox, and a redirect that stops at a subprocess half-works in
  * silence. The child must therefore never derive it — but this file is the PARENT, so
- * deriving it is exactly this file's job, and `js/emit.mjs` receives the answer.
+ * deriving it is exactly this file's job, and `the host emit` receives the answer.
  *
  * POSIX spelling, per the original: `claudeMdExcludes` entries are glob patterns, where a
  * backslash is an escape, so the Windows-native form risks never matching.
  */
 function preambleExclude(claudeMd) {
   if (path.basename(claudeMd) !== 'CLAUDE.md') return null;
-  return pyResolve(path.join(claudeConfigDir(), 'CLAUDE.md')).split(path.sep).join('/');
+  return resolvePath(path.join(claudeConfigDir(), 'CLAUDE.md')).split(path.sep).join('/');
 }
 
 /**
@@ -566,10 +567,6 @@ function pruneOwned(oc, oldOwned, owned) {
   }
 }
 
-function isDir(p) {
-  try { return statSync(p).isDirectory(); } catch { return false; }
-}
-
 /**
  * `_build_global._project_survivors` — registered per-repo PROJECT installs of `emitName`.
  *
@@ -736,7 +733,7 @@ function emitOpencodeGlobal(cfg, args, out) {
  * `_build_global._emit_claude_core` — the shared engine behind six emits.
  *
  * Only the two Copilot ones run through it so far, and that is a deliberate split rather
- * than an arbitrary stopping point: `js/emit.mjs:1166` gates the entire settings/hook path
+ * than an arbitrary stopping point: `js/build/emit-claude.mjs's wire` gates the entire settings/hook path
  * behind `if (!isCopilot)`, so a Copilot emit never reaches `hookPrefix` and therefore never
  * needs `hookOpts` — the pair of machine-absolute values (`sys.executable` and the harness
  * entry point) that a Node driver has no way to produce. Copilot crossing first isolates
@@ -1007,7 +1004,7 @@ export function emitProjectInto(host, { theme, out, root, footprint = 'full', do
   // same reason: a drift reader that renders `expected` at the DEFAULT pack set reports the
   // whole doctrines section as edited on every narrowed install. `null` means "no opinion" and
   // `makeCfg` renders all four, which is what every validation caller wants.
-  return withPyNewlines(() => emit(makeCfg(doctrines ? { doctrines } : {}),
+  return withPlatformNewlines(() => emit(makeCfg(doctrines ? { doctrines } : {}),
     { theme, footprint, root }, out));
 }
 
@@ -1020,7 +1017,7 @@ export function emitProjectInto(host, { theme, out, root, footprint = 'full', do
  * exactly as `run` inherits it below.
  */
 export function buildInto({ theme, out, footprint = 'lean' }) {
-  return withPyNewlines(
+  return withPlatformNewlines(
     () => build(makeCfg(), theme, out, { footprint, nativeCatalog: false }),
   );
 }
@@ -1042,7 +1039,7 @@ export function emitGlobalInto(host, {
   // rendering at `peer`/`direct`; the drift readers pass what the deployment actually says,
   // because rendering `expected` at the defaults reports AGENT.md as edited on every install
   // that chose a register — the same scar the footprint left in `diffCollect`, one axis over.
-  return withPyNewlines(
+  return withPlatformNewlines(
     () => emit(
       // THE PACK SELECTION RIDES THE SAME RAIL, with one difference: `doctrinesOfDir` answers
       // `null` for "no marker / undetectable", and that must render at ALL packs rather than
@@ -1062,16 +1059,16 @@ export function emitGlobalInto(host, {
  * `_harness_build.cmd_build` is `run([sys.executable, BUILD, *extra]).returncode` — Python
  * needs a second process because `build.py` is a different PROGRAM. Here it is a module in
  * the same one, and `bin/geneseed-cli.mjs` is under a transitive `child_process` ban, so
- * `js/generate.mjs` calls this directly. The export is what makes the auto-run below need a
+ * `js/build/generate.mjs` calls this directly. The export is what makes the auto-run below need a
  * guard: without one, importing this file to reach `main` would RUN the generator with the
  * CLI's argv.
  */
 export function main(argv) {
-  // `withPyNewlines` is what makes this driver's bytes Python's bytes on Windows, for every
+  // `withPlatformNewlines` is what makes this driver's bytes Python's bytes on Windows, for every
   // print site in the whole render tree at once — see its docblock for why a funnel and not
-  // 25 calls to `pyPrint`. It wraps the `catch` as well as `run`, because `die` writes its
+  // 25 calls to `printOut`. It wraps the `catch` as well as `run`, because `die` writes its
   // line on the way out.
-  return withPyNewlines(() => {
+  return withPlatformNewlines(() => {
     try {
       return run(argv);
     } catch (e) {
@@ -1092,12 +1089,12 @@ function run(argv) {
   // different places because the transitive `child_process` ban splits them.
   //
   // `--sync-themes` is HERE, because it needs nothing this driver may not have: it reads
-  // `themes/`, rewrites the files textually, and prints. `js/themes.mjs` carries it.
+  // `themes/`, rewrites the files textually, and prints. `js/build/themes.mjs` carries it.
   // Non-zero when files were CHANGED (0 == already in sync), so CI can run it as a drift
   // check — build.py:393-397's mapping, and a refusal (exit 2) if the template is unreadable.
   if (args.syncThemes) return syncThemes() ? 1 : 0;
   // `--validate-only` is NOT, and cannot be: its source-tree half is the doctor, and
-  // `js/doctor.mjs` starts a process (`node --check` over the OpenCode plugins). This driver
+  // `js/inspect/checks-authoring.mjs` starts a process (`node --check` over the OpenCode plugins). This driver
   // is under a transitive ban on reaching any such module, gated twice — by a source grep in
   // `tests/test_node_cli_parity.py` and by an import walk in `tests/test_hook_cli_parity.py`.
   // So the tool crossed onto the CLI binary, which already carries the doctor, and this flag
@@ -1172,10 +1169,10 @@ function run(argv) {
 }
 
 /**
- * Run only when this file IS the entry point, not when `js/generate.mjs` imports it.
+ * Run only when this file IS the entry point, not when `js/build/generate.mjs` imports it.
  *
  * `import.meta.main` would say this in one word and is Node 24; the spec's `engines` floor
- * is still open and this machine runs v22, the same reason `js/emit.mjs` avoids it. So the
+ * is still open and this machine runs v22, which is why the comparison is spelled out rather than using it. So the
  * check is the manual one, through `realpathSync` because `process.argv[1]` is whatever the
  * caller typed and `import.meta.url` is always the resolved file — an `npx`-generated shim
  * or a `geneseed link` symlink makes those differ as strings while naming the same file.
@@ -1183,9 +1180,9 @@ function run(argv) {
  * BOTH ways of getting this wrong are gated, which is why it is a guard and not a comment,
  * and both were measured rather than argued:
  *
- *   * stuck FALSE — `node bin/geneseed.mjs` becomes a silent no-op: 259 golden cells.
+ *   * stuck FALSE — `node bin/build-driver.mjs` becomes a silent no-op: 259 golden cells.
  *   * stuck TRUE — importing this file runs the generator on the IMPORTER's argv, so it is
- *     not only `build` that breaks. `bin/geneseed-cli.mjs` reaches `js/generate.mjs` at
+ *     not only `build` that breaks. `bin/geneseed-cli.mjs` reaches `js/build/generate.mjs` at
  *     module load, so every CLI verb dies in the driver's flag parser: **62 of the 166
  *     acceptance cells**, `exclude` and `status` and `version` among them.
  */

package/bin/geneseed-cli.mjs

@@ -4,24 +4,24 @@
  * invokes. `bin/geneseed-hook.mjs` is the twin of the four it does.
  *
  * WHY A THIRD BINARY. P5c's whole question, and the three candidates were: grow the hook
- * entry, put verbs in `bin/geneseed.mjs`, or this. Each of the other two costs something
+ * entry, put verbs in `bin/build-driver.mjs`, or this. Each of the other two costs something
  * specific.
  *
  *   * GROWING `bin/geneseed-hook.mjs` weakens the gate the design now rests on.
  *     `test_the_entry_carries_exactly_the_verbs_the_emitter_wires` asserts EQUALITY between
- *     that file's table and the hooks `js/settings.mjs` wires, and P5b made it load-bearing:
+ *     that file's table and the hooks `js/hosts/settings.mjs` wires, and P5b made it load-bearing:
  *     the shim is machine-wide (`~/.geneseed/bin/geneseed-hook[.cmd]`, no per-install
  *     component) and last-writer-wins, so a Node emit owns the hooks of installs Python
  *     wrote, and the verb sets matching is what makes that safe. Relaxing it to a subset
  *     relation to admit `exclude` would be the single most damaging edit available here.
  *     Two more reasons point the same way, and the second is not in that file's own
- *     argument: `exclude`'s writer imports `js/settings.mjs` and `js/emit.mjs`, ~2,100 lines
+ *     argument: `exclude`'s writer imports `js/hosts/settings.mjs` and `the emit modules`, ~2,100 lines
  *     that would then load on EVERY PreToolUse call — the spec's hook-latency budget says
  *     the shim must exec a minimal entry, not the CLI. And the entry's refusal list, which
  *     names every verb it does not carry, is what makes "silently accepted `doctor` and did
  *     nothing" impossible; every Geneseed hook exits 0 and signals through stdout, so a
  *     no-op and a success are one observation.
- *   * `bin/geneseed.mjs` IS `build.py`'s `main()` — a different Python program from
+ *   * `bin/build-driver.mjs` IS `build.py`'s `main()` — a different Python program from
  *     `rituals/harness.py`, not a different half of the same one. It parses generator FLAGS
  *     with a partition asserted over them (`test_the_node_driver_classifies_every_emit`),
  *     `tests/golden.py` drives it 259 times per run, and it is under a hard `child_process`
@@ -31,7 +31,7 @@
  *
  * What this costs is what the P5b handoff predicted: a second acceptance matrix. It is paid
  * in `tests/harness_golden.py`, which now carries a `bin` per cell and takes `--new-cli`
- * beside `--new` — and it would have been paid identically by the `bin/geneseed.mjs` option,
+ * beside `--new` — and it would have been paid identically by the `bin/build-driver.mjs` option,
  * so it is not a discriminator between the two.
  *
  * THE VERB SET REFUSES THE REST BY NAME, exactly as the hook entry does. It carries 22 of the
@@ -46,24 +46,25 @@
  * for the file as a whole is that its transitive imports now reach two modules that spawn,
  * which `_ALLOWED_SPAWNS` in `tests/test_hook_cli_parity.py` declares argv by argv.
  */
-import { cmdCatalog } from '../js/catalog.mjs';
-import { cliSpec, printHelp } from '../js/cli.mjs';
-import { cmdDiff } from '../js/diff.mjs';
-import { cmdDoctor, cmdValidate } from '../js/doctor.mjs';
-import { parseDriverArgs } from './geneseed.mjs';
-import { cmdExclude } from '../js/excludes.mjs';
-import { cmdBuild, cmdPrompt, cmdRebuildAll, cmdTheme } from '../js/generate.mjs';
-import { cmdMigrate } from '../js/migrate.mjs';
-import { pyInt } from '../js/lib/fs.mjs';
-import { cmdLink, cmdUnlink } from '../js/link.mjs';
-import { cmdMcp } from '../js/mcp.mjs';
-import { cmdMemory } from '../js/memory.mjs';
-import { cmdHome, cmdMenu } from '../js/menu.mjs';
-import { cmdTui } from '../js/tui.mjs';
-import { cmdSetup } from '../js/setup.mjs';
-import { cmdStatus, cmdVersion } from '../js/status.mjs';
-import { cmdUninstall } from '../js/uninstall.mjs';
-import { cmdBootstrap, cmdSyncSelf, cmdUpgrade } from '../js/update.mjs';
+import { cmdCatalog } from '../js/build/catalog.mjs';
+import { cliSpec, printHelp } from '../js/ui/cli.mjs';
+import { cmdDiff } from '../js/inspect/diff.mjs';
+import { cmdDoctor } from '../js/inspect/doctor.mjs';
+import { cmdValidate } from '../js/inspect/validate.mjs';
+import { parseDriverArgs } from './build-driver.mjs';
+import { cmdExclude } from '../js/inspect/excludes.mjs';
+import { cmdBuild, cmdPrompt, cmdRebuildAll, cmdTheme } from '../js/build/generate.mjs';
+import { cmdMigrate } from '../js/maintain/migrate.mjs';
+import { parseIntStrict } from '../js/lib/text.mjs';
+import { cmdLink, cmdUnlink } from '../js/hosts/link.mjs';
+import { cmdMcp } from '../js/hosts/mcp.mjs';
+import { cmdMemory } from '../js/maintain/memory.mjs';
+import { cmdHome, cmdMenu } from '../js/ui/menu.mjs';
+import { cmdTui } from '../js/ui/tui.mjs';
+import { cmdSetup } from '../js/maintain/setup.mjs';
+import { cmdStatus, cmdVersion } from '../js/inspect/status.mjs';
+import { cmdUninstall } from '../js/maintain/uninstall.mjs';
+import { cmdBootstrap, cmdSyncSelf, cmdUpgrade } from '../js/maintain/update.mjs';
 import { cmdWeb } from '../js/web/server.mjs';
 
 /**
@@ -74,7 +75,7 @@ import { cmdWeb } from '../js/web/server.mjs';
  * `add_argument` calls, gated against the subparsers by NAME only. When
  * `_web_docs._cli_reference` stopped walking the parser and started reading the CLI table,
  * keeping that would have made THREE transcriptions of one parser — the parser, the file, and
- * here. So the argument surface comes from `js/cli.mjs`'s `cliSpec()`, derived from the same
+ * here. So the argument surface comes from `js/ui/cli.mjs`'s `cliSpec()`, derived from the same
  * file the docs page serves, and what is left in a row is the one thing a data file cannot
  * hold: the FUNCTION.
  *
@@ -150,14 +151,14 @@ const VERBS = {
     // Points at `cmdSyncSelf` rather than at `cmdUpgrade`, and that is not tidiness:
     // `sync-self` DROPS its `ref` before `upgrade` ever sees it, where `upgrade` both WARNS
     // about one and re-reads it as a theme — so the two verbs answer `sync-self cyberpunk`
-    // and `sync-self v1.2.3` differently. See `js/update.mjs`'s `syncSelf` for both halves.
+    // and `sync-self v1.2.3` differently. See `js/maintain/update.mjs`'s `syncSelf` for both halves.
     fn: cmdSyncSelf,
   },
   bootstrap: {
     fn: cmdBootstrap,
   },
   // P7a. Both are DISPATCHERS whose off-TTY arm is the whole of what a cell can reach, and
-  // `menu`'s on-TTY arm falls back rather than opening a panel — `js/menu.mjs`'s header
+  // `menu`'s on-TTY arm falls back rather than opening a panel — `js/ui/menu.mjs`'s header
   // argues both.
   menu: {
     fn: cmdMenu,
@@ -168,7 +169,7 @@ const VERBS = {
   // P7b, and it is the twenty-fifth and last. `cmd_tui`'s FIRST arm is `if not sys.stdin.
   // isatty()`, so off a TTY — which is every cell there is — the verb is one line and an
   // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
-  // `js/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
+  // `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
   // panel-unavailable line rather than inventing a second full-screen UI, and
   // `tests/test_tui_boundary.py` asserts that the arm it declares is genuinely unreachable
   // here rather than merely untested.
@@ -201,7 +202,7 @@ const VERBS = {
 };
 
 function die(code, msg) {
-  // CRLF on Windows, for the same reason `js/hooks.mjs`'s funnels translate: argparse writes
+  // CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse writes
   // this line through `sys.stderr`, which does.
   process.stderr.write(`geneseed: error: ${msg}${process.platform === 'win32' ? '\r\n' : '\n'}`);
   return code;
@@ -211,7 +212,7 @@ function die(code, msg) {
  * `argparse`'s surface for the verbs here, and only theirs: ordered positionals, some
  * optional, some with `choices`.
  *
- * `spec` comes from `js/cli.mjs`'s `cliSpec()` since P10c — derived from `js/cli-table.json`,
+ * `spec` comes from `js/ui/cli.mjs`'s `cliSpec()` since P10c — derived from `js/cli-table.json`,
  * which P2 made the owned document. This function's rules are unchanged; what
  * changed is that the table they run over is no longer written out by hand beside them. Every
  * argparse feature named below is a row of that derivation.
@@ -274,7 +275,7 @@ function parse(spec, argv) {
     // `type=int`. argparse's own wording, minus the usage block it prints around it — the
     // same rule the rest of this parser follows. The VALUE stays a string in `args`; the
     // command converts, and this is what guarantees the conversion cannot fail there.
-    if ((spec.ints ?? []).includes(flag) && pyInt(value) === null) {
+    if ((spec.ints ?? []).includes(flag) && parseIntStrict(value) === null) {
       return { error: `argument ${flag}: invalid int value: '${value}'` };
     }
     args[dest] = value;
@@ -347,7 +348,7 @@ async function main(argv) {
   //
   // So a row would have meant amending two gates and recording a corpus half blind. It takes
   // the generator's own parser (see `parseDriverArgs`) because its flags are the generator's,
-  // and it is on THIS binary — not on `bin/geneseed.mjs` — because it runs the doctor, which
+  // and it is on THIS binary — not on `bin/build-driver.mjs` — because it runs the doctor, which
   // starts a process the driver is banned from reaching.
   if (verb === 'validate') {
     try {
@@ -397,7 +398,7 @@ async function main(argv) {
     return await spec.fn(parsed.args);
   } catch (e) {
     // `e.exitCode` is the generator's existing marker for a DELIBERATE refusal that has
-    // already explained itself on stderr — `js/emit.mjs:1289` reads the same flag, and it is
+    // already explained itself on stderr — `js/build/emit-claude.mjs` reads the same flag, and it is
     // `sys.exit(<message>)` on the Python side. Anything without it is a crash and keeps its
     // stack: Python prints a traceback for an unhandled exception, and turning one into a
     // tidy one-liner here would hide a bug behind a refusal's clothing.