resolutionflow/docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md

# Self-Serve Signup & Onboarding — Phase 2: Frontend + Cutover

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
>
> **Granularity note:** Unlike Phase 1, this plan defines *contracts and acceptance criteria* — not every component detail. Implementers exercise judgment on internal structure (hooks vs. props, file splits, CSS organization) as long as the contracts hold and integration tests pass. Steps use checkbox (`- [ ]`) syntax for tracking; each task is one mergeable PR.

**Goal:** Layer the user-facing self-serve flow on top of the Phase 1 backend foundation — pricing page, OAuth buttons + register redesign, welcome wizard, dashboard redesign with trial pill + next-step card + checklist, accept-invite page, sales contact form, billing portal — gated behind `SELF_SERVE_ENABLED` and `VITE_SELF_SERVE_ENABLED` until cutover.

**Architecture:** Frontend reads billing state from a new `useBillingStore` Zustand store fed by `GET /billing/state`. New routes layer on the existing React Router v7 + lazyWithRetry pattern. Wizard state is server-persisted via `PATCH /users/me/onboarding-step`. Authenticated routes mount under existing `AppLayout`; public routes (pricing, contact-sales, accept-invite, verify-email) are top-level. Cutover is two flag flips: backend `SELF_SERVE_ENABLED=true`, frontend `VITE_SELF_SERVE_ENABLED=true`.

**Tech Stack:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config), Zustand (immer + zundo), React Router v7, Axios, Lucide. Backend additions: a few small endpoints (Phase 1 left them out) — see Phase I.

**Spec reference:** `docs/superpowers/specs/2026-05-05-self-serve-signup-onboarding-design.md` (commit `bbb01ef`).
**Phase 1 reference:** `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-1-backend.md`.

---

## Phase Sequencing

Each phase ends in a mergeable PR. Frontend gates everything behind `VITE_SELF_SERVE_ENABLED` so the new surfaces stay invisible to public users until Phase O cutover.

| Phase | Tasks | Outcome |
|---|---|---|
| I | 27–31 | Backend endpoints Phase 1 deferred + `SELF_SERVE_ENABLED` flag + `/admin/plan-limits` extension |
| J | 32–34 | Frontend billing foundation: `useBillingStore`, hooks, gating components — proven against Phase 1 backend |
| K | 35–37 | Auth surfaces: register redesign with OAuth buttons, accept-invite page, email-verification surfaces |
| L | 38–39 | Welcome wizard — 3 steps with persistence |
| M | 40–41 | Dashboard redesign — trial pill, next-step card, checklist redesign |
| N | 42–44 | Public surfaces: pricing page, contact-sales form, landing-page CTA, beta-signup 307 |
| O | 45–47 | Cutover: Stripe live-mode setup, internal validation, feature-flag flip |

---

## Phase I — Backend endpoints + admin extension + feature flag

### Task 27: BillingService.open_customer_portal + GET /billing/portal-session

**Outcome:** Authed users can request a Stripe-hosted Customer Portal URL for card updates and cancellation.

**Contract:**

```
GET /api/v1/billing/portal-session
  → 200 { url: string }
  → 503 when STRIPE_SECRET_KEY unset
  → 400 when account has no stripe_customer_id (must complete checkout first)
```

`BillingService.open_customer_portal(account)` creates a `stripe.billing_portal.Session` with `return_url=$FRONTEND_URL/account/billing` and returns the session URL.

**Acceptance criteria:**

- [ ] Endpoint mounted at `/billing/portal-session` and is in the `_SUBSCRIPTION_GUARD_ALLOWLIST` and `_EMAIL_VERIFICATION_ALLOWLIST` (so it works for canceled / unverified-past-grace users who need to update billing).
- [ ] Returns 400 with `{"error": "no_stripe_customer"}` when `account.stripe_customer_id is None`.
- [ ] Stripe call mocked via `respx`; happy-path test asserts shape `{url: ...}`.

**Integration test added:**

- `test_billing_portal_returns_url_for_account_with_stripe_customer`

**Commit:** `feat(billing): add BillingService.open_customer_portal + GET endpoint`

---

### Task 28: PATCH /users/me/onboarding-step

**Outcome:** Welcome wizard can persist Step 1/2/3 state to the server.

**Contract:**

```
PATCH /api/v1/users/me/onboarding-step
  body: {
    step: 1 | 2 | 3,
    action: "complete" | "skip",
    data?: {
      // step 1
      company_name?: string,
      team_size_bucket?: "1-2"|"3-5"|"6-10"|"11-25"|"26+",
      role_at_signup?: "owner"|"lead_tech"|"tech"|"other",
      // step 2
      primary_psa?: "connectwise"|"autotask"|"halopsa"|"none",
      // step 3 has no data — invitations posted separately to /accounts/me/invites/bulk
    },
  }
  → 200 { onboarding_step_completed: int, onboarding_dismissed: false }
```

Writes:
- step=1 + action=complete → `accounts.name`, `accounts.team_size_bucket`, `users.role_at_signup`, `users.onboarding_step_completed=1`
- step=1 + action=skip → `users.onboarding_step_completed=1` only (no field writes)
- step=2 → `accounts.primary_psa` (only on complete) + `users.onboarding_step_completed=2`
- step=3 → `users.onboarding_step_completed=3` (the actual invites POST is separate)

Validates: `step` cannot decrease; `action="skip"` ignores the `data` payload.

**Endpoint also exposes a sibling:** `POST /users/me/onboarding-dismiss-rest` → sets `users.onboarding_dismissed=TRUE`. Used by "Skip the rest" button.

**Acceptance criteria:**

