@geml/geml 1.1.1 → 1.4.2

package/dist/geml.js

@@ -8,23 +8,32 @@
 // 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 } from "node:fs";
-import { basename, dirname, join, resolve as resolvePath } from "node:path";
+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.js";
+import { renderHtml } from "./render-html.js";
+import { normalizeBlockId } from "./block-edit.js";
 import { coerce, parseAttrs } from "./attrs.js";
-import { parseInline } from "./inline.js";
+import { META_REF_SRC, parseInline } from "./inline.js";
 import { parseTable } from "./table.js";
 import { buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
 import { serialize } from "./serialize.js";
 import { gemlToMd } from "./to-md.js";
 export { mdToGeml } from "./from-md.js";
-export { renderHtml } from "./render.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, "\\$&");
+}
 // 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 = {
@@ -34,6 +43,7 @@ const REGISTRY = {
     table: "raw", // structured table parsing lands in M3
     output: "raw", // captured result of a code block (stored, never executed)
     note: "flow",
+    text: "flow", // addressable prose container: an id/attrs for a run of flow, no callout chrome
     meta: "data",
 };
 // §7: built-in diagram renderer registry. Unknown formats are a warning (the
@@ -45,6 +55,11 @@ const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml
 const FENCE_OPEN = /^(={3,})[ \t]+([A-Za-z][A-Za-z0-9_-]*)[ \t]*(\{.*\})?[ \t]*$/;
 const HEADING = /^(#{1,6})[ \t]+(.*?)[ \t]*(\{[^}]*\})?[ \t]*$/;
 const LIST_ITEM = /^[ \t]*(?:[-*]|\d+\.)[ \t]+(.*)$/;
+// Maximum block/list nesting depth the recursive-descent scanner will build
+// before emitting a diagnostic instead of recursing further. Guards parse()
+// (scanBlocks / parseList) and, in step, the renderer against a deeply nested
+// document overflowing the call stack (DoS). 256 is far past any real document.
+const MAX_NESTING = 256;
 function isCloseFence(line, openLen) {
     const t = line.replace(/\s+$/, "");
     return /^=+$/.test(t) && t.length === openLen;
@@ -62,15 +77,67 @@ function slug(text) {
 // ---------------------------------------------------------------------------
 // §4: substitute `{{key}}` in flow text with the matching `=== meta` value.
 // An unknown key is a build error (single-source-of-truth, fail loudly).
+// The scan mirrors the §5.3(1) verbatim atoms: a `{{key}}` inside a code span
+// or inline math is left untouched (so GEML prose can document this very
+// syntax), and a backslash-escaped character can neither open a span nor a
+// `{{…}}` reference — `\{{key}}` renders as the literal text `{{key}}`.
+const META_REF = new RegExp(META_REF_SRC, "y");
 function interpolate(text, line, ctx) {
     if (!text.includes("{{"))
         return text;
-    return text.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/g, (full, key) => {
-        if (ctx.meta.has(key))
-            return ctx.meta.get(key);
-        ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
-        return full;
-    });
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\\" && i + 1 < text.length) {
+            out += c + text[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === "`") {
+            let n = 0;
+            while (text[i + n] === "`")
+                n++;
+            const close = text.indexOf("`".repeat(n), i + n);
+            if (close >= 0) {
+                out += text.slice(i, close + n);
+                i = close + n;
+                continue;
+            }
+            out += text.slice(i, i + n); // unclosed run: literal, keep scanning
+            i += n;
+            continue;
+        }
+        if (c === "$") {
+            const close = text.indexOf("$", i + 1);
+            if (close > i + 1) {
+                out += text.slice(i, close + 1);
+                i = close + 1;
+                continue;
+            }
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "{" && text[i + 1] === "{") {
+            META_REF.lastIndex = i;
+            const m = META_REF.exec(text);
+            if (m) {
+                const key = m[1];
+                if (ctx.meta.has(key))
+                    out += ctx.meta.get(key);
+                else {
+                    ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
+                    out += m[0];
+                }
+                i = META_REF.lastIndex;
+                continue;
+            }
+        }
+        out += c;
+        i++;
+    }
+    return out;
 }
 // Register a block id, flagging duplicates as errors (§4: ids unique per doc).
 function registerId(ctx, id, line) {
@@ -122,6 +189,7 @@ function parseList(lines, i, base, ctx) {
     const root = mkList(matchMarker(lines[i]));
     const stack = [{ list: root, indent: matchMarker(lines[i]).indent }];
     let prevBlank = false;
+    let tooDeep = false;
     while (i < lines.length) {
         if (lines[i].trim() === "") {
             prevBlank = true;
@@ -139,9 +207,21 @@ function parseList(lines, i, base, ctx) {
             const parent = top.list.items[top.list.items.length - 1];
             if (!parent)
                 break; // deeper indent with no parent item: defensive stop
-            cur = mkList(mk);
-            (parent.children ??= []).push(cur);
-            stack.push({ list: cur, indent: mk.indent });
+            if (stack.length >= MAX_NESTING) {
+                // Refuse to nest deeper than the cap: keep the item at the current level
+                // 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 });
+                    tooDeep = true;
+                }
+                cur = top.list;
+            }
+            else {
+                cur = mkList(mk);
+                (parent.children ??= []).push(cur);
+                stack.push({ list: cur, indent: mk.indent });
+            }
         }
         else {
             // §5: a change of marker type (bullet ↔ ordered) at the same level ends
@@ -159,7 +239,7 @@ function parseList(lines, i, base, ctx) {
     }
     return { block: root, next: i };
 }
-function scanBlocks(lines, base, ctx) {
+function scanBlocks(lines, base, ctx, depth = 0) {
     const blocks = [];
     const diags = ctx.diags;
     let i = 0;
@@ -205,7 +285,7 @@ function scanBlocks(lines, base, ctx) {
             // 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;
@@ -242,7 +322,16 @@ function scanBlocks(lines, base, ctx) {
                     ctx.refs.push({ kind: "internal", anchor: of.slice(1), line: openLineNo });
             }
             if (mode === "flow") {
-                block.children = scanBlocks(body, base + i + 1, ctx);
+                if (depth >= MAX_NESTING) {
+                    // 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 });
+                    block.raw = body;
+                }
+                else {
+                    block.children = scanBlocks(body, base + i + 1, ctx, depth + 1);
+                }
             }
             else if (mode === "data") {
                 block.data = parseData(body);
@@ -453,8 +542,46 @@ export function parse(source, opts = {}) {
 }
 // The id that a fence/heading line defines, matching how scanBlocks derives it
 // (parseAttrs for the attribute object; heading text slug when no explicit id).
-function idOfHeading(braces, text) {
-    return (braces ? parseAttrs(braces).id : undefined) ?? slug(text);
+// The slug MUST come from the INTERPOLATED text — scanBlocks slugs after
+// interpolate(), so `# {{title}} Setup` registers the substituted slug; slugging
+// the raw text here would create a phantom id the parser never registered and
+// make the real one unaddressable. `ctx` is an inert context carrying the
+// document's meta (diagnostics are discarded — spans never report).
+function idOfHeading(braces, text, line, ctx) {
+    return (braces ? parseAttrs(braces).id : undefined) ?? slug(interpolate(text, line, ctx));
+}
+// The matching close of the fence opened at lines[i] (equal-length run, or the
+// labeled `=== #id` close when the block carries an id): the index just past
+// the close line, and whether one was found — an unterminated block runs to
+// the end of the scope.
+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]+#${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 };
+    }
+    return { end: lines.length, closed: false };
+}
+// A heading's span covers its whole SECTION: the heading line through the line
+// just before the next heading of same-or-higher level (fewer-or-equal `#`) in
+// the current scope, or end-of-scope. Fenced blocks are skipped whole — a `#`
+// line inside a `=== code` body is content, never a boundary.
+function sectionEnd(lines, i, level) {
+    let j = i + 1;
+    while (j < lines.length) {
+        const open = FENCE_OPEN.exec(lines[j]);
+        if (open) {
+            j = fenceClose(lines, j, open).end;
+            continue;
+        }
+        const h = HEADING.exec(lines[j]);
+        if (h && h[1].length <= level)
+            return j;
+        j++;
+    }
+    return lines.length;
 }
 // Walk `lines` exactly as scanBlocks does — same fence close rules (equal-length
 // or labeled `=== #id`), same flow-only recursion via REGISTRY — recording the
@@ -462,7 +589,7 @@ function idOfHeading(braces, text) {
 // First definition wins, mirroring ctx.ids (a duplicate id is a build error, so
 // `get`/`set` operate on the one the parser actually registered). `base` is the
 // absolute line offset of this slice within the whole document.
-function collectSpans(lines, base, out) {
+function collectSpans(lines, base, out, ctx, depth = 0) {
     const add = (id, start, end) => {
         if (!out.has(id))
             out.set(id, { start, end });
@@ -486,33 +613,27 @@ function collectSpans(lines, base, out) {
         } // hidden line: no id
         const open = FENCE_OPEN.exec(line);
         if (open) {
-            const openLen = open[1].length;
             const type = open[2];
             const id = open[3] ? parseAttrs(open[3]).id : undefined;
-            const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${id}[ \\t]*$`) : null;
-            let j = i + 1;
-            let closed = false;
-            for (; j < lines.length; j++) {
-                if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j]))) {
-                    closed = true;
-                    break;
-                }
-            }
-            const end = closed ? j + 1 : j;
+            const { end, closed } = fenceClose(lines, i, open);
             if (id !== undefined)
                 add(id, base + i, base + end);
             // Only a flow body is scanned for nested blocks (raw/data bodies are
             // opaque), so an id inside a `code` body is *not* addressable — exactly
             // the parser's contract.
-            if ((REGISTRY[type] ?? "raw") === "flow") {
-                collectSpans(lines.slice(i + 1, closed ? j : end), base + i + 1, out);
+            if ((REGISTRY[type] ?? "raw") === "flow" && depth < MAX_NESTING) {
+                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1);
             }
             i = end;
             continue;
         }
         const h = HEADING.exec(line);
         if (h) {
-            add(idOfHeading(h[3], h[2]), base + i, base + i + 1);
+            // Section span (heading through its prose and nested blocks). The walk
+            // still advances one line at a time so every nested id inside the
+            // section registers its own span — spans intentionally OVERLAP: #sec
+            // contains #code, and each remains addressable on its own.
+            add(idOfHeading(h[3], h[2], base + i + 1, ctx), base + i, base + sectionEnd(lines, i, h[1].length));
             i++;
             continue;
         }
@@ -523,29 +644,49 @@ function collectSpans(lines, base, out) {
 // with the physical lines produced by splitLines(source).
 export function blockSpans(source) {
     const out = new Map();
-    collectSpans(source.replace(/\r\n?/g, "\n").split("\n"), 0, out);
+    const lines = source.replace(/\r\n?/g, "\n").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) };
+    collectSpans(lines, 0, out, ctx);
     return out;
 }
 // Split into physical lines while *keeping* each line's terminator, so
 // join("") is byte-exact and slicing by span never rewrites line endings.
+// A line ends at `\n` or at a LONE `\r` (old-Mac style) — the same boundaries
+// the span scan's `\r\n?` -> `\n` normalization sees, so span indices always
+// address the same lines the parser counted.
 function splitLines(source) {
-    return source.split(/(?<=\n)/);
+    return source.split(/(?<=\n|\r(?!\n))/);
+}
+// `--head`: narrow any id's span to its HEAD line — the single declaring line
+// (a heading's `# … {#id}` line, a typed block's opening fence, a footnote's
+// `[^id]:` line). The head is by construction the FIRST line of the span, so
+// the narrowing is parse-free and needs no type check. Main use: `set --head`
+// edits a block's attributes (caption/compute/lang/…) without re-sending its
+// body, or renames a heading without rewriting its section.
+function narrowToHead(span) {
+    return { start: span.start, end: span.start + 1 };
 }
 // Depth-first search for the document-model node carrying `id`, descending into
 // flow-block children (and list-item children) so a nested id is found too.
-function findBlockById(blocks, id) {
-    for (const b of blocks) {
+// Returns the containing sibling array and index, not just the node: the model
+// is FLAT — a heading does not own its section; the section's prose and blocks
+// are its FOLLOWING SIBLINGS — so a section consumer needs the array.
+function findBlockSite(blocks, id) {
+    for (let i = 0; i < blocks.length; i++) {
+        const b = blocks[i];
         if ((b.kind === "heading" || b.kind === "block") && b.id === id)
-            return b;
+            return { siblings: blocks, index: i };
         if (b.kind === "block" && b.children) {
-            const hit = findBlockById(b.children, id);
+            const hit = findBlockSite(b.children, id);
             if (hit)
                 return hit;
         }
         if (b.kind === "list") {
             for (const it of b.items) {
                 if (it.children) {
-                    const hit = findBlockById(it.children, id);
+                    const hit = findBlockSite(it.children, id);
                     if (hit)
                         return hit;
                 }
@@ -554,6 +695,21 @@ function findBlockById(blocks, id) {
     }
     return undefined;
 }
+// Model-side section boundary: within one sibling array, the section opened by
+// the heading at index k runs to the next sibling heading of same-or-higher
+// level, or the array end. This is the SAME rule sectionEnd() applies to raw
+// source lines (where skipping fenced bodies makes "next heading" well-defined)
+// — the two sides must stay in lockstep; the get-set suite pins their parity
+// (ids covered by the raw slice == ids covered by the --json envelope).
+function sectionEndIndex(siblings, k) {
+    const level = siblings[k].level;
+    for (let m = k + 1; m < siblings.length; m++) {
+        const b = siblings[m];
+        if (b.kind === "heading" && b.level <= level)
+            return m;
+    }
+    return siblings.length;
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -572,45 +728,69 @@ 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.1.1"; // 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]        print ONE block by id (raw span, or --json node)
-  geml set <file.geml|-> #id [--from f][-o f] replace ONE block by id (new content: --from/stdin)
-  geml revert <file.geml> #id [--to <sel>]   restore ONE block to a past revision (sel: -N|latest|id)
-  geml check <file.geml|-> [--json]          validate only: diagnostics + exit code
-  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|mcp> [...]   code-graph toolkit (geml codemap --help)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Exit codes: 0 ok · 1 document/operation error · 2 usage error.`;
+const PARSER_VERSION = "1.4.2"; // 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)
+                                             <fmt>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --to geml  -> canonical re-format
+                                               --to json  -> document-model JSON (default)
+                                             A Markdown input converts the other way:
+                                               geml notes.md            -> GEML
+                                             --from overrides the input format (any input):
+                                               geml notes.txt --from md    treat as Markdown
+                                               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: -N | latest | id-prefix; 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 --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]",
-    set: "usage: geml set <file.geml|-> #id [--from FILE] [-o out.geml]",
-    check: "usage: geml check <file.geml|-> [--json]",
-    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]  (sel: -N | latest | id-prefix; default -1)",
+    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)",
+    revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--changed] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out]  (reconcile #id to a revision: splice / resurrect / remove; sel: -N | latest | id-prefix; 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
-       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 mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
-       (<dir> for verify/render/serve/refresh defaults to ./.geml-code-graph)`,
+    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)`,
 };
 // 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.
@@ -634,12 +814,66 @@ function readInput(file) {
         fail(file === "-" ? "cannot read stdin" : `cannot read ${file}`);
     }
 }
-// A cross-document resolver rooted at the input's directory (cwd for stdin).
-function resolverFor(file) {
-    const baseDir = file === "-" ? "." : dirname(file);
+// A cross-document resolver rooted at the input's directory (cwd for stdin),
+// CONFINED to that directory's subtree. A reference that resolves outside the
+// base — via a `..` escape, an absolute path, or (on Windows) a different drive
+// — is refused (returns null, i.e. an unresolvable ref) so a crafted document
+// cannot turn `geml check`/parse into an arbitrary local-file read oracle. §8.
+//
+// A purely LEXICAL check is not enough: a symlink that sits lexically inside the
+// subtree but points to `../../outside.geml` passes `path.relative` yet reads an
+// external target. So after the cheap lexical gate we resolve BOTH the base and
+// the target through `realpathSync` (following every symlink component) and
+// re-check that the REAL target still lies within the REAL base subtree before
+// reading. A target that does not exist makes `realpathSync` throw — handled as
+// an ordinary unresolvable ref (null), never a crash.
+//
+// `root` (CLI `--root`, an explicit per-invocation user grant — never
+// document-controlled) widens the confinement base from the input's own
+// directory to an ancestor the user names, so repo-relative `../` references
+// between sibling directories can be checked. It moves WHERE the boundary
+// stands, never whether it is enforced: both gates below run against the
+// widened base, so escapes past the root are refused exactly as above. The
+// viewer/web surfaces never pass a root — their boundary is unchanged.
+function resolverFor(file, root) {
+    const dirAbs = resolvePath(file === "-" ? "." : dirname(file));
+    const baseAbs = root === undefined ? dirAbs : resolvePath(root);
+    // Canonicalise the base once. If the base itself cannot be realpath'd, no
+    // cross-doc ref can be safely confined — resolve nothing.
+    let realBase = null;
+    try {
+        realBase = realpathSync(baseAbs);
+    }
+    catch {
+        realBase = null;
+    }
+    const outside = (from, to) => {
+        const rel = relative(from, to);
+        return rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel);
+    };
     return (d) => {
+        if (realBase === null)
+            return null;
+        // References resolve FROM the document's own directory; the gates below
+        // confine them to the (possibly widened) base.
+        const targetAbs = resolvePath(dirAbs, d);
+        // Cheap lexical gate: reject an obvious `..`/absolute/other-drive escape
+        // before touching the filesystem.
+        if (outside(baseAbs, targetAbs))
+            return null;
+        // Real (symlink-resolved) gate: a symlink pointing out of the subtree
+        // resolves to a real path outside `realBase` and is refused here.
+        let realTarget;
+        try {
+            realTarget = realpathSync(targetAbs);
+        }
+        catch {
+            return null;
+        }
+        if (outside(realBase, realTarget))
+            return null;
         try {
-            return readFileSync(resolvePath(baseDir, d), "utf8");
+            return readFileSync(realTarget, "utf8");
         }
         catch {
             return null;
@@ -650,10 +884,22 @@ function resolverFor(file) {
 // dump (cheap for agents). `--json` prints the diagnostics array for machines.
 function runCheck(args) {
     const json = args.includes("--json");
-    const file = args.find((a) => a === "-" || !a.startsWith("-"));
+    const root = flag(args, "--root");
+    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== root));
     if (!file)
         fail(SUBHELP.check);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
+    // A mistyped --root must be a usage error (exit 2), not a wall of misleading
+    // "cannot resolve document" errors from a resolver confined to nothing.
+    if (root !== undefined) {
+        let isDir = false;
+        try {
+            isDir = statSync(root).isDirectory();
+        }
+        catch { /* missing -> not a dir */ }
+        if (!isDir)
+            fail(`--root ${root} is not a directory`);
+    }
+    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root) });
     if (json) {
         console.log(JSON.stringify(doc.diagnostics, null, 2));
     }
@@ -737,39 +983,92 @@ 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)", 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") {
+            fail(`--from: unknown input format '${fromRaw}' (want geml | md)`, 2);
+        }
+        inFmt = fromRaw;
+    }
+    else if (/\.(md|markdown)$/i.test(file)) {
+        inFmt = "md";
     }
     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 === "md" ? "geml" : "json";
+    }
+    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 === "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)
@@ -777,55 +1076,35 @@ 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}`);
-    }
-    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);
-}
-// `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
@@ -849,69 +1128,503 @@ 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 (its full `=== … ===` span, or the source line for
-// a heading/footnote); `--json` prints that block's document-model node.
+// block's exact source bytes: a typed block's full `=== … ===` span, a
+// footnote's line, or — for a heading — its whole SECTION (heading line through
+// the line before the next same-or-higher heading). `--json` covers the same
+// content: a block/footnote id prints its document-model node; a heading id
+// prints a section envelope `{kind:"section", id, level, blocks:[heading,
+// …siblings up to the boundary]}`.
 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) {
-        // The model node — same shape `geml <file>` emits for it. Parsing is needed
-        // to resolve the tree (and nested-block ids), but only the one node prints.
+        // The model node(s) — same shapes `geml <file>` emits. Parsing is needed
+        // to resolve the tree (and nested-block ids), but only the target prints.
         const doc = parse(source, { resolveDoc: resolverFor(file) });
-        const block = findBlockById(doc.children, id);
-        if (!block)
+        const site = findBlockSite(doc.children, id);
+        if (!site)
             fail(`no block with id \`${id}\``, 1);
+        const block = site.siblings[site.index];
+        // `--head` on a heading suppresses the section envelope (the lone heading
+        // node IS the head). On a block/footnote id there is nothing finer than
+        // the single node — the model has no sub-node for "just the fence line" —
+        // so --head refines only the RAW output there.
+        if (block.kind === "heading" && !headOnly) {
+            // A heading id addresses its SECTION, so `--json` covers the same
+            // content as the raw span: a self-describing envelope whose blocks[0]
+            // is the heading node followed by its siblings up to the boundary.
+            // `kind: "section"` lets a consumer branch — a block/footnote id still
+            // yields the single model node (the model itself stays flat).
+            const end = sectionEndIndex(site.siblings, site.index);
+            console.log(JSON.stringify({ kind: "section", id: block.id, level: block.level, blocks: site.siblings.slice(site.index, end) }, null, 2));
+            return;
+        }
         console.log(JSON.stringify(block, null, 2));
         return;
     }
     // Raw: slice the source span byte-for-byte. No parse required, so `get` still
     // returns the exact bytes even if the document has diagnostics elsewhere.
-    const span = blockSpans(source).get(id);
-    if (!span)
+    const found = blockSpans(source).get(id);
+    if (!found)
         fail(`no block with id \`${id}\``, 1);
+    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 [file, rawId] = positionals(args, ["-o", "--out", "--from"]);
-    if (!file || !rawId)
+    const from = flag(args, "--in");
+    const headOnly = args.includes("--head");
+    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);
-    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];
+        fail(`adding the content would break the document: ${first.message} (line ${first.line}); not written`, 1);
+    }
+    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, "latest").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];
+        fail(`rename would break the document: ${e.message} (line ${e.line}); not written`, 1);
+    }
+    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
@@ -919,15 +1632,22 @@ 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) {
-    const span = blockSpans(source).get(id);
-    if (!span)
+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).
     const orig = splitLines(source);
+    // `--head`: splice only the id's head line; everything below stays
+    // byte-identical. The guard below still applies — the replacement must
+    // re-declare `{#id}` and, for a typed block, keep the fence pairing intact
+    // (an opening line that no longer matches the untouched close fence breaks
+    // the re-parse), or the splice is refused.
+    const span = headOnly ? narrowToHead(found) : found;
     const before = orig.slice(0, span.start);
     const after = orig.slice(span.end);
     let inject = replacement.replace(/\r\n?/g, "\n");
@@ -952,9 +1672,20 @@ function spliceBlock(source, id, replacement, file) {
     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>] [--changed] [--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`
@@ -964,9 +1695,16 @@ function spliceBlock(source, id, replacement, file) {
 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";
+    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 === "-")
@@ -974,21 +1712,25 @@ function runRevert(args) {
     const id = rawId.replace(/^#/, "");
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const source = readInput(file);
-    const curSpan = blockSpans(source).get(id);
-    if (!curSpan)
-        fail(`no block with id \`${id}\` in ${file}`, 1);
-    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).
+    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);
-        return s ? splitLines(text).slice(s.start, s.end).join("") : undefined;
+        if (!s)
+            return undefined;
+        const span = headOnly ? narrowToHead(s) : s;
+        return splitLines(text).slice(span.start, span.end).join("");
     };
     // Resolve the source revision, formatting any history-layer error cleanly.
     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;
@@ -999,22 +1741,135 @@ 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 --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 --changed)"}`);
+            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);
-    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];
+        fail(`removing #${id} would break the document: ${first.message} (line ${first.line}); not written`, 1);
+    }
+    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
@@ -1027,6 +1882,7 @@ function runCodemap(args) {
         render: "render-all.mjs",
         serve: "serve.mjs",
         refresh: "refresh.mjs",
+        find: "find.mjs",
         mcp: "mcp-server.mjs",
     };
     const sub = args[0] ?? "";
@@ -1037,10 +1893,28 @@ function runCodemap(args) {
     const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
-const entry = process.argv[1] ?? "";
-if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
+// 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 = (() => {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return "";
+    try {
+        return realpathSync(argv1);
+    }
+    catch {
+        return argv1;
+    }
+})();
+// `entry` must be non-empty: in a browser bundle both sides degenerate to ""
+// (esbuild defines process.argv=[] and import.meta.url="", and the node-stub's
+// fileURLToPath is String()), which would run the CLI at import time and crash
+// the page. A real CLI invocation always has argv[1].
+if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.ts"))) {
     const argv = process.argv.slice(2);
-    const cmd = argv[0];
+    // The on-disk artifact is `.geml-code-graph/`, so people reconstruct the
+    // command from the directory name — accept those spellings as `codemap`.
+    const cmd = argv[0] === "codegraph" || argv[0] === "code-graph" ? "codemap" : argv[0];
     jsonMode = argv.includes("--json");
     const rest = argv.slice(1);
     if (cmd === "--help" || cmd === "-h") {
@@ -1067,24 +1941,21 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
     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));
     }
@@ -1093,14 +1964,13 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
     }
     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);
     }
 }