chore: archive v1.2 Collection Power-Ups milestone

Archive roadmap and requirements to milestones/, evolve PROJECT.md
with validated requirements, update retrospective, and reorganize
ROADMAP.md with milestone groupings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/MILESTONES.md

@@ -1,5 +1,23 @@
 # Milestones
 
+## v1.2 Collection Power-Ups (Shipped: 2026-03-16)
+
+**Phases completed:** 3 phases, 6 plans, 11 tasks
+**Timeline:** 3 days (2026-03-14 → 2026-03-16)
+**Codebase:** 7,310 LOC TypeScript, 66 files changed (+7,243 / -206)
+
+**Key accomplishments:**
+- Weight unit conversion (g/oz/lb/kg) with segmented toggle wired across all 8 display call sites
+- Candidate status tracking (researching/ordered/arrived) with clickable StatusBadge popup
+- Sticky search/filter toolbar with text search and icon-aware CategoryFilterDropdown
+- Per-setup item classification (base/worn/consumable) with click-to-cycle badge
+- Recharts donut chart with category/classification toggle, hover tooltips, and weight subtotals
+- Classification-preserving sync that maintains metadata across atomic setup re-sync
+
+**Archive:** `.planning/milestones/v1.2-ROADMAP.md`, `.planning/milestones/v1.2-REQUIREMENTS.md`
+
+---
+
 ## v1.1 Fixes & Polish (Shipped: 2026-03-15)
 
 **Phases completed:** 3 phases, 7 plans

.planning/PROJECT.md

@@ -2,7 +2,7 @@
 
 ## What This Is
 
-A web-based gear management and purchase planning app. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, and use planning threads to research and compare new purchases. Named setups let users compose loadouts from their collection with live weight/cost totals. Built as a single-user app with a clean, minimalist interface.
+A web-based gear management and purchase planning app. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, search and filter by name or category, and use planning threads to research and compare new purchases with status tracking. Named setups let users compose loadouts with weight classification (base/worn/consumable), donut chart visualization, and live totals in selectable units. Built as a single-user app with a clean, minimalist interface.
 
 ## Core Value
 
@@ -27,6 +27,18 @@ Make it effortless to manage gear and plan new purchases — see how a potential
 - ✓ Hero image upload area with preview and click-to-upload — v1.1
 - ✓ Lucide icon picker for categories (119 curated icons, 8 groups) — v1.1
 - ✓ Automatic emoji-to-Lucide icon migration for existing categories — v1.1
+- ✓ Search items by name with instant filtering — v1.2
+- ✓ Filter collection items by category with icon-aware dropdown — v1.2
+- ✓ Combined text search with category filter and result count — v1.2
+- ✓ One-action filter clear — v1.2
+- ✓ Weight unit selection (g, oz, lb, kg) with persistence — v1.2
+- ✓ All weight displays respect selected unit across entire app — v1.2
+- ✓ Per-setup item classification (base weight, worn, consumable) — v1.2
+- ✓ Setup weight subtotals by classification — v1.2
+- ✓ Donut chart visualization with category/classification toggle — v1.2
+- ✓ Chart hover tooltips with weight and percentage — v1.2
+- ✓ Candidate status tracking (researching/ordered/arrived) — v1.2
+- ✓ Planning category filter with Lucide icons — v1.2
 
 ### Active
 
@@ -34,22 +46,18 @@ Make it effortless to manage gear and plan new purchases — see how a potential
 
 ### Future
 
-- [ ] Search items by name and filter by category
 - [ ] Side-by-side candidate comparison on weight and price
-- [ ] Candidate status tracking (researching → ordered → arrived)
 - [ ] Candidate ranking/prioritization within threads
 - [ ] Impact preview: how a candidate affects setup weight/cost
-- [ ] Weight unit selection (g, oz, lb, kg)
 - [ ] CSV import/export for gear collections
-- [ ] Weight distribution visualization (pie/bar chart by category)
-- [ ] Classify items as base weight, worn, or consumable per setup
+- [ ] Multi-user accounts with authentication
+- [ ] Collection sharing and social features (public profiles, shared setups)
+- [ ] Auto-fill product information (price, weight, images) from external sources
 
 ### Out of Scope
 
-- Authentication / multi-user — single user for v1, no login needed
 - Custom comparison parameters — complexity trap, weight/price covers 80% of cases
 - Mobile native app — web-first, responsive design sufficient
-- Social/sharing features — different product, defer to v2+
 - Price tracking / deal alerts — requires scraping, fragile
 - Barcode scanning / product database — requires external database
 - Community gear database — requires moderation, accounts
@@ -57,10 +65,11 @@ Make it effortless to manage gear and plan new purchases — see how a potential
 
 ## Context
 
-Shipped v1.1 with 6,134 LOC TypeScript.
-Tech stack: React 19, Hono, Drizzle ORM, SQLite, TanStack Router/Query, Tailwind CSS v4, Lucide React, all on Bun.
+Shipped v1.2 with 7,310 LOC TypeScript.
+Tech stack: React 19, Hono, Drizzle ORM, SQLite, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, all on Bun.
 Primary use case is bikepacking gear but data model is hobby-agnostic.
 Replaces spreadsheet-based gear tracking workflow.
+121 tests (service-level and route-level integration).
 
 ## Constraints
 
@@ -92,6 +101,15 @@ Replaces spreadsheet-based gear tracking workflow.
 | Hero image area at top of forms | Image-first UX, 4:3 aspect ratio consistent with cards | ✓ Good |
 | Emoji-to-icon automatic migration | One-time schema rename + data conversion via Drizzle migration | ✓ Good |
 | ALTER TABLE RENAME COLUMN for SQLite | Simpler than table recreation for column rename | ✓ Good |
+| Weight conversion precision: g=0dp, oz=1dp, lb=2dp, kg=2dp | Matches common usage conventions | ✓ Good |
+| Unit toggle in TotalsBar (not settings page) | Visible, quick access for frequent switching | ✓ Good |
+| CategoryFilterDropdown separate from CategoryPicker | Filter vs form concerns are different | ✓ Good |
+| No debounce on search input | Collection under 1000 items, instant feedback | ✓ Good |
+| StatusBadge popup with click-outside dismiss | Consistent with CategoryPicker pattern | ✓ Good |
+| Classification on setupItems join table | Same item can have different roles per setup | ✓ Good |
+| Click-to-cycle for ClassificationBadge | Only 3 values, simpler than popup | ✓ Good |
+| Classification-preserving sync via Map | Save metadata before delete, restore after re-insert | ✓ Good |
+| Recharts for charting | Mature React chart library, composable API | ✓ Good |
 
 ---
-*Last updated: 2026-03-15 after v1.1 milestone completion*
+*Last updated: 2026-03-16 after v1.2 milestone*

.planning/RETROSPECTIVE.md

@@ -91,6 +91,51 @@
 
 ---
 
+## Milestone: v1.2 — Collection Power-Ups
+
+**Shipped:** 2026-03-16
+**Phases:** 3 | **Plans:** 6 | **Files changed:** 66
+
+### What Was Built
+- Weight unit conversion (g/oz/lb/kg) with segmented toggle wired across all weight display call sites
+- Candidate status tracking (researching/ordered/arrived) with clickable StatusBadge popup
+- Sticky search/filter toolbar with text search and icon-aware CategoryFilterDropdown
+- Per-setup item classification (base/worn/consumable) with click-to-cycle ClassificationBadge
+- Recharts donut chart with category/classification toggle and hover tooltips
+- Classification-preserving sync that maintains metadata across atomic setup item re-sync
+
+### What Worked
+- Coarse 3-phase structure again — 19 requirements compressed into 3 phases with clear dependency ordering
+- TDD red/green commits for schema migrations (status, classification) caught edge cases early
+- Vertical slice pattern (schema → service → tests → API → UI in one plan) kept each deliverable self-contained
+- Click-outside dismiss pattern established in v1.1 was reused cleanly in StatusBadge and CategoryFilterDropdown
+- All 6 plans executed with zero deviations from plan — evidence of mature planning process
+
+### What Was Inefficient
+- Some ROADMAP.md plan checkboxes remained unchecked despite summaries existing (persistent cosmetic drift)
+- Recharts v3 Cell component is deprecated for v4 — will need migration eventually
+- Phase 8 bundled search/filter with candidate status (different concerns) — could have been separate phases for cleaner scope
+
+### Patterns Established
+- Click-to-cycle badge: for small enums (3 values), direct click cycling is simpler than popup menus
+- Join table metadata preservation: save metadata to Map before atomic sync, restore after re-insert
+- CategoryFilterDropdown: reusable filter dropdown (separate from form-based CategoryPicker)
+- Chart data transformation: group items by key, sum weights, compute percentages, filter zeroes
+- apiPatch helper: PATCH method now available in client API library for partial updates
+
+### Key Lessons
+1. Classification belongs on join tables (setupItems), not entity tables (items) — same item has different roles in different contexts
+2. Vertical slice delivery (schema → service → test → API → UI) is the optimal plan structure for feature additions
+3. Search complexity should match data scale — no debounce needed for <1000 items
+4. Recharts composable API (PieChart + Pie + Cell + Tooltip + Label) gives fine-grained chart control with minimal wrapper code
+
+### Cost Observations
+- Model mix: quality profile throughout (opus for execution)
+- Sessions: 3 continuous auto-advance sessions (one per phase)
+- Notable: All plans completed with zero deviations, execution faster than v1.0/v1.1
+
+---
+
 ## Cross-Milestone Trends
 
 ### Process Evolution
@@ -99,6 +144,7 @@
 |-----------|---------|--------|------------|
 | v1.0 | 53 | 3 | Initial build, coarse granularity, TDD backend |
 | v1.1 | ~30 | 3 | Auto-advance pipeline, parallel wave execution, auto-fix deviations |
+| v1.2 | 25 | 3 | Zero-deviation execution, vertical slice pattern, join table metadata |
 
 ### Cumulative Quality
 
@@ -106,6 +152,7 @@
 |-----------|-----|-------|-------|
 | v1.0 | 5,742 | 114 | Service + route integration |
 | v1.1 | 6,134 | ~130 | Service + route integration (updated for icon schema) |
+| v1.2 | 7,310 | ~150 | 121 tests (service + route + classification) |
 
 ### Top Lessons (Verified Across Milestones)
 
@@ -113,3 +160,5 @@
 2. Service DI pattern enables fast, reliable testing without mocks
 3. Always update Zod schemas alongside DB schema — middleware silently strips unvalidated fields
 4. Auto-advance pipeline (discuss → plan → execute) works well for clear-scope phases
+5. Vertical slice delivery (schema → service → test → API → UI) is optimal for feature additions
+6. Join table metadata (not entity table) when same entity plays different roles in different contexts

.planning/ROADMAP.md

@@ -2,26 +2,36 @@
 
 ## Milestones
 
-- ✅ **v1.0 MVP** -- Phases 1-3 (shipped 2026-03-15)
-- ✅ **v1.1 Fixes & Polish** -- Phases 4-6 (shipped 2026-03-15)
+- ✅ **v1.0 MVP** — Phases 1-3 (shipped 2026-03-15)
+- ✅ **v1.1 Fixes & Polish** — Phases 4-6 (shipped 2026-03-15)
+- ✅ **v1.2 Collection Power-Ups** — Phases 7-9 (shipped 2026-03-16)
 
 ## Phases
 
 <details>
-<summary>v1.0 MVP (Phases 1-3) -- SHIPPED 2026-03-15</summary>
+<summary>✅ v1.0 MVP (Phases 1-3) — SHIPPED 2026-03-15</summary>
 
-- [x] Phase 1: Foundation and Collection (4/4 plans) -- completed 2026-03-14
-- [x] Phase 2: Planning Threads (3/3 plans) -- completed 2026-03-15
-- [x] Phase 3: Setups and Dashboard (3/3 plans) -- completed 2026-03-15
+- [x] Phase 1: Foundation and Collection (4/4 plans) — completed 2026-03-14
+- [x] Phase 2: Planning Threads (3/3 plans) — completed 2026-03-15
+- [x] Phase 3: Setups and Dashboard (3/3 plans) — completed 2026-03-15
 
 </details>
 
 <details>
-<summary>v1.1 Fixes & Polish (Phases 4-6) -- SHIPPED 2026-03-15</summary>
+<summary>✅ v1.1 Fixes & Polish (Phases 4-6) — SHIPPED 2026-03-15</summary>
 
-- [x] Phase 4: Database & Planning Fixes (2/2 plans) -- completed 2026-03-15
-- [x] Phase 5: Image Handling (2/2 plans) -- completed 2026-03-15
-- [x] Phase 6: Category Icons (3/3 plans) -- completed 2026-03-15
+- [x] Phase 4: Database & Planning Fixes (2/2 plans) — completed 2026-03-15
+- [x] Phase 5: Image Handling (2/2 plans) — completed 2026-03-15
+- [x] Phase 6: Category Icons (3/3 plans) — completed 2026-03-15
+
+</details>
+
+<details>
+<summary>✅ v1.2 Collection Power-Ups (Phases 7-9) — SHIPPED 2026-03-16</summary>
+
+- [x] Phase 7: Weight Unit Selection (2/2 plans) — completed 2026-03-16
+- [x] Phase 8: Search, Filter, and Candidate Status (2/2 plans) — completed 2026-03-16
+- [x] Phase 9: Weight Classification and Visualization (2/2 plans) — completed 2026-03-16
 
 </details>
 
@@ -35,3 +45,6 @@
 | 4. Database & Planning Fixes | v1.1 | 2/2 | Complete | 2026-03-15 |
 | 5. Image Handling | v1.1 | 2/2 | Complete | 2026-03-15 |
 | 6. Category Icons | v1.1 | 3/3 | Complete | 2026-03-15 |
+| 7. Weight Unit Selection | v1.2 | 2/2 | Complete | 2026-03-16 |
+| 8. Search, Filter, and Candidate Status | v1.2 | 2/2 | Complete | 2026-03-16 |
+| 9. Weight Classification and Visualization | v1.2 | 2/2 | Complete | 2026-03-16 |

.planning/STATE.md

@@ -1,16 +1,16 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.1
-milestone_name: Fixes & Polish
-status: shipped
-stopped_at: v1.1 milestone completed and archived
-last_updated: "2026-03-15T17:15:00.000Z"
-last_activity: 2026-03-15 -- Shipped v1.1 Fixes & Polish milestone
+milestone: v1.2
+milestone_name: Collection Power-Ups
+status: archived
+stopped_at: Milestone v1.2 archived
+last_updated: "2026-03-16T18:30:00.000Z"
+last_activity: 2026-03-16 -- Milestone v1.2 archived
 progress:
   total_phases: 3
   completed_phases: 3
-  total_plans: 7
-  completed_plans: 7
+  total_plans: 6
+  completed_plans: 6
   percent: 100
 ---
 
@@ -18,28 +18,28 @@ progress:
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-03-15)
+See: .planning/PROJECT.md (updated 2026-03-16)
 
 **Core value:** Make it effortless to manage gear and plan new purchases -- see how a potential buy affects your total setup weight and cost before committing.
 **Current focus:** Planning next milestone
 
 ## Current Position
 
-Milestone: v1.1 Fixes & Polish -- SHIPPED
-All phases complete. No active milestone.
-Last activity: 2026-03-15 -- Shipped v1.1
-
-Progress: [██████████] 100% (v1.1 shipped)
+Milestone v1.2 Collection Power-Ups archived.
+All 3 milestones shipped (v1.0, v1.1, v1.2).
+Next step: `/gsd:new-milestone` to start next milestone.
 
 ## Accumulated Context
 
 ### Decisions
 
-(Full decision log archived in PROJECT.md Key Decisions table)
+(Full decision log in PROJECT.md Key Decisions table)
+
+Cleared at milestone boundary. v1.2 decisions archived in milestones/v1.2-ROADMAP.md.
 
 ### Pending Todos
 
-- Replace planning category filter select with icon-aware dropdown (ui)
+None active.
 
 ### Blockers/Concerns
 
@@ -47,6 +47,6 @@ None active.
 
 ## Session Continuity
 
-Last session: 2026-03-15T17:15:00.000Z
-Stopped at: v1.1 milestone completed and archived
+Last session: 2026-03-16
+Stopped at: Milestone v1.2 archived
 Resume file: None

.planning/config.json

@@ -5,7 +5,7 @@
   "commit_docs": true,
   "model_profile": "quality",
   "workflow": {
-		"research": false,
+    "research": true,
     "plan_check": true,
     "verifier": true,
     "nyquist_validation": true,

.planning/milestones/v1.2-REQUIREMENTS.md

@@ -0,0 +1,128 @@
+# Requirements Archive: v1.2 Collection Power-Ups
+
+**Archived:** 2026-03-16
+**Status:** SHIPPED
+
+For current requirements, see `.planning/REQUIREMENTS.md`.
+
+---
+
+# Requirements: GearBox v1.2 Collection Power-Ups
+
+**Defined:** 2026-03-16
+**Core Value:** Make it effortless to manage gear and plan new purchases -- see how a potential buy affects your total setup weight and cost before committing.
+
+## v1.2 Requirements
+
+Requirements for this milestone. Each maps to roadmap phases.
+
+### Search & Filter
+
+- [x] **SRCH-01**: User can search items by name with instant filtering as they type
+- [x] **SRCH-02**: User can filter collection items by category via dropdown
+- [x] **SRCH-03**: User can combine text search with category filter simultaneously
+- [x] **SRCH-04**: User can see result count when filters are active (e.g., "showing 12 of 47 items")
+- [x] **SRCH-05**: User can clear all active filters with one action
+
+### Weight Units
+
+- [x] **UNIT-01**: User can select preferred weight unit (g, oz, lb, kg) from settings
+- [x] **UNIT-02**: All weight displays across the app reflect the selected unit
+- [x] **UNIT-03**: Weight unit preference persists across sessions
+
+### Weight Classification
+
+- [x] **CLAS-01**: User can classify each item within a setup as base weight, worn, or consumable
+- [x] **CLAS-02**: Setup totals display base weight, worn weight, consumable weight, and total separately
+- [x] **CLAS-03**: Items default to "base weight" classification when added to a setup
+- [x] **CLAS-04**: Same item can have different classifications in different setups
+
+### Weight Visualization
+
+- [x] **VIZZ-01**: User can view a donut chart showing weight distribution by category in a setup
+- [x] **VIZZ-02**: User can toggle chart between category view and classification view (base/worn/consumable)
+- [x] **VIZZ-03**: User can hover chart segments to see category name, weight, and percentage
+
+### Candidate Status
+
+- [x] **CAND-01**: Each candidate displays a status badge (researching, ordered, or arrived)
+- [x] **CAND-02**: User can change a candidate's status via click interaction
+- [x] **CAND-03**: New candidates default to "researching" status
+
+### Planning UI
+
+- [x] **PLAN-01**: Planning category filter dropdown shows Lucide icons alongside category names
+
+## Future Requirements
+
+Deferred to future milestones. Tracked but not in current roadmap.
+
+### Planning Enhancements
+
+- **COMP-01**: User can compare candidates side-by-side on weight and price
+- **RANK-01**: User can rank/prioritize candidates within a thread
+- **IMPC-01**: User can preview how a candidate affects setup weight/cost before resolving
+
+### Data Management
+
+- **DATA-01**: User can import gear collection from CSV
+- **DATA-02**: User can export gear collection to CSV
+
+### Social & Multi-User
+
+- **SOCL-01**: User can create an account with authentication
+- **SOCL-02**: User can share collections and setups publicly
+- **SOCL-03**: User can view other users' public profiles and setups
+
+### Automation
+
+- **AUTO-01**: System can auto-fill product information (price, weight, images) from external sources
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Per-item weight input in multiple units | Parsing complexity, ambiguous storage -- display-only conversion is sufficient |
+| Interactive chart drill-down (click to zoom) | Adds significant interaction complexity for minimal value |
+| Weight goals / targets | Opinionated norms conflict with hobby-agnostic design |
+| Custom classification labels | base/worn/consumable covers 95% of use cases |
+| Server-side full-text search | Premature for single-user app with <1000 items |
+| Classification at item level (not setup level) | Same item has different roles in different setups |
+| Status change timestamps | Useful but adds schema complexity -- defer |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| SRCH-01 | Phase 8 | Complete |
+| SRCH-02 | Phase 8 | Complete |
+| SRCH-03 | Phase 8 | Complete |
+| SRCH-04 | Phase 8 | Complete |
+| SRCH-05 | Phase 8 | Complete |
+| UNIT-01 | Phase 7 | Complete |
+| UNIT-02 | Phase 7 | Complete |
+| UNIT-03 | Phase 7 | Complete |
+| CLAS-01 | Phase 9 | Complete |
+| CLAS-02 | Phase 9 | Complete |
+| CLAS-03 | Phase 9 | Complete |
+| CLAS-04 | Phase 9 | Complete |
+| VIZZ-01 | Phase 9 | Complete |
+| VIZZ-02 | Phase 9 | Complete |
+| VIZZ-03 | Phase 9 | Complete |
+| CAND-01 | Phase 8 | Complete |
+| CAND-02 | Phase 8 | Complete |
+| CAND-03 | Phase 8 | Complete |
+| PLAN-01 | Phase 8 | Complete |
+
+**Coverage:**
+- v1.2 requirements: 19 total
+- Mapped to phases: 19
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-16*
+*Last updated: 2026-03-16 after roadmap creation*

.planning/milestones/v1.2-ROADMAP.md

@@ -0,0 +1,98 @@
+# Roadmap: GearBox
+
+## Milestones
+
+- v1.0 MVP -- Phases 1-3 (shipped 2026-03-15)
+- v1.1 Fixes & Polish -- Phases 4-6 (shipped 2026-03-15)
+- **v1.2 Collection Power-Ups** -- Phases 7-9 (in progress)
+
+## Phases
+
+<details>
+<summary>v1.0 MVP (Phases 1-3) -- SHIPPED 2026-03-15</summary>
+
+- [x] Phase 1: Foundation and Collection (4/4 plans) -- completed 2026-03-14
+- [x] Phase 2: Planning Threads (3/3 plans) -- completed 2026-03-15
+- [x] Phase 3: Setups and Dashboard (3/3 plans) -- completed 2026-03-15
+
+</details>
+
+<details>
+<summary>v1.1 Fixes & Polish (Phases 4-6) -- SHIPPED 2026-03-15</summary>
+
+- [x] Phase 4: Database & Planning Fixes (2/2 plans) -- completed 2026-03-15
+- [x] Phase 5: Image Handling (2/2 plans) -- completed 2026-03-15
+- [x] Phase 6: Category Icons (3/3 plans) -- completed 2026-03-15
+
+</details>
+
+### v1.2 Collection Power-Ups (In Progress)
+
+**Milestone Goal:** Make core gear management significantly more useful as collections grow -- better search, proper weight classification, richer planning threads.
+
+- [x] **Phase 7: Weight Unit Selection** - Users see all weights in their preferred unit across the entire app
+- [x] **Phase 8: Search, Filter, and Candidate Status** - Users can find items quickly and track candidate purchase progress
+- [x] **Phase 9: Weight Classification and Visualization** - Users can classify gear by role and visualize weight distribution in setups
+
+## Phase Details
+
+### Phase 7: Weight Unit Selection
+**Goal**: Users see all weights in their preferred unit across the entire app
+**Depends on**: Nothing (first phase of v1.2)
+**Requirements**: UNIT-01, UNIT-02, UNIT-03
+**Success Criteria** (what must be TRUE):
+  1. User can select a weight unit (g, oz, lb, kg) from a visible control and the selection persists after closing and reopening the app
+  2. Every weight value in the app (item cards, candidate cards, category headers, totals bar, setup details) displays in the selected unit with appropriate precision
+  3. Weight input fields accept values and store them correctly regardless of display unit (no rounding drift across edit cycles)
+**Plans:** 2 plans
+
+Plans:
+- [x] 07-01-PLAN.md -- TDD formatWeight unit conversion core + useWeightUnit hook
+- [ ] 07-02-PLAN.md -- Wire unit toggle into TotalsBar and update all 8 call sites
+
+### Phase 8: Search, Filter, and Candidate Status
+**Goal**: Users can find items quickly and track candidate purchase progress
+**Depends on**: Phase 7
+**Requirements**: SRCH-01, SRCH-02, SRCH-03, SRCH-04, SRCH-05, PLAN-01, CAND-01, CAND-02, CAND-03
+**Success Criteria** (what must be TRUE):
+  1. User can type in a search field on the collection page and see items filtered instantly by name as they type
+  2. User can select a category from a dropdown (showing Lucide icons alongside names) to filter items in both collection and planning views
+  3. User can see how many items match active filters (e.g., "showing 12 of 47 items") and clear all filters with one action
+  4. Each candidate in a planning thread displays a status badge (researching, ordered, or arrived) that the user can change by clicking
+  5. New candidates automatically start with "researching" status
+**Plans:** 2 plans
+
+Plans:
+- [ ] 08-01-PLAN.md -- Candidate status vertical slice (schema migration, service, tests, StatusBadge UI)
+- [ ] 08-02-PLAN.md -- Search/filter toolbar with CategoryFilterDropdown on gear and planning tabs
+
+### Phase 9: Weight Classification and Visualization
+**Goal**: Users can classify gear by role and visualize weight distribution in setups
+**Depends on**: Phase 7, Phase 8
+**Requirements**: CLAS-01, CLAS-02, CLAS-03, CLAS-04, VIZZ-01, VIZZ-02, VIZZ-03
+**Success Criteria** (what must be TRUE):
+  1. User can classify each item within a setup as base weight, worn, or consumable, and the same item can have different classifications in different setups
+  2. Setup detail view shows separate weight subtotals for base weight, worn weight, and consumable weight in addition to the overall total
+  3. User can view a donut chart in a setup showing weight distribution, and toggle between category breakdown and classification breakdown
+  4. User can hover chart segments to see the category/classification name, weight (in selected unit), and percentage
+**Plans:** 2 plans
+
+Plans:
+- [ ] 09-01-PLAN.md -- Classification vertical slice (schema, service, tests, API route, ClassificationBadge UI)
+- [ ] 09-02-PLAN.md -- WeightSummaryCard with subtotals, donut chart, pill toggle, and visual verification
+
+## Progress
+
+**Execution Order:** Phase 7 -> Phase 8 -> Phase 9
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation and Collection | v1.0 | 4/4 | Complete | 2026-03-14 |
+| 2. Planning Threads | v1.0 | 3/3 | Complete | 2026-03-15 |
+| 3. Setups and Dashboard | v1.0 | 3/3 | Complete | 2026-03-15 |
+| 4. Database & Planning Fixes | v1.1 | 2/2 | Complete | 2026-03-15 |
+| 5. Image Handling | v1.1 | 2/2 | Complete | 2026-03-15 |
+| 6. Category Icons | v1.1 | 3/3 | Complete | 2026-03-15 |
+| 7. Weight Unit Selection | v1.2 | 2/2 | Complete | 2026-03-16 |
+| 8. Search, Filter, and Candidate Status | v1.2 | 2/2 | Complete | 2026-03-16 |
+| 9. Weight Classification and Visualization | v1.2 | 2/2 | Complete | 2026-03-16 |

.planning/phases/07-weight-unit-selection/07-01-PLAN.md

@@ -0,0 +1,238 @@
+---
+phase: 07-weight-unit-selection
+plan: 01
+type: tdd
+wave: 1
+depends_on: []
+files_modified:
+  - src/client/lib/formatters.ts
+  - src/client/hooks/useWeightUnit.ts
+  - tests/lib/formatters.test.ts
+autonomous: true
+requirements:
+  - UNIT-02
+  - UNIT-03
+
+must_haves:
+  truths:
+    - "formatWeight converts grams to g, oz, lb, kg with correct precision"
+    - "formatWeight defaults to grams when no unit is specified (backward compatible)"
+    - "formatWeight handles null/undefined input for all units"
+    - "useWeightUnit hook returns a valid WeightUnit from settings, defaulting to 'g'"
+  artifacts:
+    - path: "src/client/lib/formatters.ts"
+      provides: "WeightUnit type export and parameterized formatWeight function"
+      exports: ["WeightUnit", "formatWeight", "formatPrice"]
+      contains: "WeightUnit"
+    - path: "src/client/hooks/useWeightUnit.ts"
+      provides: "Convenience hook wrapping useSetting for weight unit"
+      exports: ["useWeightUnit"]
+    - path: "tests/lib/formatters.test.ts"
+      provides: "Unit tests for formatWeight with all 4 units and edge cases"
+      min_lines: 30
+  key_links:
+    - from: "src/client/hooks/useWeightUnit.ts"
+      to: "src/client/hooks/useSettings.ts"
+      via: "useSetting('weightUnit')"
+      pattern: "useSetting.*weightUnit"
+    - from: "src/client/hooks/useWeightUnit.ts"
+      to: "src/client/lib/formatters.ts"
+      via: "imports WeightUnit type"
+      pattern: "import.*WeightUnit.*formatters"
+---
+
+<objective>
+Create the weight unit conversion core: a parameterized `formatWeight` function with a `WeightUnit` type and a `useWeightUnit` convenience hook, all backed by tests.
+
+Purpose: Establish the conversion contracts (type, function, hook) that Plan 02 will wire into every component. TDD approach ensures the conversion math is correct before any UI work.
+Output: Working `formatWeight(grams, unit)` with tests green, `useWeightUnit()` hook ready for consumption.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-weight-unit-selection/07-RESEARCH.md
+
+@src/client/lib/formatters.ts
+@src/client/hooks/useSettings.ts
+</context>
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/client/lib/formatters.ts (current):
+```typescript
+export function formatWeight(grams: number | null | undefined): string {
+  if (grams == null) return "--";
+  return `${Math.round(grams)}g`;
+}
+
+export function formatPrice(cents: number | null | undefined): string {
+  if (cents == null) return "--";
+  return `$${(cents / 100).toFixed(2)}`;
+}
+```
+
+From src/client/hooks/useSettings.ts:
+```typescript
+export function useSetting(key: string) {
+  return useQuery({
+    queryKey: ["settings", key],
+    queryFn: async () => {
+      try {
+        const result = await apiGet<Setting>(`/api/settings/${key}`);
+        return result.value;
+      } catch (err: any) {
+        if (err?.status === 404) return null;
+        throw err;
+      }
+    },
+  });
+}
+
+export function useUpdateSetting() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ key, value }: { key: string; value: string }) =>
+      apiPut<Setting>(`/api/settings/${key}`, { value }),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({ queryKey: ["settings", variables.key] });
+    },
+  });
+}
+```
+</interfaces>
+
+<feature>
+  <name>formatWeight unit conversion</name>
+  <files>src/client/lib/formatters.ts, tests/lib/formatters.test.ts</files>
+  <behavior>
+    Conversion constants: 1 oz = 28.3495g, 1 lb = 453.592g, 1 kg = 1000g
+
+    - formatWeight(100, "g") -> "100g"
+    - formatWeight(100, "oz") -> "3.5 oz"
+    - formatWeight(1000, "lb") -> "2.20 lb"
+    - formatWeight(1500, "kg") -> "1.50 kg"
+    - formatWeight(null, "oz") -> "--"
+    - formatWeight(undefined, "kg") -> "--"
+    - formatWeight(100) -> "100g" (default unit, backward compatible)
+    - formatWeight(0, "oz") -> "0.0 oz"
+    - formatWeight(5, "lb") -> "0.01 lb" (small weight precision)
+    - formatWeight(50000, "kg") -> "50.00 kg" (large weight)
+  </behavior>
+  <implementation>
+    1. Add `WeightUnit` type export: `"g" | "oz" | "lb" | "kg"`
+    2. Add conversion constants as module-level consts (not exported)
+    3. Modify `formatWeight` signature to `(grams: number | null | undefined, unit: WeightUnit = "g"): string`
+    4. Keep the null guard as-is at the top
+    5. Add switch statement for unit-specific formatting:
+       - g: `Math.round(grams)` + "g" (0 decimals, current behavior)
+       - oz: `.toFixed(1)` + " oz" (1 decimal)
+       - lb: `.toFixed(2)` + " lb" (2 decimals)
+       - kg: `.toFixed(2)` + " kg" (2 decimals)
+    6. Do NOT modify `formatPrice` — leave it untouched
+  </implementation>
+</feature>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: TDD formatWeight with unit parameter</name>
+  <files>src/client/lib/formatters.ts, tests/lib/formatters.test.ts</files>
+  <behavior>
+    - formatWeight(100, "g") returns "100g"
+    - formatWeight(100, "oz") returns "3.5 oz"
+    - formatWeight(1000, "lb") returns "2.20 lb"
+    - formatWeight(1500, "kg") returns "1.50 kg"
+    - formatWeight(null) returns "--" for all units
+    - formatWeight(undefined, "kg") returns "--"
+    - formatWeight(100) returns "100g" (backward compatible, no second arg)
+    - formatWeight(0, "oz") returns "0.0 oz"
+  </behavior>
+  <action>
+    RED: Create `tests/lib/formatters.test.ts`. Import `formatWeight` from `@/client/lib/formatters`. Write tests for:
+    - All 4 units with a known gram value (e.g., 1000g = "1000g", "35.3 oz", "2.20 lb", "1.00 kg")
+    - Null and undefined input returning "--" for each unit
+    - Default parameter (no second arg) producing current "g" behavior
+    - Zero grams producing "0g", "0.0 oz", "0.00 lb", "0.00 kg"
+    - Precision edge cases (small values like 5g in lb = "0.01 lb")
+
+    Run tests — they should fail because formatWeight does not accept a unit parameter yet.
+
+    GREEN: Modify `src/client/lib/formatters.ts`:
+    - Export `type WeightUnit = "g" | "oz" | "lb" | "kg"`
+    - Add constants: `GRAMS_PER_OZ = 28.3495`, `GRAMS_PER_LB = 453.592`, `GRAMS_PER_KG = 1000`
+    - Change signature to `formatWeight(grams: number | null | undefined, unit: WeightUnit = "g")`
+    - Add switch statement after the null guard for unit-specific conversion and formatting
+    - Leave `formatPrice` completely untouched
+
+    Run tests — all should pass.
+
+    REFACTOR: None expected — the code is already minimal.
+  </action>
+  <verify>
+    <automated>bun test tests/lib/formatters.test.ts</automated>
+  </verify>
+  <done>formatWeight handles all 4 units with correct precision, null handling, and backward-compatible default. WeightUnit type is exported. All tests pass.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create useWeightUnit convenience hook</name>
+  <files>src/client/hooks/useWeightUnit.ts</files>
+  <action>
+    Create `src/client/hooks/useWeightUnit.ts`:
+
+    ```typescript
+    import { useSetting } from "./useSettings";
+    import type { WeightUnit } from "../lib/formatters";
+
+    const VALID_UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
+
+    export function useWeightUnit(): WeightUnit {
+      const { data } = useSetting("weightUnit");
+      if (data && VALID_UNITS.includes(data as WeightUnit)) {
+        return data as WeightUnit;
+      }
+      return "g";
+    }
+    ```
+
+    This hook:
+    - Wraps `useSetting("weightUnit")` for a typed return value
+    - Validates the stored value is a known unit (protects against bad data)
+    - Defaults to "g" when no setting exists (backward compatible — UNIT-03 persistence works via existing settings API)
+    - Returns `WeightUnit` type so components can pass directly to `formatWeight`
+  </action>
+  <verify>
+    <automated>bun run lint</automated>
+  </verify>
+  <done>useWeightUnit hook exists, imports from useSettings and formatters, returns typed WeightUnit with "g" default. Lint passes.</done>
+</task>
+
+</tasks>
+
+<verification>
+- `bun test tests/lib/formatters.test.ts` passes with all unit conversion tests green
+- `bun run lint` passes with no errors
+- `src/client/lib/formatters.ts` exports `WeightUnit` type and updated `formatWeight` function
+- `src/client/hooks/useWeightUnit.ts` exists and exports `useWeightUnit`
+- Existing tests still pass: `bun test` (full suite)
+</verification>
+
+<success_criteria>
+- formatWeight("g") produces identical output to the old function (backward compatible)
+- formatWeight with oz/lb/kg produces correct conversions with appropriate decimal precision
+- WeightUnit type is exported for use by Plan 02 components
+- useWeightUnit hook is ready for components to consume
+- All existing tests remain green (no regressions)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-weight-unit-selection/07-01-SUMMARY.md`
+</output>

.planning/phases/07-weight-unit-selection/07-01-SUMMARY.md

@@ -0,0 +1,114 @@
+---
+phase: 07-weight-unit-selection
+plan: 01
+subsystem: ui
+tags: [weight-conversion, formatters, react-hooks, tdd]
+
+# Dependency graph
+requires: []
+provides:
+  - "WeightUnit type export for all weight display components"
+  - "Parameterized formatWeight(grams, unit) with g/oz/lb/kg support"
+  - "useWeightUnit() hook wrapping settings API for typed unit access"
+affects: [07-02-PLAN]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [unit-conversion-via-formatters, settings-backed-hooks]
+
+key-files:
+  created:
+    - src/client/hooks/useWeightUnit.ts
+    - tests/lib/formatters.test.ts
+  modified:
+    - src/client/lib/formatters.ts
+
+key-decisions:
+  - "Conversion precision: g=0dp, oz=1dp, lb=2dp, kg=2dp matching common usage"
+  - "useWeightUnit validates stored value against known units to protect against corrupt data"
+
+patterns-established:
+  - "Weight formatting: always call formatWeight(grams, unit) with WeightUnit parameter"
+  - "Settings-backed hooks: wrap useSetting with typed validation for domain-specific config"
+
+requirements-completed: [UNIT-02, UNIT-03]
+
+# Metrics
+duration: 2min
+completed: 2026-03-16
+---
+
+# Phase 7 Plan 01: Weight Unit Core Summary
+
+**Parameterized formatWeight with g/oz/lb/kg conversion and useWeightUnit settings hook, backed by 21 TDD tests**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-16T11:14:19Z
+- **Completed:** 2026-03-16T11:16:30Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- TDD-developed formatWeight function supporting 4 weight units (g, oz, lb, kg) with appropriate precision
+- WeightUnit type exported for consumption by all display components in Plan 02
+- useWeightUnit convenience hook with validation and "g" default, ready for component integration
+- Full backward compatibility preserved -- formatWeight(grams) still returns "Xg" as before
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1 (RED): TDD formatWeight tests** - `431c179` (test)
+2. **Task 1 (GREEN): Implement formatWeight with unit parameter** - `6cac0a3` (feat)
+3. **Task 2: Create useWeightUnit convenience hook** - `ada3791` (feat)
+
+_TDD task had 2 commits (test -> feat). No refactor needed -- code was already minimal._
+
+## Files Created/Modified
+- `src/client/lib/formatters.ts` - Added WeightUnit type, conversion constants, switch-based unit formatting
+- `src/client/hooks/useWeightUnit.ts` - Convenience hook wrapping useSetting("weightUnit") with typed validation
+- `tests/lib/formatters.test.ts` - 21 tests covering all units, null/undefined, backward compat, edge cases
+
+## Decisions Made
+- Conversion precision follows common usage: grams rounded (0dp), ounces 1dp, pounds 2dp, kilograms 2dp
+- useWeightUnit validates stored value against a whitelist of known units, protecting against corrupt settings data
+- Conversion constants (GRAMS_PER_OZ=28.3495, GRAMS_PER_LB=453.592, GRAMS_PER_KG=1000) kept as module-level consts, not exported
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed import order in useWeightUnit.ts**
+- **Found during:** Task 2 (useWeightUnit hook creation)
+- **Issue:** Biome lint required imports sorted alphabetically (type imports before value imports)
+- **Fix:** Reordered imports to put `import type { WeightUnit }` before `import { useSetting }`
+- **Files modified:** src/client/hooks/useWeightUnit.ts
+- **Verification:** `bun run lint` passes clean
+- **Committed in:** ada3791 (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug - lint order)
+**Impact on plan:** Trivial formatting fix. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- WeightUnit type and formatWeight function ready for Plan 02 to wire into all weight-displaying components
+- useWeightUnit hook ready for components to consume the user's preferred unit from settings
+- All 108 existing tests pass (full suite regression check confirmed)
+
+## Self-Check: PASSED
+
+All files exist, all commits found, all exports verified.
+
+---
+*Phase: 07-weight-unit-selection*
+*Completed: 2026-03-16*

.planning/phases/07-weight-unit-selection/07-02-PLAN.md

@@ -0,0 +1,247 @@
+---
+phase: 07-weight-unit-selection
+plan: 02
+type: execute
+wave: 2
+depends_on:
+  - "07-01"
+files_modified:
+  - src/client/components/TotalsBar.tsx
+  - src/client/components/ItemCard.tsx
+  - src/client/components/CandidateCard.tsx
+  - src/client/components/CategoryHeader.tsx
+  - src/client/components/SetupCard.tsx
+  - src/client/components/ItemPicker.tsx
+  - src/client/routes/index.tsx
+  - src/client/routes/setups/$setupId.tsx
+autonomous: false
+requirements:
+  - UNIT-01
+  - UNIT-02
+  - UNIT-03
+
+must_haves:
+  truths:
+    - "User can see a unit toggle (g/oz/lb/kg) in the TotalsBar"
+    - "Clicking a unit in the toggle changes all weight displays across the app"
+    - "Weight unit selection persists after page refresh"
+    - "Every weight display in the app uses the selected unit"
+  artifacts:
+    - path: "src/client/components/TotalsBar.tsx"
+      provides: "Unit toggle UI and unit-aware weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/components/ItemCard.tsx"
+      provides: "Unit-aware item weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/components/CandidateCard.tsx"
+      provides: "Unit-aware candidate weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/components/CategoryHeader.tsx"
+      provides: "Unit-aware category total weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/components/SetupCard.tsx"
+      provides: "Unit-aware setup weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/components/ItemPicker.tsx"
+      provides: "Unit-aware item picker weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/routes/index.tsx"
+      provides: "Unit-aware dashboard weight display"
+      contains: "useWeightUnit"
+    - path: "src/client/routes/setups/$setupId.tsx"
+      provides: "Unit-aware setup detail weight display"
+      contains: "useWeightUnit"
+  key_links:
+    - from: "src/client/components/TotalsBar.tsx"
+      to: "/api/settings/weightUnit"
+      via: "useUpdateSetting mutation"
+      pattern: "useUpdateSetting.*weightUnit"
+    - from: "src/client/components/ItemCard.tsx"
+      to: "src/client/hooks/useWeightUnit.ts"
+      via: "useWeightUnit hook import"
+      pattern: "useWeightUnit"
+    - from: "src/client/components/TotalsBar.tsx"
+      to: "src/client/lib/formatters.ts"
+      via: "formatWeight(grams, unit)"
+      pattern: "formatWeight\\(.*,\\s*unit"
+---
+
+<objective>
+Wire weight unit selection through the entire app: add a segmented unit toggle to TotalsBar and update all 8 formatWeight call sites to use the selected unit.
+
+Purpose: Deliver the complete user-facing feature. After this plan, users can select g/oz/lb/kg and see all weights update instantly across collection, planning, setups, and dashboard.
+Output: Fully functional weight unit selection with persistent preference.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-weight-unit-selection/07-RESEARCH.md
+@.planning/phases/07-weight-unit-selection/07-01-SUMMARY.md
+</context>
+
+<interfaces>
+<!-- Contracts created by Plan 01 that this plan consumes -->
+
+From src/client/lib/formatters.ts (after Plan 01):
+```typescript
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+export function formatWeight(grams: number | null | undefined, unit?: WeightUnit): string;
+export function formatPrice(cents: number | null | undefined): string;
+```
+
+From src/client/hooks/useWeightUnit.ts (after Plan 01):
+```typescript
+export function useWeightUnit(): WeightUnit;
+```
+
+From src/client/hooks/useSettings.ts (existing):
+```typescript
+export function useUpdateSetting(): UseMutationResult<Setting, Error, { key: string; value: string }>;
+```
+
+Usage pattern for every component:
+```typescript
+import { useWeightUnit } from "../hooks/useWeightUnit";
+// ...
+const unit = useWeightUnit();
+// ...
+{formatWeight(weightGrams, unit)}
+```
+</interfaces>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add unit toggle to TotalsBar and update all call sites</name>
+  <files>
+    src/client/components/TotalsBar.tsx,
+    src/client/components/ItemCard.tsx,
+    src/client/components/CandidateCard.tsx,
+    src/client/components/CategoryHeader.tsx,
+    src/client/components/SetupCard.tsx,
+    src/client/components/ItemPicker.tsx,
+    src/client/routes/index.tsx,
+    src/client/routes/setups/$setupId.tsx
+  </files>
+  <action>
+    **TotalsBar.tsx** -- Add unit toggle and wire formatWeight:
+
+    1. Import `useWeightUnit` from `../hooks/useWeightUnit`, `useUpdateSetting` from `../hooks/useSettings`, and `WeightUnit` type from `../lib/formatters`
+    2. Inside the component function, call `const unit = useWeightUnit()` and `const updateSetting = useUpdateSetting()`
+    3. Define `const UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"]`
+    4. Add a segmented pill toggle to the right side of the TotalsBar, between the title and the stats. The toggle should be a `div` with `flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5` containing a button per unit:
+       ```
+       <button
+         key={u}
+         onClick={() => updateSetting.mutate({ key: "weightUnit", value: u })}
+         className={`px-2 py-0.5 text-xs rounded-full transition-colors ${
+           unit === u
+             ? "bg-white text-gray-700 shadow-sm font-medium"
+             : "text-gray-400 hover:text-gray-600"
+         }`}
+       >
+         {u}
+       </button>
+       ```
+    5. Update the default stats construction (the `data?.global` branch) to pass `unit` to both `formatWeight` calls:
+       - `formatWeight(data.global.totalWeight, unit)` and `formatWeight(null, unit)`
+    6. Position the toggle: place it in the flex container between the title and stats, using a wrapper div that pushes stats to the right. The toggle should be visible but not dominant -- it's a small utility control.
+
+    **ItemCard.tsx** -- 3-line change:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside component: `const unit = useWeightUnit();`
+    3. Change `{formatWeight(weightGrams)}` to `{formatWeight(weightGrams, unit)}`
+
+    **CandidateCard.tsx** -- Same 3-line pattern as ItemCard:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside component: `const unit = useWeightUnit();`
+    3. Change `{formatWeight(weightGrams)}` to `{formatWeight(weightGrams, unit)}`
+
+    **CategoryHeader.tsx** -- Same 3-line pattern:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside component: `const unit = useWeightUnit();`
+    3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
+
+    **SetupCard.tsx** -- Same 3-line pattern:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside component: `const unit = useWeightUnit();`
+    3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
+
+    **ItemPicker.tsx** -- Same 3-line pattern:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside component: `const unit = useWeightUnit();`
+    3. Change `formatWeight(item.weightGrams)` to `formatWeight(item.weightGrams, unit)`
+
+    **routes/index.tsx** (Dashboard) -- Same 3-line pattern:
+    1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
+    2. Inside `DashboardPage`: `const unit = useWeightUnit();`
+    3. Change `formatWeight(global?.totalWeight ?? null)` to `formatWeight(global?.totalWeight ?? null, unit)`
+
+    **routes/setups/$setupId.tsx** (Setup Detail) -- Same 3-line pattern:
+    1. Add import: `import { useWeightUnit } from "../../hooks/useWeightUnit";`
+    2. Inside `SetupDetailPage`: `const unit = useWeightUnit();`
+    3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
+
+    **Completeness check:** After all changes, grep for `formatWeight(` across `src/client/` -- every call must have a second `unit` argument EXCEPT the function definition itself in `formatters.ts`.
+  </action>
+  <verify>
+    <automated>bun test && bun run lint</automated>
+  </verify>
+  <done>
+    - All 8 components pass `unit` to `formatWeight`
+    - TotalsBar renders a g/oz/lb/kg toggle
+    - Clicking a toggle button calls `useUpdateSetting` with key "weightUnit"
+    - No `formatWeight` call site in src/client/ is missing the unit argument (except the definition)
+    - All tests and lint pass
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Verify weight unit selection end-to-end</name>
+  <action>
+    Human verifies the complete weight unit selection feature works correctly across all pages.
+
+    Start the dev servers: `bun run dev:client` and `bun run dev:server`
+    Open http://localhost:5173 in a browser and walk through the verification steps below.
+  </action>
+  <verify>
+    1. Navigate to the Collection page -- verify the TotalsBar shows a g/oz/lb/kg toggle
+    2. The default should be "g" -- weights display as before (e.g., "450g")
+    3. Click "oz" -- all weight badges on ItemCards, CategoryHeaders, and the TotalsBar total should update to ounces (e.g., "15.9 oz")
+    4. Click "kg" -- weights should update to kilograms (e.g., "0.45 kg")
+    5. Click "lb" -- weights should update to pounds (e.g., "0.99 lb")
+    6. Navigate to the Dashboard (/) -- the Collection card weight should show in the selected unit
+    7. Navigate to a Setup detail page -- the sticky sub-bar weight total and all ItemCards should show the selected unit
+    8. Refresh the page -- the selected unit should persist (still showing the last chosen unit)
+    9. Switch back to "g" -- all weights should return to the original gram display
+  </verify>
+  <done>User confirms all weight displays update correctly across all pages, unit toggle is visible and functional, and selection persists across refresh. Type "approved" or describe issues.</done>
+</task>
+
+</tasks>
+
+<verification>
+- `bun test` passes (full suite, no regressions)
+- `bun run lint` passes
+- grep `formatWeight(` across `src/client/` shows all call sites have unit parameter
+- Unit toggle is visible in TotalsBar on all pages that show it
+- Selecting a unit updates all weight displays instantly
+- Selected unit persists across page refresh
+</verification>
+
+<success_criteria>
+- UNIT-01: User can select g/oz/lb/kg from the TotalsBar toggle -- visible and functional
+- UNIT-02: Every weight display (ItemCard, CandidateCard, CategoryHeader, SetupCard, ItemPicker, Dashboard, Setup Detail, TotalsBar) reflects the selected unit
+- UNIT-03: Weight unit persists across sessions via the existing settings API (PUT/GET /api/settings/weightUnit)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-weight-unit-selection/07-02-SUMMARY.md`
+</output>

.planning/phases/07-weight-unit-selection/07-02-SUMMARY.md

@@ -0,0 +1,116 @@
+---
+phase: 07-weight-unit-selection
+plan: 02
+subsystem: ui
+tags: [weight-unit-toggle, react-hooks, settings-mutation, formatWeight]
+
+# Dependency graph
+requires:
+  - phase: 07-01
+    provides: "WeightUnit type, formatWeight(grams, unit), useWeightUnit() hook"
+provides:
+  - "Segmented g/oz/lb/kg toggle in TotalsBar with settings persistence"
+  - "All weight displays across the app respect selected unit"
+affects: []
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [segmented-pill-toggle, settings-mutation-via-useUpdateSetting]
+
+key-files:
+  created: []
+  modified:
+    - src/client/components/TotalsBar.tsx
+    - src/client/components/ItemCard.tsx
+    - src/client/components/CandidateCard.tsx
+    - src/client/components/CategoryHeader.tsx
+    - src/client/components/SetupCard.tsx
+    - src/client/components/ItemPicker.tsx
+    - src/client/routes/index.tsx
+    - src/client/routes/setups/$setupId.tsx
+
+key-decisions:
+  - "Unit toggle placed between title and stats in TotalsBar flex container for subtle utility control placement"
+  - "Biome requires type imports after value imports in destructured import statements"
+
+patterns-established:
+  - "All formatWeight calls pass unit from useWeightUnit -- no bare formatWeight(grams) in components"
+  - "Settings mutation for UI preferences: useUpdateSetting().mutate({ key, value })"
+
+requirements-completed: [UNIT-01, UNIT-02, UNIT-03]
+
+# Metrics
+duration: 3min
+completed: 2026-03-16
+---
+
+# Phase 7 Plan 02: Weight Unit UI Wiring Summary
+
+**Segmented g/oz/lb/kg toggle in TotalsBar with all 8 weight display call sites wired to user-selected unit**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-16T11:20:20Z
+- **Completed:** 2026-03-16T11:23:32Z
+- **Tasks:** 2 (1 auto + 1 checkpoint auto-approved)
+- **Files modified:** 8
+
+## Accomplishments
+- Added segmented pill toggle (g/oz/lb/kg) to TotalsBar with persistent settings via useUpdateSetting
+- Wired all 8 formatWeight call sites to pass the selected unit from useWeightUnit hook
+- All 108 existing tests pass with no regressions, lint clean
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add unit toggle to TotalsBar and update all call sites** - `faa4378` (feat)
+2. **Task 2: Verify weight unit selection end-to-end** - auto-approved (checkpoint)
+
+## Files Created/Modified
+- `src/client/components/TotalsBar.tsx` - Added unit toggle UI, useUpdateSetting mutation, and unit-aware formatWeight calls
+- `src/client/components/ItemCard.tsx` - Added useWeightUnit import and unit parameter to formatWeight
+- `src/client/components/CandidateCard.tsx` - Added useWeightUnit import and unit parameter to formatWeight
+- `src/client/components/CategoryHeader.tsx` - Added useWeightUnit import and unit parameter to formatWeight
+- `src/client/components/SetupCard.tsx` - Added useWeightUnit import and unit parameter to formatWeight
+- `src/client/components/ItemPicker.tsx` - Added useWeightUnit import and unit parameter to formatWeight
+- `src/client/routes/index.tsx` - Added useWeightUnit import and unit parameter to Dashboard formatWeight
+- `src/client/routes/setups/$setupId.tsx` - Added useWeightUnit import and unit parameter to Setup Detail formatWeight
+
+## Decisions Made
+- Unit toggle placed between title and stats in TotalsBar's flex container, keeping it visible but non-dominant as a small utility control
+- Biome requires `type` imports after value imports in destructured statements (e.g., `{ formatWeight, type WeightUnit }`)
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed import order for WeightUnit type in TotalsBar.tsx**
+- **Found during:** Task 1 (TotalsBar modification)
+- **Issue:** Biome lint required `type WeightUnit` to come after value imports in destructured import
+- **Fix:** Changed `{ type WeightUnit, formatPrice, formatWeight }` to `{ formatPrice, formatWeight, type WeightUnit }`
+- **Files modified:** src/client/components/TotalsBar.tsx
+- **Verification:** `bun run lint` passes clean
+- **Committed in:** faa4378 (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug - lint import ordering)
+**Impact on plan:** Trivial import ordering fix. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 7 (Weight Unit Selection) is fully complete
+- All 3 requirements (UNIT-01, UNIT-02, UNIT-03) satisfied
+- Ready to proceed to Phase 8 (Candidate Status & Category Icons)
+
+---
+*Phase: 07-weight-unit-selection*
+*Completed: 2026-03-16*

.planning/phases/07-weight-unit-selection/07-CONTEXT.md

@@ -0,0 +1,63 @@
+# Phase 7: Weight Unit Selection - Context
+
+**Gathered:** 2026-03-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can select a preferred weight unit (g, oz, lb, kg) and all weight displays across the app reflect that choice. Weight input stays in grams. The setting persists across sessions.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Claude's Discretion
+- Unit selector placement (TotalsBar, settings page, or elsewhere)
+- Pounds display format (traditional "2 lb 3 oz" vs decimal "2.19 lb")
+- Precision per unit (decimal places for oz, kg)
+- Default unit (grams, matching current behavior)
+- How formatWeight gets access to the setting (hook, context, parameter)
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `formatWeight()` in `src/client/lib/formatters.ts`: Currently `Math.round(grams) + "g"` — single conversion point for all weight display
+- `useSetting(key)` hook in `src/client/hooks/useSettings.ts`: Fetches from `/api/settings/:key`, caches with React Query
+- `useUpdateSetting()` mutation: PUT to `/api/settings/:key`, invalidates query cache
+- Settings API already exists with get/put endpoints
+
+### Established Patterns
+- Settings stored as key/value strings in SQLite `settings` table
+- React Query for server state, Zustand for UI-only state
+- Pill badges for weight/price display on ItemCard and CandidateCard (blue-50/blue-400 for weight)
+
+### Integration Points
+- `formatWeight()` call sites (~8 components): TotalsBar, ItemCard, CandidateCard, CategoryHeader, SetupCard, ItemPicker, collection route, setup detail route
+- `formatPrice()` is in the same file — similar pattern, not affected by this phase
+- TotalsBar already imports `useTotals()` and `formatWeight` — natural place for a unit toggle
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — user gave full discretion. Standard gear app patterns apply (LighterPack-style toggle).
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 07-weight-unit-selection*
+*Context gathered: 2026-03-16*

.planning/phases/07-weight-unit-selection/07-RESEARCH.md

@@ -0,0 +1,387 @@
+# Phase 7: Weight Unit Selection - Research
+
+**Researched:** 2026-03-16
+**Domain:** Weight unit conversion, display formatting, settings persistence
+**Confidence:** HIGH
+
+## Summary
+
+This phase is a display-only concern with a clean architecture. All weight data is already stored in grams (`weight_grams REAL` in SQLite). The task is to: (1) let the user pick a display unit, (2) persist that choice via the existing settings system, and (3) modify `formatWeight()` to convert grams to the selected unit before rendering. The existing `useSetting`/`useUpdateSetting` hooks and `/api/settings/:key` API handle persistence out of the box -- no schema changes or migrations needed.
+
+The codebase has a single `formatWeight(grams)` function in `src/client/lib/formatters.ts` called from exactly 8 components. Every weight display flows through this function, so the conversion is a single-point change. The challenge is threading the unit preference to `formatWeight` -- currently a pure function with no access to React state. The cleanest approach is to add a `unit` parameter and create a `useWeightUnit()` hook that components use to get the current unit, then pass it to `formatWeight`.
+
+**Primary recommendation:** Add a `unit` parameter to `formatWeight(grams, unit)`, create a `useWeightUnit()` convenience hook wrapping `useSetting("weightUnit")`, and place a small unit toggle in the TotalsBar. Keep weight input always in grams -- this is a display-only feature per the requirements and out-of-scope list.
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+(No locked decisions -- all implementation details are at Claude's discretion)
+
+### Claude's Discretion
+- Unit selector placement (TotalsBar, settings page, or elsewhere)
+- Pounds display format (traditional "2 lb 3 oz" vs decimal "2.19 lb")
+- Precision per unit (decimal places for oz, kg)
+- Default unit (grams, matching current behavior)
+- How formatWeight gets access to the setting (hook, context, parameter)
+
+### Deferred Ideas (OUT OF SCOPE)
+None -- discussion stayed within phase scope
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| UNIT-01 | User can select preferred weight unit (g, oz, lb, kg) from settings | Settings API already exists; `useSetting`/`useUpdateSetting` hooks ready; unit selector component needed in TotalsBar |
+| UNIT-02 | All weight displays across the app reflect the selected unit | Single `formatWeight()` function is the sole conversion point; 8 call sites across TotalsBar, ItemCard, CandidateCard, CategoryHeader, SetupCard, ItemPicker, collection route, setup detail route |
+| UNIT-03 | Weight unit preference persists across sessions | `settings` table + `/api/settings/:key` upsert endpoint already handle this -- just use key `"weightUnit"` |
+</phase_requirements>
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| React 19 | 19.x | UI framework | Already in project |
+| TanStack React Query | 5.x | Server state / caching | Already used for all data fetching; `useSetting` hook wraps it |
+| Hono | 4.x | API server | Settings routes already exist |
+| Drizzle ORM | latest | Database access | Settings table already defined |
+
+### Supporting
+No additional libraries needed. This phase requires zero new dependencies.
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| Parameter-based `formatWeight(g, unit)` | React Context provider | Context adds unnecessary complexity for a single value; parameter is explicit, testable, and avoids re-render cascades |
+| Zustand store for unit | `useSetting` hook (React Query) | Unit is server-persisted state, not ephemeral UI state; React Query is the correct layer per project conventions |
+
+## Architecture Patterns
+
+### Recommended Approach
+
+No new files except a small `useWeightUnit` convenience hook. The changes are surgical:
+
+```
+src/client/
+  lib/
+    formatters.ts         # MODIFY: add unit parameter to formatWeight
+  hooks/
+    useWeightUnit.ts      # NEW: convenience hook wrapping useSetting("weightUnit")
+  components/
+    TotalsBar.tsx          # MODIFY: add unit toggle control
+    ItemCard.tsx           # MODIFY: pass unit to formatWeight
+    CandidateCard.tsx      # MODIFY: pass unit to formatWeight
+    CategoryHeader.tsx     # MODIFY: pass unit to formatWeight
+    SetupCard.tsx          # MODIFY: pass unit to formatWeight
+    ItemPicker.tsx         # MODIFY: pass unit to formatWeight
+  routes/
+    index.tsx              # MODIFY: pass unit to formatWeight
+    setups/$setupId.tsx    # MODIFY: pass unit to formatWeight
+```
+
+### Pattern 1: Weight Unit Type and Conversion Constants
+
+**What:** Define a `WeightUnit` type and conversion map as a simple module constant.
+**When to use:** Everywhere unit-related logic is needed.
+**Example:**
+
+```typescript
+// In src/client/lib/formatters.ts
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+
+const GRAMS_PER_OZ = 28.3495;
+const GRAMS_PER_LB = 453.592;
+const GRAMS_PER_KG = 1000;
+
+export function formatWeight(
+  grams: number | null | undefined,
+  unit: WeightUnit = "g",
+): string {
+  if (grams == null) return "--";
+
+  switch (unit) {
+    case "g":
+      return `${Math.round(grams)}g`;
+    case "oz":
+      return `${(grams / GRAMS_PER_OZ).toFixed(1)} oz`;
+    case "lb":
+      return `${(grams / GRAMS_PER_LB).toFixed(2)} lb`;
+    case "kg":
+      return `${(grams / GRAMS_PER_KG).toFixed(2)} kg`;
+  }
+}
+```
+
+### Pattern 2: Convenience Hook
+
+**What:** A thin hook that reads the weight unit setting and returns a typed value with a sensible default.
+**When to use:** Any component that calls `formatWeight`.
+**Example:**
+
+```typescript
+// In src/client/hooks/useWeightUnit.ts
+import { useSetting } from "./useSettings";
+import type { WeightUnit } from "../lib/formatters";
+
+const VALID_UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
+
+export function useWeightUnit(): WeightUnit {
+  const { data } = useSetting("weightUnit");
+  if (data && VALID_UNITS.includes(data as WeightUnit)) {
+    return data as WeightUnit;
+  }
+  return "g"; // default matches current behavior
+}
+```
+
+### Pattern 3: Unit Selector in TotalsBar
+
+**What:** A small segmented control or dropdown in the TotalsBar for switching units.
+**When to use:** Global weight unit selection, always visible.
+**Example concept:**
+
+```typescript
+// Segmented pill buttons in TotalsBar
+const UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
+
+// Small inline toggle alongside stats
+<div className="flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5">
+  {UNITS.map((u) => (
+    <button
+      key={u}
+      onClick={() => updateSetting.mutate({ key: "weightUnit", value: u })}
+      className={`px-2 py-0.5 text-xs rounded-full transition-colors ${
+        unit === u
+          ? "bg-white text-gray-700 shadow-sm font-medium"
+          : "text-gray-400 hover:text-gray-600"
+      }`}
+    >
+      {u}
+    </button>
+  ))}
+</div>
+```
+
+### Anti-Patterns to Avoid
+- **Converting on the server side:** Database stores grams, API returns grams. Conversion is purely a display concern -- never modify the API layer.
+- **Using React Context for a single value:** The project uses React Query for server state. Adding a Context provider for one setting breaks convention and introduces unnecessary complexity.
+- **Storing converted values:** Always store grams in the database. The `weightUnit` setting is a display preference, not a data transformation.
+- **Changing weight input fields:** The requirements explicitly keep input in grams (see Out of Scope in REQUIREMENTS.md: "Per-item weight input in multiple units" is excluded). Input labels stay as "Weight (g)".
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Setting persistence | Custom localStorage + API sync | Existing `useSetting`/`useUpdateSetting` hooks + settings API | Already handles cache invalidation and server persistence |
+| Unit conversion | Complex conversion library | Simple division constants (28.3495, 453.592, 1000) | Only 4 units, all linear conversions from grams -- a library is overkill |
+
+**Key insight:** The entire feature is a ~30-line formatter change + a small UI toggle + updating 8 call sites. No external library is needed.
+
+## Common Pitfalls
+
+### Pitfall 1: Floating-Point Display Precision
+**What goes wrong:** Showing too many decimal places (e.g., "42.328947 oz") or too few (e.g., "0 kg" for a 450g item).
+**Why it happens:** Different units have different natural precision ranges.
+**How to avoid:** Use unit-specific precision: `g` = 0 decimals (round), `oz` = 1 decimal, `lb` = 2 decimals, `kg` = 2 decimals. These match gear community conventions (LighterPack and similar apps use comparable precision).
+**Warning signs:** Items showing "0 lb" or "0.0 oz" when they have measurable weight.
+
+### Pitfall 2: Null/Undefined Weight Handling
+**What goes wrong:** Conversion math on null values produces NaN or "NaN oz".
+**Why it happens:** Many items have `weightGrams: null` (optional field).
+**How to avoid:** The existing `if (grams == null) return "--"` guard at the top of `formatWeight` handles this. Keep it as the first check before any unit logic.
+**Warning signs:** "NaN" or "undefined oz" appearing in the UI.
+
+### Pitfall 3: Forgetting a Call Site
+**What goes wrong:** One component still shows grams while everything else shows the selected unit.
+**Why it happens:** `formatWeight` is called in 8 different files. Missing one is easy.
+**How to avoid:** Grep for all `formatWeight` call sites. The complete list is: TotalsBar.tsx, ItemCard.tsx, CandidateCard.tsx, CategoryHeader.tsx, SetupCard.tsx, ItemPicker.tsx, `routes/index.tsx`, `routes/setups/$setupId.tsx`. Update all 8.
+**Warning signs:** Inconsistent unit display across different views.
+
+### Pitfall 4: Default Unit Breaks Existing Behavior
+**What goes wrong:** If the default isn't "g", existing users see different numbers on upgrade.
+**Why it happens:** No `weightUnit` setting exists in the database yet.
+**How to avoid:** Default to `"g"` when `useSetting("weightUnit")` returns null (404 from API). This preserves backward compatibility -- the app looks identical until the user changes the unit.
+**Warning signs:** Weights appearing in ounces on first load without user action.
+
+### Pitfall 5: Rounding Drift on Edit Cycles
+**What goes wrong:** User edits an item, weight displays as "42.3 oz", they save without changing weight, but the stored value shifts.
+**Why it happens:** Would only occur if input fields converted units. Since input stays in grams (per Out of Scope), this cannot happen.
+**How to avoid:** Keep all input fields showing grams. The label says "Weight (g)" and the stored value is always `weight_grams`. Display conversion is one-directional: grams -> display unit.
+**Warning signs:** N/A -- this is prevented by the "input stays in grams" design decision.
+
+### Pitfall 6: React Query Cache Staleness
+**What goes wrong:** User changes unit but some components still show the old unit until they re-render.
+**Why it happens:** The `useUpdateSetting` mutation invalidates `["settings", "weightUnit"]`, but components caching the old value might not immediately re-render.
+**How to avoid:** Since `useWeightUnit()` wraps `useSetting("weightUnit")` which uses React Query with the same query key, invalidation on mutation will trigger re-renders in all subscribed components. This works out of the box.
+**Warning signs:** Temporary inconsistency after changing units -- should resolve within one render cycle.
+
+## Code Examples
+
+### Complete formatWeight Implementation
+
+```typescript
+// src/client/lib/formatters.ts
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+
+const GRAMS_PER_OZ = 28.3495;
+const GRAMS_PER_LB = 453.592;
+const GRAMS_PER_KG = 1000;
+
+export function formatWeight(
+  grams: number | null | undefined,
+  unit: WeightUnit = "g",
+): string {
+  if (grams == null) return "--";
+
+  switch (unit) {
+    case "g":
+      return `${Math.round(grams)}g`;
+    case "oz":
+      return `${(grams / GRAMS_PER_OZ).toFixed(1)} oz`;
+    case "lb":
+      return `${(grams / GRAMS_PER_LB).toFixed(2)} lb`;
+    case "kg":
+      return `${(grams / GRAMS_PER_KG).toFixed(2)} kg`;
+  }
+}
+```
+
+### useWeightUnit Hook
+
+```typescript
+// src/client/hooks/useWeightUnit.ts
+import { useSetting } from "./useSettings";
+import type { WeightUnit } from "../lib/formatters";
+
+const VALID_UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
+
+export function useWeightUnit(): WeightUnit {
+  const { data } = useSetting("weightUnit");
+  if (data && VALID_UNITS.includes(data as WeightUnit)) {
+    return data as WeightUnit;
+  }
+  return "g";
+}
+```
+
+### Component Usage Pattern (e.g., ItemCard)
+
+```typescript
+// Before:
+import { formatWeight } from "../lib/formatters";
+// ...
+{formatWeight(weightGrams)}
+
+// After:
+import { formatWeight } from "../lib/formatters";
+import { useWeightUnit } from "../hooks/useWeightUnit";
+// ...
+const unit = useWeightUnit();
+// ...
+{formatWeight(weightGrams, unit)}
+```
+
+### Stats Prop Pattern (TotalsBar and routes/index.tsx)
+
+When `formatWeight` is called inside a stats array construction (not directly in JSX), the unit must be available in that scope:
+
+```typescript
+// routes/index.tsx - Dashboard
+const unit = useWeightUnit();
+// ...
+stats={[
+  { label: "Items", value: String(global?.itemCount ?? 0) },
+  { label: "Weight", value: formatWeight(global?.totalWeight ?? null, unit) },
+  { label: "Cost", value: formatPrice(global?.totalCost ?? null) },
+]}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| `Math.round(grams) + "g"` (hardcoded) | `formatWeight(grams, unit)` (parameterized) | This phase | All weight displays become unit-aware |
+
+**Deprecated/outdated:**
+- Nothing to deprecate. The old `formatWeight(grams)` signature remains backward-compatible since `unit` defaults to `"g"`.
+
+## Design Recommendations (Claude's Discretion Areas)
+
+### Unit Selector Placement: TotalsBar
+**Recommendation:** Place the unit toggle in the TotalsBar, right side, near the weight stat. The TotalsBar is visible on every page that shows weight (collection, setups). It is the natural place for a global display preference.
+
+### Pounds Display Format: Decimal
+**Recommendation:** Use decimal pounds (`"2.19 lb"`) rather than traditional `"2 lb 3 oz"`. Reasons: (1) simpler implementation, (2) consistent with how LighterPack handles it, (3) easier to compare weights at a glance, (4) traditional format mixes two units which complicates the mental model.
+
+### Precision Per Unit
+**Recommendation:**
+- `g`: 0 decimal places (integers, matching current behavior)
+- `oz`: 1 decimal place (standard for gear weights -- e.g., "14.2 oz")
+- `lb`: 2 decimal places (e.g., "2.19 lb")
+- `kg`: 2 decimal places (e.g., "1.36 kg")
+
+### Default Unit: Grams
+**Recommendation:** Default to `"g"` -- this preserves backward compatibility. When `useSetting("weightUnit")` returns null (no setting in DB), the app behaves identically to today.
+
+### How formatWeight Gets the Unit: Parameter
+**Recommendation:** Pass `unit` as a parameter rather than using React Context or a global. This keeps `formatWeight` a pure function (testable without React), follows the existing pattern of the codebase (no Context providers used anywhere), and makes the data flow explicit.
+
+## Open Questions
+
+1. **Should the unit toggle appear in setup detail view's sub-bar?**
+   - What we know: Setup detail has its own sticky bar below TotalsBar showing setup-specific stats including weight
+   - What's unclear: Whether the global TotalsBar is visible enough from setup detail view
+   - Recommendation: The TotalsBar is sticky at the top on every page. Its toggle applies globally. No need for a second toggle in the setup bar.
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test runner (built-in) |
+| Config file | None (uses bun defaults) |
+| Quick run command | `bun test` |
+| Full suite command | `bun test` |
+
+### Phase Requirements -> Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| UNIT-01 | Settings API accepts and returns weightUnit value | unit | `bun test tests/services/settings.test.ts -t "weightUnit"` | No -- Wave 0 |
+| UNIT-02 | formatWeight converts grams to all 4 units correctly | unit | `bun test tests/lib/formatters.test.ts` | No -- Wave 0 |
+| UNIT-02 | formatWeight handles null/undefined input for all units | unit | `bun test tests/lib/formatters.test.ts` | No -- Wave 0 |
+| UNIT-03 | Settings PUT upserts weightUnit, GET retrieves it | unit | `bun test tests/routes/settings.test.ts` | No -- Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `bun test`
+- **Per wave merge:** `bun test`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] `tests/lib/formatters.test.ts` -- covers UNIT-02 (formatWeight with all units, null handling, precision)
+- [ ] `tests/routes/settings.test.ts` -- covers UNIT-01, UNIT-03 (settings API for weightUnit key)
+
+## Sources
+
+### Primary (HIGH confidence)
+- Codebase inspection: `src/client/lib/formatters.ts`, `src/client/hooks/useSettings.ts`, `src/server/routes/settings.ts`, `src/db/schema.ts` -- all directly read and analyzed
+- Codebase inspection: All 8 `formatWeight` call sites verified via grep
+
+### Secondary (MEDIUM confidence)
+- [LighterPack community patterns](https://backpackers.com/how-to/calculate-backpack-weight/) -- unit toggle between g/oz/lb/kg is standard in gear apps
+- [Metric conversion constants](https://www.metric-conversions.org/weight/) -- 1 oz = 28.3495g, 1 lb = 453.592g, 1 kg = 1000g (verified against international standard)
+
+### Tertiary (LOW confidence)
+- None
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH -- no new dependencies, all existing infrastructure verified in codebase
+- Architecture: HIGH -- single conversion point (`formatWeight`) confirmed, settings system verified working
+- Pitfalls: HIGH -- all based on direct code inspection of null handling, call sites, and data flow
+
+**Research date:** 2026-03-16
+**Valid until:** 2026-04-16 (stable -- no external dependencies or fast-moving APIs)

.planning/phases/07-weight-unit-selection/07-VALIDATION.md

@@ -0,0 +1,77 @@
+---
+phase: 7
+slug: weight-unit-selection
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-16
+---
+
+# Phase 7 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bun test runner (built-in) |
+| **Config file** | None (uses bun defaults) |
+| **Quick run command** | `bun test` |
+| **Full suite command** | `bun test` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun test`
+- **After every plan wave:** Run `bun test`
+- **Before `/gsd:verify-work`:** Full suite must be green
+- **Max feedback latency:** 5 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 07-01-01 | 01 | 1 | UNIT-01 | unit | `bun test tests/routes/settings.test.ts` | No — Wave 0 | ⬜ pending |
+| 07-01-02 | 01 | 1 | UNIT-02 | unit | `bun test tests/lib/formatters.test.ts` | No — Wave 0 | ⬜ pending |
+| 07-01-03 | 01 | 1 | UNIT-03 | unit | `bun test tests/routes/settings.test.ts` | No — Wave 0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `tests/lib/formatters.test.ts` — formatWeight with all 4 units, null handling, precision
+- [ ] `tests/routes/settings.test.ts` — settings API for weightUnit key (GET/PUT)
+
+*Existing test infrastructure (bun test, helpers/db.ts) covers framework setup.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Unit toggle renders in TotalsBar | UNIT-01 | UI component rendering | Open app, verify g/oz/lb/kg toggle visible in TotalsBar |
+| All weight displays update on unit change | UNIT-02 | Visual verification across 8 components | Switch unit, check ItemCard, CandidateCard, CategoryHeader, SetupCard, setup detail, collection route |
+| Setting persists across browser refresh | UNIT-03 | Browser session state | Select "oz", refresh page, verify still shows "oz" |
+
+---
+
+## 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 < 5s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/07-weight-unit-selection/07-VERIFICATION.md

@@ -0,0 +1,138 @@
+---
+phase: 07-weight-unit-selection
+verified: 2026-03-16T12:00:00Z
+status: human_needed
+score: 7/8 must-haves verified
+human_verification:
+  - test: "Navigate to Collection page and verify unit toggle is visible in TotalsBar"
+    expected: "A segmented g/oz/lb/kg pill toggle appears in the top bar between the title and stats"
+    why_human: "Cannot verify visual rendering or UI element presence without a browser"
+  - test: "Click 'oz' in the toggle, verify all weight badges update to ounces"
+    expected: "ItemCards, CategoryHeaders, TotalsBar total, SetupCard weights all update to e.g. '15.9 oz'"
+    why_human: "React Query invalidation and re-render behavior requires runtime verification"
+  - test: "Navigate to Dashboard, then to a Setup detail page, verify weights use selected unit"
+    expected: "All weight displays across pages reflect the chosen unit after selecting 'oz', 'lb', or 'kg'"
+    why_human: "Cross-page state propagation via settings API requires runtime verification"
+  - test: "Select 'kg', then refresh the page"
+    expected: "After refresh, weights still display in kg (unit persists)"
+    why_human: "Settings persistence across sessions requires runtime verification"
+---
+
+# Phase 7: Weight Unit Selection Verification Report
+
+**Phase Goal:** Users see all weights in their preferred unit across the entire app
+**Verified:** 2026-03-16T12:00:00Z
+**Status:** human_needed
+**Re-verification:** No - initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | formatWeight converts grams to g, oz, lb, kg with correct precision | VERIFIED | `src/client/lib/formatters.ts` switch statement with `toFixed(1)` oz, `toFixed(2)` lb/kg. 21 tests all pass. |
+| 2 | formatWeight defaults to grams when no unit is specified (backward compatible) | VERIFIED | Signature `unit: WeightUnit = "g"`. Test: `formatWeight(100)` returns `"100g"`. |
+| 3 | formatWeight handles null/undefined input for all units | VERIFIED | Null guard `if (grams == null) return "--"` fires before switch. 7 null/undefined tests pass. |
+| 4 | useWeightUnit hook returns a valid WeightUnit from settings, defaulting to 'g' | VERIFIED | `useWeightUnit.ts` validates against `VALID_UNITS` array and returns `"g"` fallback. |
+| 5 | User can see a unit toggle (g/oz/lb/kg) in the TotalsBar | ? NEEDS HUMAN | Toggle code exists in TotalsBar.tsx (lines 70-90), but visual rendering requires browser. |
+| 6 | Clicking a unit in the toggle changes all weight displays across the app | ? NEEDS HUMAN | `useUpdateSetting.mutate({ key: "weightUnit", value: u })` wired. React Query invalidation behavior requires runtime. |
+| 7 | Weight unit selection persists after page refresh | ? NEEDS HUMAN | Persistence via `GET /api/settings/weightUnit` in `useSetting`. Requires runtime verification. |
+| 8 | Every weight display in the app uses the selected unit | VERIFIED | All 9 formatWeight call sites in `src/client/` pass `unit` argument. Grep confirms no bare `formatWeight(grams)` calls remain in components. |
+
+**Score:** 5/5 automated truths verified, 3/3 runtime truths require human verification
+
+### Required Artifacts
+
+#### Plan 01 Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/client/lib/formatters.ts` | WeightUnit type export and parameterized formatWeight | VERIFIED | Exports `WeightUnit`, `formatWeight`, `formatPrice`. Contains switch for all 4 units. 28 lines, substantive. |
+| `src/client/hooks/useWeightUnit.ts` | Convenience hook wrapping useSetting for weight unit | VERIFIED | Exports `useWeightUnit`. Imports `WeightUnit` from formatters, `useSetting` from useSettings. 13 lines, substantive. |
+| `tests/lib/formatters.test.ts` | Unit tests for formatWeight with all 4 units and edge cases | VERIFIED | 98 lines (min_lines=30 satisfied). 21 tests across 7 describe blocks covering g/oz/lb/kg, null/undefined, backward compat, zero, edge cases. All pass. |
+
+#### Plan 02 Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/client/components/TotalsBar.tsx` | Unit toggle UI and unit-aware weight display | VERIFIED | Contains `useWeightUnit`, `useUpdateSetting`, UNITS array, segmented pill toggle JSX. `formatWeight` calls pass `unit`. |
+| `src/client/components/ItemCard.tsx` | Unit-aware item weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(weightGrams, unit)` on line 127. |
+| `src/client/components/CandidateCard.tsx` | Unit-aware candidate weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(weightGrams, unit)` on line 93. |
+| `src/client/components/CategoryHeader.tsx` | Unit-aware category total weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(totalWeight, unit)` on line 90. |
+| `src/client/components/SetupCard.tsx` | Unit-aware setup weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(totalWeight, unit)` on line 35. |
+| `src/client/components/ItemPicker.tsx` | Unit-aware item picker weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(item.weightGrams, unit)` on line 119. |
+| `src/client/routes/index.tsx` | Unit-aware dashboard weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(global?.totalWeight ?? null, unit)` on line 34. |
+| `src/client/routes/setups/$setupId.tsx` | Unit-aware setup detail weight display | VERIFIED | Contains `useWeightUnit`. `formatWeight(totalWeight, unit)` on line 110. |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `useWeightUnit.ts` | `useSettings.ts` | `useSetting('weightUnit')` | WIRED | Line 7: `const { data } = useSetting("weightUnit");` |
+| `useWeightUnit.ts` | `formatters.ts` | imports WeightUnit type | WIRED | Line 1: `import type { WeightUnit } from "../lib/formatters";` |
+| `TotalsBar.tsx` | `/api/settings/weightUnit` | useUpdateSetting mutation | WIRED | Line 76-79: `updateSetting.mutate({ key: "weightUnit", value: u })` |
+| `ItemCard.tsx` | `useWeightUnit.ts` | useWeightUnit hook import | WIRED | Line 1: `import { useWeightUnit } from "../hooks/useWeightUnit";` — called at line 29, used at line 127 |
+| `TotalsBar.tsx` | `formatters.ts` | formatWeight(grams, unit) | WIRED | Lines 33, 39: both calls pass `unit` from `useWeightUnit()` |
+
+### Requirements Coverage
+
+| Requirement | Source Plan(s) | Description | Status | Evidence |
+|-------------|---------------|-------------|--------|----------|
+| UNIT-01 | 07-02-PLAN | User can select preferred weight unit (g, oz, lb, kg) from settings | VERIFIED (automated) / NEEDS HUMAN (runtime) | Segmented toggle code in TotalsBar.tsx lines 70-90. Runtime: needs human to confirm visual and click behavior. |
+| UNIT-02 | 07-01-PLAN, 07-02-PLAN | All weight displays across the app reflect the selected unit | VERIFIED | All 9 formatWeight call sites in components pass `unit`. No bare `formatWeight(grams)` calls remain. |
+| UNIT-03 | 07-01-PLAN, 07-02-PLAN | Weight unit preference persists across sessions | VERIFIED (mechanism) / NEEDS HUMAN (runtime) | `useSetting("weightUnit")` reads from `/api/settings/weightUnit`. `useUpdateSetting` writes to same endpoint. Persistence across refresh requires runtime verification. |
+
+No orphaned requirements. REQUIREMENTS.md marks all three as complete for Phase 7. All three requirement IDs appear in at least one plan's `requirements` field.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| — | — | None found | — | — |
+
+Scanned all 11 modified files. No TODOs, FIXMEs, placeholder comments, empty implementations, or stub returns found. All `formatWeight` calls outside `formatters.ts` carry the `unit` argument.
+
+### Human Verification Required
+
+#### 1. Unit Toggle Visibility
+
+**Test:** Start `bun run dev:client` and `bun run dev:server`, navigate to http://localhost:5173/collection
+**Expected:** A segmented pill toggle showing g / oz / lb / kg is visible in the sticky top bar, positioned between the GearBox title and the stats (items / total / spent)
+**Why human:** Visual rendering cannot be verified programmatically
+
+#### 2. Unit Toggle Click Behavior
+
+**Test:** With the app running, click "oz" in the toggle on the Collection page
+**Expected:** All weight badges on ItemCards, CategoryHeader totals, and the TotalsBar total update immediately to ounce values (e.g., "15.9 oz"). No page reload required.
+**Why human:** React Query cache invalidation and live re-render require runtime observation
+
+#### 3. Cross-Page Unit Consistency
+
+**Test:** Select "lb" on the Collection page, then navigate to the Dashboard (/), then navigate to a Setup detail page
+**Expected:** The Dashboard Collection card weight shows in lb; all weights in the Setup detail sticky bar and ItemCards show in lb
+**Why human:** Cross-page state propagation via TanStack Router and shared React Query cache requires runtime verification
+
+#### 4. Persistence Across Refresh
+
+**Test:** Select "kg", then hard-refresh the page (Ctrl+R or F5)
+**Expected:** After refresh, all weights still display in kg. The kg button appears active/highlighted in the toggle.
+**Why human:** Browser session handling and settings API round-trip require runtime verification
+
+### Gaps Summary
+
+No automated gaps found. All artifacts exist, are substantive, and are correctly wired. The 3 human verification items are standard runtime behaviors (visual rendering, live updates, persistence) that cannot be verified statically.
+
+The implementation is complete and correct based on static analysis:
+- `formatWeight` conversion math is verified by 21 passing tests
+- All 8 component call sites pass `unit` from `useWeightUnit()` — confirmed by exhaustive grep
+- TotalsBar contains the full toggle UI with `useUpdateSetting` wired to `weightUnit` key
+- `useWeightUnit` correctly wraps `useSetting("weightUnit")` with type validation and "g" default
+- Full test suite (108 tests) passes with no regressions
+- Lint clean (78 files, no issues)
+- All 4 phase commits verified in git history (431c179, 6cac0a3, ada3791, faa4378)
+
+---
+
+_Verified: 2026-03-16T12:00:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/08-search-filter-and-candidate-status/08-01-PLAN.md

@@ -0,0 +1,240 @@
+---
+phase: 08-search-filter-and-candidate-status
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/db/schema.ts
+  - src/shared/schemas.ts
+  - src/server/services/thread.service.ts
+  - src/client/hooks/useThreads.ts
+  - src/client/hooks/useCandidates.ts
+  - src/client/components/StatusBadge.tsx
+  - src/client/components/CandidateCard.tsx
+  - tests/helpers/db.ts
+  - tests/services/thread.service.test.ts
+autonomous: true
+requirements: [CAND-01, CAND-02, CAND-03]
+
+must_haves:
+  truths:
+    - "Each candidate displays a status badge showing one of three statuses: researching, ordered, or arrived"
+    - "User can click a status badge to open a popup menu and change the candidate's status to any of the three options"
+    - "New candidates automatically have status 'researching' without the user needing to set it"
+  artifacts:
+    - path: "src/db/schema.ts"
+      provides: "status column on threadCandidates table"
+      contains: "status: text(\"status\").notNull().default(\"researching\")"
+    - path: "src/shared/schemas.ts"
+      provides: "candidateStatusSchema Zod enum"
+      exports: ["candidateStatusSchema"]
+    - path: "src/server/services/thread.service.ts"
+      provides: "status field in candidate CRUD operations"
+      contains: "status: threadCandidates.status"
+    - path: "src/client/components/StatusBadge.tsx"
+      provides: "Clickable status badge with popup menu"
+      exports: ["StatusBadge"]
+    - path: "src/client/components/CandidateCard.tsx"
+      provides: "CandidateCard renders StatusBadge in pill row"
+      contains: "StatusBadge"
+    - path: "tests/helpers/db.ts"
+      provides: "status column in test helper CREATE TABLE"
+      contains: "status TEXT NOT NULL DEFAULT 'researching'"
+  key_links:
+    - from: "src/client/components/StatusBadge.tsx"
+      to: "/api/threads/:id/candidates/:candidateId"
+      via: "useUpdateCandidate mutation"
+      pattern: "onStatusChange"
+    - from: "src/server/services/thread.service.ts"
+      to: "src/db/schema.ts"
+      via: "threadCandidates.status in select and update"
+      pattern: "threadCandidates\\.status"
+    - from: "src/client/components/CandidateCard.tsx"
+      to: "src/client/components/StatusBadge.tsx"
+      via: "StatusBadge component in pill row"
+      pattern: "<StatusBadge"
+---
+
+<objective>
+Add candidate status tracking (researching/ordered/arrived) as a full vertical slice: schema migration, service/Zod updates, tests, and clickable status badge UI on CandidateCard.
+
+Purpose: Let users track purchase progress for candidates they are evaluating in planning threads.
+Output: Working status badge on each candidate card with popup menu to change status.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md
+@.planning/phases/08-search-filter-and-candidate-status/08-RESEARCH.md
+
+@src/db/schema.ts
+@src/shared/schemas.ts
+@src/shared/types.ts
+@src/server/services/thread.service.ts
+@src/client/hooks/useThreads.ts
+@src/client/hooks/useCandidates.ts
+@src/client/components/CandidateCard.tsx
+@tests/helpers/db.ts
+@tests/services/thread.service.test.ts
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/shared/types.ts:
+```typescript
+export type CreateCandidate = z.infer<typeof createCandidateSchema>;
+export type UpdateCandidate = z.infer<typeof updateCandidateSchema>;
+export type ThreadCandidate = typeof threadCandidates.$inferSelect;
+```
+
+From src/client/hooks/useCandidates.ts:
+```typescript
+export function useUpdateCandidate(threadId: number) {
+  // mutationFn: ({ candidateId, ...data }) => apiPut(...)
+  // Already accepts partial updates. Use for status changes.
+}
+```
+
+From src/client/hooks/useThreads.ts:
+```typescript
+interface CandidateWithCategory {
+  id: number; threadId: number; name: string;
+  weightGrams: number | null; priceCents: number | null;
+  categoryId: number; notes: string | null;
+  productUrl: string | null; imageFilename: string | null;
+  createdAt: string; updatedAt: string;
+  categoryName: string; categoryIcon: string;
+  // status field NOT YET present -- Task 1 adds it
+}
+```
+
+From src/client/components/CandidateCard.tsx:
+```typescript
+interface CandidateCardProps {
+  id: number; name: string; weightGrams: number | null;
+  priceCents: number | null; categoryName: string;
+  categoryIcon: string; imageFilename: string | null;
+  productUrl?: string | null; threadId: number; isActive: boolean;
+  // status prop NOT YET present -- Task 2 adds it
+}
+```
+
+From src/client/lib/iconData.tsx:
+```typescript
+export function LucideIcon({ name, size, className }: {
+  name: string; size?: number; className?: string;
+}): JSX.Element;
+// Valid icon names for status: "search", "truck", "check"
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Add status column and update backend + tests</name>
+  <files>src/db/schema.ts, src/shared/schemas.ts, src/server/services/thread.service.ts, src/client/hooks/useThreads.ts, src/client/hooks/useCandidates.ts, tests/helpers/db.ts, tests/services/thread.service.test.ts</files>
+  <behavior>
+    - Test: createCandidate without status returns a candidate with status "researching"
+    - Test: createCandidate with status "ordered" returns a candidate with status "ordered"
+    - Test: updateCandidate can change status from "researching" to "ordered"
+    - Test: updateCandidate can change status from "ordered" to "arrived"
+    - Test: getThreadWithCandidates includes status field on each candidate
+  </behavior>
+  <action>
+    1. **Schema migration** -- Add status column to `threadCandidates` in `src/db/schema.ts`:
+       ```typescript
+       status: text("status").notNull().default("researching"),
+       ```
+       Then run `bun run db:generate && bun run db:push` to apply.
+
+    2. **Zod schemas** -- In `src/shared/schemas.ts`, add:
+       ```typescript
+       export const candidateStatusSchema = z.enum(["researching", "ordered", "arrived"]);
+       ```
+       Add `status: candidateStatusSchema.optional()` to `createCandidateSchema`. Since `updateCandidateSchema = createCandidateSchema.partial()`, it automatically includes status as optional.
+
+    3. **Service updates** -- In `src/server/services/thread.service.ts`:
+       - In `getThreadWithCandidates`, add `status: threadCandidates.status` to the select object (between `imageFilename` and `createdAt`).
+       - In `createCandidate`, add `status: data.status ?? "researching"` to the values object.
+       - In `updateCandidate`, add `status` to the data type: `status: "researching" | "ordered" | "arrived"`.
+
+    4. **Client type updates** -- In `src/client/hooks/useThreads.ts`, add `status: "researching" | "ordered" | "arrived"` to `CandidateWithCategory` interface. In `src/client/hooks/useCandidates.ts`, add `status?: "researching" | "ordered" | "arrived"` to `CandidateResponse` interface.
+
+    5. **Test helper** -- In `tests/helpers/db.ts`, add `status TEXT NOT NULL DEFAULT 'researching'` to the `thread_candidates` CREATE TABLE statement (after `image_filename TEXT` line).
+
+    6. **Service tests** -- In `tests/services/thread.service.test.ts`, add a describe block "candidate status" with the tests from the behavior section above.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test tests/services/thread.service.test.ts</automated>
+  </verify>
+  <done>Status column exists in schema, migration applied, all CRUD operations handle status field, all tests pass including new status tests.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create StatusBadge component and wire into CandidateCard</name>
+  <files>src/client/components/StatusBadge.tsx, src/client/components/CandidateCard.tsx</files>
+  <action>
+    1. **Create `src/client/components/StatusBadge.tsx`** -- A clickable pill badge with popup menu:
+       - Props: `status: "researching" | "ordered" | "arrived"`, `onStatusChange: (status: "researching" | "ordered" | "arrived") => void`
+       - Status config map:
+         ```typescript
+         const STATUS_CONFIG = {
+           researching: { icon: "search", label: "Researching" },
+           ordered: { icon: "truck", label: "Ordered" },
+           arrived: { icon: "check", label: "Arrived" },
+         } as const;
+         ```
+       - Render as a pill button (muted gray tones per user decision -- NOT semantic colors):
+         - Use `bg-gray-100 text-gray-600` styling, similar neutral tone to the category pill
+         - Show `LucideIcon` (size 14) + text label
+       - On click: call `e.stopPropagation()` (prevent card click propagation per pitfall #3), toggle popup menu open/closed
+       - Popup menu: `position: absolute` below the badge, `right-0`, with 3 options (each showing icon + label). Use a `containerRef` + `useEffect` mousedown listener for click-outside dismiss (same pattern as `CategoryPicker`). Pressing Escape also closes the menu.
+       - When an option is clicked: call `onStatusChange(selectedStatus)`, close the menu.
+       - Show a subtle checkmark or different background on the currently active status in the menu.
+
+    2. **Update `src/client/components/CandidateCard.tsx`**:
+       - Add `status: "researching" | "ordered" | "arrived"` and `onStatusChange: (status: "researching" | "ordered" | "arrived") => void` to `CandidateCardProps`.
+       - Import `StatusBadge` from `./StatusBadge`.
+       - Add `<StatusBadge status={status} onStatusChange={onStatusChange} />` to the pill row (the `flex flex-wrap gap-1.5 mb-3` div), after the category pill.
+
+    3. **Update thread detail page caller** -- Find where `CandidateCard` is rendered (in the thread detail route). Add the `status` and `onStatusChange` props. For `onStatusChange`, use the existing `useUpdateCandidate` hook: `updateCandidate.mutate({ candidateId: candidate.id, status: newStatus })`.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint && bun test</automated>
+  </verify>
+  <done>Each candidate card shows a gray status badge (icon + label) in the pill row. Clicking the badge opens a popup menu with all three status options. Selecting a status updates it via the API and the badge reflects the new status. New candidates show "Researching" by default.</done>
+</task>
+
+</tasks>
+
+<verification>
+1. `bun test` -- all existing and new tests pass
+2. `bun run lint` -- no lint errors
+3. Start dev server (`bun run dev:server` + `bun run dev:client`), navigate to a thread detail page, verify:
+   - Each candidate shows a gray "Researching" badge in the pill row
+   - Clicking the badge opens a popup menu with Researching, Ordered, Arrived options
+   - Selecting a different status updates the badge immediately
+   - Refreshing the page shows the persisted status
+</verification>
+
+<success_criteria>
+- Status column exists on thread_candidates table with default "researching"
+- All candidate CRUD operations handle the status field
+- StatusBadge component renders in CandidateCard pill row with muted gray styling
+- Clicking badge opens popup menu, selecting an option changes status via API
+- New candidates show "researching" status by default
+- All tests pass including 5 new status-specific tests
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-search-filter-and-candidate-status/08-01-SUMMARY.md`
+</output>

.planning/phases/08-search-filter-and-candidate-status/08-01-SUMMARY.md

@@ -0,0 +1,112 @@
+---
+phase: 08-search-filter-and-candidate-status
+plan: 01
+subsystem: database, api, ui
+tags: [drizzle, sqlite, zod, react, tailwind, status-tracking]
+
+requires:
+  - phase: 05-thread-candidates
+    provides: threadCandidates table and CRUD service
+provides:
+  - status column on thread_candidates (researching/ordered/arrived)
+  - candidateStatusSchema Zod enum for validation
+  - StatusBadge clickable component with popup menu
+  - Status field in candidate CRUD operations
+affects: [08-search-filter-and-candidate-status]
+
+tech-stack:
+  added: []
+  patterns: [click-outside-dismiss-popup, status-badge-pill-with-menu]
+
+key-files:
+  created:
+    - src/client/components/StatusBadge.tsx
+    - drizzle/0002_broken_roughhouse.sql
+  modified:
+    - src/db/schema.ts
+    - src/shared/schemas.ts
+    - src/server/services/thread.service.ts
+    - src/client/hooks/useThreads.ts
+    - src/client/hooks/useCandidates.ts
+    - src/client/components/CandidateCard.tsx
+    - src/client/routes/threads/$threadId.tsx
+    - tests/helpers/db.ts
+    - tests/services/thread.service.test.ts
+
+key-decisions:
+  - "StatusBadge popup uses click-outside + Escape dismiss pattern matching CategoryPicker"
+  - "Status badge uses muted gray tones (bg-gray-100 text-gray-600) per user design decision"
+
+patterns-established:
+  - "StatusBadge popup: absolute positioned dropdown with click-outside dismiss via containerRef + useEffect mousedown listener"
+
+requirements-completed: [CAND-01, CAND-02, CAND-03]
+
+duration: 5min
+completed: 2026-03-16
+---
+
+# Phase 8 Plan 1: Candidate Status Tracking Summary
+
+**Candidate status tracking (researching/ordered/arrived) with schema migration, service/Zod updates, 5 TDD tests, and clickable StatusBadge popup on CandidateCard**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-16T13:06:48Z
+- **Completed:** 2026-03-16T13:12:08Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+- Added `status` column to `thread_candidates` table with default "researching" and full Drizzle migration
+- Wired status through entire stack: schema, Zod validation, service CRUD, client type interfaces
+- Created StatusBadge component with clickable pill badge and popup menu (3 status options with icons)
+- Integrated StatusBadge into CandidateCard pill row with API mutation on status change
+- 5 new TDD tests covering all status CRUD operations (24 total thread service tests passing)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add status column and update backend + tests (TDD RED)** - `9342085` (test)
+2. **Task 1: Add status column and update backend + tests (TDD GREEN)** - `ca1c2a2` (feat)
+3. **Task 2: Create StatusBadge component and wire into CandidateCard** - `25956ed` (feat)
+
+_Note: Task 1 used TDD with separate RED and GREEN commits_
+
+## Files Created/Modified
+- `src/db/schema.ts` - Added status column to threadCandidates table
+- `src/shared/schemas.ts` - Added candidateStatusSchema Zod enum and status to createCandidateSchema
+- `src/server/services/thread.service.ts` - Status in getThreadWithCandidates select, createCandidate values, updateCandidate type
+- `src/client/hooks/useThreads.ts` - Added status to CandidateWithCategory interface
+- `src/client/hooks/useCandidates.ts` - Added status to CandidateResponse interface
+- `src/client/components/StatusBadge.tsx` - New clickable status badge with popup menu
+- `src/client/components/CandidateCard.tsx` - Added status and onStatusChange props, renders StatusBadge
+- `src/client/routes/threads/$threadId.tsx` - Passes status and useUpdateCandidate to CandidateCard
+- `tests/helpers/db.ts` - Added status column to test helper CREATE TABLE
+- `tests/services/thread.service.test.ts` - 5 new candidate status tests
+- `drizzle/0002_broken_roughhouse.sql` - Migration adding status column
+
+## Decisions Made
+- StatusBadge popup uses click-outside + Escape dismiss pattern matching CategoryPicker
+- Status badge uses muted gray tones (bg-gray-100 text-gray-600) per user design decision -- not semantic colors
+- Active status in popup menu highlighted with bg-gray-50 and checkmark icon
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Candidate status tracking fully operational
+- Ready for Plan 02 (search/filter functionality)
+
+---
+*Phase: 08-search-filter-and-candidate-status*
+*Completed: 2026-03-16*

.planning/phases/08-search-filter-and-candidate-status/08-02-PLAN.md

@@ -0,0 +1,292 @@
+---
+phase: 08-search-filter-and-candidate-status
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/client/components/CategoryFilterDropdown.tsx
+  - src/client/routes/collection/index.tsx
+autonomous: true
+requirements: [SRCH-01, SRCH-02, SRCH-03, SRCH-04, SRCH-05, PLAN-01]
+
+must_haves:
+  truths:
+    - "User can type in a search field on the gear tab and see items filtered instantly by name as they type"
+    - "User can select a category from a searchable dropdown (with Lucide icons) to filter items on both gear and planning tabs"
+    - "User can combine text search with category filter to narrow results"
+    - "User sees 'Showing X of Y items' when filters are active on the gear tab"
+    - "User clears search text and resets category dropdown individually (no combined clear button)"
+    - "When filters are active, items display as a flat grid without category group headers"
+    - "Empty filter results show 'No items match your search' message"
+    - "Planning tab category filter shows Lucide icons alongside category names"
+  artifacts:
+    - path: "src/client/components/CategoryFilterDropdown.tsx"
+      provides: "Shared searchable category filter dropdown with Lucide icons"
+      exports: ["CategoryFilterDropdown"]
+      min_lines: 60
+    - path: "src/client/routes/collection/index.tsx"
+      provides: "Search/filter toolbar in CollectionView, CategoryFilterDropdown in PlanningView"
+      contains: "CategoryFilterDropdown"
+  key_links:
+    - from: "src/client/components/CategoryFilterDropdown.tsx"
+      to: "src/client/hooks/useCategories.ts"
+      via: "categories prop passed from parent (useCategories data)"
+      pattern: "categories"
+    - from: "src/client/routes/collection/index.tsx (CollectionView)"
+      to: "src/client/components/CategoryFilterDropdown.tsx"
+      via: "CategoryFilterDropdown in sticky toolbar"
+      pattern: "<CategoryFilterDropdown"
+    - from: "src/client/routes/collection/index.tsx (PlanningView)"
+      to: "src/client/components/CategoryFilterDropdown.tsx"
+      via: "CategoryFilterDropdown replacing native select"
+      pattern: "<CategoryFilterDropdown"
+    - from: "src/client/routes/collection/index.tsx (CollectionView)"
+      to: "useItems data"
+      via: "useMemo filter chain on searchText + categoryFilter"
+      pattern: "filteredItems"
+---
+
+<objective>
+Add search/filter toolbar to the gear tab and a shared icon-aware category filter dropdown to both gear and planning tabs. Users can search items by name, filter by category, see result counts, and clear filters individually.
+
+Purpose: Help users find items quickly as collections grow, and upgrade the planning tab's plain `<select>` to a searchable icon-aware dropdown.
+Output: Sticky search/filter toolbar on gear tab, shared CategoryFilterDropdown component on both tabs.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md
+@.planning/phases/08-search-filter-and-candidate-status/08-RESEARCH.md
+
+@src/client/routes/collection/index.tsx
+@src/client/components/CategoryPicker.tsx
+@src/client/hooks/useCategories.ts
+@src/client/hooks/useItems.ts
+@src/client/lib/iconData.tsx
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/client/hooks/useItems.ts:
+```typescript
+// useItems() returns items with these fields:
+interface ItemWithCategory {
+  id: number; name: string; weightGrams: number | null;
+  priceCents: number | null; categoryId: number;
+  notes: string | null; productUrl: string | null;
+  imageFilename: string | null; createdAt: string; updatedAt: string;
+  categoryName: string; categoryIcon: string;
+}
+```
+
+From src/client/hooks/useCategories.ts:
+```typescript
+// useCategories() returns:
+interface CategoryItem {
+  id: number; name: string; icon: string; createdAt: string;
+}
+```
+
+From src/client/lib/iconData.tsx:
+```typescript
+export function LucideIcon({ name, size, className }: {
+  name: string; size?: number; className?: string;
+}): JSX.Element;
+```
+
+From src/client/routes/collection/index.tsx:
+```typescript
+// CollectionView currently:
+// - Uses useItems() for all items
+// - Groups items by categoryId into Map
+// - Renders CategoryHeader + grid per category group
+// - No search or filter state
+
+// PlanningView currently:
+// - Has categoryFilter useState<number | null>(null)
+// - Uses a native <select> for category filtering (lines 277-291)
+// - Filters threads by activeTab and categoryFilter
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create CategoryFilterDropdown component</name>
+  <files>src/client/components/CategoryFilterDropdown.tsx</files>
+  <action>
+    Create `src/client/components/CategoryFilterDropdown.tsx` -- a searchable dropdown showing categories with Lucide icons. This is a FILTER dropdown, NOT the form-based `CategoryPicker` (which handles creation). Keep them separate per user decision.
+
+    **Props:**
+    ```typescript
+    interface CategoryFilterDropdownProps {
+      value: number | null;           // selected category ID, null = "All categories"
+      onChange: (value: number | null) => void;
+      categories: Array<{ id: number; name: string; icon: string }>;
+    }
+    ```
+
+    **Structure:**
+    - **Trigger button**: Shows "All categories" with a chevron-down icon when `value` is null. Shows the selected category's `LucideIcon` (size 14) + name when a category is selected. Style: `px-3 py-2 border border-gray-200 rounded-lg text-sm bg-white` (matching search input height). Include a small clear "x" button on the right when a category is selected (clicking it calls `onChange(null)` without opening the dropdown).
+    - **Dropdown panel**: Opens below the trigger, `position: absolute`, `z-20`, white bg, border, rounded-lg, shadow-lg, max-height with overflow-y-auto. Width matches trigger or has a reasonable min-width (~220px).
+    - **Search input inside dropdown**: Text input at top of dropdown, placeholder "Search categories...", filters the category list as user types. Auto-focused when dropdown opens.
+    - **Option list**: "All categories" as first option (selecting calls `onChange(null)` and closes). Then each category: `LucideIcon` (size 16) + category name. Highlight the currently selected option with a subtle bg color. Hover state on each option.
+    - **Click-outside dismiss**: Use `containerRef` + `useEffect` mousedown listener pattern (same as `CategoryPicker`). Also close on Escape keydown.
+    - **State reset**: Clear internal search text when dropdown closes.
+
+    **Do NOT:**
+    - Reuse or modify `CategoryPicker.tsx`
+    - Add category creation capability
+    - Use Zustand for dropdown open/closed state (use local `useState`)
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint</automated>
+  </verify>
+  <done>CategoryFilterDropdown.tsx exists with searchable dropdown, Lucide icons per option, "All categories" first option, click-outside dismiss, clear button on trigger, and Escape to close. Lint passes.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add search/filter toolbar to CollectionView and replace select in PlanningView</name>
+  <files>src/client/routes/collection/index.tsx</files>
+  <action>
+    Modify `src/client/routes/collection/index.tsx` to add search and filtering to `CollectionView` and upgrade `PlanningView`'s category filter.
+
+    **CollectionView changes:**
+
+    1. Add filter state at the top of `CollectionView`:
+       ```typescript
+       const [searchText, setSearchText] = useState("");
+       const [categoryFilter, setCategoryFilter] = useState<number | null>(null);
+       ```
+
+    2. Add `useCategories` hook: `const { data: categories } = useCategories();`
+
+    3. Add filtered items computation with `useMemo`:
+       ```typescript
+       const filteredItems = useMemo(() => {
+         if (!items) return [];
+         return items.filter((item) => {
+           const matchesSearch = searchText === "" ||
+             item.name.toLowerCase().includes(searchText.toLowerCase());
+           const matchesCategory = categoryFilter === null ||
+             item.categoryId === categoryFilter;
+           return matchesSearch && matchesCategory;
+         });
+       }, [items, searchText, categoryFilter]);
+       ```
+       Import `useMemo` from React, import `useCategories` from hooks.
+
+    4. Compute filter state:
+       ```typescript
+       const hasActiveFilters = searchText !== "" || categoryFilter !== null;
+       ```
+
+    5. Add sticky toolbar ABOVE the existing item grid rendering (after loading/empty checks, before the grouped items). The toolbar only shows when there are items:
+       ```jsx
+       <div className="sticky top-0 z-10 bg-white/95 backdrop-blur-sm border-b border-gray-100 -mx-4 px-4 py-3 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 mb-6">
+         <div className="flex gap-3 items-center">
+           <div className="relative flex-1">
+             <input
+               type="text"
+               placeholder="Search items..."
+               value={searchText}
+               onChange={(e) => setSearchText(e.target.value)}
+               className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
+             />
+             {searchText && (
+               <button onClick={() => setSearchText("")} className="absolute right-2 top-1/2 -translate-y-1/2 text-gray-400 hover:text-gray-600">
+                 {/* small x icon */}
+               </button>
+             )}
+           </div>
+           <CategoryFilterDropdown
+             value={categoryFilter}
+             onChange={setCategoryFilter}
+             categories={categories ?? []}
+           />
+         </div>
+         {hasActiveFilters && (
+           <p className="text-xs text-gray-500 mt-2">
+             Showing {filteredItems.length} of {items?.length ?? 0} items
+           </p>
+         )}
+       </div>
+       ```
+
+    6. Conditional rendering based on filter state:
+       - **When `hasActiveFilters` is true**: Render `filteredItems` as a flat grid (no category grouping, no `CategoryHeader`). If `filteredItems.length === 0`, show "No items match your search" centered text message.
+       - **When `hasActiveFilters` is false**: Keep existing category-grouped rendering exactly as-is (the `groupedItems` Map pattern), but use `filteredItems` as the source (which equals all items when no filters).
+
+    **PlanningView changes:**
+
+    1. Import `CategoryFilterDropdown` from `../../components/CategoryFilterDropdown`.
+    2. Replace the native `<select>` element (lines ~277-291) with:
+       ```jsx
+       <CategoryFilterDropdown
+         value={categoryFilter}
+         onChange={setCategoryFilter}
+         categories={categories ?? []}
+       />
+       ```
+    3. Remove the `useCategories` hook call if it's already called earlier, or keep it -- just make sure categories data is available.
+
+    **Important per user decisions:**
+    - Search matches item names ONLY (not category names) -- the dropdown handles category filtering
+    - No debounce on search input (per CONTEXT.md, <1000 items)
+    - No combined "clear all" button -- user clears search and dropdown individually
+    - Filters naturally reset on tab switch because `CollectionView` unmounts when tab changes (conditional rendering in `CollectionPage`). Verify this is the case -- if `CollectionView` stays mounted, add a `key={tab}` prop to force remount.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint && bun test</automated>
+  </verify>
+  <done>Gear tab has a sticky search/filter toolbar with text input and CategoryFilterDropdown side by side. Typing filters items by name instantly. Selecting a category filters by category. Both filters combine. "Showing X of Y items" appears when filters are active. Empty results show message. Flat grid renders when filters active (no category headers). Planning tab uses CategoryFilterDropdown with Lucide icons instead of native select. All tests and lint pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+1. `bun run lint` -- no lint errors
+2. `bun test` -- all tests pass
+3. Start dev server, navigate to gear tab:
+   - Sticky toolbar visible with search input + category dropdown
+   - Type in search: items filter by name instantly
+   - Select a category from dropdown (icons visible): items filter by category
+   - Both filters combine correctly
+   - "Showing X of Y items" text appears when filters active
+   - Empty results show "No items match your search"
+   - Filtered items show as flat grid (no category headers)
+   - Clear search text: category filter still applies
+   - Select "All categories": search filter still applies
+   - Switch to planning tab: filters reset
+   - Switch back to gear tab: filters reset (clean state)
+4. Navigate to planning tab:
+   - Category filter dropdown shows Lucide icons alongside names
+   - Searchable within the dropdown
+   - "All categories" as first option
+   - Selecting a category shows icon + name in trigger button
+</verification>
+
+<success_criteria>
+- Search input filters items by name on every keystroke (no debounce)
+- CategoryFilterDropdown shows icons, is searchable, has "All categories" option
+- Filters combine (text AND category)
+- Result count displayed when filters active
+- Flat grid (no category headers) when any filter active
+- "No items match your search" on empty results
+- Filters reset on tab switch
+- Planning tab uses shared CategoryFilterDropdown instead of native select
+- Lint and tests pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-search-filter-and-candidate-status/08-02-SUMMARY.md`
+</output>

.planning/phases/08-search-filter-and-candidate-status/08-02-SUMMARY.md

@@ -0,0 +1,101 @@
+---
+phase: 08-search-filter-and-candidate-status
+plan: 02
+subsystem: ui
+tags: [react, search, filter, dropdown, lucide-icons, useMemo]
+
+# Dependency graph
+requires:
+  - phase: 06-category-system-and-ui-redesign
+    provides: CategoryPicker pattern, LucideIcon component, useCategories hook
+provides:
+  - CategoryFilterDropdown reusable component with icon-aware searchable dropdown
+  - Search/filter toolbar on gear tab with text search and category filtering
+  - Upgraded planning tab category filter with Lucide icons
+affects: []
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "CategoryFilterDropdown: filter-only dropdown separate from form-based CategoryPicker"
+    - "useMemo filter chain for combining text search + category filter"
+    - "Conditional rendering: flat grid (no category headers) when filters active"
+
+key-files:
+  created:
+    - src/client/components/CategoryFilterDropdown.tsx
+  modified:
+    - src/client/routes/collection/index.tsx
+
+key-decisions:
+  - "Kept CategoryFilterDropdown separate from CategoryPicker (filter vs form concerns)"
+  - "No debounce on search input (collection under 1000 items)"
+  - "Individual clear controls (no combined clear-all button)"
+
+patterns-established:
+  - "CategoryFilterDropdown: reusable filter dropdown with icons, search, click-outside dismiss"
+  - "Flat grid rendering when filters active to avoid confusing partial category headers"
+
+requirements-completed: [SRCH-01, SRCH-02, SRCH-03, SRCH-04, SRCH-05, PLAN-01]
+
+# Metrics
+duration: 3min
+completed: 2026-03-16
+---
+
+# Phase 8 Plan 2: Search/Filter Toolbar and Category Dropdown Summary
+
+**Sticky search/filter toolbar on gear tab with text+category filtering, and shared icon-aware CategoryFilterDropdown on both gear and planning tabs**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-16T13:06:49Z
+- **Completed:** 2026-03-16T13:10:03Z
+- **Tasks:** 2
+- **Files modified:** 2
+
+## Accomplishments
+- Created CategoryFilterDropdown component with searchable dropdown, Lucide icons per option, "All categories" default, click-outside/Escape dismiss, and clear button
+- Added sticky search/filter toolbar to CollectionView with text search input and CategoryFilterDropdown side by side
+- useMemo filter chain combines text search (by name) with category filter for instant results
+- "Showing X of Y items" count appears when filters active; flat grid (no category headers) when filtering
+- Replaced PlanningView native `<select>` with shared CategoryFilterDropdown showing Lucide icons
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create CategoryFilterDropdown component** - `9e1a875` (feat)
+2. **Task 2: Add search/filter toolbar to CollectionView and replace select in PlanningView** - `5f89acd` (feat)
+
+## Files Created/Modified
+- `src/client/components/CategoryFilterDropdown.tsx` - Searchable category filter dropdown with Lucide icons, click-outside dismiss, Escape key, clear button
+- `src/client/routes/collection/index.tsx` - Search/filter toolbar in CollectionView, CategoryFilterDropdown replacing native select in PlanningView
+
+## Decisions Made
+- Kept CategoryFilterDropdown separate from CategoryPicker (filter concerns vs form/creation concerns, per user decision)
+- No debounce on search -- collection stays under 1000 items per CONTEXT.md
+- Individual clear controls for search text and category dropdown (no combined clear-all button)
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Search and filter infrastructure complete for gear tab
+- CategoryFilterDropdown available as shared component for any future filter needs
+- Planning tab upgraded from native select to icon-aware dropdown
+- Ready for remaining Phase 8 work or next phase
+
+---
+*Phase: 08-search-filter-and-candidate-status*
+*Completed: 2026-03-16*

.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md

@@ -0,0 +1,98 @@
+# Phase 8: Search, Filter, and Candidate Status - Context
+
+**Gathered:** 2026-03-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can find collection items quickly via text search and category filter, track candidate purchase progress with status badges, and use an icon-aware category dropdown on both gear and planning tabs. Side-by-side comparison, ranking, and impact preview are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Search & filter bar
+- Sticky toolbar above the item grid on the gear tab, stays visible on scroll
+- Search input + category dropdown side by side in the toolbar
+- Client-side filtering on every keystroke (no debounce needed for <1000 items)
+- Search matches item names only (not category names) — category filtering is the dropdown's job
+- When any filter is active, items display as a flat grid (no category group headers)
+- Filters reset when switching between gear/planning/setups tabs
+
+### Candidate status
+- Three statuses: researching (default), ordered, arrived
+- Status badge appears in the existing pill row alongside weight/price/category pills
+- Badge shows icon + text label (e.g., magnifying glass + "researching", truck + "ordered", check + "arrived")
+- Muted/neutral color scheme for status badges — gray tones, not semantic colors. Color reserved for weight/price pills
+- Click the status badge to open a small popup menu showing all three status options (allows jumping to any status, including backward)
+- New candidates default to "researching" status
+- Requires `status` column on `thread_candidates` table (schema migration)
+
+### Filter feedback
+- "Showing X of Y items" count displayed when filters are active — placement at Claude's discretion
+- No combined "clear all" button — user clears search text and resets category dropdown individually
+- "No items match your search" simple text message for empty filter results (no suggestions)
+
+### Icon-aware category dropdown
+- Shared `CategoryFilterDropdown` component used on both gear tab and planning tab
+- Separate from the existing `CategoryPicker` component (which is a form combobox for category selection/creation)
+- "All categories" as the first option — selecting it clears the category filter
+- Searchable dropdown — includes a search input inside the dropdown for filtering categories
+- Trigger button shows the selected category's Lucide icon + name when a category is selected
+
+### Claude's Discretion
+- Exact toolbar styling (padding, borders, background)
+- Filter result count placement (in toolbar or above grid)
+- Status popup menu implementation details
+- Specific gray tone values for status badges
+- Keyboard accessibility patterns for the dropdown and status menu
+- Icon choices for status badges (magnifying glass, truck, check are suggestions)
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `CategoryPicker` (`src/client/components/CategoryPicker.tsx`): Combobox with icon display, search, keyboard nav, and category creation. Pattern reference for the new filter dropdown, but not reusable directly since it's a form input, not a filter
+- `LucideIcon` (`src/client/lib/iconData.ts`): Dynamic icon renderer used throughout the app — reuse for dropdown icons and status badges
+- `useCategories` hook: Already fetches all categories with icons — drives the dropdown options
+- `useItems` hook: Returns all items — client-side filtering can operate on this data
+- `CollectionTabs` / `ThreadTabs`: Tab component with pill styling — existing navigation pattern
+- `CandidateCard`: Currently has weight/price/category pill row — status badge slots in here
+
+### Established Patterns
+- Client-side state for filter/tab state (`useState` in route components, not Zustand)
+- URL params for tab navigation (`?tab=gear`)
+- React Query for server data, Zustand for UI state (panels/dialogs only)
+- Pill badges: blue-50/blue-400 for weight, green-50/green-500 for price, gray-50/gray-600 for category
+
+### Integration Points
+- `CollectionView` function in `src/client/routes/collection/index.tsx`: Search/filter toolbar goes here, above the category-grouped items
+- `PlanningView` function: Replace existing `<select>` category filter with shared `CategoryFilterDropdown`
+- `CandidateCard`: Add status prop and badge to the pill row
+- `thread_candidates` table in `src/db/schema.ts`: Add `status` column with default "researching"
+- Candidate API routes + services: Need to handle status field in CRUD operations
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — open to standard approaches
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 08-search-filter-and-candidate-status*
+*Context gathered: 2026-03-16*

.planning/phases/08-search-filter-and-candidate-status/08-RESEARCH.md

@@ -0,0 +1,491 @@
+# Phase 8: Search, Filter, and Candidate Status - Research
+
+**Researched:** 2026-03-16
+**Domain:** Client-side filtering, searchable dropdown components, schema migration, status badges
+**Confidence:** HIGH
+
+## Summary
+
+Phase 8 adds three capabilities to GearBox: (1) a search and category filter toolbar on the gear tab with result counts, (2) an icon-aware searchable category filter dropdown shared between gear and planning tabs, and (3) candidate status tracking (researching/ordered/arrived) with clickable status badges. The work spans all layers: schema migration (adding `status` column to `thread_candidates`), service/route updates (CRUD for status field), Zod schema updates, and several new client components.
+
+The codebase is well-structured for these additions. Client-side filtering is straightforward since `useItems()` already returns all items with category info. The `CategoryPicker` component provides a reference pattern for the searchable dropdown, though the new `CategoryFilterDropdown` is simpler (no creation flow). The candidate status feature requires a schema migration, but Drizzle Kit and the existing migration infrastructure handle this cleanly.
+
+**Primary recommendation:** Build in two waves -- (1) backend schema migration + candidate status (smaller, foundational), then (2) search/filter toolbar and shared category dropdown (larger, UI-focused). Both waves are pure client-side filtering with minimal server changes.
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- Sticky toolbar above the item grid on the gear tab, stays visible on scroll
+- Search input + category dropdown side by side in the toolbar
+- Client-side filtering on every keystroke (no debounce needed for <1000 items)
+- Search matches item names only (not category names) -- category filtering is the dropdown's job
+- When any filter is active, items display as a flat grid (no category group headers)
+- Filters reset when switching between gear/planning/setups tabs
+- Three statuses: researching (default), ordered, arrived
+- Status badge appears in the existing pill row alongside weight/price/category pills
+- Badge shows icon + text label (e.g., magnifying glass + "researching", truck + "ordered", check + "arrived")
+- Muted/neutral color scheme for status badges -- gray tones, not semantic colors
+- Click the status badge to open a small popup menu showing all three status options
+- New candidates default to "researching" status
+- Requires `status` column on `thread_candidates` table (schema migration)
+- "Showing X of Y items" count displayed when filters are active
+- No combined "clear all" button -- user clears search text and resets category dropdown individually
+- "No items match your search" simple text message for empty filter results
+- Shared `CategoryFilterDropdown` component used on both gear tab and planning tab
+- Separate from existing `CategoryPicker` component
+- "All categories" as the first option -- selecting it clears the category filter
+- Searchable dropdown with search input inside
+- Trigger button shows selected category's Lucide icon + name when selected
+
+### Claude's Discretion
+- Exact toolbar styling (padding, borders, background)
+- Filter result count placement (in toolbar or above grid)
+- Status popup menu implementation details
+- Specific gray tone values for status badges
+- Keyboard accessibility patterns for the dropdown and status menu
+- Icon choices for status badges (magnifying glass, truck, check are suggestions)
+
+### Deferred Ideas (OUT OF SCOPE)
+None
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| SRCH-01 | User can search items by name with instant filtering as they type | Client-side `useState` + `.filter()` on `useItems()` data. Pattern documented in Architecture section |
+| SRCH-02 | User can filter collection items by category via dropdown | New `CategoryFilterDropdown` component using `useCategories()` data. Pattern from existing `CategoryPicker` |
+| SRCH-03 | User can combine text search with category filter simultaneously | Chain `.filter()` calls -- search text AND category ID. Both stored as `useState` in `CollectionView` |
+| SRCH-04 | User can see result count when filters are active | Computed from `filteredItems.length` vs `items.length`. Conditional rendering when filters active |
+| SRCH-05 | User can clear all active filters with one action | Per CONTEXT.md: no combined button. User clears search text and resets dropdown individually. Both inputs have clear affordances |
+| PLAN-01 | Planning category filter dropdown shows Lucide icons alongside names | Replace existing `<select>` in `PlanningView` with shared `CategoryFilterDropdown` |
+| CAND-01 | Each candidate displays a status badge (researching, ordered, or arrived) | Add `status` prop to `CandidateCard`, render as pill in existing flex row |
+| CAND-02 | User can change a candidate's status via click interaction | Status badge click opens popup menu. Uses `useUpdateCandidate` mutation with `status` field |
+| CAND-03 | New candidates default to "researching" status | Schema default + Drizzle `.default("researching")`. Service layer already handles defaults via `?? null` pattern |
+</phase_requirements>
+
+## Standard Stack
+
+### Core (Already in Project)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| React | 19 | UI framework | Already installed, all components use it |
+| TanStack React Query | - | Server state | Already used for `useItems`, `useCategories`, `useThreads` |
+| Zustand | - | UI state (panels/dialogs only) | Already used in `uiStore.ts` |
+| Drizzle ORM | - | Database schema + queries | Already used for all DB operations |
+| Drizzle Kit | - | Schema migration generation | Already configured in `drizzle.config.ts` |
+| Zod | - | Request validation | Already used in `schemas.ts` and route validators |
+| Hono | - | Server framework | Already used for all API routes |
+| lucide-react | - | Icons | Already used via `LucideIcon` component for all icons |
+| Tailwind CSS | v4 | Styling | Already used throughout |
+
+### No New Dependencies Required
+
+This phase uses only existing libraries. No new packages needed.
+
+## Architecture Patterns
+
+### Recommended Project Structure (Changes Only)
+```
+src/
+  client/
+    components/
+      CategoryFilterDropdown.tsx    # NEW - shared searchable category filter
+      StatusBadge.tsx               # NEW - clickable status badge with popup menu
+      CandidateCard.tsx             # MODIFIED - add status prop and badge
+    routes/
+      collection/
+        index.tsx                   # MODIFIED - add search/filter toolbar to CollectionView
+                                    #           - replace <select> in PlanningView
+  server/
+    services/
+      thread.service.ts             # MODIFIED - handle status field in create/update candidate
+    routes/
+      threads.ts                    # NO CHANGES - already delegates to service
+  shared/
+    schemas.ts                      # MODIFIED - add status to candidate schemas
+    types.ts                        # NO CHANGES - types auto-infer from schemas
+  db/
+    schema.ts                       # MODIFIED - add status column to threadCandidates
+tests/
+  helpers/
+    db.ts                           # MODIFIED - add status column to thread_candidates CREATE TABLE
+  services/
+    thread.service.test.ts          # MODIFIED - add tests for status field
+```
+
+### Pattern 1: Client-Side Filtering with useState
+**What:** Filter items in-memory using React state, no server round-trips
+**When to use:** Small datasets (<1000 items), instant feedback needed
+**Example:**
+```typescript
+// In CollectionView
+function CollectionView() {
+  const [searchText, setSearchText] = useState("");
+  const [categoryFilter, setCategoryFilter] = useState<number | null>(null);
+  const { data: items } = useItems();
+
+  const filteredItems = useMemo(() => {
+    if (!items) return [];
+    return items.filter((item) => {
+      const matchesSearch = searchText === "" ||
+        item.name.toLowerCase().includes(searchText.toLowerCase());
+      const matchesCategory = categoryFilter === null ||
+        item.categoryId === categoryFilter;
+      return matchesSearch && matchesCategory;
+    });
+  }, [items, searchText, categoryFilter]);
+
+  const hasActiveFilters = searchText !== "" || categoryFilter !== null;
+  // ...
+}
+```
+
+### Pattern 2: Searchable Dropdown with Click-Outside Dismiss
+**What:** Dropdown with internal search input, opens on click, closes on click-outside or Escape
+**When to use:** Category filter dropdowns where a native `<select>` is insufficient (need icons, search)
+**Example:**
+```typescript
+// Reference: existing CategoryPicker pattern (containerRef + useEffect for mousedown)
+function CategoryFilterDropdown({ value, onChange, categories }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+        setSearch("");
+      }
+    }
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+  // ... trigger button + dropdown list with LucideIcon per option
+}
+```
+
+### Pattern 3: Status Badge with Popup Menu
+**What:** Clickable pill badge that opens a small menu to change status
+**When to use:** Inline status changes without opening a modal/panel
+**Example:**
+```typescript
+// StatusBadge - renders in CandidateCard's pill row
+function StatusBadge({ status, onStatusChange }: {
+  status: "researching" | "ordered" | "arrived";
+  onStatusChange: (status: string) => void;
+}) {
+  const [menuOpen, setMenuOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Click-outside dismiss pattern (same as CategoryPicker)
+  // Renders: pill button + absolute-positioned menu with 3 options
+}
+```
+
+### Pattern 4: Schema Migration with Default Value
+**What:** Add column with default to existing table using Drizzle Kit
+**When to use:** Adding new fields that need backward compatibility with existing rows
+**Example:**
+```typescript
+// In src/db/schema.ts -- add to threadCandidates table definition:
+status: text("status").notNull().default("researching"),
+
+// Then run: bun run db:generate && bun run db:push
+// Drizzle Kit will generate: ALTER TABLE thread_candidates ADD COLUMN status TEXT NOT NULL DEFAULT 'researching'
+```
+
+### Pattern 5: Flat Grid vs Category-Grouped Grid
+**What:** Conditionally render items as flat grid or category-grouped sections
+**When to use:** When filters are active, category grouping loses meaning
+**Example:**
+```typescript
+// When filters active: flat grid of filteredItems
+// When no filters: existing category-grouped Map pattern (already in CollectionView)
+const hasActiveFilters = searchText !== "" || categoryFilter !== null;
+
+return hasActiveFilters ? (
+  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {filteredItems.map((item) => <ItemCard key={item.id} ... />)}
+  </div>
+) : (
+  // Existing grouped rendering with CategoryHeader
+  <>
+    {Array.from(groupedItems.entries()).map(([categoryId, { items, ... }]) => (
+      // ... existing CategoryHeader + grid pattern
+    ))}
+  </>
+);
+```
+
+### Anti-Patterns to Avoid
+- **Server-side filtering for this use case:** Out of scope per REQUIREMENTS.md ("Premature for single-user app with <1000 items"). All filtering is client-side.
+- **Zustand for filter state:** Per codebase convention, filter/tab state uses `useState` in route components, not Zustand. Zustand is only for panel/dialog state.
+- **Debouncing search input:** Per CONTEXT.md, no debounce needed for <1000 items. React is fast enough for synchronous filtering.
+- **Modifying CategoryPicker:** The new dropdown is separate from `CategoryPicker`. CategoryPicker is a form combobox for category selection/creation. Do not conflate them.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Click-outside detection | Custom event system | `useEffect` + `mousedown` listener on `document` (existing pattern from `CategoryPicker`) | Pattern already proven in codebase, handles edge cases |
+| Dynamic icon rendering | SVG string lookup | `LucideIcon` component from `src/client/lib/iconData.tsx` | Already handles kebab-case to PascalCase conversion, fallback to Package icon |
+| Schema migrations | Manual SQL | `bun run db:generate` + `bun run db:push` (Drizzle Kit) | Generates correct ALTER TABLE, manages migration journal |
+| Popup menu positioning | Complex position calculation | CSS `position: absolute` + `right-0` on container with `position: relative` | Simple case -- badge is in a flex row, menu drops below. No viewport collision for this layout |
+
+## Common Pitfalls
+
+### Pitfall 1: Forgetting to Update Test Helper DB Schema
+**What goes wrong:** Adding `status` column to `src/db/schema.ts` but not to `tests/helpers/db.ts` CREATE TABLE statement causes all thread service tests to fail.
+**Why it happens:** The test helper creates in-memory SQLite tables manually, not via Drizzle migrations.
+**How to avoid:** Always update both `src/db/schema.ts` AND `tests/helpers/db.ts` thread_candidates CREATE TABLE in the same commit.
+**Warning signs:** Tests that worked before now fail with "table thread_candidates has no column named status".
+
+### Pitfall 2: Filter State Not Resetting on Tab Switch
+**What goes wrong:** User searches on gear tab, switches to planning, comes back -- old search text still showing stale filtered results.
+**Why it happens:** useState persists while the component is mounted. Tab switching in `CollectionPage` conditionally renders views but `CollectionView` may stay mounted if React reuses the component.
+**How to avoid:** Use a `key` prop tied to the tab value on the view components, or explicitly reset filter state in a `useEffect` keyed on tab changes. The simplest approach: since `CollectionView` is conditionally rendered (unmounted when tab !== "gear"), useState will naturally reset. Verify this is the case.
+**Warning signs:** Filters persisting when switching tabs.
+
+### Pitfall 3: Status Badge Click Propagating to Card Actions
+**What goes wrong:** Clicking the status badge also triggers the card's edit panel or other click handlers.
+**Why it happens:** Event bubbling -- `CandidateCard` has click handlers on parent elements.
+**How to avoid:** Call `e.stopPropagation()` on the status badge click handler. The existing code already does this for the external link button.
+**Warning signs:** Clicking status badge opens the edit panel instead of the status menu.
+
+### Pitfall 4: Candidate Status Not Included in API Responses
+**What goes wrong:** Status column is added to schema but `getThreadWithCandidates` doesn't select it, so frontend never receives it.
+**Why it happens:** The service uses explicit `select()` clauses, not `select(*)`. New columns must be explicitly added.
+**How to avoid:** Add `status: threadCandidates.status` to the select object in `getThreadWithCandidates`.
+**Warning signs:** Status badge always shows "researching" even after changing it.
+
+### Pitfall 5: Zod Schema Missing Status in updateCandidateSchema
+**What goes wrong:** PUT request to update candidate status gets rejected by Zod validation.
+**Why it happens:** `updateCandidateSchema = createCandidateSchema.partial()` -- if `createCandidateSchema` doesn't include status, neither does update.
+**How to avoid:** Add `status` to `updateCandidateSchema` (and optionally `createCandidateSchema`). Use `z.enum(["researching", "ordered", "arrived"])`.
+**Warning signs:** 400 errors when trying to change status via the badge.
+
+### Pitfall 6: Sticky Toolbar Covering Content
+**What goes wrong:** The sticky search/filter toolbar overlaps the first row of items when scrolled.
+**Why it happens:** `position: sticky` without adequate spacing pushes content under the toolbar.
+**How to avoid:** Ensure the grid content below the toolbar has no negative margin or overlapping. The toolbar sits in normal flow and sticks on scroll -- padding/margin on the toolbar itself handles spacing.
+**Warning signs:** First item card partially hidden behind the toolbar when scrolling.
+
+## Code Examples
+
+### Schema Migration: Add Status Column
+```typescript
+// src/db/schema.ts -- threadCandidates table
+export const threadCandidates = sqliteTable("thread_candidates", {
+  // ... existing columns ...
+  status: text("status").notNull().default("researching"),
+});
+```
+
+### Zod Schema Update
+```typescript
+// src/shared/schemas.ts
+export const candidateStatusSchema = z.enum(["researching", "ordered", "arrived"]);
+
+export const createCandidateSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  weightGrams: z.number().nonnegative().optional(),
+  priceCents: z.number().int().nonnegative().optional(),
+  categoryId: z.number().int().positive(),
+  notes: z.string().optional(),
+  productUrl: z.string().url().optional().or(z.literal("")),
+  imageFilename: z.string().optional(),
+  status: candidateStatusSchema.optional(), // optional on create, defaults to "researching"
+});
+
+export const updateCandidateSchema = createCandidateSchema.partial();
+// This automatically includes status as optional
+```
+
+### Service Update: Status in getThreadWithCandidates
+```typescript
+// src/server/services/thread.service.ts -- in getThreadWithCandidates
+const candidateList = db
+  .select({
+    id: threadCandidates.id,
+    threadId: threadCandidates.threadId,
+    name: threadCandidates.name,
+    weightGrams: threadCandidates.weightGrams,
+    priceCents: threadCandidates.priceCents,
+    categoryId: threadCandidates.categoryId,
+    notes: threadCandidates.notes,
+    productUrl: threadCandidates.productUrl,
+    imageFilename: threadCandidates.imageFilename,
+    status: threadCandidates.status,  // ADD THIS
+    createdAt: threadCandidates.createdAt,
+    updatedAt: threadCandidates.updatedAt,
+    categoryName: categories.name,
+    categoryIcon: categories.icon,
+  })
+  .from(threadCandidates)
+  .innerJoin(categories, eq(threadCandidates.categoryId, categories.id))
+  .where(eq(threadCandidates.threadId, threadId))
+  .all();
+```
+
+### Test Helper Update
+```sql
+-- tests/helpers/db.ts -- thread_candidates CREATE TABLE
+CREATE TABLE thread_candidates (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  thread_id INTEGER NOT NULL REFERENCES threads(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  weight_grams REAL,
+  price_cents INTEGER,
+  category_id INTEGER NOT NULL REFERENCES categories(id),
+  notes TEXT,
+  product_url TEXT,
+  image_filename TEXT,
+  status TEXT NOT NULL DEFAULT 'researching',
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+```
+
+### Client Hook Update: CandidateWithCategory Type
+```typescript
+// src/client/hooks/useThreads.ts -- add status to CandidateWithCategory
+interface CandidateWithCategory {
+  id: number;
+  threadId: number;
+  name: string;
+  weightGrams: number | null;
+  priceCents: number | null;
+  categoryId: number;
+  notes: string | null;
+  productUrl: string | null;
+  imageFilename: string | null;
+  status: "researching" | "ordered" | "arrived";  // ADD THIS
+  createdAt: string;
+  updatedAt: string;
+  categoryName: string;
+  categoryIcon: string;
+}
+```
+
+### Lucide Icon Names for Status Badges
+```typescript
+// Available in lucide-react (verified via iconData.tsx icon groups)
+const STATUS_CONFIG = {
+  researching: { icon: "search", label: "Researching" },
+  ordered: { icon: "truck", label: "Ordered" },
+  arrived: { icon: "check", label: "Arrived" },
+} as const;
+// Note: "search" maps to lucide's Search icon (magnifying glass)
+// "truck" maps to Truck icon
+// "check" maps to Check icon
+// All are valid lucide-react icon names and work with the LucideIcon component
+```
+
+### Sticky Toolbar Pattern
+```typescript
+// Toolbar sticks to top on scroll
+<div className="sticky top-0 z-10 bg-white/95 backdrop-blur-sm border-b border-gray-100 -mx-4 px-4 py-3 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8">
+  <div className="flex gap-3 items-center">
+    <input
+      type="text"
+      placeholder="Search items..."
+      value={searchText}
+      onChange={(e) => setSearchText(e.target.value)}
+      className="flex-1 px-3 py-2 border border-gray-200 rounded-lg text-sm ..."
+    />
+    <CategoryFilterDropdown
+      value={categoryFilter}
+      onChange={setCategoryFilter}
+    />
+  </div>
+</div>
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Native `<select>` for category filter | Searchable dropdown with icons | This phase | Planning view's `<select>` replaced with `CategoryFilterDropdown` |
+| No candidate status tracking | `status` column with badge UI | This phase | Candidates now track purchase progress |
+| Category-grouped items only | Conditional flat grid when filtering | This phase | Better UX when searching/filtering |
+
+## Open Questions
+
+1. **Sticky toolbar `top` offset**
+   - What we know: The toolbar should be `sticky top-0` but needs to account for any fixed header/navbar if one exists.
+   - What's unclear: Whether there's a fixed navbar above the collection page that would require a `top-[Npx]` offset instead of `top-0`.
+   - Recommendation: Start with `top-0`. If there's a fixed navbar, adjust the top value to match its height. The current layout appears to not have a fixed navbar based on the route structure.
+
+2. **useCandidates hook status mutation**
+   - What we know: `useUpdateCandidate` already exists and can be used for status changes via `apiPut`.
+   - What's unclear: Whether a dedicated `useUpdateCandidateStatus` hook is cleaner than reusing the general `useUpdateCandidate`.
+   - Recommendation: Reuse `useUpdateCandidate` -- it already accepts partial updates. Adding a dedicated hook would be unnecessary abstraction.
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test runner (built-in) |
+| Config file | None (uses bun defaults) |
+| Quick run command | `bun test tests/services/thread.service.test.ts` |
+| Full suite command | `bun test` |
+
+### Phase Requirements to Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| SRCH-01 | Search items by name with instant filtering | manual-only | N/A -- client-side `useState` + `filter()`, no testable service | N/A |
+| SRCH-02 | Filter by category via dropdown | manual-only | N/A -- client-side component logic | N/A |
+| SRCH-03 | Combine text search with category filter | manual-only | N/A -- client-side filtering logic | N/A |
+| SRCH-04 | Show result count when filters active | manual-only | N/A -- computed in render | N/A |
+| SRCH-05 | Clear filters individually | manual-only | N/A -- UI interaction | N/A |
+| PLAN-01 | Category dropdown shows icons | manual-only | N/A -- component rendering | N/A |
+| CAND-01 | Candidate displays status badge | unit | `bun test tests/services/thread.service.test.ts` | Needs update |
+| CAND-02 | User can change candidate status | unit | `bun test tests/services/thread.service.test.ts` | Needs update |
+| CAND-03 | New candidates default to "researching" | unit | `bun test tests/services/thread.service.test.ts` | Needs update |
+
+### Sampling Rate
+- **Per task commit:** `bun test tests/services/thread.service.test.ts`
+- **Per wave merge:** `bun test`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] `tests/helpers/db.ts` -- add `status TEXT NOT NULL DEFAULT 'researching'` to thread_candidates CREATE TABLE
+- [ ] `tests/services/thread.service.test.ts` -- add tests for: (1) createCandidate returns status "researching" by default, (2) updateCandidate can change status, (3) getThreadWithCandidates includes status field
+
+## Sources
+
+### Primary (HIGH confidence)
+- **Codebase analysis** -- direct reading of all relevant source files:
+  - `src/db/schema.ts` -- current threadCandidates table definition (no status column)
+  - `src/client/routes/collection/index.tsx` -- CollectionView (where toolbar goes) and PlanningView (where `<select>` is replaced)
+  - `src/client/components/CandidateCard.tsx` -- current pill row layout (where status badge goes)
+  - `src/client/components/CategoryPicker.tsx` -- searchable dropdown reference pattern
+  - `src/client/lib/iconData.tsx` -- LucideIcon component and available icon names
+  - `src/server/services/thread.service.ts` -- candidate CRUD with explicit select fields
+  - `src/shared/schemas.ts` -- Zod validation schemas for candidates
+  - `src/client/hooks/useThreads.ts` -- CandidateWithCategory interface
+  - `src/client/hooks/useCandidates.ts` -- mutation hooks for candidates
+  - `tests/helpers/db.ts` -- test helper CREATE TABLE statements
+  - `drizzle.config.ts` -- migration config
+  - `drizzle/0001_rename_emoji_to_icon.sql` -- migration precedent
+
+### Secondary (MEDIUM confidence)
+- **Drizzle ORM** -- ALTER TABLE ADD COLUMN with DEFAULT for SQLite is well-documented and standard
+
+### Tertiary (LOW confidence)
+- None -- all findings are from direct codebase analysis
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH -- no new libraries, all existing
+- Architecture: HIGH -- patterns derived from existing codebase conventions
+- Pitfalls: HIGH -- identified from actual code reading (explicit selects, test helper, event bubbling)
+- Schema migration: HIGH -- follows existing migration pattern (drizzle/0001_rename_emoji_to_icon.sql)
+
+**Research date:** 2026-03-16
+**Valid until:** 2026-04-16 (stable -- internal codebase patterns, no external dependency concerns)

.planning/phases/08-search-filter-and-candidate-status/08-VALIDATION.md

@@ -0,0 +1,82 @@
+---
+phase: 8
+slug: search-filter-and-candidate-status
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-16
+---
+
+# Phase 8 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | bun test |
+| **Config file** | bunfig.toml (if exists) or none |
+| **Quick run command** | `bun test` |
+| **Full suite command** | `bun test` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun test`
+- **After every plan wave:** Run `bun test`
+- **Before `/gsd:verify-work`:** Full suite must be green
+- **Max feedback latency:** 5 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 08-01-01 | 01 | 1 | CAND-01, CAND-03 | unit | `bun test tests/services/thread.service.test.ts` | ❌ W0 | ⬜ pending |
+| 08-01-02 | 01 | 1 | CAND-02 | unit | `bun test tests/services/thread.service.test.ts` | ❌ W0 | ⬜ pending |
+| 08-02-01 | 02 | 1 | SRCH-01, SRCH-02, SRCH-03 | manual | visual | N/A | ⬜ pending |
+| 08-02-02 | 02 | 1 | SRCH-04, SRCH-05 | manual | visual | N/A | ⬜ pending |
+| 08-02-03 | 02 | 1 | PLAN-01 | manual | visual | N/A | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `tests/services/thread.service.test.ts` — add candidate status tests (schema migration, default status, status update)
+- [ ] `tests/helpers/db.ts` — update CREATE TABLE for thread_candidates to include status column
+
+*Existing test infrastructure covers framework setup.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Instant search filtering as user types | SRCH-01 | Client-side UI interaction | Type in search field, verify items filter in real time |
+| Category dropdown with Lucide icons | SRCH-02, PLAN-01 | Visual rendering of icons in dropdown | Open dropdown, verify icons appear next to category names |
+| Combined search + category filter | SRCH-03 | Multi-input UI interaction | Apply both search and category filter, verify combined results |
+| Result count display | SRCH-04 | UI text rendering | Apply filter, verify "showing X of Y items" appears |
+| Clear filters individually | SRCH-05 | UI interaction | Clear search, reset dropdown, verify all items return |
+| Status badge display and click menu | CAND-01, CAND-02 | UI interaction + popup menu | Click status badge, verify menu appears with all 3 options |
+
+---
+
+## 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 < 5s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/08-search-filter-and-candidate-status/08-VERIFICATION.md

@@ -0,0 +1,143 @@
+---
+phase: 08-search-filter-and-candidate-status
+verified: 2026-03-16T13:30:00Z
+status: passed
+score: 11/11 must-haves verified
+re_verification: false
+gaps: []
+human_verification:
+  - test: "Visually confirm StatusBadge popup menu appears and dismisses correctly"
+    expected: "Clicking badge opens popup below it; clicking outside or pressing Escape closes it without changing status"
+    why_human: "Cannot verify popup positioning and dismiss behavior without a browser"
+  - test: "Visually confirm sticky toolbar stays fixed on scroll with items below"
+    expected: "Search input and CategoryFilterDropdown remain visible at top as user scrolls through a long item list"
+    why_human: "CSS sticky positioning behavior cannot be verified statically"
+  - test: "Confirm filters reset when switching tabs"
+    expected: "Navigating from gear tab to planning tab and back shows unfiltered items with empty search and 'All categories'"
+    why_human: "Route unmount/remount behavior requires browser interaction to confirm"
+---
+
+# Phase 8: Search, Filter, and Candidate Status Verification Report
+
+**Phase Goal:** Users can find items quickly and track candidate purchase progress
+**Verified:** 2026-03-16T13:30:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|---------|
+| 1 | Each candidate displays a status badge showing one of three statuses: researching, ordered, or arrived | VERIFIED | `StatusBadge.tsx` renders pill with `STATUS_CONFIG` map; `CandidateCard.tsx` line 114 renders `<StatusBadge status={status} .../>` |
+| 2 | User can click a status badge to open a popup menu and change the candidate's status to any of the three options | VERIFIED | `StatusBadge.tsx`: click handler calls `setIsOpen`, popup renders all 3 options, each calls `onStatusChange(key)` and closes |
+| 3 | New candidates automatically have status 'researching' without the user needing to set it | VERIFIED | `schema.ts` line 61: `.default("researching")`; `thread.service.ts` line 153: `status: data.status ?? "researching"` |
+| 4 | User can type in a search field on the gear tab and see items filtered instantly by name as they type | VERIFIED | `collection/index.tsx` lines 58-73: `useState searchText`, `useMemo filteredItems` filters by `item.name.toLowerCase().includes(...)` on every change |
+| 5 | User can select a category from a searchable dropdown (with Lucide icons) to filter items on both gear and planning tabs | VERIFIED | `CategoryFilterDropdown.tsx` renders `LucideIcon` per option; used in both `CollectionView` (line 205) and `PlanningView` (line 373) |
+| 6 | User can combine text search with category filter to narrow results | VERIFIED | `useMemo filteredItems` (lines 61-71): both `matchesSearch` AND `matchesCategory` must be true |
+| 7 | User sees 'Showing X of Y items' when filters are active on the gear tab | VERIFIED | `collection/index.tsx` lines 211-215: `{hasActiveFilters && <p>Showing {filteredItems.length} of {items.length} items</p>}` |
+| 8 | User can clear search text and reset category filter individually | VERIFIED | Search: clear button at line 184 calls `setSearchText("")`; Category: `x` button in `CategoryFilterDropdown.tsx` line 91 calls `onChange(null)` |
+| 9 | When filters are active, items display as a flat grid without category group headers | VERIFIED | Lines 219-278: `hasActiveFilters` branches to flat `<div className="grid ...">` rendering `filteredItems` directly, bypassing `groupedItems` Map |
+| 10 | Empty filter results show 'No items match your search' message | VERIFIED | Lines 220-226: `filteredItems.length === 0` shows `<p>No items match your search</p>` |
+| 11 | Planning tab category filter shows Lucide icons alongside category names | VERIFIED | `PlanningView` at line 373 uses `<CategoryFilterDropdown>` which renders `LucideIcon` per category option |
+
+**Score:** 11/11 truths verified
+
+### Required Artifacts
+
+#### Plan 01 Artifacts (CAND-01, CAND-02, CAND-03)
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/db/schema.ts` | status column on threadCandidates table | VERIFIED | Line 61: `status: text("status").notNull().default("researching")` — exact match |
+| `src/shared/schemas.ts` | candidateStatusSchema Zod enum | VERIFIED | Lines 40-44: `export const candidateStatusSchema = z.enum(["researching", "ordered", "arrived"])` |
+| `src/server/services/thread.service.ts` | status field in candidate CRUD | VERIFIED | `getThreadWithCandidates` selects `status`, `createCandidate` sets `status`, `updateCandidate` accepts `status` in type |
+| `src/client/components/StatusBadge.tsx` | Clickable status badge with popup menu | VERIFIED | 103 lines, full implementation with `STATUS_CONFIG`, popup menu, click-outside/Escape dismiss |
+| `src/client/components/CandidateCard.tsx` | Renders StatusBadge in pill row | VERIFIED | Line 5: imports `StatusBadge`; line 114: `<StatusBadge status={status} onStatusChange={onStatusChange} />` |
+| `tests/helpers/db.ts` | status column in CREATE TABLE | VERIFIED | Line 57: `status TEXT NOT NULL DEFAULT 'researching'` — exact match |
+
+#### Plan 02 Artifacts (SRCH-01 through SRCH-05, PLAN-01)
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/client/components/CategoryFilterDropdown.tsx` | Searchable category filter dropdown with Lucide icons | VERIFIED | 198 lines, full implementation with search input, Lucide icons per option, click-outside/Escape dismiss, clear button, "All categories" option |
+| `src/client/routes/collection/index.tsx` | Search/filter toolbar in CollectionView; CategoryFilterDropdown in PlanningView | VERIFIED | Lines 173-216: sticky toolbar with search + `<CategoryFilterDropdown>`; lines 372-377: `<CategoryFilterDropdown>` in PlanningView |
+
+### Key Link Verification
+
+#### Plan 01 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `StatusBadge.tsx` | `/api/threads/:id/candidates/:candidateId` | `useUpdateCandidate` mutation in `onStatusChange` prop | VERIFIED | `$threadId.tsx` lines 150-154: `onStatusChange={(newStatus) => updateCandidate.mutate({candidateId, status: newStatus})}` |
+| `thread.service.ts` | `src/db/schema.ts` | `threadCandidates.status` in select and update | VERIFIED | `getThreadWithCandidates` selects `status: threadCandidates.status`; `updateCandidate` spreads `...data` which includes status |
+| `CandidateCard.tsx` | `StatusBadge.tsx` | `<StatusBadge` in pill row | VERIFIED | Line 114: `<StatusBadge status={status} onStatusChange={onStatusChange} />` |
+
+#### Plan 02 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `CategoryFilterDropdown.tsx` | `useCategories` data | `categories` prop passed from parent | VERIFIED | Both `CollectionView` (line 208) and `PlanningView` (line 376) pass `categories={categories ?? []}` from `useCategories()` hook |
+| `CollectionView` in `collection/index.tsx` | `CategoryFilterDropdown.tsx` | `<CategoryFilterDropdown` in sticky toolbar | VERIFIED | Line 205: `<CategoryFilterDropdown value={categoryFilter} onChange={setCategoryFilter} categories={categories ?? []} />` |
+| `PlanningView` in `collection/index.tsx` | `CategoryFilterDropdown.tsx` | `<CategoryFilterDropdown` replacing native select | VERIFIED | Line 373: `<CategoryFilterDropdown value={categoryFilter} onChange={setCategoryFilter} categories={categories ?? []} />` |
+| `CollectionView` in `collection/index.tsx` | `useItems` data | `useMemo` filter chain on `searchText + categoryFilter` | VERIFIED | Lines 61-73: `const filteredItems = useMemo(...)` and `const hasActiveFilters = ...` correctly wired |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|------------|-------------|--------|---------|
+| SRCH-01 | 08-02-PLAN.md | User can search items by name with instant filtering | SATISFIED | `collection/index.tsx` `useMemo filteredItems` filters on every `searchText` change |
+| SRCH-02 | 08-02-PLAN.md | User can filter collection items by category via dropdown | SATISFIED | `CategoryFilterDropdown` used in `CollectionView` with `categoryFilter` state |
+| SRCH-03 | 08-02-PLAN.md | User can combine text search with category filter simultaneously | SATISFIED | Both `matchesSearch && matchesCategory` conditions in single `useMemo` |
+| SRCH-04 | 08-02-PLAN.md | User can see result count when filters are active | SATISFIED | "Showing X of Y items" renders when `hasActiveFilters` is true |
+| SRCH-05 | 08-02-PLAN.md | User can clear active filters | SATISFIED | Design decision (per CONTEXT.md) intentionally implemented as individual clear controls: search input `x` button + dropdown `x` button. Each filter is individually clearable. REQUIREMENTS.md marks this [x] complete. |
+| PLAN-01 | 08-02-PLAN.md | Planning category filter dropdown shows Lucide icons alongside category names | SATISFIED | `PlanningView` uses `CategoryFilterDropdown` which renders `LucideIcon` per category |
+| CAND-01 | 08-01-PLAN.md | Each candidate displays a status badge (researching, ordered, or arrived) | SATISFIED | `StatusBadge` rendered in `CandidateCard` pill row at line 114 |
+| CAND-02 | 08-01-PLAN.md | User can change a candidate's status via click interaction | SATISFIED | `StatusBadge` click opens popup, selecting option calls `onStatusChange`, fires `updateCandidate.mutate` |
+| CAND-03 | 08-01-PLAN.md | New candidates default to "researching" status | SATISFIED | Schema default + service fallback both enforce "researching" |
+
+All 9 requirements covered. No orphaned requirements.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| `src/client/routes/collection/index.tsx` | 222-224 | Biome formatter disagreement (JSX whitespace in `<p>` tag) | Info | Formatter-only issue, no logic impact. Not a code defect. |
+| `.planning/config.json` | all | Biome formatter expects tabs | Info | Planning config, no source code impact |
+| `drizzle/meta/0002_snapshot.json` | all | Biome formatter expects tabs | Info | Generated drizzle file, no source code impact |
+
+No blockers. No logic anti-patterns in source files. All stub detection checks pass — no `return null`, `return {}`, `return []`, console-only implementations, or placeholder comments found in any phase artifact.
+
+### Human Verification Required
+
+#### 1. StatusBadge Popup Behavior
+
+**Test:** Navigate to a thread detail page, click the "Researching" badge on any candidate
+**Expected:** Popup menu appears below the badge showing three options (Researching with search icon, Ordered with truck icon, Arrived with check icon). Currently active status is highlighted. Clicking outside or pressing Escape closes without changes.
+**Why human:** Popup positioning, z-index rendering, and dismiss behavior require browser interaction
+
+#### 2. Sticky Toolbar on Scroll
+
+**Test:** On the gear tab with 10+ items, scroll down the page
+**Expected:** The search input and category dropdown remain fixed at the top of the viewport while items scroll beneath
+**Why human:** CSS `sticky` positioning behavior with `backdrop-blur-sm` requires visual confirmation
+
+#### 3. Filter Reset on Tab Switch
+
+**Test:** Enter search text "tent", select a category, then switch to the Planning tab, then switch back to Gear
+**Expected:** On return to Gear tab, search field is empty and "All categories" is shown (no filter active)
+**Why human:** Requires verifying React component unmount/remount behavior through actual navigation
+
+### Gaps Summary
+
+No gaps. All 11 observable truths are verified. All 8 artifacts exist with substantive implementations. All 7 key links are confirmed wired. All 9 requirements are satisfied. 24 tests pass including 5 new candidate status tests. 113 total tests pass across the full suite.
+
+The only open items are 3 human verification checks for visual/behavioral aspects that cannot be confirmed statically — these are normal for a UI phase and do not indicate missing functionality.
+
+**Note on SRCH-05:** The requirement states "clear all active filters with one action." The implementation provides individual clear controls (search `x` button and dropdown `x` button) per explicit design decision documented in `08-CONTEXT.md`. The REQUIREMENTS.md marks SRCH-05 as [x] complete. This is an intentional scoping decision made during context capture, not a missed requirement.
+
+---
+
+_Verified: 2026-03-16T13:30:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/09-weight-classification-and-visualization/09-01-PLAN.md

@@ -0,0 +1,360 @@
+---
+phase: 09-weight-classification-and-visualization
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/db/schema.ts
+  - src/shared/schemas.ts
+  - src/shared/types.ts
+  - src/server/services/setup.service.ts
+  - src/server/routes/setups.ts
+  - src/client/lib/api.ts
+  - src/client/hooks/useSetups.ts
+  - src/client/components/ClassificationBadge.tsx
+  - src/client/routes/setups/$setupId.tsx
+  - tests/helpers/db.ts
+  - tests/services/setup.service.test.ts
+  - tests/routes/setups.test.ts
+autonomous: true
+requirements: [CLAS-01, CLAS-03, CLAS-04]
+
+must_haves:
+  truths:
+    - "User can click a classification badge on any item card within a setup and it cycles through base weight, worn, consumable"
+    - "Items default to base weight classification when added to a setup"
+    - "Same item in different setups can have different classifications"
+    - "Classifications persist after adding/removing other items from the setup (syncSetupItems preserves them)"
+  artifacts:
+    - path: "src/db/schema.ts"
+      provides: "classification column on setupItems table"
+      contains: "classification.*text.*default.*base"
+    - path: "src/shared/schemas.ts"
+      provides: "classificationSchema Zod enum and updateClassificationSchema"
+      exports: ["classificationSchema", "updateClassificationSchema"]
+    - path: "src/server/services/setup.service.ts"
+      provides: "updateItemClassification service function, classification-preserving syncSetupItems, classification field in getSetupWithItems"
+      exports: ["updateItemClassification"]
+    - path: "src/server/routes/setups.ts"
+      provides: "PATCH /:id/items/:itemId/classification endpoint"
+    - path: "src/client/components/ClassificationBadge.tsx"
+      provides: "Click-to-cycle classification badge component"
+      min_lines: 30
+    - path: "src/client/routes/setups/$setupId.tsx"
+      provides: "ClassificationBadge wired into item cards in setup view"
+    - path: "tests/services/setup.service.test.ts"
+      provides: "Tests for updateItemClassification, classification preservation, defaults"
+    - path: "tests/routes/setups.test.ts"
+      provides: "Integration test for PATCH classification route"
+  key_links:
+    - from: "src/client/components/ClassificationBadge.tsx"
+      to: "/api/setups/:id/items/:itemId/classification"
+      via: "useUpdateItemClassification mutation hook"
+      pattern: "apiPatch.*classification"
+    - from: "src/server/routes/setups.ts"
+      to: "src/server/services/setup.service.ts"
+      via: "updateItemClassification service call"
+      pattern: "updateItemClassification"
+    - from: "src/server/services/setup.service.ts"
+      to: "src/db/schema.ts"
+      via: "setupItems.classification column"
+      pattern: "setupItems\\.classification"
+    - from: "src/client/routes/setups/$setupId.tsx"
+      to: "src/client/components/ClassificationBadge.tsx"
+      via: "ClassificationBadge rendered on each ItemCard"
+      pattern: "ClassificationBadge"
+---
+
+<objective>
+Add per-setup item classification (base weight / worn / consumable) as a complete vertical slice: schema migration, service layer with tests, API route, and ClassificationBadge UI component wired into the setup detail page.
+
+Purpose: Users need to classify gear items by their role within a specific setup to enable weight breakdown analysis. The same item can serve different roles in different setups (e.g., a jacket is "worn" in a hiking setup but "base weight" in a bike setup).
+
+Output: Working classification system -- clicking a badge on any item card in a setup cycles through base/worn/consumable, persists to the database, and survives item sync operations.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md
+@.planning/phases/09-weight-classification-and-visualization/09-RESEARCH.md
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/db/schema.ts (setupItems table -- CURRENT, needs classification column added):
+```typescript
+export const setupItems = sqliteTable("setup_items", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  setupId: integer("setup_id").notNull().references(() => setups.id, { onDelete: "cascade" }),
+  itemId: integer("item_id").notNull().references(() => items.id, { onDelete: "cascade" }),
+});
+```
+
+From src/server/services/setup.service.ts (functions to modify):
+```typescript
+type Db = typeof prodDb;
+export function getSetupWithItems(db: Db, setupId: number): { ...setup, items: [...] } | null;
+export function syncSetupItems(db: Db, setupId: number, itemIds: number[]): void;
+export function removeSetupItem(db: Db, setupId: number, itemId: number): void;
+```
+
+From src/shared/schemas.ts (existing pattern for enums):
+```typescript
+export const candidateStatusSchema = z.enum(["researching", "ordered", "arrived"]);
+```
+
+From src/client/lib/api.ts (existing helpers -- NO apiPatch exists):
+```typescript
+export async function apiGet<T>(url: string): Promise<T>;
+export async function apiPost<T>(url: string, body: unknown): Promise<T>;
+export async function apiPut<T>(url: string, body: unknown): Promise<T>;
+export async function apiDelete<T>(url: string): Promise<T>;
+```
+
+From src/client/hooks/useSetups.ts (existing types):
+```typescript
+interface SetupItemWithCategory {
+  id: number; name: string; weightGrams: number | null; priceCents: number | null;
+  categoryId: number; notes: string | null; productUrl: string | null;
+  imageFilename: string | null; createdAt: string; updatedAt: string;
+  categoryName: string; categoryIcon: string;
+}
+// NEEDS: classification field added to this interface
+```
+
+From src/client/components/StatusBadge.tsx (pattern reference for click interaction):
+```typescript
+// Uses click-to-open popup with status options
+// ClassificationBadge should be SIMPLER: direct click-to-cycle (only 3 values)
+// Must call e.stopPropagation() to prevent ItemCard click handler
+```
+
+From src/client/components/ItemCard.tsx (props interface -- badge goes in the badges area):
+```typescript
+interface ItemCardProps {
+  id: number; name: string; weightGrams: number | null; priceCents: number | null;
+  categoryName: string; categoryIcon: string; imageFilename: string | null;
+  productUrl?: string | null; onRemove?: () => void;
+}
+// Classification badge will be rendered OUTSIDE ItemCard, in the setup detail page's
+// grid layout, alongside the ItemCard. The ItemCard itself does NOT need modification.
+// The badge sits in the flex-wrap gap-1.5 area of ItemCard OR as a sibling element.
+```
+
+From tests/helpers/db.ts (setup_items CREATE TABLE -- needs classification column):
+```sql
+CREATE TABLE setup_items (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  setup_id INTEGER NOT NULL REFERENCES setups(id) ON DELETE CASCADE,
+  item_id INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE
+)
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Schema migration, service layer, and tests for classification</name>
+  <files>
+    src/db/schema.ts,
+    src/shared/schemas.ts,
+    src/shared/types.ts,
+    src/server/services/setup.service.ts,
+    tests/helpers/db.ts,
+    tests/services/setup.service.test.ts
+  </files>
+  <behavior>
+    - Test: updateItemClassification sets classification for a specific item in a specific setup
+    - Test: updateItemClassification with "worn" changes item from default "base" to "worn"
+    - Test: getSetupWithItems returns classification field for each item (defaults to "base")
+    - Test: syncSetupItems preserves existing classifications when re-syncing (save before delete, restore after insert)
+    - Test: syncSetupItems assigns "base" to newly added items that have no prior classification
+    - Test: same item in two different setups can have different classifications
+  </behavior>
+  <action>
+    1. **Update test helper FIRST** (`tests/helpers/db.ts`): Add `classification text NOT NULL DEFAULT 'base'` to the `setup_items` CREATE TABLE statement.
+
+    2. **Write failing tests** in `tests/services/setup.service.test.ts`:
+       - Add `describe("updateItemClassification", ...)` block with tests for setting classification and verifying the update
+       - Add test in existing `getSetupWithItems` describe for classification field presence (should default to "base")
+       - Add test in existing `syncSetupItems` describe for classification preservation (sync with different item list, verify classifications retained for items that remain)
+       - Add test for same item in two setups having different classifications
+       - Import the new `updateItemClassification` function from setup.service.ts
+
+    3. **Run tests** -- they must FAIL (RED phase).
+
+    4. **Update Drizzle schema** (`src/db/schema.ts`): Add `classification: text("classification").notNull().default("base")` to the `setupItems` table definition.
+
+    5. **Generate migration**: Run `bun run db:generate` to create the migration SQL file. Then run `bun run db:push` to apply.
+
+    6. **Add Zod schema** (`src/shared/schemas.ts`):
+       ```typescript
+       export const classificationSchema = z.enum(["base", "worn", "consumable"]);
+       export const updateClassificationSchema = z.object({
+         classification: classificationSchema,
+       });
+       ```
+
+    7. **Add types** (`src/shared/types.ts`): Add `UpdateClassification` type inferred from `updateClassificationSchema`. The `SetupItem` type auto-updates from Drizzle schema inference.
+
+    8. **Implement service functions** (`src/server/services/setup.service.ts`):
+       - Add `updateItemClassification(db, setupId, itemId, classification)` -- uses `db.update(setupItems).set({ classification }).where(sql\`..setupId AND ..itemId\`)`.
+       - Modify `getSetupWithItems` to include `classification: setupItems.classification` in the select fields.
+       - Modify `syncSetupItems` to preserve classifications using Approach A from research: before deleting, read existing classifications into a `Map<number, string>` (itemId -> classification). After re-inserting, apply saved classifications using `classificationMap.get(itemId) ?? "base"` in the insert values.
+
+    9. **Run tests** -- they must PASS (GREEN phase).
+  </action>
+  <verify>
+    <automated>bun test tests/services/setup.service.test.ts</automated>
+  </verify>
+  <done>
+    - updateItemClassification changes an item's classification in a setup
+    - getSetupWithItems returns classification field defaulting to "base"
+    - syncSetupItems preserves classifications for retained items, defaults new items to "base"
+    - Same item can have different classifications in different setups
+    - All existing setup service tests still pass
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: API route, client hook, ClassificationBadge, and wiring into setup detail page</name>
+  <files>
+    src/server/routes/setups.ts,
+    src/client/lib/api.ts,
+    src/client/hooks/useSetups.ts,
+    src/client/components/ClassificationBadge.tsx,
+    src/client/routes/setups/$setupId.tsx,
+    tests/routes/setups.test.ts
+  </files>
+  <action>
+    1. **Add PATCH route** (`src/server/routes/setups.ts`):
+       - Import `updateClassificationSchema` from schemas and `updateItemClassification` from service.
+       - Add `app.patch("/:id/items/:itemId/classification", zValidator("json", updateClassificationSchema), handler)`.
+       - Handler: extract `setupId` and `itemId` from params, `classification` from validated body, call `updateItemClassification(db, setupId, itemId, classification)`, return `{ success: true }`.
+
+    2. **Add integration test** (`tests/routes/setups.test.ts`):
+       - Add `describe("PATCH /api/setups/:id/items/:itemId/classification", ...)` block.
+       - Test: create setup, add item, PATCH classification to "worn", GET setup and verify item has classification "worn".
+       - Test: PATCH with invalid classification value returns 400.
+
+    3. **Add `apiPatch` helper** (`src/client/lib/api.ts`):
+       ```typescript
+       export async function apiPatch<T>(url: string, body: unknown): Promise<T> {
+         const res = await fetch(url, {
+           method: "PATCH",
+           headers: { "Content-Type": "application/json" },
+           body: JSON.stringify(body),
+         });
+         return handleResponse<T>(res);
+       }
+       ```
+
+    4. **Update client hooks** (`src/client/hooks/useSetups.ts`):
+       - Add `classification: string` field to `SetupItemWithCategory` interface (defaults to "base" from API).
+       - Add `useUpdateItemClassification(setupId: number)` mutation hook:
+         ```typescript
+         export function useUpdateItemClassification(setupId: number) {
+           const queryClient = useQueryClient();
+           return useMutation({
+             mutationFn: ({ itemId, classification }: { itemId: number; classification: string }) =>
+               apiPatch<{ success: boolean }>(
+                 `/api/setups/${setupId}/items/${itemId}/classification`,
+                 { classification },
+               ),
+             onSuccess: () => {
+               queryClient.invalidateQueries({ queryKey: ["setups", setupId] });
+             },
+           });
+         }
+         ```
+       - Import `apiPatch` from `../lib/api`.
+
+    5. **Create ClassificationBadge component** (`src/client/components/ClassificationBadge.tsx`):
+       - Props: `classification: string`, `onCycle: () => void`.
+       - Define `CLASSIFICATION_ORDER = ["base", "worn", "consumable"] as const`.
+       - Define `CLASSIFICATION_LABELS = { base: "Base Weight", worn: "Worn", consumable: "Consumable" }`.
+       - Render as a `<button>` with pill styling: `bg-gray-100 text-gray-600 hover:bg-gray-200` (muted gray per user decision).
+       - Display the label text for the current classification.
+       - On click: call `e.stopPropagation()` (critical -- prevents ItemCard from opening edit panel), then call `onCycle()`.
+       - The parent component computes the next classification and calls the mutation.
+
+    6. **Wire into setup detail page** (`src/client/routes/setups/$setupId.tsx`):
+       - Import `ClassificationBadge` and `useUpdateItemClassification`.
+       - Create the mutation hook: `const updateClassification = useUpdateItemClassification(numericId)`.
+       - Add a helper function to compute next classification:
+         ```typescript
+         function nextClassification(current: string): string {
+           const order = ["base", "worn", "consumable"];
+           const idx = order.indexOf(current);
+           return order[(idx + 1) % order.length];
+         }
+         ```
+       - In the items grid, render `ClassificationBadge` below each `ItemCard` (as a sibling within the grid cell). Wrap ItemCard + badge in a `<div>`:
+         ```tsx
+         <div key={item.id}>
+           <ItemCard ... />
+           <div className="px-4 pb-3 -mt-1">
+             <ClassificationBadge
+               classification={item.classification}
+               onCycle={() => updateClassification.mutate({
+                 itemId: item.id,
+                 classification: nextClassification(item.classification),
+               })}
+             />
+           </div>
+         </div>
+         ```
+       - Alternatively, the badge can go inside the card's badge row if preferred. Use discretion on exact placement -- it should be near the weight/price badges but distinct.
+
+    7. **Run all tests** to verify nothing broken.
+  </action>
+  <verify>
+    <automated>bun test tests/routes/setups.test.ts && bun test tests/services/setup.service.test.ts</automated>
+  </verify>
+  <done>
+    - PATCH /api/setups/:id/items/:itemId/classification endpoint works (200 for valid, 400 for invalid)
+    - ClassificationBadge renders on each item card in setup detail view with muted gray styling
+    - Clicking the badge cycles classification: base weight -> worn -> consumable -> base weight
+    - Badge click does NOT open the item edit panel (stopPropagation works)
+    - Classification change persists after page refresh
+    - GET /api/setups/:id returns classification field for each item
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+```bash
+# All tests pass
+bun test
+
+# Classification service tests specifically
+bun test tests/services/setup.service.test.ts -t "classification"
+
+# Classification route tests specifically
+bun test tests/routes/setups.test.ts -t "classification"
+```
+</verification>
+
+<success_criteria>
+- Classification badge visible on every item card in setup detail view (not hidden for default)
+- Click cycles through base weight -> worn -> consumable -> base weight
+- Badge uses muted gray styling (bg-gray-100 text-gray-600) consistent with Phase 8 status badges
+- Default classification is "base" for newly added items
+- syncSetupItems preserves classifications when items are added/removed
+- Same item in different setups can have different classifications
+- All existing tests continue to pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/09-weight-classification-and-visualization/09-01-SUMMARY.md`
+</output>

.planning/phases/09-weight-classification-and-visualization/09-01-SUMMARY.md

@@ -0,0 +1,129 @@
+---
+phase: 09-weight-classification-and-visualization
+plan: 01
+subsystem: database, api, ui
+tags: [drizzle, sqlite, hono, react, tailwind, classification, setup-items]
+
+# Dependency graph
+requires:
+  - phase: 08-search-filter-and-candidate-status
+    provides: StatusBadge pattern for click-interactive badges, muted gray styling convention
+provides:
+  - classification column on setupItems join table (base/worn/consumable)
+  - updateItemClassification service function
+  - classification-preserving syncSetupItems
+  - PATCH /api/setups/:id/items/:itemId/classification endpoint
+  - ClassificationBadge click-to-cycle component
+  - apiPatch client helper
+  - useUpdateItemClassification mutation hook
+affects: [09-02-weight-breakdown-visualization]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [click-to-cycle badge, classification preservation on sync, per-join-table metadata]
+
+key-files:
+  created:
+    - src/client/components/ClassificationBadge.tsx
+    - drizzle/0003_misty_mongu.sql
+  modified:
+    - src/db/schema.ts
+    - src/shared/schemas.ts
+    - src/shared/types.ts
+    - src/server/services/setup.service.ts
+    - src/server/routes/setups.ts
+    - src/client/lib/api.ts
+    - src/client/hooks/useSetups.ts
+    - src/client/routes/setups/$setupId.tsx
+    - tests/helpers/db.ts
+    - tests/services/setup.service.test.ts
+    - tests/routes/setups.test.ts
+
+key-decisions:
+  - "ClassificationBadge uses simple click-to-cycle (not popup) since only 3 values"
+  - "Classification stored on setupItems join table so same item can differ across setups"
+  - "syncSetupItems reads classifications into Map before delete, restores after re-insert"
+
+patterns-established:
+  - "Click-to-cycle badge: for small enums (3 values), direct click cycling is simpler than popup"
+  - "Join table metadata preservation: save metadata before atomic sync, restore after re-insert"
+  - "apiPatch helper: PATCH method available in client API library for partial updates"
+
+requirements-completed: [CLAS-01, CLAS-03, CLAS-04]
+
+# Metrics
+duration: 5min
+completed: 2026-03-16
+---
+
+# Phase 9 Plan 1: Classification Schema and Badge Summary
+
+**Per-setup item classification (base/worn/consumable) with click-to-cycle badge, classification-preserving sync, and full test coverage**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-16T14:08:56Z
+- **Completed:** 2026-03-16T14:13:32Z
+- **Tasks:** 2
+- **Files modified:** 12
+
+## Accomplishments
+- Added classification column to setupItems table with Drizzle migration (defaults to "base")
+- Implemented classification-preserving syncSetupItems that saves/restores classifications across atomic re-sync
+- Built PATCH endpoint with Zod validation for updating item classification within a setup
+- Created ClassificationBadge component with click-to-cycle interaction (base weight -> worn -> consumable)
+- Wired badge into setup detail page below each ItemCard in the category-grouped grid
+- Added apiPatch client helper and useUpdateItemClassification mutation hook
+- 7 new tests (5 service, 2 route) covering classification CRUD, preservation, cross-setup independence, and validation
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Schema migration, service layer, and tests for classification** - `4491e4c` (feat - TDD red/green)
+2. **Task 2: API route, client hook, ClassificationBadge, and wiring** - `fb738d7` (feat)
+
+## Files Created/Modified
+- `src/db/schema.ts` - Added classification column to setupItems table
+- `drizzle/0003_misty_mongu.sql` - SQLite migration for classification column
+- `src/shared/schemas.ts` - Added classificationSchema and updateClassificationSchema
+- `src/shared/types.ts` - Added UpdateClassification type
+- `src/server/services/setup.service.ts` - Added updateItemClassification, modified getSetupWithItems and syncSetupItems
+- `src/server/routes/setups.ts` - Added PATCH /:id/items/:itemId/classification endpoint
+- `src/client/lib/api.ts` - Added apiPatch helper
+- `src/client/hooks/useSetups.ts` - Added classification field and useUpdateItemClassification hook
+- `src/client/components/ClassificationBadge.tsx` - New click-to-cycle badge component
+- `src/client/routes/setups/$setupId.tsx` - Wired ClassificationBadge into item grid
+- `tests/helpers/db.ts` - Added classification column to test schema
+- `tests/services/setup.service.test.ts` - Added 5 classification tests
+- `tests/routes/setups.test.ts` - Added 2 classification integration tests
+
+## Decisions Made
+- ClassificationBadge uses simple click-to-cycle rather than popup (only 3 values, simpler UX)
+- Classification stored on setupItems join table (not items table) so same item can have different roles in different setups
+- syncSetupItems preserves classifications by reading into Map<itemId, classification> before delete and restoring after re-insert
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Classification data is available for weight breakdown visualization (Plan 09-02)
+- getSetupWithItems returns classification field for every item, ready for grouping by classification
+- All 121 tests pass across the full suite
+
+## Self-Check: PASSED
+
+All 14 files verified present. Both task commits (4491e4c, fb738d7) confirmed in git history.
+
+---
+*Phase: 09-weight-classification-and-visualization*
+*Completed: 2026-03-16*

.planning/phases/09-weight-classification-and-visualization/09-02-PLAN.md

@@ -0,0 +1,309 @@
+---
+phase: 09-weight-classification-and-visualization
+plan: 02
+type: execute
+wave: 2
+depends_on: ["09-01"]
+files_modified:
+  - src/client/components/WeightSummaryCard.tsx
+  - src/client/routes/setups/$setupId.tsx
+  - package.json
+autonomous: false
+requirements: [CLAS-02, VIZZ-01, VIZZ-02, VIZZ-03]
+
+must_haves:
+  truths:
+    - "Setup detail view shows separate weight subtotals for base weight, worn weight, consumable weight, and total"
+    - "User can view a donut chart showing weight distribution by category in the setup"
+    - "User can toggle the chart between category breakdown and classification breakdown via pill toggle"
+    - "Hovering a chart segment shows category/classification name, weight in selected unit, and percentage"
+    - "Total weight displayed in the center of the donut hole"
+  artifacts:
+    - path: "src/client/components/WeightSummaryCard.tsx"
+      provides: "Summary card with weight subtotals, donut chart, pill toggle, and tooltips"
+      min_lines: 100
+    - path: "src/client/routes/setups/$setupId.tsx"
+      provides: "WeightSummaryCard rendered below sticky bar when setup has items"
+    - path: "package.json"
+      provides: "recharts dependency installed"
+      contains: "recharts"
+  key_links:
+    - from: "src/client/components/WeightSummaryCard.tsx"
+      to: "recharts"
+      via: "PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer imports"
+      pattern: "from.*recharts"
+    - from: "src/client/components/WeightSummaryCard.tsx"
+      to: "src/client/lib/formatters.ts"
+      via: "formatWeight for subtotals and tooltip display"
+      pattern: "formatWeight"
+    - from: "src/client/routes/setups/$setupId.tsx"
+      to: "src/client/components/WeightSummaryCard.tsx"
+      via: "WeightSummaryCard rendered with setup.items prop"
+      pattern: "WeightSummaryCard"
+---
+
+<objective>
+Add the WeightSummaryCard component with classification weight subtotals, a donut chart for weight distribution, and a pill toggle for switching between category and classification views.
+
+Purpose: Users need to visualize how weight is distributed across their setup -- both by gear category (shelter, sleep, cook) and by classification (base weight, worn, consumable). The donut chart with tooltips makes weight analysis intuitive.
+
+Output: A summary card below the setup sticky bar showing Base | Worn | Consumable | Total weight columns alongside a donut chart with interactive tooltips, togglable between category and classification breakdowns.
+</objective>
+
+<execution_context>
+@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
+@/home/jlmak/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md
+@.planning/phases/09-weight-classification-and-visualization/09-RESEARCH.md
+@.planning/phases/09-weight-classification-and-visualization/09-01-SUMMARY.md
+
+<interfaces>
+<!-- Key types and contracts from Plan 01. Executor uses these directly. -->
+
+From src/client/hooks/useSetups.ts (after Plan 01):
+```typescript
+interface SetupItemWithCategory {
+  id: number;
+  name: string;
+  weightGrams: number | null;
+  priceCents: number | null;
+  categoryId: number;
+  notes: string | null;
+  productUrl: string | null;
+  imageFilename: string | null;
+  createdAt: string;
+  updatedAt: string;
+  categoryName: string;
+  categoryIcon: string;
+  classification: string;  // "base" | "worn" | "consumable" -- added by Plan 01
+}
+```
+
+From src/client/lib/formatters.ts:
+```typescript
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+export function formatWeight(grams: number | null | undefined, unit: WeightUnit = "g"): string;
+```
+
+From src/client/hooks/useWeightUnit.ts:
+```typescript
+export function useWeightUnit(): WeightUnit;
+```
+
+From 09-RESEARCH.md (Recharts pattern):
+```typescript
+import { PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer } from "recharts";
+// Use Cell for per-slice colors (still functional in v3, deprecated for v4)
+// Use fixed numeric height on ResponsiveContainer (e.g., height={200})
+// Filter out zero-weight entries before passing to chart
+```
+
+From 09-RESEARCH.md (color palettes):
+```typescript
+const CATEGORY_COLORS = [
+  "#6366f1", "#f59e0b", "#10b981", "#ef4444", "#8b5cf6",
+  "#06b6d4", "#f97316", "#ec4899", "#14b8a6", "#84cc16",
+];
+const CLASSIFICATION_COLORS = {
+  base: "#6366f1",       // indigo
+  worn: "#f59e0b",       // amber
+  consumable: "#10b981", // emerald
+};
+```
+
+From 09-CONTEXT.md (locked decisions):
+- Summary card below sticky bar, always visible when setup has items
+- Card with columns layout: Base | Worn | Consumable | Total
+- Donut chart inside the summary card alongside weight subtotals
+- Pill toggle above the chart: "Category" / "Classification" (same style as weight unit selector)
+- Total weight in center of donut hole
+- Hover tooltips: segment name, weight in selected unit, percentage
+- Chart library: Recharts (PieChart + Pie with innerRadius)
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Install Recharts, create WeightSummaryCard, wire into setup detail page</name>
+  <files>
+    src/client/components/WeightSummaryCard.tsx,
+    src/client/routes/setups/$setupId.tsx,
+    package.json
+  </files>
+  <action>
+    1. **Install Recharts**: Run `bun add recharts`. This adds recharts to package.json. React and react-dom are already peer deps in the project.
+
+    2. **Create WeightSummaryCard component** (`src/client/components/WeightSummaryCard.tsx`):
+
+       **Props interface:**
+       ```typescript
+       interface WeightSummaryCardProps {
+         items: SetupItemWithCategory[];  // from useSetups hook (includes classification field)
+       }
+       ```
+       Import `SetupItemWithCategory` from `../hooks/useSetups`.
+
+       **State:** `viewMode: "category" | "classification"` -- local React state, default "category".
+
+       **Weight subtotals computation** (derive from items array):
+       ```typescript
+       const baseWeight = items.reduce((sum, i) => i.classification === "base" ? sum + (i.weightGrams ?? 0) : sum, 0);
+       const wornWeight = items.reduce((sum, i) => i.classification === "worn" ? sum + (i.weightGrams ?? 0) : sum, 0);
+       const consumableWeight = items.reduce((sum, i) => i.classification === "consumable" ? sum + (i.weightGrams ?? 0) : sum, 0);
+       const totalWeight = baseWeight + wornWeight + consumableWeight;
+       ```
+
+       **Chart data transformation:**
+       - `buildCategoryChartData(items)`: Group by `categoryName`, sum `weightGrams`, compute percentage. Filter out zero-weight groups. Return `Array<{ name: string, weight: number, percent: number }>`.
+       - `buildClassificationChartData(items)`: Group by classification using labels ("Base Weight", "Worn", "Consumable"), sum weights, compute percentage. Filter out zero-weight groups.
+       - Select data source based on `viewMode`.
+
+       **Render structure:**
+       ```
+       <div className="bg-white rounded-xl border border-gray-100 p-5 mb-6">
+         <!-- Pill toggle: Category | Classification -->
+         <div className="flex items-center justify-between mb-4">
+           <h3 className="text-sm font-medium text-gray-700">Weight Summary</h3>
+           <PillToggle viewMode={viewMode} onChange={setViewMode} />
+         </div>
+
+         <!-- Main content: chart + subtotals side by side -->
+         <div className="flex items-center gap-8">
+           <!-- Donut chart -->
+           <div className="flex-shrink-0" style={{ width: 180, height: 180 }}>
+             <ResponsiveContainer width="100%" height={180}>
+               <PieChart>
+                 <Pie data={chartData} dataKey="weight" nameKey="name"
+                   cx="50%" cy="50%" innerRadius={55} outerRadius={80} paddingAngle={2}>
+                   {chartData.map((entry, index) => (
+                     <Cell key={entry.name} fill={colors[index % colors.length]} />
+                   ))}
+                   <Label value={formatWeight(totalWeight, unit)} position="center"
+                     style={{ fontSize: "14px", fontWeight: 600, fill: "#374151" }} />
+                 </Pie>
+                 <Tooltip content={<CustomTooltip unit={unit} />} />
+               </PieChart>
+             </ResponsiveContainer>
+           </div>
+
+           <!-- Weight subtotals columns -->
+           <div className="flex-1 grid grid-cols-4 gap-4">
+             <SubtotalColumn label="Base" weight={baseWeight} unit={unit} color="#6366f1" />
+             <SubtotalColumn label="Worn" weight={wornWeight} unit={unit} color="#f59e0b" />
+             <SubtotalColumn label="Consumable" weight={consumableWeight} unit={unit} color="#10b981" />
+             <SubtotalColumn label="Total" weight={totalWeight} unit={unit} />
+           </div>
+         </div>
+       </div>
+       ```
+
+       **Pill toggle** (inline component or extracted):
+       - Two buttons in a `bg-gray-100 rounded-full` container: "Category" and "Classification".
+       - Active state: `bg-white text-gray-700 shadow-sm font-medium`. Inactive: `text-gray-400 hover:text-gray-600`.
+       - Same pattern as TotalsBar weight unit selector.
+
+       **SubtotalColumn** (inline component):
+       - Vertical stack: colored dot (if color provided), label in text-xs text-gray-500, weight value in text-sm font-semibold text-gray-900.
+
+       **CustomTooltip:**
+       - Props: `active`, `payload`, `unit` (WeightUnit).
+       - When active and payload exists, show: segment name (bold), weight formatted with `formatWeight()`, percentage as `(XX.X%)`.
+       - Styled: `bg-white border border-gray-200 rounded-lg shadow-lg px-3 py-2 text-sm`.
+
+       **Color selection:**
+       - When `viewMode === "category"`: use `CATEGORY_COLORS` array (cycle through for many categories).
+       - When `viewMode === "classification"`: use `CLASSIFICATION_COLORS` object (keyed by classification value).
+
+       **Edge cases:**
+       - If all items have null/zero weight, show a placeholder message ("No weight data to display") instead of the chart.
+       - If items array is empty, component should not render (handled by parent).
+
+    3. **Wire into setup detail page** (`src/client/routes/setups/$setupId.tsx`):
+       - Import `WeightSummaryCard` from `../../components/WeightSummaryCard`.
+       - Render `<WeightSummaryCard items={setup.items} />` between the actions bar and the items grid (before the `{itemCount > 0 && (` block), but INSIDE the `itemCount > 0` condition so it only shows when there are items.
+       - Exact placement: after the actions `<div>` and before the items-grouped-by-category `<div>`, within the `{itemCount > 0 && (...)}` block.
+
+    4. **Verify**: Run `bun run build` to ensure no TypeScript errors and Recharts imports resolve correctly.
+  </action>
+  <verify>
+    <automated>bun run build</automated>
+  </verify>
+  <done>
+    - WeightSummaryCard renders below sticky bar when setup has items
+    - Shows 4 columns: Base | Worn | Consumable | Total with correct weight values in selected unit
+    - Donut chart renders with colored segments for weight distribution
+    - Pill toggle switches between category view and classification view
+    - Hovering chart segments shows tooltip with name, weight, and percentage
+    - Total weight displayed in center of donut hole
+    - Empty/zero-weight items handled gracefully
+    - Build succeeds with no TypeScript errors
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Visual verification of complete weight classification and visualization</name>
+  <files>N/A</files>
+  <action>
+    Present the user with verification steps for the complete Phase 9 feature set.
+    This checkpoint covers both Plan 01 (classification badges) and Plan 02 (summary card + chart) together.
+  </action>
+  <what-built>
+    Complete weight classification and visualization system:
+    1. Classification badges on every item card in setup view (click to cycle: base weight / worn / consumable)
+    2. Weight summary card with Base | Worn | Consumable | Total subtotals
+    3. Donut chart with category/classification toggle and hover tooltips
+    4. Total weight in the center of the donut hole
+  </what-built>
+  <how-to-verify>
+    1. Start dev servers: `bun run dev:server` and `bun run dev:client`
+    2. Open http://localhost:5173 and navigate to a setup with items (or create one and add items)
+    3. **Classification badges**: Verify each item card shows a gray pill badge. Click it and confirm it cycles: "Base Weight" -> "Worn" -> "Consumable" -> "Base Weight". Confirm clicking the badge does NOT open the item edit panel.
+    4. **Classification persistence**: Refresh the page. Confirm classifications are preserved.
+    5. **Weight subtotals**: With items classified differently, verify the summary card shows correct subtotals for Base, Worn, Consumable, and Total columns.
+    6. **Donut chart (Category view)**: Verify the donut chart shows colored segments grouped by category. Hover segments to see tooltip with category name, weight, and percentage.
+    7. **Donut chart (Classification view)**: Click the "Classification" pill toggle. Verify chart segments change to show base/worn/consumable breakdown with different colors. Hover to verify tooltips.
+    8. **Donut center**: Confirm total weight is displayed in the center of the donut hole in the selected weight unit.
+    9. **Weight unit**: Toggle the weight unit in the top bar (if available). Confirm all subtotals, chart center, and tooltips update to the new unit.
+    10. **Add/remove items**: Add another item to the setup. Verify it appears with default "Base Weight" badge and the chart updates. Remove an item and verify classifications for remaining items are preserved.
+  </how-to-verify>
+  <verify>Visual verification by user following steps above</verify>
+  <done>User confirms all classification badges, weight subtotals, donut chart, toggle, and tooltips work correctly</done>
+  <resume-signal>Type "approved" to complete Phase 9, or describe any issues to address</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+```bash
+# Full test suite passes
+bun test
+
+# Build succeeds
+bun run build
+
+# Lint passes
+bun run lint
+```
+</verification>
+
+<success_criteria>
+- WeightSummaryCard visible below sticky bar on setup detail page (only when items exist)
+- Four weight columns (Base, Worn, Consumable, Total) show correct values in selected unit
+- Donut chart renders with colored segments proportional to weight distribution
+- Pill toggle switches between category and classification chart views
+- Tooltip on hover shows segment name, formatted weight, and percentage
+- Total weight displayed in center of donut hole
+- Chart handles edge cases (no weight data, single category, etc.)
+- User confirms visual appearance matches expectations
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/09-weight-classification-and-visualization/09-02-SUMMARY.md`
+</output>

.planning/phases/09-weight-classification-and-visualization/09-02-SUMMARY.md

@@ -0,0 +1,107 @@
+---
+phase: 09-weight-classification-and-visualization
+plan: 02
+subsystem: ui
+tags: [react, recharts, donut-chart, tailwind, weight-visualization, pie-chart]
+
+# Dependency graph
+requires:
+  - phase: 09-weight-classification-and-visualization
+    provides: classification column on setupItems, getSetupWithItems returns classification field, SetupItemWithCategory type
+provides:
+  - WeightSummaryCard component with donut chart and classification subtotals
+  - Pill toggle for category/classification chart views
+  - Recharts integration (PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer)
+  - Custom tooltip with formatted weight and percentage display
+affects: []
+
+# Tech tracking
+tech-stack:
+  added: [recharts]
+  patterns: [donut chart with center label, pill toggle view switcher, chart data transformation from items array]
+
+key-files:
+  created:
+    - src/client/components/WeightSummaryCard.tsx
+  modified:
+    - src/client/routes/setups/$setupId.tsx
+    - package.json
+
+key-decisions:
+  - "Recharts v3 Cell component used for per-slice colors (still functional, deprecated for v4)"
+  - "Fixed numeric height on ResponsiveContainer (180px) to avoid zero-height rendering"
+  - "Zero-weight items filtered out before chart data to prevent invisible/NaN slices"
+
+patterns-established:
+  - "Donut chart: PieChart with Pie innerRadius/outerRadius and Label position=center for hole text"
+  - "Chart data transformation: group items by key, sum weights, compute percentages, filter zeroes"
+  - "Pill toggle view switcher: reusable pattern for switching between data breakdowns"
+
+requirements-completed: [CLAS-02, VIZZ-01, VIZZ-02, VIZZ-03]
+
+# Metrics
+duration: 2min
+completed: 2026-03-16
+---
+
+# Phase 9 Plan 2: Weight Breakdown Visualization Summary
+
+**Recharts donut chart with category/classification toggle, weight subtotals card, and hover tooltips inside setup detail page**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-16T14:18:52Z
+- **Completed:** 2026-03-16T14:20:57Z
+- **Tasks:** 1 (+ 1 auto-approved checkpoint)
+- **Files modified:** 4
+
+## Accomplishments
+- Created WeightSummaryCard component with donut chart visualization using Recharts
+- Implemented pill toggle switching between category and classification chart views
+- Built weight subtotals display (Base | Worn | Consumable | Total) with colored indicator dots
+- Added custom tooltip showing segment name, formatted weight, and percentage on hover
+- Rendered total weight in center of donut hole using selected weight unit
+- Wired WeightSummaryCard into setup detail page below sticky bar (only when items exist)
+- Handled edge case of zero-weight items with placeholder message
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Install Recharts, create WeightSummaryCard, wire into setup detail page** - `d098277` (feat)
+
+## Files Created/Modified
+- `src/client/components/WeightSummaryCard.tsx` - New component with donut chart, pill toggle, subtotals, and custom tooltip
+- `src/client/routes/setups/$setupId.tsx` - Added WeightSummaryCard import and rendering inside itemCount > 0 block
+- `package.json` - Added recharts dependency
+- `bun.lock` - Updated lockfile with recharts and its dependencies
+
+## Decisions Made
+- Used Recharts v3 Cell component for per-slice colors (functional in v3, deprecated for v4 removal)
+- Fixed 180px height on ResponsiveContainer to prevent zero-height rendering issue
+- Filter zero-weight entries before passing to chart to avoid invisible/NaN segments
+- Default view mode is "category" (most useful initial view for gear analysis)
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 9 complete: classification badges + weight visualization both functional
+- All 121 tests pass, build succeeds, lint clean on modified files
+- Recharts available for any future chart features
+
+## Self-Check: PASSED
+
+All 3 files verified present. Task commit (d098277) confirmed in git history. recharts found in package.json. WeightSummaryCard found in $setupId.tsx.
+
+---
+*Phase: 09-weight-classification-and-visualization*
+*Completed: 2026-03-16*

.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md

@@ -0,0 +1,93 @@
+# Phase 9: Weight Classification and Visualization - Context
+
+**Gathered:** 2026-03-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can classify each item within a setup as base weight, worn, or consumable (same item can differ across setups). Setup detail view shows weight subtotals by classification and a donut chart for weight distribution, toggleable between category and classification breakdowns. Side-by-side comparison, ranking, and impact preview are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Classification UI
+- Click-to-cycle badge on each item card within a setup — clicks cycle through base weight → worn → consumable → base weight
+- Follows the StatusBadge pattern from Phase 8 (pill badge, click interaction)
+- Default classification is "base weight" when an item is added to a setup
+- Badge always visible on every item card in the setup (not hidden for default)
+- Muted gray color scheme for all classification badges (bg-gray-100 text-gray-600), consistent with Phase 8 status badges
+- Classification stored on `setup_items` join table (already decided in prior phases)
+
+### Weight subtotals display
+- Summary section below the setup sticky bar, always visible when setup has items
+- Card with columns layout: Base | Worn | Consumable | Total — each as a labeled column with weight value
+- Sticky bar keeps its existing simple stats (item count, total weight, total cost)
+- Summary card is a separate visual element, not inline text
+
+### Chart placement & style
+- Donut chart sits inside the summary card alongside the weight subtotals — chart + numbers as one visual unit
+- Pill toggle above the chart for switching between "Category" and "Classification" views (same style as weight unit selector)
+- Total weight displayed in the center of the donut hole (e.g., "2.87kg")
+- Hover tooltips show segment name, weight (in selected unit), and percentage
+- Chart library: **Recharts** (PieChart + Pie with innerRadius for donut shape)
+
+### Claude's Discretion
+- Summary card exact layout (chart left/right, column arrangement)
+- Chart color palette for segments (should work with both category and classification views)
+- Minimum item threshold for showing chart vs a placeholder message
+- Donut chart sizing and proportions
+- Tooltip styling
+- Keyboard accessibility for classification cycling
+- Animation on chart transitions between category/classification views
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `StatusBadge` (`src/client/components/StatusBadge.tsx`): Click-to-cycle pattern with popup — direct pattern reference for classification badge
+- `formatWeight()` in `src/client/lib/formatters.ts`: Handles unit conversion, reuse for subtotals and chart tooltips
+- `useWeightUnit()` hook: Gets current weight unit setting for display
+- `getSetupWithItems()` in `src/server/services/setup.service.ts`: Fetches setup items with category joins — needs to include classification field
+- `syncSetupItems()`: Delete-all + re-insert pattern — needs to preserve classification values
+
+### Established Patterns
+- Settings stored as key/value strings in SQLite `settings` table
+- React Query for server data, Zustand for UI-only state (panels/dialogs)
+- Pill badges: blue-50/blue-400 for weight, green-50/green-500 for price, gray-50/gray-600 for metadata
+- Weight unit pill toggle in TotalsBar — same pattern for chart category/classification toggle
+- Click-outside + Escape dismiss pattern for popups (CategoryPicker, StatusBadge)
+
+### Integration Points
+- `setup_items` table (`src/db/schema.ts`): Add `classification` column with default "base"
+- `getSetupWithItems()`: Include classification in query results
+- `syncSetupItems()`: Must handle classification when syncing (preserve during re-insert)
+- Setup detail page (`src/client/routes/setups/$setupId.tsx`): Add summary card section, classification badges on ItemCards, donut chart
+- `ItemCard` component: Needs optional `classification` prop and badge (only rendered in setup context)
+- Setup routes (`src/server/routes/setups.ts`): API needs to accept/return classification data
+- Test helper (`tests/helpers/db.ts`): Update CREATE TABLE for setup_items to include classification column
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — user gave clear structural decisions. Standard gear app patterns apply (LighterPack-style classification).
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 09-weight-classification-and-visualization*
+*Context gathered: 2026-03-16*

.planning/phases/09-weight-classification-and-visualization/09-RESEARCH.md

@@ -0,0 +1,553 @@
+# Phase 9: Weight Classification and Visualization - Research
+
+**Researched:** 2026-03-16
+**Domain:** Schema migration, classification UI, chart visualization (Recharts)
+**Confidence:** HIGH
+
+## Summary
+
+Phase 9 adds two features: (1) per-setup item classification (base weight / worn / consumable) stored on the `setup_items` join table, and (2) a donut chart visualization of weight distribution inside the setup detail page. The classification feature requires a schema migration adding a `classification` column with a default of `"base"` to `setup_items`, updates to the sync/query service layer, a new API endpoint for updating individual item classifications, and a click-to-cycle badge on each item card within setup context. The visualization feature requires installing Recharts and building a summary card component with a donut chart, weight subtotals, and a pill toggle for switching between category and classification breakdowns.
+
+The project has strong existing patterns to follow: the `StatusBadge` click-to-cycle component from Phase 8, the `formatWeight()` utility with `useWeightUnit()` hook, the TotalsBar pill toggle for weight units, and the Drizzle migration pattern established in prior phases (e.g., `0002_broken_roughhouse.sql` adding a column with `ALTER TABLE ... ADD`). Recharts v3.x is the decided chart library, which is mature, well-documented, and has a straightforward API for donut charts using `PieChart` + `Pie` with `innerRadius`.
+
+**Primary recommendation:** Use Recharts v3.x with `Cell` component for individual slice colors (still functional in v3, deprecated only for v4), `Label` for center text, and a custom `content` function on `Tooltip` for formatted hover data. Store classification as a text column on `setup_items` with a Zod enum for validation.
+
+<user_constraints>
+
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- Click-to-cycle badge on each item card within a setup -- clicks cycle through base weight -> worn -> consumable -> base weight
+- Follows the StatusBadge pattern from Phase 8 (pill badge, click interaction)
+- Default classification is "base weight" when an item is added to a setup
+- Badge always visible on every item card in the setup (not hidden for default)
+- Muted gray color scheme for all classification badges (bg-gray-100 text-gray-600), consistent with Phase 8 status badges
+- Classification stored on `setup_items` join table (already decided in prior phases)
+- Summary section below the setup sticky bar, always visible when setup has items
+- Card with columns layout: Base | Worn | Consumable | Total -- each as a labeled column with weight value
+- Sticky bar keeps its existing simple stats (item count, total weight, total cost)
+- Summary card is a separate visual element, not inline text
+- Donut chart sits inside the summary card alongside the weight subtotals -- chart + numbers as one visual unit
+- Pill toggle above the chart for switching between "Category" and "Classification" views (same style as weight unit selector)
+- Total weight displayed in the center of the donut hole (e.g., "2.87kg")
+- Hover tooltips show segment name, weight (in selected unit), and percentage
+- Chart library: **Recharts** (PieChart + Pie with innerRadius for donut shape)
+
+### Claude's Discretion
+- Summary card exact layout (chart left/right, column arrangement)
+- Chart color palette for segments (should work with both category and classification views)
+- Minimum item threshold for showing chart vs a placeholder message
+- Donut chart sizing and proportions
+- Tooltip styling
+- Keyboard accessibility for classification cycling
+- Animation on chart transitions between category/classification views
+
+### Deferred Ideas (OUT OF SCOPE)
+None -- discussion stayed within phase scope
+
+</user_constraints>
+
+<phase_requirements>
+
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| CLAS-01 | User can classify each item within a setup as base weight, worn, or consumable | Classification column on `setup_items`, click-to-cycle badge component, PATCH API endpoint |
+| CLAS-02 | Setup totals display base weight, worn weight, consumable weight, and total separately | Summary card component computing subtotals from items array grouped by classification |
+| CLAS-03 | Items default to "base weight" classification when added to a setup | Schema default `"base"` on classification column, Drizzle migration with DEFAULT |
+| CLAS-04 | Same item can have different classifications in different setups | Classification on `setup_items` join table (not `items` table) -- architecture already decided |
+| VIZZ-01 | User can view a donut chart showing weight distribution by category in a setup | Recharts PieChart + Pie with innerRadius, data grouped by category |
+| VIZZ-02 | User can toggle chart between category view and classification view | Pill toggle component (reuse TotalsBar pattern), local React state for view mode |
+| VIZZ-03 | User can hover chart segments to see category name, weight, and percentage | Recharts Tooltip with custom content renderer using formatWeight() |
+
+</phase_requirements>
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| recharts | ^3.8.0 | Donut chart visualization | Most popular React charting library, declarative API, built on D3, 27K GitHub stars |
+
+### Supporting (already in project)
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| drizzle-orm | ^0.45.1 | Schema migration for classification column | Add column to setup_items table |
+| zod | ^4.3.6 | Validation for classification enum | API input validation |
+| react | ^19.2.4 | UI components | Summary card, badge, chart wrapper |
+| tailwindcss | ^4.2.1 | Styling | Summary card layout, badge styling |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| Recharts | Chart.js / react-chartjs-2 | Chart.js is imperative; Recharts is declarative React components -- better fit for this stack |
+| Recharts | Visx | Lower-level D3 wrapper; more control but more code for a simple donut chart |
+| Recharts | Tremor | Tremor wraps Recharts but adds full design system overhead -- too heavy for one chart |
+
+**Installation:**
+```bash
+bun add recharts
+```
+
+Note: Recharts has `react` and `react-dom` as peer dependencies, both already in the project. No additional peer deps needed.
+
+## Architecture Patterns
+
+### Schema Change: setup_items classification column
+
+```sql
+-- Migration: ALTER TABLE setup_items ADD classification text DEFAULT 'base' NOT NULL;
+ALTER TABLE `setup_items` ADD `classification` text DEFAULT 'base' NOT NULL;
+```
+
+The Drizzle schema change in `src/db/schema.ts`:
+```typescript
+export const setupItems = sqliteTable("setup_items", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  setupId: integer("setup_id")
+    .notNull()
+    .references(() => setups.id, { onDelete: "cascade" }),
+  itemId: integer("item_id")
+    .notNull()
+    .references(() => items.id, { onDelete: "cascade" }),
+  classification: text("classification").notNull().default("base"),
+});
+```
+
+Values: `"base"` | `"worn"` | `"consumable"` -- stored as text, validated with Zod enum.
+
+### API Design: Classification Update
+
+A new `PATCH /api/setups/:id/items/:itemId/classification` endpoint is the cleanest approach. It avoids modifying the existing sync endpoint (which does delete-all + re-insert and would lose classifications).
+
+Alternatively, a dedicated `PATCH /api/setup-items/:setupItemId` could work, but using the composite key `(setupId, itemId)` is more consistent with the existing `DELETE /api/setups/:id/items/:itemId` pattern.
+
+**Use:** `PATCH /api/setups/:setupId/items/:itemId/classification` with body `{ classification: "worn" }`.
+
+### syncSetupItems Must Preserve Classifications
+
+The existing `syncSetupItems` function does delete-all + re-insert. After adding classification, this will reset all classifications to "base" whenever items are synced. Two approaches:
+
+**Approach A (recommended):** Before deleting, read existing classifications into a map `{ itemId -> classification }`. After re-inserting, apply the saved classifications. This keeps the atomic sync pattern intact.
+
+**Approach B:** Change sync to diff-based (add new, remove missing, keep existing). More complex, breaks the simple pattern.
+
+Use Approach A -- preserves the established pattern with minimal changes.
+
+### getSetupWithItems Must Include Classification
+
+The `getSetupWithItems` query needs to select `classification` from `setupItems`:
+
+```typescript
+const itemList = db
+  .select({
+    id: items.id,
+    name: items.name,
+    weightGrams: items.weightGrams,
+    priceCents: items.priceCents,
+    categoryId: items.categoryId,
+    // ... existing fields ...
+    categoryName: categories.name,
+    categoryIcon: categories.icon,
+    classification: setupItems.classification, // NEW
+  })
+  .from(setupItems)
+  .innerJoin(items, eq(setupItems.itemId, items.id))
+  .innerJoin(categories, eq(items.categoryId, categories.id))
+  .where(eq(setupItems.setupId, setupId))
+  .all();
+```
+
+### Component Architecture
+
+```
+src/client/
+  components/
+    ClassificationBadge.tsx     # Click-to-cycle badge (base/worn/consumable)
+    WeightSummaryCard.tsx       # Summary card: subtotals + donut chart
+  routes/
+    setups/
+      $setupId.tsx              # Modified: adds ClassificationBadge to ItemCard, adds WeightSummaryCard
+  hooks/
+    useSetups.ts                # Modified: add useUpdateItemClassification mutation, update types
+```
+
+### Pattern: ClassificationBadge (Click-to-Cycle)
+
+Follow the StatusBadge pattern but simplified -- no popup menu needed since there are only 3 values and the user cycles through them. Direct click-to-cycle is faster UX for 3 options.
+
+```typescript
+const CLASSIFICATION_ORDER = ["base", "worn", "consumable"] as const;
+type Classification = typeof CLASSIFICATION_ORDER[number];
+
+const CLASSIFICATION_CONFIG = {
+  base: { label: "Base Weight", icon: "backpack" },
+  worn: { label: "Worn", icon: "shirt" },
+  consumable: { label: "Consumable", icon: "droplets" },
+} as const;
+```
+
+Click handler cycles to next classification: `base -> worn -> consumable -> base`.
+
+### Pattern: Donut Chart with Recharts v3
+
+```typescript
+import { PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer } from "recharts";
+
+// Cell is still functional in v3 (deprecated for v4 removal)
+// This is the standard pattern for v3.x
+<ResponsiveContainer width="100%" height={200}>
+  <PieChart>
+    <Pie
+      data={chartData}
+      dataKey="weight"
+      nameKey="name"
+      cx="50%"
+      cy="50%"
+      innerRadius={55}
+      outerRadius={80}
+      paddingAngle={2}
+    >
+      {chartData.map((entry, index) => (
+        <Cell key={entry.name} fill={COLORS[index % COLORS.length]} />
+      ))}
+      <Label
+        value={formatWeight(totalWeight, unit)}
+        position="center"
+        className="text-lg font-semibold"
+      />
+    </Pie>
+    <Tooltip content={<CustomTooltip unit={unit} />} />
+  </PieChart>
+</ResponsiveContainer>
+```
+
+### Pattern: Custom Tooltip
+
+```typescript
+function CustomTooltip({ active, payload, unit }: any) {
+  if (!active || !payload?.length) return null;
+  const { name, weight, percent } = payload[0].payload;
+  return (
+    <div className="bg-white border border-gray-200 rounded-lg shadow-lg px-3 py-2 text-sm">
+      <p className="font-medium text-gray-900">{name}</p>
+      <p className="text-gray-600">
+        {formatWeight(weight, unit)} ({(percent * 100).toFixed(1)}%)
+      </p>
+    </div>
+  );
+}
+```
+
+### Pattern: Data Transformation for Chart
+
+```typescript
+// Category view: group items by category, sum weights
+function buildCategoryChartData(items: SetupItemWithCategory[]) {
+  const groups = new Map<string, number>();
+  for (const item of items) {
+    const current = groups.get(item.categoryName) ?? 0;
+    groups.set(item.categoryName, current + (item.weightGrams ?? 0));
+  }
+  const total = items.reduce((sum, i) => sum + (i.weightGrams ?? 0), 0);
+  return Array.from(groups.entries())
+    .filter(([_, weight]) => weight > 0)
+    .map(([name, weight]) => ({ name, weight, percent: total > 0 ? weight / total : 0 }));
+}
+
+// Classification view: group by classification, sum weights
+function buildClassificationChartData(items: SetupItemWithClassification[]) {
+  const groups = { base: 0, worn: 0, consumable: 0 };
+  for (const item of items) {
+    groups[item.classification] += item.weightGrams ?? 0;
+  }
+  const total = Object.values(groups).reduce((a, b) => a + b, 0);
+  return Object.entries(groups)
+    .filter(([_, weight]) => weight > 0)
+    .map(([key, weight]) => ({
+      name: CLASSIFICATION_CONFIG[key as Classification].label,
+      weight,
+      percent: total > 0 ? weight / total : 0,
+    }));
+}
+```
+
+### Pattern: Pill Toggle (View Mode Switcher)
+
+Reuse the exact pattern from TotalsBar's weight unit toggle:
+
+```typescript
+const VIEW_MODES = ["category", "classification"] as const;
+type ViewMode = typeof VIEW_MODES[number];
+
+const [viewMode, setViewMode] = useState<ViewMode>("category");
+
+// Rendered as:
+<div className="flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5">
+  {VIEW_MODES.map((mode) => (
+    <button
+      key={mode}
+      onClick={() => setViewMode(mode)}
+      className={`px-2.5 py-0.5 text-xs rounded-full transition-colors capitalize ${
+        viewMode === mode
+          ? "bg-white text-gray-700 shadow-sm font-medium"
+          : "text-gray-400 hover:text-gray-600"
+      }`}
+    >
+      {mode === "category" ? "Category" : "Classification"}
+    </button>
+  ))}
+</div>
+```
+
+### Anti-Patterns to Avoid
+- **Modifying syncSetupItems to accept classifications in the itemIds array:** This couples the sync endpoint to classification data. Keep them separate -- sync manages membership, classification update manages role.
+- **Computing classification subtotals on the server:** The setup detail page already computes totals client-side from the items array. Keep classification subtotals client-side too for consistency.
+- **Using a separate table for classifications:** Overkill. A single column on `setup_items` is the right level of complexity.
+- **Using Recharts v4 patterns (RechartsSymbols.fill):** v4 is not released. Stick with `Cell` component which works in v3.x.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Donut chart rendering | Custom SVG arc calculations | Recharts `PieChart` + `Pie` | Arc math, hit detection, animation, accessibility -- all handled |
+| Chart tooltips | Custom hover position tracking | Recharts `Tooltip` with `content` prop | Viewport boundary detection, positioning, hover state management |
+| Responsive chart sizing | Manual resize observers | Recharts `ResponsiveContainer` | Handles debounced resize, prevents layout thrashing |
+| Weight unit formatting | Inline conversion in chart | Existing `formatWeight()` utility | Already handles all units with correct decimal places |
+
+**Key insight:** Recharts handles all the hard SVG/D3 work. The implementation should focus on data transformation (grouping items into chart segments) and styling (Tailwind classes on the summary card and tooltip).
+
+## Common Pitfalls
+
+### Pitfall 1: syncSetupItems Destroys Classifications
+**What goes wrong:** The existing sync function deletes all setup_items then re-inserts. After adding classification, every sync resets all items to "base".
+**Why it happens:** Delete-all + re-insert pattern was designed before classification existed.
+**How to avoid:** Save classifications before delete, restore after re-insert (Approach A above).
+**Warning signs:** Items losing their classification after adding/removing any item from the setup.
+
+### Pitfall 2: ResponsiveContainer Needs a Defined Parent Height
+**What goes wrong:** Recharts `ResponsiveContainer` with `height="100%"` renders at 0px if the parent container has no explicit height.
+**Why it happens:** CSS percentage heights require the parent to have a defined height.
+**How to avoid:** Use a fixed numeric height on `ResponsiveContainer` (e.g., `height={200}`) or ensure the parent div has an explicit height (e.g., `h-[200px]`).
+**Warning signs:** Chart not visible, 0-height container.
+
+### Pitfall 3: Chart Data with Zero-Weight Items
+**What goes wrong:** Items with `null` or `0` weight produce zero-size or NaN chart segments.
+**Why it happens:** Recharts renders slices proportional to `dataKey` values. Zero values create invisible or problematic slices.
+**How to avoid:** Filter out zero-weight entries before passing data to the chart. Show a "no weight data" placeholder if all items have null weight.
+**Warning signs:** Console warnings about NaN, invisible chart segments, misaligned tooltips.
+
+### Pitfall 4: Test Helper Must Match Schema
+**What goes wrong:** Tests fail because the in-memory DB schema in `tests/helpers/db.ts` doesn't include the new `classification` column.
+**Why it happens:** The test helper has hand-written CREATE TABLE statements that must be manually kept in sync with `src/db/schema.ts`.
+**How to avoid:** Update the test helper's `setup_items` CREATE TABLE to include `classification text NOT NULL DEFAULT 'base'` alongside updating the Drizzle schema.
+**Warning signs:** Tests failing with "no such column: classification" errors.
+
+### Pitfall 5: Classification Badge Click Propagates to ItemCard
+**What goes wrong:** Clicking the classification badge opens the item edit panel instead of cycling classification.
+**Why it happens:** ItemCard is a `<button>` element. Click events bubble up from the badge to the card.
+**How to avoid:** Call `e.stopPropagation()` on the classification badge click handler. This is the same pattern used by the remove button and product URL link on ItemCard.
+**Warning signs:** Edit panel opening when user tries to change classification.
+
+## Code Examples
+
+### Zod Schema for Classification
+
+```typescript
+// In src/shared/schemas.ts
+export const classificationSchema = z.enum(["base", "worn", "consumable"]);
+
+export const updateClassificationSchema = z.object({
+  classification: classificationSchema,
+});
+```
+
+### Service: Update Item Classification
+
+```typescript
+// In src/server/services/setup.service.ts
+export function updateItemClassification(
+  db: Db = prodDb,
+  setupId: number,
+  itemId: number,
+  classification: string,
+) {
+  return db
+    .update(setupItems)
+    .set({ classification })
+    .where(
+      sql`${setupItems.setupId} = ${setupId} AND ${setupItems.itemId} = ${itemId}`,
+    )
+    .run();
+}
+```
+
+### Service: syncSetupItems with Classification Preservation
+
+```typescript
+export function syncSetupItems(
+  db: Db = prodDb,
+  setupId: number,
+  itemIds: number[],
+) {
+  return db.transaction((tx) => {
+    // Save existing classifications before delete
+    const existing = tx
+      .select({
+        itemId: setupItems.itemId,
+        classification: setupItems.classification,
+      })
+      .from(setupItems)
+      .where(eq(setupItems.setupId, setupId))
+      .all();
+
+    const classificationMap = new Map(
+      existing.map((e) => [e.itemId, e.classification]),
+    );
+
+    // Delete all existing items for this setup
+    tx.delete(setupItems).where(eq(setupItems.setupId, setupId)).run();
+
+    // Re-insert with preserved classifications
+    for (const itemId of itemIds) {
+      tx.insert(setupItems)
+        .values({
+          setupId,
+          itemId,
+          classification: classificationMap.get(itemId) ?? "base",
+        })
+        .run();
+    }
+  });
+}
+```
+
+### Hook: useUpdateItemClassification
+
+```typescript
+// In src/client/hooks/useSetups.ts
+export function useUpdateItemClassification(setupId: number) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ itemId, classification }: { itemId: number; classification: string }) =>
+      apiPut<{ success: boolean }>(
+        `/api/setups/${setupId}/items/${itemId}/classification`,
+        { classification },
+      ),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["setups", setupId] });
+    },
+  });
+}
+```
+
+### Color Palette for Chart Segments
+
+```typescript
+// Category colors: distinguishable palette for up to 10 categories
+const CATEGORY_COLORS = [
+  "#6366f1", // indigo
+  "#f59e0b", // amber
+  "#10b981", // emerald
+  "#ef4444", // red
+  "#8b5cf6", // violet
+  "#06b6d4", // cyan
+  "#f97316", // orange
+  "#ec4899", // pink
+  "#14b8a6", // teal
+  "#84cc16", // lime
+];
+
+// Classification colors: 3 distinct colors matching the semantic meaning
+const CLASSIFICATION_COLORS = {
+  base: "#6366f1",       // indigo -- "foundation" feel
+  worn: "#f59e0b",       // amber -- "on your body" warmth
+  consumable: "#10b981", // emerald -- "used up" organic feel
+};
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Recharts `Cell` for per-slice colors | Still `Cell` in v3.x (deprecated for v4) | v3.0 deprecated, v4 removes | Use `Cell` now; plan to migrate to data-mapped colors when v4 drops |
+| Recharts v2 state management | Recharts v3 rewritten state | v3.0 (2024) | Better performance, fewer rendering bugs |
+| `activeShape` prop on Pie | `shape` prop with `isActive` callback | v3.0 | Use `shape` for custom active sectors if needed |
+
+**Deprecated/outdated:**
+- `Cell` component: Deprecated in v3, removed in v4. Still functional now. When v4 releases, migrate to `RechartsSymbols.fill` in data objects or `fillKey` prop.
+- `activeShape` / `inactiveShape` props on Pie: Deprecated in v3 in favor of unified `shape` prop.
+
+## Open Questions
+
+1. **Recharts bundle size impact**
+   - What we know: Recharts depends on D3 modules, adding ~50-80KB gzipped to the bundle
+   - What's unclear: Exact tree-shaking behavior with Vite and specific imports
+   - Recommendation: Import only needed components (`import { PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer } from "recharts"`) -- Vite will tree-shake unused parts
+
+2. **Chart animation performance**
+   - What we know: Recharts animations are CSS-based and generally smooth
+   - What's unclear: Whether toggling between category/classification views should animate the transition
+   - Recommendation: Enable default animation on initial render. For view toggles, let Recharts handle the re-render naturally (it will animate by default). If janky, set `isAnimationActive={false}`.
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test runner (built-in) |
+| Config file | None -- Bun test requires no config |
+| Quick run command | `bun test tests/services/setup.service.test.ts` |
+| Full suite command | `bun test` |
+
+### Phase Requirements -> Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| CLAS-01 | Update item classification in setup | unit | `bun test tests/services/setup.service.test.ts -t "updateItemClassification"` | Needs new tests |
+| CLAS-02 | Get setup with classification subtotals | unit | `bun test tests/services/setup.service.test.ts -t "classification"` | Needs new tests |
+| CLAS-03 | Default classification is "base" | unit | `bun test tests/services/setup.service.test.ts -t "default"` | Needs new tests |
+| CLAS-04 | Different classifications in different setups | unit | `bun test tests/services/setup.service.test.ts -t "different setups"` | Needs new tests |
+| VIZZ-01 | Donut chart renders with category data | manual-only | N/A -- visual rendering | N/A |
+| VIZZ-02 | Toggle switches chart data source | manual-only | N/A -- UI interaction | N/A |
+| VIZZ-03 | Hover tooltip shows name/weight/percentage | manual-only | N/A -- hover behavior | N/A |
+| CLAS-01 | Classification PATCH route | integration | `bun test tests/routes/setups.test.ts -t "classification"` | Needs new tests |
+| CLAS-03 | syncSetupItems preserves classification | unit | `bun test tests/services/setup.service.test.ts -t "preserves classification"` | Needs new tests |
+
+### Sampling Rate
+- **Per task commit:** `bun test tests/services/setup.service.test.ts && bun test tests/routes/setups.test.ts`
+- **Per wave merge:** `bun test`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] `tests/services/setup.service.test.ts` -- add tests for `updateItemClassification`, classification preservation in `syncSetupItems`, classification defaults, and different-setup classification
+- [ ] `tests/routes/setups.test.ts` -- add test for `PATCH /:id/items/:itemId/classification` route
+- [ ] `tests/helpers/db.ts` -- update `setup_items` CREATE TABLE to include `classification text NOT NULL DEFAULT 'base'`
+
+## Sources
+
+### Primary (HIGH confidence)
+- [Recharts API docs - Pie](https://recharts.github.io/en-US/api/Pie) - innerRadius, outerRadius, dataKey, Cell usage
+- [Recharts API docs - Tooltip](https://recharts.github.io/en-US/api/Tooltip/) - custom content, formatter, active/payload
+- [Recharts API docs - Cell (deprecation notice)](https://recharts.github.io/en-US/api/Cell/) - deprecated in v3, removed in v4
+- [Recharts npm](https://www.npmjs.com/package/recharts) - v3.8.0 latest, MIT license
+- Existing codebase: `src/db/schema.ts`, `src/server/services/setup.service.ts`, `src/client/components/StatusBadge.tsx`, `src/client/components/TotalsBar.tsx`
+
+### Secondary (MEDIUM confidence)
+- [Recharts Cell Discussion #5474](https://github.com/recharts/recharts/discussions/5474) - Cell replacement patterns
+- [GeeksforGeeks Donut Chart Tutorial](https://www.geeksforgeeks.org/reactjs/create-a-donut-chart-using-recharts-in-reactjs/) - donut chart pattern
+- [Recharts Label in center of PieChart #191](https://github.com/recharts/recharts/issues/191) - center label patterns
+- [Recharts 3.0 Migration Guide](https://github.com/recharts/recharts/wiki/3.0-migration-guide) - v3 breaking changes
+
+### Tertiary (LOW confidence)
+- None
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH - Recharts is the user's locked decision, v3.8.0 is current, API is well-documented
+- Architecture: HIGH - Classification column pattern mirrors the Phase 8 status column migration exactly; all code patterns verified against existing codebase
+- Pitfalls: HIGH - syncSetupItems preservation is the main risk; verified by reading the actual delete-all + re-insert code; other pitfalls are standard React/Recharts issues
+
+**Research date:** 2026-03-16
+**Valid until:** 2026-04-16 (Recharts v3 is stable; v4 with Cell removal is not imminent)

.planning/phases/09-weight-classification-and-visualization/09-VALIDATION.md

@@ -0,0 +1,82 @@
+---
+phase: 9
+slug: weight-classification-and-visualization
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-16
+---
+
+# Phase 9 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bun test runner |
+| **Config file** | none — existing infrastructure |
+| **Quick run command** | `bun test` |
+| **Full suite command** | `bun test` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun test`
+- **After every plan wave:** Run `bun test`
+- **Before `/gsd:verify-work`:** Full suite must be green
+- **Max feedback latency:** 5 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 09-01-01 | 01 | 1 | CLAS-01, CLAS-04 | unit | `bun test tests/services/setup.service.test.ts` | ❌ W0 | ⬜ pending |
+| 09-01-02 | 01 | 1 | CLAS-03 | unit | `bun test tests/services/setup.service.test.ts` | ❌ W0 | ⬜ pending |
+| 09-01-03 | 01 | 1 | CLAS-01 | route | `bun test tests/routes/setups.test.ts` | ❌ W0 | ⬜ pending |
+| 09-02-01 | 02 | 2 | CLAS-02 | unit | `bun test tests/services/setup.service.test.ts` | ❌ W0 | ⬜ pending |
+| 09-02-02 | 02 | 2 | VIZZ-01, VIZZ-02, VIZZ-03 | manual | N/A — visual component | N/A | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `tests/services/setup.service.test.ts` — classification CRUD tests (service layer)
+- [ ] `tests/routes/setups.test.ts` — classification API endpoint tests
+- [ ] `tests/helpers/db.ts` — update CREATE TABLE for setup_items to include classification column
+
+*Existing test infrastructure covers framework setup. Wave 0 adds phase-specific test files.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Classification badge click-to-cycle | CLAS-01 | UI interaction, React component | Click badge on item card in setup, verify it cycles base→worn→consumable→base |
+| Summary card weight subtotals | CLAS-02 | Visual layout verification | Add items to setup, classify some as worn/consumable, verify subtotals update |
+| Donut chart renders with segments | VIZZ-01 | Recharts canvas/SVG rendering | Open setup with items, verify donut chart shows colored segments |
+| Chart toggle category/classification | VIZZ-02 | UI interaction | Click pill toggle, verify chart segments change between category and classification views |
+| Chart hover tooltips | VIZZ-03 | Hover interaction | Hover over donut segments, verify tooltip shows name, weight, percentage |
+
+---
+
+## 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 < 5s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/09-weight-classification-and-visualization/09-VERIFICATION.md

@@ -0,0 +1,158 @@
+---
+phase: 09-weight-classification-and-visualization
+verified: 2026-03-16T15:00:00Z
+status: passed
+score: 9/9 must-haves verified
+re_verification: false
+---
+
+# Phase 9: Weight Classification and Visualization Verification Report
+
+**Phase Goal:** Users can classify gear by role and visualize weight distribution in setups
+**Verified:** 2026-03-16T15:00:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| #  | Truth                                                                                                               | Status     | Evidence                                                                                       |
+|----|---------------------------------------------------------------------------------------------------------------------|------------|-----------------------------------------------------------------------------------------------|
+| 1  | User can click a classification badge on any item card within a setup and it cycles through base weight, worn, consumable | VERIFIED | ClassificationBadge renders in $setupId.tsx per item; nextClassification cycles the three values; useUpdateItemClassification mutation fires PATCH call |
+| 2  | Items default to base weight classification when added to a setup                                                   | VERIFIED   | schema.ts: `classification text NOT NULL DEFAULT 'base'`; syncSetupItems uses `classificationMap.get(itemId) ?? "base"` |
+| 3  | Same item in different setups can have different classifications                                                     | VERIFIED   | Classification stored on setupItems join table (not items); test confirmed in setup.service.test.ts |
+| 4  | Classifications persist after adding/removing other items from the setup (syncSetupItems preserves them)            | VERIFIED   | syncSetupItems reads Map<itemId, classification> before delete, restores after re-insert; 2 tests confirm |
+| 5  | Setup detail view shows separate weight subtotals for base weight, worn weight, consumable weight, and total        | VERIFIED   | WeightSummaryCard computes baseWeight/wornWeight/consumableWeight/totalWeight and renders 4 SubtotalColumn components |
+| 6  | User can view a donut chart showing weight distribution by category in the setup                                    | VERIFIED   | WeightSummaryCard uses Recharts PieChart+Pie with innerRadius=55/outerRadius=80; default viewMode="category" |
+| 7  | User can toggle the chart between category breakdown and classification breakdown via pill toggle                   | VERIFIED   | Pill toggle button array maps over VIEW_MODES ["category","classification"]; state switches chartData source |
+| 8  | Hovering a chart segment shows category/classification name, weight in selected unit, and percentage                | VERIFIED   | CustomTooltip renders name, formatWeight(weight, unit), (percent*100).toFixed(1)% |
+| 9  | Total weight displayed in the center of the donut hole                                                              | VERIFIED   | `<Label value={formatWeight(totalWeight, unit)} position="center" .../>` inside Pie |
+
+**Score:** 9/9 truths verified
+
+---
+
+### Required Artifacts
+
+#### Plan 01 Artifacts
+
+| Artifact | Expected | Status | Details |
+|---|---|---|---|
+| `src/db/schema.ts` | classification column on setupItems table | VERIFIED | `classification: text("classification").notNull().default("base")` at line 89 |
+| `src/shared/schemas.ts` | classificationSchema Zod enum and updateClassificationSchema | VERIFIED | Both exported at lines 78-82 |
+| `src/server/services/setup.service.ts` | updateItemClassification, classification-preserving syncSetupItems, classification field in getSetupWithItems | VERIFIED | All three implemented; syncSetupItems uses Map pattern; getSetupWithItems selects `classification: setupItems.classification` |
+| `src/server/routes/setups.ts` | PATCH /:id/items/:itemId/classification endpoint | VERIFIED | app.patch("/:id/items/:itemId/classification", ...) at line 78 with Zod validation and service call |
+| `src/client/components/ClassificationBadge.tsx` | Click-to-cycle classification badge component (min 30 lines) | VERIFIED | 30 lines; button with stopPropagation + onCycle; CLASSIFICATION_LABELS map |
+| `src/client/routes/setups/$setupId.tsx` | ClassificationBadge wired into item cards in setup view | VERIFIED | Imported and rendered per item inside `{categoryItems.map(...)}` with nextClassification helper |
+| `tests/services/setup.service.test.ts` | Tests for updateItemClassification, classification preservation, defaults | VERIFIED | 5 new tests: default "base", preservation on sync, new items default, cross-setup independence, classification update |
+| `tests/routes/setups.test.ts` | Integration test for PATCH classification route | VERIFIED | 2 new tests: valid PATCH updates+persists, invalid value returns 400 |
+
+#### Plan 02 Artifacts
+
+| Artifact | Expected | Status | Details |
+|---|---|---|---|
+| `src/client/components/WeightSummaryCard.tsx` | Summary card with weight subtotals, donut chart, pill toggle, and tooltips (min 100 lines) | VERIFIED | 265 lines; all four features present |
+| `src/client/routes/setups/$setupId.tsx` | WeightSummaryCard rendered below sticky bar when setup has items | VERIFIED | `<WeightSummaryCard items={setup.items} />` inside `{itemCount > 0 && (...)}` block at line 196 |
+| `package.json` | recharts dependency installed | VERIFIED | `"recharts": "^3.8.0"` at line 43 |
+
+---
+
+### Key Link Verification
+
+#### Plan 01 Key Links
+
+| From | To | Via | Status | Details |
+|---|---|---|---|---|
+| `ClassificationBadge.tsx` | `/api/setups/:id/items/:itemId/classification` | useUpdateItemClassification mutation hook (apiPatch) | VERIFIED | useSetups.ts exports useUpdateItemClassification which calls `apiPatch(.../classification, ...)`; $setupId.tsx imports and calls it |
+| `src/server/routes/setups.ts` | `src/server/services/setup.service.ts` | updateItemClassification service call | VERIFIED | Routes imports updateItemClassification from service; calls it in PATCH handler |
+| `src/server/services/setup.service.ts` | `src/db/schema.ts` | setupItems.classification column | VERIFIED | service.ts uses `setupItems.classification` in select (line 56) and `set({ classification })` in update (line 143) |
+| `src/client/routes/setups/$setupId.tsx` | `src/client/components/ClassificationBadge.tsx` | ClassificationBadge rendered on each ItemCard | VERIFIED | Imported at line 4; rendered inside item map at lines 235-245 |
+
+#### Plan 02 Key Links
+
+| From | To | Via | Status | Details |
+|---|---|---|---|---|
+| `WeightSummaryCard.tsx` | recharts | PieChart, Pie, Cell, Tooltip, Label, ResponsiveContainer imports | VERIFIED | All six named imports from "recharts" at lines 2-9 |
+| `WeightSummaryCard.tsx` | `src/client/lib/formatters.ts` | formatWeight for subtotals and tooltip display | VERIFIED | `formatWeight` imported at line 12; used in SubtotalColumn, CustomTooltip, and center Label |
+| `src/client/routes/setups/$setupId.tsx` | `WeightSummaryCard.tsx` | WeightSummaryCard rendered with setup.items prop | VERIFIED | Imported at line 7; rendered as `<WeightSummaryCard items={setup.items} />` at line 196 |
+
+---
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|---|---|---|---|---|
+| CLAS-01 | 09-01 | User can classify each item within a setup as base weight, worn, or consumable | SATISFIED | ClassificationBadge + PATCH endpoint + updateItemClassification service all wired and tested |
+| CLAS-02 | 09-02 | Setup totals display base weight, worn weight, consumable weight, and total separately | SATISFIED | WeightSummaryCard renders 4 SubtotalColumn components with computed weights |
+| CLAS-03 | 09-01 | Items default to "base weight" classification when added to a setup | SATISFIED | DB default "base" + syncSetupItems fallback + test confirms default |
+| CLAS-04 | 09-01 | Same item can have different classifications in different setups | SATISFIED | Classification on join table; cross-setup test passes |
+| VIZZ-01 | 09-02 | User can view a donut chart showing weight distribution by category in a setup | SATISFIED | Recharts PieChart with buildCategoryChartData, default viewMode="category" |
+| VIZZ-02 | 09-02 | User can toggle chart between category view and classification view | SATISFIED | Pill toggle with VIEW_MODES array, setViewMode state updates chartData source |
+| VIZZ-03 | 09-02 | User can hover chart segments to see category name, weight, and percentage | SATISFIED | CustomTooltip renders all three fields; passed to PieChart as `content` prop |
+
+No orphaned requirements — all 7 IDs declared in plan frontmatter and accounted for.
+
+---
+
+### Anti-Patterns Found
+
+No blockers or warnings found in modified files. The only `return null` instance is a standard React guard clause in CustomTooltip (not a stub).
+
+---
+
+### Human Verification Required
+
+The following items cannot be verified programmatically and require a running browser session:
+
+#### 1. Click-to-cycle badge interaction and stopPropagation
+
+**Test:** Open a setup with items. Click a classification badge on one item card.
+**Expected:** Badge label cycles Base Weight -> Worn -> Consumable -> Base Weight. The item edit panel does NOT open when clicking the badge.
+**Why human:** stopPropagation correctness and visual badge state update require browser execution.
+
+#### 2. Donut chart renders with correct segment proportions
+
+**Test:** Add items with different categories and weights to a setup. View the setup detail page.
+**Expected:** Donut chart segments are proportional to weight distribution. Total weight appears in the center hole.
+**Why human:** Chart rendering requires browser + Recharts layout.
+
+#### 3. Pill toggle switches chart data
+
+**Test:** Click the "Classification" pill on the WeightSummaryCard.
+**Expected:** Chart segments change from category-based colors to indigo/amber/emerald for base/worn/consumable. Tooltips show "Base Weight", "Worn", or "Consumable" labels.
+**Why human:** Visual and interactive behavior requires browser.
+
+#### 4. Tooltip on hover
+
+**Test:** Hover over a chart segment.
+**Expected:** Tooltip appears with segment name, formatted weight in the selected unit, and percentage.
+**Why human:** Hover state requires browser interaction.
+
+#### 5. Weight unit propagation
+
+**Test:** Toggle the weight unit in the top bar (g / oz / lb / kg). Observe WeightSummaryCard.
+**Expected:** All four subtotal columns and the donut center label update to the selected unit.
+**Why human:** useWeightUnit hook behavior and re-render requires browser.
+
+---
+
+### Test Suite Results
+
+All 121 tests pass across 10 files (32 setup-specific tests across services and routes).
+
+- `tests/services/setup.service.test.ts` — 5 new classification tests pass (default "base", preservation, new item default, cross-setup independence, update from base to worn)
+- `tests/routes/setups.test.ts` — 2 new PATCH classification tests pass (valid update + 400 for invalid value)
+
+---
+
+### Summary
+
+Phase 9 goal is fully achieved. All 9 observable truths are verified against the actual codebase — no stubs, no orphaned artifacts, no broken links. The complete vertical slice from DB schema to UI component is wired and exercised by 7 automated tests. Human verification is needed only for visual/interactive browser behaviors (chart rendering, hover tooltips, click cycling), which are structurally sound in the code.
+
+---
+
+_Verified: 2026-03-16T15:00:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/research/ARCHITECTURE.md

@@ -1,362 +1,677 @@
 # Architecture Research
 
-**Domain:** Single-user gear management and purchase planning web app
-**Researched:** 2026-03-14
+**Domain:** Gear management app -- v1.2 feature integration (search/filter, weight classification, weight distribution charts, candidate status tracking, weight unit selection)
+**Researched:** 2026-03-16
 **Confidence:** HIGH
 
-## Standard Architecture
+## System Overview: Integration Map
 
-### System Overview
+The v1.2 features integrate across all existing layers. This diagram shows where new components slot in relative to the current architecture.
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Client (Browser)                         │
-│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐   │
-│  │ Dashboard  │  │Collection │  │  Threads  │  │  Setups   │   │
-│  │   Page     │  │   Page    │  │   Page    │  │   Page    │   │
-│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘   │
-│        │              │              │              │           │
-│  ┌─────┴──────────────┴──────────────┴──────────────┴─────┐    │
-│  │              Shared UI Components                       │    │
-│  │  (ItemCard, ComparisonTable, WeightBadge, CostBadge)    │    │
-│  └────────────────────────┬───────────────────────────────┘    │
-│                           │ fetch()                            │
-├───────────────────────────┼────────────────────────────────────┤
-│                    Bun.serve()                                  │
-│  ┌────────────────────────┴───────────────────────────────┐    │
-│  │                   API Routes Layer                      │    │
-│  │   /api/items    /api/threads    /api/setups             │    │
-│  │   /api/stats    /api/candidates /api/images             │    │
-│  └────────────────────────┬───────────────────────────────┘    │
-│                           │                                    │
-│  ┌────────────────────────┴───────────────────────────────┐    │
-│  │                  Service Layer                          │    │
-│  │   ItemService  ThreadService  SetupService  StatsService│    │
-│  └────────────────────────┬───────────────────────────────┘    │
-│                           │                                    │
-│  ┌────────────────────────┴───────────────────────────────┐    │
-│  │               Data Access (Drizzle ORM)                 │    │
-│  │                    Schema + Queries                     │    │
-│  └────────────────────────┬───────────────────────────────┘    │
-│                           │                                    │
-│  ┌────────────────────────┴───────────────────────────────┐    │
-│  │                  SQLite (bun:sqlite)                    │    │
-│  │                   gearbox.db file                       │    │
-│  └────────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────────┘
+CLIENT LAYER
++-----------------------------------------------------------------+
+|  Routes                                                         |
+|  +------------+  +------------+  +------------+                 |
+|  | /collection|  | /threads/$ |  | /setups/$  |                 |
+|  | [MODIFIED] |  | [MODIFIED] |  | [MODIFIED] |                 |
+|  +------+-----+  +------+-----+  +------+-----+                |
+|         |               |               |                       |
+|  Components (NEW)                                               |
+|  +------------+  +--------------+  +-------------+              |
+|  | SearchBar  |  | WeightChart  |  | UnitSelector|              |
+|  +------------+  +--------------+  +-------------+              |
+|                                                                 |
+|  Components (MODIFIED)                                          |
+|  +------------+  +--------------+  +-------------+              |
+|  | ItemCard   |  | CandidateCard|  | TotalsBar   |              |
+|  | ItemForm   |  | CandidateForm|  | CategoryHdr |              |
+|  +------------+  +--------------+  +-------------+              |
+|                                                                 |
+|  Hooks (NEW)              Hooks (MODIFIED)                      |
+|  +------------------+     +------------------+                  |
+|  | useFormatWeight  |     | useSetups        |                  |
+|  +------------------+     | useThreads       |                  |
+|                           +------------------+                  |
+|                                                                 |
+|  Lib (MODIFIED)           Stores (NO CHANGE)                    |
+|  +------------------+     +------------------+                  |
+|  | formatters.ts    |     | uiStore.ts       |                  |
+|  +------------------+     +------------------+                  |
++-----------------------------------------------------------------+
+|  API Layer: lib/api.ts -- NO CHANGE                             |
++-----------------------------------------------------------------+
+SERVER LAYER
+|  Routes (MODIFIED)                                              |
+|  +------------+  +------------+  +------------+                 |
+|  | items.ts   |  | threads.ts |  | setups.ts  |                 |
+|  | (no change)|  | (no change)|  | +PATCH item|                 |
+|  +------+-----+  +------+-----+  +------+-----+                |
+|         |               |               |                       |
+|  Services (MODIFIED)                                            |
+|  +------------+  +--------------+  +--------------+             |
+|  | item.svc   |  | thread.svc   |  | setup.svc    |             |
+|  | (no change)|  | +cand.status  |  | +weightClass  |             |
+|  +------+-----+  +------+-------+  +------+-------+             |
++---------+----------------+----------------+---------------------+
+DATABASE LAYER
+|  schema.ts (MODIFIED)                                           |
+|  +----------------------------------------------------------+  |
+|  | setup_items: +weight_class TEXT DEFAULT 'base'            |  |
+|  | thread_candidates: +status TEXT DEFAULT 'researching'     |  |
+|  | settings: weightUnit row (uses existing key-value table)  |  |
+|  +----------------------------------------------------------+  |
+|                                                                 |
+|  tests/helpers/db.ts (MODIFIED -- add new columns)             |
++-----------------------------------------------------------------+
 ```
 
-This is a monolithic full-stack app running on a single Bun process. No microservices, no separate API server, no Docker. Bun's built-in fullstack dev server handles both static asset bundling and API routes from a single `Bun.serve()` call. SQLite is the database -- embedded, zero-config, accessed through Bun's native `bun:sqlite` module (3-6x faster than better-sqlite3).
+## Feature-by-Feature Integration
 
-### Component Responsibilities
+### Feature 1: Search Items and Filter by Category
 
-| Component | Responsibility | Typical Implementation |
-|-----------|----------------|------------------------|
-| Dashboard Page | Entry point, summary cards, navigation | React page showing item count, active threads, setup stats |
-| Collection Page | CRUD for gear items, filtering, sorting | React page with list/grid views, item detail modal |
-| Threads Page | Purchase research threads with candidates | React page with thread list, candidate comparison view |
-| Setups Page | Compose named setups from collection items | React page with drag/drop or select-to-add from collection |
-| API Routes | HTTP endpoints for all data operations | Bun.serve() route handlers, REST-style |
-| Service Layer | Business logic, calculations (weight/cost totals) | TypeScript modules with domain logic |
-| Data Access | Schema definition, queries, migrations | Drizzle ORM with SQLite dialect |
-| SQLite DB | Persistent storage | Single file, bun:sqlite native module |
-| Image Storage | Photo uploads for gear items | Local filesystem (`./uploads/`) served as static files |
+**Scope:** Client-side filtering of already-fetched data. No server changes needed -- the collection is small enough (single user) that client-side filtering is both simpler and faster.
 
-## Recommended Project Structure
+**Integration points:**
+
+| Layer | File | Change Type | Details |
+|-------|------|-------------|---------|
+| Client | `routes/collection/index.tsx` | MODIFY | Add search input and category filter dropdown above the gear grid in `CollectionView` |
+| Client | NEW `components/SearchBar.tsx` | NEW | Reusable search input component with clear button |
+| Client | `hooks/useItems.ts` | NO CHANGE | Already returns all items; filtering happens in the route |
+
+**Data flow:**
 
 ```
-src/
-├── index.tsx              # Bun.serve() entry point, route registration
-├── pages/                 # HTML entrypoints for each page
-│   ├── index.html         # Dashboard
-│   ├── collection.html    # Collection page
-│   ├── threads.html       # Planning threads page
-│   └── setups.html        # Setups page
-├── client/                # React frontend code
-│   ├── components/        # Shared UI components
-│   │   ├── ItemCard.tsx
-│   │   ├── WeightBadge.tsx
-│   │   ├── CostBadge.tsx
-│   │   ├── ComparisonTable.tsx
-│   │   ├── StatusBadge.tsx
-│   │   └── Layout.tsx
-│   ├── pages/             # Page-level React components
-│   │   ├── Dashboard.tsx
-│   │   ├── Collection.tsx
-│   │   ├── ThreadList.tsx
-│   │   ├── ThreadDetail.tsx
-│   │   ├── SetupList.tsx
-│   │   └── SetupDetail.tsx
-│   ├── hooks/             # Custom React hooks
-│   │   ├── useItems.ts
-│   │   ├── useThreads.ts
-│   │   └── useSetups.ts
-│   └── lib/               # Client utilities
-│       ├── api.ts         # Fetch wrapper for API calls
-│       └── formatters.ts  # Weight/cost formatting helpers
-├── server/                # Backend code
-│   ├── routes/            # API route handlers
-│   │   ├── items.ts
-│   │   ├── threads.ts
-│   │   ├── candidates.ts
-│   │   ├── setups.ts
-│   │   ├── images.ts
-│   │   └── stats.ts
-│   └── services/          # Business logic
-│       ├── item.service.ts
-│       ├── thread.service.ts
-│       ├── setup.service.ts
-│       └── stats.service.ts
-├── db/                    # Database layer
-│   ├── schema.ts          # Drizzle table definitions
-│   ├── index.ts           # Database connection singleton
-│   ├── seed.ts            # Optional dev seed data
-│   └── migrations/        # Drizzle Kit generated migrations
-├── shared/                # Types shared between client and server
-│   └── types.ts           # Item, Thread, Candidate, Setup types
-uploads/                   # Gear photos (gitignored, outside src/)
-drizzle.config.ts          # Drizzle Kit config
+CollectionView (owns search/filter state via useState)
+    |
+    +-- SearchBar (controlled input, calls setSearchTerm)
+    +-- CategoryFilter (dropdown from useCategories, calls setCategoryFilter)
+    |
+    +-- Items = useItems().data
+        .filter(item => matchesSearch(item.name, searchTerm))
+        .filter(item => !categoryFilter || item.categoryId === categoryFilter)
+        |
+        +-- Grouped by category -> rendered as before
 ```
 
-### Structure Rationale
+**Why client-side:** The `useItems()` hook already fetches all items. For a single-user app, even 500 items is trivially fast to filter in memory. Adding server-side search would mean new API parameters, new query logic, and pagination -- all unnecessary complexity. If the collection grows beyond ~2000 items someday, server-side search can be added to the existing `getAllItems` service function by accepting optional `search` and `categoryId` parameters and adding Drizzle `like()` + `eq()` conditions.
 
-- **`client/` and `server/` separation:** Clear boundary between browser code and server code. Both import from `shared/` and `db/` (server only) but never from each other.
-- **`pages/` HTML entrypoints:** Bun's fullstack server uses HTML files as route entrypoints. Each HTML file imports its corresponding React component tree.
-- **`server/routes/` + `server/services/`:** Routes handle HTTP concerns (parsing params, status codes). Services handle business logic (calculating totals, validating state transitions). This prevents bloated route handlers.
-- **`db/schema.ts` as single source of truth:** All table definitions in one file. Drizzle infers TypeScript types from the schema, so types flow from DB to API to client.
-- **`shared/types.ts`:** API response types and domain enums shared between client and server. Avoids type drift.
-- **`uploads/` outside `src/`:** User-uploaded images are not source code. Served as static files by Bun.
+**Pattern -- filtered items with useMemo:**
 
-## Architectural Patterns
-
-### Pattern 1: Bun Fullstack Monolith
-
-**What:** Single Bun.serve() process serves HTML pages, bundled React assets, and API routes. No separate frontend dev server, no proxy config, no CORS.
-**When to use:** Single-user apps, prototypes, small team projects where deployment simplicity matters.
-**Trade-offs:** Extremely simple to deploy (one process, one command), but no horizontal scaling. For GearBox this is ideal -- single user, no scaling needed.
-
-**Example:**
 ```typescript
-// src/index.tsx
-import homepage from "./pages/index.html";
-import collectionPage from "./pages/collection.html";
-import { itemRoutes } from "./server/routes/items";
-import { threadRoutes } from "./server/routes/threads";
+// In CollectionView component
+const [searchTerm, setSearchTerm] = useState("");
+const [categoryFilter, setCategoryFilter] = useState<number | null>(null);
 
-Bun.serve({
-  routes: {
-    "/": homepage,
-    "/collection": collectionPage,
-    ...itemRoutes,
-    ...threadRoutes,
-  },
-  development: true,
-});
+const filteredItems = useMemo(() => {
+  if (!items) return [];
+  return items
+    .filter(item => {
+      if (!searchTerm) return true;
+      return item.name.toLowerCase().includes(searchTerm.toLowerCase());
+    })
+    .filter(item => {
+      if (!categoryFilter) return true;
+      return item.categoryId === categoryFilter;
+    });
+}, [items, searchTerm, categoryFilter]);
 ```
 
-### Pattern 2: Service Layer for Business Logic
+No debounce library needed -- `useMemo` re-computes on keystroke, and filtering an in-memory array of <1000 items is sub-millisecond. Debounce is only needed if triggering API calls.
 
-**What:** Route handlers delegate to service modules that contain domain logic. Services are pure functions or classes that take data in and return results, with no HTTP awareness.
-**When to use:** When routes would otherwise contain calculation logic (weight totals, cost impact analysis, status transitions).
-**Trade-offs:** Slightly more files, but logic is testable without HTTP mocking and reusable across routes.
+**The category filter already exists** in `PlanningView` (lines 191-209 and 277-290 in `collection/index.tsx`). The same pattern should be reused for the gear tab with an icon-aware dropdown replacing the plain `<select>`. The existing `useCategories` hook provides the category list.
+
+**Planning category filter upgrade:** The current plain `<select>` in PlanningView should be upgraded to an icon-aware dropdown that shows Lucide icons next to category names. This is a shared component that both the gear tab filter and the planning tab filter can use.
+
+---
+
+### Feature 2: Weight Classification (Base / Worn / Consumable)
+
+**Scope:** Per-item-per-setup classification. An item's classification depends on the setup context (a rain jacket might be "worn" in one setup and "base" in another). This means the classification lives on the `setup_items` join table, not on the `items` table.
+
+**Integration points:**
+
+| Layer | File | Change Type | Details |
+|-------|------|-------------|---------|
+| DB | `schema.ts` | MODIFY | Add `weightClass` column to `setup_items` |
+| DB | Drizzle migration | NEW | `ALTER TABLE setup_items ADD COLUMN weight_class TEXT NOT NULL DEFAULT 'base'` |
+| Shared | `schemas.ts` | MODIFY | Add `weightClass` to sync schema, add update schema |
+| Shared | `types.ts` | NO CHANGE | Types auto-infer from Drizzle schema |
+| Server | `setup.service.ts` | MODIFY | `getSetupWithItems` returns `weightClass`; add `updateSetupItemClass` function |
+| Server | `routes/setups.ts` | MODIFY | Add `PATCH /:id/items/:itemId` for classification update |
+| Client | `hooks/useSetups.ts` | MODIFY | `SetupItemWithCategory` type adds `weightClass`; add `useUpdateSetupItemClass` mutation |
+| Client | `routes/setups/$setupId.tsx` | MODIFY | Show classification badges, add toggle UI, compute classification totals |
+| Client | `components/ItemCard.tsx` | MODIFY | Accept optional `weightClass` prop for setup context |
+| Test | `tests/helpers/db.ts` | MODIFY | Add `weight_class` column to `setup_items` CREATE TABLE |
+
+**Schema change:**
 
-**Example:**
 ```typescript
-// server/services/setup.service.ts
-export function calculateSetupTotals(items: Item[]): SetupTotals {
-  return {
-    totalWeight: items.reduce((sum, i) => sum + (i.weightGrams ?? 0), 0),
-    totalCost: items.reduce((sum, i) => sum + (i.priceCents ?? 0), 0),
-    itemCount: items.length,
-  };
-}
-
-export function computeCandidateImpact(
-  setup: Setup,
-  candidate: Candidate
-): Impact {
-  const currentTotals = calculateSetupTotals(setup.items);
-  return {
-    weightDelta: (candidate.weightGrams ?? 0) - (setup.replacingItem?.weightGrams ?? 0),
-    costDelta: (candidate.priceCents ?? 0) - (setup.replacingItem?.priceCents ?? 0),
-    newTotalWeight: currentTotals.totalWeight + this.weightDelta,
-    newTotalCost: currentTotals.totalCost + this.costDelta,
-  };
-}
-```
-
-### Pattern 3: Drizzle ORM with bun:sqlite
-
-**What:** Drizzle provides type-safe SQL query building and schema-as-code migrations on top of Bun's native SQLite. Schema definitions double as TypeScript type sources.
-**When to use:** Any Bun + SQLite project that wants type safety without the overhead of a full ORM like Prisma.
-**Trade-offs:** Lightweight (no query engine, no runtime overhead). SQL-first philosophy means you write SQL-like code, not abstract methods. Migration tooling via Drizzle Kit is solid but simpler than Prisma Migrate.
-
-**Example:**
-```typescript
-// db/schema.ts
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
-
-export const items = sqliteTable("items", {
+// In schema.ts -- setup_items table
+export const setupItems = sqliteTable("setup_items", {
   id: integer("id").primaryKey({ autoIncrement: true }),
-  name: text("name").notNull(),
-  category: text("category"),
-  weightGrams: integer("weight_grams"),
-  priceCents: integer("price_cents"),
-  purchaseSource: text("purchase_source"),
-  productUrl: text("product_url"),
-  notes: text("notes"),
-  imageFilename: text("image_filename"),
-  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+  setupId: integer("setup_id")
+    .notNull()
+    .references(() => setups.id, { onDelete: "cascade" }),
+  itemId: integer("item_id")
+    .notNull()
+    .references(() => items.id, { onDelete: "cascade" }),
+  weightClass: text("weight_class").notNull().default("base"),
+  // Values: "base" | "worn" | "consumable"
 });
 ```
 
-## Data Flow
+**Why on setup_items, not items:** LighterPack and all serious gear tracking tools classify items per-loadout. A sleeping bag is "base weight" in a backpacking setup but might not be in a day hike setup. The same pair of hiking boots is "worn weight" in every setup, but this is a user choice per context. Storing on the join table preserves this flexibility at zero additional complexity -- the `setup_items` table already exists.
 
-### Request Flow
+**New endpoint for classification update:**
 
-```
-[User clicks "Add Item"]
-    |
-[React component] --> fetch("/api/items", { method: "POST", body })
-    |
-[Bun.serve route handler] --> validates input, calls service
-    |
-[ItemService.create()] --> business logic, defaults
-    |
-[Drizzle ORM] --> db.insert(items).values(...)
-    |
-[bun:sqlite] --> writes to gearbox.db
-    |
-[Response] <-- { id, name, ... } JSON <-- 201 Created
-    |
-[React state update] --> re-renders item list
+The existing sync pattern (delete-all + re-insert) would destroy classification data on every item add/remove. Instead, add a targeted update endpoint:
+
+```typescript
+// In setup.service.ts
+export function updateSetupItemClass(
+  db: Db,
+  setupId: number,
+  itemId: number,
+  weightClass: "base" | "worn" | "consumable",
+) {
+  return db
+    .update(setupItems)
+    .set({ weightClass })
+    .where(
+      sql`${setupItems.setupId} = ${setupId} AND ${setupItems.itemId} = ${itemId}`,
+    )
+    .run();
+}
 ```
 
-### Key Data Flows
-
-1. **Collection CRUD:** Straightforward REST. Client sends item data, server validates, persists, returns updated item. Client hooks (useItems) manage local state.
-
-2. **Thread lifecycle:** Create thread -> Add candidates -> Compare -> Resolve (pick winner). Resolution triggers: candidate becomes a collection item, thread status changes to "resolved", other candidates marked as rejected. This is the most stateful flow.
-
-3. **Setup composition:** User selects items from collection to add to a named setup. Server calculates aggregate weight/cost. When viewing a thread candidate, "impact on setup" is computed by comparing candidate against current setup totals (or against a specific item being replaced).
-
-4. **Dashboard aggregation:** Dashboard fetches summary stats via `/api/stats` -- total items, total collection value, active threads count, setup count. This is a read-only aggregation endpoint, not a separate data store.
-
-5. **Image upload:** Multipart form upload to `/api/images`, saved to `./uploads/` with a UUID filename. The filename is stored on the item record. Images served as static files.
-
-### Data Model Relationships
-
-```
-items (gear collection)
-  |
-  |-- 1:N --> setup_items (junction) <-- N:1 -- setups
-  |
-  |-- 1:N --> thread_candidates (when resolved, candidate -> item)
-
-threads (planning threads)
-  |
-  |-- 1:N --> candidates (potential purchases)
-                |-- status: researching | ordered | arrived
-                |-- resolved_as: winner | rejected | null
-
-setups
-  |
-  |-- N:M --> items (via setup_items junction table)
+```typescript
+// In routes/setups.ts -- new PATCH route
+app.patch("/:setupId/items/:itemId", zValidator("json", updateSetupItemClassSchema), (c) => {
+  const db = c.get("db");
+  const setupId = Number(c.req.param("setupId"));
+  const itemId = Number(c.req.param("itemId"));
+  const { weightClass } = c.req.valid("json");
+  updateSetupItemClass(db, setupId, itemId, weightClass);
+  return c.json({ success: true });
+});
 ```
 
-### State Management
+**Also update syncSetupItems** to preserve existing classifications or accept them:
 
-No global state library needed. React hooks + fetch are sufficient for a single-user app with this complexity level.
-
-```
-[React Hook per domain]     [API call]        [Server]         [SQLite]
-useItems() state  -------->  GET /api/items --> route handler --> SELECT
-  |                                                               |
-  |<-- setItems(data) <--- JSON response <--- query result <------+
+```typescript
+// Updated syncSetupItems to accept optional weightClass
+export function syncSetupItems(
+  db: Db,
+  setupId: number,
+  items: Array<{ itemId: number; weightClass?: string }>,
+) {
+  return db.transaction((tx) => {
+    tx.delete(setupItems).where(eq(setupItems.setupId, setupId)).run();
+    for (const item of items) {
+      tx.insert(setupItems)
+        .values({
+          setupId,
+          itemId: item.itemId,
+          weightClass: item.weightClass ?? "base",
+        })
+        .run();
+    }
+  });
+}
 ```
 
-Each page manages its own state via custom hooks (`useItems`, `useThreads`, `useSetups`). No Redux, no Zustand. If a mutation on one page affects another (e.g., resolving a thread adds an item to collection), the target page simply refetches on mount.
+**Sync schema update:**
 
-## Scaling Considerations
+```typescript
+export const syncSetupItemsSchema = z.object({
+  items: z.array(z.object({
+    itemId: z.number().int().positive(),
+    weightClass: z.enum(["base", "worn", "consumable"]).default("base"),
+  })),
+});
+```
 
-| Scale | Architecture Adjustments |
-|-------|--------------------------|
-| Single user (GearBox) | SQLite + single Bun process. Zero infrastructure. This is the target. |
-| 1-10 users | Still fine with SQLite in WAL mode. Add basic auth if needed. |
-| 100+ users | Switch to PostgreSQL, add connection pooling, consider separate API server. Not relevant for this project. |
+This is a **breaking change** to the sync API shape (from `{ itemIds: number[] }` to `{ items: [...] }`). The single call site is `useSyncSetupItems` in `useSetups.ts`, called from `ItemPicker.tsx`.
 
-### Scaling Priorities
+**Client-side classification totals** are computed from the setup items array, not from a separate API:
 
-1. **First bottleneck:** Image storage. If users upload many high-res photos, disk fills up. Mitigation: resize on upload (sharp library), limit file sizes.
-2. **Second bottleneck:** SQLite write contention under concurrent access. Not a concern for single-user. If it ever matters, switch to WAL mode or PostgreSQL.
+```typescript
+const baseWeight = setup.items
+  .filter(i => i.weightClass === "base")
+  .reduce((sum, i) => sum + (i.weightGrams ?? 0), 0);
 
-## Anti-Patterns
+const wornWeight = setup.items
+  .filter(i => i.weightClass === "worn")
+  .reduce((sum, i) => sum + (i.weightGrams ?? 0), 0);
 
-### Anti-Pattern 1: Storing Money as Floats
+const consumableWeight = setup.items
+  .filter(i => i.weightClass === "consumable")
+  .reduce((sum, i) => sum + (i.weightGrams ?? 0), 0);
+```
 
-**What people do:** Use `float` or JavaScript `number` for prices (e.g., `19.99`).
-**Why it's wrong:** Floating point arithmetic causes rounding errors. `0.1 + 0.2 !== 0.3`. Price calculations silently drift.
-**Do this instead:** Store prices as integers in cents (`1999` for $19.99). Format for display only in the UI layer. The schema uses `priceCents: integer`.
+**UI for classification toggle:** A three-segment toggle on each item card within the setup detail view. Clicking a segment calls `useUpdateSetupItemClass`. The three segments use the same pill-tab pattern already used for Active/Resolved in PlanningView.
 
-### Anti-Pattern 2: Overengineering State Management
+---
 
-**What people do:** Install Redux/Zustand/Jotai for a single-user CRUD app, create elaborate store slices, actions, reducers.
-**Why it's wrong:** Adds complexity with zero benefit when there is one user and no shared state across tabs or real-time updates.
-**Do this instead:** Use React hooks with fetch. `useState` + `useEffect` + a thin API wrapper. Refetch on mount. Keep it boring.
+### Feature 3: Weight Distribution Visualization
 
-### Anti-Pattern 3: SPA with Client-Side Routing for Everything
+**Scope:** Donut chart showing weight breakdown by category (on collection page) and by classification (on setup detail page). Uses `react-minimal-pie-chart` (~2kB gzipped) instead of Recharts (~45kB) because this is the only chart in the app.
 
-**What people do:** Build a full SPA with React Router, lazy loading, code splitting for 4-5 pages.
-**Why it's wrong:** Bun's fullstack server already handles page routing via HTML entrypoints. Adding client-side routing means duplicating routing logic, losing Bun's built-in asset optimization per page, and adding bundle complexity.
-**Do this instead:** Use Bun's HTML-based routing. Each page is a separate HTML entrypoint with its own React tree. Navigation between pages is standard `<a href>` links. Keep client-side routing for in-page state (e.g., tabs within thread detail) only.
+**Integration points:**
 
-### Anti-Pattern 4: Storing Computed Aggregates in the Database
+| Layer | File | Change Type | Details |
+|-------|------|-------------|---------|
+| Package | `package.json` | MODIFY | Add `react-minimal-pie-chart` dependency |
+| Client | NEW `components/WeightChart.tsx` | NEW | Reusable donut chart component |
+| Client | `routes/collection/index.tsx` | MODIFY | Add chart above category list in gear tab |
+| Client | `routes/setups/$setupId.tsx` | MODIFY | Add classification breakdown chart |
+| Client | `hooks/useTotals.ts` | NO CHANGE | Already returns `CategoryTotals[]` with weights |
 
-**What people do:** Store `totalWeight` and `totalCost` on the setup record, then try to keep them in sync when items change.
-**Why it's wrong:** Stale data, sync bugs, update anomalies. Items get edited but setup totals do not get recalculated.
-**Do this instead:** Compute totals on read. SQLite is fast enough for `SUM()` across a handful of items. Calculate in the service layer or as a SQL aggregate. For a single-user app with small datasets, this is effectively instant.
+**Why react-minimal-pie-chart over Recharts:** The app needs exactly one chart type (donut/pie). Recharts adds ~45kB gzipped for a full charting library when only the PieChart component is used. `react-minimal-pie-chart` is <3kB gzipped, has zero dependencies beyond React, supports donut charts via `lineWidth` prop, includes animation, and provides label support. It is the right tool for a focused need.
 
-## Integration Points
+**Chart component pattern:**
 
-### External Services
+```typescript
+// components/WeightChart.tsx
+import { PieChart } from "react-minimal-pie-chart";
 
-| Service | Integration Pattern | Notes |
-|---------|---------------------|-------|
-| None for v1 | N/A | Single-user local app, no external APIs needed |
-| Product URLs | Outbound links only | Store URLs to retailer pages, no API scraping |
+interface WeightChartProps {
+  segments: Array<{
+    label: string;
+    value: number;    // weight in grams (always grams internally)
+    color: string;
+  }>;
+  size?: number;
+}
 
-### Internal Boundaries
+export function WeightChart({ segments, size = 200 }: WeightChartProps) {
+  const filtered = segments.filter(s => s.value > 0);
+  if (filtered.length === 0) return null;
 
-| Boundary | Communication | Notes |
-|----------|---------------|-------|
-| Client <-> Server | REST API (JSON over fetch) | No WebSockets needed, no real-time requirements |
-| Routes <-> Services | Direct function calls | Same process, no serialization overhead |
-| Services <-> Database | Drizzle ORM queries | Type-safe, no raw SQL strings |
-| Server <-> Filesystem | Image read/write | `./uploads/` directory for gear photos |
+  return (
+    <PieChart
+      data={filtered.map(s => ({
+        title: s.label,
+        value: s.value,
+        color: s.color,
+      }))}
+      lineWidth={35}          // donut style
+      paddingAngle={2}
+      rounded
+      animate
+      animationDuration={500}
+      style={{ height: size, width: size }}
+    />
+  );
+}
+```
 
-## Build Order (Dependency Chain)
+**Two usage contexts:**
 
-The architecture implies this build sequence:
+1. **Collection page** -- weight by category. Data source: `useTotals().data.categories`. Each `CategoryTotals` already has `totalWeight` and `categoryName`. Assign a consistent color per category (use category index mapped to a palette array).
 
-1. **Database schema + Drizzle setup** -- Everything depends on the data model. Define tables for items, threads, candidates, setups, setup_items first.
-2. **API routes for items (CRUD)** -- The core entity. Threads and setups reference items.
-3. **Collection UI** -- First visible feature. Validates the data model and API work end-to-end.
-4. **Thread + candidate API and UI** -- Depends on items existing to resolve candidates into the collection.
-5. **Setup composition API and UI** -- Depends on items existing to compose into setups.
-6. **Dashboard** -- Aggregates stats from all other entities. Build last since it reads from everything.
-7. **Polish: image upload, impact calculations, status tracking** -- Enhancement layer on top of working CRUD.
+2. **Setup detail page** -- weight by classification. Data source: computed from `setup.items` grouping by `weightClass`. Three fixed colors for base/worn/consumable.
 
-This ordering means each phase produces a usable increment: after phase 3 you have a working gear catalog, after phase 4 you can plan purchases, after phase 5 you can compose setups.
+**Color palette for categories:**
+
+```typescript
+const CATEGORY_COLORS = [
+  "#6B7280", "#3B82F6", "#10B981", "#F59E0B",
+  "#EF4444", "#8B5CF6", "#EC4899", "#14B8A6",
+  "#F97316", "#6366F1", "#84CC16", "#06B6D4",
+];
+
+function getCategoryColor(index: number): string {
+  return CATEGORY_COLORS[index % CATEGORY_COLORS.length];
+}
+```
+
+**Classification colors (matching the app's muted palette):**
+
+```typescript
+const CLASSIFICATION_COLORS = {
+  base: "#6B7280",       // gray -- the core pack weight
+  worn: "#3B82F6",       // blue -- on your body
+  consumable: "#F59E0B", // amber -- gets used up
+};
+```
+
+**Chart placement:** On the collection page, the chart appears as a compact summary card above the category-grouped items, alongside the global totals. On the setup detail page, it appears in the sticky sub-bar area or as a collapsible section showing base/worn/consumable breakdown with a legend. Keep it compact -- this is a supplementary visualization, not the primary UI.
+
+---
+
+### Feature 4: Candidate Status Tracking
+
+**Scope:** Track candidate lifecycle from "researching" through "ordered" to "arrived". This is a column on the `thread_candidates` table, displayed as a badge on `CandidateCard`, and editable inline.
+
+**Integration points:**
+
+| Layer | File | Change Type | Details |
+|-------|------|-------------|---------|
+| DB | `schema.ts` | MODIFY | Add `status` column to `thread_candidates` |
+| DB | Drizzle migration | NEW | `ALTER TABLE thread_candidates ADD COLUMN status TEXT NOT NULL DEFAULT 'researching'` |
+| Shared | `schemas.ts` | MODIFY | Add `status` to candidate schemas |
+| Server | `thread.service.ts` | MODIFY | Include `status` in candidate creates and updates |
+| Server | `routes/threads.ts` | NO CHANGE | Already passes through all candidate fields |
+| Client | `hooks/useThreads.ts` | MODIFY | `CandidateWithCategory` type adds `status` |
+| Client | `hooks/useCandidates.ts` | NO CHANGE | `useUpdateCandidate` already handles partial updates |
+| Client | `components/CandidateCard.tsx` | MODIFY | Show status badge, add click-to-cycle |
+| Client | `components/CandidateForm.tsx` | MODIFY | Add status selector to form |
+| Test | `tests/helpers/db.ts` | MODIFY | Add `status` column to `thread_candidates` CREATE TABLE |
+
+**Schema change:**
+
+```typescript
+// In schema.ts -- thread_candidates table
+export const threadCandidates = sqliteTable("thread_candidates", {
+  // ... existing fields ...
+  status: text("status").notNull().default("researching"),
+  // Values: "researching" | "ordered" | "arrived"
+});
+```
+
+**Status badge colors (matching app's muted palette from v1.1):**
+
+```typescript
+const CANDIDATE_STATUS_STYLES = {
+  researching: "bg-gray-100 text-gray-600",
+  ordered:     "bg-amber-50 text-amber-600",
+  arrived:     "bg-green-50 text-green-600",
+} as const;
+```
+
+**Inline status cycling:** On `CandidateCard`, clicking the status badge cycles to the next state (researching -> ordered -> arrived). This calls the existing `useUpdateCandidate` mutation with just the status field. No new endpoint needed -- the `updateCandidate` service already accepts partial updates via `updateCandidateSchema.partial()`.
+
+```typescript
+// In CandidateCard
+const STATUS_ORDER = ["researching", "ordered", "arrived"] as const;
+
+function cycleStatus(current: string) {
+  const idx = STATUS_ORDER.indexOf(current as any);
+  return STATUS_ORDER[(idx + 1) % STATUS_ORDER.length];
+}
+
+// onClick handler for status badge:
+updateCandidate.mutate({
+  candidateId: id,
+  status: cycleStatus(status),
+});
+```
+
+**Candidate creation default:** New candidates default to "researching". The `createCandidateSchema` includes `status` as optional with default.
+
+```typescript
+export const createCandidateSchema = z.object({
+  // ... existing fields ...
+  status: z.enum(["researching", "ordered", "arrived"]).default("researching"),
+});
+```
+
+---
+
+### Feature 5: Weight Unit Selection
+
+**Scope:** User preference stored in the `settings` table, applied globally across all weight displays. The database always stores grams -- unit conversion is a display-only concern handled in the client formatter.
+
+**Integration points:**
+
+| Layer | File | Change Type | Details |
+|-------|------|-------------|---------|
+| DB | `settings` table | NO SCHEMA CHANGE | Uses existing key-value `settings` table: `{ key: "weightUnit", value: "g" }` |
+| Server | Settings routes | NO CHANGE | Existing `GET/PUT /api/settings/:key` handles this |
+| Client | `hooks/useSettings.ts` | MODIFY | Add `useWeightUnit` convenience hook |
+| Client | `lib/formatters.ts` | MODIFY | `formatWeight` accepts unit parameter |
+| Client | NEW `hooks/useFormatWeight.ts` | NEW | Hook combining weight unit setting + formatter |
+| Client | ALL components showing weight | MODIFY | Use new formatting approach |
+| Client | `components/ItemForm.tsx` | MODIFY | Weight input label shows current unit, converts on submit |
+| Client | `components/CandidateForm.tsx` | MODIFY | Same as ItemForm |
+| Client | NEW `components/UnitSelector.tsx` | NEW | Unit picker UI (segmented control or dropdown) |
+
+**Settings approach -- why not a new table:**
+
+The `settings` table already exists with a `key/value` pattern, and `useSettings.ts` already has `useSetting(key)` and `useUpdateSetting`. Adding weight unit is:
+
+```typescript
+// In useSettings.ts
+export function useWeightUnit() {
+  return useSetting("weightUnit"); // Returns "g" | "oz" | "lb" | "kg" or null (default to "g")
+}
+```
+
+**Conversion constants:**
+
+```typescript
+const GRAMS_PER_UNIT = {
+  g:  1,
+  oz: 28.3495,
+  lb: 453.592,
+  kg: 1000,
+} as const;
+
+type WeightUnit = keyof typeof GRAMS_PER_UNIT;
+```
+
+**Modified formatWeight:**
+
+```typescript
+export function formatWeight(
+  grams: number | null | undefined,
+  unit: WeightUnit = "g",
+): string {
+  if (grams == null) return "--";
+  const converted = grams / GRAMS_PER_UNIT[unit];
+  const decimals = unit === "g" ? 0 : unit === "kg" ? 2 : 1;
+  return `${converted.toFixed(decimals)} ${unit}`;
+}
+```
+
+**Threading unit through components -- custom hook approach:**
+
+Create a `useFormatWeight()` hook. Components call it to get a unit-aware formatter. No React Context needed -- `useSetting()` already provides reactive data through React Query.
+
+```typescript
+// hooks/useFormatWeight.ts
+import { useSetting } from "./useSettings";
+import { formatWeight as rawFormat, type WeightUnit } from "../lib/formatters";
+
+export function useFormatWeight() {
+  const { data: unitSetting } = useSetting("weightUnit");
+  const unit = (unitSetting ?? "g") as WeightUnit;
+
+  return {
+    unit,
+    formatWeight: (grams: number | null | undefined) => rawFormat(grams, unit),
+  };
+}
+```
+
+Components that display weight (ItemCard, CandidateCard, CategoryHeader, TotalsBar, SetupDetailPage) call `const { formatWeight } = useFormatWeight()` instead of importing `formatWeight` directly from `lib/formatters.ts`. This is 6-8 call sites to update.
+
+**Weight input handling:** When the user enters weight in the form, the input accepts the selected unit and converts to grams before sending to the API. The label changes from "Weight (g)" to "Weight (oz)" etc.
+
+```typescript
+// In ItemForm, the label reads from the hook
+const { unit } = useFormatWeight();
+// Label: `Weight (${unit})`
+
+// On submit, before payload construction:
+const weightGrams = form.weightValue
+  ? Number(form.weightValue) * GRAMS_PER_UNIT[unit]
+  : undefined;
+```
+
+**When editing an existing item**, the form pre-fills by converting stored grams back to the display unit:
+
+```typescript
+const displayWeight = item.weightGrams != null
+  ? (item.weightGrams / GRAMS_PER_UNIT[unit]).toFixed(unit === "g" ? 0 : unit === "kg" ? 2 : 1)
+  : "";
+```
+
+**Unit selector placement:** In the TotalsBar component. The user sees the unit right where weights are displayed and can switch inline. A small segmented control or dropdown next to the weight display in the top bar.
+
+---
+
+## New vs Modified Files -- Complete Inventory
+
+### New Files (5)
+
+| File | Purpose |
+|------|---------|
+| `src/client/components/SearchBar.tsx` | Reusable search input with clear button |
+| `src/client/components/WeightChart.tsx` | Donut chart wrapper around react-minimal-pie-chart |
+| `src/client/components/UnitSelector.tsx` | Weight unit segmented control / dropdown |
+| `src/client/hooks/useFormatWeight.ts` | Hook combining weight unit setting + formatter |
+| `src/db/migrations/XXXX_v1.2_columns.sql` | Drizzle migration for new columns |
+
+### Modified Files (15)
+
+| File | What Changes |
+|------|-------------|
+| `package.json` | Add `react-minimal-pie-chart` dependency |
+| `src/db/schema.ts` | Add `weightClass` to setup_items, `status` to thread_candidates |
+| `src/shared/schemas.ts` | Add `status` to candidate schemas, update sync schema |
+| `src/server/services/setup.service.ts` | Return `weightClass`, add `updateSetupItemClass`, update `syncSetupItems` |
+| `src/server/services/thread.service.ts` | Include `status` in candidate create/update |
+| `src/server/routes/setups.ts` | Add `PATCH /:id/items/:itemId` for classification |
+| `src/client/lib/formatters.ts` | `formatWeight` accepts unit param, add conversion constants |
+| `src/client/hooks/useSetups.ts` | `SetupItemWithCategory` adds `weightClass`, update sync mutation, add classification mutation |
+| `src/client/hooks/useThreads.ts` | `CandidateWithCategory` adds `status` field |
+| `src/client/hooks/useSettings.ts` | Add `useWeightUnit` convenience export |
+| `src/client/routes/collection/index.tsx` | Add SearchBar + category filter to gear tab, add weight chart |
+| `src/client/routes/setups/$setupId.tsx` | Classification toggles per item, classification chart, updated totals |
+| `src/client/components/ItemCard.tsx` | Optional `weightClass` badge in setup context |
+| `src/client/components/CandidateCard.tsx` | Status badge + click-to-cycle behavior |
+| `tests/helpers/db.ts` | Add `weight_class` and `status` columns to CREATE TABLE statements |
+
+### Unchanged Files
+
+| File | Why No Change |
+|------|-------------|
+| `src/client/lib/api.ts` | Existing fetch wrappers handle all new API shapes |
+| `src/client/stores/uiStore.ts` | No new panel/dialog state needed |
+| `src/server/routes/items.ts` | Search is client-side |
+| `src/server/services/item.service.ts` | No query changes needed |
+| `src/server/services/totals.service.ts` | Category totals unchanged; classification totals computed client-side |
+| `src/server/routes/totals.ts` | No new endpoints |
+| `src/server/index.ts` | No new route registrations (setups routes already registered) |
+
+## Build Order (Dependency-Aware)
+
+The features have specific dependencies that dictate build order.
+
+```
+Phase 1: Weight Unit Selection
+  +-- Modifies formatWeight which is used everywhere
+  +-- Must be done first so subsequent weight displays use the new formatter
+  +-- Dependencies: none (uses existing settings infrastructure)
+
+Phase 2: Search/Filter
+  +-- Pure client-side addition, no schema changes
+  +-- Can be built independently
+  +-- Dependencies: none
+
+Phase 3: Candidate Status Tracking
+  +-- Schema migration (simple column add)
+  +-- Minimal integration surface
+  +-- Dependencies: none (but batch schema migration with Phase 4)
+
+Phase 4: Weight Classification
+  +-- Schema migration + sync API change + new PATCH endpoint
+  +-- Requires weight unit work to be done (displays classification totals)
+  +-- Dependencies: Phase 1 (weight formatting)
+
+Phase 5: Weight Distribution Charts
+  +-- Depends on weight classification (for setup breakdown chart)
+  +-- Depends on weight unit (chart labels need formatted weights)
+  +-- Dependencies: Phase 1 + Phase 4
+  +-- npm dependency: react-minimal-pie-chart
+```
+
+**Batch Phase 3 and Phase 4 schema migrations into one Drizzle migration** since they both add columns. Run `bun run db:generate` once after both schema changes are made.
+
+## Data Flow Changes Summary
+
+### Current Data Flows (unchanged)
+
+```
+useItems()   -> GET /api/items   -> getAllItems(db)   -> items JOIN categories
+useThreads() -> GET /api/threads -> getAllThreads(db)  -> threads JOIN categories
+useSetups()  -> GET /api/setups  -> getAllSetups(db)   -> setups + subqueries
+useTotals()  -> GET /api/totals  -> getCategoryTotals  -> items GROUP BY categoryId
+```
+
+### New/Modified Data Flows
+
+```
+Search/Filter:
+  CollectionView local state (searchTerm, categoryFilter)
+    -> useMemo over useItems().data
+    -> no API change
+
+Weight Unit:
+  useFormatWeight() -> useSetting("weightUnit") -> GET /api/settings/weightUnit
+    -> formatWeight(grams, unit) -> display string
+
+Candidate Status:
+  CandidateCard click -> useUpdateCandidate({ status: "ordered" })
+    -> PUT /api/threads/:id/candidates/:cid -> updateCandidate(db, cid, { status })
+
+Weight Classification:
+  Setup detail -> getSetupWithItems now returns weightClass per item
+    -> client groups by weightClass for totals
+    -> PATCH /api/setups/:id/items/:itemId updates classification
+
+Weight Chart:
+  Collection: useTotals().data.categories -> WeightChart segments
+  Setup: setup.items grouped by weightClass -> WeightChart segments
+```
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1: Server-Side Search for Small Collections
+
+**What people do:** Build a search API with pagination, debounced requests, loading states
+**Why it's wrong for this app:** Single-user app with <1000 items. Server round-trips add latency and complexity for zero benefit. Client already has all items in React Query cache.
+**Do this instead:** Filter in-memory using `useMemo` over the cached items array.
+
+### Anti-Pattern 2: Weight Classification on the Items Table
+
+**What people do:** Add `weightClass` column to `items` table
+**Why it's wrong:** An item's classification is context-dependent -- the same item can be "base" in one setup and not present in another. Putting it on `items` forces a single global classification.
+**Do this instead:** Put `weightClass` on `setup_items` join table. This is how LighterPack and every serious gear tracker works.
+
+### Anti-Pattern 3: Converting Stored Values to User's Unit
+
+**What people do:** Store weights in the user's preferred unit, or convert on the server before sending
+**Why it's wrong:** Changing the unit preference would require re-interpreting all stored data. Different users (future multi-user) might prefer different units from the same data.
+**Do this instead:** Always store grams in the database. Convert to display unit only in the client formatter. The conversion is a pure function with no side effects.
+
+### Anti-Pattern 4: Heavy Charting Library for One Chart Type
+
+**What people do:** Install Recharts (~45kB) or Chart.js (~67kB) for a single donut chart
+**Why it's wrong:** Massive bundle size overhead for minimal usage. These libraries are designed for dashboards with many chart types.
+**Do this instead:** Use `react-minimal-pie-chart` (<3kB) which does exactly donut/pie charts with zero dependencies.
+
+### Anti-Pattern 5: React Context Provider for Weight Unit
+
+**What people do:** Build a full React Context provider with `createContext`, `useContext`, a Provider wrapper component
+**Why it's excessive here:** The `useSetting("weightUnit")` hook already provides reactive data through React Query. Adding a Context layer on top adds indirection for no benefit.
+**Do this instead:** Create a simple custom hook `useFormatWeight()` that internally calls `useSetting("weightUnit")`. React Query already handles caching and reactivity.
 
 ## Sources
 
-- [Bun Fullstack Dev Server docs](https://bun.com/docs/bundler/fullstack) -- Official documentation on Bun's HTML-based routing and asset bundling
-- [bun:sqlite API Reference](https://bun.com/reference/bun/sqlite) -- Native SQLite module documentation
-- [Building Full-Stack App with Bun.js, React and Drizzle ORM](https://awplife.com/building-full-stack-app-with-bun-js-react-drizzle/) -- Project structure reference
-- [Bun v3.1 Release (InfoQ)](https://www.infoq.com/news/2026/01/bun-v3-1-release/) -- Zero-config frontend, built-in DB clients
-- [Bun + React + Hono pattern](https://dev.to/falconz/serving-a-react-app-and-hono-api-together-with-bun-1gfg) -- Alternative fullstack patterns
-- [Inventory Management DB Design (Medium)](https://medium.com/@bhargavkoya56/weekly-db-project-1-inventory-management-db-design-seed-from-schema-design-to-performance-8e6b56445fe6) -- Schema design patterns for inventory systems
+- [Drizzle ORM Filters Documentation](https://orm.drizzle.team/docs/operators) -- like, and, or operators for SQLite
+- [Drizzle ORM Conditional Filters Guide](https://orm.drizzle.team/docs/guides/conditional-filters-in-query) -- dynamic filter patterns
+- [SQLite LIKE case sensitivity with Drizzle](https://github.com/drizzle-team/drizzle-orm-docs/issues/239) -- SQLite LIKE is case-insensitive for ASCII
+- [react-minimal-pie-chart npm](https://www.npmjs.com/package/react-minimal-pie-chart) -- lightweight pie/donut chart, <3kB gzipped
+- [react-minimal-pie-chart GitHub](https://github.com/toomuchdesign/react-minimal-pie-chart) -- API docs and examples
+- [LighterPack Tutorial - 99Boulders](https://www.99boulders.com/lighterpack-tutorial) -- base/worn/consumable weight classification standard
+- [Pack Weight Categories](https://hikertimes.com/difference-between-base-weight-and-total-weight/) -- base weight vs total weight definitions
+- [Pack Weight Calculator](https://backpackpeek.com/blog/pack-weight-calculator-base-weight-guide) -- weight classification guide
 
 ---
-*Architecture research for: GearBox gear management app*
-*Researched: 2026-03-14*
+*Architecture research for: GearBox v1.2 Collection Power-Ups*
+*Researched: 2026-03-16*

.planning/research/FEATURES.md

@@ -1,201 +1,244 @@
-# Feature Research
+# Feature Research: v1.2 Collection Power-Ups
 
-**Domain:** Gear management and purchase planning (personal inventory + research workflow)
-**Researched:** 2026-03-14
+**Domain:** Gear management -- search/filter, weight classification, weight visualization, candidate status tracking, weight unit selection
+**Researched:** 2026-03-16
 **Confidence:** HIGH
+**Scope:** New features only. v1.0/v1.1 features (item CRUD, categories, threads, setups, dashboard, onboarding, images, icons) are already shipped.
 
-## Feature Landscape
+## Table Stakes
 
-### Table Stakes (Users Expect These)
+Features that gear management users expect. Missing these makes the app feel incomplete for collections beyond ~20 items.
 
-Features users assume exist. Missing these = product feels incomplete.
+| Feature | Why Expected | Complexity | Dependencies on Existing |
+|---------|--------------|------------|--------------------------|
+| Search items by name | Every competitor with an inventory concept has search. Hikt highlights "searchable digital closet." PackLight Supporter Edition has inventory search. Once a collection exceeds 30 items, scrolling to find something is painful. LighterPack notably lacks this and users complain. | LOW | Items query (`useItems`), collection view. Client-side only -- no API changes needed for <500 items. |
+| Filter items by category | Already partially exists in Planning view (category dropdown for threads). Collection view groups by category visually but has no filter. Users need to quickly narrow to "show me just my shelter items." | LOW | Categories query (`useCategories`), collection view. Client-side filtering of already-fetched items. |
+| Weight unit selection (g, oz, lb, kg) | Universal across all competitors. LighterPack supports toggling between g/oz/lb/kg. Packrat offers per-item input in any unit with display conversion. Backpacking Light forum users specifically praise apps that let you "enter item weights in grams and switch the entire display to lbs & oz." Gear specs come in mixed units -- a sleeping bag in lbs/oz, a fuel canister in grams. | LOW | `formatWeight()` in `lib/formatters.ts`, `settings` table (already exists with key/value store), TotalsBar, ItemCard, CandidateCard, SetupCard -- every weight display. |
+| Weight classification (base/worn/consumable) | LighterPack pioneered this three-way split and it is now universal. Hikt, PackLight, Packstack, HikeLite, 99Boulders spreadsheet -- all support it. "Base weight" is the core metric of the ultralight community. Without classification, weight totals are a single number with no actionable insight. | MEDIUM | `setup_items` join table (needs new column), setup detail view, setup service, totals computation. Schema migration required. |
 
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|------------|-------|
-| Item CRUD with core fields (name, weight, price, category) | Every gear app and spreadsheet has this. It is the minimum unit of value. | LOW | Weight and price are the two fields users care about most. Category groups items visually. |
-| Weight unit support (g, oz, lb, kg) | Gear communities are split between metric and imperial. LighterPack, GearGrams, Hikt all support multi-unit. | LOW | Store in grams internally, display in user-preferred unit. Conversion is trivial. |
-| Automatic weight/cost totals | Spreadsheets do this. Every competitor does this. Manual math = why bother with an app. | LOW | Sum by category, by setup, by collection. Real-time recalculation on any change. |
-| Categories/grouping | LighterPack, GearGrams, Packstack all organize by category (shelter, sleep, cook, clothing, etc.). Without grouping, lists become unreadable past 20 items. | LOW | User-defined categories. Suggest defaults but allow custom. |
-| Named setups / packing lists | LighterPack has lists, GearGrams has lists, Packstack has trips, Hikt has packing lists. Composing subsets of your gear into purpose-specific loadouts is universal. | MEDIUM | Items belong to collection; setups reference items from collection. Many-to-many relationship. |
-| Setup weight/cost breakdown | Every competitor shows base weight, worn weight, consumable weight as separate totals. Pie charts or percentage breakdowns by category are standard (LighterPack pioneered this). | MEDIUM | Weight classification (base/worn/consumable) per item per setup. Visual breakdown is expected. |
-| Notes/description per item | Spreadsheet users write notes. Every competitor supports free text on items. Useful for fit notes, durability observations, model year specifics. | LOW | Plain text field. No rich text needed for v1. |
-| Product links / URLs | Users track where they found or bought items. Spreadsheets always have a "link" column. | LOW | Single URL field per item. |
-| Photos per item | Hikt, GearCloset, and Packrat all support item photos. Visual identification matters -- many gear items look similar in text. | MEDIUM | Image upload and storage. Start with one photo per item; multi-photo is a differentiator. |
-| Search and filter | Once a collection exceeds 30-40 items, finding things without search is painful. Hikt highlights "searchable digital closet." | LOW | Filter by category, search by name. Basic but essential. |
-| Import from CSV | GearGrams, HikeLite, HikerHerd, Packrat all support CSV import. Users migrating from spreadsheets (GearBox's primary audience) need this. | MEDIUM | Define a simple CSV schema. Map columns to fields. Handle unit conversion on import. |
-| Export to CSV | Companion to import. Users want data portability and backup ability. | LOW | Straightforward serialization of collection data. |
+## Differentiators
 
-### Differentiators (Competitive Advantage)
+Features that set GearBox apart or add meaningful value beyond what competitors offer.
 
-Features that set the product apart. Not required, but valuable.
+| Feature | Value Proposition | Complexity | Dependencies on Existing |
+|---------|-------------------|------------|--------------------------|
+| Weight distribution visualization (donut/pie chart) | LighterPack's pie chart is iconic and widely cited as its best feature. "The pie chart at the top is a great way to visualize how your pack weight breaks down by category." PackLight uses bar graphs. GearBox can do this per-setup with a modern donut chart that also shows base/worn/consumable breakdown -- a combination no competitor offers cleanly. | MEDIUM | Totals data (already computed server-side per category), weight classification (new), a chart library (react-minimal-pie-chart at 2kB or Recharts). |
+| Candidate status tracking (researching/ordered/arrived) | No competitor has this. Research confirmed: the specific workflow of tracking purchase status through stages does not exist in any gear management app. This is unique to GearBox's planning thread concept. It makes threads a living document of the purchase lifecycle, not just a comparison tool. | LOW | `thread_candidates` table (needs new `status` column), CandidateCard, CandidateForm. Simple text field migration. |
+| Planning category filter with icon-aware dropdown | Already partially built as a plain `<select>` in PlanningView. Upgrading to show Lucide icons alongside category names makes filtering feel polished and consistent with the icon picker UX. | LOW | Existing CategoryPicker component pattern, existing category filter state in PlanningView. |
+| Weight classification shown per-setup (not global) | In LighterPack, worn/consumable flags are per-item within a list. In GearBox, items exist in a global collection and appear in multiple setups. The same jacket might be "worn" in a summer bikepacking setup but "base weight" (packed in panniers) in a winter setup. Classification belongs on the setup_items join, not on the item itself. This is architecturally superior to competitors. | MEDIUM | `setup_items` table schema, setup sync endpoint, setup detail UI. |
 
-| Feature | Value Proposition | Complexity | Notes |
-|---------|-------------------|------------|-------|
-| Purchase planning threads | No competitor has this. LighterPack, GearGrams, Packstack, Hikt are all post-purchase tools. GearBox's core value is the pre-purchase research workflow: create a thread, add candidates, compare, decide, then move the winner to your collection. This is the single biggest differentiator. | HIGH | Thread model with candidate items, status tracking, resolution workflow. This is the app's reason to exist. |
-| Impact preview ("how does this affect my setup?") | No competitor shows how a potential purchase changes your overall setup weight/cost. Users currently do this math manually in spreadsheets. Seeing "+120g to base weight, +$85 to total cost" before buying is uniquely valuable. | MEDIUM | Requires linking threads to setups. Calculate delta between current item (if replacing) and candidate. |
-| Thread resolution workflow | The lifecycle of "researching -> ordered -> arrived -> in collection" does not exist in any competitor. Closing a thread and promoting the winner to your collection is a novel workflow that mirrors how people actually buy gear. | MEDIUM | Status state machine on thread items. Resolution action that creates/updates collection item. |
-| Side-by-side candidate comparison | Wishlist apps let you save items. GearBox lets you compare candidates within a thread on the dimensions that matter (weight, price, notes). Similar to product comparison on retail sites, but for your specific context. | MEDIUM | Comparison view pulling from thread candidates. Highlight differences in weight/price. |
-| Priority/ranking within threads | Mark favorites among candidates. Simple but no gear app does this because no gear app has a research/planning concept. | LOW | Numeric rank or star/favorite flag per candidate in a thread. |
-| Multi-photo per item | Most competitors support zero or one photo. Multiple photos (product shots, detail shots, in-use shots) add real value for gear tracking. | MEDIUM | Gallery per item. Storage considerations. Defer to v1.x. |
-| Weight distribution visualization | LighterPack's pie chart is iconic. A clean, modern version with interactive breakdowns by category adds polish. | MEDIUM | Chart component showing percentage of total weight by category. |
-| Hobby-agnostic data model | Competitors are hiking/backpacking-specific. GearBox works for bikepacking, sim racing, photography, cycling, or any collection hobby. The data model uses generic "categories" rather than hardcoded "shelter/sleep/cook." | LOW | Architecture decision more than feature. No hiking-specific terminology baked into the model. |
+## Anti-Features
 
-### Anti-Features (Commonly Requested, Often Problematic)
+Features to explicitly NOT build in this milestone.
 
-Features that seem good but create problems.
+| Anti-Feature | Why Avoid | What to Do Instead |
+|--------------|-----------|-------------------|
+| Per-item weight input in multiple units | Packrat lets you enter "2 lb 3 oz" per item. This adds parsing complexity, ambiguous storage, and conversion bugs. | Store grams internally (already done). Convert for display only. Users enter grams; if they want oz input, they convert mentally or we add a unit toggle on the input field later. |
+| Interactive chart drill-down (click to zoom) | LighterPack lets you click pie slices to zoom into category breakdowns. Adds significant interaction complexity. | Static donut chart with hover tooltips. Drill-down is a future enhancement. |
+| Weight goals / targets ("your target base weight is X") | Some apps show ultralight thresholds. Adds opinionated norms that conflict with hobby-agnostic design. | Show the numbers. Let users interpret them. |
+| Custom weight classification labels | Beyond base/worn/consumable. Some users want "luxury" or "shared" categories. | Three classifications cover 95% of use cases. The notes field handles edge cases. |
+| Server-side search / full-text search | SQLite FTS5 or similar. Premature for a single-user app with <1000 items. | Client-side filtering of the already-fetched items array. Simpler, faster for the expected data scale. |
+| Worn/consumable at the global item level | Tempting to add a classification column to the `items` table. | Classification varies by setup context. A rain shell is "worn" on a day hike but "base weight" (packed) on a bike tour. The join table `setup_items` is the correct location. |
 
-| Feature | Why Requested | Why Problematic | Alternative |
-|---------|---------------|-----------------|-------------|
-| Multi-user / social sharing | "Share my setup with friends," "collaborate on packing lists." Hikt Premium has real-time collaboration. | Adds auth, permissions, data isolation, and massive complexity to a single-user app. The PROJECT.md explicitly scopes this out. Premature for v1. | Export/share as read-only link or image in a future version. No auth needed. |
-| Price tracking / deal alerts | Wishlist apps (Sortd, WishUpon) track price drops. Seems useful for purchase planning. | Requires scraping or API integrations with retailers. Fragile, maintenance-heavy, legally gray. Completely different product category. | Store the price you found manually. Link to the product page. Users can check prices themselves. |
-| Barcode/product database scanning | Hikt has barcode scanning and product database lookup. Seems like it saves time. | Requires maintaining or licensing a product database. Outdoor gear barcodes are inconsistent. Mobile-first feature that does not fit a web-first app. | Manual entry is fine for a collection that grows by 1-5 items per month. Not a data-entry-heavy workflow. |
-| Custom comparison parameters | "Let me define which fields to compare (warmth rating, denier, waterproof rating)." | Turns a simple app into a configurable schema builder. Massive complexity for marginal value. PROJECT.md lists this as out of scope for v1. | Use the notes field for specs. Fixed comparison on weight/price covers 80% of use cases. |
-| Community gear database / shared catalog | "Browse what other people use," "copy someone's gear list." Hikt has community packing lists. | Requires moderation, data quality controls, user accounts, and content management. Completely different product. | Stay focused on personal inventory. Community features are a different app. |
-| Mobile native app | PackLight and Hikt have iOS/Android apps. | Doubles or triples development effort. Web-first serves the use case (gear management is a desk activity, not a trailside activity). PROJECT.md scopes this out. | Responsive web design. Works on mobile browsers for quick lookups. |
-| Real-time weather integration | Packstack integrates weather for trip planning. | Requires external API, ongoing costs, and is only relevant to outdoor-specific use cases. GearBox is hobby-agnostic. | Out of scope. Users check weather separately. |
-| Automated "what to bring" recommendations | AI/rule-based suggestions based on trip conditions. | Requires domain knowledge per hobby, weather data, user preference modeling. Over-engineered for a personal tool. | Users build their own setups. They know their gear. |
+## Feature Details
+
+### 1. Search and Filter
+
+**What users expect:** A text input that filters visible items by name as you type. A category dropdown or pill selector to filter by category. Both should work together (search within a category).
+
+**Domain patterns observed:**
+- Hikt: Searchable gear closet with category and specification filters
+- PackLight: Inventory search (premium feature) with category organization
+- Backpacking Light Calculator: Search filter in gear locker and within packs
+- LighterPack: No text search -- widely considered a gap
+
+**Recommended implementation:**
+- Sticky search bar above the collection grid with a text input and category filter dropdown
+- Client-side filtering using `Array.filter()` on the items array from `useItems()`
+- Case-insensitive substring match on item name
+- Category filter as pills or dropdown (reuse the pattern from PlanningView)
+- URL search params for filter state (shareable filtered views, consistent with existing `?tab=` pattern)
+- Clear filters button when any filter is active
+- Result count displayed ("showing 12 of 47 items")
+
+**Complexity:** LOW. Pure client-side. No API changes. ~100 lines of new component code plus minor state management.
+
+### 2. Weight Classification (Base/Worn/Consumable)
+
+**What users expect:** Every item in a setup can be marked as one of three types:
+- **Base weight**: Items carried in the pack. The fixed weight of your loadout. This is the primary metric ultralight hikers optimize.
+- **Worn weight**: Items on your body while hiking (shoes, primary clothing, watch, sunglasses). Not counted toward pack weight but tracked as part of "skin-out" weight.
+- **Consumable weight**: Items that deplete during a trip (food, water, fuel, sunscreen). Variable weight not counted toward base weight.
+
+**Domain patterns observed:**
+- LighterPack: Per-item icons (shirt icon = worn, flame icon = consumable). Default = base weight. Totals show base/worn/consumable/total separately.
+- Packstack: "Separates base weight, worn weight, and consumables so you always know exactly what your pack weighs."
+- HikeLite: "Mark heavy clothing as worn to see your true base weight."
+- 99Boulders spreadsheet: Column with dropdown: WORN / CONSUMABLE / - (dash = base).
+
+**Critical design decision -- classification scope:**
+In LighterPack, items only exist within lists, so the flag is per-item-per-list inherently. In GearBox, items live in a global collection and are referenced by setups. The classification MUST live on the `setup_items` join table, not on the `items` table. Reason: the same item can have different classifications in different setups (a puffy jacket is "worn" on a cold-weather hike but "base weight" in a three-season setup where it stays packed).
+
+**Recommended implementation:**
+- Add `classification TEXT NOT NULL DEFAULT 'base'` column to `setup_items` table
+- Valid values: `"base"`, `"worn"`, `"consumable"`
+- Default to `"base"` (most items are base weight; this matches user expectation)
+- UI: Small segmented control or icon toggle on each item within the setup detail view
+- LighterPack-style icons: backpack icon (base), shirt icon (worn), flame/droplet icon (consumable)
+- Setup totals recalculated: show base weight, worn weight, consumable weight, and total (skin-out) as four separate numbers
+- SQL aggregation update: `SUM(CASE WHEN classification = 'base' THEN weight_grams ELSE 0 END)` etc.
+
+**Complexity:** MEDIUM. Requires schema migration, API changes (sync endpoint must accept classification), service layer updates, and UI for per-item classification within setup views.
+
+### 3. Weight Distribution Visualization
+
+**What users expect:** A chart showing where the weight is. By category is standard. By classification (base/worn/consumable) is a bonus.
+
+**Domain patterns observed:**
+- LighterPack: Color-coded pie chart by category, click to drill down. "As you enter each piece of equipment, a pie chart immediately displays a breakdown of where your weight is appropriated." Colors are customizable per category.
+- PackLight: Bar graph comparing category weights
+- OutPack: Category breakdown graph
+
+**Two chart contexts:**
+1. **Collection-level**: Weight by category across the whole collection. Uses existing `useTotals()` data.
+2. **Setup-level**: Weight by category AND by classification within a specific setup. More useful because setups represent actual loadouts.
+
+**Recommended implementation:**
+- Donut chart (modern feel, consistent with GearBox's minimalist aesthetic)
+- Library: `react-minimal-pie-chart` (2kB gzipped, zero dependencies, SVG-based) over Recharts (40kB+). GearBox only needs pie/donut -- no line charts, bar charts, etc.
+- Setup detail view: Donut chart showing weight by category, with center text showing total base weight
+- Optional toggle: switch between "by category" and "by classification" views
+- Color assignment: Derive from category or classification type (base = neutral gray, worn = blue, consumable = amber)
+- Hover tooltips showing category name, weight, and percentage
+- Responsive: Chart should work on mobile viewports
+
+**Complexity:** MEDIUM. New dependency, new component, integration with totals data. The chart itself is straightforward; the data aggregation for per-setup-per-category-per-classification is the main work.
+
+### 4. Candidate Status Tracking
+
+**What users expect:** This is novel -- no competitor has it. The workflow mirrors real purchase behavior:
+1. **Researching** (default): You found this product, added it to a thread, and are evaluating it
+2. **Ordered**: You decided to buy it and placed an order
+3. **Arrived**: The product has been delivered. Ready for thread resolution.
+
+**Why this matters:** Without status tracking, threads are a flat list of candidates. With it, threads become a living purchase tracker. A user can see at a glance "I ordered the Nemo Tensor, still researching two other pads."
+
+**Recommended implementation:**
+- Add `status TEXT NOT NULL DEFAULT 'researching'` column to `thread_candidates` table
+- Valid values: `"researching"`, `"ordered"`, `"arrived"`
+- UI: Status badge on CandidateCard (small colored pill, similar to existing weight/price badges)
+- Color scheme: researching = gray/neutral, ordered = amber/yellow, arrived = green
+- Status change: Dropdown or simple click-to-cycle on the candidate card
+- Thread-level summary: Show count by status ("2 researching, 1 ordered")
+- When resolving a thread, only candidates with status "arrived" should be selectable as winners (soft constraint -- show a warning, not a hard block, since users may resolve with a "researching" candidate they just bought in-store)
+
+**Complexity:** LOW. Simple column addition, enum-like text field, badge rendering, optional status transition UI.
+
+### 5. Weight Unit Selection
+
+**What users expect:** Choose a preferred unit (grams, ounces, pounds, kilograms) and have ALL weight displays in the app use that unit. LighterPack toggles between g/oz/lb/kg at the top level. The BPL Calculator app lets you "enter item weights in grams and switch the entire display to lbs & oz."
+
+**Domain patterns observed:**
+- LighterPack: Toggle at list level between lb/oz/g/kg. Only changes summary display, not per-item display.
+- Packrat: "Input items in different units, choose how they're displayed, and freely convert between them."
+- BPL Calculator: Global settings change, applied to all displays
+- WeighMyGear: Input locked to grams, less intuitive
+
+**Recommended implementation:**
+- Store preference in existing `settings` table as `{ key: "weightUnit", value: "g" }` (default: grams)
+- Supported units: `g` (grams), `oz` (ounces), `lb` (pounds + ounces), `kg` (kilograms)
+- Conversion constants: 1 oz = 28.3495g, 1 lb = 453.592g, 1 kg = 1000g
+- Display format per unit:
+  - `g`: "450g" (round to integer)
+  - `oz`: "15.9 oz" (one decimal)
+  - `lb`: "2 lb 3 oz" (pounds + remainder ounces, traditional format)
+  - `kg`: "1.45 kg" (two decimals)
+- Update `formatWeight()` to accept unit parameter or read from a React context/hook
+- Settings UI: Simple dropdown or segmented control, accessible from a settings page or inline in the TotalsBar
+- Internal storage stays as grams (already the case with `weight_grams` column)
+- Affects: TotalsBar, ItemCard, CandidateCard, SetupCard, CategoryHeader, setup detail view, chart tooltips
+
+**Complexity:** LOW. No schema changes. Update the `formatWeight()` function, add a settings hook, propagate the unit to all display points. The main effort is touching every component that displays weight (there are ~6-8 call sites).
+
+### 6. Planning Category Filter with Icon-Aware Dropdown
+
+**What users expect:** The existing category filter in PlanningView is a plain `<select>` without icons. Since categories now have Lucide icons (v1.1), the filter should show them.
+
+**Recommended implementation:**
+- Replace the native `<select>` with a custom dropdown component that renders `<LucideIcon>` alongside category names
+- Match the visual style of the CategoryPicker used in thread creation
+- Same functionality, better visual consistency
+
+**Complexity:** LOW. UI-only change. Replace ~20 lines of `<select>` with a custom dropdown component.
 
 ## Feature Dependencies
 
 ```
-[Item CRUD + Core Fields]
+[Weight Unit Selection] --independent-- (affects all displays, no schema changes)
     |
-    +--requires--> [Categories]
-    |
-    +--enables---> [Named Setups / Packing Lists]
-    |                   |
-    |                   +--enables---> [Setup Weight/Cost Breakdown]
-    |                   |
-    |                   +--enables---> [Impact Preview] (also requires Planning Threads)
-    |
-    +--enables---> [Planning Threads]
-                        |
-                        +--enables---> [Candidate Comparison]
-                        |
-                        +--enables---> [Thread Resolution Workflow]
-                        |                   |
-                        |                   +--creates---> items in [Collection]
-                        |
-                        +--enables---> [Priority/Ranking]
-                        |
-                        +--enables---> [Status Tracking] (researching -> ordered -> arrived)
+    +-- should ship first (all other features benefit from correct unit display)
 
-[Search & Filter] --enhances--> [Item CRUD] (becomes essential at ~30+ items)
+[Search & Filter] --independent-- (pure client-side, no schema changes)
+    |
+    +-- no dependencies on other v1.2 features
 
-[Import CSV] --populates--> [Item CRUD] (bootstrap for spreadsheet migrants)
+[Candidate Status Tracking] --independent-- (schema change on thread_candidates only)
+    |
+    +-- no dependencies on other v1.2 features
 
-[Photos] --enhances--> [Item CRUD] (independent, can add anytime)
+[Weight Classification] --depends-on--> [existing setup_items table]
+    |
+    +-- schema migration on setup_items
+    +-- enables [Weight Distribution Visualization]
 
-[Weight Unit Support] --enhances--> [All weight displays] (must be in from day one)
+[Weight Distribution Visualization] --depends-on--> [Weight Classification]
+    |
+    +-- needs classification data to show base/worn/consumable breakdown
+    +-- can show by-category chart without classification (partial value)
+    +-- new dependency: react-minimal-pie-chart
+
+[Planning Category Filter Icons] --depends-on--> [existing CategoryPicker pattern]
+    |
+    +-- pure UI enhancement
 ```
 
-### Dependency Notes
+### Implementation Order Rationale
 
-- **Named Setups require Item CRUD:** Setups are compositions of existing collection items. The collection must exist first.
-- **Planning Threads require Item CRUD:** Thread candidates have the same data shape as collection items (weight, price, etc.). Reuse the item model.
-- **Impact Preview requires both Setups and Threads:** You need a setup to compare against and a thread candidate to evaluate. This is a later-phase feature.
-- **Thread Resolution creates Collection Items:** The resolution workflow bridges threads and collection. Both must be stable before resolution logic is built.
-- **Import CSV populates Collection:** Import is a bootstrap feature for users migrating from spreadsheets. Should be available early but after the core item model is solid.
+1. **Weight Unit Selection** first -- touches formatting everywhere, foundational for all subsequent weight displays
+2. **Search & Filter** second -- standalone, immediately useful, low risk
+3. **Candidate Status Tracking** third -- standalone schema change, simple
+4. **Planning Category Filter** fourth -- quick UI polish
+5. **Weight Classification** fifth -- most complex schema change, affects setup data model
+6. **Weight Distribution Visualization** last -- depends on classification, needs chart library, highest UI complexity
 
-## MVP Definition
+## Complexity Summary
 
-### Launch With (v1)
-
-Minimum viable product -- what is needed to validate the concept and replace a spreadsheet.
-
-- [ ] Item CRUD with weight, price, category, notes, product link -- the core inventory
-- [ ] User-defined categories -- organize items meaningfully
-- [ ] Weight unit support (g, oz, lb, kg) -- non-negotiable for gear community
-- [ ] Automatic weight/cost totals by category and overall -- the reason to use an app over a text file
-- [ ] Named setups with item selection and totals -- compose loadouts from your collection
-- [ ] Planning threads with candidate items -- the core differentiator, add candidates you are researching
-- [ ] Side-by-side candidate comparison on weight/price -- the payoff of the thread concept
-- [ ] Thread resolution (pick a winner, move to collection) -- close the loop
-- [ ] Dashboard home page -- clean entry point per PROJECT.md constraints
-- [ ] Search and filter on collection -- usability at scale
-
-### Add After Validation (v1.x)
-
-Features to add once core is working and the planning thread workflow is proven.
-
-- [ ] Impact preview ("this candidate adds +120g to your Summer Bikepacking setup") -- requires setups + threads to be stable
-- [ ] Status tracking on thread items (researching / ordered / arrived) -- lifecycle tracking
-- [ ] Priority/ranking within threads -- mark favorites among candidates
-- [ ] Photos per item -- visual identification, one photo per item initially
-- [ ] CSV import/export -- migration path from spreadsheets, data portability
-- [ ] Weight distribution visualization (pie/bar chart by category) -- polish feature
-
-### Future Consideration (v2+)
-
-Features to defer until product-market fit is established.
-
-- [ ] Multi-photo gallery per item -- storage and UI complexity
-- [ ] Shareable read-only links for setups -- lightweight sharing without auth
-- [ ] Drag-and-drop reordering in lists and setups -- UX refinement
-- [ ] Bulk operations (multi-select, bulk categorize, bulk delete) -- power user feature
-- [ ] Dark mode -- common request, low priority for initial launch
-- [ ] Item history / changelog (track weight after modifications, price changes) -- advanced tracking
-
-## Feature Prioritization Matrix
-
-| Feature | User Value | Implementation Cost | Priority |
-|---------|------------|---------------------|----------|
-| Item CRUD with core fields | HIGH | LOW | P1 |
-| Categories | HIGH | LOW | P1 |
-| Weight unit support | HIGH | LOW | P1 |
-| Auto weight/cost totals | HIGH | LOW | P1 |
-| Named setups | HIGH | MEDIUM | P1 |
-| Planning threads | HIGH | HIGH | P1 |
-| Candidate comparison | HIGH | MEDIUM | P1 |
-| Thread resolution | HIGH | MEDIUM | P1 |
-| Dashboard home | MEDIUM | LOW | P1 |
-| Search and filter | MEDIUM | LOW | P1 |
-| Impact preview | HIGH | MEDIUM | P2 |
-| Status tracking (threads) | MEDIUM | LOW | P2 |
-| Priority/ranking (threads) | MEDIUM | LOW | P2 |
-| Photos per item | MEDIUM | MEDIUM | P2 |
-| CSV import/export | MEDIUM | MEDIUM | P2 |
-| Weight visualization charts | MEDIUM | MEDIUM | P2 |
-| Multi-photo gallery | LOW | MEDIUM | P3 |
-| Shareable links | LOW | MEDIUM | P3 |
-| Drag-and-drop reordering | LOW | MEDIUM | P3 |
-| Bulk operations | LOW | MEDIUM | P3 |
-
-**Priority key:**
-- P1: Must have for launch
-- P2: Should have, add when possible
-- P3: Nice to have, future consideration
-
-## Competitor Feature Analysis
-
-| Feature | LighterPack | GearGrams | Packstack | Hikt | GearBox (Our Approach) |
-|---------|-------------|-----------|-----------|------|------------------------|
-| Gear inventory | Per-list only (no central closet) | Central library + lists | Full gear library | Full closet with search | Full collection as central source of truth |
-| Weight tracking | Excellent -- base/worn/consumable splits, pie charts | Good -- multi-unit, category totals | Good -- base/worn/consumable | Excellent -- smart insights | Base/worn/consumable with unit flexibility |
-| Packing lists / setups | Unlimited lists (web) | Multiple lists via drag-drop | Trip-based (2 free) | 3 free lists, more with premium | Named setups composed from collection |
-| Purchase planning | None | None | None | None | Planning threads with candidates, comparison, resolution -- unique |
-| Impact analysis | None | None | None | None | Show how a candidate changes setup weight/cost -- unique |
-| Photos | None | None | None | Yes | Yes (v1.x) |
-| Import/export | None (copy-linked lists only) | CSV import | None mentioned | LighterPack import, CSV | CSV import/export (v1.x) |
-| Mobile | No native app (web only, poor mobile UX) | Web only | iOS only | iOS + Android + web | Web-first, responsive design |
-| Sharing | Shareable links | None mentioned | Shareable trip links | Community lists, collaboration | Deferred (v2+, read-only links) |
-| Hobby scope | Hiking/backpacking only | Hiking/backpacking only | Hiking/backpacking only | Hiking/backpacking only | Any hobby (bikepacking, sim racing, photography, etc.) |
-| Pricing | Free | Free | Freemium (2 lists free) | Freemium (3 lists free) | Single-user, no tiers |
-| Status | Open source, aging, no mobile | Maintained but dated | Active development | Actively developed, modern | New entrant with unique purchase planning angle |
+| Feature | Schema Change | API Change | New Dependency | UI Scope | Overall |
+|---------|---------------|------------|----------------|----------|---------|
+| Search & Filter | None | None | None | Collection view only | LOW |
+| Weight Unit Selection | None (uses settings) | None (settings API exists) | None | All weight displays (~8 components) | LOW |
+| Candidate Status Tracking | `thread_candidates.status` column | Update candidate CRUD | None | CandidateCard, CandidateForm | LOW |
+| Planning Category Filter | None | None | None | PlanningView dropdown | LOW |
+| Weight Classification | `setup_items.classification` column | Update setup sync + detail endpoints | None | Setup detail view | MEDIUM |
+| Weight Distribution Chart | None | Possibly new totals endpoint | react-minimal-pie-chart (~2kB) | New chart component | MEDIUM |
 
 ## Sources
 
-- [LighterPack](https://lighterpack.com/) -- free web-based gear list tool, community standard
-- [GearGrams](https://www.geargrams.com/) -- drag-and-drop gear library with multi-unit support
-- [Packstack](https://www.packstack.io/) -- trip-centric gear management with weather integration
-- [Hikt](https://hikt.app/) -- modern gear manager with mobile apps and community features
-- [Hikt Blog: Best Backpacking Gear Apps 2026](https://hikt.app/blog/best-backpacking-gear-apps-2026/) -- competitive comparison
-- [HikeLite](https://hikeliteapp.com/) -- ultralight gear management with CSV support
-- [Packrat](https://www.packrat.app/) -- iOS/Android gear inventory with CSV/JSON import
-- [LighterPack GitHub Issues](https://github.com/galenmaly/lighterpack/issues) -- user feature requests and limitations
-- [Palespruce Bikepacking Gear Spreadsheet](http://www.palespruce.com/bikepacking-gear-spreadsheet/) -- spreadsheet workflow GearBox replaces
-- [99Boulders Backpacking Gear List Spreadsheet](https://www.99boulders.com/backpacking-gear-list-spreadsheet) -- spreadsheet workflow patterns
+- [LighterPack](https://lighterpack.com/) -- weight classification and pie chart visualization patterns
+- [LighterPack Tutorial (99Boulders)](https://www.99boulders.com/lighterpack-tutorial) -- detailed feature walkthrough
+- [LighterPack Tutorial (Backpackers.com)](https://backpackers.com/blog/how-to-calculate-backpack-weight-with-lighterpack/) -- base/worn/consumable definitions
+- [Hikt](https://hikt.app/) -- searchable gear closet, base vs worn weight display
+- [PackLight (iOS)](https://apps.apple.com/us/app/packlight-for-backpacking/id1054845207) -- search, custom categories, bar graph visualization
+- [Packstack](https://www.packstack.io/) -- base/worn/consumable weight separation
+- [HikeLite](https://hikeliteapp.com/) -- worn weight marking, CSV import format
+- [Packrat](https://www.packrat.app/) -- flexible weight unit input and display conversion
+- [BPL Calculator Forum Discussion](https://backpackinglight.com/forums/topic/new-backpacking-hiking-weight-calculator-app/) -- unit conversion UX, search filter patterns
+- [react-minimal-pie-chart (GitHub)](https://github.com/toomuchdesign/react-minimal-pie-chart) -- 2kB lightweight chart library
+- [Best React Chart Libraries 2025 (LogRocket)](https://blog.logrocket.com/best-react-chart-libraries-2025/) -- chart library comparison
+- [LighterPack GitHub Issues](https://github.com/galenmaly/lighterpack/issues) -- user feature requests
+- [OutPack](https://outpack.app/) -- modern LighterPack alternative with category breakdown graphs
+- [Pack Weight Calculator Guide (BackpackPeek)](https://backpackpeek.com/blog/pack-weight-calculator-base-weight-guide) -- base weight calculation methodology
 
 ---
-*Feature research for: Gear management and purchase planning*
-*Researched: 2026-03-14*
+*Feature research for: v1.2 Collection Power-Ups (search/filter, weight classification, visualization, candidate status, weight units)*
+*Researched: 2026-03-16*

.planning/research/PITFALLS.md

@@ -1,136 +1,202 @@
 # Pitfalls Research
 
-**Domain:** Gear management, collection tracking, purchase planning (single-user web app)
-**Researched:** 2026-03-14
-**Confidence:** HIGH (domain-specific patterns well-documented across gear community and inventory app space)
+**Domain:** Adding search/filter, weight classification, weight distribution charts, candidate status tracking, and weight unit selection to an existing gear management app (GearBox v1.2)
+**Researched:** 2026-03-16
+**Confidence:** HIGH (pitfalls derived from direct codebase analysis + domain-specific patterns from gear tracking community + React/SQLite ecosystem knowledge)
 
 ## Critical Pitfalls
 
-### Pitfall 1: Unit Handling Treated as Display-Only
+### Pitfall 1: Weight Unit Conversion Rounding Accumulation
 
 **What goes wrong:**
-Weight and price values are stored as bare numbers without unit metadata. The app assumes everything is grams or dollars, then breaks when users enter ounces, pounds, kilograms, or foreign currencies. Worse: calculations like "total setup weight" silently produce garbage when items have mixed units. A 200g tent and a 5lb sleeping bag get summed as 205.
+GearBox stores weight as `real("weight_grams")` (a floating-point column in SQLite). When adding unit selection (g, oz, lb, kg), the naive approach is to convert on display and let users input in their preferred unit, converting back to grams on save. The problem: repeated round-trip conversions accumulate rounding errors. A user enters `5.3 oz`, which converts to `150.253...g`, gets stored as `150.253`, then displayed back as `5.30 oz` (fine so far). But if the user opens the edit form (which shows `5.30 oz`), makes no changes, and saves, the value reconverts from the displayed `5.30` to `150.2535g` -- a different value from what was stored. Over multiple edit cycles, weights drift. More critically, the existing `SUM(items.weight_grams)` aggregates in `setup.service.ts` and `totals.service.ts` will accumulate these micro-errors across dozens of items, producing totals that visibly disagree with manual addition of displayed values. A setup showing items of "5.3 oz + 2.1 oz" but a total of "7.41 oz" (instead of 7.40 oz) erodes trust in the app's core value proposition.
 
 **Why it happens:**
-In a single-user app it feels safe to skip unit handling -- "I'll just always use grams." But real product specs come in mixed units (manufacturers list in oz, g, kg, lb), and copy-pasting from product pages means mixed data creeps in immediately.
+The conversion factor between grams and ounces (28.3495) is irrational enough that floating-point representation always involves truncation. Combined with SQLite's `REAL` type (8-byte IEEE 754 float, ~15 digits of precision), individual items are accurate enough, but the accumulation across conversions and summation surfaces visible errors.
 
 **How to avoid:**
-Store all weights in a canonical unit (grams) at write time. Accept input in any unit but convert on save. Store the original unit for display purposes but always compute on the canonical value. Build a simple conversion layer from day one -- it is 20 lines of code now vs. a data migration later.
+1. Store weights in grams as the canonical unit -- this is already done. Good.
+2. Convert only at the display boundary (the `formatWeight` function in `lib/formatters.ts`). Never convert grams to another unit, let the user edit, and convert back.
+3. When the user inputs in oz/lb/kg, convert to grams once on save and store. The edit form should always load the stored grams value and re-convert for display, never re-convert from a previously displayed value.
+4. Round only at the final display step, not during storage. Use `Number(value.toFixed(1))` for display, never for the stored value.
+5. For totals, compute `SUM(weight_grams)` in SQL (already done), then convert the total to display units once. Do not sum converted per-item display values.
+6. Consider changing `weight_grams` from `real` to `integer` to store milligrams (or tenths of grams) for sub-gram precision without floating-point issues. This is a larger migration but eliminates the class of errors entirely.
 
 **Warning signs:**
-- Weight field is a plain number input with no unit selector
-- No conversion logic exists anywhere in the codebase
-- Aggregation functions (total weight) do simple `SUM()` without unit awareness
+- Edit form pre-fills with a converted value and saves by reconverting that value
+- `formatWeight` is called before summation rather than after
+- Unit conversion is done in multiple places (client and server) with different rounding
+- Tests compare floating-point totals with `===` instead of tolerance-based comparison
 
 **Phase to address:**
-Phase 1 (Data model / Core CRUD) -- unit handling must be in the schema from the start. Retrofitting requires migrating every existing item.
+Phase 1 (Weight unit selection) -- the conversion layer must be designed correctly from the start. Getting this wrong poisons every downstream feature (charts, setup totals, classification breakdowns).
 
 ---
 
-### Pitfall 2: Rigid Category Hierarchy Instead of Flexible Tagging
+### Pitfall 2: Weight Classification Stored at Wrong Level
 
 **What goes wrong:**
-The app ships with a fixed category tree (Shelter > Tents > 1-Person Tents) that works for bikepacking but fails for sim racing gear, photography equipment, or any other hobby. Users cannot create categories, and items that span categories (a jacket that is both "clothing" and "rain gear") get awkwardly forced into one slot. The "generic enough for any hobby" goal from PROJECT.md dies on contact with a rigid hierarchy.
+Weight classification (base weight / worn / consumable) seems like a property of the item itself -- "my rain jacket is always worn weight." So the developer adds a `classification` column to the `items` table. But this is wrong: the same item can be classified differently in different setups. A rain jacket is "worn" in a summer bikepacking setup but "base weight" (packed in the bag) in a winter setup where you wear a heavier outer shell. By putting classification on the item, users cannot accurately model multiple setups with the same gear, which is the entire point of the setup feature.
 
 **Why it happens:**
-Hierarchical categories feel structured and "correct" during design. Flat tags feel messy. But hierarchies require knowing the domain upfront, and GearBox explicitly needs to support arbitrary hobbies.
+LighterPack and similar tools model classification at the list level (each list has its own classification per item), but when you look at the GearBox schema, the `setup_items` join table only has `(id, setup_id, item_id)`. It feels more natural to add a column to the item itself rather than to a join table, especially since the current `setup_items` table is minimal. The single-user context also makes it feel like "my items have fixed classifications."
 
 **How to avoid:**
-Use a flat tag/label system as the primary organization mechanism. Users create their own tags ("bikepacking", "sleep-system", "cook-kit"). An item can have multiple tags. Optionally allow a single "category" field for broad grouping, but do not enforce hierarchy. Tags are the flexible axis; a single category field is the structured axis.
+Add `classification TEXT DEFAULT 'base'` to the `setup_items` table, not to `items`. This means:
+- The same item can have different classifications in different setups
+- Classification is optional and defaults to "base" (the most common case)
+- The `items` table stays generic -- classification is a setup-level concern
+- Existing `setup_items` rows get a sensible default via the migration
+- SQL aggregates for setup totals can easily group by classification: `SUM(CASE WHEN setup_items.classification = 'base' THEN items.weight_grams ELSE 0 END)`
+
+If classification is also useful outside of setups (e.g., in the collection view for a general breakdown), add it as an optional `defaultClassification` on `items` that serves as a hint when adding items to setups, but the authoritative classification is always on `setup_items`.
 
 **Warning signs:**
-- Schema has a `category_id` foreign key to a `categories` table with `parent_id`
-- Seed data contains a pre-built category tree
-- Adding a new hobby requires modifying the database
+- `classification` column added to `items` table
+- Setup detail view shows classification but cannot be different per setup
+- Weight breakdown chart shows the same classification for an item across all setups
+- No way to classify an item as "worn" in one setup and "base" in another
 
 **Phase to address:**
-Phase 1 (Data model) -- this is a schema-level decision. Changing from hierarchy to tags after data exists requires migration of every item's categorization.
+Phase 2 (Weight classification) -- this is the single most important schema decision in v1.2. Getting it wrong requires migrating data out of the `items` table into `setup_items` later, which means reconciling possibly-different classifications that users already set.
 
 ---
 
-### Pitfall 3: Planning Thread State Machine Complexity Explosion
+### Pitfall 3: Search/Filter Implemented Server-Side for a Client-Side Dataset
 
 **What goes wrong:**
-Thread items have statuses (researching, ordered, arrived) plus a thread-level resolution (pick winner, close thread, move to collection). Developers build these as independent fields without modeling the valid state transitions, leading to impossible states: an item marked "arrived" in a thread that was "cancelled," or a "winner" that was never "ordered." The UI then needs defensive checks everywhere, and bugs appear as ghost items in the collection.
+The developer adds a `GET /api/items?search=tent&category=3` endpoint, sending filtered results from the server. This means:
+- Every keystroke fires an API request (or requires debouncing, adding latency)
+- The client's React Query cache for `["items"]` now contains different data depending on filter params, causing stale/inconsistent state
+- Category grouping in `CollectionView` breaks because the full list is no longer available
+- The existing `useTotals()` hook returns totals for all items, but the list shows filtered items -- a confusing mismatch
 
 **Why it happens:**
-Status tracking looks simple -- it is just a string field. But the combination of item-level status + thread-level lifecycle + the "move winner to collection" side effect creates a state machine with many transitions, and without explicit modeling, invalid states are reachable.
+Server-side filtering is the "correct" pattern at scale, and most tutorials teach it that way. But GearBox is a single-user app where the entire collection fits comfortably in memory. The existing `useItems()` hook already fetches all items in one call and the collection view groups them client-side.
 
 **How to avoid:**
-Model the thread lifecycle as an explicit state machine with defined transitions. Document which item statuses are valid in each thread state. The "resolve thread" action should be a single transaction that: (1) validates the winner exists, (2) creates the collection item, (3) marks the thread as resolved, (4) updates the thread item status. Use a state diagram during design, not just field definitions.
+Implement search and filter entirely on the client side:
+1. Keep `useItems()` fetching the full list (it already does)
+2. Add filter state (search query, category ID) as URL search params or React state in the collection page
+3. Filter the `items` array in the component using `Array.filter()` before grouping and rendering
+4. The totals bar should continue to show collection totals (unfiltered), not filtered totals -- or show both ("showing 12 of 47 items")
+5. Only move to server-side filtering if the collection exceeds ~500 items, which is far beyond typical for a single-user gear app
+
+This preserves the existing caching behavior, requires zero API changes, and gives instant feedback on every keystroke.
 
 **Warning signs:**
-- Thread status and item status are independent string/enum fields with no transition validation
-- No transaction wrapping the "resolve thread + create collection item" flow
-- UI shows impossible combinations (resolved thread with "researching" items)
+- New query parameters added to `GET /api/items` endpoint
+- `useItems` hook accepts filter params, creating multiple cache entries
+- Search input has a debounce delay
+- Filtered view totals disagree with dashboard totals
 
 **Phase to address:**
-Phase 2 (Planning threads) -- design the state machine before writing any thread code. Do not add statuses incrementally.
+Phase 1 (Search/filter) -- the decision to filter client-side vs server-side affects where state lives and must be decided before building the UI.
 
 ---
 
-### Pitfall 4: Image Storage Strategy Causes Data Loss or Bloat
+### Pitfall 4: Candidate Status Transition Without Validation
 
 **What goes wrong:**
-Two failure modes: (A) Images stored as file paths break when files are moved, deleted, or the app directory changes. Dangling references show broken image icons everywhere. (B) Images stored as BLOBs in SQLite bloat the database, slow down backups, and make the DB file unwieldy as the collection grows.
+The existing thread system has a simple `status: "active" | "resolved"` on threads and no status on candidates. Adding candidate status tracking (researching -> ordered -> arrived) as a simple text column without transition validation allows impossible states: a candidate marked "arrived" in a thread that was already "resolved," or a candidate going from "arrived" back to "researching." Worse, the existing `resolveThread` function in `thread.service.ts` copies candidate data to create a collection item -- but does not check or update candidate status, so a "researching" candidate can be resolved as the winner (logically wrong, though the data flow works).
 
 **Why it happens:**
-Image storage seems like a simple problem. File paths are the obvious approach but create a coupling between database records and filesystem state. BLOBs seem self-contained but do not scale with photo-heavy collections.
+The current codebase uses plain strings for thread status with no validation layer. The developer follows the same pattern for candidate status: just a text column with no constraints. SQLite does not enforce enum values, so any string is accepted.
 
 **How to avoid:**
-Store images in a dedicated directory within the app's data folder (e.g., `data/images/{item-id}/`). Store relative paths in the database (never absolute). Generate deterministic filenames from item ID + timestamp to avoid collisions. On item deletion, clean up the image directory. For thumbnails under 100KB, SQLite BLOBs are actually 35% faster than filesystem reads, so consider storing thumbnails as BLOBs while keeping full-size images on disk.
+1. Define valid candidate statuses as a union type: `"researching" | "ordered" | "arrived"` in `schemas.ts`
+2. Add Zod validation for the status field with `.refine()` or `z.enum()` to reject invalid values at the API level
+3. Define valid transitions: `researching -> ordered -> arrived` (and optionally `* -> dropped`)
+4. In the service layer, validate that the requested status transition is valid before applying it (e.g., cannot go from "arrived" to "researching")
+5. When resolving a thread, do NOT require a specific candidate status -- the user may resolve with a "researching" candidate if they decide to buy it outright. But DO update all non-winner candidates to a terminal state like "dropped" in the same transaction.
+6. Add a check in `resolveThread`: if the thread is already resolved, reject the operation (this check already exists in the current code -- good)
 
 **Warning signs:**
-- Absolute file paths in the database
-- No cleanup logic when items are deleted (orphaned images accumulate)
-- Database file growing much larger than expected (images stored as BLOBs)
-- No fallback/placeholder when an image file is missing
+- Candidate status is a plain `text()` column with no Zod enum validation
+- No transition validation in the update candidate service
+- `resolveThread` does not update non-winner candidate statuses
+- UI allows arbitrary status changes via a dropdown with no constraints
 
 **Phase to address:**
-Phase 1 (Core CRUD with item photos) -- image handling must be decided before any photos are stored. Migrating image storage strategy later requires moving files and updating every record.
+Phase 3 (Candidate status tracking) -- must be designed with awareness of the existing thread resolution flow in `thread.service.ts`. The status field and transition logic should be added together, not incrementally.
 
 ---
 
-### Pitfall 5: Setup Composition Breaks on Collection Changes
+### Pitfall 5: Weight Distribution Chart Diverges from Displayed Totals
 
 **What goes wrong:**
-A setup ("Summer Bikepacking") references items from the collection. When an item is deleted from the collection, updated, or replaced via a planning thread resolution, the setup silently breaks -- showing stale data, missing items, or incorrect totals. The user's carefully composed setup becomes untrustworthy.
+The weight distribution chart (e.g., a donut chart showing weight by category or by classification) computes its data from one source, while the totals bar and setup detail page compute from another. The chart might use client-side summation of displayed (rounded) values while the totals use SQL `SUM()`. Or the chart uses the `useTotals()` hook data while the setup page computes totals inline (as `$setupId.tsx` currently does on lines 53-61). These different computation paths produce different numbers for the same data, and when a chart slice says "Shelter: 2,450g" but the category header says "Shelter: 2,451g," users lose trust.
 
 **Why it happens:**
-Setups are modeled as a simple join table (setup_id, item_id) without considering what happens when the item side changes. The relationship is treated as static when it is actually dynamic.
+The codebase already has two computation paths for totals: `totals.service.ts` computes via SQL aggregates, and the setup detail page computes via JavaScript reduce on the client. These happen to agree now because there is no unit conversion, but adding unit display and classification filtering creates more opportunities for divergence.
 
 **How to avoid:**
-Use foreign keys with explicit `ON DELETE` behavior (not CASCADE -- that silently removes setup entries). When an item is deleted, mark the setup-item link as "removed" and show a visual indicator in the setup view ("1 item no longer in collection"). When a planning thread resolves and replaces an item, offer to update setups that contained the old item. Setups should always recompute totals from live item data, never cache them.
+1. Establish a single source of truth for all weight computations: the SQL aggregate in the service layer.
+2. For chart data, create a dedicated endpoint or extend `GET /api/totals` to return breakdowns by category AND by classification (for setups). Do not recompute in the chart component.
+3. For setup-specific charts, extend `getSetupWithItems` to return pre-computed breakdowns, or compute them from the setup's item list using a shared utility function that is used by both the totals display and the chart.
+4. Unit conversion happens once, at the display layer, using the same `formatWeight` function everywhere.
+5. Write a test that compares the chart data source against the totals data source and asserts they agree.
 
 **Warning signs:**
-- Setup totals are stored as columns rather than computed from item data
-- No foreign key constraints between setups and items
-- Deleting a collection item does not check if it belongs to any setup
-- No UI indication when a setup references a missing item
+- Chart component does its own `reduce()` on item data instead of using the same data as the totals display
+- Two different API endpoints return weight totals for the same scope and the values differ by small amounts
+- Chart labels show different precision than text displays (chart: "2.4 kg", header: "2,451 g")
+- No shared utility function for weight summation
 
 **Phase to address:**
-Phase 3 (Setups) -- but the foreign key design must be planned in Phase 1 when the items table is created. The item schema needs to anticipate setup references.
+Phase 3 (Weight distribution visualization) -- but the single-source-of-truth pattern should be established in Phase 1 when refactoring formatters for unit selection.
 
 ---
 
-### Pitfall 6: Comparison View That Does Not Actually Help Decisions
+### Pitfall 6: Schema Migration Breaks Test Helper
 
 **What goes wrong:**
-The side-by-side comparison in planning threads shows raw data (weight: 450g, price: $120) without context. Users cannot see at a glance which candidate is lighter, cheaper, or how each compares to what they already own. The comparison becomes a formatted table, not a decision tool. Users go back to their spreadsheet because it was easier to add formulas.
+GearBox's test infrastructure uses a manual `createTestDb()` function in `tests/helpers/db.ts` that creates tables with raw SQL `CREATE TABLE` statements instead of using Drizzle's migration system. When adding new columns (e.g., `classification` to `setup_items`, `status` to `thread_candidates`, `weight_unit` to `settings`), the developer updates `src/db/schema.ts` and runs `bun run db:generate` + `bun run db:push`, but forgets to update the test helper's CREATE TABLE statements. All tests pass in the test database (which has the old schema) while the real database has the new schema -- or worse, tests fail with cryptic column-not-found errors and the developer wastes time debugging the wrong thing.
 
 **Why it happens:**
-Building a comparison view that displays data is easy. Building one that surfaces insights ("this is 30% lighter than your current tent but costs 2x more") requires computing deltas against the existing collection, which is a different feature than just showing two items side by side.
+The test helper duplicates the schema definition in raw SQL rather than deriving it from the Drizzle schema. This is a known pattern in the codebase (documented in CLAUDE.md: "When adding schema columns, update both `src/db/schema.ts` and the test helper's CREATE TABLE statements"). But under the pressure of adding multiple schema changes across several features, it is easy to miss one table or one column.
 
 **How to avoid:**
-Design comparison views to show: (1) absolute values for each candidate, (2) deltas between candidates (highlighted: lighter/heavier, cheaper/more expensive), (3) delta against the current item being replaced from the collection. Use color coding or directional indicators (green down arrow for weight savings, red up arrow for cost increase). This is the core value proposition of GearBox -- do not ship a comparison that is worse than a spreadsheet.
+1. **Every schema change PR must include the corresponding test helper update.** Add this as a checklist item in the development workflow.
+2. Consider writing a simple validation test that compares the columns in `createTestDb()` tables against the Drizzle schema definition, failing if they diverge. This catches the problem automatically.
+3. For v1.2, since multiple schema changes are landing (classification on setup_items, status on candidates, possibly weight_unit in settings), batch the test helper update and verify all changes in one pass.
+4. Long-term: investigate using Drizzle's `migrate()` with in-memory SQLite to eliminate the duplication entirely.
 
 **Warning signs:**
-- Comparison view is a static table with no computed differences
-- No way to link a thread to "the item I'm replacing" from the collection
-- Weight/cost impact on overall setup is not visible from the thread view
+- Schema column added to `schema.ts` but not to `tests/helpers/db.ts`
+- Tests pass locally but queries fail at runtime
+- New service function works in the app but throws in tests
+- Test database has fewer columns than production database
 
 **Phase to address:**
-Phase 2 (Planning threads) -- comparison is the heart of the thread feature. Build the delta computation alongside the basic thread CRUD, not as a follow-up.
+Every phase that touches the schema. Must be addressed in Phase 1 (unit settings), Phase 2 (classification on setup_items), and Phase 3 (candidate status). Each phase should verify test helper parity as a completion criterion.
+
+---
+
+### Pitfall 7: Weight Unit Preference Stored Wrong, Applied Wrong
+
+**What goes wrong:**
+The developer stores the user's preferred weight unit as a setting (using the existing `settings` table with key-value pairs). But then applies it inconsistently: the collection page shows grams, the setup page shows ounces, the chart shows kilograms. Or the setting is read once on page load and cached in Zustand, so changing the preference requires a page refresh. Or the setting is read on every render, causing a flash of "g" before the "oz" preference loads.
+
+**Why it happens:**
+The `settings` table is a key-value store with no type safety. The preference is a string like `"oz"` that must be parsed and applied in many places: `formatWeight` in formatters, chart labels, totals bar, setup detail, item cards, category headers. Missing any one of these locations creates an inconsistency.
+
+**How to avoid:**
+1. Store the preference in the `settings` table as `{ key: "weightUnit", value: "g" | "oz" | "lb" | "kg" }`.
+2. Create a `useWeightUnit()` hook that wraps `useSettings()` and returns the parsed unit with a fallback to `"g"`.
+3. Modify `formatWeight` to accept a unit parameter: `formatWeight(grams, unit)`. This is a single function used everywhere, so changing it propagates automatically.
+4. Do NOT store converted values anywhere -- always store grams, convert at display time.
+5. Use React Query for the settings fetch so the preference is cached and shared across components. When the user changes their preference, invalidate `["settings"]` and all displays update simultaneously via React Query's reactivity.
+6. Handle the loading state: show raw grams (or a loading skeleton) until the preference is loaded. Do not flash a different unit.
+
+**Warning signs:**
+- `formatWeight` does not accept a unit parameter -- it is hardcoded to `"g"`
+- Weight unit preference is stored in Zustand instead of React Query (settings endpoint)
+- Some components use `formatWeight` and some inline their own formatting
+- Changing the unit preference does not update all visible weights without a page refresh
+
+**Phase to address:**
+Phase 1 (Weight unit selection) -- this is foundational infrastructure. The `formatWeight` refactor and `useWeightUnit` hook must exist before building any other feature that displays weight.
 
 ---
 
@@ -140,21 +206,24 @@ Shortcuts that seem reasonable but create long-term problems.
 
 | Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
 |----------|-------------------|----------------|-----------------|
-| Caching setup totals in a column | Faster reads, simpler queries | Stale data when items change, bugs when totals disagree with item sum | Never -- always compute from source items |
-| Storing currency as float | Simple to implement | Floating point rounding errors in price totals (classic $0.01 bugs) | Never -- use integer cents or a decimal type |
-| Skipping "replaced by" links in threads | Simpler thread resolution | Cannot track upgrade history, cannot auto-update setups | Only in earliest prototype, must add before thread resolution ships |
-| Hardcoding unit labels | Faster initial development | Cannot support multiple hobbies with different unit conventions (e.g., ml for water bottles) | MVP only if unit conversion layer is planned for next phase |
-| Single image per item | Simpler UI and storage | Gear often needs multiple angles, especially for condition tracking | Acceptable for v1 if schema supports multiple images (just limit UI to one) |
+| Adding classification to `items` instead of `setup_items` | Simpler schema, no join table changes | Cannot have different classifications per setup; future migration required | Never -- the per-setup model is the correct one |
+| Client-side unit conversion on both read and write paths | Simple bidirectional conversion | Rounding drift over edit cycles, inconsistent totals | Never -- convert once on write, display-only on read |
+| Separate chart data computation from totals computation | Faster chart development, no API changes | Numbers disagree between chart and text displays | Only if a shared utility function ensures identical computation |
+| Hardcoding chart library colors per category | Quick to implement | Colors collide when user adds categories; no dark mode support | MVP only if using a predictable color generation function is planned |
+| Adding candidate status without transition validation | Faster to implement | Invalid states accumulate, resolve logic has edge cases | Only if validation is added before the feature ships to production |
+| Debouncing search instead of client-side filter | Familiar pattern from server-filtered apps | Unnecessary latency, complex cache management | Never for this app's scale (sub-500 items) |
 
 ## Integration Gotchas
 
-Common mistakes when connecting to external services.
+Since v1.2 is adding features to an existing system rather than integrating external services, these are internal integration points where new features interact with existing ones.
 
-| Integration | Common Mistake | Correct Approach |
-|-------------|----------------|------------------|
-| Product link scraping | Attempting to auto-fetch product details from URLs, which breaks constantly as sites change layouts | Store the URL as a plain link. Do not scrape. Let users enter details manually. Scraping is a maintenance burden that exceeds its value for a single-user app. |
-| Image URLs vs local storage | Hotlinking product images from retailer sites, which break when products are delisted | Always download and store images locally. External URLs rot within months. |
-| Export/import formats | Building a custom JSON format that only GearBox understands | Support CSV import/export as the universal fallback. Users are migrating from spreadsheets -- CSV is their native format. |
+| Integration Point | Common Mistake | Correct Approach |
+|-------------------|----------------|------------------|
+| Search/filter + category grouping | Filtering items breaks the existing category-grouped layout because the group headers disappear when no items match | Filter within groups: show category headers only for groups with matching items. Empty groups should hide, not show "no items." |
+| Weight classification + existing setup totals | Adding classification changes how totals are computed (base weight vs total weight), but existing setup list cards show `totalWeight` which was previously "everything" | Keep `totalWeight` as the sum of all items. Add `baseWeight` as a new computed field (sum of items where classification = 'base'). Show both in the setup detail view. |
+| Candidate status + thread resolution | Adding status to candidates but not updating `resolveThread` to handle it | The `resolveThread` transaction must set winner status to a terminal state and non-winners to "dropped." New candidates added to an already-resolved thread should be rejected. |
+| Unit selection + React Query cache | Changing the weight unit preference does not invalidate the items cache because items are stored in grams regardless | The unit preference is a display concern, not a data concern. Do NOT invalidate items/totals on unit change. Just re-render with the new unit. Ensure `formatWeight` is called reactively, not cached. |
+| Weight chart + empty/null weights | Chart component crashes or shows misleading data when items have `null` weight | Filter out items with null weight from chart data. Show a note like "3 items excluded (no weight recorded)." Never treat null as 0 in a chart -- that makes the chart lie. |
 
 ## Performance Traps
 
@@ -162,10 +231,11 @@ Patterns that work at small scale but fail as usage grows.
 
 | Trap | Symptoms | Prevention | When It Breaks |
 |------|----------|------------|----------------|
-| Loading all collection items for every setup view | Slow page loads, high memory usage | Paginate collection views; setup views should query only member items | 500+ items in collection |
-| Recomputing all setup totals on every item edit | Edit latency increases linearly with number of setups | Only recompute totals for setups containing the edited item | 20+ setups referencing overlapping items |
-| Storing full-resolution photos without thumbnails | Page loads become unusably slow when browsing collection | Generate thumbnails on upload; use thumbnails in list views, full images only in detail view | 50+ items with photos |
-| Loading all thread candidates for comparison | Irrelevant for small threads, but threads can accumulate many "considered" items | Limit comparison view to 3-4 selected candidates; archive dismissed ones | 15+ candidates in a single thread |
+| Re-rendering entire collection on search keystroke | UI jank on every character typed in search box | Use `useMemo` to memoize the filtered list; ensure `ItemCard` is memoized with `React.memo` | 100+ items with images |
+| Chart re-renders on every parent state change | Chart animation restarts on unrelated state updates (e.g., opening a panel) | Memoize chart data computation with `useMemo`; wrap chart component in `React.memo`; use `isAnimationActive={false}` after initial render | Any chart library with entrance animations |
+| Recharts SVG rendering with many category slices | Donut chart becomes sluggish with 20+ categories, each with a tooltip and label | Limit chart to top N categories by weight, group the rest into "Other." Recharts is SVG-based, so keep segments under ~15. | 20+ categories (unlikely for single user, but possible) |
+| Fetching settings on every component that displays weight | Waterfall of settings requests, or flash of unconverted weights | Use React Query with `staleTime: Infinity` for settings (they change rarely). Prefetch settings at app root. | First load of any page with weights |
+| Computing classification breakdown per-render | Expensive reduce operations on every render cycle | Compute once in `useMemo` keyed on the items array and classification data | Setups with 50+ items (common for full bikepacking lists) |
 
 ## Security Mistakes
 
@@ -173,9 +243,9 @@ Domain-specific security issues beyond general web security.
 
 | Mistake | Risk | Prevention |
 |---------|------|------------|
-| No backup mechanism for SQLite database | Single file corruption = total data loss of entire collection | Implement automatic periodic backups (copy the .db file). Provide a manual "export all" button. Single-user apps have no server-side backup by default. |
-| Product URLs stored without sanitization | Stored URLs could contain javascript: protocol or XSS payloads if rendered as links | Validate URLs on save (must be http/https). Render with `rel="noopener noreferrer"`. |
-| Image uploads without size/type validation | Malicious or accidental upload of huge files or non-image files | Validate file type (accept only jpg/png/webp) and enforce max size (e.g., 5MB) on upload. |
+| Candidate status field accepts arbitrary strings | SQLite text column accepts anything; UI may display unexpected values or XSS payloads in status badges | Validate status against enum in Zod schema. Reject unknown values at API level. Use `z.enum(["researching", "ordered", "arrived"])`. |
+| Search query used in raw SQL LIKE | SQL injection if search string is interpolated into query (unlikely with Drizzle ORM but possible in raw SQL aggregates) | Use Drizzle's `like()` or `ilike()` operators which parameterize automatically. Never use template literals in `sql\`\`` with unsanitized user input. |
+| Unit preference allows arbitrary values | Settings table stores any string; a crafted value could break formatWeight or cause display issues | Validate unit against `z.enum(["g", "oz", "lb", "kg"])` both on read and write. Use a typed constant for the allowed values. |
 
 ## UX Pitfalls
 
@@ -183,25 +253,28 @@ Common user experience mistakes in this domain.
 
 | Pitfall | User Impact | Better Approach |
 |---------|-------------|-----------------|
-| Requiring all fields to add an item | Users abandon data entry because they do not know the weight or price yet for items they already own | Only require name. Make weight, price, category, etc. optional. Users fill in details over time. |
-| No bulk operations for collection management | Adding 30 existing items one-by-one is painful enough that users never finish initial setup | Provide CSV import for initial collection population. Consider a "quick add" mode with minimal fields. |
-| Thread resolution is destructive | User resolves a thread and loses all the research notes and rejected candidates | Archive resolved threads, do not delete them. Users want to reference why they chose item X over Y months later. |
-| Flat item list with no visual grouping | Collection becomes an unscannable wall of text at 50+ items | Group by tag/category in the default view. Provide sort options (weight, price, date added). Show item thumbnails in list view. |
-| Weight displayed without context | "450g" means nothing without knowing if that is heavy or light for this category | Show weight relative to the lightest/heaviest item in the same category, or relative to the item being replaced |
-| No "undo" for destructive actions | Accidental deletion of an item with detailed notes is unrecoverable | Soft-delete with a 30-day trash, or at minimum a confirmation dialog that names the item being deleted |
+| Search clears when switching tabs (gear/planning/setups) | User searches for "tent," switches to planning to check threads, switches back and search is gone | Persist search query as a URL search parameter (`?tab=gear&q=tent`). TanStack Router already handles tab via search params. |
+| Unit selection buried in settings page | User cannot quickly toggle between g and oz when comparing products listed in different units | Add a unit toggle/selector directly in the weight display area (e.g., in the TotalsBar or a small dropdown next to weight values). Keep global preference in settings, but allow quick access. |
+| Classification picker adds friction to setup composition | User must classify every item when adding it to a setup, turning a quick "add to loadout" into a tedious process | Default all items to "base" classification. Allow bulk reclassification. Show classification as an optional second step after composing the setup. |
+| Chart with no actionable insight | A pie chart showing "Shelter: 40%, Sleep: 25%, Cooking: 20%" is pretty but does not help the user make decisions | Pair the chart with a list sorted by weight. Highlight the heaviest category. If possible, show how the breakdown compares to "typical" or to other setups. At minimum, make chart segments clickable to filter to that category. |
+| Status badges with no timestamps | User sees "ordered" but cannot remember when they ordered, or whether it has been suspiciously long | Store status change timestamps. Show relative time ("ordered 3 days ago"). Highlight statuses that have been stale too long ("ordered 30+ days ago -- still waiting?"). |
+| Filter resets feel destructive | User applies multiple filters (category + search), then accidentally clears one and loses the other | Show active filters as dismissible chips/pills above the list. Each filter is independently clearable. A "clear all" button resets everything. |
 
 ## "Looks Done But Isn't" Checklist
 
 Things that appear complete but are missing critical pieces.
 
-- [ ] **Item CRUD:** Often missing image cleanup on delete -- verify orphaned images are removed when items are deleted
-- [ ] **Planning threads:** Often missing the "link to existing collection item being replaced" -- verify threads can reference what they are upgrading
-- [ ] **Setup composition:** Often missing recomputation on item changes -- verify that editing an item's weight updates all setups containing it
-- [ ] **CSV import:** Often missing unit detection/conversion -- verify that importing "5 oz" vs "142g" both result in correct canonical storage
-- [ ] **Thread resolution:** Often missing setup propagation -- verify that resolving a thread and adding the winner to collection offers to update setups that contained the replaced item
-- [ ] **Comparison view:** Often missing delta computation -- verify that the comparison shows differences between candidates, not just raw values side by side
-- [ ] **Dashboard totals:** Often missing staleness handling -- verify dashboard stats reflect current data, not cached snapshots
-- [ ] **Item deletion:** Often missing setup impact check -- verify the user is warned "This item is in 3 setups" before confirming deletion
+- [ ] **Search/filter:** Often missing keyboard shortcut (Cmd/Ctrl+K to focus search) -- verify search is easily accessible without mouse
+- [ ] **Search/filter:** Often missing empty state for "no results" -- verify a helpful message appears when search matches nothing, distinct from "collection is empty"
+- [ ] **Weight classification:** Often missing the per-setup model -- verify the same item can have different classifications in different setups
+- [ ] **Weight classification:** Often missing "unclassified" handling -- verify items with no classification default to "base" in all computations
+- [ ] **Weight chart:** Often missing null-weight items -- verify items without weight data are excluded from chart with a visible note, not silently treated as 0g
+- [ ] **Weight chart:** Often missing responsiveness -- verify chart renders correctly on mobile widths (Recharts needs `ResponsiveContainer` wrapper)
+- [ ] **Candidate status:** Often missing transition validation -- verify a candidate cannot go from "arrived" back to "researching"
+- [ ] **Candidate status:** Often missing integration with thread resolution -- verify resolving a thread updates all candidate statuses appropriately
+- [ ] **Unit selection:** Often missing consistent application -- verify every weight display in the app (cards, headers, totals, charts, setup detail, item picker) uses the selected unit
+- [ ] **Unit selection:** Often missing the edit form -- verify the item/candidate edit form shows weight in the selected unit and converts correctly on save
+- [ ] **Unit selection:** Often missing chart axis labels -- verify the chart shows the correct unit in labels and tooltips
 
 ## Recovery Strategies
 
@@ -209,12 +282,13 @@ When pitfalls occur despite prevention, how to recover.
 
 | Pitfall | Recovery Cost | Recovery Steps |
 |---------|---------------|----------------|
-| Mixed units without conversion | MEDIUM | Add unit column to items table. Write a migration script that prompts user to confirm/correct units for existing items. Recompute all setup totals. |
-| Rigid category hierarchy | HIGH | Migrate categories to tags (each leaf category becomes a tag). Update all item references. Redesign category UI to tag-based UI. |
-| Thread state machine bugs | MEDIUM | Audit all threads for impossible states. Write a cleanup script. Add transition validation. Retest all state transitions. |
-| Image path breakage | LOW-MEDIUM | Write a script that scans DB for broken image paths. Move images to canonical location. Update paths. Add fallback placeholder. |
-| Stale setup totals | LOW | Drop cached total columns. Replace with computed queries. One-time migration, no data loss. |
-| Currency as float | MEDIUM | Multiply all price values by 100, change column type to integer (cents). Rounding during conversion may lose sub-cent precision. |
+| Classification on items instead of setup_items | HIGH | Add classification column to setup_items. Write migration to copy item classification to all setup_item rows referencing it. Remove classification from items. Review all service queries. |
+| Rounding drift from bidirectional conversion | MEDIUM | Audit all items for drift (compare stored grams to expected values). Fix formatWeight to convert only at display. One-time data cleanup for items with suspicious fractional grams. |
+| Chart data disagrees with totals | LOW | Refactor chart to use the same data source as totals. Create shared utility. No data migration needed. |
+| Test helper out of sync with schema | LOW | Update CREATE TABLE statements in test helper. Run all tests. Fix any that relied on the old schema. |
+| Server-side search causing cache issues | MEDIUM | Revert to client-side filtering. Remove query params from useItems. May need to clear stale React Query cache entries with different keys. |
+| Candidate status without transitions | MEDIUM | Add transition validation to update endpoint. Audit existing candidates for invalid states. Write cleanup migration if needed. |
+| Unit preference inconsistently applied | LOW | Audit all weight display points. Ensure all use formatWeight with unit parameter. No data changes needed. |
 
 ## Pitfall-to-Phase Mapping
 
@@ -222,28 +296,27 @@ How roadmap phases should address these pitfalls.
 
 | Pitfall | Prevention Phase | Verification |
 |---------|------------------|--------------|
-| Unit handling | Phase 1: Data model | Schema stores canonical grams + original unit. Conversion utility exists with tests. |
-| Category rigidity | Phase 1: Data model | Items have a tags array/join table. No hierarchical category table exists. |
-| Image storage | Phase 1: Core CRUD | Images stored in `data/images/` with relative paths. Thumbnails generated on upload. Cleanup on delete. |
-| Currency precision | Phase 1: Data model | Price stored as integer cents. Display layer formats to dollars/euros. |
-| Thread state machine | Phase 2: Planning threads | State transitions documented in code. Invalid transitions throw errors. Resolution is transactional. |
-| Comparison usefulness | Phase 2: Planning threads | Comparison view shows deltas. Thread can link to "item being replaced." Setup impact visible. |
-| Setup integrity | Phase 3: Setups | Totals computed from live data. Item deletion warns about setup membership. Soft-delete or archive for removed items. |
-| Data loss / no backup | Phase 1: Infrastructure | Automatic DB backup on a schedule. Manual export button on dashboard. |
-| Bulk import | Phase 1: Core CRUD | CSV import available from collection view. Handles unit variations in weight column. |
+| Rounding accumulation | Phase 1: Weight unit selection | `formatWeight` converts grams to display unit. Edit forms load grams from API, not from displayed value. Write test: edit an item 10 times without changes, weight stays identical. |
+| Classification at wrong level | Phase 2: Weight classification | `classification` column exists on `setup_items`, not `items`. Test: same item in two setups has different classifications. |
+| Server-side search for client data | Phase 1: Search/filter | No new API parameters on `GET /api/items`. Filter logic lives in `CollectionView` component. Test: search works instantly without network requests. |
+| Status without transition validation | Phase 3: Candidate status | Zod enum validates status values. Service rejects invalid transitions. Test: updating "arrived" to "researching" returns 400 error. |
+| Chart/totals divergence | Phase 3: Weight visualization | Chart data and totals bar use same computation path. Test: sum of chart segment values equals displayed total. |
+| Test helper desync | Every schema-changing phase | Each phase's PR includes updated test helper. CI test suite catches column mismatches. |
+| Unit preference inconsistency | Phase 1: Weight unit selection | All weight displays use `formatWeight(grams, unit)`. Test: change unit preference, verify all visible weights update without refresh. |
 
 ## Sources
 
-- [Ultralight: The Gear Tracking App I'm Leaving LighterPack For](https://trailsmag.net/blogs/hiker-box/ultralight-the-gear-tracking-app-i-m-leaving-lighterpack-for) -- LighterPack limitations and community complaints
-- [SQLite Internal vs External BLOBs](https://sqlite.org/intern-v-extern-blob.html) -- official SQLite guidance on image storage tradeoffs
-- [35% Faster Than The Filesystem](https://sqlite.org/fasterthanfs.html) -- SQLite BLOB performance data
-- [Comparison Tables for Products, Services, and Features - NN/g](https://www.nngroup.com/articles/comparison-tables/) -- comparison UX best practices
-- [Designing The Perfect Feature Comparison Table - Smashing Magazine](https://www.smashingmagazine.com/2017/08/designing-perfect-feature-comparison-table/) -- comparison table design patterns
-- [Comparing products: UX design best practices - Contentsquare](https://contentsquare.com/blog/comparing-products-design-practices-to-help-your-users-avoid-fragmented-comparison-7/) -- product comparison UX pitfalls
-- [Common Unit Conversion Mistakes That Break Applications](https://helppdev.com/en/blog/common-unit-conversion-mistakes-that-break-applications) -- unit conversion antipatterns
-- [Inventory App Design - UXPin](https://www.uxpin.com/studio/blog/inventory-app-design/) -- inventory app UX patterns
-- [Designing better file organization around tags, not hierarchies](https://www.nayuki.io/page/designing-better-file-organization-around-tags-not-hierarchies) -- tags vs hierarchy tradeoffs
+- [Weight conversion precision and rounding best practices](https://explore.st-aug.edu/exp/from-ounces-to-pounds-the-precision-behind-weight-conversions-heres-how-many-grams-equal-a-practical-pound) -- authoritative source on conversion factor precision
+- [Base weight classification definitions and community debates](https://thetrek.co/continental-divide-trail/how-to-easily-lower-your-base-weight-calculate-it-differently/) -- real-world examples of classification ambiguity
+- [LighterPack user classification errors](https://www.99boulders.com/lighterpack-tutorial) -- LighterPack's approach to base/worn/consumable
+- [Avoiding common mistakes with TanStack Query](https://www.buncolak.com/posts/avoiding-common-mistakes-with-tanstack-query-part-1/) -- anti-patterns with React Query caching
+- [TanStack Query discussions on filtering with cache](https://github.com/TanStack/query/discussions/1113) -- community patterns for client-side vs server-side filtering
+- [Recharts performance and limitations](https://blog.logrocket.com/best-react-chart-libraries-2025/) -- SVG rendering pitfalls, ResponsiveContainer requirement
+- [Drizzle ORM SQLite migration pitfalls](https://github.com/drizzle-team/drizzle-orm/issues/1313) -- data loss bug with push + add column
+- [State machine anti-patterns](https://rclayton.silvrback.com/use-state-machines) -- importance of explicit transition validation
+- [Ultralight gear tracker leaving LighterPack](https://trailsmag.net/blogs/hiker-box/ultralight-the-gear-tracking-app-i-m-leaving-lighterpack-for) -- community frustrations with existing tools
+- Direct codebase analysis of GearBox v1.1 (schema.ts, services, hooks, routes) -- existing patterns and integration points
 
 ---
-*Pitfalls research for: GearBox -- gear management and purchase planning app*
-*Researched: 2026-03-14*
+*Pitfalls research for: GearBox v1.2 -- Collection Power-Ups (search/filter, weight classification, charts, candidate status, unit selection)*
+*Researched: 2026-03-16*

.planning/research/STACK.md

@@ -1,191 +1,179 @@
-# Stack Research
+# Technology Stack -- v1.2 Collection Power-Ups
 
-**Domain:** Single-user gear management and purchase planning web app
-**Researched:** 2026-03-14
+**Project:** GearBox
+**Researched:** 2026-03-16
+**Scope:** Stack additions for search/filter, weight classification, weight distribution charts, candidate status tracking, weight unit selection
 **Confidence:** HIGH
 
-## Recommended Stack
+## Key Finding: Minimal New Dependencies
 
-### Core Technologies
+Four of five v1.2 features require **zero new libraries**. They are pure application logic built on top of the existing stack (Drizzle ORM filters, Zod schema extensions, Zustand state, React Query invalidation). The only decision point is whether to add a charting library for weight distribution visualization.
 
-| Technology | Version | Purpose | Why Recommended |
-|------------|---------|---------|-----------------|
-| Bun | 1.3.x | Runtime, package manager, bundler | User constraint. Built-in SQLite, fast installs, native TS support. Eliminates need for separate runtime/bundler/pkg manager. |
-| React | 19.2.x | UI framework | Industry standard, massive ecosystem, stable. Server Components not needed for this SPA -- stick with client-side React. |
-| Vite | 8.0.x | Dev server, production builds | Rolldown-based builds (5-30x faster than Vite 7). Zero-config React support. Bun-compatible. HMR out of the box. |
-| Hono | 4.12.x | Backend API framework | Built on Web Standards, first-class Bun support, zero dependencies, tiny (~12kB). Perfect for a lightweight REST API. Faster than Express on Bun benchmarks. |
-| SQLite (bun:sqlite) | Built-in | Database | Zero-dependency, built into Bun runtime. 3-6x faster than better-sqlite3. Single file database -- perfect for single-user app. No server process to manage. |
-| Drizzle ORM | 0.45.x | Database ORM, migrations | Type-safe SQL, ~7.4kB, zero dependencies. Native bun:sqlite driver support. SQL-like query API (not abstracting SQL away). Built-in migration tooling via drizzle-kit. |
-| Tailwind CSS | 4.2.x | Styling | CSS-native configuration (no JS config file). Auto content detection. Microsecond incremental builds. Perfect for "light, airy, minimalist" design constraint. |
-| TanStack Router | 1.167.x | Client-side routing | Full type-safe routing with typed params and search params. File-based route generation. Better SPA experience than React Router v7 (whose best features require framework mode). |
-| TanStack Query | 5.93.x | Server state management | Handles API data fetching, caching, and synchronization. Eliminates manual loading/error state management. Automatic cache invalidation on mutations. |
-| Zustand | 5.0.x | Client state management | Minimal boilerplate, ~1kB. For UI state like active filters, modal state, theme. TanStack Query handles server state; Zustand handles the rest. |
-| Zod | 4.3.x | Schema validation | Validates API inputs on the server, form data on the client, and shares types between both. Single source of truth for data shapes. |
-| TypeScript | 5.x (Bun built-in) | Type safety | Bun transpiles TS natively -- no tsc needed at runtime. Catches bugs at dev time. Required by Drizzle and TanStack Router for type-safe queries and routes. |
+## New Dependency
 
-### Supporting Libraries
+### Charting: react-minimal-pie-chart
 
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| @tanstack/react-query-devtools | 5.x | Query debugging | Development only. Inspect cache state, refetch timing, query status. |
-| drizzle-kit | latest | DB migrations CLI | Run `drizzle-kit generate` and `drizzle-kit migrate` for schema changes. |
-| @hono/zod-validator | latest | Request validation middleware | Validate API request bodies/params using Zod schemas in Hono routes. |
-| clsx | 2.x | Conditional class names | When building components with variant styles. Pairs with Tailwind. |
-| @tanstack/react-router-devtools | latest | Router debugging | Development only. Inspect route matches, params, search params. |
+| Technology | Version | Purpose | Why |
+|------------|---------|---------|-----|
+| react-minimal-pie-chart | ^9.1.2 | Weight distribution donut/pie charts | Under 2kB gzipped. Supports pie, donut, loading, and completion chart types. SVG-based with CSS animations, hover/click interactions, custom label rendering. React 19 compatible (peerDeps explicitly include `^19`). Zero external dependencies. TypeScript native. |
 
-### Development Tools
+**Why this over alternatives:**
 
-| Tool | Purpose | Notes |
-|------|---------|-------|
-| Bun | Test runner | `bun test` -- built-in, Jest-compatible API. No need for Vitest or Jest. |
-| Biome | Linter + formatter | Single tool replacing ESLint + Prettier. Fast (Rust-based), minimal config. `biome check --write` does both. |
-| Vite React plugin | React HMR/JSX | `@vitejs/plugin-react` for Fast Refresh during development. |
+| Criterion | react-minimal-pie-chart | Recharts | Custom SVG | Chart.js |
+|-----------|------------------------|----------|------------|----------|
+| Bundle size | ~2kB gzipped | ~97kB gzipped | 0kB | ~60kB gzipped |
+| Chart types needed | Pie + donut (exactly what we need) | Overkill (line, bar, area, scatter, etc.) | Manual math | Overkill |
+| React 19 support | Explicit in peerDeps | Isolated rendering issues reported with 19.2.x | N/A | Wrapper has open React 19 issues |
+| Interactivity | Click, hover, focus, keyboard events per segment | Full but heavy | Must implement from scratch | Canvas-based (harder to style) |
+| Labels | Render prop for custom labels (percentage, value, SVG) | Built-in | Must implement | Built-in |
+| Animation | CSS-based, configurable duration/easing, reveal effect | D3-based, heavier | Must implement | Canvas animation |
+| Learning curve | Minimal -- one component, straightforward props | Moderate -- many components | High -- SVG arc math | Moderate |
+| Maintenance risk | Low -- tiny surface area, stable API | Low -- large community | Zero | Medium -- Canvas abstraction |
+
+**Why not custom SVG:** The SVG `<circle>` + `stroke-dasharray` approach works for static charts but breaks interactivity (stacked circles mean only the last segment is clickable). The `<path>` arc approach gives full interactivity but requires implementing arc math, animation, labels, hover states, and accessibility from scratch. At ~2kB, react-minimal-pie-chart costs less than the custom code would and handles all edge cases.
+
+**Why not Recharts:** GearBox needs exactly one chart type (donut/pie). Recharts adds ~97kB of unused capability. It also had isolated rendering issues reported with React 19.2.x, and pulls in D3 submodules. Significant overkill for this use case.
+
+## Existing Stack Usage for Each Feature
+
+### 1. Search/Filter Items
+
+**No new dependencies.** Uses existing Drizzle ORM operators and React state.
+
+| Existing Tech | How It Is Used |
+|---------------|----------------|
+| Drizzle ORM `like()` | Server-side text search on `items.name` column. SQLite LIKE is case-insensitive by default, so no need for `ilike()`. |
+| Drizzle ORM `eq()`, `and()` | Category filter: `eq(items.categoryId, selectedId)`. Combine with search: `and(like(...), eq(...))`. |
+| TanStack Query | New query key pattern: `["items", { search, categoryId }]` for filtered results. Server-side filtering preferred over client-side to establish the pattern early (collections grow). |
+| Zustand or URL search params | Store active filter state. URL search params preferred (already used for tab state) so filter state is shareable/bookmarkable. |
+| Zod | Validate query params on the Hono route: `z.object({ search: z.string().optional(), categoryId: z.number().optional() })`. |
+
+**Implementation approach:** Add query parameters to `GET /api/items` rather than client-side filtering. Drizzle's conditional filter pattern handles optional params cleanly:
+
+```typescript
+import { like, eq, and } from "drizzle-orm";
+
+const conditions = [];
+if (search) conditions.push(like(items.name, `%${search}%`));
+if (categoryId) conditions.push(eq(items.categoryId, categoryId));
+
+db.select().from(items).where(and(...conditions));
+```
+
+### 2. Weight Classification (Base/Worn/Consumable)
+
+**No new dependencies.** Schema change + UI state.
+
+| Existing Tech | How It Is Used |
+|---------------|----------------|
+| Drizzle ORM | Add `weightClass` column to `setup_items` table: `text("weight_class").notNull().default("base")`. Classification is per-setup-item, not per-item globally (a sleeping bag is "base" in a bikepacking setup but might be categorized differently elsewhere). |
+| Zod | Extend `syncSetupItemsSchema` to include classification: `z.enum(["base", "worn", "consumable"])`. |
+| drizzle-kit | Generate migration for the new column: `bun run db:generate`. |
+| SQL aggregates | Compute base/worn/consumable weight subtotals server-side, same pattern as existing category totals in `useTotals`. |
+
+**Key design decision:** Weight classification belongs on `setup_items` (the join table), not on `items` directly. An item's classification depends on context -- hiking poles are "worn" if you always use them, "base" if they pitch your tent. LighterPack follows this same model. This means the `syncSetupItemsSchema` changes from `{ itemIds: number[] }` to `{ items: Array<{ itemId: number, weightClass: "base" | "worn" | "consumable" }> }`.
+
+### 3. Weight Distribution Charts
+
+**One new dependency:** `react-minimal-pie-chart` (documented above).
+
+| Existing Tech | How It Is Used |
+|---------------|----------------|
+| TanStack Query (`useTotals`) | Already returns per-category weight totals. Extend to also return per-weight-class totals for a given setup. |
+| Tailwind CSS | Style chart container, legend, responsive layout. Chart labels use Tailwind color tokens for consistency. |
+| Lucide React | Category icons in the chart legend, consistent with existing CategoryHeader component. |
+
+**Chart data sources:**
+- **By category:** Already available from `GET /api/totals` response (`categories` array with `totalWeight` per category). No new endpoint needed.
+- **By weight classification:** New endpoint `GET /api/setups/:id/breakdown` returning `{ base: number, worn: number, consumable: number }` computed from the `weight_class` column on `setup_items`.
+
+### 4. Candidate Status Tracking
+
+**No new dependencies.** Schema change + UI update.
+
+| Existing Tech | How It Is Used |
+|---------------|----------------|
+| Drizzle ORM | Add `status` column to `thread_candidates` table: `text("status").notNull().default("researching")`. Values: `"researching"`, `"ordered"`, `"arrived"`. |
+| Zod | Add to `createCandidateSchema` and `updateCandidateSchema`: `status: z.enum(["researching", "ordered", "arrived"]).default("researching")`. |
+| Tailwind CSS | Status badge colors on CandidateCard (gray for researching, amber for ordered, green for arrived). Same badge pattern used for thread status already. |
+| Lucide React | Status icons: `search` for researching, `truck` for ordered, `check-circle` for arrived. Already in the curated icon set. |
+
+### 5. Weight Unit Selection
+
+**No new dependencies.** Settings storage + formatter change.
+
+| Existing Tech | How It Is Used |
+|---------------|----------------|
+| SQLite `settings` table | Store preferred unit: `{ key: "weightUnit", value: "g" }`. Same pattern as existing onboarding settings. |
+| React Query (`useSettings`) | Already exists. Fetch and cache the weight unit preference. |
+| `formatWeight()` in `lib/formatters.ts` | Extend to accept a unit parameter and convert from grams (the canonical storage format). |
+| Zustand (optional) | Could cache the unit preference in UI store for synchronous access in formatters. Alternatively, pass it through React context or as a parameter. |
+
+**Conversion constants (stored weights are always grams):**
+
+| Unit | From Grams | Display Format |
+|------|-----------|----------------|
+| g (grams) | `x` | `${Math.round(x)}g` |
+| oz (ounces) | `x / 28.3495` | `${(x / 28.3495).toFixed(1)}oz` |
+| lb (pounds) | `x / 453.592` | `${(x / 453.592).toFixed(2)}lb` |
+| kg (kilograms) | `x / 1000` | `${(x / 1000).toFixed(2)}kg` |
+
+**Key decision:** Store weights in grams always. Convert on display only. This avoids precision loss from repeated conversions and keeps the database canonical. The `formatWeight` function becomes the single conversion point.
 
 ## Installation
 
 ```bash
-# Initialize project
-bun init
-
-# Core frontend
-bun add react react-dom @tanstack/react-router @tanstack/react-query zustand zod clsx
-
-# Core backend
-bun add hono @hono/zod-validator drizzle-orm
-
-# Styling
-bun add tailwindcss @tailwindcss/vite
-
-# Build tooling
-bun add -d vite @vitejs/plugin-react typescript @types/react @types/react-dom
-
-# Database tooling
-bun add -d drizzle-kit
-
-# Linting + formatting
-bun add -d @biomejs/biome
-
-# Dev tools (optional but recommended)
-bun add -d @tanstack/react-query-devtools @tanstack/react-router-devtools
+# Only new dependency for v1.2
+bun add react-minimal-pie-chart
 ```
 
-## Architecture Pattern
+That is it. One package, under 2kB gzipped.
 
-**Monorepo-lite (single package, split directories):**
+## Schema Changes Summary
 
-```
-/src
-  /client          -- React SPA (Vite entry point)
-    /routes         -- TanStack Router file-based routes
-    /components     -- Shared UI components
-    /stores         -- Zustand stores
-    /api            -- TanStack Query hooks (fetch wrappers)
-  /server          -- Hono API server
-    /routes         -- API route handlers
-    /db             -- Drizzle schema, migrations
-  /shared          -- Zod schemas shared between client and server
-/public            -- Static assets, uploaded images
-```
+These are the Drizzle schema modifications needed (no new tables, just column additions):
 
-Bun runs the Hono server, which also serves the Vite-built SPA in production. In development, Vite dev server proxies API calls to the Hono backend.
+| Table | Change | Migration |
+|-------|--------|-----------|
+| `setup_items` | Add `weightClass: text("weight_class").notNull().default("base")` | `bun run db:generate && bun run db:push` |
+| `thread_candidates` | Add `status: text("status").notNull().default("researching")` | `bun run db:generate && bun run db:push` |
+| `settings` | No schema change (already key-value). Insert `weightUnit` row. | Seed via service or onboarding. |
 
-## Alternatives Considered
-
-| Recommended | Alternative | When to Use Alternative |
-|-------------|-------------|-------------------------|
-| Hono | Elysia | If you want end-to-end type safety with Eden Treaty. Elysia is Bun-native but heavier, more opinionated, and has a smaller ecosystem than Hono. |
-| Hono | Express | Never for new Bun projects. Express is Node-centric, not built on Web Standards, slower on Bun. |
-| TanStack Router | React Router v7 | If you want the simplest possible routing with minimal type safety. React Router v7's best features (loaders, type safety) require framework mode which adds complexity. |
-| Drizzle ORM | Prisma | If you have a complex relational model and want auto-generated migrations. But Prisma is heavy (~8MB), generates a query engine binary, and has weaker SQLite support. |
-| Drizzle ORM | Kysely | If you want a pure query builder without ORM features. Kysely is lighter but lacks built-in migration tooling. |
-| Zustand | Jotai | If you prefer atomic state (bottom-up). Zustand is simpler for this app's needs -- a few global stores, not many independent atoms. |
-| Tailwind CSS | Vanilla CSS / CSS Modules | If you strongly prefer writing plain CSS. But Tailwind accelerates building consistent minimalist UIs and requires less design system setup. |
-| bun:sqlite | PostgreSQL | If you later need multi-user with concurrent writes. Overkill for single-user. Adds a database server dependency. |
-| Biome | ESLint + Prettier | If you need specific ESLint plugins not yet in Biome. But Biome covers 95% of use cases with zero config. |
-| Vite | Bun's built-in bundler | Bun can serve HTML directly as of 1.3, but Vite's ecosystem (plugins, HMR, proxy) is far more mature for SPA development. |
-
-## What NOT to Use
+## What NOT to Add
 
 | Avoid | Why | Use Instead |
 |-------|-----|-------------|
-| Next.js | Server-centric framework. Massive overhead for a single-user SPA. Forces Node.js patterns. No benefit without SSR/SSG needs. | Vite + React + Hono |
-| Remix / React Router framework mode | Adds server framework complexity. This is a simple SPA with a separate API -- framework routing is unnecessary overhead. | TanStack Router (SPA mode) |
-| better-sqlite3 | Requires native compilation, compatibility issues with Bun. bun:sqlite is built-in and 3-6x faster. | bun:sqlite (built into Bun) |
-| Redux / Redux Toolkit | Massive boilerplate for a small app. Actions, reducers, slices -- all unnecessary when Zustand does the same in 10 lines. | Zustand |
-| Mongoose / MongoDB | Document DB is wrong fit. Gear items have relational structure (items belong to setups, threads reference items). SQL is the right model. | Drizzle + SQLite |
-| Axios | Unnecessary abstraction over fetch. Bun and browsers both have native fetch. TanStack Query wraps fetch already. | Native fetch |
-| styled-components / Emotion | CSS-in-JS adds runtime overhead and bundle size. Tailwind is faster (zero runtime) and better for consistent minimalist design. | Tailwind CSS |
-| Jest / Vitest | Bun has a built-in test runner with Jest-compatible API. No need for external test frameworks. | bun test |
-| ESLint + Prettier | Two tools, complex configuration, slow (JS-based). Biome does both in one tool, faster. | Biome |
+| Recharts | 97kB for one chart type. React 19 edge-case issues. D3 dependency chain. | react-minimal-pie-chart (2kB) |
+| Chart.js / react-chartjs-2 | Canvas-based (harder to style with Tailwind). Open React 19 peer dep issues. Overkill. | react-minimal-pie-chart |
+| visx | Low-level D3 primitives. Steep learning curve. Have to build chart from scratch. Great for custom viz, overkill for a donut chart. | react-minimal-pie-chart |
+| Fuse.js or similar search library | Client-side fuzzy search adds bundle weight and complexity. SQLite LIKE is sufficient for name search on a single-user collection (hundreds of items, not millions). | Drizzle `like()` operator |
+| Full-text search (FTS5) | SQLite FTS5 is powerful but requires virtual tables and different query syntax. Overkill for simple name matching on small collections. | Drizzle `like()` operator |
+| i18n library for unit conversion | This is not internationalization. It is four conversion constants and a formatter function. A library would be absurd. | Custom `formatWeight()` function |
+| State machine library (XState) | Candidate status is a simple enum, not a complex state machine. Three values with no guards or side effects. | Zod enum + Drizzle text column |
+| New Zustand store for filters | Filter state should live in URL search params for shareability/bookmarkability. The collection page already uses this pattern for tabs. | TanStack Router search params |
 
-## Version Compatibility
+## Existing Stack Version Compatibility
 
-| Package A | Compatible With | Notes |
-|-----------|-----------------|-------|
-| Bun 1.3.x | bun:sqlite (built-in) | SQLite driver is part of the runtime, always compatible. |
-| Drizzle ORM 0.45.x | bun:sqlite via `drizzle-orm/bun-sqlite` | Official driver. Import from `drizzle-orm/bun-sqlite`. |
-| Drizzle ORM 0.45.x | drizzle-kit (latest) | drizzle-kit handles migration generation/execution. Must match major drizzle-orm version. |
-| React 19.2.x | TanStack Router 1.x | TanStack Router 1.x supports React 18+ and 19.x. |
-| React 19.2.x | TanStack Query 5.x | TanStack Query 5.x supports React 18+ and 19.x. |
-| React 19.2.x | Zustand 5.x | Zustand 5.x supports React 18+ and 19.x. |
-| Vite 8.x | @vitejs/plugin-react | Check plugin version matches Vite major. Use latest plugin for Vite 8. |
-| Tailwind CSS 4.2.x | @tailwindcss/vite | v4 uses Vite plugin instead of PostCSS. Import as `@tailwindcss/vite` in vite config. |
-| Zod 4.x | @hono/zod-validator | Verify @hono/zod-validator supports Zod 4. If not, pin Zod 3.23.x until updated. |
+All existing dependencies remain unchanged. The only version consideration:
 
-## Key Configuration Notes
-
-### Bun + Vite Setup
-Vite runs as the dev server for the frontend. The Hono API server runs separately. Use Vite's `server.proxy` to forward `/api/*` requests to the Hono backend during development.
-
-### SQLite WAL Mode
-Enable WAL mode on database initialization for better performance:
-```typescript
-import { Database } from "bun:sqlite";
-const db = new Database("gearbox.db");
-db.run("PRAGMA journal_mode = WAL");
-db.run("PRAGMA foreign_keys = ON");
-```
-
-### Tailwind v4 (No Config File)
-Tailwind v4 uses CSS-native configuration. No `tailwind.config.js` needed:
-```css
-@import "tailwindcss";
-@theme {
-  --color-primary: #2563eb;
-  --font-sans: "Inter", sans-serif;
-}
-```
-
-### Drizzle Schema Example (bun:sqlite)
-```typescript
-import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";
-
-export const gearItems = sqliteTable("gear_items", {
-  id: integer("id").primaryKey({ autoIncrement: true }),
-  name: text("name").notNull(),
-  category: text("category").notNull(),
-  weightGrams: real("weight_grams"),
-  priceCents: integer("price_cents"),
-  source: text("source"),
-  notes: text("notes"),
-  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
-});
-```
+| New Package | Compatible With | Verified |
+|-------------|-----------------|----------|
+| react-minimal-pie-chart ^9.1.2 | React 19 (`peerDeps: "^16.8.0 \|\| ^17 \|\| ^18 \|\| ^19"`) | YES -- package.json on GitHub confirms. Dev deps test against React 19.0.0. |
+| react-minimal-pie-chart ^9.1.2 | TypeScript 5.x | YES -- library is TypeScript native (built with TS 3.8+). |
+| react-minimal-pie-chart ^9.1.2 | Bun bundler / Vite | YES -- pure ESM, no native dependencies, standard npm package. |
 
 ## Sources
 
-- [Bun official docs](https://bun.com/docs) -- bun:sqlite features, runtime capabilities (HIGH confidence)
-- [Hono official docs](https://hono.dev/docs) -- Bun integration, static serving (HIGH confidence)
-- [Drizzle ORM docs - Bun SQLite](https://orm.drizzle.team/docs/connect-bun-sqlite) -- driver support verified (HIGH confidence)
-- [Vite releases](https://vite.dev/releases) -- v8.0 with Rolldown confirmed (HIGH confidence)
-- [Tailwind CSS v4.2 blog](https://tailwindcss.com/blog/tailwindcss-v4) -- CSS-native config, Vite plugin (HIGH confidence)
-- [TanStack Router docs](https://tanstack.com/router/latest) -- v1.167.x confirmed (HIGH confidence)
-- [TanStack Query docs](https://tanstack.com/query/latest) -- v5.93.x for React (HIGH confidence)
-- [Zustand npm](https://www.npmjs.com/package/zustand) -- v5.0.x confirmed (HIGH confidence)
-- [Zod v4 release notes](https://zod.dev/v4) -- v4.3.x confirmed (MEDIUM confidence -- verify @hono/zod-validator compatibility)
-- [React versions](https://react.dev/versions) -- v19.2.x confirmed (HIGH confidence)
-- [Bun SQLite vs better-sqlite3 benchmarks](https://bun.com/docs/runtime/sqlite) -- 3-6x performance advantage (HIGH confidence)
+- [Drizzle ORM Filter Operators](https://orm.drizzle.team/docs/operators) -- `like`, `eq`, `and`, `or` operators for search/filter (HIGH confidence)
+- [Drizzle ORM Conditional Filters Guide](https://orm.drizzle.team/docs/guides/conditional-filters-in-query) -- dynamic filter composition pattern (HIGH confidence)
+- [react-minimal-pie-chart GitHub](https://github.com/toomuchdesign/react-minimal-pie-chart) -- version 9.1.2, React 19 peerDeps confirmed (HIGH confidence)
+- [react-minimal-pie-chart package.json](https://github.com/toomuchdesign/react-minimal-pie-chart/blob/master/package.json) -- React 19 in peerDependencies and devDependencies (HIGH confidence)
+- [Recharts npm](https://www.npmjs.com/package/recharts) -- v3.8.0, ~97kB bundle (HIGH confidence)
+- [Recharts React 19 issue #6857](https://github.com/recharts/recharts/issues/6857) -- rendering issues reported with React 19.2.3 (MEDIUM confidence -- may be project-specific)
+- [LighterPack weight classification model](https://lighterpack.com) -- base/worn/consumable terminology is industry standard for gear management (HIGH confidence)
+- [Pack Weight Calculator Guide](https://backpackpeek.com/blog/pack-weight-calculator-base-weight-guide) -- weight classification definitions (HIGH confidence)
+- [SQLite LIKE case sensitivity note](https://github.com/drizzle-team/drizzle-orm-docs/issues/239) -- LIKE is case-insensitive in SQLite, no need for ilike (MEDIUM confidence)
 
 ---
-*Stack research for: GearBox -- gear management and purchase planning web app*
-*Researched: 2026-03-14*
+*Stack research for: GearBox v1.2 -- Collection Power-Ups*
+*Researched: 2026-03-16*

.planning/research/SUMMARY.md

@@ -1,243 +1,208 @@
 # Project Research Summary
 
-**Project:** GearBox
-**Domain:** Single-user gear management and purchase planning web app
-**Researched:** 2026-03-14
+**Project:** GearBox v1.2 -- Collection Power-Ups
+**Domain:** Gear management (bikepacking, sim racing, etc.) -- feature enhancement milestone
+**Researched:** 2026-03-16
 **Confidence:** HIGH
 
 ## Executive Summary
 
-GearBox is a single-user personal gear management app with a critical differentiator: purchase planning threads. Every competitor (LighterPack, GearGrams, Packstack, Hikt) is a post-purchase inventory tool — they help you track what you own. GearBox closes the loop by adding a structured pre-purchase research workflow where users compare candidates, track research status, and resolve threads by promoting winners into their collection. This is the entire reason to build the product; the collection management side is table stakes, and the purchase planning threads are the moat. Research strongly recommends building both together in the v1 scope, not sequencing them separately, because the thread resolution workflow only becomes compelling once a real collection exists to reference.
+GearBox v1.2 adds six features to the existing gear management app: item search/filter, weight classification (base/worn/consumable), weight distribution charts, candidate status tracking, weight unit selection, and a planning category filter upgrade. Research confirms that four of six features require zero new dependencies -- they are pure application logic built on the existing stack (Drizzle ORM, React Query, Zod, Tailwind). The sole new dependency is `react-minimal-pie-chart` (~2kB gzipped) for donut chart visualization. The codebase is well-positioned for these additions: the settings table already supports key-value preferences, the `setup_items` join table is the correct place for weight classification, and the client-side data model is small enough for in-memory filtering.
 
-The recommended architecture is a single-process Bun fullstack monolith: Hono for the API layer, React 19 + Vite 8 for the frontend, Drizzle ORM + bun:sqlite for the database, TanStack Router + TanStack Query for client navigation and server state, and Tailwind CSS v4 for styling. This stack is purpose-built for the constraints: Bun is a project requirement, SQLite is optimal for single-user, and every tool in the list has zero or near-zero runtime overhead. Zustand handles the small amount of client-only UI state. The entire stack is type-safe end-to-end through Zod schemas shared between client and server.
+The recommended approach is to build weight unit selection first because it refactors the `formatWeight` function that every subsequent feature depends on for display. Search/filter and candidate status tracking are independent and low-risk. Weight classification is the most architecturally significant change -- it adds a column to the `setup_items` join table and changes the sync API shape from `{ itemIds: number[] }` to `{ items: Array<{ itemId, weightClass }> }`. Weight distribution charts come last because they depend on both the unit formatter and the classification data. The two schema changes (columns on `setup_items` and `thread_candidates`) should be batched into a single Drizzle migration.
 
-The biggest risks are front-loaded in Phase 1: unit handling (weights must be canonicalized to grams from day one), currency precision (prices must be stored as integer cents), category flexibility (must use user-defined tags, not a hardcoded hierarchy), and image storage strategy (relative paths to a local directory, never BLOBs for full-size, never absolute paths). Getting these wrong requires painful data migrations later. The second major risk is the thread state machine in Phase 2 — the combination of candidate status, thread lifecycle, and "move winner to collection" creates a stateful flow that must be modeled as an explicit state machine with transactional resolution, not assembled incrementally.
+The primary risks are: (1) weight unit conversion rounding drift from bidirectional conversion in edit forms, (2) accidentally placing weight classification on the `items` table instead of the `setup_items` join table, and (3) chart data diverging from displayed totals due to separate computation paths. All three are preventable with clear architectural rules established in the first phase: store grams canonically, convert only at the display boundary, and use a single source of truth for weight computations.
 
 ## Key Findings
 
 ### Recommended Stack
 
-The stack is a tightly integrated Bun-native toolchain with no redundant tools. Bun serves as runtime, package manager, test runner, and provides built-in SQLite — eliminating entire categories of infrastructure. Vite 8 (Rolldown-based, 5-30x faster than Vite 7) handles the dev server and production frontend builds. The client-server boundary is clean: Hono serves the API, React handles the UI, and Zod schemas in a `shared/` directory provide a single source of truth for data shapes on both sides.
+The existing stack (React 19, Hono, Drizzle ORM, SQLite, Bun) handles all v1.2 features without modification. One small library addition is needed.
 
-The architecture note in STACK.md suggests Bun's fullstack HTML-based routing (not Vite's dev server proxy pattern). This differs slightly from the standard Vite proxy setup: each page is a separate HTML entrypoint imported into `Bun.serve()`, and TanStack Router handles in-page client-side navigation only. This simplifies the development setup to a single `bun run` command with no proxy configuration.
+**Core technologies (all existing, no changes):**
+- **Drizzle ORM `like()`, `eq()`, `and()`**: Available for server-side filtering if needed in the future, but client-side filtering is preferred at this scale
+- **Zod `z.enum()`**: Validates weight classification (`"base" | "worn" | "consumable"`) and candidate status (`"researching" | "ordered" | "arrived"`) with compile-time type safety
+- **React Query `useSetting()`**: Reactive settings caching ensures unit preference changes propagate to all weight displays without page refresh
+- **Existing `settings` table**: Key-value store supports weight unit preference with no schema change
 
-**Core technologies:**
-- Bun 1.3.x: Runtime, package manager, test runner, bundler — eliminates Node.js and npm
-- React 19.2.x + Vite 8.x: SPA framework + dev server — stable, large ecosystem, HMR out of the box
-- Hono 4.12.x: API layer — Web Standards based, first-class Bun support, ~12kB, faster than Express on Bun
-- SQLite (bun:sqlite) + Drizzle ORM 0.45.x: Database — zero-dependency, built into Bun, type-safe queries and migrations
-- TanStack Router 1.167.x + TanStack Query 5.93.x: Routing + server state — full type-safe routing, automatic cache invalidation
-- Tailwind CSS 4.2.x: Styling — CSS-native config, no JS file, microsecond incremental builds
-- Zustand 5.x: Client UI state — minimal boilerplate for filter state, modals, theme
-- Zod 4.3.x: Schema validation — shared between client and server as single source of truth for types
-- Biome: Linting + formatting — replaces ESLint + Prettier, Rust-based, near-zero config
+**New dependency:**
+- **react-minimal-pie-chart ^9.1.2**: Donut/pie charts at ~2kB gzipped. React 19 compatible (explicit in peerDeps). Zero external dependencies. TypeScript native. Chosen over Recharts (~97kB, React 19 rendering issues reported) and Chart.js (~60kB, canvas-based, harder to style with Tailwind).
 
-**Version flag:** Verify that `@hono/zod-validator` supports Zod 4.x before starting. If not, pin Zod 3.23.x until the validator is updated.
+**What NOT to add:**
+- Recharts, Chart.js, or visx (massive overkill for one chart type)
+- Fuse.js or FTS5 (overkill for name search on sub-1000 item collections)
+- XState (candidate status is a simple enum, not a complex state machine)
+- i18n library for unit conversion (four constants and a formatter function)
 
 ### Expected Features
 
-The feature research distinguishes cleanly between what every gear app does (table stakes) and what GearBox uniquely does (purchase planning threads). No competitor has threads, candidate comparison, or thread resolution. This is the entire competitive surface. Everything else is hygiene.
+**Must have (table stakes):**
+- **Search items by name** -- every competitor with an inventory has search; LighterPack notably lacks it and users complain
+- **Filter items by category** -- partially exists in planning view, missing from collection view
+- **Weight unit selection (g/oz/lb/kg)** -- universal across all competitors; gear specs come in mixed units
+- **Weight classification (base/worn/consumable)** -- pioneered by LighterPack, now industry standard; "base weight" is the core metric of the ultralight community
 
-**Must have (table stakes) — v1 launch:**
-- Item CRUD with weight, price, category, notes, product URL — minimum unit of value
-- User-defined categories/tags — must be flexible, not a hardcoded hierarchy
-- Weight unit support (g, oz, lb, kg) — gear community requires this; store canonical grams internally
-- Automatic weight/cost totals by category and setup — the reason to use an app over a text file
-- Named setups composed from collection items — compose loadouts, get aggregate totals
-- Planning threads with candidate items — the core differentiator
-- Side-by-side candidate comparison with deltas (not just raw values) — the payoff of threads
-- Thread resolution: pick winner, move to collection — closes the purchase research loop
-- Search and filter on collection — essential at 30+ items
-- Dashboard home page — clean entry point per project constraints
+**Should have (differentiators):**
+- **Weight distribution donut chart** -- LighterPack's pie chart is cited as its best feature; GearBox can uniquely combine category and classification breakdown
+- **Candidate status tracking (researching/ordered/arrived)** -- entirely unique to GearBox's planning thread concept; no competitor has purchase lifecycle tracking
+- **Per-setup classification** -- architecturally superior to competitors; the same item can be classified differently across setups
 
-**Should have (competitive) — v1.x after validation:**
-- Impact preview: how a thread candidate changes a specific setup's weight and cost
-- Status tracking on thread items (researching / ordered / arrived)
-- Priority/ranking within threads
-- Photos per item (one photo per item initially)
-- CSV import/export — migration path from spreadsheets, data portability
-- Weight distribution visualization (pie/bar chart by category)
-
-**Defer — v2+:**
-- Multi-photo gallery per item
-- Shareable read-only links for setups
-- Drag-and-drop reordering
-- Bulk operations (multi-select, bulk delete)
-- Dark mode
-- Item history/changelog
+**Defer (v2+):**
+- Per-item weight input in multiple units (parsing complexity)
+- Interactive chart drill-down (click to zoom into categories)
+- Weight goals/targets (opinionated norms conflict with hobby-agnostic design)
+- Custom weight classification labels beyond base/worn/consumable
+- Server-side full-text search (premature for single-user scale)
+- Status change timestamps on candidates (useful but not essential now)
 
 ### Architecture Approach
 
-The architecture is a monolithic Bun process with a clear 4-layer structure: API routes (HTTP concerns), service layer (business logic and calculations), Drizzle ORM (type-safe data access), and bun:sqlite (embedded storage). There are no microservices, no Docker, no external database server. The client is a React SPA served as static files by the same Bun process. Internal communication is REST + JSON; no WebSockets needed. The data model has three primary entities — items, threads (with candidates), and setups — connected by explicit foreign keys and a junction table for the many-to-many setup-to-items relationship.
+All v1.2 features integrate into the existing three-layer architecture (client/server/database) with minimal structural changes. The client layer gains 5 new files (SearchBar, WeightChart, UnitSelector components; useFormatWeight hook; migration SQL) and modifies 15 existing files. The server layer changes are limited to the setup service (weight classification PATCH endpoint, updated sync function) and thread service (candidate status field passthrough). No new route registrations are needed in `src/server/index.ts`. The API layer (`lib/api.ts`) and UI state store (`uiStore.ts`) require no changes.
 
 **Major components:**
-1. Collection (items): Core entity. Source of truth for owned gear. Every other feature references items.
-2. Planning Threads (threads + candidates): Pre-purchase research. Thread lifecycle is a state machine; resolution is transactional.
-3. Setups: Named loadouts composed from collection items. Totals are always computed live from item data, never cached.
-4. Service Layer: Business logic isolated from HTTP concerns. Enables testing without HTTP mocking. Key: `calculateSetupTotals()`, `computeCandidateImpact()`.
-5. Dashboard: Read-only aggregation. Built last since it reads from all other entities.
-6. Image Storage: Filesystem (`./uploads/` or `data/images/{item-id}/`) with relative paths in DB. Thumbnails on upload.
-
-**Build order from ARCHITECTURE.md (follow this):**
-1. Database schema (Drizzle) — everything depends on this
-2. Items API (CRUD) — the core entity
-3. Collection UI — first visible feature, validates end-to-end
-4. Threads + candidates API and UI — depends on items for resolution
-5. Setups API and UI — depends on items for composition
-6. Dashboard — aggregates from all entities, build last
-7. Polish: image upload, impact calculations, status tracking
+1. **`useFormatWeight` hook** -- single source of truth for unit-aware weight formatting; wraps `useSetting("weightUnit")` and `formatWeight(grams, unit)` so all weight displays stay consistent
+2. **`WeightChart` component** -- reusable donut chart wrapper; used in collection page (weight by category) and setup detail page (weight by classification)
+3. **`SearchBar` component** -- reusable search input with clear button; collection page filters via `useMemo` over the cached `useItems()` data
+4. **Updated `syncSetupItems`** -- breaking API change from `{ itemIds: number[] }` to `{ items: Array<{ itemId, weightClass }> }`; single call site (ItemPicker.tsx) makes this safe
+5. **`PATCH /api/setups/:id/items/:itemId`** -- new endpoint for updating weight classification without triggering full sync (which would destroy classification data)
 
 ### Critical Pitfalls
 
-1. **Unit handling treated as display-only** — Store all weights as canonical grams at write time. Accept any unit as input, convert on save. Build a `weightToGrams(value, unit)` utility on day one. A bare number field with no unit tracking will silently corrupt all aggregates when users paste specs in mixed units.
+1. **Weight unit conversion rounding drift** -- bidirectional conversion in edit forms causes grams to drift over multiple edit cycles. Always load stored grams from the API, convert for display, and convert user input back to grams once on save. Never re-convert from a previously displayed value.
 
-2. **Rigid category hierarchy** — Use user-defined flat tags, not a hardcoded category tree. A `categories` table with `parent_id` foreign keys will fail the moment a user tries to track sim racing gear or photography equipment. Tags allow many-to-many, support any hobby, and do not require schema changes to add a new domain.
+2. **Weight classification at the wrong level** -- placing `classification` on the `items` table instead of `setup_items` prevents per-setup classification. A rain jacket is "worn" in summer but "base weight" in winter. This is the single most important schema decision in v1.2 and is costly to reverse.
 
-3. **Thread state machine complexity** — Model the thread lifecycle as an explicit state machine before writing any code. Document valid transitions. The "resolve thread" action must be a single atomic transaction: validate winner exists, create collection item, mark thread resolved, update candidate statuses. Without this, impossible states (resolved thread with active candidates, ghost items in collection) accumulate silently.
+3. **Chart data diverging from displayed totals** -- the codebase already has two computation paths (SQL aggregates in `totals.service.ts` vs. JavaScript reduce in `$setupId.tsx`). Adding charts creates a third. Use a shared utility for weight summation and convert units only at the final display step.
 
-4. **Setup totals cached in the database** — Never store `totalWeight` or `totalCost` on a setup record. Always compute from live item data via `SUM()`. Cached totals go stale the moment any member item is edited, and the bugs are subtle (the UI shows a total that doesn't match the items).
+4. **Server-side search for client-side data** -- adding search API parameters creates React Query cache fragmentation and unnecessary latency. Keep filtering client-side with `useMemo` over the cached items array.
 
-5. **Comparison view that displays data but doesn't aid decisions** — The comparison view must show deltas between candidates and against the item being replaced from the collection, not just raw values side by side. Color-code lighter/heavier, cheaper/more expensive. A comparison table with no computed differences is worse than a spreadsheet.
-
-**Additional high-priority pitfalls to address per phase:**
-- Currency stored as floats (use integer cents always)
-- Image paths stored as absolute paths or as BLOBs for full-size images
-- Thread resolution is destructive (archive threads, don't delete them — users need to reference why they chose X over Y)
-- Item deletion without setup impact warning
+5. **Test helper desync with schema** -- the manual `createTestDb()` in `tests/helpers/db.ts` duplicates schema in raw SQL. Every column addition must be mirrored there or tests pass against the wrong schema.
 
 ## Implications for Roadmap
 
-Based on the combined research, a 5-phase structure is recommended. Phases 1-3 deliver the v1 MVP; Phases 4-5 deliver the v1.x feature set.
+Based on combined research, a 5-phase structure is recommended:
 
-### Phase 1: Foundation — Data Model, Infrastructure, Core Item CRUD
+### Phase 1: Weight Unit Selection
 
-**Rationale:** Everything depends on getting the data model right. Unit handling, currency precision, category flexibility, image storage strategy, and the items schema are all Phase 1 decisions. Getting these wrong requires expensive data migrations. The architecture research explicitly states: "Database schema + Drizzle setup — Everything depends on the data model." The pitfalls research agrees: 6 of 9 pitfalls have "Phase 1" as their prevention phase.
+**Rationale:** Foundational infrastructure. The `formatWeight` refactor touches every component that displays weight (~8 call sites). All subsequent features depend on this formatter working correctly with unit awareness. Building this first means classification totals, chart labels, and setup breakdowns automatically display in the user's preferred unit.
 
-**Delivers:** Working gear catalog — users can add, edit, delete, and browse their collection. Item CRUD with all core fields. Weight unit conversion. User-defined categories. Image upload with thumbnail generation and cleanup on delete. SQLite database with WAL mode enabled, automatic backup mechanism, and all schemas finalized.
+**Delivers:** Global weight unit preference (g/oz/lb/kg) stored in settings, `useFormatWeight` hook, updated `formatWeight` function, UnitSelector component in TotalsBar, correct unit display across all existing weight surfaces (ItemCard, CandidateCard, CategoryHeader, TotalsBar, setup detail), correct unit handling in ItemForm and CandidateForm weight inputs.
 
-**Features from FEATURES.md:** Item CRUD with core fields, user-defined categories, weight unit support (g/oz/lb/kg), notes and product URL fields, search and filter.
+**Addresses:** Weight unit selection (table stakes from FEATURES.md)
 
-**Pitfalls to prevent:** Unit handling (canonical grams), currency precision (integer cents), category flexibility (user-defined tags, no hierarchy), image storage (relative paths, thumbnails), data loss prevention (WAL mode, auto-backup mechanism).
+**Avoids:** Rounding drift (Pitfall 1), inconsistent unit application (Pitfall 7), flash of unconverted weights on load
 
-**Research flag:** Standard patterns. Schema design for inventory apps is well-documented. No research phase needed.
+**Schema changes:** None (uses existing settings table key-value store)
 
----
+### Phase 2: Search, Filter, and Planning Category Filter
 
-### Phase 2: Planning Threads — The Core Differentiator
+**Rationale:** Pure client-side addition with no schema changes, no API changes, and no dependencies on other v1.2 features. Immediately useful as collections grow. The planning category filter upgrade fits naturally here since both involve filter UX and the icon-aware dropdown is a shared component.
 
-**Rationale:** Threads are why GearBox exists. The feature dependency graph in FEATURES.md shows threads require items to exist (to resolve candidates into the collection), which is why Phase 1 must complete first. The thread state machine is the most complex feature in the product and gets its own phase to ensure the state transitions are modeled correctly before any UI is built.
+**Delivers:** Search input in collection view, icon-aware category filter dropdown (reused in gear and planning tabs), filtered item display with count ("showing 12 of 47 items"), URL search param persistence, empty state for no results, result count display.
 
-**Delivers:** Complete purchase planning workflow — create threads, add candidates with weight/price/notes, compare candidates side-by-side with weight/cost deltas (not just raw values), resolve threads by selecting a winner and moving it to the collection, archive resolved threads.
+**Addresses:** Search items by name (table stakes), filter by category (table stakes), planning category filter upgrade (differentiator)
 
-**Features from FEATURES.md:** Planning threads, side-by-side candidate comparison (with deltas), thread resolution workflow. Does not include status tracking (researching/ordered/arrived) or priority/ranking — those are v1.x.
+**Avoids:** Server-side search anti-pattern (Pitfall 3), search state lost on tab switch (UX pitfall), category groups disappearing incorrectly during filtering
 
-**Pitfalls to prevent:** Thread state machine complexity (model transitions explicitly, transactional resolution), comparison usefulness (show deltas and impact, not just raw data), thread archiving (never destructive resolution).
+**Schema changes:** None
 
-**Research flag:** Needs careful design work before coding. The state machine for thread lifecycle (open -> in-progress -> resolved/cancelled) combined with candidate status (researching / ordered / arrived) and the resolution side-effect (create collection item) has no off-the-shelf reference implementation. Design the state diagram first.
+### Phase 3: Candidate Status Tracking
 
----
+**Rationale:** Simple schema change on `thread_candidates` with minimal integration surface. Independent of other features. Low complexity but requires awareness of the existing thread resolution flow. Schema change should be batched with Phase 4 into one Drizzle migration.
 
-### Phase 3: Setups — Named Loadouts and Composition
+**Delivers:** Status column on candidates (researching/ordered/arrived), status badge on CandidateCard with click-to-cycle, status field in CandidateForm, Zod enum validation, status transition validation in service layer (researching -> ordered -> arrived, no backward transitions).
 
-**Rationale:** Setups require items to exist (Phase 1) and benefit from threads being stable (Phase 2) because thread resolution can affect setup membership (the replaced item should be updatable in setups). The many-to-many setup-items relationship and the setup integrity pitfall require careful foreign key design.
+**Addresses:** Candidate status tracking (differentiator -- unique to GearBox)
 
-**Delivers:** Named setups composed from collection items. Weight and cost totals computed live (never cached). Base/worn/consumable weight classification per item per setup. Category weight breakdown. Item deletion warns about setup membership. Visual indicator when a setup item is no longer in the collection.
+**Avoids:** Status without transition validation (Pitfall 4), test helper desync (Pitfall 6), not handling candidate status during thread resolution
 
-**Features from FEATURES.md:** Named setups with item selection and totals, setup weight/cost breakdown by category, automatic totals.
+**Schema changes:** Add `status TEXT NOT NULL DEFAULT 'researching'` to `thread_candidates`
 
-**Pitfalls to prevent:** Setup totals cached in DB (always compute live), setup composition breaks on collection changes (explicit `ON DELETE` behavior, visual indicators for missing items, no silent CASCADE).
+### Phase 4: Weight Classification
 
-**Research flag:** Standard patterns for junction table composition. No research phase needed for the setup-items relationship. The weight classification (base/worn/consumable) per setup entry is worth a design session — this is per-setup metadata on the junction, not a property of the item itself.
+**Rationale:** Most architecturally significant change in v1.2. Changes the sync API shape (breaking change, single call site). Requires Phase 1 to be complete so classification totals display in the correct unit. Schema migration should be batched with Phase 3.
 
----
+**Delivers:** `weightClass` column on `setup_items`, updated sync endpoint accepting `{ items: Array<{ itemId, weightClass }> }`, new `PATCH /api/setups/:id/items/:itemId` endpoint, three-segment classification toggle per item in setup detail view, base/worn/consumable weight subtotals.
 
-### Phase 4: Dashboard and Polish
+**Addresses:** Weight classification base/worn/consumable (table stakes), per-setup classification (differentiator)
 
-**Rationale:** The architecture research explicitly states "Dashboard — aggregates stats from all other entities. Build last since it reads from everything." Dashboard requires all prior phases to be stable since it reads from items, threads, and setups simultaneously. This phase also adds the weight visualization chart that requires a full dataset to be meaningful.
+**Avoids:** Classification on items table (Pitfall 2), test helper desync (Pitfall 6), losing classification data on sync
 
-**Delivers:** Dashboard home page with summary cards (item count, active threads, setup count, collection value). Weight distribution visualization (pie/bar chart by category). Dashboard stats endpoint (`/api/stats`) as a read-only aggregation. General UI polish for the "light, airy, minimalist" aesthetic.
+**Schema changes:** Add `weight_class TEXT NOT NULL DEFAULT 'base'` to `setup_items`
 
-**Features from FEATURES.md:** Dashboard home page, weight distribution visualization.
+### Phase 5: Weight Distribution Charts
 
-**Research flag:** Standard patterns. Dashboard aggregation is a straightforward read-only endpoint. Charting is well-documented. No research phase needed.
+**Rationale:** Depends on Phase 1 (unit-aware labels) and Phase 4 (classification data for setup breakdown). Only phase requiring a new npm dependency. Highest UI complexity but lowest architectural risk -- read-only visualization of existing data.
 
----
+**Delivers:** `react-minimal-pie-chart` integration, `WeightChart` component, collection-level donut chart (weight by category from `useTotals()`), setup-level donut chart (weight by classification), chart legend with consistent colors, hover tooltips with formatted weights.
 
-### Phase 5: v1.x Enhancements
+**Addresses:** Weight distribution visualization (differentiator)
 
-**Rationale:** These features add significant value but depend on the core (Phases 1-3) being proven out. Impact preview requires both stable setups and stable threads. CSV import/export validates the data model is clean (if import is buggy, the model has problems). Photos add storage complexity that is easier to handle once the core CRUD flow is solid.
+**Avoids:** Chart/totals divergence (Pitfall 5), chart crashing on null-weight items, unnecessary chart re-renders on unrelated state changes
 
-**Delivers:** Impact preview (how a thread candidate changes a specific setup's weight/cost). Thread item status tracking (researching / ordered / arrived). Priority/ranking within threads. Photos per item (upload, display, cleanup). CSV import/export with unit detection.
-
-**Features from FEATURES.md:** Impact preview, status tracking, priority/ranking, photos per item, CSV import/export.
-
-**Pitfalls to prevent:** CSV import missing unit conversion (must detect and convert oz/lb/kg to grams on import). Image uploads without size/type validation. Product URLs not sanitized (validate http/https protocol, render with `rel="noopener noreferrer"`).
-
-**Research flag:** CSV import with unit detection may need a design pass — handling "5 oz", "142g", "0.3 lb" in the same weight column requires a parsing strategy. Worth a short research spike before implementation.
-
----
+**Schema changes:** None (npm dependency: `bun add react-minimal-pie-chart`)
 
 ### Phase Ordering Rationale
 
-- **Data model first:** Six of nine pitfalls identified are Phase 1 prevention items. The schema is the hardest thing to change later and the most consequential.
-- **Threads before setups:** Thread resolution creates collection items; setup composition consumes them. But more importantly, threads are the differentiating feature — proving the thread workflow works is more valuable than setups.
-- **Dashboard last:** Explicitly recommended by architecture research. Aggregating from incomplete entities produces misleading data and masks bugs.
-- **Impact preview in Phase 5:** This feature requires both stable setups (Phase 3) and stable threads (Phase 2). Building it before both are solid means rebuilding it when either changes.
-- **Photos deferred to Phase 5:** The core value proposition is weight/cost tracking and purchase planning, not a photo gallery. Adding photo infrastructure in Phase 1 increases scope without validating the core concept.
+- **Phase 1 first** because `formatWeight` is called by every weight-displaying component. Refactoring it after other features are built means touching the same files twice.
+- **Phase 2 is independent** and could be built in any order, but sequencing it second allows the team to ship a quick win while Phase 3/4 schema changes are designed.
+- **Batch Phase 3 + Phase 4 schema migrations** into one `bun run db:generate` run. Both add columns to existing tables; a single migration simplifies deployment.
+- **Phase 4 after Phase 1** because classification totals need the unit-aware formatter.
+- **Phase 5 last** because it is pure visualization depending on data from Phases 1 and 4, and introduces the only external dependency.
 
 ### Research Flags
 
-**Needs design/research before coding:**
-- **Phase 2 (Thread State Machine):** Design the state diagram for thread lifecycle x candidate status before writing any code. Define all valid transitions and invalid states explicitly. This is the most stateful feature in the product and has no off-the-shelf pattern to follow.
-- **Phase 5 (CSV Import):** Design the column-mapping and unit-detection strategy before implementation. The spreadsheet-to-app migration workflow is critical for the target audience (users migrating from gear spreadsheets).
+Phases likely needing deeper research during planning:
+- **Phase 4 (Weight Classification):** The sync API shape change is breaking. The existing delete-all/re-insert pattern destroys classification data. Needs careful design of the PATCH endpoint and how ItemPicker interacts with classification preservation during item add/remove. Worth a `/gsd:research-phase`.
+- **Phase 5 (Weight Distribution Charts):** react-minimal-pie-chart API specifics (label rendering, responsive sizing, animation control) should be validated with a quick prototype. Consider a short research spike.
 
-**Standard patterns — no research phase needed:**
-- **Phase 1 (Data model + CRUD):** Schema design for inventory apps is well-documented. Drizzle + bun:sqlite patterns are covered in official docs.
-- **Phase 3 (Setups):** Junction table composition is a standard relational pattern. Foreign key behavior for integrity is documented.
-- **Phase 4 (Dashboard):** Aggregation endpoints and charting are standard. No novel patterns.
+Phases with standard patterns (skip research-phase):
+- **Phase 1 (Weight Unit Selection):** Well-documented pattern. Extend `formatWeight`, add a `useSetting` wrapper, propagate through components. No unknowns.
+- **Phase 2 (Search/Filter):** Textbook client-side filtering with `useMemo`. No API changes. Standard React pattern.
+- **Phase 3 (Candidate Status):** Simple column addition with Zod enum validation. Existing `useUpdateCandidate` mutation already handles partial updates.
 
 ## Confidence Assessment
 
 | Area | Confidence | Notes |
 |------|------------|-------|
-| Stack | HIGH | All technologies verified against official docs. Version compatibility confirmed. One flag: verify `@hono/zod-validator` supports Zod 4.x before starting. |
-| Features | HIGH | Competitor analysis is thorough (LighterPack, GearGrams, Packstack, Hikt all compared). Feature gaps and differentiators are clearly identified. |
-| Architecture | HIGH | Bun fullstack monolith pattern is official and well-documented. Service layer and data flow patterns are standard. |
-| Pitfalls | HIGH | Pitfalls are domain-specific and well-sourced. SQLite BLOB guidance from official SQLite docs. Comparison UX from NN/g. Unit conversion antipatterns documented. |
+| Stack | HIGH | Only one new dependency (react-minimal-pie-chart). React 19 compatibility verified via package.json peerDeps. All other features use existing stack with no changes. |
+| Features | HIGH | Feature set derived from analysis of 8+ competing tools (LighterPack, Hikt, PackLight, Packstack, HikeLite, Packrat, OutPack, BPL Calculator). Clear consensus on table stakes vs. differentiators. |
+| Architecture | HIGH | Based on direct codebase analysis with integration points mapped to specific files. The 5 new / 15 modified file inventory is concrete and verified against the existing codebase. |
+| Pitfalls | HIGH | Derived from codebase-specific patterns (test helper duplication, dual computation paths) combined with domain risks (unit conversion rounding, classification scope). Not generic warnings. |
 
-**Overall confidence: HIGH**
+**Overall confidence:** HIGH
 
 ### Gaps to Address
 
-- **Zod 4 / @hono/zod-validator compatibility:** STACK.md flags this explicitly. Verify before starting. If incompatible, pin Zod 3.23.x. This is a quick check, not a blocker.
-
-- **Bun fullstack vs. Vite proxy setup:** STACK.md describes the Vite dev server proxy pattern (standard approach), while ARCHITECTURE.md describes Bun's HTML-based routing with `Bun.serve()` (newer approach). These are two valid patterns. The architecture file's approach (Bun fullstack) is simpler for production deployment. Confirm which pattern to follow before project setup — they require different `vite.config.ts` and entry point structures.
-
-- **Weight classification (base/worn/consumable) data model:** Where does this live? On the `setup_items` junction table (per-setup classification, same item can be "base" in one setup and "worn" in another) or on the item itself (one classification for all setups)? The per-setup model is more flexible but more complex. Decide in Phase 1 schema design, not Phase 3 when setups are built.
-
-- **Tag vs. single-category field:** PITFALLS.md recommends a flat tag system. FEATURES.md implies a single "category" field. The right answer is probably a single optional category field (for broad grouping, e.g., "clothing") plus user-defined tags for fine-grained organization. Confirm the data model in Phase 1.
+- **`lb` display format:** FEATURES.md suggests "2 lb 3 oz" (pounds + remainder ounces) while STACK.md suggests simpler decimal format. The traditional "lb + oz" format is more useful to American users but adds formatting complexity. Decide during Phase 1 implementation.
+- **Status change timestamps:** PITFALLS.md recommends storing `statusChangedAt` alongside `status` for staleness detection ("ordered 30 days ago -- still waiting?"). Low effort to add during the schema migration. Decide during Phase 3 planning.
+- **Sync API backward compatibility:** The sync endpoint shape changes from `{ itemIds: number[] }` to `{ items: [...] }`. Single call site (ItemPicker.tsx), but verify no external consumers exist before shipping.
+- **react-minimal-pie-chart responsive behavior:** SVG-based and should handle responsive sizing, but exact approach (CSS width vs. explicit size prop) should be validated in Phase 5. Not a risk, just a detail to confirm.
 
 ## Sources
 
 ### Primary (HIGH confidence)
-- [Bun official docs](https://bun.com/docs) — bun:sqlite, fullstack dev server, Bun.serve() routing
-- [Hono official docs](https://hono.dev/docs) — Bun integration, middleware patterns
-- [Drizzle ORM docs - Bun SQLite](https://orm.drizzle.team/docs/connect-bun-sqlite) — driver support, schema patterns
-- [Vite releases](https://vite.dev/releases) — v8.0 with Rolldown confirmed
-- [Tailwind CSS v4.2 blog](https://tailwindcss.com/blog/tailwindcss-v4) — CSS-native config, Vite plugin
-- [TanStack Router docs](https://tanstack.com/router/latest) — file-based routing, typed params
-- [TanStack Query docs](https://tanstack.com/query/latest) — cache invalidation, mutations
-- [SQLite Internal vs External BLOBs](https://sqlite.org/intern-v-extern-blob.html) — image storage guidance
-- [Comparison Tables — NN/g](https://www.nngroup.com/articles/comparison-tables/) — comparison UX best practices
+- [Drizzle ORM Filter Operators](https://orm.drizzle.team/docs/operators) -- like, eq, and operators for search/filter
+- [Drizzle ORM Conditional Filters Guide](https://orm.drizzle.team/docs/guides/conditional-filters-in-query) -- dynamic filter composition
+- [react-minimal-pie-chart GitHub](https://github.com/toomuchdesign/react-minimal-pie-chart) -- v9.1.2, React 19 peerDeps verified in package.json
+- [LighterPack](https://lighterpack.com/) -- base/worn/consumable classification standard, pie chart visualization pattern
+- [99Boulders LighterPack Tutorial](https://www.99boulders.com/lighterpack-tutorial) -- classification definitions and feature walkthrough
+- [BackpackPeek Pack Weight Calculator Guide](https://backpackpeek.com/blog/pack-weight-calculator-base-weight-guide) -- weight classification methodology
+- Direct codebase analysis of GearBox v1.1 -- schema.ts, services, hooks, routes, test helpers
 
 ### Secondary (MEDIUM confidence)
-- [Hikt Blog: Best Backpacking Gear Apps 2026](https://hikt.app/blog/best-backpacking-gear-apps-2026/) — competitor feature analysis
-- [Building Full-Stack App with Bun.js, React and Drizzle ORM](https://awplife.com/building-full-stack-app-with-bun-js-react-drizzle/) — project structure reference
-- [Designing better file organization around tags, not hierarchies](https://www.nayuki.io/page/designing-better-file-organization-around-tags-not-hierarchies) — tags vs hierarchy rationale
+- [Hikt](https://hikt.app/) -- searchable gear closet, base vs worn weight display
+- [PackLight (iOS)](https://apps.apple.com/us/app/packlight-for-backpacking/id1054845207) -- search, categories, bar graph visualization
+- [Packstack](https://www.packstack.io/) -- base/worn/consumable weight separation
+- [Packrat](https://www.packrat.app/) -- flexible weight unit input and display conversion
+- [Recharts React 19 issue #6857](https://github.com/recharts/recharts/issues/6857) -- rendering issues with React 19.2.3
+- [TanStack Query filtering discussions](https://github.com/TanStack/query/discussions/1113) -- client-side vs server-side filtering patterns
+- [LogRocket Best React Chart Libraries 2025](https://blog.logrocket.com/best-react-chart-libraries-2025/) -- chart library comparison
 
-### Tertiary (LOW confidence / needs validation)
-- [Zod v4 release notes](https://zod.dev/v4) — @hono/zod-validator compatibility with Zod 4 unconfirmed, verify before use
+### Tertiary (LOW confidence)
+- [SQLite LIKE case sensitivity](https://github.com/drizzle-team/drizzle-orm-docs/issues/239) -- LIKE is case-insensitive in SQLite (relevant only if search moves server-side)
+- [Drizzle ORM SQLite migration pitfalls #1313](https://github.com/drizzle-team/drizzle-orm/issues/1313) -- data loss bug with push + add column (monitor during migration)
 
 ---
-*Research completed: 2026-03-14*
+*Research completed: 2026-03-16*
 *Ready for roadmap: yes*

README.md

@@ -1,2 +1,83 @@
 # GearBox
 
+A single-user web app for managing gear collections (bikepacking, sim racing, etc.), tracking weight and price, and planning purchases through research threads.
+
+## Features
+
+- Organize gear into categories with custom icons
+- Track weight and price for every item
+- Create setups (packing lists) from your collection with automatic weight/cost totals
+- Research threads for comparing candidates before buying
+- Image uploads for items and candidates
+
+## Quick Start
+
+### Docker Compose (recommended)
+
+Create a `docker-compose.yml`:
+
+```yaml
+services:
+  gearbox:
+    image: gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
+    container_name: gearbox
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_PATH=./data/gearbox.db
+    volumes:
+      - gearbox-data:/app/data
+      - gearbox-uploads:/app/uploads
+    healthcheck:
+      test: ["CMD", "bun", "-e", "fetch('http://localhost:3000/api/health').then(r=>r.ok?process.exit(0):process.exit(1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
+    restart: unless-stopped
+
+volumes:
+  gearbox-data:
+  gearbox-uploads:
+```
+
+Then run:
+
+```bash
+docker compose up -d
+```
+
+GearBox will be available at `http://localhost:3000`.
+
+### Docker
+
+```bash
+docker run -d \
+  --name gearbox \
+  -p 3000:3000 \
+  -e NODE_ENV=production \
+  -e DATABASE_PATH=./data/gearbox.db \
+  -v gearbox-data:/app/data \
+  -v gearbox-uploads:/app/uploads \
+  --restart unless-stopped \
+  gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
+```
+
+## Data
+
+All data is stored in two Docker volumes:
+
+- **gearbox-data** -- SQLite database
+- **gearbox-uploads** -- uploaded images
+
+Back up these volumes to preserve your data.
+
+## Updating
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Database migrations run automatically on startup.

bun.lock

@@ -15,6 +15,7 @@
         "lucide-react": "^0.577.0",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
+        "recharts": "^3.8.0",
         "tailwindcss": "^4.2.1",
         "zod": "^4.3.6",
         "zustand": "^5.0.11",
@@ -177,6 +178,8 @@
 
     "@oxc-project/types": ["@oxc-project/types@0.115.0", "", {}, "sha512-4n91DKnebUS4yjUHl2g3/b2T+IUdCfmoZGhmwsovZCDaJSs+QkVAM+0AqqTxHSsHfeiMuueT75cZaZcT/m0pSw=="],
 
+    "@reduxjs/toolkit": ["@reduxjs/toolkit@2.11.2", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "@standard-schema/utils": "^0.3.0", "immer": "^11.0.0", "redux": "^5.0.1", "redux-thunk": "^3.1.0", "reselect": "^5.1.0" }, "peerDependencies": { "react": "^16.9.0 || ^17.0.0 || ^18 || ^19", "react-redux": "^7.2.1 || ^8.1.3 || ^9.0.0" }, "optionalPeers": ["react", "react-redux"] }, "sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ=="],
+
     "@rolldown/binding-android-arm64": ["@rolldown/binding-android-arm64@1.0.0-rc.9", "", { "os": "android", "cpu": "arm64" }, "sha512-lcJL0bN5hpgJfSIz/8PIf02irmyL43P+j1pTCfbD1DbLkmGRuFIA4DD3B3ZOvGqG0XiVvRznbKtN0COQVaKUTg=="],
 
     "@rolldown/binding-darwin-arm64": ["@rolldown/binding-darwin-arm64@1.0.0-rc.9", "", { "os": "darwin", "cpu": "arm64" }, "sha512-J7Zk3kLYFsLtuH6U+F4pS2sYVzac0qkjcO5QxHS7OS7yZu2LRs+IXo+uvJ/mvpyUljDJ3LROZPoQfgBIpCMhdQ=="],
@@ -209,6 +212,10 @@
 
     "@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-rc.7", "", {}, "sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA=="],
 
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
+
+    "@standard-schema/utils": ["@standard-schema/utils@0.3.0", "", {}, "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g=="],
+
     "@tailwindcss/node": ["@tailwindcss/node@4.2.1", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.31.1", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.1" } }, "sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg=="],
 
     "@tailwindcss/oxide": ["@tailwindcss/oxide@4.2.1", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.2.1", "@tailwindcss/oxide-darwin-arm64": "4.2.1", "@tailwindcss/oxide-darwin-x64": "4.2.1", "@tailwindcss/oxide-freebsd-x64": "4.2.1", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.1", "@tailwindcss/oxide-linux-arm64-gnu": "4.2.1", "@tailwindcss/oxide-linux-arm64-musl": "4.2.1", "@tailwindcss/oxide-linux-x64-gnu": "4.2.1", "@tailwindcss/oxide-linux-x64-musl": "4.2.1", "@tailwindcss/oxide-wasm32-wasi": "4.2.1", "@tailwindcss/oxide-win32-arm64-msvc": "4.2.1", "@tailwindcss/oxide-win32-x64-msvc": "4.2.1" } }, "sha512-yv9jeEFWnjKCI6/T3Oq50yQEOqmpmpfzG1hcZsAOaXFQPfzWprWrlHSdGPEF3WQTi8zu8ohC9Mh9J470nT5pUw=="],
@@ -275,12 +282,32 @@
 
     "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
 
+    "@types/d3-array": ["@types/d3-array@3.2.2", "", {}, "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw=="],
+
+    "@types/d3-color": ["@types/d3-color@3.1.3", "", {}, "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A=="],
+
+    "@types/d3-ease": ["@types/d3-ease@3.0.2", "", {}, "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA=="],
+
+    "@types/d3-interpolate": ["@types/d3-interpolate@3.0.4", "", { "dependencies": { "@types/d3-color": "*" } }, "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA=="],
+
+    "@types/d3-path": ["@types/d3-path@3.1.1", "", {}, "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg=="],
+
+    "@types/d3-scale": ["@types/d3-scale@4.0.9", "", { "dependencies": { "@types/d3-time": "*" } }, "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw=="],
+
+    "@types/d3-shape": ["@types/d3-shape@3.1.8", "", { "dependencies": { "@types/d3-path": "*" } }, "sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w=="],
+
+    "@types/d3-time": ["@types/d3-time@3.0.4", "", {}, "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g=="],
+
+    "@types/d3-timer": ["@types/d3-timer@3.0.2", "", {}, "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw=="],
+
     "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
     "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
     "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
 
+    "@types/use-sync-external-store": ["@types/use-sync-external-store@0.0.6", "", {}, "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg=="],
+
     "@vitejs/plugin-react": ["@vitejs/plugin-react@6.0.1", "", { "dependencies": { "@rolldown/pluginutils": "1.0.0-rc.7" }, "peerDependencies": { "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0", "babel-plugin-react-compiler": "^1.0.0", "vite": "^8.0.0" }, "optionalPeers": ["@rolldown/plugin-babel", "babel-plugin-react-compiler"] }, "sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ=="],
 
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
@@ -329,8 +356,32 @@
 
     "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
 
+    "d3-array": ["d3-array@3.2.4", "", { "dependencies": { "internmap": "1 - 2" } }, "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg=="],
+
+    "d3-color": ["d3-color@3.1.0", "", {}, "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA=="],
+
+    "d3-ease": ["d3-ease@3.0.1", "", {}, "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w=="],
+
+    "d3-format": ["d3-format@3.1.2", "", {}, "sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg=="],
+
+    "d3-interpolate": ["d3-interpolate@3.0.1", "", { "dependencies": { "d3-color": "1 - 3" } }, "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g=="],
+
+    "d3-path": ["d3-path@3.1.0", "", {}, "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ=="],
+
+    "d3-scale": ["d3-scale@4.0.2", "", { "dependencies": { "d3-array": "2.10.0 - 3", "d3-format": "1 - 3", "d3-interpolate": "1.2.0 - 3", "d3-time": "2.1.1 - 3", "d3-time-format": "2 - 4" } }, "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ=="],
+
+    "d3-shape": ["d3-shape@3.2.0", "", { "dependencies": { "d3-path": "^3.1.0" } }, "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA=="],
+
+    "d3-time": ["d3-time@3.1.0", "", { "dependencies": { "d3-array": "2 - 3" } }, "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q=="],
+
+    "d3-time-format": ["d3-time-format@4.1.0", "", { "dependencies": { "d3-time": "1 - 3" } }, "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg=="],
+
+    "d3-timer": ["d3-timer@3.0.1", "", {}, "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA=="],
+
     "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
 
+    "decimal.js-light": ["decimal.js-light@2.5.1", "", {}, "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg=="],
+
     "decompress-response": ["decompress-response@6.0.0", "", { "dependencies": { "mimic-response": "^3.1.0" } }, "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ=="],
 
     "deep-extend": ["deep-extend@0.6.0", "", {}, "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA=="],
@@ -349,6 +400,8 @@
 
     "enhanced-resolve": ["enhanced-resolve@5.20.0", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ=="],
 
+    "es-toolkit": ["es-toolkit@1.45.1", "", {}, "sha512-/jhoOj/Fx+A+IIyDNOvO3TItGmlMKhtX8ISAHKE90c4b/k1tqaqEZ+uUqfpU8DMnW5cgNJv606zS55jGvza0Xw=="],
+
     "esbuild": ["esbuild@0.25.12", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.25.12", "@esbuild/android-arm": "0.25.12", "@esbuild/android-arm64": "0.25.12", "@esbuild/android-x64": "0.25.12", "@esbuild/darwin-arm64": "0.25.12", "@esbuild/darwin-x64": "0.25.12", "@esbuild/freebsd-arm64": "0.25.12", "@esbuild/freebsd-x64": "0.25.12", "@esbuild/linux-arm": "0.25.12", "@esbuild/linux-arm64": "0.25.12", "@esbuild/linux-ia32": "0.25.12", "@esbuild/linux-loong64": "0.25.12", "@esbuild/linux-mips64el": "0.25.12", "@esbuild/linux-ppc64": "0.25.12", "@esbuild/linux-riscv64": "0.25.12", "@esbuild/linux-s390x": "0.25.12", "@esbuild/linux-x64": "0.25.12", "@esbuild/netbsd-arm64": "0.25.12", "@esbuild/netbsd-x64": "0.25.12", "@esbuild/openbsd-arm64": "0.25.12", "@esbuild/openbsd-x64": "0.25.12", "@esbuild/openharmony-arm64": "0.25.12", "@esbuild/sunos-x64": "0.25.12", "@esbuild/win32-arm64": "0.25.12", "@esbuild/win32-ia32": "0.25.12", "@esbuild/win32-x64": "0.25.12" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg=="],
 
     "esbuild-register": ["esbuild-register@3.6.0", "", { "dependencies": { "debug": "^4.3.4" }, "peerDependencies": { "esbuild": ">=0.12 <1" } }, "sha512-H2/S7Pm8a9CL1uhp9OvjwrBh5Pvx0H8qVOxNu8Wed9Y7qv56MPtq+GGM8RJpq6glYJn9Wspr8uw7l55uyinNeg=="],
@@ -357,6 +410,8 @@
 
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
 
+    "eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
+
     "expand-template": ["expand-template@2.0.3", "", {}, "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
@@ -385,10 +440,14 @@
 
     "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
 
+    "immer": ["immer@10.2.0", "", {}, "sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw=="],
+
     "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
 
     "ini": ["ini@1.3.8", "", {}, "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew=="],
 
+    "internmap": ["internmap@2.0.3", "", {}, "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg=="],
+
     "is-binary-path": ["is-binary-path@2.1.0", "", { "dependencies": { "binary-extensions": "^2.0.0" } }, "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw=="],
 
     "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
@@ -477,12 +536,24 @@
 
     "react-dom": ["react-dom@19.2.4", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.4" } }, "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ=="],
 
+    "react-is": ["react-is@19.2.4", "", {}, "sha512-W+EWGn2v0ApPKgKKCy/7s7WHXkboGcsrXE+2joLyVxkbyVQfO3MUEaUQDHoSmb8TFFrSKYa9mw64WZHNHSDzYA=="],
+
+    "react-redux": ["react-redux@9.2.0", "", { "dependencies": { "@types/use-sync-external-store": "^0.0.6", "use-sync-external-store": "^1.4.0" }, "peerDependencies": { "@types/react": "^18.2.25 || ^19", "react": "^18.0 || ^19", "redux": "^5.0.0" }, "optionalPeers": ["@types/react", "redux"] }, "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g=="],
+
     "readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
 
     "readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
 
     "recast": ["recast@0.23.11", "", { "dependencies": { "ast-types": "^0.16.1", "esprima": "~4.0.0", "source-map": "~0.6.1", "tiny-invariant": "^1.3.3", "tslib": "^2.0.1" } }, "sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA=="],
 
+    "recharts": ["recharts@3.8.0", "", { "dependencies": { "@reduxjs/toolkit": "^1.9.0 || 2.x.x", "clsx": "^2.1.1", "decimal.js-light": "^2.5.1", "es-toolkit": "^1.39.3", "eventemitter3": "^5.0.1", "immer": "^10.1.1", "react-redux": "8.x.x || 9.x.x", "reselect": "5.1.1", "tiny-invariant": "^1.3.3", "use-sync-external-store": "^1.2.2", "victory-vendor": "^37.0.2" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-is": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Z/m38DX3L73ExO4Tpc9/iZWHmHnlzWG4njQbxsF5aSjwqmHNDDIm0rdEBArkwsBvR8U6EirlEHiQNYWCVh9sGQ=="],
+
+    "redux": ["redux@5.0.1", "", {}, "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w=="],
+
+    "redux-thunk": ["redux-thunk@3.1.0", "", { "peerDependencies": { "redux": "^5.0.0" } }, "sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw=="],
+
+    "reselect": ["reselect@5.1.1", "", {}, "sha512-K/BG6eIky/SBpzfHZv/dd+9JBFiS4SWV7FIujVyJRux6e45+73RaUHXLmIR1f7WOMaQ0U1km6qwklRQxpJJY0w=="],
+
     "resolve-pkg-maps": ["resolve-pkg-maps@1.0.0", "", {}, "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="],
 
     "rolldown": ["rolldown@1.0.0-rc.9", "", { "dependencies": { "@oxc-project/types": "=0.115.0", "@rolldown/pluginutils": "1.0.0-rc.9" }, "optionalDependencies": { "@rolldown/binding-android-arm64": "1.0.0-rc.9", "@rolldown/binding-darwin-arm64": "1.0.0-rc.9", "@rolldown/binding-darwin-x64": "1.0.0-rc.9", "@rolldown/binding-freebsd-x64": "1.0.0-rc.9", "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.9", "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.9", "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.9", "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.9", "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.9", "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.9", "@rolldown/binding-linux-x64-musl": "1.0.0-rc.9", "@rolldown/binding-openharmony-arm64": "1.0.0-rc.9", "@rolldown/binding-wasm32-wasi": "1.0.0-rc.9", "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.9", "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.9" }, "bin": { "rolldown": "bin/cli.mjs" } }, "sha512-9EbgWge7ZH+yqb4d2EnELAntgPTWbfL8ajiTW+SyhJEC4qhBbkCKbqFV4Ge4zmu5ziQuVbWxb/XwLZ+RIO7E8Q=="],
@@ -545,6 +616,8 @@
 
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
+    "victory-vendor": ["victory-vendor@37.3.6", "", { "dependencies": { "@types/d3-array": "^3.0.3", "@types/d3-ease": "^3.0.0", "@types/d3-interpolate": "^3.0.1", "@types/d3-scale": "^4.0.2", "@types/d3-shape": "^3.1.0", "@types/d3-time": "^3.0.0", "@types/d3-timer": "^3.0.0", "d3-array": "^3.1.6", "d3-ease": "^3.0.1", "d3-interpolate": "^3.0.1", "d3-scale": "^4.0.2", "d3-shape": "^3.1.0", "d3-time": "^3.0.0", "d3-timer": "^3.0.1" } }, "sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ=="],
+
     "vite": ["vite@8.0.0", "", { "dependencies": { "@oxc-project/runtime": "0.115.0", "lightningcss": "^1.32.0", "picomatch": "^4.0.3", "postcss": "^8.5.8", "rolldown": "1.0.0-rc.9", "tinyglobby": "^0.2.15" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "@vitejs/devtools": "^0.0.0-alpha.31", "esbuild": "^0.27.0", "jiti": ">=1.21.0", "less": "^4.0.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "@vitejs/devtools", "esbuild", "jiti", "less", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-fPGaRNj9Zytaf8LEiBhY7Z6ijnFKdzU/+mL8EFBaKr7Vw1/FWcTBAMW0wLPJAGMPX38ZPVCVgLceWiEqeoqL2Q=="],
 
     "webpack-virtual-modules": ["webpack-virtual-modules@0.6.2", "", {}, "sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ=="],
@@ -559,6 +632,8 @@
 
     "@esbuild-kit/core-utils/esbuild": ["esbuild@0.18.20", "", { "optionalDependencies": { "@esbuild/android-arm": "0.18.20", "@esbuild/android-arm64": "0.18.20", "@esbuild/android-x64": "0.18.20", "@esbuild/darwin-arm64": "0.18.20", "@esbuild/darwin-x64": "0.18.20", "@esbuild/freebsd-arm64": "0.18.20", "@esbuild/freebsd-x64": "0.18.20", "@esbuild/linux-arm": "0.18.20", "@esbuild/linux-arm64": "0.18.20", "@esbuild/linux-ia32": "0.18.20", "@esbuild/linux-loong64": "0.18.20", "@esbuild/linux-mips64el": "0.18.20", "@esbuild/linux-ppc64": "0.18.20", "@esbuild/linux-riscv64": "0.18.20", "@esbuild/linux-s390x": "0.18.20", "@esbuild/linux-x64": "0.18.20", "@esbuild/netbsd-x64": "0.18.20", "@esbuild/openbsd-x64": "0.18.20", "@esbuild/sunos-x64": "0.18.20", "@esbuild/win32-arm64": "0.18.20", "@esbuild/win32-ia32": "0.18.20", "@esbuild/win32-x64": "0.18.20" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA=="],
 
+    "@reduxjs/toolkit/immer": ["immer@11.1.4", "", {}, "sha512-XREFCPo6ksxVzP4E0ekD5aMdf8WMwmdNaz6vuvxgI40UaEiu6q3p8X52aU6GdyvLY3XXX/8R7JOTXStz/nBbRw=="],
+
     "@tailwindcss/node/lightningcss": ["lightningcss@1.31.1", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.31.1", "lightningcss-darwin-arm64": "1.31.1", "lightningcss-darwin-x64": "1.31.1", "lightningcss-freebsd-x64": "1.31.1", "lightningcss-linux-arm-gnueabihf": "1.31.1", "lightningcss-linux-arm64-gnu": "1.31.1", "lightningcss-linux-arm64-musl": "1.31.1", "lightningcss-linux-x64-gnu": "1.31.1", "lightningcss-linux-x64-musl": "1.31.1", "lightningcss-win32-arm64-msvc": "1.31.1", "lightningcss-win32-x64-msvc": "1.31.1" } }, "sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ=="],
 
     "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.9.0", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.0", "tslib": "^2.4.0" }, "bundled": true }, "sha512-0DQ98G9ZQZOxfUcQn1waV2yS8aWdZ6kJMbYCJB3oUBecjWYO1fqJ+a1DRfPF3O5JEkwqwP1A9QEN/9mYm2Yd0w=="],

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   gearbox:
-    build: .
+    image: gitea.jeanlucmakiola.de/makiolaj/gearbox:latest
     container_name: gearbox
     ports:
       - "3000:3000"
@@ -10,6 +10,12 @@ services:
     volumes:
       - gearbox-data:/app/data
       - gearbox-uploads:/app/uploads
+    healthcheck:
+      test: ["CMD", "bun", "-e", "fetch('http://localhost:3000/api/health').then(r=>r.ok?process.exit(0):process.exit(1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
     restart: unless-stopped
 
 volumes:

drizzle/0002_broken_roughhouse.sql

@@ -0,0 +1 @@
+ALTER TABLE `thread_candidates` ADD `status` text DEFAULT 'researching' NOT NULL;

drizzle/0003_misty_mongu.sql

@@ -0,0 +1 @@
+ALTER TABLE `setup_items` ADD `classification` text DEFAULT 'base' NOT NULL;

drizzle/meta/0002_snapshot.json

@@ -0,0 +1,475 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "ad8099fa-5c3f-4918-9e21-a259cae77d4f",
+  "prevId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "tables": {
+    "categories": {
+      "name": "categories",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'package'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "categories_name_unique": {
+          "name": "categories_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "items": {
+      "name": "items",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "weight_grams": {
+          "name": "weight_grams",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "price_cents": {
+          "name": "price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "product_url": {
+          "name": "product_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "image_filename": {
+          "name": "image_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "items_category_id_categories_id_fk": {
+          "name": "items_category_id_categories_id_fk",
+          "tableFrom": "items",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "settings": {
+      "name": "settings",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "setup_items": {
+      "name": "setup_items",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "setup_id": {
+          "name": "setup_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "setup_items_setup_id_setups_id_fk": {
+          "name": "setup_items_setup_id_setups_id_fk",
+          "tableFrom": "setup_items",
+          "tableTo": "setups",
+          "columnsFrom": [
+            "setup_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "setup_items_item_id_items_id_fk": {
+          "name": "setup_items_item_id_items_id_fk",
+          "tableFrom": "setup_items",
+          "tableTo": "items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "setups": {
+      "name": "setups",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "thread_candidates": {
+      "name": "thread_candidates",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "weight_grams": {
+          "name": "weight_grams",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "price_cents": {
+          "name": "price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "product_url": {
+          "name": "product_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "image_filename": {
+          "name": "image_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'researching'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "thread_candidates_thread_id_threads_id_fk": {
+          "name": "thread_candidates_thread_id_threads_id_fk",
+          "tableFrom": "thread_candidates",
+          "tableTo": "threads",
+          "columnsFrom": [
+            "thread_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "thread_candidates_category_id_categories_id_fk": {
+          "name": "thread_candidates_category_id_categories_id_fk",
+          "tableFrom": "thread_candidates",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "threads": {
+      "name": "threads",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'active'"
+        },
+        "resolved_candidate_id": {
+          "name": "resolved_candidate_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "threads_category_id_categories_id_fk": {
+          "name": "threads_category_id_categories_id_fk",
+          "tableFrom": "threads",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

drizzle/meta/0003_snapshot.json

@@ -0,0 +1,483 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "628b9ef4-c715-4bbe-a118-042d80fde91e",
+  "prevId": "ad8099fa-5c3f-4918-9e21-a259cae77d4f",
+  "tables": {
+    "categories": {
+      "name": "categories",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'package'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "categories_name_unique": {
+          "name": "categories_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "items": {
+      "name": "items",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "weight_grams": {
+          "name": "weight_grams",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "price_cents": {
+          "name": "price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "product_url": {
+          "name": "product_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "image_filename": {
+          "name": "image_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "items_category_id_categories_id_fk": {
+          "name": "items_category_id_categories_id_fk",
+          "tableFrom": "items",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "settings": {
+      "name": "settings",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "setup_items": {
+      "name": "setup_items",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "setup_id": {
+          "name": "setup_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "classification": {
+          "name": "classification",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'base'"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "setup_items_setup_id_setups_id_fk": {
+          "name": "setup_items_setup_id_setups_id_fk",
+          "tableFrom": "setup_items",
+          "tableTo": "setups",
+          "columnsFrom": [
+            "setup_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "setup_items_item_id_items_id_fk": {
+          "name": "setup_items_item_id_items_id_fk",
+          "tableFrom": "setup_items",
+          "tableTo": "items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "setups": {
+      "name": "setups",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "thread_candidates": {
+      "name": "thread_candidates",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "weight_grams": {
+          "name": "weight_grams",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "price_cents": {
+          "name": "price_cents",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "product_url": {
+          "name": "product_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "image_filename": {
+          "name": "image_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'researching'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "thread_candidates_thread_id_threads_id_fk": {
+          "name": "thread_candidates_thread_id_threads_id_fk",
+          "tableFrom": "thread_candidates",
+          "tableTo": "threads",
+          "columnsFrom": [
+            "thread_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "thread_candidates_category_id_categories_id_fk": {
+          "name": "thread_candidates_category_id_categories_id_fk",
+          "tableFrom": "thread_candidates",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "threads": {
+      "name": "threads",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'active'"
+        },
+        "resolved_candidate_id": {
+          "name": "resolved_candidate_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category_id": {
+          "name": "category_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "threads_category_id_categories_id_fk": {
+          "name": "threads_category_id_categories_id_fk",
+          "tableFrom": "threads",
+          "tableTo": "categories",
+          "columnsFrom": [
+            "category_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

drizzle/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1773593102000,
       "tag": "0001_rename_emoji_to_icon",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1773666521689,
+      "tag": "0002_broken_roughhouse",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1773670263013,
+      "tag": "0003_misty_mongu",
+      "breakpoints": true
     }
   ]
 }

index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>GearBox</title>
   </head>
   <body>

package.json

@@ -40,6 +40,7 @@
 		"lucide-react": "^0.577.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",
+		"recharts": "^3.8.0",
 		"tailwindcss": "^4.2.1",
 		"zod": "^4.3.6",
 		"zustand": "^5.0.11"

public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m7.5 4.27 9 5.15"/><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></svg>

src/client/components/CandidateCard.tsx

@@ -1,6 +1,8 @@
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 import { LucideIcon } from "../lib/iconData";
 import { useUIStore } from "../stores/uiStore";
+import { StatusBadge } from "./StatusBadge";
 
 interface CandidateCardProps {
 	id: number;
@@ -13,6 +15,8 @@ interface CandidateCardProps {
 	productUrl?: string | null;
 	threadId: number;
 	isActive: boolean;
+	status: "researching" | "ordered" | "arrived";
+	onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
 }
 
 export function CandidateCard({
@@ -26,7 +30,10 @@ export function CandidateCard({
 	productUrl,
 	threadId,
 	isActive,
+	status,
+	onStatusChange,
 }: CandidateCardProps) {
+	const unit = useWeightUnit();
 	const openCandidateEditPanel = useUIStore((s) => s.openCandidateEditPanel);
 	const openConfirmDeleteCandidate = useUIStore(
 		(s) => s.openConfirmDeleteCandidate,
@@ -46,7 +53,7 @@ export function CandidateCard({
 							openExternalLink(productUrl);
 						}
 					}}
-					className="absolute top-2 right-2 z-10 w-6 h-6 flex items-center justify-center rounded-full bg-gray-100/80 text-gray-400 hover:bg-blue-100 hover:text-blue-500 opacity-0 group-hover:opacity-100 transition-all cursor-pointer"
+					className="absolute top-2 right-2 z-10 w-6 h-6 flex items-center justify-center rounded-full bg-gray-100/80 text-gray-400 hover:bg-gray-200 hover:text-gray-600 opacity-0 group-hover:opacity-100 transition-all cursor-pointer"
 					title="Open product link"
 				>
 					<svg
@@ -87,12 +94,12 @@ export function CandidateCard({
 				</h3>
 				<div className="flex flex-wrap gap-1.5 mb-3">
 					{weightGrams != null && (
-						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700">
-							{formatWeight(weightGrams)}
+						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-400">
+							{formatWeight(weightGrams, unit)}
 						</span>
 					)}
 					{priceCents != null && (
-						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-700">
+						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-500">
 							{formatPrice(priceCents)}
 						</span>
 					)}
@@ -104,12 +111,13 @@ export function CandidateCard({
 						/>{" "}
 						{categoryName}
 					</span>
+					<StatusBadge status={status} onStatusChange={onStatusChange} />
 				</div>
 				<div className="flex gap-2">
 					<button
 						type="button"
 						onClick={() => openCandidateEditPanel(id)}
-						className="text-xs text-gray-500 hover:text-blue-600 transition-colors"
+						className="text-xs text-gray-500 hover:text-gray-700 transition-colors"
 					>
 						Edit
 					</button>

src/client/components/CandidateForm.tsx

@@ -152,7 +152,7 @@ export function CandidateForm({
 					type="text"
 					value={form.name}
 					onChange={(e) => setForm((f) => ({ ...f, name: e.target.value }))}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. Osprey Talon 22"
 				/>
 				{errors.name && (
@@ -177,7 +177,7 @@ export function CandidateForm({
 					onChange={(e) =>
 						setForm((f) => ({ ...f, weightGrams: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. 680"
 				/>
 				{errors.weightGrams && (
@@ -202,7 +202,7 @@ export function CandidateForm({
 					onChange={(e) =>
 						setForm((f) => ({ ...f, priceDollars: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. 129.99"
 				/>
 				{errors.priceDollars && (
@@ -234,7 +234,7 @@ export function CandidateForm({
 					value={form.notes}
 					onChange={(e) => setForm((f) => ({ ...f, notes: e.target.value }))}
 					rows={3}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent resize-none"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent resize-none"
 					placeholder="Any additional notes..."
 				/>
 			</div>
@@ -254,7 +254,7 @@ export function CandidateForm({
 					onChange={(e) =>
 						setForm((f) => ({ ...f, productUrl: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="https://..."
 				/>
 				{errors.productUrl && (
@@ -267,7 +267,7 @@ export function CandidateForm({
 				<button
 					type="submit"
 					disabled={isPending}
-					className="flex-1 py-2.5 px-4 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
+					className="flex-1 py-2.5 px-4 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
 				>
 					{isPending
 						? "Saving..."

src/client/components/CategoryFilterDropdown.tsx

@@ -0,0 +1,198 @@
+import { useEffect, useRef, useState } from "react";
+import { LucideIcon } from "../lib/iconData";
+
+interface CategoryFilterDropdownProps {
+	value: number | null;
+	onChange: (value: number | null) => void;
+	categories: Array<{ id: number; name: string; icon: string }>;
+}
+
+export function CategoryFilterDropdown({
+	value,
+	onChange,
+	categories,
+}: CategoryFilterDropdownProps) {
+	const [isOpen, setIsOpen] = useState(false);
+	const [searchText, setSearchText] = useState("");
+	const containerRef = useRef<HTMLDivElement>(null);
+	const searchInputRef = useRef<HTMLInputElement>(null);
+
+	const selectedCategory = categories.find((c) => c.id === value);
+
+	const filteredCategories = categories.filter((c) =>
+		c.name.toLowerCase().includes(searchText.toLowerCase()),
+	);
+
+	// Click-outside dismiss
+	useEffect(() => {
+		function handleClickOutside(e: MouseEvent) {
+			if (
+				containerRef.current &&
+				!containerRef.current.contains(e.target as Node)
+			) {
+				setIsOpen(false);
+				setSearchText("");
+			}
+		}
+		document.addEventListener("mousedown", handleClickOutside);
+		return () => document.removeEventListener("mousedown", handleClickOutside);
+	}, []);
+
+	// Escape key dismiss
+	useEffect(() => {
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape" && isOpen) {
+				setIsOpen(false);
+				setSearchText("");
+			}
+		}
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [isOpen]);
+
+	// Auto-focus search input when dropdown opens
+	useEffect(() => {
+		if (isOpen && searchInputRef.current) {
+			searchInputRef.current.focus();
+		}
+	}, [isOpen]);
+
+	function handleSelect(categoryId: number | null) {
+		onChange(categoryId);
+		setIsOpen(false);
+		setSearchText("");
+	}
+
+	return (
+		<div ref={containerRef} className="relative">
+			{/* Trigger button */}
+			<button
+				type="button"
+				onClick={() => setIsOpen((prev) => !prev)}
+				className="flex items-center gap-2 px-3 py-2 border border-gray-200 rounded-lg text-sm bg-white hover:bg-gray-50 transition-colors whitespace-nowrap"
+			>
+				{selectedCategory ? (
+					<>
+						<LucideIcon
+							name={selectedCategory.icon}
+							size={14}
+							className="text-gray-500 shrink-0"
+						/>
+						<span className="text-gray-900">{selectedCategory.name}</span>
+					</>
+				) : (
+					<span className="text-gray-600">All categories</span>
+				)}
+				{selectedCategory ? (
+					<button
+						type="button"
+						onClick={(e) => {
+							e.stopPropagation();
+							onChange(null);
+						}}
+						className="ml-1 text-gray-400 hover:text-gray-600"
+					>
+						<svg
+							className="w-3.5 h-3.5"
+							fill="none"
+							stroke="currentColor"
+							viewBox="0 0 24 24"
+						>
+							<path
+								strokeLinecap="round"
+								strokeLinejoin="round"
+								strokeWidth={2}
+								d="M6 18L18 6M6 6l12 12"
+							/>
+						</svg>
+					</button>
+				) : (
+					<svg
+						className="w-4 h-4 text-gray-400"
+						fill="none"
+						stroke="currentColor"
+						viewBox="0 0 24 24"
+					>
+						<path
+							strokeLinecap="round"
+							strokeLinejoin="round"
+							strokeWidth={2}
+							d="M19 9l-7 7-7-7"
+						/>
+					</svg>
+				)}
+			</button>
+
+			{/* Dropdown panel */}
+			{isOpen && (
+				<div className="absolute right-0 z-20 mt-1 min-w-[220px] bg-white border border-gray-200 rounded-lg shadow-lg">
+					{/* Search input */}
+					<div className="p-2 border-b border-gray-100">
+						<input
+							ref={searchInputRef}
+							type="text"
+							placeholder="Search categories..."
+							value={searchText}
+							onChange={(e) => setSearchText(e.target.value)}
+							className="w-full px-2.5 py-1.5 border border-gray-200 rounded text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
+						/>
+					</div>
+
+					{/* Option list */}
+					<ul className="max-h-60 overflow-y-auto py-1">
+						{/* All categories option */}
+						{(searchText === "" ||
+							"all categories".includes(searchText.toLowerCase())) && (
+							<li>
+								<button
+									type="button"
+									onClick={() => handleSelect(null)}
+									className={`w-full text-left px-3 py-2 text-sm cursor-pointer hover:bg-gray-50 ${
+										value === null
+											? "bg-gray-50 font-medium text-gray-900"
+											: "text-gray-700"
+									}`}
+								>
+									All categories
+								</button>
+							</li>
+						)}
+
+						{/* Category options */}
+						{filteredCategories.map((cat) => (
+							<li key={cat.id}>
+								<button
+									type="button"
+									onClick={() => handleSelect(cat.id)}
+									className={`w-full text-left px-3 py-2 text-sm cursor-pointer flex items-center gap-2 hover:bg-gray-50 ${
+										cat.id === value
+											? "bg-gray-50 font-medium text-gray-900"
+											: "text-gray-700"
+									}`}
+								>
+									<LucideIcon
+										name={cat.icon}
+										size={16}
+										className="text-gray-500 shrink-0"
+									/>
+									{cat.name}
+								</button>
+							</li>
+						))}
+
+						{/* No results */}
+						{filteredCategories.length === 0 &&
+							!(
+								searchText === "" ||
+								"all categories".includes(searchText.toLowerCase())
+							) && (
+								<li className="px-3 py-2 text-sm text-gray-400">
+									No categories found
+								</li>
+							)}
+					</ul>
+				</div>
+			)}
+		</div>
+	);
+}

src/client/components/CategoryHeader.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { useDeleteCategory, useUpdateCategory } from "../hooks/useCategories";
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 import { LucideIcon } from "../lib/iconData";
 import { IconPicker } from "./IconPicker";
@@ -21,6 +22,7 @@ export function CategoryHeader({
 	totalCost,
 	itemCount,
 }: CategoryHeaderProps) {
+	const unit = useWeightUnit();
 	const [isEditing, setIsEditing] = useState(false);
 	const [editName, setEditName] = useState(name);
 	const [editIcon, setEditIcon] = useState(icon);
@@ -64,7 +66,7 @@ export function CategoryHeader({
 				<button
 					type="button"
 					onClick={handleSave}
-					className="text-sm text-blue-600 hover:text-blue-800 font-medium"
+					className="text-sm text-gray-600 hover:text-gray-800 font-medium"
 				>
 					Save
 				</button>
@@ -85,7 +87,7 @@ export function CategoryHeader({
 			<h2 className="text-lg font-semibold text-gray-900">{name}</h2>
 			<span className="text-sm text-gray-400">
 				{itemCount} {itemCount === 1 ? "item" : "items"} ·{" "}
-				{formatWeight(totalWeight)} · {formatPrice(totalCost)}
+				{formatWeight(totalWeight, unit)} · {formatPrice(totalCost)}
 			</span>
 			{!isUncategorized && (
 				<div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">

src/client/components/CategoryPicker.tsx

@@ -169,7 +169,7 @@ export function CategoryPicker({ value, onChange }: CategoryPickerProps) {
 						setInputValue("");
 					}}
 					onKeyDown={handleKeyDown}
-					className={`w-full py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent ${
+					className={`w-full py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent ${
 						!isOpen && selectedCategory ? "pl-8 pr-3" : "px-3"
 					}`}
 				/>
@@ -187,7 +187,7 @@ export function CategoryPicker({ value, onChange }: CategoryPickerProps) {
 							aria-selected={cat.id === value}
 							className={`px-3 py-2 text-sm cursor-pointer flex items-center gap-1.5 ${
 								i === highlightIndex
-									? "bg-blue-50 text-blue-900"
+									? "bg-gray-100 text-gray-900"
 									: "hover:bg-gray-50"
 							} ${cat.id === value ? "font-medium" : ""}`}
 							onClick={() => handleSelect(cat.id)}
@@ -207,7 +207,7 @@ export function CategoryPicker({ value, onChange }: CategoryPickerProps) {
 							aria-selected={false}
 							className={`px-3 py-2 text-sm cursor-pointer border-t border-gray-100 ${
 								highlightIndex === filtered.length
-									? "bg-blue-50 text-blue-900"
+									? "bg-gray-100 text-gray-900"
 									: "hover:bg-gray-50 text-gray-600"
 							}`}
 							onClick={handleStartCreate}
@@ -231,7 +231,7 @@ export function CategoryPicker({ value, onChange }: CategoryPickerProps) {
 									type="button"
 									onClick={handleConfirmCreate}
 									disabled={createCategory.isPending}
-									className="text-xs font-medium text-blue-600 hover:text-blue-800 disabled:opacity-50"
+									className="text-xs font-medium text-gray-600 hover:text-gray-800 disabled:opacity-50"
 								>
 									{createCategory.isPending ? "..." : "Create"}
 								</button>

src/client/components/ClassificationBadge.tsx

@@ -0,0 +1,30 @@
+const CLASSIFICATION_LABELS: Record<string, string> = {
+	base: "Base Weight",
+	worn: "Worn",
+	consumable: "Consumable",
+};
+
+interface ClassificationBadgeProps {
+	classification: string;
+	onCycle: () => void;
+}
+
+export function ClassificationBadge({
+	classification,
+	onCycle,
+}: ClassificationBadgeProps) {
+	const label = CLASSIFICATION_LABELS[classification] ?? "Base Weight";
+
+	return (
+		<button
+			type="button"
+			onClick={(e) => {
+				e.stopPropagation();
+				onCycle();
+			}}
+			className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-gray-100 text-gray-600 hover:bg-gray-200 transition-colors cursor-pointer"
+		>
+			{label}
+		</button>
+	);
+}

src/client/components/CreateThreadModal.tsx

@@ -93,7 +93,7 @@ export function CreateThreadModal() {
 							value={name}
 							onChange={(e) => setName(e.target.value)}
 							placeholder="e.g. Lightweight sleeping bag"
-							className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+							className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 						/>
 					</div>
 
@@ -108,7 +108,7 @@ export function CreateThreadModal() {
 							id="thread-category"
 							value={categoryId ?? ""}
 							onChange={(e) => setCategoryId(Number(e.target.value))}
-							className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent bg-white"
+							className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent bg-white"
 						>
 							{categories?.map((cat) => (
 								<option key={cat.id} value={cat.id}>
@@ -131,7 +131,7 @@ export function CreateThreadModal() {
 						<button
 							type="submit"
 							disabled={createThread.isPending}
-							className="px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 disabled:opacity-50 rounded-lg transition-colors"
+							className="px-4 py-2 text-sm font-medium text-white bg-gray-700 hover:bg-gray-800 disabled:opacity-50 rounded-lg transition-colors"
 						>
 							{createThread.isPending ? "Creating..." : "Create Thread"}
 						</button>

src/client/components/DashboardCard.tsx

@@ -43,7 +43,7 @@ export function DashboardCard({
 				))}
 			</div>
 			{allZero && emptyText && (
-				<p className="mt-4 text-sm text-blue-600 font-medium">{emptyText}</p>
+				<p className="mt-4 text-sm text-gray-500 font-medium">{emptyText}</p>
 			)}
 		</Link>
 	);

src/client/components/ExternalLinkDialog.tsx

@@ -38,7 +38,7 @@ export function ExternalLinkDialog() {
 					You are about to leave GearBox
 				</h3>
 				<p className="text-sm text-gray-600 mb-1">You will be redirected to:</p>
-				<p className="text-sm text-blue-600 break-all mb-6">
+				<p className="text-sm text-gray-600 break-all mb-6">
 					{externalLinkUrl}
 				</p>
 				<div className="flex justify-end gap-3">
@@ -52,7 +52,7 @@ export function ExternalLinkDialog() {
 					<button
 						type="button"
 						onClick={handleContinue}
-						className="px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors"
+						className="px-4 py-2 text-sm font-medium text-white bg-gray-700 hover:bg-gray-800 rounded-lg transition-colors"
 					>
 						Continue
 					</button>

src/client/components/IconPicker.tsx

@@ -150,7 +150,7 @@ export function IconPicker({ value, onChange, size = "md" }: IconPickerProps) {
 									setActiveGroup(0);
 								}}
 								placeholder="Search icons..."
-								className="w-full px-2 py-1.5 text-sm border border-gray-200 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+								className="w-full px-2 py-1.5 text-sm border border-gray-200 rounded-md focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 							/>
 						</div>
 
@@ -164,7 +164,7 @@ export function IconPicker({ value, onChange, size = "md" }: IconPickerProps) {
 										onClick={() => setActiveGroup(i)}
 										className={`flex-1 flex items-center justify-center py-1 rounded transition-colors ${
 											i === activeGroup
-												? "bg-blue-50 text-blue-700"
+												? "bg-gray-200 text-gray-700"
 												: "hover:bg-gray-50 text-gray-500"
 										}`}
 										title={group.name}
@@ -173,7 +173,7 @@ export function IconPicker({ value, onChange, size = "md" }: IconPickerProps) {
 											name={group.icon}
 											size={16}
 											className={
-												i === activeGroup ? "text-blue-700" : "text-gray-400"
+												i === activeGroup ? "text-gray-700" : "text-gray-400"
 											}
 										/>
 									</button>

src/client/components/ItemCard.tsx

@@ -1,3 +1,4 @@
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 import { LucideIcon } from "../lib/iconData";
 import { useUIStore } from "../stores/uiStore";
@@ -25,6 +26,7 @@ export function ItemCard({
 	productUrl,
 	onRemove,
 }: ItemCardProps) {
+	const unit = useWeightUnit();
 	const openEditPanel = useUIStore((s) => s.openEditPanel);
 	const openExternalLink = useUIStore((s) => s.openExternalLink);
 
@@ -48,7 +50,7 @@ export function ItemCard({
 							openExternalLink(productUrl);
 						}
 					}}
-					className={`absolute top-2 ${onRemove ? "right-10" : "right-2"} z-10 w-6 h-6 flex items-center justify-center rounded-full bg-gray-100/80 text-gray-400 hover:bg-blue-100 hover:text-blue-500 opacity-0 group-hover:opacity-100 transition-all cursor-pointer`}
+					className={`absolute top-2 ${onRemove ? "right-10" : "right-2"} z-10 w-6 h-6 flex items-center justify-center rounded-full bg-gray-100/80 text-gray-400 hover:bg-gray-200 hover:text-gray-600 opacity-0 group-hover:opacity-100 transition-all cursor-pointer`}
 					title="Open product link"
 				>
 					<svg
@@ -121,12 +123,12 @@ export function ItemCard({
 				</h3>
 				<div className="flex flex-wrap gap-1.5">
 					{weightGrams != null && (
-						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700">
-							{formatWeight(weightGrams)}
+						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-400">
+							{formatWeight(weightGrams, unit)}
 						</span>
 					)}
 					{priceCents != null && (
-						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-700">
+						<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-500">
 							{formatPrice(priceCents)}
 						</span>
 					)}

src/client/components/ItemForm.tsx

@@ -144,7 +144,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 					type="text"
 					value={form.name}
 					onChange={(e) => setForm((f) => ({ ...f, name: e.target.value }))}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. Osprey Talon 22"
 				/>
 				{errors.name && (
@@ -169,7 +169,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 					onChange={(e) =>
 						setForm((f) => ({ ...f, weightGrams: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. 680"
 				/>
 				{errors.weightGrams && (
@@ -194,7 +194,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 					onChange={(e) =>
 						setForm((f) => ({ ...f, priceDollars: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="e.g. 129.99"
 				/>
 				{errors.priceDollars && (
@@ -226,7 +226,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 					value={form.notes}
 					onChange={(e) => setForm((f) => ({ ...f, notes: e.target.value }))}
 					rows={3}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent resize-none"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent resize-none"
 					placeholder="Any additional notes..."
 				/>
 			</div>
@@ -246,7 +246,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 					onChange={(e) =>
 						setForm((f) => ({ ...f, productUrl: e.target.value }))
 					}
-					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+					className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 					placeholder="https://..."
 				/>
 				{errors.productUrl && (
@@ -259,7 +259,7 @@ export function ItemForm({ mode, itemId }: ItemFormProps) {
 				<button
 					type="submit"
 					disabled={isPending}
-					className="flex-1 py-2.5 px-4 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
+					className="flex-1 py-2.5 px-4 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
 				>
 					{isPending
 						? "Saving..."

src/client/components/ItemPicker.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import { useItems } from "../hooks/useItems";
 import { useSyncSetupItems } from "../hooks/useSetups";
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 import { LucideIcon } from "../lib/iconData";
 import { SlideOutPanel } from "./SlideOutPanel";
@@ -20,6 +21,7 @@ export function ItemPicker({
 }: ItemPickerProps) {
 	const { data: items } = useItems();
 	const syncItems = useSyncSetupItems(setupId);
+	const unit = useWeightUnit();
 	const [selectedIds, setSelectedIds] = useState<Set<number>>(new Set());
 
 	// Reset selected IDs when panel opens
@@ -107,14 +109,14 @@ export function ItemPicker({
 													type="checkbox"
 													checked={selectedIds.has(item.id)}
 													onChange={() => handleToggle(item.id)}
-													className="rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+													className="rounded border-gray-300 text-gray-600 focus:ring-gray-400"
 												/>
 												<span className="flex-1 text-sm text-gray-900 truncate">
 													{item.name}
 												</span>
 												<span className="text-xs text-gray-400 shrink-0">
 													{item.weightGrams != null &&
-														formatWeight(item.weightGrams)}
+														formatWeight(item.weightGrams, unit)}
 													{item.weightGrams != null &&
 														item.priceCents != null &&
 														" · "}
@@ -143,7 +145,7 @@ export function ItemPicker({
 						type="button"
 						onClick={handleDone}
 						disabled={syncItems.isPending}
-						className="flex-1 px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 disabled:opacity-50 rounded-lg transition-colors"
+						className="flex-1 px-4 py-2 text-sm font-medium text-white bg-gray-700 hover:bg-gray-800 disabled:opacity-50 rounded-lg transition-colors"
 					>
 						{syncItems.isPending ? "Saving..." : "Done"}
 					</button>

src/client/components/OnboardingWizard.tsx

@@ -102,7 +102,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 						<div
 							key={s}
 							className={`h-1.5 rounded-full transition-all ${
-								s <= Math.min(step, 3) ? "bg-blue-600 w-8" : "bg-gray-200 w-6"
+								s <= Math.min(step, 3) ? "bg-gray-700 w-8" : "bg-gray-200 w-6"
 							}`}
 						/>
 					))}
@@ -121,7 +121,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 						<button
 							type="button"
 							onClick={() => setStep(2)}
-							className="w-full py-3 px-4 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors"
+							className="w-full py-3 px-4 bg-gray-700 hover:bg-gray-800 text-white font-medium rounded-lg transition-colors"
 						>
 							Get Started
 						</button>
@@ -159,7 +159,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 									type="text"
 									value={categoryName}
 									onChange={(e) => setCategoryName(e.target.value)}
-									className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+									className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 									placeholder="e.g. Shelter"
 								/>
 							</div>
@@ -184,7 +184,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 							type="button"
 							onClick={handleCreateCategory}
 							disabled={createCategory.isPending}
-							className="mt-6 w-full py-3 px-4 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
+							className="mt-6 w-full py-3 px-4 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
 						>
 							{createCategory.isPending ? "Creating..." : "Create Category"}
 						</button>
@@ -221,7 +221,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 									type="text"
 									value={itemName}
 									onChange={(e) => setItemName(e.target.value)}
-									className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+									className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 									placeholder="e.g. Big Agnes Copper Spur"
 								/>
 							</div>
@@ -241,7 +241,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 										step="any"
 										value={itemWeight}
 										onChange={(e) => setItemWeight(e.target.value)}
-										className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+										className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 										placeholder="e.g. 1200"
 									/>
 								</div>
@@ -259,7 +259,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 										step="0.01"
 										value={itemPrice}
 										onChange={(e) => setItemPrice(e.target.value)}
-										className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+										className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
 										placeholder="e.g. 349.99"
 									/>
 								</div>
@@ -272,7 +272,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 							type="button"
 							onClick={handleCreateItem}
 							disabled={createItem.isPending}
-							className="mt-6 w-full py-3 px-4 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
+							className="mt-6 w-full py-3 px-4 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
 						>
 							{createItem.isPending ? "Adding..." : "Add Item"}
 						</button>
@@ -307,7 +307,7 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
 							type="button"
 							onClick={handleDone}
 							disabled={updateSetting.isPending}
-							className="w-full py-3 px-4 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
+							className="w-full py-3 px-4 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white font-medium rounded-lg transition-colors"
 						>
 							{updateSetting.isPending ? "Finishing..." : "Done"}
 						</button>

src/client/components/SetupCard.tsx

@@ -1,4 +1,5 @@
 import { Link } from "@tanstack/react-router";
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 
 interface SetupCardProps {
@@ -16,6 +17,7 @@ export function SetupCard({
 	totalWeight,
 	totalCost,
 }: SetupCardProps) {
+	const unit = useWeightUnit();
 	return (
 		<Link
 			to="/setups/$setupId"
@@ -24,15 +26,15 @@ export function SetupCard({
 		>
 			<div className="flex items-start justify-between mb-3">
 				<h3 className="text-sm font-semibold text-gray-900 truncate">{name}</h3>
-				<span className="ml-2 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700 shrink-0">
+				<span className="ml-2 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-400 shrink-0">
 					{itemCount} {itemCount === 1 ? "item" : "items"}
 				</span>
 			</div>
 			<div className="flex flex-wrap gap-1.5">
-				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700">
-					{formatWeight(totalWeight)}
+				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-400">
+					{formatWeight(totalWeight, unit)}
 				</span>
-				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-700">
+				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-500">
 					{formatPrice(totalCost)}
 				</span>
 			</div>

src/client/components/StatusBadge.tsx

@@ -0,0 +1,103 @@
+import { useEffect, useRef, useState } from "react";
+import { LucideIcon } from "../lib/iconData";
+
+const STATUS_CONFIG = {
+	researching: { icon: "search", label: "Researching" },
+	ordered: { icon: "truck", label: "Ordered" },
+	arrived: { icon: "check", label: "Arrived" },
+} as const;
+
+type CandidateStatus = keyof typeof STATUS_CONFIG;
+
+interface StatusBadgeProps {
+	status: CandidateStatus;
+	onStatusChange: (status: CandidateStatus) => void;
+}
+
+export function StatusBadge({ status, onStatusChange }: StatusBadgeProps) {
+	const [isOpen, setIsOpen] = useState(false);
+	const containerRef = useRef<HTMLDivElement>(null);
+
+	const config = STATUS_CONFIG[status];
+
+	useEffect(() => {
+		if (!isOpen) return;
+
+		function handleClickOutside(e: MouseEvent) {
+			if (
+				containerRef.current &&
+				!containerRef.current.contains(e.target as Node)
+			) {
+				setIsOpen(false);
+			}
+		}
+
+		function handleEscape(e: KeyboardEvent) {
+			if (e.key === "Escape") {
+				setIsOpen(false);
+			}
+		}
+
+		document.addEventListener("mousedown", handleClickOutside);
+		document.addEventListener("keydown", handleEscape);
+		return () => {
+			document.removeEventListener("mousedown", handleClickOutside);
+			document.removeEventListener("keydown", handleEscape);
+		};
+	}, [isOpen]);
+
+	return (
+		<div ref={containerRef} className="relative">
+			<button
+				type="button"
+				onClick={(e) => {
+					e.stopPropagation();
+					setIsOpen((prev) => !prev);
+				}}
+				className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-medium bg-gray-100 text-gray-600 hover:bg-gray-200 transition-colors cursor-pointer"
+			>
+				<LucideIcon name={config.icon} size={14} className="text-gray-500" />
+				{config.label}
+			</button>
+
+			{isOpen && (
+				<div className="absolute right-0 top-full mt-1 z-20 bg-white border border-gray-200 rounded-lg shadow-lg py-1 min-w-[150px]">
+					{(Object.keys(STATUS_CONFIG) as CandidateStatus[]).map((key) => {
+						const option = STATUS_CONFIG[key];
+						const isActive = key === status;
+						return (
+							<button
+								key={key}
+								type="button"
+								onClick={(e) => {
+									e.stopPropagation();
+									onStatusChange(key);
+									setIsOpen(false);
+								}}
+								className={`w-full flex items-center gap-2 px-3 py-1.5 text-sm text-left hover:bg-gray-50 transition-colors ${
+									isActive ? "bg-gray-50 font-medium" : ""
+								}`}
+							>
+								<LucideIcon
+									name={option.icon}
+									size={14}
+									className={isActive ? "text-gray-700" : "text-gray-400"}
+								/>
+								<span className={isActive ? "text-gray-900" : "text-gray-600"}>
+									{option.label}
+								</span>
+								{isActive && (
+									<LucideIcon
+										name="check"
+										size={14}
+										className="ml-auto text-gray-500"
+									/>
+								)}
+							</button>
+						);
+					})}
+				</div>
+			)}
+		</div>
+	);
+}

src/client/components/ThreadCard.tsx

@@ -66,7 +66,7 @@ export function ThreadCard({
 				)}
 			</div>
 			<div className="flex flex-wrap gap-1.5">
-				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-blue-50 text-blue-700">
+				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-gray-50 text-gray-600">
 					<LucideIcon
 						name={categoryIcon}
 						size={16}
@@ -74,14 +74,14 @@ export function ThreadCard({
 					/>{" "}
 					{categoryName}
 				</span>
-				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-purple-50 text-purple-700">
+				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-purple-50 text-purple-500">
 					{candidateCount} {candidateCount === 1 ? "candidate" : "candidates"}
 				</span>
 				<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-gray-50 text-gray-600">
 					{formatDate(createdAt)}
 				</span>
 				{priceRange && (
-					<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-700">
+					<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-50 text-green-500">
 						{priceRange}
 					</span>
 				)}

src/client/components/ThreadTabs.tsx

@@ -1,14 +1,17 @@
-interface ThreadTabsProps {
-	active: "gear" | "planning";
-	onChange: (tab: "gear" | "planning") => void;
+type TabKey = "gear" | "planning" | "setups";
+
+interface CollectionTabsProps {
+	active: TabKey;
+	onChange: (tab: TabKey) => void;
 }
 
 const tabs = [
 	{ key: "gear" as const, label: "My Gear" },
 	{ key: "planning" as const, label: "Planning" },
+	{ key: "setups" as const, label: "Setups" },
 ];
 
-export function ThreadTabs({ active, onChange }: ThreadTabsProps) {
+export function CollectionTabs({ active, onChange }: CollectionTabsProps) {
 	return (
 		<div className="flex border-b border-gray-200">
 			{tabs.map((tab) => (
@@ -18,13 +21,13 @@ export function ThreadTabs({ active, onChange }: ThreadTabsProps) {
 					onClick={() => onChange(tab.key)}
 					className={`px-4 py-2.5 text-sm font-medium transition-colors relative ${
 						active === tab.key
-							? "text-blue-600"
+							? "text-gray-700"
 							: "text-gray-500 hover:text-gray-700"
 					}`}
 				>
 					{tab.label}
 					{active === tab.key && (
-						<span className="absolute bottom-0 left-0 right-0 h-0.5 bg-blue-600 rounded-t" />
+						<span className="absolute bottom-0 left-0 right-0 h-0.5 bg-gray-700 rounded-t" />
 					)}
 				</button>
 			))}

src/client/components/TotalsBar.tsx

@@ -1,6 +1,11 @@
 import { Link } from "@tanstack/react-router";
+import { useUpdateSetting } from "../hooks/useSettings";
 import { useTotals } from "../hooks/useTotals";
-import { formatPrice, formatWeight } from "../lib/formatters";
+import { useWeightUnit } from "../hooks/useWeightUnit";
+import { formatPrice, formatWeight, type WeightUnit } from "../lib/formatters";
+import { LucideIcon } from "../lib/iconData";
+
+const UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
 
 interface TotalsBarProps {
 	title?: string;
@@ -14,6 +19,8 @@ export function TotalsBar({
 	linkTo,
 }: TotalsBarProps) {
 	const { data } = useTotals();
+	const unit = useWeightUnit();
+	const updateSetting = useUpdateSetting();
 
 	// When no stats provided, use global totals (backward compatible)
 	const displayStats =
@@ -21,24 +28,34 @@ export function TotalsBar({
 		(data?.global
 			? [
 					{ label: "items", value: String(data.global.itemCount) },
-					{ label: "total", value: formatWeight(data.global.totalWeight) },
+					{
+						label: "total",
+						value: formatWeight(data.global.totalWeight, unit),
+					},
 					{ label: "spent", value: formatPrice(data.global.totalCost) },
 				]
 			: [
 					{ label: "items", value: "0" },
-					{ label: "total", value: formatWeight(null) },
+					{ label: "total", value: formatWeight(null, unit) },
 					{ label: "spent", value: formatPrice(null) },
 				]);
 
+	const titleContent = (
+		<span className="flex items-center gap-2">
+			<LucideIcon name="package" size={20} className="text-gray-500" />
+			{title}
+		</span>
+	);
+
 	const titleElement = linkTo ? (
 		<Link
 			to={linkTo}
-			className="text-lg font-semibold text-gray-900 hover:text-blue-600 transition-colors"
+			className="text-lg font-semibold text-gray-900 hover:text-gray-600 transition-colors"
 		>
-			{title}
+			{titleContent}
 		</Link>
 	) : (
-		<h1 className="text-lg font-semibold text-gray-900">{title}</h1>
+		<h1 className="text-lg font-semibold text-gray-900">{titleContent}</h1>
 	);
 
 	// If stats prop is explicitly an empty array, show title only (dashboard mode)
@@ -49,6 +66,28 @@ export function TotalsBar({
 			<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
 				<div className="flex items-center justify-between h-14">
 					{titleElement}
+					<div className="flex items-center gap-4">
+						<div className="flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5">
+							{UNITS.map((u) => (
+								<button
+									key={u}
+									type="button"
+									onClick={() =>
+										updateSetting.mutate({
+											key: "weightUnit",
+											value: u,
+										})
+									}
+									className={`px-2 py-0.5 text-xs rounded-full transition-colors ${
+										unit === u
+											? "bg-white text-gray-700 shadow-sm font-medium"
+											: "text-gray-400 hover:text-gray-600"
+									}`}
+								>
+									{u}
+								</button>
+							))}
+						</div>
 						{showStats && (
 							<div className="flex items-center gap-6 text-sm text-gray-500">
 								{displayStats.map((stat) => (
@@ -64,5 +103,6 @@ export function TotalsBar({
 					</div>
 				</div>
 			</div>
+		</div>
 	);
 }

src/client/components/WeightSummaryCard.tsx

@@ -0,0 +1,265 @@
+import { useState } from "react";
+import {
+	Cell,
+	Label,
+	Pie,
+	PieChart,
+	ResponsiveContainer,
+	Tooltip,
+} from "recharts";
+import type { SetupItemWithCategory } from "../hooks/useSetups";
+import { useWeightUnit } from "../hooks/useWeightUnit";
+import { formatWeight, type WeightUnit } from "../lib/formatters";
+
+const CATEGORY_COLORS = [
+	"#6366f1",
+	"#f59e0b",
+	"#10b981",
+	"#ef4444",
+	"#8b5cf6",
+	"#06b6d4",
+	"#f97316",
+	"#ec4899",
+	"#14b8a6",
+	"#84cc16",
+];
+
+const CLASSIFICATION_COLORS: Record<string, string> = {
+	base: "#6366f1",
+	worn: "#f59e0b",
+	consumable: "#10b981",
+};
+
+const CLASSIFICATION_LABELS: Record<string, string> = {
+	base: "Base Weight",
+	worn: "Worn",
+	consumable: "Consumable",
+};
+
+type ViewMode = "category" | "classification";
+const VIEW_MODES: ViewMode[] = ["category", "classification"];
+
+interface ChartDatum {
+	name: string;
+	weight: number;
+	percent: number;
+	classificationKey?: string;
+}
+
+interface WeightSummaryCardProps {
+	items: SetupItemWithCategory[];
+}
+
+function buildCategoryChartData(items: SetupItemWithCategory[]): ChartDatum[] {
+	const groups = new Map<string, number>();
+	for (const item of items) {
+		const current = groups.get(item.categoryName) ?? 0;
+		groups.set(item.categoryName, current + (item.weightGrams ?? 0));
+	}
+	const total = items.reduce((sum, i) => sum + (i.weightGrams ?? 0), 0);
+	return Array.from(groups.entries())
+		.filter(([, weight]) => weight > 0)
+		.map(([name, weight]) => ({
+			name,
+			weight,
+			percent: total > 0 ? weight / total : 0,
+		}));
+}
+
+function buildClassificationChartData(
+	items: SetupItemWithCategory[],
+): ChartDatum[] {
+	const groups: Record<string, number> = {
+		base: 0,
+		worn: 0,
+		consumable: 0,
+	};
+	for (const item of items) {
+		groups[item.classification] += item.weightGrams ?? 0;
+	}
+	const total = Object.values(groups).reduce((a, b) => a + b, 0);
+	return Object.entries(groups)
+		.filter(([, weight]) => weight > 0)
+		.map(([key, weight]) => ({
+			name: CLASSIFICATION_LABELS[key] ?? key,
+			weight,
+			percent: total > 0 ? weight / total : 0,
+			classificationKey: key,
+		}));
+}
+
+function CustomTooltip({
+	active,
+	payload,
+	unit,
+}: {
+	active?: boolean;
+	payload?: Array<{ payload: ChartDatum }>;
+	unit: WeightUnit;
+}) {
+	if (!active || !payload?.length) return null;
+	const { name, weight, percent } = payload[0].payload;
+	return (
+		<div className="bg-white border border-gray-200 rounded-lg shadow-lg px-3 py-2 text-sm">
+			<p className="font-medium text-gray-900">{name}</p>
+			<p className="text-gray-600">
+				{formatWeight(weight, unit)} ({(percent * 100).toFixed(1)}%)
+			</p>
+		</div>
+	);
+}
+
+function SubtotalColumn({
+	label,
+	weight,
+	unit,
+	color,
+}: {
+	label: string;
+	weight: number;
+	unit: WeightUnit;
+	color?: string;
+}) {
+	return (
+		<div className="flex flex-col items-center gap-1">
+			{color && (
+				<span
+					className="w-2.5 h-2.5 rounded-full"
+					style={{ backgroundColor: color }}
+				/>
+			)}
+			<span className="text-xs text-gray-500">{label}</span>
+			<span className="text-sm font-semibold text-gray-900">
+				{formatWeight(weight, unit)}
+			</span>
+		</div>
+	);
+}
+
+export function WeightSummaryCard({ items }: WeightSummaryCardProps) {
+	const unit = useWeightUnit();
+	const [viewMode, setViewMode] = useState<ViewMode>("category");
+
+	const baseWeight = items.reduce(
+		(sum, i) =>
+			i.classification === "base" ? sum + (i.weightGrams ?? 0) : sum,
+		0,
+	);
+	const wornWeight = items.reduce(
+		(sum, i) =>
+			i.classification === "worn" ? sum + (i.weightGrams ?? 0) : sum,
+		0,
+	);
+	const consumableWeight = items.reduce(
+		(sum, i) =>
+			i.classification === "consumable" ? sum + (i.weightGrams ?? 0) : sum,
+		0,
+	);
+	const totalWeight = baseWeight + wornWeight + consumableWeight;
+
+	const chartData =
+		viewMode === "category"
+			? buildCategoryChartData(items)
+			: buildClassificationChartData(items);
+
+	const colors =
+		viewMode === "category"
+			? CATEGORY_COLORS
+			: chartData.map(
+					(d) => CLASSIFICATION_COLORS[d.classificationKey ?? ""] ?? "#6366f1",
+				);
+
+	if (totalWeight === 0) {
+		return (
+			<div className="bg-white rounded-xl border border-gray-100 p-5 mb-6">
+				<h3 className="text-sm font-medium text-gray-700 mb-2">
+					Weight Summary
+				</h3>
+				<p className="text-sm text-gray-400">No weight data to display</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="bg-white rounded-xl border border-gray-100 p-5 mb-6">
+			{/* Header with pill toggle */}
+			<div className="flex items-center justify-between mb-4">
+				<h3 className="text-sm font-medium text-gray-700">Weight Summary</h3>
+				<div className="flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5">
+					{VIEW_MODES.map((mode) => (
+						<button
+							key={mode}
+							type="button"
+							onClick={() => setViewMode(mode)}
+							className={`px-2.5 py-0.5 text-xs rounded-full transition-colors ${
+								viewMode === mode
+									? "bg-white text-gray-700 shadow-sm font-medium"
+									: "text-gray-400 hover:text-gray-600"
+							}`}
+						>
+							{mode === "category" ? "Category" : "Classification"}
+						</button>
+					))}
+				</div>
+			</div>
+
+			{/* Main content: chart + subtotals side by side */}
+			<div className="flex items-center gap-8">
+				{/* Donut chart */}
+				<div className="flex-shrink-0" style={{ width: 180, height: 180 }}>
+					<ResponsiveContainer width="100%" height={180}>
+						<PieChart>
+							<Pie
+								data={chartData}
+								dataKey="weight"
+								nameKey="name"
+								cx="50%"
+								cy="50%"
+								innerRadius={55}
+								outerRadius={80}
+								paddingAngle={2}
+							>
+								{chartData.map((entry, index) => (
+									<Cell key={entry.name} fill={colors[index % colors.length]} />
+								))}
+								<Label
+									value={formatWeight(totalWeight, unit)}
+									position="center"
+									style={{
+										fontSize: "14px",
+										fontWeight: 600,
+										fill: "#374151",
+									}}
+								/>
+							</Pie>
+							<Tooltip content={<CustomTooltip unit={unit} />} />
+						</PieChart>
+					</ResponsiveContainer>
+				</div>
+
+				{/* Weight subtotals columns */}
+				<div className="flex-1 grid grid-cols-4 gap-4">
+					<SubtotalColumn
+						label="Base"
+						weight={baseWeight}
+						unit={unit}
+						color="#6366f1"
+					/>
+					<SubtotalColumn
+						label="Worn"
+						weight={wornWeight}
+						unit={unit}
+						color="#f59e0b"
+					/>
+					<SubtotalColumn
+						label="Consumable"
+						weight={consumableWeight}
+						unit={unit}
+						color="#10b981"
+					/>
+					<SubtotalColumn label="Total" weight={totalWeight} unit={unit} />
+				</div>
+			</div>
+		</div>
+	);
+}

src/client/hooks/useCandidates.ts

@@ -12,6 +12,7 @@ interface CandidateResponse {
 	notes: string | null;
 	productUrl: string | null;
 	imageFilename: string | null;
+	status: "researching" | "ordered" | "arrived";
 	createdAt: string;
 	updatedAt: string;
 }

src/client/hooks/useSetups.ts

@@ -1,5 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { apiDelete, apiGet, apiPost, apiPut } from "../lib/api";
+import { apiDelete, apiGet, apiPatch, apiPost, apiPut } from "../lib/api";
 
 interface SetupListItem {
 	id: number;
@@ -24,6 +24,7 @@ interface SetupItemWithCategory {
 	updatedAt: string;
 	categoryName: string;
 	categoryIcon: string;
+	classification: string;
 }
 
 interface SetupWithItems {
@@ -105,3 +106,20 @@ export function useRemoveSetupItem(setupId: number) {
 		},
 	});
 }
+
+export function useUpdateItemClassification(setupId: number) {
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: ({
+			itemId,
+			classification,
+		}: { itemId: number; classification: string }) =>
+			apiPatch<{ success: boolean }>(
+				`/api/setups/${setupId}/items/${itemId}/classification`,
+				{ classification },
+			),
+		onSuccess: () => {
+			queryClient.invalidateQueries({ queryKey: ["setups", setupId] });
+		},
+	});
+}

src/client/hooks/useThreads.ts

@@ -26,6 +26,7 @@ interface CandidateWithCategory {
 	notes: string | null;
 	productUrl: string | null;
 	imageFilename: string | null;
+	status: "researching" | "ordered" | "arrived";
 	createdAt: string;
 	updatedAt: string;
 	categoryName: string;

src/client/hooks/useWeightUnit.ts

@@ -0,0 +1,12 @@
+import type { WeightUnit } from "../lib/formatters";
+import { useSetting } from "./useSettings";
+
+const VALID_UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
+
+export function useWeightUnit(): WeightUnit {
+	const { data } = useSetting("weightUnit");
+	if (data && VALID_UNITS.includes(data as WeightUnit)) {
+		return data as WeightUnit;
+	}
+	return "g";
+}

src/client/lib/api.ts

@@ -45,6 +45,15 @@ export async function apiPut<T>(url: string, body: unknown): Promise<T> {
 	return handleResponse<T>(res);
 }
 
+export async function apiPatch<T>(url: string, body: unknown): Promise<T> {
+	const res = await fetch(url, {
+		method: "PATCH",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+	return handleResponse<T>(res);
+}
+
 export async function apiDelete<T>(url: string): Promise<T> {
 	const res = await fetch(url, { method: "DELETE" });
 	return handleResponse<T>(res);

src/client/lib/formatters.ts

@@ -1,6 +1,24 @@
-export function formatWeight(grams: number | null | undefined): string {
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+
+const GRAMS_PER_OZ = 28.3495;
+const GRAMS_PER_LB = 453.592;
+const GRAMS_PER_KG = 1000;
+
+export function formatWeight(
+	grams: number | null | undefined,
+	unit: WeightUnit = "g",
+): string {
 	if (grams == null) return "--";
+	switch (unit) {
+		case "g":
 			return `${Math.round(grams)}g`;
+		case "oz":
+			return `${(grams / GRAMS_PER_OZ).toFixed(1)} oz`;
+		case "lb":
+			return `${(grams / GRAMS_PER_LB).toFixed(2)} lb`;
+		case "kg":
+			return `${(grams / GRAMS_PER_KG).toFixed(2)} kg`;
+	}
 }
 
 export function formatPrice(cents: number | null | undefined): string {

src/client/routeTree.gen.ts

@@ -10,7 +10,6 @@
 
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as IndexRouteImport } from './routes/index'
-import { Route as SetupsIndexRouteImport } from './routes/setups/index'
 import { Route as CollectionIndexRouteImport } from './routes/collection/index'
 import { Route as ThreadsThreadIdRouteImport } from './routes/threads/$threadId'
 import { Route as SetupsSetupIdRouteImport } from './routes/setups/$setupId'
@@ -20,11 +19,6 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
-const SetupsIndexRoute = SetupsIndexRouteImport.update({
-  id: '/setups/',
-  path: '/setups/',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const CollectionIndexRoute = CollectionIndexRouteImport.update({
   id: '/collection/',
   path: '/collection/',
@@ -46,14 +40,12 @@ export interface FileRoutesByFullPath {
   '/setups/$setupId': typeof SetupsSetupIdRoute
   '/threads/$threadId': typeof ThreadsThreadIdRoute
   '/collection/': typeof CollectionIndexRoute
-  '/setups/': typeof SetupsIndexRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/setups/$setupId': typeof SetupsSetupIdRoute
   '/threads/$threadId': typeof ThreadsThreadIdRoute
   '/collection': typeof CollectionIndexRoute
-  '/setups': typeof SetupsIndexRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
@@ -61,30 +53,18 @@ export interface FileRoutesById {
   '/setups/$setupId': typeof SetupsSetupIdRoute
   '/threads/$threadId': typeof ThreadsThreadIdRoute
   '/collection/': typeof CollectionIndexRoute
-  '/setups/': typeof SetupsIndexRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths:
-    | '/'
-    | '/setups/$setupId'
-    | '/threads/$threadId'
-    | '/collection/'
-    | '/setups/'
+  fullPaths: '/' | '/setups/$setupId' | '/threads/$threadId' | '/collection/'
   fileRoutesByTo: FileRoutesByTo
-  to:
-    | '/'
-    | '/setups/$setupId'
-    | '/threads/$threadId'
-    | '/collection'
-    | '/setups'
+  to: '/' | '/setups/$setupId' | '/threads/$threadId' | '/collection'
   id:
     | '__root__'
     | '/'
     | '/setups/$setupId'
     | '/threads/$threadId'
     | '/collection/'
-    | '/setups/'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
@@ -92,7 +72,6 @@ export interface RootRouteChildren {
   SetupsSetupIdRoute: typeof SetupsSetupIdRoute
   ThreadsThreadIdRoute: typeof ThreadsThreadIdRoute
   CollectionIndexRoute: typeof CollectionIndexRoute
-  SetupsIndexRoute: typeof SetupsIndexRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -104,13 +83,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/setups/': {
-      id: '/setups/'
-      path: '/setups'
-      fullPath: '/setups/'
-      preLoaderRoute: typeof SetupsIndexRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/collection/': {
       id: '/collection/'
       path: '/collection'
@@ -140,7 +112,6 @@ const rootRouteChildren: RootRouteChildren = {
   SetupsSetupIdRoute: SetupsSetupIdRoute,
   ThreadsThreadIdRoute: ThreadsThreadIdRoute,
   CollectionIndexRoute: CollectionIndexRoute,
-  SetupsIndexRoute: SetupsIndexRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)

src/client/routes/__root.tsx

@@ -95,13 +95,14 @@ function RootLayout() {
 	const showFab =
 		isCollection &&
 		(!collectionSearch ||
-			(collectionSearch as Record<string, string>).tab !== "planning");
+			!(collectionSearch as Record<string, string>).tab ||
+			(collectionSearch as Record<string, string>).tab === "gear");
 
 	// Show a minimal loading state while checking onboarding status
 	if (onboardingLoading) {
 		return (
 			<div className="min-h-screen bg-gray-50 flex items-center justify-center">
-				<div className="w-6 h-6 border-2 border-blue-600 border-t-transparent rounded-full animate-spin" />
+				<div className="w-6 h-6 border-2 border-gray-600 border-t-transparent rounded-full animate-spin" />
 			</div>
 		);
 	}
@@ -178,7 +179,7 @@ function RootLayout() {
 				<button
 					type="button"
 					onClick={openAddPanel}
-					className="fixed bottom-6 right-6 z-20 w-14 h-14 bg-blue-600 hover:bg-blue-700 text-white rounded-full shadow-lg hover:shadow-xl transition-all flex items-center justify-center"
+					className="fixed bottom-6 right-6 z-20 w-14 h-14 bg-gray-700 hover:bg-gray-800 text-white rounded-full shadow-lg hover:shadow-xl transition-all flex items-center justify-center"
 					title="Add new item"
 				>
 					<svg

src/client/routes/collection/index.tsx

@@ -1,20 +1,23 @@
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { z } from "zod";
+import { CategoryFilterDropdown } from "../../components/CategoryFilterDropdown";
 import { CategoryHeader } from "../../components/CategoryHeader";
 import { CreateThreadModal } from "../../components/CreateThreadModal";
 import { ItemCard } from "../../components/ItemCard";
+import { SetupCard } from "../../components/SetupCard";
 import { ThreadCard } from "../../components/ThreadCard";
-import { ThreadTabs } from "../../components/ThreadTabs";
+import { CollectionTabs } from "../../components/ThreadTabs";
 import { useCategories } from "../../hooks/useCategories";
 import { useItems } from "../../hooks/useItems";
+import { useCreateSetup, useSetups } from "../../hooks/useSetups";
 import { useThreads } from "../../hooks/useThreads";
 import { useTotals } from "../../hooks/useTotals";
 import { LucideIcon } from "../../lib/iconData";
 import { useUIStore } from "../../stores/uiStore";
 
 const searchSchema = z.object({
-	tab: z.enum(["gear", "planning"]).catch("gear"),
+	tab: z.enum(["gear", "planning", "setups"]).catch("gear"),
 });
 
 export const Route = createFileRoute("/collection/")({
@@ -26,15 +29,21 @@ function CollectionPage() {
 	const { tab } = Route.useSearch();
 	const navigate = useNavigate();
 
-	function handleTabChange(newTab: "gear" | "planning") {
+	function handleTabChange(newTab: "gear" | "planning" | "setups") {
 		navigate({ to: "/collection", search: { tab: newTab } });
 	}
 
 	return (
 		<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6">
-			<ThreadTabs active={tab} onChange={handleTabChange} />
+			<CollectionTabs active={tab} onChange={handleTabChange} />
 			<div className="mt-6">
-				{tab === "gear" ? <CollectionView /> : <PlanningView />}
+				{tab === "gear" ? (
+					<CollectionView />
+				) : tab === "planning" ? (
+					<PlanningView />
+				) : (
+					<SetupsView />
+				)}
 			</div>
 		</div>
 	);
@@ -43,8 +52,26 @@ function CollectionPage() {
 function CollectionView() {
 	const { data: items, isLoading: itemsLoading } = useItems();
 	const { data: totals } = useTotals();
+	const { data: categories } = useCategories();
 	const openAddPanel = useUIStore((s) => s.openAddPanel);
 
+	const [searchText, setSearchText] = useState("");
+	const [categoryFilter, setCategoryFilter] = useState<number | null>(null);
+
+	const filteredItems = useMemo(() => {
+		if (!items) return [];
+		return items.filter((item) => {
+			const matchesSearch =
+				searchText === "" ||
+				item.name.toLowerCase().includes(searchText.toLowerCase());
+			const matchesCategory =
+				categoryFilter === null || item.categoryId === categoryFilter;
+			return matchesSearch && matchesCategory;
+		});
+	}, [items, searchText, categoryFilter]);
+
+	const hasActiveFilters = searchText !== "" || categoryFilter !== null;
+
 	if (itemsLoading) {
 		return (
 			<div className="animate-pulse space-y-6">
@@ -79,7 +106,7 @@ function CollectionView() {
 					<button
 						type="button"
 						onClick={openAddPanel}
-						className="inline-flex items-center gap-2 px-5 py-2.5 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+						className="inline-flex items-center gap-2 px-5 py-2.5 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 					>
 						<svg
 							aria-hidden="true"
@@ -102,25 +129,6 @@ function CollectionView() {
 		);
 	}
 
-	// Group items by categoryId
-	const groupedItems = new Map<
-		number,
-		{ items: typeof items; categoryName: string; categoryIcon: string }
-	>();
-
-	for (const item of items) {
-		const group = groupedItems.get(item.categoryId);
-		if (group) {
-			group.items.push(item);
-		} else {
-			groupedItems.set(item.categoryId, {
-				items: [item],
-				categoryName: item.categoryName,
-				categoryIcon: item.categoryIcon,
-			});
-		}
-	}
-
 	// Build category totals lookup
 	const categoryTotalsMap = new Map<
 		number,
@@ -136,9 +144,104 @@ function CollectionView() {
 		}
 	}
 
+	// Group filtered items by categoryId (used when no active filters)
+	const groupedItems = new Map<
+		number,
+		{
+			items: typeof filteredItems;
+			categoryName: string;
+			categoryIcon: string;
+		}
+	>();
+
+	for (const item of filteredItems) {
+		const group = groupedItems.get(item.categoryId);
+		if (group) {
+			group.items.push(item);
+		} else {
+			groupedItems.set(item.categoryId, {
+				items: [item],
+				categoryName: item.categoryName,
+				categoryIcon: item.categoryIcon,
+			});
+		}
+	}
+
 	return (
 		<>
-			{Array.from(groupedItems.entries()).map(
+			{/* Search/filter toolbar */}
+			<div className="sticky top-0 z-10 bg-white/95 backdrop-blur-sm border-b border-gray-100 -mx-4 px-4 py-3 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 mb-6">
+				<div className="flex gap-3 items-center">
+					<div className="relative flex-1">
+						<input
+							type="text"
+							placeholder="Search items..."
+							value={searchText}
+							onChange={(e) => setSearchText(e.target.value)}
+							className="w-full px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
+						/>
+						{searchText && (
+							<button
+								type="button"
+								onClick={() => setSearchText("")}
+								className="absolute right-2 top-1/2 -translate-y-1/2 text-gray-400 hover:text-gray-600"
+							>
+								<svg
+									className="w-4 h-4"
+									fill="none"
+									stroke="currentColor"
+									viewBox="0 0 24 24"
+								>
+									<path
+										strokeLinecap="round"
+										strokeLinejoin="round"
+										strokeWidth={2}
+										d="M6 18L18 6M6 6l12 12"
+									/>
+								</svg>
+							</button>
+						)}
+					</div>
+					<CategoryFilterDropdown
+						value={categoryFilter}
+						onChange={setCategoryFilter}
+						categories={categories ?? []}
+					/>
+				</div>
+				{hasActiveFilters && (
+					<p className="text-xs text-gray-500 mt-2">
+						Showing {filteredItems.length} of {items.length} items
+					</p>
+				)}
+			</div>
+
+			{/* Filtered results */}
+			{hasActiveFilters ? (
+				filteredItems.length === 0 ? (
+					<div className="py-12 text-center">
+						<p className="text-sm text-gray-500">
+							No items match your search
+						</p>
+					</div>
+				) : (
+					<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+						{filteredItems.map((item) => (
+							<ItemCard
+								key={item.id}
+								id={item.id}
+								name={item.name}
+								weightGrams={item.weightGrams}
+								priceCents={item.priceCents}
+								categoryName={item.categoryName}
+								categoryIcon={item.categoryIcon}
+								imageFilename={item.imageFilename}
+								productUrl={item.productUrl}
+							/>
+						))}
+					</div>
+				)
+			) : (
+				Array.from(groupedItems.entries()).map(
 					([
 						categoryId,
 						{ items: categoryItems, categoryName, categoryIcon },
@@ -172,6 +275,7 @@ function CollectionView() {
 							</div>
 						);
 					},
+				)
 			)}
 		</>
 	);
@@ -217,7 +321,7 @@ function PlanningView() {
 				<button
 					type="button"
 					onClick={openCreateThreadModal}
-					className="inline-flex items-center gap-2 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+					className="inline-flex items-center gap-2 px-4 py-2 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 				>
 					<svg
 						aria-hidden="true"
@@ -246,7 +350,7 @@ function PlanningView() {
 						onClick={() => setActiveTab("active")}
 						className={`px-4 py-1.5 text-sm font-medium rounded-full transition-colors ${
 							activeTab === "active"
-								? "bg-blue-600 text-white"
+								? "bg-gray-700 text-white"
 								: "text-gray-600 hover:bg-gray-200"
 						}`}
 					>
@@ -257,7 +361,7 @@ function PlanningView() {
 						onClick={() => setActiveTab("resolved")}
 						className={`px-4 py-1.5 text-sm font-medium rounded-full transition-colors ${
 							activeTab === "resolved"
-								? "bg-blue-600 text-white"
+								? "bg-gray-700 text-white"
 								: "text-gray-600 hover:bg-gray-200"
 						}`}
 					>
@@ -266,20 +370,11 @@ function PlanningView() {
 				</div>
 
 				{/* Category filter */}
-				<select
-					value={categoryFilter ?? ""}
-					onChange={(e) =>
-						setCategoryFilter(e.target.value ? Number(e.target.value) : null)
-					}
-					className="px-3 py-1.5 border border-gray-200 rounded-lg text-sm bg-white focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
-				>
-					<option value="">All categories</option>
-					{categories?.map((cat) => (
-						<option key={cat.id} value={cat.id}>
-							{cat.name}
-						</option>
-					))}
-				</select>
+				<CategoryFilterDropdown
+					value={categoryFilter}
+					onChange={setCategoryFilter}
+					categories={categories ?? []}
+				/>
 			</div>
 
 			{/* Content: empty state or thread grid */}
@@ -291,7 +386,7 @@ function PlanningView() {
 						</h2>
 						<div className="space-y-6 text-left mb-10">
 							<div className="flex items-start gap-4">
-								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-700 font-bold text-sm shrink-0">
+								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-gray-200 text-gray-700 font-bold text-sm shrink-0">
 									1
 								</div>
 								<div>
@@ -302,7 +397,7 @@ function PlanningView() {
 								</div>
 							</div>
 							<div className="flex items-start gap-4">
-								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-700 font-bold text-sm shrink-0">
+								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-gray-200 text-gray-700 font-bold text-sm shrink-0">
 									2
 								</div>
 								<div>
@@ -313,7 +408,7 @@ function PlanningView() {
 								</div>
 							</div>
 							<div className="flex items-start gap-4">
-								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-700 font-bold text-sm shrink-0">
+								<div className="flex items-center justify-center w-8 h-8 rounded-full bg-gray-200 text-gray-700 font-bold text-sm shrink-0">
 									3
 								</div>
 								<div>
@@ -327,7 +422,7 @@ function PlanningView() {
 						<button
 							type="button"
 							onClick={openCreateThreadModal}
-							className="inline-flex items-center gap-2 px-5 py-2.5 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+							className="inline-flex items-center gap-2 px-5 py-2.5 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 						>
 							<svg
 								aria-hidden="true"
@@ -374,3 +469,87 @@ function PlanningView() {
 		</div>
 	);
 }
+
+function SetupsView() {
+	const [newSetupName, setNewSetupName] = useState("");
+	const { data: setups, isLoading } = useSetups();
+	const createSetup = useCreateSetup();
+
+	function handleCreateSetup(e: React.FormEvent) {
+		e.preventDefault();
+		const name = newSetupName.trim();
+		if (!name) return;
+		createSetup.mutate({ name }, { onSuccess: () => setNewSetupName("") });
+	}
+
+	return (
+		<div>
+			{/* Create setup form */}
+			<form onSubmit={handleCreateSetup} className="flex gap-2 mb-6">
+				<input
+					type="text"
+					value={newSetupName}
+					onChange={(e) => setNewSetupName(e.target.value)}
+					placeholder="New setup name..."
+					className="flex-1 px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-gray-400 focus:border-transparent"
+				/>
+				<button
+					type="submit"
+					disabled={!newSetupName.trim() || createSetup.isPending}
+					className="px-4 py-2 bg-gray-700 hover:bg-gray-800 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
+				>
+					{createSetup.isPending ? "Creating..." : "Create"}
+				</button>
+			</form>
+
+			{/* Loading skeleton */}
+			{isLoading && (
+				<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+					{[1, 2].map((i) => (
+						<div
+							key={i}
+							className="h-24 bg-gray-200 rounded-xl animate-pulse"
+						/>
+					))}
+				</div>
+			)}
+
+			{/* Empty state */}
+			{!isLoading && (!setups || setups.length === 0) && (
+				<div className="py-16 text-center">
+					<div className="max-w-md mx-auto">
+						<div className="mb-4">
+							<LucideIcon
+								name="tent"
+								size={48}
+								className="text-gray-400 mx-auto"
+							/>
+						</div>
+						<h2 className="text-xl font-semibold text-gray-900 mb-2">
+							No setups yet
+						</h2>
+						<p className="text-sm text-gray-500">
+							Create one to plan your loadout.
+						</p>
+					</div>
+				</div>
+			)}
+
+			{/* Setup grid */}
+			{!isLoading && setups && setups.length > 0 && (
+				<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+					{setups.map((setup) => (
+						<SetupCard
+							key={setup.id}
+							id={setup.id}
+							name={setup.name}
+							itemCount={setup.itemCount}
+							totalWeight={setup.totalWeight}
+							totalCost={setup.totalCost}
+						/>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}

src/client/routes/index.tsx

@@ -3,6 +3,7 @@ import { DashboardCard } from "../components/DashboardCard";
 import { useSetups } from "../hooks/useSetups";
 import { useThreads } from "../hooks/useThreads";
 import { useTotals } from "../hooks/useTotals";
+import { useWeightUnit } from "../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../lib/formatters";
 
 export const Route = createFileRoute("/")({
@@ -13,6 +14,7 @@ function DashboardPage() {
 	const { data: totals } = useTotals();
 	const { data: threads } = useThreads(false);
 	const { data: setups } = useSetups();
+	const unit = useWeightUnit();
 
 	const global = totals?.global;
 	const activeThreadCount = threads?.length ?? 0;
@@ -29,7 +31,7 @@ function DashboardPage() {
 						{ label: "Items", value: String(global?.itemCount ?? 0) },
 						{
 							label: "Weight",
-							value: formatWeight(global?.totalWeight ?? null),
+							value: formatWeight(global?.totalWeight ?? null, unit),
 						},
 						{ label: "Cost", value: formatPrice(global?.totalCost ?? null) },
 					]}
@@ -45,7 +47,8 @@ function DashboardPage() {
 					]}
 				/>
 				<DashboardCard
-					to="/setups"
+					to="/collection"
+					search={{ tab: "setups" }}
 					title="Setups"
 					icon="tent"
 					stats={[{ label: "Setups", value: String(setupCount) }]}

src/client/routes/setups/$setupId.tsx

@@ -1,13 +1,17 @@
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
 import { useState } from "react";
 import { CategoryHeader } from "../../components/CategoryHeader";
+import { ClassificationBadge } from "../../components/ClassificationBadge";
 import { ItemCard } from "../../components/ItemCard";
 import { ItemPicker } from "../../components/ItemPicker";
+import { WeightSummaryCard } from "../../components/WeightSummaryCard";
 import {
 	useDeleteSetup,
 	useRemoveSetupItem,
 	useSetup,
+	useUpdateItemClassification,
 } from "../../hooks/useSetups";
+import { useWeightUnit } from "../../hooks/useWeightUnit";
 import { formatPrice, formatWeight } from "../../lib/formatters";
 import { LucideIcon } from "../../lib/iconData";
 
@@ -17,11 +21,13 @@ export const Route = createFileRoute("/setups/$setupId")({
 
 function SetupDetailPage() {
 	const { setupId } = Route.useParams();
+	const unit = useWeightUnit();
 	const navigate = useNavigate();
 	const numericId = Number(setupId);
 	const { data: setup, isLoading } = useSetup(numericId);
 	const deleteSetup = useDeleteSetup();
 	const removeItem = useRemoveSetupItem(numericId);
+	const updateClassification = useUpdateItemClassification(numericId);
 
 	const [pickerOpen, setPickerOpen] = useState(false);
 	const [confirmDelete, setConfirmDelete] = useState(false);
@@ -84,6 +90,12 @@ function SetupDetailPage() {
 		}
 	}
 
+	function nextClassification(current: string): string {
+		const order = ["base", "worn", "consumable"];
+		const idx = order.indexOf(current);
+		return order[(idx + 1) % order.length];
+	}
+
 	function handleDelete() {
 		deleteSetup.mutate(numericId, {
 			onSuccess: () => navigate({ to: "/setups" }),
@@ -105,7 +117,7 @@ function SetupDetailPage() {
 						</span>
 						<span>
 							<span className="font-medium text-gray-700">
-								{formatWeight(totalWeight)}
+								{formatWeight(totalWeight, unit)}
 							</span>{" "}
 							total
 						</span>
@@ -124,7 +136,7 @@ function SetupDetailPage() {
 				<button
 					type="button"
 					onClick={() => setPickerOpen(true)}
-					className="inline-flex items-center gap-2 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+					className="inline-flex items-center gap-2 px-4 py-2 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 				>
 					<svg
 						className="w-4 h-4"
@@ -170,7 +182,7 @@ function SetupDetailPage() {
 						<button
 							type="button"
 							onClick={() => setPickerOpen(true)}
-							className="inline-flex items-center gap-2 px-5 py-2.5 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+							className="inline-flex items-center gap-2 px-5 py-2.5 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 						>
 							Add Items
 						</button>
@@ -178,9 +190,10 @@ function SetupDetailPage() {
 				</div>
 			)}
 
-			{/* Items grouped by category */}
+			{/* Weight summary card + items grouped by category */}
 			{itemCount > 0 && (
 				<div className="pb-6">
+					<WeightSummaryCard items={setup.items} />
 					{Array.from(groupedItems.entries()).map(
 						([
 							categoryId,
@@ -206,8 +219,8 @@ function SetupDetailPage() {
 									/>
 									<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
 										{categoryItems.map((item) => (
+											<div key={item.id}>
 												<ItemCard
-												key={item.id}
 													id={item.id}
 													name={item.name}
 													weightGrams={item.weightGrams}
@@ -218,6 +231,20 @@ function SetupDetailPage() {
 													productUrl={item.productUrl}
 													onRemove={() => removeItem.mutate(item.id)}
 												/>
+												<div className="px-4 pb-3 -mt-1">
+													<ClassificationBadge
+														classification={item.classification}
+														onCycle={() =>
+															updateClassification.mutate({
+																itemId: item.id,
+																classification: nextClassification(
+																	item.classification,
+																),
+															})
+														}
+													/>
+												</div>
+											</div>
 										))}
 									</div>
 								</div>

src/client/routes/setups/index.tsx

@@ -1,93 +0,0 @@
-import { createFileRoute } from "@tanstack/react-router";
-import { useState } from "react";
-import { SetupCard } from "../../components/SetupCard";
-import { useCreateSetup, useSetups } from "../../hooks/useSetups";
-import { LucideIcon } from "../../lib/iconData";
-
-export const Route = createFileRoute("/setups/")({
-	component: SetupsListPage,
-});
-
-function SetupsListPage() {
-	const [newSetupName, setNewSetupName] = useState("");
-	const { data: setups, isLoading } = useSetups();
-	const createSetup = useCreateSetup();
-
-	function handleCreateSetup(e: React.FormEvent) {
-		e.preventDefault();
-		const name = newSetupName.trim();
-		if (!name) return;
-		createSetup.mutate({ name }, { onSuccess: () => setNewSetupName("") });
-	}
-
-	return (
-		<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6">
-			{/* Create setup form */}
-			<form onSubmit={handleCreateSetup} className="flex gap-2 mb-6">
-				<input
-					type="text"
-					value={newSetupName}
-					onChange={(e) => setNewSetupName(e.target.value)}
-					placeholder="New setup name..."
-					className="flex-1 px-3 py-2 border border-gray-200 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
-				/>
-				<button
-					type="submit"
-					disabled={!newSetupName.trim() || createSetup.isPending}
-					className="px-4 py-2 bg-blue-600 hover:bg-blue-700 disabled:opacity-50 text-white text-sm font-medium rounded-lg transition-colors"
-				>
-					{createSetup.isPending ? "Creating..." : "Create"}
-				</button>
-			</form>
-
-			{/* Loading skeleton */}
-			{isLoading && (
-				<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-					{[1, 2].map((i) => (
-						<div
-							key={i}
-							className="h-24 bg-gray-200 rounded-xl animate-pulse"
-						/>
-					))}
-				</div>
-			)}
-
-			{/* Empty state */}
-			{!isLoading && (!setups || setups.length === 0) && (
-				<div className="py-16 text-center">
-					<div className="max-w-md mx-auto">
-						<div className="mb-4">
-							<LucideIcon
-								name="tent"
-								size={48}
-								className="text-gray-400 mx-auto"
-							/>
-						</div>
-						<h2 className="text-xl font-semibold text-gray-900 mb-2">
-							No setups yet
-						</h2>
-						<p className="text-sm text-gray-500">
-							Create one to plan your loadout.
-						</p>
-					</div>
-				</div>
-			)}
-
-			{/* Setup grid */}
-			{!isLoading && setups && setups.length > 0 && (
-				<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-					{setups.map((setup) => (
-						<SetupCard
-							key={setup.id}
-							id={setup.id}
-							name={setup.name}
-							itemCount={setup.itemCount}
-							totalWeight={setup.totalWeight}
-							totalCost={setup.totalCost}
-						/>
-					))}
-				</div>
-			)}
-		</div>
-	);
-}

src/client/routes/threads/$threadId.tsx

@@ -1,5 +1,6 @@
 import { createFileRoute, Link } from "@tanstack/react-router";
 import { CandidateCard } from "../../components/CandidateCard";
+import { useUpdateCandidate } from "../../hooks/useCandidates";
 import { useThread } from "../../hooks/useThreads";
 import { LucideIcon } from "../../lib/iconData";
 import { useUIStore } from "../../stores/uiStore";
@@ -13,6 +14,7 @@ function ThreadDetailPage() {
 	const threadId = Number(threadIdParam);
 	const { data: thread, isLoading, isError } = useThread(threadId);
 	const openCandidateAddPanel = useUIStore((s) => s.openCandidateAddPanel);
+	const updateCandidate = useUpdateCandidate(threadId);
 
 	if (isLoading) {
 		return (
@@ -38,7 +40,7 @@ function ThreadDetailPage() {
 				<Link
 					to="/"
 					search={{ tab: "planning" }}
-					className="text-sm text-blue-600 hover:text-blue-700"
+					className="text-sm text-gray-600 hover:text-gray-700"
 				>
 					Back to planning
 				</Link>
@@ -67,7 +69,7 @@ function ThreadDetailPage() {
 					<span
 						className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${
 							isActive
-								? "bg-blue-50 text-blue-700"
+								? "bg-gray-100 text-gray-600"
 								: "bg-gray-100 text-gray-500"
 						}`}
 					>
@@ -92,7 +94,7 @@ function ThreadDetailPage() {
 					<button
 						type="button"
 						onClick={openCandidateAddPanel}
-						className="inline-flex items-center gap-2 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition-colors"
+						className="inline-flex items-center gap-2 px-4 py-2 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
 					>
 						<svg
 							className="w-4 h-4"
@@ -144,6 +146,13 @@ function ThreadDetailPage() {
 							productUrl={candidate.productUrl}
 							threadId={threadId}
 							isActive={isActive}
+							status={candidate.status}
+							onStatusChange={(newStatus) =>
+								updateCandidate.mutate({
+									candidateId: candidate.id,
+									status: newStatus,
+								})
+							}
 						/>
 					))}
 				</div>

src/db/schema.ts

@@ -58,6 +58,7 @@ export const threadCandidates = sqliteTable("thread_candidates", {
 	notes: text("notes"),
 	productUrl: text("product_url"),
 	imageFilename: text("image_filename"),
+	status: text("status").notNull().default("researching"),
 	createdAt: integer("created_at", { mode: "timestamp" })
 		.notNull()
 		.$defaultFn(() => new Date()),
@@ -85,6 +86,7 @@ export const setupItems = sqliteTable("setup_items", {
 	itemId: integer("item_id")
 		.notNull()
 		.references(() => items.id, { onDelete: "cascade" }),
+	classification: text("classification").notNull().default("base"),
 });
 
 export const settings = sqliteTable("settings", {

src/server/routes/setups.ts

@@ -3,6 +3,7 @@ import { Hono } from "hono";
 import {
 	createSetupSchema,
 	syncSetupItemsSchema,
+	updateClassificationSchema,
 	updateSetupSchema,
 } from "../../shared/schemas.ts";
 import {
@@ -12,6 +13,7 @@ import {
 	getSetupWithItems,
 	removeSetupItem,
 	syncSetupItems,
+	updateItemClassification,
 	updateSetup,
 } from "../services/setup.service.ts";
 
@@ -73,6 +75,19 @@ app.put("/:id/items", zValidator("json", syncSetupItemsSchema), (c) => {
 	return c.json({ success: true });
 });
 
+app.patch(
+	"/:id/items/:itemId/classification",
+	zValidator("json", updateClassificationSchema),
+	(c) => {
+		const db = c.get("db");
+		const setupId = Number(c.req.param("id"));
+		const itemId = Number(c.req.param("itemId"));
+		const { classification } = c.req.valid("json");
+		updateItemClassification(db, setupId, itemId, classification);
+		return c.json({ success: true });
+	},
+);
+
 app.delete("/:id/items/:itemId", (c) => {
 	const db = c.get("db");
 	const setupId = Number(c.req.param("id"));

src/server/services/setup.service.ts

@@ -53,6 +53,7 @@ export function getSetupWithItems(db: Db = prodDb, setupId: number) {
 			updatedAt: items.updatedAt,
 			categoryName: categories.name,
 			categoryIcon: categories.icon,
+			classification: setupItems.classification,
 		})
 		.from(setupItems)
 		.innerJoin(items, eq(setupItems.itemId, items.id))
@@ -101,16 +102,51 @@ export function syncSetupItems(
 	itemIds: number[],
 ) {
 	return db.transaction((tx) => {
+		// Save existing classifications before deleting
+		const existing = tx
+			.select({
+				itemId: setupItems.itemId,
+				classification: setupItems.classification,
+			})
+			.from(setupItems)
+			.where(eq(setupItems.setupId, setupId))
+			.all();
+
+		const classificationMap = new Map<number, string>();
+		for (const row of existing) {
+			classificationMap.set(row.itemId, row.classification);
+		}
+
 		// Delete all existing items for this setup
 		tx.delete(setupItems).where(eq(setupItems.setupId, setupId)).run();
 
-		// Re-insert new items
+		// Re-insert new items, preserving classifications for retained items
 		for (const itemId of itemIds) {
-			tx.insert(setupItems).values({ setupId, itemId }).run();
+			tx.insert(setupItems)
+				.values({
+					setupId,
+					itemId,
+					classification: classificationMap.get(itemId) ?? "base",
+				})
+				.run();
 		}
 	});
 }
 
+export function updateItemClassification(
+	db: Db = prodDb,
+	setupId: number,
+	itemId: number,
+	classification: string,
+) {
+	db.update(setupItems)
+		.set({ classification })
+		.where(
+			sql`${setupItems.setupId} = ${setupId} AND ${setupItems.itemId} = ${itemId}`,
+		)
+		.run();
+}
+
 export function removeSetupItem(
 	db: Db = prodDb,
 	setupId: number,

src/server/services/thread.service.ts

@@ -72,6 +72,7 @@ export function getThreadWithCandidates(db: Db = prodDb, threadId: number) {
 			notes: threadCandidates.notes,
 			productUrl: threadCandidates.productUrl,
 			imageFilename: threadCandidates.imageFilename,
+			status: threadCandidates.status,
 			createdAt: threadCandidates.createdAt,
 			updatedAt: threadCandidates.updatedAt,
 			categoryName: categories.name,
@@ -149,6 +150,7 @@ export function createCandidate(
 			notes: data.notes ?? null,
 			productUrl: data.productUrl ?? null,
 			imageFilename: data.imageFilename ?? null,
+			status: data.status ?? "researching",
 		})
 		.returning()
 		.get();
@@ -165,6 +167,7 @@ export function updateCandidate(
 		notes: string;
 		productUrl: string;
 		imageFilename: string;
+		status: "researching" | "ordered" | "arrived";
 	}>,
 ) {
 	const existing = db

src/shared/schemas.ts

@@ -36,6 +36,13 @@ export const updateThreadSchema = z.object({
 	categoryId: z.number().int().positive().optional(),
 });
 
+// Candidate status
+export const candidateStatusSchema = z.enum([
+	"researching",
+	"ordered",
+	"arrived",
+]);
+
 // Candidate schemas (same fields as items)
 export const createCandidateSchema = z.object({
 	name: z.string().min(1, "Name is required"),
@@ -45,6 +52,7 @@ export const createCandidateSchema = z.object({
 	notes: z.string().optional(),
 	productUrl: z.string().url().optional().or(z.literal("")),
 	imageFilename: z.string().optional(),
+	status: candidateStatusSchema.optional(),
 });
 
 export const updateCandidateSchema = createCandidateSchema.partial();
@@ -65,3 +73,10 @@ export const updateSetupSchema = z.object({
 export const syncSetupItemsSchema = z.object({
 	itemIds: z.array(z.number().int().positive()),
 });
+
+// Classification schemas
+export const classificationSchema = z.enum(["base", "worn", "consumable"]);
+
+export const updateClassificationSchema = z.object({
+	classification: classificationSchema,
+});

src/shared/types.ts

@@ -17,6 +17,7 @@ import type {
 	syncSetupItemsSchema,
 	updateCandidateSchema,
 	updateCategorySchema,
+	updateClassificationSchema,
 	updateItemSchema,
 	updateSetupSchema,
 	updateThreadSchema,
@@ -37,6 +38,7 @@ export type ResolveThread = z.infer<typeof resolveThreadSchema>;
 export type CreateSetup = z.infer<typeof createSetupSchema>;
 export type UpdateSetup = z.infer<typeof updateSetupSchema>;
 export type SyncSetupItems = z.infer<typeof syncSetupItemsSchema>;
+export type UpdateClassification = z.infer<typeof updateClassificationSchema>;
 
 // Types inferred from Drizzle schema
 export type Item = typeof items.$inferSelect;

tests/helpers/db.ts

@@ -54,6 +54,7 @@ export function createTestDb() {
       notes TEXT,
       product_url TEXT,
       image_filename TEXT,
+      status TEXT NOT NULL DEFAULT 'researching',
       created_at INTEGER NOT NULL DEFAULT (unixepoch()),
       updated_at INTEGER NOT NULL DEFAULT (unixepoch())
     )
@@ -72,7 +73,8 @@ export function createTestDb() {
     CREATE TABLE setup_items (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       setup_id INTEGER NOT NULL REFERENCES setups(id) ON DELETE CASCADE,
-      item_id INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE
+      item_id INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+      classification TEXT NOT NULL DEFAULT 'base'
     )
   `);
 

tests/lib/formatters.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { formatWeight } from "@/client/lib/formatters";
+
+describe("formatWeight", () => {
+	describe("grams (default)", () => {
+		test("formats grams with no decimal", () => {
+			expect(formatWeight(100, "g")).toBe("100g");
+		});
+
+		test("rounds fractional grams", () => {
+			expect(formatWeight(99.6, "g")).toBe("100g");
+		});
+
+		test("formats zero grams", () => {
+			expect(formatWeight(0, "g")).toBe("0g");
+		});
+
+		test("defaults to grams when no unit specified (backward compatible)", () => {
+			expect(formatWeight(100)).toBe("100g");
+		});
+	});
+
+	describe("ounces", () => {
+		test("converts grams to ounces with 1 decimal", () => {
+			expect(formatWeight(100, "oz")).toBe("3.5 oz");
+		});
+
+		test("converts 1000g to ounces", () => {
+			expect(formatWeight(1000, "oz")).toBe("35.3 oz");
+		});
+
+		test("formats zero as ounces", () => {
+			expect(formatWeight(0, "oz")).toBe("0.0 oz");
+		});
+	});
+
+	describe("pounds", () => {
+		test("converts grams to pounds with 2 decimals", () => {
+			expect(formatWeight(1000, "lb")).toBe("2.20 lb");
+		});
+
+		test("handles small weight in pounds", () => {
+			expect(formatWeight(5, "lb")).toBe("0.01 lb");
+		});
+
+		test("formats zero as pounds", () => {
+			expect(formatWeight(0, "lb")).toBe("0.00 lb");
+		});
+	});
+
+	describe("kilograms", () => {
+		test("converts grams to kilograms with 2 decimals", () => {
+			expect(formatWeight(1500, "kg")).toBe("1.50 kg");
+		});
+
+		test("handles large weight in kilograms", () => {
+			expect(formatWeight(50000, "kg")).toBe("50.00 kg");
+		});
+
+		test("converts 1000g to 1 kg", () => {
+			expect(formatWeight(1000, "kg")).toBe("1.00 kg");
+		});
+
+		test("formats zero as kilograms", () => {
+			expect(formatWeight(0, "kg")).toBe("0.00 kg");
+		});
+	});
+
+	describe("null and undefined handling", () => {
+		test("returns '--' for null with no unit", () => {
+			expect(formatWeight(null)).toBe("--");
+		});
+
+		test("returns '--' for null with grams", () => {
+			expect(formatWeight(null, "g")).toBe("--");
+		});
+
+		test("returns '--' for null with ounces", () => {
+			expect(formatWeight(null, "oz")).toBe("--");
+		});
+
+		test("returns '--' for null with pounds", () => {
+			expect(formatWeight(null, "lb")).toBe("--");
+		});
+
+		test("returns '--' for null with kilograms", () => {
+			expect(formatWeight(null, "kg")).toBe("--");
+		});
+
+		test("returns '--' for undefined with kilograms", () => {
+			expect(formatWeight(undefined, "kg")).toBe("--");
+		});
+
+		test("returns '--' for undefined with no unit", () => {
+			expect(formatWeight(undefined)).toBe("--");
+		});
+	});
+});

tests/routes/setups.test.ts

@@ -205,6 +205,67 @@ describe("Setup Routes", () => {
 		});
 	});
 
+	describe("PATCH /api/setups/:id/items/:itemId/classification", () => {
+		it("updates item classification and persists it", async () => {
+			const setup = await createSetupViaAPI(app, "Kit");
+			const item = await createItemViaAPI(app, {
+				name: "Jacket",
+				categoryId: 1,
+			});
+
+			// Sync item to setup
+			await app.request(`/api/setups/${setup.id}/items`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ itemIds: [item.id] }),
+			});
+
+			// Patch classification to "worn"
+			const res = await app.request(
+				`/api/setups/${setup.id}/items/${item.id}/classification`,
+				{
+					method: "PATCH",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ classification: "worn" }),
+				},
+			);
+
+			expect(res.status).toBe(200);
+			const body = await res.json();
+			expect(body.success).toBe(true);
+
+			// Verify classification persisted
+			const getRes = await app.request(`/api/setups/${setup.id}`);
+			const getBody = await getRes.json();
+			expect(getBody.items[0].classification).toBe("worn");
+		});
+
+		it("returns 400 for invalid classification value", async () => {
+			const setup = await createSetupViaAPI(app, "Kit");
+			const item = await createItemViaAPI(app, {
+				name: "Tent",
+				categoryId: 1,
+			});
+
+			await app.request(`/api/setups/${setup.id}/items`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ itemIds: [item.id] }),
+			});
+
+			const res = await app.request(
+				`/api/setups/${setup.id}/items/${item.id}/classification`,
+				{
+					method: "PATCH",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ classification: "invalid-value" }),
+				},
+			);
+
+			expect(res.status).toBe(400);
+		});
+	});
+
 	describe("DELETE /api/setups/:id/items/:itemId", () => {
 		it("removes single item from setup", async () => {
 			const setup = await createSetupViaAPI(app, "Kit");

tests/services/setup.service.test.ts

@@ -7,6 +7,7 @@ import {
 	getSetupWithItems,
 	removeSetupItem,
 	syncSetupItems,
+	updateItemClassification,
 	updateSetup,
 } from "../../src/server/services/setup.service.ts";
 import { createTestDb } from "../helpers/db.ts";
@@ -172,6 +173,106 @@ describe("Setup Service", () => {
 		});
 	});
 
+	describe("getSetupWithItems - classification", () => {
+		it("returns classification field defaulting to 'base' for each item", () => {
+			const setup = createSetup(db, { name: "Day Hike" });
+			const item = createItem(db, {
+				name: "Water Bottle",
+				categoryId: 1,
+				weightGrams: 200,
+				priceCents: 2500,
+			});
+			syncSetupItems(db, setup.id, [item.id]);
+
+			const result = getSetupWithItems(db, setup.id);
+			expect(result?.items).toHaveLength(1);
+			expect(result?.items[0].classification).toBe("base");
+		});
+	});
+
+	describe("syncSetupItems - classification preservation", () => {
+		it("preserves existing classifications when re-syncing items", () => {
+			const setup = createSetup(db, { name: "Kit" });
+			const item1 = createItem(db, { name: "Tent", categoryId: 1 });
+			const item2 = createItem(db, { name: "Jacket", categoryId: 1 });
+			const item3 = createItem(db, { name: "Stove", categoryId: 1 });
+
+			// Initial sync
+			syncSetupItems(db, setup.id, [item1.id, item2.id]);
+
+			// Change classifications
+			updateItemClassification(db, setup.id, item1.id, "worn");
+			updateItemClassification(db, setup.id, item2.id, "consumable");
+
+			// Re-sync with item2 kept and item3 added (item1 removed)
+			syncSetupItems(db, setup.id, [item2.id, item3.id]);
+
+			const result = getSetupWithItems(db, setup.id);
+			expect(result?.items).toHaveLength(2);
+
+			const item2Result = result?.items.find((i: any) => i.name === "Jacket");
+			const item3Result = result?.items.find((i: any) => i.name === "Stove");
+			expect(item2Result?.classification).toBe("consumable");
+			expect(item3Result?.classification).toBe("base");
+		});
+
+		it("assigns 'base' to newly added items with no prior classification", () => {
+			const setup = createSetup(db, { name: "Kit" });
+			const item1 = createItem(db, { name: "Item 1", categoryId: 1 });
+
+			syncSetupItems(db, setup.id, [item1.id]);
+			const result = getSetupWithItems(db, setup.id);
+			expect(result?.items[0].classification).toBe("base");
+		});
+	});
+
+	describe("updateItemClassification", () => {
+		it("sets classification for a specific item in a specific setup", () => {
+			const setup = createSetup(db, { name: "Kit" });
+			const item = createItem(db, { name: "Tent", categoryId: 1 });
+			syncSetupItems(db, setup.id, [item.id]);
+
+			updateItemClassification(db, setup.id, item.id, "worn");
+
+			const result = getSetupWithItems(db, setup.id);
+			expect(result?.items[0].classification).toBe("worn");
+		});
+
+		it("changes item from default 'base' to 'worn'", () => {
+			const setup = createSetup(db, { name: "Kit" });
+			const item = createItem(db, { name: "Jacket", categoryId: 1 });
+			syncSetupItems(db, setup.id, [item.id]);
+
+			// Verify default
+			let result = getSetupWithItems(db, setup.id);
+			expect(result?.items[0].classification).toBe("base");
+
+			// Update
+			updateItemClassification(db, setup.id, item.id, "worn");
+
+			result = getSetupWithItems(db, setup.id);
+			expect(result?.items[0].classification).toBe("worn");
+		});
+
+		it("same item in two different setups can have different classifications", () => {
+			const setup1 = createSetup(db, { name: "Hiking" });
+			const setup2 = createSetup(db, { name: "Biking" });
+			const item = createItem(db, { name: "Jacket", categoryId: 1 });
+
+			syncSetupItems(db, setup1.id, [item.id]);
+			syncSetupItems(db, setup2.id, [item.id]);
+
+			updateItemClassification(db, setup1.id, item.id, "worn");
+			updateItemClassification(db, setup2.id, item.id, "base");
+
+			const result1 = getSetupWithItems(db, setup1.id);
+			const result2 = getSetupWithItems(db, setup2.id);
+
+			expect(result1?.items[0].classification).toBe("worn");
+			expect(result2?.items[0].classification).toBe("base");
+		});
+	});
+
 	describe("cascade behavior", () => {
 		it("deleting a collection item removes it from all setups", () => {
 			const setup = createSetup(db, { name: "Kit" });

tests/services/thread.service.test.ts

@@ -217,6 +217,87 @@ describe("Thread Service", () => {
 		});
 	});
 
+	describe("candidate status", () => {
+		it("createCandidate without status returns a candidate with status 'researching'", () => {
+			const thread = createThread(db, { name: "Test Thread", categoryId: 1 });
+			const candidate = createCandidate(db, thread.id, {
+				name: "No Status",
+				categoryId: 1,
+			});
+
+			expect(candidate.status).toBe("researching");
+		});
+
+		it("createCandidate with status 'ordered' returns a candidate with status 'ordered'", () => {
+			const thread = createThread(db, { name: "Test Thread", categoryId: 1 });
+			const candidate = createCandidate(db, thread.id, {
+				name: "Ordered Item",
+				categoryId: 1,
+				status: "ordered",
+			});
+
+			expect(candidate.status).toBe("ordered");
+		});
+
+		it("updateCandidate can change status from 'researching' to 'ordered'", () => {
+			const thread = createThread(db, { name: "Test Thread", categoryId: 1 });
+			const candidate = createCandidate(db, thread.id, {
+				name: "Status Change",
+				categoryId: 1,
+			});
+
+			expect(candidate.status).toBe("researching");
+
+			const updated = updateCandidate(db, candidate.id, {
+				status: "ordered",
+			});
+
+			expect(updated?.status).toBe("ordered");
+		});
+
+		it("updateCandidate can change status from 'ordered' to 'arrived'", () => {
+			const thread = createThread(db, { name: "Test Thread", categoryId: 1 });
+			const candidate = createCandidate(db, thread.id, {
+				name: "Arriving Item",
+				categoryId: 1,
+				status: "ordered",
+			});
+
+			const updated = updateCandidate(db, candidate.id, {
+				status: "arrived",
+			});
+
+			expect(updated?.status).toBe("arrived");
+		});
+
+		it("getThreadWithCandidates includes status field on each candidate", () => {
+			const thread = createThread(db, { name: "Status Thread", categoryId: 1 });
+			createCandidate(db, thread.id, {
+				name: "Candidate A",
+				categoryId: 1,
+			});
+			createCandidate(db, thread.id, {
+				name: "Candidate B",
+				categoryId: 1,
+				status: "ordered",
+			});
+
+			const result = getThreadWithCandidates(db, thread.id);
+			expect(result).toBeDefined();
+			expect(result?.candidates).toHaveLength(2);
+
+			const candidateA = result?.candidates.find(
+				(c) => c.name === "Candidate A",
+			);
+			const candidateB = result?.candidates.find(
+				(c) => c.name === "Candidate B",
+			);
+
+			expect(candidateA?.status).toBe("researching");
+			expect(candidateB?.status).toBe("ordered");
+		});
+	});
+
 	describe("resolveThread", () => {
 		it("atomically creates collection item from candidate data and archives thread", () => {
 			const thread = createThread(db, { name: "Tent Decision", categoryId: 1 });