Onboarding Flow

Feature: [one-line name — e.g., "Post-signup workspace setup flow"]

## What and why

Problem
[What's happening today? Are users dropping off, skipping setup, or arriving at the core product without enough context to get value from it?]

Who this is for
[Specific user type and entry point — e.g., "New users who have just verified their email address and are loading the app for the first time"]

In scope
- [Steps included in this flow]
- [Data collected at each step]
- [Entry point(s) — where does this flow start?]
- [Exit point — where does the user land when the flow is complete or skipped?]

Out of scope
- [Steps deferred to a later phase]
- [User types this flow does not apply to — e.g., "Users invited to an existing workspace bypass this flow"]
- [Emails or notifications not included in this phase]

Key behaviors
- When [user completes step X], [what is saved and what happens next]
- When [user skips step X], [what default value is applied and where they go]
- When [user closes the app or browser mid-flow], [what state is preserved]
- When [user completes the final step], [where they land and what they see]
- When [user returns to a partially completed flow], [where they re-enter]

Edge cases
- What happens if the user refreshes the browser or force-quits the app mid-flow?
- What happens if the user tries to access the main product before completing onboarding?
- What happens if a required step fails — e.g., an API call to set up a workspace errors out?
- What happens if the user completes onboarding on one device and opens the app on another?
- What happens if the user has already completed part of this flow (e.g., returning after email verification delay)?
- What does the flow look like for users invited to join an existing account vs. creating a new one?

Open questions
- [Which steps are mandatory vs. skippable?]
- [What analytics events need to fire at each step?]
- [Are there email or in-app notification triggers at any step?]
- [What's the re-entry behavior — does the flow resume or restart?]
- [Is there an A/B test planned for any step in this flow?]

## Coding agent context

Tech stack
[e.g., "Next.js 14, TypeScript, Prisma, PostgreSQL, Resend for transactional email"]

Reference files
[e.g., "See /app/onboarding/ for the existing onboarding route structure"]
[e.g., "See /components/StepProgress.tsx for the progress indicator component"]
[e.g., "See /lib/analytics.ts for the track() function — all analytics events go through this"]

Patterns to follow
- [e.g., "State is managed in the onboarding context — see /context/OnboardingContext.tsx"]
- [e.g., "Each step is a separate route under /onboarding/[step] — follow this pattern for new steps"]
- [e.g., "Email triggers use the existing Resend wrapper in /lib/email.ts"]

Do not
- [ ] Do not mark a step as required in code if it isn't required by the product spec — skippability is a product decision, not a default
- [ ] Do not lose progress on browser refresh — onboarding state must persist (database or cookie, not localStorage)
- [ ] Do not allow users to reach the main product in a broken state if onboarding errors mid-flow
- [ ] Do not fire analytics events more than once per step — deduplication matters
- [ ] Do not hard-code copy inside step components — use the content constants file
- [ ] Do not block onboarding completion on non-critical setup steps (e.g., optional profile photo upload)

Acceptance criteria
- [ ] Each step saves its data before the user advances to the next step
- [ ] Skipped steps apply the correct default values and do not leave the user in a broken state
- [ ] Refreshing the page mid-flow returns the user to their current step with no data loss
- [ ] Users who have already completed the flow are not shown it again on subsequent logins
- [ ] Analytics events fire once per step, on completion (not on load)
- [ ] Email triggers fire at the correct step and only once per user
- [ ] The flow handles the invited-user path correctly if in scope
- [ ] The exit destination after flow completion is correct for all completion and skip paths
- [ ] Existing tests pass without modification