omgbase 0.13.0 → 0.18.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "48b355b",
-  "built": "2026-10-12T21:39:26.285Z"
+  "commit": "66abf7c",
+  "built": "2026-10-14T06:35:28.357Z"
 }

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

@@ -46,9 +46,12 @@ export declare function runSugar(cli: Cli, ws: Workspace, repo: RepoRow, sugar:
  * SAME renderers as local. The global --dry-run is the `plan` tool over the
  * effects the verb would build (`effects` composes them from the refs as given:
  * an id names its row, anything else a document path — the server resolves);
- * no tool takes `dry_run` since surface 4.0.
+ * no tool takes `dry_run` since surface 4.0. A server that does not list the
+ * tool (spec/surface §4 "Profiles": `--tools minimal`) gets `apply { effects,
+ * reason: <tool> }` from the same closure (`remoteSugar`, spec/cli §2.3);
+ * `refs` are the refs the verb received, refused there when one is a locator.
  */
-export declare function runSugarRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>): Promise<number>;
+export declare function runSugarRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): Promise<number>;
 /** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
 export declare function targetOf(ref: string): EffectTarget;
 /**
@@ -70,7 +73,8 @@ export declare function renderPlan(cli: Cli, plan: Plan): number;
 /**
  * A Receipt (any write tool's result since 4.0 — a `links_*` result carries its
  * `hits`/`pairs` beside the receipt's keys): `--json` verbatim; human the
- * commit confirmation of §4 (one revision per touched document) and, on
+ * commit confirmation of §4 (one revision per touched document), the plan's
+ * summary lines under it (4.3: what was committed, in words) and, on
  * stdout, the ids the write names — the plan's `preview.results[].ids` with
  * every `$new.n` realized from `new_ids` when the plan is at hand with its
  * preview (a local write, any `execute`); else (a plan echoed without
@@ -79,6 +83,8 @@ export declare function renderPlan(cli: Cli, plan: Plan): number;
  * ids that name no row.
  */
 export declare function renderReceipt(cli: Cli, receipt: Receipt, plan?: unknown): number;
+/** The Receipt's `summary` (spec/cli §4, 4.3): what was committed in words, one line per effect, indented under the confirmation on stderr. */
+export declare function renderSummary(cli: Cli, summary: readonly string[] | undefined): void;
 export declare function receiptIds(receipt: Receipt, plan: unknown): string[];
 /**
  * The dry-run rendering every write verb shares (spec/cli §3.6): the note on

package/dist/src/cmd/_mutate.js

@@ -2,7 +2,7 @@ import { readFileSync, readSync } from "node:fs";
 import { userInfo } from "node:os";
 import { applyEffectsDetailed, applySugar, executePlan, isValidId, substituteSymbols, unifiedDiff, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, EXIT_ERROR } from "../output.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, remoteSugar } from "./_remote.js";
 // Shared plumbing for every write command (spec/cli §3.6, §4; ADR-021's
 // retirement release, cli 4.0). The sugar verbs build their effects with the
 // shared builders of `@omgbase/core` (`mutate/sugar.ts` — the same table the
@@ -152,12 +152,15 @@ export function runSugar(cli, ws, repo, sugar, opts = {}) {
  * SAME renderers as local. The global --dry-run is the `plan` tool over the
  * effects the verb would build (`effects` composes them from the refs as given:
  * an id names its row, anything else a document path — the server resolves);
- * no tool takes `dry_run` since surface 4.0.
+ * no tool takes `dry_run` since surface 4.0. A server that does not list the
+ * tool (spec/surface §4 "Profiles": `--tools minimal`) gets `apply { effects,
+ * reason: <tool> }` from the same closure (`remoteSugar`, spec/cli §2.3);
+ * `refs` are the refs the verb received, refused there when one is a locator.
  */
-export async function runSugarRemote(cli, tool, toolArgs, effects) {
+export async function runSugarRemote(cli, tool, toolArgs, effects, refs = []) {
     if (cli.flags.dryRun)
-        return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects() }));
-    return renderReceipt(cli, await remoteCall(cli, tool, toolArgs));
+        return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects(), diffs: true }));
+    return renderReceipt(cli, await remoteSugar(cli, tool, toolArgs, effects, refs));
 }
 /** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
 export function targetOf(ref) {
@@ -195,7 +198,7 @@ export function runEffects(cli, ws, repo, effects, opts = {}) {
 /** Remote peer of `runEffects`: the `apply` tool with `effects` (the Receipt), or on a dry run the `plan` tool (the Plan). */
 export async function runEffectsRemote(cli, effects, reason) {
     if (cli.flags.dryRun)
-        return renderPlan(cli, await remoteCall(cli, "plan", { effects }));
+        return renderPlan(cli, await remoteCall(cli, "plan", { effects, diffs: true }));
     return renderReceipt(cli, await remoteCall(cli, "apply", { effects, ...(reason ? { reason } : {}) }));
 }
 /** `execute`: commit exactly a Plan (the plan form, spec/mutate §11.7 — admission, then the one transaction), rendered as a Receipt. */
