From 79fae0369bf776be9d6b4da966f554c89e422cf9 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 10:06:38 +0200
Subject: [PATCH 01/14] feat(cli): offer AI build debug in onboarding TUI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Ink-based `build init` wizard runs `requestBuildInternal` with a custom
logger so build output flows through React state. On failure today the build
code still tries to drive the AI flow with `@clack/prompts` (`confirm`,
`select`, `spinner`) — but Ink owns the terminal, so those clack writes/reads
collide with React redraws and the AI prompt either corrupts the TUI or hangs.
Net effect: users in the onboarding wizard never get a usable AI debug offer.

This change adds a `caller-handled` mode so the wizard can drive the AI UX
with Ink-native components.

Layering (matches docs/superpowers/specs in wiki):

- `cli/src/ai/analyze.ts`
  - `runCapgoAiAnalysis({ apiHost, apikey, jobId, appId })` reads the
    `/tmp/capgo-builds/<jobId>.log` file, returns `too_big` over 10 MB,
    `error { message: 'log_unavailable' }` if missing, otherwise delegates
    to `postAnalyzeRequest`.
  - `releaseCapturedLogs(jobId)` thin wrapper around
    `cleanupCapturedJobFiles({ keepAiPromptFile: false })`.

- `cli/src/ai/telemetry.ts`
  - Extend `AiAnalysisTriggeredBy` with `'onboarding'` so PostHog can
    segment onboarding-driven AI usage from CLI menu / CI flag.

- `cli/src/schemas/build.ts`
  - `BuildRequestOptions.aiAnalysisMode?: 'auto-prompt' | 'caller-handled' | 'skip'`
    (default `'auto-prompt'` — direct CLI invocation matrix unchanged).
  - `BuildRequestResult.aiAnalysis?: { jobId, capturedLogPath, ready }`.

- `cli/src/build/request.ts`
  - Branch the failure-AI block on `aiAnalysisMode`. `'caller-handled'`
    keeps the captured log alive (via `keepPromptFile=true`) and surfaces
    it on the result so callers can run `runCapgoAiAnalysis`. `'skip'`
    no-ops. `'auto-prompt'` keeps the existing clack flow.
  - Capture stays enabled in caller-handled mode regardless of TTY so the
    captured log is always available to the caller; explicit `'skip'`
    suppresses capture entirely.

- `cli/src/build/onboarding/{types,android/types}.ts`
  - New `OnboardingStep`/`AndroidOnboardingStep`: `'ai-analysis-prompt'`,
    `'ai-analysis-running'`, `'ai-analysis-result'`. `STEP_PROGRESS` +
    `getPhaseLabel` entries.

- `cli/src/build/onboarding/{ui,android/ui}/app.tsx`
  - Pass `aiAnalysisMode: 'caller-handled'` to `requestBuildInternal`. On
    failure with `aiAnalysis.ready === true`, transition to
    `'ai-analysis-prompt'` (Ink `<Select>` with Debug-with-AI / Skip).
    Pick "Debug" -> `'ai-analysis-running'` (`<SpinnerLine>`) which calls
    `runCapgoAiAnalysis` and transitions to `'ai-analysis-result'`. Render
    the analysis via existing `renderMarkdown` (ANSI passes through Ink's
    `<Text>`). On exit, call `releaseCapturedLogs(jobId)`.
  - PostHog: `trackAiAnalysisChoice({ ..., triggeredBy: 'onboarding' })`
    fires when the user picks Debug or Skip; `trackAiAnalysisResult` fires
    after `postAnalyzeRequest` resolves. Existing
    `trackBuilderOnboardingStep` continues to fire on each new step.

CI/CD safety: no new detection. The two existing layers handle it —
`shouldCaptureLogs()` gates on TTY, and Ink itself requires a TTY to render.
In CI, capture is off, `result.aiAnalysis` is undefined, and the wizard goes
straight to `build-complete`.

Build infra: TypeScript 6.0.3 turns the deprecated `baseUrl` into a hard
error. Adding `"ignoreDeprecations": "6.0"` per TS recommendation unblocks
`bun run build` on main. Unrelated to the feature but bundled here so the
binary is buildable on the branch.

Test coverage:
- `cli/test/test-ai-onboarding-mode.mjs` (9 tests, all passing):
  - `decideAnalyzeBehavior` matrix unchanged (regression guard)
  - `runCapgoAiAnalysis` happy path, too-big, missing log
  - `releaseCapturedLogs` deletes the log + is best-effort
- Existing `test-ai-analyze-flow`, `test-ai-log-capture`,
  `test-ai-render-markdown`, `test-onboarding-progress`, and
  `test-onboarding-recovery` all still pass.
---
 cli/package.json                            |   5 +-
 cli/src/ai/analyze.ts                       |  42 ++++-
 cli/src/ai/telemetry.ts                     |   2 +-
 cli/src/build/onboarding/android/types.ts   |  11 ++
 cli/src/build/onboarding/android/ui/app.tsx | 160 +++++++++++++++++-
 cli/src/build/onboarding/types.ts           |  11 ++
 cli/src/build/onboarding/ui/app.tsx         | 170 +++++++++++++++++++-
 cli/src/build/request.ts                    |  37 ++++-
 cli/src/schemas/build.ts                    |  20 +++
 cli/test/test-ai-onboarding-mode.mjs        | 167 +++++++++++++++++++
 cli/tsconfig.json                           |   1 +
 11 files changed, 613 insertions(+), 13 deletions(-)
 create mode 100644 cli/test/test-ai-onboarding-mode.mjs

diff --git a/cli/package.json b/cli/package.json
index f9990ec36f..e1ea65c5b7 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -94,11 +94,12 @@
     "test:macos-signing": "bun test/test-macos-signing.mjs",
     "test:apple-api-import-helpers": "bun test/test-apple-api-import-helpers.mjs",
     "test:manifest-path-encoding": "bun test/test-manifest-path-encoding.mjs",
-    "test": "bun run build && 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: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: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-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-render-markdown",
+    "test": "bun run build && 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: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: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-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-render-markdown && bun run test:ai-onboarding-mode",
     "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",
-    "test:ai-render-markdown": "bun test/test-ai-render-markdown.mjs"
+    "test:ai-render-markdown": "bun test/test-ai-render-markdown.mjs",
+    "test:ai-onboarding-mode": "bun test/test-ai-onboarding-mode.mjs"
   },
   "dependencies": {
     "@inkjs/ui": "^2.0.0",
diff --git a/cli/src/ai/analyze.ts b/cli/src/ai/analyze.ts
index b25d2efbf8..8063eaa022 100644
--- a/cli/src/ai/analyze.ts
+++ b/cli/src/ai/analyze.ts
@@ -1,5 +1,5 @@
 import { readFile, stat, writeFile } from 'node:fs/promises'
-import { getAiPromptPath, getLogCapturePath } from './log-capture'
+import { cleanupCapturedJobFiles, getAiPromptPath, getLogCapturePath } from './log-capture'
 import { SYSTEM_PROMPT } from './prompt'
 
 export type AnalyzeBehavior = 'show_menu' | 'ask_then_menu' | 'auto_upload' | 'skip'
@@ -100,3 +100,43 @@ export async function isLogTooBig(jobId: string): Promise<boolean> {
     return false
   }
 }
+
+export interface RunCapgoAiAnalysisInput {
+  apiHost: string
+  apikey: string
+  jobId: string
+  appId: string
+}
+
+// Reads the captured log file for a failed job, then sends it to the Capgo AI
+// edge function. Used by callers (e.g. the Ink onboarding TUI) that can't show
+// the interactive clack menu in `requestBuildInternal`.
+export async function runCapgoAiAnalysis(input: RunCapgoAiAnalysisInput): Promise<PostAnalyzeResult> {
+  // Check the byte limit before the read so a multi-MB log file doesn't get
+  // pulled into memory just to be rejected.
+  if (await isLogTooBig(input.jobId))
+    return { kind: 'too_big' }
+
+  let logs: string
+  try {
+    logs = await readFile(getLogCapturePath(input.jobId), 'utf8')
+  }
+  catch (err) {
+    return { kind: 'error', message: err instanceof Error ? err.message : 'log_unavailable' }
+  }
+
+  return postAnalyzeRequest({
+    apiHost: input.apiHost,
+    apikey: input.apikey,
+    jobId: input.jobId,
+    appId: input.appId,
+    logs,
+  })
+}
+
+// Best-effort cleanup of captured artifacts for a job. Callers in caller-handled
+// mode use this once the user has either viewed the analysis or chosen to skip,
+// since `requestBuildInternal` leaves the log file in place for them.
+export async function releaseCapturedLogs(jobId: string): Promise<void> {
+  await cleanupCapturedJobFiles(jobId, { keepAiPromptFile: false })
+}
diff --git a/cli/src/ai/telemetry.ts b/cli/src/ai/telemetry.ts
index 4113d79d6a..2405e08513 100644
--- a/cli/src/ai/telemetry.ts
+++ b/cli/src/ai/telemetry.ts
@@ -1,7 +1,7 @@
 import { sendEvent } from '../utils.js'
 
 export type AiAnalysisChoice = 'capgo_ai' | 'local_ai' | 'skip' | 'auto_upload'
-export type AiAnalysisTriggeredBy = 'menu' | 'ci_flag'
+export type AiAnalysisTriggeredBy = 'menu' | 'ci_flag' | 'onboarding'
 export type AiAnalysisResult = 'success' | 'already_analyzed' | 'too_big' | 'error'
 
 export interface TrackAiAnalysisChoiceInput {
diff --git a/cli/src/build/onboarding/android/types.ts b/cli/src/build/onboarding/android/types.ts
index d4cd58a973..902ea20c36 100644
--- a/cli/src/build/onboarding/android/types.ts
+++ b/cli/src/build/onboarding/android/types.ts
@@ -55,6 +55,10 @@ export type AndroidOnboardingStep
     | 'ci-secrets-failed'
     | 'ask-build'
     | 'requesting-build'
+    // AI debug — only entered when the build fails and logs were captured
+    | 'ai-analysis-prompt'
+    | 'ai-analysis-running'
+    | 'ai-analysis-result'
     | 'build-complete'
     | 'error'
 
@@ -222,6 +226,9 @@ export const ANDROID_STEP_PROGRESS: Record<AndroidOnboardingStep, number> = {
   'ci-secrets-failed': 88,
   'ask-build': 90,
   'requesting-build': 95,
+  'ai-analysis-prompt': 96,
+  'ai-analysis-running': 98,
+  'ai-analysis-result': 99,
   'build-complete': 100,
   'error': 0,
 }
@@ -279,6 +286,10 @@ export function getAndroidPhaseLabel(step: AndroidOnboardingStep): string {
     case 'ask-build':
     case 'requesting-build':
       return 'Step 4 of 4 · Save & Build'
+    case 'ai-analysis-prompt':
+    case 'ai-analysis-running':
+    case 'ai-analysis-result':
+      return 'AI debug'
     case 'build-complete':
       return 'Complete'
     case 'error':
diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index eafb3129c0..d09f7f7404 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -25,6 +25,9 @@ import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { createSupabaseClient, findSavedKey, findSavedKeySilent, getOrganizationId } from '../../../../utils.js'
 import { loadSavedCredentials, updateSavedCredentials } from '../../../credentials.js'
+import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../../ai/analyze.js'
+import { renderMarkdown } from '../../../../ai/render-markdown.js'
+import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../../request.js'
 import type { CiSecretEntry, CiSecretSetupAdvice, CiSecretTarget } from '../../ci-secrets.js'
 import { createCiSecretEntries, detectCiSecretTargets, getCiSecretTargetLabel, listExistingCiSecretKeys, uploadCiSecrets } from '../../ci-secrets.js'
@@ -377,6 +380,11 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
   // Phase 6 — build output
   const [buildUrl, setBuildUrl] = useState('')
   const [buildOutput, setBuildOutput] = useState<string[]>([])
+  // ── AI-analysis sub-flow (see iOS sibling for full notes). Entered only when
+  // requestBuildInternal returns aiAnalysis.ready=true on a failed build.
+  const [aiJobId, setAiJobId] = useState<string | null>(null)
+  const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
+  const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -1401,6 +1409,11 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           const result = await requestBuildInternal(appId, {
             platform: 'android',
             apikey: capgoKey,
+            // The Ink TUI owns the terminal — @clack/prompts inside
+            // requestBuildInternal would corrupt rendering. Caller-handled mode
+            // surfaces the captured log path via result.aiAnalysis and lets us
+            // render the AI flow with Ink-native components.
+            aiAnalysisMode: 'caller-handled',
           }, true, buildLogger)
           if (cancelled)
             return
@@ -1418,6 +1431,13 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           }
           else {
             setBuildOutput(prev => [...prev, `⚠ ${result.error || 'unknown error'}`])
+            // Offer AI-assisted diagnosis when logs were captured. The log file
+            // stays on disk until releaseCapturedLogs runs in 'build-complete'.
+            if (result.aiAnalysis?.ready && result.aiAnalysis.jobId) {
+              setAiJobId(result.aiAnalysis.jobId)
+              setStep('ai-analysis-prompt')
+              return
+            }
           }
           setStep('build-complete')
         }
@@ -1431,8 +1451,79 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
       })()
     }
 
