feat: Onboarding MVP #1499

sidneyswift · 2026-01-28T21:12:57Z

Summary

Implements complete onboarding flow for new org users
8-step guided experience: Welcome → Role → Artists → Task Picker → Running → Result → Recurring → Complete
Persists state to localStorage, syncs to account on completion
Auto-redirects new org users to onboarding

Changes (16 User Stories)

US-001: /onboarding route with distraction-free layout
US-002: useOnboarding hook for state management
US-003: OnboardingFlow orchestrator component
US-004: Progress indicator (step X of 8)
US-005: WelcomeStep - name input
US-006: RoleStep - role selection (Manager, Label/A&R, Marketing, etc.)
US-007: ArtistsStep - priority artist selection (1-3)
US-008: Onboarding task templates in agent_templates
US-009: runOnboardingTask helper function
US-010: TaskPickerStep - select automation task
US-011: RunningStep - task execution with progress animation
US-012: ResultStep - display task results
US-013: RecurringStep - set up recurring automation
US-014: CompleteStep - confirmation and redirect
US-015: Account API updates for onboarding data
US-016: Auto-redirect for users needing onboarding

Test plan

Visit /onboarding as a new org user
Complete all 8 steps
Verify task runs and emails results
Verify recurring task is created (if selected)
Verify redirect to dashboard after completion
Verify returning users are not redirected to onboarding

🤖 Generated with Claude Code

- Create app/onboarding/page.tsx that renders <OnboardingFlow /> component - Create app/onboarding/layout.tsx with fixed positioning to hide Sidebar/ArtistsSidebar - Create components/Onboarding/OnboardingFlow.tsx placeholder component - Layout uses essential providers from root (Privy, Theme, User) via inheritance Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Create hooks/useOnboarding.tsx with OnboardingState interface - State includes: step, name, role, priorityArtists, selectedTask, taskResult, taskError, recurring - Provides setters for each field plus nextStep, prevStep, goToStep functions - Persists state to localStorage key 'recoup-onboarding' on every change - Restores state from localStorage on mount - Provides complete() function that calls account update API and clears localStorage - Update account update API to accept onboarding_data and onboarding_status fields Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Create OnboardingProgress.tsx with step indicator, progress bar, and step dots - Update OnboardingFlow.tsx to render progress above step content - Use brand primary color #345A5D for progress visualization - Show current step number out of total steps (e.g. "Step 2 of 8") Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Implement WelcomeStep with name input and org greeting - Shows "Welcome to Recoup! I'm your AI assistant for [Org Name]" - Shows "What should I call you?" with name input field - Pre-fills name from onboarding state or user data - Continue button disabled until name is entered - Uses useAccountOrganizations and useOrganization for org name - Adds placeholder step components (to be implemented in subsequent stories) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Implement RoleStep with: - Personalized greeting using name from onboarding state - 6 role cards in grid layout: Manager, Label/A&R, Marketing, PR/Publicist, Artist, Other - Single-select with visual highlight on selected card - Back and Continue buttons with brand primary color #345A5D - Continue disabled until a role is selected - Persists selection to localStorage via setRole() on continue Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Shows org roster with artist selection (1-3 artists) - Displays artist cards in grid with Avatar and Name - Multi-select with visual highlight for selected artists - Fetches artists via API with org ID context - Pre-fills from saved onboarding state - Handles loading and empty states gracefully Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Add fetchOnboardingTemplates.ts to fetch templates with 'onboarding' tag - Add filterTemplatesByRole.ts to filter by role:* tags - Add interpolatePrompt.ts to replace {artistName} and {userEmail} placeholders - Add barrel export in index.ts Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Add /api/onboarding-templates endpoint to fetch templates - Implement full TaskPickerStep with template fetching via API - Filter templates by user role using filterTemplatesByRole helper - Single-select UI with visual highlight for selected task - Includes loading skeleton, error state with retry, empty state with skip - Convert AgentTemplateRow to AgentTemplate for onboarding state Co-Authored-By: Claude Opus 4.5 <[email protected]>

