@geml/geml 1.3.2 → 1.4.3

package/dist/geml.js

@@ -5,15 +5,18 @@
 // `meta` data block, ATX headings, lists and paragraphs, the attribute object
 // with §4 value typing, and a document-model JSON serialization.
 //
-// M2: inline parsing of flow blocks (§5 — emphasis/strong/strike, code, math,
-// media embeds, links, auto-references, footnotes) and build-time reference
-// validation (§8 — unique ids, resolvable internal/cross-document references).
-import { readFileSync, writeFileSync, realpathSync, statSync } from "node:fs";
+// M2: inline parsing of unfenced blocks (§5 — emphasis/strong/strike, code,
+// math, media embeds, links, auto-references, footnotes) and build-time
+// reference validation (§8 — unique ids, resolvable internal/cross-document
+// references).
+import { readFileSync, writeFileSync, realpathSync, statSync, existsSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { commit, restore, verify, listRevisions, resolveContent, firstChangedContent } from "./history.js";
 import { renderHtml } from "./render-html.js";
+import { normalizeBlockId } from "./block-edit.js";
+import { normalizeSource } from "./diagnostics.js";
 import { coerce, parseAttrs } from "./attrs.js";
 import { META_REF_SRC, parseInline } from "./inline.js";
 import { parseTable } from "./table.js";
@@ -25,6 +28,17 @@ export { mdToGeml } from "./from-md.js";
 export { renderHtml } from "./render-html.js";
 export { serialize } from "./serialize.js";
 export { gemlToMd } from "./to-md.js";
+// A block id is any non-whitespace run (§4), so it may contain regex
+// metacharacters. Every place that builds a RegExp from an id MUST run it
+// through this first, or a crafted id (`#a(`, `#(x+x+)+y`) turns a labeled-close
+// or reference match into an uncaught `SyntaxError` or a ReDoS on the main
+// parse path (SEC: document-controlled RegExp injection).
+function reLit(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// Re-exported from ./diagnostics.js so that `Diagnostic` stays importable from
+// the package root. The catalogue of codes lives there (spec Appendix A).
+export { SEVERITY } from "./diagnostics.js";
 // Type registry: which body mode each typed block uses. Unknown types are a
 // warning and fall back to `raw` (forward compatibility, §3/§8).
 const REGISTRY = {
@@ -118,7 +132,7 @@ function interpolate(text, line, ctx) {
                 if (ctx.meta.has(key))
                     out += ctx.meta.get(key);
                 else {
-                    ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
+                    ctx.diags.push({ severity: "error", code: "unknown-metadata-reference", message: `unknown metadata reference \`{{${key}}}\``, line });
                     out += m[0];
                 }
                 i = META_REF.lastIndex;
@@ -133,7 +147,7 @@ function interpolate(text, line, ctx) {
 // Register a block id, flagging duplicates as errors (§4: ids unique per doc).
 function registerId(ctx, id, line) {
     if (ctx.ids.has(id)) {
-        ctx.diags.push({ severity: "error", message: `duplicate id \`#${id}\` (first defined at line ${ctx.ids.get(id)})`, line });
+        ctx.diags.push({ severity: "error", code: "duplicate-id", message: `duplicate id \`#${id}\` (first defined at line ${ctx.ids.get(id)})`, line });
     }
     else {
         ctx.ids.set(id, line);
@@ -203,7 +217,7 @@ function parseList(lines, i, base, ctx) {
                 // rather than building a model that overflows the renderer (DoS). One
                 // diagnostic per over-deep list; content is preserved, just flattened.
                 if (!tooDeep) {
-                    ctx.diags.push({ severity: "error", message: `list nesting too deep (max ${MAX_NESTING})`, line: base + i + 1 });
+                    ctx.diags.push({ severity: "error", code: "list-nesting-too-deep", message: `list nesting too deep (max ${MAX_NESTING})`, line: base + i + 1 });
                     tooDeep = true;
                 }
                 cur = top.list;
@@ -276,7 +290,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             // of any length ≥ 3 followed by the block's id). The labeled close is a
             // *local* close: it can't be gotten wrong by miscounting `=`, so it is the
             // safe way to nest (§3).
-            const labeled = attrs.id !== undefined ? new RegExp(`^={3,}[ \\t]+#${attrs.id}[ \\t]*$`) : null;
+            const labeled = attrs.id !== undefined ? new RegExp(`^={3,}[ \\t]+#${reLit(attrs.id)}[ \\t]*$`) : null;
             const body = [];
             let j = i + 1;
             let closed = false;
@@ -289,11 +303,11 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             }
             if (!closed) {
                 const how = attrs.id !== undefined ? `${"=".repeat(openLen)} or \`=== #${attrs.id}\`` : "=".repeat(openLen);
-                diags.push({ severity: "error", message: `unterminated \`${type}\` block (no matching ${how})`, line: openLineNo });
+                diags.push({ severity: "error", code: "unterminated-block", message: `unterminated \`${type}\` block (no matching ${how})`, line: openLineNo });
             }
             let mode = REGISTRY[type];
             if (mode === undefined) {
-                diags.push({ severity: "warning", message: `unknown block type \`${type}\`; body kept as raw`, line: openLineNo });
+                diags.push({ severity: "warning", code: "unknown-block-type", message: `unknown block type \`${type}\`; body kept as raw`, line: openLineNo });
                 mode = "raw";
             }
             const block = {
@@ -317,7 +331,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                     // Refuse to recurse past the cap: emit a diagnostic and keep the body
                     // as raw so the parser returns cleanly instead of overflowing the
                     // call stack on a pathologically nested document (DoS).
-                    diags.push({ severity: "error", message: `block nesting too deep (max ${MAX_NESTING}); body kept as raw`, line: openLineNo });
+                    diags.push({ severity: "error", code: "block-nesting-too-deep", message: `block nesting too deep (max ${MAX_NESTING}); body kept as raw`, line: openLineNo });
                     block.raw = body;
                 }
                 else {
@@ -347,7 +361,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                         // §7: native chart — resolved in a second pass (data=#id may be
                         // defined later in the document).
                         if (body.length > 0 && body.some((l) => l.trim() !== "")) {
-                            diags.push({ severity: "warning", message: "geml-chart body is ignored; the chart spec lives in attributes", line: openLineNo });
+                            diags.push({ severity: "warning", code: "ignored-diagram-body", message: "geml-chart body is ignored; the chart spec lives in attributes", line: openLineNo });
                         }
                         (ctx.charts ??= []).push({ block, line: openLineNo });
                     }
@@ -357,18 +371,18 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                         // ("view config travels with the data"). Body is empty.
                         const src = attrs.attrs["src"];
                         if (typeof src !== "string" || src === "") {
-                            diags.push({ severity: "warning", message: "geml-code-graph: missing `src=` (nothing to render)", line: openLineNo });
+                            diags.push({ severity: "warning", code: "code-graph-missing-src", message: "geml-code-graph: missing `src=` (nothing to render)", line: openLineNo });
                         }
                         else if (ctx.resolveDoc && ctx.resolveDoc(src) === null) {
-                            diags.push({ severity: "warning", message: `geml-code-graph: cannot resolve document \`${src}\``, line: openLineNo });
+                            diags.push({ severity: "warning", code: "code-graph-unresolvable-document", message: `geml-code-graph: cannot resolve document \`${src}\``, line: openLineNo });
                         }
                         if (body.length > 0 && body.some((l) => l.trim() !== "")) {
-                            diags.push({ severity: "warning", message: "geml-code-graph body is ignored; the embed is configured by `src=` alone", line: openLineNo });
+                            diags.push({ severity: "warning", code: "ignored-diagram-body", message: "geml-code-graph body is ignored; the embed is configured by `src=` alone", line: openLineNo });
                         }
                     }
                     else if (typeof fmt === "string" && !DIAGRAM_RENDERERS.has(fmt)) {
                         // §7: warn on a diagram format with no registered renderer.
-                        diags.push({ severity: "warning", message: `no registered renderer for diagram format \`${fmt}\`; body kept raw`, line: openLineNo });
+                        diags.push({ severity: "warning", code: "unknown-diagram-format", message: `no registered renderer for diagram format \`${fmt}\`; body kept raw`, line: openLineNo });
                     }
                 }
             }
@@ -436,7 +450,7 @@ function parseData(lines) {
 // resolving `other.geml#id` references.
 function gatherIds(source) {
     const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
-    scanBlocks(source.replace(/\r\n?/g, "\n").split("\n"), 0, ctx);
+    scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
     return new Set(ctx.ids.keys());
 }
 // Pre-scan for `=== meta` blocks (at any fence depth) and merge their
@@ -468,14 +482,14 @@ function validateRefs(ctx, opts) {
             if (!ref.doc)
                 continue;
             if (!opts.resolveDoc) {
-                ctx.diags.push({ severity: "warning", message: `cross-document reference \`${ref.doc}${ref.anchor ? "#" + ref.anchor : ""}\` not checked (no document resolver)`, line: ref.line });
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `cross-document reference \`${ref.doc}${ref.anchor ? "#" + ref.anchor : ""}\` not checked (no document resolver)`, line: ref.line });
                 continue;
             }
             let ids = docIds.get(ref.doc);
             if (ids === undefined) {
                 const src = opts.resolveDoc(ref.doc);
                 if (src === null) {
-                    ctx.diags.push({ severity: "error", message: `cannot resolve document \`${ref.doc}\``, line: ref.line });
+                    ctx.diags.push({ severity: "error", code: "unresolvable-document", message: `cannot resolve document \`${ref.doc}\``, line: ref.line });
                     docIds.set(ref.doc, new Set());
                     continue;
                 }
@@ -483,14 +497,16 @@ function validateRefs(ctx, opts) {
                 docIds.set(ref.doc, ids);
             }
             if (ref.anchor !== undefined && !ids.has(ref.anchor)) {
-                ctx.diags.push({ severity: "error", message: `unresolved reference \`${ref.doc}#${ref.anchor}\``, line: ref.line });
+                ctx.diags.push({ severity: "error", code: "unresolved-cross-document-reference", message: `unresolved reference \`${ref.doc}#${ref.anchor}\``, line: ref.line });
             }
             continue;
         }
         // internal, autoref, footnote — anchor must be a known id in this document.
         if (ref.anchor !== undefined && !ctx.ids.has(ref.anchor)) {
-            const what = ref.kind === "footnote" ? `footnote \`[^${ref.anchor}]\`` : `reference \`#${ref.anchor}\``;
-            ctx.diags.push({ severity: "error", message: `unresolved ${what}`, line: ref.line });
+            const footnote = ref.kind === "footnote";
+            const what = footnote ? `footnote \`[^${ref.anchor}]\`` : `reference \`#${ref.anchor}\``;
+            const code = footnote ? "unresolved-footnote" : "unresolved-reference";
+            ctx.diags.push({ severity: "error", code, message: `unresolved ${what}`, line: ref.line });
         }
     }
 }
@@ -501,13 +517,15 @@ function resolveCharts(ctx) {
         const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"] : "";
         const id = ref.replace(/^#/, "");
         if (id === "") {
-            ctx.diags.push({ severity: "error", message: "geml-chart: missing `data=#id`", line });
+            ctx.diags.push({ severity: "error", code: "chart-missing-data", message: "geml-chart: missing `data=#id`", line });
             continue;
         }
         const table = ctx.tables?.get(id);
         if (!table) {
-            const what = ctx.ids.has(id) ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
-            ctx.diags.push({ severity: "error", message: `geml-chart: ${what}`, line });
+            const known = ctx.ids.has(id);
+            const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
+            const code = known ? "chart-data-not-a-table" : "unresolved-reference";
+            ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
             continue;
         }
         if (table.src !== undefined) {
@@ -524,7 +542,7 @@ function resolveCharts(ctx) {
     }
 }
 export function parse(source, opts = {}) {
-    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const lines = normalizeSource(source).split("\n");
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
     resolveCharts(ctx);
@@ -548,7 +566,7 @@ function idOfHeading(braces, text, line, ctx) {
 function fenceClose(lines, i, open) {
     const openLen = open[1].length;
     const id = open[3] ? parseAttrs(open[3]).id : undefined;
-    const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${id}[ \\t]*$`) : null;
+    const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${reLit(id)}[ \\t]*$`) : null;
     for (let j = i + 1; j < lines.length; j++) {
         if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j])))
             return { end: j + 1, closed: true };
@@ -635,7 +653,7 @@ function collectSpans(lines, base, out, ctx, depth = 0) {
 // with the physical lines produced by splitLines(source).
 export function blockSpans(source) {
     const out = new Map();
-    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const lines = normalizeSource(source).split("\n");
     // Inert context: heading auto-ids slug the interpolated text (parser parity);
     // its diagnostics are discarded — the span scan never reports.
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
@@ -719,52 +737,86 @@ function parseStamp(s) {
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
 const VERSION = "1.0"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.3.2"; // reference implementation; keep in sync with package.json
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|->                         parse -> document-model JSON (stdout)
-  geml get <file.geml|-> #id [--json][--head]  print ONE block by id (a heading id = its section;
-                                             --head narrows any id to its head line; --json = model node)
-  geml set <file.geml|-> #id [--from f][-o f][--head] replace ONE block by id (new content: --from/stdin)
-  geml revert <file.geml> #id [--to <sel>][--head] restore ONE block to a past revision (sel: -N|latest|id)
-  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)
-  geml render <file.geml|-> [-o out.html]    render to one self-contained HTML file
-  geml fmt <file.geml|-> [-o out.geml]       re-serialize to canonical GEML
-  geml convert <file.md|-> [-o out.geml]     Markdown -> GEML
-  geml export <file.geml|-> [-o out.md]      GEML -> Markdown (lossy)
-  geml history <commit|verify|show|restore|log> <file.geml> [...]
-  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Exit codes: 
-  0 ok
-  1 document/operation error
-  2 command usage error.
+const PARSER_VERSION = "1.4.3"; // reference implementation; keep in sync with package.json
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [-o out]   transform a document (default: --to json)
+                                             --to  <output>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --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 get    <file.geml|-> [#id] [--json] [--head]   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).
+  geml set    <file.geml|-> #id [--head|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
+                                             (--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)
+  geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
+  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
+  geml mcp    --workspace <dir> [--no-history]   serve document CRUD over MCP (stdio)
+                                             (9 tools: list/read/check/history + write/add/delete/rename/revert;
+                                              every write is validated before it reaches disk)
+  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.
 const SUBHELP = {
-    get: "usage: geml get <file.geml|-> #id [--json] [--head]  (a heading id = its whole section; --head narrows any id to its head line)",
-    set: "usage: geml set <file.geml|-> #id [--from FILE] [-o out.geml] [--head]",
+    get: "usage: geml get <file.geml|-> [#id] [--json] [--head]  (with #id: that block, a heading id = its whole section, --head = its head line; without #id: list every addressable id, --json = array)",
+    set: "usage: geml set <file.geml|-> #id [--head|--body] [--in F | --in F#src | --in -] [-o out.geml]  (content: --in F takes F's block #id, --in F#src takes #src, else stdin raw; default = whole block, --head = head line — both normalize the id to #id — --body = body; guarded splice, refused if it breaks the doc)",
+    add: "usage: geml add <file.geml|-> (--append | --before #id | --after #id) [--in F | --in F#src | --in -] [-o out.geml]  (insert a GEML fragment — 1+ blocks and/or prose — at a position; --in F takes all of F, --in F#src takes #src, else stdin raw; content keeps its own ids, a collision is refused)",
+    delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml]  (remove one or more blocks; a missing id is skipped with a note, not an error; a reference left dangling is a warning, not a refusal — delete never fails on a live reference)",
+    rename: "usage: geml rename <file.geml|-> #old #new [-o out.geml]  (rewrite an id's declaration AND every reference — [[#id]], [text](#id), chart data=#id, footnote [^id] — id-boundary safe, skipping raw block bodies; #new must be free; refused if it breaks the doc)",
     check: "usage: geml check <file.geml|-> [--root <dir>] [--json]  (--root: resolve cross-doc refs within <dir> instead of the file's own directory)",
-    render: "usage: geml render <file.geml|-> [-o out.html]",
-    convert: "usage: geml convert <file.md|-> [-o out.geml]",
-    export: "usage: geml export <file.geml|-> [-o out.md]",
-    fmt: "usage: geml fmt <file.geml|-> [-o out.geml]",
-    revert: "usage: geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out] [--head]  (sel: -N | latest | id-prefix; default -1)",
+    revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out]  (reconcile #id to a revision: splice / resurrect / remove; sel: 0 | -N | id-prefix | changed; default -1)",
     history: "usage: geml history <commit|verify|show|restore|log> <file.geml> [...]",
-    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)
-       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
+    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)
+       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
        (<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 --workspace <dir> [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Nine tools: geml_list_ids · geml_read_block · geml_check · geml_history_log
+              geml_write_block · geml_add_block · geml_delete_block
+              geml_rename_id · geml_revert_block
+
+  --workspace <dir>   REQUIRED. Root holding the .geml documents. Every path a
+                      client names is confined here; a client cannot widen it.
+  --no-history        Skip the .gemlhistory commit taken before each write
+                      (default: commit, so geml_revert_block always has a
+                      revision to undo to).
+
+  Register with a client:
+    claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
 // envelope so an agent that standardizes on --json never has to parse text.
@@ -779,6 +831,19 @@ function fail(msg, code = 2) {
         console.error(`error: ${msg}`);
     process.exit(code);
 }
+// Refuse a mutation whose RESULT would be broken (the pre-write check every
+// mutation runs). Prose mode is the long-standing wording: the first error,
+// phrased by the call site. `--json` additionally carries the FULL diagnostic
+// list with the stable codes of spec Appendix A, so a programmatic caller —
+// `geml mcp` above all — reports what actually broke instead of re-parsing
+// English out of stderr.
+function refuseBroken(prose, errs) {
+    if (jsonMode) {
+        console.error(JSON.stringify({ error: prose, code: 1, diagnostics: errs }));
+        process.exit(1);
+    }
+    fail(prose, 1);
+}
 // Read a file, or stdin when the path is "-". On failure emit a clean error.
 function readInput(file) {
     try {
@@ -942,10 +1007,10 @@ function runHistory(args) {
             console.log(`restored ${file} to ${rev}`);
         }
         else if (sub === "log") {
-            // Newest-first, with the `--to` selector for each row in the first column
-            // (`latest` for the tip, then `-1`, `-2`, …) so the output is copy-paste.
+            // Newest-first, with the `--rev` selector for each row in the first column
+            // (`0` for the tip, then `-1`, `-2`, …) so the output is copy-paste.
             for (const r of listRevisions(historyPath)) {
-                const sel = r.current ? "latest" : `-${r.offset}`;
+                const sel = r.current ? "0" : `-${r.offset}`;
                 console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
             }
         }
@@ -957,39 +1022,98 @@ function runHistory(args) {
         fail(historyError(e, file, historyPath));
     }
 }
-// `geml convert <file.md|-> [-o out.geml]` — Markdown -> GEML.
-function runConvert(args) {
-    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== flag(args, "-o")));
+function runTransform(argv) {
+    const out = flag(argv, "-o") ?? flag(argv, "--out");
+    const fromRaw = flag(argv, "--from");
+    const toRaw = flag(argv, "--to");
+    const [file] = positionals(argv, ["-o", "--out", "--from", "--to"]);
     if (!file)
-        fail(SUBHELP.convert);
-    const { geml, notes } = mdToGeml(readInput(file));
-    for (const n of notes)
-        console.error(`note: ${n}`);
-    const outPath = flag(args, "-o") ?? flag(args, "--out");
-    if (outPath) {
-        writeFileSync(outPath, geml);
-        console.error(`wrote ${outPath}`);
+        fail("no input file (use '-' to read from stdin)", 2);
+    // A bare `--to`/`--from` (no following value) is a mistyped flag, not a
+    // silent fall-through to the default — flag() would return undefined and we
+    // must not quietly ignore it.
+    if (argv.includes("--from") && fromRaw === undefined)
+        fail("--from needs a format (geml | md | json)", 2);
+    if (argv.includes("--to") && toRaw === undefined)
+        fail("--to needs a format (json | html | md | geml)", 2);
+    // Input format: an explicit --from wins (for any input, file or stdin), else
+    // the file extension, else GEML (covers .geml, unknown extensions, and stdin).
+    let inFmt;
+    if (fromRaw !== undefined) {
+        if (fromRaw !== "geml" && fromRaw !== "md" && fromRaw !== "json") {
+            fail(`--from: unknown input format '${fromRaw}' (want geml | md | json)`, 2);
+        }
+        inFmt = fromRaw;
+    }
+    else if (/\.(md|markdown)$/i.test(file)) {
+        inFmt = "md";
+    }
+    else if (/\.json$/i.test(file)) {
+        inFmt = "json";
     }
     else {
-        process.stdout.write(geml);
+        inFmt = "geml";
     }
-}
-// `geml export <file.geml|-> [-o out.md]` — GEML -> Markdown (lossy). Writes
-// the output even with diagnostics, prints any lossy-projection notes, and
-// exits non-zero on a parse error — same contract as render.
-function runExport(args) {
-    const out = flag(args, "-o") ?? flag(args, "--out");
-    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== out));
-    if (!file)
-        fail(SUBHELP.export);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
-    const { md, notes } = gemlToMd(doc);
-    if (out) {
-        writeFileSync(out, md);
-        console.error(`wrote ${out}`);
+    // Output format: an explicit --to wins, else md input -> geml, geml -> json.
+    let outFmt;
+    if (toRaw !== undefined) {
+        if (toRaw !== "json" && toRaw !== "html" && toRaw !== "md" && toRaw !== "geml") {
+            fail(`--to: unknown output format '${toRaw}' (want json | html | md | geml)`, 2);
+        }
+        outFmt = toRaw;
     }
-    else
-        process.stdout.write(md);
+    else {
+        outFmt = inFmt === "geml" ? "json" : "geml"; // geml->json; md/json->geml
+    }
+    const src = readInput(file);
+    // md -> geml is a direct projection, not a parse/serialize round-trip: emit
+    // the converter's GEML verbatim (the old `convert`; no diagnostics to raise).
+    if (inFmt === "md" && outFmt === "geml") {
+        const { geml, notes } = mdToGeml(src);
+        writeOut(geml, out);
+        for (const n of notes)
+            console.error(`note: ${n}`);
+        return;
+    }
+    // Otherwise load a document — a md input is converted to GEML first — and
+    // project it to the target.
+    let notes = [];
+    let doc;
+    if (inFmt === "json") {
+        doc = loadModelJson(src, file); // the inverse of `--to json`
+    }
+    else if (inFmt === "md") {
+        const conv = mdToGeml(src);
+        notes = conv.notes;
+        doc = parse(conv.geml, { resolveDoc: resolverFor(file) });
+    }
+    else {
+        doc = parse(src, { resolveDoc: resolverFor(file) });
+    }
+    let output;
+    switch (outFmt) {
+        case "json":
+            output = JSON.stringify(doc, null, 2) + "\n"; // == the former bare parse
+            break;
+        case "geml":
+            output = serialize(doc); // == the former `fmt`
+            break;
+        case "html":
+            output = renderHtml(doc, {
+                source: file === "-" ? "stdin" : basename(file),
+                // geml-code-graph embeds load + parse sibling codemap docs on demand.
+                loadDoc: resolverFor(file),
+                parseDoc: (s) => parse(s),
+            });
+            break;
+        case "md": {
+            const r = gemlToMd(doc); // == the former `export`
+            notes = notes.concat(r.notes);
+            output = r.md;
+            break;
+        }
+    }
+    writeOut(output, out);
     for (const n of notes)
         console.error(`note: ${n}`);
     for (const d of doc.diagnostics)
@@ -997,55 +1121,57 @@ function runExport(args) {
     if (doc.diagnostics.some((d) => d.severity === "error"))
         process.exit(1);
 }
-// `geml render <file.geml> [-o out.html]` — GEML -> one self-contained,
-// interactive HTML artifact (the P0 runtime). Writes the file even when there
-// are diagnostics (a viewer should still show what it can), but exits non-zero
-// on any error so CI and agents get a hard signal.
-function runRender(args) {
-    const out = flag(args, "-o") ?? flag(args, "--out");
-    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== out));
-    if (!file)
-        fail(SUBHELP.render);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
-    const html = renderHtml(doc, {
-        source: file === "-" ? "stdin" : basename(file),
-        // geml-code-graph embeds load + parse sibling codemap documents on demand.
-        loadDoc: resolverFor(file),
-        parseDoc: (s) => parse(s),
-    });
-    if (out) {
-        writeFileSync(out, html);
-        console.error(`wrote ${out}`);
+// Load a document-model JSON (the exact output of `--to json`) back into a
+// Document, so `--from json --to geml` is the inverse of a prior `--to json`.
+// The model is trusted as-is — no re-parse — so a clean round-trip is byte-stable
+// with `--to geml`. Anything that is not a document model is refused, and any
+// carried diagnostics are preserved (so a broken doc's JSON stays flagged).
+function loadModelJson(src, file) {
+    let obj;
+    try {
+        obj = JSON.parse(src);
     }
-    else
-        process.stdout.write(html);
-    for (const d of doc.diagnostics)
-        console.error(`${d.severity}: ${d.message} (line ${d.line})`);
-    if (doc.diagnostics.some((d) => d.severity === "error"))
-        process.exit(1);
+    catch (e) {
+        fail(`--from json: ${file === "-" ? "stdin" : file} is not valid JSON (${e.message})`, 1);
+    }
+    const d = obj;
+    if (!d || typeof d !== "object" || d.kind !== "document" || !Array.isArray(d.children)) {
+        fail(`--from json: not a GEML document-model JSON (expected {"kind":"document","children":[…]})`, 1);
+    }
+    const doc = d;
+    if (!Array.isArray(doc.diagnostics))
+        doc.diagnostics = [];
+    return doc;
 }
-// `geml fmt <file.geml> [-o out.geml]` — re-serialize the document model into
-// canonical GEML. Because `serialize` is the inverse of `parse`, `fmt` is a
-// pretty-printer whose output parses back to the same model (round-trip stable).
-function runFmt(args) {
-    const out = flag(args, "-o") ?? flag(args, "--out");
-    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== out));
-    if (!file)
-        fail(SUBHELP.fmt);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
-    const text = serialize(doc);
+// Write to `-o out` (with a `wrote` note on stderr) or to stdout.
+function writeOut(text, out) {
     if (out) {
         writeFileSync(out, text);
         console.error(`wrote ${out}`);
     }
     else
         process.stdout.write(text);
-    // A broken document must not be reported as a clean format. Surface the
-    // diagnostics and exit non-zero, matching parse/render/check.
-    for (const d of doc.diagnostics)
-        console.error(`${d.severity}: ${d.message} (line ${d.line})`);
-    if (doc.diagnostics.some((d) => d.severity === "error"))
-        process.exit(1);
+}
+// Output-target rule shared by the MUTATION verbs (set, and — soon — add,
+// delete, rename, revert): a real file input with no `-o` is edited IN PLACE
+// (it's the obvious target, and it's what lets an agent chain edits without
+// re-reading a path back out of stdout); stdin (`file === "-"`) has no such
+// target, so it falls back to stdout. `-o` always wins when given: `-o -`
+// explicitly requests stdout (even for a file input), `-o <path>` writes
+// there. Every write announces itself with `wrote <path>` on stderr; stdout
+// stays reserved for the document bytes so it's still pipeable.
+function resolveOutTarget(file, oFlag) {
+    const toFile = (path) => ({
+        write(text) { writeFileSync(path, text); console.error(`wrote ${path}`); },
+    });
+    const toStdout = { write(text) { process.stdout.write(text); } };
+    if (oFlag === "-")
+        return toStdout;
+    if (oFlag !== undefined)
+        return toFile(oFlag);
+    if (file === "-")
+        return toStdout;
+    return toFile(file);
 }
 // Positional args (a file, an id) are the non-flag tokens that aren't the value
 // of a value-taking flag. `-` (stdin) is a positional, not a flag. An id may be
@@ -1069,6 +1195,47 @@ function positionals(args, valued) {
     }
     return out;
 }
+// `geml get <file>` with no id: list every addressable id — the document's
+// table of contents. Default output is one id per line with its kind (and, for
+// a heading, its level and text); `--json` is a machine-readable array so an
+// agent can pick its next `get #id` target. Ids are listed in document order
+// (the registration order parse() records), covering the same set `get #id`
+// resolves against: typed blocks, headings, and footnote definitions.
+function listIds(source, file, json) {
+    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const rows = doc.ids.map((id) => {
+        const site = findBlockSite(doc.children, id);
+        const b = site?.siblings[site.index];
+        if (b?.kind === "heading")
+            return { id, kind: "heading", level: b.level, text: b.text };
+        if (b?.kind === "block") {
+            const row = { id, kind: b.type };
+            if (b.classes.includes("footnote"))
+                row.footnote = true; // §5.2 footnote definition
+            return row;
+        }
+        return { id, kind: b?.kind ?? "unknown" };
+    });
+    if (json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.error(`no addressable ids in ${file === "-" ? "stdin" : file}`);
+        return;
+    }
+    // Align the id and kind columns; append a heading's level+text or a footnote flag.
+    const idW = Math.max(...rows.map((r) => r.id.length + 1));
+    const kindW = Math.max(...rows.map((r) => r.kind.length));
+    for (const r of rows) {
+        let line = `#${r.id}`.padEnd(idW + 1) + " " + r.kind.padEnd(kindW);
+        if (r.kind === "heading")
+            line += `  h${r.level}  ${r.text}`;
+        else if (r.footnote)
+            line += "  footnote";
+        console.log(line.replace(/\s+$/, ""));
+    }
+}
 // `geml get <file.geml|-> #id [--json]` — print ONE block, addressed by id,
 // without loading the rest of the document into context. Default output is the
 // block's exact source bytes: a typed block's full `=== … ===` span, a
@@ -1081,8 +1248,14 @@ function runGet(args) {
     const json = args.includes("--json");
     const headOnly = args.includes("--head");
     const [file, rawId] = positionals(args, []);
-    if (!file || !rawId)
+    if (!file)
         fail(SUBHELP.get);
+    // No id: list every addressable id — the document's "table of contents", so
+    // an agent can discover what `get #id` can target without pulling the model.
+    if (!rawId) {
+        listIds(readInput(file), file, json);
+        return;
+    }
     const id = rawId.replace(/^#/, "");
     const source = readInput(file);
     if (json) {
@@ -1118,42 +1291,407 @@ function runGet(args) {
     const span = headOnly ? narrowToHead(found) : found;
     process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
 }
-// `geml set <file.geml|-> #id [--from FILE] [-o out]` — replace ONLY that
-// block's source span with new content (from --from or stdin), preserving every
-// other byte. Prints the full updated document, or writes in place with -o. The
-// splice is re-parsed and rejected if it broke the doc: `set` never writes a
-// corrupt file.
+const NO_CONTENT = "no replacement content (use --in FILE or pipe it on stdin)";
+// `geml set <file.geml|-> #id [--head|--body] [--in F|F#src|-] [-o out]` —
+// replace ONE existing block, addressed by #id, with new content, preserving
+// every other byte. Two content CHANNELS × three MODES:
+//
+//   channels · `--in F[#src]` extracts a BLOCK from GEML file F (F is always
+//              read as GEML — extension ignored, no md conversion): `--in F`
+//              takes the block whose id == the target #id; `--in F#src` takes
+//              #src. stdin (default, or `--in -`) is raw bytes.
+//   modes    · default replaces the WHOLE block, `--head` only the head line,
+//              `--body` only the body. Default and `--head` NORMALIZE the
+//              content's id to #id (its source id is irrelevant); `--body`
+//              keeps the target's head verbatim, so #id is preserved naturally.
+//
+// Output follows resolveOutTarget (file -> in place, stdin -> stdout, `-o`/`-o -`
+// override) and every splice is guarded — re-parsed and rejected if it broke
+// the doc, so `set` never writes a corrupt file.
 function runSet(args) {
     const out = flag(args, "-o") ?? flag(args, "--out");
-    const from = flag(args, "--from");
+    const from = flag(args, "--in");
     const headOnly = args.includes("--head");
-    const [file, rawId] = positionals(args, ["-o", "--out", "--from"]);
-    if (!file || !rawId)
+    const bodyOnly = args.includes("--body");
+    if (headOnly && bodyOnly)
+        fail("--head and --body are mutually exclusive", 2);
+    const [file, rawId] = positionals(args, ["-o", "--out", "--in"]);
+    if (!file)
         fail(SUBHELP.set);
+    // No id: there is no block to replace. Point the way to discovery, not a bare
+    // usage line — `geml get <file>` lists every id `set` can target.
+    if (!rawId)
+        fail(`no #id given — run 'geml get ${file === "-" ? "<file>" : file}' to list addressable ids`, 2);
     const id = rawId.replace(/^#/, "");
-    // Both the document and the replacement can't come from stdin. Reject that up
-    // front — before consuming stdin — so the document read below is unambiguous.
-    if (file === "-" && from === undefined) {
-        fail("reading the document from stdin needs --from for the new content", 2);
+    // The raw channel is stdin — `--in` omitted or `--in -`; anything else sources
+    // a block from a file. Document and content can't BOTH be stdin: reject that
+    // up front, before consuming stdin, so the document read below is unambiguous.
+    const rawChannel = from === undefined || from === "-";
+    if (file === "-" && rawChannel) {
+        fail("reading the document from stdin needs --in for the new content", 2);
     }
     const source = readInput(file);
-    // New content: an explicit --from file, else stdin.
-    let replacement;
-    if (from !== undefined) {
-        replacement = readInput(from);
+    if (bodyOnly) {
+        runSetBody(source, id, from, rawChannel, file, out);
+        return;
+    }
+    // default / --head: content is a whole block (default) or a bare head line.
+    let content;
+    if (rawChannel) {
+        content = readInput("-");
+        if (content === "")
+            fail(NO_CONTENT, 1);
+        // Default mode wants exactly ONE block. Pure prose has no head to carry the
+        // id (steer to --body); multiple blocks are `add`'s job. --head takes a
+        // lone head line, so it skips the whole-block shape check.
+        if (!headOnly) {
+            const shape = contentShape(content);
+            if (shape === "empty")
+                fail(NO_CONTENT, 1);
+            if (shape === "prose")
+                fail(`content is prose, not a block — use --body to set the body of #${id}`, 1);
+            if (shape === "multi")
+                fail("set replaces ONE block, but the content has multiple blocks (use add)", 1);
+        }
     }
     else {
-        replacement = readInput("-");
-        if (replacement === "")
-            fail("no replacement content (use --from FILE or pipe it on stdin)", 1);
+        content = extractBlock(from, id, headOnly ? "head" : "whole");
     }
-    const updated = spliceBlock(source, id, replacement, file, headOnly);
-    if (out) {
-        writeFileSync(out, updated);
-        console.error(`wrote ${out}`);
+    const normalized = normalizeBlockId(content, id);
+    const updated = spliceBlock(source, id, normalized, file, headOnly);
+    resolveOutTarget(file, out).write(updated);
+}
+// `--body`: swap ONLY the target block's body, keeping its head (and #id) and,
+// for a typed block, its close fence. Assembles head + new body + close and
+// reuses the guarded spliceBlock — the head carries #id, so the id survives
+// with no normalization needed.
+function runSetBody(source, id, from, rawChannel, file, out) {
+    const found = blockSpans(source).get(id);
+    if (!found)
+        fail(`no block with id \`${id}\``, 1);
+    const lines = splitLines(source);
+    const headLine = lines[found.start] ?? "";
+    const headText = stripEol(headLine);
+    // A typed block keeps its closing fence; a heading section has none.
+    let closeLine = null;
+    const open = FENCE_OPEN.exec(headText);
+    if (open) {
+        const lastText = stripEol(lines[found.end - 1] ?? "").replace(/[ \t]+$/, "");
+        const bid = open[3] ? parseAttrs(open[3]).id : undefined;
+        const labeled = bid !== undefined && new RegExp(`^={3,}[ \\t]+#${reLit(bid)}[ \\t]*$`).test(lastText);
+        if (isCloseFence(lastText, open[1].length) || labeled)
+            closeLine = lines[found.end - 1] ?? "";
+    }
+    let body;
+    if (rawChannel) {
+        body = readInput("-");
+        if (body === "")
+            fail(NO_CONTENT, 1);
+    }
+    else {
+        body = extractBlock(from, id, "body");
     }
+    let head = headLine;
+    if (head !== "" && !/(\r\n|\r|\n)$/.test(head))
+        head += "\n";
+    let b = body.replace(/\r\n?/g, "\n");
+    if (closeLine !== null && b !== "" && !b.endsWith("\n"))
+        b += "\n";
+    const replacement = closeLine !== null ? head + b + closeLine : head + b;
+    // A typed block (closeLine !== null) must stay ONE block: enforce the
+    // block-count invariant so a `===` fence in the raw body can't close it early
+    // and inject siblings (SEC F2). A heading section body has no close fence and
+    // may legitimately contain blocks, so it is not count-guarded.
+    const updated = spliceBlock(source, id, replacement, file, false, closeLine !== null);
+    resolveOutTarget(file, out).write(updated);
+}
+// `geml add <file|-> (--append | --before #x | --after #x) [--in F|F#src|-] [-o]`
+// — insert a GEML fragment (1+ blocks and/or prose) at a position. Unlike `set`,
+// `add` names no target id, so content keeps its OWN ids (no normalization); an
+// id colliding with the document (or duplicated within the fragment) makes the
+// re-parse fail and nothing is written. Bare prose is a valid fragment.
+function runAdd(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const from = flag(args, "--in");
+    const before = flag(args, "--before");
+    const after = flag(args, "--after");
+    const append = args.includes("--append");
+    const posCount = (append ? 1 : 0) + (before !== undefined ? 1 : 0) + (after !== undefined ? 1 : 0);
+    if (posCount !== 1)
+        fail("add needs exactly one position: --append | --before #id | --after #id", 2);
+    const [file] = positionals(args, ["-o", "--out", "--in", "--before", "--after"]);
+    if (!file)
+        fail(SUBHELP.add);
+    const rawChannel = from === undefined || from === "-";
+    if (file === "-" && rawChannel)
+        fail("reading the document from stdin needs --in for the new content", 2);
+    const source = readInput(file);
+    // Content: --in F#src -> block #src; --in F -> all of F (a multi-block
+    // fragment is fine here); stdin -> raw. No id-normalization: add keeps ids.
+    let content;
+    if (rawChannel)
+        content = readInput("-");
+    else if (from.includes("#"))
+        content = extractBlock(from, "", "whole");
     else
-        process.stdout.write(updated);
+        content = readInput(from);
+    if (content.trim() === "")
+        fail("no content to add (use --in FILE or pipe it on stdin)", 1);
+    // Resolve the physical-line insertion point.
+    const lines = splitLines(source);
+    let at;
+    if (append) {
+        at = lines.length;
+    }
+    else {
+        const anchorId = (before ?? after).replace(/^#/, "");
+        const span = blockSpans(source).get(anchorId);
+        if (!span)
+            fail(`no block with id \`${anchorId}\` in ${file === "-" ? "stdin" : file}`, 1);
+        at = before !== undefined ? span.start : span.end;
+    }
+    const updated = insertFragment(source, lines, at, content, file);
+    resolveOutTarget(file, out).write(updated);
+}
+// Splice `fragment` into `source` at physical-line index `at` (splitLines
+// coords), separating it from adjacent content with a single blank line so
+// blocks don't fuse, then GUARD: the re-parse must be error-free (a colliding
+// or duplicate id surfaces as an error diagnostic) and no pre-existing id may
+// vanish. Returns the updated text; on any violation fail()s and writes nothing.
+function insertFragment(source, lines, at, fragment, file) {
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const before = lines.slice(0, at);
+    const after = lines.slice(at);
+    // The preceding line must end in a newline so the fragment starts on its own.
+    if (before.length && !/(\r\n|\r|\n)$/.test(before[before.length - 1])) {
+        before[before.length - 1] += "\n";
+    }
+    let frag = fragment.replace(/\r\n?/g, "\n");
+    if (!frag.endsWith("\n"))
+        frag += "\n";
+    // A single blank separator on each side that has adjacent content and isn't
+    // already blank — keeps a following head / preceding block from fusing.
+    const blank = (s) => stripEol(s).trim() === "";
+    const sepBefore = before.length && !blank(before[before.length - 1]) ? "\n" : "";
+    const sepAfter = after.length && !blank(after[0]) ? "\n" : "";
+    const updated = before.join("") + sepBefore + frag + sepAfter + after.join("");
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
+    if (errs.length) {
+        const first = errs[0];
+        refuseBroken(`adding the content would break the document: ${first.message} (line ${first.line}); not written`, errs);
+    }
+    const now = new Set(reparsed.ids);
+    const dropped = beforeIds.find((x) => !now.has(x));
+    if (dropped !== undefined)
+        fail(`adding the content would drop block \`#${dropped}\`; not written`, 1);
+    return updated;
+}
+// `geml delete <file|-> #id [#id2 …] [-o]` — remove one or more blocks. A
+// missing id is SKIPPED with a note (declarative "ensure absent", not an
+// error). Unlike set/add, delete's write is LENIENT: removing a complete block
+// can't break the parse structurally, but it may leave a reference dangling —
+// that is a WARNING, never a refusal (delete is reversible via revert + history,
+// and `geml check` still flags the dangling ref afterward). Contained/overlapping
+// spans (a nested block inside a deleted heading section) are handled by deleting
+// the UNION of target lines, so a line is never spliced twice.
+function runDelete(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const pos = positionals(args, ["-o", "--out"]);
+    const file = pos[0];
+    if (!file)
+        fail(SUBHELP.delete);
+    const ids = pos.slice(1).map((s) => s.replace(/^#/, ""));
+    if (ids.length === 0)
+        fail("delete needs at least one #id (run 'geml get <file>' to list ids)", 2);
+    const source = readInput(file);
+    const spans = blockSpans(source);
+    const toDelete = new Set();
+    let found = 0;
+    for (const id of ids) {
+        const span = spans.get(id);
+        if (!span) {
+            console.error(`skipped #${id}: no such block`);
+            continue;
+        }
+        found++;
+        for (let i = span.start; i < span.end; i++)
+            toDelete.add(i);
+    }
+    if (found === 0) {
+        resolveOutTarget(file, out).write(source);
+        return;
+    } // nothing to remove
+    const updated = splitLines(source).filter((_, i) => !toDelete.has(i)).join("");
+    // Lenient guard: surface any resulting error diagnostic (a reference now
+    // dangling) as a WARNING, but write regardless.
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    for (const d of reparsed.diagnostics.filter((x) => x.severity === "error")) {
+        console.error(`warning: ${d.message} (line ${d.line}) — left dangling by delete; run 'geml check' to see it as an error`);
+    }
+    resolveOutTarget(file, out).write(updated);
+}
+// `geml rename <file|-> #old #new [-o]` — the one verb that reaches OUTSIDE a
+// block: it rewrites #old's declaration AND every reference to it. #new must be
+// free; the guarded re-parse refuses anything that would break the doc.
+function runRename(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const [file, rawOld, rawNew] = positionals(args, ["-o", "--out"]);
+    if (!file || !rawOld || !rawNew)
+        fail(SUBHELP.rename);
+    const oldId = rawOld.replace(/^#/, "");
+    const newId = rawNew.replace(/^#/, "");
+    if (oldId === newId)
+        fail("#old and #new are the same id — nothing to rename", 2);
+    const source = readInput(file);
+    const before = parse(source, { resolveDoc: resolverFor(file) });
+    if (!before.ids.includes(oldId))
+        fail(`no block with id \`${oldId}\``, 1);
+    if (before.ids.includes(newId))
+        fail(`id \`${newId}\` already exists; not written`, 1);
+    // Renaming an id that has recorded history breaks the revert-lineage for it
+    // (revert keys by id and can't follow #old -> #new across the boundary). Warn
+    // so the user knows a later `revert #new` won't reach pre-rename revisions.
+    if (file !== "-") {
+        const hp = historyPathFor(file);
+        if (existsSync(hp)) {
+            try {
+                if (blockSpans(resolveContent(hp, "0").text).has(oldId)) {
+                    console.error(`warning: #${oldId} has history; revert across this rename is not tracked — see docs`);
+                }
+            }
+            catch { /* unreadable/empty history: no warning */ }
+        }
+    }
+    const updated = rewriteId(source, oldId, newId, file);
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
+    if (errs.length) {
+        const e = errs[0];
+        refuseBroken(`rename would break the document: ${e.message} (line ${e.line}); not written`, errs);
+    }
+    if (!reparsed.ids.includes(newId))
+        fail(`rename did not produce #${newId}; not written`, 1);
+    if (reparsed.ids.includes(oldId))
+        fail(`#${oldId} still present after rename; not written`, 1);
+    // Every OTHER id must be untouched. The `#old` match boundary treats a char
+    // outside [A-Za-z0-9_-] as an id terminator, but ids may contain e.g. `.`
+    // (`#foo.bar`), so renaming `#foo` could silently rewrite the *different* id
+    // `#foo.bar` -> `#baz.bar`. Reject when the set of ids other than the rename
+    // pair changed at all (SEC/correctness: collateral id corruption).
+    const othersBefore = before.ids.filter((id) => id !== oldId).sort().join("\n");
+    const othersAfter = reparsed.ids.filter((id) => id !== newId).sort().join("\n");
+    if (othersBefore !== othersAfter) {
+        fail(`rename would also change other ids sharing the \`${oldId}\` prefix (e.g. \`#${oldId}…\`); not written`, 1);
+    }
+    resolveOutTarget(file, out).write(updated);
+}
+// Rewrite id `old` -> `new` everywhere it is a declaration or reference, id-
+// boundary-safe: `#old` is replaced only when NOT followed by an id char, so a
+// longer id like `#old2` / `#old-x` is untouched. Covers the declaration
+// (`{#old …}`, labeled close `=== #old`), block references (`[[#old]]`,
+// `[t](#old)`, chart `data=#old`) and footnotes (`[^old]`). RAW / data block
+// BODIES (code/diagram/math/table/meta) are skipped — a `#old` there is literal
+// text, not a reference. (Known residual: id-less raw bodies and inline
+// code/math spans in flow content — see design §8.)
+function rewriteId(source, oldId, newId, file) {
+    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const spans = blockSpans(source);
+    const protectedLines = new Set();
+    for (const b of doc.children) {
+        if (b.kind === "block" && (b.mode === "raw" || b.mode === "data") && b.id) {
+            const span = spans.get(b.id);
+            if (span) {
+                const br = bodyRange(source, span);
+                for (let i = br.start; i < br.end; i++)
+                    protectedLines.add(i);
+            }
+        }
+    }
+    const esc = reLit(oldId);
+    const hashRe = new RegExp(`#${esc}(?![A-Za-z0-9_-])`, "g");
+    const fnRe = new RegExp(`(\\[\\^)${esc}(?![A-Za-z0-9_-])`, "g");
+    const lines = splitLines(source);
+    for (let i = 0; i < lines.length; i++) {
+        if (protectedLines.has(i))
+            continue;
+        lines[i] = lines[i].replace(hashRe, `#${newId}`).replace(fnRe, `$1${newId}`);
+    }
+    return lines.join("");
+}
+// Extract one block from a GEML file for `--in`. `spec` is `F` (block whose id
+// == the target) or `F#src` (block #src) — the last `#` splits path from id, so
+// a `#` inside the path is tolerated; F is read as GEML regardless of extension
+// (blockSpans + splitLines, no parse — same slice `geml get` prints). `part`
+// selects the whole span, its head line, or its body. A missing file or absent
+// id is an operation error (exit 1); the caller writes nothing.
+function extractBlock(spec, targetId, part) {
+    const hash = spec.lastIndexOf("#");
+    const fragFile = hash >= 0 ? spec.slice(0, hash) : spec;
+    const fragId = hash >= 0 ? spec.slice(hash + 1).replace(/^#/, "") : targetId;
+    let text;
+    try {
+        text = readFileSync(fragFile, "utf8");
+    }
+    catch {
+        fail(`cannot read ${fragFile}`, 1);
+    }
+    const span = blockSpans(text).get(fragId);
+    if (!span)
+        fail(`no block with id \`${fragId}\` in ${fragFile}`, 1);
+    const lines = splitLines(text);
+    if (part === "head")
+        return lines.slice(span.start, span.start + 1).join("");
+    if (part === "body") {
+        const b = bodyRange(text, span);
+        return lines.slice(b.start, b.end).join("");
+    }
+    return lines.slice(span.start, span.end).join("");
+}
+// Strip a single trailing terminator (`\r\n`, `\r`, or `\n`) from one line.
+function stripEol(line) {
+    return line.replace(/(\r\n|\r|\n)$/, "");
+}
+// The body sub-range of a block span: [head+1, close) for a closed typed block,
+// otherwise [head+1, end) — a heading section (no close fence) or an
+// unterminated block whose span already runs to end-of-scope.
+function bodyRange(text, span) {
+    const lines = splitLines(text);
+    const open = FENCE_OPEN.exec(stripEol(lines[span.start] ?? ""));
+    if (open) {
+        const lastText = stripEol(lines[span.end - 1] ?? "").replace(/[ \t]+$/, "");
+        const bid = open[3] ? parseAttrs(open[3]).id : undefined;
+        const labeled = bid !== undefined && new RegExp(`^={3,}[ \\t]+#${reLit(bid)}[ \\t]*$`).test(lastText);
+        const closed = isCloseFence(lastText, open[1].length) || labeled;
+        return { start: span.start + 1, end: closed ? span.end - 1 : span.end };
+    }
+    return { start: span.start + 1, end: span.end };
+}
+// The shape of default-mode stdin content, section-aware: a heading OWNS its
+// section (`# H …blocks…` is ONE unit, not many), matching sectionEnd/blockSpans.
+// Used to reject pure prose (-> --body) and multi-block content (-> add) before
+// the splice — extraction via --in is inherently one block and skips this.
+function contentShape(content) {
+    const bs = parse(content).children;
+    let blockUnits = 0, proseUnits = 0, i = 0;
+    while (i < bs.length) {
+        const b = bs[i];
+        if (b.kind === "heading") {
+            i = sectionEndIndex(bs, i);
+            blockUnits++;
+        }
+        else if (b.kind === "block") {
+            i++;
+            blockUnits++;
+        }
+        else {
+            i++;
+            proseUnits++;
+        }
+    }
+    if (blockUnits === 0)
+        return proseUnits === 0 ? "empty" : "prose";
+    return blockUnits + proseUnits === 1 ? "single" : "multi";
 }
 // Replace block #id's source span in `source` with `replacement`, preserving
 // every other byte, and GUARD the result: the re-parse must be error-free, #id
@@ -1161,11 +1699,12 @@ function runSet(args) {
 // can silently swallow a neighbour). Returns the updated document text; on any
 // violation it calls fail() and never returns a corrupt document. Shared by
 // `set` and `revert`.
-function spliceBlock(source, id, replacement, file, headOnly = false) {
+function spliceBlock(source, id, replacement, file, headOnly = false, guardCount = false) {
     const found = blockSpans(source).get(id);
     if (!found)
         fail(`no block with id \`${id}\``, 1);
-    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const beforeDoc = parse(source, { resolveDoc: resolverFor(file) });
+    const beforeIds = beforeDoc.ids;
     // Keep the bytes before and after the target span exactly; give the new block
     // a single trailing newline so the following block still starts on its own
     // line (unless it is the file's last line, which may legitimately lack one).
@@ -1191,7 +1730,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false) {
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
-        fail(`replacement would break the document: ${first.message} (line ${first.line}); not written`, 1);
+        refuseBroken(`replacement would break the document: ${first.message} (line ${first.line}); not written`, errs);
     }
     const now = new Set(reparsed.ids);
     if (!now.has(id))
@@ -1200,22 +1739,46 @@ function spliceBlock(source, id, replacement, file, headOnly = false) {
     if (dropped !== undefined) {
         fail(`replacement would drop block \`#${dropped}\` (malformed content?); not written`, 1);
     }
+    // For a typed block with a close fence, the body is opaque and swapping it
+    // keeps exactly ONE block. A raw `--body` can embed a `===` fence of the
+    // block's length that closes the target early and turns the remainder — plus
+    // the close line we re-appended — into NEW sibling blocks, including an id-less
+    // `=== meta` that redefines document metadata (the dropped-id check above
+    // cannot see an id-less injection). Guarded callers refuse any count change.
+    // (Not enforced for heading sections / whole-block set, whose replacement may
+    // legitimately span several top-level blocks.)
+    if (guardCount && reparsed.children.length !== beforeDoc.children.length) {
+        fail(`replacement changes the block count (a fence in the body closed #${id} early and injected sibling block(s)?); not written`, 1);
+    }
     return updated;
 }
-// `geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out] [--history PATH]`
+// `geml revert <file.geml> #id [--rev <sel>] [--dry-run] [-o out] [--history PATH]`
 // Restore ONE block to a past revision's version — a targeted, guarded splice
-// that leaves the rest of the document untouched. <sel> (default `-1`): `-N` (N
-// revisions back from current), `latest`, or an id prefix/suffix. `--changed`
-// skips revisions that never touched the block, landing on its previous
-// *distinct* version. `--dry-run` prints what would be spliced in, writing
-// nothing. Writes in place by default (revert is a mutation); `-o` redirects.
+// that leaves the rest of the document untouched. <sel> (default `-1`): `0` (the
+// tip), `-N` (N revisions back), an id prefix/suffix, or `changed` — a content
+// selector that skips revisions which never touched the block, landing on its
+// previous *distinct* version. `--dry-run` prints what would be spliced in,
+// writing nothing. Writes in place by default (revert is a mutation); `-o` redirects.
 function runRevert(args) {
-    const changed = args.includes("--changed");
     const dryRun = args.includes("--dry-run");
     const headOnly = args.includes("--head");
     const out = flag(args, "-o") ?? flag(args, "--out");
-    const to = flag(args, "--to") ?? "-1";
-    const [file, rawId] = positionals(args, ["--to", "--history", "-o", "--out"]);
+    const to = flag(args, "--rev") ?? "-1";
+    // `--rev changed` is a CONTENT selector, not a position: skip commits that
+    // never touched this block, landing on its previous *distinct* version. It is
+    // just a `--rev` value, so it cannot conflict with a positional `-N`.
+    const changed = to === "changed";
+    // The former standalone `--changed` flag is now this value; refuse the old
+    // spelling loudly rather than silently ignoring it (and reverting to -1).
+    if (args.includes("--changed"))
+        fail("--changed is now `--rev changed`", 2);
+    const before = flag(args, "--before");
+    const after = flag(args, "--after");
+    const append = args.includes("--append");
+    if ((append ? 1 : 0) + (before !== undefined ? 1 : 0) + (after !== undefined ? 1 : 0) > 1) {
+        fail("revert takes at most one position: --append | --before #id | --after #id", 2);
+    }
+    const [file, rawId] = positionals(args, ["--rev", "--history", "-o", "--out", "--before", "--after"]);
     if (!file || !rawId)
         fail(SUBHELP.revert);
     if (file === "-")
@@ -1223,13 +1786,13 @@ function runRevert(args) {
     const id = rawId.replace(/^#/, "");
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const source = readInput(file);
-    const found = blockSpans(source).get(id);
-    if (!found)
-        fail(`no block with id \`${id}\` in ${file}`, 1);
-    const curSpan = headOnly ? narrowToHead(found) : found;
-    const curBlock = splitLines(source).slice(curSpan.start, curSpan.end).join("");
-    // Extract block #id's source from a reconstructed revision (undefined if the
-    // block did not exist there). Under `--head`, extract only the head line.
+    const curFull = blockSpans(source).get(id); // undefined => absent now
+    const curBlock = curFull === undefined ? undefined : (() => {
+        const span = headOnly ? narrowToHead(curFull) : curFull;
+        return splitLines(source).slice(span.start, span.end).join("");
+    })();
+    // Extract #id's block from a reconstructed revision (undefined => absent
+    // there). Under `--head`, extract only the head line.
     const pick = (text) => {
         const s = blockSpans(text).get(id);
         if (!s)
@@ -1241,7 +1804,7 @@ function runRevert(args) {
     const target = (() => {
         try {
             if (changed) {
-                const found = firstChangedContent(historyPath, curBlock, pick);
+                const found = firstChangedContent(historyPath, curBlock ?? "", pick);
                 if (!found)
                     fail(`no earlier revision changes \`${id}\``, 1);
                 return found;
@@ -1252,22 +1815,142 @@ function runRevert(args) {
             fail(historyError(e, file, historyPath), 1);
         }
     })();
-    const oldBlock = pick(target.text);
-    if (oldBlock === undefined)
-        fail(`block \`${id}\` does not exist at revision ${target.id}`, 1);
-    if (oldBlock === curBlock) {
-        console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --to -2, or --changed)"}`);
+    const oldBlock = pick(target.text); // undefined => absent at R
+    // Common write path (bespoke message; -o path redirects; -o - -> stdout).
+    const emit = (updated, verb) => {
+        const dest = out ?? file;
+        if (dest === "-")
+            process.stdout.write(updated);
+        else
+            writeFileSync(dest, updated);
+        console.error(`${verb}${dest === file ? "" : dest === "-" ? " -> stdout" : ` -> ${dest}`}`);
+    };
+    // Reconcile #id between now and revision R across the four presence cells.
+    if (curBlock === undefined && oldBlock === undefined) {
+        fail(`\`${id}\` exists in neither the document nor ${target.id} (try --rev changed)`, 1);
+    }
+    // both present -> SPLICE (undo set)
+    if (curBlock !== undefined && oldBlock !== undefined) {
+        if (oldBlock === curBlock) {
+            console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --rev -2, or --rev changed)"}`);
+            // A no-op still has to PRODUCE the document when an output destination was
+            // asked for: `-o` means "write the result somewhere", and the result of a
+            // no-op revert is the unchanged document. Returning silently here left
+            // `-o -` consumers with exit 0 and empty stdout, which reads as "success,
+            // and the document is now empty".
+            if (out !== undefined)
+                emit(source, `#${id} unchanged`);
+            return;
+        }
+        if (dryRun) {
+            console.error(`would revert #${id} to ${target.id}:`);
+            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            return;
+        }
+        emit(spliceBlock(source, id, oldBlock, file, headOnly), `reverted #${id} to ${target.id}`);
+        return;
+    }
+    // --head is only meaningful for the splice cell (it can't resurrect or remove).
+    if (headOnly) {
+        fail("--head only applies when the block exists in both the document and the target revision", 2);
+    }
+    // absent now, present at R -> RESURRECT (undo delete)
+    if (curBlock === undefined && oldBlock !== undefined) {
+        // Guard: if the block we'd resurrect is the same (modulo id) as one already
+        // present under a different id, #id was likely renamed away — resurrecting
+        // would duplicate it. Point at `rename` instead of writing.
+        const cmpKey = normalizeBlockId(oldBlock, "__cmp__");
+        for (const [cid, cs] of blockSpans(source)) {
+            if (cid === id)
+                continue;
+            const csrc = splitLines(source).slice(cs.start, cs.end).join("");
+            if (normalizeBlockId(csrc, "__cmp__") === cmpKey) {
+                fail(`#${id} looks renamed to #${cid}; use 'rename #${cid} #${id}' to undo the rename`, 1);
+            }
+        }
+        const { at, where, warn } = resurrectPosition(source, target.text, id, before, after, append, file);
+        if (dryRun) {
+            console.error(`would resurrect #${id} from ${target.id} at ${where}:`);
+            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            return;
+        }
+        if (warn)
+            console.error(`warning: anchors for #${id} are gone; appended at end`);
+        emit(insertFragment(source, splitLines(source), at, oldBlock, file), `resurrected #${id} from ${target.id} at ${where}`);
         return;
     }
+    // present now, absent at R -> REMOVE (undo add)
+    // Guard: if the block we'd remove is the same (modulo id) as one present at R
+    // under a different id, #id was likely renamed IN — removing would delete a
+    // renamed block. Point at `rename` instead (the dangerous direction).
+    {
+        const cmpKey = normalizeBlockId(curBlock, "__cmp__");
+        for (const [rid, rs] of blockSpans(target.text)) {
+            if (rid === id)
+                continue;
+            const rsrc = splitLines(target.text).slice(rs.start, rs.end).join("");
+            if (normalizeBlockId(rsrc, "__cmp__") === cmpKey) {
+                fail(`#${id} looks renamed from #${rid}; revert would delete it — use 'rename #${id} #${rid}'`, 1);
+            }
+        }
+    }
     if (dryRun) {
-        console.error(`would revert #${id} to ${target.id}:`);
-        process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+        console.error(`would remove #${id} (absent at ${target.id})`);
         return;
     }
-    const updated = spliceBlock(source, id, oldBlock, file, headOnly);
-    const dest = out ?? file;
-    writeFileSync(dest, updated);
-    console.error(`reverted #${id} to ${target.id}${dest === file ? "" : ` -> ${dest}`}`);
+    const span = curFull;
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const updated = splitLines(source).filter((_, i) => i < span.start || i >= span.end).join("");
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
+    if (errs.length) {
+        const first = errs[0];
+        refuseBroken(`removing #${id} would break the document: ${first.message} (line ${first.line}); not written`, errs);
+    }
+    const now = new Set(reparsed.ids);
+    const dropped = beforeIds.find((x) => x !== id && !now.has(x));
+    if (dropped !== undefined)
+        fail(`removing #${id} would drop block \`#${dropped}\`; not written`, 1);
+    emit(updated, `removed #${id} (absent at ${target.id})`);
+}
+// Choose the physical-line insertion point for a resurrected block. Explicit
+// --append/--before/--after win; otherwise infer from the block's neighbours in
+// revision R: the nearest id BEFORE it that still exists now (insert after it),
+// else the nearest id AFTER it that still exists (insert before it), else append
+// at end (warn=true). The deleted block's own former descendants are absent now
+// too, so they are naturally skipped as anchors.
+function resurrectPosition(source, revText, id, before, after, append, file) {
+    const lines = splitLines(source);
+    const here = blockSpans(source);
+    if (append)
+        return { at: lines.length, where: "end", warn: false };
+    if (before !== undefined) {
+        const a = before.replace(/^#/, "");
+        const s = here.get(a);
+        if (!s)
+            fail(`no block with id \`${a}\` in ${file}`, 1);
+        return { at: s.start, where: `before #${a}`, warn: false };
+    }
+    if (after !== undefined) {
+        const a = after.replace(/^#/, "");
+        const s = here.get(a);
+        if (!s)
+            fail(`no block with id \`${a}\` in ${file}`, 1);
+        return { at: s.end, where: `after #${a}`, warn: false };
+    }
+    const revIds = [...blockSpans(revText).keys()];
+    const idx = revIds.indexOf(id);
+    for (let i = idx - 1; i >= 0; i--) {
+        const s = here.get(revIds[i]);
+        if (s)
+            return { at: s.end, where: `after #${revIds[i]}`, warn: false };
+    }
+    for (let i = idx + 1; i < revIds.length; i++) {
+        const s = here.get(revIds[i]);
+        if (s)
+            return { at: s.start, where: `before #${revIds[i]}`, warn: false };
+    }
+    return { at: lines.length, where: "end", warn: true };
 }
 // geml codemap <sub>: the code-graph toolkit ships as plain scripts in the
 // package's codemap/ directory (they are argv-driven programs, some
@@ -1291,6 +1974,15 @@ function runCodemap(args) {
     const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
+// geml mcp: the document-CRUD MCP server. Runs as a child's MAIN module for the
+// same reason `codemap mcp` does — it owns stdin/stdout for the whole session
+// (the stdio transport), and dispatching by spawn keeps this module free of a
+// runtime import cycle (mcp.js imports the parser from here).
+function runMcp(args) {
+    const mod = join(dirname(fileURLToPath(import.meta.url)), "mcp.js");
+    const r = spawnSync(process.execPath, [mod, ...args], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+}
 // npm's unix bin shim is a symlink named plain `geml`, so detect "run as a
 // CLI" by resolving argv[1] to its real path, not by its spelling.
 const entry = (() => {
@@ -1339,40 +2031,39 @@ if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.t
     else if (cmd === "set") {
         runSet(argv.slice(1));
     }
+    else if (cmd === "add") {
+        runAdd(argv.slice(1));
+    }
+    else if (cmd === "delete") {
+        runDelete(argv.slice(1));
+    }
+    else if (cmd === "rename") {
+        runRename(argv.slice(1));
+    }
     else if (cmd === "revert") {
         runRevert(argv.slice(1));
     }
     else if (cmd === "history") {
         runHistory(argv.slice(1));
     }
-    else if (cmd === "convert") {
-        runConvert(argv.slice(1));
-    }
-    else if (cmd === "export") {
-        runExport(argv.slice(1));
-    }
-    else if (cmd === "render") {
-        runRender(argv.slice(1));
-    }
-    else if (cmd === "fmt") {
-        runFmt(argv.slice(1));
-    }
     else if (cmd === "check") {
         runCheck(argv.slice(1));
     }
     else if (cmd === "codemap") {
         runCodemap(argv.slice(1));
     }
+    else if (cmd === "mcp") {
+        runMcp(argv.slice(1));
+    }
     else if (cmd !== "-" && !/[.\/\\]/.test(cmd)) {
         // A bare word that is neither a known command nor a path is almost always
-        // a mistyped command — say so, don't try to read it as a file.
+        // a mistyped command — say so, don't try to read it as a file. (The
+        // reclaimed verbs render/export/fmt/convert land here too.)
         fail(`unknown command '${cmd}'. Run 'geml --help'.`);
     }
     else {
-        // Default: parse a file (or stdin via '-') to the document-model JSON.
-        const doc = parse(readInput(cmd), { resolveDoc: resolverFor(cmd) });
-        console.log(JSON.stringify(doc, null, 2));
-        if (doc.diagnostics.some((d) => d.severity === "error"))
-            process.exit(1);
+        // A file (or stdin via '-') is the transform entry: `--to`/`--from`/`-o`,
+        // default `--to json`. The single door for every format conversion.
+        runTransform(argv);
     }
 }