- [ ] In `_EMAIL_VERIFICATION_ALLOWLIST` (so users can move through the wizard before verifying email).
- [ ] In `_SUBSCRIPTION_GUARD_ALLOWLIST` (wizard runs during the trial; never gated).
- [ ] Refusing to decrease `step` is enforced (a step=2 PATCH followed by step=1 returns 400).
- [ ] Tests cover: complete with data writes fields; skip without data only advances step; idempotent re-PATCH of same step.

**Integration tests added:**

- `test_onboarding_step1_complete_writes_account_name_and_team_size_and_role`
- `test_onboarding_step2_skip_advances_without_psa`
- `test_onboarding_step_cannot_decrease`
- `test_onboarding_dismiss_rest_sets_flag`

**Commit:** `feat(onboarding): add PATCH /users/me/onboarding-step + dismiss-rest`

---

### Task 29: POST /sales-leads endpoint

**Outcome:** Public Talk-to-sales form has somewhere to post.

**Contract:**

```
POST /api/v1/sales-leads
  body: {
    email: string,
    name: string,
    company: string,
    team_size?: string,
    message?: string,
    source: "pricing_page" | "register_footer" | "landing_page",
    posthog_distinct_id?: string,
  }
  → 201 { id: uuid, status: "received" }
```

Public — no auth required. Rate-limit: max 5 submissions per IP per hour (use existing `core.rate_limit`).

Side effects:
1. Insert `sales_leads` row.
2. Fire-and-forget `EmailService.send_sales_lead_notification` to `settings.SALES_LEAD_RECIPIENT_EMAIL` (new env var, default `sales@resolutionflow.com`).
3. Emit PostHog server-side event `talk_to_sales_form_submitted` with `source` property.

**Acceptance criteria:**

- [ ] Anti-spam: rate-limited per IP.
- [ ] Email send failure doesn't fail the request (logged warning).
- [ ] Sales-lead recipient email is configurable; defaults to a placeholder until cutover.

**Integration tests:**

- `test_sales_lead_creates_row_and_sends_notification_email`
- `test_sales_lead_rate_limited_after_5_per_hour`

**Commit:** `feat(sales): add POST /sales-leads public endpoint`

---

### Task 30: Extend /admin/plan-limits to surface plan_billing fields

**Outcome:** Super-admins can manage plan_billing (Stripe IDs, display names, prices, public/archived flags) via the same admin page they already use.

**Contract change:**

```
GET /api/v1/admin/plan-limits → list[PlanLimitWithBillingResponse]

PlanLimitWithBillingResponse extends PlanLimitResponse with:
  display_name?: string
  description?: string
  monthly_price_cents?: int | null
  annual_price_cents?: int | null
  stripe_product_id?: string | null
  stripe_monthly_price_id?: string | null
  stripe_annual_price_id?: string | null
  is_public?: bool
  is_archived?: bool
  sort_order?: int

PUT /api/v1/admin/plan-limits accepts the same fields; updates plan_billing
in the same transaction. If a plan_billing row doesn't exist for the plan,
PUT creates it.
```

**Acceptance criteria:**

- [ ] Single PUT round-trips both `plan_limits` and `plan_billing` in one transaction.
- [ ] Cache invalidation: `app.state.billing_cache` flushed for all accounts on the affected plan.
- [ ] No new admin page in v1 — existing `/admin/plan-limits` UI just gets new form fields.

**Integration tests:**

- `test_admin_plan_limits_get_includes_plan_billing_fields_when_present`
- `test_admin_plan_limits_put_creates_plan_billing_row`
- `test_admin_plan_limits_put_invalidates_billing_cache`

**Commit:** `feat(admin): extend /admin/plan-limits to manage plan_billing fields`

---

### Task 31: Wire SELF_SERVE_ENABLED feature flag

**Outcome:** A single flag controls whether the new public-facing self-serve flow is exposed.

**Contract:**

Backend:
- `settings.SELF_SERVE_ENABLED: bool = False` (already added in Phase 1 Task 14).
- New endpoint `GET /api/v1/config/public` (no auth) returns `{self_serve_enabled: bool, oauth_providers: ["google", "microsoft"] | []}` — frontend reads this once at load.

Frontend:
- `VITE_SELF_SERVE_ENABLED` env var (build-time bake-in per Lesson 60).
- New `useAppConfig` hook: prefers backend `/config/public` response, falls back to `VITE_SELF_SERVE_ENABLED` for build-time gating.
- Public routes (`/pricing`, `/contact-sales`, `/accept-invite`, OAuth callbacks) return 404 from the frontend router when `self_serve_enabled === false`.
- Register page hides OAuth buttons + invite-code-removed copy when flag is off (preserves the existing invite-code-required register flow).

**Acceptance criteria:**

- [ ] Flag is OFF by default in all envs except where explicitly enabled.
- [ ] When OFF: existing `/auth/register` invite-code flow still works exactly as today.
- [ ] When ON: new flows are reachable; invite-code requirement is removed (the field still exists in the schema for backward-compat but the gate-check accepts NULL).

**Integration tests:**

- `test_get_config_public_returns_self_serve_flag`
- `test_register_invite_code_required_when_self_serve_disabled` (regression)
- `test_register_invite_code_optional_when_self_serve_enabled`

**Commit:** `feat(config): add SELF_SERVE_ENABLED flag + GET /config/public`

---

## Phase J — Frontend billing foundation

### Task 32: useBillingStore Zustand store + GET /billing/state integration

**Outcome:** Frontend has a single source of truth for subscription / plan / feature state.

**Contract — store shape:**

```typescript
// frontend/src/store/billingStore.ts
interface BillingState {
  subscription: {
    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'incomplete' | 'complimentary'
    plan: string
    current_period_start: string | null  // ISO
    current_period_end: string | null    // ISO
    cancel_at_period_end: boolean
    seat_limit: number | null
    has_pro_entitlement: boolean
    is_paid: boolean
  } | null
  planBilling: {
    display_name: string
    description: string | null
    monthly_price_cents: number | null
    annual_price_cents: number | null
  } | null
  planLimits: Record<string, unknown>
  enabledFeatures: Record<string, boolean>
  isLoading: boolean
  error: string | null
}

interface BillingStore extends BillingState {
  fetch: () => Promise<void>
  refetch: () => Promise<void>
  reset: () => void
}
```

