@omgbase/core 0.28.0 → 0.29.2

package/dist/src/mcp/server.js

@@ -12,19 +12,19 @@ import { oqxRunAsync, collectSemanticPhrases } from "../oqx/run.js";
 import { graphNeighborhood } from "./graph.js";
 import { textSearch } from "../search/text.js";
 import { EngineError, errorBody } from "./errors.js";
-import { argumentError, stringList, validateArguments } from "./arguments.js";
+import { argumentError, nearest, stringList, validateArguments } from "./arguments.js";
 import { linksRetarget, linksRepair } from "../mutate/macros.js";
 import { canonicalDocPath } from "../mutate/docs.js";
 import { applyEffects, executeByDigest, executePlan, planEffects } from "../mutate/plan.js";
 import { appendEffects, applySugar, checkEffects, createEffects, deleteDocEffects, docsAppendEffects, insertEffects, mergeEffects, moveBlocksEffects, moveDocEffects, moveLinks, nodeSetEffects, removeBlocksEffects, requireAbsentPath, retargetEffects, setMetaEffects, splitEffects, updateBlockEffects, updateContentEffects, } from "../mutate/sugar.js";
-import { fixTool } from "../mutate/canonical.js";
+import { canonicalJson, fixTool } from "../mutate/canonical.js";
 import { historyNode, diffBlocks, docDiffUnified, changesSince, docHistory } from "../graph/history.js";
 import { linksStale, linksStaleSummary } from "../graph/link-health.js";
 import { resolve as resolveThing } from "../search/resolve.js";
 import { reposStatus, syncStatus, reposList } from "../sync/admin.js";
 import { observeFile, observeMany, observeDelete } from "../sync/observe.js";
 import { withWriterLockAsync } from "../sync/writer-lock.js";
-import { QUERY_SYNTAX } from "./reference.js";
+import { QUERY_SYNTAX_CARD, QUERY_SYNTAX_SECTION_NAMES, QUERY_SYNTAX_SECTIONS, querySyntaxSection } from "./reference.js";
 import { versionInfo } from "../version.js";
 import { storagePath, referencePath } from "../core/paths.js";
 import { isContainerBlock } from "../format/index.js";
@@ -84,7 +84,7 @@ const selectionExpectSchema = z.object({ max: z.number().int().nonnegative() });
 function selectorArgs(args) {
     return { ...(args.select !== undefined ? { select: args.select } : {}), ...(args.expect !== undefined ? { expect: args.expect } : {}) };
 }
-const effectSchema = z.looseObject({ op: z.enum(["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"]) }).describe("one effect: { op: \"create\", path, markdown, frontmatter? } | { op: \"insert\", into: Target, at?, markdown, expect? } | { op: \"set\", target, field, value, expect? } | { op: \"unset\", target: document, field: \"frontmatter.<key>\", expect? } | { op: \"move\", target: document, to, retarget_inbound? } | { op: \"move\", targets: [block…], into, at?, expect? } | { op: \"remove\", target: document } | { op: \"remove\", targets: [block…], expect? } | { op: \"split\", target: block, at: [byte…], expect? } | { op: \"merge\", targets: [block…], separator?, expect? } | { op: \"retarget\", repairs: [{ from, to }], path_glob? }. Target: a bare document path, a block/node id, $new.<n> (an identity an earlier effect creates), or { kind: \"document\", id? | path? } | { kind: \"block\", id } | { kind: \"node\", id } | { kind: \"section\", heading_id }. at: \"start\" | \"end\" | { before: <block id> } | { after: <block id> } — a place among the children of `into`, so \"right after block X\" is into: X's parent (its parent block id, or the document path when X is top-level), at: { after: X }. field: a block's is \"markdown\" or \"attrs.checked\"; a document's \"frontmatter.<key>\" or (set only) \"content\"; a node's an editable property (value, name, checked). expect on a single-target op: { content_hash?, parent_children_hash?, revision? }; on remove/merge targets it is keyed by block id: { <block id>: { content_hash?, parent_children_hash? } }. expect: { max } is the request's top-level argument beside select, never inside an effect.");
+const effectSchema = z.looseObject({ op: z.enum(["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"]) }).describe("one effect: { op: \"create\", path, markdown, frontmatter? } | { op: \"insert\", into: Target, at?, markdown, expect? } | { op: \"set\", target, field, value, expect? } | { op: \"unset\", target: document, field: \"_frontmatter.<key>\", expect? } | { op: \"move\", target: document, to, retarget_inbound? } | { op: \"move\", targets: [block…], into, at?, expect? } | { op: \"remove\", target: document } | { op: \"remove\", targets: [block…], expect? } | { op: \"split\", target: block, at: [byte…], expect? } | { op: \"merge\", targets: [block…], separator?, expect? } | { op: \"retarget\", repairs: [{ from, to }], path_glob? }. Target: a bare document path, a block/node id, $new.<n> (an identity an earlier effect creates), or { kind: \"document\", _id? | _path? } | { kind: \"block\", _id } | { kind: \"node\", _id } | { kind: \"section\", heading_id }. at: \"start\" | \"end\" | { before: <block id> } | { after: <block id> } — a place among the children of `into`, so \"right after block X\" is into: X's parent (its parent block id, or the document path when X is top-level), at: { after: X }. field: a block's is \"markdown\" or \"_attrs.checked\"; a document's \"_frontmatter.<key>\" or (set only) \"content\"; a node's an editable property (value, name, checked). expect on a single-target op: { content_hash?, parent_children_hash?, revision? }; on remove/merge targets it is keyed by block id: { <block id>: { content_hash?, parent_children_hash? } }. expect: { max } is the request's top-level argument beside select, never inside an effect.");
 // An example ladder (spec/surface §4 "Descriptions", 4.3): the description of
 // each `MINIMAL_TOOLS` tool is a one-line summary, then one example per line —
 // a rung is a line beginning `{` with the call's arguments as JSON, three
@@ -102,7 +102,7 @@ const ladder = (...lines) => lines.join("\n");
 // The `docs_read` ladder's time-travel rung (4.7): the revision id is the one
 // the spec minter gives `/processes/calcination.md`'s ingest revision over the
 // alchemy corpus (`examples.json` runs the rung before any write).
