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

package/dist/cli.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import {
+  AUDIT_LOG_MAX_LIMIT,
+  BuildMode,
   BuildTaskExecuteType,
   BuildTaskSort,
   BuildTaskStatus,
-  DEFAULT_BUSINESS_DOMAIN,
+  CatalogHealthCheckStatus,
+  ConnectorCategory,
+  ConnectorMode,
   DEFAULT_LIST_LIMIT,
   DEFAULT_QUERY_LIMIT,
   DiscoverScheduleSort,
@@ -11,17 +15,28 @@ import {
   DiscoverTaskSort,
   DiscoverTaskTriggerType,
   DryRunSignal,
+  FUNCTION_TEMPLATE_TYPES,
+  FunctionAiGenerationType,
   HttpError,
+  IMPEX_TYPES,
   InputError,
+  ResourceCategory,
+  ResourceStatus,
+  SKILL_SOURCES,
+  SKILL_STATUSES,
   SemanticUnderstandingApplyMode,
   SemanticUnderstandingScope,
   SemanticUnderstandingTaskSort,
   SortDirection,
+  TOOL_METADATA_TYPES,
   VegaTaskStatus,
+  WaitTimeoutError,
   activePlatform,
   attachToken,
+  buildTaskState,
   changePasswordSafe,
   classifyPath,
+  configureVersionCheck,
   createClient,
   credentialDeviceLogin,
   currentToken,
@@ -30,17 +45,19 @@ import {
   deletePlatform,
   deviceLogin,
   enableDryRun,
+  ensureCompatible,
   exportCreds,
   filesUnder,
   formatError,
-  getUserSafe,
+  getMeSafe,
+  isBuildTaskUnsuccessful,
   isHeadless,
   lifecycleHint,
   listPlatforms,
   logout,
   openBrowser,
+  package_default,
   parseBigIntJSON,
-  parseEmbeddingFields,
   parsePkMap,
   rawCall,
   readPlatformConfig,
@@ -48,6 +65,8 @@ import {
   renderReportMarkdown,
   renderTree,
   resolveContext,
+  scopeFromKinds,
+  sessionInsecure,
   setActivePlatform,
   status,
   stringifyBigIntJSON,
@@ -56,83 +75,17 @@ import {
   trimTrailingSlashes,
   updatePlatformConfig,
   use,
+  validateBknDirectory,
   validateFixturePath,
   whoami
-} from "./chunk-WIYRGBAB.js";
+} from "./chunk-ORVEVDGJ.js";
 
 // src/cli-program.ts
-import { Command as Command16 } from "commander";
-
-// package.json
-var package_default = {
-  name: "@openbkn/bkn-sdk",
-  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: ">=22.19.0"
-  },
-  bin: {
-    openbkn: "./dist/cli.js"
-  },
-  main: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.js"
-    }
-  },
-  files: ["dist", "!dist/**/*.map", "README.md", "README.zh.md", "LICENSE", "NOTICE"],
-  publishConfig: {
-    access: "public"
-  },
-  repository: {
-    type: "git",
-    url: "git+https://github.com/openbkn-ai/bkn-sdk.git"
-  },
-  keywords: ["bkn", "openbkn", "knowledge-network", "cli", "sdk", "typescript"],
-  scripts: {
-    build: "tsup",
-    dev: "tsup --watch",
-    typecheck: "tsc --noEmit",
-    "check:deps": "node scripts/check-no-self-dep.mjs",
-    "capture:returns": "node scripts/capture-returns.mjs",
-    lint: "npm run check:deps && biome check . && tsc --noEmit",
-    format: "biome format --write .",
-    test: "vitest run",
-    "test:e2e:trace-business": "npm run build && node test/e2e/bkn-trace-business-interaction.mjs",
-    "test:e2e:smoke": "npm run build && test/e2e/live-smoke.sh",
-    "test:e2e:suite": "npm run build && test/e2e/live-suite.sh",
-    "test:e2e:write": "npm run build && test/e2e/live-write.sh",
-    "test:cover": "vitest run --coverage",
-    ci: "npm run lint && npm test",
-    prepublishOnly: "npm run ci && npm run build"
-  },
-  dependencies: {
-    "@clack/prompts": "^0.9.1",
-    chalk: "^5.4.1",
-    commander: "^13.1.0",
-    "csv-parse": "^6.2.1",
-    "js-yaml": "^4.3.0",
-    jszip: "^3.10.1",
-    undici: "^8.9.0",
-    zod: "^3.24.1"
-  },
-  devDependencies: {
-    "@biomejs/biome": "^1.9.4",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.0.0",
-    tsup: "^8.4.0",
-    typescript: "^5.8.0",
-    vitest: "^3.0.0"
-  }
-};
+import { Command as Command17 } from "commander";
 
 // src/commands/admin.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { Command as Command2 } from "commander";
+import { Command as Command2, Option } from "commander";
 
 // src/help/grouped-help.ts
 var GROUP = /* @__PURE__ */ Symbol("openbkn.group");
@@ -161,11 +114,11 @@ var VERB_SECTIONS = [
     "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)$/,
+    /^(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|stop|resume|ensure-current|create-new-generation|close|complete|fail|cancel|handoff|operations)$/,
     "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)$/,
+    /^(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|publish-history|update-metadata|update-package|create-from-catalog|export-config)$/,
     "WRITE"
   ]
 ];
@@ -314,7 +267,8 @@ var ROW_ENVELOPES = [
   "roles",
   "departments",
   "members",
-  "keys"
+  "keys",
+  "logs"
 ];
 function toRows(value) {
   const isRowArray = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => x !== null && typeof x === "object" && !Array.isArray(x));
@@ -401,7 +355,7 @@ function stringifyCell(v) {
 // src/utils/prompt.ts
 import { createInterface } from "readline";
 function promptLine(query, hidden = false) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve2) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     if (hidden) {
       const mutable = rl;
@@ -412,7 +366,7 @@ function promptLine(query, hidden = false) {
     rl.question(query, (answer) => {
       rl.close();
       if (hidden) process.stdout.write("\n");
-      resolve3(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -446,6 +400,17 @@ function traceOptionsFrom(o) {
     ...interactionId ? { interactionId } : {}
   };
 }
+function retryOptionsFrom(o) {
+  return {
+    retry: o.retry !== false,
+    onRetry: (n) => {
+      process.stderr.write(
+        `openbkn: ${n.method} ${new URL(n.url).pathname} failed (${n.reason}); retry ${n.attempt}/${n.retries} in ${n.delayMs / 1e3}s
+`
+      );
+    }
+  };
+}
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
   const trace = traceOptionsFrom(o);
@@ -455,8 +420,9 @@ function clientFrom(cmd) {
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
-    businessDomain: o.bizDomain,
     insecure: o.insecure,
+    versionCheckMode: "cli",
+    ...retryOptionsFrom(o),
     ...trace ? { trace } : {},
     ...remembered.source === "stored" && remembered.id ? { rememberedConversationId: remembered.id } : {},
     // Remember a conversation this run opens, so the next command continues the
@@ -484,10 +450,67 @@ function outputOptions(cmd) {
   const o = cmd.optsWithGlobals();
   return { json: Boolean(o.json), compact: Boolean(o.compact), full: Boolean(o.full) };
 }
+var positiveInt = (flag, max) => (v) => {
+  const bound = max === void 0 ? "a positive integer" : `an integer from 1 to ${max}`;
+  if (!/^\d+$/.test(v)) throw new InputError(`${flag} must be ${bound} (got '${v}')`);
+  const n = Number.parseInt(v, 10);
+  if (!Number.isSafeInteger(n) || n <= 0 || max !== void 0 && n > max) {
+    throw new InputError(`${flag} must be ${bound} (got '${v}')`);
+  }
+  return n;
+};
+var MAX_PAGE_SIZE = 100;
+var oneOf = (flag, values) => (v) => {
+  if (values.includes(v)) return v;
+  throw new InputError(`${flag} must be one of: ${values.join(" | ")} (got '${v}')`);
+};
 function csv(value) {
   if (!value) return void 0;
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
+function readJsonArgs(opts, required = false) {
+  if (opts.args !== void 0 && opts.argsFile !== void 0) {
+    throw new InputError("--args and --args-file cannot be combined");
+  }
+  const file = opts.argsFile ?? (opts.args === "-" ? "-" : void 0);
+  let raw = opts.args;
+  if (file !== void 0) {
+    try {
+      raw = readFileSync(file === "-" ? 0 : file, "utf8");
+    } catch (error) {
+      throw new InputError(
+        `Cannot read ${file === "-" ? "stdin" : `--args-file '${file}'`}: ${error instanceof Error ? error.message : error}`
+      );
+    }
+  }
+  if (raw === void 0) {
+    if (required) throw new InputError("--args is required (run with --schema to see its shape)");
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = parseBigIntJSON(raw);
+  } catch {
+    throw new InputError("--args must be valid JSON");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InputError("--args must be a JSON object");
+  }
+  return parsed;
+}
+function cypherParams(raw) {
+  if (raw === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = parseBigIntJSON(raw);
+  } catch {
+    throw new InputError("--params is not valid JSON.");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InputError(`--params must be a JSON object, as in '{"floor": 100}'.`);
+  }
+  return parsed;
+}
 function readBody(opts) {
   const raw = opts.bodyFile ? readFileSync(opts.bodyFile, "utf8") : opts.body;
   if (!raw) throw new InputError("Provide --body '<json>' or --body-file <path>.");
@@ -500,19 +523,50 @@ function readBody(opts) {
 
 // src/commands/auth.ts
 import { Command } from "commander";
-async function resolveAccount(baseUrl, accessToken, insecure, idToken) {
-  const sub = decodeJwt(idToken ?? accessToken)?.sub;
-  if (!sub) return void 0;
+async function resolveAccount(ctx, idToken) {
+  const claims = decodeJwt(idToken ?? ctx.token);
+  if (claims?.preferred_username) return claims.preferred_username;
+  if (!claims?.sub) return void 0;
   try {
-    const u = await getUserSafe(
-      { baseUrl, token: accessToken, businessDomain: DEFAULT_BUSINESS_DOMAIN, insecure },
-      sub
-    );
-    return u.account;
+    const u = await getMeSafe(ctx);
+    return u?.account;
   } catch {
     return void 0;
   }
 }
+async function verifyLoginPlatform(ctx) {
+  await ensureCompatible(ctx, new URL(ctx.baseUrl));
+}
+function loginContext(baseUrl, token, insecure, options) {
+  const ctx = {
+    baseUrl: trimTrailingSlashes(baseUrl),
+    token,
+    insecure: Boolean(insecure),
+    ...retryOptionsFrom(options)
+  };
+  configureVersionCheck(ctx, "login");
+  return ctx;
+}
+function warnEnvShadow(baseUrl) {
+  const notes = [];
+  const vars = [];
+  if (process.env.BKN_TOKEN) {
+    notes.push("BKN_TOKEN is set \u2014 other commands send it instead of this session's token.");
+    vars.push("BKN_TOKEN");
+  }
+  const envBase = process.env.BKN_BASE_URL;
+  if (envBase && baseUrl && trimTrailingSlashes(envBase) !== trimTrailingSlashes(baseUrl)) {
+    notes.push(
+      "BKN_BASE_URL is set to a different platform \u2014 other commands use it instead of this saved session."
+    );
+    vars.push("BKN_BASE_URL");
+  }
+  if (vars.length === 0) return;
+  process.stderr.write(
+    `warning: ${notes.join(" ")} To use the saved session: \`unset ${vars.join(" ")}\`
+`
+  );
+}
 function renderSessions(items) {
   const byPlatform = /* @__PURE__ */ new Map();
   for (const it of items) {
@@ -543,9 +597,11 @@ function registerAuthLeaves(cmd) {
         process.stdout.write(`Logged in to ${r.baseUrl ?? url} as ${r.username ?? r.userId}
 `);
       }
+      warnEnvShadow(r.baseUrl ?? url);
     };
     const token = opts.token ?? g.token;
     if (token) {
+      await verifyLoginPlatform(loginContext(url, token, g.insecure, g));
       report(attachToken(url, token, { insecure: g.insecure }));
       return;
     }
@@ -594,18 +650,16 @@ User code: ${userCode}
       }
       throw e;
     }
+    const authenticatedContext = loginContext(url, tokens.accessToken, g.insecure, g);
+    await verifyLoginPlatform(authenticatedContext);
     if (!account) {
-      account = await resolveAccount(
-        url,
-        tokens.accessToken,
-        Boolean(g.insecure),
-        tokens.idToken
-      );
+      account = await resolveAccount(authenticatedContext, tokens.idToken);
     }
     report(
       attachToken(url, tokens.accessToken, {
         refreshToken: tokens.refreshToken,
         idToken: tokens.idToken,
+        expiresAt: tokens.expiresAt,
         username: account,
         insecure: g.insecure
       })
@@ -620,25 +674,22 @@ User code: ${userCode}
     process.stdout.write(`${token}
 `);
   });
-  cmd.command("whoami [url]").description("Show current user identity (from the token)").option("--no-lookup", "skip the backend identity fallback (eacp/user/get)").action(async (_url, opts, cmd2) => {
+  cmd.command("whoami [url]").description("Show current user identity (from the token)").option("--no-lookup", "skip the backend identity lookup (bkn-safe /me)").action(async (_url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
     const me = whoami({ user: g.user });
     if (opts.lookup !== false && me.baseUrl && me.sub) {
       try {
-        const u = await getUserSafe(
-          {
-            baseUrl: me.baseUrl,
-            token: currentToken({ user: g.user }),
-            businessDomain: DEFAULT_BUSINESS_DOMAIN,
-            insecure: Boolean(g.insecure)
-          },
-          me.sub
-        );
+        const u = await getMeSafe({
+          baseUrl: me.baseUrl,
+          token: currentToken({ user: g.user }),
+          insecure: g.insecure ?? sessionInsecure({ user: g.user })
+        });
         if (u.account) me.username = u.account;
         if (u.name) me.name = u.name;
       } catch {
       }
     }
+    warnEnvShadow(me.baseUrl);
     const out = outputOptions(cmd2);
     if (out.json || out.compact || out.full) {
       printJson(me, out);
@@ -699,8 +750,9 @@ User code: ${userCode}
       baseUrl: url ?? g.baseUrl,
       token: g.token,
       user: g.user,
-      businessDomain: g.bizDomain,
-      insecure: g.insecure
+      insecure: g.insecure,
+      versionCheckMode: "cli",
+      ...retryOptionsFrom(g)
     });
     const account = opts.account ?? await promptLine("Account: ");
     const oldPassword = opts.oldPassword ?? await promptLine("Current password: ", true);
@@ -758,6 +810,24 @@ TOKENS
 
 // src/commands/admin.ts
 var int = (v) => Number.parseInt(v, 10);
+var NEW_USER_PASSWORD_ENV = "BKN_NEW_USER_PASSWORD";
+async function newUserPassword(opts) {
+  if (opts.password) return opts.password;
+  if (opts.promptPassword) {
+    const typed = await promptLine("Initial password: ", true);
+    if (typed) return typed;
+    throw new InputError("No password entered.");
+  }
+  const fromEnv = process.env[NEW_USER_PASSWORD_ENV];
+  if (fromEnv) return fromEnv;
+  throw new InputError(
+    `A new user needs an initial password: pass --password, --prompt-password, or set ${NEW_USER_PASSWORD_ENV}.`
+  );
+}
+function departmentIds(values) {
+  if (values === void 0) return void 0;
+  return values.flatMap((v) => v.split(",")).map((v) => v.trim()).filter((v) => v && v !== "-1");
+}
 var DEFAULT_RESET_PASSWORD = "openbkn";
 async function importLicenseFile(cmd, file, receipt) {
   const text = readFileSync2(file, "utf8");
@@ -769,10 +839,9 @@ function adminCommand() {
   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 \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) => {
+  org.command("list").description("List departments \u2192 {departments, total}").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,
         name: opts.name,
         limit: opts.limit,
         offset: opts.offset
@@ -783,39 +852,37 @@ function adminCommand() {
   org.command("get <id>").description("Get one department").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).admin.orgGet(id), outputOptions(cmd));
   });
-  org.command("members <id>").description("List members of a department").option("--role <r>", "role qualifier", "super_admin").option("--fields <s>", "fields segment", "users").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (id, opts, cmd) => {
+  org.command("members <id>").description("List direct members of a department \u2192 {users, total}").option("--limit <n>", "page size (default: all members)", int).option("--offset <n>", "page offset", int).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.orgMembers(id, {
-        role: opts.role,
         limit: opts.limit,
         offset: opts.offset
       }),
       outputOptions(cmd)
     );
   });
-  org.command("create").description("Create a department").requiredOption("--name <s>", "department name").option("--parent <id>", "parent department id", "-1").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").option("--status <n>", "status (1=enabled)", int).option("--oss-id <id>", "object-storage site id").action(async (opts, cmd) => {
+  org.command("create").description("Create a department").requiredOption("--name <s>", "department name").option("--parent <id>", "parent department id (omit for a root department)").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.orgCreate({
         name: opts.name,
-        parentId: opts.parent,
+        // "-1" was the ISF spelling of "no parent"; bkn-safe wants none.
+        parentId: opts.parent === "-1" ? void 0 : opts.parent,
         code: opts.code,
         remark: opts.remark,
         email: opts.email,
-        managerID: opts.manager,
-        status: opts.status
+        managerID: opts.manager
       }),
       outputOptions(cmd)
     );
   });
-  org.command("update <id>").description("Update a department (only provided fields change)").option("--name <s>", "new name").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").option("--status <n>", "status (1=enabled)", int).option("--oss-id <id>", "object-storage site id").action(async (id, opts, cmd) => {
+  org.command("update <id>").description("Update a department (only provided fields change)").option("--name <s>", "new name").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.orgUpdate(id, {
         name: opts.name,
         code: opts.code,
         remark: opts.remark,
         email: opts.email,
-        managerID: opts.manager,
-        status: opts.status
+        managerID: opts.manager
       }),
       outputOptions(cmd)
     );
@@ -823,14 +890,14 @@ function adminCommand() {
   org.command("delete <id>").description("Delete a department").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).admin.orgDelete(id), outputOptions(cmd));
   });
