@seclai/cli 1.4.0 → 1.6.0

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command as Command4 } from "commander";
 import { realpathSync } from "fs";
 import { fileURLToPath, pathToFileURL } from "url";
 
 // src/helpers.ts
+import { InvalidArgumentError } from "commander";
 import { readFile } from "fs/promises";
 import { readFileSync } from "fs";
 import process2 from "process";
@@ -74,10 +75,27 @@ function getCliVersion() {
 }
 function createClient(opts) {
   const seclaiOpts = {};
+  const identityFlags = [
+    ["apiKey", "--api-key", "Pass a key, or omit the flag to use SECLAI_API_KEY or SSO."],
+    ["profile", "--profile", "Pass a profile name, or omit the flag to use the default profile."],
+    ["accountId", "--account-id", "Pass an account ID, or omit the flag to use the default org."],
+    ["configDir", "--config-dir", "Pass a directory, or omit the flag to use ~/.seclai."]
+  ];
+  for (const [key, flag, hint] of identityFlags) {
+    const value = opts[key];
+    if (typeof value === "string" && value.trim().length === 0) {
+      throw new Error(`${flag} was given an empty value. ${hint}`);
+    }
+  }
   if (opts.apiKey !== void 0) seclaiOpts.apiKey = opts.apiKey;
   if (opts.profile !== void 0) seclaiOpts.profile = opts.profile;
   if (opts.configDir !== void 0) seclaiOpts.configDir = opts.configDir;
   if (opts.accountId !== void 0) seclaiOpts.accountId = opts.accountId;
+  const envVersion = process2.env.SECLAI_API_VERSION;
+  const blank = (v) => v === void 0 || v.trim().length === 0;
+  const version = blank(opts.apiVersion) ? opts.apiVersion !== void 0 ? void 0 : blank(envVersion) ? void 0 : envVersion : opts.apiVersion;
+  if (version !== void 0) seclaiOpts.apiVersion = version;
+  if (opts.allowUnknownApiVersion) seclaiOpts.allowUnknownApiVersion = true;
   const envUrl = process2.env.SECLAI_API_URL;
   seclaiOpts.baseUrl = envUrl && envUrl.length > 0 ? envUrl : "https://api.seclai.com";
   return new Seclai(seclaiOpts);
@@ -87,6 +105,11 @@ function printJson(rt, value) {
   rt.writeOut(`${JSON.stringify(value, null, indent)}
 `);
 }
+function warnDeprecated(rt, message, fate = "rejected") {
+  const suffix = fate === "kept" ? "" : fate === "removed" ? " This will be removed in a future release." : " This will be rejected in a future release.";
+  rt.writeErr(`warning: ${message}${suffix}
+`);
+}
 function printError(rt, err) {
   if (err instanceof SeclaiAPIValidationError) {
     rt.writeErr(`${err.name}: ${err.message}
@@ -114,8 +137,13 @@ function printError(rt, err) {
   if (err instanceof SeclaiConfigurationError) {
     rt.writeErr(`${err.name}: ${err.message}
 `);
-    rt.writeErr(`hint: Set the SECLAI_API_KEY environment variable or pass --api-key.
+    if (/api version/i.test(err.message)) {
+      rt.writeErr(`hint: Pass --allow-unknown-api-version to send it anyway.
+`);
+    } else {
+      rt.writeErr(`hint: Set the SECLAI_API_KEY environment variable or pass --api-key.
 `);
+    }
     return;
   }
   if (err instanceof Error) {
@@ -134,6 +162,37 @@ async function run(rt, main) {
     rt.setExitCode(1);
   }
 }
+function parseNumber(value) {
+  if (!/^\d+$/.test(value.trim())) {
+    throw new InvalidArgumentError("Expected a non-negative whole number.");
+  }
+  return Number(value.trim());
+}
+function withLimitOption(cmd, description = "Page size.") {
+  return cmd.option("--limit <n>", description, parseNumber);
+}
+function withOffsetListOptions(cmd) {
+  return withLimitOption(cmd).option("--offset <n>", "Number of items to skip.", parseNumber);
+}
+function toPagedEnvelope(res, ...legacyKeys) {
+  if (Array.isArray(res)) return { data: res };
+  if (res === null || typeof res !== "object") return res;
+  const obj = res;
+  if (Array.isArray(obj.data)) return obj;
+  for (const key of legacyKeys) {
+    if (Array.isArray(obj[key])) {
+      const { [key]: rows, ...rest } = obj;
+      return { data: rows, ...rest };
+    }
+  }
+  return res;
+}
+function offsetListOpts(opts) {
+  const o = {};
+  if (opts.limit !== void 0) o.limit = opts.limit;
+  if (opts.offset !== void 0) o.offset = opts.offset;
+  return o;
+}
 function withJsonInputOptions(cmd) {
   return cmd.option("--json <json>", "Inline JSON body. Use '-' to read from stdin.").option("--json-file <path>", "Path to JSON file. Use '-' to read from stdin.");
 }
@@ -176,7 +235,7 @@ async function readAiInput(rt, opts) {
 // src/commands/agents.ts
 function register(program, rt) {
   const agents = program.command("agents").description("Manage agents, runs, definitions, export, and AI assistance.");
-  agents.command("list").description("List agents.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (opts) => {
+  agents.command("list").description("List agents.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listAgents(listOpts(opts)));
@@ -209,7 +268,40 @@ function register(program, rt) {
       printJson(rt, { ok: true });
     });
   });
-  agents.command("run").description("Run an agent. Use --stream/--events/--poll for different modes.").argument("<agentId>", "Agent ID.").option("--json <json>", "Inline JSON body. Use '-' for stdin.").option("--json-file <path>", "JSON file path. Use '-' for stdin.").option("--stream", "Stream and print final result when done.").option("--events", "Stream SSE events as newline-delimited JSON.").option("--event-filter <types>", "Comma-separated event types to show (with --events).").option("--output <mode>", "Output mode: 'full' prints entire event, 'data' prints only the data field, 'status' prints a one-line summary.", "full").option("--poll", "Poll until completion instead of streaming.").option("--poll-interval-ms <n>", "Poll interval in ms (with --poll).", (v) => Number(v)).option("--timeout-ms <n>", "Client-side timeout in ms.", (v) => Number(v)).option("--include-step-outputs", "Include step outputs (with --poll).").action(async (agentId, opts) => {
+  agents.command("disable").description("Pause an agent across every trigger path (API, schedule, email, sub-agent calls).").argument("<agentId>", "Agent ID.").action(async (agentId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.disableAgent(agentId));
+    });
+  });
+  agents.command("enable").description("Resume a paused agent.").argument("<agentId>", "Agent ID.").action(async (agentId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.enableAgent(agentId));
+    });
+  });
+  agents.command("callers").description("List the live agents that call this agent via a call_agent step.").argument("<agentId>", "Agent ID.").action(async (agentId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.getAgentCallers(agentId));
+    });
+  });
+  const triggers = agents.command("triggers").description("Agent trigger configuration.");
+  triggers.command("email-config").description("Set the alias, sender allowlist, and inbound-handling flags on an EMAIL_RECEIVED trigger.").argument("<agentId>", "Agent ID.").argument("<triggerId>", "Trigger ID.").option("--json <json>", "Config body JSON. Use '-' for stdin.").option("--json-file <path>", "Config body JSON file. Use '-' for stdin.").action(async (agentId, triggerId, opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const body = await readJsonInput(rt, { json: opts.json, jsonFile: opts.jsonFile });
+      printJson(
+        rt,
+        await client.setEmailTriggerConfig(
+          agentId,
+          triggerId,
+          body
+        )
+      );
+    });
+  });
+  agents.command("run").description("Run an agent. Use --stream/--events/--poll for different modes.").argument("<agentId>", "Agent ID.").option("--json <json>", "Inline JSON body. Use '-' for stdin.").option("--json-file <path>", "JSON file path. Use '-' for stdin.").option("--stream", "Stream and print final result when done.").option("--events", "Stream SSE events as newline-delimited JSON.").option("--event-filter <types>", "Comma-separated event types to show (with --events).").option("--output <mode>", "Output mode: 'full' prints entire event, 'data' prints only the data field, 'status' prints a one-line summary.", "full").option("--poll", "Poll until completion instead of streaming.").option("--poll-interval-ms <n>", "Poll interval in ms (with --poll).", parseNumber).option("--timeout-ms <n>", "Client-side timeout in ms.", parseNumber).option("--include-step-outputs", "Include step outputs (with --poll).").action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const body = await readJsonInput(rt, { json: opts.json, jsonFile: opts.jsonFile });
@@ -257,7 +349,7 @@ function register(program, rt) {
     });
   });
   const runs = agents.command("runs").description("Manage agent runs.");
-  runs.command("list").description("List runs for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--status <status>", "Filter by run status (e.g. queued, running, completed, failed, cancelled).").action(async (agentId, opts) => {
+  runs.command("list").description("List runs for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--status <status>", "Filter by run status (e.g. queued, running, completed, failed, cancelled).").action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const o = listOpts(opts);
@@ -274,10 +366,17 @@ function register(program, rt) {
       );
     });
   });
-  runs.command("delete").description("Delete a run.").argument("<runId>", "Run ID.").action(async (runId) => {
+  runs.command("delete").description("Deprecated alias for 'runs cancel'. The API has no delete-a-run operation.").argument("<runId>", "Run ID.").action(async (runId) => {
     await run(rt, async () => {
+      warnDeprecated(
+        rt,
+        `'agents runs delete' is deprecated and cancels the run rather than deleting it \u2014 the API has no delete-a-run operation. Use 'agents runs cancel', which also prints the cancelled run instead of {"ok": true}.`,
+        // Kept, not scheduled for removal — the whole point of the alias is
+        // that existing scripts keep working.
+        "kept"
+      );
       const client = createClient(program.opts());
-      await client.deleteAgentRun(runId);
+      await client.cancelAgentRun(runId);
       printJson(rt, { ok: true });
     });
   });
@@ -398,10 +497,20 @@ function register(program, rt) {
       printJson(rt, await client.generateStepConfig(agentId, body));
     });
   });
-  ai.command("history").description("Get agent AI conversation history.").argument("<agentId>", "Agent ID.").action(async (agentId) => {
+  withOffsetListOptions(
+    ai.command("history").description("Get agent AI conversation history for one step type.").argument("<agentId>", "Agent ID.").requiredOption(
+      "--step-type <type>",
+      "Step type to read history for (e.g. llm). Required by the API."
+    ).option("--step-id <id>", "Restrict to a single step.")
+  ).action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      printJson(rt, await client.getAgentAiConversationHistory(agentId));
+      const o = {
+        ...offsetListOpts(opts),
+        stepType: opts.stepType
+      };
+      if (opts.stepId !== void 0) o.stepId = opts.stepId;
+      printJson(rt, await client.getAgentAiConversationHistory(agentId, o));
     });
   });
   ai.command("mark").description("Mark an AI suggestion (accept/reject).").argument("<agentId>", "Agent ID.").argument("<conversationId>", "Conversation ID.").option("--json <json>", "Mark body JSON.").option("--json-file <path>", "Mark body JSON file.").action(async (agentId, conversationId, opts) => {
@@ -412,10 +521,14 @@ function register(program, rt) {
       printJson(rt, { ok: true });
     });
   });
-  runs.command("eval-results").description("List evaluation results for a run.").argument("<agentId>", "Agent ID.").argument("<runId>", "Run ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (agentId, runId, opts) => {
+  runs.command("eval-results").description("List evaluation results for a run.").argument("<agentId>", "Agent ID.").argument("<runId>", "Run ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option(
+    "--paged",
+    "Wrap the results in {data: [...]}, the shape this endpoint moves to from --api-version 2026-07-27."
+  ).action(async (agentId, runId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      printJson(rt, await client.listRunEvaluationResults(agentId, runId, listOpts(opts)));
+      const res = await client.listRunEvaluationResults(agentId, runId, listOpts(opts));
+      printJson(rt, opts.paged ? toPagedEnvelope(res) : res);
     });
   });
 }
