prototype: three onboarding UX prototypes for design exploration

[simple-agent-manager]

⚠️ PROTOTYPE ONLY — DO NOT MERGE TO PRODUCTION ⚠️

This PR contains three self-contained onboarding prototypes built for design exploration only. All prototypes use mock data, have no auth dependencies, and make no API calls. They exist to evaluate different UX approaches for getting a new user from sign-up to their first working task.

These files must be removed before any production merge. The prototype routes (/prototype/*) are clearly separated from production routes in App.tsx.

---

Background: The Problem

A less-technical user was confused by our current onboarding about:

• OAuth vs API keys — which one lets them use their existing Claude Pro subscription?
• Billing implications — will they be charged extra for tokens? How much?
• Cloud infrastructure — why do they need a Hetzner account? What if they don't have one?
• Too many concepts at once — the current wizard dumps agent keys, cloud providers, and GitHub all at once

The Three Prototypes

1. Zero-to-Hero (/prototype/onboarding-zero-to-hero)

Approach: Exhaustive guided explanation

A 7-step wizard that explains every concept before asking the user to act:

1. Welcome with value prop
2. "How SAM Works" concept explainer (agent → VM → code → PR)
3. Choose your AI agent (Claude Code or Codex)
4. Billing step — three clear options with cost explanations:
   • "Use my Claude Pro/Max subscription" (OAuth — $0 extra)
   • "Use my API key" (pay-per-token, ~$0.01–1.50/task)
   • "Use SAM credits" (platform-managed, set a budget)
5. Cloud infrastructure — "Bring your own Hetzner" vs "SAM manages it"
6. GitHub App install with repo selection
7. First task with suggestion chips + animated provisioning

Best for: Users who want to understand everything before committing.

2. Instant Start (/prototype/onboarding-instant-start)

Approach: Value-first, setup-later

Gets the user building in 30 seconds, defers all configuration:

1. Pick a template repo (Next.js, Express, FastAPI)
2. Describe what you want to build (with suggestions)
3. Watch animated provisioning ("Claiming workspace... Installing agent...")
4. See the agent working with simulated chat messages and tool calls
5. After the user has seen value, reveal setup (billing, cloud, GitHub) with "Trial" badges

Best for: Users who want to see what SAM does before investing in configuration.

3. Choose-Your-Path (/prototype/onboarding-choose-path)

Approach: Personalized setup based on user's situation

Asks 4-5 questions to generate a custom onboarding plan:

• "How familiar are you with AI coding tools?" (brand new / some / expert)
• "Do you have an AI subscription?" (Claude Pro, ChatGPT, API key, nothing)
• "Do you have a cloud hosting account?" (Hetzner, other, none)
• "Do you have a GitHub repo ready?" (yes, use template)

Then shows a personalized step-by-step plan with time estimates ("~3 minutes total") and executes each step with progress indicators.

Best for: Users with varying backgrounds who need a tailored path.

---

Screenshots (47 captured)

All screenshots are in .codex/tmp/playwright-screenshots/ in this PR. Key flows:

Zero-to-Hero

Step	Mobile	Desktop
Welcome	zero-to-hero-01-welcome-mobile.png	zero-to-hero-01-welcome-desktop.png
Concept	zero-to-hero-02-concept-mobile.png	zero-to-hero-02-concept-desktop.png
Agent Selection	zero-to-hero-03-agent-mobile.png	zero-to-hero-03-agent-desktop.png
Billing (3 modes)	zero-to-hero-04-billing-mobile.png	zero-to-hero-04-billing-apikey-desktop.png
Cloud	zero-to-hero-05-cloud-mobile.png	zero-to-hero-05-cloud-byoc-desktop.png
GitHub	zero-to-hero-06-github-mobile.png	zero-to-hero-06-github-desktop.png
First Task	zero-to-hero-07-first-task-mobile.png	zero-to-hero-07-task-running-desktop.png

Instant Start

Step	Mobile	Desktop
Pick Repo	instant-start-01-pick-repo-mobile.png	instant-start-01-pick-repo-desktop.png
Pick Task	instant-start-02-pick-task-mobile.png	instant-start-02-pick-task-desktop.png
Provisioning	instant-start-03-provisioning-mobile.png	—
Agent Working	instant-start-04-agent-working-mobile.png	instant-start-04-agent-working-desktop.png
Agent Chat	instant-start-04b-agent-chat-mobile.png	instant-start-04b-agent-chat-desktop.png
Setup Reveal	instant-start-05-setup-reveal-mobile.png	—

Choose-Your-Path

Step	Mobile	Desktop
Experience	choose-path-01-experience-mobile.png	choose-path-01-experience-desktop.png
AI Subscription	choose-path-02-ai-subscription-mobile.png	choose-path-02-ai-subscription-desktop.png
Cloud Account	choose-path-03-cloud-account-mobile.png	choose-path-03-cloud-account-desktop.png
GitHub Ready	choose-path-04-github-ready-mobile.png	choose-path-04-github-ready-desktop.png
Path Preview	choose-path-05-path-preview-mobile.png	choose-path-05-path-preview-desktop.png
Executing	choose-path-06-executing-mobile.png	—

---

Test Results

18 Playwright test cases across 3 viewports (iPhone SE 375px, iPhone 14 390px, Desktop 1280px) × 6 test suites = 18/18 passing. All overflow checks pass.

Files Changed

• apps/web/src/App.tsx — Added 3 prototype routes (public, no auth)
• apps/web/src/pages/prototype-onboarding-zero-to-hero/ — Prototype 1
• apps/web/src/pages/prototype-onboarding-instant-start/ — Prototype 2
• apps/web/src/pages/prototype-onboarding-choose-path/ — Prototype 3
• apps/web/tests/playwright/onboarding-prototypes-audit.spec.ts — Visual audit
• .codex/tmp/playwright-screenshots/*.png — 47 screenshots

Before Any Production Merge

These prototype routes and files MUST be removed:

1. Delete apps/web/src/pages/prototype-onboarding-*/
2. Remove the 3 <Route path="/prototype/..."> lines from App.tsx
3. Delete the Playwright test file
4. Delete .codex/tmp/playwright-screenshots/

The learnings from whichever prototype is chosen should be applied to the real onboarding wizard at apps/web/src/components/onboarding/.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
7.6% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud