@geml/geml 1.5.1 → 1.7.0

package/dist/geml.js

@@ -9,23 +9,25 @@
 // 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 { readFileSync, writeFileSync, realpathSync, statSync, existsSync, mkdirSync, readdirSync, copyFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
-import { commit, restore, verify, listRevisions, resolveContent, firstChangedContent } from "./history.js";
+import { save, restore, verify, isCurrent, 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, isSafeUrl, schemeOf } from "./inline.js";
 import { parseTable } from "./table.js";
-import { buildChart } from "./chart.js";
+import { USES, buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
 import { serialize } from "./serialize.js";
+import { addressUnits, discoveryHint, matchContent, matchType, parseSelector, shortestAddress, } from "./selector.js";
 import { gemlToMd } from "./to-md.js";
 export { mdToGeml } from "./from-md.js";
-export { renderHtml } from "./render-html.js";
+export { renderHtml, pageAssets } 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
@@ -36,6 +38,57 @@ export { gemlToMd } from "./to-md.js";
 function reLit(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+// The `data` block's format engines (GEP-0005), shared by the inline-body
+// path and the `src=` pass: parse `body` under `fmt`, returning the value
+// and/or diagnostics. `openLineNo` anchors line numbers — the open fence for
+// an inline body, the block's own line for external content.
+function parseDataBody(fmt, body, openLineNo) {
+    const diags = [];
+    if (fmt === "json") {
+        const text = body.join("\n");
+        try {
+            return { value: JSON.parse(text), diags };
+        }
+        catch (e) {
+            diags.push({ severity: "error", code: "data-parse", message: `data: body is not valid JSON (${e instanceof Error ? e.message : String(e)})`, line: jsonErrorLine(e, text, openLineNo) });
+        }
+    }
+    else if (fmt === "jsonl") {
+        const values = [];
+        let ok = true;
+        for (let li = 0; li < body.length; li++) {
+            const t = body[li].trim();
+            if (t === "")
+                continue; // blank lines are permitted and ignored
+            try {
+                values.push(JSON.parse(t));
+            }
+            catch {
+                diags.push({ severity: "error", code: "data-parse", message: `data: body line ${li + 1} is not one JSON value`, line: openLineNo + 1 + li });
+                ok = false;
+            }
+        }
+        if (ok)
+            return { value: values, diags };
+    }
+    else if (fmt === "yaml" || fmt === "toml") {
+        diags.push({ severity: "warning", code: "data-format-no-engine", message: `data: no \`${fmt}\` engine in this processor; body kept raw, not verified`, line: openLineNo });
+    }
+    else {
+        diags.push({ severity: "warning", code: "unknown-data-format", message: `unknown data format \`${fmt}\`; body kept raw`, line: openLineNo });
+    }
+    return { diags };
+}
+// Map a JSON.parse failure to the document line it happened on. V8 messages
+// carry "at position N" (newer Nodes add line/column, but position is the
+// stable token); counting newlines up to it gives the 1-based body line, and
+// the open fence line offsets it into the document. No position -> the fence.
+function jsonErrorLine(e, text, openLineNo) {
+    const m = /position (\d+)/.exec(e instanceof Error ? e.message : "");
+    if (!m)
+        return openLineNo;
+    return openLineNo + text.slice(0, Number(m[1])).split("\n").length;
+}
 // 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";
@@ -46,6 +99,7 @@ const REGISTRY = {
     diagram: "raw",
     math: "raw",
     table: "raw", // structured table parsing lands in M3
+    data: "raw", // GEP-0005: value tree — a format engine parses the raw body in a second stage
     embed: "raw", // block transclusion: `src=` points at the content, body unused
     note: "flow",
     text: "flow", // addressable prose container: an id/attrs for a run of flow, no callout chrome
@@ -59,6 +113,24 @@ 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]*$/;
+// A line with the exact shape of a labeled close (§3): a `=` run and a `#id`,
+// nothing else. Matched against lines that fell through to paragraph text,
+// where such a line means the close closed nothing (stray-labeled-fence).
+const STRAY_LABELED_FENCE = /^={3,}[ \t]+#(\S+)[ \t]*$/;
+// The registered block types (§3's registry), for the fence-like check below:
+// an unknown word after `===` is likelier a wall of `=` art or foreign syntax,
+// so only a KNOWN type name earns the warning.
+const REGISTERED_TYPES = new Set(["code", "diagram", "table", "math", "embed", "note", "text", "meta", "data"]);
+// A line that WANTS to open a fence — a `=` run and a registered type name —
+// but failed the fence production. The classic shape is bare, unbraced
+// attributes (`=== embed src=#a`): the line silently became prose and any
+// reference in it was never checked, which buried a real bug (all eight
+// embeds of the playground showcase shipped in this shape, rendering as
+// paragraphs under a green `check`). Matched, like STRAY_LABELED_FENCE, only
+// against lines that fell through to paragraph text — raw block bodies and
+// `\`-folded fence lines never reach that position, so the measured corpus
+// false-positive rate is zero.
+const FENCE_LIKE = /^={3,}[ \t]+([A-Za-z][A-Za-z0-9_-]*)\b/;
 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()
@@ -294,22 +366,36 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             const type = open[2];
             const attrs = open[3] ? parseAttrs(open[3]) : { classes: [], attrs: {} };
             const openLineNo = base + i + 1;
-            // Collect the body. A block closes on a bare fence of exactly the opening
-            // length, OR — when it has an id — on a labeled fence `=== #id` (a `=` run
-            // 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).
+            // Collect the body. A block closes on the FIRST line that is a bare fence
+            // of exactly the opening length, OR — when it has an id — a labeled fence
+            // `=== #id` (a `=` run of any length ≥ 3 followed by the block's id). The
+            // labeled close can't be gotten wrong by miscounting `=`, but it does NOT
+            // shadow the bare close: a same-length bare fence in the body still ends
+            // the block first, so nesting needs a longer outer fence (§3).
             const labeled = attrs.id !== undefined ? new RegExp(`^={3,}[ \\t]+#${reLit(attrs.id)}[ \\t]*$`) : null;
             const body = [];
             let j = i + consumed;
             let closed = false;
+            let closedByBare = false;
             for (; j < lines.length; j++) {
-                if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j]))) {
+                if (isCloseFence(lines[j], openLen)) {
+                    closed = true;
+                    closedByBare = true;
+                    break;
+                }
+                if (labeled && labeled.test(lines[j])) {
                     closed = true;
                     break;
                 }
                 body.push(lines[j]);
             }
