@geml/geml 1.4.6 → 1.5.1

package/dist/geml.js

@@ -18,7 +18,7 @@ import { renderHtml } from "./render-html.js";
 import { normalizeBlockId } from "./block-edit.js";
 import { normalizeSource } from "./diagnostics.js";
 import { coerce, parseAttrs } from "./attrs.js";
-import { META_REF_SRC, parseInline } from "./inline.js";
+import { META_REF_SRC, parseInline, isSafeUrl, schemeOf } from "./inline.js";
 import { parseTable } from "./table.js";
 import { buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
@@ -46,7 +46,7 @@ const REGISTRY = {
     diagram: "raw",
     math: "raw",
     table: "raw", // structured table parsing lands in M3
-    output: "raw", // captured result of a code block (stored, never executed)
+    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
     meta: "data",
@@ -154,7 +154,7 @@ function registerId(ctx, id, line) {
     }
 }
 // §5: a list marker — `-`/`*` (unordered) or `N.` (ordered) — capturing the
-// leading indent (in spaces; a tab counts as one) and the item content. Nesting
+// leading indent (in spaces; a tab counts as 4) and the item content. Nesting
 // is decided by that indent.
 const MARKER = /^([ \t]*)(?:[-*]|(\d+)\.)[ \t]+(.*)$/;
 function matchMarker(line) {
@@ -162,7 +162,14 @@ function matchMarker(line) {
     if (!m)
         return null;
     const ordered = m[2] !== undefined;
-    const mk = { indent: m[1].length, ordered, rest: m[3] };
+    let indent = 0;
+    for (const ch of m[1]) {
+        if (ch === '\t')
+            indent += 4;
+        else
+            indent += 1;
+    }
+    const mk = { indent, ordered, rest: m[3] };
     if (ordered)
         mk.start = parseInt(m[2], 10);
     return mk;
@@ -249,7 +256,26 @@ function scanBlocks(lines, base, ctx, depth = 0) {
     const diags = ctx.diags;
     let i = 0;
     while (i < lines.length) {
-        const line = lines[i];
+        let line = lines[i];
+        let consumed = 1;
+        // C-01: Attribute line continuation via `\`.
+        // If a line looks like a fence or heading and ends with `\`, fold subsequent lines.
+        if ((line.startsWith("===") || line.startsWith("#")) && line.endsWith("\\")) {
+            let folded = line.slice(0, -1).trimEnd();
+            while (i + consumed < lines.length) {
+                const next = lines[i + consumed].trim();
+                if (next.endsWith("\\")) {
+                    folded += " " + next.slice(0, -1).trimEnd();
+                    consumed++;
+                }
+                else {
+                    folded += " " + next;
+                    consumed++;
+                    break;
+                }
+            }
+            line = folded;
+        }
         if (line.trim() === "") {
             i++;
             continue;
@@ -259,24 +285,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
         const hid = /^[ \t]*%%[ \t]?(.*)$/.exec(line);
         if (hid) {
             blocks.push({ kind: "hidden", text: hid[1] });
-            i++;
-            continue;
-        }
-        // §5.2: a Markdown-style footnote definition `[^id]: text` defines the
-        // target a `[^id]` reference points at — recorded as a note block with that
-        // id, so the reference resolves. (A model that reaches for Markdown
-        // footnotes by habit then "just works" instead of leaving a dangling ref.)
-        const fndef = /^\[\^([^\]]+)\]:[ \t]?(.*)$/.exec(line);
-        if (fndef) {
-            const id = fndef[1].trim();
-            const lineNo = base + i + 1;
-            registerId(ctx, id, lineNo);
-            const text = interpolate(fndef[2], lineNo, ctx);
-            blocks.push({
-                kind: "block", type: "note", mode: "flow", id, classes: ["footnote"], attrs: {},
-                children: [{ kind: "paragraph", text, inlines: parseInline(text, lineNo, ctx) }],
-            });
-            i++;
+            i += consumed;
             continue;
         }
         const open = FENCE_OPEN.exec(line);
@@ -292,7 +301,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             // safe way to nest (§3).
             const labeled = attrs.id !== undefined ? new RegExp(`^={3,}[ \\t]+#${reLit(attrs.id)}[ \\t]*$`) : null;
             const body = [];
-            let j = i + 1;
+            let j = i + consumed;
             let closed = false;
             for (; j < lines.length; j++) {
                 if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j]))) {
@@ -310,6 +319,31 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                 diags.push({ severity: "warning", code: "unknown-block-type", message: `unknown block type \`${type}\`; body kept as raw`, line: openLineNo });
                 mode = "raw";
             }
+            else {
+                // `hidden` (§4) and `caption` (§4, and the label an auto-reference takes
+                // per §5.2) are not type-specific: every typed block may carry them. Only
+                // the extras below are per type.
+                let validRe;
+                if (type === "table")
+                    validRe = /^(src|format|header|format-data|compute\d*|summary\d*|span\d*)$/;
+                else if (type === "embed")
+                    validRe = /^(src)$/;
+                else if (type === "diagram")
+                    validRe = /^(src|data|format|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.
+                else if (type === "code")
+                    validRe = /^(lang|src|anchor|name|entry-via)$/;
+                else
+                    validRe = /^$/;
+                const universal = /^(hidden|caption)$/;
+                for (const key of Object.keys(attrs.attrs)) {
+                    if (!universal.test(key) && !validRe.test(key)) {
+                        diags.push({ severity: "warning", code: "unknown-attribute", message: `unknown attribute \`${key}\` for block type \`${type}\``, line: openLineNo });
+                    }
+                }
+            }
             const block = {
                 kind: "block", type, mode, classes: attrs.classes, attrs: attrs.attrs,
             };
@@ -319,12 +353,50 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             }
             if (attrs.attrs["hidden"] === true)
                 block.hidden = true; // §4: not rendered, still in model
-            // §3: an `output` block stores a code block's captured result; `of=#id`
-            // (when present) binds it to that block and is checked like any reference.
-            if (type === "output" && typeof attrs.attrs["of"] === "string") {
-                const of = attrs.attrs["of"];
-                if (of.startsWith("#"))
-                    ctx.refs.push({ kind: "internal", anchor: of.slice(1), line: openLineNo });
+            // Block transclusion: `src=` names the content this block stands for, and
+            // is registered as an ordinary reference so the existing §8 resolver
+            // validates the document and the id. Without that, an embed would be the
+            // one reference shape whose rot is silent.
+            if (type === "embed") {
+                const src = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : "";
+                if (src === "") {
+                    diags.push({ severity: "error", code: "embed-missing-src", message: "embed: missing `src=`", line: openLineNo });
+                }
+                else {
+                    const hash = src.indexOf("#");
+                    const docPath = hash < 0 ? src : src.slice(0, hash);
+                    const anchor = hash < 0 ? undefined : src.slice(hash + 1);
+                    // §9.5: a destination naming a scheme outside the allowlist MUST NOT be
+                    // emitted as a navigable or loadable target, and the check belongs HERE —
+                    // when the model is built — so no consumer of the model can reintroduce
+                    // it. The attribute is blanked as well as reported, the same treatment a
+                    // media `src` already gets: a diagnostic alone would still leave the
+                    // string in `attrs` for a renderer to put in an href.
+                    if (!isSafeUrl(src)) {
+                        diags.push({ severity: "error", code: "unsafe-embed-scheme", message: `embed: \`src=${src}\` names a disallowed URL scheme`, line: openLineNo });
+                        block.attrs = { ...block.attrs, src: "" };
+                    }
+                    else if (docPath !== "" && !/\.geml$/i.test(docPath)) {
+                        diags.push({ severity: "error", code: "embed-target-not-geml", message: `embed: \`${docPath}\` is not a GEML document; \`src=\` names a \`.geml\` file (optionally with a #fragment)`, line: openLineNo });
+                    }
+                    else if (docPath === "") {
+                        // Recorded with an empty doc so the self-cycle pass can see it.
+                        if (anchor !== undefined)
+                            (ctx.embeds ??= []).push({ doc: "", anchor, line: openLineNo });
+                        // `src=#id`: a block of THIS document. Validated against local ids.
+                        if (anchor !== undefined)
+                            ctx.refs.push({ kind: "internal", anchor, line: openLineNo });
+                    }
+                    else {
+                        ctx.refs.push({ kind: "cross", doc: docPath, anchor, line: openLineNo });
+                        // Kept apart from refs: a transclusion can pull in a document that
+                        // transcludes further, so cycle detection has to walk the graph.
+                        (ctx.embeds ??= []).push(anchor === undefined ? { doc: docPath, line: openLineNo } : { doc: docPath, anchor, line: openLineNo });
+                    }
+                }
+                if (body.some((l) => l.trim() !== "")) {
+                    diags.push({ severity: "warning", code: "ignored-embed-body", message: "embed body is ignored; the target lives in `src=`", line: openLineNo });
+                }
             }
             if (mode === "flow") {
                 if (depth >= MAX_NESTING) {
@@ -344,8 +416,11 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             else {
                 block.raw = body;
                 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);
+                    if (srcAttr !== undefined)
+                        (ctx.tableSources ??= []).push({ block, line: openLineNo, target: srcAttr });
                     block.table = model;
                     for (const d of diagnostics)
                         diags.push({ ...d, line: openLineNo });
@@ -394,9 +469,10 @@ function scanBlocks(lines, base, ctx, depth = 0) {
         if (h) {
             const lineNo = base + i + 1;
             const level = h[1].length;
-            const a = h[3] ? parseAttrs(h[3]) : { classes: [], attrs: {} };
-            const text = interpolate(h[2], lineNo, ctx);
-            const id = a.id ?? slug(text);
+            const rawText = h[2];
+            const a = parseAttrs(h[3] ?? "");
+            const text = interpolate(rawText, lineNo, ctx);
+            const id = a.id ?? slug(rawText);
             registerId(ctx, id, lineNo);
             const block = {
                 kind: "heading", level, text, inlines: parseInline(text, lineNo, ctx), id, classes: a.classes, attrs: a.attrs,
@@ -404,7 +480,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             if (a.attrs["hidden"] === true)
                 block.hidden = true;
             blocks.push(block);
-            i++;
+            i += consumed;
             continue;
         }
         if (LIST_ITEM.test(line)) {
@@ -448,6 +524,342 @@ function parseData(lines) {
 // ---------------------------------------------------------------------------
 // Collect the block ids of a (cross-document) source, without validation, for
 // resolving `other.geml#id` references.
+// S5/S6: a transclusion may pull in a document that transcludes further, so a
+// cycle is only visible by walking the graph. Reported at check time — before
+// any rendering — so a build fails on the cycle rather than on a placeholder in
+// the output. Paths compose the way the renderer composes them: a target inside
+// a borrowed document is relative to THAT document.
+// `data=rows.csv` on a chart, desugared: the anonymous table it stands for. Built
+// by handing the loaded lines to the SAME body parser a `=== table {src=…}` uses,
+// with the chart's own `format=`/`header=` carried over, so nothing about how the
+// data is read is specific to charts. Returns null when the source could not be
+// resolved — the diagnostic is already pushed, in the table rules' own words.
+function chartSourceTable(ctx, opts, block, target, line) {
+    const scheme = schemeOf(target);
+    if (scheme === "http" || scheme === "https") {
+        // §9.4: fetched at render time, so there is nothing to chart at build time —
+        // the same state a remote-sourced table leaves behind.
+        return null;
+    }
+    if (!opts.resolveDoc) {
+        ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `geml-chart: data source \`${target}\` not checked (no document resolver)`, line });
+        return null;
+    }
+    const text = opts.resolveDoc(target);
+    if (text === null) {
+        ctx.diags.push({ severity: "error", code: "unresolvable-table-source", message: `geml-chart: cannot resolve data source \`${target}\``, line });
+        return null;
+    }
+    const attrs = {
+        format: typeof block.attrs["format-data"] === "string" ? block.attrs["format-data"] : inferDataFormat(target),
+        header: block.attrs["header"] === undefined ? true : block.attrs["header"],
+    };
+    const { model, diagnostics } = parseTable(normalizeSource(text).split("\n"), attrs, line, ctx);
+    for (const d of diagnostics)
+        ctx.diags.push({ ...d, line });
+    model.src = target;
+    return model;
+}
+const inferDataFormat = (target) => (/\.tsv$/i.test(target) ? "tsv" : "csv");
+// The renderer's own cap (render.ts EMBED_DEPTH_CAP). Kept in step here so the
+// check and the render agree on which documents are reachable at all.
+const EMBED_DEPTH_LIMIT = 8;
+function detectTransclusionCycles(ctx, opts) {
+    if (!opts.resolveDoc || ctx.embeds === undefined || ctx.embeds.length === 0)
+        return;
+    const resolve = opts.resolveDoc;
+    const embedsOf = new Map(); // memoized per path
+    const reported = new Set();
+    // A three-colour DFS over DOCUMENTS, not over paths. Enumerating every path
+    // through the graph is exponential in its fan-out: a chain of 21 tiny files,
+    // each embedding the next three times, took over two minutes — and `check` is
+    // the CI gate and the validator every MCP write runs twice. Grey means "on the
+    // current stack" and is the cycle; black means already fully explored, so each
+    // edge is walked once and the whole traversal is O(V+E).
+    const colour = new Map();
+    const walk = (path, base, stack, line) => {
+        const rel = relJoinPath(base, path);
+        if (colour.get(rel) === "grey") {
+            const chain = [...stack, rel].join(" → ");
+            if (reported.has(chain))
+                return;
+            reported.add(chain);
+            ctx.diags.push({ severity: "error", code: "transclusion-cycle", message: `transclusion cycle: ${chain}`, line });
+            return;
+        }
+        if (colour.get(rel) === "black")
+            return;
+        // Agree with the renderer about what is even reachable, instead of exploring
+        // eight times deeper than it will ever expand.
+        if (stack.length >= EMBED_DEPTH_LIMIT)
+            return;
+        colour.set(rel, "grey");
+        let inner = embedsOf.get(rel);
+        if (inner === undefined) {
+            const src = resolve(rel);
+            inner = src === null ? [] : gatherEmbeds(src); // an unresolvable doc is already an error
+            embedsOf.set(rel, inner);
+        }
+        for (const e of inner)
+            walk(e.doc, relDirPath(rel), [...stack, rel], line);
+        colour.set(rel, "black");
+    };
+    // The root is named so a chain can be seen returning to it. Falling back to ""
+    // only loses the A→…→A case, which is what happened before `self` existed.
+    const root = opts.self ?? "";
+    for (const e of ctx.embeds)
+        walk(e.doc, relDirPath(root), [root], e.line);
+}
+// The smallest cycle of all, and the one the cross-document walk above cannot
+// see: `=== embed {src=#sec}` written INSIDE the section `#sec` selects the slice
+// that contains it. Decided on spans, so the boundary is exactly the one `geml
+// get` uses — a heading id spans its whole section, so an embed anywhere in that
+// section is inside its own target.
+function detectSelfEmbedCycles(source, ctx) {
+    const selfEmbeds = (ctx.embeds ?? []).filter((e) => e.doc === "" && e.anchor !== undefined);
+    if (selfEmbeds.length === 0)
+        return;
+    const spans = blockSpans(source);
+    for (const e of selfEmbeds) {
+        const span = spans.get(e.anchor);
+        if (span === undefined)
+            continue; // a missing id is already an unresolved reference
+        const line = e.line - 1; // spans are 0-based line indices
+        if (line >= span.start && line <= span.end) {
+            ctx.diags.push({
+                severity: "error",
+                code: "transclusion-cycle",
+                message: `transclusion cycle: \`#${e.anchor}\` selects the content this embed is part of`,
+                line: e.line,
+            });
+        }
+    }
+}
+// A phrase that projects itself. The same shape as detectSelfEmbedCycles, and
+// deliberately the same machinery rather than a second parallel one: decided on
+// spans, so a projection written anywhere inside its own target is caught.
+function detectSelfProjectionCycles(source, ctx) {
+    const local = (ctx.projections ?? []).filter((p) => p.doc === undefined);
+    if (local.length === 0)
+        return;
+    const spans = blockSpans(source);
+    for (const p of local) {
+        const span = spans.get(p.anchor);
+        if (span === undefined)
+            continue;
+        const line = p.line - 1;
+        if (line >= span.start && line <= span.end) {
+            ctx.diags.push({
+                severity: "error",
+                code: "transclusion-cycle",
+                message: `transclusion cycle: \`![[#${p.anchor}]]\` projects the content it is part of`,
+                line: p.line,
+            });
+        }
+    }
+}
+// Inline content that a projection may stand for: a `text` block whose body is a
+// single paragraph. Returned so the renderer and this validator agree on one
+// definition. Anything else — a heading (and so a whole section), a table, a
+// diagram, a multi-paragraph body — is block content, and no amount of syntax
+// makes it fit inside a sentence.
+export function projectableInlines(blocks, id) {
+    const found = (function find(bs) {
+        for (const b of bs) {
+            if ((b.kind === "block" || b.kind === "heading") && b.id === id)
+                return b;
+            if (b.kind === "block" && b.children) {
+                const inner = find(b.children);
+                if (inner)
+                    return inner;
+            }
+        }
+        return undefined;
+    })(blocks);
+    if (found === undefined)
+        return null;
+    if (found.kind !== "block" || found.type !== "text")
+        return "not-inline";
+    const kids = (found.children ?? []).filter((c) => !(c.kind === "paragraph" && c.text.trim() === ""));
+    if (kids.length !== 1 || kids[0].kind !== "paragraph")
+        return "not-inline";
+    return { inlines: kids[0].inlines };
+}
+// A projection may only stand for inline content, and the target decides — the
+// same shape of rule as `table-source-not-a-table`, not a rule about where the
+// reference was written.
+function validateProjections(children, ctx, opts) {
+    for (const p of ctx.projections ?? []) {
+        let blocks = null;
+        if (p.doc === undefined)
+            blocks = children;
+        else if (opts.resolveDoc) {
+            const src = opts.resolveDoc(p.doc);
+            if (src === null)
+                continue; // already an unresolvable-document error
+            blocks = parse(src).children;
+        }
+        if (blocks === null)
+            continue; // unchecked without a resolver, like any cross-doc ref
+        const got = projectableInlines(blocks, p.anchor);
+        if (got === null)
+            continue; // already an unresolved-reference error
+        if (got === "not-inline") {
+            const target = p.doc === undefined ? `#${p.anchor}` : `${p.doc}#${p.anchor}`;
+            ctx.diags.push({
+                severity: "error",
+                code: "inline-transclusion-not-inline",
+                message: `\`![[${target}]]\` projects inline content, but the target is not a single-paragraph \`text\` block; for block content use \`=== embed {src=${target}}\``,
+                line: p.line,
+            });
+        }
+    }
+}
+// Same pure-string path composition the renderer uses (relJoin/relDir there).
+function relJoinPath(base, target) {
+    if (base === "" || target === "" || target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target))
+        return target;
+    const out = [];
+    for (const s of (base + "/" + target).split("/")) {
+        if (s === "" || s === ".")
+            continue;
+        if (s === ".." && out.length > 0 && out[out.length - 1] !== "..")
+            out.pop();
+        else
+            out.push(s);
+    }
+    return out.join("/");
+}
+function relDirPath(p) {
+    const i = p.lastIndexOf("/");
+    return i < 0 ? "" : p.slice(0, i);
+}
+function gatherEmbeds(source) {
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map(), embeds: [] };
+    scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
+    return (ctx.embeds ?? []).map((e) => (e.anchor === undefined ? { doc: e.doc } : { doc: e.doc, anchor: e.anchor }));
+}
+// One rule for "where this data comes from", shared by a table's `src=`
+// and a chart's `data=`. Three target forms: a data file, `#id` naming a table
+// block in this document, or `doc.geml#id` naming one in another document. An
+// unresolvable target is an error — a table whose source silently produced no
+// rows used to render as an empty table with no diagnostic at all.
+function tableFromDocument(source, id) {
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
+    const blocks = scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
+    const found = ctx.tables?.get(id);
+    if (found !== undefined)
+        return found;
+    const anyBlock = (function find(bs) {
+        for (const b of bs) {
+            if ((b.kind === "block" || b.kind === "heading") && b.id === id)
+                return b;
+            if (b.kind === "block" && b.children) {
+                const inner = find(b.children);
+                if (inner)
+                    return inner;
+            }
+        }
+        return undefined;
+    })(blocks);
+    return anyBlock === undefined ? null : "not-a-table";
+}
+function resolveTableSources(ctx, opts) {
+    const pending = ctx.tableSources ?? [];
+    if (pending.length === 0)
+        return;
+    const err = (line, code, message) => void ctx.diags.push({ severity: "error", code, message, line });
+    // Data files first: a `#id` target may point at a table whose OWN rows come
+    // from a file, and this way that table is already populated when it is read.
+    for (const { block, line, target } of pending) {
+        if (target.includes("#"))
+            continue;
+        // §9.4: a remote source is fetched by the RENDERER, not the parser. Leaving
+        // `model.src` set with no columns is the state resolveCharts already handles,
+        // so a chart over it defers too. Passing it to resolveDoc treated a URL as a
+        // filesystem path and failed a spec-conformant document.
+        const scheme = schemeOf(target);
+        if (scheme === "http" || scheme === "https")
+            continue;
+        if (scheme !== null) {
+            err(line, "unresolvable-table-source", `table source \`${target}\` names a disallowed URL scheme`);
+            continue;
+        }
+        // A data source is data. Without this the loader read any file under the base
+        // — a `.env`, a private key — split it into rows, and put it in the model and
+        // the page, with no diagnostic. `embed` already applies the same shape of rule.
+        if (!/\.(csv|tsv)$/i.test(target)) {
+            err(line, "unresolvable-table-source", `table source \`${target}\` is not a \`.csv\`/\`.tsv\` data file`);
+            continue;
+        }
+        if (!opts.resolveDoc) {
+            ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `table source \`${target}\` not checked (no document resolver)`, line });
+            continue;
+        }
+        const text = opts.resolveDoc(target);
+        if (text === null) {
+            err(line, "unresolvable-table-source", `cannot resolve table source \`${target}\``);
+            continue;
+        }
+        // Reuse the body parser: with `src` dropped, the file's lines are just
+        // this table's body, so format/header/compute/summary all behave identically.
+        const attrs = { ...block.attrs };
+        delete attrs["src"];
+        const { model, diagnostics } = parseTable(normalizeSource(text).split("\n"), attrs, line, ctx);
+        model.src = target;
+        block.table = model;
+        for (const d of diagnostics)
+            ctx.diags.push({ ...d, line });
+        if (block.id !== undefined)
+            (ctx.tables ??= new Map()).set(block.id, model);
+    }
+    for (const { block, line, target } of pending) {
+        const hash = target.indexOf("#");
+        if (hash < 0)
+            continue;
+        const docPath = target.slice(0, hash);
+        const id = target.slice(hash + 1);
+        let model;
+        if (docPath === "") {
+            const local = ctx.tables?.get(id);
+            if (local === undefined) {
+                if (ctx.ids.has(id))
+                    err(line, "table-source-not-a-table", `table source \`#${id}\` is not a table`);
+                else
+                    err(line, "unresolved-reference", `unresolved reference \`#${id}\``);
+                continue;
+            }
+            model = local;
+        }
+        else {
+            if (!opts.resolveDoc) {
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `table source \`${target}\` not checked (no document resolver)`, line });
+                continue;
+            }
+            const text = opts.resolveDoc(docPath);
+            if (text === null) {
+                err(line, "unresolvable-document", `cannot resolve document \`${docPath}\``);
+                continue;
+            }
+            const remote = tableFromDocument(text, id);
+            if (remote === null) {
+                err(line, "unresolved-cross-document-reference", `unresolved reference \`${target}\``);
+                continue;
+            }
+            if (remote === "not-a-table") {
+                err(line, "table-source-not-a-table", `table source \`${target}\` is not a table`);
+                continue;
+            }
+            model = remote;
+        }
+        // Borrowed, not copied in the source: the model is shared, so the borrowing
+        // table means exactly what the original means. Its own caption still wins.
+        const caption = block.table?.caption;
+        block.table = caption === undefined ? model : { ...model, caption };
+        if (block.id !== undefined)
+            (ctx.tables ??= new Map()).set(block.id, block.table);
+    }
+}
 function gatherIds(source) {
     const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
     scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
@@ -512,26 +924,77 @@ function validateRefs(ctx, opts) {
 }
 // §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) {
+function resolveCharts(ctx, opts) {
     for (const { block, line } of ctx.charts ?? []) {
-        const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"] : "";
-        const id = ref.replace(/^#/, "");
-        if (id === "") {
+        const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"].trim() : "";
+        if (ref === "" || ref === "#") {
             ctx.diags.push({ severity: "error", code: "chart-missing-data", message: "geml-chart: missing `data=#id`", line });
             continue;
         }
-        const table = ctx.tables?.get(id);
-        if (!table) {
-            const known = ctx.ids.has(id);
-            const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
-            const code = known ? "chart-data-not-a-table" : "unresolved-reference";
-            ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
-            continue;
+        // `data=` resolves by the same rule as a table's source: `#id` (or a bare id)
+        // names a table in THIS document, `doc.geml#id` one in another. Splitting on
+        // the LAST `#` is what the old code got wrong — it stripped the leading one
+        // and reported `#other.geml#fy25`, a target that never existed.
+        const hash = ref.indexOf("#");
+        const docPath = hash <= 0 ? "" : ref.slice(0, hash);
+        const id = hash < 0 ? ref : ref.slice(hash + 1);
+        let table;
+        if (docPath === "") {
+            table = ctx.tables?.get(id);
+            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
+                // anonymous table with that source, feeding this chart. Nothing new is
+                // invented — the resolution, the `.csv`/`.tsv` gate, the §9.4 remote rule
+                // and `format=` all come from the table rules, which is what makes the one
+                // source rule hold for charts too instead of charts being its exception.
+                if (hash < 0 && /\.(csv|tsv)$/i.test(id)) {
+                    const sugar = chartSourceTable(ctx, opts, block, id, line);
+                    if (sugar === null)
+                        continue; // already reported by the table rules
+                    table = sugar;
+                }
+                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 });
+                    continue;
+                }
+                else {
+                    const known = ctx.ids.has(id);
+                    const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
+                    const code = known ? "chart-data-not-a-table" : "unresolved-reference";
+                    ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
+                    continue;
+                }
+            }
+        }
+        else {
+            if (!opts.resolveDoc) {
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `geml-chart: data target \`${ref}\` not checked (no document resolver)`, line });
+                continue;
+            }
+            const text = opts.resolveDoc(docPath);
+            if (text === null) {
+                ctx.diags.push({ severity: "error", code: "unresolvable-document", message: `geml-chart: cannot resolve document \`${docPath}\``, line });
+                continue;
+            }
+            const remote = tableFromDocument(text, id);
+            if (remote === null) {
+                ctx.diags.push({ severity: "error", code: "unresolved-cross-document-reference", message: `geml-chart: unresolved reference \`${ref}\``, line });
+                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 });
+                continue;
+            }
+            table = remote;
         }
-        if (table.src !== undefined) {
-            // §6: the table's data is external (src=), loaded at render time. The
-            // chart is therefore resolved at render time too — its column references
-            // are checked there, not here — so skip build-time chart resolution.
+        if (table.src !== undefined && table.columns.length === 0) {
+            // §6: the table names a source whose data did not arrive at build time — a
+            // remote URL, or any source with no document resolver supplied. The chart is
+            // therefore resolved at render time, and its column names are checked there.
+            // The test is whether the data is actually here, not what the source looks
+            // like: skipping every `src` table unconditionally is what left a chart
+            // unbuilt with no diagnostic while the page said to go and read one.
             continue;
         }
         const { model, diagnostics } = buildChart(block.attrs, table);
@@ -545,19 +1008,34 @@ export function parse(source, opts = {}) {
     const lines = normalizeSource(source).split("\n");
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
-    resolveCharts(ctx);
+    // 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);
+    resolveCharts(ctx, opts);
     validateRefs(ctx, opts);
+    detectTransclusionCycles(ctx, opts);
+    detectSelfEmbedCycles(source, ctx);
+    validateProjections(children, ctx, opts);
+    detectSelfProjectionCycles(source, ctx);
+    for (const m of ctx.mediaDocTargets ?? []) {
+        ctx.diags.push({
+            severity: "error",
+            code: "media-target-is-document",
+            // `!` projects, so a GEML target here is a near-miss an author will reach for
+            // once that reading is established. Name both forms it could have meant.
+            message: `\`![](${m.src})\` projects a GEML document, which is not media: for block content use \`=== embed {src=${m.src}}\`, for a phrase use \`![[${m.src}]]\``,
+            line: m.line,
+        });
+    }
     return { kind: "document", children, ids: [...ctx.ids.keys()], diagnostics: ctx.diags };
 }
 // The id that a fence/heading line defines, matching how scanBlocks derives it
 // (parseAttrs for the attribute object; heading text slug when no explicit id).
-// The slug MUST come from the INTERPOLATED text — scanBlocks slugs after
-// interpolate(), so `# {{title}} Setup` registers the substituted slug; slugging
-// the raw text here would create a phantom id the parser never registered and
-// make the real one unaddressable. `ctx` is an inert context carrying the
-// document's meta (diagnostics are discarded — spans never report).
+// The slug MUST come from the RAW text, before interpolation, so that changing
+// a meta variable does not silently change the block's addressable id.
+// `ctx` is passed just in case future features need context.
 function idOfHeading(braces, text, line, ctx) {
-    return (braces ? parseAttrs(braces).id : undefined) ?? slug(interpolate(text, line, ctx));
+    return (braces ? parseAttrs(braces).id : undefined) ?? slug(text);
 }
 // The matching close of the fence opened at lines[i] (equal-length run, or the
 // labeled `=== #id` close when the block carries an id): the index just past
@@ -594,7 +1072,7 @@ function sectionEnd(lines, i, level) {
 }
 // Walk `lines` exactly as scanBlocks does — same fence close rules (equal-length
 // or labeled `=== #id`), same flow-only recursion via REGISTRY — recording the
-// source span of every addressable id (typed block, heading, footnote def).
+// source span of every addressable id (typed block, heading).
 // First definition wins, mirroring ctx.ids (a duplicate id is a build error, so
 // `get`/`set` operate on the one the parser actually registered). `base` is the
 // absolute line offset of this slice within the whole document.
@@ -662,8 +1140,8 @@ types) {
 export function blockSpans(source) {
     const out = new Map();
     const lines = normalizeSource(source).split("\n");
-    // Inert context: heading auto-ids slug the interpolated text (parser parity);
-    // its diagnostics are discarded — the span scan never reports.
+    // Inert context: heading auto-ids slug the raw text, but parseDoc still
+    // requires a valid context to parse the document.
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
     collectSpans(lines, 0, out, ctx);
     return out;
@@ -700,8 +1178,8 @@ function toNewline(text, nl) {
     return nl === "\n" ? lf : lf.replace(/\n/g, nl);
 }
 // `--head`: narrow any id's span to its HEAD line — the single declaring line
-// (a heading's `# … {#id}` line, a typed block's opening fence, a footnote's
-// `[^id]:` line). The head is by construction the FIRST line of the span, so
+// (a heading's `# … {#id}` line, or a typed block's opening fence). The head is
+// by construction the FIRST line of the span, so
 // the narrowing is parse-free and needs no type check. Main use: `set --head`
 // edits a block's attributes (caption/compute/lang/…) without re-sending its
 // body, or renames a heading without rewriting its section.
@@ -794,51 +1272,54 @@ export const PARSER_VERSION = (() => {
     }
     return "0.0.0";
 })();
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [-o out]   transform a document (default: --to json)
-                                             --to  <output>: json | html | md | geml
-                                               --to md    -> Markdown (lossy)
-                                               --to html  -> self-contained HTML
-                                               --to geml  -> canonical re-format
-                                               --to json  -> document-model JSON (default)
-                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
-                                               geml notes.md                -> GEML   (md inferred from extension)
-                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
-                                               geml - --from md             read Markdown on stdin
-  geml get    <file.geml|-> [#id] [--json] [--head]   with #id: print that block
-                                             (a heading id = its whole section; --head = head line;
-                                             --json = model node). Without #id: list all addressable
-                                             ids (--json = array).
-  geml set    <file.geml|-> #id [--head|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
-                                             (--in F takes F's block #id, F#src takes #src, else stdin raw;
-                                              default = whole block · --head = head line · --body = body)
-  geml add    <file.geml|-> (--append | --before #id | --after #id) [--in f[#src]|-] [-o f]   insert a fragment
-                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
-  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
-                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
-  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
-  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
-                                             (sel: 0 | -N | id-prefix | changed; default -1)
-  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
-                                             (--root widens cross-doc refs to dir d, e.g. the repo root)
-  geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
-  geml codemap <build|verify|render|serve|refresh|find> [...]       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 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.
 `;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
@@ -851,35 +1332,35 @@ const SUBHELP = {
     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)
+    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 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:
     claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
@@ -1002,7 +1483,7 @@ function runCheck(args) {
         if (!isDir)
             fail(`--root ${root} is not a directory`);
     }
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root) });
+    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     if (json) {
         console.log(JSON.stringify(doc.diagnostics, null, 2));
     }
@@ -1090,7 +1571,15 @@ function runTransform(argv) {
     const out = flag(argv, "-o") ?? flag(argv, "--out");
     const fromRaw = flag(argv, "--from");
     const toRaw = flag(argv, "--to");
-    const [file] = positionals(argv, ["-o", "--out", "--from", "--to"]);
+    // 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
+    // flag — a document whose embeds `check --root .` validated still rendered with
+    // every one of them unresolved, which reads as "transclusion does not work".
+    const root = flag(argv, "--root");
+    if (argv.includes("--root") && root === undefined)
+        fail("--root needs a directory", 2);
+    const [file] = positionals(argv, ["-o", "--out", "--from", "--to", "--root"]);
     if (!file)
         fail("no input file (use '-' to read from stdin)", 2);
     // A bare `--to`/`--from` (no following value) is a mistyped flag, not a
@@ -1149,10 +1638,10 @@ function runTransform(argv) {
     else if (inFmt === "md") {
         const conv = mdToGeml(src);
         notes = conv.notes;
-        doc = parse(conv.geml, { resolveDoc: resolverFor(file) });
+        doc = parse(conv.geml, { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     }
     else {
-        doc = parse(src, { resolveDoc: resolverFor(file) });
+        doc = parse(src, { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     }
     let output;
     switch (outFmt) {
@@ -1166,8 +1655,8 @@ function runTransform(argv) {
             output = renderHtml(doc, {
                 source: file === "-" ? "stdin" : basename(file),
                 // geml-code-graph embeds load + parse sibling codemap docs on demand.
-                loadDoc: resolverFor(file),
-                parseDoc: (s) => parse(s),
+                loadDoc: resolverFor(file, root),
+                parseDoc: (s) => parse(s, { resolveDoc: resolverFor(file, root) }),
             });
             break;
         case "md": {
@@ -1291,7 +1780,7 @@ function resolveSelector(source, file, raw) {
         return bare;
     const level = m[1].length;
     const want = m[2];
-    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const heads = doc.ids.flatMap((id) => {
         const site = findBlockSite(doc.children, id);
         const b = site?.siblings[site.index];
@@ -1330,9 +1819,10 @@ function resolveSelector(source, file, raw) {
 // a heading, its level and text); `--json` is a machine-readable array so an
 // agent can pick its next `get #id` target. Ids are listed in document order
 // (the registration order parse() records), covering the same set `get #id`
-// resolves against: typed blocks, headings, and footnote definitions.
+// 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 doc = parse(source, { resolveDoc: resolverFor(file) });
+    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];
@@ -1340,8 +1830,10 @@ function listIds(source, file, json) {
             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"))
-                row.footnote = true; // §5.2 footnote definition
+                row.footnote = true;
             return row;
         }
         return { id, kind: b?.kind ?? "unknown" };
@@ -1391,7 +1883,7 @@ function getByType(source, file, type, json, headOnly) {
             // 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) }).children, type);
+            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;
@@ -1457,7 +1949,7 @@ function runGet(args) {
     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) });
+        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);
@@ -1532,6 +2024,11 @@ function runSet(args) {
         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("-");
@@ -1655,7 +2152,7 @@ function runAdd(args) {
 // or duplicate id surfaces as an error diagnostic) and no pre-existing id may
 // vanish. Returns the updated text; on any violation fail()s and writes nothing.
 function insertFragment(source, lines, at, fragment, file) {
-    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).ids;
     const before = lines.slice(0, at);
     const after = lines.slice(at);
     const nl = newlineOf(source); // the fragment AND every separator we add
@@ -1672,7 +2169,7 @@ function insertFragment(source, lines, at, fragment, file) {
     const sepBefore = before.length && !blank(before[before.length - 1]) ? nl : "";
     const sepAfter = after.length && !blank(after[0]) ? nl : "";
     const updated = before.join("") + sepBefore + frag + sepAfter + after.join("");
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
@@ -1722,7 +2219,7 @@ function runDelete(args) {
     const updated = splitLines(source).filter((_, i) => !toDelete.has(i)).join("");
     // Lenient guard: surface any resulting error diagnostic (a reference now
     // dangling) as a WARNING, but write regardless.
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     for (const d of reparsed.diagnostics.filter((x) => x.severity === "error")) {
         console.error(`warning: ${d.message} (line ${d.line}) — left dangling by delete; run 'geml check' to see it as an error`);
     }
@@ -1741,7 +2238,7 @@ function runRename(args) {
     if (oldId === newId)
         fail("#old and #new are the same id — nothing to rename", 2);
     const source = readInput(file);
-    const before = parse(source, { resolveDoc: resolverFor(file) });
+    const before = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     if (!before.ids.includes(oldId))
         fail(`no block with id \`${oldId}\``, 1);
     if (before.ids.includes(newId))
@@ -1761,7 +2258,7 @@ function runRename(args) {
         }
     }
     const updated = rewriteId(source, oldId, newId, file);
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const e = errs[0];
@@ -1792,7 +2289,7 @@ function runRename(args) {
 // text, not a reference. (Known residual: id-less raw bodies and inline
 // code/math spans in flow content — see design §8.)
 function rewriteId(source, oldId, newId, file) {
-    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const spans = blockSpans(source);
     const protectedLines = new Set();
     for (const b of doc.children) {
@@ -1900,7 +2397,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const found = blockSpans(source).get(id);
     if (!found)
         fail(`no block with id \`${id}\``, 1);
-    const beforeDoc = parse(source, { resolveDoc: resolverFor(file) });
+    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
     // a single trailing newline so the following block still starts on its own
@@ -1924,7 +2421,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     // surface as error diagnostics (registerId flags dups); one check covers both.
     // Then require the target id to survive, and — because a malformed replacement
     // can swallow a neighbour — that every other pre-existing id survives too.
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
@@ -2107,9 +2604,9 @@ function runRevert(args) {
         return;
     }
     const span = curFull;
-    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).ids;
     const updated = splitLines(source).filter((_, i) => i < span.start || i >= span.end).join("");
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];