+    // AI analysis — entered only when requestBuildInternal returned with
+    // aiAnalysis.ready=true. See iOS sibling for full notes.
+    if (step === 'ai-analysis-running' && aiJobId) {
+      ;(async () => {
+        await trackAiAnalysisChoice({
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          orgId: resolvedOrgId ?? '',
+          appId,
+          platform: 'android',
+          jobId: aiJobId,
+          choice: 'capgo_ai',
+          triggeredBy: 'onboarding',
+        }).catch(() => { /* telemetry never breaks the wizard */ })
+
+        const result = await runCapgoAiAnalysis({
+          apiHost: 'https://api.capgo.app',
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          jobId: aiJobId,
+          appId,
+        })
+
+        if (cancelled)
+          return
+
+        const resultTag: 'success' | 'already_analyzed' | 'too_big' | 'error'
+          = result.kind === 'ok'
+            ? 'success'
+            : result.kind === 'already_analyzed'
+              ? 'already_analyzed'
+              : result.kind === 'too_big'
+                ? 'too_big'
+                : 'error'
+
+        await trackAiAnalysisResult({
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          orgId: resolvedOrgId ?? '',
+          appId,
+          platform: 'android',
+          jobId: aiJobId,
+          result: resultTag,
+          errorStatus: result.kind === 'error' ? result.status : undefined,
+        }).catch(() => { /* telemetry never breaks the wizard */ })
+
+        if (result.kind === 'ok') {
+          setAiAnalysisText(renderMarkdown(result.analysis, true))
+          setAiResultMessage(null)
+        }
+        else if (result.kind === 'already_analyzed') {
+          setAiAnalysisText(null)
+          setAiResultMessage('AI analysis was already requested for this build (only one per job).')
+        }
+        else if (result.kind === 'too_big') {
+          setAiAnalysisText(null)
+          setAiResultMessage('Build log is too large for Capgo AI (>10 MB). Try a local AI tool with the captured log.')
+        }
+        else {
+          setAiAnalysisText(null)
+          const detail = [
+            result.status ? `(status ${result.status})` : null,
+            result.message,
+          ].filter(Boolean).join(' ')
+          setAiResultMessage(`AI analysis failed${detail ? `: ${detail}` : ''}.`)
+        }
+        setStep('ai-analysis-result')
+      })()
+    }
+
     if (step === 'build-complete') {
       setBuildOutput([])
+      // Best-effort cleanup of any leftover captured log.
+      if (aiJobId) {
+        void releaseCapturedLogs(aiJobId).catch(() => { /* best-effort */ })
+      }
       const timer = setTimeout(() => {
         if (!cancelled)
           exit()
@@ -1457,9 +1548,9 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build'
-  const showHeader = step !== 'requesting-build'
-  const showLog = step !== 'requesting-build' && step !== 'build-complete'
+  const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result'
+  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result'
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result'
 
   return (
     <Box flexDirection="column" padding={1}>
@@ -2590,6 +2681,69 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
         </Box>
       )}
 
+      {/* AI debug — ask the user whether to send the captured log */}
+      {step === 'ai-analysis-prompt' && (
+        <Box flexDirection="column" marginTop={1}>
+          <ErrorLine text="Build failed." />
+          <Newline />
+          <Text>We can analyze the build log with Capgo AI (Kimi K2.5) and suggest a fix.</Text>
+          <Newline />
+          <Select
+            options={[
+              { label: '🤖  Debug with AI', value: 'debug' },
+              { label: '⏭   Skip', value: 'skip' },
+            ]}
+            onChange={async (value) => {
+              if (value === 'debug') {
+                setStep('ai-analysis-running')
+              }
+              else {
+                if (aiJobId) {
+                  await trackAiAnalysisChoice({
+                    apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+                    orgId: resolvedOrgId ?? '',
+                    appId,
+                    platform: 'android',
+                    jobId: aiJobId,
+                    choice: 'skip',
+                    triggeredBy: 'onboarding',
+                  }).catch(() => { /* telemetry never breaks the wizard */ })
+                }
+                setStep('build-complete')
+              }
+            }}
+          />
+        </Box>
+      )}
+
+      {/* AI debug — spinner while the edge function is running */}
+      {step === 'ai-analysis-running' && (
+        <Box flexDirection="column" marginTop={1}>
+          <SpinnerLine text="Analyzing build log with Capgo AI (Kimi K2.5)..." />
+        </Box>
+      )}
+
+      {/* AI debug — render the diagnosis (or fallback message), then exit */}
+      {step === 'ai-analysis-result' && (
+        <Box flexDirection="column" marginTop={1}>
+          <Text bold color="cyan">AI analysis</Text>
+          <Newline />
+          {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+          {aiResultMessage && <Text>{aiResultMessage}</Text>}
+          <Newline />
+          <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
+          <Newline />
+          <Select
+            options={[
+              { label: '✔  Continue', value: 'continue' },
+            ]}
+            onChange={() => {
+              setStep('build-complete')
+            }}
+          />
+        </Box>
+      )}
+
       {step === 'error' && error && retryStep && (
         <Box flexDirection="column" marginTop={1}>
           <ErrorLine text={error} />
diff --git a/cli/src/build/onboarding/types.ts b/cli/src/build/onboarding/types.ts
index ae61aa9b33..36f13ef9ba 100644
--- a/cli/src/build/onboarding/types.ts
+++ b/cli/src/build/onboarding/types.ts
@@ -45,6 +45,10 @@ export type OnboardingStep
     | 'ci-secrets-failed'
     | 'ask-build'
     | 'requesting-build'
+    // AI debug — only entered when the build fails and logs were captured
+    | 'ai-analysis-prompt'
+    | 'ai-analysis-running'
+    | 'ai-analysis-result'
     | 'build-complete'
     | 'no-platform'
     | 'error'
@@ -164,6 +168,9 @@ export const STEP_PROGRESS: Record<OnboardingStep, number> = {
   'ci-secrets-failed': 84,
   'ask-build': 85,
   'requesting-build': 90,
+  'ai-analysis-prompt': 92,
+  'ai-analysis-running': 95,
+  'ai-analysis-result': 98,
   'build-complete': 100,
   'no-platform': 0,
   'error': 0,
@@ -224,6 +231,10 @@ export function getPhaseLabel(step: OnboardingStep): string {
     case 'ask-build':
     case 'requesting-build':
       return 'Step 4 of 4 · Save & Build'
+    case 'ai-analysis-prompt':
+    case 'ai-analysis-running':
+    case 'ai-analysis-result':
+      return 'AI debug'
     case 'build-complete':
       return 'Complete'
     case 'no-platform':
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 7435e3a98d..eb96de24ea 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -19,6 +19,9 @@ import { writeOnboardingSupportBundle } from '../../../onboarding-support.js'
 import { formatRunnerCommand, splitRunnerCommand } from '../../../runner-command.js'
 import { createSupabaseClient, findSavedKeySilent, getOrganizationId, getPMAndCommand } from '../../../utils.js'
 import { loadSavedCredentials, updateSavedCredentials } from '../../credentials.js'
+import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../ai/analyze.js'
+import { renderMarkdown } from '../../../ai/render-markdown.js'
+import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../request.js'
 import { CertificateLimitError, createCertificate, createProfile, deleteProfile, DuplicateProfileError, ensureBundleId, findCertIdBySha1, generateJwt, listProfilesForCert, revokeCertificate, verifyApiKey } from '../apple-api.js'
 import { createP12, DEFAULT_P12_PASSWORD, generateCsr } from '../csr.js'
@@ -261,6 +264,13 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
   const [buildUrl, setBuildUrl] = useState('')
   const [buildOutput, setBuildOutput] = useState<string[]>([])
   const [supportBundlePath, setSupportBundlePath] = useState<string | null>(null)
+  // ── AI-analysis sub-flow (entered only when the build fails and logs were
+  // captured). `aiJobId` is set when entering 'ai-analysis-prompt'; the running
+  // step reads it to call runCapgoAiAnalysis; the result step renders one of
+  // these two state strings depending on the PostAnalyzeResult kind.
+  const [aiJobId, setAiJobId] = useState<string | null>(null)
+  const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
+  const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -1237,6 +1247,11 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           const result = await requestBuildInternal(appId, {
             platform: 'ios',
             apikey: capgoKey,
+            // The Ink TUI owns the terminal — @clack/prompts inside
+            // requestBuildInternal would corrupt rendering. Caller-handled mode
+            // surfaces the captured log path via result.aiAnalysis and lets us
+            // render the AI flow with Ink-native components.
+            aiAnalysisMode: 'caller-handled',
           }, true, buildLogger) // silent=true, use our logger
           if (cancelled)
             return
@@ -1254,6 +1269,14 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           }
           else {
             setBuildOutput(prev => [...prev, `⚠ ${result.error || 'unknown error'}`])
+            // If logs were captured we can offer AI-assisted diagnosis. The
+            // captured log file stays on disk until the user views the result
+            // (or skips); 'ai-analysis-result' calls releaseCapturedLogs on exit.
+            if (result.aiAnalysis?.ready && result.aiAnalysis.jobId) {
+              setAiJobId(result.aiAnalysis.jobId)
+              setStep('ai-analysis-prompt')
+              return
+            }
           }
           setStep('build-complete')
         }
@@ -1268,8 +1291,86 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
       })()
     }
 
+    // AI analysis — entered only when requestBuildInternal returned with
+    // aiAnalysis.ready=true. The captured log file is on disk; we call the
+    // edge function, then transition to 'ai-analysis-result' which renders the
+    // diagnosis (or a friendly fallback message) and waits for Enter.
+    if (step === 'ai-analysis-running' && aiJobId) {
+      ;(async () => {
+        // Fire the Choice telemetry here (not in 'ai-analysis-prompt'): we only
+        // know the user picked "Debug with AI" because we landed in `running`.
+        await trackAiAnalysisChoice({
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          orgId: resolvedOrgId ?? '',
+          appId,
+          platform: 'ios',
+          jobId: aiJobId,
+          choice: 'capgo_ai',
+          triggeredBy: 'onboarding',
+        }).catch(() => { /* telemetry never breaks the wizard */ })
+
+        const result = await runCapgoAiAnalysis({
+          apiHost: 'https://api.capgo.app',
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          jobId: aiJobId,
+          appId,
+        })
+
+        if (cancelled)
+          return
+
+        const resultTag: 'success' | 'already_analyzed' | 'too_big' | 'error'
+          = result.kind === 'ok'
+            ? 'success'
+            : result.kind === 'already_analyzed'
+              ? 'already_analyzed'
+              : result.kind === 'too_big'
+                ? 'too_big'
+                : 'error'
+
+        await trackAiAnalysisResult({
+          apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+          orgId: resolvedOrgId ?? '',
+          appId,
+          platform: 'ios',
+          jobId: aiJobId,
+          result: resultTag,
+          errorStatus: result.kind === 'error' ? result.status : undefined,
+        }).catch(() => { /* telemetry never breaks the wizard */ })
+
+        if (result.kind === 'ok') {
+          // Render markdown to ANSI escapes; Ink <Text> passes them through.
+          // Fall back to raw text if a future Ink version stops doing so.
+          setAiAnalysisText(renderMarkdown(result.analysis, true))
+          setAiResultMessage(null)
+        }
+        else if (result.kind === 'already_analyzed') {
+          setAiAnalysisText(null)
+          setAiResultMessage('AI analysis was already requested for this build (only one per job).')
+        }
+        else if (result.kind === 'too_big') {
+          setAiAnalysisText(null)
+          setAiResultMessage('Build log is too large for Capgo AI (>10 MB). Try a local AI tool with the captured log.')
+        }
+        else {
+          setAiAnalysisText(null)
+          const detail = [
+            result.status ? `(status ${result.status})` : null,
+            result.message,
+          ].filter(Boolean).join(' ')
+          setAiResultMessage(`AI analysis failed${detail ? `: ${detail}` : ''}.`)
+        }
+        setStep('ai-analysis-result')
+      })()
+    }
+
     if (step === 'build-complete') {
       setBuildOutput([])
+      // Best-effort cleanup of any leftover captured log file. Safe to call
+      // even if we never entered the AI flow (operates only on jobs we know).
+      if (aiJobId) {
+        void releaseCapturedLogs(aiJobId).catch(() => { /* best-effort */ })
+      }
       // Exit immediately after rendering the final screen
       const timer = setTimeout(() => {
         if (!cancelled)
@@ -1290,9 +1391,9 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build'
-  const showHeader = step !== 'requesting-build'
-  const showLog = step !== 'requesting-build' && step !== 'build-complete'
+  const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result'
+  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result'
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result'
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null
@@ -2431,6 +2532,69 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
         )
       })()}
 
+      {/* AI debug — ask the user whether to send the captured log */}
+      {step === 'ai-analysis-prompt' && (
+        <Box flexDirection="column" marginTop={1}>
+          <ErrorLine text="Build failed." />
+          <Newline />
+          <Text>We can analyze the build log with Capgo AI (Kimi K2.5) and suggest a fix.</Text>
+          <Newline />
+          <Select
+            options={[
+              { label: '🤖  Debug with AI', value: 'debug' },
+              { label: '⏭   Skip', value: 'skip' },
+            ]}
+            onChange={async (value) => {
+              if (value === 'debug') {
+                setStep('ai-analysis-running')
+              }
+              else {
+                if (aiJobId) {
+                  await trackAiAnalysisChoice({
+                    apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+                    orgId: resolvedOrgId ?? '',
+                    appId,
+                    platform: 'ios',
+                    jobId: aiJobId,
+                    choice: 'skip',
+                    triggeredBy: 'onboarding',
+                  }).catch(() => { /* telemetry never breaks the wizard */ })
+                }
+                setStep('build-complete')
+              }
+            }}
+          />
+        </Box>
+      )}
+
+      {/* AI debug — spinner while the edge function is running */}
+      {step === 'ai-analysis-running' && (
+        <Box flexDirection="column" marginTop={1}>
+          <SpinnerLine text="Analyzing build log with Capgo AI (Kimi K2.5)..." />
+        </Box>
+      )}
+
+      {/* AI debug — render the diagnosis (or fallback message), then exit */}
+      {step === 'ai-analysis-result' && (
+        <Box flexDirection="column" marginTop={1}>
+          <Text bold color="cyan">AI analysis</Text>
+          <Newline />
+          {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+          {aiResultMessage && <Text>{aiResultMessage}</Text>}
+          <Newline />
+          <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
+          <Newline />
+          <Select
+            options={[
+              { label: '✔  Continue', value: 'continue' },
+            ]}
+            onChange={() => {
+              setStep('build-complete')
+            }}
+          />
+        </Box>
+      )}
+
       {/* Error with retry */}
       {step === 'error' && error && (
         <Box flexDirection="column" marginTop={1}>
diff --git a/cli/src/build/request.ts b/cli/src/build/request.ts
index f975c72502..cd885e0859 100644
--- a/cli/src/build/request.ts
+++ b/cli/src/build/request.ts
@@ -1631,9 +1631,17 @@ export async function requestBuildInternal(appId: string, options: BuildRequestO
     // --ai-analytics is set in CI (so auto-upload has logs to send). Without the
     // flag-OR, the CI auto_upload branch from decideAnalyzeBehavior would never
     // have a log file to read.
-    const captureEnabled = shouldCaptureLogs() || options.aiAnalytics === true
+    const aiAnalysisMode: 'auto-prompt' | 'caller-handled' | 'skip' = options.aiAnalysisMode ?? 'auto-prompt'
+    // Capture when interactive, when the CI flag is set, OR when the caller asked
+    // to drive the AI flow themselves (e.g. Ink onboarding) so the captured log
+    // is available for runCapgoAiAnalysis.
+    const captureEnabled = (shouldCaptureLogs() || options.aiAnalytics === true || aiAnalysisMode === 'caller-handled')
+      && aiAnalysisMode !== 'skip'
     let capturedJobId: string | null = null
     let keepPromptFile = false // mutable so local-AI flow can set it true
+    // Populated only in caller-handled mode on a failed build. Returned to the
+    // caller so it can render its own AI prompt UI and later release the log.
+    let aiAnalysisInfo: BuildRequestResult['aiAnalysis']
 
     if (captureEnabled && buildRequest.job_id) {
       capturedJobId = buildRequest.job_id
@@ -1977,8 +1985,30 @@ export async function requestBuildInternal(appId: string, options: BuildRequestO
         }
       }
 
-      // On failure, offer the AI analysis flow (interactive menu or auto-upload).
-      if (finalStatus === 'failed' && captureEnabled && capturedJobId) {
+      // On failure, offer the AI analysis flow.
+      //
+      // - 'skip'           → no-op (caller wants nothing to do with AI here).
+      // - 'caller-handled' → leave the captured log on disk and surface it via
+      //                      `result.aiAnalysis` so the caller (e.g. the Ink
+      //                      onboarding wizard) can run `runCapgoAiAnalysis`
+      //                      and render its own UI without clack corrupting
+      //                      its terminal renderer.
+      // - 'auto-prompt'    → existing interactive / CI matrix via
+      //                      decideAnalyzeBehavior + clack prompts.
+      if (finalStatus === 'failed' && captureEnabled && capturedJobId && aiAnalysisMode === 'caller-handled') {
+        // Preserve the captured log until the caller calls
+        // releaseCapturedLogs(jobId) explicitly. Without this, the cleanup
+        // handlers registered above would remove it on process exit before
+        // the caller had a chance to read it.
+        keepPromptFile = true
+        const logsPath = `${process.env.CAPGO_AI_LOG_BASE_DIR || '/tmp/capgo-builds'}/${capturedJobId}.log`
+        aiAnalysisInfo = {
+          jobId: capturedJobId,
+          capturedLogPath: logsPath,
+          ready: true,
+        }
+      }
+      else if (finalStatus === 'failed' && captureEnabled && capturedJobId && aiAnalysisMode === 'auto-prompt') {
         const behavior = decideAnalyzeBehavior({
           isTTY: process.stdout.isTTY === true,
           aiAnalyticsFlag: options.aiAnalytics === true,
@@ -2180,6 +2210,7 @@ export async function requestBuildInternal(appId: string, options: BuildRequestO
         jobId: buildRequest.job_id,
         uploadUrl: buildRequest.upload_url,
         status: finalStatus || startResult.status || buildRequest.status,
+        aiAnalysis: aiAnalysisInfo,
       }
     }
     finally {
diff --git a/cli/src/schemas/build.ts b/cli/src/schemas/build.ts
index 2d7d855f7a..4cb7cce534 100644
--- a/cli/src/schemas/build.ts
+++ b/cli/src/schemas/build.ts
@@ -66,6 +66,16 @@ export const buildRequestOptionsSchema = optionsBaseSchema.extend({
   playstoreUpload: z.boolean().optional(),
   verbose: z.boolean().optional(),
   aiAnalytics: z.boolean().optional(),
+  // Controls the on-failure AI-analysis flow inside requestBuildInternal:
+  //   - 'auto-prompt' (default) — current behavior: clack-driven menu when
+  //     interactive, decideAnalyzeBehavior matrix in CI.
+  //   - 'caller-handled'        — skip the clack block entirely and surface
+  //     `aiAnalysis` on the result so the caller (e.g. the Ink onboarding
+  //     wizard) drives the UX. The captured log file is preserved so the
+  //     caller can read it before calling `releaseCapturedLogs`.
+  //   - 'skip'                  — skip the AI block entirely; normal cleanup
+  //     runs (log file deleted on exit).
+  aiAnalysisMode: z.enum(['auto-prompt', 'caller-handled', 'skip']).optional(),
 })
 
 export type BuildRequestOptions = z.infer<typeof buildRequestOptionsSchema>
@@ -89,6 +99,16 @@ export const buildRequestResultSchema = z.object({
   uploadUrl: z.string().optional(),
   status: z.string().optional(),
   error: z.string().optional(),
+  // Populated only when `aiAnalysisMode === 'caller-handled'` AND the build
+  // failed AND log capture was active. `ready: true` means the captured log
+  // file is on disk at `capturedLogPath` and a caller can run `runCapgoAiAnalysis`
+  // immediately. Callers must invoke `releaseCapturedLogs(jobId)` when they're
+  // done viewing the analysis (or chose to skip) so the file gets cleaned up.
+  aiAnalysis: z.object({
+    jobId: z.string(),
+    capturedLogPath: z.string(),
+    ready: z.boolean(),
+  }).optional(),
 })
 
 export type BuildRequestResult = z.infer<typeof buildRequestResultSchema>
diff --git a/cli/test/test-ai-onboarding-mode.mjs b/cli/test/test-ai-onboarding-mode.mjs
new file mode 100644
index 0000000000..f94e3ab460
--- /dev/null
+++ b/cli/test/test-ai-onboarding-mode.mjs
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// Tests for the caller-handled AI flow used by the Ink onboarding wizard:
+//   - runCapgoAiAnalysis (reads /tmp log, delegates to postAnalyzeRequest)
+//   - releaseCapturedLogs (best-effort cleanup wrapper)
+// Plus a regression check that decideAnalyzeBehavior still returns the same
+// matrix when the new aiAnalysisMode lives elsewhere — direct CLI invocation
+// must not change behavior.
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  decideAnalyzeBehavior,
+  HARD_LOG_SIZE_LIMIT,
+  releaseCapturedLogs,
+  runCapgoAiAnalysis,
+} from '../src/ai/analyze.ts'
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  return Promise.resolve()
+    .then(() => fn())
+    .then(() => { console.log(`✅ ${name}`); passed++ })
+    .catch((err) => { console.error(`❌ ${name}\n   ${err.message}`); failed++ })
+}
+
+const TEST_DIR = join(tmpdir(), `capgo-ai-onboarding-test-${Date.now()}`)
+await mkdir(TEST_DIR, { recursive: true })
+process.env.CAPGO_AI_LOG_BASE_DIR = TEST_DIR
+
+// ---- decideAnalyzeBehavior unchanged ----
+await test('decideAnalyzeBehavior matrix unchanged: interactive+flag → show_menu', () => {
+  if (decideAnalyzeBehavior({ isTTY: true, aiAnalyticsFlag: true }) !== 'show_menu')
+    throw new Error('regression')
+})
+await test('decideAnalyzeBehavior matrix unchanged: interactive only → ask_then_menu', () => {
+  if (decideAnalyzeBehavior({ isTTY: true, aiAnalyticsFlag: false }) !== 'ask_then_menu')
+    throw new Error('regression')
+})
+await test('decideAnalyzeBehavior matrix unchanged: CI+flag → auto_upload', () => {
+  if (decideAnalyzeBehavior({ isTTY: false, aiAnalyticsFlag: true }) !== 'auto_upload')
+    throw new Error('regression')
+})
+await test('decideAnalyzeBehavior matrix unchanged: CI alone → skip', () => {
+  if (decideAnalyzeBehavior({ isTTY: false, aiAnalyticsFlag: false }) !== 'skip')
+    throw new Error('regression')
+})
+
+// ---- runCapgoAiAnalysis ----
+await test('runCapgoAiAnalysis reads the captured log and posts to /build/ai_analyze', async () => {
+  const jobId = `job-ok-${Date.now()}`
+  const logPath = join(TEST_DIR, `${jobId}.log`)
+  await writeFile(logPath, 'pretend xcode log line 1\npretend xcode log line 2\n')
+
+  let captured = null
+  const origFetch = globalThis.fetch
+  globalThis.fetch = async (url, init) => {
+    captured = { url, init }
+    return new Response(JSON.stringify({ analysis: '### Likely cause\nsigning' }), {
+      status: 200, headers: { 'content-type': 'application/json' },
+    })
+  }
+  try {
+    const result = await runCapgoAiAnalysis({
+      apiHost: 'https://api.test',
+      apikey: 'key',
+      jobId,
+      appId: 'com.test.app',
+    })
+    if (result.kind !== 'ok')
+      throw new Error(`expected ok, got ${result.kind}`)
+    if (!result.analysis.includes('signing'))
+      throw new Error('analysis text not propagated')
+    if (!captured)
+      throw new Error('fetch was not called')
+    if (!captured.url.endsWith('/build/ai_analyze'))
+      throw new Error(`unexpected url ${captured.url}`)
+    const body = JSON.parse(captured.init.body)
+    if (body.jobId !== jobId)
+      throw new Error('jobId not forwarded')
+    if (!body.logs.includes('pretend xcode'))
+      throw new Error('log content not forwarded')
+  }
+  finally {
+    globalThis.fetch = origFetch
+  }
+})
+
+await test('runCapgoAiAnalysis returns too_big when log exceeds HARD_LOG_SIZE_LIMIT', async () => {
+  const jobId = `job-big-${Date.now()}`
+  const logPath = join(TEST_DIR, `${jobId}.log`)
+  // Write 1 byte over the limit. Using a Buffer keeps the test fast.
+  const buf = Buffer.alloc(HARD_LOG_SIZE_LIMIT + 1, 'x')
+  await writeFile(logPath, buf)
+
+  let fetchCalled = false
+  const origFetch = globalThis.fetch
+  globalThis.fetch = async () => {
+    fetchCalled = true
+    return new Response('', { status: 500 })
+  }
+  try {
+    const result = await runCapgoAiAnalysis({
+      apiHost: 'https://api.test',
+      apikey: 'key',
+      jobId,
+      appId: 'com.test.app',
+    })
+    if (result.kind !== 'too_big')
+      throw new Error(`expected too_big, got ${result.kind}`)
+    if (fetchCalled)
+      throw new Error('fetch should not be called for too-big logs')
+  }
+  finally {
+    globalThis.fetch = origFetch
+  }
+})
+
+await test('runCapgoAiAnalysis returns error when the captured log is missing', async () => {
+  let fetchCalled = false
+  const origFetch = globalThis.fetch
+  globalThis.fetch = async () => {
+    fetchCalled = true
+    return new Response('', { status: 500 })
+  }
+  try {
+    const result = await runCapgoAiAnalysis({
+      apiHost: 'https://api.test',
+      apikey: 'key',
+      jobId: `job-missing-${Date.now()}`,
+      appId: 'com.test.app',
+    })
+    if (result.kind !== 'error')
+      throw new Error(`expected error, got ${result.kind}`)
+    if (fetchCalled)
+      throw new Error('fetch should not be called when log file is missing')
+  }
+  finally {
+    globalThis.fetch = origFetch
+  }
+})
+
+// ---- releaseCapturedLogs ----
+await test('releaseCapturedLogs deletes the captured log file', async () => {
+  const jobId = `job-release-${Date.now()}`
+  const logPath = join(TEST_DIR, `${jobId}.log`)
+  await writeFile(logPath, 'some content')
+  if (!existsSync(logPath))
+    throw new Error('precondition: log file should exist')
+
+  await releaseCapturedLogs(jobId)
+
+  if (existsSync(logPath))
+    throw new Error('log file should be deleted after releaseCapturedLogs')
+})
+
+await test('releaseCapturedLogs is best-effort when nothing exists', async () => {
+  // Should not throw on a missing file.
+  await releaseCapturedLogs(`job-noop-${Date.now()}`)
+})
+
+console.log(`\n${passed} passed, ${failed} failed`)
+if (failed > 0)
+  process.exit(1)
diff --git a/cli/tsconfig.json b/cli/tsconfig.json
index 308023f0cb..af46250a33 100644
--- a/cli/tsconfig.json
+++ b/cli/tsconfig.json
@@ -4,6 +4,7 @@
     "lib": [
       "es2023"
     ],
+    "ignoreDeprecations": "6.0",
     "baseUrl": "src",
     "module": "ESNext",
     "moduleResolution": "Bundler",

From ed75fd0b43b642b026e4829154300c010cf6c983 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 13:50:35 +0200
Subject: [PATCH 02/14] feat(cli): add retry-after-AI-fix loop to onboarding
 (max 2 retries)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After the AI analysis renders, the user often needs to apply the suggested
fix in their editor and re-run the build. Previously the only option from
'ai-analysis-result' was "Continue" -> exit, which forced the user to
re-launch the wizard (and re-run credential discovery) just to re-attempt
the build.

This change lets the user retry directly from inside the wizard:

- 'ai-analysis-result' now shows two options when retries remain:
    🔄  I fixed it, retry build (N retries left)
    ⏭   Continue (skip retry)
- On retry: release the captured log for the current jobId, reset AI state
  (aiJobId / aiAnalysisText / aiResultMessage), increment aiRetryCount,
  and transition back to 'requesting-build'. The existing useEffect for
  that step re-runs `requestBuildInternal` and (on failure) routes back
  through the AI flow with the new jobId.
- After MAX_AI_RETRIES (= 2) the retry option is removed and a single
  "Continue" is shown. A dim note explains how many retries were used.
- Total wizard-internal attempts capped at 3: initial + 2 retries.

PostHog: extend `AiAnalysisChoice` with 'retry' (additive). The Choice
event fires per-retry-attempt, carrying the current jobId — so the
funnel can measure "AI suggestion was actionable enough to merit a
retry" and "retry led to a successful subsequent build" as separate
metrics by joining on app/job.

Mirrored to both iOS (cli/src/build/onboarding/ui/app.tsx) and Android
(cli/src/build/onboarding/android/ui/app.tsx) wizards.

Privacy: as before, only closed-enum choice values cross the telemetry
boundary; the AI diagnosis text is never observed.
---
 cli/src/ai/telemetry.ts                     |  2 +-
 cli/src/build/onboarding/android/ui/app.tsx | 88 ++++++++++++++-----
 cli/src/build/onboarding/ui/app.tsx         | 97 ++++++++++++++++-----
 3 files changed, 146 insertions(+), 41 deletions(-)

diff --git a/cli/src/ai/telemetry.ts b/cli/src/ai/telemetry.ts
index 2405e08513..8f34c154cc 100644
--- a/cli/src/ai/telemetry.ts
+++ b/cli/src/ai/telemetry.ts
@@ -1,6 +1,6 @@
 import { sendEvent } from '../utils.js'
 
-export type AiAnalysisChoice = 'capgo_ai' | 'local_ai' | 'skip' | 'auto_upload'
+export type AiAnalysisChoice = 'capgo_ai' | 'local_ai' | 'skip' | 'auto_upload' | 'retry'
 export type AiAnalysisTriggeredBy = 'menu' | 'ci_flag' | 'onboarding'
 export type AiAnalysisResult = 'success' | 'already_analyzed' | 'too_big' | 'error'
 
diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index d09f7f7404..f5b0411fcf 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -29,6 +29,12 @@ import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../../ai/analyze.
 import { renderMarkdown } from '../../../../ai/render-markdown.js'
 import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../../request.js'
+
+// Upper bound on "I fixed it, retry build" attempts after an AI diagnosis.
+// Three total attempts (initial + two retries) caps the AI cost when a model
+// suggestion doesn't actually fix the failure mode while still giving the user
+// a couple of in-wizard chances to iterate.
+const MAX_AI_RETRIES = 2
 import type { CiSecretEntry, CiSecretSetupAdvice, CiSecretTarget } from '../../ci-secrets.js'
 import { createCiSecretEntries, detectCiSecretTargets, getCiSecretTargetLabel, listExistingCiSecretKeys, uploadCiSecrets } from '../../ci-secrets.js'
 import { mapAndroidOnboardingError, mapSaValidationKindToCategory } from '../../error-categories.js'
@@ -385,6 +391,7 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
   const [aiJobId, setAiJobId] = useState<string | null>(null)
   const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
   const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
+  const [aiRetryCount, setAiRetryCount] = useState(0)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -2723,26 +2730,67 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
         </Box>
       )}
 
-      {/* AI debug — render the diagnosis (or fallback message), then exit */}
-      {step === 'ai-analysis-result' && (
-        <Box flexDirection="column" marginTop={1}>
-          <Text bold color="cyan">AI analysis</Text>
-          <Newline />
-          {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
-          {aiResultMessage && <Text>{aiResultMessage}</Text>}
-          <Newline />
-          <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
-          <Newline />
-          <Select
-            options={[
-              { label: '✔  Continue', value: 'continue' },
-            ]}
-            onChange={() => {
-              setStep('build-complete')
-            }}
-          />
-        </Box>
-      )}
+      {/* AI debug — render the diagnosis (or fallback message), then offer
+          retry-or-skip. Retry transitions back to 'requesting-build' so the
+          user can rebuild after applying the AI's fix in another terminal,
+          without re-running the credential wizard. Capped at MAX_AI_RETRIES. */}
+      {step === 'ai-analysis-result' && (() => {
+        const retriesLeft = MAX_AI_RETRIES - aiRetryCount
+        const canRetry = retriesLeft > 0
+        const retryLabel = retriesLeft === 1
+          ? '🔄  I fixed it, retry build (last retry)'
+          : `🔄  I fixed it, retry build (${retriesLeft} retries left)`
+        return (
+          <Box flexDirection="column" marginTop={1}>
+            <Text bold color="cyan">AI analysis</Text>
+            <Newline />
+            {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+            {aiResultMessage && <Text>{aiResultMessage}</Text>}
+            <Newline />
+            <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
+            <Newline />
+            {!canRetry && (
+              <>
+                <Text dimColor>You've used all {MAX_AI_RETRIES} retries. Exit and re-run the wizard if you need another attempt.</Text>
+                <Newline />
+              </>
+            )}
+            <Select
+              options={canRetry
+                ? [
+                    { label: retryLabel, value: 'retry' },
+                    { label: '⏭   Continue (skip retry)', value: 'skip' },
+                  ]
+                : [
+                    { label: '✔  Continue', value: 'continue' },
+                  ]}
+              onChange={async (value) => {
+                if (value === 'retry') {
+                  if (aiJobId) {
+                    await trackAiAnalysisChoice({
+                      apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+                      orgId: resolvedOrgId ?? '',
+                      appId,
+                      platform: 'android',
+                      jobId: aiJobId,
+                      choice: 'retry',
+                      triggeredBy: 'onboarding',
+                    }).catch(() => { /* telemetry never breaks the wizard */ })
+                    void releaseCapturedLogs(aiJobId).catch(() => { /* best-effort */ })
+                  }
+                  setAiJobId(null)
+                  setAiAnalysisText(null)
+                  setAiResultMessage(null)
+                  setAiRetryCount(prev => prev + 1)
+                  setStep('requesting-build')
+                  return
+                }
+                setStep('build-complete')
+              }}
+            />
+          </Box>
+        )
+      })()}
 
       {step === 'error' && error && retryStep && (
         <Box flexDirection="column" marginTop={1}>
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index eb96de24ea..b6830f8655 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -23,6 +23,12 @@ import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../ai/analyze.js'
 import { renderMarkdown } from '../../../ai/render-markdown.js'
 import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../request.js'
+
+// Upper bound on "I fixed it, retry build" attempts after an AI diagnosis.
+// Three total attempts (initial + two retries) caps the AI cost when a model
+// suggestion doesn't actually fix the failure mode while still giving the user
+// a couple of in-wizard chances to iterate.
+const MAX_AI_RETRIES = 2
 import { CertificateLimitError, createCertificate, createProfile, deleteProfile, DuplicateProfileError, ensureBundleId, findCertIdBySha1, generateJwt, listProfilesForCert, revokeCertificate, verifyApiKey } from '../apple-api.js'
 import { createP12, DEFAULT_P12_PASSWORD, generateCsr } from '../csr.js'
 import { mapIosOnboardingError } from '../error-categories.js'
@@ -268,9 +274,12 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
   // captured). `aiJobId` is set when entering 'ai-analysis-prompt'; the running
   // step reads it to call runCapgoAiAnalysis; the result step renders one of
   // these two state strings depending on the PostAnalyzeResult kind.
+  // `aiRetryCount` tracks how many "I fixed it, retry" attempts the user has
+  // used so we can cap them at MAX_AI_RETRIES.
   const [aiJobId, setAiJobId] = useState<string | null>(null)
   const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
   const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
+  const [aiRetryCount, setAiRetryCount] = useState(0)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -2574,26 +2583,74 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
         </Box>
       )}
 
-      {/* AI debug — render the diagnosis (or fallback message), then exit */}
-      {step === 'ai-analysis-result' && (
-        <Box flexDirection="column" marginTop={1}>
-          <Text bold color="cyan">AI analysis</Text>
-          <Newline />
-          {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
-          {aiResultMessage && <Text>{aiResultMessage}</Text>}
-          <Newline />
-          <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
-          <Newline />
-          <Select
-            options={[
-              { label: '✔  Continue', value: 'continue' },
-            ]}
-            onChange={() => {
-              setStep('build-complete')
-            }}
-          />
-        </Box>
-      )}
+      {/* AI debug — render the diagnosis (or fallback message), then offer
+          retry-or-skip. Retry transitions back to 'requesting-build' so the
+          user can rebuild after applying the AI's fix in another terminal,
+          without re-running the credential wizard. Capped at MAX_AI_RETRIES. */}
+      {step === 'ai-analysis-result' && (() => {
+        const retriesLeft = MAX_AI_RETRIES - aiRetryCount
+        const canRetry = retriesLeft > 0
+        const retryLabel = retriesLeft === 1
+          ? '🔄  I fixed it, retry build (last retry)'
+          : `🔄  I fixed it, retry build (${retriesLeft} retries left)`
+        return (
+          <Box flexDirection="column" marginTop={1}>
+            <Text bold color="cyan">AI analysis</Text>
+            <Newline />
+            {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+            {aiResultMessage && <Text>{aiResultMessage}</Text>}
+            <Newline />
+            <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
+            <Newline />
+            {!canRetry && (
+              <>
+                <Text dimColor>You've used all {MAX_AI_RETRIES} retries. Exit and re-run the wizard if you need another attempt.</Text>
+                <Newline />
+              </>
+            )}
+            <Select
+              options={canRetry
+                ? [
+                    { label: retryLabel, value: 'retry' },
+                    { label: '⏭   Continue (skip retry)', value: 'skip' },
+                  ]
+                : [
+                    { label: '✔  Continue', value: 'continue' },
+                  ]}
+              onChange={async (value) => {
+                if (value === 'retry') {
+                  // Track the retry intent before we tear down the AI state so
+                  // the choice event carries the per-attempt context.
+                  if (aiJobId) {
+                    await trackAiAnalysisChoice({
+                      apikey: resolvedApiKeyRef.current ?? apikey ?? '',
+                      orgId: resolvedOrgId ?? '',
+                      appId,
+                      platform: 'ios',
+                      jobId: aiJobId,
+                      choice: 'retry',
+                      triggeredBy: 'onboarding',
+                    }).catch(() => { /* telemetry never breaks the wizard */ })
+                    // Free the captured log for the previous attempt; the next
+                    // attempt's `requestBuildInternal` will create a new file
+                    // tied to a new builder_job_id.
+                    void releaseCapturedLogs(aiJobId).catch(() => { /* best-effort */ })
+                  }
+                  // Reset AI state so the next failure starts clean.
+                  setAiJobId(null)
+                  setAiAnalysisText(null)
+                  setAiResultMessage(null)
+                  setAiRetryCount(prev => prev + 1)
+                  setStep('requesting-build')
+                  return
+                }
+                // 'skip' (with retries available) or 'continue' (none left).
+                setStep('build-complete')
+              }}
+            />
+          </Box>
+        )
+      })()}
 
       {/* Error with retry */}
       {step === 'error' && error && (

From 0dcaba9389a5d80379e1bc6b18cfc6a93dc546e5 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 15:17:34 +0200
Subject: [PATCH 03/14] feat(cli): route AI analysis through scrollable viewer
 when it overflows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

If the on-failure AI diagnosis is taller than the user's terminal viewport,
rendering it inline causes the earlier lines to scroll off the top before the
retry/skip picker appears — which we explicitly do not want in the onboarding
wizard. Earlier lines scrolled into the terminal history aren't the "active"
screen, so the user can't see both the diagnosis and the choices at the same
time and the wizard ends up in a confusing state.

This change adds a conservative fit estimator and routes overflowing analyses
through a new fullscreen scrollable viewer modeled on the existing
`FullscreenDiffViewer` from main.

### Fit estimator — `cli/src/build/onboarding/ai-fit.ts`

`isAiAnalysisTooTall(text, terminalRows, terminalCols)` estimates rendered
rows (per logical line × wrap factor, ignoring ANSI escapes for length) and
compares against `terminalRows - AI_RESULT_CHROME_ROWS` (default 20). The
20-row chrome reserve is deliberately generous: prefer a false-positive
scroll (one extra keystroke) over a false-negative inline render (lines
disappear off the top).

### Scrollable viewer — `cli/src/build/onboarding/ui/components.tsx`

`FullscreenAiViewer` mirrors the shape of `FullscreenDiffViewer` on main but
takes pre-rendered ANSI text lines instead of structured diff lines.
Keybindings: ↑/↓ or j/k (line), PgUp/PgDn or u/d/Space (page), g/G (top/
bottom), Esc/Enter (dismiss). Shows "Showing N-M of TOTAL lines" footer and a
status-aware exit hint.

### New step — `'ai-analysis-result-scroll'` (iOS + Android)

Added to both `OnboardingStep` and `AndroidOnboardingStep`, plus
`STEP_PROGRESS` and `getPhaseLabel`. The outer wizard Header / progress bar
/ log panel are hidden during this step so the viewer gets the full screen
(same pattern main uses for `view-workflow-diff`).

### Wizard wiring (both iOS and Android `ui/app.tsx`)

- New `aiViewedFull` state. The step useEffect for `ai-analysis-result`
  checks fit and transitions to `ai-analysis-result-scroll` when needed.
- The scroll step renders `<FullscreenAiViewer />`; on exit it sets
  `aiViewedFull=true` and returns to `ai-analysis-result`.
- The inline `ai-analysis-result` render now branches on `aiViewedFull`:
  if true, replaces the body dump with a compact "📖 Analysis already
  shown above (scroll your terminal back to re-read it)" marker so the
  retry/skip picker is always visible.
- Retry handler resets `aiViewedFull` so the next attempt re-evaluates
  fit against the new analysis text.

### Test coverage

`cli/test/test-ai-fit.mjs` (12 tests, all green):
- ANSI strip
- Empty / short / overflowing inputs
- Borderline conservative case
- Single very long wrapping line

Existing `test-ai-onboarding-mode`, `test-ai-analyze-flow`,
`test-ai-log-capture`, `test-ai-render-markdown` continue to pass — no
regression in the underlying flow.
---
 cli/package.json                            |   5 +-
 cli/src/build/onboarding/ai-fit.ts          |  74 +++++++++++++
 cli/src/build/onboarding/android/types.ts   |   3 +
 cli/src/build/onboarding/android/ui/app.tsx |  43 ++++++-
 cli/src/build/onboarding/types.ts           |   3 +
 cli/src/build/onboarding/ui/app.tsx         |  62 ++++++++++-
 cli/src/build/onboarding/ui/components.tsx  |  95 +++++++++++++++-
 cli/test/test-ai-fit.mjs                    | 117 ++++++++++++++++++++
 8 files changed, 388 insertions(+), 14 deletions(-)
 create mode 100644 cli/src/build/onboarding/ai-fit.ts
 create mode 100644 cli/test/test-ai-fit.mjs

diff --git a/cli/package.json b/cli/package.json
index e1ea65c5b7..8660d21de7 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -94,12 +94,13 @@
     "test:macos-signing": "bun test/test-macos-signing.mjs",
     "test:apple-api-import-helpers": "bun test/test-apple-api-import-helpers.mjs",
     "test:manifest-path-encoding": "bun test/test-manifest-path-encoding.mjs",
-    "test": "bun run build && 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: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: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-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-render-markdown && bun run test:ai-onboarding-mode",
+    "test": "bun run build && 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: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: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-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-render-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit",
     "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",
     "test:ai-render-markdown": "bun test/test-ai-render-markdown.mjs",
-    "test:ai-onboarding-mode": "bun test/test-ai-onboarding-mode.mjs"
+    "test:ai-onboarding-mode": "bun test/test-ai-onboarding-mode.mjs",
+    "test:ai-fit": "bun test/test-ai-fit.mjs"
   },
   "dependencies": {
     "@inkjs/ui": "^2.0.0",
diff --git a/cli/src/build/onboarding/ai-fit.ts b/cli/src/build/onboarding/ai-fit.ts
new file mode 100644
index 0000000000..26204440ac
--- /dev/null
+++ b/cli/src/build/onboarding/ai-fit.ts
@@ -0,0 +1,74 @@
+/**
+ * Fit estimation for the AI analysis result step in the onboarding TUI.
+ *
+ * The on-failure AI flow can return a multi-screen markdown diagnosis. If
+ * that text doesn't fit in the user's current terminal viewport we MUST
+ * route it through the scrollable `FullscreenAiViewer` — otherwise the
+ * earlier lines scroll out of view and the onboarding wizard ends up in
+ * an unreadable state.
+ *
+ * The estimator deliberately errs on the side of "doesn't fit": a
+ * false-positive scroll is fine (just one more keystroke for the user),
+ * but a false-negative inline render is bad UX (text disappears off the
+ * top of the screen).
+ */
+
+// Conservative chrome reserve: outer Header + AI title + safety warning +
+// the retry/skip Select with up to 2 options + blank lines/margins.
+// Sized for the worst case so a small terminal still feels safe.
+export const AI_RESULT_CHROME_ROWS = 20
+
+// ESC sequence used by `renderMarkdown` and `kleur`/`chalk` to color text.
+// The escape byte (0x1B) lives in a private-use region so the regex below
+// is exact even for input that includes literal '[' or 'm' bytes.
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1B\[[0-9;]*m/g
+
+/** Strip ANSI SGR escape codes so length matches what the user actually sees. */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_RE, '')
+}
+
+/**
+ * Estimate how many terminal rows a multi-line, possibly ANSI-styled string
+ * will occupy when rendered by Ink at the given column width.
+ *
+ * Each logical line (split on '\n') becomes `ceil(visibleLen / cols)` rows,
+ * with a floor of 1 to account for empty lines that still consume a row.
+ */
+export function estimateRenderedRows(text: string, terminalCols: number): number {
+  if (!text)
+    return 0
+  const cols = Math.max(1, Math.floor(terminalCols))
+  const lines = text.split('\n')
+  let total = 0
+  for (const line of lines) {
+    const visibleLen = stripAnsi(line).length
+    total += Math.max(1, Math.ceil(visibleLen / cols))
+  }
+  return total
+}
+
+/**
+ * Decide whether the AI analysis text should be routed through the
+ * scrollable fullscreen viewer. Conservative — prefers true (scroll) when
+ * the estimate is close to the available row budget.
+ *
+ * @param text         The AI analysis markdown (already rendered to ANSI).
+ * @param terminalRows Total terminal rows from `useStdout().stdout?.rows`.
+ * @param terminalCols Total terminal cols from `useStdout().stdout?.columns`.
+ * @param chromeRows   Reserved rows for the surrounding wizard chrome.
+ *                     Defaults to `AI_RESULT_CHROME_ROWS`.
+ */
+export function isAiAnalysisTooTall(
+  text: string,
+  terminalRows: number,
+  terminalCols: number,
+  chromeRows: number = AI_RESULT_CHROME_ROWS,
+): boolean {
+  if (!text)
+    return false
+  const availableRows = Math.max(1, terminalRows - chromeRows)
+  const estimated = estimateRenderedRows(text, terminalCols)
+  return estimated > availableRows
+}
diff --git a/cli/src/build/onboarding/android/types.ts b/cli/src/build/onboarding/android/types.ts
index 902ea20c36..30b02c0f4c 100644
--- a/cli/src/build/onboarding/android/types.ts
+++ b/cli/src/build/onboarding/android/types.ts
@@ -59,6 +59,7 @@ export type AndroidOnboardingStep
     | 'ai-analysis-prompt'
     | 'ai-analysis-running'
     | 'ai-analysis-result'
+    | 'ai-analysis-result-scroll'
     | 'build-complete'
     | 'error'
 
@@ -228,6 +229,7 @@ export const ANDROID_STEP_PROGRESS: Record<AndroidOnboardingStep, number> = {
   'requesting-build': 95,
   'ai-analysis-prompt': 96,
   'ai-analysis-running': 98,
+  'ai-analysis-result-scroll': 98,
   'ai-analysis-result': 99,
   'build-complete': 100,
   'error': 0,
@@ -289,6 +291,7 @@ export function getAndroidPhaseLabel(step: AndroidOnboardingStep): string {
     case 'ai-analysis-prompt':
     case 'ai-analysis-running':
     case 'ai-analysis-result':
+    case 'ai-analysis-result-scroll':
       return 'AI debug'
     case 'build-complete':
       return 'Complete'
diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index f5b0411fcf..1324d8250c 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -29,6 +29,7 @@ import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../../ai/analyze.
 import { renderMarkdown } from '../../../../ai/render-markdown.js'
 import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../../request.js'
+import { isAiAnalysisTooTall } from '../../ai-fit.js'
 
 // Upper bound on "I fixed it, retry build" attempts after an AI diagnosis.
 // Three total attempts (initial + two retries) caps the AI cost when a model
@@ -40,7 +41,7 @@ import { createCiSecretEntries, detectCiSecretTargets, getCiSecretTargetLabel, l
 import { mapAndroidOnboardingError, mapSaValidationKindToCategory } from '../../error-categories.js'
 import { canUseFilePicker, openKeystorePicker, openServiceAccountJsonPicker } from '../../file-picker.js'
 import { trackBuilderOnboardingStep } from '../../telemetry.js'
-import { Divider, ErrorLine, FilteredTextInput, Header, SpinnerLine, SuccessLine } from '../../ui/components.js'
+import { Divider, ErrorLine, FilteredTextInput, FullscreenAiViewer, Header, SpinnerLine, SuccessLine } from '../../ui/components.js'
 import { findAndroidApplicationIds } from '../gradle-parser.js'
 import { validateServiceAccountJson } from '../service-account-validation.js'
 import {
@@ -392,6 +393,8 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
   const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
   const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
   const [aiRetryCount, setAiRetryCount] = useState(0)
+  // See iOS sibling for full notes on aiViewedFull.
+  const [aiViewedFull, setAiViewedFull] = useState(false)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -402,6 +405,7 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const { stdout } = useStdout()
   const terminalRows = stdout?.rows ?? 24
+  const terminalCols = stdout?.columns ?? 80
 
   const addLog = useCallback((text: string, color = 'green') => {
     setLogLines(prev => [...prev, { text, color }])
@@ -1525,6 +1529,14 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
       })()
     }
 
+    // See iOS sibling: route through fullscreen scroll viewer when the
+    // analysis is taller than the available viewport.
+    if (step === 'ai-analysis-result' && aiAnalysisText && !aiViewedFull) {
+      if (isAiAnalysisTooTall(aiAnalysisText, terminalRows, terminalCols)) {
+        setStep('ai-analysis-result-scroll')
+      }
+    }
+
     if (step === 'build-complete') {
       setBuildOutput([])
       // Best-effort cleanup of any leftover captured log.
@@ -1555,9 +1567,10 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result'
-  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result'
-  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result'
+  const isAiResultScroll = step === 'ai-analysis-result-scroll'
+  const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result' && !isAiResultScroll
 
   return (
     <Box flexDirection="column" padding={1}>
@@ -2744,7 +2757,12 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           <Box flexDirection="column" marginTop={1}>
             <Text bold color="cyan">AI analysis</Text>
             <Newline />
-            {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+            {aiAnalysisText && !aiViewedFull && <Text>{aiAnalysisText}</Text>}
+            {aiAnalysisText && aiViewedFull && (
+              <Text dimColor>
+                📖  Analysis already shown above (scroll your terminal back to re-read it).
+              </Text>
+            )}
             {aiResultMessage && <Text>{aiResultMessage}</Text>}
             <Newline />
             <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
@@ -2781,6 +2799,7 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
                   setAiJobId(null)
                   setAiAnalysisText(null)
                   setAiResultMessage(null)
+                  setAiViewedFull(false)
                   setAiRetryCount(prev => prev + 1)
                   setStep('requesting-build')
                   return
@@ -2792,6 +2811,20 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
         )
       })()}
 
+      {/* AI debug — scrollable viewer (see iOS sibling). */}
+      {step === 'ai-analysis-result-scroll' && aiAnalysisText && (
+        <FullscreenAiViewer
+          title="AI analysis"
+          subtitle={`${aiAnalysisText.split('\n').length} lines — scrollable because the analysis is taller than your terminal`}
+          lines={aiAnalysisText.split('\n')}
+          terminalRows={terminalRows}
+          onExit={() => {
+            setAiViewedFull(true)
+            setStep('ai-analysis-result')
+          }}
+        />
+      )}
+
       {step === 'error' && error && retryStep && (
         <Box flexDirection="column" marginTop={1}>
           <ErrorLine text={error} />
diff --git a/cli/src/build/onboarding/types.ts b/cli/src/build/onboarding/types.ts
index 36f13ef9ba..fa2cf07361 100644
--- a/cli/src/build/onboarding/types.ts
+++ b/cli/src/build/onboarding/types.ts
@@ -49,6 +49,7 @@ export type OnboardingStep
     | 'ai-analysis-prompt'
     | 'ai-analysis-running'
     | 'ai-analysis-result'
+    | 'ai-analysis-result-scroll'
     | 'build-complete'
     | 'no-platform'
     | 'error'
@@ -170,6 +171,7 @@ export const STEP_PROGRESS: Record<OnboardingStep, number> = {
   'requesting-build': 90,
   'ai-analysis-prompt': 92,
   'ai-analysis-running': 95,
+  'ai-analysis-result-scroll': 97,
   'ai-analysis-result': 98,
   'build-complete': 100,
   'no-platform': 0,
@@ -234,6 +236,7 @@ export function getPhaseLabel(step: OnboardingStep): string {
     case 'ai-analysis-prompt':
     case 'ai-analysis-running':
     case 'ai-analysis-result':
+    case 'ai-analysis-result-scroll':
       return 'AI debug'
     case 'build-complete':
       return 'Complete'
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index b6830f8655..8d826b8435 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -23,6 +23,7 @@ import { releaseCapturedLogs, runCapgoAiAnalysis } from '../../../ai/analyze.js'
 import { renderMarkdown } from '../../../ai/render-markdown.js'
 import { trackAiAnalysisChoice, trackAiAnalysisResult } from '../../../ai/telemetry.js'
 import { requestBuildInternal } from '../../request.js'
+import { isAiAnalysisTooTall } from '../ai-fit.js'
 
 // Upper bound on "I fixed it, retry build" attempts after an AI diagnosis.
 // Three total attempts (initial + two retries) caps the AI cost when a model
@@ -44,7 +45,7 @@ import {
 
   STEP_PROGRESS,
 } from '../types.js'
-import { Divider, ErrorLine, FilteredTextInput, Header, SpinnerLine, SuccessLine } from './components.js'
+import { Divider, ErrorLine, FilteredTextInput, FullscreenAiViewer, Header, SpinnerLine, SuccessLine } from './components.js'
 
 const OUTPUT_LINE_SPLIT_RE = /\r?\n/
 const CARRIAGE_RETURN_RE = /\r/g
@@ -176,6 +177,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
   // Get terminal height for build output sizing
   const { stdout } = useStdout()
   const terminalRows = stdout?.rows ?? 24
+  const terminalCols = stdout?.columns ?? 80
 
   // Refs to avoid stale closures in useEffect async handlers
   const p8ContentRef = useRef(p8Content)
@@ -276,10 +278,14 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
   // these two state strings depending on the PostAnalyzeResult kind.
   // `aiRetryCount` tracks how many "I fixed it, retry" attempts the user has
   // used so we can cap them at MAX_AI_RETRIES.
+  // `aiViewedFull` flips true once the user has dismissed the scrollable
+  // FullscreenAiViewer for the current analysis — prevents 'ai-analysis-result'
+  // from immediately re-routing back into the scroll step on every render.
   const [aiJobId, setAiJobId] = useState<string | null>(null)
   const [aiAnalysisText, setAiAnalysisText] = useState<string | null>(null)
   const [aiResultMessage, setAiResultMessage] = useState<string | null>(null)
   const [aiRetryCount, setAiRetryCount] = useState(0)
+  const [aiViewedFull, setAiViewedFull] = useState(false)
   const [ciSecretEntries, setCiSecretEntries] = useState<CiSecretEntry[]>([])
   const [ciSecretTargets, setCiSecretTargets] = useState<CiSecretTarget[]>([])
   const [ciSecretTarget, setCiSecretTarget] = useState<CiSecretTarget | null>(null)
@@ -1373,6 +1379,16 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
       })()
     }
 
+    // When entering 'ai-analysis-result' with text the user hasn't yet seen,
+    // estimate fit and route through the fullscreen scroll viewer if the
+    // analysis is taller than the available viewport. The check is
+    // deliberately conservative — see ai-fit.ts for the heuristic.
+    if (step === 'ai-analysis-result' && aiAnalysisText && !aiViewedFull) {
+      if (isAiAnalysisTooTall(aiAnalysisText, terminalRows, terminalCols)) {
+        setStep('ai-analysis-result-scroll')
+      }
+    }
+
     if (step === 'build-complete') {
       setBuildOutput([])
       // Best-effort cleanup of any leftover captured log file. Safe to call
@@ -1400,9 +1416,12 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result'
-  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result'
-  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result'
+  // The scrollable AI viewer takes over the screen — hide outer chrome so it
+  // gets maximum vertical space.
+  const isAiResultScroll = step === 'ai-analysis-result-scroll'
+  const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result' && !isAiResultScroll
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null
@@ -2593,11 +2612,21 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
         const retryLabel = retriesLeft === 1
           ? '🔄  I fixed it, retry build (last retry)'
           : `🔄  I fixed it, retry build (${retriesLeft} retries left)`
+        // When the analysis was routed through the scroll viewer the user has
+        // already read it — repeating the body here would just push the picker
+        // off-screen on small terminals. Show a compact "Analysis reviewed"
+        // marker instead. `aiResultMessage` (used for too_big / error / etc.)
+        // is always short so it can render inline regardless.
         return (
           <Box flexDirection="column" marginTop={1}>
             <Text bold color="cyan">AI analysis</Text>
             <Newline />
-            {aiAnalysisText && <Text>{aiAnalysisText}</Text>}
+            {aiAnalysisText && !aiViewedFull && <Text>{aiAnalysisText}</Text>}
+            {aiAnalysisText && aiViewedFull && (
+              <Text dimColor>
+                📖  Analysis already shown above (scroll your terminal back to re-read it).
+              </Text>
+            )}
             {aiResultMessage && <Text>{aiResultMessage}</Text>}
             <Newline />
             <Text color="yellow">⚠ AI can make mistakes. Always verify the diagnosis against the full log before applying the suggested fix.</Text>
@@ -2636,10 +2665,13 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
                     // tied to a new builder_job_id.
                     void releaseCapturedLogs(aiJobId).catch(() => { /* best-effort */ })
                   }
-                  // Reset AI state so the next failure starts clean.
+                  // Reset AI state so the next failure starts clean. The fit
+                  // check (and possible scroll-viewer route) will re-evaluate
+                  // against the new analysis text.
                   setAiJobId(null)
                   setAiAnalysisText(null)
                   setAiResultMessage(null)
+                  setAiViewedFull(false)
                   setAiRetryCount(prev => prev + 1)
                   setStep('requesting-build')
                   return
@@ -2652,6 +2684,24 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
         )
       })()}
 
+      {/* AI debug — scrollable viewer for analyses too tall for the viewport.
+          The outer Header / progress bar are hidden during this step so the
+          viewer gets the full terminal height. On exit, we mark the analysis
+          as "viewed" and return to 'ai-analysis-result' (which now shows a
+          compact "Analysis above" indicator + the retry/skip picker). */}
+      {step === 'ai-analysis-result-scroll' && aiAnalysisText && (
+        <FullscreenAiViewer
+          title="AI analysis"
+          subtitle={`${aiAnalysisText.split('\n').length} lines — scrollable because the analysis is taller than your terminal`}
+          lines={aiAnalysisText.split('\n')}
+          terminalRows={terminalRows}
+          onExit={() => {
+            setAiViewedFull(true)
+            setStep('ai-analysis-result')
+          }}
+        />
+      )}
+
       {/* Error with retry */}
       {step === 'error' && error && (
         <Box flexDirection="column" marginTop={1}>
diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index a303bc6d76..8ff513388c 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -2,7 +2,7 @@ import type { FC } from 'react'
 import { Box, Text, useInput } from 'ink'
 import Spinner from 'ink-spinner'
 // src/build/onboarding/ui/components.tsx
-import React, { useState } from 'react'
+import React, { useEffect, useState } from 'react'
 
 export const Divider: FC<{ width?: number }> = ({ width = 60 }) => (
   <Text dimColor>{'─'.repeat(width)}</Text>
@@ -98,3 +98,96 @@ export const Header: FC = () => (
     </Text>
   </Box>
 )
+
+/**
+ * Scrollable, fullscreen viewer for the AI build-analysis markdown when it
+ * is taller than the user's terminal viewport. Mirrors the shape of the
+ * workflow-file diff viewer on main, but for pre-rendered ANSI lines (no
+ * `add`/`del` colouring — the markdown renderer already styled them).
+ *
+ * Keybindings:
+ *   ↑/k        scroll one line up
+ *   ↓/j        scroll one line down
+ *   PgUp/u     jump up one viewport
+ *   PgDn/d/␣   jump down one viewport
+ *   Home/g     jump to top
+ *   End/G      jump to bottom
+ *   Esc/Enter  dismiss the viewer (returns control to the parent step)
+ */
+export const FullscreenAiViewer: FC<{
+  title: string
+  subtitle?: string
+  lines: string[]
+  terminalRows: number
+  onExit: () => void
+}> = ({ title, subtitle, lines, terminalRows, onExit }) => {
+  // Reserve 8 rows for the viewer's own chrome: title (1) + optional subtitle
+  // (1) + top divider (1) + bottom divider (1) + position line (1) + exit
+  // hint (1) + 2 rows of breathing room. The parent wizard already hides its
+  // outer Header during this step so the viewer can use the full screen.
+  const viewportRows = Math.max(1, Math.min(lines.length || 1, terminalRows - 8))
+  const [scrollOffset, setScrollOffset] = useState(0)
+  const total = lines.length
+  const maxScrollOffset = Math.max(0, lines.length - viewportRows)
+
+  // Clamp the scroll if the viewport grows past the bottom (e.g. terminal
+  // resized larger after the user scrolled to the bottom).
+  useEffect(() => {
+    setScrollOffset(prev => Math.min(prev, maxScrollOffset))
+  }, [maxScrollOffset])
+
+  useInput((input, key) => {
+    if (key.escape || key.return) {
+      onExit()
+      return
+    }
+    if (key.downArrow || input === 'j') {
+      setScrollOffset(prev => Math.min(prev + 1, maxScrollOffset))
+      return
+    }
+    if (key.upArrow || input === 'k') {
+      setScrollOffset(prev => Math.max(prev - 1, 0))
+      return
+    }
+    if (key.pageDown || input === 'd' || input === ' ') {
+      setScrollOffset(prev => Math.min(prev + viewportRows, maxScrollOffset))
+      return
+    }
+    if (key.pageUp || input === 'u') {
+      setScrollOffset(prev => Math.max(prev - viewportRows, 0))
+      return
+    }
+    if (input === 'g') {
+      setScrollOffset(0)
+      return
+    }
+    if (input === 'G') {
+      setScrollOffset(maxScrollOffset)
+    }
+  })
+
+  const visibleLines = lines.slice(scrollOffset, scrollOffset + viewportRows)
+  const firstVisibleLine = total === 0 ? 0 : scrollOffset + 1
+  const lastVisibleLine = Math.min(total, scrollOffset + visibleLines.length)
+  const atBottom = scrollOffset >= maxScrollOffset
+
+  return (
+    <Box flexDirection="column">
+      <Text bold color="cyan">{title}</Text>
+      {subtitle && <Text dimColor>{subtitle}</Text>}
+      <Text color="cyan">{'─'.repeat(60)}</Text>
+      {visibleLines.map((line, index) => (
+        <Text key={`ai-line-${scrollOffset + index}`}>{line}</Text>
+      ))}
+      <Text color="cyan">{'─'.repeat(60)}</Text>
+      <Text dimColor>
+        {`Showing ${firstVisibleLine}-${lastVisibleLine} of ${total} lines. ↑/↓ or PgUp/PgDn to scroll.`}
+      </Text>
+      <Text color="yellow" bold>
+        {atBottom
+          ? 'Press Esc or Enter to continue to the retry/skip prompt.'
+          : 'Press Esc or Enter when done to continue.'}
+      </Text>
+    </Box>
+  )
+}
diff --git a/cli/test/test-ai-fit.mjs b/cli/test/test-ai-fit.mjs
new file mode 100644
index 0000000000..b17fce708f
--- /dev/null
+++ b/cli/test/test-ai-fit.mjs
@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Tests for the AI-result fit estimator used by the onboarding TUI to decide
+// whether to render the analysis inline or route it through the scrollable
+// FullscreenAiViewer.
+//
+// The heuristic is deliberately conservative — prefers "scroll" when in doubt
+// — so the tests focus on:
+//   1. Empty text  → never overflows.
+//   2. Text that fits comfortably → returns false.
+//   3. Text that obviously overflows → returns true.
+//   4. ANSI escape codes don't inflate the estimate.
+//   5. Long single line that would wrap → counted as multiple rows.
+import {
+  AI_RESULT_CHROME_ROWS,
+  estimateRenderedRows,
+  isAiAnalysisTooTall,
+  stripAnsi,
+} from '../src/build/onboarding/ai-fit.ts'
+
+let passed = 0
+let failed = 0
+function test(name, fn) {
+  try {
+    fn()
+    console.log(`✅ ${name}`)
+    passed++
+  }
+  catch (err) {
+    console.error(`❌ ${name}\n   ${err.message}`)
+    failed++
+  }
+}
+
+test('AI_RESULT_CHROME_ROWS is conservative (≥ 15)', () => {
+  if (AI_RESULT_CHROME_ROWS < 15)
+    throw new Error(`chrome reserve too small: ${AI_RESULT_CHROME_ROWS}`)
+})
+
+test('stripAnsi removes SGR escape codes', () => {
+  const styled = `\x1b[1;36mhello\x1b[0m world`
+  if (stripAnsi(styled) !== 'hello world')
+    throw new Error(`got ${JSON.stringify(stripAnsi(styled))}`)
+})
+
+test('estimateRenderedRows returns 0 for empty text', () => {
+  if (estimateRenderedRows('', 80) !== 0)
+    throw new Error('empty should be 0')
+})
+
+test('estimateRenderedRows counts each newline as a row floor of 1', () => {
+  // 5 short lines → 5 rows
+  const txt = ['a', 'b', '', 'c', 'd'].join('\n')
+  const rows = estimateRenderedRows(txt, 80)
+  if (rows !== 5)
+    throw new Error(`expected 5, got ${rows}`)
+})
+
+test('estimateRenderedRows accounts for line wrap', () => {
+  // 160 chars on a 40-col terminal → 4 rows
+  const txt = 'a'.repeat(160)
+  const rows = estimateRenderedRows(txt, 40)
+  if (rows !== 4)
+    throw new Error(`expected 4, got ${rows}`)
+})
+
+test('estimateRenderedRows ignores ANSI codes for length', () => {
+  // 'hello' with red color = 5 visible chars, should be 1 row at width 80
+  const txt = `\x1b[31mhello\x1b[0m`
+  const rows = estimateRenderedRows(txt, 80)
+  if (rows !== 1)
+    throw new Error(`expected 1, got ${rows}`)
+})
+
+test('isAiAnalysisTooTall: empty text → false', () => {
+  if (isAiAnalysisTooTall('', 30, 80) !== false)
+    throw new Error('empty should fit')
+})
+
+test('isAiAnalysisTooTall: short text on a tall terminal → false (fits)', () => {
+  const txt = ['### Likely cause', '', 'Missing entitlement.'].join('\n')
+  if (isAiAnalysisTooTall(txt, 40, 80) !== false)
+    throw new Error('3 short lines on 40-row terminal should fit')
+})
+
+test('isAiAnalysisTooTall: many lines on a small terminal → true (overflows)', () => {
+  // 50 lines on a 24-row terminal — definitely doesn't fit
+  const txt = Array.from({ length: 50 }, (_, i) => `line ${i}`).join('\n')
+  if (isAiAnalysisTooTall(txt, 24, 80) !== true)
+    throw new Error('50 lines on 24-row terminal should NOT fit')
+})
+
+test('isAiAnalysisTooTall: borderline case errs on the side of scroll (conservative)', () => {
+  // 20 rows of text, 24-row terminal, 20-row chrome reserve → 4 rows budget.
+  // 20 > 4, must return true.
+  const txt = Array.from({ length: 20 }, (_, i) => `line ${i}`).join('\n')
+  if (isAiAnalysisTooTall(txt, 24, 80) !== true)
+    throw new Error('borderline should err toward true')
+})
+
+test('isAiAnalysisTooTall: very tall terminal accepts moderate analyses', () => {
+  // 10 rows of text, 60-row terminal — fits easily even with 20-row chrome
+  const txt = Array.from({ length: 10 }, (_, i) => `line ${i}`).join('\n')
+  if (isAiAnalysisTooTall(txt, 60, 80) !== false)
+    throw new Error('10 lines on 60-row terminal should fit')
+})
+
+test('isAiAnalysisTooTall: one very long wrapping line on narrow terminal → true', () => {
+  // One logical line, 800 chars, 40-col terminal → 20 wrapped rows
+  // 20 rows on 24-row terminal with 20-row chrome → 4 budget → overflows.
+  const txt = 'a'.repeat(800)
+  if (isAiAnalysisTooTall(txt, 24, 40) !== true)
+    throw new Error('long wrapping line should overflow')
+})
+
+console.log(`\n${passed} passed, ${failed} failed`)
+if (failed > 0)
+  process.exit(1)

From 71d38443b17c8f2ae012e978daafb1c63abb9be8 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 15:35:21 +0200
Subject: [PATCH 04/14] fix(cli): make AI viewer reactive to resize and account
 for line wrap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two bugs caused the FullscreenAiViewer to push content into the terminal's
scrollback history, forcing the user to scroll the terminal emulator (not
the viewer) to see the analysis:

1. Dimensions were captured at mount time. When the terminal was resized
   the viewer kept its original `viewportRows` and chrome reserve, so the
   actual rendered output could be taller (or shorter) than the live screen.

2. Both `viewportRows` and `maxScrollOffset` treated each logical line as
   one terminal row. Long lines wrap, so a "10-row" slice could actually
   render as 30+ rows on a narrow terminal — overflowing the viewport.

This change addresses both:

- `FullscreenAiViewer` now subscribes to `stdout.on('resize', ...)` and
  stores `{ rows, cols }` in state. Every resize triggers a re-render that
  recomputes the viewport, max scroll offset, divider width, and visible
  slice against the live dimensions.

- Two new helpers in `ai-fit.ts`:
    `pickVisibleLines(lines, scrollOffset, viewportRows, terminalCols)`
       — wrap-aware slice. Stops adding logical lines once their cumulative
         wrapped row count would exceed the viewport. Always includes at
         least one line so the viewer body is never empty.
    `computeMaxScrollOffset(lines, viewportRows, terminalCols)`
       — wrap-aware scroll bound. Walks backwards from the last line,
         packing as many tail lines as fit (counting wrap), and returns the
         offset of the first fully-visible tail line.

- Chrome reserve bumped from 8 to 10 rows to absorb chrome lines that
  themselves wrap on narrow terminals (subtitle, position line, exit hint
  are all sentence-length and can wrap on <60-col terminals).

- Dividers now scale to `min(60, cols - 1)` so they never wrap and silently
  eat a viewport row.

Test coverage in `test-ai-fit.mjs` (22 tests, all green):
- ANSI strip, simple row counting, wrap accounting (preserved)
- `pickVisibleLines`: empty input, scroll past end, simple slice, wrap-
  triggered early stop, one-line floor for hostile single lines, offset.
- `computeMaxScrollOffset`: empty input, viewport-larger-than-content,
  simple packing, wrap-aware tail packing.
---
 cli/src/build/onboarding/ai-fit.ts         | 70 ++++++++++++++++++
 cli/src/build/onboarding/ui/components.tsx | 64 +++++++++++++----
 cli/test/test-ai-fit.mjs                   | 84 ++++++++++++++++++++++
 3 files changed, 206 insertions(+), 12 deletions(-)

diff --git a/cli/src/build/onboarding/ai-fit.ts b/cli/src/build/onboarding/ai-fit.ts
index 26204440ac..7a87d220a7 100644
--- a/cli/src/build/onboarding/ai-fit.ts
+++ b/cli/src/build/onboarding/ai-fit.ts
@@ -72,3 +72,73 @@ export function isAiAnalysisTooTall(
   const estimated = estimateRenderedRows(text, terminalCols)
   return estimated > availableRows
 }
+
+/**
+ * Wrap-aware rendered-row count for a single logical line.
+ * Treats blank/empty lines as one row (Ink still occupies a row for them).
+ */
+function renderedRowsForLine(line: string, terminalCols: number): number {
+  const cols = Math.max(1, Math.floor(terminalCols))
+  const visibleLen = stripAnsi(line).length
+  return Math.max(1, Math.ceil(visibleLen / cols))
+}
+
+/**
+ * Pick the slice of `lines` starting at `scrollOffset` that fits within
+ * `viewportRows` *rendered* rows on a terminal `terminalCols` wide. Returns
+ * fewer lines than would otherwise be sliced when individual lines wrap.
+ *
+ * Always returns at least one line if the input is non-empty and the
+ * `scrollOffset` is in-range — even if that line wraps to more rows than the
+ * viewport. The user can still scroll past it; without this floor the viewer
+ * would render an empty body on hostile inputs.
+ */
+export function pickVisibleLines(
+  lines: string[],
+  scrollOffset: number,
+  viewportRows: number,
+  terminalCols: number,
+): string[] {
+  if (lines.length === 0 || scrollOffset >= lines.length)
+    return []
+  const result: string[] = []
+  let rowsUsed = 0
+  for (let i = scrollOffset; i < lines.length; i++) {
+    const rows = renderedRowsForLine(lines[i], terminalCols)
+    if (result.length > 0 && rowsUsed + rows > viewportRows)
+      break
+    result.push(lines[i])
+    rowsUsed += rows
+    if (rowsUsed >= viewportRows)
+      break
+  }
+  return result
+}
+
+/**
+ * Compute the largest `scrollOffset` that still keeps content visible at the
+ * bottom of the viewport — i.e. the offset where the LAST line is rendered
+ * within the viewport. Walks backwards from the end, packing as many tail
+ * lines as fit (accounting for wrap), and returns the offset of the first
+ * fully-visible tail line.
+ */
+export function computeMaxScrollOffset(
+  lines: string[],
+  viewportRows: number,
+  terminalCols: number,
+): number {
+  if (lines.length === 0)
+    return 0
+  let rowsUsed = 0
+  let kFromEnd = 0
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const rows = renderedRowsForLine(lines[i], terminalCols)
+    if (kFromEnd > 0 && rowsUsed + rows > viewportRows)
+      break
+    rowsUsed += rows
+    kFromEnd += 1
+    if (rowsUsed >= viewportRows)
+      break
+  }
+  return Math.max(0, lines.length - kFromEnd)
+}
diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index 8ff513388c..80da7dd196 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -1,8 +1,9 @@
 import type { FC } from 'react'
-import { Box, Text, useInput } from 'ink'
+import { Box, Text, useInput, useStdout } from 'ink'
 import Spinner from 'ink-spinner'
 // src/build/onboarding/ui/components.tsx
 import React, { useEffect, useState } from 'react'
+import { computeMaxScrollOffset, pickVisibleLines } from '../ai-fit.js'
 
 export const Divider: FC<{ width?: number }> = ({ width = 60 }) => (
   <Text dimColor>{'─'.repeat(width)}</Text>
@@ -121,16 +122,49 @@ export const FullscreenAiViewer: FC<{
   terminalRows: number
   onExit: () => void
 }> = ({ title, subtitle, lines, terminalRows, onExit }) => {
-  // Reserve 8 rows for the viewer's own chrome: title (1) + optional subtitle
-  // (1) + top divider (1) + bottom divider (1) + position line (1) + exit
-  // hint (1) + 2 rows of breathing room. The parent wizard already hides its
-  // outer Header during this step so the viewer can use the full screen.
-  const viewportRows = Math.max(1, Math.min(lines.length || 1, terminalRows - 8))
-  const [scrollOffset, setScrollOffset] = useState(0)
+  // Track terminal dimensions in state so the component re-renders on resize.
+  // Without this, the viewport was computed at mount and the body could
+  // overflow the live screen if the user enlarged or shrank the terminal —
+  // forcing the user to scroll their terminal emulator to see content the
+  // viewer should have paginated.
+  const { stdout } = useStdout()
+  const initialRows = stdout?.rows ?? terminalRows
+  const initialCols = stdout?.columns ?? 80
+  const [dims, setDims] = useState<{ rows: number, cols: number }>({
+    rows: initialRows,
+    cols: initialCols,
+  })
+
+  useEffect(() => {
+    if (!stdout)
+      return
+    const handler = (): void => {
+      setDims({
+        rows: stdout.rows ?? 24,
+        cols: stdout.columns ?? 80,
+      })
+    }
+    stdout.on('resize', handler)
+    return () => {
+      stdout.off('resize', handler)
+    }
+  }, [stdout])
+
+  // Reserve 10 rows for the viewer's own chrome: title + optional subtitle +
+  // two dividers + position line + exit hint + a margin to absorb chrome
+  // lines that themselves wrap on narrow terminals. The parent wizard has
+  // already hidden its outer Header for this step so the viewer owns the
+  // whole screen.
+  const VIEWER_CHROME_ROWS = 10
+  const viewportRows = Math.max(1, dims.rows - VIEWER_CHROME_ROWS)
   const total = lines.length
-  const maxScrollOffset = Math.max(0, lines.length - viewportRows)
+  // Wrap-aware bound: maximum offset that still places the last logical line
+  // inside the viewport. Without per-line wrap accounting the user could
+  // scroll past the end on narrow terminals.
+  const maxScrollOffset = computeMaxScrollOffset(lines, viewportRows, dims.cols)
+  const [scrollOffset, setScrollOffset] = useState(0)
 
-  // Clamp the scroll if the viewport grows past the bottom (e.g. terminal
+  // Clamp the scroll if the viewport grew past the bottom (e.g. terminal
   // resized larger after the user scrolled to the bottom).
   useEffect(() => {
     setScrollOffset(prev => Math.min(prev, maxScrollOffset))
@@ -166,20 +200,26 @@ export const FullscreenAiViewer: FC<{
     }
   })
 
-  const visibleLines = lines.slice(scrollOffset, scrollOffset + viewportRows)
+  // Wrap-aware visible slice. `pickVisibleLines` stops adding logical lines
+  // once their cumulative wrapped row count would overflow `viewportRows`,
+  // so we never render past the bottom of the live terminal.
+  const visibleLines = pickVisibleLines(lines, scrollOffset, viewportRows, dims.cols)
   const firstVisibleLine = total === 0 ? 0 : scrollOffset + 1
   const lastVisibleLine = Math.min(total, scrollOffset + visibleLines.length)
   const atBottom = scrollOffset >= maxScrollOffset
+  // Divider widths scale to the terminal so the cosmetic border doesn't
+  // wrap on narrow terminals (which would silently eat a viewport row).
+  const dividerWidth = Math.max(10, Math.min(60, dims.cols - 1))
 
   return (
     <Box flexDirection="column">
       <Text bold color="cyan">{title}</Text>
       {subtitle && <Text dimColor>{subtitle}</Text>}
-      <Text color="cyan">{'─'.repeat(60)}</Text>
+      <Text color="cyan">{'─'.repeat(dividerWidth)}</Text>
       {visibleLines.map((line, index) => (
         <Text key={`ai-line-${scrollOffset + index}`}>{line}</Text>
       ))}
-      <Text color="cyan">{'─'.repeat(60)}</Text>
+      <Text color="cyan">{'─'.repeat(dividerWidth)}</Text>
       <Text dimColor>
         {`Showing ${firstVisibleLine}-${lastVisibleLine} of ${total} lines. ↑/↓ or PgUp/PgDn to scroll.`}
       </Text>
diff --git a/cli/test/test-ai-fit.mjs b/cli/test/test-ai-fit.mjs
index b17fce708f..094d4d786c 100644
--- a/cli/test/test-ai-fit.mjs
+++ b/cli/test/test-ai-fit.mjs
@@ -12,8 +12,10 @@
 //   5. Long single line that would wrap → counted as multiple rows.
 import {
   AI_RESULT_CHROME_ROWS,
+  computeMaxScrollOffset,
   estimateRenderedRows,
   isAiAnalysisTooTall,
+  pickVisibleLines,
   stripAnsi,
 } from '../src/build/onboarding/ai-fit.ts'
 
@@ -112,6 +114,88 @@ test('isAiAnalysisTooTall: one very long wrapping line on narrow terminal → tr
     throw new Error('long wrapping line should overflow')
 })
 
+// ── pickVisibleLines ─────────────────────────────────────────────────────────
+
+test('pickVisibleLines: empty input returns []', () => {
+  const out = pickVisibleLines([], 0, 10, 80)
+  if (out.length !== 0)
+    throw new Error('expected []')
+})
+
+test('pickVisibleLines: scrollOffset past end returns []', () => {
+  const out = pickVisibleLines(['a', 'b'], 5, 10, 80)
+  if (out.length !== 0)
+    throw new Error('expected []')
+})
+
+test('pickVisibleLines: returns at most viewportRows simple lines', () => {
+  const lines = ['a', 'b', 'c', 'd', 'e']
+  const out = pickVisibleLines(lines, 0, 3, 80)
+  if (out.join(',') !== 'a,b,c')
+    throw new Error(`got ${out.join(',')}`)
+})
+
+test('pickVisibleLines: stops early when wrapped lines would overflow', () => {
+  // 80-char line wraps to 4 rows on a 20-col terminal. Viewport 5 rows →
+  // 4 (first line) + 1 (second short) = 5 fits exactly, then we stop.
+  // The third short line is dropped because rowsUsed already hit viewportRows.
+  const lines = ['x'.repeat(80), 'short', 'short']
+  const out = pickVisibleLines(lines, 0, 5, 20)
+  if (out.length !== 2)
+    throw new Error(`expected 2 lines, got ${out.length}`)
+})
+
+test('pickVisibleLines: floor at one line even if it overflows by itself', () => {
+  // 200-char line wraps to 10 rows on 20-col terminal, viewport is 5 rows.
+  // We still include the line so the viewer isn't blank.
+  const lines = ['x'.repeat(200)]
+  const out = pickVisibleLines(lines, 0, 5, 20)
+  if (out.length !== 1)
+    throw new Error('expected 1 line as floor')
+})
+
+test('pickVisibleLines: starts from scrollOffset', () => {
+  const lines = ['a', 'b', 'c', 'd', 'e']
+  const out = pickVisibleLines(lines, 2, 2, 80)
+  if (out.join(',') !== 'c,d')
+    throw new Error(`got ${out.join(',')}`)
+})
+
+// ── computeMaxScrollOffset ───────────────────────────────────────────────────
+
+test('computeMaxScrollOffset: empty input is 0', () => {
+  if (computeMaxScrollOffset([], 5, 80) !== 0)
+    throw new Error('expected 0')
+})
+
+test('computeMaxScrollOffset: simple lines, viewport ≥ count → 0', () => {
+  // 5 short lines, viewport 10 — everything fits, max offset is 0
+  const lines = ['a', 'b', 'c', 'd', 'e']
+  if (computeMaxScrollOffset(lines, 10, 80) !== 0)
+    throw new Error('expected 0 when everything fits')
+})
+
+test('computeMaxScrollOffset: simple lines, viewport < count → packs from end', () => {
+  // 10 short lines, viewport 3 → max offset = 7 (lines 7,8,9 visible)
+  const lines = Array.from({ length: 10 }, (_, i) => `line ${i}`)
+  if (computeMaxScrollOffset(lines, 3, 80) !== 7)
+    throw new Error(`expected 7, got ${computeMaxScrollOffset(lines, 3, 80)}`)
+})
+
+test('computeMaxScrollOffset: long wrapping tail line counts for wrap', () => {
+  // Last line wraps to 3 rows on a 20-col terminal, viewport 5 → only 2 short
+  // tail lines + the wrapping line fit. Actually: tail line takes 3 rows,
+  // then 2 more short lines (1 row each) = 5 rows total. So 3 lines fit at
+  // the end → max offset = 10 - 3 = 7.
+  const lines = [
+    ...Array.from({ length: 9 }, (_, i) => `line ${i}`),
+    'y'.repeat(60),
+  ]
+  const got = computeMaxScrollOffset(lines, 5, 20)
+  if (got !== 7)
+    throw new Error(`expected 7, got ${got}`)
+})
+
 console.log(`\n${passed} passed, ${failed} failed`)
 if (failed > 0)
   process.exit(1)

From 66ea6dc204fcc13286cf941ea40b83e7055606b9 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 15:45:14 +0200
Subject: [PATCH 05/14] fix(cli): hide outer Header on AI debug sub-flow to
 avoid duplicate chrome
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ink renders in normal-terminal mode, so each step transition leaves the
previous frame in the user's scrollback. When the AI prompt step's Select
fires and the wizard transitions to `ai-analysis-running` (or beyond), the
new frame previously rendered its own Header — producing the visible
artifact of two stacked "🚀 Capgo Cloud Build · Onboarding" boxes:

  ╔══════════════════════════╗   ← frozen above by the previous frame
  ║  Capgo Cloud Build       ║
  ║  · Onboarding            ║
  ╚══════════════════════════╝
  AI debug · 92%
  ...
  > Debug with AI ✔
    Skip
  ╔══════════════════════════╗   ← duplicate, rendered by the new frame
  ║  Capgo Cloud Build       ║
  ║  · Onboarding            ║
  ╚══════════════════════════╝
  AI debug · 95%
  ...
  Analyzing build log with Capgo AI (Kimi K2.5)...

This was already partly addressed for `ai-analysis-result` and
`ai-analysis-result-scroll`. Extending the same suppression to
`ai-analysis-prompt` and `ai-analysis-running` keeps the entire AI
sub-flow Header-free, so the most recent Header in scrollback is the
one tied to the user's current AI step instead of a stale earlier one.

The frozen "Debug with AI ✔ / Skip" line is left visible — that's
normal Ink behavior in non-alternative-screen mode (the previous
frame's content stays in scrollback) and would require a fullscreen
mode switch to address, out of scope here.

Mirrored to both iOS (cli/src/build/onboarding/ui/app.tsx) and Android
(cli/src/build/onboarding/android/ui/app.tsx) wizards.
---
 cli/src/build/onboarding/android/ui/app.tsx |  9 +++++++--
 cli/src/build/onboarding/ui/app.tsx         | 14 ++++++++++++--
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index 1324d8250c..3e3ffc045f 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -1567,10 +1567,15 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
+  // See iOS sibling for the rationale: Header is hidden across the whole
+  // AI sub-flow to avoid the duplicate-Header visual that happens when a
+  // step transition leaves the previous frame in the user's scrollback
+  // and the new frame renders the Header again below it.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
+  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiStep
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
     <Box flexDirection="column" padding={1}>
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 8d826b8435..30650bab07 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -1418,10 +1418,20 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
   const phaseLabel = getPhaseLabel(step)
   // The scrollable AI viewer takes over the screen — hide outer chrome so it
   // gets maximum vertical space.
+  // Header is hidden across the WHOLE AI sub-flow (not just the scroll
+  // step): Ink renders in normal-terminal mode, so each step transition
+  // leaves the previous frame in the user's scrollback. If the new frame
+  // also rendered a Header, the user would see TWO identical
+  // "Capgo Cloud Build · Onboarding" boxes stacked — one frozen above
+  // (from the prompt step) and one fresh below (on the running/result
+  // step). Suppressing the Header during the AI sub-flow keeps the
+  // transition visually unambiguous: the most recent header in the
+  // scrollback is the one that belongs to the AI step.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
+  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showLog = step !== 'requesting-build' && step !== 'build-complete' && step !== 'ai-analysis-prompt' && step !== 'ai-analysis-running' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiStep
+  const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null

From f462f37f7aa3a2baf9104ec4bc7273e608f6c38e Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 15:48:00 +0200
Subject: [PATCH 06/14] fix(cli): keep Header on AI prompt step (only suppress
 on post-Select steps)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous fix went too far and hid the Header on every AI sub-flow
step including the entry one (`ai-analysis-prompt`). That left the user
seeing a chrome-less "Build failed." prompt with no wizard anchoring,
which felt jarring — the screenshot showed an isolated `AI debug`
phase label + progress bar over a bare error message and Select.

Refining: keep the Header on `ai-analysis-prompt` (the entry into the
AI sub-flow — first thing the user sees, needs wizard anchoring) and
only suppress it on the steps that render AFTER the prompt's Select
fires (`ai-analysis-running`, `ai-analysis-result`,
`ai-analysis-result-scroll`). Those are the ones at risk of stacking a
fresh Header below the frozen previous frame in the user's scrollback.

Net result:
- First entry to AI flow: Header + AI debug + progress + "Build failed"
  + Select  — looks like a normal wizard step, no missing chrome.
- User picks: Select freezes that frame into scrollback.
- New frame (running): no Header — frozen Header from prompt remains the
  most recent one visible, no duplicate.
- Same for result / result-scroll.

Mirrored to both iOS and Android wizards.
---
 cli/src/build/onboarding/android/ui/app.tsx | 13 ++++++------
 cli/src/build/onboarding/ui/app.tsx         | 23 +++++++++------------
 2 files changed, 17 insertions(+), 19 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index 3e3ffc045f..c90506e984 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -1567,14 +1567,15 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  // See iOS sibling for the rationale: Header is hidden across the whole
-  // AI sub-flow to avoid the duplicate-Header visual that happens when a
-  // step transition leaves the previous frame in the user's scrollback
-  // and the new frame renders the Header again below it.
+  // See iOS sibling for the rationale: keep Header on the AI prompt (entry
+  // point — gives wizard anchoring), but hide it on steps that come AFTER
+  // the prompt's Select fires so we don't render a duplicate Header below
+  // the frozen previous frame.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
-  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const isPostPromptAiStep = step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const isAiStep = step === 'ai-analysis-prompt' || isPostPromptAiStep
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isAiStep
+  const showHeader = step !== 'requesting-build' && !isPostPromptAiStep
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 30650bab07..0b979dbb26 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -1416,21 +1416,18 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  // The scrollable AI viewer takes over the screen — hide outer chrome so it
-  // gets maximum vertical space.
-  // Header is hidden across the WHOLE AI sub-flow (not just the scroll
-  // step): Ink renders in normal-terminal mode, so each step transition
-  // leaves the previous frame in the user's scrollback. If the new frame
-  // also rendered a Header, the user would see TWO identical
-  // "Capgo Cloud Build · Onboarding" boxes stacked — one frozen above
-  // (from the prompt step) and one fresh below (on the running/result
-  // step). Suppressing the Header during the AI sub-flow keeps the
-  // transition visually unambiguous: the most recent header in the
-  // scrollback is the one that belongs to the AI step.
+  // Ink renders in normal-terminal mode, so each step transition leaves
+  // the previous frame in the user's scrollback. The first AI step
+  // (`ai-analysis-prompt`) keeps the Header so the user has wizard
+  // anchoring when "Build failed" appears. Every step AFTER the prompt's
+  // Select fires (running, result, scroll) hides the Header so it doesn't
+  // re-render below the frozen previous frame and produce a visible
+  // duplicate "🚀 Capgo Cloud Build · Onboarding" box.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
-  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const isPostPromptAiStep = step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const isAiStep = step === 'ai-analysis-prompt' || isPostPromptAiStep
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isAiStep
+  const showHeader = step !== 'requesting-build' && !isPostPromptAiStep
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)

From 2d7ea704948154953db4a6475a2bebfe79ec125e Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 15:56:04 +0200
Subject: [PATCH 07/14] =?UTF-8?q?fix(cli):=20render=20onboarding=20Header?=
 =?UTF-8?q?=20via=20Ink=20Static=20=E2=80=94=20one=20banner,=20no=20duplic?=
 =?UTF-8?q?ates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous "hide Header on post-Select AI steps" fix removed the
duplicate banner artifact, but at the cost of leaving the AI-running
step Header-less — the wizard then looked decapitated as soon as the
user picked "Debug with AI".

The right tool for this is Ink's `<Static>`. Static items are written
to the terminal exactly once, above the dynamic render area, and never
re-rendered. Putting the Header inside `<Static>` gives us:

- A single persistent "🚀 Capgo Cloud Build · Onboarding" banner that
  the user sees on every step (including the whole AI sub-flow).
- Zero risk of a duplicate banner ever appearing — Ink does not re-emit
  static content on subsequent renders, so step transitions, terminal
  resizes, and the @inkjs/ui Select committing its selected line into
  scrollback all leave the banner untouched.

The previous `showHeader` conditional and the `isPostPromptAiStep`
helper are no longer needed; removed in both wizards. `showLog` and
`showProgress` keep their existing per-step semantics — only the Header
moved to Static.

Module-level `STATIC_HEADER_ITEMS = ['header']` keeps the items array
reference stable across renders so Static doesn't ever decide a new
item appeared. Ink's Static items prop is typed as a mutable `string[]`,
so the constant is declared accordingly (the array is never mutated in
practice).

Mirrored to both iOS (cli/src/build/onboarding/ui/app.tsx) and Android
(cli/src/build/onboarding/android/ui/app.tsx) wizards.
---
 cli/src/build/onboarding/android/ui/app.tsx | 33 ++++++++++-------
 cli/src/build/onboarding/ui/app.tsx         | 41 +++++++++++++--------
 2 files changed, 45 insertions(+), 29 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index c90506e984..aa692475e7 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -20,7 +20,7 @@ import { homedir } from 'node:os'
 import { join, resolve as resolvePath } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
 // src/build/onboarding/android/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { createSupabaseClient, findSavedKey, findSavedKeySilent, getOrganizationId } from '../../../../utils.js'
@@ -126,6 +126,10 @@ function emptyProgress(appId: string): AndroidOnboardingProgress {
   }
 }
 
+// Static items passed to Ink's `<Static>` to render the Header exactly once.
+// See iOS sibling for the rationale.
+const STATIC_HEADER_ITEMS: string[] = ['header']
+
 const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir, apikey }) => {
   const { exit } = useApp()
   const startStep: AndroidOnboardingStep = getAndroidResumeStep(initialProgress)
@@ -1567,22 +1571,24 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  // See iOS sibling for the rationale: keep Header on the AI prompt (entry
-  // point — gives wizard anchoring), but hide it on steps that come AFTER
-  // the prompt's Select fires so we don't render a duplicate Header below
-  // the frozen previous frame.
+  // See iOS sibling: Header is rendered exactly once via `<Static>` below
+  // so a single persistent banner sits above every step (including the AI
+  // sub-flow), with no duplicate-Header artifact when steps transition.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
-  const isPostPromptAiStep = step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
-  const isAiStep = step === 'ai-analysis-prompt' || isPostPromptAiStep
+  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isPostPromptAiStep
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
-    <Box flexDirection="column" padding={1}>
-      {showHeader && <Header />}
-
-      {showProgress && (
+    <>
+      {/* Render the Header exactly once via Ink's `<Static>` — see iOS
+          sibling. The dynamic area below changes step-by-step but the
+          banner stays put. */}
+      <Static items={STATIC_HEADER_ITEMS}>
+        {item => <Header key={item} />}
+      </Static>
+      <Box flexDirection="column" padding={1}>
+        {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
           <Box marginTop={1}>
@@ -2855,7 +2861,8 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           />
         </Box>
       )}
-    </Box>
+      </Box>
+    </>
   )
 }
 
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 0b979dbb26..07e3dfd1c1 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -11,7 +11,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
 import open from 'open'
 // src/build/onboarding/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
@@ -98,6 +98,11 @@ async function runRunnerCommand(runner: string, args: string[]): Promise<{ succe
   })
 }
 
+// Static items passed to Ink's `<Static>` to render the Header exactly once,
+// above the dynamic render area. Using a module-level constant keeps the
+// reference stable across renders so Static doesn't think new items appeared.
+const STATIC_HEADER_ITEMS: string[] = ['header']
+
 const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey }) => {
   const { exit } = useApp()
   const startStep = getResumeStep(initialProgress)
@@ -1416,28 +1421,31 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  // Ink renders in normal-terminal mode, so each step transition leaves
-  // the previous frame in the user's scrollback. The first AI step
-  // (`ai-analysis-prompt`) keeps the Header so the user has wizard
-  // anchoring when "Build failed" appears. Every step AFTER the prompt's
-  // Select fires (running, result, scroll) hides the Header so it doesn't
-  // re-render below the frozen previous frame and produce a visible
-  // duplicate "🚀 Capgo Cloud Build · Onboarding" box.
+  // The outer Header is rendered inside `<Static>` below — it's written to
+  // the terminal exactly once and never re-rendered, so the user sees a
+  // single persistent banner across every step (including the AI sub-flow
+  // and its transitions). That eliminates the duplicate-Header artifact
+  // that came from Ink committing each step's frame into scrollback.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
-  const isPostPromptAiStep = step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
-  const isAiStep = step === 'ai-analysis-prompt' || isPostPromptAiStep
+  const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isPostPromptAiStep
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null
 
   return (
-    <Box flexDirection="column" padding={1}>
-      {showHeader && <Header />}
-
-      {/* Progress bar */}
+    <>
+      {/* Render the Header exactly once via Ink's `<Static>` — see the
+          STATIC_HEADER_ITEMS comment above. The dynamic render area below
+          changes step-by-step but never touches the Header, so resizing the
+          terminal or transitioning between steps cannot produce a duplicate
+          banner in scrollback. */}
+      <Static items={STATIC_HEADER_ITEMS}>
+        {item => <Header key={item} />}
+      </Static>
+      <Box flexDirection="column" padding={1}>
+        {/* Progress bar */}
       {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
@@ -2855,7 +2863,8 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           <Newline />
         </Box>
       )}
-    </Box>
+      </Box>
+    </>
   )
 }
 

From a661967393951abe7e0a19be93668ac80983afcd Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:10:47 +0200
Subject: [PATCH 08/14] fix(cli): run onboarding in alternative-screen mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This replaces the previous Ink-Static-Header approach (which made the
banner permanent at the cost of losing it on `requesting-build` and the
scrollable AI viewer) with terminal alt-screen mode for the whole wizard.

In alt-screen mode the terminal uses a separate buffer where each Ink
frame fully replaces the previous one. That removes the underlying cause
of the duplicate-Header artifact (Ink committing each step's frame into
scrollback) and unlocks the original `showHeader` conditional, so we can
go back to:

- Header VISIBLE on every interactive step including the entire AI
  sub-flow (`ai-analysis-prompt`, `ai-analysis-running`,
  `ai-analysis-result`) — fixes the "no banner on Analyzing build log"
  regression.
- Header HIDDEN on `requesting-build` and `ai-analysis-result-scroll`
  — those steps get the full terminal height for build output and the
  scrollable AI viewer, as before the Static experiment.

### Mechanics

`command.ts`:
- `enterAltScreen()` writes `ESC[?1049h ESC[H` (enter alt buffer + cursor
  home) before `render()`.
- `exitAltScreen()` writes `ESC[?1049l` after `waitUntilExit()` so the
  user's pre-wizard terminal content is restored on clean exit.
- Process-level cleanup handlers (`exit` / `SIGINT` / `SIGTERM` /
  `uncaughtException`) also call `exitAltScreen()` so the user is never
  stranded in an alt buffer if something crashes.
- After exit, prints a one-line summary
  `✔ Capgo onboarding complete for <appId> (<platform>).` so the user
  has a visible breadcrumb in the normal terminal flow that the wizard
  finished (the wizard's last frame is wiped by the buffer restore —
  same UX as vim/htop/less, which is the expected behavior for a TUI).

### iOS / Android wizards

- Reverted commit 2d7ea7049 (Ink Static for Header).
- `showHeader = step !== 'requesting-build' && !isAiResultScroll` — the
  same conditional intent as before the duplicate-Header bug ever
  surfaced.
- Removed the now-redundant `isPostPromptAiStep` helper.

### Trade-offs

- The wizard's per-step output is no longer left in scrollback when the
  user exits — that's the expected TUI behavior and is documented by the
  completion summary line.
- Power users who wanted to scroll back through wizard steps DURING the
  flow lose that ability (alt buffer doesn't keep scrollback). They can
  use the wizard's own back/retry affordances instead.
---
 cli/src/build/onboarding/android/ui/app.tsx | 31 +++----
 cli/src/build/onboarding/command.ts         | 95 +++++++++++++++++----
 cli/src/build/onboarding/ui/app.tsx         | 38 +++------
 3 files changed, 104 insertions(+), 60 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index aa692475e7..ceadbe152a 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -20,7 +20,7 @@ import { homedir } from 'node:os'
 import { join, resolve as resolvePath } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
 // src/build/onboarding/android/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { createSupabaseClient, findSavedKey, findSavedKeySilent, getOrganizationId } from '../../../../utils.js'
@@ -126,10 +126,6 @@ function emptyProgress(appId: string): AndroidOnboardingProgress {
   }
 }
 
-// Static items passed to Ink's `<Static>` to render the Header exactly once.
-// See iOS sibling for the rationale.
-const STATIC_HEADER_ITEMS: string[] = ['header']
-
 const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir, apikey }) => {
   const { exit } = useApp()
   const startStep: AndroidOnboardingStep = getAndroidResumeStep(initialProgress)
@@ -1571,24 +1567,22 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  // See iOS sibling: Header is rendered exactly once via `<Static>` below
-  // so a single persistent banner sits above every step (including the AI
-  // sub-flow), with no duplicate-Header artifact when steps transition.
+  // See iOS sibling: the wizard runs in the terminal's alternative screen
+  // buffer so each Ink frame fully replaces the previous — no scrollback
+  // accumulation, no duplicate Header artifact. `showHeader` can be a plain
+  // step conditional that hides on the steps which need max screen
+  // (`requesting-build` and the scrollable AI viewer).
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
-    <>
-      {/* Render the Header exactly once via Ink's `<Static>` — see iOS
-          sibling. The dynamic area below changes step-by-step but the
-          banner stays put. */}
-      <Static items={STATIC_HEADER_ITEMS}>
-        {item => <Header key={item} />}
-      </Static>
-      <Box flexDirection="column" padding={1}>
-        {showProgress && (
+    <Box flexDirection="column" padding={1}>
+      {showHeader && <Header />}
+
+      {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
           <Box marginTop={1}>
@@ -2861,8 +2855,7 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           />
         </Box>
       )}
-      </Box>
-    </>
+    </Box>
   )
 }
 
diff --git a/cli/src/build/onboarding/command.ts b/cli/src/build/onboarding/command.ts
index 5d44577b6e..5aac57b4a1 100644
--- a/cli/src/build/onboarding/command.ts
+++ b/cli/src/build/onboarding/command.ts
@@ -65,6 +65,29 @@ async function resolvePlatform(
   return choice
 }
 
+// ANSI escape codes for the terminal's alternative screen buffer. Running
+// the wizard in alt-screen mode means each Ink frame fully replaces the
+// previous one (no scrollback accumulation), which kills the duplicate-
+// Header artifact at step transitions and lets us conditionally hide the
+// Header on steps that need the full terminal height (`requesting-build`
+// and the scrollable AI viewer).
+//
+// Trade-off: when the wizard exits, the terminal restores to whatever was
+// on screen before — the wizard's output is gone. That's the same behavior
+// as `vim`/`htop`/`less`, and it's the expected UX for a TUI wizard. We
+// print a one-line completion summary AFTER exiting alt screen so the
+// user sees something concrete in their terminal flow.
+const ENTER_ALT_SCREEN = '\x1B[?1049h\x1B[H' // enter buffer + cursor home
+const EXIT_ALT_SCREEN = '\x1B[?1049l'
+
+function enterAltScreen(): void {
+  process.stdout.write(ENTER_ALT_SCREEN)
+}
+
+function exitAltScreen(): void {
+  process.stdout.write(EXIT_ALT_SCREEN)
+}
+
 export async function onboardingBuilderCommand(options: OnboardingBuilderOptions = {}): Promise<void> {
   // Ink requires an interactive terminal — fail fast in CI/pipes
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -95,23 +118,61 @@ export async function onboardingBuilderCommand(options: OnboardingBuilderOptions
 
   const platform = await resolvePlatform(options, iosDir, androidDir)
 
-  if (platform === 'android') {
-    const androidProgress = await loadAndroidProgress(appId)
-    const { waitUntilExit } = render(
-      React.createElement(AndroidOnboardingApp, {
-        appId,
-        initialProgress: androidProgress,
-        androidDir,
-        apikey: options.apikey,
-      }),
-    )
-    await waitUntilExit()
-    return
+  // Defensive cleanup: if the process exits abnormally (uncaught exception,
+  // SIGINT before Ink's own handler fires, etc.) we must restore the user's
+  // normal terminal buffer — otherwise they're stranded in alt-screen mode
+  // with no visible scrollback. Register handlers BEFORE entering alt screen
+  // so any failure between here and the explicit exit still recovers.
+  let altScreenActive = true
+  const cleanupAltScreen = (): void => {
+    if (!altScreenActive)
+      return
+    altScreenActive = false
+    exitAltScreen()
+  }
+  process.once('exit', cleanupAltScreen)
+  process.once('SIGINT', cleanupAltScreen)
+  process.once('SIGTERM', cleanupAltScreen)
+  process.once('uncaughtException', (err) => {
+    cleanupAltScreen()
+    // Re-throw on next tick so Node's default uncaughtException handling
+    // (print stack + exit non-zero) still fires after we've restored the
+    // terminal.
+    setImmediate(() => {
+      throw err
+    })
+  })
+
+  enterAltScreen()
+  try {
+    if (platform === 'android') {
+      const androidProgress = await loadAndroidProgress(appId)
+      const { waitUntilExit } = render(
+        React.createElement(AndroidOnboardingApp, {
+          appId,
+          initialProgress: androidProgress,
+          androidDir,
+          apikey: options.apikey,
+        }),
+      )
+      await waitUntilExit()
+    }
+    else {
+      const progress = await loadProgress(appId)
+      const { waitUntilExit } = render(
+        React.createElement(OnboardingApp, { appId, initialProgress: progress, iosDir, apikey: options.apikey }),
+      )
+      await waitUntilExit()
+    }
+  }
+  finally {
+    cleanupAltScreen()
   }
 
-  const progress = await loadProgress(appId)
-  const { waitUntilExit } = render(
-    React.createElement(OnboardingApp, { appId, initialProgress: progress, iosDir, apikey: options.apikey }),
-  )
-  await waitUntilExit()
+  // Brief summary in the user's normal terminal flow so they have a visible
+  // record that onboarding finished (alt-screen restoration wiped the
+  // wizard's last frame). Written through process.stdout to bypass the
+  // project-wide no-console lint rule — this is a one-shot UX message,
+  // not application logging.
+  process.stdout.write(`\n✔ Capgo onboarding complete for ${appId} (${platform}).\n`)
 }
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 07e3dfd1c1..1509d08cba 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -11,7 +11,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
 import open from 'open'
 // src/build/onboarding/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
@@ -98,11 +98,6 @@ async function runRunnerCommand(runner: string, args: string[]): Promise<{ succe
   })
 }
 
-// Static items passed to Ink's `<Static>` to render the Header exactly once,
-// above the dynamic render area. Using a module-level constant keeps the
-// reference stable across renders so Static doesn't think new items appeared.
-const STATIC_HEADER_ITEMS: string[] = ['header']
-
 const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey }) => {
   const { exit } = useApp()
   const startStep = getResumeStep(initialProgress)
@@ -1421,31 +1416,27 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  // The outer Header is rendered inside `<Static>` below — it's written to
-  // the terminal exactly once and never re-rendered, so the user sees a
-  // single persistent banner across every step (including the AI sub-flow
-  // and its transitions). That eliminates the duplicate-Header artifact
-  // that came from Ink committing each step's frame into scrollback.
+  // Onboarding runs in the terminal's alternative screen buffer (set up in
+  // `onboardingBuilderCommand`), so each Ink frame fully replaces the
+  // previous one — no scrollback accumulation, no duplicate Header artifact
+  // when steps transition. That means `showHeader` can be a normal
+  // step-based conditional: hidden on the steps that need the full
+  // terminal height (`requesting-build` and the scrollable AI viewer),
+  // visible everywhere else INCLUDING the entire AI sub-flow.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null
 
   return (
-    <>
-      {/* Render the Header exactly once via Ink's `<Static>` — see the
-          STATIC_HEADER_ITEMS comment above. The dynamic render area below
-          changes step-by-step but never touches the Header, so resizing the
-          terminal or transitioning between steps cannot produce a duplicate
-          banner in scrollback. */}
-      <Static items={STATIC_HEADER_ITEMS}>
-        {item => <Header key={item} />}
-      </Static>
-      <Box flexDirection="column" padding={1}>
-        {/* Progress bar */}
+    <Box flexDirection="column" padding={1}>
+      {showHeader && <Header />}
+
+      {/* Progress bar */}
       {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
@@ -2863,8 +2854,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           <Newline />
         </Box>
       )}
-      </Box>
-    </>
+    </Box>
   )
 }
 

From e1a2736ca7b5eab169d03492f96b559fb0d7a3e8 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:17:59 +0200
Subject: [PATCH 09/14] Revert "fix(cli): run onboarding in alternative-screen
 mode"

This reverts commit a661967393951abe7e0a19be93668ac80983afcd.
---
 cli/src/build/onboarding/android/ui/app.tsx | 31 ++++---
 cli/src/build/onboarding/command.ts         | 95 ++++-----------------
 cli/src/build/onboarding/ui/app.tsx         | 38 ++++++---
 3 files changed, 60 insertions(+), 104 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index ceadbe152a..aa692475e7 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -20,7 +20,7 @@ import { homedir } from 'node:os'
 import { join, resolve as resolvePath } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
 // src/build/onboarding/android/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { createSupabaseClient, findSavedKey, findSavedKeySilent, getOrganizationId } from '../../../../utils.js'
@@ -126,6 +126,10 @@ function emptyProgress(appId: string): AndroidOnboardingProgress {
   }
 }
 
