@seclai/cli 1.4.0 → 1.5.0

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command as Command3 } 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";
@@ -78,6 +79,10 @@ function createClient(opts) {
   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 version = opts.apiVersion ?? (envVersion && envVersion.length > 0 ? envVersion : void 0);
+  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 +92,10 @@ function printJson(rt, value) {
   rt.writeOut(`${JSON.stringify(value, null, indent)}
 `);
 }
+function warnDeprecated(rt, message) {
+  rt.writeErr(`warning: ${message} This will be rejected in a future release.
+`);
+}
 function printError(rt, err) {
   if (err instanceof SeclaiAPIValidationError) {
     rt.writeErr(`${err.name}: ${err.message}
@@ -134,6 +143,25 @@ async function run(rt, main) {
     rt.setExitCode(1);
   }
 }
+function parseNumber(value) {
+  const parsed = value.trim() === "" ? Number.NaN : Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new InvalidArgumentError("Expected a number.");
+  }
+  return parsed;
+}
+function withLimitOption(cmd) {
+  return cmd.option("--limit <n>", "Page size.", parseNumber);
+}
+function withOffsetListOptions(cmd) {
+  return withLimitOption(cmd).option("--offset <n>", "Number of items to skip.", parseNumber);
+}
+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 +204,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 +237,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 +318,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 +335,14 @@ 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}.`
+      );
       const client = createClient(program.opts());
-      await client.deleteAgentRun(runId);
+      await client.cancelAgentRun(runId);
       printJson(rt, { ok: true });
     });
   });
@@ -398,10 +463,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,7 +487,7 @@ 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).action(async (agentId, runId, opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listRunEvaluationResults(agentId, runId, listOpts(opts)));
@@ -735,10 +810,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 +856,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 +869,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 +882,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)));
@@ -1002,12 +1083,20 @@ 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.").option(
+    "--severity <severity>",
+    "Deprecated and ignored \u2014 GET /alerts declares no severity filter. Filter with jq instead."
+  ).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;
+      if (opts.severity !== void 0) {
+        warnDeprecated(
+          rt,
+          `'alerts list --severity' is ignored \u2014 the API has no severity filter, so it never filtered anything. Filter client-side, e.g. | jq '[.data[] | select(.severity == "high")]'.`
+        );
+      }
       printJson(rt, await client.listAlerts(o));
     });
   });
@@ -1044,7 +1133,7 @@ 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).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listAlertConfigs(listOpts(opts)));
@@ -1093,19 +1182,203 @@ function register9(program, rt) {
   });
 }
 