**Behavior:**

- Auto-fetches on auth-store login (subscribe to `authStore`).
- Auto-resets on logout.
- Polls every 60s while the dashboard is mounted (simple `useInterval` in a top-level component is fine — no SSE for v1).
- `refetch()` is exposed for explicit refresh after Stripe Checkout success-redirect.

**Acceptance criteria:**

- [ ] Initial state is null/empty; populates after first successful fetch.
- [ ] 401 from `/billing/state` triggers logout via existing axios interceptor (no special handling needed).
- [ ] Polling disabled when no user is logged in.

**Integration tests (Vitest):**

- `useBillingStore fetches on login and populates subscription`
- `useBillingStore resets on logout`
- `useBillingStore refetch overwrites stale data`

**Commit:** `feat(billing): add useBillingStore and /billing/state integration`

---

### Task 33: useFeature, useFeatureLimit, useTrialBanner hooks

**Outcome:** Components can ask "is this feature on?" / "how many sessions left?" / "what stage is the trial in?" without re-implementing the read.

**Contract — hook signatures:**

```typescript
// useFeature: enabled boolean for a feature key
function useFeature(flagKey: string): boolean

// useFeatureLimit: progress against a quantitative limit
function useFeatureLimit(field: keyof PlanLimits): {
  used: number       // from /api/v1/usage/{field} (lazy fetch, cached 60s)
  limit: number | null
  percentage: number | null  // null when limit is null (unlimited)
  isAtLimit: boolean
  isLoading: boolean
}

// useTrialBanner: derives stage from subscription state
function useTrialBanner(): {
  stage: 'pristine' | 'warning' | 'urgent' | 'expired' | 'complimentary' | 'paid' | 'past_due' | 'canceled' | null
  daysRemaining: number | null
}
```

**Stage derivation:**
- `subscription.status === 'complimentary'` → `complimentary`
- `subscription.status === 'active'` → `paid`
- `subscription.status === 'past_due'` → `past_due`
- `subscription.status === 'canceled'` → `canceled`
- `subscription.status === 'trialing'` AND `current_period_end > now()` → `pristine` (>3 days), `warning` (1–3), `urgent` (<1)
- `subscription.status === 'trialing'` AND `current_period_end <= now()` → `expired`

**Acceptance criteria:**

- [ ] `useFeatureLimit` does NOT block render — returns `isLoading=true` until usage data arrives.
- [ ] `useTrialBanner` returns `null` when subscription is null (no flicker on initial load).
- [ ] All three hooks subscribe to `useBillingStore` such that updates propagate without manual refetch.

**Integration tests (Vitest):**

- `useFeature returns false when flag absent`
- `useFeatureLimit transitions isLoading → loaded`
- `useTrialBanner stage matches subscription state matrix`

**Commit:** `feat(billing): add useFeature, useFeatureLimit, useTrialBanner hooks`

---

### Task 34: FeatureGate, UpgradePrompt, EmailVerificationGate components

**Outcome:** Three drop-in components that handle the most common gating patterns. Component implementation details (props, layout, Tailwind classes) are at implementer's discretion as long as the API holds.

**Contracts:**

```tsx
// FeatureGate: render children if feature enabled, else fallback (default <UpgradePrompt />)
<FeatureGate feature="psa_integration" fallback={<UpgradePrompt feature="psa_integration" />}>
  <PsaConfigPanel />
</FeatureGate>

// UpgradePrompt: standardized "this feature is on Pro" affordance with CTA
<UpgradePrompt feature="psa_integration" />  // resolves display name + plan name internally

// EmailVerificationGate: wraps protected content; renders <EmailVerificationWall /> past grace
<EmailVerificationGate>
  <DashboardContent />
</EmailVerificationGate>
```

**Behavior:**

- `<FeatureGate>` reads from `useFeature(feature)`. Server-side check via `require_feature` is the security boundary; this is UX.
- `<UpgradePrompt>` CTA links to `/account/billing/select-plan`.
- `<EmailVerificationGate>` reads `users.email_verified_at` + `users.created_at` from `authStore.user`. Day 1–6 unverified renders children (banner shown elsewhere). Day 7+ unverified renders `<EmailVerificationWall>`.

**Acceptance criteria:**

- [ ] All three components are exported from `frontend/src/components/common/`.
- [ ] No CSS-in-JS — Tailwind classes per existing pattern.
- [ ] Lock icon + greyed style for `<UpgradePrompt>` matches the design system tokens (no `bg-accent` for non-interactive elements per design lessons).

**Integration tests (Vitest + Playwright):**

- `FeatureGate renders children when flag enabled, fallback when disabled` (Vitest)
- `UpgradePrompt CTA navigates to /account/billing/select-plan` (Vitest)
- `EmailVerificationGate renders wall on day 8 unverified user` (Vitest, mocked authStore)

**Commit:** `feat(billing): add FeatureGate, UpgradePrompt, EmailVerificationGate components`

---

## Phase K — Auth surfaces

### Task 35: Register page redesign with OAuth buttons + invite-code-optional

**Outcome:** New register flow supports email+password OR Google OR Microsoft, with promo code field collapsed (deferred per spec) and the legacy invite-code field invisible when `SELF_SERVE_ENABLED`.

**Contract:**

Frontend route stays `/register`. Component lives at `frontend/src/pages/RegisterPage.tsx` (modified, not replaced).