@@ -423,7 +536,7 @@ function register(program, rt) {
 // src/commands/sources.ts
 function register2(program, rt) {
   const sources = program.command("sources").alias("source").description("Manage content sources.");
-  sources.command("list").description("List sources.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").option("--account-id <id>", "Filter by account ID.").action(async (opts) => {
+  sources.command("list").description("List sources.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").option("--account-id <id>", "Filter by account ID.").action(async (opts) => {
     await run(rt, async () => {
       const globalOpts = program.opts();
       const client = createClient(globalOpts);
@@ -476,7 +589,7 @@ function register2(program, rt) {
     });
   });
   const exports_ = sources.command("exports").description("Manage source exports.");
-  exports_.command("list").description("List exports for a source.").argument("<sourceId>", "Source ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (sourceId, opts) => {
+  exports_.command("list").description("List exports for a source.").argument("<sourceId>", "Source ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (sourceId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listSourceExports(sourceId, listOpts(opts)));
@@ -547,7 +660,7 @@ function register2(program, rt) {
 // src/commands/contents.ts
 function register3(program, rt) {
   const contents = program.command("contents").description("Manage indexed content and embeddings.");
-  contents.command("get").description("Get content version details.").argument("<contentVersionId>", "Content version ID.").option("--start <n>", "Text start offset (0-based).", (v) => Number(v)).option("--end <n>", "Text end offset (exclusive).", (v) => Number(v)).action(async (contentVersionId, opts) => {
+  contents.command("get").description("Get content version details.").argument("<contentVersionId>", "Content version ID.").option("--start <n>", "Text start offset (0-based).", parseNumber).option("--end <n>", "Text end offset (exclusive).", parseNumber).action(async (contentVersionId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const o = {};
@@ -578,7 +691,7 @@ function register3(program, rt) {
       printJson(rt, await client.replaceContentWithInlineText(contentVersionId, body));
     });
   });
-  contents.command("embeddings").description("List embeddings for a content version.").argument("<contentVersionId>", "Content version ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (contentVersionId, opts) => {
+  contents.command("embeddings").description("List embeddings for a content version.").argument("<contentVersionId>", "Content version ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (contentVersionId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listContentEmbeddings(contentVersionId, listOpts(opts)));
@@ -589,7 +702,7 @@ function register3(program, rt) {
 // src/commands/kb.ts
 function register4(program, rt) {
   const kb = program.command("kb").description("Manage knowledge bases.");
-  kb.command("list").description("List knowledge bases.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
+  kb.command("list").description("List knowledge bases.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listKnowledgeBases(listOpts(opts)));
@@ -627,7 +740,7 @@ function register4(program, rt) {
 // src/commands/memory.ts
 function register5(program, rt) {
   const memory = program.command("memory").description("Manage memory banks.");
-  memory.command("list").description("List memory banks.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
+  memory.command("list").description("List memory banks.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listMemoryBanks(listOpts(opts)));
@@ -735,10 +848,16 @@ function register5(program, rt) {
 function register6(program, rt) {
   const evals = program.command("evals").description("Manage evaluations.");
   const criteria = evals.command("criteria").description("Evaluation criteria.");
-  criteria.command("list").description("List evaluation criteria for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (agentId, opts) => {
+  criteria.command("list").description("List evaluation criteria for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option(
+    "--paged",
+    "Wrap the results in {data: [...]} instead of returning a bare array. The pagination block is included once the API sends one, from --api-version 2026-07-27."
+  ).action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      printJson(rt, await client.listEvaluationCriteria(agentId, listOpts(opts)));
+      printJson(
+        rt,
+        opts.paged ? await client.listEvaluationCriteriaPage(agentId, listOpts(opts)) : await client.listEvaluationCriteria(agentId, listOpts(opts))
+      );
     });
   });
   criteria.command("create").description("Create evaluation criteria.").argument("<agentId>", "Agent ID.").option("--json <json>", "Criteria body JSON.").option("--json-file <path>", "Criteria body JSON file.").action(async (agentId, opts) => {
@@ -775,7 +894,7 @@ function register6(program, rt) {
     });
   });
   const results = evals.command("results").description("Evaluation results.");
-  results.command("list").description("List results for criteria.").argument("<criteriaId>", "Criteria ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (criteriaId, opts) => {
+  results.command("list").description("List results for criteria.").argument("<criteriaId>", "Criteria ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (criteriaId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listEvaluationResults(criteriaId, listOpts(opts)));
@@ -788,7 +907,7 @@ function register6(program, rt) {
       printJson(rt, await client.createEvaluationResult(criteriaId, body));
     });
   });
-  evals.command("compatible-runs").description("List runs compatible with criteria.").argument("<criteriaId>", "Criteria ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (criteriaId, opts) => {
+  evals.command("compatible-runs").description("List runs compatible with criteria.").argument("<criteriaId>", "Criteria ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (criteriaId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listCompatibleRuns(criteriaId, listOpts(opts)));
@@ -801,13 +920,13 @@ function register6(program, rt) {
       printJson(rt, await client.testDraftEvaluation(agentId, body));
     });
   });
-  evals.command("agent-results").description("List all evaluation results for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (agentId, opts) => {
+  evals.command("agent-results").description("List all evaluation results for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listAgentEvaluationResults(agentId, listOpts(opts)));
     });
   });
-  evals.command("agent-runs").description("List evaluation run summaries for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (agentId, opts) => {
+  evals.command("agent-runs").description("List evaluation run summaries for an agent.").argument("<agentId>", "Agent ID.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).action(async (agentId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listEvaluationRuns(agentId, listOpts(opts)));
@@ -824,7 +943,7 @@ function register6(program, rt) {
 // src/commands/solutions.ts
 function register7(program, rt) {
   const solutions = program.command("solutions").description("Manage solutions.");
-  solutions.command("list").description("List solutions.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
+  solutions.command("list").description("List solutions.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--sort <field>", "Sort field.").option("--order <asc|desc>", "Sort direction.").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listSolutions(listOpts(opts)));
@@ -1002,12 +1121,11 @@ function register8(program, rt) {
 // src/commands/alerts.ts
 function register9(program, rt) {
   const alerts = program.command("alerts").description("Manage alerts and alert configurations.");
-  alerts.command("list").description("List alerts.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).option("--status <status>", "Filter by status.").option("--severity <severity>", "Filter by severity.").action(async (opts) => {
+  alerts.command("list").description("List alerts.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option("--status <status>", "Filter by status.").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const o = listOpts(opts);
       if (opts.status) o.status = opts.status;
-      if (opts.severity) o.severity = opts.severity;
       printJson(rt, await client.listAlerts(o));
     });
   });
@@ -1044,10 +1162,14 @@ function register9(program, rt) {
     });
   });
   const configs = alerts.command("configs").description("Alert configurations.");
-  configs.command("list").description("List alert configurations.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (opts) => {
+  configs.command("list").description("List alert configurations.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option(
+    "--paged",
+    "Wrap the results in {data: [...]}, the shape this endpoint moves to from --api-version 2026-07-27."
+  ).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      printJson(rt, await client.listAlertConfigs(listOpts(opts)));
+      const res = await client.listAlertConfigs(listOpts(opts));
+      printJson(rt, opts.paged ? toPagedEnvelope(res, "configs") : res);
     });
   });
   configs.command("create").description("Create an alert configuration.").option("--json <json>", "Config body JSON.").option("--json-file <path>", "Config body JSON file.").action(async (opts) => {
@@ -1093,19 +1215,220 @@ function register9(program, rt) {
   });
 }
 
-// src/commands/models.ts
+// src/commands/email.ts
+import { Argument, Option } from "commander";
 function register10(program, rt) {
+  const email = program.command("email").description("Agent email: sending domains, inbound blocklist, inbound health, and opt-outs.");
+  const domains = email.command("domains").description("Agent-email sending domains.");
+  domains.command("list").description("List the account's email domains and the plan limits for adding more.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.listEmailDomains());
+    });
+  });
+  domains.command("add").description("Add and provision a new agent-email domain. Returns the DNS records to publish.").addOption(
+    new Option("--kind <kind>", "'vanity' (a subdomain of seclai.com) or 'custom' (your own domain).").choices(["vanity", "custom"]).makeOptionMandatory()
+  ).requiredOption("--value <domain>", "The domain to add.").option("--delegated", "The domain's DNS is delegated to Seclai, so records are published automatically.").action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const body = {
+        kind: opts.kind,
+        value: opts.value
+      };
+      if (opts.delegated) body.delegated = true;
+      printJson(rt, await client.addEmailDomain(body));
+    });
+  });
+  domains.command("remove").description("Remove a domain and tear down its sending identity and inbound routing.").argument("<domainId>", "Domain ID.").action(async (domainId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.removeEmailDomain(domainId));
+    });
+  });
+  domains.command("verify").description("Run a verification check on a domain immediately.").argument("<domainId>", "Domain ID.").action(async (domainId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.verifyEmailDomain(domainId));
+    });
+  });
+  domains.command("set-primary").description("Promote a verified domain to the account's primary sending domain.").argument("<domainId>", "Domain ID.").action(async (domainId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.setPrimaryEmailDomain(domainId));
+    });
+  });
+  domains.command("use-shared").description("Revert to the shared agent.seclai.com sending and inbound domain.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      await client.useSharedEmailDomain();
+      printJson(rt, { ok: true });
+    });
+  });
+  domains.command("test-email").description("Send a test message from a verified domain to the account owner.").argument("<domainId>", "Domain ID.").action(async (domainId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.sendEmailDomainTestEmail(domainId));
+    });
+  });
+  domains.command("dmarc").description("Get the DMARC aggregate-report summary for a domain.").argument("<domainId>", "Domain ID.").option("--days <n>", "Reporting window in days.", parseNumber).option("--top-sources <n>", "How many sending sources to include.", parseNumber).action(async (domainId, opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const o = {};
+      if (opts.days !== void 0) o.days = opts.days;
+      if (opts.topSources !== void 0) o.topSources = opts.topSources;
+      printJson(rt, await client.getDmarcSummary(domainId, o));
+    });
+  });
+  const blocked = email.command("blocked").description("Inbound email sender blocklist.");
+  withOffsetListOptions(
+    blocked.command("list").description("List blocked inbound senders (newest first) and the account's auto-block mode.")
+  ).action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.listBlockedEmailSenders(offsetListOpts(opts)));
+    });
+  });
+  blocked.command("add").description("Block an inbound sender address or domain.").requiredOption("--sender-email <email>", "Sender address, or the domain when --match-type is 'domain'.").addOption(
+    new Option("--match-type <type>", "'address' or 'domain'.").choices(["address", "domain"]).default("address")
+  ).option("--note <text>", "Why the sender was blocked.").action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const body = {
+        sender_email: opts.senderEmail,
+        match_type: opts.matchType
+      };
+      if (opts.note !== void 0) body.note = opts.note;
+      printJson(rt, await client.blockEmailSender(body));
+    });
+  });
+  blocked.command("remove").description("Unblock a sender.").argument("<blockedId>", "Blocklist entry ID.").action(async (blockedId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      await client.unblockEmailSender(blockedId);
+      printJson(rt, { ok: true });
+    });
+  });
+  blocked.command("auto-block-mode").description("Set whether a governance BLOCK on an authenticated sender auto-adds them to the blocklist.").addArgument(
+    // A closed set the API will only ever 422 on. Failing the parse names the
+    // accepted values; the server names nothing.
+    new Argument("<mode>", "How governance BLOCK verdicts feed the blocklist.").choices([
+      "disabled",
+      "input",
+      "input_and_output"
+    ])
+  ).action(async (mode) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.setAutoBlockMode({ mode }));
+    });
+  });
+  const inbound = email.command("inbound").description("Inbound email health and queue control.");
+  inbound.command("status").description("Get inbound-email quota usage, pause state, and queued-run counts.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.getInboundEmailStatus());
+    });
+  });
+  inbound.command("rejections").description("List recently rejected inbound emails and why they were rejected.").option("--agent-id <id>", "Restrict to one agent.").option("--limit <n>", "Maximum rejections to return.", parseNumber).action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const o = {};
+      if (opts.agentId !== void 0) o.agentId = opts.agentId;
+      if (opts.limit !== void 0) o.limit = opts.limit;
+      printJson(rt, await client.listInboundEmailRejections(o));
+    });
+  });
+  inbound.command("cancel-queued").description("Fail all of the account's queued (over-quota) inbound-email runs at once.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.cancelQueuedEmailRuns());
+    });
+  });
+  inbound.command("resume").description("Manually lift the account-wide inbound-email pause.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.resumeInboundEmail());
+    });
+  });
+  const optouts = email.command("optouts").description("Recipients who opted out of agent email.");
+  withOffsetListOptions(
+    optouts.command("list").description("List agent-email opt-outs.").option("--agent-id <id>", "Restrict to one agent.")
+  ).action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const o = offsetListOpts(opts);
+      if (opts.agentId !== void 0) o.agentId = opts.agentId;
+      printJson(rt, await client.listAgentEmailOptOuts(o));
+    });
+  });
+  optouts.command("remove").description("Remove an opt-out so the recipient can receive agent email again.").argument("<optoutId>", "Opt-out ID.").action(async (optoutId) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      await client.removeAgentEmailOptOut(optoutId);
+      printJson(rt, { ok: true });
+    });
+  });
+}
+
+// src/commands/account.ts
+import { SeclaiApiVersion } from "@seclai/sdk";
+function register11(program, rt) {
+  program.command("me").description("Show the authenticated user's account ID and organization memberships.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.getMe());
+    });
+  });
+  const version = program.command("api-version").description("Read or pin the account's dated API version.");
+  version.command("get").description(
+    "Show the version a request resolves to. Reflects --api-version when passed, otherwise the account pin, otherwise the default."
+  ).action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.getApiVersion());
+    });
+  });
+  version.command("set").description("Pin the account to a dated API version. Affects every client, not just this CLI.").argument("<date>", "API version as YYYY-MM-DD.").action(async (date) => {
+    await run(rt, async () => {
+      const known = Object.values(SeclaiApiVersion);
+      if (!known.includes(date) && !program.opts().allowUnknownApiVersion) {
+        throw new Error(
+          `Unknown API version "${date}". This release knows ${[...new Set(known)].sort().join(", ")}. Pass --allow-unknown-api-version to pin it anyway.`
+        );
+      }
+      const client = createClient(program.opts());
+      printJson(rt, await client.updateApiVersion(date));
+    });
+  });
+  version.command("clear").description("Remove the account's version pin, reverting to the default version.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.updateApiVersion(null));
+    });
+  });
+}
+
+// src/commands/models.ts
+function register12(program, rt) {
   const models = program.command("models").description("Models, model alerts, recommendations, and playground experiments.");
-  models.command("list").description("List models grouped by provider.").option("--provider <provider>", "Filter by provider name.").option("--supports-tool-use", "Only models that support tool use.").option("--supports-thinking", "Only models that support thinking.").action(async (opts) => {
+  models.command("list").description("List models grouped by provider.").option("--provider <provider>", "Filter by provider name.").option("--supports-tool-use", "Only models that support tool use.").option("--supports-thinking", "Only models that support thinking.").option("--supports-input-media <media>", "Only models accepting this input modality (e.g. image, audio).").option("--supports-output-media <media>", "Only models producing this output modality (e.g. image, video).").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const o = {};
       if (opts.provider !== void 0) o.provider = opts.provider;
       if (opts.supportsToolUse !== void 0) o.supportsToolUse = opts.supportsToolUse;
       if (opts.supportsThinking !== void 0) o.supportsThinking = opts.supportsThinking;
+      if (opts.supportsInputMedia !== void 0) o.supportsInputMedia = opts.supportsInputMedia;
+      if (opts.supportsOutputMedia !== void 0) o.supportsOutputMedia = opts.supportsOutputMedia;
       printJson(rt, await client.listModels(o));
     });
   });
