@geml/geml 1.6.0 → 1.7.0

package/dist/geml.js

@@ -9,8 +9,9 @@
 // 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 { save, restore, verify, isCurrent, listRevisions, resolveContent, firstChangedContent } from "./history.js";
@@ -20,13 +21,13 @@ 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
@@ -37,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";
@@ -47,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
@@ -60,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()
@@ -295,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 });
@@ -326,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.
@@ -416,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);
@@ -502,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) });
     }
@@ -555,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 });
@@ -735,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);
@@ -751,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)
@@ -847,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;
             }
@@ -923,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) {
@@ -942,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
@@ -955,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 {
@@ -984,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
@@ -1012,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);
@@ -1319,6 +1882,8 @@ Usage:
                                              --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)
@@ -1351,6 +1916,10 @@ Usage:
                                               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.
@@ -1364,7 +1933,7 @@ Exit codes:
 // 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|-> [<selector>] [--head|--body] [--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; without a selector: list every addressable block with its shortest unique address, --json = array)",
+    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)",
@@ -1408,6 +1977,19 @@ const SUBHELP = {
 
   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.
@@ -1486,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))
@@ -1556,18 +2150,6 @@ function historyError(e, file, historyPath) {
     }
     return err?.message ?? String(e);
 }
-// The three verbs the four-verb collapse removed (design §2/§6). They are HARD
-// deletions, not aliases — the same call this repo already made for `geml
-// codemap mcp` and `geml mcp --workspace`: one word, one meaning, and a stale
-// spelling that keeps working is a second vocabulary the docs and an agent's
-// memory then both carry. So each names its replacement rather than falling into
-// `unknown history subcommand`, which would leave the caller guessing which of
-// four verbs took over.
-const RETIRED_HISTORY = {
-    commit: "geml history commit was renamed: use `geml history save <file.geml> [-m msg]` (same behaviour, except that a file identical to the tip is now a no-op instead of an empty revision).",
-    log: "geml history log was removed: use `geml history get <file.geml>` — no revision selector lists every revision, newest first, with the same copy-pasteable first column.",
-    show: "geml history show was removed: use `geml history get <file.geml> <rev>` — a revision selector prints that revision's full text (`--json` wraps it as {id, text}).",
-};
 // 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.
@@ -1594,8 +2176,6 @@ function runHistory(args) {
     const [sub, file, rev, ...extra] = historyPositionals(args);
     if (!sub || !file)
         fail(SUBHELP.history);
-    if (RETIRED_HISTORY[sub])
-        fail(RETIRED_HISTORY[sub]);
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const json = args.includes("--json");
     try {
@@ -1717,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
@@ -1764,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).
@@ -1800,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) }),
@@ -2148,7 +2738,8 @@ function runGet(args) {
     const json = args.includes("--json");
     const headOnly = args.includes("--head");
     const bodyOnly = args.includes("--body");
-    const [file, rawSel] = positionals(args, []);
+    const view = args.includes("--view");
+    const [file, rawSel] = positionals(args, ["--root"]);
     if (!file)
         fail(SUBHELP.get);
     if (headOnly && bodyOnly)
@@ -2171,16 +2762,72 @@ function runGet(args) {
         return;
     }
     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).
-        const nodes = units.map((u) => unitNode(source, file, u, all));
-        console.log(JSON.stringify(units.length === 1 ? nodes[0] : nodes, null, 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;
     }
     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;
+        }
+        for (const n of notes)
+            console.error(n);
+        process.stdout.write(out.join(""));
+        return;
+    }
     for (const u of units)
         process.stdout.write(sliceUnit(source, u.span, headOnly, bodyOnly));
 }
@@ -2208,6 +2855,12 @@ function runSet(args) {
     const bodyOnly = args.includes("--body");
     if (headOnly && bodyOnly)
         fail("--head and --body are mutually exclusive", 2);
+    // `--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);
@@ -2934,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 = (() => {
@@ -3006,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