# Phase 7: Setup Wizard - Context

**Gathered:** 2026-04-20
**Status:** Ready for planning

<domain>
## Phase Boundary

A new user can set up their budget template in under 3 minutes by following a guided 3-step wizard with pre-filled common items and a live running balance. The wizard auto-redirects first-run users (detected by useFirstRunState), creates categories and template items on completion, persists state across refreshes, and supports skip at any point. Bilingual (EN/DE) via existing i18n system.

</domain>

<decisions>
## Implementation Decisions

### Wizard Layout & Navigation
- Numbered horizontal stepper (1-2-3 bar at top) — minimal, clear progress indicator
- Centered card layout (max-w-2xl) on clean background — consistent with auth pages
- Next/Back buttons at bottom + step indicator is clickable for going back
- Same centered card on mobile, full-width breakpoint — project is desktop-first

### Income Step (Step 1)
- Single "monthly net income" number input — simplest mental model
- Pre-filled with 3000 (PRESETS salary default), user can clear and type their own
- Show user's profile currency (EUR) from useAuth/profile next to input
- Required field, must be > 0, numeric only — can't proceed without income entered

### Recurring Items Step (Step 2)
- Full checklist: all 19 PRESETS shown, grouped by category type, with item name + category badge + editable amount per row
- Bills (4) + variable_expense (5) pre-checked by default — focuses on spending categories the wizard is about
- Income/debt/saving/investment items unchecked by default
- Sticky bar at top: "Remaining to allocate: Income - sum(checked) = X" — turns red when negative
- Inline number input per item, only editable when item is checked

### Review Step & Completion (Step 3)
- Read-only summary card: income at top, grouped checked items with amounts below, total and remaining at bottom
- "Complete" creates categories (from checked item types that don't already exist) + template items (from checked items with amounts)
- Does NOT create first month's budget (Phase 8 handles auto-budget creation)
- After completion: redirect to `/` (dashboard) with success toast "Template created! Your first budget will appear automatically."

### Skip & State Persistence
- "Skip" button on each step + global "Skip setup" to exit wizard entirely without creating data
- Wizard state persisted in localStorage keyed by user_id — survives page refresh
- On complete or skip: clear localStorage, mark profiles.setup_completed = true
- Refreshing mid-wizard restores the wizard at the correct step

### Claude's Discretion
- Exact component decomposition (how many sub-components for the wizard)
- Animation/transition between steps (if any)
- Exact styling of category badges and grouping headers
- Toast message wording variations
- Error handling UX for failed API calls during completion

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `src/hooks/useFirstRunState.ts` — detects first-run users (isFirstRun + loading)
- `src/hooks/useCategories.ts` — CRUD for categories (create method available)
- `src/hooks/useTemplate.ts` — CRUD for template items (createItem method available)
- `src/hooks/useAuth.ts` — profile access (currency, locale)
- `src/data/presets.ts` — 19 PresetItem entries with slug, type, defaultAmount, item_tier
- `src/components/ui/card.tsx` — Card component
- `src/components/ui/button.tsx` — Button component
- `src/components/ui/input.tsx` — Input component
- `src/components/ui/badge.tsx` — Badge component (for category type indicators)
- `src/components/ui/sonner.tsx` — Toast notifications
- `src/i18n/en.json` + `de.json` — presets.* keys already translated

### Established Patterns
- Pages are in `src/pages/*.tsx`, routed via React Router
- Hooks use React Query with Supabase client
- Category types: income, bill, variable_expense, debt, saving, investment
- UI uses Tailwind + shadcn/ui components with OKLCH pastel design tokens
- Auth-protected routes via layout wrapper

### Integration Points
- Router: Add `/setup` route, redirect logic in dashboard or layout
- `useFirstRunState()` — gate for redirect (check !loading && isFirstRun)
- `useCategories().create` — create categories on wizard completion
- `useTemplate().createItem` — create template items on wizard completion
- `profiles.setup_completed` — mark true on completion/skip via Supabase update

</code_context>

<specifics>
## Specific Ideas

- Pre-filled common items come from the existing PRESETS array (19 items, already i18n'd)
- The "remaining to allocate" balance = income entered in step 1 minus sum of checked item amounts in step 2
- Wizard must not create duplicate categories if user already has some (edge case: user skipped wizard, manually created categories, then somehow re-enters wizard)
- Phase 6 decisions: round EUR amounts, backfill existing users to setup_completed=true (they never see wizard)

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>