@openbkn/bkn-sdk 0.1.1-alpha.9 → 0.1.2

package/dist/cli.js

@@ -6,8 +6,8 @@ import {
   HttpError,
   InputError,
   activePlatform,
-  attachNoAuth,
   attachToken,
+  changePasswordSafe,
   createClient,
   credentialDeviceLogin,
   currentToken,
@@ -16,7 +16,6 @@ import {
   deletePlatform,
   deviceLogin,
   exportCreds,
-  fetchAuthStatus,
   formatError,
   getUserSafe,
   isHeadless,
@@ -28,24 +27,24 @@ import {
   rawCall,
   readPlatformConfig,
   renderReportMarkdown,
-  request,
   resolveContext,
   setActivePlatform,
   status,
   switchUser,
   toExitCode,
   use,
+  validateFixturePath,
   whoami,
   writePlatformConfig
-} from "./chunk-BFE4SU3V.js";
+} from "./chunk-LH3ONZGQ.js";
 
 // src/cli.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.1-alpha.9",
+  version: "0.1.2",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
@@ -63,7 +62,7 @@ var package_default = {
       import: "./dist/index.js"
     }
   },
-  files: ["dist", "README.md", "README.zh.md", "LICENSE"],
+  files: ["dist", "!dist/**/*.map", "README.md", "README.zh.md", "LICENSE", "NOTICE"],
   publishConfig: {
     access: "public"
   },
@@ -76,21 +75,23 @@ var package_default = {
     build: "tsup",
     dev: "tsup --watch",
     typecheck: "tsc --noEmit",
-    lint: "biome check . && tsc --noEmit",
+    "check:deps": "node scripts/check-no-self-dep.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:cover": "vitest run --coverage",
     ci: "npm run lint && npm test",
     prepublishOnly: "npm run ci && npm run build"
   },
   dependencies: {
     "@clack/prompts": "^0.9.1",
-    "@openbkn/bkn-sdk": "^0.1.1-alpha.3",
     chalk: "^5.4.1",
     commander: "^13.1.0",
     "csv-parse": "^6.2.1",
     "js-yaml": "^4.2.0",
     jszip: "^3.10.1",
+    undici: "^8.7.0",
     zod: "^3.24.1"
   },
   devDependencies: {
@@ -104,6 +105,7 @@ var package_default = {
 };
 
 // src/commands/admin.ts
+import { readFileSync as readFileSync2 } from "fs";
 import { Command as Command2 } from "commander";
 
 // src/help/grouped-help.ts
@@ -174,10 +176,15 @@ function renderOrgTree(nodes, prefix = "") {
 // src/utils/output.ts
 function printJson(value, opts = {}) {
   if (opts.json || opts.compact) {
-    process.stdout.write(`${JSON.stringify(value, null, opts.compact ? 0 : 2)}
+    const json = JSON.stringify(value === void 0 ? null : value, null, opts.compact ? 0 : 2);
+    process.stdout.write(`${json}
 `);
     return;
   }
+  if (value === void 0) {
+    process.stdout.write("(ok)\n");
+    return;
+  }
   const rows = toRows(value);
   if (rows) {
     const fullColumns = columnsOf(rows).filter((c) => rows.some((r) => stringifyCell(r[c]) !== ""));
@@ -215,7 +222,8 @@ var ROW_ENVELOPES = [
   "users",
   "roles",
   "departments",
-  "members"
+  "members",
+  "keys"
 ];
 function toRows(value) {
   const isRowArray = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => x !== null && typeof x === "object" && !Array.isArray(x));
@@ -300,16 +308,46 @@ function stringifyCell(v) {
   return s.length > CELL_MAX ? `${s.slice(0, CELL_MAX - 1)}\u2026` : s;
 }
 
+// src/utils/prompt.ts
+import { createInterface } from "readline";
+function promptLine(query, hidden = false) {
+  return new Promise((resolve2) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    if (hidden) {
+      const mutable = rl;
+      mutable._writeToOutput = (s) => {
+        if (s.startsWith(query)) process.stdout.write(query);
+      };
+    }
+    rl.question(query, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write("\n");
+      resolve2(answer.trim());
+    });
+  });
+}
+
 // src/commands/_shared.ts
 import { readFileSync } from "fs";
+function traceOptionsFrom(o) {
+  const conversationId = (typeof o.conversationId === "string" ? o.conversationId : void 0) ?? process.env.BKN_CONVERSATION_ID;
+  const interactionId = (typeof o.interactionId === "string" ? o.interactionId : void 0) ?? process.env.BKN_INTERACTION_ID;
+  if (!conversationId && !interactionId) return void 0;
+  return {
+    ...conversationId ? { conversationId } : {},
+    ...interactionId ? { interactionId } : {}
+  };
+}
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
+  const trace = traceOptionsFrom(o);
   return createClient({
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
     businessDomain: o.bizDomain,
-    insecure: o.insecure
+    insecure: o.insecure,
+    ...trace ? { trace } : {}
   });
 }
 function outputOptions(cmd) {
@@ -331,27 +369,7 @@ function readBody(opts) {
 }
 
 // src/commands/auth.ts
-import { createInterface } from "readline";
 import { Command } from "commander";
-
-// src/api/eacp-crypto.ts
-import {
-  constants,
-  createPrivateKey,
-  createPublicKey,
-  publicEncrypt
-} from "crypto";
-
-// src/api/admin.ts
-async function changePasswordSafe(ctx, account, oldPassword, newPassword) {
-  await request(ctx, "/api/safe/v1/auth/change-password", {
-    method: "POST",
-    body: { account, old_password: oldPassword, new_password: newPassword }
-  });
-  return { ok: true };
-}
-
-// src/commands/auth.ts
 async function resolveAccount(baseUrl, accessToken, insecure, idToken) {
   const sub = decodeJwt(idToken ?? accessToken)?.sub;
   if (!sub) return void 0;
@@ -365,22 +383,6 @@ async function resolveAccount(baseUrl, accessToken, insecure, idToken) {
     return void 0;
   }
 }
-function promptLine(query, hidden = false) {
-  return new Promise((resolve2) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    if (hidden) {
-      const mutable = rl;
-      mutable._writeToOutput = (s) => {
-        if (s.startsWith(query)) process.stdout.write(query);
-      };
-    }
-    rl.question(query, (answer) => {
-      rl.close();
-      if (hidden) process.stdout.write("\n");
-      resolve2(answer.trim());
-    });
-  });
-}
 function renderSessions(items) {
   const byPlatform = /* @__PURE__ */ new Map();
   for (const it of items) {
@@ -396,25 +398,17 @@ function renderSessions(items) {
   return lines.join("\n") || "(no saved sessions)";
 }
 function registerAuthLeaves(cmd) {
-  cmd.command("login <url>").description("Log in to a platform (attach a token, or browser/password OAuth)").option("-u, --username <name>", "username for password signin").option("-p, --password <pwd>", "password for password signin").option("--token <token>", "provide a token directly (CI / headless)").option("--client-id <id>", "use a fixed OAuth2 client id (skip dynamic registration)").option("--client-secret <secret>", "OAuth2 client secret (omit for public/PKCE)").option(
-    "--port <n>",
-    "loopback redirect port for the auth_code flow",
-    (v) => Number.parseInt(v, 10)
-  ).option("--device", "headless device-code login (RFC 8628) \u2014 no callback server, no password").option("--audience <aud>", "device-code token audience", "bkn-safe").option(
+  cmd.command("login <url>").description("Log in to a platform (attach a token, or browser/password OAuth)").option("-u, --username <name>", "username for password signin").option("-p, --password <pwd>", "password for password signin").option("--token <token>", "provide a token directly (CI / headless)").option("--client-id <id>", "OAuth2 client id to authenticate as").option("--device", "headless device-code login (RFC 8628) \u2014 no callback server, no password").option("--audience <aud>", "device-code token audience", "bkn-safe").option(
     "--timeout <s>",
     "device-login wait before timing out",
     (v) => Number.parseInt(v, 10),
     120
-  ).option("--no-browser", "(legacy) print the URL instead of opening a browser").option("--product <name>", "(legacy) ISF OAuth product query").option("--signin-public-key-file <path>", "(legacy) RSA public key for ISF /oauth2/signin").option("--no-auth", "register the platform with no authentication (no bkn-safe)").action(async (url, opts, cmd2) => {
+  ).option("--no-browser", "print the URL instead of opening a browser").action(async (url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
-    if (g.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
     const out = outputOptions(cmd2);
     const report = (r) => {
       if (out.json || out.compact) {
         printJson({ loggedIn: true, ...r }, out);
-      } else if (r.noAuth) {
-        process.stdout.write(`Registered ${r.baseUrl ?? url} (no authentication)
-`);
       } else {
         process.stdout.write(`Logged in to ${r.baseUrl ?? url} as ${r.username ?? r.userId}
 `);
@@ -425,19 +419,6 @@ function registerAuthLeaves(cmd) {
       report(attachToken(url, token, { insecure: g.insecure }));
       return;
     }
-    if (opts.auth === false) {
-      report(attachNoAuth(url, { insecure: g.insecure }));
-      return;
-    }
-    const authStatus = await fetchAuthStatus(url);
-    if (authStatus && !authStatus.enabled) {
-      process.stderr.write(
-        `Platform auth is disabled (stack: ${authStatus.stack ?? "none"}) \u2014 registering without auth.
-`
-      );
-      report(attachNoAuth(url, { insecure: g.insecure }));
-      return;
-    }
     let tokens;
     let account;
     try {
@@ -448,7 +429,8 @@ function registerAuthLeaves(cmd) {
         tokens = await credentialDeviceLogin(url, username, password, {
           clientId: opts.clientId,
           audience: opts.audience,
-          timeoutMs: opts.timeout * 1e3
+          timeoutMs: opts.timeout * 1e3,
+          insecure: g.insecure
         });
       } else {
         const headless = isHeadless();
@@ -457,6 +439,7 @@ function registerAuthLeaves(cmd) {
           clientId: opts.clientId,
           audience: opts.audience,
           timeoutMs: opts.timeout * 1e3,
+          insecure: g.insecure,
           onPrompt: ({ userCode, verificationUri, verificationUriComplete }) => {
             const target = verificationUriComplete ?? verificationUri;
             process.stderr.write(
@@ -475,9 +458,9 @@ User code: ${userCode}
       }
     } catch (e) {
       if (e instanceof Error && /Device auth failed \(404\)/.test(e.message)) {
-        process.stderr.write("No auth endpoint found \u2014 registering platform without auth.\n");
-        report(attachNoAuth(url, { insecure: g.insecure }));
-        return;
+        throw new InputError(
+          `No auth endpoint on ${url} \u2014 the platform has no bkn-safe auth stack. Deploy bkn-safe, or log in elsewhere and pass the token with \`--token\`.`
+        );
       }
       throw e;
     }
@@ -493,29 +476,29 @@ User code: ${userCode}
       attachToken(url, tokens.accessToken, {
         refreshToken: tokens.refreshToken,
         idToken: tokens.idToken,
-        insecure: g.insecure,
-        username: account
+        username: account,
+        insecure: g.insecure
       })
     );
   });
