@geml/geml 1.8.2 → 1.8.4

package/codemap/verify.mjs

@@ -1,158 +1,158 @@
-#!/usr/bin/env node
-// geml-code-graph verify — the codemap's correctness oracle, two passes:
-//
-//   1. `geml check` over every .geml (document structure, id uniqueness,
-//      native references).
-//   2. The codemap-profile pass (docs/codemap-profile.md): CSV cells and meta
-//      values are opaque to the GEML standard BY DESIGN (the standard stays
-//      untouched), so edge integrity is checked here — the from/to columns of
-//      #calls / #called-by / #ref-by tables and every meta `entry` value must
-//      resolve (`#id` in the same document, `doc.geml#id` in a sibling).
-//      A renamed or deleted method therefore fails the build, not the reader.
-//
-//   geml codemap verify [dir] [--geml <path-to-geml.js|geml>]
-import { readdirSync, existsSync, readFileSync } from "node:fs";
-import { join, resolve, dirname, relative } from "node:path";
-import { posix } from "node:path";
-import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
-
-const args = process.argv.slice(2);
-const flagI = args.indexOf("--geml");
-if (args.includes("--help") || args.includes("-h")) {
-  console.error("usage: geml codemap verify [dir] [--geml <path>]   (dir defaults to ./.geml-code-graph)");
-  process.exit(2);
-}
-const dir = args.find((a, i) => !a.startsWith("-") && (flagI < 0 || i !== flagI + 1)) || ".geml-code-graph";
-const rootDir = resolve(dir);
-
-// Resolve the geml CLI (pass 1) and the parser API (pass 2).
-const localParser = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
-let cli = flagI >= 0 ? args[flagI + 1] : undefined;
-if (!cli) cli = existsSync(localParser) ? localParser : "geml";
-// win32 cmd.exe quoting (same rationale as build.mjs). q: space-aware quote for
-// the PROGRAM token — a bare launcher name (geml resolved via PATH) whose
-// .cmd/.bat shim uses %~dp0 breaks if the name is blanket-quoted. shq: ALWAYS
-// double-quote ARGUMENTS — Node does not escape args under shell:true, so a
-// `.geml` filename containing & | ( ) would otherwise break out and inject.
-// cmd.exe treats those metacharacters and whitespace as literal inside quotes;
-// CRT rules for embedded " / trailing \.
-// q quotes only when it must; WHEN it does it defers to shq, so a program path
-// ending in a backslash cannot escape our own closing quote and swallow the
-// next token. One set of CRT rules, in one place.
-const q = (s) => (/[\s"]/.test(String(s)) ? shq(s) : String(s));
-const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
-// A codemap document's `src=` routes are written relative to the indexed
-// SOURCE root (`geml-parser/src/attrs.ts` from a document two levels down), so
-// checking one has to be told that root — the same value `serve` derives, from
-// the recorded recipe, falling back to the parent of the graph directory.
-let srcRoot = resolve(rootDir, "..");
-try { srcRoot = resolve(rootDir, JSON.parse(readFileSync(join(rootDir, "_index", "refresh.json"), "utf8")).root ?? ".."); } catch { /* no recipe: parent */ }
-const checkArgs = (file) => ["check", "--root", srcRoot, file];
-const runCheck = (file) => {
-  // The built-parser path: run node on geml.js directly (array args, no shell).
-  if (cli.endsWith(".js")) return spawnSync(process.execPath, [cli, ...checkArgs(file)], { encoding: "utf8" });
-  // A non-.js cli may be a .cmd/.bat launcher (e.g. geml.cmd on PATH), which
-  // Node can only spawn through the shell. Hand cmd.exe ONE pre-escaped command
-  // string (never an args array — that is the unescaped, injection-prone path).
-  if (process.platform === "win32") {
-    return spawnSync([q(cli), ...checkArgs(file).map(shq)].join(" "), { encoding: "utf8", shell: true });
-  }
-  return spawnSync(cli, checkArgs(file), { encoding: "utf8" });
-};
-if (!existsSync(localParser)) {
-  console.error("verify: the profile pass needs the built parser (cd geml-parser && npm install && npm run build)");
-  process.exit(1);
-}
-const { parse } = await import(`file://${localParser.replace(/\\/g, "/")}`);
-
-const files = [];
-const walk = (d) => {
-  for (const e of readdirSync(d, { withFileTypes: true })) {
-    const p = join(d, e.name);
-    if (e.isDirectory()) walk(p);
-    else if (e.name.endsWith(".geml")) files.push(p);
-  }
-};
-walk(rootDir);
-files.sort();
-
-// ---- pass 1: geml check ----
-let failed = 0;
-for (const f of files) {
-  const r = runCheck(f);
-  if (r.status !== 0) {
-    failed++;
-    console.error(`FAIL ${f}`);
-    console.error((r.stderr || r.stdout || "").split("\n").slice(0, 4).map((l) => `  ${l}`).join("\n"));
-  }
-}
-
-// ---- pass 2: codemap profile references ----
-const REF_TABLES = new Set(["calls", "called-by", "ref-by"]);
-// Cross-stack link tables: `from`/`to` may be a #ref (resolved cross-tree
-// link — checked) OR plain `file:line` text (a call/route outside any indexed
-// function — tolerated, nothing to resolve).
-const LINK_TABLES = new Set(["api-calls", "api-served-by"]);
-const relDoc = (f) => relative(rootDir, f).replace(/\\/g, "/");
-const docs = new Map(); // relPath -> { ids:Set, blocks }
-const collectIds = (blocks, ids) => {
-  for (const b of blocks) {
-    if (b.id) ids.add(b.id);
-    if (b.children) collectIds(b.children, ids);
-    if (b.items) for (const it of b.items) if (it.children) collectIds(it.children, ids);
-  }
-};
-for (const f of files) {
-  const doc = parse(readFileSync(f, "utf8"));
-  const ids = new Set();
-  collectIds(doc.children, ids);
-  docs.set(relDoc(f), { ids, blocks: doc.children });
-}
-
-let refErrors = 0;
-const err = (doc, where, msg) => {
-  refErrors++;
-  console.error(`REF  ${doc} ${where}: ${msg}`);
-};
-const checkRef = (fromDoc, where, ref, lenient = false) => {
-  ref = String(ref).trim();
-  if (!ref) return lenient ? undefined : err(fromDoc, where, "empty reference cell");
-  const h = ref.indexOf("#");
-  if (h < 0) return lenient ? undefined : err(fromDoc, where, `not a reference: \`${ref}\``);
-  let targetDoc = fromDoc;
-  if (h > 0) targetDoc = posix.normalize(posix.join(posix.dirname(fromDoc), ref.slice(0, h)));
-  const id = ref.slice(h + 1);
-  const target = docs.get(targetDoc);
-  if (!target) return err(fromDoc, where, `cannot resolve document \`${ref.slice(0, h)}\``);
-  // reads/writes values may carry a plain-text `.member` suffix (ids never contain '.')
-  const bare = id.split(".")[0];
-  if (!target.ids.has(bare)) return err(fromDoc, where, `unresolved reference \`${ref}\``);
-};
-
-for (const [docPath, { blocks }] of docs) {
-  for (const b of blocks) {
-    if (b.kind !== "block") continue;
-    if (b.type === "table" && (REF_TABLES.has(b.id) || LINK_TABLES.has(b.id)) && b.table) {
-      const lenient = LINK_TABLES.has(b.id);
-      const fromCol = b.table.columns.indexOf("from");
-      const toCol = b.table.columns.indexOf("to");
-      if (fromCol < 0 || toCol < 0) { err(docPath, `#${b.id}`, "missing from/to columns"); continue; }
-      b.table.rows.forEach((row, i) => {
-        checkRef(docPath, `#${b.id} row ${i + 1} from`, row[fromCol]?.text ?? "", lenient);
-        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "", lenient);
-      });
-    }
-    if (b.type === "meta" && b.data?.entry) {
-      for (const ref of String(b.data.entry).split(/\s+/).filter(Boolean)) {
-        checkRef(docPath, "meta entry", ref);
-      }
-    }
-  }
-}
-
-console.error(
-  `verify: ${files.length - failed}/${files.length} documents pass geml check; `
-  + `profile references: ${refErrors === 0 ? "all resolve" : `${refErrors} dangling`}`,
-);
-process.exit(failed || refErrors ? 1 : 0);
+#!/usr/bin/env node
+// geml-code-graph verify — the codemap's correctness oracle, two passes:
+//
+//   1. `geml check` over every .geml (document structure, id uniqueness,
+//      native references).
+//   2. The codemap-profile pass (docs/codemap-profile.md): CSV cells and meta
+//      values are opaque to the GEML standard BY DESIGN (the standard stays
+//      untouched), so edge integrity is checked here — the from/to columns of
+//      #calls / #called-by / #ref-by tables and every meta `entry` value must
+//      resolve (`#id` in the same document, `doc.geml#id` in a sibling).
+//      A renamed or deleted method therefore fails the build, not the reader.
+//
+//   geml codemap verify [dir] [--geml <path-to-geml.js|geml>]
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname, relative } from "node:path";
+import { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+const flagI = args.indexOf("--geml");
+if (args.includes("--help") || args.includes("-h")) {
+  console.error("usage: geml codemap verify [dir] [--geml <path>]   (dir defaults to ./.geml-code-graph)");
+  process.exit(2);
+}
+const dir = args.find((a, i) => !a.startsWith("-") && (flagI < 0 || i !== flagI + 1)) || ".geml-code-graph";
+const rootDir = resolve(dir);
+
+// Resolve the geml CLI (pass 1) and the parser API (pass 2).
+const localParser = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
+let cli = flagI >= 0 ? args[flagI + 1] : undefined;
+if (!cli) cli = existsSync(localParser) ? localParser : "geml";
+// win32 cmd.exe quoting (same rationale as build.mjs). q: space-aware quote for
+// the PROGRAM token — a bare launcher name (geml resolved via PATH) whose
+// .cmd/.bat shim uses %~dp0 breaks if the name is blanket-quoted. shq: ALWAYS
+// double-quote ARGUMENTS — Node does not escape args under shell:true, so a
+// `.geml` filename containing & | ( ) would otherwise break out and inject.
+// cmd.exe treats those metacharacters and whitespace as literal inside quotes;
+// CRT rules for embedded " / trailing \.
+// q quotes only when it must; WHEN it does it defers to shq, so a program path
+// ending in a backslash cannot escape our own closing quote and swallow the
+// next token. One set of CRT rules, in one place.
+const q = (s) => (/[\s"]/.test(String(s)) ? shq(s) : String(s));
+const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+// A codemap document's `src=` routes are written relative to the indexed
+// SOURCE root (`geml-parser/src/attrs.ts` from a document two levels down), so
+// checking one has to be told that root — the same value `serve` derives, from
+// the recorded recipe, falling back to the parent of the graph directory.
+let srcRoot = resolve(rootDir, "..");
+try { srcRoot = resolve(rootDir, JSON.parse(readFileSync(join(rootDir, "_index", "refresh.json"), "utf8")).root ?? ".."); } catch { /* no recipe: parent */ }
+const checkArgs = (file) => ["check", "--root", srcRoot, file];
+const runCheck = (file) => {
+  // The built-parser path: run node on geml.js directly (array args, no shell).
+  if (cli.endsWith(".js")) return spawnSync(process.execPath, [cli, ...checkArgs(file)], { encoding: "utf8" });
+  // A non-.js cli may be a .cmd/.bat launcher (e.g. geml.cmd on PATH), which
+  // Node can only spawn through the shell. Hand cmd.exe ONE pre-escaped command
+  // string (never an args array — that is the unescaped, injection-prone path).
+  if (process.platform === "win32") {
+    return spawnSync([q(cli), ...checkArgs(file).map(shq)].join(" "), { encoding: "utf8", shell: true });
+  }
+  return spawnSync(cli, checkArgs(file), { encoding: "utf8" });
+};
+if (!existsSync(localParser)) {
+  console.error("verify: the profile pass needs the built parser (cd geml-parser && npm install && npm run build)");
+  process.exit(1);
+}
+const { parse } = await import(`file://${localParser.replace(/\\/g, "/")}`);
+
+const files = [];
+const walk = (d) => {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".geml")) files.push(p);
+  }
+};
+walk(rootDir);
+files.sort();
+
+// ---- pass 1: geml check ----
+let failed = 0;
+for (const f of files) {
+  const r = runCheck(f);
+  if (r.status !== 0) {
+    failed++;
+    console.error(`FAIL ${f}`);
+    console.error((r.stderr || r.stdout || "").split("\n").slice(0, 4).map((l) => `  ${l}`).join("\n"));
+  }
+}
+
+// ---- pass 2: codemap profile references ----
+const REF_TABLES = new Set(["calls", "called-by", "ref-by"]);
+// Cross-stack link tables: `from`/`to` may be a #ref (resolved cross-tree
+// link — checked) OR plain `file:line` text (a call/route outside any indexed
+// function — tolerated, nothing to resolve).
+const LINK_TABLES = new Set(["api-calls", "api-served-by"]);
+const relDoc = (f) => relative(rootDir, f).replace(/\\/g, "/");
+const docs = new Map(); // relPath -> { ids:Set, blocks }
+const collectIds = (blocks, ids) => {
+  for (const b of blocks) {
+    if (b.id) ids.add(b.id);
+    if (b.children) collectIds(b.children, ids);
+    if (b.items) for (const it of b.items) if (it.children) collectIds(it.children, ids);
+  }
+};
+for (const f of files) {
+  const doc = parse(readFileSync(f, "utf8"));
+  const ids = new Set();
+  collectIds(doc.children, ids);
+  docs.set(relDoc(f), { ids, blocks: doc.children });
+}
+
+let refErrors = 0;
+const err = (doc, where, msg) => {
+  refErrors++;
+  console.error(`REF  ${doc} ${where}: ${msg}`);
+};
+const checkRef = (fromDoc, where, ref, lenient = false) => {
+  ref = String(ref).trim();
+  if (!ref) return lenient ? undefined : err(fromDoc, where, "empty reference cell");
+  const h = ref.indexOf("#");
+  if (h < 0) return lenient ? undefined : err(fromDoc, where, `not a reference: \`${ref}\``);
+  let targetDoc = fromDoc;
+  if (h > 0) targetDoc = posix.normalize(posix.join(posix.dirname(fromDoc), ref.slice(0, h)));
+  const id = ref.slice(h + 1);
+  const target = docs.get(targetDoc);
+  if (!target) return err(fromDoc, where, `cannot resolve document \`${ref.slice(0, h)}\``);
+  // reads/writes values may carry a plain-text `.member` suffix (ids never contain '.')
+  const bare = id.split(".")[0];
+  if (!target.ids.has(bare)) return err(fromDoc, where, `unresolved reference \`${ref}\``);
+};
+
+for (const [docPath, { blocks }] of docs) {
+  for (const b of blocks) {
+    if (b.kind !== "block") continue;
+    if (b.type === "table" && (REF_TABLES.has(b.id) || LINK_TABLES.has(b.id)) && b.table) {
+      const lenient = LINK_TABLES.has(b.id);
+      const fromCol = b.table.columns.indexOf("from");
+      const toCol = b.table.columns.indexOf("to");
+      if (fromCol < 0 || toCol < 0) { err(docPath, `#${b.id}`, "missing from/to columns"); continue; }
+      b.table.rows.forEach((row, i) => {
+        checkRef(docPath, `#${b.id} row ${i + 1} from`, row[fromCol]?.text ?? "", lenient);
+        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "", lenient);
+      });
+    }
+    if (b.type === "meta" && b.data?.entry) {
+      for (const ref of String(b.data.entry).split(/\s+/).filter(Boolean)) {
+        checkRef(docPath, "meta entry", ref);
+      }
+    }
+  }
+}
+
+console.error(
+  `verify: ${files.length - failed}/${files.length} documents pass geml check; `
+  + `profile references: ${refErrors === 0 ? "all resolve" : `${refErrors} dangling`}`,
+);
+process.exit(failed || refErrors ? 1 : 0);