Top-of-page CTAs:
- **"Continue with Google"** button → opens OAuth window → on callback, POSTs `code` to `POST /api/v1/auth/google/callback` → stores tokens via existing auth-store login flow → redirects to `/welcome` (new user) or `/` (returning).
- **"Continue with Microsoft"** button → same shape against `/auth/microsoft/callback`.
- **"or sign up with email"** divider, then existing email + password form.

Removed/conditional:
- **Invite-code field** — hidden when `useAppConfig().self_serve_enabled === true`. When the flag is off, the existing required-invite-code flow runs unchanged.
- **Promo-code field** — not in v1 (deferred per spec). UI should NOT include it.

`/register?plan=pro` query param is captured into `localStorage` (`rf-intended-plan`) so `BillingService.start_trial` (already runs on Pro by default) can later be enriched OR the in-app picker can preselect.

**Acceptance criteria:**

- [ ] Email+password register call still works; auto-sends verification email per Phase 1 Task 20.
- [ ] OAuth callback creates User + Account + Subscription per Phase 1 Task 17/18; lands on `/welcome`.
- [ ] When self-serve disabled: invite-code flow visible, OAuth buttons hidden.
- [ ] When self-serve enabled: invite-code field hidden, OAuth buttons visible.
- [ ] Existing test users (`engineer@resolutionflow.example.com` etc.) can still log in via `/login` unchanged.

**Integration tests (Playwright):**

- `register email+password → verification email queued → land on /welcome`
- `register via Google OAuth (mocked provider) → land on /welcome`
- `register page hides OAuth + shows invite-code field when self_serve_enabled is false`

**Commit:** `feat(auth): redesign /register with OAuth buttons; hide invite-code under flag`

---

### Task 36: AcceptInvitePage at /accept-invite?code=...

**Outcome:** Invitee from email can join an existing account with set-password OR Google OR Microsoft.

**Contract:**

New top-level route `/accept-invite?code=<32-char-code>`. Component at `frontend/src/pages/AcceptInvitePage.tsx`.

Flow:
1. On mount, `GET /api/v1/accounts/invites/{code}/lookup` (NEW endpoint — see acceptance criteria) returns `{account_name, inviter_name, invited_email, role}` or 404/410 (expired/revoked/used).
2. Render: "Join {account_name} on ResolutionFlow" + email locked to `invited_email` + three sign-in options (set password, Google, Microsoft).
3. On submit, POST to existing `/auth/register` with `account_invite_code` and the email matching `invited_email` (per Phase 1 Task 20 enforcement).
4. OAuth path: launch provider with state including the invite code; callback POSTs `{code, account_invite_code, invited_email}` to handle linking.
5. Success → land on `/?welcome=teammate` (suppresses welcome wizard for invitees per spec).

**Backend addition needed (small):**

```
GET /api/v1/accounts/invites/{code}/lookup
  → 200 {account_name, inviter_name, invited_email, role}
  → 404 invite_invalid_or_expired_or_revoked
```

This is a public endpoint (no auth) reading account-scoped data, so uses `_admin_session_factory()` per the Phase 4 RLS pattern.

**Acceptance criteria:**

- [ ] Invalid/expired/revoked codes show a clear "ask {inviter} to resend" message with a link to email the inviter (via `mailto:`).
- [ ] Email field is locked to `invited_email` — frontend doesn't even render an editable input.
- [ ] OAuth path requires the provider's email to match `invited_email`; mismatch returns the same `invite_email_mismatch` error from Phase 1.
- [ ] Successful accept lands on `/?welcome=teammate`; the dashboard shows a "Welcome to {account_name}" toast and a checklist with "Setup shop" + "Invite a teammate" auto-marked done.

**Integration tests (Playwright):**

- `accept invite with email/password → join existing account → land on /?welcome=teammate`
- `accept invite with Google OAuth (matching email) → land on dashboard`
- `accept invite with mismatched email → see invite_email_mismatch error`
- `accept invite with expired code → see resend message`

**Commit:** `feat(auth): add /accept-invite page + lookup endpoint`

---

### Task 37: Email verification surfaces — banner, wall, /verify-email route

**Outcome:** UI for the soft 7-day grace + day-7 wall.

**Contract:**

- **`<EmailVerificationBanner />`** — thin top-of-dashboard bar visible when `users.email_verified_at IS NULL` AND grace not expired. "Resend" link calls existing `POST /auth/email/send-verification`.
- **`<EmailVerificationWall />`** — full-content replacement when grace expired. Same "Resend" CTA + a "Sign out" button.
- **`/verify-email?token=...`** — frontend route that calls existing `POST /auth/email/verify` and shows success/error state. On success, refreshes the auth store and redirects to `/?verified=1` toast.

**Acceptance criteria:**

- [ ] Banner contrasts well in dark theme (use `bg-warning-dim` per design tokens, not custom colors).
- [ ] Wall has a "Sign out" button so a user with a typo'd email can recover.
- [ ] Verification success toast does not double-fire on remount.
- [ ] If user is already verified when hitting `/verify-email`, the page shows "Already verified" rather than failing.

**Integration tests (Playwright):**

- `unverified day-1 user sees banner on dashboard`
- `unverified day-8 user sees wall, can sign out, can resend`
- `clicking verification link verifies and redirects to dashboard with toast`

**Commit:** `feat(auth): add email verification banner, wall, /verify-email page`

---

## Phase L — Welcome wizard

### Task 38: Wizard scaffold + Step 1 (Your shop)

**Outcome:** Authed users at `/welcome` see a deliberate first-impression flow that captures shop context.

**Routing:**

```
/welcome              → redirects to next incomplete step or "/" if done
/welcome/step-1       → "Your shop"
/welcome/step-2       → "Your PSA"
/welcome/step-3       → "Invite your team"
```

A top-level `<WelcomeRouter />` reads `users.onboarding_step_completed` + `users.onboarding_dismissed` from authStore and dispatches:

