geneseed 3.1.3 → 3.3.0

package/bin/geneseed-cli.mjs

@@ -41,31 +41,22 @@
  * keeps the two tables from ever answering the same verb twice, since the shim bakes only one
  * of them.
  *
- * P6h MADE THE DISPATCH ASYNCHRONOUS and put `js/web/` on this entry's import graph. Both
- * are noted where they happen (`main`'s `await`, and the `web` row below); the consequence
- * 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.
+ * P6h MADE THE DISPATCH ASYNCHRONOUS and put `js/web/` on this entry's import graph — LAZILY,
+ * since the slim pass: every command module loads through its verb's thunk, so the graph is
+ * reached per verb rather than per invocation. The modules that spawn are still declared argv
+ * by argv in `ALLOWED_SPAWNS` (`tests/unit/hook_cli.test.mjs`), whose closure walk follows
+ * the dynamic spelling too.
  */
-import { cmdCatalog } from '../js/build/catalog.mjs';
+// THE FOUR EAGER IMPORTS ARE THE PARSER'S OWN, AND NOTHING ELSE LOADS BEFORE DISPATCH.
+// The twenty command modules used to be static imports, which made every invocation pay for
+// all of them: `geneseed status` loaded the web daemon, the TUI, the updater and the whole
+// build driver — 57 modules, ~1 MB, ~40-55 ms — before a byte of its own work. The verb
+// table below now holds one LOADER per row (`() => import(…).then(m => m.cmdX)`), so a verb
+// loads its slice of the tree and no other verb's. The spawn allow-list gate still sees the
+// whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
 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';
+import { printErr } from '../js/lib/fs.mjs';
 
 /**
  * The verbs this entry answers — and, since P10c, NOTHING ELSE ABOUT THEM.
@@ -83,56 +74,31 @@ import { cmdWeb } from '../js/web/server.mjs';
  * `tests/test_hook_cli_parity.py` scrapes `const VERBS = {` for its three matrix gates, and
  * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER, which `harness_golden` cells
  * assert verbatim — the order is the old table's and is not alphabetical.
+ *
+ * FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
+ * is now a thunk that imports the command's module and resolves to its function, so the one
+ * field a row holds is still the one thing a data file cannot — where the FUNCTION lives.
+ * `main` awaits `VERBS[verb]()` after the parse succeeds; the scraping regexes in
+ * `tests/unit/{cli_table,hook_cli,docs}.test.mjs` match on the KEY and the colon only; the
+ * literal string `const VERBS = {` and the key order neither changed.
  */
 const VERBS = {
-  exclude: {
-    fn: cmdExclude,
-  },
-  status: {
-    fn: cmdStatus,
-  },
-  version: {
-    fn: cmdVersion,
-  },
-  build: {
-    fn: cmdBuild,
-  },
-  prompt: {
-    fn: cmdPrompt,
-  },
-  theme: {
-    fn: cmdTheme,
-  },
-  diff: {
-    fn: cmdDiff,
-  },
-  'rebuild-all': {
-    fn: cmdRebuildAll,
-  },
-  migrate: {
-    fn: cmdMigrate,
-  },
-  doctor: {
-    fn: cmdDoctor,
-  },
-  uninstall: {
-    fn: cmdUninstall,
-  },
-  link: {
-    fn: cmdLink,
-  },
-  unlink: {
-    fn: cmdUnlink,
-  },
-  setup: {
-    fn: cmdSetup,
-  },
-  web: {
-    fn: cmdWeb,
-  },
-  upgrade: {
-    fn: cmdUpgrade,
-  },
+  exclude: () => import('../js/inspect/excludes.mjs').then((m) => m.cmdExclude),
+  status: () => import('../js/inspect/status.mjs').then((m) => m.cmdStatus),
+  version: () => import('../js/inspect/status.mjs').then((m) => m.cmdVersion),
+  build: () => import('../js/build/generate.mjs').then((m) => m.cmdBuild),
+  prompt: () => import('../js/build/generate.mjs').then((m) => m.cmdPrompt),
+  theme: () => import('../js/build/generate.mjs').then((m) => m.cmdTheme),
+  diff: () => import('../js/inspect/diff.mjs').then((m) => m.cmdDiff),
+  'rebuild-all': () => import('../js/build/generate.mjs').then((m) => m.cmdRebuildAll),
+  migrate: () => import('../js/maintain/migrate.mjs').then((m) => m.cmdMigrate),
+  doctor: () => import('../js/inspect/doctor.mjs').then((m) => m.cmdDoctor),
+  uninstall: () => import('../js/maintain/uninstall.mjs').then((m) => m.cmdUninstall),
+  link: () => import('../js/hosts/link.mjs').then((m) => m.cmdLink),
+  unlink: () => import('../js/hosts/link.mjs').then((m) => m.cmdUnlink),
+  setup: () => import('../js/maintain/setup.mjs').then((m) => m.cmdSetup),
+  web: () => import('../js/web/server.mjs').then((m) => m.cmdWeb),
+  upgrade: () => import('../js/maintain/update.mjs').then((m) => m.cmdUpgrade),
   // `up.add_parser(..., aliases=["update"])`, reproduced in P8c as a ROW OF ITS OWN rather than
   // as an `aliases` field on the row above — because a field would be a DECLARATION and the
   // three matrix gates read this table as the DISPATCH (rule 7, and M23 is where it was
@@ -144,28 +110,18 @@ const VERBS = {
   //
   // It is NOT what the web console's `update` ACTION needs: that row's argv names `upgrade`,
   // the subparser, and always did. The two were coupled only in a handoff's note.
-  update: {
-    fn: cmdUpgrade,
-  },
-  'sync-self': {
-    // 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/maintain/update.mjs`'s `syncSelf` for both halves.
-    fn: cmdSyncSelf,
-  },
-  bootstrap: {
-    fn: cmdBootstrap,
-  },
+  update: () => import('../js/maintain/update.mjs').then((m) => m.cmdUpgrade),
+  // 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/maintain/update.mjs`'s `syncSelf` for both halves.
+  'sync-self': () => import('../js/maintain/update.mjs').then((m) => m.cmdSyncSelf),
+  bootstrap: () => import('../js/maintain/update.mjs').then((m) => m.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/ui/menu.mjs`'s header
   // argues both.
-  menu: {
-    fn: cmdMenu,
-  },
-  home: {
-    fn: cmdHome,
-  },
+  menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
+  home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
   // 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;
@@ -173,9 +129,7 @@ const VERBS = {
   // 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.
-  tui: {
-    fn: cmdTui,
-  },
+  tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
   // THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
   // than by alphabet: every row above is the twin of a subparser, and these three are not.
   // The information behind them existed only behind the web console — the catalog endpoint,
@@ -190,21 +144,15 @@ const VERBS = {
   // ABSOLUTE — `tests/snapshot/cli_help.test.mjs` splits the two populations by name and refuses a
   // verb that falls into neither, and each has its own unit gate stating what it does rather
   // than that it agrees.
-  catalog: {
-    fn: cmdCatalog,
-  },
-  mcp: {
-    fn: cmdMcp,
-  },
-  memory: {
-    fn: cmdMemory,
-  },
+  catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
+  mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
+  memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
 };
 
 function die(code, msg) {
   // 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'}`);
+  // this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
+  printErr(`geneseed: error: ${msg}\n`);
   return code;
 }
 
@@ -351,6 +299,11 @@ async function main(argv) {
   // 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') {
+    // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
+    // generator driver in, and every OTHER verb was paying for it.
+    const [{ cmdValidate }, { parseDriverArgs }] = await Promise.all([
+      import('../js/inspect/validate.mjs'), import('./build-driver.mjs'),
+    ]);
     try {
       return cmdValidate(parseDriverArgs(argv.slice(1)));
     } catch (e) {
@@ -358,8 +311,8 @@ async function main(argv) {
       throw e;
     }
   }
-  const spec = VERBS[verb];
-  if (!spec) {
+  const load = VERBS[verb];
+  if (!load) {
     // "and every other harness subcommand is still Python — run the interpreter against the
     // old harness script" is GONE, and its removal is not cosmetic: with the four hook verbs
     // named, the two entry points now cover every subcommand there is, so the clause was not
@@ -395,7 +348,11 @@ async function main(argv) {
     // it `process.exitCode` would be assigned a PENDING PROMISE, which Node coerces to 0
     // and prints nothing about. `web status` would then report "not running" and exit 0.
     // Awaiting a number is a no-op for the ten synchronous verbs.
-    return await spec.fn(parsed.args);
+    //
+    // The load happens HERE, after the parse succeeded: a bad argument line refuses in a
+    // few milliseconds without touching the command's module tree, which is also why the
+    // parse errors above cannot depend on anything a loader would have brought in.
+    return await (await load())(parsed.args);
   } catch (e) {
     // `e.exitCode` is the generator's existing marker for a DELIBERATE refusal that has
     // already explained itself on stderr — `js/build/emit-claude.mjs` reads the same flag, and it is

package/bin/geneseed-hook.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * The hook entry point — a Node twin of `rituals/harness.py` for the four verbs the
- * emitted `settings.json` actually invokes.
+ * The hook entry point — a Node twin of `rituals/harness.py` for the verbs the emitted
+ * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Copilot).
  *
  * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
  * and each alone would be enough:
@@ -37,13 +37,20 @@
  * 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/hosts/hooks.mjs';
-import { printHelp } from '../js/ui/cli.mjs';
+import { cmdContext, cmdGitGate, cmdRuleGate, cmdToolGate, cmdLearn } from '../js/hosts/hooks.mjs';
+// Not a new module on the hot path: `js/hosts/hooks.mjs` above already imports
+// `js/lib/fs.mjs`, so this edge names a file the process has already loaded.
+import { printErr } from '../js/lib/fs.mjs';
 
+// `--host` selects the verdict dialect (see js/hosts/hooks.mjs's header); the emitter bakes
+// it into the command for every host that is not Claude Code, so the hook never has to guess
+// its reader from the payload's shape.
+const HOSTED = { '--root': 'root', '--host': 'host' };
 const VERBS = {
-  context: { fn: cmdContext, flags: { '--root': 'root' } },
-  'git-gate': { fn: cmdGitGate, flags: { '--root': 'root' } },
-  'rule-gate': { fn: cmdRuleGate, flags: { '--root': 'root' } },
+  context: { fn: cmdContext, flags: HOSTED },
+  'git-gate': { fn: cmdGitGate, flags: HOSTED },
+  'rule-gate': { fn: cmdRuleGate, flags: HOSTED },
+  'tool-gate': { fn: cmdToolGate, flags: HOSTED },
   learn: {
     fn: cmdLearn,
     flags: { '--memory': 'memory' },
@@ -54,18 +61,18 @@ const VERBS = {
 
 function die(code, msg) {
   // 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'}`);
+  // writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
+  printErr(`geneseed-hook: error: ${msg}\n`);
   return code;
 }
 
 /**
- * `argparse`'s surface for these four verbs, and only theirs: `--flag VALUE`, the
+ * `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
  * `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
  * positional.
  */
 function parse(spec, argv) {
-  const args = { root: null, memory: null, consolidate: false, file: null };
+  const args = { root: null, host: null, memory: null, consolidate: false, file: null };
   for (let i = 0; i < argv.length; i += 1) {
     const tok = argv[i];
     const eq = tok.indexOf('=');
@@ -89,7 +96,7 @@ function parse(spec, argv) {
   return { args };
 }
 
-function main(argv) {
+async function main(argv) {
   // `geneseed status | head` closes stdout early. Python exits quietly through
   // BrokenPipeError; the Node equivalent is an EPIPE that would otherwise be an unhandled
   // 'error' event and a stack trace on a hook path.
@@ -108,16 +115,19 @@ function main(argv) {
     // The COMMAND is not a table: `geneseed` is this package's `bin` entry for the CLI
     // (package.json), it answers every non-hook verb, and it survives the deletion of the
     // interpreter-plus-script invocation this line used to print.
-    return die(2, `invalid choice: '${verb}'. This entry point carries only the four HOOK `
+    return die(2, `invalid choice: '${verb}'. This entry point carries only the HOOK `
       + `verbs (${Object.keys(VERBS).join(', ')}); every other harness subcommand lives `
       + 'elsewhere — run `geneseed ' + verb + '`.');
   }
   // `<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/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.
+  // `js/ui/cli.mjs` is imported HERE, not at the top: a static import cost every tool call
+  // of every session a module parse (~3 ms of an ~12 ms controllable budget) for a branch
+  // only a human at a terminal ever takes. The hook path never awaits it, so `main` staying
+  // async-shaped costs the hot verbs nothing.
   if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
+    const { printHelp } = await import('../js/ui/cli.mjs');
     const rc = printHelp('geneseed-hook', verb);
     if (rc !== null) return rc;
   }
@@ -126,4 +136,4 @@ function main(argv) {
   return spec.fn(parsed.args);
 }
 
-process.exitCode = main(process.argv.slice(2));
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/docs/candidate-hosts.md

@@ -0,0 +1,74 @@
+# Candidate hosts — what Codex, Cursor and Gemini CLI actually offer
+
+*2026-09-05. Item 6 of the host-gap review. A docs check, not a design: each tool's
+own reference was read for the three surfaces Geneseed emits — an instructions
+carrier, skills, and hooks — so that "add host X" can be costed without re-reading
+the docs. Nothing here is implemented. Sources: the Codex CLI repo
+(`codex-rs/hooks`, `codex-rs/core/src/agents_md.rs`), `cursor.com/docs/{rules,skills,hooks}`,
+`geminicli.com/docs/{hooks,cli/gemini-md,cli/tutorials/skills-getting-started}`.*
+
+## The finding that changes the cost
+
+**`.agents/skills/` is a cross-tool convention.** Cursor loads skills from
+`.agents/skills/` and `~/.agents/skills/` (and, for compatibility, from `.claude/skills/`
+and `.codex/skills/`); Codex from `~/.codex/skills` (`$CODEX_HOME/skills`) and
+`.agents/skills`; Gemini CLI from `.gemini/skills` **or the `.agents/skills` alias**. One
+`skills/` emit into `.agents/` therefore reaches all three, byte-identical to what every
+current host gets. Skills are the largest surface by file count and they cost nothing new.
+
+## Per-host contracts
+
+| Surface | Codex CLI | Cursor | Gemini CLI |
+| --- | --- | --- | --- |
+| **Instructions** | `AGENTS.md` at the repo root (and nested), plus a global `~/.codex/AGENTS.md` that no size cap touches | `AGENTS.md` at the root and in subdirectories, combined; also `.cursor/rules/*.mdc` | `GEMINI.md` by default; `context.fileName` in `settings.json` accepts a list, e.g. `["AGENTS.md", "GEMINI.md"]` |
+| **Skills** | `~/.codex/skills`, `.agents/skills` — `SKILL.md` + frontmatter | `.cursor/skills`, `.agents/skills`, `~/.cursor/skills`, `~/.agents/skills`, plus `.claude/skills` and `.codex/skills` for compatibility | `.gemini/skills` or `.agents/skills`; `/skills list`, `/skills reload` |
+| **Hook config** | `hooks.json` in a config layer's folder, or a `[hooks]` table in `config.toml` (same schema, capitalised event names) | `.cursor/hooks.json` (project) and `~/.cursor/hooks.json` (user); plugins may ship `hooks/hooks.json` | `settings.json` `hooks` object (project `.gemini/`, user `~/.gemini/`) |
+| **Hook shape** | **Claude-shaped**: event → `[{matcher, hooks: [{type: "command", command, timeout}]}]`; 11 events incl. `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` | event → `[{command, matcher?}]`; events incl. `sessionStart`, `preToolUse`, `beforeShellExecution`, `beforeReadFile`, `afterFileEdit`, `stop`, `sessionEnd` | **Claude-shaped groups, Gemini names**: `SessionStart`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `PreCompact`, `SessionEnd`; matchers are regexes over tool names |
+| **Gate payload** | `tool_name` / `tool_input` (Claude's field names) | `tool_name` / `tool_input`, `cwd`, `tool_use_id` | `tool_name` / `tool_input`, `session_id`, `transcript_path`, `cwd`, `hook_event_name` |
+| **Gate verdict** | `hookSpecificOutput.permissionDecision`: **`allow` / `deny` / `ask`** — the ask tier exists | `permission: "allow" \| "deny"` + `user_message` / `agent_message`; **no ask** | `decision: "deny"` + `reason`, or exit code 2 with stderr as the reason; `systemMessage` shows the user a line; **no ask** |
+| **Context injection** | `SessionStart` → `additionalContext` (Claude form) | `sessionStart` → `additional_context` (snake_case) | `SessionStart` → `hookSpecificOutput.additionalContext`; plain stdout is not read |
+| **Learn point** | `Stop` / `SubagentStop` / `PreCompact`, transcript on stdin as on Claude | `stop` (payload not checked for a transcript path) | `AfterAgent` (turn end) and `PreCompact`; `transcript_path` is in the base schema |
+| **Tool names for matchers** | Claude's (`Bash`, `Write`, `Edit`) | `Shell`, `Read`, `Write`, MCP, `Task` (generic `preToolUse`) | `run_shell_command` (`command`), `write_file` (`file_path`, `content`), `replace` (`file_path`, `old_string`, `new_string`) |
+| **Subagents** | `SubagentStart`/`SubagentStop` exist; custom agents not checked | Plugins carry `agents/` | Local and remote subagents (`/agents list`, `enable`, `disable`) |
+
+## What each would cost, against what exists
+
+- **Codex CLI — cheapest, and the only one with an ask tier.** Its hook schema is
+  Claude's with `hooks.json`/`config.toml` as the carrier, its payload field names are
+  Claude's, and `permissionDecision: "ask"` exists. The Claude engine with `host: "codex"`
+  covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the four hook verbs
+  unchanged; the only new code is the carrier writer (a `hooks.json` merge or a TOML
+  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`). Roughly the Copilot
+  port minus the dialect work.
+
+- **Gemini CLI — Claude's groups, Gemini's names.** The hook groups are Claude's
+  `event → [{matcher, hooks}]` and the payload fields are Claude's, but the events are
+  `BeforeTool`/`AfterAgent` and the verdict is `decision: "deny"` or a `systemMessage`.
+  Bob Shell shares Gemini's *config* shape (`context.fileName`, `tools.allowed:
+  ["run_shell_command(git)"]`), but Bob's documented *hook* protocol is its own —
+  Claude's event names, refusal by exit code 2; see `adapters/bob/README.md` — so the two
+  are not one dialect. Instructions need one settings key (`context.fileName` to include
+  `AGENTS.md`) or a `GEMINI.md` carrier; skills go to `.agents/skills`. No ask tier: Laws
+  I/IV deny, the consent rules become a `systemMessage`.
+
+- **Cursor — a third verdict dialect.** `AGENTS.md` and `.agents/skills` are free; hooks
+  are `hooks.json` with a `{command}` list per event and a `permission: allow|deny`
+  verdict, `additional_context` in snake_case for `sessionStart`. Same block-or-warn stance
+  as Copilot, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
+  Cursor also reads `.claude/skills/`, so a Claude project install already gives a Cursor
+  user the skills.
+
+## Recommendation
+
+If a fifth host is wanted, Codex first: it reuses the most and it is the only candidate
+where the gates can *ask* rather than block. Before any of them, a `--emit agents` for
+the shared `.agents/skills/` folder would give Codex, Cursor and Gemini users the whole
+skill catalogue for the price of one directory name, with no host-specific code at all.
+A Gemini host would be the fourth verdict spelling in `js/hosts/hooks.mjs` (after Claude's
+ask, Copilot's block, Bob's exit code 2), plus a resolver and a carrier.
+
+## Not verified
+
+None of the three CLIs is installed on the reviewing machine. Every row above is from the
+tool's own documentation as indexed on 2026-09-05; the "learn point" column for Cursor and
+the Codex custom-agent surface were not checked further than noted.

package/docs/extending.md

@@ -215,11 +215,12 @@ a defect.
 
 Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions:
 
-- `--footprint` defaults to **lean**, and lean keeps only the heading plus the first sentence
-  (`terseBlocks` in `js/build/render.mjs`). A clause added to the second paragraph is invisible in the
-  default build. Amend the first sentence, or the amendment does not exist for most installs. The
-  same is true of a doctrine rule; it is **not** true of the ontology, which ships whole at both
-  footprints.
+- `--footprint` defaults to **lean**, and a law's lean text is the authored `LEAN:else` half of
+  its block in `src/laws/universal.md` (`resolveLean` in `js/build/render.mjs`). Amend **both**
+  halves, or the amendment does not exist for most installs. A doctrine rule is different: it is
+  still machine-cut to its heading plus first sentence (`terseBlocks`), so a clause in its second
+  paragraph is invisible in the default build. The on-disk `laws/` and `ontology/` copies always
+  render at full, whatever the footprint.
 
 ### 2c — Adding an INVARIANT
 

package/docs/token-footprint.md

@@ -4,10 +4,11 @@ What a deployed harness costs in context-window tokens, per host. Token counts a
 chars/4 estimates and shift a little with theme and version.
 
 **Treat every number below as a floor, not a reading.** They were measured on a
-`--footprint full` build of the neutral theme when the tree carried 41 skills and 17
-agents; it carries more skills than that now, and nothing re-measures this page
-automatically. For a live figure on your own install, ask the agent for the
-`token-report` skill — that is what it is for.
+`--footprint lean` build (the default) of the neutral theme when the tree carried
+47 skills and 17 agents, and nothing re-measures this page automatically. For a
+live figure on your own install, ask the agent for the `token-report` skill —
+that is what it is for. A `--footprint full` build runs roughly 5k tokens
+heavier on the root file.
 
 ## Always-on cost per session
 
@@ -15,40 +16,50 @@ The context every host injects at session start, before you type anything:
 
 | Component | Claude Code | OpenCode | Bob | Copilot |
 |---|---|---|---|---|
-| Root instruction file | ~10.7k (`CLAUDE.md`) | ~10.6k (`AGENT.md`) | ~10.7k (`AGENTS.md`) | ~10.7k (`AGENTS.md`) |
-| Skill metadata (name + description) | ~1.6k | ~1.6k | ~1.6k | ~1.6k |
-| Agent metadata | ~0.45k | ~0.55k | ~0.45k | ~0.45k |
+| Root instruction file | ~6.4k (`CLAUDE.md`) | ~6.4k (`AGENT.md`) | ~8.3k (`AGENTS.md`) | ~8.3k (`AGENTS.md`) |
+| Skill metadata (name + description) | ~1.7k | ~1.7k | ~1.7k | ~1.7k |
+| Agent metadata | ~0.5k | ~0.55k | ~0.5k | ~0.5k |
 | Eager memory/notebook injection | ~1.2k (SessionStart hook) | ~1.2k (context plugin) | ~1.2k (SessionStart hook) | — (no hooks; read on demand) |
-| **Total** | **~14k** | **~14k** | **~14k** | **~12.8k** |
+| **Total** | **~9.8k** | **~9.9k** | **~11.7k** | **~10.5k** |
 
-The emits are at parity by design: ~14k tokens, about 7% of a 200k
-window (Copilot runs slightly lighter because it has no hook mechanism — the
-memory/notebook indexes load when the agent reads them, not eagerly). The
+The emits are at parity by design: ~10–12k tokens, about 5–6% of a 200k
+window. Bob and Copilot carry the §3/§4 catalogue tables inline because their
+hosts expose no native skill/agent inventory; Claude Code and OpenCode ship a
+pointer to the host's own inventory instead, ~1.9k tokens lighter. Copilot also
+runs without eager injection — it has no hook mechanism, so the
+memory/notebook indexes load when the agent reads them, not eagerly. The
 eager-injection path is budget-capped identically everywhere
 (16 KB per file, 48 KB total ≈ 12k tokens ceiling), so growing Memory degrades
 every host the same way instead of one silently falling behind.
 
 ## Where the tokens go
 
-- **The root file is ~76% of the bill**, and the constitution inside it is the
+- **The root file is ~65% of the bill**, and the constitution inside it is the
   bulk of that — no longer one section but three: the Ontology, the nine Rules,
   and the doctrine packs this install built in. **Two** levers move it, not one.
-  The [footprint dial](#/docs/footprint) (`lean`, the default, keeps each Rule
-  and each doctrine rule as its heading plus first line, and ships the Ontology
-  *whole*; `full` inlines every rationale). And the
+  The [footprint dial](#/docs/footprint) (`lean`, the default, swaps each Rule,
+  the Ontology and the longest prose sections — the preamble, §6 Notebook, §8
+  Wiki — for their hand-written condensations, and cuts each doctrine rule to its
+  heading plus first line; `full` inlines every rationale). And the
   [doctrine packs](#/docs/setup-choices) — `geneseed-build --doctrines craft,rigor`
   drops whole blocks of §2 at build time, which removes far more than the
   footprint dial trims. Anything else is noise.
 
-  The three-tier split grew the root file: measured on `neutral`, `AGENT.md`
-  went from 31,457 bytes to 36,882 at `lean` (+17.2%) and 53,378 to 54,810 at
-  `full` (+2.7%). The lean growth is the larger one *by design* — the Ontology
-  is prose, and truncating four flowing sections to four orphan sentences would
-  have shipped a worldview nobody could read.
+  The lean condensations are authored, not generated. An earlier design shipped
+  the Ontology *whole* under `lean` on the grounds that truncating four flowing
+  sections to four orphan sentences would ship a worldview nobody could read —
+  the `LEAN:` blocks answer that by hand-writing the short form instead
+  (measured on `neutral`, the root file at `lean` went from 29,966 bytes to
+  25,614 with them).
 - **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
   heaviest (`react-view-transitions`, ~17.5k with its reference files) loads
   its references progressively.
+- **User-only skills leave the catalogue.** A skill whose source carries
+  `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
+  Code and Bob then drop its description from the always-on skill metadata and
+  only `/name` opens it. Seven skills carry it today (the five teaching drills,
+  `herdr`, `opencode-theme`), roughly a seventh of the ~1.7k skill-metadata line.
 - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
   never enters the context window.
 
@@ -73,7 +84,7 @@ token counter also includes, none of which Geneseed controls:
    per-repo install, a personal `~/.claude/CLAUDE.md`, or MCP servers each add
    their own share.
 
-So a ~34k session on a work repo is normal arithmetic: ~14k harness +
+So a ~30k session on a work repo is normal arithmetic: ~10k harness +
 ~10k repo docs + ~5–10k host overhead. Set `GENESEED_DEBUG=1` (OpenCode) to
 log exactly which files the context plugin injected, or run the SessionStart
 command by hand to see the hook's payload.

package/docs/web-ui.md

@@ -51,7 +51,7 @@ The left rail mirrors the harness's own shape:
 | Group | Views |
 | --- | --- |
 | *(ungrouped)* | Dashboard |
-| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Docs · Graph |
+| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Docs |
 | **🩺 Care** | Activity · Changes · Doctor |
 | **🎨 Setup** | Harness · Settings |
 
@@ -72,9 +72,10 @@ streams the output of background jobs and keeps their history across reloads.
 ### 🧬 Harness
 
 - **Dashboard** (`#/`) — a live readout of what's deployed. Three lenses: **Status**
-  (readiness ring, a KPI band, a genome grid, recent activity), **Lineage** (a mini
-  cross-link graph), and **Operator** (a searchable table of every deployed capability).
-  Headlines reflect the active theme's voice.
+  (readiness ring, a KPI band, a genome grid, recent activity), **Lineage** (the
+  source → render → deployed timeline and the genome-by-volume strand chart), and
+  **Operator** (a searchable table of every deployed capability). Headlines reflect the
+  active theme's voice.
 
   The KPI band reads **Agents · Skills · Invariants · Local edits**. That third tile is
   labelled *Invariants* and not *Constitution* on purpose: its value is the invariant count
@@ -107,15 +108,6 @@ streams the output of background jobs and keeps their history across reloads.
   **Promote to rule** control turns a recurring lesson into a trial rule in
   `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
   twice — landing you on the Rules page.
-- **Graph** (`#/graph`) — the cross-link constellation across agents, skills and the
-  **invariants only**: every `[[wikilink]]` between agents/skills, plus every `Rule N`
-  mention that lands on a real invariant. ⚠ The reference pattern matches the tier noun
-  followed by a **Roman numeral** — `Rule`, `Law`, or whatever the active theme calls one,
-  which is how `Dictate III` still resolves under `imperial`. A doctrine address is
-  `<pack> <n>` and matches nothing, so **doctrine cross-links are not drawn**; the graph is
-  a view of the invariant backbone, not of the whole constitution. Hover to isolate a
-  neighbourhood, scroll to zoom, drag to pan, search to highlight; orphans dim out. Click a
-  node to open its spec.
 
 ### 📚 Learn
 

package/harness.config.json

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

package/js/README.md

@@ -13,7 +13,7 @@ a module that does not exist, is a test failure. `geneseed doctor` reports the s
 
 ```
 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/geneseed-hook.mjs    the hook entry — 5 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
@@ -66,7 +66,7 @@ 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` |
+| `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Copilot), `learn`. `--host` picks the verdict dialect |
 | `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 |
@@ -168,13 +168,12 @@ the deployed harness as JSON.
 | `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.
+test call sites construct one directly and drive it without a socket. `routes.mjs`'s tables
+and inline lists are held against a surface list written out in
+`tests/unit/web_server.test.mjs` — growing or shrinking the API edits both, in one commit.
 
 ---
 
@@ -192,12 +191,3 @@ exported sets are deliberately EMPTY and must stay declared: each is half of a p
 | 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.