+// Static items passed to Ink's `<Static>` to render the Header exactly once.
+// See iOS sibling for the rationale.
+const STATIC_HEADER_ITEMS: string[] = ['header']
+
 const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir, apikey }) => {
   const { exit } = useApp()
   const startStep: AndroidOnboardingStep = getAndroidResumeStep(initialProgress)
@@ -1567,22 +1571,24 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  // See iOS sibling: the wizard runs in the terminal's alternative screen
-  // buffer so each Ink frame fully replaces the previous — no scrollback
-  // accumulation, no duplicate Header artifact. `showHeader` can be a plain
-  // step conditional that hides on the steps which need max screen
-  // (`requesting-build` and the scrollable AI viewer).
+  // See iOS sibling: Header is rendered exactly once via `<Static>` below
+  // so a single persistent banner sits above every step (including the AI
+  // sub-flow), with no duplicate-Header artifact when steps transition.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
-    <Box flexDirection="column" padding={1}>
-      {showHeader && <Header />}
-
-      {showProgress && (
+    <>
+      {/* Render the Header exactly once via Ink's `<Static>` — see iOS
+          sibling. The dynamic area below changes step-by-step but the
+          banner stays put. */}
+      <Static items={STATIC_HEADER_ITEMS}>
+        {item => <Header key={item} />}
+      </Static>
+      <Box flexDirection="column" padding={1}>
+        {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
           <Box marginTop={1}>
@@ -2855,7 +2861,8 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           />
         </Box>
       )}
-    </Box>
+      </Box>
+    </>
   )
 }
 