Implements the RunningStep component that executes the user's first automated task during onboarding. Features include: - Animated spinner with brand color styling - Animated progress steps (Researching → Analyzing → Sending email) - Integration with runOnboardingTask helper and chat/generate API - Error state with "Try again" and "Skip for now" buttons - 60-second timeout warning with skip option - Fetches first priority artist name for prompt interpolation Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Show task result from onboarding state in readable format - Display success icon with brand color - Show 'I just sent this to [email]' notification - Back button allows retry, Continue progresses flow - Handle null taskResult case for skipped tasks Co-Authored-By: Claude Opus 4.5 <[email protected]>

Implement the recurring task setup step with: - 4 frequency options: weekly, biweekly, monthly, none - Radio button UI with visual selection state - Task creation via TASKS_API_URL when frequency selected - Interpolates prompt with artist name and user email - Cron schedule configuration for each frequency - Pre-fill from saved state for back navigation - Loading state during task creation Co-Authored-By: Claude Opus 4.5 <[email protected]>

Implement the final onboarding step with: - Celebration emoji and "You're all set!" message - Conditional messaging based on recurring frequency selection - "Go to Dashboard" button that calls complete() to persist onboarding data and redirects to home Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Create needsOnboarding.ts helper function to check if user needs onboarding - Create OnboardingGuard component to redirect new org users to /onboarding - Add OnboardingGuard to Providers hierarchy inside ArtistProvider - Auto-select first priority artist when completing onboarding - Skip redirect if already on /onboarding route or already completed onboarding Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel · 2026-01-28T21:13:04Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
recoup-chat	Ready	Preview	Jan 28, 2026 9:16pm

coderabbitai · 2026-01-28T21:13:06Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🔍 Trigger a full review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f02c39262

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-01-28T21:17:36Z

components/Onboarding/steps/RunningStep.tsx

+    // Fetch artist name first, then run task
+    const init = async () => {
+      await fetchArtistName();
+      runTask();


Use fetched artist name before starting task

In RunningStep, the task is started immediately after await fetchArtistName(), but fetchArtistName only calls setArtistName, which updates state asynchronously. That means runTask still reads the old artistName value from its closure (defaulting to "Artist"), so the onboarding prompt won’t include the real artist name on the first run. This occurs whenever the artist fetch succeeds and the task starts in the same tick. Consider returning the fetched name and passing it into runOnboardingTask, or triggering runTask after the artistName state update is applied.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-01-28T21:17:36Z

components/Onboarding/OnboardingGuard.tsx

+    // Parse onboarding_status from userData
+    const onboardingStatus = userData.onboarding_status as
+      | OnboardingStatus
+      | null
+      | undefined;


Refresh onboarding status before redirect guard

The guard bases its redirect decision on userData.onboarding_status, but the completion flow only posts to /api/account/update and does not refresh userData in the same session. As a result, right after onboarding completion, the first navigation to / can still look incomplete to this guard and bounce the user back to /onboarding until a full reload. Consider updating userData with the completion response or checking a local completion flag so the guard reflects the just-finished state.

Useful? React with 👍 / 👎.

sidneyswift and others added 14 commits January 28, 2026 14:39

feat: [US-009] Create runOnboardingTask helper function

711095d

Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel bot deployed to Preview – recoup-chat January 28, 2026 21:16 View deployment

chatgpt-codex-connector bot reviewed Jan 28, 2026

View reviewed changes

sidneyswift mentioned this pull request Jan 28, 2026

feat: Seed onboarding task templates recoupable/database#4

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Onboarding MVP #1499

feat: Onboarding MVP #1499

Uh oh!

sidneyswift commented Jan 28, 2026

Uh oh!

vercel bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 28, 2026

Review skipped

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Jan 28, 2026

Uh oh!

chatgpt-codex-connector bot Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

feat: Onboarding MVP #1499

Are you sure you want to change the base?

feat: Onboarding MVP #1499

Uh oh!

Conversation

sidneyswift commented Jan 28, 2026

Summary

Changes (16 User Stories)

Test plan

Uh oh!

vercel bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 28, 2026

Review skipped

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel bot commented Jan 28, 2026 •

edited

Loading