geneseed 3.1.0 → 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.

package/js/build/bundle.mjs

@@ -0,0 +1,231 @@
+/**
+ * `build` — render one theme's sources into a bundle directory, and the two checks that
+ * decide whether it may.
+ *
+ * The LAYER BOTH HOST EMITS SIT ON, and that is why it is not in `emit.mjs` with them: the
+ * first map left it there, and the derived imports came back with `emit-opencode.mjs` and
+ * `emit-claude.mjs` importing `emit.mjs` while `emit.mjs` imported them back. A bundle is
+ * produced before any host is chosen, so it belongs UNDER the emitters, not beside them.
+ *
+ * `assertSourceComplete` scans the TEMPLATE rather than the render, and the src-dirs marker
+ * is how a re-emit knows which directory names the last one used.
+ */
+import path from 'node:path';
+import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { copyFile, readText, writeText } from '../lib/fs.mjs';
+import { jsonDumpsIndent, parseJson, formatReprAscii, isTruthy } from '../lib/json.mjs';
+import { OWNED_SRC_DIRS, SRC_DIRS_MARKER, TMPL_SPEC_RE, isDir, isFile } from './emit-common.mjs';
+import { SRC_DIR_TOKENS, renderAll } from './render.mjs';
+import {
+  ensureBundleGitignore, ensureContextStub, ensureMemoryIndex, ensureNotebookIndex,
+  ensureProfileStub, ensureRulesStub, ensureWikiStub,
+} from './stubs.mjs';
+import { writeVersion } from './version.mjs';
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Source completeness
+// ---------------------------------------------------------------------------
+
+/** `_build_render._missing_referenced_specs` — scans the TEMPLATE, not the render. */
+function missingReferencedSpecs(cfg) {
+  let tmpl;
+  try {
+    tmpl = readText(path.join(cfg.src, 'AGENT.md.tmpl'));
+  } catch {
+    return [];
+  }
+  const missing = new Set();
+  for (const [, kind, name] of tmpl.matchAll(TMPL_SPEC_RE)) {
+    const dir = kind.toLowerCase();
+    if (name !== '_template' && !isFile(path.join(cfg.src, dir, `${name}.md`))) {
+      missing.add(`${dir}/${name}.md`);
+    }
+  }
+  return [...missing].sort();
+}
+
+/**
+ * `_build_render.assert_source_complete`.
+ *
+ * Python raises `SystemExit(1)` after writing to stderr. Here the message goes to the
+ * captured stderr buffer and the throw carries the exit code, which the driver turns
+ * into a process status by `bin/build-driver.mjs`'s `main` — so the caller sees the same stream
+ * bytes and the same exit status whichever runtime rendered.
+ */
+export function assertSourceComplete(cfg, context = '') {
+  const missing = missingReferencedSpecs(cfg);
+  if (!missing.length) return;
+  const where = context ? ` (${context})` : '';
+  process.stderr.write(
+    `[geneseed][E-INCOMPLETE] ✗ source is incomplete${where}: AGENT.md references `
+    + `${missing.length} spec(s) with no file under src/:\n`
+    + missing.map((m) => `    - ${m}\n`).join('')
+    + '[geneseed] ✗ Refusing to emit — a partial source would write dead links '
+    + 'and a global re-emit would delete the good copies in an existing install.\n'
+    + '[geneseed] ✗ Re-sync the source (./geneseed update, or re-run the upgrade) '
+    + 'and try again.\n');
+  const e = new Error('source is incomplete');
+  e.exitCode = 1;
+  throw e;
+}
+
+// ---------------------------------------------------------------------------
+// The owned-dir marker
+// ---------------------------------------------------------------------------
+
+/** `_build_render._read_prior_src_dirs` — `{}` on anything unreadable or not an object. */
+function readPriorSrcDirs(out) {
+  let data;
+  try {
+    data = parseJson(readText(path.join(out, SRC_DIRS_MARKER)));
+  } catch {
+    return {};
+  }
+  return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+}
+
+/** `_build_render._write_src_dirs_marker` — temp + replace. */
+function writeSrcDirsMarker(out, resolved) {
+  const tmp = path.join(out, `${SRC_DIRS_MARKER}.tmp`);
+  writeText(tmp, `${jsonDumpsIndent(resolved)}\n`);
+  renameSync(tmp, path.join(out, SRC_DIRS_MARKER));
+}
+
+/**
+ * The guard on the prune of a RENAMED owned dir — `build`'s one destructive path driven
+ * by file content rather than by code.
+ *
+ * `.geneseed-srcdirs.json` is a plain file a user (or another tool) can edit, and the
+ * name in it is joined onto `out` and handed to a recursive delete. `".."` would take out
+ * the bundle's PARENT, an absolute path replaces `out` entirely under Python's
+ * `Path.__truediv__`, and `"a/b"` reaches into nested content. Only a plain
+ * single-segment name resolving directly under `out` is ever deleted.
+ */
+function safePriorDirName(out, priorName) {
+  return typeof priorName === 'string'
+    && priorName !== '.' && priorName !== '..'
+    && !path.isAbsolute(priorName)
+    && path.basename(priorName) === priorName
+    && path.dirname(path.resolve(out, priorName)) === path.resolve(out);
+}
+
+// ---------------------------------------------------------------------------
+// build
+// ---------------------------------------------------------------------------
+
+/**
+ * `_build_render.build` — render the bundle into `out`.
+ *
+ * `out` arrives as the STRING Python already resolved, and is echoed into the progress
+ * lines verbatim: Python interpolates `str(Path)`, which is backslash-separated on
+ * Windows, and re-deriving it here would differ by separator in every message.
+ */
+/**
+ * THE PHASE BOUNDARY MARKER — T8, and the whole of what this port owes
+ * `tests/test_emit_phase_order.py`.
+ *
+ * Every emit runs its stages in one order: RENDER* → WIRE* → PRUNE → MANIFEST → VERIFY. RENDER
+ * writes files Geneseed owns wholesale; WIRE reconciles files the USER co-owns (the
+ * CLAUDE.md/AGENTS.md managed block, settings(.local).json, opencode.json) by reading what is
+ * already there and merging into it. WIRE must precede MANIFEST because wiring is what fills the
+ * `managed` record the manifest writes, and every teardown path unwires exactly what was wired.
+ *
+ * WHY A RUNTIME LOG AND NOT A SOURCE WALK. The reference gated this with five `ast` walks over
+ * its own generator, and could, because it keeps `_claude_render` / `_claude_wire` as two
+ * dispatchers and therefore two statements at every call site — a shape its own docstring calls
+ * "not incidental, it is what leaves this walker something to check". THIS PORT DOES NOT HAVE
+ * THAT SHAPE: `claudeWire` is a real function but the two OpenCode emits inline their merge
+ * (`emitOpencodeRender`, `emitOpencodeGlobalRender`), and PRUNE/MANIFEST/VERIFY are not in this
+ * module at all — they are in `bin/build-driver.mjs`'s driver bodies. A walker would have to span two
+ * files and would still be reading source rather than watching a run.
+ *
+ * So the order is made OBSERVABLE instead, which is strictly the better gate: it reports what
+ * actually executed, in the order it executed, including the branch a given host took.
+ *
+ * ⚠ BEHIND AN ENV VAR THE THREE REPLAYERS DO NOT SET, and that is the entire safety argument.
+ * `cellEnv` clears every `GENESEED_*` knob by prefix, so no recorded cell can turn this on and
+ * the emit corpus cannot move by one byte. It writes to STDERR, never stdout: stdout is the
+ * decision channel every Geneseed hook signals through, and a stray byte there turns a blocking
+ * gate into a silently permissive one.
+ *
+ * Read at CALL time, not at import, so one process can drive several emits under it.
+ */
+export function phaseLog(phase) {
+  if (!process.env.GENESEED_PHASE_LOG) return;
+  process.stderr.write(`[geneseed:phase] ${phase}\n`);
+}
+
+export function build(cfg, themeName, out, { footprint = 'full', nativeCatalog = false } = {}) {
+  phaseLog('RENDER');
+  const { theme, items } = renderAll(cfg, themeName, { footprint, nativeCatalog });
+  assertSourceComplete(cfg, `theme '${themeName}'`);
+  mkdirSync(out, { recursive: true });
+
+  // Wipe the owned dirs ONLY inside an established bundle: a first render into an
+  // arbitrary repo (`--out .`) must never delete an agents/ or skills/ the USER owns.
+  const isBundle = isFile(path.join(out, '.geneseed-theme')) || isFile(path.join(out, VERSION_MARKER));
+  const priorSrcDirs = isBundle ? readPriorSrcDirs(out) : {};
+  const resolvedSrcDirs = {};
+  for (const srcDir of OWNED_SRC_DIRS) {
+    // `theme.get(token, srcDir)` — `??` agrees with it except for an explicit JSON null,
+    // where Python would go on to join `None` onto a path and raise. No theme has one.
+    const dirname = theme[SRC_DIR_TOKENS[srcDir]] ?? srcDir;
+    resolvedSrcDirs[srcDir] = dirname;
+    const managed = path.join(out, dirname);
+
+    // `isTruthy`, not `priorName &&`: the marker is user-editable JSON, and Python's
+    // `if prior_name` is false for `[]`, `{}` and `0` where JS's is true for the first
+    // two. Getting that wrong warns about a value Python skips in silence — a stderr
+    // divergence reachable only from a hand-edited file, which is the one place nobody
+    // would look for it.
+    const priorName = priorSrcDirs[srcDir];
+    if (isBundle && isTruthy(priorName) && priorName !== dirname) {
+      if (safePriorDirName(out, priorName)) {
+        const stale = path.join(out, priorName);
+        if (isDir(stale)) rmSync(stale, { recursive: true, force: true });
+      } else {
+        process.stderr.write('[geneseed] WARN: ignoring suspicious prior dir name '
+          + `${formatReprAscii(priorName)} recorded in ${SRC_DIRS_MARKER} - not pruned.\n`);
+      }
+    }
+
+    if (!isDir(managed)) continue;
+    if (isBundle) {
+      rmSync(managed, { recursive: true, force: true });
+    } else {
+      // STDOUT, and ASCII-only: this print crashed with UnicodeEncodeError on a cp1252
+      // Windows console when it carried a warning-sign emoji.
+      process.stdout.write(`[geneseed] WARN: ${managed} already exists and ${out} is not a `
+        + 'Geneseed bundle — keeping it; rendered files merge into it.\n');
+    }
+  }
+
+  const nbDirname = theme[SRC_DIR_TOKENS.notebook] ?? 'notebook';
+  for (const { rel, text, src } of items) {
+    const dest = path.join(out, rel);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    // The notebook is the agent's sovereign space: seeded files are written once and
+    // never re-emitted, so the agent may rewrite its own rules. Only `.gitignore` is
+    // re-asserted — the one law it cannot lift.
+    const parts = rel.split('/');
+    if (parts[0] === nbDirname && path.basename(rel) !== '.gitignore' && existsSync(dest)) {
+      continue;
+    }
+    if (text !== null) writeText(dest, text);
+    else copyFile(src, dest);
+  }
+
+  writeText(path.join(out, '.geneseed-theme'), `${themeName}\n`);
+  writeVersion(cfg, out);
+  writeSrcDirsMarker(out, resolvedSrcDirs);
+  ensureContextStub(out);
+  ensureWikiStub(out);
+  ensureRulesStub(out);
+  ensureProfileStub(out);
+  ensureBundleGitignore(out);
+  ensureMemoryIndex(path.join(out, theme[SRC_DIR_TOKENS.memory] ?? 'memory'));
+  ensureNotebookIndex(path.join(out, theme[SRC_DIR_TOKENS.notebook] ?? 'notebook'));
+  process.stdout.write(`[geneseed] built theme '${themeName}' -> ${out} (${items.length} files)\n`);
+}
+