diff --git a/cli/src/build/onboarding/command.ts b/cli/src/build/onboarding/command.ts
index 5aac57b4a1..5d44577b6e 100644
--- a/cli/src/build/onboarding/command.ts
+++ b/cli/src/build/onboarding/command.ts
@@ -65,29 +65,6 @@ async function resolvePlatform(
   return choice
 }
 
-// ANSI escape codes for the terminal's alternative screen buffer. Running
-// the wizard in alt-screen mode means each Ink frame fully replaces the
-// previous one (no scrollback accumulation), which kills the duplicate-
-// Header artifact at step transitions and lets us conditionally hide the
-// Header on steps that need the full terminal height (`requesting-build`
-// and the scrollable AI viewer).
-//
-// Trade-off: when the wizard exits, the terminal restores to whatever was
-// on screen before — the wizard's output is gone. That's the same behavior
-// as `vim`/`htop`/`less`, and it's the expected UX for a TUI wizard. We
-// print a one-line completion summary AFTER exiting alt screen so the
-// user sees something concrete in their terminal flow.
-const ENTER_ALT_SCREEN = '\x1B[?1049h\x1B[H' // enter buffer + cursor home
-const EXIT_ALT_SCREEN = '\x1B[?1049l'
-
-function enterAltScreen(): void {
-  process.stdout.write(ENTER_ALT_SCREEN)
-}
-
-function exitAltScreen(): void {
-  process.stdout.write(EXIT_ALT_SCREEN)
-}
-
 export async function onboardingBuilderCommand(options: OnboardingBuilderOptions = {}): Promise<void> {
   // Ink requires an interactive terminal — fail fast in CI/pipes
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -118,61 +95,23 @@ export async function onboardingBuilderCommand(options: OnboardingBuilderOptions
 
   const platform = await resolvePlatform(options, iosDir, androidDir)
 
-  // Defensive cleanup: if the process exits abnormally (uncaught exception,
-  // SIGINT before Ink's own handler fires, etc.) we must restore the user's
-  // normal terminal buffer — otherwise they're stranded in alt-screen mode
-  // with no visible scrollback. Register handlers BEFORE entering alt screen
-  // so any failure between here and the explicit exit still recovers.
-  let altScreenActive = true
-  const cleanupAltScreen = (): void => {
-    if (!altScreenActive)
-      return
-    altScreenActive = false
-    exitAltScreen()
-  }
-  process.once('exit', cleanupAltScreen)
-  process.once('SIGINT', cleanupAltScreen)
-  process.once('SIGTERM', cleanupAltScreen)
-  process.once('uncaughtException', (err) => {
-    cleanupAltScreen()
-    // Re-throw on next tick so Node's default uncaughtException handling
-    // (print stack + exit non-zero) still fires after we've restored the
-    // terminal.
-    setImmediate(() => {
-      throw err
-    })
-  })
-
-  enterAltScreen()
-  try {
-    if (platform === 'android') {
-      const androidProgress = await loadAndroidProgress(appId)
-      const { waitUntilExit } = render(
-        React.createElement(AndroidOnboardingApp, {
-          appId,
-          initialProgress: androidProgress,
-          androidDir,
-          apikey: options.apikey,
-        }),
-      )
-      await waitUntilExit()
-    }
-    else {
-      const progress = await loadProgress(appId)
-      const { waitUntilExit } = render(
-        React.createElement(OnboardingApp, { appId, initialProgress: progress, iosDir, apikey: options.apikey }),
-      )
-      await waitUntilExit()
-    }
-  }
-  finally {
-    cleanupAltScreen()
+  if (platform === 'android') {
+    const androidProgress = await loadAndroidProgress(appId)
+    const { waitUntilExit } = render(
+      React.createElement(AndroidOnboardingApp, {
+        appId,
+        initialProgress: androidProgress,
+        androidDir,
+        apikey: options.apikey,
+      }),
+    )
+    await waitUntilExit()
+    return
   }
 
-  // Brief summary in the user's normal terminal flow so they have a visible
-  // record that onboarding finished (alt-screen restoration wiped the
-  // wizard's last frame). Written through process.stdout to bypass the
-  // project-wide no-console lint rule — this is a one-shot UX message,
-  // not application logging.
-  process.stdout.write(`\n✔ Capgo onboarding complete for ${appId} (${platform}).\n`)
+  const progress = await loadProgress(appId)
+  const { waitUntilExit } = render(
+    React.createElement(OnboardingApp, { appId, initialProgress: progress, iosDir, apikey: options.apikey }),
+  )
+  await waitUntilExit()
 }
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 1509d08cba..07e3dfd1c1 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -11,7 +11,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
 import open from 'open'
 // src/build/onboarding/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
@@ -98,6 +98,11 @@ async function runRunnerCommand(runner: string, args: string[]): Promise<{ succe
   })
 }
 
