GearBox/.planning/milestones/v2.2-phases/30-onboarding-redesign/30-03-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements
30	03	integration	2	01 02	src/client/routes/__root.tsx src/client/components/OnboardingWizard.tsx	true

Replace the old OnboardingWizard with the new OnboardingFlow in the root route trigger, ensure the onboarding flow triggers correctly on first login, and remove the old wizard component file.

Task 1: Replace OnboardingWizard with OnboardingFlow in root route

- src/client/routes/__root.tsx - src/client/components/OnboardingWizard.tsx - src/client/components/onboarding/OnboardingFlow.tsx Update `src/client/routes/__root.tsx`:

1. Replace the import:

   • Remove: import { OnboardingWizard } from "../components/OnboardingWizard";
   • Add: import { OnboardingFlow } from "../components/onboarding/OnboardingFlow";

2. Find the onboarding rendering logic (around lines 193+). The current code conditionally renders <OnboardingWizard onComplete={...} />. Replace with <OnboardingFlow onComplete={...} />.

The onComplete callback should:

• Dismiss the onboarding overlay (same behavior as current wizard)
• The OnboardingFlow already handles setting onboardingComplete via its internal hooks

The trigger logic stays the same: show onboarding when onboardingComplete !== "true" and user is authenticated. grep "OnboardingFlow" src/client/routes/__root.tsx && ! grep "OnboardingWizard" src/client/routes/__root.tsx && echo "PASS" || echo "FAIL" <acceptance_criteria>

• __root.tsx imports OnboardingFlow from ../components/onboarding/OnboardingFlow
• No import of OnboardingWizard remains in __root.tsx
• <OnboardingFlow onComplete={...} /> replaces <OnboardingWizard onComplete={...} />
• Onboarding trigger condition unchanged: authenticated + onboardingComplete !== "true" </acceptance_criteria>

Task 2: Remove old OnboardingWizard component

- src/client/components/OnboardingWizard.tsx Delete the old onboarding wizard file:

rm src/client/components/OnboardingWizard.tsx

Then verify no other files import it:

grep -r "OnboardingWizard" src/ --include="*.ts" --include="*.tsx"

If any references remain, update them to use OnboardingFlow or remove them. test ! -f src/client/components/OnboardingWizard.tsx && ! grep -r "OnboardingWizard" src/ --include=".ts" --include=".tsx" 2>/dev/null && echo "PASS" || echo "FAIL" <acceptance_criteria>

• src/client/components/OnboardingWizard.tsx file no longer exists
• No references to OnboardingWizard in any .ts or .tsx file under src/ </acceptance_criteria>

Task 3: Verify onboarding trigger logic

- src/client/routes/__root.tsx Verify that the onboarding trigger in `__root.tsx` works correctly with the new flow:

1. The condition for showing onboarding should check:

   • User is authenticated (session exists)
   • onboardingComplete setting is not "true"
   • Onboarding has not been dismissed in this session

2. The onComplete callback should:

   • Set local state to dismiss the onboarding overlay
   • The OnboardingFlow component handles the server-side setting update internally

3. Ensure the OnboardingFlow receives onComplete prop that triggers the root route to stop rendering the overlay.

No changes may be needed if the existing trigger logic already works with the new component signature (both old and new use onComplete: () => void). Verify and adjust only if needed. grep -A5 "onboardingComplete" src/client/routes/__root.tsx | grep -q "OnboardingFlow" && echo "PASS" || echo "FAIL" <acceptance_criteria>

• Onboarding renders when authenticated AND onboardingComplete !== "true"
• OnboardingFlow receives onComplete callback
• After completion, OnboardingFlow no longer renders
• Page behind onboarding is accessible after completion (no stuck overlay) </acceptance_criteria>

1. `bun run lint` passes 2. `bun test` passes 3. `bun run build` succeeds (no dead imports or missing modules) 4. New user (onboardingComplete not set) sees full-screen OnboardingFlow on login 5. After completing onboarding, OnboardingFlow is dismissed and collection is shown 6. Existing user (onboardingComplete = "true") does NOT see onboarding 7. Old OnboardingWizard.tsx file is gone

<success_criteria>

• Old OnboardingWizard replaced with new OnboardingFlow
• Trigger logic preserved — shows for new users, hidden for existing
• Build succeeds with no dead imports
• Clean removal of old component file </success_criteria>

<threat_model>

Threat	Severity	Mitigation
Onboarding overlay stuck on screen (JS error)	Medium	onComplete callback triggers local state dismissal; setting update is secondary
Old wizard references causing build failure	Low	grep verification ensures no stale imports remain
</threat_model>

<must_haves>

• OnboardingWizard replaced by OnboardingFlow in __root.tsx
• Old OnboardingWizard.tsx deleted with no stale references
• Onboarding triggers correctly for new users
• Build succeeds </must_haves>