kingminos 0.0.0-stage → 0.1.0

package/dist/kingminos.js

@@ -0,0 +1,1695 @@
+#!/usr/bin/env node
+
+// src/kingminos.ts
+import { readFileSync, realpathSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/sanitize.ts
+function stripSafeToWrite(value) {
+  if (Array.isArray(value)) {
+    return value.map(stripSafeToWrite);
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === "safe_to_write") {
+        continue;
+      }
+      out[key] = stripSafeToWrite(child);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/client.ts
+async function apiRequest(input) {
+  const headers = new Headers(input.headers);
+  headers.set("x-kingminos-client", "cli");
+  if (input.token) {
+    headers.set("Authorization", `Bearer ${input.token}`);
+  }
+  let body;
+  if (input.body !== void 0) {
+    headers.set("content-type", "application/json");
+    body = JSON.stringify(input.body);
+  }
+  const response = await input.fetch(input.url, {
+    method: input.method,
+    headers,
+    body
+  });
+  return {
+    status: response.status,
+    contentType: response.headers.get("content-type") ?? "",
+    text: await response.text()
+  };
+}
+function formatBody(text, contentType) {
+  const trimmed = text.replace(/^\uFEFF/, "");
+  if (trimmed === "") {
+    return "";
+  }
+  const jsonLike = contentType.includes("json") || looksLikeJson(trimmed);
+  if (jsonLike) {
+    try {
+      return `${JSON.stringify(stripSafeToWrite(JSON.parse(trimmed)), null, 2)}
+`;
+    } catch {
+    }
+  }
+  return trimmed.endsWith("\n") ? trimmed : `${trimmed}
+`;
+}
+function looksLikeJson(text) {
+  const start = text.trimStart()[0];
+  return start === "{" || start === "[";
+}
+
+// src/const.ts
+var DEFAULT_BASE_URL = "https://api.kingminos.com";
+var TOKEN_ENV = "KINGMINOS_API_KEY";
+var BASE_URL_ENV = "KINGMINOS_BASE_URL";
+var BYOK_PROVIDERS = [
+  "zoominfo",
+  "leadmagic",
+  "findymail",
+  "wiza",
+  "aiark",
+  "builtwith",
+  "prospeo",
+  "apollo",
+  "companyurlfinder",
+  "peopledatalabs",
+  "hginsights",
+  "brandfetch",
+  "enrichcrm",
+  "lemlist",
+  "snovio",
+  "cognism",
+  "lusha",
+  "starbridge",
+  "clay",
+  "databar",
+  "quickenrich",
+  "getleads",
+  "blitzapi"
+];
+function isByokProvider(value) {
+  return BYOK_PROVIDERS.includes(value);
+}
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["help", "h", "dry-run", "skip-cache", "json"]);
+var GLOBAL_FLAGS = /* @__PURE__ */ new Set(["token", "base-url", "help", "h", "json"]);
+var EXIT = {
+  ok: 0,
+  usage: 1,
+  unauthorized: 2,
+  payment: 3,
+  rateLimited: 4,
+  server: 5,
+  http: 6
+};
+
+// src/usage.ts
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+function assertNever(value, message) {
+  throw new Error(message ?? `unexpected value: ${String(value)}`);
+}
+
+// src/parse.ts
+var COMMAND_FLAGS = {
+  health: /* @__PURE__ */ new Set(),
+  openapi: /* @__PURE__ */ new Set(),
+  providers: /* @__PURE__ */ new Set(),
+  capabilities: /* @__PURE__ */ new Set(),
+  recipes: /* @__PURE__ */ new Set(),
+  batch: /* @__PURE__ */ new Set(["file", "priority", "explain", "schema", "dry-run", "path"]),
+  "company.resolve": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "domain",
+    "website",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "schema-version",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "path",
+    "preset",
+    "priority"
+  ]),
+  "company.domain": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "company-name",
+    "domain",
+    "website",
+    "city",
+    "state",
+    "country",
+    "postal-code",
+    "phone",
+    "linkedin-url",
+    "family-policy",
+    "path",
+    "preset",
+    "skip-cache",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "schema-version",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "cache",
+    "cache-control",
+    "priority"
+  ]),
+  "company.b2b_social": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "domain",
+    "website",
+    "linkedin-url",
+    "hint",
+    "country",
+    "path",
+    "preset",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "priority"
+  ]),
+  "company.icon": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "domain",
+    "website",
+    "dry-run",
+    "external-ref",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema"
+  ]),
+  "company.description": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "domain",
+    "website",
+    "path",
+    "preset",
+    "max-chars",
+    "skip-cache",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "cache",
+    "cache-control",
+    "priority"
+  ]),
+  "company.hierarchy": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "name",
+    "domain",
+    "website",
+    "country",
+    "path",
+    "preset",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "priority"
+  ]),
+  "person.verify_employment": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "first-name",
+    "last-name",
+    "linkedin-url",
+    "expected-company",
+    "expected-company-domain",
+    "expected-company-name",
+    "expected-company-website",
+    "dry-run",
+    "external-ref",
+    "routing",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "max-provider-credits",
+    "priority"
+  ]),
+  "person.language": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "first-name",
+    "last-name",
+    "linkedin-url",
+    "skip-cache",
+    "dry-run",
+    "external-ref",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "priority"
+  ]),
+  "person.phone": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "first-name",
+    "last-name",
+    "linkedin-url",
+    "domain",
+    "phone-types",
+    "max-results",
+    "format",
+    "skip-cache",
+    "dry-run",
+    "external-ref",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "cache",
+    "cache-control",
+    "priority"
+  ]),
+  "person.title": /* @__PURE__ */ new Set([
+    "body",
+    "email",
+    "first-name",
+    "last-name",
+    "linkedin-url",
+    "company-domain",
+    "fields",
+    "path",
+    "routing",
+    "skip-cache",
+    "dry-run",
+    "external-ref",
+    "compliance",
+    "idempotency-key",
+    "explain",
+    "schema",
+    "cache",
+    "cache-control",
+    "priority"
+  ]),
+  "runs.get": /* @__PURE__ */ new Set(["explain", "schema"]),
+  "credentials.put": /* @__PURE__ */ new Set(["body", "api-key", "client-id", "client-secret"]),
+  "credentials.delete": /* @__PURE__ */ new Set(),
+  "subjects.delete": /* @__PURE__ */ new Set(),
+  help: /* @__PURE__ */ new Set()
+};
+var KNOWN_FLAGS = /* @__PURE__ */ new Set([
+  ...GLOBAL_FLAGS,
+  ...BOOLEAN_FLAGS,
+  ...Object.values(COMMAND_FLAGS).flatMap((names) => [...names])
+]);
+function parseArgv(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === void 0) {
+      break;
+    }
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const rawName = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+      const name = rawName.trim();
+      if (!name) {
+        throw new UsageError("empty flag");
+      }
+      if (!KNOWN_FLAGS.has(name)) {
+        throw new UsageError(`unknown flag --${name}`);
+      }
+      if (BOOLEAN_FLAGS.has(name)) {
+        if (eq !== -1) {
+          throw new UsageError(`--${name} does not take a value`);
+        }
+        flags[name] = true;
+        continue;
+      }
+      const value = eq === -1 ? argv[i + 1] : arg.slice(eq + 1);
+      if (eq === -1) {
+        i += 1;
+      }
+      if (value === void 0 || eq === -1 && value.startsWith("--")) {
+        throw new UsageError(`--${name} requires a value`);
+      }
+      flags[name] = value;
+      continue;
+    }
+    if (arg === "-h") {
+      flags.help = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new UsageError(`unknown flag ${arg}`);
+    }
+    positionals.push(arg);
+  }
+  return { positionals, flags };
+}
+function resolveCommand(positionals) {
+  if (positionals.length === 0) {
+    return { name: "help" };
+  }
+  const [head, mid, tail, ...rest] = positionals;
+  if (rest.length > 0) {
+    throw new UsageError(`unexpected arguments: ${rest.join(" ")}`);
+  }
+  switch (head) {
+    case "help":
+      return { name: "help", topic: mid };
+    case "health":
+    case "openapi":
+    case "providers":
+    case "capabilities":
+    case "recipes":
+      if (mid !== void 0) {
+        throw new UsageError(`${head} does not take arguments`);
+      }
+      return { name: head };
+    case "batch":
+      return resolveBatch(mid, tail);
+    case "company":
+      return resolveCompany(mid, tail);
+    case "person":
+      if (mid !== "verify-employment" && mid !== "language" && mid !== "phone" && mid !== "title") {
+        throw new UsageError("person commands: verify-employment | language | phone | title");
+      }
+      if (tail !== void 0) {
+        throw new UsageError(`person ${mid} does not take positional arguments`);
+      }
+      if (mid === "language") {
+        return { name: "person.language" };
+      }
+      if (mid === "phone") {
+        return { name: "person.phone" };
+      }
+      if (mid === "title") {
+        return { name: "person.title" };
+      }
+      return { name: "person.verify_employment" };
+    case "runs":
+      if (mid !== "get" || !tail) {
+        throw new UsageError("runs commands: get <id>");
+      }
+      return { name: "runs.get", id: tail };
+    case "credentials":
+      if (mid !== "put" && mid !== "delete" || !tail) {
+        throw new UsageError("credentials commands: put <provider> | delete <provider>");
+      }
+      return mid === "put" ? { name: "credentials.put", provider: tail } : { name: "credentials.delete", provider: tail };
+    case "subjects":
+      if (mid !== "delete" || !tail) {
+        throw new UsageError("subjects commands: delete <subject_key>");
+      }
+      return { name: "subjects.delete", subjectKey: tail };
+    default:
+      throw new UsageError(`unknown command ${head}`);
+  }
+}
+function resolveBatch(mid, tail) {
+  if (mid === "company") {
+    const inner = resolveCompany(tail, void 0);
+    switch (inner.name) {
+      case "company.resolve":
+      case "company.domain":
+      case "company.hierarchy":
+      case "company.b2b_social":
+      case "company.icon":
+      case "company.description":
+        return { name: "batch", capability: inner.name };
+      default:
+        throw new UsageError(
+          "batch company commands: resolve | domain | hierarchy | b2b-social | icon | description"
+        );
+    }
+  }
+  if (mid === "person") {
+    if (tail !== "verify-employment" && tail !== "language" && tail !== "phone" && tail !== "title") {
+      throw new UsageError("batch person commands: verify-employment | language | phone | title");
+    }
+    if (tail === "language") {
+      return { name: "batch", capability: "person.language" };
+    }
+    if (tail === "phone") {
+      return { name: "batch", capability: "person.phone" };
+    }
+    if (tail === "title") {
+      return { name: "batch", capability: "person.title" };
+    }
+    return { name: "batch", capability: "person.verify_employment" };
+  }
+  throw new UsageError(
+    "batch commands: batch <company|person> <command> --file <jsonl> --priority speed|balance|accuracy|coverage"
+  );
+}
+function resolveCompany(mid, tail) {
+  if (tail !== void 0) {
+    throw new UsageError(
+      "company <resolve|domain|hierarchy|b2b-social|icon|description> does not take positional arguments"
+    );
+  }
+  switch (mid) {
+    case "resolve":
+      return { name: "company.resolve" };
+    case "domain":
+      return { name: "company.domain" };
+    case "hierarchy":
+      return { name: "company.hierarchy" };
+    case "b2b-social":
+      return { name: "company.b2b_social" };
+    case "icon":
+      return { name: "company.icon" };
+    case "description":
+      return { name: "company.description" };
+    default:
+      throw new UsageError(
+        "company commands: resolve | domain | hierarchy | b2b-social | icon | description"
+      );
+  }
+}
+function assertKnownFlags(commandName, flags) {
+  const allowed = COMMAND_FLAGS[commandName];
+  if (!allowed) {
+    throw new UsageError(`unknown command ${commandName}`);
+  }
+  for (const name of Object.keys(flags)) {
+    if (GLOBAL_FLAGS.has(name) || allowed.has(name)) {
+      continue;
+    }
+    throw new UsageError(`unknown flag --${name}`);
+  }
+}
+function flagString(flags, name) {
+  const value = flags[name];
+  if (value === void 0 || value === true) {
+    return void 0;
+  }
+  return value;
+}
+function flagBool(flags, name) {
+  return flags[name] === true ? true : void 0;
+}
+
+// src/priority.ts
+var PRIORITY_HELP = "Before a bulk run, ask which path: speed, balance, accuracy, or coverage. Re-run with --priority speed|balance|accuracy|coverage. Max yield = coverage. company.resolve value is the one-step lookup, not a tier.";
+function parsePriority(value) {
+  switch (value) {
+    case "speed":
+    case "balance":
+    case "accuracy":
+    case "coverage":
+      return value;
+    default:
+      throw new UsageError(PRIORITY_HELP);
+  }
+}
+function pathForPriority(priority) {
+  return priority;
+}
+function applyPriority(body, priority, _capability) {
+  const path = pathForPriority(priority);
+  const routing = body.routing && typeof body.routing === "object" && !Array.isArray(body.routing) ? body.routing : {};
+  return { ...body, routing: { ...routing, path } };
+}
+function formatDecisionNotes(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return "";
+  }
+  const record = body;
+  const lines = [];
+  const confidence = record.answer?.confidence;
+  if (confidence === "high" || confidence === "medium" || confidence === "low") {
+    lines.push(`Confidence: ${confidence}`);
+  } else if (confidence === null) {
+    lines.push("Confidence: none");
+  }
+  const spent = record.usage?.credits?.spent;
+  if (typeof spent === "number") {
+    lines.push(`Credits spent: ${spent}`);
+  }
+  return lines.length > 0 ? `
+${lines.join("\n")}
+` : "";
+}
+function formatNextStepsHints(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return "";
+  }
+  const steps = body.next_steps;
+  if (!Array.isArray(steps) || steps.length === 0) {
+    return "";
+  }
+  const lines = ["", "Next:"];
+  for (const raw of steps) {
+    if (!raw || typeof raw !== "object") {
+      continue;
+    }
+    const step = raw;
+    const credits = typeof step.est_credits === "number" ? ` (~${step.est_credits} credits)` : "";
+    const target = step.capability ? ` ${step.capability}` : "";
+    lines.push(`- ${step.action ?? "next"}${target}${credits}: ${step.reason ?? ""}`.trim());
+    if (step.suggested && typeof step.suggested === "object") {
+      lines.push(`  suggested: ${JSON.stringify(step.suggested)}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands.ts
+function buildRequest(command, flags, loader) {
+  switch (command.name) {
+    case "help":
+      throw new UsageError("help is not an HTTP call");
+    case "batch":
+      throw new UsageError("batch is not a single HTTP call");
+    case "health":
+      return { method: "GET", path: "/health", headers: {}, auth: false };
+    case "openapi":
+      return { method: "GET", path: "/openapi.yaml", headers: {}, auth: false };
+    case "providers":
+      return { method: "GET", path: "/v1/providers", headers: {}, auth: true };
+    case "capabilities":
+      return { method: "GET", path: "/v1/capabilities", headers: {}, auth: true };
+    case "recipes":
+      return { method: "GET", path: "/v1/recipes", headers: {}, auth: true };
+    case "company.resolve":
+      return capabilityPost("/v1/company/resolve", resolveBody(flags, loader), flags);
+    case "company.domain":
+      return capabilityPost("/v1/company/domain", domainBody(flags, loader), flags, {
+        cache: true
+      });
+    case "company.hierarchy":
+      return capabilityPost("/v1/company/hierarchy", hierarchyBody(flags, loader), flags);
+    case "company.b2b_social":
+      return capabilityPost("/v1/company/b2b-social", b2bSocialBody(flags, loader), flags);
+    case "company.icon":
+      return capabilityPost("/v1/company/icon", iconBody(flags, loader), flags);
+    case "company.description":
+      return capabilityPost("/v1/company/description", descriptionBody(flags, loader), flags, {
+        cache: true
+      });
+    case "person.verify_employment":
+      return capabilityPost("/v1/person/verify-employment", employmentBody(flags, loader), flags);
+    case "person.language":
+      return capabilityPost("/v1/person/language", languageBody(flags, loader), flags);
+    case "person.phone":
+      return capabilityPost("/v1/person/phone", phoneBody(flags, loader), flags, {
+        cache: true
+      });
+    case "person.title":
+      return capabilityPost("/v1/person/title", titleBody(flags, loader), flags, {
+        cache: true
+      });
+    case "runs.get":
+      return {
+        method: "GET",
+        path: `/v1/runs/${encodeURIComponent(command.id)}`,
+        headers: explainSchemaHeaders(flags),
+        auth: true
+      };
+    case "credentials.put":
+      return {
+        method: "PUT",
+        path: `/v1/credentials/${encodeURIComponent(parseProvider(command.provider))}`,
+        headers: {},
+        body: credentialsPutBody(command.provider, flags, loader),
+        auth: true
+      };
+    case "credentials.delete":
+      return {
+        method: "DELETE",
+        path: `/v1/credentials/${encodeURIComponent(parseProvider(command.provider))}`,
+        headers: {},
+        auth: true
+      };
+    case "subjects.delete":
+      return {
+        method: "DELETE",
+        path: `/v1/subjects/${encodeURIComponent(command.subjectKey)}`,
+        headers: {},
+        auth: true
+      };
+    default:
+      return assertNever(command);
+  }
+}
+function capabilityPost(path, body, flags, options) {
+  return {
+    method: "POST",
+    path,
+    headers: {
+      ...explainSchemaHeaders(flags),
+      ...optionalHeader("Idempotency-Key", flagString(flags, "idempotency-key")),
+      ...optionalHeader("X-Router-Max-Provider-Credits", flagString(flags, "max-provider-credits")),
+      ...options?.cache ? {
+        ...optionalHeader("X-Router-Cache", flagString(flags, "cache")),
+        ...optionalHeader("Cache-Control", flagString(flags, "cache-control"))
+      } : {}
+    },
+    body,
+    auth: true
+  };
+}
+function explainSchemaHeaders(flags) {
+  return {
+    ...optionalHeader("X-Router-Explain", flagString(flags, "explain")),
+    ...optionalHeader("X-Router-Schema", flagString(flags, "schema"))
+  };
+}
+function optionalHeader(name, value) {
+  return value === void 0 ? {} : { [name]: value };
+}
+function resolveBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  assignString(body, "schema_version", flags, "schema-version");
+  assignString(body, "path", flags);
+  assignString(body, "preset", flags);
+  return withPriority(body, flags, "company.resolve");
+}
+function domainBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "company_name", flags, "company-name");
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignString(body, "city", flags);
+  assignString(body, "state", flags);
+  assignString(body, "country", flags);
+  assignString(body, "postal_code", flags, "postal-code");
+  assignString(body, "phone", flags);
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  assignString(body, "family_policy", flags, "family-policy");
+  assignString(body, "path", flags);
+  assignString(body, "preset", flags);
+  if (flagBool(flags, "skip-cache")) {
+    body.skip_cache = true;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  assignString(body, "schema_version", flags, "schema-version");
+  return withPriority(body, flags, "company.domain");
+}
+function b2bSocialBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  assignString(body, "hint", flags);
+  assignString(body, "country", flags);
+  assignString(body, "path", flags);
+  assignString(body, "preset", flags);
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "company.b2b_social");
+}
+function iconBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignCommon(body, flags);
+  assignJson(body, "compliance", flags);
+  return body;
+}
+function descriptionBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignString(body, "path", flags);
+  assignString(body, "preset", flags);
+  assignInteger(body, "max_chars", flags, "max-chars", 80, 500);
+  if (flagBool(flags, "skip-cache")) {
+    body.skip_cache = true;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "company.description");
+}
+function hierarchyBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "name", flags);
+  assignString(body, "domain", flags);
+  assignString(body, "website", flags);
+  assignString(body, "country", flags);
+  assignString(body, "path", flags);
+  assignString(body, "preset", flags);
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "company.hierarchy");
+}
+function employmentBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "first_name", flags, "first-name");
+  assignString(body, "last_name", flags, "last-name");
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  const expected = expectedCompany(flags);
+  if (expected) {
+    body.expected_company = expected;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "person.verify_employment");
+}
+function languageBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  assignString(body, "first_name", flags, "first-name");
+  assignString(body, "last_name", flags, "last-name");
+  if (flagBool(flags, "skip-cache")) {
+    body.skip_cache = true;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "person.language");
+}
+function phoneBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  assignString(body, "first_name", flags, "first-name");
+  assignString(body, "last_name", flags, "last-name");
+  assignString(body, "domain", flags);
+  const phoneTypes = flagString(flags, "phone-types");
+  if (phoneTypes !== void 0) {
+    const types = phoneTypes.split(",").map((type) => type.trim()).filter(Boolean);
+    if (types.length > 0) {
+      body.phone_types = types;
+    }
+  }
+  const maxResults = Number(flagString(flags, "max-results"));
+  if (Number.isInteger(maxResults) && maxResults >= 1) {
+    body.max_results = maxResults;
+  }
+  assignString(body, "format", flags);
+  if (flagBool(flags, "skip-cache")) {
+    body.skip_cache = true;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "person.phone");
+}
+function titleBody(flags, loader) {
+  const body = baseBody(flags, loader);
+  assignString(body, "email", flags);
+  assignString(body, "linkedin_url", flags, "linkedin-url");
+  assignString(body, "first_name", flags, "first-name");
+  assignString(body, "last_name", flags, "last-name");
+  assignString(body, "company_domain", flags, "company-domain");
+  const fields = flagString(flags, "fields");
+  if (fields !== void 0) {
+    const list = fields.split(",").map((field) => field.trim()).filter(Boolean);
+    if (list.length > 0) {
+      body.fields = list;
+    }
+  }
+  if (flagBool(flags, "skip-cache")) {
+    body.skip_cache = true;
+  }
+  assignCommon(body, flags);
+  assignJson(body, "routing", flags);
+  const path = flagString(flags, "path");
+  if (path !== void 0) {
+    const routing = body.routing && typeof body.routing === "object" && !Array.isArray(body.routing) ? body.routing : {};
+    body.routing = { ...routing, path };
+  }
+  assignJson(body, "compliance", flags);
+  return withPriority(body, flags, "person.title");
+}
+function expectedCompany(flags) {
+  const fromJson = parseJsonFlag(flags, "expected-company");
+  const company = fromJson ? { ...fromJson } : {};
+  const domain = flagString(flags, "expected-company-domain");
+  const name = flagString(flags, "expected-company-name");
+  const website = flagString(flags, "expected-company-website");
+  if (domain !== void 0) {
+    company.domain = domain;
+  }
+  if (name !== void 0) {
+    company.name = name;
+  }
+  if (website !== void 0) {
+    company.website = website;
+  }
+  return Object.keys(company).length > 0 ? company : void 0;
+}
+function withPriority(body, flags, capability) {
+  const raw = flagString(flags, "priority");
+  if (raw === void 0) {
+    return body;
+  }
+  return applyPriority(body, parsePriority(raw), capability);
+}
+function assignCommon(body, flags) {
+  if (flagBool(flags, "dry-run")) {
+    body.dry_run = true;
+  }
+  assignString(body, "external_ref", flags, "external-ref");
+}
+function assignString(body, field, flags, flagName = field.replaceAll("_", "-")) {
+  const value = flagString(flags, flagName);
+  if (value !== void 0) {
+    body[field] = value;
+  }
+}
+function assignInteger(body, field, flags, flagName, min, max) {
+  const raw = flagString(flags, flagName);
+  if (raw === void 0) {
+    return;
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value)) {
+    throw new UsageError(`--${flagName} must be an integer`);
+  }
+  if (value < min || value > max) {
+    throw new UsageError(`--${flagName} must be between ${min} and ${max}`);
+  }
+  body[field] = value;
+}
+function assignJson(body, field, flags) {
+  const parsed = parseJsonFlag(flags, field);
+  if (parsed) {
+    body[field] = parsed;
+  }
+}
+function parseJsonFlag(flags, name) {
+  const raw = flagString(flags, name);
+  if (raw === void 0) {
+    return void 0;
+  }
+  return parseObjectJson(raw, `--${name}`);
+}
+function baseBody(flags, loader) {
+  const raw = flagString(flags, "body");
+  if (raw === void 0) {
+    return {};
+  }
+  return { ...loadBodyObject(raw, loader) };
+}
+function loadBodyObject(raw, loader) {
+  if (raw === "-") {
+    return parseObjectJson(loader.stdin, "--body -");
+  }
+  if (raw.startsWith("@")) {
+    const path = raw.slice(1);
+    if (!path) {
+      throw new UsageError("--body @file requires a path");
+    }
+    return parseObjectJson(loader.readFile(path), `--body @${path}`);
+  }
+  return parseObjectJson(raw, "--body");
+}
+function parseObjectJson(raw, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new UsageError(`${label} is not valid JSON`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new UsageError(`${label} must be a JSON object`);
+  }
+  return parsed;
+}
+function parseProvider(provider) {
+  if (provider === "websearch") {
+    throw new UsageError("websearch is house-only (byok_not_supported)");
+  }
+  if (!isByokProvider(provider)) {
+    throw new UsageError(`unknown_provider: ${provider}`);
+  }
+  return provider;
+}
+function credentialsPutBody(provider, flags, loader) {
+  const rawBody = flagString(flags, "body");
+  const fromFile = rawBody ? loadBodyObject(rawBody, loader) : void 0;
+  if (provider === "zoominfo") {
+    const clientId = flagString(flags, "client-id") ?? stringField(fromFile, "clientId");
+    const clientSecret = flagString(flags, "client-secret") ?? stringField(fromFile, "clientSecret");
+    if (!clientId || !clientSecret) {
+      throw new UsageError(
+        "credentials put zoominfo requires --client-id and --client-secret (or --body { clientId, clientSecret })"
+      );
+    }
+    return { clientId, clientSecret };
+  }
+  if (fromFile && flagString(flags, "api-key") === void 0 && (stringField(fromFile, "apiKey") || stringField(fromFile, "api_key"))) {
+    return fromFile;
+  }
+  const apiKey = flagString(flags, "api-key") ?? stringField(fromFile, "apiKey") ?? stringField(fromFile, "api_key");
+  if (!apiKey) {
+    throw new UsageError(`credentials put ${provider} requires --api-key (or --body { apiKey })`);
+  }
+  return { apiKey };
+}
+function stringField(body, key) {
+  const value = body?.[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+
+// src/help.ts
+var ROOT_HELP = `King Minos CLI \u2014 KingMinos by OutboundSync
+
+Usage:
+  kingminos [--token <key>] [--base-url <url>] [--json] <command>
+
+Auth:
+  Pass a tenant Bearer with --token or ${TOKEN_ENV}.
+  Tenant keys use the osr_ prefix. App-minted user tokens use km_.
+  Mint a key at https://app.kingminos.com after sign-in.
+  The CLI never stores or logs a key.
+
+API:
+  Default ${DEFAULT_BASE_URL}
+  Override with --base-url or ${BASE_URL_ENV}
+
+Global flags:
+  --token <key>       Bearer token (overrides ${TOKEN_ENV})
+  --base-url <url>    API host
+  --json              Print the response body only (no Next: hints)
+  --help, -h          This help
+
+Commands (live OpenAPI only):
+  health                         GET  /health
+  openapi                        GET  /openapi.yaml
+  providers                      GET  /v1/providers
+  capabilities                   GET  /v1/capabilities
+  recipes                        GET  /v1/recipes
+  company resolve                POST /v1/company/resolve
+  company domain                 POST /v1/company/domain
+  company hierarchy              POST /v1/company/hierarchy
+  company b2b-social             POST /v1/company/b2b-social
+  company icon                   POST /v1/company/icon
+  company description            POST /v1/company/description
+  person verify-employment       POST /v1/person/verify-employment
+  person language                POST /v1/person/language
+  person phone                   POST /v1/person/phone
+  person title                   POST /v1/person/title
+  runs get <id>                  GET  /v1/runs/{id}
+  credentials put <provider>     PUT  /v1/credentials/{provider}
+  credentials delete <provider>  DELETE /v1/credentials/{provider}
+  subjects delete <subject_key>  DELETE /v1/subjects/{subject_key}
+  batch <company|person> <cmd>   POST each JSONL/JSON-array row (requires --file --priority)
+
+Tiers:
+  --priority speed|balance|accuracy|coverage maps to routing.path.
+  Ask which path before a bulk run. Max yield = coverage.
+  company.resolve value is the one-step lookup, not a tier.
+
+Credits:
+  Billing is for delivered answers. Print usage.credits.spent from the response.
+  The CLI does not hardcode prices.
+
+Your Keys providers: ${BYOK_PROVIDERS.join(", ")}
+Websearch is house-only (no credentials command).
+LeadMagic, Wiza, Findymail, and AI Ark are house-key vendors. ZoomInfo, BuiltWith,
+Prospeo, Apollo, Company URL Finder, People Data Labs, HG Insights, Brandfetch,
+and Enrich-CRM stay BYOK.
+
+Exit codes: 0 ok \xB7 1 usage \xB7 2 unauthorized (401) \xB7 3 out of credits (402)
+            4 rate limited (429) \xB7 5 server (5xx) \xB7 6 other HTTP error
+
+See kingminos <command> --help for request fields on that call.
+`;
+function commandHelp(command) {
+  switch (command) {
+    case "health":
+      return `kingminos health
+
+GET /health (no auth)
+`;
+    case "openapi":
+      return `kingminos openapi
+
+GET /openapi.yaml (no auth)
+Prints the live OpenAPI document.
+`;
+    case "providers":
+      return `kingminos providers
+
+GET /v1/providers
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+`;
+    case "capabilities":
+      return `kingminos capabilities
+
+GET /v1/capabilities
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+`;
+    case "recipes":
+      return `kingminos recipes
+
+GET /v1/recipes
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+Machine-readable chaining workflows. Ask speed / balance / accuracy / coverage before a bulk run. Max yield = coverage.
+`;
+    case "batch":
+      return `kingminos batch <company|person> <command> --file <path|-> --priority speed|balance|accuracy|coverage
+
+Client-side loop over JSONL (or a JSON array) of request bodies. Not a bulk API.
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+Ask speed / balance / accuracy / coverage before a list run; --priority is required. Max yield = coverage.
+`;
+    case "company.resolve":
+      return `kingminos company resolve
+
+POST /v1/company/resolve
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --name --domain --website --dry-run --external-ref
+             --path --preset --priority speed|balance|accuracy|coverage
+             --routing <json> --compliance <json> --schema-version 2
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2 --max-provider-credits <n>
+`;
+    case "company.domain":
+      return `kingminos company domain
+
+POST /v1/company/domain
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --name --company-name --domain --website
+             --city --state --country --postal-code --phone --linkedin-url
+             --family-policy collapse_brand|separate_regional
+             --path --preset --priority speed|balance|accuracy|coverage
+             --skip-cache --dry-run --external-ref
+             --routing <json> --compliance <json> --schema-version 2
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal --schema 2
+             --max-provider-credits <n> --cache bypass
+             --cache-control no-cache|no-store
+`;
+    case "company.b2b_social":
+      return `kingminos company b2b-social
+
+POST /v1/company/b2b-social
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Decide the company's B2B social page URL (result.linkedin_url).
+Pass --domain (required). --name is optional ranking only.
+--path speed is the bulk-list path (homepage-first, then ranked search).
+Delivered answers are billed; misses are not. See usage.credits.spent.
+Do not use company resolve for a B2B social page.
+
+Body fields: --email --name --domain --website --linkedin-url
+             --hint --country
+             --path --preset --priority speed|balance|accuracy|coverage
+             --dry-run --external-ref
+             --routing <json> --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2 --max-provider-credits <n>
+`;
+    case "company.icon":
+      return `kingminos company icon
+
+POST /v1/company/icon
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --name --domain --website
+             --dry-run --external-ref
+             --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2
+`;
+    case "company.description":
+      return `kingminos company description
+
+POST /v1/company/description
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --name --domain --website
+             --path --preset --priority speed|balance|accuracy|coverage
+             --max-chars <80-500> --skip-cache --dry-run --external-ref
+             --routing <json> --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2 --max-provider-credits <n>
+             --cache bypass --cache-control no-cache|no-store
+`;
+    case "company.hierarchy":
+      return `kingminos company hierarchy
+
+POST /v1/company/hierarchy
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --name --domain --website --country
+             --path --preset --priority speed|balance|accuracy|coverage
+             --dry-run --external-ref
+             --routing <json> --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2 --max-provider-credits <n>
+`;
+    case "person.verify_employment":
+      return `kingminos person verify-employment
+
+POST /v1/person/verify-employment
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email --first-name --last-name --linkedin-url
+             --expected-company <json>
+             --expected-company-domain --expected-company-name
+             --expected-company-website --priority speed|balance|accuracy|coverage
+             --dry-run --external-ref --routing <json> --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal
+             --schema 2 --max-provider-credits <n>
+`;
+    case "person.language":
+      return `kingminos person language
+
+POST /v1/person/language
+Can we engage this person in English, and if not, in what language?
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email | --linkedin-url (one required)
+             --first-name --last-name (match-only: rejects a mismatched profile)
+             --priority speed|balance|accuracy --skip-cache
+             --dry-run --external-ref --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal --schema 2
+`;
+    case "person.phone":
+      return `kingminos person phone
+
+POST /v1/person/phone
+One dialable phone number for a person, plus the ranked rest.
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email | --linkedin-url (one required)
+             --first-name --last-name (match-only: rejects a mismatched profile)
+             --domain
+             --phone-types mobile,landline,other,unknown (omit = any)
+             --max-results <1-10> (default 3)
+             --format e164|international|national|digits|digits_national
+                      (fills \`number\`; default e164; every phone also has \`formats\`)
+             --priority speed|balance|accuracy|coverage
+             --skip-cache --dry-run --external-ref --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal --schema 2
+             --cache bypass --cache-control no-cache|no-store
+`;
+    case "person.title":
+      return `kingminos person title
+
+POST /v1/person/title
+A person's current job title, seniority and function.
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Body fields: --email | --linkedin-url (one required)
+             --first-name --last-name (match-only: rejects a mismatched profile)
+             --company-domain (match-only current employer)
+             --fields title,seniority,function (omit = all three)
+             --path speed|balance|accuracy|coverage
+             --priority speed|balance|accuracy|coverage
+             --routing <json> (only / ignore)
+             --skip-cache --dry-run --external-ref --compliance <json>
+             --body <json|@file|->
+Headers:     --idempotency-key --explain default|full|minimal --schema 2
+             --cache bypass --cache-control no-cache|no-store
+Delivered answers are billed; misses are not. See usage.credits.spent.
+`;
+    case "runs.get":
+      return `kingminos runs get <id>
+
+GET /v1/runs/{id}
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+
+Headers: --explain default|full|minimal --schema 2
+`;
+    case "credentials.put":
+      return `kingminos credentials put <provider>
+
+PUT /v1/credentials/{provider}
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+Providers: ${BYOK_PROVIDERS.join(", ")}
+Websearch is house-only (byok_not_supported).
+
+zoominfo:  --client-id --client-secret  \u2192 { clientId, clientSecret }
+others:    --api-key                    \u2192 { apiKey }
+or --body <json|@file|->  (api_key alias accepted by the API)
+
+Responses never include the raw key. This CLI does not store or log it.
+`;
+    case "credentials.delete":
+      return `kingminos credentials delete <provider>
+
+DELETE /v1/credentials/{provider}
+Requires tenant Bearer (--token or ${TOKEN_ENV}).
+Providers: ${BYOK_PROVIDERS.join(", ")}
+`;
+    case "subjects.delete":
+      return `kingminos subjects delete <subject_key>
+
+DELETE /v1/subjects/{subject_key}
+Requires tenant Bearer with erase scope (--token or ${TOKEN_ENV}).
+Company: registrable domain. Person: email:<addr> or li:<slug>.
+`;
+    default:
+      return ROOT_HELP;
+  }
+}
+
+// src/http-error.ts
+function classifyHttpError(status, body) {
+  const extra = errorSuffix(body);
+  if (status === 401) {
+    return {
+      exitCode: EXIT.unauthorized,
+      message: `Unauthorized (401)${authDetail(body)}. Set KINGMINOS_API_KEY or pass --token.${extra}`
+    };
+  }
+  if (status === 402) {
+    return {
+      exitCode: EXIT.payment,
+      message: `Out of credits (402). Add credits at https://app.kingminos.com.${extra}`
+    };
+  }
+  if (status === 429) {
+    const budget = isBudgetError(body);
+    return {
+      exitCode: EXIT.rateLimited,
+      message: budget ? `Out of credits or daily key budget (429). Retry after Retry-After, or add credits.${extra}` : `Rate limited (429). Retry after the Retry-After header.${extra}`
+    };
+  }
+  if (status >= 500) {
+    return {
+      exitCode: EXIT.server,
+      message: `KingMinos server error (${status}). Retry the same Idempotency-Key if you sent one.${extra}`
+    };
+  }
+  return {
+    exitCode: EXIT.http,
+    message: `HTTP ${status}${extra}`
+  };
+}
+function authDetail(body) {
+  const detail = stringField2(body, "detail");
+  switch (detail) {
+    case "missing":
+      return ": missing Bearer token";
+    case "malformed":
+      return ": malformed Bearer token (send `Authorization: Bearer <key>`, not a bare key)";
+    case "mismatch":
+      return ": API key did not match";
+    case void 0:
+      return ": missing, malformed, or mismatched API key";
+    default:
+      return `: ${detail}`;
+  }
+}
+function isBudgetError(body) {
+  const error = stringField2(body, "error") ?? "";
+  return error === "key_budget_exhausted" || error === "tenant_budget_exhausted" || error.includes("budget") || error.includes("credit");
+}
+function errorSuffix(body) {
+  const error = stringField2(body, "error");
+  const hint = stringField2(body, "hint");
+  const parts = [error, hint].filter((part) => Boolean(part));
+  return parts.length > 0 ? ` ${parts.join(" \u2014 ")}` : "";
+}
+function stringField2(body, key) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return void 0;
+  }
+  const value = body[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+
+// src/kingminos.ts
+async function runCli(io) {
+  try {
+    return await runCliUnsafe(io);
+  } catch (error) {
+    const secrets = collectSecrets(io);
+    if (error instanceof UsageError) {
+      io.stderr(`${redact(error.message, secrets)}
+`);
+      return EXIT.usage;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    io.stderr(`${redact(message, secrets)}
+`);
+    return EXIT.usage;
+  }
+}
+async function runCliUnsafe(io) {
+  const parsed = parseArgv(io.argv);
+  if (parsed.flags.help === true || parsed.flags.h === true) {
+    if (parsed.positionals.length === 0) {
+      io.stdout(ROOT_HELP);
+      return 0;
+    }
+    const command2 = resolveCommand(parsed.positionals);
+    io.stdout(command2.name === "help" ? ROOT_HELP : commandHelp(command2.name));
+    return 0;
+  }
+  const command = resolveCommand(parsed.positionals);
+  if (command.name === "help") {
+    io.stdout(command.topic ? commandHelp(helpTopic(command.topic)) : ROOT_HELP);
+    return 0;
+  }
+  assertKnownFlags(command.name, parsed.flags);
+  if (command.name === "batch") {
+    return runBatch(io, command, parsed.flags);
+  }
+  const request = buildRequest(command, parsed.flags, {
+    readFile: io.readFile ?? ((path) => readFileSync(path, "utf8")),
+    stdin: io.stdin ?? ""
+  });
+  const token = request.auth ? requireToken(parsed.flags, io.env) : void 0;
+  const baseUrl = resolveBaseUrl(parsed.flags, io.env);
+  const response = await apiRequest({
+    fetch: io.fetch,
+    method: request.method,
+    url: `${baseUrl}${request.path}`,
+    token,
+    headers: request.headers,
+    body: request.body
+  });
+  const formatted = formatBody(response.text, response.contentType);
+  const secrets = collectSecrets(io, parsed.flags);
+  const asJson = flagBool(parsed.flags, "json") === true;
+  if (response.status >= 400) {
+    return writeHttpError(io, response.status, response.text, formatted, secrets, asJson);
+  }
+  io.stdout(redact(formatted, secrets));
+  if (!asJson) {
+    const parsedBody = parseJson(response.text);
+    io.stdout(redact(formatDecisionNotes(parsedBody), secrets));
+    io.stdout(redact(formatNextStepsHints(parsedBody), secrets));
+  }
+  return EXIT.ok;
+}
+function writeHttpError(io, status, rawText, formatted, secrets, asJson) {
+  const classified = classifyHttpError(status, parseJson(rawText));
+  if (asJson) {
+    io.stderr(redact(formatted, secrets));
+  } else {
+    io.stderr(redact(`${classified.message}
+${formatted}`, secrets));
+  }
+  return classified.exitCode;
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+async function runBatch(io, command, flags) {
+  const rawPriority = flagString(flags, "priority");
+  if (!rawPriority) {
+    throw new UsageError(
+      "Before a bulk run, ask which path: speed, balance, accuracy, or coverage. Re-run with --priority speed|balance|accuracy|coverage. Max yield = coverage."
+    );
+  }
+  const priority = parsePriority(rawPriority);
+  const file = flagString(flags, "file");
+  if (!file) {
+    throw new UsageError(
+      "batch requires --file <path|-> (JSONL or a JSON array of request bodies)"
+    );
+  }
+  const loader = {
+    readFile: io.readFile ?? ((path) => readFileSync(path, "utf8")),
+    stdin: io.stdin ?? ""
+  };
+  const raw = file === "-" ? loader.stdin : loader.readFile(file);
+  const rows = parseBatchRows(raw);
+  if (rows.length === 0) {
+    throw new UsageError("batch file is empty");
+  }
+  const token = requireToken(flags, io.env);
+  const baseUrl = resolveBaseUrl(flags, io.env);
+  const secrets = collectSecrets(io, flags);
+  const asJson = flagBool(flags, "json") === true;
+  let worst = EXIT.ok;
+  for (const [index, row] of rows.entries()) {
+    const body = applyPriority(row, priority, command.capability);
+    const request = buildRequest({ name: command.capability }, flags, {
+      ...loader,
+      stdin: JSON.stringify(body)
+    });
+    request.body = body;
+    const response = await apiRequest({
+      fetch: io.fetch,
+      method: request.method,
+      url: `${baseUrl}${request.path}`,
+      token,
+      headers: request.headers,
+      body: request.body
+    });
+    const formatted = formatBody(response.text, response.contentType);
+    if (response.status >= 400) {
+      const prefix = asJson ? "" : `row ${index + 1} `;
+      const code = writeHttpError(
+        io,
+        response.status,
+        response.text,
+        `${prefix}${formatted}`,
+        secrets,
+        asJson
+      );
+      worst = Math.max(worst, code);
+      continue;
+    }
+    if (asJson) {
+      io.stdout(redact(formatted, secrets));
+    } else {
+      io.stdout(redact(`# row ${index + 1}
+${formatted}`, secrets));
+      const parsedBody = parseJson(response.text);
+      io.stdout(redact(formatDecisionNotes(parsedBody), secrets));
+      io.stdout(redact(formatNextStepsHints(parsedBody), secrets));
+    }
+  }
+  return worst;
+}
+function parseBatchRows(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return [];
+  }
+  if (trimmed.startsWith("[")) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) {
+      throw new UsageError("--file JSON array is invalid");
+    }
+    return parsed.map((row, index) => {
+      if (!row || typeof row !== "object" || Array.isArray(row)) {
+        throw new UsageError(`--file row ${index + 1} must be a JSON object`);
+      }
+      return row;
+    });
+  }
+  return trimmed.split(/\r?\n/).flatMap((line, index) => {
+    if (!line.trim()) {
+      return [];
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      throw new UsageError(`--file line ${index + 1} is not valid JSON`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new UsageError(`--file line ${index + 1} must be a JSON object`);
+    }
+    return [parsed];
+  });
+}
+function helpTopic(topic) {
+  switch (topic) {
+    case "resolve":
+      return "company.resolve";
+    case "domain":
+      return "company.domain";
+    case "hierarchy":
+      return "company.hierarchy";
+    case "b2b-social":
+      return "company.b2b_social";
+    case "icon":
+      return "company.icon";
+    case "description":
+      return "company.description";
+    case "verify-employment":
+      return "person.verify_employment";
+    case "language":
+      return "person.language";
+    case "phone":
+      return "person.phone";
+    case "title":
+      return "person.title";
+    case "recipes":
+      return "recipes";
+    case "batch":
+      return "batch";
+    default:
+      return topic;
+  }
+}
+function resolveBaseUrl(flags, env) {
+  const fromFlag = typeof flags["base-url"] === "string" ? flags["base-url"] : void 0;
+  const raw = fromFlag?.trim() || env[BASE_URL_ENV]?.trim() || DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, "");
+}
+function optionalToken(flags, env) {
+  const fromFlag = typeof flags.token === "string" ? flags.token.trim() : "";
+  const fromEnv = env[TOKEN_ENV]?.trim() ?? "";
+  return fromFlag || fromEnv || void 0;
+}
+function requireToken(flags, env) {
+  const token = optionalToken(flags, env);
+  if (!token) {
+    throw new UsageError(`missing tenant Bearer: set ${TOKEN_ENV} or pass --token`);
+  }
+  return token;
+}
+function collectSecrets(io, flags) {
+  const secrets = [];
+  const push = (value) => {
+    const trimmed = value?.trim();
+    if (trimmed) {
+      secrets.push(trimmed);
+    }
+  };
+  push(io.env[TOKEN_ENV]);
+  if (typeof flags?.token === "string") {
+    push(flags.token);
+  }
+  if (typeof flags?.["api-key"] === "string") {
+    push(flags["api-key"]);
+  }
+  if (typeof flags?.["client-secret"] === "string") {
+    push(flags["client-secret"]);
+  }
+  return secrets;
+}
+function redact(text, secrets) {
+  return secrets.reduce((out, secret) => out.split(secret).join("[redacted]"), text);
+}
+function launchedAsCli() {
+  const self = fileURLToPath(import.meta.url);
+  const argv1 = process.argv[1];
+  if (!argv1) {
+    return false;
+  }
+  try {
+    return realpathSync(argv1) === realpathSync(self);
+  } catch {
+    return argv1.endsWith("kingminos.ts") || argv1.endsWith("kingminos.js") || /(^|\/)kingminos$/.test(argv1);
+  }
+}
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+if (launchedAsCli()) {
+  const readBodyStdin = process.argv.includes("--body") && process.argv.includes("-");
+  const stdin = readBodyStdin ? await readStdin() : "";
+  const code = await runCli({
+    argv: process.argv.slice(2),
+    env: process.env,
+    stdout: (text) => {
+      process.stdout.write(text);
+    },
+    stderr: (text) => {
+      process.stderr.write(text);
+    },
+    fetch,
+    stdin
+  });
+  process.exitCode = code;
+}
+export {
+  BASE_URL_ENV,
+  DEFAULT_BASE_URL,
+  EXIT,
+  ROOT_HELP,
+  TOKEN_ENV,
+  assertKnownFlags,
+  buildRequest,
+  classifyHttpError,
+  formatDecisionNotes,
+  parseArgv,
+  resolveCommand,
+  runCli,
+  stripSafeToWrite
+};