@geml/geml 1.8.1 → 1.8.2

package/README.md

@@ -108,6 +108,9 @@ 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)
+# --root works on every verb above, not just check. A write is refused when the result
+# would not parse, so a document whose ../sibling.md links resolve only from the repo
+# root needs --root to be editable at all. The MCP server passes its own root for you.
 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>   # your codebase's call graph as GEML docs
 geml mcp    --root <dir> [--graph <dir>]  # serve documents (+ the code graph) over MCP

package/dist/attrs.d.ts

@@ -3,7 +3,15 @@ export interface Attrs {
     id?: string;
     classes: string[];
     attrs: Record<string, Value>;
+    odd?: {
+        kind: "id" | "class" | "flag" | "key";
+        name: string;
+    }[];
 }
+export declare function oddNames(a: Attrs): {
+    kind: "id" | "class" | "flag" | "key";
+    name: string;
+}[];
 export declare function coerce(raw: string): Value;
 export declare function tokenize(s: string): string[];
 export declare function parseAttrs(src: string): Attrs;

package/dist/attrs.js

@@ -1,5 +1,29 @@
 // Shared attribute-object and value typing (§4), used by the block scanner
 // and the inline parser.
+// §4: NAME = NAME-CHAR+, NAME-CHAR = LETTER | DIGIT | "-" | "_", LETTER being
+// any Unicode letter. Ids, classes and attribute keys are all NAMEs; only
+// VALUES may hold anything else.
+const NAME = /^[\p{L}\p{N}_-]+$/u;
+// Why this is worth a diagnostic: the attribute object is whitespace-separated,
+// so `{#Trade-offs & Laws}` parses as the id `Trade-offs` plus two boolean flags
+// named `&` and `Laws` — a legal parse of a document nobody meant to write, and
+// silent, because a bare word IS how a flag is spelled. The id you addressed is
+// then not the id you have. Naming what cannot be a NAME turns that into a
+// question the author can answer.
+export function oddNames(a) {
+    const odd = [];
+    if (a.id !== undefined && !NAME.test(a.id))
+        odd.push({ kind: "id", name: a.id });
+    for (const c of a.classes)
+        if (!NAME.test(c))
+            odd.push({ kind: "class", name: c });
+    for (const [k, v] of Object.entries(a.attrs)) {
+        if (NAME.test(k))
+            continue;
+        odd.push({ kind: v === true ? "flag" : "key", name: k });
+    }
+    return odd;
+}
 // §4 value typing: quoted -> string, true/false -> boolean, integer/float
 // syntax -> number, any other bare word -> string. No arrays/dates/tables.
 export function coerce(raw) {

package/dist/cli.js

@@ -168,7 +168,12 @@ Usage:
   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)