@@ -226,7 +229,8 @@ export function renderPlan(cli, plan) {
 /**
  * A Receipt (any write tool's result since 4.0 — a `links_*` result carries its
  * `hits`/`pairs` beside the receipt's keys): `--json` verbatim; human the
- * commit confirmation of §4 (one revision per touched document) and, on
+ * commit confirmation of §4 (one revision per touched document), the plan's
+ * summary lines under it (4.3: what was committed, in words) and, on
  * stdout, the ids the write names — the plan's `preview.results[].ids` with
  * every `$new.n` realized from `new_ids` when the plan is at hand with its
  * preview (a local write, any `execute`); else (a plan echoed without
@@ -244,10 +248,16 @@ export function renderReceipt(cli, receipt, plan) {
     const { render, style, io } = cli;
     const n = receipt.revisions.length;
     io.err(style.dim(`  ${style.ok(render.g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
+    renderSummary(cli, receipt.summary);
     for (const id of ids)
         io.out(id);
     return EXIT_OK;
 }
+/** The Receipt's `summary` (spec/cli §4, 4.3): what was committed in words, one line per effect, indented under the confirmation on stderr. */
+export function renderSummary(cli, summary) {
+    for (const line of summary ?? [])
+        cli.io.err(cli.style.dim(`    ${line}`));
+}
 export function receiptIds(receipt, plan) {
     const results = plan?.preview?.results;
     if (!Array.isArray(results))

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

@@ -11,6 +11,20 @@ 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>;
+/** Whether the remote engine lists `tool` (spec/surface §4 "Profiles": a `--tools minimal` server lists ten). */
+export declare function remoteHasTool(cli: Cli, tool: string): Promise<boolean>;
+/** A `#` locator (`path#type[n]`, `#^anchor`): a ref only a server with the sugar tools resolves. */
+export declare function isLocator(ref: string): boolean;
+/**
+ * The remote sugar call (spec/cli §2.3, 4.2): call `tool` with `toolArgs` when
+ * the server lists it — the server resolves refs and pins CAS — else send
+ * `apply { effects, reason: <tool> }` with the effects the local builders make
+ * from the refs as given (the closure a dry run already uses: an id names its
+ * row, anything else a document path). Server-side locator resolution is the
+ * one thing a minimal server cannot do, so a `#` locator among `refs` is a
+ * usage error there rather than a bogus document path.
+ */
+export declare function remoteSugar<T>(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): 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). */

package/dist/src/cmd/_remote.js

@@ -57,6 +57,34 @@ export async function remoteCall(cli, tool, args) {
     const eng = await remoteEngine(cli);
     return eng.callTool(tool, { ...args, ...(cli.flags.repo ? { repo: cli.flags.repo } : {}) });
 }
+/** Whether the remote engine lists `tool` (spec/surface §4 "Profiles": a `--tools minimal` server lists ten). */
+export async function remoteHasTool(cli, tool) {
+    return (await remoteEngine(cli)).hasTool(tool);
+}
+/** A `#` locator (`path#type[n]`, `#^anchor`): a ref only a server with the sugar tools resolves. */
+export function isLocator(ref) {
+    return ref.includes("#") && !isValidId(ref, "b") && !isValidId(ref, "d");
+}
+/**
+ * The remote sugar call (spec/cli §2.3, 4.2): call `tool` with `toolArgs` when
+ * the server lists it — the server resolves refs and pins CAS — else send
+ * `apply { effects, reason: <tool> }` with the effects the local builders make
+ * from the refs as given (the closure a dry run already uses: an id names its
+ * row, anything else a document path). Server-side locator resolution is the
+ * one thing a minimal server cannot do, so a `#` locator among `refs` is a
+ * usage error there rather than a bogus document path.
+ */
+export async function remoteSugar(cli, tool, toolArgs, effects, refs = []) {
+    if (await remoteHasTool(cli, tool))
+        return remoteCall(cli, tool, toolArgs);
+    const locator = refs.find(isLocator);
+    if (locator !== undefined) {
+        throw new CliUsageError(`${JSON.stringify(locator)} is a locator, and this server does not list ${tool} (a minimal tools profile) — refs are not resolved server-side there; pass a block or document id instead`);
+    }
+    // The commit reason: the caller's own `reason` argument when the tool takes one, else the tool's name.
+    const reason = typeof toolArgs.reason === "string" ? toolArgs.reason : tool;
+    return remoteCall(cli, "apply", { effects: await effects(), reason });
+}
 /** 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). */

package/dist/src/cmd/admin.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
-import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, } from "@omgbase/core";
+import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, sizeReport, vacuum, reclaimableBytes, humanBytes, formatShare, } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, emitMachine, renderHelp } from "../output.js";
+import { columns } from "../render.js";
 import { loadEmbedding, drainEmbeddings } from "./_embed.js";
 // admin/maintenance (11 §5.8–5.9). The live watcher moved to `omg sync --watch`.
 // ---- rebuild-index ----------------------------------------------------------