| State | Redirect |
|---|---|
| `onboarding_dismissed === true` | `/` |
| `onboarding_step_completed >= 3` | `/` |
| `onboarding_step_completed === null/0` | `/welcome/step-1` |
| `onboarding_step_completed === 1` | `/welcome/step-2` |
| `onboarding_step_completed === 2` | `/welcome/step-3` |

**Step 1 fields (per spec):**

- Company name (pre-filled from `accounts.name`, editable)
- Team size: select from `1-2 / 3-5 / 6-10 / 11-25 / 26+`
- Your role: select from `Owner / Lead Tech / Tech / Other`

**Step 1 actions:**
- **Continue** → PATCH `/users/me/onboarding-step` `{step: 1, action: "complete", data: {...}}` → `/welcome/step-2`
- **Skip** → PATCH `{step: 1, action: "skip"}` → `/welcome/step-2`
- **Skip the rest** → POST `/users/me/onboarding-dismiss-rest` → `/`

**Acceptance criteria:**

- [ ] Each navigation persists state server-side before transition; refresh resumes correctly.
- [ ] Skip-the-rest is a quiet text link, not a primary button.
- [ ] Email-verification banner is visible above the wizard if user is unverified (banner persists into wizard).

**Integration tests (Playwright):**

- `new user lands on /welcome/step-1 after register`
- `step-1 Continue with all fields filled persists and advances`
- `step-1 Skip-the-rest dismisses and lands on /`
- `refresh in middle of step-1 returns to step-1 with prior data still in form (or empty if not yet saved)`

**Commit:** `feat(onboarding): add welcome wizard scaffold + Step 1 (Your shop)`

---

### Task 39: Wizard Steps 2 (Your PSA) and 3 (Invite team)

**Outcome:** Wizard is complete; users can finish or skip individual steps.

**Step 2 fields (per spec):**

- PSA selection: tiles for `ConnectWise / Autotask / HaloPSA / No PSA yet`. Selecting one shows a quiet inline "Connect now" link that navigates to `/account/integrations` (out of wizard).

**Step 3 fields (per spec):**

- Email input rows × 3, with "+ Add another" up to 10 max
- Per-row role select: default "Tech" (maps to `engineer`), with "Viewer" option
- "Skip" and "Skip the rest" links

**Step 3 submit behavior:**

- POST `/api/v1/accounts/me/invites/bulk` with the populated rows.
- Then PATCH `/users/me/onboarding-step` `{step: 3, action: "complete"}`.
- On success → `/?welcome=true` (shows a "You're all set" toast).
- Bulk endpoint's `failed[]` array displayed inline next to the failed email; user can retry.

**Acceptance criteria:**

- [ ] Step 2 default action is "Continue" (not "Connect now"); the inline credential entry is intentionally NOT in the wizard.
- [ ] Step 3 invites are sent (email send happens server-side per Phase 1 Task 22).
- [ ] Empty Step 3 + Skip = no invites sent; step still advances.
- [ ] Each step's persistence is independent — navigating back via browser back button respects `onboarding_step_completed`.

**Integration tests (Playwright):**

- `step-2 select ConnectWise → continue → primary_psa is set in /billing/state-equivalent or /auth/me`
- `step-3 enter 2 emails → invites visible in /accounts/me/invites + emails sent`
- `step-3 with one bad email shows partial success, user can retry`
- `wizard end-to-end: register → step-1 → step-2 → step-3 → dashboard with success toast`

**Commit:** `feat(onboarding): add wizard Steps 2 (PSA) and 3 (Invite team)`

---

## Phase M — Dashboard redesign

### Task 40: Topbar trial pill + email verification banner integration

**Outcome:** Every authed page shows the right billing-state pill in the topbar.

**Contract — `<TrialPill />` placement:**

Mounts inside `AppLayout` topbar. Reads `useTrialBanner()`:

| Stage | Pill |
|---|---|
| `pristine` | "Pro trial · Nd" — info color |
| `warning` (≤3d) | "Pro trial · Nd" — warning amber |
| `urgent` (≤1d) | "Pro trial · today" — urgent (warning amber, slightly more saturated) |
| `expired` | "Trial expired — pick a plan" — clickable → `/account/billing/select-plan` |
| `paid` | tier display name (e.g., "Pro") — quiet |
| `complimentary` | "Complimentary Pro" — friendly tag, no CTA |
| `past_due` | "Payment failed — update card" — clickable → `/account/billing` |
| `canceled` | "Reactivate" — clickable → `/account/billing/select-plan` |
| `null` | hidden |

**Acceptance criteria:**

- [ ] Color tokens are existing design-system tokens (`--accent` / `--warning` / etc.) — no custom colors.
- [ ] Pill is keyboard-focusable for clickable variants.
- [ ] EmailVerificationBanner from Task 37 sits BELOW the topbar, ABOVE main content. Both can coexist.
- [ ] Mobile: pill collapses to icon + tooltip when topbar is too narrow.

**Integration tests (Playwright):**

- `complimentary user sees "Complimentary Pro" pill`
- `trialing user with 12 days remaining sees "Pro trial · 12d"`
- `expired-trial user sees clickable "Trial expired" pill`
- `past_due user sees clickable "Payment failed" pill`

**Commit:** `feat(dashboard): add TrialPill in AppLayout topbar`

---

### Task 41: Next-step card + checklist redesign + dashboard wiring

**Outcome:** Dashboard surfaces a single "next thing to do" card; full checklist available behind a toggle. Replaces the existing `OnboardingChecklist` component.

**Contract:**