+                                             (--root widens cross-doc refs to dir d, e.g. the repo root;
+                                              every read and write verb takes it. A write is REFUSED when
+                                              the result would not parse, so a document whose ../x.md
+                                              links only resolve from the repo root needs --root to be
+                                              editable at all — otherwise the guard reads its own blind
+                                              spot as breakage)
   geml history <save|get|restore|verify> <file.geml> [...]   .gemlhistory version sidecar
                                              (save = append the file as a revision · get = list revisions, or
                                               print one · restore = overwrite the file with one · verify = rebuild
@@ -197,15 +202,15 @@ Exit codes:
 // shown on misuse and the `<cmd> --help` text.
 const SUBHELP = {
     get: "usage: geml get <file.geml|-> [<selector>] [--head|--intro|--body] [--view [--root <dir>]] [--json]  (selector = a filter over blocks: #id | '## Heading' (its whole section) | '=== type' (every block of that type — N matches print N contents, count on stderr) | '=== type@<hex>[~n]' or '@<hex>[~n]' (content address, for blocks with no #id) | L<n> or L<n>-<m> (position — the smallest block that fully contains those lines, so the `L27-58` the listing prints pastes straight back, and a line number from an editor, a linter or a diff hunk becomes a block); a section cuts three ways — --head = the heading line, --intro = its opening region: everything under it up to its FIRST SUBHEADING (empty when one follows immediately, the whole body when none does; a block has no intro and is refused), --body = everything under it; --view = read THROUGH an `embed` to the entity block it stands for, following a chain to its end (the identity on any other block, and on a section selector — it never splices two documents' bytes together); provenance goes to stderr as `view: <sel> -> <doc>[#<id>]`; read-only, `set` refuses it; chain reads are confined to --root (default: the document's own directory) and never fetched over the network; without a selector: list every addressable block with its shortest unique address, --json = array)",
-    set: "usage: geml set <file.geml|-> <selector> [--head|--intro|--body] [--in F | --in F#src | --in -] [-o out.geml]  (selector as in `get`, but it must match exactly ONE block — '=== type' matching several is refused; content: --in F takes F's block #id, --in F#src takes #src, else stdin raw; default = whole block, --head = head line — both normalize the id when the target has one — --body = body, --intro = a heading's opening region up to its first subheading (an empty region INSERTS there); guarded splice, refused if it breaks the doc — but a replacement that REMOVES blocks is carried out and reported on stderr, named ones and unnamed alike, with `geml revert` as the way back (the same stance `delete` takes; the ordinary read-edit-write cycle removes nothing, since `get` handed those blocks over); writing through an @<hex> address prints the new address on stderr)",
-    add: "usage: geml add <file.geml|-> (--append | --before #id | --after #id) [--in F | --in F#src | --in -] [-o out.geml]  (insert a GEML fragment — 1+ blocks and/or prose — at a position; --in F takes all of F, --in F#src takes #src, else stdin raw; content keeps its own ids, a collision is refused)",
-    delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml]  (remove one or more blocks; a missing id is skipped with a note, not an error; a reference left dangling is a warning, not a refusal — delete never fails on a live reference)",
-    rename: "usage: geml rename <file.geml|-> #old #new [-o out.geml]  (rewrite an id's declaration AND every reference — [[#id]], [text](#id), chart data=#id, footnote [^id] — id-boundary safe, skipping raw block bodies; #new must be free; refused if it breaks the doc)",
+    set: "usage: geml set <file.geml|-> <selector> [--head|--intro|--body] [--in F | --in F#src | --in -] [-o out.geml] [--root d]  (selector as in `get`, but it must match exactly ONE block — '=== type' matching several is refused; content: --in F takes F's block #id, --in F#src takes #src, else stdin raw; default = whole block, --head = head line — both normalize the id when the target has one — --body = body, --intro = a heading's opening region up to its first subheading (an empty region INSERTS there); guarded splice, refused if it breaks the doc — but a replacement that REMOVES blocks is carried out and reported on stderr, named ones and unnamed alike, with `geml revert` as the way back (the same stance `delete` takes; the ordinary read-edit-write cycle removes nothing, since `get` handed those blocks over); writing through an @<hex> address prints the new address on stderr)",
+    add: "usage: geml add <file.geml|-> (--append | --before #id | --after #id) [--in F | --in F#src | --in -] [-o out.geml] [--root d]  (insert a GEML fragment — 1+ blocks and/or prose — at a position; --in F takes all of F, --in F#src takes #src, else stdin raw; content keeps its own ids, a collision is refused)",
+    delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml] [--root d]  (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] [--root d]  (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|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)",
+    replace: "usage: geml replace <file.geml|-> <old> <new> [--within <selector>] [-o out.geml] [--root d]  (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)",
+    revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out] [--root d]  (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)
        geml history get     <file.geml> [<rev>] [--json]   NO <rev>: every revision, newest first, first column = the selector; WITH <rev>: that revision's full text
        geml history restore <file.geml> <rev> [--force]    overwrite the working file with a revision (--force discards unsaved changes)
