@typeship-ax/cli 0.6.0

package/src/cli.ts

@@ -0,0 +1,2695 @@
+#!/usr/bin/env node
+// typeship — command-line client. Generated by typeship — https://typeship.dev
+// Flags-only for API commands (CI-safe); `login` is the one interactive
+// exception (hidden prompt on a TTY, --with-token/--token for scripts).
+// Prints raw JSON to stdout; errors as JSON on stderr.
+// Exit codes: 0 success, 1 API/transport error, 2 usage error.
+
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TypeshipClient, formatDebugEvent, type DebugEvent } from "./index.js";
+import { GLOBALS, OPS, buildArgs, findOp, missingRequired, type OpSpec, type ParamSpec } from "./ops.js";
+import {
+  MCP_CLIENTS, agentGuide, agentBlock, agentInstructionsFile, agentMode, bundleProperty, claimProperty, classifyApiError, collectionProperty, detectHarness, envelope,
+  exitCodeFor, findMcpClient, installSkills, mcpConfigured, pendingClaims, recordClaim, summarizeDoctor, upsertAgentBlock, writeBundle, writeMcpConfig,
+  type AgentContext, type CommandSummary, type DoctorCheck, type EnvelopeInput, type IssueCode, type McpEntry, type McpWriteResult,
+} from "./cli-agent.js";
+import { relativeDate } from "./dates.js";
+
+
+const BIN = "typeship";
+const DEFAULT_BASE_URL = "https://typeship.dev/api/v1";
+const AUTH_SCALARS: { option: string; flag: string; env: string }[] = [{"option":"bearerToken","flag":"token","env":"TYPESHIP_TOKEN"}];
+const BASIC: { envUser: string; envPass: string } | null = null;
+const EXCLUDED_OPS = 0;
+const VERSION = "0.6.0";
+const API_VERSION = "0.6.0";
+const SPEC_FORMAT = "openapi";
+const WHOAMI: { resource: string; method: string } | null = {"resource":"account","method":"retrieve"};
+const ENVIRONMENTS: Record<string, string> = {};
+const HAS_MCP = false;
+const PKG_NAME = "@typeship-ax/cli";
+const UPDATE_NOTICE = false;
+const API_DESCRIPTION: string | null = "Generate production SDKs, CLIs, and MCP servers from an OpenAPI or\nGraphQL spec, and keep every selected output current.\n\nEvery operation but one requires an API key, created in the console and\nsent as `Authorization: Bearer ak_...`. A browser session is not a\ncredential for this API. The exception is POST /generate, which works\nanonymously with the free plan's limits.\n";
+const DOCS_URL_DEFAULT: string | null = "https://typeship.dev";
+const RELAY: { mintUrl: string; project: string } | null = null;
+const SUPPORT_URL: string | null = null;
+const OAUTH_TOKEN_URL: string | null = null;
+const OAUTH_CLIENT_ID: string | null = null;
+const OAUTH_SCOPES: string[] = [];
+const OAUTH_TOKEN_PARAMS: Record<string, string> = {};
+const MCP_URL: string | null = "https://typeship.dev/mcp";
+const SKILLS_REPO: string | null = "typeship-ax/skills";
+const CLI_AUTH_URL: string | null = "https://typeship.dev/api/auth/cli";
+const ENV_PREFIX = "TYPESHIP";
+const API_TITLE = "typeship";
+
+interface Parsed {
+  positionals: string[];
+  flags: Map<string, string | boolean>;
+  /** Every value of a flag given more than once (`--ids a --ids b`);
+   * flags keeps the last one for scalar callers. */
+  repeated: Map<string, string[]>;
+  help: boolean;
+}
+
+/** Flags that never take a value, so they don't swallow the next positional
+ * (`--non-interactive accounts list`). Built-in commands' own switches
+ * (`mcp --cursor`, `upgrade --check`) count only under that command, so an
+ * API parameter with the same name (`accounts list --cursor <c>`) still
+ * takes its value. Boolean API parameters are recognized once the command
+ * is known. */
+const CORE_BOOLEAN_FLAGS = new Set(["all", "version", "non-interactive", "debug", "validate", "yes", "force", "json"]);
+const BUILTIN_BOOLEAN_FLAGS: Record<string, string[]> = {
+  login: ["with-token", "no-browser"],
+  upgrade: ["check"],
+  mcp: ["claude", "cursor", "claude-desktop", "codex", "vscode", "windsurf", "gemini", "opencode", "zed", "all", "read-only"],
+  docs: ["web", "schema"],
+  init: ["all", "yes", "no-skills", "no-mcp", "no-agents-md"],
+  auth: ["live"],
+  doctor: [],
+};
+
+function isBooleanFlag(name: string, positionals: string[]): boolean {
+  if (CORE_BOOLEAN_FLAGS.has(name)) return true;
+  const first = positionals[0];
+  if (first !== undefined && (BUILTIN_BOOLEAN_FLAGS[first] ?? []).includes(name)) return true;
+  if (positionals.length >= 2) {
+    const op = findOp(positionals[0]!, positionals[1]!);
+    if (op) return op.params.some((p) => p.flag === name && p.type === "boolean");
+  }
+  return false;
+}
+
+function parseArgv(argv: string[]): Parsed {
+  const positionals: string[] = [];
+  const flags = new Map<string, string | boolean>();
+  const repeated = new Map<string, string[]>();
+  let help = false;
+  const setFlag = (name: string, value: string | boolean) => {
+    if (typeof value === "string" && flags.has(name)) {
+      const previous = flags.get(name);
+      const list = repeated.get(name) ?? (typeof previous === "string" ? [previous] : []);
+      list.push(value);
+      repeated.set(name, list);
+    }
+    flags.set(name, value);
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--help" || arg === "-h") { help = true; continue; }
+    if (arg === "-v") { flags.set("version", true); continue; }
+    if (arg === "-y") { flags.set("yes", true); continue; }
+    if (arg === "-k" && argv[i + 1] !== undefined) { setFlag("k", argv[i + 1]!); i++; continue; }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        setFlag(arg.slice(2, eq), arg.slice(eq + 1));
+      } else if (isBooleanFlag(arg.slice(2), positionals)) {
+        const next = argv[i + 1];
+        if (next === "true" || next === "false") { setFlag(arg.slice(2), next); i++; }
+        else flags.set(arg.slice(2), true);
+      } else {
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          setFlag(arg.slice(2), next);
+          i++;
+        } else {
+          flags.set(arg.slice(2), true);
+        }
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags, repeated, help };
+}
+
+/** --mode agent > TYPESHIP_MODE=agent > no terminal on stdin and stdout. In
+ * agent mode nothing prompts and no browser opens; every stop is a JSON
+ * envelope with next_steps. See cli-agent.ts. */
+function isAgentMode(parsed: Parsed): boolean {
+  return agentMode({
+    flagMode: parsed.flags.get("mode"),
+    envMode: process.env["TYPESHIP_MODE"],
+    stdoutIsTTY: process.stdout.isTTY === true,
+    stdinIsTTY: process.stdin.isTTY === true,
+  });
+}
+
+/** The explicit switch only: --non-interactive or TYPESHIP_NON_INTERACTIVE=1. */
+function explicitNonInteractive(parsed: Parsed): boolean {
+  return parsed.flags.get("non-interactive") === true || process.env["TYPESHIP_NON_INTERACTIVE"] === "1";
+}
+
+/** Explicit switch, or agent mode: nothing prompts, no browser opens. */
+function nonInteractive(parsed: Parsed): boolean {
+  return explicitNonInteractive(parsed) || isAgentMode(parsed);
+}
+
+/** --yes / --force (or TYPESHIP_YES=1): skip confirmations, including destructive ones. */
+function assumeYes(parsed: Parsed): boolean {
+  return parsed.flags.get("yes") === true || parsed.flags.get("force") === true || process.env["TYPESHIP_YES"] === "1";
+}
+
+// ---------------------------------------------------------------------------
+// color — human surfaces only (help, stderr hints); JSON is never colored
+// ---------------------------------------------------------------------------
+
+let COLOR_OUT = false;
+let COLOR_ERR = false;
+
+/** --color on|off|auto (Stripe-style; explicit beats NO_COLOR beats TTY). */
+function colorEnabled(stream: { isTTY?: boolean }, parsed: Parsed): boolean {
+  const flag = parsed.flags.get("color");
+  if (flag === "off" || flag === "never") return false;
+  if (flag === "on" || flag === "always") return true;
+  if (flag !== undefined && flag !== true && flag !== "auto") {
+    fail(2, "--color expects on, off, or auto");
+  }
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") return false;
+  return stream.isTTY === true && process.env.TERM !== "dumb";
+}
+
+const ANSI = { bold: "1", dim: "2", cyan: "36", yellow: "33", green: "32", red: "31" } as const;
+
+function paintOut(code: keyof typeof ANSI, text: string): string {
+  return COLOR_OUT ? "\x1b[" + ANSI[code] + "m" + text + "\x1b[0m" : text;
+}
+
+function paintErr(code: keyof typeof ANSI, text: string): string {
+  return COLOR_ERR ? "\x1b[" + ANSI[code] + "m" + text + "\x1b[0m" : text;
+}
+
+function out(value: unknown): void {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+
+/** --fields a,b.c: the dotted paths to keep in API results (null = everything). Set in main(). */
+let FIELDS: string[][] | null = null;
+
+/** Keep only FIELDS of a result: arrays item by item, objects by dotted path; scalars untouched. */
+function project(value: unknown): unknown {
+  if (FIELDS === null) return value;
+  if (Array.isArray(value)) return value.map(project);
+  if (value === null || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const path of FIELDS) {
+    let cursor: unknown = value;
+    for (const key of path) {
+      if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) { cursor = undefined; break; }
+      cursor = (cursor as Record<string, unknown>)[key];
+    }
+    if (cursor === undefined) continue;
+    let target = out;
+    for (const key of path.slice(0, -1)) {
+      const next = target[key];
+      if (next === undefined || next === null || typeof next !== "object" || Array.isArray(next)) target[key] = {};
+      target = target[key] as Record<string, unknown>;
+    }
+    target[path[path.length - 1]!] = cursor;
+  }
+  return out;
+}
+
+/** Thrown after scheduling exit so sync callers stop; main() swallows it. */
+class ExitPending extends Error {}
+
+/** Exit only after stdout has flushed — process.exit() mid-write truncates
+ * large payloads on pipes. */
+function flushExit(code: number): Promise<never> {
+  return new Promise(() => {
+    process.stdout.write("", () => process.exit(code));
+  });
+}
+
+/**
+ * Every failure is one JSON envelope on stderr:
+ *   {status: "error"|"action_required", issues: [{code, message}], docs_url?, next_steps: [], detail?}
+ * Branch on issues[].code (stable), never on the message. Exit 1 when the
+ * request or command failed, 2 for usage (wrong flags, missing arguments,
+ * a confirmation the caller must give).
+ */
+function failWith(input: EnvelopeInput): never {
+  const body = envelope({ docsUrl: DOCS_URL_DEFAULT, ...input });
+  const code = exitCodeFor(input.code);
+  const payload = HUMAN_ERRORS ? humanError(body, code) : JSON.stringify(body, null, 2) + "\n";
+  process.stderr.write(payload, () => process.exit(code));
+  throw new ExitPending();
+}
+
+/** Set once argv is parsed: a person at a terminal reads prose; pipes, CI,
+ * and agents get the JSON envelope, byte for byte. */
+let HUMAN_ERRORS = false;
+
+/**
+ * The same envelope as prose for a terminal:
+ *   acme: No such account
+ *     Check the resource id; list the resource first.
+ *     NOT_FOUND · HTTP 404 · exit 1 · pipe stderr or --mode agent for JSON
+ */
+function humanError(body: ReturnType<typeof envelope>, code: number): string {
+  const lines: string[] = [];
+  const issue = body.issues[0];
+  lines.push(paintErr("red", BIN + ":") + " " + (issue?.message ?? "failed"));
+  for (const extra of body.issues.slice(1)) lines.push("  " + extra.message);
+  for (const step of body.next_steps ?? []) lines.push("  " + step);
+  const detail = body.detail as { status?: number; body?: unknown; violations?: unknown } | undefined;
+  if (detail?.violations !== undefined) {
+    for (const v of (detail.violations as { path?: string; message?: string }[]).slice(0, 8)) lines.push("  " + paintErr("dim", (v.path ? v.path + ": " : "") + (v.message ?? "")));
+  } else if (detail?.body !== undefined) {
+    // The API's own body, when the message above did not already come from
+    // it; the request id always, for support tickets.
+    const compact = typeof detail.body === "string" ? detail.body : JSON.stringify(detail.body);
+    const firstWords = (issue?.message ?? "").slice(0, 40);
+    if (compact && compact !== "{}" && !(firstWords && compact.includes(firstWords))) lines.push("  " + paintErr("dim", "API said: " + (compact.length > 300 ? compact.slice(0, 297) + "…" : compact)));
+    const requestId = (detail.body as { request_id?: unknown; requestId?: unknown } | null)?.request_id ?? (detail.body as { requestId?: unknown } | null)?.requestId;
+    if (typeof requestId === "string") lines.push("  " + paintErr("dim", "request id: " + requestId));
+  }
+  const tags = [issue?.code ?? "ERROR", ...(typeof detail?.status === "number" && detail.status > 0 ? ["HTTP " + detail.status] : []), "exit " + code, "pipe stderr or --mode agent for JSON"];
+  lines.push("  " + paintErr("dim", tags.join(" · ")));
+  return lines.join("\n") + "\n";
+}
+
+/** The --help a usage error points at: the command's own once one is resolved. */
+let USAGE_HINT = BIN + " --help";
+
+/** Legacy shape: exit 2 is usage, everything else is a failed command. The
+ * message states the problem; what to do next goes in next_steps (the
+ * usage pointer by default, for exit 2). */
+function fail(code: number, message: string, extra?: unknown, nextSteps?: string[]): never {
+  const usageCode: IssueCode = /^Unknown command/.test(message) ? "UNKNOWN_COMMAND"
+    : /^Unknown flag/.test(message) ? "UNKNOWN_FLAG"
+    : /^(Missing required|Expected \d+ argument)/.test(message) ? "MISSING_ARGUMENT"
+    : "INVALID_USAGE";
+  return failWith({
+    code: code === 2 ? usageCode : "COMMAND_FAILED",
+    message,
+    ...(extra !== undefined ? { detail: extra } : {}),
+    nextSteps: nextSteps ?? (code === 2 ? ["Run '" + USAGE_HINT + "' for the flags this command takes."] : []),
+  });
+}
+
+/** An SDK error result as an envelope: status-derived code, the API's body as detail, concrete next steps. */
+function failApi(error: unknown, hadCredential: boolean): never {
+  return failWith(classifyApiError(error, { bin: BIN, hadCredential, docsUrl: DOCS_URL_DEFAULT }));
+}
+
+// ---------------------------------------------------------------------------
+// credentials — written by `login`, cleared by `logout`
+// ---------------------------------------------------------------------------
+
+interface StoredCreds {
+  scalars?: Record<string, string>;
+  basic?: { username: string; password: string };
+  oauth?: { accessToken: string; refreshToken?: string; expiresAt?: number };
+  /** Set when this CLI minted the stored credential for itself (browser
+   * approval), so `logout` knows it may revoke it. A pasted key is not. */
+  minted?: { via: "browser"; key_name: string; org_id?: string };
+}
+
+function configDir(): string {
+  const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(base, BIN);
+}
+
+function credsPath(): string {
+  return join(configDir(), "credentials.json");
+}
+
+function readCreds(): StoredCreds | null {
+  try {
+    return JSON.parse(readFileSync(credsPath(), "utf8")) as StoredCreds;
+  } catch {
+    return null;
+  }
+}
+
+function writeCreds(creds: StoredCreds): void {
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(credsPath(), JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => resolve(data));
+  });
+}
+
+/** One visible line from a TTY, for yes/no confirmations. */
+function readLine(): Promise<string> {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const onData = (chunk: string) => {
+      stdin.pause();
+      stdin.off("data", onData);
+      resolve(chunk);
+    };
+    stdin.on("data", onData);
+  });
+}
+
+/** Hidden-input prompt. Login is the one interactive command; every API
+ * command stays flags-only. */
+function promptHidden(promptText: string): Promise<string> {
+  return new Promise((resolve) => {
+    process.stderr.write(promptText);
+    const stdin = process.stdin;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let value = "";
+    const onData = (chunk: string) => {
+      for (const ch of chunk) {
+        if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+          if (stdin.isTTY) stdin.setRawMode(false);
+          stdin.pause();
+          stdin.off("data", onData);
+          process.stderr.write("\n");
+          resolve(value);
+          return;
+        }
+        if (ch === "\u0003") {
+          if (stdin.isTTY) stdin.setRawMode(false);
+          process.stderr.write("\n");
+          process.exit(2);
+        }
+        if (ch === "\u007f" || ch === "\b") { value = value.slice(0, -1); continue; }
+        value += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function oauthForm(url: string, params: Record<string, string>): Promise<{ status: number; body: Record<string, unknown> | null }> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams(params).toString(),
+  });
+  let body: Record<string, unknown> | null = null;
+  try { body = await response.json() as Record<string, unknown>; } catch { /* non-JSON error body */ }
+  return { status: response.status, body };
+}
+
+/** RFC 8628 device flow: discover the device endpoint from the token URL's
+ * well-known metadata, show the code, poll until authorized. */
+async function deviceLogin(clientId: string, agent = false): Promise<void> {
+  if (!OAUTH_TOKEN_URL) fail(2, "This API declares no OAuth token URL.");
+  const origin = new URL(OAUTH_TOKEN_URL).origin;
+  let deviceEndpoint: string | undefined;
+  let tokenEndpoint = OAUTH_TOKEN_URL;
+  for (const wellKnown of ["/.well-known/oauth-authorization-server", "/.well-known/openid-configuration"]) {
+    try {
+      const response = await fetch(origin + wellKnown, { headers: { Accept: "application/json" } });
+      if (!response.ok) continue;
+      const meta = await response.json() as { device_authorization_endpoint?: string; token_endpoint?: string };
+      if (meta.device_authorization_endpoint) {
+        deviceEndpoint = meta.device_authorization_endpoint;
+        if (meta.token_endpoint) tokenEndpoint = meta.token_endpoint;
+        break;
+      }
+    } catch { /* try the next well-known path */ }
+  }
+  if (!deviceEndpoint) {
+    fail(1, "The authorization server does not advertise a device flow. Run '" + BIN + " login' with a pasted credential instead.");
+  }
+  const start = await oauthForm(deviceEndpoint!, {
+    client_id: clientId,
+    ...(OAUTH_SCOPES.length > 0 ? { scope: OAUTH_SCOPES.join(" ") } : {}),
+    ...OAUTH_TOKEN_PARAMS,
+  });
+  const startBody = start.body as { device_code?: string; user_code?: string; verification_uri?: string; verification_uri_complete?: string; interval?: number; expires_in?: number } | null;
+  if (start.status !== 200 || !startBody?.device_code) {
+    fail(1, "Device authorization failed (HTTP " + start.status + ").", start.body);
+  }
+  const uri = startBody!.verification_uri_complete ?? startBody!.verification_uri;
+  process.stderr.write("Open " + paintErr("cyan", String(uri)) + " and enter code: " + paintErr("bold", String(startBody!.user_code)) + "\n");
+  // Under an agent the same facts also go out as one JSON line (stderr,
+  // so stdout stays the single result document), for the agent to hand
+  // the URL and code to the user while this polls.
+  if (agent) process.stderr.write(JSON.stringify({ event: "device_code", verification_uri: uri, user_code: startBody!.user_code, expires_in: startBody!.expires_in ?? 900 }) + "\n");
+  let intervalMs = (startBody!.interval ?? 5) * 1000;
+  const deadline = Date.now() + (startBody!.expires_in ?? 900) * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    const poll = await oauthForm(tokenEndpoint, {
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: startBody!.device_code!,
+      client_id: clientId,
+    });
+    const tokenBody = poll.body as { access_token?: string; refresh_token?: string; expires_in?: number; error?: string } | null;
+    if (poll.status === 200 && tokenBody?.access_token) {
+      writeCreds({
+        ...(readCreds() ?? {}),
+        oauth: {
+          accessToken: tokenBody.access_token,
+          refreshToken: tokenBody.refresh_token,
+          expiresAt: tokenBody.expires_in ? Date.now() + tokenBody.expires_in * 1000 : undefined,
+        },
+      });
+      process.stderr.write(paintErr("green", "Logged in.") + "\n");
+      out({ ok: true, method: "device", credentials: credsPath() });
+      await flushExit(0);
+    }
+    const errorCode = tokenBody?.error;
+    if (errorCode === "authorization_pending") continue;
+    if (errorCode === "slow_down") { intervalMs += 5000; continue; }
+    fail(1, "Device login failed: " + (errorCode ?? "HTTP " + poll.status), poll.body);
+  }
+  fail(1, "Device login timed out before the code was entered.");
+}
+
+/** Stored OAuth access token, refreshed through the token URL when expired.
+ * A failed refresh returns the stale token; the API's 401 explains better
+ * than a local guess. */
+async function refreshedOauthToken(stored: StoredCreds): Promise<string | undefined> {
+  const oauth = stored.oauth;
+  if (!oauth) return undefined;
+  const expired = oauth.expiresAt !== undefined && Date.now() > oauth.expiresAt - 60_000;
+  if (!expired || !oauth.refreshToken || !OAUTH_TOKEN_URL) return oauth.accessToken;
+  const clientId = process.env["TYPESHIP_CLIENT_ID"] ?? OAUTH_CLIENT_ID;
+  const result = await oauthForm(OAUTH_TOKEN_URL, {
+    grant_type: "refresh_token",
+    refresh_token: oauth.refreshToken,
+    ...(clientId ? { client_id: clientId } : {}),
+  });
+  const body = result.body as { access_token?: string; refresh_token?: string; expires_in?: number } | null;
+  if (result.status === 200 && body?.access_token) {
+    const next = {
+      accessToken: body.access_token,
+      refreshToken: body.refresh_token ?? oauth.refreshToken,
+      expiresAt: body.expires_in ? Date.now() + body.expires_in * 1000 : undefined,
+    };
+    writeCreds({ ...stored, oauth: next });
+    return next.accessToken;
+  }
+  return oauth.accessToken;
+}
+
+async function storePastedToken(stored: StoredCreds, token: string): Promise<void> {
+  const first = AUTH_SCALARS[0];
+  if (!first) fail(2, "This API declares no credential the CLI can store. Use --username/--password if it uses basic auth.");
+  stored.scalars = { ...stored.scalars, [first!.option]: token };
+  writeCreds(stored);
+  out({ ok: true, method: "paste", stored_as: first!.flag, credentials: credsPath() });
+  await flushExit(0);
+}
+
+/**
+ * Browser approval (PKCE-shaped): POST <CLI_AUTH_URL>/start with an S256
+ * challenge, show the person the verification URL (open it unless we are
+ * headless or under an agent), poll <CLI_AUTH_URL>/status with the verifier
+ * until the API hands back a key minted for this CLI, store it. The key
+ * never crosses the chat: the agent relays a URL, the person clicks once.
+ */
+/** The approval endpoint follows the base URL: a preview or local deployment
+ * of the API approves its own logins. */
+function cliAuthUrl(flags: Map<string, string | boolean>): string {
+  const base = resolveBaseUrl(flags);
+  try {
+    if (CLI_AUTH_URL && DEFAULT_BASE_URL && base) {
+      const defaultOrigin = new URL(DEFAULT_BASE_URL).origin;
+      const origin = new URL(base).origin;
+      if (origin !== defaultOrigin && CLI_AUTH_URL.startsWith(defaultOrigin)) return origin + CLI_AUTH_URL.slice(defaultOrigin.length);
+    }
+  } catch { /* fall through to the configured URL */ }
+  return CLI_AUTH_URL!;
+}
+
+/** Browser approval, start to key: opens (or prints) the approval URL and
+ * polls until a person decides. Returns the minted credential; every
+ * failure exits with the envelope. Shared by `login` and `init`. */
+async function browserApprove(headless: boolean, flags: Map<string, string | boolean>): Promise<{ api_key: string; key_name: string; org_id?: string }> {
+  const first = AUTH_SCALARS[0]!;
+  const authUrl = cliAuthUrl(flags);
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const name = BIN + " CLI on " + hostname();
+  const source = headless && !process.stdin.isTTY ? "agent" : "cli";
+  let start: { session?: string; verification_url?: string; expires_in?: number; interval?: number; error?: string };
+  try {
+    const response = await fetch(authUrl + "/start", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code_challenge: challenge, name, source }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    start = await response.json() as typeof start;
+    if (!response.ok || !start.session || !start.verification_url) {
+      failWith({ code: "COMMAND_FAILED", message: "Could not start the browser login: " + (start.error ?? "HTTP " + response.status), nextSteps: ["Pass the credential directly: '" + BIN + " login --" + first.flag + " <value>'."] });
+    }
+  } catch (e) {
+    failWith({ code: "NETWORK_ERROR", message: "Could not reach " + authUrl + "/start: " + (e as Error).message, nextSteps: ["Check the network, or pass the credential directly: '" + BIN + " login --" + first.flag + " <value>'."] });
+  }
+  const url = start!.verification_url!;
+  const expiresIn = start!.expires_in ?? 600;
+  const intervalMs = Math.max(1, start!.interval ?? 3) * 1000;
+  process.stderr.write("Approve this CLI in your browser: " + paintErr("cyan", url) + "\n");
+  if (headless) {
+    process.stderr.write(JSON.stringify({ event: "browser_approval", verification_url: url, expires_in: expiresIn, note: "Give this URL to the user; polling until they approve or it expires." }) + "\n");
+  } else {
+    openInBrowser(url);
+  }
+  const deadline = Date.now() + expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    let poll: { status?: string; api_key?: string; key_name?: string; org_id?: string };
+    try {
+      const response = await fetch(authUrl + "/status", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ session: start!.session, code_verifier: verifier }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      poll = await response.json() as typeof poll;
+    } catch {
+      continue; // a blip; the next tick tries again
+    }
+    if (poll.status === "pending") continue;
+    if (poll.status === "complete" && poll.api_key) {
+      return { api_key: poll.api_key, key_name: poll.key_name ?? name, ...(poll.org_id ? { org_id: poll.org_id } : {}) };
+    }
+    if (poll.status === "denied") failWith({ status: "action_required", code: "AUTH_INVALID", message: "The request was denied in the browser.", nextSteps: ["Run '" + BIN + " login' again if that was a mistake, or pass a credential directly with --" + first.flag + "."] });
+    if (poll.status === "expired") break;
+    failWith({ code: "COMMAND_FAILED", message: "Browser login stopped: " + (poll.status ?? "unknown status"), nextSteps: ["Run '" + BIN + " login' again."] });
+  }
+  failWith({ status: "action_required", code: "TTY_REQUIRED", message: "The browser approval expired after " + expiresIn + "s without a decision.", nextSteps: ["Run '" + BIN + " login' again and approve the link within ten minutes.", "Or pass the credential directly: '" + BIN + " login --" + first.flag + " <value>'."] });
+}
+
+/** Store what the browser approval minted, marked as this CLI's own. */
+function storeMinted(stored: StoredCreds, minted: { api_key: string; key_name: string; org_id?: string }): void {
+  const first = AUTH_SCALARS[0]!;
+  stored.scalars = { ...stored.scalars, [first.option]: minted.api_key };
+  stored.minted = { via: "browser", key_name: minted.key_name, ...(minted.org_id ? { org_id: minted.org_id } : {}) };
+  writeCreds(stored);
+}
+
+async function browserLogin(stored: StoredCreds, headless: boolean, flags: Map<string, string | boolean>): Promise<void> {
+  const minted = await browserApprove(headless, flags);
+  storeMinted(stored, minted);
+  out({ ok: true, method: "browser", key_name: minted.key_name, ...(minted.org_id ? { org_id: minted.org_id } : {}), credentials: credsPath() });
+  await flushExit(0);
+}
+
+async function cmdLogin(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    const lines = [
+      BIN + " login — store credentials at " + credsPath(),
+      "",
+      ...AUTH_SCALARS.map((a) => "  " + BIN + " login --" + a.flag + " <value>"),
+      ...(CLI_AUTH_URL ? ["  " + BIN + " login                        approve in the browser: a key is minted for you (add --no-browser to print the link instead of opening it)"] : []),
+      "  " + BIN + " login --with-token           read the credential from stdin (CI)",
+      ...(OAUTH_TOKEN_URL ? ["  " + BIN + " login --client-id <id>       OAuth device flow" + (OAUTH_CLIENT_ID ? " (a default id is built in)" : "")] : []),
+      ...(BASIC ? ["  " + BIN + " login --username <u> --password <p>"] : []),
+      ...(CLI_AUTH_URL ? [] : ["  " + BIN + " login                        interactive prompt (TTY only)"]),
+      "",
+      "Precedence at request time: flags > env vars > stored credentials.",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+  const stored: StoredCreds = readCreds() ?? {};
+
+  const scalarValues: Record<string, string> = {};
+  for (const a of AUTH_SCALARS) {
+    const v = parsed.flags.get(a.flag);
+    if (typeof v === "string") scalarValues[a.option] = v;
+  }
+  const username = parsed.flags.get("username");
+  const password = parsed.flags.get("password");
+  const gotBasic = BASIC !== null && typeof username === "string" && typeof password === "string";
+  if (Object.keys(scalarValues).length > 0 || gotBasic) {
+    if (Object.keys(scalarValues).length > 0) stored.scalars = { ...stored.scalars, ...scalarValues };
+    if (gotBasic) stored.basic = { username: username as string, password: password as string };
+    writeCreds(stored);
+    out({ ok: true, method: "flags", credentials: credsPath() });
+    await flushExit(0);
+  }
+
+  if (parsed.flags.get("with-token") === true) {
+    const token = (await readStdin()).trim();
+    if (!token) fail(2, "--with-token expects the credential on stdin.");
+    await storePastedToken(stored, token);
+  }
+
+  const clientId = (typeof parsed.flags.get("client-id") === "string" ? parsed.flags.get("client-id") as string : undefined)
+    ?? process.env["TYPESHIP_CLIENT_ID"] ?? OAUTH_CLIENT_ID ?? undefined;
+  if (OAUTH_TOKEN_URL && clientId !== undefined && !explicitNonInteractive(parsed)) {
+    await deviceLogin(clientId, isAgentMode(parsed));
+  }
+
+  // Browser approval: the API mints a key for this CLI once a person
+  // approves in the browser. Works under an agent too (it prints the URL and
+  // polls); only the explicit non-interactive switch turns it off.
+  if (CLI_AUTH_URL && AUTH_SCALARS[0] && !explicitNonInteractive(parsed)) {
+    await browserLogin(stored, isAgentMode(parsed) || parsed.flags.get("no-browser") === true, parsed.flags);
+  }
+
+  if (nonInteractive(parsed) || !process.stdin.isTTY) {
+    failWith({
+      status: "action_required",
+      code: "TTY_REQUIRED",
+      message: "login needs a terminal to prompt, and there is none.",
+      nextSteps: [
+        ...AUTH_SCALARS.map((a) => "Pass the credential: '" + BIN + " login --" + a.flag + " <value>', or set " + a.env + " in the environment."),
+        "Pipe it: echo \"$TOKEN\" | " + BIN + " login --with-token",
+        ...(OAUTH_TOKEN_URL ? ["Device flow: '" + BIN + " login --client-id <id>' (prints a URL and code for the user)."] : []),
+        ...(CLI_AUTH_URL ? ["Browser approval: '" + BIN + " login --no-browser' prints a link for the user to approve and waits."] : []),
+      ],
+    });
+  }
+  const first = AUTH_SCALARS[0];
+  if (!first) fail(2, "This API declares no credential the CLI can prompt for. See '" + BIN + " login --help'.");
+  const token = (await promptHidden("Paste " + first.flag.replace(/-/g, " ") + " (input hidden): ")).trim();
+  if (!token) fail(2, "Nothing entered.");
+  await storePastedToken(stored, token);
+}
+
+async function cmdLogout(): Promise<void> {
+  const stored = readCreds();
+  const existed = existsSync(credsPath());
+  // A key this CLI minted for itself (browser approval) is revoked on the
+  // way out, so logging out ends the credential and not just the file. A
+  // pasted or CI key is someone else's to revoke, and is left alone.
+  let revoked: boolean | null = null;
+  const first = AUTH_SCALARS[0];
+  const ownKey = first && stored?.minted?.via === "browser" ? stored.scalars?.[first.option] : undefined;
+  if (ownKey && CLI_AUTH_URL) {
+    try {
+      const response = await fetch(CLI_AUTH_URL + "/revoke", { method: "POST", headers: { Authorization: "Bearer " + ownKey }, signal: AbortSignal.timeout(15_000) });
+      revoked = response.ok;
+    } catch {
+      revoked = false;
+    }
+  }
+  rmSync(credsPath(), { force: true });
+  out({ ok: true, removed: existed ? credsPath() : null, ...(revoked === null ? {} : { revoked, key_name: stored?.minted?.key_name }) });
+  await flushExit(0);
+}
+
+async function cmdWhoami(parsed: Parsed): Promise<void> {
+  const op = WHOAMI ? OPS.find((o) => o.resource === WHOAMI.resource && o.method === WHOAMI.method) : undefined;
+  if (op) {
+    const client = await makeClient(parsed.flags);
+    const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; data?: unknown; error?: unknown }>>>)[op.resource]!;
+    const result = await target[op.method]!();
+    if (result.ok) { out(result.data ?? { ok: true }); await flushExit(0); }
+    failApi(result.error, LAST_CLIENT_HAD_CREDENTIAL);
+  }
+  const stored = readCreds();
+  let source = "none";
+  if (AUTH_SCALARS.some((a) => typeof parsed.flags.get(a.flag) === "string")) {
+    source = "flags";
+  } else {
+    const envScalar = AUTH_SCALARS.find((a) => process.env[a.env] !== undefined);
+    if (envScalar) source = "env:" + envScalar.env;
+    else if (stored && (stored.scalars || stored.basic || stored.oauth)) source = "login";
+  }
+  out({ authenticated: source !== "none", source, credentials: existsSync(credsPath()) ? credsPath() : null });
+  await flushExit(source === "none" ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// config — stored defaults (base URL / named environment)
+// ---------------------------------------------------------------------------
+
+interface CliConfigFile {
+  baseUrl?: string;
+  environment?: string;
+  docsUrl?: string;
+}
+
+function configFilePath(): string {
+  return join(configDir(), "config.json");
+}
+
+function readConfig(): CliConfigFile {
+  try {
+    return JSON.parse(readFileSync(configFilePath(), "utf8")) as CliConfigFile;
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config: CliConfigFile): void {
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(configFilePath(), JSON.stringify(config, null, 2) + "\n");
+}
+
+const CONFIG_KEYS = ["base-url", "environment", "docs-url"];
+
+function configGet(config: CliConfigFile, key: string): string | undefined {
+  return key === "base-url" ? config.baseUrl : key === "environment" ? config.environment : config.docsUrl;
+}
+
+async function cmdConfig(parsed: Parsed): Promise<void> {
+  const sub = parsed.positionals[1];
+  const key = parsed.positionals[2];
+  const value = parsed.positionals[3];
+  if (parsed.help) {
+    const lines = [
+      BIN + " config — stored defaults at " + configFilePath(),
+      "",
+      "  " + BIN + " config list",
+      "  " + BIN + " config get  <" + CONFIG_KEYS.join("|") + ">",
+      "  " + BIN + " config set  base-url <url>",
+      ...(Object.keys(ENVIRONMENTS).length > 0
+        ? ["  " + BIN + " config set  environment <" + Object.keys(ENVIRONMENTS).join("|") + ">"]
+        : []),
+      "  " + BIN + " config set  docs-url <url>       docs site for '" + BIN + " docs'",
+      "  " + BIN + " config unset <" + CONFIG_KEYS.join("|") + ">",
+      "  " + BIN + " config path",
+      "",
+      "Base URL resolution: --base-url > env var > config base-url > config environment > spec default.",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+  if (sub === undefined || sub === "list") {
+    const config = readConfig();
+    out({
+      base_url: config.baseUrl ?? null,
+      environment: config.environment ?? null,
+      docs_url: config.docsUrl ?? DOCS_URL_DEFAULT,
+      environments: Object.keys(ENVIRONMENTS),
+      file: existsSync(configFilePath()) ? configFilePath() : null,
+    });
+    await flushExit(0);
+  }
+  if (sub === "path") {
+    process.stdout.write(configFilePath() + "\n");
+    await flushExit(0);
+  }
+  if (sub === "get" || sub === "set" || sub === "unset") {
+    if (key === undefined || !CONFIG_KEYS.includes(key)) {
+      fail(2, "config " + sub + " expects one of: " + CONFIG_KEYS.join(", "));
+    }
+    const config = readConfig();
+    if (sub === "get") {
+      out({ [key.replace(/-/g, "_")]: configGet(config, key) ?? null });
+      await flushExit(0);
+    }
+    if (sub === "unset") {
+      if (key === "base-url") delete config.baseUrl;
+      else if (key === "environment") delete config.environment;
+      else delete config.docsUrl;
+      writeConfig(config);
+      out({ ok: true });
+      await flushExit(0);
+    }
+    if (value === undefined) fail(2, "config set " + key + " expects a value");
+    if (key === "base-url" || key === "docs-url") {
+      try {
+        new URL(value!);
+      } catch {
+        fail(2, key + " must be a valid URL");
+      }
+      if (key === "base-url") config.baseUrl = value;
+      else config.docsUrl = value;
+    } else {
+      if (!(value! in ENVIRONMENTS)) {
+        fail(2, Object.keys(ENVIRONMENTS).length > 0
+          ? "environment must be one of: " + Object.keys(ENVIRONMENTS).join(", ")
+          : "The spec declares no named environments; use 'config set base-url' instead.");
+      }
+      config.environment = value;
+    }
+    writeConfig(config);
+    out({ ok: true, [key.replace(/-/g, "_")]: value });
+    await flushExit(0);
+  }
+  fail(2, "Unknown config command: " + String(sub) + ". Use list, get, set, unset, or path.");
+}
+
+// ---------------------------------------------------------------------------
+// mcp — wire the sibling MCP server into agent clients
+// ---------------------------------------------------------------------------
+
+function mcpServerPath(): { path: string; warning: string | null } {
+  const self = fileURLToPath(import.meta.url);
+  let path = self.replace(/cli\.(js|mjs|cjs)$/, "mcp.$1");
+  let warning: string | null = null;
+  if (self.endsWith(".ts")) {
+    path = self.replace(/([\\/])src([\\/])cli\.ts$/, "$1dist$2mcp.js");
+    if (!existsSync(path)) {
+      warning = "Build the package first (npm install && npm run build) so " + path + " exists.";
+    }
+  }
+  return { path, warning };
+}
+
+function claudeDesktopConfigPath(): string {
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "win32") {
+    return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  }
+  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "Claude", "claude_desktop_config.json");
+}
+
+/** The mcp entry for a client: the hosted endpoint when the API has one
+ * (auth env var as a reference, never a literal), else the local stdio
+ * server. --url overrides. */
+function mcpEntryFor(url: string | undefined, readOnly = false): { entry: McpEntry; warnings: string[] } {
+  const warnings: string[] = [];
+  const hosted = url ?? MCP_URL ?? undefined;
+  if (hosted) {
+    const envVar = AUTH_SCALARS[0]?.env;
+    // The hosted endpoint serves its read-only twin at <url>/readonly; a
+    // remote server of someone else's may not, so say so.
+    const target = readOnly ? hosted.replace(/\/+$/, "") + "/readonly" : hosted;
+    if (readOnly && url !== undefined && !MCP_URL) warnings.push("--read-only appended /readonly to the URL, which typeship-hosted endpoints serve; check that this server does too.");
+    return { entry: { url: target, ...(envVar ? { headers: { Authorization: "Bearer ${" + envVar + "}" } } : {}) }, warnings };
+  }
+  if (!HAS_MCP) {
+    fail(2, "This package was generated without the MCP server target. Regenerate with it, or pass --url for a remote endpoint.");
+  }
+  const server = mcpServerPath();
+  if (server.warning) warnings.push(server.warning);
+  return { entry: { command: "node", args: [server.path, ...(readOnly ? ["--read-only"] : [])] }, warnings };
+}
+
+const MCP_CLIENT_FLAGS: Record<string, string> = {
+  claude: "claude-code", cursor: "cursor", "claude-desktop": "claude-desktop", codex: "codex", vscode: "vscode",
+  windsurf: "windsurf", gemini: "gemini-cli", opencode: "opencode", zed: "zed",
+};
+
+async function cmdMcp(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    const lines = [
+      BIN + " mcp — connect this API's MCP server to agent clients",
+      "",
+      "  " + BIN + " mcp                          print the server entry JSON",
+      "  " + BIN + " mcp install --all            write it into every agent client found on this machine",
+      "  " + BIN + " mcp install --claude         Claude Code (./.mcp.json)",
+      "  " + BIN + " mcp install --codex          Codex CLI (~/.codex/config.toml)",
+      "  " + BIN + " mcp install --vscode         VS Code (./.vscode/mcp.json)",
+      "  " + BIN + " mcp install --windsurf | --gemini | --opencode | --zed | --claude-desktop",
+      "  " + BIN + " mcp install --cursor         Cursor (./.cursor/mcp.json; see note below)",
+      "  " + BIN + " mcp --url <https://...>      use a remote MCP endpoint instead of the local server",
+      "  " + BIN + " mcp install --claude --read-only   register a read-only server (writes are not callable)",
+      "",
+      (MCP_URL ? "Default entry: the hosted endpoint " + MCP_URL + " with the auth env var as a reference (never a literal key)." : "Default entry: this package's local stdio server, which reads credentials saved by '" + BIN + " login' or the CLI's auth env vars."),
+      "The old spelling '" + BIN + " mcp --claude' still works. --all skips Cursor until it speaks MCP 2026-07-28.",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+  const url = typeof parsed.flags.get("url") === "string" ? parsed.flags.get("url") as string : undefined;
+  if (url) {
+    try {
+      new URL(url);
+    } catch {
+      fail(2, "--url must be a valid URL");
+    }
+  }
+  const { entry, warnings } = mcpEntryFor(url, parsed.flags.get("read-only") === true);
+  const cwd = process.cwd();
+  const wanted = new Set<string>();
+  for (const [flag, id] of Object.entries(MCP_CLIENT_FLAGS)) if (parsed.flags.get(flag) === true) wanted.add(id);
+  const all = parsed.flags.get("all") === true;
+  if (all) {
+    for (const client of MCP_CLIENTS) if (!client.incompatible && client.detect(cwd)) wanted.add(client.id);
+  }
+  if (wanted.has("claude-desktop") && entry.url) {
+    if (all) wanted.delete("claude-desktop");
+    else fail(2, "Claude Desktop reads only stdio servers from its config file; add a remote server as a connector in Claude Desktop (Settings > Connectors > Add custom connector) with " + entry.url + ". Or drop --url to register this package's local server.");
+  }
+
+  if (wanted.size === 0) {
+    out({
+      server: BIN,
+      entry,
+      ...(warnings.length > 0 ? { warnings } : {}),
+      detected: MCP_CLIENTS.filter((c) => c.detect(cwd)).map((c) => c.id),
+      note: "Pass --all to write this entry into every detected client, one of --claude/--codex/--vscode/--windsurf/--gemini/--opencode/--zed/--claude-desktop/--cursor for a specific one, or merge it under mcpServers yourself." + (entry.url ? "" : " The server reads credentials saved by '" + BIN + " login'."),
+    });
+    await flushExit(0);
+  }
+  const results: McpWriteResult[] = [];
+  for (const id of wanted) {
+    const client = findMcpClient(id)!;
+    results.push(writeMcpConfig(client, cwd, BIN, entry));
+  }
+  out({
+    ok: true,
+    server: BIN,
+    entry,
+    written: results.filter((r) => r.written).map((r) => r.file),
+    clients: results,
+    ...(warnings.length > 0 ? { warnings } : {}),
+    ...(all && MCP_CLIENTS.some((c) => c.incompatible && c.detect(cwd)) ? { skipped: MCP_CLIENTS.filter((c) => c.incompatible && c.detect(cwd)).map((c) => ({ client: c.id, reason: c.incompatible })) } : {}),
+  });
+  await flushExit(0);
+}
+
+// ---------------------------------------------------------------------------
+// agent contract — init, agent-guide, auth check, doctor, help --json
+// ---------------------------------------------------------------------------
+
+function agentContext(): AgentContext {
+  return {
+    bin: BIN,
+    pkg: PKG_NAME,
+    apiTitle: API_TITLE,
+    version: VERSION,
+    envPrefix: ENV_PREFIX,
+    authEnvVars: [...AUTH_SCALARS.map((a) => a.env), ...(BASIC ? [BASIC.envUser, BASIC.envPass] : [])],
+    docsUrl: docsSiteUrl(),
+    mcpUrl: MCP_URL,
+    skillsRepo: SKILLS_REPO,
+    hasMcp: HAS_MCP,
+    builtins: BUILTIN_COMMANDS,
+  };
+}
+
+function commandSummaries(): CommandSummary[] {
+  return OPS.map((op) => ({
+    resource: op.command[0],
+    command: op.command[1],
+    method: op.httpMethod,
+    path: op.path,
+    ...(op.summary ? { summary: op.summary } : {}),
+    paginated: op.paginated,
+    destructive: op.safety === "destructive",
+    auth: op.auth,
+    flags: op.params.filter((p) => p.kind !== "path").map((p) => ({ flag: p.flag, type: p.type, ...(p.items ? { items: p.items } : {}), ...(p.enum ? { enum: p.enum } : {}), required: p.required, ...(p.description ? { description: p.description.split("\n")[0] } : {}) })),
+  }));
+}
+
+/**
+ * help --json: a compact command index. Full schemas live behind the
+ * per-operation docs command so discovery does not spend an agent's context
+ * window on every response shape before it has chosen an operation.
+ */
+function helpJson(): Record<string, unknown> {
+  const byResource = new Map<string, CommandSummary[]>();
+  for (const c of commandSummaries()) {
+    const list = byResource.get(c.resource) ?? [];
+    list.push(c);
+    byResource.set(c.resource, list);
+  }
+  return {
+    schema_version: "2",
+    name: BIN,
+    version: VERSION,
+    api: API_TITLE,
+    api_version: API_VERSION,
+    spec_format: SPEC_FORMAT,
+    usage: BIN + " <resource> <command> [args] [--flags]",
+    resources: [...byResource.entries()].map(([resource, commands]) => ({
+      resource,
+      commands: commands.map((c) => {
+        const op = OPS.find((o) => o.command[0] === resource && o.command[1] === c.command)!;
+        return {
+          command: c.command,
+          method: c.method,
+          path: c.path,
+          ...(c.summary ? { summary: c.summary } : {}),
+          paginated: c.paginated,
+          safety: op.safety,
+          destructive: c.destructive,
+          auth: c.auth,
+          positional: op.params.filter((p) => p.kind === "path").map((p) => p.name),
+          flags: c.flags,
+          details_command: BIN + " docs " + resource + " " + c.command + " --json",
+        };
+      }),
+    })),
+    discovery: {
+      search: BIN + " docs search <term> --json",
+      operation: BIN + " docs <resource> <command> --json",
+      note: "Choose an operation from this index, then read only that operation's complete schemas and example arguments.",
+    },
+    builtins: BUILTIN_COMMANDS,
+    global_flags: ["--help", "--version", "--debug", "--non-interactive", "--mode agent|human", "--yes", "--force", "--color on|off|auto", "--base-url <url>", "--data '<json>' | @<file> | -", "--fields <a,b.c>", "--all", "--validate", "--out <dir>", ...AUTH_SCALARS.map((a) => "--" + a.flag + " <value>")],
+    auth_env_vars: agentContext().authEnvVars,
+  };
+}
+
+async function cmdAgentGuide(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    process.stdout.write(BIN + " agent-guide [--format json] — how an agent should drive this CLI: conventions, first command, docs, MCP, skills, next steps. JSON.\n");
+    await flushExit(0);
+  }
+  out(agentGuide(agentContext(), commandSummaries()));
+  await flushExit(0);
+}
+
+/** Which credential the CLI would send, without sending it. --live calls the identity endpoint too. */
+async function cmdAuth(parsed: Parsed): Promise<void> {
+  const sub = parsed.positionals[1];
+  if (parsed.help || sub !== "check") {
+    process.stdout.write([
+      BIN + " auth check [--live] — report the credential the CLI would use, as JSON: {status: ok|action_required, authenticated, source, ...}",
+      "  --live   also call the API's identity endpoint" + (WHOAMI ? "" : " (none in this API; --live is a no-op)"),
+      "",
+      "Precedence: flags > env vars > stored credentials (" + credsPath() + ").",
+    ].join("\n") + "\n");
+    await flushExit(parsed.help ? 0 : 2);
+  }
+  const stored = readCreds();
+  let source = "none";
+  if (AUTH_SCALARS.some((a) => typeof parsed.flags.get(a.flag) === "string")) source = "flags";
+  else {
+    const envScalar = AUTH_SCALARS.find((a) => process.env[a.env] !== undefined);
+    if (envScalar) source = "env:" + envScalar.env;
+    else if (stored && (stored.scalars || stored.basic || stored.oauth)) source = "login";
+  }
+  const authenticated = source !== "none";
+  const report: Record<string, unknown> = {
+    status: authenticated ? "ok" : "action_required",
+    authenticated,
+    source,
+    credentials_path: existsSync(credsPath()) ? credsPath() : null,
+    auth_env_vars: agentContext().authEnvVars,
+    base_url: resolveBaseUrl(parsed.flags) ?? null,
+    next_steps: authenticated ? [] : [
+      ...AUTH_SCALARS.map((a) => "Set " + a.env + " in the environment, or run '" + BIN + " login --" + a.flag + " <value>'."),
+      "Then run '" + BIN + " auth check --live'.",
+    ],
+  };
+  if (authenticated && parsed.flags.get("live") === true && WHOAMI) {
+    const op = OPS.find((o) => o.resource === WHOAMI.resource && o.method === WHOAMI.method);
+    if (op) {
+      const client = await makeClient(parsed.flags);
+      const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; data?: unknown; error?: unknown }>>>)[op.resource]!;
+      const result = await target[op.method]!();
+      if (result.ok) report.identity = result.data;
+      else {
+        const why = classifyApiError(result.error, { bin: BIN, hadCredential: true, docsUrl: DOCS_URL_DEFAULT });
+        report.status = "action_required";
+        report.live = { ok: false, code: why.code, message: why.message };
+        report.next_steps = why.nextSteps ?? [];
+      }
+    }
+  }
+  out(report);
+  await flushExit(report.status === "ok" ? 0 : 1);
+}
+
+async function cmdDoctor(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    process.stdout.write(BIN + " doctor — check the install: binary, node, credentials, base URL, docs, MCP client config. JSON with next_steps.\n");
+    await flushExit(0);
+  }
+  const checks: DoctorCheck[] = [];
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  checks.push({ name: "node", ok: nodeMajor >= 18, detail: process.version, ...(nodeMajor >= 18 ? {} : { fix: "Install Node 18 or newer." }) });
+  checks.push({ name: "cli", ok: true, detail: BIN + " " + VERSION + " (" + PKG_NAME + ")" });
+  const stored = readCreds();
+  const envScalar = AUTH_SCALARS.find((a) => process.env[a.env] !== undefined);
+  const hasCred = Boolean(envScalar) || Boolean(stored && (stored.scalars || stored.basic || stored.oauth));
+  checks.push({ name: "credentials", ok: hasCred, detail: envScalar ? "env:" + envScalar.env : hasCred ? credsPath() : "none", ...(hasCred ? {} : { fix: AUTH_SCALARS[0] ? "Set " + AUTH_SCALARS[0].env + " or run '" + BIN + " login'." : "Run '" + BIN + " login'." }) });
+  const baseUrl = resolveBaseUrl(parsed.flags);
+  if (baseUrl) {
+    try {
+      const response = await fetch(baseUrl, { method: "GET", signal: AbortSignal.timeout(8_000) });
+      checks.push({ name: "base_url", ok: true, detail: baseUrl + " → HTTP " + response.status });
+    } catch (e) {
+      checks.push({ name: "base_url", ok: false, detail: baseUrl + ": " + (e as Error).message, fix: "Check the network, or set --base-url / " + ENV_PREFIX + "_BASE_URL." });
+    }
+  } else {
+    checks.push({ name: "base_url", ok: false, detail: "none", fix: "Pass --base-url or run '" + BIN + " config set base-url <url>'." });
+  }
+  if (hasCred && WHOAMI) {
+    const op = OPS.find((o) => o.resource === WHOAMI.resource && o.method === WHOAMI.method);
+    if (op) {
+      try {
+        const client = await makeClient(parsed.flags);
+        const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; error?: unknown }>>>)[op.resource]!;
+        const result = await target[op.method]!();
+        checks.push(result.ok ? { name: "identity", ok: true, detail: op.command.join(" ") + " ok" } : { name: "identity", ok: false, detail: classifyApiError(result.error, { bin: BIN, hadCredential: true, docsUrl: DOCS_URL_DEFAULT }).message, fix: "The credential was rejected; run '" + BIN + " login' with a current one." });
+      } catch (e) {
+        checks.push({ name: "identity", ok: false, detail: (e as Error).message });
+      }
+    }
+  }
+  const docs = docsSiteUrl();
+  if (docs) {
+    const index = await fetchDocs("llms.txt");
+    checks.push({ name: "docs", ok: index !== null, detail: docs + "/llms.txt" + (index !== null ? " reachable" : " unreachable"), ...(index !== null ? {} : { fix: "The docs site is not answering; '" + BIN + " docs' falls back to the built-in reference." }) });
+  }
+  if (HAS_MCP || MCP_URL) {
+    const cwd = process.cwd();
+    const configured = MCP_CLIENTS.filter((c) => c.detect(cwd) && mcpConfigured(c, cwd, BIN)).map((c) => c.id);
+    const detected = MCP_CLIENTS.filter((c) => c.detect(cwd) && !c.incompatible).map((c) => c.id);
+    checks.push({ name: "mcp_clients", ok: detected.length === 0 || configured.length > 0, detail: "detected: " + (detected.join(", ") || "none") + "; configured: " + (configured.join(", ") || "none"), ...(detected.length > 0 && configured.length === 0 ? { fix: "Run '" + BIN + " mcp install --all'." } : {}) });
+  }
+  const claims = pendingClaims(process.cwd(), BIN);
+  if (claims.length > 0) checks.push({ name: "unclaimed", ok: false, detail: claims.length + " unclaimed generation(s) in ." + BIN + "/claims.json", fix: "Claim them: " + claims.map((c) => c.url).join(", ") });
+  const summary = summarizeDoctor(checks);
+  out({ ...summary, harness: detectHarness(), agent_mode: isAgentMode(parsed) });
+  await flushExit(summary.status === "ok" ? 0 : 1);
+}
+
+/**
+ * init: the one command that connects a machine (or a repo) to this API.
+ * Stores a credential when given one, installs the skills repository, writes
+ * MCP config for every agent client found, and upserts a marked block into
+ * AGENTS.md (CLAUDE.md under Claude Code). Idempotent; --all takes the
+ * defaults without asking; every part reports and none of them fails init.
+ */
+async function cmdInit(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    process.stdout.write([
+      BIN + " init [--all] [-k <credential>] [--yes] [--no-skills] [--no-mcp] [--no-agents-md]",
+      "",
+      "  -k, --" + (AUTH_SCALARS[0]?.flag ?? "token") + " <value>   store the credential (or set " + (AUTH_SCALARS[0]?.env ?? ENV_PREFIX + "_TOKEN") + " in the environment)" + (CLI_AUTH_URL ? "; with neither, approve one in the browser" : ""),
+      "  --all                    do everything without prompting (implied under an agent)",
+      "  --no-skills | --no-mcp | --no-agents-md   skip a part",
+      "",
+      "Writes: " + credsPath() + " (credential), the skills directory of each agent on this machine" + (SKILLS_REPO ? " (npx skills add " + SKILLS_REPO + ")" : " (no skills repository configured)") + ", MCP config for detected clients, and a '" + BIN + "' block in ./AGENTS.md.",
+    ].join("\n") + "\n");
+    await flushExit(0);
+  }
+  const report: Record<string, unknown> = { ok: true, bin: BIN };
+  const nextSteps: string[] = [];
+  const cwd = process.cwd();
+  const harness = detectHarness();
+
+  // 1. credential
+  const stored: StoredCreds = readCreds() ?? {};
+  const first = AUTH_SCALARS[0];
+  const given = (typeof parsed.flags.get("k") === "string" ? parsed.flags.get("k") as string : undefined)
+    ?? (first && typeof parsed.flags.get(first.flag) === "string" ? parsed.flags.get(first.flag) as string : undefined);
+  if (given && first) {
+    stored.scalars = { ...stored.scalars, [first.option]: given };
+    writeCreds(stored);
+    report.credential = { status: "stored", path: credsPath() };
+  } else if (first && process.env[first.env]) {
+    report.credential = { status: "env", variable: first.env };
+  } else if (stored.scalars || stored.basic || stored.oauth) {
+    report.credential = { status: "stored", path: credsPath() };
+  } else if (first && CLI_AUTH_URL && !explicitNonInteractive(parsed)) {
+    // Nothing anywhere: approve a credential in the browser, as `login`
+    // would, then carry on. Under an agent the URL is printed for the person
+    // and polled; only the explicit non-interactive switch skips this.
+    const minted = await browserApprove(isAgentMode(parsed) || parsed.flags.get("no-browser") === true, parsed.flags);
+    storeMinted(stored, minted);
+    report.credential = { status: "minted", method: "browser", key_name: minted.key_name, ...(minted.org_id ? { org_id: minted.org_id } : {}), path: credsPath() };
+  } else {
+    report.credential = { status: "none" };
+    if (first) nextSteps.push("Set " + first.env + " in the environment, or run '" + BIN + " init -k <credential>' or '" + BIN + " login'.");
+  }
+
+  // 2. skills
+  if (parsed.flags.get("no-skills") === true) report.skills = { status: "skipped" };
+  else if (SKILLS_REPO) report.skills = installSkills(SKILLS_REPO, { agent: harness === "claude-code" ? "claude-code" : null });
+  else report.skills = { status: "skipped", repo: null, detail: "No skills repository is configured for this CLI." };
+
+  // 3. MCP config
+  if (parsed.flags.get("no-mcp") === true || !(HAS_MCP || MCP_URL)) {
+    report.mcp = { status: HAS_MCP || MCP_URL ? "skipped" : "unavailable" };
+  } else {
+    const { entry, warnings } = mcpEntryFor(undefined);
+    const clients = MCP_CLIENTS.filter((c) => !c.incompatible && c.detect(cwd) && !(c.id === "claude-desktop" && entry.url));
+    const results = clients.map((c) => writeMcpConfig(c, cwd, BIN, entry));
+    report.mcp = { status: results.length > 0 ? "written" : "no-clients", entry, clients: results, ...(warnings.length > 0 ? { warnings } : {}) };
+    if (results.length === 0) nextSteps.push("No MCP client was found on this machine; run '" + BIN + " mcp' to print the entry.");
+  }
+
+  // 4. AGENTS.md
+  if (parsed.flags.get("no-agents-md") === true) {
+    report.agents_md = { status: "skipped" };
+  } else {
+    const file = agentInstructionsFile(cwd, harness);
+    const result = upsertAgentBlock(file, BIN + " agent-contract", agentBlock(agentContext(), commandSummaries()));
+    report.agents_md = { status: result.updated ? "updated" : "written", file: result.file };
+  }
+
+  nextSteps.push("Run '" + BIN + " auth check --live'" + (WHOAMI ? "" : " (or any read command)") + " to confirm the connection.");
+  nextSteps.push("Run '" + BIN + " agent-guide' for the conventions, or '" + BIN + " --help' for commands.");
+  out({ ...report, next_steps: nextSteps });
+  await flushExit(0);
+}
+
+// ---------------------------------------------------------------------------
+// upgrade — explicit self-update via the npm registry
+// ---------------------------------------------------------------------------
+
+function semverLess(a: string, b: string): boolean {
+  const pa = a.split(/[.+-]/).map(Number);
+  const pb = b.split(/[.+-]/).map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+function registryBase(): string {
+  return (process.env.npm_config_registry ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+}
+
+async function latestVersion(timeoutMs: number): Promise<string | null> {
+  try {
+    const response = await fetch(registryBase() + "/" + PKG_NAME, {
+      headers: { Accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return null;
+    const doc = await response.json() as { "dist-tags"?: { latest?: string } };
+    return doc["dist-tags"]?.latest ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function cmdUpgrade(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    const lines = [
+      BIN + " upgrade — update this CLI from the npm registry",
+      "",
+      "  " + BIN + " upgrade            install the latest published version (npm install -g)",
+      "  " + BIN + " upgrade --check    report current vs latest without installing",
+      "",
+      "Registry: " + registryBase() + " (honors npm_config_registry).",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+  const latest = await latestVersion(5000);
+  if (latest === null) {
+    fail(1, PKG_NAME + " is not on the registry (" + registryBase() + "). This package updates by regeneration from its API spec; get the latest from the API provider.");
+  }
+  const outdated = semverLess(VERSION, latest!);
+  if (parsed.flags.get("check") === true) {
+    out({ current: VERSION, latest, outdated, registry: registryBase() });
+    await flushExit(0);
+  }
+  if (!outdated) {
+    out({ ok: true, current: VERSION, latest, message: "Already up to date." });
+    await flushExit(0);
+  }
+  // How this binary was installed decides how it upgrades; "npm install -g"
+  // over a pnpm, bun, or npx install would leave two copies or none.
+  let self = process.argv[1] ?? "";
+  try { self = realpathSync(self); } catch { /* keep the literal path */ }
+  const manager = /[\\/]_npx[\\/]/.test(self) ? "npx" : /[\\/]pnpm[\\/]/.test(self) ? "pnpm" : /[\\/]\.bun[\\/]/.test(self) ? "bun" : /[\\/]yarn[\\/]/.test(self) ? "yarn" : "npm";
+  if (manager === "npx") fail(1, "This run came through npx, which fetches the latest version each time; there is nothing to upgrade in place.");
+  if (manager !== "npm") {
+    const command = manager === "pnpm" ? "pnpm add -g " + PKG_NAME + "@" + latest : manager === "bun" ? "bun add -g " + PKG_NAME + "@" + latest : "yarn global add " + PKG_NAME + "@" + latest;
+    failWith({ status: "action_required", code: "COMMAND_FAILED", message: PKG_NAME + " was installed with " + manager + ", so npm can't upgrade it in place.", nextSteps: ["Run: " + command] });
+  }
+  process.stderr.write("Upgrading " + PKG_NAME + " " + VERSION + " -> " + latest + "\n");
+  // Windows resolves npm to npm.cmd, which only a shell can start.
+  const install = spawnSync("npm", ["install", "-g", PKG_NAME + "@" + latest], { stdio: ["ignore", "inherit", "inherit"], shell: process.platform === "win32" });
+  if (install.status !== 0) {
+    fail(1, "npm install failed (exit " + String(install.status) + "). Try: npm install -g " + PKG_NAME + "@latest");
+  }
+  out({ ok: true, upgraded: { from: VERSION, to: latest } });
+  await flushExit(0);
+}
+
+// ---------------------------------------------------------------------------
+// completion — shell completion scripts built from the op table
+// ---------------------------------------------------------------------------
+
+const TOP_WORDS = ["login", "logout", "whoami", "config", "mcp", "upgrade", "docs", "webhooks", "feedback", "completion", "help", "version", "init", "agent-guide", "auth", "doctor"];
+
+/** Every flag an API command accepts, with the values a flag completes to (enums, on|off|auto, agent|human). */
+function completionFlagsFor(op: OpSpec): { flags: string[]; values: Record<string, string[]> } {
+  const flags = [...op.params.filter((p) => p.kind !== "path").map((p) => "--" + p.flag), ...COMPLETION_GLOBAL_FLAGS];
+  const values: Record<string, string[]> = { "--color": ["on", "off", "auto"], "--mode": ["agent", "human"] };
+  for (const p of op.params) {
+    const enumValues = p.type === "array" ? p.items?.enum : p.enum;
+    if (enumValues && enumValues.length > 0) values["--" + p.flag] = enumValues;
+    if (p.type === "boolean") values["--" + p.flag] = ["true", "false"];
+  }
+  return { flags, values };
+}
+
+const COMPLETION_GLOBAL_FLAGS = ["--help", "--version", "--non-interactive", "--color", "--base-url", "--data", "--fields", "--all", "--validate", "--debug", "--mode", "--yes", "--force", "--out", ...AUTH_SCALARS.map((a) => "--" + a.flag)];
+const BUILTIN_WORDS: Record<string, string[]> = {
+  config: ["list", "get", "set", "unset", "path"],
+  completion: ["bash", "zsh", "fish"],
+  auth: ["check"],
+  mcp: ["install"],
+  webhooks: ["listen", "fake"],
+};
+
+/** bash (and zsh via bashcompinit): resources, commands, flags, and the values a flag takes. */
+function completionScript(): string {
+  const fn = "_" + BIN.replace(/-/g, "_") + "_complete";
+  const resources = [...new Set(OPS.map((o) => o.command[0]))];
+  const lines: string[] = [];
+  lines.push(fn + "() {");
+  lines.push('  local cur="${COMP_WORDS[COMP_CWORD]}"');
+  lines.push('  local prev="${COMP_WORDS[COMP_CWORD-1]}"');
+  lines.push('  local first="${COMP_WORDS[1]}"');
+  lines.push('  local second="${COMP_WORDS[2]}"');
+  lines.push('  if [ "$COMP_CWORD" -eq 1 ]; then');
+  lines.push('    COMPREPLY=($(compgen -W "' + [...TOP_WORDS, ...resources].join(" ") + '" -- "$cur")); return');
+  lines.push("  fi");
+  lines.push('  if [ "$COMP_CWORD" -eq 2 ]; then');
+  lines.push('    case "$first" in');
+  for (const resource of resources) {
+    const cmds = OPS.filter((o) => o.command[0] === resource).map((o) => o.command[1]).join(" ");
+    lines.push("      " + resource + ') COMPREPLY=($(compgen -W "' + cmds + '" -- "$cur")); return ;;');
+  }
+  for (const [word, subs] of Object.entries(BUILTIN_WORDS)) lines.push("      " + word + ') COMPREPLY=($(compgen -W "' + subs.join(" ") + '" -- "$cur")); return ;;');
+  lines.push('      docs) COMPREPLY=($(compgen -W "search read ' + resources.join(" ") + '" -- "$cur")); return ;;');
+  lines.push("    esac");
+  lines.push("  fi");
+  lines.push('  if [ "$first" = "config" ] && [ "$COMP_CWORD" -eq 3 ]; then COMPREPLY=($(compgen -W "' + CONFIG_KEYS.join(" ") + '" -- "$cur")); return; fi');
+  lines.push('  if [ "$first" = "mcp" ] && [ "$second" = "install" ]; then COMPREPLY=($(compgen -W "' + Object.keys(MCP_CLIENT_FLAGS).map((f) => "--" + f).join(" ") + ' --all --url" -- "$cur")); return; fi');
+  lines.push('  case "$first $second" in');
+  for (const op of OPS) {
+    const { flags, values } = completionFlagsFor(op);
+    lines.push('    "' + op.command[0] + " " + op.command[1] + '")');
+    lines.push('      case "$prev" in');
+    for (const [flag, options] of Object.entries(values)) lines.push("        " + flag + ') COMPREPLY=($(compgen -W "' + options.join(" ") + '" -- "$cur")); return ;;');
+    lines.push("      esac");
+    lines.push('      COMPREPLY=($(compgen -W "' + flags.join(" ") + '" -- "$cur")); return ;;');
+  }
+  lines.push("  esac");
+  lines.push('  COMPREPLY=($(compgen -W "' + COMPLETION_GLOBAL_FLAGS.join(" ") + '" -- "$cur"))');
+  lines.push("}");
+  lines.push("complete -F " + fn + " " + BIN);
+  return lines.join("\n");
+}
+
+/** fish: the same table as "complete" rules. */
+function fishCompletionScript(): string {
+  const resources = [...new Set(OPS.map((o) => o.command[0]))];
+  const q = (text: string) => "'" + text.replace(/'/g, "\\'") + "'";
+  const lines: string[] = ["complete -c " + BIN + " -f"];
+  const top = [...TOP_WORDS, ...resources];
+  lines.push("complete -c " + BIN + " -n '__fish_use_subcommand' -a " + q(top.join(" ")));
+  for (const resource of resources) {
+    const cmds = OPS.filter((o) => o.command[0] === resource);
+    lines.push("complete -c " + BIN + " -n '__fish_seen_subcommand_from " + resource + "; and not __fish_seen_subcommand_from " + cmds.map((o) => o.command[1]).join(" ") + "' -a " + q(cmds.map((o) => o.command[1]).join(" ")));
+    for (const op of cmds) {
+      const { flags, values } = completionFlagsFor(op);
+      const seen = "__fish_seen_subcommand_from " + resource + "; and __fish_seen_subcommand_from " + op.command[1];
+      for (const flag of flags) {
+        const options = values[flag];
+        lines.push("complete -c " + BIN + " -n " + q(seen) + " -l " + flag.slice(2) + (options ? " -x -a " + q(options.join(" ")) : " -r"));
+      }
+    }
+  }
+  for (const [word, subs] of Object.entries(BUILTIN_WORDS)) {
+    lines.push("complete -c " + BIN + " -n '__fish_seen_subcommand_from " + word + "; and not __fish_seen_subcommand_from " + subs.join(" ") + "' -a " + q(subs.join(" ")));
+  }
+  lines.push("complete -c " + BIN + " -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set unset' -a " + q(CONFIG_KEYS.join(" ")));
+  lines.push("complete -c " + BIN + " -n '__fish_seen_subcommand_from docs' -a " + q(["search", "read", ...resources].join(" ")));
+  return lines.join("\n");
+}
+
+async function cmdCompletion(parsed: Parsed): Promise<void> {
+  const shell = parsed.positionals[1];
+  if (parsed.help || shell === undefined) {
+    const lines = [
+      BIN + " completion <bash|zsh|fish> — print a shell completion script: resources, commands, flags, and enum values",
+      "",
+      '  bash: add to ~/.bashrc:   eval "$(' + BIN + ' completion bash)"',
+      '  zsh:  add to ~/.zshrc:    eval "$(' + BIN + ' completion zsh)"',
+      "  fish: " + BIN + " completion fish > ~/.config/fish/completions/" + BIN + ".fish",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(parsed.help ? 0 : 2);
+  }
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") fail(2, "completion expects bash, zsh, or fish");
+  const script = shell === "fish" ? fishCompletionScript()
+    : shell === "zsh" ? "autoload -U +X bashcompinit && bashcompinit\n" + completionScript()
+    : completionScript();
+  process.stdout.write(script + "\n");
+  await flushExit(0);
+}
+
+// ---------------------------------------------------------------------------
+// docs — spec reference + the docs site's prose (llms.txt convention)
+// ---------------------------------------------------------------------------
+
+function docsSiteUrl(): string | null {
+  return readConfig().docsUrl ?? DOCS_URL_DEFAULT;
+}
+
+/** Fetch llms.txt / llms-full.txt / a prose page from the docs site,
+ * with a 1h cache in the config dir. Explicit command = explicit fetch;
+ * nothing here runs unless the user asked for docs. */
+async function fetchDocs(pathOrFile: string): Promise<string | null> {
+  const base = docsSiteUrl();
+  const url = /^https?:\/\//.test(pathOrFile)
+    ? pathOrFile
+    : base === null
+      ? null
+      : base.replace(/\/+$/, "") + "/" + pathOrFile.replace(/^\/+/, "");
+  if (url === null) return null;
+  const cacheFile = join(configDir(), "docs-cache", url.replace(/[^a-zA-Z0-9.]+/g, "_").slice(-120));
+  try {
+    const stat = statSync(cacheFile);
+    if (Date.now() - stat.mtimeMs < 60 * 60 * 1000) return readFileSync(cacheFile, "utf8");
+  } catch { /* not cached */ }
+  try {
+    const response = await fetch(url, {
+      headers: { Accept: "text/markdown, text/plain, */*" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+    const text = await response.text();
+    mkdirSync(join(configDir(), "docs-cache"), { recursive: true, mode: 0o700 });
+    writeFileSync(cacheFile, text);
+    return text;
+  } catch {
+    try {
+      return readFileSync(cacheFile, "utf8");
+    } catch {
+      return null;
+    }
+  }
+}
+
+function searchTerms(query: string): string[] {
+  return [...new Set(query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length >= 2))];
+}
+
+/** Token search across names, prose, paths, and arguments. A phrase such as
+ * "create project" should find the projects create command, even though that exact
+ * substring never occurs in the generated command. */
+function referenceSearchScore(op: OpSpec, query: string): number {
+  const terms = searchTerms(query);
+  if (terms.length === 0) return 0;
+  const names = [...op.command, op.tool].join("_").toLowerCase().split(/[^a-z0-9]+/);
+  const summary = (op.summary ?? "").toLowerCase();
+  const description = (op.description ?? "").toLowerCase();
+  const path = op.path.toLowerCase();
+  const params = op.params.flatMap((p) => [p.name.toLowerCase(), p.flag.toLowerCase()]);
+  let score = 0;
+  for (const term of terms) {
+    if (names.includes(term)) score += 10;
+    if (summary.split(/[^a-z0-9]+/).includes(term)) score += 5;
+    else if (summary.includes(term)) score += 3;
+    if (path.includes(term)) score += 3;
+    if (params.includes(term)) score += 3;
+    else if (params.some((param) => param.includes(term))) score += 1;
+    if (description.includes(term)) score += 1;
+  }
+  return score;
+}
+
+function referenceFor(op: OpSpec, includeSchemas = false): string {
+  const lines: string[] = [];
+  lines.push(paintOut("bold", usageLine(op)));
+  if (op.summary) lines.push(op.summary);
+  lines.push(wireOf(op) + (op.paginated ? "  (paginated: --all streams every item)" : ""));
+  if (op.description) lines.push("", op.description.trim());
+  lines.push("", paintOut("bold", "Contract:"));
+  lines.push("  Safety: " + op.safety + (op.safety === "destructive" ? " (requires --force)" : ""));
+  lines.push("  Auth: " + op.auth);
+  const groups: [string, ParamSpec[]][] = [
+    ["Path arguments", op.params.filter((p) => p.kind === "path")],
+    ["Flags", op.params.filter((p) => p.kind !== "path")],
+  ];
+  for (const [label, params] of groups) {
+    if (params.length === 0) continue;
+    lines.push("", paintOut("bold", label + ":"));
+    for (const p of params) {
+      const name = p.kind === "path" ? "<" + p.name + ">" : "--" + p.flag;
+      lines.push("  " + padPaint("cyan", name, 30) + typeLabel(p) + (p.required ? " " + paintOut("yellow", "(required)") : ""));
+      const values = p.type === "array" ? p.items?.enum : p.enum;
+      if (values && values.join("|").length > 24) lines.push("      one of: " + values.join(", "));
+      if (p.description) {
+        for (const descLine of p.description.trim().split("\n")) lines.push("      " + descLine);
+      }
+    }
+  }
+  const extras = commandExtras(op);
+  if (extras.length > 0) {
+    lines.push("", paintOut("bold", "CLI flags:"));
+    for (const [name, text] of extras) lines.push("  " + padPaint("cyan", name, 30) + text);
+  }
+  lines.push("", paintOut("bold", "Example:"), "  " + exampleLine(op));
+  if (includeSchemas) {
+    lines.push("", paintOut("bold", "Input schema:"), JSON.stringify(op.inputSchema, null, 2));
+    lines.push("", paintOut("bold", "Wire arguments:"), JSON.stringify(op.exampleArguments, null, 2));
+    if (op.outputSchema) lines.push("", paintOut("bold", "Output schema:"), JSON.stringify(op.outputSchema, null, 2));
+  } else {
+    lines.push("", "Add --schema for the complete input/output schemas, or --json for the machine contract.");
+  }
+  return lines.join("\n");
+}
+
+/** Opens a browser for a person; under an agent it prints the URL instead of opening anything. */
+function openInBrowser(url: string, parsed?: Parsed): { opened: boolean; url: string } {
+  if (parsed && nonInteractive(parsed)) {
+    out({ opened: false, url, note: "Agent mode: nothing was opened. Give this URL to the user." });
+    return { opened: false, url };
+  }
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  spawnSync(opener, args, { stdio: "ignore" });
+  return { opened: true, url };
+}
+
+async function cmdDocs(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    const lines = [
+      BIN + " docs — API reference from the spec, plus the docs site's guides",
+      "",
+      "  " + BIN + " docs                          overview",
+      "  " + BIN + " docs <resource> <command>     operation contract and example",
+      "      --schema                              include input/output JSON Schema",
+      "      --json                                print the machine contract as JSON",
+      "  " + BIN + " docs search <term>            search reference and guides",
+      "      --json / --format json                 print structured matches and availability",
+      "  " + BIN + " docs read <page>              print a docs-site page in the terminal",
+      "  " + BIN + " docs --web                    open the docs site in a browser",
+      "",
+      "Guides come from the docs site's llms.txt (set with '" + BIN + " config set docs-url <url>').",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+
+  if (parsed.flags.get("web") === true) {
+    const base = docsSiteUrl();
+    if (base === null) fail(2, "No docs site configured. Run '" + BIN + " config set docs-url <url>'.");
+    const opened = openInBrowser(base!, parsed);
+    if (opened.opened) out({ ok: true, opened: base });
+    await flushExit(0);
+  }
+
+  const sub = parsed.positionals[1];
+
+  if (sub === "search") {
+    const term = parsed.positionals.slice(2).join(" ");
+    if (!term) fail(2, "docs search expects a term");
+    const jsonOutput = parsed.flags.get("json") === true || parsed.flags.get("format") === "json";
+    const refMatches = OPS.map((op) => ({ op, score: referenceSearchScore(op, term) }))
+      .filter((match) => match.score > 0)
+      .sort((a, b) => b.score - a.score || a.op.command.join(" ").localeCompare(b.op.command.join(" ")))
+      .map((match) => match.op);
+    const prose = await fetchDocs("llms-full.txt");
+    const proseMatches: { heading: string; excerpt: string; score: number }[] = [];
+    if (prose !== null) {
+      let heading = "";
+      const terms = searchTerms(term);
+      for (const line of prose.split("\n")) {
+        if (/^#{1,3} /.test(line)) heading = line.replace(/^#+ /, "").trim();
+        else {
+          const lowerHeading = heading.toLowerCase();
+          const lowerLine = line.toLowerCase();
+          const matched = terms.filter((word) => lowerHeading.includes(word) || lowerLine.includes(word));
+          if (matched.length > 0) {
+            const allTerms = matched.length === terms.length;
+            proseMatches.push({
+              heading,
+              excerpt: line.trim().slice(0, 160),
+              score: matched.length * 10 + (allTerms ? 50 : 0) + (lowerHeading.includes(term.toLowerCase()) || lowerLine.includes(term.toLowerCase()) ? 25 : 0),
+            });
+          }
+        }
+      }
+      proseMatches.sort((a, b) => b.score - a.score || a.heading.localeCompare(b.heading) || a.excerpt.localeCompare(b.excerpt));
+    }
+    const docsStatus = docsSiteUrl() === null ? "not_configured" : prose === null ? "unavailable" : "ok";
+    if (jsonOutput) {
+      out({
+        schema_version: "1",
+        query: term,
+        reference: refMatches.slice(0, 15).map((op) => ({
+          command: op.command.join(" "),
+          method: op.httpMethod,
+          path: op.path,
+          ...(op.summary ? { summary: op.summary } : {}),
+          details_command: BIN + " docs " + op.command.join(" ") + " --json",
+        })),
+        guides: proseMatches.slice(0, 15).map(({ heading, excerpt }) => ({ heading, excerpt })),
+        totals: { reference: refMatches.length, guides: proseMatches.length },
+        guides_status: docsStatus,
+        ...(docsStatus === "not_configured" ? { next_steps: ["Run '" + BIN + " config set docs-url <url>' to add guide search; the API reference was still searched."] } : {}),
+        ...(docsStatus === "unavailable" ? { next_steps: ["The docs site could not be reached; cached guide content was unavailable. The API reference was still searched."] } : {}),
+      });
+      await flushExit(0);
+    }
+    const lines: string[] = [];
+    if (refMatches.length > 0) {
+      lines.push(paintOut("bold", "Reference:"));
+      for (const op of refMatches.slice(0, 15)) lines.push("  " + padPaint("cyan", op.command.join(" "), 34) + (op.summary ?? wireOf(op)));
+    }
+    if (proseMatches.length > 0) {
+      lines.push(...(lines.length > 0 ? [""] : []), paintOut("bold", "Guides:"));
+      for (const match of proseMatches.slice(0, 15)) lines.push("  " + padPaint("cyan", match.heading.slice(0, 32), 34) + match.excerpt.slice(0, 100));
+    } else if (docsStatus === "not_configured") {
+      lines.push(...(lines.length > 0 ? [""] : []), "(no docs site configured for guide search: '" + BIN + " config set docs-url <url>')");
+    } else if (docsStatus === "unavailable") {
+      lines.push(...(lines.length > 0 ? [""] : []), "(docs site unavailable; the API reference was still searched)");
+    }
+    if (lines.length === 0) lines.push("No matches for: " + term);
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(0);
+  }
+
+  if (sub === "read") {
+    const page = parsed.positionals[2];
+    if (page === undefined) fail(2, "docs read expects a page path or URL");
+    let target = page!;
+    if (!/^https?:\/\//.test(target)) {
+      const index = await fetchDocs("llms.txt");
+      const linked = index?.match(/\((https?:[^)]+)\)/g)?.map((m) => m.slice(1, -1)) ?? [];
+      const hit = linked.find((u) => u.toLowerCase().includes(target.toLowerCase()));
+      if (hit !== undefined) target = hit;
+    }
+    const text = await fetchDocs(target);
+    if (text === null) {
+      fail(1, docsSiteUrl() === null
+        ? "No docs site configured. Run '" + BIN + " config set docs-url <url>'."
+        : "Couldn't fetch that page. Run '" + BIN + " docs' to see the index.");
+    }
+    process.stdout.write(text! + (text!.endsWith("\n") ? "" : "\n"));
+    await flushExit(0);
+  }
+
+  if (sub !== undefined) {
+    const op = findOp(sub!, parsed.positionals[2] ?? "");
+    if (!op) {
+      const list = OPS.filter((o) => o.command[0] === sub);
+      if (list.length === 0) fail(2, "Unknown docs topic: " + sub + ". Run '" + BIN + " docs' for the overview.");
+      const lines = [paintOut("bold", "Commands for " + sub + ":"), ""];
+      for (const resourceOp of list) {
+        lines.push("  " + padPaint("cyan", resourceOp.command.join(" "), 34) + (resourceOp.summary ?? ""));
+      }
+      process.stdout.write(lines.join("\n") + "\n");
+      await flushExit(0);
+    }
+    if (parsed.flags.get("json") === true) {
+      process.stdout.write(JSON.stringify({
+        schema_version: "1",
+        spec_format: SPEC_FORMAT,
+        api_version: API_VERSION,
+        operation: op,
+      }, null, 2) + "\n");
+      await flushExit(0);
+    }
+    process.stdout.write(referenceFor(op!, parsed.flags.get("schema") === true) + "\n");
+    await flushExit(0);
+  }
+
+  const lines: string[] = [];
+  lines.push(paintOut("bold", "typeship") + " (v" + API_VERSION + ")");
+  if (API_DESCRIPTION) lines.push("", API_DESCRIPTION.trim());
+  lines.push("", paintOut("bold", "Reference:") + " " + BIN + " docs <resource> <command>");
+  const byResource = new Map<string, number>();
+  for (const op of OPS) byResource.set(op.command[0], (byResource.get(op.command[0]) ?? 0) + 1);
+  for (const [resource, count] of byResource) {
+    lines.push("  " + padPaint("cyan", resource, 24) + count + " command" + (count === 1 ? "" : "s"));
+  }
+  const base = docsSiteUrl();
+  lines.push("", paintOut("bold", "Guides:") + " " + (base !== null
+    ? base + "  (" + BIN + " docs search <term>, " + BIN + " docs read <page>, " + BIN + " docs --web)"
+    : "no docs site configured — '" + BIN + " config set docs-url <url>'"));
+  if (base !== null) {
+    const index = await fetchDocs("llms.txt");
+    if (index === null) {
+      lines.push("  (the docs site doesn't publish llms.txt; only --web is available)");
+    } else {
+      const titles = [...index.matchAll(/^- \[([^\]]+)\]/gm)].map((m) => m[1]).slice(0, 12);
+      for (const title of titles) lines.push("  " + title);
+    }
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+  await flushExit(0);
+}
+
+// ---------------------------------------------------------------------------
+// webhooks listen — forward relayed events to a local handler
+// ---------------------------------------------------------------------------
+
+interface RelayedEvent {
+  seq: number;
+  method: string;
+  headers: Record<string, string>;
+  content_type: string | null;
+  body: string;
+}
+
+function eventTypeOf(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    for (const key of ["type", "event", "event_type", "eventType", "name"]) {
+      if (typeof parsed[key] === "string") return parsed[key] as string;
+    }
+  } catch { /* not JSON */ }
+  return null;
+}
+
+async function cmdWebhooksFake(parsed: Parsed): Promise<void> {
+  void parsed;
+  fail(2, "This API's spec declares no webhooks, so there is nothing to fake.");
+}
+
+async function cmdWebhooks(parsed: Parsed): Promise<void> {
+  const sub = parsed.positionals[1];
+  if (parsed.help || sub === undefined) {
+    const lines = [
+      BIN + " webhooks — work with this API's webhook events",
+      "",
+      "  " + BIN + " webhooks listen --forward-to localhost:3000/webhooks",
+      "  " + BIN + " webhooks listen --forward-to localhost:3000/hooks --events account.created,account.updated",
+      "  " + BIN + " webhooks fake [<event>] [--key whsec_...] [--forward-to <url>]",
+      "",
+      "listen mints a private relay URL to point the API's webhook settings",
+      "at; events replay locally with their original headers, so signature",
+      "verification keeps working. No tunnels, no exposed ports.",
+      "fake sends (or prints) a signed sample event for local handler testing.",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+    await flushExit(parsed.help ? 0 : 2);
+  }
+  if (sub === "fake") { await cmdWebhooksFake(parsed); }
+  if (sub !== "listen") fail(2, "Unknown webhooks command: " + String(sub) + ". Try '" + BIN + " webhooks listen' or '" + BIN + " webhooks fake'.");
+  if (!RELAY) {
+    fail(2, "The webhook relay isn't enabled for this package. The API provider can enable it in their typeship console; the next regeneration bakes it in.");
+  }
+  const forwardRaw = parsed.flags.get("forward-to");
+  if (typeof forwardRaw !== "string") {
+    fail(2, "webhooks listen requires --forward-to <url>, e.g. --forward-to localhost:3000/webhooks");
+  }
+  const forwardTo = /^https?:\/\//.test(forwardRaw as string) ? forwardRaw as string : "http://" + (forwardRaw as string);
+  const eventsRaw = parsed.flags.get("events");
+  const eventsFilter = typeof eventsRaw === "string"
+    ? eventsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+    : null;
+
+  interface MintedSession {
+    session_id?: string;
+    ingest_url?: string;
+    poll_url?: string;
+    errors?: { message?: string }[];
+  }
+  let minted: MintedSession | null = null;
+  try {
+    const response = await fetch(RELAY!.mintUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ project: RELAY!.project }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    minted = await response.json().catch(() => null) as MintedSession | null;
+    if (!response.ok || typeof minted?.ingest_url !== "string" || typeof minted.poll_url !== "string") {
+      const detail = minted?.errors?.[0]?.message ?? "HTTP " + response.status;
+      fail(1, "Couldn't start a relay session: " + detail);
+    }
+  } catch (e) {
+    if (e instanceof ExitPending) throw e;
+    fail(1, "Couldn't reach the relay: " + (e as Error).message);
+  }
+
+  process.stderr.write(paintErr("green", "Ready!") + " Forwarding relayed events to " + forwardTo + "\n");
+  process.stderr.write("Point this API's webhook endpoint at: " + paintErr("cyan", minted!.ingest_url!) + " (^C to quit)\n");
+
+  let cursor = 0;
+  let pollFailures = 0;
+  for (;;) {
+    let payload: { events: RelayedEvent[]; next: number };
+    try {
+      const response = await fetch(minted!.poll_url! + "?after=" + cursor + "&wait=1", {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(30_000),
+      });
+      if (response.status === 404) fail(1, "The relay session expired. Run '" + BIN + " webhooks listen' again.");
+      if (!response.ok) throw new Error("HTTP " + response.status);
+      payload = await response.json() as typeof payload;
+      pollFailures = 0;
+    } catch (e) {
+      if (e instanceof ExitPending) throw e;
+      pollFailures++;
+      if (pollFailures > 5) fail(1, "Lost the relay: " + (e as Error).message);
+      await new Promise((resolve) => setTimeout(resolve, 2000 * pollFailures));
+      continue;
+    }
+    for (const event of payload.events) {
+      cursor = event.seq;
+      const type = eventTypeOf(event.body);
+      if (eventsFilter !== null && (type === null || !eventsFilter.includes(type))) continue;
+      const started = Date.now();
+      try {
+        const forwarded = await fetch(forwardTo, {
+          method: event.method,
+          headers: event.headers,
+          body: event.method === "GET" ? undefined : event.body,
+          signal: AbortSignal.timeout(30_000),
+        });
+        process.stderr.write(
+          (forwarded.ok ? paintErr("green", String(forwarded.status)) : paintErr("yellow", String(forwarded.status))) +
+          "  " + (type ?? event.method) + " [" + event.seq + "] (" + (Date.now() - started) + "ms)\n",
+        );
+      } catch (e) {
+        process.stderr.write(paintErr("yellow", "unreachable") + "  " + (type ?? event.method) + " [" + event.seq + "]: " + (e as Error).message + "\n");
+      }
+    }
+    if (payload.next > cursor) cursor = payload.next;
+  }
+}
+
+async function cmdFeedback(parsed: Parsed): Promise<void> {
+  if (parsed.help) {
+    process.stdout.write(BIN + " feedback — open the API provider's issue tracker with environment details prefilled\n");
+    await flushExit(0);
+  }
+  if (!SUPPORT_URL) {
+    fail(2, "No support URL is configured for this CLI. The API provider can set one in their typeship console.");
+  }
+  let target = SUPPORT_URL!;
+  if (/github\.com\/[^/]+\/[^/]+\/issues\/new/.test(target)) {
+    const bodyLines = [
+      "<!-- describe the problem or request above the line -->",
+      "",
+      "---",
+      "- cli: " + BIN + " " + VERSION + " (api " + API_VERSION + ")",
+      "- node: " + process.version,
+      "- platform: " + process.platform + "/" + process.arch,
+    ];
+    const sep = target.includes("?") ? "&" : "?";
+    target += sep + "title=" + encodeURIComponent("[" + BIN + "] ") + "&body=" + encodeURIComponent(bodyLines.join("\n"));
+  }
+  if (!nonInteractive(parsed)) process.stderr.write("Opening " + paintErr("cyan", SUPPORT_URL!) + "\n");
+  const opened = openInBrowser(target, parsed);
+  if (opened.opened) out({ ok: true, opened: SUPPORT_URL });
+  await flushExit(0);
+}
+
+/** Opt-in (console setting) once-a-day upgrade hint. Off by default:
+ * generated code phones nobody unless the project owner chose this. The
+ * notice prints the previous run's cached answer; at most once a day it
+ * refreshes the cache first, with a 1.5s cap so a slow registry can't
+ * hold a command hostage. */
+async function maybeUpdateNotice(commandWord: string | undefined, quiet: boolean): Promise<void> {
+  if (!UPDATE_NOTICE || quiet) return;
+  if (commandWord === undefined || ["upgrade", "version", "help", "login", "logout"].includes(commandWord)) return;
+  const cacheFile = join(configDir(), "update-check.json");
+  let cache: { checkedAt?: number; latest?: string } = {};
+  try {
+    cache = JSON.parse(readFileSync(cacheFile, "utf8")) as typeof cache;
+  } catch { /* no cache yet */ }
+  if ((cache.checkedAt ?? 0) < Date.now() - 24 * 60 * 60 * 1000) {
+    const latest = await latestVersion(1500);
+    if (latest !== null) {
+      cache = { checkedAt: Date.now(), latest };
+      mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+      writeFileSync(cacheFile, JSON.stringify(cache) + "\n");
+    }
+  }
+  if (cache.latest !== undefined && semverLess(VERSION, cache.latest)) {
+    process.stderr.write(paintErr("yellow", "A newer " + BIN + " is available: " + VERSION + " -> " + cache.latest + ". Run '" + BIN + " upgrade'.") + "\n");
+  }
+}
+
+/** The command that fetches the next page: same positionals, the next page's query flags. */
+function nextCommandFor(op: OpSpec, pathValues: string[], next: Record<string, unknown>): string {
+  const parts = [BIN, op.command[0], op.command[1], ...pathValues.map(shellQuote)];
+  for (const [wire, value] of Object.entries(next)) {
+    if (value === undefined || value === null) continue;
+    const spec = op.params.find((p) => (p.kind === "query" || p.kind === "body") && p.name === wire);
+    const flag = spec ? spec.flag : wire;
+    const text = Array.isArray(value) ? value.map(String).join(",") : typeof value === "object" ? JSON.stringify(value) : String(value);
+    parts.push("--" + flag, shellQuote(text));
+  }
+  return parts.join(" ");
+}
+
+/** Quote a value for a copy-pasteable shell line (POSIX single quotes). */
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+function usageLine(op: OpSpec): string {
+  const paths = op.params.filter((p) => p.kind === "path").map((p) => "<" + p.name + ">").join(" ");
+  return BIN + " " + op.command[0] + " " + op.command[1] + (paths ? " " + paths : "");
+}
+
+/** How the command reaches the wire: "GET /users/{id}", or for GraphQL the
+ * root field, since every operation is one POST to the endpoint. */
+function wireOf(op: OpSpec): string {
+  return op.graphql ? "GraphQL " + op.graphql.kind + " " + op.graphql.field : op.httpMethod + " " + op.path;
+}
+
+/** Pad to a column, then paint — escape codes must not count toward width. */
+function padPaint(code: keyof typeof ANSI, text: string, width: number): string {
+  return paintOut(code, text) + " ".repeat(Math.max(1, width - text.length));
+}
+
+/** Terminal width for wrapping help: the real column count, else 100, never under 60. */
+function termWidth(): number {
+  const cols = process.stdout.columns;
+  return Math.max(60, Math.min(cols && cols > 0 ? cols : 100, 160));
+}
+
+/** Word-wrap text to a width. */
+function wrapText(text: string, width: number): string[] {
+  const words = text.split(/\s+/).filter((w) => w !== "");
+  const lines: string[] = [];
+  let line = "";
+  const max = Math.max(20, width);
+  for (const word of words) {
+    if (line === "") { line = word; continue; }
+    if ((line + " " + word).length > max) { lines.push(line); line = word; }
+    else line += " " + word;
+  }
+  if (line !== "") lines.push(line);
+  return lines;
+}
+
+/** The first sentence of a description for --help: Markdown links flattened, one line, bounded. */
+function helpSentence(description: string | undefined): string {
+  if (!description) return "";
+  const flat = description.trim().replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ");
+  const m = flat.match(/^(.{1,200}?[.!?])(\s|$)/);
+  const first = m ? m[1]! : flat;
+  return first.length > 220 ? first.slice(0, 217).replace(/\s+\S*$/, "") + "…" : first;
+}
+
+/** Type column text for a param: string, number, string[], a|b|c, enum, object, json, path. */
+function typeLabel(p: ParamSpec): string {
+  if (p.type === "file") return "path (uploaded)";
+  if (p.format && p.type === "string") return p.format;
+  const inlineEnum = (values: string[] | undefined) => values && values.join("|").length <= 24 ? values.join("|") : undefined;
+  if (p.type === "array") {
+    const items = p.items ?? { type: "json" as const };
+    const inner = inlineEnum(items.enum) ?? (items.enum ? "enum" : items.type);
+    return inner + "[]";
+  }
+  if (p.enum) return inlineEnum(p.enum) ?? "enum";
+  return p.type;
+}
+
+/** The enum values that did not fit in the type column, for a continuation line. */
+function enumNote(p: ParamSpec): string | null {
+  const values = p.type === "array" ? p.items?.enum : p.enum;
+  if (!values || values.join("|").length <= 24) return null;
+  return "one of: " + values.join(", ");
+}
+
+/** A "--flag  type  description" table with columns sized to the content and descriptions wrapped. */
+function flagTable(params: ParamSpec[], extras: [string, string][]): string[] {
+  const width = termWidth();
+  const rows: { name: string; type: string; required: boolean; text: string; note: string | null }[] = params.map((p) => ({
+    name: p.kind === "path" ? "<" + p.name + ">" : "--" + p.flag,
+    type: typeLabel(p),
+    required: p.required,
+    text: helpSentence(p.description),
+    note: enumNote(p),
+  }));
+  for (const [name, text] of extras) rows.push({ name, type: "", required: false, text, note: null });
+  const nameCol = Math.min(34, Math.max(12, ...rows.map((r) => r.name.length + 2)));
+  const typeCol = Math.min(28, Math.max(8, ...rows.map((r) => r.type.length + 2)));
+  const indent = 2 + nameCol + typeCol;
+  const lines: string[] = [];
+  for (const r of rows) {
+    // A name wider than its column gets its own line; the type and text follow beneath, aligned.
+    const head = r.name.length + 2 > nameCol
+      ? "  " + paintOut("cyan", r.name) + "\n" + " ".repeat(2 + nameCol) + r.type.padEnd(typeCol)
+      : "  " + padPaint("cyan", r.name, nameCol) + r.type.padEnd(typeCol);
+    const plain = (r.required ? "(required)" + (r.text ? " " : "") : "") + r.text;
+    if (plain === "") { lines.push(head.trimEnd()); }
+    else {
+      const wrapped = wrapText(plain, width - indent);
+      const first = r.required ? paintOut("yellow", "(required)") + wrapped[0]!.slice("(required)".length) : wrapped[0]!;
+      lines.push((head + first).trimEnd());
+      for (const more of wrapped.slice(1)) lines.push(" ".repeat(indent) + more);
+    }
+    if (r.note) for (const more of wrapText(r.note, width - indent)) lines.push(" ".repeat(indent) + paintOut("dim", more));
+  }
+  return lines;
+}
+
+/** Display order for a resource's commands: the CRUD verbs first, then the rest in spec order. */
+const VERB_ORDER = ["list", "get", "create", "update", "delete"];
+function displayOrder(list: OpSpec[]): OpSpec[] {
+  const rank = (o: OpSpec) => { const i = VERB_ORDER.indexOf(o.command[1]); return i === -1 ? VERB_ORDER.length : i; };
+  return [...list].map((o, i) => ({ o, i })).sort((a, b) => rank(a.o) - rank(b.o) || a.i - b.i).map((x) => x.o);
+}
+
+/** "Label: text" wrapped to the terminal with the continuation indented under the text. */
+function labeled(label: string, text: string, width: number, indent: number): string[] {
+  const first = label.padEnd(indent);
+  const wrapped = wrapText(text, width - indent);
+  return wrapped.map((line, i) => (i === 0 ? first + line : " ".repeat(indent) + line));
+}
+
+function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
+  const byResource = new Map<string, OpSpec[]>();
+  for (const op of OPS) {
+    const list = byResource.get(op.command[0]) ?? [];
+    list.push(op);
+    byResource.set(op.command[0], list);
+  }
+  const width = termWidth();
+  const lines: string[] = [];
+  lines.push(paintOut("bold", BIN) + ": " + "typeship" + " (v" + "0.6.0" + ")");
+  lines.push("");
+  lines.push(paintOut("bold", "Usage:") + " " + BIN + " <resource> <command> [args] [--flags]");
+  lines.push("");
+  lines.push(paintOut("bold", "Resources:"));
+  // Big APIs get a digest per resource; the resource's own help has the full list.
+  const digest = OPS.length > 120;
+  const col = Math.min(30, Math.max(...[...byResource.keys()].map((r) => r.length)) + 4);
+  for (const [resource, list] of byResource) {
+    const names = displayOrder(list).map((o) => o.command[1]);
+    const text = digest && names.length > 6
+      ? names.slice(0, 6).join(", ") + ", … " + (names.length - 6) + " more (" + BIN + " " + resource + ")"
+      : names.join(", ");
+    const wrapped = wrapText(text, width - 2 - col);
+    lines.push("  " + padPaint("cyan", resource, col) + wrapped[0]);
+    for (const more of wrapped.slice(1)) lines.push(" ".repeat(2 + col) + more);
+  }
+  lines.push("");
+  const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --data '<json>', --fields <a,b.c>, --all (paginated lists), --validate (schema-check bodies)" +
+    (AUTH_SCALARS.length > 0 ? ", " + AUTH_SCALARS.map((a) => "--" + a.flag + " <value>").join(", ") : "");
+  lines.push(...labeled(paintOut("bold", "Global flags:") + " ", flagsText, width, 14).map((l, i) => (i === 0 ? l : l)));
+  lines.push(...labeled("Credential env vars: ", [
+    ...AUTH_SCALARS.map((a) => a.env),
+    ...(BASIC ? [BASIC.envUser, BASIC.envPass] : []),
+  ].join(", ") || "none", width, 21));
+  lines.push(...labeled("Endpoint env var: ", "TYPESHIP_BASE_URL", width, 18));
+  lines.push(...labeled("Account: ", BIN + " login | logout | whoami | auth check  (stored at " + credsPath() + ")", width, 9));
+  lines.push(...labeled("Setup: ", BIN + " init (connect this machine)" + " | " + BIN + " config (defaults)" + (HAS_MCP || MCP_URL ? " | " + BIN + " mcp install --all (agent clients)" : "") + " | " + BIN + " doctor | " + BIN + " upgrade | " + BIN + " completion <shell>", width, 7));
+  lines.push(...labeled("Agents: ", BIN + " agent-guide | " + BIN + " help --json | --mode agent | -y/--yes/--force | --out <dir>  (JSON errors: {status, issues[{code}], next_steps})", width, 8));
+  lines.push(...labeled("Docs: ", BIN + " docs [<resource> <command> | search <term> | read <page> | --web]", width, 6));
+  if (RELAY) lines.push("Webhooks: " + BIN + " webhooks listen --forward-to <url>  (local event forwarding)");
+  if (SUPPORT_URL) lines.push("Feedback: " + BIN + " feedback  (opens the provider's issue tracker)");
+  if (EXCLUDED_OPS > 0 && HAS_MCP) {
+    lines.push("");
+    lines.push("Note: " + EXCLUDED_OPS + " operation(s) with uploads or event streams are CLI/SDK-only, not MCP tools.");
+  }
+  lines.push("");
+  lines.push("Run '" + BIN + " <resource>' for a resource's commands, '" + BIN + " <resource> <command> --help' for flags.");
+  stream.write(lines.join("\n") + "\n");
+}
+
+function printResource(resource: string, stream: NodeJS.WriteStream = process.stdout): void {
+  const list = displayOrder(OPS.filter((o) => o.command[0] === resource));
+  const lines: string[] = ["Commands for " + resource + ":", ""];
+  const width = termWidth();
+  const col = Math.min(64, Math.max(...list.map((o) => usageLine(o).length)) + 2);
+  for (const op of list) {
+    const usage = usageLine(op);
+    const wrapped = wrapText((helpSentence(op.summary) || wireOf(op)) + authNote(op), width - 2 - col);
+    if (usage.length + 2 > col) {
+      lines.push("  " + usage);
+      for (const line of wrapped) lines.push(" ".repeat(2 + col) + line);
+    } else {
+      lines.push("  " + usage.padEnd(col) + wrapped[0]);
+      for (const line of wrapped.slice(1)) lines.push(" ".repeat(2 + col) + line);
+    }
+  }
+  lines.push("", "Run '" + BIN + " " + resource + " <command> --help' for flags.");
+  stream.write(lines.join("\n") + "\n");
+}
+
+/** Flags the CLI itself adds to an API command, as [flag, description] rows. */
+function commandExtras(op: OpSpec): [string, string][] {
+  const extras: [string, string][] = [];
+  if (op.hasBody && op.bodyKind === "binary") extras.push(["--file <path>", "raw request body, uploaded as-is (- reads stdin)"]);
+  else if (op.hasBody) extras.push(["--data '<json>'", "raw JSON body" + (op.bodyStyle === "fields" ? " (merged under field flags)" : "") + "; @<file> reads a file, - reads stdin"]);
+  if (op.select) extras.push(["--select '<selection>'", "GraphQL selection set replacing the default, e.g. '{ id name }'"]);
+  if (op.paginated) extras.push(["--all", "stream every item from every page (NDJSON)"]);
+  const collectionField = collectionProperty(op.outputSchema);
+  extras.push(["--fields <a,b.c>", "keep only these fields of the result" + (op.paginated ? " (per item)" : collectionField ? " (per item in " + collectionField + ")" : "")]);
+  if (bundleProperty(op.outputSchema) !== null) extras.push(["--out <dir>", "write the response's files ({path, content}) into a directory"]);
+  if (op.safety === "destructive") extras.push(["--force, -y", "destructive: required without a terminal, skips the prompt with one"]);
+  return extras;
+}
+
+/** One runnable example built from the required inputs. */
+function exampleLine(op: OpSpec): string {
+  const parts = [BIN, op.command[0], op.command[1]];
+  for (const p of op.params) {
+    if (!p.required) continue;
+    const generated = p.type === "file" ? undefined : op.exampleArguments[p.name];
+    const values = p.type === "array" ? p.items?.enum : p.enum;
+    const fallback: unknown = p.type === "file" ? "./file"
+      : values ? values[0]!
+      : p.type === "number" ? 1
+      : p.type === "boolean" ? true
+      : p.type === "object" ? {}
+      : p.type === "array" ? [p.items?.type === "number" ? 1 : "value"]
+      : "value";
+    const value = generated ?? fallback;
+    const sample = typeof value === "string" ? shellQuote(value)
+      : typeof value === "object" ? shellQuote(JSON.stringify(value))
+      : String(value);
+    if (p.kind === "path") parts.push(sample);
+    else parts.push("--" + p.flag, sample);
+  }
+  const required = op.bodyStyle === "data" && ((op.inputSchema.required as string[] | undefined) ?? []).includes("body");
+  if (required) {
+    const body = op.exampleArguments.body;
+    parts.push(op.bodyKind === "binary" ? "--file ./file" : "--data " + shellQuote(JSON.stringify(body ?? {})));
+  }
+  if (op.safety === "destructive") parts.push("--force");
+  return parts.join(" ");
+}
+
+/** " (no auth needed)" for an anonymous operation in an API that otherwise authenticates. */
+function authNote(op: OpSpec): string {
+  const apiHasAuth = AUTH_SCALARS.length > 0 || BASIC !== null || OAUTH_TOKEN_URL !== null;
+  return apiHasAuth && op.auth === "none" ? " (no auth needed)" : apiHasAuth && op.auth === "optional" ? " (auth optional)" : "";
+}
+
+function printOp(op: OpSpec): void {
+  const lines: string[] = [];
+  lines.push(paintOut("bold", usageLine(op)));
+  if (op.summary) lines.push(helpSentence(op.summary));
+  lines.push(wireOf(op) + authNote(op));
+  lines.push("");
+  const rows = op.params.filter((p) => p.kind !== "path");
+  const extras = commandExtras(op);
+  if (rows.length > 0 || extras.length > 0) {
+    lines.push(paintOut("bold", "Flags:"));
+    lines.push(...flagTable(rows, extras));
+  }
+  if (op.sse) lines.push("  (streams: one JSON line per server-sent event until the stream ends)");
+  lines.push("", paintOut("bold", "Example:"));
+  lines.push("  " + exampleLine(op));
+  if (op.paginated) lines.push("  " + usageLine(op) + " --all | jq -r '.id'");
+  const arrayFlag = rows.find((p) => p.type === "array");
+  if (arrayFlag) {
+    const sample = arrayFlag.items?.enum ? arrayFlag.items.enum.slice(0, 2).join(",") : arrayFlag.items?.type === "number" ? "1,2" : "a,b";
+    lines.push("", "Array flags take a comma list (--" + arrayFlag.flag + " " + sample + "), the flag repeated, or a JSON array.");
+  }
+  const dateFlag = rows.find((p) => p.format && p.type === "string");
+  if (dateFlag) {
+    lines.push("", "Date flags take ISO 8601 or a relative form (--" + dateFlag.flag + " -7d, -P7D, \"7 days ago\", today, now); relative values resolve against the clock.");
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+/** A text file named by a flag value (--data @body.json). */
+function readTextFile(flag: string, path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (e) {
+    return fail(2, "--" + flag + ": cannot read " + path + " (" + (e as Error).message + ")");
+  }
+}
+
+/** Everything on stdin as bytes, for --file -. */
+function readStdinBytes(): Promise<Uint8Array<ArrayBuffer>> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on("data", (chunk: Buffer) => { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); });
+    process.stdin.on("end", () => {
+      const all = Buffer.concat(chunks);
+      const bytes = new Uint8Array(all.byteLength);
+      bytes.set(all);
+      resolve(bytes);
+    });
+  });
+}
+
+/** A local file as an upload part; the SDK's multipart encoder takes Blobs. */
+function fileFromPath(flag: string, path: string): File {
+  try {
+    return new File([readFileSync(path)], basename(path));
+  } catch (e) {
+    return fail(2, "--" + flag + ": cannot read " + path + " (" + (e as Error).message + ")");
+  }
+}
+
+/** One scalar value of a flag (or of an array flag's element). */
+function coerceScalar(flag: string, type: "string" | "number" | "boolean" | "object" | "json", enumValues: string[] | undefined, text: string): unknown {
+  if (type === "object") {
+    let parsed: unknown;
+    try { parsed = JSON.parse(text); } catch (e) { fail(2, "--" + flag + " expects JSON objects, got: " + text + " (" + (e as Error).message + ")"); }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) fail(2, "--" + flag + " expects JSON objects, got: " + text);
+    return parsed;
+  }
+  if (type === "boolean") {
+    if (text === "true") return true;
+    if (text === "false") return false;
+    fail(2, "--" + flag + " expects true or false, got: " + text);
+  }
+  if (type === "number") {
+    const n = Number(text);
+    if (!Number.isFinite(n) || text.trim() === "") fail(2, "--" + flag + " expects a number, got: " + text);
+    return n;
+  }
+  if (type === "json") {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text; // let plain strings through for loosely-typed fields
+    }
+  }
+  if (enumValues && !enumValues.includes(text)) {
+    fail(2, "--" + flag + " must be one of: " + enumValues.join(", ") + " (got: " + text + ")");
+  }
+  return text;
+}
+
+/**
+ * A flag's raw value(s) as the typed value the SDK expects.
+ * Arrays take the flag repeated (--tag a --tag b), a comma list (--tag a,b),
+ * or a JSON array; a lone scalar is a one-item array, never a bare string.
+ * Objects must be JSON. Enum values are checked locally.
+ */
+function coerce(spec: ParamSpec, raw: string | boolean, repeated?: string[]): unknown {
+  if (spec.type === "file") {
+    if (raw === true) fail(2, "--" + spec.flag + " expects a file path");
+    return fileFromPath(spec.flag, String(raw));
+  }
+  if (spec.type === "boolean") {
+    if (raw === true) return true;
+    return coerceScalar(spec.flag, "boolean", undefined, String(raw));
+  }
+  if (raw === true) fail(2, "--" + spec.flag + " needs a value");
+  const text = String(raw);
+  if (spec.type === "array") {
+    const items = spec.items ?? { type: "json" as const };
+    const values = repeated !== undefined ? repeated : [text];
+    const out: unknown[] = [];
+    for (const value of values) {
+      const trimmed = value.trim();
+      if (trimmed.startsWith("[")) {
+        let parsed: unknown;
+        try { parsed = JSON.parse(trimmed); } catch (e) { fail(2, "--" + spec.flag + " looks like a JSON array but does not parse: " + (e as Error).message); }
+        if (!Array.isArray(parsed)) fail(2, "--" + spec.flag + " expects an array");
+        for (const element of parsed as unknown[]) {
+          out.push(typeof element === "string" && items.type !== "json" && items.type !== "object" ? coerceScalar(spec.flag, items.type, items.enum, element) : element);
+        }
+        continue;
+      }
+      // A comma list splits for scalar elements; JSON elements (objects) keep commas.
+      const parts = items.type === "json" || items.type === "object" || repeated !== undefined ? [value] : value.split(",").map((v) => v.trim()).filter((v) => v !== "");
+      for (const part of parts) out.push(coerceScalar(spec.flag, items.type, items.enum, part));
+    }
+    return out;
+  }
+  if (spec.type === "object") {
+    let parsed: unknown;
+    try { parsed = JSON.parse(text); } catch (e) { fail(2, "--" + spec.flag + " expects a JSON object, e.g. --" + spec.flag + " '{\"key\": \"value\"}' (" + (e as Error).message + ")"); }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) fail(2, "--" + spec.flag + " expects a JSON object, got: " + text);
+    return parsed;
+  }
+  if (spec.format && spec.type === "string") {
+    // Relative dates (-7d, 7 days ago, today) resolve against the clock;
+    // absolute values pass through for the API to judge.
+    const resolved = relativeDate(text, spec.format);
+    if (resolved && "error" in resolved) fail(2, "--" + spec.flag + ": " + resolved.error);
+    if (resolved) return resolved.value;
+  }
+  return coerceScalar(spec.flag, spec.type === "json" ? "json" : spec.type === "number" ? "number" : "string", spec.enum, text);
+}
+
+/** Whether the last client built carried any credential; failApi tells NO_AUTH from AUTH_INVALID with it. */
+let LAST_CLIENT_HAD_CREDENTIAL = false;
+
+/** Where a credential would come from, without sending it: "flags", "env:<VAR>", "login", or null. */
+function credentialSource(flags: Map<string, string | boolean>): string | null {
+  if (AUTH_SCALARS.some((a) => typeof flags.get(a.flag) === "string")) return "flags";
+  if (BASIC && typeof flags.get("username") === "string" && typeof flags.get("password") === "string") return "flags";
+  const envScalar = AUTH_SCALARS.find((a) => process.env[a.env] !== undefined);
+  if (envScalar) return "env:" + envScalar.env;
+  if (BASIC && process.env[BASIC.envUser] !== undefined && process.env[BASIC.envPass] !== undefined) return "env:" + BASIC.envUser;
+  const stored = readCreds();
+  if (stored && (stored.scalars || stored.basic || stored.oauth)) return "login";
+  return null;
+}
+
+/** Base URL resolution: --base-url > env > config base-url > config environment > spec default. */
+function resolveBaseUrl(flags: Map<string, string | boolean>): string | undefined {
+  const config = readConfig();
+  return (typeof flags.get("base-url") === "string" ? flags.get("base-url") as string : undefined)
+    ?? process.env["TYPESHIP_BASE_URL"]
+    ?? config.baseUrl
+    ?? (config.environment !== undefined ? ENVIRONMENTS[config.environment] : undefined)
+    ?? DEFAULT_BASE_URL ?? undefined;
+}
+
+async function makeClient(flags: Map<string, string | boolean>): Promise<TypeshipClient> {
+  const stored = readCreds();
+  const options: Record<string, unknown> = {};
+  const baseUrl = resolveBaseUrl(flags);
+  if (baseUrl === undefined) fail(2, "No base URL. Pass --base-url, set TYPESHIP_BASE_URL, or run '" + BIN + " config set base-url <url>'.");
+  options.baseUrl = baseUrl;
+  for (const a of AUTH_SCALARS) {
+    const v = (typeof flags.get(a.flag) === "string" ? flags.get(a.flag) as string : undefined)
+      ?? process.env[a.env] ?? stored?.scalars?.[a.option];
+    if (v !== undefined) options[a.option] = v;
+  }
+  if (BASIC) {
+    const username = (typeof flags.get("username") === "string" ? flags.get("username") as string : undefined)
+      ?? process.env[BASIC.envUser] ?? stored?.basic?.username;
+    const password = (typeof flags.get("password") === "string" ? flags.get("password") as string : undefined)
+      ?? process.env[BASIC.envPass] ?? stored?.basic?.password;
+    if (username !== undefined && password !== undefined) options.basicAuth = { username, password };
+  }
+  if (options.bearerToken === undefined && stored?.oauth) {
+    const token = await refreshedOauthToken(stored);
+    if (token !== undefined) options.bearerToken = token;
+  }
+  if (flags.get("debug") === true || process.env["TYPESHIP_DEBUG"] === "1") {
+    options.debug = (event: DebugEvent) => process.stderr.write(paintErr("dim", formatDebugEvent(BIN, event)) + "\n");
+  }
+  if (flags.get("validate") === true) options.validate = true;
+  for (const g of GLOBALS) {
+    const flagValue = flags.get(g.flag);
+    const value = typeof flagValue === "string" ? flagValue : process.env["TYPESHIP_" + g.envSuffix];
+    if (value !== undefined) options[g.option] = value;
+  }
+  LAST_CLIENT_HAD_CREDENTIAL = AUTH_SCALARS.some((a) => options[a.option] !== undefined) || options.basicAuth !== undefined || options.bearerToken !== undefined;
+  // Who is calling: the CLI, under which agent harness, and whether an
+  // agent is driving. "agent" means a harness was detected or the caller
+  // said so (--mode agent / env); a bare non-TTY run (CI, a pipeline) is
+  // "non-interactive", so usage by surface does not count CI as agents.
+  // The API can read it back; it carries no secrets.
+  const harness = detectHarness();
+  const explicitAgent = flags.get("mode") === "agent" || process.env["TYPESHIP_MODE"] === "agent";
+  const behaving = agentMode({ flagMode: flags.get("mode"), envMode: process.env["TYPESHIP_MODE"], stdoutIsTTY: process.stdout.isTTY === true, stdinIsTTY: process.stdin.isTTY === true });
+  const caller = harness || explicitAgent ? "; agent" : behaving ? "; non-interactive" : "";
+  options.defaultHeaders = {
+    ...(options.defaultHeaders as Record<string, string> | undefined),
+    "User-Agent": PKG_NAME + "-cli/" + VERSION + " (typeship" + (harness ? "; harness=" + harness : "") + caller + ")",
+  };
+  return new TypeshipClient(options as never);
+}
+
+function editDistance(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]!;
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const next = Math.min(prev[j]! + 1, prev[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = prev[j]!;
+      prev[j] = next;
+    }
+  }
+  return prev[b.length]!;
+}
+
+/** Closest candidate within edit distance 2, for did-you-mean hints. */
+function didYouMean(input: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined;
+  let bestDistance = 3;
+  for (const candidate of candidates) {
+    const d = editDistance(input.toLowerCase(), candidate.toLowerCase());
+    if (d < bestDistance) { bestDistance = d; best = candidate; }
+  }
+  return best;
+}
+
+const BUILTIN_COMMANDS = ["login", "logout", "whoami", "config", "mcp", "docs", "upgrade", "feedback", "completion", "webhooks", "help", "version", "init", "agent-guide", "auth", "doctor"];
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgv(argv);
+  if (parsed.positionals[0] === "help") {
+    // help --json: the command surface as data (agents read this once).
+    if (parsed.flags.get("json") === true || parsed.flags.get("format") === "json") { out(helpJson()); await flushExit(0); }
+    parsed.positionals.shift(); parsed.help = true;
+  }
+  if (parsed.flags.get("format") !== undefined && parsed.flags.get("format") !== "json") {
+    fail(2, "--format json is the only format; output is always JSON.");
+  }
+  if (parsed.flags.has("version") || parsed.positionals[0] === "version") {
+    // "typeship 1.0.0 (typeship 1.0.0, ...)" said the name three times; when
+    // the API's title is the bin, name the API version as such.
+    const apiLabel = API_TITLE.toLowerCase().replace(/[^a-z0-9]/g, "") === BIN.toLowerCase().replace(/[^a-z0-9]/g, "") ? "API " + API_VERSION : API_TITLE + " " + API_VERSION;
+    process.stdout.write(BIN + " " + VERSION + " (" + apiLabel + ", generated by typeship)\n");
+    await flushExit(0);
+  }
+  const [resourceCmd, methodCmd] = parsed.positionals;
+  COLOR_OUT = colorEnabled(process.stdout, parsed);
+  COLOR_ERR = colorEnabled(process.stderr, parsed);
+  // Prose errors for a person: stderr is a terminal (or --mode human says
+  // to behave as if), and nothing asked for JSON.
+  const forcedHuman = parsed.flags.get("mode") === "human" || parsed.flags.get("mode") === "interactive" || process.env["TYPESHIP_MODE"] === "human";
+  HUMAN_ERRORS = (process.stderr.isTTY === true || forcedHuman) && !isAgentMode(parsed) && parsed.flags.get("format") !== "json" && parsed.flags.get("json") !== true;
+  await maybeUpdateNotice(resourceCmd, explicitNonInteractive(parsed));
+
+  if (resourceCmd === "init") { await cmdInit(parsed); }
+  if (resourceCmd === "agent-guide") { await cmdAgentGuide(parsed); }
+  if (resourceCmd === "auth") { await cmdAuth(parsed); }
+  if (resourceCmd === "doctor") { await cmdDoctor(parsed); }
+  if (resourceCmd === "upgrade") { await cmdUpgrade(parsed); }
+  if (resourceCmd === "webhooks") { await cmdWebhooks(parsed); }
+  if (resourceCmd === "feedback") { await cmdFeedback(parsed); }
+  if (resourceCmd === "docs") { await cmdDocs(parsed); }
+  if (resourceCmd === "completion") { await cmdCompletion(parsed); }
+  if (resourceCmd === "config") { await cmdConfig(parsed); }
+  if (resourceCmd === "mcp") { await cmdMcp(parsed); }
+  if (resourceCmd === "login") { await cmdLogin(parsed); }
+  if (resourceCmd === "logout") {
+    if (parsed.help) { process.stdout.write(BIN + " logout — remove " + credsPath() + "\n"); await flushExit(0); }
+    await cmdLogout();
+  }
+  if (resourceCmd === "whoami") {
+    if (parsed.help) {
+      process.stdout.write(BIN + " whoami — " + (WHOAMI
+        ? "call the API's identity endpoint with the resolved credentials"
+        : "report which credentials the CLI would use (no identity endpoint in this API)") + "\n");
+      await flushExit(0);
+    }
+    await cmdWhoami(parsed);
+  }
+
+  // Help on request goes to stdout and exits 0; help because the command
+  // was incomplete is a usage error: stderr, exit 2, like every other one.
+  if (!resourceCmd) { printRoot(parsed.help ? process.stdout : process.stderr); await flushExit(parsed.help ? 0 : 2); }
+  const resourceExists = OPS.some((o) => o.command[0] === resourceCmd);
+  if (!resourceExists) {
+    const suggestion = didYouMean(resourceCmd, [...new Set(OPS.map((o) => o.command[0])), ...BUILTIN_COMMANDS]);
+    fail(2, "Unknown command: " + resourceCmd + "." + (suggestion ? " Did you mean '" + BIN + " " + suggestion + "'?" : ""),
+      undefined, ["Run '" + BIN + " --help' for the commands."]);
+  }
+  if (!methodCmd) { printResource(resourceCmd, parsed.help ? process.stdout : process.stderr); await flushExit(parsed.help ? 0 : 2); }
+
+  const op = findOp(resourceCmd, methodCmd);
+  if (!op) {
+    const suggestion = didYouMean(methodCmd, OPS.filter((o) => o.command[0] === resourceCmd).map((o) => o.command[1]));
+    fail(2, "Unknown command: " + resourceCmd + " " + methodCmd + "." + (suggestion ? " Did you mean '" + BIN + " " + resourceCmd + " " + suggestion + "'?" : ""),
+      undefined, ["Run '" + BIN + " " + resourceCmd + "' for its commands."]);
+  }
+  if (parsed.help) { printOp(op); await flushExit(0); }
+  USAGE_HINT = BIN + " " + op.command[0] + " " + op.command[1] + " --help";
+
+  const pathSpecs = op.params.filter((p) => p.kind === "path");
+  const pathValues = parsed.positionals.slice(2);
+  if (pathValues.length !== pathSpecs.length) {
+    fail(2, "Expected " + pathSpecs.length + " argument(s): " + usageLine(op));
+  }
+
+  const values: Record<string, unknown> = {};
+  pathSpecs.forEach((spec, i) => { values[spec.name] = pathValues[i]; });
+
+  let dataBody: unknown;
+  const dataRaw = parsed.flags.get("data");
+  if (dataRaw === true) fail(2, "--data expects a JSON value, @<file>, or - for stdin");
+  if (typeof dataRaw === "string") {
+    // curl conventions: @path reads a file, - reads stdin, anything else is the literal.
+    const text = dataRaw === "-" ? await readStdin()
+      : dataRaw.startsWith("@") ? readTextFile("data", dataRaw.slice(1))
+      : dataRaw;
+    try { dataBody = JSON.parse(text); } catch (e) { fail(2, "--data is not valid JSON" + (dataRaw === "-" ? " (stdin)" : dataRaw.startsWith("@") ? " (" + dataRaw.slice(1) + ")" : "") + ": " + (e as Error).message); }
+  }
+  // A binary body (an upload that isn't a form) comes from --file (- reads stdin).
+  const fileRaw = parsed.flags.get("file");
+  if (op.bodyKind === "binary" && typeof fileRaw === "string") {
+    dataBody = fileRaw === "-" ? new File([await readStdinBytes()], "stdin") : fileFromPath("file", fileRaw);
+  }
+
+  // Mirrors opReservedFlags() in the generator: API parameters never use these
+  // names (colliding ones are emitted as --<kind>-<name>), so an unknown flag
+  // check can be exact.
+  const RESERVED_FLAGS = new Set(["data", "all", "select", "base-url", "debug", "validate", "non-interactive", "color", "version", "help", "yes", "force", "mode", "format", "json", "out", "fields", ...AUTH_SCALARS.map((a) => a.flag), ...(BASIC ? ["username", "password"] : []), ...GLOBALS.map((g) => g.flag)]);
+  for (const spec of op.params) {
+    if (spec.kind === "path") continue;
+    const raw = parsed.flags.get(spec.flag);
+    if (raw === undefined) continue;
+    // A flag given more than once is an array: array-typed params collect
+    // every value (each coerced to the element type); loosely typed (json)
+    // params become an array of the parsed values.
+    const all = parsed.repeated.get(spec.flag);
+    values[spec.name] = spec.type === "array"
+      ? coerce(spec, raw, all)
+      : all !== undefined && spec.type === "json"
+        ? all.map((v) => coerce(spec, v))
+        : coerce(spec, raw);
+  }
+  for (const key of parsed.flags.keys()) {
+    if (RESERVED_FLAGS.has(key)) continue;
+    if (key === "file" && op.bodyKind === "binary") continue;
+    if (!op.params.some((p) => p.flag === key)) {
+      const suggestion = didYouMean(key, [...op.params.filter((p) => p.kind !== "path").map((p) => p.flag), ...RESERVED_FLAGS]);
+      fail(2, "Unknown flag --" + key + "." + (suggestion ? " Did you mean --" + suggestion + "?" : ""));
+    }
+  }
+
+  const missing = missingRequired(op, values).filter((name) =>
+    !(op.bodyStyle === "fields" && dataBody !== undefined && typeof dataBody === "object" && dataBody !== null && name in (dataBody as object)),
+  );
+  if (missing.length > 0) fail(2, "Missing required: " + missing.map((m) => "--" + (op.params.find((p) => p.name === m)?.flag ?? m)).join(", "));
+  // A body that isn't a plain object (array, string, union) has no field
+  // flags; when the spec requires it, --data is the only way to send it.
+  const rawBodyRequired = op.bodyStyle === "data" && ((op.inputSchema.required as string[] | undefined) ?? []).includes("body");
+  if (rawBodyRequired && dataBody === undefined) {
+    fail(2, op.bodyKind === "binary"
+      ? "Missing required: --file <path> (this operation's request body is required)"
+      : "Missing required: --data '<json>' (this operation's request body is required)");
+  }
+
+  // --fields id,name,owner.email keeps only those paths of the result (per item for lists).
+  const fieldsRaw = parsed.flags.get("fields");
+  if (fieldsRaw === true) fail(2, "--fields expects a comma-separated list of field paths, e.g. --fields id,name");
+  if (typeof fieldsRaw === "string") {
+    FIELDS = fieldsRaw.split(",").map((f) => f.trim()).filter((f) => f !== "").map((f) => f.split("."));
+    if (FIELDS.length === 0) fail(2, "--fields expects at least one field path");
+  }
+
+  // --out <dir> materializes a file-shaped response (see cli-agent.ts bundleProperty).
+  const bundleField = bundleProperty(op.outputSchema);
+  const collectionField = collectionProperty(op.outputSchema);
+  const outDir = typeof parsed.flags.get("out") === "string" ? (parsed.flags.get("out") as string) : undefined;
+  if (outDir !== undefined && bundleField === null) {
+    fail(2, "--out applies to commands whose response carries files ({path, content}); " + op.command.join(" ") + " does not.");
+  }
+
+  // The spec says this operation needs a credential and none resolved:
+  // say so now, locally, instead of sending a request to learn it.
+  if (op.auth === "required" && (AUTH_SCALARS.length > 0 || BASIC || OAUTH_TOKEN_URL) && credentialSource(parsed.flags) === null) {
+    failWith({
+      status: "action_required",
+      code: "NO_AUTH",
+      message: op.command.join(" ") + " needs a credential (" + wireOf(op) + " is authenticated) and none was found.",
+      nextSteps: [
+        ...AUTH_SCALARS.map((a) => "Set " + a.env + " in the environment, pass --" + a.flag + " <value>, or run '" + BIN + " login'."),
+        ...(BASIC ? ["Set " + BASIC.envUser + " and " + BASIC.envPass + ", or pass --username and --password."] : []),
+        ...(AUTH_SCALARS.length === 0 && !BASIC ? ["Run '" + BIN + " login'."] : []),
+        "'" + BIN + " auth check' shows what the CLI would send.",
+      ],
+    });
+  }
+
+  // Destructive commands need --force. A person gets asked; an agent gets
+  // an action_required envelope with the exact command to run, so nothing
+  // is deleted on a guess.
+  if (op.safety === "destructive" && !assumeYes(parsed)) {
+    const rerun = BIN + " " + process.argv.slice(2).map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ") + " --force";
+    if (nonInteractive(parsed) || !process.stdin.isTTY) {
+      failWith({
+        status: "action_required",
+        code: "CONFIRMATION_REQUIRED",
+        message: op.command.join(" ") + " is destructive (" + op.httpMethod + " " + op.path + ") and needs --force.",
+        nextSteps: ["Confirm with the user, then run: " + rerun],
+      });
+    }
+    process.stderr.write(paintErr("yellow", op.command.join(" ") + " will " + op.httpMethod + " " + op.path + ". Continue? [y/N] "));
+    const answer = (await readLine()).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") failWith({ status: "action_required", code: "CONFIRMATION_REQUIRED", message: "Cancelled.", nextSteps: ["Run again with --force to skip the prompt: " + rerun] });
+  }
+
+  const client = await makeClient(parsed.flags);
+  const selectValue = typeof parsed.flags.get("select") === "string" ? (parsed.flags.get("select") as string) : undefined;
+  const args = buildArgs(op, values, dataBody, selectValue);
+  const target = (client as unknown as Record<string, Record<string, (...a: unknown[]) => unknown>>)[op.resource]!;
+  const callResult = target[op.method]!(...args);
+
+  if (op.paginated && parsed.flags.get("all") === true) {
+    try {
+      for await (const item of callResult as AsyncIterable<unknown>) {
+        process.stdout.write(JSON.stringify(project(item)) + "\n");
+      }
+      await flushExit(0);
+    } catch (e) {
+      failApi(e, LAST_CLIENT_HAD_CREDENTIAL);
+    }
+  }
+
+  const result = await (callResult as Promise<{ ok: boolean; data?: unknown; error?: unknown }>);
+  if (result.ok) {
+    if (op.sse) {
+      // Server-sent events as NDJSON, one line per event, until the stream ends.
+      try {
+        for await (const event of result.data as AsyncIterable<{ event?: string; id?: string; data: string }>) {
+          process.stdout.write(JSON.stringify(project(event)) + "\n");
+        }
+      } catch (e) {
+        failApi(e, LAST_CLIENT_HAD_CREDENTIAL);
+      }
+      await flushExit(0);
+    }
+    // A claim-shaped response (claim.url): say where to claim it, and leave
+    // a breadcrumb so a later session or doctor can list what is unclaimed.
+    if (claimProperty(op.outputSchema)) {
+      const claim = (result.data as { claim?: { url?: string; expires_at?: string } | null } | undefined)?.claim;
+      if (claim && typeof claim.url === "string") {
+        const file = recordClaim(process.cwd(), BIN, { url: claim.url, ...(claim.expires_at ? { expires_at: claim.expires_at } : {}), command: BIN + " " + process.argv.slice(2).join(" "), created_at: new Date().toISOString() });
+        process.stderr.write(paintErr("dim", "Unclaimed: a signed-in person can turn this into a project at " + claim.url + (claim.expires_at ? " (until " + claim.expires_at + ")" : "") + ". Noted in " + file + ".") + "\n");
+      }
+    }
+    if (op.paginated) {
+      // One page, plus what fetches the next: the raw arguments (the MCP
+      // tool's nextPage shape) and the exact command, so a script or an
+      // agent never has to reconstruct the cursor flag.
+      const page = result.data as { items: unknown[]; hasNextPage(): boolean; nextPageParams(): Record<string, unknown> | null };
+      const next = page.nextPageParams();
+      out({
+        items: project(page.items),
+        hasMore: next !== null,
+        ...(next !== null ? { nextPage: next, nextCommand: nextCommandFor(op, pathValues, next) } : {}),
+      });
+    } else if (FIELDS !== null && collectionField !== null && result.data !== null && typeof result.data === "object" && !Array.isArray(result.data) && Array.isArray((result.data as Record<string, unknown>)[collectionField])) {
+      // Batch-style collection envelopes ({data: [...]}) use item-relative
+      // fields, matching paginated results, while retaining envelope metadata.
+      const data = result.data as Record<string, unknown>;
+      out({ ...data, [collectionField]: project(data[collectionField]) });
+    } else if (outDir !== undefined && bundleField !== null) {
+      // --out: a file-shaped response (an array of {path, content}) lands
+      // on disk; stdout gets the rest of the response plus a summary.
+      const data = (result.data ?? {}) as Record<string, unknown>;
+      const files = (data[bundleField] as { path: string; content: string }[] | undefined) ?? [];
+      const written = writeBundle(outDir, files);
+      const { [bundleField]: _omitted, ...rest } = data;
+      out({ ...(project(rest) as Record<string, unknown>), out: written });
+    } else {
+      out(project(result.data ?? { ok: true }));
+    }
+    await flushExit(0);
+  }
+  failApi(result.error, LAST_CLIENT_HAD_CREDENTIAL);
+}
+
+function errorMessage(error: unknown): string {
+  const base = error instanceof Error ? error.name + ": " + error.message : String(error);
+  if (error instanceof Error && error.name === "TransportError") {
+    return base + " — check the base URL (--base-url, TYPESHIP_BASE_URL, or '" + BIN + " config base-url') and your network";
+  }
+  return base;
+}
+
+function serializeError(error: unknown): unknown {
+  if (error && typeof error === "object" && "violations" in error) {
+    return { violations: (error as { violations: unknown }).violations };
+  }
+  if (error && typeof error === "object" && "status" in error) {
+    const e = error as { status: number; body?: unknown };
+    return { status: e.status, body: e.body };
+  }
+  return undefined;
+}
+
+main().catch((e) => {
+  if (e instanceof ExitPending) return;
+  try {
+    fail(1, errorMessage(e));
+  } catch {
+    // exit already scheduled
+  }
+});