@openbkn/bkn-sdk 0.1.3 → 0.1.4

package/dist/cli.js

@@ -1,10 +1,21 @@
 #!/usr/bin/env node
 import {
+  BuildTaskSort,
+  BuildTaskStatus,
   DEFAULT_BUSINESS_DOMAIN,
   DEFAULT_LIST_LIMIT,
   DEFAULT_QUERY_LIMIT,
+  DiscoverScheduleSort,
+  DiscoverStrategy,
+  DiscoverTaskSort,
+  DiscoverTaskTriggerType,
   HttpError,
   InputError,
+  SemanticUnderstandingApplyMode,
+  SemanticUnderstandingScope,
+  SemanticUnderstandingTaskSort,
+  SortDirection,
+  VegaTaskStatus,
   activePlatform,
   attachToken,
   changePasswordSafe,
@@ -25,6 +36,7 @@ import {
   listPlatforms,
   logout,
   openBrowser,
+  parseBigIntJSON,
   parseEmbeddingFields,
   parsePkMap,
   rawCall,
@@ -35,26 +47,27 @@ import {
   resolveContext,
   setActivePlatform,
   status,
+  stringifyBigIntJSON,
   switchUser,
   toExitCode,
+  updatePlatformConfig,
   use,
   validateFixturePath,
-  whoami,
-  writePlatformConfig
-} from "./chunk-PC2F54XD.js";
+  whoami
+} from "./chunk-Z2NRTUB3.js";
 
 // src/cli.ts
-import { Command as Command17 } from "commander";
+import { Command as Command16 } from "commander";
 
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.3",
+  version: "0.1.4",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
   engines: {
-    node: ">=22.19.0"
+    node: ">=24.19.0"
   },
   bin: {
     openbkn: "./dist/cli.js"
@@ -85,6 +98,9 @@ var package_default = {
     format: "biome format --write .",
     test: "vitest run",
     "test:e2e:trace-business": "npm run build && node test/e2e/bkn-trace-business-interaction.mjs",
+    "test:e2e:smoke": "npm run build && test/e2e/live-smoke.sh",
+    "test:e2e:suite": "npm run build && test/e2e/live-suite.sh",
+    "test:e2e:write": "npm run build && test/e2e/live-write.sh",
     "test:cover": "vitest run --coverage",
     ci: "npm run lint && npm test",
     prepublishOnly: "npm run ci && npm run build"
@@ -102,7 +118,7 @@ var package_default = {
   devDependencies: {
     "@biomejs/biome": "^1.9.4",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.13.0",
+    "@types/node": "^24.0.0",
     tsup: "^8.4.0",
     typescript: "^5.8.0",
     vitest: "^3.0.0"
@@ -181,7 +197,7 @@ function renderOrgTree(nodes, prefix = "") {
 // src/utils/output.ts
 function printJson(value, opts = {}) {
   if (opts.json || opts.compact) {
-    const json = JSON.stringify(value === void 0 ? null : value, null, opts.compact ? 0 : 2);
+    const json = stringifyBigIntJSON(value === void 0 ? null : value, opts.compact ? 0 : 2);
     process.stdout.write(`${json}
 `);
     return;
@@ -208,7 +224,7 @@ function printJson(value, opts = {}) {
     process.stdout.write("(no results)\n");
     return;
   }
-  process.stdout.write(`${JSON.stringify(value, null, 2)}
+  process.stdout.write(`${stringifyBigIntJSON(value, 2)}
 `);
 }
 function isEmptyEnvelope(value) {
@@ -307,7 +323,7 @@ function pad(s, width) {
 }
 function stringifyCell(v) {
   if (v === null || v === void 0) return "";
-  const raw = Array.isArray(v) && v.every((x) => x === null || typeof x !== "object") ? v.join(",") : typeof v === "object" ? JSON.stringify(v) : String(v);
+  const raw = Array.isArray(v) && v.every((x) => x === null || typeof x !== "object") ? v.join(",") : typeof v === "object" ? stringifyBigIntJSON(v) : String(v);
   const s = raw.replace(/\s+/g, " ").trim();
   return s.length > CELL_MAX ? `${s.slice(0, CELL_MAX - 1)}\u2026` : s;
 }
@@ -333,8 +349,26 @@ function promptLine(query, hidden = false) {
 
 // src/commands/_shared.ts
 import { readFileSync } from "fs";
+function platformOf(o) {
+  const baseUrl = (typeof o.baseUrl === "string" ? o.baseUrl : void 0) ?? process.env.BKN_BASE_URL ?? activePlatform();
+  return baseUrl?.replace(/\/+$/, "");
+}
+function transientIdentity(o) {
+  return Boolean(o.user || process.env.BKN_USER || o.token || process.env.BKN_TOKEN);
+}
+function conversationSource(o) {
+  const flag = typeof o.conversationId === "string" ? o.conversationId : void 0;
+  if (flag) return { id: flag, source: "flag" };
+  const env = process.env.BKN_CONVERSATION_ID;
+  if (env) return { id: env, source: "env" };
+  if (o.newConversation || transientIdentity(o)) return { source: "none" };
+  const baseUrl = platformOf(o);
+  const stored = baseUrl ? readPlatformConfig(baseUrl).conversationId : void 0;
+  return stored ? { id: stored, source: "stored" } : { source: "none" };
+}
 function traceOptionsFrom(o) {
-  const conversationId = (typeof o.conversationId === "string" ? o.conversationId : void 0) ?? process.env.BKN_CONVERSATION_ID;
+  const found = conversationSource(o);
+  const conversationId = found.source === "stored" ? void 0 : found.id;
   const interactionId = (typeof o.interactionId === "string" ? o.interactionId : void 0) ?? process.env.BKN_INTERACTION_ID;
   if (!conversationId && !interactionId) return void 0;
   return {
@@ -345,14 +379,36 @@ function traceOptionsFrom(o) {
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
   const trace = traceOptionsFrom(o);
-  return createClient({
+  const storeBaseUrl = platformOf(o);
+  const remembered = conversationSource(o);
+  const client = createClient({
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
     businessDomain: o.bizDomain,
     insecure: o.insecure,
-    ...trace ? { trace } : {}
+    ...trace ? { trace } : {},
+    ...remembered.source === "stored" && remembered.id ? { rememberedConversationId: remembered.id } : {},
+    // Remember a conversation this run opens, so the next command continues the
+    // same thread instead of starting a new one. Only for the active identity —
+    // `transientIdentity` explains which identities are left out.
+    // `--new-conversation` says "for this command", so it must not replace what
+    // it declined to use — otherwise one run with the flag would silently end
+    // the thread every other run was continuing.
+    ...transientIdentity(o) || o.newConversation ? {} : {
+      onConversationOpened: (conversationId) => {
+        if (!storeBaseUrl) return;
+        try {
+          updatePlatformConfig(storeBaseUrl, {
+            conversationId,
+            conversationOpenedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch {
+        }
+      }
+    }
   });
+  return client;
 }
 function outputOptions(cmd) {
   const o = cmd.optsWithGlobals();
@@ -366,7 +422,7 @@ function readBody(opts) {
   const raw = opts.bodyFile ? readFileSync(opts.bodyFile, "utf8") : opts.body;
   if (!raw) throw new InputError("Provide --body '<json>' or --body-file <path>.");
   try {
-    return JSON.parse(raw);
+    return parseBigIntJSON(raw);
   } catch {
     throw new InputError("Request body is not valid JSON.");
   }
@@ -967,7 +1023,7 @@ function adminCommand() {
     );
     const out = outputOptions(cmd);
     try {
-      printJson(JSON.parse(res.body), out);
+      printJson(parseBigIntJSON(res.body), out);
     } catch {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
@@ -1500,8 +1556,8 @@ function bknCommand() {
     printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
   });
   bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
-    "--embedding-model <id>",
-    "embedding model id for declared vector indexes (with --build)"
+    "--embedding-model <name-or-id>",
+    "small-model name (or numeric ID, resolved to its name) for declared vector indexes (with --build)"
   ).action(async (dir, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.push(dir, {
@@ -1530,7 +1586,10 @@ function bknCommand() {
   bkn.command("create-from-catalog <catalog-id>").description("Build a knowledge network from a Vega catalog's tables").requiredOption("--name <name>", "knowledge network name").option("--tables <list>", "comma-separated table names (default: all)").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,<table>:<col>...]'").option("--build", "submit a Vega build task per resource after creation").option(
     "--embedding-fields <map>",
     "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
-  ).option("--embedding-model <id>", "embedding model id for the vector index (with --build)").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
+  ).option(
+    "--embedding-model <name-or-id>",
+    "small-model name (or numeric ID, resolved to its name) for the vector index (with --build)"
+  ).option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).kn.createFromCatalog({
         catalogId,
@@ -1551,28 +1610,6 @@ function bknCommand() {
     printJson(result, outputOptions(cmd));
     if (!result.valid) process.exitCode = 1;
   });
-  bkn.command("create-from-csv <catalog-id>").description("Import CSV files into a Vega catalog, then build a KN from them").requiredOption("--files <glob>", "CSV paths (comma-separated or glob)").requiredOption("--name <name>", "knowledge network name").option("--table-prefix <s>", "prefix for derived table names", "").option("--batch-size <n>", "rows per insert batch", int4, 500).option("--tables <list>", "subset of imported tables to include in the KN").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,...]'").option("--build", "submit a Vega build task per resource after creation").option(
-    "--embedding-fields <map>",
-    "columns to vectorize per table (with --build): '<table>:<col>[+<col>...][,...]'"
-  ).option("--embedding-model <id>", "embedding model id for the vector index (with --build)").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
-    printJson(
-      await clientFrom(cmd).kn.createFromCsv({
-        catalogId,
-        name: opts.name,
-        files: opts.files,
-        tablePrefix: opts.tablePrefix,
-        batchSize: opts.batchSize,
-        tables: csv(opts.tables),
-        pkMap: opts.pkMap ? parsePkMap(opts.pkMap) : void 0,
-        build: Boolean(opts.build),
-        embeddingFields: opts.embeddingFields ? parseEmbeddingFields(opts.embeddingFields) : void 0,
-        embeddingModel: opts.embeddingModel,
-        noRollback: opts.rollback === false,
-        onProgress: (m) => console.error(m)
-      }),
-      outputOptions(cmd)
-    );
-  });
   return group(bkn, "AI DATA PLATFORM");
 }
 
@@ -1609,7 +1646,7 @@ function callCommand() {
     });
     const out = outputOptions(cmd2);
     try {
-      printJson(JSON.parse(res.body), out);
+      printJson(parseBigIntJSON(res.body), out);
     } catch {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
@@ -1646,7 +1683,7 @@ function configCommand() {
     if (key === "baseUrl") {
       setActivePlatform(value.replace(/\/+$/, ""));
     } else if (key === "businessDomain") {
-      writePlatformConfig(requireActive(), { businessDomain: value });
+      updatePlatformConfig(requireActive(), { businessDomain: value });
     } else {
       throw new InputError(`Unknown config key: ${key} (expected baseUrl | businessDomain)`);
     }
@@ -1654,7 +1691,7 @@ function configCommand() {
   });
   config.command("set-bd <value>").description("Set the default business domain for the active platform").action((value, _opts, cmd) => {
     const baseUrl = requireActive();
-    writePlatformConfig(baseUrl, { businessDomain: value });
+    updatePlatformConfig(baseUrl, { businessDomain: value });
     printJson({ baseUrl, businessDomain: value }, outputOptions(cmd));
   });
   config.command("list-bd").description("List business domains (requires login)").action(() => {
@@ -1674,7 +1711,7 @@ function buildArgs(opts) {
   let out = {};
   if (opts.args) {
     try {
-      out = JSON.parse(opts.args);
+      out = parseBigIntJSON(opts.args);
     } catch {
       throw new InputError("--args must be valid JSON");
     }
@@ -1685,7 +1722,7 @@ function buildArgs(opts) {
     const key = pair.slice(0, idx);
     const raw = pair.slice(idx + 1);
     try {
-      out[key] = JSON.parse(raw);
+      out[key] = parseBigIntJSON(raw);
     } catch {
       out[key] = raw;
     }
@@ -1723,7 +1760,7 @@ function contextCommand() {
   cmd.command("query-object-instance <kn-id>").description("Query object instances (provide --args as JSON)").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
     let args;
     try {
-      args = JSON.parse(opts.args);
+      args = parseBigIntJSON(opts.args);
     } catch {
       throw new InputError("--args must be valid JSON");
     }
@@ -1745,6 +1782,36 @@ function contextCommand() {
   cmd.command("relation-types <kn-id> <ids...>").description("Full definitions for the given relation-type ids (unmatched \u2192 `missing`)").action(async (knId, ids, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).context.relationTypes(knId, ids), outputOptions(cmd2));
   });
+  cmd.command("conversation").description("Show the remembered conversation, or forget it with --forget").option(
+    "--forget",
+    "drop it, so the next command opens a fresh conversation (acts on this machine's store for the active user, whatever identity the request would use)"
+  ).action((opts, cmd2) => {
+    const o = cmd2.optsWithGlobals();
+    const baseUrl = platformOf(o);
+    if (!baseUrl) throw new InputError("No platform. Run `openbkn auth login` first.");
+    const forgot = opts.forget ? readPlatformConfig(baseUrl).conversationId : void 0;
+    if (opts.forget) {
+      updatePlatformConfig(baseUrl, {
+        conversationId: void 0,
+        conversationOpenedAt: void 0
+      });
+    }
+    const { id, source } = conversationSource(o);
+    const stored = readPlatformConfig(baseUrl);
+    printJson(
+      {
+        baseUrl,
+        conversationId: id ?? null,
+        source,
+        ...stored.conversationOpenedAt ? { storedOpenedAt: stored.conversationOpenedAt } : {},
+        // What is on disk, even when something outranks it — otherwise
+        // `--forget` looks like a no-op to whoever just ran this.
+        ...stored.conversationId && stored.conversationId !== id ? { storedConversationId: stored.conversationId } : {},
+        ...opts.forget ? { forgot: forgot ?? null } : {}
+      },
+      outputOptions(cmd2)
+    );
+  });
   cmd.command("info").description("List the deploy's MCP tool catalog (global \u2014 no KN needed)").action(async (_opts, cmd2) => {
     printToolList(await clientFrom(cmd2).context.info(), outputOptions(cmd2));
   });
@@ -1791,7 +1858,7 @@ function contextCommand() {
     let args;
     if (opts.args) {
       try {
-        args = JSON.parse(opts.args);
+        args = parseBigIntJSON(opts.args);
       } catch {
         throw new InputError("--args must be valid JSON");
       }
@@ -1800,7 +1867,7 @@ function contextCommand() {
   });
   const jsonArgs = (raw) => {
     try {
-      return JSON.parse(raw);
+      return parseBigIntJSON(raw);
     } catch {
       throw new InputError("--args must be valid JSON");
     }
@@ -1826,88 +1893,10 @@ function contextCommand() {
   return group(cmd, "AI DATA PLATFORM");
 }
 
-// src/commands/dataflow.ts
-import { Command as Command9 } from "commander";
-var int6 = (v) => Number.parseInt(v, 10);
-function dataflowCommand() {
-  const cmd = new Command9("dataflow").description("Dataflow document workflows \u2014 list, runs, logs");
-  cmd.command("list").description("List all dataflows").action(async (_opts, cmd2) => {
-    printJson(await clientFrom(cmd2).dataflows.list(), outputOptions(cmd2));
-  });
-  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").option("--limit <n>", "page size (backend default 20)", int6).option("--page <n>", "page (0-based; backend default 0)", int6).action(async (dagId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.runs(dagId, {
-        since: opts.since,
-        page: opts.page,
-        limit: opts.limit
-      }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("logs <dagId> <instanceId>").description("Show logs for one run").option("--page <n>", "page", int6, 0).option("--limit <n>", "page size", int6, DEFAULT_LIST_LIMIT).action(async (dagId, instanceId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.logs(dagId, instanceId, {
-        page: opts.page,
-        limit: opts.limit
-      }),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("run <dagId>").description("Trigger a dataflow run from a remote file URL").requiredOption("--url <url>", "remote file URL").requiredOption("--name <name>", "file name").action(async (dagId, opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.run(dagId, opts.url, opts.name),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("create").description("Create a dataflow (DAG) from a full document body (--body / --body-file)").option("--body <json>", "dataflow document JSON").option("--body-file <path>", "read the dataflow document JSON from a file").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).dataflows.create(readBody(opts)), outputOptions(cmd2));
-  });
-  const parseSet = (pairs) => {
-    const out = {};
-    for (const item of pairs ?? []) {
-      const i = item.indexOf("=");
-      if (i > 0) out[item.slice(0, i)] = item.slice(i + 1);
-    }
-    return out;
-  };
-  cmd.command("templates").description("List available dataset/bkn/dataflow templates").action(async (_opts, cmd2) => {
-    printJson(clientFrom(cmd2).dataflows.templates(), outputOptions(cmd2));
-  });
-  cmd.command("create-dataset").description("Create a dataset from a template (--template <name> --set k=v ...)").requiredOption("--template <name>", "template name").option(
-    "--set <kv...>",
-    "set a template argument (key=value); repeatable",
-    (v, acc) => {
-      acc.push(v);
-      return acc;
-    },
-    []
-  ).action(async (opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.createDataset(opts.template, parseSet(opts.set)),
-      outputOptions(cmd2)
-    );
-  });
-  cmd.command("create-bkn").description("Create a knowledge network from a template (--template <name> --set k=v ...)").requiredOption("--template <name>", "template name").option(
-    "--set <kv...>",
-    "set a template argument (key=value); repeatable",
-    (v, acc) => {
-      acc.push(v);
-      return acc;
-    },
-    []
-  ).action(async (opts, cmd2) => {
-    printJson(
-      await clientFrom(cmd2).dataflows.createBkn(opts.template, parseSet(opts.set)),
-      outputOptions(cmd2)
-    );
-  });
-  return group(cmd, "AI DATA PLATFORM");
-}
-
 // src/commands/explore.ts
 import { createServer } from "http";
-import { Command as Command10 } from "commander";
-var int7 = (v) => Number.parseInt(v, 10);
+import { Command as Command9 } from "commander";
+var int6 = (v) => Number.parseInt(v, 10);
 var ROUTES = {
   "GET /api/bkn/meta": (c, q) => c.kn.get(req(q, "knId")),
   "POST /api/bkn/search": (c, _q, b) => c.kn.search(str(b.knId), str(b.query), {
@@ -1938,7 +1927,7 @@ function readBody2(reqMsg) {
     reqMsg.on("end", () => {
       if (!data.trim()) return resolve2({});
       try {
-        resolve2(JSON.parse(data));
+        resolve2(parseBigIntJSON(data));
       } catch {
         reject(new Error("invalid JSON body"));
       }
@@ -1951,10 +1940,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 Command10("explore").description(
+  const cmd = new Command9("explore").description(
     "Start a local web server with read-only bkn + vega JSON endpoints"
   );
-  cmd.option("--port <n>", "port to listen on", int7, 7777).option("--host <h>", "host to bind", "127.0.0.1").action(async (opts, command) => {
+  cmd.option("--port <n>", "port to listen on", int6, 7777).option("--host <h>", "host to bind", "127.0.0.1").action(async (opts, command) => {
     const client = clientFrom(command);
     const server = createServer((reqMsg, res) => {
       void handle(client, reqMsg, res);
@@ -1984,7 +1973,7 @@ async function handle(client, reqMsg, res) {
     const body = method === "GET" ? {} : await readBody2(reqMsg);
     const data = await handler(client, url.searchParams, body);
     res.writeHead(200, { "content-type": "application/json" });
-    res.end(JSON.stringify(data ?? null));
+    res.end(stringifyBigIntJSON(data ?? null));
   } catch (err) {
     res.writeHead(500, { "content-type": "application/json" });
     res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
@@ -1992,8 +1981,8 @@ async function handle(client, reqMsg, res) {
 }
 
 // src/commands/model.ts
-import { Command as Command11 } from "commander";
-var int8 = (v) => Number.parseInt(v, 10);
+import { Command as Command10 } from "commander";
+var int7 = (v) => Number.parseInt(v, 10);
 async function resolveLlmModelName(client, model) {
   if (!/^\d+$/.test(model)) return model;
   const detail = await client.models.llm.get(model);
@@ -2015,11 +2004,11 @@ function addManagementCommands(parent, kind) {
   });
 }
 function modelCommand() {
-  const model = new Command11("model").description(
+  const model = new Command10("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", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 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", int7, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int7, 1).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.llm.list({
         name: opts.name,
@@ -2052,7 +2041,7 @@ function modelCommand() {
   });
   addManagementCommands(llm, "llm");
   const small = model.command("small").description("Small models (embedding / reranker)");
-  small.command("list").description("List small models").option("--name <s>", "filter by name").option("--type <t>", "model type filter").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int8, 1).action(async (opts, cmd) => {
+  small.command("list").description("List small models").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) => {
     printJson(
       await clientFrom(cmd).models.small.list({
         name: opts.name,
@@ -2066,13 +2055,13 @@ function modelCommand() {
   small.command("get <modelId>").description("Get a small model").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).models.small.get(id), outputOptions(cmd));
   });
-  small.command("embeddings <modelId>").description("Compute embeddings").requiredOption("-i, --input <text>", "comma-separated input texts").action(async (id, opts, cmd) => {
+  small.command("embeddings <model>").description("Compute embeddings (<model> = model name or numeric id)").requiredOption("-i, --input <text>", "comma-separated input texts").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.embeddings(id, csv(opts.input) ?? []),
       outputOptions(cmd)
     );
   });
-  small.command("rerank <modelId>").description("Rerank documents against a query").requiredOption("-q, --query <text>", "query").requiredOption("-d, --documents <list>", "comma-separated documents").action(async (id, opts, cmd) => {
+  small.command("rerank <model>").description("Rerank documents against a query (<model> = model name or numeric id)").requiredOption("-q, --query <text>", "query").requiredOption("-d, --documents <list>", "comma-separated documents").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).models.small.rerank(id, opts.query, csv(opts.documents) ?? []),
       outputOptions(cmd)
@@ -2107,38 +2096,27 @@ Examples:
 }
 
 // src/commands/resource.ts
-import { Command as Command12 } from "commander";
-var int9 = (v) => Number.parseInt(v, 10);
-var parsePairs = (raw) => {
-  if (!raw) return void 0;
-  return raw.split(",").map((part) => {
-    const idx = part.indexOf("=");
-    if (idx < 1) throw new Error("--extension must be key=value[,key=value]");
-    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
-  }).filter((p) => p.key.length > 0);
-};
+import { Command as Command11 } from "commander";
+var int8 = (v) => Number.parseInt(v, 10);
 function resourceCommand() {
-  const cmd = new Command12("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
-  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--datasource-id <id>", "alias of --catalog-id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int9, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd2) => {
+  const cmd = new Command11("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
+  cmd.command("list").description("List resources under a catalog").option("--catalog-id <id>", "filter by catalog id").option("--category <c>", "resource category (table | logicview | dataset)").option("--type <c>", "alias of --category").option("--status <status>", "filter by status").option("--schema <name>", "filter by source schema").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int8, 0).option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.list({
-      datasourceId: opts.catalogId ?? opts.datasourceId,
+      catalogId: opts.catalogId,
       category: opts.category ?? opts.type,
       status: opts.status,
-      database: opts.database,
+      schema: opts.schema,
       limit: opts.limit,
       offset: opts.offset,
-      includeExtensions: opts.includeExtensions,
-      includeExtensionKeys: opts.includeExtensionKeys,
-      extensionPairs: parsePairs(opts.extension),
       sort: opts.sort,
       direction: opts.direction
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").option("--limit <n>", "rows to scan before filtering", int9, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
+  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--limit <n>", "rows to scan before filtering", int8, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
-      datasourceId: opts.catalogId ?? opts.datasourceId,
+      catalogId: opts.catalogId,
       limit: opts.limit
     });
     printJson(data, outputOptions(cmd2));
@@ -2146,7 +2124,7 @@ function resourceCommand() {
   cmd.command("get <id>").description("Get resource details").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.get(id), outputOptions(cmd2));
   });
-  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int9).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
+  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int8, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int8, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int8).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.query(id, {
       limit: opts.limit,
       offset: opts.offset,
@@ -2164,8 +2142,8 @@ function resourceCommand() {
 }
 
 // src/commands/skill.ts
-import { Command as Command13 } from "commander";
-var int10 = (v) => Number.parseInt(v, 10);
+import { Command as Command12 } from "commander";
+var int9 = (v) => Number.parseInt(v, 10);
 var positiveInt = (flag) => (v) => {
   if (!/^\d+$/.test(v)) {
     throw new InputError(`${flag} must be a positive integer (got '${v}')`);
@@ -2190,8 +2168,8 @@ function checkSource(source) {
 }
 var draftOption = (c) => c.option("--draft", "read the draft (management) version instead of the published one");
 function skillCommand() {
-  const cmd = new Command13("skill").description("Skill registry and market");
-  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int10, 1);
+  const cmd = new Command12("skill").description("Skill registry and market");
+  const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int9, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int9, 1);
   listOpts(cmd.command("list").description("List skills")).option("--create-user <s>", "filter by creator").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).skills.list({
@@ -2329,7 +2307,7 @@ ${files.length} files, ${bytes} B
     );
   });
   cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
-    const extendInfo = opts.extendInfo ? JSON.parse(opts.extendInfo) : void 0;
+    const extendInfo = opts.extendInfo ? parseBigIntJSON(opts.extendInfo) : void 0;
     printJson(
       await clientFrom(cmd2).skills.register(dir, {
         source: checkSource(opts.source),
@@ -2369,11 +2347,11 @@ ${files.length} files, ${bytes} B
 }
 
 // src/commands/toolbox.ts
-import { Command as Command14 } from "commander";
-var int11 = (v) => Number.parseInt(v, 10);
+import { Command as Command13 } from "commander";
+var int10 = (v) => Number.parseInt(v, 10);
 function toolboxCommand() {
-  const cmd = new Command14("toolbox").description("Agent toolbox lifecycle");
-  cmd.command("list").description("List toolboxes").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).action(async (opts, cmd2) => {
+  const cmd = new Command13("toolbox").description("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) => {
     printJson(
       await clientFrom(cmd2).toolboxes.list({
         keyword: opts.keyword,
@@ -2414,8 +2392,8 @@ function toolboxCommand() {
   return group(cmd, "DECISION AGENT");
 }
 function toolCommand() {
-  const cmd = new Command14("tool").description("Tools inside a toolbox");
-  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int11).option("--page <n>", "page (1-based; backend default 1)", int11).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
+  const cmd = new Command13("tool").description("Tools inside a toolbox");
+  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int10).option("--page <n>", "page (1-based; backend default 1)", int10).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
         page: opts.page,
@@ -2437,17 +2415,17 @@ function toolCommand() {
       outputOptions(cmd2)
     );
   });
-  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option("--body <json>", "request body JSON").option("--header <json>", "headers map JSON").option("--query <json>", "query params JSON").option("--path <json>", "path params JSON").option("--timeout <s>", "per-call timeout seconds", int11);
+  const invokeOpts = (c) => c.requiredOption("--toolbox <box-id>", "toolbox id").option("--body <json>", "request body JSON").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 parseJson = (s, label) => {
     if (!s) return void 0;
     try {
-      return JSON.parse(s);
+      return parseBigIntJSON(s);
     } catch {
       throw new InputError(`--${label} must be valid JSON`);
     }
   };
   const buildEnvelope = (opts) => ({
-    body: opts.body ? JSON.parse(opts.body) : void 0,
+    body: opts.body ? parseBigIntJSON(opts.body) : void 0,
     header: parseJson(opts.header, "header"),
     query: parseJson(opts.query, "query"),
     path: parseJson(opts.path, "path"),
@@ -2480,7 +2458,7 @@ function toolCommand() {
 
 // src/commands/trace.ts
 import { readFileSync as readFileSync5, writeFileSync } from "fs";
-import { Command as Command15 } from "commander";
+import { Command as Command14 } from "commander";
 
 // src/bkn-trace/schema-validate.ts
 import { readFileSync as readFileSync4 } from "fs";
@@ -2523,7 +2501,7 @@ function parseFile(file) {
   const text = readFileSync4(file, "utf8");
   const ext = extname(file).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") return yaml.load(text);
-  return JSON.parse(text);
+  return parseBigIntJSON(text);
 }
 function inferKind(data) {
   if (data && typeof data === "object" && !Array.isArray(data)) {
@@ -2557,8 +2535,43 @@ function validateSchemaFile(file, kind) {
 }
 
 // src/commands/trace.ts
+function renderPayload(payload) {
+  if (!payload) return "-";
+  if (payload.mode === "inline") return stringifyBigIntJSON(payload.inline);
+  if (payload.mode === "referenced") return `[referenced] ${payload.ref ?? "-"}`;
+  return `[omitted] ${payload.omitted_reason ?? "unknown"}`;
+}
+function renderTechnicalTraceDetail(detail) {
+  const lines = [
+    `Trace: ${detail.summary.trace_id}`,
+    `Status: ${detail.summary.status}`,
+    `Request: ${detail.summary.request_id || "-"}`,
+    `Question: ${detail.summary.question_preview || "-"}`,
+    `Result: ${detail.summary.result_preview || "-"}`,
+    `Service: ${detail.summary.root_service || "-"}`,
+    `Spans: ${detail.graph?.data.nodes.length ?? 0}`
+  ];
+  if (detail.partial) {
+    lines.push(`Partial: ${(detail.partial_reasons ?? []).join(", ") || "yes"}`);
+  }
+  for (const operation of detail.operations) {
+    lines.push(
+      "",
+      `${operation.fact.tool_name} \xB7 ${operation.fact.operation_id} \xB7 attempt ${operation.fact.attempt} \xB7 ${operation.state}`,
+      `Source: ${operation.fact.protocol}/${operation.fact.source_module}`,
+      `Input: ${renderPayload(operation.fact.input)}`
+    );
+    if (operation.fact.output) lines.push(`Output: ${renderPayload(operation.fact.output)}`);
+    if (operation.fact.error) lines.push(`Error: ${renderPayload(operation.fact.error)}`);
+    if (operation.partial_reasons?.length) {
+      lines.push(`Partial: ${operation.partial_reasons.join(", ")}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
 function traceCommand() {
-  const cmd = new Command15("trace").description(
+  const cmd = new Command14("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) => {
@@ -2633,6 +2646,12 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
+  interactions.command("operations <interaction-id>").description("List the exact Operation call facts for one interaction").action(async (interactionId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.listInteractionOperations(interactionId),
+      outputOptions(cmd2)
+    );
+  });
   for (const action of ["complete", "fail", "cancel", "handoff"]) {
     interactions.command(`${action} <interaction-id>`).description(`${action} a managed interaction using a 3.0 completion manifest`).requiredOption("--body-file <path>", "read completion manifest JSON from a protected file").action(async (interactionId, opts, cmd2) => {
       const input = readBody(opts);
@@ -2653,6 +2672,16 @@ function traceCommand() {
       outputOptions(cmd2)
     );
   });
+  operations.command("attempt <operation-id> <attempt>").description("Get one exact Operation attempt call fact").action(async (operationId, attempt, _opts, cmd2) => {
+    if (!/^[1-9]\d*$/.test(attempt)) {
+      throw new InputError("attempt must be a positive integer");
+    }
+    const ordinal = Number.parseInt(attempt, 10);
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getOperationAttempt(operationId, ordinal),
+      outputOptions(cmd2)
+    );
+  });
   operations.command("retry <operation-id>").description("Create the next retry attempt for an eligible failed operation").requiredOption("--body-file <path>", "read retry request JSON from a protected file").action(async (operationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.lifecycle.retryOperationAttempt(
@@ -2666,14 +2695,41 @@ function traceCommand() {
   receipts.command("get <receipt-id>").description("Get an authorized operation receipt").action(async (receiptId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).trace.lifecycle.getReceipt(receiptId), outputOptions(cmd2));
   });
-  cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
+  cmd.command("get <conversation-id>").description("Fetch normalized spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("search").description("Raw trace search (--body / --body-file OpenSearch JSON)").option("--body <json>", "search body JSON").option("--body-file <path>", "read search body JSON from a file").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).trace.search(readBody(opts)), outputOptions(cmd2));
+  cmd.command("detail <trace-id>").description("Get one typed technical trace with Span and Operation facts").action(async (traceId, _opts, cmd2) => {
+    const detail = await clientFrom(cmd2).trace.get(traceId);
+    const output = outputOptions(cmd2);
+    if (output.json || output.compact) printJson(detail, output);
+    else process.stdout.write(renderTechnicalTraceDetail(detail));
+  });
+  cmd.command("spans <conversation-id>").description("Fetch normalized spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("search").description("List authorized technical traces").option("--limit <n>", "page size, 1..200", (value) => Number.parseInt(value, 10)).option("--cursor <cursor>", "opaque pagination cursor").option("--from <time>", "started at or after this RFC3339 timestamp").option("--to <time>", "started at or before this RFC3339 timestamp").option("--status <status>", "execution status").option("--service <service>", "exact producing service").option("--tool <tool>", "exact root tool").option("--trace-id <id>", "exact Trace ID").option("--error-keyword <text>", "case-insensitive error text").option("--conversation-id <id>", "exact conversation ID").option("--interaction-id <id>", "exact interaction ID").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.search({
+        limit: opts.limit,
+        cursor: opts.cursor,
+        from: opts.from,
+        to: opts.to,
+        status: opts.status,
+        service: opts.service,
+        tool: opts.tool,
+        traceId: opts.traceId,
+        errorKeyword: opts.errorKeyword,
+        conversationId: opts.conversationId,
+        interactionId: opts.interactionId
+      }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("diagnose <conversation-id>").description("Diagnose a conversation's trace (symbolic rules; --llm adds rubric judging)").option("--llm", "also run LLM-judged rubric rules via the local `claude` CLI").action(async (conversationId, opts, cmd2) => {
     const report = await clientFrom(cmd2).trace.diagnose(conversationId, {
@@ -2692,17 +2748,17 @@ 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(readFileSync5(queriesFile, "utf8"));
+    const raw = parseBigIntJSON(readFileSync5(queriesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     if (opts.out) {
-      writeFileSync(opts.out, JSON.stringify({ cases }, null, 2));
+      writeFileSync(opts.out, stringifyBigIntJSON({ cases }, 2));
       printJson({ out: opts.out, cases: cases.length }, outputOptions(cmd2));
     } else {
       printJson({ cases }, outputOptions(cmd2));
     }
   });
   evalSet.command("test <cases-file>").description("Run an eval set against an agent (--llm enables semantic_match)").requiredOption("--agent <id>", "agent id to run the queries against").option("--version <v>", "agent version", "v0").option("--llm", "enable semantic_match assertions via the local `claude` CLI").action(async (casesFile, opts, cmd2) => {
-    const raw = JSON.parse(readFileSync5(casesFile, "utf8"));
+    const raw = parseBigIntJSON(readFileSync5(casesFile, "utf8"));
     const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
     const result = await clientFrom(cmd2).trace.evalSetTest(opts.agent, cases, {
       version: opts.version,
@@ -2726,8 +2782,28 @@ function traceCommand() {
 }
 
 // src/commands/vega.ts
-import { Command as Command16 } from "commander";
-var int12 = (v) => Number.parseInt(v, 10);
+import { Command as Command15 } from "commander";
+var int11 = (value) => {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new InputError(`expected an integer, received "${value}"`);
+  }
+  return parsed;
+};
+var expectedUpdateTime = (value) => {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new InputError("--expected-update-time must be a positive integer timestamp");
+  }
+  return parsed;
+};
+var confidenceThreshold = (value) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new InputError("--confidence-threshold must be a number between 0 and 1");
+  }
+  return parsed;
+};
 var bool = (value) => {
   if (value === "true") return true;
   if (value === "false") return false;
@@ -2736,7 +2812,7 @@ var bool = (value) => {
 var parseJsonObject = (value, flag) => {
   let parsed;
   try {
-    parsed = JSON.parse(value);
+    parsed = parseBigIntJSON(value);
   } catch {
     throw new InputError(`${flag} must be valid JSON`);
   }
@@ -2745,10 +2821,15 @@ var parseJsonObject = (value, flag) => {
   }
   return parsed;
 };
-var parseStringRecord = (value, flag) => {
-  const parsed = parseJsonObject(value, flag);
-  if (Object.values(parsed).some((item) => typeof item !== "string")) {
-    throw new InputError(`${flag} values must be strings`);
+var parseJsonArray = (value, flag) => {
+  let parsed;
+  try {
+    parsed = parseBigIntJSON(value);
+  } catch {
+    throw new InputError(`${flag} must be valid JSON`);
+  }
+  if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "object" || item === null || Array.isArray(item))) {
+    throw new InputError(`${flag} must be a JSON array of objects`);
   }
   return parsed;
 };
@@ -2771,20 +2852,133 @@ var healthCheckSchedule = (mode, cronExpr) => {
   }
   throw new InputError("health-check mode must be inherit, enabled, or disabled");
 };
-var parsePairs2 = (raw) => {
-  if (!raw) return void 0;
-  return raw.split(",").map((part) => {
-    const idx = part.indexOf("=");
-    if (idx < 1) throw new InputError("--extension must be key=value[,key=value]");
-    return { key: part.slice(0, idx).trim(), value: part.slice(idx + 1).trim() };
-  }).filter((p) => p.key.length > 0);
+var buildTaskStatuses = (raw) => {
+  if (raw === void 0) return void 0;
+  const statuses = csv(raw);
+  if (!statuses?.length) {
+    throw new InputError("--status must include at least one build status");
+  }
+  return statuses.map((status2) => {
+    const parsed = BuildTaskStatus.safeParse(status2);
+    if (!parsed.success) {
+      throw new InputError(
+        `invalid build status "${status2}"; expected one of ${BuildTaskStatus.options.join(", ")}`
+      );
+    }
+    return parsed.data;
+  });
+};
+var buildTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = BuildTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid build task sort "${raw}"; expected one of ${BuildTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverStrategy = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverStrategy.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover strategy "${raw}"; expected one of ${DiscoverStrategy.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var requiredDiscoverStrategy = (raw) => discoverStrategy(raw);
+var taskStatuses = (raw) => {
+  if (raw === void 0) return void 0;
+  const values = csv(raw);
+  if (!values?.length) throw new InputError("--status must include at least one task status");
+  return values.map((value) => {
+    const parsed = VegaTaskStatus.safeParse(value);
+    if (!parsed.success) {
+      throw new InputError(
+        `invalid task status "${value}"; expected one of ${VegaTaskStatus.options.join(", ")}`
+      );
+    }
+    return parsed.data;
+  });
+};
+var semanticScope = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingScope.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic task scope "${raw}"; expected one of ${SemanticUnderstandingScope.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var semanticApplyMode = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingApplyMode.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic apply mode "${raw}"; expected one of ${SemanticUnderstandingApplyMode.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverScheduleSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverScheduleSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover schedule sort "${raw}"; expected one of ${DiscoverScheduleSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover task sort "${raw}"; expected one of ${DiscoverTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var discoverTaskTriggerType = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = DiscoverTaskTriggerType.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid discover task trigger type "${raw}"; expected one of ${DiscoverTaskTriggerType.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var semanticTaskSort = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SemanticUnderstandingTaskSort.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid semantic task sort "${raw}"; expected one of ${SemanticUnderstandingTaskSort.options.join(", ")}`
+    );
+  }
+  return parsed.data;
+};
+var sortDirection = (raw) => {
+  if (raw === void 0) return void 0;
+  const parsed = SortDirection.safeParse(raw);
+  if (!parsed.success) {
+    throw new InputError(
+      `invalid sort direction "${raw}"; expected one of ${SortDirection.options.join(", ")}`
+    );
+  }
+  return parsed.data;
 };
 function vegaCommand() {
-  const vega = new Command16("vega").description(
+  const vega = new Command15("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).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--type <type>", "filter by catalog type: physical | logical").option("--enabled <bool>", "filter by enabled state").option("--health-check-status <s>", "filter by health status").option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (_opts, cmd) => {
+  catalog.command("list").description("List catalog entries").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--name <s>", "filter by name").option("--tag <s>", "filter by tag").option("--type <type>", "filter by catalog type: physical | logical").option("--connector-type <type>", "filter by connector type").option("--enabled <bool>", "filter by enabled state").option("--health-check-status <s>", "filter by health status").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (_opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const data = await clientFrom(cmd).vega.catalogs({
       limit: o.limit,
@@ -2792,11 +2986,9 @@ function vegaCommand() {
       name: o.name,
       tag: o.tag,
       type: o.type,
+      connectorType: o.connectorType,
       enabled: o.enabled === void 0 ? void 0 : o.enabled === "true",
       healthCheckStatus: o.healthCheckStatus,
-      includeExtensions: o.includeExtensions,
-      includeExtensionKeys: o.includeExtensionKeys,
-      extensionPairs: parsePairs2(o.extension),
       sort: o.sort,
       direction: o.direction
     });
@@ -2805,7 +2997,7 @@ function vegaCommand() {
   catalog.command("get <id>").description("Get a catalog by id").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.getCatalog(id), outputOptions(cmd));
   });
-  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (backend default 20, max 1000; -1 = all)", int12).option("--offset <n>", "page offset", int12, 0).action(async (id, opts, cmd) => {
+  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (default 30, max 1000; -1 = all)", int11).option("--offset <n>", "page offset", int11, 0).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
       outputOptions(cmd)
@@ -2814,9 +3006,8 @@ function vegaCommand() {
   catalog.command("health <id>").description("Health-status for a catalog").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealth(id), outputOptions(cmd));
   });
-  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
     const connectorConfig = parseJsonObject(opts.connectorConfig, "--connector-config");
-    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
       await clientFrom(cmd).vega.createCatalog(
         {
@@ -2828,7 +3019,6 @@ function vegaCommand() {
           description: opts.description,
           enabled: opts.enabled ? true : void 0,
           internal: opts.internal ? true : void 0,
-          extensions,
           healthCheckSchedule: healthCheckSchedule(opts.healthCheckMode, opts.healthCheckCron)
         },
         { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
@@ -2836,9 +3026,12 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
+  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
     const connectorConfig = opts.connectorConfig ? parseJsonObject(opts.connectorConfig, "--connector-config") : void 0;
-    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
       await clientFrom(cmd).vega.updateCatalog(
         id,
@@ -2849,7 +3042,7 @@ function vegaCommand() {
           tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
           description: opts.description,
           enabled: opts.enabled,
-          extensions
+          expectedUpdateTime: opts.expectedUpdateTime
         },
         { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
       ),
@@ -2862,8 +3055,9 @@ function vegaCommand() {
   catalog.command("disable <id>").description("Disable a catalog").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.disableCatalog(id), outputOptions(cmd));
   });
-  catalog.command("delete <id>").description("Delete a catalog").action(async (id, _opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.deleteCatalog(id), outputOptions(cmd));
+  catalog.command("delete <id>").description("Delete a catalog").option("--dry-run", "preview deletion impact without changing data").action(async (id, opts, cmd) => {
+    const result = opts.dryRun ? await clientFrom(cmd).vega.deleteCatalog(id, { dryRun: true }) : await clientFrom(cmd).vega.deleteCatalog(id);
+    printJson(result, outputOptions(cmd));
   });
   catalog.command("test-connection <id>").description("Test a catalog connection").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.testCatalogConnection(id), outputOptions(cmd));
@@ -2880,17 +3074,182 @@ function vegaCommand() {
   catalog.command("health-check-schedule <id>").description("Get a catalog health-check schedule").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.catalogHealthCheckSchedule(id), outputOptions(cmd));
   });
-  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").action(async (id, opts, cmd) => {
+  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).action(async (id, opts, cmd) => {
     const schedule = healthCheckSchedule(opts.mode, opts.cron);
     if (!schedule) throw new InputError("--mode is required");
     printJson(
-      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, schedule),
+      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, {
+        ...schedule,
+        expectedUpdateTime: opts.expectedUpdateTime
+      }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverCatalog(id, {
+        strategy: discoverStrategy(opts.strategy)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  const discoverSchedule = vega.command("discover-schedule").description("Resource discovery schedules");
+  discoverSchedule.command("list").description("List discovery schedules").option("--name <s>", "filter by name").option("--catalog-id <id>", "filter by catalog id").option("--enabled <bool>", "filter by enabled state", bool).option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "name | create_time | update_time | next_run").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverSchedules({
+        name: opts.name,
+        catalogId: opts.catalogId,
+        enabled: opts.enabled,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: discoverScheduleSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  discoverSchedule.command("get <id>").description("Get a discovery schedule").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getDiscoverSchedule(id), outputOptions(cmd));
+  });
+  discoverSchedule.command("create").description("Create a discovery schedule").requiredOption("--name <s>", "schedule name").requiredOption("--catalog-id <id>", "catalog id").requiredOption("--cron <expr>", "five-field cron expression").option("--start-time <ms>", "start time", int11).option("--end-time <ms>", "end time", int11).option("--enabled", "create enabled").option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.createDiscoverSchedule({
+        name: opts.name,
+        catalogId: opts.catalogId,
+        cronExpr: opts.cron,
+        startTime: opts.startTime,
+        endTime: opts.endTime,
+        enabled: opts.enabled ? true : void 0,
+        strategy: discoverStrategy(opts.strategy)
+      }),
       outputOptions(cmd)
     );
   });
-  catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--wait", "wait for discovery to complete").action(async (id, opts, cmd) => {
+  discoverSchedule.command("update <id>").description("Fully update a discovery schedule").requiredOption("--name <s>", "schedule name").requiredOption("--catalog-id <id>", "current catalog id").requiredOption("--cron <expr>", "five-field cron expression").requiredOption("--enabled <bool>", "current enabled state", bool).requiredOption("--start-time <ms>", "start time (0 = no lower bound)", int11).requiredOption("--end-time <ms>", "end time (0 = no upper bound)", int11).requiredOption("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).requiredOption(
+    "--expected-update-time <ms>",
+    "optimistic-lock update time",
+    expectedUpdateTime
+  ).action(async (id, opts, cmd) => {
     printJson(
-      await clientFrom(cmd).vega.discoverCatalog(id, Boolean(opts.wait)),
+      await clientFrom(cmd).vega.updateDiscoverSchedule(id, {
+        name: opts.name,
+        catalogId: opts.catalogId,
+        cronExpr: opts.cron,
+        enabled: opts.enabled,
+        startTime: opts.startTime,
+        endTime: opts.endTime,
+        strategy: requiredDiscoverStrategy(opts.strategy),
+        expectedUpdateTime: opts.expectedUpdateTime
+      }),
+      outputOptions(cmd)
+    );
+  });
+  for (const action of ["enable", "disable", "delete"]) {
+    discoverSchedule.command(`${action} <id>`).description(`${action[0]?.toUpperCase()}${action.slice(1)} a discovery schedule`).action(async (id, _opts, cmd) => {
+      const api = clientFrom(cmd).vega;
+      const result = action === "enable" ? await api.enableDiscoverSchedule(id) : action === "disable" ? await api.disableDiscoverSchedule(id) : await api.deleteDiscoverSchedule(id);
+      printJson(result, outputOptions(cmd));
+    });
+  }
+  const discoverTask = vega.command("discover-task").description("Resource discovery tasks");
+  discoverTask.command("list").description("List discovery tasks").option("--catalog-id <id>", "filter by catalog id").option("--schedule-id <id>", "filter by schedule id").option("--status <status>", `comma-separated: ${VegaTaskStatus.options.join(" | ")}`).option("--strategy <strategy>", `strategy: ${DiscoverStrategy.options.join(" | ")}`).option("--trigger-type <type>", "manual | scheduled").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "create_time | start_time | finish_time | last_progress_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.discoverTasks({
+        catalogId: opts.catalogId,
+        scheduleId: opts.scheduleId,
+        status: taskStatuses(opts.status),
+        strategy: discoverStrategy(opts.strategy),
+        triggerType: discoverTaskTriggerType(opts.triggerType),
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: discoverTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  discoverTask.command("get <id>").description("Get a discovery task").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getDiscoverTask(id), outputOptions(cmd));
+  });
+  discoverTask.command("delete <ids...>").description("Delete completed discovery tasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.deleteDiscoverTasks(ids, {
+        ignoreMissing: opts.ignoreMissing
+      }),
+      outputOptions(cmd)
+    );
+  });
+  const semanticTask = vega.command("semantic-task").description("Semantic-understanding tasks");
+  semanticTask.command("list").description("List semantic-understanding tasks").option("--scope <scope>", `scope: ${SemanticUnderstandingScope.options.join(" | ")}`).option("--catalog-id <id>", "filter by catalog id").option("--resource-id <id>", "filter by resource id").option("--status <status>", `comma-separated: ${VegaTaskStatus.options.join(" | ")}`).option(
+    "--apply-mode <mode>",
+    `apply mode: ${SemanticUnderstandingApplyMode.options.join(" | ")}`
+  ).option("--applied <bool>", "filter by applied state", bool).option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "create_time | start_time | finish_time").option("--direction <dir>", "asc | desc").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.semanticUnderstandingTasks({
+        scope: semanticScope(opts.scope),
+        catalogId: opts.catalogId,
+        resourceId: opts.resourceId,
+        status: taskStatuses(opts.status),
+        applyMode: semanticApplyMode(opts.applyMode),
+        applied: opts.applied,
+        limit: opts.limit,
+        offset: opts.offset,
+        sort: semanticTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  semanticTask.command("create").description("Create a semantic-understanding task").requiredOption("--scope <scope>", "resource | catalog").option("--catalog-id <id>", "catalog id").option("--resource-id <id>", "resource id").option("--apply-mode <mode>", "dry_run | fill_empty | force").option("--confidence-threshold <n>", "minimum confidence (0..1)", confidenceThreshold).option("--include-sample-rows", "include resource sample rows").option("--sample-max-rows <n>", "sample row limit", int11).action(async (opts, cmd) => {
+    const scope = semanticScope(opts.scope);
+    if (!scope) throw new InputError("--scope is required");
+    const applyMode = semanticApplyMode(opts.applyMode);
+    if (scope === "catalog" && !opts.catalogId) {
+      throw new InputError("--catalog-id is required for catalog scope");
+    }
+    if (scope === "resource" && !opts.resourceId) {
+      throw new InputError("--resource-id is required for resource scope");
+    }
+    if (scope === "catalog" && (opts.includeSampleRows || opts.sampleMaxRows !== void 0)) {
+      throw new InputError("sample row options are only valid for resource scope");
+    }
+    if (scope === "resource" && opts.includeSampleRows && opts.sampleMaxRows === void 0) {
+      throw new InputError("--sample-max-rows is required with --include-sample-rows");
+    }
+    if (scope === "resource" && !opts.includeSampleRows && opts.sampleMaxRows !== void 0) {
+      throw new InputError("--sample-max-rows requires --include-sample-rows");
+    }
+    if (opts.sampleMaxRows !== void 0 && (opts.sampleMaxRows < 1 || opts.sampleMaxRows > 20)) {
+      throw new InputError("--sample-max-rows must be between 1 and 20");
+    }
+    const common = {
+      applyMode,
+      confidenceThreshold: opts.confidenceThreshold
+    };
+    const request = scope === "catalog" ? { scope: "catalog", catalogId: opts.catalogId, ...common } : {
+      scope: "resource",
+      resourceId: opts.resourceId,
+      includeSampleRows: opts.includeSampleRows ? true : void 0,
+      samplePolicy: opts.sampleMaxRows === void 0 ? void 0 : { masked: false, maxRows: opts.sampleMaxRows },
+      ...common
+    };
+    printJson(
+      await clientFrom(cmd).vega.createSemanticUnderstandingTask(request),
+      outputOptions(cmd)
+    );
+  });
+  semanticTask.command("get <id>").description("Get a semantic-understanding task").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.getSemanticUnderstandingTask(id), outputOptions(cmd));
+  });
+  semanticTask.command("delete <ids...>").description("Delete completed semantic-understanding tasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.deleteSemanticUnderstandingTasks(ids, {
+        ignoreMissing: opts.ignoreMissing
+      }),
       outputOptions(cmd)
     );
   });
@@ -2904,14 +3263,14 @@ function vegaCommand() {
   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(
+  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int11).option("--offset <n>", "first-page offset", int11).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int11).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int11).option(
     "-d, --data <json>",
     "full request body as JSON (advanced; wins over individual query flags)"
   ).action(async (opts, cmd) => {
     let body;
     if (opts.data) {
       try {
-        body = JSON.parse(opts.data);
+        body = parseBigIntJSON(opts.data);
       } catch {
         throw new InputError("--data must be valid JSON");
       }
@@ -2948,18 +3307,15 @@ function vegaCommand() {
     printJson(await clientFrom(cmd).vega.sql(body), outputOptions(cmd));
   });
   const resource = vega.command("resource").description("Vega-backend resources");
-  resource.command("list").description("List resources").option("--datasource-id <id>", "filter by catalog/datasource id").option("--catalog-id <id>", "alias of --datasource-id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--status <status>", "filter by status").option("--database <name>", "filter by database").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--include-extensions", "include all extension key/value pairs").option("--include-extension-keys <keys>", "include selected extension keys").option("--extension <k=v,...>", "filter by extension key/value pairs").option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd) => {
+  resource.command("list").description("List resources").option("--catalog-id <id>", "filter by catalog id").option("--type <category>", "resource category").option("--category <category>", "alias of --type").option("--status <status>", "filter by status").option("--schema <name>", "filter by source schema").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--sort <field>", "sort field: name | create_time | update_time").option("--direction <dir>", "sort direction: asc | desc").action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).resource.list({
-        datasourceId: opts.datasourceId ?? opts.catalogId,
+        catalogId: opts.catalogId,
         category: opts.type ?? opts.category,
         status: opts.status,
-        database: opts.database,
+        schema: opts.schema,
         limit: opts.limit,
         offset: opts.offset,
-        includeExtensions: opts.includeExtensions,
-        includeExtensionKeys: opts.includeExtensionKeys,
-        extensionPairs: parsePairs2(opts.extension),
         sort: opts.sort,
         direction: opts.direction
       }),
@@ -2969,17 +3325,59 @@ function vegaCommand() {
   resource.command("get <id>").description("Get a resource").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).resource.get(id), outputOptions(cmd));
   });
-  resource.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", (v) => Number.parseInt(v, 10), 50).option("--offset <n>", "row offset", (v) => Number.parseInt(v, 10), 0).action(async (id, opts, cmd) => {
+  resource.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int11, 50).option("--offset <n>", "row offset", int11, 0).action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).resource.query(id, { limit: opts.limit, offset: opts.offset }),
       outputOptions(cmd)
     );
   });
+  resource.command("document-get <resource-id> <document-id>").description("Get one dataset document").action(async (resourceId, documentId, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.getDocument(resourceId, documentId),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-create <resource-id>").description("Create dataset documents").requiredOption("--data <json>", "JSON array of documents").action(async (resourceId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.createDocuments(
+        resourceId,
+        parseJsonArray(opts.data, "--data")
+      ),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-upsert <resource-id>").description("Upsert dataset documents; every document must have an id").requiredOption("--data <json>", "JSON array of documents").action(async (resourceId, opts, cmd) => {
+    const documents = parseJsonArray(opts.data, "--data");
+    if (documents.some((document) => typeof document.id !== "string")) {
+      throw new InputError("every document in --data must have a string id");
+    }
+    printJson(
+      await clientFrom(cmd).resource.upsertDocuments(resourceId, documents),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-delete <resource-id> <document-ids...>").description("Delete dataset documents by id").action(async (resourceId, documentIds, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.deleteDocuments(resourceId, documentIds),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("document-delete-filter <resource-id>").description("Delete dataset documents by a non-empty filter").requiredOption("--filter <json>", "filter_condition JSON object").action(async (resourceId, opts, cmd) => {
+    const filter = parseJsonObject(opts.filter, "--filter");
+    if (!Object.keys(filter).length) throw new InputError("--filter must not be empty");
+    printJson(
+      await clientFrom(cmd).resource.deleteDocumentsByFilter(resourceId, filter),
+      outputOptions(cmd)
+    );
+  });
   const dataset = vega.command("dataset").description("Dataset index build tasks");
   dataset.command("build <resource-id>").description("Build a resource's index (creates a BuildTask)").requiredOption("--mode <mode>", "build mode: batch | streaming").option("--embedding-fields <list>", "comma-separated fields to vectorize").option(
     "--build-key-fields <list>",
     "comma-separated key fields (batch: time; streaming: row id)"
-  ).option("--embedding-model <id>", "default embedding model name/id").option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
+  ).option(
+    "--embedding-model <name-or-id>",
+    "default small-model name (a numeric ID is resolved to its name)"
+  ).option("--fulltext-fields <list>", "comma-separated fields for fulltext index").option("--fulltext-analyzer <name>", "fulltext analyzer").option("--execute-type <type>", "batch execution type: incremental | full").option("--wait", "poll until the build reaches a terminal state").option("--timeout <s>", "wait timeout in seconds", (v) => Number.parseInt(v, 10), 300).action(async (resourceId, _opts, cmd) => {
     const o = cmd.optsWithGlobals();
     const embeddingFields = csv(o.embeddingFields);
     const buildKeyFields = csv(o.buildKeyFields);
@@ -3007,28 +3405,22 @@ function vegaCommand() {
     const task = await clientFrom(cmd).vega.buildStatus(taskId);
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "created_at | updated_at").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
-    if (opts.orderBy === "default") {
-      throw new InputError(
-        '--order-by default is no longer supported; use "created_at" or "updated_at"'
-      );
-    }
+  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int11, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int11, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", `comma-separated statuses: ${BuildTaskStatus.options.join(" | ")}`).option("--mode <mode>", "filter by mode: batch | streaming").option("--sort <field>", `sort field: ${BuildTaskSort.options.join(" | ")}`).option("--direction <dir>", `sort direction: ${SortDirection.options.join(" | ")}`).action(async (opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.buildTasks({
         limit: opts.limit,
         offset: opts.offset,
         resourceId: opts.resourceId,
         catalogId: opts.catalogId,
-        status: opts.status,
-        active: opts.active,
+        status: buildTaskStatuses(opts.status),
         mode: opts.mode,
-        orderBy: opts.orderBy,
-        order: opts.order
+        sort: buildTaskSort(opts.sort),
+        direction: sortDirection(opts.direction)
       }),
       outputOptions(cmd)
     );
   });
-  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (ignored for incremental tasks)").action(async (taskId, opts, cmd) => {
+  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (rejected for incremental tasks)").action(async (taskId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.startBuildTask(taskId, { reset: opts.reset }),
       outputOptions(cmd)
@@ -3037,11 +3429,10 @@ function vegaCommand() {
   dataset.command("build-stop <task-id>").description("Stop a BuildTask").action(async (taskId, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.stopBuildTask(taskId), outputOptions(cmd));
   });
-  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").option("--delete-active-index", "delete active indexes too").action(async (ids, opts, cmd) => {
+  dataset.command("build-delete <ids...>").description("Delete one or more BuildTasks").option("--ignore-missing", "ignore missing task ids").action(async (ids, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.deleteBuildTasks(ids, {
-        ignoreMissing: opts.ignoreMissing,
-        deleteActiveIndex: opts.deleteActiveIndex
+        ignoreMissing: opts.ignoreMissing
       }),
       outputOptions(cmd)
     );
@@ -3050,8 +3441,11 @@ function vegaCommand() {
 }
 
 // src/cli.ts
-var program = new Command17();
-program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
+var program = new Command16();
+program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option(
+  "--new-conversation",
+  "ignore the remembered conversation for this command (see `openbkn context conversation`)"
+).option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
 program.addCommand(authCommand());
 program.addCommand(callCommand());
 program.addCommand(configCommand());
@@ -3059,7 +3453,6 @@ program.addCommand(appkeyCommand());
 program.addCommand(vegaCommand());
 program.addCommand(bknCommand());
 program.addCommand(resourceCommand());
-program.addCommand(dataflowCommand());
 program.addCommand(contextCommand());
 program.addCommand(agentCommand());
 program.addCommand(modelCommand());