+  models.command("tiers").description("Show each media-generation modality and tier with its model and cost.").action(async () => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      printJson(rt, await client.getGenerationTiers());
+    });
+  });
   models.command("get").description("Get full details for a specific model.").argument("<modelId>", "Model ID.").action(async (modelId) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
@@ -1113,10 +1436,14 @@ function register10(program, rt) {
     });
   });
   const alerts = models.command("alerts").description("Model alerts.");
-  alerts.command("list").description("List model alerts.").option("--page <n>", "Page number.", (v) => Number(v)).option("--limit <n>", "Page size.", (v) => Number(v)).action(async (opts) => {
+  alerts.command("list").description("List model alerts.").option("--page <n>", "Page number.", parseNumber).option("--limit <n>", "Page size.", parseNumber).option(
+    "--paged",
+    "Wrap the results in {data: [...]}, the shape this endpoint moves to from --api-version 2026-07-27."
+  ).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      printJson(rt, await client.listModelAlerts(listOpts(opts)));
+      const res = await client.listModelAlerts(listOpts(opts));
+      printJson(rt, opts.paged ? toPagedEnvelope(res, "alerts") : res);
     });
   });
   alerts.command("mark-read").description("Mark a model alert as read.").argument("<alertId>", "Alert ID.").action(async (alertId) => {
@@ -1146,15 +1473,15 @@ function register10(program, rt) {
     });
   });
   const experiments = models.command("experiments").description("Model playground experiments.");
-  experiments.command("list").description("List model playground experiments.").option("--days <n>", "Filter to last N days.", (v) => Number(v)).option("--start-date <date>", "Start date (ISO 8601).").option("--end-date <date>", "End date (ISO 8601).").option("--limit <n>", "Page size.", (v) => Number(v)).option("--offset <n>", "Offset.", (v) => Number(v)).action(async (opts) => {
+  withOffsetListOptions(
+    experiments.command("list").description("List model playground experiments.").option("--days <n>", "Filter to last N days.", parseNumber).option("--start-date <date>", "Start date (ISO 8601).").option("--end-date <date>", "End date (ISO 8601).")
+  ).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
-      const o = {};
+      const o = offsetListOpts(opts);
       if (opts.days !== void 0) o.days = opts.days;
       if (opts.startDate !== void 0) o.startDate = opts.startDate;
       if (opts.endDate !== void 0) o.endDate = opts.endDate;
-      if (opts.limit !== void 0) o.limit = opts.limit;
-      if (opts.offset !== void 0) o.offset = opts.offset;
       printJson(rt, await client.listExperiments(o));
     });
   });
@@ -1187,20 +1514,31 @@ function register10(program, rt) {
 }
 
 // src/commands/search.ts
-function register11(program, rt) {
-  program.command("search").description("Search across Seclai resources.").requiredOption("--query <text>", "Search query text.").option("--limit <n>", "Max results.", (v) => Number(v)).option("--entity-type <type>", "Filter by entity type (e.g. agent, source, knowledge_base, memory_bank).").action(async (opts) => {
+import { Option as Option2 } from "commander";
+function register13(program, rt) {
+  program.command("search").description("Search across Seclai resources.").requiredOption("--query <text>", "Search query text.").option("--limit <n>", "Max results.", parseNumber).option("--entity-type <type>", "Filter by entity type (e.g. agent, source, knowledge_base, memory_bank).").action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       const o = { query: opts.query };
       if (opts.limit !== void 0) o.limit = opts.limit;
-      if (opts.entityType) o.entityType = opts.entityType;
+      if (opts.entityType !== void 0) o.entityType = opts.entityType;
       printJson(rt, await client.search(o));
     });
   });
+  const docs = program.command("docs").description("Seclai documentation.");
+  docs.command("search").description("Search the Seclai documentation.").requiredOption("--query <text>", "Search query text.").addOption(new Option2("--mode <mode>", "Search mode.").choices(["keyword", "semantic"])).option("--limit <n>", "Max results.", parseNumber).action(async (opts) => {
+    await run(rt, async () => {
+      const client = createClient(program.opts());
+      const o = { query: opts.query };
+      if (opts.mode !== void 0) o.mode = opts.mode;
+      if (opts.limit !== void 0) o.limit = opts.limit;
+      printJson(rt, await client.searchDocs(o));
+    });
+  });
 }
 
 // src/commands/ai.ts