@@ -249,13 +254,15 @@ const SUBHELP = {
   One command, three things, all user-global — so any Claude Code session can
   author, validate, and blockwise-edit GEML:
     1. the authoring skill -> <skillsDir>/geml   (default ~/.claude/skills/geml)
-    2. the geml CLI        -> npm i -g @geml/geml   (skipped when already on PATH)
+    2. the geml CLI        -> npm i -g @geml/geml@<this version>   (skipped when PATH already has it)
     3. the MCP server      -> claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .
-  Touches no settings.json and installs no hooks. Idempotent — re-run after an
-  upgrade to refresh the skill text alongside the CLI it teaches.
+  Touches no settings.json and installs no hooks. Idempotent — and it is the
+  whole upgrade: a re-run refreshes the skill text AND brings the global CLI to
+  the version that text documents, so "npx -y @geml/geml skill install" is one
+  step, not two.
 
   --dest <dir>   install the skill under <dir> instead of ~/.claude/skills
-  --no-global    skip the global npm install
+  --no-global    leave the global CLI alone — no install, no version change
   --no-mcp       skip the MCP server registration
   --dry-run      report what would be written, change nothing
 
@@ -426,7 +433,27 @@ function existsFor(file, root) {
 }
 // Both halves for a parse: every call site wants them together, and pairing
 // them here keeps a resolver from being wired up without its existence probe.
-function docOpts(file, root) {
+// The root that cross-document references resolve against for the rest of this
+// process, taken from `--root` by whichever verb is running.
+//
+// Why a module-level value rather than a parameter: the write verbs re-parse
+// through `resolveSelector`, `spliceSpan`, `insertFragment`, `rewriteId` and
+// `unitNode`, and threading a root through those signatures and their dozen call
+// sites would deliver the same value to the same place by a longer route. It is
+// safe to hold here because a verb is one process: `geml mcp` spawns the CLI per
+// tool call rather than calling these functions in-process.
+let CLI_ROOT;
+// Read `--root` and make it this process's root. Verbs call this before they
+// parse anything; `--root` present with no directory is a usage error, the same
+// as it is on `check`.
+function useRoot(args) {
+    const r = flag(args, "--root");
+    if (args.includes("--root") && r === undefined)
+        fail("--root needs a directory", 2);
+    CLI_ROOT = r;
+    return r;
+}
+function docOpts(file, root = CLI_ROOT) {
     return { resolveDoc: resolverFor(file, root), docExists: existsFor(file, root) };
 }
 // `geml check <file>` — validate only: diagnostics + exit code, no document
@@ -1088,6 +1115,7 @@ function reportMatches(type, units) {
 // descriptions agents are already reading. `get <file>` keeps working.
 function runList(args) {
     const [file, extra] = positionals(args, ["--root"]);
+    useRoot(args);
     if (!file)
         fail(SUBHELP.list);
     // `list` IS the empty filter, so a selector here means the caller wanted
@@ -1135,7 +1163,10 @@ function gemlFilesUnder(path, out, explicit = false) {
 // being true the moment anything above it changes. `codemap find` already
 // resolves a substring to `doc#id` for symbols; this is the same move for prose.
 function runFind(args) {
-    const pos = positionals(args, []);
+    // `--root` is declared here, and ignored, so that it cannot be mistaken for
+    // one more path to search: `find` resolves no cross-document references, and
+    // swallowing the directory as a search path widens what a caller narrowed.
+    const pos = positionals(args, ["--root"]);
     const pattern = pos[0];
     if (pattern === undefined)
         fail(SUBHELP.find);
@@ -1220,6 +1251,7 @@ function runGet(args) {
     const introOnly = args.includes("--intro");
     const view = args.includes("--view");
     const [file, rawSel] = positionals(args, ["--root"]);
+    useRoot(args);
     if (!file)
         fail(SUBHELP.get);
     const parts = [headOnly && "--head", introOnly && "--intro", bodyOnly && "--body"].filter(Boolean);
@@ -1339,7 +1371,8 @@ function runGet(args) {
 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"]);
+    const [file, oldText, newText] = positionals(args, ["-o", "--out", "--within", "--root"]);
+    useRoot(args);
     if (!file || oldText === undefined || newText === undefined)
         fail(SUBHELP.replace);
     if (oldText === "")
@@ -1474,7 +1507,8 @@ function runSet(args) {
     if (args.includes("--view")) {
         fail("--view is read-only. To edit the target, read the frame's `src` and edit that document.", 2);
     }
-    const [file, rawSel] = positionals(args, ["-o", "--out", "--in"]);
+    const [file, rawSel] = positionals(args, ["-o", "--out", "--in", "--root"]);
+    useRoot(args);
     if (!file)
         fail(SUBHELP.set);
     // No selector: there is no block to replace. Point the way to discovery, not a
@@ -1649,7 +1683,8 @@ function runAdd(args) {
     const posCount = (append ? 1 : 0) + (before !== undefined ? 1 : 0) + (after !== undefined ? 1 : 0);
     if (posCount !== 1)
         fail("add needs exactly one position: --append | --before #id | --after #id", 2);
-    const [file] = positionals(args, ["-o", "--out", "--in", "--before", "--after"]);
+    const [file] = positionals(args, ["-o", "--out", "--in", "--before", "--after", "--root"]);
+    useRoot(args);
     if (!file)
         fail(SUBHELP.add);
     const rawChannel = from === undefined || from === "-";
@@ -1728,7 +1763,8 @@ function insertFragment(source, lines, at, fragment, file) {
 // the UNION of target lines, so a line is never spliced twice.
 function runDelete(args) {
     const out = flag(args, "-o") ?? flag(args, "--out");
-    const pos = positionals(args, ["-o", "--out"]);
+    const pos = positionals(args, ["-o", "--out", "--root"]);
+    useRoot(args);
     const file = pos[0];
     if (!file)
         fail(SUBHELP.delete);
@@ -1767,7 +1803,8 @@ function runDelete(args) {
 // free; the guarded re-parse refuses anything that would break the doc.
 function runRename(args) {
     const out = flag(args, "-o") ?? flag(args, "--out");
-    const [file, rawOld, rawNew] = positionals(args, ["-o", "--out"]);
+    const [file, rawOld, rawNew] = positionals(args, ["-o", "--out", "--root"]);
+    useRoot(args);
     if (!file || !rawOld || !rawNew)
         fail(SUBHELP.rename);
     const oldId = rawOld.replace(/^#/, "");
@@ -2051,7 +2088,8 @@ function runRevert(args) {
     if ((append ? 1 : 0) + (before !== undefined ? 1 : 0) + (after !== undefined ? 1 : 0) > 1) {
         fail("revert takes at most one position: --append | --before #id | --after #id", 2);
     }
-    const [file, rawId] = positionals(args, ["--rev", "--history", "-o", "--out", "--before", "--after"]);
+    const [file, rawId] = positionals(args, ["--rev", "--history", "-o", "--out", "--before", "--after", "--root"]);
+    useRoot(args);
     if (!file || !rawId)
         fail(SUBHELP.revert);
     if (file === "-")
@@ -2428,13 +2466,26 @@ function runSkill(args) {
     const sh = process.platform === "win32";
     const run = (cmd, a, inherit = false) => spawnSync(cmd, a, { shell: sh, encoding: "utf8", ...(inherit ? { stdio: "inherit" } : {}) });
     if (!noGlobal) {
+        // The skill text just written came out of THIS package (`skill/` next to
+        // dist/), so the CLI it teaches is this package's version. Anything else on
+        // PATH is a mismatch — which is why the test is an equality and not an
+        // ordering: "different version" and "not installed" both mean "put the
+        // version the skill documents there", and pinning the spec is what makes
+        // one `npx -y @geml/geml skill install` a complete upgrade.
+        //
+        // The version is read back out of `geml --version` ("geml 1.2.3 (GEML spec
+        // …)") rather than trusted as a whole string: an unreadable or unexpected
+        // line is simply not a match, and lands in the install branch.
         const have = run("geml", ["--version"]);
-        if (have.status === 0) {
-            console.log(`cli    ${String(have.stdout ?? "").trim()} already on PATH`);
+        const onPath = have.status === 0
+            ? /\b\d+\.\d+\.\d+[^\s)]*/.exec(String(have.stdout ?? ""))?.[0]
+            : undefined;
+        if (onPath === PARSER_VERSION) {
+            console.log(`cli    ${PARSER_VERSION} already on PATH`);
         }
         else {
-            console.log("cli    installing @geml/geml globally (npm i -g)...");
-            const r = run("npm", ["install", "-g", "@geml/geml", "--no-audit", "--no-fund", "--loglevel=error"], true);
+            console.log(`cli    installing @geml/geml globally (npm i -g)${onPath ? `, ${onPath} -> ${PARSER_VERSION}` : ""}...`);
+            const r = run("npm", ["install", "-g", `@geml/geml@${PARSER_VERSION}`, "--no-audit", "--no-fund", "--loglevel=error"], true);
             if (r.status !== 0)
                 console.error("cli    global install failed — install later with: npm i -g @geml/geml");
         }

package/dist/diagnostics.d.ts

@@ -1,4 +1,4 @@
-export type DiagnosticCode = "unterminated-block" | "unknown-block-type" | "unknown-attribute" | "block-nesting-too-deep" | "list-nesting-too-deep" | "inline-nesting-too-deep" | "stray-labeled-fence" | "fence-like-line" | "unresolvable-code-source" | "bad-code-source" | "bad-source-range" | "code-src-and-body" | "duplicate-id" | "unresolved-reference" | "unresolved-footnote" | "unresolved-cross-document-reference" | "unresolvable-document" | "unchecked-cross-document-reference" | "embed-missing-src" | "ignored-embed-body" | "transclusion-cycle" | "embed-target-not-geml" | "media-target-is-document" | "inline-transclusion-not-inline" | "unsafe-embed-scheme" | "unresolvable-table-source" | "table-source-not-a-table" | "unknown-metadata-reference" | "duplicate-meta-key" | "table-src-and-body" | "unknown-table-format" | "bad-table-delimiter" | "ignored-table-delimiter" | "bad-compute-formula" | "unlexable-compute-formula" | "compute-error" | "compute-non-numeric-cell" | "compute-not-a-number" | "bad-summary-entry" | "summary-unknown-column" | "unlexable-summary-expression" | "summary-error" | "unknown-diagram-format" | "ignored-diagram-body" | "code-graph-missing-src" | "code-graph-unresolvable-document" | "chart-missing-data" | "chart-data-not-a-table" | "chart-missing-type" | "chart-unknown-type" | "chart-unknown-rows-scope" | "chart-missing-channel" | "chart-empty-channel" | "chart-unknown-column" | "chart-unused-channel" | "chart-missing-summary-row" | "chart-summary-row-unavailable" | "chart-non-numeric-value" | "chart-data-not-records" | "data-parse" | "unknown-data-format" | "data-format-no-engine" | "bad-data-schema" | "data-src-and-body" | "bad-data-source" | "unresolvable-data-source";
+export type DiagnosticCode = "unterminated-block" | "unknown-block-type" | "unknown-attribute" | "block-nesting-too-deep" | "list-nesting-too-deep" | "inline-nesting-too-deep" | "stray-labeled-fence" | "fence-like-line" | "unresolvable-code-source" | "bad-code-source" | "bad-source-range" | "code-src-and-body" | "name-not-a-name" | "duplicate-id" | "unresolved-reference" | "unresolved-footnote" | "unresolved-cross-document-reference" | "unresolvable-document" | "unchecked-cross-document-reference" | "embed-missing-src" | "ignored-embed-body" | "transclusion-cycle" | "embed-target-not-geml" | "media-target-is-document" | "inline-transclusion-not-inline" | "unsafe-embed-scheme" | "unresolvable-table-source" | "table-source-not-a-table" | "unknown-metadata-reference" | "duplicate-meta-key" | "table-src-and-body" | "unknown-table-format" | "bad-table-delimiter" | "ignored-table-delimiter" | "bad-compute-formula" | "unlexable-compute-formula" | "compute-error" | "compute-non-numeric-cell" | "compute-not-a-number" | "bad-summary-entry" | "summary-unknown-column" | "unlexable-summary-expression" | "summary-error" | "unknown-diagram-format" | "ignored-diagram-body" | "code-graph-missing-src" | "code-graph-unresolvable-document" | "chart-missing-data" | "chart-data-not-a-table" | "chart-missing-type" | "chart-unknown-type" | "chart-unknown-rows-scope" | "chart-missing-channel" | "chart-empty-channel" | "chart-unknown-column" | "chart-unused-channel" | "chart-missing-summary-row" | "chart-summary-row-unavailable" | "chart-non-numeric-value" | "chart-data-not-records" | "data-parse" | "unknown-data-format" | "data-format-no-engine" | "bad-data-schema" | "data-src-and-body" | "bad-data-source" | "unresolvable-data-source";
 export interface Diagnostic {
     severity: "error" | "warning";
     code: DiagnosticCode;

package/dist/diagnostics.js

@@ -25,6 +25,9 @@ export const SEVERITY = {
     "bad-code-source": "error",
     "bad-source-range": "error",
     "code-src-and-body": "error",
+    // A warning, not an error: this has always parsed, and documents rely on the
+    // leniency. What the author is missing is that it parsed as something else.
+    "name-not-a-name": "warning",
     "duplicate-id": "error",
     "unresolved-reference": "error",
     "unresolved-footnote": "error",

package/dist/geml.js

@@ -18,7 +18,7 @@ import { readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { normalizeSource } from "./diagnostics.js";
-import { coerce, parseAttrs } from "./attrs.js";
+import { coerce, oddNames, parseAttrs } from "./attrs.js";
 import { META_REF_SRC, parseInline, isSafeUrl, schemeOf } from "./inline.js";
 import { parseTable } from "./table.js";
 import { USES, buildChart } from "./chart.js";
@@ -142,6 +142,21 @@ export const FENCE_OPEN = /^(={3,})[ \t]+([A-Za-z][A-Za-z0-9_-]*)[ \t]*(?:(\{.*\
 // Together: the group runs to the end of the line and starts at the first `{`
 // after the last OTHER `}`. Returns the RegExpExecArray shape the call sites
 // already destructure.
+// A name in the attribute object that is not a NAME (§4). A WARNING, not an
+// error: it has always parsed, documents in the wild rely on the leniency, and
+// what the author needs is to be told — `{#a & b}` gives the id `a` and two
+// flags called `&` and `b`, which is a legal parse of something nobody wrote.
+function reportOddNames(a, line, diags) {
+    for (const { kind, name } of oddNames(a)) {
+        diags.push({
+            severity: "warning",
+            code: "name-not-a-name",
+            message: `${kind} \`${name}\` is not a NAME (§4: letters, digits, \`-\`, \`_\`)`
+                + (kind === "flag" ? " — an attribute object is whitespace-separated, so a space in an id or class splits it into flags like this one" : ""),
+            line,
+        });
+    }
+}
 const HEADING_HEAD = /^(#{1,6})[ \t]+/;
 function matchHeading(line) {
     const m = HEADING_HEAD.exec(line);
@@ -414,6 +429,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             const type = open[2];
             const attrs = open[3] ? parseAttrs(open[3]) : { classes: [], attrs: {} };
             const openLineNo = base + i + 1;
+            reportOddNames(attrs, openLineNo, diags);
             // Collect the body. A block closes on the FIRST line that is a bare fence
             // of exactly the opening length, OR — when it has an id — a labeled fence
             // `=== #id` (a `=` run of any length ≥ 3 followed by the block's id). The
@@ -672,6 +688,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             const level = h[1].length;
             const rawText = h[2];
             const a = parseAttrs(h[3] ?? "");
+            reportOddNames(a, lineNo, diags);
             const text = interpolate(rawText, lineNo, ctx);
             const id = a.id ?? slug(rawText);
             registerId(ctx, id, lineNo);

package/dist/mcp.js

@@ -121,7 +121,43 @@ function resolveGraphDir(graphDir) {
 // Driving the CLI
 // ---------------------------------------------------------------------------
 const CLI = resolve(dirname(fileURLToPath(import.meta.url)), "geml.js");
+// Verbs whose cross-document reference resolution takes a root. The write ones
+// matter most: a write is refused when the result would not parse, so without a
+// root the guard reads its own blind spot as breakage and a document whose
+// `../sibling.md` links only resolve from the server root cannot be edited at
+// all. The server has always known that root and simply never handed it over.
+// NOT `find`: it searches block CONTENT and resolves no references, while its
+// positionals are the places to look — a stray `--root` reads as one more of
+// them, widening the very search the caller narrowed. A test caught exactly
+// that when this list was written without the exception.
+const ROOT_VERBS = new Set([
+    "get", "list", "check", "set", "replace", "add", "delete", "rename", "revert",
+]);
+// The server root as the filesystem really spells it. Falls back to the stored
+// value when it cannot be canonicalized: an unusable root is the caller's
+// problem to hear about from the verb, not something to throw from here.
+function rootReal() {
+    try {
+        return realpathSync(OPTS.root);
+    }
+    catch {
+        return OPTS.root;
+    }
+}
 function runCli(args, input) {
+    // The server root IS the resolution root: every `file` already lives under it,
+    // so a reference reaching a sibling directory is in scope by definition.
+    if (ROOT_VERBS.has(args[0] ?? "") && !args.includes("--root")) {
+        // CANONICALIZED, because `resolveInRoot` already canonicalizes every `file`
+        // it hands over. Passing the root raw mixes the two: the CLI's cheap lexical
+        // gate compares the reference's absolute path against the root with
+        // `relative()`, and a root reached through a symlink is lexically outside a
+        // canonical target, so every cross-document reference in the workspace
+        // resolves to nothing. On macOS that is the default state of affairs —
+        // `os.tmpdir()` is `/var/folders/…`, a symlink to `/private/var/folders/…`
+        // — which is why this passed on Windows and failed in CI.
+        args = [...args, "--root", rootReal()];
+    }
     const r = spawnSync(process.execPath, [CLI, ...args], {
         input: input ?? "",
         encoding: "utf8",

package/package.json

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

package/skill/references/authoring.geml

@@ -208,6 +208,10 @@ signal, and prints only diagnostics (cheap on context):
 geml check file.geml          # diagnostics + exit code only
 geml check --json file.geml   # machine-readable diagnostics array
 geml check --root . file.geml # widen cross-doc reference resolution to a dir
+                              # EVERY read and write verb takes --root. A write is
+                              # refused when the result would not parse, so a doc whose
+                              # ../sibling.md links resolve only from the repo root needs
+                              # it to be editable at all. `geml mcp` passes its own root.
 ===
 
 All commands accept `-` to read from stdin.