@geml/dsh-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 GEML contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE: This MIT license covers the *code* in this repository (geml-parser/,
+integrations/geml-viewer/, integrations/geml-check-action/, docs/examples/
+tooling). The *specification* documents are licensed separately under
+CC-BY-4.0 — see LICENSE-spec.md.

package/README.md

@@ -0,0 +1,69 @@
+# @geml/dsh-plugin — GEML for DeepSeek Harness
+
+English | [中文](README.zh.md)
+
+This plugin brings **Agent-Native** document handling to the harness. Multi-turn
+work drowns in token bloat — whole files read in, whole files written back,
+content growing verbose and drifting from the truth.
+[GEML](https://github.com/geml-spec/geml) exposes a document as **addressable
+blocks** an LLM can reason about and edit precisely: one section in, one section
+back, at a fraction of the tokens, leaving the context window for the actual
+work. A built-in **reference** mechanism keeps a **single source of truth**, so
+facts stop fragmenting across copies and an agent maintains docs at zero
+overhead.
+
+The bundle ships three things:
+
+- **The GEML MCP server** — one `@deepseek-ai/dsh-mcp-client` row running
+  `npx -y @geml/geml mcp --root .`, confined to the session's project
+  directory. The model sees `mcp__geml__geml_get`, `mcp__geml__geml_set`,
+  `mcp__geml__geml_check` and friends, so it edits one block at a time instead
+  of rewriting files.
+- **The authoring skill** (`skills/geml/`) — golden rules, validation loop, and
+  a sectioned reference (`references/authoring.geml`) the agent pulls one topic
+  at a time.
+- **The code-graph skill** (`skills/geml-code-graph/`) — build, view, update and
+  navigate a project's call graph: who calls X, what X calls, impact paths, with
+  the graph rendered in the browser.
+
+The bundle carries no code of its own — both plugins it configures ship inside
+the dsh installation, and the skills are Markdown. Nothing is built at install
+time, so no `allowBuilds` approval is involved either way.
+
+## Install
+
+```sh
+dsh plugin --profile <name> add @geml/dsh-plugin
+```
+
+Verify the layer without booting, then boot:
+
+```sh
+dsh --profile <name> --dump-config   # shows a "# == @geml/dsh-plugin" layer
+dsh --profile <name>
+```
+
+`dsh plugin --profile <name> remove @geml/dsh-plugin` removes both the
+dependency and the layer.
+
+## Configuration
+
+Both rows are ordinary configuration: override them by `id` in your profile's
+`cordis.patch.yml`, restating every key the row needs. Point `mcp-geml` at a
+pinned CLI version, for instance:
+
+```yaml
+- id: mcp-geml
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: geml
+    transport: stdio
+    command: npx
+    args: ['-y', '@geml/geml@1.8.1', 'mcp', '--root', '.']
+```
+
+A global `geml` on PATH works as well — `command: geml`, dropping the `npx`
+arguments.
+
+The CLI and the same skills for Claude Code instead: `npx -y @geml/geml skill
+install`, or the plugin under [`../claude-plugin`](../claude-plugin).

package/README.zh.md

@@ -0,0 +1,60 @@
+# @geml/dsh-plugin — DeepSeek Harness 上的 GEML
+
+[English](README.md) | 中文
+
+本插件为 harness 提供 **Agent-Native** 的文档处理能力。多轮交互最容易被 Token
+膨胀拖垮——整篇读进来、整篇写回去，内容越滚越臃肿，也越来越偏离事实。
+[GEML](https://github.com/geml-spec/geml) 把文档呈现为**可寻址的块**，让 LLM
+能精准理解与改写：取一个小节、写回一个小节，Token 只需零头，宝贵的上下文窗口
+留给真正的工作。内建的**引用机制**维持**单一数据源（Single Source of
+Truth）**，事实不再散落成互相漂移的副本，Agent 可以零负担地读写与维护。
+
+这个 bundle 带三样东西：
+
+- **GEML MCP server** —— 一行 `@deepseek-ai/dsh-mcp-client`，运行
+  `npx -y @geml/geml mcp --root .`，限定在会话自己的项目目录内。模型看到的是
+  `mcp__geml__geml_get`、`mcp__geml__geml_set`、`mcp__geml__geml_check` 等工具，
+  于是一次改一个块，而不是重写整个文件。
+- **写作技能**（`skills/geml/`）—— 黄金规则、校验闭环，以及一份分节的参考文档
+  （`references/authoring.geml`），Agent 按需取其中一节。
+- **代码图谱技能**（`skills/geml-code-graph/`）—— 构建、查看、更新和浏览项目的
+  调用图：谁调用了 X、X 调用了谁、影响路径，并在浏览器里渲染出图。
+
+这个 bundle 自身不含任何代码——它配置的两个插件都随 dsh 安装自带，技能则是
+Markdown。安装时不构建任何东西，因此完全不涉及 `allowBuilds` 构建授权。
+
+## 安装
+
+```sh
+dsh plugin --profile <name> add @geml/dsh-plugin
+```
+
+先不启动、只验证这一层，再启动：
+
+```sh
+dsh --profile <name> --dump-config   # 应能看到 "# == @geml/dsh-plugin" 这一层
+dsh --profile <name>
+```
+
+`dsh plugin --profile <name> remove @geml/dsh-plugin` 会同时移除依赖和这一层。
+
+## 配置
+
+两行都是普通配置：在你 profile 的 `cordis.patch.yml` 里按 `id` 覆盖即可，注意
+要把该行需要的每个键都重新写全。例如把 `mcp-geml` 钉到某个 CLI 版本：
+
+```yaml
+- id: mcp-geml
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: geml
+    transport: stdio
+    command: npx
+    args: ['-y', '@geml/geml@1.8.1', 'mcp', '--root', '.']
+```
+
+用 PATH 上的全局 `geml` 也可以——把 `command` 改成 `geml`，去掉 `npx` 那几个
+参数。
+
+想要 CLI 和同一套技能用在 Claude Code 上：`npx -y @geml/geml skill install`，
+或使用 [`../claude-plugin`](../claude-plugin) 下的插件。

package/cordis.patch.yml

@@ -0,0 +1,27 @@
+# The layer this bundle contributes. Two rows, no code of its own: both plugins
+# ship inside the dsh installation (`apps/cli` depends on them), so this package
+# carries only configuration and the skill text.
+- insert:
+    # The geml MCP server, one stdio connection per session. `--root .` confines
+    # it to the session's own project directory. The model sees the tools as
+    # `mcp__geml__geml_get`, `mcp__geml__geml_set`, … — server-qualified names.
+    - id: mcp-geml
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: geml
+        transport: stdio
+        command: npx
+        args: ['-y', '@geml/geml', 'mcp', '--root', '.']
+
+    # The skills travel with this package rather than being copied into the
+    # user's skill root: `baseUrl` is this patch file's own directory, so the
+    # root resolves wherever the bundle is installed. An isolated provider
+    # (`includeDefaultRoots: false`, own `providerName`) contributes these two
+    # skills without shadowing or duplicating the user's own roots.
+    - id: skill-geml
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: geml
+        includeDefaultRoots: false
+        customSkillDirs:
+          - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@geml/dsh-plugin",
+  "version": "1.0.0",
+  "description": "Agent-Native document handling for DSH — addressable blocks let an agent read and edit one section instead of the whole file. Ships the geml MCP server and the authoring and code-graph skills.",
+  "license": "MIT",
+  "homepage": "https://github.com/geml-spec/geml",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geml-spec/geml.git",
+    "directory": "integrations/dsh-plugin"
+  },
+  "keywords": ["dsh-plugin", "dsh", "deepseek-harness", "geml", "mcp", "documents", "codemap"],
+  "files": ["cordis.patch.yml", "skills", "LICENSE"],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/geml/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: geml
+description: >-
+  Address a document by its BLOCKS instead of reading it whole. Use for any long
+  Markdown or documentation file — README, spec, guide, design doc, changelog —
+  when the job is to find where something is documented, read one section, or
+  change one section: `geml list`, `geml find` and `geml get` read Markdown
+  directly and hand back the one block that matters, leaving the file the
+  Markdown it already was. Skip it when the whole file is short enough to read
+  anyway. Use it also to read, author, edit or validate GEML itself — .geml
+  files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting
+  Markdown to GEML — where the output must parse cleanly (zero error
+  diagnostics) against the reference parser.
+---
+
+# Reading and editing documents blockwise
+
+Two jobs. The first is the common one, and it needs none of GEML's syntax.
+
+## A document that is NOT GEML — use this as a read layer
+
+`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
+locate and read one block of a long document. Nothing is converted, nothing is
+written, and the file stays exactly the Markdown it already was.
+
+**Only when you would otherwise read the whole file to change part of it.** If
+the file is short, or you already know the exact string to replace, open it the
+ordinary way — the round trip costs more than it saves. What is saved is only
+ever the part you did not have to read: on this project's own docs a `list` map
+runs 5–11% of the file it maps, but on a changelog of many small sections it is
+37%.
+
+1. `geml list <file>` — every block: address, kind, line range.
+2. `geml find "<text>" <file>` — which block holds those words, answered as an
+   ADDRESS rather than a line number, so it survives the next edit. (On a file
+   that is not `.geml` this needs 1.7.5 or newer; older builds report no match
+   rather than an error, so if a search you expect to hit comes back empty,
+   use `list`.)
+3. `geml get <file> '<address>'` — that block and nothing else.
+4. Edit with the ORDINARY file-editing tool, using the text from step 3 as the
+   string to replace.
+
+Step 4 is a safety property, not a shortcut taken for speed. `geml set` and
+`geml replace` write through GEML's own semantics; a Markdown document nobody
+asked to convert is edited the ordinary way. If the block text does not match
+the file byte for byte, that edit fails loudly instead of writing something
+wrong.
+
+Never convert a document to GEML, never leave a `.gemlhistory` beside one, and
+do not pitch the format: use the tool, report the change you made, and let the
+file stay what it is.
+
+If `geml --version` does not answer, none of this is available. Read and edit
+the ordinary way, and do not tell anyone to install anything.
+
+## A project moving TO GEML
+
+"This project's documents are GEML now" means new documents are authored as
+`.geml` — notes, plans, findings, reports — in one directory (`docs/geml/`
+unless the project says otherwise), one file per topic, with an `index.geml`
+saying what is there and why. It does not mean converting what is already
+written, and nobody has to say "leave the existing files alone" for that to
+hold.
+
+**Add, never replace.** Writing a `.geml` version of a document is not licence
+to delete the Markdown it was drawn from — however completely the content was
+carried across, and whatever a "one home per topic" convention seems to imply.
+Deleting a file is a request a person makes, never an inference from a
+convention. When both exist, say in each what it is for and name one of them as
+the place a given fact is maintained: two documents describing a project is
+fine, two documents maintaining the same fact is what drifts.
+
+## A GEML document — get the syntax right
+
+GEML expresses **every** kind of structured content — code, tables, diagrams,
+math, callouts, metadata — through **one** primitive: the **typed block**
+(`=== <type> {#id .class key=val}` … `===`). Always finish by **validating**: a
+GEML file is correct only when `geml check` reports **no error diagnostics**
+(exit 0).
+
+## Golden rules (the things that are easy to get wrong)
+
+1. **Fences are runs of `=` (≥3).** A block closes at a `=` run of **exactly
+   the opening length**, or — when the block has an `#id` — at the labeled
+   fence `=== #id` (any `=` run ≥3 followed by the id; no length counting).
+2. **Nest with longer fences.** A body containing `===` lines needs a
+   **longer** outer fence: `====` wraps `===`. Careful: a same-length bare
+   `===` in the body closes the block even if you intend a labeled close —
+   the labeled close only spares you length-counting, it does NOT protect
+   same-length inner fences.
+3. **Headings are ATX `#` only** (`#`…`######`). No setext underlines, no
+   `---` breaks, no YAML frontmatter — metadata is a `=== meta` block, and the
+   document TITLE lives there (`title = "…"`), not in an H1. A heading may
+   carry a stable explicit id: `## Title {#sec}`.
+4. **Give every section a stable `{#id}`** — `## Findings {#findings}` — then
+   keep ids unique per document, with **every reference resolving**:
+   `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`, `other.geml#id`. An
+   unresolved reference is a build **error**. Naming them is the part that pays
+   later: a document with no ids costs what Markdown costs, because there is
+   nothing for `geml get` to read or `geml set` to replace short of the file.
+5. **No raw HTML.** Notes → `=== note`, comments → `%%` lines, hidden content
+   → `{hidden}`, addressable prose → `=== text`, verified data → `=== data`
+   (json/jsonl; `code` shows text, `data` IS data).
+
+## Validate every time
+
+```sh
+geml check file.geml          # diagnostics + exit code only; exit 0 = correct
+geml check --json file.geml   # machine-readable diagnostics array
+```
+
+If `geml` is not on PATH: `npm i -g @geml/geml` (package `@geml/geml`, command
+`geml`), or run without installing via `npx -y @geml/geml check file.geml`.
+Inside the geml-spec repo prefer the local build:
+`node geml-parser/dist/geml.js <args>`. If no parser is reachable, follow the
+golden rules and validate once it is.
+
+`geml skill install` sets all of this up user-global, and installs this text
+into whatever other agent tools it detects — a tool's directory has to be there
+already; none is ever created for you. `--dry-run` shows what it would do.
+
+## Work blockwise (agent editing)
+
+```sh
+geml list    file.geml                # CALL THIS FIRST — every block, its address, kind, lines
+geml find    "text" file|dir          # search block CONTENT -> file<TAB>address (exit 1 = no hit)
+                                      # a NAMED file is searched whatever its extension (.md too);
+                                      # a directory walks *.geml only
+geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
+geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
+geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
+geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
+```
+
+Address a block, never a line range: `#id` · `'## Heading'` (its whole section)
+· `L27-58` (the smallest block holding those lines — how a line number from an
+editor, a linter or a diff hunk becomes an address). `list` and `find` print
+addresses that paste straight into the others, so neither `grep` nor a line
+count is needed to locate anything.
+
+The rest is one `geml get` away in the reference below, and stays there because
+it is needed rarely and this page is read every time: the remaining address
+forms in `#cli`, and in `#editing` the three ways to cut a section
+(`--head`/`--intro`/`--body`), the experimental `replace`, and what a write that
+drops blocks does.
+
+## Full reference — pull ONE section, not the whole file
+
+`references/authoring.geml` (under this skill's base directory) holds the
+detailed reference. Fetch just the section you need:
+
+```sh
+geml get <skill-base>/references/authoring.geml '#tables'
+```
+
+| section | covers |
+|---|---|
+| `#typed-block` | block anatomy, attribute object, examples of every registered type |
+| `#tables` | pipe/CSV bodies, `compute=`, `summary=`, printf display, `span=` merges |
+| `#charts` | `geml-chart` diagrams bound to a table via `data=#id` |
+| `#data` | the `data` block — value tree, `json`/`jsonl` formats, blind append, chart binding |
+| `#inline` | inline markup, links/refs/footnotes, task lists, media embeds |
+| `#hidden` | `%%` comments, `{hidden}`, `{{key}}` interpolation, `=== embed` |
+| `#cli` | every CLI verb — get/set/add/delete/rename, `--to` conversion, check |
+| `#editing` | the blockwise editing loop + `.gemlhistory` versioning |
+| `#project-config` | carrying a project's Claude config docs in GEML, quietly |
+| `#checklist` | full pre-flight authoring checklist |

package/skills/geml/references/authoring.geml

@@ -0,0 +1,365 @@
+=== meta
+title = "GEML authoring reference"
+role = "detail sections behind the geml skill"
+howto = "pull ONE section: geml get <this-file> '#<section-id>' — ids: typed-block, tables, charts, data, inline, hidden, cli, editing, project-config, checklist, reference"
+===
+
+%% The golden rules and the validation workflow live in ../SKILL.md (always loaded
+%% with the skill). This file holds the full detail, one addressable section per
+%% topic. Keep the section ids stable — SKILL.md's section map points at them.
+
+# Typed block {#typed-block}
+
+==== code {#ex-anatomy lang=geml}
+=== <type> {#id .class key=val}
+<body>
+===
+====
+
+The **type** decides how the body is read (the *body mode*):
+
+- `raw` (verbatim): `code`, `diagram`, `table`, `data`, `math`, `embed`
+- `flow` (parsed prose with inline markup): `note` (callout), `text`
+  (addressable prose — an `#id` for a run of plain prose, no callout chrome;
+  use sparingly)
+- `data` (one `key=val` per line): `meta`
+
+An **unknown type** is a warning (body kept raw) — prefer the registered types.
+
+## Attribute object {#attribute-object}
+
+Written `{#id .class key=val}` on the opening fence or a heading line:
+
+- `#id` — unique anchor for references.
+- `.class` — a *semantic* label (no styling implied).
+- `key=val` — typed: quoted `"…"` = string; `true`/`false` = bool;
+  integer/float syntax = number; any other bare word = string. A **bare word
+  with no `=` is a boolean flag set to true** (e.g. `hidden`).
+- Order is insignificant; recommended `#id`, then `.class`, then `key=val`.
+
+## Examples of each block {#block-examples}
+
+==== code {#ex-blocks lang=geml}
+=== meta
+title = "Budget plan"
+version = "1.0-draft"
+===
+
+=== code {#hello lang=python}
+print("hi")
+===
+
+=== note {.warning}
+Back up before upgrading.        (flow body — inline markup works here)
+===
+
+=== text {#thesis}
+Addressable prose: plain rendering, but geml get/set #thesis can edit it.
+===
+
+=== math {#gauss caption="Gaussian integral"}
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+===
+
+=== diagram {#flow format=mermaid caption="Review flow"}
+graph LR
+  A[Draft] --> B{Review} -->|ok| C[Publish]
+===
+====
+
+`diagram` hosts an external DSL (`mermaid`, `graphviz`, `dot`, `d2`,
+`plantuml`, `geml-chart`); the processor never interprets the body. An unknown
+`format` is a warning.
+
+# Tables {#tables}
+
+Two bodies, one model: the visual (pipe) form, or the data form
+(`format=csv`/`tsv`). Both parse to the same table model.
+
+==== code {#ex-tables lang=geml}
+=== table {#budget caption="Annual cost"}
+| Plan  | Months | Rate |
+|-------|-------:|-----:|
+| Basic |      1 |   30 |
+===
+
+=== table {#fy25 format=csv header=1 compute="FY [%.1f] = Q1 + Q2 + Q3 + Q4" summary="Segment = 'Total'; FY [%.1f] = sum(FY)"}
+Segment,  Q1, Q2, Q3, Q4
+Cloud,     8, 10, 12, 14
+===
+====
+
+- `delim=";"` — one character replacing the data form's natural delimiter (`,`
+  for csv, tab for tsv): European CSV, `|`-delimited exports. Anything but a
+  single character is an error, a tab is `format=tsv` (attribute values have no
+  escapes), and `delim` without a data `format` is ignored (warning). The data
+  form splits and nothing more — it never strips outer `|` like the visual form.
+- `compute="Name = expr; Name2 = expr2"` — per-row formulas over columns (by
+  header name, or single letter `A`,`B`,…), operators `+ - * / ( )`.
+  Reference an earlier computed column by name. Quote names with spaces:
+  `'Unit Price'`.
+- Aggregates `sum|avg|min|max|count` (e.g. `sum(FY)`) — for the `summary=`
+  foot row. A bare (non-aggregated) column ref in `summary` is an error.
+- A trailing `[printf]` on a name sets numeric display: `FY [%.1f]`,
+  `P [%.1f%%]`.
+- Merge cells with `span="r2c1:2x1"`.
+
+# Charts {#charts}
+
+Render a table — don't copy it:
+
+==== code {#ex-chart lang=geml}
+=== diagram {#rev format=geml-chart data=#fy25 type=bar x=Segment y=FY}
+===
+====
+
+`data=#id` must point at a `table` block (single source of truth); the column
+refs (`x`, `y`, …) are checked. `type ∈ {bar,line,area,pie,scatter}`. The body
+is empty (the spec lives in attributes).
+
+# Data blocks {#data}
+
+`=== data` carries the VALUE TREE (scalars/arrays/objects — JSON's value
+domain) as verified data. The dividing line: `code` shows text the processor
+never interprets; `data` IS data — the body parses under `format=`, and a
+body the engine rejects is a build ERROR naming the line.
+
+==== code {#ex-data lang=geml}
+=== data {#cfg}
+{"name": "geml", "port": 8140}
+===
+
+=== data {#log format=jsonl}
+{"ts":"09:00","latency":41}
+{"ts":"09:01","latency":58}
+===
+
+=== diagram {format=geml-chart data=#log type=line x=ts y=latency}
+===
+====
+
+- `format=json` (default): the body is ONE JSON value. `format=jsonl`: one
+  JSON value per non-blank line — the record-stream form. Because a document
+  is a flat sequence of blocks, appending a complete `data` block at EOF is a
+  valid continuation of any document (blind-append, like a jsonl file, with
+  ids and verification on top).
+- `src=` loads the content from an external file (`.json`/`.jsonl`; explicit
+  `format=` wins over the extension) — exactly ONE of `src=` and a body.
+  `http(s)` sources load at render time. The log arrangement: keep the
+  records in a plain `.jsonl` any tool can append to and tail — the GEML doc
+  is its verified, chartable view. A chart may also name a local file
+  directly: `data=log.jsonl`.
+- A source route MAY narrow the file to a line range — `src=log.jsonl#L900-999`,
+  1-based and inclusive — which is how a window of a long log is addressed.
+  `code` uses the SAME route syntax for the code it shows
+  (`src=src/attrs.ts#L14-24`): the route is the source of truth, a range the
+  file no longer has is an error (a drifted reference fails the build), and a
+  body kept alongside it is a snapshot that warns when it goes stale. Routes
+  resolve document-relative, or relative to `--root` when one is given.
+- `yaml`/`toml` are RESERVED names: no engine in the core — body kept raw
+  plus a warning, never guessed. csv/tsv belong to `table`, not `data`
+  (their delimiter/header dialect parameters only mean something against a
+  column model).
+- A chart's `data=#id` accepts a `data` block whose value is a RECORD ARRAY
+  (non-empty array of objects): keys project to columns; every column the
+  chart references must be present and scalar in every record.
+- `schema=` names a block (`#id`) or GEML document holding a schema —
+  reference-checked only today; value validation is a later GEP.
+- The parsed value lives in the model: `geml get '#cfg' --json` returns the
+  node with `value`, no re-parsing. `geml fmt` canonicalizes: json at
+  two-space indent, jsonl one compact value per line.
+
+# Inline markup {#inline}
+
+Inside flow blocks only: `*emphasis*` · `**strong**` · `` `code` `` ·
+`~~strike~~` · `$inline math$`.
+
+- Link: `[text](https://…)` · internal ref `[text](#id)` · auto-ref `[[#id]]`
+  (link text from the target's caption/heading) · footnote `[^id]`.
+- Media embed: `![alt](clip.mp4)` — kind (image/audio/video) inferred from the
+  extension; renders/plays in place (a link navigates, an embed does not).
+- Hard line break: trailing `\`. Escape punctuation with `\`; block syntax at
+  line start is escaped the same way (`\===`, `\#`).
+- Lists: `- item` / `1. item`. **Task list**: `- [ ] open` / `- [x] done`.
+
+# Hidden, comments, interpolation, embed {#hidden}
+
+- **`%%` line** — a hidden, raw, never-rendered note (TODO/review remark).
+  Kept in the model (tools can find it) but NOT inline-parsed, so a scratch
+  note can't break the build. Line-start only.
+- **`{hidden}` block** — present in the model and **fully reference-checked**,
+  but not rendered. Use it for a source table that only feeds a chart:
+  `=== table {#fy25 hidden …}`.
+- **`{{key}}`** in flow text is replaced with the matching `=== meta` value;
+  an unknown key is a build **error** (single source of truth). Inside a code
+  span it stays verbatim — that is how to *show* the syntax.
+- **`=== embed {src=other.geml#id}`** stands for content that lives elsewhere
+  and renders it in place; a fragment naming a heading takes the whole
+  section, and no fragment takes the whole document. `src=` is
+  reference-checked, so a reference-only index document can be validated.
+  Cycles are an error; nesting is capped.
+
+# CLI {#cli}
+
+Validate first — `geml check` exits non-zero on any error, a hard pass/fail
+signal, and prints only diagnostics (cheap on context):
+
+=== code {#cli-check lang=sh}
+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
+===
+
+All commands accept `-` to read from stdin.
+
+=== code {#cli-verbs lang=sh}
+geml file.geml                        # document-model JSON (default --to json)
+geml list    file.geml                # CALL FIRST: every block, its address, kind, line range
+geml find    "text" file|dir          # search block CONTENT -> file<TAB>address; exit 1 = no hit
+                                      # a NAMED file is searched whatever its extension — `list`,
+                                      # `get` and `find` all read Markdown, so this addresses a
+                                      # plain README without converting it; a DIRECTORY walks *.geml
+geml get     file.geml                # same listing as `list` (the no-selector default)
+geml get     file.geml '#id'          # print ONE block (raw span; --json = model node)
+geml get     file.geml '=== note'     # every block of a type; '@a3f9c1d2' = a block with no #id
+geml get     file.geml 'L27-58'       # position: the smallest block holding those lines
+geml get     file.geml '#sec' --intro # a section cut three ways: --head | --intro | --body
+geml set     file.geml '#id' --in f   # replace ONE block (guarded: re-parsed, never writes broken)
+geml set     file.geml '#sec' --intro # replace just the opening; the subsections stay put
+geml replace file.geml OLD NEW        # EXPERIMENTAL, may be withdrawn: literal swap, checked and
+                                      # reported; --within '#id' or '=== type' narrows the scope
+geml add     file.geml --after '#id' --in f   # insert a fragment (keeps its own ids)
+geml delete  file.geml '#id' ['#id2']         # remove one or more blocks
+geml rename  file.geml '#old' '#new'          # rename an id AND every reference to it
+===
+
+A heading id addresses its whole SECTION (through the next same-or-higher
+heading); `--head` narrows any id to its head line alone (rename a heading, or
+edit a block's attributes without re-sending its body).
+
+An `embed` block has no content of its own, so `get '#e'` returns the FRAME
+(its `src=`). To see what the window looks onto, add `--view`:
+
+=== code {#cli-view lang=sh}
+geml get file.geml '#e' --view          # the entity block the chain ends at
+geml get file.geml '#e' --view --body   # just its body — the usual want
+geml get file.geml '#e' --view --json   # its model node, plus `from`
+===
+
+`--view` resolves to the ENTITY block: multi-layer chains are followed to the
+end, and on any block that is not an embed it changes nothing. Provenance goes
+to stderr (`view: #e -> part.geml#tip`) because the bytes belong to ANOTHER
+document — their refs and relative paths resolve against that one. It is
+read-only (`set` refuses it), chain reads are confined to `--root` (default: the
+document's own directory), and a non-local target is refused, never fetched. A
+SECTION selector is the identity: piercing an embed inside it would splice two
+documents' bytes together, so address that embed instead. MCP: `geml_get
+{view: true, part: "body"}`.
+
+Conversion is ONE entry — `geml <file> --to <format>` — not a verb per format:
+
+=== code {#cli-convert lang=sh}
+geml file.geml --to html -o out.html  # one self-contained, interactive HTML file
+geml file.geml --to md   -o out.md    # GitHub-Flavored Markdown (lossy; loss notes on stderr)
+geml input.md  --to geml -o out.geml  # Markdown -> GEML
+geml file.geml --to geml              # canonical re-format (idempotent)
+===
+
+Install: `npm i -g @geml/geml` (package `@geml/geml`, command `geml`), or
+one-shot via `npx -y @geml/geml <args>`. From a clone of the geml-spec repo:
+`cd geml-parser && npm install && npm run build && npm link`, or run
+`node geml-parser/dist/geml.js <args>` directly.
+
+# Editing and versioning {#editing}
+
+When revising a `.geml` over many steps, work **one block at a time** and
+snapshot as you go, rather than re-emitting the whole file:
+
+=== code {#editing-loop lang=sh}
+geml get    file.geml '#intro'         # read just this block (a heading id = its whole section)
+geml set    file.geml '#intro' --in -  # replace just this span (stdin or --in FILE);
+                                       #   the splice is re-parsed and REJECTED if it breaks the doc
+geml history save   file.geml -m "…"   # snapshot into the .gemlhistory sidecar — do this each step
+geml history get    file.geml          # revisions, newest first; first column IS the --rev selector
+geml revert file.geml '#intro'         # roll ONE block back to the previous revision (= --rev -1)
+geml revert file.geml '#intro' --rev -2       # …two revisions back (also: --rev 0 = tip, --rev <id>)
+geml revert file.geml '#intro' --rev changed  # …the block's last ACTUAL change — use this after other
+                                       #   blocks were written since; a fixed -N silently no-ops there
+===
+
+**Retain every step.** `history` and `revert` can only recover what was saved
+— so after each meaningful edit to a `.geml`, run `geml history save`
+(automatable with a `PostToolUse` hook). Together, `get`/`set` (address one
+block) and `history`/`revert` (version and rewind it) let an agent revise a
+document incrementally and undo any single section.
+
+**A section can be cut three ways**, on `get` and `set` alike: `--head` (the
+heading line), `--intro` (what it says before its first subheading — empty when
+one follows immediately, the whole body when none does), `--body` (everything
+under it, so it always contains the intro). `--intro` is how you edit a
+section's opening without pulling its subsections into context, and setting an
+empty one writes an opening where the section had none.
+
+**When the exact old text is already known** and nothing needs reading — a
+version string in six places, a renamed term — `geml replace` is the cheap path,
+and the one to prefer over dropping to `sed`: the same two short strings, but
+the result is re-parsed before it lands, the blocks it touched are named back to
+you, and it is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern,
+and refuses a swap that would rename an id (use `geml rename`, which fixes the
+references too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but
+do not build anything on it that cannot change.
+
+**A write is refused when it would BREAK the document**, never merely because it
+removes something: a replacement that drops blocks is carried out and NAMED on
+stderr — unnamed blocks included — with `geml revert` as the way back. Read,
+edit, write back, and nothing is dropped, because `get` handed those blocks to
+you. Send content that omits them only when removing them is the point.
+
+**Where sidecars do NOT belong:** a doc that git already versions — config
+docs especially — usually needs no `.gemlhistory`; do not create one there
+unless the user asks for finer-than-commit history.
+
+# Project config in GEML {#project-config}
+
+A project's Claude instruction docs can live in GEML with **zero settings
+changes and zero hooks** — quiet by design:
+
+1. Put the doc at `.claude/geml/<name>.geml` (e.g. `instructions.geml`), one
+   topic per section, each heading with a stable `{#id}` — so a single rule
+   can be edited (`geml set`) or removed (`geml delete`) without touching the
+   rest.
+2. Reference it from the project's `CLAUDE.md` with one import line:
+   `@.claude/geml/instructions.geml` — Claude Code expands imports of any
+   file type literally at session start (recursive, max 4 hops).
+3. Leave everything else in `CLAUDE.md` alone — especially tool-managed,
+   installer-appended sections (they are updated in place by their
+   installers and must stay in Markdown where those tools grep for them).
+4. The imported `.geml` must not contain bare `@path` tokens in prose — the
+   import scanner does not recognize GEML code fences, only Markdown ones.
+5. No `.gemlhistory` for these files: git is their history.
+
+When asked to create or restructure project instructions, prefer this shape
+without ceremony; never convert files the user did not ask about, and never
+move a tool-managed block out of `CLAUDE.md`.
+
+# Authoring checklist {#checklist}
+
+- [ ] Every closing fence is a `=` run of exactly the opening length, or the
+      labeled fence `=== #id` of an id-carrying block.
+- [ ] Bodies containing `===` runs are wrapped in a LONGER fence (`====`) —
+      a same-length bare `===` in the body closes the block early, labeled
+      close or not.
+- [ ] Headings are ATX `#`; metadata is a `=== meta` block (no frontmatter);
+      the document title is `title = "…"` in meta, not an H1.
+- [ ] All ids unique; all `[t](#id)` / `[[#id]]` / `[[doc.geml#id]]` /
+      `[^id]` / `src=` / `data=` references resolve.
+- [ ] `{{key}}` keys exist in `=== meta` (code-span occurrences stay literal).
+- [ ] No raw HTML; comments use `%%`, hidden content uses `{hidden}`.
+- [ ] Validated: `geml check` reports zero error diagnostics (exit 0).
+
+# Reference {#reference}
+
+Full normative spec, in the geml-spec repo
+(https://github.com/geml-spec/geml): `spec/GEML-spec.md` (English),
+`spec/GEML-spec_CN.md` (中文). History sidecar: `spec/GEML-history-spec.md`.
+The spec is itself written in GEML (dogfood): `spec/in_geml_format/`.

package/skills/geml-code-graph/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: geml-code-graph
+description: >-
+  Build, view, update, and navigate a project's call graph as GEML codemap
+  documents. Use when asked to see/update/build a project's code graph or
+  codemap (看下/更新下 code-graph), when asked "who calls X" / "what does X
+  call" / to trace a call chain or impact path, or whenever a
+  .geml-code-graph/ directory with index.geml and _index/name-lookup.json
+  exists.
+  Detects the project's languages itself — never asks the user; viewing ends
+  with the browser OPEN on the graph.
+---
+
+# Code-graph navigation (codemap profile)
+
+The call graph lives as **text documents, not a database**
+([profile](https://github.com/geml-spec/geml/blob/main/docs/design/specs/codemap/codemap-profile.md)):
+one GEML document per container (module / dir /
+file), each with ONE meta (`module`, `src`, `entry`, `resolution-default`),
+empty-body `code` blocks per method, and up to three CSV edge tables —
+`#calls` (out), `#called-by` (in), `#unresolved` (blind spots). The build's
+`verify` has checked that every edge reference resolves.
+
+## The moves
+
+```sh
+# 1. resolve a name — where does a symbol live
+node -e "console.log(JSON.stringify(require('./.geml-code-graph/_index/name-lookup.json')['hashtableFind'],null,1))"
+#   → [{"anchor":"c:hashtable.c#hashtableFind(…)","doc":"hashtable.c.geml","id":"hashtableFind"}, …]
+#   Multiple entries = real ambiguity (e.g. a .c definition and a .h inline) — inspect each.
+
+# 2. container overview — the module's surface, one glance
+head -8 .geml-code-graph/hashtable.c.geml          # meta: entry = the externally-called methods
+
+# 3. open the method block (src= tells you exactly where the code is)
+geml get .geml-code-graph/hashtable.c.geml '#hashtableFind'
+
+# 4. forward: what it calls (grep your method's rows; follow doc.geml#id refs)
+geml get .geml-code-graph/hashtable.c.geml '#calls'
+
+# 5. reverse: who calls it (aggregated, with file:line sites)
+geml get .geml-code-graph/hashtable.c.geml '#called-by'
+```
+
+A reference is `#id` (same document) or `sibling.geml#id` (that document, that
+block) — `geml get` it the same way. `index.geml` holds the repo-level view:
+app entries in its meta, `#modules` / `#module-edges` aggregate tables.
+
+## Reading the tables
+
+| Line | Meaning |
+|---|---|
+| `#calls` row, empty confidence | resolved at the document's `resolution-default`, high confidence |
+| `#calls` row `kind=candidate` | dispatch ambiguity: one of several implementations, right after its main `call` row. Treat the SET as the answer, never just the first |
+| `#calls` row confidence `medium`/`low` | the extractor is less sure — say so when reporting |
+| `#unresolved` rows (hidden table) | calls the extractor could NOT resolve — **blind spots, not evidence of absence**; fall back to grep when one matters |
+| `#called-by` absent for a method | no *resolved* callers. Under `resolution-default = heuristic` that means little; under `cpg` it is strong (but pointer/dynamic dispatch still lands in `#unresolved`) |
+
+Symbol classes: `.accessor` (bean get/set/is leaves — the graph view hides
+them by default, tables keep them) · `.leaf` (calls nothing, only called — usually skippable when
+tracing logic) · `.test` (test territory) · `.flow-entry` (critical-flow start).
+
+## "看下/更新下 X 项目的 code-graph" — the end-to-end move
+
+The toolkit ships inside the `@geml/geml` package: `geml codemap …`
+(without a global install: `npx -y @geml/geml codemap …`).
+
+### Dispatch first — generation is slow, the conversation must not block on it
+
+Indexers take real time (scip: seconds–minutes; Joern on a repo: minutes).
+Pick the executor BEFORE starting:
+
+- **Codemap exists, user wants to look** → inline, seconds:
+  `serve --background` + open the browser. No subagent.
+- **Update asked and `_index/refresh.json` exists** → no subagent either:
+  `geml codemap refresh <dir> --background` (detached process, costs the
+  conversation nothing). Open the CURRENT graph immediately — serve renders
+  live, so when the refresh lands, F5 shows it; say exactly that.
+- **geml files must be (re)generated agentically** — first build, no recipe
+  recorded, adapters change, or a refresh failed → hand the WHOLE generation
+  to ONE subagent (Agent tool; `run_in_background: true` so the user can keep
+  working). Its prompt must be self-contained: project root; detect the
+  languages per the table below (never ask); the exact indexer +
+  `geml codemap build --history` + `geml codemap verify` commands; verify
+  MUST exit 0; write `_index/refresh.json` with the exact commands used;
+  return container/method/entry counts, verify result, and any language
+  gaps. The MAIN conversation does the last mile itself when the subagent
+  reports: `serve --background`, open the browser (if an older codemap was
+  already on screen, telling the user to F5 is the whole move).
+
+1. **Have a codemap?** `<proj>/.geml-code-graph/index.geml` exists → skip to
+   step 4 (view) or step 3 (update was asked). An older `codemap/`/`graph/`
+   tree from before the rename is not special: regenerate into
+   `.geml-code-graph/` (one build; carry the `*.gemlhistory` sidecars over
+   first if they matter) and remove the old directory.
+2. **Detect the language(s) — NEVER ask the user.** (Steps 2–3 are the
+   generation work — per Dispatch above they normally run inside the
+   subagent.) Judge from manifests
+   first, then source-file counts (`Glob`/`ls`). Multiple languages with
+   real code (≥ a handful of files each) → one build with REPEATED
+   `--adapter` groups; the codemap merges them (Java+TS validated).
+
+   | Signal | Indexer → adapter |
+   |---|---|
+   | `tsconfig.json` / mostly `.ts` `.tsx` `.js` | `npx --yes @sourcegraph/scip-typescript index --output index.scip` (run IN the target repo/subproject) → `--adapter scip --raw index.scip` |
+   | React / JSX (`.tsx` `.jsx`) | same scip route, verified tier: `<Child />` render edges, custom-hook calls, and `useReducer(reducer, …)` wiring all resolve high — arrow components (`const Foo = () =>`) included. Indirect dispatch is **absent, not `#unresolved`**: callback-prop calls (`onToggle(…)`), `dispatch()`→reducer case handling, and context-injected functions ride scip locals/members and leave NO edge — grep when one matters. Also invisible: `memo()`/`forwardRef()`-wrapped components (const = call, inner fn is a local) and module-scope `render(<App />)` callers |
+   | `Cargo.toml` / `.rs` | `rust-analyzer scip . --output rust.scip` (run IN the crate/workspace root; missing → `rustup component add rust-analyzer` or the rust-analyzer GitHub releases page) → `--adapter scip --raw rust.scip`. Precise tier: rust-analyzer-resolved, cross-file/cross-crate calls included; calls into std/external crates land in `#unresolved` |
+   | `pom.xml` / `build.gradle` / `.java` | Joern (locate per **Locating Joern** below; JDK required): `GEML_SRC=<abs-src> GEML_OUT=<abs-raw> GEML_LANG=JAVASRC joern --script <pkg>/codemap/joern-export.sc` → `--adapter joern --raw <raw>`. GEML_LANG takes Joern's `--language` names, UPPERCASE — lowercase `javasrc` fails with "No CPG generator exists" |
+   | `.c` / `.h` | same Joern route, `GEML_LANG=NEWC` (valkey-validated) |
+   | `.py` / `go.mod` / `.kt` | Joern frontends, `GEML_LANG=PYTHONSRC` etc. (usable tier — SAY SO in your report) |
+   | only a code-review-graph `graph.db` | `--db <graph.db>` (heuristic tier — say so) |
+   | none of the above | report honestly which languages are unsupported; do not guess |
+
+   `.vue` / `.svelte` SFCs: covered — use the AUTO build (`geml codemap
+   build --root <proj>`), not the manual per-indexer route. It virtualizes
+   each SFC project (Volar / svelte2tsx, fetched hermetically via npx) into
+   shadow TS with line-map sidecars, runs one scip pass over shadows + the
+   project's real TS/JS, and attributes every symbol back to the original
+   file and line. Template event handlers surface as edges from a synthetic
+   `<Component>.template` node (`@click="save"` → `#App-template, #save`;
+   mustapi-validated across three Vue apps, 85/85 SFCs). Honest residuals —
+   say them when reporting: component-TAG usage (`<Child/>`) is not a call
+   edge; Nuxt auto-imports (unimported `ref`, auto-registered components)
+   don't resolve, so those references drop; top-level `<script setup>`
+   calls, including `computed(() => …)` bodies, drop exactly like
+   module-level calls in plain TS; a failed virtualization falls back to
+   plain TS indexing and says so.
+
+   Vendored source trees explode the job list — next.js's
+   `packages/next/src/compiled/` carries ~140 checked-in package.json bundles,
+   each becoming its own scip job. Prune them at build time:
+   `geml codemap build --root <proj> --exclude "src/compiled/**"` (repeatable;
+   the exclusion also keeps their symbols out of the graph).
+
+   **Locating Joern — never hardcode a path.** Resolve it fresh on each run,
+   in this order: (1) `joern` on PATH — if `joern --version` works, use it;
+   (2) else read `~/.claude/skills/geml-code-graph/config.json` (`{"joern": "<launcher-or-dir>"}`)
+   and pass it as `geml codemap build … --joern <path>` (or export `GEML_JOERN`);
+   (3) else ASK the user for the joern-cli location (Windows: the folder unzipped
+   from joern-cli.zip; macOS/Linux: the joern-install.sh install dir), WRITE it
+   into that JSON file, then reuse it. `<path>` may be the launcher itself or the
+   directory holding it (`joern.bat` on Windows, `joern` on unix). Ask at most
+   once per machine — after that the JSON answers. Mirrors the CLI's own
+   `--joern` / `GEML_JOERN` resolution.
+3. **Build + verify** (also the "更新" path — builds are deterministic,
+   only changed documents are rewritten):
+
+   ```sh
+   geml codemap build --adapter scip --raw index.scip --root <proj> \
+        --out <proj>/.geml-code-graph --history      # --container module|dir|file: match
+                                            # the layout (default dir; flat C repo → file)
+   geml codemap verify <proj>/.geml-code-graph       # MUST exit 0 before showing anyone
+   ```
+
+   **First successful build: record the recipe** so `refresh` (and the
+   commit hook) can replay it — write `<proj>/.geml-code-graph/_index/refresh.json`
+   with the EXACT commands you ran:
+
+   ```json
+   { "root": "..",
+     "steps": ["npx --yes @sourcegraph/scip-typescript index --output index.scip",
+               "geml codemap build --adapter scip --raw index.scip --root . --out .geml-code-graph --history",
+               "geml codemap verify .geml-code-graph"] }
+   ```
+
+   From then on, "更新下" = `geml codemap refresh <proj>/.geml-code-graph` (skips
+   itself when git HEAD hasn't moved; log at `_index/refresh.log`).
+4. **View — finish with the browser OPEN, not with instructions.**
+
+   ```sh
+   geml codemap serve <proj>/.geml-code-graph --background   # detached: SURVIVES the agent session;
+                                                    # http://localhost:8140, pages render live
+                                                    # from .geml — rebuild + F5, never stale.
+                                                    # already-running port → reused, not stacked.
+   geml codemap serve <proj>/.geml-code-graph --stop         # stop it (pid: .geml-code-graph/_index/serve.pid)
+   geml codemap render <proj>/.geml-code-graph               # serverless alternative: bake .html next to
+                                                    # each doc; open file:///…/.geml-code-graph/index.html
+   ```
+
+   Always `--background` (a viewer must not die with the session). Then open
+   it for the user: Windows `start "" <url>` (or `Start-Process <url>`),
+   macOS `open <url>`, Linux `xdg-open <url>`. Port taken by something
+   else → pick another (`--port`), open that one.
+
+`index.html` is the module overview; clicking a module opens its page inside
+the graph area (nested view). Method pages: click = callee chain, ⊕ on an
+entry = full caller chain, breadcrumb walks back up.
+
+## Keep it in sync on every commit (optional per-project hook)
+
+With the recipe recorded (step 3), a Claude Code PostToolUse hook makes any
+`git commit` Claude runs in that project refresh the codemap in the
+BACKGROUND (never blocks the commit; non-commit commands exit instantly;
+projects without `refresh.json` are silently skipped). Add to the project's
+`.claude/settings.json`:
+
+```json
+{ "hooks": { "PostToolUse": [ { "matcher": "Bash", "hooks": [
+  { "type": "command", "command": "geml codemap refresh .geml-code-graph --hook --commit" }
+] } ] } }
+```
+
+(`.geml-code-graph` = the codemap dir relative to the project root; use an absolute
+path if the hook cwd differs.) With `--commit`, the refreshed documents land
+as their own follow-up commit — `chore(codemap): refresh for <sha>`, codemap
+dir only — so the next push carries code + graph together. It is loop-safe
+(the follow-up commit changes no source file, so the refresh it triggers
+skips) and it stands down when HEAD moved during the refresh or a merge is in
+progress. Drop `--commit` to keep the old behavior: refreshed files stay in
+the working tree for you to include in a later commit.
+
+Between commits (editing-time sync), `geml codemap serve <dir> --watch`
+re-runs the recipe after 30s of quiet whenever an indexed source file
+changes — pages render live, so a browser reload shows the new graph.
+
+Add `--history [-m msg]` to build to snapshot changed documents into
+`.gemlhistory` sidecars — then `geml history get .geml-code-graph/<doc>.geml` shows
+the graph's evolution and `geml revert .geml-code-graph/<doc>.geml '#method' --rev -1`
+rolls one method's edges back. Language maturity tiers and the smoke-test
+gate: [DESIGN-geml-code-graph.md](https://github.com/geml-spec/geml/blob/main/docs/design/specs/codemap/DESIGN-geml-code-graph.md) §3.4. An MCP wrapper with the same
+three moves exists (`geml mcp --root <dir>`, which serves them next to the
+document tools when the root holds a graph); the CLI path works without it.