@typeship-ax/cli 0.22.0 → 0.24.0

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// typeship — command-line client. Generated by typeship — https://typeship.dev
+// 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.
@@ -9,40 +9,56 @@ import { spawnSync } from "node:child_process";
 import { oauthBrowserLogin, type OAuthLoginSession } from "./oauth-login.js";
 import { oauthDeviceLogin, customBrowserApproval, loginEndpoint, type ApprovedCredential } from "./polling-login.js";
 import { oauthStatusRequest } from "./oauth-request.js";
-import { checkConsoleBrowserLogin } from "./console-login-check.js";
-import { type FileCredentialStore, assertCredentialDestination, assertStoredIdentity, credentialIdentityBinding, type CredentialDestination, oauthSessionToken, sessionBinding, type SessionConfiguration, type StoredCredentials as StoredCreds } from "./oauth-session.js";
+import { type FileCredentialStore, sessionCredential, assertCredentialDestination, assertStoredIdentity, credentialIdentityBinding, type CredentialDestination, oauthSessionToken, sessionBinding, type SessionConfiguration, type StoredCredentials as StoredCreds } from "./oauth-session.js";
 import { createCredentialStore } from "./credential-storage.js";
 import { identityPolicyOf, identityFetch, identityResult, verifyApiIdentity, verifyClientIdentity, readApiIdentity, assertApiIdentity, type ApiIdentity, type IdentityConfiguration, type IdentityPolicy, type VerifiedIdentity } from "./api-identity.js";
