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

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  BuildTaskExecuteType,
   BuildTaskSort,
   BuildTaskStatus,
   DEFAULT_BUSINESS_DOMAIN,
@@ -9,6 +10,7 @@ import {
   DiscoverStrategy,
   DiscoverTaskSort,
   DiscoverTaskTriggerType,
+  DryRunSignal,
   HttpError,
   InputError,
   SemanticUnderstandingApplyMode,
@@ -27,6 +29,7 @@ import {
   decodeJwt,
   deletePlatform,
   deviceLogin,
+  enableDryRun,
   exportCreds,
   filesUnder,
   formatError,
@@ -50,24 +53,25 @@ import {
   stringifyBigIntJSON,
   switchUser,
   toExitCode,
+  trimTrailingSlashes,
   updatePlatformConfig,
   use,
   validateFixturePath,
   whoami
-} from "./chunk-Z2NRTUB3.js";
+} from "./chunk-WIYRGBAB.js";
 
-// src/cli.ts
+// src/cli-program.ts
 import { Command as Command16 } from "commander";
 
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.4",
+  version: "0.1.5-rc.1",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
   engines: {
-    node: ">=24.19.0"
+    node: ">=22.19.0"
   },
   bin: {
     openbkn: "./dist/cli.js"
@@ -94,6 +98,7 @@ 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",
@@ -131,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);
@@ -154,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)}`);
@@ -162,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));
@@ -174,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
@@ -206,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
@@ -257,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;
@@ -280,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;
   });
@@ -297,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] ?? "")))
   );
@@ -331,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;
@@ -342,7 +412,7 @@ function promptLine(query, hidden = false) {
     rl.question(query, (answer) => {
       rl.close();
       if (hidden) process.stdout.write("\n");
-      resolve2(answer.trim());
+      resolve3(answer.trim());
     });
   });
 }
@@ -351,7 +421,7 @@ function promptLine(query, hidden = false) {
 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?.replace(/\/+$/, "");
+  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);
@@ -576,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
 `
     );
@@ -613,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);
@@ -657,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
@@ -672,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,
@@ -736,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,
@@ -822,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)
@@ -924,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 {
@@ -933,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 {
@@ -948,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 }),
@@ -997,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) => {
@@ -1030,125 +1135,16 @@ function adminCommand() {
     }
     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));
+  groupChildren(admin, {
+    GROUPS: ["org", "user", "role", "llm", "small-model", "license", "audit", "auth", "config"],
+    RUN: ["call"]
   });
-  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)
-    );
-  });
-  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) {
@@ -1170,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) {
@@ -1210,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";
@@ -1332,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,
@@ -1354,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));
   });
@@ -1375,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)
@@ -1396,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));
   });
@@ -1421,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)
@@ -1430,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,
@@ -1460,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)
@@ -1487,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");
@@ -1500,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)
@@ -1515,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)
@@ -1534,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)
@@ -1574,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)
@@ -1610,17 +1673,73 @@ function bknCommand() {
     printJson(result, outputOptions(cmd));
     if (!result.valid) process.exitCode = 1;
   });
