@typeship-ax/cli 0.22.0 → 0.24.0

package/dist/cli-agent.js

@@ -1,5 +1,5 @@
 /**
- * The agent contract of a generated CLI. Generated by typeship — https://typeship.dev
+ * The agent contract of a generated CLI. Generated by Typeship — https://typeship.dev
  *
  * Everything a coding agent needs from a command-line tool and a human does
  * not: a JSON error envelope with stable codes and next steps, agent-mode
@@ -27,6 +27,7 @@ export function exitCodeFor(code) {
         case "UNKNOWN_COMMAND":
         case "UNKNOWN_FLAG":
         case "MISSING_ARGUMENT":
+        case "FIELDS_UNMATCHED":
         case "TTY_REQUIRED":
         case "CONFIRMATION_REQUIRED":
             return 2;
@@ -38,9 +39,9 @@ export function exitCodeFor(code) {
 export function classifyApiError(error, context) {
     const e = (error ?? {});
     // The message is the API's own words when it sent any, else the SDK's
-    // (the spec's response description). The error class name rides in
-    // detail, not in front of the message: "NotFoundError: No such account
-    // (no such account)" said one thing three times.
+    // ("HTTP 404"). The error class name rides in detail, not in front of the
+    // message: "NotFoundError: No such account (no such account)" said one
+    // thing three times.
     const base = e.message ? e.message : String(error);
     if (e.violations !== undefined) {
         const nextStep = e.direction === "response"
@@ -50,12 +51,12 @@ export function classifyApiError(error, context) {
                 : "Correct the body fields named in detail.violations to match their constraints, then run the command again.";
         return { code: "VALIDATION_FAILED", message: base, detail: { ...(e.name ? { error: e.name } : {}), violations: e.violations }, nextSteps: [nextStep] };
     }
-    if (e.name === "TransportError" || (typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(base))) {
+    if (e.name === "TransportError" || (e.name !== "PaginationError" && typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(base))) {
         return {
             code: "NETWORK_ERROR",
             message: base,
             nextSteps: [
-                "Check the base URL (--base-url, the " + context.bin.toUpperCase().replace(/[^A-Z0-9]/g, "_") + "_BASE_URL variable, or '" + context.bin + " config base-url') and the network.",
+                "Check the base URL (--base-url, the " + context.envPrefix + "_BASE_URL variable, or '" + context.bin + " config base-url') and the network.",
                 "Retry once with backoff; do not loop.",
             ],
         };
@@ -68,27 +69,57 @@ export function classifyApiError(error, context) {
         ? e.body.request_id ?? e.body.requestId
         : undefined;
     const requestId = e.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
-    const detail = { status, ...(e.name ? { error: e.name } : {}), ...(requestId ? { request_id: requestId } : {}), ...(e.body !== undefined ? { body: e.body } : {}) };
+    // An in-band GraphQL error keeps the vendor's code next to the normalized one.
+    const vendorCode = e.name === "GraphQLRequestError" ? graphqlVendorCode(error) : undefined;
+    const detail = { status, ...(e.name ? { error: e.name } : {}), ...(vendorCode ? { vendor_code: vendorCode } : {}), ...(requestId ? { request_id: requestId } : {}), ...(e.body !== undefined ? { body: e.body } : {}) };
     const same = apiMessage !== undefined && (apiMessage.toLowerCase() === base.toLowerCase() || base.toLowerCase().includes(apiMessage.toLowerCase()) || apiMessage.toLowerCase().includes(base.toLowerCase()));
     const message = apiMessage === undefined ? base : same ? apiMessage : apiMessage + " (" + base + ")";
     const upgradeUrl = extractUrl(e.body, ["upgrade_url", "upgradeUrl", "signup_url", "claim_url"]);
-    if (status === 401) {
-        return context.hadCredential
-            ? { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential was rejected. Check it is current: '" + context.bin + " auth check', then '" + context.bin + " login --help' to store a new one."] }
-            : { status: "action_required", code: "NO_AUTH", message, detail, nextSteps: ["No credential was sent. Set the auth env var, pass --token, or run '" + context.bin + " login'.", "'" + context.bin + " auth check' shows what the CLI would send."] };
+    // A rate limit can arrive as a 403 (GitHub); the SDK marks it either way.
+    if (status === 429 || e.rateLimit !== undefined) {
+        return { status: "action_required", code: "RATE_LIMITED", message, detail: { ...detail, ...(e.rateLimit?.retryAt ? { retry_at: isoSeconds(e.rateLimit.retryAt) } : {}) }, nextSteps: [rateLimitNextStep(e.rateLimit?.retryAt, "run the same command again")] };
     }
+    // A failure the API reported inside a 2xx body: classify by its code.
+    const scopes = context.requiredScopes ?? [];
+    const scopeFailure = () => ({ code: "INSUFFICIENT_SCOPE", message: message + " This operation requires the OAuth scopes: " + scopes.join(", ") + ".", detail: { ...detail, required_scopes: scopes }, nextSteps: [
+            context.canLogin ? "Sign in again with those scopes: '" + context.bin + " login --scopes " + scopes.join(",") + "'." : "Use a token granted those scopes.",
+            "If the token already has them, the account may lack access to this resource.",
+        ] });
+    if (e.name === "PayloadError") {
+        if (scopes.length && /^missing_scope$/i.test(String(e.code)))
+            return scopeFailure();
+        const reported = payloadFailureCode(e.code);
+        if (reported === "AUTH_INVALID")
+            return { code: "AUTH_INVALID", message, detail, nextSteps: ["The API rejected the credential (" + String(e.code) + "). Check it is current: '" + context.bin + " auth check'."] };
+        if (reported === "RATE_LIMITED")
+            return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: ["Wait, then run the same command again."] };
+        return { code: "CALL_FAILED", message, detail, nextSteps: ["The API reported a failure in a successful response; detail.body says why."] };
+    }
+    const unauthenticated = () => context.hadCredential
+        ? { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential was rejected. Check it is current: '" + context.bin + " auth check', then '" + context.bin + " login --help' to store a new one."] }
+        : { status: "action_required", code: "NO_AUTH", message, detail, nextSteps: ["No credential was sent. Set the auth env var, pass --token, or run '" + context.bin + " login'.", "'" + context.bin + " auth check' shows what the CLI would send."] };
+    const forbidden = () => scopes.length ? scopeFailure() : { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential lacks access to this operation."] };
+    // An in-band GraphQL error (HTTP 200): classified by the vendor's code.
+    if (e.name === "GraphQLRequestError") {
+        switch (vendorCode === undefined ? undefined : graphqlErrorClass(vendorCode)) {
+            case "not_found": return { code: "NOT_FOUND", message, detail, nextSteps: ["Check the id in the arguments; list the resource first to find the right one."] };
+            case "unauthenticated": return unauthenticated();
+            case "forbidden": return forbidden();
+            case "bad_input": return { code: "INVALID_REQUEST", message, detail, nextSteps: ["The API rejected an argument or the selection; the errors in detail.body name it (message, path). Fix that and run the command again."] };
+            case "rate_limited": return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: [rateLimitNextStep(undefined, "run the same command again")] };
+            default: return { code: "CALL_FAILED", message, detail };
+        }
+    }
+    if (status === 401)
+        return unauthenticated();
     if (status === 403)
-        return { code: "AUTH_INVALID", message, detail, nextSteps: ["The credential lacks access to this operation."] };
+        return forbidden();
     if (status === 402) {
         return { status: "action_required", code: "PLAN_LIMIT", message, detail, nextSteps: [upgradeUrl ? "Lift the limit at " + upgradeUrl + ", then run the same command again." : "The account's plan stops here; upgrade it, then run the same command again.", "Do not retry the same call as is."] };
     }
     if (status === 404)
         return { code: "NOT_FOUND", message, detail, nextSteps: notFoundNextSteps(message) };
-    if (status === 429) {
-        const retryAfter = extractRetryAfter(e);
-        return { status: "action_required", code: "RATE_LIMITED", message, detail, nextSteps: [retryAfter ? "Wait " + retryAfter + " seconds, then run the same command again." : "Back off and retry once; the SDK already retried with the server's Retry-After."] };
-    }
-    if (status === 422 && apiCode === "spec_error")
+    if (status === 422 && (apiCode === "spec_invalid" || apiCode === "spec_error"))
         return { code: "SPEC_INVALID", message, detail, nextSteps: ["The API rejected the spec it was given; the message says why.", context.docsUrl ? "Look the message up: '" + context.bin + " docs search \"" + (apiMessage ?? "").slice(0, 60).replace(/"/g, "'") + "\"'." : "Fix the spec and run again."] };
     if (status === 400 || status === 422 || status === 409 || status === 413)
         return { code: "INVALID_REQUEST", message, detail, nextSteps: ["Read detail.body for the field the API named; run the command with --help for its flags."] };
@@ -96,6 +127,43 @@ export function classifyApiError(error, context) {
         return { code: "SERVER_ERROR", message, detail, nextSteps: ["Retry once with backoff. If it persists, report detail.request_id."] };
     return { code: "CALL_FAILED", message, detail };
 }
+/** Login, saved-session and credential-store failures, recognised by error
+ * name (so this module needs no login runtime) on the error or its cause.
+ * Undefined when the error is none of them. */
+export function classifyAuthFailure(error, context) {
+    const login = "'" + context.bin + " login'";
+    const environment = context.envVars.length ? ["Or supply credentials through the environment: " + context.envVars.join(", ") + "."] : [];
+    for (let node = error, depth = 0; node && typeof node === "object" && depth < 4; node = node.cause, depth++) {
+        const message = typeof node.message === "string" && node.message ? node.message : "Login failed.";
+        switch (node.name) {
+            case "DeviceFlowUnavailableError":
+                return { status: "action_required", code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " without --device to sign in through the browser.", ...environment] };
+            case "LoginPollingError":
+                if (node.code === "request_failed" && typeof node.providerError === "string")
+                    return { code: "LOGIN_FAILED", message, nextSteps: ["The provider rejected the login request. Check the client ID and that the application is registered for this sign-in flow, then run " + login + " again.", ...environment] };
+                if (node.code === "request_failed")
+                    return { code: "LOGIN_FAILED", message, nextSteps: ["Check the network and the login service, then run " + login + " again.", ...environment] };
+                if (node.code === "invalid_response")
+                    return { code: "LOGIN_FAILED", message, nextSteps: ["The login service's response did not match its contract. Retry " + login + " once; if it persists, report it to the API owner.", ...environment] };
+                return { code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " again and approve the new request.", ...environment] };
+            case "OAuthResponseError":
+                if (node.code === "request_failed" || node.code === "timed_out")
+                    return { code: "NETWORK_ERROR", message: "The OAuth provider could not be reached (" + String(node.code).replace("_", " ") + ").", nextSteps: ["Check the network and the provider, then run " + login + " again."] };
+                return { code: "LOGIN_FAILED", message: "The OAuth provider returned an unusable response (" + String(node.code).replace(/_/g, " ") + ").", nextSteps: ["Run " + login + " again. If it keeps failing, report it to the API owner.", ...environment] };
+            case "OAuthLoginError":
+                return { code: "LOGIN_FAILED", message, nextSteps: ["Run " + login + " again. If it keeps failing, the OAuth application settings may need attention from the API owner.", ...environment] };
+            case "OAuthSessionError":
+                return { status: "action_required", code: "LOGIN_REQUIRED", message, nextSteps: ["Run " + login + " to sign in again.", ...environment] };
+            case "CredentialStorageError":
+                return { status: "action_required", code: "CREDENTIAL_STORE_UNAVAILABLE", message, nextSteps: [
+                        "Unlock or enable the OS credential store (macOS Keychain, Linux Secret Service or Windows DPAPI) and retry.",
+                        ...environment,
+                        "To use a plaintext file store instead, set " + context.storeVariable + "=file and run " + login + ".",
+                    ] };
+        }
+    }
+    return undefined;
+}
 /** A file lookup needs path guidance, not the generic advice for a missing
  * resource id. Prefer the API's own index when its message names one. */
 function notFoundNextSteps(message) {
@@ -122,13 +190,50 @@ function extractUrl(body, keys) {
     }
     return undefined;
 }