- **`<NextStepCard />`** at top of dashboard content (below banner). Reads from existing `/users/onboarding-status` payload (extended in Phase 1 to drop SOLO/TEAM split — see Phase 1 Task wiring if needed; if not done, do it here).
- Shows the highest-priority incomplete item with a primary CTA button. Items in priority order:
  1. Verify your email (only if unverified — hidden for OAuth signups)
  2. Set up your shop (`onboarding_step_completed >= 1`)
  3. Run your first FlowPilot session (existing `ran_session` check)
  4. Connect your PSA (existing `connected_psa` check)
  5. Invite a teammate (extend existing `invited_teammate` check)
  6. Pick a plan — surfaces near trial end (only when stage is `warning` / `urgent` / `expired`)
- Below the card, "Show all setup steps" toggle expands a full checklist view (single list, no SOLO/TEAM split per spec).

**OnboardingChecklist component changes:**

- Remove `SOLO_ITEMS` / `TEAM_ITEMS` split — single unified list.
- Drop the stale `tried_ai_assistant` / "Check out the Script Builder" item entirely.
- Add "Pick a plan" item that shows when trial-banner stage is `warning` or later.

**Backend addition:**

`/api/v1/users/onboarding-status` (existing endpoint) response shape extended:

```python
class OnboardingStatus(BaseModel):
    # existing
    created_flow: bool
    ran_session: bool
    exported_session: bool
    invited_teammate: bool
    connected_psa: bool
    is_team_user: bool         # KEEP — internal logic only; no UI bifurcation
    dismissed: bool            # users.onboarding_dismissed
    # NEW
    email_verified: bool
    shop_setup_done: bool      # users.onboarding_step_completed >= 1
    # REMOVED from new code paths (kept in payload for backward-compat during deploy):
    # tried_ai_assistant: bool
```

**Acceptance criteria:**

- [ ] Old `OnboardingChecklist` widget is replaced wholesale on the dashboard route. Other pages that referenced it (none found in current code, but confirm via grep) are updated or unaffected.
- [ ] Next-step card disappears when all items are done OR `onboarding_dismissed=TRUE`.
- [ ] No SOLO/TEAM bifurcation in the checklist UI.
- [ ] Stale "Script Builder" item is gone.

**Integration tests (Playwright):**

- `dashboard for new user surfaces "Verify your email" as next step`
- `after verifying, next step is "Set up your shop"`
- `after wizard step 1, next step is "Run your first FlowPilot session"`
- `"Show all setup steps" expands to a 6-item list with no SOLO/TEAM headers`
- `Pick-a-plan appears at trial day 12, urgent at day 13, primary at day 14`

**Commit:** `feat(dashboard): replace checklist with next-step card + unified list`

---

## Phase N — Public surfaces

### Task 42: Pricing page (B-style) at /pricing

**Outcome:** Public pricing page lives at `/pricing`, gated by feature flag.

**Contract:**

Public route. Component at `frontend/src/pages/PricingPage.tsx`. Reads `plan_billing` data via a new public endpoint:

```
GET /api/v1/plans/public
  → 200 [
    {
      plan: string,
      display_name: string,
      description: string | null,
      monthly_price_cents: number | null,
      annual_price_cents: number | null,
      max_seats: number | null,        // from plan_limits
      sort_order: number,
      is_public: true,                 // filtered server-side
    },
    ...
  ]
```

Page sections (per spec B):
1. Hero (one-liner + reverse-trial reassurance)
2. Three plan cards (Starter / Pro recommended / Enterprise) — Pro card has "Recommended" badge; Enterprise card has "Talk to sales" CTA → `/contact-sales`
3. Comparison table (which features in which plan) — driven by feature flag display names
4. Single testimonial slot (placeholder until real testimonial available)
5. Trust strip — security/compliance copy

**Acceptance criteria:**

- [ ] Returns 404 when `self_serve_enabled === false`.
- [ ] Plan cards show prices from `plan_billing.monthly_price_cents`. Enterprise card hides price.
- [ ] "Start free trial" buttons on Starter/Pro link to `/register?plan=pro` (or starter).
- [ ] "Talk to sales" on Enterprise links to `/contact-sales`.
- [ ] Trust strip claims should be honest — see spec open-risks #7 (GDPR DPA) and #7b (SOC2). If those aren't ready by cutover, copy in this task uses softer language (e.g., "Built on Stripe + AWS · Encrypted in transit and at rest").

**Integration tests (Playwright):**

- `unauth user sees pricing page when self_serve_enabled is true`
- `pricing page → "Start free trial" → /register?plan=pro`
- `pricing page → "Talk to sales" → /contact-sales`
- `pricing page returns 404 when self_serve_enabled is false`

**Commit:** `feat(pricing): add /pricing page (B-style)`

---

### Task 43: Talk-to-sales form at /contact-sales + landing-page CTA

**Outcome:** Enterprise prospects have a clear path; `LandingPage.tsx` gets a "See pricing" CTA.

**Contract:**

`/contact-sales` route with form posting to `POST /sales-leads` (Phase I Task 29).

Form fields:
- Name (required)
- Work email (required)
- Company (required)
- Team size (select; same buckets as wizard Step 1 + a "more than 26" option)
- "What brought you here?" (textarea, optional)
- Submit button

After submit:
- Confirmation page: "Thanks — we'll reach out within 1 business day. Want to skip ahead? [Calendly link]"
- Calendly link is a config string (`VITE_CALENDLY_URL`); when unset, link section is hidden.

`LandingPage.tsx` modification:
- Add a prominent "See pricing" CTA near the existing "Get started" CTA.
- Both visible regardless of `self_serve_enabled` (see-pricing 404s if flag off, landing keeps existing behavior). Actually: gate the See-pricing CTA behind `useAppConfig().self_serve_enabled` so we don't show a button that 404s.

**Acceptance criteria:**

- [ ] Form blocks duplicate submissions client-side (disable button while in flight).
- [ ] PostHog `talk_to_sales_form_submitted` event fires with `source: 'pricing_page' | 'landing_page'` based on referrer.
- [ ] Calendly link block hides when `VITE_CALENDLY_URL` unset.

**Integration tests (Playwright):**