+            // Remember a bare close of an id-bearing block (first definition wins,
+            // mirroring ctx.ids): if a `=== #id` line for it turns up later as plain
+            // text, the stray-labeled-fence warning can name the line that really
+            // closed the block.
+            if (closedByBare && attrs.id !== undefined && !ctx.bareClosed?.has(attrs.id)) {
+                (ctx.bareClosed ??= new Map()).set(attrs.id, base + j + 1);
+            }
             if (!closed) {
                 const how = attrs.id !== undefined ? `${"=".repeat(openLen)} or \`=== #${attrs.id}\`` : "=".repeat(openLen);
                 diags.push({ severity: "error", code: "unterminated-block", message: `unterminated \`${type}\` block (no matching ${how})`, line: openLineNo });
@@ -325,11 +411,13 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                 // the extras below are per type.
                 let validRe;
                 if (type === "table")
-                    validRe = /^(src|format|header|format-data|compute\d*|summary\d*|span\d*)$/;
+                    validRe = /^(src|format|delim|header|format-data|compute\d*|summary\d*|span\d*)$/;
+                else if (type === "data")
+                    validRe = /^(format|schema|src)$/;
                 else if (type === "embed")
                     validRe = /^(src)$/;
                 else if (type === "diagram")
-                    validRe = /^(src|data|format|type|rows|x|y|size|series)$/;
+                    validRe = /^(src|data|format|format-data|delim|header|type|rows|x|y|size|series)$/;
                 // `src`/`anchor` on a `code` block are the code-graph profile's
                 // (docs/codemap-profile.md): every document `geml codemap build` writes
                 // carries them, so warning on them would warn on our own output.
@@ -415,7 +503,72 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             }
             else {
                 block.raw = body;
-                if (type === "table") {
+                if (type === "data") {
+                    // §GEP-0005: the value tree. The body stayed raw at scan time; a
+                    // format engine parses it here — the same two-stage shape `table`
+                    // uses. Admission to the format registry requires a SELF-DESCRIBING
+                    // syntax (bytes alone determine the value): the core ships `json`
+                    // (default — the model's own serialization) and `jsonl`; `yaml` and
+                    // `toml` are reserved names with no engine here, and degrade exactly
+                    // like an unknown `diagram` format: body kept raw, one warning.
+                    const fmtRaw = attrs.attrs["format"];
+                    const fmt = fmtRaw === undefined ? "json" : String(fmtRaw);
+                    // `src=` names external content — the same one-source rule tables
+                    // have (§6): exactly one of `src=` and an inline body. The engine
+                    // runs over the file in a second pass (resolveDataSources); running
+                    // it here over the empty body would report a spurious parse error.
+                    const srcAttr = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : undefined;
+                    const hasBody = body.some((l) => l.trim() !== "");
+                    if (srcAttr !== undefined && srcAttr !== "" && hasBody) {
+                        diags.push({ severity: "error", code: "data-src-and-body", message: "data: carries both `src=` and an inline body; exactly one is permitted (the body wins here)", line: openLineNo });
+                    }
+                    if (srcAttr !== undefined && srcAttr !== "" && !hasBody) {
+                        (ctx.dataSources ??= []).push({ block, line: openLineNo, target: srcAttr });
+                    }
+                    else {
+                        const parsed = parseDataBody(fmt, body, openLineNo);
+                        for (const d of parsed.diags)
+                            diags.push(d);
+                        if (parsed.value !== undefined)
+                            block.value = parsed.value;
+                    }
+                    // `schema=` is reference-checked ONLY (GEP-0005): it must name a
+                    // block or a GEML document; validating the value against it is a
+                    // later GEP. The reference goes through the ordinary §8 resolver so
+                    // a dangling schema rots loudly like any other reference.
+                    const schema = attrs.attrs["schema"];
+                    if (schema !== undefined) {
+                        const s = typeof schema === "string" ? schema.trim() : "";
+                        if (s.startsWith("#") && s.length > 1) {
+                            ctx.refs.push({ kind: "internal", anchor: s.slice(1), line: openLineNo });
+                        }
+                        else if (/\.geml(#|$)/i.test(s)) {
+                            const h = s.indexOf("#");
+                            if (h < 0)
+                                ctx.refs.push({ kind: "cross", doc: s, anchor: undefined, line: openLineNo });
+                            else
+                                ctx.refs.push({ kind: "cross", doc: s.slice(0, h), anchor: s.slice(h + 1), line: openLineNo });
+                        }
+                        else {
+                            diags.push({ severity: "error", code: "bad-data-schema", message: `data: \`schema=${s}\` must name a block (\`#id\`) or a GEML document (\`doc.geml[#id]\`)`, line: openLineNo });
+                        }
+                    }
+                    // First definition wins, matching ctx.ids/ctx.tables.
+                    if (block.id !== undefined && block.value !== undefined && !ctx.dataValues?.has(block.id)) {
+                        (ctx.dataValues ??= new Map()).set(block.id, block.value);
+                    }
+                }
+                else if (type === "code") {
+                    // `src=` on a code block is a ROUTE to the code it shows —
+                    // `<path>[#L<start>[-<end>]]` — resolved in a second pass, like a
+                    // table's `src=`. The code-graph runtime has always fetched and
+                    // sliced it at render time; checking it here is what makes a stale
+                    // range a build error instead of a panel that silently shows a path.
+                    const srcAttr = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : undefined;
+                    if (srcAttr !== undefined && srcAttr !== "")
+                        (ctx.codeSources ??= []).push({ block, line: openLineNo, target: srcAttr });
+                }
+                else if (type === "table") {
                     const srcAttr = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : undefined;
                     // §6: parse the raw body (visual or csv/tsv) into one table model.
                     const { model, diagnostics } = parseTable(body, attrs.attrs, openLineNo, ctx);
@@ -501,6 +654,38 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             para.push(lines[i]);
             i++;
         }
+        // A line shaped exactly like a labeled close (`=== #id`) that got this far
+        // closed nothing — when the id's block was already ended by a same-length
+        // bare fence in its body (§3), everything from that fence on silently fell
+        // out of the block. Warn: "ok: no diagnostics" over a truncated document is
+        // the failure mode this diagnostic exists for. The id is used only as a Map
+        // key here — no RegExp is built from it, so reLit() does not apply.
+        for (let k = 0; k < para.length; k++) {
+            const stray = STRAY_LABELED_FENCE.exec(para[k]);
+            if (!stray)
+                continue;
+            const id = stray[1];
+            const lineNo = paraStart + k;
+            const closedAt = ctx.bareClosed?.get(id);
+            diags.push({
+                severity: "warning", code: "stray-labeled-fence", line: lineNo,
+                message: closedAt !== undefined
+                    ? `labeled fence for \`#${id}\` at line ${lineNo}, but block \`#${id}\` was already closed by a bare fence at line ${closedAt} — body may be silently truncated`
+                    : `labeled fence for \`#${id}\` closes no block; the line is plain paragraph text`,
+            });
+        }
+        for (let k = 0; k < para.length; k++) {
+            // Sibling trap to the stray labeled close: a would-be OPEN fence that
+            // missed the production and silently became prose (§3 requires braced
+            // attributes; `=== embed src=#a` is the classic miss).
+            const like = FENCE_LIKE.exec(para[k]);
+            if (like && REGISTERED_TYPES.has(like[1])) {
+                diags.push({
+                    severity: "warning", code: "fence-like-line", line: paraStart + k,
+                    message: `line looks like an open fence for \`${like[1]}\` but is not one — attributes must be braced (\`=== ${like[1]} {…}\`); the line reads as plain paragraph text`,
+                });
+            }
+        }
         const text = interpolate(para.join("\n"), paraStart, ctx);
         blocks.push({ kind: "paragraph", text, inlines: parseInline(text, paraStart, ctx) });
     }
@@ -554,6 +739,11 @@ function chartSourceTable(ctx, opts, block, target, line) {
         format: typeof block.attrs["format-data"] === "string" ? block.attrs["format-data"] : inferDataFormat(target),
         header: block.attrs["header"] === undefined ? true : block.attrs["header"],
     };
+    // A chart reading a `;`-delimited export needs the same delimiter override a
+    // table does; the table rules validate it (§6).
+    const delim = block.attrs["delim"];
+    if (delim !== undefined)
+        attrs["delim"] = delim;
     const { model, diagnostics } = parseTable(normalizeSource(text).split("\n"), attrs, line, ctx);
     for (const d of diagnostics)
         ctx.diags.push({ ...d, line });
@@ -734,6 +924,111 @@ function relDirPath(p) {
     const i = p.lastIndexOf("/");
     return i < 0 ? "" : p.slice(0, i);
 }
+// A chain that cannot reach an entity block. Carries the diagnostic code it
+// corresponds to (§3) so the message can name it without inventing a new one.
+class ViewError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+// Walking a chain is DOCUMENT-DRIVEN file access: `src=` comes from file
+// content, so without a confinement root a document could name any path on the
+// machine. And never a URL — `geml get` is a read command that agents and
+// editors call constantly, so letting content steer it at the network would turn
+// it into an SSRF entry point (§3.1). Both refusals reuse existing codes (§3).
+function readConfined(rel, root) {
+    if (!/\.geml$/i.test(rel)) {
+        throw new ViewError("embed-target-not-geml", `embed-target-not-geml: \`${rel}\` is not a \`.geml\` document`);
+    }
+    const base = resolvePath(root);
+    const abs = resolvePath(root, rel);
+    if (abs !== base && !abs.startsWith(base + sep)) {
+        throw new ViewError("unresolvable-document", `unresolvable-document: \`${rel}\` lies outside the confinement root \`${root}\``);
+    }
+    try {
+        return readFileSync(abs, "utf8");
+    }
+    catch {
+        throw new ViewError("unresolvable-document", `unresolvable-document: cannot resolve \`${rel}\``);
+    }
+}
+// One hop: read the target document and select what the fragment names. Several
+// units come back when the fragment names a section (§4.3).
+function oneHop(file, src, root) {
+    const hash = src.indexOf("#");
+    const docPath = hash < 0 ? src : src.slice(0, hash);
+    const frag = hash < 0 ? undefined : src.slice(hash + 1);
+    // Check the scheme on what the DOCUMENT wrote, before composition: a URL can
+    // only arrive through `src=`, never from joining relative paths — and testing
+    // the composed path instead would read a Windows drive letter (`C:/…`) as a
+    // scheme and refuse every absolute path, which is exactly what the MCP layer
+    // hands the CLI.
+    if (schemeOf(docPath) !== null) {
+        throw new ViewError("unchecked-cross-document-reference", `unchecked-cross-document-reference: \`${docPath}\` is not local; \`--view\` never fetches over the network`);
+    }
+    const rel = relJoinPath(relDirPath(file), docPath);
+    const text = readConfined(rel, root);
+    if (frag === undefined) {
+        // `src=other.geml`: the frame looks onto the WHOLE document. Every block
+        // comes from the same target, so the resolution base stays uniform — unlike
+        // a host-side section selector, where splicing would mix two documents.
+        // `meta` is frontmatter, not content (render.ts's selectEmbed).
+        //
+        // Only TOP-LEVEL units: a heading's unit spans its whole section, so taking
+        // every addressed unit would emit the blocks inside a section twice.
+        const every = addressedUnits(text).map((a) => a.unit);
+        const top = every.filter((u) => !every.some((o) => o !== u && o.span.start <= u.span.start && o.span.end >= u.span.end
+            && (o.span.start < u.span.start || o.span.end > u.span.end)));
+        return { doc: rel, text, units: top.filter((u) => !(u.kind === "block" && u.type === "meta")), all: [], from: shownPath(rel, root) };
+    }
+    const { units, all } = selectUnits(text, rel, `#${frag}`, rel);
+    return { doc: rel, text, units, all, from: `${shownPath(rel, root)}#${frag}` };
+}
+// Provenance is stated relative to the confinement root, not as the path the
+// walk happens to have composed. The MCP layer hands the CLI an ABSOLUTE path,
+// so without this `from` would be `C:/Users/…/part.geml#tip` — leaking the
+// server's layout, and not a path any caller could pass back in.
+function shownPath(rel, root) {
+    const r = relative(root, rel).replace(/\\/g, "/");
+    return r === "" ? rel : r;
+}
+function viewResolve(source, file, unit, root, depth = 0, seen = new Set()) {
+    const src = unit.kind === "block" && unit.type === "embed" ? embedSrcOf(source, unit) : undefined;
+    if (src === undefined)
+        return [{ doc: file, text: source, unit, all: [], from: "" }];
+    // The renderer expands no deeper either (EMBED_DEPTH_LIMIT), but where the
+    // cycle detector may stop SILENTLY — a 9-deep chain is legal and simply is
+    // not expanded — `--view` may not: stopping here means what we are holding is
+    // still a frame, and returning it would break the contract silently.
+    if (depth >= EMBED_DEPTH_LIMIT) {
+        throw new ViewError("depth", `chain still not on an entity block after ${EMBED_DEPTH_LIMIT} hops (the renderer expands no deeper either)`);
+    }
+    const hop = oneHop(file, src, root);
+    // Same key shape as the check's cycle detector: a document plus what was
+    // selected in it.
+    const key = `${hop.doc}#${hop.units.map((u) => u.id ?? "").join(",")}`;
+    if (seen.has(key)) {
+        throw new ViewError("transclusion-cycle", `transclusion-cycle: \`${hop.from}\` is already being expanded in this chain`);
+    }
+    const nextSeen = new Set(seen).add(key);
+    // Per-unit application, recursively: what a frame looks onto may itself be a
+    // frame, and a section may hold a mix (§4.3).
+    return hop.units.flatMap((u) => viewResolve(hop.text, hop.doc, u, root, depth + 1, nextSeen)
+        // An inner identity step has no provenance of its own, so carry this hop's:
+        // `from` must always name where the bytes actually came from.
+        .map((r) => (r.from === "" ? { ...r, from: hop.from } : r)));
+}
+// The `src=` of an embed unit, read off its head line: a Unit carries the span,
+// not parsed attributes.
+function embedSrcOf(source, unit) {
+    const braces = /\{[^}]*\}/.exec(sliceUnit(source, unit.span, true, false));
+    if (!braces)
+        return undefined;
+    const v = parseAttrs(braces[0]).attrs["src"];
+    return typeof v === "string" ? v : undefined;
+}
 function gatherEmbeds(source) {
     const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map(), embeds: [] };
     scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
@@ -750,6 +1045,11 @@ function tableFromDocument(source, id) {
     const found = ctx.tables?.get(id);
     if (found !== undefined)
         return found;
+    // GEP-0005: a remote `data` block is the other chart-source form; its value
+    // is projected by the CALLER (recordsToTable needs the chart's attributes).
+    const dv = ctx.dataValues?.get(id);
+    if (dv !== undefined)
+        return { records: dv };
     const anyBlock = (function find(bs) {
         for (const b of bs) {
             if ((b.kind === "block" || b.kind === "heading") && b.id === id)
@@ -846,7 +1146,11 @@ function resolveTableSources(ctx, opts) {
                 err(line, "unresolved-cross-document-reference", `unresolved reference \`${target}\``);
                 continue;
             }
-            if (remote === "not-a-table") {
+            // A table's `src=` names a TABLE. A `data` block is a chart-source form
+            // (§7.1, GEP-0005), not a table-source form — the column algebra a
+            // borrowing table implies (compute/summary against named columns) has
+            // no defined meaning over a value tree.
+            if (remote === "not-a-table" || "records" in remote) {
                 err(line, "table-source-not-a-table", `table source \`${target}\` is not a table`);
                 continue;
             }
@@ -922,6 +1226,213 @@ function validateRefs(ctx, opts) {
         }
     }
 }
+// `src=` on a `code` block: the route to the code the block shows,
+// `<path>[#L<start>[-<end>]]` (1-based, inclusive). The code-graph runtime has
+// always fetched and sliced this at render time; resolving it here is what
+// turns a range that no longer exists — the source moved or shrank — from a
+// silently empty panel into a build error. There is no extension gate (code is
+// any language); the safety rule is the resolver's confinement to the document
+// tree, widened only by `--root`.
+const SOURCE_RANGE = /^L(\d+)(?:-(\d+))?$/;
+// One route syntax for the two types whose `src=` fragment position is free —
+// `code` and `data`. (A table's is already taken: `src=doc.geml#id` names a
+// block.) `<path>[#L<start>[-<end>]]`, 1-based and inclusive; `to === 0` means
+// "through end of file". Returns null after reporting, so callers just skip.
+function parseSourceRoute(target, kind, line, ctx) {
+    const hash = target.indexOf("#");
+    const path = hash < 0 ? target : target.slice(0, hash);
+    const frag = hash < 0 ? "" : target.slice(hash + 1);
+    if (frag === "")
+        return { path, from: 1, to: 0 };
+    const m = SOURCE_RANGE.exec(frag);
+    if (!m) {
+        ctx.diags.push({ severity: "error", code: "bad-source-range", message: `${kind} source \`${target}\`: unrecognised fragment (expected \`#L<start>\` or \`#L<start>-<end>\`)`, line });
+        return null;
+    }
+    const from = Number(m[1]);
+    const to = m[2] === undefined ? from : Number(m[2]);
+    if (from < 1 || to < from) {
+        ctx.diags.push({ severity: "error", code: "bad-source-range", message: `${kind} source \`${target}\`: line range is empty or starts before line 1`, line });
+        return null;
+    }
+    return { path, from, to };
+}
+// Slice a resolved file to a route's range, or report that the range no longer
+// exists — the signal a stale reference exists at all.
+function sliceSourceRange(text, route, target, kind, line, ctx) {
+    const all = normalizeSource(text).split("\n");
+    // A trailing newline yields a final empty element; it is not a line.
+    if (all.length > 0 && all[all.length - 1] === "")
+        all.pop();
+    if (route.to > all.length) {
+        ctx.diags.push({ severity: "error", code: "bad-source-range", message: `${kind} source \`${target}\`: the file has ${all.length} line(s), so lines ${route.from}-${route.to} no longer exist — the range is stale`, line });
+        return null;
+    }
+    return all.slice(route.from - 1, route.to === 0 ? all.length : route.to);
+}
+function resolveCodeSources(ctx, opts) {
+    for (const { block, line, target } of ctx.codeSources ?? []) {
+        const scheme = schemeOf(target);
+        // A remote source is fetched by the RENDERER (§9.4), as for a table.
+        if (scheme === "http" || scheme === "https")
+            continue;
+        if (scheme !== null) {
+            ctx.diags.push({ severity: "error", code: "bad-code-source", message: `code source \`${target}\` names a disallowed URL scheme`, line });
+            continue;
+        }
+        const route = parseSourceRoute(target, "code", line, ctx);
+        if (route === null)
+            continue;
+        const { path, from, to } = route;
+        if (!opts.resolveDoc) {
+            ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `code source \`${target}\` not checked (no document resolver)`, line });
+            continue;
+        }
+        const text = opts.resolveDoc(path);
+        if (text === null) {
+            // A WARNING, not an error, and the code/value model split is the reason:
+            // a value that cannot be loaded is a promise the document failed to keep
+            // (an error — see `unresolvable-data-source`), while a code region that
+            // cannot be reached right now is still a code region at a location. A
+            // generated code graph read away from its sources — published on its own,
+            // or describing another checkout — must stay valid, exactly as the
+            // render-time runtime degrades to showing the path.
+            ctx.diags.push({ severity: "warning", code: "unresolvable-code-source", message: `cannot resolve code source \`${path}\` — not checked`, line });
+            continue;
+        }
+        const slice = sliceSourceRange(text, { from, to }, target, "code", line, ctx);
+        if (slice === null)
+            continue;
+        const hasBody = (block.raw ?? []).some((l) => l.trim() !== "");
+        if (!hasBody) {
+            block.raw = slice;
+        }
+        else if ((block.raw ?? []).join("\n") !== slice.join("\n")) {
+            // A body alongside `src=` is a cached snapshot, kept for offline reading.
+            // Silence would let the two drift — the very thing the route prevents.
+            ctx.diags.push({ severity: "warning", code: "stale-code-snapshot", message: `code block body differs from its source \`${target}\` — the body is a snapshot and is now out of date`, line });
+        }
+    }
+}
+// GEP-0005: `src=` on a `data` block names external content — the same
+// external-source discipline tables have (§6, §9.4): an http(s) source is
+// fetched by the RENDERER, never the parser (the block defers, and so does a
+// chart over it); any other scheme is refused; the file must look like data
+// (`.json`/`.jsonl`); a missing resolver leaves it unchecked with a warning.
+function resolveDataSources(ctx, opts) {
+    for (const { block, line, target } of ctx.dataSources ?? []) {
+        const defer = () => { if (block.id !== undefined)
+            (ctx.dataSrcPending ??= new Set()).add(block.id); };
+        const scheme = schemeOf(target);
+        if (scheme === "http" || scheme === "https") {
+            defer();
+            continue;
+        }
+        if (scheme !== null) {
+            ctx.diags.push({ severity: "error", code: "unresolvable-data-source", message: `data source \`${target}\` names a disallowed URL scheme`, line });
+            continue;
+        }
+        // The route shares `code`'s syntax (§3.2): a line range MAY narrow the file.
+        const route = parseSourceRoute(target, "data", line, ctx);
+        if (route === null)
+            continue;
+        const { path } = route;
+        // A data source is data — the same shape rule table sources enforce, so
+        // the loader cannot be pointed at a `.env` or a private key.
+        if (!/\.(json|jsonl)$/i.test(path)) {
+            ctx.diags.push({ severity: "error", code: "bad-data-source", message: `data source \`${path}\` is not a \`.json\`/\`.jsonl\` data file`, line });
+            continue;
+        }
+        // Explicit format= wins; otherwise the (already-gated) extension names it.
+        const fmtAttr = block.attrs["format"];
+        const fmt = typeof fmtAttr === "string" ? fmtAttr : /\.jsonl$/i.test(path) ? "jsonl" : "json";
+        // A range narrows the file to lines; what those lines mean is then the
+        // format's business, unchanged. Slicing a `jsonl` log is the obvious use;
+        // slicing a `json` file works whenever the slice is itself a value, and
+        // when it is not, the ordinary data-parse error already names the line.
+        // No extra rule.
+        if (!opts.resolveDoc) {
+            ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `data source \`${target}\` not checked (no document resolver)`, line });
+            defer();
+            continue;
+        }
+        const text = opts.resolveDoc(path);
+        if (text === null) {
+            ctx.diags.push({ severity: "error", code: "unresolvable-data-source", message: `cannot resolve data source \`${path}\``, line });
+            continue;
+        }
+        const lines = sliceSourceRange(text, route, target, "data", line, ctx);
+        if (lines === null)
+            continue;
+        const parsed = parseDataBody(fmt, lines, line);
+        for (const d of parsed.diags)
+            ctx.diags.push(d);
+        if (parsed.value !== undefined) {
+            block.value = parsed.value;
+            if (block.id !== undefined && !ctx.dataValues?.has(block.id)) {
+                (ctx.dataValues ??= new Map()).set(block.id, parsed.value);
+            }
+        }
+    }
+}
+// GEP-0005: a chart's `data=` may target a `data` block whose value is a
+// RECORD ARRAY — a non-empty array of objects. Keys project to columns in
+// first-seen order; every column the chart actually references (x/y/size/
+// series) must be present with a SCALAR value in every record, and a
+// violation is an error naming the first offending record. Columns the chart
+// does not reference may hold anything (nested values project as compact
+// JSON text). The projection feeds the unchanged table machinery.
+function recordsToTable(value, attrs, line, ctx) {
+    const fail = (msg) => {
+        ctx.diags.push({ severity: "error", code: "chart-data-not-records", message: `geml-chart: ${msg}`, line });
+        return null;
+    };
+    if (!Array.isArray(value) || value.length === 0)
+        return fail("data target is not a non-empty record array");
+    const columns = [];
+    for (let i = 0; i < value.length; i++) {
+        const r = value[i];
+        if (r === null || typeof r !== "object" || Array.isArray(r))
+            return fail(`record ${i + 1} is not an object`);
+        for (const k of Object.keys(r))
+            if (!columns.includes(k))
+                columns.push(k);
+    }
+    // Only the channels this chart TYPE reads are "referenced" (§7.1): a stray
+    // size= on a bar chart is buildChart's chart-unused-channel WARNING, and the
+    // projection must not turn it into an error a table source would not raise.
+    // An unknown/missing type validates x/y only; buildChart reports the type.
+    const typeAttr = String(attrs["type"] ?? "");
+    const uses = USES[typeAttr] ?? new Set(["x", "y"]);
+    const channels = [];
+    for (const c of ["x", "y", "size", "series"]) {
+        if (!uses.has(c))
+            continue;
+        const v = attrs[c];
+        if (typeof v === "string")
+            for (const name of v.split(",").map((s) => s.trim()).filter(Boolean))
+                channels.push(name);
+    }
+    for (const col of channels) {
+        for (let i = 0; i < value.length; i++) {
+            const v = value[i][col];
+            if (v === undefined || v === null || typeof v === "object") {
+                return fail(`column \`${col}\` is missing or non-scalar in record ${i + 1}`);
+            }
+        }
+    }
+    const rows = value.map((r) => columns.map((c) => {
+        const v = r[c];
+        const text = v === undefined ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+        // Data, not prose: cells carry plain-text inlines, never inline-parsed —
+        // the same treatment `format=csv` cells get (a `*` in a value is a `*`).
+        const cell = { text, inlines: text === "" ? [] : [{ type: "text", value: text }] };
+        if (typeof v === "number" && Number.isFinite(v))
+            cell.value = v;
+        return cell;
+    }));
+    return { header: true, columns, align: columns.map(() => undefined), rows };
+}
 // §7: resolve every geml-chart against its referenced table. Runs after the
 // scan so that `data=#id` may point at a table defined anywhere in the doc.
 function resolveCharts(ctx, opts) {
@@ -941,6 +1452,21 @@ function resolveCharts(ctx, opts) {
         let table;
         if (docPath === "") {
             table = ctx.tables?.get(id);
+            if (!table && ctx.dataValues?.has(id)) {
+                // GEP-0005: the target is a `data` block. A RECORD ARRAY projects to
+                // the table model (keys -> columns) and feeds the unchanged chart
+                // machinery, so column checks and rendering stay single-sourced.
+                const projected = recordsToTable(ctx.dataValues.get(id), block.attrs, line, ctx);
+                if (projected === null)
+                    continue; // reported by the projection
+                table = projected;
+            }
+            if (!table && ctx.dataSrcPending?.has(id)) {
+                // GEP-0005: the target is a `data` block whose `src=` is render-time
+                // (http, or no resolver) — defer exactly like a src table with no
+                // columns; the renderer checks it when the data actually arrives.
+                continue;
+            }
             if (!table) {
                 // A chart is a view of a table, and a data file is one of the three ways
                 // §6 lets a table name its content. So `data=rows.csv` desugars: it is an
@@ -954,8 +1480,36 @@ function resolveCharts(ctx, opts) {
                         continue; // already reported by the table rules
                     table = sugar;
                 }
+                else if (hash < 0 && /\.(json|jsonl)$/i.test(id) && schemeOf(id) === null) {
+                    // GEP-0005 sugar, the json/jsonl twin of the csv path: an anonymous
+                    // LOCAL data source projected through the record-array rules. A
+                    // remote URL needs a NAMED `data` block with `src=` — its fetch is
+                    // render-time, and an anonymous source has no block to defer on.
+                    if (!opts.resolveDoc) {
+                        ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `geml-chart: data source \`${id}\` not checked (no document resolver)`, line });
+                        continue;
+                    }
+                    const text = opts.resolveDoc(id);
+                    if (text === null) {
+                        ctx.diags.push({ severity: "error", code: "unresolvable-data-source", message: `geml-chart: cannot resolve data source \`${id}\``, line });
+                        continue;
+                    }
+                    const parsed = parseDataBody(/\.jsonl$/i.test(id) ? "jsonl" : "json", normalizeSource(text).split("\n"), line);
+                    for (const d of parsed.diags)
+                        ctx.diags.push(d);
+                    if (parsed.value === undefined)
+                        continue;
+                    const projected = recordsToTable(parsed.value, block.attrs, line, ctx);
+                    if (projected === null)
+                        continue; // reported by the projection
+                    table = projected;
+                }
+                else if (hash < 0 && /\.(json|jsonl)$/i.test(id)) {
+                    ctx.diags.push({ severity: "error", code: "bad-data-source", message: `geml-chart: \`data=${id}\`: a remote json/jsonl source needs a named \`data\` block with \`src=\``, line });
+                    continue;
+                }
                 else if (hash < 0 && /\.[a-z0-9]+$/i.test(id)) {
-                    ctx.diags.push({ severity: "error", code: "unresolvable-table-source", message: `geml-chart: \`data=${id}\` is not a \`.csv\`/\`.tsv\` data file, and not a \`#id\` naming a table`, line });
+                    ctx.diags.push({ severity: "error", code: "unresolvable-table-source", message: `geml-chart: \`data=${id}\` is not a \`.csv\`/\`.tsv\`/\`.json\`/\`.jsonl\` data file, and not a \`#id\` naming a table or data block`, line });
                     continue;
                 }
                 else {
@@ -983,10 +1537,18 @@ function resolveCharts(ctx, opts) {
                 continue;
             }
             if (remote === "not-a-table") {
-                ctx.diags.push({ severity: "error", code: "chart-data-not-a-table", message: `geml-chart: data target \`${ref}\` is not a table`, line });
+                ctx.diags.push({ severity: "error", code: "chart-data-not-a-table", message: `geml-chart: data target \`${ref}\` is neither a table nor a data block`, line });
                 continue;
             }
-            table = remote;
+            if ("records" in remote) {
+                const projected = recordsToTable(remote.records, block.attrs, line, ctx);
+                if (projected === null)
+                    continue; // reported by the projection
+                table = projected;
+            }
+            else {
+                table = remote;
+            }
         }
         if (table.src !== undefined && table.columns.length === 0) {
             // §6: the table names a source whose data did not arrive at build time — a
@@ -1011,6 +1573,8 @@ export function parse(source, opts = {}) {
     // Table sources first: a chart reads the build-time model of the table it
     // charts, so that model has to be filled before charts are resolved.
     resolveTableSources(ctx, opts);
+    resolveDataSources(ctx, opts);
+    resolveCodeSources(ctx, opts);
     resolveCharts(ctx, opts);
     validateRefs(ctx, opts);
     detectTransclusionCycles(ctx, opts);
@@ -1077,9 +1641,12 @@ function sectionEnd(lines, i, level) {
 // `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, ctx, depth = 0, 
-// Optional second index: every typed block by TYPE, id-bearing or not, so a
-// block the author never named is still addressable (`=== meta`).
-types) {
+// Optional second index: every addressable unit in document order — typed
+// blocks (id-bearing or not, so a block the author never named is still
+// addressable), headings, footnote definitions. A second SINK on the one
+// walk, not a second walk: the selector design's "one definition, one
+// implementation" applies to the scan as much as to the syntax.
+units) {
     const add = (id, start, end) => {
         if (!out.has(id))
             out.set(id, { start, end });
@@ -1094,6 +1661,7 @@ types) {
         const fndef = /^\[\^([^\]]+)\]:[ \t]?(.*)$/.exec(line);
         if (fndef) {
             add(fndef[1].trim(), base + i, base + i + 1);
+            units?.push({ span: { start: base + i, end: base + i + 1 }, kind: "footnote", id: fndef[1].trim() });
             i++;
             continue;
         }
@@ -1108,16 +1676,12 @@ types) {
             const { end, closed } = fenceClose(lines, i, open);
             if (id !== undefined)
                 add(id, base + i, base + end);
-            if (types) {
-                const list = types.get(type) ?? [];
-                list.push({ span: { start: base + i, end: base + end }, id });
-                types.set(type, list);
-            }
+            units?.push({ span: { start: base + i, end: base + end }, kind: "block", type, ...(id !== undefined ? { id } : {}) });
             // 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" && depth < MAX_NESTING) {
-                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1, types);
+                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1, units);
             }
             i = end;
             continue;
@@ -1128,7 +1692,10 @@ types) {
             // 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));
+            const hid = idOfHeading(h[3], h[2], base + i + 1, ctx);
+            const hend = base + sectionEnd(lines, i, h[1].length);
+            add(hid, base + i, hend);
+            units?.push({ span: { start: base + i, end: hend }, kind: "heading", id: hid, level: h[1].length, text: h[2] });
             i++;
             continue;
         }
@@ -1146,12 +1713,23 @@ export function blockSpans(source) {
     collectSpans(lines, 0, out, ctx);
     return out;
 }
-function blockTypeSpans(source) {
+// Every addressable unit, in document order, each decorated with its content
+// address (§3.2). Ids are OPTIONAL in GEML (§1: a block MAY carry one), so
+// `meta`, a callout `note`, a `table` — anything the author had no reason to
+// name — has no id to address it by; this index is what makes those addressable
+// anyway, by type (`=== meta`) or by content (`@<hex>`). No block type is
+// special-cased; meta is merely the one that is usually unique.
+//
+// The ONE index selector matching and the listing both work from, so `get`,
+// `set` and the listing can never disagree about what exists.
+function addressedUnits(source) {
     const lines = normalizeSource(source).split("\n");
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
-    const types = new Map();
-    collectSpans(lines, 0, new Map(), ctx, 0, types);
-    return types;
+    const units = [];
+    collectSpans(lines, 0, new Map(), ctx, 0, units);
+    // The address hashes the block's own source text — the exact bytes `get`
+    // would print for it — so an address can be recomputed from `get` output.
+    return addressUnits(units, (u) => lines.slice(u.span.start, u.span.end).join("\n"));
 }
 // Split into physical lines while *keeping* each line's terminator, so
 // join("") is byte-exact and slicing by span never rewrites line endings.
@@ -1186,6 +1764,32 @@ function toNewline(text, nl) {
 function narrowToHead(span) {
     return { start: span.start, end: span.start + 1 };
 }
+// The unit's CLOSING fence line, or null when it has none — a heading section,
+// or a fence left unclosed at EOF. Extracted so `get --body` and `set --body`
+// decide it in ONE place: the selector design's §4 defines HEAD/BODY by the
+// round-trip invariant `get X --body | set X --body` leaving the file
+// byte-identical, and two copies of this judgement is exactly how that breaks.
+function closeFenceLine(lines, span) {
+    const open = FENCE_OPEN.exec(stripEol(lines[span.start] ?? ""));
+    if (!open)
+        return null;
+    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);
+    return isCloseFence(lastText, open[1].length) || labeled ? lines[span.end - 1] ?? "" : null;
+}
+// BODY span: a fenced block's lines BETWEEN the fences; a heading's lines after
+// the heading through the section boundary — trailing blank lines included,
+// because that is the span `set --body` replaces (§4's table).
+function narrowToBody(lines, span) {
+    return { start: span.start + 1, end: closeFenceLine(lines, span) !== null ? span.end - 1 : span.end };
+}
+// Slice one unit's output bytes, honouring --head / --body.
+function sliceUnit(source, span, headOnly, bodyOnly) {
+    const lines = splitLines(source);
+    const s = headOnly ? narrowToHead(span) : bodyOnly ? narrowToBody(lines, span) : span;
+    return lines.slice(s.start, s.end).join("");
+}
 // 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.
 // Returns the containing sibling array and index, not just the node: the model
@@ -1238,13 +1842,9 @@ function flag(args, name) {
 function historyPathFor(geml) {
     return geml.replace(/\.geml$/, "") + ".gemlhistory";
 }
-function parseStamp(s) {
-    const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(s);
-    if (!m)
-        throw new Error(`bad --at timestamp: ${s} (want YYYYMMDDTHHMMSSZ)`);
-    const [, y, mo, d, h, mi, se] = m;
-    return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
-}
+// (A `YYYYMMDDTHHMMSSZ` parser lived here for `history commit --at`. That flag
+// left the CLI with design §9-Q4 — the library API takes a real Date — so the parser
+// went with it rather than staying as an uncalled branch.)
 const VERSION = "1.0"; // GEML spec version this CLI targets
 // The published version, read from package.json rather than restated here.
 // "Keep in sync with package.json" was a comment, and comments do not run: this
@@ -1272,96 +1872,124 @@ export const PARSER_VERSION = (() => {
     }
     return "0.0.0";
 })();
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
-                                             (--root widens cross-doc resolution to dir d, as on check — an
-                                              === embed whose target sits above the file's own directory
-                                              needs it, or it renders unresolved)
-                                             --to  <output>: json | html | md | geml
-                                               --to md    -> Markdown (lossy)
-                                               --to html  -> self-contained HTML
-                                               --to 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> [...]       code-graph toolkit (alias: codegraph)
-  geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
-                                             (10 tools, each geml_ + its CLI verb: list/get/check/history/to +
-                                              set/add/delete/rename/revert; every write is validated before it
-                                              reaches disk. A code graph under --root adds four read-only
-                                              geml_codemap_* tools to the same server)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Mutations (set/add/delete/rename) write the whole updated document in place for a
-file, or to stdout for '-' input; -o redirects it (-o - = stdout).
-Exit codes:
-  0 ok
-  1 document/operation error
-  2 command usage error.
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
+                                             (--root widens cross-doc resolution to dir d, as on check — an
+                                              === embed whose target sits above the file's own directory
+                                              needs it, or it renders unresolved)
+                                             --to  <output>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --to html --fragment -> body-only markup, no page shell
+                                                            (embed in your own layout; assets via pageAssets)
+                                               --to geml  -> canonical re-format
+                                               --to json  -> document-model JSON (default)
+                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
+                                               geml notes.md                -> GEML   (md inferred from extension)
+                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
+                                               geml - --from md             read Markdown on stdin
+  geml 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 <save|get|restore|verify> <file.geml> [...]   .gemlhistory version sidecar
+                                             (save = append the file as a revision · get = list revisions, or
+                                              print one · restore = overwrite the file with one · verify = rebuild
+                                              and re-hash the whole chain)
+  geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
+  geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
+                                             (10 tools, each geml_ + its CLI command path: list/get/check/history/to +
+                                              set/add/delete/rename/revert; every write is validated before it
+                                              reaches disk. A code graph under --root adds four read-only
+                                              geml_codemap_* tools to the same server)
+  geml skill  install [--dest <dir>] [--no-global] [--no-mcp]   set up GEML for Claude Code, user-global
+                                             (authoring skill -> ~/.claude/skills/geml, CLI -> npm i -g,
+                                              MCP server registered at user scope; touches no settings.json,
+                                              installs no hooks; idempotent — re-run to update)
+  geml --help | --version [--json]
+
+Use '-' as the file to read from stdin.
+Mutations (set/add/delete/rename) write the whole updated document in place for a
+file, or to stdout for '-' input; -o redirects it (-o - = stdout).
+Exit codes:
+  0 ok
+  1 document/operation error
+  2 command usage error.
 `;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
 const SUBHELP = {
-    get: "usage: geml get <file.geml|-> [#id | '## Heading' | '=== type'] [--json] [--head]  (selector: an #id, or a LINE copied from the document — a heading `## Title` addresses its whole section, a fence `=== meta` addresses that block by type and lists the candidates when several match; --head = the head line; without a selector: 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)",
+    get: "usage: geml get <file.geml|-> [<selector>] [--head|--body] [--view [--root <dir>]] [--json]  (selector = a filter over blocks: #id | '## Heading' (its whole section) | '=== type' (every block of that type — N matches print N contents, count on stderr) | '=== type@<hex>[~n]' or '@<hex>[~n]' (content address, for blocks with no #id); --head = head line, --body = body; --view = read THROUGH an `embed` to the entity block it stands for, following a chain to its end (the identity on any other block, and on a section selector — it never splices two documents' bytes together); provenance goes to stderr as `view: <sel> -> <doc>[#<id>]`; read-only, `set` refuses it; chain reads are confined to --root (default: the document's own directory) and never fetched over the network; without a selector: list every addressable block with its shortest unique address, --json = array)",
+    set: "usage: geml set <file.geml|-> <selector> [--head|--body] [--in F | --in F#src | --in -] [-o out.geml]  (selector as in `get`, but it must match exactly ONE block — '=== type' matching several is refused; 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 when the target has one — --body = body; guarded splice, refused if it breaks the doc; writing through an @<hex> address prints the new address on stderr)",
     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>] [--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)
+    history: `usage: geml history save    <file.geml> [-m <msg>]      append the working file as a new revision (identical to the tip = no-op)
+       geml history get     <file.geml> [<rev>] [--json]   NO <rev>: every revision, newest first, first column = the selector; WITH <rev>: that revision's full text
+       geml history restore <file.geml> <rev> [--force]    overwrite the working file with a revision (--force discards unsaved changes)
+       geml history verify  <file.geml>                    rebuild and re-hash every revision in the chain
+       (<rev>: 0 = the tip | -N = N revisions back | an unambiguous revision id — the strings 'get' prints.
+        All four take --history <path> to point at a sidecar other than <file>.gemlhistory.)`,
+    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
+       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
+       geml codemap verify [dir]                 geml check + profile reference checks
+       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
+       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
+       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
+       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
-    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
-
-  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
-  Every tool is geml_ + its CLI verb, so the terminal and the assistant share
-  one vocabulary.
-  Ten tools: geml_list · geml_get · geml_check · geml_history · geml_to
-             geml_set · geml_add · geml_delete · geml_rename · geml_revert
-  With a code graph under --root, four more (read-only), so one client entry
-  covers both: geml_codemap_search · geml_codemap_callchain
-               geml_codemap_list · geml_codemap_node
-
-  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
-                      client names is confined here; a client cannot widen it.
-  --graph <dir>       Code-graph directory, inside --root. Defaults to
-                      <root>/.geml-code-graph when it holds an index.geml; with
-                      no graph the four graph tools are not served at all.
-  --no-history        Skip the .gemlhistory commit taken before each write
-                      (default: commit, so geml_revert always has a revision to
-                      undo to).
-
-  Register with a client:
+    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Every tool is geml_ + its CLI COMMAND PATH, so the terminal and the assistant
+  share one vocabulary — geml_history mirrors the "geml history" command group,
+  whose read verb (get) is the only one of the four served here.
+  Ten tools: geml_list · geml_get · geml_check · geml_history · geml_to
+             geml_set · geml_add · geml_delete · geml_rename · geml_revert
+  With a code graph under --root, four more (read-only), so one client entry
+  covers both: geml_codemap_search · geml_codemap_callchain
+               geml_codemap_list · geml_codemap_node
+
+  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
+                      client names is confined here; a client cannot widen it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when it holds an index.geml; with
+                      no graph the four graph tools are not served at all.
+  --no-history        Skip the .gemlhistory revision saved before each write
+                      (default: save one, so geml_revert always has a revision
+                      to undo to).
+
+  Register with a client:
     claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
+    skill: `usage: geml skill install [--dest <skillsDir>] [--no-global] [--no-mcp]
+
+  One command, three things, all user-global — so any Claude Code session can
+  author, validate, and blockwise-edit GEML:
+    1. the authoring skill -> <skillsDir>/geml   (default ~/.claude/skills/geml)
+    2. the geml CLI        -> npm i -g @geml/geml   (skipped when already on PATH)
+    3. the MCP server      -> claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .
+  Touches no settings.json and installs no hooks. Idempotent — re-run after an
+  upgrade to refresh the skill text alongside the CLI it teaches.
+
+  --dest <dir>   install the skill under <dir> instead of ~/.claude/skills
+  --no-global    skip the global npm install
+  --no-mcp       skip the MCP server registration`,
 };
 // 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.