-function extractRetryAfter(e) {
-    const headers = e.headers;
-    const fromHeader = headers?.get?.("retry-after");
-    if (fromHeader)
-        return fromHeader;
-    const match = /retry after (\d+)s/i.exec(JSON.stringify(e.body ?? ""));
-    return match?.[1];
+function isoSeconds(at) {
+    return new Date(Math.ceil(at.getTime() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** "Wait until <time>" when the API said when the limit resets. */
+export function rateLimitNextStep(retryAt, then) {
+    return retryAt instanceof Date && !Number.isNaN(retryAt.getTime())
+        ? "Rate limited: wait until " + isoSeconds(retryAt) + ", then " + then + "."
+        : "Rate limited: back off, then " + then + "; the SDK already honored any Retry-After within its ceiling.";
+}
+/** The vendor's own code on an in-band GraphQL error: the first error's
+ * extensions.code, or its type (GitHub). */
+function graphqlVendorCode(error) {
+    const first = error?.errors?.[0];
+    const code = first?.extensions?.code ?? first?.type;
+    return typeof code === "string" && code !== "" ? code : undefined;
+}
+/** GraphQL error codes whose meaning is settled (Apollo's standard codes,
+ * GitHub's types, Linear's codes), by recovery class. Any other code is
+ * passed through as is, with no guessed next step. The MCP server's
+ * classification uses the same table. */
+function graphqlErrorClass(code) {
+    const c = code.toUpperCase();
+    if (c === "NOT_FOUND")
+        return "not_found";
+    if (c === "UNAUTHENTICATED" || c === "AUTHENTICATION_ERROR")
+        return "unauthenticated";
+    if (c === "FORBIDDEN")
+        return "forbidden";
+    if (c === "BAD_USER_INPUT" || c === "GRAPHQL_VALIDATION_FAILED" || c === "GRAPHQL_PARSE_FAILED" || c === "INPUT_ERROR")
+        return "bad_input";
+    if (c === "RATE_LIMITED" || c === "RATELIMITED")
+        return "rate_limited";
+    return undefined;
+}
+/** Error codes APIs report inside a 2xx body (Slack's `error`), mapped to
+ * the stable codes when their meaning is unambiguous. */
+export function payloadFailureCode(code) {
+    if (typeof code !== "string")
+        return undefined;
+    if (/^(not_authed|invalid_auth|token_revoked|token_expired|account_inactive|unauthorized|unauthenticated|forbidden|access_denied|missing_scope)$/i.test(code))
+        return "AUTH_INVALID";
+    if (/^(ratelimited|rate_limited|rate_limit_exceeded|too_many_requests)$/i.test(code))
+        return "RATE_LIMITED";
+    return undefined;
 }
 /**
  * --mode agent beats <PREFIX>_MODE=agent beats "no terminal on either end".
@@ -166,6 +271,28 @@ export function detectHarness(env = process.env) {
         return "devin";
     return null;
 }
+const ENV_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Rewrite `${VAR}` header references into the client's syntax, or drop the headers that hold one. */
+function entryForClient(client, entry) {
+    const style = client.headerEnv ?? "dollar";
+    if (!entry.headers || style === "dollar")
+        return { entry };
+    const headers = {};
+    const dropped = [];
+    for (const [name, value] of Object.entries(entry.headers)) {
+        if (style === "none" && value.search(ENV_REF) !== -1)
+            dropped.push(name);
+        else
+            headers[name] = style === "env-colon" ? value.replace(ENV_REF, "${env:$1}") : style === "brace-env" ? value.replace(ENV_REF, "{env:$1}") : value;
+    }
+    const next = { ...entry };
+    delete next.headers;
+    if (Object.keys(headers).length)
+        next.headers = headers;
+    return dropped.length
+        ? { entry: next, note: client.label + " does not expand environment variables in headers, so the entry omits " + dropped.join(", ") + "; the client signs in with MCP authorization when the server supports it." }
+        : { entry: next };
+}
 function readOr(file, fallback) {
     try {
         return readFileSync(file, "utf8");
@@ -201,10 +328,18 @@ function tomlMerge(existing, name, entry) {
     const lines = [header];
     if (entry.url) {
         lines.push("url = " + JSON.stringify(entry.url));
-        const auth = entry.headers?.Authorization ?? entry.headers?.authorization;
-        const envRef = auth ? /\$\{([A-Z0-9_]+)\}/.exec(auth)?.[1] : undefined;
-        if (envRef)
-            lines.push("bearer_token_env_var = " + JSON.stringify(envRef));
+        const envHeaders = [];
+        for (const [header, value] of Object.entries(entry.headers ?? {})) {
+            const envRef = /\$\{([A-Z0-9_]+)\}/.exec(value)?.[1];
+            if (!envRef)
+                continue;
+            if (header.toLowerCase() === "authorization" && /^Bearer /.test(value))
+                lines.push("bearer_token_env_var = " + JSON.stringify(envRef));
+            else
+                envHeaders.push(JSON.stringify(header) + " = " + JSON.stringify(envRef));
+        }
+        if (envHeaders.length)
+            lines.push("env_http_headers = { " + envHeaders.join(", ") + " }");
     }
     else {
         lines.push("command = " + JSON.stringify(entry.command ?? "node"));
@@ -238,6 +373,7 @@ export const MCP_CLIENTS = [
         label: "VS Code",
         file: (cwd) => join(cwd, ".vscode", "mcp.json"),
         detect: (cwd) => existsSync(join(cwd, ".vscode")) || existsSync(join(home(), ".vscode")),
+        headerEnv: "env-colon",
         write: (existing, name, entry) => jsonMerge(existing, ["servers"], name, standardEntry(entry)),
     },
     {
@@ -245,6 +381,7 @@ export const MCP_CLIENTS = [
         label: "Windsurf",
         file: () => join(home(), ".codeium", "windsurf", "mcp_config.json"),
         detect: () => existsSync(join(home(), ".codeium", "windsurf")),
+        headerEnv: "env-colon",
         write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { serverUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
     },
     {
@@ -252,6 +389,7 @@ export const MCP_CLIENTS = [
         label: "Gemini CLI",
         file: () => join(home(), ".gemini", "settings.json"),
         detect: () => existsSync(join(home(), ".gemini")),
+        headerEnv: "none",
         write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, entry.url ? { httpUrl: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : stdioEntry(entry)),
     },
     {
@@ -259,6 +397,7 @@ export const MCP_CLIENTS = [
         label: "OpenCode",
         file: () => join(xdg(), "opencode", "opencode.json"),
         detect: () => existsSync(join(xdg(), "opencode")),
+        headerEnv: "brace-env",
         write: (existing, name, entry) => jsonMerge(existing, ["mcp"], name, entry.url ? { type: "remote", url: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : { type: "local", command: [entry.command ?? "node", ...(entry.args ?? [])] }),
     },
     {
@@ -266,6 +405,7 @@ export const MCP_CLIENTS = [
         label: "Zed",
         file: () => join(xdg(), "zed", "settings.json"),
         detect: () => existsSync(join(xdg(), "zed")),
+        headerEnv: "none",
         write: (existing, name, entry) => jsonMerge(existing, ["context_servers"], name, entry.url ? { source: "custom", url: entry.url, ...(entry.headers ? { headers: entry.headers } : {}) } : { source: "custom", command: entry.command ?? "node", args: entry.args ?? [] }),
     },
     {
@@ -284,23 +424,32 @@ export const MCP_CLIENTS = [
         label: "Cursor",
         file: (cwd) => join(cwd, ".cursor", "mcp.json"),
         detect: () => existsSync(join(home(), ".cursor")),
+        headerEnv: "env-colon",
         write: (existing, name, entry) => jsonMerge(existing, ["mcpServers"], name, standardEntry(entry)),
     },
 ];
+// Every client's write receives entries in its own env-reference syntax,
+// whether it is called through writeMcpConfig or directly.
+for (const client of MCP_CLIENTS) {
+    const write = client.write;
+    client.write = (existing, name, entry) => write(existing, name, entryForClient(client, entry).entry);
+}
 export function findMcpClient(id) {
     return MCP_CLIENTS.find((c) => c.id === id);
 }
-/** Merge the entry into one client's config file. Never writes a literal secret: callers pass env references. */
+/** Merge the entry into one client's config file. Never writes a literal secret: callers pass `${VAR}` references, which each client receives in its own syntax. */
 export function writeMcpConfig(client, cwd, name, entry) {
     const file = client.file(cwd);
     if (!entry.url && client.id === "claude-desktop" && !entry.command) {
         return { client: client.id, file, written: false, note: "Claude Desktop reads only stdio servers from its config file; add a remote server as a connector in the app." };
     }
     const existing = readOr(file, "");
+    const adapted = entryForClient(client, entry);
     const next = client.write(existing, name, entry);
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, next);
-    return { client: client.id, file, written: true, ...(client.incompatible ? { note: client.incompatible } : {}) };
+    const note = [client.incompatible, adapted.note].filter(Boolean).join(" ");
+    return { client: client.id, file, written: true, ...(note ? { note } : {}) };
 }
 /** Does a client's config already mention this server? For doctor. */
 export function mcpConfigured(client, cwd, name) {
@@ -346,7 +495,6 @@ export function agentInstructionsFile(cwd) {
         return claude;
     return agents;
 }
-/** One line per command, pipe-delimited: the compact index that goes into AGENTS.md. */
 /** string, number, usd|eur, string[], usd|eur[], object, json — the type as a reader expects it. */
 export function flagTypeLabel(f) {
     const inline = (values) => values && values.join("|").length <= 24 ? values.join("|") : values ? "enum" : undefined;
@@ -354,6 +502,7 @@ export function flagTypeLabel(f) {
         return (inline(f.items?.enum) ?? f.items?.type ?? "json") + "[]";
     return inline(f.enum) ?? f.type;
 }
+/** One line per command, pipe-delimited: the compact index that goes into AGENTS.md. */
 export function compactIndex(commands) {
     return commands
         .map((c) => {
@@ -362,27 +511,56 @@ export function compactIndex(commands) {
     })
         .join("\n");
 }
+/** Bytes of command index the guide and AGENTS.md carry before they switch to one line per resource. */
+export const COMMAND_INDEX_BUDGET = 8_000;
+const RESOURCE_INDEX_NAMES = 12;
+/**
+ * One line per resource with its first command names, for an API whose
+ * per-command index would not fit COMMAND_INDEX_BUDGET. Resources past the
+ * budget are counted, not listed; help --json has them all.
+ */
+export function resourceIndex(bin, commands) {
+    const byResource = new Map();
+    for (const c of commands)
+        byResource.set(c.resource, [...(byResource.get(c.resource) ?? []), c.command]);
+    const lines = [];
+    let bytes = 0;
+    let listed = 0;
+    for (const [resource, names] of byResource) {
+        const more = names.length - RESOURCE_INDEX_NAMES;
+        const line = resource + ": " + names.slice(0, RESOURCE_INDEX_NAMES).join(", ") + (more > 0 ? ", … +" + more + " more" : "");
+        if (bytes + line.length + 1 > COMMAND_INDEX_BUDGET)
+            break;
+        lines.push(line);
+        bytes += line.length + 1;
+        listed++;
+    }
+    if (listed < byResource.size)
+        lines.push("… " + (byResource.size - listed) + " more resources: " + bin + " help --json");
+    return lines.join("\n");
+}
 /** The AGENTS.md block body. */
 export function agentBlock(ctx, commands) {
     const auth = ctx.authEnvVars.length ? ctx.authEnvVars.join(", ") : "(none)";
-    const index = ctx.docsIndexUrl ?? (ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms.txt" : null);
+    const docsIndex = ctx.docsIndexUrl ?? (ctx.docsUrl ? ctx.docsUrl.replace(/\/+$/, "") + "/llms.txt" : null);
+    const index = compactIndex(commands);
     return [
         "## " + ctx.bin + " CLI (" + ctx.apiTitle + ")",
         "",
         "API commands write JSON on stdout; discovery commands take --json. Errors are JSON on stderr ({status, issues[{code,message}], next_steps}), exit 0/1/2. Non-interactive under an agent: no prompts, no browsers.",
         "",
-        ...((ctx.omittedOperations?.length ?? 0) > 0 ? ["- Plan limit: generated " + (ctx.generatedOperationCount ?? commands.length) + " of " + ((ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperations.length) + " operations. Omitted: " + ctx.omittedOperations.map((op) => "`" + op.tool + "` (" + op.method + " " + op.path + ")").join(", ") + ". These return `PLAN_LIMIT`; upgrade and regenerate before use."] : []),
-        "- Auth: " + auth + " in the environment, or `" + ctx.bin + " login`. Never write a key into a file in this repo.",
-        "- Discover: `" + ctx.bin + " --help`, `" + ctx.bin + " <resource> <command> --help`, `" + ctx.bin + " help --json` (machine-readable), `" + ctx.bin + " agent-guide --format json`.",
-        "- Docs: " + (index ? "`" + ctx.bin + " docs search <term> --json`; " + index : "`" + ctx.bin + " docs <resource> <command> --json` (a docs URL was not provided at generate time)") + ".",
+        ...((ctx.omittedOperationCount ?? 0) > 0 ? ["- Coverage: this build includes " + (ctx.generatedOperationCount ?? commands.length) + " of " + ((ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperationCount) + " operations; api.json lists the rest, and calling one returns `PLAN_LIMIT`."] : []),
+        ctx.authNotDeclared
+            ? "- Auth: not declared by the API Spec. If the API needs a token, set " + auth + " or run `" + ctx.bin + " login`; other headers go in `--header \"Name: value\"` or " + ctx.envPrefix + "_HEADERS. Never write a key into a file in this repo."
+            : "- Auth: " + auth + " in the environment, or `" + ctx.bin + " login`. Never write a key into a file in this repo.",
+        "- Discover: `" + ctx.bin + " help --json` indexes resources and command names; `" + ctx.bin + " help <resource> --json` lists a resource's commands; `" + ctx.bin + " help <resource> <command> --json` gives one command's flags. `" + ctx.bin + " help --json --all` prints every command with every flag at once. Humans: `" + ctx.bin + " --help`, `" + ctx.bin + " <resource> <command> --help`.",
+        "- Docs: " + (docsIndex ? "`" + ctx.bin + " docs search <term> --json`; " + docsIndex : "`" + ctx.bin + " docs <resource> <command> --json` (a docs URL was not provided at generate time)") + ".",
         "- Lists: `--all` streams every page as NDJSON. Destructive commands need `--force`.",
         ...(ctx.hasMcp ? ["- MCP: `" + ctx.bin + " mcp install --all` registers this API's MCP server with the agent clients on this machine" + (ctx.mcpUrl ? " (hosted: " + ctx.mcpUrl + ")" : "") + "."] : []),
         "",
-        "Commands (resource command | METHOD path | required flags | summary):",
-        "",
-        "```",
-        compactIndex(commands),
-        "```",
+        ...(Buffer.byteLength(index) <= COMMAND_INDEX_BUDGET
+            ? ["Commands (resource command | METHOD path | required flags | summary):", "", "```", index, "```"]
+            : ["Commands by resource (" + commands.length + " commands; `" + ctx.bin + " help <resource> --json` lists a resource's commands with summaries):", "", "```", resourceIndex(ctx.bin, commands), "```"]),
     ].join("\n");
 }
 /** What `agent-guide --format json` returns. */
@@ -401,12 +579,12 @@ export function agentGuide(ctx, commands) {
         package: ctx.pkg,
         api: ctx.apiTitle,
         version: ctx.version,
-        generated_by: "typeship",
+        generated_by: "Typeship",
         guide: agentBlock(ctx, commands),
         first_command: first ? ctx.bin + " " + first.resource + " " + first.command : ctx.bin + " --help",
         docs_index_url: docsIndexUrl,
         docs_full_url: docsFullUrl,
-        ...((ctx.omittedOperations?.length ?? 0) > 0 ? { coverage: { generated_operations: ctx.generatedOperationCount ?? commands.length, total_operations: (ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperations.length, omitted_operations: ctx.omittedOperations } } : {}),
+        ...((ctx.omittedOperationCount ?? 0) > 0 ? { coverage: { generated_operations: ctx.generatedOperationCount ?? commands.length, total_operations: (ctx.generatedOperationCount ?? commands.length) + ctx.omittedOperationCount } } : {}),
         hosted_mcp_url: ctx.mcpUrl,
         local_mcp: ctx.hasMcp ? ctx.bin + "-mcp (stdio) or '" + ctx.bin + " mcp install --all'" : null,
         skills_install: ctx.skillsRepo ? "npx skills add " + ctx.skillsRepo : null,
@@ -419,12 +597,13 @@ export function agentGuide(ctx, commands) {
             destructive: "Commands classified as destructive need --force (or --yes); without it they return CONFIRMATION_REQUIRED with the exact command to run.",
             flags: "Positional path arguments first, then --flags. Array flags take a comma list, the flag repeated, or a JSON array; object flags take JSON. --data '<json>' merges under field flags (@<file> reads a file, - reads stdin).",
             pagination: "Paginated commands return {items, hasMore, nextPage, nextCommand}: run nextCommand for the next page, or --all walks every page.",
+            discovery: "help --json is a bounded index of resources and command names. help <resource> --json pages through one resource's commands (next_command), help <resource> <command> --json is one command's flags, docs <resource> <command> --json its complete schemas, and docs search <term> --json finds commands by topic. help --json --all prints every command with every flag; on a large API it is large.",
         },
         builtins: ctx.builtins,
         next_steps: [
             ...(ctx.authEnvVars.length ? ["Set " + ctx.authEnvVars[0] + " in the environment or run '" + ctx.bin + " login'."] : []),
             "Run '" + ctx.bin + " auth check'.",
-            "Run '" + ctx.bin + " help --json' for the command index, or read the AGENTS.md block '" + ctx.bin + " init' writes.",
+            "Run '" + ctx.bin + " help --json' for the command index, then '" + ctx.bin + " help <resource> <command> --json' for the command you need.",
             ...(ctx.hasMcp ? ["Run '" + ctx.bin + " mcp install --all' if this session has an MCP-capable client."] : []),
         ],
     };
@@ -544,3 +723,111 @@ export function summarizeDoctor(checks) {
         next_steps: failing.map((c) => c.fix).filter((f) => Boolean(f)),
     };
 }
+/** Every OAuth scope an operation's security requirements name, in order. */
+export function requiredScopes(security) {
+    return [...new Set((security ?? []).flatMap((requirement) => Object.values(requirement).flat()))];
+}
+export const REDACTED = "<redacted>";
+/** Header and query names that carry credentials, whatever the API calls
+ * them: Authorization, Cookie, X-Api-Key, api_key, access_token, a session
+ * or signature. */
+const SENSITIVE_NAME = /^(authorization|proxy-authorization|cookie|cookie2|set-cookie)$|api[-_]?key|apikey|token|secret|password|passwd|session|signature|credential|^key$|^auth$/i;
+function redactText(text, secrets) {
+    let out = text;
+    for (const secret of secrets)
+        if (secret.length >= 4)
+            out = out.split(secret).join(REDACTED);
+    return out;
+}
+/**
+ * The request a dry run captured, as --dry-run shows it. `sensitiveNames`
+ * are the header and query names the API's security schemes bind; `secrets`
+ * are the resolved credential values, redacted wherever they appear (a
+ * token pasted into a body field, a key in a URL).
+ */
+export async function requestPreview(input, options = {}) {
+    const secrets = [...new Set((options.secrets ?? []).filter((s) => typeof s === "string" && s.length >= 4))].sort((a, b) => b.length - a.length);
+    const named = new Set((options.sensitiveNames ?? []).map((n) => n.toLowerCase()));
+    const sensitive = (name) => named.has(name.toLowerCase()) || SENSITIVE_NAME.test(name);
+    const url = new URL(input.url);
+    const query = {};
+    for (const [name, raw] of url.searchParams) {
+        const value = sensitive(name) ? REDACTED : redactText(raw, secrets);
+        const previous = query[name];
+        query[name] = previous === undefined ? value : Array.isArray(previous) ? [...previous, value] : [previous, value];
+    }
+    const encodedSecrets = [...secrets, ...secrets.map(encodeURIComponent)];
+    const search = [...url.searchParams].map(([name, raw]) => encodeURIComponent(name) + "=" + (sensitive(name) ? REDACTED : redactText(encodeURIComponent(raw), encodedSecrets))).join("&");
+    const shownUrl = url.origin + redactText(url.pathname, encodedSecrets) + (search ? "?" + search : "");
+    const headers = {};
+    for (const [name, value] of Object.entries(input.headers)) {
+        headers[name] = sensitive(name) ? REDACTED : redactText(value, secrets);
+    }
+    const contentType = Object.entries(input.headers).find(([name]) => name.toLowerCase() === "content-type")?.[1] ?? "";
+    const body = await previewBody(input.body, contentType, secrets);
+    return {
+        dry_run: true,
+        sent: false,
+        message: "Dry run: nothing was sent to the API. This is the request the command would send, with credentials redacted.",
+        request: {
+            method: input.method,
+            url: shownUrl,
+            path: redactText(url.pathname, encodedSecrets),
+            query,
+            headers,
+            ...(body !== undefined ? { body } : {}),
+        },
+    };
+}
+async function previewBody(body, contentType, secrets) {
+    if (body === undefined || body === null)
+        return undefined;
+    const redactValue = (value) => {
+        if (typeof value === "string")
+            return redactText(value, secrets);
+        if (Array.isArray(value))
+            return value.map(redactValue);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, SENSITIVE_NAME.test(k) && typeof v === "string" && secrets.some((s) => v.includes(s)) ? REDACTED : redactValue(v)]));
+        return value;
+    };
+    if (typeof body === "string") {
+        if (/json/i.test(contentType)) {
+            try {
+                return redactValue(JSON.parse(body));
+            }
+            catch { /* shown as text */ }
+        }
+        return redactText(body, secrets);
+    }
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        const parts = [];
+        for (const [name, value] of body.entries()) {
+            parts.push(typeof value === "string"
+                ? { name, value: redactText(value, secrets) }
+                : { name, filename: value.name, ...(value.type ? { type: value.type } : {}), bytes: value.size });
+        }
+        return { multipart: parts };
+    }
+    if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams)
+        return redactText(body.toString(), secrets);
+    if (typeof Blob !== "undefined" && body instanceof Blob)
+        return { binary: true, bytes: body.size, ...(body.type ? { type: body.type } : {}) };
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer)
+        return { binary: true, bytes: body.byteLength };
+    return { stream: true };
+}
+/** --dry-run for a person: the request line, then query, headers and body. */
+export function formatRequestPreview(preview) {
+    const { request } = preview;
+    const lines = ["Dry run: nothing was sent. Credentials are redacted.", "", request.method + " " + request.url];
+    const headers = Object.entries(request.headers);
+    if (headers.length)
+        lines.push("", "Headers:", ...headers.map(([name, value]) => "  " + name + ": " + value));
+    if (request.body !== undefined) {
+        lines.push("", "Body:");
+        const text = typeof request.body === "string" ? request.body : JSON.stringify(request.body, null, 2);
+        lines.push(...text.split("\n").map((line) => "  " + line));
+    }
+    return lines.join("\n") + "\n";
+}