omgbase 0.10.0 → 0.11.0

package/README.md

@@ -182,7 +182,7 @@ The global `--server <cmd|url>` flag runs the same command against a **remote en
 Global flags are recognized anywhere on the line: `-C <dir>`, `--repo <slug>`, `--json`, `--jsonl`, `--ids`, `--stale`, `--no-color`, `--dry-run`, `--server <cmd|url>`, `-H <header>`, `--help`/`-h`, `--version`/`-V`.
 
 - Human output (default) is colorized on a TTY; `--no-color`, `NO_COLOR`, or a pipe degrades to plain text.
-- Query hits (`omg q`, `omg run`) print as `<id>  <path>` lines. When the query projects (`select …`), they print as an aligned table instead: a dim header row, the id first, then the path (unless the projection itself selects `$path`), then the projected columns in `select` order. Strings and numbers are verbatim, an absent field is an empty cell, and a nested list/record is compact JSON clipped at 60 characters with `…`; `--jsonl` has the full values.
+- Query hits (`omg q`, `omg run`) print as `<id>  <path>` lines. When the query projects (`select …`), they print as an aligned table instead: a dim header row, the id first, then the path (unless the projection itself selects `path`), then the projected columns in `select` order. Strings and numbers are verbatim, an absent field is an empty cell, and a nested list/record is compact JSON clipped at 60 characters with `…`; `--jsonl` has the full values.
 - `--json` prints the library's result object verbatim as one JSON document (the same shape the MCP tools return). `--jsonl` flattens list results to one object per line; `--ids` prints bare ids/paths, one per line — pipe fuel for `omg cat -`, `omg show -`, `omg done -`.
 - `--dry-run` is global across every mutator: full validation and render, diffs printed, nothing committed.
 - Errors always go to stderr: `error[<code>]: <message>` plus any conflict payload, or the typed error object as JSON with `--json`.

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "d2df0ed",
-  "built": "2026-10-10T07:57:27.728Z"
+  "commit": "0145153",
+  "built": "2026-10-12T05:05:42.833Z"
 }

package/dist/src/cmd/_mutate.d.ts

@@ -38,7 +38,7 @@ export interface RunOpsOptions {
 export declare function runOps(cli: Cli, ws: Workspace, repo: RepoRow, ops: Op[], opts?: RunOpsOptions): number;
 /**
  * Remote peer of runOps: call the changeset-producing tool that mirrors this
- * command (blocks_insert, tasks_complete, …) against the `--server` engine — the
+ * command (blocks_insert, blocks_check, …) against the `--server` engine — the
  * server resolves refs + pins CAS + applies — then render the returned
  * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
  * tool's dry_run so the preview comes back without committing.

package/dist/src/cmd/_mutate.js

@@ -142,7 +142,7 @@ export function runOps(cli, ws, repo, ops, opts = {}) {
 }
 /**
  * Remote peer of runOps: call the changeset-producing tool that mirrors this
- * command (blocks_insert, tasks_complete, …) against the `--server` engine — the
+ * command (blocks_insert, blocks_check, …) against the `--server` engine — the
  * server resolves refs + pins CAS + applies — then render the returned
  * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
  * tool's dry_run so the preview comes back without committing.

package/dist/src/cmd/_remote.d.ts

@@ -1,4 +1,5 @@
 import { type EngineSpec } from "@omgbase/sync";
+import { type Store } from "@omgbase/core";
 import type { Cli } from "../context.js";
 /** Classify the global `--server` (+ `-H`) flags into an `EngineSpec`: an
  *  http(s) URL → Streamable HTTP with the headers attached; anything else → a
@@ -10,6 +11,21 @@ export declare function remoteSpec(cli: Cli): EngineSpec;
  *  Returns the tool's parsed JSON result (same shape the local core fn returns,
  *  so the command's existing renderer works unchanged). */
 export declare function remoteCall<T>(cli: Cli, tool: string, args: Record<string, unknown>): Promise<T>;
+/** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
+ *  a `d_` id is the `id` argument, anything else the `path` — the two names a
+ *  `docs_*` tool takes (one of them required). */
+export declare function docLocator(ref: string): {
+    id: string;
+} | {
+    path: string;
+};
+/** The live document a ref names, for a LOCAL verb, or the surface's own
+ *  `doc_missing` ("no document with id or path "<ref>"", `data` the locator) —
+ *  the same wording the `docs_*` tools give a remote caller (spec/surface §4
+ *  "Arguments"), so `omg mv nope.md …` reads alike in both modes. */
+export declare function requireDoc(store: Store, repoId: string, ref: string): string;
+/** The live node a ref names, or the surface's `block_missing` ("no node with id "<ref>""). */
+export declare function requireNode(store: Store, repoId: string, nodeId: string): string;
 /** Close the remote connection if one was opened (idempotent). Called after a
  *  one-shot command and on shell exit. */
 export declare function closeRemote(): Promise<void>;

package/dist/src/cmd/_remote.js

@@ -1,5 +1,6 @@
 import { connectEngine, parseEngineSpec } from "@omgbase/sync";
-import { CliUsageError } from "../output.js";
+import { isValidId, findDocByRef } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike } from "../output.js";
 // Remote (`--server`) mode plumbing (ADR-014). When a command runs with the
 // global `--server <cmd|url>` flag, it reaches a remote engine over MCP instead
 // of the embedded local store: it calls the MCP tool that mirrors its local
@@ -56,6 +57,29 @@ export async function remoteCall(cli, tool, args) {
     const eng = await remoteEngine(cli);
     return eng.callTool(tool, { ...args, ...(cli.flags.repo ? { repo: cli.flags.repo } : {}) });
 }
+/** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
+ *  a `d_` id is the `id` argument, anything else the `path` — the two names a
+ *  `docs_*` tool takes (one of them required). */
+export function docLocator(ref) {
+    return isValidId(ref, "d") ? { id: ref } : { path: ref };
+}
+/** The live document a ref names, for a LOCAL verb, or the surface's own
+ *  `doc_missing` ("no document with id or path "<ref>"", `data` the locator) —
+ *  the same wording the `docs_*` tools give a remote caller (spec/surface §4
+ *  "Arguments"), so `omg mv nope.md …` reads alike in both modes. */
+export function requireDoc(store, repoId, ref) {
+    const info = findDocByRef(store, repoId, ref);
+    if (!info)
+        throw new EngineErrorLike("doc_missing", `no document with id or path ${JSON.stringify(ref)}`, { data: docLocator(ref) });
+    return info.docId;
+}
+/** The live node a ref names, or the surface's `block_missing` ("no node with id "<ref>""). */
+export function requireNode(store, repoId, nodeId) {
+    const row = store.db.prepare("SELECT 1 FROM nodes WHERE node_id = ? AND repo_id = ?").get(nodeId, repoId);
+    if (!row)
+        throw new EngineErrorLike("block_missing", `no node with id ${JSON.stringify(nodeId)}`, { data: { id: nodeId } });
+    return nodeId;
+}
 /** Close the remote connection if one was opened (idempotent). Called after a
  *  one-shot command and on shell exit. */
 export async function closeRemote() {

package/dist/src/cmd/cat.d.ts

@@ -1,2 +1,11 @@
 import type { Command } from "../commands.js";
+/** A ref that names a block: a `b_` block id, an `n_` node id (its block), or a
+ *  `path#type[n]` locator — everything else is a document (a `d_` id or a path). */
+export declare function isBlockRef(ref: string): boolean;
+/** The remote tool that reads the block a ref names, by the ref's SHAPE (ids
+ *  carry their kind, spec/surface §4 "Names and arguments"): an `n_` node id is
+ *  `nodes_block_read` (the block the node was projected from — `blocks_read`'s
+ *  shape; `blocks_read` itself takes a block id only), a `b_` id or a
+ *  `path#type[n]` locator is `blocks_read`, anything else is a document (null). */
+export declare function blockReadTool(ref: string): "nodes_block_read" | "blocks_read" | null;
 export declare const cmdCat: Command;

package/dist/src/cmd/cat.js

@@ -1,8 +1,37 @@
 import { parseArgs } from "node:util";
 import { resolveRef, nodesGet, docsRead } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, docLocator } from "./_remote.js";
 import { expandBlockArgs } from "./_mutate.js";