- `submit /contact-sales form → see confirmation page → /sales-leads has new row`
- `landing page shows "See pricing" CTA when self_serve_enabled, hides when off`

**Commit:** `feat(sales): add /contact-sales form + landing page CTA`

---

### Task 44: Beta-signup deprecation

**Outcome:** The legacy `beta_signup.py` endpoint redirects to register; existing waitlist gets a heads-up email.

**Contract:**

- `POST /api/v1/beta-signup` (existing) → keep mounted but return `307 Temporary Redirect` to `/register?from=beta`.
- One-off admin script `scripts/email_beta_waitlist.py` that reads existing `beta_signup` table and queues "we've launched" emails to each.
- Don't drop the table; archive in place.

**Acceptance criteria:**

- [ ] Existing tests against `/beta-signup` either updated to expect 307 or removed.
- [ ] Script is idempotent (uses an `email_sent_at` field on the beta-signup row, adding it via migration if needed).

**Integration tests:**

- `POST /beta-signup returns 307 to /register?from=beta`

**Commit:** `feat(sales): redirect beta-signup to /register; queue waitlist emails`

---

## Phase O — Cutover

### Task 45: Stripe live-mode setup checklist (manual)

**Outcome:** Stripe live-mode is configured and matches test mode. Manual step; this task tracks completion.

**Checklist:**

- [ ] In Stripe Dashboard (live mode):
  - [ ] Create Products: ResolutionFlow Starter, ResolutionFlow Pro, ResolutionFlow Enterprise.
  - [ ] Create monthly + annual recurring Prices for Starter and Pro.
  - [ ] Enterprise has no Prices in the catalog (sales-created per customer).
  - [ ] Enable Customer Portal: update payment method, cancel subscription, view invoices. Disable plan-switching from the portal.
  - [ ] Register webhook endpoint at `https://api.resolutionflow.com/api/v1/webhooks/stripe` with events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`, `invoice.payment_succeeded`.
  - [ ] Save the live webhook signing secret.
- [ ] In Railway prod environment variables:
  - [ ] `STRIPE_SECRET_KEY` (live mode key, `sk_live_...`)
  - [ ] `STRIPE_WEBHOOK_SECRET` (live signing secret)
  - [ ] `STRIPE_PUBLISHABLE_KEY` (live publishable key) → `VITE_STRIPE_PUBLISHABLE_KEY` for frontend builds
  - [ ] `OAUTH_REDIRECT_BASE` = `https://resolutionflow.com`
  - [ ] `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` for prod Google OAuth app (separate from dev/test)
  - [ ] `MS_CLIENT_ID` / `MS_CLIENT_SECRET` for prod Microsoft OAuth app
