@geml/geml 1.8.1 → 1.8.3

package/dist/cli.js

@@ -125,144 +125,151 @@ function embedSrcOf(source, unit) {
     const v = parseAttrs(braces[0]).attrs["src"];
     return typeof v === "string" ? v : undefined;
 }
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
-                                             (--root widens cross-doc resolution to dir d, as on check — an
-                                              === embed whose target sits above the file's own directory
-                                              needs it, or it renders unresolved)
-                                             --to  <output>: json | html | md | geml
-                                               --to md    -> Markdown (lossy)
-                                               --to html  -> self-contained HTML
-                                               --to html --fragment -> body-only markup, no page shell
-                                                            (embed in your own layout; assets via pageAssets)
-                                               --to geml  -> canonical re-format
-                                               --to json  -> document-model JSON (default)
-                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
-                                               geml notes.md                -> GEML   (md inferred from extension)
-                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
-                                               geml - --from md             read Markdown on stdin
-  geml list   <file.geml|-> [--json]                  list every addressable block: address, kind, lines
-                                             (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 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
-                                             ids (--json = array). A selector may also be a POSITION,
-                                             'L27' or 'L27-58' — the smallest block containing those
-                                             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
-                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
-  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
-                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
-  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
-  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
-                                             (sel: 0 | -N | id-prefix | changed; default -1)
-  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
-                                             (--root widens cross-doc refs to dir d, e.g. the repo root)
-  geml history <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
-                                              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)
-                                             (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)
-  geml skill  install [--dest <dir>] [--no-global] [--no-mcp]   set up GEML for Claude Code, user-global
-                                             (authoring skill -> ~/.claude/skills/geml, CLI -> npm i -g,
-                                              MCP server registered at user scope; touches no settings.json,
-                                              installs no hooks; idempotent — re-run to update)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Mutations (set/add/delete/rename) write the whole updated document in place for a
-file, or to stdout for '-' input; -o redirects it (-o - = stdout).
-Exit codes:
-  0 ok
-  1 document/operation error
-  2 command usage error.
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
+                                             (--root widens cross-doc resolution to dir d, as on check — an
+                                              === embed whose target sits above the file's own directory
+                                              needs it, or it renders unresolved)
+                                             --to  <output>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --to html --fragment -> body-only markup, no page shell
+                                                            (embed in your own layout; assets via pageAssets)
+                                               --to geml  -> canonical re-format
+                                               --to json  -> document-model JSON (default)
+                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
+                                               geml notes.md                -> GEML   (md inferred from extension)
+                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
+                                               geml - --from md             read Markdown on stdin
+  geml list   <file.geml|-> [--json]                  list every addressable block: address, kind, lines
+                                             (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 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
+                                             ids (--json = array). A selector may also be a POSITION,
+                                             'L27' or 'L27-58' — the smallest block containing those
+                                             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
+                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
+  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
+                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
+  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
+  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
+                                             (sel: 0 | -N | id-prefix | changed; default -1)
+  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
+                                             (--root widens cross-doc refs to dir d, e.g. the repo root;
+                                              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
+                                              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)
+                                             (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)
+  geml skill  install [--dest <dir>] [--no-global] [--no-mcp]   set up GEML for Claude Code, user-global
+                                             (authoring skill -> ~/.claude/skills/geml, CLI -> npm i -g,
+                                              MCP server registered at user scope; touches no settings.json,
+                                              installs no hooks; idempotent — re-run to update)
+  geml --help | --version [--json]
+
+Use '-' as the file to read from stdin.
+Mutations (set/add/delete/rename) write the whole updated document in place for a
+file, or to stdout for '-' input; -o redirects it (-o - = stdout).
+Exit codes:
+  0 ok
+  1 document/operation error
+  2 command usage error.
 `;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
 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)",
-    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)
-       geml history verify  <file.geml>                    rebuild and re-hash every revision in the chain
-       (<rev>: 0 = the tip | -N = N revisions back | an unambiguous revision id — the strings 'get' prints.
+    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)
+       geml history verify  <file.geml>                    rebuild and re-hash every revision in the chain
+       (<rev>: 0 = the tip | -N = N revisions back | an unambiguous revision id — the strings 'get' prints.
         All four take --history <path> to point at a sidecar other than <file>.gemlhistory.)`,
-    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
-       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
-       geml codemap verify [dir]                 geml check + profile reference checks
-       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
-       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
-       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
-       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
+    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
+       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
+       geml codemap verify [dir]                 geml check + profile reference checks
+       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
+       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
+       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
+       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
-    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
-
-  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
-  Every tool is geml_ + its CLI COMMAND PATH, so the terminal and the assistant
-  share one vocabulary — geml_history mirrors the "geml history" command group,
-  whose read verb (get) is the only one of the four served here.
-  Eleven tools: geml_list · geml_find · geml_get · geml_check · geml_history
-                geml_to · geml_set · geml_add · geml_delete · geml_rename
-                geml_revert
-  With a code graph under --root, four more (read-only), so one client entry
-  covers both: geml_codemap_search · geml_codemap_callchain
-               geml_codemap_list · geml_codemap_node
-
-  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
-                      client names is confined here; a client cannot widen it.
-  --graph <dir>       Code-graph directory, inside --root. Defaults to
-                      <root>/.geml-code-graph when it holds an index.geml; with
-                      no graph the four graph tools are not served at all.
-  --no-history        Skip the .gemlhistory revision saved before each write
-                      (default: save one, so geml_revert always has a revision
-                      to undo to).
-
-  Register with a client:
+    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Every tool is geml_ + its CLI COMMAND PATH, so the terminal and the assistant
+  share one vocabulary — geml_history mirrors the "geml history" command group,
+  whose read verb (get) is the only one of the four served here.
+  Eleven tools: geml_list · geml_find · geml_get · geml_check · geml_history
+                geml_to · geml_set · geml_add · geml_delete · geml_rename
+                geml_revert
+  With a code graph under --root, four more (read-only), so one client entry
+  covers both: geml_codemap_search · geml_codemap_callchain
+               geml_codemap_list · geml_codemap_node
+
+  --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
+                      client names is confined here; a client cannot widen it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when it holds an index.geml; with
+                      no graph the four graph tools are not served at all.
+  --no-history        Skip the .gemlhistory revision saved before each write
+                      (default: save one, so geml_revert always has a revision
+                      to undo to).
+
+  Register with a client:
     claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
-    skill: `usage: geml skill install [--dest <skillsDir>] [--no-global] [--no-mcp] [--dry-run]
-
-  One command, three things, all user-global — so any Claude Code session can
-  author, validate, and blockwise-edit GEML:
-    1. the authoring skill -> <skillsDir>/geml   (default ~/.claude/skills/geml)
-    2. the geml CLI        -> npm i -g @geml/geml   (skipped when already on PATH)
-    3. the MCP server      -> claude mcp add --scope user geml -- npx -y @geml/geml mcp --root .
-  Touches no settings.json and installs no hooks. Idempotent — re-run after an
-  upgrade to refresh the skill text alongside the CLI it teaches.
-
-  --dest <dir>   install the skill under <dir> instead of ~/.claude/skills
-  --no-global    skip the global npm install
-  --no-mcp       skip the MCP server registration
-  --dry-run      report what would be written, change nothing
-
-  Other agent tools are installed by DETECTION: a tool's own context file gets
-  the skill text inside a marker pair (refreshed on a re-run, nothing else in
-  the file touched) when its directory is already there — ~/.gemini, ~/.qwen,
-  and an AGENTS.md in the current project. A tool that is not installed is
+    skill: `usage: geml skill install [--dest <skillsDir>] [--no-global] [--no-mcp] [--dry-run]
+
+  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@<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 — 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    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
+
+  Other agent tools are installed by DETECTION: a tool's own context file gets
+  the skill text inside a marker pair (refreshed on a re-run, nothing else in
+  the file touched) when its directory is already there — ~/.gemini, ~/.qwen,
+  and an AGENTS.md in the current project. A tool that is not installed is
   skipped and named; no tool directory is ever created for you.`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
@@ -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 === "-")
@@ -2254,7 +2292,7 @@ function runCodemap(args) {
     // `unknown codemap subcommand`: this string is what an operator sees in a
     // client's server log when the entry they registered stops starting.
     if (sub === "mcp") {
-        fail("geml codemap mcp was removed: use `geml mcp --root <dir>`, which serves the three code-graph tools alongside the document tools (graph: <root>/.geml-code-graph, or --graph <dir>).");
+        fail("geml codemap mcp was removed: use `geml mcp --root <dir>`, which serves the four code-graph tools alongside the document tools (graph: <root>/.geml-code-graph, or --graph <dir>).");
     }
     const script = scripts[sub];
     if (!script)
@@ -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);
@@ -1118,33 +1135,49 @@ function gatherIds(source) {
     scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
     return new Set(ctx.ids.keys());
 }
-// Pre-scan for `=== meta` blocks (at any fence depth) and merge their
-// `key=val` lines, so `{{key}}` interpolation can resolve forward references.
+// Pre-scan for `=== meta` blocks and merge their `key=val` lines, so `{{key}}`
+// interpolation can resolve forward references.
+//
+// The walk descends exactly as scanBlocks/collectSpans do — into FLOW bodies
+// only, because a raw or data body is opaque (§3). This used to be a flat regex
+// sweep over every line, which read a `=== meta` shown as an EXAMPLE inside a
+// longer-fenced `==== code` as a real definition: its keys supplied live
+// `{{key}}` values (`geml check` clean, so nothing said so), and a key the
+// document also defined at top level warned `duplicate-meta-key` against a
+// definition that does not exist. Closing is fenceClose's job too now, so a
+// `=== meta {#m}` may close on its labeled fence `=== #m` like any other block.
 function collectMeta(lines, diags) {
     const meta = new Map();
     const firstLine = new Map(); // key → 1-based line of the defining fence
-    for (let i = 0; i < lines.length; i++) {
-        const open = FENCE_OPEN.exec(lines[i]);
-        if (!open || open[2] !== "meta")
-            continue;
-        const len = open[1].length;
-        const body = [];
-        let j = i + 1;
-        for (; j < lines.length && !isCloseFence(lines[j], len); j++)
-            body.push(lines[j]);
-        for (const [k, v] of Object.entries(parseData(body))) {
-            if (meta.has(k)) {
-                diags?.push({ severity: "warning", code: "duplicate-meta-key",
-                    message: `meta key \`${k}\` already defined at line ${firstLine.get(k)}; later definition at line ${i + 1} is ignored`,
-                    line: i + 1 });
+    const walk = (ls, base, depth) => {
+        for (let i = 0; i < ls.length; i++) {
+            const open = FENCE_OPEN.exec(ls[i]);
+            if (!open)
+                continue;
+            const type = open[2];
+            const { end, closed } = fenceClose(ls, i, open);
+            const body = ls.slice(i + 1, closed ? end - 1 : end);
+            if (type === "meta") {
+                const line = base + i + 1; // 1-based, in the original stream
+                for (const [k, v] of Object.entries(parseData(body))) {
+                    if (meta.has(k)) {
+                        diags?.push({ severity: "warning", code: "duplicate-meta-key",
+                            message: `meta key \`${k}\` already defined at line ${firstLine.get(k)}; later definition at line ${line} is ignored`,
+                            line });
+                    }
+                    else {
+                        meta.set(k, String(v));
+                        firstLine.set(k, line);
+                    }
+                }
             }
-            else {
-                meta.set(k, String(v));
-                firstLine.set(k, i + 1);
+            else if ((REGISTRY.get(type) ?? "raw") === "flow" && depth < MAX_NESTING) {
+                walk(body, base + i + 1, depth + 1);
             }
+            i = end - 1; // the loop's ++ lands on `end`
         }
-        i = j;
-    }
+    };
+    walk(lines, 0, 0);
     return meta;
 }
 // §8: resolve every discovered reference. Internal/autoref/footnote anchors