-  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,
@@ -1657,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(
@@ -1681,7 +1812,7 @@ 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") {
       updatePlatformConfig(requireActive(), { businessDomain: value });
     } else {
@@ -1697,12 +1828,13 @@ function configCommand() {
   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;
@@ -1740,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 = parseBigIntJSON(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)
@@ -1815,15 +1958,106 @@ function contextCommand() {
   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)
@@ -1831,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,
@@ -1854,7 +2088,10 @@ 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 {
@@ -1865,124 +2102,978 @@ function contextCommand() {
     }
     printJson(await clientFrom(cmd2).context.prompt(knId, name, args), outputOptions(cmd2));
   });
-  const jsonArgs = (raw) => {
-    try {
-      return parseBigIntJSON(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
+
+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.
+
+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.`
+  );
+  return group(cmd, "DATA & KNOWLEDGE");
 }
 
-// src/commands/explore.ts
-import { createServer } from "http";
-import { Command as Command9 } from "commander";
-var int6 = (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 ?? {})
+// 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"]
+  }
 };
-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(parseBigIntJSON(data));
-      } catch {
-        reject(new Error("invalid JSON body"));
-      }
-    });
-    reqMsg.on("error", reject);
-  });
+
+// 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"
+      };
+    }
+  }
+  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 };
+}
+function firstLine(message) {
+  return (message.split("\n")[0] ?? message).slice(0, 160);
+}
+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"}` };
 }
-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 Command9("explore").description(
-    "Start a local web server with read-only bkn + vega JSON endpoints"
+
+// 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"
   );
-  cmd.option("--port <n>", "port to listen on", int6, 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 {
+    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)
+  };
 }
-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;
+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 handler = ROUTES[`${method} ${url.pathname}`];
-  if (!handler) {
-    res.writeHead(404, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "not found" }));
-    return;
+  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 {
-    const body = method === "GET" ? {} : await readBody2(reqMsg);
-    const data = await handler(client, url.searchParams, body);
-    res.writeHead(200, { "content-type": "application/json" });
-    res.end(stringifyBigIntJSON(data ?? null));
+    return readFileSync4(file === "-" ? 0 : file, "utf8");
   } catch (err) {
-    res.writeHead(500, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(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 int7 = (v) => Number.parseInt(v, 10);
+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);
@@ -1990,25 +3081,34 @@ async function resolveLlmModelName(client, 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").option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
+  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 Command10("model").description(
-    "Model factory \u2014 LLM / small-model CRUD, chat / embeddings / rerank, default selection"
+    "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", int7, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int7, 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,
@@ -2041,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", int7, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int7, 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,
@@ -2092,15 +3192,22 @@ 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 Command11 } from "commander";
-var int8 = (v) => Number.parseInt(v, 10);
+var int7 = (v) => Number.parseInt(v, 10);
 function resourceCommand() {
-  const cmd = new Command11("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("--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", int8, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int8, 0).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({
       catalogId: opts.catalogId,
       category: opts.category ?? opts.type,
@@ -2113,7 +3220,7 @@ function resourceCommand() {
     });
     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("--limit <n>", "rows to scan before filtering", int8, 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,
       catalogId: opts.catalogId,
@@ -2124,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", int8, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int8, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int8).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,
@@ -2138,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 Command12 } from "commander";
-var int9 = (v) => Number.parseInt(v, 10);
+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}')`);
@@ -2168,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 Command12("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", int9, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int9, 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,
@@ -2186,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));
   });
@@ -2325,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)
@@ -2343,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 Command13 } from "commander";
-var int10 = (v) => Number.parseInt(v, 10);
+import yaml from "js-yaml";
+var int9 = (v) => Number.parseInt(v, 10);
 function toolboxCommand() {
-  const cmd = new Command13("toolbox").description("Agent toolbox lifecycle");
-  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 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,
@@ -2361,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)
     );