-function register12(program, rt) {
+function register14(program, rt) {
   const ai = program.command("ai").description("Top-level AI assistant.");
   ai.command("feedback").description("Submit AI feedback.").option("--json <json>", "Feedback body JSON.").option("--json-file <path>", "Feedback body JSON file.").action(async (opts) => {
     await run(rt, async () => {
@@ -1278,73 +1616,138 @@ function register12(program, rt) {
 import { existsSync, statSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { dirname, join } from "path";
-var SKILL_MD = `---
+var SKILL_FILES = [
+  { name: "SKILL.md", content: `---
 name: seclai-cli
 description: >-
   Manage Seclai agents, knowledge bases, sources, memory banks, evaluations,
-  solutions, governance, alerts, and more via the CLI. Use when working with
-  the Seclai platform or when the user mentions Seclai CLI commands.
+  solutions, governance, alerts, agent email, and models via the CLI. Use when
+  working with the Seclai platform or when the user mentions Seclai CLI commands.
 ---
 
 # Seclai CLI
 
-The Seclai CLI (\`seclai\` / \`npx @seclai/cli\`) manages agents, knowledge bases, sources, memory banks, evaluations, solutions, governance, alerts, and more from the terminal.
+The Seclai CLI (\`seclai\` / \`npx @seclai/cli\`) manages agents, knowledge bases,
+sources, memory banks, evaluations, solutions, governance, alerts, agent email,
+and models from the terminal.
 
-All commands output JSON to stdout. Pipe into \`jq\` for filtering.
+Every command writes JSON to stdout. Pipe into \`jq\` for filtering. Errors go to
+stderr and set a non-zero exit code, so \`set -e\` scripts fail as expected.
+
+**Find the commands for a task in the map below, then read that reference file.**
+Only this page is loaded up front; the references are read on demand.
 
 ## Quick start
 
 \`\`\`bash
-# authenticate
 export SECLAI_API_KEY="sk-..."
 
-# create an agent
 seclai agents create --json '{"name":"My Agent","description":"QA chatbot"}'
-
-# configure steps via AI assistant
 seclai agents ai gen-steps <agentId> --user-input "Build a QA chatbot that uses a knowledge base"
-
-# accept the generated plan
 seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
-
-# run the agent
 seclai agents run <agentId> --json '{"input":"How do I reset my password?"}' --stream
-
-# list runs
 seclai agents runs list <agentId>
 \`\`\`
 
+## Command map
+
+| Group | What it covers | Reference |
+| --- | --- | --- |
+| \`agents\` | Agents, runs, definitions, export/import, input uploads, triggers, agent AI | [references/agents.md](references/agents.md) |
+| \`sources\` \`contents\` \`kb\` \`memory\` | Sources and uploads, exports, embedding migration, indexed content, knowledge bases, memory banks | [references/knowledge.md](references/knowledge.md) |
+| \`evals\` | Evaluation criteria, results, runs, agent-level summaries | [references/evaluations.md](references/evaluations.md) |
+| \`solutions\` \`governance\` | Solutions, resource links, conversations, solution and governance AI | [references/solutions.md](references/solutions.md) |
+| \`alerts\` | Alerts, alert configurations, organization preferences | [references/alerts.md](references/alerts.md) |
+| \`email\` | Agent email: sending domains, inbound blocklist, inbound health, opt-outs | [references/email.md](references/email.md) |
+| \`models\` | Model catalog, generation tiers, model alerts, recommendations, playground experiments | [references/models.md](references/models.md) |
+| \`auth\` \`configure\` \`api-version\` \`mcp\` \`skills\` \`completion\` | Authentication, profiles, API version pinning, editor integration | [references/setup.md](references/setup.md) |
+| \`ai\` | Top-level AI assistant for knowledge bases, sources, solutions and memory | [references/ai-assistant.md](references/ai-assistant.md) |
+| \`search\` \`docs\` \`me\` | Search across resources, search the documentation, show the authenticated account | below, under [Search and account](#search-and-account) |
+
+Cross-cutting topics: [streaming and event modes](references/streaming.md),
+[file uploads](references/uploads.md).
+
 ## Authentication
 
-Set \`SECLAI_API_KEY\` env var or pass \`--api-key <key>\`.
-Override the API URL with \`SECLAI_API_URL\` (default: https://api.seclai.com).
+Two modes:
+
+1. **API key** \u2014 set \`SECLAI_API_KEY\`, or pass \`--api-key <key>\`.
+2. **SSO** \u2014 \`seclai auth login\` for browser-based OAuth2/PKCE. Tokens are cached
+   locally and refreshed automatically.
+
+Override the API host with \`SECLAI_API_URL\` (default \`https://api.seclai.com\`).
 
 ## Global options
 
 \`\`\`bash
---api-key <key>    # Seclai API key (or set SECLAI_API_KEY)
---compact          # Output compact single-line JSON
--V, --version      # Print version
+--api-key <key>              # or set SECLAI_API_KEY
+--profile <name>             # SSO profile (or SECLAI_PROFILE, default 'default')
+--account-id <id>            # multi-org targeting (X-Account-Id header)
+--config-dir <path>          # or SECLAI_CONFIG_DIR, default ~/.seclai
+--api-version <date>         # or SECLAI_API_VERSION; see below
+--allow-unknown-api-version  # send a version this CLI was not built against
+--compact                    # single-line JSON
+-V, --version
+\`\`\`
+
+## API versions
+
+The API is versioned by date, and a version can change a response's shape \u2014 a
+bare array becoming \`{data, pagination}\`, for instance. **The CLI sends no
+version header by default**, so upgrading it never changes what a command
+prints. Opt in per invocation, or pin the account:
+
+\`\`\`bash
+seclai api-version get                        # what does a request resolve to?
+seclai --api-version 2026-07-27 alerts list   # this invocation only
+seclai api-version set 2026-07-27             # every client on the account
+seclai api-version clear
 \`\`\`
 
+An \`--api-version\` this CLI was not built against is rejected, because a newer
+version can reshape a response the CLI would then misread. Pass
+\`--allow-unknown-api-version\` to send it anyway. \`api-version set\` takes a
+\`YYYY-MM-DD\` date and rejects anything else, because the pin applies to every
+client on the account.
+
+\`--api-key\`, \`--profile\`, \`--account-id\` and \`--config-dir\` reject an empty
+value. A shell expanding an unset variable passes \`""\`, which the SDK's
+credential chain discards, so each would silently resolve elsewhere \u2014 a
+different identity, another account's cached tokens, or the default org. Guard
+the flag rather than the value: \`seclai \${KEY:+--api-key "$KEY"} agents list\`.
+
+An empty \`--api-version\` is accepted with a warning, since it costs only the
+version header; a future release will reject it too.
+
 ## Common patterns
 
-### JSON input
-Most create/update commands accept \`--json '{"key":"value"}'\` or \`--json-file path.json\`.
-Use \`--json -\` or \`--json-file -\` to read from stdin.
+**JSON input.** Most create/update commands take \`--json '{"key":"value"}'\` or
+\`--json-file path.json\`. Use \`-\` as the value to read from stdin.
+
+**AI shorthand.** AI generation commands accept \`--user-input <text>\` in place of
+\`--json '{"user_input":"<text>"}'\`.
+
+**Pagination.** List commands take \`--page <n>\` and \`--limit <n>\`; some add
+\`--sort <field>\` and \`--order asc|desc\`. A few endpoints paginate by offset
+instead and take \`--limit\` / \`--offset\`.
 
-### AI assistant shorthand
-AI generation commands accept \`--user-input <text>\` as shorthand for \`--json '{"user_input":"<text>"}'\`.
+**Uploads.** Upload commands take \`--file <path>\`, plus optional \`--title\`,
+\`--metadata '{"k":"v"}'\`, \`--metadata-file\`, \`--file-name\` and \`--mime-type\`.
 
-### Pagination
-List commands support \`--page <n>\` and \`--limit <n>\`. Some also support \`--sort <field>\` and \`--order asc|desc\`.
+## Search and account
 
-### File uploads
-Upload commands accept \`--file <path>\` (required), plus optional \`--title\`, \`--metadata '{"k":"v"}'\`, \`--metadata-file path.json\`, \`--file-name\`, \`--mime-type\`.
+\`\`\`bash
+seclai search --query "deployment guide" [--limit N] [--entity-type <type>]
+seclai docs search --query "memory banks" [--mode keyword|semantic] [--limit N]
+seclai me   # account ID and organization memberships
+\`\`\`
+` },
+  { name: "references/agents.md", content: `# Agents
 
-## Commands
+Agents, their runs, definitions, export/import, input uploads, triggers, and the
+agent AI assistant.
 
-### Agents
+## CRUD and lifecycle
 
 \`\`\`bash
 seclai agents list [--page N] [--limit N]
@@ -1352,100 +1755,382 @@ seclai agents create --json '{"name":"My Agent","description":"..."}'
 seclai agents get <agentId>
 seclai agents update <agentId> --json '{"name":"Renamed"}'
 seclai agents delete <agentId>
+
+# pause across every trigger path (API, schedule, email, sub-agent calls)
+seclai agents disable <agentId>
+seclai agents enable <agentId>
+
+# which live agents call this one via a call_agent step?
+seclai agents callers <agentId>
+\`\`\`
+
+## Triggers
+
+\`\`\`bash
+# alias, sender allowlist and inbound-handling flags for an EMAIL_RECEIVED trigger
+seclai agents triggers email-config <agentId> <triggerId> --json '{"alias":"support"}'
 \`\`\`
 
-### Running agents
+## Running agents
+
+Four modes: basic, streaming, NDJSON events, and polling. See
+[streaming.md](streaming.md) for event shapes and filtering.
 
 \`\`\`bash
 # simple run \u2014 returns the final result
 seclai agents run <agentId> --json '{"input":"Hello"}'
 
-# stream \u2014 wait for completion via SSE, print final result
+# stream \u2014 wait for completion via SSE, print the final result
 seclai agents run <agentId> --json '{"input":"Hello"}' --stream [--timeout-ms 60000]
 
-# events \u2014 stream individual SSE events as NDJSON lines
-# --output: full (entire event), data (event data only), status (status events only)
-# --event-filter: comma-separated event types to include, e.g. "status,data"
+# events \u2014 every SSE event as an NDJSON line
+# --output: full (entire event), data (event data only), status (one-line summary)
+# --event-filter: comma-separated event types, e.g. "status,data"
 seclai agents run <agentId> --json '{"input":"Hello"}' --events [--output full|data|status] [--event-filter "status,data"]
 
-# poll \u2014 poll for completion
+# poll \u2014 submit, then poll until complete
 seclai agents run <agentId> --json '{"input":"Hello"}' --poll [--poll-interval-ms 2000] [--include-step-outputs]
 \`\`\`
 
-### Agent runs
+## Runs
 
 \`\`\`bash
 seclai agents runs list <agentId> [--page N] [--limit N] [--status <status>]
 seclai agents runs get <runId> [--include-step-outputs]
-seclai agents runs delete <runId>
 seclai agents runs cancel <runId>
+seclai agents runs delete <runId>  # deprecated alias for \`runs cancel\`; the API has no delete-a-run operation
 seclai agents runs search --json '{"query":"..."}'
 seclai agents runs eval-results <agentId> <runId> [--page N] [--limit N]
+
+# Download a file emitted by a run step. attachmentId is the URL-safe-base64
+# storage_key from run output manifests or webhooks.
+seclai agents runs download-attachment <runId> <attachmentId> [--download-name <name>] [--output <path>]
 \`\`\`
 
-### Agent definitions
+Without \`--output\`, raw bytes go to stdout \u2014 redirect to a file rather than
+letting them hit the terminal.
+
+## Definitions
 
 \`\`\`bash
 seclai agents def get <agentId>
-seclai agents def update <agentId> --json '{"steps":[{"step_type":"llm","config":{...}}]}'
+seclai agents def update <agentId> --json '{"steps":[{"step_type":"llm","config":{}}]}'
 \`\`\`
 
-### Agent input uploads
+## Export and import
 
 \`\`\`bash
+# portable JSON snapshot of an agent definition
+seclai agents export <agentId> [--no-download]
+
+# Validate an agent_definition payload before importing \u2014 no writes.
+# Reports counts and any unresolved_refs (knowledge bases, memory banks, source
+# connections or sub-agents that do not exist in this account).
+seclai agents export <agentId> \\
+  | jq '{agent_definition: .}' \\
+  | seclai agents preview-import --json-file -
+
+# Import via \`agents create\` (or \`agents update\`) with agent_definition set to
+# the export payload, and entity_remap mapping unresolved source UUIDs to target
+# UUIDs taken from preview-import's unresolved_refs[*].alternatives.
+seclai agents create --json '{"name":"Imported","trigger_type":"dynamic_input","agent_definition":{},"entity_remap":{}}'
+\`\`\`
+
+## Input uploads
+
+\`\`\`bash
+# What files (if any) does this agent expect? requires_uploads reports whether it
+# accepts files; the agent block lists the names, indexes and patterns a run-time
+# batch must satisfy. Call this before staging uploads.
+seclai agents attachment-references <agentId>
+
 seclai agents upload-input <agentId> --file ./input.pdf [--file-name name] [--mime-type type]
 seclai agents input-status <agentId> <uploadId>
 \`\`\`
 
-### Agent AI assistant
+## Agent AI assistant
 
 \`\`\`bash
 seclai agents ai gen-steps <agentId> --user-input "Build a QA chatbot"
 seclai agents ai step-config <agentId> --json '{"step_type":"llm","user_input":"Configure the LLM step"}'
-seclai agents ai history <agentId>
+
+# --step-type is required; the API rejects the request without it
+seclai agents ai history <agentId> --step-type llm [--step-id <id>] [--limit N] [--offset N]
+
 seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
 \`\`\`
 
-### Sources
+## Example: knowledge-base-backed agent
 
 \`\`\`bash
-seclai sources list [--page N] [--limit N] [--sort field] [--order asc|desc] [--account-id id]
-seclai sources create --json '{"name":"Docs","description":"Product documentation"}'
-seclai sources get <sourceId>
-seclai sources update <sourceId> --json '{"name":"Updated Docs"}'
-seclai sources delete <sourceId>
+seclai kb create --json '{"name":"Support KB","description":"Customer support articles"}'
+seclai agents create --json '{"name":"Support Bot","description":"Answers customer questions"}'
+seclai agents ai gen-steps <agentId> --user-input "Build a QA chatbot that searches the Support KB"
+seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
+seclai agents run <agentId> --json '{"input":"How do I reset my password?"}' --stream
 \`\`\`
 
-### Source uploads
+## Example: memory-powered agent
 
 \`\`\`bash
-seclai sources upload <sourceId> --file ./doc.pdf [--title "My Doc"] [--metadata '{"category":"docs"}'] [--file-name name] [--mime-type type]
-seclai sources upload-text <sourceId> --json '{"text":"Article content here...","title":"My Article"}'
+seclai memory create --json '{"name":"User Preferences","type":"general"}'
+seclai agents create --json '{"name":"Personal Assistant","description":"Remembers user preferences"}'
+seclai agents ai gen-steps <agentId> --user-input "Build a chat agent that remembers user preferences. Use general memory bank <memoryBankId>"
+seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
 \`\`\`
+` },
+  { name: "references/ai-assistant.md", content: `# Top-level AI assistant
 
-### Source exports
+\`seclai ai\` creates resources from a natural-language description, without
+starting from a solution or an agent. The domain-scoped assistants \u2014
+\`agents ai\`, \`memory ai\`, \`solutions ai\`, \`governance ai\` \u2014 live with their
+resources.
 
 \`\`\`bash
-seclai sources exports list <sourceId> [--page N] [--limit N]
-seclai sources exports create <sourceId> --json '{"format":"jsonl"}'
-seclai sources exports get <sourceId> <exportId>
-seclai sources exports cancel <sourceId> <exportId>
-seclai sources exports delete <sourceId> <exportId>
-seclai sources exports download <sourceId> <exportId>
-seclai sources exports estimate <sourceId> --json '{"format":"jsonl"}'
+seclai ai kb --user-input "Create a support knowledge base"
+seclai ai source --user-input "Create a documentation source"
+seclai ai solution --user-input "Build a customer support solution"
+seclai ai memory --user-input "Create a conversation memory bank"
+
+seclai ai memory-history
+seclai ai accept <conversationId> --json '{"accepted":true}'
+seclai ai decline <conversationId>
+seclai ai memory-accept <conversationId> --json '{"accepted":true}'
+
+seclai ai feedback --json '{"feedback":"The response was helpful"}'
 \`\`\`
 
-### Embedding migration
+## The generate-then-accept cycle
+
+Every assistant command returns a *proposal* with a conversation ID. Nothing is
+created until you accept it:
 
 \`\`\`bash
-seclai sources migration get <sourceId>
-seclai sources migration start <sourceId> --json '{"target_model":"text-embedding-3-large"}'
-seclai sources migration cancel <sourceId>
+seclai ai kb --user-input "Create a support knowledge base"
+# read the proposal, note the conversation id
+seclai ai accept <conversationId> --json '{"accepted":true}'
 \`\`\`
 
-### Contents (indexed content)
+Memory-bank proposals have their own accept command (\`ai memory-accept\`) and
+their own history (\`ai memory-history\`); everything else uses \`ai accept\` /
+\`ai decline\`.
+` },
+  { name: "references/alerts.md", content: `# Alerts
 
-\`\`\`bash
+Account alerts, the configurations that raise them, and per-organization
+delivery preferences.
+
+Model-catalog alerts are separate \u2014 see [models.md](models.md).
+
+## Alerts
+
+\`\`\`bash
+seclai alerts list [--page N] [--limit N] [--status <status>]
+seclai alerts get <alertId>
+seclai alerts status <alertId> --json '{"status":"resolved"}'
+seclai alerts comment <alertId> --json '{"comment":"Fixed the issue"}'
+seclai alerts subscribe <alertId>
+seclai alerts unsubscribe <alertId>
+\`\`\`
+
+\`GET /alerts\` declares no severity filter, so there is no \`--severity\` \u2014 it
+never filtered anything, and returned unfiltered rows that looked filtered.
+Filter client-side instead:
+
+\`\`\`bash
+seclai alerts list | jq '[.data[] | select(.severity == "high")]'
+\`\`\`
+
+## Alert configurations
+
+\`\`\`bash
+seclai alerts configs list [--page N] [--limit N]
+seclai alerts configs create --json '{"name":"Latency Alert","description":"...","threshold":5000}'
+seclai alerts configs get <configId>
+seclai alerts configs update <configId> --json '{"threshold":3000}'
+seclai alerts configs delete <configId>
+\`\`\`
+
+## Organization preferences
+
+\`\`\`bash
+seclai alerts prefs list
+seclai alerts prefs update <organizationId> <alertType> --json '{"enabled":true}'
+\`\`\`
+
+Preferences are per organization and per alert type, so \`update\` takes both.
+` },
+  { name: "references/email.md", content: `# Agent email
+
+The domains agents send from, the inbound blocklist, inbound health, and
+recipient opt-outs.
+
+Per-agent inbound configuration (alias, sender allowlist) lives on the trigger \u2014
+see \`agents triggers email-config\` in [agents.md](agents.md).
+
+## Sending domains
+
+\`\`\`bash
+seclai email domains list
+seclai email domains add --kind custom --value mail.example.com [--delegated]
+seclai email domains verify <domainId>        # run a DNS check now
+seclai email domains set-primary <domainId>
+seclai email domains test-email <domainId>    # send a test to the account owner
+seclai email domains dmarc <domainId> [--days N] [--top-sources N]
+seclai email domains remove <domainId>
+seclai email domains use-shared               # revert to agent.seclai.com
+\`\`\`
+
+\`--kind\` is \`vanity\` (a subdomain of seclai.com) or \`custom\` (your own domain).
+\`add\` returns the DNS records to publish; pass \`--delegated\` when the domain's
+DNS is delegated to Seclai so those records are published for you. A domain must
+verify before \`set-primary\` will accept it.
+
+## Inbound sender blocklist
+
+\`\`\`bash
+seclai email blocked list [--limit N] [--offset N]
+seclai email blocked add --sender-email spam@example.com [--note "phishing"]
+seclai email blocked add --sender-email example.com --match-type domain
+seclai email blocked remove <blockedId>
+seclai email blocked auto-block-mode disabled|input|input_and_output
+\`\`\`
+
+\`--match-type\` is \`address\` (the default) or \`domain\`. \`auto-block-mode\` controls
+whether a governance BLOCK on an authenticated sender adds them to the blocklist
+automatically.
+
+## Inbound health
+
+\`\`\`bash
+seclai email inbound status          # quota usage, pause state, queued run counts
+seclai email inbound rejections [--agent-id <id>] [--limit N]
+seclai email inbound cancel-queued   # fail every over-quota parked run at once
+seclai email inbound resume          # lift the account-wide pause
+\`\`\`
+
+When inbound email exceeds quota, runs park in a QUEUED state and the account
+pauses. \`status\` shows both; \`cancel-queued\` clears the backlog and \`resume\`
+lifts the pause. Check \`rejections\` first \u2014 it reports why messages were turned
+away, which is usually the more useful answer.
+
+## Recipient opt-outs
+
+\`\`\`bash
+seclai email optouts list [--agent-id <id>] [--limit N] [--offset N]
+seclai email optouts remove <optoutId>
+\`\`\`
+
+Removing an opt-out lets that recipient receive agent email again.
+` },
+  { name: "references/evaluations.md", content: `# Evaluations Workflow
+
+## Step 1: Create evaluation criteria for an agent
+\`\`\`bash
+seclai evals criteria create <agentId> --json '{"name":"Answer Accuracy","description":"Does the answer correctly address the question?","eval_type":"llm_judge"}'
+\`\`\`
+
+## Step 2: Find runs to evaluate
+\`\`\`bash
+# list all runs for an agent
+seclai agents runs list <agentId> --limit 10
+
+# or find runs compatible with specific criteria
+seclai evals compatible-runs <criteriaId> --limit 10
+\`\`\`
+
+## Step 3: Test criteria before committing
+\`\`\`bash
+seclai evals test-draft <agentId> --json '{"criteria":{"name":"Answer Accuracy","eval_type":"llm_judge","description":"..."},"run_id":"<runId>"}'
+\`\`\`
+
+## Step 4: Create evaluation results
+\`\`\`bash
+seclai evals results create <criteriaId> --json '{"run_id":"<runId>","score":0.95}'
+\`\`\`
+
+## Step 5: Review summaries
+\`\`\`bash
+seclai evals criteria summary <criteriaId>
+seclai evals agent-results <agentId>
+seclai evals agent-runs <agentId> --limit 20
+seclai evals non-manual-summary <agentId>
+\`\`\`
+
+## Managing criteria
+\`\`\`bash
+seclai evals criteria list <agentId> [--page N] [--limit N] [--paged]
+seclai evals criteria get <criteriaId>
+seclai evals criteria update <criteriaId> --json '{"name":"Updated Name"}'
+seclai evals criteria delete <criteriaId>
+\`\`\`
+
+\`--paged\` wraps the results in \`{"data": [...]}\` instead of returning a bare
+array, so \`.data\` is a stable path to read whatever \`--api-version\` is in effect.
+Nothing is invented: the \`pagination\` block appears only once the API sends one,
+from \`--api-version 2026-07-27\`. Move scripts to \`.data\` first, then opt in to
+get \`.pagination\`.
+
+## Viewing results
+\`\`\`bash
+seclai evals results list <criteriaId> [--page N] [--limit N]
+seclai evals compatible-runs <criteriaId> [--page N] [--limit N]
+seclai evals agent-results <agentId> [--page N] [--limit N]
+seclai evals agent-runs <agentId> [--page N] [--limit N]
+\`\`\`
+` },
+  { name: "references/knowledge.md", content: `# Sources, content, knowledge bases and memory banks
+
+The ingestion side of Seclai: where documents come from, how they are indexed,
+and the stores agents read from.
+
+For upload mechanics \u2014 MIME types, size limits, metadata \u2014 see
+[uploads.md](uploads.md).
+
+## Sources
+
+\`\`\`bash
+seclai sources list [--page N] [--limit N] [--sort field] [--order asc|desc] [--account-id id]
+seclai sources create --json '{"name":"Docs","description":"Product documentation"}'
+seclai sources get <sourceId>
+seclai sources update <sourceId> --json '{"name":"Updated Docs"}'
+seclai sources delete <sourceId>
+\`\`\`
+
+\`source\` is accepted as an alias for \`sources\`.
+
+## Source uploads
+
+\`\`\`bash
+seclai sources upload <sourceId> --file ./doc.pdf [--title "My Doc"] [--metadata '{"category":"docs"}'] [--file-name name] [--mime-type type]
+seclai sources upload-text <sourceId> --json '{"text":"Article content here...","title":"My Article"}'
+\`\`\`
+
+## Source exports
+
+\`\`\`bash
+seclai sources exports list <sourceId> [--page N] [--limit N]
+seclai sources exports create <sourceId> --json '{"format":"jsonl"}'
+seclai sources exports get <sourceId> <exportId>
+seclai sources exports cancel <sourceId> <exportId>
+seclai sources exports delete <sourceId> <exportId>
+seclai sources exports download <sourceId> <exportId>
+seclai sources exports estimate <sourceId> --json '{"format":"jsonl"}'
+\`\`\`
+
+\`estimate\` reports the size and cost before you commit to \`create\`.
+
+## Embedding migration
+
+\`\`\`bash
+seclai sources migration get <sourceId>
+seclai sources migration start <sourceId> --json '{"target_model":"text-embedding-3-large"}'
+seclai sources migration cancel <sourceId>
+\`\`\`
+
+## Contents (indexed content)
+
+\`\`\`bash
 seclai contents get <contentVersionId> [--start N] [--end N]
 seclai contents delete <contentVersionId>
 seclai contents upload <contentVersionId> --file ./updated.pdf [--title "Title"] [--file-name name] [--mime-type type]
@@ -1453,7 +2138,10 @@ seclai contents replace-text <contentVersionId> --json '{"text":"Replacement tex
 seclai contents embeddings <contentVersionId> [--page N] [--limit N]
 \`\`\`
 
-### Knowledge bases
+\`--start\` / \`--end\` on \`contents get\` slice the returned text by character
+offset, which is how you inspect a long document without pulling all of it.
+
+## Knowledge bases
 
 \`\`\`bash
 seclai kb list [--page N] [--limit N] [--sort field] [--order asc|desc]
@@ -1463,7 +2151,7 @@ seclai kb update <kbId> --json '{"name":"Updated KB"}'
 seclai kb delete <kbId>
 \`\`\`
 
-### Memory banks
+## Memory banks
 
 \`\`\`bash
 seclai memory list [--page N] [--limit N] [--sort field] [--order asc|desc]
@@ -1474,11 +2162,11 @@ seclai memory update <memoryBankId> --json '{"name":"Renamed"}'
 seclai memory delete <memoryBankId>
 \`\`\`
 
-### Memory bank utilities
+### Utilities
 
 \`\`\`bash
 seclai memory stats <memoryBankId>
-seclai memory agents <memoryBankId>
+seclai memory agents <memoryBankId>        # agents using this bank
 seclai memory compact <memoryBankId>
 seclai memory delete-source <memoryBankId>
 seclai memory templates
@@ -1486,6 +2174,9 @@ seclai memory test-compaction <memoryBankId> --json '{"prompt":"Summarize the co
 seclai memory test-compaction-standalone --json '{"prompt":"Summarize the conversation"}'
 \`\`\`
 
+Both \`test-compaction\` commands are dry runs \u2014 they show what compaction would
+produce without writing to the bank.
+
 ### Memory bank AI
 
 \`\`\`bash
@@ -1494,180 +2185,190 @@ seclai memory ai last
 seclai memory ai accept <conversationId> --json '{"accepted":true}'
 \`\`\`
 
-### Evaluations \u2014 criteria
+## Example: create a source and upload content
 
 \`\`\`bash
-seclai evals criteria list <agentId> [--page N] [--limit N]
-seclai evals criteria create <agentId> --json '{"name":"Response Quality","description":"...","eval_type":"llm_judge"}'
-seclai evals criteria get <criteriaId>
-seclai evals criteria update <criteriaId> --json '{"name":"Updated Criteria"}'
-seclai evals criteria delete <criteriaId>
-seclai evals criteria summary <criteriaId>
+seclai sources create --json '{"name":"Product Docs","description":"Product documentation source"}'
+# note the id from the output
+seclai sources upload <sourceId> --file ./docs.pdf --title "Product Manual" --metadata '{"version":"2.0"}'
+seclai sources get <sourceId>
 \`\`\`
+` },
+  { name: "references/models.md", content: `# Models
 
-### Evaluations \u2014 results & runs
+The model catalog, media-generation tiers, model-catalog alerts, recommendations
+and the playground.
 
-\`\`\`bash
-seclai evals results list <criteriaId> [--page N] [--limit N]
-seclai evals results create <criteriaId> --json '{"run_id":"...","score":0.9}'
-seclai evals compatible-runs <criteriaId> [--page N] [--limit N]
-seclai evals test-draft <agentId> --json '{"criteria":{"name":"Test","eval_type":"llm_judge"},"run_id":"..."}'
-seclai evals agent-results <agentId> [--page N] [--limit N]
-seclai evals agent-runs <agentId> [--page N] [--limit N]
-seclai evals non-manual-summary <agentId>
-\`\`\`
-
-### Solutions
+## Catalog
 
 \`\`\`bash
-seclai solutions list [--page N] [--limit N] [--sort field] [--order asc|desc]
-seclai solutions create --json '{"name":"Customer Support Solution"}'
-seclai solutions get <solutionId>
-seclai solutions update <solutionId> --json '{"name":"Updated"}'
-seclai solutions delete <solutionId>
+seclai models list [--provider <name>] [--supports-tool-use] [--supports-thinking]
+seclai models list [--supports-input-media <media>] [--supports-output-media <media>]
+seclai models get <modelId>
+
+# each media-generation modality and tier, with its model and cost
+seclai models tiers
 \`\`\`
 
-### Solution links
+The capability flags compose, so \`--supports-tool-use --supports-thinking\`
+returns only models with both. \`--supports-input-media\` / \`--supports-output-media\`
+take a modality such as \`image\`, \`audio\` or \`video\`.
+
+## Model alerts
 
 \`\`\`bash
-# link resources \u2014 each flag takes a JSON array of IDs
-seclai solutions link <solutionId> --agents '["agentId1"]' --kb '["kbId1"]' --sources '["sourceId1"]'
-seclai solutions unlink <solutionId> --agents '["agentId1"]'
+seclai models alerts list [--page N] [--limit N]
+seclai models alerts mark-read <alertId>
+seclai models alerts mark-all-read
+seclai models alerts unread-count
 \`\`\`
 
-### Solution conversations & AI
+These are catalog alerts \u2014 deprecations, price changes, new models \u2014 not the
+account alerts in [alerts.md](alerts.md).
 
-\`\`\`bash
-seclai solutions convos list <solutionId>
-seclai solutions convos add <solutionId> --json '{"message":"How should I structure this?"}'
-seclai solutions convos mark <solutionId> <conversationId> --json '{"accepted":true}'
+## Recommendations
 
-seclai solutions ai generate <solutionId> --user-input "Add an FAQ source"
-seclai solutions ai kb <solutionId> --user-input "Create a knowledge base for docs"
-seclai solutions ai source <solutionId> --user-input "Create a file source for PDFs"
-seclai solutions ai accept <solutionId> <conversationId> --json '{"accepted":true}'
-seclai solutions ai decline <solutionId> <conversationId>
+\`\`\`bash
+seclai models recommendations <modelId>
 \`\`\`
 
-### Alerts
+Suggests replacements for a model, which is how you act on a deprecation alert.
+
+## Playground experiments
 
 \`\`\`bash
-seclai alerts list [--page N] [--limit N] [--status <status>] [--severity <severity>]
-seclai alerts get <alertId>
-seclai alerts status <alertId> --json '{"status":"resolved"}'
-seclai alerts comment <alertId> --json '{"comment":"Fixed the issue"}'
-seclai alerts subscribe <alertId>
-seclai alerts unsubscribe <alertId>
+seclai models experiments list [--days N] [--start-date <date>] [--end-date <date>] [--limit N] [--offset N]
+seclai models experiments create --json '{"model_ids":["gpt-4o"],"prompt":"Compare responses"}'
+seclai models experiments get <experimentId>
+seclai models experiments cancel <experimentId>
+seclai models experiments delete <experimentId>  # soft-delete, preserves audit history
 \`\`\`
 
-### Alert configurations
+\`create\` takes several \`model_ids\` and runs the same prompt against each, which
+is the point \u2014 side-by-side comparison. \`cancel\` stops a running experiment;
+\`delete\` soft-deletes a finished one.
+` },
+  { name: "references/setup.md", content: `# Setup: authentication, profiles, API version, editor integration
+
+## SSO authentication
 
 \`\`\`bash
-seclai alerts configs list [--page N] [--limit N]
-seclai alerts configs create --json '{"name":"Latency Alert","description":"...","threshold":5000}'
-seclai alerts configs get <configId>
-seclai alerts configs update <configId> --json '{"threshold":3000}'
-seclai alerts configs delete <configId>
+seclai auth login [--port <port>] [--no-browser]   # OAuth2 + PKCE in the browser
+seclai auth status                                 # active profile's auth state
+seclai auth refresh                                # refresh the token manually
+seclai auth logout                                 # clear cached tokens
 \`\`\`
 
-### Alert preferences
+Tokens are cached under the config directory and refreshed automatically, so
+\`auth refresh\` is only needed to force it. An API key in \`SECLAI_API_KEY\` takes a
+different path entirely and needs none of this.
+
+## Profiles
 
 \`\`\`bash
-seclai alerts prefs list
-seclai alerts prefs update <organizationId> <alertType> --json '{"enabled":true}'
+seclai configure sso [--profile-name <name>]   # interactive: domain, client ID, region, account ID
+seclai configure list                          # every configured profile
 \`\`\`
 
-### Governance AI
+Profiles live in \`~/.seclai/config\` (override with \`--config-dir\` or
+\`SECLAI_CONFIG_DIR\`). Select one per invocation with \`--profile <name>\`, or set
+\`SECLAI_PROFILE\`.
+
+## API version
 
 \`\`\`bash
-seclai governance ai generate --user-input "Create a content safety policy"
-seclai governance ai list
-seclai governance ai accept <conversationId>
-seclai governance ai decline <conversationId>
+seclai api-version get           # what version does a request resolve to?
+seclai api-version set <date>    # pin the account \u2014 affects every client
+seclai api-version clear         # remove the pin
 \`\`\`
 
-### Model alerts
+\`set\` and \`clear\` change the account, not just this CLI. To affect only your own
+invocation, use the \`--api-version\` global option instead.
+
+## MCP server
 
 \`\`\`bash
-seclai models alerts list [--page N] [--limit N]
-seclai models alerts mark-read <alertId>
-seclai models alerts mark-all-read
-seclai models alerts unread-count
-seclai models recommendations <modelId>
+# write Seclai MCP server config into AI coding tool config files
+seclai mcp configure --key <apiKey> [--target claude-code|cursor|claude-desktop|windsurf|all] [--dir .]
+
+# print the config JSON for manual setup
+seclai mcp show [--key <apiKey>]
 \`\`\`
 
-### Search
+## Skill files
 
 \`\`\`bash
-seclai search --query "deployment guide" [--limit N] [--entity-type <type>]
+# install these skill files into AI coding tool directories
+seclai skills install [--tool copilot|claude|cursor|windsurf|codex|kiro|cline|roo|gemini|antigravity|all] [--dir .]
 \`\`\`
 
-### AI assistant (global)
+With no \`--tool\`, the target is detected from the directory structure.
+
+## Shell completion
 
 \`\`\`bash
-seclai ai feedback --json '{"feedback":"The response was helpful"}'
-seclai ai kb --user-input "Create a support knowledge base"
-seclai ai source --user-input "Create a documentation source"
-seclai ai solution --user-input "Build a customer support solution"
-seclai ai memory --user-input "Create a conversation memory bank"
-seclai ai memory-history
-seclai ai accept <conversationId> --json '{"accepted":true}'
-seclai ai decline <conversationId>
-seclai ai memory-accept <conversationId> --json '{"accepted":true}'
+seclai completion bash   # eval "$(seclai completion bash)" in ~/.bashrc
+seclai completion zsh    # eval "$(seclai completion zsh)" in ~/.zshrc
+seclai completion fish   # seclai completion fish > ~/.config/fish/completions/seclai.fish
 \`\`\`
+` },
+  { name: "references/solutions.md", content: `# Solutions and governance
 
-### Skills
+Solutions group agents, knowledge bases and sources into one deliverable.
+Governance defines the policies applied to agent input and output.
+
+## Solutions
 
 \`\`\`bash
-# install skill files into AI coding tool directories (auto-detects or specify)
-seclai skills install [--tool copilot|claude|cursor|windsurf|codex|kiro|cline|roo|gemini|antigravity|all] [--dir .]
+seclai solutions list [--page N] [--limit N] [--sort field] [--order asc|desc]
+seclai solutions create --json '{"name":"Customer Support Solution"}'
+seclai solutions get <solutionId>
+seclai solutions update <solutionId> --json '{"name":"Updated"}'
+seclai solutions delete <solutionId>
 \`\`\`
 
-### MCP server
+## Linking resources
 
 \`\`\`bash
-# configure MCP server access in AI coding tool config files
-seclai mcp configure --key <apiKey> [--target claude-code|cursor|claude-desktop|windsurf|all] [--dir .]
-
-# show the MCP config JSON snippet
-seclai mcp show [--key <apiKey>]
+# each flag takes a JSON array of IDs
+seclai solutions link <solutionId> --agents '["agentId1"]' --kb '["kbId1"]' --sources '["sourceId1"]'
+seclai solutions unlink <solutionId> --agents '["agentId1"]'
 \`\`\`
 
-## Example: Create a source and upload content
+## Conversations
 
 \`\`\`bash
-seclai sources create --json '{"name":"Product Docs","description":"Product documentation source"}'
-# note the id from the output
-seclai sources upload <sourceId> --file ./docs.pdf --title "Product Manual" --metadata '{"version":"2.0"}'
-seclai sources get <sourceId>
+seclai solutions convos list <solutionId>
+seclai solutions convos add <solutionId> --json '{"message":"How should I structure this?"}'
+seclai solutions convos mark <solutionId> <conversationId> --json '{"accepted":true}'
 \`\`\`
 
-## Example: Set up a knowledge base with an agent
+## Solution AI
 
 \`\`\`bash
-seclai kb create --json '{"name":"Support KB","description":"Customer support articles"}'
-seclai agents create --json '{"name":"Support Bot","description":"Answers customer questions"}'
-seclai agents ai gen-steps <agentId> --user-input "Build a QA chatbot that searches the Support KB"
-seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
-seclai agents run <agentId> --json '{"input":"How do I reset my password?"}' --stream
+seclai solutions ai generate <solutionId> --user-input "Add an FAQ source"
+seclai solutions ai kb <solutionId> --user-input "Create a knowledge base for docs"
+seclai solutions ai source <solutionId> --user-input "Create a file source for PDFs"
+seclai solutions ai accept <solutionId> <conversationId> --json '{"accepted":true}'
+seclai solutions ai decline <solutionId> <conversationId>
 \`\`\`
 
-## Example: Evaluate agent quality
+\`ai kb\` and \`ai source\` create the resource and link it to the solution in one
+step, which is why they live here rather than under \`kb\` or \`sources\`.
+
+## Governance AI
 
 \`\`\`bash
-# create eval criteria
-seclai evals criteria create <agentId> --json '{"name":"Answer Accuracy","eval_type":"llm_judge","description":"Does the answer correctly address the question?"}'
-# find compatible runs
-seclai evals compatible-runs <criteriaId> --limit 5
-# test the criteria against a run without persisting
-seclai evals test-draft <agentId> --json '{"criteria":{"name":"Answer Accuracy","eval_type":"llm_judge"},"run_id":"<runId>"}'
-# create a persisted result
-seclai evals results create <criteriaId> --json '{"run_id":"<runId>","score":0.95}'
-# view summary
-seclai evals criteria summary <criteriaId>
+seclai governance ai generate --user-input "Create a content safety policy"
+seclai governance ai list
+seclai governance ai accept <conversationId>
+seclai governance ai decline <conversationId>
 \`\`\`
 
-## Example: Solution with linked resources
+A generated policy is a proposal until accepted \u2014 \`generate\` alone changes
+nothing.
+
+## Example: solution with linked resources
 
 \`\`\`bash
 seclai solutions create --json '{"name":"Customer Support"}'
@@ -1675,30 +2376,15 @@ seclai solutions link <solutionId> --agents '["<agentId>"]' --kb '["<kbId>"]' --
 seclai solutions get <solutionId>
 \`\`\`
 
-## Example: Memory-powered agent
-
-\`\`\`bash
-seclai memory create --json '{"name":"User Preferences","type":"general"}'
-seclai agents create --json '{"name":"Personal Assistant","description":"Remembers user preferences"}'
-seclai agents ai gen-steps <agentId> --user-input "Build a chat agent that remembers user preferences. Use general memory bank <memoryBankId>"
-seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
-\`\`\`
-
-## Example: Governance policy setup
+## Example: governance policy setup
 
 \`\`\`bash
 seclai governance ai generate --user-input "Create a content safety policy that blocks harmful outputs"
 seclai governance ai list
 seclai governance ai accept <conversationId>
 \`\`\`
-
-## Specific topics
-
-* **Streaming & event modes** [references/streaming.md](references/streaming.md)
-* **File uploads & content management** [references/uploads.md](references/uploads.md)
-* **Evaluations workflow** [references/evaluations.md](references/evaluations.md)
-`;
-var STREAMING_REF = `# Streaming Agent Runs
+` },
+  { name: "references/streaming.md", content: `# Streaming Agent Runs
 
 ## Modes
 
@@ -1750,8 +2436,8 @@ seclai agents run <agentId> --json '{"input":"Hello"}'
 # check later:
 seclai agents runs get <runId>
 \`\`\`
-`;
-var UPLOADS_REF = `# File Uploads & Content Management
+` },
+  { name: "references/uploads.md", content: `# File Uploads & Content Management
 
 ## Upload to a source
 \`\`\`bash
@@ -1767,11 +2453,21 @@ seclai sources upload-text <sourceId> --json '{"text":"Article content here...",
 
 ## Upload input for agent runs
 \`\`\`bash
+# Check what files (if any) the agent expects before uploading. requires_uploads
+# reports whether the agent accepts files; the agent block lists the exact names /
+# indexes / patterns a run-time batch must satisfy.
+seclai agents attachment-references <agentId>
 seclai agents upload-input <agentId> --file ./input.pdf
 seclai agents upload-input <agentId> --file ./data.csv --file-name "report.csv" --mime-type "text/csv"
 seclai agents input-status <agentId> <uploadId>
 \`\`\`
 
+## Download an attachment emitted by a run
+\`\`\`bash
+# attachmentId is the URL-safe-base64 storage_key from run output manifests / webhooks.
+seclai agents runs download-attachment <runId> <attachmentId> --output ./out.pdf
+\`\`\`
+
 ## Replace content
 \`\`\`bash
 # replace with file
@@ -1792,61 +2488,10 @@ seclai contents get <contentVersionId> --start 0 --end 1000
 # view embeddings
 seclai contents embeddings <contentVersionId> [--page N] [--limit N]
 \`\`\`
-`;
-var EVALUATIONS_REF = `# Evaluations Workflow
-
-## Step 1: Create evaluation criteria for an agent
-\`\`\`bash
-seclai evals criteria create <agentId> --json '{"name":"Answer Accuracy","description":"Does the answer correctly address the question?","eval_type":"llm_judge"}'
-\`\`\`
-
-## Step 2: Find runs to evaluate
-\`\`\`bash
-# list all runs for an agent
-seclai agents runs list <agentId> --limit 10
-
-# or find runs compatible with specific criteria
-seclai evals compatible-runs <criteriaId> --limit 10
-\`\`\`
-
-## Step 3: Test criteria before committing
-\`\`\`bash
-seclai evals test-draft <agentId> --json '{"criteria":{"name":"Answer Accuracy","eval_type":"llm_judge","description":"..."},"run_id":"<runId>"}'
-\`\`\`
-
-## Step 4: Create evaluation results
-\`\`\`bash
-seclai evals results create <criteriaId> --json '{"run_id":"<runId>","score":0.95}'
-\`\`\`
-
-## Step 5: Review summaries
-\`\`\`bash
-seclai evals criteria summary <criteriaId>
-seclai evals agent-results <agentId>
-seclai evals agent-runs <agentId> --limit 20
-seclai evals non-manual-summary <agentId>
-\`\`\`
-
-## Managing criteria
-\`\`\`bash
-seclai evals criteria list <agentId>
-seclai evals criteria get <criteriaId>
-seclai evals criteria update <criteriaId> --json '{"name":"Updated Name"}'
-seclai evals criteria delete <criteriaId>
-\`\`\`
-
-## Viewing results
-\`\`\`bash
-seclai evals results list <criteriaId> [--page N] [--limit N]
-\`\`\`
-`;
+` }
+];
 function getToolConfig(tool, destDir) {
-  const skillFiles = [
-    { name: "SKILL.md", content: SKILL_MD },
-    { name: "references/streaming.md", content: STREAMING_REF },
-    { name: "references/uploads.md", content: UPLOADS_REF },
-    { name: "references/evaluations.md", content: EVALUATIONS_REF }
-  ];
+  const skillFiles = SKILL_FILES;
   switch (tool) {
     case "copilot":
       return { dir: join(destDir, ".github", "copilot", "seclai-cli"), files: skillFiles };
@@ -1888,7 +2533,7 @@ function detectTools(destDir) {
   if (existsSync(join(destDir, ".antigravity"))) detected.push("antigravity");
   return detected;
 }
-function register13(program, rt) {
+function register15(program, rt) {
   const skills = program.command("skills").description("Install Seclai CLI skill files for AI coding tools.");
   skills.command("install").description(
     "Write Seclai CLI skill/instruction files into the current workspace.\n\nDetected tools: copilot, claude, cursor, windsurf, codex, kiro, cline, roo, gemini, antigravity.\nUse --tool to target a specific tool, or 'all' for all supported tools."
@@ -1989,7 +2634,7 @@ function detectTargets(destDir) {
     return false;
   });
 }
-function register14(program, rt) {
+function register16(program, rt) {
   const mcp = program.command("mcp").description("Configure the Seclai MCP server for AI coding tools.");
   mcp.command("configure").description(
     "Add the Seclai MCP server to AI coding tool config files.\n\nTargets: claude-code, cursor, claude-desktop, windsurf.\nUse --target to pick a specific tool, or 'all' for all known targets."
@@ -2045,237 +2690,156 @@ function register14(program, rt) {
 }
 
 // src/commands/completion.ts
-var BASH = `#!/usr/bin/env bash
+function collectTree(program) {
+  const tree = /* @__PURE__ */ new Map();
+  const walk = (cmd, prefix) => {
+    const children = [];
+    for (const sub of cmd.commands) {
+      const name = sub.name();
+      if (name === "help") continue;
+      children.push({ name, description: sub.description().replace(/\s+/g, " ").trim() });
+      walk(sub, [...prefix, name]);
+    }
+    if (children.length > 0) tree.set(prefix.join(" "), children);
+  };
+  walk(program, []);
+  return tree;
+}
+function globalOptions(program) {
+  return program.options.filter((o) => o.long && o.long !== "--help").map((o) => ({
+    flag: o.long,
+    description: o.description.replace(/\s+/g, " ").trim()
+  }));
+}
+var names = (children) => children.map((c) => c.name).join(" ");
+function renderBash(tree, options) {
+  const cases = [...tree.entries()].map(([prefix, children]) => `    ${JSON.stringify(prefix)}) __seclai_reply "${names(children)}" ;;`).join("\n");
+  return `#!/usr/bin/env bash
 # seclai bash completion \u2014 add to ~/.bashrc:
 #   eval "$(seclai completion bash)"
+#
+# Generated from the command tree by \`seclai completion bash\`. Do not edit.
+
+__seclai_reply() {
+  COMPREPLY=( $(compgen -W "$1" -- "$__seclai_cur") )
+}
 
 _seclai_completions() {
-  local cur prev commands
-  cur="\${COMP_WORDS[COMP_CWORD]}"
-  prev="\${COMP_WORDS[COMP_CWORD-1]}"
-
-  # Top-level commands
-  commands="agents sources contents kb memory evals solutions governance alerts models search ai skills mcp completion help"
-
-  case "\${COMP_WORDS[1]}" in
-    agents)
-      case "\${COMP_WORDS[2]}" in
-        runs)   COMPREPLY=( $(compgen -W "list get delete cancel search eval-results download-attachment" -- "$cur") ); return ;;
-        def)    COMPREPLY=( $(compgen -W "get update" -- "$cur") ); return ;;
-        ai)     COMPREPLY=( $(compgen -W "gen-steps step-config history mark" -- "$cur") ); return ;;
-        *)      COMPREPLY=( $(compgen -W "list create get update delete run runs def export preview-import upload-input input-status attachment-references ai" -- "$cur") ); return ;;
-      esac ;;
-    sources|source)
-      case "\${COMP_WORDS[2]}" in
-        exports)    COMPREPLY=( $(compgen -W "list create get cancel delete download estimate" -- "$cur") ); return ;;
-        migration)  COMPREPLY=( $(compgen -W "get start cancel" -- "$cur") ); return ;;
-        *)          COMPREPLY=( $(compgen -W "list create get update delete upload upload-text exports migration" -- "$cur") ); return ;;
-      esac ;;
-    contents) COMPREPLY=( $(compgen -W "get delete upload replace replace-text embeddings" -- "$cur") ); return ;;
-    kb)       COMPREPLY=( $(compgen -W "list create get update delete" -- "$cur") ); return ;;
-    memory)
-      case "\${COMP_WORDS[2]}" in
-        ai) COMPREPLY=( $(compgen -W "generate last accept" -- "$cur") ); return ;;
-        *)  COMPREPLY=( $(compgen -W "list create get update delete stats agents compact delete-source templates test-compaction test-compaction-standalone ai" -- "$cur") ); return ;;
-      esac ;;
-    evals)
-      case "\${COMP_WORDS[2]}" in
-        criteria) COMPREPLY=( $(compgen -W "list create get update delete summary" -- "$cur") ); return ;;
-        results)  COMPREPLY=( $(compgen -W "list create" -- "$cur") ); return ;;
-        *)        COMPREPLY=( $(compgen -W "criteria results compatible-runs test-draft agent-results agent-runs non-manual-summary" -- "$cur") ); return ;;
-      esac ;;
-    solutions)
-      case "\${COMP_WORDS[2]}" in
-        convos) COMPREPLY=( $(compgen -W "list add mark" -- "$cur") ); return ;;
-        ai)     COMPREPLY=( $(compgen -W "generate kb source accept decline" -- "$cur") ); return ;;
-        *)      COMPREPLY=( $(compgen -W "list create get update delete link unlink convos ai" -- "$cur") ); return ;;
-      esac ;;
-    governance)
-      case "\${COMP_WORDS[2]}" in
-        ai) COMPREPLY=( $(compgen -W "generate list accept decline" -- "$cur") ); return ;;
-        *)  COMPREPLY=( $(compgen -W "ai" -- "$cur") ); return ;;
-      esac ;;
-    alerts)
-      case "\${COMP_WORDS[2]}" in
-        configs) COMPREPLY=( $(compgen -W "list create get update delete" -- "$cur") ); return ;;
-        prefs)   COMPREPLY=( $(compgen -W "list update" -- "$cur") ); return ;;
-        *)       COMPREPLY=( $(compgen -W "list get status comment subscribe unsubscribe configs prefs" -- "$cur") ); return ;;
-      esac ;;
-    models)
-      case "\${COMP_WORDS[2]}" in
-        alerts)      COMPREPLY=( $(compgen -W "list mark-read mark-all-read unread-count" -- "$cur") ); return ;;
-        experiments) COMPREPLY=( $(compgen -W "list create get cancel delete" -- "$cur") ); return ;;
-        *)           COMPREPLY=( $(compgen -W "alerts recommendations experiments" -- "$cur") ); return ;;
-      esac ;;
-    ai) COMPREPLY=( $(compgen -W "feedback kb source solution memory memory-history accept decline memory-accept" -- "$cur") ); return ;;
-    skills) COMPREPLY=( $(compgen -W "install" -- "$cur") ); return ;;
-    mcp) COMPREPLY=( $(compgen -W "configure show" -- "$cur") ); return ;;
-    completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ); return ;;
+  local __seclai_cur prefix i
+  __seclai_cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  # Everything typed so far except the program name and the word being
+  # completed, with flags dropped, joined by spaces.
+  prefix=""
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    case "\${COMP_WORDS[i]}" in
+      -*) continue ;;
+    esac
+    if [ -z "$prefix" ]; then
+      prefix="\${COMP_WORDS[i]}"
+    else
+      prefix="$prefix \${COMP_WORDS[i]}"
+    fi
+  done
+
+  case "$__seclai_cur" in
+    -*) __seclai_reply "${options.map((o) => o.flag).join(" ")}"; return ;;
   esac
 
-  COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+  case "$prefix" in
+${cases}
+    *) COMPREPLY=() ;;
+  esac
 }
 
 complete -F _seclai_completions seclai
 `;
-var ZSH = `#compdef seclai
+}
+function renderZsh(tree, options) {
+  const cases = [...tree.entries()].map(([prefix, children]) => {
+    const described = children.map((c) => `'${c.name}:${c.description.replace(/['`$]/g, "")}'`).join(" ");
+    return `    ${JSON.stringify(prefix)}) sub=(${described}) ;;`;
+  }).join("\n");
+  const opts = options.map((o) => `'${o.flag}[${o.description.replace(/['\]`$]/g, "")}]'`).join(" ");
+  return `#compdef seclai
 # seclai zsh completion \u2014 add to ~/.zshrc:
 #   eval "$(seclai completion zsh)"
+#
+# Generated from the command tree by \`seclai completion zsh\`. Do not edit.
 
 _seclai() {
-  local -a commands
-  commands=(
-    'agents:Manage agents, runs, definitions, and AI assistance'
-    'sources:Manage content sources'
-    'contents:Manage indexed content and embeddings'
-    'kb:Manage knowledge bases'
-    'memory:Manage memory banks'
-    'evals:Manage evaluations'
-    'solutions:Manage solutions'
-    'governance:Governance AI assistant'
-    'alerts:Manage alerts and alert configurations'
-    'models:Model alerts and recommendations'
-    'search:Search across Seclai resources'
-    'ai:Top-level AI assistant'
-    'skills:Install skill files for AI coding tools'
-    'mcp:Configure the Seclai MCP server'
-    'completion:Generate shell completion scripts'
-    'help:Display help for command'
-  )
-
-  _arguments -C \\
-    '--api-key[Seclai API key]:key' \\
-    '--compact[Output compact JSON]' \\
-    '-V[Output version]' \\
-    '-h[Display help]' \\
-    '1:command:->cmd' \\
-    '*::arg:->args'
-
-  case $state in
-    cmd) _describe 'command' commands ;;
-    args)
-      case \${words[1]} in
-        agents)
-          local -a sub=(list create get update delete run runs def export preview-import upload-input input-status attachment-references ai)
-          _describe 'subcommand' sub ;;
-        sources|source)
-          local -a sub=(list create get update delete upload upload-text exports migration)
-          _describe 'subcommand' sub ;;
-        contents)
-          local -a sub=(get delete upload replace replace-text embeddings)
-          _describe 'subcommand' sub ;;
-        kb)
-          local -a sub=(list create get update delete)
-          _describe 'subcommand' sub ;;
-        memory)
-          local -a sub=(list create get update delete stats agents compact delete-source templates test-compaction test-compaction-standalone ai)
-          _describe 'subcommand' sub ;;
-        evals)
-          local -a sub=(criteria results compatible-runs test-draft agent-results agent-runs non-manual-summary)
-          _describe 'subcommand' sub ;;
-        solutions)
-          local -a sub=(list create get update delete link unlink convos ai)
-          _describe 'subcommand' sub ;;
-        governance)
-          local -a sub=(ai)
-          _describe 'subcommand' sub ;;
-        alerts)
-          local -a sub=(list get status comment subscribe unsubscribe configs prefs)
-          _describe 'subcommand' sub ;;
-        models)
-          local -a sub=(alerts recommendations experiments)
-          _describe 'subcommand' sub ;;
-        ai)
-          local -a sub=(feedback kb source solution memory memory-history accept decline memory-accept)
-          _describe 'subcommand' sub ;;
-        skills)
-          local -a sub=(install)
-          _describe 'subcommand' sub ;;
-        mcp)
-          local -a sub=(configure show)
-          _describe 'subcommand' sub ;;
-        completion)
-          local -a sub=(bash zsh fish)
-          _describe 'shell' sub ;;
-      esac ;;
+  local prefix cur
+  local -a sub opts
+  cur="\${words[CURRENT]}"
+
+  opts=(${opts})
+  if [[ "$cur" == -* ]]; then
+    _describe 'option' opts
+    return
+  fi
+
+  # Words typed so far, minus the program name, the word being completed, and
+  # any flags.
+  prefix="\${(j: :)\${(M)words[2,CURRENT-1]:#[^-]*}}"
+
+  case "$prefix" in
+${cases}
+    *) return ;;
   esac
+
+  _describe 'command' sub
 }
 
-_seclai "$@"
+compdef _seclai seclai
 `;
-var FISH = `# seclai fish completion \u2014 save to ~/.config/fish/completions/seclai.fish
+}
+function renderFish(tree, options) {
+  const lines = [...tree.entries()].map(
+    ([prefix, children]) => children.map(
+      (c) => `complete -c seclai -f -n "__seclai_at '${prefix}'" -a "${c.name}" -d "${c.description.replace(/["$`]/g, "")}"`
+    ).join("\n")
+  ).join("\n");
+  const opts = options.map(
+    (o) => `complete -c seclai -l ${o.flag.replace(/^--/, "")} -d "${o.description.replace(/["$`]/g, "")}"`
+  ).join("\n");
+  return `# seclai fish completion \u2014 save to your completions directory:
 #   seclai completion fish > ~/.config/fish/completions/seclai.fish
-
-set -l top agents sources contents kb memory evals solutions governance alerts models search ai skills mcp completion help
-
-# Top-level
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "agents" -d "Manage agents"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "sources" -d "Manage sources"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "contents" -d "Manage content"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "kb" -d "Knowledge bases"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "memory" -d "Memory banks"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "evals" -d "Evaluations"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "solutions" -d "Solutions"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "governance" -d "Governance AI"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "alerts" -d "Alerts"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "models" -d "Model alerts"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "search" -d "Search resources"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "ai" -d "AI assistant"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "skills" -d "Skill files"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "mcp" -d "MCP server config"
-complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "completion" -d "Shell completions"
-
-# agents
-complete -c seclai -n "__fish_seen_subcommand_from agents; and not __fish_seen_subcommand_from list create get update delete run runs def export preview-import upload-input input-status attachment-references ai" -f -a "list create get update delete run runs def export preview-import upload-input input-status attachment-references ai"
-
-# sources
-complete -c seclai -n "__fish_seen_subcommand_from sources; and not __fish_seen_subcommand_from list create get update delete upload upload-text exports migration" -f -a "list create get update delete upload upload-text exports migration"
-
-# contents
-complete -c seclai -n "__fish_seen_subcommand_from contents; and not __fish_seen_subcommand_from get delete upload replace replace-text embeddings" -f -a "get delete upload replace replace-text embeddings"
-
-# kb
-complete -c seclai -n "__fish_seen_subcommand_from kb; and not __fish_seen_subcommand_from list create get update delete" -f -a "list create get update delete"
-
-# memory
-complete -c seclai -n "__fish_seen_subcommand_from memory; and not __fish_seen_subcommand_from list create get update delete stats agents compact delete-source templates test-compaction test-compaction-standalone ai" -f -a "list create get update delete stats agents compact delete-source templates test-compaction test-compaction-standalone ai"
-
-# evals
-complete -c seclai -n "__fish_seen_subcommand_from evals; and not __fish_seen_subcommand_from criteria results compatible-runs test-draft agent-results agent-runs non-manual-summary" -f -a "criteria results compatible-runs test-draft agent-results agent-runs non-manual-summary"
-
-# solutions
-complete -c seclai -n "__fish_seen_subcommand_from solutions; and not __fish_seen_subcommand_from list create get update delete link unlink convos ai" -f -a "list create get update delete link unlink convos ai"
-
-# governance
-complete -c seclai -n "__fish_seen_subcommand_from governance; and not __fish_seen_subcommand_from ai" -f -a "ai"
-
-# alerts
-complete -c seclai -n "__fish_seen_subcommand_from alerts; and not __fish_seen_subcommand_from list get status comment subscribe unsubscribe configs prefs" -f -a "list get status comment subscribe unsubscribe configs prefs"
-
-# models
-complete -c seclai -n "__fish_seen_subcommand_from models; and not __fish_seen_subcommand_from alerts recommendations experiments" -f -a "alerts recommendations experiments"
-
-# ai
-complete -c seclai -n "__fish_seen_subcommand_from ai; and not __fish_seen_subcommand_from feedback kb source solution memory memory-history accept decline memory-accept" -f -a "feedback kb source solution memory memory-history accept decline memory-accept"
-
-# skills
-complete -c seclai -n "__fish_seen_subcommand_from skills; and not __fish_seen_subcommand_from install" -f -a "install"
-
-# mcp
-complete -c seclai -n "__fish_seen_subcommand_from mcp; and not __fish_seen_subcommand_from configure show" -f -a "configure show"
-
-# completion
-complete -c seclai -n "__fish_seen_subcommand_from completion; and not __fish_seen_subcommand_from bash zsh fish" -f -a "bash zsh fish"
+#
+# Generated from the command tree by \`seclai completion fish\`. Do not edit.
+
+function __seclai_prefix
+    set -l toks (commandline -opc)
+    set -e toks[1]
+    set -l out
+    for t in $toks
+        if not string match -q -- '-*' $t
+            set -a out $t
+        end
+    end
+    string join ' ' $out
+end
+
+function __seclai_at
+    test (__seclai_prefix) = "$argv[1]"
+end
+
+${lines}
 
 # Global options
-complete -c seclai -l api-key -d "Seclai API key"
-complete -c seclai -l compact -d "Output compact JSON"
-complete -c seclai -s V -l version -d "Output version"
+${opts}
 `;