-// src/commands/models.ts
+// src/commands/email.ts
 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.").requiredOption("--kind <kind>", "'vanity' (a subdomain of seclai.com) or 'custom' (your own domain).").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'.").option("--match-type <type>", "'address' or 'domain'.", "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.").argument("<mode>", "One of 'disabled', 'input', or '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
+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 () => {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new Error(`Expected an API version as YYYY-MM-DD, got "${date}".`);
+      }
+      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,7 +1386,7 @@ 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).action(async (opts) => {
     await run(rt, async () => {
       const client = createClient(program.opts());
       printJson(rt, await client.listModelAlerts(listOpts(opts)));
@@ -1146,15 +1419,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,8 +1460,9 @@ 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 } 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 };
@@ -1197,10 +1471,20 @@ function register11(program, rt) {
       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 Option("--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 +1562,137 @@ 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) |
+
+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,353 +1700,636 @@ 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"
 
-### Embedding migration
+seclai ai memory-history
+seclai ai accept <conversationId> --json '{"accepted":true}'
+seclai ai decline <conversationId>
+seclai ai memory-accept <conversationId> --json '{"accepted":true}'
 
-\`\`\`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 feedback --json '{"feedback":"The response was helpful"}'
 \`\`\`
 
-### Contents (indexed content)
+## The generate-then-accept cycle
+
+Every assistant command returns a *proposal* with a conversation ID. Nothing is
+created until you accept it:
 
 \`\`\`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]
-seclai contents replace-text <contentVersionId> --json '{"text":"Replacement text","title":"Updated"}'
-seclai contents embeddings <contentVersionId> [--page N] [--limit N]
+seclai ai kb --user-input "Create a support knowledge base"
+# read the proposal, note the conversation id
+seclai ai accept <conversationId> --json '{"accepted":true}'
 \`\`\`
 
-### Knowledge bases
+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
+
+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 kb list [--page N] [--limit N] [--sort field] [--order asc|desc]
-seclai kb create --json '{"name":"Support KB","description":"Customer support articles"}'
-seclai kb get <kbId>
-seclai kb update <kbId> --json '{"name":"Updated KB"}'
-seclai kb delete <kbId>
+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>
 \`\`\`
 
-### Memory banks
+\`GET /alerts\` declares no severity filter. \`--severity\` still parses, but it is
+ignored with a warning and will be removed \u2014 it never filtered anything. Filter
+client-side instead:
 
 \`\`\`bash
-seclai memory list [--page N] [--limit N] [--sort field] [--order asc|desc]
-# type: "conversation" (chat history) or "general" (structured facts)
-seclai memory create --json '{"name":"Chat Memory","type":"conversation"}'
-seclai memory get <memoryBankId>
-seclai memory update <memoryBankId> --json '{"name":"Renamed"}'
-seclai memory delete <memoryBankId>
+seclai alerts list | jq '[.data[] | select(.severity == "high")]'
 \`\`\`
 
-### Memory bank utilities
+## Alert configurations
 
 \`\`\`bash
-seclai memory stats <memoryBankId>
-seclai memory agents <memoryBankId>
-seclai memory compact <memoryBankId>
-seclai memory delete-source <memoryBankId>
-seclai memory templates
-seclai memory test-compaction <memoryBankId> --json '{"prompt":"Summarize the conversation"}'
-seclai memory test-compaction-standalone --json '{"prompt":"Summarize the conversation"}'
+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>
 \`\`\`
 
-### Memory bank AI
+## Organization preferences
 
 \`\`\`bash
-seclai memory ai generate --user-input "Configure compaction for chat memory"
-seclai memory ai last
-seclai memory ai accept <conversationId> --json '{"accepted":true}'
+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
 \`\`\`
 
-### Evaluations \u2014 criteria
+\`--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 list <agentId> [--page N] [--limit N]
-seclai evals criteria create <agentId> --json '{"name":"Response Quality","description":"...","eval_type":"llm_judge"}'
+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 Criteria"}'
+seclai evals criteria update <criteriaId> --json '{"name":"Updated Name"}'
 seclai evals criteria delete <criteriaId>
-seclai evals criteria summary <criteriaId>
 \`\`\`
 
-### Evaluations \u2014 results & runs
+\`--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 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>
 \`\`\`
+` },
+  { name: "references/knowledge.md", content: `# Sources, content, knowledge bases and memory banks
 
-### Solutions
+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 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 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>
 \`\`\`
 
-### Solution links
+\`source\` is accepted as an alias for \`sources\`.
+
+## Source uploads
 
 \`\`\`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 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"}'
 \`\`\`
 
-### Solution conversations & AI
+## Source exports
 
 \`\`\`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}'
+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 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>
+\`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>
 \`\`\`
 
-### Alerts
+## Contents (indexed content)
 
 \`\`\`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 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]
+seclai contents replace-text <contentVersionId> --json '{"text":"Replacement text","title":"Updated"}'
+seclai contents embeddings <contentVersionId> [--page N] [--limit N]
 \`\`\`
 
-### Alert configurations
+\`--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 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 kb list [--page N] [--limit N] [--sort field] [--order asc|desc]
+seclai kb create --json '{"name":"Support KB","description":"Customer support articles"}'
+seclai kb get <kbId>
+seclai kb update <kbId> --json '{"name":"Updated KB"}'
+seclai kb delete <kbId>
 \`\`\`
 
-### Alert preferences
+## Memory banks
 
 \`\`\`bash
-seclai alerts prefs list
-seclai alerts prefs update <organizationId> <alertType> --json '{"enabled":true}'
+seclai memory list [--page N] [--limit N] [--sort field] [--order asc|desc]
+# type: "conversation" (chat history) or "general" (structured facts)
+seclai memory create --json '{"name":"Chat Memory","type":"conversation"}'
+seclai memory get <memoryBankId>
+seclai memory update <memoryBankId> --json '{"name":"Renamed"}'
+seclai memory delete <memoryBankId>
 \`\`\`
 
-### Governance AI
+### Utilities
 
 \`\`\`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 memory stats <memoryBankId>
+seclai memory agents <memoryBankId>        # agents using this bank
+seclai memory compact <memoryBankId>
+seclai memory delete-source <memoryBankId>
+seclai memory templates
+seclai memory test-compaction <memoryBankId> --json '{"prompt":"Summarize the conversation"}'
+seclai memory test-compaction-standalone --json '{"prompt":"Summarize the conversation"}'
 \`\`\`
 
-### Model alerts
+Both \`test-compaction\` commands are dry runs \u2014 they show what compaction would
+produce without writing to the bank.
+
+### Memory bank AI
+
+\`\`\`bash
+seclai memory ai generate --user-input "Configure compaction for chat memory"
+seclai memory ai last
+seclai memory ai accept <conversationId> --json '{"accepted":true}'
+\`\`\`
+
+## Example: create a source and upload content
+
+\`\`\`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>
+\`\`\`
+` },
+  { name: "references/models.md", content: `# Models
+
+The model catalog, media-generation tiers, model-catalog alerts, recommendations
+and the playground.
+
+## Catalog
+
+\`\`\`bash
+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
+\`\`\`
+
+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
 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
+\`\`\`
+
+These are catalog alerts \u2014 deprecations, price changes, new models \u2014 not the
+account alerts in [alerts.md](alerts.md).
+
+## Recommendations
+
+\`\`\`bash
 seclai models recommendations <modelId>
 \`\`\`
 
-### Search
+Suggests replacements for a model, which is how you act on a deprecation alert.
+
+## Playground experiments
 
 \`\`\`bash
-seclai search --query "deployment guide" [--limit N] [--entity-type <type>]
+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
 \`\`\`
 
-### AI assistant (global)
+\`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 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 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
 \`\`\`
 
-### Skills
+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
-# 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 configure sso [--profile-name <name>]   # interactive: domain, client ID, region, account ID
+seclai configure list                          # every configured profile
 \`\`\`
 
-### MCP server
+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
-# configure MCP server access in AI coding tool config files
+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
+\`\`\`
+
+\`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
+# 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 .]
 
-# show the MCP config JSON snippet
+# print the config JSON for manual setup
 seclai mcp show [--key <apiKey>]
 \`\`\`
 
-## Example: Create a source and upload content
+## Skill files
 
 \`\`\`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>
+# 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 .]
 \`\`\`
 
-## Example: Set up a knowledge base with an agent
+With no \`--tool\`, the target is detected from the directory structure.
+
+## Shell completion
 
 \`\`\`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 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
 
-## Example: Evaluate agent quality
+Solutions group agents, knowledge bases and sources into one deliverable.
+Governance defines the policies applied to agent input and output.
+
+## Solutions
 
 \`\`\`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 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>
 \`\`\`
 
-## Example: Solution with linked resources
+## Linking resources
 
 \`\`\`bash
-seclai solutions create --json '{"name":"Customer Support"}'
-seclai solutions link <solutionId> --agents '["<agentId>"]' --kb '["<kbId>"]' --sources '["<sourceId>"]'
-seclai solutions get <solutionId>
+# 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: Memory-powered agent
+## Conversations
 
 \`\`\`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}'
+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: Governance policy setup
+## Solution AI
 
 \`\`\`bash
-seclai governance ai generate --user-input "Create a content safety policy that blocks harmful outputs"
+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>
+\`\`\`
+
+\`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
+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>
 \`\`\`
 
-## Specific topics
+A generated policy is a proposal until accepted \u2014 \`generate\` alone changes
+nothing.
 
-* **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
+## Example: solution with linked resources
+
+\`\`\`bash
+seclai solutions create --json '{"name":"Customer Support"}'
+seclai solutions link <solutionId> --agents '["<agentId>"]' --kb '["<kbId>"]' --sources '["<sourceId>"]'
+seclai solutions get <solutionId>
+\`\`\`
+
+## 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>
+\`\`\`
+` },
+  { name: "references/streaming.md", content: `# Streaming Agent Runs
 
 ## Modes
 
@@ -1750,8 +2381,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 +2398,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 +2433,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 +2478,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 +2579,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."
@@ -2055,15 +2645,16 @@ _seclai_completions() {
   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"
+  commands="agents sources contents kb memory evals solutions governance alerts email models search docs me api-version ai skills mcp completion auth configure 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 ;;
+        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 ;;
+        triggers) COMPREPLY=( $(compgen -W "email-config" -- "$cur") ); return ;;
+        *)        COMPREPLY=( $(compgen -W "list create get update delete disable enable callers triggers run runs def export preview-import upload-input input-status attachment-references ai" -- "$cur") ); return ;;
       esac ;;
     sources|source)
       case "\${COMP_WORDS[2]}" in
@@ -2101,12 +2692,24 @@ _seclai_completions() {
         prefs)   COMPREPLY=( $(compgen -W "list update" -- "$cur") ); return ;;
         *)       COMPREPLY=( $(compgen -W "list get status comment subscribe unsubscribe configs prefs" -- "$cur") ); return ;;
       esac ;;
+    email)
+      case "\${COMP_WORDS[2]}" in
+        domains) COMPREPLY=( $(compgen -W "list add remove verify set-primary use-shared test-email dmarc" -- "$cur") ); return ;;
+        blocked) COMPREPLY=( $(compgen -W "list add remove auto-block-mode" -- "$cur") ); return ;;
+        inbound) COMPREPLY=( $(compgen -W "status rejections cancel-queued resume" -- "$cur") ); return ;;
+        optouts) COMPREPLY=( $(compgen -W "list remove" -- "$cur") ); return ;;
+        *)       COMPREPLY=( $(compgen -W "domains blocked inbound optouts" -- "$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 ;;
+        *)           COMPREPLY=( $(compgen -W "list get tiers alerts recommendations experiments" -- "$cur") ); return ;;
       esac ;;
+    docs) COMPREPLY=( $(compgen -W "search" -- "$cur") ); return ;;
+    api-version) COMPREPLY=( $(compgen -W "get set clear" -- "$cur") ); return ;;
+    auth) COMPREPLY=( $(compgen -W "login logout status refresh" -- "$cur") ); return ;;
+    configure) COMPREPLY=( $(compgen -W "sso list" -- "$cur") ); return ;;
     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 ;;
@@ -2134,17 +2737,28 @@ _seclai() {
     'solutions:Manage solutions'
     'governance:Governance AI assistant'
     'alerts:Manage alerts and alert configurations'
-    'models:Model alerts and recommendations'
+    'email:Agent email domains, blocklist, inbound health, opt-outs'
+    'models:Models, model alerts, recommendations, experiments'
     'search:Search across Seclai resources'
+    'docs:Search the Seclai documentation'
+    'me:Show the authenticated user and organizations'
+    'api-version:Read or pin the dated API version'
     'ai:Top-level AI assistant'
     'skills:Install skill files for AI coding tools'
     'mcp:Configure the Seclai MCP server'
     'completion:Generate shell completion scripts'
+    'auth:SSO authentication'
+    'configure:Manage SSO profiles'
     'help:Display help for command'
   )
 
   _arguments -C \\
     '--api-key[Seclai API key]:key' \\
+    '--profile[SSO profile name]:name' \\
+    '--account-id[Account ID (X-Account-Id header)]:id' \\
+    '--config-dir[Config directory]:path' \\
+    '--api-version[Dated API version (YYYY-MM-DD)]:date' \\
+    '--allow-unknown-api-version[Permit an unrecognized --api-version]' \\
     '--compact[Output compact JSON]' \\
     '-V[Output version]' \\
     '-h[Display help]' \\
@@ -2156,7 +2770,7 @@ _seclai() {
     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)
+          local -a sub=(list create get update delete disable enable callers triggers 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)
@@ -2182,8 +2796,23 @@ _seclai() {
         alerts)
           local -a sub=(list get status comment subscribe unsubscribe configs prefs)
           _describe 'subcommand' sub ;;
+        email)
+          local -a sub=(domains blocked inbound optouts)
+          _describe 'subcommand' sub ;;
         models)
-          local -a sub=(alerts recommendations experiments)
+          local -a sub=(list get tiers alerts recommendations experiments)
+          _describe 'subcommand' sub ;;
+        docs)
+          local -a sub=(search)
+          _describe 'subcommand' sub ;;
+        api-version)
+          local -a sub=(get set clear)
+          _describe 'subcommand' sub ;;
+        auth)
+          local -a sub=(login logout status refresh)
+          _describe 'subcommand' sub ;;
+        configure)
+          local -a sub=(sso list)
           _describe 'subcommand' sub ;;
         ai)
           local -a sub=(feedback kb source solution memory memory-history accept decline memory-accept)
@@ -2206,7 +2835,7 @@ _seclai "$@"
 var FISH = `# seclai fish completion \u2014 save to ~/.config/fish/completions/seclai.fish
 #   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
+set -l top agents sources contents kb memory evals solutions governance alerts email models search docs me api-version ai skills mcp completion auth configure help
 
 # Top-level
 complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "agents" -d "Manage agents"
@@ -2218,15 +2847,21 @@ complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "evals" -d "E
 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 "email" -d "Agent email"
+complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "models" -d "Models and 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 "docs" -d "Search documentation"
+complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "me" -d "Authenticated user"
+complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "api-version" -d "Dated API version"
 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"
+complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "auth" -d "SSO authentication"
+complete -c seclai -n "not __fish_seen_subcommand_from $top" -f -a "configure" -d "Manage SSO profiles"
 
 # 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"
+complete -c seclai -n "__fish_seen_subcommand_from agents; and not __fish_seen_subcommand_from list create get update delete disable enable callers triggers run runs def export preview-import upload-input input-status attachment-references ai" -f -a "list create get update delete disable enable callers triggers 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"
@@ -2252,8 +2887,23 @@ complete -c seclai -n "__fish_seen_subcommand_from governance; and not __fish_se
 # 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"
 
+# email
+complete -c seclai -n "__fish_seen_subcommand_from email; and not __fish_seen_subcommand_from domains blocked inbound optouts" -f -a "domains blocked inbound optouts"
+
 # models
-complete -c seclai -n "__fish_seen_subcommand_from models; and not __fish_seen_subcommand_from alerts recommendations experiments" -f -a "alerts recommendations experiments"
+complete -c seclai -n "__fish_seen_subcommand_from models; and not __fish_seen_subcommand_from list get tiers alerts recommendations experiments" -f -a "list get tiers alerts recommendations experiments"
+
+# docs
+complete -c seclai -n "__fish_seen_subcommand_from docs; and not __fish_seen_subcommand_from search" -f -a "search"
+
+# api-version
+complete -c seclai -n "__fish_seen_subcommand_from api-version; and not __fish_seen_subcommand_from get set clear" -f -a "get set clear"
+
+# auth
+complete -c seclai -n "__fish_seen_subcommand_from auth; and not __fish_seen_subcommand_from login logout status refresh" -f -a "login logout status refresh"
+
+# configure
+complete -c seclai -n "__fish_seen_subcommand_from configure; and not __fish_seen_subcommand_from sso list" -f -a "sso list"
 
 # 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"
@@ -2269,11 +2919,16 @@ complete -c seclai -n "__fish_seen_subcommand_from completion; and not __fish_se
 
 # Global options
 complete -c seclai -l api-key -d "Seclai API key"
+complete -c seclai -l profile -d "SSO profile name"
+complete -c seclai -l account-id -d "Account ID (X-Account-Id header)"
+complete -c seclai -l config-dir -d "Config directory"
+complete -c seclai -l api-version -d "Dated API version (YYYY-MM-DD)"
+complete -c seclai -l allow-unknown-api-version -d "Permit an unrecognized --api-version"
 complete -c seclai -l compact -d "Output compact JSON"
 complete -c seclai -s V -l version -d "Output version"
 `;
 var SCRIPTS = { bash: BASH, zsh: ZSH, fish: FISH };
-function register15(program, rt) {
+function register17(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];
     if (!script) {
@@ -2447,7 +3102,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 +3276,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 () => {
@@ -2734,8 +3389,15 @@ function escapeRegExp(s) {
 }
 
 // src/cli.ts
+var VALUED_GLOBAL_OPTIONS = [
+  ["apiKey", "--api-key", "reject", "Pass a key, or omit the flag to use SECLAI_API_KEY or SSO."],
+  ["profile", "--profile", "reject", "Pass a profile name, or omit the flag to use the default profile."],
+  ["accountId", "--account-id", "reject", "Pass an account ID, or omit the flag to use the default org."],
+  ["configDir", "--config-dir", "reject", "Pass a directory, or omit the flag to use ~/.seclai."],
+  ["apiVersion", "--api-version", "warn", "Pass a YYYY-MM-DD date, or omit the flag to use the account default."]
+];
 function createProgram(rt = defaultRuntime()) {
-  const program = new Command();
+  const program = new Command3();
   const cliVersion = getCliVersion();
   program.name("seclai").description(
     `Seclai Command Line Interface (v${cliVersion})
@@ -2755,6 +3417,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 +3435,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 +3455,15 @@ Examples:
   program.exitOverride();
   program.hook("preAction", (thisCommand) => {
     const globalOpts = thisCommand.opts();
+    for (const [key, flag, policy, hint] of VALUED_GLOBAL_OPTIONS) {
+      const value = globalOpts[key];
+      if (typeof value !== "string" || value.length > 0) continue;
+      if (policy === "reject") {
+        throw new Error(`${flag} was given an empty value. ${hint}`);
+      }
+      delete globalOpts[key];
+      warnDeprecated(rt, `${flag} was given an empty value and is being ignored. ${hint}`);
+    }
     rt.compact = Boolean(globalOpts.compact);
   });
   register(program, rt);
@@ -2805,6 +3483,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()) {