@openbkn/bkn-sdk 0.1.0

package/dist/cli.js

@@ -0,0 +1,2317 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_LIST_LIMIT,
+  DEFAULT_QUERY_LIMIT,
+  InputError,
+  activePlatform,
+  attachToken,
+  changePassword,
+  createClient,
+  currentToken,
+  deletePlatform,
+  exportCreds,
+  formatError,
+  listPlatforms,
+  logout,
+  parsePkMap,
+  rawCall,
+  readPlatformConfig,
+  renderOrgTree,
+  renderReportMarkdown,
+  resolveContext,
+  setActivePlatform,
+  status,
+  switchUser,
+  toExitCode,
+  use,
+  usersOf,
+  whoami,
+  writePlatformConfig
+} from "./chunk-4NXAIG4G.js";
+
+// src/cli.ts
+import { Command as Command16 } from "commander";
+
+// package.json
+var package_default = {
+  name: "@openbkn/bkn-sdk",
+  version: "0.1.0",
+  description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
+  type: "module",
+  license: "Apache-2.0",
+  engines: {
+    node: ">=22"
+  },
+  bin: {
+    openbkn: "./dist/cli.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    }
+  },
+  files: ["dist", "README.md", "README.zh.md", "LICENSE"],
+  publishConfig: {
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/openbkn-ai/bkn-sdk.git"
+  },
+  keywords: ["bkn", "openbkn", "knowledge-network", "cli", "sdk", "typescript"],
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    typecheck: "tsc --noEmit",
+    lint: "biome check . && tsc --noEmit",
+    format: "biome format --write .",
+    test: "vitest run",
+    "test:cover": "vitest run --coverage",
+    ci: "npm run lint && npm test",
+    prepublishOnly: "npm run ci && npm run build"
+  },
+  dependencies: {
+    "@clack/prompts": "^0.9.1",
+    chalk: "^5.4.1",
+    "cli-table3": "^0.6.5",
+    commander: "^13.1.0",
+    "csv-parse": "^6.2.1",
+    "js-yaml": "^4.2.0",
+    jszip: "^3.10.1",
+    zod: "^3.24.1"
+  },
+  devDependencies: {
+    "@biomejs/biome": "^1.9.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.0",
+    tsup: "^8.4.0",
+    typescript: "^5.8.0",
+    vitest: "^3.0.0"
+  }
+};
+
+// src/commands/admin.ts
+import { Command as Command2 } from "commander";
+
+// src/help/grouped-help.ts
+var GROUP = /* @__PURE__ */ Symbol("openbkn.group");
+var DEFAULT_GROUP = "COMMANDS";
+function group(cmd, name) {
+  cmd[GROUP] = name;
+  return cmd;
+}
+function groupOf(cmd) {
+  return cmd[GROUP] ?? DEFAULT_GROUP;
+}
+function formatHelp(cmd, helper) {
+  const out = [];
+  const desc = helper.commandDescription(cmd);
+  if (desc) out.push(desc, "");
+  out.push("USAGE", `  ${helper.commandUsage(cmd)}`, "");
+  const subs = helper.visibleCommands(cmd);
+  if (subs.length > 0) {
+    const width = Math.max(...subs.map((c) => helper.subcommandTerm(c).length));
+    const sections = /* @__PURE__ */ new Map();
+    for (const c of subs) {
+      const g = groupOf(c);
+      const bucket = sections.get(g);
+      if (bucket) bucket.push(c);
+      else sections.set(g, [c]);
+    }
+    for (const [name, cmds] of sections) {
+      out.push(name);
+      for (const c of cmds) {
+        out.push(`  ${helper.subcommandTerm(c).padEnd(width)}  ${helper.subcommandDescription(c)}`);
+      }
+      out.push("");
+    }
+  }
+  const opts = helper.visibleOptions(cmd);
+  if (opts.length > 0) {
+    const width = Math.max(...opts.map((o) => helper.optionTerm(o).length));
+    out.push("FLAGS");
+    for (const o of opts) {
+      out.push(`  ${helper.optionTerm(o).padEnd(width)}  ${helper.optionDescription(o)}`);
+    }
+    out.push("");
+  }
+  return out.join("\n");
+}
+function installGroupedHelp(root) {
+  const apply = (cmd) => {
+    cmd.configureHelp({ formatHelp });
+    for (const child of cmd.commands) apply(child);
+  };
+  apply(root);
+}
+
+// src/utils/output.ts
+import Table from "cli-table3";
+function printJson(value, opts = {}) {
+  if (opts.json || opts.compact) {
+    process.stdout.write(`${JSON.stringify(value, null, opts.compact ? 0 : 2)}
+`);
+    return;
+  }
+  const rows = toRows(value);
+  if (rows) {
+    const columns = columnsOf(rows);
+    if (columns.length > 0) {
+      printTable(rows, columns);
+      return;
+    }
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+var ROW_ENVELOPES = ["entries", "data", "cases", "reports", "results", "list", "recurringRules"];
+function toRows(value) {
+  const isRowArray = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => x !== null && typeof x === "object" && !Array.isArray(x));
+  if (isRowArray(value)) return value;
+  if (value && typeof value === "object") {
+    for (const key of ROW_ENVELOPES) {
+      const inner = value[key];
+      if (isRowArray(inner)) return inner;
+    }
+  }
+  return null;
+}
+function columnsOf(rows) {
+  const seen = [];
+  for (const row of rows) {
+    for (const k of Object.keys(row)) if (!seen.includes(k)) seen.push(k);
+  }
+  return seen;
+}
+function printTable(rows, columns, opts = {}) {
+  if (opts.json || opts.compact) {
+    printJson(rows, opts);
+    return;
+  }
+  const table = new Table({ head: columns });
+  for (const row of rows) {
+    table.push(columns.map((c) => stringifyCell(row[c])));
+  }
+  process.stdout.write(`${table.toString()}
+`);
+}
+var CELL_MAX = 48;
+function stringifyCell(v) {
+  if (v === null || v === void 0) return "";
+  const s = (typeof v === "object" ? JSON.stringify(v) : String(v)).replace(/\s+/g, " ").trim();
+  return s.length > CELL_MAX ? `${s.slice(0, CELL_MAX - 1)}\u2026` : s;
+}
+
+// src/commands/_shared.ts
+import { readFileSync } from "fs";
+function clientFrom(cmd) {
+  const o = cmd.optsWithGlobals();
+  return createClient({
+    baseUrl: o.baseUrl,
+    token: o.token,
+    user: o.user,
+    businessDomain: o.bizDomain,
+    insecure: o.insecure
+  });
+}
+function outputOptions(cmd) {
+  const o = cmd.optsWithGlobals();
+  return { json: Boolean(o.json), compact: Boolean(o.compact) };
+}
+function csv(value) {
+  if (!value) return void 0;
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+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);
+  } catch {
+    throw new InputError("Request body is not valid JSON.");
+  }
+}
+
+// src/commands/auth.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { Command } from "commander";
+
+// src/auth/oauth.ts
+import { spawn } from "child_process";
+import { createHash, constants as cryptoConstants, publicEncrypt, randomBytes } from "crypto";
+import { createServer } from "http";
+var DEFAULT_REDIRECT_PORT = 9010;
+var DEFAULT_SCOPE = "openid offline all";
+var STUDIOWEB_LOGIN_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsyOstgbYuubBi2PUqeVj
+GKlkwVUY6w1Y8d4k116dI2SkZI8fxcjHALv77kItO4jYLVplk9gO4HAtsisnNE2o
+wlYIqdmyEPMwupaeFFFcg751oiTXJiYbtX7ABzU5KQYPjRSEjMq6i5qu/mL67XTk
+hvKwrC83zme66qaKApmKupDODPb0RRkutK/zHfd1zL7sciBQ6psnNadh8pE24w8O
+2XVy1v2bgSNkGHABgncR7seyIg81JQ3c/Axxd6GsTztjLnlvGAlmT1TphE84mi99
+fUaGD2A1u1qdIuNc+XuisFeNcUW6fct0+x97eS2eEGRr/7qxWmO/P20sFVzXc2bF
+1QIDAQAB
+-----END PUBLIC KEY-----`;
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+function generatePkce() {
+  const verifier = randomBytes(48).toString("base64url");
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+function buildAuthorizeUrl(base, clientId, redirectUri, state, codeChallenge, scope = DEFAULT_SCOPE) {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope,
+    state,
+    "x-forwarded-prefix": "",
+    lang: "zh-cn",
+    product: "adp",
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256"
+  });
+  return `${base}/oauth2/auth?${params.toString()}`;
+}
+function mapToken(data) {
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    idToken: data.id_token
+  };
+}
+async function registerClient(base, redirectUri, scope = DEFAULT_SCOPE) {
+  const res = await fetch(`${base}/oauth2/clients`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({
+      client_name: "openbkn-cli",
+      grant_types: ["authorization_code", "implicit", "refresh_token"],
+      response_types: ["token id_token", "code", "token"],
+      scope,
+      redirect_uris: [redirectUri],
+      post_logout_redirect_uris: [redirectUri.replace("/callback", "/successful-logout")],
+      metadata: { device: { name: "openbkn-cli", client_type: "web", description: "openbkn CLI" } }
+    })
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Client registration failed (${res.status}): ${await res.text() || res.statusText}`
+    );
+  }
+  const data = await res.json();
+  return { clientId: data.client_id, clientSecret: data.client_secret };
+}
+async function exchangeCode(base, code, redirectUri, client, codeVerifier) {
+  const params = {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: codeVerifier
+  };
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded",
+    Accept: "application/json"
+  };
+  if (client.clientSecret) {
+    headers.Authorization = `Basic ${Buffer.from(`${client.clientId}:${client.clientSecret}`).toString("base64")}`;
+  } else {
+    params.client_id = client.clientId;
+  }
+  const res = await fetch(`${base}/oauth2/token`, {
+    method: "POST",
+    headers,
+    body: new URLSearchParams(params).toString()
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Token exchange failed (${res.status}): ${await res.text() || res.statusText}`
+    );
+  }
+  return mapToken(await res.json());
+}
+function startCallbackServer(port) {
+  return new Promise((resolve2, reject) => {
+    const server = createServer((req2, res) => {
+      const u = new URL(req2.url ?? "/", `http://127.0.0.1:${port}`);
+      if (u.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const code = u.searchParams.get("code");
+      const error = u.searchParams.get("error");
+      if (error) {
+        res.writeHead(400, { "content-type": "text/html" });
+        res.end(`<h1>Login failed</h1><p>${error}</p>`);
+        server.close(() => reject(new Error(`OAuth error: ${error}`)));
+        return;
+      }
+      if (!code) {
+        res.writeHead(400);
+        res.end("missing code");
+        return;
+      }
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end("<h1>Login successful</h1><p>You can close this window.</p>");
+      resolve2({
+        code,
+        state: u.searchParams.get("state") ?? void 0,
+        close: () => server.close()
+      });
+    });
+    server.on("error", reject);
+    server.listen(port, "127.0.0.1");
+  });
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32"
+    }).unref();
+  } catch {
+  }
+}
+async function browserLogin(baseUrl, opts = {}) {
+  const base = normalizeBaseUrl(baseUrl);
+  const port = opts.port ?? DEFAULT_REDIRECT_PORT;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const scope = opts.scope ?? DEFAULT_SCOPE;
+  const client = opts.clientId ? { clientId: opts.clientId } : await registerClient(base, redirectUri, scope);
+  const { verifier, challenge } = generatePkce();
+  const state = randomBytes(12).toString("hex");
+  const authUrl = buildAuthorizeUrl(base, client.clientId, redirectUri, state, challenge, scope);
+  const waiter = startCallbackServer(port);
+  if (opts.noBrowser) {
+    process.stderr.write(`Open this URL to log in:
+${authUrl}
+`);
+  } else {
+    process.stderr.write(`Opening browser for login\u2026
+If it doesn't open, visit:
+${authUrl}
+`);
+    openBrowser(authUrl);
+  }
+  const { code, state: returned, close } = await waiter;
+  close();
+  if (returned && returned !== state) throw new Error("OAuth state mismatch \u2014 possible CSRF.");
+  return exchangeCode(base, code, redirectUri, client, verifier);
+}
+function mergeCookies(existing, res) {
+  const setCookies = typeof res.headers.getSetCookie === "function" ? res.headers.getSetCookie() : res.headers.get("set-cookie") ? [res.headers.get("set-cookie")] : [];
+  const map = /* @__PURE__ */ new Map();
+  const add = (pair) => {
+    const eq = pair.indexOf("=");
+    if (eq > 0) map.set(pair.slice(0, eq), pair.slice(eq + 1));
+  };
+  for (const p of existing.split(";").map((s) => s.trim()).filter(Boolean))
+    add(p);
+  for (const sc of setCookies) add(sc.split(";")[0]?.trim() ?? "");
+  return [...map.entries()].map(([k, v]) => `${k}=${v}`).join("; ");
+}
+function parseSigninProps(html) {
+  const m = html.match(/<script[^>]*\bid=["']__NEXT_DATA__["'][^>]*>([\s\S]*?)<\/script>/i);
+  if (!m?.[1]) throw new Error("Could not find __NEXT_DATA__ on /oauth2/signin.");
+  const data = JSON.parse(m[1]);
+  const pp = data.props?.pageProps;
+  const csrftoken = pp?.csrftoken ?? pp?._csrf;
+  if (typeof csrftoken !== "string") throw new Error("Sign-in page did not expose csrftoken.");
+  return {
+    csrftoken,
+    challenge: typeof pp?.challenge === "string" ? pp.challenge : void 0,
+    remember: pp?.remember === true || pp?.remember === "true"
+  };
+}
+async function followToCallback(startUrl, jar0, state, redirectUri) {
+  let url = startUrl;
+  let jar = jar0;
+  const cb = new URL(redirectUri);
+  for (let hop = 0; hop < 40; hop++) {
+    const resp = await fetch(url, {
+      headers: { Cookie: jar, Accept: "text/html,*/*;q=0.8" },
+      redirect: "manual"
+    });
+    jar = mergeCookies(jar, resp);
+    if (![302, 303, 307, 308].includes(resp.status)) {
+      throw new Error(`Unexpected OAuth response (HTTP ${resp.status}).`);
+    }
+    const loc = resp.headers.get("location");
+    if (!loc) throw new Error(`OAuth redirect missing Location (HTTP ${resp.status}).`);
+    const next = new URL(loc, url);
+    if (next.origin === cb.origin && next.pathname === cb.pathname) {
+      const err = next.searchParams.get("error");
+      if (err) throw new Error(`Authorization failed: ${err}`);
+      const code = next.searchParams.get("code");
+      if (next.searchParams.get("state") !== state) throw new Error("OAuth state mismatch.");
+      if (!code) throw new Error("Callback missing authorization code.");
+      return code;
+    }
+    url = next.href;
+  }
+  throw new Error("Too many OAuth redirects.");
+}
+async function passwordLogin(baseUrl, username, password, opts = {}) {
+  const base = normalizeBaseUrl(baseUrl);
+  const port = opts.port ?? DEFAULT_REDIRECT_PORT;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const scope = opts.scope ?? DEFAULT_SCOPE;
+  const client = opts.clientId ? { clientId: opts.clientId } : await registerClient(base, redirectUri, scope);
+  const { verifier, challenge } = generatePkce();
+  const state = randomBytes(12).toString("hex");
+  let jar = "";
+  const authResp = await fetch(
+    buildAuthorizeUrl(base, client.clientId, redirectUri, state, challenge, scope),
+    { redirect: "manual" }
+  );
+  jar = mergeCookies(jar, authResp);
+  const authLoc = authResp.headers.get("location");
+  if (!authLoc) throw new Error(`/oauth2/auth did not redirect (HTTP ${authResp.status}).`);
+  const signinUrl = new URL(authLoc, base);
+  if (!signinUrl.pathname.includes("signin")) {
+    throw new Error(`Expected a sign-in redirect, got: ${authLoc}`);
+  }
+  const pageResp = await fetch(signinUrl.href, {
+    headers: { Cookie: jar, Accept: "text/html,*/*;q=0.8" },
+    redirect: "manual"
+  });
+  jar = mergeCookies(jar, pageResp);
+  const props = parseSigninProps(await pageResp.text());
+  const loginChallenge = signinUrl.searchParams.get("login_challenge")?.trim() || props.challenge?.trim();
+  if (!loginChallenge) throw new Error("Could not resolve the login challenge.");
+  const cipher = publicEncrypt(
+    {
+      key: opts.signinPublicKeyPem ?? STUDIOWEB_LOGIN_PUBLIC_KEY_PEM,
+      padding: cryptoConstants.RSA_PKCS1_PADDING
+    },
+    Buffer.from(password, "utf8")
+  ).toString("base64");
+  const postResp = await fetch(`${base}/oauth2/signin`, {
+    method: "POST",
+    headers: {
+      Cookie: jar,
+      "Content-Type": "application/json",
+      Accept: "application/json, text/plain, */*",
+      Origin: new URL(base).origin,
+      Referer: signinUrl.href
+    },
+    body: JSON.stringify({
+      _csrf: props.csrftoken,
+      challenge: loginChallenge,
+      account: username,
+      password: cipher,
+      vcode: { id: "", content: "" },
+      dualfactorauthinfo: { validcode: { vcode: "" }, OTP: { OTP: "" } },
+      remember: props.remember ?? false,
+      device: { name: "", description: "", client_type: "console_web", udids: [] }
+    }),
+    redirect: "manual"
+  });
+  jar = mergeCookies(jar, postResp);
+  let code;
+  if ([302, 303, 307].includes(postResp.status)) {
+    const loc = postResp.headers.get("location");
+    if (!loc) throw new Error("Sign-in response missing Location.");
+    code = await followToCallback(new URL(loc, base).href, jar, state, redirectUri);
+  } else if (postResp.status === 200) {
+    const text = await postResp.text();
+    let json = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+    }
+    const redir = json && typeof json.redirect === "string" ? json.redirect : "";
+    if (!redir) {
+      const msg = json && typeof json.message === "string" ? json.message : text.slice(0, 300);
+      throw new InputError(`Sign-in failed: ${msg}`);
+    }
+    code = await followToCallback(new URL(redir, base).href, jar, state, redirectUri);
+  } else {
+    throw new InputError(
+      `Sign-in failed (HTTP ${postResp.status}): ${(await postResp.text()).slice(0, 300)}`
+    );
+  }
+  return exchangeCode(base, code, redirectUri, client, verifier);
+}
+
+// src/commands/auth.ts
+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>", "local callback port", (v) => Number.parseInt(v, 10)).option(
+    "--signin-public-key-file <path>",
+    "override the RSA public key (PEM) for password signin"
+  ).option("--product <name>", "OAuth product query (default 'adp')").option("--no-browser", "headless: print the authorize 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 token = opts.token ?? g.token;
+    if (token) {
+      const r2 = attachToken(url, token, { insecure: g.insecure });
+      printJson({ loggedIn: true, ...r2 }, outputOptions(cmd2));
+      return;
+    }
+    const signinKey = opts.signinPublicKeyFile ? readFileSync2(opts.signinPublicKeyFile, "utf8") : void 0;
+    const tokens = opts.username ? await passwordLogin(url, opts.username, opts.password ?? "", {
+      clientId: opts.clientId,
+      port: opts.port,
+      signinPublicKeyPem: signinKey
+    }) : await browserLogin(url, {
+      clientId: opts.clientId,
+      port: opts.port,
+      noBrowser: opts.browser === false
+    });
+    const r = attachToken(url, tokens.accessToken, {
+      refreshToken: tokens.refreshToken,
+      idToken: tokens.idToken,
+      insecure: g.insecure
+    });
+    printJson({ loggedIn: true, ...r }, outputOptions(cmd2));
+  });
+  cmd.command("status").description("Show base URL and whether a token is configured").action((_opts, cmd2) => printJson(status(), outputOptions(cmd2)));
+  cmd.command("token").description("Print the current access token (keep secret)").action(() => {
+    process.stdout.write(`${currentToken()}
+`);
+  });
+  cmd.command("whoami [url]").description("Show current user identity (from the token)").option("--no-lookup", "skip the backend identity fallback (eacp/user/get)").action(
+    (_url, _opts, cmd2) => printJson(whoami(), outputOptions(cmd2))
+  );
+  cmd.command("list").alias("ls").description("List platforms with a saved session").action((_opts, cmd2) => printJson(listPlatforms(), outputOptions(cmd2)));
+  cmd.command("use <url>").description("Switch the active platform").action((url, _opts, cmd2) => {
+    use(url);
+    printJson(status(), outputOptions(cmd2));
+  });
+  cmd.command("logout").description("Remove the stored token for the active platform").action((_opts, cmd2) => printJson({ loggedOut: logout() }, outputOptions(cmd2)));
+  cmd.command("delete <url>").description("Delete saved credentials for a platform").action(
+    (url, _opts, cmd2) => printJson({ deleted: deletePlatform(url) }, outputOptions(cmd2))
+  );
+  cmd.command("switch <url> <user-id>").description("Switch the active user for a platform").action((url, userId, _opts, cmd2) => {
+    printJson(switchUser(url, userId), outputOptions(cmd2));
+  });
+  cmd.command("users <url>").description("List saved user profiles for a platform").action((url, _opts, cmd2) => {
+    printJson(usersOf(url), outputOptions(cmd2));
+  });
+  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 (EACP, RSA-encrypted in transit)").requiredOption("-a, --account <name>", "account / login name").requiredOption("--old-password <pwd>", "current password").requiredOption("--new-password <pwd>", "new password").option("--public-key-file <path>", "override the RSA public key (PEM) for password encryption").action(async (_url, opts, cmd2) => {
+    const g = cmd2.optsWithGlobals();
+    const ctx = resolveContext({
+      baseUrl: g.baseUrl,
+      token: g.token,
+      user: g.user,
+      businessDomain: g.bizDomain,
+      insecure: g.insecure
+    });
+    printJson(
+      await changePassword(ctx, opts.account, opts.oldPassword, opts.newPassword),
+      outputOptions(cmd2)
+    );
+  });
+}
+function authCommand() {
+  const cmd = new Command("auth").description("Login, session, and token management");
+  registerAuthLeaves(cmd);
+  return group(cmd, "AUTHENTICATION & CONFIG");
+}
+
+// src/commands/admin.ts
+var int = (v) => Number.parseInt(v, 10);
+function adminCommand() {
+  const admin = new Command2("admin").description(
+    "Operator CLI (kweaver-admin): 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) => {
+    printJson(
+      await clientFrom(cmd).admin.orgList({
+        role: opts.role,
+        name: opts.name,
+        limit: opts.limit,
+        offset: opts.offset
+      }),
+      outputOptions(cmd)
+    );
+  });
+  org.command("get <id>").description("Get one department").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.orgGet(id), outputOptions(cmd));
+  });
+  org.command("members <id>").description("List members of a department").option("--role <r>", "role qualifier", "super_admin").option("--fields <s>", "fields segment", "users").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.orgMembers(id, {
+        role: opts.role,
+        limit: opts.limit,
+        offset: opts.offset
+      }),
+      outputOptions(cmd)
+    );
+  });
+  org.command("create").description("Create a department").requiredOption("--name <s>", "department name").option("--parent <id>", "parent department id", "-1").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").option("--status <n>", "status (1=enabled)", int).option("--oss-id <id>", "object-storage site id").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.orgCreate({
+        name: opts.name,
+        parentId: opts.parent,
+        code: opts.code,
+        remark: opts.remark,
+        email: opts.email,
+        managerID: opts.manager,
+        status: opts.status
+      }),
+      outputOptions(cmd)
+    );
+  });
+  org.command("update <id>").description("Update a department (only provided fields change)").option("--name <s>", "new name").option("--code <s>", "department code").option("--remark <s>", "remark").option("--email <s>", "email").option("--manager <id>", "manager user id").option("--status <n>", "status (1=enabled)", int).option("--oss-id <id>", "object-storage site id").action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.orgUpdate(id, {
+        name: opts.name,
+        code: opts.code,
+        remark: opts.remark,
+        email: opts.email,
+        managerID: opts.manager,
+        status: opts.status
+      }),
+      outputOptions(cmd)
+    );
+  });
+  org.command("delete <id>").description("Delete a department").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.orgDelete(id), outputOptions(cmd));
+  });
+  org.command("tree").description("Print the department hierarchy").option("--role <r>", "role qualifier", "super_admin").action(async (opts, cmd) => {
+    const tree = await clientFrom(cmd).admin.orgTree(opts.role);
+    const out = outputOptions(cmd);
+    if (out.json) printJson(tree, out);
+    else console.log(renderOrgTree(tree));
+  });
+  const user = admin.command("user").description("User management");
+  user.command("list").description("List users").option("--org <id>", "filter by department id").option("--keyword <s>", "filter by name").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.userList({
+        orgId: opts.org,
+        name: opts.keyword,
+        limit: opts.limit,
+        offset: opts.offset
+      }),
+      outputOptions(cmd)
+    );
+  });
+  user.command("assign-role <user> <role>").description("Grant a role to a user").action(async (userId, roleId, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.addRoleMember(roleId, userId, "user"),
+      outputOptions(cmd)
+    );
+  });
+  user.command("revoke-role <user> <role>").description("Revoke a role from a user").action(async (userId, roleId, _opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.removeRoleMember(roleId, userId, "user"),
+      outputOptions(cmd)
+    );
+  });
+  user.command("get <id>").description("Get one user").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.userGet(id), outputOptions(cmd));
+  });
+  user.command("roles <user>").description("List roles granted to a user").action(async (userId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.userRoles(userId), outputOptions(cmd));
+  });
+  user.command("create").description("Create a user (gets the platform default password)").requiredOption("--login <name>", "login name").option("--display-name <s>", "display name (defaults to login name)").option("--email <s>", "email").option("--department <id>", "department id", "-1").option("--code <s>", "user code").option("--position <s>", "position").option("--remark <s>", "remark").option("--tel <s>", "telephone").option("--priority <n>", "priority", int).option("--csf-level <n>", "confidentiality level", int).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.userCreate({
+        loginName: opts.login,
+        displayName: opts.displayName,
+        email: opts.email,
+        departmentIds: opts.department ? [opts.department] : void 0,
+        code: opts.code,
+        position: opts.position,
+        remark: opts.remark,
+        telNumber: opts.tel,
+        priority: opts.priority,
+        csfLevel: opts.csfLevel
+      }),
+      outputOptions(cmd)
+    );
+  });
+  user.command("update <id>").description("Update a user (only provided fields change)").option("--display-name <s>", "display name").option("--email <s>", "email").option("--code <s>", "user code").option("--position <s>", "position").option("--remark <s>", "remark").option("--tel <s>", "telephone").option("--manager <id>", "manager user id").option("--idcard <s>", "id-card number").option("--priority <n>", "priority", int).option("--csf-level <n>", "confidentiality level", int).option("--csf-level2 <n>", "secondary confidentiality level", int).option("--expire-time <n>", "account expiry (epoch, -1 = never)", int).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.userUpdate(id, {
+        displayName: opts.displayName,
+        email: opts.email,
+        code: opts.code,
+        position: opts.position,
+        remark: opts.remark,
+        telNumber: opts.tel,
+        managerID: opts.manager,
+        priority: opts.priority,
+        csfLevel: opts.csfLevel
+      }),
+      outputOptions(cmd)
+    );
+  });
+  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 (RSA-encrypted in transit)").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").option("--new-password <s>", "the new password (alias of --password)").option("--prompt-password", "prompt for the new password interactively").option("-y, --yes", "skip confirmation").action(async (id, opts, cmd) => {
+    const userId = id ?? opts.id ?? opts.user;
+    const pwd = opts.password ?? opts.newPassword;
+    if (!userId) throw new Error("Provide a user id (positional or --id).");
+    if (!pwd) throw new Error("Provide --password / --new-password.");
+    printJson(await clientFrom(cmd).admin.userResetPassword(userId, pwd), outputOptions(cmd));
+  });
+  const role = admin.command("role").description("Role management");
+  role.command("list").description("List roles").option("--keyword <s>", "filter by keyword").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).option("--source <s>", "role source filter (business | user)").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.roleList({ keyword: opts.keyword, limit: opts.limit }),
+      outputOptions(cmd)
+    );
+  });
+  role.command("get <role>").description("Get a role by id").option("--view <mode>", "detail view mode").action(async (roleId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).admin.roleGet(roleId), outputOptions(cmd));
+  });
+  role.command("members <role>").description("List members of a role").option("--keyword <s>", "filter by keyword").option("--type <t>", "filter by member type (user|department|group|app)").option("--member <spec...>", "filter to specific member(s) '<type>:<id-or-name>'").option("--limit <n>", "page size", int, 100).option("--offset <n>", "page offset", int, 0).action(async (roleId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.roleMembers(roleId, {
+        keyword: opts.keyword,
+        limit: opts.limit
+      }),
+      outputOptions(cmd)
+    );
+  });
+  role.command("add-member <role> <id>").description("Add a member to a role").option("--type <t>", "member type", "user").option("--member <spec...>", "member(s) as '<type>:<id-or-name>' (alt to <id>)").action(async (roleId, id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.addRoleMember(roleId, id, opts.type),
+      outputOptions(cmd)
+    );
+  });
+  role.command("remove-member <role> <id>").description("Remove a member from a role").option("--type <t>", "member type", "user").option("--member <spec...>", "member(s) as '<type>:<id-or-name>' (alt to <id>)").action(async (roleId, id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).admin.removeRoleMember(roleId, id, opts.type),
+      outputOptions(cmd)
+    );
+  });
+  const modelBody = (opts) => {
+    if (opts.body || opts.bodyFile) return readBody(opts);
+    const mc = {};
+    if (opts.apiModel) mc.api_model = opts.apiModel;
+    if (opts.apiUrl) mc.api_url = opts.apiUrl;
+    if (opts.apiBase) mc.api_url = opts.apiBase;
+    if (opts.apiKey) mc.api_key = opts.apiKey;
+    const body = {};
+    if (opts.name) body.model_name = opts.name;
+    if (opts.series) body.model_series = opts.series;
+    if (opts.type) body.model_type = opts.type;
+    if (opts.icon) body.icon = opts.icon;
+    if (opts.embeddingDim !== void 0) body.model_dimensions = opts.embeddingDim;
+    if (opts.maxTokens !== void 0) body.max_model_len = opts.maxTokens;
+    if (opts.batchSize !== void 0) body.batch_size = opts.batchSize;
+    if (Object.keys(mc).length > 0) body.model_config = mc;
+    return body;
+  };
+  for (const kind of ["llm", "small-model"]) {
+    const isLlm = kind === "llm";
+    const m = admin.command(kind).description(`${kind} management`);
+    const ns = isLlm ? "llm" : "small";
+    const list = m.command("list").description(`List ${kind} models`).option("--name <s>", "filter by name").option("--page <n>", "page", int, 1).option("--size <n>", "page size", int, DEFAULT_LIST_LIMIT);
+    (isLlm ? list.option("--series <s>", "model series") : list.option("--type <t>", "model type")).action(async (opts, cmd) => {
+      printJson(
+        await clientFrom(cmd).models[ns].list({
+          name: opts.name,
+          page: opts.page,
+          limit: opts.size,
+          modelType: opts.type
+        }),
+        outputOptions(cmd)
+      );
+    });
+    m.command("get <modelid>").description(`Get a ${kind} model`).action(async (id, _opts, cmd) => {
+      printJson(await clientFrom(cmd).models[ns].get(id), outputOptions(cmd));
+    });
+    const add = m.command("add").description(`Register a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option("--api-model <s>", "upstream API model id").option("--api-key <s>", "upstream API key").option("--body <json>", "model config JSON (overrides flags)").option("--body-file <path>", "read config JSON from a file");
+    if (isLlm) {
+      add.option("--series <s>", "model series").option("--api-base <url>", "upstream API base URL").option("--icon <url>", "icon URL");
+    } else {
+      add.option("--type <t>", "small-model type (embedding|reranker)").option("--api-url <url>", "upstream API URL").option("--embedding-dim <n>", "embedding dimensions", int).option("--max-tokens <n>", "max tokens", int).option("--batch-size <n>", "batch size", int);
+    }
+    add.action(async (opts, cmd) => {
+      printJson(await clientFrom(cmd).models[ns].add(modelBody(opts)), outputOptions(cmd));
+    });
+    const edit = m.command("edit <modelid>").description(`Edit a ${kind} model (granular flags or --body/--body-file)`).option("--name <s>", "model name").option("--body <json>", "model config JSON (overrides flags)").option("--body-file <path>", "read config JSON from a file");
+    if (isLlm) {
+      edit.option("--icon <url>", "icon URL");
+    } else {
+      edit.option("--api-model <s>", "upstream API model id").option("--api-url <url>", "upstream API URL");
+    }
+    edit.action(async (id, opts, cmd) => {
+      printJson(
+        await clientFrom(cmd).models[ns].edit({ model_id: id, ...modelBody(opts) }),
+        outputOptions(cmd)
+      );
+    });
+    m.command("delete <modelid...>").description(`Delete ${kind} model(s)`).action(async (ids, _opts, cmd) => {
+      printJson(await clientFrom(cmd).models[ns].delete(ids), outputOptions(cmd));
+    });
+    m.command("test <modelid>").description(`Test a ${kind} model`).option("--body <json>", "test request JSON").option("--body-file <path>", "read test request JSON from a file").action(async (id, opts, cmd) => {
+      const body = opts.body || opts.bodyFile ? readBody(opts) : {};
+      printJson(
+        await clientFrom(cmd).models[ns].test({ model_id: id, ...body }),
+        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({
+        user: opts.user,
+        start: opts.start,
+        end: opts.end,
+        page: opts.page,
+        size: opts.size
+      }),
+      outputOptions(cmd)
+    );
+  });
+  const adminConfig = admin.command("config").description("Admin CLI config (active platform)");
+  adminConfig.command("show").description("Show the active platform").action((_opts, cmd) => {
+    printJson({ baseUrl: activePlatform() }, outputOptions(cmd));
+  });
+  adminConfig.command("set <key> <value>").description("Set a config value (baseUrl)").action((key, value, _opts, cmd) => {
+    if (key !== "baseUrl") {
+      throw new Error(`Unknown config key: ${key} (only baseUrl supported)`);
+    }
+    setActivePlatform(value.replace(/\/+$/, ""));
+    printJson({ ok: true, baseUrl: value }, outputOptions(cmd));
+  });
+  admin.command("call <url>").description("Operator API passthrough (curl-style; auto-injected auth)").option("-X, --request <method>", "HTTP method").option(
+    "-H, --header <header>",
+    'extra header "Name: value" (repeatable)',
+    (v, a) => {
+      a.push(v);
+      return a;
+    },
+    []
+  ).option("-d, --data <body>", "request body (JSON content-type if unset)").action(async (url, opts, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const res = await rawCall(
+      resolveContext({
+        baseUrl: g.baseUrl,
+        token: g.token,
+        user: g.user,
+        businessDomain: g.bizDomain,
+        insecure: g.insecure
+      }),
+      url,
+      { method: opts.request, header: opts.header, data: opts.data, businessDomain: g.bizDomain }
+    );
+    const out = outputOptions(cmd);
+    try {
+      printJson(JSON.parse(res.body), out);
+    } catch {
+      process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
+`);
+    }
+    if (res.status >= 400) process.exitCode = 1;
+  });
+  return group(admin, "OPERATOR");
+}
+
+// src/commands/agent.ts
+import { Command as Command3 } from "commander";
+var int2 = (v) => Number.parseInt(v, 10);
+function agentCommand() {
+  const cmd = new Command3("agent").description("Agent CRUD, chat, sessions, publish");
+  cmd.command("list").description("List published agents").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).option("--category-id <id>", "filter by category").action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).agents.list({
+      name: opts.name,
+      limit: opts.limit,
+      offset: opts.offset,
+      categoryId: opts.categoryId
+    });
+    printJson(data, outputOptions(cmd2));
+  });
+  cmd.command("personal-list").description("List personal-space agents").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).agents.personalList({
+      name: opts.name,
+      limit: opts.limit,
+      offset: opts.offset
+    });
+    printJson(data, outputOptions(cmd2));
+  });
+  cmd.command("category-list").description("List agent categories").action(async (_opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.categoryList(), outputOptions(cmd2));
+  });
+  cmd.command("template-list").description("List published agent templates").option("--name <s>", "filter by name").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int2, 0).action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).agents.templateList({
+      name: opts.name,
+      limit: opts.limit,
+      offset: opts.offset
+    });
+    printJson(data, outputOptions(cmd2));
+  });
+  cmd.command("template-get <id>").description("Get a published agent template").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.templateGet(id), outputOptions(cmd2));
+  });
+  cmd.command("get <id>").description("Get agent details").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.get(id), outputOptions(cmd2));
+  });
+  cmd.command("get-by-key <key>").description("Get an agent by key").action(async (key, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.getByKey(key), outputOptions(cmd2));
+  });
+  cmd.command("create").description("Create an agent (--body-file <json> or --body '<json>')").option("--body <json>", "agent definition JSON").option("--body-file <path>", "read agent definition JSON from a file").action(async (opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.create(readBody(opts)), outputOptions(cmd2));
+  });
+  cmd.command("update <id>").description("Update an agent (--body-file <json> or --body '<json>')").option("--body <json>", "agent definition JSON").option("--body-file <path>", "read agent definition JSON from a file").action(async (id, opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.update(id, readBody(opts)), outputOptions(cmd2));
+  });
+  cmd.command("delete <id>").description("Delete an agent").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.delete(id), outputOptions(cmd2));
+  });
+  cmd.command("publish <id>").description("Publish an agent").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.publish(id), outputOptions(cmd2));
+  });
+  cmd.command("unpublish <id>").description("Unpublish an agent").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.unpublish(id), outputOptions(cmd2));
+  });
+  cmd.command("sessions <agent>").description("List conversations for an agent (by agent key)").option("--limit <n>", "page size", int2, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int2, 1).action(async (agentKey, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).agents.sessions(agentKey, { size: opts.limit, page: opts.page }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("history <agent> <conversation-id>").description("Show message history for a conversation").action(async (agentKey, conversationId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.history(agentKey, conversationId), outputOptions(cmd2));
+  });
+  cmd.command("chat <agent-id>").description("Chat with an agent (SSE streaming with --stream)").requiredOption("-m, --message <text>", "user message").option("--version <v>", "agent version", "v0").option("--conversation-id <id>", "continue an existing conversation").option("--stream", "stream the reply to stdout as it arrives").action(async (agentId, opts, cmd2) => {
+    const client = clientFrom(cmd2);
+    if (opts.stream) {
+      const res = await client.agents.chat(agentId, opts.message, {
+        version: opts.version,
+        conversationId: opts.conversationId,
+        stream: true,
+        onDelta: (t) => process.stdout.write(t)
+      });
+      process.stdout.write("\n");
+      if (res.conversationId) console.error(`conversation_id: ${res.conversationId}`);
+      return;
+    }
+    printJson(
+      await client.agents.chat(agentId, opts.message, {
+        version: opts.version,
+        conversationId: opts.conversationId
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("trace <conversation-id>").description("Get trace spans for a conversation (agent-scoped alias of `trace get`)").action(async (conversationId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.spans(conversationId), outputOptions(cmd2));
+  });
+  const skill = cmd.command("skill").description("Manage skills attached to an agent");
+  skill.command("list <agent-id>").description("List skill ids attached to an agent").action(async (agentId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.skillList(agentId), outputOptions(cmd2));
+  });
+  skill.command("add <agent-id> <skill-ids>").description("Attach skill(s) to an agent (comma-joined ids)").action(async (agentId, ids, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).agents.skillAdd(agentId, csv(ids) ?? []), outputOptions(cmd2));
+  });
+  skill.command("remove <agent-id> <skill-ids>").description("Detach skill(s) from an agent (comma-joined ids)").action(async (agentId, ids, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).agents.skillRemove(agentId, csv(ids) ?? []),
+      outputOptions(cmd2)
+    );
+  });
+  return group(cmd, "DECISION AGENT");
+}
+
+// src/commands/bkn.ts
+import { Command as Command4 } from "commander";
+
+// src/utils/bkn-validate.ts
+import { existsSync, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
+import { join, resolve } from "path";
+var BKN_OBJECT_NAME_MAX_LENGTH = 40;
+function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  const block = text.slice(3, end);
+  const fm = {};
+  for (const line of block.split("\n")) {
+    const m = line.match(/^\s*(type|id|name)\s*:\s*(.+?)\s*$/);
+    if (m?.[1]) fm[m[1]] = m[2]?.replace(/^["']|["']$/g, "");
+  }
+  return fm;
+}
+function bknFiles(dir) {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".bkn")).map((f) => join(dir, f));
+}
+function endpointRefs(text) {
+  const refs = [];
+  const idx = text.indexOf("### Endpoint");
+  if (idx === -1) return refs;
+  const after = text.slice(idx + "### Endpoint".length);
+  const next = after.indexOf("\n###");
+  const section = next === -1 ? after : after.slice(0, next);
+  for (const line of section.split("\n")) {
+    const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
+    if (cells.length < 2) continue;
+    const [source, target] = cells;
+    if (!source || !target) continue;
+    if (/^source$/i.test(source) || /^-+$/.test(source)) continue;
+    refs.push({ source, target });
+  }
+  return refs;
+}
+function validateBknDirectory(dirPath) {
+  const dir = resolve(dirPath);
+  const errors = [];
+  const warnings = [];
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    return {
+      valid: false,
+      dir,
+      counts: { objectTypes: 0, relationTypes: 0, conceptGroups: 0 },
+      errors: [`Not a directory: ${dir}`],
+      warnings: []
+    };
+  }
+  const networkPath = join(dir, "network.bkn");
+  if (!existsSync(networkPath)) {
+    errors.push("Missing network.bkn at the BKN root.");
+  } else {
+    const fm = parseFrontmatter(readFileSync3(networkPath, "utf8"));
+    if (!fm) errors.push("network.bkn has no frontmatter block.");
+    else {
+      if (fm.type !== "knowledge_network")
+        errors.push(`network.bkn type must be 'knowledge_network', got '${fm.type ?? ""}'.`);
+      if (!fm.id) errors.push("network.bkn is missing 'id'.");
+      if (!fm.name) errors.push("network.bkn is missing 'name'.");
+    }
+  }
+  const otIds = /* @__PURE__ */ new Set();
+  const otFiles = bknFiles(join(dir, "object_types"));
+  for (const file of otFiles) {
+    const fm = parseFrontmatter(readFileSync3(file, "utf8"));
+    const rel = file.slice(dir.length + 1);
+    if (!fm || fm.type !== "object_type") {
+      errors.push(`${rel}: not a valid object_type (missing/wrong frontmatter type).`);
+      continue;
+    }
+    if (!fm.id) errors.push(`${rel}: object_type missing 'id'.`);
+    if (!fm.name) errors.push(`${rel}: object_type missing 'name'.`);
+    if (fm.name && [...fm.name].length > BKN_OBJECT_NAME_MAX_LENGTH) {
+      errors.push(
+        `${rel}: object_type name exceeds ${BKN_OBJECT_NAME_MAX_LENGTH} codepoints ('${fm.name}').`
+      );
+    }
+    if (fm.id) {
+      if (otIds.has(fm.id)) errors.push(`Duplicate object_type id '${fm.id}'.`);
+      otIds.add(fm.id);
+    }
+  }
+  const rtFiles = bknFiles(join(dir, "relation_types"));
+  for (const file of rtFiles) {
+    const text = readFileSync3(file, "utf8");
+    const fm = parseFrontmatter(text);
+    const rel = file.slice(dir.length + 1);
+    if (!fm || fm.type !== "relation_type") {
+      errors.push(`${rel}: not a valid relation_type (missing/wrong frontmatter type).`);
+      continue;
+    }
+    if (!fm.id) errors.push(`${rel}: relation_type missing 'id'.`);
+    for (const { source, target } of endpointRefs(text)) {
+      if (otIds.size > 0 && !otIds.has(source))
+        warnings.push(`${rel}: endpoint source '${source}' is not a known object_type.`);
+      if (otIds.size > 0 && !otIds.has(target))
+        warnings.push(`${rel}: endpoint target '${target}' is not a known object_type.`);
+    }
+  }
+  const cgFiles = bknFiles(join(dir, "concept_groups"));
+  return {
+    valid: errors.length === 0,
+    dir,
+    counts: {
+      objectTypes: otFiles.length,
+      relationTypes: rtFiles.length,
+      conceptGroups: cgFiles.length
+    },
+    errors,
+    warnings
+  };
+}
+
+// src/commands/bkn.ts
+var int3 = (v) => Number.parseInt(v, 10);
+function bknCommand() {
+  const bkn = new Command4("bkn").description("Knowledge networks \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 o = cmd.optsWithGlobals();
+    const data = await clientFrom(cmd).kn.list({
+      limit: o.limit,
+      offset: o.offset,
+      namePattern: o.namePattern,
+      tag: o.tag,
+      sort: o.sort,
+      direction: o.direction
+    });
+    printJson(data, outputOptions(cmd));
+  });
+  bkn.command("get <kn-id>").description("Get a knowledge network (use --stats or --export)").option("--stats", "include statistics").option("--export", "return the full export payload").action(async (knId, opts, cmd) => {
+    const data = await clientFrom(cmd).kn.get(knId, {
+      stats: opts.stats,
+      exportMode: opts.export
+    });
+    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) => {
+    const data = await clientFrom(cmd).kn.search(knId, query, {
+      maxConcepts: opts.maxConcepts,
+      mode: opts.mode
+    });
+    printJson(data, outputOptions(cmd));
+  });
+  const schemaGroups = [
+    ["object-type", "objectTypes", "objectType"],
+    ["relation-type", "relationTypes", "relationType"],
+    ["action-type", "actionTypes", null]
+  ];
+  for (const [name, listMethod, crud] of schemaGroups) {
+    const g = bkn.command(name).description(`${name} list/get/...`);
+    g.command("list <kn-id>").description(`List ${name}s`).option("--branch <b>", "branch", "main").action(async (knId, opts, cmd) => {
+      printJson(
+        await clientFrom(cmd).kn[listMethod](knId, { branch: opts.branch }),
+        outputOptions(cmd)
+      );
+    });
+    if (crud) {
+      g.command("get <kn-id> <id>").description(`Get ${name}`).action(async (knId, id, _o, cmd) => {
+        printJson(await clientFrom(cmd).kn[`${crud}Get`](knId, id), outputOptions(cmd));
+      });
+      g.command("create <kn-id>").description(`Create ${name} (--body / --body-file)`).option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+        printJson(
+          await clientFrom(cmd).kn[`${crud}Create`](knId, readBody(opts)),
+          outputOptions(cmd)
+        );
+      });
+      g.command("update <kn-id> <id>").description(`Update ${name} (--body / --body-file)`).option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
+        printJson(
+          await clientFrom(cmd).kn[`${crud}Update`](knId, id, readBody(opts)),
+          outputOptions(cmd)
+        );
+      });
+      g.command("delete <kn-id> <id>").description(`Delete ${name}`).option("-y, --yes", "skip confirmation").action(async (knId, id, _o, cmd) => {
+        printJson(await clientFrom(cmd).kn[`${crud}Delete`](knId, id), outputOptions(cmd));
+      });
+    }
+  }
+  const actionType = bkn.commands.find((c) => c.name() === "action-type");
+  actionType?.command("query <kn-id> <at-id>").description("Query an action type (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, atId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionTypeQuery(knId, atId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  actionType?.command("execute <kn-id> <at-id>").description("Execute an action type (--body / --body-file envelope JSON)").option("--body <json>", "execution envelope JSON").option("--body-file <path>", "read envelope JSON from a file").action(async (knId, atId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionTypeExecute(knId, atId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  actionType?.command("inputs <kn-id> <at-id>").description("Get an action type's input schema").action(async (knId, atId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionTypeInputs(knId, atId), outputOptions(cmd));
+  });
+  actionType?.command("get <kn-id> <at-id>").description("Get an action type").action(async (knId, atId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionTypeGet(knId, atId), outputOptions(cmd));
+  });
+  bkn.command("stats <kn-id>").description("Get knowledge-network statistics (alias for get --stats)").action(async (knId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.get(knId, { stats: true }), outputOptions(cmd));
+  });
+  bkn.command("export <kn-id>").description("Export a knowledge network (alias for get --export)").action(async (knId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.get(knId, { exportMode: true }), outputOptions(cmd));
+  });
+  const objectType = bkn.commands.find((c) => c.name() === "object-type");
+  objectType?.command("query <kn-id> <ot-id>").description("Query instances of an object type (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, otId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.objectTypeQuery(knId, otId, readBody(opts)),
+      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));
+  });
+  bkn.command("update <kn-id>").description("Update a knowledge network (--body / --body-file)").option("--body <json>", "update body JSON").option("--body-file <path>", "read update body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.update(knId, readBody(opts)), outputOptions(cmd));
+  });
+  bkn.command("delete <kn-id>").description("Delete a knowledge network").option("-y, --yes", "skip confirmation").action(async (knId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.delete(knId), outputOptions(cmd));
+  });
+  bkn.command("subgraph <kn-id>").description("Query a subgraph (--body / --body-file JSON)").option("--body <json>", "subgraph query JSON").option("--body-file <path>", "read subgraph query JSON from a file").action(async (knId, opts, cmd) => {
+    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) => {
+    printJson(
+      await clientFrom(cmd).kn.actionLogs(knId, {
+        status: opts.status,
+        actionTypeId: opts.actionTypeId,
+        limit: opts.limit
+      }),
+      outputOptions(cmd)
+    );
+  });
+  actionLog.command("get <kn-id> <log-id>").description("Get an action log").action(async (knId, logId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionLog(knId, logId), outputOptions(cmd));
+  });
+  actionLog.command("cancel <kn-id> <log-id>").description("Cancel a running action").action(async (knId, logId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.cancelActionLog(knId, logId), outputOptions(cmd));
+  });
+  bkn.command("action-execution <kn-id> <execution-id>").description("Get action execution status").action(async (knId, execId, _opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionExecution(knId, execId), outputOptions(cmd));
+  });
+  const metric = bkn.command("metric").description("Metrics \u2014 query / dry-run");
+  metric.command("query <kn-id> <metric-id>").description("Query a metric's data (--body / --body-file JSON)").option("--body <json>", "query JSON").option("--body-file <path>", "read query JSON from a file").action(async (knId, metricId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricQuery(knId, metricId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  metric.command("dry-run <kn-id>").description("Dry-run a metric definition (--body / --body-file JSON)").option("--body <json>", "metric definition JSON").option("--body-file <path>", "read metric definition JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricDryRun(knId, readBody(opts)), outputOptions(cmd));
+  });
+  metric.command("list <kn-id>").description("List metrics").action(async (knId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricList(knId), outputOptions(cmd));
+  });
+  metric.command("get <kn-id> <metric-id>").description("Get a metric").action(async (knId, id, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricGet(knId, id), outputOptions(cmd));
+  });
+  metric.command("create <kn-id>").description("Create a metric (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricCreate(knId, readBody(opts)), outputOptions(cmd));
+  });
+  metric.command("update <kn-id> <metric-id>").description("Update a metric (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.metricUpdate(knId, id, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  metric.command("delete <kn-id> <metric-id>").description("Delete a metric").action(async (knId, id, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricDelete(knId, id), outputOptions(cmd));
+  });
+  metric.command("search <kn-id>").description("Search metrics (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricSearch(knId, readBody(opts)), outputOptions(cmd));
+  });
+  metric.command("validate <kn-id>").description("Validate a metric definition (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.metricValidate(knId, readBody(opts)), outputOptions(cmd));
+  });
+  const cg = bkn.command("concept-group").description("Concept groups \u2014 list/get");
+  cg.command("list <kn-id>").description("List concept groups").action(async (knId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.conceptGroups(knId), outputOptions(cmd));
+  });
+  cg.command("get <kn-id> <cg-id>").description("Get a concept group").action(async (knId, cgId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.conceptGroup(knId, cgId), outputOptions(cmd));
+  });
+  cg.command("create <kn-id>").description("Create a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroupCreate(knId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  cg.command("update <kn-id> <cg-id>").description("Update a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroupUpdate(knId, cgId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  cg.command("delete <kn-id> <cg-id>").description("Delete a concept group").action(async (knId, cgId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.conceptGroupDelete(knId, cgId), outputOptions(cmd));
+  });
+  cg.command("add-members <kn-id> <cg-id>").description("Add object types to a concept group (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, cgId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroupAddMembers(knId, cgId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  cg.command("remove-members <kn-id> <cg-id> <ot-ids>").description("Remove object types (comma-joined ids) from a concept group").action(async (knId, cgId, otIds, _o, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.conceptGroupRemoveMembers(knId, cgId, otIds),
+      outputOptions(cmd)
+    );
+  });
+  const sched = bkn.command("action-schedule").description("Action schedules \u2014 list/get");
+  sched.command("list <kn-id>").description("List action schedules").action(async (knId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionSchedules(knId), outputOptions(cmd));
+  });
+  sched.command("get <kn-id> <schedule-id>").description("Get an action schedule").action(async (knId, sId, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionSchedule(knId, sId), outputOptions(cmd));
+  });
+  sched.command("create <kn-id>").description("Create an action schedule (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionScheduleCreate(knId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  sched.command("update <kn-id> <schedule-id>").description("Update an action schedule (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionScheduleUpdate(knId, sId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  sched.command("set-status <kn-id> <schedule-id>").description("Set an action schedule's status (--body / --body-file)").option("--body <json>", "body JSON").option("--body-file <path>", "read body JSON from a file").action(async (knId, sId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.actionScheduleSetStatus(knId, sId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  sched.command("delete <kn-id> <schedule-ids>").description("Delete action schedule(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
+    printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
+  });
+  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").action(async (dir, opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.push(dir, { branch: opts.branch }), outputOptions(cmd));
+  });
+  bkn.command("pull <kn-id> [directory]").description("Download a knowledge network as a BKN tar and extract it locally").option("--branch <name>", "source branch", "main").action(async (knId, dir, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.pull(knId, dir ?? knId, { branch: opts.branch }),
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("relation-type-paths <kn-id>").description("Query relation-type paths between object types (--body / --body-file JSON)").option("--body <json>", "request JSON").option("--body-file <path>", "read request JSON from a file").action(async (knId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.relationTypePaths(knId, readBody(opts)),
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("resources").description("List BKN-backend resources").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).kn.bknResources(), outputOptions(cmd));
+  });
+  bkn.command("create-from-catalog <catalog-id>").description("Build a knowledge network from a Vega catalog's tables").requiredOption("--name <name>", "knowledge network name").option("--tables <list>", "comma-separated table names (default: all)").option("--pk-map <map>", "explicit primary keys: '<table>:<col>[,<table>:<col>...]'").option("--build", "submit a Vega build task per resource after creation").option("--no-rollback", "keep a partially-created KN on failure").action(async (catalogId, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).kn.createFromCatalog({
+        catalogId,
+        name: opts.name,
+        tables: csv(opts.tables),
+        pkMap: opts.pkMap ? parsePkMap(opts.pkMap) : void 0,
+        build: Boolean(opts.build),
+        noRollback: opts.rollback === false,
+        onProgress: (m) => console.error(m)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  bkn.command("validate <directory>").description("Validate a local BKN directory's structure (offline)").action(async (dir, _opts, cmd) => {
+    const result = validateBknDirectory(dir);
+    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("--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),
+        noRollback: opts.rollback === false,
+        onProgress: (m) => console.error(m)
+      }),
+      outputOptions(cmd)
+    );
+  });
+  return group(bkn, "AI DATA PLATFORM");
+}
+
+// src/commands/call.ts
+import { Command as Command5 } 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(
+    "-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 ctx = resolveContext({
+      baseUrl: g.baseUrl,
+      token: g.token,
+      user: g.user,
+      businessDomain: g.bizDomain,
+      insecure: g.insecure
+    });
+    const res = await rawCall(ctx, url, {
+      method: opts.request,
+      header: opts.header,
+      data: opts.data ?? opts.dataRaw,
+      form: opts.form,
+      businessDomain: g.bizDomain,
+      verbose: opts.verbose
+    });
+    const out = outputOptions(cmd2);
+    try {
+      printJson(JSON.parse(res.body), out);
+    } catch {
+      process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
+`);
+    }
+    if (res.status >= 400) process.exitCode = 1;
+  });
+  return group(cmd, "AUTHENTICATION & CONFIG");
+}
+
+// src/commands/config.ts
+import { Command as Command6 } from "commander";
+function requireActive() {
+  const baseUrl = activePlatform();
+  if (!baseUrl) throw new InputError("No active platform. Run `openbkn auth login <url>` first.");
+  return baseUrl;
+}
+function configCommand() {
+  const config = new Command6("config").description("Per-platform CLI configuration");
+  config.command("show").description("Show the active platform and business domain").action((_opts, cmd) => {
+    const baseUrl = activePlatform();
+    printJson(
+      {
+        baseUrl,
+        businessDomain: baseUrl ? readPlatformConfig(baseUrl).businessDomain : void 0
+      },
+      outputOptions(cmd)
+    );
+  });
+  config.command("set <key> <value>").description("Set a config value (baseUrl | businessDomain)").action((key, value, _opts, cmd) => {
+    if (key === "baseUrl") {
+      setActivePlatform(value.replace(/\/+$/, ""));
+    } else if (key === "businessDomain") {
+      writePlatformConfig(requireActive(), { businessDomain: value });
+    } else {
+      throw new InputError(`Unknown config key: ${key} (expected baseUrl | businessDomain)`);
+    }
+    printJson({ ok: true, key, value }, outputOptions(cmd));
+  });
+  config.command("set-bd <value>").description("Set the default business domain for the active platform").action((value, _opts, cmd) => {
+    const baseUrl = requireActive();
+    writePlatformConfig(baseUrl, { businessDomain: value });
+    printJson({ baseUrl, businessDomain: value }, outputOptions(cmd));
+  });
+  config.command("list-bd").description("List business domains (requires login)").action(() => {
+    throw new InputError("Not yet implemented \u2014 requires backend business-domains API.");
+  });
+  return group(config, "AUTHENTICATION & CONFIG");
+}
+
+// src/commands/context.ts
+import { Command as Command7 } from "commander";
+var int4 = (v) => Number.parseInt(v, 10);
+function contextCommand() {
+  const cmd = new Command7("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) => {
+    const data = await clientFrom(cmd2).context.searchSchema(knId, query, {
+      searchScope: opts.scope ? String(opts.scope).split(",") : void 0,
+      maxConcepts: opts.max
+    });
+    printJson(data, outputOptions(cmd2));
+  });
+  cmd.command("query-object-instance <kn-id>").description("Query object instances (provide --args as JSON)").requiredOption("--args <json>", "tool arguments as JSON").action(async (knId, opts, cmd2) => {
+    let args;
+    try {
+      args = JSON.parse(opts.args);
+    } catch {
+      throw new InputError("--args must be valid JSON");
+    }
+    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) => {
+    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("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("resources <kn-id>").description("List MCP resources").action(async (knId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.resources(knId), outputOptions(cmd2));
+  });
+  cmd.command("resource <kn-id> <uri>").description("Read one MCP resource by uri").action(async (knId, uri, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.resource(knId, uri), outputOptions(cmd2));
+  });
+  cmd.command("templates <kn-id>").description("List MCP resource templates").action(async (knId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.templates(knId), outputOptions(cmd2));
+  });
+  cmd.command("prompts <kn-id>").description("List MCP prompts").action(async (knId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).context.prompts(knId), outputOptions(cmd2));
+  });
+  cmd.command("prompt <kn-id> <name>").description("Get one MCP prompt (--args JSON for prompt arguments)").option("--args <json>", "prompt arguments as JSON").action(async (knId, name, opts, cmd2) => {
+    let args;
+    if (opts.args) {
+      try {
+        args = JSON.parse(opts.args);
+      } catch {
+        throw new InputError("--args must be valid JSON");
+      }
+    }
+    printJson(await clientFrom(cmd2).context.prompt(knId, name, args), outputOptions(cmd2));
+  });
+  const jsonArgs = (raw) => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new InputError("--args must be valid JSON");
+    }
+  };
+  cmd.command("query-instance-subgraph <kn-id>").description("Layer-2: 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) => {
+    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) => {
+    printJson(
+      await clientFrom(cmd2).context.actionInfo(knId, jsonArgs(opts.args)),
+      outputOptions(cmd2)
+    );
+  });
+  return group(cmd, "AI DATA PLATFORM");
+}
+
+// src/commands/dataflow.ts
+import { Command as Command8 } from "commander";
+var int5 = (v) => Number.parseInt(v, 10);
+function dataflowCommand() {
+  const cmd = new Command8("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) => {
+    printJson(
+      await clientFrom(cmd2).dataflows.runs(dagId, { since: opts.since }),
+      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) => {
+    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 as createServer2 } from "http";
+import { Command as Command9 } from "commander";
+var int6 = (v) => Number.parseInt(v, 10);
+var ROUTES = {
+  "GET /api/bkn/meta": (c, q) => c.kn.get(req(q, "knId")),
+  "POST /api/bkn/search": (c, _q, b) => c.kn.search(str(b.knId), str(b.query), {
+    maxConcepts: typeof b.maxConcepts === "number" ? b.maxConcepts : void 0
+  }),
+  "POST /api/bkn/instances": (c, _q, b) => c.kn.objectTypeQuery(str(b.knId), str(b.objectTypeId), b.body ?? {}),
+  "POST /api/bkn/subgraph": (c, _q, b) => c.kn.subgraph(str(b.knId), b.body ?? b),
+  "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),
+  "GET /api/vega/connector-types": (c) => c.vega.connectorTypes(),
+  "POST /api/vega/query": (c, _q, b) => c.resource.query(str(b.resourceId), b.options ?? {})
+};
+function str(v) {
+  return typeof v === "string" ? v : String(v ?? "");
+}
+function req(q, key) {
+  const v = q.get(key);
+  if (!v) throw new Error(`missing query param: ${key}`);
+  return v;
+}
+function readBody2(reqMsg) {
+  return new Promise((resolve2, reject) => {
+    let data = "";
+    reqMsg.on("data", (chunk) => {
+      data += chunk;
+    });
+    reqMsg.on("end", () => {
+      if (!data.trim()) return resolve2({});
+      try {
+        resolve2(JSON.parse(data));
+      } catch {
+        reject(new Error("invalid JSON body"));
+      }
+    });
+    reqMsg.on("error", reject);
+  });
+}
+var INDEX = `<!doctype html><meta charset="utf-8"><title>openbkn explore</title>
+<h1>openbkn explore</h1>
+<p>Read-only JSON endpoints for bkn + vega:</p>
+<ul>${Object.keys(ROUTES).map((r) => `<li><code>${r}</code></li>`).join("")}</ul>`;
+function exploreCommand() {
+  const cmd = new Command9("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) => {
+    const client = clientFrom(command);
+    const server = createServer2((reqMsg, res) => {
+      void handle(client, reqMsg, res);
+    });
+    server.listen(opts.port, opts.host, () => {
+      console.error(`openbkn explore running at http://${opts.host}:${opts.port}/`);
+      console.error("bkn + vega read endpoints only. Press Ctrl+C to stop.");
+    });
+  });
+  return group(cmd, "FOUNDATION");
+}
+async function handle(client, reqMsg, res) {
+  const url = new URL(reqMsg.url ?? "/", "http://localhost");
+  const method = reqMsg.method ?? "GET";
+  if (method === "GET" && url.pathname === "/") {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(INDEX);
+    return;
+  }
+  const handler = ROUTES[`${method} ${url.pathname}`];
+  if (!handler) {
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "not found" }));
+    return;
+  }
+  try {
+    const body = method === "GET" ? {} : await readBody2(reqMsg);
+    const data = await handler(client, url.searchParams, body);
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(data ?? null));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+  }
+}
+
+// src/commands/model.ts
+import { Command as Command10 } from "commander";
+var int7 = (v) => Number.parseInt(v, 10);
+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));
+  });
+  parent.command("edit").description("Update a model definition (JSON via --body / --body-file)").option("--body <json>", "model definition JSON").option("--body-file <path>", "read model definition JSON from a file").action(async (opts, cmd) => {
+    printJson(await clientFrom(cmd).models[kind].edit(readBody(opts)), outputOptions(cmd));
+  });
+  parent.command("delete <model-ids>").description("Delete model(s) (comma-joined ids)").action(async (ids, _o, cmd) => {
+    printJson(await clientFrom(cmd).models[kind].delete(csv(ids) ?? []), outputOptions(cmd));
+  });
+  parent.command("test").description("Test a model's connectivity / inference (JSON via --body / --body-file)").option("--body <json>", "test request JSON").option("--body-file <path>", "read test request JSON from a file").action(async (opts, cmd) => {
+    printJson(await clientFrom(cmd).models[kind].test(readBody(opts)), outputOptions(cmd));
+  });
+}
+function modelCommand() {
+  const model = new Command10("model").description("Model factory \u2014 LLM / small-model CRUD + chat");
+  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) => {
+    printJson(
+      await clientFrom(cmd).models.llm.list({
+        name: opts.name,
+        modelType: opts.type,
+        limit: opts.limit,
+        page: opts.page
+      }),
+      outputOptions(cmd)
+    );
+  });
+  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) => {
+    const messages = [{ role: "user", content: opts.message }];
+    if (opts.stream) {
+      await clientFrom(cmd).models.llm.chatStream(id, messages, (t) => process.stdout.write(t));
+      process.stdout.write("\n");
+      return;
+    }
+    printJson(await clientFrom(cmd).models.llm.chat(id, messages), 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) => {
+    printJson(
+      await clientFrom(cmd).models.small.list({
+        name: opts.name,
+        modelType: opts.type,
+        limit: opts.limit,
+        page: opts.page
+      }),
+      outputOptions(cmd)
+    );
+  });
+  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) => {
+    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) => {
+    printJson(
+      await clientFrom(cmd).models.small.rerank(id, opts.query, csv(opts.documents) ?? []),
+      outputOptions(cmd)
+    );
+  });
+  addManagementCommands(small, "small");
+  return group(model, "MODELS & SKILLS");
+}
+
+// src/commands/resource.ts
+import { Command as Command11 } from "commander";
+var int8 = (v) => Number.parseInt(v, 10);
+function resourceCommand() {
+  const cmd = new Command11("resource").alias("res").description("Resources \u2014 list, find, get, query, delete");
+  cmd.command("list").description("List resources under a datasource/catalog").option("--datasource-id <id>", "filter by datasource/catalog id").option("--type <category>", "resource category (table | logicview)").option("--limit <n>", "page size", int8, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).resource.list({
+      datasourceId: opts.datasourceId,
+      category: opts.type,
+      limit: opts.limit
+    });
+    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("--datasource-id <id>", "limit to a datasource/catalog").action(async (opts, cmd2) => {
+    const data = await clientFrom(cmd2).resource.find(opts.name, {
+      exact: opts.exact,
+      datasourceId: opts.datasourceId
+    });
+    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) => {
+    const data = await clientFrom(cmd2).resource.query(id, {
+      limit: opts.limit,
+      offset: opts.offset,
+      needTotal: opts.needTotal
+    });
+    printJson(data, outputOptions(cmd2));
+  });
+  cmd.command("delete <id>").description("Delete a resource").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).resource.delete(id), outputOptions(cmd2));
+  });
+  return group(cmd, "AI DATA PLATFORM");
+}
+
+// src/commands/skill.ts
+import { Command as Command12 } from "commander";
+var int9 = (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);
+  listOpts(cmd.command("list").description("List skills")).option("--create-user <s>", "filter by creator").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.list({
+        name: opts.name,
+        source: opts.source,
+        status: opts.status,
+        createUser: opts.createUser,
+        pageSize: opts.limit,
+        page: opts.page
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("get <skill-id>").description("Get a skill by id").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.get(id), outputOptions(cmd2));
+  });
+  listOpts(cmd.command("market").description("Browse the skill market")).action(
+    async (opts, cmd2) => {
+      printJson(
+        await clientFrom(cmd2).skills.market({
+          name: opts.name,
+          source: opts.source,
+          pageSize: opts.limit,
+          page: opts.page
+        }),
+        outputOptions(cmd2)
+      );
+    }
+  );
+  cmd.command("market-get <skill-id>").description("Get a market skill by id").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.marketGet(id), outputOptions(cmd2));
+  });
+  cmd.command("delete <skill-id>").description("Delete a skill").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.delete(id), outputOptions(cmd2));
+  });
+  cmd.command("content <skill-id>").description("Read a skill's SKILL.md content index").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.content(id), outputOptions(cmd2));
+  });
+  cmd.command("read-file <skill-id> <rel-path>").description("Read a file inside a skill (progressive)").action(async (id, relPath, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.readFile(id, relPath), outputOptions(cmd2));
+  });
+  cmd.command("history <skill-id>").description("Show a skill's version history").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.history(id), outputOptions(cmd2));
+  });
+  cmd.command("set-status <skill-id> <status>").description("Change status: unpublish | published | offline").action(async (id, status2, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.setStatus(id, status2),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", "source tag").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
+    const extendInfo = opts.extendInfo ? JSON.parse(opts.extendInfo) : void 0;
+    printJson(
+      await clientFrom(cmd2).skills.register(dir, { source: opts.source, extendInfo }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("download <skill-id> [out-path]").description("Download a skill archive to a local .zip").action(async (skillId, outPath, _o, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.download(skillId, outPath), outputOptions(cmd2));
+  });
+  cmd.command("install <skill-id> [directory]").description("Download a skill archive and extract it locally").action(async (skillId, dir, _o, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.install(skillId, dir), outputOptions(cmd2));
+  });
+  cmd.command("update-metadata <skill-id>").description("Update a skill's metadata (--body / --body-file JSON)").option("--body <json>", "metadata JSON").option("--body-file <path>", "read metadata JSON from a file").action(async (skillId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.updateMetadata(skillId, readBody(opts)),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("update-package <skill-id> <directory>").description("Replace a skill's package from a local directory").action(async (skillId, dir, _o, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.updatePackage(skillId, dir), outputOptions(cmd2));
+  });
+  cmd.command("republish <skill-id>").description("Republish a previous skill version").requiredOption("--version <v>", "version to republish").action(async (skillId, opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.republish(skillId, opts.version), outputOptions(cmd2));
+  });
+  cmd.command("publish-history <skill-id>").description("Publish a historical skill version").requiredOption("--version <v>", "version to publish").action(async (skillId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.publishHistory(skillId, opts.version),
+      outputOptions(cmd2)
+    );
+  });
+  return group(cmd, "MODELS & SKILLS");
+}
+
+// src/commands/toolbox.ts
+import { Command as Command13 } from "commander";
+var int10 = (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) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.list({
+        keyword: opts.keyword,
+        limit: opts.limit,
+        offset: opts.offset
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("create").description("Create a toolbox").requiredOption("--name <name>", "toolbox name").requiredOption("--service-url <url>", "tool service URL").option("--description <d>", "description").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.create({
+        name: opts.name,
+        serviceUrl: opts.serviceUrl,
+        description: opts.description
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("publish <box-id>").description("Publish a toolbox").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).toolboxes.publish(id), outputOptions(cmd2));
+  });
+  cmd.command("unpublish <box-id>").description("Unpublish a toolbox (status=draft)").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).toolboxes.unpublish(id), outputOptions(cmd2));
+  });
+  cmd.command("delete <box-id>").description("Delete a toolbox").option("-y, --yes", "skip confirmation").action(async (id, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).toolboxes.delete(id), outputOptions(cmd2));
+  });
+  cmd.command("export <box-id>").description("Export a toolbox config to a local .adp file").requiredOption("-o, --out <file>", "output .adp path").option("--type <t>", "impex type: toolbox | mcp | operator", "toolbox").action(async (boxId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.export(boxId, opts.out, opts.type),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("import <file>").description("Import a toolbox config from a local .adp file").option("--type <t>", "impex type: toolbox | mcp | operator", "toolbox").action(async (file, opts, cmd2) => {
+    printJson(await clientFrom(cmd2).toolboxes.import(file, opts.type), outputOptions(cmd2));
+  });
+  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));
+  });
+  cmd.command("enable <tool-ids...>").description("Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.setToolStatus(opts.toolbox, toolIds, "enabled"),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("disable <tool-ids...>").description("Disable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.setToolStatus(opts.toolbox, toolIds, "disabled"),
+      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 parseJson = (s, label) => {
+    if (!s) return void 0;
+    try {
+      return JSON.parse(s);
+    } catch {
+      throw new InputError(`--${label} must be valid JSON`);
+    }
+  };
+  const buildEnvelope = (opts) => ({
+    body: opts.body ? JSON.parse(opts.body) : void 0,
+    header: parseJson(opts.header, "header"),
+    query: parseJson(opts.query, "query"),
+    path: parseJson(opts.path, "path"),
+    timeout: opts.timeout ? Number(opts.timeout) : void 0
+  });
+  invokeOpts(
+    cmd.command("execute <tool-id>").description("Invoke a published+enabled tool")
+  ).action(async (toolId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.execute(opts.toolbox, toolId, buildEnvelope(opts)),
+      outputOptions(cmd2)
+    );
+  });
+  invokeOpts(
+    cmd.command("debug <tool-id>").description("Invoke a tool (draft/disabled too)")
+  ).action(async (toolId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.debug(opts.toolbox, toolId, buildEnvelope(opts)),
+      outputOptions(cmd2)
+    );
+  });
+  cmd.command("upload <file>").description("Upload a tool definition file (OpenAPI spec) into a toolbox").requiredOption("--toolbox <id>", "target toolbox id").option("--metadata-type <t>", "metadata type", "openapi").action(async (file, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.upload(opts.toolbox, file, opts.metadataType),
+      outputOptions(cmd2)
+    );
+  });
+  return group(cmd, "DECISION AGENT");
+}
+
+// src/commands/trace.ts
+import { readFileSync as readFileSync5, writeFileSync } from "fs";
+import { Command as Command14 } from "commander";
+
+// src/trace-ai/schema-validate.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { extname } from "path";
+import yaml from "js-yaml";
+import { z } from "zod";
+var Assertion = z.object({
+  type: z.enum([
+    "contains",
+    "not_contains",
+    "regex",
+    "tool_call_count",
+    "tool_call_order",
+    "latency_ms",
+    "semantic_match"
+  ])
+}).passthrough();
+var EvalCase = z.object({
+  query_id: z.string().optional(),
+  query: z.string().optional(),
+  input: z.object({ user_message: z.string() }).optional(),
+  reference: z.object({ answer: z.string() }).optional(),
+  assertions: z.array(Assertion).optional(),
+  tags: z.array(z.string()).optional()
+});
+var EvalSetFile = z.union([
+  z.array(EvalCase),
+  z.object({ cases: z.array(EvalCase) }),
+  z.object({ queries: z.array(EvalCase) })
+]);
+var DiagnosisRule = z.object({
+  id: z.string(),
+  severity: z.enum(["low", "medium", "high"]),
+  symptom: z.string(),
+  predicate: z.string().optional(),
+  rubric: z.unknown().optional(),
+  params: z.record(z.string(), z.unknown()).optional()
+});
+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);
+}
+function inferKind(data) {
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const o = data;
+    if ("predicate" in o || "rubric" in o || "symptom" in o && "severity" in o) return "rule";
+  }
+  return "eval-set";
+}
+function validateSchemaFile(file, kind) {
+  let data;
+  try {
+    data = parseFile(file);
+  } catch (e) {
+    return {
+      valid: false,
+      kind: kind ?? "eval-set",
+      file,
+      errors: [`parse error: ${e instanceof Error ? e.message : String(e)}`]
+    };
+  }
+  const resolved = kind ?? inferKind(data);
+  const schema = resolved === "rule" ? DiagnosisRule : EvalSetFile;
+  const result = schema.safeParse(data);
+  if (result.success) return { valid: true, kind: resolved, file, errors: [] };
+  return {
+    valid: false,
+    kind: resolved,
+    file,
+    errors: result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+  };
+}
+
+// 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"
+  );
+  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 }),
+      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("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, {
+      llm: Boolean(opts.llm)
+    });
+    const out = outputOptions(cmd2);
+    if (out.json) printJson(report, out);
+    else console.log(renderReportMarkdown(report));
+  });
+  cmd.command("scan <conversation-ids>").description("Batch-diagnose several conversations (comma-joined) + aggregate findings").option("--llm", "hybrid mode (rubric + synthesizer) per trace via local `claude`").action(async (ids, opts, cmd2) => {
+    const list = ids.split(",").map((s) => s.trim()).filter(Boolean);
+    printJson(
+      await clientFrom(cmd2).trace.scan(list, { llm: Boolean(opts.llm) }),
+      outputOptions(cmd2)
+    );
+  });
+  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 cases = clientFrom(cmd2).trace.evalSetBuild(raw);
+    if (opts.out) {
+      writeFileSync(opts.out, JSON.stringify({ cases }, null, 2));
+      printJson({ out: opts.out, cases: cases.length }, outputOptions(cmd2));
+    } else {
+      printJson({ cases }, outputOptions(cmd2));
+    }
+  });
+  evalSet.command("test <cases-file>").description("Run an eval set against an agent (--llm enables semantic_match)").requiredOption("--agent <id>", "agent id to run the queries against").option("--version <v>", "agent version", "v0").option("--llm", "enable semantic_match assertions via the local `claude` CLI").action(async (casesFile, opts, cmd2) => {
+    const raw = JSON.parse(readFileSync5(casesFile, "utf8"));
+    const cases = clientFrom(cmd2).trace.evalSetBuild(raw);
+    const result = await clientFrom(cmd2).trace.evalSetTest(opts.agent, cases, {
+      version: opts.version,
+      llm: Boolean(opts.llm)
+    });
+    printJson(result, outputOptions(cmd2));
+    if (result.failed > 0) process.exitCode = 1;
+  });
+  const schema = cmd.command("schema").description("Validate eval-set / diagnosis-rule files");
+  schema.command("validate <file>").description("Validate an eval-set or diagnosis-rule file (JSON/YAML) against its schema").option("--kind <k>", "force schema kind: eval-set | rule (default: auto-detect)").action(async (file, opts, cmd2) => {
+    const result = validateSchemaFile(file, opts.kind);
+    printJson(result, outputOptions(cmd2));
+    if (!result.valid) process.exitCode = 1;
+  });
+  return group(cmd, "TRACE AI");
+}
+
+// src/commands/vega.ts
+import { Command as Command15 } from "commander";
+function vegaCommand() {
+  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).action(async (_opts, cmd) => {
+    const o = cmd.optsWithGlobals();
+    const data = await clientFrom(cmd).vega.catalogs({ limit: o.limit, offset: o.offset });
+    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("health <ids...>").description("Health-status for one or more catalogs").action(async (ids, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.catalogHealth(ids), outputOptions(cmd));
+  });
+  const connector = vega.command("connector-type").description("Connector types");
+  connector.command("list").description("List connector types").action(async (_opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.connectorTypes(), outputOptions(cmd));
+  });
+  connector.command("get <type>").description("Get a connector type").action(async (type, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.connectorType(type), 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("--type <category>", "resource category").option("--limit <n>", "page size", (v) => Number.parseInt(v, 10), DEFAULT_LIST_LIMIT).action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).resource.list({
+        datasourceId: opts.datasourceId,
+        category: opts.type,
+        limit: opts.limit
+      }),
+      outputOptions(cmd)
+    );
+  });
+  resource.command("get <id>").description("Get a resource").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).resource.get(id), outputOptions(cmd));
+  });
+  resource.command("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) => {
+    printJson(
+      await clientFrom(cmd).resource.query(id, { limit: opts.limit, offset: opts.offset }),
+      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>", "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) => {
+    const o = cmd.optsWithGlobals();
+    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
+      },
+      { wait: Boolean(o.wait), timeoutMs: o.timeout * 1e3 }
+    );
+    printJson(task, outputOptions(cmd));
+  });
+  dataset.command("build-status <resource-id> <task-id>").description("Show a BuildTask's state and progress").action(async (_resourceId, taskId, _opts, cmd) => {
+    const task = await clientFrom(cmd).vega.buildStatus(taskId);
+    printJson(task, 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("--biz-domain <s>", "business domain (alias: -bd)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
+program.addCommand(authCommand());
+program.addCommand(callCommand());
+program.addCommand(configCommand());
+program.addCommand(vegaCommand());
+program.addCommand(bknCommand());
+program.addCommand(resourceCommand());
+program.addCommand(dataflowCommand());
+program.addCommand(contextCommand());
+program.addCommand(agentCommand());
+program.addCommand(modelCommand());
+program.addCommand(skillCommand());
+program.addCommand(toolboxCommand());
+program.addCommand(toolCommand());
+program.addCommand(traceCommand());
+program.addCommand(adminCommand());
+program.addCommand(exploreCommand());
+installGroupedHelp(program);
+var argv = process.argv.map((a) => a === "-bd" ? "--biz-domain" : a);
+try {
+  await program.parseAsync(argv);
+} catch (err) {
+  console.error(formatError(err));
+  process.exit(toExitCode(err));
+}
+//# sourceMappingURL=cli.js.map