Unified multi-engine onboarding: "Get Michael ready" should install, validate and sign in to whichever engine the owner picks — not only Claude

Start with src/shared/engineSetup.ts and src/shared/agentProvider.ts to trace the current setup contract and provider presets, then follow the onboarding wizard and officeBreak paths named in the issue. The work spans credential validation, engine choice, and provider-specific rate-limit handling; check the related tests for those flows. Done means onboarding can choose and validate a configured provider and rate limits pause gracefully for supported providers.

Problem / motivation

The codebase already carries fully wired presets for 12 non-Claude providers (agentProvider.ts L24–37), complete with hook bridges, auto-mode flags, resume strategies, and install commands. Flipping BUILD_ENGINES from ['claude'] to ['claude', 'codex', 'gemini'] (L173) and toggling SHOW_ENGINE_PICKER to true (buildFeatures.ts L149) is supposed to be all it takes — but the "Get Michael ready" onboarding wizard immediately breaks, because:

1. engineSetup.ts is hard-wired to Claude. EngineSetupStatus.applies is documented as "False for an engine this step does not set up (anything but Claude)". The status probes claude auth status, the sign-in method is 'account' | 'apiKey' (both Anthropic-specific), and the phase machine ('installing' | 'signin' | 'browser') maps only to Claude's OAuth-browser flow. A Codex owner needs an OPENAI_API_KEY; a Gemini owner needs gcloud auth login or a Google API key. Neither has a validation step.

2. No credential validation for non-Claude engines. Claude's setup verifies installation and sign-in before letting Michael start (engineSetupNeeded at L32). For Codex, the app can detect the binary (engine:codex in the tool catalog) but cannot check whether the user has authenticated — so Michael spawns, the first API call fails with 401 Unauthorized, and the owner sees a cryptic CLI error inside a terminal they were told is autonomous.

3. Rate-limit and plan-exhaustion handling is Claude-only. officeBreak recognizes StopFailure rate_limit from Claude's lifecycle. OpenAI returns HTTP 429 with x-ratelimit-* headers, Google returns RESOURCE_EXHAUSTED, and xAI has its own shape. When BUILD_ENGINES is expanded, an office running Codex hits its rate limit and Michael just dies silently instead of pausing gracefully.

4. The onboarding wizard has no engine chooser UX. Even with SHOW_ENGINE_PICKER = true, the setup wizard's "Get Michael ready" step has no visual affordance for picking an engine and validating its credentials. The engine picker only exists inside the Add Agent finalize step — after onboarding is already done.

This is what blocks the product from supporting "other popular platforms such as Codex, Gemini" end-to-end. The presets are wired, the bridges are built, but the front door — onboarding — only opens for Claude.

Proposed solution

1. Generalize EngineSetupStatus to a per-provider credential contract

Replace the Claude-specific method: 'account' | 'apiKey' with a discriminated union:

export type EngineCredentialMethod =
  | { kind: 'claude-account' }                        // claude auth login (browser OAuth)
  | { kind: 'api-key'; envVar: string; label: string } // OPENAI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY
  | { kind: 'cli-login'; command: string }             // gcloud auth login, codex auth
  | { kind: 'none' };                                  // local / OSS models (qwen, crush w/ local LLM)

Each preset in agentProvider.ts declares its credentialMethod alongside the existing installCommand. engineSetup.ts becomes generic:

• applies is true for whatever provider the owner picked (from BUILD_ENGINES).
• installed comes from the existing tool-catalog binary probe.
• signedIn dispatches on credentialMethod.kind: run claude auth status for Claude, check process.env.OPENAI_API_KEY presence for Codex, run gemini auth status for Gemini CLI, etc.

2. Add an engine-choice step to the onboarding wizard

Between the Welcome step and the current "Get Michael ready" step, add an "Choose your AI engine" step that:

• Shows every provider in BUILD_ENGINES with its availability badge (already computed by classifyEngineAvailability).
• Lets the owner pick one. The selection writes config.defaultEngine.
• The "Get Michael ready" step then adapts its install/sign-in rows to that provider's credentialMethod.

3. Per-provider rate-limit recognition in officeBreak

Add a rateLimitSignal field to AgentProviderPreset:

rateLimitSignal?: {
  /** The lifecycle event field to match. */
  match: (event: HookEvent) => boolean;
  /** User-facing message for the pause card. */
  message: string;
};

Claude's existing StopFailure rate_limit moves into its preset. Codex gets event.error?.code === 'rate_limit_exceeded'. Gemini gets RESOURCE_EXHAUSTED. The officeBreak module dispatches on the preset instead of hard-coding Claude.

4. Scope

In scope	Out of scope
engineSetup.ts generalization	Provider-neutral policy compiler (#48)
Onboarding engine chooser UX	Cross-engine conformance tests (#83)
Per-provider credential validation	Engine-agnostic background task runner (#176)
Rate-limit normalization in officeBreak	Adding providers to BUILD_ENGINES itself (#222)
Tests for each credential method	Hook bridge verification for unverified providers

This is the plumbing that makes #222 (adding providers to setup) actually work end-to-end. #222 proposes the user-facing idea; this issue defines the engine-setup machinery underneath.

Screenshot, mockup or recording

See below — annotated screenshot of the "Get Michael ready" setup screen today, showing the gap where non-Claude engine rows should appear.

Alternatives considered

1. Keep engineSetup.ts Claude-only and just expand BUILD_ENGINES. This is what happens if someone flips the flag today. Michael's onboarding step says applies: false, skips credential validation, and the owner hits auth failures at runtime. The missing-CLI install ladder (cliInstall.ts) handles installation but not authentication, so half the problem remains.

2. Move all credential checks into cliInstall.ts (the install ladder). The ladder runs inside the agent's PTY, which means the owner sees a terminal command running. For Claude this works (browser OAuth is visual). For an API key it doesn't — there is no terminal command that reads a key from the user and writes it to the right env file; the key must come from the settings UI. The credential contract belongs in the setup wizard, not the terminal.

3. Per-provider standalone setup modules (e.g. codexSetup.ts, geminiSetup.ts). More isolated, but adds N files where one generic contract + N entries in the preset table achieves the same coverage. The existing pattern (providerAutomation.ts's total Record<AgentProvider, …>) already proves the table approach works and catches new providers at compile time.

Area

Setup / onboarding

Pre-flight

• I attached a screenshot, mockup or recording above.
• I searched existing issues and discussions, and this isn't a duplicate.

Not a duplicate of:

• #222 ("Add support for other AI agent providers in setup"): proposes the user-facing provider choice. This issue defines the engine-setup machinery (credential validation, rate-limit normalization, onboarding wizard generalization) that #222 needs underneath.
• #142 ("Multi-Provider Agent Architecture with Graceful Fallback"): proposes runtime fallback between providers. This issue is about first-run onboarding, not runtime fallback.
• #176 ("engine-agnostic background task runner"): about scheduled background tasks. This issue is about the onboarding wizard and credential validation.
• #83 ("Cross-Engine Compatibility and Cross-Platform Conformance Tests"): about test coverage. This issue is about production code changes to engineSetup.ts and officeBreak.ts.
• #129 ("Keep working through a plan limit"): about mid-session engine handoff when a plan is exhausted. This issue's rate-limit work is about recognizing the limit signal per provider, not about switching to another provider.