@@ -35,13 +36,16 @@ function runRebuild(cli, args) {
 }
 // ---- gc ---------------------------------------------------------------------
 function runGcCmd(cli, args) {
-    const { values } = parseArgs({ args, allowPositionals: true, options: { "dry-run": { type: "boolean" }, help: { type: "boolean" } } });
+    const { values } = parseArgs({ args, allowPositionals: true, options: { "dry-run": { type: "boolean" }, vacuum: { type: "boolean" }, help: { type: "boolean" } } });
     if (values.help) {
         return renderHelp(cli, {
             name: "gc",
-            summary: "Mark-and-sweep unreferenced blobs and tree nodes (refuses unless gc.enabled is set in repo settings)",
-            usage: "gc [--dry-run]",
-            options: [["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"]],
+            summary: "Mark-and-sweep unreferenced blobs and tree nodes, and the `same` disposition rows a pre-14.2 store wrote (refuses unless gc.enabled is set in repo settings)",
+            usage: "gc [--dry-run] [--vacuum]",
+            options: [
+                ["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"],
+                ["--vacuum", "after the sweep, VACUUM the database to return its free pages to the filesystem (`doctor --size` shows how many)"],
+            ],
         });
     }
     // `--dry-run` is also a global flag (parseGlobals consumes it) — honor either spelling.
@@ -53,24 +57,41 @@ function runGcCmd(cli, args) {
     if (!enabled && !dryRun) {
         throw new EngineErrorLike("target_missing", "gc is disabled; set gc.enabled=true (or use --dry-run)");
     }
-    const result = runGc(ws.store, { enabled: enabled || dryRun });
+    // A dry run counts every sweep — blobs, tree nodes and the `same` disposition
+    // rows a 14.1 store wrote (spec/store §7, 14.2) — and deletes nothing.
+    const swept = runGc(ws.store, { enabled: enabled || dryRun, dryRun });
+    // `--vacuum` runs after the sweep (the sweep's freed pages are what it returns);
+    // a dry run measures the free pages and vacuums nothing (spec/store §7).
+    const vac = values.vacuum
+        ? dryRun
+            ? { reclaimable: reclaimableBytes(ws.store), applied: false }
+            : { ...vacuum(ws.store), applied: true }
+        : undefined;
+    const result = vac ? { ...swept, vacuum: vac } : swept;
     if (cli.flags.mode !== "human")
         return emitMachine(cli, result);
-    cli.io.err(cli.style.dim(`  swept ${result.blobsSwept} blobs, ${result.treeNodesSwept} tree nodes`));
+    cli.io.err(cli.style.dim(`  swept ${swept.blobsSwept} blobs, ${swept.treeNodesSwept} tree nodes, ${swept.sameDispositionsSwept} same dispositions`));
+    if (vac)
+        cli.io.err(cli.style.dim(vac.applied ? `  vacuumed, reclaimed ${humanBytes(vac.reclaimable)}` : `  would vacuum ${humanBytes(vac.reclaimable)}`));
     return EXIT_OK;
 }
 // ---- doctor -----------------------------------------------------------------
 function runDoctor(cli, args) {
-    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    const { values } = parseArgs({ args, allowPositionals: true, options: { size: { type: "boolean" }, help: { type: "boolean" } } });
     if (values.help) {
         return renderHelp(cli, {
             name: "doctor",
             summary: "Invariant sweep: convergence, FTS rows vs live leaf blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
-            usage: "doctor [--json]",
-            options: [["--json", "`{ ok, checks: [{ name, ok, detail }] }`"]],
+            usage: ["doctor [--json]", "doctor --size [--json]"],
+            options: [
+                ["--size", "instead of the checks: what the database is made of — bytes and rows per category (content, history, search, sync) and table, the file's pages, what VACUUM would reclaim, advice"],
+                ["--json", "`{ ok, checks: [{ name, ok, detail }] }`; with --size `{ file, categories, same_dispositions, advice }`"],
+            ],
         });
     }
     const ws = cli.workspace();
+    if (values.size)
+        return runDoctorSize(cli, sizeReport(ws.store));
     const repo = cli.repo(ws);
     const db = ws.store.db;
     const checks = [];
@@ -98,6 +119,52 @@ function runDoctor(cli, args) {
     }
     return allOk ? EXIT_OK : EXIT_ERROR;
 }
+// `doctor --size` (spec/cli §6, cli 4.3): the store's size report (spec/store
+// §7 "Size") as one aligned table — each category, then its three biggest
+// tables indented — the file's page accounting, and the advice lines. Exit 0:
+// a size report is information, not a check. The bytes and share cells are
+// right-aligned in fixed widths (the widest humanized size, `1023.9 KB`, is 9;
+// the widest share, `100.0%`, 6) so the layout is the same whatever the
+// numbers — which is what lets the fixtures pin it by shape (§8).
+const TOP_TABLES = 3;
+const NO_BYTES = "—";
+const BYTES_CELL = 9;
+const SHARE_CELL = 6;
+function runDoctorSize(cli, report) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, report);
+    const { style, io } = cli;
+    const bytes = (n) => (n === null ? NO_BYTES : humanBytes(n)).padStart(BYTES_CELL);
+    const share = (n) => (n === null ? NO_BYTES : formatShare(n)).padStart(SHARE_CELL);
+    // The last column is never padded by `columns`, so the row counts are
+    // right-aligned here (to the widest count, or the header).
+    const shown = report.categories.flatMap((c) => [c.rows, ...c.tables.slice(0, TOP_TABLES).map((t) => t.rows)]);
+    const rowsWidth = Math.max(4, ...shown.map((n) => String(n).length));
+    const count = (n) => String(n).padStart(rowsWidth);
+    const rows = [[style.dim("category"), style.dim("bytes".padStart(BYTES_CELL)), style.dim("share".padStart(SHARE_CELL)), style.dim("rows".padStart(rowsWidth))]];
+    for (const c of report.categories) {
+        rows.push([style.accent(c.name), bytes(c.bytes), share(c.share), count(c.rows)]);
+        for (const t of c.tables.slice(0, TOP_TABLES))
+            rows.push([`  ${t.name}`, bytes(t.bytes), share(t.share), count(t.rows)]);
+    }
+    for (const line of columns(rows, [{}, { align: "right" }, { align: "right" }]))
+        io.out(`  ${line}`);
+    if (report.detail)
+        io.out(style.dim(`  ${report.detail}: row counts only`));
+    io.out("");
+    const f = report.file;
+    const file = [
+        ["file", style.path(f.path)],
+        ["size", `${humanBytes(f.bytes)} on disk, wal ${humanBytes(f.wal_bytes)}`],
+        ["pages", `${f.page_count} x ${f.page_size} bytes, ${f.freelist_count} free`],
+        ["reclaimable", humanBytes(f.reclaimable)],
+    ];
+    for (const line of columns(file))
+        io.out(`  ${line}`);
+    for (const a of report.advice)
+        io.out(`  ${style.dim("advice:")} ${a}`);
+    return EXIT_OK;
+}
 function resolveConfigScope(cli, ws) {
     if (cli.flags.repo === "")
         return { kind: "workspace" };

package/dist/src/cmd/mcp.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError } from "@omgbase/core";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError, resolveSettings, parseToolsProfile, TOOLS_PROFILES, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { installSpecSeams, WRITER_LOCK_TIMEOUT_ENV } from "../seams.js";
 import { loadEmbedding } from "./_embed.js";
 import { openRepoSource } from "./_source.js";
