@capgo/cli 8.32.7 → 8.33.1

package/dist/src/shared/cli-user-error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker for *expected* CLI failures that represent a legitimate user-facing
+ * state — missing input, a channel with no bundle linked, insufficient
+ * permissions — rather than a crash. The CLI still prints a clear message and
+ * exits non-zero, but `shouldCapturePosthogException` skips these so they never
+ * open an error tracking `$exception` issue. They are still counted via
+ * `trackCommandFailed` / `categorizeCliError`, so failure analytics stay intact.
+ *
+ * Keep any dynamic identifier (e.g. a channel name) OUT of the message and pass
+ * it via `context` instead: interpolating it into the message makes error
+ * tracking fingerprint a separate issue per value, which is exactly the noise
+ * this class exists to avoid.
+ *
+ * Precedent for domain-specific error markers already exists in the CLI with
+ * `MacOSSigningError` and `BuildRecordReadError`.
+ */
+export declare class CliUserError extends Error {
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, context?: Record<string, unknown>);
+}

package/dist/src/types/supabase.types.d.ts

@@ -1514,6 +1514,7 @@ export type Database = {
                     versions_created: number;
                     apps_with_cli_onboarding_builds_24h: number;
                     apps_with_manual_builds_24h: number;
+                    apps_with_preview: number;
                     apps_active: number | null;
                     average_ltv: number;
                     build_avg_seconds_day_android: number;
@@ -1607,6 +1608,7 @@ export type Database = {
                     versions_created?: number;
                     apps_with_cli_onboarding_builds_24h?: number;
                     apps_with_manual_builds_24h?: number;
+                    apps_with_preview?: number;
                     apps_active?: number | null;
                     average_ltv?: number;
                     build_avg_seconds_day_android?: number;
@@ -1700,6 +1702,7 @@ export type Database = {
                     versions_created?: number;
                     apps_with_cli_onboarding_builds_24h?: number;
                     apps_with_manual_builds_24h?: number;
+                    apps_with_preview?: number;
                     apps_active?: number | null;
                     average_ltv?: number;
                     build_avg_seconds_day_android?: number;

package/dist/src/utils.d.ts

@@ -24,6 +24,14 @@ export declare const TUS_UPLOAD_RETRY_DELAYS: number[];
 export declare const MAX_MANIFEST_ENTRIES = 10000;
 /** User-facing error when a delta/manifest upload exceeds MAX_MANIFEST_ENTRIES. */
 export declare function deltaManifestTooLargeMessage(fileCount: number): string;
+/**
+ * Stable `name` for the error thrown when the standard (non-TUS) upload hits its
+ * wall-clock timeout. Kept typed and constant so error tracking groups every
+ * occurrence into a single issue instead of one duplicate per CLI version.
+ */
+export declare const UPLOAD_TIMEOUT_ERROR_NAME = "BundleUploadTimeoutError";
+/** User-facing error when the standard HTTP PUT upload exceeds its wall-clock timeout. */
+export declare function uploadTimeoutMessage(timeoutMs: number): string;
 export declare const PACKNAME = "package.json";
 export type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 export type Organization = ArrayElement<Database['public']['Functions']['get_orgs_v7']['Returns']>;
@@ -135,7 +143,14 @@ interface CapgoConfig {
     hostFilesApi: string;
     hostApi: string;
 }
-export declare function getRemoteConfig(silent?: boolean, signal?: AbortSignal): Promise<CapgoConfig>;
+export declare function getRemoteConfig(silent?: boolean, signal?: AbortSignal): Promise<{
+    supaHost?: string;
+    supaKey?: string;
+    host: string;
+    hostWeb: string;
+    hostFilesApi: string;
+    hostApi: string;
+}>;
 interface CapgoFilesConfig {
     partialUpload: boolean;
     partialUploadForced: boolean;
@@ -148,12 +163,42 @@ interface CapgoFilesConfig {
 export declare function getRemoteFileConfig(): Promise<CapgoFilesConfig>;
 export declare function normalizeSupabaseHost(host: string): string;
 export declare function formatCapgoApiErrorBody(body: unknown): string;
-/** Resolve Capgo public API base URL for CLI mutations (app create/update, etc.). */
+/** Capgo-managed Supabase hosts (cloud). Match hostname exactly. */
+export declare function isCapgoManagedSupabaseHost(supaHost?: string): boolean;
+/**
+ * Resolve Capgo public API base URL for CLI mutations (app create/update, etc.).
+ * Capgo cloud uses api.capgo.app. Self-host with only localSupa (default localApi)
+ * keeps /functions/v1 on that Supabase host.
+ */
 export declare function resolveConfiguredCapgoPublicApiHost(config: {
     hostApi: string;
+    hostFilesApi?: string;
     supaHost?: string;
     supaKey?: string;
 }): string;
+export interface CapgoCliInvokeOptions {
+    apikey: string;
+    method?: string;
+    body?: unknown;
+    /** Capgo cloud files worker; ignored when resolving to self-host /functions/v1 */
+    useFilesHost?: boolean;
+    supaHost?: string;
+    supaAnon?: string;
+    signal?: AbortSignal;
+}
+export declare function getCapgoCliHttpStatus(error: unknown): number | undefined;
+export declare function readCapgoCliApiErrorPayload(error: unknown): Promise<{
+    error?: string;
+    message?: string;
+} | null>;
+/**
+ * Invoke Capgo HTTP APIs formerly reached via supabase.functions.invoke.
+ * Capgo cloud -> hostApi / hostFilesApi. Self-host -> /functions/v1.
+ */
+export declare function invokeCapgoCliApi<T = any>(path: string, options: CapgoCliInvokeOptions): Promise<{
+    data: T | null;
+    error: Error | null;
+}>;
 export declare function resolveCapgoPublicApiHost(options?: {
     supaHost?: string;
     supaAnon?: string;
@@ -1589,6 +1634,7 @@ export declare function createSupabaseClient(apikey: string, supaHost?: string,
                 versions_created: number;
                 apps_with_cli_onboarding_builds_24h: number;
                 apps_with_manual_builds_24h: number;
+                apps_with_preview: number;
                 apps_active: number | null;
                 average_ltv: number;
                 build_avg_seconds_day_android: number;
@@ -1682,6 +1728,7 @@ export declare function createSupabaseClient(apikey: string, supaHost?: string,
                 versions_created?: number;
                 apps_with_cli_onboarding_builds_24h?: number;
                 apps_with_manual_builds_24h?: number;
+                apps_with_preview?: number;
                 apps_active?: number | null;
                 average_ltv?: number;
                 build_avg_seconds_day_android?: number;
@@ -1775,6 +1822,7 @@ export declare function createSupabaseClient(apikey: string, supaHost?: string,
                 versions_created?: number;
                 apps_with_cli_onboarding_builds_24h?: number;
                 apps_with_manual_builds_24h?: number;
+                apps_with_preview?: number;
                 apps_active?: number | null;
                 average_ltv?: number;
                 build_avg_seconds_day_android?: number;
@@ -5664,7 +5712,10 @@ export declare function findMainFileForProjectType(projectType: string, isTypeSc
 export declare function findBuildCommandForProjectType(projectType: string): Promise<"build" | "generate">;
 export declare function findMainFile(silent?: boolean, rootDir?: string): Promise<string>;
 export declare function updateOrCreateVersion(supabase: SupabaseClient<Database>, update: Database['public']['Tables']['app_versions']['Insert']): Promise<import("@supabase/supabase-js").PostgrestSingleResponse<null>>;
-export declare function uploadUrl(supabase: SupabaseClient<Database>, appId: string, name: string): Promise<string>;
+export declare function uploadUrl(apikey: string, appId: string, name: string, options?: {
+    supaHost?: string;
+    supaAnon?: string;
+}): Promise<string>;
 export declare const BROTLI_MIN_UPDATER_VERSION_V5 = "5.10.0";
 export declare const BROTLI_MIN_UPDATER_VERSION_V6 = "6.25.0";
 export declare const BROTLI_MIN_UPDATER_VERSION_V7 = "7.0.30";
@@ -5677,8 +5728,13 @@ export type manifestType = Awaited<ReturnType<typeof generateManifest>>;
 export declare function zipFile(filePath: string): Promise<Buffer>;
 export declare function zipFileUnix(filePath: string): Buffer<ArrayBufferLike>;
 export declare function zipFileWindows(filePath: string): Promise<Buffer>;
+export declare function appAddHintMessage(appId: string): string;
+export declare function isAppNotFoundError(error: unknown): boolean;
 export declare function uploadTUS(apikey: string, data: Buffer, orgId: string, appId: string, name: string, spinner: UploadSpinner, localConfig: CapgoConfig, chunkSize: number): Promise<boolean>;
-export declare function deletedFailedVersion(supabase: SupabaseClient<Database>, appId: string, name: string): Promise<void>;
+export declare function deletedFailedVersion(apikey: string, appId: string, name: string, options?: {
+    supaHost?: string;
+    supaAnon?: string;
+}): Promise<void>;
 export interface VersionManifestEntry {
     file_name: string;
     s3_path: string;
@@ -5688,7 +5744,10 @@ export interface VersionManifestEntry {
  * Writes delta manifest rows through the backend (file_size stays 0 until R2 size lookup).
  * Prefer this over writing app_versions.manifest jsonb — old CLIs still use that legacy path.
  */
-export declare function setVersionManifest(supabase: SupabaseClient<Database>, appId: string, name: string, manifest: VersionManifestEntry[]): Promise<void>;
+export declare function setVersionManifest(apikey: string, appId: string, name: string, manifest: VersionManifestEntry[], options?: {
+    supaHost?: string;
+    supaAnon?: string;
+}): Promise<void>;
 export declare function updateOrCreateChannel(supabase: SupabaseClient<Database>, update: Database['public']['Tables']['channels']['Insert']): Promise<import("@supabase/supabase-js").PostgrestSingleResponse<{
     allow_dev: boolean;
     allow_device: boolean;
@@ -5751,7 +5810,10 @@ export declare function assertCliPermission(supabase: SupabaseClient<Database>,
     silent?: boolean;
 }): Promise<void>;
 export declare function assertOrgPermission(supabase: SupabaseClient<Database>, apikey: string, permissionKey: string, orgId: string, message: string, silent: boolean): Promise<void>;
-export declare function getOrganizationId(supabase: SupabaseClient<Database>, appId: string): Promise<string>;
+export declare function getOrganizationId(apikey: string, appId: string, options?: {
+    supaHost?: string;
+    supaAnon?: string;
+}): Promise<string>;
 export declare function getHumanDate(createdA: string | null): string;
 export declare function getPMAndCommand(): {
     pm: PackageManagerType;
@@ -5759,6 +5821,11 @@ export declare function getPMAndCommand(): {
     installCommand: string;
     runner: PackageManagerRunner;
 };
+export declare function setPMAndCommand(next: {
+    pm: PackageManagerType;
+    command: InstallCommand;
+    runner: PackageManagerRunner;
+}): void;
 export declare function getNativeProjectResetAdvice(platformRunner: string, nativePlatform: 'ios' | 'android'): {
     summary: string;
     command: string;

package/dist/src/versionHelpers.d.ts

@@ -1,9 +1,42 @@
+/** CLI / API auto-bump levels (fix is normalized to patch at parse time) */
+export type AutoBumpLevel = 'major' | 'minor' | 'patch' | 'metadata';
+/** Resolver input including AI-backed classification */
+export type AutoBumpInput = AutoBumpLevel | 'ai';
+/** @std/semver increment release types used by auto-bump */
+export type AutoBumpRelease = 'major' | 'minor' | 'patch' | 'prerelease';
+/**
+ * Normalize CLI/SDK auto-bump values including `ai`.
+ * - bare flag / true → minor
+ * - fix → patch
+ * - ai → ai (resolved later via Workers AI)
+ * - metadata stays metadata (mapped to prerelease increment later)
+ */
+export declare function normalizeAutoBumpInput(level: string | boolean | undefined | null): AutoBumpInput | undefined;
+/**
+ * Normalize CLI/SDK auto-bump values to concrete bump levels (excludes `ai`).
+ * Prefer `normalizeAutoBumpInput` when `ai` is allowed.
+ */
+export declare function normalizeAutoBumpLevel(level: string | boolean | undefined | null): AutoBumpLevel | undefined;
+export declare function autoBumpLevelToRelease(level: AutoBumpLevel | AutoBumpRelease): AutoBumpRelease;
+/**
+ * Auto-bump a semver version by the given level
+ * @param currentVersion - The current version string (e.g., "1.0.0")
+ * @param level - major | minor | patch | metadata | prerelease
+ * @returns The bumped version or a fallback version if parsing fails
+ */
+export declare function autoBumpVersionBy(currentVersion: string, level?: AutoBumpLevel | AutoBumpRelease): string;
 /**
  * Auto-bump a semver version by incrementing the patch number
  * @param currentVersion - The current version string (e.g., "1.0.0")
  * @returns The bumped version or a fallback version if parsing fails
  */
 export declare function autoBumpVersion(currentVersion: string): string;
+/**
+ * Auto-bump a semver version by incrementing the minor number
+ * @param currentVersion - The current version string (e.g., "1.0.0")
+ * @returns The bumped version or a fallback version if parsing fails
+ */
+export declare function autoBumpMinorVersion(currentVersion: string): string;
 /**
  * Interactively ask the user how to handle version bumping
  * @param currentVersion - The current version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capgo/cli",
   "type": "module",
-  "version": "8.32.7",
+  "version": "8.33.1",
   "description": "A CLI to upload to capgo servers",
   "author": "Martin martin@capgo.app",
   "license": "Apache 2.0",
@@ -73,6 +73,7 @@
     "test:upload": "bun test/test-upload-validation.mjs",
     "test:fail-on-incompatible": "bun test/test-fail-on-incompatible.mjs",
     "test:native-dependencies": "bun test/test-native-dependencies.mjs",
+    "test:package-json-guard": "bun test/test-package-json-guard.mjs",
     "test:credentials": "bun test/test-credentials.mjs",
     "test:asc-key-protocol": "bun test/test-asc-key-protocol.mjs",
     "test:credentials-validation": "bun test/test-credentials-validation.mjs",
@@ -160,7 +161,7 @@
     "test:ios-marketing-version": "bun test/test-ios-marketing-version.mjs",
     "test:platform-flow-contract": "bun test/test-platform-flow-contract.mjs",
     "test:tail-engine-shared": "bun test/test-tail-engine-shared.mjs",
-    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:native-dependencies && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:app-set-options && bun run test:mcp-analytics && bun run test:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-monorepo-targeting && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:mcp-no-key-handshake && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:cicd-failure-help && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-upload-prompt && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt && bun run test:apple-api-cert-create && bun run test:android-tail-engine && bun run test:android-tail-render && bun run test:android-tail-routing && bun run test:dev-gate-stripped && bun run test:frame-fit-ios-shared && bun run test:ios-confirm-app-id && bun run test:ios-create-new && bun run test:ios-e2e && bun run test:ios-flow-contract && bun run test:ios-import-discovery && bun run test:ios-import-export && bun run test:ios-import-pickers && bun run test:ios-import-recovery && bun run test:ios-recovery && bun run test:ios-resume && bun run test:ios-tail-handoff && bun run test:ios-tui-render && bun run test:p8-error && bun run test:ios-tui-routing && bun run test:ios-updater-sync-validation && bun run test:ios-verify-app && bun run test:ios-marketing-version && bun run test:platform-flow-contract && bun run test:tail-engine-shared && bun run test:prescan && bun run test:android-reporting-api && bun run test:android-app-verification && bun run test:android-rename && bun run test:appflow-auth && bun run test:appflow-api-map && bun run test:appflow-validate && bun run test:appflow-flow && bun run test:appflow-gapfill && bun run test:appflow-engine && bun run test:appflow-tail && bun run test:appflow-fetch && bun run test:appflow-sa-decode && bun run test:app-permission-helper && bun run test:organization-set-api-host && bun run test:trial-warning && bun run test:plan-validation",
+    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:auto-bump-version && bun run test:auto-bump-ai-diff && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:native-dependencies && bun run test:package-json-guard && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:app-set-options && bun run test:mcp-analytics && bun run test:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-monorepo-targeting && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:mcp-no-key-handshake && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:cicd-failure-help && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-upload-prompt && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt && bun run test:apple-api-cert-create && bun run test:android-tail-engine && bun run test:android-tail-render && bun run test:android-tail-routing && bun run test:dev-gate-stripped && bun run test:frame-fit-ios-shared && bun run test:ios-confirm-app-id && bun run test:ios-create-new && bun run test:ios-e2e && bun run test:ios-flow-contract && bun run test:ios-import-discovery && bun run test:ios-import-export && bun run test:ios-import-pickers && bun run test:ios-import-recovery && bun run test:ios-recovery && bun run test:ios-resume && bun run test:ios-tail-handoff && bun run test:ios-tui-render && bun run test:p8-error && bun run test:ios-tui-routing && bun run test:ios-updater-sync-validation && bun run test:ios-verify-app && bun run test:ios-marketing-version && bun run test:platform-flow-contract && bun run test:tail-engine-shared && bun run test:prescan && bun run test:android-reporting-api && bun run test:android-app-verification && bun run test:android-rename && bun run test:appflow-auth && bun run test:appflow-api-map && bun run test:appflow-validate && bun run test:appflow-flow && bun run test:appflow-gapfill && bun run test:appflow-engine && bun run test:appflow-tail && bun run test:appflow-fetch && bun run test:appflow-sa-decode && bun run test:app-permission-helper && bun run test:organization-set-api-host && bun run test:trial-warning && bun run test:plan-validation",
     "test:build-platform-selection": "bun test/test-build-platform-selection.mjs",
     "test:ai-log-capture": "bun test/test-ai-log-capture.mjs",
     "test:ai-analyze-flow": "bun test/test-ai-analyze-flow.mjs",
@@ -204,7 +205,9 @@
     "test:app-permission-helper": "bun test/test-app-permission-helper.mjs",
     "test:organization-set-api-host": "bun test/test-organization-set-api-host.mjs",
     "test:trial-warning": "bun test/test-trial-warning.mjs",
-    "test:plan-validation": "bun test/test-plan-validation.mjs"
+    "test:plan-validation": "bun test/test-plan-validation.mjs",
+    "test:auto-bump-version": "bun test/test-auto-bump-version.mjs",
+    "test:auto-bump-ai-diff": "bun test/test-auto-bump-ai-diff.mjs"
   },
   "dependencies": {
     "@inkjs/ui": "^2.0.0",

package/skills/native-builds/SKILL.md

@@ -7,6 +7,22 @@ description: Use when working with Capgo Cloud native iOS and Android build requ
 
 Use this skill for Capgo Cloud native iOS and Android build workflows.
 
+## Build prescan overrides
+
+Before `build request` uploads, Capgo runs a local/remote **prescan**. Prefer per-check overrides over disabling the whole scan:
+
+- `--prescan-skip <checkId>` — do not run that check (repeatable / comma-separated)
+- `--prescan-warn <checkId>` — still run it, but downgrade findings to warning
+- `--no-prescan` / `--prescan-ignore-fatal` — global escapes; use only when necessary
+
+Example (intentional Capacitor `server.url` / Next.js shell):
+
+```bash
+npx @capgo/cli@latest build request <appId> --platform ios --prescan-skip ios/capacitor-server-url-shipped
+```
+
+Standalone: `build prescan` accepts `--skip` / `--warn`. Full catalog: `webdocs/prescan-checks.mdx`.
+
 ## Onboarding (automated iOS setup)
 
 ### `build init` (alias: `build onboarding`)
@@ -116,7 +132,7 @@ interface BuildLogger {
 - `--app-store-connect-team-id <id>`
 - `--ios-scheme <scheme>`
 - `--ios-target <target>`
-- `--ios-distribution <mode>`: `app_store` or `ad_hoc`
+- `--ios-distribution <mode>`: `app_store` (default, uploads to TestFlight) or `ad_hoc` (skips store upload; use with `--output-upload` for IPA-only when the App Store app does not exist yet)
 - `--ios-provisioning-profile <mapping>`: repeatable path or `bundleId=path`
 
 #### Android request options
@@ -131,13 +147,13 @@ interface BuildLogger {
 
 #### Output behavior options
 
-- `--no-playstore-upload`: skip Play Store upload for the build, requires `--output-upload`
+- `--output-upload`: upload the finished IPA/APK/AAB to Capgo storage and print a time-limited download link (and QR). Pair with `--no-playstore-upload` (Android) or `--ios-distribution ad_hoc` (iOS) for artifact-only builds
+- `--no-output-upload`: skip Capgo storage upload (no download link); store upload can still happen when store credentials are set
+- `--no-playstore-upload`: Android — skip Google Play upload for this build (ignores saved Play credentials). Requires `--output-upload`. Use when the Play app does not exist yet or you only need the AAB download
 - `--submit-to-store-review`: submit after upload instead of leaving a draft/inactive store release. Android completes the Google Play release; iOS submits to TestFlight external review.
 - `--store-release-name <name>`: Android Google Play version_name/release label.
 - `--store-release-notes <notes>`: Google Play changelog and iOS TestFlight What to Test text.
 - `--ios-testflight-groups <groups>`: comma-separated external TestFlight group names or IDs required with `--submit-to-store-review` on iOS.
-- `--output-upload`
-- `--no-output-upload`
 - `--output-retention <duration>`: `1h` to `7d`
 - `--skip-build-number-bump`
 - `--no-skip-build-number-bump`