-const REVISION_RUNG = "{\"path\":\"/processes/calcination.md\",\"at\":\"r_7\"}   as of a revision (rev ids: from revisions where path == \"/processes/calcination.md\")";
+const REVISION_RUNG = "{\"_path\":\"/processes/calcination.md\",\"at\":\"r_7\"}   as of a revision (rev ids: revisions { _rev where _path == \"/processes/calcination.md\" })";
 function ok(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
@@ -128,6 +128,17 @@ export const WRITE_TOOLS = new Set([
     "docs_create", "docs_move", "docs_delete", "docs_set_meta", "docs_update",
     "observe", "observe_many", "observe_delete",
 ]);
+/**
+ * How many plans a server remembers for `execute { plan_id }` alone (spec/surface
+ * §4 `execute`, 5.1): the most recent `plan` results of this process, by
+ * `plan_id`, least recently produced evicted first. The same bound as the Rust
+ * catalog's `PLAN_MEMORY`.
+ */
+export const PLAN_MEMORY = 64;
+/** The message of `plan_unknown` (5.1), spelled alike by both engines. */
+export function planUnknownMessage(planId) {
+    return `this server has no plan ${planId} — re-run plan, or pass the plan (or \`plan_id\` + \`effects\`) with execute`;
+}
 export function buildServer(ctx) {
     const server = new McpServer({ name: "omgbase", version: VERSION });
     const { store } = ctx;
@@ -157,6 +168,25 @@ export function buildServer(ctx) {
     const profile = ctx.tools ?? "full";
     const inProfile = PROFILES[profile];
     const registry = new Map();
+    // The plans this server produced (spec/surface §4 `execute`, 5.1): `plan`'s
+    // results by `plan_id`, the last PLAN_MEMORY of them, so `execute { plan_id }`
+    // alone runs the FULL plan form — `stale_plan` and `plan_mismatch` told apart
+    // exactly as if the client had echoed the Plan — without the client replaying
+    // 5–19 kB of plan as its own output. Per process: a plan_id this server never
+    // produced (another server's, a restart) is `plan_unknown`, retriable.
+    const plans = new Map();
+    function rememberPlan(plan) {
+        plans.delete(plan.plan_id);
+        plans.set(plan.plan_id, plan);
+        while (plans.size > PLAN_MEMORY)
+            plans.delete(plans.keys().next().value);
+    }
+    function rememberedPlan(planId) {
+        const plan = plans.get(planId);
+        if (!plan)
+            throw new EngineError("plan_unknown", planUnknownMessage(planId), { data: { plan_id: planId }, retriable: true });
+        return plan;
+    }
     function tool(name, def, handler) {
         if (!inProfile(name))
             return;
@@ -205,7 +235,7 @@ export function buildServer(ctx) {
     const REPO_ARG = { repo: z.string().optional() };
     // The document locator every `docs_*` tool takes (§4 "Arguments"): the row's
     // own attributes, at least one of them.
-    const DOC_ARGS = { id: z.string().optional(), path: z.string().optional() };
+    const DOC_ARGS = { _id: z.string().optional(), _path: z.string().optional() };
     // Wrap a successful write's result: notify the host so it can schedule a
     // background embed drain. onMutation must be cheap/non-blocking (see
     // ServerContext); we never await it, keeping it off the response path.
@@ -214,15 +244,16 @@ export function buildServer(ctx) {
         return ok(payload);
     }
     // ---- the document locator (§4 "Arguments") ---------------------------------
-    // `id` is the document's id, `path` its path (either form, §1 "Paths"); at
+    // `_id` is the document's id, `_path` its path (either form, §1 "Paths"); at
     // least one is required, and when both are given they must name the same
-    // document. A miss is `doc_missing` "no document with id or path "<value>""
+    // document. A miss is `doc_missing` "no document with _id or _path "<value>""
     // with the arguments as given in `data`;
-    // neither given is `filter_invalid` "pass id or path"; a disagreement is
-    // `filter_invalid` "id "…" and path "…" name different documents". `findDoc`
-    // never falls through from an id to a path.
+    // neither given is `filter_invalid` "pass _id or _path"; a disagreement is
+    // `filter_invalid` "_id "…" and _path "…" name different documents". `findDoc`
+    // never falls through from an id to a path. A bare `id`/`path` never reaches
+    // here: `validateArguments` refuses it with the `_` spelling and a `fix` (5.0).
     function locateDoc(repoId, toolName, shape, args) {
-        const [idKey, pathKey] = ["id", "path"];
+        const [idKey, pathKey] = ["_id", "_path"];
         const id = args[idKey];
         const path = args[pathKey];
         if (id === undefined && path === undefined)
@@ -257,7 +288,7 @@ export function buildServer(ctx) {
         return row.doc_id;
     }
     function blockMissing(value, hint) {
-        return new EngineError("block_missing", `no block with id ${JSON.stringify(value)}${hint ? ` (${hint})` : ""}`, { data: { id: value } });
+        return new EngineError("block_missing", `no block with id ${JSON.stringify(value)}${hint ? ` (${hint})` : ""}`, { data: { _id: value } });
     }
     // `nodes_block_read`: the block a node was projected from — the node must
     // exist and name a live block (a block-less node, e.g. one derived from the
@@ -266,10 +297,10 @@ export function buildServer(ctx) {
     function blockOfNode(nodeId) {
         const node = store.db.prepare("SELECT doc_id, block_id FROM nodes WHERE node_id = ?").get(nodeId);
         if (!node)
-            throw new EngineError("block_missing", `no node with id ${JSON.stringify(nodeId)}`, { data: { id: nodeId } });
+            throw new EngineError("block_missing", `no node with id ${JSON.stringify(nodeId)}`, { data: { _id: nodeId } });
         const live = node.block_id ? store.db.prepare("SELECT 1 FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(node.block_id) : undefined;
         if (!node.block_id || !live)
-            throw new EngineError("block_missing", `node ${JSON.stringify(nodeId)} has no block`, { data: { id: nodeId, doc_id: node.doc_id } });
+            throw new EngineError("block_missing", `node ${JSON.stringify(nodeId)} has no block`, { data: { _id: nodeId, _doc_id: node.doc_id } });
         return { docId: node.doc_id, blockId: node.block_id };
     }
     // `docs_append`'s `section`: a heading's TEXT, matched against the normalized
@@ -294,13 +325,13 @@ export function buildServer(ctx) {
             const fold = (t) => t.replace(/[A-Z]/g, (c) => c.toLowerCase());
             const near = rows.filter((r) => fold(normalizeText(r.text)) === fold(needle));
             const fix = near.length === 1
-                ? fixTool("blocks_append", { id: near[0].block_id, text: call.text })
-                : fixTool("docs_append", { ...(call.id !== undefined ? { id: call.id } : {}), ...(call.path !== undefined ? { path: call.path } : {}), text: call.text });
-            throw new EngineError("parent_missing", `no heading ${JSON.stringify(section)} in ${shown}`, { data: { section, path: shown, fix } });
+                ? fixTool("blocks_append", { _id: near[0].block_id, text: call.text })
+                : fixTool("docs_append", { ...(call._id !== undefined ? { _id: call._id } : {}), ...(call._path !== undefined ? { _path: call._path } : {}), text: call.text });
+            throw new EngineError("parent_missing", `no heading ${JSON.stringify(section)} in ${shown}`, { data: { section, _path: shown, fix } });
         }
         if (matches.length > 1) {
             throw new EngineError("ambiguous_heading", `heading ${JSON.stringify(section)} matches ${matches.length} headings in ${shown}; pass the heading's id to blocks_append`, {
-                data: { section, path: shown, candidates: matches.map((m) => ({ id: m.block_id, doc_id: m.doc_id })), fix: fixTool("blocks_append", { id: matches[0].block_id, text: call.text }) },
+                data: { section, _path: shown, candidates: matches.map((m) => ({ _id: m.block_id, _doc_id: m.doc_id })), fix: fixTool("blocks_append", { _id: matches[0].block_id, text: call.text }) },
             });
         }
         return matches[0].block_id;
@@ -356,9 +387,9 @@ export function buildServer(ctx) {
     function sugar(repoId, rootPath, built) {
         return okMutated(surfaceReceipt(runSugar(repoId, rootPath, built).receipt));
     }
-    const blockTarget = (id) => ({ kind: "block", id });
+    const blockTarget = (id) => ({ kind: "block", _id: id });
     // A parent ref as an effect target: a document ref is the document's top level, a block ref the block.
-    const parentTarget = (p) => typeof p.parent === "object" ? { kind: "document", id: p.docId } : { kind: "block", id: p.parent };
+    const parentTarget = (p) => typeof p.parent === "object" ? { kind: "document", _id: p.docId } : { kind: "block", _id: p.parent };
     // An empty block list is an argument error (3.2, §9) — it used to reach the
     // kernel as a malformed op (`block_missing "block undefined not found"`).
     function requireSome(tool, arg, list) {
@@ -404,7 +435,7 @@ export function buildServer(ctx) {
         };
     }
     tool("docs_outline", {
-        description: "Orientation call. Returns a document's compact indented outline (alias/type/label per line, § marks section headings). IDs are stable; prefer them in follow-ups. Address the document by `id` or `path` (at least one; a `path` in either form). For the whole document body in one call, use docs_read.",
+        description: "Orientation call. Returns a document's compact indented outline (alias/type/label per line, § marks section headings). IDs are stable; prefer them in follow-ups. Address the document by `_id` or `_path` (at least one; a `_path` in either form). For the whole document body in one call, use docs_read.",
         inputSchema: {
             ...DOC_ARGS,
             resolution: z.enum(["skeleton", "outline"]).optional(),
@@ -428,7 +459,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_read", {
-        description: ladder("docs_read — One document, whole: raw bytes plus properties { frontmatter, inline, computed } and id/path/rev.", "{\"path\":\"/processes/calcination.md\"}   by path (either form)", "{\"path\":\"/processes/calcination.md\",\"include_ids\":true}   plus ids (pre-order), hashes (the CAS tokens expect.content_hash takes), parents (null = top level)", "{\"id\":\"d_14\"}   by id (a query hit's id)", REVISION_RUNG, "Structure only: query md:section nodes. Many documents: a query with select raw. Grammar: query_syntax."),
+        description: ladder("docs_read — One document, whole: _raw bytes plus properties { frontmatter, inline, computed } and _id/_path/rev.", "{\"_path\":\"/processes/calcination.md\"}   by _path (either form)", "{\"_path\":\"/processes/calcination.md\",\"include_ids\":true}   plus ids (pre-order), hashes (the CAS tokens expect.content_hash takes), parents (null = top level)", "{\"_id\":\"d_14\"}   by _id (a query hit's _id)", REVISION_RUNG, "Structure only: query md:section nodes. Many documents: a query with select _raw. Grammar: query_syntax."),
         inputSchema: {
             ...DOC_ARGS,
             include_ids: z.boolean().optional(),
@@ -450,7 +481,7 @@ export function buildServer(ctx) {
             }
             const res = docsRead(store, docId, args.include_ids ? { includeIds: true } : {});
             if (!res)
-                throw new EngineError("doc_missing", `no document with id or path ${JSON.stringify(args.id ?? args.path)}`, { data: { id: docId } });
+                throw new EngineError("doc_missing", `no document with id or path ${JSON.stringify(args._id ?? args._path)}`, { data: { _id: docId } });
             return ok(res);
         }
         catch (e) {
@@ -458,7 +489,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_read_many", {
-        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a document id OR a path, in either form), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`raw` = complete file bytes verbatim, `properties` grouped by source, plus `id`/`path`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block `id` → block `hash`} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it; the FIRST doc always ships even when it alone exceeds the budget (the same at-least-one-row contract as docs_list/docs_tree, so a budgeted caller always makes progress). Use this after query/blocks_search/blocks_resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline (docs_get_many before surface 3.0).",
+        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a document id OR a path, in either form), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`_raw` = complete file bytes verbatim, `properties` grouped by source, plus `_id`/`_path`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block `_id` → block `_hash`} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it; the FIRST doc always ships even when it alone exceeds the budget (the same at-least-one-row contract as docs_list/docs_tree, so a budgeted caller always makes progress). Use this after query/blocks_search/blocks_resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline (docs_get_many before surface 3.0).",
         inputSchema: {
             docs: stringList(),
             include_ids: z.boolean().optional(),
@@ -479,9 +510,9 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_read", {
-        description: "Hydrate one block subtree at a resolution (skeleton|outline|text|raw|full). `id` is the block's id (`b_…`) and its document is inferred from it; an `n_` node id is not a block id — nodes_block_read reads the block a node was projected from (nodes_get before surface 3.0: blocks used to be called nodes here, and `nodes` now names the extracted-entity rows). Every resolution carries the block's `id` and `type`; raw and full add `raw` (its source bytes) and `hash` (its own raw hash) — the value update/split need in expect.content_hash, so you can fetch it before editing rather than reading it back from a conflict; full adds `text`, `attrs`, `ordinal`, `depth` and `parent_id` (null at the top level). Use this to expand the lean ids returned by query/blocks_resolve. To read a whole document in one call, use docs_read (blocks_read on a heading's id returns only that block, not its section).",
+        description: "Hydrate one block subtree at a resolution (skeleton|outline|text|raw|full). `_id` is the block's id (`b_…`) and its document is inferred from it; an `n_` node id is not a block id — nodes_block_read reads the block a node was projected from (nodes_get before surface 3.0: blocks used to be called nodes here, and `nodes` now names the extracted-entity rows). Every resolution carries the block's `_id` and `_type`; raw and full add `_raw` (its source bytes) and `_hash` (its own raw hash) — the value update/split need in expect.content_hash, so you can fetch it before editing rather than reading it back from a conflict; full adds `_text`, `_attrs`, `_ordinal`, `_depth` and `parent_id` (null at the top level). Use this to expand the lean ids returned by query/blocks_resolve. To read a whole document in one call, use docs_read (blocks_read on a heading's id returns only that block, not its section).",
         inputSchema: {
-            id: z.string(),
+            _id: z.string(),
             resolution: z.enum(["skeleton", "outline", "text", "raw", "full"]).optional(),
             ...REPO_ARG,
         },
@@ -491,11 +522,11 @@ export function buildServer(ctx) {
             // `id` is a block id, unambiguously the `blocks_` kind's (§4 "Names and
             // arguments"): an `n_` id names a NODE and is `block_missing` pointing at
             // `nodes_block_read` (the name pass had dereferenced it here, §9).
-            if (args.id.startsWith("n_"))
-                throw blockMissing(args.id, "an n_ id names a node — nodes_block_read reads its block");
-            const node = nodesGet(store, docOfBlock(args.id), args.id, args.resolution ? { resolution: args.resolution } : {});
+            if (args._id.startsWith("n_"))
+                throw blockMissing(args._id, "an n_ id names a node — nodes_block_read reads its block");
+            const node = nodesGet(store, docOfBlock(args._id), args._id, args.resolution ? { resolution: args.resolution } : {});
             if (!node)
-                throw blockMissing(args.id);
+                throw blockMissing(args._id);
             return ok(node);
         }
         catch (e) {
@@ -503,19 +534,19 @@ export function buildServer(ctx) {
         }
     });
     tool("nodes_block_read", {
-        description: "Read the block a NODE was projected from: `id` is the node's id (`n_…`, from `query` over `from nodes`) and the result is exactly what blocks_read returns for that block — the same resolutions (skeleton|outline|text|raw|full, default full), the same `id`/`type`/`raw`/`hash`/`text`/`attrs`/`ordinal`/`depth`/`parent_id`. The hop from an occurrence (an `md:link`, `md:task`, `md:section`, … node) to the editable block that holds it, in one call; blocks_read itself takes a block id only. An unknown node, or a node that names no live block (a block-less node, such as one derived from the frontmatter), is block_missing.",
+        description: "Read the block a NODE was projected from: `_id` is the node's id (`n_…`, from `query` over `nodes { … }`) and the result is exactly what blocks_read returns for that block — the same resolutions (skeleton|outline|text|raw|full, default full), the same `_id`/`_type`/`_raw`/`_hash`/`_text`/`_attrs`/`_ordinal`/`_depth`/`parent_id`. The hop from an occurrence (an `md:link`, `md:task`, `md:section`, … node) to the editable block that holds it, in one call; blocks_read itself takes a block id only. An unknown node, or a node that names no live block (a block-less node, such as one derived from the frontmatter), is block_missing.",
         inputSchema: {
-            id: z.string(),
+            _id: z.string(),
             resolution: z.enum(["skeleton", "outline", "text", "raw", "full"]).optional(),
             ...REPO_ARG,
         },
     }, async (args) => {
         try {
             repoScope(args.repo);
-            const { docId, blockId } = blockOfNode(args.id);
+            const { docId, blockId } = blockOfNode(args._id);
             const node = nodesGet(store, docId, blockId, args.resolution ? { resolution: args.resolution } : {});
             if (!node)
-                throw new EngineError("block_missing", `node ${JSON.stringify(args.id)} has no block`, { data: { id: args.id, doc_id: docId } });
+                throw new EngineError("block_missing", `node ${JSON.stringify(args._id)} has no block`, { data: { _id: args._id, _doc_id: docId } });
             return ok(node);
         }
         catch (e) {
@@ -523,9 +554,9 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_read_many", {
-        description: "Fetch up to 100 blocks by id (in request order) with budget truncation — the plural of blocks_read (nodes_get_many before surface 3.0). Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side. Result carries `nodes` (the hydrated blocks, one per resolved id), `truncated` (cap or `budget_tokens` hit — the first resolved block always ships even when it alone exceeds the budget, so a budgeted caller always makes progress), and `unresolved` — the requested ids that name no live block (never silently dropped).",
+        description: "Fetch up to 100 blocks by id (in request order) with budget truncation — the plural of blocks_read (nodes_get_many before surface 3.0). Block ids are globally unique, so `_ids` may span ANY number of documents — each id is resolved to its owning doc server-side. Result carries `nodes` (the hydrated blocks, one per resolved id), `truncated` (cap or `budget_tokens` hit — the first resolved block always ships even when it alone exceeds the budget, so a budgeted caller always makes progress), and `unresolved` — the requested ids that name no live block (never silently dropped).",
         inputSchema: {
-            ids: stringList(),
+            _ids: stringList(),
             resolution: z.enum(["skeleton", "outline", "text", "raw", "full"]).optional(),
             budget_tokens: z.number().int().optional(),
             ...REPO_ARG,
@@ -533,7 +564,7 @@ export function buildServer(ctx) {
     }, async (args) => {
         try {
             repoScope(args.repo);
-            const res = nodesGetMany(store, null, args.ids, {
+            const res = nodesGetMany(store, null, args._ids, {
                 ...(args.resolution ? { resolution: args.resolution } : {}),
                 ...(args.budget_tokens !== undefined ? { budgetTokens: args.budget_tokens } : {}),
             });
@@ -544,10 +575,12 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_tree", {
-        description: ladder("docs_tree — Orientation: the shape of a repo in one small call, like tree -L depth with document and block counts per entry.", "{}   the root at depth 1: one entry per directory (path ends in /) or shallow document, plus total", "{\"path\":\"/processes/\",\"depth\":1}   descend into a directory entry", "{\"depth\":2,\"limit\":5}   collapse deeper; limit/cursor page the entries, total always covers everything under path", "Ranked or attribute-based discovery: blocks_resolve, or query (select path from docs where ...). Grammar: query_syntax."),
+        description: ladder("docs_tree — Orientation: the repo's directories with document and block counts, one small page (tree -L depth -d + du).", "{}   the root: one row per directory ({ _path ending in /, docs, blocks }), files_here = documents at the root itself, total", "{\"path\":\"/processes/\",\"files\":true}   descend (path is the prefix) and list its documents too ({ _id, _path, blocks })", "{\"depth\":2,\"updated\":true}   nested directories to depth 2; updated adds _updated_at; limit/cursor page the rows", "Find documents by attribute, not by path: query (docs { select _path where ... }). Grammar: query_syntax."),
         inputSchema: {
             path: z.string().optional(),
             depth: z.number().int().optional(),
+            files: z.boolean().optional(),
+            updated: z.boolean().optional(),
             limit: z.number().int().optional(),
             cursor: z.string().nullable().optional(),
             budget_tokens: z.number().int().optional(),
@@ -559,6 +592,8 @@ export function buildServer(ctx) {
             return ok(docsTree(store, repoId, {
                 ...(args.path !== undefined ? { path: args.path } : {}),
                 ...(args.depth !== undefined ? { depth: args.depth } : {}),
+                ...(args.files !== undefined ? { files: args.files } : {}),
+                ...(args.updated !== undefined ? { updated: args.updated } : {}),
                 ...(args.limit !== undefined ? { limit: args.limit } : {}),
                 ...(args.cursor !== undefined ? { cursor: args.cursor } : {}),
                 ...(args.budget_tokens !== undefined ? { budgetTokens: args.budget_tokens } : {}),
@@ -569,7 +604,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_list", {
-        description: "ENUMERATE live documents (the `omg ls` operation) as a page: `{ items: [{ id, path, updated_at, blocks }], truncated, cursor }` — the document's id, its path (`/`-rooted, as every path the surface returns), last-commit timestamp (ISO, or null) and live block count — ordered by path. This is a flat `ls`, not an orientation primitive: unscoped on a large repo it is hundreds of rows, and the engine has no directory concept here — `path_glob` is a simple LIKE match where `*` matches ANY run INCLUDING `/` (so `projects/*` is the whole subtree; there is no 'immediate children only'). To learn a repo's shape, call docs_tree first, then scope this with a `path_glob` once you know where to look. Paged under the uniform list contract: `limit` (default " + DOCS_LIST_DEFAULT_LIMIT + ") caps rows, `cursor` (from a truncated page) resumes after the last row returned, `budget_tokens` caps the page's estimated size (at least one row is always returned), and `truncated` is honest — when true you have NOT seen everything. For structured/ranked discovery use `query` or `blocks_resolve`.",
+        description: "ENUMERATE live documents (the `omg ls` operation) as a page: `{ items: [{ _id, _path, _updated_at, blocks }], truncated, cursor }` — the document's `_id`, its `_path` (`/`-rooted, as every path the surface returns), last-commit timestamp (ISO, or null) and live block count — ordered by path. This is a flat `ls`, not an orientation primitive: unscoped on a large repo it is hundreds of rows, and the engine has no directory concept here — `path_glob` is a simple LIKE match where `*` matches ANY run INCLUDING `/` (so `projects/*` is the whole subtree; there is no 'immediate children only'). To learn a repo's shape, call docs_tree first, then scope this with a `path_glob` once you know where to look. Paged under the uniform list contract: `limit` (default " + DOCS_LIST_DEFAULT_LIMIT + ") caps rows, `cursor` (from a truncated page) resumes after the last row returned, `budget_tokens` caps the page's estimated size (at least one row is always returned), and `truncated` is honest — when true you have NOT seen everything. For structured/ranked discovery use `query` or `blocks_resolve`.",
         inputSchema: {
             path_glob: z.string().optional(),
             limit: z.number().int().optional(),
@@ -592,11 +627,28 @@ export function buildServer(ctx) {
         }
     });
     tool("query_syntax", {
-        description: ladder("query_syntax — The full OQX reference: clause order, targets and fields, scalar semantics, nested queries and the root row, follow, paging, worked examples.", "{}   no arguments; returns { syntax }", "Call it before writing a non-trivial query; every other tool's examples end here, at query_syntax."),
-        inputSchema: {},
-    }, async () => ok({ syntax: QUERY_SYNTAX }));
+        description: ladder("query_syntax — The OQX reference: a card (clause order, the names rule and engine names per kind, consumers, follow, examples), then one chapter at a time.", "{}   the ~3 kB card: { syntax, sections } — enough for most queries", "{\"section\":\"follow\"}   one chapter in full ({ section, syntax }); the names are the card's sections list", "{\"section\":\"all\"}   the whole manual (38 kB) — rarely needed", "Call the card before a non-trivial query; every other tool's examples end here, at query_syntax."),
+        inputSchema: { section: z.string().optional() },
+    }, async (args) => {
+        try {
+            // (5.1) The card by default; a chapter by its slug; `all` the manual. An
+            // unknown name is an argument error naming the chapters, its `fix` the
+            // call respelled with the nearest name (or `all`).
+            if (args.section === undefined)
+                return ok({ syntax: QUERY_SYNTAX_CARD, sections: QUERY_SYNTAX_SECTIONS.map((s) => s.slug) });
+            const syntax = querySyntaxSection(args.section);
+            if (syntax === null) {
+                const fix = canonicalJson({ section: nearest(args.section, QUERY_SYNTAX_SECTION_NAMES) ?? "all" });
+                throw argumentError("query_syntax", `unknown section \`${args.section}\`; the sections are ${QUERY_SYNTAX_SECTION_NAMES.join(", ")}`, registry.get("query_syntax").shape, fix);
+            }
+            return ok({ section: args.section, syntax });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     tool("query", {
-        description: ladder("query — rows (id, path, projection) from docs, blocks, nodes or links.", "{\"query\":\"select title, stage from docs where \\\"process\\\" in tags order by path limit 5\"}   frontmatter; membership; order, limit", "{\"query\":\"select type, text from blocks where path == \\\"/processes/calcination.md\\\"\"}   a document's blocks in order", "{\"query\":\"select block_id from nodes where kind == \\\"md:section\\\" and name == \\\"Tasks\\\" and path == \\\"/processes/calcination.md\\\"\"}   a heading's block id", "{\"query\":\"select path, value from nodes where kind == \\\"md:task\\\" and not checked\"}   open tasks", "{\"query\":\"select path, block_id from links where dst_path == \\\"/processes/calcination.md\\\"\"}   inbound links (path = source)", "{\"query\":\"select path from docs where title ~* \\\"salt\\\"\"}   regex (~* ci, !~ not); substring: .contains(\\\"s\\\")", "Also docs count { where … }, follow, ^docs joins, text()/semantic(): query_syntax."),
+        description: ladder("query — rows (_id, _path, projection) from docs, blocks, nodes or links.", "{\"query\":\"docs { select _title, stage where \\\"process\\\" in tags order by _path limit 5 }\"}   frontmatter; in; order, limit", "{\"query\":\"blocks { select _type, _text where _path == \\\"/processes/calcination.md\\\" }\"}   a document's blocks in order", "{\"query\":\"nodes { select _block_id where _kind == \\\"md:section\\\" and _name == \\\"Tasks\\\" and _path == \\\"/processes/calcination.md\\\" }\"}   a heading's block id", "{\"query\":\"nodes { select _path, _value where _kind == \\\"md:task\\\" and not checked }\"}   open tasks", "{\"query\":\"links { select _path, _block_id where _dst_path == \\\"/processes/calcination.md\\\" }\"}   inbound links (_path = source)", "{\"query\":\"docs { select _path where _title ~* \\\"salt\\\" }\"}   regex (~* ci, !~ not); substring: .contains(\\\"s\\\")", "Also docs count { where … }, follow, ^docs joins, text()/semantic(): query_syntax."),
         inputSchema: {
             query: z.string(),
             limit: z.number().int().optional(),
@@ -624,7 +676,7 @@ export function buildServer(ctx) {
         }
     });
     tool("graph", {
-        description: "Neighborhood macro: the bounded graph AROUND one or more root documents in ONE call — { documents, links, frontier } — so you can orient without hand-writing an OQX `follow`. This is a CONVENIENCE WRAPPER, not a new engine: it compiles its args into an OQX `follow out_links collect { from dst }` / `follow in_links collect { from doc }` query and runs it through the same `query` path (the returned `queries` field is the exact follow query it generated). It does NOT replace `follow` or `from links` — reach for the `query` tool directly when you need successor/frontier predicates, `$key`-keyed identity, `$ordinal` budgets, cross-document correlation, or the links scan with its own projections. `roots` are one or more doc refs (paths and/or ids); they are depth 0. `degrees` is the max hop distance (root = 0; maps to `follow … collect { … depth degrees+1 }`, capped so degrees+1 ≤ 8; default 1). `direction` is `out` (outgoing links), `in` (backlinks), or `both` (default). `predicate` restricts the neighborhood to documents reachable from a root via edges of that predicate (both the documents and the edges are filtered). `select` adds document projections (OQX select expressions, e.g. \"layer\", \"path\"). `max_documents` caps the distinct document set (default 200) with a `truncated` flag. Returns: `documents` (each with `id`/`path`/`degree` = min hops from a root/`frontier` bool + your projections — a bare-name selection such as \"title\" is its own key, `id`/`path` land on the envelope keys, and any other expression is `sel_<i>`), `links` (the traversed links as rows of the `links` target under its own field names — `id`, `doc_id`/`block_id` (the source), `via_id`, `dst_id`, `dst_path`, `uri`, `dst_kind`, `predicate`, `provenance`, `anchor`, `field`; external `x_…` and dangling phantom endpoints are preserved as edge stubs, exactly as `from links` surfaces them), and `frontier` (the documents on the outer boundary — `{ id, path, degree }`, min degree == degrees; at degrees 0 that is the roots themselves).",
+        description: "Neighborhood macro: the bounded graph AROUND one or more root documents in ONE call — { documents, links, frontier } — so you can orient without hand-writing an OQX `follow`. This is a CONVENIENCE WRAPPER, not a new engine: it compiles its args into an OQX `follow _out_links { from _dst }` / `follow _in_links { from _doc }` query and runs it through the same `query` path (the returned `queries` field is the exact follow query it generated). It does NOT replace `follow` or `from links` — reach for the `query` tool directly when you need successor/frontier predicates, `$key`-keyed identity, `$ordinal` budgets, cross-document correlation, or the links scan with its own projections. `roots` are one or more doc refs (paths and/or ids); they are depth 0. `degrees` is the max hop distance (root = 0; maps to `follow … collect { … depth degrees+1 }`, capped so degrees+1 ≤ 8; default 1). `direction` is `out` (outgoing links), `in` (backlinks), or `both` (default). `predicate` restricts the neighborhood to documents reachable from a root via edges of that predicate (both the documents and the edges are filtered). `select` adds document projections (OQX select expressions, e.g. \"layer\", \"_title\"). `max_documents` caps the distinct document set (default 200) with a `truncated` flag. Returns: `documents` (each with `_id`/`_path`/`degree` = min hops from a root/`frontier` bool + your projections — a name selection such as \"layer\" or \"_title\" is its own key, `_id`/`_path` land on the envelope keys, and any other expression is `sel_<i>`), `links` (the traversed links as rows of the `links` target under its own field names — `_id`, `_doc_id`/`_block_id` (the source), `_via_id`, `_dst_id`, `_dst_path`, `_uri`, `_dst_kind`, `_predicate`, `_provenance`, `_anchor`, `_field`; external `x_…` and dangling phantom endpoints are preserved as edge stubs, exactly as `from links` surfaces them), and `frontier` (the documents on the outer boundary — `{ _id, _path, degree }`, min degree == degrees; at degrees 0 that is the roots themselves).",
         inputSchema: {
             roots: stringList({ min: 1 }),
             degrees: z.number().int().optional(),
@@ -639,7 +691,7 @@ export function buildServer(ctx) {
             const { repoId } = repoScope(args.repo);
             // A `select` using semantic(...) needs a provider — surface the specific
             // code, mirroring the `query` tool.
-            if (!ctx.embedQuery && (args.select ?? []).some((s) => collectSemanticPhrases(`from docs select x: ${s}`).length > 0))
+            if (!ctx.embedQuery && (args.select ?? []).some((s) => collectSemanticPhrases(`docs { select x: ${s} }`).length > 0))
                 throw providerUnavailable();
             return ok(await graphNeighborhood(store, repoId, args, rankableEmbed(repoId)));
         }
@@ -648,7 +700,7 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_search", {
-        description: "Full-text (FTS5, bm25-ranked) keyword search over block text: `{ hits: [{ id (the block), doc_id, path, type, text, score }], truncated }`. Input is treated as a search box — plain words are ANDed, \"quoted phrases\" match adjacency, punctuation like / is safe (no query DSL). For structured filtering or frontmatter projection use `query` instead (see query_syntax). (text_search before surface 3.0.)",
+        description: "Full-text (FTS5, bm25-ranked) keyword search over block text: `{ hits: [{ _id (the block), _doc_id, _path, _type, _text, score }], truncated }`. Input is treated as a search box — plain words are ANDed, \"quoted phrases\" match adjacency, punctuation like / is safe (no query DSL). For structured filtering or frontmatter projection use `query` instead (see query_syntax). (text_search before surface 3.0.)",
         inputSchema: { q: z.string(), limit: z.number().int().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -660,7 +712,7 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_resolve", {
-        description: ladder("blocks_resolve — \"the id of the thing I mean\": a title or term, ranked to blocks { id, locator, preview, evidence }.", "{\"query\":\"calcination\"}   best on short, entity-shaped input", "{\"query\":\"Emerald Tablet\",\"limit\":3}   use the returned id in the next call (docs_read, a plan target)", "Open questions or passages: query with text(\"...\") or order by semantic(\"...\") desc. Grammar: query_syntax."),
+        description: ladder("blocks_resolve — \"the id of the thing I mean\": a title or term, ranked to blocks { _id, locator, preview, evidence }.", "{\"query\":\"calcination\"}   best on short, entity-shaped input", "{\"query\":\"Emerald Tablet\",\"limit\":3}   use the returned _id in the next call (docs_read, a plan target)", "Open questions or passages: query with text(\"...\") or order by semantic(\"...\") desc. Grammar: query_syntax."),
         inputSchema: { query: z.string(), limit: z.number().int().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -677,7 +729,7 @@ export function buildServer(ctx) {
         }
     });
     tool("apply", {
-        description: ladder("apply — plan and commit in one call; returns the Receipt { plan_id, commit, revisions, new_ids, committed, summary }.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/substances/salt.md\",\"field\":\"frontmatter.verified\",\"value\":false}],\"reason\":\"re-check salt\"}   one scalar; a bare path is a document target", "{\"effects\":[{\"op\":\"insert\",\"into\":\"/lab/2026-02-notes.md\",\"at\":\"end\",\"markdown\":\"## Follow-ups\\n\\n- [ ] re-run cycle 4\"}]}   append at a document's end", "{\"select\":\"from blocks where type == \\\"task\\\" and not checked and path == \\\"/processes/calcination.md\\\"\",\"effects\":[{\"op\":\"set\",\"field\":\"attrs.checked\",\"value\":true}],\"expect\":{\"max\":10}}   bulk check-off; expect.max is REQUIRED with select", "Plan first for anything you cannot undo by hand; every error's data.fix is a corrected call to copy. Grammar: query_syntax."),
+        description: ladder("apply — plan and commit in one call; returns the Receipt { plan_id, commit, revisions, new_ids, committed, summary }.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/substances/salt.md\",\"field\":\"_frontmatter.verified\",\"value\":false}],\"reason\":\"re-check salt\"}   one scalar; a bare path is a document target", "{\"effects\":[{\"op\":\"insert\",\"into\":\"/lab/2026-02-notes.md\",\"at\":\"end\",\"markdown\":\"## Follow-ups\\n\\n- [ ] re-run cycle 4\"}]}   append at a document's end", "{\"select\":\"blocks { _type == \\\"task\\\" and not checked and _path == \\\"/processes/calcination.md\\\" }\",\"effects\":[{\"op\":\"set\",\"field\":\"_attrs.checked\",\"value\":true}],\"expect\":{\"max\":10}}   bulk check-off; expect.max is REQUIRED with select", "Plan first for anything you cannot undo by hand; every error's data.fix is a corrected call to copy. Grammar: query_syntax."),
         inputSchema: {
             effects: z.array(effectSchema),
             select: z.string().optional(),
@@ -703,14 +755,18 @@ export function buildServer(ctx) {
     // commits exactly a plan (the plan form, or the digest form `plan_id` +
     // `effects`); `apply { effects }` above is plan + execute in one call.
     tool("plan", {
-        description: ladder("plan — Preview a write: the Plan (summary, $new.n ids) burns no id; execute next. Need file bodies? add diffs: true.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/processes/calcination.md\",\"field\":\"frontmatter.verified\",\"value\":false}]}   path = doc", "{\"effects\":[{\"op\":\"insert\",\"into\":{\"kind\":\"section\",\"heading_id\":\"b_153\"},\"markdown\":\"- [ ] Weigh the calx\"}]}   in a section", "{\"effects\":[{\"op\":\"create\",\"path\":\"lab/march.md\",\"markdown\":\"# March\\n\"},{\"op\":\"insert\",\"into\":\"$new.0\",\"markdown\":\"Hi.\"}]}   fill it: $new.0", "{\"select\":\"from docs where stage == \\\"nigredo\\\"\",\"effects\":[{\"op\":\"set\",\"field\":\"frontmatter.ok\",\"value\":true}]}   no target: the hit", "{\"select\":\"from docs where type == \\\"lab-note\\\"\",\"effects\":[{\"op\":\"insert\",\"into\":\"-> `/processes/${subject}.md`\",\"markdown\":\"-> `[${title}](${path})`\"}]}   -> reads the row", "Ops: create insert set unset move remove split merge retarget; grammar: query_syntax."),
+        description: ladder("plan — Preview: the Plan (summary, $new.n ids) burns no id. Commit: execute { plan_id }. Bodies: diffs: true.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/processes/calcination.md\",\"field\":\"_frontmatter.verified\",\"value\":false}]}   path = doc", "{\"effects\":[{\"op\":\"insert\",\"into\":{\"kind\":\"section\",\"heading_id\":\"b_153\"},\"markdown\":\"- [ ] Weigh the calx\"}]}   in a section", "{\"effects\":[{\"op\":\"create\",\"path\":\"lab/march.md\",\"markdown\":\"# March\\n\"},{\"op\":\"insert\",\"into\":\"$new.0\",\"markdown\":\"Hi.\"}]}   fill it: $new.0", "{\"select\":\"docs { stage == \\\"nigredo\\\" }\",\"effects\":[{\"op\":\"set\",\"field\":\"_frontmatter.ok\",\"value\":true}]}   no target: the hit", "{\"select\":\"docs { type == \\\"lab-note\\\" }\",\"effects\":[{\"op\":\"insert\",\"into\":\"-> `/processes/${subject}.md`\",\"markdown\":\"-> `[${_title}](${_path})`\"}]}   -> reads the row", "Ops: create insert set unset move remove split merge retarget; grammar: query_syntax."),
         inputSchema: { effects: z.array(effectSchema), select: z.string().optional(), expect: selectionExpectSchema.optional(), diffs: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             if (!rootPath)
                 throw new EngineError("repo_not_found", "repo has no filesystem source; mutation disabled");
-            const plan = surfacePlan(planEffects(store, { repoId, rootPath, effects: args.effects, ...selectorArgs(args), ...LOCK_DIR }));
+            const planned = planEffects(store, { repoId, rootPath, effects: args.effects, ...selectorArgs(args), ...LOCK_DIR });
+            // (5.1) remembered for `execute { plan_id }` alone — the Plan as planned,
+            // preview included (its `summary` is the Receipt's).
+            rememberPlan(planned);
+            const plan = surfacePlan(planned);
             // (4.5) `preview.diffs` — whole before/after bodies of every touched
             // document — only on request: `diffs: true`. The digest is over the
             // core, never the preview, so `plan_id` is the same either way.
@@ -724,7 +780,7 @@ export function buildServer(ctx) {
         }
     });
     tool("execute", {
-        description: ladder("execute — Commit exactly a plan from plan: the plan form (the whole Plan object) or the digest form (plan_id plus the same effects, re-planned and committed only if the digest still matches).", "{\"plan_id\":\"ab416d8686fe527fd13439fcf0c7accb9e23307c0730edc17149c8b46f0f032a\",\"effects\":[{\"op\":\"set\",\"target\":\"/processes/calcination.md\",\"field\":\"frontmatter.verified\",\"value\":false}]}   digest form: the plan_id plan returned for these effects", "Or pass the whole object: {\"plan\": the Plan as returned}. A document that moved on fails stale_plan (retriable: call plan again). Grammar: query_syntax."),
+        description: ladder("execute — Commit a plan from plan: by plan_id alone (this server remembers the plans it made), or the plan form (the whole Plan object), or the digest form (plan_id plus the same effects, re-planned and committed only if the digest still matches).", "{\"plan_id\":\"4cebb67faba4347b922151762478e60ddf56115a955489e222bee3c6bb2c7e7f\"}   the id alone: the remembered plan runs; an id this server never planned is plan_unknown (re-run plan)", "Or {\"plan\": the Plan as returned} or {\"plan_id\", \"effects\"}. A document that moved on fails stale_plan (retriable: call plan again). Grammar: query_syntax."),
         inputSchema: { plan: z.record(z.string(), z.unknown()).optional(), plan_id: z.string().optional(), effects: z.array(effectSchema).optional(), select: z.string().optional(), expect: selectionExpectSchema.optional(), reason: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -732,17 +788,23 @@ export function buildServer(ctx) {
             if (!rootPath)
                 throw new EngineError("repo_not_found", "repo has no filesystem source; mutation disabled");
             const shape = registry.get("execute").shape;
+            // Three forms (spec/surface §4 `execute`): the plan form, the id alone
+            // (5.1: the plan this server remembers under it, run as the plan form),
+            // and the digest form (`plan_id` + `effects`, with `select`/`expect`).
             const planForm = args.plan !== undefined;
             const selector = args.select !== undefined || args.expect !== undefined;
-            const digestForm = args.plan_id !== undefined || args.effects !== undefined || selector;
-            if (planForm === digestForm)
-                throw argumentError("execute", "pass exactly one of `plan` or `plan_id` + `effects`", shape);
+            const idForm = args.plan_id !== undefined && args.effects === undefined && !selector;
+            const digestForm = !idForm && (args.plan_id !== undefined || args.effects !== undefined || selector);
+            if (planForm === (idForm || digestForm))
+                throw argumentError("execute", "pass exactly one of `plan`, `plan_id` or `plan_id` + `effects`", shape);
             if (digestForm && (args.plan_id === undefined || args.effects === undefined))
                 throw argumentError("execute", "the digest form needs both `plan_id` and `effects`", shape);
             const origin = { actor: "agent:mcp", ...(args.reason ? { reason: args.reason } : {}) };
             const receipt = planForm
                 ? executePlan(store, { repoId, rootPath, plan: args.plan, origin, ...LOCK_DIR })
-                : executeByDigest(store, { repoId, rootPath, planId: args.plan_id, effects: args.effects, ...selectorArgs(args), origin, ...LOCK_DIR });
+                : idForm
+                    ? executePlan(store, { repoId, rootPath, plan: rememberedPlan(args.plan_id), origin, ...LOCK_DIR })
+                    : executeByDigest(store, { repoId, rootPath, planId: args.plan_id, effects: args.effects, ...selectorArgs(args), origin, ...LOCK_DIR });
             return okMutated(surfaceReceipt(receipt));
         }
         catch (e) {
@@ -775,13 +837,13 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_update", {
-        description: "Replace a block's markdown and/or set a task's `checked` state, with compare-and-swap. `id` is the block's id (or any ref resolve accepts); `expect.content_hash` is pinned to the block's current bytes server-side when omitted (protects against a concurrent edit). `markdown` may parse to SEVERAL sibling blocks (e.g. a paragraph followed by a list): the target keeps its id and takes the first, the rest are inserted right after it with fresh ids — the Receipt's `new_ids` lists them (`$new.0`, …). A list item may likewise be replaced by a multi-item list (`- a\\n- b`), yielding sibling items. Task state is settable flat as `checked` (the same name reads flatten to — `from blocks where checked`), synced to the `[ ]`/`[x]` in the raw; every OTHER block attr (heading `level`, code `lang`, list `ordered`) is derived from the markdown, so set those by editing `markdown` (the 3.x `attrs` bag is retired and refused by name). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"block\", id }, field: \"markdown\" | \"attrs.checked\", value, expect? }] }` (both when both are given) — returns the Receipt; preview with `plan`.",
-        inputSchema: { id: z.string(), markdown: z.string().optional(), checked: z.boolean().optional(), expect: expectSchema.optional(), ...REPO_ARG },
+        description: "Replace a block's markdown and/or set a task's `checked` state, with compare-and-swap. `_id` is the block's id (or any ref resolve accepts); `expect.content_hash` is pinned to the block's current bytes server-side when omitted (protects against a concurrent edit). `markdown` may parse to SEVERAL sibling blocks (e.g. a paragraph followed by a list): the target keeps its id and takes the first, the rest are inserted right after it with fresh ids — the Receipt's `new_ids` lists them (`$new.0`, …). A list item may likewise be replaced by a multi-item list (`- a\\n- b`), yielding sibling items. Task state is settable flat as `checked` (the same name reads flatten to — `blocks { checked }`), synced to the `[ ]`/`[x]` in the raw; every OTHER block attr (heading `level`, code `lang`, list `ordered`) is derived from the markdown, so set those by editing `markdown` (the 3.x `attrs` bag is retired and refused by name). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"block\", _id }, field: \"markdown\" | \"_attrs.checked\", value, expect? }] }` (both when both are given) — returns the Receipt; preview with `plan`.",
+        inputSchema: { _id: z.string(), markdown: z.string().optional(), checked: z.boolean().optional(), expect: expectSchema.optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
-            const block = resolveBlockRef(repoId, args.id);
+            const block = resolveBlockRef(repoId, args._id);
             const built = updateBlockEffects(block, { markdown: args.markdown, checked: args.checked, expect: args.expect });
             // Nothing to set is an argument error (4.0): there is no effect for "touch".
             if (built.effects.length === 0)
@@ -829,13 +891,13 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_split", {
-        description: "Split a block at UTF-8 byte offset(s) into consecutive blocks. `id` is the block's id (or a ref); `at` is a list of integer byte offsets into the block's raw bytes (spec/mutate §2.5; an offset inside a multi-byte character rounds down to its start). CAS is pinned to the block's current bytes server-side. Sugar for `apply { effects: [{ op: \"split\", target, at }] }` — returns the Receipt (`new_ids` holds the new siblings); preview with `plan`.",
-        inputSchema: { id: z.string(), at: z.array(z.number().int()), ...REPO_ARG },
+        description: "Split a block at UTF-8 byte offset(s) into consecutive blocks. `_id` is the block's id (or a ref); `at` is a list of integer byte offsets into the block's raw bytes (spec/mutate §2.5; an offset inside a multi-byte character rounds down to its start). CAS is pinned to the block's current bytes server-side. Sugar for `apply { effects: [{ op: \"split\", target, at }] }` — returns the Receipt (`new_ids` holds the new siblings); preview with `plan`.",
+        inputSchema: { _id: z.string(), at: z.array(z.number().int()), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
-            const block = resolveBlockRef(repoId, args.id);
+            const block = resolveBlockRef(repoId, args._id);
             // The planner pins the content CAS from the live row (the block is live: it resolved).
             return sugar(repoId, root, splitEffects(block, args.at));
         }
@@ -859,14 +921,14 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_check", {
-        description: "Macro: check (or uncheck with checked:false) the given task blocks. `ids` are the blocks' ids (or refs). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"block\", id }, field: \"attrs.checked\", value }, …] }`, one per block, each CAS-pinned — returns the Receipt; preview with `plan` (tasks_complete { blocks } before surface 3.0).",
-        inputSchema: { ids: stringList(), checked: z.boolean().optional(), ...REPO_ARG },
+        description: "Macro: check (or uncheck with checked:false) the given task blocks. `_ids` are the blocks' ids (or refs). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"block\", _id }, field: \"_attrs.checked\", value }, …] }`, one per block, each CAS-pinned — returns the Receipt; preview with `plan` (tasks_complete { blocks } before surface 3.0).",
+        inputSchema: { _ids: stringList(), checked: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
-            requireSome("blocks_check", "ids", args.ids);
-            const blocks = args.ids.map((b) => resolveBlockRef(repoId, b));
+            requireSome("blocks_check", "_ids", args._ids);
+            const blocks = args._ids.map((b) => resolveBlockRef(repoId, b));
             // N × `set attrs.checked`, each CAS-pinned by the planner; a block named
             // twice is one write (the planner drops the identical duplicate, 3.2).
             return sugar(repoId, root, checkEffects(blocks, args.checked ?? true));
@@ -876,34 +938,34 @@ export function buildServer(ctx) {
         }
     });
     tool("nodes_set", {
-        description: "Macro: surgically set one editable property of a projected node (e.g. a link's `name` text or `value` target, a task's `checked`). `id` is the node's id (from `query` over `from nodes` — the one tool that addresses `nodes` rows), `prop` the property, `value` its new value. Resolves the node to its block and rewrites only that node's span. Nodes are read-only projections — this is the affordance to edit what a node represents without hand-rewriting the block. Errors node_not_editable (with the editable prop list) when the kind/prop has no editor. Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"node\", id }, field: prop, value }] }` — returns the Receipt; preview with `plan` (node_set before surface 3.0).",
-        inputSchema: { id: z.string(), prop: z.string(), value: z.string(), ...REPO_ARG },
+        description: "Macro: surgically set one editable property of a projected node (e.g. a link's `name` text or `value` target, a task's `checked`). `_id` is the node's id (from `query` over `nodes { … }` — the one tool that addresses `nodes` rows), `prop` the property, `value` its new value. Resolves the node to its block and rewrites only that node's span. Nodes are read-only projections — this is the affordance to edit what a node represents without hand-rewriting the block. Errors node_not_editable (with the editable prop list) when the kind/prop has no editor. Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"node\", _id }, field: prop, value }] }` — returns the Receipt; preview with `plan` (node_set before surface 3.0).",
+        inputSchema: { _id: z.string(), prop: z.string(), value: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
-            const known = store.db.prepare("SELECT 1 FROM nodes WHERE node_id = ? AND repo_id = ?").get(args.id, repoId);
+            const known = store.db.prepare("SELECT 1 FROM nodes WHERE node_id = ? AND repo_id = ?").get(args._id, repoId);
             if (!known)
-                throw new EngineError("block_missing", `no node with id ${JSON.stringify(args.id)}`, { data: { id: args.id } });
-            return sugar(repoId, root, nodeSetEffects(args.id, args.prop, args.value));
+                throw new EngineError("block_missing", `no node with id ${JSON.stringify(args._id)}`, { data: { _id: args._id } });
+            return sugar(repoId, root, nodeSetEffects(args._id, args.prop, args.value));
         }
         catch (e) {
             return fail(e);
         }
     });
     tool("blocks_append", {
-        description: "Macro: append markdown INTO a block, by what the block is. `id` is a block's id (or a ref). A HEADING: the `text` is inserted at the end of its section range (before the next heading of equal or higher level) — `insert into { kind: \"section\", heading_id }`. A CONTAINER (a list, list item, task, blockquote or table — anything the kernel accepts as a parent): inserted at the end of its children (`insert into { kind: \"block\", id } at end`). A LEAF (a paragraph, code fence, …) is `block_not_container` — append means \"into\", never a sibling insert; place after it with `blocks_insert { to: <its parent>, at: { after: <id> } }`. Sugar for that one `insert` effect — returns the Receipt; preview with `plan`. To append at a whole document's end, or inside a section named by its heading TEXT, use docs_append.",
-        inputSchema: { id: z.string(), text: z.string(), ...REPO_ARG },
+        description: "Macro: append markdown INTO a block, by what the block is. `_id` is a block's id (or a ref). A HEADING: the `text` is inserted at the end of its section range (before the next heading of equal or higher level) — `insert into { kind: \"section\", heading_id }`. A CONTAINER (a list, list item, task, blockquote or table — anything the kernel accepts as a parent): inserted at the end of its children (`insert into { kind: \"block\", _id } at end`). A LEAF (a paragraph, code fence, …) is `block_not_container` — append means \"into\", never a sibling insert; place after it with `blocks_insert { to: <its parent>, at: { after: <_id> } }`. Sugar for that one `insert` effect — returns the Receipt; preview with `plan`. To append at a whole document's end, or inside a section named by its heading TEXT, use docs_append.",
+        inputSchema: { _id: z.string(), text: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
-            const block = resolveBlockRef(repoId, args.id);
+            const block = resolveBlockRef(repoId, args._id);
             const row = store.db
                 .prepare("SELECT b.type AS type, d.format AS format, b.parent_block AS parent, d.path AS path, (SELECT count(*) FROM blocks c WHERE c.parent_block = b.block_id AND c.deleted_commit IS NULL) AS children FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_commit IS NULL")
                 .get(block);
             if (!row)
-                throw blockMissing(args.id);
+                throw blockMissing(args._id);
             let into;
             if (row.type === "heading") {
                 into = { kind: "section", heading_id: block };
@@ -914,7 +976,7 @@ export function buildServer(ctx) {
             else {
                 // The fix (4.4): the sibling insert spelled out — its parent block, or the document when it is top-level.
                 throw new EngineError("block_not_container", `block ${block} is a ${row.type}, not a heading or a container; append means into — insert after it with blocks_insert { to: <its parent>, at: { after: ${JSON.stringify(block)} } }`, {
-                    data: { id: block, type: row.type, fix: fixTool("blocks_insert", { to: row.parent ?? referencePath(row.path), at: { after: block }, markdown: args.text }) },
+                    data: { _id: block, _type: row.type, fix: fixTool("blocks_insert", { to: row.parent ?? referencePath(row.path), at: { after: block }, markdown: args.text }) },
                 });
             }
             return sugar(repoId, root, appendEffects(into, args.text));
@@ -924,7 +986,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_append", {
-        description: "Macro: append markdown to a document — at its END, or at the end of one of its sections when `section` names a heading by its TEXT (`\"Setup\"`; an ATX spelling `\"## Setup\"` is accepted). The journal/log/running-note primitive. ADDITIVE and identity-preserving, NOT a whole-body replace: the `text` is parsed into blocks and inserted as NEW blocks after the existing ones (at the document's top level, or inside the section's range), so every existing block keeps its stable `b_` id (omgbase deliberately has no whole-body `docs_put` — see mcp-api). Sugar for one `insert at end` effect into the document or the resolved section — returns the Receipt (`new_ids` the appended blocks); preview with `plan`. Address the document by `id` or `path` (at least one). The document must already exist — a missing doc errors `doc_missing` (creating one is docs_create's job, never this); a `section` matching no heading in it is `parent_missing`, one matching several is `ambiguous_heading` with `candidates[{ id, doc_id }]` — pass that heading's id to blocks_append, which appends into a block by its id.",
+        description: "Macro: append markdown to a document — at its END, or at the end of one of its sections when `section` names a heading by its TEXT (`\"Setup\"`; an ATX spelling `\"## Setup\"` is accepted). The journal/log/running-note primitive. ADDITIVE and identity-preserving, NOT a whole-body replace: the `text` is parsed into blocks and inserted as NEW blocks after the existing ones (at the document's top level, or inside the section's range), so every existing block keeps its stable `b_` id (omgbase deliberately has no whole-body `docs_put` — see mcp-api). Sugar for one `insert at end` effect into the document or the resolved section — returns the Receipt (`new_ids` the appended blocks); preview with `plan`. Address the document by `_id` or `_path` (at least one). The document must already exist — a missing doc errors `doc_missing` (creating one is docs_create's job, never this); a `section` matching no heading in it is `parent_missing`, one matching several is `ambiguous_heading` with `candidates[{ _id, _doc_id }]` — pass that heading's `_id` to blocks_append, which appends into a block by its id.",
         inputSchema: { ...DOC_ARGS, text: z.string(), section: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -938,10 +1000,10 @@ export function buildServer(ctx) {
             let into;
             if (args.section !== undefined) {
                 const info = findDoc(store, { docId });
-                into = { kind: "section", heading_id: resolveSectionHeading(docId, info.path, args.section, { ...(args.id !== undefined ? { id: args.id } : {}), ...(args.path !== undefined ? { path: args.path } : {}), text: args.text }) };
+                into = { kind: "section", heading_id: resolveSectionHeading(docId, info.path, args.section, { ...(args._id !== undefined ? { _id: args._id } : {}), ...(args._path !== undefined ? { _path: args._path } : {}), text: args.text }) };
             }
             else {
-                into = { kind: "document", id: docId };
+                into = { kind: "document", _id: docId };
             }
             return sugar(repoId, root, docsAppendEffects(into, args.text));
         }
@@ -950,7 +1012,7 @@ export function buildServer(ctx) {
         }
     });
     tool("links_retarget", {
-        description: "Macro: rewrite ONE link destination everywhere it is linked — the single-pair form of links_repair (same matching rules: whole link destinations only, leading `/` optional, fragments preserved; prose/inline code/code fences untouched). Scope source docs with `path_glob`. COMMITS: sugar for `apply { effects: [{ op: \"retarget\", repairs: [{ from, to }], path_glob? }] }`; returns `hits[{id,path,oldRaw,newRaw}]` (the rewritten block and its document) and `pairs[{from,to,hits}]` plus the Receipt (`commit` null when nothing matched). To PREVIEW first, call `plan` with that one effect: its `preview.retarget[0]` carries the same `hits` and `pairs` and `preview.diffs` the files, and it fails exactly where the commit would (through surface 3.x this tool was a dry run by default, with `applied`).",
+        description: "Macro: rewrite ONE link destination everywhere it is linked — the single-pair form of links_repair (same matching rules: whole link destinations only, leading `/` optional, fragments preserved; prose/inline code/code fences untouched). Scope source docs with `path_glob`. COMMITS: sugar for `apply { effects: [{ op: \"retarget\", repairs: [{ from, to }], path_glob? }] }`; returns `hits[{_id,_path,oldRaw,newRaw}]` (the rewritten block and its document) and `pairs[{from,to,hits}]` plus the Receipt (`commit` null when nothing matched). To PREVIEW first, call `plan` with that one effect: its `preview.retarget[0]` carries the same `hits` and `pairs` and `preview.diffs` the files, and it fails exactly where the commit would (through surface 3.x this tool was a dry run by default, with `applied`).",
         inputSchema: { from_target: z.string(), to_target: z.string(), path_glob: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -969,7 +1031,7 @@ export function buildServer(ctx) {
         }
     });
     tool("links_stale", {
-        description: "READ-ONLY link health: surfaces DANGLING internal links — links whose target path has NO live document (stored as a `phantom:` edge; a doc created at that path auto-resolves them). Returns `stale[]` (each a link row under the `links` target's names: `doc_id`, `path` (the source document), `block_id` (null for a frontmatter edge), predicate, provenance, dst_kind, `target` = the canonical missing path, `/`-rooted like every path the surface returns (e.g. `/guides/old.md`), `authored` = the destination text exactly as written in the source block (e.g. `/guides/old.md#Setup`; null for frontmatter edges), `anchor`, and reason `dangling_doc`), plus `externalCount` (http(s) links — UNVERIFIABLE here, never marked broken, since reachability needs network I/O the engine won't do), `totalOpenEdges`, and `truncated` (capped by `limit`, default 500). `summary:true` returns counts only — `staleCount`, `byTarget[{target,count}]`, `bySource[{path,count}]`, `externalCount`, `totalOpenEdges` — for a repo-wide audit in one small call. Scope the SOURCE docs with `path_glob` (e.g. \"journal/*\"; `*` matches across `/`). Fix the reported targets with `links_repair` (batch) or `links_retarget` (single): either `target` or `authored` works as `from`. Anchors (#heading/^ref) into an existing doc are NOT verified in v1. Contrast docs_read/query which answer 'what does this doc say', not 'which of its links are broken'.",
+        description: "READ-ONLY link health: surfaces DANGLING internal links — links whose target path has NO live document (stored as a `phantom:` edge; a doc created at that path auto-resolves them). Returns `stale[]` (each a link row under the `links` target's names: `_doc_id`, `_path` (the source document), `_block_id` (null for a frontmatter edge), `_predicate`, `_provenance`, `_dst_kind`, `target` = the canonical missing path, `/`-rooted like every path the surface returns (e.g. `/guides/old.md`), `authored` = the destination text exactly as written in the source block (e.g. `/guides/old.md#Setup`; null for frontmatter edges), `_anchor`, and reason `dangling_doc`), plus `externalCount` (http(s) links — UNVERIFIABLE here, never marked broken, since reachability needs network I/O the engine won't do), `totalOpenEdges`, and `truncated` (capped by `limit`, default 500). `summary:true` returns counts only — `staleCount`, `byTarget[{target,count}]`, `bySource[{_path,count}]`, `externalCount`, `totalOpenEdges` — for a repo-wide audit in one small call. Scope the SOURCE docs with `path_glob` (e.g. \"journal/*\"; `*` matches across `/`). Fix the reported targets with `links_repair` (batch) or `links_retarget` (single): either `target` or `authored` works as `from`. Anchors (#heading/^ref) into an existing doc are NOT verified in v1. Contrast docs_read/query which answer 'what does this doc say', not 'which of its links are broken'.",
         inputSchema: { path_glob: z.string().optional(), limit: z.number().int().optional(), summary: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -986,7 +1048,7 @@ export function buildServer(ctx) {
         }
     });
     tool("links_repair", {
-        description: "Macro: BULK stale-link repair — rewrite one or MANY LINK DESTINATIONS in ONE changeset. Pass `repairs` (an array of {from,to}) to fix several dangling targets — e.g. those surfaced by links_stale — at once; a single {from_target,to_target} pair is also accepted. MATCHING: `from` must be the WHOLE destination of a Markdown link/image `[t](dest)`, a wikilink `[[dest]]`/`[[dest|alias]]`, or a bare-path inline field `key:: /dest` — a leading `/` is optional on either side (so links_stale's `target` or `authored` both work), and a trailing `#heading`/`^ref` fragment on the link is kept and re-appended to `to`. NOT rewritten: prose mentions, inline code, `code_fence` blocks, longer paths that merely contain `from`, and frontmatter values (use docs_set_meta). Scope source docs with `path_glob` (as in links_stale). Ops coalesce to one update per TOP-MOST block (a list and its items count once), so a batch never trips over its own re-minted children. COMMITS: sugar for `apply { effects: [{ op: \"retarget\", repairs, path_glob? }] }`; returns `hits[{id,path,oldRaw,newRaw}]` (the rewritten block and its document) and `pairs[{from,to,hits}]` (per-pair destination counts; 0 = nothing matched) plus the Receipt (`commit` null when nothing matched). To PREVIEW first, call `plan` with that one effect — its `preview.retarget[0]` carries the same `hits`/`pairs`, `preview.diffs` the files — and it fails exactly where the commit would (through surface 3.x this tool was a dry run by default, with `applied`).",
+        description: "Macro: BULK stale-link repair — rewrite one or MANY LINK DESTINATIONS in ONE changeset. Pass `repairs` (an array of {from,to}) to fix several dangling targets — e.g. those surfaced by links_stale — at once; a single {from_target,to_target} pair is also accepted. MATCHING: `from` must be the WHOLE destination of a Markdown link/image `[t](dest)`, a wikilink `[[dest]]`/`[[dest|alias]]`, or a bare-path inline field `key:: /dest` — a leading `/` is optional on either side (so links_stale's `target` or `authored` both work), and a trailing `#heading`/`^ref` fragment on the link is kept and re-appended to `to`. NOT rewritten: prose mentions, inline code, `code_fence` blocks, longer paths that merely contain `from`, and frontmatter values (use docs_set_meta). Scope source docs with `path_glob` (as in links_stale). Ops coalesce to one update per TOP-MOST block (a list and its items count once), so a batch never trips over its own re-minted children. COMMITS: sugar for `apply { effects: [{ op: \"retarget\", repairs, path_glob? }] }`; returns `hits[{_id,_path,oldRaw,newRaw}]` (the rewritten block and its document) and `pairs[{from,to,hits}]` (per-pair destination counts; 0 = nothing matched) plus the Receipt (`commit` null when nothing matched). To PREVIEW first, call `plan` with that one effect — its `preview.retarget[0]` carries the same `hits`/`pairs`, `preview.diffs` the files — and it fails exactly where the commit would (through surface 3.x this tool was a dry run by default, with `applied`).",
         inputSchema: {
             repairs: z.array(z.object({ from: z.string(), to: z.string() })).optional(),
             from_target: z.string().optional(),
@@ -1034,7 +1096,7 @@ export function buildServer(ctx) {
     /** `path_taken` exactly as the legacy document operations raised it: their message, no `data` (§9). */
     const requireAbsent = (repoId, rootPath, rel, takenMessage) => requireAbsentPath(store, repoId, { rootPath }, rel, takenMessage);
     tool("docs_create", {
-        description: "Create a new document at `path` (the new document's path, either form) from complete file bytes (`markdown`), with optional structured `frontmatter`. Sugar for `apply { effects: [{ op: \"create\", path, markdown, frontmatter? }] }` — returns the Receipt: `revisions[0]` is the created document (its `id`, rooted `path`, `hash`), `new_ids[\"$new.0\"]` the same id and `$new.1…` its blocks in pre-order. Fails path_taken if it already exists. Preview with `plan` over that effect (`preview.diffs[path]` is `\"\" → the bytes`).",
+        description: "Create a new document at `path` (the new document's path, either form) from complete file bytes (`markdown`), with optional structured `frontmatter`. Sugar for `apply { effects: [{ op: \"create\", path, markdown, frontmatter? }] }` — returns the Receipt: `revisions[0]` is the created document (its `_id`, rooted `_path`, `_hash`), `new_ids[\"$new.0\"]` the same id and `$new.1…` its blocks in pre-order. Fails path_taken if it already exists. Preview with `plan` over that effect (`preview.diffs[path]` is `\"\" → the bytes`).",
         inputSchema: { path: z.string(), markdown: z.string(), frontmatter: z.record(z.string(), z.unknown()).optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1049,14 +1111,14 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_move", {
-        description: "Rename a document to a new path (`to_path`, `/`-rooted or bare); the document is addressed by `id` or `path`. Block identity and history are preserved, and the inbound links FOLLOW it: every link written against the old path (Markdown links/images, wikilinks, bare-path inline fields — anchors, link text, titles and code spans preserved, absolute vs relative style kept) is rewritten to the new path in the same call as one CAS-checked commit, so a move never leaves the graph broken. Fails path_taken if the destination exists. Sugar for `apply { effects: [{ op: \"move\", target: { kind: \"document\", id }, to, retarget_inbound? }] }` — returns the Receipt (one revision per rewritten source; the moved document's own revision does not advance unless it links to itself) plus `retargeted` (the touched blocks/docs) and `dangling` — what could NOT be rewritten, i.e. frontmatter relations (block null; fix with docs_set_meta). Pass `retarget_inbound:false` to opt out for the rarer intent that the old path become unbound: the links are left as written, listed in `dangling` ({doc_id, path, block_id, target, anchor, field?} per occurrence — a link row under the `links` target's names) and reported by links_stale (their edges become `phantom:<old path>`); links already written against the new path start resolving to this doc either way. Preview with `plan` over that effect: `preview.diffs` holds the old path emptied, the new path filled and the rewritten sources.",
+        description: "Rename a document to a new path (`to_path`, `/`-rooted or bare); the document is addressed by `_id` or `_path`. Block identity and history are preserved, and the inbound links FOLLOW it: every link written against the old path (Markdown links/images, wikilinks, bare-path inline fields — anchors, link text, titles and code spans preserved, absolute vs relative style kept) is rewritten to the new path in the same call as one CAS-checked commit, so a move never leaves the graph broken. Fails path_taken if the destination exists. Sugar for `apply { effects: [{ op: \"move\", target: { kind: \"document\", _id }, to, retarget_inbound? }] }` — returns the Receipt (one revision per rewritten source; the moved document's own revision does not advance unless it links to itself) plus `retargeted` (the touched blocks/docs) and `dangling` — what could NOT be rewritten, i.e. frontmatter relations (`_block_id` null; fix with docs_set_meta). Pass `retarget_inbound:false` to opt out for the rarer intent that the old path become unbound: the links are left as written, listed in `dangling` ({_doc_id, _path, _block_id, target, _anchor, _field?} per occurrence — a link row under the `links` target's names) and reported by links_stale (their edges become `phantom:<old path>`); links already written against the new path start resolving to this doc either way. Preview with `plan` over that effect: `preview.diffs` holds the old path emptied, the new path filled and the rewritten sources.",
         inputSchema: { ...DOC_ARGS, to_path: z.string(), retarget_inbound: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const scope = repoScope(args.repo);
             const docId = locateDoc(scope.repoId, "docs_move", registry.get("docs_move").shape, args);
             const rootPath = requireRoot(scope.rootPath);
-            const doc = { id: docId, path: pathOfDoc(docId) };
+            const doc = { _id: docId, _path: pathOfDoc(docId) };
             const to = canonicalDocPath(args.to_path);
             requireAbsent(scope.repoId, rootPath, to, `a document already exists at ${to}`);
             const retargetInbound = args.retarget_inbound !== false;
@@ -1073,21 +1135,21 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_delete", {
-        description: "Delete a document: tombstone it and its live blocks (resurrection-poolable) and remove the file. Address it by `id` or `path`. Sugar for `apply { effects: [{ op: \"remove\", target: { kind: \"document\", id } }] }` — returns the Receipt (a tombstone advances no revision: `revisions` is empty, `commit` the one commit). Preview with `plan` over that effect (`preview.diffs[path]` is `the bytes → \"\"`).",
+        description: "Delete a document: tombstone it and its live blocks (resurrection-poolable) and remove the file. Address it by `_id` or `_path`. Sugar for `apply { effects: [{ op: \"remove\", target: { kind: \"document\", _id } }] }` — returns the Receipt (a tombstone advances no revision: `revisions` is empty, `commit` the one commit). Preview with `plan` over that effect (`preview.diffs[path]` is `the bytes → \"\"`).",
         inputSchema: { ...DOC_ARGS, ...REPO_ARG },
     }, async (args) => {
         try {
             const scope = repoScope(args.repo);
             const docId = locateDoc(scope.repoId, "docs_delete", registry.get("docs_delete").shape, args);
             const rootPath = requireRoot(scope.rootPath);
-            return sugar(scope.repoId, rootPath, deleteDocEffects({ id: docId, path: pathOfDoc(docId) }));
+            return sugar(scope.repoId, rootPath, deleteDocEffects({ _id: docId, _path: pathOfDoc(docId) }));
         }
         catch (e) {
             return fail(e);
         }
     });
     tool("docs_set_meta", {
-        description: "Surgical frontmatter patch: set the given keys and/or unset named keys on the document addressed by `id` or `path`. Other frontmatter and the whole body are preserved (every block keeps its id). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"document\", id }, field: \"frontmatter.<key>\", value }, { op: \"unset\", …, field: \"frontmatter.<key>\" }, …] }`, one effect per key — returns the Receipt; at least one of `set`/`unset` is required. Preview with `plan` over those effects (`preview.diffs[path]` is the file before → after).",
+        description: "Surgical frontmatter patch: set the given keys and/or unset named keys on the document addressed by `_id` or `_path`. Other frontmatter and the whole body are preserved (every block keeps its id). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"document\", _id }, field: \"_frontmatter.<key>\", value }, { op: \"unset\", …, field: \"_frontmatter.<key>\" }, …] }`, one effect per key — returns the Receipt; at least one of `set`/`unset` is required. Preview with `plan` over those effects (`preview.diffs[path]` is the file before → after).",
         inputSchema: { ...DOC_ARGS, set: z.record(z.string(), z.unknown()).optional(), unset: stringList().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1098,7 +1160,7 @@ export function buildServer(ctx) {
             // One scalar effect per key, `unset` winning over `set` for a shared key;
             // the planner drops a repeated `unset`. An empty patch is an argument
             // error (3.3, §9) — it used to rewrite the frontmatter through the emitter for nothing.
-            const built = setMetaEffects({ id: docId, path: pathOfDoc(docId) }, args.set, args.unset);
+            const built = setMetaEffects({ _id: docId, _path: pathOfDoc(docId) }, args.set, args.unset);
             if (built.effects.length === 0)
                 throw argumentError("docs_set_meta", "pass `set` and/or `unset`", shape);
             return sugar(scope.repoId, rootPath, built);
@@ -1108,14 +1170,14 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_update", {
-        description: "Whole-document update with smart identity preservation — sugar for `apply { effects: [{ op: \"set\", target: { kind: \"document\", id }, field: \"content\", value: content }] }` (surface 4.0). Submit the complete proposed `content` for a document (`id` or `path`); the engine reconciles it against the current tree, preserving stable block ids for structure that is recognizably the same (edits, moves, reorders), minting for new structure, and tombstoning removals — frontmatter changes included — and commits the derived ops as ONE transaction. Returns the Receipt `{ plan_id, commit, revisions: [{ id, path, hash }], new_ids, committed: true }`; content that already equals the document is a plan with nothing to do — no commit (`commit: null`, no revision). To INSPECT the identity consequences before committing, call `plan { effects: [that set] }`: its `preview.identity[<doc id>]` is `{ matcher_v, summary: { preserved, updated, moved, created, removed, split, merged, ambiguous }, ops: [{ op_index, disposition, blocks, confidence, reason }], diagnostics }` — each planned kernel op (`preview`'s `op_index` into the plan's `opset.ops`) annotated with the disposition it realizes — and the plan's `preconditions.docs` pin the document's revision and hash; then `execute` that plan, or call this tool. A document that changed since planning fails stale_plan (re-plan). Content the planner cannot reproduce byte-for-byte fails plan_not_convergent; the message names the first divergent byte and the proposed block (index/type) that failed to round-trip (full diagnostics in `data.diagnostics`).",
+        description: "Whole-document update with smart identity preservation — sugar for `apply { effects: [{ op: \"set\", target: { kind: \"document\", _id }, field: \"content\", value: content }] }` (surface 4.0). Submit the complete proposed `content` for a document (`_id` or `_path`); the engine reconciles it against the current tree, preserving stable block ids for structure that is recognizably the same (edits, moves, reorders), minting for new structure, and tombstoning removals — frontmatter changes included — and commits the derived ops as ONE transaction. Returns the Receipt `{ plan_id, commit, revisions: [{ _id, _path, _hash }], new_ids, committed: true }`; content that already equals the document is a plan with nothing to do — no commit (`commit: null`, no revision). To INSPECT the identity consequences before committing, call `plan { effects: [that set] }`: its `preview.identity[<doc id>]` is `{ matcher_v, summary: { preserved, updated, moved, created, removed, split, merged, ambiguous }, ops: [{ op_index, disposition, blocks, confidence, reason }], diagnostics }` — each planned kernel op (`preview`'s `op_index` into the plan's `opset.ops`) annotated with the disposition it realizes — and the plan's `preconditions.docs` pin the document's revision and hash; then `execute` that plan, or call this tool. A document that changed since planning fails stale_plan (re-plan). Content the planner cannot reproduce byte-for-byte fails plan_not_convergent; the message names the first divergent byte and the proposed block (index/type) that failed to round-trip (full diagnostics in `data.diagnostics`).",
         inputSchema: { ...DOC_ARGS, content: z.string(), reason: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const scope = repoScope(args.repo);
             const docId = locateDoc(scope.repoId, "docs_update", registry.get("docs_update").shape, args);
             const rootPath = requireRoot(scope.rootPath);
-            const { receipt } = runSugar(scope.repoId, rootPath, updateContentEffects({ id: docId }, args.content), args.reason);
+            const { receipt } = runSugar(scope.repoId, rootPath, updateContentEffects({ _id: docId }, args.content), args.reason);
             return okMutated(surfaceReceipt(receipt));
         }
         catch (e) {
@@ -1123,7 +1185,7 @@ export function buildServer(ctx) {
         }
     });
     tool("observe", {
-        description: "SYNC INGEST (ADR-014): record `content` as the current authoritative bytes for `path`, committed as an OBSERVED-origin revision — a write *around* the engine, the way a human/external edit is recorded. Contrast docs_update, which is api-origin (a write *through* the engine, agent intent); both reconcile the new bytes against the current block tree and preserve stable ids, but the origin differs (and thus the change-feed semantics and matcher path). This is the file→DB direction for an out-of-process synchronizer: it never writes a file, so it works on a headless/sourceless server with no working tree. Idempotent: bytes whose hash already equals the stored revision are an ECHO — no commit (`echo:true`, `rev:null`). Bytes with git conflict markers are still ingested (opaque) and the doc is flagged (`conflicted:true`). To mirror a deletion, use `observe_delete` (an observed, resurrection-pooled tombstone — not `docs_delete`, which is an intentional api-origin removal that also unlinks the file). Returns `{ id, path, rev, commitId, converged, echo, conflicted, dispositions }` — the document's row attributes plus a disposition summary (how identity threaded). `path` is a FILE event's path from the store's layer, not a row locator, so it keeps its name.",
+        description: "SYNC INGEST (ADR-014): record `content` as the current authoritative bytes for `path`, committed as an OBSERVED-origin revision — a write *around* the engine, the way a human/external edit is recorded. Contrast docs_update, which is api-origin (a write *through* the engine, agent intent); both reconcile the new bytes against the current block tree and preserve stable ids, but the origin differs (and thus the change-feed semantics and matcher path). This is the file→DB direction for an out-of-process synchronizer: it never writes a file, so it works on a headless/sourceless server with no working tree. Idempotent: bytes whose hash already equals the stored revision are an ECHO — no commit (`echo:true`, `rev:null`). Bytes with git conflict markers are still ingested (opaque) and the doc is flagged (`conflicted:true`). To mirror a deletion, use `observe_delete` (an observed, resurrection-pooled tombstone — not `docs_delete`, which is an intentional api-origin removal that also unlinks the file). Returns `{ _id, _path, rev, commitId, converged, echo, conflicted, dispositions }` — the document's row attributes plus a disposition summary (how identity threaded). The `path` ARGUMENT is a FILE event's path from the store's layer, not a row locator, so it keeps its bare name.",
         inputSchema: { path: z.string(), content: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1159,18 +1221,18 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_history", {
-        description: "A block's biography: the commits that CHANGED the block `id` names — inserted, edited, moved, split/merge lineage, resurrected — with disposition kind/confidence/reason, newest first. A commit that rewrote the document but left this block byte-identical in place is not listed (store 14.2: `same` verdicts are not persisted; through 14.1 every commit to the document appeared here), so the newest entry's `ts` is the block's `updated_at`; to learn whether the block was present in some other commit, diff two revisions with docs_diff (history_node before surface 3.0 — it always took a block id and returned the block's changes). Not repo-scoped: block ids are global.",
-        inputSchema: { id: z.string(), limit: z.number().int().optional() },
+        description: "A block's biography: the commits that CHANGED the block `_id` names — inserted, edited, moved, split/merge lineage, resurrected — with disposition kind/confidence/reason, newest first. A commit that rewrote the document but left this block byte-identical in place is not listed (store 14.2: `same` verdicts are not persisted; through 14.1 every commit to the document appeared here), so the newest entry's `ts` is the block's `_updated_at`; to learn whether the block was present in some other commit, diff two revisions with docs_diff (history_node before surface 3.0 — it always took a block id and returned the block's changes). Not repo-scoped: block ids are global.",
+        inputSchema: { _id: z.string(), limit: z.number().int().optional() },
     }, async (args) => {
         try {
-            return ok(historyNode(store, args.id, args.limit !== undefined ? { limit: args.limit } : {}));
+            return ok(historyNode(store, args._id, args.limit !== undefined ? { limit: args.limit } : {}));
         }
         catch (e) {
             return fail(e);
         }
     });
     tool("docs_diff", {
-        description: "Block-grain diff between two revisions of a document: `[{ kind: added|removed|changed, id (the block), before?, after? }]` in that order. Address the document by `id` or `path` (at least one); `from_rev`/`to_rev` are revision ids (from docs_history, changes_since or blocks_history). Contrast docs_diff_unified, the unified text diff. (diff before surface 3.0.)",
+        description: "Block-grain diff between two revisions of a document: `[{ kind: added|removed|changed, _id (the block), before?, after? }]` in that order. Address the document by `_id` or `_path` (at least one); `from_rev`/`to_rev` are revision ids (from docs_history, changes_since or blocks_history). Contrast docs_diff_unified, the unified text diff. (diff before surface 3.0.)",
         inputSchema: { ...DOC_ARGS, from_rev: z.string(), to_rev: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1187,7 +1249,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_diff_unified", {
-        description: "Unified diff between two revisions of a document (the `omg diff` rendering): returns `{ id, path, from, to, diff }` where `diff` is a unified diff of the two revisions' file texts — for each revision exactly the bytes docs_read_at returns, so hunk line numbers are real file lines (Myers shortest edit script; `@@ -a,b +c,d @@` hunks with 3 lines of context; lines prefixed `-`, `+` or a space; no file header; identical texts → \"\"). Address the document by `id` or `path` (at least one). `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `docs_diff`, which returns block-grain added/removed/changed entries. (diff_unified before surface 3.0.)",
+        description: "Unified diff between two revisions of a document (the `omg diff` rendering): returns `{ _id, _path, from, to, diff }` where `diff` is a unified diff of the two revisions' file texts — for each revision exactly the bytes docs_read_at returns, so hunk line numbers are real file lines (Myers shortest edit script; `@@ -a,b +c,d @@` hunks with 3 lines of context; lines prefixed `-`, `+` or a space; no file header; identical texts → \"\"). Address the document by `_id` or `_path` (at least one). `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `docs_diff`, which returns block-grain added/removed/changed entries. (diff_unified before surface 3.0.)",
         inputSchema: { ...DOC_ARGS, from_rev: z.string().optional(), to_rev: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1196,7 +1258,7 @@ export function buildServer(ctx) {
             return ok(docDiffUnified(store, docId, {
                 ...(args.from_rev !== undefined ? { fromRev: args.from_rev } : {}),
                 ...(args.to_rev !== undefined ? { toRev: args.to_rev } : {}),
-                label: JSON.stringify(args.id ?? args.path),
+                label: JSON.stringify(args._id ?? args._path),
             }));
         }
         catch (e) {
@@ -1204,7 +1266,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_read_at", {
-        description: "TIME-TRAVEL read: the whole file bytes of a document AS OF a past revision — `raw` is the reconstructed source at that `rev` (fences/tables/list markers preserved), plus `id`/`path` (the path as of that revision)/`rev`. Sugar for `docs_read { id | path, at: rev }` (surface 4.7) — the same result, byte for byte. Use this to audit or answer 'what did this doc say at revision N', or to fetch the exact prior text before reverting. Get a `rev` from `query` over the `revisions` target (`from revisions where path == … order by seq`), docs_diff, blocks_history, docs_history or changes_since. Contrast: docs_read = current bytes; docs_diff = block-grain changes BETWEEN two revisions. `renderedHashMatch` is true when the reconstruction is byte-for-byte the file at that revision; it can be false for an old revision ONLY when the document's leading/frontmatter trivia (separator bytes, not block content) changed since — block content always reconstructs faithfully. No `properties`: the property table is current-state only (through 4.6 the current bag rode along flagged propertiesAreCurrent). Address the document by `id` or `path` plus a `rev` id. A revision whose bodies were moved to an archive segment (`archived` in docs_history / the revisions target) reads through the segment when it is attached; otherwise the call fails `revision_archived` with `data: { rev, archive, path? }` — an operator attaches the file with `omg history attach`.",
+        description: "TIME-TRAVEL read: the whole file bytes of a document AS OF a past revision — `_raw` is the reconstructed source at that `rev` (fences/tables/list markers preserved), plus `_id`/`_path` (the path as of that revision)/`rev`. Sugar for `docs_read { _id | _path, at: rev }` (surface 4.7) — the same result, byte for byte. Use this to audit or answer 'what did this doc say at revision N', or to fetch the exact prior text before reverting. Get a `rev` from `query` over the `revisions` target (`revisions { _path == … order by _seq }`), docs_diff, blocks_history, docs_history or changes_since. Contrast: docs_read = current bytes; docs_diff = block-grain changes BETWEEN two revisions. `renderedHashMatch` is true when the reconstruction is byte-for-byte the file at that revision; it can be false for an old revision ONLY when the document's leading/frontmatter trivia (separator bytes, not block content) changed since — block content always reconstructs faithfully. No `properties`: the property table is current-state only (through 4.6 the current bag rode along flagged propertiesAreCurrent). Address the document by `_id` or `_path` plus a `rev` id. A revision whose bodies were moved to an archive segment (`_archived` in docs_history / the revisions target) reads through the segment when it is attached; otherwise the call fails `revision_archived` with `data: { rev, archive, path? }` — an operator attaches the file with `omg history attach`.",
         inputSchema: { ...DOC_ARGS, rev: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1217,7 +1279,7 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_history", {
-        description: "VERSION HISTORY of matching documents, grouped BY DOCUMENT: for each doc (`id`, `path`, `deleted`, `currentRev`), its ordered revision list (oldest→newest) with `rev`/`seq`/`commit`/`updated_at`/`origin`/`actor`/`hash`/`isCurrent`/`archived` (true when the revision's bodies live in an archive segment — the row stays, docs_read_at reads through the segment while it is attached). Give `path_glob` (e.g. \"journal/*\" — `*` matches ACROSS `/`, so journal/* and journal/** are equivalent) OR a single document by `id` or `path`; at least one is required. `hash` (hex of the revision's rendered file hash) lets you spot no-op vs real changes. Feed a returned `rev` into `docs_read_at` (whole doc AT that rev) or `docs_diff` (block-grain changes BETWEEN two revs). By default only live docs; `include_deleted:true` also returns tombstoned docs (their history is intact for audit). `limit` caps DOCUMENTS returned (default 50) with a `truncated` flag. Contrast `changes_since`: a repo-wide COMMIT feed, not this per-document view.",
+        description: "VERSION HISTORY of matching documents, grouped BY DOCUMENT: for each doc (`_id`, `_path`, `deleted`, `currentRev`), its ordered revision list (oldest→newest) — each version a `revisions` row under the row's names: `_rev`/`_seq`/`_commit`/`_ts`/`_origin`/`_actor`/`_hash`/`_is_current`/`_archived` (true when the revision's bodies live in an archive segment — the row stays, docs_read_at reads through the segment while it is attached). Give `path_glob` (e.g. \"journal/*\" — `*` matches ACROSS `/`, so journal/* and journal/** are equivalent) OR a single document by `_id` or `_path`; at least one is required. `_hash` (hex of the revision's rendered file hash) lets you spot no-op vs real changes. Feed a returned `_rev` into `docs_read_at` (whole doc AT that rev) or `docs_diff` (block-grain changes BETWEEN two revs). By default only live docs; `include_deleted:true` also returns tombstoned docs (their history is intact for audit). `limit` caps DOCUMENTS returned (default 50) with a `truncated` flag. Contrast `changes_since`: a repo-wide COMMIT feed, not this per-document view.",
         inputSchema: {
             path_glob: z.string().optional(),
             ...DOC_ARGS,
@@ -1228,17 +1290,17 @@ export function buildServer(ctx) {
     }, async (args) => {
         try {
             const { repoId } = repoScope(args.repo);
-            if (!args.path_glob && args.id === undefined && args.path === undefined) {
-                throw new EngineError("target_missing", "docs_history requires one of path_glob, id or path");
+            if (!args.path_glob && args._id === undefined && args._path === undefined) {
+                throw new EngineError("target_missing", "docs_history requires one of path_glob, _id or _path");
             }
             let doc;
-            if (args.id !== undefined || args.path !== undefined) {
+            if (args._id !== undefined || args._path !== undefined) {
                 // A live document resolves through the locator; with include_deleted a
                 // tombstoned one is looked up by the same attribute.
                 const tomb = args.include_deleted
-                    ? (args.id !== undefined
-                        ? store.db.prepare("SELECT doc_id FROM docs WHERE doc_id = ? AND repo_id = ?").get(args.id, repoId)
-                        : store.db.prepare("SELECT doc_id FROM docs WHERE repo_id = ? AND path = ?").get(repoId, storagePath(args.path)))
+                    ? (args._id !== undefined
+                        ? store.db.prepare("SELECT doc_id FROM docs WHERE doc_id = ? AND repo_id = ?").get(args._id, repoId)
+                        : store.db.prepare("SELECT doc_id FROM docs WHERE repo_id = ? AND path = ?").get(repoId, storagePath(args._path)))
                     : undefined;
                 doc = tomb ? tomb.doc_id : locateDoc(repoId, "docs_history", registry.get("docs_history").shape, args);
             }
@@ -1254,7 +1316,7 @@ export function buildServer(ctx) {
         }
     });
     tool("changes_since", {
-        description: ladder("changes_since — Re-orient after time away: the commit feed after a cursor, each digest with its revisions [{ id, path, hash }].", "{}   everything from the start; head is the current max seq", "{\"cursor\":20,\"limit\":5}   commits after seq 20, five at a time (cursor pages while truncated)", "{\"origin\":\"api\"}   only the writes made through the engine (observed = edits on disk; import)", "Poll with your last cursor: an empty page with cursor == head means nothing new. Read a changed document with docs_read, its blocks with query (grammar: query_syntax)."),
+        description: ladder("changes_since — Re-orient after time away: the commit feed after a cursor, each digest with its revisions [{ _id, _path, _hash }].", "{}   everything from the start; head is the current max seq", "{\"cursor\":20,\"limit\":5}   commits after seq 20, five at a time (cursor pages while truncated)", "{\"origin\":\"api\"}   only the writes made through the engine (observed = edits on disk; import)", "Poll with your last cursor: an empty page with cursor == head means nothing new. Read a changed document with docs_read, its blocks with query (grammar: query_syntax)."),
         inputSchema: { cursor: z.number().int().optional(), origin: z.enum(["api", "observed", "import"]).optional(), limit: z.number().int().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
@@ -1270,7 +1332,7 @@ export function buildServer(ctx) {
         }
     });
     tool("repos_status", {
-        description: "Repo counts (`{ id, slug, rootPath, docs, blocks, commits, openEdges, unconverged, disk }`): docs, blocks, commits, open edges, unconverged doc count, and on-disk drift. " +
+        description: "Repo counts (`{ _id, slug, rootPath, docs, blocks, commits, openEdges, unconverged, disk }` — `_id` is the root row's id): docs, blocks, commits, open edges, unconverged doc count, and on-disk drift. " +
             "`disk` reports a READ-ONLY scan of the working tree vs the DB: `changed` (files edited on disk but not re-ingested), " +
             "`deleted` (docs whose file is gone from disk), `untracked` (new *.md not yet ingested), and `checked` " +
             "(false when the server has no working-tree path — disk agreement is then UNVERIFIED, not clean).",