docs(07): smart discuss context .planning/phases/07-setup-wizard/07-CONTEXT.md

.planning/phases/07-setup-wizard/07-CONTEXT.md

@@ -0,0 +1,103 @@
+# 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>