+// `omg cat <node…|->` (11 §5.2) — content only, default raw exact bytes, pipe-clean.
+// For a document ref, cats the whole rendered document; for a block, the block
+// (subtree at raw). No decoration on stdout: cat is the bytes. Several refs (or
+// `-` = refs from stdin, one per line — the counterpart of `--ids`, same
+// convention as the mutators) are cat'ed in order, like unix cat. `--json` is
+// the mapped tool's result: `docs_read` for a document, `blocks_read` for a block,
+// `nodes_block_read` for a node (the block it was projected from — the same shape).
+//
+// Refs are what `resolveRef` accepts: a block/doc/node id or a document path
+// in either form (`/notes/x.md`, `notes/x.md`). `--resolution` is a block-level notion (blocks_read); a document
+// is always its exact bytes (docs_read has no resolution ladder), so asking for
+// another resolution on a document ref is warned about, not silently ignored.
+/** A ref that names a block: a `b_` block id, an `n_` node id (its block), or a
+ *  `path#type[n]` locator — everything else is a document (a `d_` id or a path). */
+export function isBlockRef(ref) {
+    return blockReadTool(ref) !== null;
+}
+/** The remote tool that reads the block a ref names, by the ref's SHAPE (ids
+ *  carry their kind, spec/surface §4 "Names and arguments"): an `n_` node id is
+ *  `nodes_block_read` (the block the node was projected from — `blocks_read`'s
+ *  shape; `blocks_read` itself takes a block id only), a `b_` id or a
+ *  `path#type[n]` locator is `blocks_read`, anything else is a document (null). */
+export function blockReadTool(ref) {
+    if (ref.startsWith("n_"))
+        return "nodes_block_read";
+    if (ref.startsWith("b_") || ref.includes("#"))
+        return "blocks_read";
+    return null;
+}
 /** `--resolution` only means something for a block; say so (stderr) rather than
  *  silently handing back raw bytes as if the flag had applied. */
 function warnDocResolution(cli, ref, resolution) {
@@ -11,17 +40,21 @@ function warnDocResolution(cli, ref, resolution) {
     cli.io.err(cli.style.warn(`  --resolution ${resolution} ignored for ${ref}: a document is always its exact bytes (resolutions apply to block refs)`));
 }
 async function catOne(cli, ref, resolution) {
-    // Remote: the polymorphic `read_ref` tool classifies + reads server-side.
+    // Remote: the ref's SHAPE picks the tool (ids carry their kind, a path is a
+    // document): an `n_` node id is `nodes_block_read` (the block it was projected
+    // from), a `b_` id or a `path#type[n]` locator is `blocks_read` (a block id
+    // only — an `n_` id there is `block_missing`), a `d_` id or a path is
+    // `docs_read` — the same results the local run renders (`read_ref` classified
+    // server-side before surface 3.0).
     if (cli.flags.server) {
-        const r = await remoteCall(cli, "read_ref", { ref, ...(resolution !== "raw" ? { resolution } : {}) });
-        if (r.kind === "document") {
-            warnDocResolution(cli, ref, resolution);
-            // The `docs_read` result is the `read_ref` document result without `kind`.
-            const { kind: _kind, ...doc } = r;
-            void _kind;
-            return { text: String(r.content ?? ""), json: doc, capture: r.content };
+        const tool = blockReadTool(ref);
+        if (tool) {
+            const r = await remoteCall(cli, tool, { id: ref, resolution });
+            return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
         }
-        return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
+        const r = await remoteCall(cli, "docs_read", docLocator(ref));
+        warnDocResolution(cli, ref, resolution);
+        return { text: String(r.raw ?? ""), json: r, capture: r.raw };
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -39,7 +72,7 @@ async function catOne(cli, ref, resolution) {
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         warnDocResolution(cli, ref, resolution);
         // shell: the bytes (a string; @_ only). `--json` is the `docs_read` result.
-        return { text: res.content, json: res, capture: res.content };
+        return { text: res.raw, json: res, capture: res.raw };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution });
     if (!node)

package/dist/src/cmd/diff.js

@@ -1,8 +1,8 @@
 import { parseArgs } from "node:util";
 import { findDoc, docDiffUnified, diffBlocks } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
-import { remoteCall } from "./_remote.js";
-// `omg diff <doc>` (11 §5.5) — `diff_unified`: the unified diff, `--json` the
+import { remoteCall, docLocator } from "./_remote.js";
+// `omg diff <doc>` (11 §5.5) — `docs_diff_unified`: the unified diff, `--json` the
 // tool's `{ doc, path, from, to, diff }`. With no revisions: current vs previous
 // ("what did the last commit do here"). `--blocks` is the block-grain `diff`
 // tool: added/removed/changed blocks between the same two revisions.
@@ -20,7 +20,7 @@ async function runDiff(cli, args) {
             options: [
                 ["--from <rev>", "older revision id (default: the one before --to)"],
                 ["--to <rev>", "newer revision id (default: current)"],
-                ["--blocks", "block-grain: which blocks were added, removed or changed (the `diff` tool)"],
+                ["--blocks", "block-grain: which blocks were added, removed or changed (the `docs_diff` tool)"],
             ],
         });
     }
@@ -29,8 +29,8 @@ async function runDiff(cli, args) {
         throw new CliUsageError("diff requires a <doc>");
     let result;
     if (cli.flags.server) {
-        result = await remoteCall(cli, "diff_unified", {
-            doc: ref,
+        result = await remoteCall(cli, "docs_diff_unified", {
+            ...docLocator(ref),
             ...(values.from ? { from_rev: values.from } : {}),
             ...(values.to ? { to_rev: values.to } : {}),
         });
@@ -52,11 +52,11 @@ async function runDiff(cli, args) {
         // Block-grain over the same resolved revision pair.
         let entries;
         if (cli.flags.server)
-            entries = await remoteCall(cli, "diff", { doc: ref, from_rev: result.from, to_rev: result.to });
+            entries = await remoteCall(cli, "docs_diff", { ...docLocator(ref), from_rev: result.from, to_rev: result.to });
         else
-            entries = diffBlocks(cli.workspace().store, result.doc, result.from, result.to);
+            entries = diffBlocks(cli.workspace().store, result.id, result.from, result.to);
         if (cli.flags.mode !== "human")
-            return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e.blockId) });
+            return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e.id) });
         if (entries.length === 0) {
             io.err(style.dim("  no changes"));
             return EXIT_OK;
@@ -64,7 +64,7 @@ async function runDiff(cli, args) {
         for (const e of entries) {
             const mark = e.kind === "added" ? style.ok("+") : e.kind === "removed" ? style.err("-") : style.warn("~");
             const preview = (e.after ?? e.before ?? "").split("\n")[0] ?? "";
-            io.out(`${mark} ${style.id(e.blockId)}  ${preview}`.trimEnd());
+            io.out(`${mark} ${style.id(e.id)}  ${preview}`.trimEnd());
         }
         return EXIT_OK;
     }

package/dist/src/cmd/docs.js

@@ -3,14 +3,15 @@ import { parse as parseYamlScalar } from "yaml";
 import { docsCreate, docsMove, docsDelete, docsSetMeta, surfaceDocOpResult, surfaceDocMoveResult, referencePath } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts, renderDiffs } from "./_mutate.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, docLocator, requireDoc } from "./_remote.js";
 // Document-level commands (11 §5.6): new / mv / rm --doc / meta. Thin wrappers
 // over the core doc ops, which own the file-write + commit + flock protocol.
 // The global --dry-run rides as the op's `dryRun` (spec/cli §3.6): the op
 // validates and returns the per-file diffs it would make, committing nothing.
