fix(onboarding): inline input at every step + agent-neutral multi-provider wizard

[simple-agent-manager]

Summary

The onboarding "Choose-Your-Path" wizard had no-op steps that collected nothing and was structurally Claude-locked. A user reached the OAuth step and got no field to enter a token — the step just advanced. Root cause: ai-oauth, ai-sam, and cloud-sam steps were no-ops; the only OAuth step was gated on a has-claude tag, making non-Anthropic OAuth (Codex) and the 4 non-major agents unreachable.

This PR makes every step collect AND persist real input inline, and makes the wizard fully agent-neutral:

• Explicit agent-selection step — all 6 AGENT_CATALOG agents selectable; per-agent auth methods driven by catalog/capabilities (api-key all; oauth-token only oauthSupport agents = claude-code/openai-codex; sam only proxy-supported = claude-code/openai-codex).
• OAuth inline — saveAgentCredential({ credentialKind: 'oauth-token', autoActivate: true }) (literal 'oauth-token'). Reuses the setup-token password field + Codex auth.json textarea widgets.
• SAM-managed AI inline — persists providerMode:'sam' via saveAgentSettings AND collects budget inline (daily input/output token limits + monthly cost cap → PUT /api/usage/ai/budget).
• Cloud Hetzner/Scaleway toggle — keeps the inline Hetzner token step; adds an inline Scaleway step (secretKey + projectId). No GCP (multi-step WIF/OAuth — left to Settings).
• Path-generation logic de-Claude-ified — has-claude OAuth gate replaced with a generic per-agent oauthSupport capability check; all copy made provider-neutral.
• Completion dead-end fixed — project step now calls markStepDone → onComplete → CompletionScreen ("You're all set!"), no spurious navigation.
• Inert tags / dead branches removed (openai-key, has-api-key, no-ai, has-hetzner, no-cloud, sam-infra).

Validation

• pnpm lint — 0 errors (pre-existing warnings only)
• pnpm typecheck — clean
• pnpm test — 2432 web tests pass (85 onboarding unit tests across 6 files)
• Additional validation run (if applicable) — 8 Playwright inline-audit tests pass at 375px + 1280px

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging run 28245891076 conclusion=success on onboarding-inline-multi-agent
• Live app verified via Playwright — logged into app.sammy.party via POST /api/auth/token-login (200), drove the wizard live
• Existing workflows confirmed working — dashboard, settings, projects all load; no horizontal overflow; no new console errors
• New feature/fix verified on staging — wizard appears at /dashboard?onboarding; two-question tree works; Start setup → cloud-byoc step renders #onboarding-hetzner-token inline; Scaleway toggle reveals #onboarding-scaleway-secret + #onboarding-scaleway-project inline at both 375px and 1280px
• Infrastructure verification completed — N/A: no infra changes (no cloud-init / VM agent / DNS / TLS / deploy-script paths touched)
• Mobile and desktop verification notes added for UI changes — verified at 375px (iPhone SE) and 1280px (desktop); no overflow at either

Staging Verification Evidence

Authenticated via token-login (200), then drove the live wizard on app.sammy.party:

• Wizard renders, cloud question (I have Hetzner or Scaleway) and repo question (Yes, I have a repo) answerable, Start setup advances to execution.
• cloud-byoc step renders the Hetzner token field inline against the real backend — the previously-inert cloud step now collects input.
• Scaleway provider toggle works live: #onboarding-scaleway-secret + #onboarding-scaleway-project appear, no overflow at 375px or 1280px.
• The ai-setup/OAuth agent grid was filtered out of the executable list on staging because the primary test user already has an active agent credential (correct path-generator behavior — ai-setup becomes optional). That surface is fully covered by the 8 local Playwright audits (existingAgent:false) and the StepExecution render unit tests.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed — agent/auth/cloud toggle groups use role="group" + aria-labelledby (orphaned <label> fixed); Codex auth.json textarea spellCheck={false}
• Shared UI components used or exception documented — reuses Settings setup-token / Codex auth.json input patterns
• Playwright visual audit run locally — mobile (375x667) + desktop (1280x800); no horizontal overflow; screenshots captured before any secret fill() so no secret value is written to disk (onboarding-inline-audit.spec.ts)

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. User picks an agent → StepForm.tsx agent grid (role="group") sets StepFormState.selectedAgent
2. authMethodsForAgent(agentId) (step-actions.ts) → renders only supported auth toggles (api-key / oauth-token / sam)
3. User enters credential → StepExecution.tsx collects into form state →
   • api-key/oauth-token: executeStep() → saveAgentCredential({ agentType, credentialKind, credential, autoActivate: true }) (step-actions.ts)
   • sam: saveAgentSettings({ providerMode: 'sam' }) + buildBudgetRequest() → updateUserAiBudget() (PUT /api/usage/ai/budget)