+// Static items passed to Ink's `<Static>` to render the Header exactly once,
+// above the dynamic render area. Using a module-level constant keeps the
+// reference stable across renders so Static doesn't think new items appeared.
+const STATIC_HEADER_ITEMS: string[] = ['header']
+
 const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey }) => {
   const { exit } = useApp()
   const startStep = getResumeStep(initialProgress)
@@ -1416,27 +1421,31 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  // Onboarding runs in the terminal's alternative screen buffer (set up in
-  // `onboardingBuilderCommand`), so each Ink frame fully replaces the
-  // previous one — no scrollback accumulation, no duplicate Header artifact
-  // when steps transition. That means `showHeader` can be a normal
-  // step-based conditional: hidden on the steps that need the full
-  // terminal height (`requesting-build` and the scrollable AI viewer),
-  // visible everywhere else INCLUDING the entire AI sub-flow.
+  // The outer Header is rendered inside `<Static>` below — it's written to
+  // the terminal exactly once and never re-rendered, so the user sees a
+  // single persistent banner across every step (including the AI sub-flow
+  // and its transitions). That eliminates the duplicate-Header artifact
+  // that came from Ink committing each step's frame into scrollback.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
-  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
     ? getBuildOnboardingRecoveryAdvice(error, retryStep, pm.runner, appId)
     : null
 
   return (
-    <Box flexDirection="column" padding={1}>
-      {showHeader && <Header />}
-
-      {/* Progress bar */}
+    <>
+      {/* Render the Header exactly once via Ink's `<Static>` — see the
+          STATIC_HEADER_ITEMS comment above. The dynamic render area below
+          changes step-by-step but never touches the Header, so resizing the
+          terminal or transitioning between steps cannot produce a duplicate
+          banner in scrollback. */}
+      <Static items={STATIC_HEADER_ITEMS}>
+        {item => <Header key={item} />}
+      </Static>
+      <Box flexDirection="column" padding={1}>
+        {/* Progress bar */}
       {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
@@ -2854,7 +2863,8 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           <Newline />
         </Box>
       )}
-    </Box>
+      </Box>
+    </>
   )
 }
 

From a0e2b78b8f4ce4aea538a430cbeb5bcc6be59798 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:22:36 +0200
Subject: [PATCH 10/14] fix(cli): shrink onboarding Header to a 2-row banner
 (Static)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Static-Header approach kept the banner visible across every step
(including the entire AI sub-flow), with no duplicate-banner artifact at
step transitions and no need for alt-screen mode. The remaining gripe
was the row cost on `requesting-build` and the scrollable AI viewer —
the double-bordered box was 4-5 rows tall, eating real estate where
vertical space matters.

This change replaces the bordered box with a compact two-row banner:

  🚀  Capgo Cloud Build · Onboarding
  ────────────────────────────────

A single bold line + a thin dim divider gives the same "I'm in the Capgo
wizard" anchoring at one third of the row cost. Heavy steps now lose
~2 rows instead of ~4-5.

No code changes outside `components.tsx` — `<Static>` and the call sites
already render whatever the Header component returns.
---
 cli/src/build/onboarding/ui/components.tsx | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index 80da7dd196..b801e2f640 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -86,17 +86,20 @@ export const FilteredTextInput: FC<{
   )
 }
 
+// Compact two-row banner rendered exactly once (via <Static>) at the top of
+// the wizard. The previous double-bordered box was 4-5 rows tall; that cost
+// was visible on `requesting-build` and the scrollable AI viewer, where
+// vertical space matters. A single bold line + a thin divider gives the
+// same "I'm in the Capgo wizard" anchoring at one third of the row cost,
+// without any borders that compete with step-level chrome below.
 export const Header: FC = () => (
-  <Box
-    borderStyle="double"
-    borderColor="cyan"
-    paddingX={4}
-    paddingY={1}
-    alignSelf="center"
-  >
+  <Box flexDirection="column">
     <Text bold color="cyan">
       🚀  Capgo Cloud Build · Onboarding
     </Text>
+    <Text color="cyan" dimColor>
+      {'─'.repeat(60)}
+    </Text>
   </Box>
 )
 

