feat(onboarding): state-derived onboarding router with resume-on-landing + skip-for-now - #1872
Conversation
…ing + skip-for-now On every authenticated landing, chat home derives the onboarding step from the activation checkpoint predicates (has artists -> artists have socials -> has claimed catalog -> has enabled task) over existing data sources, never a stored wizard cursor (#1867). Incomplete accounts resume the sequence at the first unmet step; an always-visible skip drops to the app with a dismissible session-scoped checklist; activated accounts never see it. Step cards are titled placeholders linking to the existing pages until the step PRs land. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Next review available in: 57 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (5)
📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThe PR adds a state-derived onboarding flow with activation checkpoints, session-scoped skip and dismissal controls, readiness-aware data composition, and conditional sequence or checklist rendering on the home page. ChangesOnboarding state model and derivation
Landing data readiness wiring
Session gate and view selection
Landing-page onboarding UI
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant HomePage
participant useOnboardingGate
participant useOnboardingState
participant getOnboardingView
participant OnboardingSequence
participant OnboardingChecklist
HomePage->>useOnboardingGate: request onboarding view and callbacks
useOnboardingGate->>useOnboardingState: derive readiness, step, and checkpoints
useOnboardingGate->>getOnboardingView: evaluate readiness and session flags
getOnboardingView-->>useOnboardingGate: return none, sequence, or checklist
useOnboardingGate-->>HomePage: return onboarding state and actions
HomePage->>OnboardingSequence: render incomplete step when view is sequence
HomePage->>OnboardingChecklist: render checklist when view is checklist
Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 773ee81c82
ℹ️ 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".
| export function useOnboardingState(): OnboardingState { | ||
| const { authenticated } = usePrivy(); | ||
| const { artists, isLoading: artistsLoading } = useArtistProvider(); | ||
| const catalogsQuery = useCatalogs(); |
There was a problem hiding this comment.
When a user has already loaded / with no catalogs and then claims a catalog through valuation/chat/API or another tab, this reuses useCatalogs(), whose query is treated as fresh for 5 minutes (hooks/useCatalogs.ts sets staleTime: 5 * 60 * 1000 and disables focus refetch). Returning to / within that window keeps catalogsQuery.isSuccess true with cached [], so getOnboardingStep still shows the catalog step instead of advancing from the DB, which breaks the intended state-derived resume behavior.
Useful? React with 👍 / 👎.
| // app instead of mis-deriving a step from partial state. | ||
| const isReady = | ||
| authenticated && | ||
| !artistsLoading && |
There was a problem hiding this comment.
If /api/artists errors after auth, useArtistsRoster supplies artists = [] and exposes only isPending as isLoading; once the errored query is no longer pending, this condition marks onboarding ready as soon as catalogs/tasks succeed. The gate then derives the first step as artists from partial state and replaces home with the sequence, even though failed checkpoint fetches are supposed to fail open to the normal app.
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 17 files
Confidence score: 5/5
- Safe to merge after the addressed issues were fixed.
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
Why are both these changes added explicitly to the home page instead of to the global layout? Is there a reason we're applying this to one specific page route instead of globally across the app pages?
There was a problem hiding this comment.
Deliberate for slice 1, but it's a fair challenge. Three reasons it's on HomePage rather than the global layout: (1) the sequence must not intercept its own step pages — /catalogs/{id} (the report the valuation email deep-links to), /onboarding/*, /artists, /tasks are all pages the sequence sends users to; a global gate would need an exclusion list to avoid trapping users in a loop, and that list doesn't stabilize until the step PRs land. (2) Home is where the documented failure lives — the issue's repro is 'returning user lands on a blank chat box', and / is the app's default landing. (3) Smallest blast radius while the router's derivation logic gets its first prod exposure.
Agreed on the end state though: once the step pages are merged, promoting the checklist to the global authenticated layout is cheap and safe (it's non-intercepting), and the sequence gate can go global behind an exclusion set of sequence-owned + public routes. Proposing that as a follow-up item on #1867 rather than expanding this PR.
|
Preview verification — 2026-07-20 · preview
Screenshots (assets branch Scenario 2 — fresh account lands on the sequence at the derived step: Scenario 3 — skip drops to the app with the pinned checklist: Scenario 6 — checklist still present after Dismiss (bug): Root cause for scenario 1 (pre-existing, NOT this PR's code): during first-ever sign-in the app fired Infra note: preview sign-ins were blocked for ~6 weeks by the preview Privy test app ( Next on this PR: fixing the Dismiss bug plus the cubic review findings (account-scoped skip state, storage-safe wrapper, catalogs staleness, roster-error fail-open, heading hierarchy) — will push and re-verify. |
…unt-scoped session flags, storage safety, fresh catalogs per landing, roster-error fail-open, h3 card heading Fixes the preview-verified dismiss bug and all cubic findings on #1872: - Dismiss live bug: the checklist was position:fixed to the viewport, so the z-[65] ArtistsSidebar rail overlapped its right edge and clipped the dismiss button off-screen. Now absolute within the (relative) home content area. Gate state was already single-owner (HomePage passes callbacks down) — locked in with a HomePage-level dismiss/skip/resume test. - P1 cross-account leak: skip/dismiss sessionStorage keys are scoped by account id and re-derived when the account in the tab changes (useOnboardingSessionFlags). - P2 storage safety: read/write go through safe helpers that no-op on throwing storage so the gate fails open instead of crashing. - P2 catalogs staleness: useRefreshCatalogsOnLanding invalidates the catalogs cache on onboarding mount for one fresh read per landing; useCatalogs behavior unchanged for other consumers. - P2 roster-error fail-open: useArtistsRoster now exposes isError; deriveOnboardingState keeps isReady false on roster error so the view resolves to none. - P3 hook length: projection extracted to pure deriveOnboardingState. - P3 heading hierarchy: step card h1 -> h3 under the container h2. Tests: TDD red-first; +26 tests (jsdom + @testing-library/react added as devDeps; vitest include extended to .test.tsx). 174 passing; tsc clean apart from the 7 pre-existing main errors in lib/emails tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Review fixes — all findings addressed in
Verification: TDD red-first for every change (7 new test files failing before implementation). Still to re-verify on preview: the checklist's new in-content position (Dismiss reachable, card fully visible next to the rail) — the layout aspect can't be proven in jsdom. 🤖 Generated with Claude Code |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
components/Onboarding/OnboardingChecklist.tsx (1)
3-3: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse Radix UI icons for UI component indicators.
These UI components currently import structural indicators from Lucide React. As per coding guidelines:
Use@radix-ui/react-iconsfor UI component icons (not Lucide React).
components/Onboarding/OnboardingChecklist.tsx#L3-L3: Replace theXicon import fromlucide-reactwith the equivalent from@radix-ui/react-icons(e.g.,Cross2Icon).components/Onboarding/OnboardingCheckpointList.tsx#L3-L3: Replace theCheckicon import fromlucide-reactwith the equivalent from@radix-ui/react-icons(e.g.,CheckIcon).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@components/Onboarding/OnboardingChecklist.tsx` at line 3, Replace the Lucide React X import in components/Onboarding/OnboardingChecklist.tsx at lines 3-3 with the equivalent Cross2Icon from `@radix-ui/react-icons`, and replace the Check import in components/Onboarding/OnboardingCheckpointList.tsx at lines 3-3 with CheckIcon from the same package; update usages as needed while preserving the existing indicator behavior.Source: Coding guidelines
components/Onboarding/OnboardingStepCard.tsx (1)
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winExport explicit props interfaces extending
React.ComponentProps.The new components do not follow the strict architectural pattern for component properties. As per coding guidelines:
Extend native HTML attributes using React.ComponentProps<"element"> patternandExport component prop types with explicit ComponentNameProps naming convention.
components/Onboarding/OnboardingStepCard.tsx#L13-L13: ExportOnboardingStepCardPropsextendingReact.ComponentProps<"section">and spread...propsonto the section element.components/Onboarding/OnboardingCheckpointList.tsx#L12-L16: ExportOnboardingCheckpointListPropsextendingReact.ComponentProps<"ul">and spread...propsonto the ul element.components/Onboarding/OnboardingChecklist.tsx#L7-L11: ExportOnboardingChecklistPropsextendingReact.ComponentProps<"aside">and spread...propsonto the aside element.components/Home/HomePage.tsx#L11-L11: ExportHomePagePropsextendingReact.ComponentProps<"div">and spread...propsonto the root div element.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@components/Onboarding/OnboardingStepCard.tsx` at line 13, Update components/Onboarding/OnboardingStepCard.tsx:13 to export OnboardingStepCardProps extending React.ComponentProps<"section">, accept those props alongside step, and spread ...props onto the root section. Apply the same pattern to components/Onboarding/OnboardingCheckpointList.tsx:12-16 with exported OnboardingCheckpointListProps extending React.ComponentProps<"ul"> and spread props on the ul; components/Onboarding/OnboardingChecklist.tsx:7-11 with exported OnboardingChecklistProps extending React.ComponentProps<"aside"> and spread props on the aside; and components/Home/HomePage.tsx:11 with exported HomePageProps extending React.ComponentProps<"div"> and spread props on the root div.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@components/Onboarding/OnboardingChecklist.tsx`:
- Line 3: Replace the Lucide React X import in
components/Onboarding/OnboardingChecklist.tsx at lines 3-3 with the equivalent
Cross2Icon from `@radix-ui/react-icons`, and replace the Check import in
components/Onboarding/OnboardingCheckpointList.tsx at lines 3-3 with CheckIcon
from the same package; update usages as needed while preserving the existing
indicator behavior.
In `@components/Onboarding/OnboardingStepCard.tsx`:
- Line 13: Update components/Onboarding/OnboardingStepCard.tsx:13 to export
OnboardingStepCardProps extending React.ComponentProps<"section">, accept those
props alongside step, and spread ...props onto the root section. Apply the same
pattern to components/Onboarding/OnboardingCheckpointList.tsx:12-16 with
exported OnboardingCheckpointListProps extending React.ComponentProps<"ul"> and
spread props on the ul; components/Onboarding/OnboardingChecklist.tsx:7-11 with
exported OnboardingChecklistProps extending React.ComponentProps<"aside"> and
spread props on the aside; and components/Home/HomePage.tsx:11 with exported
HomePageProps extending React.ComponentProps<"div"> and spread props on the root
div.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e777091e-aadf-4c45-a576-c4fe77216bd8
⛔ Files ignored due to path filters (15)
components/Home/__tests__/HomePage.onboarding.test.tsxis excluded by!**/*.test.*and included bycomponents/**hooks/__tests__/useOnboardingSessionFlags.test.tsxis excluded by!**/*.test.*and included byhooks/**hooks/__tests__/useRefreshCatalogsOnLanding.test.tsxis excluded by!**/*.test.*and included byhooks/**lib/onboarding/__tests__/deriveOnboardingState.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingCheckpoints.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingFlagKey.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingStep.edge.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingStep.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingStepContent.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/getOnboardingView.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/readOnboardingFlag.test.tsis excluded by!**/*.test.*and included bylib/**lib/onboarding/__tests__/writeOnboardingFlag.test.tsis excluded by!**/*.test.*and included bylib/**package.jsonis excluded by none and included by nonepnpm-lock.yamlis excluded by!**/pnpm-lock.yamland included by nonevitest.config.tsis excluded by none and included by none
📒 Files selected for processing (20)
components/Home/HomePage.tsxcomponents/Onboarding/OnboardingChecklist.tsxcomponents/Onboarding/OnboardingCheckpointList.tsxcomponents/Onboarding/OnboardingSequence.tsxcomponents/Onboarding/OnboardingStepCard.tsxhooks/artists/useArtistsRoster.tshooks/useArtists.tsxhooks/useOnboardingGate.tshooks/useOnboardingSessionFlags.tshooks/useOnboardingState.tshooks/useRefreshCatalogsOnLanding.tslib/onboarding/deriveOnboardingState.tslib/onboarding/getOnboardingCheckpoints.tslib/onboarding/getOnboardingFlagKey.tslib/onboarding/getOnboardingStep.tslib/onboarding/getOnboardingStepContent.tslib/onboarding/getOnboardingView.tslib/onboarding/readOnboardingFlag.tslib/onboarding/types.tslib/onboarding/writeOnboardingFlag.ts
There was a problem hiding this comment.
3 issues found across 24 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="hooks/useOnboardingSessionFlags.ts">
<violation number="1" location="hooks/useOnboardingSessionFlags.ts:24">
P2: An account switch can briefly render the previous account's skip/dismiss state because these values remain in React state until the `[accountId]` effect runs. Deriving or invalidating the flags synchronously for the active account would prevent the wrong onboarding view from flashing when the new account is already ready.</violation>
</file>
<file name="hooks/useRefreshCatalogsOnLanding.ts">
<violation number="1" location="hooks/useRefreshCatalogsOnLanding.ts:17">
P3: Every landing invalidates the entire `catalogs` query-key family rather than the current account's entry, so previously cached accounts are unnecessarily made stale and can incur extra network requests later. Scoping the invalidation to the active `accountId` would preserve the intended fresh read without invalidating unrelated account caches.</violation>
</file>
<file name="lib/onboarding/deriveOnboardingState.ts">
<violation number="1" location="lib/onboarding/deriveOnboardingState.ts:55">
P2: On a landing with cached data, the gate can briefly derive onboarding from stale catalogs/tasks: `useOnboardingState` supplies `catalogsReady`/`tasksReady` from React Query `isSuccess`, which stays true during an `isFetching` background refetch (and catalogs are explicitly invalidated on landing). Including the query fetch state in readiness would keep the gate failed open until refreshed checkpoint data is settled.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| export function useOnboardingSessionFlags( | ||
| accountId: string, | ||
| ): OnboardingSessionFlags { | ||
| const [skipped, setSkipped] = useState(() => |
There was a problem hiding this comment.
P2: An account switch can briefly render the previous account's skip/dismiss state because these values remain in React state until the [accountId] effect runs. Deriving or invalidating the flags synchronously for the active account would prevent the wrong onboarding view from flashing when the new account is already ready.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At hooks/useOnboardingSessionFlags.ts, line 24:
<comment>An account switch can briefly render the previous account's skip/dismiss state because these values remain in React state until the `[accountId]` effect runs. Deriving or invalidating the flags synchronously for the active account would prevent the wrong onboarding view from flashing when the new account is already ready.</comment>
<file context>
@@ -0,0 +1,54 @@
+export function useOnboardingSessionFlags(
+ accountId: string,
+): OnboardingSessionFlags {
+ const [skipped, setSkipped] = useState(() =>
+ readOnboardingFlag("skipped", accountId),
+ );
</file context>
| authenticated && | ||
| !artistsLoading && | ||
| !artistsError && | ||
| catalogsReady && |
There was a problem hiding this comment.
P2: On a landing with cached data, the gate can briefly derive onboarding from stale catalogs/tasks: useOnboardingState supplies catalogsReady/tasksReady from React Query isSuccess, which stays true during an isFetching background refetch (and catalogs are explicitly invalidated on landing). Including the query fetch state in readiness would keep the gate failed open until refreshed checkpoint data is settled.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At lib/onboarding/deriveOnboardingState.ts, line 55:
<comment>On a landing with cached data, the gate can briefly derive onboarding from stale catalogs/tasks: `useOnboardingState` supplies `catalogsReady`/`tasksReady` from React Query `isSuccess`, which stays true during an `isFetching` background refetch (and catalogs are explicitly invalidated on landing). Including the query fetch state in readiness would keep the gate failed open until refreshed checkpoint data is settled.</comment>
<file context>
@@ -0,0 +1,60 @@
+ authenticated &&
+ !artistsLoading &&
+ !artistsError &&
+ catalogsReady &&
+ tasksReady,
+ step: getOnboardingStep(state),
</file context>
| const queryClient = useQueryClient(); | ||
|
|
||
| useEffect(() => { | ||
| queryClient.invalidateQueries({ queryKey: ["catalogs"] }); |
There was a problem hiding this comment.
P3: Every landing invalidates the entire catalogs query-key family rather than the current account's entry, so previously cached accounts are unnecessarily made stale and can incur extra network requests later. Scoping the invalidation to the active accountId would preserve the intended fresh read without invalidating unrelated account caches.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At hooks/useRefreshCatalogsOnLanding.ts, line 17:
<comment>Every landing invalidates the entire `catalogs` query-key family rather than the current account's entry, so previously cached accounts are unnecessarily made stale and can incur extra network requests later. Scoping the invalidation to the active `accountId` would preserve the intended fresh read without invalidating unrelated account caches.</comment>
<file context>
@@ -0,0 +1,19 @@
+ const queryClient = useQueryClient();
+
+ useEffect(() => {
+ queryClient.invalidateQueries({ queryKey: ["catalogs"] });
+ }, [queryClient]);
+}
</file context>
…verification Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Final combined-build verification — 2026-07-20 · preview
Screenshots (assets branch Gate 1 — brand-new signup's very first landing: Gates 4-6 — repositioned checklist with reachable Dismiss: Earlier rounds for comparison: initial matrix (5/7 + two bugs), per-finding fixes, #1876's standalone verification. All merge gates from #1867's quality bar are now met. Ready for merge review. |
…ssible reminder Remove the checklist-dismissed escape hatch entirely. After "skip for now" the bottom-right "Finish setting up" card is now always present while onboarding is incomplete (survives refresh via the session skip flag), and clicking it re-opens the sequence — there is no way to permanently hide it. Net-removal: drops the second session flag, its storage read/write usage, the dismissChecklist callback threading, the X/Dismiss button, and the separate "Resume setup" button (the card header is now the resume trigger). getOnboardingView collapses to two views (sequence | checklist) and OnboardingFlag to a single member. +47 / -134. Full suite 181 pass, tsc clean on touched files, prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
0 issues found across 12 files (changes from recent commits).
Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.
Re-trigger cubic
…utton The checklist header "Finish setting up" is a plain title again (it read as non-clickable). Re-opening the sequence is now a clearly-styled primary "Continue" button at the bottom of the card, replacing the ambiguous click-the-header affordance. Suite 181 pass, tsc clean on touched files, prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
0 issues found across 2 files (changes from recent commits).
Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.
Re-trigger cubic
…t-task emails, add-artist, Kimi K3 (#1880) * feat(onboarding): state-derived onboarding router with resume-on-landing + skip-for-now (#1872) * feat(onboarding): state-derived onboarding router with resume-on-landing + skip-for-now On every authenticated landing, chat home derives the onboarding step from the activation checkpoint predicates (has artists -> artists have socials -> has claimed catalog -> has enabled task) over existing data sources, never a stored wizard cursor (#1867). Incomplete accounts resume the sequence at the first unmet step; an always-visible skip drops to the app with a dismissible session-scoped checklist; activated accounts never see it. Step cards are titled placeholders linking to the existing pages until the step PRs land. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(onboarding): review fixes — checklist clipped by right rail, account-scoped session flags, storage safety, fresh catalogs per landing, roster-error fail-open, h3 card heading Fixes the preview-verified dismiss bug and all cubic findings on #1872: - Dismiss live bug: the checklist was position:fixed to the viewport, so the z-[65] ArtistsSidebar rail overlapped its right edge and clipped the dismiss button off-screen. Now absolute within the (relative) home content area. Gate state was already single-owner (HomePage passes callbacks down) — locked in with a HomePage-level dismiss/skip/resume test. - P1 cross-account leak: skip/dismiss sessionStorage keys are scoped by account id and re-derived when the account in the tab changes (useOnboardingSessionFlags). - P2 storage safety: read/write go through safe helpers that no-op on throwing storage so the gate fails open instead of crashing. - P2 catalogs staleness: useRefreshCatalogsOnLanding invalidates the catalogs cache on onboarding mount for one fresh read per landing; useCatalogs behavior unchanged for other consumers. - P2 roster-error fail-open: useArtistsRoster now exposes isError; deriveOnboardingState keeps isReady false on roster error so the view resolves to none. - P3 hook length: projection extracted to pure deriveOnboardingState. - P3 heading hierarchy: step card h1 -> h3 under the container h2. Tests: TDD red-first; +26 tests (jsdom + @testing-library/react added as devDeps; vitest include extended to .test.tsx). 174 passing; tsc clean apart from the 7 pre-existing main errors in lib/emails tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor(onboarding): make the skip checklist a persistent, non-dismissible reminder Remove the checklist-dismissed escape hatch entirely. After "skip for now" the bottom-right "Finish setting up" card is now always present while onboarding is incomplete (survives refresh via the session skip flag), and clicking it re-opens the sequence — there is no way to permanently hide it. Net-removal: drops the second session flag, its storage read/write usage, the dismissChecklist callback threading, the X/Dismiss button, and the separate "Resume setup" button (the card header is now the resume trigger). getOnboardingView collapses to two views (sequence | checklist) and OnboardingFlag to a single member. +47 / -134. Full suite 181 pass, tsc clean on touched files, prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(onboarding): restore plain title + add explicit "Continue" button The checklist header "Finish setting up" is a plain title again (it read as non-clickable). Re-opening the sequence is now a clearly-styled primary "Continue" button at the bottom of the card, replacing the ambiguous click-the-header affordance. Suite 181 pass, tsc clean on touched files, prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> * feat: post-valuation catalog report on /catalogs/[catalogId] (chat#1867 sequence step 1) (#1873) The marketing valuation CTA landed on a bare Catalog Songs admin screen. /catalogs/{id} now opens as a real catalog report: valuation echo (central value + range via the ported marketing formula), lifetime streams, tracks/releases measured, per-release table with album art, per-section diagnosis + prescription copy, and one primary CTA (set up your weekly report -> /tasks). The existing songs/ISRC management UI stays reachable as a secondary Manage songs tab. Valuation math mirrors marketing/lib/valuation (identical constants; age from the api's catalog_age_years, 5y default). Release rollups are null-safe on album/name/artist metadata independently of the sibling crash-fix PR. Reuses the chat#1852 useCatalogMeasurements hook, extending its response type with the v2 aggregate fields as optionals. Co-authored-by: Claude Fable 5 <noreply@anthropic.com> * feat: roster + socials verification onboarding steps (chat#1867) (#1870) * feat: roster + socials verification onboarding steps (chat#1867) Two self-contained onboarding step components for the chat#1867 sequence, mounted standalone at /onboarding/roster so the slice is user-testable before the onboarding router lands: - ConfirmRosterStep: shows the auto-created artist(s) from the valuation flow, inline "add another artist" for multi-artist managers (existing POST /api/artists endpoint), confirm to advance. - VerifySocialsStep: per rostered artist, lists the auto-matched socials with handle + follower count; each match is confirmed or rejected, wrong matches are fixed by pasting the correct profile link (existing PATCH /api/artists/{id} profileUrls path), and artists with no socials record an explicit "none". Verification state is pure client-side logic (lib/onboarding/*, TDD'd): verdict reducers, per-artist and step-level resolution predicates, PATCH payload building with APPPLE->APPLE platform-key normalization, and a follower-count accessor tolerant of the API's snake_case rows behind chat's camelCase SOCIAL type. No new endpoints, tables, or context providers - hooks compose the existing ArtistProvider / OrganizationProvider / Privy auth. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor(onboarding): simplify verify-socials to accept-by-default (chat#1867) Per design review: drop the per-social Correct/Wrong verdicts, the resolution/gating machinery, and the explicit "This artist has no socials" button. Matches are accepted by default; the only actions are Edit (fix a wrong link, existing PATCH profileUrls path) and — for an artist with no matches — a soft nudge + "Add a profile". Continue always proceeds (empty = implicit none). Deletes the verdict code that would otherwise be merged and immediately removed: socialVerificationTypes, applySocialVerdict, isArtistSocialsResolved, areAllArtistsResolved, markArtistHasNoSocials, findSocialIdByPlatform, useSocialsVerification, SocialVerifyRow (+ their tests). Net −13 files. Note: "Remove/delete a social" (the other half of the design) needs a new api endpoint — the api's PATCH profileUrls is per-platform merge with no delete-social path — tracked as a fast-follow on chat#1867. Full suite 144 pass, tsc clean on touched files, lint + prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(onboarding): always offer Add-a-profile per artist, not just empty ones A matched-social list can still be missing platforms (e.g. Spotify found but no Instagram). Surface 'Add a profile' below every artist's socials, not only when zero were auto-matched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> * feat(onboarding): first-task step — pre-run weekly report + confirm schedule (#1871) Sequence final step for chat#1867 (respec 2026-07-20, pre-run shape): generate the first weekly catalog report immediately through the normal chat pipeline (same POST /api/chat transport a send uses), show it finished, then ask one question — "get this every Monday?". Confirm creates the enabled weekly task via the existing POST /api/tasks path (which also mints the schedule) and shows the next-run time; decline creates nothing. Mounted standalone at /onboarding/first-task so the step is user-testable before the OnboardingSequence container exists. The pre-run prompt and the scheduled task prompt come from one builder, so the preview the user confirms is byte-for-byte what Monday's run uses. Co-authored-by: Claude Fable 5 <noreply@anthropic.com> * feat(onboarding): first-task weekly report actually emails — LA EQUIS template + Kimi K3 (chat#1867) (#1877) * feat(onboarding): first-task weekly report actually emails (LA EQUIS template + Kimi K3) The first-task prompt generated a report but never emailed it (email is a prompt-driven send_email call, and the prompt had no recipient or send instruction) — proven by firing the created task: the agent ran and persisted a report, but email_send_log stayed empty. Generalize buildFirstTaskPrompt from the proven LA EQUIS weekly report (scheduled_action 39fb5f68, running week over week): resolve the artist's Spotify id from its connected profile -> capture this week's play counts -> compute real week-over-week per-track deltas -> build a fully hex-specced inline-CSS HTML email -> send via the recoup-platform-email-helper skill -> confirm the Resend id. Carries the sandbox no-python and anti-fabrication guardrails verbatim (what makes the send reliable). Thread the account email (recipientEmail) + artistAccountId through both callers so the pre-run preview and the Monday scheduled task both send to the account holder. Bump both surfaces from DEFAULT_MODEL (openai/gpt-5.4-mini — completes the data calls but gives up before composing the long HTML email, the LA EQUIS lesson) to a new REPORT_MODEL (moonshotai/kimi-k3), which reliably composes and sends. chat#1867 (first-task email-prompt gap). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(onboarding): default model -> Kimi K3 (KISS); harden email-less + shell paths Address review feedback on #1877: - Sweets (KISS): collapse the new REPORT_MODEL constant into DEFAULT_MODEL — set DEFAULT_MODEL = moonshotai/kimi-k3 app-wide (the fast gpt-5.4-mini default gave up before composing the long HTML report email). Revert both onboarding hooks to DEFAULT_MODEL; relabel the featured picker entry (id: DEFAULT_MODEL) from "GPT-5.4 Mini" to "Kimi K3" so it isn't mislabeled. - CodeRabbit (email-less login): a wallet/phone/social-only Privy account has no email — FirstTaskStep now shows a distinct "add an email" alert (not an infinite "Preparing…"), and useConfirmFirstTask's onError distinguishes EMAIL_REQUIRED from a generic retry. - Codex (shell-safety): artist/track/album names are user-entered; add a prompt guardrail to pass them as single quoted args so a name with quotes/;/$() can't alter the email-helper command. Codex "non-Pro users get rejected" P2 is a false positive: the prior default (gpt-5.4-mini) is also non-free by isFreeModel yet ships as the default, so the API does not hard-block non-free default models. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Update lib/consts.ts * chore(models): refresh featured model list to latest per series Sweets: while touching the featured list, bring every entry to its series' latest (verified present in the AI Gateway catalog): - GPT-5.2 -> GPT-5.5 - Claude Opus 4.5 -> 4.8 - Claude Sonnet 4.5 -> Sonnet 5 - Gemini 2.5 Flash Lite -> Gemini 3.5 Flash Lite - Gemini 3 Pro -> Gemini 3.1 Pro - Grok 4 -> Grok 4.5 (Kimi K3 already latest.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(chat): reuse the real Message renderer in the first-task pre-run (DRY) The onboarding pre-run rendered only the last assistant message's TEXT (getReportTextFromMessages -> <Response>), dropping tool-call and reasoning components — a downgraded, diverging copy of the chat UI. #1877's tool-heavy email workflow made the gap obvious (raw narration, no tool components). Reuse the normal chat's <Message>/<MessageParts> so tool calls/results get their real components. MessageParts was coupled to useVercelChatContext (status + reload); decouple it: both are now optional props with a context fallback, so the normal chat is behaviorally unchanged (props omitted -> context used) while the pre-run supplies them without mounting a provider (VercelChatProvider owns its own useChat instance, so wrapping the pre-run would double the chat). - VercelChatProvider: export VercelChatContext for the optional read. - MessageParts/Message: optional status/reload props, fall back to context. - useFirstTaskReport: expose messages + status. - FirstTaskReportRun: render assistant messages via <Message> (filtering out the auto-sent prompt user message), not a text dump. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(artists): Add New Artist opens a shared Spotify search — kills the /artists loop (chat#1867) (#1878) * fix(artists): Add New Artist opens a shared Spotify search (kills the /artists loop) "Add New Artist" (and the sidebar/header equivalents) called toggleCreation, which pushed `/?q=create a new artist` and relied on the home CHAT to interpret it. The onboarding router (chat#1872) now intercepts the home for incomplete accounts and renders "Finish setting up" instead, so the query never ran — the "Open your roster" CTA bounced back to /artists → infinite loop. Replace the redirect with a shared Spotify artist-search dialog: - lib/spotify/parseSpotifyArtistResults.ts — pure parser for the GET /api/spotify/search?type=artist envelope (id/name/imageUrl/profileUrl/followers). - lib/artists/addSpotifyArtist.ts — create by name (POST /api/artists) then link the Spotify image + profile URL (PATCH), so the roster gets real data. - useSpotifyArtistSearch (debounced, abortable) + useAddSpotifyArtist hooks. - components/Artists/SpotifyArtistSearch.tsx — the shared typeahead (reused next for social enrichment + verify-socials). - components/Artists/AddArtistDialog.tsx — global dialog, mounted in layout. - useArtistMode.toggleCreation now opens the dialog (isCreationOpen/closeCreation) instead of the redirect — fixes /artists, sidebar, and header at once. TDD: parseSpotifyArtistResults 5/5, addSpotifyArtist 2/2, red→green. tsc clean on touched files, eslint/prettier clean. chat#1867 (/artists add-artist loop). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(artists): reuse canonical Spotify types; drop redundant parser (−106 LOC) Simplification pass on the add-artist slice: - Delete lib/spotify/parseSpotifyArtistResults.ts (+ its 5 tests) and the custom SpotifyArtistResult type — types/spotify.ts already exports SpotifySearchResponse ({ artists?: { items: SpotifyArtistSearchResult[] } }) and SpotifyArtistSearchResult (id/name/external_urls/images/followers). useSpotifyArtistSearch now reads `data.artists?.items` directly and returns the canonical type; the component and addSpotifyArtist read images[0].url / followers.total / external_urls.spotify inline. Kept (checked, "no simpler"): addSpotifyArtist's two-step create→link, because POST /api/artists only accepts a name; and useSpotifyArtistSearch, since there is no existing debounced-search hook to reuse. Net -106 LOC; behavior unchanged; addSpotifyArtist 2/2 green, tsc 0 new. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(onboarding): seed the catalog by kicking /api/valuation on first artist add (chat#1867) (#1879) * feat(onboarding): seed the catalog by kicking /api/valuation on first artist add Closes the onboarding catalog dead-end for direct signups. When the first artist is added via the Spotify search (#1878 already links their Spotify profile), useAddSpotifyArtist now fire-and-forget kicks POST /api/valuation { spotify_artist_id } (api#776) — only when the account has no catalog yet — which materializes the catalog + value band in ~20s. So the "Claim your catalog" step is already complete by the time the user reaches it, and they flow through to the first-task step (weekly report emails). - lib/valuation/runValuation.ts — client POST /api/valuation (TDD 2/2). - hooks/useAddSpotifyArtist.ts — background kick on first add (gated on an empty, loaded catalogs query), surfaced via a toast.promise ("Valuing … → Your catalog is ready"), invalidating the catalogs query on success so the sequence advances. chat#1867 (seed onboarding catalog on first artist add). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(models): fix organizeModels fixture — featured id gpt-5.2 → gpt-5.5 (post-#1877) The featured-models refresh in #1877 replaced openai/gpt-5.2 with openai/gpt-5.5, but organizeModels.test.ts still asserted gpt-5.2 was featured — failing CI on test. Update the fixture + assertion to a currently-featured id. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 participant
Part of #1867 ("State-derived onboarding router: resume-on-landing + skip-for-now").
What
On every authenticated landing on chat home, the app derives the account's onboarding step from the activation checkpoint predicates and routes accordingly:
Checkpoint predicates (in sequence order), all over existing data:
artistsfetchArtists(account_artist_ids)socialsaccount_socialson the roster responsecataloggetCatalogs(account_catalogs)taskgetTasks(scheduled_actions.enabled)Derived, never stored
Per the issue's architecture decision: there is no
onboarding_stepcolumn and no wizard cursor. The step is a pure function of account state recomputed on every landing, so:sessionStorage), not persisted state: the next visit re-derives and resumes by default.The gate also fails open: while any checkpoint source is loading or errored, the normal app renders, so the sequence never flashes for activated accounts and a failed fetch never walls anyone off.
Structure
lib/onboarding/getOnboardingCheckpoints.ts- the four predicates -> checkpoint flags (pure)lib/onboarding/getOnboardingStep.ts- first unmet checkpoint -> step enum (pure, core logic)lib/onboarding/getOnboardingView.ts- {isReady, step, skipped, dismissed} -> none | sequence | checklist (pure)lib/onboarding/getOnboardingStepContent.ts- placeholder card copy + link per stephooks/useOnboardingState.ts- composes existing data hooks (useArtistProvider,useCatalogs,useScheduledActions) into derived statehooks/useOnboardingGate.ts- view decision + session-scoped skip/resume/dismisscomponents/Onboarding/*- sequence container, step placeholder card, checkpoint list, pinned checklistcomponents/Home/HomePage.tsx- chat-home integration pointStep cards are titled placeholders (purpose + link to the existing page where the step can be completed today); each step's real in-sequence experience ships in the sibling PRs on #1867, slotting into this frame.
Tests
TDD (failing tests first, then implementation). 18 new unit tests in
lib/onboarding/__tests__/:getOnboardingStep: all 16 predicate combinations against the spec's priority order, plus null/undefined/empty socials, per-artist socials requirement, disabled and paused (null-enabled) tasks, out-of-band advancement (valuation auto-claim lands ontask), fully-activated ->complete, determinism.getOnboardingCheckpoints: order, independence of flags, socials incomplete while roster empty.getOnboardingView: loading -> none, activated -> never, resume-by-default, skip -> checklist, dismiss -> none.getOnboardingStepContent: every step has title/description/link to an existing route.Verification
pnpm exec vitest run: 40 files / 148 tests, all green (130 pre-existing + 18 new).pnpm exec tsc --noEmit: 8 errors, all pre-existing onmain(verified identical with this change stashed); 0 in new files.pnpm build(local): webpack compile passed and the build's TypeScript phase passed (no type errors); the build then fails at "Collecting page data" for/api/agent-creatorwithMissing Supabase credentials: { hasUrl: false, hasKey: false }- environmental (this checkout has no.env, only.env.example), unrelated to this client-side change and identical without it. The Vercel preview build (which has env) is the authoritative build check.next lintis broken onmain:Invalid project directory ... /lint).How to test on preview
/shows the sequence at its derived step (e.g. "Schedule your first report" with earlier checkpoints ticked). Complete a step out-of-band (e.g. create a task via API/chat), reload -> the sequence auto-advances or disappears.🤖 Generated with Claude Code
Summary by cubic
Adds a state-derived onboarding router that resumes on landing and supports “skip for now.” After skip, a pinned checklist stays visible until setup is complete; a “Continue” button re-opens onboarding. Activated accounts go straight to chat.
New Features
useOnboardingGate: incomplete accounts see the sequence; after skip, a persistent pinned checklist appears with a clear “Continue” button to resume.Bug Fixes
isErrorandderiveOnboardingState.Written for commit ea068a8. Summary will update on new commits.
Summary by CodeRabbit