@@ -34,21 +34,28 @@ async function runMcp(cli, args) {
     const { values } = parseArgs({
         args,
         allowPositionals: true,
-        options: { "no-watch": { type: "boolean" }, help: { type: "boolean" } },
+        options: { "no-watch": { type: "boolean" }, tools: { type: "string" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "mcp",
             summary: "Serve the MCP tool surface on stdio for an MCP host (Claude Code, Cursor, …); the host owns the process lifetime",
-            usage: "mcp [-C <workspace-dir>] [--repo <slug>] [--no-watch]",
+            usage: "mcp [-C <workspace-dir>] [--repo <slug>] [--no-watch] [--tools full|minimal]",
             options: [
                 ["-C <dir>", "the workspace to serve — a directory at or below one containing .omgbase/ (the host rarely starts you inside it)"],
                 ["--repo <slug>", "which repo, when the workspace has several"],
                 ["--no-watch", "don't run the in-process file watcher (it is auto-off when another live watcher holds the lease)"],
+                ["--tools <profile>", "the catalog profile to serve: full (default — every tool) or minimal (ten tools: query, query_syntax, docs_read, docs_tree, blocks_resolve, changes_since, plan, execute, apply, version); overrides the mcp.tools setting"],
             ],
             notes: [`host config: {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]}`],
         });
     }
+    // The profile flag is checked before anything is opened: a bad value is the
+    // usage error (exit 2) whatever the workspace holds.
+    const flagProfile = values.tools === undefined ? undefined : parseToolsProfile(values.tools);
+    if (values.tools !== undefined && flagProfile === null) {
+        throw new CliUsageError(`--tools must be one of ${TOOLS_PROFILES.join("|")} (got ${JSON.stringify(values.tools)})`);
+    }
     announceSpecSeams(cli);
     // The host launches us from its own cwd, so a missing workspace here almost
     // always means the host config lacks `-C <dir>` — say so, rather than the
@@ -66,6 +73,21 @@ async function runMcp(cli, args) {
         throw err;
     }
     const repo = cli.repo(ws);
+    // The catalog profile (spec/surface §4 "Profiles", spec/cli `mcp` 4.2): the
+    // flag wins over the workspace's `mcp.tools` setting (repo overrides
+    // inherit, as every setting does); an unrecognized setting value is reported
+    // and ignored — the server comes up `full`, never silently reduced.
+    const settingProfile = resolveSettings(ws.store, repo.repoId).mcp?.tools;
+    let tools = "full";
+    if (flagProfile !== undefined && flagProfile !== null)
+        tools = flagProfile;
+    else if (settingProfile !== undefined) {
+        const parsed = parseToolsProfile(settingProfile);
+        if (parsed === null)
+            cli.io.err(cli.style.warn(`[mcp] ignoring setting mcp.tools = ${JSON.stringify(settingProfile)} (expected ${TOOLS_PROFILES.join("|")}); serving the full catalog`));
+        else
+            tools = parsed;
+    }
     // Connect the configured embedder once (if any) so the query tool's
     // `semantic` mode has a vectorizer for the session. Unset ⇒ semantic queries
     // return provider_unavailable. The spawned process lives for the session and
@@ -156,6 +178,8 @@ async function runMcp(cli, args) {
     }
     if (drainer)
         cli.io.err(cli.style.dim(`[mcp] auto-embed on mutation enabled`));
+    if (tools !== "full")
+        cli.io.err(cli.style.dim(`[mcp] tools profile: ${tools}`));
     // 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
@@ -182,6 +206,7 @@ async function runMcp(cli, args) {
         ...(loaded ? { embedProvider: loaded.providerName } : {}),
         // The `version` tool's view of this binary (spec/surface §4).
         host: hostInfo(),
+        tools,
     });
     let shuttingDown = false;
     const shutdown = async () => {

package/dist/src/cmd/mutate.js

@@ -4,7 +4,7 @@ import { resolveRef, isContainerBlock, appendEffects, checkEffects, insertEffect
 import { CliUsageError, EngineErrorLike, renderHelp } from "../output.js";
 import { runSugar, runSugarRemote, runEffects, runEffectsRemote, runExecutePlan, runExecutePlanRemote, readContent, readStdin, expandBlockArgs, extractContentOpts, targetOf } from "./_mutate.js";
 import { runRmDoc } from "./docs.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, remoteHasTool } from "./_remote.js";
 // Write sugar (11 §5.6; cli 4.0): each command resolves its refs, builds its
 // effects with the shared builders of `@omgbase/core` (the same table the MCP
 // tools use — ADR-012, the CLI holds no business logic) and applies them as one
@@ -43,6 +43,12 @@ function taskBlock(ws, ref, blockId) {
     }
     return blockId;
 }
+/** The block ref an `--at` anchor names (none for start/end) — a ref the remote fallback must be able to send as an id. */
+function anchorOf(at) {
+    if (typeof at === "string")
+        return [];
+    return "before" in at ? [at.before] : [at.after];
+}
 // Parse an `--at` spec: end|start|before X|after X (default end).
 function parseAt(values) {
     const at = values.at?.trim();
@@ -157,7 +163,7 @@ async function runInsert(cli, args) {
     const expect = values.expect ? { parent_children_hash: values.expect } : undefined;
     const at = parseAt(values);
     if (cli.flags.server) {
-        return runSugarRemote(cli, "blocks_insert", { to, markdown, at, ...(expect ? { expect } : {}) }, () => insertEffects(targetOf(to), at, markdown, expect).effects);
+        return runSugarRemote(cli, "blocks_insert", { to, markdown, at, ...(expect ? { expect } : {}) }, () => insertEffects(targetOf(to), at, markdown, expect).effects, [to, ...anchorOf(at)]);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -192,7 +198,7 @@ async function runUpdate(cli, args) {
     const expect = values.expect ? { content_hash: values.expect } : undefined;
     // Remote: the server pins CAS from current bytes when --expect is absent.
     if (cli.flags.server) {
-        return runSugarRemote(cli, "blocks_update", { id: ref, markdown, ...(expect ? { expect } : {}) }, () => updateBlockEffects(ref, { markdown, expect }).effects);
+        return runSugarRemote(cli, "blocks_update", { id: ref, markdown, ...(expect ? { expect } : {}) }, () => updateBlockEffects(ref, { markdown, expect }).effects, [ref]);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -236,7 +242,7 @@ async function runMove(cli, args) {
     const at = parseAt(values);
     const to = values.to;
     if (cli.flags.server) {
-        return runSugarRemote(cli, "blocks_move", { blocks: refs, to, at, ...(expect ? { expect } : {}) }, () => moveBlocksEffects(refs, targetOf(to), at, expect).effects);
+        return runSugarRemote(cli, "blocks_move", { blocks: refs, to, at, ...(expect ? { expect } : {}) }, () => moveBlocksEffects(refs, targetOf(to), at, expect).effects, [...refs, to, ...anchorOf(at)]);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -270,7 +276,7 @@ async function runRm(cli, args) {
     if (refs.length === 0)
         throw new CliUsageError("rm requires one or more blocks (or - for stdin), or --doc");
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_remove", { blocks: refs }, () => removeBlocksEffects(refs).effects);
+        return runSugarRemote(cli, "blocks_remove", { blocks: refs }, () => removeBlocksEffects(refs).effects, refs);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
@@ -300,7 +306,7 @@ async function runDone(cli, args) {
         throw new CliUsageError("done requires one or more task blocks (or - for stdin)");
     const checked = !values.undo;
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) }, () => checkEffects(refs, checked).effects);
+        return runSugarRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) }, () => checkEffects(refs, checked).effects, refs);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => taskBlock(ws, r, block(cli, ws, repo.repoId, r)));
@@ -336,9 +342,13 @@ async function runAppend(cli, args) {
     // server-side (spec/surface §4); a remote dry run reads the kind first.
     if (cli.flags.server) {
         return runSugarRemote(cli, "blocks_append", { id: target, text: markdown }, async () => {
-            const { type } = await remoteCall(cli, "blocks_read", { id: target, resolution: "skeleton" });
+            // The block's type decides the effect; `blocks_read` reads it on a full
+            // server, a `query` over the blocks target on a minimal one (§2.3).
+            const type = (await remoteHasTool(cli, "blocks_read"))
+                ? (await remoteCall(cli, "blocks_read", { id: target, resolution: "skeleton" })).type
+                : (await remoteCall(cli, "query", { query: `select type from blocks where id == ${JSON.stringify(target)}` })).hits[0]?.type;
             return appendEffects(type === "heading" ? { kind: "section", heading_id: target } : { kind: "block", id: target }, markdown).effects;
-        });
+        }, [target]);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -393,7 +403,7 @@ async function runSplit(cli, args) {
         return n;
     });
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_split", { id: ref, at }, () => splitEffects(ref, at).effects);
+        return runSugarRemote(cli, "blocks_split", { id: ref, at }, () => splitEffects(ref, at).effects, [ref]);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);
@@ -422,7 +432,7 @@ async function runMerge(cli, args) {
     if (refs.length < 2)
         throw new CliUsageError("merge requires at least two blocks");
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_merge", { blocks: refs, ...(values.sep !== undefined ? { separator: values.sep } : {}) }, () => mergeEffects(refs, values.sep).effects);
+        return runSugarRemote(cli, "blocks_merge", { blocks: refs, ...(values.sep !== undefined ? { separator: values.sep } : {}) }, () => mergeEffects(refs, values.sep).effects, refs);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));

package/dist/src/cmd/node.js

@@ -41,7 +41,7 @@ async function runNode(cli, args) {
         const value = valueParts.join(" ");
         // Remote: nodes_set resolves node → block + rewrites the span server-side.
         if (cli.flags.server)
-            return runSugarRemote(cli, "nodes_set", { id: nodeId, prop, value }, () => nodeSetEffects(nodeId, prop, value).effects);
+            return runSugarRemote(cli, "nodes_set", { id: nodeId, prop, value }, () => nodeSetEffects(nodeId, prop, value).effects, [nodeId]);
         const ws = cli.workspace();
         const repo = cli.repo(ws);
         return runSugar(cli, ws, repo, nodeSetEffects(requireNode(ws.store, repo.repoId, nodeId), prop, value), values.actor ? { actor: values.actor } : {});

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

@@ -6,7 +6,8 @@ import type { Cli } from "../context.js";
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
  * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document. The truncation footer prints in every mode but `--json`.
+ * document, and so does a `bare` result (its hits carry no envelope). The
+ * truncation footer prints in every mode but `--json`.
  */
-export declare function renderOqxResult(cli: Cli, result: OqxResult): number;
+export declare function renderOqxResult(cli: Cli, result: OqxResult, bare?: boolean): number;
 export declare const cmdOqx: Command;

package/dist/src/cmd/oqx.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
 import { oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { truncationFooter, CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp, renderHits } from "../output.js";
+import { truncationFooter, CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp, renderHits, renderBareHits } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 import { readStdin } from "./_mutate.js";
@@ -31,7 +31,11 @@ import { readStdin } from "./_mutate.js";
 // `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
 // string or -f file|-. Human output: one hit per line (id + path), or an aligned
 // id/path/columns table when the query projects (`select`), or the scalar for
-// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids.
+// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids. `--bare`
+// is the tool's `bare` passed through (ADR-012: a thin client; spec/surface
+// §1.4, 4.2): every hit is its projection alone, rendered as a table without
+// the id/path columns (`--json`/`--jsonl` the bare hits; `--ids` has no id to
+// print and falls back to the document, like a scalar result).
 async function runOqx(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -39,6 +43,7 @@ async function runOqx(cli, args) {
         options: {
             n: { type: "string", short: "n" },
             cursor: { type: "string" },
+            bare: { type: "boolean" },
             file: { type: "string", short: "f" },
             help: { type: "boolean" },
         },
@@ -47,12 +52,13 @@ async function runOqx(cli, args) {
         renderHelp(cli, {
             name: "query",
             summary: "Composable OQX query: [select …] from <docs|blocks|nodes|links> [where …] [follow …] [order by …] [limit N] (alias: q)",
-            usage: ["query <source> [-n <N>] [--cursor <c>] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>]"],
+            usage: ["query <source> [-n <N>] [--cursor <c>] [--bare] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>] [--bare]"],
             options: [
                 ["<source>", "the OQX query text (quote it); `from` may be omitted inside blocks"],
                 ["-f <file|->", "read the query from a file, or stdin with `-`"],
                 ["-n <N>", "page size"],
                 ["--cursor <c>", "continue a truncated result"],
+                ["--bare", "hits as the projection only — no automatic id/path columns (needs a `select`; `values` is the bare-values form)"],
                 ["--ids", `bare ids, one per line — pipe fuel (\`… --ids | ${cli.prog} cat -\`)`],
             ],
             notes: [
@@ -97,6 +103,8 @@ async function runOqx(cli, args) {
         opts.limit = Number(values.n);
     if (values.cursor)
         opts.cursor = values.cursor;
+    if (values.bare)
+        opts.bare = true;
     let result;
     if (cli.flags.server) {
         // Remote: the `query` MCP tool returns the same OqxResult; render unchanged.
@@ -104,6 +112,7 @@ async function runOqx(cli, args) {
             query: source,
             ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
             ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+            ...(opts.bare !== undefined ? { bare: opts.bare } : {}),
         });
     }
     else {
@@ -138,29 +147,40 @@ async function runOqx(cli, args) {
         : result.consumer === "exists" ? result.exists
             : result.consumer === "none" ? result.none
                 : result.values ?? result);
-    return renderOqxResult(cli, result);
+    return renderOqxResult(cli, result, opts.bare === true);
 }
 /**
  * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
  * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document. The truncation footer prints in every mode but `--json`.
+ * document, and so does a `bare` result (its hits carry no envelope). The
+ * truncation footer prints in every mode but `--json`.
  */
-export function renderOqxResult(cli, result) {
+export function renderOqxResult(cli, result, bare = false) {
     const cursor = result.truncated ? result.cursor ?? "" : null;
     if (cli.flags.mode !== "human") {
         const list = result.values ?? (result.consumer === "collect" || result.consumer === "first" || result.consumer === "single" ? result.hits : undefined);
         return emitMachine(cli, result, {
             ...(list ? { items: list } : {}),
-            ...(list && !result.values ? { ids: result.hits.map((h) => h.id) } : {}),
+            ...(list && !result.values && !bare ? { ids: result.hits.map((h) => h.id) } : {}),
             cursor,
         });
     }
+    // Unknown names (spec/surface §1.5, spec/cli §6 `query`): the result's `hints`
+    // — names the query reads that no row of their kind carries — print LAST on
+    // stderr, one dim `  hint: …` line each, in every human rendering (the
+    // machine modes carry the member itself).
+    const { style, io } = cli;
+    const hints = () => {
+        for (const h of result.hints ?? [])
+            io.err(style.dim(`  hint: ${h}`));
+    };
     // Scalar consumers (count/exists/none) have no hits — render the reduction itself.
     if (result.consumer === "count" || result.consumer === "exists" || result.consumer === "none") {
         const scalar = result.consumer === "count" ? String(result.count) : result.consumer === "exists" ? String(result.exists) : String(result.none);
         cli.io.out(scalar);
+        hints();
         return EXIT_OK;
     }
     // A `values` projection has no hits — one bare value per line (strings
@@ -170,16 +190,21 @@ export function renderOqxResult(cli, result) {
             cli.io.out(typeof v === "string" ? v : JSON.stringify(v));
         if (cursor !== null)
             truncationFooter(cli.io, cli.style, cursor);
+        hints();
         return EXIT_OK;
     }
-    const { style, io } = cli;
     if (result.hits.length === 0) {
         io.err(style.dim("  no hits"));
+        hints();
         return EXIT_OK;
     }
-    renderHits(cli, result.hits);
+    if (bare)
+        renderBareHits(cli, result.hits);
+    else
+        renderHits(cli, result.hits);
     if (result.truncated)
         truncationFooter(io, style, result.cursor ?? "");
+    hints();
     return EXIT_OK;
 }
 // `query` (alias `q`) is the single, default query surface — the OQX engine.

package/dist/src/cmd/retarget.js

@@ -2,7 +2,7 @@ import { parseArgs } from "node:util";
 import { applySugar, planEffects, retargetEffects, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { defaultActor, renderPlan as renderPlanDiffs, renderReceipt, unifiedDiffLines } from "./_mutate.js";
-import { remoteCall } from "./_remote.js";
+import { remoteCall, remoteSugar } from "./_remote.js";
 async function runRetarget(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -29,10 +29,11 @@ async function runRetarget(cli, args) {
     // Remote: the `plan` tool previews, `links_retarget` commits server-side.
     if (cli.flags.server) {
         if (!values.apply || cli.flags.dryRun) {
-            const plan = await remoteCall(cli, "plan", { effects: sugar.effects });
+            const plan = await remoteCall(cli, "plan", { effects: sugar.effects, diffs: true });
             return values.apply ? renderPlanDiffs(cli, plan) : renderHits(cli, from, to, retargetOf(plan).hits);
         }
-        const r = await remoteCall(cli, "links_retarget", { from_target: from, to_target: to, ...(values.scope ? { path_glob: values.scope } : {}) });
+        // `links_retarget` where listed (its result adds `hits`/`pairs`), else `apply { retarget }` (spec/cli §2.3, 4.2).
+        const r = await remoteSugar(cli, "links_retarget", { from_target: from, to_target: to, ...(values.scope ? { path_glob: values.scope } : {}) }, () => sugar.effects);
         return renderReceipt(cli, r);
     }
     const ws = cli.workspace();

package/dist/src/cmd/update.js

@@ -1,9 +1,9 @@
 import { parseArgs } from "node:util";
 import { applyEffectsDetailed, planEffects, referencePath, renderIdentityPlan, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
-import { readContent, extractContentOpts, receiptIds, defaultActor } from "./_mutate.js";
+import { readContent, extractContentOpts, receiptIds, defaultActor, renderSummary } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
-import { remoteCall, docLocator, requireDoc } from "./_remote.js";
+import { remoteCall, remoteSugar, 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
@@ -59,10 +59,12 @@ async function runDocUpdate(cli, args) {
         // Remote: the `docs_update` tool commits the `set content` server-side and
         // returns the Receipt (the confirmation then lists the ids it minted, as a
         // remote `apply` does); the dry run is the `plan` tool over the same effect.
+        // A server without `docs_update` (a minimal profile) gets `apply` over the same effect (spec/cli §2.3, 4.2).
+        const setContent = { op: "set", target: { kind: "document", ...docLocator(doc) }, field: "content", value: bytes };
         if (dryRun)
-            plan = await remoteCall(cli, "plan", { effects: [{ op: "set", target: { kind: "document", ...docLocator(doc) }, field: "content", value: bytes }] });
+            plan = await remoteCall(cli, "plan", { effects: [setContent], diffs: true });
         else
-            receipt = await remoteCall(cli, "docs_update", { ...docLocator(doc), content: bytes, ...(values.reason ? { reason: values.reason } : {}) });
+            receipt = await remoteSugar(cli, "docs_update", { ...docLocator(doc), content: bytes, ...(values.reason ? { reason: values.reason } : {}) }, () => [setContent]);
     }
     else {
         const ws = cli.workspace();
@@ -108,6 +110,7 @@ async function runDocUpdate(cli, args) {
     const g = cli.render.g;
     const n = receipt.revisions.length;
     cli.io.err(cli.style.dim(`  ${cli.style.ok(g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
+    renderSummary(cli, receipt.summary);
     for (const id of new Set(receiptIds(receipt, plan)))
         cli.io.out(id);
     return EXIT_OK;

package/dist/src/cmd/version.js

@@ -41,7 +41,7 @@ async function runVersion(cli, args) {
         return emitMachine(cli, info);
     const { io, style } = cli;
     const dash = "—";
-    const keys = ["engine", "version", "specs", "schema", "mcp", "runtime", "commit", "built"];
+    const keys = ["engine", "version", "specs", "schema", "mcp", "runtime", "commit", "built", "profile"];
     const width = Math.max(...keys.map((k) => k.length));
     const line = (key, value) => {
         io.out(`${style.dim(key.padEnd(width))}  ${value === null ? style.dim(dash) : String(value)}`);
@@ -58,6 +58,9 @@ async function runVersion(cli, args) {
     line("runtime", info.runtime);
     line("commit", info.commit);
     line("built", info.built);
+    // The catalog profile served (spec/surface §4 "Profiles", 4.3): `full` for
+    // the library itself; over --server, whatever the remote serves.
+    line("profile", info.profile);
     return EXIT_OK;
 }
 export const cmdVersion = {

package/dist/src/output.d.ts

@@ -103,6 +103,15 @@ export declare function renderHits(cli: {
     io: IO;
     style: Style;
 }, hits: HitLike[]): void;
+/** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
+ *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
+ *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  column, rendered as any other cell — with no envelope columns before them.
+ *  Header row, then one row per hit; cells as the enveloped table's. */
+export declare function renderBareHits(cli: {
+    io: IO;
+    style: Style;
+}, hits: Record<string, unknown>[]): void;
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export declare function truncationFooter(io: IO, style: Style, cursor: number | string): void;
 export {};

package/dist/src/output.js

@@ -231,6 +231,29 @@ export function renderHits(cli, hits) {
     for (const line of columns(rows))
         io.out(line);
 }
+/** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
+ *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
+ *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  column, rendered as any other cell — with no envelope columns before them.
+ *  Header row, then one row per hit; cells as the enveloped table's. */
+export function renderBareHits(cli, hits) {
+    const { io, style } = cli;
+    const cols = [];
+    const seen = new Set();
+    for (const h of hits) {
+        for (const k of Object.keys(h)) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            cols.push(k);
+        }
+    }
+    const rows = [cols.map((c) => style.dim(c))];
+    for (const h of hits)
+        rows.push(cols.map((c) => hitCell(h[c])));
+    for (const line of columns(rows))
+        io.out(line);
+}
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export function truncationFooter(io, style, cursor) {
     io.err(style.dim(`… truncated; continue with --cursor ${cursor}`));

package/package.json

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