- [ ] Run `python -m scripts.sync_stripe_plan_ids` (Phase 1 Task 6 referenced; create if not existing) to populate `plan_billing` rows with live Stripe IDs:
  - [ ] Pro monthly + annual price IDs
  - [ ] Starter monthly + annual price IDs (if Starter is in scope; see open risk #14)
  - [ ] Enterprise: stripe_product_id only, no price IDs

**Acceptance criteria:**

- [ ] Live webhook receives a test event (use Stripe CLI's `stripe trigger checkout.session.completed` against the live endpoint with a test customer) and is logged in `stripe_events`.
- [ ] `plan_billing` rows query returns expected Stripe IDs for Pro tier.

**No commit** — this is a deploy-time operation.

---

### Task 46: Internal validation pass (test mode → soft cutover via per-email allowlist)

**Outcome:** Real flow exercised end-to-end against the prod backend with `SELF_SERVE_ENABLED=false`, gated to internal testers only.

**Per-email allowlist mechanism:**

Backend reads `INTERNAL_TESTER_EMAILS` env var (comma-separated). When `SELF_SERVE_ENABLED=false` AND `current_user.email` is in the list, treat the user as if the flag were on (e.g., bypass invite-code requirement, expose pricing page via a header check). For frontend, the `/config/public` endpoint returns `self_serve_enabled: true` for these specific authenticated users.

**Validation scenarios:**

- [ ] Email signup → wizard step-by-step → first FlowPilot session run → trial-end synthetic time (DB query: `UPDATE subscriptions SET current_period_end = now() - interval '1 day' WHERE account_id = ...`) → plan picker → Stripe Checkout (test card `4242 4242 4242 4242`) → webhook → status='active'.
- [ ] Google sign-in (real Google account) → `/welcome` → wizard → dashboard.
- [ ] Microsoft sign-in (real M365 account) → same flow.
- [ ] Invite-by-email: existing tester invites a teammate → teammate receives email → clicks link → `/accept-invite` → set password → joins account → lands on `/?welcome=teammate`.
- [ ] Email match enforcement: try to register with `account_invite_code` and a different email → see `invite_email_mismatch`.
- [ ] Past-due simulation: use Stripe test card `4000 0000 0000 0341` → first invoice succeeds, next charge declines → `subscription_status='past_due'` → topbar pill changes → user can update card via Customer Portal.
- [ ] Pilot complimentary: log in as an existing pilot account → see "Complimentary Pro" pill, no walls, no nudges.
- [ ] Webhook signature failure: send a forged webhook → 400 + log entry.
- [ ] OAuth-only user attempts password login: rejected with `use_oauth_provider`.

**Acceptance criteria:**

- [ ] All 9 scenarios pass in prod test mode with internal testers.
- [ ] Errors logged during validation are reviewed and either fixed or documented.

**No commit** — validation is a checklist of test runs.

---

### Task 47: Feature-flag flip + week-1 monitoring

**Outcome:** `SELF_SERVE_ENABLED=true` and `VITE_SELF_SERVE_ENABLED=true` in prod. Public pricing page is live.

**Cutover steps:**

- [ ] Send pre-launch email to all pilot users via `EmailService.send_complimentary_account_announcement` (1-2 days before flip).
- [ ] Schedule the flip during low-traffic hours.
- [ ] Update Railway env vars: `SELF_SERVE_ENABLED=true` (backend), `VITE_SELF_SERVE_ENABLED=true` (frontend, requires redeploy since Vite bakes at build time).
- [ ] Verify prod: pricing page returns 200; new user can register without invite code.
- [ ] Announce launch (founder action; not eng).

**Week-1 monitoring (PostHog dashboards):**

- [ ] Funnel: `pricing_page_viewed → register_started → register_completed → email_verification_completed → welcome_wizard_completed → first_session_started`
- [ ] OAuth method mix
- [ ] Wizard skip rate per step
- [ ] `feature_gate_blocked` count by `flag_key`
- [ ] Trial conversion: `trial_modal_shown → checkout_completed`
- [ ] Stripe webhook error rate (Sentry alert if > 1/hour)
- [ ] `subscriptions.is_paid` audit query (manual SQL): confirm complimentary accounts are NOT counted in MRR

**Rollback plan:**

- Flip both flags back to `false`. Pricing page → 404. Register page → invite-code-required flow. Pilot complimentary status preserved (benign).
- Stripe webhook handler stays live regardless.
- Forward-only schema means nothing to revert at the DB level.

**No commit** — this is a deploy + monitor task.

---

## Self-Review

**Spec coverage check (against `2026-05-05-self-serve-signup-onboarding-design.md`):**

| Spec section | Covered by |
|---|---|
| §3.1 Pricing page | Task 42 |
| §3.2 Register page redesign with OAuth + invite-code-optional | Task 35 |
| §3.3 Welcome wizard (3 steps) | Tasks 38, 39 |
| §3.4 Dashboard with topbar pill + next-step card | Tasks 40, 41 |
| §3.5 Email verification surfaces | Task 37 |
| §3.6 Trial-end conversion (in-app modal day 10, wall day 14) | Task 41 covers checklist; the modal is part of Task 40's TrialPill stage transitions + the dashboard's modal trigger via `useTrialBanner` — implementer's discretion to add a `<TrialEndingModal />` component if it emerges naturally |
| §3.7 Plan picker → Stripe Checkout | Frontend page at `/account/billing/select-plan` lives within the dashboard area; Task 41's "Pick a plan" CTA navigates there. Component exists in scope of Task 40/41 — implementer's call on whether to split into its own file. |
| §3.8 Past-due / dunning | Task 40 (TrialPill `past_due` stage) + Customer Portal link |
| §3.9 Sales lead | Tasks 29, 43 |
| §3.10 Owner transfer (existing) | No new task — surface in Account → Team page during dashboard work, implementer's discretion |
| §4 BillingService.open_customer_portal | Task 27 |
| §4 PATCH /users/me/onboarding-step | Task 28 |
| §4 GET /billing/state consumed by frontend | Task 32 |
| §4 useFeature/useFeatureLimit/useTrialBanner | Task 33 |
| §4 FeatureGate / UpgradePrompt | Task 34 |
| §4 Caching invalidation triggered from /admin/plan-limits | Task 30 |
| §5 Beta-signup deprecation | Task 44 |
| §5 SELF_SERVE_ENABLED dark launch | Task 31 |
| §5 Stripe live-mode setup | Task 45 |
| §5 Internal validation phase | Task 46 |
| §5 Cutover + monitoring | Task 47 |

**Gaps and judgment-calls (called out for implementer):**

- **`<TrialEndingModal />` (day-10 in-app modal)** — left to implementer to decide whether it's its own task or rolled into Task 40. Spec is clear about behavior; component split is style.
- **Plan picker page (`/account/billing/select-plan`)** — frontend page that calls `POST /billing/checkout-session` and redirects. Lives within Task 40/41 area; not its own task. Acceptance: "user can pick Starter/Pro + seats and be redirected to Stripe Checkout."
- **Owner-transfer surface in Account → Team page** — existing endpoint, just needs UI. Implementer's call on which task absorbs this.
- **`<TrialEndedWall />`** — referenced in spec; renders on dashboard route when trial expired. Lives in Task 40/41 area as a render-branch of the dashboard layout.

**Placeholder scan:** none — every "implementer's discretion" call is bounded by a contract and acceptance criteria.

**Type/contract consistency:**

- `BillingState` shape in Task 32 matches `BillingStateResponse` from Phase 1 Task 24.
- `PATCH /users/me/onboarding-step` payload in Task 28 matches the wizard's writes in Tasks 38, 39.
- OAuth callback contract in Task 35 matches Phase 1 Task 17/18 endpoint shapes.
- `<EmailVerificationGate>` in Task 34 reads from authStore; `<TrialPill>` in Task 40 reads from `useBillingStore`. Different sources, intentional (verification is on `User`, trial is on `Subscription`).

---

## Execution Handoff

**Plan complete and saved to `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md`.**

This plan is intentionally higher-altitude than Phase 1: contracts and acceptance criteria, not component-detail walkthroughs. Implementers exercise judgment on internal structure as long as contracts hold and integration tests pass.

**Recommended execution sequence:**

1. **Phase 1 first** (`2026-05-06-self-serve-signup-phase-1-backend.md`). Phase 2 depends on its endpoints.
2. After Phase 1 lands, **execute Phase 2 phases I → O sequentially**. Each phase is one or a few mergeable PRs.
3. **Cutover (Phase O)** is gated by Phase 1 + Phase 2 both green in prod test mode.

**Two execution options for Phase 2:**

**1. Subagent-Driven (recommended)** — fresh subagent per task with two-stage review. Higher-altitude tasks pair well with this since the subagent has room to make local design decisions inside the contract.

**2. Inline Execution** — execute tasks in a long-running session using executing-plans, with checkpoints between phases.

**Which approach?**