geneseed 3.1.0 → 3.1.2

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,33 +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 } from '../js/checkout.mjs';
+import {
+  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',
@@ -93,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));
 }
 
 /**
@@ -124,6 +127,7 @@ export function resolveOut(raw) {
 function configDefaults() {
   const d = {
     theme: 'neutral', posture: 'peer', mode: 'direct', doctrines: [...PACK_ORDER],
+    excludeRules: [],
   };
   if (!existsSync(CONFIG)) return d;
   try {
@@ -146,6 +150,19 @@ function configDefaults() {
             + 'list of known pack names — using all packs.\n');
         }
       }
+      // The second axis, read the same forgiving way and defaulting the OTHER direction: a
+      // bad value excludes NOTHING, because the safe answer for a list of things to take
+      // away is to take nothing away. Same reasoning as `doctrines` defaulting to all.
+      if (data.excludeRules !== undefined) {
+        if (Array.isArray(data.excludeRules)
+          && data.excludeRules.every((x) => typeof x === 'string')) {
+          d.excludeRules = [...new Set(data.excludeRules.map((x) => x.replace(/[ \t]+/, '.')))]
+            .sort();
+        } else {
+          process.stderr.write(`[geneseed] WARN: ${path.basename(CONFIG)} "excludeRules" is `
+            + 'not a list of rule addresses — excluding nothing.\n');
+        }
+      }
     }
   } catch {
     process.stderr.write(`[geneseed] WARN: ${path.basename(CONFIG)} is unreadable — `
@@ -162,7 +179,7 @@ function configDefaults() {
  */
 const VALUED = {
   '--theme': 'theme', '--posture': 'posture', '--mode': 'mode',
-  '--doctrines': 'doctrines',
+  '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules',
   '--out': 'out', '--target': 'out', '--emit': 'emit',
   '--footprint': 'footprint', '--root': 'root',
 };
@@ -202,8 +219,39 @@ 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.
+ *
+ * BOTH SPELLINGS ACCEPTED ON THE WAY IN, ONE ON THE WAY OUT. The carrier's marker line and
+ * every citation in the corpus spell a rule `process 7`; the console's deep link and the
+ * catalogue spell it `process.7`. A flag that took only one of them would be wrong for
+ * whichever half of the documentation the reader had open, so it takes either and normalises
+ * to the dotted form the code compares.
+ *
+ * ⚠ VALIDATED AGAINST THE PACK FILES, NOT A RANGE. `process 9` and `craft 0` are both
+ * refusals, and so is a pack this checkout does not ship — an exclusion that names nothing is
+ * a typo that would otherwise take away nothing in silence, which is the failure this flag
+ * can least afford: the user asked for a rule to STOP binding and it would keep binding.
+ * Sorted, deduped, for the same marker-stability reason `--doctrines` is.
  */