-// Every path printed is the reference form (spec/surface §1 "Paths"): the
-// library's result is re-shaped through `surfaceDocOpResult` — the same
-// function the MCP server applies — before it is rendered.
+// Every path printed is the reference form (spec/surface §1 "Paths") and the
+// result's identity is `id`/`path` (3.0): the library's result is re-shaped
+// through `surfaceDocOpResult` — the same function the MCP server applies —
+// before it is rendered, so the CLI and the tool print one shape.
 function ctxOf(cli, ws, repoId, rootPath, actor) {
     return {
         repoId,
@@ -30,7 +31,7 @@ function report(cli, verb, res) {
         return EXIT_OK;
     }
     cli.io.err(cli.style.dim(`  ${cli.style.ok(cli.render.g.ok)} ${verb} ${cli.style.accent(res.path)}`));
-    cli.io.out(res.docId);
+    cli.io.out(res.id);
     return EXIT_OK;
 }
 // `mv` rewrites the inbound links by default (spec/mutate 1.3; `--no-retarget`
@@ -51,14 +52,14 @@ function reportMove(cli, from, res) {
     }
     if (res.dangling.length === 0)
         return code;
-    const where = res.dangling.map((l) => (l.block ? `${l.path} ${l.block}` : `${l.path} (frontmatter)`)).join(", ");
+    const where = res.dangling.map((l) => (l.block_id ? `${l.path} ${l.block_id}` : `${l.path} (frontmatter)`)).join(", ");
     const n = res.dangling.length;
     io.err(style.warn(`  ${style.warn(cli.render.g.warn)} ${n} inbound link${n === 1 ? "" : "s"} still name${n === 1 ? "s" : ""} the old path: ${where}`));
-    if (res.dangling.some((l) => l.block))
+    if (res.dangling.some((l) => l.block_id))
         io.err(style.dim(`  fix: ${cli.prog} retarget ${from} ${res.path} --apply`));
     const seen = new Set();
     for (const l of res.dangling) {
-        if (l.block || !l.field)
+        if (l.block_id || !l.field)
             continue;
         const key = `${l.path}\u0000${l.field}`;
         if (seen.has(key))
@@ -125,22 +126,22 @@ async function runMv(cli, args) {
         throw new CliUsageError("mv requires <doc> and <new-path>");
     const noRetarget = values["no-retarget"] === true;
     if (cli.flags.server) {
-        const res = await remoteCall(cli, "docs_move", { doc, to_path: toPath, ...(noRetarget ? { retarget_inbound: false } : {}), ...dryRunArg(cli) });
+        const res = await remoteCall(cli, "docs_move", { ...docLocator(doc), to_path: toPath, ...(noRetarget ? { retarget_inbound: false } : {}), ...dryRunArg(cli) });
         return reportMove(cli, fromPathOf(res, doc), res);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = surfaceDocMoveResult(docsMove(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, toPath, noRetarget ? { retargetInbound: false } : {}));
+    const res = surfaceDocMoveResult(docsMove(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), requireDoc(ws.store, repo.repoId, doc), toPath, noRetarget ? { retargetInbound: false } : {}));
     return reportMove(cli, fromPathOf(res, doc), res);
 }
 // ---- rm --doc (block rm lives in mutate.ts; this handles the --doc branch) --
 export async function runRmDoc(cli, doc, actor) {
     if (cli.flags.server) {
-        return report(cli, "deleted", await remoteCall(cli, "docs_delete", { doc, ...dryRunArg(cli) }));
+        return report(cli, "deleted", await remoteCall(cli, "docs_delete", { ...docLocator(doc), ...dryRunArg(cli) }));
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = surfaceDocOpResult(docsDelete(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, actor), doc));
+    const res = surfaceDocOpResult(docsDelete(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, actor), requireDoc(ws.store, repo.repoId, doc)));
     return report(cli, "deleted", res);
 }
 // ---- meta -------------------------------------------------------------------
@@ -193,7 +194,7 @@ async function runMeta(cli, args) {
         throw new CliUsageError("meta requires --set or --unset");
     if (cli.flags.server) {
         return report(cli, "patched", await remoteCall(cli, "docs_set_meta", {
-            doc,
+            ...docLocator(doc),
             ...(Object.keys(set).length ? { set } : {}),
             ...(unset.length ? { unset } : {}),
             ...dryRunArg(cli),
@@ -201,7 +202,7 @@ async function runMeta(cli, args) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = surfaceDocOpResult(docsSetMeta(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, { set, unset }));
+    const res = surfaceDocOpResult(docsSetMeta(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), requireDoc(ws.store, repo.repoId, doc), { set, unset }));
     return report(cli, "patched", res);
 }
 function dryRunArg(cli) {

package/dist/src/cmd/edit.js

@@ -37,7 +37,7 @@ function runEdit(cli, args) {
     const repo = cli.repo(ws);
     const resolved = resolveRef(ws.store, repo.repoId, ref);
     if (!resolved || resolved.kind !== "block")
-        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
     const blockId = resolved.blockId;
     const node = nodesGet(ws.store, resolved.docId, blockId, { resolution: "raw" });
     const before = node?.raw ?? "";

package/dist/src/cmd/find.js

@@ -36,9 +36,9 @@ async function runFind(cli, args) {
     const limit = values.one ? 1 : values.n ? Number(values.n) : 10;
     let hits;
     if (cli.flags.server) {
-        // Remote: the `resolve` tool does the hybrid ranking server-side (using the
+        // Remote: the `blocks_resolve` tool does the hybrid ranking server-side (using the
         // server's embedder if configured). Same ranked-hit shape → render unchanged.
-        hits = await remoteCall(cli, "resolve", { query: text, limit });
+        hits = await remoteCall(cli, "blocks_resolve", { query: text, limit });
     }
     else {
         const ws = cli.workspace();

package/dist/src/cmd/hist.js

@@ -2,7 +2,7 @@ import { parseArgs } from "node:util";
 import { resolveRef, historyNode } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
-// `omg hist <node>` (11 §5.5) — history_node: a block's biography.
+// `omg hist <node>` (11 §5.5) — blocks_history: a block's biography.
 async function runHist(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -22,9 +22,9 @@ async function runHist(cli, args) {
         throw new CliUsageError("hist requires a <node>");
     let changes;
     if (cli.flags.server) {
-        // Remote: history_node keys on a block id (globally unique). Pass the ref
+        // Remote: blocks_history keys on a block id (globally unique). Pass the ref
         // through — a locator would need a local resolve, so remote hist wants an id.
-        changes = await remoteCall(cli, "history_node", { id: ref, ...(values.n ? { limit: Number(values.n) } : {}) });
+        changes = await remoteCall(cli, "blocks_history", { id: ref, ...(values.n ? { limit: Number(values.n) } : {}) });
     }
     else {
         const ws = cli.workspace();

package/dist/src/cmd/links.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { resolveRef, docLinks } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
-// `omg links <node>` (11 §5.4) — open edges touching the node; default both
+// `omg links <node>` (11 §5.4) — open links touching the node; default both
 // directions, grouped; doc-grain by default, --blocks for block-grain (one row
 // per edge, naming the source block). Backlinks = --in.
 function runLinks(cli, args) {
@@ -19,13 +19,13 @@ function runLinks(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "links",
-            summary: "Open edges touching a node, grouped by predicate (both directions by default)",
+            summary: "Open links touching a node, grouped by predicate (both directions by default)",
             usage: "links <node> [--in|--out] [--pred <p,p>] [--blocks]",
             options: [
-                ["--in", "incoming edges only (backlinks)"],
-                ["--out", "outgoing edges only"],
+                ["--in", "incoming links only (backlinks)"],
+                ["--out", "outgoing links only"],
                 ["--pred <p,p>", "keep only these predicates"],
-                ["--blocks", "block-grain edges (default: doc-grain)"],
+                ["--blocks", "block-grain links (default: doc-grain)"],
             ],
         });
     }
@@ -47,7 +47,7 @@ function runLinks(cli, args) {
     cli.capture?.(result); // shell: edges (out+in) become the addressable frame
     // `{ out, in }` is not a list: `--jsonl` prints the document; `--ids` the far nodes.
     if (cli.flags.mode !== "human")
-        return emitMachine(cli, result, { ids: [...result.out, ...result.in].map((e) => e.node) });
+        return emitMachine(cli, result, { ids: [...result.out, ...result.in].map((e) => e.doc_id) });
     const { render, style, io } = cli;
     const g = render.g;
     if (result.out.length === 0 && result.in.length === 0) {
@@ -56,26 +56,26 @@ function runLinks(cli, args) {
     }
     // Doc-grain: one row per (predicate, node) with its rollup count. Block-grain:
     // one row per edge, the source block beside the far node.
-    const src = (e) => style.dim(`(${e.block ?? "frontmatter"})`);
+    const src = (e) => style.dim(`(${e.block_id ?? "frontmatter"})`);
     if (result.out.length > 0) {
         io.out(style.dim("  out"));
         for (const e of result.out) {
             if (values.blocks)
-                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.node)} ${src(e)}`);
+                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.doc_id)} ${src(e)}`);
             else
-                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.node)} ${style.dim(`×${e.count}`)}`);
+                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.doc_id)} ${style.dim(`×${e.count}`)}`);
         }
     }
     if (result.in.length > 0) {
         io.out(style.dim("  in (backlinks)"));
         for (const e of result.in) {
             if (values.blocks)
-                io.out(`    ${style.id(e.node)} ${src(e)} ${style.dim(g.arrow)} ${style.accent(e.predicate)}`);
+                io.out(`    ${style.id(e.doc_id)} ${src(e)} ${style.dim(g.arrow)} ${style.accent(e.predicate)}`);
             else
-                io.out(`    ${style.id(e.node)} ${style.dim(g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+                io.out(`    ${style.id(e.doc_id)} ${style.dim(g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
         }
     }
     return EXIT_OK;
 }
-export const cmdLinks = { name: "links", summary: "Open edges touching a node", run: (cli, a) => runLinks(cli, a) };
+export const cmdLinks = { name: "links", summary: "Open links touching a node", run: (cli, a) => runLinks(cli, a) };
 //# sourceMappingURL=links.js.map

package/dist/src/cmd/ls.js

@@ -38,9 +38,11 @@ async function runLs(cli, args) {
         rows.push(...page.items);
         cursor = page.truncated ? page.cursor : null;
     } while (cursor);
-    cli.capture?.(rows); // shell: docs become the addressable frame (ref = path)
+    cli.capture?.(rows); // shell: docs become the addressable frame (ref = id, label path)
+    // `--ids` prints the documents' `id`s (spec/cli 3.0; the paths before, a
+    // stand-in for an identity the row did not carry).
     if (cli.flags.mode !== "human")
-        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r.path) });
+        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r.id) });
     const { style, io } = cli;
     if (rows.length === 0) {
         io.err(style.dim("  no documents"));
@@ -49,7 +51,7 @@ async function runLs(cli, args) {
     const table = rows.map((r) => [
         style.accent(r.path),
         style.dim(`${r.blocks} blocks`),
-        style.dim(relTime(r.ts)),
+        style.dim(relTime(r.updated_at)),
     ]);
     for (const line of columns(table, [{}, { align: "right" }, { align: "right" }]))
         io.out(line);

package/dist/src/cmd/mcp.js

@@ -65,7 +65,7 @@ async function runMcp(cli, args) {
     const repo = cli.repo(ws);
     // Connect the configured embedder once (if any) so the query tool's
     // `semantic` mode has a vectorizer for the session. Unset ⇒ semantic queries
-    // return semantic_unavailable. The spawned process lives for the session and
+    // return provider_unavailable. The spawned process lives for the session and
     // is released on shutdown.
     //
     // A CONFIGURED-but-broken embedder must never be mistaken for "no embedder":
@@ -151,7 +151,7 @@ async function runMcp(cli, args) {
     // The query surface's `embedQuery`: a live vectorizer when the embedder loaded,
     // or — when it's configured-but-broken — a hook that throws `embedder_failed`
     // so semantic access fails loudly and specifically (not the misleading
-    // `semantic_unavailable`, which the server emits only when embedQuery is
+    // `provider_unavailable`, which the server emits only when embedQuery is
     // absent, i.e. genuinely no provider configured). `const` captures satisfy
     // closure narrowing over the `let`-bound state above.
     const loaded = embedding;
@@ -167,6 +167,7 @@ async function runMcp(cli, args) {
         ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
         ...(drainer ? { onMutation: () => drainer.schedule() } : {}),
         ...(embedQuery ? { embedQuery } : {}),
+        ...(loaded ? { embedProvider: loaded.providerName } : {}),
         // The `version` tool's view of this binary (spec/surface §4).
         host: hostInfo(),
     });

package/dist/src/cmd/mutate.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
-import { resolveRef, tasksComplete, sectionsAppend, } from "@omgbase/core";
+import { resolveRef, tasksComplete, sectionsAppend, isContainerBlock, } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, renderHelp } from "../output.js";
 import { runOps, runOpsRemote, readContent, readStdin, expandBlockArgs, extractContentOpts } from "./_mutate.js";
 import { runRmDoc } from "./docs.js";
@@ -10,7 +10,7 @@ import { runRmDoc } from "./docs.js";
 function block(cli, ws, repoId, ref) {
     const r = resolveRef(ws.store, repoId, ref);
     if (!r || r.kind !== "block")
-        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
     return r.blockId;
 }
 // `done` addresses task blocks only (spec/cli §6): any other live block type is
@@ -21,7 +21,7 @@ function taskBlock(ws, ref, blockId) {
         .prepare("SELECT type FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
         .get(blockId);
     if (!row)
-        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
     if (row.type !== "task") {
         throw new EngineErrorLike("type_mismatch", `not a task: ${ref} is a ${row.type}`, { data: { block: blockId, type: row.type } });
     }
@@ -141,7 +141,7 @@ async function runUpdate(cli, args) {
     const markdown = readContent(content);
     // Remote: the server pins CAS from current bytes when --expect is absent.
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_update", { block: ref, markdown, ...(values.expect ? { expect: { content_hash: values.expect } } : {}) });
+        return runOpsRemote(cli, "blocks_update", { id: ref, markdown, ...(values.expect ? { expect: { content_hash: values.expect } } : {}) });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);
@@ -226,7 +226,7 @@ async function runRm(cli, args) {
     const op = { op: "remove", blocks };
     return runOps(cli, ws, repo, [op], actorOf(values));
 }
-// ---- done (tasks_complete) --------------------------------------------------
+// ---- done (blocks_check) --------------------------------------------------
 async function runDone(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -249,7 +249,7 @@ async function runDone(cli, args) {
     if (refs.length === 0)
         throw new CliUsageError("done requires one or more task blocks (or - for stdin)");
     if (cli.flags.server)
-        return runOpsRemote(cli, "tasks_complete", { blocks: refs, ...(values.undo ? { checked: false } : {}) });
+        return runOpsRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => taskBlock(ws, r, block(cli, ws, repo.repoId, r)));
@@ -258,7 +258,7 @@ async function runDone(cli, args) {
         : tasksComplete(ws.store, blocks);
     return runOps(cli, ws, repo, ops, actorOf(values));
 }
-// ---- append (sections_append) -----------------------------------------------
+// ---- append (blocks_append) --------------------------------------------------
 async function runAppend(cli, args) {
     const content = extractContentOpts(args);
     const { values, positionals } = parseArgs({
@@ -269,10 +269,10 @@ async function runAppend(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "append",
-            summary: "Append markdown at the end of a heading's section",
-            usage: "append <heading> (-m <markdown> | -f <file> | -) [--actor <s>] [--dry-run]",
+            summary: "Append markdown into a block: a heading's section or a container's children",
+            usage: "append <block> (-m <markdown> | -f <file> | -) [--actor <s>] [--dry-run]",
             options: [
-                ["<heading>", "the heading block (id or locator) whose section receives the content"],
+                ["<block>", "a heading (its section receives the content) or a container — list, item, quote, table (its children do)"],
                 ["-m <markdown>", "content inline"],
                 ["-f <file>", "content from a file"],
                 ["-", "content from stdin"],
@@ -280,17 +280,34 @@ async function runAppend(cli, args) {
             ],
         });
     }
-    const heading = positionals[0];
-    if (!heading)
-        throw new CliUsageError("append requires a <heading> block");
+    const target = positionals[0];
+    if (!target)
+        throw new CliUsageError("append requires a <block>");
     const markdown = readContent(content);
-    // Remote: sections_append resolves the heading ref (id OR text) server-side.
+    // Remote: blocks_append resolves the ref and decides by the block's kind
+    // server-side (spec/surface §4).
     if (cli.flags.server)
-        return runOpsRemote(cli, "sections_append", { heading, markdown });
+        return runOpsRemote(cli, "blocks_append", { id: target, text: markdown });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const headingId = block(cli, ws, repo.repoId, heading);
-    return runOps(cli, ws, repo, sectionsAppend(headingId, markdown), actorOf(values));
+    const blockId = block(cli, ws, repo.repoId, target);
+    return runOps(cli, ws, repo, appendOps(ws.store, blockId, markdown), actorOf(values));
+}
+/** The ops `blocks_append` expands to, by what the block is: a heading → the end
+ *  of its section (`sectionsAppend`); a container → the end of its children; a
+ *  leaf → `block_not_container` (append means into, never a sibling insert). */
+function appendOps(store, blockId, markdown) {
+    const row = store.db
+        .prepare("SELECT b.type AS type, d.format AS format, (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(blockId);
+    if (!row)
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(blockId)}`, { data: { id: blockId } });
+    if (row.type === "heading")
+        return sectionsAppend(blockId, markdown);
+    if (isContainerBlock(row.format ?? "markdown", { type: row.type, children: new Array(row.children) })) {
+        return [{ op: "insert", to: { parent: blockId, at: "end" }, markdown }];
+    }
+    throw new EngineErrorLike("block_not_container", `block ${blockId} 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(blockId)} } }`, { data: { id: blockId, type: row.type } });
 }
 // ---- split / merge ----------------------------------------------------------
 async function runSplit(cli, args) {
@@ -324,7 +341,7 @@ async function runSplit(cli, args) {
         return n;
     });
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_split", { block: ref, at });
+        return runOpsRemote(cli, "blocks_split", { id: ref, at });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);

package/dist/src/cmd/node.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
 import { nodeSet, editablePropsFor } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { requireNode } from "./_remote.js";
 import { runOps, runOpsRemote } from "./_mutate.js";
 // `omg node set <nodeId> <prop> <value>` (node-editability) — surgically set an
 // editable property of a projected node (e.g. a link's text/target, a task's
@@ -37,13 +38,13 @@ async function runNode(cli, args) {
         if (!nodeId || !prop || valueParts.length === 0)
             throw new CliUsageError("node set <nodeId> <prop> <value>");
         const value = valueParts.join(" ");
-        // Remote: node_set resolves node → block + rewrites the span server-side.
+        // Remote: nodes_set resolves node → block + rewrites the span server-side.
         if (cli.flags.server)
-            return runOpsRemote(cli, "node_set", { node: nodeId, prop, value });
+            return runOpsRemote(cli, "nodes_set", { id: nodeId, prop, value });
         const ws = cli.workspace();
         const repo = cli.repo(ws);
-        const ops = nodeSet(ws.store, nodeId, prop, value);
-        return runOps(cli, ws, repo, ops, { reason: `node_set ${prop}`, ...(values.actor ? { actor: values.actor } : {}) });
+        const ops = nodeSet(ws.store, requireNode(ws.store, repo.repoId, nodeId), prop, value);
+        return runOps(cli, ws, repo, ops, { reason: `nodes_set ${prop}`, ...(values.actor ? { actor: values.actor } : {}) });
     }
     if (sub === "props") {
         // `props` is a local editability lookup with no remote tool (a niche read).

package/dist/src/cmd/oqx.js

@@ -23,7 +23,7 @@ import { readStdin } from "./_mutate.js";
 // query to a parent binding, the root row's collections ^docs/^nodes/^blocks for
 // join-equivalents, first/single lookups, full-text text(...) + embedding-score
 // semantic(...) predicates, `order by <expr> [asc|desc]` ranking, and recursive
-// `follow [distinct] <rel> [{ where … frontier … depth n by … }]` traversal over
+// `follow [distinct] <rel> [{ where … frontier … depth n }]` traversal (a brace after a destination is its block, oqx 0.20) over
 // a type-preserving relation with $depth/$stop/$ordinal recursion metadata +
 // post-walk filtering. A top-level consumer directive changes the result shape:
 // `docs count { … }` / `docs exists { … }` reduce to a scalar,
@@ -46,7 +46,7 @@ async function runOqx(cli, args) {
     if (values.help) {
         renderHelp(cli, {
             name: "query",
-            summary: "Composable OQX query: from <docs|blocks|nodes|edges> where … select … [order by …] [follow …] (alias: q)",
+            summary: "Composable OQX query: from <docs|blocks|nodes|links> where … select … [order by …] [follow …] (alias: q)",
             usage: ["query <source> [-n <N>] [--cursor <c>] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>]"],
             options: [
                 ["<source>", "the OQX query text (quote it); `from` may be omitted inside blocks"],
@@ -63,23 +63,28 @@ async function runOqx(cli, args) {
         });
         cli.io.out("  e.g. query 'from docs where nodes count { where kind == \"md:task\" } >= 2'");
         cli.io.out("       query 'select items: section.blocks collect { where type == \"list_item\" } from nodes where kind == \"md:section\"'");
-        cli.io.out("       query 'select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !attrs.checked }'");
-        cli.io.out("       query 'select owner_id, owner: ^nodes single { where kind == \"person\" && attrs.id == ^owner_id } from docs'   # ^docs/^nodes/^blocks/^edges: the repository (the root row) from inside a row; 0^docs from any depth");
+        cli.io.out("       query 'select path, open from docs where nodes collect { ^open: value where kind == \"md:task\" and not attrs.checked }'");
+        cli.io.out("       query 'select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id } from docs'   # ^docs/^nodes/^blocks/^links: the repository (the root row) from inside a row; 0^docs from any depth; ^id / 0^id = the repository id");
         cli.io.out("       query 'docs count { where layer == \"canon\" }'   # scalar; also <target> exists/none/first/single { … } at the top level");
-        cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" && !checked }'   # none = zero rows (≡ !exists; \"every\" = none over the complement)");
+        cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" and not checked }'   # none = zero rows (≡ not … exists; \"every\" = none over the complement)");
+        cli.io.out("       query 'from docs where era is not null and (layer == \"canon\" or layer == \"working\")'   # and / or / not are the connectives (&& || ! accepted); x is y / x is not y = identity, x is null = absent");
+        cli.io.out("       query 'docs { type == \"substance\" and not verified }'   # sugar: a block without a consumer is collect; a leading predicate drops `where` (bare names still project — filter a bare field with `is x`); after a follow destination too: follow children { depth 2 } is its block");
+        cli.io.out("       query 'select subject, process: ^docs[slug == ^subject].path from docs where type == \"lab-note\"'   # x[p] = first match or absent; x[p]! = exactly one, required; x[n] = positional; title! = the value or a loud error; a select item may use the items to its left");
+        cli.io.out("       query 'select path, $depth from docs where path == \"/timeline/review.md\" follow refs(before), refs(after)'   # refs(field): the live documents a property's references name (either path form or a d_ id; dangling dropped) — a receiver, a source or a follow destination");
+        cli.io.out("       query 'select path, next: ^docs { ^path in list(before) } from docs where type == \"milestone\"'   # paths are /-rooted on the surface (path == \"/x.md\"; inputs accept both forms), so a property's reference compares with ^path directly");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc limit 2 offset 1'   # limit/offset bound the set (after order/distinct, before the consumer)");
-        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $it } from docs where $path == \"/x.md\"'   # a record as a collection ($key/$it); also entries(attrs), entries(inline)");
-        cli.io.out("       query 'select $path values from docs where layer == \"canon\"'   # `values`: bare values, no {id,path} hits (one item only)");
-        cli.io.out("       query 'select $path, tags: tags collect { $it values where $it != \"draft\" } from docs'   # $it = the current item (here: each tag)");
+        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $it } from docs where path == \"/x.md\"'   # a record as a collection ($key/$it); also entries(attrs), entries(inline)");
+        cli.io.out("       query 'select path values from docs where layer == \"canon\"'   # `values`: bare values, no {id,path} hits (one item only)");
+        cli.io.out("       query 'select path, tags: tags collect { $it values where $it != \"draft\" } from docs'   # $it = the current item (here: each tag)");
         cli.io.out("       query 'docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
-        cli.io.out("       query 'from docs where text(\"philosophers stone\") && layer == \"canon\"'   # full-text prune");
+        cli.io.out("       query 'from docs where text(\"philosophers stone\") and layer == \"canon\"'   # full-text prune");
         cli.io.out("       query 'select s: semantic(\"the great work\") from blocks where semantic(\"the great work\") > 0.6'  # embedding score (needs a provider)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc'   # order by <expr> [asc|desc]");
-        cli.io.out("       query 'select t: text, d: $depth, s: $stop from blocks where $id == \"b_x\" follow block.children'   # recursive walk ($depth/$stop metadata)");
-        cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <rel> [{ where … frontier … depth n by … }]");
-        cli.io.out("       query 'select p: $path, d: $depth, s: $stop from docs where $path == \"/index.md\" follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
-        cli.io.out("       query 'from blocks where type == \"list_item\" && $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
-        cli.io.out("       query 'select src: $src, to: $dst_path from edges where predicate == \"depends_on\"'   # the edges target: predicate/provenance/dst_kind + $src/$dst_path/$dst_uri");
+        cli.io.out("       query 'select t: text, d: $depth, s: $stop from blocks where id == \"b_x\" follow block.children'   # recursive walk ($depth/$stop metadata)");
+        cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <dest> [{ where … frontier … depth n }] — a brace after any destination is that destination's block (identity is $key: project $key: <expr> to rekey a walk)");
+        cli.io.out("       query 'select p: path, d: $depth, s: $stop from docs where path == \"/index.md\" follow out_links collect { from dst }'   # citation graph (cyclic-safe: $stop=cycle)");
+        cli.io.out("       query 'from blocks where type == \"list_item\" and $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
+        cli.io.out("       query 'select src: doc_id, to: dst_path from links where predicate == \"depends_on\"'   # the links target: predicate/provenance/dst_kind + doc_id/dst_path/uri");
         return EXIT_OK;
     }
     const source = values.file
@@ -111,7 +116,7 @@ async function runOqx(cli, args) {
         if (phrases.length > 0) {
             const loaded = await loadEmbedding(ws, repo.repoId);
             if (!loaded) {
-                throw new EngineErrorLike("semantic_unavailable", "semantic(...) needs an embedding provider", {
+                throw new EngineErrorLike("provider_unavailable", "semantic(...) needs an embedding provider", {
                     hint: "omg config set embedding.provider <command|url>",
                 });
             }

package/dist/src/cmd/outline.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { findDoc, docsOutline, referencePath } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, emitMachine, renderHelp } from "../output.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, docLocator } from "./_remote.js";
 // `omg outline <doc|path>` (alias ol) — the wire format (06 §6). Human output
 // prints the outline text with full block ids inline; --json emits the
 // OutlineResult verbatim.
@@ -32,11 +32,11 @@ async function runOutline(cli, args) {
     let result;
     let header;
     if (cli.flags.server) {
-        // Remote: the docs_outline tool resolves the ref + returns the same
-        // OutlineResult. The header shows the ref you passed (no local path lookup):
+        // Remote: the docs_outline tool resolves the locator (`id` for a `d_` id,
+        // else `path`) + returns the same OutlineResult. The header shows the ref you passed (no local path lookup):
         // a path ref rooted (spec/surface §1 "Paths"), a `d_` id verbatim.
         result = await remoteCall(cli, "docs_outline", {
-            doc: ref,
+            ...docLocator(ref),
             ...(values.depth ? { depth: Number(values.depth) } : {}),
             ...(values.skeleton ? { resolution: "skeleton" } : {}),
         });

package/dist/src/cmd/retarget.js

@@ -66,7 +66,7 @@ function renderPlan(cli, from, to, hits) {
     }
     io.err(style.dim(`  plan — ${hits.length} block(s) would change; re-run with --apply to commit`));
     for (const h of hits) {
-        io.out(style.id(h.block));
+        io.out(style.id(h.id));
         for (const line of unifiedDiffLines(cli, h.oldRaw, h.newRaw))
             io.out(line);
         io.out("");

package/dist/src/cmd/run.js

@@ -84,7 +84,7 @@ async function runRun(cli, args) {
     if (phrases.length > 0) {
         const loaded = await loadEmbedding(ws, repo.repoId);
         if (!loaded) {
-            throw new EngineErrorLike("semantic_unavailable", "semantic(...) needs an embedding provider", {
+            throw new EngineErrorLike("provider_unavailable", "semantic(...) needs an embedding provider", {
                 hint: "omg config set embedding.provider <command|url>",
             });
         }

package/dist/src/cmd/show.js

@@ -9,15 +9,20 @@ function showOne(cli, ref, include) {
     if (!resolved)
         throw new EngineErrorLike("doc_missing", `no node ${ref}`);
     if (resolved.kind === "document") {
-        // The card reads the merged properties + open edges; `--json` is the
-        // `read_ref` result for a document (`{ kind: "document", ...docs_read }`).
+        // The card reads the merged properties + open links; `--json` is the
+        // `docs_read` result tagged with its kind (`{ kind: "document", ...docs_read }`).
         const res = docsRead(ws.store, resolved.docId);
         if (!res)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         const links = docLinks(ws.store, resolved.docId, { direction: "both" });
-        const properties = docPropertiesMerged(ws.store.db, resolved.docId);
+        // The authored keys, merged (frontmatter + inline — the `data` view); the
+        // computed rows are rendered under their surface names (`title`/`tags`,
+        // spec/surface §1.2 — the store's `$title`/`$tags` keys never reach the
+        // terminal) from the re-keyed `properties.computed` the read carries.
+        const properties = Object.fromEntries(Object.entries(docPropertiesMerged(ws.store.db, resolved.docId)).filter(([k]) => !k.startsWith("$")));
+        const computed = res.properties.computed ?? {};
         const payload = { kind: "document", ...res };
-        return { payload, render: () => renderDocCard(cli, res.path, properties, links) };
+        return { payload, render: () => renderDocCard(cli, res.path, properties, computed, links) };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution: "full" });
     if (!node)
@@ -34,7 +39,7 @@ function runShow(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "show",
-            summary: "Metadata card for a node: attrs, placement, open edges, last change (`cat` is the bytes)",
+            summary: "Metadata card for a node: attrs, placement, open links, last change (`cat` is the bytes)",
             usage: "show <node…|-> [--include history]",
             options: [
                 ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a doc path (`/notes/x.md`; the leading `/` is optional)"],
@@ -59,7 +64,7 @@ function runShow(cli, args) {
         c.render();
     return EXIT_OK;
 }
-function renderDocCard(cli, path, fm, links) {
+function renderDocCard(cli, path, fm, computed, links) {
     const { render, style, io } = cli;
     io.out(render.wordmark(path));
     io.out(render.rule(40));
@@ -69,23 +74,32 @@ function renderDocCard(cli, path, fm, links) {
         for (const k of keys)
             io.out(`    ${style.accent(k)} ${style.dim("=")} ${fmt(fm[k])}`);
     }
+    // The computed rows under their surface names (`title`, `tags` — spec/surface
+    // §1.2), their own section so a computed title never masquerades as authored.
+    const computedKeys = Object.keys(computed);
+    if (computedKeys.length > 0) {
+        io.out(`  ${style.dim("computed")}`);
+        for (const k of computedKeys)
+            io.out(`    ${style.accent(k)} ${style.dim("=")} ${fmt(computed[k])}`);
+    }
     if (links.out.length > 0) {
-        io.out(`  ${style.dim("out edges")}`);
+        io.out(`  ${style.dim("out links")}`);
         for (const e of links.out)
-            io.out(`    ${style.accent(e.predicate)} ${style.dim(render.g.arrow)} ${style.id(e.node)} ${style.dim(`×${e.count}`)}`);
+            io.out(`    ${style.accent(e.predicate)} ${style.dim(render.g.arrow)} ${style.id(e.doc_id)} ${style.dim(`×${e.count}`)}`);
     }
     if (links.in.length > 0) {
         io.out(`  ${style.dim("backlinks")}`);
         for (const e of links.in)
-            io.out(`    ${style.id(e.node)} ${style.dim(render.g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+            io.out(`    ${style.id(e.doc_id)} ${style.dim(render.g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
     }
 }
 function renderBlockCard(cli, node, history) {
     const { render, style, io } = cli;
     io.out(`  ${render.typeGlyph(node.type)} ${style.bold(node.type)}  ${style.id(node.id)}`);
     io.out(render.rule(40));
-    if (node.placement)
-        io.out(`  ${style.dim("placement")}  parent=${style.id(node.placement.parent ?? "—")} ordinal=${node.placement.ordinal} depth=${node.placement.depth}`);
+    // The placement is flattened onto the row (3.0: `parent_id`/`ordinal`/`depth`); the line reads the same.
+    if (node.ordinal !== undefined)
+        io.out(`  ${style.dim("placement")}  parent=${style.id(node.parent_id ?? "—")} ordinal=${node.ordinal} depth=${node.depth}`);
     if (node.attrs && Object.keys(node.attrs).length > 0) {
         io.out(`  ${style.dim("attrs")}`);
         for (const [k, v] of Object.entries(node.attrs))

package/dist/src/cmd/update.js

@@ -3,7 +3,7 @@ import { docsUpdate, renderOpsetPlan, surfaceDocsUpdate } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, docLocator, requireDoc } from "./_remote.js";
 // `omg update <target> (-f file | -)`: a polymorphic-target command (the omgbase
 // north-star — every command accepts any entity ref). A block id (b_…) replaces
 // that block's markdown (CAS-pinned, the low-level op). A doc id or path is the
@@ -57,7 +57,7 @@ async function runDocUpdate(cli, args) {
         // Remote: docs_update reconciles + commits server-side, returning the same
         // { opset, result } — render unchanged.
         const r = await remoteCall(cli, "docs_update", {
-            doc,
+            ...docLocator(doc),
             content: bytes,
             ...(values.reason ? { reason: values.reason } : {}),
             ...(dryRun ? { dry_run: true } : {}),
@@ -76,7 +76,7 @@ async function runDocUpdate(cli, args) {
             ...(ws.omgbaseDir ? { omgbaseDir: ws.omgbaseDir } : {}),
             ...(values.actor ? { actor: values.actor } : {}),
         };
-        ({ opset, result } = surfaceDocsUpdate(docsUpdate(ws.store, ctx, doc, bytes, {
+        ({ opset, result } = surfaceDocsUpdate(docsUpdate(ws.store, ctx, requireDoc(ws.store, repo.repoId, doc), bytes, {
             dryRun,
             ...(values.reason ? { reason: values.reason } : {}),
         })));

package/dist/src/context.js

@@ -85,7 +85,7 @@ export const REMOTE_OK = new Set([
     // doc-level mutators
     "new", "mv", "meta", "rm", "update", "retarget",
     // block-level sugar (server-side ref resolution + CAS via the blocks_* /
-    // tasks_complete / sections_append / node_set / apply tools)
+    // blocks_check / blocks_append / nodes_set / apply tools)
     "apply", "insert", "move", "split", "merge", "done", "append", "node",
     // shell accepts --server itself, then threads it into every line it runs.
     "shell",

package/dist/src/output.d.ts

@@ -92,10 +92,13 @@ export declare const HIT_CELL_MAX = 60;
 export declare function truncateCell(s: string, max?: number): string;
 /** Render one projected value as a table cell (unstyled). */
 export declare function hitCell(v: unknown): string;
-/** The projected column names across `hits`: every key but the injected id/path,
- *  in first-seen order. Empty when nothing was projected. */
+/** The projected column names across `hits`: every key but the envelope's
+ *  `id`/`path` (spec/surface §1.4, 3.0 — a `path` projection collapses onto
+ *  the envelope key, so it is never a column), in first-seen order. Empty when
+ *  nothing was projected. */
 export declare function hitColumns(hits: HitLike[]): string[];
-/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected. */
+/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected
+ *  (header `id`, `path`, then the projected keys — spec/cli §4, 3.0). */
 export declare function renderHits(cli: {
     io: IO;
     style: Style;

package/dist/src/output.js

@@ -190,8 +190,10 @@ export function hitCell(v) {
         return String(v);
     return truncateCell(JSON.stringify(v) ?? String(v));
 }
-/** The projected column names across `hits`: every key but the injected id/path,
- *  in first-seen order. Empty when nothing was projected. */
+/** The projected column names across `hits`: every key but the envelope's
+ *  `id`/`path` (spec/surface §1.4, 3.0 — a `path` projection collapses onto
+ *  the envelope key, so it is never a column), in first-seen order. Empty when
+ *  nothing was projected. */
 export function hitColumns(hits) {
     const cols = [];
     const seen = new Set(["id", "path"]);
@@ -205,7 +207,8 @@ export function hitColumns(hits) {
     }
     return cols;
 }
-/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected. */
+/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected
+ *  (header `id`, `path`, then the projected keys — spec/cli §4, 3.0). */
 export function renderHits(cli, hits) {
     const { io, style } = cli;
     const projected = hitColumns(hits);
@@ -214,7 +217,7 @@ export function renderHits(cli, hits) {
             io.out(`${style.id(h.id)}  ${style.accent(h.path)}`.trimEnd());
         return;
     }
-    const cols = projected.includes("$path") ? ["id", ...projected] : ["id", "path", ...projected];
+    const cols = ["id", "path", ...projected];
     const rows = [cols.map((c) => style.dim(c))];
     for (const h of hits) {
         rows.push(cols.map((c) => {
@@ -222,8 +225,6 @@ export function renderHits(cli, hits) {
                 return style.id(h.id);
             if (c === "path")
                 return style.accent(h.path);
-            if (c === "$path" && typeof h[c] === "string")
-                return style.accent(h[c]);
             return hitCell(h[c]);
         }));
     }

package/dist/src/shell/refs.js

@@ -10,7 +10,10 @@
 // signal to use OQX instead.
 export class RefError extends Error {
 }
-const REF_RE = /^@(\d+|_|[A-Za-z][\w-]*)(?:\[(\d+)\])?(?:\.([A-Za-z_]\w*))?$/;
+// `.field` reads any projected key (`@1.id`, `@t[1].path`, `@1.layer` —
+// spec/surface §1.4, 3.0 spells the envelope as the bare attributes); a leading
+// `$` is admitted for an OQX-named projection (`$depth`).
+const REF_RE = /^@(\d+|_|[A-Za-z][\w-]*)(?:\[(\d+)\])?(?:\.(\$?[A-Za-z_]\w*))?$/;
 /** Parse a whole-token reference; null if the token isn't a reference. */
 export function parseRef(token) {
     if (!token.startsWith("@"))
@@ -64,13 +67,20 @@ function rowOf(el) {
         return { ref: el, label: el, value: el };
     if (el && typeof el === "object") {
         const o = el;
-        const ref = firstString(o, ["id", "node", "block", "locator", "path"]);
-        const label = firstString(o, ["path", "locator", "name", "id", "node"]) ?? ref ?? preview(o);
+        const ref = firstString(o, REF_KEYS);
+        const label = firstString(o, ["path", "locator", "name", "id", "node", "doc_id"]) ?? ref ?? preview(o);
         return { ref: ref ?? label ?? "", label: label ?? "", value: el };
     }
     const s = String(el);
     return { ref: s, label: s, value: el };
 }
+// The keys that make an object an entity ref, in precedence order: a row's
+// `id` (spec/surface §1.2, 3.0 — every tool result spells a row's identity as
+// the attribute; a 2.x server's `id` is the same key), a `links` row's far node
+// (`doc_id`) and an edge's `block_id`, then the pre-3.0 envelopes (`node`,
+// `block`) — kept so a remote 2.x server's results still address — then
+// `locator` and a path.
+const REF_KEYS = ["id", "doc_id", "block_id", "node", "block", "locator", "path"];
 function firstString(o, keys) {
     for (const k of keys)
         if (typeof o[k] === "string")
@@ -98,7 +108,7 @@ export function coerce(value) {
     }
     if (typeof value === "object") {
         const o = value;
-        const ref = firstString(o, ["id", "node", "block", "locator", "path"]);
+        const ref = firstString(o, REF_KEYS);
         if (ref)
             return ref;
         // A collection-shaped result object (e.g. {hits:[…]}) can't be one arg.

package/dist/src/shell/session.js

@@ -295,7 +295,7 @@ export class ShellSession {
             return String(v);
         if (v && typeof v === "object") {
             const o = v;
-            const id = o.id ?? o.node ?? o.path ?? o.locator;
+            const id = o.id ?? o.id ?? o.node ?? o.path ?? o.path ?? o.locator; // a query hit leads with id/path (surface 3.0)
             return id ? String(id) : "record";
         }
         return "empty";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.10.0",
+    "@omgbase/core": "^0.11.0",
     "@omgbase/fs-adapter": "^0.2.0",
-    "@omgbase/sync": "^0.4.10",
+    "@omgbase/sync": "^0.5.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {