@geml/geml 1.7.2 → 1.7.4

package/README.md

@@ -24,7 +24,8 @@ print("hi")
 - **Addressable** — every block can be named: an `#id`, or a content address for
   the ones nobody named; `geml get` / `geml set '<selector>'`
   read or patch one section without re-emitting the whole file (on this repo's
-  own spec, ~**66× less context** than shipping the whole document).
+  own spec, ~**120× less context** than shipping the whole document — the block
+  is ~590 chars whatever the document grows to).
 - **Verifiable** — references are checked at build time (a dangling `#id` is an
   error, not a silent dead link), and the parser emits a document-model JSON
   with a `diagnostics` array, so agents and CI get a structured pass/fail signal.
@@ -101,13 +102,15 @@ geml find   "text" doc.geml|dir     # search block CONTENT -> file<TAB>address;
 geml get    doc.geml ['<selector>'] # list addressable blocks, or print what the selector matches
 geml get    doc.geml '#sec' --intro # a section cuts three ways: --head | --intro | --body
 geml set    doc.geml '<selector>' [--head|--intro|--body] [--in F[#src]]   # replace ONE block's content
+geml replace doc.geml OLD NEW [--within '<selector>']   # EXPERIMENTAL: literal swap, checked and reported
 geml add    doc.geml (--append|--before #id|--after #id) [--in F[#src]]   # insert a fragment
 geml delete doc.geml '#id' ['#id2' …]     # remove one or more blocks
 geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
 geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
 geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
 geml history <save|get|restore|verify> doc.geml [...]   # .gemlhistory version sidecar (get = list revisions, or print one)
-geml codemap <build|verify|render|serve|refresh|find|mcp>      # your codebase's call graph as GEML docs
+geml codemap <build|verify|render|serve|refresh|find>   # your codebase's call graph as GEML docs
+geml mcp    --root <dir> [--graph <dir>]  # serve documents (+ the code graph) over MCP
 geml --help | --version             # --version --json prints {"parser","spec"}
 ```
 
@@ -138,6 +141,15 @@ byte-identical — and `--intro` is how a section's opening is edited without
 pulling its subsections into context. A block has no intro; asking for one is a
 usage error rather than a quiet fall back to the body.
 
+`replace` is the cheap path when the exact old text is already known and nothing
+needs reading — a version string in six places, a term renamed. It is the one
+operation where GEML can beat `sed` outright rather than imitate it: the same
+two short strings, but the result is re-parsed before it lands, the blocks it
+touched are named back to you, and it is in `.gemlhistory` to revert. It swaps a
+LITERAL, never a pattern, and refuses a swap that would rename an id — that is
+`geml rename`, which fixes the references too. **It is EXPERIMENTAL and may be
+withdrawn**; build nothing on it that cannot change.
+
 A write is refused when it would break the document, never merely because it
 removes something. A replacement that drops blocks is carried out and the
 dropped blocks are named on stderr — unnamed ones counted, references left
@@ -234,9 +246,13 @@ Add to your `claude_desktop_config.json`:
 ### Claude Code / CLI Clients
 Run the following command to add the server:
 ```sh
-/mcp add npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
+claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
 ```
 
+With a code graph under `--root` (`geml codemap build`), the same server also
+serves four read-only `geml_codemap_*` tools. Every tool and option:
+[`docs/mcp-guide.md`](https://github.com/geml-spec/geml/blob/main/docs/mcp-guide.md).
+
 ## Library
 
 ```js
@@ -259,6 +275,11 @@ Full normative spec, history-sidecar spec, and format comparison live in the
 [repository](https://github.com/geml-spec/geml). The spec is itself
 written in GEML (`GEML-spec.geml`) and parsed clean on every test run.
 
+What changed between releases:
+[`CHANGELOG.md`](https://github.com/geml-spec/geml/blob/main/CHANGELOG.md).
+The parser and the specification version independently — `geml --version --json`
+prints both.
+
 ## License
 
 MIT.

package/codemap/build.mjs

@@ -513,6 +513,12 @@ console.error(
   + `${stats.containers} containers (${stats.written} of ${stats.docs} files written), `
   + `${(stats.bytes / 1048576).toFixed(2)} MB -> ${outDir}`,
 );
+// A build that deletes files says which ones. Silence here is how the orphans
+// accumulated in the first place — name them, so a rename that drops a whole
+// naming scheme is visible in the log rather than three renamings later.
+if (stats.pruned?.length) {
+  console.error(`  pruned ${stats.pruned.length} document(s) no longer produced: ${stats.pruned.join(", ")}`);
+}
 
 // --history: snapshot every changed document into its .gemlhistory sidecar —
 // the graph's own architectural history (geml history get / revert per node).

package/codemap/emit.mjs

@@ -13,7 +13,7 @@
 // Emission is deterministic: stable sort orders everywhere; a file is only
 // written when its bytes changed (mtime = "what a change touched").
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
 import { buildNormalizer } from "./normalize.mjs";
 
@@ -461,10 +461,40 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     if (!existsSync(p) || readFileSync(p, "utf8") !== content) writeFileSync(p, content);
   }
 
+  // ---- prune documents this build no longer produces ----
+  // A container that stops yielding symbols simply gets no document; without
+  // this, the one written by an earlier build stays behind describing code that
+  // is gone. Those orphans are not inert: `geml check` reads their `src=` line
+  // ranges and fails the build-time reference check, which is how nine of them
+  // — across two renamings of the naming scheme — went unnoticed until one
+  // orphan's source file happened to SHRINK past its recorded line numbers.
+  //
+  // `allDocs` is the authoritative set: every .geml this run emitted, written
+  // or byte-identical. Anything else at the top level of outDir is an orphan.
+  // Two guards keep this from eating a file it does not own: only the top level
+  // is scanned (never _index/, _build/, or any subtree), and a candidate must
+  // carry the generated-document marker `resolution-default` in its head — a
+  // hand-placed .geml parked in the directory is left alone.
+  const pruned = [];
+  const keep = new Set(allDocs);
+  let present = [];
+  try { present = readdirSync(outDir); } catch { present = []; }
+  for (const f of present) {
+    if (!f.endsWith(".geml") || keep.has(f)) continue;
+    const p = join(outDir, f);
+    try {
+      if (!statSync(p).isFile()) continue;
+      if (!/^===\s*meta\b[\s\S]*?\bresolution-default\s*=/.test(readFileSync(p, "utf8").slice(0, 2000))) continue;
+      unlinkSync(p);
+      pruned.push(f);
+    } catch { /* unreadable or already gone — not this build's problem */ }
+  }
+
   return {
     ...stats,
     allDocs,
     writtenDocs,
+    pruned,
     containers: containers.size,
     symbols: symbols.length,
     methods: methods.length,

package/codemap/render-all.mjs

@@ -8,7 +8,7 @@
 // graph area (nested frame), so the whole map is browsable offline — this is
 // the "copy the folder to someone" mode. For a live view that never goes
 // stale, use `geml codemap serve` instead.
-import { readdirSync, readFileSync, writeFileSync, realpathSync } from "node:fs";
+import { readdirSync, readFileSync, writeFileSync, realpathSync, unlinkSync } from "node:fs";
 import { join, basename, sep, resolve as resolvePath } from "node:path";
 import { parse, renderHtml } from "../dist/geml.js";
 
@@ -73,5 +73,18 @@ for (const f of files) {
     console.error(`render: ${f}: ${e.message}`);
   }
 }
+// Each tool prunes what it owns: build removes the documents it no longer
+// produces, and this removes the pages whose document is gone. An orphan page
+// is worse than a stale one — it is unreachable from index.html yet still
+// served, so a copied folder ships a page describing deleted code with no way
+// to notice. Only a `<base>.html` whose `<base>.geml` is absent qualifies, so
+// nothing that has a document behind it is ever touched.
+const prunedPages = [];
+for (const f of files) {
+  if (!f.endsWith(".html")) continue;
+  if (files.includes(f.replace(/\.html$/, ".geml"))) continue;
+  try { unlinkSync(join(dir, f)); prunedPages.push(f); } catch { /* already gone */ }
+}
 console.error(`rendered ${n} page(s) -> ${dir}${failed.length ? `; FAILED: ${failed.join(", ")}` : ""}`);
+if (prunedPages.length) console.error(`  pruned ${prunedPages.length} orphan page(s): ${prunedPages.join(", ")}`);
 process.exit(failed.length ? 1 : 0);

package/dist/cli.js

@@ -147,7 +147,8 @@ Usage:
                                              (call this first — its addresses are what every verb below takes)
   geml find   <pattern> [<file|dir> …] [--json] [--case] [--head]   search block content -> file#address
                                              (an address, not a line number, so a hit pastes into get/set;
-                                              a dir is walked for *.geml; exit 1 when nothing matched)
+                                              a named file is searched whatever its extension, a dir walks
+                                              *.geml only; exit 1 when nothing matched)
   geml get    <file.geml|-> [#id] [--json] [--head|--intro|--body]   with #id: print that block
                                              (a heading id = its whole section; --head = head line;
                                              --json = model node). Without #id: list all addressable
@@ -156,6 +157,7 @@ Usage:
                                              lines, which is how a grep hit or a stack trace becomes
                                              an address.
   geml set    <file.geml|-> #id [--head|--intro|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
+  geml replace <file.geml|-> <old> <new> [--within <selector>] [-o f]   EXPERIMENTAL: swap a literal string, checked and reported
                                              (--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
@@ -173,7 +175,7 @@ Usage:
                                               and re-hash the whole chain)
   geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
   geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
-                                             (10 tools, each geml_ + its CLI command path: list/get/check/history/to +
+                                             (11 tools, each geml_ + its CLI command path: list/find/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)
@@ -200,7 +202,8 @@ const SUBHELP = {
     delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml]  (remove one or more blocks; a missing id is skipped with a note, not an error; a reference left dangling is a warning, not a refusal — delete never fails on a live reference)",
     rename: "usage: geml rename <file.geml|-> #old #new [-o out.geml]  (rewrite an id's declaration AND every reference — [[#id]], [text](#id), chart data=#id, footnote [^id] — id-boundary safe, skipping raw block bodies; #new must be free; refused if it breaks the doc)",
     list: "usage: geml list <file.geml|-> [--json]  (list every addressable block with its shortest unique address, its kind and its line range — the same listing `geml get <file>` prints with no selector, under the name the MCP surface already uses. Call it FIRST: the addresses it prints are what get/set/add/delete/rename/revert all take)",
-    find: "usage: geml find <pattern> [<file.geml|dir> …] [--json] [--case] [--head]  (search block CONTENT and print `<file>TAB<address>` per hit — an address, never a line number, so a hit is `geml get <file> '<address>'` with no editing. The address is the INNERMOST block holding the match, never its enclosing section, and a block is reported once however many lines in it matched. Substring, case-insensitive unless --case; a directory is walked for *.geml; no path = the current directory; --head adds the matching line as a third column. Exit 1 when nothing matched, so `if geml find …` works in a script)",
+    find: "usage: geml find <pattern> [<file|dir> …] [--json] [--case] [--head]  (search block CONTENT and print `<file>TAB<address>` per hit — an address, never a line number, so a hit is `geml get <file> '<address>'` with no editing. The address is the INNERMOST block holding the match, never its enclosing section, and a block is reported once however many lines in it matched. Substring, case-insensitive unless --case; a file you NAME is searched whatever its extension, including Markdown, while a directory is walked for *.geml only; no path = the current directory; --head adds the matching line as a third column. Exit 1 when nothing matched, so `if geml find …` works in a script)",
+    replace: "usage: geml replace <file.geml|-> <old> <new> [--within <selector>] [-o out.geml]  (EXPERIMENTAL — this verb MAY BE WITHDRAWN in a later release; it is here to find out whether an addressed, checked replacement earns its place beside `sed`, and if it does not, it goes. Build nothing on it you cannot change, and say so in a discussion if it is doing real work for you. Swaps a LITERAL string — never a pattern, that is what `sed` is for and where the footguns are. Without --within the whole document; with it, only inside the blocks that selector matches, and unlike `set` it may match several: `--within '=== table'` means every table. What this buys over `sed -i`, at the same cost of two short strings and nothing read: the result is re-parsed and refused if it would break the document, the blocks it touched are NAMED on stderr, and the write lands in .gemlhistory where `revert` can undo it. An id is not text — a replacement that would rename one is refused and points at `geml rename`, which fixes every reference too. Exit 1 when nothing matched, so `if geml replace …` works in a script)",
     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 save    <file.geml> [-m <msg>]      append the working file as a new revision (identical to the tip = no-op)
@@ -637,9 +640,11 @@ function runTransform(argv) {
     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);
+    // Dispatch only lands here when argv[0] is `-` or carries a path character,
+    // and `positionals` keeps both — so there is always a file. A guard for the
+    // empty case would read as a possibility that does not exist; a caller who
+    // writes `geml --to md` is told `unknown command '--to'` at the door.
+    const file = positionals(argv, ["-o", "--out", "--from", "--to", "--root"])[0];
     // A bare `--to`/`--from` (no following value) is a mistyped flag, not a
     // silent fall-through to the default — flag() would return undefined and we
     // must not quietly ignore it.
@@ -1096,7 +1101,14 @@ function runList(args) {
 // platforms — a listing that reorders between machines is a listing nobody can
 // diff. Hidden directories and `node_modules` are skipped: a search verb that
 // dredges up vendored copies trains people to stop reading its output.
-function gemlFilesUnder(path, out) {
+// `explicit` marks a path the caller NAMED, as opposed to one this walk found.
+// A named file is searched whatever it is called: `get` and `list` already read
+// a `.md` this way, and having only `find` refuse meant
+// `geml find GEML README.md` exited 1 against a file holding forty-four
+// matches — a search that answers "no" about a file you pointed straight at.
+// The `.geml` filter belongs to the DIRECTORY walk, where taking every file
+// would drag the whole source tree through the parser.
+function gemlFilesUnder(path, out, explicit = false) {
     let dir = false;
     try {
         dir = statSync(path).isDirectory();
@@ -1105,7 +1117,7 @@ function gemlFilesUnder(path, out) {
         return;
     }
     if (!dir) {
-        if (path.endsWith(".geml"))
+        if (explicit || path.endsWith(".geml"))
             out.push(path);
         return;
     }
@@ -1132,8 +1144,9 @@ function runFind(args) {
     const json = args.includes("--json");
     const needle = sensitive ? pattern : pattern.toLowerCase();
     const files = [];
-    for (const p of pos.slice(1).length ? pos.slice(1) : ["."])
-        gemlFilesUnder(p, files);
+    const named = pos.slice(1);
+    for (const p of named.length ? named : ["."])
+        gemlFilesUnder(p, files, named.length > 0);
     const hits = [];
     for (const f of files) {
         let source;
@@ -1309,6 +1322,126 @@ function runGet(args) {
     for (const u of units)
         process.stdout.write(sliceUnit(source, u.span, part));
 }
+// `geml replace <file> <old> <new> [--within <selector>]` — swap a literal
+// string, everywhere or inside named blocks, without reading the document.
+//
+// This is the one operation where GEML can beat `sed` outright rather than
+// imitate it. The cost is the same — two short strings out, nothing read in —
+// and three things come back that `sed -i` cannot give: the write is re-parsed
+// and refused if it would break the document, the blocks it touched are named,
+// and it lands in `.gemlhistory` where `revert` can undo it. Measured on a real
+// day of editing, ten of fourteen changes were bulk blind replacement done with
+// the original commands; every one of those was an edit that escaped all three.
+//
+// LITERAL, never a pattern. Regular expressions are where `sed` is genuinely
+// better and where the footguns live, and the moment this grows them it stops
+// being "GEML, addressed" and becomes a worse `sed`.
+function runReplace(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const within = flag(args, "--within");
+    const [file, oldText, newText] = positionals(args, ["-o", "--out", "--within"]);
+    if (!file || oldText === undefined || newText === undefined)
+        fail(SUBHELP.replace);
+    if (oldText === "")
+        fail("the text to replace is empty — that would match everywhere", 2);
+    const source = readInput(file);
+    const where = file === "-" ? "stdin" : file;
+    const all = addressedUnits(source);
+    // Scope: the whole document, or every block a selector matches. Several
+    // matches are fine here — `replace … --within '=== table'` meaning "in all
+    // the tables" is the useful reading, and unlike `set` there is no ambiguity
+    // about which one receives the write.
+    const lines = splitLines(source);
+    const lineStart = [];
+    {
+        let at = 0;
+        for (const l of lines) {
+            lineStart.push(at);
+            at += l.length;
+        }
+    }
+    let scopes;
+    if (within === undefined) {
+        scopes = [{ from: 0, to: source.length }];
+    }
+    else {
+        // `selectUnits` already refuses a selector that matches nothing, with the
+        // message the other verbs give, so there is no empty case to handle here.
+        const { units } = selectUnits(source, file, within, where);
+        scopes = units.map((u) => ({
+            from: lineStart[u.span.start],
+            to: u.span.end >= lineStart.length ? source.length : lineStart[u.span.end],
+        }));
+    }
+    // Find every occurrence inside the scopes, right to left, so replacing one
+    // cannot move the ones not yet done.
+    const hits = [];
+    for (const s of scopes) {
+        let at = source.indexOf(oldText, s.from);
+        while (at !== -1 && at + oldText.length <= s.to) {
+            hits.push(at);
+            at = source.indexOf(oldText, at + oldText.length);
+        }
+    }
+    hits.sort((a, b) => a - b);
+    if (hits.length === 0) {
+        // Exit 1 like `find`, so `if geml replace …` means what it looks like.
+        fail(`\`${oldText}\` does not occur in ${within === undefined ? where : `\`${within}\` of ${where}`} — nothing written`, 1);
+    }
+    let updated = source;
+    for (const at of [...hits].reverse()) {
+        updated = updated.slice(0, at) + newText + updated.slice(at + oldText.length);
+    }
+    // Which blocks were touched — the report has to speak in addresses, or this
+    // is just `sed` with a longer name.
+    const lineOf = (off) => {
+        let lo = 0, hi = lineStart.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (lineStart[mid] <= off)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo;
+    };
+    const touched = new Set();
+    for (const at of hits) {
+        const ln = lineOf(at);
+        let best;
+        for (const a of all) {
+            if (a.unit.span.start <= ln && ln < a.unit.span.end) {
+                if (!best || (a.unit.span.end - a.unit.span.start) < (best.unit.span.end - best.unit.span.start))
+                    best = a;
+            }
+        }
+        if (best)
+            touched.add(shortestAddress(best, all));
+    }
+    // An id is not text to be swapped: changing one silently cuts every reference
+    // to it, which is precisely what `rename` exists to do properly.
+    const before = parse(source, { ...docOpts(file) });
+    const after = parse(updated, { ...docOpts(file), self: file === "-" ? undefined : basename(file) });
+    const goneIds = before.ids.filter((x) => !new Set(after.ids).has(x));
+    const newIds = after.ids.filter((x) => !new Set(before.ids).has(x));
+    if (goneIds.length && newIds.length) {
+        fail(`that would rename \`#${goneIds[0]}\` to \`#${newIds[0]}\` — an id is not text: use \`geml rename ${where} '#${goneIds[0]}' '#${newIds[0]}'\`, which fixes every reference too. Nothing written`, 2);
+    }
+    const errs = after.diagnostics.filter((d) => d.severity === "error");
+    if (errs.length) {
+        refuseBroken(`the replacement would break the document: ${errs[0].message} (line ${errs[0].line}); nothing written`, errs);
+    }
+    // Blocks the replacement removed follow `set`'s rule: carried out, and named.
+    const droppedAnon = Math.max(0, countBlockUnits(source) - countBlockUnits(updated) - goneIds.length);
+    if (goneIds.length || droppedAnon) {
+        const named = goneIds.map((x) => `\`#${x}\``).join(", ");
+        const anon = droppedAnon ? `${droppedAnon} unnamed block${droppedAnon > 1 ? "s" : ""}` : "";
+        console.error(`dropped ${[named, anon].filter(Boolean).join(" and ")} — run 'geml revert' to put them back`);
+    }
+    resolveOutTarget(file, out).write(updated);
+    const list = [...touched].join(", ");
+    console.error(`replaced ${hits.length} occurrence${hits.length > 1 ? "s" : ""}${list ? ` in ${list}` : ""}`);
+}
 const NO_CONTENT = "no replacement content (use --in FILE or pipe it on stdin)";
 // `geml set <file.geml|-> #id [--head|--body] [--in F|F#src|-] [-o out]` —
 // replace ONE existing block, addressed by #id, with new content, preserving
@@ -2392,6 +2525,9 @@ const entry = (() => {
     else if (cmd === "set") {
         runSet(argv.slice(1));
     }
+    else if (cmd === "replace") {
+        runReplace(argv.slice(1));
+    }
     else if (cmd === "add") {
         runAdd(argv.slice(1));
     }

package/dist/geml.js

@@ -1137,6 +1137,31 @@ function validateRefs(ctx, opts) {
         if (ref.kind === "cross") {
             if (!ref.doc)
                 continue;
+            // WHAT `#frag` MEANS IS THE TARGET FORMAT'S BUSINESS, and GEML only
+            // defines it for GEML. In `page.html#sec` the fragment is an element id;
+            // in `notes.md#sec` it is a forge's heading slug or an `<a id>`. Reading
+            // either with GEML's own rules got both directions wrong: it accepted
+            // `{#brace}` that no forge resolves, refused `<a id="x">` and slug
+            // anchors that every forge does, and — this is the part that makes the
+            // check untrustworthy rather than merely strict — passed by ACCIDENT
+            // whenever the name happened to appear anywhere in the target, which is
+            // how this repo's own `../GEML-spec.md#appendix-a-diagnostic-catalogue`
+            // was green: that string is in a LINK there, not a definition.
+            //
+            // So the document must still resolve — a link to a file that is not
+            // there is broken whatever its format — and the fragment is left to the
+            // format that owns it. Same lesson as directories: do not judge another
+            // convention by GEML's rules; a check that guesses teaches people to
+            // ignore it.
+            const gemlTarget = /\.geml$/i.test(ref.doc);
+            if (!gemlTarget && ref.anchor !== undefined && opts.resolveDoc) {
+                // The document still has to be there — a link to a missing file is
+                // broken whatever its format — but nothing here reads its fragment.
+                if (opts.resolveDoc(ref.doc) === null && !opts.docExists?.(ref.doc)) {
+                    ctx.diags.push({ severity: "error", code: "unresolvable-document", message: `cannot resolve document \`${ref.doc}\``, line: ref.line });
+                }
+                continue;
+            }
             if (!opts.resolveDoc) {
                 ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `cross-document reference \`${ref.doc}${ref.anchor ? "#" + ref.anchor : ""}\` not checked (no document resolver)`, line: ref.line });
                 continue;

package/dist/mcp.js

@@ -275,7 +275,7 @@ export const TOOLS = [
     },
     {
         name: "geml_find",
-        description: "Search block CONTENT across the served documents and get back ADDRESSES, one row of `<file>\\t<address>` per hit. This is the other half of geml_list: `list` says what a document contains, `find` says which block holds the words you are looking for — and it answers with an address that pastes straight into geml_get or geml_set, never a line number that the next edit invalidates. The address is the innermost block holding the match, and a block that matches on many lines is reported once. Substring, case-insensitive unless `case` is true. Omit `path` to search every `*.geml` under the server root, or give a file or directory to narrow it. No match is not an error: the result is empty.",
+        description: "Search block CONTENT across the served documents and get back ADDRESSES, one row of `<file>\\t<address>` per hit. This is the other half of geml_list: `list` says what a document contains, `find` says which block holds the words you are looking for — and it answers with an address that pastes straight into geml_get or geml_set, never a line number that the next edit invalidates. The address is the innermost block holding the match, and a block that matches on many lines is reported once. Substring, case-insensitive unless `case` is true. Omit `path` to search every `*.geml` under the server root, or give a file or directory to narrow it — a file you name is searched whatever its extension, Markdown included, while a directory walks `*.geml` only. No match is not an error: the result is empty.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geml/geml",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "mcpName": "io.github.geml-spec/geml",
   "publishConfig": {
     "access": "public"

package/skill/SKILL.md

@@ -58,9 +58,12 @@ already; none is ever created for you. `--dry-run` shows what it would do.
 
 ```sh
 geml list    file.geml                # CALL THIS FIRST — every block, its address, kind, lines
-geml find    "text" file.geml|dir     # search block CONTENT -> file<TAB>address (exit 1 = no hit)
+geml find    "text" file|dir          # search block CONTENT -> file<TAB>address (exit 1 = no hit)
+                                      # a NAMED file is searched whatever its extension (.md too);
+                                      # a directory walks *.geml only
 geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
 geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
+geml replace file.geml OLD NEW        # EXPERIMENTAL literal swap; --within '#id' to narrow
 geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
 geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
 ```
@@ -78,6 +81,15 @@ under it, so it always contains the intro). `--intro` is how you edit a
 section's opening without pulling its subsections into context, and setting an
 empty one writes an opening where the section had none.
 
+When the exact old text is already known and nothing needs reading — a version
+string in six places, a renamed term — `geml replace` is the cheap path, and the
+one to prefer over dropping to `sed`: same two short strings, but the result is
+re-parsed before it lands, the blocks it touched are named back to you, and it
+is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern, and refuses
+a swap that would rename an id (use `geml rename`, which fixes the references
+too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but do not
+build anything on it that cannot change.
+
 A write is refused when it would break the document, never merely because it
 removes something: a replacement that drops blocks is carried out and NAMED on
 stderr — unnamed blocks included — with `geml revert` as the way back. Read,

package/skill/references/authoring.geml

@@ -215,7 +215,10 @@ All commands accept `-` to read from stdin.
 === code {#cli-verbs lang=sh}
 geml file.geml                        # document-model JSON (default --to json)
 geml list    file.geml                # CALL FIRST: every block, its address, kind, line range
-geml find    "text" file.geml|dir     # search block CONTENT -> file<TAB>address; exit 1 = no hit
+geml find    "text" file|dir          # search block CONTENT -> file<TAB>address; exit 1 = no hit
+                                      # a NAMED file is searched whatever its extension — `list`,
+                                      # `get` and `find` all read Markdown, so this addresses a
+                                      # plain README without converting it; a DIRECTORY walks *.geml
 geml get     file.geml                # same listing as `list` (the no-selector default)
 geml get     file.geml '#id'          # print ONE block (raw span; --json = model node)
 geml get     file.geml '=== note'     # every block of a type; '@a3f9c1d2' = a block with no #id
@@ -223,6 +226,8 @@ geml get     file.geml 'L27-58'       # position: the smallest block holding tho
 geml get     file.geml '#sec' --intro # a section cut three ways: --head | --intro | --body
 geml set     file.geml '#id' --in f   # replace ONE block (guarded: re-parsed, never writes broken)
 geml set     file.geml '#sec' --intro # replace just the opening; the subsections stay put
+geml replace file.geml OLD NEW        # EXPERIMENTAL, may be withdrawn: literal swap, checked and
+                                      # reported; --within '#id' or '=== type' narrows the scope
 geml add     file.geml --after '#id' --in f   # insert a fragment (keeps its own ids)
 geml delete  file.geml '#id' ['#id2']         # remove one or more blocks
 geml rename  file.geml '#old' '#new'          # rename an id AND every reference to it