-  org.command("tree").description("Print the department hierarchy").option("--role <r>", "role qualifier", "super_admin").action(async (opts, cmd) => {
-    const tree = await clientFrom(cmd).admin.orgTree(opts.role);
+  org.command("tree").description("Print the department hierarchy").action(async (_opts, cmd) => {
+    const tree = await clientFrom(cmd).admin.orgTree();
     const out = outputOptions(cmd);
     if (out.json) printJson(tree, out);
     else console.log(renderOrgTree(tree));
   });
   const user = admin.command("user").description("User management");
-  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) => {
+  user.command("list").description("List users \u2192 {users, total}").option("--org <id>", "only direct members of this department").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,
@@ -859,35 +926,27 @@ function adminCommand() {
   user.command("roles <user>").description("List roles granted to a user").action(async (userId, _opts, cmd) => {
     printJson(await clientFrom(cmd).admin.userRoles(userId), outputOptions(cmd));
   });
-  user.command("create").description("Create a user (gets the platform default password)").requiredOption("--login <name>", "login name").option("--display-name <s>", "display name (defaults to login name)").option("--email <s>", "email").option("--department <id>", "department id", "-1").option("--code <s>", "user code").option("--position <s>", "position").option("--remark <s>", "remark").option("--tel <s>", "telephone").option("--priority <n>", "priority", int).option("--csf-level <n>", "confidentiality level", int).action(async (opts, cmd) => {
+  user.command("create").description("Create a user with an explicit initial password (must change on first login)").requiredOption("--login <name>", "login name").option("--password <s>", `initial password (or set ${NEW_USER_PASSWORD_ENV})`).option("--prompt-password", "type the initial password interactively (input hidden)").option("--display-name <s>", "display name").option("--email <s>", "email").option("--department <id...>", "initial department id(s)").option("--tel <s>", "telephone").action(async (opts, cmd) => {
+    const password = await newUserPassword(opts);
     printJson(
       await clientFrom(cmd).admin.userCreate({
         loginName: opts.login,
+        password,
         displayName: opts.displayName,
         email: opts.email,
-        departmentIds: opts.department ? [opts.department] : void 0,
-        code: opts.code,
-        position: opts.position,
-        remark: opts.remark,
-        telNumber: opts.tel,
-        priority: opts.priority,
-        csfLevel: opts.csfLevel
+        departmentIds: departmentIds(opts.department),
+        telNumber: opts.tel
       }),
       outputOptions(cmd)
     );
   });
-  user.command("update <id>").description("Update a user (only provided fields change)").option("--display-name <s>", "display name").option("--email <s>", "email").option("--code <s>", "user code").option("--position <s>", "position").option("--remark <s>", "remark").option("--tel <s>", "telephone").option("--manager <id>", "manager user id").option("--idcard <s>", "id-card number").option("--priority <n>", "priority", int).option("--csf-level <n>", "confidentiality level", int).option("--csf-level2 <n>", "secondary confidentiality level", int).option("--expire-time <n>", "account expiry (epoch, -1 = never)", int).action(async (id, opts, cmd) => {
+  user.command("update <id>").description("Update a user (only provided fields change)").option("--display-name <s>", "display name").option("--email <s>", "email").option("--tel <s>", "telephone").option("--department <id...>", "replace department membership with these id(s)").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.userUpdate(id, {
         displayName: opts.displayName,
         email: opts.email,
-        code: opts.code,
-        position: opts.position,
-        remark: opts.remark,
         telNumber: opts.tel,
-        managerID: opts.manager,
-        priority: opts.priority,
-        csfLevel: opts.csfLevel
+        departmentIds: opts.department === void 0 ? void 0 : departmentIds(opts.department)
       }),
       outputOptions(cmd)
     );
@@ -916,19 +975,24 @@ function adminCommand() {
       );
   });
   const role = admin.command("role").description("Role management");
-  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) => {
+  role.command("list").description("List roles \u2192 {roles, total}").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 (system | business | custom)").action(async (opts, cmd) => {
     printJson(
-      await clientFrom(cmd).admin.roleList({ keyword: opts.keyword, limit: opts.limit }),
+      await clientFrom(cmd).admin.roleList({
+        keyword: opts.keyword,
+        limit: opts.limit,
+        offset: opts.offset,
+        source: opts.source
+      }),
       outputOptions(cmd)
     );
   });
   role.command("get <role>").description("Get a role by id").option("--view <mode>", "detail view mode").action(async (roleId, _opts, cmd) => {
     printJson(await clientFrom(cmd).admin.roleGet(roleId), outputOptions(cmd));
   });
-  role.command("members <role>").description("List members of a role").option("--keyword <s>", "filter by keyword").option("--type <t>", "filter by member type (user|department|group|app)").option("--member <spec...>", "filter to specific member(s) '<type>:<id-or-name>'").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (roleId, opts, cmd) => {
+  role.command("members <role>").description("List members of a role \u2192 {members, total}").option("--limit <n>", "page size (default: all members)", int).option("--offset <n>", "page offset", int).action(async (roleId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).admin.roleMembers(roleId, {
-        keyword: opts.keyword,
+        offset: opts.offset,
         limit: opts.limit
       }),
       outputOptions(cmd)
@@ -968,7 +1032,10 @@ function adminCommand() {
     ["grant-perm", true],
     ["revoke-perm", false]
   ]) {
-    role.command(`${verb} <role>`).description(`${grant ? "Grant" : "Revoke"} a permission on a custom role (403 on built-in)`).requiredOption("--resource-type <t>", "resource type (e.g. catalog)").option("--resource-id <id>", "resource id ('*' = whole type)", "*").requiredOption("--operations <list>", "comma-separated operations").action(async (roleId, opts, cmd) => {
+    role.command(`${verb} <role>`).description(`${grant ? "Grant" : "Revoke"} a permission on a custom role (403 on built-in)`).requiredOption(
+      "--resource-type <t>",
+      "resource type: knowledge_network|catalog|resource|tool_box|function|mcp|skill"
+    ).option("--resource-id <id>", "resource id ('*' = whole type)", "*").requiredOption("--operations <list>", "comma-separated operations").action(async (roleId, opts, cmd) => {
       printJson(
         await clientFrom(cmd).admin.rolePermission(
           roleId,
@@ -1003,8 +1070,8 @@ function adminCommand() {
     const isLlm = kind === "llm";
     const m = admin.command(kind).description(`${kind} management`);
     const ns = isLlm ? "llm" : "small";
-    const list = m.command("list").description(`List ${kind} models`).option("--name <s>", "filter by name").option("--page <n>", "page", int, 1).option("--size <n>", "page size", int, DEFAULT_LIST_LIMIT);
-    (isLlm ? list.option("--series <s>", "model series") : list.option("--type <t>", "model type")).action(async (opts, cmd) => {
+    const list2 = m.command("list").description(`List ${kind} models`).option("--name <s>", "filter by name").option("--page <n>", "page", int, 1).option("--size <n>", "page size", int, DEFAULT_LIST_LIMIT);
+    list2.option("--type <t>", "model type filter").action(async (opts, cmd) => {
       printJson(
         await clientFrom(cmd).models[ns].list({
           name: opts.name,
@@ -1080,18 +1147,34 @@ function adminCommand() {
   ).action(async (_opts, cmd) => {
     printJson(await clientFrom(cmd).admin.licenseFingerprint(), outputOptions(cmd));
   });
-  admin.command("audit").description("Audit log queries").command("list").description("List login audit events").option("--user <name>", "filter by user").option("--start <time>", "start time").option("--end <time>", "end time").option("--page <n>", "page", int, 1).option("--size <n>", "page size", int, 30).action(async (opts, cmd) => {
+  const audit = admin.command("audit").description("Audit trail: management mutations and token-gate refusals (bkn-safe)");
+  audit.command("list").description("List audit log entries, newest first \u2192 {logs, total}").option("--actor-id <id>", "token subject id of the actor").option("--request-id <id>", "all rows written for one mutating HTTP request").option("--resource <noun>", "route noun, e.g. users, role-bindings, policies").option("--action <verb>", "business verb, e.g. create, grant, revoke, reset_password").option("--target-id <id>", "target id").option("--failed-only", "only refused and failed attempts (HTTP 4xx/5xx)").option("--from <time>", "created at or after this RFC 3339 timestamp (inclusive)").option("--to <time>", "created before this RFC 3339 timestamp (exclusive)").option("--before-id <id>", "keyset tiebreaker for rows sharing the --to timestamp").option("--offset <n>", "rows to skip", int).option("--limit <n>", `page size, 0..${AUDIT_LOG_MAX_LIMIT}`, int, DEFAULT_LIST_LIMIT).addOption(new Option("--start <time>", "alias of --from").hideHelp()).addOption(new Option("--end <time>", "alias of --to").hideHelp()).action(async (opts, cmd) => {
+    if (opts.start !== void 0 && opts.from !== void 0) {
+      throw new InputError("--start is an alias of --from; pass only one.");
+    }
+    if (opts.end !== void 0 && opts.to !== void 0) {
+      throw new InputError("--end is an alias of --to; pass only one.");
+    }
     printJson(
       await clientFrom(cmd).admin.auditList({
-        user: opts.user,
-        start: opts.start,
-        end: opts.end,
-        page: opts.page,
-        size: opts.size
+        actorId: opts.actorId,
+        requestId: opts.requestId,
+        resource: opts.resource,
+        action: opts.action,
+        targetId: opts.targetId,
+        failedOnly: Boolean(opts.failedOnly),
+        from: opts.from ?? opts.start,
+        to: opts.to ?? opts.end,
+        beforeId: opts.beforeId,
+        offset: opts.offset,
+        limit: opts.limit
       }),
       outputOptions(cmd)
     );
   });
+  audit.command("get <id>").description("Get one audit log entry").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.auditGet(id), outputOptions(cmd));
+  });
   const adminConfig = admin.command("config").description("Admin CLI config (active platform)");
   adminConfig.command("show").description("Show the active platform").action((_opts, cmd) => {
     printJson({ baseUrl: activePlatform() }, outputOptions(cmd));
@@ -1120,11 +1203,12 @@ function adminCommand() {
         baseUrl: g.baseUrl,
         token: g.token,
         user: g.user,
-        businessDomain: g.bizDomain,
-        insecure: g.insecure
+        insecure: g.insecure,
+        versionCheckMode: "cli",
+        ...retryOptionsFrom(g)
       }),
       url,
-      { method: opts.request, header: opts.header, data: opts.data, businessDomain: g.bizDomain }
+      { method: opts.request, header: opts.header, data: opts.data }
     );
     const out = outputOptions(cmd);
     try {
@@ -1218,129 +1302,155 @@ function appkeyCommand() {
 
 // src/commands/bkn.ts
 import { Command as Command4 } from "commander";
-
-// src/utils/bkn-validate.ts
-import { existsSync, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
-import { join, resolve } from "path";
-var BKN_OBJECT_NAME_MAX_LENGTH = 40;
-function parseFrontmatter(text) {
-  if (!text.startsWith("---")) return null;
-  const end = text.indexOf("\n---", 3);
-  if (end === -1) return null;
-  const block = text.slice(3, end);
-  const fm = {};
-  for (const line of block.split("\n")) {
-    const m = line.match(/^\s*(type|id|name)\s*:\s*(.+?)\s*$/);
-    if (m?.[1]) fm[m[1]] = m[2]?.replace(/^["']|["']$/g, "");
+var int3 = (v) => Number.parseInt(v, 10);
+function rejectUnknownSearchOptions(cmd) {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  const raw = root.rawArgs ?? [];
+  const separator = raw.indexOf("--");
+  const afterSeparator = separator < 0 ? [] : raw.slice(separator + 1);
+  for (const arg of cmd.args) {
+    if (/^--[A-Za-z]/.test(arg) && !afterSeparator.includes(arg)) {
+      throw new InputError(
+        `unknown option '${arg}' for bkn search (see --help); to search for text that starts with "--", put it after a -- separator`
+      );
+    }
+  }
+  if (cmd.args.length > 2) {
+    throw new InputError(
+      `bkn search takes <kn-id> <query>, received ${cmd.args.length} arguments; quote a multi-word query`
+    );
+  }
+}
+var SYSTEM_PROPERTIES = ["_instance_id", "_instance_identity", "_display"];
+var DIRECTIONS = ["asc", "desc"];
+var NAME_OR_UPDATE_TIME = ["update_time", "name"];
+var SCHEDULE_SORTS = [
+  "create_time",
+  "update_time",
+  "next_run_time",
+  "last_run_time",
+  "name"
+];
+var CAPABILITY_SORTS = ["create_time", "update_time"];
+var sortDirection = oneOf("--direction", DIRECTIONS);
+var IMPORT_MODES = ["normal", "overwrite", "ignore"];
+var BINDING_POLICIES = ["preserve", "detach"];
+function knListLimit(v) {
+  if (v === "-1") return -1;
+  const n = /^\d+$/.test(v) ? Number(v) : Number.NaN;
+  if (!(n >= 1 && n <= 1e3)) {
+    throw new InputError(`--limit must be an integer from 1 to 1000, or -1 for all (got '${v}')`);
   }
-  return fm;
+  return n;
 }
-function bknFiles(dir) {
-  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".bkn")).map((f) => join(dir, f));
+var nonNegativeInt = (flag) => (v) => {
+  const n = /^\d+$/.test(v) ? Number(v) : Number.NaN;
+  if (!Number.isSafeInteger(n)) {
+    throw new InputError(`${flag} must be a non-negative integer (got '${v}')`);
+  }
+  return n;
+};
+function actionLogKeyword(v) {
+  if (v.length > 128) {
+    throw new InputError(`--keyword must be at most 128 characters (got ${v.length})`);
+  }
+  return v;
 }
-function endpointRefs(text) {
-  const refs = [];
-  const idx = text.indexOf("### Endpoint");
-  if (idx === -1) return refs;
-  const after = text.slice(idx + "### Endpoint".length);
-  const next = after.indexOf("\n###");
-  const section = next === -1 ? after : after.slice(0, next);
-  for (const line of section.split("\n")) {
-    const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
-    if (cells.length < 2) continue;
-    const [source, target] = cells;
-    if (!source || !target) continue;
-    if (/^source$/i.test(source) || /^-+$/.test(source)) continue;
-    refs.push({ source, target });
+function writeModeFlags(cmd, withImportMode) {
+  cmd.option("--no-strict-mode", "skip dependency validation (strict_mode=false)");
+  if (withImportMode) {
+    cmd.option(
+      "--import-mode <mode>",
+      "existing ids/names: normal (default, error) | overwrite | ignore",
+      oneOf("--import-mode", IMPORT_MODES)
+    );
   }
-  return refs;
+  return cmd;
 }
-function validateBknDirectory(dirPath) {
-  const dir = resolve(dirPath);
-  const errors = [];
-  const warnings = [];
-  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
-    return {
-      valid: false,
-      dir,
-      counts: { objectTypes: 0, relationTypes: 0, conceptGroups: 0 },
-      errors: [`Not a directory: ${dir}`],
-      warnings: []
-    };
+function writeModes(opts) {
+  return {
+    branch: opts.branch,
+    strictMode: opts.strictMode === false ? false : void 0,
+    importMode: opts.importMode
+  };
+}
+function systemProperties(value) {
+  const list2 = csv(value);
+  for (const p of list2 ?? []) oneOf("--exclude-system-properties", SYSTEM_PROPERTIES)(p);
+  return list2;
+}
+var CAPABILITY_TYPES = ["skill", "function", "mcp_tool"];
+function capabilityEntries(opts) {
+  const targets = [opts.skill, opts.box, opts.mcp].filter((v) => v !== void 0);
+  if (targets.length !== 1) {
+    throw new InputError(
+      "Name exactly one of --skill <ids>, --box <box-id> or --mcp <mcp-id> to attach."
+    );
   }
-  const networkPath = join(dir, "network.bkn");
-  if (!existsSync(networkPath)) {
-    errors.push("Missing network.bkn at the BKN root.");
-  } else {
-    const fm = parseFrontmatter(readFileSync3(networkPath, "utf8"));
-    if (!fm) errors.push("network.bkn has no frontmatter block.");
-    else {
-      if (fm.type !== "knowledge_network")
-        errors.push(`network.bkn type must be 'knowledge_network', got '${fm.type ?? ""}'.`);
-      if (!fm.id) errors.push("network.bkn is missing 'id'.");
-      if (!fm.name) errors.push("network.bkn is missing 'name'.");
+  const comment = opts.comment || void 0;
+  if (opts.skill !== void 0) {
+    if (opts.tool !== void 0 || opts.allTools) {
+      throw new InputError("--tool and --all-tools go with --box or --mcp, not --skill.");
     }
+    const ids = csv(opts.skill) ?? [];
+    if (ids.length === 0) throw new InputError("--skill needs at least one skill id.");
+    return ids.map((id) => ({ capability_type: "skill", capability_id: id, comment }));
   }
-  const otIds = /* @__PURE__ */ new Set();
-  const otFiles = bknFiles(join(dir, "object_types"));
-  for (const file of otFiles) {
-    const fm = parseFrontmatter(readFileSync3(file, "utf8"));
-    const rel = file.slice(dir.length + 1);
-    if (!fm || fm.type !== "object_type") {
-      errors.push(`${rel}: not a valid object_type (missing/wrong frontmatter type).`);
-      continue;
-    }
-    if (!fm.id) errors.push(`${rel}: object_type missing 'id'.`);
-    if (!fm.name) errors.push(`${rel}: object_type missing 'name'.`);
-    if (fm.name && [...fm.name].length > BKN_OBJECT_NAME_MAX_LENGTH) {
-      errors.push(
-        `${rel}: object_type name exceeds ${BKN_OBJECT_NAME_MAX_LENGTH} codepoints ('${fm.name}').`
-      );
-    }
-    if (fm.id) {
-      if (otIds.has(fm.id)) errors.push(`Duplicate object_type id '${fm.id}'.`);
-      otIds.add(fm.id);
-    }
+  const flag = opts.box !== void 0 ? "--box" : "--mcp";
+  const owner = (opts.box ?? opts.mcp ?? "").trim();
+  const type = opts.box !== void 0 ? "function" : "mcp_tool";
+  if (!owner) throw new InputError(`${flag} needs an id.`);
+  if (opts.tool !== void 0 && opts.allTools) {
+    throw new InputError("Use --tool or --all-tools, not both.");
   }
-  const rtFiles = bknFiles(join(dir, "relation_types"));
-  for (const file of rtFiles) {
-    const text = readFileSync3(file, "utf8");
-    const fm = parseFrontmatter(text);
-    const rel = file.slice(dir.length + 1);
-    if (!fm || fm.type !== "relation_type") {
-      errors.push(`${rel}: not a valid relation_type (missing/wrong frontmatter type).`);
-      continue;
-    }
-    if (!fm.id) errors.push(`${rel}: relation_type missing 'id'.`);
-    for (const { source, target } of endpointRefs(text)) {
-      if (otIds.size > 0 && !otIds.has(source))
-        warnings.push(`${rel}: endpoint source '${source}' is not a known object_type.`);
-      if (otIds.size > 0 && !otIds.has(target))
-        warnings.push(`${rel}: endpoint target '${target}' is not a known object_type.`);
-    }
+  if (opts.allTools) return [{ capability_type: type, box_id: owner, all_tools: true, comment }];
+  const tools = csv(opts.tool) ?? [];
+  if (tools.length === 0) {
+    throw new InputError(
+      `${flag} binds tools, not the container: add --tool <ids> or --all-tools.`
+    );
+  }
+  return tools.map((tool) => ({
+    capability_type: type,
+    box_id: owner,
+    capability_id: tool,
+    comment
+  }));
+}
+function warnUnboundCapabilities(result, declared) {
+  if (declared.malformed) {
+    process.stderr.write(
+      `warning: network.bkn capabilities ${declared.malformed}; none of it was bound.
+`
+    );
+  }
+  const report = result?.capabilities;
+  const skipped = Array.isArray(report?.skipped) ? report.skipped.filter(
+    (s) => typeof s === "object" && s !== null
+  ) : [];
+  if (skipped.length === 0) return;
+  const noun = skipped.length === 1 ? "capability was" : "capabilities were";
+  process.stderr.write(`warning: ${skipped.length} declared ${noun} not bound:
+`);
+  for (const skip of skipped) {
+    const owner = skip.box_name ? `${skip.box_name} / ` : "";
+    const name = skip.name || skip.declared_id || "(unnamed)";
+    const detail = skip.detail ? ` \u2014 ${skip.detail}` : "";
+    process.stderr.write(`  ${skip.capability_type} ${owner}${name}: ${skip.reason}${detail}
+`);
   }
-  const cgFiles = bknFiles(join(dir, "concept_groups"));
-  return {
-    valid: errors.length === 0,
-    dir,
-    counts: {
-      objectTypes: otFiles.length,
-      relationTypes: rtFiles.length,
-      conceptGroups: cgFiles.length
-    },
-    errors,
-    warnings
-  };
 }
-
-// src/commands/bkn.ts
-var int3 = (v) => Number.parseInt(v, 10);
 function bknCommand() {
   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) => {
+  bkn.command("list").description("List knowledge networks").option("--limit <n>", "page size, 1\u20131000, or -1 for all", knListLimit, 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>",
+    "update_time | name",
+    oneOf("--sort", NAME_OR_UPDATE_TIME),
+    "update_time"
+  ).option("--direction <dir>", "asc | desc", sortDirection, "desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).kn.list({
       limit: o.limit,
@@ -1352,16 +1462,31 @@ function bknCommand() {
     });
     printJson(data, outputOptions(cmd));
   });
-  bkn.command("get <kn-id>").description("Get a knowledge network (use --stats or --export)").option("--stats", "include statistics").option("--export", "return the full export payload").action(async (knId, opts, cmd) => {
+  bkn.command("get <kn-id>").description("Get a knowledge network (use --stats or --export)").option("--stats", "include statistics").option("--export", "return the full export payload").option("--branch <b>", "branch (default: main)").option(
+    "--detail-level <level>",
+    "full (default) | summary \u2014 sent as detail_level; the service applies it only with --export (openbkn-ai/bkn-foundry#1632)",
+    oneOf("--detail-level", ["full", "summary"])
+  ).action(async (knId, opts, cmd) => {
     const data = await clientFrom(cmd).kn.get(knId, {
       stats: opts.stats,
-      exportMode: opts.export
+      exportMode: opts.export,
+      branch: opts.branch,
+      detailLevel: opts.detailLevel
     });
     printJson(data, outputOptions(cmd));
   });
-  bkn.command("search <kn-id> <query>").description(
+  bkn.command("search <kn-id> <query>").allowUnknownOption().allowExcessArguments().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) => {
+  ).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>",
+    "positive count of object types that may take part",
+    positiveInt("--max-object-types")
+  ).option(
+    "--max-instances <n>",
+    "positive count of instances per object type",
+    positiveInt("--max-instances")
+  ).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) => {
+    rejectUnknownSearchOptions(cmd);
     const data = await clientFrom(cmd).kn.search(knId, query, {
       objectTypes: csv(opts.objectTypes),
       excludeObjectTypes: csv(opts.excludeObjectTypes),
@@ -1380,36 +1505,59 @@ function bknCommand() {
   ];
   for (const [name, listMethod, crud] of schemaGroups) {
     const g = bkn.command(name).description(`${name} list/get/...`);
-    g.command("list <kn-id>").description(`List ${name}s`).option("--branch <b>", "branch", "main").action(async (knId, opts, cmd) => {
+    g.command("list <kn-id>").description(`List ${name}s`).option("--branch <b>", "branch", "main").option("--name-pattern <s>", "fuzzy name filter").option("--tag <s>", "exact tag filter").action(async (knId, opts, cmd) => {
       printJson(
-        await clientFrom(cmd).kn[listMethod](knId, { branch: opts.branch }),
+        await clientFrom(cmd).kn[listMethod](knId, {
+          branch: opts.branch,
+          namePattern: opts.namePattern,
+          tag: opts.tag
+        }),
         outputOptions(cmd)
       );
     });
     if (crud) {
-      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("get <kn-id> <id>").description(`Get ${name} \u2192 {entries}`).option("--branch <b>", "branch (default: main)").action(async (knId, id, opts, cmd) => {
+        printJson(
+          await clientFrom(cmd).kn[`${crud}Get`](knId, id, { branch: opts.branch }),
+          outputOptions(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) => {
+      writeModeFlags(
+        g.command("create <kn-id>").description(`Create ${name}s (--body / --body-file) \u2192 body is {entries:[\u2026]}`).option(
+          "--body <json>",
+          "body JSON {entries:[\u2026]} (a bare array is wrapped) \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+        ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)"),
+        true
+      ).action(async (knId, opts, cmd) => {
         printJson(
-          await clientFrom(cmd).kn[`${crud}Create`](knId, readBody(opts)),
+          await clientFrom(cmd).kn[`${crud}Create`](knId, readBody(opts), writeModes(opts)),
           outputOptions(cmd)
         );
       });
-      g.command("update <kn-id> <id>").description(`Update ${name} (--body / --body-file)`).option(
+      g.command("update <kn-id> <id>").description(`Update ${name} (--body / --body-file); the body carries base_version`).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) => {
+        "body JSON, including base_version from `get` \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+      ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)").option("--no-strict-mode", "skip dependency validation (strict_mode=false)").action(async (knId, id, opts, cmd) => {
         printJson(
-          await clientFrom(cmd).kn[`${crud}Update`](knId, id, readBody(opts)),
+          await clientFrom(cmd).kn[`${crud}Update`](knId, id, readBody(opts), {
+            branch: opts.branch,
+            strictMode: opts.strictMode === false ? false : void 0
+          }),
           outputOptions(cmd)
         );
       });
-      g.command("delete <kn-id> <id>").description(`Delete ${name}`).option("-y, --yes", "skip confirmation").action(async (knId, id, _o, cmd) => {
-        printJson(await clientFrom(cmd).kn[`${crud}Delete`](knId, id), outputOptions(cmd));
+      const del = g.command("delete <kn-id> <id>").description(`Delete ${name}`).option("-y, --yes", "skip confirmation").option("--branch <b>", "branch (default: main)");
+      if (crud === "objectType") {
+        del.option("--force", "delete even when a relation type still binds it (force_delete)");
+      }
+      del.action(async (knId, id, opts, cmd) => {
+        printJson(
+          await clientFrom(cmd).kn[`${crud}Delete`](knId, id, {
+            branch: opts.branch,
+            forceDelete: opts.force
+          }),
+          outputOptions(cmd)
+        );
       });
     }
   }
@@ -1417,23 +1565,36 @@ function bknCommand() {
   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) => {
+  ).option("--body-file <path>", "read query JSON from a file").option("--branch <b>", "branch (default: main)").option("--include-type-info", "include the action type definition").option(
+    "--exclude-system-properties <list>",
+    "drop system fields: _instance_id,_instance_identity,_display"
+  ).action(async (knId, atId, opts, cmd) => {
+    const excludeSystemProperties = systemProperties(opts.excludeSystemProperties);
     printJson(
-      await clientFrom(cmd).kn.actionTypeQuery(knId, atId, readBody(opts)),
+      await clientFrom(cmd).kn.actionTypeQuery(knId, atId, readBody(opts), {
+        branch: opts.branch,
+        includeTypeInfo: opts.includeTypeInfo,
+        excludeSystemProperties
+      }),
       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 \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) => {
+  ).option("--body-file <path>", "read envelope JSON from a file").option("--branch <b>", "branch (default: main)").action(async (knId, atId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.actionTypeExecute(knId, atId, readBody(opts)),
+      await clientFrom(cmd).kn.actionTypeExecute(knId, atId, readBody(opts), {
+        branch: opts.branch
+      }),
       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));
+  actionType?.command("get <kn-id> <at-id>").description("Get an action type").option("--branch <b>", "branch (default: main)").action(async (knId, atId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionTypeGet(knId, atId, { branch: opts.branch }),
+      outputOptions(cmd)
+    );
   });
   bkn.command("stats <kn-id>").description("Get knowledge-network statistics (alias for get --stats)").action(async (knId, _opts, cmd) => {
     printJson(await clientFrom(cmd).kn.get(knId, { stats: true }), outputOptions(cmd));
@@ -1445,46 +1606,159 @@ function bknCommand() {
   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) => {
+  ).option("--body-file <path>", "read query JSON from a file").option("--branch <b>", "branch (default: main)").option("--include-type-info", "include the object type definition").option("--include-logic-params", "include the computation parameters of logic properties").option(
+    "--exclude-system-properties <list>",
+    "drop system fields: _instance_id,_instance_identity,_display"
+  ).option("--ignoring-store-cache", "skip the index and read the store directly").addHelpText(
+    "after",
+    `
+The first page sends {limit, condition?, sort?, need_total?, properties?}. How the next
+page is asked for depends on the deploy: one that includes foundry #1623 answers with
+paging.next_cursor (null on the last page) \u2014 resend the query with "cursor" set to it.
+An older deploy answers without paging \u2014 resend the query with "offset" instead.
+
+  openbkn bkn object-type query <kn-id> <ot-id> --body '{"limit": 20}'
+  openbkn bkn object-type query <kn-id> <ot-id> --body '{"limit": 20, "cursor": "<next_cursor>"}'
+  openbkn bkn object-type query <kn-id> <ot-id> --body '{"limit": 20, "offset": 20}'   # older deploys`
+  ).action(async (knId, otId, opts, cmd) => {
+    const excludeSystemProperties = systemProperties(opts.excludeSystemProperties);
     printJson(
-      await clientFrom(cmd).kn.objectTypeQuery(knId, otId, readBody(opts)),
+      await clientFrom(cmd).kn.objectTypeQuery(knId, otId, readBody(opts), {
+        branch: opts.branch,
+        includeTypeInfo: opts.includeTypeInfo,
+        includeLogicParams: opts.includeLogicParams,
+        excludeSystemProperties,
+        ignoringStoreCache: opts.ignoringStoreCache
+      }),
       outputOptions(cmd)
     );
   });
-  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("create <name>").description("Create an (empty) knowledge network").option("--branch <b>", "branch, sent in both the query and the body", "main").option(
+    "--import-mode <mode>",
+    "an existing id/name: normal (default, error) | overwrite | ignore",
+    oneOf("--import-mode", IMPORT_MODES)
+  ).option("--no-strict-mode", "skip dependency validation (strict_mode=false)").option(
+    "--binding-policy <policy>",
+    "environment-local bindings: preserve (default) | detach",
+    oneOf("--binding-policy", BINDING_POLICIES)
+  ).action(async (name, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.create({
+        name,
+        ...writeModes(opts),
+        bindingPolicy: opts.bindingPolicy
+      }),
+      outputOptions(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));
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: the body's branch, else main)"),
+    true
+  ).action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.update(knId, readBody(opts), writeModes(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("delete <kn-id>").description("Delete a knowledge network").option("-y, --yes", "skip confirmation").option("--branch <b>", "branch (default: main)").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.delete(knId, { branch: opts.branch }), outputOptions(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));
+  ).option("--body-file <path>", "read subgraph query JSON from a file").option(
+    "--query-type <type>",
+    "relation_path to follow given paths (default: explore from a start point)",
+    oneOf("--query-type", ["", "relation_path"])
+  ).option("--branch <b>", "branch (default: main)").option("--include-logic-params", "include the computation parameters of logic properties").option(
+    "--exclude-system-properties <list>",
+    "drop system fields: _instance_id,_instance_identity,_display"
+  ).option("--ignoring-store-cache", "skip the index and read the store directly").action(async (knId, opts, cmd) => {
+    const excludeSystemProperties = systemProperties(opts.excludeSystemProperties);
+    printJson(
+      await clientFrom(cmd).kn.subgraph(knId, readBody(opts), {
+        queryType: opts.queryType,
+        branch: opts.branch,
+        includeLogicParams: opts.includeLogicParams,
+        excludeSystemProperties,
+        ignoringStoreCache: opts.ignoringStoreCache
+      }),
+      outputOptions(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) => {
+  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>",
+    "pending | running | completed | failed | cancelled",
+    oneOf("--status", ["pending", "running", "completed", "failed", "cancelled"])
+  ).option("--action-type-id <id>", "filter by action type").option(
+    "--trigger-type <t>",
+    "manual | scheduled",
+    oneOf("--trigger-type", ["manual", "scheduled"])
+  ).option(
+    "--keyword <s>",
+    "case-insensitive substring of the execution id (max 128 characters)",
+    actionLogKeyword
+  ).option("--start-time-from <ms>", "start time lower bound, epoch milliseconds", int3).option("--start-time-to <ms>", "start time upper bound, epoch milliseconds", int3).option("--limit <n>", "page size, 1\u20131000", positiveInt("--limit", 1e3), DEFAULT_LIST_LIMIT).option(
+    "--offset <n>",
+    "page offset; not allowed with --search-after",
+    nonNegativeInt("--offset")
+  ).option("--need-total", "also return total_count").option("--search-after <cursor>", "deep-paging cursor from the previous page (comma-joined)").action(async (knId, opts, cmd) => {
+    if (opts.searchAfter !== void 0 && opts.offset !== void 0) {
+      throw new InputError("--offset cannot be combined with --search-after; use one of them");
+    }
     printJson(
       await clientFrom(cmd).kn.actionLogs(knId, {
         status: opts.status,
         actionTypeId: opts.actionTypeId,
-        limit: opts.limit
+        triggerType: opts.triggerType,
+        keyword: opts.keyword,
+        startTimeFrom: opts.startTimeFrom,
+        startTimeTo: opts.startTimeTo,
+        limit: opts.limit,
+        offset: opts.offset,
+        needTotal: opts.needTotal,
+        searchAfter: opts.searchAfter
       }),
       outputOptions(cmd)
     );
   });
-  actionLog.command("get <kn-id> <log-id>").description("Get an action log").action(async (knId, logId, _opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.actionLog(knId, logId), outputOptions(cmd));
+  actionLog.command("get <kn-id> <log-id>").description("Get an action log").option(
+    "--results-limit <n>",
+    "page size of the embedded results, 1\u20131000",
+    positiveInt("--results-limit", 1e3)
+  ).option(
+    "--results-offset <n>",
+    "offset into the embedded results; offset + limit must not exceed 10000",
+    nonNegativeInt("--results-offset")
+  ).option(
+    "--results-status <s>",
+    "success | failed",
+    oneOf("--results-status", ["success", "failed"])
+  ).action(async (knId, logId, opts, cmd) => {
+    const window = (opts.resultsOffset ?? 0) + (opts.resultsLimit ?? 100);
+    if (opts.resultsOffset !== void 0 && window > 1e4) {
+      throw new InputError(
+        `--results-offset + --results-limit must not exceed 10000 (got ${window})`
+      );
+    }
+    printJson(
+      await clientFrom(cmd).kn.actionLog(knId, logId, {
+        resultsLimit: opts.resultsLimit,
+        resultsOffset: opts.resultsOffset,
+        resultsStatus: opts.resultsStatus
+      }),
+      outputOptions(cmd)
+    );
   });
-  actionLog.command("cancel <kn-id> <log-id>").description("Cancel a running action").action(async (knId, logId, _opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.cancelActionLog(knId, logId), outputOptions(cmd));
+  actionLog.command("cancel <kn-id> <log-id>").description("Cancel a running action").option("--reason <text>", "why it was cancelled").action(async (knId, logId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.cancelActionLog(knId, logId, { reason: opts.reason }),
+      outputOptions(cmd)
+    );
   });
   bkn.command("action-execution <kn-id> <execution-id>").description("Get action execution status").action(async (knId, execId, _opts, cmd) => {
     printJson(await clientFrom(cmd).kn.actionExecution(knId, execId), outputOptions(cmd));
@@ -1493,141 +1767,297 @@ function bknCommand() {
   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) => {
+  ).option("--body-file <path>", "read query JSON from a file").option("--branch <b>", "branch (default: main)").option("--fill-null", "align trend series to every bucket, filling gaps with null").action(async (knId, metricId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.metricQuery(knId, metricId, readBody(opts)),
+      await clientFrom(cmd).kn.metricQuery(knId, metricId, readBody(opts), {
+        branch: opts.branch,
+        fillNull: opts.fillNull
+      }),
       outputOptions(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));
+  ).option("--body-file <path>", "read metric definition JSON from a file").option("--branch <b>", "branch (default: main)").option("--fill-null", "align trend series to every bucket, filling gaps with null").action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricDryRun(knId, readBody(opts), {
+        branch: opts.branch,
+        fillNull: opts.fillNull
+      }),
+      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("list <kn-id>").description("List metrics").option("--branch <b>", "branch", "main").option("--name-pattern <s>", "fuzzy name filter").option("--tag <s>", "exact tag filter").action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricList(knId, {
+        branch: opts.branch,
+        namePattern: opts.namePattern,
+        tag: opts.tag
+      }),
+      outputOptions(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("get <kn-id> <metric-id>").description("Get a metric \u2192 {entries}, since the route takes a list of ids").option("--branch <b>", "branch (default: main)").action(async (knId, id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricGet(knId, id, { branch: opts.branch }),
+      outputOptions(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));
+  writeModeFlags(
+    metric.command("create <kn-id>").description("Create metrics (--body / --body-file) \u2192 body is {entries:[\u2026]}").option(
+      "--body <json>",
+      "body JSON {entries:[\u2026]} (a bare array is wrapped) \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (bkn-backend)"
+    ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)"),
+    true
+  ).action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricCreate(knId, readBody(opts), writeModes(opts)),
+      outputOptions(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) => {
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: main)"),
+    false
+  ).action(async (knId, id, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.metricUpdate(knId, id, readBody(opts)),
+      await clientFrom(cmd).kn.metricUpdate(knId, id, readBody(opts), writeModes(opts)),
       outputOptions(cmd)
     );
   });
-  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("delete <kn-id> <metric-id>").description("Delete a metric").option("--branch <b>", "branch (default: main)").action(async (knId, id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricDelete(knId, id, { branch: opts.branch }),
+      outputOptions(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));
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: main)"),
+    true
+  ).action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricValidate(knId, readBody(opts), writeModes(opts)),
+      outputOptions(cmd)
+    );
   });
   const cg = bkn.command("concept-group").description("Concept groups \u2014 list/get");
-  cg.command("list <kn-id>").description("List concept groups").action(async (knId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.conceptGroups(knId), outputOptions(cmd));
+  cg.command("list <kn-id>").description("List concept groups (all of them unless --limit is given)").option("--branch <b>", "branch (default: main)").option("--name-pattern <s>", "fuzzy name filter").option("--tag <s>", "exact tag filter").option("--sort <field>", "update_time | name", oneOf("--sort", NAME_OR_UPDATE_TIME)).option("--direction <dir>", "asc | desc", sortDirection).option("--offset <n>", "page offset", int3).option("--limit <n>", "page size (default: -1, all)", int3).action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroups(knId, {
+        branch: opts.branch,
+        namePattern: opts.namePattern,
+        tag: opts.tag,
+        sort: opts.sort,
+        direction: opts.direction,
+        offset: opts.offset,
+        limit: opts.limit
+      }),
+      outputOptions(cmd)
+    );
   });
-  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("get <kn-id> <cg-id>").description("Get a concept group").option("--branch <b>", "branch (default: main)").option("--stats", "include statistics").option("--mode <mode>", "response view mode (default view when omitted)").action(async (knId, cgId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroup(knId, cgId, {
+        branch: opts.branch,
+        includeStatistics: opts.stats,
+        mode: opts.mode
+      }),
+      outputOptions(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) => {
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: main)"),
+    true
+  ).action(async (knId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.conceptGroupCreate(knId, readBody(opts)),
+      await clientFrom(cmd).kn.conceptGroupCreate(knId, readBody(opts), writeModes(opts)),
       outputOptions(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) => {
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: main)"),
+    false
+  ).action(async (knId, cgId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.conceptGroupUpdate(knId, cgId, readBody(opts)),
+      await clientFrom(cmd).kn.conceptGroupUpdate(knId, cgId, readBody(opts), writeModes(opts)),
       outputOptions(cmd)
     );
   });
-  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("delete <kn-id> <cg-id>").description("Delete a concept group").option("--branch <b>", "branch (default: main)").action(async (knId, cgId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroupDelete(knId, cgId, { branch: opts.branch }),
+      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 \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) => {
+  writeModeFlags(
+    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").option("--branch <b>", "branch (default: main)"),
+    false
+  ).action(async (knId, cgId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.conceptGroupAddMembers(knId, cgId, readBody(opts)),
+      await clientFrom(cmd).kn.conceptGroupAddMembers(knId, cgId, readBody(opts), writeModes(opts)),
       outputOptions(cmd)
     );
   });
-  cg.command("remove-members <kn-id> <cg-id> <ot-ids>").description("Remove object types (comma-joined ids) from a concept group").action(async (knId, cgId, otIds, _o, cmd) => {
+  cg.command("remove-members <kn-id> <cg-id> <ot-ids>").description("Remove object types (comma-joined ids) from a concept group").option("--branch <b>", "branch (default: main)").action(async (knId, cgId, otIds, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.conceptGroupRemoveMembers(knId, cgId, otIds),
+      await clientFrom(cmd).kn.conceptGroupRemoveMembers(knId, cgId, otIds, {
+        branch: opts.branch
+      }),
       outputOptions(cmd)
     );
   });
   const sched = bkn.command("action-schedule").description("Action schedules \u2014 list/get");
-  sched.command("list <kn-id>").description("List action schedules").action(async (knId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.actionSchedules(knId), outputOptions(cmd));
+  sched.command("list <kn-id>").description("List action schedules (all of them unless --limit is given)").option("--branch <b>", "branch (default: main)").option("--name-pattern <s>", "fuzzy name filter").option("--action-type-id <id>", "filter by bound action type").option("--status <s>", "active | inactive", oneOf("--status", ["active", "inactive"])).option("--sort <field>", SCHEDULE_SORTS.join(" | "), oneOf("--sort", SCHEDULE_SORTS)).option("--direction <dir>", "asc | desc", sortDirection).option("--offset <n>", "page offset", int3).option("--limit <n>", "page size (default: -1, all)", int3).action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionSchedules(knId, {
+        branch: opts.branch,
+        namePattern: opts.namePattern,
+        actionTypeId: opts.actionTypeId,
+        status: opts.status,
+        sort: opts.sort,
+        direction: opts.direction,
+        offset: opts.offset,
+        limit: opts.limit
+      }),
+      outputOptions(cmd)
+    );
   });
-  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("get <kn-id> <schedule-id>").description("Get an action schedule").option("--branch <b>", "branch (default: main)").action(async (knId, sId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionSchedule(knId, sId, { branch: opts.branch }),
+      outputOptions(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) => {
+  ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)").action(async (knId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.actionScheduleCreate(knId, readBody(opts)),
+      await clientFrom(cmd).kn.actionScheduleCreate(knId, readBody(opts), {
+        branch: opts.branch
+      }),
       outputOptions(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) => {
+  ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)").action(async (knId, sId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.actionScheduleUpdate(knId, sId, readBody(opts)),
+      await clientFrom(cmd).kn.actionScheduleUpdate(knId, sId, readBody(opts), {
+        branch: opts.branch
+      }),
       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 \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) => {
+  ).option("--body-file <path>", "read body JSON from a file").option("--branch <b>", "branch (default: main)").action(async (knId, sId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.actionScheduleSetStatus(knId, sId, readBody(opts)),
+      await clientFrom(cmd).kn.actionScheduleSetStatus(knId, sId, readBody(opts), {
+        branch: opts.branch
+      }),
       outputOptions(cmd)
     );
   });
-  sched.command("delete <kn-id> <schedule-ids>").description("Delete action schedule(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
+  sched.command("delete <kn-id> <schedule-ids>").description("Delete action schedule(s) (comma-joined ids)").option("--branch <b>", "branch (default: main)").action(async (knId, ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionScheduleDelete(knId, ids, { branch: opts.branch }),
+      outputOptions(cmd)
+    );
   });
-  bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
-    "--embedding-model <name-or-id>",
-    "small-model name (or numeric ID, resolved to its name) for declared vector indexes (with --build)"
-  ).action(async (dir, opts, cmd) => {
+  const capability = bkn.command("capability").description("Skills, tool box tools and MCP tools bound to a network \u2014 list/attach/detach");
+  capability.command("list <kn-id>").description("List what the network has bound \u2192 {entries, boxes, total_count, \u2026}").option("--type <type>", "skill | function | mcp_tool").option("--box <box-id>", "only the tools of this tool box or MCP Server").option(
+    "--metadata-type <kind>",
+    "only function bindings whose tool box is openapi | function",
+    oneOf("--metadata-type", ["openapi", "function"])
+  ).option("--with-detail", "also fill description and status (one extra call per skill)").option("--branch <name>", "knowledge network branch (default: main)").option("--limit <n>", "page size", int3).option("--offset <n>", "page offset", int3).option("--sort <field>", "create_time | update_time", oneOf("--sort", CAPABILITY_SORTS)).option("--direction <dir>", "asc | desc", sortDirection).action(async (knId, opts, cmd) => {
+    if (opts.type && !CAPABILITY_TYPES.includes(opts.type)) {
+      throw new InputError(`--type must be one of ${CAPABILITY_TYPES.join(", ")}.`);
+    }
     printJson(
-      await clientFrom(cmd).kn.push(dir, {
+      await clientFrom(cmd).kn.capabilityList(knId, {
         branch: opts.branch,
-        build: Boolean(opts.build),
-        embeddingModel: opts.embeddingModel
+        type: opts.type,
+        boxId: opts.box,
+        metadataType: opts.metadataType,
+        withDetail: opts.withDetail,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: opts.sort,
+        direction: opts.direction
       }),
       outputOptions(cmd)
     );
   });
+  capability.command("attach <kn-id>").description("Bind skills, tool box tools or MCP tools; binding one twice is a no-op").option("--skill <ids>", "skill ids (comma-separated)").option("--box <box-id>", "a tool box \u2014 name its tools with --tool, or take --all-tools").option("--mcp <mcp-id>", "an MCP Server \u2014 name its tools with --tool, or take --all-tools").option("--tool <ids>", "tool ids for --box, tool names for --mcp (comma-separated)").option("--all-tools", "every enabled tool the box or server holds now").option("--comment <text>", "note stored on each new binding").option("--branch <name>", "knowledge network branch (default: main)").addHelpText(
+    "after",
+    `
+A binding is always to a tool, never to a box. --all-tools is expanded when you run it
+into one binding per tool the box holds at that moment; a tool added to the box later is
+not bound until you attach it (\`capability list\` counts it under boxes[].unmounted_tools).
+
+  openbkn bkn capability attach <kn-id> --skill <skill-id>
+  openbkn bkn capability attach <kn-id> --box <box-id> --tool <tool-id>[,<tool-id>]
+  openbkn bkn capability attach <kn-id> --box <box-id> --all-tools
+  openbkn bkn capability attach <kn-id> --mcp <mcp-id> --tool <tool-name>`
+  ).action(async (knId, opts, cmd) => {
+    const entries = capabilityEntries(opts);
+    printJson(
+      await clientFrom(cmd).kn.capabilityAttach(knId, entries, { branch: opts.branch }),
+      outputOptions(cmd)
+    );
+  });
+  capability.command("detach <kn-id> <binding-ids>").description("Release bindings by id (comma-separated, from `capability list`)").option("--branch <name>", "knowledge network branch (default: main)").action(async (knId, ids, opts, cmd) => {
+    const bindingIds = csv(ids) ?? [];
+    if (bindingIds.length === 0) throw new InputError("Name at least one binding id.");
+    await clientFrom(cmd).kn.capabilityDetach(knId, bindingIds, { branch: opts.branch });
+    printJson(
+      { kn_id: knId, branch: opts.branch ?? "main", detached: bindingIds },
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option(
+    "--import-mode <mode>",
+    "sent as import_mode: normal (default) | overwrite | ignore \u2014 0.1.5 deploys accept but do not apply it yet",
+    oneOf("--import-mode", ["normal", "overwrite", "ignore"])
+  ).option(
+    "--no-strict-mode",
+    "send strict_mode=false (skip dependency checks) \u2014 0.1.5 deploys accept but do not apply it yet"
+  ).option(
+    "--binding-policy <policy>",
+    "environment-local bindings: preserve (default) | detach",
+    oneOf("--binding-policy", ["preserve", "detach"])
+  ).action(async (dir, opts, cmd) => {
+    const declared = validateBknDirectory(dir).capabilities;
+    const result = await clientFrom(cmd).kn.push(dir, {
+      branch: opts.branch,
+      importMode: opts.importMode,
+      strictMode: opts.strictMode === false ? false : void 0,
+      bindingPolicy: opts.bindingPolicy,
+      verifyIntegrity: true,
+      onIntegrityWarning: (warning) => process.stderr.write(`warning: ${warning}
+`)
+    });
+    warnUnboundCapabilities(result, declared);
+    printJson(result, outputOptions(cmd));
+  });
   bkn.command("pull <kn-id> [directory]").description("Download a knowledge network as a BKN tar and extract it locally").option("--branch <name>", "source branch", "main").action(async (knId, dir, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.pull(knId, dir ?? knId, { branch: opts.branch }),
@@ -1637,31 +2067,69 @@ function bknCommand() {
   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) => {
+  ).option("--body-file <path>", "read request JSON from a file").option("--branch <b>", "branch (default: main)").addHelpText(
+    "after",
+    `
+The body needs source_object_type_id, direction (forward | backward | bidirectional) and
+path_length (1\u20133). The contract's enum spells the reverse direction \`reverse\`, but the
+backend refuses it with 400 InvalidParameter.Direction; use \`backward\`.
+
+  openbkn bkn relation-type-paths <kn-id> \\
+    --body '{"source_object_type_id": "<ot-id>", "direction": "bidirectional", "path_length": 2}'`
+  ).action(async (knId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).kn.relationTypePaths(knId, readBody(opts)),
+      await clientFrom(cmd).kn.relationTypePaths(knId, readBody(opts), { branch: opts.branch }),
       outputOptions(cmd)
     );
   });
-  bkn.command("resources").description("List BKN-backend resources").action(async (_opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.bknResources(), outputOptions(cmd));
-  });
-  bkn.command("create-from-catalog <catalog-id>").description("Build a knowledge network from a Vega catalog's tables").requiredOption("--name <name>", "knowledge network name").option("--tables <list>", "comma-separated table names (default: all)").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,<table>:<col>...]'").option("--build", "submit a Vega build task per resource after creation").option(
-    "--embedding-fields <map>",
-    "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
+  bkn.command("cypher <kn-id>").description(
+    "Answer a read-only Cypher query over the network's model, outside any Trace session"
+  ).requiredOption(
+    "--query <cypher>",
+    "read-only Cypher: labels are object types, relationship types are relation types"
   ).option(
-    "--embedding-model <name-or-id>",
-    "small-model name (or numeric ID, resolved to its name) for the vector index (with --build)"
-  ).option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
+    "--params <json>",
+    `values for $name placeholders, as a JSON object: '{"floor": 100}'`
+  ).option("--branch <branch>", "knowledge network branch (default: main)").addHelpText(
+    "after",
+    `
+The compiler behind \`openbkn context run-cypher\`, called directly: the same subset,
+the same limits, the same refusals naming the construct and its position. Answers
+{columns, entries}; the generated SQL is never returned. Nothing is recorded in BKN
+Trace \u2014 use context run-cypher when the query is part of a conversation an agent
+should be able to account for.
+
+  openbkn bkn cypher <kn-id> \\
+    --query "MATCH (c:customer)<-[:rel_order_customer]-(o:order) RETURN c.city AS city, count(*) AS orders"`
+  ).action(async (knId, opts, cmd) => {
+    if (!opts.query.trim()) throw new InputError("--query must not be empty.");
+    printJson(
+      await clientFrom(cmd).kn.cypher(knId, opts.query, {
+        branch: opts.branch,
+        parameters: cypherParams(opts.params)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("resources").description("List BKN-backend resources (knowledge networks) \u2192 {entries, total_count}").option("--keyword <s>", "name keyword filter").option("--limit <n>", "page size", int3, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int3, 0).option("--sort <field>", "sort field (default: name)").option("--direction <dir>", "asc | desc", sortDirection).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.bknResources({
+        keyword: opts.keyword,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: opts.sort,
+        direction: opts.direction
+      }),
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("create-from-catalog <catalog-id>").description("Build a knowledge network from a Vega catalog's tables").requiredOption("--name <name>", "knowledge network name").option("--tables <list>", "comma-separated table names (default: all)").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,<table>:<col>...]'").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.createFromCatalog({
         catalogId,
         name: opts.name,
         tables: csv(opts.tables),
         pkMap: opts.pkMap ? parsePkMap(opts.pkMap) : void 0,
-        build: Boolean(opts.build),
-        embeddingFields: opts.embeddingFields ? parseEmbeddingFields(opts.embeddingFields) : void 0,
-        embeddingModel: opts.embeddingModel,
         noRollback: opts.rollback === false,
         onProgress: (m) => console.error(m)
       }),
@@ -1680,6 +2148,7 @@ function bknCommand() {
       "action-type",
       "metric",
       "concept-group",
+      "capability",
       "action-log",
       "action-schedule"
     ],
@@ -1692,6 +2161,7 @@ function bknCommand() {
       "search",
       "subgraph",
       "relation-type-paths",
+      "cypher",
       "resources",
       "action-execution",
       "validate"
@@ -1703,6 +2173,10 @@ function bknCommand() {
     RUN: ["query", "dry-run", "validate"],
     WRITE: ["create", "update", "delete"]
   });
+  groupChildren(capability, {
+    READ: ["list"],
+    WRITE: ["attach", "detach"]
+  });
   guide(
     bkn,
     `WHERE IDS COME FROM
@@ -1718,6 +2192,13 @@ SEARCH VS THE MCP SIDE
 EDITING SCHEMA AS FILES
   pull <kn-id> ./dir  ->  edit  ->  validate ./dir  ->  push ./dir
   \`validate\` is offline and catches structure errors before the upload.
+  network.bkn may declare the skills and tools the network depends on under
+  \`capabilities:\`. push binds them by id, then by name; one this platform cannot
+  resolve is skipped, not fatal, and push lists every skip on stderr.
+
+CAPABILITIES
+  \`capability list <kn-id>\` shows what a network has bound \u2014 the set Context Loader
+  recalls skills and tools from; a network with nothing bound recalls nothing.
 
 REQUEST BODIES
   create/update take a definition; query/execute/dry-run take a query. Both are documented
@@ -1726,7 +2207,7 @@ REQUEST BODIES
 
 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
+  then \`openbkn vega resource build <resource-id>\` produces the index. There is no
   whole-network build.`
   );
   return group(bkn, "DATA & KNOWLEDGE");
@@ -1739,7 +2220,7 @@ function collect(value, prev) {
   return prev;
 }
 function callCommand() {
-  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(
+  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 on the current platform").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,
@@ -1751,8 +2232,9 @@ function callCommand() {
       baseUrl: g.baseUrl,
       token: g.token,
       user: g.user,
-      businessDomain: g.bizDomain,
       insecure: g.insecure,
+      versionCheckMode: "cli",
+      ...retryOptionsFrom(g),
       ...trace ? { trace } : {}
     });
     const res = await rawCall(ctx, url, {
@@ -1760,7 +2242,6 @@ function callCommand() {
       header: opts.header,
       data: opts.data ?? opts.dataRaw,
       form: opts.form,
-      businessDomain: g.bizDomain,
       verbose: opts.verbose
     });
     const out = outputOptions(cmd2);
@@ -1785,69 +2266,42 @@ function callCommand() {
 
 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.`
+  read the path and request body there rather than guessing. Authentication 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 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 Command6("config").description("Remember a platform URL / business domain");
-  config.command("show").description("Show the active platform and business domain").action((_opts, cmd) => {
+  const config = new Command6("config").description("Remember a platform URL");
+  config.command("show").description("Show the active platform").action((_opts, cmd) => {
     const baseUrl = activePlatform();
-    printJson(
-      {
-        baseUrl,
-        businessDomain: baseUrl ? readPlatformConfig(baseUrl).businessDomain : void 0
-      },
-      outputOptions(cmd)
-    );
+    printJson({ baseUrl }, outputOptions(cmd));
   });
-  config.command("set <key> <value>").description("Set a config value (baseUrl | businessDomain)").action((key, value, _opts, cmd) => {
+  config.command("set <key> <value>").description("Set a config value (baseUrl)").action((key, value, _opts, cmd) => {
     if (key === "baseUrl") {
       setActivePlatform(trimTrailingSlashes(value));
-    } else if (key === "businessDomain") {
-      updatePlatformConfig(requireActive(), { businessDomain: value });
     } else {
-      throw new InputError(`Unknown config key: ${key} (expected baseUrl | businessDomain)`);
+      throw new InputError(`Unknown config key: ${key} (expected baseUrl)`);
     }
     printJson({ ok: true, key, value }, outputOptions(cmd));
   });
-  config.command("set-bd <value>").description("Set the default business domain for the active platform").action((value, _opts, cmd) => {
-    const baseUrl = requireActive();
-    updatePlatformConfig(baseUrl, { businessDomain: value });
-    printJson({ baseUrl, businessDomain: value }, outputOptions(cmd));
-  });
-  config.command("list-bd").description("List business domains (requires login)").action(() => {
-    throw new InputError("Not yet implemented \u2014 requires backend business-domains API.");
-  });
-  groupChildren(config, { READ: ["show", "list-bd"], WRITE: ["set", "set-bd"] });
+  groupChildren(config, { READ: ["show"], WRITE: ["set"] });
   return group(config, "SIGN IN & SETTINGS");
 }
 
 // src/commands/context.ts
-import { Command as Command7 } from "commander";
+import { Command as Command7, Option as Option2 } from "commander";
 var int4 = (v) => Number.parseInt(v, 10);
+var list = (v) => v.split(",").map((part) => part.trim()).filter(Boolean);
 var collectArg = (v, prev) => {
   prev.push(v);
   return prev;
 };
 function buildArgs(opts) {
-  let out = {};
-  if (opts.args) {
-    try {
-      out = parseBigIntJSON(opts.args);
-    } catch {
-      throw new InputError("--args must be valid JSON");
-    }
-  }
+  const out = readJsonArgs(opts) ?? {};
   for (const pair of opts.arg ?? []) {
     const idx = pair.indexOf("=");
     if (idx <= 0) throw new InputError(`--arg must be key=value (got: ${pair})`);
@@ -1882,20 +2336,34 @@ function contextCommand() {
   const cmd = new Command7("context").description(
     "Ask a network questions (the MCP interface agents use)"
   );
-  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");
-    }
-  };
+  const jsonArgs = (opts) => readJsonArgs(opts, true);
   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) => {
+  ).option(
+    "--concept-groups <ids>",
+    "comma-separated concept-group ids to confine recall to (ids from kn-detail)",
+    list
+  ).option(
+    "--only <kinds>",
+    "return only these concept kinds, comma-separated: object,relation,action,metric",
+    list
+  ).addOption(new Option2("--scope <kinds>", "alias of --only").argParser(list).hideHelp()).option("--max <n>", "max concepts per kind", int4).option(
+    "--schema-brief",
+    "trimmed schema: property name/type only (MCP tool default true; REST default false)"
+  ).option("--no-schema-brief", "full schema: adds property comments, primary keys and tags").option("--include-columns", "add each data property's physical column (needed for run-sql)").option("--rerank", "re-rank relation types (the server default)").option("--no-rerank", "skip relation-type re-ranking").option("--rerank-model <name>", "override the deploy's rerank model (operators only)").action(async (knId, query, opts, cmd2) => {
+    if (opts.only && opts.scope) throw new InputError("--scope is an alias of --only; pass one");
+    const kinds = opts.only ?? opts.scope;
+    const scope = {
+      ...kinds ? scopeFromKinds(kinds) : {},
+      ...opts.conceptGroups?.length ? { conceptGroups: opts.conceptGroups } : {}
+    };
     const data = await clientFrom(cmd2).context.searchSchema(knId, query, {
-      searchScope: opts.scope ? String(opts.scope).split(",") : void 0,
-      maxConcepts: opts.max
+      searchScope: Object.keys(scope).length > 0 ? scope : void 0,
+      maxConcepts: opts.max,
+      schemaBrief: opts.schemaBrief,
+      enableRerank: opts.rerank,
+      rerankModel: opts.rerankModel,
+      includeColumns: opts.includeColumns
     });
     printJson(data, outputOptions(cmd2));
   });
@@ -1903,21 +2371,37 @@ function contextCommand() {
     `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) => {
+    "tool arguments as JSON (- for stdin); kn_id is filled from <kn-id> unless given; --schema prints the shape"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").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);
+    const args = jsonArgs(opts);
     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)", int4).action(async (knId, otId, opts, cmd2) => {
+  cmd.command("search-capabilities <kn-id>").description(
+    "Rank every capability the network mounted: skills, functions, API tools, MCP tools"
+  ).option("--query <text>", "rank by relevance; omit to list in mount order").option("--types <list>", "comma-separated: skill,function,mcp_tool", list).option(
+    "--metadata-types <list>",
+    "comma-separated: openapi,function (splits function tools)",
+    list
+  ).option("--owner-id <id>", "one toolbox or MCP server").option("--limit <n>", "max results (1-100)", int4).action(async (knId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).context.findSkills(knId, otId, opts.topK),
+      await clientFrom(cmd2).context.searchCapabilities(knId, {
+        query: opts.query,
+        types: opts.types,
+        metadataTypes: opts.metadataTypes,
+        ownerId: opts.ownerId,
+        limit: opts.limit
+      }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("kn-detail <kn-id>").description("Get a KN's schema at a detail level (progressive: summary skeleton \u2192 drill down)").option("--detail-level <level>", "summary (default) | full", "summary").action(async (knId, opts, cmd2) => {
-    const level = opts.detailLevel === "full" ? "full" : "summary";
-    printJson(await clientFrom(cmd2).context.knDetail(knId, level), outputOptions(cmd2));
+  cmd.command("kn-detail <kn-id>").description("Get a KN's schema at a detail level (progressive: summary skeleton \u2192 drill down)").option(
+    "--detail-level <level>",
+    "summary (default) | full",
+    oneOf("--detail-level", ["summary", "full"]),
+    "summary"
+  ).action(async (knId, opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.knDetail(knId, opts.detailLevel), outputOptions(cmd2));
   });
   cmd.command("object-types <kn-id> <ids...>").description("Full definitions for the given object-type ids (unmatched \u2192 `missing`)").action(async (knId, ids, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).context.objectTypes(knId, ids), outputOptions(cmd2));
@@ -1994,6 +2478,51 @@ adds paging and --need-total but records nothing in Trace.`
     if (opts.timeout !== void 0) args.query_timeout = opts.timeout;
     printJson(await clientFrom(cmd2).context.toolCall(knId, "run_sql", args), outputOptions(cmd2));
   });
+  cmd.command("run-cypher <kn-id>").description(
+    "Filter along a path and aggregate across object types with read-only Cypher over the model"
+  ).option(
+    "--query <cypher>",
+    "read-only Cypher: labels are object types, relationship types are relation types"
+  ).option(
+    "--params <json>",
+    `values for $name placeholders, as a JSON object: '{"floor": 100}'`
+  ).option("--branch <branch>", "knowledge network branch (default: main)").option("--schema", "print this tool's argument schema from the deploy instead of calling it").addHelpText(
+    "after",
+    `
+Everything is named the way the model names it \u2014 no resource id, no physical column:
+
+  openbkn context search-schema <kn-id> "<what you are after>" --json
+      \u2192 object type and relation type ids or names, property names
+
+  openbkn context run-cypher <kn-id> \\
+    --query "MATCH (o:order)-[:rel_order_item_order]->(i:order_item)
+             WHERE o.status IN ['paid','shipped'] AND o.amount > \\$floor
+             RETURN o.status AS status, count(*) AS orders ORDER BY orders DESC LIMIT 20" \\
+    --params '{"floor": 100}'
+
+Supported: several MATCH clauses and comma-separated paths; -[:R]->, <-[:R]- and
+undirected -[:R]-; WHERE with comparisons, IN, IS NULL, AND/OR/NOT; RETURN with
+aliases, DISTINCT and count/sum/avg/min/max (grouping by the other returned columns);
+ORDER BY, SKIP, LIMIT. Refused with the construct and its position: OPTIONAL MATCH,
+WITH, UNION, variable-length paths, functions and arithmetic, returning a whole node.
+A query holds at most 8 relationships and 9 nodes; without LIMIT it returns 1000 rows,
+and LIMIT may not exceed 10000.
+
+What Cypher cannot say \u2014 CTEs, UNION, window functions \u2014 or a resource never modelled
+as an object type belongs in run-sql. The same query runs outside any Trace session
+through \`openbkn bkn cypher\`.`
+  ).action(async (knId, opts, cmd2) => {
+    if (opts.schema) return printToolSchema(cmd2, knId, "run_cypher");
+    if (!opts.query)
+      throw new InputError("--query is required (or use --schema to see the shape)");
+    printJson(
+      await clientFrom(cmd2).context.runCypher(knId, opts.query, {
+        branch: opts.branch,
+        parameters: cypherParams(opts.params)
+      }),
+      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",
@@ -2002,7 +2531,10 @@ adds paging and --need-total but records nothing in Trace.`
     "--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(
+  ).option(
+    "--args <json>",
+    "extra tool arguments merged in (condition, sort, offset \u2026; - for stdin)"
+  ).option("--args-file <path>", "read extra tool arguments as JSON from a file (or - for stdin)").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
@@ -2014,7 +2546,7 @@ Paths multiply with each hop, so start at 1 or 2.`
       throw new InputError("--hops is required (or use --schema to see the shape)");
     }
     const args = {
-      ...opts.args ? jsonArgs(opts.args) : {},
+      ...readJsonArgs(opts) ?? {},
       source_object_type_id: objectTypeId,
       direction: opts.direction,
       path_length: opts.hops
@@ -2027,8 +2559,8 @@ Paths multiply with each hop, so start at 1 or 2.`
   });
   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(
+    "tool arguments: analysis_dimensions, time, condition, having, order_by, limit, fill_null; - for stdin"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").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>\`
@@ -2036,7 +2568,7 @@ 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 };
+    const args = { ...readJsonArgs(opts) ?? {}, metric_id: metricId };
     printJson(
       await clientFrom(cmd2).context.toolCall(knId, "query_metric", args),
       outputOptions(cmd2)
@@ -2047,8 +2579,8 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
   });
   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(
+    "tool arguments as JSON (- for stdin); kn_id (for network-scoped tools) and response_format=json are filled unless given \u2014 input schema comes from `context tools <kn-id>`"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").option(
     "--arg <key=value>",
     "one argument (repeatable; value parsed as JSON, else string)",
     collectArg,
@@ -2056,8 +2588,23 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
   ).option(
     "--schema",
     "print the named tool's argument schema from the deploy instead of calling it"
-  ).action(async (knId, name, opts, cmd2) => {
+  ).option("--receipt", "return the validated operation receipt (requires --json or --compact)").action(async (knId, name, opts, cmd2) => {
+    if (opts.receipt && opts.schema) {
+      throw new InputError("--receipt cannot be combined with --schema");
+    }
+    if (opts.receipt && !cmd2.optsWithGlobals().json && !cmd2.optsWithGlobals().compact) {
+      throw new InputError("--receipt requires --json or --compact");
+    }
     if (opts.schema) return printToolSchema(cmd2, knId, name);
+    if (opts.receipt) {
+      const { value, receipt } = await clientFrom(cmd2).context.managedToolCall(
+        knId,
+        name,
+        buildArgs(opts)
+      );
+      printJson({ value, bkn_receipt: receipt }, { ...outputOptions(cmd2), json: true });
+      return;
+    }
     printJson(
       await clientFrom(cmd2).context.toolCall(knId, name, buildArgs(opts)),
       outputOptions(cmd2)
@@ -2065,7 +2612,7 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
   });
   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 \u2014 see `context call-method <kn-id> tools/list`").option(
+  ).option("--args <json>", "method params as JSON; use - for stdin").option("--args-file <path>", "read method params as JSON from a file (or - for stdin)").option(
     "--arg <key=value>",
     "one param (repeatable; value parsed as JSON, else string)",
     collectArg,
@@ -2088,49 +2635,36 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
   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 \u2014 argument names come from `context prompts <kn-id>`"
-  ).action(async (knId, name, opts, cmd2) => {
-    let args;
-    if (opts.args) {
-      try {
-        args = parseBigIntJSON(opts.args);
-      } catch {
-        throw new InputError("--args must be valid JSON");
-      }
-    }
+  cmd.command("prompt <kn-id> <name>").description("Get one MCP prompt (--args JSON for prompt arguments)").option("--args <json>", "prompt arguments as JSON; use - for stdin").option("--args-file <path>", "read prompt arguments as JSON from a file (or - for stdin)").action(async (knId, name, opts, cmd2) => {
+    const args = readJsonArgs(opts);
     printJson(await clientFrom(cmd2).context.prompt(knId, name, args), outputOptions(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) => {
+    "tool arguments as JSON (- for stdin); kn_id is filled from <kn-id> unless given; --schema prints the shape"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").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)),
+      await clientFrom(cmd2).context.queryInstanceSubgraph(knId, jsonArgs(opts)),
       outputOptions(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) => {
+    "tool arguments as JSON (- for stdin); kn_id is filled from <kn-id> unless given; --schema prints the shape"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").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)),
+      await clientFrom(cmd2).context.logicProperties(knId, jsonArgs(opts)),
       outputOptions(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) => {
+    "tool arguments as JSON (- for stdin); kn_id is filled from <kn-id> unless given; --schema prints the shape"
+  ).option("--args-file <path>", "read tool arguments as JSON from a file (or - for stdin)").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)
-    );
+    printJson(await clientFrom(cmd2).context.actionInfo(knId, jsonArgs(opts)), outputOptions(cmd2));
   });
   groupChildren(cmd, {
     GROUPS: ["conversation"],
@@ -2146,11 +2680,12 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
       "templates",
       "prompts",
       "prompt",
-      "find-skills"
+      "search-capabilities"
     ],
     RUN: [
       "query-object-instance",
       "run-sql",
+      "run-cypher",
       "explore-subgraph",
       "query-metric",
       "query-instance-subgraph",
@@ -2170,15 +2705,29 @@ rewriting it with \`run-sql\` produces a number the platform will not agree with
      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.
+  Aggregation, ranking, GROUP BY or joins are not query-object-instance. When the question
+  can be stated in object types and relation types \u2014 filter along a path, aggregate what
+  it reaches \u2014 use \`run-cypher <kn-id>\`: model names only, no resource ids or physical
+  columns. SQL through \`run-sql <kn-id>\` is for what the Cypher subset cannot say.
+  Unknown topology is \`explore-subgraph <kn-id> <ot-id> --hops <n>\`, 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.
 
+QUERY ARGUMENTS
+  query-object-instance rejects unknown argument keys before calling the platform. Combine
+  conditions with condition.sub_conditions, not condition.conditions; vector search belongs in
+  condition.operation=knn, not a top-level knn argument. Do not combine condition and filters:
+  the platform ignores filters when condition is present. Page with cursor (the MCP tool's
+  key) or offset, never both; search_after (the REST name) is passed through unchanged for a
+  deploy that advertises it. Any kn_id in --args must match <kn-id>. For properties and condition.field,
+  run object-types <kn-id> <ot-id> first to see the valid field names. Specifying properties
+  also reads the object-type schema once and rejects unknown names before the query. --schema shows the
+  argument shape advertised by this deploy. Every --args option also accepts --args-file <path>,
+  while --args - reads JSON from stdin.
+
 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.`
@@ -2217,7 +2766,6 @@ var returns_default = {
     "bkn list": ["entries", "total_count"],
     "bkn get": [
       "branch",
-      "business_domain",
       "color",
       "comment",
       "create_time",
@@ -2239,7 +2787,6 @@ var returns_default = {
     "bkn action-type get": ["entries"],
     "bkn stats": [
       "branch",
-      "business_domain",
       "color",
       "comment",
       "create_time",
@@ -2400,7 +2947,6 @@ var returns_default = {
     ],
     "skill list": ["data", "has_next", "has_prev", "page", "page_size", "total", "total_pages"],
     "skill get": [
-      "business_domain_id",
       "category",
       "category_name",
       "create_time",
@@ -2416,7 +2962,6 @@ var returns_default = {
     ],
     "skill market": ["data", "has_next", "has_prev", "page", "page_size", "total", "total_pages"],
     "skill market-get": [
-      "business_domain_id",
       "category",
       "category_name",
       "create_time",
@@ -2437,8 +2982,8 @@ var returns_default = {
     "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"],
+    "sandbox deps": ["dependencies", "session_id"],
+    "sandbox template": ["code_template", "template_type"],
     "trace graph": [
       "data",
       "duration_nano",
@@ -2572,7 +3117,7 @@ var returns_default = {
       "updated_at"
     ],
     "admin user roles": ["roles"],
-    "admin role list": ["roles"],
+    "admin role list": ["roles", "total"],
     "admin role get": [
       "built_in",
       "created_at",
@@ -2631,7 +3176,7 @@ var SERVICE_PROBES = [
   { 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"
+    path: "/api/agent-operator-integration/v1/tool-box/list?page=1&page_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" },
@@ -2644,7 +3189,7 @@ var COMMAND_SERVICE = [
   [/^resource\b/, "vega-backend"],
   [/^context\b/, "agent-retrieval"],
   [/^trace\b/, "agent-observability"],
-  [/^(skill|toolbox|tool|function)\b/, "agent-operator-integration"],
+  [/^(skill|mcp|sandbox|toolbox|tool|function|api)\b/, "agent-operator-integration"],
   [/^model\b/, "mf-model-manager"],
   [/^(auth|appkey)\b/, "safe"],
   [/^admin (llm|small-model)\b/, "mf-model-manager"],
@@ -2656,10 +3201,11 @@ var COMMAND_TOOL = {
   "context query-instance-subgraph": "query_instance_subgraph",
   "context explore-subgraph": "explore_subgraph",
   "context run-sql": "run_sql",
+  "context run-cypher": "run_cypher",
   "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 search-capabilities": "search_capabilities",
   "context kn-detail": "get_kn_detail",
   "context object-types": "get_object_types",
   "context relation-types": "get_relation_types"
@@ -2714,6 +3260,7 @@ var ID_SOURCES = {
   "at-id": "openbkn bkn action-type list <kn-id>",
   "metric-id": "openbkn bkn metric list <kn-id>",
   "skill-id": "openbkn skill list",
+  "mcp-id": "openbkn mcp list",
   "box-id": "openbkn toolbox list",
   "tool-id": "openbkn tool list --toolbox <box-id>",
   "conversation-id": "openbkn trace conversations list",
@@ -2727,8 +3274,7 @@ var ID_SOURCES = {
   "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>",
+  "document-ids": "openbkn vega resource document-get <resource-id> <document-ids...>",
   // Named entities, wherever they appear; the overrides below cover the cases
   // where the same word means something else.
   role: "openbkn admin role list",
@@ -2750,12 +3296,15 @@ var GROUP_ID_SOURCES = [
   [/^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"],
+  [/^vega build-task\b/, "openbkn vega build-task 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"],
+  [/^mcp\b/, "openbkn mcp list"],
   [/^toolbox\b/, "openbkn toolbox list"],
+  [/^function\b/, "openbkn function list --toolbox <box-id>"],
+  [/^api\b/, "openbkn api list --toolbox <box-id>"],
   [/^tool\b/, "openbkn tool list --toolbox <box-id>"],
   [/^appkey\b/, "openbkn appkey list"],
   [/^admin org\b/, "openbkn admin org list"],
@@ -2764,6 +3313,7 @@ var GROUP_ID_SOURCES = [
   [/^admin role\b/, "openbkn admin role list"],
   [/^admin llm\b/, "openbkn admin llm list"],
   [/^admin small-model\b/, "openbkn admin small-model list"],
+  [/^admin audit\b/, "openbkn admin audit 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>"],
@@ -2776,13 +3326,15 @@ var GROUP_ID_SOURCES = [
 function sourceOf(argName, path, isLast) {
   const override = ARGUMENT_OVERRIDES[`${path.join(" ")}|${argName}`];
   if (override !== void 0) return override ?? void 0;
+  const parent = path.slice(0, -1).join(" ");
+  const groupSource = GROUP_ID_SOURCES.find(([re]) => re.test(parent))?.[1];
+  if (/^tool-ids?$/i.test(argName) && groupSource) return groupSource;
   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];
+  return groupSource;
 }
 function describeOption(opt) {
   return {
@@ -2813,7 +3365,7 @@ function describeNode(cmd, parentPath, depth) {
   };
   if (depth <= 0) return children.length ? { ...skeleton, hasCommands: true } : skeleton;
   const aliases = cmd.aliases();
-  const options = cmd.options.filter((o) => o.long !== "--help");
+  const options = cmd.options.filter((o) => o.long !== "--help" && !o.hidden);
   return {
     ...skeleton,
     ...aliases.length ? { aliases } : {},
@@ -2849,8 +3401,8 @@ var FIELD_MEANINGS = {
   guide: "prose the command's own --help prints under its command list",
   commands: "nested commands"
 };
-function resolve2(program2, path) {
-  let node = program2;
+function resolve(program, path) {
+  let node = program;
   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(" ")}`);
@@ -2858,29 +3410,29 @@ function resolve2(program2, path) {
   }
   return node;
 }
-function describeCommandTree(program2, opts = {}) {
+function describeCommandTree(program, 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)
+      ...describeNode(resolve(program, opts.path), opts.path.slice(0, -1), depth + 1)
     };
   }
-  const top = program2.commands.filter(
+  const top = program.commands.filter(
     (c) => !c.name().startsWith("help") && c.name() !== "describe"
   );
   return {
-    name: program2.name(),
-    version: program2.version(),
-    summary: program2.description(),
+    name: program.name(),
+    version: program.version(),
+    summary: program.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)
+    globalOptions: program.options.filter((o) => o.long !== "--help").map(describeOption),
+    guide: guideOf(program)
   };
 }
 function rows(node, indent = "") {
@@ -2922,14 +3474,14 @@ function renderText(tree) {
   }
   return out.join("\n");
 }
-function describeCommand(program2) {
+function describeCommand(program) {
   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 tree = describeCommandTree(program, { path, depth: opts.depth, probe });
     const out = outputOptions(self);
     if (!out.json && !out.compact && !opts.pretty) {
       process.stdout.write(`${renderText(tree)}
@@ -2942,12 +3494,11 @@ function describeCommand(program2) {
 }
 
 // src/commands/function.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { Command as Command9 } from "commander";
-var int5 = (v) => Number.parseInt(v, 10);
 function readCode(file) {
   try {
-    return readFileSync4(file === "-" ? 0 : file, "utf8");
+    return readFileSync3(file === "-" ? 0 : file, "utf8");
   } catch (err) {
     throw new InputError(
       `Cannot read ${file === "-" ? "stdin" : file}: ${err instanceof Error ? err.message : err}`
@@ -2969,8 +3520,21 @@ function parseJsonOption(raw, label) {
     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 parseJsonObjectOption(raw, label) {
+  const parsed = parseJsonOption(raw, label);
+  if (parsed === void 0) return void 0;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InputError(`--${label} must be a JSON object`);
+  }
+  return parsed;
+}
+function definitionFlags(c, includeType = true, flagSet = "all") {
+  if (flagSet === "openapi-import") return c;
+  if (flagSet === "openapi-update") {
+    return c.option("--name <n>", "tool name; required, update replaces the tool").option("--description <d>", "what it does; required, update replaces the tool");
+  }
+  const flags = 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("--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");
+  return includeType ? flags.option("--type <t>", "function | openapi", "function") : flags;
 }
 function parameterList(raw, label) {
   const parsed = parseJsonOption(raw, label);
@@ -2990,18 +3554,41 @@ function functionDefinitionFrom(file, opts) {
     dependenciesUrl: opts.indexUrl
   };
 }
-function functionCommand() {
-  const cmd = new Command9("function").description(
+function generationType(value) {
+  return oneOf("type", FunctionAiGenerationType)(value);
+}
+function generationRequestFrom(type, opts) {
+  const inputs = parameterList(opts.inputs, "inputs");
+  const outputs = parameterList(opts.outputs, "outputs");
+  if (type === "python_function_generator") {
+    if (!opts.query?.trim()) {
+      throw new InputError("--query is required for python_function_generator");
+    }
+    if (opts.code !== void 0) {
+      throw new InputError("--code only applies to metadata_param_generator");
+    }
+    return { query: opts.query, inputs, outputs };
+  }
+  if (opts.query !== void 0) {
+    throw new InputError("--query only applies to python_function_generator");
+  }
+  if (!opts.code) {
+    throw new InputError("--code <file> is required for metadata_param_generator");
+  }
+  return { code: readCode(opts.code), inputs, outputs };
+}
+function sandboxCommand() {
+  const cmd = new Command9("sandbox").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(
+  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", positiveInt("--timeout")).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") ?? {},
+      event: parseJsonObjectOption(opts.event, "event") ?? {},
       timeout: opts.timeout,
       dependencies: opts.dep,
       dependenciesUrl: opts.indexUrl,
@@ -3032,12 +3619,38 @@ function functionCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("template").description("The handler() skeleton to start from").option("--type <t>", "template type (python)", "python").action(async (opts, cmd2) => {
+  cmd.command("template").description("The handler() skeleton to start from").option(
+    "--type <t>",
+    "template type (python)",
+    oneOf("--type", FUNCTION_TEMPLATE_TYPES),
+    "python"
+  ).action(async (opts, cmd2) => {
     printJson(await clientFrom(cmd2).functions.template(opts.type), outputOptions(cmd2));
   });
+  cmd.command("generate <type>").description("Generate function code or parameter metadata with the platform's default LLM").option("--query <text>", "natural-language request (python_function_generator)").option("--code <file>", "existing code to analyse (metadata_param_generator; `-` reads stdin)").option("--inputs <json>", "known input parameters to constrain generation").option("--outputs <json>", "known output parameters to constrain generation").option(
+    "--timeout <s>",
+    "seconds to wait for the model (default 300; a default ingress answers 504 at 60)",
+    positiveInt("--timeout")
+  ).action(async (type, opts, cmd2) => {
+    const direction = generationType(type);
+    printJson(
+      await clientFrom(cmd2).functions.generate(
+        direction,
+        generationRequestFrom(direction, opts),
+        opts.timeout === void 0 ? {} : { timeoutMs: opts.timeout * 1e3 }
+      ),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("prompt <type>").description("Read the prompt template used for one Function AI generation direction").action(async (type, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).functions.promptTemplate(generationType(type)),
+      outputOptions(cmd2)
+    );
+  });
   groupChildren(cmd, {
-    READ: ["deps", "versions", "template"],
-    RUN: ["run", "infer-schema"]
+    READ: ["deps", "versions", "template", "prompt"],
+    RUN: ["run", "infer-schema", "generate"]
   });
   guide(
     cmd,
@@ -3048,7 +3661,7 @@ function functionCommand() {
           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.
+  \`print\` output as \`stdout\`. \`sandbox template\` prints the skeleton.
 
   READING THE ANSWER
   Code that raises still answers HTTP 200 \u2014 \`exit_code\` is the verdict and the
@@ -3061,24 +3674,168 @@ function functionCommand() {
   --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
+  sandbox deps                       what is already importable
+  sandbox run ./add.py --event ...   iterate here; nothing is kept
+  sandbox generate python_function_generator --query "..."
+                                     draft a handler with the platform model
   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`
+  function create ./add.py --toolbox the same code, now a registered Function Tool
+  function debug <tool-id> --toolbox try it before enabling or publishing
+  function enable <tool-id> --toolbox
+                                     a tool is off until enabled
+  toolbox publish <box-id>           execute needs a published box
+  function execute <tool-id> --toolbox
+                                     the call agents make
+
+  LONG JOBS
+  A registered function called through the toolbox is cut at about 30s whatever
+  its --timeout, and answers 200 with result: null. Keep long work on
+  \`sandbox run\`, which waits for the sandbox's own limit. The ingress still
+  answers 504 when its read timeout passes: 60s by default, unless the deploy
+  raises proxy-read-timeout.`
+  );
+  return group(cmd, "TOOLS & SKILLS");
+}
+
+// src/commands/mcp.ts
+import { Command as Command10, Option as Option3 } from "commander";
+var REDACTED = "<redacted>";
+var SECRET_NAME = /(^|[-_.])(authorization|auth|cookie|token|api[-_]?key|apikey|secret|pass|password|passwd|pwd|credentials?|private[-_]?key|access[-_]?key([-_]?id)?|secret[-_]?key|ak|sk)$/i;
+var SCHEMA_KEYS = /* @__PURE__ */ new Set(["inputSchema", "input_schema", "outputSchema", "output_schema"]);
+function redactUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return value;
+  }
+  let changed = false;
+  if (url.password) {
+    url.password = REDACTED;
+    changed = true;
+  }
+  for (const name of [...url.searchParams.keys()]) {
+    if (SECRET_NAME.test(name)) {
+      url.searchParams.set(name, REDACTED);
+      changed = true;
+    }
+  }
+  return changed ? url.toString() : value;
+}
+function redactArgs(args) {
+  return args.map((arg, i) => {
+    if (typeof arg !== "string") return arg;
+    const assigned = /^(-{0,2})([^=\s]+)=(.*)$/.exec(arg);
+    if (assigned?.[2] && SECRET_NAME.test(assigned[2])) {
+      return `${assigned[1]}${assigned[2]}=${REDACTED}`;
+    }
+    const previous = args[i - 1];
+    if (typeof previous === "string" && /^--?[^=\s]+$/.test(previous)) {
+      if (SECRET_NAME.test(previous.replace(/^-+/, ""))) return REDACTED;
+    }
+    return arg;
+  });
+}
+function maskValues(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  return Object.fromEntries(Object.keys(value).map((key) => [key, REDACTED]));
+}
+function redactMcpOutput(value) {
+  if (Array.isArray(value)) return value.map(redactMcpOutput);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => {
+      if (SCHEMA_KEYS.has(key)) return [key, item];
+      if (key === "headers" || key === "env") return [key, maskValues(item)];
+      if (key === "args" && Array.isArray(item)) return [key, redactArgs(item)];
+      if (typeof item === "string" && /url$/i.test(key)) return [key, redactUrl(item)];
+      if (item !== null && typeof item !== "object" && SECRET_NAME.test(key)) {
+        return [key, REDACTED];
+      }
+      return [key, redactMcpOutput(item)];
+    })
+  );
+}
+function mcpCommand() {
+  const cmd = new Command10("mcp").description(
+    "Registered MCP Servers: inspect their configuration and discover their tools"
+  );
+  cmd.command("list").description("List MCP Servers you can access").option("--name <text>", "filter by name").option("--source <text>", "filter by source").option("--category <text>", "filter by category").option("--status <status>", "filter by status (unpublish|published|offline|editing)").option("--create-user <text>", "filter by creator").option("--internal", "show only internal servers").addOption(
+    new Option3("--mode <mode>", "filter by connection mode").choices([
+      "sse",
+      "stream",
+      "stdio_uv",
+      "stdio_npx"
+    ])
+  ).addOption(
+    new Option3("--sort-by <field>", "sort field").choices(["update_time", "create_time", "name"])
+  ).addOption(new Option3("--sort-order <order>", "sort direction").choices(["asc", "desc"])).option(
+    "--limit <n>",
+    "page size (1-100)",
+    positiveInt("--limit", MAX_PAGE_SIZE),
+    DEFAULT_LIST_LIMIT
+  ).option("--page <n>", "page (1-based)", positiveInt("--page"), 1).option("--all", "return every accessible server (ignores --limit/--page defaults)").action(async (opts, command) => {
+    const paging = (flag) => opts.all && command.getOptionValueSource(flag) === "default" ? void 0 : opts[flag];
+    printJson(
+      redactMcpOutput(
+        await clientFrom(command).mcp.list({
+          page: paging("page"),
+          pageSize: paging("limit"),
+          sortBy: opts.sortBy,
+          sortOrder: opts.sortOrder,
+          name: opts.name,
+          source: opts.source,
+          category: opts.category,
+          status: opts.status,
+          createUser: opts.createUser,
+          isInternal: opts.internal || void 0,
+          mode: opts.mode,
+          all: opts.all || void 0
+        })
+      ),
+      outputOptions(command)
+    );
+  });
+  cmd.command("get <mcp-id>").description("Read one MCP Server's configuration and platform connection addresses").action(async (mcpId, _opts, command) => {
+    printJson(redactMcpOutput(await clientFrom(command).mcp.get(mcpId)), outputOptions(command));
+  });
+  cmd.command("tools <mcp-id>").description("List the MCP protocol tools a registered server advertises; does not invoke one").option("--draft", "list the tools of the draft configuration (needs view permission)").action(async (mcpId, opts, command) => {
+    printJson(
+      redactMcpOutput(
+        await clientFrom(command).mcp.tools(mcpId, { draft: opts.draft || void 0 })
+      ),
+      outputOptions(command)
+    );
+  });
+  groupChildren(cmd, { READ: ["list", "get", "tools"] });
+  guide(
+    cmd,
+    `WHAT THIS READS
+  These are registered MCP Servers in the execution factory, not Context Loader's
+  agent-facing MCP retrieval interface. \`mcp get\` includes the platform connection
+  addresses; \`mcp tools\` only discovers the remote tool schemas and does not call one.
+
+  ORDER OF WORK
+  mcp list                  choose an accessible server
+  mcp get <mcp-id>          inspect its configuration and connection addresses
+  mcp tools <mcp-id>        inspect tool names and input schemas
+
+  CREDENTIALS
+  Output masks header and env values, secrets in launch args and URLs, and
+  credential-named fields. Tool input schemas are printed as advertised.`
   );
   return group(cmd, "TOOLS & SKILLS");
 }
 
 // src/commands/model.ts
-import { Command as Command10 } from "commander";
-var int6 = (v) => Number.parseInt(v, 10);
+import { Command as Command11 } from "commander";
+var int5 = (v) => Number.parseInt(v, 10);
 async function resolveLlmModelName(client, model) {
   if (!/^\d+$/.test(model)) return model;
   const detail = await client.models.llm.get(model);
-  if (!detail?.model_name) throw new InputError(`No LLM found with id ${model}.`);
-  return detail.model_name;
+  const name = detail?.model_name ?? detail?.data?.model_name;
+  if (!name) throw new InputError(`No LLM found with id ${model}.`);
+  return name;
 }
 function addManagementCommands(parent, kind) {
   parent.command("add").description("Register a model (definition JSON via --body / --body-file)").option(
@@ -3093,6 +3850,14 @@ function addManagementCommands(parent, kind) {
   ).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));
   });
+  if (kind === "llm") {
+    parent.commands.find((c) => c.name() === "edit")?.addHelpText(
+      "after",
+      `
+Send the full definition, including "quota" (true | false): some platform
+versions answer an edit without it with HTTP 500 ModelFactory.Mydb.DataBase.ParameterError.`
+    );
+  }
   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));
   });
@@ -3104,11 +3869,11 @@ function addManagementCommands(parent, kind) {
   });
 }
 function modelCommand() {
-  const model = new Command10("model").description(
+  const model = new Command11("model").description(
     "Large and small models: chat, embeddings, rerank, defaults"
   );
   const llm = model.command("llm").description("Large language models");
-  llm.command("list").description("List LLM models \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) => {
+  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", int5, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int5, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.llm.list({
         name: opts.name,
@@ -3141,7 +3906,7 @@ function modelCommand() {
   });
   addManagementCommands(llm, "llm");
   const small = model.command("small").description("Small models (embedding / reranker)");
-  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) => {
+  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", int5, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int5, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.list({
         name: opts.name,
@@ -3203,24 +3968,152 @@ Examples:
 }
 
 // src/commands/resource.ts
-import { Command as Command11 } from "commander";
-var int7 = (v) => Number.parseInt(v, 10);
+import { Command as Command12 } from "commander";
+var int6 = (flag) => (v) => {
+  if (!/^-?\d+$/.test(v)) throw new InputError(`${flag} must be an integer (got '${v}')`);
+  const n = Number(v);
+  if (!Number.isSafeInteger(n)) throw new InputError(`${flag} must be an integer (got '${v}')`);
+  return n;
+};
+var nonNegativeInt2 = (flag) => (v) => {
+  const n = int6(flag)(v);
+  if (n < 0) throw new InputError(`${flag} must be 0 or greater (got '${v}')`);
+  return n;
+};
+var keepAliveSec = (v) => {
+  const n = int6("--keep-alive-sec")(v);
+  if (n < 60 || n > 3600) {
+    throw new InputError(`--keep-alive-sec must be an integer from 60 to 3600 (got '${v}')`);
+  }
+  return n;
+};
+var SORT_FIELDS = ["name", "create_time", "update_time"];
+var DIRECTIONS2 = ["asc", "desc"];
+function addResourceListOptions(cmd, categoryFlag) {
+  const alias = categoryFlag === "--category" ? "--type" : "--category";
+  return cmd.option("--catalog-id <id>", "filter by catalog id").option("--name <name>", "filter by name").option(
+    `${categoryFlag} <category>`,
+    `resource category: ${ResourceCategory.options.join(" | ")}`,
+    oneOf(categoryFlag, ResourceCategory.options)
+  ).option(
+    `${alias} <category>`,
+    `alias of ${categoryFlag}`,
+    oneOf(alias, ResourceCategory.options)
+  ).option(
+    "--status <status>",
+    `filter by status: ${ResourceStatus.options.join(" | ")}`,
+    oneOf("--status", ResourceStatus.options)
+  ).option(
+    "--enabled <bool>",
+    "filter by enabled state: true | false",
+    oneOf("--enabled", ["true", "false"])
+  ).option("--last-discover-status <status>", "filter by latest discovery status").option("--schema <name>", "filter by source schema").option("--limit <n>", "page size", int6("--limit"), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", nonNegativeInt2("--offset"), 0).option(
+    "--sort <field>",
+    `sort field: ${SORT_FIELDS.join(" | ")}`,
+    oneOf("--sort", SORT_FIELDS)
+  ).option(
+    "--direction <dir>",
+    `sort direction: ${DIRECTIONS2.join(" | ")}`,
+    oneOf("--direction", DIRECTIONS2)
+  );
+}
+function resourceListOptionsFrom(opts) {
+  return {
+    catalogId: opts.catalogId,
+    name: opts.name,
+    category: opts.category ?? opts.type,
+    status: opts.status,
+    enabled: opts.enabled === void 0 ? void 0 : opts.enabled === "true",
+    lastDiscoverStatus: opts.lastDiscoverStatus,
+    schema: opts.schema,
+    limit: opts.limit,
+    offset: opts.offset,
+    sort: opts.sort,
+    direction: opts.direction
+  };
+}
+function addResourceQueryOptions(cmd) {
+  return cmd.option("--limit <n>", "row limit", int6("--limit")).option("--offset <n>", "row offset", nonNegativeInt2("--offset")).option(
+    "--paging-mode <mode>",
+    "paging mode: single | cursor",
+    oneOf("--paging-mode", ["single", "cursor"])
+  ).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", keepAliveSec).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").option("--filter <json>", "Vega filter_condition JSON object").option("--sort <field:dir,...>", "sort fields, e.g. create_time:desc,id:asc").option("--output-fields <f1,f2>", "comma-separated fields to return").option(
+    "--binary-mode <mode>",
+    "Binary fields as metadata (byte length, default) | content (Base64)",
+    oneOf("--binary-mode", ["metadata", "content"])
+  ).option("--ignore-local-index", "read a table's source even when a local index is available");
+}
+function parseFilter(raw) {
+  let parsed;
+  try {
+    parsed = parseBigIntJSON(raw);
+  } catch {
+    throw new InputError("--filter must be valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new InputError("--filter must be a JSON object");
+  }
+  return parsed;
+}
+function parseSort(raw) {
+  const items = csv(raw) ?? [];
+  if (items.length === 0) throw new InputError("--sort must name at least one field");
+  return items.map((item) => {
+    const at = item.lastIndexOf(":");
+    const field = at === -1 ? item : item.slice(0, at);
+    const direction = at === -1 ? "asc" : item.slice(at + 1);
+    if (!field || direction !== "asc" && direction !== "desc") {
+      throw new InputError(`--sort entries must be field[:asc|desc] (got '${item}')`);
+    }
+    return { field, direction };
+  });
+}
+function resourceQueryOptionsFrom(opts, defaultLimit) {
+  if (opts.cursor) {
+    const initialOnly = [
+      ["--limit", opts.limit],
+      ["--offset", opts.offset],
+      ["--paging-mode", opts.pagingMode],
+      ["--keep-alive-sec", opts.keepAliveSec],
+      ["--filter", opts.filter],
+      ["--sort", opts.sort],
+      ["--output-fields", opts.outputFields],
+      ["--binary-mode", opts.binaryMode],
+      ["--ignore-local-index", opts.ignoreLocalIndex]
+    ].filter(([, value]) => value !== void 0);
+    if (initialOnly.length > 0) {
+      throw new InputError(
+        `--cursor cannot be combined with initial-query options (${initialOnly.map(([flag]) => flag).join(", ")})`
+      );
+    }
+    return {
+      cursor: opts.cursor,
+      ...opts.needTotal ? { needTotal: true } : {}
+    };
+  }
+  return {
+    limit: opts.limit ?? defaultLimit,
+    offset: opts.offset ?? 0,
+    pagingMode: opts.pagingMode,
+    keepAliveSec: opts.keepAliveSec,
+    needTotal: opts.needTotal ? true : void 0,
+    ...opts.filter !== void 0 ? { filterCondition: parseFilter(opts.filter) } : {},
+    ...opts.sort !== void 0 ? { sort: parseSort(opts.sort) } : {},
+    ...opts.outputFields !== void 0 ? { outputFields: csv(opts.outputFields) ?? [] } : {},
+    ...opts.binaryMode !== void 0 ? { binaryMode: opts.binaryMode } : {},
+    ...opts.ignoreLocalIndex ? { ignoreLocalIndex: true } : {}
+  };
+}
 function resourceCommand() {
-  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,
-      status: opts.status,
-      schema: opts.schema,
-      limit: opts.limit,
-      offset: opts.offset,
-      sort: opts.sort,
-      direction: opts.direction
-    });
+  const cmd = new Command12("resource").alias("res").description("Tables and views behind a network: find, inspect, sample, enable, disable");
+  addResourceListOptions(
+    cmd.command("list").description("List resources under a catalog"),
+    "--category"
+  ).action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).resource.list(resourceListOptionsFrom(opts));
     printJson(data, outputOptions(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) => {
+  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", int6("--limit"), DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
       catalogId: opts.catalogId,
@@ -3238,15 +4131,13 @@ function resourceCommand() {
       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,
-      pagingMode: opts.pagingMode,
-      keepAliveSec: opts.keepAliveSec,
-      cursor: opts.cursor,
-      needTotal: opts.needTotal
-    });
+  addResourceQueryOptions(
+    cmd.command("query <id>").description(`Fetch data rows from a resource (default limit ${DEFAULT_QUERY_LIMIT})`)
+  ).action(async (id, opts, cmd2) => {
+    const data = await clientFrom(cmd2).resource.query(
+      id,
+      resourceQueryOptionsFrom(opts, DEFAULT_QUERY_LIMIT)
+    );
     printJson(data, outputOptions(cmd2));
   });
   cmd.command("delete <id>").description("Delete a resource").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
@@ -3261,18 +4152,7 @@ function resourceCommand() {
 }
 
 // src/commands/skill.ts
-import { Command as Command12 } from "commander";
-var int8 = (v) => Number.parseInt(v, 10);
-var positiveInt = (flag) => (v) => {
-  if (!/^\d+$/.test(v)) {
-    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
-  }
-  const n = Number.parseInt(v, 10);
-  if (!Number.isSafeInteger(n) || n <= 0) {
-    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
-  }
-  return n;
-};
+import { Command as Command13 } from "commander";
 var MOCKED_EXIT_CODE = 125;
 function sandboxExitCode(result) {
   if (result?.mocked) return MOCKED_EXIT_CODE;
@@ -3280,31 +4160,70 @@ function sandboxExitCode(result) {
   if (!Number.isSafeInteger(code) || code < 0) return 1;
   return code > 255 ? 1 : code;
 }
-var SKILL_SOURCES = ["custom", "internal"];
+function metadataBody(body) {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    throw new InputError("update-metadata body must be a JSON object");
+  }
+  const b = body;
+  const missing = ["name", "description", "category"].filter(
+    (k) => typeof b[k] !== "string" || b[k].length === 0
+  );
+  if (missing.length > 0) {
+    throw new InputError(
+      `update-metadata replaces the metadata: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} required (non-empty string)`
+    );
+  }
+  if (b.source !== void 0 && !SKILL_SOURCES.includes(b.source)) {
+    throw new InputError(
+      `source must be one of: ${SKILL_SOURCES.join(" | ")} (got ${JSON.stringify(b.source)})`
+    );
+  }
+  const ext = b.extend_info;
+  if (ext !== void 0 && (ext === null || typeof ext !== "object" || Array.isArray(ext))) {
+    throw new InputError("extend_info must be a JSON object");
+  }
+  return b;
+}
 function checkSource(source) {
   if (source === void 0 || SKILL_SOURCES.includes(source)) return source;
   throw new InputError(`--source must be one of: ${SKILL_SOURCES.join(" | ")} (got '${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(
+  const cmd = new Command13("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);
+  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--category <s>", "filter by category").option("--create-user <s>", "filter by creator").option(
+    "--sort-by <f>",
+    "create_time | update_time | name (service default update_time)",
+    oneOf("--sort-by", ["create_time", "update_time", "name"])
+  ).option("--sort-order <o>", "asc | desc", oneOf("--sort-order", ["asc", "desc"])).option(
+    "--limit <n>",
+    `page size, 1-${MAX_PAGE_SIZE}`,
+    positiveInt("--limit", MAX_PAGE_SIZE),
+    DEFAULT_LIST_LIMIT
+  ).option("--page <n>", "page (1-based)", positiveInt("--page"), 1).option("--all", "return every skill, ignoring page size");
+  const listFilters = (opts) => ({
+    name: opts.name,
+    category: opts.category,
+    createUser: opts.createUser,
+    sortBy: opts.sortBy,
+    sortOrder: opts.sortOrder,
+    pageSize: opts.limit,
+    page: opts.page,
+    all: opts.all
+  });
   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) => {
+  ).option(
+    "--status <s>",
+    "unpublish | published | offline | editing",
+    oneOf("--status", ["unpublish", "published", "offline", "editing"])
+  ).action(async (opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).skills.list({
-        name: opts.name,
-        source: opts.source,
-        status: opts.status,
-        createUser: opts.createUser,
-        pageSize: opts.limit,
-        page: opts.page
-      }),
+      await clientFrom(cmd2).skills.list({ ...listFilters(opts), status: opts.status }),
       outputOptions(cmd2)
     );
   });
@@ -3314,15 +4233,7 @@ function skillCommand() {
   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)
-    );
+    printJson(await clientFrom(cmd2).skills.market(listFilters(opts)), 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));
@@ -3425,17 +4336,16 @@ ${files.length} files, ${bytes} B
   cmd.command("history <skill-id>").description("Show a skill's version history").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.history(id), outputOptions(cmd2));
   });
-  cmd.command("set-status <skill-id> <status>").description("Change status: unpublish | published | offline").action(async (id, status2, _opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).skills.setStatus(id, status2),
-      outputOptions(cmd2)
-    );
+  cmd.command("set-status <skill-id> <status>").description(`Publish or take down a skill: ${SKILL_STATUSES.join(" | ")}`).action(async (id, status2, _opts, cmd2) => {
+    const target = oneOf("<status>", SKILL_STATUSES)(status2);
+    printJson(await clientFrom(cmd2).skills.setStatus(id, target), outputOptions(cmd2));
   });
-  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
+  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--category <s>", "category (service default other_category)").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
     const extendInfo = opts.extendInfo ? parseBigIntJSON(opts.extendInfo) : void 0;
     printJson(
       await clientFrom(cmd2).skills.register(dir, {
         source: checkSource(opts.source),
+        category: opts.category,
         extendInfo
       }),
       outputOptions(cmd2)
@@ -3450,22 +4360,26 @@ ${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(
+  cmd.command("update-metadata <skill-id>").description(
+    "Replace a skill's metadata (--body / --body-file JSON: name, description, category required)"
+  ).option(
     "--body <json>",
-    "metadata JSON \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (execution-factory)"
+    "{name, description, category, source?: custom|internal, extend_info?} \u2014 a full overwrite"
   ).option("--body-file <path>", "read metadata JSON from a file").action(async (skillId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).skills.updateMetadata(skillId, readBody(opts)),
+      await clientFrom(cmd2).skills.updateMetadata(skillId, metadataBody(readBody(opts))),
       outputOptions(cmd2)
     );
   });
   cmd.command("update-package <skill-id> <directory>").description("Replace a skill's package from a local directory").action(async (skillId, dir, _o, cmd2) => {
     printJson(await clientFrom(cmd2).skills.updatePackage(skillId, dir), outputOptions(cmd2));
   });
-  cmd.command("republish <skill-id>").description("Republish a previous skill version").requiredOption("--version <v>", "version to republish").action(async (skillId, opts, cmd2) => {
+  cmd.command("republish <skill-id>").description(
+    "Copy a historical version back into the draft (publishes nothing; see publish-history)"
+  ).requiredOption("--version <v>", "historical version to restore into the draft").action(async (skillId, opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.republish(skillId, opts.version), outputOptions(cmd2));
   });
-  cmd.command("publish-history <skill-id>").description("Publish a historical skill version").requiredOption("--version <v>", "version to publish").action(async (skillId, opts, cmd2) => {
+  cmd.command("publish-history <skill-id>").description("Publish a historical skill version directly").requiredOption("--version <v>", "version to publish").action(async (skillId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).skills.publishHistory(skillId, opts.version),
       outputOptions(cmd2)
@@ -3506,30 +4420,87 @@ PUBLISHED VS DRAFT
 
 AUTHORING
   register <dir> zips and registers; update-package replaces the files; update-metadata
-  changes only the metadata. set-status and republish move versions around.`
+  changes only the metadata (a full overwrite: name, description, category required).
+  set-status publishes or takes down the current version. republish copies a historical
+  version back into the draft and publishes nothing; publish-history publishes one.`
   );
   return group(cmd, "TOOLS & SKILLS");
 }
 
 // src/commands/toolbox.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14, Option as Option4 } from "commander";
 import yaml from "js-yaml";
-var int9 = (v) => Number.parseInt(v, 10);
+var SORT_ORDERS = ["asc", "desc"];
+var TOOLBOX_STATUSES = ["unpublish", "published", "offline"];
+function toolCallFailed(result) {
+  if (!result || typeof result !== "object") return false;
+  const { status_code: status2, error } = result;
+  if (typeof status2 === "number" && status2 >= 400) return true;
+  return typeof error === "string" ? error.length > 0 : error !== void 0 && error !== null;
+}
+function pathParams(parsed) {
+  if (parsed === void 0) return void 0;
+  for (const [k, v] of Object.entries(parsed)) {
+    if (typeof v !== "string") {
+      throw new InputError(
+        `--path values must be strings (path parameter '${k}' is ${v === null ? "null" : Array.isArray(v) ? "an array" : typeof v})`
+      );
+    }
+  }
+  return parsed;
+}
+function globalParameterOption(raw) {
+  const parsed = parseJsonObjectOption(raw, "global-parameter");
+  if (parsed === void 0) return void 0;
+  for (const k of ["name", "description", "in", "type"]) {
+    if (typeof parsed[k] !== "string" || !parsed[k]) {
+      throw new InputError(`--global-parameter needs a non-empty string '${k}'`);
+    }
+  }
+  return parsed;
+}
 function toolboxCommand() {
-  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) => {
+  const cmd = new Command14("toolbox").description("Toolboxes: group tools into one publishable box");
+  cmd.command("list").description("List toolboxes \u2192 {data, total, page, page_size, has_next}; the id is `box_id`").option("--name <s>", "filter by toolbox name").addOption(new Option4("--keyword <s>", "deprecated: use --name").hideHelp()).option("--status <s>", "unpublish | published | offline", oneOf("--status", TOOLBOX_STATUSES)).option("--category <s>", "filter by category").option(
+    "--metadata-type <t>",
+    "openapi | function",
+    oneOf("--metadata-type", ["openapi", "function"])
+  ).option("--create-user <s>", "filter by creator").option("--release-user <s>", "filter by publisher").option(
+    "--sort-by <f>",
+    "create_time | update_time | name (service default update_time)",
+    oneOf("--sort-by", ["create_time", "update_time", "name"])
+  ).option("--sort-order <o>", "asc | desc", oneOf("--sort-order", SORT_ORDERS)).option(
+    "--limit <n>",
+    `page size, 1-${MAX_PAGE_SIZE}`,
+    positiveInt("--limit", MAX_PAGE_SIZE),
+    DEFAULT_LIST_LIMIT
+  ).option("--page <n>", "page (1-based)", positiveInt("--page"), 1).option("--all", "return every toolbox, ignoring page size").addOption(new Option4("--offset <n>", "removed: use --page").hideHelp()).action(async (opts, cmd2) => {
+    if (opts.offset !== void 0) {
+      throw new InputError("--offset is not supported: the service pages by --page (1-based)");
+    }
+    if (opts.keyword !== void 0 && opts.name !== void 0) {
+      throw new InputError("--keyword is a deprecated alias of --name; pass only --name");
+    }
     printJson(
       await clientFrom(cmd2).toolboxes.list({
-        keyword: opts.keyword,
-        limit: opts.limit,
-        offset: opts.offset
+        name: opts.name ?? opts.keyword,
+        status: opts.status,
+        category: opts.category,
+        metadataType: opts.metadataType,
+        createUser: opts.createUser,
+        releaseUser: opts.releaseUser,
+        sortBy: opts.sortBy,
+        sortOrder: opts.sortOrder,
+        pageSize: opts.limit,
+        page: opts.page,
+        all: opts.all
       }),
       outputOptions(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) => {
+  ).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").option("--category <c>", "box category (service default other_category)").action(async (opts, cmd2) => {
     if (opts.type !== "openapi" && opts.type !== "function") {
       throw new InputError("--type must be openapi or function");
     }
@@ -3541,7 +4512,8 @@ function toolboxCommand() {
         name: opts.name,
         serviceUrl: opts.serviceUrl,
         description: opts.description,
-        metadataType: opts.type
+        metadataType: opts.type,
+        category: opts.category
       }),
       outputOptions(cmd2)
     );
@@ -3549,20 +4521,37 @@ function toolboxCommand() {
   cmd.command("publish <box-id>").description("Publish a toolbox").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).toolboxes.publish(id), outputOptions(cmd2));
   });
-  cmd.command("unpublish <box-id>").description("Unpublish a toolbox (status=draft)").action(async (id, _opts, cmd2) => {
+  cmd.command("unpublish <box-id>").description("Take a published toolbox down (status=offline)").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).toolboxes.unpublish(id), outputOptions(cmd2));
   });
   cmd.command("delete <box-id>").description("Delete a toolbox").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).toolboxes.delete(id), outputOptions(cmd2));
   });
-  cmd.command("export <box-id>").description("Export a toolbox config to a local .adp file").requiredOption("-o, --out <file>", "output .adp path").option("--type <t>", "impex type: toolbox | mcp | operator", "toolbox").action(async (boxId, opts, cmd2) => {
+  cmd.command("export <box-id>").description("Export a toolbox config to a local .adp file").requiredOption("-o, --out <file>", "output .adp path").option(
+    "--type <t>",
+    "impex type: toolbox | mcp | operator",
+    oneOf("--type", IMPEX_TYPES),
+    "toolbox"
+  ).action(async (boxId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.export(boxId, opts.out, opts.type),
       outputOptions(cmd2)
     );
   });
-  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));
+  cmd.command("import <file>").description("Import a toolbox config from a local .adp file").option(
+    "--type <t>",
+    "impex type: toolbox | mcp | operator",
+    oneOf("--type", IMPEX_TYPES),
+    "toolbox"
+  ).option(
+    "--mode <m>",
+    "create (fail if it exists; service default) | upsert (update if it exists)",
+    oneOf("--mode", ["create", "upsert"])
+  ).action(async (file, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.import(file, opts.type, opts.mode),
+      outputOptions(cmd2)
+    );
   });
   groupChildren(cmd, {
     READ: ["list", "export"],
@@ -3575,41 +4564,81 @@ function toolboxCommand() {
   --type function  its tools are platform functions, no service URL to give
 
   ORDER OF WORK
-  toolbox create --name "<n>"        an empty box, in draft
+  toolbox create --name "<n>"        an empty box, not yet published
   tool create ./add.py --toolbox     a function tool, or --type openapi for a spec
+  tool debug <tool-id>               call it while building, before enable/publish
   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
+  toolbox publish <box-id>           execute needs a published box
+  tool execute <tool-id>             call an enabled tool in a published box
 
-  Publishing the box is about the market, not about calling: an enabled tool in
-  an unpublished box executes. \`tool enable\` is the gate.
+  Both gates apply to \`execute\`: the tool must be enabled and the box published \u2014
+  an unpublished or offline box answers 400 ToolNotAvailable. \`debug\` skips both.
 
   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 in a box: add one from code or a spec, enable it, call it"
+  return buildToolCommand({ name: "tool", createCommand: "create", includeUpload: true });
+}
+function functionToolCommand() {
+  return buildToolCommand({
+    name: "function",
+    metadataType: "function",
+    createCommand: "create",
+    includeUpload: false
+  });
+}
+function apiToolCommand() {
+  return buildToolCommand({
+    name: "api",
+    metadataType: "openapi",
+    createCommand: "import",
+    includeUpload: false
+  });
+}
+function buildToolCommand(config) {
+  const kind = config.metadataType;
+  const kindName = kind === "function" ? "Function Tools" : kind === "openapi" ? "OpenAPI Tools" : "Tools";
+  const cmd = new Command14(config.name).description(
+    kind ? `${kindName} in a toolbox: add one, enable it, and call it` : "Advanced 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) => {
+  cmd.command("list").description(kind ? `List ${kindName.toLowerCase()} in a toolbox` : "List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option(
+    "--limit <n>",
+    `page size, 1-${MAX_PAGE_SIZE} (backend default 10)`,
+    positiveInt("--limit", MAX_PAGE_SIZE)
+  ).option("--page <n>", "page (1-based; backend default 1)", positiveInt("--page")).option("--all", "return every tool, ignoring page size").option("--name <s>", "filter by tool name").option(
+    "--status <s>",
+    "enabled | disabled",
+    oneOf("--status", ["enabled", "disabled"])
+  ).option(
+    "--sort-by <f>",
+    "create_time | update_time | tool_name (service default create_time)",
+    oneOf("--sort-by", ["create_time", "update_time", "tool_name"])
+  ).option("--sort-order <o>", "asc | desc", oneOf("--sort-order", SORT_ORDERS)).option("--user-id <id>", "filter by creator").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
         page: opts.page,
         pageSize: opts.limit,
-        all: opts.all
+        all: opts.all,
+        name: opts.name,
+        status: opts.status,
+        sortBy: opts.sortBy,
+        sortOrder: opts.sortOrder,
+        userId: opts.userId
       }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("enable <tool-ids...>").description("Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
+  cmd.command("enable <tool-ids...>").description(kind ? `Enable one or more ${kindName.toLowerCase()}` : "Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.setToolStatus(opts.toolbox, toolIds, "enabled"),
       outputOptions(cmd2)
     );
   });
-  cmd.command("disable <tool-ids...>").description("Disable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
+  cmd.command("disable <tool-ids...>").description(
+    kind ? `Disable one or more ${kindName.toLowerCase()}` : "Disable one or more tools"
+  ).requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.setToolStatus(opts.toolbox, toolIds, "disabled"),
       outputOptions(cmd2)
@@ -3618,40 +4647,65 @@ function toolCommand() {
   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);
+  ).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; the client waits this long plus a margin (sandbox max when omitted)",
+    positiveInt("--timeout")
+  );
   const parseJson = (s, label) => {
-    if (!s) return void 0;
+    if (s === void 0) return void 0;
+    let parsed;
     try {
-      return parseBigIntJSON(s);
+      parsed = parseBigIntJSON(s);
     } catch {
       throw new InputError(`--${label} must be valid JSON`);
     }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new InputError(`--${label} must be a JSON object`);
+    }
+    return parsed;
   };
   const buildEnvelope = (opts) => ({
     body: opts.body ? parseBigIntJSON(opts.body) : void 0,
     header: parseJson(opts.header, "header"),
     query: parseJson(opts.query, "query"),
-    path: parseJson(opts.path, "path"),
+    path: pathParams(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("debug <tool-id>").description("Invoke a tool that is not enabled yet")
+    cmd.command("execute <tool-id>").description(
+      kind ? `Invoke an enabled ${kindName.slice(0, -1)} in a published toolbox` : "Invoke an enabled tool in a published toolbox"
+    )
   ).action(async (toolId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).toolboxes.debug(opts.toolbox, toolId, buildEnvelope(opts)),
-      outputOptions(cmd2)
+    const result = await clientFrom(cmd2).toolboxes.execute(
+      opts.toolbox,
+      toolId,
+      buildEnvelope(opts)
     );
+    printJson(result, outputOptions(cmd2));
+    if (toolCallFailed(result)) process.exitCode = 1;
+  });
+  invokeOpts(
+    cmd.command("debug <tool-id>").description(
+      kind ? `Invoke a ${kindName.slice(0, -1)} before it is enabled or its toolbox published` : "Invoke a tool before it is enabled or its toolbox published"
+    )
+  ).action(async (toolId, opts, cmd2) => {
+    const result = await clientFrom(cmd2).toolboxes.debug(opts.toolbox, toolId, buildEnvelope(opts));
+    printJson(result, outputOptions(cmd2));
+    if (toolCallFailed(result)) process.exitCode = 1;
+  });
+  const commonToolFields = (opts) => ({
+    useRule: opts.useRule,
+    globalParameters: globalParameterOption(opts.globalParameter),
+    extendInfo: parseJsonObjectOption(opts.extendInfo, "extend-info")
   });
+  const toolExtraFlags = (c) => c.option("--use-rule <s>", "usage rule carried onto the tool").option(
+    "--global-parameter <json>",
+    "one parameter fixed onto every call: {name,description,in,type,required?,value?}"
+  ).option("--extend-info <json>", "extra metadata as a JSON object");
   const toolFrom = (file, opts) => {
-    if (opts.type === "openapi") {
+    const metadataType = kind ?? opts.type;
+    if (metadataType === "openapi") {
       let data;
       try {
         data = yaml.load(readCode(file));
@@ -3660,19 +4714,23 @@ function toolCommand() {
           `${file} is not valid JSON or YAML: ${err instanceof Error ? err.message : err}`
         );
       }
-      return { metadataType: "openapi", data, useRule: opts.useRule };
+      return { metadataType: "openapi", data, ...commonToolFields(opts) };
     }
-    if (opts.type !== "function") throw new InputError("--type must be function or openapi");
+    if (metadataType !== "function") throw new InputError("--type must be function or openapi");
     return {
       metadataType: "function",
       function: functionDefinitionFrom(file, opts),
-      useRule: opts.useRule
+      ...commonToolFields(opts)
     };
   };
   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")
+    toolExtraFlags(
+      cmd.command(`${config.createCommand} <file>`).description(
+        kind === "function" ? "Register a Function Tool from code" : kind === "openapi" ? "Import OpenAPI Tools from a JSON or YAML specification" : "Create a tool from code (or a spec)"
+      ).requiredOption("--toolbox <box-id>", "target toolbox id")
+    ),
+    !kind,
+    kind === "openapi" ? "openapi-import" : "all"
   ).action(async (file, opts, cmd2) => {
     const result = await clientFrom(cmd2).toolboxes.createTool(
       opts.toolbox,
@@ -3681,11 +4739,19 @@ function toolCommand() {
     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) => {
+  cmd.command("get <tool-id>").description(
+    kind ? `One ${kindName.slice(0, -1)} in full: metadata, parameters, usage rule` : "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")
+    toolExtraFlags(
+      cmd.command("update <tool-id> <file>").description(
+        kind ? `Replace a ${kindName.slice(0, -1)} definition; the id survives and an enabled tool stays enabled` : "Replace a tool's definition; the id survives and an enabled tool stays enabled"
+      ).requiredOption("--toolbox <box-id>", "toolbox id")
+    ),
+    !kind,
+    kind === "openapi" ? "openapi-update" : "all"
   ).action(async (toolId, file, opts, cmd2) => {
     if (!opts.name || !opts.description) {
       throw new InputError(
@@ -3701,32 +4767,72 @@ function toolCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("delete <tool-ids...>").description("Delete tools from a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("-y, --yes", "skip confirmation").action(async (toolIds, opts, cmd2) => {
+  cmd.command("delete <tool-ids...>").description(
+    kind ? `Delete ${kindName.toLowerCase()} from a toolbox` : "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)
-    );
-  });
+  if (config.includeUpload) {
+    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>",
+      "openapi | function",
+      oneOf("--metadata-type", TOOL_METADATA_TYPES),
+      "openapi"
+    ).action(async (file, opts, cmd2) => {
+      printJson(
+        await clientFrom(cmd2).toolboxes.upload(opts.toolbox, file, opts.metadataType),
+        outputOptions(cmd2)
+      );
+    });
+  }
   groupChildren(cmd, {
     READ: ["list", "get"],
     RUN: ["execute", "debug"],
-    WRITE: ["create", "update", "delete", "enable", "disable", "upload"]
+    WRITE: [
+      config.createCommand,
+      "update",
+      "delete",
+      "enable",
+      "disable",
+      ...config.includeUpload ? ["upload"] : []
+    ]
   });
+  if (kind) {
+    guide(
+      cmd,
+      `WHAT THIS GROUP MANAGES
+  ${kind === "function" ? "Function Tools keep Python handler code in a Toolbox." : "OpenAPI Tools keep operations imported from a JSON or YAML specification."}
+  \`--toolbox\` is always the container id; create it with \`toolbox create\`.
+
+  ORDER OF WORK
+  toolbox create --name "<n>"${kind === "openapi" ? " --service-url <url>" : " --type function"}
+  ${config.name} ${config.createCommand} <file> --toolbox <box-id>
+  ${config.name} debug <tool-id> --toolbox <box-id>     try it before enable/publish
+  ${config.name} enable <tool-id> --toolbox <box-id>
+  toolbox publish <box-id>
+  ${config.name} execute <tool-id> --toolbox <box-id>
+
+  \`execute\` needs the tool enabled and the box published; an unpublished or offline
+  box answers 400 ToolNotAvailable. \`debug\` works before either.
+  \`${config.name} list\` does not check the box: --toolbox must name a box whose
+  metadata type is ${kind}.${kind === "function" ? `
+  execute and debug go through the toolbox proxy, which cuts a function at about
+  30s whatever --timeout says, answering 200 with result: null. Run long jobs
+  with \`sandbox run\`.` : ""}`
+    );
+  }
   return group(cmd, "TOOLS & SKILLS");
 }
 
 // src/commands/trace.ts
-import { readFileSync as readFileSync6, writeFileSync } from "fs";
-import { Command as Command14 } from "commander";
+import { readFileSync as readFileSync5, writeFileSync } from "fs";
+import { Command as Command15 } from "commander";
 
 // src/bkn-trace/schema-validate.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { extname } from "path";
 import yaml2 from "js-yaml";
 import { z } from "zod";
@@ -3763,7 +4869,7 @@ var DiagnosisRule = z.object({
   params: z.record(z.string(), z.unknown()).optional()
 });
 function parseFile(file) {
-  const text = readFileSync5(file, "utf8");
+  const text = readFileSync4(file, "utf8");
   const ext = extname(file).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") return yaml2.load(text);
   return parseBigIntJSON(text);
@@ -3807,28 +4913,30 @@ function renderPayload(payload) {
   return `[omitted] ${payload.omitted_reason ?? "unknown"}`;
 }
 function renderTechnicalTraceDetail(detail) {
+  const summary = detail?.summary;
   const lines = [
-    `Trace: ${detail.summary.trace_id}`,
-    `Status: ${detail.summary.status}`,
-    `Request: ${detail.summary.request_id || "-"}`,
-    `Question: ${detail.summary.question_preview || "-"}`,
-    `Result: ${detail.summary.result_preview || "-"}`,
-    `Service: ${detail.summary.root_service || "-"}`,
-    `Spans: ${detail.graph?.data.nodes.length ?? 0}`
+    `Trace: ${summary?.trace_id || detail?.graph?.trace_id || "-"}`,
+    `Status: ${summary?.status || detail?.graph?.status || "-"}`,
+    `Request: ${summary?.request_id || "-"}`,
+    `Question: ${summary?.question_preview || "-"}`,
+    `Result: ${summary?.result_preview || "-"}`,
+    `Service: ${summary?.root_service || "-"}`,
+    `Spans: ${detail?.graph?.data?.nodes?.length ?? 0}`
   ];
-  if (detail.partial) {
+  if (detail?.partial) {
     lines.push(`Partial: ${(detail.partial_reasons ?? []).join(", ") || "yes"}`);
   }
-  for (const operation of detail.operations) {
+  for (const operation of detail?.operations ?? []) {
+    const fact = operation?.fact ?? {};
     lines.push(
       "",
-      `${operation.fact.tool_name} \xB7 ${operation.fact.operation_id} \xB7 attempt ${operation.fact.attempt} \xB7 ${operation.state}`,
-      `Source: ${operation.fact.protocol}/${operation.fact.source_module}`,
-      `Input: ${renderPayload(operation.fact.input)}`
+      `${fact.tool_name ?? "-"} \xB7 ${fact.operation_id ?? "-"} \xB7 attempt ${fact.attempt ?? "-"} \xB7 ${operation?.state ?? "-"}`,
+      `Source: ${fact.protocol ?? "-"}/${fact.source_module ?? "-"}`,
+      `Input: ${renderPayload(fact.input)}`
     );
-    if (operation.fact.output) lines.push(`Output: ${renderPayload(operation.fact.output)}`);
-    if (operation.fact.error) lines.push(`Error: ${renderPayload(operation.fact.error)}`);
-    if (operation.partial_reasons?.length) {
+    if (fact.output) lines.push(`Output: ${renderPayload(fact.output)}`);
+    if (fact.error) lines.push(`Error: ${renderPayload(fact.error)}`);
+    if (operation?.partial_reasons?.length) {
       lines.push(`Partial: ${operation.partial_reasons.join(", ")}`);
     }
   }
@@ -3836,7 +4944,7 @@ function renderTechnicalTraceDetail(detail) {
 `;
 }
 function traceCommand() {
-  const cmd = new Command14("trace").description(
+  const cmd = new Command15("trace").description(
     "Inspect what an agent actually did, and diagnose bad answers"
   );
   cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
@@ -3984,7 +5092,8 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("search").description("List authorized technical traces \u2192 {entries, total, next_cursor, partial}").option("--limit <n>", "page size, 1..200", (value) => Number.parseInt(value, 10)).option("--cursor <cursor>", "opaque pagination cursor").option("--from <time>", "started at or after this RFC3339 timestamp").option("--to <time>", "started at or before this RFC3339 timestamp").option("--status <status>", "execution status").option("--service <service>", "exact producing service").option("--tool <tool>", "exact root tool").option("--trace-id <id>", "exact Trace ID").option("--error-keyword <text>", "case-insensitive error text").option("--conversation-id <id>", "exact conversation ID").option("--interaction-id <id>", "exact interaction ID").action(async (opts, cmd2) => {
+  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("--agent-or-app <name>", "agent or application").option("--trace-id <id>", "exact Trace ID").option("--keyword <text>", "trace, request, operation, or error keyword").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) => {
+    const opts = cmd2.optsWithGlobals();
     printJson(
       await clientFrom(cmd2).trace.search({
         limit: opts.limit,
@@ -3994,7 +5103,9 @@ function traceCommand() {
         status: opts.status,
         service: opts.service,
         tool: opts.tool,
+        agentOrApp: opts.agentOrApp,
         traceId: opts.traceId,
+        keyword: opts.keyword,
         errorKeyword: opts.errorKeyword,
         conversationId: opts.conversationId,
         interactionId: opts.interactionId
@@ -4011,15 +5122,15 @@ function traceCommand() {
     else console.log(renderReportMarkdown(report));
   });
   cmd.command("scan <conversation-ids>").description("Batch-diagnose several conversations (comma-joined) + aggregate findings").option("--llm", "hybrid mode (rubric + synthesizer) per trace via local `claude`").action(async (ids, opts, cmd2) => {
-    const list = ids.split(",").map((s) => s.trim()).filter(Boolean);
+    const list2 = ids.split(",").map((s) => s.trim()).filter(Boolean);
     printJson(
-      await clientFrom(cmd2).trace.scan(list, { llm: Boolean(opts.llm) }),
+      await clientFrom(cmd2).trace.scan(list2, { llm: Boolean(opts.llm) }),
       outputOptions(cmd2)
     );
   });
   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(readFileSync6(queriesFile, "utf8"));
+    const raw = parseBigIntJSON(readFileSync5(queriesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     if (opts.out) {
       writeFileSync(opts.out, stringifyBigIntJSON({ cases }, 2));
@@ -4064,14 +5175,117 @@ MANAGED LIFECYCLE
 }
 
 // src/commands/vega.ts
-import { Command as Command15 } from "commander";
-var int10 = (value) => {
+import { Command as Command16 } from "commander";
+
+// src/utils/build-progress.ts
+var LOG_EVERY_MS = 1e4;
+function formatDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1e3));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+function describeBuildProgress(task, elapsedMs, etaMs) {
+  const state = task.status ?? "unknown";
+  const parts = [`BuildTask ${task.id}: ${state}`];
+  const total = task.total_count;
+  const synced = task.synced_count;
+  if (typeof synced === "number" && typeof total === "number" && total > 0) {
+    const pct = Math.min(100, Math.floor(synced / total * 100));
+    parts.push(`${synced.toLocaleString("en-US")}/${total.toLocaleString("en-US")} rows (${pct}%)`);
+  } else if (typeof synced === "number") {
+    parts.push(`${synced.toLocaleString("en-US")} rows`);
+  }
+  parts.push(`${formatDuration(elapsedMs)} elapsed`);
+  if (etaMs !== void 0) parts.push(`~${formatDuration(etaMs)} left`);
+  return parts.join(" \xB7 ");
+}
+function buildProgressReporter(out = process.stderr, now = Date.now) {
+  const start = now();
+  let baseline;
+  let lastState;
+  let lastLine = "";
+  let lastLoggedAt = Number.NEGATIVE_INFINITY;
+  let open = false;
+  const eta = (task, at) => {
+    const synced = task.synced_count;
+    const total = task.total_count;
+    if (typeof synced !== "number" || typeof total !== "number" || total <= 0) return void 0;
+    if (task.status !== "running") return void 0;
+    if (!baseline) {
+      baseline = { at, synced };
+      return void 0;
+    }
+    const rate = (synced - baseline.synced) / (at - baseline.at);
+    return rate > 0 ? Math.max(0, (total - synced) / rate) : void 0;
+  };
+  return {
+    update(task) {
+      const at = now();
+      const state = task.status ?? "";
+      const line = describeBuildProgress(task, at - start, eta(task, at));
+      if (out.isTTY) {
+        out.write(`\r\x1B[2K${line}`);
+        open = true;
+      } else if (state !== lastState || line !== lastLine && at - lastLoggedAt >= LOG_EVERY_MS) {
+        out.write(`${line}
+`);
+        lastLoggedAt = at;
+      }
+      lastState = state;
+      lastLine = line;
+    },
+    end() {
+      if (open) out.write("\n");
+      open = false;
+    }
+  };
+}
+
+// src/commands/vega.ts
+var int7 = (value) => {
   const parsed = Number(value);
   if (!Number.isSafeInteger(parsed)) {
     throw new InputError(`expected an integer, received "${value}"`);
   }
   return parsed;
 };
+var nonNegativeInt3 = (flag) => (value) => {
+  const parsed = Number(value);
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(parsed)) {
+    throw new InputError(`${flag} must be an integer 0 or greater (got '${value}')`);
+  }
+  return parsed;
+};
+var seconds = (value) => {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new InputError(
+      `--timeout must be a whole number of seconds (0 = no limit), received "${value}"`
+    );
+  }
+  return parsed;
+};
+async function waitAndReport(cmd, wait) {
+  const progress = buildProgressReporter();
+  let task;
+  try {
+    task = await wait((t) => progress.update(t));
+  } catch (err) {
+    progress.end();
+    if (err instanceof WaitTimeoutError) printJson(err.last, outputOptions(cmd));
+    throw err;
+  }
+  progress.end();
+  printJson(task, outputOptions(cmd));
+  if (isBuildTaskUnsuccessful(task)) {
+    const reason = task.error_msg;
+    throw new Error(
+      `BuildTask ${task.id} ended ${buildTaskState(task)}${typeof reason === "string" && reason ? `: ${reason}` : "."}`
+    );
+  }
+}
 var expectedUpdateTime = (value) => {
   const parsed = Number(value);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
@@ -4115,6 +5329,12 @@ var parseJsonArray = (value, flag) => {
   }
   return parsed;
 };
+var parseResourceProperties = (value) => parseJsonArray(value, "--schema-definition").map((property) => {
+  if (typeof property.name !== "string" || property.name.length === 0) {
+    throw new InputError("--schema-definition properties must have a non-empty string name");
+  }
+  return property;
+});
 var healthCheckSchedule = (mode, cronExpr) => {
   if (!mode) {
     if (cronExpr) throw new InputError("a health-check cron expression requires enabled mode");
@@ -4255,7 +5475,7 @@ var semanticTaskSort = (raw) => {
   }
   return parsed.data;
 };
-var sortDirection = (raw) => {
+var sortDirection2 = (raw) => {
   if (raw === void 0) return void 0;
   const parsed = SortDirection.safeParse(raw);
   if (!parsed.success) {
@@ -4265,12 +5485,48 @@ var sortDirection = (raw) => {
   }
   return parsed.data;
 };
+var connectorMode = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = ConnectorMode.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid connector mode "${raw}"; expected one of ${ConnectorMode.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var connectorCategory = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = ConnectorCategory.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid connector category "${raw}"; expected one of ${ConnectorCategory.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
 function vegaCommand() {
-  const vega = new Command15("vega").description(
+  const vega = new Command16("vega").description(
     "Data sources: catalogs, connectors, SQL, index builds"
   );
   const catalog = vega.command("catalog").description("Catalog entries");
-  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", 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) => {
+  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 0).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option(
+    "--type <type>",
+    "filter by catalog type: physical | logical",
+    oneOf("--type", ["physical", "logical"])
+  ).option("--connector-type <type>", "filter by connector type").option("--enabled <bool>", "filter by enabled state: true | false", bool).option(
+    "--health-check-status <s>",
+    `filter by health status: ${CatalogHealthCheckStatus.options.join(" | ")}`,
+    oneOf("--health-check-status", CatalogHealthCheckStatus.options)
+  ).option(
+    "--sort <field>",
+    "sort field: name | create_time | update_time",
+    oneOf("--sort", ["name", "create_time", "update_time"])
+  ).option(
+    "--direction <dir>",
+    "sort direction: asc | desc",
+    oneOf("--direction", SortDirection.options)
+  ).action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).vega.catalogs({
       limit: o.limit,
@@ -4279,7 +5535,7 @@ function vegaCommand() {
       tag: o.tag,
       type: o.type,
       connectorType: o.connectorType,
-      enabled: o.enabled === void 0 ? void 0 : o.enabled === "true",
+      enabled: o.enabled,
       healthCheckStatus: o.healthCheckStatus,
       sort: o.sort,
       direction: o.direction
@@ -4289,7 +5545,21 @@ 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)", int10).option("--offset <n>", "page offset", int10, 0).action(async (id, opts, cmd) => {
+  catalog.command("stats").description("Count visible catalogs by catalog and connector type").option("--name <s>", "filter by catalog name before aggregation").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.catalogConnectorTypeStats({ name: opts.name }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("resources <id>").description("List resources under a catalog").option(
+    "--category <c>",
+    `filter by category: ${ResourceCategory.options.join(" | ")}`,
+    oneOf("--category", ResourceCategory.options)
+  ).option(
+    "--limit <n>",
+    `page size (default ${DEFAULT_LIST_LIMIT}); page with --offset against total_count`,
+    int7
+  ).option("--offset <n>", "page offset", nonNegativeInt3("--offset"), 0).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
       outputOptions(cmd)
@@ -4298,8 +5568,16 @@ function vegaCommand() {
   catalog.command("health <id>").description("Health-status for a catalog").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealth(id), outputOptions(cmd));
   });
-  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
-    const connectorConfig = parseJsonObject(opts.connectorConfig, "--connector-config");
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").option("--connector-type <s>", "connector type (e.g. mysql); required unless --built-in").option("--connector-config <json>", "connector config JSON; not allowed with --built-in").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--built-in", "create a built-in (logical) catalog, with no connector").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
+    if (opts.builtIn && (opts.connectorType || opts.connectorConfig)) {
+      throw new InputError(
+        "--built-in creates a logical catalog: omit --connector-type and --connector-config"
+      );
+    }
+    if (!opts.builtIn && !opts.connectorType) {
+      throw new InputError("--connector-type is required unless --built-in");
+    }
+    const connectorConfig = opts.connectorConfig === void 0 ? void 0 : parseJsonObject(opts.connectorConfig, "--connector-config");
     printJson(
       await clientFrom(cmd).vega.createCatalog(
         {
@@ -4309,8 +5587,8 @@ function vegaCommand() {
           connectorConfig,
           tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
           description: opts.description,
-          enabled: opts.enabled ? true : void 0,
-          internal: opts.internal ? true : void 0,
+          enabled: Boolean(opts.enabled),
+          builtIn: opts.builtIn ? true : void 0,
           healthCheckSchedule: healthCheckSchedule(opts.healthCheckMode, opts.healthCheckCron)
         },
         { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
@@ -4318,11 +5596,22 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").requiredOption(
+  catalog.command("update <id>").description(
+    "Update a catalog; fields you leave out keep their current values (read, then full PUT)"
+  ).option("--name <s>", "catalog name").option("--connector-type <s>", "connector type").option("--enabled <bool>", "current enabled state (must match; use enable/disable)", bool).option("--connector-config <json>", "connector config JSON (sent only when given)").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option(
     "--expected-update-time <ms>",
-    "optimistic-lock update time",
+    "optimistic-lock update time (default: the update_time read before the PUT)",
     expectedUpdateTime
   ).option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
+    const hasPatch = [
+      opts.name,
+      opts.connectorType,
+      opts.enabled,
+      opts.connectorConfig,
+      opts.tags,
+      opts.description
+    ].some((value) => value !== void 0);
+    if (!hasPatch) throw new InputError("provide at least one catalog field to update");
     const connectorConfig = opts.connectorConfig ? parseJsonObject(opts.connectorConfig, "--connector-config") : void 0;
     printJson(
       await clientFrom(cmd).vega.updateCatalog(
@@ -4390,7 +5679,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", 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) => {
+  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", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 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,
@@ -4399,7 +5688,7 @@ function vegaCommand() {
         limit: opts.limit,
         offset: opts.offset,
         sort: discoverScheduleSort(opts.sort),
-        direction: sortDirection(opts.direction)
+        direction: sortDirection2(opts.direction)
       }),
       outputOptions(cmd)
     );
@@ -4407,7 +5696,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", int10).option("--end-time <ms>", "end time", int10).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 (0 = no lower bound)", nonNegativeInt3("--start-time")).option("--end-time <ms>", "end time (0 = no upper bound)", nonNegativeInt3("--end-time")).option("--enabled", "create enabled").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.createDiscoverSchedule({
         name: opts.name,
@@ -4421,7 +5710,15 @@ 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)", int10).requiredOption("--end-time <ms>", "end time (0 = no upper bound)", int10).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)",
+    nonNegativeInt3("--start-time")
+  ).requiredOption(
+    "--end-time <ms>",
+    "end time (0 = no upper bound)",
+    nonNegativeInt3("--end-time")
+  ).requiredOption("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).requiredOption(
     "--expected-update-time <ms>",
     "optimistic-lock update time",
     expectedUpdateTime
@@ -4448,7 +5745,7 @@ 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("--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) => {
+  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", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 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,
@@ -4460,7 +5757,7 @@ function vegaCommand() {
         limit: opts.limit,
         offset: opts.offset,
         sort: discoverTaskSort(opts.sort),
-        direction: sortDirection(opts.direction)
+        direction: sortDirection2(opts.direction)
       }),
       outputOptions(cmd)
     );
@@ -4480,7 +5777,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", 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) => {
+  ).option("--applied <bool>", "filter by applied state", bool).option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 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),
@@ -4492,12 +5789,12 @@ function vegaCommand() {
         limit: opts.limit,
         offset: opts.offset,
         sort: semanticTaskSort(opts.sort),
-        direction: sortDirection(opts.direction)
+        direction: sortDirection2(opts.direction)
       }),
       outputOptions(cmd)
     );
   });
-  semanticTask.command("create").description("Create a semantic-understanding task").requiredOption("--scope <scope>", "resource | catalog").option("--catalog-id <id>", "catalog id").option("--resource-id <id>", "resource id").option("--apply-mode <mode>", "dry_run | fill_empty | force").option("--confidence-threshold <n>", "minimum confidence (0..1)", confidenceThreshold).option("--include-sample-rows", "include resource sample rows").option("--sample-max-rows <n>", "sample row limit", int10).action(async (opts, cmd) => {
+  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", int7).action(async (opts, cmd) => {
     const scope = semanticScope(opts.scope);
     if (!scope) throw new InputError("--scope is required");
     const applyMode = semanticApplyMode(opts.applyMode);
@@ -4547,18 +5844,44 @@ function vegaCommand() {
     );
   });
   const connector = vega.command("connector-type").description("Connector types");
-  connector.command("list").description("List connector types").action(async (_opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.connectorTypes(), outputOptions(cmd));
+  connector.command("list").description("List connector types").option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--mode <mode>", `runtime mode: ${ConnectorMode.options.join(" | ")}`).option("--category <category>", `category: ${ConnectorCategory.options.join(" | ")}`).option("--enabled <bool>", "filter by enabled state", bool).option("--available <bool>", "filter by runtime availability", bool).option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 0).option("--direction <dir>", `sort direction: ${SortDirection.options.join(" | ")}`).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.connectorTypes({
+        name: opts.name,
+        tag: opts.tag,
+        mode: connectorMode(opts.mode),
+        category: connectorCategory(opts.category),
+        enabled: opts.enabled,
+        available: opts.available,
+        limit: opts.limit,
+        offset: opts.offset,
+        direction: sortDirection2(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
   });
   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("index-capabilities").description(
+    "List local-index analyzers and probe time (undocumented deploy extension; 404 where absent)"
+  ).action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.indexCapabilities(), outputOptions(cmd));
+  });
   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)", 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(
+  ).option(
+    "--input-dialect <dialect>",
+    "SQL input dialect: postgres | mysql | trino | duckdb | tsql",
+    oneOf("--input-dialect", ["postgres", "mysql", "trino", "duckdb", "tsql"])
+  ).option(
+    "--paging-mode <mode>",
+    "paging mode: single | cursor",
+    oneOf("--paging-mode", ["single", "cursor"])
+  ).option("--limit <n>", "page size (cursor mode requires it)", int7).option("--offset <n>", "first-page offset", nonNegativeInt3("--offset")).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", keepAliveSec).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)", int7).option(
     "-d, --data <json>",
     "full request body as JSON (advanced; wins over individual query flags)"
   ).action(async (opts, cmd) => {
@@ -4602,23 +5925,78 @@ 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", 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) => {
+  addResourceListOptions(resource.command("list").description("List resources"), "--type").action(
+    async (opts, cmd) => {
+      printJson(
+        await clientFrom(cmd).resource.list(resourceListOptionsFrom(opts)),
+        outputOptions(cmd)
+      );
+    }
+  );
+  resource.command("get <id>").description("Get a resource").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).resource.get(id), outputOptions(cmd));
+  });
+  resource.command("create").description("Create a dataset or logic-view resource").requiredOption("--catalog-id <id>", "catalog id").requiredOption("--name <s>", "resource name").requiredOption("--category <category>", "resource category: dataset | logicview").option("--id <id>", "explicit resource id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--schema-definition <json>", "schema_definition JSON array").option("--index-config <json>", "index_config JSON object").option("--logic-definition <json>", "logic_definition JSON array").action(async (opts, cmd) => {
+    if (opts.category !== "dataset" && opts.category !== "logicview") {
+      throw new InputError("--category must be dataset or logicview");
+    }
     printJson(
-      await clientFrom(cmd).resource.list({
+      await clientFrom(cmd).resource.create({
+        id: opts.id,
         catalogId: opts.catalogId,
-        category: opts.type ?? opts.category,
-        status: opts.status,
-        schema: opts.schema,
-        limit: opts.limit,
-        offset: opts.offset,
-        sort: opts.sort,
-        direction: opts.direction
+        name: opts.name,
+        category: opts.category,
+        ...opts.tags !== void 0 ? { tags: csv(opts.tags) ?? [] } : {},
+        description: opts.description,
+        ...opts.schemaDefinition !== void 0 ? {
+          schemaDefinition: parseResourceProperties(opts.schemaDefinition)
+        } : {},
+        ...opts.indexConfig !== void 0 ? {
+          indexConfig: parseJsonObject(
+            opts.indexConfig,
+            "--index-config"
+          )
+        } : {},
+        ...opts.logicDefinition !== void 0 ? { logicDefinition: parseJsonArray(opts.logicDefinition, "--logic-definition") } : {}
       }),
       outputOptions(cmd)
     );
   });
-  resource.command("get <id>").description("Get a resource").action(async (id, _opts, cmd) => {
-    printJson(await clientFrom(cmd).resource.get(id), outputOptions(cmd));
+  resource.command("update <id>").description("Update resource metadata, schema, features, or index configuration").option("--name <s>", "resource name").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--schema-definition <json>", "replacement schema_definition JSON array").option("--index-config <json>", "replacement index_config JSON object").option("--logic-definition <json>", "replacement logic_definition JSON array").option("--expected-update-time <ms>", "optimistic-lock update time", expectedUpdateTime).action(async (id, opts, cmd) => {
+    const hasPatch = [
+      opts.name,
+      opts.tags,
+      opts.description,
+      opts.schemaDefinition,
+      opts.indexConfig,
+      opts.logicDefinition
+    ].some((value) => value !== void 0);
+    if (!hasPatch) throw new InputError("provide at least one resource field to update");
+    printJson(
+      await clientFrom(cmd).resource.update(id, {
+        name: opts.name,
+        ...opts.tags !== void 0 ? { tags: csv(opts.tags) ?? [] } : {},
+        description: opts.description,
+        ...opts.schemaDefinition !== void 0 ? {
+          schemaDefinition: parseResourceProperties(opts.schemaDefinition)
+        } : {},
+        ...opts.indexConfig !== void 0 ? {
+          indexConfig: parseJsonObject(
+            opts.indexConfig,
+            "--index-config"
+          )
+        } : {},
+        ...opts.logicDefinition !== void 0 ? { logicDefinition: parseJsonArray(opts.logicDefinition, "--logic-definition") } : {},
+        expectedUpdateTime: opts.expectedUpdateTime
+      }),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("delete <ids...>").description("Delete one or more resources").option("--ignore-missing", "ignore missing resource ids").action(async (ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.delete(ids, { ignoreMissing: opts.ignoreMissing }),
+      outputOptions(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));
@@ -4630,93 +6008,119 @@ function vegaCommand() {
       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) => {
+  addResourceQueryOptions(
+    resource.command("query <id>").description(`Fetch data rows from a resource (default limit ${DEFAULT_QUERY_LIMIT})`)
+  ).action(async (id, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).resource.query(id, { limit: opts.limit, offset: opts.offset }),
+      await clientFrom(cmd).resource.query(id, resourceQueryOptionsFrom(opts, DEFAULT_QUERY_LIMIT)),
       outputOptions(cmd)
     );
   });
-  resource.command("document-get <resource-id> <document-id>").description("Get one dataset document").action(async (resourceId, documentId, _opts, cmd) => {
+  resource.command("document-get <resource-id> <document-ids...>").description("Get dataset documents by id").option("--ignore-missing", "Skip missing documents").action(async (resourceId, documentIds, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).resource.getDocument(resourceId, documentId),
+      await clientFrom(cmd).resource.getDocuments(resourceId, documentIds, {
+        ignoreMissing: opts.ignoreMissing
+      }),
       outputOptions(cmd)
     );
   });
-  resource.command("document-create <resource-id>").description("Create dataset documents").requiredOption(
+  resource.command("document-create <resource-id>").description("Create one dataset document").requiredOption(
     "--data <json>",
-    "JSON array of documents \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (vega-backend)"
+    "Document JSON object \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (vega-backend)"
   ).action(async (resourceId, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).resource.createDocuments(
+      await clientFrom(cmd).resource.createDocument(
         resourceId,
-        parseJsonArray(opts.data, "--data")
+        parseJsonObject(opts.data, "--data")
       ),
       outputOptions(cmd)
     );
   });
-  resource.command("document-upsert <resource-id>").description("Upsert dataset documents; every document must have an id").requiredOption(
+  resource.command("document-upsert <resource-id> <docid>").description("Upsert one dataset document").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");
-    }
+    "Document JSON object \u2014 docs: https://openbkn-ai.github.io/bkn-foundry/ (vega-backend)"
+  ).action(async (resourceId, docid, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).resource.upsertDocuments(resourceId, documents),
+      await clientFrom(cmd).resource.upsertDocument(
+        resourceId,
+        docid,
+        parseJsonObject(opts.data, "--data")
+      ),
       outputOptions(cmd)
     );
   });
-  resource.command("document-delete <resource-id> <document-ids...>").description("Delete dataset documents by id").action(async (resourceId, documentIds, _opts, cmd) => {
+  resource.command("document-delete <resource-id> <document-ids...>").description("Delete dataset documents by id").option("--ignore-missing", "Skip missing documents").action(async (resourceId, documentIds, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).resource.deleteDocuments(resourceId, documentIds),
+      await clientFrom(cmd).resource.deleteDocuments(resourceId, documentIds, {
+        ignoreMissing: opts.ignoreMissing
+      }),
       outputOptions(cmd)
     );
   });
-  resource.command("document-delete-filter <resource-id>").description("Delete dataset documents by a non-empty filter").requiredOption("--filter <json>", "filter_condition JSON object").action(async (resourceId, opts, cmd) => {
-    const filter = parseJsonObject(opts.filter, "--filter");
-    if (!Object.keys(filter).length) throw new InputError("--filter must not be empty");
+  resource.command("document-delete-filter <resource-id>").description("Delete dataset documents by an equality selector or Vega filter condition").option("--filter <json>", "Vega filter_condition JSON object").option("--selector <json>", "JSON equality selector").action(async (resourceId, opts, cmd) => {
+    if (Boolean(opts.filter) === Boolean(opts.selector)) {
+      throw new InputError("exactly one of --filter or --selector is required");
+    }
+    const filter = parseJsonObject(
+      opts.filter ?? opts.selector,
+      opts.filter ? "--filter" : "--selector"
+    );
+    if (!Object.keys(filter).length) {
+      throw new InputError(`${opts.filter ? "--filter" : "--selector"} must not be empty`);
+    }
     printJson(
-      await clientFrom(cmd).resource.deleteDocumentsByFilter(resourceId, filter),
+      await (opts.selector ? clientFrom(cmd).resource.deleteDocumentsBySelector(resourceId, filter) : clientFrom(cmd).resource.deleteDocumentsByFilter(resourceId, filter)),
       outputOptions(cmd)
     );
   });
-  const dataset = vega.command("dataset").description("Dataset index build tasks");
-  dataset.command("build <resource-id>").description("Build a resource's index (creates a BuildTask)").requiredOption("--mode <mode>", "build mode: batch | streaming").option("--embedding-fields <list>", "comma-separated fields to vectorize").option(
-    "--build-key-fields <list>",
-    "comma-separated key fields (batch: time; streaming: row id)"
+  resource.command("build <resource-id>").description("Create a batch BuildTask from the resource's saved index configuration").option("--execute-type <type>", "batch execution type: incremental | full").option(
+    "--wait",
+    "wait for the build to end, with progress on stderr; exits non-zero unless it completes"
   ).option(
-    "--embedding-model <name-or-id>",
-    "default small-model name (a numeric ID is resolved to its name)"
-  ).option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
+    "--timeout <s>",
+    "with --wait: give up after this many seconds (0 = no limit)",
+    seconds,
+    300
+  ).action(async (resourceId, _opts, cmd) => {
     const o = cmd.optsWithGlobals();
-    const embeddingFields = csv(o.embeddingFields);
-    const buildKeyFields = csv(o.buildKeyFields);
-    const fulltextFields = csv(o.fulltextFields);
-    if (embeddingFields || buildKeyFields || o.embeddingModel || fulltextFields || o.fulltextAnalyzer) {
-      await clientFrom(cmd).resource.configureIndex(resourceId, {
-        embeddingFields,
-        buildKeyFields,
-        embeddingModel: o.embeddingModel,
-        fulltextFields,
-        fulltextAnalyzer: o.fulltextAnalyzer
-      });
+    const req = {
+      resource_id: resourceId,
+      mode: "batch",
+      execute_type: buildTaskExecuteType(o.executeType)
+    };
+    if (!o.wait) {
+      printJson(await clientFrom(cmd).vega.build(req), outputOptions(cmd));
+      return;
     }
-    const task = await clientFrom(cmd).vega.build(
-      {
-        resource_id: resourceId,
-        mode: o.mode,
-        execute_type: o.executeType
-      },
-      { wait: Boolean(o.wait), timeoutMs: o.timeout * 1e3 }
+    await waitAndReport(
+      cmd,
+      (onProgress) => clientFrom(cmd).vega.build(req, { wait: true, timeoutMs: o.timeout * 1e3, onProgress })
     );
-    printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-status <task-id>").description("Show a BuildTask's state and progress").action(async (taskId, _opts, cmd) => {
-    const task = await clientFrom(cmd).vega.buildStatus(taskId);
-    printJson(task, outputOptions(cmd));
+  const buildTask = vega.command("build-task").description("Resource index BuildTasks");
+  buildTask.command("get <task-id>").description("Show a BuildTask's state and progress").option(
+    "--wait",
+    "wait for the task to end, with progress on stderr; exits non-zero unless it completes"
+  ).option(
+    "--timeout <s>",
+    "with --wait: give up after this many seconds (0 = no limit)",
+    seconds,
+    300
+  ).action(async (taskId, opts, cmd) => {
+    if (!opts.wait) {
+      printJson(await clientFrom(cmd).vega.buildStatus(taskId), outputOptions(cmd));
+      return;
+    }
+    await waitAndReport(
+      cmd,
+      (onProgress) => clientFrom(cmd).vega.waitForBuild(taskId, { timeoutMs: opts.timeout * 1e3, onProgress })
+    );
   });
-  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(
+  buildTask.command("list").description("List BuildTasks").option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int7, 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: ${BuildMode.options.join(" | ")}`,
+    oneOf("--mode", BuildMode.options)
+  ).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) => {
@@ -4730,21 +6134,21 @@ function vegaCommand() {
         mode: opts.mode,
         executeType: buildTaskExecuteType(opts.executeType),
         sort: buildTaskSort(opts.sort),
-        direction: sortDirection(opts.direction)
+        direction: sortDirection2(opts.direction)
       }),
       outputOptions(cmd)
     );
   });
-  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (rejected for incremental tasks)").action(async (taskId, opts, cmd) => {
+  buildTask.command("start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (rejected for incremental tasks)").action(async (taskId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.startBuildTask(taskId, { reset: opts.reset }),
       outputOptions(cmd)
     );
   });
-  dataset.command("build-stop <task-id>").description("Stop a BuildTask").action(async (taskId, _opts, cmd) => {
+  buildTask.command("stop <task-id>").description("Stop a BuildTask").action(async (taskId, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.stopBuildTask(taskId), outputOptions(cmd));
   });
-  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
+  buildTask.command("delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.deleteBuildTasks(ids, {
         ignoreMissing: opts.ignoreMissing
@@ -4756,18 +6160,22 @@ function vegaCommand() {
     GROUPS: [
       "catalog",
       "resource",
+      "build-task",
       "connector-type",
-      "dataset",
       "discover-schedule",
       "discover-task",
       "semantic-task"
     ],
+    READ: ["index-capabilities"],
     RUN: ["sql"]
   });
   groupChildren(resource, {
     READ: ["list", "get", "document-get"],
-    RUN: ["query", "discover"],
+    RUN: ["query", "discover", "build"],
     WRITE: [
+      "create",
+      "update",
+      "delete",
       "enable",
       "disable",
       "document-create",
@@ -4776,8 +6184,13 @@ function vegaCommand() {
       "document-delete-filter"
     ]
   });
+  groupChildren(buildTask, {
+    READ: ["list", "get"],
+    RUN: ["start", "stop"],
+    WRITE: ["delete"]
+  });
   groupChildren(catalog, {
-    READ: ["list", "get", "resources", "health", "health-check-schedule"],
+    READ: ["list", "get", "stats", "resources", "health", "health-check-schedule"],
     RUN: ["test-connection", "test-connection-config", "discover"],
     WRITE: ["create", "update", "enable", "disable", "delete", "set-health-check-schedule"]
   });
@@ -4790,41 +6203,51 @@ function vegaCommand() {
 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.
+  resource query <id> reads rows through the resource: --filter, --sort, --output-fields,
+  cursor paging, and --ignore-local-index to bypass a table's local index.
 
 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.`
+  resource update <resource-id> saves schema_definition and index_config. Then resource build
+  <resource-id> creates a BuildTask; build-task get / list follow it.
+  --wait (on resource build, or build-task get for an existing task) shows progress on stderr
+  and exits non-zero unless the task completes. --timeout 0 waits without a limit.`
   );
   return group(vega, "DATA & KNOWLEDGE");
 }
 
 // src/cli-program.ts
 function buildProgram() {
-  const program2 = new Command16();
-  program2.name("openbkn").description(
+  const program = new Command17();
+  program.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(
+  ).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("--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));
+  ).option("-k, --insecure", "skip TLS verification (dev / self-signed only)").option(
+    "--no-retry",
+    "fail at once on a refused/dropped connection or a 429/502/503, instead of retrying 3 times"
+  ).option("--dry-run", "print the request this command would send, and send nothing").showHelpAfterError();
+  program.addCommand(authCommand());
+  program.addCommand(configCommand());
+  program.addCommand(appkeyCommand());
+  program.addCommand(bknCommand());
+  program.addCommand(vegaCommand());
+  program.addCommand(resourceCommand());
+  program.addCommand(contextCommand());
+  program.addCommand(modelCommand());
+  program.addCommand(skillCommand());
+  program.addCommand(mcpCommand());
+  program.addCommand(sandboxCommand());
+  program.addCommand(toolboxCommand());
+  program.addCommand(functionToolCommand());
+  program.addCommand(apiToolCommand());
+  program.addCommand(toolCommand());
+  program.addCommand(traceCommand());
+  program.addCommand(adminCommand());
+  program.addCommand(callCommand());
+  program.addCommand(describeCommand(program));
   guide(
-    program2,
+    program,
     `FIRST STEPS
     openbkn auth login https://your-platform -u <user> -p <pass>
     openbkn bkn list                       # knowledge networks you can see
@@ -4837,13 +6260,16 @@ function buildProgram() {
                          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>
+                         vega resource 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>
+    Ship an API          toolbox create --name "<n>" --service-url <url>  ->
+                         api import ./api.yaml --toolbox <box-id>  ->
+                         api enable <tool-id> --toolbox <box-id>  ->  toolbox publish <box-id>
+                         ->  api execute <tool-id> --toolbox <box-id>
+    Ship some code       sandbox run ./add.py  ->  toolbox create --name "<n>" --type function
+                         ->  function create ./add.py --toolbox <box-id> --name add  ->
+                         function enable <tool-id> --toolbox <box-id>  ->
+                         toolbox publish <box-id>  ->  function execute <tool-id> --toolbox <box-id>
     Debug an answer      trace conversations list  ->  trace diagnose <conversation-id> --llm
 
   GOOD TO KNOW
@@ -4855,12 +6281,31 @@ function buildProgram() {
     --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.
+    Saved logins are selected with --user; access follows the account's platform grants.
     \`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;
+  installGroupedHelp(program);
+  return program;
+}
+
+// src/cli-run.ts
+async function runCli(argv = process.argv) {
+  const program = buildProgram();
+  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)}
+`);
+      return;
+    }
+    console.error(formatError(err));
+    process.exitCode = toExitCode(err);
+  } finally {
+    await releaseLifecycleSessions();
+  }
 }
 
 // src/cli.ts
@@ -4868,21 +6313,5 @@ 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));
-}
-await releaseLifecycleSessions();
+await runCli();
 //# sourceMappingURL=cli.js.map