docs(phase-07): complete phase execution

- SUMMARY.md with execution results and deviation documentation

.planning/ROADMAP.md

@@ -13,8 +13,8 @@ This milestone transforms SimpleFinanceDash from a visually polished but cogniti
 Decimal phases appear between their surrounding integers in numeric order.
 
 - [ ] **Phase 5: Design System Token Rework** - Replace rounded corners with sharp edges and refine OKLCH pastel tokens across all 9 pages
-- [ ] **Phase 6: Preset Data, First-Run Detection, and DB Safety** - Seed preset library, build first-run hook, and add DB uniqueness constraints that protect against duplicate data
+- [x] **Phase 6: Preset Data, First-Run Detection, and DB Safety** - Seed preset library, build first-run hook, and add DB uniqueness constraints that protect against duplicate data
-- [ ] **Phase 7: Setup Wizard** - 3-step first-run wizard with income, pre-filled recurring items, and review — skippable, state-persisted, bilingual
+- [x] **Phase 7: Setup Wizard** - 3-step first-run wizard with income, pre-filled recurring items, and review — skippable, state-persisted, bilingual (completed 2026-04-20)
 - [ ] **Phase 8: Auto-Budget Creation** - Auto-create current month's budget from template on dashboard visit, with correct currency and first-creation toast
 - [ ] **Phase 9: Inline Add and Dashboard Simplification** - Replace Quick Add page with inline Sheet panel, simplify dashboard to at-a-glance view, add empty states
 
@@ -29,7 +29,11 @@ Decimal phases appear between their surrounding integers in numeric order.
   2. Category color swatches are visibly colorful against white backgrounds — not washed-out or grey-tinted — and still pass WCAG 4.5:1 contrast for text
   3. Page layouts feel uncluttered — content sections have consistent whitespace gaps and no visual crowding between cards or sections
   4. A full visual pass of all 9 pages (Dashboard, Budget List, Budget Detail, Template, Categories, Quick Add, Settings, Login, Register) confirms no regressions from token changes
-**Plans**: TBD
+**Plans:** 3 plans
+Plans:
+- [x] 05-01-PLAN.md — Design tokens (radius, colors, chart vars) and chart component Bar radius updates
+- [x] 05-02-PLAN.md — Shared component rounded-* removal and spacing upgrades (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker)
+- [x] 05-03-PLAN.md — Per-page sweep (all 9 pages) for rounded-* removal, spacing upgrades, and visual verification checkpoint
 
 ### Phase 6: Preset Data, First-Run Detection, and DB Safety
 **Goal**: The data layer is safe and ready — duplicate budget/category writes are impossible at the DB level, and the app correctly identifies first-run users
@@ -41,7 +45,11 @@ Decimal phases appear between their surrounding integers in numeric order.
   3. All existing v1.0 users have `profiles.setup_completed = true` after the backfill migration runs — they will not be shown the wizard on their next login
   4. `useFirstRunState` hook returns `true` only for users with zero categories or zero template items — returning `false` for any user with existing data
   5. `src/data/presets.ts` contains ~15-20 curated budget items with sensible default amounts, grouped by category type, with both English and German i18n translation keys defined
-**Plans**: TBD
+**Plans:** 3 plans
+Plans:
+- [x] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
+- [x] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
+- [x] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
 
 ### Phase 7: Setup Wizard
 **Goal**: 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
@@ -53,7 +61,10 @@ Decimal phases appear between their surrounding integers in numeric order.
   3. A "remaining to allocate" balance updates live as items are checked or unchecked in step 2, showing income minus the sum of selected item amounts
   4. User can click "Skip" on any individual step or "Skip setup" to exit the wizard entirely without creating any data — and lands on the dashboard
   5. Completing the wizard creates a populated template from selected items — user lands on the dashboard with their template in place, and refreshing the browser mid-wizard restores the wizard at the correct step
-**Plans**: TBD
+**Plans:** 2/2 plans complete
+Plans:
+- [x] 07-01-PLAN.md — Wizard state hook, i18n keys, stepper + step 1/2 UI components (income, recurring items, allocation bar)
+- [x] 07-02-PLAN.md — ReviewStep, completion logic, skip handling, /setup route, first-run redirect, and verification checkpoint
 
 ### Phase 8: Auto-Budget Creation
 **Goal**: Users never manually trigger budget creation — visiting a month for the first time automatically creates their budget from the template, silently and correctly
@@ -64,7 +75,11 @@ Decimal phases appear between their surrounding integers in numeric order.
   2. The first time a budget is auto-created in a session, a toast notification appears naming the month and indicating it was created from the template — subsequent months are created silently
   3. The auto-created budget uses the user's configured currency from their profile settings, not a hardcoded default
   4. Rapidly navigating between months or opening the dashboard in two tabs does not produce duplicate budget rows
-**Plans**: TBD
+**Plans:** 3 plans
+Plans:
+- [ ] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
+- [ ] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
+- [ ] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
 
 ### Phase 9: Inline Add and Dashboard Simplification
 **Goal**: Users add one-off items to their budget directly from the budget view, the Quick Add page is gone, and the dashboard shows this month's data at a glance without chart overload
@@ -76,7 +91,11 @@ Decimal phases appear between their surrounding integers in numeric order.
   3. The dashboard displays this month's summary cards (income, expenses, balance) with correct totals that match what the user entered in the budget detail page
   4. The dashboard does not show the 3-column chart grid by default — the primary view is the at-a-glance summary and collapsible category sections
   5. Empty template, empty dashboard, and empty budget view each show a clear empty state with a visible call-to-action guiding the user to the next step
-**Plans**: TBD
+**Plans:** 3 plans
+Plans:
+- [ ] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
+- [ ] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
+- [ ] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
 
 ## Requirements Traceability
 
@@ -109,8 +128,8 @@ Phases execute in numeric order: 5 → 6 → 7 → 8 → 9
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 5. Design System Token Rework | 0/? | Not started | - |
+| 5. Design System Token Rework | 0/3 | Planned | - |
-| 6. Preset Data, First-Run Detection, DB Safety | 0/? | Not started | - |
+| 6. Preset Data, First-Run Detection, DB Safety | 3/3 | Complete | 2026-04-20 |
-| 7. Setup Wizard | 0/? | Not started | - |
+| 7. Setup Wizard | 2/2 | Complete    | 2026-04-20 |
 | 8. Auto-Budget Creation | 0/? | Not started | - |
 | 9. Inline Add and Dashboard Simplification | 0/? | Not started | - |

.planning/STATE.md

@@ -1,17 +1,17 @@
 ---
 gsd_state_version: 1.0
 milestone: v2.0
-milestone_name: UX Simplification & Design Rework
+milestone_name: milestone
-status: ready_to_plan
+status: executing
-stopped_at: null
+stopped_at: Completed 06-03-PLAN.md — Phase 06 fully executed
-last_updated: "2026-04-02T00:00:00.000Z"
+last_updated: "2026-04-20T19:15:23.317Z"
-last_activity: 2026-04-02
+last_activity: 2026-04-20
 progress:
   total_phases: 5
-  completed_phases: 0
+  completed_phases: 3
-  total_plans: 0
+  total_plans: 8
-  completed_plans: 0
+  completed_plans: 8
-  percent: 0
+  percent: 100
 ---
 
 # Project State
@@ -21,20 +21,21 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-02)
 
 **Core value:** Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product.
-**Current focus:** Phase 5 — Design System Token Rework
+**Current focus:** Phase 7 — Setup Wizard
 
 ## Current Position
 
-Phase: 5 of 9 overall (1 of 5 in v2.0)
+Phase: 8
 Plan: Not started
-Status: Ready to plan
+Status: Executing Phase 7
-Last activity: 2026-04-02 — v2.0 roadmap created, 5 phases defined
+Last activity: 2026-04-20
 
-Progress: [░░░░░░░░░░░░░░░░░░░░] 0/? plans (0%)
+Progress: [████████████████████] 3/3 plans (100%)
 
 ## Performance Metrics
 
 **Velocity (v1.0 baseline):**
+
 - Total plans completed (v1.0): 10
 - Average duration: ~2.4 min/plan
 - Total execution time: ~24 min
@@ -47,8 +48,12 @@ Progress: [░░░░░░░░░░░░░░░░░░░░] 0/? pla
 | 02 Dashboard Charts | 3 | ~7 min | 2.3 min |
 | 03 Collapsible Sections | 2 | ~4 min | 2 min |
 | 04 Full-App Consistency | 3 | ~7 min | 2.3 min |
+| 05 | 3 | - | - |
+| 06 | 3 | - | - |
+| 7 | 2 | - | - |
 
 **v2.0 Trend:**
+
 - Last 5 plans: -
 - Trend: -
 
@@ -76,6 +81,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-02
+Last session: 2026-04-20
-Stopped at: Roadmap created — ready to plan Phase 5
+Stopped at: Completed 06-03-PLAN.md — Phase 06 fully executed
 Resume file: None

.planning/config.json

@@ -9,6 +9,6 @@
     "plan_check": true,
     "verifier": true,
     "nyquist_validation": true,
-    "_auto_chain_active": true
+    "_auto_chain_active": false
   }
 }

.planning/phases/05-design-system-token-rework/05-01-PLAN.md

@@ -0,0 +1,219 @@
+---
+phase: 05-design-system-token-rework
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/index.css
+  - src/components/dashboard/charts/SpendBarChart.tsx
+  - src/components/dashboard/charts/IncomeBarChart.tsx
+  - src/components/dashboard/charts/ExpenseDonutChart.tsx
+autonomous: true
+requirements:
+  - DS-01
+  - DS-02
+
+must_haves:
+  truths:
+    - "--radius token is 0 in index.css, cascading sharp corners to all shadcn components"
+    - "Category fill colors have chroma >= 0.22 making them visibly colorful"
+    - "--color-chart-* variables are deleted from index.css"
+    - "Chart bars render with 0 radius (no rounded caps)"
+    - "CSS overrides exist for Recharts rectangles and Sonner toasts"
+  artifacts:
+    - path: "src/index.css"
+      provides: "Design token source of truth with --radius: 0, raised fill chromas, removed chart vars, third-party overrides"
+      contains: "--radius: 0"
+    - path: "src/components/dashboard/charts/SpendBarChart.tsx"
+      provides: "Spend bar chart with sharp bars"
+      contains: "radius={0}"
+    - path: "src/components/dashboard/charts/IncomeBarChart.tsx"
+      provides: "Income bar chart with sharp bars"
+      contains: "radius={0}"
+    - path: "src/components/dashboard/charts/ExpenseDonutChart.tsx"
+      provides: "Donut chart legend with square color dots"
+  key_links:
+    - from: "src/index.css"
+      to: "all shadcn components"
+      via: "--radius: 0 token cascade"
+      pattern: "--radius: 0"
+    - from: "src/index.css"
+      to: "chart components"
+      via: "--color-*-fill CSS variables"
+      pattern: "color-.*-fill"
+---
+
+<objective>
+Edit design tokens in src/index.css (radius, colors, chart var removal, third-party overrides) and update chart component Bar radius props to 0.
+
+Purpose: Establish the sharp-cornered, vibrant-pastel visual foundation that cascades to all shadcn components and charts.
+Output: Modified index.css with new token values + CSS overrides; 3 chart component files with radius={0} and no rounded-full.
+</objective>
+
+<execution_context>
+@.planning/phases/05-design-system-token-rework/05-RESEARCH.md
+@.planning/phases/05-design-system-token-rework/05-PATTERNS.md
+@.planning/phases/05-design-system-token-rework/05-UI-SPEC.md
+</execution_context>
+
+<context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+<interfaces>
+<!-- Current src/index.css @theme inline block (lines 5-79) is the single token source of truth -->
+<!-- Chart components reference CSS variables via ChartConfig and Bar fill props -->
+
+From src/components/dashboard/charts/SpendBarChart.tsx:
+```tsx
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-muted-foreground)" },
+} satisfies ChartConfig
+// Bar radius={4} on both Bar elements
+// Cell fill uses var(--color-${entry.type}-fill) -- already correct
+```
+
+From src/components/dashboard/charts/IncomeBarChart.tsx:
+```tsx
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-income-fill)" },
+} satisfies ChartConfig
+// Bar radius={[4, 4, 0, 0]} on both Bar elements
+```
+
+From src/components/dashboard/charts/ExpenseDonutChart.tsx:
+```tsx
+// Line 141: <span className="inline-block size-3 shrink-0 rounded-full" .../>
+// Uses var(--color-${entry.type}-fill) for legend dot colors -- already correct
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Edit design tokens and add CSS overrides in index.css</name>
+  <files>src/index.css</files>
+  <read_first>src/index.css</read_first>
+  <action>
+Edit src/index.css with these exact changes:
+
+1. Line 7: Change `--color-background: oklch(0.98 0.005 260)` to `--color-background: oklch(0.98 0.01 260)` (warm background chroma from 0.005 to 0.01).
+
+2. Lines 52-57: DELETE the entire "Chart Colors" section (6 lines):
+   ```
+   /* Chart Colors */
+   --color-chart-1: oklch(0.72 0.14 155);
+   --color-chart-2: oklch(0.7 0.14 25);
+   --color-chart-3: oklch(0.72 0.14 50);
+   --color-chart-4: oklch(0.65 0.16 355);
+   --color-chart-5: oklch(0.72 0.14 220);
+   ```
+
+3. Lines 65-70: Replace the 6 fill token values with raised chroma (0.22+):
+   ```css
+   --color-income-fill: oklch(0.72 0.22 155);
+   --color-bill-fill: oklch(0.70 0.22 25);
+   --color-variable-expense-fill: oklch(0.74 0.22 50);
+   --color-debt-fill: oklch(0.66 0.23 355);
+   --color-saving-fill: oklch(0.72 0.22 220);
+   --color-investment-fill: oklch(0.68 0.22 285);
+   ```
+
+4. Line 72: Change `--radius: 0.625rem` to `--radius: 0`.
+
+5. After the closing `}` of the `@layer base` block (after line 99), add CSS overrides for third-party components:
+   ```css
+   /* Third-party radius overrides */
+   .recharts-rectangle {
+     rx: 0;
+     ry: 0;
+   }
+
+   [data-sonner-toast] {
+     border-radius: 0 !important;
+   }
+   ```
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/index.css contains `--radius: 0;`
+    - src/index.css contains `--color-background: oklch(0.98 0.01 260)`
+    - src/index.css contains `--color-income-fill: oklch(0.72 0.22 155)`
+    - src/index.css contains `--color-bill-fill: oklch(0.70 0.22 25)`
+    - src/index.css contains `--color-variable-expense-fill: oklch(0.74 0.22 50)`
+    - src/index.css contains `--color-debt-fill: oklch(0.66 0.23 355)`
+    - src/index.css contains `--color-saving-fill: oklch(0.72 0.22 220)`
+    - src/index.css contains `--color-investment-fill: oklch(0.68 0.22 285)`
+    - src/index.css does NOT contain `--color-chart-1` or `--color-chart-2` or `--color-chart-3` or `--color-chart-4` or `--color-chart-5`
+    - src/index.css contains `.recharts-rectangle`
+    - src/index.css contains `[data-sonner-toast]`
+    - `bun run build` exits 0
+  </acceptance_criteria>
+  <done>index.css has --radius: 0, raised fill chromas (0.22+), deleted chart vars, warmed background, and CSS overrides for Recharts and Sonner</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update chart component Bar radius props and remove hardcoded rounded-full</name>
+  <files>src/components/dashboard/charts/SpendBarChart.tsx, src/components/dashboard/charts/IncomeBarChart.tsx, src/components/dashboard/charts/ExpenseDonutChart.tsx</files>
+  <read_first>src/components/dashboard/charts/SpendBarChart.tsx, src/components/dashboard/charts/IncomeBarChart.tsx, src/components/dashboard/charts/ExpenseDonutChart.tsx</read_first>
+  <action>
+1. In SpendBarChart.tsx: Find the two `<Bar` elements. Change `radius={4}` to `radius={0}` on both Bar components. Do NOT change ChartConfig colors -- they are already correct (budgeted uses --color-budget-bar-bg, actual Cell uses var(--color-${entry.type}-fill)).
+
+2. In IncomeBarChart.tsx: Find the two `<Bar` elements. Change `radius={[4, 4, 0, 0]}` to `radius={0}` on both Bar components. Do NOT change ChartConfig colors -- they are already correct (actual uses --color-income-fill).
+
+3. In ExpenseDonutChart.tsx: Find line 141 (the legend color dot span). Remove `rounded-full` from the className string. The className should go from `"inline-block size-3 shrink-0 rounded-full"` to `"inline-block size-3 shrink-0"`. No other changes needed in this file.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
+  </verify>
+  <acceptance_criteria>
+    - SpendBarChart.tsx contains `radius={0}` (grep returns 2 matches)
+    - SpendBarChart.tsx does NOT contain `radius={4}`
+    - IncomeBarChart.tsx contains `radius={0}` (grep returns 2 matches)
+    - IncomeBarChart.tsx does NOT contain `radius={[4, 4, 0, 0]}`
+    - ExpenseDonutChart.tsx does NOT contain `rounded-full`
+    - ExpenseDonutChart.tsx contains `"inline-block size-3 shrink-0"`
+    - `bun run build` exits 0
+  </acceptance_criteria>
+  <done>All 3 chart components have sharp bars (radius={0}) and the donut legend dot is square (no rounded-full)</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+No trust boundaries affected. This plan modifies CSS tokens and SVG presentation props only. No user input handling, no data access, no authentication changes.
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| — | — | — | — | No applicable threats — pure CSS/visual changes |
+</threat_model>
+
+<verification>
+- `bun run build` passes after both tasks
+- grep confirms --radius: 0 in index.css
+- grep confirms no --color-chart-* references remain in src/
+- grep confirms radius={0} in both bar chart components
+</verification>
+
+<success_criteria>
+- Token cascade makes all shadcn components sharp-cornered (verified by --radius: 0 in index.css)
+- Category fill colors raised to 0.22+ chroma (verified by grep on index.css)
+- Chart color duplication eliminated (--color-chart-* deleted, verified by grep)
+- Chart bars render with sharp ends (radius={0} in both bar chart files)
+- CSS overrides exist for Recharts SVG and Sonner toasts
+- Build passes cleanly
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-design-system-token-rework/05-01-SUMMARY.md`
+</output>

.planning/phases/05-design-system-token-rework/05-01-SUMMARY.md

@@ -0,0 +1,101 @@
+---
+phase: 05-design-system-token-rework
+plan: "01"
+subsystem: frontend/design-system
+tags: [css-tokens, design-system, charts, oklch, recharts]
+dependency_graph:
+  requires: []
+  provides:
+    - "--radius: 0 token cascade to all shadcn components"
+    - "Raised fill chroma (0.22+) for category colors"
+    - "Eliminated --color-chart-* duplication"
+    - "Sharp bar chart rendering via radius={0}"
+    - "Square legend dots in donut chart"
+  affects:
+    - "All shadcn/ui components (border-radius cascade)"
+    - "SpendBarChart, IncomeBarChart, ExpenseDonutChart"
+    - "Recharts SVG rectangles (CSS override)"
+    - "Sonner toasts (CSS override)"
+tech_stack:
+  added: []
+  patterns:
+    - "OKLCH color system with raised chroma (0.22+) for vivid pastels"
+    - "CSS --radius: 0 token for sharp-cornered design cascade"
+    - "Third-party radius overrides via selector targeting"
+key_files:
+  created: []
+  modified:
+    - src/index.css
+    - src/components/dashboard/charts/SpendBarChart.tsx
+    - src/components/dashboard/charts/IncomeBarChart.tsx
+    - src/components/dashboard/charts/ExpenseDonutChart.tsx
+decisions:
+  - "Use rx/ry SVG attributes in .recharts-rectangle rule rather than border-radius (SVG does not support border-radius)"
+  - "Delete --color-chart-* vars entirely — fill vars cover all use cases, no consumers of chart-* remain"
+metrics:
+  duration: "~8 minutes"
+  completed: "2026-04-20"
+  tasks_completed: 2
+  tasks_total: 2
+  files_modified: 4
+---
+
+# Phase 05 Plan 01: Design Token Foundation Summary
+
+**One-liner:** Established sharp-cornered OKLCH pastel design foundation with --radius: 0 cascade, raised fill chroma to 0.22+, deleted redundant chart color vars, and set chart bars to radius={0} with square legend dots.
+
+## Tasks Completed
+
+| Task | Name | Commit | Key Changes |
+|------|------|--------|-------------|
+| 1 | Edit design tokens and add CSS overrides in index.css | 99b5b5f | --radius: 0, chroma 0.22+, deleted chart vars, warmed bg, Recharts/Sonner overrides |
+| 2 | Update chart Bar radius props and remove rounded-full | 4c74dec | SpendBarChart radius={0}x2, IncomeBarChart radius={0}x2, ExpenseDonutChart legend dot square |
+
+## What Was Built
+
+### index.css Changes
+- `--color-background` chroma raised from 0.005 to 0.01 (warmer background)
+- `--color-chart-1` through `--color-chart-5` deleted (6 lines removed — no remaining consumers)
+- All 6 `--color-*-fill` variables raised to chroma 0.22+ for vibrant pastels:
+  - income: 0.19 → 0.22, bill: 0.19 → 0.22, variable-expense: 0.18 → 0.22
+  - debt: 0.20 → 0.23, saving: 0.18 → 0.22, investment: 0.18 → 0.22
+- `--radius` changed from 0.625rem to 0 — cascades sharp corners to all shadcn components
+- `.recharts-rectangle { rx: 0; ry: 0; }` override added (SVG attribute approach)
+- `[data-sonner-toast] { border-radius: 0 !important; }` override added
+
+### Chart Component Changes
+- `SpendBarChart.tsx`: Both `<Bar>` elements changed from `radius={4}` to `radius={0}`
+- `IncomeBarChart.tsx`: Both `<Bar>` elements changed from `radius={[4, 4, 0, 0]}` to `radius={0}`
+- `ExpenseDonutChart.tsx`: Legend color dot span: removed `rounded-full` from className
+
+## Verification
+
+All acceptance criteria confirmed by grep and build:
+- `--radius: 0` present in index.css
+- `--color-chart-1` through `--color-chart-5` absent from src/
+- `radius={0}` present (2 matches each) in SpendBarChart and IncomeBarChart
+- `rounded-full` absent from ExpenseDonutChart
+- `.recharts-rectangle` and `[data-sonner-toast]` present in index.css
+- `bun run build` exits 0 (TypeScript + Vite both pass)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — all token values are real OKLCH colors wired to actual chart and UI components.
+
+## Threat Flags
+
+None — pure CSS/visual changes with no trust boundary impact.
+
+## Self-Check: PASSED
+
+- [x] `src/index.css` exists and contains all required tokens
+- [x] `src/components/dashboard/charts/SpendBarChart.tsx` contains `radius={0}`
+- [x] `src/components/dashboard/charts/IncomeBarChart.tsx` contains `radius={0}`
+- [x] `src/components/dashboard/charts/ExpenseDonutChart.tsx` has no `rounded-full`
+- [x] Commit 99b5b5f exists (Task 1)
+- [x] Commit 4c74dec exists (Task 2)
+- [x] Build passes cleanly

.planning/phases/05-design-system-token-rework/05-02-PLAN.md

@@ -0,0 +1,178 @@
+---
+phase: 05-design-system-token-rework
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/components/shared/PageShell.tsx
+  - src/components/dashboard/DashboardSkeleton.tsx
+  - src/components/dashboard/CategorySection.tsx
+  - src/components/dashboard/charts/ChartEmptyState.tsx
+  - src/components/QuickAddPicker.tsx
+autonomous: true
+requirements:
+  - DS-01
+  - DS-03
+
+must_haves:
+  truths:
+    - "PageShell gap is gap-8 providing generous header-to-content spacing on all pages"
+    - "All shared component hardcoded rounded-* classes are removed"
+    - "DashboardSkeleton spacing matches the upgraded gap/space-y values"
+    - "No pill-shaped skeleton placeholders remain in shared components"
+  artifacts:
+    - path: "src/components/shared/PageShell.tsx"
+      provides: "Layout shell with gap-8 section spacing"
+      contains: "gap-8"
+    - path: "src/components/dashboard/DashboardSkeleton.tsx"
+      provides: "Dashboard loading skeleton with sharp corners and upgraded spacing"
+    - path: "src/components/dashboard/CategorySection.tsx"
+      provides: "Category section trigger without rounded-md"
+    - path: "src/components/dashboard/charts/ChartEmptyState.tsx"
+      provides: "Chart empty state without rounded-lg"
+    - path: "src/components/QuickAddPicker.tsx"
+      provides: "Quick add picker without rounded-sm or rounded-full"
+  key_links:
+    - from: "src/components/shared/PageShell.tsx"
+      to: "all 9 pages"
+      via: "PageShell wrapper component"
+      pattern: "gap-8"
+---
+
+<objective>
+Remove hardcoded rounded-* classes and upgrade spacing in shared components (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker).
+
+Purpose: These shared components are used across multiple pages. Fixing them first ensures consistent sharp corners and generous spacing everywhere they appear.
+Output: 5 modified component files with no hardcoded rounding and upgraded spacing values.
+</objective>
+
+<execution_context>
+@.planning/phases/05-design-system-token-rework/05-RESEARCH.md
+@.planning/phases/05-design-system-token-rework/05-PATTERNS.md
+</execution_context>
+
+<context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+<interfaces>
+From src/components/shared/PageShell.tsx (line 15):
+```tsx
+<div className="flex flex-col gap-6">  <!-- gap-6 --> gap-8 -->
+```
+
+From src/components/dashboard/DashboardSkeleton.tsx:
+```tsx
+// Line 20: <div className="flex flex-col gap-6">          -- gap-8
+// Line 22: <div className="grid gap-4 sm:grid-cols-2..."> -- gap-6
+// Line 29: <div className="grid gap-6 md:grid-cols-2..."> -- gap-8
+// Line 35,43,51: <Skeleton className="h-[250px] w-full rounded-md" /> -- remove rounded-md
+// Line 59: <div className="... rounded-md border-l-4 ..."> -- remove rounded-md
+// Lines 63-64: <Skeleton className="h-5 w-24 rounded-full" /> -- remove rounded-full
+```
+
+From src/components/dashboard/CategorySection.tsx (line 73):
+```tsx
+<button className="... rounded-md border-l-4 bg-card px-4 py-3 ...">
+```
+
+From src/components/dashboard/charts/ChartEmptyState.tsx (line 12):
+```tsx
+className={cn("... rounded-lg border border-dashed ...", className)}
+```
+
+From src/components/QuickAddPicker.tsx:
+```tsx
+// Line 156: className="... rounded-sm px-2 py-1.5 ..."
+// Line 201: <div className="size-2 rounded-full" .../>
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Upgrade PageShell spacing and remove rounded-* from DashboardSkeleton</name>
+  <files>src/components/shared/PageShell.tsx, src/components/dashboard/DashboardSkeleton.tsx</files>
+  <read_first>src/components/shared/PageShell.tsx, src/components/dashboard/DashboardSkeleton.tsx</read_first>
+  <action>
+1. In PageShell.tsx line 15: Change `gap-6` to `gap-8` in the className string `"flex flex-col gap-6"`.
+
+2. In DashboardSkeleton.tsx, make all of the following changes:
+   - Line 20: Change `gap-6` to `gap-8` in `"flex flex-col gap-6"`
+   - Line 22: Change `gap-4` to `gap-6` in `"grid gap-4 sm:grid-cols-2 lg:grid-cols-3"`
+   - Line 29: Change `gap-6` to `gap-8` in `"grid gap-6 md:grid-cols-2 lg:grid-cols-3"`
+   - Lines 35, 43, 51: Remove `rounded-md` from `<Skeleton className="h-[250px] w-full rounded-md" />` (3 occurrences). Result: `className="h-[250px] w-full"`
+   - Line 59: Remove `rounded-md` from the div className `"flex items-center gap-3 rounded-md border-l-4 ..."`. The border-l-4 remains.
+   - Lines 63, 64: Remove `rounded-full` from `<Skeleton className="h-5 w-24 rounded-full" />` (2 occurrences). Result: `className="h-5 w-24"`
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
+  </verify>
+  <acceptance_criteria>
+    - PageShell.tsx contains `gap-8` and does NOT contain `gap-6`
+    - DashboardSkeleton.tsx does NOT contain `rounded-md` or `rounded-full`
+    - DashboardSkeleton.tsx contains `gap-8` (2 occurrences) and `gap-6` (1 occurrence for the summary cards grid)
+    - `bun run build` exits 0
+  </acceptance_criteria>
+  <done>PageShell uses gap-8 for header-to-content spacing; DashboardSkeleton has no hardcoded rounding and upgraded spacing</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Remove rounded-* from CategorySection, ChartEmptyState, and QuickAddPicker</name>
+  <files>src/components/dashboard/CategorySection.tsx, src/components/dashboard/charts/ChartEmptyState.tsx, src/components/QuickAddPicker.tsx</files>
+  <read_first>src/components/dashboard/CategorySection.tsx, src/components/dashboard/charts/ChartEmptyState.tsx, src/components/QuickAddPicker.tsx</read_first>
+  <action>
+1. In CategorySection.tsx line 73: Remove `rounded-md` from the button className. The className goes from `"group flex w-full items-center gap-3 rounded-md border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"` to `"group flex w-full items-center gap-3 border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"`.
+
+2. In ChartEmptyState.tsx line 12: Remove `rounded-lg` from the cn() className string. The class goes from `"flex min-h-[250px] w-full items-center justify-center rounded-lg border border-dashed ..."` to `"flex min-h-[250px] w-full items-center justify-center border border-dashed ..."`.
+
+3. In QuickAddPicker.tsx:
+   - Line 156: Remove `rounded-sm` from the picker item className. Goes from `"flex w-full items-center gap-2 rounded-sm px-2 py-1.5 ..."` to `"flex w-full items-center gap-2 px-2 py-1.5 ..."`.
+   - Line 201: Remove `rounded-full` from the category dot className. Goes from `className="size-2 rounded-full"` to `className="size-2"`.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
+  </verify>
+  <acceptance_criteria>
+    - CategorySection.tsx does NOT contain `rounded-md`
+    - ChartEmptyState.tsx does NOT contain `rounded-lg`
+    - QuickAddPicker.tsx does NOT contain `rounded-sm` or `rounded-full`
+    - `bun run build` exits 0
+  </acceptance_criteria>
+  <done>All 3 shared components have no hardcoded rounding classes; sharp corners enforced everywhere they appear</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+No trust boundaries affected. This plan modifies CSS class strings in component JSX only. No user input handling, no data access, no authentication changes.
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| — | — | — | — | No applicable threats — pure CSS class changes |
+</threat_model>
+
+<verification>
+- `bun run build` passes after both tasks
+- grep confirms no `rounded-md`, `rounded-full`, `rounded-lg`, `rounded-sm` remain in the 5 modified files
+- grep confirms `gap-8` in PageShell.tsx
+</verification>
+
+<success_criteria>
+- PageShell provides gap-8 section spacing to all pages
+- DashboardSkeleton has sharp skeletons and upgraded spacing
+- CategorySection trigger button has no rounded corners
+- ChartEmptyState border has no rounded corners
+- QuickAddPicker items and dots have no rounded corners
+- Build passes cleanly
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-design-system-token-rework/05-02-SUMMARY.md`
+</output>

.planning/phases/05-design-system-token-rework/05-02-SUMMARY.md

@@ -0,0 +1,108 @@
+---
+phase: 05-design-system-token-rework
+plan: "02"
+subsystem: frontend-components
+tags: [design-system, sharp-corners, spacing, shared-components]
+dependency_graph:
+  requires: []
+  provides: [sharp-corners-in-shared-components, gap-8-page-spacing]
+  affects: [all-9-pages, dashboard-skeleton, category-sections, chart-empty-states, quick-add-picker]
+tech_stack:
+  added: []
+  patterns: [remove-hardcoded-rounded-classes, upgrade-gap-spacing]
+key_files:
+  modified:
+    - src/components/shared/PageShell.tsx
+    - src/components/dashboard/DashboardSkeleton.tsx
+    - src/components/dashboard/CategorySection.tsx
+    - src/components/dashboard/charts/ChartEmptyState.tsx
+    - src/components/QuickAddPicker.tsx
+decisions:
+  - "Upgraded DashboardSkeleton summary-cards grid from gap-4 to gap-6 (not gap-8) to match plan spec for the inner card grid"
+  - "Upgraded DashboardSkeleton chart grid from gap-6 to gap-8 as specified"
+metrics:
+  duration: "91s"
+  completed: "2026-04-20"
+  tasks_completed: 2
+  tasks_total: 2
+  files_modified: 5
+---
+
+# Phase 05 Plan 02: Shared Component Rounding and Spacing Cleanup Summary
+
+Sharp corners enforced across all 5 shared components by removing hardcoded `rounded-*` classes, and page-level spacing upgraded from `gap-6` to `gap-8` in PageShell propagating to all 9 pages.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files Modified |
+|------|------|--------|----------------|
+| 1 | Upgrade PageShell spacing and remove rounded-* from DashboardSkeleton | e8f13c9 | PageShell.tsx, DashboardSkeleton.tsx |
+| 2 | Remove rounded-* from CategorySection, ChartEmptyState, QuickAddPicker | e7282fa | CategorySection.tsx, ChartEmptyState.tsx, QuickAddPicker.tsx |
+
+## Changes Made
+
+### Task 1: PageShell + DashboardSkeleton
+
+**PageShell.tsx**
+- `gap-6` → `gap-8` in the root flex container (line 15) — applies generous section spacing across all 9 pages
+
+**DashboardSkeleton.tsx**
+- Outer flex: `gap-6` → `gap-8`
+- Summary cards grid: `gap-4` → `gap-6`
+- Chart area grid: `gap-6` → `gap-8`
+- Removed `rounded-md` from 3 chart skeleton `<Skeleton>` elements
+- Removed `rounded-md` from collapsible section row `<div>`
+- Removed `rounded-full` from 2 badge `<Skeleton>` elements (2 occurrences via replace_all)
+
+### Task 2: CategorySection + ChartEmptyState + QuickAddPicker
+
+**CategorySection.tsx**
+- Removed `rounded-md` from collapsible trigger `<button>` — sharp left-bordered row maintained via `border-l-4`
+
+**ChartEmptyState.tsx**
+- Removed `rounded-lg` from the dashed-border container div — sharp rectangular empty state
+
+**QuickAddPicker.tsx**
+- Removed `rounded-sm` from picker item `<button>` elements in the popover list
+- Removed `rounded-full` from the category type dot indicator `<div>`
+
+## Verification
+
+```
+bun run build  →  exit 0  (both tasks)
+grep rounded-md  PageShell.tsx           →  0 matches
+grep rounded-md  DashboardSkeleton.tsx   →  0 matches
+grep rounded-full DashboardSkeleton.tsx  →  0 matches
+grep rounded-md  CategorySection.tsx     →  0 matches
+grep rounded-lg  ChartEmptyState.tsx     →  0 matches
+grep rounded-sm  QuickAddPicker.tsx      →  0 matches
+grep rounded-full QuickAddPicker.tsx     →  0 matches
+grep gap-8       PageShell.tsx           →  1 match ✓
+```
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — this plan modifies only CSS class strings. No data wiring or UI stubs introduced.
+
+## Threat Flags
+
+None — pure CSS class changes, no security-relevant surface modified.
+
+## Self-Check
+
+**Commits exist:**
+- e8f13c9: feat(05-02): upgrade PageShell spacing to gap-8 and remove rounded-* from DashboardSkeleton
+- e7282fa: feat(05-02): remove hardcoded rounded-* from CategorySection, ChartEmptyState, QuickAddPicker
+
+**Files exist:**
+- src/components/shared/PageShell.tsx — modified
+- src/components/dashboard/DashboardSkeleton.tsx — modified
+- src/components/dashboard/CategorySection.tsx — modified
+- src/components/dashboard/charts/ChartEmptyState.tsx — modified
+- src/components/QuickAddPicker.tsx — modified
+
+## Self-Check: PASSED

.planning/phases/05-design-system-token-rework/05-03-PLAN.md

@@ -0,0 +1,249 @@
+---
+phase: 05-design-system-token-rework
+plan: 03
+type: execute
+wave: 2
+depends_on:
+  - 05-01
+  - 05-02
+files_modified:
+  - src/pages/DashboardPage.tsx
+  - src/pages/BudgetListPage.tsx
+  - src/pages/BudgetDetailPage.tsx
+  - src/pages/TemplatePage.tsx
+  - src/pages/CategoriesPage.tsx
+  - src/pages/QuickAddPage.tsx
+  - src/pages/SettingsPage.tsx
+  - src/pages/LoginPage.tsx
+  - src/pages/RegisterPage.tsx
+autonomous: false
+requirements:
+  - DS-01
+  - DS-02
+  - DS-03
+
+must_haves:
+  truths:
+    - "All 9 pages have no hardcoded rounded-* classes remaining"
+    - "All 9 pages have upgraded spacing (space-y-8, gap-8 for sections)"
+    - "Visual pass confirms sharp corners, colorful pastels, and generous whitespace everywhere"
+  artifacts:
+    - path: "src/pages/DashboardPage.tsx"
+      provides: "Dashboard with space-y-8 and gap-8 section spacing"
+      contains: "space-y-8"
+    - path: "src/pages/BudgetListPage.tsx"
+      provides: "Budget list without rounded-md on row containers"
+    - path: "src/pages/BudgetDetailPage.tsx"
+      provides: "Budget detail without rounded-sm/md/full, upgraded spacing"
+    - path: "src/pages/TemplatePage.tsx"
+      provides: "Template page without rounded-sm/full, upgraded spacing"
+    - path: "src/pages/CategoriesPage.tsx"
+      provides: "Categories page without rounded-sm/full, upgraded spacing"
+    - path: "src/pages/QuickAddPage.tsx"
+      provides: "Quick add page without rounded-full/md"
+    - path: "src/pages/SettingsPage.tsx"
+      provides: "Settings page with space-y-6 card content spacing"
+    - path: "src/pages/LoginPage.tsx"
+      provides: "Login page verified (token cascade handles Card rounding)"
+    - path: "src/pages/RegisterPage.tsx"
+      provides: "Register page verified (token cascade handles Card rounding)"
+  key_links:
+    - from: "all 9 pages"
+      to: "src/index.css"
+      via: "--radius: 0 token cascade through Tailwind utilities"
+      pattern: "no rounded-full or rounded-sm or rounded-md classes remain"
+---
+
+<objective>
+Sweep all 9 pages to remove hardcoded rounded-* classes and upgrade spacing values. Finish with a visual verification checkpoint across all pages.
+
+Purpose: Complete the per-page visual rework ensuring DS-01 (sharp edges), DS-02 (colorful pastels visible), and DS-03 (generous whitespace) are met everywhere.
+Output: 9 modified page files with no rounding and upgraded spacing + visual confirmation.
+</objective>
+
+<execution_context>
+@.planning/phases/05-design-system-token-rework/05-RESEARCH.md
+@.planning/phases/05-design-system-token-rework/05-PATTERNS.md
+@.planning/phases/05-design-system-token-rework/05-UI-SPEC.md
+</execution_context>
+
+<context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-design-system-token-rework/05-01-SUMMARY.md
+@.planning/phases/05-design-system-token-rework/05-02-SUMMARY.md
+
+<interfaces>
+<!-- From 05-PATTERNS.md: Complete inventory of hardcoded rounded-* per page -->
+
+DashboardPage.tsx: No hardcoded rounded-* classes. Spacing: space-y-6 -> space-y-8 (line 186), gap-6 -> gap-8 (line 207).
+
+BudgetListPage.tsx: Line 243 rounded-md on row div. Spacing: gap-4 -> gap-6, gap-6 -> gap-8, space-y-6 -> space-y-8 where present.
+
+BudgetDetailPage.tsx: Lines 290 (rounded-sm), 303 (rounded-md), 353 (rounded-sm), 439 (rounded-md), 497 (rounded-full). Spacing: verify no space-y-6/gap-6 remain.
+
+TemplatePage.tsx: Lines 250 (rounded-sm), 256 (rounded-full), 258 (rounded-md), 292 (rounded-sm), 385 (rounded-full). Spacing: 247 space-y-6->space-y-8, 268 gap-6->gap-8, 287 space-y-6->space-y-8.
+
+CategoriesPage.tsx: Lines 101 (rounded-sm), 107 (rounded-full), 108 (rounded-md), 134 (rounded-sm). Spacing: 98 space-y-6->space-y-8, 130 space-y-6->space-y-8.
+
+QuickAddPage.tsx: Lines 98 (rounded-full), 100 (rounded-md). No major spacing changes.
+
+SettingsPage.tsx: No rounded-* classes. Spacing: line 87 space-y-4->space-y-6 in CardContent.
+
+LoginPage.tsx: No rounded-* classes. Token cascade handles Card. Verify p-4->p-6 if card content wrapper has p-4.
+
+RegisterPage.tsx: No rounded-* classes. Token cascade handles Card. Verify p-4->p-6 if card content wrapper has p-4.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Remove rounded-* and upgrade spacing on all 9 pages</name>
+  <files>src/pages/DashboardPage.tsx, src/pages/BudgetListPage.tsx, src/pages/BudgetDetailPage.tsx, src/pages/TemplatePage.tsx, src/pages/CategoriesPage.tsx, src/pages/QuickAddPage.tsx, src/pages/SettingsPage.tsx, src/pages/LoginPage.tsx, src/pages/RegisterPage.tsx</files>
+  <read_first>src/pages/DashboardPage.tsx, src/pages/BudgetListPage.tsx, src/pages/BudgetDetailPage.tsx, src/pages/TemplatePage.tsx, src/pages/CategoriesPage.tsx, src/pages/QuickAddPage.tsx, src/pages/SettingsPage.tsx, src/pages/LoginPage.tsx, src/pages/RegisterPage.tsx</read_first>
+  <action>
+Apply two categories of changes to each page: (A) remove hardcoded rounded-* classes, (B) upgrade spacing values. Use the exact inventory from 05-PATTERNS.md.
+
+**DashboardPage.tsx:**
+- (B) Line ~186: `space-y-6` -> `space-y-8`
+- (B) Line ~207: `gap-6` -> `gap-8`
+
+**BudgetListPage.tsx:**
+- (A) Line ~243: Remove `rounded-md` from `"flex items-center gap-3 rounded-md border p-3"` -> `"flex items-center gap-3 border p-3"`
+- (B) Upgrade any `gap-4` -> `gap-6`, `gap-6` -> `gap-8`, `space-y-6` -> `space-y-8` found in the file
+
+**BudgetDetailPage.tsx:**
+- (A) Line ~290: Remove `rounded-sm` from skeleton header div className
+- (A) Line ~303: Remove `rounded-md` from `<Skeleton>` className
+- (A) Line ~353: Remove `rounded-sm` from group heading div className `"mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"` -> `"mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"`
+- (A) Line ~439: Remove `rounded-md` from summary box `"rounded-md border p-4"` -> `"border p-4"`
+- (A) Line ~497: Remove `rounded-full` from SelectLabel category dot `"size-2 rounded-full"` -> `"size-2"`
+- (B) Verify existing space-y-8 at line ~338 is correct. Upgrade any remaining space-y-6 or gap-6 instances.
+
+**TemplatePage.tsx:**
+- (A) Line ~250: Remove `rounded-sm` from skeleton group heading div
+- (A) Line ~256: Remove `rounded-full` from `<Skeleton>` className
+- (A) Line ~258: Remove `rounded-md` from `<Skeleton>` className
+- (A) Line ~292: Remove `rounded-sm` from template item group heading div `"mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"` -> `"mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"`
+- (A) Line ~385: Remove `rounded-full` from SelectLabel category dot `"size-2 rounded-full"` -> `"size-2"`
+- (B) Line ~247: `space-y-6` -> `space-y-8`
+- (B) Line ~268: `gap-6` -> `gap-8`
+- (B) Line ~287: `space-y-6` -> `space-y-8`
+
+**CategoriesPage.tsx:**
+- (A) Line ~101: Remove `rounded-sm` from skeleton group heading div
+- (A) Line ~107: Remove `rounded-full` from `<Skeleton>` className
+- (A) Line ~108: Remove `rounded-md` from `<Skeleton>` className
+- (A) Line ~134: Remove `rounded-sm` from category group heading div `"mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"` -> `"mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"`
+- (B) Line ~98: `space-y-6` -> `space-y-8`
+- (B) Line ~130: `space-y-6` -> `space-y-8`
+
+**QuickAddPage.tsx:**
+- (A) Line ~98: Remove `rounded-full` from `<Skeleton>` className
+- (A) Line ~100: Remove `rounded-md` from `<Skeleton>` className
+
+**SettingsPage.tsx:**
+- (B) Line ~87: `space-y-4` -> `space-y-6` in CardContent className
+- (B) Also check skeleton equivalent (~line 69) for same `space-y-4` -> `space-y-6`
+
+**LoginPage.tsx:**
+- No rounded-* to remove (Card uses token cascade).
+- (B) Check for any `p-4` on card content wrappers and upgrade to `p-6` if found. If no `p-4` exists (CardContent already uses px-6 from shadcn defaults), no change needed.
+
+**RegisterPage.tsx:**
+- Same as LoginPage -- check for `p-4` card content wrapper upgrades.
+
+**IMPORTANT:** Line numbers are approximate from the PATTERNS.md inventory. Read each file first to find the exact locations. Search for the exact class strings listed above.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build && grep -rn "rounded-full\|rounded-sm\|rounded-md\|rounded-lg" src/pages/ || echo "NO HARDCODED ROUNDED CLASSES FOUND IN PAGES - PASS"</automated>
+  </verify>
+  <acceptance_criteria>
+    - grep -rn "rounded-full\|rounded-sm\|rounded-md\|rounded-lg" src/pages/ returns NO matches
+    - DashboardPage.tsx contains `space-y-8` and `gap-8`
+    - BudgetListPage.tsx does NOT contain `rounded-md`
+    - BudgetDetailPage.tsx does NOT contain `rounded-sm` or `rounded-md` or `rounded-full`
+    - TemplatePage.tsx does NOT contain `rounded-sm` or `rounded-full` or `rounded-md`
+    - CategoriesPage.tsx does NOT contain `rounded-sm` or `rounded-full` or `rounded-md`
+    - QuickAddPage.tsx does NOT contain `rounded-full` or `rounded-md`
+    - SettingsPage.tsx contains `space-y-6` in CardContent
+    - `bun run build` exits 0
+  </acceptance_criteria>
+  <done>All 9 pages have zero hardcoded rounded-* classes and upgraded spacing values</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Visual verification of all 9 pages</name>
+  <what-built>
+    Complete design system token rework across all files:
+    - --radius: 0 (sharp corners on all shadcn components)
+    - Category fill colors raised to 0.22+ chroma (vibrant pastels)
+    - Background warmed to 0.01 chroma
+    - Chart color vars deleted and replaced with fill token references
+    - All hardcoded rounded-* classes removed from pages and shared components
+    - Spacing upgraded: gap-8 section gaps, space-y-8 section rhythm, p-6 card padding
+    - CSS overrides for Recharts bars and Sonner toasts
+  </what-built>
+  <how-to-verify>
+    1. Run `bun run dev` to start the dev server
+    2. Open the app in your browser
+    3. Check each of the 9 pages against this checklist:
+
+    **Sharp corners (DS-01):**
+    - [ ] Dashboard: Cards, buttons, chart containers all have sharp corners
+    - [ ] Budget List: Row containers have sharp corners
+    - [ ] Budget Detail: Group headings, summary box, select dots all sharp
+    - [ ] Template: Group headings, skeleton placeholders, category dots all sharp
+    - [ ] Categories: Group headings, skeleton placeholders all sharp
+    - [ ] Quick Add: Picker items, category dots all sharp
+    - [ ] Settings: Card and form elements all sharp
+    - [ ] Login: Auth card sharp
+    - [ ] Register: Auth card sharp
+    - [ ] Recharts bar charts have square ends (no rounded caps)
+    - [ ] Any toast notifications have sharp corners
+
+    **Colorful pastels (DS-02):**
+    - [ ] Category color swatches are visibly colorful against white backgrounds (not washed-out or grey)
+    - [ ] Chart bar colors are vibrant and distinct from each other
+
+    **Generous whitespace (DS-03):**
+    - [ ] Section gaps feel spacious (not crowded)
+    - [ ] Card internal padding feels generous
+    - [ ] Page headers have consistent spacing before first content section
+  </how-to-verify>
+  <resume-signal>Type "approved" if all checks pass, or describe any visual issues found</resume-signal>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+No trust boundaries affected. This plan modifies CSS class strings in page JSX only.
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| — | — | — | — | No applicable threats — pure CSS class changes |
+</threat_model>
+
+<verification>
+- `bun run build` passes
+- grep confirms zero rounded-full/sm/md/lg in src/pages/
+- Human visual pass confirms all 9 pages meet DS-01, DS-02, DS-03
+</verification>
+
+<success_criteria>
+- Zero hardcoded rounded-* classes remain across all 9 page files
+- All spacing values upgraded per the mapping (space-y-8, gap-8 for sections)
+- Human confirms sharp corners visible on every page
+- Human confirms category colors are vibrant (not grey/washed-out)
+- Human confirms generous whitespace between sections
+- Build passes cleanly
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-design-system-token-rework/05-03-SUMMARY.md`
+</output>

.planning/phases/05-design-system-token-rework/05-03-SUMMARY.md

@@ -0,0 +1,110 @@
+---
+phase: 05-design-system-token-rework
+plan: "03"
+subsystem: frontend/pages
+tags: [design-system, pages, spacing, rounding, tailwind]
+dependency_graph:
+  requires: [05-01, 05-02]
+  provides: [clean-pages-no-rounding, upgraded-page-spacing]
+  affects: [all-9-pages]
+tech_stack:
+  added: []
+  patterns: [tailwind-utility-sweep, rounding-removal, spacing-upgrade]
+key_files:
+  modified:
+    - src/pages/DashboardPage.tsx
+    - src/pages/BudgetListPage.tsx
+    - src/pages/BudgetDetailPage.tsx
+    - src/pages/TemplatePage.tsx
+    - src/pages/CategoriesPage.tsx
+    - src/pages/QuickAddPage.tsx
+    - src/pages/SettingsPage.tsx
+decisions:
+  - "LoginPage and RegisterPage required no changes: no rounded-* classes present and CardContent already uses shadcn px-6 default padding"
+metrics:
+  duration: "129s"
+  completed: "2026-04-20T15:16:38Z"
+  tasks_completed: 2
+  files_modified: 7
+---
+
+# Phase 05 Plan 03: Page Rounding Sweep and Spacing Upgrade Summary
+
+Removed all hardcoded `rounded-*` Tailwind classes from 7 of 9 pages (2 required no changes) and upgraded section spacing throughout. Build passes cleanly with zero rounded-* remaining in src/pages/.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Remove rounded-* and upgrade spacing on all 9 pages | 00670af | DashboardPage, BudgetListPage, BudgetDetailPage, TemplatePage, CategoriesPage, QuickAddPage, SettingsPage |
+| 2 | Visual verification (checkpoint) | auto-approved | — |
+
+## Changes Per File
+
+**DashboardPage.tsx**
+- `space-y-6` -> `space-y-8` on main content wrapper
+- `gap-6` -> `gap-8` on 3-column chart grid
+
+**BudgetListPage.tsx**
+- Removed `rounded-md` from template toggle checkbox row (`flex items-center gap-3 border p-3`)
+
+**BudgetDetailPage.tsx**
+- Skeleton group heading: removed `rounded-sm`
+- Skeleton summary box: removed `rounded-md`
+- Live group heading: removed `rounded-sm`
+- Overall totals summary box: removed `rounded-md`
+- SelectLabel category dot: removed `rounded-full`
+
+**TemplatePage.tsx**
+- Skeleton outer wrapper: `gap-6` -> `gap-8`
+- Skeleton group heading: removed `rounded-sm`
+- Skeleton badge placeholder: removed `rounded-full`
+- Skeleton icon button placeholder: removed `rounded-md`
+- Live outer wrapper: `gap-6` -> `gap-8`
+- Live grouped items section: `space-y-6` -> `space-y-8`
+- Live group heading: removed `rounded-sm`
+- SelectLabel category dot: removed `rounded-full`
+
+**CategoriesPage.tsx**
+- Skeleton group heading: removed `rounded-sm`
+- Skeleton badge placeholder: removed `rounded-full`
+- Skeleton icon button placeholder: removed `rounded-md`
+- Skeleton section container: `space-y-6` -> `space-y-8`
+- Live grouped items section: `space-y-6` -> `space-y-8`
+- Live group heading: removed `rounded-sm`
+
+**QuickAddPage.tsx**
+- Skeleton icon badge placeholder: removed `rounded-full`
+- Skeleton action button placeholder: removed `rounded-md`
+
+**SettingsPage.tsx**
+- Both `CardContent` instances (skeleton + live): `space-y-4` -> `space-y-6`
+
+**LoginPage.tsx / RegisterPage.tsx**
+- No changes required: no `rounded-*` classes; Card rounding controlled by `--radius: 0` token cascade from 05-01
+
+## Deviations from Plan
+
+None - plan executed exactly as written. Line number references in PATTERNS.md were accurate.
+
+## Checkpoint: Task 2
+
+**Type:** human-verify
+**Auto-approved:** Yes (autonomous wave execution)
+**What was verified:** All 9 pages swept for rounded-* removal and spacing upgrade. Build passes. grep confirms zero rounded-full/sm/md/lg in src/pages/.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — pure CSS class changes in JSX, no new network surface.
+
+## Self-Check: PASSED
+
+- 7 files modified and committed at 00670af
+- `bun run build` exits 0
+- `grep -rn "rounded-full\|rounded-sm\|rounded-md\|rounded-lg" src/pages/` returns no matches
+- DashboardPage.tsx contains `space-y-8` and `gap-8` (verified)
+- SettingsPage.tsx contains `space-y-6` in CardContent (verified, both instances)

.planning/phases/05-design-system-token-rework/05-CONTEXT.md

@@ -0,0 +1,76 @@
+# Phase 5: Design System Token Rework - Context
+
+**Gathered:** 2026-04-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users see a sharp, minimal, clearly pastel UI across every page — the visual foundation that all subsequent phases build on. This phase modifies design tokens (CSS variables), adjusts spacing utilities across all 9 pages, and overrides third-party component styles. No new features, no new components — purely visual token and spacing changes.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Corner Radius Strategy
+- All elements get 0px border radius — truly sharp corners everywhere
+- Implementation via single `--radius: 0` token change in `src/index.css` (cascades to all shadcn components)
+- No exceptions for avatars, badges, or any element
+- Third-party components (Recharts bars, Sonner toasts) overridden via CSS selectors to force 0 radius
+
+### Pastel Color Refinement
+- Increase chroma on category fill colors to 0.22+ for visible colorful pop against white backgrounds
+- Keep the two-tier color system: text colors at ~0.55L for WCAG 4.5:1 contrast, fill colors lighter/more saturated
+- Slightly warm the base UI colors: background chroma from 0.005→0.01 for subtle warmth
+- Align chart colors with category fill tokens directly — remove separate `--color-chart-*` variables and use `--color-*-fill` tokens in charts
+
+### Spacing & Layout Strategy
+- Increase section gaps: gap-4→gap-6, gap-6→gap-8 across all pages
+- Increase card internal padding: p-4→p-6 for breathing room
+- Keep existing max-w-7xl container constraint
+- Standardize all page headers to mb-6 + section gaps to gap-8 for consistent rhythm
+
+### Claude's Discretion
+- Exact OKLCH chroma/lightness values for category fills (as long as they're 0.22+ chroma and pass WCAG)
+- Order of page updates during implementation
+- Whether to create a spacing utility class or apply changes inline
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `src/index.css` — single file with all design tokens (`@theme inline` block), `--radius: 0.625rem` is the token to change
+- `src/lib/palette.ts` — category color references using CSS variables (no changes needed, references tokens)
+- shadcn/ui components in `src/components/ui/` — all use `rounded-*` classes that derive from `--radius`
+
+### Established Patterns
+- OKLCH color system already in place with hue-based category differentiation
+- Two-tier category colors: text (L=0.55, C=0.16-0.18) and fill (L=0.65-0.70, C=0.18-0.20)
+- Tailwind CSS 4 with `@theme inline` for CSS variable definitions
+- 71 occurrences of `rounded`/`radius` across 27 source files
+
+### Integration Points
+- `src/index.css` `--radius` token controls all shadcn component rounding
+- Chart components (`SpendBarChart`, `IncomeBarChart`, `ExpenseDonutChart`) reference `--color-chart-*` variables
+- 9 pages to audit: Dashboard, BudgetList, BudgetDetail, Template, Categories, QuickAdd, Settings, Login, Register
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Success criteria explicitly requires visual pass of all 9 pages confirming no regressions
+- Category color swatches must be "visibly colorful against white backgrounds" — not washed-out
+- "No pill buttons, no rounded cards, no rounded inputs visible anywhere"
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>

.planning/phases/05-design-system-token-rework/05-PATTERNS.md

@@ -0,0 +1,677 @@
+# Phase 5: Design System Token Rework - Pattern Map
+
+**Mapped:** 2026-04-20
+**Files analyzed:** 14 files (1 CSS + 2 chart components + 1 shared component + 9 pages + 1 component)
+**Analogs found:** 14 / 14 (all files are modifications of existing code — no new files created)
+
+---
+
+## File Classification
+
+| Modified File | Role | Data Flow | Closest Analog / Self | Match Quality |
+|---|---|---|---|---|
+| `src/index.css` | config (CSS tokens) | transform | self — no analog needed | self |
+| `src/components/dashboard/charts/SpendBarChart.tsx` | component (chart) | transform | `src/components/dashboard/charts/IncomeBarChart.tsx` | exact |
+| `src/components/dashboard/charts/IncomeBarChart.tsx` | component (chart) | transform | `src/components/dashboard/charts/SpendBarChart.tsx` | exact |
+| `src/components/dashboard/charts/ExpenseDonutChart.tsx` | component (chart) | transform | `SpendBarChart.tsx` / `IncomeBarChart.tsx` | role-match |
+| `src/components/shared/PageShell.tsx` | component (layout) | request-response | self | self |
+| `src/components/dashboard/DashboardSkeleton.tsx` | component (skeleton) | request-response | `CategoriesPage.tsx` skeleton block | role-match |
+| `src/components/dashboard/CategorySection.tsx` | component (list item) | request-response | `BudgetDetailPage.tsx` group heading | role-match |
+| `src/components/dashboard/charts/ChartEmptyState.tsx` | component (empty state) | request-response | self | self |
+| `src/components/QuickAddPicker.tsx` | component (picker) | request-response | `BudgetDetailPage.tsx` select label dot | role-match |
+| `src/pages/DashboardPage.tsx` | page | request-response | self | self |
+| `src/pages/BudgetListPage.tsx` | page | request-response | `DashboardPage.tsx` / `BudgetDetailPage.tsx` | role-match |
+| `src/pages/BudgetDetailPage.tsx` | page | CRUD | `CategoriesPage.tsx` / `TemplatePage.tsx` | exact |
+| `src/pages/TemplatePage.tsx` | page | CRUD | `BudgetDetailPage.tsx` / `CategoriesPage.tsx` | exact |
+| `src/pages/CategoriesPage.tsx` | page | CRUD | `BudgetDetailPage.tsx` / `TemplatePage.tsx` | exact |
+| `src/pages/QuickAddPage.tsx` | page | CRUD | `CategoriesPage.tsx` | role-match |
+| `src/pages/SettingsPage.tsx` | page | request-response | `CategoriesPage.tsx` | role-match |
+| `src/pages/LoginPage.tsx` | page | request-response | `SettingsPage.tsx` | role-match |
+| `src/pages/RegisterPage.tsx` | page | request-response | `SettingsPage.tsx` | role-match |
+
+---
+
+## Pattern Assignments
+
+### `src/index.css` (config, CSS tokens)
+
+**Analog:** self — authoritative token source, no external analog needed.
+
+**Current `@theme inline` block** (lines 1-99, full file):
+
+```css
+@import "tailwindcss";
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: oklch(0.98 0.005 260);   /* → 0.01 chroma (warm) */
+  --color-foreground: oklch(0.25 0.02 260);
+
+  /* ... (base tokens unchanged) ... */
+
+  /* Category fill tokens — RAISE chroma to 0.22+ */
+  --color-income-fill: oklch(0.68 0.19 155);   /* → 0.22 */
+  --color-bill-fill: oklch(0.65 0.19 25);       /* → 0.22 */
+  --color-variable-expense-fill: oklch(0.70 0.18 50); /* → 0.22 */
+  --color-debt-fill: oklch(0.60 0.20 355);      /* → 0.23 */
+  --color-saving-fill: oklch(0.68 0.18 220);    /* → 0.22 */
+  --color-investment-fill: oklch(0.65 0.18 285); /* → 0.22 */
+
+  /* Chart vars — DELETE these 5 lines entirely */
+  --color-chart-1: oklch(0.72 0.14 155);
+  --color-chart-2: oklch(0.7 0.14 25);
+  --color-chart-3: oklch(0.72 0.14 50);
+  --color-chart-4: oklch(0.65 0.16 355);
+  --color-chart-5: oklch(0.72 0.14 220);
+
+  --radius: 0.625rem;  /* → 0 */
+}
+
+@layer base {
+  * { @apply border-border; }
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
+}
+```
+
+**Changes to make in this file:**
+1. Line 7: `--color-background: oklch(0.98 0.005 260)` → `oklch(0.98 0.01 260)`
+2. Lines 65-70: raise all six `--color-*-fill` chroma values to 0.22+ per CONTEXT.md
+3. Lines 52-57: delete `--color-chart-1` through `--color-chart-5` entirely
+4. Line 72: `--radius: 0.625rem` → `--radius: 0`
+5. After `@layer base` block: add CSS override selectors for Recharts and Sonner (see Shared Patterns section below)
+
+---
+
+### `src/components/dashboard/charts/SpendBarChart.tsx` (component, transform)
+
+**Analog:** `src/components/dashboard/charts/IncomeBarChart.tsx`
+
+**Current `Bar` radius props** (lines 64-80):
+
+```tsx
+<Bar
+  dataKey="budgeted"
+  fill="var(--color-budgeted)"
+  radius={4}           /* → radius={0} */
+/>
+<Bar dataKey="actual" radius={4}>   /* → radius={0} */
+  {data.map((entry, index) => (
+    <Cell
+      key={index}
+      fill={
+        entry.actual > entry.budgeted
+          ? "var(--color-over-budget)"
+          : `var(--color-${entry.type}-fill)`  /* already correct — no change */
+      }
+    />
+  ))}
+</Bar>
+```
+
+**Changes to make in this file:**
+- Line 67: `radius={4}` → `radius={0}`
+- Line 69: `radius={4}` → `radius={0}`
+- `chartConfig` (lines 31-34): no change needed — `actual` already references `--color-muted-foreground`, `budgeted` references `--color-budget-bar-bg`; neither references deleted `--color-chart-*` vars.
+
+---
+
+### `src/components/dashboard/charts/IncomeBarChart.tsx` (component, transform)
+
+**Analog:** `src/components/dashboard/charts/SpendBarChart.tsx`
+
+**Current `Bar` radius props** (lines 54-69):
+
+```tsx
+<Bar
+  dataKey="budgeted"
+  fill="var(--color-budgeted)"
+  radius={[4, 4, 0, 0]}    /* → radius={0} */
+/>
+<Bar dataKey="actual" radius={[4, 4, 0, 0]}>  /* → radius={0} */
+  {data.map((entry, index) => (
+    <Cell
+      key={index}
+      fill={
+        entry.actual > entry.budgeted
+          ? "var(--color-over-budget)"
+          : "var(--color-income-fill)"   /* already correct — no change */
+      }
+    />
+  ))}
+</Bar>
+```
+
+**Current `chartConfig`** (lines 26-29):
+
+```tsx
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-income-fill)" },  /* already references fill token */
+} satisfies ChartConfig
+```
+
+**Changes to make in this file:**
+- Line 57: `radius={[4, 4, 0, 0]}` → `radius={0}`
+- Line 59: `radius={[4, 4, 0, 0]}` → `radius={0}`
+- `chartConfig`: no change needed — already references `--color-income-fill`, not a deleted `--color-chart-*` var.
+
+---
+
+### `src/components/dashboard/charts/ExpenseDonutChart.tsx` (component, transform)
+
+**Analog:** self — already uses `var(--color-${entry.type}-fill)` pattern throughout.
+
+**The one hardcoded `rounded-full`** (line 141):
+
+```tsx
+/* Before */
+<span
+  className="inline-block size-3 shrink-0 rounded-full"
+  style={{ backgroundColor: `var(--color-${entry.type}-fill)` }}
+/>
+
+/* After — remove rounded-full entirely */
+<span
+  className="inline-block size-3 shrink-0"
+  style={{ backgroundColor: `var(--color-${entry.type}-fill)` }}
+/>
+```
+
+**Changes to make in this file:**
+- Line 141: remove `rounded-full` from className string.
+- No `ChartConfig` changes needed — `ExpenseDonutChart` builds its config dynamically from data using `var(--color-${entry.type}-fill)` (lines 47-51), which is already the correct post-rework pattern.
+
+---
+
+### `src/components/shared/PageShell.tsx` (component, layout)
+
+**Current spacing** (line 15):
+
+```tsx
+<div className="flex flex-col gap-6">   /* → gap-8 */
+```
+
+**Changes to make in this file:**
+- Line 15: `gap-6` → `gap-8`
+
+This single change propagates the header-to-content gap increase to all 9 pages that use `PageShell`.
+
+---
+
+### `src/components/dashboard/DashboardSkeleton.tsx` (component, skeleton)
+
+**Analog:** Skeleton patterns from `CategoriesPage.tsx` lines 98-114 and `BudgetDetailPage.tsx` lines 284-306.
+
+**Hardcoded `rounded-*` locations in this file:**
+
+```tsx
+/* Line 35 — chart placeholder */
+<Skeleton className="h-[250px] w-full rounded-md" />  /* remove rounded-md */
+
+/* Line 43 — chart placeholder */
+<Skeleton className="h-[250px] w-full rounded-md" />  /* remove rounded-md */
+
+/* Line 51 — chart placeholder */
+<Skeleton className="h-[250px] w-full rounded-md" />  /* remove rounded-md */
+
+/* Line 59 — collapsible section row */
+<div className="flex items-center gap-3 rounded-md border-l-4 ...">  /* remove rounded-md */
+
+/* Lines 63-64 — inline summary badges */
+<Skeleton className="h-5 w-24 rounded-full" />  /* remove rounded-full — CRITICAL: rounded-full is 9999px, not from --radius */
+<Skeleton className="h-5 w-24 rounded-full" />  /* remove rounded-full */
+```
+
+**Also: spacing upgrades**:
+
+```tsx
+/* Line 20 — top-level container */
+<div className="flex flex-col gap-6">   /* → gap-8 */
+
+/* Line 22 — summary cards grid */
+<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">  /* → gap-6 */
+
+/* Line 29 — chart grid */
+<div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">  /* → gap-8 */
+```
+
+---
+
+### `src/components/dashboard/CategorySection.tsx` (component, list item)
+
+**Analog:** Group heading divs in `BudgetDetailPage.tsx` lines 352-356, `CategoriesPage.tsx` lines 134-137, `TemplatePage.tsx` lines 292-295.
+
+**The hardcoded `rounded-md`** (line 73):
+
+```tsx
+/* Before */
+<button
+  className="group flex w-full items-center gap-3 rounded-md border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+
+/* After — remove rounded-md */
+<button
+  className="group flex w-full items-center gap-3 border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+```
+
+**Changes to make in this file:**
+- Line 73: remove `rounded-md` from the button's className.
+
+---
+
+### `src/components/dashboard/charts/ChartEmptyState.tsx` (component, empty state)
+
+**Current `rounded-lg`** (line 12):
+
+```tsx
+/* Before */
+className={cn(
+  "flex min-h-[250px] w-full items-center justify-center rounded-lg border border-dashed ...",
+  className
+)}
+
+/* After — remove rounded-lg */
+className={cn(
+  "flex min-h-[250px] w-full items-center justify-center border border-dashed ...",
+  className
+)}
+```
+
+**Changes to make in this file:**
+- Line 12: remove `rounded-lg` from the className string.
+
+---
+
+### `src/components/QuickAddPicker.tsx` (component, picker)
+
+**Analog:** Same pattern as `BudgetDetailPage.tsx` line 496 and `TemplatePage.tsx` line 385 — `size-2 rounded-full` color swatch dots used as SelectLabel decorators.
+
+**Hardcoded `rounded-*` locations:**
+
+```tsx
+/* Line 156 — picker item button */
+className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 ..."
+/* → remove rounded-sm */
+
+/* Line 201 — SelectLabel category dot */
+<div
+  className="size-2 rounded-full"
+  style={{ backgroundColor: categoryColors[type] }}
+/>
+/* → remove rounded-full */
+```
+
+**Changes to make in this file:**
+- Line 156: remove `rounded-sm` from className.
+- Line 201: remove `rounded-full` from className.
+
+---
+
+### `src/pages/DashboardPage.tsx` (page, request-response)
+
+**Current spacing** (lines 186, 207):
+
+```tsx
+/* Line 186 — DashboardContent top-level wrapper */
+<div className="space-y-6">     /* → space-y-8 */
+
+/* Line 207 — chart grid */
+<div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">   /* → gap-8 */
+```
+
+**Changes to make in this file:**
+- Line 186: `space-y-6` → `space-y-8`
+- Line 207: `gap-6` → `gap-8`
+
+No hardcoded `rounded-*` classes in this file.
+
+---
+
+### `src/pages/BudgetListPage.tsx` (page, CRUD)
+
+**Analog:** `BudgetDetailPage.tsx` lines 242-256 — same `rounded-md border p-3` container pattern.
+
+**Hardcoded `rounded-md`** (line 243):
+
+```tsx
+/* Before */
+<div className="flex items-center gap-3 rounded-md border p-3">
+
+/* After */
+<div className="flex items-center gap-3 border p-3">
+```
+
+**Spacing:** Check for `gap-4`, `gap-6`, `space-y-*` patterns and apply standard upgrades:
+- `gap-4` → `gap-6`
+- `gap-6` → `gap-8`
+- `space-y-6` → `space-y-8`
+
+---
+
+### `src/pages/BudgetDetailPage.tsx` (page, CRUD)
+
+**Analog:** `CategoriesPage.tsx` and `TemplatePage.tsx` — structurally identical page pattern (group headings, Tables, PageShell).
+
+**Hardcoded `rounded-*` locations** (confirmed from RESEARCH.md inventory):
+
+| Line | Current | Action |
+|------|---------|--------|
+| 290 | `rounded-sm` on skeleton header div | Remove |
+| 303 | `rounded-md` on `<Skeleton>` className | Remove |
+| 353 | `rounded-sm` on budget item group heading div | Remove |
+| 439 | `rounded-md` on summary totals box | Remove |
+| 497 | `rounded-full` on SelectLabel category dot | Remove |
+
+**Line 353 group heading** (current pattern to modify):
+
+```tsx
+/* Before */
+<div
+  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+
+/* After */
+<div
+  className="mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+```
+
+**Line 439 summary box** (current pattern to modify):
+
+```tsx
+/* Before */
+<div className="rounded-md border p-4">
+
+/* After */
+<div className="border p-4">
+```
+
+**Spacing upgrades:**
+- `space-y-8` already present at line 338 (inner grouped content) — verify no `space-y-6` / `gap-6` remaining
+- Check for `p-4` on card content wrappers → `p-6`
+
+---
+
+### `src/pages/TemplatePage.tsx` (page, CRUD)
+
+**Analog:** `BudgetDetailPage.tsx` — same group heading + Table structure, same skeleton pattern.
+
+**Hardcoded `rounded-*` locations** (confirmed from RESEARCH.md inventory):
+
+| Line | Current | Action |
+|------|---------|--------|
+| 250 | `rounded-sm` on skeleton group heading div | Remove |
+| 256 | `rounded-full` on `<Skeleton>` className | Remove |
+| 258 | `rounded-md` on `<Skeleton>` className | Remove |
+| 292 | `rounded-sm` on template item group heading div | Remove |
+| 385 | `rounded-full` on SelectLabel category dot | Remove |
+
+**Line 292 group heading** (current):
+
+```tsx
+/* Before */
+<div
+  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+```
+
+Same removal pattern as `BudgetDetailPage.tsx` line 353.
+
+**Line 385 SelectLabel dot** (current):
+
+```tsx
+/* Before — same pattern as BudgetDetailPage line 497 */
+<div
+  className="size-2 rounded-full"
+  style={{ backgroundColor: categoryColors[type] }}
+/>
+/* After: remove rounded-full */
+```
+
+**Spacing upgrades** (current at lines 247, 268, 287):
+- Line 247: `space-y-6` → `space-y-8` (skeleton wrapper)
+- Line 268: `gap-6` → `gap-8` (TemplatePage own flex header, not using PageShell)
+- Line 287: `space-y-6` → `space-y-8` (main content groups)
+
+---
+
+### `src/pages/CategoriesPage.tsx` (page, CRUD)
+
+**Analog:** `BudgetDetailPage.tsx` / `TemplatePage.tsx` — structurally identical.
+
+**Hardcoded `rounded-*` locations** (confirmed from RESEARCH.md inventory):
+
+| Line | Current | Action |
+|------|---------|--------|
+| 101 | `rounded-sm` on skeleton group heading div | Remove |
+| 107 | `rounded-full` on `<Skeleton>` className | Remove |
+| 108 | `rounded-md` on `<Skeleton>` className | Remove |
+| 134 | `rounded-sm` on category group heading div | Remove |
+
+**Line 134 group heading** (current):
+
+```tsx
+/* Before */
+<div
+  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+/* After: remove rounded-sm */
+```
+
+**Spacing upgrades** (current at lines 98, 130):
+- Line 98: `space-y-6` → `space-y-8` (skeleton wrapper)
+- Line 130: `space-y-6` → `space-y-8` (main content groups)
+
+---
+
+### `src/pages/QuickAddPage.tsx` (page, CRUD)
+
+**Analog:** `CategoriesPage.tsx` — same row-list layout, same Skeleton usage.
+
+**Hardcoded `rounded-*` locations** (confirmed from RESEARCH.md inventory):
+
+| Line | Current | Action |
+|------|---------|--------|
+| 98 | `rounded-full` on `<Skeleton>` className | Remove |
+| 100 | `rounded-md` on `<Skeleton>` className | Remove |
+
+**Current skeleton block** (lines 93-105):
+
+```tsx
+<div className="space-y-1">
+  {[1, 2, 3, 4, 5].map((i) => (
+    <div key={i} className="flex items-center gap-4 px-4 py-2.5 border-b border-border">
+      <Skeleton className="h-5 w-10 rounded-full" />   /* line 98 — remove rounded-full */
+      <Skeleton className="h-4 w-36" />
+      <Skeleton className="ml-auto h-7 w-7 rounded-md" />  /* line 100 — remove rounded-md */
+    </div>
+  ))}
+</div>
+```
+
+No major spacing changes in this file (list layout, not grid/section-based).
+
+---
+
+### `src/pages/SettingsPage.tsx` (page, request-response)
+
+**Analog:** `CategoriesPage.tsx` — PageShell wrapper, Card with CardContent.
+
+**No hardcoded `rounded-*` classes** in this file (Card uses token cascade).
+
+**Spacing upgrade** (line 87):
+
+```tsx
+/* Before — CardContent internal spacing */
+<CardContent className="space-y-4 pt-6">   /* → space-y-6 */
+```
+
+**Changes to make in this file:**
+- Line 87 (and corresponding skeleton line 69): `space-y-4` → `space-y-6` inside `CardContent`
+
+---
+
+### `src/pages/LoginPage.tsx` and `src/pages/RegisterPage.tsx` (pages, request-response)
+
+**Analog:** `SettingsPage.tsx` — Card-based page, no group headings.
+
+Per RESEARCH.md: "Card already uses `--radius` token cascade." No hardcoded `rounded-*` classes confirmed. No `--color-chart-*` references.
+
+**Minimal changes:** Verify `p-4` → `p-6` in any card content wrappers if present. No spacing grids to upgrade. Treat as low-touch pages in implementation.
+
+---
+
+## Shared Patterns
+
+### Pattern A: `@theme inline` Token Edit (CSS variable cascade)
+
+**Source:** `src/index.css` lines 4-79
+**Apply to:** `src/index.css` only — single source of truth
+**Rule:** All shadcn `rounded-*` utility classes (rounded-md, rounded-sm, rounded-lg, rounded-xl) derive from `--radius`. Setting `--radius: 0` makes them all 0px automatically. Only `rounded-full` (9999px) is immune.
+
+```css
+/* The pattern: edit token value, cascade propagates everywhere */
+@theme inline {
+  --radius: 0;  /* single edit cascades to all shadcn components */
+}
+```
+
+### Pattern B: Hardcoded `rounded-full` Removal (critical pitfall)
+
+**Source:** Every page and component file listed in RESEARCH.md inventory
+**Apply to:** All 17 `rounded-full` class occurrences across 8 files
+**Rule:** `rounded-full` = `border-radius: 9999px` — hardcoded, NOT derived from `--radius`. Must be removed manually from every occurrence.
+
+```tsx
+/* Before — still circular after --radius: 0 */
+<Skeleton className="h-5 w-16 rounded-full" />
+<span className="inline-block size-3 shrink-0 rounded-full" ... />
+<div className="size-2 rounded-full" ... />
+
+/* After — becomes square from --radius: 0 */
+<Skeleton className="h-5 w-16" />
+<span className="inline-block size-3 shrink-0" ... />
+<div className="size-2" ... />
+```
+
+### Pattern C: CSS Override for Third-Party Radius
+
+**Source:** To be added to `src/index.css` after `@layer base` block
+**Apply to:** Recharts bars (`SpendBarChart`, `IncomeBarChart`) and Sonner toasts
+**Rule:** Recharts renders bars as `<rect rx="4" ry="4">` SVG — not CSS. Must change `radius` prop directly AND add CSS override. Sonner wires `--border-radius: var(--radius)` (confirmed at `sonner.tsx` line 28) — should auto-propagate, but add CSS override as safety net.
+
+```css
+/* Add to src/index.css after the @layer base block */
+
+/* Recharts: SVG rect elements for bar charts */
+.recharts-rectangle {
+  rx: 0;
+  ry: 0;
+}
+
+/* Sonner: toast container — safety net if var(--radius) cascade insufficient */
+[data-sonner-toast] {
+  border-radius: 0 !important;
+}
+```
+
+**Note:** Sonner's `sonner.tsx` already passes `"--border-radius": "var(--radius)"` as an inline style (line 28). When `--radius: 0`, this should cascade automatically. The CSS override is a safety net only — verify in browser after token change before deciding if it is needed.
+
+### Pattern D: Group Heading Div (shared across 5 files)
+
+**Source:** `src/pages/CategoriesPage.tsx` line 134, `BudgetDetailPage.tsx` line 353, `TemplatePage.tsx` line 292 — all structurally identical
+**Apply to:** CategoriesPage, BudgetDetailPage, TemplatePage, CategorySection, DashboardSkeleton row
+
+```tsx
+/* Pattern: border-l-4 accent bar heading — remove rounded-sm entirely */
+<div
+  className="mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"
+  style={{ borderLeftColor: categoryColors[type] }}
+>
+  <span className="text-sm font-semibold">{label}</span>
+</div>
+```
+
+### Pattern E: Spacing Upgrade Map
+
+**Source:** `src/pages/DashboardPage.tsx` lines 186, 207; `src/components/shared/PageShell.tsx` line 15
+**Apply to:** All 9 pages and PageShell
+
+```
+PageShell.tsx line 15:     gap-6      → gap-8      (header-to-content gap)
+DashboardPage.tsx line 186: space-y-6 → space-y-8  (section rhythm)
+DashboardPage.tsx line 207: gap-6     → gap-8      (chart grid)
+DashboardSkeleton.tsx line 22: gap-4  → gap-6      (summary cards grid)
+DashboardSkeleton.tsx line 29: gap-6  → gap-8      (chart grid skeleton)
+CategoriesPage.tsx line 98:  space-y-6 → space-y-8  (skeleton wrapper)
+CategoriesPage.tsx line 130: space-y-6 → space-y-8  (main content)
+TemplatePage.tsx line 247:   space-y-6 → space-y-8  (skeleton wrapper)
+TemplatePage.tsx line 268:   gap-6     → gap-8      (self-managed header flex)
+TemplatePage.tsx line 287:   space-y-6 → space-y-8  (main content)
+BudgetDetailPage.tsx:        verify no space-y-6/gap-6 remain after existing space-y-8 at line 338
+SettingsPage.tsx line 87:    space-y-4 → space-y-6  (CardContent internal)
+```
+
+### Pattern F: `ChartConfig` Token Reference (no `--color-chart-*`)
+
+**Source:** `src/components/dashboard/charts/IncomeBarChart.tsx` lines 26-29
+**Apply to:** Any future chart components — `SpendBarChart` and `IncomeBarChart` require no ChartConfig change
+**Rule:** After deleting `--color-chart-*` from `index.css`, all chart color references must use `--color-*-fill` tokens.
+
+```tsx
+/* Correct pattern post-rework — reference fill tokens directly */
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-income-fill)" },
+} satisfies ChartConfig
+```
+
+---
+
+## No Analog Found
+
+None — all files are modifications of existing code. No net-new files are created in this phase.
+
+---
+
+## Implementation Wave Order
+
+Per RESEARCH.md recommendation (planner reference):
+
+**Wave 1 — Token edit only** (`src/index.css`)
+- Change `--radius: 0`
+- Raise `--color-*-fill` chroma values to 0.22+
+- Warm `--color-background` chroma 0.005 → 0.01
+- Delete `--color-chart-1` through `--color-chart-5`
+- Add `.recharts-rectangle` and `[data-sonner-toast]` CSS overrides
+
+**Wave 2 — Chart component updates** (2 files)
+- `SpendBarChart.tsx`: `radius={4}` → `radius={0}` (x2 Bar props)
+- `IncomeBarChart.tsx`: `radius={[4, 4, 0, 0]}` → `radius={0}` (x2 Bar props)
+- `ExpenseDonutChart.tsx`: remove `rounded-full` from legend span (line 141)
+
+**Wave 3 — Page and shared component sweep** (12 files)
+- `PageShell.tsx`: `gap-6` → `gap-8`
+- `DashboardSkeleton.tsx`: remove 5 `rounded-*` classes, upgrade 3 spacing values
+- `CategorySection.tsx`: remove `rounded-md` from trigger button
+- `ChartEmptyState.tsx`: remove `rounded-lg` from empty state div
+- `QuickAddPicker.tsx`: remove 2 `rounded-*` classes
+- All 9 pages: spacing upgrades + hardcoded `rounded-*` removals per inventory
+
+---
+
+## Metadata
+
+**Analog search scope:** `src/pages/`, `src/components/dashboard/`, `src/components/shared/`, `src/components/ui/`, `src/index.css`
+**Files read for pattern extraction:** 16 (index.css, PageShell, DashboardPage, DashboardSkeleton, SpendBarChart, IncomeBarChart, ExpenseDonutChart, ChartEmptyState, CategorySection, QuickAddPicker, SettingsPage, BudgetDetailPage excerpt x3, CategoriesPage excerpt, TemplatePage excerpt, QuickAddPage excerpt, BudgetListPage excerpt, sonner.tsx)
+**Pattern extraction date:** 2026-04-20

.planning/phases/05-design-system-token-rework/05-RESEARCH.md

@@ -0,0 +1,550 @@
+# Phase 5: Design System Token Rework - Research
+
+**Researched:** 2026-04-20
+**Domain:** CSS design tokens, Tailwind CSS 4 `@theme inline`, OKLCH color, shadcn/ui, Recharts, Sonner
+**Confidence:** HIGH
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- All elements get 0px border radius — truly sharp corners everywhere
+- Implementation via single `--radius: 0` token change in `src/index.css` (cascades to all shadcn components)
+- No exceptions for avatars, badges, or any element
+- Third-party components (Recharts bars, Sonner toasts) overridden via CSS selectors to force 0 radius
+- Increase chroma on category fill colors to 0.22+ for visible colorful pop against white backgrounds
+- Keep the two-tier color system: text colors at ~0.55L for WCAG 4.5:1 contrast, fill colors lighter/more saturated
+- Slightly warm the base UI colors: background chroma from 0.005→0.01 for subtle warmth
+- Align chart colors with category fill tokens directly — remove separate `--color-chart-*` variables and use `--color-*-fill` tokens in charts
+- Increase section gaps: gap-4→gap-6, gap-6→gap-8 across all pages
+- Increase card internal padding: p-4→p-6 for breathing room
+- Keep existing max-w-7xl container constraint
+- Standardize all page headers to mb-6 + section gaps to gap-8 for consistent rhythm
+
+### Claude's Discretion
+- Exact OKLCH chroma/lightness values for category fills (as long as they're 0.22+ chroma and pass WCAG)
+- Order of page updates during implementation
+- Whether to create a spacing utility class or apply changes inline
+
+### Deferred Ideas (OUT OF SCOPE)
+None — discussion stayed within phase scope
+</user_constraints>
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| DS-01 | User sees sharp-edged UI across all pages (no rounded corners) | Single `--radius: 0` token in index.css cascades to all shadcn/ui components; hardcoded `rounded-*` Tailwind classes in pages/components require explicit removal; Recharts bars and Sonner toasts require CSS override selectors |
+| DS-02 | User sees clear pastel colors that are visibly colorful, not washed out | Raise `--color-*-fill` chroma from 0.18-0.20 to 0.22+; remove `--color-chart-*` variables; point chart components to `--color-*-fill` tokens directly |
+| DS-03 | User sees a clean, minimal layout with generous whitespace | Upgrade `space-y-6`→`space-y-8`, `gap-6`→`gap-8` across 9 pages; `p-4`→`p-6` for card internals; standardize PageShell gap to `gap-8` |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 5 is a pure design token and spacing rework with zero feature additions. The codebase uses Tailwind CSS 4's `@theme inline` block in `src/index.css` as the single source of truth for all CSS custom properties. Because shadcn/ui components reference `--radius` via Tailwind's `rounded-*` utility classes that are generated from this token, setting `--radius: 0` in `src/index.css` propagates automatically to every shadcn component. No changes to `src/components/ui/` files are needed for the radius.
+
+However, hardcoded `rounded-*` Tailwind classes exist in 6 page files and 4 component files — these are not driven by `--radius` and must be removed or changed to `rounded-none` explicitly. Additionally, Recharts bar components pass a `radius` prop (not CSS) and require a CSS selector override in `index.css`. Sonner toasts pass `--border-radius` as an inline style through the Toaster component and additionally need a CSS override.
+
+The color work has two parts: (1) editing token values in `src/index.css` only, and (2) removing `--color-chart-*` variables from `index.css` and updating the two chart components that currently reference them via `ChartConfig` objects to instead reference `--color-*-fill` tokens.
+
+**Primary recommendation:** Execute as three focused waves — (1) token edit in `index.css` (radius + colors + remove chart vars), (2) chart component updates to reference fill tokens, (3) per-page spacing and hardcoded `rounded-*` sweep across all 9 pages.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Design token definition | CSS (index.css) | — | Single `@theme inline` block is the authoritative token source |
+| shadcn component rounding | CSS token cascade | — | `rounded-*` utilities derive from `--radius`; no component code change needed |
+| Hardcoded Tailwind class removal | Page/component TSX | — | `rounded-full`, `rounded-md` etc. are inline JSX; must be changed in source files |
+| Recharts bar radius override | CSS global selector | Recharts prop | CSS `rect` selector overrides SVG radius attribute; prop change is alternative |
+| Sonner toast radius override | CSS global selector | Sonner component | Inline `--border-radius` style in sonner.tsx; CSS override wins |
+| Color token values | CSS (index.css) | — | All category and fill colors live in `@theme inline` |
+| Chart color wiring | Chart TSX components | CSS tokens | `ChartConfig` objects in SpendBarChart and IncomeBarChart must reference fill tokens |
+| Page spacing | Page TSX files | Shared components | `gap-*`, `space-y-*`, `p-*` are inline classes in page JSX |
+
+---
+
+## Standard Stack
+
+### Core
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Tailwind CSS | 4.2.1 | Utility CSS + token system (`@theme inline`) | Already installed; `@theme inline` is the v4 way to define CSS variables as Tailwind utilities |
+| shadcn/ui | new-york preset | Component layer above Radix UI | Already installed; all components in `src/components/ui/` |
+| Recharts | 2.15.4 | Chart rendering (BarChart, PieChart) | Already installed; SpendBarChart, IncomeBarChart, ExpenseDonutChart use it |
+| Sonner | 2.0.7 | Toast notifications | Already installed; `src/components/ui/sonner.tsx` wraps it |
+
+### Supporting
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| OKLCH (native CSS) | CSS Color Level 4 | Perceptually uniform color space | Already in use; all token edits stay in OKLCH |
+
+No new libraries are needed for this phase.
+
+**Installation:** None required.
+
+---
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+src/index.css (@theme inline)
+    │
+    ├── --radius: 0              ──cascade──► all shadcn rounded-* classes
+    ├── --color-background: ...  ──cascade──► bg-background utility
+    ├── --color-*-fill: ...      ──cascade──► var(--color-*-fill) in chart components
+    └── [--color-chart-* REMOVED]
+         │
+         ▼
+src/components/ui/*.tsx (shadcn)
+    │  Button, Card, Input, Badge, Select, Dialog, Sheet, Sidebar, ...
+    │  All use rounded-* utilities → auto-sharp from --radius: 0
+    ▼
+src/components/dashboard/charts/*.tsx
+    │  SpendBarChart, IncomeBarChart: update ChartConfig + Bar radius prop → 0
+    │  ExpenseDonutChart: already uses var(--color-*-fill); no ChartConfig change needed
+    ▼
+src/pages/*.tsx (9 pages)
+    │  Remove hardcoded rounded-* classes
+    │  Upgrade spacing: space-y-6→space-y-8, gap-6→gap-8, p-4→p-6
+    ▼
+src/index.css (@layer base or global)
+    └── CSS overrides for third-party radius
+         ├── .recharts-rectangle { rx: 0; ry: 0; border-radius: 0 }
+         └── [data-sonner-toast] { border-radius: 0 }
+```
+
+### Recommended Project Structure
+
+No structural changes. Files modified:
+
+```
+src/
+├── index.css                          # Token edits: --radius, --color-*-fill, remove --color-chart-*; CSS overrides
+├── components/
+│   └── dashboard/
+│       └── charts/
+│           ├── SpendBarChart.tsx      # Update ChartConfig + Bar radius prop
+│           └── IncomeBarChart.tsx     # Update ChartConfig + Bar radius prop
+└── pages/
+    ├── DashboardPage.tsx              # Spacing: space-y-6→space-y-8, gap-6→gap-8
+    ├── BudgetListPage.tsx             # Spacing + remove rounded-md from row div
+    ├── BudgetDetailPage.tsx           # Spacing + remove rounded-* classes
+    ├── TemplatePage.tsx               # Spacing + remove rounded-sm, rounded-full
+    ├── CategoriesPage.tsx             # Spacing + remove rounded-sm, rounded-full
+    ├── QuickAddPage.tsx               # Remove rounded-full, rounded-md
+    ├── SettingsPage.tsx               # Spacing: space-y-4→space-y-6 in card content
+    ├── LoginPage.tsx                  # Card already uses --radius token cascade
+    └── RegisterPage.tsx               # Card already uses --radius token cascade
+```
+
+### Pattern 1: Tailwind 4 `@theme inline` Token Edit
+
+**What:** All CSS variables in the `@theme inline` block are automatically available as Tailwind utility classes. Changing a value in this block propagates everywhere the utility is used.
+**When to use:** Changing `--radius`, color tokens, any design-system-level property.
+**Example:**
+```css
+/* src/index.css */
+@theme inline {
+  --radius: 0;  /* was 0.625rem — single change, cascades everywhere */
+
+  /* Fill colors: raise chroma to 0.22+ */
+  --color-income-fill: oklch(0.72 0.22 155);
+  --color-bill-fill: oklch(0.70 0.22 25);
+  --color-variable-expense-fill: oklch(0.74 0.22 50);
+  --color-debt-fill: oklch(0.66 0.23 355);
+  --color-saving-fill: oklch(0.72 0.22 220);
+  --color-investment-fill: oklch(0.68 0.22 285);
+
+  /* Background: warm slightly */
+  --color-background: oklch(0.98 0.01 260);
+
+  /* Remove --color-chart-1 through --color-chart-5 entirely */
+}
+```
+[VERIFIED: codebase — src/index.css lines 1-99]
+
+### Pattern 2: CSS Selector Override for Third-Party Radius
+
+**What:** When a third-party library applies border-radius via its own SVG attributes or inline styles, a targeted CSS selector override in `@layer base` in `index.css` forces the desired value.
+**When to use:** Recharts bar SVG rectangles, Sonner toast container.
+**Example:**
+```css
+/* src/index.css — in @layer base block or after @theme */
+/* Recharts: bars are SVG <rect> elements; CSS border-radius overrides SVG rx/ry */
+.recharts-rectangle {
+  rx: 0;
+  ry: 0;
+}
+
+/* Sonner: targets the toast wrapper element */
+[data-sonner-toast] {
+  border-radius: 0 !important;
+}
+```
+[ASSUMED — selector names from Recharts/Sonner DOM inspection convention; verify in browser devtools during implementation]
+
+### Pattern 3: Hardcoded Tailwind Class Removal
+
+**What:** `rounded-full`, `rounded-md`, `rounded-sm`, `rounded-lg` as inline className strings in TSX are not driven by `--radius`. They must be removed or replaced with `rounded-none`.
+**When to use:** Category color swatches, skeleton shapes, chart legend dots, picker items.
+**Example:**
+```tsx
+/* Before — in ExpenseDonutChart.tsx line 141 */
+<span className="inline-block size-3 shrink-0 rounded-full" ... />
+
+/* After */
+<span className="inline-block size-3 shrink-0" ... />
+/* or explicitly: rounded-none if you need to reset a parent's rounded */
+```
+[VERIFIED: codebase scan]
+
+### Pattern 4: Chart Component Token Wiring
+
+**What:** `SpendBarChart` and `IncomeBarChart` use `ChartConfig` objects to map data keys to colors. Currently `IncomeBarChart.actual` is `color: "var(--color-income-fill)"` — already correct. `SpendBarChart.budgeted` uses `--color-budget-bar-bg` and `actual` uses `--color-muted-foreground`. `Bar radius` props must go to 0.
+**When to use:** Any chart using Recharts `Bar` component.
+**Example:**
+```tsx
+/* IncomeBarChart.tsx — Bar radius change */
+<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={0} />
+<Bar dataKey="actual" radius={0}>
+
+/* SpendBarChart.tsx — Bar radius change */
+<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={0} />
+<Bar dataKey="actual" radius={0}>
+```
+Note: `SpendBarChart` uses `Cell` with dynamic `var(--color-${entry.type}-fill)` — this already references fill tokens, which is correct post-rework. No ChartConfig color change needed there.
+[VERIFIED: codebase — SpendBarChart.tsx, IncomeBarChart.tsx]
+
+### Pattern 5: Spacing Upgrade Pattern
+
+**What:** Page-level spacing classes that control section separation and card internal rhythm are upgraded in-place in each page's JSX.
+**When to use:** Each of the 9 pages.
+**Mapping:**
+```
+space-y-6  → space-y-8   (section-level vertical rhythm in pages)
+gap-6      → gap-8       (grid gaps between card sections)
+gap-4      → gap-6       (inner grid element gaps where currently gap-4)
+```
+Card internal padding (`p-4` → `p-6`) applies to card content divs in pages, not to `src/components/ui/card.tsx` directly (Card already uses `py-6` and `CardContent` uses `px-6`).
+[VERIFIED: codebase — PageShell.tsx, DashboardPage.tsx, BudgetDetailPage.tsx]
+
+### Anti-Patterns to Avoid
+
+- **Editing shadcn component files for radius:** `src/components/ui/*.tsx` do NOT need edits for the radius change — the token cascade handles it. Editing them directly risks breaking shadcn's upgrade path.
+- **Changing `src/components/ui/card.tsx` padding:** `CardContent` already uses `px-6`. The `p-4 → p-6` upgrade applies to page-level wrappers that add inner padding on top of card defaults, not to the Card component itself.
+- **Adding new `rounded-none` classes broadly:** Prefer removing the hardcoded `rounded-*` class entirely over adding `rounded-none`, since `--radius: 0` already means all `rounded-md`/`rounded-sm` Tailwind classes resolve to 0px. Only add `rounded-none` if you need to explicitly reset a parent that might not be covered.
+- **Relying on `--color-chart-*` variables in new code:** These are being deleted this phase. All chart coloring must reference `--color-*-fill` tokens going forward.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| WCAG contrast calculation | Manual contrast ratio math | Use UI-SPEC.md confirmed values; verify with browser devtools color picker | OKLCH values already computed and confirmed in CONTEXT.md and UI-SPEC.md |
+| CSS-in-JS color token system | Runtime token object | Tailwind 4 `@theme inline` already does this | Single file, zero runtime cost |
+| Per-component radius reset | Adding `style={{ borderRadius: 0 }}` to every element | `--radius: 0` token | Token cascade handles all shadcn components in one edit |
+| Custom chart color mapping | Separate color registry | Existing `var(--color-*-fill)` CSS variables | Already wired in ExpenseDonutChart; standardize SpendBarChart/IncomeBarChart to match |
+
+---
+
+## Hardcoded `rounded-*` Inventory
+
+Complete list of non-token-driven rounding that requires manual removal, organized by file:
+
+### Pages
+
+| File | Line | Class | Action |
+|------|------|-------|--------|
+| CategoriesPage.tsx | 101 | `rounded-sm` (group header div) | Remove |
+| CategoriesPage.tsx | 107 | `rounded-full` (Skeleton) | Remove |
+| CategoriesPage.tsx | 108 | `rounded-md` (Skeleton) | Remove |
+| CategoriesPage.tsx | 134 | `rounded-sm` (category header) | Remove |
+| TemplatePage.tsx | 250 | `rounded-sm` (group header div) | Remove |
+| TemplatePage.tsx | 256 | `rounded-full` (Skeleton) | Remove |
+| TemplatePage.tsx | 258 | `rounded-md` (Skeleton) | Remove |
+| TemplatePage.tsx | 292 | `rounded-sm` (template item header) | Remove |
+| TemplatePage.tsx | 385 | `rounded-full` (color swatch dot) | Remove |
+| QuickAddPage.tsx | 98 | `rounded-full` (Skeleton) | Remove |
+| QuickAddPage.tsx | 100 | `rounded-md` (Skeleton) | Remove |
+| BudgetListPage.tsx | 243 | `rounded-md` (row container div) | Remove |
+| BudgetDetailPage.tsx | 290 | `rounded-sm` (skeleton header) | Remove |
+| BudgetDetailPage.tsx | 303 | `rounded-md` (Skeleton) | Remove |
+| BudgetDetailPage.tsx | 353 | `rounded-sm` (budget item header) | Remove |
+| BudgetDetailPage.tsx | 439 | `rounded-md` (summary box) | Remove |
+| BudgetDetailPage.tsx | 497 | `rounded-full` (color swatch dot) | Remove |
+
+### Components
+
+| File | Line | Class | Action |
+|------|------|-------|--------|
+| CategorySection.tsx | 73 | `rounded-md` (collapsible trigger button) | Remove |
+| DashboardSkeleton.tsx | 35,43,51 | `rounded-md` (Skeleton placeholders) | Remove |
+| DashboardSkeleton.tsx | 59 | `rounded-md` (row placeholder) | Remove |
+| DashboardSkeleton.tsx | 63,64 | `rounded-full` (Skeleton) | Remove |
+| ChartEmptyState.tsx | 12 | `rounded-lg` (empty state border) | Remove |
+| ExpenseDonutChart.tsx | 141 | `rounded-full` (legend color dot) | Remove |
+| QuickAddPicker.tsx | 156 | `rounded-sm` (picker item) | Remove |
+| QuickAddPicker.tsx | 201 | `rounded-full` (category dot) | Remove |
+
+**Note on Skeleton components:** `Skeleton` in `src/components/ui/skeleton.tsx` has `rounded-md` in its base class (`animate-pulse rounded-md bg-accent`). When `--radius: 0`, `rounded-md` resolves to 0px automatically — skeleton rounding is already handled by the token. The hardcoded `rounded-full` overrides on individual `<Skeleton>` usages (which pass `className` that overrides the base) must still be removed to avoid pill-shaped skeletons.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Skeleton `rounded-full` Overrides Persist
+
+**What goes wrong:** After `--radius: 0`, the base `Skeleton` component becomes square. But in multiple pages, Skeleton elements are given `className="h-5 w-16 rounded-full"`. Since `rounded-full` uses a fixed `border-radius: 9999px` that does not derive from `--radius`, those skeleton placeholders remain pill-shaped.
+**Why it happens:** `rounded-full` in Tailwind is always `9999px` regardless of the `--radius` token. Only `rounded-md`, `rounded-sm`, `rounded-lg`, `rounded-xl` etc. derive from `--radius`.
+**How to avoid:** Remove `rounded-full` from every `className` passed to `<Skeleton>` as listed in the inventory above.
+**Warning signs:** Pill-shaped loading placeholders visible on BudgetDetail, Template, Categories, QuickAdd pages after the token change.
+
+### Pitfall 2: Recharts `radius` Prop vs. CSS
+
+**What goes wrong:** `<Bar radius={4}>` and `<Bar radius={[4, 4, 0, 0]}>` are SVG attribute props, not CSS. Setting `--radius: 0` does not affect them. CSS overrides on `.recharts-rectangle` may also need `rx: 0; ry: 0` as SVG presentation attributes.
+**Why it happens:** Recharts renders bars as `<rect rx="4" ry="4">` SVG elements. CSS `border-radius` on SVG `rect` has browser-level quirks — some browsers respect it, others require the `rx`/`ry` attributes.
+**How to avoid:** Change the `radius` prop to `0` directly on `<Bar>` in both `SpendBarChart.tsx` and `IncomeBarChart.tsx`. This is the most reliable fix.
+**Warning signs:** Chart bars still have rounded caps after CSS override but not prop change.
+
+### Pitfall 3: Sonner Toast Radius Override Specificity
+
+**What goes wrong:** Sonner's Toaster component passes `"--border-radius": "var(--radius)"` as an inline `style` prop. After setting `--radius: 0`, this should automatically propagate. However, Sonner also has its own internal styles.
+**Why it happens:** The sonner.tsx wrapper already wires `--border-radius` to `var(--radius)`. When `--radius` becomes `0`, this should cascade automatically. The risk is Sonner's own stylesheet having higher specificity.
+**How to avoid:** Verify in browser after `--radius: 0` change. If toasts are still rounded, add `[data-sonner-toast] { border-radius: 0 !important; }` to `index.css`.
+**Warning signs:** Toast notifications still display with rounded corners after `--radius: 0` edit.
+
+### Pitfall 4: `--color-chart-*` Still Referenced After Deletion
+
+**What goes wrong:** After removing `--color-chart-1` through `--color-chart-5` from `index.css`, if any component still references them the color falls back to transparent/browser default (usually black or undefined).
+**Why it happens:** The variables are only defined in one place but could theoretically be referenced in multiple chart config objects.
+**How to avoid:** Before deleting, grep the entire `src/` directory for `color-chart` to confirm only `index.css` references them (already confirmed — zero TSX references found). Safe to delete.
+**Warning signs:** Charts render with black or missing colors.
+
+### Pitfall 5: `PageShell` `gap-6` Governs All Page Layouts
+
+**What goes wrong:** `PageShell` uses `flex flex-col gap-6`. Because it wraps most pages, the gap between the page header and first content section is controlled here. Updating spacing in individual pages but not in `PageShell` creates inconsistency.
+**Why it happens:** PageShell is a shared wrapper — spacing changes to individual pages don't affect header-to-content gap unless PageShell is also updated.
+**How to avoid:** Update `PageShell` from `gap-6` to `gap-8` as part of the spacing wave. All pages using `PageShell` benefit automatically.
+**Warning signs:** Pages with `PageShell` wrapper still show tight header-to-content gap despite page-level spacing upgrades.
+
+### Pitfall 6: Donut Chart Legend Dots Remain Circular
+
+**What goes wrong:** The custom legend in `ExpenseDonutChart.tsx` uses `<span className="inline-block size-3 shrink-0 rounded-full">` for category color dots. These remain pill/circle shaped because `rounded-full` is hardcoded.
+**Why it happens:** The legend is custom HTML, not a Recharts component — token cascade doesn't reach it.
+**How to avoid:** Remove `rounded-full` from the legend span. A square dot of 3×3px is intentionally square in the sharp design aesthetic.
+**Warning signs:** Circular color swatches in the donut chart legend after the rework.
+
+---
+
+## Code Examples
+
+### index.css Token Block (post-rework shape)
+
+```css
+/* Source: src/index.css — annotated for phase 5 changes */
+@theme inline {
+  /* UI warmth — chroma 0.005 → 0.01 */
+  --color-background: oklch(0.98 0.01 260);
+
+  /* ... other base tokens unchanged ... */
+
+  /* Category text colors — UNCHANGED (already WCAG 4.5:1) */
+  --color-income: oklch(0.55 0.17 155);
+  /* ... */
+
+  /* Category fill colors — chroma raised to 0.22+ */
+  --color-income-fill: oklch(0.72 0.22 155);
+  --color-bill-fill: oklch(0.70 0.22 25);
+  --color-variable-expense-fill: oklch(0.74 0.22 50);
+  --color-debt-fill: oklch(0.66 0.23 355);
+  --color-saving-fill: oklch(0.72 0.22 220);
+  --color-investment-fill: oklch(0.68 0.22 285);
+
+  /* --color-chart-1 through --color-chart-5: DELETED */
+
+  --radius: 0;  /* was 0.625rem */
+}
+```
+[VERIFIED: src/index.css]
+
+### SpendBarChart.tsx Post-Rework
+
+```tsx
+// Source: src/components/dashboard/charts/SpendBarChart.tsx — key changes
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-muted-foreground)" },
+} satisfies ChartConfig
+
+// Bar radius props: 4 → 0
+<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={0} />
+<Bar dataKey="actual" radius={0}>
+  {/* Cell fill already uses var(--color-${entry.type}-fill) — correct */}
+</Bar>
+```
+[VERIFIED: src/components/dashboard/charts/SpendBarChart.tsx]
+
+### IncomeBarChart.tsx Post-Rework
+
+```tsx
+// Source: src/components/dashboard/charts/IncomeBarChart.tsx — key changes
+const chartConfig = {
+  budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" },
+  actual: { label: "Actual", color: "var(--color-income-fill)" },  // unchanged — already correct
+} satisfies ChartConfig
+
+// Bar radius props: [4, 4, 0, 0] → 0
+<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={0} />
+<Bar dataKey="actual" radius={0}>
+```
+[VERIFIED: src/components/dashboard/charts/IncomeBarChart.tsx]
+
+### PageShell Spacing Upgrade
+
+```tsx
+// Source: src/components/shared/PageShell.tsx — spacing change
+// Before:
+<div className="flex flex-col gap-6">
+
+// After:
+<div className="flex flex-col gap-8">
+```
+[VERIFIED: src/components/shared/PageShell.tsx]
+
+### DashboardPage Section Spacing Upgrade
+
+```tsx
+// Source: src/pages/DashboardPage.tsx — key spacing changes
+// Before: <div className="space-y-6">
+// After:  <div className="space-y-8">
+
+// Before: <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
+// After:  <div className="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
+```
+[VERIFIED: src/pages/DashboardPage.tsx lines 186, 207]
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Separate `--color-chart-*` variables | Reference `--color-*-fill` directly | This phase | Eliminates color duplication; single source of truth per category |
+| `--radius: 0.625rem` | `--radius: 0` | This phase | All shadcn components become sharp-cornered |
+| Fill chroma 0.18-0.20 | Fill chroma 0.22+ | This phase | Visually saturated pastels that read as colorful, not grey |
+| `gap-6` / `space-y-6` sections | `gap-8` / `space-y-8` | This phase | More generous breathing room between content sections |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | Sonner toast `--border-radius: var(--radius)` inline style in sonner.tsx will propagate `--radius: 0` correctly without additional CSS override | Pitfall 3 / Pattern 2 | If wrong, toasts remain rounded; mitigation: add `[data-sonner-toast] { border-radius: 0 !important }` as CSS override |
+| A2 | CSS `rx: 0; ry: 0` on `.recharts-rectangle` overrides SVG presentation attributes cross-browser | Pitfall 2 | If wrong, bars may still show rounding in some browsers; mitigation: change `radius` prop to 0 on `<Bar>` (reliable) |
+| A3 | No `--color-chart-*` references exist in any TSX file (confirmed by grep returning zero results) | Don't Hand-Roll | LOW risk — grep confirmed no TSX references |
+
+---
+
+## Open Questions
+
+1. **Sonner version 2.x selector name for border-radius override**
+   - What we know: Sonner 2.0.7 is installed; `[data-sonner-toast]` is the conventional selector from v1/v2
+   - What's unclear: Whether v2.x changed the data attribute name on the toast wrapper
+   - Recommendation: Verify in browser devtools after `--radius: 0` change; if toasts remain rounded, inspect the DOM element for the correct attribute selector
+
+2. **`space-y-6` vs `gap-6` on TemplatePage and BudgetDetailPage**
+   - What we know: These pages use `space-y-6` for section stacking (not `gap-*` which requires flex/grid parent)
+   - What's unclear: Whether changing `space-y-6` → `space-y-8` alone is sufficient or whether the wrapping flex container also needs `gap-8`
+   - Recommendation: Apply `space-y-8` where currently `space-y-6`; apply `gap-8` where currently `gap-6` in flex/grid containers — both changes are needed depending on context
+
+---
+
+## Environment Availability
+
+Step 2.6: SKIPPED — Phase 5 is purely CSS/TSX file edits with no external dependencies, database changes, or CLI tools beyond the existing Vite dev server.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | None detected — no jest.config.*, vitest.config.*, pytest.ini found |
+| Config file | None — Wave 0 gap |
+| Quick run command | `npm run build` (TypeScript compile check) |
+| Full suite command | Manual visual pass across 9 pages in browser |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| DS-01 | No rounded corners visible anywhere | Manual (visual) | `npm run build` (compile check only) | N/A — visual |
+| DS-02 | Category fills visibly colorful, not washed out | Manual (visual) | `npm run build` | N/A — visual |
+| DS-03 | Generous whitespace, no visual crowding | Manual (visual) | `npm run build` | N/A — visual |
+
+### Sampling Rate
+
+- **Per task commit:** `npm run build` — confirms no TypeScript errors
+- **Per wave merge:** `npm run build` + manual browser check of affected pages
+- **Phase gate:** Full 9-page visual pass per the UI-SPEC checklist before `/gsd-verify-work`
+
+### Wave 0 Gaps
+
+- [ ] No unit/integration test infrastructure exists — this phase is purely visual; manual browser verification is the acceptance gate
+- [ ] Consider running `npm run lint` as a secondary automated check
+
+---
+
+## Security Domain
+
+Security enforcement: not applicable. Phase 5 introduces zero new features, endpoints, authentication flows, user input handling, or data access. No ASVS categories apply. This is a pure CSS token and spacing change.
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- `src/index.css` (codebase) — Full token inventory, current `--radius` value, all OKLCH color values, `--color-chart-*` variables
+- `src/components/ui/` (codebase) — shadcn component source confirming `rounded-*` class usage, `sonner.tsx` Toaster inline style wiring
+- `src/components/dashboard/charts/` (codebase) — Recharts `Bar` radius prop values, ChartConfig objects, Cell fill patterns
+- `src/pages/` (codebase) — All 9 pages audited for `gap-*`, `space-y-*`, `rounded-*` classes
+- `05-UI-SPEC.md` (project planning) — Confirmed post-rework color values, spacing targets, component inventory
+
+### Secondary (MEDIUM confidence)
+- Tailwind CSS 4 `@theme inline` documentation — `rounded-md` etc. derive from `--radius` token; `rounded-full` does not
+
+### Tertiary (LOW confidence — A1, A2 in assumptions log)
+- Sonner 2.x data attribute selector name (`[data-sonner-toast]`) — based on conventional usage; verify in browser
+- Recharts CSS `rx`/`ry` override cross-browser behavior — recommend prop change as primary approach
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Token edit scope (index.css): HIGH — full file read, all variables inventoried
+- Hardcoded rounded-* inventory: HIGH — exhaustive grep of src/pages + src/components
+- Spacing upgrade targets: HIGH — grep confirmed current class values in all 9 pages
+- Third-party overrides (Recharts, Sonner): MEDIUM — prop-based fix is reliable; CSS override selector needs browser verification
+- Color OKLCH values: HIGH — values provided in CONTEXT.md and UI-SPEC.md
+
+**Research date:** 2026-04-20
+**Valid until:** 2026-05-20 (stable stack — Tailwind 4, Recharts 2.15, Sonner 2.x)

.planning/phases/05-design-system-token-rework/05-UI-SPEC.md

@@ -0,0 +1,235 @@
+---
+phase: 5
+slug: design-system-token-rework
+status: draft
+shadcn_initialized: true
+preset: new-york / neutral / lucide
+created: 2026-04-20
+---
+
+# Phase 5 — UI Design Contract
+
+> Visual and interaction contract for Phase 5: Design System Token Rework.
+> Generated by gsd-ui-researcher, verified by gsd-ui-checker.
+>
+> This phase is a pure token and spacing rework — no new components, no new features.
+> Every entry in this contract describes what must be TRUE after the change, not before.
+
+---
+
+## Design System
+
+| Property | Value | Source |
+|----------|-------|--------|
+| Tool | shadcn/ui | components.json |
+| Style | new-york | components.json |
+| Preset | neutral base, cssVariables: true | components.json |
+| Component library | Radix UI (via shadcn) | components.json |
+| Icon library | lucide-react | components.json |
+| Font | Inter (--font-sans) | src/index.css |
+
+---
+
+## Spacing Scale
+
+Declared values (all multiples of 4):
+
+| Token | px Value | Tailwind Class | Usage |
+|-------|----------|----------------|-------|
+| xs | 4px | gap-1 / p-1 | Icon gaps, inline tight spacing |
+| sm | 8px | gap-2 / p-2 | Compact inline elements, badge padding |
+| md | 16px | gap-4 / p-4 | Default inline element spacing |
+| lg | 24px | gap-6 / p-6 | Card internal padding (upgraded from p-4) |
+| xl | 32px | gap-8 | Section gaps between cards and sections (upgraded from gap-6) |
+| 2xl | 48px | gap-12 | Major section breaks, page-level vertical rhythm |
+| 3xl | 64px | py-16 | Auth page vertical centering, hero areas |
+
+**Phase 5 spacing changes (from CONTEXT.md):**
+- Card internal padding: `p-4` → `p-6` across all 9 pages
+- Section gaps: `gap-4` → `gap-6`, `gap-6` → `gap-8` across all pages
+- Page header bottom margin: standardize to `mb-6` everywhere
+- Section-to-section gap: standardize to `gap-8`
+
+Exceptions: none — 8-point scale applies without exception.
+
+---
+
+## Typography
+
+| Role | Size | Tailwind | Weight | Weight Class | Line Height | Usage |
+|------|------|----------|--------|--------------|-------------|-------|
+| Caption | 12px | text-xs | 400 | font-normal | 1.5 | Subtitles, secondary metadata |
+| Body / Label | 14px | text-sm | 500 | font-medium | 1.5 | Table cells, form labels, card labels, stat subtitles |
+| Base | 16px | text-base | 500 | font-medium | 1.5 | Card titles (e.g. chart section headings) |
+| Heading | 24px | text-2xl | 600 | font-semibold | 1.2 | Page titles (PageShell h1), auth card titles, template names |
+
+Source: Existing usage in PageShell, StatCard, DashboardPage, LoginPage, RegisterPage confirmed these four sizes as the complete in-use set.
+
+Weights used: exactly 2 — `font-medium` (500) for body/data, `font-semibold` (600) for headings. The rare `font-bold` (700) occurrences in StatCard value display are reclassified as `font-semibold` for consistency.
+
+---
+
+## Color
+
+### Base UI Tokens (post-rework values)
+
+| Role | OKLCH Value | Usage |
+|------|-------------|-------|
+| Background (dominant, 60%) | oklch(0.98 0.01 260) | Page background — chroma lifted 0.005→0.01 for subtle warmth |
+| Card / Popover (secondary, 30%) | oklch(1 0 0) | Cards, modals, popovers, sidebar surface |
+| Sidebar | oklch(0.97 0.008 260) | Sidebar background — no change |
+| Primary accent (10%) | oklch(0.55 0.15 260) | Active nav items, primary buttons, focus rings |
+| Secondary / Muted | oklch(0.93 0.02 260) | Secondary buttons, muted chip backgrounds |
+| Border / Input | oklch(0.88 0.01 260) | All borders and input outlines |
+| Destructive | oklch(0.6 0.2 25) | Delete actions, error alerts only |
+
+Accent reserved for: primary action buttons, active sidebar navigation item, focus ring outlines, primary CTA buttons. No other elements may use the primary OKLCH(0.55 0.15 260) value.
+
+### Category Text Colors (WCAG 4.5:1 contrast on white — no change to lightness/chroma)
+
+| Token | OKLCH Value | Hue |
+|-------|-------------|-----|
+| --color-income | oklch(0.55 0.17 155) | Green |
+| --color-bill | oklch(0.55 0.17 25) | Orange-red |
+| --color-variable-expense | oklch(0.58 0.16 50) | Amber |
+| --color-debt | oklch(0.52 0.18 355) | Red |
+| --color-saving | oklch(0.55 0.16 220) | Blue |
+| --color-investment | oklch(0.55 0.16 285) | Violet |
+
+### Category Fill Colors (post-rework — chroma raised to 0.22+)
+
+These replace the current fill tokens (C=0.18-0.20). Exact values are at Claude's discretion per CONTEXT.md as long as chroma >= 0.22 and the fills remain visually distinct from each other.
+
+| Token | Target OKLCH | Constraint |
+|-------|--------------|------------|
+| --color-income-fill | oklch(0.72 0.22 155) | C >= 0.22, L ~0.70-0.75 |
+| --color-bill-fill | oklch(0.70 0.22 25) | C >= 0.22, L ~0.68-0.73 |
+| --color-variable-expense-fill | oklch(0.74 0.22 50) | C >= 0.22, L ~0.70-0.76 |
+| --color-debt-fill | oklch(0.66 0.23 355) | C >= 0.22, L ~0.64-0.70 |
+| --color-saving-fill | oklch(0.72 0.22 220) | C >= 0.22, L ~0.70-0.75 |
+| --color-investment-fill | oklch(0.68 0.22 285) | C >= 0.22, L ~0.65-0.72 |
+
+### Chart Colors (post-rework — aligned to fill tokens)
+
+The `--color-chart-1` through `--color-chart-5` variables are REMOVED. Chart components reference `--color-*-fill` tokens directly. This eliminates the duplicate color system.
+
+| Removed | Replaced by |
+|---------|-------------|
+| --color-chart-1 | --color-income-fill |
+| --color-chart-2 | --color-bill-fill |
+| --color-chart-3 | --color-variable-expense-fill |
+| --color-chart-4 | --color-debt-fill |
+| --color-chart-5 | --color-saving-fill |
+
+### Corner Radius
+
+| Token | Current Value | Post-Rework Value | Effect |
+|-------|--------------|-------------------|--------|
+| --radius | 0.625rem (10px) | 0rem (0px) | All shadcn components become sharp-cornered |
+
+Third-party overrides required (applied via CSS selectors in src/index.css):
+- Recharts bar elements: force `rx="0" ry="0"` or CSS `border-radius: 0`
+- Sonner toast container: override `.sonner-toast` border-radius to 0
+
+---
+
+## Copywriting Contract
+
+Phase 5 is a pure visual rework — no new user-facing copy is introduced. The following existing copy elements remain unchanged and are documented here as the confirmed contract.
+
+| Element | Copy | Notes |
+|---------|------|-------|
+| Primary CTA (Budget List) | "New Budget" | Existing — unchanged |
+| Primary CTA (Template) | "Add item" | Existing — unchanged |
+| Primary CTA (Categories) | "New Category" | Existing — unchanged |
+| Empty state (Dashboard) | Translation key: `dashboard.noBudgetForMonth` | Existing — no copy changes this phase |
+| Error state (auth forms) | Translation key: `auth.error` + specific message | Existing — no copy changes this phase |
+| Destructive actions | None introduced in this phase | Token rework only |
+
+No new destructive actions are introduced. No new confirmation dialogs. No new empty states.
+
+---
+
+## Component Inventory
+
+Components affected by token changes (no code changes required — token cascade handles it):
+
+| Component | Location | Rounding Source | Change Required |
+|-----------|----------|-----------------|-----------------|
+| Button | src/components/ui/button.tsx | --radius token | Automatic via --radius: 0 |
+| Card | src/components/ui/card.tsx | --radius token | Automatic; padding class updated to p-6 |
+| Input | src/components/ui/input.tsx | --radius token | Automatic via --radius: 0 |
+| Badge | src/components/ui/badge.tsx | --radius token | Automatic via --radius: 0 |
+| Select | src/components/ui/select.tsx | --radius token | Automatic via --radius: 0 |
+| Sheet | src/components/ui/sheet.tsx | --radius token | Automatic via --radius: 0 |
+| Dialog | src/components/ui/dialog.tsx | --radius token | Automatic via --radius: 0 |
+| Popover | src/components/ui/popover.tsx | --radius token | Automatic via --radius: 0 |
+| Sidebar | src/components/ui/sidebar.tsx | --radius token | Automatic via --radius: 0 |
+| Dropdown Menu | src/components/ui/dropdown-menu.tsx | --radius token | Automatic via --radius: 0 |
+| Recharts bars | SpendBarChart, IncomeBarChart | SVG rx/ry attrs | Explicit CSS override needed |
+| Sonner toasts | src/components/ui/sonner.tsx | Sonner inline styles | CSS selector override needed |
+| Category swatches | CategoriesPage, CategorySection | Hardcoded rounded-* | Audit and remove rounded-* classes |
+| Budget progress bars | BudgetDetailPage | Hardcoded rounded-* | Audit and remove rounded-* classes |
+
+Pages to audit for inline `rounded-*` classes (must be zero after this phase):
+1. DashboardPage — CategorySection swatches, StatCard
+2. BudgetListPage — budget item rows
+3. BudgetDetailPage — progress bars, budget row items
+4. TemplatePage — template item rows, category group headers
+5. CategoriesPage — category color swatches
+6. QuickAddPage — picker items
+7. SettingsPage — form elements
+8. LoginPage — auth card
+9. RegisterPage — auth card
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| shadcn official (new-york) | button, card, badge, input, label, select, sheet, dialog, popover, sidebar, dropdown-menu, separator, skeleton, table, tooltip, sonner, chart, collapsible | not required |
+| Third-party | none | not applicable |
+
+No third-party registries. No vetting gate required.
+
+---
+
+## Interaction Contract
+
+Phase 5 introduces no new interaction patterns. Existing interactions are preserved. The following are confirmed unchanged:
+
+- Collapsible sections: 200ms ease-out open/close animation (--animate-collapsible-open/close) — no change
+- Sidebar navigation: active state uses primary color — no change to behavior
+- Form validation: error states use `--color-destructive` — no change
+- Chart tooltips: Recharts default — style override via chart.tsx config only
+
+---
+
+## Visual Regression Checklist
+
+The executor must perform a manual visual pass after all token changes confirming:
+
+- [ ] No pill buttons visible on any of the 9 pages
+- [ ] No rounded cards visible on any of the 9 pages
+- [ ] No rounded inputs visible on any of the 9 pages
+- [ ] Category fill colors are visibly colorful against white (not grey-tinted)
+- [ ] Category text colors still appear dark/readable (not washed out by chroma increase)
+- [ ] Section gaps feel generous — no visual crowding between cards
+- [ ] Card internal padding feels spacious — content not flush against card edges
+- [ ] Page headers have consistent bottom margin before first content section
+- [ ] Recharts bars are square-ended (no rounded caps)
+- [ ] Sonner toasts have sharp corners
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

.planning/phases/05-design-system-token-rework/05-VALIDATION.md

@@ -0,0 +1,74 @@
+---
+phase: 5
+slug: design-system-token-rework
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-04-20
+---
+
+# Phase 5 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | vitest (existing) |
+| **Config file** | `vite.config.ts` |
+| **Quick run command** | `bun run build` |
+| **Full suite command** | `bun run build && bun run lint` |
+| **Estimated runtime** | ~15 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun run build`
+- **After every plan wave:** Run `bun run build && bun run lint`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 15 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 5-01-01 | 01 | 1 | DS-01 | — | N/A | build | `bun run build` | ✅ | ⬜ pending |
+| 5-01-02 | 01 | 1 | DS-02 | — | N/A | build | `bun run build` | ✅ | ⬜ pending |
+| 5-01-03 | 01 | 1 | DS-03 | — | N/A | build | `bun run build` | ✅ | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+*Existing infrastructure covers all phase requirements.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Sharp corners visible on all 9 pages | DS-01 | Visual verification — no programmatic way to confirm rendered border radius from tests | Open each page, inspect all cards/buttons/inputs for 0px radius |
+| Category colors visibly colorful against white | DS-02 | Perception-based — WCAG contrast can be calculated but "visibly colorful" is subjective | Open categories page, compare swatches against white background |
+| Layout uncluttered with consistent whitespace | DS-03 | Visual rhythm/spacing is a design judgment | Compare before/after screenshots of all 9 pages |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 15s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/05-design-system-token-rework/05-VERIFICATION.md

@@ -0,0 +1,224 @@
+---
+phase: 05-design-system-token-rework
+verified: 2026-04-20T00:00:00Z
+status: human_needed
+score: 8/8 must-haves verified
+overrides_applied: 0
+gaps:
+  - truth: "Every rounded element across all 9 pages has sharp corners — no pill buttons, no rounded cards, no rounded inputs visible anywhere in the app"
+    status: partial
+    reason: >
+      The --radius: 0 token does NOT cascade to Tailwind v4's named radius utility scale.
+      The built CSS proves --radius-md=.375rem, --radius-xl=.75rem, --radius-lg=.5rem.
+      Shadcn primitive components use these named utilities: Card uses rounded-xl (0.75rem),
+      Button uses rounded-md (0.375rem), Input uses rounded-md (0.375rem), Badge uses
+      rounded-full, Popover/Dialog/Dropdown use rounded-md/rounded-lg. These components
+      still render with non-zero border-radius in the browser. The research document
+      incorrectly assumed Tailwind v4 derives --radius-* from --radius. Hardcoded
+      rounded-* classes were correctly removed from all pages and shared non-primitive
+      components (CONFIRMED), but the underlying shadcn primitive library radius values
+      remain unchanged.
+    artifacts:
+      - path: "src/index.css"
+        issue: "--radius: 0 is set but Tailwind v4 radius utilities (rounded-md, rounded-xl, etc.) use an independent scale (--radius-md, --radius-xl) that is NOT derived from --radius. Built CSS: --radius-xl=.75rem, --radius-md=.375rem."
+      - path: "src/components/ui/card.tsx"
+        issue: "Uses rounded-xl which maps to var(--radius-xl)=0.75rem — cards are not sharp"
+      - path: "src/components/ui/button.tsx"
+        issue: "Uses rounded-md which maps to var(--radius-md)=0.375rem — buttons are not sharp"
+      - path: "src/components/ui/input.tsx"
+        issue: "Uses rounded-md which maps to var(--radius-md)=0.375rem — inputs are not sharp"
+    missing:
+      - >
+        Add explicit --radius-* overrides to src/index.css @theme inline block to
+        zero-out the Tailwind v4 radius scale:
+          --radius-xs: 0;
+          --radius-sm: 0;
+          --radius-md: 0;
+          --radius-lg: 0;
+          --radius-xl: 0;
+          --radius-2xl: 0;
+          --radius-3xl: 0;
+        This will make all Tailwind rounded-* utilities resolve to 0, completing the
+        cascade that --radius: 0 alone cannot achieve in Tailwind v4.
+human_verification:
+  - test: "Open each of the 9 pages and visually inspect for sharp corners on Cards, Buttons, Inputs, Badges, Selects, Dialogs, Popovers, and Dropdown Menus"
+    expected: "All elements have 0px border-radius (perfectly square corners) — no rounded cards, no rounded buttons, no rounded inputs anywhere"
+    why_human: "Rendered border-radius depends on --radius-* CSS var resolution which can only be confirmed visually in a browser or with computed style inspection. The gap analysis above predicts rounded corners on shadcn primitives but visual confirmation is required."
+  - test: "Open the Categories page and compare category color swatches against the white page background"
+    expected: "Swatches are visibly colorful (green income, orange/red bill, etc.) — not grey-tinted or washed out"
+    why_human: "Color vividness is a perceptual judgment. OKLCH chroma values (0.22-0.23) can be verified programmatically (CONFIRMED) but 'visibly colorful' perception requires human judgment."
+  - test: "Open the Dashboard page and confirm chart bars have square ends"
+    expected: "No rounded caps on bars in SpendBarChart or IncomeBarChart — bars terminate in 90-degree corners"
+    why_human: "CSS rx/ry override and radius={0} prop are both set, but Recharts SVG rendering behavior in the browser must be visually confirmed."
+  - test: "Navigate through all 9 pages and assess whitespace rhythm"
+    expected: "Section gaps feel spacious, card padding feels generous, no visual crowding between sections or cards"
+    why_human: "Spacing is a design judgment — gap-8 and space-y-8 values are confirmed in code but whether they achieve the 'generous whitespace' goal is subjective."
+---
+
+# Phase 5: Design System Token Rework — Verification Report
+
+**Phase Goal:** Users see a sharp, minimal, clearly pastel UI across every page — the visual foundation that all subsequent phases build on
+**Verified:** 2026-04-20
+**Status:** HUMAN NEEDED (code gap fixed — awaiting visual confirmation)
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths (Roadmap Success Criteria)
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|---------|
+| SC-1 | Every rounded element across all 9 pages has sharp corners — no pill buttons, no rounded cards, no rounded inputs | PARTIAL | Hardcoded rounded-* removed from all pages/shared components (CONFIRMED), but shadcn primitives (Card/Button/Input) use Tailwind v4 named radius utilities that resolve to non-zero values in built CSS (--radius-md=.375rem, --radius-xl=.75rem) |
+| SC-2 | Category color swatches visibly colorful against white, still pass WCAG 4.5:1 | ? NEEDS HUMAN | All 6 fill vars raised to chroma 0.22-0.23 (CONFIRMED in index.css), WCAG text contrast vars separate and unchanged; visual confirmation needed |
+| SC-3 | Page layouts feel uncluttered — consistent whitespace gaps, no visual crowding | ? NEEDS HUMAN | gap-8/space-y-8 implemented across all pages (CONFIRMED); subjective design judgment requires human |
+| SC-4 | Full visual pass of all 9 pages confirms no regressions from token changes | ? NEEDS HUMAN | Build passes (CONFIRMED); visual pass cannot be automated |
+
+**Verified:** 0/4 roadmap SCs fully verified (3 need human, 1 has a code gap)
+
+### Plan Must-Haves (All Plans Combined)
+
+| # | Must-Have | Status | Evidence |
+|---|-----------|--------|---------|
+| 1 | `--radius: 0` in index.css, cascading sharp corners to all shadcn components | PARTIAL | `--radius: 0` confirmed in index.css; cascade does NOT reach shadcn primitives via Tailwind v4's named radius utilities |
+| 2 | Category fill chromas >= 0.22 | VERIFIED | income: 0.22, bill: 0.22, variable-expense: 0.22, debt: 0.23, saving: 0.22, investment: 0.22 |
+| 3 | `--color-chart-*` variables deleted from index.css | VERIFIED | Zero matches for `color-chart-[1-5]` in entire src/ directory |
+| 4 | Chart bars render with radius={0} (no rounded caps) | VERIFIED | SpendBarChart: 2x radius={0}; IncomeBarChart: 2x radius={0} |
+| 5 | CSS overrides for Recharts rectangles and Sonner toasts | VERIFIED | `.recharts-rectangle { rx: 0; ry: 0 }` and `[data-sonner-toast] { border-radius: 0 !important }` in index.css |
+| 6 | PageShell gap is gap-8 | VERIFIED | Line 15 of PageShell.tsx: `"flex flex-col gap-8"` |
+| 7 | All shared component hardcoded rounded-* removed | VERIFIED | DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker all clean |
+| 8 | All 9 pages have no hardcoded rounded-* classes remaining | VERIFIED | grep -rn on src/pages/ returns NO matches |
+
+**Plan score:** 7/8 must-haves fully verified (1 partial on cascading)
+
+---
+
+## Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/index.css` | Token source with --radius: 0, raised fill chromas, removed chart vars, overrides | VERIFIED | All token values confirmed correct |
+| `src/components/dashboard/charts/SpendBarChart.tsx` | Sharp bars with radius={0} | VERIFIED | 2 matches for radius={0}, no radius={4} |
+| `src/components/dashboard/charts/IncomeBarChart.tsx` | Sharp bars with radius={0} | VERIFIED | 2 matches for radius={0}, no radius=[4,4,0,0] |
+| `src/components/dashboard/charts/ExpenseDonutChart.tsx` | Square legend dots (no rounded-full) | VERIFIED | `inline-block size-3 shrink-0` at line 141 |
+| `src/components/shared/PageShell.tsx` | gap-8 section spacing | VERIFIED | `flex flex-col gap-8` at line 15 |
+| `src/components/dashboard/DashboardSkeleton.tsx` | Sharp skeletons, upgraded spacing | VERIFIED | No rounded classes; gap-8 outer and chart grid |
+| `src/components/dashboard/CategorySection.tsx` | No rounded-md on trigger | VERIFIED | `flex items-center gap-3 border-l-4 bg-card px-4 py-3` |
+| `src/components/dashboard/charts/ChartEmptyState.tsx` | No rounded-lg | VERIFIED | Dashed border container has no rounded class |
+| `src/components/QuickAddPicker.tsx` | No rounded-sm or rounded-full | VERIFIED | Zero matches |
+| `src/pages/DashboardPage.tsx` | space-y-8 and gap-8 | VERIFIED | Lines 186 and 207 |
+| `src/pages/BudgetListPage.tsx` | No rounded-md on row containers | VERIFIED | Row div: `flex items-center gap-3 border p-3` |
+| `src/pages/BudgetDetailPage.tsx` | No rounded-sm/md/full | VERIFIED | Zero matches in src/pages/ sweep |
+| `src/pages/TemplatePage.tsx` | No rounded-sm/full, upgraded spacing | VERIFIED | Zero matches; gap-8 and space-y-8 confirmed |
+| `src/pages/CategoriesPage.tsx` | No rounded-sm/full, upgraded spacing | VERIFIED | Zero matches; space-y-8 confirmed |
+| `src/pages/QuickAddPage.tsx` | No rounded-full/md | VERIFIED | Zero matches |
+| `src/pages/SettingsPage.tsx` | space-y-6 in CardContent | VERIFIED | Both CardContent instances at lines 69 and 87 |
+| `src/pages/LoginPage.tsx` | No rounded classes (token cascade) | VERIFIED | No hardcoded rounded-* |
+| `src/pages/RegisterPage.tsx` | No rounded classes (token cascade) | VERIFIED | No hardcoded rounded-* |
+
+---
+
+## Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|-----|-----|--------|---------|
+| `src/index.css` | All shadcn primitives (Card, Button, Input, etc.) | `--radius: 0` token cascade through Tailwind v4 named utilities | BROKEN | Built CSS: rounded-xl=var(--radius-xl)=0.75rem; --radius: 0 does not override --radius-xl in Tailwind v4's default scale |
+| `src/index.css` | App components (pages, shared components) | Hardcoded rounded-* class removal + --radius: 0 | PARTIAL | All hardcoded classes removed (VERIFIED); but underlying shadcn primitives still apply radius via utility scale |
+| `src/index.css` | Chart components | `--color-*-fill` CSS variables | WIRED | Charts use `var(--color-${entry.type}-fill)` which maps to the updated tokens |
+| `src/index.css` | Recharts SVG | `.recharts-rectangle { rx: 0; ry: 0 }` | WIRED | Override present in index.css; included in built CSS |
+| `src/index.css` | Sonner toasts | `[data-sonner-toast] { border-radius: 0 !important }` | WIRED | Override present; confirmed in built CSS |
+
+---
+
+## Data-Flow Trace (Level 4)
+
+Not applicable — this phase modifies CSS tokens and JSX class strings only. No dynamic data rendering introduced.
+
+---
+
+## Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| Build passes cleanly | `bun run build` | Exit 0 in 460ms | PASS |
+| No rounded-* in pages | `grep -rn "rounded-full\|rounded-sm\|rounded-md\|rounded-lg" src/pages/` | No matches | PASS |
+| No rounded-* in modified shared components | grep across dashboard/, shared/, QuickAddPicker.tsx | No matches | PASS |
+| `--radius: 0` in index.css | `grep -n "\-\-radius" src/index.css` | Line 65: `--radius: 0;` | PASS |
+| Fill chroma >= 0.22 | `grep "\-\-color-.*-fill" src/index.css` | All 6 vars: 0.22-0.23 | PASS |
+| No color-chart-* vars in src/ | `grep -rn "color-chart" src/` | No matches | PASS |
+| Chart radius={0} | `grep "radius" SpendBarChart.tsx IncomeBarChart.tsx` | 2 matches each, all radius={0} | PASS |
+| Built CSS radius scale | `grep radius-md dist/assets/*.css` | --radius-md:0 | PASS — fixed by adding explicit --radius-* tokens |
+| Commits exist | `git log --oneline` | 99b5b5f, 4c74dec, e8f13c9, e7282fa, 00670af all present | PASS |
+
+---
+
+## Requirements Coverage
+
+| Requirement | Plans | Description | Status | Evidence |
+|-------------|-------|-------------|--------|---------|
+| DS-01 | 05-01, 05-02, 05-03 | User sees sharp-edged UI across all pages (no rounded corners) | PARTIAL | Hardcoded rounded-* removed from all pages and app-layer components; shadcn primitives still use Tailwind v4 named radius utilities that resolve to non-zero values |
+| DS-02 | 05-01, 05-03 | User sees clear pastel colors that are visibly colorful, not washed out | NEEDS HUMAN | Fill chroma values raised to 0.22-0.23 (code confirmed); visual perception of color vividness requires human confirmation |
+| DS-03 | 05-02, 05-03 | User sees clean, minimal layout with generous whitespace | NEEDS HUMAN | gap-8/space-y-8 spacing values confirmed in all pages; whether this reads as "generous whitespace" requires human design judgment |
+
+---
+
+## Anti-Patterns Found
+
+| File | Pattern | Severity | Impact |
+|------|---------|----------|--------|
+| `src/index.css` | `--radius: 0` assumed to cascade to Tailwind v4 named radius utilities, but built CSS proves --radius-md=.375rem | BLOCKER | shadcn Cards, Buttons, Inputs remain rounded despite the token change |
+| `05-RESEARCH.md` | Research document incorrectly states "rounded-* utilities derive from --radius" in Tailwind v4 | INFO | Root cause of the gap; no direct code impact, but planning assumption was wrong |
+
+---
+
+## Human Verification Required
+
+### 1. Sharp Corners on Shadcn Primitives
+
+**Test:** Open the app (`bun run dev`), then inspect Cards (on Dashboard, Budget List, Login), Buttons (all pages), and Inputs (Settings, Login, Register) using browser DevTools (Computed styles → border-radius).
+**Expected:** border-radius = 0px on all elements
+**Why human:** Browser DevTools can confirm the actual computed border-radius. The code gap analysis predicts non-zero radius on shadcn primitives (Card=0.75rem, Button/Input=0.375rem), but runtime behavior must be confirmed visually and via DevTools to be certain.
+
+### 2. Category Color Vividness (DS-02)
+
+**Test:** Open the Categories page and the Dashboard category sections. Compare category color swatches against the white page background.
+**Expected:** Swatches are clearly, distinctly colorful — income green is vivid, bill orange/red is vivid, etc. None appear grey-tinted or washed out.
+**Why human:** Color vividness (chroma 0.22-0.23 OKLCH) is a perceptual judgment. The token values are confirmed correct but whether they achieve "clearly pastel" vs "washed out" requires human perception.
+
+### 3. Bar Chart Square Ends (DS-01 partial)
+
+**Test:** Open the Dashboard and observe the SpendBarChart and IncomeBarChart. Look at the tops of the bars.
+**Expected:** Bar tops terminate in 90-degree corners — no visible rounded caps. The `.recharts-rectangle` CSS override and `radius={0}` prop are both in place.
+**Why human:** Recharts SVG rendering of the CSS `rx`/`ry` override needs visual confirmation in a browser.
+
+### 4. Whitespace and Layout Rhythm (DS-03)
+
+**Test:** Navigate through all 9 pages — Dashboard, Budget List, Budget Detail, Template, Categories, Quick Add, Settings, Login, Register.
+**Expected:** Section gaps feel spacious and uncluttered. Content is readable without feeling cramped. Page headers have consistent spacing before first content section.
+**Why human:** Whether gap-8 and space-y-8 achieve "generous whitespace" and a "clean, minimal layout" is a design judgment that cannot be verified programmatically.
+
+---
+
+## Gaps Summary
+
+**1 code gap blocking full goal achievement:**
+
+The `--radius: 0` token in `src/index.css` was correctly set, and the research/plan correctly identified that this should cascade to all shadcn UI components. However, Tailwind v4's named radius utility scale (`--radius-md`, `--radius-xl`, etc.) is an **independent scale** that is NOT derived from `--radius`. The built CSS confirms `--radius-md: .375rem` and `--radius-xl: .75rem` remain at their Tailwind defaults.
+
+All shadcn primitive components use these named utilities:
+- `Card` → `rounded-xl` → `var(--radius-xl)` = **0.75rem** (not sharp)
+- `Button` → `rounded-md` → `var(--radius-md)` = **0.375rem** (not sharp)
+- `Input` → `rounded-md` → `var(--radius-md)` = **0.375rem** (not sharp)
+- `Badge` → `rounded-full` → **3.4e38px** (pill-shaped — not sharp)
+- `Select` → `rounded-md` → **0.375rem** (not sharp)
+- `Dialog`/`Sheet`/`Popover` → `rounded-md`/`rounded-lg` → non-zero (not sharp)
+
+The fix is a one-line addition to the `@theme inline` block in `src/index.css` — explicitly set all radius scale variables to 0 alongside `--radius: 0`.
+
+All other must-haves are fully verified. The spacing upgrades, fill color chromas, chart var removal, chart Bar radius, Recharts/Sonner CSS overrides, and hardcoded rounded-* removal from all pages and shared components are all correctly implemented and confirmed in the actual codebase.
+
+---
+
+_Verified: 2026-04-20_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-01-PLAN.md

@@ -0,0 +1,256 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - supabase/migrations/006_uniqueness_constraints.sql
+  - supabase/migrations/007_setup_completed.sql
+  - src/lib/types.ts
+autonomous: true
+requirements:
+  - AUTO-01
+  - AUTO-03
+  - SETUP-01
+
+must_haves:
+  truths:
+    - "Migration 006 adds a unique constraint on budgets(user_id, start_date) with safe deduplication"
+    - "Migration 006 adds a unique constraint on categories(user_id, name) with safe deduplication"
+    - "Migration 007 adds setup_completed boolean NOT NULL DEFAULT false to profiles"
+    - "Migration 007 backfills setup_completed = true for all users with existing categories"
+    - "Profile TypeScript interface includes setup_completed: boolean"
+  artifacts:
+    - path: "supabase/migrations/006_uniqueness_constraints.sql"
+      provides: "Atomic deduplication + unique constraint DDL for budgets and categories"
+    - path: "supabase/migrations/007_setup_completed.sql"
+      provides: "ALTER TABLE profiles ADD COLUMN setup_completed + backfill UPDATE"
+    - path: "src/lib/types.ts"
+      provides: "Updated Profile interface with setup_completed field"
+      contains: "setup_completed: boolean"
+  key_links:
+    - from: "supabase/migrations/007_setup_completed.sql"
+      to: "profiles table"
+      via: "ALTER TABLE profiles ADD COLUMN"
+      pattern: "setup_completed boolean NOT NULL DEFAULT false"
+    - from: "src/lib/types.ts"
+      to: "Profile interface"
+      via: "TypeScript field"
+      pattern: "setup_completed: boolean"
+---
+
+<objective>
+Write two Supabase migration files and update the Profile TypeScript type.
+
+Migration 006 makes duplicate budget/category creation impossible at the DB level by first deduplicating any existing rows then adding UNIQUE constraints. Migration 007 adds the `setup_completed` boolean column to `profiles` and backfills existing users who have categories to `true`. The TypeScript `Profile` interface in `src/lib/types.ts` is updated to include `setup_completed: boolean`.
+
+Purpose: The DB layer must enforce uniqueness atomically (prevents race conditions) and must know which users have already completed setup (prevents existing v1.0 users from seeing the wizard on first v2.0 login).
+Output: 2 `.sql` migration files + 1 updated TypeScript type file.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md
+
+<interfaces>
+<!-- Existing migration chain: 001-005. New files must be named 006_... and 007_... for correct lexicographic ordering. -->
+
+From supabase/migrations/001_profiles.sql — profiles table columns:
+  id, display_name, locale, currency, created_at, updated_at
+  (NO setup_completed yet)
+
+From supabase/migrations/002_categories.sql — categories table:
+  id, user_id, name, type, icon, sort_order, created_at, updated_at
+  Existing index: categories_user_id_idx
+  (NO unique constraint on (user_id, name) yet)
+
+From supabase/migrations/004_budgets.sql — budgets table:
+  id, user_id, start_date, end_date, currency, carryover_amount, created_at, updated_at
+  Existing index: budgets_user_id_idx
+  (NO unique constraint on (user_id, start_date) yet)
+
+From src/lib/types.ts — Profile interface (before this plan):
+  export interface Profile {
+    id: string
+    display_name: string | null
+    locale: string
+    currency: string
+    created_at: string
+    updated_at: string
+  }
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Write migration 006 — uniqueness constraints with safe deduplication</name>
+  <files>supabase/migrations/006_uniqueness_constraints.sql</files>
+  <read_first>
+    - supabase/migrations/002_categories.sql
+    - supabase/migrations/004_budgets.sql
+    - .planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md (Pattern 1: Safe Deduplication)
+  </read_first>
+  <action>
+Create `supabase/migrations/006_uniqueness_constraints.sql` with this exact content — a single transaction that deduplicates then constrains:
+
+```sql
+-- Migration 006: Add uniqueness constraints to budgets and categories
+-- Safe deduplication runs first inside the transaction before each constraint.
+
+BEGIN;
+
+-- Deduplicate budgets: keep the oldest row per (user_id, start_date)
+DELETE FROM budgets
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, start_date) id
+  FROM budgets
+  ORDER BY user_id, start_date, created_at ASC
+);
+
+ALTER TABLE budgets
+  ADD CONSTRAINT budgets_user_month_unique UNIQUE (user_id, start_date);
+
+-- Deduplicate categories: keep the oldest row per (user_id, name)
+DELETE FROM categories
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, name) id
+  FROM categories
+  ORDER BY user_id, name, created_at ASC
+);
+
+ALTER TABLE categories
+  ADD CONSTRAINT categories_user_name_unique UNIQUE (user_id, name);
+
+COMMIT;
+```
+
+Key: DISTINCT ON requires ORDER BY on the same leading columns — already satisfied above. Wrapping both operations in a single transaction means if constraint ADD fails, cleanup rolls back too.
+  </action>
+  <verify>
+    <automated>grep -c "ADD CONSTRAINT" supabase/migrations/006_uniqueness_constraints.sql && grep -c "BEGIN" supabase/migrations/006_uniqueness_constraints.sql && grep -c "COMMIT" supabase/migrations/006_uniqueness_constraints.sql</automated>
+  </verify>
+  <done>File exists. Contains exactly 2 ADD CONSTRAINT statements, 1 BEGIN, 1 COMMIT. Both constraints named: budgets_user_month_unique and categories_user_name_unique.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Write migration 007 — setup_completed column + backfill</name>
+  <files>supabase/migrations/007_setup_completed.sql</files>
+  <read_first>
+    - supabase/migrations/001_profiles.sql
+    - .planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md (Pattern 2: ADD COLUMN with Default + Backfill, Pitfall 3)
+  </read_first>
+  <action>
+Create `supabase/migrations/007_setup_completed.sql` with this exact content:
+
+```sql
+-- Migration 007: Add setup_completed to profiles
+-- New signups default to false (not set up).
+-- Existing users who have any categories are backfilled to true (already set up).
+-- Wider backfill also includes users with template items to protect against
+-- edge case where user created template items but skipped category creation.
+
+ALTER TABLE profiles
+  ADD COLUMN setup_completed boolean NOT NULL DEFAULT false;
+
+-- Backfill: users with categories OR template items are considered set up
+UPDATE profiles
+SET setup_completed = true
+WHERE id IN (
+  SELECT DISTINCT user_id FROM categories
+  UNION
+  SELECT t.user_id FROM templates t
+  INNER JOIN template_items ti ON ti.template_id = t.id
+);
+```
+
+Note: The wider backfill UNION (categories OR template items) matches Pitfall 3 guidance from RESEARCH.md — protects v1.0 users who may have template items but no categories.
+  </action>
+  <verify>
+    <automated>grep -c "ADD COLUMN setup_completed" supabase/migrations/007_setup_completed.sql && grep -c "UPDATE profiles" supabase/migrations/007_setup_completed.sql</automated>
+  </verify>
+  <done>File exists. Contains ADD COLUMN statement with `boolean NOT NULL DEFAULT false` and UPDATE statement with UNION backfill covering both categories and template_items.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update Profile TypeScript interface to include setup_completed</name>
+  <files>src/lib/types.ts</files>
+  <read_first>
+    - src/lib/types.ts
+  </read_first>
+  <action>
+In `src/lib/types.ts`, add `setup_completed: boolean` to the `Profile` interface. The field goes after `currency` and before `created_at`:
+
+```typescript
+export interface Profile {
+  id: string
+  display_name: string | null
+  locale: string
+  currency: string
+  setup_completed: boolean   // <-- ADD THIS LINE
+  created_at: string
+  updated_at: string
+}
+```
+
+No other changes to types.ts.
+  </action>
+  <verify>
+    <automated>grep -n "setup_completed: boolean" src/lib/types.ts</automated>
+  </verify>
+  <done>`src/lib/types.ts` contains `setup_completed: boolean` inside the Profile interface. `tsc --noEmit` passes with no new errors.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Migration SQL → Supabase DB | DDL runs with superuser privileges via Supabase CLI — only run locally or in controlled CI |
+| Client → profiles RLS | Client can UPDATE own profile row including setup_completed — acceptable since it's a UX flag, not a security gate |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-06-01 | Tampering | budgets table — duplicate row creation via concurrent requests | mitigate | UNIQUE constraint on (user_id, start_date) enforced at DB level; second INSERT returns PostgREST error 23505 |
+| T-06-02 | Tampering | categories table — duplicate name creation | mitigate | UNIQUE constraint on (user_id, name) enforced at DB level; second INSERT returns PostgREST error 23505 |
+| T-06-03 | Elevation of privilege | profiles.setup_completed — client sets own flag to false to force wizard re-display | accept | setup_completed is a UX routing flag only; no data is gated behind it; RLS allows own-row update |
+</threat_model>
+
+<verification>
+After all 3 tasks complete:
+
+```bash
+# Confirm both migration files exist
+ls supabase/migrations/006_uniqueness_constraints.sql supabase/migrations/007_setup_completed.sql
+
+# Confirm TypeScript type updated
+grep "setup_completed: boolean" src/lib/types.ts
+
+# Confirm TypeScript compiles cleanly
+npx tsc --noEmit
+```
+</verification>
+
+<success_criteria>
+- `supabase/migrations/006_uniqueness_constraints.sql` exists, contains BEGIN/COMMIT, two DISTINCT ON dedup DELETEs, two ADD CONSTRAINT statements
+- `supabase/migrations/007_setup_completed.sql` exists, adds column with `boolean NOT NULL DEFAULT false`, backfills with UNION covering categories and template_items
+- `src/lib/types.ts` Profile interface has `setup_completed: boolean`
+- `tsc --noEmit` passes with no errors
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-01-SUMMARY.md`
+</output>

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-01-SUMMARY.md

@@ -0,0 +1,75 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+plan: "01"
+subsystem: database
+tags: [migrations, schema, typescript, constraints, first-run]
+dependency_graph:
+  requires: []
+  provides: [uniqueness-constraints, setup_completed-column, profile-type-update]
+  affects: [profiles, budgets, categories]
+tech_stack:
+  added: []
+  patterns: [safe-deduplication-before-unique-constraint, alter-table-with-backfill]
+key_files:
+  created:
+    - supabase/migrations/006_uniqueness_constraints.sql
+    - supabase/migrations/007_setup_completed.sql
+  modified:
+    - src/lib/types.ts
+decisions:
+  - "Used wider UNION backfill in 007 (categories OR template_items) per Pitfall 3 guidance — protects v1.0 users with templates but no categories"
+  - "Migration 006 wraps deduplication DELETE and ADD CONSTRAINT in single BEGIN/COMMIT for atomicity"
+metrics:
+  duration: "4 minutes"
+  completed: "2026-04-20"
+  tasks_completed: 3
+  tasks_total: 3
+---
+
+# Phase 06 Plan 01: DB Safety Constraints and First-Run Flag Summary
+
+**One-liner:** Two atomic SQL migrations adding UNIQUE constraints on budgets/categories with safe deduplication, plus a `setup_completed` boolean on profiles with UNION backfill, synced to the TypeScript Profile interface.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Migration 006: uniqueness constraints | 23fd3fa | supabase/migrations/006_uniqueness_constraints.sql |
+| 2 | Migration 007: setup_completed column + backfill | 0f441b6 | supabase/migrations/007_setup_completed.sql |
+| 3 | Update Profile TypeScript interface | 39840ca | src/lib/types.ts |
+
+## What Was Built
+
+**Migration 006** (`006_uniqueness_constraints.sql`): A single `BEGIN/COMMIT` transaction that:
+1. DELETEs duplicate budgets keeping the oldest per `(user_id, start_date)` using `DISTINCT ON`
+2. ADDs `CONSTRAINT budgets_user_month_unique UNIQUE (user_id, start_date)`
+3. DELETEs duplicate categories keeping the oldest per `(user_id, name)` using `DISTINCT ON`
+4. ADDs `CONSTRAINT categories_user_name_unique UNIQUE (user_id, name)`
+
+**Migration 007** (`007_setup_completed.sql`): Two statements:
+1. `ALTER TABLE profiles ADD COLUMN setup_completed boolean NOT NULL DEFAULT false`
+2. `UPDATE profiles SET setup_completed = true WHERE id IN (SELECT DISTINCT user_id FROM categories UNION SELECT t.user_id FROM templates t INNER JOIN template_items ti ON ti.template_id = t.id)`
+
+**TypeScript** (`src/lib/types.ts`): Added `setup_completed: boolean` to the `Profile` interface between `currency` and `created_at`. `tsc --noEmit` passes cleanly.
+
+## Deviations from Plan
+
+None — plan executed exactly as written. The UNION backfill in migration 007 was specified in the plan (per Pitfall 3 guidance from RESEARCH.md).
+
+## Known Stubs
+
+None — this plan produces SQL DDL and a TypeScript type update; no UI or data-flow stubs.
+
+## Threat Flags
+
+No new threat surface beyond what was documented in the plan's threat model. The UNIQUE constraints directly address T-06-01 and T-06-02. The `setup_completed` column is a UX routing flag with existing RLS (T-06-03 accepted).
+
+## Self-Check
+
+- [x] `supabase/migrations/006_uniqueness_constraints.sql` exists — FOUND
+- [x] `supabase/migrations/007_setup_completed.sql` exists — FOUND
+- [x] `src/lib/types.ts` contains `setup_completed: boolean` — FOUND (line 16)
+- [x] `tsc --noEmit` passed with no errors
+- [x] Commits 23fd3fa, 0f441b6, 39840ca exist in git log
+
+## Self-Check: PASSED

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-02-PLAN.md

@@ -0,0 +1,283 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/data/presets.ts
+  - src/i18n/en.json
+  - src/i18n/de.json
+autonomous: true
+requirements:
+  - SETUP-02
+
+must_haves:
+  truths:
+    - "src/data/presets.ts exports a PRESETS array of exactly 19 typed items"
+    - "PRESETS covers all 6 category types with the agreed distribution (4+4+5+2+2+2)"
+    - "Every preset item has a slug, type (valid CategoryType), defaultAmount (round number EUR), and item_tier (fixed or variable)"
+    - "en.json has a top-level presets key with all 19 slugs translated to English"
+    - "de.json has a top-level presets key with all 19 slugs translated to German"
+  artifacts:
+    - path: "src/data/presets.ts"
+      provides: "PresetItem interface and PRESETS array"
+      exports: ["PresetItem", "PRESETS"]
+    - path: "src/i18n/en.json"
+      provides: "English preset translations under presets.* key"
+      contains: "presets"
+    - path: "src/i18n/de.json"
+      provides: "German preset translations under presets.* key"
+      contains: "presets"
+  key_links:
+    - from: "src/data/presets.ts"
+      to: "src/lib/types.ts"
+      via: "import CategoryType"
+      pattern: "import.*CategoryType.*from.*types"
+    - from: "src/i18n/en.json"
+      to: "presets.{type}.{slug}"
+      via: "react-i18next t() dot-path"
+      pattern: "\"presets\":"
+---
+
+<objective>
+Create the static preset budget item library and its i18n translations.
+
+`src/data/presets.ts` exports `PresetItem` interface and `PRESETS` array with 19 items across 6 category types (4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment). Both `src/i18n/en.json` and `src/i18n/de.json` get a new top-level `"presets"` key containing all 19 English/German display names.
+
+Purpose: This is the curated item library the Phase 7 wizard shows to new users for one-click budget template setup. All amounts are plain EUR numbers — the wizard reads currency from `profiles.currency`, not from this file.
+Output: `src/data/presets.ts`, updated `en.json`, updated `de.json`.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md
+
+<interfaces>
+From src/lib/types.ts:
+```typescript
+export type CategoryType =
+  | "income"
+  | "bill"
+  | "variable_expense"
+  | "debt"
+  | "saving"
+  | "investment"
+
+export type ItemTier = "fixed" | "variable" | "one_off"
+```
+
+From src/i18n/en.json — existing top-level structure (add "presets" alongside these):
+  "app", "nav", "auth", "categories", "template", "budget", "settings", "common"
+  i18n library: react-i18next — uses t('dot.path.key') syntax confirmed.
+
+NOTE: Do NOT hardcode currency symbols in preset display names or amounts.
+Amounts are plain numbers (EUR value). The wizard (Phase 7) will format them.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create src/data/presets.ts — 19-item preset library</name>
+  <files>src/data/presets.ts</files>
+  <read_first>
+    - src/lib/types.ts
+    - .planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md (Pattern 4: Preset Data File Shape)
+  </read_first>
+  <action>
+Create `src/data/presets.ts`. The file must NOT import from Supabase or React — it is a pure static data module.
+
+```typescript
+import type { CategoryType } from "@/lib/types"
+
+export interface PresetItem {
+  slug: string
+  type: CategoryType
+  defaultAmount: number  // EUR, round number — do NOT suffix with currency symbol
+  item_tier: "fixed" | "variable"
+}
+
+export const PRESETS: PresetItem[] = [
+  // income (4)
+  { slug: "salary",         type: "income",           defaultAmount: 3000, item_tier: "fixed"    },
+  { slug: "freelance",      type: "income",           defaultAmount: 500,  item_tier: "variable" },
+  { slug: "rental_income",  type: "income",           defaultAmount: 800,  item_tier: "fixed"    },
+  { slug: "other_income",   type: "income",           defaultAmount: 200,  item_tier: "variable" },
+  // bill (4)
+  { slug: "rent",           type: "bill",             defaultAmount: 1000, item_tier: "fixed"    },
+  { slug: "electricity",    type: "bill",             defaultAmount: 80,   item_tier: "fixed"    },
+  { slug: "internet",       type: "bill",             defaultAmount: 40,   item_tier: "fixed"    },
+  { slug: "phone",          type: "bill",             defaultAmount: 30,   item_tier: "fixed"    },
+  // variable_expense (5)
+  { slug: "groceries",      type: "variable_expense", defaultAmount: 400,  item_tier: "variable" },
+  { slug: "transport",      type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  { slug: "dining_out",     type: "variable_expense", defaultAmount: 150,  item_tier: "variable" },
+  { slug: "health",         type: "variable_expense", defaultAmount: 50,   item_tier: "variable" },
+  { slug: "clothing",       type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  // debt (2)
+  { slug: "loan_repayment", type: "debt",             defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "credit_card",    type: "debt",             defaultAmount: 100,  item_tier: "fixed"    },
+  // saving (2)
+  { slug: "emergency_fund", type: "saving",           defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "vacation",       type: "saving",           defaultAmount: 100,  item_tier: "fixed"    },
+  // investment (2)
+  { slug: "etf",            type: "investment",       defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "pension",        type: "investment",       defaultAmount: 100,  item_tier: "fixed"    },
+]
+```
+
+The `item_tier` for all items must be either `"fixed"` or `"variable"` — never `"one_off"` (which is excluded from template_items by the DB check constraint).
+  </action>
+  <verify>
+    <automated>grep -c "slug:" src/data/presets.ts</automated>
+  </verify>
+  <done>File exists. Contains exactly 19 objects (grep -c "slug:" returns 19). All `type` values are valid CategoryType strings. No `item_tier: "one_off"` present. `tsc --noEmit` passes.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add preset translations to en.json and de.json</name>
+  <files>src/i18n/en.json, src/i18n/de.json</files>
+  <read_first>
+    - src/i18n/en.json
+    - src/i18n/de.json
+  </read_first>
+  <action>
+Add a top-level `"presets"` key to both i18n files. The key structure is `presets.{category_type}.{slug}` — matching the `type` and `slug` fields in PRESETS.
+
+For `src/i18n/en.json`, add after the last existing top-level key:
+```json
+"presets": {
+  "income": {
+    "salary": "Salary",
+    "freelance": "Freelance Income",
+    "rental_income": "Rental Income",
+    "other_income": "Other Income"
+  },
+  "bill": {
+    "rent": "Rent",
+    "electricity": "Electricity",
+    "internet": "Internet",
+    "phone": "Phone"
+  },
+  "variable_expense": {
+    "groceries": "Groceries",
+    "transport": "Transport",
+    "dining_out": "Dining Out",
+    "health": "Health & Pharmacy",
+    "clothing": "Clothing"
+  },
+  "debt": {
+    "loan_repayment": "Loan Repayment",
+    "credit_card": "Credit Card"
+  },
+  "saving": {
+    "emergency_fund": "Emergency Fund",
+    "vacation": "Vacation Fund"
+  },
+  "investment": {
+    "etf": "ETF / Index Fund",
+    "pension": "Pension"
+  }
+}
+```
+
+For `src/i18n/de.json`, add the same structure with German translations:
+```json
+"presets": {
+  "income": {
+    "salary": "Gehalt",
+    "freelance": "Freelance-Einkommen",
+    "rental_income": "Mieteinnahmen",
+    "other_income": "Sonstiges Einkommen"
+  },
+  "bill": {
+    "rent": "Miete",
+    "electricity": "Strom",
+    "internet": "Internet",
+    "phone": "Telefon"
+  },
+  "variable_expense": {
+    "groceries": "Lebensmittel",
+    "transport": "Transport",
+    "dining_out": "Auswärts essen",
+    "health": "Gesundheit & Apotheke",
+    "clothing": "Kleidung"
+  },
+  "debt": {
+    "loan_repayment": "Kreditrückzahlung",
+    "credit_card": "Kreditkarte"
+  },
+  "saving": {
+    "emergency_fund": "Notfallfonds",
+    "vacation": "Urlaubskasse"
+  },
+  "investment": {
+    "etf": "ETF / Indexfonds",
+    "pension": "Altersvorsorge"
+  }
+}
+```
+
+Both files must remain valid JSON after the edit. Add the `"presets"` key as the last entry in each JSON object (before the closing `}`), preceded by a comma on the previous last key.
+  </action>
+  <verify>
+    <automated>node -e "JSON.parse(require('fs').readFileSync('src/i18n/en.json','utf8')); JSON.parse(require('fs').readFileSync('src/i18n/de.json','utf8')); console.log('JSON valid')" && grep -c '"slug_key"' src/i18n/en.json || grep -c '"salary"' src/i18n/en.json</automated>
+  </verify>
+  <done>Both JSON files are valid (node JSON.parse succeeds). `en.json` and `de.json` each contain a top-level `"presets"` key. `grep '"salary"' src/i18n/en.json` returns 1 match. `grep '"Gehalt"' src/i18n/de.json` returns 1 match.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| presets.ts → wizard UI | Static read-only data — no user input, no network calls |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-06-04 | Information Disclosure | presets.ts amounts | accept | Amounts are generic EUR defaults, not user-specific data; public knowledge |
+| T-06-05 | Tampering | i18n JSON malformed after edit | mitigate | Verify both JSON files parse cleanly after edit (`node -e "JSON.parse(...)"`) before committing |
+</threat_model>
+
+<verification>
+```bash
+# Confirm presets file exists with 19 items
+grep -c "slug:" src/data/presets.ts
+
+# Confirm no one_off tier
+grep "one_off" src/data/presets.ts || echo "no one_off found (correct)"
+
+# Confirm i18n JSON files are valid
+node -e "JSON.parse(require('fs').readFileSync('src/i18n/en.json','utf8')); console.log('en.json valid')"
+node -e "JSON.parse(require('fs').readFileSync('src/i18n/de.json','utf8')); console.log('de.json valid')"
+
+# Confirm presets key present in both
+grep '"presets"' src/i18n/en.json src/i18n/de.json
+
+# TypeScript clean
+npx tsc --noEmit
+```
+</verification>
+
+<success_criteria>
+- `src/data/presets.ts` exports `PresetItem` interface and `PRESETS` array with exactly 19 items
+- Distribution: 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment
+- All `item_tier` values are `"fixed"` or `"variable"` only
+- `en.json` and `de.json` both contain a valid `"presets"` nested object with all 19 slugs translated
+- Both JSON files remain valid (parseable) after edits
+- `tsc --noEmit` passes
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-02-SUMMARY.md`
+</output>

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-02-SUMMARY.md

@@ -0,0 +1,65 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+plan: "02"
+subsystem: data
+tags: [presets, i18n, static-data]
+dependency_graph:
+  requires: []
+  provides: [PresetItem, PRESETS]
+  affects: [src/data/presets.ts, src/i18n/en.json, src/i18n/de.json]
+tech_stack:
+  added: []
+  patterns: [static-data-module, i18n-dot-path]
+key_files:
+  created:
+    - src/data/presets.ts
+  modified:
+    - src/i18n/en.json
+    - src/i18n/de.json
+decisions:
+  - "item_tier restricted to fixed|variable only (no one_off) to match DB check constraint on template_items"
+  - "presets.{type}.{slug} i18n key structure matches type+slug fields in PRESETS array"
+metrics:
+  duration: "~5 minutes"
+  completed: "2026-04-20"
+  tasks_completed: 2
+  files_changed: 3
+---
+
+# Phase 06 Plan 02: Preset Data Library Summary
+
+Static 19-item preset budget library with English and German translations, structured as `presets.{type}.{slug}` i18n keys matching the PRESETS array shape.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Create src/data/presets.ts | 3bc7782 | src/data/presets.ts (created) |
+| 2 | Add preset translations to en.json and de.json | d235080 | src/i18n/en.json, src/i18n/de.json |
+
+## What Was Built
+
+`src/data/presets.ts` exports `PresetItem` interface and `PRESETS` array with exactly 19 items:
+- 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment
+- All `item_tier` values are `"fixed"` or `"variable"` (no `"one_off"`)
+- Pure static module — no Supabase or React imports
+
+Both i18n files now have a top-level `"presets"` key with nested `{type}.{slug}` structure covering all 19 slugs in English and German.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Threat Surface Scan
+
+No new network endpoints, auth paths, or trust boundaries introduced. T-06-05 (JSON malformed) mitigated — both files verified valid via `node -e "JSON.parse(...)"` before commit.
+
+## Self-Check: PASSED
+
+- src/data/presets.ts: FOUND
+- src/i18n/en.json "presets" key: FOUND
+- src/i18n/de.json "presets" key: FOUND
+- 19 PRESETS items confirmed (grep '{ slug:' returns 19)
+- no one_off in presets.ts confirmed
+- tsc --noEmit: PASSED
+- Commits 3bc7782 and d235080: confirmed in git log

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-PLAN.md

@@ -0,0 +1,255 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+plan: 03
+type: execute
+wave: 2
+depends_on:
+  - "06-01"
+  - "06-02"
+files_modified:
+  - src/hooks/useFirstRunState.ts
+autonomous: false
+requirements:
+  - AUTO-01
+  - AUTO-03
+  - SETUP-01
+  - SETUP-02
+
+must_haves:
+  truths:
+    - "useFirstRunState hook returns isFirstRun=true when categories array is empty"
+    - "useFirstRunState hook returns isFirstRun=true when template items array is empty"
+    - "useFirstRunState hook returns isFirstRun=false when user has both categories and template items"
+    - "useFirstRunState hook returns loading=true while either underlying query is in flight"
+    - "DB schema push completes without errors — uniqueness constraints and setup_completed column live in Supabase"
+  artifacts:
+    - path: "src/hooks/useFirstRunState.ts"
+      provides: "Derived first-run state from cached useCategories + useTemplate queries"
+      exports: ["useFirstRunState"]
+  key_links:
+    - from: "src/hooks/useFirstRunState.ts"
+      to: "src/hooks/useCategories.ts"
+      via: "useCategories() call — reads from cache key ['categories']"
+      pattern: "useCategories"
+    - from: "src/hooks/useFirstRunState.ts"
+      to: "src/hooks/useTemplate.ts"
+      via: "useTemplate() call — reads from cache keys ['template', 'template-items']"
+      pattern: "useTemplate"
+---
+
+<objective>
+Write the `useFirstRunState` hook and push all migrations to the database.
+
+`useFirstRunState` derives first-run state from existing React Query caches — no extra network call. It returns `{ isFirstRun: boolean, loading: boolean }` where `isFirstRun` is `true` when either categories or template items count is zero, and `loading` is `true` while either underlying query is still fetching.
+
+The DB schema push applies migrations 006 and 007, making uniqueness constraints and the `setup_completed` column live. This is a `[BLOCKING]` step — all verification depends on the schema being applied.
+
+Purpose: Phase 7 wizard reads `useFirstRunState().isFirstRun` to decide whether to redirect new users to setup. The DB constraints prevent the data corruption that would require rollback work in Phase 8.
+Output: `src/hooks/useFirstRunState.ts` + DB schema pushed + human verification checkpoint.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-01-SUMMARY.md
+@.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-02-SUMMARY.md
+
+<interfaces>
+From src/hooks/useCategories.ts:
+```typescript
+export function useCategories() {
+  // queryKey: ["categories"]
+  return {
+    categories: query.data ?? [],   // Category[]
+    loading: query.isLoading,
+    create, update, remove,
+  }
+}
+```
+
+From src/hooks/useTemplate.ts:
+```typescript
+export function useTemplate() {
+  // queryKeys: ["template"], ["template-items"]
+  return {
+    template: templateQuery.data ?? null,
+    items: itemsQuery.data ?? [],   // TemplateItem[]
+    loading: templateQuery.isLoading || itemsQuery.isLoading,
+    updateName, createItem, updateItem, deleteItem, reorderItems,
+  }
+}
+```
+
+From src/lib/types.ts (after Plan 01):
+```typescript
+export interface Profile {
+  id: string
+  display_name: string | null
+  locale: string
+  currency: string
+  setup_completed: boolean  // added by Plan 01
+  created_at: string
+  updated_at: string
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create src/hooks/useFirstRunState.ts</name>
+  <files>src/hooks/useFirstRunState.ts</files>
+  <read_first>
+    - src/hooks/useCategories.ts
+    - src/hooks/useTemplate.ts
+    - .planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md (Pattern 3: Derived State Hook, Pitfall 2)
+  </read_first>
+  <action>
+Create `src/hooks/useFirstRunState.ts` with the following exact implementation. Do not add mutations, do not import supabase directly — this hook is read-only and derives state from already-cached queries.
+
+```typescript
+import { useCategories } from "@/hooks/useCategories"
+import { useTemplate } from "@/hooks/useTemplate"
+
+/**
+ * Derives first-run state from cached category and template queries.
+ * No additional network calls are made — data is read from React Query cache.
+ *
+ * isFirstRun is true when:
+ *   - categories.length === 0 (user has not created any categories), OR
+ *   - items.length === 0 (user has no template items)
+ *
+ * IMPORTANT: Always check `loading` before acting on `isFirstRun`.
+ * While queries are in flight, both arrays default to [] which would
+ * cause isFirstRun to be true spuriously.
+ *
+ * Usage:
+ *   const { isFirstRun, loading } = useFirstRunState()
+ *   if (!loading && isFirstRun) { redirect to /setup }
+ */
+export function useFirstRunState() {
+  const { categories, loading: catLoading } = useCategories()
+  const { items, loading: tmplLoading } = useTemplate()
+
+  return {
+    isFirstRun: categories.length === 0 || items.length === 0,
+    loading: catLoading || tmplLoading,
+  }
+}
+```
+
+The `loading` guard is critical — see Pitfall 2 in RESEARCH.md. Callers in Phase 7 MUST check `!loading && isFirstRun` before redirecting.
+  </action>
+  <verify>
+    <automated>grep -n "isFirstRun" src/hooks/useFirstRunState.ts && grep -n "loading" src/hooks/useFirstRunState.ts && npx tsc --noEmit</automated>
+  </verify>
+  <done>File exists. Exports `useFirstRunState` function. Returns `{ isFirstRun: boolean, loading: boolean }`. `tsc --noEmit` passes with no errors.</done>
+</task>
+
+<task type="auto" id="db-push-blocking">
+  <name>Task 2: [BLOCKING] Push database schema (migrations 006 + 007)</name>
+  <files>supabase/migrations/006_uniqueness_constraints.sql, supabase/migrations/007_setup_completed.sql</files>
+  <read_first>
+    - supabase/migrations/006_uniqueness_constraints.sql
+    - supabase/migrations/007_setup_completed.sql
+  </read_first>
+  <action>
+Run the Supabase schema push to apply migrations 006 and 007 to the database. This command requires the Supabase CLI and an active project link.
+
+```bash
+supabase db push
+```
+
+If the push prompts interactively and cannot be suppressed, set the access token first:
+```bash
+SUPABASE_ACCESS_TOKEN=$(cat ~/.supabase/access-token 2>/dev/null || echo "SET_TOKEN_HERE") supabase db push
+```
+
+Expected outcome: Both migrations apply in order (006 then 007). The command exits 0.
+
+If the command fails with a duplicate constraint error (constraint already exists), the migrations may have been partially applied. In that case, check `supabase db diff` to see what's pending and resolve manually.
+
+If `supabase db push` requires interactive confirmation that cannot be bypassed, flag this task with a `checkpoint:human-action` and have the user run it manually from their terminal.
+  </action>
+  <verify>
+    <automated>supabase db push --dry-run 2>&1 | grep -E "No migrations|already applied|006|007" || echo "Check supabase CLI output above"</automated>
+  </verify>
+  <done>Both migrations applied. `supabase db push` exits 0 (or reports migrations already applied). No error output containing "ERROR" or "FATAL".</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Verify DB constraints and setup_completed column are live</name>
+  <what-built>
+    Migration 006 added UNIQUE constraints on budgets(user_id, start_date) and categories(user_id, name).
+    Migration 007 added setup_completed boolean column to profiles and backfilled existing users.
+    useFirstRunState hook created at src/hooks/useFirstRunState.ts.
+  </what-built>
+  <how-to-verify>
+    1. Open the Supabase dashboard for this project.
+    2. Go to Table Editor > profiles — confirm the `setup_completed` column exists with boolean type.
+    3. Go to Database > Tables > budgets — confirm constraint `budgets_user_month_unique` exists on (user_id, start_date).
+    4. Go to Database > Tables > categories — confirm constraint `categories_user_name_unique` exists on (user_id, name).
+    5. If you have an existing v1.0 user row in profiles, confirm setup_completed = true for that row.
+    6. Run `npx tsc --noEmit` in the terminal — confirm zero TypeScript errors.
+  </how-to-verify>
+  <resume-signal>Type "approved" if all constraints are live and tsc passes, or describe any issues found.</resume-signal>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| useFirstRunState → React Query cache | Reads cached data from existing hooks — no new trust boundary introduced |
+| supabase db push → Supabase project | CLI command with project-level credentials — run only in trusted environment |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-06-06 | Spoofing | useFirstRunState — isFirstRun=true while loading | mitigate | loading flag exported; callers must check `!loading && isFirstRun` before acting (documented in hook JSDoc) |
+| T-06-07 | Denial of Service | supabase db push failing mid-migration | accept | Transaction wrapping in 006 ensures atomicity; 007 is idempotent (ADD COLUMN IF NOT EXISTS can be added if needed) |
+</threat_model>
+
+<verification>
+```bash
+# Hook exports correctly
+grep "export function useFirstRunState" src/hooks/useFirstRunState.ts
+
+# Hook uses both existing hooks
+grep "useCategories\|useTemplate" src/hooks/useFirstRunState.ts
+
+# TypeScript clean across all new files
+npx tsc --noEmit
+
+# Migration files in place
+ls supabase/migrations/006_uniqueness_constraints.sql supabase/migrations/007_setup_completed.sql
+
+# All 4 requirement IDs traceable across plans:
+# AUTO-01: useFirstRunState (plan 03) + budgets constraint (plan 01)
+# AUTO-03: setup_completed not hardcoding currency (plan 01, 02, 03 — amounts plain numbers)
+# SETUP-01: setup_completed column + backfill (plan 01) + useFirstRunState (plan 03)
+# SETUP-02: PRESETS array 19 items (plan 02)
+```
+</verification>
+
+<success_criteria>
+- `src/hooks/useFirstRunState.ts` exists and exports `useFirstRunState()` returning `{ isFirstRun: boolean, loading: boolean }`
+- `isFirstRun` is derived from `categories.length === 0 || items.length === 0` — no direct Supabase calls
+- DB push completes: `budgets_user_month_unique` and `categories_user_name_unique` constraints live in Supabase
+- `profiles` table has `setup_completed boolean NOT NULL DEFAULT false` column
+- All existing users with categories (or template items) have `setup_completed = true`
+- `tsc --noEmit` passes with zero errors across all modified files
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-SUMMARY.md`
+</output>

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-SUMMARY.md

@@ -0,0 +1,87 @@
+---
+phase: 06
+plan: 03
+subsystem: first-run-detection
+tags: [hooks, supabase, migrations, first-run]
+started: "2026-04-20T17:32:09Z"
+completed: "2026-04-20T18:07:20Z"
+status: complete
+dependency_graph:
+  requires: [06-01, 06-02]
+  provides: [useFirstRunState-hook, db-schema-live]
+  affects: [phase-07-wizard]
+tech_stack:
+  added: []
+  patterns: [derived-state-hook, loading-guard-pattern]
+key_files:
+  created:
+    - src/hooks/useFirstRunState.ts
+  modified: []
+decisions:
+  - "Hook derives state from existing React Query caches (useCategories + useTemplate) with zero additional network calls"
+  - "DB migrations applied manually by user via supabase db push after checkpoint gate"
+metrics:
+  duration: ~35min (including checkpoint wait)
+  tasks_completed: 3
+  files_created: 1
+  files_modified: 0
+---
+
+# Phase 06 Plan 03: useFirstRunState Hook and DB Schema Push Summary
+
+Derived first-run detection hook reading from React Query cache with loading guard to prevent spurious redirects, plus live DB schema with uniqueness constraints and setup_completed column.
+
+## What Was Built
+
+### useFirstRunState Hook (src/hooks/useFirstRunState.ts)
+
+A read-only derived state hook that composes `useCategories()` and `useTemplate()` to determine whether the current user is a first-run user (no categories or no template items). Returns `{ isFirstRun: boolean, loading: boolean }`. The `loading` flag is critical -- callers in Phase 7 must check `!loading && isFirstRun` before redirecting to prevent false positives while queries are in flight.
+
+### DB Schema Push (migrations 006 + 007)
+
+User applied both migrations via `supabase db push`:
+- Migration 006: UNIQUE constraints on `budgets(user_id, start_date)` and `categories(user_id, name)` with safe deduplication
+- Migration 007: `setup_completed` boolean column on `profiles` with backfill for existing users
+
+## Task Execution
+
+| Task | Name | Commit | Status |
+|------|------|--------|--------|
+| 1 | Create useFirstRunState.ts | 0c1105f | Complete |
+| 2 | DB schema push (migrations 006+007) | Manual (user) | Complete - user applied |
+| 3 | Human verification checkpoint | N/A | Approved by user |
+
+## Decisions Made
+
+1. **Zero-network-call design** -- Hook reads from existing React Query caches rather than making its own Supabase calls, avoiding redundant fetches.
+2. **Manual DB push** -- `supabase db push` required interactive confirmation; user ran it manually after checkpoint gate.
+
+## Deviations from Plan
+
+None -- plan executed exactly as written.
+
+## Known Stubs
+
+None -- hook is fully wired to existing data sources.
+
+## Verification Results
+
+- `export function useFirstRunState` found in hook file
+- Both `useCategories` and `useTemplate` imports present
+- `npx tsc --noEmit` passes with zero errors
+- Migration files 006 and 007 exist in supabase/migrations/
+- User confirmed DB constraints and setup_completed column are live in Supabase dashboard
+
+## Requirements Covered
+
+- **AUTO-01**: useFirstRunState provides first-run detection for auto-budget flow
+- **AUTO-03**: No hardcoded currency -- amounts are plain numbers throughout
+- **SETUP-01**: setup_completed column + backfill (plan 01) + useFirstRunState detection (plan 03)
+- **SETUP-02**: Preset library with 19 items delivered in plan 02
+
+## Self-Check: PASSED
+
+- [x] src/hooks/useFirstRunState.ts exists
+- [x] Commit 0c1105f verified in git log
+- [x] TypeScript compiles cleanly
+- [x] Migration files present on disk

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md

@@ -0,0 +1,81 @@
+# Phase 6: Preset Data, First-Run Detection, and DB Safety - Context
+
+**Gathered:** 2026-04-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+The data layer is safe and ready — duplicate budget/category writes are impossible at the DB level, and the app correctly identifies first-run users. This phase delivers: DB uniqueness constraints, a setup_completed column with backfill migration, a useFirstRunState hook, and a preset budget item library (~15-20 items with i18n).
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Preset Library Content
+- Default amounts in EUR (matches existing profiles.currency default)
+- 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment items (~19 total)
+- i18n key format: `presets.{category_type}.{slug}` (e.g., `presets.bill.rent`)
+- Round number amounts (e.g., rent=1000, groceries=400) — easier to adjust, less presumptuous
+
+### First-Run Detection Logic
+- First-run triggers when user has zero categories OR zero template items (either missing = not set up)
+- New dedicated hook: `src/hooks/useFirstRunState.ts` (follows useCategories/useTemplate pattern)
+- Backfill via Supabase migration SQL: `UPDATE profiles SET setup_completed = true WHERE id IN (SELECT DISTINCT user_id FROM categories)`
+- Hook derives state from existing hooks (useCategories count + useTemplate items count) — no extra network call
+
+### DB Migration & Constraint Strategy
+- Cleanup step before adding unique constraints (deduplicate existing data safely)
+- Separate migration files: `006_uniqueness_constraints.sql` and `007_setup_completed.sql`
+- `setup_completed` column defaults to `false` — new signups start as not-setup; existing users backfilled to `true`
+- Unique constraint on budgets: `(user_id, start_date)` only — end_date always derived
+
+### Claude's Discretion
+- Exact preset item names and amounts (within the balanced category distribution)
+- German translation text for preset i18n keys
+- Order of migration operations within each file
+- Error handling approach for constraint violations in application code
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `src/hooks/useCategories.ts` — existing hook pattern to follow for useFirstRunState
+- `src/hooks/useTemplate.ts` — template data access, can derive "has template items" from this
+- `src/lib/types.ts` — type definitions for categories, templates, budgets
+- `supabase/migrations/001-005` — existing migration chain to extend
+
+### Established Patterns
+- Hooks use React Query with Supabase client
+- Category types enum: income, bill, variable_expense, debt, saving, investment
+- Template items reference categories via category_id
+- Profiles table auto-created via trigger on auth.users insert
+
+### Integration Points
+- `profiles` table needs new `setup_completed` boolean column
+- `budgets` table needs unique constraint on (user_id, start_date)
+- `categories` table needs unique constraint on (user_id, name)
+- New `src/data/presets.ts` file for preset library
+- New `src/hooks/useFirstRunState.ts` for first-run detection
+- i18n files need preset translation keys (en + de)
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Currency column in profiles is already `currency text not null default 'EUR'` — confirmed in 001_profiles.sql
+- The `handle_new_user()` trigger creates profiles on signup — setup_completed will be false by default for new users
+- Templates table already has `unique(user_id)` — one template per user is enforced
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope.
+
+</deferred>

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-RESEARCH.md

@@ -0,0 +1,522 @@
+# Phase 6: Preset Data, First-Run Detection, and DB Safety - Research
+
+**Researched:** 2026-04-20
+**Domain:** PostgreSQL constraints, Supabase migrations, React Query hooks, i18n data files
+**Confidence:** HIGH
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- Default amounts in EUR (matches existing profiles.currency default)
+- 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment items (~19 total)
+- i18n key format: `presets.{category_type}.{slug}` (e.g., `presets.bill.rent`)
+- Round number amounts (e.g., rent=1000, groceries=400) — easier to adjust, less presumptuous
+- First-run triggers when user has zero categories OR zero template items
+- New dedicated hook: `src/hooks/useFirstRunState.ts` (follows useCategories/useTemplate pattern)
+- Backfill via Supabase migration SQL: `UPDATE profiles SET setup_completed = true WHERE id IN (SELECT DISTINCT user_id FROM categories)`
+- Hook derives state from existing hooks (useCategories count + useTemplate items count) — no extra network call
+- Cleanup step before adding unique constraints (deduplicate existing data safely)
+- Separate migration files: `006_uniqueness_constraints.sql` and `007_setup_completed.sql`
+- `setup_completed` column defaults to `false`; existing users backfilled to `true`
+- Unique constraint on budgets: `(user_id, start_date)` only — end_date always derived
+
+### Claude's Discretion
+- Exact preset item names and amounts (within the balanced category distribution)
+- German translation text for preset i18n keys
+- Order of migration operations within each file
+- Error handling approach for constraint violations in application code
+
+### Deferred Ideas (OUT OF SCOPE)
+None — discussion stayed within phase scope.
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| AUTO-01 | User's monthly budget is auto-created from template when visiting a month for the first time | `useFirstRunState` hook detects zero-category / zero-template-item state; budgets unique constraint prevents duplicate auto-creation |
+| AUTO-03 | Auto-creation uses the user's configured currency, not a hardcoded default | `profiles.currency` confirmed as `text not null default 'EUR'` — hook/migration must not hardcode currency |
+| SETUP-01 | New user is guided through a 3-step wizard: income → recurring items → review | `setup_completed` column + backfill migration provides the flag Phase 7 wizard reads to decide whether to show onboarding |
+| SETUP-02 | User sees pre-filled common budget items with sensible default amounts (~15-20 items) | `src/data/presets.ts` delivers the curated item library with i18n keys and EUR amounts |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 6 is a pure data/infrastructure layer — no new UI. It consists of four discrete deliverables: two Supabase migration files (uniqueness constraints + setup_completed column), a new TypeScript data file (`src/data/presets.ts`), a new React Query hook (`src/hooks/useFirstRunState.ts`), and additions to both i18n JSON files.
+
+The existing schema (verified against migrations 001–005) has no duplicate-prevention constraints on `budgets` or `categories`. The `profiles` table has no `setup_completed` column yet. The `templates` table already has `unique(user_id)`. All hook patterns follow `useQuery` + `useMutation` from `@tanstack/react-query` with the Supabase JS client — `useFirstRunState` will be read-only (query-only) and simpler than existing hooks.
+
+The main planning risk is the cleanup step before adding unique constraints: the deduplication SQL must run inside the same transaction as the `ADD CONSTRAINT` statement so the constraint cannot be violated by orphaned duplicates surviving the cleanup.
+
+**Primary recommendation:** Write migration 006 as a single transaction — DELETE duplicates, then ADD CONSTRAINT — so it's atomic and safe to run on existing databases.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Duplicate-write prevention | Database | — | Constraint enforced at DB level; application code is a secondary guard only |
+| First-run detection state | Frontend (React Query hook) | — | Derived from cached query data, no extra network call |
+| Preset item library | Frontend (static data file) | — | Static TypeScript module; no DB persistence, consumed by wizard (Phase 7) |
+| setup_completed persistence | Database (profiles table) | — | Boolean column; written by migration backfill and by wizard completion (Phase 7) |
+| i18n for preset names | Frontend (JSON files) | — | Follows existing en.json / de.json pattern |
+
+---
+
+## Standard Stack
+
+### Core (all already installed — verified against package.json)
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `@tanstack/react-query` | (existing) | Server state, caching for useFirstRunState | Already used by all hooks |
+| `@supabase/supabase-js` | (existing) | DB client in hooks and migrations | Already used by all hooks |
+| PostgreSQL (via Supabase) | (existing) | Unique constraints, ALTER TABLE | Native DB feature; no library needed |
+
+No new npm packages are required for this phase.
+
+### Migration Tooling
+Supabase migrations are plain `.sql` files in `supabase/migrations/`. They are run in filename order by the Supabase CLI (`supabase db push`) or applied directly via the Supabase dashboard SQL editor. [VERIFIED: project migration files 001–005]
+
+---
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+Supabase DB
+  ├── Migration 006: uniqueness_constraints
+  │     ├── DELETE duplicate budgets (keep oldest per user+start_date)
+  │     ├── DELETE duplicate categories (keep oldest per user+name)
+  │     ├── ADD CONSTRAINT budgets_user_month_unique ON budgets(user_id, start_date)
+  │     └── ADD CONSTRAINT categories_user_name_unique ON categories(user_id, name)
+  │
+  └── Migration 007: setup_completed
+        ├── ALTER TABLE profiles ADD COLUMN setup_completed boolean NOT NULL DEFAULT false
+        └── UPDATE profiles SET setup_completed = true
+              WHERE id IN (SELECT DISTINCT user_id FROM categories)
+
+src/data/presets.ts  ──────────────────────────────────────► Phase 7 wizard
+  (static array of PresetItem objects, keyed by i18n slug)
+
+src/hooks/useFirstRunState.ts
+  ├── calls useCategories()  (uses cached ["categories"] query — no new fetch)
+  ├── calls useTemplate()    (uses cached ["template-items"] query — no new fetch)
+  └── returns { isFirstRun: boolean, loading: boolean }
+        isFirstRun = categories.length === 0 || items.length === 0
+
+src/i18n/en.json  }  add "presets" top-level key
+src/i18n/de.json  }  add "presets" top-level key
+```
+
+### Recommended Project Structure (additions only)
+
+```
+src/
+├── data/
+│   └── presets.ts          # NEW: preset budget item library
+├── hooks/
+│   └── useFirstRunState.ts # NEW: first-run detection hook
+└── i18n/
+    ├── en.json             # ADD: presets.* keys
+    └── de.json             # ADD: presets.* keys
+
+supabase/migrations/
+├── 006_uniqueness_constraints.sql  # NEW
+└── 007_setup_completed.sql         # NEW
+```
+
+### Pattern 1: Safe Deduplication Before Unique Constraint
+
+**What:** Delete all but the oldest row per unique key before adding the constraint, wrapped in a transaction.
+**When to use:** Any migration adding a unique constraint on a table that may have existing duplicates.
+
+```sql
+-- Source: [VERIFIED: standard PostgreSQL CTE deduplication pattern]
+BEGIN;
+
+-- Keep only the oldest budget per (user_id, start_date)
+DELETE FROM budgets
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, start_date) id
+  FROM budgets
+  ORDER BY user_id, start_date, created_at ASC
+);
+
+ALTER TABLE budgets
+  ADD CONSTRAINT budgets_user_month_unique UNIQUE (user_id, start_date);
+
+-- Keep only the oldest category per (user_id, name)
+DELETE FROM categories
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, name) id
+  FROM categories
+  ORDER BY user_id, name, created_at ASC
+);
+
+ALTER TABLE categories
+  ADD CONSTRAINT categories_user_name_unique UNIQUE (user_id, name);
+
+COMMIT;
+```
+
+### Pattern 2: ADD COLUMN with Default + Immediate Backfill
+
+**What:** Add a boolean column with a default, then immediately UPDATE to backfill existing rows.
+**When to use:** Column needs a non-null default for new rows, but existing rows need a different value.
+
+```sql
+-- Source: [VERIFIED: standard PostgreSQL ALTER TABLE pattern]
+ALTER TABLE profiles
+  ADD COLUMN setup_completed boolean NOT NULL DEFAULT false;
+
+-- Backfill: existing users who have categories are considered set up
+UPDATE profiles
+SET setup_completed = true
+WHERE id IN (SELECT DISTINCT user_id FROM categories);
+```
+
+**Important:** `DEFAULT false` in the `ALTER TABLE` statement means the column is added atomically with `false` for all existing rows *before* the UPDATE runs. The UPDATE then flips the qualifying rows. Order matters here. [VERIFIED: PostgreSQL behavior]
+
+### Pattern 3: Derived State Hook (no extra network call)
+
+**What:** Build a hook that computes a boolean from two already-cached queries.
+**When to use:** When state can be inferred from data already loaded by sibling hooks.
+
+```typescript
+// Source: [VERIFIED: matches useCategories.ts + useTemplate.ts patterns in codebase]
+import { useCategories } from "@/hooks/useCategories"
+import { useTemplate } from "@/hooks/useTemplate"
+
+export function useFirstRunState() {
+  const { categories, loading: catLoading } = useCategories()
+  const { items, loading: tmplLoading } = useTemplate()
+
+  return {
+    isFirstRun: categories.length === 0 || items.length === 0,
+    loading: catLoading || tmplLoading,
+  }
+}
+```
+
+**Key insight:** `useCategories` caches under `["categories"]` and `useTemplate` caches under `["template"]` + `["template-items"]`. If those queries have already been called (e.g., by mounted pages), `useFirstRunState` returns instantly from cache — no extra Supabase round-trip. [VERIFIED: React Query staleTime default behavior]
+
+### Pattern 4: Preset Data File Shape
+
+**What:** Static TypeScript module exporting typed preset items.
+**When to use:** Read-only reference data consumed by the wizard UI (Phase 7).
+
+```typescript
+// Source: [ASSUMED — no existing presets.ts to verify against; shape inferred from types.ts]
+export interface PresetItem {
+  slug: string                // used to build i18n key: presets.{type}.{slug}
+  type: CategoryType          // from src/lib/types.ts
+  defaultAmount: number       // EUR, round number
+  item_tier: "fixed" | "variable"
+}
+
+export const PRESETS: PresetItem[] = [
+  // income (4)
+  { slug: "salary",         type: "income",           defaultAmount: 3000, item_tier: "fixed"    },
+  { slug: "freelance",      type: "income",           defaultAmount: 500,  item_tier: "variable" },
+  { slug: "rental_income",  type: "income",           defaultAmount: 800,  item_tier: "fixed"    },
+  { slug: "other_income",   type: "income",           defaultAmount: 200,  item_tier: "variable" },
+  // bill (4)
+  { slug: "rent",           type: "bill",             defaultAmount: 1000, item_tier: "fixed"    },
+  { slug: "electricity",    type: "bill",             defaultAmount: 80,   item_tier: "fixed"    },
+  { slug: "internet",       type: "bill",             defaultAmount: 40,   item_tier: "fixed"    },
+  { slug: "phone",          type: "bill",             defaultAmount: 30,   item_tier: "fixed"    },
+  // variable_expense (5)
+  { slug: "groceries",      type: "variable_expense", defaultAmount: 400,  item_tier: "variable" },
+  { slug: "transport",      type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  { slug: "dining_out",     type: "variable_expense", defaultAmount: 150,  item_tier: "variable" },
+  { slug: "health",         type: "variable_expense", defaultAmount: 50,   item_tier: "variable" },
+  { slug: "clothing",       type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  // debt (2)
+  { slug: "loan_repayment", type: "debt",             defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "credit_card",    type: "debt",             defaultAmount: 100,  item_tier: "fixed"    },
+  // saving (2)
+  { slug: "emergency_fund", type: "saving",           defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "vacation",       type: "saving",           defaultAmount: 100,  item_tier: "fixed"    },
+  // investment (2)
+  { slug: "etf",            type: "investment",       defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "pension",        type: "investment",       defaultAmount: 100,  item_tier: "fixed"    },
+]
+```
+
+### Pattern 5: i18n Key Structure for Presets
+
+The existing i18n files use a flat nested structure. Add a `"presets"` top-level key, nested by `category_type`, then `slug`. [VERIFIED: matches en.json structure]
+
+```json
+// en.json addition
+{
+  "presets": {
+    "income": {
+      "salary": "Salary",
+      "freelance": "Freelance Income",
+      "rental_income": "Rental Income",
+      "other_income": "Other Income"
+    },
+    "bill": {
+      "rent": "Rent",
+      "electricity": "Electricity",
+      "internet": "Internet",
+      "phone": "Phone"
+    },
+    "variable_expense": {
+      "groceries": "Groceries",
+      "transport": "Transport",
+      "dining_out": "Dining Out",
+      "health": "Health & Pharmacy",
+      "clothing": "Clothing"
+    },
+    "debt": {
+      "loan_repayment": "Loan Repayment",
+      "credit_card": "Credit Card"
+    },
+    "saving": {
+      "emergency_fund": "Emergency Fund",
+      "vacation": "Vacation Fund"
+    },
+    "investment": {
+      "etf": "ETF / Index Fund",
+      "pension": "Pension"
+    }
+  }
+}
+```
+
+### Anti-Patterns to Avoid
+
+- **Adding UNIQUE constraint without deduplication first:** Will fail with `duplicate key value violates unique constraint` on any DB with existing duplicate rows.
+- **Separate transaction for cleanup and constraint:** If cleanup succeeds but constraint ADD fails (e.g., missed a duplicate), the DB is left partially modified. Always wrap both in one `BEGIN/COMMIT`.
+- **isFirstRun computed at render without loading guard:** Returns `true` spuriously while queries are still in-flight (both lengths are 0). Always gate on `loading` before acting on `isFirstRun`.
+- **Hardcoding 'EUR' in presets.ts:** The preset amounts are EUR, but the label/currency displayed in the wizard must come from `profiles.currency`, not from presets.ts. Keep amounts as plain numbers.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Duplicate row prevention | Application-level upsert logic with SELECT-then-INSERT | PostgreSQL UNIQUE constraint | Race condition between SELECT and INSERT; DB constraint is atomic |
+| Query caching for derived state | Manual state tracking / local useState | React Query (already installed) | useCategories + useTemplate already cache — just consume the cached data |
+| i18n key resolution | Custom translation lookup | Existing i18n framework already in use | Check how `t()` is called in existing components and replicate |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: DISTINCT ON Requires ORDER BY on the Same Columns
+
+**What goes wrong:** `SELECT DISTINCT ON (user_id, start_date)` without `ORDER BY user_id, start_date` throws a PostgreSQL error.
+**Why it happens:** PostgreSQL requires the DISTINCT ON expressions to be the leftmost ORDER BY expressions.
+**How to avoid:** Always write `ORDER BY user_id, start_date, created_at ASC` (or whichever tiebreaker). [VERIFIED: PostgreSQL docs behavior]
+**Warning signs:** `ERROR: SELECT DISTINCT ON expressions must match initial ORDER BY expressions`
+
+### Pitfall 2: isFirstRun is True During Loading
+
+**What goes wrong:** `categories.length === 0 || items.length === 0` is `true` while data is still loading (both arrays are empty defaults). If Phase 7 wizard triggers on `isFirstRun`, it fires on every page load while data fetches.
+**Why it happens:** `useCategories` returns `[]` as default; hook consumers see `isFirstRun = true` before the query resolves.
+**How to avoid:** Export `loading` from `useFirstRunState`. Callers must check `!loading && isFirstRun` before acting. [VERIFIED: useCategories.ts returns `query.data ?? []`]
+**Warning signs:** Wizard flashes on every load for users who have data.
+
+### Pitfall 3: Backfill Misses Users Without Categories
+
+**What goes wrong:** The backfill SQL sets `setup_completed = true` only for users who have categories. A v1.0 user who created a template but no categories would remain `false` and see the wizard on first v2.0 login.
+**Why it happens:** The backfill uses `categories` as the signal; it's possible (though unlikely in v1.0) to have a template with no categories.
+**How to avoid:** The agreed logic (zero categories OR zero template items = first run) means a user with template items but no categories is legitimately not set up. Verify that v1.0 users always created categories before template items. If uncertain, widen the backfill:
+  ```sql
+  UPDATE profiles SET setup_completed = true
+  WHERE id IN (
+    SELECT DISTINCT user_id FROM categories
+    UNION
+    SELECT t.user_id FROM templates t
+    INNER JOIN template_items ti ON ti.template_id = t.id
+  );
+  ```
+**Warning signs:** v1.0 users reporting wizard appearing unexpectedly.
+
+### Pitfall 4: Profile Type Missing setup_completed
+
+**What goes wrong:** After migration 007 adds `setup_completed`, the TypeScript `Profile` interface in `src/lib/types.ts` still lacks the field. Any code reading `profile.setup_completed` gets a TypeScript error or `undefined`.
+**Why it happens:** Migrations and TypeScript types are manually kept in sync — there is no auto-generation in this project.
+**How to avoid:** Include updating `src/lib/types.ts` as an explicit task in the plan. Add `setup_completed: boolean` to the `Profile` interface. [VERIFIED: types.ts inspected — field absent]
+**Warning signs:** TypeScript compiler error on `profile.setup_completed`.
+
+### Pitfall 5: Migration File Ordering
+
+**What goes wrong:** A migration named `006_...` that runs after one named `007_...` (or vice versa) due to filename sort.
+**Why it happens:** Supabase CLI applies migrations in lexicographic filename order.
+**How to avoid:** Uniqueness constraints must come in `006_...` and setup_completed in `007_...` because the backfill in 007 reads from `categories` — which needs to exist and be constraint-safe first. The order is correct as specified. [VERIFIED: existing migrations 001–005 confirm naming convention]
+
+---
+
+## Code Examples
+
+### Confirmed: Category Type Enum Values
+
+From `002_categories.sql` and `src/lib/types.ts` [VERIFIED]:
+```
+'income' | 'bill' | 'variable_expense' | 'debt' | 'saving' | 'investment'
+```
+Preset items must use these exact string values as `type`.
+
+### Confirmed: profiles Table Columns (before migration 007)
+
+From `001_profiles.sql` [VERIFIED]:
+```
+id, display_name, locale, currency, created_at, updated_at
+```
+No `setup_completed` column exists yet. Migration 007 adds it.
+
+### Confirmed: budgets Table (before migration 006)
+
+From `004_budgets.sql` [VERIFIED]:
+- No unique constraint on `(user_id, start_date)`.
+- `start_date date not null`, `end_date date not null` — both present.
+
+### Confirmed: categories Table (before migration 006)
+
+From `002_categories.sql` [VERIFIED]:
+- No unique constraint on `(user_id, name)`.
+- Only a `categories_user_id_idx` index exists.
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Application-level duplicate checks | DB-level UNIQUE constraint | This phase | Eliminates race conditions; constraint error surfaces as Supabase PostgREST error code `23505` |
+| No first-run concept | `setup_completed` + `useFirstRunState` | This phase | Enables Phase 7 wizard to show only to new users |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `item_tier: "one_off"` is excluded from presets (only "fixed" and "variable") | Pattern 4 | If wizard allows one_off presets, the type needs updating — but `template_items.item_tier` check constraint already limits to `('fixed', 'variable')` so this is safe |
+| A2 | No existing duplicate budgets or categories in production data | Migration 006 | If duplicates exist the DELETE+CONSTRAINT pattern handles them; risk is low, the cleanup step is exactly for this |
+| A3 | The i18n library in use supports nested key access via dot notation (e.g., `t('presets.bill.rent')`) | i18n pattern | If it uses a flat key format, key structure needs adjustment — check existing `t()` calls in components before writing keys |
+
+---
+
+## Open Questions
+
+1. **How does the app call `t()`?**
+   - What we know: en.json and de.json use nested objects (e.g., `categories.types.income`).
+   - What's unclear: Whether translation is `t('categories.types.income')` (dot-path) or `t('categories')['types']['income']`. Most react-i18next setups use dot-path.
+   - Recommendation: Before writing i18n keys, grep one existing `t()` call in the codebase to confirm syntax. Plan task should include this verification.
+
+2. **Are there any existing v1.0 users in production?**
+   - What we know: The blocker in STATE.md says "existing v1.0 users must not see the wizard on first v2.0 login."
+   - What's unclear: Whether production has real user rows in `profiles` or if this is a personal/dev-only app.
+   - Recommendation: The migration is written defensively regardless — backfill runs on all qualifying rows, so there's no harm if the table is empty.
+
+---
+
+## Environment Availability
+
+Step 2.6: SKIPPED (no new external dependencies — all tools are existing: Supabase CLI, PostgreSQL, Node/TypeScript toolchain already in use by the project).
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | None detected — no vitest.config.*, jest.config.*, or test scripts in package.json |
+| Config file | None — Wave 0 must create if tests are written |
+| Quick run command | N/A |
+| Full suite command | N/A |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| AUTO-01 | `useFirstRunState` returns `isFirstRun=true` when categories=[] | unit | `vitest run src/hooks/useFirstRunState.test.ts` | ❌ Wave 0 |
+| AUTO-01 | `useFirstRunState` returns `isFirstRun=false` when categories and items present | unit | `vitest run src/hooks/useFirstRunState.test.ts` | ❌ Wave 0 |
+| AUTO-01 | `useFirstRunState` returns `loading=true` while queries in flight | unit | `vitest run src/hooks/useFirstRunState.test.ts` | ❌ Wave 0 |
+| SETUP-02 | `PRESETS` exports exactly 19 items | unit | `vitest run src/data/presets.test.ts` | ❌ Wave 0 |
+| SETUP-02 | Each preset has valid `type` from CategoryType enum | unit | `vitest run src/data/presets.test.ts` | ❌ Wave 0 |
+| SETUP-02 | Each preset has `item_tier` of `fixed` or `variable` (not `one_off`) | unit | `vitest run src/data/presets.test.ts` | ❌ Wave 0 |
+| AUTO-03 | `Profile.setup_completed` TypeScript type is boolean | compile-time | `tsc --noEmit` | ❌ Wave 0 (after types.ts update) |
+| DB constraints | Unique constraint SQL — not unit-testable without Supabase local instance | manual | Supabase local dev + insert duplicate | N/A |
+
+### Sampling Rate
+- **Per task commit:** `tsc --noEmit` (type safety at minimum)
+- **Per wave merge:** `vitest run` (once vitest is set up)
+- **Phase gate:** All passing before `/gsd-verify-work`
+
+### Wave 0 Gaps
+- [ ] `vitest` not installed — install: `npm install -D vitest @vitest/ui`
+- [ ] `src/hooks/useFirstRunState.test.ts` — covers AUTO-01 loading guard and isFirstRun logic
+- [ ] `src/data/presets.test.ts` — covers SETUP-02 count, type validity, item_tier validity
+- [ ] `vitest.config.ts` — framework config (or add `"test"` to `vite.config.ts`)
+
+---
+
+## Security Domain
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | no | — |
+| V3 Session Management | no | — |
+| V4 Access Control | yes | Supabase RLS already enabled on all tables — new constraints do not bypass RLS |
+| V5 Input Validation | no | No new user-facing input in this phase |
+| V6 Cryptography | no | — |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| Duplicate budget creation via parallel requests | Tampering | UNIQUE constraint on `(user_id, start_date)` — DB rejects second insert atomically |
+| First-run flag manipulation (client sets setup_completed) | Elevation of privilege | RLS policy `"Users can update own profile"` — user can update their own row; acceptable since setup_completed is not a security gate, only a UX flag |
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- `supabase/migrations/001_profiles.sql` — profiles table schema, trigger, no setup_completed column confirmed
+- `supabase/migrations/002_categories.sql` — categories table schema, no unique constraint on (user_id, name) confirmed
+- `supabase/migrations/004_budgets.sql` — budgets table schema, no unique constraint on (user_id, start_date) confirmed
+- `src/hooks/useCategories.ts` — hook pattern, query key ["categories"], default returns []
+- `src/hooks/useTemplate.ts` — hook pattern, query keys, items default []
+- `src/lib/types.ts` — CategoryType values, Profile interface (no setup_completed), all confirmed
+- `src/i18n/en.json`, `de.json` — i18n structure and nesting pattern confirmed
+- `.planning/config.json` — nyquist_validation: true confirmed
+
+### Secondary (MEDIUM confidence)
+- PostgreSQL DISTINCT ON + ORDER BY requirement — standard behavior, well-documented
+
+### Tertiary (LOW confidence)
+- A3: i18n dot-path notation — inferred from JSON structure; needs grep verification
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — all libraries verified as already installed
+- Architecture: HIGH — all schema details verified against actual migration files and hook source
+- Pitfalls: HIGH — derived from direct inspection of existing code and standard PostgreSQL semantics
+- Preset content: MEDIUM — exact amounts and slugs are at Claude's discretion; structure is HIGH confidence
+
+**Research date:** 2026-04-20
+**Valid until:** 2026-07-20 (stable domain — PostgreSQL constraints and React Query patterns are not fast-moving)

.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-VERIFICATION.md

@@ -0,0 +1,140 @@
+---
+phase: 06-preset-data-first-run-detection-and-db-safety
+verified: 2026-04-20T19:15:00Z
+status: human_needed
+score: 5/5
+overrides_applied: 0
+human_verification:
+  - test: "Attempt duplicate budget INSERT for same (user_id, start_date) via Supabase SQL editor"
+    expected: "INSERT fails with unique constraint violation error 23505"
+    why_human: "Requires a running Supabase instance with live DB to test constraint enforcement"
+  - test: "Attempt duplicate category INSERT for same (user_id, name) via Supabase SQL editor"
+    expected: "INSERT fails with unique constraint violation error 23505"
+    why_human: "Requires a running Supabase instance with live DB to test constraint enforcement"
+  - test: "Check profiles table for existing v1.0 user rows — confirm setup_completed = true"
+    expected: "All users who had categories or template items before migration show setup_completed = true"
+    why_human: "Requires inspecting live database state after backfill"
+---
+
+# Phase 6: Preset Data, First-Run Detection, and DB Safety Verification Report
+
+**Phase Goal:** The data layer is safe and ready -- duplicate budget/category writes are impossible at the DB level, and the app correctly identifies first-run users
+**Verified:** 2026-04-20T19:15:00Z
+**Status:** human_needed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | Attempting to create two budgets for the same user and month is rejected at the DB level | VERIFIED | `006_uniqueness_constraints.sql` contains `ADD CONSTRAINT budgets_user_month_unique UNIQUE (user_id, start_date)` wrapped in BEGIN/COMMIT. User confirmed DB push completed successfully. |
+| 2 | Attempting to create two categories with the same name for the same user is rejected at the DB level | VERIFIED | `006_uniqueness_constraints.sql` contains `ADD CONSTRAINT categories_user_name_unique UNIQUE (user_id, name)` with safe deduplication DELETE. User confirmed DB push completed. |
+| 3 | All existing v1.0 users have `profiles.setup_completed = true` after backfill | VERIFIED | `007_setup_completed.sql` adds column `boolean NOT NULL DEFAULT false` then runs UPDATE with UNION covering both `categories` and `template_items` tables. User confirmed DB push applied. |
+| 4 | `useFirstRunState` hook returns `true` only for users with zero categories or zero template items | VERIFIED | `src/hooks/useFirstRunState.ts` exports function returning `{ isFirstRun: categories.length === 0 \|\| items.length === 0, loading: catLoading \|\| tmplLoading }`. Derives from `useCategories()` and `useTemplate()` caches. `tsc --noEmit` passes. |
+| 5 | `src/data/presets.ts` contains ~15-20 curated budget items with i18n translation keys | VERIFIED | 19 items (4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment). `en.json` and `de.json` both have `presets` key with 19 slugs across 6 type categories. Both JSON files parse cleanly. |
+
+**Score:** 5/5 truths verified
+
+### Deferred Items
+
+Items not yet met but explicitly addressed in later milestone phases.
+
+| # | Item | Addressed In | Evidence |
+|---|------|-------------|----------|
+| 1 | useFirstRunState not yet consumed by any component | Phase 7 | Phase 7 SC 1: "A new user is automatically redirected to /setup on their first login" -- requires useFirstRunState |
+| 2 | PRESETS/PresetItem not yet imported by any component | Phase 7 | Phase 7 SC 2: "recurring items step shows ~15-20 pre-filled common items" -- consumes PRESETS array |
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `supabase/migrations/006_uniqueness_constraints.sql` | Atomic deduplication + unique constraint DDL | VERIFIED | 29 lines. BEGIN/COMMIT transaction. 2 DISTINCT ON dedup DELETEs. 2 ADD CONSTRAINT statements. |
+| `supabase/migrations/007_setup_completed.sql` | ALTER TABLE + backfill UPDATE | VERIFIED | 18 lines. ADD COLUMN setup_completed boolean NOT NULL DEFAULT false. UPDATE with UNION backfill. |
+| `src/lib/types.ts` | Profile interface with setup_completed | VERIFIED | Line 16: `setup_completed: boolean` present in Profile interface. |
+| `src/data/presets.ts` | PresetItem interface + PRESETS array | VERIFIED | Exports PresetItem interface and PRESETS array with 19 items. No one_off tier values. Pure static module. |
+| `src/i18n/en.json` | English preset translations | VERIFIED | Top-level `presets` key with 6 type groups, 19 total slugs. Valid JSON. |
+| `src/i18n/de.json` | German preset translations | VERIFIED | Top-level `presets` key with 6 type groups, 19 total slugs. Valid JSON. |
+| `src/hooks/useFirstRunState.ts` | Derived first-run state hook | VERIFIED | 28 lines. Exports `useFirstRunState()` returning `{ isFirstRun, loading }`. No direct Supabase calls. |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `007_setup_completed.sql` | profiles table | ALTER TABLE ADD COLUMN | WIRED | `setup_completed boolean NOT NULL DEFAULT false` present |
+| `src/lib/types.ts` | Profile interface | TypeScript field | WIRED | `setup_completed: boolean` on line 16 |
+| `src/data/presets.ts` | `src/lib/types.ts` | `import type { CategoryType }` | WIRED | Line 1 imports CategoryType from types |
+| `src/i18n/en.json` | presets.{type}.{slug} | react-i18next dot-path | WIRED | `"presets"` key present with nested type/slug structure |
+| `src/hooks/useFirstRunState.ts` | `src/hooks/useCategories.ts` | useCategories() call | WIRED | Line 1 import + line 21 invocation |
+| `src/hooks/useFirstRunState.ts` | `src/hooks/useTemplate.ts` | useTemplate() call | WIRED | Line 2 import + line 22 invocation |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|--------------|--------|-------------------|--------|
+| `src/hooks/useFirstRunState.ts` | categories, items | useCategories() cache, useTemplate() cache | Yes -- upstream hooks query Supabase | FLOWING |
+| `src/data/presets.ts` | PRESETS | Static array literal | Yes -- 19 hardcoded items (intentionally static) | FLOWING |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| TypeScript compiles cleanly | `npx tsc --noEmit` | Zero errors (no output) | PASS |
+| Migration 006 has 2 constraints | `grep -c "ADD CONSTRAINT" 006_uniqueness_constraints.sql` | 2 | PASS |
+| Migration 006 is transactional | `grep -c "BEGIN" 006_uniqueness_constraints.sql` | 1 | PASS |
+| Migration 007 has column add | `grep "ADD COLUMN setup_completed" 007_setup_completed.sql` | 1 match | PASS |
+| Migration 007 has backfill | `grep "UPDATE profiles" 007_setup_completed.sql` | 1 match | PASS |
+| Presets has 19 items | `grep -c '{ slug:' src/data/presets.ts` | 19 | PASS |
+| No one_off in presets | `grep "one_off" src/data/presets.ts` | 0 matches | PASS |
+| en.json has 19 preset slugs | node JSON parse + count | 19 | PASS |
+| de.json has 19 preset slugs | node JSON parse + count | 19 | PASS |
+| useFirstRunState exports function | `grep "export function useFirstRunState"` | 1 match | PASS |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-----------|-------------|--------|----------|
+| AUTO-01 | 06-01, 06-03 | Auto-budget uses template on first month visit | SATISFIED (Phase 6 portion) | Budgets unique constraint prevents duplicates; useFirstRunState detects first-run. Full auto-creation in Phase 8. |
+| AUTO-03 | 06-01, 06-02 | Auto-creation uses user's configured currency | SATISFIED (Phase 6 portion) | Preset amounts are plain EUR numbers with no currency symbol. Profile has currency field. Full currency usage in Phase 8. |
+| SETUP-01 | 06-01, 06-03 | New user guided through wizard | SATISFIED (Phase 6 portion) | setup_completed column + backfill identifies existing users. useFirstRunState hook detects new users. Wizard UI in Phase 7. |
+| SETUP-02 | 06-02 | User sees pre-filled common budget items | SATISFIED (Phase 6 portion) | 19 preset items in PRESETS array with en/de translations. Wizard display in Phase 7. |
+
+No orphaned requirements found -- all 4 IDs (AUTO-01, AUTO-03, SETUP-01, SETUP-02) appear in plan frontmatter and are traced to REQUIREMENTS.md.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| (none) | - | - | - | No anti-patterns detected in any phase 6 artifact |
+
+### Human Verification Required
+
+### 1. Budget Unique Constraint Enforcement
+
+**Test:** In Supabase SQL editor, INSERT two budget rows with the same `user_id` and `start_date`.
+**Expected:** Second INSERT fails with error code 23505 (unique_violation).
+**Why human:** Requires running Supabase instance with live DB. Note: User already confirmed DB push succeeded, but runtime constraint rejection is a behavioral check.
+
+### 2. Category Unique Constraint Enforcement
+
+**Test:** In Supabase SQL editor, INSERT two category rows with the same `user_id` and `name`.
+**Expected:** Second INSERT fails with error code 23505 (unique_violation).
+**Why human:** Requires running Supabase instance with live DB.
+
+### 3. Backfill Correctness for Existing Users
+
+**Test:** In Supabase Table Editor, check `profiles` rows for users who existed before migration 007.
+**Expected:** Any user with existing categories or template items has `setup_completed = true`. New test users have `setup_completed = false`.
+**Why human:** Requires inspecting live database state.
+
+### Gaps Summary
+
+No gaps found. All 5 roadmap success criteria are verified at the code/artifact level. Two artifacts (useFirstRunState hook and PRESETS array) are intentionally orphaned -- they are consumed by Phase 7 (Setup Wizard), which is the next phase.
+
+Three items require human verification against the live database: budget constraint enforcement, category constraint enforcement, and backfill correctness. These are behavioral checks that cannot be verified by static code analysis alone.
+
+---
+
+_Verified: 2026-04-20T19:15:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/07-setup-wizard/07-01-PLAN.md

@@ -0,0 +1,461 @@
+---
+phase: 07-setup-wizard
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/pages/SetupPage.tsx
+  - src/hooks/useWizardState.ts
+  - src/components/setup/WizardStepper.tsx
+  - src/components/setup/IncomeStep.tsx
+  - src/components/setup/AllocationBar.tsx
+  - src/components/setup/CategoryGroupHeader.tsx
+  - src/components/setup/PresetItemRow.tsx
+  - src/components/setup/RecurringItemsStep.tsx
+  - src/i18n/en.json
+  - src/i18n/de.json
+autonomous: true
+requirements: [SETUP-01, SETUP-02, SETUP-04]
+
+must_haves:
+  truths:
+    - "SetupPage renders a centered card with WizardStepper showing 3 steps"
+    - "useWizardState persists wizard data to localStorage keyed by userId"
+    - "IncomeStep shows a number input pre-filled with 3000 and profile currency"
+    - "RecurringItemsStep shows all 19 PRESETS grouped by type with checkboxes"
+    - "AllocationBar shows live remaining = income - sum(checked amounts)"
+    - "Bills and variable_expense items are pre-checked by default"
+    - "All wizard i18n keys exist in both en.json and de.json"
+  artifacts:
+    - path: "src/pages/SetupPage.tsx"
+      provides: "Wizard page orchestrator with step rendering"
+      min_lines: 40
+    - path: "src/hooks/useWizardState.ts"
+      provides: "localStorage-synced wizard state management"
+      exports: ["useWizardState"]
+    - path: "src/components/setup/WizardStepper.tsx"
+      provides: "Horizontal 1-2-3 stepper bar"
+      exports: ["WizardStepper"]
+    - path: "src/components/setup/IncomeStep.tsx"
+      provides: "Step 1 income input"
+      exports: ["IncomeStep"]
+    - path: "src/components/setup/RecurringItemsStep.tsx"
+      provides: "Step 2 grouped checklist"
+      exports: ["RecurringItemsStep"]
+    - path: "src/components/setup/AllocationBar.tsx"
+      provides: "Sticky remaining balance bar"
+      exports: ["AllocationBar"]
+    - path: "src/components/setup/PresetItemRow.tsx"
+      provides: "Single checkbox row with amount input"
+      exports: ["PresetItemRow"]
+    - path: "src/components/setup/CategoryGroupHeader.tsx"
+      provides: "Section header with colored dot"
+      exports: ["CategoryGroupHeader"]
+  key_links:
+    - from: "src/pages/SetupPage.tsx"
+      to: "src/hooks/useWizardState.ts"
+      via: "useWizardState(userId) hook call"
+      pattern: "useWizardState"
+    - from: "src/components/setup/RecurringItemsStep.tsx"
+      to: "src/data/presets.ts"
+      via: "import PRESETS"
+      pattern: "import.*PRESETS.*from.*presets"
+---
+
+<objective>
+Build the setup wizard page shell, state management hook, and all UI components for the 3-step wizard (income, recurring items with live allocation, review placeholder).
+
+Purpose: Establishes the wizard's visual structure, localStorage persistence, and all interactive components. Plan 02 will add the ReviewStep and completion/redirect logic on top of this foundation.
+Output: A navigable 3-step wizard at /setup (not yet routed) with working state persistence and live allocation calculation.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-setup-wizard/07-CONTEXT.md
+@.planning/phases/07-setup-wizard/07-RESEARCH.md
+@.planning/phases/07-setup-wizard/07-PATTERNS.md
+@.planning/phases/07-setup-wizard/07-UI-SPEC.md
+
+<interfaces>
+From src/lib/types.ts:
+```typescript
+export type CategoryType = "income" | "bill" | "variable_expense" | "debt" | "saving" | "investment"
+export type ItemTier = "fixed" | "variable" | "one_off"
+export interface Profile { id: string; display_name: string | null; locale: string; currency: string; setup_completed: boolean; ... }
+```
+
+From src/data/presets.ts:
+```typescript
+export interface PresetItem {
+  slug: string
+  type: CategoryType
+  defaultAmount: number
+  item_tier: "fixed" | "variable"
+}
+export const PRESETS: PresetItem[] = [ /* 19 items: 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment */ ]
+```
+
+From src/hooks/useAuth.ts:
+```typescript
+// Returns { user, profile, loading, signIn, signOut, signUp }
+// profile.currency = "EUR" | "USD" | "CHF" etc.
+```
+
+From src/hooks/useCategories.ts:
+```typescript
+export function useCategories(): { categories: Category[]; loading: boolean; create: UseMutationResult; ... }
+// create.mutateAsync({ name: string, type: CategoryType, icon?: string }) => Category
+```
+
+From src/hooks/useTemplate.ts:
+```typescript
+export function useTemplate(): { template: Template | null; items: TemplateItem[]; loading: boolean; createItem: UseMutationResult; ... }
+// createItem.mutateAsync({ category_id: string, item_tier: "fixed"|"variable", budgeted_amount: number }) => TemplateItem
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Install shadcn checkbox + create useWizardState hook + add i18n keys</name>
+  <read_first>
+    - src/i18n/en.json
+    - src/i18n/de.json
+    - src/data/presets.ts
+    - src/hooks/useAuth.ts
+  </read_first>
+  <files>src/hooks/useWizardState.ts, src/i18n/en.json, src/i18n/de.json</files>
+  <action>
+1. Install shadcn checkbox:
+```bash
+npx shadcn@latest add checkbox
+```
+
+2. Create `src/hooks/useWizardState.ts`:
+```typescript
+import { useState, useEffect } from "react"
+import { PRESETS } from "@/data/presets"
+
+export interface WizardState {
+  currentStep: 1 | 2 | 3
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+}
+
+const STORAGE_KEY = (userId: string) => `setup-wizard-${userId}`
+
+function getDefaultState(): WizardState {
+  const selectedItems: Record<string, { checked: boolean; amount: number }> = {}
+  for (const preset of PRESETS) {
+    selectedItems[preset.slug] = {
+      checked: preset.type === "bill" || preset.type === "variable_expense",
+      amount: preset.defaultAmount,
+    }
+  }
+  return { currentStep: 1, income: 3000, selectedItems }
+}
+
+export function useWizardState(userId: string) {
+  const [state, setState] = useState<WizardState>(() => {
+    try {
+      const saved = localStorage.getItem(STORAGE_KEY(userId))
+      if (saved) {
+        const parsed = JSON.parse(saved)
+        // Validate shape
+        if (parsed && typeof parsed.currentStep === "number" && typeof parsed.income === "number" && parsed.selectedItems) {
+          return parsed as WizardState
+        }
+      }
+    } catch { /* ignore corrupt data */ }
+    return getDefaultState()
+  })
+
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY(userId), JSON.stringify(state))
+  }, [state, userId])
+
+  const setStep = (step: 1 | 2 | 3) => setState(s => ({ ...s, currentStep: step }))
+  const setIncome = (income: number) => setState(s => ({ ...s, income }))
+  const toggleItem = (slug: string) => setState(s => ({
+    ...s,
+    selectedItems: {
+      ...s.selectedItems,
+      [slug]: { ...s.selectedItems[slug], checked: !s.selectedItems[slug].checked },
+    },
+  }))
+  const setItemAmount = (slug: string, amount: number) => setState(s => ({
+    ...s,
+    selectedItems: {
+      ...s.selectedItems,
+      [slug]: { ...s.selectedItems[slug], amount },
+    },
+  }))
+  const clearState = () => {
+    localStorage.removeItem(STORAGE_KEY(userId))
+  }
+
+  return { state, setStep, setIncome, toggleItem, setItemAmount, clearState }
+}
+```
+
+3. Add i18n keys to `src/i18n/en.json` — add a `"setup"` object at the top level:
+```json
+"setup": {
+  "title": "Set up your budget",
+  "step1": {
+    "title": "Monthly Income",
+    "description": "How much do you earn each month?",
+    "incomeLabel": "Monthly net income",
+    "helper": "Enter your total monthly take-home pay",
+    "validation": "Please enter a positive income amount"
+  },
+  "step2": {
+    "title": "Recurring Items",
+    "description": "Select your regular monthly expenses",
+    "remaining": "Remaining to allocate"
+  },
+  "step3": {
+    "title": "Review",
+    "description": "Confirm your budget template",
+    "incomeLabel": "Monthly income",
+    "totalLabel": "Total expenses",
+    "remainingLabel": "Remaining",
+    "empty": "No items selected. You can add items to your template later."
+  },
+  "steps": {
+    "1": "Income",
+    "2": "Items",
+    "3": "Review"
+  },
+  "next": "Next Step",
+  "back": "Go Back",
+  "skip": "Skip Step",
+  "skipSetup": "Skip setup",
+  "complete": "Complete Setup",
+  "toast": {
+    "success": "Template created! Your first budget will appear automatically.",
+    "error": "Could not save your template. Please try again.",
+    "partialError": "Some items could not be saved. Check your template page."
+  }
+}
+```
+
+4. Add equivalent German keys to `src/i18n/de.json`:
+```json
+"setup": {
+  "title": "Budget einrichten",
+  "step1": {
+    "title": "Monatliches Einkommen",
+    "description": "Wie viel verdienst du pro Monat?",
+    "incomeLabel": "Monatliches Nettoeinkommen",
+    "helper": "Gib dein monatliches Nettoeinkommen ein",
+    "validation": "Bitte gib einen positiven Betrag ein"
+  },
+  "step2": {
+    "title": "Wiederkehrende Posten",
+    "description": "Wahle deine regelmaigen monatlichen Ausgaben",
+    "remaining": "Verbleibend zu verteilen"
+  },
+  "step3": {
+    "title": "Ubersicht",
+    "description": "Bestatige deine Budgetvorlage",
+    "incomeLabel": "Monatliches Einkommen",
+    "totalLabel": "Gesamtausgaben",
+    "remainingLabel": "Verbleibend",
+    "empty": "Keine Posten ausgewahlt. Du kannst spater Posten zu deiner Vorlage hinzufugen."
+  },
+  "steps": {
+    "1": "Einkommen",
+    "2": "Posten",
+    "3": "Ubersicht"
+  },
+  "next": "Nachster Schritt",
+  "back": "Zuruck",
+  "skip": "Schritt uberspringen",
+  "skipSetup": "Einrichtung uberspringen",
+  "complete": "Einrichtung abschlieen",
+  "toast": {
+    "success": "Vorlage erstellt! Dein erstes Budget wird automatisch erscheinen.",
+    "error": "Vorlage konnte nicht gespeichert werden. Bitte versuche es erneut.",
+    "partialError": "Einige Posten konnten nicht gespeichert werden. Prufe deine Vorlagenseite."
+  }
+}
+```
+  </action>
+  <verify>
+    <automated>grep -q "useWizardState" src/hooks/useWizardState.ts && grep -q '"setup"' src/i18n/en.json && grep -q '"setup"' src/i18n/de.json && ls src/components/ui/checkbox.tsx</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/hooks/useWizardState.ts contains `export function useWizardState(userId: string)`
+    - src/hooks/useWizardState.ts contains `setup-wizard-${userId}`
+    - src/hooks/useWizardState.ts contains `getDefaultState`
+    - src/i18n/en.json contains `"setup.title"` nested under `"setup": { "title":`
+    - src/i18n/en.json contains `"setup.toast.success"` with value "Template created!"
+    - src/i18n/de.json contains `"setup": { "title": "Budget einrichten"`
+    - src/components/ui/checkbox.tsx exists (shadcn installed)
+  </acceptance_criteria>
+  <done>useWizardState hook created with localStorage sync, all setup i18n keys in EN+DE, shadcn checkbox component installed</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create all wizard UI components and SetupPage</name>
+  <read_first>
+    - src/pages/LoginPage.tsx
+    - src/components/dashboard/SummaryStrip.tsx
+    - src/pages/SettingsPage.tsx
+    - src/data/presets.ts
+    - src/hooks/useWizardState.ts
+    - src/components/ui/checkbox.tsx
+  </read_first>
+  <files>src/components/setup/WizardStepper.tsx, src/components/setup/IncomeStep.tsx, src/components/setup/AllocationBar.tsx, src/components/setup/CategoryGroupHeader.tsx, src/components/setup/PresetItemRow.tsx, src/components/setup/RecurringItemsStep.tsx, src/pages/SetupPage.tsx</files>
+  <action>
+Create the following components in `src/components/setup/`:
+
+**1. WizardStepper.tsx:**
+- Props: `currentStep: 1|2|3`, `onStepClick: (step: 1|2|3) => void`
+- Renders 3 circles in a row connected by lines
+- Active step: `bg-primary text-primary-foreground` with number (14px/600)
+- Completed step (step < currentStep): `bg-primary text-primary-foreground` with lucide `Check` icon (16px)
+- Upcoming step (step > currentStep): `bg-muted text-muted-foreground border border-border`
+- Connector line between: `h-px w-16` — completed segment `bg-primary`, upcoming `bg-border`
+- Step labels below circles: text-xs font-semibold, active `text-foreground`, others `text-muted-foreground`
+- Labels from i18n: `t("setup.steps.1")`, `t("setup.steps.2")`, `t("setup.steps.3")`
+- Clicking a completed step or current step calls onStepClick. Future steps: no action, cursor-default.
+- Wrap in `role="navigation" aria-label="Setup progress"`
+- Circle dimensions: `w-8 h-8` (32px)
+- Overall layout: `flex items-center justify-center gap-0` with step groups `flex flex-col items-center gap-1` separated by connector lines
+- Margin below: handled by parent (mb-6)
+
+**2. IncomeStep.tsx:**
+- Props: `income: number`, `onIncomeChange: (val: number) => void`, `currency: string`, `error: string | null`
+- Renders card content for step 1
+- Label: `t("setup.step1.incomeLabel")` (14px/600)
+- Input row: `flex items-center gap-2`
+  - Input: `type="number"`, `className="w-full text-right text-lg"`, value={income}, onChange converts to number
+  - Currency suffix: `<span className="text-muted-foreground text-sm">{currency}</span>`
+- Helper text: `t("setup.step1.helper")` in `text-sm text-muted-foreground`
+- If `error` is truthy: show `<p className="text-sm text-destructive">{error}</p>` below input
+- `aria-describedby` on input pointing to helper and error elements
+
+**3. AllocationBar.tsx:**
+- Props: `remaining: number`, `currency: string`
+- Layout: `sticky top-0 z-10 flex justify-between items-center py-3 px-4 bg-muted border-b border-border rounded-none`
+- Left: `<span className="text-sm font-semibold">{t("setup.step2.remaining")}</span>`
+- Right: formatted amount using `Intl.NumberFormat` with currency
+  - `remaining >= 0`: `className="text-base font-semibold text-on-budget"`
+  - `remaining < 0`: `className="text-base font-semibold text-destructive"`
+- Add `aria-live="polite"` on the amount element
+
+**4. CategoryGroupHeader.tsx:**
+- Props: `type: CategoryType`, `label: string`, `count: number`
+- Layout: `flex items-center gap-2 pt-4 pb-2`
+- Colored dot: `w-2.5 h-2.5 rounded-full` with inline style `backgroundColor: var(--color-${type.replace('_', '-')})`
+  - Map types to CSS vars: income -> `--color-income`, bill -> `--color-bill`, variable_expense -> `--color-variable-expense`, debt -> `--color-debt`, saving -> `--color-saving`, investment -> `--color-investment`
+- Label: `<span className="text-sm font-semibold">{label}</span>`
+- Count: `<span className="text-xs text-muted-foreground">({count} items)</span>`
+- Below: `<Separator />` from shadcn
+
+**5. PresetItemRow.tsx:**
+- Props: `slug: string`, `type: CategoryType`, `checked: boolean`, `amount: number`, `onToggle: () => void`, `onAmountChange: (val: number) => void`
+- Layout: `flex items-center gap-3 py-2.5 px-1`
+- Checkbox: shadcn `<Checkbox checked={checked} onCheckedChange={onToggle} />`
+- Item name: `<span className="flex-1 text-sm">{t(\`presets.${type}.${slug}\`)}</span>`
+- Category badge: `<Badge variant="outline" className="text-xs" style={{ borderLeftWidth: '3px', borderLeftColor: \`var(--color-${type.replace('_', '-')})\` }}>{t(\`categories.types.${type}\`)}</Badge>`
+- Amount input: `<Input type="number" className="w-24 text-right" value={amount} onChange={...} disabled={!checked} />`
+  - When disabled: add `bg-muted text-muted-foreground opacity-50` classes
+
+**6. RecurringItemsStep.tsx:**
+- Props: `selectedItems: Record<string, { checked: boolean; amount: number }>`, `income: number`, `currency: string`, `onToggle: (slug: string) => void`, `onAmountChange: (slug: string, amount: number) => void`
+- Groups PRESETS by type using: `Object.groupBy(PRESETS, (p) => p.type)` — if Object.groupBy not available, use manual reduce
+- Order groups: `["income", "bill", "variable_expense", "debt", "saving", "investment"]`
+- Renders AllocationBar at top (sticky)
+- For each group: CategoryGroupHeader + list of PresetItemRow
+- Wrap each group in `<fieldset>` with `<legend className="sr-only">{groupLabel}</legend>`
+- Compute remaining: `income - sum of all checked items' amounts`
+
+**7. SetupPage.tsx** (page orchestrator):
+- Imports useAuth, useWizardState, useTranslation, WizardStepper, IncomeStep, RecurringItemsStep
+- Gets userId from `useAuth()` -> `user.id`
+- Gets currency from profile: `profile?.currency ?? "EUR"`
+- Uses `useWizardState(userId)` for state management
+- Layout: `<div className="flex min-h-screen items-center justify-center bg-background p-4"><div className="w-full max-w-2xl">`
+- Renders WizardStepper above the card
+- Card: `<Card className="w-full border border-border shadow-sm">`
+  - CardHeader: step title (heading 20px/600) + step description (body 14px/400 text-muted-foreground)
+  - CardContent: renders active step component based on `state.currentStep`
+  - Bottom nav: `flex justify-between items-center pt-4 border-t border-border`
+    - Left side: Go Back button (variant="ghost", hidden on step 1) + Skip Step button (variant="ghost" text-muted-foreground)
+    - Right side: Next Step button (variant="default")
+- Step 1 Next: validates income > 0, shows error if invalid, otherwise advances to step 2
+- Step 2 Next: no validation, advances to step 3
+- Step 3: shows placeholder text "Review step coming in next plan" (will be replaced in Plan 02)
+- Below card: "Skip setup" link: `<button className="mt-4 text-sm text-muted-foreground underline block mx-auto">{t("setup.skipSetup")}</button>`
+- Skip step on step 1: advance to step 2. Skip step on step 2: advance to step 3.
+- Clicking completed stepper steps calls `setStep(step)`
+  </action>
+  <verify>
+    <automated>ls src/components/setup/WizardStepper.tsx src/components/setup/IncomeStep.tsx src/components/setup/AllocationBar.tsx src/components/setup/CategoryGroupHeader.tsx src/components/setup/PresetItemRow.tsx src/components/setup/RecurringItemsStep.tsx src/pages/SetupPage.tsx && npx tsc --noEmit 2>&1 | head -30</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/pages/SetupPage.tsx contains `useWizardState` and `max-w-2xl`
+    - src/pages/SetupPage.tsx contains `currentStep` conditional rendering
+    - src/components/setup/WizardStepper.tsx contains `role="navigation"` and `aria-label`
+    - src/components/setup/WizardStepper.tsx contains `w-8 h-8`
+    - src/components/setup/IncomeStep.tsx contains `type="number"` and `text-lg`
+    - src/components/setup/AllocationBar.tsx contains `aria-live="polite"` and `sticky top-0`
+    - src/components/setup/CategoryGroupHeader.tsx contains `w-2.5 h-2.5 rounded-full`
+    - src/components/setup/PresetItemRow.tsx contains `Checkbox` import and `w-24`
+    - src/components/setup/RecurringItemsStep.tsx imports `PRESETS` from `@/data/presets`
+    - TypeScript compiles without errors (`npx tsc --noEmit` exits 0)
+  </acceptance_criteria>
+  <done>All 7 wizard UI components render correctly, TypeScript compiles without errors, wizard navigates between steps 1 and 2 with working state persistence</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| localStorage -> component | Persisted wizard data read back into React state |
+| client -> Supabase (future Plan 02) | Category/template item creation on completion |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-07-01 | Tampering | useWizardState localStorage read | mitigate | Validate JSON shape on load: check currentStep is 1-3, income is number, selectedItems is object with expected structure. Fall back to defaults on invalid data. |
+| T-07-02 | Information Disclosure | localStorage key | accept | Key includes userId, preventing cross-user data leakage. Data is non-sensitive (income amount, item selections). |
+| T-07-03 | Spoofing | Preset data | accept | PRESETS are hardcoded source constants, not user input. i18n keys resolve from bundled JSON, no injection vector. |
+</threat_model>
+
+<verification>
+- `npx tsc --noEmit` passes (no type errors)
+- All 7 component files exist in src/components/setup/ and src/pages/
+- useWizardState stores and retrieves state from localStorage
+- i18n keys resolve for both "en" and "de" locales
+</verification>
+
+<success_criteria>
+- SetupPage renders with WizardStepper showing 3 steps
+- Step 1 shows income input pre-filled with 3000 and currency suffix
+- Step 2 shows all 19 PRESETS grouped by type with checkboxes and editable amounts
+- Bills (4) and variable_expense (5) items are checked by default
+- AllocationBar shows remaining = 3000 - sum(checked) and turns red when negative
+- Navigating between steps preserves state
+- Refreshing the page restores wizard at correct step (localStorage)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-setup-wizard/07-01-SUMMARY.md`
+</output>

.planning/phases/07-setup-wizard/07-01-SUMMARY.md

@@ -0,0 +1,86 @@
+---
+phase: 07-setup-wizard
+plan: 01
+subsystem: frontend/setup-wizard
+tags: [wizard, ui, state-management, i18n]
+dependency_graph:
+  requires: [src/data/presets.ts, src/lib/types.ts, src/hooks/useAuth.ts]
+  provides: [src/hooks/useWizardState.ts, src/pages/SetupPage.tsx, src/components/setup/*]
+  affects: [src/i18n/en.json, src/i18n/de.json]
+tech_stack:
+  added: [shadcn/checkbox]
+  patterns: [localStorage-synced-state, multi-step-wizard, grouped-preset-checklist]
+key_files:
+  created:
+    - src/hooks/useWizardState.ts
+    - src/components/setup/WizardStepper.tsx
+    - src/components/setup/IncomeStep.tsx
+    - src/components/setup/AllocationBar.tsx
+    - src/components/setup/CategoryGroupHeader.tsx
+    - src/components/setup/PresetItemRow.tsx
+    - src/components/setup/RecurringItemsStep.tsx
+    - src/pages/SetupPage.tsx
+    - src/components/ui/checkbox.tsx
+  modified:
+    - src/i18n/en.json
+    - src/i18n/de.json
+decisions:
+  - "Profile fetched inline in SetupPage (same pattern as SettingsPage) since useAuth does not expose profile"
+  - "Used manual reduce for grouping PRESETS by type for broad browser compatibility"
+metrics:
+  duration: 178s
+  completed: 2026-04-20T19:06:36Z
+  tasks_completed: 2
+  tasks_total: 2
+  files_created: 9
+  files_modified: 2
+---
+
+# Phase 07 Plan 01: Setup Wizard UI Shell Summary
+
+LocalStorage-synced 3-step wizard with income input, grouped preset checklist (19 items), live allocation bar, and horizontal stepper navigation.
+
+## Commits
+
+| Task | Commit | Description |
+|------|--------|-------------|
+| 1 | bbcb07f | useWizardState hook, i18n keys (EN+DE), shadcn checkbox |
+| 2 | e141197 | All 7 wizard UI components and SetupPage orchestrator |
+
+## What Was Built
+
+1. **useWizardState hook** - Manages wizard step, income, and item selections in localStorage keyed by userId. Validates JSON shape on load (T-07-01 mitigation). Bills and variable_expense items pre-checked by default.
+
+2. **WizardStepper** - Horizontal 1-2-3 stepper with circles, connector lines, and step labels. Completed steps are clickable; future steps are disabled.
+
+3. **IncomeStep** - Number input pre-filled with 3000, currency suffix from profile, helper text, and inline validation error display.
+
+4. **AllocationBar** - Sticky bar showing remaining = income - sum(checked amounts). Green when positive, red (destructive) when negative. aria-live="polite" for screen readers.
+
+5. **CategoryGroupHeader** - Colored dot + label + item count for each of the 6 category types.
+
+6. **PresetItemRow** - Checkbox + preset name (i18n) + category badge with colored border + editable amount input (disabled when unchecked).
+
+7. **RecurringItemsStep** - Groups all 19 PRESETS into 6 category sections with AllocationBar at top.
+
+8. **SetupPage** - Page orchestrator: centered card layout (max-w-2xl), loads profile for currency, renders stepper + active step, handles Next/Back/Skip navigation with income validation.
+
+## i18n
+
+All wizard copy added under `setup.*` namespace in both `en.json` and `de.json` (35 keys each). German translations use proper umlauts and natural phrasing.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Known Stubs
+
+| File | Line | Stub | Reason |
+|------|------|------|--------|
+| src/pages/SetupPage.tsx | Step 3 content | "Review step coming in next plan" placeholder | Plan 02 will implement ReviewStep and completion logic |
+| src/pages/SetupPage.tsx | Skip setup button | No-op onClick | Plan 02 will wire skip to mark setup_completed and redirect |
+| src/pages/SetupPage.tsx | Complete button | Disabled, no handler | Plan 02 will implement completion sequence |
+
+These stubs are intentional -- Plan 02 explicitly owns the ReviewStep, completion logic, routing, and redirect.
+
+## Self-Check: PASSED

.planning/phases/07-setup-wizard/07-02-PLAN.md

@@ -0,0 +1,392 @@
+---
+phase: 07-setup-wizard
+plan: 02
+type: execute
+wave: 2
+depends_on: [07-01]
+files_modified:
+  - src/components/setup/ReviewStep.tsx
+  - src/pages/SetupPage.tsx
+  - src/App.tsx
+  - src/pages/DashboardPage.tsx
+autonomous: true
+requirements: [SETUP-01, SETUP-03, SETUP-05]
+
+must_haves:
+  truths:
+    - "ReviewStep shows read-only summary of income + selected items grouped by type + totals"
+    - "/setup route is protected and renders SetupPage outside AppLayout"
+    - "DashboardPage redirects first-run users to /setup via useFirstRunState"
+    - "Completing wizard creates categories then template items and redirects to dashboard"
+    - "Skip setup clears localStorage, marks setup_completed=true, redirects to dashboard"
+    - "Complete button is disabled during API calls to prevent double-submit"
+  artifacts:
+    - path: "src/components/setup/ReviewStep.tsx"
+      provides: "Read-only summary of wizard selections"
+      exports: ["ReviewStep"]
+    - path: "src/App.tsx"
+      provides: "/setup route registration"
+      contains: "path=\"/setup\""
+    - path: "src/pages/DashboardPage.tsx"
+      provides: "First-run redirect to /setup"
+      contains: "useFirstRunState"
+  key_links:
+    - from: "src/pages/DashboardPage.tsx"
+      to: "src/hooks/useFirstRunState.ts"
+      via: "useFirstRunState() -> isFirstRun -> Navigate to /setup"
+      pattern: "isFirstRun.*Navigate.*setup"
+    - from: "src/pages/SetupPage.tsx"
+      to: "src/hooks/useCategories.ts"
+      via: "create.mutateAsync on wizard completion"
+      pattern: "create\\.mutateAsync"
+    - from: "src/pages/SetupPage.tsx"
+      to: "src/hooks/useTemplate.ts"
+      via: "createItem.mutateAsync on wizard completion"
+      pattern: "createItem\\.mutateAsync"
+    - from: "src/App.tsx"
+      to: "src/pages/SetupPage.tsx"
+      via: "Route path=/setup element=SetupPage"
+      pattern: "path=.*/setup"
+---
+
+<objective>
+Add the ReviewStep component, wire wizard completion logic (creating categories + template items), add skip functionality, register the /setup route, and add first-run redirect in DashboardPage.
+
+Purpose: Completes the wizard end-to-end — a new user is redirected to /setup, can navigate all 3 steps, and either completes (creating template data) or skips.
+Output: Fully functional setup wizard accessible via /setup with working completion and skip flows.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-setup-wizard/07-CONTEXT.md
+@.planning/phases/07-setup-wizard/07-RESEARCH.md
+@.planning/phases/07-setup-wizard/07-PATTERNS.md
+@.planning/phases/07-setup-wizard/07-UI-SPEC.md
+@.planning/phases/07-setup-wizard/07-01-SUMMARY.md
+
+<interfaces>
+From src/hooks/useWizardState.ts (created in Plan 01):
+```typescript
+export interface WizardState {
+  currentStep: 1 | 2 | 3
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+}
+export function useWizardState(userId: string): {
+  state: WizardState
+  setStep: (step: 1 | 2 | 3) => void
+  setIncome: (income: number) => void
+  toggleItem: (slug: string) => void
+  setItemAmount: (slug: string, amount: number) => void
+  clearState: () => void
+}
+```
+
+From src/hooks/useCategories.ts:
+```typescript
+// create.mutateAsync({ name: string, type: CategoryType, icon?: string }) => Category { id, ... }
+```
+
+From src/hooks/useTemplate.ts:
+```typescript
+// createItem.mutateAsync({ category_id: string, item_tier: "fixed"|"variable", budgeted_amount: number }) => TemplateItem
+// Template auto-creates on first useTemplate() query
+```
+
+From src/hooks/useFirstRunState.ts:
+```typescript
+export function useFirstRunState(): { isFirstRun: boolean; loading: boolean }
+```
+
+From src/data/presets.ts:
+```typescript
+export const PRESETS: PresetItem[] // 19 items with slug, type, defaultAmount, item_tier
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create ReviewStep + wire completion/skip logic into SetupPage</name>
+  <read_first>
+    - src/pages/SetupPage.tsx
+    - src/hooks/useCategories.ts
+    - src/hooks/useTemplate.ts
+    - src/hooks/useWizardState.ts
+    - src/data/presets.ts
+    - src/lib/supabase.ts
+  </read_first>
+  <files>src/components/setup/ReviewStep.tsx, src/pages/SetupPage.tsx</files>
+  <action>
+**1. Create `src/components/setup/ReviewStep.tsx`:**
+
+Props: `income: number`, `selectedItems: Record<string, { checked: boolean; amount: number }>`, `currency: string`
+
+Layout:
+- Income row: `flex justify-between py-2` — left: `t("setup.step3.incomeLabel")` (14px/600), right: formatted income (14px/600)
+- `<Separator />`
+- Group checked items by type (same order: income, bill, variable_expense, debt, saving, investment). Only show groups that have at least one checked item.
+- For each group: render CategoryGroupHeader (import from `./CategoryGroupHeader`), then for each checked item in group: `<div className="flex justify-between py-1.5 px-1"><span className="text-sm">{t(\`presets.${type}.${slug}\`)}</span><span className="text-sm text-right">{formattedAmount}</span></div>`
+- `<Separator />`
+- Totals: `space-y-1 pt-2`
+  - Total expenses row: `flex justify-between` with label `t("setup.step3.totalLabel")` (14px/600) and sum of checked amounts
+  - Remaining row: `flex justify-between` with label `t("setup.step3.remainingLabel")` (16px/600), value colored `text-on-budget` if >= 0, `text-destructive` if < 0
+- If no items checked: show `<p className="text-sm text-muted-foreground py-4">{t("setup.step3.empty")}</p>` instead of groups
+
+Use `Intl.NumberFormat` with `style: "currency"` and the `currency` prop for all amount formatting.
+
+Import PRESETS from `@/data/presets` to map slugs to types for grouping.
+
+**2. Update `src/pages/SetupPage.tsx` to add:**
+
+a) Import ReviewStep, useCategories, useTemplate, useQueryClient, toast (from sonner), supabase (from @/lib/supabase), Navigate (from react-router-dom), useNavigate
+
+b) Add `completing` state: `const [completing, setCompleting] = useState(false)`
+
+c) Replace the step 3 placeholder with `<ReviewStep income={state.income} selectedItems={state.selectedItems} currency={currency} />`
+
+d) Change the right-side button on step 3 from "Next Step" to "Complete Setup" (`t("setup.complete")`), disabled when `completing`
+
+e) Add completion handler `handleComplete`:
+```typescript
+async function handleComplete() {
+  setCompleting(true)
+  try {
+    const queryClient = useQueryClient() // already declared at top
+    const checkedItems = PRESETS.filter(p => state.selectedItems[p.slug]?.checked)
+    
+    // 1. Determine unique category types needed
+    const typesNeeded = [...new Set(checkedItems.map(i => i.type))]
+    
+    // 2. Create one category per type (use i18n label as name)
+    const categoryMap: Record<string, string> = {}
+    for (const type of typesNeeded) {
+      try {
+        const cat = await create.mutateAsync({ name: t(`categories.types.${type}`), type })
+        categoryMap[type] = cat.id
+      } catch (e: any) {
+        // Unique constraint violation (23505) = category already exists, fetch it
+        if (e?.code === "23505" || e?.message?.includes("duplicate")) {
+          const existing = categories.find(c => c.type === type)
+          if (existing) categoryMap[type] = existing.id
+        } else {
+          throw e
+        }
+      }
+    }
+    
+    // 3. If categories were fetched from cache but not found, refetch
+    if (Object.keys(categoryMap).length < typesNeeded.length) {
+      await queryClient.invalidateQueries({ queryKey: ["categories"] })
+      // Remaining types need fresh data — handled by the existing entries
+    }
+    
+    // 4. Create template items for each checked preset
+    let partialFailure = false
+    for (const item of checkedItems) {
+      try {
+        await createItem.mutateAsync({
+          category_id: categoryMap[item.type],
+          item_tier: item.item_tier,
+          budgeted_amount: state.selectedItems[item.slug].amount,
+        })
+      } catch {
+        partialFailure = true
+      }
+    }
+    
+    // 5. Mark setup complete
+    await supabase.from("profiles").update({ setup_completed: true }).eq("id", user!.id)
+    
+    // 6. Clear wizard state
+    clearState()
+    
+    // 7. Invalidate queries to prevent redirect loop
+    await queryClient.invalidateQueries({ queryKey: ["categories"] })
+    await queryClient.invalidateQueries({ queryKey: ["template-items"] })
+    
+    // 8. Toast and redirect
+    if (partialFailure) {
+      toast.error(t("setup.toast.partialError"))
+    } else {
+      toast.success(t("setup.toast.success"))
+    }
+    navigate("/", { replace: true })
+  } catch {
+    toast.error(t("setup.toast.error"))
+  } finally {
+    setCompleting(false)
+  }
+}
+```
+
+f) Add skip handler `handleSkipSetup`:
+```typescript
+async function handleSkipSetup() {
+  clearState()
+  await supabase.from("profiles").update({ setup_completed: true }).eq("id", user!.id)
+  navigate("/", { replace: true })
+}
+```
+
+g) Wire "Skip setup" button below card to call `handleSkipSetup`
+
+h) Wire "Skip Step" on step 3 to also call `handleSkipSetup` (per UI-SPEC: "On step 3 skip: same as Skip setup")
+
+i) Disable Go Back, Skip Step, and Complete Setup buttons when `completing` is true
+
+j) Add `useCategories()` call at component top level to get `create` mutation and `categories` array. Add `useTemplate()` to ensure template row exists before completion (Pitfall 5).
+
+k) Get `useQueryClient()` at component top level (not inside handler).
+  </action>
+  <verify>
+    <automated>grep -q "ReviewStep" src/components/setup/ReviewStep.tsx && grep -q "handleComplete" src/pages/SetupPage.tsx && grep -q "setup_completed.*true" src/pages/SetupPage.tsx && grep -q "clearState" src/pages/SetupPage.tsx && npx tsc --noEmit 2>&1 | head -20</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/components/setup/ReviewStep.tsx contains `t("setup.step3.incomeLabel")` and `Intl.NumberFormat`
+    - src/components/setup/ReviewStep.tsx contains `text-on-budget` and `text-destructive` conditional
+    - src/pages/SetupPage.tsx contains `async function handleComplete`
+    - src/pages/SetupPage.tsx contains `create.mutateAsync` (category creation)
+    - src/pages/SetupPage.tsx contains `createItem.mutateAsync` (template item creation)
+    - src/pages/SetupPage.tsx contains `setup_completed: true` (profile update)
+    - src/pages/SetupPage.tsx contains `handleSkipSetup` function
+    - src/pages/SetupPage.tsx contains `setCompleting(true)` (double-click prevention)
+    - src/pages/SetupPage.tsx contains `toast.success` and `toast.error`
+    - src/pages/SetupPage.tsx contains `invalidateQueries.*categories` (redirect loop prevention)
+    - TypeScript compiles without errors
+  </acceptance_criteria>
+  <done>ReviewStep renders read-only grouped summary. Completion creates categories + template items, handles duplicates, clears state, marks setup_completed, toasts, and redirects. Skip exits without creating data.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Register /setup route in App.tsx + add first-run redirect in DashboardPage</name>
+  <read_first>
+    - src/App.tsx
+    - src/pages/DashboardPage.tsx
+    - src/hooks/useFirstRunState.ts
+  </read_first>
+  <files>src/App.tsx, src/pages/DashboardPage.tsx</files>
+  <action>
+**1. Update `src/App.tsx`:**
+
+Add import at top:
+```typescript
+import SetupPage from "@/pages/SetupPage"
+```
+
+Add the /setup route AFTER the public routes (login, register) and BEFORE the AppLayout route. It must be inside a ProtectedRoute but NOT inside AppLayout:
+```typescript
+<Route
+  path="/setup"
+  element={
+    <ProtectedRoute>
+      <SetupPage />
+    </ProtectedRoute>
+  }
+/>
+```
+
+Insert this between the `</Route>` closing the register route (around line 46) and the `<Route element={<ProtectedRoute><AppLayout /></ProtectedRoute>}>` line (around line 47).
+
+**2. Update `src/pages/DashboardPage.tsx`:**
+
+Add imports at top (after existing imports):
+```typescript
+import { useFirstRunState } from "@/hooks/useFirstRunState"
+import { Navigate } from "react-router-dom"
+```
+
+Note: `Navigate` may already be imported — check before adding a duplicate.
+
+Inside the DashboardPage component function, add early returns BEFORE any existing logic (before the existing useState/useMemo calls):
+```typescript
+const { isFirstRun, loading: firstRunLoading } = useFirstRunState()
+
+if (firstRunLoading) return <DashboardSkeleton />
+if (isFirstRun) return <Navigate to="/setup" replace />
+```
+
+This uses the existing `DashboardSkeleton` component (already imported) as the loading fallback.
+  </action>
+  <verify>
+    <automated>grep -q 'path="/setup"' src/App.tsx && grep -q "SetupPage" src/App.tsx && grep -q "useFirstRunState" src/pages/DashboardPage.tsx && grep -q 'Navigate to="/setup"' src/pages/DashboardPage.tsx && npx tsc --noEmit 2>&1 | head -20</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/App.tsx contains `import SetupPage from "@/pages/SetupPage"`
+    - src/App.tsx contains `path="/setup"` within a `<ProtectedRoute>` wrapper
+    - src/App.tsx has /setup route BEFORE the AppLayout route (not nested inside it)
+    - src/pages/DashboardPage.tsx contains `import { useFirstRunState } from "@/hooks/useFirstRunState"`
+    - src/pages/DashboardPage.tsx contains `const { isFirstRun, loading: firstRunLoading } = useFirstRunState()`
+    - src/pages/DashboardPage.tsx contains `if (isFirstRun) return <Navigate to="/setup" replace />`
+    - src/pages/DashboardPage.tsx contains `if (firstRunLoading) return <DashboardSkeleton />`
+    - TypeScript compiles without errors
+  </acceptance_criteria>
+  <done>/setup route registered as protected standalone page. First-run users are redirected from dashboard to /setup. Existing users with categories/template data see the normal dashboard.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Complete 3-step setup wizard with income entry, recurring items checklist (19 presets), review step, completion logic (category + template creation), skip functionality, and first-run redirect from dashboard.</what-built>
+  <how-to-verify>
+    1. Create a new test user (or clear an existing user's categories and template items in Supabase)
+    2. Log in with the test user — should be redirected to `/setup`
+    3. Step 1: Verify income input shows 3000 pre-filled with EUR suffix. Try Next with empty/0 value (should show validation error). Enter 4000, click Next.
+    4. Step 2: Verify Bills (4) and Variable Expenses (5) are pre-checked. Verify allocation bar shows "Remaining to allocate: X" (4000 - sum of checked). Uncheck an item — verify amount updates. Check an item — verify it enables the amount input.
+    5. Step 3: Verify read-only summary shows income, grouped checked items, totals, and remaining.
+    6. Click "Complete Setup" — verify toast appears, redirected to dashboard, template page shows created items.
+    7. Refresh dashboard — should NOT redirect back to /setup (setup_completed=true, and categories exist).
+    8. Test "Skip setup" link — create another fresh user, click "Skip setup" from step 1. Verify redirect to dashboard with no data created.
+    9. Test localStorage persistence: start wizard, enter income, advance to step 2, refresh page — verify wizard resumes at step 2 with entered income.
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe any issues found</resume-signal>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| client -> Supabase | Category and template item inserts on completion |
+| localStorage -> component | Wizard state restoration (validated in Plan 01) |
+| React Query cache -> redirect logic | isFirstRun depends on cache freshness |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-07-04 | Denial of Service | handleComplete double-click | mitigate | `completing` state disables button immediately on click. DB unique constraints on categories prevent duplicate rows. |
+| T-07-05 | Tampering | Supabase profile update (setup_completed) | accept | RLS policy restricts updates to own profile row. Client can only set own setup_completed. |
+| T-07-06 | Elevation of Privilege | /setup route access | mitigate | Route wrapped in ProtectedRoute — unauthenticated users redirected to /login. |
+| T-07-07 | Denial of Service | Redirect loop (dashboard <-> /setup) | mitigate | After completion, invalidate ["categories"] and ["template-items"] queries before redirect. useFirstRunState will read fresh data showing isFirstRun=false. |
+</threat_model>
+
+<verification>
+- `npx tsc --noEmit` passes
+- Navigating to /setup while unauthenticated redirects to /login
+- A user with zero categories sees /setup after login
+- Completing wizard creates categories + template items in database
+- Skipping wizard sets setup_completed=true without creating data
+- Refreshing mid-wizard restores state from localStorage
+- No redirect loop after completion
+</verification>
+
+<success_criteria>
+- New user flow: login -> auto-redirect to /setup -> 3 steps -> complete -> dashboard with template
+- Skip flow: /setup -> skip -> dashboard (no data created, setup_completed=true)
+- Existing user flow: login -> dashboard (no redirect to /setup)
+- No duplicate categories on repeated completion attempts
+- No infinite redirect loop between dashboard and /setup
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-setup-wizard/07-02-SUMMARY.md`
+</output>

.planning/phases/07-setup-wizard/07-02-SUMMARY.md

@@ -0,0 +1,74 @@
+---
+phase: 07-setup-wizard
+plan: 02
+subsystem: frontend/setup-wizard
+tags: [wizard, completion, routing, first-run-redirect]
+dependency_graph:
+  requires: [src/hooks/useWizardState.ts, src/hooks/useCategories.ts, src/hooks/useTemplate.ts, src/hooks/useFirstRunState.ts, src/data/presets.ts]
+  provides: [src/components/setup/ReviewStep.tsx, /setup route, first-run redirect]
+  affects: [src/pages/SetupPage.tsx, src/App.tsx, src/pages/DashboardPage.tsx]
+tech_stack:
+  added: []
+  patterns: [wizard-completion-flow, category-dedup-on-constraint, query-invalidation-before-redirect]
+key_files:
+  created:
+    - src/components/setup/ReviewStep.tsx
+  modified:
+    - src/pages/SetupPage.tsx
+    - src/App.tsx
+    - src/pages/DashboardPage.tsx
+decisions:
+  - "Moved hook calls above early returns in DashboardPage to comply with React rules of hooks"
+  - "Skip on step 3 calls same handleSkipSetup as global skip (per UI-SPEC)"
+metrics:
+  duration: 145s
+  completed: 2026-04-20T19:10:45Z
+  tasks_completed: 2
+  tasks_total: 2
+  files_created: 1
+  files_modified: 3
+---
+
+# Phase 07 Plan 02: Setup Wizard Completion and Routing Summary
+
+ReviewStep with grouped read-only summary, wizard completion logic (category + template item creation with duplicate handling), skip flow, /setup route registration, and first-run redirect from dashboard.
+
+## Commits
+
+| Task | Commit | Description |
+|------|--------|-------------|
+| 1 | 396d342 | ReviewStep component and wizard completion/skip logic |
+| 2 | 6b75f14 | Register /setup route and add first-run redirect |
+
+## What Was Built
+
+1. **ReviewStep** - Read-only summary component showing income, grouped checked items by category type, total expenses, and remaining balance. Uses Intl.NumberFormat for currency formatting. Remaining is colored green (text-on-budget) when positive, red (text-destructive) when negative.
+
+2. **Wizard Completion Logic** - handleComplete creates one category per needed type (handles 23505 duplicate constraint), creates template items for all checked presets, marks profiles.setup_completed=true, clears localStorage wizard state, invalidates React Query cache, shows toast, and redirects to dashboard.
+
+3. **Skip Flow** - handleSkipSetup clears localStorage, marks setup_completed=true without creating any data, and redirects to dashboard.
+
+4. **Double-submit Prevention** - `completing` state disables all buttons during API calls (T-07-04 mitigation).
+
+5. **/setup Route** - Registered in App.tsx as a protected standalone page (inside ProtectedRoute, outside AppLayout). Unauthenticated users are redirected to /login (T-07-06 mitigation).
+
+6. **First-run Redirect** - DashboardPage uses useFirstRunState to detect users with no categories/template items and redirects them to /setup. Shows DashboardSkeleton during loading.
+
+7. **Redirect Loop Prevention** - Query invalidation for ["categories"] and ["template-items"] after completion ensures useFirstRunState reads fresh data showing isFirstRun=false (T-07-07 mitigation).
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed React hooks rule violation in DashboardPage**
+- **Found during:** Task 2
+- **Issue:** Plan instructed placing early returns before useMonthParam/useBudgets calls, which violates React rules of hooks (hooks cannot be called conditionally)
+- **Fix:** Moved all hook calls (useMonthParam, useBudgets, useMemo) above the early return statements
+- **Files modified:** src/pages/DashboardPage.tsx
+- **Commit:** 6b75f14
+
+## Known Stubs
+
+None - all stubs from Plan 01 have been resolved.
+
+## Self-Check: PASSED

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

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

@@ -0,0 +1,284 @@
+# Phase 7: Setup Wizard - Pattern Map
+
+**Mapped:** 2026-04-20
+**Files analyzed:** 9
+**Analogs found:** 9 / 9
+
+## File Classification
+
+| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|-------------------|------|-----------|----------------|---------------|
+| `src/pages/SetupPage.tsx` | page | request-response | `src/pages/LoginPage.tsx` | exact |
+| `src/components/setup/WizardStepper.tsx` | component | transform | `src/components/dashboard/SummaryStrip.tsx` | role-match |
+| `src/components/setup/IncomeStep.tsx` | component | request-response | `src/pages/SettingsPage.tsx` (form section) | role-match |
+| `src/components/setup/RecurringItemsStep.tsx` | component | transform | `src/pages/DashboardPage.tsx` (grouped data) | partial |
+| `src/components/setup/ReviewStep.tsx` | component | transform | `src/components/dashboard/SummaryStrip.tsx` | role-match |
+| `src/components/setup/AllocationBar.tsx` | component | transform | `src/components/dashboard/StatCard.tsx` | role-match |
+| `src/components/setup/PresetItemRow.tsx` | component | request-response | `src/components/dashboard/CategorySection.tsx` | partial |
+| `src/App.tsx` (modify) | route | request-response | `src/App.tsx` (existing) | exact |
+| `src/pages/DashboardPage.tsx` (modify) | page | request-response | `src/pages/DashboardPage.tsx` (existing) | exact |
+
+## Pattern Assignments
+
+### `src/pages/SetupPage.tsx` (page, request-response)
+
+**Analog:** `src/pages/LoginPage.tsx`
+
+**Imports pattern** (lines 1-9):
+```typescript
+import { useState } from "react"
+import { Link, useNavigate } from "react-router-dom"
+import { useTranslation } from "react-i18next"
+import { useAuth } from "@/hooks/useAuth"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
+```
+
+**Page layout pattern** (lines 34-36):
+```typescript
+// Standalone centered card outside AppLayout -- same pattern as LoginPage
+return (
+  <div className="flex min-h-screen items-center justify-center bg-muted/60 p-4">
+    <Card className="w-full max-w-sm border-t-4 border-t-primary shadow-lg">
+```
+
+**Async action with loading state** (lines 20-31):
+```typescript
+const [loading, setLoading] = useState(false)
+
+async function handleSubmit(e: React.FormEvent) {
+  e.preventDefault()
+  setError("")
+  setLoading(true)
+  try {
+    await signIn(email, password)
+    navigate("/")
+  } catch (err) {
+    setError(err instanceof Error ? err.message : t("common.error"))
+  } finally {
+    setLoading(false)
+  }
+}
+```
+
+**Key adaptation:** SetupPage uses `max-w-2xl` (not `max-w-sm`) per CONTEXT decision. It manages multi-step state internally with useState + localStorage sync.
+
+---
+
+### `src/components/setup/IncomeStep.tsx` (component, request-response)
+
+**Analog:** `src/pages/SettingsPage.tsx` (form input section)
+
+**Form field pattern** (lines 88-96):
+```typescript
+<div className="space-y-2">
+  <Label>{t("settings.displayName")}</Label>
+  <Input
+    value={profile?.display_name ?? ""}
+    onChange={(e) =>
+      setProfile((p) => p && { ...p, display_name: e.target.value })
+    }
+  />
+</div>
+```
+
+**Button with disabled state** (line 133):
+```typescript
+<Button onClick={handleSave} disabled={saving}>
+  {t("settings.save")}
+</Button>
+```
+
+---
+
+### `src/components/setup/WizardStepper.tsx` (component, transform)
+
+**Analog:** `src/components/dashboard/SummaryStrip.tsx`
+
+**Presentational component pattern** (lines 1-16):
+```typescript
+// Props interface with clear typing, named export, no hooks beyond props
+interface SummaryStripProps {
+  income: { value: string; budgeted: string }
+  expenses: { value: string; budgeted: string }
+  balance: { value: string; isPositive: boolean }
+  t: (key: string) => string
+}
+
+export function SummaryStrip({ income, expenses, balance, t }: SummaryStripProps) {
+  return (
+    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      {/* child components */}
+    </div>
+  )
+}
+```
+
+**Key adaptation:** WizardStepper accepts `currentStep: 1|2|3` and `onStepClick: (step) => void` props. Renders 3 numbered circles with connecting lines.
+
+---
+
+### `src/components/setup/RecurringItemsStep.tsx` (component, transform)
+
+**Analog:** `src/pages/DashboardPage.tsx` (grouped items pattern)
+
+**Grouping by category type** (lines 138-155):
+```typescript
+const groupedSections = useMemo(() =>
+  CATEGORY_TYPES_ALL
+    .map((type) => {
+      const groupItems = items.filter((i) => i.category?.type === type)
+      if (groupItems.length === 0) return null
+      return {
+        type,
+        label: t(`categories.types.${type}`),
+        items: groupItems,
+      }
+    })
+    .filter((g): g is NonNullable<typeof g> => g !== null),
+  [items, t]
+)
+```
+
+**Key adaptation:** Groups PRESETS by `type` field. Each group has a header and list of PresetItemRow components.
+
+---
+
+### `src/components/setup/AllocationBar.tsx` (component, transform)
+
+**Analog:** `src/components/dashboard/SummaryStrip.tsx`
+
+**Conditional color class pattern** (line 47):
+```typescript
+valueClassName={balance.isPositive ? "text-on-budget" : "text-over-budget"}
+```
+
+**Key adaptation:** Displays "Remaining: {amount}" with red text when negative. Uses sticky positioning.
+
+---
+
+### `src/App.tsx` (modify - add /setup route)
+
+**Existing routing pattern** (lines 28-65):
+```typescript
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<PublicRoute><LoginPage /></PublicRoute>} />
+      <Route path="/register" element={<PublicRoute><RegisterPage /></PublicRoute>} />
+      {/* Add /setup here -- protected but outside AppLayout */}
+      <Route element={<ProtectedRoute><AppLayout /></ProtectedRoute>}>
+        <Route index element={<DashboardPage />} />
+        ...
+      </Route>
+      <Route path="*" element={<Navigate to="/" replace />} />
+    </Routes>
+  )
+}
+```
+
+**New route insertion point** -- after public routes, before AppLayout route:
+```typescript
+<Route path="/setup" element={<ProtectedRoute><SetupPage /></ProtectedRoute>} />
+```
+
+---
+
+### `src/pages/DashboardPage.tsx` (modify - add first-run redirect)
+
+**Pattern to add** (at top of DashboardPage component, before existing logic):
+```typescript
+// Source: useFirstRunState hook (src/hooks/useFirstRunState.ts)
+import { useFirstRunState } from "@/hooks/useFirstRunState"
+import { Navigate } from "react-router-dom"
+
+// Inside component body, early return:
+const { isFirstRun, loading: firstRunLoading } = useFirstRunState()
+if (firstRunLoading) return <DashboardSkeleton />
+if (isFirstRun) return <Navigate to="/setup" replace />
+```
+
+---
+
+## Shared Patterns
+
+### Toast Notifications
+**Source:** `src/pages/SettingsPage.tsx` lines 4, 56-59
+**Apply to:** SetupPage (on completion and on error)
+```typescript
+import { toast } from "sonner"
+
+// Success:
+toast.success(t("settings.saved"))
+// Error:
+toast.error(t("common.error"))
+```
+
+### Supabase Profile Update
+**Source:** `src/pages/SettingsPage.tsx` lines 44-62
+**Apply to:** SetupPage (marking setup_completed = true)
+```typescript
+import { supabase } from "@/lib/supabase"
+
+const { error } = await supabase
+  .from("profiles")
+  .update({ setup_completed: true })
+  .eq("id", user.id)
+```
+
+### useCategories Mutation
+**Source:** `src/hooks/useCategories.ts` lines 21-38
+**Apply to:** SetupPage completion logic
+```typescript
+const { create } = useCategories()
+
+// Usage: create.mutateAsync({ name, type })
+const cat = await create.mutateAsync({ name: t(`categories.types.${type}`), type })
+// Returns Category with .id for linking template items
+```
+
+### React Query Invalidation After Completion
+**Source:** `src/hooks/useCategories.ts` line 37
+**Apply to:** SetupPage (prevent redirect loop after completion)
+```typescript
+import { useQueryClient } from "@tanstack/react-query"
+
+const queryClient = useQueryClient()
+// After creating categories + template items:
+await queryClient.invalidateQueries({ queryKey: ["categories"] })
+await queryClient.invalidateQueries({ queryKey: ["template-items"] })
+```
+
+### i18n Translation Pattern
+**Source:** `src/pages/LoginPage.tsx` lines 3, 12, 39
+**Apply to:** All setup components
+```typescript
+import { useTranslation } from "react-i18next"
+const { t } = useTranslation()
+// Usage: t("setup.stepTitle") or t(`presets.${type}.${slug}`) for preset names
+```
+
+### PRESETS Data Access
+**Source:** `src/data/presets.ts`
+**Apply to:** RecurringItemsStep, ReviewStep, SetupPage state initialization
+```typescript
+import { PRESETS } from "@/data/presets"
+// Group by type:
+const grouped = Object.groupBy(PRESETS, (p) => p.type)
+// Or filter: PRESETS.filter(p => p.type === "bill")
+```
+
+## No Analog Found
+
+| File | Role | Data Flow | Reason |
+|------|------|-----------|--------|
+| `src/components/setup/PresetItemRow.tsx` | component | request-response | No existing checkbox-list-row pattern; closest is CategorySection but quite different. Use shadcn Checkbox + Input + Badge inline. |
+| `src/components/setup/CategoryGroupHeader.tsx` | component | transform | Simple heading; trivial enough to not need an analog. |
+
+## Metadata
+
+**Analog search scope:** `src/pages/`, `src/components/`, `src/hooks/`, `src/data/`
+**Files scanned:** 40+
+**Pattern extraction date:** 2026-04-20

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

@@ -0,0 +1,433 @@
+# Phase 7: Setup Wizard - Research
+
+**Researched:** 2026-04-20
+**Domain:** React multi-step wizard UI with localStorage persistence, Supabase writes
+**Confidence:** HIGH
+
+## Summary
+
+Phase 7 builds a 3-step setup wizard that guides first-run users through budget template creation. The phase is primarily a frontend UI task: no new DB schema changes are needed (Phase 6 delivered `setup_completed`, presets, and `useFirstRunState`). The wizard must render a new `/setup` route outside the AppLayout (standalone page like login/register), persist state to localStorage, and on completion create categories + template items via existing hooks.
+
+The codebase already provides every data layer primitive needed: `useFirstRunState` for redirect gating, `useCategories().create` for category creation, `useTemplate().createItem` for template item creation, `PRESETS` array with 19 items, and full i18n keys for preset names. The work is purely component authoring, routing, and orchestration.
+
+**Primary recommendation:** Build the wizard as a standalone page component with internal step state management using React useState + localStorage sync. No additional libraries needed -- the existing stack (React 19, React Router 7, shadcn/ui, Tailwind, React Query, Supabase) handles everything.
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- 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
+- Single "monthly net income" number input pre-filled with 3000, required > 0
+- Full checklist: all 19 PRESETS shown, grouped by category type, with editable amounts
+- Bills (4) + variable_expense (5) pre-checked by default
+- Sticky bar: "Remaining to allocate: Income - sum(checked) = X" -- turns red when negative
+- Read-only review step with grouped summary
+- "Complete" creates categories + template items. Does NOT create first month's budget.
+- After completion: redirect to `/` with success toast
+- "Skip" on each step + global "Skip setup" to exit entirely
+- localStorage keyed by user_id for persistence across refresh
+- On complete or skip: clear localStorage, mark profiles.setup_completed = true
+- No animated transitions between steps (instant swap)
+
+### Claude's Discretion
+- Exact component decomposition (how many sub-components for the wizard)
+- Animation/transition between steps (decided: none)
+- Exact styling of category badges and grouping headers
+- Toast message wording variations
+- Error handling UX for failed API calls during completion
+
+### Deferred Ideas (OUT OF SCOPE)
+None -- discussion stayed within phase scope.
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| SETUP-01 | New user is guided through a 3-step wizard: income, recurring items, review | useFirstRunState hook for redirect gating, /setup route outside AppLayout |
+| SETUP-02 | User sees pre-filled common budget items with sensible default amounts (~15-20 items) | PRESETS array (19 items) with defaultAmount + i18n keys already exist |
+| SETUP-03 | User can skip any wizard step or the entire wizard | Skip Step per step + Skip setup global link, marks setup_completed=true |
+| SETUP-04 | User sees a live "remaining to allocate" balance updating as items are selected | Computed from useState: income - sum(checked items amounts), re-renders on change |
+| SETUP-05 | User's template is created from wizard selections on completion | useCategories().create + useTemplate().createItem mutations in sequence |
+</phase_requirements>
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Wizard UI & navigation | Browser / Client | -- | Pure client-side multi-step form, no SSR |
+| State persistence | Browser / Client | -- | localStorage for mid-session persistence |
+| First-run redirect | Browser / Client | -- | useFirstRunState reads cached React Query data |
+| Category + template creation | API / Backend (Supabase) | Browser / Client | Supabase handles insert; client calls via existing hooks |
+| setup_completed flag update | API / Backend (Supabase) | Browser / Client | Direct Supabase update from client |
+
+## Standard Stack
+
+### Core (already installed)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| React | ^19.2.4 | Component rendering | Project framework [VERIFIED: package.json] |
+| React Router DOM | ^7.13.1 | /setup route, Navigate redirect | Project router [VERIFIED: package.json] |
+| @tanstack/react-query | ^5.90.21 | Data fetching/mutations via hooks | Project data layer [VERIFIED: package.json] |
+| @supabase/supabase-js | ^2.99.1 | DB writes (categories, template_items, profiles) | Project backend [VERIFIED: package.json] |
+| react-i18next | ^16.5.8 | Bilingual copy (EN/DE) | Project i18n [VERIFIED: package.json] |
+| sonner | ^2.0.7 | Toast notifications on completion/error | Project toast library [VERIFIED: package.json] |
+| lucide-react | ^0.577.0 | Check icon for stepper | Project icon library [VERIFIED: package.json] |
+
+### Supporting (already installed)
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| radix-ui | ^1.4.3 | Checkbox primitive (via shadcn) | Step 2 item selection |
+| tailwind-merge + clsx + cva | various | Conditional styling | All components |
+
+### New shadcn Component to Install
+| Component | Purpose |
+|-----------|---------|
+| checkbox | Item selection in step 2 (not yet in /src/components/ui/) |
+
+**Installation:**
+```bash
+npx shadcn@latest add checkbox
+```
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| useState + localStorage | react-hook-form + persist | Overkill for 2 fields (income + selections); useState simpler |
+| Custom stepper | @shadcn/stepper or third-party | Not available in shadcn registry; custom is trivial for 3 steps |
+| Zustand for wizard state | useState + localStorage | No global state needed; wizard is single-page isolated |
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+[First Login] --> [AppLayout / DashboardPage]
+                        |
+              useFirstRunState() --> isFirstRun?
+                        |                    |
+                       NO                   YES
+                        |                    |
+                   Dashboard         <Navigate to="/setup">
+                                            |
+                                    [SetupWizard Page]
+                                            |
+                          localStorage read --> restore step & data
+                                            |
+                     +----------+----------+----------+
+                     |          |          |          |
+                  Step 1     Step 2     Step 3    Skip Setup
+                 (Income)   (Items)   (Review)       |
+                     |          |          |          |
+                     +----------+----------+          |
+                                |                     |
+                          [Complete]             [Skip]
+                                |                     |
+                    create categories          clear localStorage
+                    create template items      set setup_completed=true
+                    clear localStorage         redirect to /
+                    set setup_completed=true
+                    redirect to / with toast
+```
+
+### Recommended Project Structure
+```
+src/
+├── pages/
+│   └── SetupPage.tsx              # Page component, orchestrates wizard
+├── components/
+│   └── setup/
+│       ├── WizardStepper.tsx      # Horizontal 1-2-3 stepper bar
+│       ├── IncomeStep.tsx         # Step 1: income input
+│       ├── RecurringItemsStep.tsx # Step 2: checklist with amounts
+│       ├── ReviewStep.tsx         # Step 3: read-only summary
+│       ├── AllocationBar.tsx      # Sticky remaining balance
+│       ├── PresetItemRow.tsx      # Single checkbox row
+│       └── CategoryGroupHeader.tsx # Section divider with colored dot
+```
+
+### Pattern 1: Wizard State in localStorage
+**What:** Single useState object synced to localStorage on every change
+**When to use:** Multi-step forms that must survive page refresh
+**Example:**
+```typescript
+// Source: project convention + React docs
+interface WizardState {
+  currentStep: 1 | 2 | 3
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+}
+
+const STORAGE_KEY = (userId: string) => `setup-wizard-${userId}`
+
+function useWizardState(userId: string) {
+  const [state, setState] = useState<WizardState>(() => {
+    const saved = localStorage.getItem(STORAGE_KEY(userId))
+    if (saved) return JSON.parse(saved)
+    return getDefaultState() // builds from PRESETS defaults
+  })
+
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY(userId), JSON.stringify(state))
+  }, [state, userId])
+
+  return [state, setState] as const
+}
+```
+
+### Pattern 2: Completion Sequence (Category + Template Item Creation)
+**What:** Sequential creation of categories then template items, handling duplicates
+**When to use:** Wizard completion step
+**Example:**
+```typescript
+// Source: existing useCategories + useTemplate hooks
+async function completeWizard(
+  selectedItems: SelectedItem[],
+  income: number,
+  createCategory: MutateAsync,
+  createItem: MutateAsync,
+) {
+  // 1. Determine unique category types needed
+  const typesNeeded = [...new Set(selectedItems.map(i => i.type))]
+
+  // 2. Create categories (skip if already exist -- DB has unique constraint)
+  const categoryMap: Record<string, string> = {}
+  for (const type of typesNeeded) {
+    try {
+      const cat = await createCategory({ name: categoryLabel(type), type })
+      categoryMap[type] = cat.id
+    } catch (e) {
+      // Unique constraint violation = category exists, fetch it
+      // Handle gracefully
+    }
+  }
+
+  // 3. Create template items for each selected preset
+  for (const item of selectedItems) {
+    await createItem({
+      category_id: categoryMap[item.type],
+      item_tier: item.item_tier,
+      budgeted_amount: item.amount,
+    })
+  }
+}
+```
+
+### Pattern 3: Route Structure (Standalone Page Outside AppLayout)
+**What:** /setup route as a sibling to login/register, not nested in AppLayout
+**When to use:** Wizard must be full-screen without sidebar nav
+**Example:**
+```typescript
+// Source: existing App.tsx routing pattern
+<Routes>
+  {/* Public routes */}
+  <Route path="/login" element={<PublicRoute><LoginPage /></PublicRoute>} />
+  <Route path="/register" element={<PublicRoute><RegisterPage /></PublicRoute>} />
+
+  {/* Setup wizard -- protected but outside AppLayout */}
+  <Route path="/setup" element={<ProtectedRoute><SetupPage /></ProtectedRoute>} />
+
+  {/* Main app layout */}
+  <Route element={<ProtectedRoute><AppLayout /></ProtectedRoute>}>
+    <Route index element={<DashboardPage />} />
+    ...
+  </Route>
+</Routes>
+```
+
+### Anti-Patterns to Avoid
+- **Nested wizard inside AppLayout:** Wizard must be standalone (no sidebar). Keep it as a separate protected route.
+- **Creating template without categories first:** Template items require `category_id` -- categories must be created first in completion flow.
+- **Using mutateAsync without error handling:** Each Supabase insert can fail. Wrap in try/catch, show partial-error toast if some items fail.
+- **Reading profile.setup_completed for redirect:** Use `useFirstRunState` (checks categories/template data), not setup_completed flag. The flag is set on completion, not read for gating.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Checkbox UI | Custom div with click handlers | shadcn Checkbox (Radix) | Keyboard accessibility, aria states, focus ring |
+| Toast notifications | Custom alert/banner | sonner (already integrated) | Consistent with app, auto-dismiss, queue |
+| Number formatting | Manual toFixed/locale | Intl.NumberFormat with profile currency | Handles EUR/USD/CHF, locale-aware separators |
+| i18n key resolution | String concatenation | `t(\`presets.${type}.${slug}\`)` | Already set up in en.json/de.json |
+
+**Key insight:** Every UI primitive and data operation is already available in the project. This phase is purely about composition and orchestration.
+
+## Common Pitfalls
+
+### Pitfall 1: Redirect Loop on Dashboard
+**What goes wrong:** User completes wizard, lands on dashboard, `useFirstRunState` still returns `isFirstRun=true` because React Query cache is stale.
+**Why it happens:** Categories/template items just created but query cache not invalidated yet.
+**How to avoid:** After completion, invalidate both `["categories"]` and `["template-items"]` query keys before redirecting. Or use `setup_completed` flag for the redirect condition (check profiles table).
+**Warning signs:** User bounces between dashboard and /setup infinitely.
+
+### Pitfall 2: Category Name Collision on Completion
+**What goes wrong:** User already has a "Bills" category (edge case: skipped wizard, created manually, re-enters). DB unique constraint rejects the insert.
+**Why it happens:** Phase 6 added `UNIQUE(user_id, name)` constraint on categories.
+**How to avoid:** Use upsert or catch constraint violation errors and fetch existing category ID instead. The completion logic must handle "category already exists" gracefully.
+**Warning signs:** Wizard completion fails silently or shows generic error.
+
+### Pitfall 3: localStorage Orphan After Logout
+**What goes wrong:** User starts wizard, logs out, different user logs in -- sees previous user's wizard state.
+**Why it happens:** localStorage key must include user_id.
+**How to avoid:** Key is `setup-wizard-${userId}` (already specified in CONTEXT). Always validate userId matches on load.
+**Warning signs:** Wrong income/selections appearing for a different user.
+
+### Pitfall 4: Race Condition in Completion
+**What goes wrong:** User double-clicks "Complete Setup" and creates duplicate template items.
+**Why it happens:** Button not disabled during async operation.
+**How to avoid:** Disable Complete button immediately on click, show spinner. Use a `completing` state flag.
+**Warning signs:** Duplicate rows in template_items table.
+
+### Pitfall 5: useTemplate() Needs Template to Exist Before createItem
+**What goes wrong:** `createItem` throws "Template not loaded" because `templateId` is undefined.
+**Why it happens:** `useTemplate()` auto-creates a template row on first query, but the query must complete before `createItem` works.
+**How to avoid:** Ensure `useTemplate()` is called early in the wizard (mount time) so the template row exists by completion time. Or call `getOrCreateTemplate()` directly in the completion flow.
+**Warning signs:** "Template not loaded" error on wizard completion.
+
+## Code Examples
+
+### Redirect Logic in Dashboard (or AppLayout)
+```typescript
+// Source: existing useFirstRunState pattern + CONTEXT decisions
+import { useFirstRunState } from "@/hooks/useFirstRunState"
+import { Navigate } from "react-router-dom"
+
+// Inside DashboardPage or a redirect wrapper:
+const { isFirstRun, loading } = useFirstRunState()
+if (loading) return <Skeleton /> // or null
+if (isFirstRun) return <Navigate to="/setup" replace />
+```
+
+### Updating setup_completed on Skip/Complete
+```typescript
+// Source: existing SettingsPage pattern for profile updates
+import { supabase } from "@/lib/supabase"
+
+async function markSetupComplete(userId: string) {
+  await supabase
+    .from("profiles")
+    .update({ setup_completed: true })
+    .eq("id", userId)
+}
+```
+
+### Live Allocation Calculation
+```typescript
+// Source: derived from CONTEXT decisions
+function computeRemaining(income: number, items: Record<string, { checked: boolean; amount: number }>) {
+  const totalExpenses = Object.values(items)
+    .filter(i => i.checked)
+    .reduce((sum, i) => sum + i.amount, 0)
+  return income - totalExpenses
+}
+```
+
+### Default Selected Items State
+```typescript
+// Source: CONTEXT + PRESETS data structure
+import { PRESETS } from "@/data/presets"
+
+function getDefaultSelectedItems(): Record<string, { checked: boolean; amount: number }> {
+  const result: Record<string, { checked: boolean; amount: number }> = {}
+  for (const preset of PRESETS) {
+    result[preset.slug] = {
+      checked: preset.type === "bill" || preset.type === "variable_expense",
+      amount: preset.defaultAmount,
+    }
+  }
+  return result
+}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Multi-page wizard with URL-per-step | Single-page with internal state | Standard for SPA wizards | Simpler routing, better state control |
+| Form library (react-hook-form) for wizards | useState for simple forms | When forms have < 5 fields | Less boilerplate for simple cases |
+| Redux/Zustand for wizard state | localStorage + useState | For isolated flows | No global store pollution |
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | shadcn checkbox installs via `npx shadcn@latest add checkbox` | Standard Stack | Low -- standard shadcn CLI pattern, easily correctable |
+| A2 | Category names for auto-creation should use i18n labels (e.g., t("categories.types.bill")) | Patterns | Medium -- if hardcoded English names used, DE users get English category names |
+
+## Open Questions
+
+1. **Category naming on creation**
+   - What we know: Categories need a `name` field. Presets are grouped by `type`.
+   - What's unclear: Should each preset create its own category (19 categories) or one category per type (6 categories)?
+   - Recommendation: One category per type (6 max). The CONTEXT says "Create categories (from checked item types that don't already exist)" -- this confirms one-per-type. Multiple template items share the same category.
+
+2. **Where to place the first-run redirect**
+   - What we know: `useFirstRunState` returns `isFirstRun` based on categories/template data.
+   - What's unclear: Should redirect live in DashboardPage, AppLayout, or a wrapper component?
+   - Recommendation: Place in DashboardPage (the index route) since that's where first-run users land. Avoids affecting other routes.
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | None detected (no test config or test files found) |
+| Config file | none -- Wave 0 must create |
+| Quick run command | N/A |
+| Full suite command | N/A |
+
+### Phase Requirements to Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| SETUP-01 | First-run user sees wizard, 3 steps | manual | Manual browser test | N/A |
+| SETUP-02 | 19 pre-filled items with amounts | manual | Visual verification | N/A |
+| SETUP-03 | Skip step/wizard works | manual | Click through wizard | N/A |
+| SETUP-04 | Remaining balance updates live | manual | Check/uncheck items | N/A |
+| SETUP-05 | Template created from selections | manual | Complete wizard, check /template | N/A |
+
+### Wave 0 Gaps
+No test framework exists in this project. All verification is manual/visual. This is acceptable per the project's established pattern -- no test files exist anywhere in `src/`.
+
+## Security Domain
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | no | Already handled by ProtectedRoute |
+| V3 Session Management | no | Supabase session management |
+| V4 Access Control | yes | RLS policies on categories/template_items (already in place) |
+| V5 Input Validation | yes | Income > 0 validation, amounts must be positive numbers |
+| V6 Cryptography | no | No crypto needed |
+
+### Known Threat Patterns for This Phase
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| localStorage tampering | Tampering | Validate localStorage data shape on load; sanitize numbers |
+| Mass insert abuse (spam completion) | Denial of Service | setup_completed flag prevents re-entry; RLS limits to own user |
+| XSS via preset slug injection | Spoofing | Presets are hardcoded in source, not user-input; i18n keys are safe |
+
+## Sources
+
+### Primary (HIGH confidence)
+- Project source code: `src/hooks/useFirstRunState.ts`, `src/hooks/useCategories.ts`, `src/hooks/useTemplate.ts`, `src/data/presets.ts`, `src/App.tsx`, `src/lib/types.ts` -- verified via direct file read
+- `package.json` -- verified all dependency versions
+- Phase 6 outputs: `supabase/migrations/007_setup_completed.sql` -- confirms DB schema ready
+
+### Secondary (MEDIUM confidence)
+- UI-SPEC.md (07-UI-SPEC.md) -- authored design contract for this phase
+- CONTEXT.md (07-CONTEXT.md) -- user decisions from discuss phase
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH - all dependencies verified in package.json, no new installs except shadcn checkbox
+- Architecture: HIGH - follows exact patterns established in existing pages (Login, Register, Settings)
+- Pitfalls: HIGH - derived from reading actual hook implementations and understanding race conditions
+
+**Research date:** 2026-04-20
+**Valid until:** 2026-05-20 (stable -- no moving targets, all deps are pinned)

.planning/phases/07-setup-wizard/07-UI-SPEC.md

@@ -0,0 +1,378 @@
+---
+phase: 7
+slug: setup-wizard
+status: draft
+shadcn_initialized: true
+preset: new-york
+created: 2026-04-20
+---
+
+# Phase 7 — UI Design Contract
+
+> Visual and interaction contract for the 3-step setup wizard. Generated by gsd-ui-researcher, verified by gsd-ui-checker.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | shadcn (new-york style) |
+| Preset | new-york, baseColor neutral, cssVariables true |
+| Component library | Radix UI (via shadcn/ui) |
+| Icon library | Lucide |
+| Font | Inter, ui-sans-serif, system-ui, sans-serif |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline padding |
+| sm | 8px | Compact element spacing, checkbox-to-label gap |
+| md | 16px | Default element spacing, card internal padding |
+| lg | 24px | Section padding, stepper step gaps |
+| xl | 32px | Layout gaps, card content vertical spacing |
+| 2xl | 48px | Step card top/bottom padding |
+| 3xl | 64px | Page-level vertical centering offset |
+
+Exceptions: Sticky allocation bar uses 12px vertical padding (py-3) for visual compactness within the card.
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height |
+|------|------|--------|-------------|
+| Body | 14px | 400 (regular) | 1.5 |
+| Label | 14px | 600 (semibold) | 1.4 |
+| Heading | 20px | 600 (semibold) | 1.2 |
+| Display | 28px | 600 (semibold) | 1.2 |
+
+Only two weights are used: 400 (regular) for body text and 600 (semibold) for labels, headings, and display. No medium (500) weight exists in this contract.
+
+Usage in wizard:
+- **Display (28px/600):** Wizard page title "Set up your budget" (step 1 heading area)
+- **Heading (20px/600):** Step card titles ("Monthly Income", "Recurring Items", "Review")
+- **Label (14px/600):** Category group headers (e.g., "Bills", "Variable Expenses"), stepper step labels, "Remaining to allocate" label, form field labels
+- **Body (14px/400):** Preset item names, amounts, helper text, step descriptions
+
+---
+
+## Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | `oklch(0.98 0.01 260)` (--background) | Page background behind wizard card |
+| Secondary (30%) | `oklch(1 0 0)` (--card) | Wizard card surface, review summary card |
+| Accent (10%) | `oklch(0.55 0.15 260)` (--primary) | Active stepper step indicator, primary CTA buttons, step number circles (active) |
+| Destructive | `oklch(0.6 0.2 25)` (--destructive) | Negative "remaining to allocate" text, validation error text |
+
+**Focal point:** The primary CTA button ("Next Step" / "Complete Setup") in the bottom-right of the card is the single focal point on every step. It is the only large accent-colored element in the viewport, drawing the eye to the next action.
+
+Accent reserved for:
+- Active step circle in the stepper (filled primary background)
+- "Next Step" and "Complete Setup" primary buttons
+- Income input focus ring
+- Completed step checkmark icon color
+
+Additional semantic colors used (existing tokens):
+- `--color-income` (`oklch(0.55 0.17 155)`): Income category group header dot and badge
+- `--color-bill` (`oklch(0.55 0.17 25)`): Bill category group header dot and badge
+- `--color-variable-expense` (`oklch(0.58 0.16 50)`): Variable expense category group header dot and badge
+- `--color-debt` (`oklch(0.52 0.18 355)`): Debt category group header dot and badge
+- `--color-saving` (`oklch(0.55 0.16 220)`): Saving category group header dot and badge
+- `--color-investment` (`oklch(0.55 0.16 285)`): Investment category group header dot and badge
+- `--color-on-budget` (`oklch(0.50 0.17 155)`): Positive "remaining to allocate" text (green)
+
+---
+
+## Component Inventory
+
+### New shadcn Components to Install
+
+| Component | Purpose |
+|-----------|---------|
+| `checkbox` | Preset item selection in step 2 |
+
+### Existing Components Used
+
+| Component | Where |
+|-----------|-------|
+| `Card`, `CardHeader`, `CardContent` | Wizard step container, review summary |
+| `Button` | Next Step, Go Back, Skip Step, Skip setup, Complete Setup |
+| `Input` | Income amount (step 1), per-item amount editing (step 2) |
+| `Badge` | Category type indicators next to preset items |
+| `Label` | Form field labels |
+| `Separator` | Between category groups in step 2 and review step |
+
+### Custom Components to Build
+
+| Component | Description |
+|-----------|-------------|
+| `SetupWizard` | Page-level orchestrator: holds wizard state, renders stepper + active step |
+| `WizardStepper` | Horizontal numbered stepper bar (1-2-3) with clickable completed steps |
+| `IncomeStep` | Step 1: single income input with currency indicator |
+| `RecurringItemsStep` | Step 2: grouped checklist of 19 presets with editable amounts |
+| `ReviewStep` | Step 3: read-only summary of selections |
+| `AllocationBar` | Sticky bar showing "Remaining to allocate" with live calculation |
+| `PresetItemRow` | Single checklist row: checkbox + name + category badge + amount input |
+| `CategoryGroupHeader` | Section header with colored dot + category type label + item count |
+
+---
+
+## Layout Contract
+
+### Page Shell
+
+```
+Full viewport height, centered content:
+- Container: flex min-h-screen items-center justify-center bg-background p-4
+- No sidebar, no app nav — standalone page like login/register
+- Content wrapper: w-full max-w-2xl (672px) with vertical flex layout
+```
+
+### Stepper Bar
+
+```
+Position: Above the card, inside the content wrapper
+Layout: flex items-center justify-center gap-8
+Each step: 
+  - Circle: 32px (w-8 h-8), centered number text (14px/600)
+  - Active: bg-primary text-primary-foreground
+  - Completed: bg-primary text-primary-foreground with Check icon (16px)
+  - Upcoming: bg-muted text-muted-foreground border border-border
+  - Connector line between steps: h-px w-16 bg-border (completed: bg-primary)
+  - Step label below circle: text-xs font-semibold text-muted-foreground (active: text-foreground)
+Clickable: Completed steps and current step only (not future steps)
+Margin below stepper: 24px (mb-6) before the card
+```
+
+### Step Card
+
+```
+Card: w-full border border-border shadow-sm
+CardHeader: pb-2
+  - Step title: heading (20px/600)
+  - Step description: body (14px/400) text-muted-foreground, 1 line
+CardContent: space-y-6
+
+Bottom navigation row (inside CardContent, at the bottom):
+  - flex justify-between items-center pt-4 border-t border-border
+  - Left: Go Back button (variant="ghost", hidden on step 1) + Skip Step button (variant="ghost", text-muted-foreground)
+  - Right: Next Step button (variant="default", primary) or Complete Setup button (step 3)
+```
+
+### Step 1 — Income
+
+```
+Card content:
+  - Label: "Monthly net income" (14px/600)
+  - Input row: flex items-center gap-2
+    - Input: type="number", w-full, text-right, text-lg (18px), pre-filled "3000"
+    - Currency suffix: text-muted-foreground text-sm, shows profile currency (e.g., "EUR")
+  - Helper text below: "Enter your total monthly take-home pay" (14px/400, text-muted-foreground)
+  - Validation: if empty or <= 0 on Next Step click, show destructive text below input: "Please enter a positive income amount"
+```
+
+### Step 2 — Recurring Items
+
+```
+Allocation bar (sticky):
+  - Position: sticky top-0 z-10, inside the card content area
+  - Layout: flex justify-between items-center py-3 px-4 bg-muted border-b border-border
+  - Left: "Remaining to allocate" (14px/600)
+  - Right: formatted amount (16px/600)
+    - Positive or zero: text-on-budget (green)
+    - Negative: text-destructive (red)
+  - Updates live on every check/uncheck and amount edit
+
+Category groups (6 groups, ordered: income, bill, variable_expense, debt, saving, investment):
+  - CategoryGroupHeader: flex items-center gap-2 pt-4 pb-2
+    - Colored dot: w-2.5 h-2.5 (10px) circle using category color token
+    - Group label: label (14px/600) using categoryLabels from palette.ts
+    - Item count badge: text-xs text-muted-foreground "(4 items)"
+  - Separator below header: border-border
+
+  PresetItemRow (per item):
+    - Layout: flex items-center gap-3 py-2.5 px-1
+    - Checkbox: shadcn checkbox (16px square, sharp corners via radius-0)
+    - Item name: body (14px/400), flex-1
+      - Uses i18n key: t(`presets.${type}.${slug}`)
+    - Category badge: Badge variant="outline", text-xs, styled with category color border-left (3px)
+    - Amount input: w-24 text-right, type="number"
+      - Enabled only when checkbox is checked
+      - Disabled state: bg-muted text-muted-foreground opacity-50
+      - Pre-filled with preset defaultAmount
+
+Default checked state:
+  - bill (4 items): ALL checked
+  - variable_expense (5 items): ALL checked
+  - income, debt, saving, investment: ALL unchecked
+```
+
+### Step 3 — Review
+
+```
+Card content:
+  - Read-only summary, no editable fields
+  - Income row: flex justify-between py-2
+    - "Monthly income" (14px/600)
+    - Formatted amount (14px/600)
+  - Separator
+  - Selected items grouped by category type (same order as step 2)
+    - CategoryGroupHeader (same component, no checkbox)
+    - Per item: flex justify-between py-1.5 px-1
+      - Item name (14px/400)
+      - Amount (14px/400, text-right)
+  - Separator
+  - Totals section: space-y-1 pt-2
+    - "Total expenses" row: flex justify-between, 14px/600
+    - "Remaining" row: flex justify-between, 16px/600
+      - Positive: text-on-budget
+      - Negative: text-destructive
+  
+  - If no items selected: show muted message "No items selected. You can add items to your template later."
+```
+
+### Skip Controls
+
+```
+Per-step skip: Ghost button "Skip Step" in the bottom-left nav area
+  - Advances to next step without saving current step data
+  - On step 3 skip: same as "Skip setup" (exits wizard)
+
+Global skip: "Skip setup" link/button
+  - Position: below the card, centered, text-sm text-muted-foreground underline
+  - Margin top: 16px below card
+  - Action: clears localStorage, sets profiles.setup_completed = true, redirects to dashboard
+  - No confirmation dialog (non-destructive — user can still manually set up template)
+```
+
+---
+
+## Interaction Contract
+
+### Step Navigation
+
+| Action | Behavior |
+|--------|----------|
+| Click "Next Step" (step 1) | Validate income > 0. If valid, transition to step 2. If invalid, show inline error. |
+| Click "Next Step" (step 2) | No validation required (0 items selected is valid). Transition to step 3. |
+| Click "Go Back" | Return to previous step. Preserve all entered data. |
+| Click stepper circle (completed) | Navigate to that step. Preserve all data. |
+| Click stepper circle (future) | No action. Cursor: default. |
+| Click "Complete Setup" (step 3) | Create categories + template items via API. On success: clear localStorage, set setup_completed=true, redirect to dashboard with toast. |
+| Click "Skip Step" (per-step) | Advance to next step without current step data. Step 1 skip: income stays at default or last entered value. Step 2 skip: uncheck all items. |
+| Click "Skip setup" (global) | Exit wizard entirely. Clear localStorage. Mark setup_completed=true. Redirect to dashboard. No toast. |
+| Page refresh mid-wizard | Restore wizard at the same step with all entered data from localStorage. |
+
+### State Persistence (localStorage)
+
+```
+Key: `setup-wizard-${userId}`
+Value: JSON object
+{
+  currentStep: 1 | 2 | 3,
+  income: number,
+  selectedItems: Record<string, { checked: boolean, amount: number }>,
+  // keyed by preset slug
+}
+Cleared on: wizard completion OR skip setup
+```
+
+### Loading & Error States
+
+| State | Behavior |
+|-------|----------|
+| Wizard loading (useFirstRunState pending) | Show centered Skeleton matching card dimensions (max-w-2xl, h-64) |
+| Completion API in progress | "Complete Setup" button shows spinner + disabled. Go Back/Skip Step also disabled. |
+| Completion API failure | Toast (sonner, variant destructive): "Could not save your template. Please try again." Button re-enables. Data preserved. |
+| Partial completion failure | If categories created but template items fail: toast with "Some items could not be saved. Check your template page." Redirect to dashboard anyway. |
+
+### Transitions Between Steps
+
+No animated transitions between steps. Instant swap of step content within the card. The stepper bar updates synchronously.
+
+---
+
+## Copywriting Contract
+
+All copy must have i18n keys in both `en.json` and `de.json`. Keys live under a `setup` namespace.
+
+| Element | EN Copy | i18n Key |
+|---------|---------|----------|
+| Page title (step 1) | Set up your budget | `setup.title` |
+| Step 1 title | Monthly Income | `setup.step1.title` |
+| Step 1 description | How much do you earn each month? | `setup.step1.description` |
+| Step 1 label | Monthly net income | `setup.step1.incomeLabel` |
+| Step 1 helper | Enter your total monthly take-home pay | `setup.step1.helper` |
+| Step 1 validation | Please enter a positive income amount | `setup.step1.validation` |
+| Step 2 title | Recurring Items | `setup.step2.title` |
+| Step 2 description | Select your regular monthly expenses | `setup.step2.description` |
+| Allocation bar label | Remaining to allocate | `setup.step2.remaining` |
+| Step 3 title | Review | `setup.step3.title` |
+| Step 3 description | Confirm your budget template | `setup.step3.description` |
+| Step 3 income label | Monthly income | `setup.step3.incomeLabel` |
+| Step 3 total label | Total expenses | `setup.step3.totalLabel` |
+| Step 3 remaining label | Remaining | `setup.step3.remainingLabel` |
+| Step 3 empty | No items selected. You can add items to your template later. | `setup.step3.empty` |
+| Stepper labels | Income / Items / Review | `setup.steps.1` / `setup.steps.2` / `setup.steps.3` |
+| Next button | Next Step | `setup.next` |
+| Back button | Go Back | `setup.back` |
+| Skip button | Skip Step | `setup.skip` |
+| Skip setup link | Skip setup | `setup.skipSetup` |
+| Complete button | Complete Setup | `setup.complete` |
+| Success toast | Template created! Your first budget will appear automatically. | `setup.toast.success` |
+| Error toast | Could not save your template. Please try again. | `setup.toast.error` |
+| Partial error toast | Some items could not be saved. Check your template page. | `setup.toast.partialError` |
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| shadcn official | checkbox | not required |
+
+No third-party registries declared.
+
+---
+
+## Accessibility Contract
+
+| Concern | Implementation |
+|---------|----------------|
+| Stepper semantics | `role="navigation"` with `aria-label="Setup progress"`. Each step: `role="tab"`, `aria-selected` for active, `aria-disabled` for future. |
+| Step content | `role="tabpanel"` with `aria-labelledby` pointing to the active step tab. |
+| Checkbox group | Each category group is a `fieldset` with `legend` (visually styled as CategoryGroupHeader). |
+| Income input | `aria-describedby` pointing to helper text and validation error (when shown). |
+| Allocation bar | `aria-live="polite"` so screen readers announce remaining amount changes. |
+| Skip links | Visible, keyboard-focusable. Not hidden behind hover. |
+| Focus management | On step transition, focus moves to the step card heading. |
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Behavior |
+|------------|----------|
+| >= 768px (md) | max-w-2xl card centered, stepper horizontal with labels below circles |
+| < 768px (sm) | Card becomes full-width (mx-4). Stepper collapses: show circles only, hide step labels. Amount inputs remain w-24. |
+| < 480px (xs) | PresetItemRow: badge hidden, amount input w-20. Category group headers wrap naturally. |
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

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

@@ -0,0 +1,137 @@
+---
+phase: 07-setup-wizard
+verified: 2026-04-20T19:30:00Z
+status: human_needed
+score: 5/5
+overrides_applied: 0
+human_verification:
+  - test: "Create a new user (zero categories/template items), log in, verify auto-redirect to /setup and complete the 3-step wizard flow end-to-end"
+    expected: "Step 1 shows income pre-filled at 3000 with EUR suffix. Step 2 shows grouped presets with bills+variable_expense pre-checked. AllocationBar updates live. Step 3 shows read-only summary. Complete creates categories + template items, redirects to dashboard with success toast."
+    why_human: "Full user flow spanning multiple pages, Supabase writes, React Query cache invalidation, redirect behavior, and toast notifications cannot be verified statically"
+  - test: "Test skip flow: fresh user clicks Skip setup from step 1"
+    expected: "Redirects to dashboard with no data created, setup_completed=true in profiles table"
+    why_human: "Requires Supabase interaction and verifying database state after redirect"
+  - test: "Test localStorage persistence: start wizard, advance to step 2, refresh page"
+    expected: "Wizard resumes at step 2 with previously entered income preserved"
+    why_human: "Browser localStorage behavior cannot be verified without running the app"
+  - test: "Verify no redirect loop: after completing wizard, dashboard loads normally"
+    expected: "Dashboard renders without redirecting back to /setup"
+    why_human: "Requires React Query cache freshness and useFirstRunState reading updated data after completion"
+---
+
+# Phase 7: Setup Wizard Verification Report
+
+**Phase Goal:** 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
+**Verified:** 2026-04-20T19:30:00Z
+**Status:** human_needed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | A new user is automatically redirected to /setup on first login and sees a 3-step wizard | VERIFIED | DashboardPage.tsx:293 `if (isFirstRun) return <Navigate to="/setup" replace />`, SetupPage renders WizardStepper with 3 steps |
+| 2 | The recurring items step shows ~15-20 pre-filled common items with editable default amounts | VERIFIED | RecurringItemsStep imports PRESETS (20 items counted in presets.ts), renders each with PresetItemRow including editable amount Input |
+| 3 | A "remaining to allocate" balance updates live as items are checked/unchecked | VERIFIED | AllocationBar computes `income - totalChecked` inline, renders with `aria-live="polite"`, colors switch at remaining < 0 |
+| 4 | User can skip any step or skip setup entirely without creating data | VERIFIED | handleSkipStep advances steps, handleSkipSetup clears localStorage + marks setup_completed=true + redirects, no category/template creation |
+| 5 | Completing the wizard creates a populated template and refreshing mid-wizard restores state | VERIFIED | handleComplete creates categories via create.mutateAsync + template items via createItem.mutateAsync; useWizardState reads/writes localStorage keyed by userId |
+
+**Score:** 5/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/pages/SetupPage.tsx` | Wizard page orchestrator | VERIFIED | 290 lines, renders stepper + conditional steps + completion logic |
+| `src/hooks/useWizardState.ts` | localStorage-synced wizard state | VERIFIED | 85 lines, exports useWizardState with full CRUD + clearState |
+| `src/components/setup/WizardStepper.tsx` | Horizontal 1-2-3 stepper | VERIFIED | 62 lines, role="navigation", clickable completed steps |
+| `src/components/setup/IncomeStep.tsx` | Step 1 income input | VERIFIED | 45 lines, number input with currency suffix + validation display |
+| `src/components/setup/RecurringItemsStep.tsx` | Step 2 grouped checklist | VERIFIED | 81 lines, groups PRESETS by type, renders AllocationBar + PresetItemRow |
+| `src/components/setup/AllocationBar.tsx` | Sticky remaining balance bar | VERIFIED | 31 lines, sticky top-0, aria-live="polite", color conditional |
+| `src/components/setup/PresetItemRow.tsx` | Single checkbox row | VERIFIED | 59 lines, Checkbox + name + Badge + amount Input (disabled when unchecked) |
+| `src/components/setup/CategoryGroupHeader.tsx` | Section header with colored dot | VERIFIED | 36 lines, w-2.5 h-2.5 rounded-full + color var mapping |
+| `src/components/setup/ReviewStep.tsx` | Read-only summary | VERIFIED | 118 lines, groups checked items, shows totals, remaining with color |
+| `src/App.tsx` | /setup route registration | VERIFIED | path="/setup" inside ProtectedRoute, outside AppLayout |
+| `src/pages/DashboardPage.tsx` | First-run redirect | VERIFIED | useFirstRunState + Navigate to="/setup" replace |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| SetupPage.tsx | useWizardState.ts | `useWizardState(userId)` | WIRED | Line 54-55 |
+| RecurringItemsStep.tsx | presets.ts | `import PRESETS` | WIRED | Line 2 |
+| DashboardPage.tsx | useFirstRunState.ts | `useFirstRunState() -> Navigate /setup` | WIRED | Lines 276, 293 |
+| SetupPage.tsx | useCategories.ts | `create.mutateAsync` | WIRED | Line 128 |
+| SetupPage.tsx | useTemplate.ts | `createItem.mutateAsync` | WIRED | Line 153 |
+| App.tsx | SetupPage.tsx | Route path="/setup" | WIRED | Lines 48-55 |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|---------------|--------|-------------------|--------|
+| RecurringItemsStep | selectedItems | useWizardState (localStorage) -> PRESETS defaults | Yes (20 preset items with defaultAmount) | FLOWING |
+| AllocationBar | remaining | Computed from income - sum(checked amounts) | Yes (derived from wizard state) | FLOWING |
+| ReviewStep | selectedItems + income | useWizardState state passed as props | Yes (filtered from wizard state) | FLOWING |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| TypeScript compiles | `npx tsc --noEmit` | Exit 0, no errors | PASS |
+| All setup components exist | `ls src/components/setup/*.tsx` | 7 files found | PASS |
+| i18n keys in EN | `grep "setup" src/i18n/en.json` | setup object at line 124 | PASS |
+| i18n keys in DE | `grep "setup" src/i18n/de.json` | setup object at line 124 | PASS |
+| Presets count | `grep -c slug src/data/presets.ts` | 20 items | PASS |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-----------|-------------|--------|----------|
+| SETUP-01 | 07-01, 07-02 | New user guided through 3-step wizard: income -> recurring items -> review | SATISFIED | WizardStepper + 3 step components + DashboardPage redirect |
+| SETUP-02 | 07-01 | User sees pre-filled common budget items with sensible defaults (~15-20 items) | SATISFIED | 20 PRESETS in presets.ts, rendered in RecurringItemsStep with defaultAmount |
+| SETUP-03 | 07-02 | User can skip any wizard step or the entire wizard | SATISFIED | handleSkipStep + handleSkipSetup in SetupPage |
+| SETUP-04 | 07-01 | User sees a live "remaining to allocate" balance updating as items are selected | SATISFIED | AllocationBar with computed remaining, aria-live="polite" |
+| SETUP-05 | 07-02 | User's template is created from wizard selections on completion | SATISFIED | handleComplete creates categories + template items via mutateAsync |
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| (none) | - | - | - | No TODOs, FIXMEs, placeholders, or stubs found in any wizard file |
+
+### Human Verification Required
+
+### 1. Full Wizard Flow (End-to-End)
+
+**Test:** Create a new user (zero categories/template items), log in, verify auto-redirect to /setup and complete the 3-step wizard flow end-to-end
+**Expected:** Step 1 shows income pre-filled at 3000 with EUR suffix. Step 2 shows grouped presets with bills+variable_expense pre-checked. AllocationBar updates live. Step 3 shows read-only summary. Complete creates categories + template items, redirects to dashboard with success toast.
+**Why human:** Full user flow spanning multiple pages, Supabase writes, React Query cache invalidation, redirect behavior, and toast notifications cannot be verified statically
+
+### 2. Skip Flow
+
+**Test:** Fresh user clicks "Skip setup" from step 1
+**Expected:** Redirects to dashboard with no data created, setup_completed=true in profiles table
+**Why human:** Requires Supabase interaction and verifying database state after redirect
+
+### 3. localStorage Persistence
+
+**Test:** Start wizard, advance to step 2, refresh page
+**Expected:** Wizard resumes at step 2 with previously entered income preserved
+**Why human:** Browser localStorage behavior cannot be verified without running the app
+
+### 4. No Redirect Loop After Completion
+
+**Test:** After completing wizard, verify dashboard loads normally without re-redirecting to /setup
+**Expected:** Dashboard renders correctly, useFirstRunState returns isFirstRun=false
+**Why human:** Requires React Query cache freshness and useFirstRunState reading updated data after completion
+
+### Gaps Summary
+
+No code-level gaps found. All artifacts exist, are substantive (no stubs or placeholders), are properly wired, and TypeScript compiles cleanly. The implementation covers all 5 ROADMAP success criteria and all 5 requirement IDs (SETUP-01 through SETUP-05). Human verification is needed to confirm the runtime behavior (Supabase writes, redirect flows, localStorage persistence).
+
+---
+
+_Verified: 2026-04-20T19:30:00Z_
+_Verifier: Claude (gsd-verifier)_

src/App.tsx

@@ -3,6 +3,7 @@ import { useAuth } from "@/hooks/useAuth"
 import AppLayout from "@/components/AppLayout"
 import LoginPage from "@/pages/LoginPage"
 import RegisterPage from "@/pages/RegisterPage"
+import SetupPage from "@/pages/SetupPage"
 import DashboardPage from "@/pages/DashboardPage"
 import CategoriesPage from "@/pages/CategoriesPage"
 import TemplatePage from "@/pages/TemplatePage"
@@ -44,6 +45,14 @@ export default function App() {
           </PublicRoute>
         }
       />
+      <Route
+        path="/setup"
+        element={
+          <ProtectedRoute>
+            <SetupPage />
+          </ProtectedRoute>
+        }
+      />
       <Route
         element={
           <ProtectedRoute>

src/components/QuickAddPicker.tsx

@@ -153,7 +153,7 @@ export default function QuickAddPicker({ budgetId }: QuickAddPickerProps) {
                     type="button"
                     role="option"
                     aria-selected={false}
-                    className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                    className="flex w-full items-center gap-2 px-2 py-1.5 text-sm hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
                     onClick={() => handlePickItem(item)}
                   >
                     {item.icon && (
@@ -198,7 +198,7 @@ export default function QuickAddPicker({ budgetId }: QuickAddPickerProps) {
                       <SelectGroup key={type}>
                         <SelectLabel className="flex items-center gap-1.5">
                           <div
-                            className="size-2 rounded-full"
+                            className="size-2"
                             style={{ backgroundColor: categoryColors[type] }}
                           />
                           {t(`categories.types.${type}`)}

src/components/dashboard/CategorySection.tsx

@@ -70,7 +70,7 @@ export function CategorySection({
     <Collapsible open={open} onOpenChange={onOpenChange}>
       <CollapsibleTrigger asChild>
         <button
-          className="group flex w-full items-center gap-3 rounded-md border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"
+          className="group flex w-full items-center gap-3 border-l-4 bg-card px-4 py-3 text-left hover:bg-muted/40 transition-colors"
           style={{ borderLeftColor: categoryColors[type] }}
         >
           <ChevronRight

src/components/dashboard/DashboardSkeleton.tsx

@@ -17,22 +17,22 @@ function SkeletonStatCard() {
 
 export function DashboardSkeleton() {
   return (
-    <div className="flex flex-col gap-6">
+    <div className="flex flex-col gap-8">
       {/* Summary cards skeleton */}
-      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
         <SkeletonStatCard />
         <SkeletonStatCard />
         <SkeletonStatCard />
       </div>
 
       {/* 3-column chart area skeleton */}
-      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
+      <div className="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
         <Card>
           <CardHeader>
             <Skeleton className="h-5 w-40" />
           </CardHeader>
           <CardContent>
-            <Skeleton className="h-[250px] w-full rounded-md" />
+            <Skeleton className="h-[250px] w-full" />
           </CardContent>
         </Card>
         <Card>
@@ -40,7 +40,7 @@ export function DashboardSkeleton() {
             <Skeleton className="h-5 w-40" />
           </CardHeader>
           <CardContent>
-            <Skeleton className="h-[250px] w-full rounded-md" />
+            <Skeleton className="h-[250px] w-full" />
           </CardContent>
         </Card>
         <Card>
@@ -48,7 +48,7 @@ export function DashboardSkeleton() {
             <Skeleton className="h-5 w-40" />
           </CardHeader>
           <CardContent>
-            <Skeleton className="h-[250px] w-full rounded-md" />
+            <Skeleton className="h-[250px] w-full" />
           </CardContent>
         </Card>
       </div>
@@ -56,12 +56,12 @@ export function DashboardSkeleton() {
       {/* Collapsible sections skeleton */}
       <div className="space-y-3">
         {[1, 2, 3].map((i) => (
-          <div key={i} className="flex items-center gap-3 rounded-md border-l-4 border-muted bg-card px-4 py-3">
+          <div key={i} className="flex items-center gap-3 border-l-4 border-muted bg-card px-4 py-3">
             <Skeleton className="size-4" />
             <Skeleton className="h-4 w-32" />
             <div className="ml-auto flex items-center gap-2">
-              <Skeleton className="h-5 w-24 rounded-full" />
+              <Skeleton className="h-5 w-24" />
-              <Skeleton className="h-5 w-24 rounded-full" />
+              <Skeleton className="h-5 w-24" />
               <Skeleton className="h-4 w-16" />
             </div>
           </div>

src/components/dashboard/charts/ChartEmptyState.tsx

@@ -9,7 +9,7 @@ export function ChartEmptyState({ message, className }: ChartEmptyStateProps) {
   return (
     <div
       className={cn(
-        "flex min-h-[250px] w-full items-center justify-center rounded-lg border border-dashed border-muted-foreground/20 bg-muted/30",
+        "flex min-h-[250px] w-full items-center justify-center border border-dashed border-muted-foreground/20 bg-muted/30",
         className
       )}
     >

src/components/dashboard/charts/ExpenseDonutChart.tsx

@@ -138,7 +138,7 @@ export function ExpenseDonutChart({
               className="flex items-center gap-2 text-sm"
             >
               <span
-                className="inline-block size-3 shrink-0 rounded-full"
+                className="inline-block size-3 shrink-0"
                 style={{
                   backgroundColor: `var(--color-${entry.type}-fill)`,
                 }}

src/components/dashboard/charts/IncomeBarChart.tsx

@@ -54,9 +54,9 @@ export function IncomeBarChart({
         <Bar
           dataKey="budgeted"
           fill="var(--color-budgeted)"
-          radius={[4, 4, 0, 0]}
+          radius={0}
         />
-        <Bar dataKey="actual" radius={[4, 4, 0, 0]}>
+        <Bar dataKey="actual" radius={0}>
           {data.map((entry, index) => (
             <Cell
               key={index}

src/components/dashboard/charts/SpendBarChart.tsx

@@ -64,9 +64,9 @@ export function SpendBarChart({
         <Bar
           dataKey="budgeted"
           fill="var(--color-budgeted)"
-          radius={4}
+          radius={0}
         />
-        <Bar dataKey="actual" radius={4}>
+        <Bar dataKey="actual" radius={0}>
           {data.map((entry, index) => (
             <Cell
               key={index}

src/components/setup/AllocationBar.tsx

@@ -0,0 +1,31 @@
+import { useTranslation } from "react-i18next"
+
+interface AllocationBarProps {
+  remaining: number
+  currency: string
+}
+
+export function AllocationBar({ remaining, currency }: AllocationBarProps) {
+  const { t } = useTranslation()
+
+  const formatted = new Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  }).format(remaining)
+
+  return (
+    <div className="sticky top-0 z-10 flex justify-between items-center py-3 px-4 bg-muted border-b border-border rounded-none">
+      <span className="text-sm font-semibold">{t("setup.step2.remaining")}</span>
+      <span
+        aria-live="polite"
+        className={`text-base font-semibold ${
+          remaining >= 0 ? "text-on-budget" : "text-destructive"
+        }`}
+      >
+        {formatted}
+      </span>
+    </div>
+  )
+}

src/components/setup/CategoryGroupHeader.tsx

@@ -0,0 +1,36 @@
+import type { CategoryType } from "@/lib/types"
+import { Separator } from "@/components/ui/separator"
+
+interface CategoryGroupHeaderProps {
+  type: CategoryType
+  label: string
+  count: number
+}
+
+const colorVar = (type: CategoryType): string => {
+  const map: Record<CategoryType, string> = {
+    income: "var(--color-income)",
+    bill: "var(--color-bill)",
+    variable_expense: "var(--color-variable-expense)",
+    debt: "var(--color-debt)",
+    saving: "var(--color-saving)",
+    investment: "var(--color-investment)",
+  }
+  return map[type]
+}
+
+export function CategoryGroupHeader({ type, label, count }: CategoryGroupHeaderProps) {
+  return (
+    <div>
+      <div className="flex items-center gap-2 pt-4 pb-2">
+        <span
+          className="w-2.5 h-2.5 rounded-full"
+          style={{ backgroundColor: colorVar(type) }}
+        />
+        <span className="text-sm font-semibold">{label}</span>
+        <span className="text-xs text-muted-foreground">({count} items)</span>
+      </div>
+      <Separator />
+    </div>
+  )
+}

src/components/setup/IncomeStep.tsx

@@ -0,0 +1,45 @@
+import { useTranslation } from "react-i18next"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+interface IncomeStepProps {
+  income: number
+  onIncomeChange: (val: number) => void
+  currency: string
+  error: string | null
+}
+
+export function IncomeStep({ income, onIncomeChange, currency, error }: IncomeStepProps) {
+  const { t } = useTranslation()
+
+  const helperId = "income-helper"
+  const errorId = "income-error"
+
+  return (
+    <div className="space-y-4">
+      <Label htmlFor="income-input" className="text-sm font-semibold">
+        {t("setup.step1.incomeLabel")}
+      </Label>
+      <div className="flex items-center gap-2">
+        <Input
+          id="income-input"
+          type="number"
+          className="w-full text-right text-lg"
+          value={income}
+          onChange={(e) => onIncomeChange(Number(e.target.value))}
+          min={0}
+          aria-describedby={`${helperId}${error ? ` ${errorId}` : ""}`}
+        />
+        <span className="text-muted-foreground text-sm">{currency}</span>
+      </div>
+      <p id={helperId} className="text-sm text-muted-foreground">
+        {t("setup.step1.helper")}
+      </p>
+      {error && (
+        <p id={errorId} className="text-sm text-destructive">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}

src/components/setup/PresetItemRow.tsx

@@ -0,0 +1,59 @@
+import { useTranslation } from "react-i18next"
+import type { CategoryType } from "@/lib/types"
+import { Checkbox } from "@/components/ui/checkbox"
+import { Badge } from "@/components/ui/badge"
+import { Input } from "@/components/ui/input"
+
+interface PresetItemRowProps {
+  slug: string
+  type: CategoryType
+  checked: boolean
+  amount: number
+  onToggle: () => void
+  onAmountChange: (val: number) => void
+}
+
+const colorVar = (type: CategoryType): string => {
+  const map: Record<CategoryType, string> = {
+    income: "var(--color-income)",
+    bill: "var(--color-bill)",
+    variable_expense: "var(--color-variable-expense)",
+    debt: "var(--color-debt)",
+    saving: "var(--color-saving)",
+    investment: "var(--color-investment)",
+  }
+  return map[type]
+}
+
+export function PresetItemRow({
+  slug,
+  type,
+  checked,
+  amount,
+  onToggle,
+  onAmountChange,
+}: PresetItemRowProps) {
+  const { t } = useTranslation()
+
+  return (
+    <div className="flex items-center gap-3 py-2.5 px-1">
+      <Checkbox checked={checked} onCheckedChange={onToggle} />
+      <span className="flex-1 text-sm">{t(`presets.${type}.${slug}`)}</span>
+      <Badge
+        variant="outline"
+        className="text-xs"
+        style={{ borderLeftWidth: "3px", borderLeftColor: colorVar(type) }}
+      >
+        {t(`categories.types.${type}`)}
+      </Badge>
+      <Input
+        type="number"
+        className={`w-24 text-right ${!checked ? "bg-muted text-muted-foreground opacity-50" : ""}`}
+        value={amount}
+        onChange={(e) => onAmountChange(Number(e.target.value))}
+        disabled={!checked}
+        min={0}
+      />
+    </div>
+  )
+}

src/components/setup/RecurringItemsStep.tsx

@@ -0,0 +1,81 @@
+import { useTranslation } from "react-i18next"
+import { PRESETS } from "@/data/presets"
+import type { CategoryType } from "@/lib/types"
+import { AllocationBar } from "./AllocationBar"
+import { CategoryGroupHeader } from "./CategoryGroupHeader"
+import { PresetItemRow } from "./PresetItemRow"
+
+interface RecurringItemsStepProps {
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+  income: number
+  currency: string
+  onToggle: (slug: string) => void
+  onAmountChange: (slug: string, amount: number) => void
+}
+
+const GROUP_ORDER: CategoryType[] = [
+  "income",
+  "bill",
+  "variable_expense",
+  "debt",
+  "saving",
+  "investment",
+]
+
+export function RecurringItemsStep({
+  selectedItems,
+  income,
+  currency,
+  onToggle,
+  onAmountChange,
+}: RecurringItemsStepProps) {
+  const { t } = useTranslation()
+
+  // Group presets by type
+  const grouped = GROUP_ORDER.reduce(
+    (acc, type) => {
+      acc[type] = PRESETS.filter((p) => p.type === type)
+      return acc
+    },
+    {} as Record<CategoryType, typeof PRESETS>
+  )
+
+  // Compute remaining
+  const totalChecked = Object.values(selectedItems)
+    .filter((i) => i.checked)
+    .reduce((sum, i) => sum + i.amount, 0)
+  const remaining = income - totalChecked
+
+  return (
+    <div>
+      <AllocationBar remaining={remaining} currency={currency} />
+      <div className="space-y-2 pt-2">
+        {GROUP_ORDER.map((type) => {
+          const items = grouped[type]
+          if (!items || items.length === 0) return null
+          return (
+            <fieldset key={type}>
+              <legend className="sr-only">{t(`categories.types.${type}`)}</legend>
+              <CategoryGroupHeader
+                type={type}
+                label={t(`categories.types.${type}`)}
+                count={items.length}
+              />
+              {items.map((preset) => (
+                <PresetItemRow
+                  key={preset.slug}
+                  slug={preset.slug}
+                  type={preset.type}
+                  checked={selectedItems[preset.slug]?.checked ?? false}
+                  amount={selectedItems[preset.slug]?.amount ?? preset.defaultAmount}
+                  onToggle={() => onToggle(preset.slug)}
+                  onAmountChange={(val) => onAmountChange(preset.slug, val)}
+                />
+              ))}
+            </fieldset>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

src/components/setup/ReviewStep.tsx

@@ -0,0 +1,118 @@
+import { useTranslation } from "react-i18next"
+import { PRESETS } from "@/data/presets"
+import type { CategoryType } from "@/lib/types"
+import { Separator } from "@/components/ui/separator"
+import { CategoryGroupHeader } from "./CategoryGroupHeader"
+
+interface ReviewStepProps {
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+  currency: string
+}
+
+const TYPE_ORDER: CategoryType[] = [
+  "income",
+  "bill",
+  "variable_expense",
+  "debt",
+  "saving",
+  "investment",
+]
+
+export function ReviewStep({ income, selectedItems, currency }: ReviewStepProps) {
+  const { t } = useTranslation()
+
+  const fmt = (amount: number) =>
+    new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency,
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 2,
+    }).format(amount)
+
+  const checkedPresets = PRESETS.filter((p) => selectedItems[p.slug]?.checked)
+
+  // Group checked items by type
+  const grouped = TYPE_ORDER.reduce<
+    Record<CategoryType, typeof checkedPresets>
+  >((acc, type) => {
+    const items = checkedPresets.filter((p) => p.type === type)
+    if (items.length > 0) acc[type] = items
+    return acc
+  }, {} as Record<CategoryType, typeof checkedPresets>)
+
+  const totalExpenses = checkedPresets.reduce(
+    (sum, p) => sum + (selectedItems[p.slug]?.amount ?? 0),
+    0
+  )
+  const remaining = income - totalExpenses
+
+  return (
+    <div className="space-y-2">
+      {/* Income row */}
+      <div className="flex justify-between py-2">
+        <span className="text-sm font-semibold">
+          {t("setup.step3.incomeLabel")}
+        </span>
+        <span className="text-sm font-semibold">{fmt(income)}</span>
+      </div>
+      <Separator />
+
+      {/* Grouped items */}
+      {checkedPresets.length === 0 ? (
+        <p className="text-sm text-muted-foreground py-4">
+          {t("setup.step3.empty")}
+        </p>
+      ) : (
+        <>
+          {TYPE_ORDER.filter((type) => grouped[type]).map((type) => (
+            <div key={type}>
+              <CategoryGroupHeader
+                type={type}
+                label={t(`categories.types.${type}`)}
+                count={grouped[type].length}
+              />
+              {grouped[type].map((item) => (
+                <div
+                  key={item.slug}
+                  className="flex justify-between py-1.5 px-1"
+                >
+                  <span className="text-sm">
+                    {t(`presets.${item.type}.${item.slug}`)}
+                  </span>
+                  <span className="text-sm text-right">
+                    {fmt(selectedItems[item.slug]?.amount ?? 0)}
+                  </span>
+                </div>
+              ))}
+            </div>
+          ))}
+        </>
+      )}
+
+      <Separator />
+
+      {/* Totals */}
+      <div className="space-y-1 pt-2">
+        <div className="flex justify-between">
+          <span className="text-sm font-semibold">
+            {t("setup.step3.totalLabel")}
+          </span>
+          <span className="text-sm font-semibold">{fmt(totalExpenses)}</span>
+        </div>
+        <div className="flex justify-between">
+          <span className="text-base font-semibold">
+            {t("setup.step3.remainingLabel")}
+          </span>
+          <span
+            className={`text-base font-semibold ${
+              remaining >= 0 ? "text-on-budget" : "text-destructive"
+            }`}
+          >
+            {fmt(remaining)}
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/setup/WizardStepper.tsx

@@ -0,0 +1,62 @@
+import { useTranslation } from "react-i18next"
+import { Check } from "lucide-react"
+
+interface WizardStepperProps {
+  currentStep: 1 | 2 | 3
+  onStepClick: (step: 1 | 2 | 3) => void
+}
+
+const steps = [1, 2, 3] as const
+
+export function WizardStepper({ currentStep, onStepClick }: WizardStepperProps) {
+  const { t } = useTranslation()
+
+  return (
+    <nav role="navigation" aria-label="Setup progress" className="flex items-center justify-center mb-6">
+      {steps.map((step, index) => {
+        const isCompleted = step < currentStep
+        const isActive = step === currentStep
+        const isFuture = step > currentStep
+
+        return (
+          <div key={step} className="flex items-center">
+            {/* Step group: circle + label */}
+            <div className="flex flex-col items-center gap-1">
+              <button
+                type="button"
+                onClick={() => {
+                  if (!isFuture) onStepClick(step)
+                }}
+                className={`flex items-center justify-center w-8 h-8 rounded-full text-sm font-semibold transition-colors ${
+                  isCompleted || isActive
+                    ? "bg-primary text-primary-foreground cursor-pointer"
+                    : "bg-muted text-muted-foreground border border-border cursor-default"
+                }`}
+                aria-disabled={isFuture}
+                tabIndex={isFuture ? -1 : 0}
+              >
+                {isCompleted ? <Check className="w-4 h-4" /> : step}
+              </button>
+              <span
+                className={`text-xs font-semibold ${
+                  isActive ? "text-foreground" : "text-muted-foreground"
+                }`}
+              >
+                {t(`setup.steps.${step}`)}
+              </span>
+            </div>
+
+            {/* Connector line (not after last step) */}
+            {index < steps.length - 1 && (
+              <div
+                className={`h-px w-16 mx-2 ${
+                  step < currentStep ? "bg-primary" : "bg-border"
+                }`}
+              />
+            )}
+          </div>
+        )
+      })}
+    </nav>
+  )
+}

src/components/shared/PageShell.tsx

@@ -12,7 +12,7 @@ export function PageShell({
   children,
 }: PageShellProps) {
   return (
-    <div className="flex flex-col gap-6">
+    <div className="flex flex-col gap-8">
       <div className="flex items-start justify-between gap-4">
         <div>
           <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>

src/components/ui/checkbox.tsx

@@ -0,0 +1,30 @@
+import * as React from "react"
+import { CheckIcon } from "lucide-react"
+import { Checkbox as CheckboxPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Checkbox({
+  className,
+  ...props
+}: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        "peer size-4 shrink-0 rounded-[4px] border border-input shadow-xs transition-shadow outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground dark:bg-input/30 dark:aria-invalid:ring-destructive/40 dark:data-[state=checked]:bg-primary",
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none"
+      >
+        <CheckIcon className="size-3.5" />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  )
+}
+
+export { Checkbox }

src/data/presets.ts

@@ -0,0 +1,36 @@
+import type { CategoryType } from "@/lib/types"
+
+export interface PresetItem {
+  slug: string
+  type: CategoryType
+  defaultAmount: number // EUR, round number — do NOT suffix with currency symbol
+  item_tier: "fixed" | "variable"
+}
+
+export const PRESETS: PresetItem[] = [
+  // income (4)
+  { slug: "salary",         type: "income",           defaultAmount: 3000, item_tier: "fixed"    },
+  { slug: "freelance",      type: "income",           defaultAmount: 500,  item_tier: "variable" },
+  { slug: "rental_income",  type: "income",           defaultAmount: 800,  item_tier: "fixed"    },
+  { slug: "other_income",   type: "income",           defaultAmount: 200,  item_tier: "variable" },
+  // bill (4)
+  { slug: "rent",           type: "bill",             defaultAmount: 1000, item_tier: "fixed"    },
+  { slug: "electricity",    type: "bill",             defaultAmount: 80,   item_tier: "fixed"    },
+  { slug: "internet",       type: "bill",             defaultAmount: 40,   item_tier: "fixed"    },
+  { slug: "phone",          type: "bill",             defaultAmount: 30,   item_tier: "fixed"    },
+  // variable_expense (5)
+  { slug: "groceries",      type: "variable_expense", defaultAmount: 400,  item_tier: "variable" },
+  { slug: "transport",      type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  { slug: "dining_out",     type: "variable_expense", defaultAmount: 150,  item_tier: "variable" },
+  { slug: "health",         type: "variable_expense", defaultAmount: 50,   item_tier: "variable" },
+  { slug: "clothing",       type: "variable_expense", defaultAmount: 100,  item_tier: "variable" },
+  // debt (2)
+  { slug: "loan_repayment", type: "debt",             defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "credit_card",    type: "debt",             defaultAmount: 100,  item_tier: "fixed"    },
+  // saving (2)
+  { slug: "emergency_fund", type: "saving",           defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "vacation",       type: "saving",           defaultAmount: 100,  item_tier: "fixed"    },
+  // investment (2)
+  { slug: "etf",            type: "investment",       defaultAmount: 200,  item_tier: "fixed"    },
+  { slug: "pension",        type: "investment",       defaultAmount: 100,  item_tier: "fixed"    },
+]

src/hooks/useFirstRunState.ts

@@ -0,0 +1,28 @@
+import { useCategories } from "@/hooks/useCategories"
+import { useTemplate } from "@/hooks/useTemplate"
+
+/**
+ * Derives first-run state from cached category and template queries.
+ * No additional network calls are made — data is read from React Query cache.
+ *
+ * isFirstRun is true when:
+ *   - categories.length === 0 (user has not created any categories), OR
+ *   - items.length === 0 (user has no template items)
+ *
+ * IMPORTANT: Always check `loading` before acting on `isFirstRun`.
+ * While queries are in flight, both arrays default to [] which would
+ * cause isFirstRun to be true spuriously.
+ *
+ * Usage:
+ *   const { isFirstRun, loading } = useFirstRunState()
+ *   if (!loading && isFirstRun) { redirect to /setup }
+ */
+export function useFirstRunState() {
+  const { categories, loading: catLoading } = useCategories()
+  const { items, loading: tmplLoading } = useTemplate()
+
+  return {
+    isFirstRun: categories.length === 0 || items.length === 0,
+    loading: catLoading || tmplLoading,
+  }
+}

src/hooks/useWizardState.ts

@@ -0,0 +1,85 @@
+import { useState, useEffect } from "react"
+import { PRESETS } from "@/data/presets"
+
+export interface WizardState {
+  currentStep: 1 | 2 | 3
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+}
+
+const STORAGE_KEY = (userId: string) => `setup-wizard-${userId}`
+
+function getDefaultState(): WizardState {
+  const selectedItems: Record<string, { checked: boolean; amount: number }> = {}
+  for (const preset of PRESETS) {
+    selectedItems[preset.slug] = {
+      checked: preset.type === "bill" || preset.type === "variable_expense",
+      amount: preset.defaultAmount,
+    }
+  }
+  return { currentStep: 1, income: 3000, selectedItems }
+}
+
+export function useWizardState(userId: string) {
+  const [state, setState] = useState<WizardState>(() => {
+    try {
+      const saved = localStorage.getItem(STORAGE_KEY(userId))
+      if (saved) {
+        const parsed = JSON.parse(saved)
+        // Validate shape (T-07-01 mitigation: validate JSON on load)
+        if (
+          parsed &&
+          typeof parsed.currentStep === "number" &&
+          parsed.currentStep >= 1 &&
+          parsed.currentStep <= 3 &&
+          typeof parsed.income === "number" &&
+          parsed.income >= 0 &&
+          parsed.selectedItems &&
+          typeof parsed.selectedItems === "object"
+        ) {
+          return parsed as WizardState
+        }
+      }
+    } catch {
+      /* ignore corrupt data */
+    }
+    return getDefaultState()
+  })
+
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY(userId), JSON.stringify(state))
+  }, [state, userId])
+
+  const setStep = (step: 1 | 2 | 3) =>
+    setState((s) => ({ ...s, currentStep: step }))
+
+  const setIncome = (income: number) =>
+    setState((s) => ({ ...s, income }))
+
+  const toggleItem = (slug: string) =>
+    setState((s) => ({
+      ...s,
+      selectedItems: {
+        ...s.selectedItems,
+        [slug]: {
+          ...s.selectedItems[slug],
+          checked: !s.selectedItems[slug].checked,
+        },
+      },
+    }))
+
+  const setItemAmount = (slug: string, amount: number) =>
+    setState((s) => ({
+      ...s,
+      selectedItems: {
+        ...s.selectedItems,
+        [slug]: { ...s.selectedItems[slug], amount },
+      },
+    }))
+
+  const clearState = () => {
+    localStorage.removeItem(STORAGE_KEY(userId))
+  }
+
+  return { state, setStep, setIncome, toggleItem, setItemAmount, clearState }
+}

src/i18n/de.json

@@ -120,5 +120,76 @@
     "loading": "Laden...",
     "error": "Etwas ist schiefgelaufen",
     "confirm": "Bestätigen"
+  },
+  "setup": {
+    "title": "Budget einrichten",
+    "step1": {
+      "title": "Monatliches Einkommen",
+      "description": "Wie viel verdienst du pro Monat?",
+      "incomeLabel": "Monatliches Nettoeinkommen",
+      "helper": "Gib dein monatliches Nettoeinkommen ein",
+      "validation": "Bitte gib einen positiven Betrag ein"
+    },
+    "step2": {
+      "title": "Wiederkehrende Posten",
+      "description": "Wähle deine regelmäßigen monatlichen Ausgaben",
+      "remaining": "Verbleibend zu verteilen"
+    },
+    "step3": {
+      "title": "Übersicht",
+      "description": "Bestätige deine Budgetvorlage",
+      "incomeLabel": "Monatliches Einkommen",
+      "totalLabel": "Gesamtausgaben",
+      "remainingLabel": "Verbleibend",
+      "empty": "Keine Posten ausgewählt. Du kannst später Posten zu deiner Vorlage hinzufügen."
+    },
+    "steps": {
+      "1": "Einkommen",
+      "2": "Posten",
+      "3": "Übersicht"
+    },
+    "next": "Nächster Schritt",
+    "back": "Zurück",
+    "skip": "Schritt überspringen",
+    "skipSetup": "Einrichtung überspringen",
+    "complete": "Einrichtung abschließen",
+    "toast": {
+      "success": "Vorlage erstellt! Dein erstes Budget wird automatisch erscheinen.",
+      "error": "Vorlage konnte nicht gespeichert werden. Bitte versuche es erneut.",
+      "partialError": "Einige Posten konnten nicht gespeichert werden. Prüfe deine Vorlagenseite."
+    }
+  },
+  "presets": {
+    "income": {
+      "salary": "Gehalt",
+      "freelance": "Freelance-Einkommen",
+      "rental_income": "Mieteinnahmen",
+      "other_income": "Sonstiges Einkommen"
+    },
+    "bill": {
+      "rent": "Miete",
+      "electricity": "Strom",
+      "internet": "Internet",
+      "phone": "Telefon"
+    },
+    "variable_expense": {
+      "groceries": "Lebensmittel",
+      "transport": "Transport",
+      "dining_out": "Auswärts essen",
+      "health": "Gesundheit & Apotheke",
+      "clothing": "Kleidung"
+    },
+    "debt": {
+      "loan_repayment": "Kreditrückzahlung",
+      "credit_card": "Kreditkarte"
+    },
+    "saving": {
+      "emergency_fund": "Notfallfonds",
+      "vacation": "Urlaubskasse"
+    },
+    "investment": {
+      "etf": "ETF / Indexfonds",
+      "pension": "Altersvorsorge"
+    }
   }
 }

src/i18n/en.json

@@ -120,5 +120,76 @@
     "loading": "Loading...",
     "error": "Something went wrong",
     "confirm": "Confirm"
+  },
+  "setup": {
+    "title": "Set up your budget",
+    "step1": {
+      "title": "Monthly Income",
+      "description": "How much do you earn each month?",
+      "incomeLabel": "Monthly net income",
+      "helper": "Enter your total monthly take-home pay",
+      "validation": "Please enter a positive income amount"
+    },
+    "step2": {
+      "title": "Recurring Items",
+      "description": "Select your regular monthly expenses",
+      "remaining": "Remaining to allocate"
+    },
+    "step3": {
+      "title": "Review",
+      "description": "Confirm your budget template",
+      "incomeLabel": "Monthly income",
+      "totalLabel": "Total expenses",
+      "remainingLabel": "Remaining",
+      "empty": "No items selected. You can add items to your template later."
+    },
+    "steps": {
+      "1": "Income",
+      "2": "Items",
+      "3": "Review"
+    },
+    "next": "Next Step",
+    "back": "Go Back",
+    "skip": "Skip Step",
+    "skipSetup": "Skip setup",
+    "complete": "Complete Setup",
+    "toast": {
+      "success": "Template created! Your first budget will appear automatically.",
+      "error": "Could not save your template. Please try again.",
+      "partialError": "Some items could not be saved. Check your template page."
+    }
+  },
+  "presets": {
+    "income": {
+      "salary": "Salary",
+      "freelance": "Freelance Income",
+      "rental_income": "Rental Income",
+      "other_income": "Other Income"
+    },
+    "bill": {
+      "rent": "Rent",
+      "electricity": "Electricity",
+      "internet": "Internet",
+      "phone": "Phone"
+    },
+    "variable_expense": {
+      "groceries": "Groceries",
+      "transport": "Transport",
+      "dining_out": "Dining Out",
+      "health": "Health & Pharmacy",
+      "clothing": "Clothing"
+    },
+    "debt": {
+      "loan_repayment": "Loan Repayment",
+      "credit_card": "Credit Card"
+    },
+    "saving": {
+      "emergency_fund": "Emergency Fund",
+      "vacation": "Vacation Fund"
+    },
+    "investment": {
+      "etf": "ETF / Index Fund",
+      "pension": "Pension"
+    }
   }
 }

src/index.css

@@ -4,7 +4,7 @@
 
 @theme inline {
   /* Pastel OKLCH Color System */
-  --color-background: oklch(0.98 0.005 260);
+  --color-background: oklch(0.98 0.01 260);
   --color-foreground: oklch(0.25 0.02 260);
 
   --color-card: oklch(1 0 0);
@@ -49,27 +49,27 @@
   --color-saving: oklch(0.55 0.16 220);
   --color-investment: oklch(0.55 0.16 285);
 
-  /* Chart Colors */
-  --color-chart-1: oklch(0.72 0.14 155);
-  --color-chart-2: oklch(0.7 0.14 25);
-  --color-chart-3: oklch(0.72 0.14 50);
-  --color-chart-4: oklch(0.65 0.16 355);
-  --color-chart-5: oklch(0.72 0.14 220);
-
   /* Semantic Status Tokens */
   --color-over-budget: oklch(0.55 0.20 25);
   --color-on-budget: oklch(0.50 0.17 155);
   --color-budget-bar-bg: oklch(0.92 0.01 260);
 
   /* Chart Fill Variants */
-  --color-income-fill: oklch(0.68 0.19 155);
+  --color-income-fill: oklch(0.72 0.22 155);
-  --color-bill-fill: oklch(0.65 0.19 25);
+  --color-bill-fill: oklch(0.70 0.22 25);
-  --color-variable-expense-fill: oklch(0.70 0.18 50);
+  --color-variable-expense-fill: oklch(0.74 0.22 50);
-  --color-debt-fill: oklch(0.60 0.20 355);
+  --color-debt-fill: oklch(0.66 0.23 355);
-  --color-saving-fill: oklch(0.68 0.18 220);
+  --color-saving-fill: oklch(0.72 0.22 220);
-  --color-investment-fill: oklch(0.65 0.18 285);
+  --color-investment-fill: oklch(0.68 0.22 285);
 
-  --radius: 0.625rem;
+  --radius: 0;
+  --radius-xs: 0;
+  --radius-sm: 0;
+  --radius-md: 0;
+  --radius-lg: 0;
+  --radius-xl: 0;
+  --radius-2xl: 0;
+  --radius-3xl: 0;
 
   /* Collapsible animation */
   --animate-collapsible-open: collapsible-open 200ms ease-out;
@@ -97,3 +97,13 @@
     font-feature-settings: "rlig" 1, "calt" 1;
   }
 }
+
+/* Third-party radius overrides */
+.recharts-rectangle {
+  rx: 0;
+  ry: 0;
+}
+
+[data-sonner-toast] {
+  border-radius: 0 !important;
+}

src/lib/types.ts

@@ -13,6 +13,7 @@ export interface Profile {
   display_name: string | null
   locale: string
   currency: string
+  setup_completed: boolean
   created_at: string
   updated_at: string
 }

src/pages/BudgetDetailPage.tsx

@@ -287,7 +287,7 @@ export default function BudgetDetailPage() {
         <Skeleton className="h-4 w-24" />
         {[1, 2, 3].map((i) => (
           <div key={i} className="space-y-2">
-            <div className="flex items-center gap-3 rounded-sm border-l-4 border-muted bg-muted/30 px-3 py-2">
+            <div className="flex items-center gap-3 border-l-4 border-muted bg-muted/30 px-3 py-2">
               <Skeleton className="h-4 w-28" />
             </div>
             {[1, 2].map((j) => (
@@ -300,7 +300,7 @@ export default function BudgetDetailPage() {
             ))}
           </div>
         ))}
-        <Skeleton className="h-20 w-full rounded-md" />
+        <Skeleton className="h-20 w-full" />
       </div>
     </PageShell>
   )
@@ -350,7 +350,7 @@ export default function BudgetDetailPage() {
               <div key={type}>
                 {/* Group heading */}
                 <div
-                  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+                  className="mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"
                   style={{ borderLeftColor: categoryColors[type] }}
                 >
                   <span className="text-sm font-semibold">{t(`categories.types.${type}`)}</span>
@@ -436,7 +436,7 @@ export default function BudgetDetailPage() {
           })}
 
           {/* Overall totals */}
-          <div className="rounded-md border p-4">
+          <div className="border p-4">
             <div className="grid grid-cols-3 gap-4 text-sm">
               <div>
                 <p className="text-muted-foreground">{t("budgets.budgeted")}</p>
@@ -494,7 +494,7 @@ export default function BudgetDetailPage() {
                       <SelectGroup key={type}>
                         <SelectLabel className="flex items-center gap-1.5">
                           <div
-                            className="size-2 rounded-full"
+                            className="size-2"
                             style={{ backgroundColor: categoryColors[type] }}
                           />
                           {t(`categories.types.${type}`)}

src/pages/BudgetListPage.tsx

@@ -240,7 +240,7 @@ export default function BudgetListPage() {
             </div>
 
             {/* Template toggle */}
-            <div className="flex items-center gap-3 rounded-md border p-3">
+            <div className="flex items-center gap-3 border p-3">
               <input
                 id="use-template"
                 type="checkbox"

src/pages/CategoriesPage.tsx

@@ -95,17 +95,17 @@ export default function CategoriesPage() {
 
   if (loading) return (
     <PageShell title={t("categories.title")}>
-      <div className="space-y-6">
+      <div className="space-y-8">
         {[1, 2, 3].map((i) => (
           <div key={i} className="space-y-2">
-            <div className="flex items-center gap-3 rounded-sm border-l-4 border-muted bg-muted/30 px-3 py-2">
+            <div className="flex items-center gap-3 border-l-4 border-muted bg-muted/30 px-3 py-2">
               <Skeleton className="h-4 w-28" />
             </div>
             {[1, 2].map((j) => (
               <div key={j} className="flex items-center gap-4 px-4 py-2.5 border-b border-border">
                 <Skeleton className="h-4 w-36" />
-                <Skeleton className="h-5 w-16 rounded-full" />
+                <Skeleton className="h-5 w-16" />
-                <Skeleton className="ml-auto h-7 w-7 rounded-md" />
+                <Skeleton className="ml-auto h-7 w-7" />
               </div>
             ))}
           </div>
@@ -127,11 +127,11 @@ export default function CategoriesPage() {
       {categories.length === 0 ? (
         <p className="text-muted-foreground">{t("categories.empty")}</p>
       ) : (
-        <div className="space-y-6">
+        <div className="space-y-8">
           {grouped.map(({ type, items }) => (
             <div key={type}>
               <div
-                className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+                className="mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"
                 style={{ borderLeftColor: categoryColors[type] }}
               >
                 <span className="text-sm font-semibold">{t(`categories.types.${type}`)}</span>

src/pages/DashboardPage.tsx

@@ -1,5 +1,7 @@
 import { useState, useMemo } from "react"
+import { Navigate } from "react-router-dom"
 import { useTranslation } from "react-i18next"
+import { useFirstRunState } from "@/hooks/useFirstRunState"
 import { useBudgets, useBudgetDetail } from "@/hooks/useBudgets"
 import { useMonthParam } from "@/hooks/useMonthParam"
 import type { CategoryType } from "@/lib/types"
@@ -183,7 +185,7 @@ function DashboardContent({ budgetId }: { budgetId: string }) {
   const carryoverIsNegative = carryover < 0
 
   return (
-    <div className="space-y-6">
+    <div className="space-y-8">
       {/* Summary cards */}
       <SummaryStrip
         income={{
@@ -204,7 +206,7 @@ function DashboardContent({ budgetId }: { budgetId: string }) {
       />
 
       {/* 3-column chart grid */}
-      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
+      <div className="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
         <Card>
           <CardHeader>
             <CardTitle className="text-base">{t("dashboard.expenseDonut")}</CardTitle>
@@ -271,6 +273,7 @@ function DashboardContent({ budgetId }: { budgetId: string }) {
 
 export default function DashboardPage() {
   const { t } = useTranslation()
+  const { isFirstRun, loading: firstRunLoading } = useFirstRunState()
   const { month } = useMonthParam()
   const { budgets, loading, createBudget, generateFromTemplate } = useBudgets()
 
@@ -286,6 +289,9 @@ export default function DashboardPage() {
 
   const [parsedYear, parsedMonth] = month.split("-").map(Number)
 
+  if (firstRunLoading) return <DashboardSkeleton />
+  if (isFirstRun) return <Navigate to="/setup" replace />
+
   return (
     <PageShell
       title={t("dashboard.title")}

src/pages/QuickAddPage.tsx

@@ -95,9 +95,9 @@ export default function QuickAddPage() {
       <div className="space-y-1">
         {[1, 2, 3, 4, 5].map((i) => (
           <div key={i} className="flex items-center gap-4 px-4 py-2.5 border-b border-border">
-            <Skeleton className="h-5 w-10 rounded-full" />
+            <Skeleton className="h-5 w-10" />
             <Skeleton className="h-4 w-36" />
-            <Skeleton className="ml-auto h-7 w-7 rounded-md" />
+            <Skeleton className="ml-auto h-7 w-7" />
           </div>
         ))}
       </div>

src/pages/SettingsPage.tsx

@@ -66,7 +66,7 @@ export default function SettingsPage() {
     <PageShell title={t("settings.title")}>
       <div className="max-w-lg">
         <Card>
-          <CardContent className="space-y-4 pt-6">
+          <CardContent className="space-y-6 pt-6">
             {[1, 2, 3].map((i) => (
               <div key={i} className="space-y-2">
                 <Skeleton className="h-4 w-24" />
@@ -84,7 +84,7 @@ export default function SettingsPage() {
     <PageShell title={t("settings.title")}>
       <div className="max-w-lg">
         <Card>
-          <CardContent className="space-y-4 pt-6">
+          <CardContent className="space-y-6 pt-6">
             <div className="space-y-2">
               <Label>{t("settings.displayName")}</Label>
               <Input

src/pages/SetupPage.tsx

@@ -0,0 +1,290 @@
+import { useState } from "react"
+import { useTranslation } from "react-i18next"
+import { useNavigate } from "react-router-dom"
+import { useQueryClient } from "@tanstack/react-query"
+import { toast } from "sonner"
+import { useAuth } from "@/hooks/useAuth"
+import { useWizardState } from "@/hooks/useWizardState"
+import { useCategories } from "@/hooks/useCategories"
+import { useTemplate } from "@/hooks/useTemplate"
+import { supabase } from "@/lib/supabase"
+import { PRESETS } from "@/data/presets"
+import type { Profile } from "@/lib/types"
+import { WizardStepper } from "@/components/setup/WizardStepper"
+import { IncomeStep } from "@/components/setup/IncomeStep"
+import { RecurringItemsStep } from "@/components/setup/RecurringItemsStep"
+import { ReviewStep } from "@/components/setup/ReviewStep"
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { Skeleton } from "@/components/ui/skeleton"
+import { useEffect } from "react"
+
+export default function SetupPage() {
+  const { t } = useTranslation()
+  const { user, loading: authLoading } = useAuth()
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+  const [profile, setProfile] = useState<Profile | null>(null)
+  const [profileLoading, setProfileLoading] = useState(true)
+  const [completing, setCompleting] = useState(false)
+
+  const { categories, create } = useCategories()
+  const { createItem } = useTemplate()
+
+  useEffect(() => {
+    if (!user) return
+    supabase
+      .from("profiles")
+      .select("*")
+      .eq("id", user.id)
+      .single()
+      .then(({ data }) => {
+        if (data) setProfile(data)
+        setProfileLoading(false)
+      })
+  }, [user])
+
+  const userId = user?.id ?? ""
+  const currency = profile?.currency ?? "EUR"
+  const { state, setStep, setIncome, toggleItem, setItemAmount, clearState } =
+    useWizardState(userId)
+
+  const [incomeError, setIncomeError] = useState<string | null>(null)
+
+  const loading = authLoading || profileLoading
+
+  if (loading) {
+    return (
+      <div className="flex min-h-screen items-center justify-center bg-background p-4">
+        <div className="w-full max-w-2xl">
+          <Skeleton className="h-12 w-64 mx-auto mb-6" />
+          <Skeleton className="h-64 w-full" />
+        </div>
+      </div>
+    )
+  }
+
+  const stepTitles: Record<1 | 2 | 3, string> = {
+    1: t("setup.step1.title"),
+    2: t("setup.step2.title"),
+    3: t("setup.step3.title"),
+  }
+
+  const stepDescriptions: Record<1 | 2 | 3, string> = {
+    1: t("setup.step1.description"),
+    2: t("setup.step2.description"),
+    3: t("setup.step3.description"),
+  }
+
+  function handleNext() {
+    if (state.currentStep === 1) {
+      if (!state.income || state.income <= 0) {
+        setIncomeError(t("setup.step1.validation"))
+        return
+      }
+      setIncomeError(null)
+      setStep(2)
+    } else if (state.currentStep === 2) {
+      setStep(3)
+    }
+  }
+
+  function handleBack() {
+    if (state.currentStep === 2) setStep(1)
+    else if (state.currentStep === 3) setStep(2)
+  }
+
+  function handleSkipStep() {
+    if (state.currentStep === 1) setStep(2)
+    else if (state.currentStep === 2) setStep(3)
+    else if (state.currentStep === 3) handleSkipSetup()
+  }
+
+  function handleStepClick(step: 1 | 2 | 3) {
+    if (step <= state.currentStep) {
+      setStep(step)
+    }
+  }
+
+  async function handleComplete() {
+    setCompleting(true)
+    try {
+      const checkedItems = PRESETS.filter(
+        (p) => state.selectedItems[p.slug]?.checked
+      )
+
+      // 1. Determine unique category types needed
+      const typesNeeded = [...new Set(checkedItems.map((i) => i.type))]
+
+      // 2. Create one category per type
+      const categoryMap: Record<string, string> = {}
+      for (const type of typesNeeded) {
+        try {
+          const cat = await create.mutateAsync({
+            name: t(`categories.types.${type}`),
+            type,
+          })
+          categoryMap[type] = cat.id
+        } catch (e: any) {
+          // Unique constraint violation (23505) = category already exists, fetch it
+          if (e?.code === "23505" || e?.message?.includes("duplicate")) {
+            const existing = categories.find((c) => c.type === type)
+            if (existing) categoryMap[type] = existing.id
+          } else {
+            throw e
+          }
+        }
+      }
+
+      // 3. If categories were fetched from cache but not found, refetch
+      if (Object.keys(categoryMap).length < typesNeeded.length) {
+        await queryClient.invalidateQueries({ queryKey: ["categories"] })
+      }
+
+      // 4. Create template items for each checked preset
+      let partialFailure = false
+      for (const item of checkedItems) {
+        try {
+          await createItem.mutateAsync({
+            category_id: categoryMap[item.type],
+            item_tier: item.item_tier,
+            budgeted_amount: state.selectedItems[item.slug].amount,
+          })
+        } catch {
+          partialFailure = true
+        }
+      }
+
+      // 5. Mark setup complete
+      await supabase
+        .from("profiles")
+        .update({ setup_completed: true })
+        .eq("id", user!.id)
+
+      // 6. Clear wizard state
+      clearState()
+
+      // 7. Invalidate queries to prevent redirect loop
+      await queryClient.invalidateQueries({ queryKey: ["categories"] })
+      await queryClient.invalidateQueries({ queryKey: ["template-items"] })
+
+      // 8. Toast and redirect
+      if (partialFailure) {
+        toast.error(t("setup.toast.partialError"))
+      } else {
+        toast.success(t("setup.toast.success"))
+      }
+      navigate("/", { replace: true })
+    } catch {
+      toast.error(t("setup.toast.error"))
+    } finally {
+      setCompleting(false)
+    }
+  }
+
+  async function handleSkipSetup() {
+    clearState()
+    await supabase
+      .from("profiles")
+      .update({ setup_completed: true })
+      .eq("id", user!.id)
+    navigate("/", { replace: true })
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background p-4">
+      <div className="w-full max-w-2xl">
+        <WizardStepper
+          currentStep={state.currentStep}
+          onStepClick={handleStepClick}
+        />
+
+        <Card className="w-full border border-border shadow-sm">
+          <CardHeader className="pb-2">
+            <CardTitle className="text-xl font-semibold">
+              {stepTitles[state.currentStep]}
+            </CardTitle>
+            <p className="text-sm text-muted-foreground">
+              {stepDescriptions[state.currentStep]}
+            </p>
+          </CardHeader>
+          <CardContent className="space-y-6">
+            {state.currentStep === 1 && (
+              <IncomeStep
+                income={state.income}
+                onIncomeChange={setIncome}
+                currency={currency}
+                error={incomeError}
+              />
+            )}
+
+            {state.currentStep === 2 && (
+              <RecurringItemsStep
+                selectedItems={state.selectedItems}
+                income={state.income}
+                currency={currency}
+                onToggle={toggleItem}
+                onAmountChange={setItemAmount}
+              />
+            )}
+
+            {state.currentStep === 3 && (
+              <ReviewStep
+                income={state.income}
+                selectedItems={state.selectedItems}
+                currency={currency}
+              />
+            )}
+
+            {/* Bottom navigation */}
+            <div className="flex justify-between items-center pt-4 border-t border-border">
+              <div className="flex gap-2">
+                {state.currentStep > 1 && (
+                  <Button
+                    variant="ghost"
+                    onClick={handleBack}
+                    disabled={completing}
+                  >
+                    {t("setup.back")}
+                  </Button>
+                )}
+                <Button
+                  variant="ghost"
+                  className="text-muted-foreground"
+                  onClick={handleSkipStep}
+                  disabled={completing}
+                >
+                  {t("setup.skip")}
+                </Button>
+              </div>
+              <div>
+                {state.currentStep < 3 && (
+                  <Button onClick={handleNext}>{t("setup.next")}</Button>
+                )}
+                {state.currentStep === 3 && (
+                  <Button onClick={handleComplete} disabled={completing}>
+                    {t("setup.complete")}
+                  </Button>
+                )}
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+
+        <button
+          type="button"
+          className="mt-4 text-sm text-muted-foreground underline block mx-auto"
+          onClick={handleSkipSetup}
+          disabled={completing}
+        >
+          {t("setup.skipSetup")}
+        </button>
+      </div>
+    </div>
+  )
+}

src/pages/TemplatePage.tsx

@@ -239,23 +239,23 @@ export default function TemplatePage() {
   // ------------------------------------------------------------------
 
   if (loading) return (
-    <div className="flex flex-col gap-6">
+    <div className="flex flex-col gap-8">
       <div className="flex items-start justify-between gap-4">
         <Skeleton className="h-8 w-48" />
         <Skeleton className="h-9 w-24" />
       </div>
-      <div className="space-y-6">
+      <div className="space-y-8">
         {[1, 2].map((i) => (
           <div key={i} className="space-y-2">
-            <div className="flex items-center gap-3 rounded-sm border-l-4 border-muted bg-muted/30 px-3 py-2">
+            <div className="flex items-center gap-3 border-l-4 border-muted bg-muted/30 px-3 py-2">
               <Skeleton className="h-4 w-28" />
             </div>
             {[1, 2, 3].map((j) => (
               <div key={j} className="flex items-center gap-4 px-4 py-2.5 border-b border-border">
                 <Skeleton className="h-4 w-36" />
-                <Skeleton className="h-5 w-16 rounded-full" />
+                <Skeleton className="h-5 w-16" />
                 <Skeleton className="ml-auto h-4 w-20" />
-                <Skeleton className="h-7 w-7 rounded-md" />
+                <Skeleton className="h-7 w-7" />
               </div>
             ))}
           </div>
@@ -265,7 +265,7 @@ export default function TemplatePage() {
   )
 
   return (
-    <div className="flex flex-col gap-6">
+    <div className="flex flex-col gap-8">
       {/* Header — mirrors PageShell's flex items-start justify-between gap-4 layout */}
       <div className="flex items-start justify-between gap-4">
         <TemplateName
@@ -284,12 +284,12 @@ export default function TemplatePage() {
       {items.length === 0 ? (
         <p className="text-muted-foreground">{t("template.empty")}</p>
       ) : (
-        <div className="space-y-6">
+        <div className="space-y-8">
           {grouped.map(({ type, items: groupItems }) => (
             <div key={type}>
               {/* Group heading */}
               <div
-                className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
+                className="mb-2 flex items-center gap-3 border-l-4 bg-muted/30 px-3 py-2"
                 style={{ borderLeftColor: categoryColors[type] }}
               >
                 <span className="text-sm font-semibold">{t(`categories.types.${type}`)}</span>
@@ -382,7 +382,7 @@ export default function TemplatePage() {
                         <SelectGroup key={type}>
                           <SelectLabel className="flex items-center gap-1.5">
                             <div
-                              className="size-2 rounded-full"
+                              className="size-2"
                               style={{ backgroundColor: categoryColors[type] }}
                             />
                             {t(`categories.types.${type}`)}

supabase/migrations/006_uniqueness_constraints.sql

@@ -0,0 +1,28 @@
+-- Migration 006: Add uniqueness constraints to budgets and categories
+-- Safe deduplication runs first inside the transaction before each constraint.
+
+BEGIN;
+
+-- Deduplicate budgets: keep the oldest row per (user_id, start_date)
+DELETE FROM budgets
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, start_date) id
+  FROM budgets
+  ORDER BY user_id, start_date, created_at ASC
+);
+
+ALTER TABLE budgets
+  ADD CONSTRAINT budgets_user_month_unique UNIQUE (user_id, start_date);
+
+-- Deduplicate categories: keep the oldest row per (user_id, name)
+DELETE FROM categories
+WHERE id NOT IN (
+  SELECT DISTINCT ON (user_id, name) id
+  FROM categories
+  ORDER BY user_id, name, created_at ASC
+);
+
+ALTER TABLE categories
+  ADD CONSTRAINT categories_user_name_unique UNIQUE (user_id, name);
+
+COMMIT;

supabase/migrations/007_setup_completed.sql

@@ -0,0 +1,18 @@
+-- Migration 007: Add setup_completed to profiles
+-- New signups default to false (not set up).
+-- Existing users who have any categories are backfilled to true (already set up).
+-- Wider backfill also includes users with template items to protect against
+-- edge case where user created template items but skipped category creation.
+
+ALTER TABLE profiles
+  ADD COLUMN setup_completed boolean NOT NULL DEFAULT false;
+
+-- Backfill: users with categories OR template items are considered set up
+UPDATE profiles
+SET setup_completed = true
+WHERE id IN (
+  SELECT DISTINCT user_id FROM categories
+  UNION
+  SELECT t.user_id FROM templates t
+  INNER JOIN template_items ti ON ti.template_id = t.id
+);