4. Cloud step → createCredential({ provider: 'hetzner'|'scaleway', ... })
5. Project step → createProject() → markStepDone() → onComplete() → ChoosePathWizard setPhase('complete') → CompletionScreen

Untested Gaps

The ai-setup/OAuth agent grid path is not reachable on the staging primary user (already has an agent credential, so the step is correctly optional/filtered). It is covered by: 8 local Playwright real-browser audits with existingAgent:false mock (asserts the OAuth #onboarding-oauth-token field renders — the exact original bug), StepExecution render unit tests (six-agent grid + api-key reveal), and step-actions unit tests (oauth-token / sam payload shape).

Post-Mortem (Required for bug fix PRs)

What broke

During onboarding a user selected the OAuth/subscription option and was shown no input field — the step silently advanced, persisting nothing. Non-Anthropic agents (Codex) and the 4 non-major agents (Gemini/Mistral/OpenCode/Amp) were structurally unreachable.

Root cause

ai-oauth, ai-sam, and cloud-sam steps were implemented as no-ops (StepForm.tsx/step-actions.ts) that rendered no field and called no persistence API. The flow was Claude-locked structurally: questions.ts tagged the subscription option has-claude and path-generator.ts gated the only OAuth step on that tag, so any non-Claude OAuth path produced an empty step.

Class of bug

Unwired UI control — a UI affordance (the OAuth step) that collects input but never sends it anywhere, combined with provider lock-in encoded in routing logic rather than derived from capabilities. Same class as the rule 06 "UI-to-Backend data path" failures.

Why it wasn't caught

The no-op steps had no behavioral test asserting a field rendered or a persistence call fired; the existing tests asserted step navigation, not data capture. No test exercised a non-Claude OAuth agent through path generation.

Process fix included in this PR

Coverage added so this class is caught going forward: StepExecution render tests assert the credential input actually appears after agent selection; step-actions tests assert the exact saveAgentCredential / budget payload shape; Playwright audits assert #onboarding-oauth-token renders (the literal original bug). The work also exercises path-generator with all 6 agents so provider-specific gating regressions surface in unit tests. (Aligns with existing rules 06 UI-to-Backend and 35 vertical-slice; no rule file change required — the gap was missing tests, now added.)

Post-mortem file

tasks/archive/2026-06-26-onboarding-inline-multi-agent.md

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A, all completed

Reviewer	Status	Outcome
task-completion-validator	PASS	3 LOW findings, none merge-blocking; all A-F checks pass (research→checklist, checklist→diff, criteria→tests, UI→backend, multi-resource, vertical-slice)
ui-ux-specialist	ADDRESSED	H1 orphaned <label> → role="group" + aria-labelledby on agent/auth/cloud groups; M3 role="group" on button containers; M1 text-[11px]→text-xs; fixed in 2696fbf
security-auditor	ADDRESSED	0 CRIT/HIGH; spellCheck={false} on Codex auth.json textarea; screenshots moved before fill() for all secret fields so no secret value hits disk; credential literals/kinds correct; fixed in 2696fbf
test-engineer	ADDRESSED	H1 CompletionScreen assertion; H2 null-auth-method branch test; M1 validate payload shape; M2 positive dailyOutputTokenLimit; M3 StepExecution render tests (ai-setup + cloud-byoc); M4 Playwright CompletionScreen assertion; fixed in 2696fbf

Exceptions (If any)

• Scope: cloud-sam step persists no backend field (no such field exists).
• Rationale: per rule 42 (no untracked behavior-degrading placeholders), it is an honest "Continue" confirmation step rather than faking persistence to a non-existent endpoint.
• Expiration: N/A — correct as-is until a SAM-infra preference field is added to the backend.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: <reason> — reuses existing in-repo APIs (saveAgentCredential, validateAgentCredential, saveAgentSettings, createCredential, updateUserAiBudget) and the existing AGENT_CATALOG/capabilities; no new external API surface consulted.

Codebase Impact Analysis

apps/web/src/components/onboarding/choose-path/ (questions, path-generator, step-actions, StepForm, StepExecution, ChoosePathWizard). Reads from packages/shared (AGENT_CATALOG, CredentialKind, AgentProviderMode, Scaleway/Hetzner provider shapes). No API or shared package changes — purely consumes existing endpoints.

Documentation & Specs

N/A: no user-facing docs describe the internal onboarding step tree; behavior is self-contained in the wizard component and covered by tests. Task record updated in tasks/archive/.

Constitution & Risk Check

Principle XI (no hardcoded values): auth methods + provider list derived from AGENT_CATALOG/capabilities, not hardcoded branches. Risk: credential handling — mitigated by security-auditor review (secrets never screenshotted, correct credentialKind literals, spellCheck={false}). Multi-tenant: all persistence uses existing per-user credential APIs.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing onboarding-inline-multi-agent (2696fbf) with main (8c20f2d)}

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud