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

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

<objective>
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.
</objective>

<tasks>

### Task 1: Replace OnboardingWizard with OnboardingFlow in root route
<task type="code">
<read_first>
- src/client/routes/__root.tsx
- src/client/components/OnboardingWizard.tsx
- src/client/components/onboarding/OnboardingFlow.tsx
</read_first>
<action>
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.
</action>
<verify>
<automated>grep "OnboardingFlow" src/client/routes/__root.tsx && ! grep "OnboardingWizard" src/client/routes/__root.tsx && echo "PASS" || echo "FAIL"</automated>
</verify>
<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>

### Task 2: Remove old OnboardingWizard component
<task type="command">
<read_first>
- src/client/components/OnboardingWizard.tsx
</read_first>
<action>
Delete the old onboarding wizard file:

```bash
rm src/client/components/OnboardingWizard.tsx
```

Then verify no other files import it:

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

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

### Task 3: Verify onboarding trigger logic
<task type="code">
<read_first>
- src/client/routes/__root.tsx
</read_first>
<action>
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.
</action>
<verify>
<automated>grep -A5 "onboardingComplete" src/client/routes/__root.tsx | grep -q "OnboardingFlow" && echo "PASS" || echo "FAIL"</automated>
</verify>
<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>
</task>

</tasks>

<verification>
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
</verification>

<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>