-  cmd.command("status").description("Show base URL and whether a token is configured").action((_opts, cmd2) => printJson(status(), outputOptions(cmd2)));
+  cmd.command("status").description("Show base URL and whether a token is configured").action(
+    (_opts, cmd2) => printJson(status({ user: cmd2.optsWithGlobals().user }), outputOptions(cmd2))
+  );
   cmd.command("token").description("Print the current access token, refreshing it if expired (keep secret)").option("--no-refresh", "print the stored token as-is, without refreshing").action(async (opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
-    if (g.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-    const token = opts.refresh === false ? currentToken() : await currentTokenFresh();
+    const token = opts.refresh === false ? currentToken({ user: g.user }) : await currentTokenFresh({ insecure: g.insecure, user: g.user });
     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) => {
     const g = cmd2.optsWithGlobals();
-    if (g.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-    const me = whoami();
+    const me = whoami({ user: g.user });
     if (opts.lookup !== false && me.baseUrl && me.sub) {
       try {
         const u = await getUserSafe(
           {
             baseUrl: me.baseUrl,
-            token: currentToken(),
+            token: currentToken({ user: g.user }),
             businessDomain: DEFAULT_BUSINESS_DOMAIN,
             insecure: Boolean(g.insecure)
           },
@@ -580,9 +563,8 @@ User code: ${userCode}
   cmd.command("export").description("Export the active session's tokens (for a headless host)").action((_opts, cmd2) => {
     printJson(exportCreds(), outputOptions(cmd2));
   });
-  cmd.command("change-password [url]").description("Change your account password (bkn-safe self-service; no browser)").option("-a, --account <name>", "account / login name (the login column, e.g. admin)").option("--old-password <pwd>", "current password").option("--new-password <pwd>", "new password").option("--public-key-file <path>", "(legacy) RSA public key for ISF password encryption").action(async (url, opts, cmd2) => {
+  cmd.command("change-password [url]").description("Change your account password (bkn-safe self-service; no browser)").option("-a, --account <name>", "account / login name (the login column, e.g. admin)").option("--old-password <pwd>", "current password").option("--new-password <pwd>", "new password").action(async (url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
-    if (g.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
     const ctx = resolveContext({
       baseUrl: url ?? g.baseUrl,
       token: g.token,
@@ -623,10 +605,14 @@ function authCommand() {
 // src/commands/admin.ts
 var int = (v) => Number.parseInt(v, 10);
 var DEFAULT_RESET_PASSWORD = "openbkn";
+async function importLicenseFile(cmd, file, receipt) {
+  const text = readFileSync2(file, "utf8");
+  const res = await clientFrom(cmd).admin.licenseImport(text, { receipt });
+  printJson(res, outputOptions(cmd));
+  if ("stored" in res && res.stored) process.exitCode = 1;
+}
 function adminCommand() {
-  const admin = new Command2("admin").description(
-    "Operator CLI (kweaver-admin): org, user, role, models, audit"
-  );
+  const admin = new Command2("admin").description("Operator CLI: org, user, role, models, audit");
   registerAuthLeaves(admin.command("auth").description("Operator authentication"));
   const org = admin.command("org").description("Departments and org structure");
   org.command("list").description("List departments").option("--role <r>", "role qualifier", "super_admin").option("--name <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
@@ -755,15 +741,19 @@ function adminCommand() {
   user.command("delete <id>").description("Delete a user").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).admin.userDelete(id), outputOptions(cmd));
   });
-  user.command("reset-password [id]").description("Reset a user's password (defaults to the platform initial password)").option("--id <userId>", "explicit user UUID (alt to the positional id)").option("--user <account>", "resolve the user by account / login name").option("--password <s>", "the new password (default: platform initial 'openbkn')").option("--new-password <s>", "the new password (alias of --password)").option("-y, --yes", "skip confirmation").action(async (id, opts, cmd) => {
+  user.command("reset-password [id]").description("Reset a user's password (defaults to the platform initial password)").option("--id <userId>", "explicit user UUID (alt to the positional id)").option("--user <account>", "resolve the user by account / login name").option("--password <s>", "the new password (default: platform initial 'openbkn')").option("--new-password <s>", "the new password (alias of --password)").option("--prompt-password", "type the new password interactively (input hidden)").option("-y, --yes", "skip confirmation").action(async (id, opts, cmd) => {
     const userId = id ?? opts.id ?? opts.user;
     if (!userId) throw new Error("Provide a user id (positional or --id).");
-    const pwd = opts.password ?? opts.newPassword ?? DEFAULT_RESET_PASSWORD;
+    let explicit = opts.password ?? opts.newPassword;
+    if (!explicit && opts.promptPassword) {
+      explicit = await promptLine("New password: ", true);
+      if (!explicit) throw new InputError("No password entered.");
+    }
+    const pwd = explicit ?? DEFAULT_RESET_PASSWORD;
     const r = await clientFrom(cmd).admin.userResetPassword(userId, pwd);
     const out = outputOptions(cmd);
     if (out.json || out.compact) printJson(r, out);
-    else if (opts.password || opts.newPassword)
-      process.stdout.write(`Password reset for ${userId}.
+    else if (explicit) process.stdout.write(`Password reset for ${userId}.
 `);
     else
       process.stdout.write(
@@ -906,6 +896,27 @@ function adminCommand() {
       );
     });
   }
+  const license = admin.command("license").description("Cluster license management");
+  license.command("show").description("Current license detail (state/edition/expiry/features)").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.licenseGet(), outputOptions(cmd));
+  });
+  license.command("import <file>").description("Import a .lic license file (online deployments auto-activate)").action(async (file, _opts, cmd) => {
+    await importLicenseFile(cmd, file, false);
+  });
+  license.command("receipt <file>").description("Import an offline activation receipt (.lic from the license portal)").action(async (file, _opts, cmd) => {
+    await importLicenseFile(cmd, file, true);
+  });
+  license.command("activate").description("Report the installed license to the issuer (online deployments)").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.licenseActivate(), outputOptions(cmd));
+  });
+  license.command("remove").description("Remove the installed license (back to unactivated)").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.licenseRemove(), outputOptions(cmd));
+  });
+  license.command("fingerprint").description(
+    "This cluster's machine code (paste into the license portal for offline activation)"
+  ).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) => {
     printJson(
       await clientFrom(cmd).admin.auditList({
@@ -966,7 +977,14 @@ function adminCommand() {
 import { Command as Command3 } from "commander";
 var int2 = (v) => Number.parseInt(v, 10);
 function agentCommand() {
-  const cmd = new Command3("agent").description("Agent CRUD, chat, sessions, publish");
+  const cmd = new Command3("agent").description(
+    "[DEPRECATED] Decision Agent \u2014 CRUD, chat, sessions, publish (being phased out)"
+  );
+  cmd.hook("preAction", () => {
+    process.stderr.write(
+      "\u26A0\uFE0F  `openbkn agent` is deprecated and may be removed in a future release.\n"
+    );
+  });
   cmd.command("list").description("List published agents").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).option("--category-id <id>", "filter by category").action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).agents.list({
       name: opts.name,
@@ -1068,11 +1086,78 @@ function agentCommand() {
   return group(cmd, "DECISION AGENT");
 }
 
-// src/commands/bkn.ts
+// src/commands/appkey.ts
 import { Command as Command4 } from "commander";
+var int3 = (v) => Number.parseInt(v, 10);
+var DAY_MS = 864e5;
+function printNewKey(created, out) {
+  if (out.json || out.compact) {
+    printJson(created, out);
+    return;
+  }
+  process.stderr.write(
+    "\u26A0\uFE0F  Copy this key now \u2014 the plaintext is shown only once and cannot be retrieved again.\n\n"
+  );
+  const fields = [
+    ["key", created.key],
+    ["name", created.name],
+    ["id", `${created.id}  (use this to revoke/regenerate)`],
+    ["key_id", created.key_id],
+    ["expires_at", created.expires_at ?? "never"]
+  ];
+  const w = Math.max(...fields.map(([k]) => k.length));
+  for (const [k, v] of fields) process.stdout.write(`  ${k.padEnd(w)}  ${v}
+`);
+}
+function appkeyCommand() {
+  const appkey = new Command4("appkey").description(
+    "AppKeys \u2014 user-issued long-lived credentials (bak_) for the Context Loader"
+  );
+  appkey.command("list").description("List your own AppKeys (no secrets)").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).appKeys.list(), outputOptions(cmd));
+  });
+  appkey.command("create").description("Issue an AppKey \u2014 the plaintext key is shown ONCE, on create").requiredOption("--name <s>", "display name (to tell keys apart)").option("--expires-at <rfc3339>", "expiry as RFC3339 (e.g. 2027-01-01T00:00:00Z)").option("--expire-days <n>", "expiry in N days from now (alternative to --expires-at)", int3).option("--never-expire", "never expire (wins over --expires-at/--expire-days)").action(async (opts, cmd) => {
+    let expiresAt = opts.expiresAt;
+    if (opts.expireDays !== void 0) {
+      if (!Number.isFinite(opts.expireDays) || opts.expireDays <= 0) {
+        throw new InputError("--expire-days must be a positive integer.");
+      }
+      if (expiresAt) {
+        throw new InputError("Use either --expires-at or --expire-days, not both.");
+      }
+      expiresAt = new Date(Date.now() + opts.expireDays * DAY_MS).toISOString();
+    }
+    const created = await clientFrom(cmd).appKeys.create({
+      name: opts.name,
+      expiresAt,
+      neverExpire: Boolean(opts.neverExpire)
+    });
+    printNewKey(created, outputOptions(cmd));
+  });
+  appkey.command("regenerate <id>").alias("rotate").description("Rotate a key in place \u2014 mints a new plaintext; the old bak_ dies immediately").action(async (id, _opts, cmd) => {
+    const created = await clientFrom(cmd).appKeys.regenerate(id);
+    printNewKey(created, outputOptions(cmd));
+  });
+  appkey.command("revoke <id>").alias("delete").alias("rm").description("Revoke one of your AppKeys (immediate; use the `id`, not `key_id`)").action(async (id, _opts, cmd) => {
+    await clientFrom(cmd).appKeys.revoke(id);
+    printJson({ revoked: id }, outputOptions(cmd));
+  });
+  const admin = appkey.command("admin").description("Admin governance over all AppKeys");
+  admin.command("list").description("List all AppKeys, or one owner's (adds owner_user_id)").option("--owner-id <id>", "filter to a single owner").action(async (opts, cmd) => {
+    printJson(await clientFrom(cmd).appKeys.adminList(opts.ownerId), outputOptions(cmd));
+  });
+  admin.command("revoke <id>").alias("delete").alias("rm").description("Revoke any AppKey by id").action(async (id, _opts, cmd) => {
+    await clientFrom(cmd).appKeys.adminRevoke(id);
+    printJson({ revoked: id }, outputOptions(cmd));
+  });
+  return group(appkey, "AUTHENTICATION & CONFIG");
+}
+
+// src/commands/bkn.ts
+import { Command as Command5 } from "commander";
 
 // src/utils/bkn-validate.ts
-import { existsSync, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
 import { join, resolve } from "path";
 var BKN_OBJECT_NAME_MAX_LENGTH = 40;
 function parseFrontmatter(text) {
@@ -1125,7 +1210,7 @@ function validateBknDirectory(dirPath) {
   if (!existsSync(networkPath)) {
     errors.push("Missing network.bkn at the BKN root.");
   } else {
-    const fm = parseFrontmatter(readFileSync2(networkPath, "utf8"));
+    const fm = parseFrontmatter(readFileSync3(networkPath, "utf8"));
     if (!fm) errors.push("network.bkn has no frontmatter block.");
     else {
       if (fm.type !== "knowledge_network")
@@ -1137,7 +1222,7 @@ function validateBknDirectory(dirPath) {
   const otIds = /* @__PURE__ */ new Set();
   const otFiles = bknFiles(join(dir, "object_types"));
   for (const file of otFiles) {
-    const fm = parseFrontmatter(readFileSync2(file, "utf8"));
+    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).`);
@@ -1157,7 +1242,7 @@ function validateBknDirectory(dirPath) {
   }
   const rtFiles = bknFiles(join(dir, "relation_types"));
   for (const file of rtFiles) {
-    const text = readFileSync2(file, "utf8");
+    const text = readFileSync3(file, "utf8");
     const fm = parseFrontmatter(text);
     const rel = file.slice(dir.length + 1);
     if (!fm || fm.type !== "relation_type") {
@@ -1187,10 +1272,10 @@ function validateBknDirectory(dirPath) {
 }
 
 // src/commands/bkn.ts
-var int3 = (v) => Number.parseInt(v, 10);
+var int4 = (v) => Number.parseInt(v, 10);
 function bknCommand() {
-  const bkn = new Command4("bkn").description("Knowledge networks \u2014 list, query, schema, instances");
-  bkn.command("list").description("List knowledge networks").option("--limit <n>", "page size", int3, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int3, 0).option("--name-pattern <s>", "filter by name pattern").option("--tag <s>", "filter by tag").option("--sort <field>", "sort field", "update_time").option("--direction <dir>", "asc | desc", "desc").action(async (_opts, cmd) => {
+  const bkn = new Command5("bkn").description("Knowledge networks \u2014 list, query, schema, instances");
+  bkn.command("list").description("List knowledge networks").option("--limit <n>", "page size", int4, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int4, 0).option("--name-pattern <s>", "filter by name pattern").option("--tag <s>", "filter by tag").option("--sort <field>", "sort field", "update_time").option("--direction <dir>", "asc | desc", "desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).kn.list({
       limit: o.limit,
@@ -1209,7 +1294,7 @@ function bknCommand() {
     });
     printJson(data, outputOptions(cmd));
   });
-  bkn.command("search <kn-id> <query>").description("Semantic search within a knowledge network").option("--max-concepts <n>", "max concepts to return", int3, 10).option("--mode <mode>", "retrieval mode", "keyword_vector_retrieval").action(async (knId, query, opts, cmd) => {
+  bkn.command("search <kn-id> <query>").description("Semantic search within a knowledge network").option("--max-concepts <n>", "max concepts to return", int4, 10).option("--mode <mode>", "retrieval mode", "keyword_vector_retrieval").action(async (knId, query, opts, cmd) => {
     const data = await clientFrom(cmd).kn.search(knId, query, {
       maxConcepts: opts.maxConcepts,
       mode: opts.mode
@@ -1282,9 +1367,6 @@ function bknCommand() {
       outputOptions(cmd)
     );
   });
-  objectType?.command("properties <kn-id> <ot-id>").description("Get an object type's calculated properties").action(async (knId, otId, _opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.objectTypeProperties(knId, otId), 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));
   });
@@ -1298,7 +1380,7 @@ function bknCommand() {
     printJson(await clientFrom(cmd).kn.subgraph(knId, readBody(opts)), outputOptions(cmd));
   });
   const actionLog = bkn.command("action-log").description("Action logs \u2014 list/get/cancel");
-  actionLog.command("list <kn-id>").description("List action logs").option("--status <s>", "filter by status").option("--action-type-id <id>", "filter by action type").option("--limit <n>", "page size", int3, DEFAULT_LIST_LIMIT).action(async (knId, opts, cmd) => {
+  actionLog.command("list <kn-id>").description("List action logs").option("--status <s>", "filter by status").option("--action-type-id <id>", "filter by action type").option("--limit <n>", "page size", int4, DEFAULT_LIST_LIMIT).action(async (knId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.actionLogs(knId, {
         status: opts.status,
@@ -1413,19 +1495,6 @@ function bknCommand() {
   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));
   });
-  const job = bkn.command("job").description("Build jobs \u2014 list/get/tasks");
-  job.command("list <kn-id>").description("List jobs").action(async (knId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobs(knId), outputOptions(cmd));
-  });
-  job.command("get <kn-id> <job-id>").description("Get a job").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.job(knId, jobId), outputOptions(cmd));
-  });
-  job.command("tasks <kn-id> <job-id>").description("List a job's tasks").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobTasks(knId, jobId), outputOptions(cmd));
-  });
-  job.command("delete <kn-id> <job-ids>").description("Delete job(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobDelete(knId, ids), outputOptions(cmd));
-  });
   bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
     "--embedding-model <id>",
     "embedding model id for declared vector indexes (with --build)"
@@ -1478,7 +1547,7 @@ function bknCommand() {
     printJson(result, outputOptions(cmd));
     if (!result.valid) process.exitCode = 1;
   });
-  bkn.command("create-from-csv <catalog-id>").description("Import CSV files into a Vega catalog, then build a KN from them").requiredOption("--files <glob>", "CSV paths (comma-separated or glob)").requiredOption("--name <name>", "knowledge network name").option("--table-prefix <s>", "prefix for derived table names", "").option("--batch-size <n>", "rows per insert batch", int3, 500).option("--tables <list>", "subset of imported tables to include in the KN").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,...]'").option("--build", "submit a Vega build task per resource after creation").option(
+  bkn.command("create-from-csv <catalog-id>").description("Import CSV files into a Vega catalog, then build a KN from them").requiredOption("--files <glob>", "CSV paths (comma-separated or glob)").requiredOption("--name <name>", "knowledge network name").option("--table-prefix <s>", "prefix for derived table names", "").option("--batch-size <n>", "rows per insert batch", int4, 500).option("--tables <list>", "subset of imported tables to include in the KN").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,...]'").option("--build", "submit a Vega build task per resource after creation").option(
     "--embedding-fields <map>",
     "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
   ).option("--embedding-model <id>", "embedding model id for the vector index (with --build)").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
@@ -1504,25 +1573,27 @@ function bknCommand() {
 }
 
 // src/commands/call.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 function collect(value, prev) {
   prev.push(value);
   return prev;
 }
 function callCommand() {
-  const cmd = new Command5("call").alias("curl").description("Call an API with curl-style flags and auto-injected auth headers").argument("<url>", "API path (e.g. /api/...) or absolute URL").option("-X, --request <method>", "HTTP method").option("-H, --header <header>", 'extra header "Name: value" (repeatable)', collect, []).option("-d, --data <body>", "request body (sets JSON content-type if unset)").option("--data-raw <body>", "alias for --data").option(
+  const cmd = new Command6("call").alias("curl").description("Call an API with curl-style flags and auto-injected auth headers").argument("<url>", "API path (e.g. /api/...) or absolute URL").option("-X, --request <method>", "HTTP method").option("-H, --header <header>", 'extra header "Name: value" (repeatable)', collect, []).option("-d, --data <body>", "request body (sets JSON content-type if unset)").option("--data-raw <body>", "alias for --data").option(
     "-F, --form <field>",
     "multipart field key=value or key=@file (repeatable)",
     collect,
     []
   ).option("-v, --verbose", "print request line to stderr").action(async (url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
+    const trace = traceOptionsFrom(g);
     const ctx = resolveContext({
       baseUrl: g.baseUrl,
       token: g.token,
       user: g.user,
       businessDomain: g.bizDomain,
-      insecure: g.insecure
+      insecure: g.insecure,
+      ...trace ? { trace } : {}
     });
     const res = await rawCall(ctx, url, {
       method: opts.request,
@@ -1545,14 +1616,14 @@ function callCommand() {
 }
 
 // src/commands/config.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } 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("Per-platform CLI configuration");
+  const config = new Command7("config").description("Per-platform CLI configuration");
   config.command("show").description("Show the active platform and business domain").action((_opts, cmd) => {
     const baseUrl = activePlatform();
     printJson(
@@ -1585,13 +1656,56 @@ function configCommand() {
 }
 
 // src/commands/context.ts
-import { Command as Command7 } from "commander";
-var int4 = (v) => Number.parseInt(v, 10);
+import { Command as Command8 } from "commander";
+var int5 = (v) => Number.parseInt(v, 10);
+var collectArg = (v, prev) => {
+  prev.push(v);
+  return prev;
+};
+function buildArgs(opts) {
+  let out = {};
+  if (opts.args) {
+    try {
+      out = JSON.parse(opts.args);
+    } catch {
+      throw new InputError("--args must be valid JSON");
+    }
+  }
+  for (const pair of opts.arg ?? []) {
+    const idx = pair.indexOf("=");
+    if (idx <= 0) throw new InputError(`--arg must be key=value (got: ${pair})`);
+    const key = pair.slice(0, idx);
+    const raw = pair.slice(idx + 1);
+    try {
+      out[key] = JSON.parse(raw);
+    } catch {
+      out[key] = raw;
+    }
+  }
+  return out;
+}
+function printToolList(res, out) {
+  if (out.json || out.compact) {
+    printJson(res, out);
+    return;
+  }
+  const r = res ?? {};
+  const arr = [res, r.tools, r.result?.tools, r.data].find(Array.isArray);
+  if (!arr) {
+    printJson(res, out);
+    return;
+  }
+  const rows = arr.map((t) => ({
+    name: t.name ?? t.tool_name ?? t.key ?? "",
+    description: typeof t.description === "string" ? t.description : ""
+  }));
+  printJson(rows, out);
+}
 function contextCommand() {
-  const cmd = new Command7("context").description(
+  const cmd = new Command8("context").description(
     "Context loader (MCP) \u2014 schema discovery, instance query, skill recall"
   );
-  cmd.command("search-schema <kn-id> <query>").description("Search object/relation/action/metric schemas").option("--scope <list>", "comma-separated scopes (object,relation,action,metric)").option("--max <n>", "max concepts", int4).action(async (knId, query, opts, cmd2) => {
+  cmd.command("search-schema <kn-id> <query>").description("Search object/relation/action/metric schemas").option("--scope <list>", "comma-separated scopes (object,relation,action,metric)").option("--max <n>", "max concepts", int5).action(async (knId, query, opts, cmd2) => {
     const data = await clientFrom(cmd2).context.searchSchema(knId, query, {
       searchScope: opts.scope ? String(opts.scope).split(",") : void 0,
       maxConcepts: opts.max
@@ -1607,23 +1721,51 @@ function contextCommand() {
     }
     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("find-skills <kn-id> <object-type-id>").description("Recall skills for an object type").option("--top-k <n>", "max skills (1-20)", int5).action(async (knId, otId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).context.findSkills(knId, otId, opts.topK),
       outputOptions(cmd2)
     );
   });
-  cmd.command("tools <kn-id>").description("List MCP tools").action(async (knId, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).context.tools(knId), 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("tool-call <kn-id> <name>").description("Call any MCP tool directly (--args JSON)").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, name, opts, cmd2) => {
-    let args;
-    try {
-      args = JSON.parse(opts.args);
-    } catch {
-      throw new InputError("--args must be valid JSON");
-    }
-    printJson(await clientFrom(cmd2).context.toolCall(knId, name, args), 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));
+  });
+  cmd.command("relation-types <kn-id> <ids...>").description("Full definitions for the given relation-type ids (unmatched \u2192 `missing`)").action(async (knId, ids, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.relationTypes(knId, ids), outputOptions(cmd2));
+  });
+  cmd.command("info").description("List the deploy's MCP tool catalog (global \u2014 no KN needed)").action(async (_opts, cmd2) => {
+    printToolList(await clientFrom(cmd2).context.info(), outputOptions(cmd2));
+  });
+  cmd.command("tools <kn-id>").description("List MCP tools advertised for a KN session").action(async (knId, _opts, cmd2) => {
+    printToolList(await clientFrom(cmd2).context.tools(knId), outputOptions(cmd2));
+  });
+  cmd.command("tool-call <kn-id> <name>").description("Call any MCP tool by name \u2014 current or future (use `tools` to discover)").option("--args <json>", "tool arguments as JSON").option(
+    "--arg <key=value>",
+    "one argument (repeatable; value parsed as JSON, else string)",
+    collectArg,
+    []
+  ).action(async (knId, name, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).context.toolCall(knId, name, buildArgs(opts)),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("call-method <kn-id> <method>").description(
+    "Call any MCP method by name (e.g. tools/list, resources/read) \u2014 current or future"
+  ).option("--args <json>", "method params as JSON").option(
+    "--arg <key=value>",
+    "one param (repeatable; value parsed as JSON, else string)",
+    collectArg,
+    []
+  ).action(async (knId, method, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).context.callMethod(knId, method, buildArgs(opts)),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("resources <kn-id>").description("List MCP resources").action(async (knId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).context.resources(knId), outputOptions(cmd2));
@@ -1655,19 +1797,19 @@ function contextCommand() {
       throw new InputError("--args must be valid JSON");
     }
   };
-  cmd.command("query-instance-subgraph <kn-id>").description("Layer-2: query an instance subgraph across relation-type paths").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("query-instance-subgraph <kn-id>").description("Query an instance subgraph across relation-type paths").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).context.queryInstanceSubgraph(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
     );
   });
-  cmd.command("get-logic-properties <kn-id>").description("Layer-3: compute logic-property values for instances").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("get-logic-properties <kn-id>").description("Compute logic-property values for instances").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).context.logicProperties(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
     );
   });
-  cmd.command("get-action-info <kn-id>").description("Layer-3: fetch action info / dynamic tools for an instance").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+  cmd.command("get-action-info <kn-id>").description("Fetch action info / dynamic tools for an instance").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).context.actionInfo(knId, jsonArgs(opts.args)),
       outputOptions(cmd2)
@@ -1677,20 +1819,24 @@ function contextCommand() {
 }
 
 // src/commands/dataflow.ts
-import { Command as Command8 } from "commander";
-var int5 = (v) => Number.parseInt(v, 10);
+import { Command as Command9 } from "commander";
+var int6 = (v) => Number.parseInt(v, 10);
 function dataflowCommand() {
-  const cmd = new Command8("dataflow").description("Dataflow document workflows \u2014 list, runs, logs");
+  const cmd = new Command9("dataflow").description("Dataflow document workflows \u2014 list, runs, logs");
   cmd.command("list").description("List all dataflows").action(async (_opts, cmd2) => {
     printJson(await clientFrom(cmd2).dataflows.list(), outputOptions(cmd2));
   });
-  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").action(async (dagId, opts, cmd2) => {
+  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").option("--limit <n>", "page size (backend default 20)", int6).option("--page <n>", "page (0-based; backend default 0)", int6).action(async (dagId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).dataflows.runs(dagId, { since: opts.since }),
+      await clientFrom(cmd2).dataflows.runs(dagId, {
+        since: opts.since,
+        page: opts.page,
+        limit: opts.limit
+      }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("logs <dagId> <instanceId>").description("Show logs for one run").option("--page <n>", "page", int5, 0).option("--limit <n>", "page size", int5, DEFAULT_LIST_LIMIT).action(async (dagId, instanceId, opts, cmd2) => {
+  cmd.command("logs <dagId> <instanceId>").description("Show logs for one run").option("--page <n>", "page", int6, 0).option("--limit <n>", "page size", int6, DEFAULT_LIST_LIMIT).action(async (dagId, instanceId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).dataflows.logs(dagId, instanceId, {
         page: opts.page,
@@ -1752,8 +1898,8 @@ function dataflowCommand() {
 
 // src/commands/explore.ts
 import { createServer } from "http";
-import { Command as Command9 } from "commander";
-var int6 = (v) => Number.parseInt(v, 10);
+import { Command as Command10 } from "commander";
+var int7 = (v) => Number.parseInt(v, 10);
 var ROUTES = {
   "GET /api/bkn/meta": (c, q) => c.kn.get(req(q, "knId")),
   "POST /api/bkn/search": (c, _q, b) => c.kn.search(str(b.knId), str(b.query), {
@@ -1761,7 +1907,6 @@ var ROUTES = {
   }),
   "POST /api/bkn/instances": (c, _q, b) => c.kn.objectTypeQuery(str(b.knId), str(b.objectTypeId), b.body ?? {}),
   "POST /api/bkn/subgraph": (c, _q, b) => c.kn.subgraph(str(b.knId), b.body ?? b),
-  "POST /api/bkn/properties": (c, _q, b) => c.kn.objectTypeProperties(str(b.knId), str(b.objectTypeId)),
   "GET /api/vega/catalogs": (c) => c.vega.catalogs(),
   "GET /api/vega/catalog": (c, q) => c.vega.getCatalog(req(q, "catalogId")),
   "GET /api/vega/catalog-resources": (c, q) => c.vega.catalogResources(req(q, "catalogId"), q.get("category") ?? void 0),
@@ -1798,10 +1943,10 @@ var INDEX = `<!doctype html><meta charset="utf-8"><title>openbkn explore</title>
 <p>Read-only JSON endpoints for bkn + vega:</p>
 <ul>${Object.keys(ROUTES).map((r) => `<li><code>${r}</code></li>`).join("")}</ul>`;
 function exploreCommand() {
-  const cmd = new Command9("explore").description(
+  const cmd = new Command10("explore").description(
     "Start a local web server with read-only bkn + vega JSON endpoints"
   );
-  cmd.option("--port <n>", "port to listen on", int6, 7777).option("--host <h>", "host to bind", "127.0.0.1").action(async (opts, command) => {
+  cmd.option("--port <n>", "port to listen on", int7, 7777).option("--host <h>", "host to bind", "127.0.0.1").action(async (opts, command) => {
     const client = clientFrom(command);
     const server = createServer((reqMsg, res) => {
       void handle(client, reqMsg, res);
@@ -1839,8 +1984,14 @@ async function handle(client, reqMsg, res) {
 }
 
 // src/commands/model.ts
-import { Command as Command10 } from "commander";
-var int7 = (v) => Number.parseInt(v, 10);
+import { Command as Command11 } from "commander";
+var int8 = (v) => Number.parseInt(v, 10);
+async function resolveLlmModelName(client, model) {
+  if (!/^\d+$/.test(model)) return model;
+  const detail = await client.models.llm.get(model);
+  if (!detail?.model_name) throw new InputError(`No LLM found with id ${model}.`);
+  return detail.model_name;
+}
 function addManagementCommands(parent, kind) {
   parent.command("add").description("Register a model (definition JSON via --body / --body-file)").option("--body <json>", "model definition JSON").option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
     printJson(await clientFrom(cmd).models[kind].add(readBody(opts)), outputOptions(cmd));
@@ -1856,9 +2007,11 @@ function addManagementCommands(parent, kind) {
   });
 }
 function modelCommand() {
-  const model = new Command10("model").description("Model factory \u2014 LLM / small-model CRUD + chat");
+  const model = new Command11("model").description(
+    "Model factory \u2014 LLM / small-model CRUD, chat / embeddings / rerank, default selection"
+  );
   const llm = model.command("llm").description("Large language models");
-  llm.command("list").description("List LLM models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int7, 1).action(async (opts, cmd) => {
+  llm.command("list").description("List LLM models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.llm.list({
         name: opts.name,
@@ -1872,18 +2025,26 @@ function modelCommand() {
   llm.command("get <modelId>").description("Get an LLM model").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).models.llm.get(id), outputOptions(cmd));
   });
-  llm.command("chat <modelId>").description("OpenAI-compatible chat completion").requiredOption("-m, --message <text>", "user message").option("--stream", "stream the reply token-by-token to stdout").action(async (id, opts, cmd) => {
+  llm.command("chat <model>").description("OpenAI-compatible chat completion (<model> = model name or numeric id)").requiredOption("-m, --message <text>", "user message").option("--stream", "stream the reply token-by-token to stdout").action(async (model2, opts, cmd) => {
+    const client = clientFrom(cmd);
+    const name = await resolveLlmModelName(client, model2);
     const messages = [{ role: "user", content: opts.message }];
     if (opts.stream) {
-      await clientFrom(cmd).models.llm.chatStream(id, messages, (t) => process.stdout.write(t));
+      await client.models.llm.chatStream(name, messages, (t) => process.stdout.write(t));
       process.stdout.write("\n");
       return;
     }
-    printJson(await clientFrom(cmd).models.llm.chat(id, messages), outputOptions(cmd));
+    printJson(await client.models.llm.chat(name, messages), outputOptions(cmd));
+  });
+  llm.command("set-default <modelId>").description("Set this LLM as the system default (admin)").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).models.llm.setDefault(id, true), outputOptions(cmd));
+  });
+  llm.command("unset-default <modelId>").description("Clear this LLM as the system default (admin)").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).models.llm.setDefault(id, false), outputOptions(cmd));
   });
   addManagementCommands(llm, "llm");
   const small = model.command("small").description("Small models (embedding / reranker)");
-  small.command("list").description("List small models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int7, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int7, 1).action(async (opts, cmd) => {
+  small.command("list").description("List small models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.list({
         name: opts.name,
@@ -1909,37 +2070,81 @@ function modelCommand() {
       outputOptions(cmd)
     );
   });
+  small.command("get-default").description("Show the system default small model for a type").option("--type <t>", "model type: embedding | reranker", "embedding").action(async (opts, cmd) => {
+    printJson(await clientFrom(cmd).models.small.getDefault(opts.type), outputOptions(cmd));
+  });
+  small.command("set-default <modelId>").description("Set this small model as the system default for its type (admin)").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).models.small.setDefault(id, true), outputOptions(cmd));
+  });
+  small.command("unset-default <modelId>").description("Clear this small model as the system default (admin)").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).models.small.setDefault(id, false), outputOptions(cmd));
+  });
   addManagementCommands(small, "small");
+  model.addHelpText(
+    "after",
+    `
+Identifiers:
+  \u2022 get / set-default / delete take the numeric model id (e.g. 2071747547839467520).
+  \u2022 chat takes a model NAME, but also accepts a numeric id (resolved to its name).
+
+Examples:
+  $ openbkn model llm list                          # ids + the 'default' flag
+  $ openbkn model llm chat deepseek_v4_flash -m hi  # by name
+  $ openbkn model llm chat 2071747547839467520 -m hi --stream   # by id, streamed
+  $ openbkn model llm set-default 2071747547839467520           # system default LLM
+  $ openbkn model small get-default --type embedding            # current default
+  $ openbkn model small set-default <id>                        # default embedding/reranker`
+  );
   return group(model, "MODELS & SKILLS");
 }
 
 // src/commands/resource.ts
-import { Command as Command11 } from "commander";
-var int8 = (v) => Number.parseInt(v, 10);
+import { Command as Command12 } from "commander";
+var int9 = (v) => Number.parseInt(v, 10);
+var parsePairs = (raw) => {
+  if (!raw) return void 0;
+  return raw.split(",").map((part) => {
+    const idx = part.indexOf("=");
+    if (idx < 1) throw new Error("--extension must be key=value[,key=value]");
+    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
+  }).filter((p) => p.key.length > 0);
+};
 function resourceCommand() {
-  const cmd = new Command11("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
-  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--datasource-id <id>", "alias of --catalog-id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
+  const cmd = new Command12("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
+  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--datasource-id <id>", "alias of --catalog-id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int9, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.list({
       datasourceId: opts.catalogId ?? opts.datasourceId,
       category: opts.category ?? opts.type,
-      limit: opts.limit
+      status: opts.status,
+      database: opts.database,
+      limit: opts.limit,
+      offset: opts.offset,
+      includeExtensions: opts.includeExtensions,
+      includeExtensionKeys: opts.includeExtensionKeys,
+      extensionPairs: parsePairs(opts.extension),
+      sort: opts.sort,
+      direction: opts.direction
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").action(async (opts, cmd2) => {
+  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").option("--limit <n>", "rows to scan before filtering", int9, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
-      datasourceId: opts.catalogId ?? opts.datasourceId
+      datasourceId: opts.catalogId ?? opts.datasourceId,
+      limit: opts.limit
     });
     printJson(data, outputOptions(cmd2));
   });
   cmd.command("get <id>").description("Get resource details").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.get(id), outputOptions(cmd2));
   });
-  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int8, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int8, 0).option("--need-total", "include total count").action(async (id, opts, cmd2) => {
+  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int9).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
     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
     });
     printJson(data, outputOptions(cmd2));
@@ -1951,11 +2156,11 @@ function resourceCommand() {
 }
 
 // src/commands/skill.ts
-import { Command as Command12 } from "commander";
-var int9 = (v) => Number.parseInt(v, 10);
+import { Command as Command13 } from "commander";
+var int10 = (v) => Number.parseInt(v, 10);
 function skillCommand() {
-  const cmd = new Command12("skill").description("Skill registry and market");
-  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int9, 1);
+  const cmd = new Command13("skill").description("Skill registry and market");
+  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int10, 1);
   listOpts(cmd.command("list").description("List skills")).option("--create-user <s>", "filter by creator").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).skills.list({
@@ -2041,11 +2246,11 @@ function skillCommand() {
 }
 
 // src/commands/toolbox.ts
-import { Command as Command13 } from "commander";
-var int10 = (v) => Number.parseInt(v, 10);
+import { Command as Command14 } from "commander";
+var int11 = (v) => Number.parseInt(v, 10);
 function toolboxCommand() {
-  const cmd = new Command13("toolbox").description("Agent toolbox lifecycle");
-  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int10, 0).action(async (opts, cmd2) => {
+  const cmd = new Command14("toolbox").description("Agent toolbox lifecycle");
+  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.list({
         keyword: opts.keyword,
@@ -2086,9 +2291,16 @@ function toolboxCommand() {
   return group(cmd, "DECISION AGENT");
 }
 function toolCommand() {
-  const cmd = new Command13("tool").description("Tools inside a toolbox");
-  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).toolboxes.tools(opts.toolbox), outputOptions(cmd2));
+  const cmd = new Command14("tool").description("Tools inside a toolbox");
+  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int11).option("--page <n>", "page (1-based; backend default 1)", int11).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
+        page: opts.page,
+        pageSize: opts.limit,
+        all: opts.all
+      }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("enable <tool-ids...>").description("Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
     printJson(
@@ -2102,7 +2314,7 @@ function toolCommand() {
       outputOptions(cmd2)
     );
   });
-  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option("--body <json>", "request body JSON").option("--header <json>", "headers map JSON").option("--query <json>", "query params JSON").option("--path <json>", "path params JSON").option("--timeout <s>", "per-call timeout seconds", int10);
+  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option("--body <json>", "request body JSON").option("--header <json>", "headers map JSON").option("--query <json>", "query params JSON").option("--path <json>", "path params JSON").option("--timeout <s>", "per-call timeout seconds", int11);
   const parseJson = (s, label) => {
     if (!s) return void 0;
     try {
@@ -2144,11 +2356,11 @@ function toolCommand() {
 }
 
 // src/commands/trace.ts
-import { readFileSync as readFileSync4, writeFileSync } from "fs";
-import { Command as Command14 } from "commander";
+import { readFileSync as readFileSync5, writeFileSync } from "fs";
+import { Command as Command15 } from "commander";
 
-// src/trace-ai/schema-validate.ts
-import { readFileSync as readFileSync3 } from "fs";
+// src/bkn-trace/schema-validate.ts
+import { readFileSync as readFileSync4 } from "fs";
 import { extname } from "path";
 import yaml from "js-yaml";
 import { z } from "zod";
@@ -2185,7 +2397,7 @@ var DiagnosisRule = z.object({
   params: z.record(z.string(), z.unknown()).optional()
 });
 function parseFile(file) {
-  const text = readFileSync3(file, "utf8");
+  const text = readFileSync4(file, "utf8");
   const ext = extname(file).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") return yaml.load(text);
   return JSON.parse(text);
@@ -2223,9 +2435,36 @@ function validateSchemaFile(file, kind) {
 
 // src/commands/trace.ts
 function traceCommand() {
-  const cmd = new Command14("trace").description(
-    "Trace AI \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
+  const cmd = new Command15("trace").description(
+    "BKN Trace \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
   );
+  cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.graph(traceId), outputOptions(cmd2));
+  });
+  cmd.command("evidence-chain [trace-id]").description("Fetch BKN Trace evidence chain by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.evidenceChain(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("business-graph [trace-id]").description("Fetch BKN Trace business semantic graph by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.businessGraph(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("snapshot-preview [trace-id]").description("Fetch metadata-only evidence snapshot preview by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.snapshotPreview(traceScope(traceId, opts.requestId), {
+        limit: opts.limit
+      }),
+      outputOptions(cmd2)
+    );
+  });
   cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
@@ -2252,7 +2491,7 @@ function traceCommand() {
   });
   const evalSet = cmd.command("eval-set").description("Build + run trace eval sets");
   evalSet.command("build <queries-file>").description("Build eval cases from a queries JSON file").option("--out <file>", "write the cases JSON here (default: stdout)").action(async (queriesFile, opts, cmd2) => {
-    const raw = JSON.parse(readFileSync4(queriesFile, "utf8"));
+    const raw = JSON.parse(readFileSync5(queriesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     if (opts.out) {
       writeFileSync(opts.out, JSON.stringify({ cases }, null, 2));
@@ -2262,7 +2501,7 @@ function traceCommand() {
     }
   });
   evalSet.command("test <cases-file>").description("Run an eval set against an agent (--llm enables semantic_match)").requiredOption("--agent <id>", "agent id to run the queries against").option("--version <v>", "agent version", "v0").option("--llm", "enable semantic_match assertions via the local `claude` CLI").action(async (casesFile, opts, cmd2) => {
-    const raw = JSON.parse(readFileSync4(casesFile, "utf8"));
+    const raw = JSON.parse(readFileSync5(casesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     const result = await clientFrom(cmd2).trace.evalSetTest(opts.agent, cases, {
       version: opts.version,
@@ -2277,45 +2516,108 @@ function traceCommand() {
     printJson(result, outputOptions(cmd2));
     if (!result.valid) process.exitCode = 1;
   });
+  cmd.command("validate-fixture <path>").description("Validate BKN Trace 1.0/2.0/2.1 fixture JSON files").action(async (path, _opts, cmd2) => {
+    const result = validateFixturePath(path);
+    printJson(result, outputOptions(cmd2));
+    if (!result.ok) process.exitCode = 1;
+  });
+  const evidence = cmd.command("evidence").description("Submit BKN Trace 2.x business evidence events");
+  evidence.command("emit <file>").description("Submit a BKN Trace 2.0/2.1 event batch JSON file").action(async (file, _opts, cmd2) => {
+    const body = JSON.parse(readFileSync5(file, "utf8"));
+    printJson(await clientFrom(cmd2).trace.emitEvidenceEvents(body), outputOptions(cmd2));
+  });
   return group(cmd, "TRACE AI");
 }
+function traceScope(traceId, requestId) {
+  if (traceId && requestId) {
+    throw new InputError("Provide either trace id or --request-id, not both.");
+  }
+  if (requestId) return { requestId };
+  if (traceId) return traceId;
+  throw new InputError("Provide a trace id or --request-id.");
+}
 
 // src/commands/vega.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
+var int12 = (v) => Number.parseInt(v, 10);
+var parsePairs2 = (raw) => {
+  if (!raw) return void 0;
+  return raw.split(",").map((part) => {
+    const idx = part.indexOf("=");
+    if (idx < 1) throw new InputError("--extension must be key=value[,key=value]");
+    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
+  }).filter((p) => p.key.length > 0);
+};
 function vegaCommand() {
-  const vega = new Command15("vega").description(
+  const vega = new Command16("vega").description(
     "Vega observability \u2014 catalog, resources, index build tasks"
   );
   const catalog = vega.command("catalog").description("Catalog entries");
-  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", (v) => Number.parseInt(v, 10), 0).action(async (_opts, cmd) => {
+  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", (v) => Number.parseInt(v, 10), 0).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--type <type>", "filter by catalog type: physical | logical").option("--enabled <bool>", "filter by enabled state").option("--health-check-status <s>", "filter by health status").option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
-    const data = await clientFrom(cmd).vega.catalogs({ limit: o.limit, offset: o.offset });
+    const data = await clientFrom(cmd).vega.catalogs({
+      limit: o.limit,
+      offset: o.offset,
+      name: o.name,
+      tag: o.tag,
+      type: o.type,
+      enabled: o.enabled === void 0 ? void 0 : o.enabled === "true",
+      healthCheckStatus: o.healthCheckStatus,
+      includeExtensions: o.includeExtensions,
+      includeExtensionKeys: o.includeExtensionKeys,
+      extensionPairs: parsePairs2(o.extension),
+      sort: o.sort,
+      direction: o.direction
+    });
     printJson(data, outputOptions(cmd));
   });
   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)").action(async (id, opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.catalogResources(id, opts.category), outputOptions(cmd));
+  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (backend default 20, max 1000; -1 = all)", int12).option("--offset <n>", "page offset", int12, 0).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
+      outputOptions(cmd)
+    );
   });
   catalog.command("health <ids...>").description("Health-status for one or more catalogs").action(async (ids, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealth(ids), 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("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").action(async (opts, cmd) => {
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").action(async (opts, cmd) => {
     let connectorConfig;
     try {
       connectorConfig = JSON.parse(opts.connectorConfig);
     } catch {
       throw new Error("--connector-config must be valid JSON");
     }
+    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
     printJson(
       await clientFrom(cmd).vega.createCatalog({
+        id: opts.id,
         name: opts.name,
         connectorType: opts.connectorType,
         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
+        enabled: opts.enabled ? true : void 0,
+        internal: opts.internal ? true : void 0,
+        extensions
+      }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("update <id>").description("Update a catalog").option("--name <s>", "catalog name").option("--connector-type <s>", "connector type").option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled <bool>", "enabled state").option("--extensions <json>", "extension key/value JSON object").action(async (id, opts, cmd) => {
+    const connectorConfig = opts.connectorConfig ? JSON.parse(opts.connectorConfig) : void 0;
+    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
+    printJson(
+      await clientFrom(cmd).vega.updateCatalog(id, {
+        name: opts.name,
+        connectorType: opts.connectorType,
+        connectorConfig,
+        tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+        description: opts.description,
+        enabled: opts.enabled === void 0 ? void 0 : opts.enabled === "true",
+        extensions
       }),
       outputOptions(cmd)
     );
@@ -2323,6 +2625,15 @@ function vegaCommand() {
   catalog.command("enable <id>").description("Enable a catalog (required before discovery)").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.enableCatalog(id), outputOptions(cmd));
   });
+  catalog.command("disable <id>").description("Disable a catalog").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.disableCatalog(id), outputOptions(cmd));
+  });
+  catalog.command("delete <id>").description("Delete a catalog").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.deleteCatalog(id), outputOptions(cmd));
+  });
+  catalog.command("test-connection <id>").description("Test a catalog connection").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.testCatalogConnection(id), outputOptions(cmd));
+  });
   catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--wait", "wait for discovery to complete").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.discoverCatalog(id, Boolean(opts.wait)),
@@ -2336,13 +2647,67 @@ function vegaCommand() {
   connector.command("get <type>").description("Get a connector type").action(async (type, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.connectorType(type), outputOptions(cmd));
   });
+  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").option(
+    "--query <sql>",
+    "SQL string; reference a resource with a {{<resource-id>}} placeholder"
+  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int12).option("--offset <n>", "first-page offset", int12).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int12).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int12).option(
+    "-d, --data <json>",
+    "full request body as JSON (advanced; wins over individual query flags)"
+  ).action(async (opts, cmd) => {
+    let body;
+    if (opts.data) {
+      try {
+        body = JSON.parse(opts.data);
+      } catch {
+        throw new InputError("--data must be valid JSON");
+      }
+    } else if (opts.cursor) {
+      if (opts.query || opts.inputDialect || opts.pagingMode || opts.limit !== void 0 || opts.offset !== void 0 || opts.keepAliveSec !== void 0 || opts.queryTimeoutSec !== void 0) {
+        throw new InputError("--cursor cannot be combined with initial-query options");
+      }
+      body = {
+        paging: { cursor: opts.cursor },
+        ...opts.needTotal ? { need_total: true } : {}
+      };
+    } else {
+      if (!opts.query) {
+        throw new InputError("Provide --query, --cursor, or --data.");
+      }
+      if (opts.pagingMode === "cursor" && opts.limit === void 0) {
+        throw new InputError("--limit is required when --paging-mode cursor");
+      }
+      const paging = {
+        ...opts.pagingMode ? { mode: opts.pagingMode } : {},
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts.offset !== void 0 ? { offset: opts.offset } : {},
+        ...opts.keepAliveSec !== void 0 ? { keep_alive_sec: opts.keepAliveSec } : {}
+      };
+      body = {
+        query: opts.query,
+        query_format: "sql",
+        ...opts.inputDialect ? { input_dialect: opts.inputDialect } : {},
+        ...Object.keys(paging).length ? { paging } : {},
+        ...opts.needTotal ? { need_total: true } : {},
+        ...opts.queryTimeoutSec !== void 0 ? { query_timeout_sec: opts.queryTimeoutSec } : {}
+      };
+    }
+    printJson(await clientFrom(cmd).vega.sql(body), outputOptions(cmd));
+  });
   const resource = vega.command("resource").description("Vega-backend resources");
-  resource.command("list").description("List resources").option("--datasource-id <id>", "filter by catalog/datasource id").option("--catalog-id <id>", "alias of --datasource-id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).action(async (opts, cmd) => {
+  resource.command("list").description("List resources").option("--datasource-id <id>", "filter by catalog/datasource id").option("--catalog-id <id>", "alias of --datasource-id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).resource.list({
         datasourceId: opts.datasourceId ?? opts.catalogId,
         category: opts.type ?? opts.category,
-        limit: opts.limit
+        status: opts.status,
+        database: opts.database,
+        limit: opts.limit,
+        offset: opts.offset,
+        includeExtensions: opts.includeExtensions,
+        includeExtensionKeys: opts.includeExtensionKeys,
+        extensionPairs: parsePairs2(opts.extension),
+        sort: opts.sort,
+        direction: opts.direction
       }),
       outputOptions(cmd)
     );
@@ -2360,16 +2725,25 @@ function vegaCommand() {
   dataset.command("build <resource-id>").description("Build a resource's index (creates a BuildTask)").requiredOption("--mode <mode>", "build mode: batch | streaming").option("--embedding-fields <list>", "comma-separated fields to vectorize").option(
     "--build-key-fields <list>",
     "comma-separated key fields (batch: time; streaming: row id)"
-  ).option("--embedding-model <id>", "embedding model id (default if omitted)").option("--model-dimensions <n>", "vector dimensions", (v) => Number.parseInt(v, 10)).option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
+  ).option("--embedding-model <id>", "default embedding model name/id").option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
     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 task = await clientFrom(cmd).vega.build(
       {
         resource_id: resourceId,
         mode: o.mode,
-        embedding_fields: csv(o.embeddingFields),
-        build_key_fields: csv(o.buildKeyFields),
-        embedding_model: o.embeddingModel,
-        model_dimensions: o.modelDimensions
+        execute_type: o.executeType
       },
       { wait: Boolean(o.wait), timeoutMs: o.timeout * 1e3 }
     );
@@ -2379,15 +2753,50 @@ function vegaCommand() {
     const task = await clientFrom(cmd).vega.buildStatus(taskId);
     printJson(task, outputOptions(cmd));
   });
+  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "default | created_at | updated_at | status | mode").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.buildTasks({
+        limit: opts.limit,
+        offset: opts.offset,
+        resourceId: opts.resourceId,
+        catalogId: opts.catalogId,
+        status: opts.status,
+        active: opts.active,
+        mode: opts.mode,
+        orderBy: opts.orderBy,
+        order: opts.order
+      }),
+      outputOptions(cmd)
+    );
+  });
+  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart from the beginning").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) => {
+    printJson(await clientFrom(cmd).vega.stopBuildTask(taskId), outputOptions(cmd));
+  });
+  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").option("--delete-active-index", "delete active indexes too").action(async (ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.deleteBuildTasks(ids, {
+        ignoreMissing: opts.ignoreMissing,
+        deleteActiveIndex: opts.deleteActiveIndex
+      }),
+      outputOptions(cmd)
+    );
+  });
   return group(vega, "AI DATA PLATFORM");
 }
 
 // src/cli.ts
-var program = new Command16();
-program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
+var program = new Command17();
+program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
 program.addCommand(authCommand());
 program.addCommand(callCommand());
 program.addCommand(configCommand());
+program.addCommand(appkeyCommand());
 program.addCommand(vegaCommand());
 program.addCommand(bknCommand());
 program.addCommand(resourceCommand());