From ec1fb8aad2508f610a47c6840f045607bd9b8daf Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:31:20 +0200
Subject: [PATCH 11/14] =?UTF-8?q?fix(cli):=20drop=20Static=20=E2=80=94=20r?=
 =?UTF-8?q?ender=20Header=20conditionally=20in=20the=20dynamic=20area?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Static was rejected by the user. Restoring conditional Header rendering:

- `showHeader = step !== 'requesting-build' && !isAiResultScroll`
- Header is shown on every interactive step including the full AI
  sub-flow (prompt → running → result), giving the user the "Capgo
  Cloud Build · Onboarding" anchoring they explicitly asked for on the
  AI running step.
- Header is hidden on `requesting-build` and on the scrollable AI
  viewer so those steps get the full terminal height as before.

The Header itself stays in its compact two-row form (bold line + thin
divider) introduced earlier — when visible it only costs ~2 rows, and
when hidden the user gets the full screen on heavy steps.

Static is gone from both `ui/app.tsx` files: no more `<Static>` wrapper,
no `STATIC_HEADER_ITEMS` constant, and the `Static` symbol is dropped
from the `ink` import.

Trade-off acknowledged in earlier reviews: if Ink's render diff hits a
size-change edge case (e.g. terminal narrow enough that the prompt
frame scrolls), the previous frame's content can persist in the user's
scrollback. We're accepting that artifact rather than going back to
Static or to alternative-screen mode, both of which the user has
explicitly rejected.
---
 cli/src/build/onboarding/android/ui/app.tsx | 28 ++++++-----------
 cli/src/build/onboarding/ui/app.tsx         | 33 +++++++--------------
 2 files changed, 19 insertions(+), 42 deletions(-)