package/dist/cli.js

@@ -125,78 +125,78 @@ function embedSrcOf(source, unit) {
     const v = parseAttrs(braces[0]).attrs["src"];
     return typeof v === "string" ? v : undefined;
 }
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
-                                             (--root widens cross-doc resolution to dir d, as on check — an
-                                              === embed whose target sits above the file's own directory
-                                              needs it, or it renders unresolved)
-                                             --to  <output>: json | html | md | geml
-                                               --to md    -> Markdown (lossy)
-                                               --to html  -> self-contained HTML
-                                               --to html --fragment -> body-only markup, no page shell
-                                                            (embed in your own layout; assets via pageAssets)
-                                               --to geml  -> canonical re-format
-                                               --to json  -> document-model JSON (default)
-                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
-                                               geml notes.md                -> GEML   (md inferred from extension)
-                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
-                                               geml - --from md             read Markdown on stdin
-  geml list   <file.geml|-> [--json]                  list every addressable block: address, kind, lines
-                                             (call this first — its addresses are what every verb below takes)
-  geml find   <pattern> [<file|dir> …] [--json] [--case] [--head]   search block content -> file#address
-                                             (an address, not a line number, so a hit pastes into get/set;
-                                              a named file is searched whatever its extension, a dir walks
-                                              *.geml only; exit 1 when nothing matched)
-  geml get    <file.geml|-> [#id] [--json] [--head|--intro|--body]   with #id: print that block
-                                             (a heading id = its whole section; --head = head line;
-                                             --json = model node). Without #id: list all addressable
-                                             ids (--json = array). A selector may also be a POSITION,
-                                             'L27' or 'L27-58' — the smallest block containing those
-                                             lines, which is how a grep hit or a stack trace becomes
-                                             an address.
-  geml set    <file.geml|-> #id [--head|--intro|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
-  geml replace <file.geml|-> <old> <new> [--within <selector>] [-o f]   EXPERIMENTAL: swap a literal string, checked and reported
-                                             (--in F takes F's block #id, F#src takes #src, else stdin raw;
-                                              default = whole block · --head = head line · --body = body)
-  geml add    <file.geml|-> (--append | --before #id | --after #id) [--in f[#src]|-] [-o f]   insert a fragment
-                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
-  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
-                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
-  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
-  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
-                                             (sel: 0 | -N | id-prefix | changed; default -1)
-  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
-                                             (--root widens cross-doc refs to dir d, e.g. the repo root;
-                                              every read and write verb takes it. A write is REFUSED when
-                                              the result would not parse, so a document whose ../x.md
-                                              links only resolve from the repo root needs --root to be
-                                              editable at all — otherwise the guard reads its own blind
-                                              spot as breakage)
-  geml history <save|get|restore|verify> <file.geml> [...]   .gemlhistory version sidecar
-                                             (save = append the file as a revision · get = list revisions, or
-                                              print one · restore = overwrite the file with one · verify = rebuild
-                                              and re-hash the whole chain)
-  geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
-  geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
-                                             (11 tools, each geml_ + its CLI command path: list/find/get/check/history/to +
-                                              set/add/delete/rename/revert; every write is validated before it
-                                              reaches disk. A code graph under --root adds four read-only
-                                              geml_codemap_* tools to the same server)
-  geml skill  install [--dest <dir>] [--no-global] [--no-mcp]   set up GEML for Claude Code, user-global
-                                             (authoring skill -> ~/.claude/skills/geml, CLI -> npm i -g,
-                                              MCP server registered at user scope; touches no settings.json,
-                                              installs no hooks; idempotent — re-run to update)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Mutations (set/add/delete/rename) write the whole updated document in place for a
-file, or to stdout for '-' input; -o redirects it (-o - = stdout).
-Exit codes:
-  0 ok
-  1 document/operation error
-  2 command usage error.
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
+                                             (--root widens cross-doc resolution to dir d, as on check — an
+                                              === embed whose target sits above the file's own directory
+                                              needs it, or it renders unresolved)
+                                             --to  <output>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --to html --fragment -> body-only markup, no page shell
+                                                            (embed in your own layout; assets via pageAssets)
+                                               --to geml  -> canonical re-format
+                                               --to json  -> document-model JSON (default)
+                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
+                                               geml notes.md                -> GEML   (md inferred from extension)
+                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
+                                               geml - --from md             read Markdown on stdin
+  geml list   <file.geml|-> [--json]                  list every addressable block: address, kind, lines
+                                             (call this first — its addresses are what every verb below takes)
+  geml find   <pattern> [<file|dir> …] [--json] [--case] [--head]   search block content -> file#address
+                                             (an address, not a line number, so a hit pastes into get/set;
+                                              a named file is searched whatever its extension, a dir walks
+                                              *.geml only; exit 1 when nothing matched)
+  geml get    <file.geml|-> [#id] [--json] [--head|--intro|--body]   with #id: print that block
+                                             (a heading id = its whole section; --head = head line;
+                                             --json = model node). Without #id: list all addressable
+                                             ids (--json = array). A selector may also be a POSITION,
+                                             'L27' or 'L27-58' — the smallest block containing those
+                                             lines, which is how a grep hit or a stack trace becomes
+                                             an address.
+  geml set    <file.geml|-> #id [--head|--intro|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
+  geml replace <file.geml|-> <old> <new> [--within <selector>] [-o f]   EXPERIMENTAL: swap a literal string, checked and reported
+                                             (--in F takes F's block #id, F#src takes #src, else stdin raw;
+                                              default = whole block · --head = head line · --body = body)
+  geml add    <file.geml|-> (--append | --before #id | --after #id) [--in f[#src]|-] [-o f]   insert a fragment
+                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
+  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
+                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
+  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
+  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
+                                             (sel: 0 | -N | id-prefix | changed; default -1)
+  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
+                                             (--root widens cross-doc refs to dir d, e.g. the repo root;
+                                              every read and write verb takes it. A write is REFUSED when
+                                              the result would not parse, so a document whose ../x.md
+                                              links only resolve from the repo root needs --root to be
+                                              editable at all — otherwise the guard reads its own blind
+                                              spot as breakage)
+  geml history <save|get|restore|verify> <file.geml> [...]   .gemlhistory version sidecar
+                                             (save = append the file as a revision · get = list revisions, or
+                                              print one · restore = overwrite the file with one · verify = rebuild
+                                              and re-hash the whole chain)
+  geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
+  geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
+                                             (11 tools, each geml_ + its CLI command path: list/find/get/check/history/to +
+                                              set/add/delete/rename/revert; every write is validated before it
+                                              reaches disk. A code graph under --root adds four read-only
+                                              geml_codemap_* tools to the same server)
+  geml skill  install [--dest <dir>] [--no-global] [--no-mcp]   set up GEML for Claude Code, user-global
+                                             (authoring skill -> ~/.claude/skills/geml, CLI -> npm i -g,
+                                              MCP server registered at user scope; touches no settings.json,
+                                              installs no hooks; idempotent — re-run to update)
+  geml --help | --version [--json]
+
+Use '-' as the file to read from stdin.
+Mutations (set/add/delete/rename) write the whole updated document in place for a
+file, or to stdout for '-' input; -o redirects it (-o - = stdout).
+Exit codes:
+  0 ok
+  1 document/operation error
+  2 command usage error.
 `;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
@@ -211,65 +211,65 @@ const SUBHELP = {
     replace: "usage: geml replace <file.geml|-> <old> <new> [--within <selector>] [-o out.geml] [--root d]  (EXPERIMENTAL — this verb MAY BE WITHDRAWN in a later release; it is here to find out whether an addressed, checked replacement earns its place beside `sed`, and if it does not, it goes. Build nothing on it you cannot change, and say so in a discussion if it is doing real work for you. Swaps a LITERAL string — never a pattern, that is what `sed` is for and where the footguns are. Without --within the whole document; with it, only inside the blocks that selector matches, and unlike `set` it may match several: `--within '=== table'` means every table. What this buys over `sed -i`, at the same cost of two short strings and nothing read: the result is re-parsed and refused if it would break the document, the blocks it touched are NAMED on stderr, and the write lands in .gemlhistory where `revert` can undo it. An id is not text — a replacement that would rename one is refused and points at `geml rename`, which fixes every reference too. Exit 1 when nothing matched, so `if geml replace …` works in a script)",
     check: "usage: geml check <file.geml|-> [--root <dir>] [--json]  (--root: resolve cross-doc refs within <dir> instead of the file's own directory)",
     revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out] [--root d]  (reconcile #id to a revision: splice / resurrect / remove; sel: 0 | -N | id-prefix | changed; default -1)",
-    history: `usage: geml history save    <file.geml> [-m <msg>]      append the working file as a new revision (identical to the tip = no-op)
-       geml history get     <file.geml> [<rev>] [--json]   NO <rev>: every revision, newest first, first column = the selector; WITH <rev>: that revision's full text
-       geml history restore <file.geml> <rev> [--force]    overwrite the working file with a revision (--force discards unsaved changes)
-       geml history verify  <file.geml>                    rebuild and re-hash every revision in the chain
-       (<rev>: 0 = the tip | -N = N revisions back | an unambiguous revision id — the strings 'get' prints.
+    history: `usage: geml history save    <file.geml> [-m <msg>]      append the working file as a new revision (identical to the tip = no-op)
+       geml history get     <file.geml> [<rev>] [--json]   NO <rev>: every revision, newest first, first column = the selector; WITH <rev>: that revision's full text
+       geml history restore <file.geml> <rev> [--force]    overwrite the working file with a revision (--force discards unsaved changes)
+       geml history verify  <file.geml>                    rebuild and re-hash every revision in the chain
+       (<rev>: 0 = the tip | -N = N revisions back | an unambiguous revision id — the strings 'get' prints.
         All four take --history <path> to point at a sidecar other than <file>.gemlhistory.)`,
-    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
-       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
-       geml codemap verify [dir]                 geml check + profile reference checks
-       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
-       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
-       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
-       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
+    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
+       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
+       geml codemap verify [dir]                 geml check + profile reference checks
+       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
+       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
+       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
+       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
-    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
-
-  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
-  Every tool is geml_ + its CLI COMMAND PATH, so the terminal and the assistant
-  share one vocabulary — geml_history mirrors the "geml history" command group,
-  whose read verb (get) is the only one of the four served here.
-  Eleven tools: geml_list · geml_find · geml_get · geml_check · geml_history
-                geml_to · geml_set · geml_add · geml_delete · geml_rename
-                geml_revert
-  With a code graph under --root, four more (read-only), so one client entry
-  covers both: geml_codemap_search · geml_codemap_callchain
-               geml_codemap_list · geml_codemap_node
-
-  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
-                      client names is confined here; a client cannot widen it.
-  --graph <dir>       Code-graph directory, inside --root. Defaults to
-                      <root>/.geml-code-graph when it holds an index.geml; with
-                      no graph the four graph tools are not served at all.
-  --no-history        Skip the .gemlhistory revision saved before each write
-                      (default: save one, so geml_revert always has a revision
-                      to undo to).
-
-  Register with a client:
+    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Every tool is geml_ + its CLI COMMAND PATH, so the terminal and the assistant
+  share one vocabulary — geml_history mirrors the "geml history" command group,
+  whose read verb (get) is the only one of the four served here.
+  Eleven tools: geml_list · geml_find · geml_get · geml_check · geml_history
+                geml_to · geml_set · geml_add · geml_delete · geml_rename
+                geml_revert
+  With a code graph under --root, four more (read-only), so one client entry
+  covers both: geml_codemap_search · geml_codemap_callchain
+               geml_codemap_list · geml_codemap_node
+
+  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
+                      client names is confined here; a client cannot widen it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when it holds an index.geml; with
+                      no graph the four graph tools are not served at all.
+  --no-history        Skip the .gemlhistory revision saved before each write
+                      (default: save one, so geml_revert always has a revision
+                      to undo to).
+
+  Register with a client:
     claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
-    skill: `usage: geml skill install [--dest <skillsDir>] [--no-global] [--no-mcp] [--dry-run]
-
-  One command, three things, all user-global — so any Claude Code session can
-  author, validate, and blockwise-edit GEML:
-    1. the authoring skill -> <skillsDir>/geml   (default ~/.claude/skills/geml)
-    2. the geml CLI        -> npm i -g @geml/geml@<this version>   (skipped when PATH already has it)
-    3. the MCP server      -> claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .
-  Touches no settings.json and installs no hooks. Idempotent — and it is the
-  whole upgrade: a re-run refreshes the skill text AND brings the global CLI to
-  the version that text documents, so "npx -y @geml/geml skill install" is one
-  step, not two.
-
-  --dest <dir>   install the skill under <dir> instead of ~/.claude/skills
-  --no-global    leave the global CLI alone — no install, no version change
-  --no-mcp       skip the MCP server registration
-  --dry-run      report what would be written, change nothing
-
-  Other agent tools are installed by DETECTION: a tool's own context file gets
-  the skill text inside a marker pair (refreshed on a re-run, nothing else in
-  the file touched) when its directory is already there — ~/.gemini, ~/.qwen,
-  and an AGENTS.md in the current project. A tool that is not installed is
+    skill: `usage: geml skill install [--dest <skillsDir>] [--no-global] [--no-mcp] [--dry-run]
+
+  One command, three things, all user-global — so any Claude Code session can
+  author, validate, and blockwise-edit GEML:
+    1. the authoring skill -> <skillsDir>/geml   (default ~/.claude/skills/geml)
+    2. the geml CLI        -> npm i -g @geml/geml@<this version>   (skipped when PATH already has it)
+    3. the MCP server      -> claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .
+  Touches no settings.json and installs no hooks. Idempotent — and it is the
+  whole upgrade: a re-run refreshes the skill text AND brings the global CLI to
+  the version that text documents, so "npx -y @geml/geml skill install" is one
+  step, not two.
+
+  --dest <dir>   install the skill under <dir> instead of ~/.claude/skills
+  --no-global    leave the global CLI alone — no install, no version change
+  --no-mcp       skip the MCP server registration
+  --dry-run      report what would be written, change nothing
+
+  Other agent tools are installed by DETECTION: a tool's own context file gets
+  the skill text inside a marker pair (refreshed on a re-run, nothing else in
+  the file touched) when its directory is already there — ~/.gemini, ~/.qwen,
+  and an AGENTS.md in the current project. A tool that is not installed is
   skipped and named; no tool directory is ever created for you.`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
@@ -2292,7 +2292,7 @@ function runCodemap(args) {
     // `unknown codemap subcommand`: this string is what an operator sees in a
     // client's server log when the entry they registered stops starting.
     if (sub === "mcp") {
-        fail("geml codemap mcp was removed: use `geml mcp --root <dir>`, which serves the three code-graph tools alongside the document tools (graph: <root>/.geml-code-graph, or --graph <dir>).");
+        fail("geml codemap mcp was removed: use `geml mcp --root <dir>`, which serves the four code-graph tools alongside the document tools (graph: <root>/.geml-code-graph, or --graph <dir>).");
     }
     const script = scripts[sub];
     if (!script)