+function parseExcludeRules(value) {
+  const s = value.trim();
+  if (s === 'none' || s === '') return [];
+  const known = knownRuleIds();
+  const out = [];
+  for (const raw of s.split(',').map((x) => x.trim()).filter(Boolean)) {
+    const id = raw.replace(/[ \t]+/, '.');
+    if (!known.includes(id)) {
+      die(2, `argument --exclude-rules: invalid choice: '${raw}' (choose from `
+        + `${known.map((c) => `'${c.replace('.', ' ')}'`).join(', ')}, or 'none')`);
+    }
+    out.push(id);
+  }
+  return [...new Set(out)].sort();
+}
+
 function parseDoctrines(value) {
   const s = value.trim();
   const known = discoverNames('doctrines', PACK_ORDER[0]);
@@ -264,6 +312,7 @@ function parseArgs(argv, defaults) {
   const args = {
     theme: defaults.theme, posture: defaults.posture, mode: defaults.mode,
     doctrines: defaults.doctrines,
+    excludeRules: defaults.excludeRules,
     out: 'Harness', emit: 'files', footprint: 'lean', root: null,
     syncThemes: false, validateOnly: false, verbose: false,
   };
@@ -296,6 +345,7 @@ function parseArgs(argv, defaults) {
   // Only when the flag was actually PASSED is this a string; left at its default it is
   // already the array `configDefaults` built, and re-parsing an array would stringify it.
   if (typeof args.doctrines === 'string') args.doctrines = parseDoctrines(args.doctrines);
+  if (typeof args.excludeRules === 'string') args.excludeRules = parseExcludeRules(args.excludeRules);
   return args;
 }
 
@@ -308,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) {
@@ -392,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
@@ -415,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('/');
 }
 
 /**
@@ -517,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`.
  *
@@ -687,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
@@ -958,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));
 }
 
@@ -971,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 }),
   );
 }
@@ -993,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
@@ -1013,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) {
@@ -1043,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
@@ -1123,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.
@@ -1134,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.

package/bin/geneseed-hook.mjs

@@ -3,7 +3,7 @@
  * The hook entry point — a Node twin of `rituals/harness.py` for the four verbs the
  * emitted `settings.json` actually invokes.
  *
- * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/geneseed.mjs`. Three reasons,
+ * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
  * and each alone would be enough:
  *
  *   * The generator driver is under a hard `child_process` ban
@@ -14,11 +14,11 @@
  *   * The hook shim bakes ONE entry and forwards `%*` to it. `harness.py` is that entry on
  *     the Python side; a Node twin needs its own, invoked as `<node> <this> context
  *     --root "<cfg>"`.
- *   * `bin/geneseed.mjs` parses generator FLAGS (`--emit`, `--theme`, `--footprint`), and
+ *   * `bin/build-driver.mjs` parses generator FLAGS (`--emit`, `--theme`, `--footprint`), and
  *     `test_the_node_driver_classifies_every_emit` asserts a partition over them. Verbs
  *     are a different shape and would sit awkwardly inside that.
  *
- * WHAT BAKES THIS FILE, SINCE P5b. `bin/geneseed.mjs` writes `<node> <checkout>/bin/
+ * WHAT BAKES THIS FILE, SINCE P5b. `bin/build-driver.mjs` writes `<node> <checkout>/bin/
  * geneseed-hook.mjs` into the machine-wide shim, so an install this driver emitted needs no
  * Python for its hooks. The exit-4 refusal it used to raise when no interpreter was
  * discoverable is gone with the discovery that fed it.
@@ -37,8 +37,8 @@
  * every Geneseed hook returns 0 and signals through stdout — so "did nothing" and "worked"
  * are the same observation.
  */
-import { cmdContext, cmdGitGate, cmdRuleGate, cmdLearn } from '../js/hooks.mjs';
-import { printHelp } from '../js/cli.mjs';
+import { cmdContext, cmdGitGate, cmdRuleGate, cmdLearn } from '../js/hosts/hooks.mjs';
+import { printHelp } from '../js/ui/cli.mjs';
 
 const VERBS = {
   context: { fn: cmdContext, flags: { '--root': 'root' } },
@@ -53,7 +53,7 @@ const VERBS = {
 };
 
 function die(code, msg) {
-  // CRLF on Windows, for the same reason `js/hooks.mjs`'s funnels translate: argparse
+  // 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-hook: error: ${msg}${process.platform === 'win32' ? '\r\n' : '\n'}`);
   return code;
@@ -115,7 +115,7 @@ function main(argv) {
   // `<verb> --help`, for the same reason and by the same owner as `bin/geneseed-cli.mjs`:
   // argparse holds `-h` at the parser, so this entry's `parse` calls it an unrecognized
   // argument. The four hook verbs are four of the reference's 26 and had the same gap.
-  // `js/cli.mjs` reads the CLI table lazily, inside its functions, so importing it costs this
+  // `js/ui/cli.mjs` reads the CLI table lazily, inside its functions, so importing it costs this
   // entry a module parse and no file read on the hook path.
   if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
     const rc = printHelp('geneseed-hook', verb);