-import { parseNamedCredentials, readNamedCredentialsFile, resolveNamedCredentials, namedCredentialAvailability, type NamedCredentials, type CredentialSchemes } from "./named-credentials.js";
+import { parseNamedCredentials, readNamedCredentialsFile, resolveNamedCredentials, namedCredentialAvailability, missingCredentials, oauthSessionSchemes, parseExtraHeaders, applyExtraHeaders, type NamedCredentials, type CredentialSchemes } from "./named-credentials.js";
 import { resolveProfile, listProfiles, selectProfile, removeProfile, readProfileConfig, updateProfileConfig, type ProfileContext } from "./auth-profiles.js";
 import { 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 { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent, type ClientOptions, type DebugEvent } from "./index.js";
-import { asApiResult, validateAgainstSchema, ValidationError, type Violation } from "./core/http.js";
+import { asApiResult, mediaTypeForPath, validateAgainstSchema, ValidationError, type Violation } from "./core/http.js";
 import { SCHEMAS, DEFS } from "./schemas.js";
-import { GLOBALS, OMITTED_OPS, OPS, buildArgs, findOp, missingRequired, type OmittedOpSpec, type OpSpec, type ParamSpec } from "./ops.js";
+import { GLOBALS, INPUT_TYPES, OMITTED_OPS, OPS, buildArgs, findOp, missingRequired, type OmittedOpSpec, 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,
+  MCP_CLIENTS, requiredScopes, agentGuide, agentBlock, agentInstructionsFile, agentMode, bundleProperty, claimProperty, classifyApiError, classifyAuthFailure, collectionProperty, detectHarness, envelope,
+  exitCodeFor, findMcpClient, formatRequestPreview, installSkills, mcpConfigured, pendingClaims, recordClaim, requestPreview, 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";
+import { checkValue, type ArgumentIssue } from "./arguments.js";
 import { docsReadCommand, docsReadTarget, fetchDocsText, resolveDocsContentUrl, searchConnectedGuides } from "./docs.js";
+import { projectFields, unmatchedFields, unmatchedFieldsMessage } from "./fields.js";
+import { renderTable } from "./table.js";
+import { SEARCH_PAGE_SIZE, rankOperations } from "./search.js";
+import { argumentPathText, findInputType, inputTypeText, namedTypesIn } from "./type-docs.js";
 
 
 const BIN = "typeship";
+/** The MCP server's key in client configs: the API's name, even when this
+ * command was renamed away from a vendor's. It reads this command's login. */
+const MCP_SERVER_KEY = "typeship";
 const DEFAULT_BASE_URL = "https://typeship.dev/api/v1";
 const NAMED_SCHEMES: CredentialSchemes = {"apiKey":{"kind":"bearer","options":["bearerToken"]}};
 const AUTH_SCALARS: { option: string; flag: string; env: string }[] = [{"option":"bearerToken","flag":"token","env":"TYPESHIP_TOKEN"}];
+/** Hosted MCP request headers as name → env reference, never a literal. */
+const HOSTED_MCP_HEADERS: Record<string, string> = {"Authorization":"Bearer ${TYPESHIP_TOKEN}"};
+const HOSTED_MCP_NOTE: string | null = null;
 const BASIC: { envUser: string; envPass: string } | null = null;
+/** Header and query names the API's key schemes use: --dry-run redacts them. */
+const CREDENTIAL_NAMES: string[] = [];
+/** The spec declares no security, so the token is offered, never required. */
+const AUTH_UNDECLARED = false;
+/** Repeated --header "Name: value" flags for this invocation. */
+let HEADER_FLAGS: string[] = [];
 /** Operations omitted from the generated package by its plan cap. */
 const EXCLUDED_OPS = 0;
 /** Generated CLI operations that are intentionally unavailable to MCP. */
 const MCP_EXCLUDED_OPS = 0;
-const VERSION = "0.22.0";
+const VERSION = "0.24.0";
 const API_VERSION = "1.0.0";
 const SPEC_FORMAT = "openapi";
 const IDENTITY_POLICY: IdentityPolicy = {};
@@ -51,10 +67,13 @@ const WHOAMI: { resource: string; method: string } | null = null;
 const ENVIRONMENTS: Record<string, string> = {};
 const HAS_MCP = false;
 const PKG_NAME = "@typeship-ax/cli";
+/** False when the package name was derived rather than chosen: the npm
+ * package of that name may be someone else's, so upgrade never installs it. */
+const PKG_CONFIRMED = true;
 const UPDATE_NOTICE = false;
 const API_DESCRIPTION: string | null = "Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every\nselected CLI, MCP, and SDK Target current.\n\nEvery operation but one requires a bearer credential: an organization\nAPI key from the console, or an OAuth access token carrying the operation's\nread, generate, or write capability and the organization selected during\nconsent. OAuth grants cannot switch organizations after consent. A browser\nsession is not a credential for this API. The exception is POST /generate,\nwhich works anonymously with the free plan's limits.\n\nExamples use Parcel, a fictional delivery service. Replace its domains,\nrepository names, and resource identifiers with your own. The hosted\npetstore Spec is a runnable sample.\n";
-const DOCS_URL_DEFAULT: string | null = "https://typeship.dev";
-const DOCS_INDEX_URL_DEFAULT: string | null = null;
+const DOCS_URL_DEFAULT: string | null = "https://typeship.dev/docs";
+const DOCS_INDEX_URL_DEFAULT: string | null = "https://typeship.dev/llms.txt";
 const RELAY: { mintUrl: string; project: string } | null = null;
 const SUPPORT_URL: string | null = null;
 const OAUTH_TOKEN_URL: string | null = null;
@@ -64,6 +83,9 @@ const OAUTH_DISCOVERY_URLS: string[] = [];
 const OAUTH_DEVICE_URL: string | null = null;
 const HAS_OAUTH_LOGIN = OAUTH_TOKEN_URL !== null || OAUTH_DISCOVERY_URLS.length > 0;
 const OAUTH_LOGIN_METHOD: string = "device";
+/** The loopback port browser login listens on unless the redirect URI names
+ * one: fixed per CLI, so it can be registered with the provider. */
+const OAUTH_DEFAULT_REDIRECT_PORT = 49910;
 const OAUTH_REDIRECT_URI: string | undefined = undefined;
 const OAUTH_ORGANIZATION_PARAMETER: "organization" | "organization_id" | undefined = undefined;
 const OAUTH_AUTHORIZATION_URL: string | undefined = undefined;
@@ -74,7 +96,7 @@ 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";
+const API_TITLE = "Typeship";
 
 interface Parsed {
   positionals: string[];
@@ -91,7 +113,7 @@ interface Parsed {
  * 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 CORE_BOOLEAN_FLAGS = new Set(["all", "version", "non-interactive", "debug", "validate", "yes", "force", "json", "dry-run"]);
 const BUILTIN_BOOLEAN_FLAGS: Record<string, string[]> = {
   login: ["with-token", "no-browser", "device"],
   logout: ["local"],
@@ -99,7 +121,7 @@ const BUILTIN_BOOLEAN_FLAGS: Record<string, string[]> = {
   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", "no-browser"],
-  auth: ["live"],
+  auth: ["live", "offline"],
   doctor: [],
 };
 
@@ -222,25 +244,64 @@ function out(value: unknown): void {
 /** --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, paths: string[][] | null = FIELDS): unknown {
-  if (paths === null) return value;
-  if (Array.isArray(value)) return value.map((item) => project(item, paths));
-  if (value === null || typeof value !== "object") return value;
-  const groups = new Map<string, string[][]>();
-  for (const [key, ...rest] of paths) {
-    if (key === undefined) continue;
-    const group = groups.get(key);
-    if (group) group.push(rest); else groups.set(key, [rest]);
-  }
-  const out: Record<string, unknown> = {};
-  for (const [key, rests] of groups) {
-    const child = (value as Record<string, unknown>)[key];
-    if (child === undefined) continue;
-    if (rests.some((rest) => rest.length === 0)) out[key] = child;
-    else if (child !== null && typeof child === "object") out[key] = project(child, rests);
-  }
-  return out;
+/** --format table: print API results as text for a person instead of JSON. Opt-in only; set in main(). */
+let TABLE = false;
+
+/** An API result on stdout: JSON, or the --format table view of the same value. */
+function printResult(value: unknown, resource: string, collectionField: string | null = null): void {
+  if (!TABLE) { out(value); return; }
+  process.stdout.write(renderTable(value, { width: process.stdout.columns || 120, heading: (text) => paintOut("bold", text), collectionField, resource }));
+}
+
+/** Whether the command being run writes: an --fields mistake on a write
+ * must not tempt anyone into running it again. Set in main(). */
+let FIELDS_AFTER_WRITE = false;
+
+/** Keep only FIELDS of a result: arrays item by item, objects by dotted path;
+ * scalars untouched. A path that matches nothing is an error naming the keys
+ * that exist, never a silent {}; one the response schema declares (an
+ * optional key no item has) is simply absent. */
+function project(value: unknown, perItem: boolean, schema: unknown): unknown {
+  if (FIELDS === null) return value;
+  const unmatched = unmatchedFields(value, FIELDS, schema);
+  if (unmatched.length > 0) failUnmatchedFields(unmatched, perItem, value);
+  return projectFields(value, FIELDS);
+}
+
+/** The declared schema of the list a result holds under `key`. */
+function listSchemaOf(schema: Record<string, unknown> | undefined, key: string): unknown {
+  return (schema?.properties as Record<string, unknown> | undefined)?.[key];
+}
+
+/** --fields over a stream (--all, events): paths no item has matched yet.
+ * The stream is printed as it arrives, so the check fails at its end. */
+function streamFieldsCheck(schema: unknown): { item(value: unknown): unknown; finish(): void } {
+  let pending: ReturnType<typeof unmatchedFields> | null = null;
+  return {
+    item(value: unknown): unknown {
+      if (FIELDS === null) return value;
+      const unmatched = unmatchedFields(value, FIELDS, schema);
+      pending = pending === null ? unmatched : pending.filter((p) => unmatched.some((u) => u.path === p.path));
+      return projectFields(value, FIELDS);
+    },
+    finish(): void {
+      if (pending !== null && pending.length > 0) failUnmatchedFields(pending, true, undefined);
+    },
+  };
+}
+
+function failUnmatchedFields(unmatched: ReturnType<typeof unmatchedFields>, perItem: boolean, result: unknown): never {
+  return failWith({
+    code: "FIELDS_UNMATCHED",
+    message: unmatchedFieldsMessage(unmatched, perItem),
+    nextSteps: [
+      FIELDS_AFTER_WRITE
+        ? "This command has already run; do not run it again to change --fields." + (result !== undefined ? " Its full result is in detail.result." : "")
+        : result !== undefined ? "The full result is in detail.result; use it rather than running the command again." : "",
+      (FIELDS_AFTER_WRITE ? "Next time, use" : "To project a later run, use") + " --fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit --fields for the whole result.",
+    ].filter((step) => step !== ""),
+    detail: { unmatched, ...(result !== undefined ? { result } : {}) },
+  });
 }
 
 /** Thrown after scheduling exit so sync callers stop; main() swallows it. */
@@ -323,7 +384,7 @@ let USAGE_HINT = BIN + " --help";
 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"
+    : /^(Missing required|Expected \d+ (or \d+ )?argument)/.test(message) ? "MISSING_ARGUMENT"
     : "INVALID_USAGE";
   return failWith({
     code: code === 2 ? usageCode : "CALL_FAILED",
@@ -334,8 +395,26 @@ function fail(code: number, message: string, extra?: unknown, nextSteps?: string
 }
 
 /** An SDK error result as an envelope: status-derived code, the API's body as detail, concrete next steps. */
+/** OAuth scopes of the operation being run, so a 403 can name them. */
+let CURRENT_SCOPES: string[] = [];
 function failApi(error: unknown, hadCredential: boolean): never {
-  return failWith(classifyApiError(error, { bin: BIN, hadCredential, docsUrl: DOCS_URL_DEFAULT }));
+  return failWith(classifyAuthFailure(error, authFailureContext()) ?? classifyApiError(error, { bin: BIN, envPrefix: ENV_PREFIX, hadCredential, docsUrl: DOCS_URL_DEFAULT, requiredScopes: CURRENT_SCOPES, canLogin: HAS_OAUTH_LOGIN }));
+}
+
+/** The SDK raises NotModifiedError for a 304: a conditional request
+ * matched. For the CLI that is a result, not a failure. */
+function isNotModified(error: unknown): error is { etag?: string } {
+  return (error as { name?: string } | null)?.name === "NotModifiedError";
+}
+
+function printNotModified(error: { etag?: string }): Promise<never> {
+  out({ ok: true, not_modified: true, ...(error.etag ? { etag: error.etag } : {}) });
+  return flushExit(0);
+}
+
+/** What a login, saved-session or credential-store failure names as alternatives. */
+function authFailureContext(): { bin: string; envVars: string[]; storeVariable: string } {
+  return { bin: BIN, storeVariable: ENV_PREFIX + "_CREDENTIAL_STORE", envVars: [...AUTH_SCALARS.map((a) => a.env), ...(BASIC ? [BASIC.envUser, BASIC.envPass] : []), ...(Object.keys(NAMED_SCHEMES).length ? [ENV_PREFIX + "_CREDENTIALS"] : [])] };
 }
 
 // ---------------------------------------------------------------------------
@@ -353,7 +432,7 @@ function credsPath(): string {
   return credentialStore().path;
 }
 
-function credentialStore(): FileCredentialStore { return createCredentialStore(configDir(), process.env["TYPESHIP_CREDENTIAL_STORE"], "TYPESHIP_CREDENTIAL_STORE"); }
+function credentialStore(): FileCredentialStore { return createCredentialStore(configDir(), BIN, process.env["TYPESHIP_CREDENTIAL_STORE"], "TYPESHIP_CREDENTIAL_STORE"); }
 function readCreds(): StoredCreds | null { return credentialStore().read(); }
 function sessionConfiguration(baseUrl: string, config = readConfig()): SessionConfiguration {
   return {
@@ -492,9 +571,10 @@ async function deviceLogin(clientId: string, parsed: Parsed): Promise<void> {
   if (!apiBaseUrl) fail(2, "Set the API base URL before logging in.");
   const loginConfiguration = sessionConfiguration(apiBaseUrl!);
   await credentialStore().prepare();
+  if (!OAUTH_DEVICE_URL && !OAUTH_ISSUER && !OAUTH_DISCOVERY_URL) fail(2, "This API does not declare device authorization. Run '" + BIN + " login' without --device to sign in through the browser.");
   const session = await withLoginCancellation((signal) => oauthDeviceLogin({
     clientId, issuer: OAUTH_ISSUER, discoveryUrls: OAUTH_DISCOVERY_URLS,
-    deviceUrl: OAUTH_DEVICE_URL, tokenUrl: OAUTH_TOKEN_URL, scopes: OAUTH_SCOPES,
+    deviceUrl: OAUTH_DEVICE_URL, tokenUrl: OAUTH_TOKEN_URL, scopes: loginScopes(parsed.flags),
     audience: OAUTH_TOKEN_PARAMS.audience, resource: OAUTH_TOKEN_PARAMS.resource,
   }, { signal, authorize({ verificationUri, userCode, expiresIn }) {
     process.stderr.write("Open " + paintErr("cyan", verificationUri) + " and enter code: " + paintErr("bold", userCode) + "\n");
@@ -509,11 +589,40 @@ async function deviceLogin(clientId: string, parsed: Parsed): Promise<void> {
   await flushExit(0);
 }
 
-async function storePastedToken(token: string, flags: Map<string, string | boolean>): 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.");
-  await saveLoginCredentials({ scalars: { [first!.option]: token } }, flags);
-  out({ ok: true, method: "paste", stored_as: first!.flag, credentials: credsPath(), ...loginIdentityReport() });
+type LoginValue = string | { username: string; password: string };
+/** What --with-token, the prompt and browser approval store. */
+interface LoginTarget { label: string; basic: boolean; storedAs: string; save(value: LoginValue): StoredCreds }
+
+/** The scheme named by --scheme, else the convenience credential that the
+ * most operations accept on its own (declared order breaks ties), else null. */
+function loginTarget(flags: Map<string, string | boolean>): LoginTarget | null {
+  const requested = flags.get("scheme");
+  if (requested !== undefined) {
+    if (typeof requested !== "string" || !Object.hasOwn(NAMED_SCHEMES, requested)) fail(2, "--scheme expects one of this API's security schemes: " + (Object.keys(NAMED_SCHEMES).join(", ") || "none") + ".");
+    const name = requested as string;
+    return { label: name, basic: NAMED_SCHEMES[name]!.kind === "basic", storedAs: name, save(value) {
+      try { return { named: parseNamedCredentials({ [name]: value }, NAMED_SCHEMES) }; } catch (error) { fail(2, (error as Error).message); }
+    } };
+  }
+  const candidates = [...AUTH_SCALARS.map((a) => a.option), ...(BASIC ? ["basicAuth"] : [])];
+  if (!candidates.length) return null;
+  const uses = (option: string) => OPS.filter((op) => op.credentialOptions?.some((alternative) => alternative.length === 1 && alternative[0] === option)).length;
+  const option = candidates.reduce((best, candidate) => uses(candidate) > uses(best) ? candidate : best);
+  if (option === "basicAuth") return { label: "username and password", basic: true, storedAs: "basic", save: (value) => ({ basic: value as { username: string; password: string } }) };
+  const scalar = AUTH_SCALARS.find((a) => a.option === option)!;
+  return { label: scalar.flag.replace(/-/g, " "), basic: false, storedAs: scalar.flag, save: (value) => ({ scalars: { [scalar.option]: value as string } }) };
+}
+
+/** Basic credentials on stdin are one line: username:password. */
+function basicFromText(text: string): { username: string; password: string } {
+  const separator = text.indexOf(":");
+  if (separator <= 0 || separator === text.length - 1) fail(2, "--with-token expects username:password on stdin for Basic auth.");
+  return { username: text.slice(0, separator), password: text.slice(separator + 1) };
+}
+
+async function storePastedToken(value: LoginValue, target: LoginTarget, flags: Map<string, string | boolean>): Promise<void> {
+  await saveLoginCredentials(target.save(value), flags);
+  out({ ok: true, method: "paste", stored_as: target.storedAs, credentials: credsPath(), ...loginIdentityReport() });
   await flushExit(0);
 }
 
@@ -547,10 +656,9 @@ async function browserApprove(headless: boolean, flags: Map<string, string | boo
 }
 
 /** Store what the browser approval minted, marked as this CLI's own. */
-async function storeMinted(minted: ApprovedCredential, flags: Map<string, string | boolean>): Promise<void> {
-  const first = AUTH_SCALARS[0]!;
+async function storeMinted(minted: ApprovedCredential, target: LoginTarget, flags: Map<string, string | boolean>): Promise<void> {
   await saveLoginCredentials({
-    scalars: { [first.option]: minted.api_key },
+    ...target.save(minted.api_key),
     minted: { via: "browser", key_name: minted.key_name, revocationUrl: minted.revocationUrl, ...(minted.org_id ? { org_id: minted.org_id } : {}) },
   }, flags, undefined, async () => {
     try {
@@ -567,16 +675,37 @@ async function storeMinted(minted: ApprovedCredential, flags: Map<string, string
   });
 }
 
-async function browserLogin(headless: boolean, flags: Map<string, string | boolean>): Promise<void> {
+async function browserLogin(headless: boolean, target: LoginTarget, flags: Map<string, string | boolean>): Promise<void> {
   await credentialStore().prepare();
   const minted = await browserApprove(headless, flags);
-  await storeMinted(minted, flags);
-  out({ ok: true, method: "browser", key_name: minted.key_name, ...(minted.org_id ? { org_id: minted.org_id } : {}), credentials: credsPath(), ...loginIdentityReport() });
+  await storeMinted(minted, target, flags);
+  out({ ok: true, method: "browser", stored_as: target.storedAs, key_name: minted.key_name, ...(minted.org_id ? { org_id: minted.org_id } : {}), credentials: credsPath(), ...loginIdentityReport() });
   await flushExit(0);
 }
 
+/** The callback URL browser login uses: the configured redirect URI, else
+ * http://127.0.0.1:<port>/callback. --redirect-port or
+ * TYPESHIP_OAUTH_REDIRECT_PORT picks another port. */
+function oauthRedirectUri(flags: Map<string, string | boolean>): string {
+  const requested = typeof flags.get("redirect-port") === "string" ? flags.get("redirect-port") as string : process.env["TYPESHIP_OAUTH_REDIRECT_PORT"];
+  const redirect = new URL(OAUTH_REDIRECT_URI ?? "http://127.0.0.1:" + OAUTH_DEFAULT_REDIRECT_PORT + "/callback");
+  if (requested !== undefined) {
+    if (!/^[1-9][0-9]{0,4}$/.test(requested) || Number(requested) > 65535) fail(2, "--redirect-port expects a port number from 1 to 65535.");
+    redirect.port = requested;
+  }
+  return redirect.href;
+}
+
+/** --scopes a,b narrows (or widens) what this login asks for. */
+function loginScopes(flags: Map<string, string | boolean>): string[] {
+  const requested = flags.get("scopes");
+  if (requested === undefined) return OAUTH_SCOPES;
+  if (typeof requested !== "string" || !requested.trim()) fail(2, "--scopes expects a comma- or space-separated list of scopes.");
+  return [...new Set((requested as string).split(/[\s,]+/).filter(Boolean))];
+}
+
 async function acquireOAuthBrowserSession(parsed: Parsed, clientId: string): Promise<void> {
-  if (!OAUTH_ISSUER) fail(2, "Browser OAuth requires the exact auth.oauth_issuer configured by the API owner.");
+  if (!OAUTH_ISSUER && !OAUTH_AUTHORIZATION_URL) fail(2, "Browser OAuth needs an authorization URL: the API Spec's authorizationCode flow, or auth.oauth_server.issuer configured by the API owner.");
   const apiBaseUrl = resolveBaseUrl(parsed.flags);
   if (!apiBaseUrl) fail(2, "Set the API base URL before logging in.");
   const loginConfiguration = sessionConfiguration(apiBaseUrl!);
@@ -588,7 +717,7 @@ async function acquireOAuthBrowserSession(parsed: Parsed, clientId: string): Pro
   } }, parsed.flags, loginConfiguration);
 }
 
-/** Normal login and Console verification use the same native exchange. */
+/** The native browser exchange. */
 async function startOAuthBrowserSession(parsed: Parsed, clientId: string, timeoutMs?: number): Promise<OAuthLoginSession> {
   const controller = new AbortController();
   const cancel = () => controller.abort();
@@ -596,9 +725,9 @@ async function startOAuthBrowserSession(parsed: Parsed, clientId: string, timeou
   process.once("SIGTERM", cancel);
   try {
     return await oauthBrowserLogin({
-      issuer: OAUTH_ISSUER!, clientId, discoveryUrl: OAUTH_DISCOVERY_URL,
+      issuer: OAUTH_ISSUER, clientId, discoveryUrl: OAUTH_DISCOVERY_URL,
       authorizationUrl: OAUTH_AUTHORIZATION_URL, tokenUrl: OAUTH_TOKEN_URL ?? undefined,
-      redirectUri: OAUTH_REDIRECT_URI, scopes: OAUTH_SCOPES,
+      redirectUri: oauthRedirectUri(parsed.flags), scopes: loginScopes(parsed.flags),
       audience: OAUTH_TOKEN_PARAMS.audience, resource: OAUTH_TOKEN_PARAMS.resource,
       organization: requestedLoginOrganization(parsed.flags),
     }, { signal: controller.signal, timeoutMs, authorize(url) {
@@ -609,56 +738,23 @@ async function startOAuthBrowserSession(parsed: Parsed, clientId: string, timeou
   } finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
 }
 
-async function cmdConsoleLoginCheck(parsed: Parsed): Promise<void> {
-  const file = parsed.flags.get("console-check");
-  if (typeof file !== "string" || !file || parsed.flags.get("device") === true || parsed.flags.get("with-token") === true || explicitNonInteractive(parsed)) fail(2, "--console-check requires a downloaded JSON file and browser login. Use --no-browser to print the sign-in link.");
-  const baseUrl = resolveBaseUrl(parsed.flags);
-  const clientId = (typeof parsed.flags.get("client-id") === "string" ? parsed.flags.get("client-id") as string : undefined) ?? process.env[ENV_PREFIX + "_CLIENT_ID"] ?? OAUTH_CLIENT_ID;
-  const op = WHOAMI && OPS.find((value) => value.resource === WHOAMI.resource && value.method === WHOAMI.method);
-  if (!baseUrl || !OAUTH_ISSUER || !clientId || OAUTH_LOGIN_METHOD !== "browser" || !op || op.auth !== "required" || !op.security?.length) fail(2, "Configure browser OAuth and a required-authentication identity read, then regenerate this CLI.");
-  const envOptions: Record<string, unknown> = {}, flagOptions: Record<string, unknown> = {};
-  for (const scalar of AUTH_SCALARS) {
-    if (process.env[scalar.env] !== undefined) envOptions[scalar.option] = process.env[scalar.env];
-    if (typeof parsed.flags.get(scalar.flag) === "string") flagOptions[scalar.option] = parsed.flags.get(scalar.flag);
-  }
-  if (BASIC && process.env[BASIC.envUser] && process.env[BASIC.envPass]) envOptions.basicAuth = { username: process.env[BASIC.envUser], password: process.env[BASIC.envPass] };
-  if (BASIC && typeof parsed.flags.get("username") === "string" && typeof parsed.flags.get("password") === "string") flagOptions.basicAuth = { username: parsed.flags.get("username"), password: parsed.flags.get("password") };
-  const environment = (typeof parsed.flags.get("environment") === "string" ? parsed.flags.get("environment") as string : Object.entries(ENVIRONMENTS).find(([, url]) => new URL(url).href === new URL(baseUrl!).href)?.[0]) ?? null;
-  const result = await checkConsoleBrowserLogin({
-    file: file as string, configuration: {
-      baseUrl: baseUrl!, environment, operation: op!.resource + "." + op!.method, requirements: op!.security!,
-      request: { method: op!.graphql ? "POST" : op!.httpMethod, path: op!.graphql ? "" : op!.path, graphqlField: op!.graphql?.field ?? null, graphqlQuery: op!.graphql ? op!.graphql.docPrefix + op!.graphql.defaultSelection + " }" : null },
-      issuer: OAUTH_ISSUER!, clientId: clientId!, discoveryUrl: OAUTH_DISCOVERY_URL ?? null,
-      authorizationUrl: OAUTH_AUTHORIZATION_URL ?? null, tokenUrl: OAUTH_TOKEN_URL,
-      redirectUri: OAUTH_REDIRECT_URI ?? "http://127.0.0.1/callback", scopes: OAUTH_SCOPES,
-      audience: OAUTH_TOKEN_PARAMS.audience ?? null, resource: OAUTH_TOKEN_PARAMS.resource ?? null,
-    }, schemes: NAMED_SCHEMES,
-    credentials: resolveNamedCredentials(NAMED_SCHEMES, [{ options: envOptions, named: environmentCredentials() }, { options: flagOptions, named: flagCredentials(parsed.flags) }]),
-    login: (timeoutMs) => startOAuthBrowserSession(parsed, clientId!, timeoutMs),
-    async verify(credentials, expectations) {
-      const kind = (value: "user" | "account" | "organization") => value === "user" ? "subject" : value;
-      const policy = Object.fromEntries(expectations.map((entry) => [kind(entry.kind), entry.pointer])) as IdentityPolicy;
-      const expected = Object.fromEntries(expectations.map((entry) => [kind(entry.kind), String(entry.expected)])) as ApiIdentity;
-      await verifyClientIdentity((options) => new TypeshipClient(options as unknown as ClientOptions), { baseUrl: baseUrl!,  credentials }, op!, policy, expected);
-    },
-    progress: (message) => process.stderr.write(message + "\n"),
-  });
-  out(result);
-  await flushExit(0);
-}
 
 async function cmdLogin(parsed: Parsed): Promise<void> {
   if (parsed.help) {
+    const target = loginTarget(new Map());
     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)",
-      ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --client-id <id>       OAuth " + OAUTH_LOGIN_METHOD + " login" + (OAUTH_CLIENT_ID ? " (a default id is built in)" : "")] : []),
-      ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --no-browser           print the approval URL instead of opening a browser", "  " + BIN + " login --device               use device authorization when your provider supports it"] : []),
+      ...(CLI_AUTH_URL && target && !target.basic ? ["  " + BIN + " login                        approve in the browser: a key is minted for you (add --no-browser to print the link instead of opening it)"] : []),
+      ...(target ? ["  " + BIN + " login --with-token           read the " + target.label + " from stdin" + (target.basic ? " as one username:password line" : "") + " (CI)"] : []),
+      ...(Object.keys(NAMED_SCHEMES).length > 1 || (!target && Object.keys(NAMED_SCHEMES).length) ? ["  " + BIN + " login --scheme <name>        choose the scheme --with-token, the prompt" + (CLI_AUTH_URL ? " and browser approval" : "") + " store" + (target ? " (default: " + target.storedAs + ")" : "") + "; a Basic scheme reads username:password"] : []),
+      ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --client-id <id>       OAuth " + (OAUTH_LOGIN_METHOD === "browser" ? "browser (authorization code + PKCE)" : "device") + " login" + (OAUTH_CLIENT_ID ? " (a default id is built in)" : "; register an application with the provider for its client ID, or set " + ENV_PREFIX + "_CLIENT_ID")] : []),
+      ...(HAS_OAUTH_LOGIN && OAUTH_LOGIN_METHOD === "browser" ? ["  " + BIN + " login --no-browser           print the sign-in URL instead of opening a browser", "  " + BIN + " login --redirect-port <n>    listen on another loopback port (default callback " + oauthRedirectUri(new Map()) + "; register it with the provider)"] : []),
+      ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --scopes <a,b>         request these scopes instead of " + (OAUTH_SCOPES.length ? OAUTH_SCOPES.join(" ") : "the provider's defaults")] : []),
+      ...(HAS_OAUTH_LOGIN && (OAUTH_DEVICE_URL || OAUTH_ISSUER || OAUTH_DISCOVERY_URL) ? ["  " + BIN + " login --device               use device authorization when your provider supports it"] : []),
       ...(BASIC ? ["  " + BIN + " login --username <u> --password <p>"] : []),
-      ...(CLI_AUTH_URL || HAS_OAUTH_LOGIN ? [] : ["  " + BIN + " login                        interactive prompt (TTY only)"]),
+      ...(CLI_AUTH_URL || HAS_OAUTH_LOGIN || !target ? [] : ["  " + BIN + " login                        interactive prompt" + (target.basic ? " for username and hidden password" : "") + " (TTY only)"]),
       "",
       "Precedence per scheme: flags > env vars > stored credentials. Named inputs beat convenience flags within the same source.",
       "  " + BIN + " login --credentials @<JSON-file>   store named credentials (use - for stdin)",
@@ -674,9 +770,8 @@ async function cmdLogin(parsed: Parsed): Promise<void> {
   }
   if (parsed.flags.has("login-organization")) {
     expectedLoginIdentity(parsed.flags);
-    if (!HAS_OAUTH_LOGIN || OAUTH_LOGIN_METHOD !== "browser" || parsed.flags.has("device") || parsed.flags.has("console-check") || parsed.flags.has("with-token") || explicitNonInteractive(parsed)) fail(2, "--login-organization is available only for interactive OAuth browser login, including --no-browser.");
+    if (!HAS_OAUTH_LOGIN || OAUTH_LOGIN_METHOD !== "browser" || parsed.flags.has("device") || parsed.flags.has("with-token") || explicitNonInteractive(parsed)) fail(2, "--login-organization is available only for interactive OAuth browser login, including --no-browser.");
   }
-  if (parsed.flags.has("console-check")) { await cmdConsoleLoginCheck(parsed); return; }
   const named = flagCredentials(parsed.flags);
   const scalarValues: Record<string, string> = {};
   for (const a of AUTH_SCALARS) {
@@ -698,9 +793,11 @@ async function cmdLogin(parsed: Parsed): Promise<void> {
   }
 
   if (parsed.flags.get("with-token") === true) {
+    const target = loginTarget(parsed.flags);
+    if (!target) fail(2, "This API declares no credential the CLI can store. See '" + BIN + " login --help'.");
     const token = (await readStdin()).trim();
     if (!token) fail(2, "--with-token expects the credential on stdin.");
-    await storePastedToken(token, parsed.flags);
+    await storePastedToken(target!.basic ? basicFromText(token) : token, target!, parsed.flags);
   }
 
   const clientId = (typeof parsed.flags.get("client-id") === "string" ? parsed.flags.get("client-id") as string : undefined)
@@ -717,8 +814,9 @@ async function cmdLogin(parsed: Parsed): Promise<void> {
   // 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(isAgentMode(parsed) || parsed.flags.get("no-browser") === true, parsed.flags);
+  const target = loginTarget(parsed.flags);
+  if (CLI_AUTH_URL && target && !target.basic && !explicitNonInteractive(parsed)) {
+    await browserLogin(isAgentMode(parsed) || parsed.flags.get("no-browser") === true, target, parsed.flags);
   }
 
   if (nonInteractive(parsed) || !process.stdin.isTTY) {
@@ -728,17 +826,24 @@ async function cmdLogin(parsed: Parsed): Promise<void> {
       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",
+        ...(BASIC ? ["Pass Basic credentials: '" + BIN + " login --username <u> --password <p>', or set " + BASIC.envUser + " and " + BASIC.envPass + " in the environment."] : []),
+        ...(target ? ["Pipe it: echo \"" + (target.basic ? "$USERNAME:$PASSWORD" : "$TOKEN") + "\" | " + BIN + " login --with-token" + (parsed.flags.has("scheme") ? " --scheme " + target.storedAs : "")] : []),
         ...(HAS_OAUTH_LOGIN ? ["OAuth login (or --device when supported by your provider): '" + BIN + " login --client-id <id>' (opens or prints the provider sign-in URL)."] : []),
         ...(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 (!target) fail(2, "This API declares no credential the CLI can prompt for. See '" + BIN + " login --help'.");
+  if (target!.basic) {
+    process.stderr.write("Username: ");
+    const username = (await readLine()).trim();
+    const password = await promptHidden("Password (input hidden): ");
+    if (!username || !password) fail(2, "Enter both a username and a password.");
+    await storePastedToken({ username, password }, target!, parsed.flags);
+  }
+  const token = (await promptHidden("Paste " + target!.label + " (input hidden): ")).trim();
   if (!token) fail(2, "Nothing entered.");
-  await storePastedToken(token, parsed.flags);
+  await storePastedToken(token, target!, parsed.flags);
 }
 
 async function cmdLogout(parsed: Parsed): Promise<void> {
@@ -753,8 +858,8 @@ async function cmdLogout(parsed: Parsed): Promise<void> {
   // 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;
+  // The approval stored exactly one credential, as a scalar or a named scheme.
+  const ownKey = stored?.minted?.via === "browser" ? [...Object.values(stored.scalars ?? {}), ...Object.values(stored.named ?? {})].find((value): value is string => typeof value === "string") : undefined;
   if (ownKey) {
     try {
       const response = await oauthStatusRequest(loginEndpoint(stored!.minted!.revocationUrl!), { method: "POST", headers: { Authorization: "Bearer " + ownKey } }, 15_000);
@@ -915,12 +1020,12 @@ function mcpEntryFor(url: string | undefined, readOnly = false): { entry: McpEnt
   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 (readOnly && url !== undefined && !MCP_URL) warnings.push("--read-only appended /readonly to the URL; check that this server serves a read-only endpoint there.");
+    if (HOSTED_MCP_NOTE) warnings.push(HOSTED_MCP_NOTE);
+    return { entry: { url: target, ...(Object.keys(HOSTED_MCP_HEADERS).length ? { headers: { ...HOSTED_MCP_HEADERS } } : {}) }, 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.");
@@ -992,7 +1097,7 @@ async function cmdMcp(parsed: Parsed): Promise<void> {
 
   if (wanted.size === 0) {
     out({
-      server: BIN,
+      server: MCP_SERVER_KEY,
       entry,
       ...(warnings.length > 0 ? { warnings } : {}),
       detected: MCP_CLIENTS.filter((c) => c.detect(cwd)).map((c) => c.id),
@@ -1003,11 +1108,11 @@ async function cmdMcp(parsed: Parsed): Promise<void> {
   const results: McpWriteResult[] = [];
   for (const id of wanted) {
     const client = findMcpClient(id)!;
-    results.push(writeMcpConfig(client, cwd, BIN, entry));
+    results.push(writeMcpConfig(client, cwd, MCP_SERVER_KEY, entry));
   }
   out({
     ok: true,
-    server: BIN,
+    server: MCP_SERVER_KEY,
     entry,
     written: results.filter((r) => r.written).map((r) => r.file),
     clients: results,
@@ -1029,10 +1134,11 @@ function agentContext(): AgentContext {
     version: VERSION,
     envPrefix: ENV_PREFIX,
     authEnvVars: [...AUTH_SCALARS.map((a) => a.env), ...(BASIC ? [BASIC.envUser, BASIC.envPass] : []), ...(Object.keys(NAMED_SCHEMES).length ? ["TYPESHIP_CREDENTIALS"] : [])],
+    ...(AUTH_UNDECLARED ? { authNotDeclared: true } : {}),
     docsUrl: docsSiteUrl(),
     docsIndexUrl: docsIndexUrl(),
     generatedOperationCount: OPS.length,
-    omittedOperations: OMITTED_OPS.map((op) => ({ command: op.command.join(" "), tool: op.tool, method: op.httpMethod, path: op.path })),
+    omittedOperationCount: OMITTED_OPS.length,
     mcpUrl: MCP_URL,
     skillsRepo: SKILLS_REPO,
     hasMcp: HAS_MCP,
@@ -1055,63 +1161,173 @@ function commandSummaries(): CommandSummary[] {
 }
 
 /**
- * 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.
+ * help --json: discovery as data, bounded so one call cannot fill an agent's
+ * context window on a large API. The default is an index of resources and
+ * command names; "help <resource> --json" pages through one resource's
+ * commands with their methods, paths and summaries; "help <resource>
+ * <command> --json" is one command with its flags; "help --json --all" is
+ * every command with every flag. Full schemas stay behind the docs command.
  */
-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);
+const HELP_INDEX_NAMES = 40;
+const HELP_INDEX_BYTES = 16_000;
+const HELP_PAGE_SIZE = 50;
+
+function helpHeader(detail: "index" | "resource" | "command" | "all"): Record<string, unknown> {
+  return { schema_version: "3", detail, name: BIN, version: VERSION, api: API_TITLE, api_version: API_VERSION, spec_format: SPEC_FORMAT };
+}
+
+function helpDiscovery(): Record<string, string> {
+  return {
+    resource: BIN + " help <resource> --json",
+    command: BIN + " help <resource> <command> --json",
+    search: BIN + " docs search <term> --json",
+    operation: BIN + " docs <resource> <command> --json",
+    all: BIN + " help --json --all",
+    note: "Find a command by resource or search, read its flags with help <resource> <command> --json, and its complete schemas with docs. --all prints every command with every flag at once.",
+  };
+}
+
+function helpCoverage(): Record<string, unknown> {
+  return EXCLUDED_OPS > 0 ? { coverage: { generated_operations: OPS.length, total_operations: OPS.length + EXCLUDED_OPS } } : {};
+}
+
+function opsByResource(): Map<string, OpSpec[]> {
+  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);
   }
+  return byResource;
+}
+
+/** One command with its flags: an entry of help --json --all. */
+function helpEntry(op: OpSpec, summary: CommandSummary): Record<string, unknown> {
   return {
-    schema_version: "2",
-    name: BIN,
-    version: VERSION,
-    api: API_TITLE,
-    api_version: API_VERSION,
-    spec_format: SPEC_FORMAT,
+    command: op.command[1],
+    method: summary.method,
+    path: summary.path,
+    ...(summary.summary ? { summary: summary.summary } : {}),
+    paginated: summary.paginated,
+    safety: op.safety,
+    destructive: summary.destructive,
+    auth: summary.auth,
+    positional: op.params.filter((p) => p.kind === "path").map((p) => p.name),
+    flags: summary.flags,
+    details_command: BIN + " docs " + op.command[0] + " " + op.command[1] + " --json",
+  };
+}
+
+function helpAll(): Record<string, unknown> {
+  const summaries = commandSummaries();
+  const byResource = opsByResource();
+  return {
+    ...helpHeader("all"),
     usage: BIN + " <resource> <command> [args] [--flags]",
-    resources: [...byResource.entries()].map(([resource, commands]) => ({
+    resources: [...byResource.entries()].map(([resource, ops]) => ({
       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",
-        };
-      }),
+      commands: ops.map((op) => helpEntry(op, summaries[OPS.indexOf(op)]!)),
     })),
-    ...(EXCLUDED_OPS > 0 ? {
-      coverage: {
-        generated_operations: OPS.length,
-        total_operations: OPS.length + EXCLUDED_OPS,
-        omitted_operations: OMITTED_OPS.map((op) => ({ command: op.command.join(" "), tool: op.tool, method: op.httpMethod, path: op.path })),
-        reason: "plan_limit",
-      },
-    } : {}),
-    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.",
-    },
+    ...helpCoverage(),
+    discovery: helpDiscovery(),
     builtins: BUILTIN_COMMANDS,
-    global_flags: ["--help", "--version", "--debug", "--non-interactive", "--mode agent|human", "--yes", "--force", "--color on|off|auto", "--credentials @<JSON-file>|-", "--base-url <url>", "--profile <name>", "--data '<json>' | @<file> | -", "--fields <a,b.c>", "--all", "--validate", "--out <dir>", ...AUTH_SCALARS.map((a) => "--" + a.flag + " <value>")],
+    global_flags: ["--help", "--version", "--debug", "--non-interactive", "--mode agent|human", "--yes", "--force", "--color on|off|auto", "--credentials @<JSON-file>|-", "--header 'Name: value'", "--timeout <seconds>", "--base-url <url>", "--profile <name>", "--data '<json>' | @<file> | -", "--fields <a,b.c>", "--all", "--validate", "--dry-run", "--out <dir>", ...AUTH_SCALARS.map((a) => "--" + a.flag + " <value>")],
     auth_env_vars: agentContext().authEnvVars,
   };
 }
 
+/** Resources and command names. Past HELP_INDEX_BYTES a resource keeps only its count. */
+function helpIndex(): Record<string, unknown> {
+  const all = helpAll();
+  let bytes = 0;
+  let overBudget = false;
+  let truncated = false;
+  const resources = [...opsByResource().entries()].map(([resource, ops]) => {
+    const names = ops.map((op) => op.command[1]);
+    const entry = { resource, command_count: names.length, commands: names.slice(0, HELP_INDEX_NAMES) };
+    const size = JSON.stringify(entry).length;
+    if (overBudget || bytes + size > HELP_INDEX_BYTES) { overBudget = truncated = true; return { resource, command_count: names.length }; }
+    bytes += size;
+    if (names.length > HELP_INDEX_NAMES) truncated = true;
+    return entry;
+  });
+  return {
+    ...helpHeader("index"),
+    usage: all.usage,
+    command_count: OPS.length,
+    resource_count: resources.length,
+    resources,
+    ...(truncated ? { truncated: "Some resources list only their first " + HELP_INDEX_NAMES + " command names or only a count. Run " + BIN + " help <resource> --json for a resource's commands." } : {}),
+    ...helpCoverage(),
+    discovery: all.discovery,
+    builtins: all.builtins,
+    global_flags: all.global_flags,
+    auth_env_vars: all.auth_env_vars,
+  };
+}
+
+function helpTarget(resource: string, method: string | undefined): OpSpec[] {
+  const ops = opsByResource().get(resource);
+  if (!ops) {
+    const omitted = omittedCommand(resource, method);
+    if (omitted) failOmitted(omitted);
+    const suggestion = didYouMean(resource, opsByResource().keys());
+    fail(2, "Unknown command: " + resource + "." + (suggestion ? " Did you mean '" + BIN + " help " + suggestion + " --json'?" : ""),
+      undefined, ["Run '" + BIN + " help --json' for the resources and their commands."]);
+  }
+  if (method === undefined) return ops!;
+  const op = findOp(resource, method);
+  if (!op) {
+    const omitted = omittedCommand(resource, method);
+    if (omitted) failOmitted(omitted);
+    const suggestion = didYouMean(method, ops!.map((o) => o.command[1]));
+    fail(2, "Unknown command: " + resource + " " + method + "." + (suggestion ? " Did you mean '" + BIN + " help " + resource + " " + suggestion + " --json'?" : ""),
+      undefined, ["Run '" + BIN + " help " + resource + " --json' for its commands."]);
+  }
+  return [op!];
+}
+
+async function cmdHelpJson(parsed: Parsed): Promise<void> {
+  const [, resource, method, extra] = parsed.positionals;
+  if (extra !== undefined) fail(2, "help --json takes at most a resource and a command.", undefined, ["Run '" + BIN + " help --json' for the index."]);
+  const all = parsed.flags.get("all") === true;
+  const pageFlag = parsed.flags.get("page");
+  const page = pageFlag === undefined ? 1 : Number(pageFlag);
+  if (!Number.isInteger(page) || page < 1) fail(2, "--page expects a whole number from 1.");
+  if (resource === undefined) {
+    if (pageFlag !== undefined) fail(2, "--page applies to help <resource> --json.");
+    out(all ? helpAll() : helpIndex());
+    await flushExit(0);
+  }
+  const ops = helpTarget(resource!, method);
+  const summaries = commandSummaries();
+  if (method !== undefined) {
+    out({ ...helpHeader("command"), resource, ...helpEntry(ops[0]!, summaries[OPS.indexOf(ops[0]!)]!) });
+    await flushExit(0);
+  }
+  if (all) {
+    out({ ...helpHeader("resource"), resource, command_count: ops.length, commands: ops.map((op) => helpEntry(op, summaries[OPS.indexOf(op)]!)) });
+    await flushExit(0);
+  }
+  const pages = Math.max(1, Math.ceil(ops.length / HELP_PAGE_SIZE));
+  if (page > pages) fail(2, "--page " + page + " is past the last page (" + pages + ") of " + resource + ".", undefined, ["Run '" + BIN + " help " + resource + " --json' for the first page."]);
+  const commands = ops.slice((page - 1) * HELP_PAGE_SIZE, page * HELP_PAGE_SIZE).map((op) => {
+    const s = summaries[OPS.indexOf(op)]!;
+    return { command: op.command[1], method: s.method, path: s.path, ...(s.summary ? { summary: s.summary } : {}), paginated: s.paginated, safety: op.safety, positional: op.params.filter((p) => p.kind === "path").map((p) => p.name) };
+  });
+  out({
+    ...helpHeader("resource"),
+    resource,
+    command_count: ops.length,
+    page,
+    pages,
+    commands,
+    ...(page < pages ? { next_command: BIN + " help " + resource + " --json --page " + (page + 1) } : {}),
+    discovery: { command: BIN + " help " + resource + " <command> --json", operation: BIN + " docs " + resource + " <command> --json", all: BIN + " help " + resource + " --json --all" },
+  });
+  await flushExit(0);
+}
+
 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");
@@ -1139,24 +1355,26 @@ async function cmdAuth(parsed: Parsed): Promise<void> {
   }
   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, ...}",
+      BIN + " auth check [--offline] — report the credential the CLI would use and verify it with the API's identity read, as JSON: {status: ok|action_required, authenticated, verification: verified|unverified|rejected, source, ...}",
       "  " + BIN + " auth profiles                 list profiles without unlocking credentials",
       "  " + BIN + " auth use <name>               select the default profile",
       "  " + BIN + " auth remove <name>            remove a profile after logout",
       "  --profile <name> overrides TYPESHIP_PROFILE, then the saved selection, then default.",
-      "  --live   also call the API's identity endpoint" + (WHOAMI ? "" : " (none in this API; --live is a no-op)"),
+      "  --offline  skip the identity read; the credential is then reported as unverified" + (WHOAMI ? "" : " (this API has no identity read, so credentials are always unverified)"),
       "",
       "Precedence: flags > env vars > stored credentials (" + credsPath() + ").",
     ].join("\n") + "\n");
     await flushExit(parsed.help ? 0 : 2);
   }
   const source = credentialSource(parsed.flags) ?? "none";
-  const authenticated = source !== "none";
+  const present = source !== "none";
   const savedIdentity = source === "login" ? readCreds() : null;
   if (savedIdentity) assertStoredIdentity(savedIdentity, identityConfiguration());
+  // A credential counts as authenticated only once the API accepted it.
   const report: Record<string, unknown> = {
-    status: authenticated ? "ok" : "action_required",
-    authenticated,
+    status: present ? "ok" : "action_required",
+    authenticated: false,
+    verification: present ? "unverified" : "none",
     source,
     credentials_path: existsSync(credsPath()) ? credsPath() : null,
     credential_storage: credentialStore().backend,
@@ -1164,12 +1382,13 @@ async function cmdAuth(parsed: Parsed): Promise<void> {
     profile: PROFILE.name, profile_source: PROFILE.source,
     auth_env_vars: agentContext().authEnvVars,
     base_url: resolveBaseUrl(parsed.flags) ?? null,
-    next_steps: authenticated ? [] : [
+    next_steps: present ? [WHOAMI ? "Run '" + BIN + " auth check' without --offline to verify the credential." : "This API has no identity read, so the credential was not checked. Run a read command to confirm the API accepts it."] : [
       ...AUTH_SCALARS.map((a) => "Set " + a.env + " in the environment, or run '" + BIN + " login --" + a.flag + " <value>'."),
-      "Then run '" + BIN + " auth check --live'.",
+      ...(AUTH_UNDECLARED ? ["The API Spec does not declare authentication. Add another header with --header \"Name: value\" or TYPESHIP_HEADERS."] : []),
+      ...(WHOAMI ? ["Then run '" + BIN + " auth check'."] : []),
     ],
   };
-  if (authenticated && parsed.flags.get("live") === true && WHOAMI) {
+  if (present && parsed.flags.get("offline") !== true && WHOAMI) {
     const op = OPS.find((o) => o.resource === WHOAMI.resource && o.method === WHOAMI.method);
     if (op) {
       const client = await makeClient(parsed.flags, op);
@@ -1178,9 +1397,12 @@ async function cmdAuth(parsed: Parsed): Promise<void> {
       if (result.ok) {
         if (identityConfiguration() && savedIdentity?.identity) assertApiIdentity(savedIdentity.identity.values, readApiIdentity(result.data, IDENTITY_POLICY));
         report.identity = result.data;
+        // An identity read that also answers anonymous callers proves nothing.
+        if (op.auth !== "none") { report.authenticated = true; report.verification = "verified"; report.next_steps = []; }
       }
       else {
-        const why = classifyApiError(result.error, { bin: BIN, hadCredential: true, docsUrl: DOCS_URL_DEFAULT });
+        const why = classifyApiError(result.error, { bin: BIN, envPrefix: ENV_PREFIX, hadCredential: true, docsUrl: DOCS_URL_DEFAULT });
+        report.verification = "rejected";
         report.status = "action_required";
         report.live = { ok: false, code: why.code, message: why.message };
         report.next_steps = why.nextSteps ?? [];
@@ -1209,7 +1431,13 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
   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 });
+      void response.body?.cancel().catch(() => {});
+      const reachable = response.status >= 200 && response.status < 300;
+      checks.push({ name: "base_url", ok: reachable, detail: baseUrl + " → HTTP " + response.status, ...(reachable ? {} : { fix: response.status === 404 || response.status === 405
+        ? "The API does not answer at this base URL. Check --base-url / " + ENV_PREFIX + "_BASE_URL, or run '" + BIN + " upgrade' if this CLI is older than the API."
+        : response.status === 401 || response.status === 403
+          ? "The API answered without a credential with HTTP " + response.status + "; the identity check below tests the credential."
+          : "The API answered HTTP " + response.status + ". Check the base URL and the API's 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." });
     }
@@ -1223,7 +1451,13 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
         const client = await makeClient(parsed.flags, op);
         const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; error?: unknown }>>>)[op.resource]!;
         const result = await asApiResult(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." });
+        const status = (result.error as { status?: unknown } | undefined)?.status;
+        checks.push(result.ok ? { name: "identity", ok: true, detail: op.command.join(" ") + " ok" } : { name: "identity", ok: false, detail: classifyApiError(result.error, { bin: BIN, envPrefix: ENV_PREFIX, hadCredential: true, docsUrl: DOCS_URL_DEFAULT }).message,
+          // Only 401 and 403 are about the credential. A 404 or 405 means the
+          // API no longer has this endpoint where this CLI version expects it.
+          fix: status === 401 || status === 403 ? "The credential was rejected; run '" + BIN + " login' with a current one."
+            : status === 404 || status === 405 ? "The API does not know " + wireOf(op) + ", which this CLI version calls. Run '" + BIN + " upgrade', and check the base URL."
+            : "The identity read failed; the detail says why." });
       } catch (e) {
         checks.push({ name: "identity", ok: false, detail: (e as Error).message });
       }
@@ -1236,7 +1470,7 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
   }
   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 configured = MCP_CLIENTS.filter((c) => c.detect(cwd) && mcpConfigured(c, cwd, MCP_SERVER_KEY)).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'." } : {}) });
   }
@@ -1276,13 +1510,18 @@ async function cmdInit(parsed: Parsed): Promise<void> {
   const first = AUTH_SCALARS[0];
   const named = flagCredentials(parsed.flags), envNamed = environmentCredentials();
   const stored: StoredCreds = Object.keys(named).length || Object.keys(envNamed).length || first && process.env[first.env] ? {} : readCreds() ?? {};
-  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);
+  // -k stores the credential login would store; --<flag> stores that scalar.
+  const target = loginTarget(parsed.flags);
+  const keyValue = typeof parsed.flags.get("k") === "string" ? parsed.flags.get("k") as string : undefined;
+  const flagValue = first && typeof parsed.flags.get(first.flag) === "string" ? parsed.flags.get(first.flag) as string : undefined;
   if (Object.keys(named).length) {
     await saveLoginCredentials({ named }, parsed.flags);
     report.credential = { status: "stored", path: credsPath() };
-  } else if (given && first) {
-    await saveLoginCredentials({ scalars: { [first.option]: given } }, parsed.flags);
+  } else if (keyValue && target && !target.basic) {
+    await saveLoginCredentials(target.save(keyValue), parsed.flags);
+    report.credential = { status: "stored", path: credsPath() };
+  } else if ((keyValue ?? flagValue) && first) {
+    await saveLoginCredentials({ scalars: { [first.option]: (keyValue ?? flagValue)! } }, parsed.flags);
     report.credential = { status: "stored", path: credsPath() };
   } else if (first && process.env[first.env]) {
     report.credential = { status: "env", variable: first.env };
@@ -1293,13 +1532,13 @@ async function cmdInit(parsed: Parsed): Promise<void> {
   } else if (first && HAS_OAUTH_LOGIN && OAUTH_LOGIN_METHOD === "browser" && (process.env[ENV_PREFIX + "_CLIENT_ID"] ?? OAUTH_CLIENT_ID) && !explicitNonInteractive(parsed)) {
     await acquireOAuthBrowserSession(parsed, (process.env[ENV_PREFIX + "_CLIENT_ID"] ?? OAUTH_CLIENT_ID)!);
     report.credential = { status: "stored", method: "oauth_browser", path: credsPath() };
-  } else if (first && CLI_AUTH_URL && !explicitNonInteractive(parsed)) {
+  } else if (target && !target.basic && 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.
     await credentialStore().prepare();
     const minted = await browserApprove(isAgentMode(parsed) || parsed.flags.get("no-browser") === true, parsed.flags);
-    await storeMinted(minted, parsed.flags);
+    await storeMinted(minted, target, parsed.flags);
     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" };
@@ -1317,7 +1556,7 @@ async function cmdInit(parsed: Parsed): Promise<void> {
   } 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));
+    const results = clients.map((c) => writeMcpConfig(c, cwd, MCP_SERVER_KEY, 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.");
   }
@@ -1331,7 +1570,7 @@ async function cmdInit(parsed: Parsed): Promise<void> {
     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 + " auth check'" + (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);
@@ -1357,6 +1596,7 @@ function registryBase(): string {
 }
 
 async function latestVersion(timeoutMs: number): Promise<string | null> {
+  if (!PKG_CONFIRMED) return null;
   try {
     const response = await fetch(registryBase() + "/" + PKG_NAME, {
       headers: { Accept: "application/vnd.npm.install-v1+json" },
@@ -1383,6 +1623,9 @@ async function cmdUpgrade(parsed: Parsed): Promise<void> {
     process.stdout.write(lines.join("\n") + "\n");
     await flushExit(0);
   }
+  if (!PKG_CONFIRMED) {
+    fail(1, "This build's package name (" + PKG_NAME + ") was not confirmed when it was generated, so upgrade does not look it up on npm, where that name may belong to another package. This package updates by regeneration from its API spec; get the latest from the API provider.");
+  }
   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.");
@@ -1434,7 +1677,7 @@ function completionFlagsFor(op: OpSpec): { flags: string[]; values: Record<strin
   return { flags, values };
 }
 
-const COMPLETION_GLOBAL_FLAGS = ["--help", "--version", "--non-interactive", "--color", "--credentials", "--base-url", "--profile", "--data", "--fields", "--all", "--validate", "--debug", "--mode", "--yes", "--force", "--out", ...AUTH_SCALARS.map((a) => "--" + a.flag)];
+const COMPLETION_GLOBAL_FLAGS = ["--help", "--version", "--non-interactive", "--color", "--credentials", "--header", "--timeout", "--base-url", "--profile", "--data", "--fields", "--all", "--validate", "--dry-run", "--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"],
@@ -1574,34 +1817,6 @@ async function fetchDocs(pathOrFile: string): Promise<string | 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)));
@@ -1620,7 +1835,9 @@ function referenceFor(op: OpSpec, includeSchemas = false): string {
     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)") : ""));
+      // An object flag reads as its named type, which docs read explains.
+      const named = objectTypeName(op, p);
+      lines.push("  " + padPaint("cyan", name, 30) + (named ? INPUT_TYPES.args[op.tool]![p.name] : 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) {
@@ -1639,11 +1856,34 @@ function referenceFor(op: OpSpec, includeSchemas = false): string {
     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 {
+    const nested = op.params.find((p) => objectTypeName(op, p) || p.type === "object" || (p.type === "array" && p.items?.type === "object"));
+    if (nested) {
+      const named = objectTypeName(op, nested);
+      lines.push("", "Nested fields: " + BIN + " docs " + op.command.join(" ") + " --path " + nested.name + " gives a flag's type and all its fields; extend the path (" + nested.name + ".<field>) to go deeper."
+        + (named ? " Named types: " + BIN + " docs read " + named + "." : ""));
+    }
     lines.push("", "Add --schema for the complete input/output schemas, or --json for the machine contract.");
   }
   return lines.join("\n");
 }
 
+/** The named input object a flag takes (IssueFilter), when it has one. */
+function objectTypeName(op: OpSpec, p: ParamSpec): string | undefined {
+  return namedTypesIn(INPUT_TYPES, INPUT_TYPES.args[op.tool]?.[p.name]).find((name) => INPUT_TYPES.types[name]!.fields);
+}
+
+function docsTypeHint(name: string): string {
+  return BIN + " docs read " + name;
+}
+
+/** docs --path: one nested argument, or a usage error naming the fields. */
+async function docsPathExit(root: { tool: string; inputSchema: Record<string, unknown>; label: string } | { type: string }, path: string): Promise<never> {
+  const found = argumentPathText(INPUT_TYPES, root, path, docsTypeHint);
+  if (!found.ok) fail(2, found.message + (found.available.length > 0 ? " Fields: " + found.available.join(", ") + "." : ""));
+  process.stdout.write((found as { text: string }).text + "\n");
+  return flushExit(0);
+}
+
 /** 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)) {
@@ -1663,11 +1903,12 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
       "",
       "  " + BIN + " docs                          overview",
       "  " + BIN + " docs <resource> <command>     operation contract and example",
+      "      --path <a.b>                          one nested argument's type and fields",
       "      --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 read <page>              print a named input type or a docs-site page",
       "  " + 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>').",
@@ -1690,23 +1931,22 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
     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);
+    // The MCP server's search_docs ranking, so both surfaces agree.
+    const refMatches = rankOperations(OPS, term).map((match) => match.op);
     const { guides: proseMatches, status: docsStatus } = await searchConnectedGuides(docsSiteUrl(), docsIndexUrl(), fetchDocs, term);
     if (jsonOutput) {
       out({
         schema_version: "1",
         query: term,
-        reference: refMatches.slice(0, 15).map((op) => ({
+        reference: refMatches.slice(0, SEARCH_PAGE_SIZE).map((op) => ({
           command: op.command.join(" "),
           method: op.httpMethod,
           path: op.path,
           ...(op.summary ? { summary: op.summary } : {}),
+          ...(op.deprecated ? { deprecated: true } : {}),
           details_command: BIN + " docs " + op.command.join(" ") + " --json",
         })),
-        guides: proseMatches.slice(0, 15).map((match) => ({ ...match, read_command: docsReadCommand(BIN, match.url) })),
+        guides: proseMatches.slice(0, SEARCH_PAGE_SIZE).map((match) => ({ ...match, read_command: docsReadCommand(BIN, match.url) })),
         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."] } : {}),
@@ -1717,11 +1957,11 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
     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)));
+      for (const op of refMatches.slice(0, SEARCH_PAGE_SIZE)) lines.push("  " + padPaint("cyan", op.command.join(" "), 34) + (op.deprecated ? "(deprecated) " : "") + (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("  " + paintOut("cyan", match.title + (match.section ? " / " + match.section : "")), "    " + match.excerpt, "    " + docsReadCommand(BIN, match.url));
+      for (const match of proseMatches.slice(0, SEARCH_PAGE_SIZE)) lines.push("  " + paintOut("cyan", match.title + (match.section ? " / " + match.section : "")), "    " + match.excerpt, "    " + docsReadCommand(BIN, match.url));
     } 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") {
@@ -1735,6 +1975,13 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
   if (sub === "read") {
     const page = parsed.positionals[2];
     if (page === undefined) fail(2, "docs read expects a page path or URL");
+    const typeName = findInputType(INPUT_TYPES, page!);
+    if (typeName) {
+      const path = parsed.flags.get("path");
+      if (typeof path === "string" && path.trim()) await docsPathExit({ type: typeName }, path);
+      process.stdout.write(inputTypeText(INPUT_TYPES, typeName, docsTypeHint) + "\n");
+      await flushExit(0);
+    }
     let target = page!;
     if (!/^https?:\/\//.test(target)) {
       const index = await fetchDocs("llms.txt");
@@ -1773,12 +2020,14 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
       }, null, 2) + "\n");
       await flushExit(0);
     }
+    const path = parsed.flags.get("path");
+    if (typeof path === "string" && path.trim()) await docsPathExit({ tool: op!.tool, inputSchema: op!.inputSchema, label: op!.command.join(" ") }, path);
     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 + ")");
+  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>();
@@ -1834,7 +2083,7 @@ function shellQuote(value: string): string {
 }
 
 function usageLine(op: OpSpec): string {
-  const paths = op.params.filter((p) => p.kind === "path").map((p) => "<" + p.name + ">").join(" ");
+  const paths = op.params.filter((p) => p.kind === "path").map((p) => p.credential ? "[<" + p.name + ">]" : "<" + p.name + ">").join(" ");
   return BIN + " " + op.command[0] + " " + op.command[1] + (paths ? " " + paths : "");
 }
 
@@ -1882,7 +2131,7 @@ function helpSentence(description: string | undefined): string {
 /** Type column text for a param: string, number, string[], a|b|c, enum, object, json, path. */
 function typeLabel(p: ParamSpec): string {
   if (p.nullable) return typeLabel({ ...p, nullable: false }) + "|null";
-  if (p.type === "file") return "path (uploaded)";
+  if (p.type === "file") return p.multiple ? "paths (uploaded, repeatable)" : "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") {
@@ -1957,7 +2206,7 @@ function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
   }
   const width = termWidth();
   const lines: string[] = [];
-  lines.push(paintOut("bold", BIN) + ": " + "typeship API" + " (v" + "1.0.0" + "), package " + "0.22.0");
+  lines.push(paintOut("bold", BIN) + ": " + "Typeship API" + " (v" + "1.0.0" + "), package " + "0.24.0");
   lines.push("");
   lines.push(paintOut("bold", "Usage:") + " " + BIN + " <resource> <command> [args] [--flags]");
   lines.push("");
@@ -1976,18 +2225,18 @@ function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
   }
   if (EXCLUDED_OPS > 0) {
     lines.push("");
-    lines.push(...labeled(paintOut("yellow", "Plan limit:") + " ", "generated " + OPS.length + " of " + (OPS.length + EXCLUDED_OPS) + " operations", width, 14));
-    lines.push(...labeled("Omitted: ", OMITTED_OPS.map((op) => op.command.join(" ") + " (" + op.httpMethod + " " + op.path + ")").join(", "), width, 14));
-    lines.push(...labeled("Upgrade: ", "https://typeship.dev/pricing, then regenerate without the operation cap", width, 14));
+    lines.push(...labeled(paintOut("yellow", "Coverage:") + " ", "this build includes " + OPS.length + " of " + (OPS.length + EXCLUDED_OPS) + " operations; api.json lists the rest", width, 14));
   }
   lines.push("");
-  const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --data '<json>', --fields <a,b.c>, --all (paginated lists), --validate (schema-check parameters and JSON bodies)" +
+  const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --header \"Name: value\", --timeout <seconds>, --data '<json>', --fields <a,b.c>, --all (paginated lists), --format table (results as text), --validate (schema-check parameters and JSON bodies), --dry-run (print the request, send nothing)" +
     (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: ", [
     "TYPESHIP_CREDENTIALS", ...AUTH_SCALARS.map((a) => a.env),
     ...(BASIC ? [BASIC.envUser, BASIC.envPass] : []),
   ].join(", ") || "none", width, 21));
+  if (AUTH_UNDECLARED) lines.push(...labeled("Auth: ", "not declared by the API Spec; " + AUTH_SCALARS[0]!.env + " is sent as Authorization: Bearer when set", width, 6));
+  lines.push(...labeled("Extra headers: ", "--header \"Name: value\" (repeatable) or TYPESHIP_HEADERS", width, 15));
   lines.push(...labeled("Endpoint env var: ", "TYPESHIP_BASE_URL", width, 18));
   lines.push(...labeled("Sign-in: ", 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));
@@ -2030,12 +2279,15 @@ function commandExtras(op: OpSpec): [string, string][] {
   const extras: [string, string][] = [];
   if (op.auth !== "none" && Object.keys(NAMED_SCHEMES).length) extras.push(["--credentials @<file>|-", "named credentials as JSON; use - for stdin"]);
   if (op.hasBody && op.bodyKind === "binary") extras.push(["--file <path>", "raw request body, uploaded as-is (- reads stdin)"]);
+  if (op.rawResponse) extras.push(["--output <file>", "write the " + (op.rawResponse === "binary" ? "binary " : "") + "response body to a file (- for stdout) and print what was written"]);
   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 ((op.fileBundleProperty ?? bundleProperty(op.outputSchema)) !== null) extras.push(["--out <dir>", "write the response's files ({path, content}) into a directory"]);
+  extras.push(["--dry-run", "print the resolved request (method, URL, headers, body) with credentials redacted; nothing is sent" + (op.safety === "destructive" ? ", so no --force is needed" : "")]);
+  if (!op.rawResponse && !op.sse) extras.push(["--format table", "print the result as a table for reading instead of JSON"]);
   if (op.safety === "destructive") extras.push(["--force, -y", "destructive: required without a terminal, skips the prompt with one"]);
   return extras;
 }
@@ -2044,6 +2296,7 @@ function commandExtras(op: OpSpec): [string, string][] {
 function exampleLine(op: OpSpec): string {
   const parts = [BIN, op.command[0], op.command[1]];
   for (const p of op.params) {
+    if (p.credential) continue; // defaulted from the configured credential
     const hasExample = p.type !== "file" && Object.hasOwn(op.exampleArguments, p.name);
     if (!p.required && !hasExample) continue;
     const generated = p.type === "file" ? undefined : op.exampleArguments[p.name];
@@ -2074,6 +2327,7 @@ function exampleLine(op: OpSpec): string {
 
 /** " (no auth needed)" for an anonymous operation in an API that otherwise authenticates. */
 function authNote(op: OpSpec): string {
+  if (AUTH_UNDECLARED) return op.auth === "none" ? " (no auth needed)" : " (auth not declared)";
   const apiHasAuth = AUTH_SCALARS.length > 0 || BASIC !== null || HAS_OAUTH_LOGIN;
   return apiHasAuth && op.auth === "none" ? " (no auth needed)" : apiHasAuth && op.auth === "optional" ? " (auth optional)" : "";
 }
@@ -2083,6 +2337,8 @@ function printOp(op: OpSpec): void {
   lines.push(paintOut("bold", usageLine(op)));
   if (op.summary) lines.push(helpSentence(op.summary));
   lines.push(wireOf(op) + authNote(op));
+  const scopes = requiredScopes(op.security);
+  if (scopes.length) lines.push("Requires OAuth scopes: " + scopes.join(", ") + (HAS_OAUTH_LOGIN ? " (login --scopes " + scopes.join(",") + ")" : ""));
   lines.push("");
   const rows = op.params.filter((p) => p.kind !== "path");
   const extras = commandExtras(op);
@@ -2135,7 +2391,7 @@ function readStdinBytes(): Promise<Uint8Array<ArrayBuffer>> {
 /** 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));
+    return new File([readFileSync(path)], basename(path), { type: mediaTypeForPath(path) });
   } catch (e) {
     return fail(2, "--" + flag + ": cannot read " + path + " (" + (e as Error).message + ")");
   }
@@ -2182,6 +2438,7 @@ function coerce(spec: ParamSpec, raw: string | boolean, repeated?: string[]): un
   if (spec.nullable && raw === "null" && repeated === undefined) return null;
   if (spec.type === "file") {
     if (raw === true) fail(2, "--" + spec.flag + " expects a file path");
+    if (spec.multiple) return (repeated ?? [String(raw)]).map((path) => fileFromPath(spec.flag, path));
     return fileFromPath(spec.flag, String(raw));
   }
   if (spec.type === "boolean") {
@@ -2252,18 +2509,83 @@ function validateParameters(op: OpSpec, values: Record<string, unknown>, flags:
 
 /** Whether the last client built carried any credential; failApi tells NO_AUTH from AUTH_INVALID with it. */
 let LAST_CLIENT_HAD_CREDENTIAL = false;
+/** The last client's Basic credentials, for path arguments that default to the username. */
+let LAST_CLIENT_BASIC: { basicAuth?: unknown; credentials?: unknown } = {};
+
+/** --dry-run: the client's fetch records the first request and sends
+ * nothing. Set before makeClient; secrets are the credential values it
+ * resolved, redacted wherever they appear in the preview. */
+let DRY_RUN: { fetch: typeof fetch; request?: { method: string; url: string; headers: Record<string, string>; body?: unknown }; secrets: string[] } | null = null;
+
+class DryRunStop extends Error {}
+
+function dryRunCapture(): NonNullable<typeof DRY_RUN> {
+  const capture: NonNullable<typeof DRY_RUN> = {
+    secrets: [],
+    fetch: async (input, init) => {
+      if (!capture.request) {
+        const headers: Record<string, string> = {};
+        new Headers(init?.headers).forEach((value, name) => { headers[name] = value; });
+        capture.request = { method: init?.method ?? "GET", url: typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url, headers, body: init?.body ?? undefined };
+      }
+      throw new DryRunStop("dry run: not sent");
+    },
+  };
+  return capture;
+}
+
+/** Every credential value a client was built with (not a Basic username,
+ * which is an account identifier such as Twilio's AccountSid). */
+function credentialSecrets(options: Record<string, unknown>): string[] {
+  const found: string[] = [];
+  const walk = (value: unknown, key: string) => {
+    if (typeof value === "string") { if (key !== "username") found.push(value); return; }
+    if (value && typeof value === "object") for (const [k, v] of Object.entries(value as Record<string, unknown>)) walk(v, k);
+  };
+  for (const a of AUTH_SCALARS) walk(options[a.option], a.option);
+  walk(options.basicAuth, "basicAuth");
+  walk(options.credentials, "credentials");
+  walk(options.bearerToken, "bearerToken");
+  return found;
+}
+
+/** Drive the command's call until its request reaches the dry-run fetch,
+ * then print that request (JSON in agent mode, text for a person) and exit.
+ * A failure before any request (a --validate violation) is reported as usual. */
+async function printDryRun(parsed: Parsed, callResult: unknown): Promise<never> {
+  let failure: unknown;
+  try {
+    const pending = callResult as { then?: unknown; [Symbol.asyncIterator]?: () => AsyncIterator<unknown> };
+    if (typeof pending.then === "function") await (callResult as Promise<unknown>);
+    else if (typeof pending[Symbol.asyncIterator] === "function") await pending[Symbol.asyncIterator]!().next();
+  } catch (e) {
+    failure = e;
+  }
+  const request = DRY_RUN?.request;
+  if (!request) {
+    failApi(failure ?? new Error("--dry-run: the command made no request"), LAST_CLIENT_HAD_CREDENTIAL);
+  }
+  const preview = await requestPreview(request!, { sensitiveNames: CREDENTIAL_NAMES, secrets: DRY_RUN!.secrets });
+  if (isAgentMode(parsed)) out(preview);
+  else process.stdout.write(formatRequestPreview(preview));
+  return await flushExit(0);
+}
+
+/** The configured Basic-auth username: the named scheme's, else basicAuth's. */
+function credentialUsername(scheme: string): string | undefined {
+  const named = (LAST_CLIENT_BASIC.credentials as Record<string, unknown> | undefined)?.[scheme];
+  const username = named && typeof named === "object" ? (named as { username?: unknown }).username
+    : (LAST_CLIENT_BASIC.basicAuth as { username?: unknown } | undefined)?.username;
+  return typeof username === "string" && username !== "" ? username : undefined;
+}
 
 /** Check the same complete alternatives the request runtime can select, after
  * per-scheme flag, environment, profile, and OAuth resolution. */
 function requireOperationCredentials(op: OpSpec, options: ClientOptions & Record<string, unknown>): void {
   if (op.auth !== "required") return;
-  const supplied = (value: unknown): boolean => typeof value === "function" || (typeof value === "string" && value.length > 0)
-    || (value !== null && typeof value === "object" && "username" in value && "password" in value && typeof value.username === "string" && value.username.length > 0 && typeof value.password === "string" && value.password.length > 0);
-  const named = Object.fromEntries(Object.entries(options.credentials ?? {}).filter(([, value]) => supplied(value))) as NamedCredentials;
-  const available = namedCredentialAvailability(NAMED_SCHEMES, new Set(Object.keys(options).filter((key) => supplied(options[key]))), named);
-  if (op.credentialOptions?.some((alternative) => alternative.length > 0 && alternative.every((option) => available.has(option)))) return;
-  const alternatives = (op.credentialOptions ?? []).filter((alternative) => alternative.length > 0 && alternative.every((option) => option.startsWith("credentials.")));
-  const missing = alternatives.map((alternative) => alternative.filter((option) => !available.has(option)).map((option) => option.slice("credentials.".length)));
+  const gap = missingCredentials(NAMED_SCHEMES, op.credentialOptions, options);
+  if (!gap) return;
+  const { alternatives, missing } = gap;
   const names = new Set(missing.flat());
   const relevant = AUTH_SCALARS.filter((scalar) => [...names].some((name) => NAMED_SCHEMES[name]?.options.includes(scalar.option)));
   const needsBasic = [...names].some((name) => NAMED_SCHEMES[name]?.options.includes("basicAuth"));
@@ -2276,7 +2598,8 @@ function requireOperationCredentials(op: OpSpec, options: ClientOptions & Record
     nextSteps: alternatives.length ? [
       ...relevant.map((a) => "Set " + a.env + " in the environment, pass --" + a.flag + " <value>, or run '" + BIN + " login'."),
       ...(needsBasic && BASIC ? ["Set " + BASIC.envUser + " and " + BASIC.envPass + ", or pass --username and --password."] : []),
-      "Supply all schemes in one alternative through " + "TYPESHIP_CREDENTIALS" + " or --credentials @<JSON-file>: " + alternatives.map((alternative) => alternative.map((option) => option.slice("credentials.".length)).join(" + ")).join(" OR ") + ".",
+      ...(HAS_OAUTH_LOGIN && [...names].some((name) => OAUTH_SESSION_SCHEMES.includes(name)) ? ["Sign in with OAuth: '" + BIN + " login'."] : []),
+      "Supply all schemes in one alternative through " + "TYPESHIP_CREDENTIALS" + " or --credentials @<JSON-file>: " + alternatives.map((alternative) => alternative.join(" + ")).join(" OR ") + ".",
     ] : ["Check the operation's security schemes in the API Spec and regenerate with a supported, compatible alternative."],
   });
 }
@@ -2307,6 +2630,23 @@ function environmentCredentials(): NamedCredentials {
   return value === undefined ? {} : parseNamedCredentials(value, NAMED_SCHEMES);
 }
 
+/** --timeout <seconds> or TYPESHIP_TIMEOUT: the per-attempt deadline
+ * (default 60 seconds) for slow operations. */
+function requestTimeoutMs(flags: Map<string, string | boolean>): number | undefined {
+  const raw = typeof flags.get("timeout") === "string" ? flags.get("timeout") as string : process.env["TYPESHIP_TIMEOUT"];
+  if (raw === undefined) return undefined;
+  const seconds = Number(raw);
+  if (!/^\d+(\.\d+)?$/.test(raw.trim()) || !Number.isFinite(seconds) || seconds <= 0 || seconds > 3600) fail(2, "--timeout expects seconds between 0 and 3600, such as --timeout 120.");
+  return Math.round(seconds * 1000);
+}
+
+/** --header flags and TYPESHIP_HEADERS: sent on every API request, after
+ * (and in place of) any generated header of the same name. */
+function extraRequestHeaders(): Record<string, string> {
+  try { return parseExtraHeaders(process.env["TYPESHIP_HEADERS"], HEADER_FLAGS, "TYPESHIP_HEADERS"); }
+  catch (error) { fail(2, (error as Error).message); }
+}
+
 /** 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 (Object.keys(flagCredentials(flags)).length) return "flags";
@@ -2330,7 +2670,29 @@ function resolveBaseUrl(flags: Map<string, string | boolean>, config = readConfi
     ?? DEFAULT_BASE_URL ?? undefined;
 }
 
+/** OAuth schemes the login session authenticates by name; empty when the
+ * session is the convenience bearer token (see oauthSessionSchemes). */
+const OAUTH_SESSION_SCHEMES = oauthSessionSchemes(NAMED_SCHEMES);
+
+/** Send a login session to the OAuth scheme, never to a separate http bearer
+ * scheme. Explicit credentials for the same scheme keep precedence. */
+function applyOAuthSession(options: ClientOptions & Record<string, unknown>, token: string | (() => Promise<string>), replace = false): void {
+  if (!OAUTH_SESSION_SCHEMES.length) {
+    if (replace || options.bearerToken === undefined) options.bearerToken = token;
+    return;
+  }
+  const credentials = (options.credentials ??= {}) as Record<string, unknown>;
+  for (const name of OAUTH_SESSION_SCHEMES) if (replace || !Object.hasOwn(credentials, name)) credentials[name] = token;
+}
+function withOAuthSession(options: ClientOptions & Record<string, unknown>, accessToken: string): ClientOptions & Record<string, unknown> {
+  const next: ClientOptions & Record<string, unknown> = { ...options, credentials: { ...(options.credentials as Record<string, unknown>) } as ClientOptions["credentials"] };
+  applyOAuthSession(next, accessToken, true);
+  if (!OAUTH_SESSION_SCHEMES.length) next.credentials = { ...(next.credentials as Record<string, unknown>), ...resolveNamedCredentials(NAMED_SCHEMES, [{ options: { bearerToken: accessToken } }]) } as ClientOptions["credentials"];
+  return next;
+}
+
 async function makeClient(flags: Map<string, string | boolean>, op: OpSpec, candidate?: StoredCreds, forIdentity = false): Promise<TypeshipClient> {
+  CURRENT_SCOPES = requiredScopes(op.security);
   const flagNamed = flagCredentials(flags), envNamed = environmentCredentials();
   const explicitOptions = new Set(AUTH_SCALARS.filter((a) => typeof flags.get(a.flag) === "string" || process.env[a.env] !== undefined).map((a) => a.option));
   if (BASIC && (typeof flags.get("username") === "string" || process.env[BASIC.envUser] !== undefined) && (typeof flags.get("password") === "string" || process.env[BASIC.envPass] !== undefined)) explicitOptions.add("basicAuth");
@@ -2369,25 +2731,29 @@ async function makeClient(flags: Map<string, string | boolean>, op: OpSpec, cand
   options.credentials = resolveNamedCredentials(NAMED_SCHEMES, [
     { named: stored?.named, options: { ...stored?.scalars, ...(stored?.basic ? { basicAuth: stored.basic } : {}) } },
     { named: envNamed, options: envOptions }, { named: flagNamed, options: flagOptions },
-    ...(forIdentity && candidate ? [{ named: candidate.named, options: { ...candidate.scalars, ...(candidate.basic ? { basicAuth: candidate.basic } : {}), ...(candidate.oauth ? { bearerToken: candidate.oauth.accessToken } : {}) } }] : []),
+    ...(forIdentity && candidate ? [{ named: candidate.named, options: { ...candidate.scalars, ...(candidate.basic ? { basicAuth: candidate.basic } : {}), ...(candidate.oauth && !OAUTH_SESSION_SCHEMES.length ? { bearerToken: candidate.oauth.accessToken } : {}) } }] : []),
   ]);
-  if (stored?.oauth && (forIdentity || options.bearerToken === undefined)) {
+  if (stored?.oauth) {
     const sessionId = stored.oauth.sessionId;
-    options.bearerToken = forIdentity ? stored.oauth.accessToken : () => oauthSessionToken(credentialStore(), {
+    const token = forIdentity ? stored.oauth.accessToken : sessionCredential((rejected) => oauthSessionToken(credentialStore(), {
       ...sessionConfiguration(baseUrl, config),
-      ...(identityConfiguration() && WHOAMI ? { verifyIdentity: (accessToken: string) => verifyClientIdentity((values) => new TypeshipClient(values as unknown as ClientOptions), { ...options, bearerToken: accessToken, credentials: resolveNamedCredentials(NAMED_SCHEMES, [{ named: options.credentials as NamedCredentials }, { options: { bearerToken: accessToken } }]) }, WHOAMI!, IDENTITY_POLICY) } : {}),
-    }, sessionId, OAUTH_TOKEN_PARAMS);
+      ...(identityConfiguration() && WHOAMI ? { verifyIdentity: (accessToken: string) => verifyClientIdentity((values) => new TypeshipClient(values as unknown as ClientOptions), withOAuthSession(options, accessToken), WHOAMI!, IDENTITY_POLICY) } : {}),
+    }, sessionId, OAUTH_TOKEN_PARAMS, rejected));
+    applyOAuthSession(options, token, forIdentity);
   }
   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;
+  const timeout = requestTimeoutMs(flags);
+  if (timeout !== undefined) options.timeoutMs = timeout;
   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 = Object.keys(options.credentials ?? {}).length > 0 || AUTH_SCALARS.some((a) => options[a.option] !== undefined) || options.basicAuth !== undefined || options.bearerToken !== undefined;
+  LAST_CLIENT_BASIC = { basicAuth: options.basicAuth, credentials: options.credentials };
   requireOperationCredentials(op, options);
   // Identify the package and version. Optional harness and caller details
   // let the API distinguish agent traffic from other non-interactive use.
@@ -2401,6 +2767,14 @@ async function makeClient(flags: Map<string, string | boolean>, op: OpSpec, cand
     "User-Agent": PKG_NAME + "-cli/" + VERSION + (details ? " (" + details + ")" : ""),
   };
   if (forIdentity) { options.fetch = identityFetch(baseUrl); options.maxRetries = 0; options.timeoutMs = 10_000; }
+  const extraHeaders = extraRequestHeaders();
+  if (Object.keys(extraHeaders).length) options.onRequest = (context) => { applyExtraHeaders(context.headers, extraHeaders); };
+  // --dry-run swaps fetch on this client only: an OAuth refresh (and its
+  // identity check) still uses the real transport, the command does not.
+  if (DRY_RUN && !forIdentity) {
+    DRY_RUN.secrets = credentialSecrets(options);
+    return new TypeshipClient({ ...options, fetch: DRY_RUN.fetch, maxRetries: 0 });
+  }
   return new TypeshipClient(options);
 }
 
@@ -2438,9 +2812,9 @@ function failOmitted(op: OmittedOpSpec): never {
   return failWith({
     status: "action_required",
     code: "PLAN_LIMIT",
-    message: "The command '" + BIN + " " + op.command.join(" ") + "' exists in the API Spec but was omitted from this generated package by its plan limit.",
-    detail: { operation: op.tool, method: op.httpMethod, path: op.path, generated_operations: OPS.length, total_operations: OPS.length + EXCLUDED_OPS },
-    nextSteps: ["Upgrade at https://typeship.dev/pricing and regenerate the package without the operation cap.", "Do not invent or retry an omitted command against this generated package."],
+    message: "The command '" + BIN + " " + op.command.join(" ") + "' is in the API but not in this package, which was generated with " + OPS.length + " of its " + (OPS.length + EXCLUDED_OPS) + " operations.",
+    detail: { operation: op.tool, ...(op.graphql ? { graphql: op.graphql.kind + " " + op.graphql.field } : { method: op.httpMethod, path: op.path }), generated_operations: OPS.length, total_operations: OPS.length + EXCLUDED_OPS },
+    nextSteps: ["The package's publisher can regenerate it with every operation.", "Do not invent or retry an omitted command against this package."],
   });
 }
 
@@ -2449,24 +2823,32 @@ const BUILTIN_COMMANDS = ["login","logout","whoami","config","mcp","docs","upgra
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const parsed = parseArgv(argv);
+  const headerFlag = parsed.flags.get("header");
+  HEADER_FLAGS = parsed.repeated.get("header") ?? (typeof headerFlag === "string" ? [headerFlag] : []);
+  if (headerFlag === true) fail(2, "--header expects \"Name: value\".");
   if (!parsed.help) validateCredentialsInput(parsed.flags);
   const profileFlag = parsed.flags.get("profile");
   if (profileFlag !== undefined && typeof profileFlag !== "string") fail(2, "--profile requires a profile name.");
   PROFILE = resolveProfile(configRoot(), { flag: profileFlag as string | undefined, environment: process.env["TYPESHIP_PROFILE"], allowMissing: ["login", "config", "auth", "init", "help"].includes(parsed.positionals[0] ?? "") || parsed.help });
   if (!parsed.help && ["login", "init"].includes(parsed.positionals[0] ?? "")) expectedLoginIdentity(parsed.flags);
   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); }
+    // help [<resource> [<command>]] --json: bounded discovery as data; --all is exhaustive.
+    if (parsed.flags.get("json") === true || parsed.flags.get("format") === "json") { await cmdHelpJson(parsed); }
     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.");
+  const formatFlag = parsed.flags.get("format");
+  if (formatFlag !== undefined && formatFlag !== "json" && formatFlag !== "table") {
+    fail(2, "--format takes json (the default) or table.");
+  }
+  TABLE = formatFlag === "table";
+  if (TABLE && !parsed.help && (BUILTIN_COMMANDS.includes(parsed.positionals[0] ?? "") || parsed.positionals.length === 0)) {
+    fail(2, "--format table applies to API commands; " + (parsed.positionals[0] ? BIN + " " + parsed.positionals[0] : BIN) + " prints JSON.");
   }
   if (parsed.flags.has("version") || parsed.positionals[0] === "version") {
     // "acme 1.0.0 (acme 1.0.0)" would say the name twice; 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");
+    process.stdout.write(BIN + " " + VERSION + " (" + apiLabel + ", generated by Typeship)\n");
     await flushExit(0);
   }
   const [resourceCmd, methodCmd] = parsed.positionals;
@@ -2531,12 +2913,18 @@ async function main(): Promise<void> {
 
   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));
+  // A path argument that is the Basic-auth username (Twilio's AccountSid)
+  // may be left out; it defaults to the configured credential below.
+  const pathGiven = pathValues.length === pathSpecs.length ? pathSpecs
+    : pathValues.length === pathSpecs.filter((p) => !p.credential).length ? pathSpecs.filter((p) => !p.credential)
+    : null;
+  if (!pathGiven) {
+    const optional = pathSpecs.filter((p) => p.credential).length;
+    fail(2, "Expected " + (optional ? (pathSpecs.length - optional) + " or " : "") + pathSpecs.length + " argument(s): " + usageLine(op));
   }
 
   const values: Record<string, unknown> = {};
-  pathSpecs.forEach((spec, i) => { values[spec.name] = pathValues[i]; });
+  pathGiven!.forEach((spec, i) => { values[spec.name] = pathValues[i]; });
 
   let dataBody: unknown;
   const dataRaw = parsed.flags.get("data");
@@ -2557,7 +2945,7 @@ async function main(): Promise<void> {
   // 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", "credentials", "all", "select", "base-url", "profile", "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)]);
+  const RESERVED_FLAGS = new Set(["data", "credentials", "header", "timeout", "all", "select", "base-url", "profile", "debug", "validate", "dry-run", "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);
@@ -2566,7 +2954,7 @@ async function main(): Promise<void> {
     // 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"
+    values[spec.name] = spec.type === "array" || (spec.type === "file" && spec.multiple)
       ? coerce(spec, raw, all)
       : all !== undefined && spec.type === "json"
         ? all.map((v) => coerce(spec, v))
@@ -2575,12 +2963,39 @@ async function main(): Promise<void> {
   for (const key of parsed.flags.keys()) {
     if (RESERVED_FLAGS.has(key)) continue;
     if (key === "file" && op.bodyKind === "binary") continue;
+    if (key === "output" && op.rawResponse) 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 + "?" : ""));
     }
   }
 
+  // Object and array values (a GraphQL input, a JSON flag, --data fields)
+  // get the checks the MCP server applies: nested types, enums, required
+  // properties, patterns and a closed object's unknown keys, all at once.
+  const argumentSchemas = (op.inputSchema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  const nestedIssues: ArgumentIssue[] = [];
+  const checkNested = (name: string, value: unknown): unknown =>
+    value !== null && typeof value === "object" && !(value instanceof Blob) && argumentSchemas[name]
+      ? checkValue(value, argumentSchemas[name]!, name, nestedIssues) : value;
+  for (const spec of op.params) {
+    if (spec.kind !== "path" && spec.type !== "file" && values[spec.name] !== undefined) values[spec.name] = checkNested(spec.name, values[spec.name]);
+  }
+  if (op.bodyStyle === "fields" && dataBody !== null && typeof dataBody === "object" && !Array.isArray(dataBody) && !(dataBody instanceof Blob)) {
+    const body = dataBody as Record<string, unknown>;
+    for (const name of Object.keys(body)) {
+      if (op.params.some((p) => p.kind === "body" && p.name === name && p.type !== "file")) body[name] = checkNested(name, body[name]);
+    }
+  }
+  if (nestedIssues.length > 0) {
+    failWith({
+      code: nestedIssues.every((issue) => issue.code === "MISSING_ARGUMENT") ? "MISSING_ARGUMENT" : "INVALID_USAGE",
+      message: nestedIssues.length + (nestedIssues.length === 1 ? " problem" : " problems") + " in the arguments; nothing was sent: " + nestedIssues.map((issue) => issue.message).join("; "),
+      detail: { issues: nestedIssues },
+      nextSteps: ["Fix the values listed in detail.issues and run again.", "Run '" + USAGE_HINT + "' for each argument's type."],
+    });
+  }
+
   const missing = missingRequired(op, values).filter((name) =>
     !(op.bodyStyle === "fields" && dataBody !== undefined && typeof dataBody === "object" && dataBody !== null && name in (dataBody as object)),
   );
@@ -2600,6 +3015,7 @@ async function main(): Promise<void> {
   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");
+    FIELDS_AFTER_WRITE = op.safety !== "read";
   }
 
   // --out <dir> materializes a file-shaped response (see cli-agent.ts bundleProperty).
@@ -2611,13 +3027,54 @@ async function main(): Promise<void> {
   }
 
   validateParameters(op, values, parsed.flags);
+  // Raw bytes on a terminal are unreadable and can garble it: ask for a
+  // destination before the request runs (it may be billed, like speech).
+  const outputFlag = op.rawResponse ? parsed.flags.get("output") : undefined;
+  if (outputFlag === true) fail(2, "--output expects a file path, or - for stdout.");
+  if (op.rawResponse === "binary" && outputFlag === undefined && process.stdout.isTTY) {
+    fail(2, op.command.join(" ") + " returns binary data. Pass --output <file>, or redirect stdout to a file.");
+  }
+  // --all on a list the generator could not page would print one page and
+  // exit 0, which reads as "that is everything".
+  if (!op.paginated && parsed.flags.get("all") === true) {
+    fail(2, op.command.join(" ") + " does not paginate, so --all has nothing to walk. Run it without --all; it returns the whole response.");
+  }
+  // --dry-run resolves everything a real call would (arguments, defaults,
+  // credentials, the body encoding) and prints the request instead of
+  // sending it. A destructive command needs no --force: nothing runs.
+  if (parsed.flags.get("dry-run") === true) {
+    if (op.paginated && parsed.flags.get("all") === true) fail(2, "--dry-run previews one request; run it without --all to see the first page's.");
+    DRY_RUN = dryRunCapture();
+  }
+  // A table needs the whole result: streams (--all, events) and raw bodies stay as they are.
+  if (TABLE) {
+    const streams = parsed.flags.get("all") === true || op.sse || (op.streamMethod !== undefined && values[op.streamMethod.flag] === op.streamMethod.value);
+    if (streams || op.rawResponse) fail(2, "--format table needs one complete JSON result; " + op.command.join(" ") + (op.rawResponse ? " returns a raw body." : " streams NDJSON here.") + " Drop --format table" + (parsed.flags.get("all") === true ? " or --all." : "."));
+  }
   const client = await makeClient(parsed.flags, op);
+  for (const spec of pathSpecs) {
+    if (!spec.credential || values[spec.name] !== undefined) continue;
+    const username = credentialUsername(spec.credential.scheme);
+    if (username === undefined) {
+      fail(2, "Missing required: <" + spec.name + ">. It defaults to the Basic-auth username (" + spec.credential.env + "), and none is configured.", undefined,
+        ["Pass " + spec.name + " as an argument: " + usageLine(op) + ".", "Or set " + spec.credential.env + (BASIC ? " and " + BASIC.envPass : "") + ", or run '" + BIN + " login'."]);
+    }
+    values[spec.name] = username;
+  }
 
   // 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 (op.safety === "destructive" && !assumeYes(parsed) && !DRY_RUN) {
+    // Credential flags are replaced by placeholders: the rerun is shown to
+    // agents and logged, so it must never repeat a key.
+    const secretFlags = new Set([...AUTH_SCALARS.map((a) => "--" + a.flag), "--header"]);
+    const rerun = BIN + " " + process.argv.slice(2).map((a, i, all) => {
+      const eq = a.indexOf("=");
+      if (a.startsWith("--") && eq > 0 && secretFlags.has(a.slice(0, eq))) return a.slice(0, eq) + "=<" + a.slice(2, eq) + ">";
+      if (i > 0 && secretFlags.has(all[i - 1]!)) return "<" + all[i - 1]!.slice(2) + ">";
+      return /\s/.test(a) ? JSON.stringify(a) : a;
+    }).join(" ") + " --force";
     if (nonInteractive(parsed) || !process.stdin.isTTY) {
       failWith({
         status: "action_required",
@@ -2634,20 +3091,30 @@ async function main(): Promise<void> {
   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);
+  // --stream true on an operation with a streaming twin prints its events
+  // as NDJSON as they arrive, instead of failing on the event stream.
+  const streaming = op.streamMethod !== undefined && values[op.streamMethod.flag] === op.streamMethod.value;
+  const callResult = target[streaming ? op.streamMethod!.method : op.method]!(...args);
+  if (DRY_RUN) await printDryRun(parsed, callResult);
 
   if (op.paginated && parsed.flags.get("all") === true) {
+    const fieldsCheck = streamFieldsCheck((listSchemaOf(op.outputSchema, "items") as { items?: unknown } | undefined)?.items);
     try {
       for await (const item of callResult as AsyncIterable<unknown>) {
-        process.stdout.write(JSON.stringify(project(item)) + "\n");
+        process.stdout.write(JSON.stringify(fieldsCheck.item(item)) + "\n");
       }
+      fieldsCheck.finish();
       await flushExit(0);
     } catch (e) {
+      if (isNotModified(e)) await printNotModified(e);
       failApi(e, LAST_CLIENT_HAD_CREDENTIAL);
     }
   }
 
   let result = await asApiResult(callResult as Promise<unknown>);
+  // 304 Not Modified: the conditional request matched, so there is no
+  // body. Say so, with the ETag to send next time.
+  if (!result.ok && isNotModified(result.error)) await printNotModified(result.error);
   if (result.ok && op.httpMethod === "POST" && op.path === "/projects/{project_id}/generate") {
     const batch = result.data as { data: Array<{ id: string }> };
     const generations = (client as unknown as { generations: { wait(id: string): Promise<unknown> } }).generations;
@@ -2660,15 +3127,33 @@ async function main(): Promise<void> {
     result = { ...result, data: { ...batch, data: completed } };
   }
   if (result.ok) {
-    if (op.sse) {
+    if (op.sse || streaming) {
       // Server-sent events as NDJSON, one line per event, until the stream ends.
+      const fieldsCheck = streamFieldsCheck(undefined);
       try {
         for await (const event of result.data as AsyncIterable<{ event?: string; id?: string; data: string }>) {
-          process.stdout.write(JSON.stringify(project(event)) + "\n");
+          process.stdout.write(JSON.stringify(fieldsCheck.item(event)) + "\n");
         }
       } catch (e) {
         failApi(e, LAST_CLIENT_HAD_CREDENTIAL);
       }
+      fieldsCheck.finish();
+      await flushExit(0);
+    }
+    // A non-JSON body (audio, a file, CSV): raw bytes to stdout, or to the
+    // --output file with a JSON note of what was written. Never "{}".
+    if (op.rawResponse || result.data instanceof Blob) {
+      const data = result.data;
+      const bytes = data instanceof Blob
+        ? new Uint8Array(await data.arrayBuffer())
+        : new TextEncoder().encode(typeof data === "string" ? data : JSON.stringify(data ?? ""));
+      if (typeof outputFlag === "string" && outputFlag !== "-") {
+        try { writeFileSync(outputFlag, bytes); } catch (e) { fail(1, "--output: cannot write " + outputFlag + " (" + (e as Error).message + ")"); }
+        const mediaType = data instanceof Blob && data.type ? data.type : op.rawResponse === "text" ? "text/plain" : "application/octet-stream";
+        out({ saved_to: resolvePath(outputFlag), bytes: bytes.length, media_type: mediaType });
+      } else {
+        process.stdout.write(bytes);
+      }
       await flushExit(0);
     }
     // A claim-shaped response (claim.url): say where to claim it, and leave
@@ -2686,17 +3171,17 @@ async function main(): Promise<void> {
       // agent never has to reconstruct the cursor flag.
       const page = result.data as { items: unknown[]; hasNextPage(): boolean; nextPageParams(): Record<string, unknown> | null; response: { requestId?: string } };
       const next = page.nextPageParams();
-      out({
-        items: project(page.items),
+      printResult({
+        items: project(page.items, true, listSchemaOf(op.outputSchema, "items")),
         hasMore: next !== null,
         ...(next !== null ? { nextPage: next, nextCommand: nextCommandFor(op, pathValues, next) } : {}),
         ...(page.response.requestId ? { request_id: page.response.requestId } : {}),
-      });
+      }, op.command[0]);
     } 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]) });
+      printResult({ ...data, [collectionField]: project(data[collectionField], true, listSchemaOf(op.outputSchema, collectionField)) }, op.command[0], 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.
@@ -2704,9 +3189,9 @@ async function main(): Promise<void> {
       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 });
+      printResult({ ...(project(rest, false, op.outputSchema) as Record<string, unknown>), out: written }, op.command[0]);
     } else {
-      out(project(result.data ?? { ok: true }));
+      printResult(result.data === undefined || result.data === null ? { ok: true } : project(result.data, Array.isArray(result.data), op.outputSchema), op.command[0], collectionField);
     }
     await flushExit(0);
   }
@@ -2724,6 +3209,8 @@ function errorMessage(error: unknown): string {
 main().catch((e) => {
   if (e instanceof ExitPending) return;
   try {
+    const auth = classifyAuthFailure(e, authFailureContext());
+    if (auth) failWith(auth);
     fail(1, errorMessage(e));
   } catch {
     // exit already scheduled