@@ -2389,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 Command13("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)", int10).option("--page <n>", "page (1-based; backend default 1)", int10).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,
@@ -2415,7 +3615,10 @@ 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", int10);
+  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 {
@@ -2431,39 +3634,101 @@ function toolCommand() {
     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("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("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("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 { 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([
@@ -2498,9 +3763,9 @@ 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);
+  if (ext === ".yaml" || ext === ".yml") return yaml2.load(text);
   return parseBigIntJSON(text);
 }
 function inferKind(data) {
@@ -2572,7 +3837,7 @@ function renderTechnicalTraceDetail(detail) {
 }
 function traceCommand() {
   const cmd = new Command14("trace").description(
-    "BKN Trace \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
+    "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));
@@ -2653,7 +3918,10 @@ function traceCommand() {
     );
   });
   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 = {
@@ -2682,7 +3950,10 @@ 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("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,
@@ -2713,7 +3984,7 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("search").description("List authorized technical traces").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) => {
+  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,
@@ -2746,9 +4017,9 @@ 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 = parseBigIntJSON(readFileSync5(queriesFile, "utf8"));
+    const raw = parseBigIntJSON(readFileSync6(queriesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     if (opts.out) {
       writeFileSync(opts.out, stringifyBigIntJSON({ cases }, 2));
@@ -2757,16 +4028,6 @@ function traceCommand() {
       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 = parseBigIntJSON(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);
@@ -2778,12 +4039,33 @@ 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 Command15 } from "commander";
-var int11 = (value) => {
+var int10 = (value) => {
   const parsed = Number(value);
   if (!Number.isSafeInteger(parsed)) {
     throw new InputError(`expected an integer, received "${value}"`);
@@ -2878,6 +4160,16 @@ var buildTaskSort = (raw) => {
   }
   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);
@@ -2975,10 +4267,10 @@ var sortDirection = (raw) => {
 };
 function vegaCommand() {
   const vega = new Command15("vega").description(
-    "Vega observability \u2014 catalog, resources, index build tasks"
+    "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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 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) => {
+  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,
@@ -2997,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 (default 30, max 1000; -1 = all)", int11).option("--offset <n>", "page offset", int11, 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)
@@ -3098,7 +4390,7 @@ function vegaCommand() {
     );
   });
   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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "name | create_time | update_time | next_run").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+  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,
@@ -3115,7 +4407,7 @@ function vegaCommand() {
   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", int11).option("--end-time <ms>", "end time", int11).option("--enabled", "create enabled").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (opts, 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,
@@ -3129,7 +4421,7 @@ function vegaCommand() {
       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)", int11).requiredOption("--end-time <ms>", "end time (0 = no upper bound)", int11).requiredOption("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).requiredOption(
+  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
@@ -3156,10 +4448,11 @@ function vegaCommand() {
     });
   }
   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("--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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "create_time | start_time | finish_time | last_progress_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+  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),
@@ -3187,7 +4480,7 @@ function vegaCommand() {
   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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "create_time | start_time | finish_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+  ).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),
@@ -3204,7 +4497,7 @@ function vegaCommand() {
       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", int11).action(async (opts, 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);
@@ -3260,10 +4553,12 @@ 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)", int11).option("--offset <n>", "first-page offset", int11).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int11).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)", int11).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) => {
@@ -3307,7 +4602,7 @@ 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("--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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).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({
         catalogId: opts.catalogId,
@@ -3325,7 +4620,17 @@ 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", int11, 50).option("--offset <n>", "row offset", int11, 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)
@@ -3337,7 +4642,10 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  resource.command("document-create <resource-id>").description("Create dataset documents").requiredOption("--data <json>", "JSON array of documents").action(async (resourceId, opts, 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,
@@ -3346,7 +4654,10 @@ function vegaCommand() {
       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").action(async (resourceId, opts, 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");
@@ -3405,7 +4716,10 @@ 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", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 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("--sort <field>", `sort field: ${BuildTaskSort.options.join(" | ")}`).option("--direction <dir>", `sort direction: ${SortDirection.options.join(" | ")}`).action(async (opts, cmd) => {
+  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,
@@ -3414,6 +4728,7 @@ function vegaCommand() {
         catalogId: opts.catalogId,
         status: buildTaskStatuses(opts.status),
         mode: opts.mode,
+        executeType: buildTaskExecuteType(opts.executeType),
         sort: buildTaskSort(opts.sort),
         direction: sortDirection(opts.direction)
       }),
@@ -3437,36 +4752,134 @@ function vegaCommand() {
       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 Command16();
-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(
-  "--new-conversation",
-  "ignore the remembered conversation for this command (see `openbkn context conversation`)"
-).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(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));