package/js/{catalog.mjs → build/catalog.mjs}

@@ -23,11 +23,11 @@
  * NOTHING HERE PAINTS. No cursor moves, no clears, no alternate screen: this writes lines
  * and stops, exactly as `status` does. That is what keeps the dropped panel dropped.
  */
-import { helpWidth } from './cli.mjs';
-import { tuiInventory } from './inventory.mjs';
-import { defaultTheme, installedDefaults } from './installs.mjs';
-import { pyPrint } from './lib/fs.mjs';
-import { dwidth, fit, icon, truncd, tuiEntries } from './tui.mjs';
+import { helpWidth } from '../ui/cli.mjs';
+import { tuiInventory } from '../inspect/inventory.mjs';
+import { defaultTheme, installedDefaults } from '../hosts/installs.mjs';
+import { printOut } from '../lib/fs.mjs';
+import { dwidth, fit, icon, truncd, tuiEntries } from '../ui/tui.mjs';
 
 /**
  * The listing's section names, and the row kind each one selects.
@@ -129,9 +129,9 @@ export function cmdCatalog(args) {
   const lines = catalogLines(tuiInventory(theme, inst.doctrines), args.section,
     helpWidth() + 2, args.source);
   if (!lines.length) {
-    pyPrint(`[catalog] nothing to list${args.section ? ` under ${args.section}` : ''}.\n`);
+    printOut(`[catalog] nothing to list${args.section ? ` under ${args.section}` : ''}.\n`);
     return 1;
   }
-  for (const line of lines) pyPrint(`${line}\n`);
+  for (const line of lines) printOut(`${line}\n`);
   return 0;
 }