@geml/geml 1.4.3 → 1.4.4

package/dist/geml.d.ts

@@ -71,3 +71,4 @@ export interface Span {
     end: number;
 }
 export declare function blockSpans(source: string): Map<string, Span>;
+export declare const PARSER_VERSION: string;

package/dist/geml.js

@@ -668,6 +668,22 @@ export function blockSpans(source) {
 function splitLines(source) {
     return source.split(/(?<=\n|\r(?!\n))/);
 }
+// Newline handling lives HERE, in one place, because it is easy to get subtly
+// wrong in each caller. Content reaching a mutation is often LF even when the
+// document is not: a history revision is stored newline-normalized, `--in` may
+// come from either kind of file, stdin from anywhere. So: detect the DOCUMENT's
+// style, compare on the normalized (LF) form, and convert back on the way in —
+// which is what keeps a CRLF document from ending up half CRLF, half LF.
+function newlineOf(text) {
+    return /\r\n/.test(text) ? "\r\n" : "\n";
+}
+function toLf(text) {
+    return text.replace(/\r\n?/g, "\n");
+}
+function toNewline(text, nl) {
+    const lf = toLf(text);
+    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
@@ -737,7 +753,32 @@ function parseStamp(s) {
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
 const VERSION = "1.0"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.4.3"; // reference implementation; keep in sync with package.json
+// The published version, read from package.json rather than restated here.
+// "Keep in sync with package.json" was a comment, and comments do not run: this
+// literal said 1.4.3 while the MCP server's own copy still said 0.1.0.
+// Resolved from this module's location — `dist/geml.js` -> `../package.json`,
+// and npm always ships package.json whatever `files` says. In a browser bundle
+// `import.meta.url` degenerates to "" (see the `entry` note below), so every
+// lookup fails and we fall back rather than throw at import time.
+export const PARSER_VERSION = (() => {
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return "0.0.0";
+    }
+    for (let i = 0; i < 3 && dir; i++) {
+        try {
+            const v = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+            if (typeof v === "string" && v)
+                return v;
+        }
+        catch { /* not here — walk up */ }
+        dir = dirname(dir);
+    }
+    return "0.0.0";
+})();
 const USAGE = `geml — GEML reference CLI
 
 Usage:
@@ -769,7 +810,7 @@ Usage:
                                              (--root widens cross-doc refs to dir d, e.g. the repo root)
   geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
   geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
-  geml mcp    --workspace <dir> [--no-history]   serve document CRUD over MCP (stdio)
+  geml mcp    --root <dir> [--no-history]        serve document CRUD over MCP (stdio)
                                              (9 tools: list/read/check/history + write/add/delete/rename/revert;
                                               every write is validated before it reaches disk)
   geml --help | --version [--json]
@@ -802,21 +843,21 @@ const SUBHELP = {
        geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
        geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
-    mcp: `usage: geml mcp --workspace <dir> [--no-history]
+    mcp: `usage: geml mcp --root <dir> [--no-history]
 
   Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
   Nine tools: geml_list_ids · geml_read_block · geml_check · geml_history_log
               geml_write_block · geml_add_block · geml_delete_block
               geml_rename_id · geml_revert_block
 
-  --workspace <dir>   REQUIRED. Root holding the .geml documents. Every path a
+  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
                       client names is confined here; a client cannot widen it.
   --no-history        Skip the .gemlhistory commit taken before each write
                       (default: commit, so geml_revert_block always has a
                       revision to undo to).
 
   Register with a client:
-    claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs`,
+    claude mcp add geml -- geml mcp --root /abs/path/to/docs`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
 // envelope so an agent that standardizes on --json never has to parse text.
@@ -1394,7 +1435,7 @@ function runSetBody(source, id, from, rawChannel, file, out) {
     let head = headLine;
     if (head !== "" && !/(\r\n|\r|\n)$/.test(head))
         head += "\n";
-    let b = body.replace(/\r\n?/g, "\n");
+    let b = toLf(body); // spliceBlock converts the result to the document's style
     if (closeLine !== null && b !== "" && !b.endsWith("\n"))
         b += "\n";
     const replacement = closeLine !== null ? head + b + closeLine : head + b;
@@ -1462,18 +1503,19 @@ function insertFragment(source, lines, at, fragment, file) {
     const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
     const before = lines.slice(0, at);
     const after = lines.slice(at);
+    const nl = newlineOf(source); // the fragment AND every separator we add
     // The preceding line must end in a newline so the fragment starts on its own.
     if (before.length && !/(\r\n|\r|\n)$/.test(before[before.length - 1])) {
-        before[before.length - 1] += "\n";
+        before[before.length - 1] += nl;
     }
-    let frag = fragment.replace(/\r\n?/g, "\n");
+    let frag = toNewline(fragment, nl);
     if (!frag.endsWith("\n"))
-        frag += "\n";
+        frag += nl;
     // A single blank separator on each side that has adjacent content and isn't
     // already blank — keeps a following head / preceding block from fusing.
     const blank = (s) => stripEol(s).trim() === "";
-    const sepBefore = before.length && !blank(before[before.length - 1]) ? "\n" : "";
-    const sepAfter = after.length && !blank(after[0]) ? "\n" : "";
+    const 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 errs = reparsed.diagnostics.filter((d) => d.severity === "error");
@@ -1717,10 +1759,11 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const span = headOnly ? narrowToHead(found) : found;
     const before = orig.slice(0, span.start);
     const after = orig.slice(span.end);
-    let inject = replacement.replace(/\r\n?/g, "\n");
+    const nl = newlineOf(source); // adopt the document's style, not LF
+    let inject = toNewline(replacement, nl);
     const lastLine = span.end >= orig.length;
     if (!inject.endsWith("\n") && !lastLine)
-        inject += "\n";
+        inject += nl;
     const updated = before.join("") + inject + after.join("");
     // Re-parse and refuse a broken result. A parse error or a duplicate id both
     // surface as error diagnostics (registerId flags dups); one check covers both.
@@ -1786,6 +1829,13 @@ function runRevert(args) {
     const id = rawId.replace(/^#/, "");
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const source = readInput(file);
+    // The sidecar stores every revision newline-NORMALIZED (history.ts), so a
+    // revision's text always comes back LF while the working file may be CRLF.
+    // Comparing those raw would make EVERY block look changed on a CRLF document
+    // (`--rev changed` reverting blocks nobody touched, and the no-op check never
+    // firing), so compare normalized and write back in the file's own style.
+    const norm = toLf; // compare on the LF form
+    const toFileNl = (s) => toNewline(s, newlineOf(source));
     const curFull = blockSpans(source).get(id); // undefined => absent now
     const curBlock = curFull === undefined ? undefined : (() => {
         const span = headOnly ? narrowToHead(curFull) : curFull;
@@ -1804,7 +1854,8 @@ function runRevert(args) {
     const target = (() => {
         try {
             if (changed) {
-                const found = firstChangedContent(historyPath, curBlock ?? "", pick);
+                // `pick` reads normalized revision text, so normalize this side too.
+                const found = firstChangedContent(historyPath, curBlock === undefined ? "" : norm(curBlock), pick);
                 if (!found)
                     fail(`no earlier revision changes \`${id}\``, 1);
                 return found;
@@ -1831,7 +1882,7 @@ function runRevert(args) {
     }
     // both present -> SPLICE (undo set)
     if (curBlock !== undefined && oldBlock !== undefined) {
-        if (oldBlock === curBlock) {
+        if (norm(oldBlock) === norm(curBlock)) {
             console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --rev -2, or --rev changed)"}`);
             // A no-op still has to PRODUCE the document when an output destination was
             // asked for: `-o` means "write the result somewhere", and the result of a
@@ -1842,12 +1893,13 @@ function runRevert(args) {
                 emit(source, `#${id} unchanged`);
             return;
         }
+        const replacement = toFileNl(oldBlock); // keep the file's newline style
         if (dryRun) {
             console.error(`would revert #${id} to ${target.id}:`);
-            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            process.stdout.write(replacement.endsWith("\n") ? replacement : replacement + "\n");
             return;
         }
-        emit(spliceBlock(source, id, oldBlock, file, headOnly), `reverted #${id} to ${target.id}`);
+        emit(spliceBlock(source, id, replacement, file, headOnly), `reverted #${id} to ${target.id}`);
         return;
     }
     // --head is only meaningful for the splice cell (it can't resurrect or remove).
@@ -1859,24 +1911,25 @@ function runRevert(args) {
         // Guard: if the block we'd resurrect is the same (modulo id) as one already
         // present under a different id, #id was likely renamed away — resurrecting
         // would duplicate it. Point at `rename` instead of writing.
-        const cmpKey = normalizeBlockId(oldBlock, "__cmp__");
+        const cmpKey = normalizeBlockId(norm(oldBlock), "__cmp__");
         for (const [cid, cs] of blockSpans(source)) {
             if (cid === id)
                 continue;
             const csrc = splitLines(source).slice(cs.start, cs.end).join("");
-            if (normalizeBlockId(csrc, "__cmp__") === cmpKey) {
+            if (normalizeBlockId(norm(csrc), "__cmp__") === cmpKey) {
                 fail(`#${id} looks renamed to #${cid}; use 'rename #${cid} #${id}' to undo the rename`, 1);
             }
         }
         const { at, where, warn } = resurrectPosition(source, target.text, id, before, after, append, file);
+        const fragment = toFileNl(oldBlock); // keep the file's newline style
         if (dryRun) {
             console.error(`would resurrect #${id} from ${target.id} at ${where}:`);
-            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            process.stdout.write(fragment.endsWith("\n") ? fragment : fragment + "\n");
             return;
         }
         if (warn)
             console.error(`warning: anchors for #${id} are gone; appended at end`);
-        emit(insertFragment(source, splitLines(source), at, oldBlock, file), `resurrected #${id} from ${target.id} at ${where}`);
+        emit(insertFragment(source, splitLines(source), at, fragment, file), `resurrected #${id} from ${target.id} at ${where}`);
         return;
     }
     // present now, absent at R -> REMOVE (undo add)
@@ -1884,7 +1937,7 @@ function runRevert(args) {
     // under a different id, #id was likely renamed IN — removing would delete a
     // renamed block. Point at `rename` instead (the dangerous direction).
     {
-        const cmpKey = normalizeBlockId(curBlock, "__cmp__");
+        const cmpKey = normalizeBlockId(norm(curBlock), "__cmp__");
         for (const [rid, rs] of blockSpans(target.text)) {
             if (rid === id)
                 continue;

package/dist/mcp.d.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 export interface McpOptions {
-    workspace: string;
+    root: string;
     history: boolean;
 }
 /** Configure the server. Exported so the suite can point it at a temp dir. */
 export declare function configure(o: Partial<McpOptions>): McpOptions;
-export declare function resolveInWorkspace(file: string): string;
+export declare function resolveInRoot(file: string): string;
 export interface Tool {
     name: string;
     description: string;
@@ -14,5 +14,5 @@ export interface Tool {
 }
 export declare const TOOLS: Tool[];
 export declare function handleLine(line: string, write?: (s: string) => void): void;
-export declare const MCP_USAGE = "usage: geml mcp --workspace <dir> [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).\n\n  --workspace <dir>   REQUIRED. Root directory holding the .geml documents.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --no-history        Do not auto-commit a .gemlhistory revision before each\n                      write. Default is to commit, so geml_revert_block always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs";
+export declare const MCP_USAGE = "usage: geml mcp --root <dir> [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).\n\n  --root <dir>        REQUIRED. Root directory holding the .geml documents.\n                      Relative paths resolve against the server process's CWD,\n                      which the CLIENT chooses \u2014 pass an absolute path.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --no-history        Do not auto-commit a .gemlhistory revision before each\n                      write. Default is to commit, so geml_revert_block always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml -- geml mcp --root /abs/path/to/docs";
 export declare function parseArgs(args: string[]): McpOptions;

package/dist/mcp.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // `geml mcp` — MCP server for GEML document CRUD.
 //
-// Nine tools over a confined workspace of `.geml` documents: four read-only,
+// Nine tools over a confined root directory of `.geml` documents: four read-only,
 // five that write. It is the document-editing counterpart to the read-only
 // code-graph server in `codemap/mcp-server.mjs`, and deliberately mirrors its
 // shape (newline-delimited JSON-RPC 2.0 over stdio, zero dependencies, an
 // exported `handleLine` so the suite can drive it in-process).
 //
-//   claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs
+//   claude mcp add geml -- geml mcp --root /abs/path/to/docs
 //
 // Three invariants make this worth more than letting a model `str_replace` the
 // file itself:
@@ -20,7 +20,7 @@
 //   2. EVERY WRITE IS PRECEDED BY A HISTORY COMMIT, so `geml_revert_block` can
 //      always undo the block that was just touched. Without this the strongest
 //      tool in the set would have nothing to revert to.
-//   3. EVERY PATH IS CONFINED to a server-side `--workspace` root the client
+//   3. EVERY PATH IS CONFINED to a server-side `--root` directory the client
 //      cannot override or widen.
 //
 // The mutations run through the CLI rather than re-implementing block editing:
@@ -32,10 +32,14 @@ import { resolve, dirname, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { parse } from "./geml.js";
+import { parse, PARSER_VERSION } from "./geml.js";
 import { commit, listRevisions, isCurrent } from "./history.js";
-const SERVER_VERSION = "0.1.0";
-let OPTS = { workspace: process.cwd(), history: true };
+// One version for the whole package: `geml --version` and the MCP handshake
+// must not disagree. This used to be its own literal and had drifted to 0.1.0
+// against a 1.4.x package — invisible to everyone except the user reading their
+// client's server list.
+const SERVER_VERSION = PARSER_VERSION;
+let OPTS = { root: process.cwd(), history: true };
 /** Configure the server. Exported so the suite can point it at a temp dir. */
 export function configure(o) {
     OPTS = { ...OPTS, ...o };
@@ -45,47 +49,47 @@ export function configure(o) {
 // Workspace confinement
 // ---------------------------------------------------------------------------
 // `file` is client-supplied, so `../../../etc/passwd` — or a symlink planted
-// inside the workspace that points out of it — must not resolve. Canonicalize
+// inside the root that points out of it — must not resolve. Canonicalize
 // BOTH sides with realpathSync (which follows every link component) and require
 // the real target to sit at or under the real root. Unlike the code-graph
 // server, whose `graph_dir` is intentionally client-chosen, the root here is
 // fixed by the operator at startup: this server WRITES, so a client that could
 // name its own root could write anywhere.
-export function resolveInWorkspace(file) {
+export function resolveInRoot(file) {
     if (typeof file !== "string" || file === "")
         throw new Error("`file` is required");
-    const root = realpathSync(OPTS.workspace);
+    const root = realpathSync(OPTS.root);
     const target = resolve(root, file);
     let real;
     try {
         real = realpathSync(target);
     }
     catch {
-        throw new Error(`no such file in the workspace: ${file}`);
+        throw new Error(`no such file under the server root: ${file}`);
     }
     if (real !== root && !real.startsWith(root + sep)) {
-        throw new Error(`path escapes the workspace: ${file}`);
+        throw new Error(`path escapes the server root: ${file}`);
     }
     if (!statSync(real).isFile())
         throw new Error(`not a file: ${file}`);
     return real;
 }
-// Cross-document references resolve against the workspace root, never against
+// Cross-document references resolve against the SERVER root, never against
 // a client-named directory: `root` may only NARROW to a directory inside it.
 function resolveRoot(root) {
-    const ws = realpathSync(OPTS.workspace);
+    const serverRoot = realpathSync(OPTS.root);
     if (root === undefined || root === "")
-        return ws;
-    const target = resolve(ws, root);
+        return serverRoot;
+    const target = resolve(serverRoot, root);
     let real;
     try {
         real = realpathSync(target);
     }
     catch {
-        throw new Error(`no such directory in the workspace: ${root}`);
+        throw new Error(`no such directory under the server root: ${root}`);
     }
-    if (real !== ws && !real.startsWith(ws + sep))
-        throw new Error(`root escapes the workspace: ${root}`);
+    if (real !== serverRoot && !real.startsWith(serverRoot + sep))
+        throw new Error(`root escapes the server root: ${root}`);
     return real;
 }
 // ---------------------------------------------------------------------------
@@ -130,9 +134,9 @@ function parseRefusal(stderr) {
 }
 const asText = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 1));
 function applyWrite(spec) {
-    const real = resolveInWorkspace(spec.file);
+    const real = resolveInRoot(spec.file);
     const before = readFileSync(real, "utf8");
-    const root = realpathSync(OPTS.workspace);
+    const root = realpathSync(OPTS.root);
     const errorKey = (d) => `${d.code}:${d.message}`;
     const preexisting = new Set(parse(before, { resolveDoc: docResolver(root) }).diagnostics
         .filter((d) => d.severity === "error")
@@ -206,7 +210,7 @@ function docResolver(root) {
     };
 }
 const hashId = (id) => (id.startsWith("#") ? id : `#${id}`);
-const FILE_ARG = { type: "string", description: "Document path relative to the server's --workspace root, e.g. notes/spec.geml" };
+const FILE_ARG = { type: "string", description: "Document path relative to the server's --root directory, e.g. notes/spec.geml" };
 export const TOOLS = [
     // ----- read -----
     {
@@ -214,7 +218,7 @@ export const TOOLS = [
         description: "List every addressable block in a GEML document: its `#id`, kind, and heading text. Call this FIRST — the ids it returns are what every other tool in this server addresses. Cheaper and more reliable than reading the file to find out what is in it.",
         inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const run = runCli(["get", real, "--json"]);
             if (!run.ok)
                 throw new Error(run.stderr || "could not list ids");
@@ -233,7 +237,7 @@ export const TOOLS = [
             required: ["file", "id"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const run = runCli(["get", real, hashId(args.id)]);
             if (!run.ok)
                 throw new Error(run.stderr || `no block with id ${hashId(args.id)}`);
@@ -247,12 +251,12 @@ export const TOOLS = [
             type: "object",
             properties: {
                 file: FILE_ARG,
-                root: { type: "string", description: "Directory (inside the workspace) against which cross-document references resolve. Defaults to the workspace root." },
+                root: { type: "string", description: "Directory (inside the server root) against which cross-document references resolve. Defaults to the server root itself. This is a REFERENCE root and is distinct from the server's own --root sandbox, which it can only narrow." },
             },
             required: ["file"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const root = resolveRoot(args.root);
             const doc = parse(readFileSync(real, "utf8"), { resolveDoc: docResolver(root) });
             const errors = doc.diagnostics.filter((d) => d.severity === "error").length;
@@ -270,7 +274,7 @@ export const TOOLS = [
         description: "List the recorded revisions of a document, newest first. Each entry's `offset` is the selector `geml_revert_block` takes as `rev` (-1 is the revision before the current one). Use this to find WHICH revision to revert a block to; an empty list means the document has no sidecar yet and nothing can be reverted.",
         inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const historyPath = real.replace(/\.geml$/, "") + ".gemlhistory";
             if (!existsSync(historyPath))
                 return { file: args.file, revisions: [], note: "no .gemlhistory sidecar yet — the first write through this server creates one" };
@@ -292,7 +296,7 @@ export const TOOLS = [
             required: ["file", "id", "body"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const part = args.part ?? "whole";
             if (!["whole", "head", "body"].includes(part))
                 throw new Error(`part must be whole|head|body, got \`${part}\``);
@@ -319,7 +323,7 @@ export const TOOLS = [
             required: ["file", "content", "position"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             let where;
             if (args.position === "append")
                 where = ["--append"];
@@ -350,7 +354,7 @@ export const TOOLS = [
             required: ["file", "ids"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const ids = Array.isArray(args.ids) ? args.ids : [args.ids];
             if (!ids.length)
                 throw new Error("`ids` must name at least one block");
@@ -375,7 +379,7 @@ export const TOOLS = [
             required: ["file", "old", "new"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             return applyWrite({
                 file: args.file,
                 cliArgs: ["rename", real, hashId(args.old), hashId(args.new), "-o", "-"],
@@ -396,7 +400,7 @@ export const TOOLS = [
             required: ["file", "id"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             // Default to `--rev changed`, NOT the tip (`0`) or the CLI's own `-1`. Each
             // write commits the PRE-write state, so the tip undoes the block only when
             // it was the MOST RECENT write — a later write to ANOTHER block moves the
@@ -434,7 +438,7 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
             reply(id, {
                 protocolVersion: params?.protocolVersion ?? "2024-11-05",
                 capabilities: { tools: {} },
-                serverInfo: { name: "geml-docs", version: SERVER_VERSION },
+                serverInfo: { name: "geml", version: SERVER_VERSION },
             });
         }
         else if (method?.startsWith("notifications/")) {
@@ -475,11 +479,13 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
-export const MCP_USAGE = `usage: geml mcp --workspace <dir> [--no-history]
+export const MCP_USAGE = `usage: geml mcp --root <dir> [--no-history]
 
   Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
 
-  --workspace <dir>   REQUIRED. Root directory holding the .geml documents.
+  --root <dir>        REQUIRED. Root directory holding the .geml documents.
+                      Relative paths resolve against the server process's CWD,
+                      which the CLIENT chooses — pass an absolute path.
                       Every path a client names is confined to this directory;
                       a client cannot widen or override it.
   --no-history        Do not auto-commit a .gemlhistory revision before each
@@ -487,27 +493,36 @@ export const MCP_USAGE = `usage: geml mcp --workspace <dir> [--no-history]
                       has a revision to undo to.
 
   Register with a client:
-    claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs`;
+    claude mcp add geml -- geml mcp --root /abs/path/to/docs`;
 export function parseArgs(args) {
-    let workspace;
+    let root;
     let history = true;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === "--workspace" || a === "-w")
-            workspace = args[++i];
-        else if (a.startsWith("--workspace="))
-            workspace = a.slice("--workspace=".length);
+        if (a === "--root" || a === "-r")
+            root = args[++i];
+        else if (a.startsWith("--root="))
+            root = a.slice("--root=".length);
         else if (a === "--no-history")
             history = false;
+        // The flag used to be --workspace/-w. Name the replacement instead of
+        // failing with a bare `unknown option`: this runs inside a client's server
+        // config, where the only thing the user sees is that the server did not
+        // start, and guessing from `unknown option '--workspace'` is a bad evening.
+        else if (a === "--workspace" || a === "-w" || a.startsWith("--workspace=")) {
+            throw new Error("--workspace is now --root (same meaning: the one directory the server may read and write)");
+        }
         else
             throw new Error(`unknown option '${a}'`);
     }
-    if (!workspace)
-        throw new Error("--workspace <dir> is required (the root the server may read and write)");
-    const abs = resolve(workspace);
+    if (!root)
+        throw new Error("--root <dir> is required (the one directory the server may read and write)");
+    // Relative paths resolve against THIS process's cwd, which an MCP client
+    // picks — so they work from a shell and are a coin flip from a client config.
+    const abs = resolve(root);
     if (!existsSync(abs) || !statSync(abs).isDirectory())
-        throw new Error(`--workspace is not a directory: ${workspace}`);
-    return { workspace: realpathSync(abs), history };
+        throw new Error(`--root is not a directory: ${root}`);
+    return { root: realpathSync(abs), history };
 }
 // Auto-run only as a MAIN module: the CLI dispatcher spawns this file as a
 // child's entry script, while an in-process `import` (the test suite) stays inert.

package/dist/render-html.js

@@ -36,43 +36,43 @@ function page(title, body, ctx, source) {
         ? `<script type="importmap">{"imports":{"node:fs":"${lg}_node-stub.js","node:path":"${lg}_node-stub.js","node:crypto":"${lg}_node-stub.js","node:url":"${lg}_node-stub.js","node:child_process":"${lg}_node-stub.js"}}</script>\n`
         : "";
     const liveJs = wantLive
-        ? `<script type="module">
-globalThis.process ??= { argv: [], env: {} };
-const { parse } = await import("${lg}geml.js");
-const { codeGraphWaves } = await import("${lg}render.js");
-const w = codeGraphWaves(async (rel) => {
-  try { const r = await fetch(rel, { cache: "no-cache" }); return r.ok ? await r.text() : null; } catch { return null; }
-}, parse);
-for (const m of document.querySelectorAll(".cg-mount[data-start]")) {
-  const start = m.getAttribute("data-start");
-  m._cgView = async (view) => {
-    // A directed view builds from the node's OWN document (its meta names the
-    // module and graph-depth); {doc} opens that document; else the mount's.
-    const src = view && view.doc ? view.doc
-      : view && view.node ? view.node.slice(0, view.node.lastIndexOf("#"))
-      : start;
-    const r = await w.build(src, view && view.doc ? undefined : view);
-    return r.error !== undefined ? null : r.data;
-  };
-}
+        ? `<script type="module">
+globalThis.process ??= { argv: [], env: {} };
+const { parse } = await import("${lg}geml.js");
+const { codeGraphWaves } = await import("${lg}render.js");
+const w = codeGraphWaves(async (rel) => {
+  try { const r = await fetch(rel, { cache: "no-cache" }); return r.ok ? await r.text() : null; } catch { return null; }
+}, parse);
+for (const m of document.querySelectorAll(".cg-mount[data-start]")) {
+  const start = m.getAttribute("data-start");
+  m._cgView = async (view) => {
+    // A directed view builds from the node's OWN document (its meta names the
+    // module and graph-depth); {doc} opens that document; else the mount's.
+    const src = view && view.doc ? view.doc
+      : view && view.node ? view.node.slice(0, view.node.lastIndexOf("#"))
+      : start;
+    const r = await w.build(src, view && view.doc ? undefined : view);
+    return r.error !== undefined ? null : r.data;
+  };
+}
 </script>\n`
         : "";
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(title)}</title>
-<style>${CSS}</style>
-${importMap}${mathHead}${mermaidHead}</head>
-<body>
-<main>
-${body}
-</main>
-${footer}
-<script>${JS}</script>
-${ctx.usedCodeGraph ? `<script>${CODE_GRAPH_JS}</script>\n` : ""}${liveJs}</body>
-</html>
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+${importMap}${mathHead}${mermaidHead}</head>
+<body>
+<main>
+${body}
+</main>
+${footer}
+<script>${JS}</script>
+${ctx.usedCodeGraph ? `<script>${CODE_GRAPH_JS}</script>\n` : ""}${liveJs}</body>
+</html>
 `;
 }
 export function renderHtml(doc, opts = {}) {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@geml/geml",
-  "version": "1.4.3",
+  "version": "1.4.4",
+  "mcpName": "io.github.geml-spec/geml",
   "publishConfig": {
     "access": "public"
   },