diff --git a/cli/src/build/onboarding/android/ui/app.tsx b/cli/src/build/onboarding/android/ui/app.tsx
index aa692475e7..22ac8a84e3 100644
--- a/cli/src/build/onboarding/android/ui/app.tsx
+++ b/cli/src/build/onboarding/android/ui/app.tsx
@@ -20,7 +20,7 @@ import { homedir } from 'node:os'
 import { join, resolve as resolvePath } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
 // src/build/onboarding/android/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import { createSupabaseClient, findSavedKey, findSavedKeySilent, getOrganizationId } from '../../../../utils.js'
@@ -126,10 +126,6 @@ function emptyProgress(appId: string): AndroidOnboardingProgress {
   }
 }
 
-// Static items passed to Ink's `<Static>` to render the Header exactly once.
-// See iOS sibling for the rationale.
-const STATIC_HEADER_ITEMS: string[] = ['header']
-
 const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir, apikey }) => {
   const { exit } = useApp()
   const startStep: AndroidOnboardingStep = getAndroidResumeStep(initialProgress)
@@ -1571,24 +1567,19 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
 
   const progressPct = ANDROID_STEP_PROGRESS[step] ?? 0
   const phaseLabel = getAndroidPhaseLabel(step)
-  // See iOS sibling: Header is rendered exactly once via `<Static>` below
-  // so a single persistent banner sits above every step (including the AI
-  // sub-flow), with no duplicate-Header artifact when steps transition.
+  // See iOS sibling: conditional Header, visible on every interactive step
+  // including the AI sub-flow, hidden on `requesting-build` and on the
+  // scrollable AI viewer so those get the full terminal height.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
 
   return (
-    <>
-      {/* Render the Header exactly once via Ink's `<Static>` — see iOS
-          sibling. The dynamic area below changes step-by-step but the
-          banner stays put. */}
-      <Static items={STATIC_HEADER_ITEMS}>
-        {item => <Header key={item} />}
-      </Static>
-      <Box flexDirection="column" padding={1}>
-        {showProgress && (
+    <Box flexDirection="column" padding={1}>
+      {showHeader && <Header />}
+      {showProgress && (
         <Box flexDirection="column" marginTop={1}>
           <Text bold color="cyan">{phaseLabel}</Text>
           <Box marginTop={1}>
@@ -2861,8 +2852,7 @@ const AndroidOnboardingApp: FC<AppProps> = ({ appId, initialProgress, androidDir
           />
         </Box>
       )}
-      </Box>
-    </>
+    </Box>
   )
 }
 
diff --git a/cli/src/build/onboarding/ui/app.tsx b/cli/src/build/onboarding/ui/app.tsx
index 07e3dfd1c1..4f6f6181a7 100644
--- a/cli/src/build/onboarding/ui/app.tsx
+++ b/cli/src/build/onboarding/ui/app.tsx
@@ -11,7 +11,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
 import { Alert, ProgressBar, Select } from '@inkjs/ui'
-import { Box, Newline, Static, Text, useApp, useInput, useStdout } from 'ink'
+import { Box, Newline, Text, useApp, useInput, useStdout } from 'ink'
 import open from 'open'
 // src/build/onboarding/ui/app.tsx
 import React, { useCallback, useEffect, useRef, useState } from 'react'
@@ -98,11 +98,6 @@ async function runRunnerCommand(runner: string, args: string[]): Promise<{ succe
   })
 }
 
-// Static items passed to Ink's `<Static>` to render the Header exactly once,
-// above the dynamic render area. Using a module-level constant keeps the
-// reference stable across renders so Static doesn't think new items appeared.
-const STATIC_HEADER_ITEMS: string[] = ['header']
-
 const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey }) => {
   const { exit } = useApp()
   const startStep = getResumeStep(initialProgress)
@@ -1421,13 +1416,14 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
 
   const progress = STEP_PROGRESS[step] ?? 0
   const phaseLabel = getPhaseLabel(step)
-  // The outer Header is rendered inside `<Static>` below — it's written to
-  // the terminal exactly once and never re-rendered, so the user sees a
-  // single persistent banner across every step (including the AI sub-flow
-  // and its transitions). That eliminates the duplicate-Header artifact
-  // that came from Ink committing each step's frame into scrollback.
+  // Header is rendered as a normal conditional. Visible on every interactive
+  // step including the AI sub-flow; hidden on `requesting-build` (build
+  // output needs the full viewport) and on the scrollable AI viewer (same
+  // reason). The Header itself is now a compact two-row banner so even when
+  // visible it only costs a couple of rows.
   const isAiResultScroll = step === 'ai-analysis-result-scroll'
   const isAiStep = step === 'ai-analysis-prompt' || step === 'ai-analysis-running' || step === 'ai-analysis-result' || isAiResultScroll
+  const showHeader = step !== 'requesting-build' && !isAiResultScroll
   const showProgress = step !== 'welcome' && step !== 'platform-select' && step !== 'adding-platform' && step !== 'no-platform' && step !== 'error' && step !== 'build-complete' && step !== 'requesting-build' && step !== 'ai-analysis-result' && !isAiResultScroll
   const showLog = step !== 'requesting-build' && step !== 'build-complete' && !isAiStep
   const recoveryAdvice = error
@@ -1435,16 +1431,8 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
     : null
 
   return (
-    <>
-      {/* Render the Header exactly once via Ink's `<Static>` — see the
-          STATIC_HEADER_ITEMS comment above. The dynamic render area below
-          changes step-by-step but never touches the Header, so resizing the
-          terminal or transitioning between steps cannot produce a duplicate
-          banner in scrollback. */}
-      <Static items={STATIC_HEADER_ITEMS}>
-        {item => <Header key={item} />}
-      </Static>
-      <Box flexDirection="column" padding={1}>
+    <Box flexDirection="column" padding={1}>
+      {showHeader && <Header />}
         {/* Progress bar */}
       {showProgress && (
         <Box flexDirection="column" marginTop={1}>
@@ -2863,8 +2851,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir, apikey })
           <Newline />
         </Box>
       )}
-      </Box>
-    </>
+    </Box>
   )
 }
 

From 2581e35971afae5d419146f86dcaea032c0ff439 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:34:33 +0200
Subject: [PATCH 12/14] fix(cli): restore bordered double-border Header banner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The compact two-row variant was introduced solely to reduce the row cost when the Header was always visible (via Static). Now that Header is conditional again and hidden on heavy steps (requesting-build, scroll viewer), the original double-bordered banner is back — same visual identity as the rest of the wizard.
---
 cli/src/build/onboarding/ui/components.tsx | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index b801e2f640..80da7dd196 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -86,20 +86,17 @@ export const FilteredTextInput: FC<{
   )
 }
 
-// Compact two-row banner rendered exactly once (via <Static>) at the top of
-// the wizard. The previous double-bordered box was 4-5 rows tall; that cost
-// was visible on `requesting-build` and the scrollable AI viewer, where
-// vertical space matters. A single bold line + a thin divider gives the
-// same "I'm in the Capgo wizard" anchoring at one third of the row cost,
-// without any borders that compete with step-level chrome below.
 export const Header: FC = () => (
-  <Box flexDirection="column">
+  <Box
+    borderStyle="double"
+    borderColor="cyan"
+    paddingX={4}
+    paddingY={1}
+    alignSelf="center"
+  >
     <Text bold color="cyan">
       🚀  Capgo Cloud Build · Onboarding
     </Text>
-    <Text color="cyan" dimColor>
-      {'─'.repeat(60)}
-    </Text>
   </Box>
 )
 

From 66eb68b53ea14eb22b11574844967c59a9ad80e3 Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 16:40:32 +0200
Subject: [PATCH 13/14] fix(cli): keep AI viewer frame height constant so
 scrolling stays in-place
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scrollable AI viewer's content area used `pickVisibleLines`, which
greedily packs logical lines into `viewportRows` rendered rows but stops
short if the next line would overflow. That means the visible content's
rendered row count is variable: scrolling can pick lines whose wrap
totals are different from the previous slice. Each render then has a
slightly different total height.

Ink renders in normal-terminal mode, so a 1-row height change between
renders writes the new frame below the old one and the user perceives
"scrolling just added an extra line at the bottom" — the previous frame
stays in scrollback right above the new one.

Fix: after picking the visible lines, compute how many rendered rows
they actually used (`totalRenderedRows`) and pad with empty <Text> rows
to fill the remainder of `viewportRows`. The viewer's chrome was already
constant; padding the body makes the WHOLE frame constant, so Ink's
diff replaces the previous frame in-place on every scroll keystroke.

Added `totalRenderedRows` to `ai-fit.ts` (sum of `renderedRowsForLine`
across an array of lines) as a small shared helper. All 22 existing
fit tests still pass.
---
 cli/src/build/onboarding/ai-fit.ts         | 15 +++++++++++++++
 cli/src/build/onboarding/ui/components.tsx | 13 ++++++++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/cli/src/build/onboarding/ai-fit.ts b/cli/src/build/onboarding/ai-fit.ts
index 7a87d220a7..5d88d8eed7 100644
--- a/cli/src/build/onboarding/ai-fit.ts
+++ b/cli/src/build/onboarding/ai-fit.ts
@@ -83,6 +83,21 @@ function renderedRowsForLine(line: string, terminalCols: number): number {
   return Math.max(1, Math.ceil(visibleLen / cols))
 }
 
+/**
+ * Sum of rendered rows for a list of logical lines.
+ *
+ * Used by the scrollable viewer to figure out how many padding rows to
+ * add below the visible content so the frame height stays constant across
+ * scroll positions (constant height = Ink renders in-place, no scrollback
+ * growth on every keystroke).
+ */
+export function totalRenderedRows(lines: string[], terminalCols: number): number {
+  let total = 0
+  for (const line of lines)
+    total += renderedRowsForLine(line, terminalCols)
+  return total
+}
+
 /**
  * Pick the slice of `lines` starting at `scrollOffset` that fits within
  * `viewportRows` *rendered* rows on a terminal `terminalCols` wide. Returns
diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index 80da7dd196..0ce6c46bab 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -3,7 +3,7 @@ import { Box, Text, useInput, useStdout } from 'ink'
 import Spinner from 'ink-spinner'
 // src/build/onboarding/ui/components.tsx
 import React, { useEffect, useState } from 'react'
-import { computeMaxScrollOffset, pickVisibleLines } from '../ai-fit.js'
+import { computeMaxScrollOffset, pickVisibleLines, totalRenderedRows } from '../ai-fit.js'
 
 export const Divider: FC<{ width?: number }> = ({ width = 60 }) => (
   <Text dimColor>{'─'.repeat(width)}</Text>
@@ -211,6 +211,14 @@ export const FullscreenAiViewer: FC<{
   // wrap on narrow terminals (which would silently eat a viewport row).
   const dividerWidth = Math.max(10, Math.min(60, dims.cols - 1))
 
+  // Pad the content area with empty rows so the viewer's total frame height
+  // is CONSTANT across scroll positions. Without this, scrolling can change
+  // the frame height by ±1 row when lines with different wrap counts move in
+  // and out of view — Ink then writes the new (taller) frame BELOW the old
+  // one and the user perceives "scrolling just added an extra line".
+  const visibleRowsUsed = totalRenderedRows(visibleLines, dims.cols)
+  const padRows = Math.max(0, viewportRows - visibleRowsUsed)
+
   return (
     <Box flexDirection="column">
       <Text bold color="cyan">{title}</Text>
@@ -219,6 +227,9 @@ export const FullscreenAiViewer: FC<{
       {visibleLines.map((line, index) => (
         <Text key={`ai-line-${scrollOffset + index}`}>{line}</Text>
       ))}
+      {Array.from({ length: padRows }).map((_, i) => (
+        <Text key={`ai-pad-${i}`}>{' '}</Text>
+      ))}
       <Text color="cyan">{'─'.repeat(dividerWidth)}</Text>
       <Text dimColor>
         {`Showing ${firstVisibleLine}-${lastVisibleLine} of ${total} lines. ↑/↓ or PgUp/PgDn to scroll.`}

From 385633c443ae0881af02af955e868c989009edaa Mon Sep 17 00:00:00 2001
From: WcaleNieWolny <isupermichael007@gmail.com>
Date: Fri, 22 May 2026 17:20:34 +0200
Subject: [PATCH 14/14] fix(cli): suppress scroll hints in AI viewer when all
 lines fit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`isAiAnalysisTooTall` is deliberately conservative — it routes the
analysis through the scrollable viewer whenever the estimate is close
to the chrome-adjusted row budget. In practice that means we sometimes
end up in the viewer with an analysis that fits the viewport outright:
`maxScrollOffset === 0`, every logical line visible at once, no
scrolling possible.

Previously the chrome still advertised scrolling in that case:

- Subtitle: "15 lines — scrollable because the analysis is taller than
  your terminal"  (← lie when all 15 fit)
- Footer:   "Showing 1-15 of 15 lines. ↑/↓ or PgUp/PgDn to scroll."
            (← pointless when there's nothing to scroll past)

Now those strings are conditional on `maxScrollOffset > 0`:

- Subtitle is omitted when scrolling would be a no-op (its only job
  was the "scrollable" advisory, which doesn't apply).
- Footer reads "Showing all N lines." instead.
- Exit hint collapses to the "Press Esc or Enter to continue to the
  retry/skip prompt." variant — the "when done" wording only makes
  sense if there's something the user is "done with".

No behavior change when scrolling IS needed; only the false-positive
copy is suppressed.
---
 cli/src/build/onboarding/ui/components.tsx | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/cli/src/build/onboarding/ui/components.tsx b/cli/src/build/onboarding/ui/components.tsx
index 0ce6c46bab..918df00ea1 100644
--- a/cli/src/build/onboarding/ui/components.tsx
+++ b/cli/src/build/onboarding/ui/components.tsx
@@ -219,10 +219,18 @@ export const FullscreenAiViewer: FC<{
   const visibleRowsUsed = totalRenderedRows(visibleLines, dims.cols)
   const padRows = Math.max(0, viewportRows - visibleRowsUsed)
 
+  // Suppress every scroll-related hint when the analysis fits the viewport
+  // outright. The conservative `isAiAnalysisTooTall` estimator in the parent
+  // sometimes routes us here even though `pickVisibleLines` ends up showing
+  // every logical line — telling the user to "↑/↓ to scroll" when scrolling
+  // is a no-op is just noise. The subtitle is also suppressed in that case
+  // because its only job is to advertise "this is scrollable".
+  const hasMoreToScroll = maxScrollOffset > 0
+
   return (
     <Box flexDirection="column">
       <Text bold color="cyan">{title}</Text>
-      {subtitle && <Text dimColor>{subtitle}</Text>}
+      {subtitle && hasMoreToScroll && <Text dimColor>{subtitle}</Text>}
       <Text color="cyan">{'─'.repeat(dividerWidth)}</Text>
       {visibleLines.map((line, index) => (
         <Text key={`ai-line-${scrollOffset + index}`}>{line}</Text>
@@ -232,12 +240,14 @@ export const FullscreenAiViewer: FC<{
       ))}
       <Text color="cyan">{'─'.repeat(dividerWidth)}</Text>
       <Text dimColor>
-        {`Showing ${firstVisibleLine}-${lastVisibleLine} of ${total} lines. ↑/↓ or PgUp/PgDn to scroll.`}
+        {hasMoreToScroll
+          ? `Showing ${firstVisibleLine}-${lastVisibleLine} of ${total} lines. ↑/↓ or PgUp/PgDn to scroll.`
+          : `Showing all ${total} lines.`}
       </Text>
       <Text color="yellow" bold>
-        {atBottom
-          ? 'Press Esc or Enter to continue to the retry/skip prompt.'
-          : 'Press Esc or Enter when done to continue.'}
+        {hasMoreToScroll && !atBottom
+          ? 'Press Esc or Enter when done to continue.'
+          : 'Press Esc or Enter to continue to the retry/skip prompt.'}
       </Text>
     </Box>
   )