-var SCRIPTS = { bash: BASH, zsh: ZSH, fish: FISH };
-function register15(program, rt) {
-  const completion = program.command("completion").description("Generate shell completion scripts.").argument("<shell>", "Shell type: bash, zsh, or fish.").action(async (shell) => {
-    const script = SCRIPTS[shell];
+}
+function renderCompletion(shell, program) {
+  const tree = collectTree(program);
+  const options = globalOptions(program);
+  if (shell === "bash") return renderBash(tree, options);
+  if (shell === "zsh") return renderZsh(tree, options);
+  if (shell === "fish") return renderFish(tree, options);
+  return void 0;
+}
+function register17(program, rt) {
+  program.command("completion").description("Generate shell completion scripts.").argument("<shell>", "Shell type: bash, zsh, or fish.").action((shell) => {
+    const script = renderCompletion(shell, program);
     if (!script) {
       rt.writeErr(`Unknown shell "${shell}". Use: bash, zsh, or fish.
 `);
@@ -2447,7 +3011,7 @@ async function loadProfile(rt, opts) {
   const profile = await loadSsoProfile(configDir, profileName);
   return { profile, profileName, configDir };
 }
-function register16(program, rt) {
+function register18(program, rt) {
   const group = program.command("auth").description("SSO authentication (login/logout/status/refresh).");
   group.command("login").description("Authenticate via SSO using Authorization Code + PKCE flow.").option("--port <port>", "Local callback port", String(DEFAULT_CALLBACK_PORT)).option("--no-browser", "Print the URL instead of opening a browser").action(async (opts) => {
     await run(rt, async () => {
@@ -2621,7 +3185,7 @@ function resolveConfigDir(opts) {
   const home = process4.env.HOME ?? process4.env.USERPROFILE ?? "";
   return join4(home, ".seclai");
 }
-function register17(program, rt) {
+function register19(program, rt) {
   const group = program.command("configure").description("Configure CLI profiles and settings.");
   group.command("sso").description("Configure an SSO profile with optional overrides. Defaults to production Seclai SSO.").option("--profile-name <name>", "Profile name to configure (default: from --profile flag)").action(async (opts) => {
     await run(rt, async () => {
@@ -2735,7 +3299,7 @@ function escapeRegExp(s) {
 
 // src/cli.ts
 function createProgram(rt = defaultRuntime()) {
-  const program = new Command();
+  const program = new Command4();
   const cliVersion = getCliVersion();
   program.name("seclai").description(
     `Seclai Command Line Interface (v${cliVersion})
@@ -2755,6 +3319,12 @@ All commands return JSON to stdout, making it easy to pipe into jq or other tool
   ).option(
     "--config-dir <path>",
     "Config directory (defaults to SECLAI_CONFIG_DIR, then ~/.seclai)."
+  ).option(
+    "--api-version <date>",
+    "Opt into dated API changes released on or before this YYYY-MM-DD (defaults to SECLAI_API_VERSION; omitted means the account default)."
+  ).option(
+    "--allow-unknown-api-version",
+    "Send an --api-version this CLI was not built against instead of rejecting it."
   ).option(
     "--compact",
     "Output compact JSON (no indentation)."
@@ -2767,6 +3337,7 @@ Environment:
   SECLAI_API_URL      Override API base URL (default: https://api.seclai.com)
   SECLAI_PROFILE      Default SSO profile (alternative to --profile)
   SECLAI_CONFIG_DIR   Config directory (alternative to --config-dir)
+  SECLAI_API_VERSION  Dated API version (alternative to --api-version)
 
 Examples:
   seclai agents list
@@ -2786,6 +3357,13 @@ Examples:
   program.exitOverride();
   program.hook("preAction", (thisCommand) => {
     const globalOpts = thisCommand.opts();
+    if (typeof globalOpts.apiVersion === "string" && globalOpts.apiVersion.trim().length === 0) {
+      warnDeprecated(
+        rt,
+        "--api-version was given an empty value and is being ignored. Pass a YYYY-MM-DD date, or omit the flag to use the account default.",
+        "rejected"
+      );
+    }
     rt.compact = Boolean(globalOpts.compact);
   });
   register(program, rt);
@@ -2805,6 +3383,8 @@ Examples:
   register15(program, rt);
   register16(program, rt);
   register17(program, rt);
+  register18(program, rt);
+  register19(program, rt);
   return program;
 }
 async function runCli(argv, rt = defaultRuntime()) {
@@ -2851,4 +3431,3 @@ export {
   createProgram,
   runCli
 };
-//# sourceMappingURL=cli.js.map