@@ -1440,7 +2068,19 @@ function resolverFor(file, root) {
             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);
+        let targetAbs = resolvePath(dirAbs, d);
+        // A SOURCE route (`code`/`data` `src=`) may instead be written relative to
+        // the resolution root — that is how the code-graph profile writes them
+        // (`geml-parser/src/attrs.ts` from a document two levels down). So when
+        // the document-relative path does not exist and a root was named, try the
+        // root as the base. Only a widened `--root` can enable this, and both
+        // confinement gates below still apply, so it cannot reach further than a
+        // document-relative reference already could.
+        if (baseAbs !== dirAbs && !existsSync(targetAbs)) {
+            const fromBase = resolvePath(baseAbs, d);
+            if (existsSync(fromBase))
+                targetAbs = fromBase;
+        }
         // Cheap lexical gate: reject an obvious `..`/absolute/other-drive escape
         // before touching the filesystem.
         if (outside(baseAbs, targetAbs))
@@ -1510,23 +2150,130 @@ function historyError(e, file, historyPath) {
     }
     return err?.message ?? String(e);
 }
+// Subcommand, file and revision, read positionally around the options —
+// `--history <path>` and `-m <msg>` may sit anywhere, and the old args[0..2]
+// indexing read `--history` itself as the file.
+//
+// The generic `positionals()` cannot be reused: it drops every `-`-leading token,
+// and a revision selector `-N` LOOKS exactly like a flag. That is the whole point
+// of the first column `history get` prints, so `-N` is admitted and every other
+// `-`-leading token is treated as an option.
+function historyPositionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--history" || a === "-m" || a === "--message") {
+            i++;
+            continue;
+        } // flag AND its value
+        if (a.startsWith("-") && !/^-\d+$/.test(a))
+            continue; // --json, --force, …
+        out.push(a);
+    }
+    return out;
+}
 function runHistory(args) {
-    const sub = args[0];
-    const file = args[1];
+    const [sub, file, rev, ...extra] = historyPositionals(args);
     if (!sub || !file)
         fail(SUBHELP.history);
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
+    const json = args.includes("--json");
     try {
-        if (sub === "commit") {
-            const at = flag(args, "--at");
-            const r = commit({
+        if (sub === "save") {
+            // design §3.1/§9-Q4: `--author` and `--at` were withdrawn from the CLI (nothing
+            // outside tests ever passed either). Refusing beats ignoring for the same
+            // reason the retired verbs above refuse: a silently dropped `--author
+            // alice` discards precisely the value the caller went out of their way to
+            // type. Both stay on the library API (save({ author, at })).
+            for (const gone of ["--author", "--at"]) {
+                if (args.some((a) => a === gone || a.startsWith(`${gone}=`))) {
+                    fail(`${gone} is no longer accepted by 'geml history save' — the only option is -m/--message. (Both remain on the library API, save({ author, at }), for embedders and for tests that pin a revision id.)`);
+                }
+            }
+            // design §3.1: an empty save is a NO-OP. `save` is the one non-idempotent verb,
+            // so an agent retrying a save it is unsure landed must not lengthen the
+            // chain by a revision with no ops. `geml mcp` already gated its
+            // pre-write snapshot on this exact predicate (mcp.ts snapshot()); this is
+            // the same `isCurrent()`, not a second hash comparison.
+            if (existsSync(historyPath) && isCurrent(historyPath, file)) {
+                console.log(`already saved as ${listRevisions(historyPath)[0].id} (no changes)`);
+                return;
+            }
+            const r = save({
                 gemlPath: file,
                 historyPath,
                 summary: flag(args, "-m") ?? flag(args, "--message") ?? "",
-                author: flag(args, "--author"),
-                at: at ? parseStamp(at) : undefined,
             });
-            console.log(`committed ${r.id}`);
+            console.log(`saved ${r.id}`);
+        }
+        else if (sub === "get") {
+            // Three tiers, split by how many addresses were given — the same rule the
+            // top-level `geml get` follows (design §1.2). Tier 2 takes a BLOCK
+            // selector inside the revision and reuses the top-level grammar verbatim
+            // (§10.1): a revision rebuilt is just a document's text, so there is no
+            // new algorithm here, and the two selector namespaces cannot collide —
+            // position is fixed and the lexis does not overlap (§10.2).
+            if (extra.length > 1) {
+                fail(`history get takes ONE revision selector and ONE block selector; got ${extra.length + 1} positionals after the file`, 2);
+            }
+            if (rev === undefined) {
+                // Newest-first, with each row's selector in the first column (`0` for
+                // the tip, then `-1`, `-2`, …) so the output is copy-paste into `get`,
+                // `restore` and `revert --rev` alike.
+                const revs = listRevisions(historyPath);
+                if (json) {
+                    console.log(JSON.stringify(revs, null, 2));
+                }
+                else {
+                    for (const r of revs) {
+                        const sel = r.current ? "0" : `-${r.offset}`;
+                        console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
+                    }
+                }
+            }
+            else {
+                // resolveContent() routes through the ONE selector grammar
+                // (resolveRevision) that the list above prints — see its comment for
+                // what happened the last time that was written twice.
+                const { id, text } = resolveContent(historyPath, rev);
+                const blockSel = extra[0];
+                if (blockSel === undefined) {
+                    if (json)
+                        console.log(JSON.stringify({ id, text }, null, 2));
+                    else
+                        process.stdout.write(text);
+                }
+                else {
+                    // Tier 2 (§10.1). Cardinality and the flag rules are the top-level
+                    // ones, checked here because this tier has its own argument list.
+                    const headOnly = args.includes("--head");
+                    const bodyOnly = args.includes("--body");
+                    if (headOnly && bodyOnly)
+                        fail("--head and --body are mutually exclusive", 2);
+                    if (json && (headOnly || bodyOnly)) {
+                        fail(`--json cannot be combined with ${headOnly ? "--head" : "--body"} — --json returns the model node, which has no sub-node for one part of a block`, 2);
+                    }
+                    const { units, all } = selectUnits(text, file, blockSel, `revision ${id}`);
+                    if (json) {
+                        // §3.2's tier table: the revision id travels with the block, so the
+                        // caller can tell WHICH version it is holding.
+                        const nodes = units.map((u) => unitNode(text, file, u, all));
+                        console.log(JSON.stringify({ id, block: units.length === 1 ? nodes[0] : nodes }, null, 2));
+                    }
+                    else {
+                        if (units.length > 1)
+                            reportMatches(units[0].type ?? "", units);
+                        for (const u of units)
+                            process.stdout.write(sliceUnit(text, u.span, headOnly, bodyOnly));
+                    }
+                }
+            }
+        }
+        else if (sub === "restore") {
+            if (!rev)
+                fail("usage: geml history restore <file.geml> <revision> [--force]");
+            restore({ historyPath, gemlPath: file, revision: rev, write: true, force: args.includes("--force") });
+            console.log(`restored ${file} to ${rev}`);
         }
         else if (sub === "verify") {
             const res = verify(historyPath, file);
@@ -1538,27 +2285,6 @@ function runHistory(args) {
             if (!res.ok)
                 process.exit(1);
         }
-        else if (sub === "show") {
-            const rev = args[2];
-            if (!rev)
-                fail("usage: geml history show <file.geml> <revision>");
-            process.stdout.write(restore({ historyPath, gemlPath: file, revision: rev }));
-        }
-        else if (sub === "restore") {
-            const rev = args[2];
-            if (!rev)
-                fail("usage: geml history restore <file.geml> <revision> [--force]");
-            restore({ historyPath, gemlPath: file, revision: rev, write: true, force: args.includes("--force") });
-            console.log(`restored ${file} to ${rev}`);
-        }
-        else if (sub === "log") {
-            // 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 ? "0" : `-${r.offset}`;
-                console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
-            }
-        }
         else {
             fail(`unknown history subcommand: ${sub}. Run 'geml --help'.`);
         }
@@ -1571,6 +2297,13 @@ function runTransform(argv) {
     const out = flag(argv, "-o") ?? flag(argv, "--out");
     const fromRaw = flag(argv, "--from");
     const toRaw = flag(argv, "--to");
+    // `--to html --fragment`: body-only markup for embedding in an existing
+    // layout (library parity: RenderOptions.fragment). Consumed here so it can
+    // be rejected on any other target — a discarded flag is a silent lie.
+    const fragIdx = argv.indexOf("--fragment");
+    const fragment = fragIdx >= 0;
+    if (fragment)
+        argv.splice(fragIdx, 1);
     // Same `--root` as `check`, and for the same reason: cross-document resolution is
     // fail-closed at the document's own directory, so a reference that climbs out of
     // it needs the tree's root named. Without this the transform silently ignored the
@@ -1618,6 +2351,8 @@ function runTransform(argv) {
     else {
         outFmt = inFmt === "geml" ? "json" : "geml"; // geml->json; md/json->geml
     }
+    if (fragment && outFmt !== "html")
+        fail("--fragment only applies to --to html", 2);
     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).
@@ -1654,6 +2389,7 @@ function runTransform(argv) {
         case "html":
             output = renderHtml(doc, {
                 source: file === "-" ? "stdin" : basename(file),
+                fragment,
                 // geml-code-graph embeds load + parse sibling codemap docs on demand.
                 loadDoc: resolverFor(file, root),
                 parseDoc: (s) => parse(s, { resolveDoc: resolverFor(file, root) }),
@@ -1822,39 +2558,55 @@ function resolveSelector(source, file, raw) {
 // resolves against: typed blocks and headings. A `[^id]` reference names one
 // of those (§5.2); the `[^id]: text` definition line was withdrawn.
 function listIds(source, file, json) {
+    const where = file === "-" ? "stdin" : file;
+    const all = addressedUnits(source);
     const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(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 };
-            // `.footnote` is authored, not synthesized (the `[^id]: text` definition
-            // line was withdrawn) — but it still marks a block meant as a footnote.
-            if (b.classes.includes("footnote"))
+    const rows = all.map((a) => {
+        const u = a.unit;
+        const row = {
+            address: shortestAddress(a, all),
+            kind: u.kind === "block" ? u.type ?? "block" : u.kind,
+            lines: [u.span.start + 1, u.span.end],
+        };
+        // §6.3: EVERY id-less block is flagged, including one whose address works
+        // only because its type happens to be unique (`=== meta`) — that it has no
+        // id yet is precisely the fact you might want to act on (§5.2).
+        if (u.id === undefined)
+            row.anon = true;
+        else
+            row.id = u.id;
+        if (u.kind === "heading") {
+            row.level = u.level;
+            row.text = u.text;
+        }
+        // `.footnote` is authored, not synthesized (the `[^id]: text` definition
+        // line was withdrawn) — but it still marks a block meant as a footnote.
+        if (u.id !== undefined) {
+            const site = findBlockSite(doc.children, u.id);
+            const b = site?.siblings[site.index];
+            if (b?.kind === "block" && b.classes.includes("footnote"))
                 row.footnote = true;
-            return row;
         }
-        return { id, kind: b?.kind ?? "unknown" };
+        return row;
     });
+    // §6.6: the empty document is a legitimate empty answer to "list everything",
+    // not a lookup failure — exit 0, and `--json` prints `[]` so a `| jq length`
+    // over a prose-only document does not blow up.
     if (json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
     }
     if (rows.length === 0) {
-        console.error(`no addressable ids in ${file === "-" ? "stdin" : file}`);
+        console.error(`no addressable blocks in ${where}`);
         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 addrW = Math.max(...rows.map((r) => r.address.length));
     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";
+        const mark = r.kind === "heading" ? `h${r.level}` : r.anon ? "anon" : "";
+        const tail = r.kind === "heading" ? r.text ?? "" : `L${r.lines[0]}-${r.lines[1]}`;
+        const line = `${r.address.padEnd(addrW)}  ${r.kind.padEnd(kindW)}  ${mark.padEnd(4)}  ${tail}`
+            + (r.footnote ? "  footnote" : "");
         console.log(line.replace(/\s+$/, ""));
     }
 }
@@ -1871,42 +2623,11 @@ function listIds(source, file, json) {
 // guessed between, so a document with three notes answers "which one" instead
 // of failing. The uniqueness that makes `=== meta` work is checked here, at
 // resolve time — nothing in the format has to promise a document holds only one.
-function getByType(source, file, type, json, headOnly) {
-    const where = file === "-" ? "stdin" : file;
-    const matches = blockTypeSpans(source).get(type) ?? [];
-    if (!matches.length) {
-        fail(`no \`${type}\` block in ${where} — run \`geml get ${where}\` to list every addressable id`, 1);
-    }
-    if (matches.length === 1) {
-        const m = matches[0];
-        if (json) {
-            // The ONLY block of its type: locating it in the model needs no index, so
-            // --json can still answer with the parsed node (meta's key/values, a
-            // table's model) rather than a mere location.
-            const node = onlyBlockOfType(parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).children, type);
-            if (node) {
-                console.log(JSON.stringify(node, null, 2));
-                return;
-            }
-        }
-        const span = headOnly ? narrowToHead(m.span) : m.span;
-        process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
-        return;
-    }
-    // Several: report WHERE they are (data on stdout, the explanation on stderr),
-    // so the caller can name one — by adding an #id, or via its section.
-    if (json) {
-        console.log(JSON.stringify({ kind: "blocks", type, matches: matches.map((m) => ({ ...(m.id ? { id: m.id } : {}), lines: [m.span.start + 1, m.span.end] })) }, null, 2));
-        return;
-    }
-    console.error(`${matches.length} \`${type}\` blocks in ${where} — give one an #id, or address its section:`);
-    for (const m of matches) {
-        console.log(`=== ${type}${m.id ? ` {#${m.id}}` : ""}  L${m.span.start + 1}-${m.span.end}`);
-    }
-}
-// The single block of `type` in a document, or undefined when there is not
-// exactly one (nested flow children included, matching the span scan's reach).
-function onlyBlockOfType(blocks, type) {
+// Every block of `type` in document order, nested flow children included —
+// exactly the span scan's reach and order, so the k-th scan match and the k-th
+// model node are the same block. That correspondence is what lets an ANONYMOUS
+// block's `--json` find its node without an id to look it up by.
+function blocksOfType(blocks, type) {
     const hits = [];
     const walk = (list) => {
         for (const b of list) {
@@ -1919,65 +2640,196 @@ function onlyBlockOfType(blocks, type) {
         }
     };
     walk(blocks);
-    return hits.length === 1 ? hits[0] : undefined;
-}
+    return hits;
+}
+// A unit's index among the units of its own type, for the positional lookup above.
+function typeIndex(all, u) {
+    return all.filter((a) => a.unit.type === u.type).findIndex((a) => a.unit === u);
+}
+// Resolve a NON-list selector to the units it matches, or fail with the reason.
+// `where` names the haystack for the error messages — a file for `geml get`, a
+// revision for `geml history get`'s tier 2. Shared by both so the one selector
+// grammar has one implementation: history's design §10.1 asks for exactly this,
+// and its §3.2 records what happened the last time a selector grammar was
+// written twice (the printed selectors stopped being readable back).
+function selectUnits(source, file, rawSel, where) {
+    const sel = parseSelector(rawSel, (braces) => parseAttrs(braces).id);
+    // Callers handle the empty selector themselves (list for `get`, usage error
+    // for `set`); reaching here with one is a caller bug surfaced as usage.
+    if (sel.form === "list")
+        fail(`no selector given — run \`geml get ${where}\` to list addressable blocks`, 2);
+    if (sel.form === "attr") {
+        // §7: the wording says "not implemented yet", not "braces are meaningless" —
+        // §2 declares attribute keys as part of the model, so implementing them
+        // later fills in a declared slot rather than reversing this message.
+        fail(`only \`#id\` is supported as a filter key today (got \`${sel.key}\`) — use \`=== ${sel.type}\` for every ${sel.type} block, or address one by \`#id\` / \`@<hex>\``, 2);
+    }
+    const all = addressedUnits(source);
+    if (sel.form === "content") {
+        const hit = matchContent(sel, all);
+        if (!hit.ok) {
+            if (hit.why === "wrong-type") {
+                // §3.3: the type prefix is a CHECK. Ignoring a wrong one would make it
+                // a decoration that is allowed to lie, and would silently accept a
+                // hand-edited address.
+                fail(`\`@${sel.hex}\` addresses a \`${hit.found}\` block, not \`${sel.type}\` — drop the type prefix to address it by content alone`, 1);
+            }
+            const suffix = sel.nth ? `~${sel.nth}` : "";
+            fail(`no block matching \`@${sel.hex}${suffix}\` in ${where} — a content address goes stale when the block's content changes (that is the point: §3.2); run \`geml get ${where}\` for current addresses`, 1);
+        }
+        return { units: [hit.unit], all };
+    }
+    if (sel.form === "type") {
+        const hits = matchType(sel.type, all);
+        if (!hits.length)
+            fail(`no \`${sel.type}\` block in ${where}${discoveryHint(where)}`, 1);
+        return { units: hits, all };
+    }
+    // `#id` / bare id / a pasted `## Heading` line — resolveSelector needs a parse
+    // to match heading TEXT, so it stays the one path that reaches the model.
+    const id = resolveSelector(source, file, sel.raw);
+    const unit = all.find((a) => a.unit.id === id)?.unit;
+    // Bare `no block with id \`x\`` — the phrasing every caller of a missing id
+    // has always seen, and which `set`'s own tests pin. `where` is appended only
+    // when it is NOT the file the caller already named (a revision), so the
+    // common case reads the same as before this selector grammar existed.
+    if (!unit)
+        fail(`no block with id \`${id}\`${where.startsWith("revision ") ? ` in ${where}` : ""}`, 1);
+    return { units: [unit], all };
+}
+// The document-model node for one unit; a heading yields its SECTION envelope,
+// so --json covers the same content as the raw span. `kind:"section"` lets a
+// consumer branch — every other unit yields the single node (the model is flat).
+function unitNode(source, file, unit, all) {
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
+    if (unit.id !== undefined) {
+        const site = findBlockSite(doc.children, unit.id);
+        if (!site)
+            fail(`no block with id \`${unit.id}\``, 1);
+        const block = site.siblings[site.index];
+        if (block.kind !== "heading")
+            return block;
+        const end = sectionEndIndex(site.siblings, site.index);
+        return { kind: "section", id: block.id, level: block.level, blocks: site.siblings.slice(site.index, end) };
+    }
+    const node = blocksOfType(doc.children, unit.type ?? "")[typeIndex(all, unit)];
+    if (!node)
+        fail(`could not locate the \`${unit.type}\` block in the document model`, 1);
+    return node;
+}
+// stderr line for an N-match selector: content stays on stdout, so a redirect
+// captures document bytes only, and the caller still learns how many it got (§5).
+function reportMatches(type, units) {
+    const at = units.map((u) => `L${u.span.start + 1}-${u.span.end}${u.id ? ` #${u.id}` : ""}`).join(" · ");
+    console.error(`${units.length} \`${type}\` blocks (${at})`);
+}
+// `geml get <file.geml|-> [<selector>] [--head|--body] [--json]` — read the
+// document's addressable structure, or one/several blocks out of it.
+//
+// The selector is a FILTER (§2 of the get/set selector design): no selector
+// LISTS every addressable block with its shortest unique address; `#id` /
+// `## Heading` / `=== type@<hex>` name at most one; `=== type` matches 0..N.
+// Cardinality is uniform (§5): 0 → exit 1, 1 → the content, N → N contents in
+// document order with the count on stderr. `--head`/`--body` narrow to one part
+// of each match, and every flag combination that used to be half-honoured is
+// now a usage error (§7) — a discarded flag is a command that quietly did
+// something else.
 function runGet(args) {
     const json = args.includes("--json");
     const headOnly = args.includes("--head");
-    const [file, rawId] = positionals(args, []);
+    const bodyOnly = args.includes("--body");
+    const view = args.includes("--view");
+    const [file, rawSel] = positionals(args, ["--root"]);
     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 (headOnly && bodyOnly)
+        fail("--head and --body are mutually exclusive", 2);
+    if (json && (headOnly || bodyOnly)) {
+        fail(`--json cannot be combined with ${headOnly ? "--head" : "--body"} — --json returns the model node, which has no sub-node for one part of a block`, 2);
+    }
     // One read: stdin can only be consumed once, and the selector resolver needs
     // the same bytes the slice below works on.
     const source = readInput(file);
-    if (!rawId) {
+    const where = file === "-" ? "stdin" : file;
+    const sel = parseSelector(rawSel, (braces) => parseAttrs(braces).id);
+    if (sel.form === "list") {
+        // §5.1: nothing here to narrow, and ignoring the flag would make
+        // `get f --head` print byte-for-byte what `get f` prints.
+        if (headOnly || bodyOnly) {
+            fail(`${headOnly ? "--head" : "--body"} names part of ONE block, so it needs a selector — run \`geml get ${where}\` to list what to address`, 2);
+        }
         listIds(source, file, json);
         return;
     }
-    // A FENCE line as the selector (`=== meta`): the same "copy the line out of
-    // the document" move as a heading line, for the blocks that carry no id.
-    // A pasted fence that DOES declare an id defers to the id path below.
-    const fence = /^={3,}[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*(\{.*\})?[ \t]*$/.exec(rawId.trim());
-    const fenceId = fence?.[2] ? parseAttrs(fence[2]).id : undefined;
-    if (fence && fenceId === undefined) {
-        getByType(source, file, fence[1], json, headOnly);
+    const { units, all } = selectUnits(source, file, rawSel, where);
+    // The chain is composed with `/` — relJoinPath's rule, and `src=` values are
+    // always `/`-separated — so normalize the PLATFORM path at this boundary. On
+    // Windows `sub\host.geml` otherwise has no directory as far as relDirPath can
+    // tell, and a relative `src=` resolves against the wrong base.
+    const startDoc = where.replace(/\\/g, "/");
+    const viewRoot = flag(args, "--root") ?? (relDirPath(startDoc) || ".");
+    if (json) {
+        // §7: N matches yield N model nodes. The old `{kind:"blocks",
+        // matches:[{lines}]}` coordinate envelope is gone — it answered "where are
+        // they" when the question is "what are they" (§9 change 2).
+        let nodes;
+        try {
+            nodes = units.flatMap((u) => {
+                if (!view)
+                    return [unitNode(source, file, u, all)];
+                return viewResolve(source, startDoc, u, viewRoot).map((res) => {
+                    const node = unitNode(res.text, res.doc, res.unit, res.all);
+                    // Provenance is mandatory (§4): the node's references and relative
+                    // paths resolve against ITS document, not the one asked about. A
+                    // whole-document target has no `#`, so it carries `doc` alone.
+                    if (res.from !== "") {
+                        const h = res.from.lastIndexOf("#");
+                        node["from"] = h < 0 ? { doc: res.from }
+                            : { doc: res.from.slice(0, h), id: res.from.slice(h + 1) };
+                    }
+                    return node;
+                });
+            });
+        }
+        catch (e) {
+            if (e instanceof ViewError)
+                fail(e.message, 1);
+            throw e;
+        }
+        console.log(JSON.stringify(nodes.length === 1 ? nodes[0] : nodes, null, 2));
         return;
     }
-    const id = fenceId ?? resolveSelector(source, file, rawId);
-    if (json) {
-        // 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), self: file === "-" ? undefined : basename(file) });
-        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;
+    if (units.length > 1)
+        reportMatches(units[0].type ?? "", units);
+    if (view) {
+        // All-or-nothing (§3.3): resolve EVERYTHING before writing a byte, so a
+        // chain that breaks halfway cannot leave a partial read on stdout for a
+        // caller that ignores the exit code. Partial scenery is not scenery.
+        const out = [];
+        const notes = [];
+        try {
+            for (const u of units) {
+                for (const res of viewResolve(source, startDoc, u, viewRoot)) {
+                    if (res.from !== "")
+                        notes.push(`view: ${rawSel} -> ${res.from}`);
+                    out.push(sliceUnit(res.text, res.unit.span, headOnly, bodyOnly));
+                }
+            }
+        }
+        catch (e) {
+            // A chain that cannot reach an entity block is a failed READ, reported the
+            // way `get` reports a selector that matches nothing: one line, exit 1.
+            if (e instanceof ViewError)
+                fail(e.message, 1);
+            throw e;
         }
-        console.log(JSON.stringify(block, null, 2));
+        for (const n of notes)
+            console.error(n);
+        process.stdout.write(out.join(""));
         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 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(""));
+    for (const u of units)
+        process.stdout.write(sliceUnit(source, u.span, headOnly, bodyOnly));
 }
 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]` —
@@ -2003,14 +2855,19 @@ function runSet(args) {
     const bodyOnly = args.includes("--body");
     if (headOnly && bodyOnly)
         fail("--head and --body are mutually exclusive", 2);
-    const [file, rawId] = positionals(args, ["-o", "--out", "--in"]);
+    // `--view` reads THROUGH an embed (see runGet). Writing through one would mean
+    // one `set` silently editing a different file, so it is refused rather than
+    // ignored — and the message has to point the way, not just say no.
+    if (args.includes("--view")) {
+        fail("--view is read-only. To edit the target, read the frame's `src` and edit that document.", 2);
+    }
+    const [file, rawSel] = 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(/^#/, "");
+    // No selector: there is no block to replace. Point the way to discovery, not a
+    // bare usage line — `geml get <file>` lists every address `set` can target.
+    if (!rawSel)
+        fail(`no selector given — run 'geml get ${file === "-" ? "<file>" : file}' to list addressable blocks`, 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.
@@ -2019,16 +2876,11 @@ function runSet(args) {
         fail("reading the document from stdin needs --in for the new content", 2);
     }
     const source = readInput(file);
+    const target = resolveSetTarget(source, file, rawSel);
     if (bodyOnly) {
-        runSetBody(source, id, from, rawChannel, file, out);
+        runSetBody(source, target, from, rawChannel, file, out);
         return;
     }
-    // default / --head: content is a whole block (default) or a bare head line.
-    // Does the target exist? Asked FIRST: the shape checks below name the id in
-    // their advice ("use --body to set the body of #far"), which reads as though the
-    // id were there. Whether the content is prose is the second question.
-    if (!blockSpans(source).has(id))
-        fail(`no block with id \`${id}\``, 1);
     let content;
     if (rawChannel) {
         content = readInput("-");
@@ -2042,39 +2894,71 @@ function runSet(args) {
             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);
+                fail(`content is prose, not a block — use --body to set the body of ${target.label}`, 1);
             if (shape === "multi")
                 fail("set replaces ONE block, but the content has multiple blocks (use add)", 1);
         }
     }
     else {
-        content = extractBlock(from, id, headOnly ? "head" : "whole");
-    }
-    const normalized = normalizeBlockId(content, id);
-    const updated = spliceBlock(source, id, normalized, file, headOnly);
+        content = extractBlock(from, target.unit.id ?? "", headOnly ? "head" : "whole");
+    }
+    // §5.2: `@<hex>` is not an id, so "normalize the content's id to the target's"
+    // has no subject — the content is used verbatim, and an id it brings that
+    // collides is caught by the splice guard like any other. An id target keeps
+    // normalizing: naming an id on the command line IS the instruction that the
+    // result carries that id (block-mutation design §4.0).
+    const replacement = target.unit.id !== undefined ? normalizeBlockId(content, target.unit.id) : content;
+    const updated = spliceSpan(source, target.unit.span, replacement, file, headOnly, false, target.unit.id);
     resolveOutTarget(file, out).write(updated);
+    reportNewAddress(updated, target);
+}
+// Resolve a selector to the ONE unit `set` will overwrite. `get` may answer with
+// N blocks; `set` may not — §5: with N targets there is no single id to
+// normalize the content to, so multi-target `set` is undefined, not merely
+// risky. Refused with exit 2 (a usage error), not exit 1.
+function resolveSetTarget(source, file, rawSel) {
+    const where = file === "-" ? "<file>" : file;
+    const sel = parseSelector(rawSel, (braces) => parseAttrs(braces).id);
+    if (sel.form === "list")
+        fail(`no selector given — run 'geml get ${where}' to list addressable blocks`, 2);
+    const { units, all } = selectUnits(source, file, rawSel, where);
+    if (units.length > 1) {
+        // §5: with N targets there is no single id to normalize the content to, so
+        // multi-target `set` is UNDEFINED, not merely risky. The addresses are
+        // printed because they ARE the fix — each is unique and pastes straight
+        // back into this same command (§6.2).
+        const opts = units.map((u) => {
+            const a = all.find((x) => x.unit === u);
+            return `  ${shortestAddress(a, all)}  L${u.span.start + 1}-${u.span.end}`;
+        }).join("\n");
+        fail(`\`${rawSel.trim()}\` matches ${units.length} blocks — set writes ONE; address it uniquely:\n${opts}`, 2);
+    }
+    const unit = units[0];
+    const label = unit.id !== undefined && sel.form === "id" ? `#${unit.id}` : `\`${rawSel.trim()}\``;
+    return { unit, label, byContent: sel.form === "content" };
+}
+// §5.3: writing through a content address CHANGES it, so print the new one —
+// otherwise a script editing the same block twice has to re-list in between.
+// stderr, because stdout may be the document itself (`-o -`).
+function reportNewAddress(updated, target) {
+    if (!target.byContent)
+        return;
+    const after = addressedUnits(updated).find((a) => a.unit.span.start === target.unit.span.start);
+    if (after)
+        console.error(`new address: ${shortestAddress(after, addressedUnits(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);
+function runSetBody(source, target, from, rawChannel, file, out) {
+    const found = target.unit.span;
     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] ?? "";
-    }
+    // A typed block keeps its closing fence; a heading section has none. Decided
+    // by the same helper `get --body` uses, so the two agree on the span and the
+    // §4 round-trip invariant holds.
+    const closeLine = closeFenceLine(lines, found);
     let body;
     if (rawChannel) {
         body = readInput("-");
@@ -2082,7 +2966,7 @@ function runSetBody(source, id, from, rawChannel, file, out) {
             fail(NO_CONTENT, 1);
     }
     else {
-        body = extractBlock(from, id, "body");
+        body = extractBlock(from, target.unit.id ?? "", "body");
     }
     let head = headLine;
     if (head !== "" && !/(\r\n|\r|\n)$/.test(head))
@@ -2095,8 +2979,9 @@ function runSetBody(source, id, from, rawChannel, file, out) {
     // 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);
+    const updated = spliceSpan(source, found, replacement, file, false, closeLine !== null, target.unit.id);
     resolveOutTarget(file, out).write(updated);
+    reportNewAddress(updated, target);
 }
 // `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`,
@@ -2397,6 +3282,13 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const found = blockSpans(source).get(id);
     if (!found)
         fail(`no block with id \`${id}\``, 1);
+    return spliceSpan(source, found, replacement, file, headOnly, guardCount, id);
+}
+// The same guarded splice addressed by SPAN rather than by id, because an
+// anonymous block (addressed by `@<hex>`) has no id to look one up with. `id`
+// is the survival guard's subject and is simply absent for those: every OTHER
+// pre-existing id must still survive, which the `dropped` check below covers.
+function spliceSpan(source, found, replacement, file, headOnly = false, guardCount = false, id) {
     const beforeDoc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const beforeIds = beforeDoc.ids;
     // Keep the bytes before and after the target span exactly; give the new block
@@ -2428,7 +3320,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
         refuseBroken(`replacement would break the document: ${first.message} (line ${first.line}); not written`, errs);
     }
     const now = new Set(reparsed.ids);
-    if (!now.has(id))
+    if (id !== undefined && !now.has(id))
         fail(`replacement removes id \`${id}\`; not written`, 1);
     const dropped = beforeIds.find((x) => x !== id && !now.has(x));
     if (dropped !== undefined) {
@@ -2443,7 +3335,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     // (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);
+        fail(`replacement changes the block count (a fence in the body closed ${id !== undefined ? `#${id}` : "the target"} early and injected sibling block(s)?); not written`, 1);
     }
     return updated;
 }
@@ -2695,6 +3587,105 @@ function runMcp(args) {
     const r = spawnSync(process.execPath, [mod, ...args], { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
+// geml skill install: one command that makes GEML usable everywhere for a
+// Claude Code user — the authoring skill resident under ~/.claude/skills/geml,
+// the CLI on the global PATH, and the MCP server registered at user scope.
+// Deliberately quiet: no settings.json edits, no hooks, no .gemlhistory
+// sidecars. Idempotent, so re-running after an upgrade refreshes everything.
+function runSkill(args) {
+    const sub = args[0];
+    if (sub !== "install")
+        fail(`unknown skill subcommand '${sub ?? ""}'.\n${SUBHELP.skill}`);
+    const rest = args.slice(1);
+    const flag = (name) => {
+        const i = rest.indexOf(name);
+        if (i >= 0)
+            rest.splice(i, 1);
+        return i >= 0;
+    };
+    const opt = (name) => {
+        const i = rest.indexOf(name);
+        if (i < 0)
+            return undefined;
+        const v = rest[i + 1];
+        if (!v)
+            fail(`${name} needs a value.\n${SUBHELP.skill}`);
+        rest.splice(i, 2);
+        return v;
+    };
+    const noGlobal = flag("--no-global");
+    const noMcp = flag("--no-mcp");
+    const dest = opt("--dest") ?? join(homedir(), ".claude", "skills");
+    if (rest.length)
+        fail(`unexpected argument '${rest[0]}'.\n${SUBHELP.skill}`);
+    // The skill ships inside the npm package, next to dist/ — the installed
+    // skill text always matches the CLI version it teaches.
+    const src = join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+    if (!existsSync(join(src, "SKILL.md")))
+        fail(`bundled skill not found at ${src} (broken install?)`, 1);
+    const target = join(dest, "geml");
+    const copied = [];
+    const copyTree = (from, to) => {
+        mkdirSync(to, { recursive: true });
+        for (const e of readdirSync(from, { withFileTypes: true })) {
+            // Never ship a history sidecar — skill and config docs carry none.
+            if (e.name.endsWith(".gemlhistory"))
+                continue;
+            const f = join(from, e.name);
+            const t = join(to, e.name);
+            if (e.isDirectory())
+                copyTree(f, t);
+            else {
+                copyFileSync(f, t);
+                copied.push(relative(dest, t));
+            }
+        }
+    };
+    try {
+        copyTree(src, target);
+    }
+    catch (e) {
+        // A clean one-liner, never a raw stack: --dest may name a file, a
+        // read-only tree, or a path whose ancestor is not a directory.
+        fail(`cannot install skill to ${target}: ${e instanceof Error ? e.message : String(e)}`, 1);
+    }
+    console.log(`skill  installed -> ${target}  (${copied.join(", ")})`);
+    // Windows npm/claude/geml are .cmd shims: they need a shell. Every argument
+    // below is a fixed literal, so shell:true adds no injection surface.
+    const sh = process.platform === "win32";
+    const run = (cmd, a, inherit = false) => spawnSync(cmd, a, { shell: sh, encoding: "utf8", ...(inherit ? { stdio: "inherit" } : {}) });
+    if (!noGlobal) {
+        const have = run("geml", ["--version"]);
+        if (have.status === 0) {
+            console.log(`cli    ${String(have.stdout ?? "").trim()} already on PATH`);
+        }
+        else {
+            console.log("cli    installing @geml/geml globally (npm i -g)...");
+            const r = run("npm", ["install", "-g", "@geml/geml", "--no-audit", "--no-fund", "--loglevel=error"], true);
+            if (r.status !== 0)
+                console.error("cli    global install failed — install later with: npm i -g @geml/geml");
+        }
+    }
+    if (!noMcp) {
+        const REG = "claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .";
+        const claude = run("claude", ["--version"]);
+        if (claude.status !== 0) {
+            console.log(`mcp    claude CLI not found — register later with: ${REG}`);
+        }
+        else if (run("claude", ["mcp", "get", "geml"]).status === 0) {
+            console.log("mcp    server 'geml' already registered");
+        }
+        else {
+            const r = run("claude", ["mcp", "add", "--scope", "user", "geml", "--", "npx", "-y", "@geml/geml", "mcp", "--root", "."]);
+            if (r.status === 0)
+                console.log("mcp    registered user-scope server 'geml' (confined to each session's project directory)");
+            else
+                console.error(`mcp    registration failed (${String(r.stderr ?? "").trim() || "unknown"}) — register later with: ${REG}`);
+        }
+    }
+    console.log("done — new Claude Code sessions pick up the skill.");
+    process.exit(0);
+}
 // 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 = (() => {
@@ -2767,6 +3758,9 @@ if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.t
     else if (cmd === "mcp") {
         runMcp(argv.slice(1));
     }
+    else if (cmd === "skill") {
+        runSkill(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. (The