@openbkn/bkn-sdk 0.1.3 → 0.1.5-rc.1

package/dist/cli.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
 import {
+  BuildTaskExecuteType,
+  BuildTaskSort,
+  BuildTaskStatus,
   DEFAULT_BUSINESS_DOMAIN,
   DEFAULT_LIST_LIMIT,
   DEFAULT_QUERY_LIMIT,
+  DiscoverScheduleSort,
+  DiscoverStrategy,
+  DiscoverTaskSort,
+  DiscoverTaskTriggerType,
+  DryRunSignal,
   HttpError,
   InputError,
+  SemanticUnderstandingApplyMode,
+  SemanticUnderstandingScope,
+  SemanticUnderstandingTaskSort,
+  SortDirection,
+  VegaTaskStatus,
   activePlatform,
   attachToken,
   changePasswordSafe,
@@ -16,6 +29,7 @@ import {
   decodeJwt,
   deletePlatform,
   deviceLogin,
+  enableDryRun,
   exportCreds,
   filesUnder,
   formatError,
@@ -25,6 +39,7 @@ import {
   listPlatforms,
   logout,
   openBrowser,
+  parseBigIntJSON,
   parseEmbeddingFields,
   parsePkMap,
   rawCall,
@@ -35,21 +50,23 @@ import {
   resolveContext,
   setActivePlatform,
   status,
+  stringifyBigIntJSON,
   switchUser,
   toExitCode,
+  trimTrailingSlashes,
+  updatePlatformConfig,
   use,
   validateFixturePath,
-  whoami,
-  writePlatformConfig
-} from "./chunk-PC2F54XD.js";
+  whoami
+} from "./chunk-WIYRGBAB.js";
 
-// src/cli.ts
-import { Command as Command17 } from "commander";
+// src/cli-program.ts
+import { Command as Command16 } from "commander";
 
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.3",
+  version: "0.1.5-rc.1",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
@@ -81,10 +98,14 @@ var package_default = {
     dev: "tsup --watch",
     typecheck: "tsc --noEmit",
     "check:deps": "node scripts/check-no-self-dep.mjs",
+    "capture:returns": "node scripts/capture-returns.mjs",
     lint: "npm run check:deps && biome check . && tsc --noEmit",
     format: "biome format --write .",
     test: "vitest run",
     "test:e2e:trace-business": "npm run build && node test/e2e/bkn-trace-business-interaction.mjs",
+    "test:e2e:smoke": "npm run build && test/e2e/live-smoke.sh",
+    "test:e2e:suite": "npm run build && test/e2e/live-suite.sh",
+    "test:e2e:write": "npm run build && test/e2e/live-write.sh",
     "test:cover": "vitest run --coverage",
     ci: "npm run lint && npm test",
     prepublishOnly: "npm run ci && npm run build"
@@ -102,7 +123,7 @@ var package_default = {
   devDependencies: {
     "@biomejs/biome": "^1.9.4",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.13.0",
+    "@types/node": "^24.0.0",
     tsup: "^8.4.0",
     typescript: "^5.8.0",
     vitest: "^3.0.0"
@@ -115,14 +136,72 @@ import { Command as Command2 } from "commander";
 
 // src/help/grouped-help.ts
 var GROUP = /* @__PURE__ */ Symbol("openbkn.group");
+var GUIDE = /* @__PURE__ */ Symbol("openbkn.guide");
 var DEFAULT_GROUP = "COMMANDS";
 function group(cmd, name) {
   cmd[GROUP] = name;
   return cmd;
 }
+function guide(cmd, text) {
+  cmd[GUIDE] = text;
+  return cmd;
+}
+var SECTION_ORDER = ["GROUPS", "READ", "RUN", "WRITE"];
+function groupChildren(parent, sections) {
+  for (const [section, names] of Object.entries(sections)) {
+    for (const name of names) {
+      const child = parent.commands.find((c) => c.name() === name);
+      if (child) group(child, section);
+    }
+  }
+}
+var VERB_SECTIONS = [
+  [
+    /^(list|get|show|find|files|history|members|roles|tree|names|content|read-file|status|whoami|users|detail|spans|graph|health|resources|search|market|market-get|stats|export|pull|validate-fixture)$/,
+    "READ"
+  ],
+  [
+    /^(query|execute|debug|run|test|chat|embeddings|rerank|diagnose|scan|discover|build|dry-run|validate|token|download|install|call|sql|receipt|fingerprint|test-connection|test-connection-config|attempt|retry|start|resume|ensure-current|create-new-generation|close|complete|fail|cancel|handoff|operations|build-status|build-list)$/,
+    "RUN"
+  ],
+  [
+    /^(create|update|delete|add|edit|remove|set|register|upload|publish|unpublish|republish|import|activate|login|logout|use|switch|change-password|enable|disable|push|assign-role|revoke-role|add-member|remove-member|reset-password|grant-perm|revoke-perm|add-members|remove-members|set-status|regenerate|revoke|set-bd|list-bd|build-start|build-stop|build-delete|publish-history|update-metadata|update-package|create-from-catalog|export-config)$/,
+    "WRITE"
+  ]
+];
+function autoGroup(parent) {
+  for (const child of parent.commands) {
+    if (child.name().startsWith("help")) continue;
+    if (child[GROUP] !== void 0) continue;
+    if (child.commands.filter((c) => !c.name().startsWith("help")).length > 0) {
+      group(child, "GROUPS");
+      continue;
+    }
+    const verb = VERB_SECTIONS.find(([re]) => re.test(child.name()));
+    if (verb) group(child, verb[1]);
+  }
+}
+function rankOf(name) {
+  if (name === DEFAULT_GROUP) return Number.MAX_SAFE_INTEGER;
+  const i = SECTION_ORDER.indexOf(name);
+  return i === -1 ? SECTION_ORDER.length : i;
+}
 function groupOf(cmd) {
   return cmd[GROUP] ?? DEFAULT_GROUP;
 }
+var SECTION_MEANINGS = {
+  GROUPS: "nested command groups \u2014 one level deeper",
+  READ: "changes nothing",
+  RUN: "acts without changing configuration (triggers a job, spends a model call, rotates a token)",
+  WRITE: "changes platform state \u2014 confirm with a person first",
+  [DEFAULT_GROUP]: "not sorted into a section yet"
+};
+function sectionOf(cmd) {
+  return groupOf(cmd);
+}
+function guideOf(cmd) {
+  return cmd[GUIDE];
+}
 function formatHelp(cmd, helper) {
   const out = [];
   const desc = helper.commandDescription(cmd);
@@ -138,7 +217,8 @@ function formatHelp(cmd, helper) {
       if (bucket) bucket.push(c);
       else sections.set(g, [c]);
     }
-    for (const [name, cmds] of sections) {
+    const ordered = [...sections.entries()].map((entry, index) => ({ entry, index })).sort((a, b) => rankOf(a.entry[0]) - rankOf(b.entry[0]) || a.index - b.index).map(({ entry }) => entry);
+    for (const [name, cmds] of ordered) {
       out.push(name);
       for (const c of cmds) {
         out.push(`  ${helper.subcommandTerm(c).padEnd(width)}  ${helper.subcommandDescription(c)}`);
@@ -146,6 +226,8 @@ function formatHelp(cmd, helper) {
       out.push("");
     }
   }
+  const extra = guideOf(cmd);
+  if (extra) out.push(extra.trim(), "");
   const opts = helper.visibleOptions(cmd);
   if (opts.length > 0) {
     const width = Math.max(...opts.map((o) => helper.optionTerm(o).length));
@@ -158,11 +240,15 @@ function formatHelp(cmd, helper) {
   return out.join("\n");
 }
 function installGroupedHelp(root) {
-  const apply = (cmd) => {
+  const apply = (cmd, path) => {
     cmd.configureHelp({ formatHelp });
-    for (const child of cmd.commands) apply(child);
+    if (cmd !== root) autoGroup(cmd);
+    cmd.showHelpAfterError(
+      path.length ? `Run \`openbkn describe ${path.join(" ")}\` to see its arguments and where their ids come from.` : "Run `openbkn describe --depth 1` for every command, or `openbkn --help` for the guide."
+    );
+    for (const child of cmd.commands) apply(child, [...path, child.name()]);
   };
-  apply(root);
+  apply(root, []);
 }
 
 // src/utils/org-tree.ts
@@ -181,7 +267,7 @@ function renderOrgTree(nodes, prefix = "") {
 // src/utils/output.ts
 function printJson(value, opts = {}) {
   if (opts.json || opts.compact) {
-    const json = JSON.stringify(value === void 0 ? null : value, null, opts.compact ? 0 : 2);
+    const json = stringifyBigIntJSON(value === void 0 ? null : value, opts.compact ? 0 : 2);
     process.stdout.write(`${json}
 `);
     return;
@@ -190,12 +276,12 @@ function printJson(value, opts = {}) {
     process.stdout.write("(ok)\n");
     return;
   }
-  const rows = toRows(value);
-  if (rows) {
-    const fullColumns = columnsOf(rows).filter((c) => rows.some((r) => stringifyCell(r[c]) !== ""));
-    const columns = opts.full ? fullColumns : selectColumns(rows);
+  const rows2 = toRows(value);
+  if (rows2) {
+    const fullColumns = columnsOf(rows2).filter((c) => rows2.some((r) => stringifyCell(r[c]) !== ""));
+    const columns = opts.full ? fullColumns : selectColumns(rows2);
     if (columns.length > 0) {
-      printTable(rows, columns);
+      printTable(rows2, columns);
       const hidden = fullColumns.length - columns.length;
       if (hidden > 0 && !opts.full) {
         process.stdout.write(`\u2026 ${hidden} more column(s); use --full or --json for everything
@@ -208,7 +294,7 @@ function printJson(value, opts = {}) {
     process.stdout.write("(no results)\n");
     return;
   }
-  process.stdout.write(`${JSON.stringify(value, null, 2)}
+  process.stdout.write(`${stringifyBigIntJSON(value, 2)}
 `);
 }
 function isEmptyEnvelope(value) {
@@ -241,9 +327,9 @@ function toRows(value) {
   }
   return null;
 }
-function columnsOf(rows) {
+function columnsOf(rows2) {
   const seen = [];
-  for (const row of rows) {
+  for (const row of rows2) {
     for (const k of Object.keys(row)) if (!seen.includes(k)) seen.push(k);
   }
   return seen;
@@ -264,16 +350,16 @@ var NOISE_COLS = /* @__PURE__ */ new Set([
 ]);
 var isNoiseCol = (c) => NOISE_COLS.has(c) || /_time$/.test(c);
 var isKeyCol = (c) => /^(id|name|key|title|label)$/i.test(c) || /_(id|name|key)$/i.test(c) || /^(status|state|type|category|mode|enabled|version|branch)$/i.test(c);
-function selectColumns(rows) {
+function selectColumns(rows2) {
   const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-  const kept = columnsOf(rows).filter((c) => {
+  const kept = columnsOf(rows2).filter((c) => {
     if (isNoiseCol(c)) return false;
-    const vals = rows.map((r) => r[c]);
+    const vals = rows2.map((r) => r[c]);
     if (!vals.some((v) => stringifyCell(v) !== "")) return false;
     if (vals.every((v) => v === null || v === void 0 || isObj(v))) return false;
     return true;
   });
-  const isLongText = (c) => rows.every((r) => {
+  const isLongText = (c) => rows2.every((r) => {
     const s = stringifyCell(r[c]);
     return s === "" || s.length >= CELL_MAX - 1;
   });
@@ -281,12 +367,12 @@ function selectColumns(rows) {
   const ordered = kept.map((c, i) => ({ c, i, r: rank(c) })).sort((a, b) => a.r - b.r || a.i - b.i).map((x) => x.c);
   return ordered.slice(0, MAX_COLS);
 }
-function printTable(rows, columns, opts = {}) {
+function printTable(rows2, columns, opts = {}) {
   if (opts.json || opts.compact) {
-    printJson(rows, opts);
+    printJson(rows2, opts);
     return;
   }
-  const cells = rows.map((row) => columns.map((c) => stringifyCell(row[c])));
+  const cells = rows2.map((row) => columns.map((c) => stringifyCell(row[c])));
   const widths = columns.map(
     (col, i) => Math.max(displayWidth(col), ...cells.map((r) => displayWidth(r[i] ?? "")))
   );
@@ -307,7 +393,7 @@ function pad(s, width) {
 }
 function stringifyCell(v) {
   if (v === null || v === void 0) return "";
-  const raw = Array.isArray(v) && v.every((x) => x === null || typeof x !== "object") ? v.join(",") : typeof v === "object" ? JSON.stringify(v) : String(v);
+  const raw = Array.isArray(v) && v.every((x) => x === null || typeof x !== "object") ? v.join(",") : typeof v === "object" ? stringifyBigIntJSON(v) : String(v);
   const s = raw.replace(/\s+/g, " ").trim();
   return s.length > CELL_MAX ? `${s.slice(0, CELL_MAX - 1)}\u2026` : s;
 }
@@ -315,7 +401,7 @@ function stringifyCell(v) {
 // src/utils/prompt.ts
 import { createInterface } from "readline";
 function promptLine(query, hidden = false) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     if (hidden) {
       const mutable = rl;
@@ -326,15 +412,33 @@ function promptLine(query, hidden = false) {
     rl.question(query, (answer) => {
       rl.close();
       if (hidden) process.stdout.write("\n");
-      resolve2(answer.trim());
+      resolve3(answer.trim());
     });
   });
 }
 
 // src/commands/_shared.ts
 import { readFileSync } from "fs";
+function platformOf(o) {
+  const baseUrl = (typeof o.baseUrl === "string" ? o.baseUrl : void 0) ?? process.env.BKN_BASE_URL ?? activePlatform();
+  return baseUrl === void 0 ? void 0 : trimTrailingSlashes(baseUrl);
+}
+function transientIdentity(o) {
+  return Boolean(o.user || process.env.BKN_USER || o.token || process.env.BKN_TOKEN);
+}
+function conversationSource(o) {
+  const flag = typeof o.conversationId === "string" ? o.conversationId : void 0;
+  if (flag) return { id: flag, source: "flag" };
+  const env = process.env.BKN_CONVERSATION_ID;
+  if (env) return { id: env, source: "env" };
+  if (o.newConversation || transientIdentity(o)) return { source: "none" };
+  const baseUrl = platformOf(o);
+  const stored = baseUrl ? readPlatformConfig(baseUrl).conversationId : void 0;
+  return stored ? { id: stored, source: "stored" } : { source: "none" };
+}
 function traceOptionsFrom(o) {
-  const conversationId = (typeof o.conversationId === "string" ? o.conversationId : void 0) ?? process.env.BKN_CONVERSATION_ID;
+  const found = conversationSource(o);
+  const conversationId = found.source === "stored" ? void 0 : found.id;
   const interactionId = (typeof o.interactionId === "string" ? o.interactionId : void 0) ?? process.env.BKN_INTERACTION_ID;
   if (!conversationId && !interactionId) return void 0;
   return {
@@ -345,14 +449,36 @@ function traceOptionsFrom(o) {
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
   const trace = traceOptionsFrom(o);
-  return createClient({
+  const storeBaseUrl = platformOf(o);
+  const remembered = conversationSource(o);
+  const client = createClient({
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
     businessDomain: o.bizDomain,
     insecure: o.insecure,
-    ...trace ? { trace } : {}
+    ...trace ? { trace } : {},
+    ...remembered.source === "stored" && remembered.id ? { rememberedConversationId: remembered.id } : {},
+    // Remember a conversation this run opens, so the next command continues the
+    // same thread instead of starting a new one. Only for the active identity —
+    // `transientIdentity` explains which identities are left out.
+    // `--new-conversation` says "for this command", so it must not replace what
+    // it declined to use — otherwise one run with the flag would silently end
+    // the thread every other run was continuing.
+    ...transientIdentity(o) || o.newConversation ? {} : {
+      onConversationOpened: (conversationId) => {
+        if (!storeBaseUrl) return;
+        try {
+          updatePlatformConfig(storeBaseUrl, {
+            conversationId,
+            conversationOpenedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch {
+        }
+      }
+    }
   });
+  return client;
 }
 function outputOptions(cmd) {
   const o = cmd.optsWithGlobals();
@@ -366,7 +492,7 @@ function readBody(opts) {
   const raw = opts.bodyFile ? readFileSync(opts.bodyFile, "utf8") : opts.body;
   if (!raw) throw new InputError("Provide --body '<json>' or --body-file <path>.");
   try {
-    return JSON.parse(raw);
+    return parseBigIntJSON(raw);
   } catch {
     throw new InputError("Request body is not valid JSON.");
   }
@@ -520,16 +646,16 @@ User code: ${userCode}
     }
     const expMs = typeof me.exp === "number" ? me.exp * 1e3 : void 0;
     const expired = expMs !== void 0 && expMs < Date.now();
-    const rows = [
+    const rows2 = [
       ["User", String(me.username ?? me.sub ?? "(unknown)")],
       ...me.name && me.name !== me.username ? [["Name", String(me.name)]] : [],
       ["ID", String(me.userId ?? me.sub ?? "-")],
       ["Platform", String(me.baseUrl ?? "-")],
       ...expMs !== void 0 ? [["Expires", `${new Date(expMs).toISOString()}${expired ? " (expired)" : ""}`]] : []
     ];
-    const pad2 = Math.max(...rows.map(([k]) => k.length));
+    const pad2 = Math.max(...rows2.map(([k]) => k.length));
     process.stdout.write(
-      `${rows.map(([k, v]) => `${k.padEnd(pad2)}  ${v}`).join("\n")}
+      `${rows2.map(([k, v]) => `${k.padEnd(pad2)}  ${v}`).join("\n")}
 \u2026 use --full or --json for all claims
 `
     );
@@ -557,7 +683,7 @@ User code: ${userCode}
 `);
   });
   cmd.command("users <url>").description("List saved users for a platform (* = active)").action((url, _opts, cmd2) => {
-    const norm = url.replace(/\/+$/, "");
+    const norm = trimTrailingSlashes(url);
     const items = listPlatforms().filter((i) => i.baseUrl === norm);
     const out = outputOptions(cmd2);
     if (out.json || out.compact) printJson(items, out);
@@ -601,9 +727,33 @@ User code: ${userCode}
   });
 }
 function authCommand() {
-  const cmd = new Command("auth").description("Login, session, and token management");
+  const cmd = new Command("auth").description("Log in; the token is saved and reused. Start here.");
   registerAuthLeaves(cmd);
-  return group(cmd, "AUTHENTICATION & CONFIG");
+  groupChildren(cmd, {
+    READ: ["status", "whoami", "list", "users"],
+    RUN: ["token", "export"],
+    WRITE: ["login", "logout", "use", "switch", "delete", "change-password"]
+  });
+  guide(
+    cmd,
+    `WAYS IN
+  login <url> -u <user> -p <pass>   password, no browser
+  login <url> --token <token>       a token you already hold (CI)
+  login <url> --device              device code, for a host with no browser
+  login <url>                       opens a browser; --no-browser prints the URL instead
+
+MANY PLATFORMS, MANY USERS
+  A session is a platform plus a user. \`use <url>\` changes which platform is
+  active; \`switch <url> <user>\` changes which saved user is active on one.
+  \`list\` shows both, marking the active pair. \`--user\` on any command borrows a
+  saved user for that call alone.
+
+TOKENS
+  \`token\` prints the access token, refreshing it first if it has expired;
+  \`--no-refresh\` prints what is stored. \`export\` hands the whole session to a
+  headless host. Both write a secret to stdout.`
+  );
+  return group(cmd, "SIGN IN & SETTINGS");
 }
 
 // src/commands/admin.ts
@@ -616,10 +766,10 @@ async function importLicenseFile(cmd, file, receipt) {
   if ("stored" in res && res.stored) process.exitCode = 1;
 }
 function adminCommand() {
-  const admin = new Command2("admin").description("Operator CLI: org, user, role, models, audit");
+  const admin = new Command2("admin").description("Orgs, users, roles, license, audit log");
   registerAuthLeaves(admin.command("auth").description("Operator authentication"));
   const org = admin.command("org").description("Departments and org structure");
-  org.command("list").description("List departments").option("--role <r>", "role qualifier", "super_admin").option("--name <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
+  org.command("list").description("List departments \u2192 {departments, total}").option("--role <r>", "role qualifier", "super_admin").option("--name <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.orgList({
         role: opts.role,
@@ -680,7 +830,7 @@ function adminCommand() {
     else console.log(renderOrgTree(tree));
   });
   const user = admin.command("user").description("User management");
-  user.command("list").description("List users").option("--org <id>", "filter by department id").option("--keyword <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
+  user.command("list").description("List users \u2192 {users, total}").option("--org <id>", "filter by department id").option("--keyword <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.userList({
         orgId: opts.org,
@@ -766,7 +916,7 @@ function adminCommand() {
       );
   });
   const role = admin.command("role").description("Role management");
-  role.command("list").description("List roles").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).option("--source <s>", "role source filter (business | user)").action(async (opts, cmd) => {
+  role.command("list").description("List roles \u2192 {roles}").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).option("--source <s>", "role source filter (business | user)").action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.roleList({ keyword: opts.keyword, limit: opts.limit }),
       outputOptions(cmd)
@@ -868,7 +1018,10 @@ function adminCommand() {
     m.command("get <modelid>").description(`Get a ${kind} model`).action(async (id, _opts, cmd) => {
       printJson(await clientFrom(cmd).models[ns].get(id), outputOptions(cmd));
     });
-    const add = m.command("add").description(`Register a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option("--api-model <s>", "upstream API model id").option("--api-key <s>", "upstream API key").option("--body <json>", "model config JSON (overrides flags)").option("--body-file <path>", "read config JSON from a file");
+    const add = m.command("add").description(`Register a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option("--api-model <s>", "upstream API model id").option("--api-key <s>", "upstream API key").option(
+      "--body <json>",
+      "model config JSON (overrides flags) \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+    ).option("--body-file <path>", "read config JSON from a file");
     if (isLlm) {
       add.option("--series <s>", "model series").option("--api-base <url>", "upstream API base URL").option("--icon <url>", "icon URL");
     } else {
@@ -877,7 +1030,10 @@ function adminCommand() {
     add.action(async (opts, cmd) => {
       printJson(await clientFrom(cmd).models[ns].add(modelBody(opts)), outputOptions(cmd));
     });
-    const edit = m.command("edit <modelid>").description(`Edit a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option("--body <json>", "model config JSON (overrides flags)").option("--body-file <path>", "read config JSON from a file");
+    const edit = m.command("edit <modelid>").description(`Edit a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option(
+      "--body <json>",
+      "model config JSON (overrides flags) \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+    ).option("--body-file <path>", "read config JSON from a file");
     if (isLlm) {
       edit.option("--icon <url>", "icon URL");
     } else {
@@ -892,7 +1048,10 @@ function adminCommand() {
     m.command("delete <modelid...>").description(`Delete ${kind} model(s)`).action(async (ids, _opts, cmd) => {
       printJson(await clientFrom(cmd).models[ns].delete(ids), outputOptions(cmd));
     });
-    m.command("test <modelid>").description(`Test a ${kind} model`).option("--body <json>", "test request JSON").option("--body-file <path>", "read test request JSON from a file").action(async (id, opts, cmd) => {
+    m.command("test <modelid>").description(`Test a ${kind} model`).option(
+      "--body <json>",
+      "test request JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+    ).option("--body-file <path>", "read test request JSON from a file").action(async (id, opts, cmd) => {
       const body = opts.body || opts.bodyFile ? readBody(opts) : {};
       printJson(
         await clientFrom(cmd).models[ns].test({ model_id: id, ...body }),
@@ -941,10 +1100,12 @@ function adminCommand() {
     if (key !== "baseUrl") {
       throw new Error(`Unknown config key: ${key} (only baseUrl supported)`);
     }
-    setActivePlatform(value.replace(/\/+$/, ""));
+    setActivePlatform(trimTrailingSlashes(value));
     printJson({ ok: true, baseUrl: value }, outputOptions(cmd));
   });
-  admin.command("call <url>").description("Operator API passthrough (curl-style; auto-injected auth)").option("-X, --request <method>", "HTTP method").option(
+  admin.command("call <url>").description(
+    "Operator API passthrough (curl-style; auto-injected auth) \u2014 paths at https://openbkn-ai.github.io/bkn-foundry/"
+  ).option("-X, --request <method>", "HTTP method").option(
     "-H, --header <header>",
     'extra header "Name: value" (repeatable)',
     (v, a) => {
@@ -967,132 +1128,23 @@ function adminCommand() {
     );
     const out = outputOptions(cmd);
     try {
-      printJson(JSON.parse(res.body), out);
+      printJson(parseBigIntJSON(res.body), out);
     } catch {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
     }
     if (res.status >= 400) process.exitCode = 1;
   });
-  return group(admin, "OPERATOR");
-}
-
-// src/commands/agent.ts
-import { Command as Command3 } from "commander";
-var int2 = (v) => Number.parseInt(v, 10);
-function agentCommand() {
-  const cmd = new Command3("agent").description(
-    "[DEPRECATED] Decision Agent \u2014 CRUD, chat, sessions, publish (being phased out)"
-  );
-  cmd.hook("preAction", () => {
-    process.stderr.write(
-      "\u26A0\uFE0F  `openbkn agent` is deprecated and may be removed in a future release.\n"
-    );
-  });
-  cmd.command("list").description("List published agents").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).option("--category-id <id>", "filter by category").action(async (opts, cmd2) => {
-    const data = await clientFrom(cmd2).agents.list({
-      name: opts.name,
-      limit: opts.limit,
-      offset: opts.offset,
-      categoryId: opts.categoryId
-    });
-    printJson(data, outputOptions(cmd2));
-  });
-  cmd.command("personal-list").description("List personal-space agents").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).action(async (opts, cmd2) => {
-    const data = await clientFrom(cmd2).agents.personalList({
-      name: opts.name,
-      limit: opts.limit,
-      offset: opts.offset
-    });
-    printJson(data, outputOptions(cmd2));
-  });
-  cmd.command("category-list").description("List agent categories").action(async (_opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.categoryList(), outputOptions(cmd2));
-  });
-  cmd.command("template-list").description("List published agent templates").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).action(async (opts, cmd2) => {
-    const data = await clientFrom(cmd2).agents.templateList({
-      name: opts.name,
-      limit: opts.limit,
-      offset: opts.offset
-    });
-    printJson(data, outputOptions(cmd2));
-  });
-  cmd.command("template-get <id>").description("Get a published agent template").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.templateGet(id), outputOptions(cmd2));
-  });
-  cmd.command("get <id>").description("Get agent details").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.get(id), outputOptions(cmd2));
-  });
-  cmd.command("get-by-key <key>").description("Get an agent by key").action(async (key, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.getByKey(key), outputOptions(cmd2));
-  });
-  cmd.command("create").description("Create an agent (--body-file <json> or --body '<json>')").option("--body <json>", "agent definition JSON").option("--body-file <path>", "read agent definition JSON from a file").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.create(readBody(opts)), outputOptions(cmd2));
-  });
-  cmd.command("update <id>").description("Update an agent (--body-file <json> or --body '<json>')").option("--body <json>", "agent definition JSON").option("--body-file <path>", "read agent definition JSON from a file").action(async (id, opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.update(id, readBody(opts)), outputOptions(cmd2));
-  });
-  cmd.command("delete <id>").description("Delete an agent").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.delete(id), outputOptions(cmd2));
-  });
-  cmd.command("publish <id>").description("Publish an agent").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.publish(id), outputOptions(cmd2));
-  });
-  cmd.command("unpublish <id>").description("Unpublish an agent").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.unpublish(id), outputOptions(cmd2));
-  });
-  cmd.command("sessions <agent>").description("List conversations for an agent (by agent key)").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int2, 1).action(async (agentKey, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).agents.sessions(agentKey, { size: opts.limit, page: opts.page }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("history <agent> <conversation-id>").description("Show message history for a conversation").action(async (agentKey, conversationId, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.history(agentKey, conversationId), outputOptions(cmd2));
-  });
-  cmd.command("chat <agent-id>").description("Chat with an agent (SSE streaming with --stream)").requiredOption("-m, --message <text>", "user message").option("--version <v>", "agent version", "v0").option("--conversation-id <id>", "continue an existing conversation").option("--stream", "stream the reply to stdout as it arrives").action(async (agentId, opts, cmd2) => {
-    const client = clientFrom(cmd2);
-    if (opts.stream) {
-      const res = await client.agents.chat(agentId, opts.message, {
-        version: opts.version,
-        conversationId: opts.conversationId,
-        stream: true,
-        onDelta: (t) => process.stdout.write(t)
-      });
-      process.stdout.write("\n");
-      if (res.conversationId) console.error(`conversation_id: ${res.conversationId}`);
-      return;
-    }
-    printJson(
-      await client.agents.chat(agentId, opts.message, {
-        version: opts.version,
-        conversationId: opts.conversationId
-      }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("trace <conversation-id>").description("Get trace spans for a conversation (agent-scoped alias of `trace get`)").action(async (conversationId, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).trace.spans(conversationId), outputOptions(cmd2));
-  });
-  const skill = cmd.command("skill").description("Manage skills attached to an agent");
-  skill.command("list <agent-id>").description("List skill ids attached to an agent").action(async (agentId, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.skillList(agentId), outputOptions(cmd2));
-  });
-  skill.command("add <agent-id> <skill-ids>").description("Attach skill(s) to an agent (comma-joined ids)").action(async (agentId, ids, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).agents.skillAdd(agentId, csv(ids) ?? []), outputOptions(cmd2));
-  });
-  skill.command("remove <agent-id> <skill-ids>").description("Detach skill(s) from an agent (comma-joined ids)").action(async (agentId, ids, _opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).agents.skillRemove(agentId, csv(ids) ?? []),
-      outputOptions(cmd2)
-    );
+  groupChildren(admin, {
+    GROUPS: ["org", "user", "role", "llm", "small-model", "license", "audit", "auth", "config"],
+    RUN: ["call"]
   });
-  return group(cmd, "DECISION AGENT");
+  return group(admin, "ADMINISTRATION");
 }
 
 // src/commands/appkey.ts
-import { Command as Command4 } from "commander";
-var int3 = (v) => Number.parseInt(v, 10);
+import { Command as Command3 } from "commander";
+var int2 = (v) => Number.parseInt(v, 10);
 var DAY_MS = 864e5;
 function printNewKey(created, out) {
   if (out.json || out.compact) {
@@ -1114,13 +1166,13 @@ function printNewKey(created, out) {
 `);
 }
 function appkeyCommand() {
-  const appkey = new Command4("appkey").description(
-    "AppKeys \u2014 user-issued long-lived credentials (bak_) for the Context Loader"
+  const appkey = new Command3("appkey").description(
+    "Issue long-lived `bak_` keys for scripts and services"
   );
-  appkey.command("list").description("List your own AppKeys (no secrets)").action(async (_opts, cmd) => {
+  appkey.command("list").description("List your own AppKeys, no secrets \u2192 {keys}").action(async (_opts, cmd) => {
     printJson(await clientFrom(cmd).appKeys.list(), outputOptions(cmd));
   });
-  appkey.command("create").description("Issue an AppKey \u2014 the plaintext key is shown ONCE, on create").requiredOption("--name <s>", "display name (to tell keys apart)").option("--expires-at <rfc3339>", "expiry as RFC3339 (e.g. 2027-01-01T00:00:00Z)").option("--expire-days <n>", "expiry in N days from now (alternative to --expires-at)", int3).option("--never-expire", "never expire (wins over --expires-at/--expire-days)").action(async (opts, cmd) => {
+  appkey.command("create").description("Issue an AppKey \u2014 the plaintext key is shown ONCE, on create").requiredOption("--name <s>", "display name (to tell keys apart)").option("--expires-at <rfc3339>", "expiry as RFC3339 (e.g. 2027-01-01T00:00:00Z)").option("--expire-days <n>", "expiry in N days from now (alternative to --expires-at)", int2).option("--never-expire", "never expire (wins over --expires-at/--expire-days)").action(async (opts, cmd) => {
     let expiresAt = opts.expiresAt;
     if (opts.expireDays !== void 0) {
       if (!Number.isFinite(opts.expireDays) || opts.expireDays <= 0) {
@@ -1154,11 +1206,18 @@ function appkeyCommand() {
     await clientFrom(cmd).appKeys.adminRevoke(id);
     printJson({ revoked: id }, outputOptions(cmd));
   });
-  return group(appkey, "AUTHENTICATION & CONFIG");
+  groupChildren(appkey, {
+    GROUPS: ["admin"],
+    READ: ["list"],
+    WRITE: ["create", "regenerate", "revoke"]
+  });
+  const appkeyAdmin = appkey.commands.find((c) => c.name() === "admin");
+  if (appkeyAdmin) groupChildren(appkeyAdmin, { READ: ["list"], WRITE: ["revoke"] });
+  return group(appkey, "SIGN IN & SETTINGS");
 }
 
 // src/commands/bkn.ts
-import { Command as Command5 } from "commander";
+import { Command as Command4 } from "commander";
 
 // src/utils/bkn-validate.ts
 import { existsSync, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
@@ -1276,10 +1335,12 @@ function validateBknDirectory(dirPath) {
 }
 
 // src/commands/bkn.ts
-var int4 = (v) => Number.parseInt(v, 10);
+var int3 = (v) => Number.parseInt(v, 10);
 function bknCommand() {
-  const bkn = new Command5("bkn").description("Knowledge networks \u2014 list, query, schema, instances");
-  bkn.command("list").description("List knowledge networks").option("--limit <n>", "page size", int4, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int4, 0).option("--name-pattern <s>", "filter by name pattern").option("--tag <s>", "filter by tag").option("--sort <field>", "sort field", "update_time").option("--direction <dir>", "asc | desc", "desc").action(async (_opts, cmd) => {
+  const bkn = new Command4("bkn").description(
+    "Knowledge networks: schema, metrics, search, import/export"
+  );
+  bkn.command("list").description("List knowledge networks").option("--limit <n>", "page size", int3, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int3, 0).option("--name-pattern <s>", "filter by name pattern").option("--tag <s>", "filter by tag").option("--sort <field>", "sort field", "update_time").option("--direction <dir>", "asc | desc", "desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).kn.list({
       limit: o.limit,
@@ -1298,10 +1359,17 @@ function bknCommand() {
     });
     printJson(data, outputOptions(cmd));
   });
-  bkn.command("search <kn-id> <query>").description("Semantic search within a knowledge network").option("--max-concepts <n>", "max concepts to return", int4, 10).option("--mode <mode>", "retrieval mode", "keyword_vector_retrieval").action(async (knId, query, opts, cmd) => {
+  bkn.command("search <kn-id> <query>").description(
+    "Recall instances from a plain sentence \u2014 no object type or field names needed \u2192 {nodes, object_types}"
+  ).option("--object-types <ids>", "pin recall to these object-type ids (comma-separated)").option("--exclude-object-types <ids>", "drop these object-type ids (comma-separated)").option("--concept-groups <names>", "limit recall to these concept groups (comma-separated)").option("--max-object-types <n>", "how many object types may take part", int3).option("--max-instances <n>", "instances per object type", int3).option("--rerank", "re-rank hits with a cross-encoder (needs a rerank model deployed)").option("--no-object-types-detail", "omit the object-type definitions that come with hits").action(async (knId, query, opts, cmd) => {
     const data = await clientFrom(cmd).kn.search(knId, query, {
-      maxConcepts: opts.maxConcepts,
-      mode: opts.mode
+      objectTypes: csv(opts.objectTypes),
+      excludeObjectTypes: csv(opts.excludeObjectTypes),
+      conceptGroups: csv(opts.conceptGroups),
+      maxObjectTypes: opts.maxObjectTypes,
+      maxInstancesPerType: opts.maxInstances,
+      rerank: opts.rerank,
+      includeObjectTypes: opts.objectTypesDetail === false ? false : void 0
     });
     printJson(data, outputOptions(cmd));
   });
@@ -1319,16 +1387,22 @@ function bknCommand() {
       );
     });
     if (crud) {
-      g.command("get <kn-id> <id>").description(`Get ${name}`).action(async (knId, id, _o, cmd) => {
+      g.command("get <kn-id> <id>").description(`Get ${name} \u2192 {entries}`).action(async (knId, id, _o, cmd) => {
         printJson(await clientFrom(cmd).kn[`${crud}Get`](knId, id), outputOptions(cmd));
       });
-      g.command("create <kn-id>").description(`Create ${name} (--body / --body-file)`).option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+      g.command("create <kn-id>").description(`Create ${name} (--body / --body-file)`).option(
+        "--body <json>",
+        "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+      ).option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
         printJson(
           await clientFrom(cmd).kn[`${crud}Create`](knId, readBody(opts)),
           outputOptions(cmd)
         );
       });
-      g.command("update <kn-id> <id>").description(`Update ${name} (--body / --body-file)`).option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
+      g.command("update <kn-id> <id>").description(`Update ${name} (--body / --body-file)`).option(
+        "--body <json>",
+        "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+      ).option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
         printJson(
           await clientFrom(cmd).kn[`${crud}Update`](knId, id, readBody(opts)),
           outputOptions(cmd)
@@ -1340,21 +1414,24 @@ function bknCommand() {
     }
   }
   const actionType = bkn.commands.find((c) => c.name() === "action-type");
-  actionType?.command("query <kn-id> <at-id>").description("Query an action type (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, atId, opts, cmd) => {
+  actionType?.command("query <kn-id> <at-id>").description("Query an action type (--body / --body-file JSON)").option(
+    "--body <json>",
+    "query JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read query JSON from a file").action(async (knId, atId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionTypeQuery(knId, atId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  actionType?.command("execute <kn-id> <at-id>").description("Execute an action type (--body / --body-file envelope JSON)").option("--body <json>", "execution envelope JSON").option("--body-file <path>", "read envelope JSON from a file").action(async (knId, atId, opts, cmd) => {
+  actionType?.command("execute <kn-id> <at-id>").description("Execute an action type (--body / --body-file envelope JSON)").option(
+    "--body <json>",
+    "execution envelope JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read envelope JSON from a file").action(async (knId, atId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionTypeExecute(knId, atId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  actionType?.command("inputs <kn-id> <at-id>").description("Get an action type's input schema").action(async (knId, atId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.actionTypeInputs(knId, atId), outputOptions(cmd));
-  });
   actionType?.command("get <kn-id> <at-id>").description("Get an action type").action(async (knId, atId, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.actionTypeGet(knId, atId), outputOptions(cmd));
   });
@@ -1365,7 +1442,10 @@ function bknCommand() {
     printJson(await clientFrom(cmd).kn.get(knId, { exportMode: true }), outputOptions(cmd));
   });
   const objectType = bkn.commands.find((c) => c.name() === "object-type");
-  objectType?.command("query <kn-id> <ot-id>").description("Query instances of an object type (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, otId, opts, cmd) => {
+  objectType?.command("query <kn-id> <ot-id>").description("Query instances of an object type (--body / --body-file JSON)").option(
+    "--body <json>",
+    "query JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read query JSON from a file").action(async (knId, otId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.objectTypeQuery(knId, otId, readBody(opts)),
       outputOptions(cmd)
@@ -1374,17 +1454,23 @@ function bknCommand() {
   bkn.command("create <name>").description("Create an (empty) knowledge network").option("--branch <b>", "branch", "main").action(async (name, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.create({ name, branch: opts.branch }), outputOptions(cmd));
   });
-  bkn.command("update <kn-id>").description("Update a knowledge network (--body / --body-file)").option("--body <json>", "update body JSON").option("--body-file <path>", "read update body JSON from a file").action(async (knId, opts, cmd) => {
+  bkn.command("update <kn-id>").description("Update a knowledge network (--body / --body-file)").option(
+    "--body <json>",
+    "update body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read update body JSON from a file").action(async (knId, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.update(knId, readBody(opts)), outputOptions(cmd));
   });
   bkn.command("delete <kn-id>").description("Delete a knowledge network").option("-y, --yes", "skip confirmation").action(async (knId, _opts, cmd) => {
     printJson(await clientFrom(cmd).kn.delete(knId), outputOptions(cmd));
   });
-  bkn.command("subgraph <kn-id>").description("Query a subgraph (--body / --body-file JSON)").option("--body <json>", "subgraph query JSON").option("--body-file <path>", "read subgraph query JSON from a file").action(async (knId, opts, cmd) => {
+  bkn.command("subgraph <kn-id>").description("Query a subgraph (--body / --body-file JSON)").option(
+    "--body <json>",
+    "subgraph query JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read subgraph query JSON from a file").action(async (knId, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.subgraph(knId, readBody(opts)), outputOptions(cmd));
   });
-  const actionLog = bkn.command("action-log").description("Action logs \u2014 list/get/cancel");
-  actionLog.command("list <kn-id>").description("List action logs").option("--status <s>", "filter by status").option("--action-type-id <id>", "filter by action type").option("--limit <n>", "page size", int4, DEFAULT_LIST_LIMIT).action(async (knId, opts, cmd) => {
+  const actionLog = bkn.command("action-log").description("Action logs \u2014 list/get/cancel; list pages with search_after");
+  actionLog.command("list <kn-id>").description("List action logs").option("--status <s>", "filter by status").option("--action-type-id <id>", "filter by action type").option("--limit <n>", "page size", int3, DEFAULT_LIST_LIMIT).action(async (knId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionLogs(knId, {
         status: opts.status,
@@ -1404,25 +1490,37 @@ function bknCommand() {
     printJson(await clientFrom(cmd).kn.actionExecution(knId, execId), outputOptions(cmd));
   });
   const metric = bkn.command("metric").description("Metrics \u2014 query / dry-run");
-  metric.command("query <kn-id> <metric-id>").description("Query a metric's data (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, metricId, opts, cmd) => {
+  metric.command("query <kn-id> <metric-id>").description("Query a metric's data (--body / --body-file JSON)").option(
+    "--body <json>",
+    "query JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read query JSON from a file").action(async (knId, metricId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.metricQuery(knId, metricId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  metric.command("dry-run <kn-id>").description("Dry-run a metric definition (--body / --body-file JSON)").option("--body <json>", "metric definition JSON").option("--body-file <path>", "read metric definition JSON from a file").action(async (knId, opts, cmd) => {
+  metric.command("dry-run <kn-id>").description("Dry-run a metric definition (--body / --body-file JSON)").option(
+    "--body <json>",
+    "metric definition JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (ontology-query)"
+  ).option("--body-file <path>", "read metric definition JSON from a file").action(async (knId, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.metricDryRun(knId, readBody(opts)), outputOptions(cmd));
   });
   metric.command("list <kn-id>").description("List metrics").action(async (knId, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.metricList(knId), outputOptions(cmd));
   });
-  metric.command("get <kn-id> <metric-id>").description("Get a metric").action(async (knId, id, _o, cmd) => {
+  metric.command("get <kn-id> <metric-id>").description("Get a metric \u2192 {entries}, since the route takes a list of ids").action(async (knId, id, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.metricGet(knId, id), outputOptions(cmd));
   });
-  metric.command("create <kn-id>").description("Create a metric (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+  metric.command("create <kn-id>").description("Create a metric (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.metricCreate(knId, readBody(opts)), outputOptions(cmd));
   });
-  metric.command("update <kn-id> <metric-id>").description("Update a metric (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
+  metric.command("update <kn-id> <metric-id>").description("Update a metric (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.metricUpdate(knId, id, readBody(opts)),
       outputOptions(cmd)
@@ -1431,10 +1529,10 @@ function bknCommand() {
   metric.command("delete <kn-id> <metric-id>").description("Delete a metric").action(async (knId, id, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.metricDelete(knId, id), outputOptions(cmd));
   });
-  metric.command("search <kn-id>").description("Search metrics (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.metricSearch(knId, readBody(opts)), outputOptions(cmd));
-  });
-  metric.command("validate <kn-id>").description("Validate a metric definition (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+  metric.command("validate <kn-id>").description("Validate a metric definition (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.metricValidate(knId, readBody(opts)), outputOptions(cmd));
   });
   const cg = bkn.command("concept-group").description("Concept groups \u2014 list/get");
@@ -1444,13 +1542,19 @@ function bknCommand() {
   cg.command("get <kn-id> <cg-id>").description("Get a concept group").action(async (knId, cgId, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.conceptGroup(knId, cgId), outputOptions(cmd));
   });
-  cg.command("create <kn-id>").description("Create a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+  cg.command("create <kn-id>").description("Create a concept group (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.conceptGroupCreate(knId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  cg.command("update <kn-id> <cg-id>").description("Update a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
+  cg.command("update <kn-id> <cg-id>").description("Update a concept group (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.conceptGroupUpdate(knId, cgId, readBody(opts)),
       outputOptions(cmd)
@@ -1459,7 +1563,10 @@ function bknCommand() {
   cg.command("delete <kn-id> <cg-id>").description("Delete a concept group").action(async (knId, cgId, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.conceptGroupDelete(knId, cgId), outputOptions(cmd));
   });
-  cg.command("add-members <kn-id> <cg-id>").description("Add object types to a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
+  cg.command("add-members <kn-id> <cg-id>").description("Add object types to a concept group (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.conceptGroupAddMembers(knId, cgId, readBody(opts)),
       outputOptions(cmd)
@@ -1478,19 +1585,28 @@ function bknCommand() {
   sched.command("get <kn-id> <schedule-id>").description("Get an action schedule").action(async (knId, sId, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.actionSchedule(knId, sId), outputOptions(cmd));
   });
-  sched.command("create <kn-id>").description("Create an action schedule (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+  sched.command("create <kn-id>").description("Create an action schedule (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionScheduleCreate(knId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  sched.command("update <kn-id> <schedule-id>").description("Update an action schedule (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
+  sched.command("update <kn-id> <schedule-id>").description("Update an action schedule (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionScheduleUpdate(knId, sId, readBody(opts)),
       outputOptions(cmd)
     );
   });
-  sched.command("set-status <kn-id> <schedule-id>").description("Set an action schedule's status (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
+  sched.command("set-status <kn-id> <schedule-id>").description("Set an action schedule's status (--body / --body-file)").option(
+    "--body <json>",
+    "body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionScheduleSetStatus(knId, sId, readBody(opts)),
       outputOptions(cmd)
@@ -1500,8 +1616,8 @@ function bknCommand() {
     printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
   });
   bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
-    "--embedding-model <id>",
-    "embedding model id for declared vector indexes (with --build)"
+    "--embedding-model <name-or-id>",
+    "small-model name (or numeric ID, resolved to its name) for declared vector indexes (with --build)"
   ).action(async (dir, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.push(dir, {
@@ -1518,7 +1634,10 @@ function bknCommand() {
       outputOptions(cmd)
     );
   });
-  bkn.command("relation-type-paths <kn-id>").description("Query relation-type paths between object types (--body / --body-file JSON)").option("--body <json>", "request JSON").option("--body-file <path>", "read request JSON from a file").action(async (knId, opts, cmd) => {
+  bkn.command("relation-type-paths <kn-id>").description("Query relation-type paths between object types (--body / --body-file JSON)").option(
+    "--body <json>",
+    "request JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+  ).option("--body-file <path>", "read request JSON from a file").action(async (knId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.relationTypePaths(knId, readBody(opts)),
       outputOptions(cmd)
@@ -1530,7 +1649,10 @@ function bknCommand() {
   bkn.command("create-from-catalog <catalog-id>").description("Build a knowledge network from a Vega catalog's tables").requiredOption("--name <name>", "knowledge network name").option("--tables <list>", "comma-separated table names (default: all)").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,<table>:<col>...]'").option("--build", "submit a Vega build task per resource after creation").option(
     "--embedding-fields <map>",
     "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
-  ).option("--embedding-model <id>", "embedding model id for the vector index (with --build)").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
+  ).option(
+    "--embedding-model <name-or-id>",
+    "small-model name (or numeric ID, resolved to its name) for the vector index (with --build)"
+  ).option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.createFromCatalog({
         catalogId,
@@ -1551,39 +1673,73 @@ function bknCommand() {
     printJson(result, outputOptions(cmd));
     if (!result.valid) process.exitCode = 1;
   });
-  bkn.command("create-from-csv <catalog-id>").description("Import CSV files into a Vega catalog, then build a KN from them").requiredOption("--files <glob>", "CSV paths (comma-separated or glob)").requiredOption("--name <name>", "knowledge network name").option("--table-prefix <s>", "prefix for derived table names", "").option("--batch-size <n>", "rows per insert batch", int4, 500).option("--tables <list>", "subset of imported tables to include in the KN").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,...]'").option("--build", "submit a Vega build task per resource after creation").option(
-    "--embedding-fields <map>",
-    "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
-  ).option("--embedding-model <id>", "embedding model id for the vector index (with --build)").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
-    printJson(
-      await clientFrom(cmd).kn.createFromCsv({
-        catalogId,
-        name: opts.name,
-        files: opts.files,
-        tablePrefix: opts.tablePrefix,
-        batchSize: opts.batchSize,
-        tables: csv(opts.tables),
-        pkMap: opts.pkMap ? parsePkMap(opts.pkMap) : void 0,
-        build: Boolean(opts.build),
-        embeddingFields: opts.embeddingFields ? parseEmbeddingFields(opts.embeddingFields) : void 0,
-        embeddingModel: opts.embeddingModel,
-        noRollback: opts.rollback === false,
-        onProgress: (m) => console.error(m)
-      }),
-      outputOptions(cmd)
-    );
-  });
-  return group(bkn, "AI DATA PLATFORM");
+  groupChildren(bkn, {
+    GROUPS: [
+      "object-type",
+      "relation-type",
+      "action-type",
+      "metric",
+      "concept-group",
+      "action-log",
+      "action-schedule"
+    ],
+    READ: [
+      "pull",
+      "list",
+      "get",
+      "stats",
+      "export",
+      "search",
+      "subgraph",
+      "relation-type-paths",
+      "resources",
+      "action-execution",
+      "validate"
+    ],
+    WRITE: ["create", "update", "delete", "push", "create-from-catalog"]
+  });
+  groupChildren(metric, {
+    READ: ["list", "get"],
+    RUN: ["query", "dry-run", "validate"],
+    WRITE: ["create", "update", "delete"]
+  });
+  guide(
+    bkn,
+    `WHERE IDS COME FROM
+  \`list\` gives kn ids; \`object-type list <kn-id>\` and \`search <kn-id> "<q>"\` give the rest.
+
+SEARCH VS THE MCP SIDE
+  \`search\` recalls instance rows from one sentence and ships the object-type definitions
+  needed to read them \u2014 start here when you do not know the schema yet. It only reaches
+  properties indexed for match/knn, so an unindexed object type yields nothing, and no hits
+  comes back as empty nodes with a message rather than an error. For schema alone use
+  \`openbkn context search-schema\`; for a structured filter use \`object-type query\`.
+
+EDITING SCHEMA AS FILES
+  pull <kn-id> ./dir  ->  edit  ->  validate ./dir  ->  push ./dir
+  \`validate\` is offline and catches structure errors before the upload.
+
+REQUEST BODIES
+  create/update take a definition; query/execute/dry-run take a query. Both are documented
+  at https://openbkn-ai.github.io/bkn-foundry/ \u2014 definitions under bkn-backend, reads and
+  executions under ontology-query. Each command's --body flag names its own module.
+
+CREATING FROM DATA
+  create-from-catalog <catalog-id> --name "<n>" builds a network from a Vega catalog,
+  then \`openbkn vega dataset build <resource-id>\` produces the index. There is no
+  whole-network build.`
+  );
+  return group(bkn, "DATA & KNOWLEDGE");
 }
 
 // src/commands/call.ts
-import { Command as Command6 } from "commander";
+import { Command as Command5 } from "commander";
 function collect(value, prev) {
   prev.push(value);
   return prev;
 }
 function callCommand() {
-  const cmd = new Command6("call").alias("curl").description("Call an API with curl-style flags and auto-injected auth headers").argument("<url>", "API path (e.g. /api/...) or absolute URL").option("-X, --request <method>", "HTTP method").option("-H, --header <header>", 'extra header "Name: value" (repeatable)', collect, []).option("-d, --data <body>", "request body (sets JSON content-type if unset)").option("--data-raw <body>", "alias for --data").option(
+  const cmd = new Command5("call").alias("curl").description("Call any platform API endpoint directly (auth added)").argument("<url>", "API path (e.g. /api/...) or absolute URL").option("-X, --request <method>", "HTTP method").option("-H, --header <header>", 'extra header "Name: value" (repeatable)', collect, []).option("-d, --data <body>", "request body (sets JSON content-type if unset)").option("--data-raw <body>", "alias for --data").option(
     "-F, --form <field>",
     "multipart field key=value or key=@file (repeatable)",
     collect,
@@ -1609,7 +1765,7 @@ function callCommand() {
     });
     const out = outputOptions(cmd2);
     try {
-      printJson(JSON.parse(res.body), out);
+      printJson(parseBigIntJSON(res.body), out);
     } catch {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
@@ -1620,18 +1776,30 @@ function callCommand() {
       process.exitCode = 1;
     }
   });
-  return group(cmd, "AUTHENTICATION & CONFIG");
+  guide(
+    cmd,
+    `WHEN TO USE THIS
+  Anything the named commands do not cover: services with no command group yet
+  (bkn-agent, execution-factory operators and sandbox functions, MCP registration,
+  skill index builds), and endpoints newer than this CLI.
+
+FINDING THE PATH
+  Every service's API is documented at https://openbkn-ai.github.io/bkn-foundry/ \u2014
+  read the path and request body there rather than guessing. Auth, business domain
+  and TLS flags are injected the same way as for any other command.`
+  );
+  return group(cmd, "RAW API");
 }
 
 // src/commands/config.ts
-import { Command as Command7 } from "commander";
+import { Command as Command6 } from "commander";
 function requireActive() {
   const baseUrl = activePlatform();
   if (!baseUrl) throw new InputError("No active platform. Run `openbkn auth login <url>` first.");
   return baseUrl;
 }
 function configCommand() {
-  const config = new Command7("config").description("Per-platform CLI configuration");
+  const config = new Command6("config").description("Remember a platform URL / business domain");
   config.command("show").description("Show the active platform and business domain").action((_opts, cmd) => {
     const baseUrl = activePlatform();
     printJson(
@@ -1644,9 +1812,9 @@ function configCommand() {
   });
   config.command("set <key> <value>").description("Set a config value (baseUrl | businessDomain)").action((key, value, _opts, cmd) => {
     if (key === "baseUrl") {
-      setActivePlatform(value.replace(/\/+$/, ""));
+      setActivePlatform(trimTrailingSlashes(value));
     } else if (key === "businessDomain") {
-      writePlatformConfig(requireActive(), { businessDomain: value });
+      updatePlatformConfig(requireActive(), { businessDomain: value });
     } else {
       throw new InputError(`Unknown config key: ${key} (expected baseUrl | businessDomain)`);
     }
@@ -1654,18 +1822,19 @@ function configCommand() {
   });
   config.command("set-bd <value>").description("Set the default business domain for the active platform").action((value, _opts, cmd) => {
     const baseUrl = requireActive();
-    writePlatformConfig(baseUrl, { businessDomain: value });
+    updatePlatformConfig(baseUrl, { businessDomain: value });
     printJson({ baseUrl, businessDomain: value }, outputOptions(cmd));
   });
   config.command("list-bd").description("List business domains (requires login)").action(() => {
     throw new InputError("Not yet implemented \u2014 requires backend business-domains API.");
   });
-  return group(config, "AUTHENTICATION & CONFIG");
+  groupChildren(config, { READ: ["show", "list-bd"], WRITE: ["set", "set-bd"] });
+  return group(config, "SIGN IN & SETTINGS");
 }
 
 // src/commands/context.ts
-import { Command as Command8 } from "commander";
-var int5 = (v) => Number.parseInt(v, 10);
+import { Command as Command7 } from "commander";
+var int4 = (v) => Number.parseInt(v, 10);
 var collectArg = (v, prev) => {
   prev.push(v);
   return prev;
@@ -1674,7 +1843,7 @@ function buildArgs(opts) {
   let out = {};
   if (opts.args) {
     try {
-      out = JSON.parse(opts.args);
+      out = parseBigIntJSON(opts.args);
     } catch {
       throw new InputError("--args must be valid JSON");
     }
@@ -1685,7 +1854,7 @@ function buildArgs(opts) {
     const key = pair.slice(0, idx);
     const raw = pair.slice(idx + 1);
     try {
-      out[key] = JSON.parse(raw);
+      out[key] = parseBigIntJSON(raw);
     } catch {
       out[key] = raw;
     }
@@ -1703,33 +1872,44 @@ function printToolList(res, out) {
     printJson(res, out);
     return;
   }
-  const rows = arr.map((t) => ({
+  const rows2 = arr.map((t) => ({
     name: t.name ?? t.tool_name ?? t.key ?? "",
     description: typeof t.description === "string" ? t.description : ""
   }));
-  printJson(rows, out);
+  printJson(rows2, out);
 }
 function contextCommand() {
-  const cmd = new Command8("context").description(
-    "Context loader (MCP) \u2014 schema discovery, instance query, skill recall"
+  const cmd = new Command7("context").description(
+    "Ask a network questions (the MCP interface agents use)"
   );
-  cmd.command("search-schema <kn-id> <query>").description("Search object/relation/action/metric schemas").option("--scope <list>", "comma-separated scopes (object,relation,action,metric)").option("--max <n>", "max concepts", int5).action(async (knId, query, opts, cmd2) => {
+  const jsonArgs = (raw) => {
+    if (!raw) throw new InputError("--args is required (run with --schema to see its shape)");
+    try {
+      return parseBigIntJSON(raw);
+    } catch {
+      throw new InputError("--args must be valid JSON");
+    }
+  };
+  cmd.command("search-schema <kn-id> <query>").description(
+    "Search object/relation/action/metric schemas \u2192 {object_types, relation_types, action_types, metric_types}"
+  ).option("--scope <list>", "comma-separated scopes (object,relation,action,metric)").option("--max <n>", "max concepts", int4).action(async (knId, query, opts, cmd2) => {
     const data = await clientFrom(cmd2).context.searchSchema(knId, query, {
       searchScope: opts.scope ? String(opts.scope).split(",") : void 0,
       maxConcepts: opts.max
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("query-object-instance <kn-id>").description("Query object instances (provide --args as JSON)").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
-    let args;
-    try {
-      args = JSON.parse(opts.args);
-    } catch {
-      throw new InputError("--args must be valid JSON");
-    }
+  cmd.command("query-object-instance <kn-id>").description(
+    `Query one object type's instances \u2014 \`--args '{"ot_id":"<id>","limit":10}'\` \u2192 {datas, total_count}`
+  ).option(
+    "--args <json>",
+    "tool arguments as JSON; kn_id is filled from <kn-id>; --schema prints the shape"
+  ).option("--schema", "print this tool's argument schema from the deploy instead of calling it").action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "query_object_instance");
+    const args = jsonArgs(opts.args);
     printJson(await clientFrom(cmd2).context.queryObjectInstance(knId, args), outputOptions(cmd2));
   });
-  cmd.command("find-skills <kn-id> <object-type-id>").description("Recall skills for an object type").option("--top-k <n>", "max skills (1-20)", int5).action(async (knId, otId, opts, cmd2) => {
+  cmd.command("find-skills <kn-id> <object-type-id>").description("Recall skills for an object type").option("--top-k <n>", "max skills (1-20)", int4).action(async (knId, otId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).context.findSkills(knId, otId, opts.topK),
       outputOptions(cmd2)
@@ -1745,18 +1925,139 @@ function contextCommand() {
   cmd.command("relation-types <kn-id> <ids...>").description("Full definitions for the given relation-type ids (unmatched \u2192 `missing`)").action(async (knId, ids, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).context.relationTypes(knId, ids), outputOptions(cmd2));
   });
+  cmd.command("conversation").description("Show the remembered conversation, or forget it with --forget").option(
+    "--forget",
+    "drop it, so the next command opens a fresh conversation (acts on this machine's store for the active user, whatever identity the request would use)"
+  ).action((opts, cmd2) => {
+    const o = cmd2.optsWithGlobals();
+    const baseUrl = platformOf(o);
+    if (!baseUrl) throw new InputError("No platform. Run `openbkn auth login` first.");
+    const forgot = opts.forget ? readPlatformConfig(baseUrl).conversationId : void 0;
+    if (opts.forget) {
+      updatePlatformConfig(baseUrl, {
+        conversationId: void 0,
+        conversationOpenedAt: void 0
+      });
+    }
+    const { id, source } = conversationSource(o);
+    const stored = readPlatformConfig(baseUrl);
+    printJson(
+      {
+        baseUrl,
+        conversationId: id ?? null,
+        source,
+        ...stored.conversationOpenedAt ? { storedOpenedAt: stored.conversationOpenedAt } : {},
+        // What is on disk, even when something outranks it — otherwise
+        // `--forget` looks like a no-op to whoever just ran this.
+        ...stored.conversationId && stored.conversationId !== id ? { storedConversationId: stored.conversationId } : {},
+        ...opts.forget ? { forgot: forgot ?? null } : {}
+      },
+      outputOptions(cmd2)
+    );
+  });
   cmd.command("info").description("List the deploy's MCP tool catalog (global \u2014 no KN needed)").action(async (_opts, cmd2) => {
     printToolList(await clientFrom(cmd2).context.info(), outputOptions(cmd2));
   });
-  cmd.command("tools <kn-id>").description("List MCP tools advertised for a KN session").action(async (knId, _opts, cmd2) => {
+  const printToolSchema = async (cmd2, knId, tool) => {
+    const listed = await clientFrom(cmd2).context.tools(knId);
+    const found = listed.tools?.find((t) => t.name === tool);
+    if (!found) throw new InputError(`this deploy does not advertise the ${tool} tool`);
+    printJson(
+      { tool: found.name, description: found.description, inputSchema: found.inputSchema },
+      { ...outputOptions(cmd2), json: true }
+    );
+  };
+  cmd.command("run-sql <kn-id>").description(
+    "Aggregate, rank or join with read-only SQL \u2014 what query-object-instance cannot do"
+  ).option("--sql <sql>", "read-only MySQL over data resources, tables named as {{<resource-id>}}").option("--timeout <sec>", "query timeout in seconds", (v) => Number.parseInt(v, 10)).option("--schema", "print this tool's argument schema from the deploy instead of calling it").addHelpText(
+    "after",
+    `
+A table is named by resource id, never by the name it carries on the source:
+
+  openbkn context search-schema <kn-id> "<what you are after>" --json
+      \u2192 object_types[].data_source.id
+
+  openbkn context run-sql <kn-id> \\
+    --sql "SELECT supplier_id, COUNT(*) c FROM {{d9g387peef0be1ifnurg}} GROUP BY supplier_id"
+
+Joining two resources means two ids, one placeholder each. Column names are the
+physical ones. Answers {columns, entries, paging} plus a bkn_receipt recording
+the operation in BKN Trace. Row limits belong in the SQL \u2014 this tool takes no
+limit argument.
+
+The same SQL runs without a knowledge network through \`openbkn vega sql\`, which
+adds paging and --need-total but records nothing in Trace.`
+  ).action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "run_sql");
+    if (!opts.sql) throw new InputError("--sql is required (or use --schema to see the shape)");
+    const args = { sql: opts.sql };
+    if (opts.timeout !== void 0) args.query_timeout = opts.timeout;
+    printJson(await clientFrom(cmd2).context.toolCall(knId, "run_sql", args), outputOptions(cmd2));
+  });
+  cmd.command("explore-subgraph <kn-id> <object-type-id>").description("Follow relations outward from one object type without naming a path first").option("--hops <n>", "how many hops to walk, 1-3", (v) => Number.parseInt(v, 10)).option(
+    "--direction <d>",
+    "forward | backward | bidirectional \u2014 pick bidirectional when unsure how the relation reads",
+    "bidirectional"
+  ).option(
+    "--limit <n>",
+    "instances of the STARTING type, not paths or total objects",
+    (v) => Number.parseInt(v, 10)
+  ).option("--args <json>", "extra tool arguments merged in (condition, sort, offset \u2026)").option("--schema", "print this tool's argument schema from the deploy instead of calling it").addHelpText(
+    "after",
+    `
+Use this when the topology is the question \u2014 "what does this supplier touch?" \u2014
+and \`query-instance-subgraph\` when you already know which relations to walk.
+Paths multiply with each hop, so start at 1 or 2.`
+  ).action(async (knId, objectTypeId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "explore_subgraph");
+    if (opts.hops === void 0) {
+      throw new InputError("--hops is required (or use --schema to see the shape)");
+    }
+    const args = {
+      ...opts.args ? jsonArgs(opts.args) : {},
+      source_object_type_id: objectTypeId,
+      direction: opts.direction,
+      path_length: opts.hops
+    };
+    if (opts.limit !== void 0) args.limit = opts.limit;
+    printJson(
+      await clientFrom(cmd2).context.toolCall(knId, "explore_subgraph", args),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("query-metric <kn-id> <metric-id>").description("Read a modelled metric through its own definition \u2014 do not restate it in SQL").option(
+    "--args <json>",
+    "tool arguments: analysis_dimensions, time, condition, having, order_by"
+  ).option("--schema", "print this tool's argument schema from the deploy instead of calling it").addHelpText(
+    "after",
+    `
+Metric ids come from an object type: \`context object-types <kn-id> <ot-id>\`
+lists them under related_metrics. The definition owns the arithmetic, so
+rewriting it with \`run-sql\` produces a number the platform will not agree with.`
+  ).action(async (knId, metricId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "query_metric");
+    const args = { ...opts.args ? jsonArgs(opts.args) : {}, metric_id: metricId };
+    printJson(
+      await clientFrom(cmd2).context.toolCall(knId, "query_metric", args),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("tools <kn-id>").description("List MCP tools advertised for a KN session \u2192 {tools} with each inputSchema").action(async (knId, _opts, cmd2) => {
     printToolList(await clientFrom(cmd2).context.tools(knId), outputOptions(cmd2));
   });
-  cmd.command("tool-call <kn-id> <name>").description("Call any MCP tool by name \u2014 current or future (use `tools` to discover)").option("--args <json>", "tool arguments as JSON").option(
+  cmd.command("tool-call <kn-id> <name>").description("Call any MCP tool by name \u2014 current or future (use `tools` to discover)").option(
+    "--args <json>",
+    "tool arguments as JSON; kn_id is filled from <kn-id> \u2014 input schema comes from `context tools <kn-id>`"
+  ).option(
     "--arg <key=value>",
     "one argument (repeatable; value parsed as JSON, else string)",
     collectArg,
     []
+  ).option(
+    "--schema",
+    "print the named tool's argument schema from the deploy instead of calling it"
   ).action(async (knId, name, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, name);
     printJson(
       await clientFrom(cmd2).context.toolCall(knId, name, buildArgs(opts)),
       outputOptions(cmd2)
@@ -1764,7 +2065,7 @@ function contextCommand() {
   });
   cmd.command("call-method <kn-id> <method>").description(
     "Call any MCP method by name (e.g. tools/list, resources/read) \u2014 current or future"
-  ).option("--args <json>", "method params as JSON").option(
+  ).option("--args <json>", "method params as JSON \u2014 see `context call-method <kn-id> tools/list`").option(
     "--arg <key=value>",
     "one param (repeatable; value parsed as JSON, else string)",
     collectArg,
@@ -1787,239 +2088,1027 @@ function contextCommand() {
   cmd.command("prompts <kn-id>").description("List MCP prompts").action(async (knId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).context.prompts(knId), outputOptions(cmd2));
   });
-  cmd.command("prompt <kn-id> <name>").description("Get one MCP prompt (--args JSON for prompt arguments)").option("--args <json>", "prompt arguments as JSON").action(async (knId, name, opts, cmd2) => {
+  cmd.command("prompt <kn-id> <name>").description("Get one MCP prompt (--args JSON for prompt arguments)").option(
+    "--args <json>",
+    "prompt arguments as JSON \u2014 argument names come from `context prompts <kn-id>`"
+  ).action(async (knId, name, opts, cmd2) => {
     let args;
     if (opts.args) {
       try {
-        args = JSON.parse(opts.args);
+        args = parseBigIntJSON(opts.args);
       } catch {
         throw new InputError("--args must be valid JSON");
       }
     }
     printJson(await clientFrom(cmd2).context.prompt(knId, name, args), outputOptions(cmd2));
   });
-  const jsonArgs = (raw) => {
-    try {
-      return JSON.parse(raw);
-    } catch {
-      throw new InputError("--args must be valid JSON");
-    }
-  };
-  cmd.command("query-instance-subgraph <kn-id>").description("Query an instance subgraph across relation-type paths").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("query-instance-subgraph <kn-id>").description("Query an instance subgraph across relation-type paths").option(
+    "--args <json>",
+    "tool arguments as JSON; kn_id is filled from <kn-id>; --schema prints the shape"
+  ).option("--schema", "print this tool's argument schema from the deploy instead of calling it").action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "query_instance_subgraph");
     printJson(
       await clientFrom(cmd2).context.queryInstanceSubgraph(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
     );
   });
-  cmd.command("get-logic-properties <kn-id>").description("Compute logic-property values for instances").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("get-logic-properties <kn-id>").description("Compute logic-property values for instances").option(
+    "--args <json>",
+    "tool arguments as JSON; kn_id is filled from <kn-id>; --schema prints the shape"
+  ).option("--schema", "print this tool's argument schema from the deploy instead of calling it").action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "get_logic_properties_values");
     printJson(
       await clientFrom(cmd2).context.logicProperties(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
     );
   });
-  cmd.command("get-action-info <kn-id>").description("Fetch action info / dynamic tools for an instance").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("get-action-info <kn-id>").description("Fetch action info / dynamic tools for an instance").option(
+    "--args <json>",
+    "tool arguments as JSON; kn_id is filled from <kn-id>; --schema prints the shape"
+  ).option("--schema", "print this tool's argument schema from the deploy instead of calling it").action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "get_action_info");
     printJson(
       await clientFrom(cmd2).context.actionInfo(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
     );
   });
-  return group(cmd, "AI DATA PLATFORM");
-}
+  groupChildren(cmd, {
+    GROUPS: ["conversation"],
+    READ: [
+      "search-schema",
+      "kn-detail",
+      "object-types",
+      "relation-types",
+      "info",
+      "tools",
+      "resources",
+      "resource",
+      "templates",
+      "prompts",
+      "prompt",
+      "find-skills"
+    ],
+    RUN: [
+      "query-object-instance",
+      "run-sql",
+      "explore-subgraph",
+      "query-metric",
+      "query-instance-subgraph",
+      "get-logic-properties",
+      "get-action-info",
+      "tool-call",
+      "call-method"
+    ]
+  });
+  guide(
+    cmd,
+    `ORDER OF WORK
+  1. search-schema <kn-id> "<question>"     find the object/relation/action ids that matter
+  2. kn-detail / object-types               drill into the ones you picked
+  3. query-object-instance                  filter + sort + page one object type
+     query-instance-subgraph                follow a known relation path
+     get-logic-properties / get-action-info  computed values, runnable actions
 
-// src/commands/dataflow.ts
-import { Command as Command9 } from "commander";
-var int6 = (v) => Number.parseInt(v, 10);
-function dataflowCommand() {
-  const cmd = new Command9("dataflow").description("Dataflow document workflows \u2014 list, runs, logs");
-  cmd.command("list").description("List all dataflows").action(async (_opts, cmd2) => {
-    printJson(await clientFrom(cmd2).dataflows.list(), outputOptions(cmd2));
-  });
-  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").option("--limit <n>", "page size (backend default 20)", int6).option("--page <n>", "page (0-based; backend default 0)", int6).action(async (dagId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.runs(dagId, {
-        since: opts.since,
-        page: opts.page,
-        limit: opts.limit
-      }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("logs <dagId> <instanceId>").description("Show logs for one run").option("--page <n>", "page", int6, 0).option("--limit <n>", "page size", int6, DEFAULT_LIST_LIMIT).action(async (dagId, instanceId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.logs(dagId, instanceId, {
-        page: opts.page,
-        limit: opts.limit
-      }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("run <dagId>").description("Trigger a dataflow run from a remote file URL").requiredOption("--url <url>", "remote file URL").requiredOption("--name <name>", "file name").action(async (dagId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.run(dagId, opts.url, opts.name),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("create").description("Create a dataflow (DAG) from a full document body (--body / --body-file)").option("--body <json>", "dataflow document JSON").option("--body-file <path>", "read the dataflow document JSON from a file").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).dataflows.create(readBody(opts)), outputOptions(cmd2));
-  });
-  const parseSet = (pairs) => {
-    const out = {};
-    for (const item of pairs ?? []) {
-      const i = item.indexOf("=");
-      if (i > 0) out[item.slice(0, i)] = item.slice(i + 1);
-    }
-    return out;
-  };
-  cmd.command("templates").description("List available dataset/bkn/dataflow templates").action(async (_opts, cmd2) => {
-    printJson(clientFrom(cmd2).dataflows.templates(), outputOptions(cmd2));
-  });
-  cmd.command("create-dataset").description("Create a dataset from a template (--template <name> --set k=v ...)").requiredOption("--template <name>", "template name").option(
-    "--set <kv...>",
-    "set a template argument (key=value); repeatable",
-    (v, acc) => {
-      acc.push(v);
-      return acc;
-    },
-    []
-  ).action(async (opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.createDataset(opts.template, parseSet(opts.set)),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("create-bkn").description("Create a knowledge network from a template (--template <name> --set k=v ...)").requiredOption("--template <name>", "template name").option(
-    "--set <kv...>",
-    "set a template argument (key=value); repeatable",
-    (v, acc) => {
-      acc.push(v);
-      return acc;
-    },
-    []
-  ).action(async (opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.createBkn(opts.template, parseSet(opts.set)),
-      outputOptions(cmd2)
-    );
-  });
-  return group(cmd, "AI DATA PLATFORM");
-}
+PICKING THE RIGHT QUERY
+  Aggregation, ranking, GROUP BY or joins are not query-object-instance \u2014 send SQL through
+  \`tool-call <kn-id> run_sql\`. Unknown topology is \`tool-call <kn-id> explore_subgraph\`,
+  not a hand-built path.
 
-// src/commands/explore.ts
-import { createServer } from "http";
-import { Command as Command10 } from "commander";
-var int7 = (v) => Number.parseInt(v, 10);
-var ROUTES = {
-  "GET /api/bkn/meta": (c, q) => c.kn.get(req(q, "knId")),
-  "POST /api/bkn/search": (c, _q, b) => c.kn.search(str(b.knId), str(b.query), {
-    maxConcepts: typeof b.maxConcepts === "number" ? b.maxConcepts : void 0
-  }),
-  "POST /api/bkn/instances": (c, _q, b) => c.kn.objectTypeQuery(str(b.knId), str(b.objectTypeId), b.body ?? {}),
-  "POST /api/bkn/subgraph": (c, _q, b) => c.kn.subgraph(str(b.knId), b.body ?? b),
-  "GET /api/vega/catalogs": (c) => c.vega.catalogs(),
-  "GET /api/vega/catalog": (c, q) => c.vega.getCatalog(req(q, "catalogId")),
-  "GET /api/vega/catalog-resources": (c, q) => c.vega.catalogResources(req(q, "catalogId"), q.get("category") ?? void 0),
-  "GET /api/vega/connector-types": (c) => c.vega.connectorTypes(),
-  "POST /api/vega/query": (c, _q, b) => c.resource.query(str(b.resourceId), b.options ?? {})
-};
-function str(v) {
-  return typeof v === "string" ? v : String(v ?? "");
-}
-function req(q, key) {
-  const v = q.get(key);
-  if (!v) throw new Error(`missing query param: ${key}`);
-  return v;
-}
-function readBody2(reqMsg) {
-  return new Promise((resolve2, reject) => {
-    let data = "";
-    reqMsg.on("data", (chunk) => {
-      data += chunk;
-    });
-    reqMsg.on("end", () => {
-      if (!data.trim()) return resolve2({});
-      try {
-        resolve2(JSON.parse(data));
-      } catch {
-        reject(new Error("invalid JSON body"));
-      }
-    });
-    reqMsg.on("error", reject);
-  });
-}
-var INDEX = `<!doctype html><meta charset="utf-8"><title>openbkn explore</title>
-<h1>openbkn explore</h1>
-<p>Read-only JSON endpoints for bkn + vega:</p>
-<ul>${Object.keys(ROUTES).map((r) => `<li><code>${r}</code></li>`).join("")}</ul>`;
-function exploreCommand() {
-  const cmd = new Command10("explore").description(
-    "Start a local web server with read-only bkn + vega JSON endpoints"
+THE SAME ID, FOUR NAMES
+  An object type's id is \`concept_id\` in search-schema output, \`id\` in kn-detail and
+  get_object_types, \`ot_id\` in query-object-instance arguments, and \`object_type_id\` on
+  an instance row. Same value throughout \u2014 carry it across, do not look it up again.
+
+RAW MCP
+  tools <kn-id> lists what this deploy advertises, with each tool's input schema.
+  tool-call / call-method reach anything the named commands above do not cover.`
   );
-  cmd.option("--port <n>", "port to listen on", int7, 7777).option("--host <h>", "host to bind", "127.0.0.1").action(async (opts, command) => {
-    const client = clientFrom(command);
-    const server = createServer((reqMsg, res) => {
-      void handle(client, reqMsg, res);
-    });
-    server.listen(opts.port, opts.host, () => {
-      console.error(`openbkn explore running at http://${opts.host}:${opts.port}/`);
-      console.error("bkn + vega read endpoints only. Press Ctrl+C to stop.");
-    });
-  });
-  return group(cmd, "FOUNDATION");
+  return group(cmd, "DATA & KNOWLEDGE");
 }
-async function handle(client, reqMsg, res) {
-  const url = new URL(reqMsg.url ?? "/", "http://localhost");
-  const method = reqMsg.method ?? "GET";
-  if (method === "GET" && url.pathname === "/") {
-    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-    res.end(INDEX);
-    return;
+
+// src/commands/describe.ts
+import { Command as Command8 } from "commander";
+
+// src/help/returns.json
+var returns_default = {
+  note: "Top-level keys observed on a live deploy, not a contract. Regenerate with scripts/capture-returns.mjs.",
+  observedAt: "2026-08-29",
+  commands: {
+    "auth status": ["baseUrl", "expired", "hasToken", "userId", "username"],
+    "auth whoami": [
+      "at_hash",
+      "aud",
+      "auth_time",
+      "baseUrl",
+      "exp",
+      "iat",
+      "iss",
+      "jti",
+      "rat",
+      "sid",
+      "sub",
+      "userId",
+      "username"
+    ],
+    "auth list": "array",
+    "config show": ["baseUrl"],
+    "appkey list": ["keys"],
+    "appkey admin list": ["keys"],
+    "bkn list": ["entries", "total_count"],
+    "bkn get": [
+      "branch",
+      "business_domain",
+      "color",
+      "comment",
+      "create_time",
+      "creator",
+      "icon",
+      "id",
+      "module_type",
+      "name",
+      "operations",
+      "tags",
+      "update_time",
+      "updater"
+    ],
+    "bkn object-type list": ["entries", "total_count"],
+    "bkn object-type get": ["entries"],
+    "bkn relation-type list": ["entries", "total_count"],
+    "bkn relation-type get": ["entries"],
+    "bkn action-type list": ["entries", "total_count"],
+    "bkn action-type get": ["entries"],
+    "bkn stats": [
+      "branch",
+      "business_domain",
+      "color",
+      "comment",
+      "create_time",
+      "creator",
+      "icon",
+      "id",
+      "module_type",
+      "name",
+      "operations",
+      "statistics",
+      "tags",
+      "update_time",
+      "updater"
+    ],
+    "bkn action-log list": ["entries"],
+    "bkn metric list": ["entries", "total_count"],
+    "bkn concept-group list": ["entries", "total_count"],
+    "bkn concept-group get": [
+      "branch",
+      "color",
+      "comment",
+      "create_time",
+      "creator",
+      "icon",
+      "id",
+      "kn_id",
+      "module_type",
+      "name",
+      "object_types",
+      "relation_types",
+      "tags",
+      "update_time",
+      "updater"
+    ],
+    "bkn action-schedule list": ["entries", "total_count"],
+    "vega catalog list": ["entries", "total_count"],
+    "vega catalog resources": ["entries", "total_count"],
+    "vega catalog health": ["health_check_result", "health_check_status", "id", "last_check_time"],
+    "vega discover-schedule list": ["entries", "total_count"],
+    "vega discover-schedule get": [
+      "catalog_id",
+      "create_time",
+      "creator",
+      "cron_expr",
+      "enabled",
+      "end_time",
+      "id",
+      "last_run",
+      "name",
+      "next_run",
+      "start_time",
+      "strategy",
+      "update_time",
+      "updater"
+    ],
+    "vega discover-task list": ["entries", "total_count"],
+    "vega discover-task get": [
+      "catalog_id",
+      "catalog_name",
+      "create_time",
+      "creator",
+      "finish_time",
+      "id",
+      "last_progress_time",
+      "message",
+      "progress",
+      "queue_priority",
+      "result",
+      "schedule_id",
+      "start_time",
+      "status",
+      "strategy",
+      "trigger_type"
+    ],
+    "vega semantic-task list": ["entries", "total_count"],
+    "vega semantic-task get": [
+      "agent_id",
+      "agent_task_id",
+      "applied",
+      "apply_detail_json",
+      "apply_mode",
+      "catalog_id",
+      "catalog_name",
+      "confidence",
+      "confidence_detail_json",
+      "confidence_threshold",
+      "create_time",
+      "creator",
+      "id",
+      "input",
+      "input_hash",
+      "resource_id",
+      "resource_name",
+      "result_json",
+      "scope",
+      "status"
+    ],
+    "vega connector-type list": ["entries", "total_count"],
+    "vega resource list": ["entries", "total_count"],
+    "vega resource get": ["entries"],
+    "resource list": ["entries", "total_count"],
+    "resource get": ["entries"],
+    "context kn-detail": [
+      "action_types",
+      "comment",
+      "concept_groups",
+      "id",
+      "name",
+      "object_types",
+      "relation_types"
+    ],
+    "context info": [
+      "auth",
+      "client_config_example",
+      "endpoint",
+      "language",
+      "protocol",
+      "service",
+      "supported_languages",
+      "tool_count",
+      "tools",
+      "transport"
+    ],
+    "context tools": ["tools"],
+    "model llm list": ["count", "data"],
+    "model llm get": [
+      "max_model_len",
+      "model_config",
+      "model_id",
+      "model_name",
+      "model_series",
+      "model_type"
+    ],
+    "model small list": ["count", "data"],
+    "model small get": [
+      "adapter",
+      "adapter_code",
+      "batch_size",
+      "create_time",
+      "default",
+      "embedding_dim",
+      "max_tokens",
+      "model_config",
+      "model_id",
+      "model_name",
+      "model_type",
+      "update_time"
+    ],
+    "model small get-default": [
+      "batch_size",
+      "default",
+      "embedding_dim",
+      "max_tokens",
+      "model_config",
+      "model_id",
+      "model_name",
+      "model_type"
+    ],
+    "skill list": ["data", "has_next", "has_prev", "page", "page_size", "total", "total_pages"],
+    "skill get": [
+      "business_domain_id",
+      "category",
+      "category_name",
+      "create_time",
+      "create_user",
+      "description",
+      "name",
+      "skill_id",
+      "source",
+      "status",
+      "update_time",
+      "update_user",
+      "version"
+    ],
+    "skill market": ["data", "has_next", "has_prev", "page", "page_size", "total", "total_pages"],
+    "skill market-get": [
+      "business_domain_id",
+      "category",
+      "category_name",
+      "create_time",
+      "create_user",
+      "description",
+      "name",
+      "release_time",
+      "release_user",
+      "skill_id",
+      "source",
+      "status",
+      "update_time",
+      "update_user",
+      "version"
+    ],
+    "skill content": ["files", "skill_id", "status", "url"],
+    "skill files": ["entries", "path", "skillId", "totalFiles", "totalSize"],
+    "skill names": ["entries"],
+    "skill history": "array",
+    "toolbox list": ["data", "has_next", "has_prev", "page", "page_size", "total", "total_pages"],
+    "function deps": ["dependencies", "session_id"],
+    "function template": ["code_template", "template_type"],
+    "trace graph": [
+      "data",
+      "duration_nano",
+      "page",
+      "partial",
+      "partial_reason",
+      "status",
+      "trace_id"
+    ],
+    "trace conversations list": ["entries"],
+    "trace conversations get": [
+      "agent_name",
+      "conversation_id",
+      "created_at",
+      "creation_auth_method",
+      "external_conversation_key",
+      "generation",
+      "one_shot",
+      "owner",
+      "row_version",
+      "status",
+      "updated_at"
+    ],
+    "trace interactions get": [
+      "closure_manifest",
+      "conversation_id",
+      "created_at",
+      "evidence_status",
+      "execution_status",
+      "interaction_id",
+      "lease_epoch",
+      "lease_expires_at",
+      "lease_token",
+      "lease_version",
+      "ordinal",
+      "row_version",
+      "terminal_at",
+      "updated_at"
+    ],
+    "trace operations get": [
+      "attempt",
+      "attempt_status",
+      "conversation_id",
+      "created_at",
+      "interaction_id",
+      "operation_id",
+      "operation_key",
+      "retryable",
+      "row_version",
+      "tool_name",
+      "updated_at"
+    ],
+    "trace receipts get": [
+      "artifact_refs",
+      "attempt",
+      "business_refs",
+      "causation_event_ids",
+      "conversation_id",
+      "evidence_durability",
+      "interaction_id",
+      "issued_at",
+      "observed_evidence_refs",
+      "operation_id",
+      "operation_key",
+      "owner",
+      "partial_reasons",
+      "receipt_id",
+      "receipt_status",
+      "request_id",
+      "required",
+      "row_version",
+      "schema_version",
+      "terminal_at",
+      "tool_name",
+      "trace_id"
+    ],
+    "trace get": "array",
+    "trace detail": ["graph", "operations", "partial", "summary"],
+    "trace spans": "array",
+    "trace search": [
+      "entries",
+      "next_cursor",
+      "page",
+      "page_size",
+      "partial",
+      "total",
+      "truncated"
+    ],
+    "admin auth status": ["baseUrl", "expired", "hasToken", "userId", "username"],
+    "admin auth whoami": [
+      "at_hash",
+      "aud",
+      "auth_time",
+      "baseUrl",
+      "exp",
+      "iat",
+      "iss",
+      "jti",
+      "rat",
+      "sid",
+      "sub",
+      "userId",
+      "username"
+    ],
+    "admin auth list": "array",
+    "admin auth export": ["accessToken", "baseUrl", "idToken", "refreshToken"],
+    "admin org list": ["departments", "total"],
+    "admin org get": [
+      "code",
+      "created_at",
+      "id",
+      "manager_id",
+      "manager_name",
+      "name",
+      "parent_id",
+      "type"
+    ],
+    "admin org members": ["total", "users"],
+    "admin org tree": "array",
+    "admin user list": ["total", "users"],
+    "admin user get": [
+      "account",
+      "account_type",
+      "departments",
+      "email",
+      "enabled",
+      "id",
+      "name",
+      "roles",
+      "telephone",
+      "updated_at"
+    ],
+    "admin user roles": ["roles"],
+    "admin role list": ["roles"],
+    "admin role get": [
+      "built_in",
+      "created_at",
+      "description",
+      "id",
+      "members",
+      "name",
+      "permissions",
+      "source"
+    ],
+    "admin role members": ["members"],
+    "admin llm list": ["count", "data"],
+    "admin llm get": [
+      "max_model_len",
+      "model_config",
+      "model_id",
+      "model_name",
+      "model_series",
+      "model_type"
+    ],
+    "admin small-model list": ["count", "data"],
+    "admin small-model get": [
+      "adapter",
+      "adapter_code",
+      "batch_size",
+      "create_time",
+      "default",
+      "embedding_dim",
+      "max_tokens",
+      "model_config",
+      "model_id",
+      "model_name",
+      "model_type",
+      "update_time"
+    ],
+    "admin license show": [
+      "activated",
+      "contract_expires_at",
+      "customer",
+      "edition",
+      "expires_at",
+      "features",
+      "instance_fp",
+      "issued_at",
+      "lic_id",
+      "limits",
+      "state"
+    ],
+    "admin config show": ["baseUrl"]
   }
-  const handler = ROUTES[`${method} ${url.pathname}`];
-  if (!handler) {
-    res.writeHead(404, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "not found" }));
-    return;
+};
+
+// src/commands/probe.ts
+var SERVICE_PROBES = [
+  { service: "bkn-backend", path: "/api/bkn-backend/v1/knowledge-networks?limit=1" },
+  { service: "vega-backend", path: "/api/vega-backend/v1/catalogs?limit=1" },
+  {
+    service: "agent-operator-integration",
+    path: "/api/agent-operator-integration/v1/tool-box/list?page=1&size=1"
+  },
+  { service: "agent-observability", path: "/api/agent-observability/v1/conversations?limit=1" },
+  { service: "mf-model-manager", path: "/api/mf-model-manager/v1/llm/list" },
+  { service: "safe", path: "/api/safe/v1/me/api-keys" },
+  { service: "agent-retrieval", path: "/api/agent-retrieval/v1/mcp/info" }
+];
+var COMMAND_SERVICE = [
+  [/^bkn\b/, "bkn-backend"],
+  [/^vega\b/, "vega-backend"],
+  [/^resource\b/, "vega-backend"],
+  [/^context\b/, "agent-retrieval"],
+  [/^trace\b/, "agent-observability"],
+  [/^(skill|toolbox|tool|function)\b/, "agent-operator-integration"],
+  [/^model\b/, "mf-model-manager"],
+  [/^(auth|appkey)\b/, "safe"],
+  [/^admin (llm|small-model)\b/, "mf-model-manager"],
+  [/^admin\b/, "safe"]
+];
+var COMMAND_TOOL = {
+  "context search-schema": "search_schema",
+  "context query-object-instance": "query_object_instance",
+  "context query-instance-subgraph": "query_instance_subgraph",
+  "context explore-subgraph": "explore_subgraph",
+  "context run-sql": "run_sql",
+  "context query-metric": "query_metric",
+  "context get-logic-properties": "get_logic_properties_values",
+  "context get-action-info": "get_action_info",
+  "context find-skills": "find_skills",
+  "context kn-detail": "get_kn_detail",
+  "context object-types": "get_object_types",
+  "context relation-types": "get_relation_types"
+};
+async function probeDeploy(cmd, now) {
+  const client = clientFrom(cmd);
+  const services = {};
+  for (const { service, path } of SERVICE_PROBES) {
+    try {
+      const res = await client.call(path);
+      services[service] = res.status === 404 || res.status === 501 || res.status >= 502 ? { available: false, reason: `HTTP ${res.status} ${res.statusText}`.trim() } : { available: true };
+    } catch (err) {
+      services[service] = {
+        available: false,
+        reason: err instanceof Error ? firstLine(err.message) : "unreachable"
+      };
+    }
   }
-  try {
-    const body = method === "GET" ? {} : await readBody2(reqMsg);
-    const data = await handler(client, url.searchParams, body);
-    res.writeHead(200, { "content-type": "application/json" });
-    res.end(JSON.stringify(data ?? null));
-  } catch (err) {
-    res.writeHead(500, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+  let mcpTools = [];
+  if (services["agent-retrieval"]?.available) {
+    try {
+      const info = await client.context.info();
+      mcpTools = (info.tools ?? []).map((t) => typeof t === "string" ? t : t.name ?? "").filter(Boolean);
+    } catch {
+    }
   }
+  return { baseUrl: client.ctx.baseUrl, checkedAt: now, services, mcpTools };
 }
-
-// src/commands/model.ts
-import { Command as Command11 } from "commander";
-var int8 = (v) => Number.parseInt(v, 10);
-async function resolveLlmModelName(client, model) {
-  if (!/^\d+$/.test(model)) return model;
-  const detail = await client.models.llm.get(model);
-  if (!detail?.model_name) throw new InputError(`No LLM found with id ${model}.`);
-  return detail.model_name;
+function firstLine(message) {
+  return (message.split("\n")[0] ?? message).slice(0, 160);
 }
-function addManagementCommands(parent, kind) {
-  parent.command("add").description("Register a model (definition JSON via --body / --body-file)").option("--body <json>", "model definition JSON").option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
+function availabilityOf(path, probe) {
+  if (!probe) return { available: "unknown" };
+  const tool = COMMAND_TOOL[path];
+  if (tool && probe.mcpTools.length) {
+    return probe.mcpTools.includes(tool) ? { available: true } : { available: false, reason: `this deploy's MCP server does not advertise ${tool}` };
+  }
+  const service = COMMAND_SERVICE.find(([re]) => re.test(path))?.[1];
+  if (!service) return { available: "unknown", reason: "no single service to check" };
+  const state = probe.services[service];
+  if (!state) return { available: "unknown" };
+  return state.available ? { available: true } : { available: false, reason: `${service}: ${state.reason ?? "unreachable"}` };
+}
+
+// src/commands/describe.ts
+var DEFAULT_SECTION = "COMMANDS";
+var ID_SOURCES = {
+  "kn-id": "openbkn bkn list",
+  "catalog-id": "openbkn vega catalog list",
+  "resource-id": "openbkn vega catalog resources <catalog-id>",
+  "ot-id": 'openbkn context search-schema <kn-id> "<q>"',
+  "at-id": "openbkn bkn action-type list <kn-id>",
+  "metric-id": "openbkn bkn metric list <kn-id>",
+  "skill-id": "openbkn skill list",
+  "box-id": "openbkn toolbox list",
+  "tool-id": "openbkn tool list --toolbox <box-id>",
+  "conversation-id": "openbkn trace conversations list",
+  "trace-id": "openbkn trace search",
+  "interaction-id": "openbkn trace search",
+  "operation-id": "openbkn trace interactions operations <interaction-id>",
+  "ot-ids": 'openbkn context search-schema <kn-id> "<q>"',
+  "object-type-id": 'openbkn context search-schema <kn-id> "<q>"',
+  "execution-id": "openbkn bkn action-log list <kn-id>",
+  "receipt-id": "openbkn trace interactions operations <interaction-id>",
+  "conversation-ids": "openbkn trace conversations list",
+  "model-ids": "openbkn model llm list",
+  "tool-ids": "openbkn tool list --toolbox <box-id>",
+  "document-id": "openbkn vega resource document-get <resource-id> <document-id>",
+  "document-ids": "openbkn vega resource document-get <resource-id> <document-id>",
+  // Named entities, wherever they appear; the overrides below cover the cases
+  // where the same word means something else.
+  role: "openbkn admin role list",
+  user: "openbkn admin user list"
+};
+var ARGUMENT_OVERRIDES = {
+  "admin role add-member|id": "openbkn admin user list",
+  "admin role remove-member|id": "openbkn admin user list",
+  "admin user assign-role|role": "openbkn admin role list",
+  "admin user revoke-role|role": "openbkn admin role list",
+  "admin user roles|user": "openbkn admin user list",
+  "admin role members|role": "openbkn admin role list",
+  "auth switch|user": "openbkn auth users <url>",
+  "admin auth switch|user": "openbkn admin auth users <url>"
+};
+var GROUP_ID_SOURCES = [
+  [/^vega catalog\b/, "openbkn vega catalog list"],
+  [/^vega resource\b/, "openbkn vega catalog resources <catalog-id>"],
+  [/^vega discover-schedule\b/, "openbkn vega discover-schedule list"],
+  [/^vega discover-task\b/, "openbkn vega discover-task list"],
+  [/^vega semantic-task\b/, "openbkn vega semantic-task list"],
+  [/^vega dataset\b/, "openbkn vega dataset build-list"],
+  [/^bkn action-schedule\b/, "openbkn bkn action-schedule list <kn-id>"],
+  [/^vega connector-type\b/, "openbkn vega connector-type list"],
+  [/^resource\b/, "openbkn resource list"],
+  [/^skill\b/, "openbkn skill list"],
+  [/^toolbox\b/, "openbkn toolbox list"],
+  [/^tool\b/, "openbkn tool list --toolbox <box-id>"],
+  [/^appkey\b/, "openbkn appkey list"],
+  [/^admin org\b/, "openbkn admin org list"],
+  [/^auth\b/, "openbkn auth list"],
+  [/^admin user\b/, "openbkn admin user list"],
+  [/^admin role\b/, "openbkn admin role list"],
+  [/^admin llm\b/, "openbkn admin llm list"],
+  [/^admin small-model\b/, "openbkn admin small-model list"],
+  [/^model llm\b/, "openbkn model llm list"],
+  [/^model small\b/, "openbkn model small list"],
+  [/^bkn object-type\b/, "openbkn bkn object-type list <kn-id>"],
+  [/^bkn relation-type\b/, "openbkn bkn relation-type list <kn-id>"],
+  [/^bkn action-type\b/, "openbkn bkn action-type list <kn-id>"],
+  [/^bkn concept-group\b/, "openbkn bkn concept-group list <kn-id>"],
+  [/^bkn action-schedule\b/, "openbkn bkn action-schedule list <kn-id>"],
+  [/^bkn action-log\b/, "openbkn bkn action-log list <kn-id>"]
+];
+function sourceOf(argName, path, isLast) {
+  const override = ARGUMENT_OVERRIDES[`${path.join(" ")}|${argName}`];
+  if (override !== void 0) return override ?? void 0;
+  const byName = ID_SOURCES[argName];
+  if (byName) return byName;
+  if (!isLast) return void 0;
+  const generic = /^(id|ids|cg-id|modelid|role|user|schedule-id|schedule-ids|task-id|log-id)$/i.test(argName);
+  if (!generic) return void 0;
+  const parent = path.slice(0, -1).join(" ");
+  return GROUP_ID_SOURCES.find(([re]) => re.test(parent))?.[1];
+}
+function describeOption(opt) {
+  return {
+    flags: opt.flags,
+    description: opt.description,
+    ...opt.mandatory ? { mandatory: true } : {},
+    ...opt.required || opt.optional ? { takesValue: true } : {},
+    ...opt.defaultValue === void 0 ? {} : { default: opt.defaultValue }
+  };
+}
+var RETURN_SHAPES = returns_default.commands;
+function shapeOf(path) {
+  return RETURN_SHAPES[path];
+}
+var activeProbe;
+function describeNode(cmd, parentPath, depth) {
+  const path = [...parentPath, cmd.name()];
+  const children = cmd.commands.filter((c) => !c.name().startsWith("help"));
+  const state = activeProbe ? availabilityOf(path.join(" "), activeProbe) : void 0;
+  const skeleton = {
+    path: path.join(" "),
+    name: cmd.name(),
+    section: sectionOf(cmd),
+    summary: cmd.description(),
+    ...shapeOf(path.join(" ")) ? { returns: shapeOf(path.join(" ")) } : {},
+    ...state ? { available: state.available } : {},
+    ...state?.reason ? { unavailable: state.reason } : {}
+  };
+  if (depth <= 0) return children.length ? { ...skeleton, hasCommands: true } : skeleton;
+  const aliases = cmd.aliases();
+  const options = cmd.options.filter((o) => o.long !== "--help");
+  return {
+    ...skeleton,
+    ...aliases.length ? { aliases } : {},
+    ...cmd.registeredArguments.length ? {
+      arguments: cmd.registeredArguments.map((arg, index, all) => {
+        const from = sourceOf(arg.name(), path, index === all.length - 1);
+        return {
+          name: arg.name(),
+          required: arg.required,
+          variadic: arg.variadic,
+          ...arg.description ? { description: arg.description } : {},
+          ...from ? { from } : {}
+        };
+      })
+    } : {},
+    ...options.length ? { options: options.map(describeOption) } : {},
+    ...guideOf(cmd) ? { guide: guideOf(cmd) } : {},
+    ...children.length ? { commands: children.map((child) => describeNode(child, path, depth - 1)) } : {}
+  };
+}
+var FIELD_MEANINGS = {
+  returns: "top-level keys observed on a live deploy \u2014 evidence for parsing, not a contract; absent where nothing was recorded",
+  available: "whether this deploy can answer the command (only after --probe). Checked per service and per MCP tool, so a command can still be refused for a capability the probe cannot see",
+  unavailable: "why it cannot; absent when it can",
+  probe: "what the probe asked and found: one read per service, plus the MCP tool catalog",
+  path: "full command path \u2014 run it as `openbkn <path>`",
+  section: "which section the command sits in; see `sections`",
+  summary: "what the command does; often names the shape it answers with",
+  hasCommands: "this walk stopped here \u2014 ask for this path to see deeper",
+  arguments: "positional arguments, in order",
+  "arguments[].from": "the command that hands out this argument's value",
+  options: "flags; `mandatory` and `takesValue` appear only when true",
+  guide: "prose the command's own --help prints under its command list",
+  commands: "nested commands"
+};
+function resolve2(program2, path) {
+  let node = program2;
+  for (const name of path) {
+    const child = node.commands.find((c) => c.name() === name || c.aliases().includes(name));
+    if (!child) throw new InputError(`no such command: ${path.join(" ")}`);
+    node = child;
+  }
+  return node;
+}
+function describeCommandTree(program2, opts = {}) {
+  activeProbe = opts.probe;
+  const depth = opts.depth === void 0 ? Number.MAX_SAFE_INTEGER : opts.depth - 1;
+  if (opts.path?.length) {
+    return {
+      sections: SECTION_MEANINGS,
+      fields: FIELD_MEANINGS,
+      ...describeNode(resolve2(program2, opts.path), opts.path.slice(0, -1), depth + 1)
+    };
+  }
+  const top = program2.commands.filter(
+    (c) => !c.name().startsWith("help") && c.name() !== "describe"
+  );
+  return {
+    name: program2.name(),
+    version: program2.version(),
+    summary: program2.description(),
+    sections: SECTION_MEANINGS,
+    fields: FIELD_MEANINGS,
+    ...opts.probe ? { probe: opts.probe } : {},
+    commands: top.map((cmd) => describeNode(cmd, [], depth)),
+    globalOptions: program2.options.filter((o) => o.long !== "--help").map(describeOption),
+    guide: guideOf(program2)
+  };
+}
+function rows(node, indent = "") {
+  const out = [
+    {
+      indent,
+      name: `${node.path.split(" ").pop()}${node.hasCommands ? " \u2026" : ""}`,
+      section: node.section === DEFAULT_SECTION ? "" : node.section,
+      summary: node.available === false ? `[unavailable] ${node.unavailable ?? ""} \u2014 ${node.summary}` : node.summary
+    }
+  ];
+  for (const child of node.commands ?? []) out.push(...rows(child, `${indent}  `));
+  return out;
+}
+function renderText(tree) {
+  const root = tree;
+  const out = [];
+  if (root.sections) {
+    const width = Math.max(...Object.keys(root.sections).map((k) => k.length));
+    out.push("SECTIONS");
+    for (const [name, meaning] of Object.entries(root.sections)) {
+      out.push(`  ${name.padEnd(width)}  ${meaning}`);
+    }
+    out.push("");
+  }
+  const nodes = root.path ? [tree] : root.commands ?? [];
+  const truncated = nodes.some(function deeper(n) {
+    return Boolean(n.hasCommands) || (n.commands ?? []).some(deeper);
+  });
+  const table = nodes.flatMap((node) => rows(node));
+  const nameWidth = Math.max(...table.map((r) => r.indent.length + r.name.length));
+  const sectionWidth = Math.max(...table.map((r) => r.section.length));
+  for (const r of table) {
+    const name = `${r.indent}${r.name}`.padEnd(nameWidth);
+    out.push(`${name}  ${r.section.padEnd(sectionWidth)}  ${r.summary}`.trimEnd());
+  }
+  if (truncated) {
+    out.push("", "\u2026 has subcommands \u2014 `openbkn describe <command>`, or raise --depth");
+  }
+  return out.join("\n");
+}
+function describeCommand(program2) {
+  const cmd = new Command8("describe").description("Print the command tree \u2014 paths, sections, flags (--json for the data)").argument("[command...]", "only this subtree, e.g. `describe bkn metric`").option(
+    "--depth <n>",
+    "how many levels to walk (1 = this level only)",
+    (v) => Number.parseInt(v, 10)
+  ).option("--pretty", "indent the JSON instead of packing it onto one line").option("--probe", "ask this deploy which commands it can answer (read-only, ~7 requests)").action(async (path, opts, self) => {
+    const probe = opts.probe ? await probeDeploy(self, (/* @__PURE__ */ new Date()).toISOString()) : void 0;
+    const tree = describeCommandTree(program2, { path, depth: opts.depth, probe });
+    const out = outputOptions(self);
+    if (!out.json && !out.compact && !opts.pretty) {
+      process.stdout.write(`${renderText(tree)}
+`);
+      return;
+    }
+    printJson(tree, { ...out, json: Boolean(opts.pretty), compact: !opts.pretty });
+  });
+  return group(cmd, "COMMANDS");
+}
+
+// src/commands/function.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { Command as Command9 } from "commander";
+var int5 = (v) => Number.parseInt(v, 10);
+function readCode(file) {
+  try {
+    return readFileSync4(file === "-" ? 0 : file, "utf8");
+  } catch (err) {
+    throw new InputError(
+      `Cannot read ${file === "-" ? "stdin" : file}: ${err instanceof Error ? err.message : err}`
+    );
+  }
+}
+function collectDep(value, previous = []) {
+  const at = value.lastIndexOf("@");
+  const name = at > 0 ? value.slice(0, at) : value;
+  const version = at > 0 ? value.slice(at + 1) : void 0;
+  if (!name) throw new InputError("--dep takes <name> or <name>@<version>");
+  return [...previous, version ? { name, version } : { name }];
+}
+function parseJsonOption(raw, label) {
+  if (raw === void 0) return void 0;
+  try {
+    return parseBigIntJSON(raw);
+  } catch {
+    throw new InputError(`--${label} must be valid JSON`);
+  }
+}
+function definitionFlags(c) {
+  return c.option("--name <n>", "name; required when the definition is a function").option("--description <d>", "what it does \u2014 the model reads this to decide when to call it").option("--type <t>", "function | openapi", "function").option("--inputs <json>", "input parameters: [{name,type,required,description}]").option("--outputs <json>", "output parameters, same shape as --inputs").option("--dep <name@version>", "package to install before running (repeatable)", collectDep).option("--index-url <url>", "package index to install from");
+}
+function parameterList(raw, label) {
+  const parsed = parseJsonOption(raw, label);
+  if (parsed === void 0) return void 0;
+  if (!Array.isArray(parsed)) throw new InputError(`--${label} must be a JSON array of parameters`);
+  return parsed;
+}
+function functionDefinitionFrom(file, opts) {
+  if (!opts.name) throw new InputError("--name is required for a function");
+  return {
+    name: opts.name,
+    description: opts.description,
+    code: readCode(file),
+    inputs: parameterList(opts.inputs, "inputs"),
+    outputs: parameterList(opts.outputs, "outputs"),
+    dependencies: opts.dep,
+    dependenciesUrl: opts.indexUrl
+  };
+}
+function functionCommand() {
+  const cmd = new Command9("function").description(
+    "Sandbox functions: run Python on the platform without registering anything"
+  );
+  cmd.command("run <file>").description("Run a file (or `-` for stdin) in the sandbox; exits non-zero when the code does").option("--event <json>", "the single argument handler() receives", "{}").option("--timeout <s>", "sandbox timeout in seconds", int5).option("--dep <name@version>", "install a package first (repeatable)", collectDep).option("--index-url <url>", "package index to install from (default PyPI)").option(
+    "--pass-token",
+    "put your credential in the sandbox's BKN_TOKEN so `sandbox_sdk.bkn` calls BKN as you"
+  ).action(async (file, opts, cmd2) => {
+    const client = clientFrom(cmd2);
+    const result = await client.functions.run({
+      code: readCode(file),
+      event: parseJsonOption(opts.event, "event") ?? {},
+      timeout: opts.timeout,
+      dependencies: opts.dep,
+      dependenciesUrl: opts.indexUrl,
+      source: "openbkn_cli",
+      // The request headers carry these too, but they stop at the service:
+      // the sandbox reads its own environment, which only these fields fill.
+      conversationId: client.ctx.trace?.conversationId,
+      interactionId: client.ctx.trace?.interactionId,
+      ...opts.passToken ? { bknToken: client.ctx.token } : {}
+    });
+    printJson(result, outputOptions(cmd2));
+    if (result.exit_code !== void 0 && result.exit_code !== 0) process.exitCode = 1;
+  });
+  cmd.command("infer-schema <file>").description(
+    "Derive a tool contract from @tool-decorated code; runs it, answers supported:false when it cannot"
+  ).action(async (file, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).functions.inferSchema(readCode(file)), outputOptions(cmd2));
+  });
+  cmd.command("deps").description("Libraries already installed in the sandbox \u2014 import these without --dep").action(async (_opts, cmd2) => {
+    printJson(await clientFrom(cmd2).functions.dependencies(), outputOptions(cmd2));
+  });
+  cmd.command("versions <package>").description("Versions of one package, asked of the package index live").option("--python <v>", "keep only versions compatible with this Python").option("--index-url <url>", "package index to ask (default PyPI)").action(async (pkg, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).functions.dependencyVersions(pkg, {
+        pythonVersion: opts.python,
+        pypiRepoUrl: opts.indexUrl
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("template").description("The handler() skeleton to start from").option("--type <t>", "template type (python)", "python").action(async (opts, cmd2) => {
+    printJson(await clientFrom(cmd2).functions.template(opts.type), outputOptions(cmd2));
+  });
+  groupChildren(cmd, {
+    READ: ["deps", "versions", "template"],
+    RUN: ["run", "infer-schema"]
+  });
+  guide(
+    cmd,
+    `THE ONE HARD RULE
+  The entry point must be a function named \`handler\`, taking one argument:
+
+      def handler(event: Dict[str, Any]) -> Any:
+          return {"sum": event.get("a", 0) + event.get("b", 0)}
+
+  \`--event\` is that argument, the return value comes back as \`result\`, and
+  \`print\` output as \`stdout\`. \`function template\` prints the skeleton.
+
+  READING THE ANSWER
+  Code that raises still answers HTTP 200 \u2014 \`exit_code\` is the verdict and the
+  traceback is in \`stderr\`. This command exits non-zero to match, so \`&&\` works.
+
+  CONTEXT INSIDE THE SANDBOX
+  --conversation-id / --interaction-id reach the sandbox as BKN_CONVERSATION_ID
+  and BKN_INTERACTION_ID, which is how \`sandbox_sdk.bkn\` hangs its own BKN calls
+  under your interaction. The credential does not travel unless you say so:
+  --pass-token puts it in BKN_TOKEN so that code runs as you.
+
+  ORDER OF WORK
+  function deps                      what is already importable
+  function run ./add.py --event ...  iterate here; nothing is kept
+  toolbox create --type function     a box to keep it in
+  tool create ./add.py --toolbox     the same code, now a tool
+  tool enable <tool-id> --toolbox    a tool is off until enabled, then agents
+                                     can call it`
+  );
+  return group(cmd, "TOOLS & SKILLS");
+}
+
+// src/commands/model.ts
+import { Command as Command10 } from "commander";
+var int6 = (v) => Number.parseInt(v, 10);
+async function resolveLlmModelName(client, model) {
+  if (!/^\d+$/.test(model)) return model;
+  const detail = await client.models.llm.get(model);
+  if (!detail?.model_name) throw new InputError(`No LLM found with id ${model}.`);
+  return detail.model_name;
+}
+function addManagementCommands(parent, kind) {
+  parent.command("add").description("Register a model (definition JSON via --body / --body-file)").option(
+    "--body <json>",
+    "model definition JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+  ).option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
     printJson(await clientFrom(cmd).models[kind].add(readBody(opts)), outputOptions(cmd));
   });
-  parent.command("edit").description("Update a model definition (JSON via --body / --body-file)").option("--body <json>", "model definition JSON").option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
+  parent.command("edit").description("Update a model definition (JSON via --body / --body-file)").option(
+    "--body <json>",
+    "model definition JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+  ).option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
     printJson(await clientFrom(cmd).models[kind].edit(readBody(opts)), outputOptions(cmd));
   });
   parent.command("delete <model-ids>").description("Delete model(s) (comma-joined ids)").action(async (ids, _o, cmd) => {
     printJson(await clientFrom(cmd).models[kind].delete(csv(ids) ?? []), outputOptions(cmd));
   });
-  parent.command("test").description("Test a model's connectivity / inference (JSON via --body / --body-file)").option("--body <json>", "test request JSON").option("--body-file <path>", "read test request JSON from a file").action(async (opts, cmd) => {
+  parent.command("test").description("Test a model's connectivity / inference (JSON via --body / --body-file)").option(
+    "--body <json>",
+    "test request JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (mf-model-manager)"
+  ).option("--body-file <path>", "read test request JSON from a file").action(async (opts, cmd) => {
     printJson(await clientFrom(cmd).models[kind].test(readBody(opts)), outputOptions(cmd));
   });
 }
 function modelCommand() {
-  const model = new Command11("model").description(
-    "Model factory \u2014 LLM / small-model CRUD, chat / embeddings / rerank, default selection"
+  const model = new Command10("model").description(
+    "Large and small models: chat, embeddings, rerank, defaults"
   );
   const llm = model.command("llm").description("Large language models");
-  llm.command("list").description("List LLM models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1).action(async (opts, cmd) => {
+  llm.command("list").description("List LLM models \u2192 {data, count}").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int6, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int6, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.llm.list({
         name: opts.name,
@@ -2052,7 +3141,7 @@ function modelCommand() {
   });
   addManagementCommands(llm, "llm");
   const small = model.command("small").description("Small models (embedding / reranker)");
-  small.command("list").description("List small models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1).action(async (opts, cmd) => {
+  small.command("list").description("List small models \u2192 {data, count}").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int6, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int6, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.list({
         name: opts.name,
@@ -2066,13 +3155,13 @@ function modelCommand() {
   small.command("get <modelId>").description("Get a small model").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).models.small.get(id), outputOptions(cmd));
   });
-  small.command("embeddings <modelId>").description("Compute embeddings").requiredOption("-i, --input <text>", "comma-separated input texts").action(async (id, opts, cmd) => {
+  small.command("embeddings <model>").description("Compute embeddings (<model> = model name or numeric id)").requiredOption("-i, --input <text>", "comma-separated input texts").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.embeddings(id, csv(opts.input) ?? []),
       outputOptions(cmd)
     );
   });
-  small.command("rerank <modelId>").description("Rerank documents against a query").requiredOption("-q, --query <text>", "query").requiredOption("-d, --documents <list>", "comma-separated documents").action(async (id, opts, cmd) => {
+  small.command("rerank <model>").description("Rerank documents against a query (<model> = model name or numeric id)").requiredOption("-q, --query <text>", "query").requiredOption("-d, --documents <list>", "comma-separated documents").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.rerank(id, opts.query, csv(opts.documents) ?? []),
       outputOptions(cmd)
@@ -2103,42 +3192,38 @@ Examples:
   $ openbkn model small get-default --type embedding            # current default
   $ openbkn model small set-default <id>                        # default embedding/reranker`
   );
-  return group(model, "MODELS & SKILLS");
+  for (const kind of [llm, small]) {
+    groupChildren(kind, {
+      READ: ["list", "get", "get-default"],
+      RUN: ["chat", "embeddings", "rerank", "test"],
+      WRITE: ["add", "edit", "delete", "set-default", "unset-default"]
+    });
+  }
+  return group(model, "MODELS");
 }
 
 // src/commands/resource.ts
-import { Command as Command12 } from "commander";
-var int9 = (v) => Number.parseInt(v, 10);
-var parsePairs = (raw) => {
-  if (!raw) return void 0;
-  return raw.split(",").map((part) => {
-    const idx = part.indexOf("=");
-    if (idx < 1) throw new Error("--extension must be key=value[,key=value]");
-    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
-  }).filter((p) => p.key.length > 0);
-};
+import { Command as Command11 } from "commander";
+var int7 = (v) => Number.parseInt(v, 10);
 function resourceCommand() {
-  const cmd = new Command12("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
-  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--datasource-id <id>", "alias of --catalog-id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int9, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd2) => {
+  const cmd = new Command11("resource").alias("res").description("Tables and views behind a network: find, inspect, sample, enable, disable");
+  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--status <status>", "filter by status").option("--schema <name>", "filter by source schema").option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 0).option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.list({
-      datasourceId: opts.catalogId ?? opts.datasourceId,
+      catalogId: opts.catalogId,
       category: opts.category ?? opts.type,
       status: opts.status,
-      database: opts.database,
+      schema: opts.schema,
       limit: opts.limit,
       offset: opts.offset,
-      includeExtensions: opts.includeExtensions,
-      includeExtensionKeys: opts.includeExtensionKeys,
-      extensionPairs: parsePairs(opts.extension),
       sort: opts.sort,
       direction: opts.direction
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").option("--limit <n>", "rows to scan before filtering", int9, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
+  cmd.command("find").description("Search resources by name, fuzzy unless --exact \u2192 a bare array, not an envelope").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--limit <n>", "rows to scan before filtering", int7, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
-      datasourceId: opts.catalogId ?? opts.datasourceId,
+      catalogId: opts.catalogId,
       limit: opts.limit
     });
     printJson(data, outputOptions(cmd2));
@@ -2146,7 +3231,14 @@ function resourceCommand() {
   cmd.command("get <id>").description("Get resource details").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.get(id), outputOptions(cmd2));
   });
-  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int9).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
+  for (const action of ["enable", "disable"]) {
+    cmd.command(`${action} <id>`).description(`${action[0]?.toUpperCase()}${action.slice(1)} a resource`).action(async (id, _opts, cmd2) => {
+      const api = clientFrom(cmd2).resource;
+      const result = action === "enable" ? await api.enable(id) : await api.disable(id);
+      printJson(result, outputOptions(cmd2));
+    });
+  }
+  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int7, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int7, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int7).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.query(id, {
       limit: opts.limit,
       offset: opts.offset,
@@ -2160,12 +3252,17 @@ function resourceCommand() {
   cmd.command("delete <id>").description("Delete a resource").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.delete(id), outputOptions(cmd2));
   });
-  return group(cmd, "AI DATA PLATFORM");
+  groupChildren(cmd, {
+    READ: ["list", "find", "get"],
+    RUN: ["query"],
+    WRITE: ["enable", "disable", "delete"]
+  });
+  return group(cmd, "DATA & KNOWLEDGE");
 }
 
 // src/commands/skill.ts
-import { Command as Command13 } from "commander";
-var int10 = (v) => Number.parseInt(v, 10);
+import { Command as Command12 } from "commander";
+var int8 = (v) => Number.parseInt(v, 10);
 var positiveInt = (flag) => (v) => {
   if (!/^\d+$/.test(v)) {
     throw new InputError(`${flag} must be a positive integer (got '${v}')`);
@@ -2190,9 +3287,15 @@ function checkSource(source) {
 }
 var draftOption = (c) => c.option("--draft", "read the draft (management) version instead of the published one");
 function skillCommand() {
-  const cmd = new Command13("skill").description("Skill registry and market");
-  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int10, 1);
-  listOpts(cmd.command("list").description("List skills")).option("--create-user <s>", "filter by creator").action(async (opts, cmd2) => {
+  const cmd = new Command12("skill").description(
+    "Skill packages (SKILL.md + files) agents load on demand"
+  );
+  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1);
+  listOpts(
+    cmd.command("list").description(
+      "List skills \u2192 {data, total, page, page_size, has_next}; the id to reuse is `skill_id`"
+    )
+  ).option("--create-user <s>", "filter by creator").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).skills.list({
         name: opts.name,
@@ -2208,19 +3311,19 @@ function skillCommand() {
   cmd.command("get <skill-id>").description("Get a skill by id").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.get(id), outputOptions(cmd2));
   });
-  listOpts(cmd.command("market").description("Browse the skill market")).action(
-    async (opts, cmd2) => {
-      printJson(
-        await clientFrom(cmd2).skills.market({
-          name: opts.name,
-          source: opts.source,
-          pageSize: opts.limit,
-          page: opts.page
-        }),
-        outputOptions(cmd2)
-      );
-    }
-  );
+  listOpts(
+    cmd.command("market").description("Browse the skill market \u2192 {data, total, page, has_next}")
+  ).action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.market({
+        name: opts.name,
+        source: opts.source,
+        pageSize: opts.limit,
+        page: opts.page
+      }),
+      outputOptions(cmd2)
+    );
+  });
   cmd.command("market-get <skill-id>").description("Get a market skill by id").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.marketGet(id), outputOptions(cmd2));
   });
@@ -2329,7 +3432,7 @@ ${files.length} files, ${bytes} B
     );
   });
   cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
-    const extendInfo = opts.extendInfo ? JSON.parse(opts.extendInfo) : void 0;
+    const extendInfo = opts.extendInfo ? parseBigIntJSON(opts.extendInfo) : void 0;
     printJson(
       await clientFrom(cmd2).skills.register(dir, {
         source: checkSource(opts.source),
@@ -2347,7 +3450,10 @@ ${files.length} files, ${bytes} B
   cmd.command("install <skill-id> [directory]").description("Download a skill archive and extract it locally").action(async (skillId, dir, _o, cmd2) => {
     printJson(await clientFrom(cmd2).skills.install(skillId, dir), outputOptions(cmd2));
   });
-  cmd.command("update-metadata <skill-id>").description("Update a skill's metadata (--body / --body-file JSON)").option("--body <json>", "metadata JSON").option("--body-file <path>", "read metadata JSON from a file").action(async (skillId, opts, cmd2) => {
+  cmd.command("update-metadata <skill-id>").description("Update a skill's metadata (--body / --body-file JSON)").option(
+    "--body <json>",
+    "metadata JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (execution-factory)"
+  ).option("--body-file <path>", "read metadata JSON from a file").action(async (skillId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).skills.updateMetadata(skillId, readBody(opts)),
       outputOptions(cmd2)
@@ -2365,15 +3471,53 @@ ${files.length} files, ${bytes} B
       outputOptions(cmd2)
     );
   });
-  return group(cmd, "MODELS & SKILLS");
+  groupChildren(cmd, {
+    READ: [
+      "list",
+      "market",
+      "get",
+      "market-get",
+      "names",
+      "content",
+      "read-file",
+      "files",
+      "history"
+    ],
+    RUN: ["execute", "download", "install"],
+    WRITE: [
+      "register",
+      "update-metadata",
+      "update-package",
+      "set-status",
+      "republish",
+      "publish-history",
+      "delete"
+    ]
+  });
+  guide(
+    cmd,
+    `READING A SKILL
+  content <id> gives the SKILL.md index; files <id> [path] walks the package; read-file
+  pulls one file. Read progressively \u2014 do not download the whole archive to answer a question.
+
+PUBLISHED VS DRAFT
+  Read commands return the published version. --draft reads the editing copy instead, which
+  is what a Studio user sees. The two differ whenever changes are unpublished.
+
+AUTHORING
+  register <dir> zips and registers; update-package replaces the files; update-metadata
+  changes only the metadata. set-status and republish move versions around.`
+  );
+  return group(cmd, "TOOLS & SKILLS");
 }
 
 // src/commands/toolbox.ts
-import { Command as Command14 } from "commander";
-var int11 = (v) => Number.parseInt(v, 10);
+import { Command as Command13 } from "commander";
+import yaml from "js-yaml";
+var int9 = (v) => Number.parseInt(v, 10);
 function toolboxCommand() {
-  const cmd = new Command14("toolbox").description("Agent toolbox lifecycle");
-  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).action(async (opts, cmd2) => {
+  const cmd = new Command13("toolbox").description("Toolboxes: group tools into one publishable box");
+  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int9, 0).action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.list({
         keyword: opts.keyword,
@@ -2383,12 +3527,21 @@ function toolboxCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("create").description("Create a toolbox").requiredOption("--name <name>", "toolbox name").requiredOption("--service-url <url>", "tool service URL").option("--description <d>", "description").action(async (opts, cmd2) => {
+  cmd.command("create").description(
+    "Create a toolbox \u2014 openapi proxies to a service, function holds platform functions"
+  ).requiredOption("--name <name>", "toolbox name").option("--service-url <url>", "where an openapi box proxies its tools; required for that type").option("--type <t>", "openapi | function", "openapi").option("--description <d>", "description").action(async (opts, cmd2) => {
+    if (opts.type !== "openapi" && opts.type !== "function") {
+      throw new InputError("--type must be openapi or function");
+    }
+    if (opts.type === "openapi" && !opts.serviceUrl) {
+      throw new InputError("--service-url is required for an openapi toolbox");
+    }
     printJson(
       await clientFrom(cmd2).toolboxes.create({
         name: opts.name,
         serviceUrl: opts.serviceUrl,
-        description: opts.description
+        description: opts.description,
+        metadataType: opts.type
       }),
       outputOptions(cmd2)
     );
@@ -2411,11 +3564,36 @@ function toolboxCommand() {
   cmd.command("import <file>").description("Import a toolbox config from a local .adp file").option("--type <t>", "impex type: toolbox | mcp | operator", "toolbox").action(async (file, opts, cmd2) => {
     printJson(await clientFrom(cmd2).toolboxes.import(file, opts.type), outputOptions(cmd2));
   });
-  return group(cmd, "DECISION AGENT");
+  groupChildren(cmd, {
+    READ: ["list", "export"],
+    WRITE: ["create", "publish", "unpublish", "delete", "import"]
+  });
+  guide(
+    cmd,
+    `TWO KINDS OF BOX
+  --type openapi   its tools proxy to --service-url; they come from a spec
+  --type function  its tools are platform functions, no service URL to give
+
+  ORDER OF WORK
+  toolbox create --name "<n>"        an empty box, in draft
+  tool create ./add.py --toolbox     a function tool, or --type openapi for a spec
+  tool enable <tool-ids...>          a tool is off until enabled
+  toolbox publish <box-id>           the box becomes visible in the market
+  tool execute <tool-id>             call an enabled tool
+  tool debug <tool-id>               call one that is not, while building it
+
+  Publishing the box is about the market, not about calling: an enabled tool in
+  an unpublished box executes. \`tool enable\` is the gate.
+
+  export / import move a whole box between deploys as an .adp file.`
+  );
+  return group(cmd, "TOOLS & SKILLS");
 }
 function toolCommand() {
-  const cmd = new Command14("tool").description("Tools inside a toolbox");
-  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int11).option("--page <n>", "page (1-based; backend default 1)", int11).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
+  const cmd = new Command13("tool").description(
+    "Tools in a box: add one from code or a spec, enable it, call it"
+  );
+  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int9).option("--page <n>", "page (1-based; backend default 1)", int9).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
         page: opts.page,
@@ -2437,55 +3615,120 @@ function toolCommand() {
       outputOptions(cmd2)
     );
   });
-  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option("--body <json>", "request body JSON").option("--header <json>", "headers map JSON").option("--query <json>", "query params JSON").option("--path <json>", "path params JSON").option("--timeout <s>", "per-call timeout seconds", int11);
+  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option(
+    "--body <json>",
+    "request body JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (execution-factory)"
+  ).option("--header <json>", "headers map JSON").option("--query <json>", "query params JSON").option("--path <json>", "path params JSON").option("--timeout <s>", "per-call timeout seconds", int9);
   const parseJson = (s, label) => {
     if (!s) return void 0;
     try {
-      return JSON.parse(s);
+      return parseBigIntJSON(s);
     } catch {
       throw new InputError(`--${label} must be valid JSON`);
     }
   };
   const buildEnvelope = (opts) => ({
-    body: opts.body ? JSON.parse(opts.body) : void 0,
+    body: opts.body ? parseBigIntJSON(opts.body) : void 0,
     header: parseJson(opts.header, "header"),
     query: parseJson(opts.query, "query"),
     path: parseJson(opts.path, "path"),
     timeout: opts.timeout ? Number(opts.timeout) : void 0
   });
+  invokeOpts(cmd.command("execute <tool-id>").description("Invoke an enabled tool")).action(
+    async (toolId, opts, cmd2) => {
+      printJson(
+        await clientFrom(cmd2).toolboxes.execute(opts.toolbox, toolId, buildEnvelope(opts)),
+        outputOptions(cmd2)
+      );
+    }
+  );
   invokeOpts(
-    cmd.command("execute <tool-id>").description("Invoke a published+enabled tool")
+    cmd.command("debug <tool-id>").description("Invoke a tool that is not enabled yet")
   ).action(async (toolId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).toolboxes.execute(opts.toolbox, toolId, buildEnvelope(opts)),
+      await clientFrom(cmd2).toolboxes.debug(opts.toolbox, toolId, buildEnvelope(opts)),
       outputOptions(cmd2)
     );
   });
-  invokeOpts(
-    cmd.command("debug <tool-id>").description("Invoke a tool (draft/disabled too)")
-  ).action(async (toolId, opts, cmd2) => {
+  const toolFrom = (file, opts) => {
+    if (opts.type === "openapi") {
+      let data;
+      try {
+        data = yaml.load(readCode(file));
+      } catch (err) {
+        throw new InputError(
+          `${file} is not valid JSON or YAML: ${err instanceof Error ? err.message : err}`
+        );
+      }
+      return { metadataType: "openapi", data, useRule: opts.useRule };
+    }
+    if (opts.type !== "function") throw new InputError("--type must be function or openapi");
+    return {
+      metadataType: "function",
+      function: functionDefinitionFrom(file, opts),
+      useRule: opts.useRule
+    };
+  };
+  definitionFlags(
+    cmd.command("create <file>").description(
+      "Create a tool from code (or a spec) \u2014 the only way to add a function tool to a box"
+    ).requiredOption("--toolbox <box-id>", "target toolbox id").option("--use-rule <s>", "usage rule carried onto the tool")
+  ).action(async (file, opts, cmd2) => {
+    const result = await clientFrom(cmd2).toolboxes.createTool(
+      opts.toolbox,
+      toolFrom(file, opts)
+    );
+    printJson(result, outputOptions(cmd2));
+    if (result?.failure_count) process.exitCode = 1;
+  });
+  cmd.command("get <tool-id>").description("One tool in full: metadata, parameters, usage rule").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolId, opts, cmd2) => {
+    printJson(await clientFrom(cmd2).toolboxes.getTool(opts.toolbox, toolId), outputOptions(cmd2));
+  });
+  definitionFlags(
+    cmd.command("update <tool-id> <file>").description("Replace a tool's definition; the id survives and an enabled tool stays enabled").requiredOption("--toolbox <box-id>", "toolbox id").option("--use-rule <s>", "usage rule carried onto the tool")
+  ).action(async (toolId, file, opts, cmd2) => {
+    if (!opts.name || !opts.description) {
+      throw new InputError(
+        "--name and --description are required: update replaces the tool, it does not patch it"
+      );
+    }
     printJson(
-      await clientFrom(cmd2).toolboxes.debug(opts.toolbox, toolId, buildEnvelope(opts)),
+      await clientFrom(cmd2).toolboxes.updateTool(opts.toolbox, toolId, {
+        ...toolFrom(file, opts),
+        name: opts.name,
+        description: opts.description
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("delete <tool-ids...>").description("Delete tools from a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("-y, --yes", "skip confirmation").action(async (toolIds, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.deleteTools(opts.toolbox, toolIds),
       outputOptions(cmd2)
     );
   });
-  cmd.command("upload <file>").description("Upload a tool definition file (OpenAPI spec) into a toolbox").requiredOption("--toolbox <id>", "target toolbox id").option("--metadata-type <t>", "metadata type", "openapi").action(async (file, opts, cmd2) => {
+  cmd.command("upload <file>").description("Add tools from an OpenAPI file \u2014 `tool create` is the same endpoint, as JSON").requiredOption("--toolbox <id>", "target toolbox id").option("--metadata-type <t>", "metadata type", "openapi").action(async (file, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.upload(opts.toolbox, file, opts.metadataType),
       outputOptions(cmd2)
     );
   });
-  return group(cmd, "DECISION AGENT");
+  groupChildren(cmd, {
+    READ: ["list", "get"],
+    RUN: ["execute", "debug"],
+    WRITE: ["create", "update", "delete", "enable", "disable", "upload"]
+  });
+  return group(cmd, "TOOLS & SKILLS");
 }
 
 // src/commands/trace.ts
-import { readFileSync as readFileSync5, writeFileSync } from "fs";
-import { Command as Command15 } from "commander";
+import { readFileSync as readFileSync6, writeFileSync } from "fs";
+import { Command as Command14 } from "commander";
 
 // src/bkn-trace/schema-validate.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 import { extname } from "path";
-import yaml from "js-yaml";
+import yaml2 from "js-yaml";
 import { z } from "zod";
 var Assertion = z.object({
   type: z.enum([
@@ -2520,10 +3763,10 @@ var DiagnosisRule = z.object({
   params: z.record(z.string(), z.unknown()).optional()
 });
 function parseFile(file) {
-  const text = readFileSync4(file, "utf8");
+  const text = readFileSync5(file, "utf8");
   const ext = extname(file).toLowerCase();
-  if (ext === ".yaml" || ext === ".yml") return yaml.load(text);
-  return JSON.parse(text);
+  if (ext === ".yaml" || ext === ".yml") return yaml2.load(text);
+  return parseBigIntJSON(text);
 }
 function inferKind(data) {
   if (data && typeof data === "object" && !Array.isArray(data)) {
@@ -2557,9 +3800,44 @@ function validateSchemaFile(file, kind) {
 }
 
 // src/commands/trace.ts
+function renderPayload(payload) {
+  if (!payload) return "-";
+  if (payload.mode === "inline") return stringifyBigIntJSON(payload.inline);
+  if (payload.mode === "referenced") return `[referenced] ${payload.ref ?? "-"}`;
+  return `[omitted] ${payload.omitted_reason ?? "unknown"}`;
+}
+function renderTechnicalTraceDetail(detail) {
+  const lines = [
+    `Trace: ${detail.summary.trace_id}`,
+    `Status: ${detail.summary.status}`,
+    `Request: ${detail.summary.request_id || "-"}`,
+    `Question: ${detail.summary.question_preview || "-"}`,
+    `Result: ${detail.summary.result_preview || "-"}`,
+    `Service: ${detail.summary.root_service || "-"}`,
+    `Spans: ${detail.graph?.data.nodes.length ?? 0}`
+  ];
+  if (detail.partial) {
+    lines.push(`Partial: ${(detail.partial_reasons ?? []).join(", ") || "yes"}`);
+  }
+  for (const operation of detail.operations) {
+    lines.push(
+      "",
+      `${operation.fact.tool_name} \xB7 ${operation.fact.operation_id} \xB7 attempt ${operation.fact.attempt} \xB7 ${operation.state}`,
+      `Source: ${operation.fact.protocol}/${operation.fact.source_module}`,
+      `Input: ${renderPayload(operation.fact.input)}`
+    );
+    if (operation.fact.output) lines.push(`Output: ${renderPayload(operation.fact.output)}`);
+    if (operation.fact.error) lines.push(`Error: ${renderPayload(operation.fact.error)}`);
+    if (operation.partial_reasons?.length) {
+      lines.push(`Partial: ${operation.partial_reasons.join(", ")}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
 function traceCommand() {
-  const cmd = new Command15("trace").description(
-    "BKN Trace \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
+  const cmd = new Command14("trace").description(
+    "Inspect what an agent actually did, and diagnose bad answers"
   );
   cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).trace.graph(traceId), outputOptions(cmd2));
@@ -2633,8 +3911,17 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
+  interactions.command("operations <interaction-id>").description("List the exact Operation call facts for one interaction").action(async (interactionId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.listInteractionOperations(interactionId),
+      outputOptions(cmd2)
+    );
+  });
   for (const action of ["complete", "fail", "cancel", "handoff"]) {
-    interactions.command(`${action} <interaction-id>`).description(`${action} a managed interaction using a 3.0 completion manifest`).requiredOption("--body-file <path>", "read completion manifest JSON from a protected file").action(async (interactionId, opts, cmd2) => {
+    interactions.command(`${action} <interaction-id>`).description(`${action} a managed interaction using a 3.0 completion manifest`).requiredOption(
+      "--body-file <path>",
+      "read completion manifest JSON from a protected file \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (agent-observability)"
+    ).action(async (interactionId, opts, cmd2) => {
       const input = readBody(opts);
       const lifecycle = clientFrom(cmd2).trace.lifecycle;
       const terminal = {
@@ -2653,7 +3940,20 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
-  operations.command("retry <operation-id>").description("Create the next retry attempt for an eligible failed operation").requiredOption("--body-file <path>", "read retry request JSON from a protected file").action(async (operationId, opts, cmd2) => {
+  operations.command("attempt <operation-id> <attempt>").description("Get one exact Operation attempt call fact").action(async (operationId, attempt, _opts, cmd2) => {
+    if (!/^[1-9]\d*$/.test(attempt)) {
+      throw new InputError("attempt must be a positive integer");
+    }
+    const ordinal = Number.parseInt(attempt, 10);
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getOperationAttempt(operationId, ordinal),
+      outputOptions(cmd2)
+    );
+  });
+  operations.command("retry <operation-id>").description("Create the next retry attempt for an eligible failed operation").requiredOption(
+    "--body-file <path>",
+    "read retry request JSON from a protected file \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (agent-observability)"
+  ).action(async (operationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.lifecycle.retryOperationAttempt(
         operationId,
@@ -2666,14 +3966,41 @@ function traceCommand() {
   receipts.command("get <receipt-id>").description("Get an authorized operation receipt").action(async (receiptId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).trace.lifecycle.getReceipt(receiptId), outputOptions(cmd2));
   });
-  cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
+  cmd.command("get <conversation-id>").description("Fetch normalized spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("detail <trace-id>").description("Get one typed technical trace with Span and Operation facts").action(async (traceId, _opts, cmd2) => {
+    const detail = await clientFrom(cmd2).trace.get(traceId);
+    const output = outputOptions(cmd2);
+    if (output.json || output.compact) printJson(detail, output);
+    else process.stdout.write(renderTechnicalTraceDetail(detail));
+  });
+  cmd.command("spans <conversation-id>").description("Fetch normalized spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("search").description("Raw trace search (--body / --body-file OpenSearch JSON)").option("--body <json>", "search body JSON").option("--body-file <path>", "read search body JSON from a file").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).trace.search(readBody(opts)), outputOptions(cmd2));
+  cmd.command("search").description("List authorized technical traces \u2192 {entries, total, next_cursor, partial}").option("--limit <n>", "page size, 1..200", (value) => Number.parseInt(value, 10)).option("--cursor <cursor>", "opaque pagination cursor").option("--from <time>", "started at or after this RFC3339 timestamp").option("--to <time>", "started at or before this RFC3339 timestamp").option("--status <status>", "execution status").option("--service <service>", "exact producing service").option("--tool <tool>", "exact root tool").option("--trace-id <id>", "exact Trace ID").option("--error-keyword <text>", "case-insensitive error text").option("--conversation-id <id>", "exact conversation ID").option("--interaction-id <id>", "exact interaction ID").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.search({
+        limit: opts.limit,
+        cursor: opts.cursor,
+        from: opts.from,
+        to: opts.to,
+        status: opts.status,
+        service: opts.service,
+        tool: opts.tool,
+        traceId: opts.traceId,
+        errorKeyword: opts.errorKeyword,
+        conversationId: opts.conversationId,
+        interactionId: opts.interactionId
+      }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("diagnose <conversation-id>").description("Diagnose a conversation's trace (symbolic rules; --llm adds rubric judging)").option("--llm", "also run LLM-judged rubric rules via the local `claude` CLI").action(async (conversationId, opts, cmd2) => {
     const report = await clientFrom(cmd2).trace.diagnose(conversationId, {
@@ -2690,27 +4017,17 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
-  const evalSet = cmd.command("eval-set").description("Build + run trace eval sets");
+  const evalSet = cmd.command("eval-set").description("Build trace eval sets");
   evalSet.command("build <queries-file>").description("Build eval cases from a queries JSON file").option("--out <file>", "write the cases JSON here (default: stdout)").action(async (queriesFile, opts, cmd2) => {
-    const raw = JSON.parse(readFileSync5(queriesFile, "utf8"));
+    const raw = parseBigIntJSON(readFileSync6(queriesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     if (opts.out) {
-      writeFileSync(opts.out, JSON.stringify({ cases }, null, 2));
+      writeFileSync(opts.out, stringifyBigIntJSON({ cases }, 2));
       printJson({ out: opts.out, cases: cases.length }, outputOptions(cmd2));
     } else {
       printJson({ cases }, outputOptions(cmd2));
     }
   });
-  evalSet.command("test <cases-file>").description("Run an eval set against an agent (--llm enables semantic_match)").requiredOption("--agent <id>", "agent id to run the queries against").option("--version <v>", "agent version", "v0").option("--llm", "enable semantic_match assertions via the local `claude` CLI").action(async (casesFile, opts, cmd2) => {
-    const raw = JSON.parse(readFileSync5(casesFile, "utf8"));
-    const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
-    const result = await clientFrom(cmd2).trace.evalSetTest(opts.agent, cases, {
-      version: opts.version,
-      llm: Boolean(opts.llm)
-    });
-    printJson(result, outputOptions(cmd2));
-    if (result.failed > 0) process.exitCode = 1;
-  });
   const schema = cmd.command("schema").description("Validate eval-set / diagnosis-rule files");
   schema.command("validate <file>").description("Validate an eval-set or diagnosis-rule file (JSON/YAML) against its schema").option("--kind <k>", "force schema kind: eval-set | rule (default: auto-detect)").action(async (file, opts, cmd2) => {
     const result = validateSchemaFile(file, opts.kind);
@@ -2722,12 +4039,53 @@ function traceCommand() {
     printJson(result, outputOptions(cmd2));
     if (!result.ok) process.exitCode = 1;
   });
-  return group(cmd, "TRACE AI");
+  groupChildren(cmd, {
+    GROUPS: ["conversations", "interactions", "operations", "receipts", "eval-set", "schema"],
+    READ: ["graph", "get", "search", "detail", "spans"],
+    RUN: ["diagnose", "scan", "validate-fixture"]
+  });
+  guide(
+    cmd,
+    `FINDING A CONVERSATION
+  conversations list gives conversation ids; get <conversation-id> pulls its spans.
+
+DIAGNOSING
+  diagnose <conversation-id>          symbolic rules only, no model needed
+  diagnose <conversation-id> --llm    adds rubric judging + a synthesized summary; needs a
+                                      local \`claude\` CLI on PATH, silently degrades without it
+  scan <id,id,...>                    the same over several conversations, aggregated
+
+MANAGED LIFECYCLE
+  conversations / interactions / operations / receipts are the write side: an agent opens an
+  interaction, reports operations, then completes it. Those bodies are 3.0 manifests,
+  documented at https://openbkn-ai.github.io/bkn-foundry/ (agent-observability).`
+  );
+  return group(cmd, "TRACING");
 }
 
 // src/commands/vega.ts
-import { Command as Command16 } from "commander";
-var int12 = (v) => Number.parseInt(v, 10);
+import { Command as Command15 } from "commander";
+var int10 = (value) => {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new InputError(`expected an integer, received "${value}"`);
+  }
+  return parsed;
+};
+var expectedUpdateTime = (value) => {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new InputError("--expected-update-time must be a positive integer timestamp");
+  }
+  return parsed;
+};
+var confidenceThreshold = (value) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new InputError("--confidence-threshold must be a number between 0 and 1");
+  }
+  return parsed;
+};
 var bool = (value) => {
   if (value === "true") return true;
   if (value === "false") return false;
@@ -2736,7 +4094,7 @@ var bool = (value) => {
 var parseJsonObject = (value, flag) => {
   let parsed;
   try {
-    parsed = JSON.parse(value);
+    parsed = parseBigIntJSON(value);
   } catch {
     throw new InputError(`${flag} must be valid JSON`);
   }
@@ -2745,10 +4103,15 @@ var parseJsonObject = (value, flag) => {
   }
   return parsed;
 };
-var parseStringRecord = (value, flag) => {
-  const parsed = parseJsonObject(value, flag);
-  if (Object.values(parsed).some((item) => typeof item !== "string")) {
-    throw new InputError(`${flag} values must be strings`);
+var parseJsonArray = (value, flag) => {
+  let parsed;
+  try {
+    parsed = parseBigIntJSON(value);
+  } catch {
+    throw new InputError(`${flag} must be valid JSON`);
+  }
+  if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "object" || item === null || Array.isArray(item))) {
+    throw new InputError(`${flag} must be a JSON array of objects`);
   }
   return parsed;
 };
@@ -2771,20 +4134,143 @@ var healthCheckSchedule = (mode, cronExpr) => {
   }
   throw new InputError("health-check mode must be inherit, enabled, or disabled");
 };
-var parsePairs2 = (raw) => {
-  if (!raw) return void 0;
-  return raw.split(",").map((part) => {
-    const idx = part.indexOf("=");
-    if (idx < 1) throw new InputError("--extension must be key=value[,key=value]");
-    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
-  }).filter((p) => p.key.length > 0);
+var buildTaskStatuses = (raw) => {
+  if (raw === void 0) return void 0;
+  const statuses = csv(raw);
+  if (!statuses?.length) {
+    throw new InputError("--status must include at least one build status");
+  }
+  return statuses.map((status2) => {
+    const parsed = BuildTaskStatus.safeParse(status2);
+    if (!parsed.success) {
+      throw new InputError(
+        `invalid build status "${status2}"; expected one of ${BuildTaskStatus.options.join(", ")}`
+      );
+    }
+    return parsed.data;
+  });
+};
+var buildTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = BuildTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid build task sort "${raw}"; expected one of ${BuildTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var buildTaskExecuteType = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = BuildTaskExecuteType.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid build task execute type "${raw}"; expected one of ${BuildTaskExecuteType.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverStrategy = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverStrategy.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover strategy "${raw}"; expected one of ${DiscoverStrategy.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var requiredDiscoverStrategy = (raw) => discoverStrategy(raw);
+var taskStatuses = (raw) => {
+  if (raw === void 0) return void 0;
+  const values = csv(raw);
+  if (!values?.length) throw new InputError("--status must include at least one task status");
+  return values.map((value) => {
+    const parsed = VegaTaskStatus.safeParse(value);
+    if (!parsed.success) {
+      throw new InputError(
+        `invalid task status "${value}"; expected one of ${VegaTaskStatus.options.join(", ")}`
+      );
+    }
+    return parsed.data;
+  });
+};
+var semanticScope = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingScope.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic task scope "${raw}"; expected one of ${SemanticUnderstandingScope.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var semanticApplyMode = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingApplyMode.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic apply mode "${raw}"; expected one of ${SemanticUnderstandingApplyMode.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverScheduleSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverScheduleSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover schedule sort "${raw}"; expected one of ${DiscoverScheduleSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover task sort "${raw}"; expected one of ${DiscoverTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverTaskTriggerType = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverTaskTriggerType.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover task trigger type "${raw}"; expected one of ${DiscoverTaskTriggerType.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var semanticTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic task sort "${raw}"; expected one of ${SemanticUnderstandingTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var sortDirection = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SortDirection.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid sort direction "${raw}"; expected one of ${SortDirection.options.join(", ")}`
+    );
+  }
+  return parsed.data;
 };
 function vegaCommand() {
-  const vega = new Command16("vega").description(
-    "Vega observability \u2014 catalog, resources, index build tasks"
+  const vega = new Command15("vega").description(
+    "Data sources: catalogs, connectors, SQL, index builds"
   );
   const catalog = vega.command("catalog").description("Catalog entries");
-  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", (v) => Number.parseInt(v, 10), 0).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--type <type>", "filter by catalog type: physical | logical").option("--enabled <bool>", "filter by enabled state").option("--health-check-status <s>", "filter by health status").option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (_opts, cmd) => {
+  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--type <type>", "filter by catalog type: physical | logical").option("--connector-type <type>", "filter by connector type").option("--enabled <bool>", "filter by enabled state").option("--health-check-status <s>", "filter by health status").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).vega.catalogs({
       limit: o.limit,
@@ -2792,11 +4278,9 @@ function vegaCommand() {
       name: o.name,
       tag: o.tag,
       type: o.type,
+      connectorType: o.connectorType,
       enabled: o.enabled === void 0 ? void 0 : o.enabled === "true",
       healthCheckStatus: o.healthCheckStatus,
-      includeExtensions: o.includeExtensions,
-      includeExtensionKeys: o.includeExtensionKeys,
-      extensionPairs: parsePairs2(o.extension),
       sort: o.sort,
       direction: o.direction
     });
@@ -2805,7 +4289,7 @@ function vegaCommand() {
   catalog.command("get <id>").description("Get a catalog by id").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.getCatalog(id), outputOptions(cmd));
   });
-  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (backend default 20, max 1000; -1 = all)", int12).option("--offset <n>", "page offset", int12, 0).action(async (id, opts, cmd) => {
+  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (default 30, max 1000; -1 = all)", int10).option("--offset <n>", "page offset", int10, 0).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
       outputOptions(cmd)
@@ -2814,9 +4298,8 @@ function vegaCommand() {
   catalog.command("health <id>").description("Health-status for a catalog").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealth(id), outputOptions(cmd));
   });
-  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
     const connectorConfig = parseJsonObject(opts.connectorConfig, "--connector-config");
-    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
       await clientFrom(cmd).vega.createCatalog(
         {
@@ -2828,7 +4311,6 @@ function vegaCommand() {
           description: opts.description,
           enabled: opts.enabled ? true : void 0,
           internal: opts.internal ? true : void 0,
-          extensions,
           healthCheckSchedule: healthCheckSchedule(opts.healthCheckMode, opts.healthCheckCron)
         },
         { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
@@ -2836,9 +4318,12 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
+  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
     const connectorConfig = opts.connectorConfig ? parseJsonObject(opts.connectorConfig, "--connector-config") : void 0;
-    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
       await clientFrom(cmd).vega.updateCatalog(
         id,
@@ -2849,7 +4334,7 @@ function vegaCommand() {
           tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
           description: opts.description,
           enabled: opts.enabled,
-          extensions
+          expectedUpdateTime: opts.expectedUpdateTime
         },
         { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
       ),
@@ -2862,8 +4347,9 @@ function vegaCommand() {
   catalog.command("disable <id>").description("Disable a catalog").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.disableCatalog(id), outputOptions(cmd));
   });
-  catalog.command("delete <id>").description("Delete a catalog").action(async (id, _opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.deleteCatalog(id), outputOptions(cmd));
+  catalog.command("delete <id>").description("Delete a catalog").option("--dry-run", "preview deletion impact without changing data").action(async (id, opts, cmd) => {
+    const result = opts.dryRun ? await clientFrom(cmd).vega.deleteCatalog(id, { dryRun: true }) : await clientFrom(cmd).vega.deleteCatalog(id);
+    printJson(result, outputOptions(cmd));
   });
   catalog.command("test-connection <id>").description("Test a catalog connection").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.testCatalogConnection(id), outputOptions(cmd));
@@ -2880,17 +4366,183 @@ function vegaCommand() {
   catalog.command("health-check-schedule <id>").description("Get a catalog health-check schedule").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealthCheckSchedule(id), outputOptions(cmd));
   });
-  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").action(async (id, opts, cmd) => {
+  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).action(async (id, opts, cmd) => {
     const schedule = healthCheckSchedule(opts.mode, opts.cron);
     if (!schedule) throw new InputError("--mode is required");
     printJson(
-      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, schedule),
+      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, {
+        ...schedule,
+        expectedUpdateTime: opts.expectedUpdateTime
+      }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverCatalog(id, {
+        strategy: discoverStrategy(opts.strategy)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  const discoverSchedule = vega.command("discover-schedule").description("Resource discovery schedules");
+  discoverSchedule.command("list").description("List discovery schedules").option("--name <s>", "filter by name").option("--catalog-id <id>", "filter by catalog id").option("--enabled <bool>", "filter by enabled state", bool).option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--sort <field>", "name | create_time | update_time | next_run").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverSchedules({
+        name: opts.name,
+        catalogId: opts.catalogId,
+        enabled: opts.enabled,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: discoverScheduleSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  discoverSchedule.command("get <id>").description("Get a discovery schedule").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getDiscoverSchedule(id), outputOptions(cmd));
+  });
+  discoverSchedule.command("create").description("Create a discovery schedule").requiredOption("--name <s>", "schedule name").requiredOption("--catalog-id <id>", "catalog id").requiredOption("--cron <expr>", "five-field cron expression").option("--start-time <ms>", "start time", int10).option("--end-time <ms>", "end time", int10).option("--enabled", "create enabled").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.createDiscoverSchedule({
+        name: opts.name,
+        catalogId: opts.catalogId,
+        cronExpr: opts.cron,
+        startTime: opts.startTime,
+        endTime: opts.endTime,
+        enabled: opts.enabled ? true : void 0,
+        strategy: discoverStrategy(opts.strategy)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  discoverSchedule.command("update <id>").description("Fully update a discovery schedule").requiredOption("--name <s>", "schedule name").requiredOption("--catalog-id <id>", "current catalog id").requiredOption("--cron <expr>", "five-field cron expression").requiredOption("--enabled <bool>", "current enabled state", bool).requiredOption("--start-time <ms>", "start time (0 = no lower bound)", int10).requiredOption("--end-time <ms>", "end time (0 = no upper bound)", int10).requiredOption("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.updateDiscoverSchedule(id, {
+        name: opts.name,
+        catalogId: opts.catalogId,
+        cronExpr: opts.cron,
+        enabled: opts.enabled,
+        startTime: opts.startTime,
+        endTime: opts.endTime,
+        strategy: requiredDiscoverStrategy(opts.strategy),
+        expectedUpdateTime: opts.expectedUpdateTime
+      }),
+      outputOptions(cmd)
+    );
+  });
+  for (const action of ["enable", "disable", "delete"]) {
+    discoverSchedule.command(`${action} <id>`).description(`${action[0]?.toUpperCase()}${action.slice(1)} a discovery schedule`).action(async (id, _opts, cmd) => {
+      const api = clientFrom(cmd).vega;
+      const result = action === "enable" ? await api.enableDiscoverSchedule(id) : action === "disable" ? await api.disableDiscoverSchedule(id) : await api.deleteDiscoverSchedule(id);
+      printJson(result, outputOptions(cmd));
+    });
+  }
+  const discoverTask = vega.command("discover-task").description("Resource discovery tasks");
+  discoverTask.command("list").description("List discovery tasks").option("--catalog-id <id>", "filter by catalog id").option("--resource-id <id>", "filter by resource id").option("--schedule-id <id>", "filter by schedule id").option("--status <status>", `comma-separated: ${VegaTaskStatus.options.join(" | ")}`).option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).option("--trigger-type <type>", "manual | scheduled").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--sort <field>", "create_time | start_time | finish_time | last_progress_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverTasks({
+        catalogId: opts.catalogId,
+        resourceId: opts.resourceId,
+        scheduleId: opts.scheduleId,
+        status: taskStatuses(opts.status),
+        strategy: discoverStrategy(opts.strategy),
+        triggerType: discoverTaskTriggerType(opts.triggerType),
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: discoverTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  discoverTask.command("get <id>").description("Get a discovery task").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getDiscoverTask(id), outputOptions(cmd));
+  });
+  discoverTask.command("delete <ids...>").description("Delete completed discovery tasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.deleteDiscoverTasks(ids, {
+        ignoreMissing: opts.ignoreMissing
+      }),
+      outputOptions(cmd)
+    );
+  });
+  const semanticTask = vega.command("semantic-task").description("Semantic-understanding tasks");
+  semanticTask.command("list").description("List semantic-understanding tasks").option("--scope <scope>", `scope: ${SemanticUnderstandingScope.options.join(" | ")}`).option("--catalog-id <id>", "filter by catalog id").option("--resource-id <id>", "filter by resource id").option("--status <status>", `comma-separated: ${VegaTaskStatus.options.join(" | ")}`).option(
+    "--apply-mode <mode>",
+    `apply mode: ${SemanticUnderstandingApplyMode.options.join(" | ")}`
+  ).option("--applied <bool>", "filter by applied state", bool).option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--sort <field>", "create_time | start_time | finish_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.semanticUnderstandingTasks({
+        scope: semanticScope(opts.scope),
+        catalogId: opts.catalogId,
+        resourceId: opts.resourceId,
+        status: taskStatuses(opts.status),
+        applyMode: semanticApplyMode(opts.applyMode),
+        applied: opts.applied,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: semanticTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  semanticTask.command("create").description("Create a semantic-understanding task").requiredOption("--scope <scope>", "resource | catalog").option("--catalog-id <id>", "catalog id").option("--resource-id <id>", "resource id").option("--apply-mode <mode>", "dry_run | fill_empty | force").option("--confidence-threshold <n>", "minimum confidence (0..1)", confidenceThreshold).option("--include-sample-rows", "include resource sample rows").option("--sample-max-rows <n>", "sample row limit", int10).action(async (opts, cmd) => {
+    const scope = semanticScope(opts.scope);
+    if (!scope) throw new InputError("--scope is required");
+    const applyMode = semanticApplyMode(opts.applyMode);
+    if (scope === "catalog" && !opts.catalogId) {
+      throw new InputError("--catalog-id is required for catalog scope");
+    }
+    if (scope === "resource" && !opts.resourceId) {
+      throw new InputError("--resource-id is required for resource scope");
+    }
+    if (scope === "catalog" && (opts.includeSampleRows || opts.sampleMaxRows !== void 0)) {
+      throw new InputError("sample row options are only valid for resource scope");
+    }
+    if (scope === "resource" && opts.includeSampleRows && opts.sampleMaxRows === void 0) {
+      throw new InputError("--sample-max-rows is required with --include-sample-rows");
+    }
+    if (scope === "resource" && !opts.includeSampleRows && opts.sampleMaxRows !== void 0) {
+      throw new InputError("--sample-max-rows requires --include-sample-rows");
+    }
+    if (opts.sampleMaxRows !== void 0 && (opts.sampleMaxRows < 1 || opts.sampleMaxRows > 20)) {
+      throw new InputError("--sample-max-rows must be between 1 and 20");
+    }
+    const common = {
+      applyMode,
+      confidenceThreshold: opts.confidenceThreshold
+    };
+    const request = scope === "catalog" ? { scope: "catalog", catalogId: opts.catalogId, ...common } : {
+      scope: "resource",
+      resourceId: opts.resourceId,
+      includeSampleRows: opts.includeSampleRows ? true : void 0,
+      samplePolicy: opts.sampleMaxRows === void 0 ? void 0 : { masked: false, maxRows: opts.sampleMaxRows },
+      ...common
+    };
+    printJson(
+      await clientFrom(cmd).vega.createSemanticUnderstandingTask(request),
       outputOptions(cmd)
     );
   });
-  catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--wait", "wait for discovery to complete").action(async (id, opts, cmd) => {
+  semanticTask.command("get <id>").description("Get a semantic-understanding task").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getSemanticUnderstandingTask(id), outputOptions(cmd));
+  });
+  semanticTask.command("delete <ids...>").description("Delete completed semantic-understanding tasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).vega.discoverCatalog(id, Boolean(opts.wait)),
+      await clientFrom(cmd).vega.deleteSemanticUnderstandingTasks(ids, {
+        ignoreMissing: opts.ignoreMissing
+      }),
       outputOptions(cmd)
     );
   });
@@ -2901,17 +4553,19 @@ function vegaCommand() {
   connector.command("get <type>").description("Get a connector type").action(async (type, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.connectorType(type), outputOptions(cmd));
   });
-  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").option(
+  vega.command("sql").description(
+    "Read-only SQL straight against a data source \u2014 no knowledge network, no Trace record"
+  ).option(
     "--query <sql>",
     "SQL string; reference a resource with a {{<resource-id>}} placeholder"
-  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int12).option("--offset <n>", "first-page offset", int12).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int12).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int12).option(
+  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int10).option("--offset <n>", "first-page offset", int10).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int10).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int10).option(
     "-d, --data <json>",
     "full request body as JSON (advanced; wins over individual query flags)"
   ).action(async (opts, cmd) => {
     let body;
     if (opts.data) {
       try {
-        body = JSON.parse(opts.data);
+        body = parseBigIntJSON(opts.data);
       } catch {
         throw new InputError("--data must be valid JSON");
       }
@@ -2948,18 +4602,15 @@ function vegaCommand() {
     printJson(await clientFrom(cmd).vega.sql(body), outputOptions(cmd));
   });
   const resource = vega.command("resource").description("Vega-backend resources");
-  resource.command("list").description("List resources").option("--datasource-id <id>", "filter by catalog/datasource id").option("--catalog-id <id>", "alias of --datasource-id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd) => {
+  resource.command("list").description("List resources").option("--catalog-id <id>", "filter by catalog id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--status <status>", "filter by status").option("--schema <name>", "filter by source schema").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).resource.list({
-        datasourceId: opts.datasourceId ?? opts.catalogId,
+        catalogId: opts.catalogId,
         category: opts.type ?? opts.category,
         status: opts.status,
-        database: opts.database,
+        schema: opts.schema,
         limit: opts.limit,
         offset: opts.offset,
-        includeExtensions: opts.includeExtensions,
-        includeExtensionKeys: opts.includeExtensionKeys,
-        extensionPairs: parsePairs2(opts.extension),
         sort: opts.sort,
         direction: opts.direction
       }),
@@ -2969,17 +4620,75 @@ function vegaCommand() {
   resource.command("get <id>").description("Get a resource").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).resource.get(id), outputOptions(cmd));
   });
-  resource.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", (v) => Number.parseInt(v, 10), 50).option("--offset <n>", "row offset", (v) => Number.parseInt(v, 10), 0).action(async (id, opts, cmd) => {
+  resource.command("discover <id>").description("Trigger metadata discovery for a resource").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.discoverResource(id), outputOptions(cmd));
+  });
+  for (const action of ["enable", "disable"]) {
+    resource.command(`${action} <id>`).description(`${action[0]?.toUpperCase()}${action.slice(1)} a resource`).action(async (id, _opts, cmd) => {
+      const api = clientFrom(cmd).resource;
+      const result = action === "enable" ? await api.enable(id) : await api.disable(id);
+      printJson(result, outputOptions(cmd));
+    });
+  }
+  resource.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int10, 50).option("--offset <n>", "row offset", int10, 0).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).resource.query(id, { limit: opts.limit, offset: opts.offset }),
       outputOptions(cmd)
     );
   });
+  resource.command("document-get <resource-id> <document-id>").description("Get one dataset document").action(async (resourceId, documentId, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.getDocument(resourceId, documentId),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-create <resource-id>").description("Create dataset documents").requiredOption(
+    "--data <json>",
+    "JSON array of documents \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (vega-backend)"
+  ).action(async (resourceId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.createDocuments(
+        resourceId,
+        parseJsonArray(opts.data, "--data")
+      ),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-upsert <resource-id>").description("Upsert dataset documents; every document must have an id").requiredOption(
+    "--data <json>",
+    "JSON array of documents \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (vega-backend)"
+  ).action(async (resourceId, opts, cmd) => {
+    const documents = parseJsonArray(opts.data, "--data");
+    if (documents.some((document) => typeof document.id !== "string")) {
+      throw new InputError("every document in --data must have a string id");
+    }
+    printJson(
+      await clientFrom(cmd).resource.upsertDocuments(resourceId, documents),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-delete <resource-id> <document-ids...>").description("Delete dataset documents by id").action(async (resourceId, documentIds, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.deleteDocuments(resourceId, documentIds),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-delete-filter <resource-id>").description("Delete dataset documents by a non-empty filter").requiredOption("--filter <json>", "filter_condition JSON object").action(async (resourceId, opts, cmd) => {
+    const filter = parseJsonObject(opts.filter, "--filter");
+    if (!Object.keys(filter).length) throw new InputError("--filter must not be empty");
+    printJson(
+      await clientFrom(cmd).resource.deleteDocumentsByFilter(resourceId, filter),
+      outputOptions(cmd)
+    );
+  });
   const dataset = vega.command("dataset").description("Dataset index build tasks");
   dataset.command("build <resource-id>").description("Build a resource's index (creates a BuildTask)").requiredOption("--mode <mode>", "build mode: batch | streaming").option("--embedding-fields <list>", "comma-separated fields to vectorize").option(
     "--build-key-fields <list>",
     "comma-separated key fields (batch: time; streaming: row id)"
-  ).option("--embedding-model <id>", "default embedding model name/id").option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
+  ).option(
+    "--embedding-model <name-or-id>",
+    "default small-model name (a numeric ID is resolved to its name)"
+  ).option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const embeddingFields = csv(o.embeddingFields);
     const buildKeyFields = csv(o.buildKeyFields);
@@ -3007,28 +4716,26 @@ function vegaCommand() {
     const task = await clientFrom(cmd).vega.buildStatus(taskId);
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "created_at | updated_at").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
-    if (opts.orderBy === "default") {
-      throw new InputError(
-        '--order-by default is no longer supported; use "created_at" or "updated_at"'
-      );
-    }
+  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", `comma-separated statuses: ${BuildTaskStatus.options.join(" | ")}`).option("--mode <mode>", "filter by mode: batch | streaming").option(
+    "--execute-type <type>",
+    `filter by execution type: ${BuildTaskExecuteType.options.join(" | ")}`
+  ).option("--sort <field>", `sort field: ${BuildTaskSort.options.join(" | ")}`).option("--direction <dir>", `sort direction: ${SortDirection.options.join(" | ")}`).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.buildTasks({
         limit: opts.limit,
         offset: opts.offset,
         resourceId: opts.resourceId,
         catalogId: opts.catalogId,
-        status: opts.status,
-        active: opts.active,
+        status: buildTaskStatuses(opts.status),
         mode: opts.mode,
-        orderBy: opts.orderBy,
-        order: opts.order
+        executeType: buildTaskExecuteType(opts.executeType),
+        sort: buildTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
       }),
       outputOptions(cmd)
     );
   });
-  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (ignored for incremental tasks)").action(async (taskId, opts, cmd) => {
+  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (rejected for incremental tasks)").action(async (taskId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.startBuildTask(taskId, { reset: opts.reset }),
       outputOptions(cmd)
@@ -3037,43 +4744,142 @@ function vegaCommand() {
   dataset.command("build-stop <task-id>").description("Stop a BuildTask").action(async (taskId, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.stopBuildTask(taskId), outputOptions(cmd));
   });
-  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").option("--delete-active-index", "delete active indexes too").action(async (ids, opts, cmd) => {
+  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.deleteBuildTasks(ids, {
-        ignoreMissing: opts.ignoreMissing,
-        deleteActiveIndex: opts.deleteActiveIndex
+        ignoreMissing: opts.ignoreMissing
       }),
       outputOptions(cmd)
     );
   });
-  return group(vega, "AI DATA PLATFORM");
+  groupChildren(vega, {
+    GROUPS: [
+      "catalog",
+      "resource",
+      "connector-type",
+      "dataset",
+      "discover-schedule",
+      "discover-task",
+      "semantic-task"
+    ],
+    RUN: ["sql"]
+  });
+  groupChildren(resource, {
+    READ: ["list", "get", "document-get"],
+    RUN: ["query", "discover"],
+    WRITE: [
+      "enable",
+      "disable",
+      "document-create",
+      "document-upsert",
+      "document-delete",
+      "document-delete-filter"
+    ]
+  });
+  groupChildren(catalog, {
+    READ: ["list", "get", "resources", "health", "health-check-schedule"],
+    RUN: ["test-connection", "test-connection-config", "discover"],
+    WRITE: ["create", "update", "enable", "disable", "delete", "set-health-check-schedule"]
+  });
+  guide(
+    vega,
+    `FINDING DATA
+  catalog list -> catalog resources <catalog-id> -> resource get <id>. A physical catalog
+  can be discovered and written; a logical one cannot.
+
+QUERYING DIRECTLY
+  sql --query "<sql>" runs against the source itself. Name a resource with a
+  {{<resource-id>}} placeholder rather than the physical table it happens to have.
+
+BUILDING AN INDEX
+  dataset build <resource-id> creates a BuildTask; build-status / build-list follow it.
+  Indexes are per resource \u2014 a knowledge network has no build of its own.`
+  );
+  return group(vega, "DATA & KNOWLEDGE");
+}
+
+// src/cli-program.ts
+function buildProgram() {
+  const program2 = new Command16();
+  program2.name("openbkn").description(
+    "openbkn \u2014 one CLI for the BKN platform: knowledge networks, the data behind them,\nthe tools and skills agents run on them, and the traces they leave."
+  ).version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option(
+    "--new-conversation",
+    "ignore the remembered conversation for this command (see `openbkn context conversation`)"
+  ).option("-k, --insecure", "skip TLS verification (dev / self-signed only)").option("--dry-run", "print the request this command would send, and send nothing").showHelpAfterError();
+  program2.addCommand(authCommand());
+  program2.addCommand(configCommand());
+  program2.addCommand(appkeyCommand());
+  program2.addCommand(bknCommand());
+  program2.addCommand(vegaCommand());
+  program2.addCommand(resourceCommand());
+  program2.addCommand(contextCommand());
+  program2.addCommand(modelCommand());
+  program2.addCommand(skillCommand());
+  program2.addCommand(toolboxCommand());
+  program2.addCommand(toolCommand());
+  program2.addCommand(functionCommand());
+  program2.addCommand(traceCommand());
+  program2.addCommand(adminCommand());
+  program2.addCommand(callCommand());
+  program2.addCommand(describeCommand(program2));
+  guide(
+    program2,
+    `FIRST STEPS
+    openbkn auth login https://your-platform -u <user> -p <pass>
+    openbkn bkn list                       # knowledge networks you can see
+    openbkn bkn --help                     # every group has its own help
+    openbkn describe --depth 1             # the whole map as one table; \`describe <command>\`
+                                           # drills in, --json ships the same tree as data
+
+  COMMON TASKS
+    Answer a question    bkn search <kn-id> "<q>"  ->  context search-schema  ->
+                         context query-object-instance --args '<json>'
+    Look at the data     vega catalog list  ->  resource find --name <t>  ->  resource query <id>
+    Build from a catalog bkn create-from-catalog <catalog-id> --name "<n>"  ->
+                         vega dataset build <resource-id>
+    Edit as files        bkn pull <kn-id> ./kn  ->  bkn validate ./kn  ->  bkn push ./kn
+    Ship a capability    skill register ./my-skill; toolbox create --name "<n>"  ->
+                         tool upload ./api.yaml --toolbox <id>  ->  toolbox publish <id>
+    Ship some code       function run ./add.py  ->  toolbox create --name "<n>" --type function
+                         ->  tool create ./add.py --toolbox <box-id> --name add  ->
+                         tool enable <tool-id> --toolbox <box-id>
+    Debug an answer      trace conversations list  ->  trace diagnose <conversation-id> --llm
+
+  GOOD TO KNOW
+    Every command group sorts its subcommands into the same four sections: GROUPS nests one
+    level deeper, READ changes nothing, RUN acts without changing configuration (triggers a
+    job, spends a model call, rotates a token), WRITE changes platform state \u2014 confirm those
+    with a person first.
+    Add --json to any command for machine-readable output (the default view trims columns,
+    --full widens it). Most list commands answer {entries, total_count}; anything else says
+    so in its own description. Ids come from list/search output \u2014 opaque, never guess one,
+    and the key holding one is not always \`id\` (\`skill_id\`, \`conversation_id\`, \`ot_id\` \u2026).
+    Multi-tenant deploys: --biz-domain picks the domain, --user switches saved logins.
+    \`openbkn call\` reaches any endpoint a command does not cover, auth injected. Look the
+    path up at https://openbkn-ai.github.io/bkn-foundry/ first \u2014 do not guess one.`
+  );
+  installGroupedHelp(program2);
+  return program2;
 }
 
 // src/cli.ts
-var program = new Command17();
-program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
-program.addCommand(authCommand());
-program.addCommand(callCommand());
-program.addCommand(configCommand());
-program.addCommand(appkeyCommand());
-program.addCommand(vegaCommand());
-program.addCommand(bknCommand());
-program.addCommand(resourceCommand());
-program.addCommand(dataflowCommand());
-program.addCommand(contextCommand());
-program.addCommand(agentCommand());
-program.addCommand(modelCommand());
-program.addCommand(skillCommand());
-program.addCommand(toolboxCommand());
-program.addCommand(toolCommand());
-program.addCommand(traceCommand());
-program.addCommand(adminCommand());
-program.addCommand(exploreCommand());
-installGroupedHelp(program);
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") process.exit(0);
+  throw err;
+});
+var program = buildProgram();
 var argv = process.argv.map((a) => a === "-bd" ? "--biz-domain" : a);
+if (argv.includes("--dry-run")) enableDryRun();
 try {
   await program.parseAsync(argv);
 } catch (err) {
+  if (err instanceof DryRunSignal) {
+    process.stdout.write(`${JSON.stringify(err.request, null, 2)}
+`);
+    await releaseLifecycleSessions();
+    process.exit(0);
+  }
   console.error(formatError(err));
   await releaseLifecycleSessions();
   process.exit(toExitCode(err));