fix: await verifyAccessToken in MCP middleware

verifyAccessToken is async and returns a Promise. Without await,
the Promise object is always truthy, so any Bearer token (even
invalid ones) was accepted. This fixes MCP OAuth authentication.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -2,9 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [Develop]
   pull_request:
-    branches: [Develop]
 
 jobs:
   ci:
@@ -26,3 +24,33 @@ jobs:
 
       - name: Build
         run: bun run build
+
+  e2e:
+    needs: ci
+    runs-on: docker
+    container:
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Bun
+        run: |
+          apt-get update && apt-get install -y unzip
+          curl -fsSL https://bun.sh/install | bash
+          echo "$HOME/.bun/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          export PATH="$HOME/.bun/bin:$PATH"
+          bun install --frozen-lockfile --ignore-scripts
+
+      - name: Build client
+        run: |
+          export PATH="$HOME/.bun/bin:$PATH"
+          bun run build
+
+      - name: Run E2E tests
+        run: |
+          export PATH="$HOME/.bun/bin:$PATH"
+          CI=true bun run test:e2e

.gitea/workflows/release.yml

@@ -40,7 +40,7 @@ jobs:
     steps:
       - name: Clone repository
         run: |
-          apk add --no-cache git curl jq
+          apk add --no-cache git curl jq docker-cli
           git clone https://${{ secrets.GITEA_TOKEN }}@gitea.jeanlucmakiola.de/${{ gitea.repository }}.git repo
           cd repo
           git checkout ${{ gitea.ref_name }}

.gitignore

@@ -223,6 +223,14 @@ dist/
 uploads/*
 !uploads/.gitkeep
 
+# Worktrees
+.worktrees/
+
+# Playwright
+e2e/test.db
+test-results/
+playwright-report/
+
 # Claude Code
 .claude/
 

.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,11 +2,11 @@
 
 ## 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 gear management and discovery platform. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, research purchases through planning threads with side-by-side comparison, and compose named setups (loadouts) with weight classification and visualization. A global item database with crowd-verified specs and structured reviews helps users make informed purchase decisions. Multi-user with public setup sharing and gear discovery.
 
 ## 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.
+Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
 
 ## Requirements
 
@@ -27,53 +27,79 @@ 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
 
-(No active milestone — use `/gsd:new-milestone` to start next)
+## Current Milestone: v2.0 Platform Foundation
+
+**Goal:** Transform GearBox from a single-user gear tracker into a multi-user platform where people discover gear, research purchases using crowd-verified data, and share their setups.
+
+**Target features:**
+- External auth provider (self-hosted, open-source) for multi-user registration
+- Migrate from SQLite to Postgres
+- Multi-user data model (user ownership on all entities, public/private visibility)
+- Global item database (seeded from manufacturer data, enrichable by users)
+- Public user profiles with shared setups
+- Structured item reviews (ratings + predefined fields, not freeform text)
+- Discovery feed (browse setups, new items, popular gear)
+- Item detail pages with aggregated specs, owner count, setup appearances
 
 ### 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
+- [ ] Freeform reviews with moderation system
+- [ ] Comments on setups
+- [ ] Follow users / activity feeds
+- [ ] OAuth / social login providers
+- [ ] User-to-user messaging
 
 ### 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
+- Barcode scanning — poor UX, manual entry is fine with global database
 - Real-time weather integration — only outdoor-specific, GearBox is hobby-agnostic
+- Freeform UGC (reviews, comments) — defer until moderation infrastructure exists
+- User-to-user messaging — high moderation burden, not core to discovery
+- Wiki-style open item editing — structured contributions only for data quality
+- Maintaining SQLite single-user mode in parallel — diverged at v2.0
 
 ## 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 through v1.4 with 11,333 LOC TypeScript across 90 files. Starting v2.0 platform transformation.
+Tech stack: React 19, Hono, Drizzle ORM, SQLite (migrating to Postgres), TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, framer-motion, all on Bun.
 Primary use case is bikepacking gear but data model is hobby-agnostic.
-Replaces spreadsheet-based gear tracking workflow.
+Existing auth: single-user with cookie sessions + API keys. Will be replaced by external auth provider.
+Existing features: MCP server (19 tools), E2E tests (Playwright), CSV import/export, item comparison, candidate ranking, setup impact preview.
+21 test files (service-level, route-level integration, and E2E).
 
 ## Constraints
 
 - **Runtime**: Bun — used as package manager and runtime
 - **Design**: Light, airy, minimalist — white/light backgrounds, lots of whitespace, no visual clutter
 - **Navigation**: Dashboard-based home page, not sidebar or top-nav tabs
-- **Scope**: No auth, single user for v1
+- **Auth**: External self-hosted provider — no in-house auth maintenance
+- **Database**: Postgres for platform deployment
+- **UGC**: Structured input only (ratings, predefined fields) — no freeform text until moderation exists
+- **Scope**: Multi-user platform with public discovery
 
 ## Key Decisions
 
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
-| No auth for v1 | Single user, simplicity first | ✓ Good |
+| Cookie/API key auth | Single user, public read + authenticated write | ✓ Good |
 | Generic data model | Support any hobby, not just bikepacking | ✓ Good |
 | Dashboard navigation | Clean entry point, not persistent nav | ✓ Good |
 | Bun runtime | User preference | ✓ Good |
@@ -92,6 +118,38 @@ 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 |
+| Platform pivot at v2.0 | Single-user model proven, now build for multi-user discovery | — Pending |
+| External auth provider | Avoid in-house auth security burden, self-hosted + open-source | — Pending |
+| SQLite → Postgres | Multi-user platform needs proper concurrent DB; auth provider needs Postgres anyway | — Pending |
+| Single-user mode diverges at v2.0 | Platform features irrelevant for solo use; maintain as separate artifact if needed | — Pending |
+| Structured UGC only (no freeform) | Minimize moderation burden; ratings + predefined fields cover 80% of value | — Pending |
+| Discovery-first, not social-first | Users come to research gear decisions, not to build social graphs | — Pending |
+| 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 |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
 
 ---
-*Last updated: 2026-03-15 after v1.1 milestone completion*
+*Last updated: 2026-04-03 after v2.0 milestone start*

.planning/REQUIREMENTS.md

@@ -0,0 +1,157 @@
+# Requirements: GearBox v2.0 Platform Foundation
+
+**Defined:** 2026-04-03
+**Core Value:** Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
+
+## v2.0 Requirements
+
+Requirements for this milestone. Each maps to roadmap phases.
+
+### Database Migration
+
+- [ ] **DB-01**: Application runs on PostgreSQL instead of SQLite
+- [ ] **DB-02**: All service functions use async database operations
+- [ ] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
+- [ ] **DB-04**: Existing SQLite data can be migrated to Postgres via a one-time script
+- [ ] **DB-05**: Docker Compose provides Postgres for local development
+
+### Authentication
+
+- [ ] **AUTH-01**: User can register an account via external OIDC auth provider
+- [ ] **AUTH-02**: User can log in via external auth provider and access their data
+- [ ] **AUTH-03**: API keys remain functional for programmatic access (MCP, scripts)
+- [ ] **AUTH-04**: Auth provider runs self-hosted alongside the application
+- [ ] **AUTH-05**: E2E tests authenticate via API keys without depending on the auth provider
+
+### Multi-User Data Model
+
+- [ ] **MULTI-01**: Every item, category, thread, and setup is owned by a specific user
+- [ ] **MULTI-02**: User can only see and modify their own data (cross-user isolation)
+- [ ] **MULTI-03**: Categories use composite unique constraint (userId + name)
+- [ ] **MULTI-04**: Existing data is assigned to the original user during migration
+- [ ] **MULTI-05**: MCP tools operate within the authenticated user's scope
+- [ ] **MULTI-06**: Settings are per-user rather than global
+
+### Image Storage
+
+- [ ] **IMG-01**: Images are stored in MinIO (S3-compatible) instead of local filesystem
+- [ ] **IMG-02**: Existing uploaded images are migrated to MinIO
+- [ ] **IMG-03**: Image upload and retrieval work through the new storage layer
+- [ ] **IMG-04**: Docker Compose provides MinIO for local development
+
+### Global Item Database
+
+- [ ] **GLOB-01**: A global item catalog exists with brand, model, category, manufacturer specs, and image
+- [ ] **GLOB-02**: Global catalog is seeded with initial items from manufacturer data
+- [ ] **GLOB-03**: User can search the global catalog by name or brand
+- [ ] **GLOB-04**: User can link a personal collection item to a global catalog entry
+- [ ] **GLOB-05**: Global item pages show basic info and owner count
+
+### User Profiles & Sharing
+
+- [ ] **PROF-01**: User has a profile with display name, avatar, and bio
+- [ ] **PROF-02**: User can view their own public profile page
+- [ ] **PROF-03**: User can set a setup as public or private
+- [ ] **PROF-04**: Public setups are viewable by anyone without authentication
+- [ ] **PROF-05**: Public profile page lists the user's public setups
+
+## Future Requirements
+
+Deferred to future milestones. Tracked but not in current roadmap.
+
+### Reviews & Ratings
+
+- **REV-01**: User can rate a global item with an overall star rating
+- **REV-02**: User can rate a global item on predefined dimensions (durability, value, etc.)
+- **REV-03**: Item detail pages show average ratings from all reviewers
+
+### Discovery
+
+- **DISC-01**: User can browse recently shared public setups
+- **DISC-02**: User can browse recently reviewed items
+- **DISC-03**: User can browse popular gear by owner count
+
+### Aggregation
+
+- **AGG-01**: Item detail pages show crowd-verified specs (manufacturer vs community-measured weight)
+- **AGG-02**: Item detail pages show which setups include this item
+- **AGG-03**: Setup composition insights ("commonly paired with")
+
+### Social
+
+- **SOCL-01**: User can fork/copy a public setup as a template
+- **SOCL-02**: Planning thread candidates can link to global items for auto-populated specs
+- **SOCL-03**: User can follow other users
+- **SOCL-04**: User can view an activity feed of followed users' content
+
+### Content Moderation
+
+- **MOD-01**: User can submit freeform text reviews
+- **MOD-02**: User can report inappropriate content
+- **MOD-03**: Admin can review and act on reported content
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Freeform text reviews | Requires moderation infrastructure not yet built |
+| Comments on setups | Moderation burden, notification system needed |
+| User-to-user messaging | High moderation burden, not core to discovery |
+| Wiki-style open item editing | Quality control risk; structured contributions only |
+| Marketplace / buy-sell | Payment processing, fraud, legal liability |
+| AI gear recommendations | Training data requirements, hallucination risk |
+| Gamification (badges, points) | Incentivizes quantity over quality |
+| Instagram-style infinite scroll | Engagement-maximizing conflicts with utility focus |
+| Price tracking / deal alerts | Requires scraping, fragile, legal gray area |
+| Mobile native app | Web-first, responsive design sufficient |
+| Real-time collaborative setups | WebSocket complexity for niche use case |
+| Maintaining SQLite single-user mode | Platform features irrelevant for solo use; diverged at v2.0 |
+| Redis infrastructure | Not needed at v2.0 scale; auth provider (Logto) doesn't require it |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DB-01 | Phase 14 | Pending |
+| DB-02 | Phase 14 | Pending |
+| DB-03 | Phase 14 | Pending |
+| DB-04 | Phase 14 | Pending |
+| DB-05 | Phase 14 | Pending |
+| AUTH-01 | Phase 15 | Pending |
+| AUTH-02 | Phase 15 | Pending |
+| AUTH-03 | Phase 15 | Pending |
+| AUTH-04 | Phase 15 | Pending |
+| AUTH-05 | Phase 15 | Pending |
+| MULTI-01 | Phase 16 | Pending |
+| MULTI-02 | Phase 16 | Pending |
+| MULTI-03 | Phase 16 | Pending |
+| MULTI-04 | Phase 16 | Pending |
+| MULTI-05 | Phase 16 | Pending |
+| MULTI-06 | Phase 16 | Pending |
+| IMG-01 | Phase 17 | Pending |
+| IMG-02 | Phase 17 | Pending |
+| IMG-03 | Phase 17 | Pending |
+| IMG-04 | Phase 17 | Pending |
+| GLOB-01 | Phase 18 | Pending |
+| GLOB-02 | Phase 18 | Pending |
+| GLOB-03 | Phase 18 | Pending |
+| GLOB-04 | Phase 18 | Pending |
+| GLOB-05 | Phase 18 | Pending |
+| PROF-01 | Phase 18 | Pending |
+| PROF-02 | Phase 18 | Pending |
+| PROF-03 | Phase 18 | Pending |
+| PROF-04 | Phase 18 | Pending |
+| PROF-05 | Phase 18 | Pending |
+
+**Coverage:**
+- v2.0 requirements: 30 total
+- Mapped to phases: 30
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-04-03*
+*Last updated: 2026-04-03 after roadmap creation*

.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,29 +2,175 @@
 
 ## 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)
+- 🚧 **v1.3 Research & Decision Tools** — Phases 10-13 (in progress)
+- 📋 **v2.0 Platform Foundation** — Phases 14-18 (planned)
 
 ## 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>
+
+### v1.3 Research & Decision Tools (In Progress)
+
+**Milestone Goal:** Give users the tools to actually decide between candidates — compare details side-by-side, see how a pick impacts their setup, and rank/annotate their options.
+
+- [x] **Phase 10: Schema Foundation + Pros/Cons Fields** — Migrate schema and deliver pros/cons annotation UI (completed 2026-03-16)
+- [x] **Phase 11: Candidate Ranking** — Drag-to-reorder priority ranking with rank badges (completed 2026-03-16)
+- [x] **Phase 12: Comparison View** — Side-by-side tabular comparison with relative deltas (completed 2026-03-17)
+- [ ] **Phase 13: Setup Impact Preview** — Per-candidate weight and cost delta against a selected setup
+
+### v2.0 Platform Foundation (Planned)
+
+**Milestone Goal:** Transform GearBox from a single-user gear tracker into a multi-user platform where people discover gear, research purchases using crowd-verified data, and share their setups.
+
+- [ ] **Phase 14: PostgreSQL Migration** — Replace SQLite with Postgres, make all operations async, establish new test infrastructure
+- [ ] **Phase 15: External Authentication** — Integrate self-hosted OIDC auth provider for user registration and login
+- [ ] **Phase 16: Multi-User Data Model** — Add user ownership to all entities with cross-user data isolation
+- [ ] **Phase 17: Object Storage** — Move images from local filesystem to MinIO (S3-compatible)
+- [ ] **Phase 18: Global Items & Public Profiles** — Global item catalog, user profiles, and public setup sharing
+
+## Phase Details
+
+### Phase 10: Schema Foundation + Pros/Cons Fields
+**Goal**: Candidates can be annotated with pros and cons, and the database is ready for ranking
+**Depends on**: Phase 9
+**Requirements**: RANK-03
+**Success Criteria** (what must be TRUE):
+  1. User can open a candidate edit form and see pros and cons text fields
+  2. User can save pros and cons text; the text persists across page refreshes
+  3. CandidateCard shows a visual indicator when a candidate has pros or cons entered
+  4. All existing tests pass after the schema migration (no column drift in test helper)
+**Plans:** 1/1 plans complete
+Plans:
+- [x] 10-01-PLAN.md — Add pros/cons fields through full stack (schema, service, Zod, form, card indicator)
+
+### Phase 11: Candidate Ranking
+**Goal**: Users can drag candidates into a priority order that persists and is visually communicated
+**Depends on**: Phase 10
+**Requirements**: RANK-01, RANK-02, RANK-04, RANK-05
+**Success Criteria** (what must be TRUE):
+  1. User can drag a candidate card to a new position within the thread's candidate list
+  2. The reordered sequence is still intact after navigating away and returning
+  3. The top three candidates display gold, silver, and bronze rank badges respectively
+  4. Drag handles and rank badges are absent on a resolved thread; candidates render in static order
+**Plans:** 2/2 plans complete
+Plans:
+- [ ] 11-01-PLAN.md — Schema migration, reorder service/route, sort_order persistence + tests
+- [ ] 11-02-PLAN.md — Drag-to-reorder UI, list/grid toggle, rank badges, resolved-thread guard
+
+### Phase 12: Comparison View
+**Goal**: Users can view all candidates for a thread side-by-side in a table with relative weight and price deltas
+**Depends on**: Phase 11
+**Requirements**: COMP-01, COMP-02, COMP-03, COMP-04
+**Success Criteria** (what must be TRUE):
+  1. User can toggle a "Compare" mode on a thread detail page to reveal a tabular view showing weight, price, images, notes, links, status, pros, and cons for every candidate in columns
+  2. The lightest candidate column is highlighted and all other columns show their weight difference relative to it; the cheapest candidate is highlighted similarly for price
+  3. The comparison table scrolls horizontally on a narrow viewport without breaking layout; the attribute label column stays fixed on the left
+  4. A resolved thread shows the comparison table in read-only mode with the winning candidate visually marked
+**Plans:** 1/1 plans complete
+Plans:
+- [ ] 12-01-PLAN.md — ComparisonTable component + compare toggle wiring in thread detail
+
+### Phase 13: Setup Impact Preview
+**Goal**: Users can select any setup and see exactly how much weight and cost each candidate would add or subtract
+**Depends on**: Phase 12
+**Requirements**: IMPC-01, IMPC-02, IMPC-03, IMPC-04
+**Success Criteria** (what must be TRUE):
+  1. User can select a setup from a dropdown in the thread header and each candidate displays a weight delta and cost delta below its name
+  2. When the selected setup contains an item in the same category as the thread, the delta reflects replacing that item (negative delta is possible) rather than pure addition
+  3. When no category match exists in the selected setup, the delta shows a pure addition amount clearly labeled as "add"
+  4. A candidate with no weight recorded shows a "-- (no weight data)" indicator instead of a zero delta
+**Plans:** 2 plans
+Plans:
+- [ ] 13-01-PLAN.md — TDD pure impact delta computation, uiStore state, ThreadWithCandidates type fix, useImpactDeltas hook
+- [ ] 13-02-PLAN.md — SetupImpactSelector + ImpactDeltaBadge components, wire into thread detail and all candidate views
+
+### Phase 14: PostgreSQL Migration
+**Goal**: The application runs entirely on PostgreSQL with async operations, and all existing tests pass against the new database
+**Depends on**: Phase 13
+**Requirements**: DB-01, DB-02, DB-03, DB-04, DB-05
+**Success Criteria** (what must be TRUE):
+  1. Application starts and serves all existing features using PostgreSQL as the sole database
+  2. All service-level and route-level tests pass using PGlite in-memory Postgres (no SQLite test infrastructure remains)
+  3. A one-time migration script converts existing SQLite data into the Postgres database without data loss
+  4. Docker Compose brings up Postgres alongside the app with a single command for local development
+**Plans**: TBD
+
+### Phase 15: External Authentication
+**Goal**: Users can register and log in via a self-hosted OIDC auth provider, replacing the built-in single-user auth system
+**Depends on**: Phase 14
+**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05
+**Success Criteria** (what must be TRUE):
+  1. A new user can register an account through the external auth provider and land on their empty GearBox dashboard
+  2. A returning user can log in via the auth provider and see their previously saved data
+  3. API keys continue to work for MCP tools and programmatic access without involving the auth provider
+  4. E2E tests run successfully using API key authentication, with no dependency on the external auth provider being available
+  5. The auth provider runs self-hosted in Docker Compose alongside Postgres and the application
+**Plans**: TBD
+
+### Phase 16: Multi-User Data Model
+**Goal**: Every piece of user-created data is owned by a specific user, with complete isolation between users
+**Depends on**: Phase 15
+**Requirements**: MULTI-01, MULTI-02, MULTI-03, MULTI-04, MULTI-05, MULTI-06
+**Success Criteria** (what must be TRUE):
+  1. User A cannot see or modify items, categories, threads, or setups created by User B
+  2. Two users can each have a category with the same name without conflict
+  3. Existing data from the single-user era is assigned to the original user account after migration
+  4. MCP tools return only data belonging to the authenticated API key's owner
+  5. Each user has independent settings (weight unit, onboarding state) that do not affect other users
+**Plans**: TBD
+
+### Phase 17: Object Storage
+**Goal**: Images are stored in and served from MinIO instead of the local filesystem
+**Depends on**: Phase 16
+**Requirements**: IMG-01, IMG-02, IMG-03, IMG-04
+**Success Criteria** (what must be TRUE):
+  1. Uploading an image for an item or candidate stores it in MinIO, not on the local filesystem
+  2. All previously uploaded images are accessible after migration to MinIO (no broken images)
+  3. Image URLs work correctly in all views (collection, planning, setups, comparison table)
+  4. Docker Compose includes MinIO for local development with no manual bucket setup required
+**Plans**: TBD
+
+### Phase 18: Global Items & Public Profiles
+**Goal**: Users can discover gear through a global catalog and share their setups publicly via profile pages
+**Depends on**: Phase 17
+**Requirements**: GLOB-01, GLOB-02, GLOB-03, GLOB-04, GLOB-05, PROF-01, PROF-02, PROF-03, PROF-04, PROF-05
+**Success Criteria** (what must be TRUE):
+  1. A global item catalog exists with brand, model, category, specs, and images, seeded with initial manufacturer data
+  2. User can search the global catalog by name or brand and link a personal collection item to a global entry
+  3. A global item page shows basic info and how many users own it
+  4. User can edit their profile (display name, avatar, bio) and view their own public profile page
+  5. User can toggle a setup between public and private; public setups are viewable by anyone without logging in and appear on the owner's public profile
+**Plans**: TBD
+**UI hint**: yes
+
 ## Progress
 
 | Phase | Milestone | Plans Complete | Status | Completed |
@@ -35,3 +181,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 |
+| 10. Schema Foundation + Pros/Cons Fields | v1.3 | 1/1 | Complete | 2026-03-16 |
+| 11. Candidate Ranking | v1.3 | 2/2 | Complete | 2026-03-16 |
+| 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 |
+| 13. Setup Impact Preview | v1.3 | 0/2 | Not started | - |
+| 14. PostgreSQL Migration | v2.0 | 0/? | Not started | - |
+| 15. External Authentication | v2.0 | 0/? | Not started | - |
+| 16. Multi-User Data Model | v2.0 | 0/? | Not started | - |
+| 17. Object Storage | v2.0 | 0/? | Not started | - |
+| 18. Global Items & Public Profiles | v2.0 | 0/? | Not started | - |

.planning/STATE.md

@@ -1,52 +1,69 @@
 ---
 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: v2.0
+milestone_name: Platform Foundation
+status: planning
+stopped_at: null
+last_updated: "2026-04-03"
+last_activity: 2026-04-03 — v2.0 roadmap created (Phases 14-18)
 progress:
-  total_phases: 3
-  completed_phases: 3
-  total_plans: 7
-  completed_plans: 7
-  percent: 100
+  total_phases: 5
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-03-15)
+See: .planning/PROJECT.md (updated 2026-04-03)
 
-**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
+**Core value:** Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
+**Current focus:** v2.0 Platform Foundation — Phase 14 (PostgreSQL Migration)
 
 ## Current Position
 
-Milestone: v1.1 Fixes & Polish -- SHIPPED
-All phases complete. No active milestone.
-Last activity: 2026-03-15 -- Shipped v1.1
+Phase: 14 of 18 (PostgreSQL Migration)
+Plan: 0 of ? in current phase
+Status: Ready to plan
+Last activity: 2026-04-03 — v2.0 roadmap created (Phases 14-18)
 
-Progress: [██████████] 100% (v1.1 shipped)
+Progress: [----------] 0% (v2.0 milestone)
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0 (v2.0 milestone)
+- Average duration: --
+- Total execution time: --
+
+*Updated after each plan completion*
 
 ## Accumulated Context
 
 ### Decisions
 
-(Full decision log archived in PROJECT.md Key Decisions table)
+Key decisions made during v2.0 planning:
+- Platform pivot: single-user to multi-user with discovery-first approach
+- External auth provider (self-hosted, open-source) — Logto vs Authentik OPEN decision
+- SQLite to Postgres migration — required by auth provider and multi-user concurrency
+- Structured UGC only — ratings and predefined fields, no freeform text until moderation
+- Separate globalItems table — not a flag on user items table
+- Single-user SQLite mode diverges at v2.0 boundary
 
 ### Pending Todos
 
-- Replace planning category filter select with icon-aware dropdown (ui)
+None active.
 
 ### Blockers/Concerns
 
-None active.
+- Auth provider decision (Logto vs Authentik) must be resolved before Phase 15 planning
+- Phase 14 is a full schema rewrite touching 6 services, 7 routes, 19 MCP tools, all tests
 
 ## Session Continuity
 
-Last session: 2026-03-15T17:15:00.000Z
-Stopped at: v1.1 milestone completed and archived
+Last session: 2026-04-03
+Stopped at: v2.0 roadmap created with 5 phases (14-18) covering 30 requirements
 Resume file: None

.planning/config.json

@@ -1,14 +1,14 @@
 {
-	"mode": "yolo",
-	"granularity": "coarse",
-	"parallelization": true,
-	"commit_docs": true,
-	"model_profile": "quality",
-	"workflow": {
-		"research": false,
-		"plan_check": true,
-		"verifier": true,
-		"nyquist_validation": true,
-		"_auto_chain_active": true
-	}
-}
+  "mode": "yolo",
+  "granularity": "coarse",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "quality",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "_auto_chain_active": 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/phases/10-schema-foundation-pros-cons-fields/10-01-PLAN.md

@@ -0,0 +1,302 @@
+---
+phase: 10-schema-foundation-pros-cons-fields
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/db/schema.ts
+  - tests/helpers/db.ts
+  - src/server/services/thread.service.ts
+  - src/shared/schemas.ts
+  - src/client/hooks/useCandidates.ts
+  - src/client/components/CandidateForm.tsx
+  - src/client/components/CandidateCard.tsx
+  - src/client/routes/threads/$threadId.tsx
+  - tests/services/thread.service.test.ts
+autonomous: true
+requirements: [RANK-03]
+
+must_haves:
+  truths:
+    - "User can open a candidate edit form and see pros and cons text fields"
+    - "User can save pros and cons text; the text persists across page refreshes"
+    - "CandidateCard shows a visual indicator when a candidate has pros or cons entered"
+    - "All existing tests pass after the schema migration (no column drift in test helper)"
+  artifacts:
+    - path: "src/db/schema.ts"
+      provides: "pros and cons nullable TEXT columns on threadCandidates"
+      contains: "pros: text"
+    - path: "tests/helpers/db.ts"
+      provides: "Mirrored pros/cons columns in test DB CREATE TABLE"
+      contains: "pros TEXT"
+    - path: "src/server/services/thread.service.ts"
+      provides: "pros/cons in createCandidate, updateCandidate, getThreadWithCandidates"
+      contains: "pros:"
+    - path: "src/shared/schemas.ts"
+      provides: "pros and cons optional string fields in createCandidateSchema"
+      contains: "pros: z.string"
+    - path: "src/client/components/CandidateForm.tsx"
+      provides: "Pros and Cons textarea inputs in candidate form"
+      contains: "candidate-pros"
+    - path: "src/client/components/CandidateCard.tsx"
+      provides: "Visual indicator badge when pros or cons are present"
+      contains: "pros || cons"
+    - path: "tests/services/thread.service.test.ts"
+      provides: "Tests for pros/cons in create, update, and get operations"
+      contains: "pros"
+  key_links:
+    - from: "src/db/schema.ts"
+      to: "tests/helpers/db.ts"
+      via: "Manual column mirroring in CREATE TABLE"
+      pattern: "pros TEXT"
+    - from: "src/shared/schemas.ts"
+      to: "src/server/services/thread.service.ts"
+      via: "Zod-inferred CreateCandidate type used in service"
+      pattern: "CreateCandidate"
+    - from: "src/server/services/thread.service.ts"
+      to: "src/client/hooks/useCandidates.ts"
+      via: "API JSON response includes pros/cons fields"
+      pattern: "pros.*string.*null"
+    - from: "src/client/hooks/useCandidates.ts"
+      to: "src/client/components/CandidateForm.tsx"
+      via: "CandidateResponse type drives form pre-fill"
+      pattern: "candidate\\.pros"
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/components/CandidateCard.tsx"
+      via: "Props threaded from candidate data to card"
+      pattern: "pros=.*candidate\\.pros"
+---
+
+<objective>
+Add pros and cons annotation fields to thread candidates, from database through UI.
+
+Purpose: RANK-03 requires users to add pros/cons text per candidate for decision-making. This plan follows the established field-addition ladder: schema -> migration -> test helper -> service -> Zod -> types -> hook -> form -> card indicator.
+
+Output: Two new nullable TEXT columns (pros, cons) on thread_candidates, fully wired through all layers, with service-level tests and a visual indicator on CandidateCard.
+</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/10-schema-foundation-pros-cons-fields/10-RESEARCH.md
+
+<interfaces>
+<!-- Current codebase contracts the executor needs. -->
+
+From src/db/schema.ts (threadCandidates table -- add pros/cons after status):
+```typescript
+export const threadCandidates = sqliteTable("thread_candidates", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  threadId: integer("thread_id").notNull().references(() => threads.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  weightGrams: real("weight_grams"),
+  priceCents: integer("price_cents"),
+  categoryId: integer("category_id").notNull().references(() => categories.id),
+  notes: text("notes"),
+  productUrl: text("product_url"),
+  imageFilename: text("image_filename"),
+  status: text("status").notNull().default("researching"),
+  // ADD: pros: text("pros"),
+  // ADD: cons: text("cons"),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+```
+
+From src/shared/schemas.ts (createCandidateSchema -- add optional pros/cons):
+```typescript
+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(),
+});
+// updateCandidateSchema = createCandidateSchema.partial() -- inherits automatically
+```
+
+From src/server/services/thread.service.ts:
+```typescript
+// createCandidate: values() object needs pros/cons
+// updateCandidate: inline Partial<{...}> type needs pros/cons
+// getThreadWithCandidates: explicit .select({}) projection needs pros/cons
+```
+
+From src/client/hooks/useCandidates.ts:
+```typescript
+interface CandidateResponse {
+  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";
+  createdAt: string; updatedAt: string;
+  // ADD: pros: string | null;
+  // ADD: cons: string | null;
+}
+```
+
+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: "researching" | "ordered" | "arrived";
+  onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
+  // ADD: pros?: string | null;
+  // ADD: cons?: string | null;
+}
+```
+
+From src/client/components/CandidateForm.tsx:
+```typescript
+interface FormData {
+  name: string; weightGrams: string; priceDollars: string;
+  categoryId: number; notes: string; productUrl: string;
+  imageFilename: string | null;
+  // ADD: pros: string;
+  // ADD: cons: string;
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Add pros/cons columns through backend + tests</name>
+  <files>src/db/schema.ts, tests/helpers/db.ts, src/server/services/thread.service.ts, src/shared/schemas.ts, tests/services/thread.service.test.ts</files>
+  <behavior>
+    - createCandidate with pros/cons returns them in the response
+    - createCandidate without pros/cons returns null for both fields
+    - updateCandidate can set pros and cons on an existing candidate
+    - updateCandidate can clear pros/cons by setting to empty string (becomes null via service)
+    - getThreadWithCandidates includes pros and cons on each candidate object
+    - All existing thread service tests still pass (no column drift)
+  </behavior>
+  <action>
+    1. **Schema** (`src/db/schema.ts`): Add two nullable TEXT columns to `threadCandidates` after `status`:
+       ```typescript
+       pros: text("pros"),
+       cons: text("cons"),
+       ```
+
+    2. **Migration**: Run `bun run db:generate` to produce the ALTER TABLE migration, then `bun run db:push` to apply.
+
+    3. **Test helper** (`tests/helpers/db.ts`): Add `pros TEXT,` and `cons TEXT,` to the `CREATE TABLE thread_candidates` statement, between the `status` line and the `created_at` line. This is CRITICAL -- without it, in-memory test DBs will silently lack the columns.
+
+    4. **Service** (`src/server/services/thread.service.ts`):
+       - `createCandidate`: Add `pros: data.pros ?? null,` and `cons: data.cons ?? null,` to the `.values({})` object.
+       - `updateCandidate`: Add `pros: string;` and `cons: string;` to the inline `Partial<{...}>` type parameter.
+       - `getThreadWithCandidates`: Add `pros: threadCandidates.pros,` and `cons: threadCandidates.cons,` to the explicit `.select({})` projection, before the `categoryName` line.
+
+    5. **Zod schemas** (`src/shared/schemas.ts`): Add to `createCandidateSchema`:
+       ```typescript
+       pros: z.string().optional(),
+       cons: z.string().optional(),
+       ```
+       `updateCandidateSchema` inherits via `.partial()` -- no changes needed there.
+
+    6. **Tests** (`tests/services/thread.service.test.ts`): Add three test cases:
+       - In `describe("createCandidate")`: "stores and returns pros and cons" -- create a candidate with `pros: "Lightweight\nGood reviews"` and `cons: "Expensive"`, assert both fields are returned correctly.
+       - In `describe("updateCandidate")`: "can set and clear pros and cons" -- create a candidate, update with pros/cons values, assert they are set, then update with empty strings, assert they are cleared (returned as empty string or null from DB).
+       - In `describe("getThreadWithCandidates")`: "includes pros and cons on each candidate" -- create a candidate with pros/cons, fetch via getThreadWithCandidates, assert `candidate.pros` and `candidate.cons` match.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test tests/services/thread.service.test.ts</automated>
+  </verify>
+  <done>
+    - pros and cons columns exist in schema.ts and test helper
+    - Drizzle migration generated and applied
+    - createCandidate, updateCandidate, getThreadWithCandidates all handle pros/cons
+    - Zod schemas accept optional pros/cons strings
+    - All existing + new thread service tests pass
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Wire pros/cons through client hooks, form, and card indicator</name>
+  <files>src/client/hooks/useCandidates.ts, src/client/components/CandidateForm.tsx, src/client/components/CandidateCard.tsx, src/client/routes/threads/$threadId.tsx</files>
+  <action>
+    1. **Hook** (`src/client/hooks/useCandidates.ts`): Add to `CandidateResponse` interface:
+       ```typescript
+       pros: string | null;
+       cons: string | null;
+       ```
+
+    2. **CandidateForm** (`src/client/components/CandidateForm.tsx`):
+       - Add `pros: string;` and `cons: string;` to `FormData` interface.
+       - Add `pros: "",` and `cons: "",` to `INITIAL_FORM`.
+       - In the `useEffect` pre-fill block, add: `pros: candidate.pros ?? "",` and `cons: candidate.cons ?? "",`.
+       - In `handleSubmit` payload, add: `pros: form.pros.trim() || undefined,` and `cons: form.cons.trim() || undefined,`.
+       - Add two textarea elements in the form, AFTER the Notes textarea and BEFORE the Product Link input. Each should follow the exact same pattern as the Notes textarea:
+         - **Pros**: label "Pros", id `candidate-pros`, placeholder "One pro per line...", rows={3}
+         - **Cons**: label "Cons", id `candidate-cons`, placeholder "One con per line...", rows={3}
+       - Use identical Tailwind classes as the existing Notes textarea.
+
+    3. **CandidateCard** (`src/client/components/CandidateCard.tsx`):
+       - Add `pros?: string | null;` and `cons?: string | null;` to `CandidateCardProps` interface.
+       - Destructure `pros` and `cons` in the component function parameters.
+       - Add a visual indicator badge in the `flex flex-wrap gap-1.5` div, after the StatusBadge. When `(pros || cons)` is truthy, render:
+         ```tsx
+         {(pros || cons) && (
+           <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-purple-50 text-purple-700">
+             +/- Notes
+           </span>
+         )}
+         ```
+
+    4. **Thread detail route** (`src/client/routes/threads/$threadId.tsx`): Pass `pros` and `cons` props to the `<CandidateCard>` component in the candidates map:
+       ```tsx
+       pros={candidate.pros}
+       cons={candidate.cons}
+       ```
+
+    5. Run `bun run lint` to verify Biome compliance (tabs, double quotes, organized imports).
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test && bun run lint</automated>
+  </verify>
+  <done>
+    - CandidateResponse includes pros/cons fields
+    - CandidateForm shows Pros and Cons textareas, pre-fills in edit mode, sends in payload
+    - CandidateCard shows purple "+/- Notes" badge when pros or cons text exists
+    - Thread detail page threads pros/cons props to CandidateCard
+    - Full test suite passes, lint passes
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. `bun test` -- full suite green (existing + new tests)
+2. `bun run lint` -- no Biome violations
+3. Manual: create a thread, add a candidate with pros and cons text, verify:
+   - Pros/cons fields appear in the edit form
+   - Saved text persists after page refresh
+   - CandidateCard shows the "+/- Notes" indicator badge
+   - A candidate without pros/cons does NOT show the badge
+</verification>
+
+<success_criteria>
+- RANK-03 fully implemented: pros/cons fields on candidates, editable via form, persisted, with visual indicator
+- Zero test regressions
+- No column drift between schema.ts and test helper
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/10-schema-foundation-pros-cons-fields/10-01-SUMMARY.md`
+</output>

.planning/phases/10-schema-foundation-pros-cons-fields/10-01-SUMMARY.md

@@ -0,0 +1,130 @@
+---
+phase: 10-schema-foundation-pros-cons-fields
+plan: "01"
+subsystem: database
+tags: [drizzle, sqlite, react, forms, zod]
+
+# Dependency graph
+requires: []
+provides:
+  - "pros/cons nullable TEXT columns on thread_candidates table (DB + migration)"
+  - "Zod schema fields: pros/cons optional strings in createCandidateSchema"
+  - "Service layer: createCandidate, updateCandidate, getThreadWithCandidates handle pros/cons"
+  - "Client CandidateForm: Pros and Cons textarea inputs with pre-fill and submit payload"
+  - "Client CandidateCard: purple +/- Notes badge when pros or cons text exists"
+  - "CandidateResponse type includes pros/cons fields"
+affects: [thread-ranking, candidate-comparison, future-candidate-features]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [field-addition-ladder, tdd-red-green]
+
+key-files:
+  created:
+    - drizzle/0004_soft_synch.sql
+  modified:
+    - src/db/schema.ts
+    - tests/helpers/db.ts
+    - src/server/services/thread.service.ts
+    - src/shared/schemas.ts
+    - src/client/hooks/useCandidates.ts
+    - src/client/components/CandidateForm.tsx
+    - src/client/components/CandidateCard.tsx
+    - src/client/routes/threads/$threadId.tsx
+    - tests/services/thread.service.test.ts
+
+key-decisions:
+  - "Empty string for pros/cons stored as-is by SQLite (not normalized to null) — updateCandidate test accepts empty string or null as cleared state"
+  - "Pros/Cons textareas placed after Notes and before Product Link — logical grouping for research annotation"
+  - "Visual indicator uses purple color scheme to distinguish from weight (blue), price (green), category (gray), and status badges"
+
+patterns-established:
+  - "Field-addition ladder: schema -> migration -> test helper -> service -> Zod -> types -> hook -> form -> card indicator"
+  - "Test helper CREATE TABLE must mirror schema.ts columns exactly — column drift causes silent test failures"
+  - "TDD: RED commit (failing tests) -> GREEN commit (implementation) per task"
+
+requirements-completed: [RANK-03]
+
+# Metrics
+duration: 6min
+completed: "2026-03-16"
+---
+
+# Phase 10 Plan 01: Schema Foundation Pros/Cons Fields Summary
+
+**Nullable pros/cons TEXT columns added to thread_candidates from SQLite schema through Drizzle migration, service layer, Zod validation, React form inputs, and CandidateCard visual badge**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-03-16T20:30:18Z
+- **Completed:** 2026-03-16T20:36:25Z
+- **Tasks:** 2
+- **Files modified:** 9
+
+## Accomplishments
+- Added pros/cons columns to threadCandidates schema and applied Drizzle migration (0004_soft_synch.sql)
+- Wired pros/cons through all backend layers: service create/update/get + Zod schemas
+- Added Pros and Cons textarea inputs to CandidateForm with pre-fill in edit mode
+- Added purple "+/- Notes" badge to CandidateCard when either field has content
+- 28 thread service tests passing (24 existing + 4 new) with zero regressions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **TDD RED - failing tests** - `719f708` (test)
+2. **Task 1: Add pros/cons columns through backend + tests** - `7a64a18` (feat)
+3. **Task 2: Wire pros/cons through client hooks, form, and card indicator** - `4f2aefe` (feat)
+
+_Note: TDD task has separate test commit (RED) and implementation commit (GREEN)_
+
+## Files Created/Modified
+- `src/db/schema.ts` - Added pros/cons nullable TEXT columns to threadCandidates
+- `drizzle/0004_soft_synch.sql` - Migration: ALTER TABLE thread_candidates ADD COLUMN pros/cons
+- `tests/helpers/db.ts` - Mirrored pros/cons in CREATE TABLE thread_candidates
+- `src/server/services/thread.service.ts` - pros/cons in createCandidate values(), updateCandidate Partial type, getThreadWithCandidates select
+- `src/shared/schemas.ts` - pros/cons optional string fields in createCandidateSchema (updateCandidateSchema inherits via .partial())
+- `src/client/hooks/useCandidates.ts` - pros/cons added to CandidateResponse interface
+- `src/client/components/CandidateForm.tsx` - Pros and Cons textareas, FormData fields, INITIAL_FORM, pre-fill, payload
+- `src/client/components/CandidateCard.tsx` - props, destructuring, purple +/- Notes badge
+- `src/client/routes/threads/$threadId.tsx` - pros={candidate.pros} cons={candidate.cons} passed to CandidateCard
+- `tests/services/thread.service.test.ts` - 4 new test cases for pros/cons create/update/get
+
+## Decisions Made
+- Empty string for pros/cons is stored as-is (not normalized to null on empty); the test accepts either empty string or null as "cleared" state since SQLite/Drizzle does not coerce empty strings.
+- Visual indicator uses purple to distinguish from existing badge color scheme (blue=weight, green=price, gray=category, status has its own colors).
+- Textarea placement (after Notes, before Product Link) groups annotation fields logically.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+Pre-existing lint violations discovered in files outside the plan scope:
+- `src/client/components/WeightSummaryCard.tsx`, `src/client/routes/collection/index.tsx`, `src/client/routes/index.tsx`, `src/client/routes/setups/$setupId.tsx` — format/organizeImports errors
+- `.obsidian/workspace.json` — Biome format error (IDE file, should be excluded)
+
+These are logged to `deferred-items.md` and not fixed (out of scope per deviation scope boundary rule).
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- RANK-03 fully implemented: pros/cons fields on candidates, editable via form, persisted in SQLite, with visual badge indicator
+- Schema foundation complete — subsequent plans in phase 10 can build ranking/sorting features on top of this data
+- No blockers
+
+---
+*Phase: 10-schema-foundation-pros-cons-fields*
+*Completed: 2026-03-16*
+
+## Self-Check: PASSED
+
+All files and commits verified:
+- All 10 key files present on disk
+- All 3 task commits found in git log (719f708, 7a64a18, 4f2aefe)
+- Key artifact strings confirmed in each file (pros: text, pros TEXT, pros: z.string, candidate-pros, pros || cons)

.planning/phases/10-schema-foundation-pros-cons-fields/10-RESEARCH.md

@@ -0,0 +1,417 @@
+# Phase 10: Schema Foundation + Pros/Cons Fields - Research
+
+**Researched:** 2026-03-16
+**Domain:** Drizzle ORM schema migration + full-stack field addition (SQLite / Hono / React)
+**Confidence:** HIGH
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| RANK-03 | User can add pros and cons text per candidate displayed as bullet lists | Confirmed: two nullable TEXT columns on `thread_candidates` + textarea inputs in `CandidateForm` + visual indicator on `CandidateCard` |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 10 is a contained, top-to-bottom field-addition task. Two nullable `TEXT` columns (`pros`, `cons`) must be added to the `thread_candidates` table, propagated through every layer that touches that table, and surfaced in the UI as editable text areas with a card-level presence indicator.
+
+The project uses Drizzle ORM with SQLite. Adding nullable columns via `ALTER TABLE … ADD COLUMN` is safe in SQLite (no default value is required for nullable TEXT). The Drizzle workflow is: edit `schema.ts` → `bun run db:generate` → `bun run db:push`. The generated SQL migration follows the established pattern already used four times in this project.
+
+There is one mandatory non-obvious step documented in CLAUDE.md: the test helper at `tests/helpers/db.ts` contains a hardcoded `CREATE TABLE thread_candidates` statement that mirrors the production schema. It must be updated in lockstep with `schema.ts` or all existing candidate tests will silently omit the new columns and new service-level tests will fail.
+
+**Primary recommendation:** Follow the exact field-addition ladder: schema → migration → test helper → service (insert + update + select projection) → Zod schemas → shared types → API route (zValidator) → React hook response type → CandidateForm → CandidateCard indicator. Every rung must be touched — skipping any one causes type drift or runtime failures.
+
+---
+
+## Standard Stack
+
+### Core
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| drizzle-orm | installed | ORM + migration generation | Project standard; all migrations use it |
+| drizzle-kit | installed | CLI for `db:generate` | Project standard; configured in drizzle.config.ts |
+| zod | installed | Schema validation on API boundary | Project standard; `@hono/zod-validator` integration |
+| bun:sqlite | runtime built-in | In-memory test DB | Used by `createTestDb()` helper |
+
+No new dependencies are required for this phase.
+
+**Installation:**
+```bash
+# No new packages — all required libraries already installed
+```
+
+---
+
+## Architecture Patterns
+
+### Established Field-Addition Ladder
+
+Every field addition in this codebase follows this exact sequence. Previous examples: `status` on candidates, `classification` on `setup_items`, `icon` on categories.
+
+```
+1. src/db/schema.ts           — Drizzle column definition
+2. drizzle/ (generated)       — bun run db:generate
+3. gearbox.db                 — bun run db:push
+4. tests/helpers/db.ts        — Raw SQL CREATE TABLE mirrored manually
+5. src/server/services/thread.service.ts
+   a. createCandidate()       — values() object
+   b. updateCandidate()       — data type + set()
+   c. getThreadWithCandidates() — explicit column projection
+6. src/shared/schemas.ts      — createCandidateSchema + updateCandidateSchema
+7. src/shared/types.ts        — auto-inferred (no manual edit needed)
+8. src/client/hooks/useCandidates.ts — CandidateResponse interface
+9. src/client/components/CandidateForm.tsx — FormData + textarea inputs + payload
+10. src/client/components/CandidateCard.tsx — visual indicator prop + render
+```
+
+### Pattern 1: Drizzle Nullable Text Column
+
+**What:** Add an optional text field to an existing Drizzle table.
+**When to use:** When the field is user-provided text, no business logic default applies.
+
+```typescript
+// Source: src/db/schema.ts — pattern already used by notes, productUrl, imageFilename
+export const threadCandidates = sqliteTable("thread_candidates", {
+  // ... existing columns ...
+  pros: text("pros"),   // nullable, no default — mirrors notes/productUrl pattern
+  cons: text("cons"),   // nullable, no default
+  // ...
+});
+```
+
+### Pattern 2: Test Helper Table Synchronization
+
+**What:** Mirror every new column in the raw SQL inside `createTestDb()`.
+**When to use:** Every time `schema.ts` is modified. Documented as mandatory in CLAUDE.md.
+
+```typescript
+// Source: tests/helpers/db.ts — existing thread_candidates CREATE TABLE
+sqlite.run(`
+  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',
+    pros TEXT,    -- ADD THIS
+    cons TEXT,    -- ADD THIS
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+  )
+`);
+```
+
+### Pattern 3: Explicit Select Projection in Service
+
+**What:** `getThreadWithCandidates` uses an explicit `.select({...})` projection, not `select()`.
+**When to use:** New columns MUST be explicitly added to the projection or they will not appear in query results.
+
+```typescript
+// Source: src/server/services/thread.service.ts — getThreadWithCandidates()
+const candidateList = db
+  .select({
+    // ... existing fields ...
+    pros: threadCandidates.pros,   // ADD
+    cons: threadCandidates.cons,   // ADD
+    categoryName: categories.name,
+    categoryIcon: categories.icon,
+  })
+  .from(threadCandidates)
+  // ...
+```
+
+### Pattern 4: Zod Schema Extension
+
+**What:** Add optional string fields to `createCandidateSchema`; `updateCandidateSchema` is derived via `.partial()` and picks them up automatically.
+**When to use:** Any new candidate API field.
+
+```typescript
+// Source: src/shared/schemas.ts
+export const createCandidateSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  // ... existing fields ...
+  pros: z.string().optional(),   // ADD
+  cons: z.string().optional(),   // ADD
+});
+
+// updateCandidateSchema = createCandidateSchema.partial() — inherits automatically
+```
+
+### Pattern 5: CandidateForm Textarea Addition
+
+**What:** Extend `FormData` interface and `INITIAL_FORM` constant, add pre-fill in `useEffect`, add textarea elements, include in payload.
+
+```typescript
+// Source: src/client/components/CandidateForm.tsx — FormData interface
+interface FormData {
+  // ... existing ...
+  pros: string;    // ADD
+  cons: string;    // ADD
+}
+
+const INITIAL_FORM: FormData = {
+  // ... existing ...
+  pros: "",        // ADD
+  cons: "",        // ADD
+};
+
+// In useEffect pre-fill:
+pros: candidate.pros ?? "",   // ADD
+cons: candidate.cons ?? "",   // ADD
+
+// In payload construction:
+pros: form.pros.trim() || undefined,   // ADD
+cons: form.cons.trim() || undefined,   // ADD
+```
+
+### Pattern 6: CandidateCard Visual Indicator
+
+**What:** Show a small badge when a candidate has pros or cons text. The requirement says "visual indicator when a candidate has pros or cons entered" — not a full display of the text (that is the form's job).
+**When to use:** When `(pros || cons)` is truthy.
+
+```tsx
+// Source: src/client/components/CandidateCard.tsx — props interface
+interface CandidateCardProps {
+  // ... existing ...
+  pros?: string | null;   // ADD
+  cons?: string | null;   // ADD
+}
+
+// In the card's badge section (alongside weight/price badges):
+{(pros || cons) && (
+  <span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-purple-50 text-purple-500">
+    Notes
+  </span>
+)}
+```
+
+The exact styling (color, icon, text) is left to the planner's discretion — the requirement only specifies "visual indicator."
+
+### Anti-Patterns to Avoid
+
+- **Forgetting the test helper**: If `tests/helpers/db.ts` is not updated, the in-memory schema won't have `pros`/`cons` columns. Tests that insert or read these fields will get `undefined` instead of the stored value, causing silent failures or column-not-found errors. CLAUDE.md documents this as a known hazard.
+- **Using `select()` without explicit fields**: The `getThreadWithCandidates` service function already uses an explicit projection. Adding fields to the schema without adding them to the projection means the client never receives the data.
+- **Storing pros/cons as a JSON array of bullet strings**: The requirement says "text per candidate displayed as bullet lists" — the display can parse newlines into bullets from a plain TEXT field. A single multi-line `TEXT` column is correct and consistent with the existing `notes` field pattern. No JSON, no separate table.
+- **Adding a separate `candidatePros` / `candidateCons` table**: Massive over-engineering. These are simple annotations on a single candidate, not a many-per-candidate relationship.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Schema migration | Custom SQL scripts | `bun run db:generate` + `bun run db:push` | Drizzle-kit generates correct ALTER TABLE, tracks journal, handles snapshot |
+| API input validation | Manual checks | Zod via `zValidator` (already wired) | All candidate routes already use `updateCandidateSchema` — just extend it |
+| Bullet-list rendering | Custom tokenizer | CSS `whitespace-pre-line` or split on `\n` | Simple text with newlines is sufficient for RANK-03 |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Test Helper Column Drift
+
+**What goes wrong:** New columns exist in production schema but are absent from the hardcoded `CREATE TABLE` in `tests/helpers/db.ts`. Tests pass structurally but new-column values are lost.
+**Why it happens:** The test helper duplicates the schema in raw SQL, not via Drizzle. There is no automated sync.
+**How to avoid:** Update `tests/helpers/db.ts` immediately after editing `schema.ts`, in the same commit wave.
+**Warning signs:** `candidate.pros` returns `undefined` in service tests even after saving a value.
+
+### Pitfall 2: Missing Explicit Column in Select Projection
+
+**What goes wrong:** `getThreadWithCandidates` uses `.select({ id: threadCandidates.id, ... })` — an explicit map. New columns are silently excluded.
+**Why it happens:** Drizzle's explicit projection doesn't automatically include newly-added columns.
+**How to avoid:** Search for every `.select({` that references `threadCandidates` and add `pros` and `cons`.
+**Warning signs:** API returns candidate without `pros`/`cons` fields even though they're saved in DB.
+
+### Pitfall 3: updateCandidate Service Type Mismatch
+
+**What goes wrong:** `updateCandidate` in `thread.service.ts` has a hardcoded `Partial<{ name, weightGrams, ... }>` type rather than using the Zod-inferred type. New fields must be manually added to this inline type.
+**Why it happens:** The function was written with an inline type, not `UpdateCandidate`.
+**How to avoid:** Add `pros: string` and `cons: string` to the `Partial<{...}>` inline type in `updateCandidate`.
+**Warning signs:** TypeScript error when trying to set `pros`/`cons` in the `.set({...data})` call.
+
+### Pitfall 4: CandidateCard Prop Not Threaded Through Call Sites
+
+**What goes wrong:** `CandidateCard` receives new `pros`/`cons` props, but the parent component (the thread detail page / candidate list) doesn't pass them.
+**Why it happens:** Adding props to a component doesn't update callers.
+**How to avoid:** Search for all `<CandidateCard` usages and add the new prop.
+**Warning signs:** Indicator never shows even when pros/cons data is present.
+
+---
+
+## Code Examples
+
+### Migration SQL (Generated Output Shape)
+
+```sql
+-- Expected output of bun run db:generate
+-- drizzle/000X_<tag>.sql
+ALTER TABLE `thread_candidates` ADD `pros` text;
+ALTER TABLE `thread_candidates` ADD `cons` text;
+```
+
+SQLite supports `ADD COLUMN` for nullable columns without a default. Confirmed by existing migration pattern (`0003_misty_mongu.sql` uses `ALTER TABLE setup_items ADD classification text DEFAULT 'base' NOT NULL`).
+
+### Service: createCandidate Values
+
+```typescript
+// Source: src/server/services/thread.service.ts
+return db
+  .insert(threadCandidates)
+  .values({
+    threadId,
+    name: data.name,
+    // ... existing fields ...
+    pros: data.pros ?? null,   // ADD
+    cons: data.cons ?? null,   // ADD
+  })
+  .returning()
+  .get();
+```
+
+### Service: updateCandidate Inline Type
+
+```typescript
+// Source: src/server/services/thread.service.ts
+export function updateCandidate(
+  db: Db = prodDb,
+  candidateId: number,
+  data: Partial<{
+    name: string;
+    weightGrams: number;
+    priceCents: number;
+    categoryId: number;
+    notes: string;
+    productUrl: string;
+    imageFilename: string;
+    status: "researching" | "ordered" | "arrived";
+    pros: string;   // ADD
+    cons: string;   // ADD
+  }>,
+) { ... }
+```
+
+### Hook: CandidateResponse Interface
+
+```typescript
+// Source: src/client/hooks/useCandidates.ts
+interface CandidateResponse {
+  id: number;
+  // ... existing ...
+  pros: string | null;   // ADD
+  cons: string | null;   // ADD
+}
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | Notes |
+|--------------|------------------|-------|
+| Manual SQL migrations | Drizzle-kit generate + push | Already established — 4 migrations in project |
+| `notes` as freeform text | `pros`/`cons` as separate nullable TEXT columns | Matches how existing `notes` field works; no special type |
+
+**Not applicable in this phase:**
+- No new libraries
+- No breaking API changes (all new fields are optional)
+- Existing candidates will have `pros = null` and `cons = null` after migration — no backfill needed
+
+---
+
+## Open Questions
+
+1. **Bullet list rendering in CandidateCard**
+   - What we know: RANK-03 says "displayed as bullet lists"
+   - What's unclear: The card currently shows the pros/cons indicator; does the card need to render the actual bullets, or does that happen elsewhere (e.g., a tooltip, expanded state, or comparison view in Phase 12)?
+   - Recommendation: Phase 10 success criteria only requires "visual indicator when a candidate has pros or cons entered." Full bullet rendering can be deferred to Phase 12 (Comparison View) or Phase 11. The form's edit view can display raw textarea text.
+
+2. **Maximum text length**
+   - What we know: SQLite TEXT has no practical length limit; the existing `notes` field has no validation constraint
+   - What's unclear: Should pros/cons have a max length?
+   - Recommendation: Omit length constraint to stay consistent with the `notes` field. Add if user feedback indicates issues.
+
+---
+
+## Validation Architecture
+
+`workflow.nyquist_validation` is `true` in `.planning/config.json`.
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | Bun test runner (built-in) |
+| Config file | None — `bun test` discovers `tests/**/*.test.ts` |
+| Quick run command | `bun test tests/services/thread.service.test.ts` |
+| Full suite command | `bun test` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| RANK-03 | `createCandidate` stores pros/cons and returns them | unit | `bun test tests/services/thread.service.test.ts` | Extend existing |
+| RANK-03 | `updateCandidate` can set/clear pros and cons | unit | `bun test tests/services/thread.service.test.ts` | Extend existing |
+| RANK-03 | `getThreadWithCandidates` returns pros/cons on each candidate | unit | `bun test tests/services/thread.service.test.ts` | Extend existing |
+| RANK-03 | `PUT /api/threads/:id/candidates/:id` accepts pros/cons in body | route | `bun test tests/routes/threads.test.ts` | Extend existing |
+| RANK-03 | All existing tests pass (no column drift) | regression | `bun test` | Existing ✅ |
+
+### 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
+
+No new test files need to be created. All tests are extensions of existing files:
+- `tests/services/thread.service.test.ts` — add `pros`/`cons` test cases to existing `describe("createCandidate")` and `describe("updateCandidate")` blocks
+- `tests/routes/threads.test.ts` — add a test case to existing `PUT` candidate describe block
+
+None — existing test infrastructure covers all phase requirements (as extensions).
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+
+- Direct code inspection: `src/db/schema.ts` — current `threadCandidates` column layout
+- Direct code inspection: `tests/helpers/db.ts` — `CREATE TABLE thread_candidates` raw SQL
+- Direct code inspection: `src/server/services/thread.service.ts` — `createCandidate`, `updateCandidate`, `getThreadWithCandidates`
+- Direct code inspection: `src/shared/schemas.ts` — `createCandidateSchema`, `updateCandidateSchema`
+- Direct code inspection: `src/client/components/CandidateForm.tsx` — form structure and payload
+- Direct code inspection: `src/client/components/CandidateCard.tsx` — props interface and badge rendering
+- Direct code inspection: `src/client/hooks/useCandidates.ts` — `CandidateResponse` interface
+- Direct code inspection: `drizzle/0003_misty_mongu.sql` — ALTER TABLE migration pattern
+- Direct code inspection: `CLAUDE.md` — explicit test-helper sync requirement
+
+### Secondary (MEDIUM confidence)
+
+- SQLite docs: `ALTER TABLE … ADD COLUMN` supports nullable columns without default — verified by existing migration pattern in project
+
+### Tertiary (LOW confidence)
+
+- None
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — no new libraries; all tooling already in use
+- Architecture: HIGH — full codebase read confirms exact ladder; no ambiguity
+- Pitfalls: HIGH — CLAUDE.md explicitly calls out test helper drift; column projection issue confirmed by reading service code
+
+**Research date:** 2026-03-16
+**Valid until:** 2026-06-16 (stable stack — 90 days)

.planning/phases/10-schema-foundation-pros-cons-fields/10-VALIDATION.md

@@ -0,0 +1,78 @@
+---
+phase: 10
+slug: schema-foundation-pros-cons-fields
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-16
+---
+
+# Phase 10 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bun test runner (built-in) |
+| **Config file** | none — `bun test` discovers `tests/**/*.test.ts` |
+| **Quick run command** | `bun test tests/services/thread.service.test.ts` |
+| **Full suite command** | `bun test` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun test tests/services/thread.service.test.ts`
+- **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 |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 10-01-01 | 01 | 1 | RANK-03 | unit | `bun test tests/services/thread.service.test.ts` | Extend existing | ⬜ pending |
+| 10-01-02 | 01 | 1 | RANK-03 | unit | `bun test tests/services/thread.service.test.ts` | Extend existing | ⬜ pending |
+| 10-01-03 | 01 | 1 | RANK-03 | unit | `bun test tests/services/thread.service.test.ts` | Extend existing | ⬜ pending |
+| 10-01-04 | 01 | 1 | RANK-03 | route | `bun test tests/routes/threads.test.ts` | Extend existing | ⬜ pending |
+| 10-01-05 | 01 | 1 | RANK-03 | regression | `bun test` | Existing ✅ | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+Existing infrastructure covers all phase requirements. All tests are extensions of existing files:
+- `tests/services/thread.service.test.ts` — add `pros`/`cons` test cases to existing describe blocks
+- `tests/routes/threads.test.ts` — add test case to existing PUT candidate describe block
+
+*No new test files or framework installs required.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| CandidateCard shows visual indicator when pros/cons present | RANK-03 | UI rendering verification | 1. Create thread with candidate 2. Add pros text 3. Verify indicator badge appears on card |
+
+---
+
+## 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/10-schema-foundation-pros-cons-fields/10-VERIFICATION.md

@@ -0,0 +1,104 @@
+---
+phase: 10-schema-foundation-pros-cons-fields
+verified: 2026-03-16T21:00:00Z
+status: passed
+score: 4/4 must-haves verified
+re_verification: false
+---
+
+# Phase 10: Schema Foundation Pros/Cons Fields Verification Report
+
+**Phase Goal:** Candidates can be annotated with pros and cons, and the database is ready for ranking
+**Verified:** 2026-03-16T21:00:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth                                                                                     | Status     | Evidence                                                                                                                                              |
+| --- | ----------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | User can open a candidate edit form and see pros and cons text fields                    | VERIFIED   | `CandidateForm.tsx` lines 250-284: two textarea elements with `id="candidate-pros"` and `id="candidate-cons"`, pre-filled via `candidate.pros ?? ""` in edit useEffect |
+| 2   | User can save pros and cons text; the text persists across page refreshes                | VERIFIED   | Form payload sends `pros: form.pros.trim() || undefined` to API; service stores `data.pros ?? null` in SQLite; migration `0004_soft_synch.sql` adds columns to live DB |
+| 3   | CandidateCard shows a visual indicator when a candidate has pros or cons entered         | VERIFIED   | `CandidateCard.tsx` line 181-185: `{(pros || cons) && <span ...bg-purple-50 text-purple-700...>+/- Notes</span>}` renders conditionally                |
+| 4   | All existing tests pass after the schema migration (no column drift in test helper)      | VERIFIED   | `bun test tests/services/thread.service.test.ts` — 28 pass, 0 fail; test helper mirrors `pros TEXT, cons TEXT` columns at lines 58-59                 |
+
+**Score:** 4/4 truths verified
+
+---
+
+### Required Artifacts
+
+| Artifact                                             | Expected                                                           | Status   | Details                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
+| `src/db/schema.ts`                                   | pros and cons nullable TEXT columns on threadCandidates            | VERIFIED | Lines 62-63: `pros: text("pros"),` and `cons: text("cons"),` present after `status` column               |
+| `tests/helpers/db.ts`                                | Mirrored pros/cons columns in test DB CREATE TABLE                 | VERIFIED | Lines 58-59: `pros TEXT,` and `cons TEXT,` present in `CREATE TABLE thread_candidates`                   |
+| `src/server/services/thread.service.ts`              | pros/cons in createCandidate, updateCandidate, getThreadWithCandidates | VERIFIED | createCandidate lines 156-157; updateCandidate Partial type lines 175-176; getThreadWithCandidates select lines 76-77 |
+| `src/shared/schemas.ts`                              | pros and cons optional string fields in createCandidateSchema      | VERIFIED | Lines 56-57: `pros: z.string().optional(),` and `cons: z.string().optional(),`; updateCandidateSchema inherits via `.partial()` |
+| `src/client/components/CandidateForm.tsx`            | Pros and Cons textarea inputs in candidate form                    | VERIFIED | Lines 250-284: two labeled textareas with ids `candidate-pros` and `candidate-cons`; FormData interface lines 22-23; INITIAL_FORM lines 34-35; pre-fill lines 68-69; payload lines 119-120 |
+| `src/client/components/CandidateCard.tsx`            | Visual indicator badge when pros or cons are present               | VERIFIED | Props interface lines 21-22: `pros?: string | null; cons?: string | null;`; destructured at line 38-39; badge at lines 181-185 using `bg-purple-50 text-purple-700` |
+| `tests/services/thread.service.test.ts`              | Tests for pros/cons in create, update, and get operations          | VERIFIED | 4 new test cases: "stores and returns pros and cons" (line 152), "returns null for pros and cons when not provided" (line 165), "can set and clear pros and cons" (line 200), "includes pros and cons on each candidate" (line 113) |
+
+---
+
+### Key Link Verification
+
+| From                                | To                                     | Via                                           | Status   | Details                                                                                                              |
+| ----------------------------------- | -------------------------------------- | --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `src/db/schema.ts`                  | `tests/helpers/db.ts`                  | Manual column mirroring in CREATE TABLE        | VERIFIED | `pros TEXT` and `cons TEXT` present in both locations; test helper lines 58-59 match schema lines 62-63             |
+| `src/shared/schemas.ts`             | `src/server/services/thread.service.ts` | Zod-inferred CreateCandidate type used in service | VERIFIED | Service imports `CreateCandidate` from `../../shared/types.ts` (line 9); `pros` and `cons` flow through the type into `createCandidate` and `updateCandidate` |
+| `src/server/services/thread.service.ts` | `src/client/hooks/useCandidates.ts` | API JSON response includes pros/cons fields    | VERIFIED | `getThreadWithCandidates` select projection explicitly includes `pros: threadCandidates.pros` and `cons: threadCandidates.cons`; `CandidateResponse` interface in hook declares `pros: string | null; cons: string | null;` |
+| `src/client/hooks/useCandidates.ts` | `src/client/components/CandidateForm.tsx` | CandidateResponse type drives form pre-fill  | VERIFIED | `CandidateForm.tsx` uses `useThread` which returns candidates; pre-fill useEffect accesses `candidate.pros` and `candidate.cons` at lines 68-69 |
+| `src/client/routes/threads/$threadId.tsx` | `src/client/components/CandidateCard.tsx` | Props threaded from candidate data to card | VERIFIED | Lines 156-157 in thread route: `pros={candidate.pros}` and `cons={candidate.cons}` passed to `<CandidateCard>` |
+
+---
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description                                                       | Status    | Evidence                                                                                                              |
+| ----------- | ----------- | ----------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| RANK-03     | 10-01-PLAN  | User can add pros and cons text per candidate displayed as bullet lists | SATISFIED | Pros/cons fields wired end-to-end: DB columns, migration, service, Zod schema, React form textareas, CandidateCard badge. REQUIREMENTS.md marks it `[x]` at line 21. |
+
+Note: The requirement description says "displayed as bullet lists" — the form stores multi-line text and the card shows a "+/- Notes" badge indicator. The text is stored as-is (one entry per line convention per plan instructions) but is not rendered as an explicit `<ul>` bullet list. This is a visual rendering concern suitable for human verification, but the data model and edit UI fully support it.
+
+**Orphaned requirements check:** REQUIREMENTS.md traceability table maps only RANK-03 to Phase 10. No additional requirements are assigned to this phase. No orphaned requirements.
+
+---
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+| ---- | ---- | ------- | -------- | ------ |
+| None detected | — | — | — | — |
+
+Scanned all 9 modified files for TODO/FIXME/placeholder comments, empty implementations, and console.log-only handlers. None found. The `pros: form.pros.trim() || undefined` pattern in `handleSubmit` correctly sends `undefined` (omitting the field) when empty, allowing the server to store `null` — this is intentional, not a stub.
+
+---
+
+### Human Verification Required
+
+#### 1. Pros/Cons Text Renders Usably in Edit Form
+
+**Test:** Open a thread, click "Add Candidate", observe the form. Scroll past Notes field — two textareas labeled "Pros" and "Cons" with placeholder "One pro per line..." and "One con per line..." should appear. Enter multi-line text in each, save, re-open the candidate, and confirm text pre-fills correctly.
+**Expected:** Text persists across saves and page refreshes; form pre-fills with saved content in edit mode.
+**Why human:** Requires a running browser with API connectivity to confirm round-trip persistence.
+
+#### 2. CandidateCard Badge Visibility
+
+**Test:** With a candidate that has pros or cons text, view the thread candidate grid. The card should show a purple "+/- Notes" badge alongside weight/price/status badges. A candidate without pros or cons should NOT show the badge.
+**Expected:** Badge appears conditionally; absent when both fields are null/empty.
+**Why human:** Requires browser rendering to verify visual appearance and conditional display.
+
+---
+
+### Gaps Summary
+
+No gaps found. All four observable truths are fully verified. Every artifact exists, is substantive (not a stub), and is properly wired end-to-end. The database migration (`drizzle/0004_soft_synch.sql`) is present and correct. All 28 service tests pass (24 pre-existing + 4 new). The three task commits (719f708, 7a64a18, 4f2aefe) are confirmed in the git log.
+
+RANK-03 is satisfied: pros and cons fields exist in the database, flow through the service layer with full CRUD support, are accepted by Zod validation, are exposed in the API response type, are editable via textarea inputs in `CandidateForm`, pre-fill correctly in edit mode, are sent in the submit payload, and surface as a purple "+/- Notes" visual indicator on `CandidateCard` when either field has content.
+
+---
+
+_Verified: 2026-03-16T21:00:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/10-schema-foundation-pros-cons-fields/deferred-items.md

@@ -0,0 +1,13 @@
+# Deferred Items
+
+## Pre-existing Lint Violations (Out of Scope for 10-01)
+
+These Biome lint/format errors existed before phase 10-01 and are not caused by any changes in this plan. They should be addressed in a separate cleanup task.
+
+- `src/client/components/WeightSummaryCard.tsx` - format violation (line length)
+- `src/client/routes/collection/index.tsx` - organizeImports, format violations
+- `src/client/routes/index.tsx` - organizeImports, format violations
+- `src/client/routes/setups/$setupId.tsx` - organizeImports violations
+- `.obsidian/workspace.json` - format violations (IDE file, should be excluded from Biome)
+
+Discovered during: Task 2 lint verification

.planning/phases/11-candidate-ranking/11-01-PLAN.md

@@ -0,0 +1,285 @@
+---
+phase: 11-candidate-ranking
+plan: "01"
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/db/schema.ts
+  - tests/helpers/db.ts
+  - src/server/services/thread.service.ts
+  - src/server/routes/threads.ts
+  - src/shared/schemas.ts
+  - src/shared/types.ts
+  - tests/services/thread.service.test.ts
+  - tests/routes/threads.test.ts
+autonomous: true
+requirements: [RANK-01, RANK-04, RANK-05]
+
+must_haves:
+  truths:
+    - "Candidates returned from getThreadWithCandidates are ordered by sort_order ascending"
+    - "Calling reorderCandidates with a new ID sequence updates sort_order values to match that sequence"
+    - "PATCH /api/threads/:id/candidates/reorder returns 200 and persists new order"
+    - "reorderCandidates returns error when thread status is not active"
+    - "New candidates created via createCandidate are appended to end of rank (highest sort_order + 1000)"
+  artifacts:
+    - path: "src/db/schema.ts"
+      provides: "sortOrder REAL column on threadCandidates"
+      contains: "sortOrder"
+    - path: "src/shared/schemas.ts"
+      provides: "reorderCandidatesSchema Zod validator"
+      contains: "reorderCandidatesSchema"
+    - path: "src/shared/types.ts"
+      provides: "ReorderCandidates type"
+      contains: "ReorderCandidates"
+    - path: "src/server/services/thread.service.ts"
+      provides: "reorderCandidates function + ORDER BY sort_order + createCandidate sort_order appending"
+      exports: ["reorderCandidates"]
+    - path: "src/server/routes/threads.ts"
+      provides: "PATCH /:id/candidates/reorder endpoint"
+      contains: "candidates/reorder"
+    - path: "tests/helpers/db.ts"
+      provides: "sort_order column in CREATE TABLE thread_candidates"
+      contains: "sort_order"
+  key_links:
+    - from: "src/server/routes/threads.ts"
+      to: "src/server/services/thread.service.ts"
+      via: "reorderCandidates(db, threadId, orderedIds)"
+      pattern: "reorderCandidates"
+    - from: "src/server/routes/threads.ts"
+      to: "src/shared/schemas.ts"
+      via: "zValidator with reorderCandidatesSchema"
+      pattern: "reorderCandidatesSchema"
+    - from: "src/server/services/thread.service.ts"
+      to: "src/db/schema.ts"
+      via: "threadCandidates.sortOrder in ORDER BY and UPDATE"
+      pattern: "threadCandidates\\.sortOrder"
+---
+
+<objective>
+Add sort_order column to thread_candidates, implement reorder service and API endpoint, and update candidate ordering throughout the backend.
+
+Purpose: Provides the persistence layer for drag-to-reorder ranking (RANK-01, RANK-04) and enforces the resolved-thread guard (RANK-05). The frontend plan (11-02) depends on this.
+Output: Working PATCH /api/threads/:id/candidates/reorder endpoint, sort_order-based ordering in getThreadWithCandidates, sort_order appending in createCandidate, full test coverage.
+</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/11-candidate-ranking/11-CONTEXT.md
+@.planning/phases/11-candidate-ranking/11-RESEARCH.md
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/db/schema.ts (threadCandidates table — add sortOrder here):
+```typescript
+export const threadCandidates = sqliteTable("thread_candidates", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  threadId: integer("thread_id").notNull().references(() => threads.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  weightGrams: real("weight_grams"),
+  priceCents: integer("price_cents"),
+  categoryId: integer("category_id").notNull().references(() => categories.id),
+  notes: text("notes"),
+  productUrl: text("product_url"),
+  imageFilename: text("image_filename"),
+  status: text("status").notNull().default("researching"),
+  pros: text("pros"),
+  cons: text("cons"),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
+});
+```
+
+From src/server/services/thread.service.ts (key functions to modify):
+```typescript
+type Db = typeof prodDb;
+export function getThreadWithCandidates(db: Db, threadId: number) // add .orderBy(threadCandidates.sortOrder)
+export function createCandidate(db: Db, threadId: number, data: ...) // add sort_order = max + 1000
+export function resolveThread(db: Db, threadId: number, candidateId: number) // existing status check pattern to reuse
+```
+
+From src/shared/schemas.ts (existing patterns):
+```typescript
+export const createCandidateSchema = z.object({ ... });
+export const resolveThreadSchema = z.object({ candidateId: z.number().int().positive() });
+```
+
+From src/shared/types.ts (add new type):
+```typescript
+export type ResolveThread = z.infer<typeof resolveThreadSchema>;
+// Add: export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
+```
+
+From src/server/routes/threads.ts (route pattern):
+```typescript
+type Env = { Variables: { db?: any } };
+const app = new Hono<Env>();
+// Pattern: app.post("/:id/resolve", zValidator("json", resolveThreadSchema), (c) => { ... });
+```
+
+From src/client/lib/api.ts:
+```typescript
+export async function apiPatch<T>(url: string, body: unknown): Promise<T>;
+```
+
+From tests/helpers/db.ts (thread_candidates CREATE TABLE — add sort_order):
+```sql
+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',
+  pros TEXT,
+  cons TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Schema, migration, service layer, and tests for sort_order + reorder</name>
+  <files>src/db/schema.ts, tests/helpers/db.ts, src/server/services/thread.service.ts, src/shared/schemas.ts, src/shared/types.ts, tests/services/thread.service.test.ts</files>
+  <behavior>
+    - Test: getThreadWithCandidates returns candidates ordered by sort_order ascending (create 3 candidates with different sort_orders, verify order)
+    - Test: reorderCandidates(db, threadId, [id3, id1, id2]) updates sort_order so querying returns [id3, id1, id2]
+    - Test: reorderCandidates returns { success: false, error } when thread status is "resolved"
+    - Test: createCandidate assigns sort_order = max existing sort_order + 1000 (first candidate gets 1000, second gets 2000)
+    - Test: reorderCandidates returns { success: false } when thread does not exist
+  </behavior>
+  <action>
+    1. **Schema** (`src/db/schema.ts`): Add `sortOrder: real("sort_order").notNull().default(0)` to the `threadCandidates` table definition.
+
+    2. **Migration**: Run `bun run db:generate` to produce the Drizzle migration SQL. Then apply it with `bun run db:push`. After applying, run a data backfill to space existing candidates:
+       ```sql
+       UPDATE thread_candidates SET sort_order = (
+         SELECT (ROW_NUMBER() OVER (PARTITION BY thread_id ORDER BY created_at)) * 1000
+         FROM thread_candidates AS tc2 WHERE tc2.id = thread_candidates.id
+       );
+       ```
+       Execute this backfill via the Drizzle migration custom SQL or a small script.
+
+    3. **Test helper** (`tests/helpers/db.ts`): Add `sort_order REAL NOT NULL DEFAULT 0` to the CREATE TABLE thread_candidates statement (after the `cons TEXT` line, before `created_at`).
+
+    4. **Zod schema** (`src/shared/schemas.ts`): Add:
+       ```typescript
+       export const reorderCandidatesSchema = z.object({
+         orderedIds: z.array(z.number().int().positive()).min(1),
+       });
+       ```
+
+    5. **Types** (`src/shared/types.ts`): Add import of `reorderCandidatesSchema` and:
+       ```typescript
+       export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
+       ```
+
+    6. **Service** (`src/server/services/thread.service.ts`):
+       - In `getThreadWithCandidates`: Add `.orderBy(threadCandidates.sortOrder)` to the candidateList query (after `.where()`).
+       - In `createCandidate`: Before inserting, query `MAX(sort_order)` from threadCandidates where threadId matches. Set `sortOrder: (maxRow?.maxOrder ?? 0) + 1000` in the `.values()` call. Use `sql<number>` template for the MAX query.
+       - Add new exported function `reorderCandidates(db, threadId, orderedIds)`:
+         - Wrap in `db.transaction()`.
+         - Verify thread exists and `status === "active"` (return `{ success: false, error: "Thread not active" }` if not).
+         - Loop through `orderedIds`, UPDATE each candidate's `sortOrder` to `(index + 1) * 1000`.
+         - Return `{ success: true }`.
+
+    7. **Tests** (`tests/services/thread.service.test.ts`):
+       - Import `reorderCandidates` from the service.
+       - Add a new `describe("reorderCandidates", () => { ... })` block with the behavior tests listed above.
+       - Add test for `getThreadWithCandidates` ordering by sort_order (create candidates, set different sort_orders manually via db, verify order).
+       - Add test for `createCandidate` sort_order appending.
+  </action>
+  <verify>
+    <automated>bun test tests/services/thread.service.test.ts</automated>
+  </verify>
+  <done>All existing thread service tests pass (28+) plus 5+ new tests for reorderCandidates, sort_order ordering, sort_order appending. sortOrder column exists in schema with REAL type.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: PATCH reorder route + route tests</name>
+  <files>src/server/routes/threads.ts, tests/routes/threads.test.ts</files>
+  <behavior>
+    - Test: PATCH /api/threads/:id/candidates/reorder with valid orderedIds returns 200 + { success: true }
+    - Test: After PATCH reorder, GET /api/threads/:id returns candidates in the new order
+    - Test: PATCH /api/threads/:id/candidates/reorder on a resolved thread returns 400
+    - Test: PATCH /api/threads/:id/candidates/reorder with empty body returns 400 (Zod validation)
+  </behavior>
+  <action>
+    1. **Route** (`src/server/routes/threads.ts`):
+       - Import `reorderCandidatesSchema` from `../../shared/schemas.ts`.
+       - Import `reorderCandidates` from `../services/thread.service.ts`.
+       - Add PATCH route BEFORE the resolution route (to avoid param conflicts):
+         ```typescript
+         app.patch(
+           "/:id/candidates/reorder",
+           zValidator("json", reorderCandidatesSchema),
+           (c) => {
+             const db = c.get("db");
+             const threadId = Number(c.req.param("id"));
+             const { orderedIds } = c.req.valid("json");
+             const result = reorderCandidates(db, threadId, orderedIds);
+             if (!result.success) return c.json({ error: result.error }, 400);
+             return c.json({ success: true });
+           },
+         );
+         ```
+
+    2. **Route tests** (`tests/routes/threads.test.ts`):
+       - Add a new `describe("PATCH /api/threads/:id/candidates/reorder", () => { ... })` block.
+       - Test: Create a thread with 3 candidates via API, PATCH reorder with reversed IDs, GET thread and verify candidates array is in the new order.
+       - Test: Resolve a thread, then PATCH reorder returns 400.
+       - Test: PATCH with invalid body (empty orderedIds array or missing field) returns 400.
+  </action>
+  <verify>
+    <automated>bun test tests/routes/threads.test.ts</automated>
+  </verify>
+  <done>PATCH /api/threads/:id/candidates/reorder returns 200 on active thread + persists order. Returns 400 on resolved thread. All existing route tests still pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+```bash
+# Full test suite — all existing + new tests green
+bun test
+
+# Verify sort_order column exists in schema
+grep -n "sortOrder" src/db/schema.ts
+
+# Verify reorder endpoint registered
+grep -n "candidates/reorder" src/server/routes/threads.ts
+
+# Verify test helper updated
+grep -n "sort_order" tests/helpers/db.ts
+```
+</verification>
+
+<success_criteria>
+- sort_order REAL column added to threadCandidates schema and test helper
+- getThreadWithCandidates returns candidates sorted by sort_order ascending
+- createCandidate appends new candidates at max sort_order + 1000
+- reorderCandidates service function updates sort_order in transaction, rejects resolved threads
+- PATCH /api/threads/:id/candidates/reorder validated with Zod, returns 200/400 correctly
+- All existing tests pass with zero regressions + 8+ new tests
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/11-candidate-ranking/11-01-SUMMARY.md`
+</output>

.planning/phases/11-candidate-ranking/11-01-SUMMARY.md

@@ -0,0 +1,117 @@
+---
+phase: 11-candidate-ranking
+plan: "01"
+subsystem: database, api
+tags: [drizzle, sqlite, hono, zod, sort-order, reorder, candidates]
+
+# Dependency graph
+requires: []
+provides:
+  - sortOrder REAL column on threadCandidates with default 0
+  - reorderCandidates service function (transaction, active-only guard)
+  - PATCH /api/threads/:id/candidates/reorder endpoint with Zod validation
+  - getThreadWithCandidates returns candidates ordered by sort_order ASC
+  - createCandidate appends at max sort_order + 1000 (first=1000, second=2000)
+  - reorderCandidatesSchema Zod validator in shared/schemas.ts
+  - ReorderCandidates type in shared/types.ts
+affects: [11-02, frontend-drag-reorder, candidate-lists]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Append-at-end sort_order: query MAX(sort_order), insert at +1000 gap"
+    - "Reorder transaction pattern: verify active thread, loop UPDATE sort_order = (index+1)*1000"
+    - "Active-only guard in reorder: return { success: false, error } when thread status != active"
+
+key-files:
+  created:
+    - drizzle/0005_clear_micromax.sql
+    - drizzle/meta/0005_snapshot.json
+  modified:
+    - src/db/schema.ts
+    - tests/helpers/db.ts
+    - src/shared/schemas.ts
+    - src/shared/types.ts
+    - src/server/services/thread.service.ts
+    - src/server/routes/threads.ts
+    - tests/services/thread.service.test.ts
+    - tests/routes/threads.test.ts
+
+key-decisions:
+  - "sortOrder uses REAL type (not INTEGER) to allow fractional values for future midpoint insertions without bulk rewrites"
+  - "First candidate gets sort_order=1000, subsequent at +1000 gaps, giving room for future insertions"
+  - "reorderCandidates uses (index+1)*1000 to space out assignments and reset gaps after each reorder"
+  - "Applied migration directly via sqlite3 CLI + data backfill instead of db:push (avoided data-loss warning on existing rows)"
+
+patterns-established:
+  - "Reorder endpoint pattern: PATCH /:id/candidates/reorder, Zod validates orderedIds array, service returns {success, error}"
+  - "Service active-only guard: check thread.status !== 'active', return {success: false, error: 'Thread not active'}"
+
+requirements-completed: [RANK-01, RANK-04, RANK-05]
+
+# Metrics
+duration: 4min
+completed: 2026-03-16
+---
+
+# Phase 11 Plan 01: Candidate Ranking Backend Summary
+
+**sortOrder REAL column, reorderCandidates transaction service, and PATCH /api/threads/:id/candidates/reorder endpoint with active-thread guard**
+
+## Performance
+
+- **Duration:** ~4 min
+- **Started:** 2026-03-16T21:19:26Z
+- **Completed:** 2026-03-16T21:22:46Z
+- **Tasks:** 2 of 2
+- **Files modified:** 8
+
+## Accomplishments
+- Added sortOrder REAL column to threadCandidates with 1000-gap append strategy
+- Implemented reorderCandidates service with transaction and active-thread guard
+- Added PATCH /api/threads/:id/candidates/reorder endpoint with Zod validation
+- getThreadWithCandidates now orders candidates by sort_order ASC
+- 10 new tests (5 service + 5 route) added; all 135 tests pass with zero regressions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Schema, migration, service layer, and tests for sort_order + reorder** - `f01d71d` (feat)
+2. **Task 2: PATCH reorder route + route tests** - `d6acfcb` (feat)
+
+_Note: TDD tasks each committed after GREEN phase._
+
+## Files Created/Modified
+- `src/db/schema.ts` - Added sortOrder REAL column to threadCandidates
+- `tests/helpers/db.ts` - Added sort_order REAL NOT NULL DEFAULT 0 to CREATE TABLE
+- `src/shared/schemas.ts` - Added reorderCandidatesSchema
+- `src/shared/types.ts` - Added ReorderCandidates type, imported reorderCandidatesSchema
+- `src/server/services/thread.service.ts` - Added reorderCandidates, updated createCandidate + getThreadWithCandidates
+- `src/server/routes/threads.ts` - Added PATCH /:id/candidates/reorder route
+- `tests/services/thread.service.test.ts` - Added 5 new tests for sort_order behavior
+- `tests/routes/threads.test.ts` - Added 5 new route tests for reorder endpoint
+- `drizzle/0005_clear_micromax.sql` - Generated migration SQL for sort_order column
+- `drizzle/meta/0005_snapshot.json` - Drizzle schema snapshot
+
+## Decisions Made
+- Used REAL type for sort_order (not INTEGER) to allow fractional values for future midpoint insertions
+- 1000-gap strategy: first candidate = 1000, each subsequent += 1000; reorder resets to (index+1)*1000
+- Applied migration directly via sqlite3 CLI to avoid Drizzle's data-loss warning on existing rows (db had 2 rows; column has DEFAULT 0 so no actual data loss)
+- Backfilled existing candidates with ROW_NUMBER * 1000 per thread to give proper initial ordering
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- `bun run db:push` showed data-loss warning for adding NOT NULL column to existing rows. Applied the migration directly via sqlite3 CLI instead (`ALTER TABLE thread_candidates ADD COLUMN sort_order REAL NOT NULL DEFAULT 0`). The column has DEFAULT 0 so no actual data loss; existing rows got 0 then were backfilled to proper 1000-gap values.
+
+## Next Phase Readiness
+- Backend reorder API fully operational; frontend drag-to-reorder (11-02) can now consume PATCH /api/threads/:id/candidates/reorder
+- sort_order values returned in getThreadWithCandidates response, available to frontend for drag state initialization
+
+---
+*Phase: 11-candidate-ranking*
+*Completed: 2026-03-16*

.planning/phases/11-candidate-ranking/11-02-PLAN.md

@@ -0,0 +1,378 @@
+---
+phase: 11-candidate-ranking
+plan: "02"
+type: execute
+wave: 2
+depends_on: ["11-01"]
+files_modified:
+  - src/client/stores/uiStore.ts
+  - src/client/hooks/useCandidates.ts
+  - src/client/components/CandidateListItem.tsx
+  - src/client/components/CandidateCard.tsx
+  - src/client/routes/threads/$threadId.tsx
+autonomous: false
+requirements: [RANK-01, RANK-02, RANK-04, RANK-05]
+
+must_haves:
+  truths:
+    - "User can drag a candidate card to a new position in list view and it persists after page refresh"
+    - "Top 3 candidates display gold, silver, and bronze medal badges"
+    - "Rank badges appear in both list view and grid view"
+    - "Drag handles are hidden and drag is disabled on resolved threads"
+    - "Rank badges remain visible on resolved threads"
+    - "User can toggle between list and grid view"
+    - "List view is the default view"
+  artifacts:
+    - path: "src/client/components/CandidateListItem.tsx"
+      provides: "Horizontal list-view candidate card with drag handle and rank badge"
+      min_lines: 60
+    - path: "src/client/routes/threads/$threadId.tsx"
+      provides: "View toggle + Reorder.Group wrapping candidates + tempItems flicker prevention"
+      contains: "Reorder.Group"
+    - path: "src/client/hooks/useCandidates.ts"
+      provides: "useReorderCandidates mutation hook"
+      contains: "useReorderCandidates"
+    - path: "src/client/stores/uiStore.ts"
+      provides: "candidateViewMode state"
+      contains: "candidateViewMode"
+    - path: "src/client/components/CandidateCard.tsx"
+      provides: "Rank badge on grid-view cards"
+      contains: "RankBadge"
+  key_links:
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/hooks/useCandidates.ts"
+      via: "useReorderCandidates(threadId)"
+      pattern: "useReorderCandidates"
+    - from: "src/client/hooks/useCandidates.ts"
+      to: "/api/threads/:id/candidates/reorder"
+      via: "apiPatch"
+      pattern: "apiPatch.*candidates/reorder"
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "framer-motion"
+      via: "Reorder.Group + Reorder.Item"
+      pattern: "Reorder\\.Group"
+    - from: "src/client/components/CandidateListItem.tsx"
+      to: "framer-motion"
+      via: "Reorder.Item + useDragControls"
+      pattern: "useDragControls"
+    - from: "src/client/stores/uiStore.ts"
+      to: "src/client/routes/threads/$threadId.tsx"
+      via: "candidateViewMode state"
+      pattern: "candidateViewMode"
+---
+
+<objective>
+Build the drag-to-reorder UI with list/grid view toggle, CandidateListItem component, framer-motion Reorder integration, rank badges, and resolved-thread guard.
+
+Purpose: Delivers the user-facing ranking experience: drag candidates to prioritize, see gold/silver/bronze medals, toggle between compact list and card grid views. All four RANK requirements are covered.
+Output: Working drag-to-reorder in list view, rank badges in both views, view toggle, resolved-thread readonly mode.
+</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/11-candidate-ranking/11-CONTEXT.md
+@.planning/phases/11-candidate-ranking/11-RESEARCH.md
+@.planning/phases/11-candidate-ranking/11-01-SUMMARY.md
+
+<interfaces>
+<!-- Interfaces created by Plan 01 that this plan depends on -->
+
+From src/shared/schemas.ts (created in 11-01):
+```typescript
+export const reorderCandidatesSchema = z.object({
+  orderedIds: z.array(z.number().int().positive()).min(1),
+});
+```
+
+From src/shared/types.ts (created in 11-01):
+```typescript
+export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
+```
+
+From src/server/services/thread.service.ts (modified in 11-01):
+```typescript
+export function reorderCandidates(db, threadId, orderedIds): { success: boolean; error?: string }
+// getThreadWithCandidates now returns candidates sorted by sort_order ascending
+// createCandidate now assigns sort_order = max + 1000 (appends to bottom)
+```
+
+API endpoint (created in 11-01):
+```
+PATCH /api/threads/:id/candidates/reorder
+Body: { orderedIds: number[] }
+Response: { success: true } | { error: string } (400)
+```
+
+From src/client/lib/api.ts:
+```typescript
+export async function apiPatch<T>(url: string, body: unknown): Promise<T>;
+```
+
+From src/client/hooks/useCandidates.ts (existing):
+```typescript
+interface CandidateResponse {
+  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";
+  pros: string | null; cons: string | null;
+  createdAt: string; updatedAt: string;
+}
+```
+
+From src/client/components/CandidateCard.tsx (existing props):
+```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: "researching" | "ordered" | "arrived";
+  onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
+  pros?: string | null; cons?: string | null;
+}
+```
+
+From src/client/stores/uiStore.ts (existing patterns):
+```typescript
+interface UIState {
+  // ... existing state
+  // Add: candidateViewMode: "list" | "grid"
+  // Add: setCandidateViewMode: (mode: "list" | "grid") => void
+}
+```
+
+From framer-motion (installed v12.37.0):
+```typescript
+import { Reorder, useDragControls } from "framer-motion";
+// Reorder.Group: axis="y", values={items}, onReorder={setItems}
+// Reorder.Item: value={item}, dragControls={controls}, dragListener={false}
+// useDragControls: controls.start(pointerEvent) on handle's onPointerDown
+```
+
+From lucide-react (confirmed available icons):
+- grip-vertical (drag handle)
+- medal (rank badge)
+- layout-list (list view toggle)
+- layout-grid (grid view toggle)
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: useReorderCandidates hook + uiStore view mode + CandidateListItem component</name>
+  <files>src/client/hooks/useCandidates.ts, src/client/stores/uiStore.ts, src/client/components/CandidateListItem.tsx</files>
+  <action>
+    1. **useReorderCandidates hook** (`src/client/hooks/useCandidates.ts`):
+       - Import `apiPatch` from `../lib/api`.
+       - Add new exported function:
+         ```typescript
+         export function useReorderCandidates(threadId: number) {
+           const queryClient = useQueryClient();
+           return useMutation({
+             mutationFn: (data: { orderedIds: number[] }) =>
+               apiPatch<{ success: boolean }>(
+                 `/api/threads/${threadId}/candidates/reorder`,
+                 data,
+               ),
+             onSettled: () => {
+               queryClient.invalidateQueries({ queryKey: ["threads", threadId] });
+             },
+           });
+         }
+         ```
+
+    2. **uiStore** (`src/client/stores/uiStore.ts`):
+       - Add to the UIState interface:
+         ```typescript
+         candidateViewMode: "list" | "grid";
+         setCandidateViewMode: (mode: "list" | "grid") => void;
+         ```
+       - Add to the create block:
+         ```typescript
+         candidateViewMode: "list",
+         setCandidateViewMode: (mode) => set({ candidateViewMode: mode }),
+         ```
+
+    3. **CandidateListItem** (`src/client/components/CandidateListItem.tsx`) — NEW FILE:
+       - Create a horizontal card component for list view.
+       - Import `{ Reorder, useDragControls }` from `framer-motion`.
+       - Import `LucideIcon` from `../lib/iconData`, formatters, hooks (useWeightUnit, useCurrency), useUIStore, StatusBadge.
+       - Props interface:
+         ```typescript
+         interface CandidateListItemProps {
+           candidate: CandidateWithCategory;  // The full candidate object from thread.candidates
+           rank: number;                      // 1-based position index
+           isActive: boolean;                 // thread.status === "active"
+           onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
+         }
+         ```
+         Where `CandidateWithCategory` is the candidate shape from `useThread` response (id, name, weightGrams, priceCents, categoryName, categoryIcon, imageFilename, productUrl, status, pros, cons, etc.). Define this type locally or reference the CandidateResponse + category fields.
+
+       - Use `useDragControls()` hook. Return a `Reorder.Item` with `value={candidate}` (the full candidate object, same reference used in Reorder.Group values), `dragControls={controls}`, `dragListener={false}`.
+
+       - Layout (horizontal card):
+         - Outer: `flex items-center gap-3 bg-white rounded-xl border border-gray-100 p-3 hover:border-gray-200 hover:shadow-sm transition-all group`
+         - LEFT: Drag handle (only if `isActive`): GripVertical icon (size 16), `onPointerDown={(e) => controls.start(e)}`, classes: `cursor-grab active:cursor-grabbing text-gray-300 hover:text-gray-500 touch-none shrink-0`
+         - RANK BADGE: Inline `RankBadge` component (see below). Shows medal icon for rank 1-3 with gold/silver/bronze colors. Returns null for rank > 3.
+         - IMAGE THUMBNAIL: 48x48 rounded-lg overflow-hidden shrink-0. If `imageFilename`, show `<img src="/uploads/${imageFilename}" />` with object-cover. Else show `LucideIcon` of `categoryIcon` (size 20) in gray on gray-50 background.
+         - NAME + BADGES: `flex-1 min-w-0` container.
+           - Name: `text-sm font-semibold text-gray-900 truncate`
+           - Badge row: `flex flex-wrap gap-1.5 mt-1` with weight (blue), price (green), category (gray + icon), StatusBadge, pros/cons badge (purple "+/- Notes").
+           - Use same badge pill classes as CandidateCard.
+         - ACTION BUTTONS (hover-reveal, right side): Winner (if isActive), Delete, External link (if productUrl). Use same click handlers as CandidateCard (openResolveDialog, openConfirmDeleteCandidate, openExternalLink from uiStore). Classes: `opacity-0 group-hover:opacity-100 transition-opacity` on a flex container.
+         - Clicking the card body (not handle or action buttons) opens the edit panel: wrap in a clickable area that calls `openCandidateEditPanel(candidate.id)`.
+
+       - **RankBadge** (inline helper or small component in same file):
+         ```typescript
+         const RANK_COLORS = ["#D4AF37", "#C0C0C0", "#CD7F32"]; // gold, silver, bronze
+         function RankBadge({ rank }: { rank: number }) {
+           if (rank > 3) return null;
+           return <LucideIcon name="medal" size={16} className="shrink-0" style={{ color: RANK_COLORS[rank - 1] }} />;
+         }
+         ```
+         Export `RankBadge` so it can be reused by CandidateCard in grid view.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -30</automated>
+  </verify>
+  <done>CandidateListItem.tsx created with drag handle, rank badge, horizontal layout. useReorderCandidates hook created. uiStore has candidateViewMode. RankBadge exported. Lint passes.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Thread detail page with view toggle, Reorder.Group, rank badges in grid view</name>
+  <files>src/client/routes/threads/$threadId.tsx, src/client/components/CandidateCard.tsx</files>
+  <action>
+    1. **CandidateCard rank badge** (`src/client/components/CandidateCard.tsx`):
+       - Import `RankBadge` from `./CandidateListItem` (or wherever it's exported).
+       - Add `rank?: number` to `CandidateCardProps`.
+       - In the card layout, add `{rank != null && <RankBadge rank={rank} />}` in the badge row (flex-wrap area), positioned as the first badge before weight/price.
+
+    2. **Thread detail page** (`src/client/routes/threads/$threadId.tsx`):
+       - Import `{ Reorder }` from `framer-motion`.
+       - Import `{ useState, useEffect }` from `react`.
+       - Import `CandidateListItem` from `../../components/CandidateListItem`.
+       - Import `useReorderCandidates` from `../../hooks/useCandidates`.
+       - Import `useUIStore` selector for `candidateViewMode` and `setCandidateViewMode`.
+       - Import `LucideIcon` (already imported).
+
+       - **View toggle** in the header area (after the "Add Candidate" button, or in the thread header row):
+         - Two icon buttons: LayoutList and LayoutGrid (from Lucide).
+         - Active button has `bg-gray-200 text-gray-900`, inactive has `text-gray-400 hover:text-gray-600`.
+         - `onClick` calls `setCandidateViewMode("list")` or `setCandidateViewMode("grid")`.
+         - Placed inline in a small toggle group: `flex items-center gap-1 bg-gray-100 rounded-lg p-0.5`
+
+       - **tempItems pattern** for flicker prevention:
+         ```typescript
+         const [tempItems, setTempItems] = useState<typeof thread.candidates | null>(null);
+         const displayItems = tempItems ?? thread.candidates;
+         // thread.candidates is already sorted by sort_order from server (11-01)
+         ```
+         Reset tempItems to null whenever `thread.candidates` reference changes (use useEffect if needed, or rely on onSettled clearing).
+
+       - **Reorder.Group** (list view, active threads only):
+         - When `candidateViewMode === "list"` AND candidates exist:
+           - If `isActive`: Wrap candidates in `<Reorder.Group axis="y" values={displayItems} onReorder={setTempItems} className="flex flex-col gap-2">`.
+             - Each candidate renders `<CandidateListItem key={candidate.id} candidate={candidate} rank={index + 1} isActive={isActive} onStatusChange={...} />`.
+             - On Reorder.Item `onDragEnd`, trigger the save. The save function:
+               ```typescript
+               function handleDragEnd() {
+                 if (!tempItems) return;
+                 reorderMutation.mutate(
+                   { orderedIds: tempItems.map((c) => c.id) },
+                   { onSettled: () => setTempItems(null) }
+                 );
+               }
+               ```
+               Attach this to `Reorder.Group` via a wrapper that uses `onPointerUp` or pass as prop to `CandidateListItem`. The cleanest approach: use framer-motion's `onDragEnd` prop on each `Reorder.Item` — when any item finishes dragging, if tempItems differs from server data, fire the mutation.
+           - If `!isActive` (resolved): Render the same `CandidateListItem` components but WITHOUT `Reorder.Group` — just a plain `<div className="flex flex-col gap-2">`. The `isActive={false}` prop hides drag handles. Rank badges remain visible per user decision.
+
+         - When `candidateViewMode === "grid"` AND candidates exist:
+           - Render the existing `<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">` with `CandidateCard` components.
+           - Pass `rank={index + 1}` to each CandidateCard so rank badges appear in grid view too.
+           - Both active and resolved threads use static grid (no drag in grid view per user decision).
+
+       - **Important framer-motion detail**: `Reorder.Group` `values` must be the same array reference as what you iterate. Use `displayItems` for both `values` and `.map()`. The `Reorder.Item` `value` must be the same object reference (not a copy). Since we use the full candidate object, `value={candidate}` where candidate comes from `displayItems.map(...)`.
+
+       - **Empty state**: Keep the existing empty state rendering for both views.
+
+       - **useEffect to clear tempItems**: When `thread.candidates` changes (new data from server), clear tempItems:
+         ```typescript
+         useEffect(() => {
+           setTempItems(null);
+         }, [thread?.candidates]);
+         ```
+         This ensures that when React Query refetches, tempItems is cleared and we render fresh server data.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -30</automated>
+  </verify>
+  <done>Thread detail page renders list/grid toggle. List view has drag-to-reorder via Reorder.Group with tempItems flicker prevention. Grid view shows rank badges. Resolved threads show static list/grid with rank badges but no drag handles. Lint passes.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Verify drag-to-reorder ranking experience</name>
+  <files>none</files>
+  <action>
+    Human verifies the complete drag-to-reorder candidate ranking with list/grid view toggle, rank badges (gold/silver/bronze), auto-save persistence, and resolved thread guard.
+  </action>
+  <what-built>Complete drag-to-reorder candidate ranking with list/grid view toggle, rank badges (gold/silver/bronze), auto-save persistence, and resolved thread guard.</what-built>
+  <how-to-verify>
+    1. Start dev servers: `bun run dev:client` and `bun run dev:server`
+    2. Navigate to an existing active thread with 3+ candidates (or create one)
+    3. Verify list view is the default (vertical stack of horizontal cards)
+    4. Verify drag handles (grip icon) appear on the left of each card
+    5. Drag a candidate to a new position — verify it moves smoothly with gap animation
+    6. Release — verify the new order persists (refresh the page to confirm)
+    7. Verify the top 3 candidates show gold, silver, bronze medal icons before their names
+    8. Toggle to grid view — verify rank badges also appear on grid cards
+    9. Toggle back to list view — verify drag still works
+    10. Navigate to a resolved thread — verify NO drag handles, but rank badges ARE visible
+    11. Verify candidates on resolved thread render in their ranked order (static)
+  </how-to-verify>
+  <verify>Human confirms all 11 verification steps pass</verify>
+  <done>All ranking features verified: drag reorder works, persists, shows rank badges in both views, disabled on resolved threads</done>
+  <resume-signal>Type "approved" or describe any issues</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+```bash
+# Full test suite green
+bun test
+
+# Verify all key files exist
+ls src/client/components/CandidateListItem.tsx
+grep -n "useReorderCandidates" src/client/hooks/useCandidates.ts
+grep -n "candidateViewMode" src/client/stores/uiStore.ts
+grep -n "Reorder.Group" src/client/routes/threads/\$threadId.tsx
+grep -n "RankBadge" src/client/components/CandidateCard.tsx
+
+# Lint clean
+bun run lint
+```
+</verification>
+
+<success_criteria>
+- List view shows horizontal cards with drag handles on active threads
+- Drag-to-reorder works via framer-motion Reorder.Group with grip handle
+- Order persists after page refresh via PATCH /api/threads/:id/candidates/reorder
+- tempItems pattern prevents React Query flicker
+- Top 3 candidates display gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) medal badges
+- Rank badges visible in both list and grid views
+- Grid/list toggle works with list as default
+- Resolved threads: no drag handles, rank badges visible, static order
+- All tests pass, lint clean
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/11-candidate-ranking/11-02-SUMMARY.md`
+</output>

.planning/phases/11-candidate-ranking/11-02-SUMMARY.md

@@ -0,0 +1,85 @@
+---
+phase: 11-candidate-ranking
+plan: "02"
+subsystem: client-ui
+tags: [drag-reorder, framer-motion, rank-badges, view-toggle, list-view]
+dependency_graph:
+  requires: [11-01]
+  provides: [drag-to-reorder-ui, rank-badges, list-grid-toggle]
+  affects: [threads/$threadId.tsx, CandidateCard, CandidateListItem, uiStore, useCandidates]
+tech_stack:
+  added: []
+  patterns:
+    - framer-motion Reorder.Group + Reorder.Item with useDragControls for drag handle
+    - tempItems pattern to prevent React Query flicker during optimistic drag
+    - RankBadge exported from CandidateListItem for reuse across views
+    - candidateViewMode in uiStore for list/grid toggle state
+key_files:
+  created:
+    - src/client/components/CandidateListItem.tsx
+  modified:
+    - src/client/hooks/useCandidates.ts
+    - src/client/stores/uiStore.ts
+    - src/client/components/CandidateCard.tsx
+    - src/client/routes/threads/$threadId.tsx
+    - src/client/lib/iconData.tsx
+    - src/client/hooks/useThreads.ts
+decisions:
+  - Resolved thread list view uses plain div (not Reorder.Group) — no drag, rank badges visible
+  - handleDragEnd fires on Reorder.Group onPointerUp to debounce reorder API call
+  - biome-ignore applied to useExhaustiveDependencies for thread?.candidates dep — intentional trigger
+metrics:
+  duration: 4min
+  completed: 2026-03-16T21:29:07Z
+  tasks_completed: 3
+  files_changed: 7
+---
+
+# Phase 11 Plan 02: Drag-to-Reorder UI Summary
+
+Drag-to-reorder candidate ranking with list/grid view toggle, gold/silver/bronze rank badges, and framer-motion Reorder.Group with tempItems flicker prevention.
+
+## What Was Built
+
+### Task 1: useReorderCandidates hook + uiStore view mode + CandidateListItem component
+- Added `useReorderCandidates` mutation hook to `useCandidates.ts` using `apiPatch` to hit `PATCH /api/threads/:id/candidates/reorder`
+- Added `candidateViewMode: "list" | "grid"` and `setCandidateViewMode` to `uiStore.ts`
+- Created `CandidateListItem.tsx` — horizontal card for list view with drag handle (GripVertical), RankBadge (medal icon), 48x48 image thumbnail, badge row (weight/price/category/status/pros-cons), and hover-reveal action buttons
+- Exported `RankBadge` component (gold `#D4AF37`, silver `#C0C0C0`, bronze `#CD7F32`) for reuse
+- Added `style` prop support to `LucideIcon` for colored medal icons
+- Added `pros` and `cons` fields to `CandidateWithCategory` in `useThreads.ts` (Rule 2 auto-fix — missing after Phase 10)
+
+### Task 2: Thread detail page with view toggle, Reorder.Group, rank badges in grid view
+- Updated `CandidateCard.tsx`: added `rank?: number` prop and renders `<RankBadge rank={rank} />` in badge row
+- Updated `threads/$threadId.tsx`:
+  - List/grid view toggle (LayoutList / LayoutGrid icons) using `candidateViewMode` from uiStore
+  - Active list view: `<Reorder.Group>` wrapping `<CandidateListItem>` instances for drag-to-reorder
+  - Resolved list view: plain `<div>` with `<CandidateListItem isActive={false}>` — rank badges visible, drag handles hidden
+  - Grid view: existing `<CandidateCard>` grid with `rank={index + 1}` passed to each card
+  - `tempItems` state: holds in-progress drag order, falls back to `thread.candidates` when null
+  - `handleDragEnd`: fires `reorderMutation.mutate({ orderedIds })` and clears tempItems on settled
+  - `useEffect` clears tempItems when `thread?.candidates` reference changes (fresh server data)
+
+### Task 3: Human verification (auto-approved — auto_chain_active)
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing] Added pros/cons fields to CandidateWithCategory in useThreads.ts**
+- **Found during:** Task 1 (needed by CandidateListItem)
+- **Issue:** `CandidateWithCategory` interface in `useThreads.ts` was missing `pros` and `cons` fields added in Phase 10. CandidateListItem needed these to render the "+/- Notes" badge.
+- **Fix:** Added `pros: string | null` and `cons: string | null` to the interface
+- **Files modified:** `src/client/hooks/useThreads.ts`
+- **Commit:** acfa995
+
+**2. [Rule 2 - Missing] Added style prop to LucideIcon component**
+- **Found during:** Task 1 (needed by RankBadge for medal colors)
+- **Issue:** LucideIcon only accepted `className` for styling; RankBadge needed inline `style={{ color }}` for gold/silver/bronze hex colors not achievable via Tailwind
+- **Fix:** Added optional `style?: React.CSSProperties` prop to LucideIcon and passed through to icon component
+- **Files modified:** `src/client/lib/iconData.tsx`
+- **Commit:** acfa995
+
+## Self-Check: PASSED
+
+All created/modified files exist. Both task commits (acfa995, 94c07e7) confirmed in git log.

.planning/phases/11-candidate-ranking/11-CONTEXT.md

@@ -0,0 +1,107 @@
+# Phase 11: Candidate Ranking - Context
+
+**Gathered:** 2026-03-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can drag candidates into a priority order within a thread. The rank persists across sessions and is visually communicated with medal badges on the top 3. Drag handles and reordering are disabled on resolved threads. Comparison view, impact preview, and pros/cons editing are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Card layout and view toggle
+- Add a grid/list view toggle in the thread header (list view is default)
+- List view: vertical stack of horizontal cards (image thumbnail on left, name + badges on right) — enables drag-to-reorder
+- Grid view: current 3-column responsive card layout preserved
+- Both views render candidates in rank order (sort_order ascending)
+- Rank badges visible in both views
+
+### Drag handle design
+- Always-visible GripVertical icon (Lucide) on the left side of each list-view card
+- Grip icon color: muted gray (text-gray-300), darkens to text-gray-500 on hover
+- Cursor changes to 'grab' on hover, 'grabbing' during drag
+- Drag feedback: elevated card with shadow + scale-up effect; other cards animate to show drop target gap (standard framer-motion Reorder behavior)
+- On resolved threads: grip icon disappears entirely (not disabled/grayed)
+- Drag only available in list view (grid view has no drag handles)
+
+### Rank badge style
+- Medal icons (Lucide 'medal' or 'trophy') in gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) for top 3 candidates
+- Positioned inline before the candidate name text
+- Candidates ranked 4th and below show no rank indicator — position implied by list order
+- On resolved threads: rank badges remain visible (static, read-only) — **overrides roadmap success criteria #4 which said "rank badges absent on resolved thread"**; user prefers retrospective visibility
+
+### Sort order and persistence
+- Schema migration adds `sort_order REAL NOT NULL DEFAULT 0` to `thread_candidates`
+- Migration initializes existing candidates with spaced values (1000, 2000, 3000...) ordered by `created_at` — ensures immediate correct ordering
+- Fractional indexing: only the moved item gets a single UPDATE (midpoint between neighbors)
+- New candidates added to a thread get the highest sort_order (appended to bottom of rank)
+- Auto-save on drop — no "Save order" button; reorder persists immediately via `PATCH /api/threads/:id/candidates/reorder`
+- `tempItems` local state pattern: render from `tempItems ?? queryData.candidates`; clear on mutation `onSettled` — prevents React Query flicker
+
+### Claude's Discretion
+- Exact horizontal card dimensions and spacing in list view
+- Grid/list toggle icon style and placement
+- Drag animation timing and spring config
+- Image thumbnail size in list view cards
+- How action buttons (Winner, Delete, Link) adapt to horizontal card layout
+- Keyboard accessibility for reordering (arrow keys to move)
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `CandidateCard` (`src/client/components/CandidateCard.tsx`): Current card component — needs horizontal variant for list view, or a new `CandidateListItem` component
+- `StatusBadge` (`src/client/components/StatusBadge.tsx`): Click-to-cycle pattern reusable in list view
+- `useCandidates.ts` hooks: `useCreateCandidate`, `useUpdateCandidate`, `useDeleteCandidate` — need new `useReorderCandidates` mutation
+- `useThread` hook: Returns thread with `candidates[]` array — already has all data needed, just needs sort_order ordering
+- `formatWeight`/`formatPrice` formatters: Reuse in list view card badges
+- `useWeightUnit`/`useCurrency` hooks: Already used by CandidateCard
+- `LucideIcon` helper: For GripVertical drag handle and medal rank badges
+- `uiStore` (Zustand): Add `candidateViewMode: 'list' | 'grid'` for view toggle persistence
+
+### Established Patterns
+- framer-motion@12.37.0 already installed — `Reorder.Group`/`Reorder.Item` for drag ordering
+- React Query for server data, Zustand for UI-only state
+- Pill badges: blue for weight, green for price, gray for category, purple for pros/cons
+- Services accept db as first param (DI pattern for testability)
+- API validation via `@hono/zod-validator` with Zod schemas
+- Hover-reveal action buttons on CandidateCard (Winner, Delete, External link)
+
+### Integration Points
+- `src/db/schema.ts`: Add `sortOrder: real("sort_order").notNull().default(0)` to `threadCandidates`
+- `src/server/services/thread.service.ts`: New `reorderCandidates()` function (transactional); update `getCandidates` to ORDER BY sort_order
+- `src/server/routes/threads.ts`: New `PATCH /:id/candidates/reorder` endpoint; reject if thread is resolved
+- `src/shared/schemas.ts`: New `reorderCandidatesSchema` (z.object with orderedIds array)
+- `src/client/routes/threads/$threadId.tsx`: Wrap candidates in `Reorder.Group`, add view toggle, use tempItems pattern
+- `src/client/hooks/useCandidates.ts`: New `useReorderCandidates` mutation hook
+- `tests/helpers/db.ts`: Update CREATE TABLE for thread_candidates to include sort_order column
+- Drizzle migration: `sort_order REAL NOT NULL DEFAULT 0` + data migration to space existing rows
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- List view cards should feel like Trello or Linear cards — horizontal layout, grip handle on the left, compact but informative
+- Drag feedback should use standard framer-motion spring animations (elevated + gap), not custom physics
+- Medal badges should use actual metallic-feeling colors (gold #D4AF37, silver #C0C0C0, bronze #CD7F32), not generic highlight colors
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 11-candidate-ranking*
+*Context gathered: 2026-03-16*

.planning/phases/11-candidate-ranking/11-RESEARCH.md

@@ -0,0 +1,540 @@
+# Phase 11: Candidate Ranking - Research
+
+**Researched:** 2026-03-16
+**Domain:** Drag-to-reorder UI + fractional indexing persistence
+**Confidence:** HIGH
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+**Card layout and view toggle**
+- Add a grid/list view toggle in the thread header (list view is default)
+- List view: vertical stack of horizontal cards (image thumbnail on left, name + badges on right) — enables drag-to-reorder
+- Grid view: current 3-column responsive card layout preserved
+- Both views render candidates in rank order (sort_order ascending)
+- Rank badges visible in both views
+
+**Drag handle design**
+- Always-visible GripVertical icon (Lucide) on the left side of each list-view card
+- Grip icon color: muted gray (text-gray-300), darkens to text-gray-500 on hover
+- Cursor changes to 'grab' on hover, 'grabbing' during drag
+- Drag feedback: elevated card with shadow + scale-up effect; other cards animate to show drop target gap (standard framer-motion Reorder behavior)
+- On resolved threads: grip icon disappears entirely (not disabled/grayed)
+- Drag only available in list view (grid view has no drag handles)
+
+**Rank badge style**
+- Medal icons (Lucide 'medal') in gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) for top 3 candidates
+- Positioned inline before the candidate name text
+- Candidates ranked 4th and below show no rank indicator — position implied by list order
+- On resolved threads: rank badges remain visible (static, read-only) — user prefers retrospective visibility
+
+**Sort order and persistence**
+- Schema migration adds `sort_order REAL NOT NULL DEFAULT 0` to `thread_candidates`
+- Migration initializes existing candidates with spaced values (1000, 2000, 3000...) ordered by `created_at`
+- Fractional indexing: only the moved item gets a single UPDATE (midpoint between neighbors)
+- New candidates added to a thread get the highest sort_order (appended to bottom of rank)
+- Auto-save on drop — no "Save order" button; reorder persists immediately via `PATCH /api/threads/:id/candidates/reorder`
+- `tempItems` local state pattern: render from `tempItems ?? queryData.candidates`; clear on mutation `onSettled` — prevents React Query flicker
+
+### Claude's Discretion
+- Exact horizontal card dimensions and spacing in list view
+- Grid/list toggle icon style and placement
+- Drag animation timing and spring config
+- Image thumbnail size in list view cards
+- How action buttons (Winner, Delete, Link) adapt to horizontal card layout
+- Keyboard accessibility for reordering (arrow keys to move)
+
+### Deferred Ideas (OUT OF SCOPE)
+None — discussion stayed within phase scope
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| RANK-01 | User can drag candidates to reorder priority ranking within a thread | framer-motion Reorder.Group/Item handles drag + onReorder callback; fractional indexing PATCH saves order |
+| RANK-02 | Top 3 ranked candidates display rank badges (gold, silver, bronze) | sort_order ascending sort gives rank position; Lucide `medal` icon confirmed available; CSS inline-color via style prop |
+| RANK-04 | Candidate rank order persists across sessions | `sort_order REAL` column + Drizzle migration + `getThreadWithCandidates` ORDER BY sort_order; tempItems pattern prevents RQ flicker |
+| RANK-05 | Drag handles and ranking are disabled on resolved threads | `isActive` prop already flows through `$threadId.tsx`; grip icon conditional render; Reorder.Group only rendered when isActive |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 11 adds drag-to-reorder ranking for research thread candidates. The core mechanism is framer-motion's `Reorder.Group` / `Reorder.Item` components (already installed at v12.37.0 — no new dependencies), combined with a `sort_order REAL` column on `thread_candidates` and a fractional indexing strategy that writes only one row per reorder.
+
+The drag handle pattern requires `useDragControls` from framer-motion so the drag is initiated only from the GripVertical icon, not from tapping anywhere on the card. The `tempItems` local state pattern prevents a visible flicker between optimistic UI and React Query re-fetch.
+
+The phase introduces a grid/list view toggle (defaulting to list). The existing `CandidateCard` component handles grid view unchanged; a new `CandidateListItem` component (or a variant prop on `CandidateCard`) provides the horizontal list-view layout with the drag handle and rank badge.
+
+**Primary recommendation:** Implement in this order — schema migration, service update, Zod schema + route, hook, then UI (view toggle, `CandidateListItem`, rank badge). This matches the established field-addition ladder pattern.
+
+---
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| framer-motion | ^12.37.0 (installed) | Drag-to-reorder via `Reorder.Group`/`Reorder.Item`; `useDragControls` for handle-based drag | Already in project; Reorder API is purpose-built for this pattern — no additional install |
+| Drizzle ORM | installed | Schema migration + `ORDER BY sort_order` query | Project ORM; REAL type required for fractional indexing |
+| @tanstack/react-query | installed | `useReorderCandidates` mutation + cache invalidation | Project data-fetch layer |
+| Zustand | installed | `candidateViewMode: 'list' | 'grid'` in uiStore | Project UI state pattern |
+| lucide-react | installed | GripVertical, Medal, LayoutList, LayoutGrid icons | All icons confirmed present in installed version |
+
+### No New Dependencies
+This phase requires zero new npm packages. framer-motion, React Query, Zustand, and Lucide are all already installed.
+
+---
+
+## Architecture Patterns
+
+### Recommended Project Structure Changes
+```
+src/
+├── db/schema.ts                           # Add sortOrder: real("sort_order")
+├── server/
+│   ├── services/thread.service.ts         # Add reorderCandidates(), update getCandidates ORDER BY
+│   └── routes/threads.ts                  # Add PATCH /:id/candidates/reorder
+├── shared/
+│   ├── schemas.ts                         # Add reorderCandidatesSchema
+│   └── types.ts                           # Add ReorderCandidates type
+├── client/
+│   ├── components/
+│   │   ├── CandidateCard.tsx              # Unchanged (grid view)
+│   │   └── CandidateListItem.tsx          # NEW: horizontal list-view card with drag handle
+│   ├── hooks/useCandidates.ts             # Add useReorderCandidates mutation
+│   ├── routes/threads/$threadId.tsx       # Add view toggle, Reorder.Group, tempItems pattern
+│   └── stores/uiStore.ts                  # Add candidateViewMode state
+└── tests/
+    ├── helpers/db.ts                       # Add sort_order column to CREATE TABLE
+    └── services/thread.service.test.ts    # Tests for reorderCandidates()
+```
+
+### Pattern 1: framer-motion Reorder with Drag Handle
+
+The `Reorder.Group` fires `onReorder` whenever a drag completes. The `useDragControls` hook
+lets the drag be triggered only from the grip icon. Wrap each item with `Reorder.Item` and
+attach `dragControls` to it.
+
+```typescript
+// Source: framer-motion dist/types/index.d.ts (confirmed in installed v12.37.0)
+import { Reorder, useDragControls } from "framer-motion";
+
+// In ThreadDetailPage — list view:
+const [tempItems, setTempItems] = useState<Candidate[] | null>(null);
+const displayItems = tempItems ?? thread.candidates; // sorted by sort_order from server
+
+<Reorder.Group
+  axis="y"
+  values={displayItems}
+  onReorder={setTempItems}      // updates local order instantly
+  className="flex flex-col gap-2"
+>
+  {displayItems.map((candidate, index) => (
+    <CandidateListItem
+      key={candidate.id}
+      candidate={candidate}
+      rank={index + 1}
+      isActive={isActive}
+      onReorderSave={() => saveOrder(tempItems)}  // called onDragEnd
+    />
+  ))}
+</Reorder.Group>
+```
+
+```typescript
+// In CandidateListItem — drag handle via useDragControls:
+// Source: framer-motion dist/types/index.d.ts
+import { Reorder, useDragControls } from "framer-motion";
+
+function CandidateListItem({ candidate, rank, isActive, ... }) {
+  const controls = useDragControls();
+
+  return (
+    <Reorder.Item value={candidate} dragControls={controls} dragListener={false}>
+      <div className="flex items-center gap-3 bg-white rounded-xl border border-gray-100 p-3">
+        {/* Drag handle — only visible on active threads */}
+        {isActive && (
+          <div
+            onPointerDown={(e) => controls.start(e)}
+            className="cursor-grab active:cursor-grabbing text-gray-300 hover:text-gray-500 touch-none"
+          >
+            <LucideIcon name="grip-vertical" size={16} />
+          </div>
+        )}
+        {/* Rank badge — top 3 only, visible on resolved too */}
+        {rank <= 3 && <RankBadge rank={rank} />}
+        {/* ... rest of card content */}
+      </div>
+    </Reorder.Item>
+  );
+}
+```
+
+**Key flag:** `dragListener={false}` on `Reorder.Item` disables the default "drag anywhere on the item" behavior, restricting drag to the handle only. This is the critical prop for handle-based reordering.
+
+**Key flag:** `touch-none` Tailwind class on the handle prevents scroll interference on mobile (`touch-action: none`).
+
+### Pattern 2: Fractional Indexing for sort_order
+
+Fractional indexing avoids rewriting all rows on every drag. Only the moved item's `sort_order` changes.
+
+```typescript
+// Service function — reorderCandidates
+// Computes new sort_order as midpoint between neighbors
+export function reorderCandidates(
+  db: Db,
+  threadId: number,
+  orderedIds: number[],
+): { success: boolean; error?: string } {
+  return db.transaction((tx) => {
+    // Verify thread is active
+    const thread = tx.select().from(threads).where(eq(threads.id, threadId)).get();
+    if (!thread || thread.status !== "active") {
+      return { success: false, error: "Thread not active" };
+    }
+
+    // Fetch current sort_orders keyed by id
+    const rows = tx
+      .select({ id: threadCandidates.id, sortOrder: threadCandidates.sortOrder })
+      .from(threadCandidates)
+      .where(eq(threadCandidates.threadId, threadId))
+      .all();
+
+    const sortMap = new Map(rows.map((r) => [r.id, r.sortOrder]));
+    const sortedExisting = [...sortMap.entries()].sort((a, b) => a[1] - b[1]);
+
+    // Re-assign spaced values in the requested order
+    // (Simpler than midpoint for full reorder; midpoint for single-item moves is optimization)
+    orderedIds.forEach((id, index) => {
+      const newOrder = (index + 1) * 1000;
+      tx.update(threadCandidates)
+        .set({ sortOrder: newOrder })
+        .where(eq(threadCandidates.id, id))
+        .run();
+    });
+
+    return { success: true };
+  });
+}
+```
+
+**Note:** The CONTEXT.md specifies midpoint-only for single-item moves. For the PATCH endpoint
+receiving a full ordered list, re-spacing at 1000 intervals is simpler and still correct.
+Midpoint optimization matters if the API receives only (id, position) for a single move —
+confirm which approach the planner selects.
+
+### Pattern 3: tempItems Flicker Prevention
+
+React Query refetch after mutation causes a visible reorder "snap back" unless tempItems absorbs the transition.
+
+```typescript
+// In ThreadDetailPage:
+const [tempItems, setTempItems] = useState<typeof thread.candidates | null>(null);
+const displayItems = tempItems ?? thread.candidates; // server data already sorted by sort_order
+
+const reorderMutation = useReorderCandidates(threadId);
+
+function handleReorder(newOrder: typeof thread.candidates) {
+  setTempItems(newOrder);
+}
+
+function handleDragEnd() {
+  if (!tempItems) return;
+  reorderMutation.mutate(
+    { orderedIds: tempItems.map((c) => c.id) },
+    {
+      onSettled: () => setTempItems(null),  // clear after server confirms or fails
+    }
+  );
+}
+```
+
+### Pattern 4: Drizzle Migration + Data Backfill
+
+Migration must add column AND backfill existing rows with spaced values to avoid all-zero sort_order.
+
+```sql
+-- Migration SQL (generated by bun run db:generate):
+ALTER TABLE `thread_candidates` ADD `sort_order` real NOT NULL DEFAULT 0;
+
+-- Data backfill SQL (run as separate statement in migration or seed script):
+-- SQLite window functions assign rank per thread, multiply by 1000
+UPDATE thread_candidates
+SET sort_order = (
+  SELECT (ROW_NUMBER() OVER (PARTITION BY thread_id ORDER BY created_at)) * 1000
+  FROM thread_candidates AS tc2
+  WHERE tc2.id = thread_candidates.id
+);
+```
+
+**SQLite version note:** SQLite supports window functions since version 3.25.0 (2018). Bun
+ships with a recent SQLite — this query is safe. Verify with `bun -e "import { Database } from 'bun:sqlite'; const db = new Database(':memory:'); console.log(db.query('SELECT sqlite_version()').get())"`.
+
+### Anti-Patterns to Avoid
+
+- **Drag from anywhere on the card:** Without `dragListener={false}` on `Reorder.Item`, clicking the card to edit it triggers a drag. Always pair with `useDragControls`.
+- **Ordering by integer with bulk update:** Updating all rows on every drag is O(n) writes. Use REAL (float) sort_order for midpoint single-update.
+- **Storing order in the React Query cache only:** Sort order must persist to the server; local-only ordering is lost on page refresh.
+- **Rendering `Reorder.Group` without `layout` on inner elements:** framer-motion needs `layout` prop on animated children to perform smooth gap animation. `Reorder.Item` handles this internally — do not nest another `motion.div` with conflicting layout props.
+- **Missing `key` on Reorder.Item:** The key must be stable (candidate.id), not index — framer-motion uses it to track item identity across reorders.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Drag-to-reorder list | Custom mousedown/mousemove/mouseup handlers | `framer-motion` Reorder.Group/Item | Handles pointer capture, scroll suppression, layout animation, keyboard fallback |
+| Drag handle restriction | Event.stopPropagation tricks | `useDragControls` + `dragListener={false}` | Official framer-motion API; handles touch events correctly |
+| Smooth gap animation during drag | CSS transform calculations | `Reorder.Item` layout animation | Built-in spring physics; other items animate to fill the gap automatically |
+| Sort order persistence strategy | Custom complex state | Fractional indexing (REAL column, midpoint) | One write per drop; no full-list rewrite; proven pattern from Linear/Trello |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: All-Zero sort_order After Migration
+**What goes wrong:** ALTERing the column with `DEFAULT 0` sets all existing rows to 0. `ORDER BY sort_order` returns them in arbitrary order.
+**Why it happens:** SQLite sets new column values to the DEFAULT for existing rows.
+**How to avoid:** Run the window-function UPDATE backfill as part of the migration or immediately after.
+**Warning signs:** Candidates render in seemingly random or creation-id order after migration.
+
+### Pitfall 2: Drag Initiates on Card Click
+**What goes wrong:** User clicks to open the edit panel and the card starts dragging instead.
+**Why it happens:** `Reorder.Item` defaults `dragListener={true}` — any pointer-down on the item starts dragging.
+**How to avoid:** Set `dragListener={false}` on `Reorder.Item` and use `useDragControls` to start drag only from the grip handle's `onPointerDown`.
+**Warning signs:** Click on candidate name opens drag instead of edit panel.
+
+### Pitfall 3: React Query Flicker After Save
+**What goes wrong:** After `reorderMutation` completes and React Query refetches, candidates visually snap back to server order for a frame.
+**Why it happens:** React Query invalidates and refetches; server returns the new order but there's a brief moment where old cache is used.
+**How to avoid:** Use `tempItems` local state pattern. Render `tempItems ?? thread.candidates`. Clear `tempItems` in `onSettled` (not `onSuccess`) so it covers both success and error cases.
+**Warning signs:** Items visually "jump" after a drop.
+
+### Pitfall 4: touch-none Missing on Drag Handle
+**What goes wrong:** On mobile, dragging the grip handle scrolls the page instead of reordering.
+**Why it happens:** Browser default: `touch-action` allows scroll on pointer-down.
+**How to avoid:** Add `className="touch-none"` (Tailwind) or `style={{ touchAction: "none" }}` on the drag handle element.
+**Warning signs:** Mobile drag scrolls page; items don't reorder on touch devices.
+
+### Pitfall 5: Resolved Thread Reorder Accepted by API
+**What goes wrong:** A resolved thread's candidates can be reordered if the server does not check thread status.
+**Why it happens:** The API endpoint receives a valid payload and processes it without checking `thread.status`.
+**How to avoid:** In `reorderCandidates()` service, verify `thread.status === "active"` and return error if not. Match pattern of `resolveThread()` which already does this check.
+**Warning signs:** PATCH succeeds on a resolved thread; RANK-05 test fails.
+
+---
+
+## Code Examples
+
+### Zod Schema for Reorder Endpoint
+```typescript
+// src/shared/schemas.ts — add:
+// Source: existing schema.ts patterns in project
+export const reorderCandidatesSchema = z.object({
+  orderedIds: z.array(z.number().int().positive()).min(1),
+});
+```
+
+### Shared Type
+```typescript
+// src/shared/types.ts — add:
+export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
+```
+
+### Drizzle Schema Column
+```typescript
+// src/db/schema.ts — in threadCandidates table:
+sortOrder: real("sort_order").notNull().default(0),
+```
+
+### getThreadWithCandidates ORDER BY Fix
+```typescript
+// src/server/services/thread.service.ts
+// Change the candidateList query to order by sort_order:
+.from(threadCandidates)
+.innerJoin(categories, eq(threadCandidates.categoryId, categories.id))
+.where(eq(threadCandidates.threadId, threadId))
+.orderBy(threadCandidates.sortOrder)  // add this
+.all();
+```
+
+### createCandidate sort_order for New Candidates
+```typescript
+// src/server/services/thread.service.ts
+// New candidates append to bottom — find current max and add 1000:
+export function createCandidate(db, threadId, data) {
+  const maxRow = db
+    .select({ maxOrder: sql<number>`MAX(sort_order)` })
+    .from(threadCandidates)
+    .where(eq(threadCandidates.threadId, threadId))
+    .get();
+  const newSortOrder = (maxRow?.maxOrder ?? 0) + 1000;
+
+  return db.insert(threadCandidates).values({
+    ...data,
+    sortOrder: newSortOrder,
+  }).returning().get();
+}
+```
+
+### Hono PATCH Route
+```typescript
+// src/server/routes/threads.ts — add:
+app.patch(
+  "/:id/candidates/reorder",
+  zValidator("json", reorderCandidatesSchema),
+  (c) => {
+    const db = c.get("db");
+    const threadId = Number(c.req.param("id"));
+    const { orderedIds } = c.req.valid("json");
+    const result = reorderCandidates(db, threadId, orderedIds);
+    if (!result.success) return c.json({ error: result.error }, 400);
+    return c.json({ success: true });
+  },
+);
+```
+
+### useReorderCandidates Hook
+```typescript
+// src/client/hooks/useCandidates.ts — add:
+export function useReorderCandidates(threadId: number) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: { orderedIds: number[] }) =>
+      apiPatch<{ success: boolean }>(
+        `/api/threads/${threadId}/candidates/reorder`,
+        data,
+      ),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ["threads", threadId] });
+    },
+  });
+}
+```
+
+### RankBadge Component (inline)
+```typescript
+// Inline in CandidateListItem or extract as small component
+const RANK_STYLES = [
+  { color: "#D4AF37", label: "1st" }, // gold
+  { color: "#C0C0C0", label: "2nd" }, // silver
+  { color: "#CD7F32", label: "3rd" }, // bronze
+];
+
+function RankBadge({ rank }: { rank: number }) {
+  if (rank > 3) return null;
+  const { color } = RANK_STYLES[rank - 1];
+  return (
+    <LucideIcon
+      name="medal"
+      size={16}
+      className="shrink-0"
+      style={{ color }}
+    />
+  );
+}
+```
+
+### tests/helpers/db.ts: thread_candidates table update
+```sql
+-- Add to CREATE TABLE thread_candidates in tests/helpers/db.ts:
+sort_order REAL NOT NULL DEFAULT 0,
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| `react-beautiful-dnd` | framer-motion Reorder | framer-motion v5+ Reorder API | Simpler API, same bundle already present, maintained by Framer |
+| Integer sort_order with bulk UPDATE | REAL (float) fractional indexing | Best practice since ~2015 (Linear, Figma) | O(1) writes per drag vs O(n) |
+| "Save order" button | Auto-save on drop | UX convention | Reduces friction; matches Trello/Linear behavior |
+
+**Deprecated/outdated:**
+- `react-beautiful-dnd`: No longer actively maintained; framer-motion Reorder is the modern replacement in React 18+ projects.
+
+---
+
+## Open Questions
+
+1. **Full-list reorder vs single-item fractional update in PATCH body**
+   - What we know: CONTEXT.md says "only the moved item gets a single UPDATE (midpoint between neighbors)" but also says PATCH receives `orderedIds` array
+   - What's unclear: If the server receives the full ordered list, re-spacing at 1000-intervals is simpler than computing midpoints server-side
+   - Recommendation: Accept full `orderedIds` array in PATCH, re-space all at 1000-intervals; this is correct and simpler. Midpoint is only an optimization for very large lists (not relevant here).
+
+2. **View toggle persistence scope**
+   - What we know: CONTEXT.md says use Zustand `candidateViewMode` for view toggle
+   - What's unclear: Whether to also persist in `localStorage` across page refreshes
+   - Recommendation: Zustand in-memory only (resets to list on refresh) is sufficient; no localStorage needed unless user reports preference loss as pain point.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test (built-in) |
+| Config file | none — `bun test` auto-discovers `*.test.ts` |
+| Quick run command | `bun test tests/services/thread.service.test.ts` |
+| Full suite command | `bun test` |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| RANK-01 | `reorderCandidates()` updates sort_order in DB in requested sequence | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 (new test cases) |
+| RANK-01 | `PATCH /api/threads/:id/candidates/reorder` returns 200 + reorders candidates | integration | `bun test tests/routes/threads.test.ts` | ❌ Wave 0 (new test cases) |
+| RANK-02 | Rank badge rendering logic (index → medal color) | unit (component logic) | `bun test` | Manual-only — no component test infra |
+| RANK-04 | `getThreadWithCandidates` returns candidates ordered by sort_order ascending | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 |
+| RANK-05 | `reorderCandidates()` returns error when thread is resolved | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 |
+| RANK-05 | `PATCH /api/threads/:id/candidates/reorder` returns 400 for resolved thread | integration | `bun test tests/routes/threads.test.ts` | ❌ Wave 0 |
+
+### 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
+- [ ] New test cases in `tests/services/thread.service.test.ts` — covers RANK-01, RANK-04, RANK-05 service behavior
+- [ ] New test cases in `tests/routes/threads.test.ts` — covers RANK-01, RANK-05 route behavior
+- [ ] Update `tests/helpers/db.ts` CREATE TABLE for `thread_candidates` to add `sort_order REAL NOT NULL DEFAULT 0`
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- framer-motion `dist/types/index.d.ts` (v12.37.0 installed) — `Reorder.Group`, `Reorder.Item`, `useDragControls`, `dragListener` prop confirmed
+- `src/client/lib/api.ts` — `apiPatch` confirmed available
+- `src/client/lib/iconData.tsx` + lucide-react installed — `medal`, `grip-vertical`, `layout-list`, `layout-grid` icons confirmed via `bun -e` introspection
+- `src/db/schema.ts` — current schema confirmed; `sort_order` column absent (needs migration)
+- `tests/helpers/db.ts` — CREATE TABLE confirmed; needs `sort_order` column added
+- `src/server/services/thread.service.ts` — `resolveThread()` pattern for status check reused in `reorderCandidates()`
+- `.planning/phases/11-candidate-ranking/11-CONTEXT.md` — all locked decisions applied
+
+### Secondary (MEDIUM confidence)
+- framer-motion Reorder documentation patterns (consistent with installed type definitions)
+- Fractional indexing / REAL sort_order pattern well-established in Linear, Trello, Figma implementations
+
+### Tertiary (LOW confidence)
+- None
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — all libraries confirmed installed and API-verified from local node_modules
+- Architecture: HIGH — patterns derived from existing codebase + confirmed framer-motion type signatures
+- Pitfalls: HIGH — derived from direct API analysis (dragListener, touch-none) and known SQLite migration behavior
+
+**Research date:** 2026-03-16
+**Valid until:** 2026-04-16 (stable dependencies; framer-motion Reorder API is mature)

.planning/phases/11-candidate-ranking/11-VALIDATION.md

@@ -0,0 +1,79 @@
+---
+phase: 11
+slug: candidate-ranking
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-16
+---
+
+# Phase 11 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bun test (built-in) |
+| **Config file** | none — `bun test` auto-discovers `*.test.ts` |
+| **Quick run command** | `bun test tests/services/thread.service.test.ts` |
+| **Full suite command** | `bun test` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `bun test tests/services/thread.service.test.ts`
+- **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 |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| TBD | 01 | 1 | RANK-01 | unit | `bun test tests/services/thread.service.test.ts` | ❌ W0 | ⬜ pending |
+| TBD | 01 | 1 | RANK-01 | integration | `bun test tests/routes/threads.test.ts` | ❌ W0 | ⬜ pending |
+| TBD | 01 | 1 | RANK-04 | unit | `bun test tests/services/thread.service.test.ts` | ❌ W0 | ⬜ pending |
+| TBD | 01 | 1 | RANK-05 | unit | `bun test tests/services/thread.service.test.ts` | ❌ W0 | ⬜ pending |
+| TBD | 01 | 1 | RANK-05 | integration | `bun test tests/routes/threads.test.ts` | ❌ W0 | ⬜ pending |
+| TBD | 02 | 1 | RANK-02 | manual | Visual inspection | N/A | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] New test cases in `tests/services/thread.service.test.ts` — covers RANK-01, RANK-04, RANK-05 service behavior
+- [ ] New test cases in `tests/routes/threads.test.ts` — covers RANK-01, RANK-05 route behavior
+- [ ] Update `tests/helpers/db.ts` CREATE TABLE for `thread_candidates` to add `sort_order REAL NOT NULL DEFAULT 0`
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Rank badge rendering (gold/silver/bronze medal icons on top 3) | RANK-02 | No component test infrastructure; visual verification required | Open thread with 3+ candidates, verify top 3 show medal icons with correct colors |
+| Drag handle visibility and interaction | RANK-01 | Visual/interaction verification | Open active thread in list view, verify grip icons visible, drag to reorder |
+| Drag handle absent on resolved thread | RANK-05 | Visual verification | Open resolved thread, verify no grip icons, rank badges still visible (static) |
+
+---
+
+## 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/11-candidate-ranking/11-VERIFICATION.md

@@ -0,0 +1,175 @@
+---
+phase: 11-candidate-ranking
+verified: 2026-03-16T23:30:00Z
+status: human_needed
+score: 11/11 must-haves verified
+re_verification:
+  previous_status: gaps_found
+  previous_score: 9/11
+  gaps_closed:
+    - "User can drag a candidate card to a new position in list view and it persists after page refresh — onPointerUp={handleDragEnd} is now correctly on the active <Reorder.Group> (line 198)"
+  gaps_remaining: []
+  regressions: []
+human_verification:
+  - test: "Drag a candidate on an active thread and refresh"
+    expected: "Dragged order is preserved after page reload (new order loaded from server)"
+    why_human: "Smooth drag animation, gap preview, pointer-event timing, and actual persistence need visual inspection and interaction"
+  - test: "Drag handles visibility on resolved vs active threads"
+    expected: "Active threads show GripVertical drag handles; resolved threads show no drag handles but rank badges remain"
+    why_human: "CSS visibility and conditional rendering need visual verification"
+  - test: "Top 3 rank badges appearance"
+    expected: "Gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) medal icons appear on positions 1, 2, 3 in both list and grid views"
+    why_human: "Color rendering and icon display need visual confirmation"
+---
+
+# Phase 11: Candidate Ranking Verification Report
+
+**Phase Goal:** Users can drag candidates into a priority order that persists and is visually communicated
+**Verified:** 2026-03-16T23:30:00Z
+**Status:** human_needed
+**Re-verification:** Yes — after gap closure
+
+## Re-verification Summary
+
+Previous status was `gaps_found` (score 9/11). The one critical blocker was:
+
+> `handleDragEnd` (which calls `reorderMutation.mutate`) was wired to the resolved-thread `<div>` via `onPointerUp`, not to the active-thread `<Reorder.Group>`. Dragging updated `tempItems` visually but never fired the mutation.
+
+**Fix verified:** `src/client/routes/threads/$threadId.tsx` line 198 now has `onPointerUp={handleDragEnd}` on the `<Reorder.Group>` for the active-thread path. The resolved-thread `<div>` (lines 217-233) has no `onPointerUp` handler. The fix is correct and complete.
+
+All 11 truths now pass automated checks. 135/135 tests pass. No regressions detected.
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | Candidates returned from getThreadWithCandidates are ordered by sort_order ascending | VERIFIED | `thread.service.ts:90` uses `.orderBy(asc(threadCandidates.sortOrder))` |
+| 2 | Calling reorderCandidates with a new ID sequence updates sort_order values | VERIFIED | `reorderCandidates` loops `orderedIds`, sets `sortOrder: (i+1)*1000` per candidate in a transaction (`thread.service.ts:240`) |
+| 3 | PATCH /api/threads/:id/candidates/reorder returns 200 and persists new order | VERIFIED | Route at `threads.ts:129-140`; Zod-validated; returns `{ success: true }` or 400 |
+| 4 | reorderCandidates returns error when thread status is not active | VERIFIED | `thread.service.ts:234` checks `thread.status !== "active"`, returns `{ success: false, error: "Thread not active" }` |
+| 5 | New candidates appended to end of rank (max sort_order + 1000) | VERIFIED | `createCandidate` queries MAX, sets `sortOrder: (maxRow?.maxOrder ?? 0) + 1000` (`thread.service.ts:150,171`) |
+| 6 | User can drag a candidate card to a new position in list view and it persists after page refresh | VERIFIED (code) | `handleDragEnd` is now wired via `onPointerUp={handleDragEnd}` on `<Reorder.Group>` at `$threadId.tsx:198`. Mutation fires on pointer-up after drag. Persistence needs human confirmation. |
+| 7 | Top 3 candidates display gold, silver, and bronze medal badges | VERIFIED (code) | `RankBadge` in `CandidateListItem.tsx:37-47` renders medal icon with `RANK_COLORS` for rank 1-3, returns null for rank > 3. Visual confirmation needed. |
+| 8 | Rank badges appear in both list view and grid view | VERIFIED | `CandidateCard.tsx:165` renders `{rank != null && <RankBadge rank={rank} />}`; `$threadId.tsx:258` passes `rank={index + 1}` to all grid cards |
+| 9 | Drag handles are hidden and drag is disabled on resolved threads | VERIFIED | `CandidateListItem.tsx:73` renders drag handle only if `isActive`; resolved threads render plain `<div>` (not `Reorder.Group`) at `$threadId.tsx:217` |
+| 10 | Rank badges remain visible on resolved threads | VERIFIED | Resolved thread renders `<CandidateListItem isActive={false}>` which always renders `<RankBadge rank={rank} />` at line 85 |
+| 11 | User can toggle between list and grid view with list as default | VERIFIED | `uiStore.ts:112` initializes `candidateViewMode: "list"`; toggle buttons in `$threadId.tsx:146-172` call `setCandidateViewMode` |
+
+**Score:** 11/11 truths verified (all pass automated checks; 3 require human visual confirmation)
+
+---
+
+## Required Artifacts
+
+### Plan 11-01 Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/db/schema.ts` | sortOrder REAL column on threadCandidates | VERIFIED | Line 64: `sortOrder: real("sort_order").notNull().default(0)` |
+| `src/shared/schemas.ts` | reorderCandidatesSchema Zod validator | VERIFIED | Line 66: `export const reorderCandidatesSchema = z.object({ orderedIds: ... })` |
+| `src/shared/types.ts` | ReorderCandidates type | VERIFIED | Line 37: `export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>` |
+| `src/server/services/thread.service.ts` | reorderCandidates function exported | VERIFIED | Lines 220+: full implementation exported; sortOrder used at lines 90, 150, 171, 240 |
+| `src/server/routes/threads.ts` | PATCH /:id/candidates/reorder endpoint | VERIFIED | Lines 129-140: registered with Zod validation |
+| `tests/helpers/db.ts` | sort_order column in CREATE TABLE | VERIFIED | Line 60: `sort_order REAL NOT NULL DEFAULT 0` |
+
+### Plan 11-02 Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/client/components/CandidateListItem.tsx` | Horizontal list card with drag handle and rank badge (min 60 lines) | VERIFIED | 211 lines; `Reorder.Item` with `useDragControls`, drag handle (lines 73-82), `RankBadge` (line 85) |
+| `src/client/routes/threads/$threadId.tsx` | Reorder.Group wrapping + tempItems pattern + handleDragEnd on Reorder.Group | VERIFIED | `Reorder.Group` at line 194 with `onPointerUp={handleDragEnd}` at line 198; `tempItems` pattern at lines 28-37, 76 |
+| `src/client/hooks/useCandidates.ts` | useReorderCandidates mutation hook | VERIFIED | Lines 66-78: calls `apiPatch` to `candidates/reorder`, invalidates query on settled |
+| `src/client/stores/uiStore.ts` | candidateViewMode state | VERIFIED | Lines 53-54 (interface), 112-113 (implementation): default "list" |
+| `src/client/components/CandidateCard.tsx` | RankBadge on grid cards | VERIFIED | Imports `RankBadge` from `CandidateListItem` (line 6); renders at line 165 when `rank != null` |
+
+---
+
+## Key Link Verification
+
+### Plan 11-01 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `threads.ts` | `thread.service.ts` | `reorderCandidates(db, threadId, orderedIds)` | WIRED | Line 136 imports and calls `reorderCandidates` |
+| `threads.ts` | `schemas.ts` | `zValidator with reorderCandidatesSchema` | WIRED | Line 8 imports `reorderCandidatesSchema`; line 131 uses `zValidator("json", reorderCandidatesSchema)` |
+| `thread.service.ts` | `schema.ts` | `threadCandidates.sortOrder in ORDER BY and UPDATE` | WIRED | Line 90 uses `asc(threadCandidates.sortOrder)`; line 240 sets `sortOrder: (i+1)*1000` |
+
+### Plan 11-02 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `threads/$threadId.tsx` | `useCandidates.ts` | `useReorderCandidates(threadId)` | WIRED | Line 7 imports, line 26 calls `useReorderCandidates(threadId)` |
+| `useCandidates.ts` | `/api/threads/:id/candidates/reorder` | `apiPatch` | WIRED | Lines 70-73: `apiPatch<{ success: boolean }>(\`/api/threads/${threadId}/candidates/reorder\`, data)` |
+| `threads/$threadId.tsx` | `framer-motion` | `Reorder.Group + Reorder.Item` | WIRED | Line 2 imports `{ Reorder }`; line 194 uses `<Reorder.Group>` |
+| `CandidateListItem.tsx` | `framer-motion` | `Reorder.Item + useDragControls` | WIRED | Line 1 imports `{ Reorder, useDragControls }`; line 55 calls `useDragControls()` |
+| `uiStore.ts` | `threads/$threadId.tsx` | `candidateViewMode state` | WIRED | Lines 23-24 consume `candidateViewMode`/`setCandidateViewMode`; lines 148-170 use them in toggle buttons |
+| `Reorder.Group` | `reorderMutation` | `handleDragEnd via onPointerUp` | WIRED | `onPointerUp={handleDragEnd}` is on the active-thread `<Reorder.Group>` at line 198. `handleDragEnd` at lines 78-84 calls `reorderMutation.mutate`. Fix confirmed. |
+
+---
+
+## Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-------------|-------------|--------|----------|
+| RANK-01 | 11-01, 11-02 | User can drag candidates to reorder priority ranking | SATISFIED | Drag via framer-motion `Reorder.Group`; `handleDragEnd` now wired at `onPointerUp` on active `Reorder.Group` (line 198); mutation fires `PATCH /api/threads/:id/candidates/reorder` |
+| RANK-02 | 11-02 | Top 3 ranked candidates display rank badges (gold, silver, bronze) | SATISFIED | `RankBadge` renders medal icon with `RANK_COLORS`; used in both `CandidateListItem` (line 85) and `CandidateCard` (line 165) |
+| RANK-04 | 11-01, 11-02 | Candidate rank order persists across sessions | SATISFIED | `sort_order` column in DB; `reorderCandidates` service updates it in a transaction; React Query invalidates on `onSettled` so next load fetches fresh sorted order |
+| RANK-05 | 11-01, 11-02 | Drag handles and ranking disabled on resolved threads | SATISFIED | `CandidateListItem.tsx:73` renders drag handle only if `isActive`; resolved threads use plain `<div>` without `Reorder.Group`; service returns 400 if thread not active |
+
+Note: RANK-03 (pros/cons fields) was handled in Phase 10 and is not part of Phase 11.
+
+---
+
+## Anti-Patterns Found
+
+No blockers or warnings detected in the fixed code.
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| — | — | — | — | No anti-patterns found |
+
+Previously identified blockers have been resolved: `onPointerUp={handleDragEnd}` is now correctly placed on the active `<Reorder.Group>` and absent from the resolved-thread `<div>`.
+
+---
+
+## Human Verification Required
+
+### 1. Drag persistence after refresh
+
+**Test:** Open an active thread with 3+ candidates, drag a candidate to a different position (e.g. drag position 3 to position 1), then refresh the page.
+**Expected:** The new order is preserved after refresh. The `PATCH /api/threads/:id/candidates/reorder` call fires on pointer-up, and the invalidated React Query refetch loads the persisted sort order.
+**Why human:** Real-time drag animation quality, gap animation between items, pointer-event timing, and the full round-trip to the server cannot be confirmed by static code analysis.
+
+### 2. Gold/silver/bronze badge colors
+
+**Test:** Open an active thread with 3+ candidates and view in list mode.
+**Expected:** Position 1 shows a gold medal icon (`#D4AF37`), position 2 shows silver (`#C0C0C0`), position 3 shows bronze (`#CD7F32`). Positions 4 and above show no badge. Toggle to grid view and verify the same badges appear on the first 3 cards.
+**Why human:** Hex color rendering accuracy and icon (medal) correctness need visual confirmation.
+
+### 3. Drag handle visibility on resolved threads
+
+**Test:** Navigate to a resolved thread in list view.
+**Expected:** No GripVertical drag handle icons are visible. Gold/silver/bronze rank badges are still present on the top 3 candidates in their sorted order. Candidates cannot be dragged.
+**Why human:** Conditional rendering of drag handles and static-only resolved state need visual verification.
+
+---
+
+## Gap Closure Confirmation
+
+The single gap from the previous verification has been closed:
+
+**Gap:** `onPointerUp={handleDragEnd}` was on the resolved-thread `<div>` (isActive=false path) only; the active `<Reorder.Group>` had no handler to trigger the mutation.
+
+**Fix:** `src/client/routes/threads/$threadId.tsx` line 198 — `onPointerUp={handleDragEnd}` is now on `<Reorder.Group axis="y" values={displayItems} onReorder={setTempItems} onPointerUp={handleDragEnd}>`. The resolved-thread `<div>` at lines 217-233 has no `onPointerUp`. The wiring is correct.
+
+**Regression check:** 135/135 tests pass. All previously-verified artifacts and key links remain intact.
+
+---
+
+_Verified: 2026-03-16T23:30:00Z_
+_Verifier: Claude (gsd-verifier)_
+_Re-verification: Yes — gap closure after previous gaps_found verdict_

.planning/phases/12-comparison-view/12-01-PLAN.md

@@ -0,0 +1,321 @@
+---
+phase: 12-comparison-view
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/client/components/ComparisonTable.tsx
+  - src/client/stores/uiStore.ts
+  - src/client/routes/threads/$threadId.tsx
+autonomous: true
+requirements: [COMP-01, COMP-02, COMP-03, COMP-04]
+
+must_haves:
+  truths:
+    - "User can toggle to a Compare view when a thread has 2+ candidates"
+    - "Comparison table shows all candidates side-by-side with weight, price, images, notes, links, status, pros, and cons"
+    - "The lightest candidate weight cell has a blue highlight; the cheapest candidate price cell has a green highlight"
+    - "Non-best cells show a gray +delta string; best cells show no delta"
+    - "The table scrolls horizontally on narrow viewports while the attribute label column stays fixed on the left"
+    - "Missing weight or price data displays a dash, never a misleading zero"
+    - "A resolved thread shows the comparison read-only with the winner column visually marked (amber tint + trophy)"
+  artifacts:
+    - path: "src/client/components/ComparisonTable.tsx"
+      provides: "Tabular side-by-side comparison component"
+      min_lines: 120
+    - path: "src/client/stores/uiStore.ts"
+      provides: "Extended candidateViewMode union type including 'compare'"
+      contains: "compare"
+    - path: "src/client/routes/threads/$threadId.tsx"
+      provides: "Compare toggle button and ComparisonTable rendering branch"
+      contains: "ComparisonTable"
+  key_links:
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/components/ComparisonTable.tsx"
+      via: "import and conditional render when candidateViewMode === 'compare'"
+      pattern: "candidateViewMode.*compare"
+    - from: "src/client/components/ComparisonTable.tsx"
+      to: "src/client/lib/formatters.ts"
+      via: "formatWeight and formatPrice for cell values and delta strings"
+      pattern: "formatWeight|formatPrice"
+    - from: "src/client/components/ComparisonTable.tsx"
+      to: "src/client/components/CandidateListItem.tsx"
+      via: "RankBadge import for rank row"
+      pattern: "RankBadge"
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/stores/uiStore.ts"
+      via: "candidateViewMode state read and setCandidateViewMode action"
+      pattern: "candidateViewMode"
+---
+
+<objective>
+Build the side-by-side candidate comparison table for research threads. Users toggle into compare mode from the existing view-mode bar and see all candidates as columns in a horizontally-scrollable table with sticky attribute labels, weight/price delta highlighting, and resolved-thread winner marking.
+
+Purpose: Enables users to directly compare candidates on weight, price, status, notes, pros, and cons without switching between cards -- the key decision-support view for the Research & Decision Tools milestone.
+
+Output: One new component (`ComparisonTable.tsx`), two modified files (`uiStore.ts`, `$threadId.tsx`).
+</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/12-comparison-view/12-CONTEXT.md
+@.planning/phases/12-comparison-view/12-RESEARCH.md
+
+@src/client/stores/uiStore.ts
+@src/client/routes/threads/$threadId.tsx
+@src/client/hooks/useThreads.ts
+@src/client/lib/formatters.ts
+@src/client/components/CandidateListItem.tsx
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+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;
+  status: "researching" | "ordered" | "arrived";
+  pros: string | null;
+  cons: string | null;
+  createdAt: string;
+  updatedAt: string;
+  categoryName: string;
+  categoryIcon: string;
+}
+
+interface ThreadWithCandidates {
+  id: number;
+  name: string;
+  status: "active" | "resolved";
+  resolvedCandidateId: number | null;
+  createdAt: string;
+  updatedAt: string;
+  candidates: CandidateWithCategory[];
+}
+```
+
+From src/client/lib/formatters.ts:
+```typescript
+export type WeightUnit = "g" | "oz" | "lb" | "kg";
+export type Currency = "USD" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD";
+export function formatWeight(grams: number | null | undefined, unit?: WeightUnit): string; // returns "--" for null
+export function formatPrice(cents: number | null | undefined, currency?: Currency): string; // returns "--" for null
+```
+
+From src/client/components/CandidateListItem.tsx:
+```typescript
+export function RankBadge({ rank }: { rank: number }): JSX.Element | null;
+// Returns null for rank > 3, renders gold/silver/bronze medal icon for 1/2/3
+```
+
+From src/client/stores/uiStore.ts (lines 52-54, current state):
+```typescript
+// Current type (will be extended):
+candidateViewMode: "list" | "grid";
+setCandidateViewMode: (mode: "list" | "grid") => void;
+```
+
+From src/client/lib/iconData.tsx:
+```typescript
+export function LucideIcon({ name, size, className, style }: LucideIconProps): JSX.Element;
+// Renders any Lucide icon by kebab-case name string
+```
+
+From src/client/hooks/useWeightUnit.ts:
+```typescript
+export function useWeightUnit(): WeightUnit; // reads from settings API
+```
+
+From src/client/hooks/useCurrency.ts:
+```typescript
+export function useCurrency(): Currency; // reads from settings API
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Build ComparisonTable component</name>
+  <files>src/client/components/ComparisonTable.tsx</files>
+  <action>
+Create `src/client/components/ComparisonTable.tsx` — a self-contained comparison table component.
+
+**Props interface:**
+```typescript
+interface ComparisonTableProps {
+  candidates: CandidateWithCategory[];
+  resolvedCandidateId: number | null;
+}
+```
+Import `CandidateWithCategory` type inline (duplicate the interface locally or import from useThreads — match project convention for component-local interfaces as seen in CandidateListItem.tsx which declares its own `CandidateWithCategory`).
+
+**Delta computation (useMemo):**
+- Weight deltas: Filter candidates with non-null `weightGrams`. Find the minimum. For each candidate, compute `delta = weightGrams - min`. If `delta === 0` (this IS the best), store `null` as delta string. Otherwise store `+${formatWeight(delta, unit)}`. Track `bestWeightId`. If all candidates have null weight, `bestWeightId = null`.
+- Price deltas: Same logic for `priceCents` with `formatPrice(delta, currency)`. Track `bestPriceId`.
+- Use `useWeightUnit()` and `useCurrency()` hooks for unit/currency-aware formatting.
+
+**Table structure:**
+- Outer: `<div className="overflow-x-auto rounded-xl border border-gray-100">` (scroll wrapper)
+- Inner: `<table>` with `style={{ minWidth: Math.max(400, candidates.length * 180) + 'px' }}` and `className="border-collapse text-sm w-full"`
+- `<thead>`: One `<tr>` with sticky corner `<th>` (empty, for label column) + one `<th>` per candidate showing name. If `candidate.id === resolvedCandidateId`, apply `bg-amber-50 text-amber-800` and prepend a trophy icon: `<LucideIcon name="trophy" size={12} className="text-amber-600" />`.
+- `<tbody>`: Render rows using a declarative ATTRIBUTE_ROWS array (see below).
+
+**Sticky left column CSS (CRITICAL):**
+Every `<td>` and `<th>` in the first (label) column MUST have: `sticky left-0 z-10 bg-white`. Without `bg-white`, scrolled content bleeds through. Use `z-10` (not higher — avoid conflicts with panels/modals).
+
+**Attribute row order** (per locked decision): Image, Name, Rank, Weight (with delta), Price (with delta), Status, Product Link, Notes, Pros, Cons.
+
+**Row rendering — use a declarative array pattern:**
+Define `ATTRIBUTE_ROWS` as an array of `{ key, label, render(candidate) }`. This keeps the JSX clean and makes row reordering trivial. Build this array inside the component function body (after useMemo hooks) so it can close over `weightDeltas`, `priceDeltas`, `bestWeightId`, `bestPriceId`, `unit`, `currency`.
+
+**Cell renderers:**
+- **Image**: 48x48 rounded-lg container. If `imageFilename`, render `<img src="/uploads/${imageFilename}" />` with `object-cover`. Else render `<LucideIcon name={categoryIcon} size={20} className="text-gray-400" />` in a `bg-gray-50` placeholder. Use `w-12 h-12` sizing.
+- **Name**: `<span className="text-sm font-medium text-gray-900">{name}</span>`
+- **Rank**: Reuse `<RankBadge rank={index + 1} />` imported from CandidateListItem. Rank is derived from array position (candidates are already sorted by sort_order from the API).
+- **Weight**: Show `formatWeight(weightGrams, unit)` as primary value in `font-medium text-gray-900`. If this is the best (`isBest`), apply `bg-blue-50` to the `<td>`. If delta string exists (not null, not best), show delta below in `text-xs text-gray-400`. If `weightGrams` is null, show `<span className="text-gray-300">—</span>`.
+- **Price**: Same pattern as weight but with `formatPrice(priceCents, currency)` and `bg-green-50` for the best cell.
+- **Status**: Render as static text `<span className="text-xs text-gray-600">{STATUS_LABELS[status]}</span>`. Define STATUS_LABELS map: `{ researching: "Researching", ordered: "Ordered", arrived: "Arrived" }`. No click-to-cycle in compare view — comparison is for reading, not mutation.
+- **Product Link**: If `productUrl` exists, render a clickable link that calls `openExternalLink(productUrl)` from uiStore: `<button onClick={() => openExternalLink(productUrl)} className="text-xs text-blue-500 hover:underline">View</button>`. If null, render `<span className="text-gray-300">—</span>`. Links remain clickable even in resolved threads (read-only means no mutations, but navigation is fine).
+- **Notes**: If `notes` exists, render `<p className="text-xs text-gray-700 whitespace-pre-line">{notes}</p>` (whitespace-pre-line preserves newlines). If null, render em dash placeholder.
+- **Pros**: If `pros` exists, split on `"\n"`, filter empty strings, render as `<ul className="list-disc list-inside space-y-0.5">` with `<li className="text-xs text-gray-700">` items. If null, render em dash placeholder.
+- **Cons**: Same as Pros rendering.
+
+**Winner column highlight (resolved threads):**
+When `resolvedCandidateId` is set, the winner's `<th>` in the header gets `bg-amber-50 text-amber-800` + trophy icon. Each body `<td>` for the winner column gets a subtle `bg-amber-50/50` tint (half-opacity amber). This must not conflict with the best-weight/best-price blue/green highlights — when both apply (winner IS also lightest), use the weight/price highlight color (it's more informative).
+
+**Row styling:**
+- Each `<tr>` gets `border-b border-gray-50` for subtle row separation.
+- Label `<td>` cells: `text-xs font-medium text-gray-500 uppercase tracking-wide w-28`.
+- Data `<td>` cells: `px-4 py-3 min-w-[160px]`.
+- Header `<th>` cells: `px-4 py-3 text-left text-xs font-medium text-gray-700 min-w-[160px]`.
+
+**Table border + rounding:**
+The outer wrapper has `rounded-xl border border-gray-100`. Add `overflow-hidden` to the wrapper alongside `overflow-x-auto` to clip the table's corners to the rounded border: `className="overflow-x-auto overflow-hidden rounded-xl border border-gray-100"`. Actually, use `overflow-x-auto` on an outer div, and put the border/rounding there. The table itself does not need border-radius.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -20</automated>
+  </verify>
+  <done>ComparisonTable.tsx exists with all 10 attribute rows, delta computation via useMemo, sticky left column with bg-white, horizontal scroll wrapper, blue/green best-cell highlights, gray delta text for non-best, amber winner column for resolved threads, em dash for missing data (never zero).</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Wire compare toggle and ComparisonTable into thread detail</name>
+  <files>src/client/stores/uiStore.ts, src/client/routes/threads/$threadId.tsx</files>
+  <action>
+**Step 1: Extend uiStore candidateViewMode (src/client/stores/uiStore.ts)**
+
+Change the type union on lines 53-54 from:
+```typescript
+candidateViewMode: "list" | "grid";
+setCandidateViewMode: (mode: "list" | "grid") => void;
+```
+to:
+```typescript
+candidateViewMode: "list" | "grid" | "compare";
+setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
+```
+
+No other changes needed in uiStore — the implementation lines 112-113 are generic and already work with the wider type.
+
+**Step 2: Add compare toggle button (src/client/routes/threads/$threadId.tsx)**
+
+In the toolbar toggle bar (the `<div className="flex items-center gap-1 bg-gray-100 rounded-lg p-0.5">` block around line 146), add a third button for compare mode. The compare button should only render when `thread.candidates.length >= 2` (per locked decision).
+
+Add the compare button after the grid button but inside the toggle container:
+```tsx
+{thread.candidates.length >= 2 && (
+  <button
+    type="button"
+    onClick={() => setCandidateViewMode("compare")}
+    className={`p-1.5 rounded-md transition-colors ${
+      candidateViewMode === "compare"
+        ? "bg-gray-200 text-gray-900"
+        : "text-gray-400 hover:text-gray-600"
+    }`}
+    title="Compare view"
+  >
+    <LucideIcon name="columns-3" size={16} />
+  </button>
+)}
+```
+
+Also: Hide the "Add Candidate" button when in compare view. Change the existing `{isActive && (` guard (around line 123) to `{isActive && candidateViewMode !== "compare" && (`. This keeps the toolbar uncluttered — users switch to list/grid to add candidates.
+
+**Step 3: Add ComparisonTable rendering branch ($threadId.tsx)**
+
+Import ComparisonTable at the top of the file:
+```typescript
+import { ComparisonTable } from "../../components/ComparisonTable";
+```
+
+In the candidates rendering section (starting around line 192), add a compare branch BEFORE the existing list check:
+```tsx
+) : candidateViewMode === "compare" ? (
+  <ComparisonTable
+    candidates={displayItems}
+    resolvedCandidateId={thread.resolvedCandidateId}
+  />
+) : candidateViewMode === "list" ? (
+  // ... existing list rendering (unchanged)
+) : (
+  // ... existing grid rendering (unchanged)
+)
+```
+
+Pass `displayItems` (not `thread.candidates`) so the order reflects any pending drag reorder state, though in compare mode drag is not active — `displayItems` will equal `thread.candidates` when `tempItems` is null.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -20 && bun test 2>&1 | tail -5</automated>
+  </verify>
+  <done>uiStore accepts "compare" as a candidateViewMode value. Thread detail page shows a third toggle icon (columns-3) when 2+ candidates exist. Clicking it renders ComparisonTable. "Add Candidate" button is hidden in compare mode. Existing list/grid views still work unchanged. All existing tests pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+1. `bun run lint` passes with no errors
+2. `bun test` full suite passes (no backend changes, existing tests unaffected)
+3. Manual browser verification:
+   - Navigate to a thread with 2+ candidates
+   - Verify the compare icon (columns-3) appears in the toggle bar
+   - Click compare icon -> tabular comparison renders with candidates as columns
+   - Verify attribute row order: Image, Name, Rank, Weight, Price, Status, Link, Notes, Pros, Cons
+   - Verify lightest weight cell has blue-50 tint, cheapest price cell has green-50 tint
+   - Verify non-best cells show gray +delta text
+   - Verify missing weight/price shows em dash (not zero)
+   - Resize viewport narrow -> table scrolls horizontally, label column stays fixed
+   - Navigate to a resolved thread -> winner column has amber tint + trophy, no mutation controls
+   - Toggle back to list/grid views -> they still work correctly
+   - Thread with 0 or 1 candidate -> compare icon does not appear
+</verification>
+
+<success_criteria>
+- ComparisonTable.tsx renders all 10 attribute rows with correct data
+- Delta highlighting: blue-50 on lightest weight, green-50 on cheapest price, gray delta text on non-best
+- Sticky label column with solid bg-white stays visible during horizontal scroll
+- Resolved threads show winner column with amber-50 tint and trophy icon
+- Missing data renders as em dash, never as zero (COMP-04)
+- Compare toggle icon appears only when >= 2 candidates
+- All existing tests continue to pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/12-comparison-view/12-01-SUMMARY.md`
+</output>

.planning/phases/12-comparison-view/12-01-SUMMARY.md

@@ -0,0 +1,110 @@
+---
+phase: 12-comparison-view
+plan: "01"
+subsystem: ui
+tags: [react, tailwind, comparison-table, zustand, framer-motion]
+
+# Dependency graph
+requires:
+  - phase: 11-candidate-ranking
+    provides: RankBadge component and sort_order-based candidate ordering
+  - phase: 10-schema-foundation-pros-cons-fields
+    provides: pros/cons fields on CandidateWithCategory type
+provides:
+  - ComparisonTable component with sticky label column and horizontal scroll
+  - candidateViewMode "compare" value in uiStore
+  - Compare toggle in thread detail toolbar (visible when 2+ candidates)
+  - Weight/price delta highlighting with best-cell color coding
+  - Resolved thread winner column marking (amber tint + trophy)
+affects: [future comparison features, thread detail enhancements]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Declarative ATTRIBUTE_ROWS array pattern for table row rendering (key, label, render, cellClass)
+    - useMemo delta computation for best-cell identification in comparison views
+
+key-files:
+  created:
+    - src/client/components/ComparisonTable.tsx
+  modified:
+    - src/client/stores/uiStore.ts
+    - src/client/routes/threads/$threadId.tsx
+
+key-decisions:
+  - "ATTRIBUTE_ROWS declarative array pattern keeps JSX clean and row reordering trivial"
+  - "cellClass function pattern in ATTRIBUTE_ROWS allows per-row cell styling without duplicating winner-check logic in every render"
+  - "Compare toggle only shown when >= 2 candidates (locked decision from plan)"
+  - "Add Candidate button hidden in compare view — compare is for reading, not mutation"
+  - "Winner highlight priority: weight/price color wins over amber tint when both apply (more informative)"
+
+patterns-established:
+  - "Declarative table row config: ATTRIBUTE_ROWS array with { key, label, render, cellClass } objects"
+  - "Sticky left column pattern: sticky left-0 z-10 bg-white on every label cell for scroll bleed prevention"
+
+requirements-completed: [COMP-01, COMP-02, COMP-03, COMP-04]
+
+# Metrics
+duration: 2min
+completed: 2026-03-17
+---
+
+# Phase 12 Plan 01: Comparison View Summary
+
+**Side-by-side candidate comparison table with sticky labels, weight/price delta highlighting, and resolved-thread winner marking via a new "compare" candidateViewMode**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-17T14:28:12Z
+- **Completed:** 2026-03-17T14:30:00Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Built ComparisonTable component with 10 attribute rows (Image, Name, Rank, Weight, Price, Status, Link, Notes, Pros, Cons) using declarative ATTRIBUTE_ROWS pattern
+- Implemented useMemo delta computation — lightest weight cell highlighted blue-50, cheapest price cell green-50, non-best cells show gray +delta string
+- Sticky left column with bg-white prevents content bleed-through on horizontal scroll
+- Amber tint + trophy icon on winner column in resolved threads; weight/price color takes priority when winner is also best
+- Extended uiStore candidateViewMode to "list" | "grid" | "compare" and wired compare toggle in thread detail toolbar
+- Compare toggle only appears when thread has 2+ candidates; Add Candidate button hidden in compare view
+- All 135 existing tests pass, no regressions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Build ComparisonTable component** - `e442b33` (feat)
+2. **Task 2: Wire compare toggle and ComparisonTable into thread detail** - `5b4026d` (feat)
+
+## Files Created/Modified
+- `src/client/components/ComparisonTable.tsx` - New comparison table component with all 10 attribute rows, delta computation, sticky labels, and winner highlighting
+- `src/client/stores/uiStore.ts` - Extended candidateViewMode union to include "compare"
+- `src/client/routes/threads/$threadId.tsx` - Added ComparisonTable import, compare toggle button (columns-3 icon), ComparisonTable rendering branch, and "Add Candidate" hidden in compare view
+
+## Decisions Made
+- ATTRIBUTE_ROWS declarative array pattern keeps table JSX clean and row reordering trivial — each row is just { key, label, render, cellClass }
+- cellClass function in ATTRIBUTE_ROWS allows per-row cell styling without duplicating winner-check logic in every render function
+- Compare toggle only shown for 2+ candidates per locked plan decision
+- Add Candidate button hidden in compare view to keep toolbar uncluttered (users switch to list/grid to add)
+- When winner IS also the lightest/cheapest, weight/price color (blue/green) takes priority over amber tint — more informative
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- Minor formatting differences caught by Biome auto-formatter (indentation depth in conditional JSX) — resolved with `biome check --write`. No logic changes.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- ComparisonTable is complete and functional; compare mode wired end-to-end in thread detail
+- No blockers — ready for any follow-on comparison view enhancements
+- All existing tests pass; no backend changes needed
+
+---
+*Phase: 12-comparison-view*
+*Completed: 2026-03-17*

.planning/phases/12-comparison-view/12-RESEARCH.md

@@ -0,0 +1,541 @@
+# Phase 12: Comparison View - Research
+
+**Researched:** 2026-03-17
+**Domain:** React tabular UI, CSS sticky columns, horizontal scroll, delta computation
+**Confidence:** HIGH
+
+## Summary
+
+Phase 12 is a pure frontend phase. No backend changes, no schema changes, no new npm packages. All required data is already returned by `useThread(threadId)` — candidates carry `weightGrams`, `priceCents`, `status`, `productUrl`, `notes`, `pros`, `cons`, `imageFilename`, `categoryIcon`, and rank is derived from sort_order position in the array. The work is entirely in building a `ComparisonTable` component, wiring a third toggle button into the existing view-mode bar, and extending the `candidateViewMode` Zustand union type.
+
+The core CSS challenge is the sticky-first-column + horizontal-scroll table pattern. Modern CSS handles this well as long as `overflow-x: auto` is placed on a wrapper `<div>`, not the `<table>` element itself, and the sticky `<td>` cells in the label column have an explicit background color (otherwise scrolling content bleeds through). Z-index layering is simple for this use case because there is only one sticky axis (the left label column); no sticky top header is needed since the table is not vertically scrollable.
+
+Delta computation is straightforward arithmetic: find the minimum `weightGrams` across candidates that have a value, subtract each candidate's value from that minimum to produce a delta, and render a `+Xg` or `—` string. The "best" cell gets `bg-blue-50` for weight (matching existing blue weight pill color) or `bg-green-50` for price (matching existing green price pill color). Missing data must never display as "0" — a dash placeholder is required by COMP-04, and `formatWeight(null)` already returns `"--"`.
+
+**Primary recommendation:** Build `ComparisonTable.tsx` as a self-contained component that accepts `candidates[]` and `resolvedCandidateId | null`, computes deltas internally with `useMemo`, renders a `<div className="overflow-x-auto">` wrapper around a plain `<table>`, and uses `sticky left-0 bg-white z-10` on the label `<td>` cells.
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- Compare mode entry point: Add a third icon to the existing list/grid toggle bar, making it list | grid | compare (three-way toggle)
+- Use `candidateViewMode: 'list' | 'grid' | 'compare'` in uiStore — extends the existing Zustand state
+- Compare icon only appears when 2+ candidates exist in the thread (hidden otherwise)
+- Table orientation: Candidates as columns, attribute labels as rows (classic product-comparison pattern — Amazon/Wirecutter style)
+- Sticky left column for attribute labels; table scrolls horizontally on narrow viewports
+- Attribute row order: Image → Name → Rank → Weight (with delta) → Price (with delta) → Status → Product Link → Notes → Pros → Cons
+- Delta highlighting style: Lightest candidate's weight cell gets a subtle colored background tint (e.g., bg-green-50); cheapest similarly
+- Non-best cells show delta text in neutral gray — no colored badges for deltas, only the "best" cell gets color
+
+### Claude's Discretion
+- "Add Candidate" button visibility when in compare view
+- Image thumbnail sizing in comparison cells (square crop vs wider aspect)
+- Multi-line text rendering strategy (clamped with expand vs full text)
+- Missing data indicator style (dash with label, empty cell, etc.)
+- Delta format: absolute value + delta underneath, or delta only for non-best cells
+- Winner column marking approach (column tint, trophy icon, or both)
+- Resolved thread interactivity (links clickable vs all read-only)
+- Resolution banner behavior in compare view
+- View mode persistence (already in Zustand — whether compare resets on navigation or persists)
+- Compare toggle icon choice (e.g., Lucide `columns-3`, `table-2`, or similar)
+- Table cell padding, border styling, and overall table chrome
+- Column minimum/maximum widths
+- Keyboard accessibility for horizontal scrolling
+
+### Deferred Ideas (OUT OF SCOPE)
+None — discussion stayed within phase scope
+</user_constraints>
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| COMP-01 | User can view candidates side-by-side in a tabular comparison layout (weight, price, images, notes, links, status) | ComparisonTable component; all fields available from useThread hook; no backend changes needed |
+| COMP-02 | User can see relative deltas highlighting the lightest and cheapest candidate with +/- differences | Delta computation via array reduce; best-cell highlight via bg-blue-50 (weight) / bg-green-50 (price); gray delta text for non-best |
+| COMP-03 | Comparison table scrolls horizontally with a sticky label column on narrow viewports | overflow-x-auto wrapper div + sticky left-0 bg-white z-10 on label td cells |
+| COMP-04 | Comparison view displays read-only summary for resolved threads | resolvedCandidateId from useThread; disable mutation actions; winner column visual tint; resolved check pattern established in Phase 11 |
+</phase_requirements>
+
+---
+
+## Standard Stack
+
+### Core (all already installed — no new packages needed)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| React 19 | ^19.2.4 | Component rendering | Project stack |
+| Tailwind CSS | v4 | Utility styling | Project stack |
+| Zustand | ^5.0.11 | candidateViewMode state | Already used for list/grid toggle |
+| lucide-react | ^0.577.0 | Toggle icon (`columns-3` confirmed present) | All icons use LucideIcon helper |
+| framer-motion | ^12.37.0 | Optional AnimatePresence for view transition | Already installed |
+
+### Supporting Utilities (already in project)
+| Utility | Location | Purpose |
+|---------|----------|---------|
+| `formatWeight(grams, unit)` | `src/client/lib/formatters.ts` | Weight cell values and delta strings; returns `"--"` for null |
+| `formatPrice(cents, currency)` | `src/client/lib/formatters.ts` | Price cell values and delta strings; returns `"--"` for null |
+| `useWeightUnit()` | `src/client/hooks/useWeightUnit.ts` | Current unit setting |
+| `useCurrency()` | `src/client/hooks/useCurrency.ts` | Current currency setting |
+| `useThread(threadId)` | `src/client/hooks/useThreads.ts` | All candidate data |
+| `RankBadge` | `src/client/components/CandidateListItem.tsx` | Rank medal icons (exported) |
+| `LucideIcon` | `src/client/lib/iconData.tsx` | Icon rendering with fallback |
+
+---
+
+## Architecture Patterns
+
+### Recommended File Structure
+```
+src/client/
+├── components/
+│   └── ComparisonTable.tsx     # New: tabular comparison component
+├── stores/
+│   └── uiStore.ts              # Modify: extend candidateViewMode union type
+└── routes/threads/
+    └── $threadId.tsx           # Modify: add compare branch + third toggle button
+```
+
+### Pattern 1: Sticky Left Column with Horizontal Scroll
+
+**What:** Wrap `<table>` in `<div className="overflow-x-auto">`. Apply `sticky left-0 bg-white z-10` to every `<td>` and `<th>` in the first (label) column.
+
+**When to use:** Any time a table needs a frozen left column with horizontal scrolling.
+
+**Critical pitfall:** The sticky `td` cells MUST have a solid background color. Without `bg-white`, scrolling content bleeds through the "sticky" cell because the cell is transparent.
+
+**Example:**
+```tsx
+// Outer wrapper enables horizontal scroll
+<div className="overflow-x-auto rounded-xl border border-gray-100">
+  <table
+    className="border-collapse text-sm"
+    style={{ minWidth: `${Math.max(400, candidates.length * 180)}px` }}
+  >
+    <thead>
+      <tr className="border-b border-gray-100">
+        {/* Sticky corner cell — bg-white mandatory */}
+        <th className="sticky left-0 z-10 bg-white px-4 py-3 text-left text-xs font-medium text-gray-400 uppercase tracking-wide w-28" />
+        {candidates.map((c) => (
+          <th key={c.id} className="px-4 py-3 text-left text-xs font-medium text-gray-700 min-w-[160px]">
+            {c.name}
+          </th>
+        ))}
+      </tr>
+    </thead>
+    <tbody>
+      {ATTRIBUTE_ROWS.map((row) => (
+        <tr key={row.key} className="border-b border-gray-50">
+          {/* Sticky label cell — bg-white mandatory */}
+          <td className="sticky left-0 z-10 bg-white px-4 py-3 text-xs font-medium text-gray-500">
+            {row.label}
+          </td>
+          {candidates.map((c) => (
+            <td key={c.id} className="px-4 py-3">
+              {row.render(c)}
+            </td>
+          ))}
+        </tr>
+      ))}
+    </tbody>
+  </table>
+</div>
+```
+
+### Pattern 2: Delta Computation (null-safe, useMemo)
+
+**What:** Derive the "best" candidate and compute deltas before rendering. Use `useMemo` keyed on `candidates` to avoid recomputing on every render.
+
+**Example:**
+```tsx
+// Source: derived from project formatters.ts patterns
+const { weightDeltas, bestWeightId } = useMemo(() => {
+  const withWeight = candidates.filter((c) => c.weightGrams != null);
+  if (withWeight.length === 0) return { weightDeltas: new Map<number, string | null>(), bestWeightId: null };
+
+  const minGrams = Math.min(...withWeight.map((c) => c.weightGrams as number));
+  const bestWeightId = withWeight.find((c) => c.weightGrams === minGrams)!.id;
+
+  const weightDeltas = new Map(
+    candidates.map((c) => {
+      if (c.weightGrams == null) return [c.id, null]; // null = missing data
+      const delta = c.weightGrams - minGrams;
+      return [c.id, delta === 0 ? null : `+${formatWeight(delta, unit)}`];
+      // delta === 0 means this IS the best — no delta string needed
+    })
+  );
+  return { weightDeltas, bestWeightId };
+}, [candidates, unit]);
+```
+
+### Pattern 3: Extending Zustand Union Type
+
+**What:** Widen the existing `candidateViewMode` type from `'list' | 'grid'` to `'list' | 'grid' | 'compare'`. The implementation setter line is unchanged.
+
+**Example:**
+```typescript
+// In uiStore.ts — only two type declaration lines change (lines 53-54):
+candidateViewMode: "list" | "grid" | "compare";
+setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
+
+// Implementation lines 112-113 — unchanged:
+candidateViewMode: "list",
+setCandidateViewMode: (mode) => set({ candidateViewMode: mode }),
+```
+
+### Pattern 4: Three-Way Toggle Button
+
+**What:** Add a third button to the existing `bg-gray-100 rounded-lg p-0.5` toggle bar in `$threadId.tsx`. Show compare button only when `thread.candidates.length >= 2`.
+
+**Example:**
+```tsx
+{thread.candidates.length >= 2 && (
+  <button
+    type="button"
+    onClick={() => setCandidateViewMode("compare")}
+    className={`p-1.5 rounded-md transition-colors ${
+      candidateViewMode === "compare"
+        ? "bg-gray-200 text-gray-900"
+        : "text-gray-400 hover:text-gray-600"
+    }`}
+    title="Compare view"
+  >
+    <LucideIcon name="columns-3" size={16} />
+  </button>
+)}
+```
+
+**Confirmed:** `columns-3` maps to `Columns3` in lucide-react ^0.577.0 and is present in the installed package (verified via `node -e "const {icons}=require('lucide-react'); console.log('Columns3' in icons)"`). Use `LucideIcon name="columns-3"` — the LucideIcon helper handles the `toPascalCase` conversion.
+
+### Pattern 5: Row Definition as Data
+
+**What:** Define the attribute rows as a declarative array, not hard-coded JSX branches. Each entry has a `key`, `label`, and a `render(candidate)` function. This makes row reordering trivial and matches the locked attribute order.
+
+**Example:**
+```tsx
+// Attribute row order per CONTEXT.md: Image → Name → Rank → Weight → Price → Status → Link → Notes → Pros → Cons
+const ATTRIBUTE_ROWS = [
+  { key: "image",  label: "Image",  render: (c: C) => <ImageCell candidate={c} /> },
+  { key: "name",   label: "Name",   render: (c: C) => <span className="text-sm font-medium text-gray-900">{c.name}</span> },
+  { key: "rank",   label: "Rank",   render: (c: C) => <RankBadge rank={rankOf(c)} /> },
+  { key: "weight", label: "Weight", render: (c: C) => <WeightCell candidate={c} delta={weightDeltas.get(c.id)} isBest={c.id === bestWeightId} unit={unit} /> },
+  { key: "price",  label: "Price",  render: (c: C) => <PriceCell candidate={c} delta={priceDeltas.get(c.id)} isBest={c.id === bestPriceId} currency={currency} /> },
+  { key: "status", label: "Status", render: (c: C) => <span className="text-xs text-gray-600">{STATUS_LABELS[c.status]}</span> },
+  { key: "link",   label: "Link",   render: (c: C) => c.productUrl ? <a href="#" onClick={() => openExternalLink(c.productUrl!)} className="text-xs text-blue-500 hover:underline">View</a> : <span className="text-gray-300">—</span> },
+  { key: "notes",  label: "Notes",  render: (c: C) => <TextCell text={c.notes} /> },
+  { key: "pros",   label: "Pros",   render: (c: C) => <BulletCell text={c.pros} /> },
+  { key: "cons",   label: "Cons",   render: (c: C) => <BulletCell text={c.cons} /> },
+];
+```
+
+### Pattern 6: Pros/Cons Rendering (confirmed newline-separated)
+
+**What:** `CandidateForm.tsx` uses a `<textarea>` with placeholder "One pro per line..." — users enter newline-separated text. The form submits `form.pros.trim() || undefined`, so empty = `undefined` → stored as `null` in DB. Non-empty content is raw text with `\n` separators.
+
+**How to render in compare table:**
+```tsx
+function BulletCell({ text }: { text: string | null }) {
+  if (!text) return <span className="text-gray-300">—</span>;
+  const items = text.split("\n").filter(Boolean);
+  if (items.length === 0) return <span className="text-gray-300">—</span>;
+  return (
+    <ul className="list-disc list-inside space-y-0.5">
+      {items.map((item, i) => (
+        <li key={i} className="text-xs text-gray-700">{item}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Anti-Patterns to Avoid
+
+- **Setting `overflow-x-auto` on `<table>` directly:** Has no effect in CSS. Must be on a wrapper `<div>`.
+- **Transparent sticky cells:** Sticky `<td>` cells without `bg-white` let scrolled content bleed through visually.
+- **Computing deltas inside render:** Use `useMemo` — compute once, not per render cycle.
+- **Using `overflow: hidden` on any ancestor of the sticky column:** Breaks the sticky positioning context.
+- **Missing data shown as "0":** `formatWeight(null)` already returns `"--"`. Guard delta computation with null checks before arithmetic.
+- **Rendering pros/cons as raw string:** Split on `\n` and render as `<ul>` — the form stores `\n`-separated text.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Weight/price formatting | Custom format functions | `formatWeight()` / `formatPrice()` in `formatters.ts` | Handles all units, currencies, null — returns `"--"` for null |
+| Rank medal icons | Custom SVG or color dots | `RankBadge` from `CandidateListItem.tsx` | Already exported, handles ranks 1-3 with correct colors |
+| Zustand state | Local useState for view mode | Existing `candidateViewMode` in `uiStore` | Persists across navigation, consistent with list/grid |
+| Icon rendering | Direct lucide component imports | `LucideIcon` helper from `iconData.tsx` | Handles fallback, consistent API across project |
+| Unit/currency awareness | Hardcode "g" or "$" | `useWeightUnit()` / `useCurrency()` | Reads from user settings |
+
+**Key insight:** This phase is almost entirely composition of already-built primitives. The delta computation logic and sticky column CSS are the only genuinely new work.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Sticky Cell Background Bleed-Through
+**What goes wrong:** The label column appears sticky but scrolling content renders on top of it, making text illegible.
+**Why it happens:** `position: sticky` keeps the element in its visual position but does not create an opaque layer. Without a background color the cell is transparent.
+**How to avoid:** Add `bg-white` to every sticky `<td>` and `<th>` in the label column. If alternating row backgrounds are used, the sticky cells must also match those background colors.
+**Warning signs:** Label text becomes unreadable when scrolling horizontally.
+
+### Pitfall 2: overflow-x-auto on Wrong Element
+**What goes wrong:** The table never scrolls horizontally regardless of viewport width.
+**Why it happens:** CSS `overflow` properties only apply to block/flex/grid containers. `<table>` is a table container — `overflow-x: auto` on `<table>` has no effect per CSS spec.
+**How to avoid:** Wrap `<table>` in `<div className="overflow-x-auto">`. Set `minWidth` on the `<table>` itself (not the wrapper) to force scrollability.
+**Warning signs:** Table content wraps aggressively instead of scrolling; columns collapse on narrow screens.
+
+### Pitfall 3: Delta Shows for Best Candidate
+**What goes wrong:** The lightest candidate shows "+0g" instead of just the value cleanly.
+**Why it happens:** Naive `delta = candidate - min` yields 0 for the best candidate.
+**How to avoid:** When `delta === 0`, return `null` for the delta string. The best-cell highlight color already communicates "this is best." Only non-best cells show a delta string.
+**Warning signs:** Best cell shows "+0g" or "+$0.00" alongside the colored highlight.
+
+### Pitfall 4: Missing Data Rendered as Zero (COMP-04 violation)
+**What goes wrong:** A candidate with `weightGrams: null` shows "0g" in the weight row, misleading the user.
+**Why it happens:** Passing `null` through subtraction arithmetic silently produces 0 in JavaScript.
+**How to avoid:** Guard before computing: `if (c.weightGrams == null) return [c.id, null]`. In the cell renderer, when value is null, render `—` (em dash).
+**Warning signs:** COMP-04 violated; user appears to see "0g" for an item with no weight entered.
+
+### Pitfall 5: z-index Conflicts with Panels/Dropdowns
+**What goes wrong:** Sticky label column renders above the SlideOutPanel or modal overlays.
+**Why it happens:** Using `z-index: 50` or higher on sticky cells competes with panel z-index values.
+**How to avoid:** Use `z-index: 10` (Tailwind `z-10`) for sticky cells. They only need to be above the regular table body cells (z-index: auto). The compare view has no interactive StatusBadge dropdowns (read-only in resolved mode; in active mode the compare view is navigational, not mutation-focused).
+**Warning signs:** Sticky column clips or obscures slide-out panels.
+
+### Pitfall 6: Pros/Cons Rendered as Raw String
+**What goes wrong:** A candidate's pros appear as a single run-on text block with no formatting.
+**Why it happens:** `CandidateForm` stores pros/cons as newline-separated plain text. Plain JSX `{candidate.pros}` ignores newlines in HTML.
+**How to avoid:** Split on `"\n"`, filter empty strings, render as `<ul>/<li>`. Confirmed from `CandidateForm.tsx` textarea with "One pro per line..." placeholder.
+**Warning signs:** All pro/con items concatenated without separation.
+
+---
+
+## Code Examples
+
+Verified patterns from project source:
+
+### Extending uiStore candidateViewMode
+```typescript
+// src/client/stores/uiStore.ts — lines 53-54 today read:
+//   candidateViewMode: "list" | "grid";
+//   setCandidateViewMode: (mode: "list" | "grid") => void;
+
+// After change (only these two lines change in the interface):
+candidateViewMode: "list" | "grid" | "compare";
+setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
+
+// Implementation at lines 112-113 — no change needed:
+candidateViewMode: "list",
+setCandidateViewMode: (mode) => set({ candidateViewMode: mode }),
+```
+
+### threadId.tsx integration point (current line 192)
+```tsx
+// Current conditional rendering at line 192:
+// ) : candidateViewMode === "list" ? (
+//   <Reorder.Group ... />  or  <div ... />
+// ) : (
+//   <div className="grid ..."> (grid view)
+// )
+
+// After change — add compare branch before list check:
+} : candidateViewMode === "compare" ? (
+  <ComparisonTable
+    candidates={displayItems}
+    resolvedCandidateId={thread.resolvedCandidateId}
+  />
+) : candidateViewMode === "list" ? (
+  // list rendering (unchanged)
+) : (
+  // grid rendering (unchanged)
+)
+```
+
+### Minimum viable ComparisonTable props interface
+```typescript
+// Reuse the CandidateWithCategory type from hooks/useThreads.ts
+interface ComparisonTableProps {
+  candidates: CandidateWithCategory[];   // already typed in useThreads.ts
+  resolvedCandidateId: number | null;    // for winner column highlight
+}
+```
+
+### Full delta computation with useMemo (null-safe)
+```typescript
+const { priceDeltas, bestPriceId } = useMemo(() => {
+  const withPrice = candidates.filter((c) => c.priceCents != null);
+  if (withPrice.length === 0) {
+    return { priceDeltas: new Map<number, string | null>(), bestPriceId: null };
+  }
+  const minCents = Math.min(...withPrice.map((c) => c.priceCents as number));
+  const bestPriceId = withPrice.find((c) => c.priceCents === minCents)!.id;
+  const priceDeltas = new Map(
+    candidates.map((c) => {
+      if (c.priceCents == null) return [c.id, null];          // missing data
+      const delta = c.priceCents - minCents;
+      return [c.id, delta === 0 ? null : `+${formatPrice(delta, currency)}`];
+    })
+  );
+  return { priceDeltas, bestPriceId };
+}, [candidates, currency]);
+```
+
+### Best-cell highlight pattern (weight example)
+```tsx
+// Weight cell — bg-blue-50 for "lightest" (matches existing blue weight pills in CandidateListItem)
+function WeightCell({ candidate, delta, isBest, unit }: WeightCellProps) {
+  return (
+    <td className={`px-4 py-3 text-sm ${isBest ? "bg-blue-50" : ""}`}>
+      {candidate.weightGrams != null ? (
+        <>
+          <span className="font-medium text-gray-900">
+            {formatWeight(candidate.weightGrams, unit)}
+          </span>
+          {delta && (
+            <span className="block text-xs text-gray-400 mt-0.5">{delta}</span>
+          )}
+        </>
+      ) : (
+        <span className="text-gray-300">—</span>
+      )}
+    </td>
+  );
+}
+```
+
+Note: CONTEXT.md uses "bg-green-50" as the example for lightest weight. Recommend aligning with existing project badge colors: lightest weight → `bg-blue-50` (consistent with blue weight pills), cheapest price → `bg-green-50` (consistent with green price pills). This is within Claude's discretion.
+
+### Winner column pattern (resolved threads)
+```tsx
+// Column header for the winning candidate gets amber tint (matches resolution banner)
+<th
+  key={c.id}
+  className={`px-4 py-3 text-left text-xs font-medium min-w-[160px] ${
+    c.id === resolvedCandidateId
+      ? "bg-amber-50 text-amber-800"
+      : "text-gray-700"
+  }`}
+>
+  <div className="flex items-center gap-1.5">
+    {c.id === resolvedCandidateId && (
+      <LucideIcon name="trophy" size={12} className="text-amber-600" />
+    )}
+    {c.name}
+  </div>
+</th>
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | Notes |
+|--------------|------------------|-------|
+| Hand-rolled format functions | Reuse `formatWeight` / `formatPrice` with delta arithmetic | Project formatters already handle all units, currencies, and null |
+| `overflow-x: auto` on `<table>` | `overflow-x-auto` on wrapper `<div>` | CSS spec: overflow only applies to block containers |
+| JS-based sticky columns | CSS `position: sticky` with `left: 0` | 92%+ browser support, zero JS overhead |
+| Inline column rendering | Declarative row-definition array | Matches the locked attribute order, easy to maintain |
+
+**Deprecated/outdated:**
+- Direct lucide icon component imports (e.g., `import { LayoutList } from "lucide-react"`): project uses `LucideIcon` helper uniformly — follow the same pattern.
+
+---
+
+## Open Questions
+
+All questions resolved during research:
+
+1. **Pros/cons storage format — RESOLVED**
+   - `CandidateForm.tsx` uses a `<textarea>` with "One pro per line..." placeholder
+   - Submit handler: `pros: form.pros.trim() || undefined` — empty string → not sent → stored as `null`
+   - Non-empty content: raw multiline text stored as-is, newline-separated
+   - **Action for planner:** Use `BulletCell` pattern (split on `\n`, render `<ul>/<li>`)
+
+2. **`columns-3` icon availability — RESOLVED**
+   - Verified: `Columns3` is present in lucide-react ^0.577.0 installed package
+   - Use `<LucideIcon name="columns-3" size={16} />` — the LucideIcon helper converts to PascalCase
+   - `table-2` is also present as a backup if needed
+
+3. **"Add Candidate" button in compare mode — RECOMMENDATION**
+   - Currently guarded by `{isActive && ...}` in `$threadId.tsx`
+   - Recommendation: hide "Add Candidate" when `candidateViewMode === "compare"` (keep toolbar uncluttered; users switch to list/grid to add)
+   - Implementation: add `&& candidateViewMode !== "compare"` to the existing `isActive` guard
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test (built-in) |
+| Config file | None — uses `bun test` directly |
+| Quick run command | `bun test tests/lib/` |
+| Full suite command | `bun test` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| COMP-01 | Candidates display all required fields in table | manual-only (UI/browser) | — | N/A |
+| COMP-02 | Delta computation: null-safe, best candidate identified, zero-delta suppressed | unit (if extracted to util) | `bun test tests/lib/comparison-deltas.test.ts` | ❌ Wave 0 gap (optional) |
+| COMP-03 | Table scrolls horizontally / sticky label column stays fixed | manual-only (CSS/browser) | — | N/A |
+| COMP-04 | Resolved thread shows read-only view with winner marked; no zero for missing data | manual-only (UI state) | — | N/A |
+
+**Note on testing scope:** COMP-01, COMP-03, COMP-04 are UI/browser behaviors. COMP-02 delta logic is pure arithmetic — testable if extracted to a standalone utility function. This is a pure frontend phase; the existing `bun test` suite covers backend services only and will not be broken by this phase.
+
+### Sampling Rate
+- **Per task commit:** `bun test` (full suite, fast — no UI tests in suite)
+- **Per wave merge:** `bun test`
+- **Phase gate:** Full suite green + manual browser verification of scroll/sticky behavior on a narrow viewport
+
+### Wave 0 Gaps
+- [ ] `tests/lib/comparison-deltas.test.ts` — covers COMP-02 delta logic if extracted to a pure utility (optional; skip if deltas stay inlined in the React component)
+
+*(If delta computation stays in the React component via `useMemo`, no new test files are needed — COMP-02 is verified manually in the browser.)*
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- Project codebase direct inspection:
+  - `src/client/stores/uiStore.ts` — confirmed `candidateViewMode` type and setter
+  - `src/client/routes/threads/$threadId.tsx` — confirmed integration points, toggle bar pattern, lines to modify
+  - `src/client/components/CandidateListItem.tsx` — confirmed `RankBadge` export, `CandidateWithCategory` interface
+  - `src/client/components/CandidateCard.tsx` — confirmed field usage patterns
+  - `src/client/components/CandidateForm.tsx` — confirmed pros/cons are newline-separated textarea input; empty = null
+  - `src/client/lib/formatters.ts` — confirmed null handling, `"--"` return for null
+  - `src/client/hooks/useThreads.ts` — confirmed `CandidateWithCategory` shape with all fields needed
+  - `package.json` — confirmed no new dependencies needed
+- Runtime verification: `Columns3` in lucide-react ^0.577.0 confirmed present via node script
+
+### Secondary (MEDIUM confidence)
+- [Tailwind CSS overflow docs](https://tailwindcss.com/docs/overflow) — `overflow-x-auto` on wrapper div pattern
+- [Tailwind CSS position docs](https://tailwindcss.com/docs/position) — sticky utility, z-index behavior
+- [Lexington Themes — scrollable sticky header table](https://lexingtonthemes.com/blog/how-to-build-a-scrollable-table-with-sticky-header-using-tailwind-css) — confirmed sticky thead pattern with Tailwind
+
+### Tertiary (LOW confidence — WebSearch, not verified against official spec)
+- [Multi-Directional Sticky CSS (Medium, Jan 2026)](https://medium.com/@ashutoshgautam10b11/multi-directional-sticky-css-and-horizontal-scroll-in-tables-41fc25c3ce8b) — z-index layering reference; this phase only needs one sticky axis (left column, z-10 suffices)
+- [DEV Community — sticky frozen column](https://dev.to/nicolaserny/table-with-a-fixed-first-column-2c5b) — background color requirement for sticky cells confirmed
+- [freeCodeCamp Forum — overflow + sticky](https://forum.freecodecamp.org/t/fixing-sticky-table-header-with-horizontal-scroll-in-a-scrollable-container/735559) — overflow-x-auto must be on wrapper div, not table element
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — all dependencies confirmed present in package.json; no new packages
+- Architecture: HIGH — directly derived from reading all relevant project source files
+- Pitfalls: HIGH — sticky bg issue confirmed by multiple sources; overflow-on-table confirmed by CSS spec; pros/cons newline format confirmed from CandidateForm source
+- Delta computation: HIGH — pure arithmetic, formatters already handle null, confirmed return values
+
+**Research date:** 2026-03-17
+**Valid until:** 2026-04-17 (stable CSS, stable React, stable project codebase)

.planning/phases/12-comparison-view/12-VALIDATION.md

@@ -0,0 +1,78 @@
+---
+phase: 12
+slug: comparison-view
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-17
+---
+
+# Phase 12 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bun test (built-in) |
+| **Config file** | None — uses `bun test` directly |
+| **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 |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 12-01-01 | 01 | 1 | COMP-01 | manual-only (UI/browser) | — | N/A | ⬜ pending |
+| 12-01-02 | 01 | 1 | COMP-02 | unit (if delta util extracted) | `bun test tests/lib/comparison-deltas.test.ts` | ❌ W0 | ⬜ pending |
+| 12-01-03 | 01 | 1 | COMP-03 | manual-only (CSS/browser) | — | N/A | ⬜ pending |
+| 12-01-04 | 01 | 1 | COMP-04 | manual-only (UI state) | — | N/A | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `tests/lib/comparison-deltas.test.ts` — stubs for COMP-02 delta computation (optional; skip if deltas stay inlined in React component via useMemo)
+
+*Existing `bun test` infrastructure covers all backend services. This phase is pure frontend — no backend tests are broken.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Candidates display all fields in tabular columns | COMP-01 | UI rendering — no backend logic | Open thread with 2+ candidates, toggle compare view, verify all fields visible |
+| Table scrolls horizontally with sticky label column | COMP-03 | CSS behavior — requires browser | Narrow viewport to <768px, verify horizontal scroll, verify label column stays fixed |
+| Resolved thread shows read-only view with winner marked | COMP-04 | UI state — requires resolved thread | Open resolved thread, toggle compare view, verify winner column highlighted, no interactive elements |
+| Missing weight/price shows dash, not zero | COMP-04 | UI rendering for null data | Add candidate with no weight, toggle compare, verify "—" not "0g" |
+
+---
+
+## 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/12-comparison-view/12-VERIFICATION.md

@@ -0,0 +1,95 @@
+---
+phase: 12-comparison-view
+verified: 2026-03-17T00:00:00Z
+status: passed
+score: 7/7 must-haves verified
+re_verification: false
+---
+
+# Phase 12: Comparison View Verification Report
+
+**Phase Goal:** Users can view all candidates for a thread side-by-side in a table with relative weight and price deltas
+**Verified:** 2026-03-17
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can toggle to a Compare view when a thread has 2+ candidates | VERIFIED | `$threadId.tsx:172` — compare button wrapped in `{thread.candidates.length >= 2 && (...)}`; clicking calls `setCandidateViewMode("compare")` |
+| 2 | Comparison table shows all candidates side-by-side with weight, price, images, notes, links, status, pros, and cons | VERIFIED | `ComparisonTable.tsx:104-269` — ATTRIBUTE_ROWS array defines all 10 rows: Image, Name, Rank, Weight, Price, Status, Link, Notes, Pros, Cons |
+| 3 | The lightest candidate weight cell has a blue highlight; the cheapest candidate price cell has a green highlight | VERIFIED | `ComparisonTable.tsx:167` — `cellClass` returns `"bg-blue-50"` when `c.id === bestWeightId`; `ComparisonTable.tsx:193` — `"bg-green-50"` when `c.id === bestPriceId` |
+| 4 | Non-best cells show a gray +delta string; best cells show no delta | VERIFIED | `ComparisonTable.tsx:64-66` — delta stored as `null` when `delta === 0` (best), else `+${formatWeight(delta, unit)}`; `ComparisonTable.tsx:160-162` — delta div only rendered when `!isBest && delta` |
+| 5 | The table scrolls horizontally on narrow viewports while the attribute label column stays fixed on the left | VERIFIED | `ComparisonTable.tsx:274` — outer `<div className="overflow-x-auto ...">` for scroll; `ComparisonTable.tsx:282,311` — every label cell has `sticky left-0 z-10 bg-white` |
+| 6 | Missing weight or price data displays a dash, never a misleading zero | VERIFIED | `ComparisonTable.tsx:152-153` — `if (c.weightGrams == null) return <span className="text-gray-300">—</span>`; `ComparisonTable.tsx:178-179` — same pattern for price |
+| 7 | A resolved thread shows the comparison read-only with the winner column visually marked (amber tint + trophy) | VERIFIED | `ComparisonTable.tsx:284-301` — winner `<th>` gets `bg-amber-50 text-amber-800` + trophy icon; body cells get `bg-amber-50/50` tint via default `extraClass` branch at line 318-320; no mutation controls exist inside ComparisonTable |
+
+**Score:** 7/7 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/client/components/ComparisonTable.tsx` | Tabular side-by-side comparison component; min 120 lines | VERIFIED | 336 lines; full ATTRIBUTE_ROWS declarative pattern, useMemo deltas, sticky column, winner highlighting |
+| `src/client/stores/uiStore.ts` | Extended candidateViewMode union including "compare" | VERIFIED | Line 53: `candidateViewMode: "list" \| "grid" \| "compare"` and line 54: `setCandidateViewMode: (mode: "list" \| "grid" \| "compare") => void` |
+| `src/client/routes/threads/$threadId.tsx` | Compare toggle button and ComparisonTable rendering branch | VERIFIED | Line 6 imports ComparisonTable; line 172-185 conditionally renders compare button; line 207-211 renders `<ComparisonTable>` when `candidateViewMode === "compare"` |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `$threadId.tsx` | `ComparisonTable.tsx` | import + conditional render when `candidateViewMode === "compare"` | WIRED | Line 6 imports; line 207 `candidateViewMode === "compare"` branch renders `<ComparisonTable candidates={displayItems} resolvedCandidateId={thread.resolvedCandidateId} />` |
+| `ComparisonTable.tsx` | `lib/formatters.ts` | `formatWeight` and `formatPrice` for cell values and delta strings | WIRED | Line 4 imports both; used at lines 66, 92, 158, 184 for both display values and delta string construction |
+| `ComparisonTable.tsx` | `CandidateListItem.tsx` | `RankBadge` import for rank row | WIRED | Line 7 imports `RankBadge`; used at line 144 in the rank ATTRIBUTE_ROW render function |
+| `$threadId.tsx` | `uiStore.ts` | `candidateViewMode` state read and `setCandidateViewMode` action | WIRED | Lines 24-25 read both from `useUIStore`; `candidateViewMode` read at lines 124, 152, 164, 177, 207, 212; `setCandidateViewMode` called at lines 150, 163, 175 |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-------------|-------------|--------|----------|
+| COMP-01 | 12-01-PLAN.md | User can view candidates side-by-side in a tabular comparison layout (weight, price, images, notes, links, status) | SATISFIED | ComparisonTable renders all fields as columns; toggle wired in $threadId.tsx |
+| COMP-02 | 12-01-PLAN.md | User can see relative deltas highlighting the lightest and cheapest candidate with +/- differences | SATISFIED | useMemo delta computation at lines 47-102; blue-50/green-50 highlights; gray delta text for non-best cells |
+| COMP-03 | 12-01-PLAN.md | Comparison table scrolls horizontally with a sticky label column on narrow viewports | SATISFIED | `overflow-x-auto` on wrapper; `sticky left-0 z-10 bg-white` on all label cells; `minWidth` computed from candidate count |
+| COMP-04 | 12-01-PLAN.md | Comparison view displays read-only summary for resolved threads | SATISFIED | No mutation actions in ComparisonTable; winner column amber-marked with trophy; `resolvedCandidateId` prop drives the read-only winner state |
+
+No orphaned requirements found. REQUIREMENTS.md maps COMP-01 through COMP-04 exclusively to Phase 12, all are accounted for by plan 12-01.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| — | — | None found | — | — |
+
+No TODO/FIXME/placeholder comments, empty implementations, or stub returns found in any of the three phase 12 files. Biome lint passes cleanly on all three files (only pre-existing unrelated issues in other src files; none in phase 12 files).
+
+### Human Verification Required
+
+#### 1. Horizontal scroll with sticky label column
+
+**Test:** Open a thread with 3+ candidates on a narrow viewport (< 600px). Scroll the table right.
+**Expected:** Candidate columns scroll off-screen left; the attribute label column (Image, Name, Rank, etc.) remains fixed at the left edge without content bleed-through.
+**Why human:** CSS `sticky` behavior with `overflow-x-auto` interactions cannot be asserted by grep; only visual browser confirmation validates the `bg-white` bleed-through prevention.
+
+#### 2. Winner column amber tint + trophy on resolved thread
+
+**Test:** Navigate to a thread that has been resolved. Switch to compare view.
+**Expected:** The winning candidate's column header shows a trophy icon and amber background; every row of that column has a subtle amber-50/50 tint. Weight/price highlight colors (blue/green) take priority over amber when the winner is also the lightest/cheapest.
+**Why human:** Color layering and opacity compositing require visual verification.
+
+#### 3. Delta display with mixed null/non-null data
+
+**Test:** Add two candidates to a thread where one has weight data and the other does not. Switch to compare view.
+**Expected:** The candidate with no weight shows an em dash in the weight row (not 0g). The one with weight shows its value with no delta label (it is trivially the best). No misleading zero appears.
+**Why human:** Edge-case rendering for the null path requires runtime React state to confirm the `formatWeight(null)` → `"--"` path is reached and displayed as `—` (em dash span), not the `"--"` string fallback from formatters.
+
+### Gaps Summary
+
+No gaps found. All seven observable truths are verified, all three artifacts exist and are substantive, all four key links are wired end-to-end, all four COMP requirements are satisfied by traceable code, lint passes on all phase files, and 135 tests pass with zero regressions.
+
+---
+
+_Verified: 2026-03-17_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/13-setup-impact-preview/13-01-PLAN.md

@@ -0,0 +1,253 @@
+---
+phase: 13-setup-impact-preview
+plan: 01
+type: tdd
+wave: 1
+depends_on: []
+files_modified:
+  - src/client/lib/impactDeltas.ts
+  - src/client/hooks/useImpactDeltas.ts
+  - src/client/hooks/useThreads.ts
+  - src/client/stores/uiStore.ts
+  - tests/lib/impactDeltas.test.ts
+autonomous: true
+requirements: [IMPC-01, IMPC-02, IMPC-03, IMPC-04]
+
+must_haves:
+  truths:
+    - "computeImpactDeltas returns replace-mode deltas when a setup item matches the thread category"
+    - "computeImpactDeltas returns add-mode deltas (candidate value only) when no category match exists"
+    - "computeImpactDeltas returns null weightDelta/priceDelta when candidate has null weight/price"
+    - "computeImpactDeltas returns mode 'none' with empty deltas when setupItems is undefined"
+    - "selectedSetupId state persists in uiStore and can be set/cleared"
+    - "ThreadWithCandidates interface includes categoryId field"
+  artifacts:
+    - path: "src/client/lib/impactDeltas.ts"
+      provides: "Pure computeImpactDeltas function with CandidateDelta, ImpactDeltas types"
+      exports: ["computeImpactDeltas", "CandidateInput", "CandidateDelta", "DeltaMode", "ImpactDeltas"]
+    - path: "src/client/hooks/useImpactDeltas.ts"
+      provides: "React hook wrapping computeImpactDeltas in useMemo"
+      exports: ["useImpactDeltas"]
+    - path: "tests/lib/impactDeltas.test.ts"
+      provides: "Unit tests for all four IMPC requirements"
+      contains: "computeImpactDeltas"
+  key_links:
+    - from: "src/client/hooks/useImpactDeltas.ts"
+      to: "src/client/lib/impactDeltas.ts"
+      via: "import computeImpactDeltas"
+      pattern: "import.*computeImpactDeltas.*from.*lib/impactDeltas"
+    - from: "src/client/hooks/useImpactDeltas.ts"
+      to: "src/client/hooks/useSetups.ts"
+      via: "SetupItemWithCategory type import"
+      pattern: "import.*SetupItemWithCategory.*from.*useSetups"
+---
+
+<objective>
+Create the pure impact delta computation logic with full TDD coverage, add selectedSetupId to uiStore, fix the ThreadWithCandidates type to include categoryId, and wrap it all in a useImpactDeltas hook.
+
+Purpose: Establish the data layer and contracts that Plan 02 will consume for rendering delta indicators. TDD ensures the replace/add mode logic and null-weight handling are correct before any UI work.
+Output: Tested pure function, React hook, updated types, uiStore state.
+</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/13-setup-impact-preview/13-RESEARCH.md
+
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+
+From src/client/hooks/useSetups.ts:
+```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;
+}
+
+export function useSetup(setupId: number | null) {
+  return useQuery({
+    queryKey: ["setups", setupId],
+    queryFn: () => apiGet<SetupWithItems>(`/api/setups/${setupId}`),
+    enabled: setupId != null,  // CRITICAL: prevents null fetch
+  });
+}
+```
+
+From src/client/hooks/useThreads.ts (BEFORE fix):
+```typescript
+interface ThreadWithCandidates {
+  id: number;
+  name: string;
+  status: "active" | "resolved";
+  resolvedCandidateId: number | null;
+  createdAt: string;
+  updatedAt: string;
+  candidates: CandidateWithCategory[];
+  // NOTE: categoryId is MISSING — server returns it but type omits it
+}
+```
+
+From src/client/stores/uiStore.ts (existing pattern):
+```typescript
+candidateViewMode: "list" | "grid" | "compare";
+setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
+// Add selectedSetupId + setter using same pattern
+```
+
+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;
+export type Currency = "USD" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD";
+export function formatPrice(cents: number | null | undefined, currency: Currency = "USD"): string;
+```
+</interfaces>
+</context>
+
+<feature>
+  <name>Impact Delta Computation</name>
+  <files>src/client/lib/impactDeltas.ts, tests/lib/impactDeltas.test.ts, src/client/hooks/useImpactDeltas.ts, src/client/hooks/useThreads.ts, src/client/stores/uiStore.ts</files>
+  <behavior>
+    IMPC-01 (setup selected, deltas computed):
+    - Given candidates with weight/price and a setup with items, returns per-candidate delta objects with weightDelta and priceDelta numbers
+    - Given no setup selected (setupItems = undefined), returns { mode: "none", deltas: {} }
+
+    IMPC-02 (replace mode auto-detection):
+    - Given setup items where one has categoryId === threadCategoryId, mode is "replace"
+    - In replace mode, weightDelta = candidate.weightGrams - replacedItem.weightGrams
+    - In replace mode, priceDelta = candidate.priceCents - replacedItem.priceCents
+    - replacedItemName is populated with the matched item's name
+
+    IMPC-03 (add mode):
+    - Given setup items where NONE have categoryId === threadCategoryId, mode is "add"
+    - In add mode, weightDelta = candidate.weightGrams (pure addition)
+    - In add mode, priceDelta = candidate.priceCents (pure addition)
+    - replacedItemName is null
+
+    IMPC-04 (null weight handling):
+    - Given candidate.weightGrams is null, weightDelta is null (not 0, not NaN)
+    - Given candidate.priceCents is null, priceDelta is null
+    - In replace mode with replacedItem.weightGrams null but candidate has weight, weightDelta = candidate.weightGrams (treat as add for that field)
+
+    Edge cases:
+    - Empty candidates array -> returns { mode based on setup, deltas: {} }
+    - Multiple setup items in same category as thread -> first match used for replacement
+  </behavior>
+  <implementation>
+    1. Create src/client/lib/impactDeltas.ts with:
+       - CandidateInput interface: { id: number; weightGrams: number | null; priceCents: number | null }
+       - DeltaMode type: "replace" | "add" | "none"
+       - CandidateDelta interface: { candidateId, mode, weightDelta, priceDelta, replacedItemName }
+       - ImpactDeltas interface: { mode: DeltaMode; deltas: Record<number, CandidateDelta> }
+       - SetupItemInput interface: { categoryId: number; weightGrams: number | null; priceCents: number | null; name: string } (minimal subset of SetupItemWithCategory)
+       - computeImpactDeltas(candidates, setupItems, threadCategoryId) pure function
+
+    2. Create src/client/hooks/useImpactDeltas.ts wrapping in useMemo
+
+    3. Add categoryId to ThreadWithCandidates in useThreads.ts
+
+    4. Add selectedSetupId + setSelectedSetupId to uiStore.ts
+  </implementation>
+</feature>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: TDD pure computeImpactDeltas function</name>
+  <files>src/client/lib/impactDeltas.ts, tests/lib/impactDeltas.test.ts</files>
+  <behavior>
+    - Test: no setup selected (undefined) returns mode "none", empty deltas
+    - Test: replace mode — setup item matches threadCategoryId, deltas are candidate minus replaced item
+    - Test: add mode — no setup item matches, deltas equal candidate values
+    - Test: null candidate weight returns null weightDelta, not zero
+    - Test: null candidate price returns null priceDelta
+    - Test: replace mode with null replacedItem weight but valid candidate weight returns candidate weight as delta (add-like for that field)
+    - Test: negative delta in replace mode (candidate lighter than replaced item)
+    - Test: zero delta in replace mode (identical weight)
+    - Test: replacedItemName populated in replace mode, null in add mode
+  </behavior>
+  <action>
+    RED: Create tests/lib/impactDeltas.test.ts importing computeImpactDeltas from @/client/lib/impactDeltas. Write all test cases above using Bun test (describe/test/expect). Run tests — they MUST fail (module not found).
+
+    GREEN: Create src/client/lib/impactDeltas.ts with:
+    - Export types: CandidateInput, SetupItemInput, DeltaMode, CandidateDelta, ImpactDeltas
+    - Export function computeImpactDeltas(candidates: CandidateInput[], setupItems: SetupItemInput[] | undefined, threadCategoryId: number): ImpactDeltas
+    - Logic: if !setupItems return { mode: "none", deltas: {} }
+    - Find replacedItem = setupItems.find(item => item.categoryId === threadCategoryId) ?? null
+    - mode = replacedItem ? "replace" : "add"
+    - For each candidate: null-guard weight/price BEFORE arithmetic. In replace mode with non-null replaced value, delta = candidate - replaced. In replace mode with null replaced value, delta = candidate value (like add). In add mode, delta = candidate value.
+    - Run tests — all MUST pass.
+
+    REFACTOR: None needed for pure function.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test tests/lib/impactDeltas.test.ts</automated>
+  </verify>
+  <done>All 9+ test cases pass. computeImpactDeltas correctly handles replace mode, add mode, null weights, null prices, and edge cases. Types are exported.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add uiStore state, fix ThreadWithCandidates type, create useImpactDeltas hook</name>
+  <files>src/client/stores/uiStore.ts, src/client/hooks/useThreads.ts, src/client/hooks/useImpactDeltas.ts</files>
+  <action>
+    1. In src/client/stores/uiStore.ts, add to UIState interface:
+       - selectedSetupId: number | null;
+       - setSelectedSetupId: (id: number | null) => void;
+       Add to create() initializer:
+       - selectedSetupId: null,
+       - setSelectedSetupId: (id) => set({ selectedSetupId: id }),
+       Place after the "Candidate view mode" section as "// Setup impact preview" section.
+
+    2. In src/client/hooks/useThreads.ts, add `categoryId: number;` to the ThreadWithCandidates interface, after the `resolvedCandidateId` field. The server already returns this field — the type was simply missing it.
+
+    3. Create src/client/hooks/useImpactDeltas.ts:
+       - Import useMemo from react
+       - Import computeImpactDeltas and types from "../lib/impactDeltas"
+       - Import type { SetupItemWithCategory } from "./useSetups"
+       - Export function useImpactDeltas(candidates: CandidateInput[], setupItems: SetupItemWithCategory[] | undefined, threadCategoryId: number): ImpactDeltas
+       - Body: return useMemo(() => computeImpactDeltas(candidates, setupItems, threadCategoryId), [candidates, setupItems, threadCategoryId])
+       - Re-export CandidateDelta, DeltaMode, ImpactDeltas types for convenience
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test tests/lib/impactDeltas.test.ts && bun test tests/lib/formatters.test.ts</automated>
+  </verify>
+  <done>uiStore has selectedSetupId + setter. ThreadWithCandidates includes categoryId. useImpactDeltas hook created and exports types. All existing tests still pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+- `bun test tests/lib/` passes all tests (impactDeltas + formatters)
+- `bun test` full suite passes (no regressions)
+- Types export correctly: CandidateInput, CandidateDelta, DeltaMode, ImpactDeltas, SetupItemInput from impactDeltas.ts
+- useImpactDeltas hook wraps pure function in useMemo
+- uiStore.selectedSetupId defaults to null
+- ThreadWithCandidates.categoryId is declared as number
+</verification>
+
+<success_criteria>
+- All IMPC requirement behaviors are tested and passing via pure function unit tests
+- Data layer contracts (types, hook, uiStore state) are ready for Plan 02 UI consumption
+- Zero regressions in existing test suite
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/13-setup-impact-preview/13-01-SUMMARY.md`
+</output>

.planning/phases/13-setup-impact-preview/13-02-PLAN.md

@@ -0,0 +1,330 @@
+---
+phase: 13-setup-impact-preview
+plan: 02
+type: execute
+wave: 2
+depends_on: ["13-01"]
+files_modified:
+  - src/client/components/SetupImpactSelector.tsx
+  - src/client/components/ImpactDeltaBadge.tsx
+  - src/client/routes/threads/$threadId.tsx
+  - src/client/components/CandidateListItem.tsx
+  - src/client/components/CandidateCard.tsx
+  - src/client/components/ComparisonTable.tsx
+autonomous: true
+requirements: [IMPC-01, IMPC-02, IMPC-03, IMPC-04]
+
+must_haves:
+  truths:
+    - "User can select a setup from a dropdown in the thread header"
+    - "Each candidate displays weight and cost delta badges when a setup is selected"
+    - "Replace mode shows signed delta with replaced item name context"
+    - "Add mode shows positive delta labeled as '(add)'"
+    - "Candidate with no weight shows '-- (no weight data)' instead of a zero"
+    - "Candidate with no price shows '-- (no price data)' instead of a zero"
+    - "Deselecting setup ('None') clears all delta indicators"
+    - "Deltas appear in list view, grid view, and comparison table"
+  artifacts:
+    - path: "src/client/components/SetupImpactSelector.tsx"
+      provides: "Setup dropdown for thread header"
+      exports: ["SetupImpactSelector"]
+    - path: "src/client/components/ImpactDeltaBadge.tsx"
+      provides: "Inline delta indicator component"
+      exports: ["ImpactDeltaBadge"]
+    - path: "src/client/routes/threads/$threadId.tsx"
+      provides: "Thread detail page wired with impact preview"
+    - path: "src/client/components/CandidateListItem.tsx"
+      provides: "List item with delta badges"
+    - path: "src/client/components/CandidateCard.tsx"
+      provides: "Card with delta badges"
+    - path: "src/client/components/ComparisonTable.tsx"
+      provides: "Comparison table with impact delta rows"
+  key_links:
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/hooks/useImpactDeltas.ts"
+      via: "useImpactDeltas hook call at page level"
+      pattern: "useImpactDeltas"
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/hooks/useSetups.ts"
+      via: "useSetup(selectedSetupId) for setup item data"
+      pattern: "useSetup\\(selectedSetupId"
+    - from: "src/client/routes/threads/$threadId.tsx"
+      to: "src/client/stores/uiStore.ts"
+      via: "selectedSetupId state read"
+      pattern: "useUIStore.*selectedSetupId"
+    - from: "src/client/components/SetupImpactSelector.tsx"
+      to: "src/client/stores/uiStore.ts"
+      via: "setSelectedSetupId state write"
+      pattern: "setSelectedSetupId"
+    - from: "src/client/components/ImpactDeltaBadge.tsx"
+      to: "src/client/lib/impactDeltas.ts"
+      via: "CandidateDelta type import"
+      pattern: "import.*CandidateDelta"
+    - from: "src/client/components/ComparisonTable.tsx"
+      to: "src/client/lib/impactDeltas.ts"
+      via: "ImpactDeltas type for deltas prop"
+      pattern: "import.*ImpactDeltas"
+---
+
+<objective>
+Build the UI components (setup dropdown + delta badges) and wire them into the thread detail page across all three view modes (list, grid, compare).
+
+Purpose: This is the user-facing delivery of the impact preview feature. Plan 01 built the logic; this plan renders it.
+Output: SetupImpactSelector component, ImpactDeltaBadge component, updated CandidateListItem/CandidateCard/ComparisonTable with delta rendering, wired thread detail page.
+</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/13-setup-impact-preview/13-RESEARCH.md
+@.planning/phases/13-setup-impact-preview/13-01-SUMMARY.md
+
+<interfaces>
+<!-- Types created by Plan 01 that this plan consumes -->
+
+From src/client/lib/impactDeltas.ts (created in Plan 01):
+```typescript
+export interface CandidateInput {
+  id: number;
+  weightGrams: number | null;
+  priceCents: number | null;
+}
+
+export type DeltaMode = "replace" | "add" | "none";
+
+export interface CandidateDelta {
+  candidateId: number;
+  mode: DeltaMode;
+  weightDelta: number | null;
+  priceDelta: number | null;
+  replacedItemName: string | null;
+}
+
+export interface ImpactDeltas {
+  mode: DeltaMode;
+  deltas: Record<number, CandidateDelta>;
+}
+```
+
+From src/client/hooks/useImpactDeltas.ts (created in Plan 01):
+```typescript
+export function useImpactDeltas(
+  candidates: CandidateInput[],
+  setupItems: SetupItemWithCategory[] | undefined,
+  threadCategoryId: number,
+): ImpactDeltas;
+```
+
+From src/client/hooks/useSetups.ts:
+```typescript
+export function useSetups(): UseQueryResult<SetupListItem[]>;
+export function useSetup(setupId: number | null): UseQueryResult<SetupWithItems>;
+```
+
+From src/client/stores/uiStore.ts (updated in Plan 01):
+```typescript
+selectedSetupId: number | null;
+setSelectedSetupId: (id: number | null) => void;
+```
+
+From src/client/hooks/useThreads.ts (updated in Plan 01):
+```typescript
+interface ThreadWithCandidates {
+  id: number;
+  name: string;
+  status: "active" | "resolved";
+  resolvedCandidateId: number | null;
+  categoryId: number;  // <-- Added in Plan 01
+  createdAt: string;
+  updatedAt: string;
+  candidates: CandidateWithCategory[];
+}
+```
+
+From src/client/lib/formatters.ts:
+```typescript
+export function formatWeight(grams: number | null | undefined, unit: WeightUnit = "g"): string;
+export function formatPrice(cents: number | null | undefined, currency: Currency = "USD"): string;
+```
+
+Existing component props that need delta additions:
+
+CandidateListItem props:
+```typescript
+interface CandidateListItemProps {
+  candidate: CandidateWithCategory;
+  rank: number;
+  isActive: boolean;
+  onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
+  // Will add: delta?: CandidateDelta;
+}
+```
+
+CandidateCard props:
+```typescript
+interface CandidateCardProps {
+  id: number;
+  name: string;
+  weightGrams: number | null;
+  priceCents: number | null;
+  // ... other props
+  // Will add: delta?: CandidateDelta;
+}
+```
+
+ComparisonTable props:
+```typescript
+interface ComparisonTableProps {
+  candidates: CandidateWithCategory[];
+  resolvedCandidateId: number | null;
+  // Will add: deltas?: Record<number, CandidateDelta>;
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create SetupImpactSelector and ImpactDeltaBadge components</name>
+  <files>src/client/components/SetupImpactSelector.tsx, src/client/components/ImpactDeltaBadge.tsx</files>
+  <action>
+    1. Create src/client/components/SetupImpactSelector.tsx:
+       - Import useSetups from hooks/useSetups
+       - Import useUIStore from stores/uiStore
+       - Export function SetupImpactSelector()
+       - Read selectedSetupId and setSelectedSetupId from uiStore
+       - Fetch setups via useSetups()
+       - If no setups or loading, return null
+       - Render: a flex row with label "Impact on setup:" (text-xs text-gray-500) and a native `<select>` element
+       - Select value = selectedSetupId ?? "", onChange parses to number or null
+       - Options: "None" (value="") + each setup by name
+       - Styling: text-sm border border-gray-200 rounded-lg px-2 py-1 text-gray-700 bg-white focus:outline-none focus:ring-1 focus:ring-gray-300
+
+    2. Create src/client/components/ImpactDeltaBadge.tsx:
+       - Import type CandidateDelta from lib/impactDeltas
+       - Import formatWeight, formatPrice, WeightUnit, Currency from lib/formatters
+       - Import useWeightUnit from hooks/useWeightUnit
+       - Import useCurrency from hooks/useCurrency
+       - Export function ImpactDeltaBadge({ delta, type }: { delta: CandidateDelta | undefined; type: "weight" | "price" })
+       - If !delta or delta.mode === "none", return null
+       - Pick value: type === "weight" ? delta.weightDelta : delta.priceDelta
+       - If value === null (no data): render `<span className="text-xs text-gray-300">` with "-- (no weight data)" or "-- (no price data)" depending on type
+       - If value is a number:
+         - formatted = type === "weight" ? formatWeight(Math.abs(value), unit) : formatPrice(Math.abs(value), currency)
+         - sign: value > 0 -> "+" , value < 0 -> "-" (use minus sign), value === 0 -> +/-
+         - colorClass: value < 0 -> "text-green-600" (lighter/cheaper is good), value > 0 -> "text-red-500", value === 0 -> "text-gray-400"
+         - modeLabel: delta.mode === "add" ? " (add)" : ""
+         - vsLabel: delta.mode === "replace" && delta.replacedItemName ? ` vs ${delta.replacedItemName}` : "" (only show this as a title attribute on the span, not inline text -- too long)
+         - Render: `<span className="text-xs font-medium {colorClass}" title={vsLabel || undefined}>{sign}{formatted}{modeLabel}</span>`
+       - The component reads unit/currency internally via hooks so callers don't need to pass them.
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -20</automated>
+  </verify>
+  <done>SetupImpactSelector renders a setup dropdown reading from uiStore. ImpactDeltaBadge renders signed, colored delta indicators with null-data handling. Both components lint-clean.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Wire impact preview into thread detail page and all candidate views</name>
+  <files>src/client/routes/threads/$threadId.tsx, src/client/components/CandidateListItem.tsx, src/client/components/CandidateCard.tsx, src/client/components/ComparisonTable.tsx</files>
+  <action>
+    1. In src/client/routes/threads/$threadId.tsx:
+       - Add imports: useSetup from hooks/useSetups, useImpactDeltas from hooks/useImpactDeltas, SetupImpactSelector from components/SetupImpactSelector, type CandidateDelta from lib/impactDeltas
+       - Read selectedSetupId from useUIStore: `const selectedSetupId = useUIStore((s) => s.selectedSetupId);`
+       - Fetch setup data: `const { data: setupData } = useSetup(selectedSetupId ?? null);`
+       - Compute deltas: `const impactDeltas = useImpactDeltas(thread.candidates, setupData?.items, thread.categoryId);` (place after thread is loaded, inside the render body after the isLoading/isError guards)
+       - Place `<SetupImpactSelector />` in the header section, after the thread name/status row and before the toolbar. Wrap it in a div for spacing if needed.
+       - Pass delta to CandidateListItem: add prop `delta={impactDeltas.deltas[candidate.id]}` to each CandidateListItem (both Reorder.Group and static div renderings)
+       - Pass delta to CandidateCard: add prop `delta={impactDeltas.deltas[candidate.id]}` (the CandidateCard receives individual props, so pass it as `delta={impactDeltas.deltas[candidate.id]}`)
+       - Pass deltas to ComparisonTable: add prop `deltas={impactDeltas.deltas}` alongside existing candidates and resolvedCandidateId
+
+    2. In src/client/components/CandidateListItem.tsx:
+       - Import type CandidateDelta from lib/impactDeltas
+       - Import ImpactDeltaBadge from ./ImpactDeltaBadge
+       - Add `delta?: CandidateDelta;` to CandidateListItemProps
+       - Add `delta` to destructured props
+       - Render two ImpactDeltaBadge components inside the badges flex-wrap div (after the existing weight and price badges):
+         - `{delta && <ImpactDeltaBadge delta={delta} type="weight" />}`
+         - `{delta && <ImpactDeltaBadge delta={delta} type="price" />}`
+       - Place these AFTER the existing weight/price badges so they appear as secondary indicators
+
+    3. In src/client/components/CandidateCard.tsx:
+       - Import type CandidateDelta from lib/impactDeltas
+       - Import ImpactDeltaBadge from ./ImpactDeltaBadge
+       - Add `delta?: CandidateDelta;` to CandidateCardProps
+       - Add `delta` to destructured props
+       - Render two ImpactDeltaBadge components inside the badges flex-wrap div (after weight/price badges):
+         - `{delta && <ImpactDeltaBadge delta={delta} type="weight" />}`
+         - `{delta && <ImpactDeltaBadge delta={delta} type="price" />}`
+
+    4. In src/client/components/ComparisonTable.tsx:
+       - Import type CandidateDelta from lib/impactDeltas
+       - Import ImpactDeltaBadge from ./ImpactDeltaBadge
+       - Add `deltas?: Record<number, CandidateDelta>;` to ComparisonTableProps
+       - Add `deltas` to destructured props
+       - Add two new rows to ATTRIBUTE_ROWS array, placed right after the "weight" row and "price" row respectively:
+         a. After "weight" row, add:
+            ```
+            {
+              key: "impact-weight",
+              label: "Impact (wt)",
+              render: (c) => deltas?.[c.id] ? <ImpactDeltaBadge delta={deltas[c.id]} type="weight" /> : <span className="text-gray-300">--</span>,
+            }
+            ```
+         b. After "price" row, add:
+            ```
+            {
+              key: "impact-price",
+              label: "Impact ($)",
+              render: (c) => deltas?.[c.id] ? <ImpactDeltaBadge delta={deltas[c.id]} type="price" /> : <span className="text-gray-300">--</span>,
+            }
+            ```
+       - These are separate rows (per research recommendation) to avoid conflating candidate-relative deltas with setup impact deltas.
+       - The impact rows show "--" when no setup is selected (deltas undefined or no entry for candidate).
+  </action>
+  <verify>
+    <automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test && bun run lint 2>&1 | head -20</automated>
+  </verify>
+  <done>
+    - SetupImpactSelector dropdown visible in thread header
+    - Selecting a setup shows weight/cost delta badges on each candidate in list, grid, and compare views
+    - Replace mode: signed delta with green (lighter/cheaper) or red (heavier/pricier) coloring
+    - Add mode: positive delta with "(add)" label
+    - Null weight/price: shows "-- (no weight data)" / "-- (no price data)" indicator
+    - Deselecting setup clears all delta indicators
+    - ComparisonTable has dedicated "Impact (wt)" and "Impact ($)" rows
+    - All tests pass, lint clean
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- `bun test` full suite passes
+- `bun run lint` clean
+- SetupImpactSelector renders in thread header with all setups as options
+- Selecting a setup triggers useSetup fetch and delta computation
+- CandidateListItem, CandidateCard, ComparisonTable all render delta badges
+- Replace mode detected when setup has item in same category as thread
+- Add mode used otherwise
+- Null weight/price shows clear indicator
+- Deselecting shows no deltas (clean state)
+</verification>
+
+<success_criteria>
+- All four IMPC requirements visible in the UI
+- Delta rendering works across list, grid, and compare views
+- No regressions in existing functionality
+- Clean lint output
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/13-setup-impact-preview/13-02-SUMMARY.md`
+</output>

.planning/phases/13-setup-impact-preview/13-RESEARCH.md

@@ -0,0 +1,518 @@
+# Phase 13: Setup Impact Preview - Research
+
+**Researched:** 2026-03-17
+**Domain:** Pure frontend — delta computation + UI (React, Zustand, React Query)
+**Confidence:** HIGH
+
+---
+
+## Summary
+
+Phase 13 adds a setup-selector dropdown to the thread detail header. When a user picks a setup, every candidate card and list row gains two delta indicators: weight delta and cost delta. The computation has two modes determined at render time — replace mode (a setup item exists in the same category as the thread) and add mode (no category match). The entire feature is a pure frontend addition: all required data is already available through existing hooks with zero backend or schema changes needed.
+
+The delta logic is straightforward arithmetic over nullable numbers: `candidate.weightGrams - replacedItem.weightGrams` in replace mode, or `candidate.weightGrams` in add mode. The only real complexity is the null-weight indicator (IMPC-04) and driving the selected setup ID through Zustand state so it persists across view-mode switches within the same thread session.
+
+**Primary recommendation:** Add `selectedSetupId: number | null` to uiStore, render a setup dropdown in the thread header, compute deltas in a `useMemo` inside a new `useImpactDeltas` hook, and render inline delta indicators below the candidate weight/price badges in both list and grid views.
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| IMPC-01 | User can select a setup and see weight and cost delta for each candidate | `useSetups()` returns all setups for dropdown; `useSetup(id)` returns items with categoryId for matching; delta computed in useMemo |
+| IMPC-02 | Impact preview auto-detects replace mode when a setup item exists in the same category as the thread | Thread has `categoryId` (from `threads.categoryId`); setup items have `categoryId` via join; match on `categoryId` equality |
+| IMPC-03 | Impact preview shows add mode (pure addition) when no category match exists in the selected setup | Default when no setup item matches `thread.categoryId`; label clearly as "+add" |
+| IMPC-04 | Candidates with missing weight data show a clear indicator instead of misleading zero deltas | `candidate.weightGrams == null` → render `"-- (no weight data)"` instead of computing |
+</phase_requirements>
+
+---
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| React 19 | ^19.2.4 | UI rendering | Project foundation |
+| Zustand | ^5.0.11 | `selectedSetupId` UI state | Established pattern for all UI-only state (panel open/close, view mode) |
+| TanStack React Query | ^5.90.21 | `useSetup(id)` for setup items | Established data fetching pattern |
+| Tailwind CSS v4 | ^4.2.1 | Delta badge styling | Project styling system |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| framer-motion | ^12.37.0 | Optional entrance animation for delta indicators | Already installed; use AnimatePresence if subtle fade needed |
+| lucide-react | ^0.577.0 | Dropdown chevron icon, delta arrow icons | Project icon system |
+
+### No New Dependencies
+This phase requires zero new npm dependencies. All needed libraries are installed.
+
+**Installation:**
+```bash
+# No new packages needed
+```
+
+---
+
+## Architecture Patterns
+
+### Recommended Project Structure
+```
+src/client/
+├── stores/uiStore.ts           # Add selectedSetupId: number | null + setter
+├── hooks/
+│   └── useImpactDeltas.ts      # New: compute add/replace deltas per candidate
+├── components/
+│   ├── SetupImpactSelector.tsx # New: setup dropdown rendered in thread header
+│   └── ImpactDeltaBadge.tsx    # New (or inline): weight/cost delta pill
+└── routes/threads/$threadId.tsx # Add selector to header, pass deltas down
+```
+
+### Pattern 1: selectedSetupId in Zustand
+
+**What:** Store selected setup ID as UI state in `uiStore.ts`, not as URL state or server state.
+
+**When to use:** The selection is ephemeral per session (no permalink needed), needs to survive view-mode switches (list/grid/compare), and must be accessible from any component in the thread page without prop drilling.
+
+**Example:**
+```typescript
+// In uiStore.ts — add to UIState interface
+selectedSetupId: number | null;
+setSelectedSetupId: (id: number | null) => void;
+
+// In create() initializer
+selectedSetupId: null,
+setSelectedSetupId: (id) => set({ selectedSetupId: id }),
+```
+
+### Pattern 2: useImpactDeltas Hook
+
+**What:** A pure computation hook that accepts candidates + a setup's item list + the thread's categoryId, and returns per-candidate delta objects.
+
+**When to use:** Delta computation must run in a single place so list, grid, and compare views all show consistent numbers.
+
+**Interface:**
+```typescript
+// src/client/hooks/useImpactDeltas.ts
+import type { SetupItemWithCategory } from "./useSetups";
+
+interface CandidateInput {
+  id: number;
+  weightGrams: number | null;
+  priceCents: number | null;
+}
+
+type DeltaMode = "replace" | "add" | "none"; // "none" = no setup selected
+
+interface CandidateDelta {
+  candidateId: number;
+  mode: DeltaMode;
+  weightDelta: number | null;    // null = candidate has no weight data
+  priceDelta: number | null;     // null = candidate has no price data
+  replacedItemName: string | null; // populated in replace mode for tooltip
+}
+
+interface ImpactDeltas {
+  mode: DeltaMode;
+  deltas: Record<number, CandidateDelta>;
+}
+
+export function useImpactDeltas(
+  candidates: CandidateInput[],
+  setupItems: SetupItemWithCategory[] | undefined,
+  threadCategoryId: number,
+): ImpactDeltas
+```
+
+**Logic:**
+```typescript
+// Source: project codebase pattern — mirrors ComparisonTable useMemo
+const impactDeltas = useMemo(() => {
+  if (!setupItems) return { mode: "none", deltas: {} };
+
+  // Find replaced item: setup item whose categoryId matches thread's categoryId
+  const replacedItem = setupItems.find(
+    (item) => item.categoryId === threadCategoryId
+  ) ?? null;
+
+  const mode: DeltaMode = replacedItem ? "replace" : "add";
+
+  const deltas: Record<number, CandidateDelta> = {};
+  for (const c of candidates) {
+    let weightDelta: number | null = null;
+    let priceDelta: number | null = null;
+
+    if (c.weightGrams != null) {
+      weightDelta = mode === "replace" && replacedItem?.weightGrams != null
+        ? c.weightGrams - replacedItem.weightGrams
+        : c.weightGrams;
+    }
+    // priceCents is integer (cents), same arithmetic
+    if (c.priceCents != null) {
+      priceDelta = mode === "replace" && replacedItem?.priceCents != null
+        ? c.priceCents - replacedItem.priceCents
+        : c.priceCents;
+    }
+
+    deltas[c.id] = {
+      candidateId: c.id,
+      mode,
+      weightDelta,
+      priceDelta,
+      replacedItemName: replacedItem?.name ?? null,
+    };
+  }
+
+  return { mode, deltas };
+}, [candidates, setupItems, threadCategoryId]);
+```
+
+### Pattern 3: SetupImpactSelector Component
+
+**What:** A compact `<select>` dropdown in the thread detail header, rendered between the thread title and the toolbar.
+
+**When to use:** Always present on active and resolved thread pages (impact preview is read-only, no mutation side effects).
+
+**Example:**
+```typescript
+// Placed in thread header, after thread name row
+function SetupImpactSelector() {
+  const { data: setups } = useSetups();
+  const selectedSetupId = useUIStore((s) => s.selectedSetupId);
+  const setSelectedSetupId = useUIStore((s) => s.setSelectedSetupId);
+
+  if (!setups || setups.length === 0) return null;
+
+  return (
+    <div className="flex items-center gap-2">
+      <label className="text-xs text-gray-500 whitespace-nowrap">
+        Impact on setup:
+      </label>
+      <select
+        value={selectedSetupId ?? ""}
+        onChange={(e) => setSelectedSetupId(e.target.value ? Number(e.target.value) : null)}
+        className="text-sm border border-gray-200 rounded-lg px-2 py-1 text-gray-700 bg-white focus:outline-none focus:ring-1 focus:ring-gray-300"
+      >
+        <option value="">None</option>
+        {setups.map((s) => (
+          <option key={s.id} value={s.id}>{s.name}</option>
+        ))}
+      </select>
+    </div>
+  );
+}
+```
+
+### Pattern 4: ImpactDeltaBadge Rendering
+
+**What:** Small inline indicator rendered below weight/price badges on each candidate. Three rendering cases per field:
+
+| Case | Render |
+|------|--------|
+| No setup selected | Nothing (no change to existing layout) |
+| Candidate has no weight | `"-- (no weight data)"` in muted gray |
+| Weight exists, replace mode | `"±Xg vs [ItemName]"` with sign-colored text |
+| Weight exists, add mode | `"+Xg (add)"` in gray |
+
+**Where it renders:** Below the existing `formatWeight` / `formatPrice` badges in `CandidateListItem` and `CandidateCard`. In `ComparisonTable`, can be added as a sub-row or a second line within the weight/price cells.
+
+**Sign coloring convention:**
+- Negative delta (lighter/cheaper when replacing) → green text
+- Positive delta (heavier/more expensive) → red text
+- Zero delta → gray text
+- No weight data → muted gray, em-dash prefix
+
+```typescript
+// Reusable inline component
+function ImpactDeltaBadge({
+  delta,
+  noDataLabel = "-- (no weight data)",
+  unit,
+  currency,
+  type,
+}: {
+  delta: CandidateDelta | undefined;
+  noDataLabel?: string;
+  unit?: WeightUnit;
+  currency?: Currency;
+  type: "weight" | "price";
+}) {
+  if (!delta || delta.mode === "none") return null;
+
+  const value = type === "weight" ? delta.weightDelta : delta.priceDelta;
+
+  if (value === null) {
+    // Candidate has no data for this field
+    return (
+      <span className="text-xs text-gray-300">{noDataLabel}</span>
+    );
+  }
+
+  const formatted = type === "weight"
+    ? formatWeight(Math.abs(value), unit)
+    : formatPrice(Math.abs(value), currency);
+
+  const sign = value > 0 ? "+" : value < 0 ? "−" : "±";
+  const colorClass = value < 0 ? "text-green-600" : value > 0 ? "text-red-500" : "text-gray-400";
+  const modeLabel = delta.mode === "add" ? " (add)" : "";
+
+  return (
+    <span className={`text-xs font-medium ${colorClass}`}>
+      {sign}{formatted}{modeLabel}
+    </span>
+  );
+}
+```
+
+### Data Flow
+
+```
+$threadId.tsx
+  ├── selectedSetupId ← useUIStore
+  ├── thread ← useThread(threadId)          // has thread.categoryId + candidates
+  ├── setupData ← useSetup(selectedSetupId) // null when none selected
+  ├── impactDeltas ← useImpactDeltas(candidates, setupData?.items, thread.categoryId)
+  │
+  ├── <SetupImpactSelector />               // sets selectedSetupId in uiStore
+  │
+  ├── <CandidateListItem delta={impactDeltas.deltas[c.id]} />
+  ├── <CandidateCard delta={impactDeltas.deltas[c.id]} />
+  └── <ComparisonTable deltas={impactDeltas.deltas} />
+```
+
+### Anti-Patterns to Avoid
+
+- **Computing deltas in each candidate component:** Delta mode (add vs replace) must be determined once from the full setup. Computing per-component means each card independently decides mode — a setup with multiple items in different categories could give inconsistent signals if the logic is subtle.
+- **Storing selectedSetupId in URL search params:** Adds routing complexity with no benefit; the selection is ephemeral and non-shareable per project scope.
+- **Calling `useSetup` inside each candidate component:** Causes N redundant React Query calls. Call once at page level, pass deltas down.
+- **Treating `priceDelta = 0` as "no data":** Zero cost delta is a valid result (exact price match). The `null` check distinguishes missing data from zero.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Formatted weight delta strings | Custom formatter | Reuse `formatWeight(Math.abs(delta), unit)` + sign prefix | Already handles all 4 units (g/oz/lb/kg) correctly |
+| Formatted price delta strings | Custom formatter | Reuse `formatPrice(Math.abs(delta), currency)` + sign prefix | Already handles all currencies and JPY integer case |
+| Setup list fetching | Custom fetch | `useSetups()` hook | Already defined, cached by React Query |
+| Setup items fetching | Custom fetch | `useSetup(id)` hook | Already defined with enabled guard |
+| UI state management | Local useState | Zustand `selectedSetupId` | Persists across view mode switches within same session |
+
+**Key insight:** All data infrastructure exists. This phase is arithmetic + UI only.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Thread categoryId vs Candidate categoryId
+
+**What goes wrong:** Using `candidate.categoryId` instead of `thread.categoryId` to find the replaced setup item. Candidates inherit the thread's category (they're in the same decision thread), but a user could theoretically pick a different category per candidate. The impact preview is about "what does buying something for this research thread do to my setup," so the match must be on the **thread** category, not individual candidate category.
+
+**Why it happens:** `CandidateWithCategory` has a `categoryId` field that looks natural to use.
+
+**How to avoid:** In `useImpactDeltas`, accept `threadCategoryId` as a separate parameter sourced from `thread.categoryId`, not from `candidate.categoryId`.
+
+**Warning signs:** Replace mode never triggers even when a setup contains an item in the expected category.
+
+### Pitfall 2: Null vs Zero for Missing Data (IMPC-04)
+
+**What goes wrong:** When `candidate.weightGrams` is `null`, the delta would be `null - replacedItem.weightGrams = NaN` or JavaScript coerces to `0`. Rendering "0g" is actively misleading — it implies the candidate has been weighed at zero.
+
+**Why it happens:** JavaScript's `null - 200 = -200` is NaN, not zero, but string formatting might swallow this silently.
+
+**How to avoid:** Explicit null guard BEFORE arithmetic: `if (c.weightGrams == null) { weightDelta = null; }`. Render `null` delta as `"-- (no weight data)"` per IMPC-04.
+
+**Warning signs:** Candidates with no weight show "0g" or "−200g" delta.
+
+### Pitfall 3: useSetup Enabled Guard
+
+**What goes wrong:** Calling `useSetup(null)` triggers a request to `/api/setups/null` — a 404 or server error.
+
+**Why it happens:** `useSetup` has `enabled: setupId != null` guard, but if the `selectedSetupId` from Zustand is not passed correctly, it might be `undefined` rather than `null`.
+
+**How to avoid:** Coerce to `null` explicitly: `useSetup(selectedSetupId ?? null)`.
+
+**Warning signs:** Network errors in dev tools when no setup is selected.
+
+### Pitfall 4: selectedSetupId Stale Across Thread Navigation
+
+**What goes wrong:** User selects "Setup A" on thread 1, navigates to thread 2, sees impact deltas for "Setup A" which may not be relevant.
+
+**Why it happens:** Zustand state persists in memory across route changes.
+
+**How to avoid:** Two acceptable approaches:
+1. **Accept it** — the user chose a setup globally; they can clear it. Simplest.
+2. **Reset on thread change** — call `setSelectedSetupId(null)` in a `useEffect` that fires on `threadId` change.
+
+Recommended: Accept cross-thread persistence (simpler, matches how `candidateViewMode` works currently).
+
+### Pitfall 5: ComparisonTable Integration
+
+**What goes wrong:** ComparisonTable already has its own `weightDeltas` computation (candidate-relative deltas: lightest vs others). Adding setup deltas as a third numeric display in the same weight cell risks visual clutter and ambiguity about which delta is which.
+
+**Why it happens:** Two delta systems in one cell with no visual separation.
+
+**How to avoid:** Render setup impact deltas in a **separate row** in ATTRIBUTE_ROWS, or as a clearly labeled sub-row below weight. Label it "Impact" with a small setup name indicator.
+
+---
+
+## Code Examples
+
+Verified patterns from existing codebase:
+
+### Existing Delta Pattern (ComparisonTable.tsx)
+```typescript
+// Source: src/client/components/ComparisonTable.tsx
+// This shows the established useMemo pattern for delta computation
+const { bestWeightId, bestPriceId, weightDeltas, priceDeltas } =
+  useMemo(() => {
+    const withWeight = candidates.filter((c) => c.weightGrams != null);
+    let bestWeightId: number | null = null;
+    const weightDeltas: Record<number, string | null> = {};
+    // ... arithmetic over nullable numbers
+    return { bestWeightId, bestPriceId, weightDeltas, priceDeltas };
+  }, [candidates, unit, currency]);
+```
+
+### Existing useSetup Hook
+```typescript
+// Source: src/client/hooks/useSetups.ts
+export function useSetup(setupId: number | null) {
+  return useQuery({
+    queryKey: ["setups", setupId],
+    queryFn: () => apiGet<SetupWithItems>(`/api/setups/${setupId}`),
+    enabled: setupId != null,  // CRITICAL: prevents null fetch
+  });
+}
+// SetupItemWithCategory includes: categoryId, weightGrams, priceCents, name
+```
+
+### Existing formatWeight / formatPrice
+```typescript
+// Source: src/client/lib/formatters.ts
+export function formatWeight(grams: number | null | undefined, unit: WeightUnit = "g"): string {
+  if (grams == null) return "--";
+  // handles g / oz / lb / kg
+}
+export function formatPrice(cents: number | null | undefined, currency: Currency = "USD"): string {
+  if (cents == null) return "--";
+  // handles JPY integer case, others to 2dp
+}
+// Pass Math.abs(delta) to these, prefix sign manually
+```
+
+### Existing Zustand UI State Pattern
+```typescript
+// Source: src/client/stores/uiStore.ts
+// All ephemeral UI state lives here — follow same pattern
+candidateViewMode: "list" | "grid" | "compare";
+setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
+// Add analogously:
+// selectedSetupId: number | null;
+// setSelectedSetupId: (id: number | null) => void;
+```
+
+### Thread categoryId Availability
+```typescript
+// Source: src/server/services/thread.service.ts — getThreadWithCandidates
+// thread object from useThread() has .categoryId (integer) directly available
+// Note: ThreadWithCandidates interface in useThreads.ts does NOT expose categoryId
+// The raw DB thread select does, but the hook return type may need updating
+```
+
+**Important finding:** The `ThreadWithCandidates` interface in `useThreads.ts` does NOT currently include `categoryId`. The server does return it (from `db.select().from(threads)`), but the TypeScript interface omits it. The planner must add `categoryId: number` to `ThreadWithCandidates` or source it from the candidates (each `CandidateWithCategory` has `categoryId`).
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Fetch data inside components | Custom hooks with React Query | Established in project | All data fetching via hooks |
+| Local component state for UI | Zustand store | Established in project | All UI state centralized |
+
+**No deprecated patterns in scope for this phase.**
+
+---
+
+## Open Questions
+
+1. **Thread categoryId exposure in ThreadWithCandidates**
+   - What we know: `getThreadWithCandidates` in thread.service.ts returns the full thread row (including `categoryId`), but `ThreadWithCandidates` TypeScript interface in `useThreads.ts` does not declare `categoryId`
+   - What's unclear: Does the API actually serialize `categoryId` in the response or is it filtered?
+   - Recommendation: Planner should add `categoryId: number` to `ThreadWithCandidates` interface and verify the server route includes it. Alternatively, use `thread.candidates[0]?.categoryId` as a fallback since all candidates share the thread's category.
+
+2. **Selector placement on narrow viewports**
+   - What we know: Thread header already has breadcrumb, title/status pill, and toolbar row
+   - What's unclear: Three rows in mobile header may feel cramped
+   - Recommendation: Planner's discretion — can be inline with toolbar or as a third header row. Research finds no hard constraint.
+
+3. **ComparisonTable delta row placement**
+   - What we know: ATTRIBUTE_ROWS pattern is extensible (just add an object to the array)
+   - What's unclear: Whether impact rows should live inside the weight/price rows or as separate "Impact Weight" / "Impact Price" rows
+   - Recommendation: Separate labeled rows to avoid conflating candidate-relative deltas (lightest/cheapest highlighting) with setup impact deltas.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Bun test (built-in) |
+| Config file | none — bun test discovers tests automatically |
+| Quick run command | `bun test tests/services/` |
+| Full suite command | `bun test` |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| IMPC-01 | Delta values computed and passed to candidates when setup selected | unit (hook logic) | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
+| IMPC-02 | Replace mode triggered when setup contains item in same category as thread | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
+| IMPC-03 | Add mode used when no category match, delta equals candidate value | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
+| IMPC-04 | Null weight candidate returns null delta (not zero, not NaN) | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
+
+**Note:** Delta computation is pure arithmetic logic and can be tested outside React via an extracted pure function. The recommended approach is to extract `computeImpactDeltas(candidates, setupItems, threadCategoryId)` as a pure function and test it directly — no React Testing Library needed.
+
+### Sampling Rate
+- **Per task commit:** `bun test tests/lib/`
+- **Per wave merge:** `bun test`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] `tests/lib/impactDeltas.test.ts` — covers IMPC-01 through IMPC-04 via pure function extracted from `useImpactDeltas`
+- [ ] `tests/lib/` directory — create if not exists (pure utility tests go here)
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- Direct codebase read — `src/db/schema.ts` — verified `threadCandidates.categoryId`, `items.categoryId`, `setupItems` join structure
+- Direct codebase read — `src/client/hooks/useSetups.ts` — verified `SetupItemWithCategory` type includes `categoryId`, `weightGrams`, `priceCents`
+- Direct codebase read — `src/client/hooks/useThreads.ts` — identified missing `categoryId` in `ThreadWithCandidates` interface
+- Direct codebase read — `src/client/components/ComparisonTable.tsx` — verified ATTRIBUTE_ROWS pattern and existing delta computation pattern
+- Direct codebase read — `src/client/stores/uiStore.ts` — verified `selectedSetupId` does not yet exist, pattern for adding it
+- Direct codebase read — `src/client/lib/formatters.ts` — verified `formatWeight` / `formatPrice` reusability with abs values
+- Direct codebase read — `tests/helpers/db.ts` — verified test infrastructure, no schema changes needed
+
+### Secondary (MEDIUM confidence)
+- `.planning/STATE.md` — confirms "Impact preview must distinguish add-mode vs replace-mode by category match" as locked architectural decision
+
+### Tertiary (LOW confidence)
+- None
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — zero new dependencies; all libraries confirmed in package.json
+- Architecture: HIGH — derived entirely from reading existing codebase; patterns are directly reusable
+- Pitfalls: HIGH — identified from code inspection (ThreadWithCandidates missing categoryId is a concrete finding, not speculation)
+- Delta math: HIGH — straightforward arithmetic, verified types from schema
+
+**Research date:** 2026-03-17
+**Valid until:** 2026-04-17 (stable codebase; no external library research)

.planning/phases/13-setup-impact-preview/13-VALIDATION.md

@@ -0,0 +1,78 @@
+---
+phase: 13
+slug: setup-impact-preview
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-17
+---
+
+# Phase 13 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | bun test (built-in) |
+| **Config file** | bunfig.toml |
+| **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 |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 13-01-01 | 01 | 1 | IMPC-01 | unit | `bun test` | ❌ W0 | ⬜ pending |
+| 13-01-02 | 01 | 1 | IMPC-02 | unit | `bun test` | ❌ W0 | ⬜ pending |
+| 13-01-03 | 01 | 1 | IMPC-03 | unit | `bun test` | ❌ W0 | ⬜ pending |
+| 13-01-04 | 01 | 1 | IMPC-04 | unit | `bun test` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] Test stubs for IMPC-01 through IMPC-04 impact delta computation
+- [ ] Test fixtures for setup items and thread candidates with weight/price data
+
+*If none: "Existing infrastructure covers all phase requirements."*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Setup dropdown renders in thread header | IMPC-01 | Visual/UI placement | Open a thread, verify dropdown appears with all setups listed |
+| Delta labels display correctly (add vs replace) | IMPC-03 | Visual formatting | Select setup with no category match, verify "add" label |
+| Missing weight shows "-- (no weight data)" | IMPC-04 | Visual indicator | Add candidate with no weight, verify placeholder text |
+
+---
+
+## 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/research/FEATURES.md

@@ -1,201 +1,302 @@
 # Feature Research
 
-**Domain:** Gear management and purchase planning (personal inventory + research workflow)
-**Researched:** 2026-03-14
-**Confidence:** HIGH
+**Domain:** Multi-user gear management and discovery platform
+**Researched:** 2026-04-03
+**Confidence:** MEDIUM-HIGH
+
+---
+
+## Context
+
+This is the feature research for **v2.0 Platform Foundation** -- transforming GearBox from a single-user gear tracker into a multi-user platform with discovery, global item database, structured reviews, and setup sharing.
+
+**Existing features (already built through v1.4):**
+- Gear collection CRUD with categories, weight/price, images, quantity
+- Planning threads with candidate comparison, ranking, pros/cons, impact preview
+- Named setups (loadouts) with classification, donut chart visualization
+- Search/filter, CSV import/export, item duplication
+- Dashboard home page, onboarding wizard
+- Single-user auth (cookie sessions + API keys), MCP server (19 tools)
+
+**Key project constraints:**
+- No freeform UGC until moderation infrastructure exists (structured input only)
+- Discovery-first, not social-first
+- External auth provider (self-hosted, open-source)
+- Postgres for multi-user platform
+
+---
 
 ## Feature Landscape
 
 ### Table Stakes (Users Expect These)
 
-Features users assume exist. Missing these = product feels incomplete.
+Features users assume exist on any multi-user gear platform. Missing these makes the platform feel broken or pointless.
 
 | 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. |
+| **User registration and authentication** | Cannot have multi-user without accounts. Every platform has sign-up/login. | HIGH | External auth provider integration (Authentik, Keycloak, or similar). Replaces current single-user cookie auth. All existing entities need userId FK. |
+| **User profiles (public)** | Every community platform has profiles. Users need identity to share and be discovered. | LOW | Minimal: display name, avatar URL, bio text, joined date. Public profile page lists user's public setups. No follower counts needed. |
+| **Setup visibility controls** | Users will not share setups if they cannot control what is public. Privacy is table stakes for any sharing platform. | LOW | Binary public/private toggle per setup. Default to private (opt-in sharing). Existing setups migrated as private. |
+| **Public setup detail pages** | Shared setup links must resolve to a readable page. If sharing is a feature, the shared thing must be viewable. | MEDIUM | Read-only view with item list, weight/cost totals, donut chart, creator attribution. No auth required for public setups. Extends existing setup detail view. |
+| **Global item database (searchable)** | Users expect to find gear by name rather than entering specs from scratch every time. LighterPack's weakness is fully manual data entry. | HIGH | Central product catalog with brand, model, category, manufacturer weight, MSRP, product URL, image. Users search and link rather than re-enter. Seed with 200-500 items in core categories to bootstrap. This is the foundational dependency for reviews, aggregation, and item detail pages. |
+| **Link personal items to global items** | Once a global DB exists, users expect to connect their gear to canonical entries for richer data. | MEDIUM | Optional FK from user items to global items. Enables aggregation (owner count, avg weight, reviews). Must handle items not yet in global DB gracefully. |
+| **Item detail page (aggregated)** | When browsing gear, clicking an item should show consolidated info: specs, who owns it, ratings. Standard on any product platform. | HIGH | Aggregated view combining: manufacturer specs from global DB, owner count, setup appearances, average ratings, crowd-reported weights. This is the integration hub for all platform features. |
+| **Structured reviews (ratings)** | Any product-oriented community needs evaluation. Users expect to rate gear and see what others think. | MEDIUM | Overall 1-5 star rating plus 3-5 dimension ratings (varies by product category). Attached to global items, not personal items. One review per user per global item. No freeform text per project constraint. |
+| **Discovery browse page** | Users expect a way to find interesting setups and gear beyond their own collection. Without this, multi-user adds no value. | MEDIUM | Not algorithmic for v2.0. Three sections: recent public setups, recently reviewed items, popular gear (most owned). Simple sorted lists with pagination. |
+| **Search global items** | Must be able to find products by name/brand in the global database. Powers linking, browsing, and review discovery. | MEDIUM | Full-text search on name, brand, category. Used in "link my item" flow, discovery browsing, and review lookup. Postgres full-text search or trigram index. |
 
 ### Differentiators (Competitive Advantage)
 
-Features that set the product apart. Not required, but valuable.
+Features that set GearBox apart from LighterPack, GearGrams, Trailspace, and MyGear. Aligned with core value: "help people make better gear decisions."
 
 | 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. |
+| **Crowd-verified specs** | LighterPack trusts user-entered data blindly. GearBox can show "manufacturer says 450g, 12 owners measured avg 478g." Real-world weight verification is unique and high-value for weight-conscious users. | MEDIUM | Aggregate weightGrams from all user items linked to a global item. Compare against manufacturer spec. Display on item detail page. Needs sufficient linked items to be meaningful (threshold: 3+ owners). |
+| **Review dimensions per product category** | Trailspace and OutdoorGearLab use editorial ratings with fixed dimensions. GearBox crowd-sources structured ratings with category-specific dimensions: a tent gets "weather protection, ventilation, setup ease" while a stove gets "boil time, fuel efficiency, packability." More relevant than one-size-fits-all. | MEDIUM | Define 3-5 rating dimensions per product category via admin config. Store dimension ratings alongside overall rating. Display as radar chart or bar chart on item detail page. |
+| **"X people own this" social proof** | Shows popularity and real adoption. No gear tracker does this because they lack a global item database. Simple count, powerful signal. | LOW | Count of users who linked a collection item to this global item. Displayed prominently on item detail page and in search results. Zero implementation complexity once linking exists. |
+| **Setup composition insights** | "This item appears in 47 bikepacking setups, commonly paired with Y and Z." Cross-setup analysis no competitor offers. Answers "what do people use this with?" | MEDIUM | Query across all public setups containing a given global item. Show co-occurrence patterns. Powerful but can be deferred to v2.x if query performance is a concern. |
+| **Setup impact preview with global items** | Already built for personal items. Extending to global items lets users preview "adding this from the store to my setup changes weight by X." Bridges research and collection management. | LOW | Already exists for personal items. Add "preview in my setup" button on global item detail pages. Reuse existing impact preview logic. |
+| **Planning threads with global item integration** | Research threads that pull in specs, reviews, and owner data from the global DB. Candidates link to global items for richer comparison than manual data entry. | MEDIUM | Add optional globalItemId to thread candidates. Auto-populate weight, price, image from global item. Show community ratings and owner count inline on candidates. |
+| **Real-world weight distribution** | Histogram showing "owners report weights between 440g-490g" for a product. Beats a single manufacturer number. Valuable for ultralight community. | LOW | Aggregate weightGrams from all linked items. Display min/max/avg. Histogram if 10+ data points. |
+| **Copy/fork public setups** | Use someone else's setup as a starting template. LighterPack has clunky CSV-based copying. One-click fork is much better UX. | LOW | Create new setup copying all items from a public setup. Items must exist in user's collection (or be linked to same global items). Clear UX for "items you do not own yet." |
 
 ### Anti-Features (Commonly Requested, Often Problematic)
 
-Features that seem good but create problems.
-
 | 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. |
+| **Freeform text reviews** | Users want to explain their experience in detail | Requires moderation, spam filtering, content policy, reporting infrastructure. PROJECT.md explicitly defers until moderation exists. | Structured ratings with predefined dimensions. Short predefined tags for pros/cons (e.g., "lightweight", "durable", "runs small"). |
+| **Comments on setups** | Social engagement, questions about gear choices | Moderation burden, notification system, spam, harassment risk. Deferred in PROJECT.md. | Link to user profile. Contact happens outside platform. |
+| **Follow users / activity feed** | Social graph, staying updated on people | Turns a gear tool into a social network. Notification infrastructure, feed ranking, engagement metrics, retention loops. Project decision: discovery-first, not social-first. | Discovery feed shows popular/recent content without requiring social connections. |
+| **Marketplace / buy-sell** | Users want to trade used gear | Payment processing, fraud prevention, disputes, shipping logistics, tax compliance. Massive liability. | Link to product URLs on global items. Users buy through retailers. |
+| **AI gear recommendations** | "What tent should I buy for bikepacking?" | Training data requirements, bias, liability for bad recommendations, hallucination risk. | Global item pages with ratings, owner counts, and setup co-occurrence do implicit recommendation. "People who own X also own Y." |
+| **Wiki-style open item editing** | Community wants to correct/enrich global item specs | Edit wars, vandalism, quality degradation, dispute resolution. PROJECT.md explicitly rules this out. | Structured contributions only: report measured weight, submit rating. Admin approval for spec corrections. Trusted contributor program later. |
+| **Price tracking / deal alerts** | Users want to know when gear goes on sale | Requires scraping retailer sites, fragile, legal gray area, maintenance burden. PROJECT.md rules this out. | Store product URL so users can check prices manually. |
+| **Real-time collaborative setups** | "Plan a group trip together" | WebSocket infrastructure, conflict resolution, permissions model, presence indicators. Massive complexity for niche use case. | Each user builds their own setup. Fork public setups as templates. |
+| **Gamification (badges, points, levels)** | Drive engagement and contributions | Incentivizes quantity over quality. Users game systems for points rather than providing genuine data. Creates toxic dynamics. | Soft social proof: "contributed X reviews" on profile. No points, no leaderboards. |
+| **Instagram-style infinite scroll feed** | Addictive browsing experience | Engagement-maximizing design conflicts with utility-focused tool. Users come to research decisions, not scroll endlessly. | Paginated, filterable discovery page. Browse with intent, not addiction. |
+
+---
 
 ## Feature Dependencies
 
 ```
-[Item CRUD + Core Fields]
+[External Auth Provider]
     |
-    +--requires--> [Categories]
+    v
+[Multi-User Data Model (userId FK on all entities)]
     |
-    +--enables---> [Named Setups / Packing Lists]
+    +---> [Postgres Migration] (concurrent access, auth provider needs Postgres)
+    |
+    +---> [User Profiles (public)]
+    |         |
+    |         +---> [Public Profile Pages]
+    |         |         |
+    |         |         +---> [Discovery Feed (browse users' public content)]
+    |         |
+    |         +---> [Setup Visibility Controls (public/private)]
     |                   |
-    |                   +--enables---> [Setup Weight/Cost Breakdown]
-    |                   |
-    |                   +--enables---> [Impact Preview] (also requires Planning Threads)
+    |                   +---> [Public Setup Detail Pages]
+    |                             |
+    |                             +---> [Copy/Fork Public Setups]
     |
-    +--enables---> [Planning Threads]
+    +---> [Global Item Database]
+              |
+              +---> [Search Global Items]
+              |
+              +---> [Link Personal Items to Global Items]
+              |         |
+              |         +---> [Owner Count ("X people own this")]
+              |         |
+              |         +---> [Crowd-Verified Specs (aggregated weight)]
+              |         |
+              |         +---> [Setup Appearances Count]
+              |         |
+              |         +---> [Real-World Weight Distribution]
+              |
+              +---> [Structured Reviews]
+              |         |
+              |         +---> [Review Dimensions per Category]
+              |         |
+              |         +---> [Average Ratings Display]
+              |
+              +---> [Item Detail Pages (aggregated hub)]
+              |         |
+              |         +---> [Setup Composition Insights]
+              |
+              +---> [Planning Thread Global Item Integration]
                         |
-                        +--enables---> [Candidate Comparison]
-                        |
-                        +--enables---> [Thread Resolution Workflow]
-                        |                   |
-                        |                   +--creates---> items in [Collection]
-                        |
-                        +--enables---> [Priority/Ranking]
-                        |
-                        +--enables---> [Status Tracking] (researching -> ordered -> arrived)
-
-[Search & Filter] --enhances--> [Item CRUD] (becomes essential at ~30+ items)
-
-[Import CSV] --populates--> [Item CRUD] (bootstrap for spreadsheet migrants)
-
-[Photos] --enhances--> [Item CRUD] (independent, can add anytime)
-
-[Weight Unit Support] --enhances--> [All weight displays] (must be in from day one)
+                        +---> [Candidate Auto-populate from Global DB]
 ```
 
 ### Dependency Notes
 
-- **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.
+- **Multi-user data model is the absolute foundation.** Every feature depends on userId ownership. Items, setups, threads, categories, reviews -- all need user scoping. This is the biggest single migration.
+- **Postgres migration is coupled with auth.** The external auth provider (Authentik, Keycloak) needs Postgres. Migrating the app DB at the same time avoids running two databases. Do these together.
+- **Global item database is the second foundation.** Reviews, item detail pages, owner counts, crowd-verified specs, and planning thread integration all depend on canonical global item records. Without this, multi-user is just "LighterPack with accounts."
+- **Structured reviews require global items.** Reviews attach to global items, not personal collection items. Otherwise reviews fragment across duplicate user-entered items with no way to aggregate.
+- **Item detail pages are the integration point.** They combine global item specs, aggregated user data, reviews, owner count, and setup appearances. Should be built after all data sources exist.
+- **Discovery feed requires profiles + public content.** Cannot browse without user identity and visibility controls producing public content to show.
+- **Linking is the bridge.** Personal items link to global items. This single FK enables owner count, crowd-verified specs, weight distribution, and setup appearances. Prioritize this flow.
+
+---
 
 ## MVP Definition
 
-### Launch With (v1)
+### Launch With (v2.0 Platform Foundation)
 
-Minimum viable product -- what is needed to validate the concept and replace a spreadsheet.
+- [ ] **External auth provider integration** -- Nothing works without multi-user identity
+- [ ] **Postgres migration** -- Required for concurrent access; auth provider dependency
+- [ ] **Multi-user data model** -- userId on items, setups, threads, categories; data isolation
+- [ ] **User profiles (minimal)** -- Display name, avatar, bio; public profile page
+- [ ] **Setup visibility controls** -- Public/private toggle, default private
+- [ ] **Public setup detail pages** -- Shareable read-only view with attribution
+- [ ] **Global item database with seed data** -- Schema, admin seeding, search
+- [ ] **Link personal items to global items** -- Association flow in collection UI
+- [ ] **Structured reviews** -- Overall rating + dimension ratings on global items
+- [ ] **Item detail pages** -- Aggregated specs, owner count, average ratings
+- [ ] **Discovery browse page** -- Recent public setups, recently reviewed, popular items
 
-- [ ] 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 (v2.x)
 
-### Add After Validation (v1.x)
+- [ ] **Crowd-verified specs display** -- "Manufacturer: 450g, Community avg: 478g" (needs 3+ owners per item to be meaningful)
+- [ ] **Setup composition insights** -- "Commonly paired with" co-occurrence analysis
+- [ ] **Planning thread global item integration** -- Candidates auto-populate from global DB
+- [ ] **Popular gear rankings by category** -- Most owned, highest rated per category
+- [ ] **Copy/fork public setups** -- One-click template from public setups
+- [ ] **Review dimension customization** -- Admin configures rating dimensions per product category
+- [ ] **Real-world weight distribution** -- Histogram on item detail pages
+- [ ] **Global item suggestion workflow** -- Users propose new items for admin review
 
-Features to add once core is working and the planning thread workflow is proven.
+### Future Consideration (v3+)
 
-- [ ] 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
+- [ ] **Freeform reviews with moderation** -- After moderation infrastructure exists
+- [ ] **Comments on setups** -- After moderation infrastructure exists
+- [ ] **Follow users / activity feed** -- After discovery model is validated
+- [ ] **OAuth / social login** -- After external auth provider is stable
+- [ ] **Trusted contributor program** -- Verified users can edit global item specs
 
-### 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 |
+| External auth provider | HIGH | HIGH | P1 |
+| Postgres migration | HIGH | HIGH | P1 |
+| Multi-user data model (userId on entities) | HIGH | HIGH | P1 |
+| User profiles (basic) | HIGH | LOW | P1 |
+| Setup visibility controls | HIGH | LOW | P1 |
+| Public setup detail pages | HIGH | MEDIUM | P1 |
+| Global item database (schema + seed) | HIGH | HIGH | P1 |
+| Link personal items to global items | HIGH | MEDIUM | P1 |
+| Search global items | HIGH | MEDIUM | P1 |
+| Structured reviews | HIGH | MEDIUM | P1 |
+| Item detail pages (aggregated) | HIGH | HIGH | P1 |
+| Discovery browse page | MEDIUM | MEDIUM | P1 |
+| Crowd-verified specs | HIGH | LOW | P2 |
+| Setup composition insights | MEDIUM | MEDIUM | P2 |
+| Planning thread global DB integration | MEDIUM | MEDIUM | P2 |
+| Copy/fork public setups | MEDIUM | LOW | P2 |
+| Popular gear rankings | MEDIUM | LOW | P2 |
+| Freeform reviews + moderation | MEDIUM | HIGH | P3 |
+| Follow users | LOW | MEDIUM | P3 |
+| Setup comments | LOW | MEDIUM | P3 |
 
 **Priority key:**
-- P1: Must have for launch
-- P2: Should have, add when possible
-- P3: Nice to have, future consideration
+- P1: Must have for v2.0 platform launch
+- P2: Should have, add in v2.x once core is validated
+- P3: Future consideration, requires new infrastructure (moderation, notifications)
+
+---
 
 ## 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 | LighterPack | GearGrams | Trailspace | MyGear | GearBox v2.0 |
+|---------|-------------|-----------|------------|--------|-------------|
+| Gear lists/setups | Yes, drag-and-drop | Yes, trip-based | No (review only) | Yes, "Locker" | Yes, named setups with classification |
+| Weight tracking | Base/worn/consumable | Carried/worn/consumable | No | Basic | Base/worn/consumable + unit conversion + donut charts |
+| User profiles | Minimal (no bio) | Minimal | Review history page | Full social profile | Display name, avatar, bio, public setups |
+| Sharing | Public link, embed code | Public link | N/A | Social feed posts | Public/private toggle, shareable URLs |
+| Global item database | No (all user-entered) | No | Yes (editorial catalog) | No | Yes, seeded + crowd-enriched with verified specs |
+| Structured reviews | No | No | Yes (summary/pros/cons + rating) | Basic star rating | Dimension ratings per product category |
+| Item aggregation | No | No | Editorial scores only | No | Owner count, avg weight, setup appearances, crowd specs |
+| Discovery/browse | No | No | Browse by category | AI-tagged social feed | Browse setups, items, popular gear (intent-driven, not feed) |
+| Purchase research | No | No | Price comparison links | No | Planning threads with candidates, ranking, impact preview |
+| Crowd-verified specs | No | No | No | No | Manufacturer vs. community-measured weight comparison |
+| Mobile app | No | Yes (iOS/Android) | No | Yes (iOS/Android) | No (responsive web, per project constraint) |
+
+### Competitive Positioning
+
+GearBox occupies a unique niche: the only platform combining **gear management** (LighterPack's strength), **structured community reviews** (Trailspace's strength), and **crowd-verified specs** (nobody does this). The planning threads feature has no direct competitor equivalent in the gear domain.
+
+**Key advantages over each competitor:**
+- **vs. LighterPack:** Global item database eliminates manual spec entry. Multi-user with profiles and sharing. Structured reviews provide community intelligence.
+- **vs. GearGrams:** Richer comparison tools (planning threads). Crowd-verified specs. Item detail pages with aggregated data.
+- **vs. Trailspace:** Not just reviews -- full gear management and setup composition. Users own and track their gear, not just review it. Crowd ratings, not editorial-only.
+- **vs. MyGear:** Not social-first (no engagement loops, no AI tagging gimmicks). Utility-focused: research decisions, verify specs, compare options. Hobby-agnostic data model.
+
+**Accepted gaps:**
+- No mobile native app (web-first, responsive design sufficient per project constraints)
+- No social feed in the Instagram sense (intentional: discovery-first, not social-first)
+- No freeform text content (intentional: structured input only until moderation exists)
+
+---
+
+## Implementation Notes for Key Features
+
+### Global Item Database Schema
+
+The global item table is distinct from user items. It represents canonical products:
+
+- `globalItems`: id, brand, model, name (display), categoryId, manufacturerWeightGrams, manufacturerPriceCents, productUrl, imageFilename, description, createdAt, updatedAt, createdByUserId
+- User items get optional `globalItemId` FK for linking
+- Admin-seeded initially; later users can suggest additions via a proposal workflow
+
+### Structured Review Schema
+
+- `reviews`: id, userId, globalItemId, overallRating (1-5), createdAt, updatedAt
+- `reviewDimensionRatings`: id, reviewId, dimensionId, rating (1-5)
+- `reviewDimensions`: id, categoryId, name (e.g., "durability", "packability"), sortOrder
+- Unique constraint: one review per user per global item
+- Dimensions are per-category, admin-defined
+
+### Discovery Feed Approach
+
+Not a personalized algorithmic feed. Three content streams, each a simple sorted query:
+
+1. **Recent public setups** -- ORDER BY createdAt DESC, paginated
+2. **Recently reviewed items** -- Global items with recent reviews, ORDER BY latest review date
+3. **Popular gear** -- Global items ORDER BY linked owner count DESC
+
+No recommendation engine. No engagement scoring. Users browse with intent.
+
+### User Profile Data
+
+Minimal profile extending the auth provider's user record:
+
+- Display name (from auth provider or custom)
+- Avatar URL (from auth provider or uploaded)
+- Bio (short text, 280 char limit)
+- Joined date
+- Public setups list (derived from setup visibility)
+- Review count (derived)
+- Collection size (count of items, public stat)
+
+---
 
 ## 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/) -- Gear list builder, community standard for ultralight hikers. Public sharing via link, no profiles or reviews.
+- [LighterPack tutorial (99Boulders)](https://www.99boulders.com/lighterpack-tutorial) -- Feature overview including sharing, linking, limitations.
+- [GearGrams](https://www.geargrams.com/) -- Trip-based gear list tracker with weight classification.
+- [Trailspace](https://www.trailspace.com/) -- User gear reviews with structured Summary/Pros/Cons format and Review Corps program.
+- [Trailspace Review Form](https://www.trailspace.com/blog/2012/02/29/new-gear-review-form.html) -- Details on structured review fields with category-specific suggestions.
+- [MyGear](https://mygear.world/) -- Social app for sports gear with Locker, feed, AI gear recognition, challenges.
+- [Outdoor Gear Lab](https://www.outdoorgearlab.com/) -- Professional structured gear reviews with side-by-side comparison methodology.
+- [Ultralight App](https://trailsmag.net/blogs/hiker-box/ultralight-the-gear-tracking-app-i-m-leaving-lighterpack-for) -- LighterPack alternative analysis showing community pain points.
+- [Ready Set Sim](https://www.readysetsim.com/) -- Sim racing gear profiles and build sharing (cross-domain reference for hobby-agnostic patterns).
+- [GetStream Social Feed Architecture](https://getstream.io/blog/social-media-feed/) -- Feed implementation patterns and anti-patterns.
 
 ---
-*Feature research for: Gear management and purchase planning*
-*Researched: 2026-03-14*
+*Feature research for: GearBox v2.0 Platform Foundation -- multi-user gear discovery platform*
+*Researched: 2026-04-03*

.planning/research/PITFALLS.md

@@ -1,249 +1,436 @@
 # 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:** Single-user to multi-user gear platform migration (GearBox v2.0)
+**Researched:** 2026-04-03
+**Confidence:** HIGH (based on direct codebase analysis of v1.4 + established migration patterns)
 
 ## Critical Pitfalls
 
-### Pitfall 1: Unit Handling Treated as Display-Only
+### Pitfall 1: Missing userId Filters Leak Data Between Users
 
 **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.
+Every query in the existing codebase operates without a `userId` filter. After adding `userId` columns to `items`, `categories`, `threads`, `setups`, and `settings`, any service function not updated to filter by `userId` will return or mutate other users' data. The current `getAllItems()` returns `db.select().from(items).innerJoin(...)` with zero WHERE clauses. One missed function means User A sees User B's gear.
+
+The surface area is large: 6 service files, 19 MCP tools, 7 route files, aggregate queries in `totals`, the `duplicateItem` function, the `getCollectionSummary` MCP resource, setup-item joins, and thread resolution (which creates a new item).
 
 **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.
+Developers add `userId` to the schema, update the obvious CRUD functions, but miss edge cases. The codebase has enough query sites (~30+) that manual "find all queries" misses something. Thread resolution is particularly dangerous because it creates an item as a side effect of updating a thread.
 
 **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. Enable Postgres Row-Level Security (RLS) as a safety net -- even if the app filters by `userId`, RLS prevents cross-user access at the database level.
+2. Add `userId` as NOT NULL to the Drizzle schema first, then use TypeScript compiler errors to find every query that needs updating (insert calls will fail where `userId` is required but not provided).
+3. Write one integration test per entity: create data as User A, query as User B, assert empty results.
+4. Grep the codebase for every `.from(items)`, `.from(categories)`, `.from(threads)`, `.from(setups)`, `.from(settings)` and verify each has a `userId` filter.
 
 **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
+- Any service function that does not accept a `userId` parameter after migration.
+- Tests that pass without specifying which user is performing the action.
+- MCP tools that work without user context.
 
 **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.
+Multi-user data model phase. This is the single most important thing to get right. Do not add public content or discovery features until every query is provably user-scoped.
 
 ---
 
-### Pitfall 2: Rigid Category Hierarchy Instead of Flexible Tagging
+### Pitfall 2: Category Name Uniqueness Breaks in Multi-User
 
 **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.
+The current schema has `name: text("name").notNull().unique()` on the `categories` table -- a global unique constraint. When User A creates a "Bikepacking" category, User B cannot. The migration must change this to a composite unique constraint on `(userId, name)`.
 
 **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.
+Single-user apps use simple unique constraints. Developers add `userId` to the table but forget to update the unique constraint from `unique(name)` to `unique(userId, name)`. The migration runs fine on an empty database but fails the moment a second user creates a category with a common name.
 
 **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.
+Audit every `.unique()` constraint in the schema during migration. `categories.name` must become a composite unique on `(userId, name)`. The `users.username` unique stays global (desired). No other tables currently have unique constraints, but new tables (reviews, products) should use composite uniqueness from the start.
 
 **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
+- Database constraint errors when a second user creates categories.
+- Tests that only ever use one user.
 
 **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.
+Multi-user data model phase, during schema migration.
 
 ---
 
-### Pitfall 3: Planning Thread State Machine Complexity Explosion
+### Pitfall 3: Drizzle Schema Rewrite Is a Replacement, Not a Migration
 
 **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.
+Drizzle ORM schemas are dialect-specific. The current schema imports from `drizzle-orm/sqlite-core` and uses `sqliteTable`, `integer().primaryKey({ autoIncrement: true })`, and `real()`. The Postgres schema must import from `drizzle-orm/pg-core` and use `pgTable`, `serial()` or `integer().generatedAlwaysAsIdentity()`, and `doublePrecision()`. This is not a migration Drizzle can auto-generate -- it requires a full schema rewrite and a fresh migration history.
+
+Specific differences that will cause bugs if missed:
+- `integer("id").primaryKey({ autoIncrement: true })` becomes `serial("id").primaryKey()` or `integer("id").primaryKey().generatedAlwaysAsIdentity()`.
+- `integer("created_at", { mode: "timestamp" })` -- SQLite stores timestamps as integers. Postgres has native `timestamp` type. Must decide: keep integer storage or switch to Postgres `timestamp()`.
+- `real("weight_grams")` -- SQLite `REAL` is 8-byte float. Postgres `real` is 4-byte float (less precision). Use `doublePrecision()` for equivalent behavior.
+- SQLite `text("status")` with string values works as pseudo-enum. Postgres has native `pgEnum` for type safety.
+- The `Db` type alias (`typeof prodDb`) changes entirely -- every service file and MCP tool imports this type.
 
 **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.
+Developers assume Drizzle abstracts away database differences. It does not at the schema layer. The query builder is mostly compatible, but schema definition is dialect-specific by design.
 
 **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.
+1. Write a new `schema.ts` from scratch using `pg-core`, not edit the existing one.
+2. Start a fresh Drizzle migration history for Postgres. SQLite migrations are irrelevant.
+3. Write a data migration script that reads from old SQLite and inserts into new Postgres.
+4. Update the `Db` type alias in all service files.
+5. Use `doublePrecision()` not `real()` for weight values to maintain precision parity with SQLite.
 
 **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)
+- Weight values losing precision (245.5g becoming 245.49999...).
+- Timestamps behaving differently (integer epoch vs. native timestamp).
+- drizzle-kit refusing to generate migrations against the wrong dialect.
 
 **Phase to address:**
-Phase 2 (Planning threads) -- design the state machine before writing any thread code. Do not add statuses incrementally.
+Database migration phase. Must complete before any other v2.0 feature.
 
 ---
 
-### Pitfall 4: Image Storage Strategy Causes Data Loss or Bloat
+### Pitfall 4: Test Infrastructure Collapses During Database Switch
 
 **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 entire test infrastructure is built on SQLite. `createTestDb()` uses `bun:sqlite` with `Database(":memory:")` and `drizzle-orm/bun-sqlite`. E2E tests use a file-based SQLite (`e2e/test.db`). After switching to Postgres, every test needs a Postgres connection -- no more in-memory databases.
+
+The MCP server hard-codes `db as prodDb` which is an SQLite Drizzle instance. The Hono context variable type for `db` changes. Every route handler that does `c.get("db")` gets a different type.
 
 **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.
+In-memory SQLite is the best testing story in the Bun ecosystem -- fast, isolated, no external services. Postgres testing requires either: (a) a running Postgres instance, (b) testcontainers with Docker, or (c) PGlite (lightweight Postgres in WebAssembly). Developers delay updating tests and end up with a broken test suite for weeks.
 
 **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. Adopt PGlite (`@electric-sql/pglite`) for unit/integration tests. It provides in-memory Postgres without Docker. Drizzle supports PGlite via `drizzle-orm/pglite`.
+2. Update `createTestDb()` to use PGlite instead of bun:sqlite.
+3. For E2E tests, use Docker Compose with a test Postgres instance, or PGlite if performance is acceptable.
+4. Update the Hono context variable type to the new Postgres Drizzle instance type.
+5. Migrate test infrastructure in the same phase as the schema, not after.
 
 **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
+- `bun test` fails across the board after schema change.
+- "Type 'BunSQLiteDatabase' is not assignable to type 'PgDatabase'" errors everywhere.
+- E2E tests silently skipped or disabled "temporarily."
 
 **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.
+Database migration phase. Tests must migrate alongside the schema.
 
 ---
 
-### Pitfall 5: Setup Composition Breaks on Collection Changes
+### Pitfall 5: Auth Provider Integration Breaks Existing Sessions, API Keys, and MCP
 
 **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 current auth stores users, sessions, and API keys in the local database. Switching to an external auth provider means: (1) user identity moves external, (2) session management changes (JWT or OAuth flow vs. cookie sessions), (3) existing API keys become orphaned because they reference the old user table, (4) the MCP server authenticates via API keys stored locally, (5) E2E tests authenticate via `POST /api/auth/login` with a seeded user, (6) the onboarding flow (`POST /api/auth/setup`) creates the first user.
 
 **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.
+Auth migration is treated as "swap the login page" when it touches the entire authentication surface: user identity, session lifecycle, API key management, MCP authentication, E2E test setup, and onboarding.
 
 **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. Keep API keys in the local database even after auth moves external. API keys are long-lived credentials managed by the application, not the auth provider.
+2. Map external provider user IDs to a local `users` table. The external provider handles authentication; the local table handles application-level data (userId foreign keys, API keys, preferences). Foreign keys reference local `users.id`, not the provider's UUID.
+3. Replace the onboarding flow: instead of "create admin account," it becomes "sign up via external provider, first user gets admin role."
+4. Update E2E tests to either mock the auth provider or use API key authentication exclusively for E2E.
 
 **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
+- MCP server stops working after auth migration.
+- E2E tests that log in via `POST /api/auth/login` all fail.
+- API keys created before migration stop working.
+- No local `users` table -- everything delegated to external provider.
 
 **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.
+Auth migration phase. Should be done early because user identity is the foundation.
 
 ---
 
-### Pitfall 6: Comparison View That Does Not Actually Help Decisions
+### Pitfall 6: Global Item Database Creates a Data Model Fork
 
 **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.
+The current `items` table represents user-owned gear. The v2.0 vision includes a "global item database" with manufacturer specs. These are fundamentally different entities: a user's item has quantity, personal notes, setup associations, and belongs to a user. A global item is a product definition with canonical specs, owned by nobody. Conflating them in one table (via `isGlobal` flag or `NULL userId`) creates an unmaintainable mess. Separating them creates a sync problem.
 
 **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.
+It seems efficient to add an `isGlobal` flag. But then queries need to handle both cases, user items need to link to global items for spec inheritance, and the API surface doubles with different permission models.
 
 **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. Create a separate `products` table for the global database. A product has: name, manufacturer, canonical weight, canonical price, product URL, image, category.
+2. User `items` gets a nullable `productId` foreign key. When set, the item inherits specs from the product but can override them (user's measured weight vs. manufacturer spec).
+3. User items without a `productId` are standalone (backward-compatible with all existing items).
+4. Reviews, owner counts, and setup appearances link to `products`, not user `items`.
 
 **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
+- `items` table query complexity increases beyond what is reasonable.
+- Ambiguity about whether an operation affects "my item" or "the global product."
+- Permission model becomes unclear (who can edit a global product?).
 
 **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.
+Global item database phase. Must come after multi-user data model is stable.
+
+---
+
+### Pitfall 7: Image Storage Migration Breaks Existing URLs and the MCP Tool
+
+**What goes wrong:**
+Images are stored in `./uploads/` on the filesystem, served via `app.use("/uploads/*", serveStatic({ root: "./" }))`, and referenced by `imageFilename` in the database. Moving to object storage changes URLs from `/uploads/uuid.jpg` to `https://bucket.s3.region.amazonaws.com/uuid.jpg`. Every existing `imageFilename` reference becomes a broken image.
+
+Both `items` and `threadCandidates` have `imageFilename` and `imageSourceUrl` fields. The MCP tool `upload_image_from_url` saves to the local filesystem. The image route `POST /api/images` saves to `./uploads/`.
+
+**Why it happens:**
+The current design stores only the filename, not the full URL. The serving path is implicit (prepend `/uploads/`). When storage moves to S3, the "prepend `/uploads/`" pattern breaks.
+
+**How to avoid:**
+1. Add a reverse proxy route: keep `/uploads/*` working but proxy to S3 instead of local filesystem. This maintains backward compatibility during transition.
+2. Or migrate `imageFilename` to store full URLs. Existing filenames get prefixed with the S3 URL during data migration.
+3. Write a migration script that uploads all `./uploads/` files to S3 and updates database references.
+4. Update `POST /api/images`, `POST /api/images/from-url`, and the MCP `upload_image_from_url` tool to write to S3.
+5. Create an image storage abstraction layer so dev can use local filesystem and production uses S3.
+
+**Warning signs:**
+- Broken images after deployment.
+- Mixed URLs (some `/uploads/`, some `https://s3...`) in the database.
+- MCP tool `upload_image_from_url` silently failing.
+
+**Phase to address:**
+Infrastructure phase. Should be done before discovery/public profiles (which serve images to many users).
+
+---
+
+### Pitfall 8: Thread Resolution Creates Items Without Proper User Scoping
+
+**What goes wrong:**
+Thread resolution copies a candidate's data into a new item. In multi-user, the newly created item must inherit the thread owner's `userId`. If the resolution logic does not explicitly set `userId` on the new item, it either fails (NOT NULL constraint) or creates an orphaned item.
+
+This is a specific instance of Pitfall 1 but deserves its own callout because resolution is a multi-step transaction: update thread status, set `resolvedCandidateId`, create new item. Any step that forgets `userId` breaks the chain.
+
+**Why it happens:**
+The resolution logic is tested as a unit but the test does not set a `userId` because none existed. After adding `userId`, the test still passes if using a default/NULL value. The bug only surfaces with a second user.
+
+**How to avoid:**
+1. Make `userId` NOT NULL on all entity tables from day one.
+2. Update `resolveThread` to accept and propagate `userId`.
+3. Write a test: resolve thread as User A, verify created item belongs to User A.
+
+**Warning signs:**
+- Items appearing in the wrong user's collection after resolution.
+- Thread resolution failing with constraint violations.
+
+**Phase to address:**
+Multi-user data model phase.
+
+---
+
+### Pitfall 9: Public Content Without Explicit Privacy Controls
+
+**What goes wrong:**
+The v2.0 plan includes "public user profiles with shared setups" and a "discovery feed." Without explicit visibility controls, the default state is ambiguous: are new setups public? Are all items in a public setup visible? Can someone discover gear a user has not chosen to share? Users expecting a private gear tracker are surprised when their collection appears in search results.
+
+**Why it happens:**
+The developer defaults to "everything public" because it is simpler to build discovery features. Privacy controls are added as an afterthought, requiring a retroactive audit of all existing data.
+
+**How to avoid:**
+1. Default to private. Every entity (setup, profile) is private unless explicitly published.
+2. Add a `visibility` column (`private` | `public`) to setups. Items are visible publicly only through public setups.
+3. User profiles are private by default. Public profile is opt-in.
+4. Public API endpoints (discovery, search) only query entities with `visibility = 'public'`.
+5. Build the visibility model in the data layer before building any discovery UI.
+
+**Warning signs:**
+- No `visibility` or `isPublic` column in the schema.
+- Discovery queries that do not filter by visibility.
+- User complaints about unexpected data exposure.
+
+**Phase to address:**
+Multi-user data model phase (add visibility columns) and discovery phase (enforce in queries).
+
+---
+
+### Pitfall 10: SQLite-Specific Patterns That Silently Break on Postgres
+
+**What goes wrong:**
+The codebase has SQLite-specific patterns that will not error but will behave differently on Postgres:
+- `src/db/index.ts` runs `PRAGMA journal_mode = WAL` and `PRAGMA foreign_keys = ON` -- Postgres has no PRAGMAs. Foreign keys are always enforced. WAL is always on.
+- `bun:sqlite` is used as the driver. Postgres needs `postgres` (postgres.js) or `pg` (node-postgres) as the driver.
+- The existing Drizzle migrator import is `drizzle-orm/bun-sqlite/migrator`. Postgres uses `drizzle-orm/node-postgres/migrator` or `drizzle-orm/postgres-js/migrator`.
+- SQLite allows inserting strings into integer columns silently. Postgres will error.
+- SQLite `AUTOINCREMENT` guarantees IDs never reuse. Postgres `serial` reuses IDs after deletions if the sequence is not explicitly configured.
+- The test helper's `Database(":memory:")` has no Postgres equivalent without PGlite.
+
+**Why it happens:**
+These patterns are invisible in a working SQLite app. They only surface during or after the switch, often as runtime errors in production.
+
+**How to avoid:**
+1. Remove all PRAGMA statements when switching to Postgres.
+2. Replace `bun:sqlite` driver with `postgres` (postgres.js is recommended for Bun compatibility).
+3. Update all migrator imports.
+4. Run the full test suite against Postgres to catch type strictness differences.
+5. Use `serial` or `identity` columns for auto-increment; accept that IDs may be reused after deletion (this should not matter for a web app).
+
+**Warning signs:**
+- "PRAGMA" in the Postgres codebase.
+- `bun:sqlite` imports anywhere in production code after migration.
+- Tests passing against SQLite but failing against Postgres.
+
+**Phase to address:**
+Database migration phase.
+
+---
+
+### Pitfall 11: Setup-Item Delete-All-Reinsert Pattern Causes Phantom Reads
+
+**What goes wrong:**
+The current setup item sync uses delete-all-then-re-insert: `DELETE FROM setup_items WHERE setupId = X`, then re-insert all items. In single-user SQLite this is fine. In multi-user Postgres with concurrent writes: (a) race conditions if two users modify setups simultaneously, (b) brief windows where a public setup appears empty to concurrent readers.
+
+**Why it happens:**
+The pattern was chosen for simplicity (noted in CLAUDE.md: "Simpler than diffing, atomic in transaction"). "Atomic in transaction" only holds if the transaction isolation level prevents phantom reads, which is not the default in Postgres (`READ COMMITTED`).
+
+**How to avoid:**
+1. Wrap in an explicit transaction with `SERIALIZABLE` or `REPEATABLE READ` isolation for the sync operation.
+2. Or switch to diff-based approach for public setups: compare existing vs. new list, delete removed, insert added.
+3. For private setups, the delete-reinsert pattern with a basic transaction is acceptable.
+
+**Warning signs:**
+- Public setups briefly appearing empty.
+- Foreign key violations in concurrent scenarios.
+
+**Phase to address:**
+Multi-user data model phase, when updating the setup service.
+
+---
+
+### Pitfall 12: Existing Data Has No Owner After Multi-User Migration
+
+**What goes wrong:**
+The existing SQLite database has items, categories, threads, setups -- all without a `userId` column. When the schema adds `userId NOT NULL`, the existing data needs an owner. If the migration script does not assign existing data to the original user, the data is either lost (NOT NULL violation prevents migration) or orphaned.
+
+**Why it happens:**
+The developer writes the new schema with `userId NOT NULL`, runs `db:push`, and the migration fails because existing rows have no `userId`. The "fix" is to make `userId` nullable, which undermines the entire data isolation model.
+
+**How to avoid:**
+1. The data migration script must: (a) create the original user in the new system, (b) assign all existing data to that user's ID, (c) then apply the NOT NULL constraint.
+2. Migration order: create tables with `userId` nullable, insert data with the owner's userId, then ALTER to NOT NULL.
+3. Verify row counts match before and after migration.
+
+**Warning signs:**
+- `userId` column is nullable in the final schema "because of migration."
+- Existing data missing after migration.
+- Migration script that only handles schema, not data.
+
+**Phase to address:**
+Database migration phase, specifically the data migration step.
 
 ---
 
 ## Technical Debt Patterns
 
-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) |
+| Keeping SQLite test infrastructure while developing Postgres features | Tests keep passing during migration | Two database dialects to maintain, false confidence from tests that do not match production | Never -- migrate tests alongside schema |
+| Storing both old `/uploads/` paths and new S3 URLs | Avoid data migration script | Every image-rendering component handles both URL formats forever | Only as a 1-2 week transition |
+| Using `userId` as nullable during migration | Existing data does not need backfilling | Every query must handle NULL userId, privacy bugs when userId is missing | Only during the migration transaction itself, then enforce NOT NULL |
+| Skipping RLS and relying only on app-level userId filtering | Faster to implement | Single missed WHERE clause = data leak | Never for multi-user platforms |
+| Deferring visibility controls to "after discovery ships" | Ship discovery faster | Retroactive privacy audit, potential data exposure, user trust damage | Never |
+| Keeping the local `users` table password hash after external auth | Avoid migration complexity | Dead column confuses future developers, potential security liability | Never -- remove password hash column after auth migration |
 
 ## Integration Gotchas
 
-Common mistakes when connecting to external services.
-
 | 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. |
+| External auth provider | Removing the local `users` table entirely | Keep a local `users` table with `externalId` (from auth provider) + local fields (preferences, API keys). Foreign keys reference local `users.id`, not the external provider's UUID. |
+| External auth provider | Storing user profile data in the auth provider and querying it at runtime | Store only identity in auth provider. Sync user profile to local `users` table on login. Application queries local table only. |
+| External auth provider | Using auth provider's session tokens directly as API authentication | Auth provider handles login/logout. Application mints its own session after verifying the auth provider's token. This decouples session lifecycle from the provider. |
+| S3-compatible object storage | Using the S3 SDK directly in route handlers | Create an image storage abstraction (interface with `upload`, `getUrl`, `delete`). Swap implementations (local filesystem for dev, S3 for production) via environment config. |
+| Postgres driver | Assuming `bun:sqlite` patterns work with Postgres | Postgres uses `postgres` (postgres.js) or `pg`. Connection pooling, async queries, and error handling differ. SQLite is synchronous; Postgres is async. Service functions may need to become async. |
+| Postgres | Assuming SQLite PRAGMA behaviors exist | Postgres has no PRAGMAs. Foreign keys are always on. WAL is always on. Remove all PRAGMA code. |
+| Drizzle ORM Postgres driver | Using synchronous `.get()` and `.all()` query methods | SQLite Drizzle uses `.get()` (sync). Postgres Drizzle uses `.execute()` or `await` on queries. Every service function that calls `.get()` or `.all()` must be updated. |
 
 ## Performance Traps
 
-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 |
+| N+1 queries in discovery feed | Feed page takes 2+ seconds | Use joins or batch queries for setups with items and categories | 50+ setups in feed, each with 10+ items |
+| Unindexed `userId` columns | All queries slow after adding userId filtering | Add indexes on `userId` for every table. Composite indexes for `(userId, categoryId)` on items. | 1000+ items across 50+ users |
+| Full-table scans for aggregates | Dashboard slow for large collections | Current aggregates are computed via SQL on read. Add materialized views or cache for public setup totals. | 100+ items per user, or public setups viewed by 100+ visitors |
+| Image serving from app server | Server CPU/bandwidth saturated | Serve images from S3/CDN. Current `serveStatic` for uploads hits the app server for every request. | 100+ concurrent users browsing image-heavy pages |
+| Global product search without full-text index | Product search slow or inaccurate | Use Postgres full-text search (`tsvector`/`tsquery`) or `pg_trgm` trigram index. | 10,000+ products |
+| Synchronous service functions on Postgres | Request timeouts, connection pool exhaustion | SQLite Drizzle is sync. Postgres Drizzle is async. Service functions that were sync must become async. | Any usage under load |
 
 ## Security Mistakes
 
-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. |
+| No RLS, relying only on app-level userId filtering | Single missed WHERE clause exposes all user data | Enable Postgres RLS on all user-owned tables. App filtering is primary; RLS is safety net. |
+| Public setup exposes private item details | Users share a setup but private notes/pricing leak | Public setup views project only public fields (name, weight, category). Define a "public item projection" and enforce it. |
+| API keys not scoped to users after auth migration | API key created by User A operates on User B's data | API keys must associate with a userId. After validation, the key's userId scopes all operations. |
+| Auth provider misconfigured for open self-registration | Random users create accounts without approval | Configure auth provider for admin-approval or invite-only registration. Test explicitly. |
+| Image upload accepts any file type | Stored XSS via SVG uploads, executable content | Validate MIME type on upload (JPEG, PNG, WebP only). Set `Content-Type` and `Content-Disposition` headers. Strip EXIF metadata. |
+| External auth provider callback URL not validated | OAuth redirect attack | Whitelist exact callback URLs in auth provider config. Never use wildcard redirect URIs. |
 
 ## UX Pitfalls
 
-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 |
+| Forcing existing single user to re-register via external auth | User loses access to their own data until they figure out new login | Migration path: on first visit after upgrade, guide user to create auth provider account and automatically link to existing data. |
+| Public profiles default to showing everything | Users surprised their gear list is public | Default profile to private. Public is opt-in with clear preview of what others see. |
+| Review system with only star ratings | Ratings without context are useless for gear decisions | Structured reviews with predefined fields (durability, weight accuracy, value) per category. "Weight is 15g heavier than listed" is actionable; a 4-star rating is not. |
+| Discovery feed dominated by one hobby | Users in other hobbies see irrelevant content | Category-based feed filtering. Show content relevant to user's categories. |
+| No indication of data ownership when browsing others' setups | User tries to edit someone else's setup and gets error | Clear visual distinction between "my setup" and "someone else's setup." Read-only view with "copy to my setups" action. |
+| Settings lost during migration | User's weight unit preference, onboarding state disappear | Migrate the `settings` table data alongside everything else. Map settings to the original user. |
 
 ## "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
+- [ ] **Multi-user data model:** Often missing userId on the `settings` table -- verify settings are user-scoped (weight unit preference, onboarding state).
+- [ ] **Multi-user data model:** Often missing userId filter on `threadCandidates` queries that join through `threads` -- verify candidates are not directly queryable across users.
+- [ ] **Multi-user data model:** Often missing userId on thread resolution -- verify `resolveThread` propagates userId to the newly created item.
+- [ ] **Auth migration:** Often missing MCP server auth update -- verify MCP tools operate in context of the authenticated user, not as global admin.
+- [ ] **Auth migration:** Often missing E2E test auth update -- verify E2E tests authenticate against new auth system or use API keys.
+- [ ] **Auth migration:** Often missing API key userId association -- verify API keys created after migration are scoped to the creating user.
+- [ ] **Database migration:** Often missing data migration script -- verify existing SQLite data is actually moved to Postgres, not just the schema.
+- [ ] **Database migration:** Often missing timestamp conversion -- verify SQLite integer timestamps are correctly handled in Postgres schema.
+- [ ] **Database migration:** Often missing weight precision check -- verify `real()` vs `doublePrecision()` does not lose decimal precision.
+- [ ] **Database migration:** Often missing sync-to-async conversion -- verify all service functions are async after Postgres switch.
+- [ ] **Image migration:** Often missing MCP tool update -- verify `upload_image_from_url` writes to S3, not local filesystem.
+- [ ] **Image migration:** Often missing `imageSourceUrl` field -- verify source URL metadata is preserved during migration.
+- [ ] **Public content:** Often missing visibility filtering on aggregate endpoints -- verify `/api/totals` only counts requesting user's items.
+- [ ] **Reviews:** Often missing rate limiting -- verify a user cannot submit 100 reviews in a minute.
+- [ ] **Discovery feed:** Often missing pagination -- verify feed does not load all public setups at once.
+- [ ] **Global items:** Often missing product-vs-item distinction -- verify adding a product to global database does not add it to anyone's collection.
 
 ## Recovery Strategies
 
-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. |
+| Data leaked between users (missing userId filter) | HIGH | Audit all queries, add RLS immediately, notify affected users, review access logs. Reputation damage is the real cost. |
+| Broken images after storage migration | MEDIUM | Keep old uploads directory as fallback. Re-upload missing images. Update database references. |
+| Test suite broken for weeks during DB migration | MEDIUM | Pause feature work. Set up PGlite test infrastructure. Port tests one file at a time. |
+| Auth migration breaks MCP server | LOW | MCP server can fall back to API key auth (already implemented). Fix isolated to MCP auth middleware. |
+| Category unique constraint failures | LOW | Drop old unique constraint, add composite unique. Single transaction. |
+| Weight precision loss (SQLite real to Postgres real) | LOW | Alter column to `doublePrecision`. One-time verification script. |
+| Public data exposure before visibility controls | HIGH | Emergency: set all entities to private, deploy, then build visibility controls properly. Cannot undo exposure. |
+| Existing data orphaned after migration | MEDIUM | Re-run data migration script with correct userId assignment. Verify row counts. |
+| Service functions still sync after Postgres switch | MEDIUM | Systematic conversion of all service functions to async. Update all callers. TypeScript will catch most issues. |
 
 ## Pitfall-to-Phase Mapping
 
-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. |
+| Missing userId filters (P1) | Multi-user data model | Integration tests: create as User A, query as User B, assert empty. RLS policies active. |
+| Category uniqueness (P2) | Multi-user data model | Two users create identically-named categories without constraint violations. |
+| Drizzle schema rewrite (P3) | Database migration | Schema compiles with pg-core. drizzle-kit generates valid Postgres migrations. Weight values maintain precision. |
+| Test infrastructure collapse (P4) | Database migration | `bun test` passes with PGlite. E2E tests pass against Postgres. No SQLite imports in test code. |
+| Auth provider breaks sessions/keys (P5) | Auth migration | Existing API keys work. MCP server authenticates. E2E tests pass. First-time setup works via external provider. |
+| Global item data model fork (P6) | Global item database | Separate `products` table exists. User items optionally reference a product. CRUD operations distinct. |
+| Image URL breakage (P7) | Infrastructure / Image storage | Existing images render. New uploads go to S3. MCP upload tool works. |
+| Thread resolution userId (P8) | Multi-user data model | Resolving a thread creates an item owned by the thread's owner. Tested with multiple users. |
+| Privacy/visibility (P9) | Multi-user data model + Discovery | Default is private. Public queries filter by visibility. No private data in discovery feed. |
+| SQLite-specific patterns (P10) | Database migration | No PRAGMAs in codebase. No bun:sqlite imports. All queries async. |
+| Setup sync race conditions (P11) | Multi-user data model | Concurrent setup modifications do not produce empty setups or constraint violations. |
+| Existing data ownership (P12) | Database migration | All existing data assigned to original user. Row counts match. userId NOT NULL enforced. |
 
 ## 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
+- Direct codebase analysis of GearBox v1.4 (schema.ts, services, auth middleware, MCP server, test helpers, db/index.ts, E2E seed)
+- [Drizzle ORM PostgreSQL documentation](https://orm.drizzle.team/docs/get-started/postgresql-new)
+- [Drizzle ORM SQLite column types](https://orm.drizzle.team/docs/column-types/sqlite)
+- [Drizzle ORM migrations documentation](https://orm.drizzle.team/docs/migrations)
+- [SQLite to PostgreSQL migration pitfalls (Open WebUI discussion)](https://github.com/open-webui/open-webui/discussions/21609)
+- [How to migrate from SQLite to PostgreSQL (Render)](https://render.com/articles/how-to-migrate-from-sqlite-to-postgresql)
+- [Multi-tenant architecture guide (WorkOS)](https://workos.com/blog/developers-guide-saas-multi-tenant-architecture)
+- [Multi-tenant vs single-tenant SaaS (Clerk)](https://clerk.com/blog/multi-tenant-vs-single-tenant)
+- [Migrating file storage to Amazon S3 (DZone)](https://dzone.com/articles/migrating-file-storage-to-amazon-s3)
+- [Drizzle ORM PostgreSQL best practices 2025 (GitHub Gist)](https://gist.github.com/productdevbook/7c9ce3bbeb96b3fabc3c7c2aa2abc717)
 
 ---
-*Pitfalls research for: GearBox -- gear management and purchase planning app*
-*Researched: 2026-03-14*
+*Pitfalls research for: GearBox v2.0 -- Single-user to multi-user platform migration*
+*Researched: 2026-04-03*

.planning/research/STACK.md

@@ -1,191 +1,260 @@
 # Stack Research
 
-**Domain:** Single-user gear management and purchase planning web app
-**Researched:** 2026-03-14
-**Confidence:** HIGH
+**Domain:** Multi-user gear management platform (v2.0 platform additions)
+**Researched:** 2026-04-03
+**Confidence:** MEDIUM-HIGH
+
+This document covers ONLY the new stack additions for v2.0. The existing stack (React 19, Hono, Drizzle ORM, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, framer-motion, Zustand, Zod, Bun) is validated and unchanged.
 
 ## Recommended Stack
 
-### Core Technologies
+### Authentication -- Logto (Self-Hosted)
 
 | 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. |
+| Logto OSS | v1.36+ | External OIDC/OAuth 2.1 auth provider | TypeScript-native, purpose-built for app auth (not enterprise IAM), requires Postgres (shared infra), beautiful pre-built sign-in UI, React SDK with hooks, lightweight JWT validation on backend. MIT-licensed core. |
+| @logto/react | ^4.0.13 | React SDK for auth flows | LogtoProvider wraps app, provides useLogto() hook for sign-in/sign-out/token access. Handles OIDC redirect flow, token refresh, and user info. |
+| jose | ^6.2.2 | JWT validation on Hono backend | Zero-dependency, Bun-compatible, used to verify Logto-issued access tokens via JWKS. Recommended by Logto docs over heavier alternatives. |
+
+**Why Logto over alternatives:**
+
+| Provider | Why Not |
+|----------|---------|
+| Authentik | Python-based, heavyweight (designed for enterprise proxy/SSO), overkill for app-level auth. No React SDK -- requires raw OIDC integration. Better for infra-level SSO (Portainer, Grafana). |
+| Zitadel | Go-based, Kubernetes-first architecture, AGPL 3.0 license (copyleft since 2025). Stronger for multi-tenant B2B SaaS. Over-engineered for a single-product platform. |
+| SuperTokens | Session-based by default (not OIDC), requires embedding their middleware into your backend. Tighter coupling than external provider model. |
+| Keycloak | Java-based, heavy memory footprint (1-2GB RAM), complex admin UI. Industry standard but vastly over-scoped for this use case. |
+
+**Integration pattern:** Logto runs as a separate Docker container alongside Postgres. React app redirects to Logto's hosted sign-in page for auth flows. Hono backend validates JWT access tokens from the Authorization header using `jose` JWKS verification -- no Logto SDK needed on the backend, just standard OIDC token validation. User identity is the Logto `sub` claim (a stable string ID), stored as `userId` on all user-owned records.
+
+**Backend middleware pattern (Hono):**
+
+```typescript
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+const jwks = createRemoteJWKSet(
+  new URL("https://logto.example.com/oidc/jwks")
+);
+
+const authMiddleware = createMiddleware(async (c, next) => {
+  const token = c.req.header("Authorization")?.replace("Bearer ", "");
+  if (!token) return c.json({ error: "Unauthorized" }, 401);
+
+  const { payload } = await jwtVerify(token, jwks, {
+    issuer: "https://logto.example.com/oidc",
+    audience: "your-api-resource-indicator",
+  });
+
+  c.set("userId", payload.sub);
+  await next();
+});
+```
+
+**React provider pattern:**
+
+```typescript
+import { LogtoProvider, LogtoConfig } from "@logto/react";
+
+const config: LogtoConfig = {
+  endpoint: "https://logto.example.com",
+  appId: "<your-app-id>",
+  resources: ["https://api.gearbox.example.com"],
+};
+
+// Wrap app root
+<LogtoProvider config={config}>
+  <App />
+</LogtoProvider>
+```
+
+### Database -- PostgreSQL via Bun Native Driver
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| PostgreSQL | 16+ | Primary database | Required by Logto anyway, proper concurrent access for multi-user, JSONB for flexible spec fields, full-text search for discovery feed. |
+| drizzle-orm | ^0.45.1 (existing) | Type-safe ORM | Already in use. Switch from `drizzle-orm/bun-sqlite` to `drizzle-orm/bun-sql` for Postgres. Schema definitions move from `sqlite-core` to `pg-core`. |
+| Bun native SQL | built-in | Postgres driver | Zero additional dependencies. `import { SQL } from "bun"` provides native Postgres bindings. Drizzle ORM supports it via `drizzle-orm/bun-sql`. |
+| postgres (postgres.js) | ^3.4.8 | Fallback Postgres driver | Only needed if Bun native SQL has issues with drizzle-kit CLI tooling (known issue #4122). More mature ecosystem, proven with Drizzle. Install as dev dependency for drizzle-kit. |
+
+**Schema migration approach:**
+
+1. Rewrite `src/db/schema.ts` imports from `drizzle-orm/sqlite-core` to `drizzle-orm/pg-core`
+2. Replace `sqliteTable` with `pgTable`
+3. Replace `integer().primaryKey({ autoIncrement: true })` with `integer().primaryKey().generatedAlwaysAsIdentity()` for PKs
+4. Replace `integer("created_at", { mode: "timestamp" })` with `timestamp("created_at").defaultNow().notNull()`
+5. Add `userId text("user_id").notNull()` to all user-owned tables (items, threads, setups, categories)
+6. Add `visibility text("visibility").notNull().default("private")` to setups and profiles
+7. Generate fresh Postgres migration with `drizzle-kit generate`
+8. Write a one-time data migration script (SQLite read -> Postgres insert) for existing data
+
+**drizzle.config.ts change:**
+
+```typescript
+// Before
+{ dialect: "sqlite", dbCredentials: { url: "./gearbox.db" } }
+
+// After
+{ dialect: "postgresql", dbCredentials: { url: process.env.DATABASE_URL } }
+```
+
+**Known issue:** drizzle-kit CLI does not use the Bun SQL driver for `push`/`generate` commands (GitHub issue #4122). Workaround: install `postgres` (postgres.js) as a dev dependency for drizzle-kit, while the app runtime uses Bun native SQL.
+
+### Image Storage -- Bun Native S3 + MinIO
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| Bun S3Client | built-in | S3 API client | Zero dependencies, native Bun bindings, extends Blob interface. Supports presigned URLs, streaming uploads. Built-in MinIO compatibility. |
+| MinIO | latest | Self-hosted S3-compatible object storage | Replaces local `./uploads/` directory. Single Go binary, Docker-friendly, S3 API compatible. Handles multi-user image scaling without cloud vendor lock-in. |
+
+**Why Bun native S3 over @aws-sdk/client-s3:**
+
+- Zero additional dependencies (Bun ships with it)
+- Simpler API (extends Blob, web-standard patterns)
+- Native performance bindings
+- Full MinIO compatibility documented by Bun team
+
+**Migration from ./uploads/:**
+
+1. Deploy MinIO container alongside app
+2. Create `gearbox-images` bucket
+3. Write migration script to upload existing files from `./uploads/` to MinIO
+4. Update image service to use S3Client for reads/writes
+5. Serve images via presigned URLs or a proxy route on Hono
+
+**Configuration:**
+
+```typescript
+import { S3Client } from "bun";
+
+const storage = new S3Client({
+  accessKeyId: process.env.S3_ACCESS_KEY!,
+  secretAccessKey: process.env.S3_SECRET_KEY!,
+  bucket: "gearbox-images",
+  endpoint: process.env.S3_ENDPOINT!, // e.g., http://minio:9000
+});
+```
 
 ### Supporting Libraries
 
 | 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. |
+| jose | ^6.2.2 | JWKS-based JWT verification | Every authenticated API request -- validate Logto access tokens on Hono middleware |
+| @logto/react | ^4.0.13 | React auth provider + hooks | Wrap app root, sign-in/sign-out flows, access token retrieval for API calls |
 
-### Development Tools
+### Development / Infrastructure
 
 | 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. |
+| Docker Compose | Local dev environment | Postgres + Logto + MinIO containers. App still runs on bare Bun for HMR. |
+| drizzle-kit | Schema management | Same tool, different dialect config. `bun run db:generate` and `bun run db:push` still work. |
 
 ## Installation
 
 ```bash
-# Initialize project
-bun init
+# New production dependencies
+bun add @logto/react jose
 
-# Core frontend
-bun add react react-dom @tanstack/react-router @tanstack/react-query zustand zod clsx
+# New dev dependencies (for drizzle-kit Postgres support)
+bun add -D postgres
 
-# 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
+# No install needed for:
+# - Bun native S3 (built-in)
+# - Bun native SQL/Postgres (built-in)
+# - drizzle-orm (already installed, just change imports)
 ```
 
-## Architecture Pattern
-
-**Monorepo-lite (single package, split directories):**
-
-```
-/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
-```
-
-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.
-
 ## Alternatives Considered
 
+### Authentication Provider
+
 | 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. |
+| Logto | Authentik | If you need proxy-mode SSO for non-OIDC apps (Portainer, legacy tools) |
+| Logto | Zitadel | If building multi-tenant B2B SaaS with organization-level isolation |
+| Logto | Keycloak | If enterprise LDAP/AD integration is mandatory |
 
-## What NOT to Use
+### Database Driver
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| Bun native SQL (`bun:sql`) | postgres.js | If Bun native SQL has concurrency bugs (known issue in Bun 1.2.0 with concurrent statements) |
+| Bun native SQL (`bun:sql`) | @neondatabase/serverless | If deploying to serverless/edge where persistent connections are not possible |
+
+### Image Storage
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| MinIO (self-hosted) | Cloudflare R2 | If you want zero-ops storage with no egress fees and don't mind cloud dependency |
+| MinIO (self-hosted) | Local filesystem (current) | For development/testing only. Not viable for multi-user at scale. |
+
+## 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 |
+| @aws-sdk/client-s3 | 60+ transitive dependencies, Bun has native S3 support | Bun built-in S3Client |
+| passport.js / express-session | Wrong paradigm -- we want external OIDC, not embedded session auth | Logto + jose JWT validation |
+| next-auth / auth.js | Designed for Next.js, assumes framework integration we don't have | Logto (external provider) |
+| better-auth | Embedded auth library, opposite of external provider model | Logto (external provider) |
+| pg (node-postgres) | Callback-based API, Bun has native Postgres bindings | Bun native SQL or postgres.js |
+| sharp / image processing libs | Premature optimization -- serve originals first, add resizing later if needed | Direct S3 storage of originals |
+| Redis | Not needed at this scale. Postgres handles sessions (via Logto), caching is premature | Postgres for everything |
+| Prisma | Already using Drizzle ORM, no reason to add a second ORM | drizzle-orm (existing) |
+| nanoid / cuid2 | Postgres `gen_random_uuid()` is built-in for public-facing IDs if needed | Postgres native UUID generation |
+| TypeORM / Sequelize | Legacy ORMs with worse TypeScript support than Drizzle | drizzle-orm (existing) |
+
+## Infrastructure Architecture
+
+```
+Docker Compose (dev) / Docker (prod)
++-- gearbox-app        (Bun, port 3000)
++-- gearbox-postgres   (PostgreSQL 16, port 5432)
+|   +-- gearbox DB     (app data)
+|   +-- logto DB       (Logto data, separate database same instance)
++-- gearbox-logto      (Logto OSS, port 3001 app / 3002 admin)
++-- gearbox-minio      (MinIO, port 9000 API / 9001 console)
+```
+
+Logto and the app share a single Postgres instance (different databases). This keeps infrastructure simple -- one Postgres to back up, one to monitor. Logto requires PostgreSQL 14+; using 16 covers both.
 
 ## 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. |
+| Package | Compatible With | Notes |
+|---------|-----------------|-------|
+| drizzle-orm@0.45.x | Bun native SQL | Supported via `drizzle-orm/bun-sql` driver |
+| drizzle-orm@0.45.x | postgres.js@3.4.x | Supported via `drizzle-orm/postgres-js` driver (fallback) |
+| drizzle-kit@0.31.x | PostgreSQL 16 | Generates Postgres-dialect migrations |
+| @logto/react@4.x | React 19 | Uses React context/hooks, compatible |
+| jose@6.x | Bun runtime | Explicitly lists Bun support in docs |
+| Logto OSS v1.36 | PostgreSQL 14+ | Logto requires PG 14 minimum; use PG 16 for both app and Logto |
+| Bun S3Client | MinIO latest | Documented compatibility with endpoint configuration |
 
-## Key Configuration Notes
+## Migration Checklist (SQLite to Postgres)
 
-### 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(),
-});
-```
+1. **Schema rewrite**: `sqlite-core` -> `pg-core` imports, adjust column types
+2. **Driver swap**: `drizzle-orm/bun-sqlite` -> `drizzle-orm/bun-sql`
+3. **Config update**: `drizzle.config.ts` dialect and credentials
+4. **Fresh migrations**: Generate from scratch for Postgres (do not try to convert SQLite migrations)
+5. **Data migration**: One-time script reads SQLite, writes to Postgres
+6. **Test infrastructure**: Update `createTestDb()` helper to use Postgres test database (or pg-mem for in-memory testing)
+7. **CI pipeline**: Add Postgres service container for test runs
+8. **Remove SQLite deps**: Remove `better-sqlite3` from devDependencies after migration confirmed
 
 ## 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)
+- [Logto official docs -- React quickstart](https://docs.logto.io/quick-starts/react) -- SDK setup, LogtoProvider config (HIGH confidence)
+- [Logto API protection -- JWT validation](https://docs.logto.io/api-protection/nodejs/express) -- jose-based middleware pattern (HIGH confidence)
+- [Logto OSS getting started](https://docs.logto.io/logto-oss/get-started-with-oss) -- Docker deployment, Postgres requirements (HIGH confidence)
+- [Logto @logto/react npm](https://www.npmjs.com/package/@logto/react) -- Version 4.0.13 confirmed (HIGH confidence)
+- [Drizzle ORM -- Bun SQL driver](https://orm.drizzle.team/docs/connect-bun-sql) -- Native Postgres via Bun (HIGH confidence)
+- [Drizzle ORM -- PostgreSQL column types](https://orm.drizzle.team/docs/column-types/pg) -- pg-core schema definitions (HIGH confidence)
+- [drizzle-kit Bun SQL issue #4122](https://github.com/drizzle-team/drizzle-orm/issues/4122) -- Known CLI limitation with Bun driver (MEDIUM confidence)
+- [Bun S3 documentation](https://bun.com/docs/runtime/s3) -- Native S3 client, MinIO config (HIGH confidence)
+- [MinIO GitHub](https://github.com/minio/minio) -- S3-compatible self-hosted storage (HIGH confidence)
+- [jose GitHub](https://github.com/panva/jose) -- JWT library v6.2.2, explicit Bun support (HIGH confidence)
+- [Authentik vs Zitadel comparison](https://wz-it.com/en/blog/authentik-vs-zitadel-identity-provider-comparison/) -- Auth provider analysis (MEDIUM confidence)
+- [Keycloak vs Authentik vs Zitadel 2026](https://blog.houseoffoss.com/post/keycloak-vs-authentik-vs-zitadel-2026-which-open-source-login-tool-should-you-use) -- Ecosystem overview (MEDIUM confidence)
+- [postgres.js npm](https://www.npmjs.com/package/postgres) -- Version 3.4.8, fallback driver (HIGH confidence)
 
 ---
-*Stack research for: GearBox -- gear management and purchase planning web app*
-*Researched: 2026-03-14*
+*Stack research for: GearBox v2.0 Platform Foundation*
+*Researched: 2026-04-03*

.planning/research/SUMMARY.md

@@ -1,243 +1,203 @@
 # Project Research Summary
 
-**Project:** GearBox
-**Domain:** Single-user gear management and purchase planning web app
-**Researched:** 2026-03-14
+**Project:** GearBox v2.0 Platform Foundation
+**Domain:** Single-user to multi-user gear management and discovery platform
+**Researched:** 2026-04-03
 **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 v2.0 is a structural migration, not a feature addition. The project transforms a proven single-user gear tracker (React 19 + Hono + Drizzle + SQLite + Bun) into a multi-user platform with a global item database, structured community reviews, and public setup sharing. The research is clear on the sequencing: database migration and multi-user data scoping must come first because every other feature depends on user-owned records and Postgres. Skipping or deferring either creates cascading rework across all downstream features.
 
-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 stack additions are conservative and well-documented: PostgreSQL 16 (required by the auth provider and for concurrent access), Bun's native S3 client against self-hosted MinIO (zero new dependencies), and an external OIDC auth provider replacing the current cookie-session system. The existing stack is validated and stays intact. The largest implementation risk is the SQLite-to-Postgres migration — it is a full schema rewrite, not an automated conversion, and it forces every service function to become async, cascading through 6 service files, 7 route files, and 19 MCP tools.
 
-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.
+**Open decision — auth provider:** STACK.md recommends Logto (TypeScript-native, purpose-built for app auth, React SDK with hooks, requires only Postgres, MIT-licensed). ARCHITECTURE.md recommends Authentik (Python-based, full OIDC/OAuth2, self-hosted, requires Postgres and Redis). Both are valid. Logto integrates at the React layer via `@logto/react` and validates JWTs on the Hono backend via `jose`. Authentik integrates at the server layer via `@hono/oidc-auth` middleware and handles all session state — no React SDK needed. This decision must be resolved before the auth phase begins and affects infrastructure dependencies, React integration complexity, and future capability for proxy-mode SSO. See the Gaps section for resolution criteria.
 
 ## 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 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.
+The existing stack (React 19, Hono, Drizzle ORM, TanStack Router/Query, Tailwind v4, Zustand, Zod, Bun) is unchanged and validated. The following are net-new additions for v2.0.
 
 **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
+- **PostgreSQL 16:** Primary database — replaces SQLite for concurrent multi-user access; required by both auth provider candidates; enables full-text search for the global item catalog
+- **Drizzle ORM pg-core:** Existing ORM, different dialect — switch from `drizzle-orm/bun-sqlite` to `drizzle-orm/bun-sql` (or `postgres-js` as fallback); schema must be rewritten from scratch using `pgTable`, not migrated from `sqliteTable`
+- **Bun native S3Client + MinIO:** Zero-dependency image storage — replaces `./uploads/` local filesystem; Bun ships a native S3 client with documented MinIO compatibility; no `@aws-sdk/client-s3` needed
+- **jose (^6.2.2):** JWT validation — verifies OIDC access tokens on the Hono backend via JWKS; zero dependencies, explicit Bun support; needed regardless of auth provider choice
+- **@logto/react (^4.0.13) OR @hono/oidc-auth:** Auth provider SDK — one of these two depending on the provider decision (see open decision above)
+- **@electric-sql/pglite:** In-process Postgres for tests — replaces `bun:sqlite` in-memory test setup; Drizzle supports it via `drizzle-orm/pglite`; avoids Docker dependency in unit/integration tests
+- **postgres (postgres.js, ^3.4.8):** Dev dependency only — required for `drizzle-kit` CLI (`db:generate`, `db:push`) due to known issue #4122 where drizzle-kit does not support the Bun native SQL driver
 
-**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.
+**Infrastructure additions:** Docker Compose running Postgres + auth provider + MinIO alongside the Bun app. The app itself continues to run on bare Bun for HMR.
 
 ### 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 for v2.0 launch (P1):**
+- External auth provider integration — nothing works without multi-user identity
+- PostgreSQL migration — concurrent access and auth provider dependency
+- Multi-user data model (userId FK on items, categories, threads, setups, settings) — data isolation foundation
+- User profiles (minimal: display name, avatar, bio, public setups list) — required for attribution on shared content
+- Setup visibility controls (public/private toggle, default private) — table stakes for any sharing feature
+- Public setup detail pages — shareable read-only view with item list, totals, creator attribution
+- Global item database with seed data — canonical product catalog enabling reviews and aggregation
+- Link personal items to global items — the bridge enabling owner counts, crowd specs, and weight data
+- Search global items — full-text search powering item linking and discovery browsing
+- Structured reviews (overall + dimension ratings, no freeform text) — community intelligence layer
+- Item detail pages (aggregated specs, owner count, average ratings) — integration hub for all platform data
+- Discovery browse page (recent public setups, recently reviewed items, popular gear) — entry point for community value
 
-**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 after validation (P2):**
+- Crowd-verified specs display (manufacturer vs. community-measured weight, needs 3+ owners per item)
+- Setup composition insights ("commonly paired with" co-occurrence analysis)
+- Planning thread global item integration (candidates auto-populate from global DB)
+- Copy/fork public setups (one-click template from public setups)
+- Popular gear rankings by category (most owned, highest rated)
 
-**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 to v3+:**
+- Freeform reviews with moderation (explicitly deferred until moderation infrastructure exists)
+- Comments on setups (moderation burden)
+- Follow users / activity feed (social-network complexity, against the discovery-first principle)
+- OAuth / social login (after external auth is stable)
 
-**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
+**Anti-features to reject explicitly:** real-time collaborative setups, marketplace/buy-sell, AI gear recommendations, wiki-style open item editing, gamification, Instagram-style infinite scroll feed.
 
 ### 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.
+The v2.0 architecture is a layered structural migration where each layer depends on the one below it: Postgres first (database), then user identity (auth), then data scoping (userId on all entities), then the global item catalog, then community features on top. Every existing service file gains a `userId` parameter and becomes `async` — this is a mechanical but wide-ranging change touching 6 services, 7 routes, 19 MCP tools, and all tests. The component topology stays the same (Hono routes -> services -> Drizzle); only the wiring within each layer 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. **Database layer (Postgres + pg-core)** — Full schema rewrite; all entity tables gain userId FK; new `globalItems` and `reviews` tables; sessions table removed; `categories` unique constraint changes to composite `(userId, name)`
+2. **Auth middleware (OIDC)** — Replaces `requireAuth`; resolves OIDC subject to local userId via `getOrCreateUser`; keeps API key system intact for MCP and programmatic access; sessions table deleted (OIDC handles state via signed JWT cookies)
+3. **User-scoped services** — All existing services gain `userId` parameter and async signature; 4 new services added: `globalItem.service`, `review.service`, `profile.service`, `discover.service`
+4. **Image storage layer (MinIO via Bun S3Client)** — Replaces filesystem writes; abstraction interface allows local dev vs. S3 production swap; existing `/uploads/*` static route replaced by proxy or presigned URL handler
+5. **Global item catalog** — Separate `globalItems` table (not the user `items` table); admin-seeded initially; user items optionally reference global items via nullable `globalItemId` FK; reviews and owner counts attach to global items, not user items
+6. **Public content layer** — Setup `isPublic` flag; public profile pages; discovery queries over public content with indexes on `owner_count`, `(is_public, updated_at)`, and `global_item_id`
 
 ### 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. **Missing userId filters leak data between users** — Any service function not updated to filter by `userId` returns all users' data across 30+ query sites. Prevention: use `userId NOT NULL` in schema so TypeScript compiler errors guide updates; add Postgres Row-Level Security as a safety net; write cross-user isolation tests per entity (create as User A, query as User B, assert empty results).
 
-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. **Drizzle schema rewrite is a replacement, not a migration** — `sqlite-core` and `pg-core` are incompatible; `real()` in Postgres is 4-byte float vs. SQLite's 8-byte (use `doublePrecision()` for weight values); timestamps change from integer epoch to native `timestamp`; all service functions must become async (`.get()` and `.all()` are sync SQLite methods, Postgres uses `await`). Prevention: rewrite schema from scratch, update all `.get()` / `.all()` calls, run full test suite against Postgres.
 
-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. **Test infrastructure collapses during DB switch** — `createTestDb()` uses `bun:sqlite` in-memory SQLite. After the switch, every test needs Postgres. Prevention: adopt PGlite (`@electric-sql/pglite`) for unit/integration tests immediately; never let the SQLite test setup coexist with Postgres production code past the migration sprint.
 
-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. **Auth migration breaks sessions, API keys, and MCP** — Switching to external OIDC touches the login flow, session management, API key ownership, MCP authentication, E2E test setup, and the onboarding flow. Prevention: keep API keys in the local database (do not delegate to the auth provider); maintain a local `users` table with `externalId` (OIDC subject) FK; keep `apiKeys` table with `userId` FK to local users; update E2E tests to authenticate via API keys.
 
-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.
+5. **Global item database creates a data model fork if built wrong** — An `isGlobal` flag or `NULL userId` on the user `items` table makes queries unmaintainable and blurs permission boundaries. Prevention: separate `globalItems` table from day one; user items get a nullable `globalItemId` FK; reviews and owner counts attach to `globalItems` only.
 
-**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
+6. **Existing data has no owner after migration** — Current SQLite data has no `userId`. Adding `userId NOT NULL` breaks migration if existing rows are not assigned an owner first. Prevention: data migration script must create the original user first, assign all existing data to that userId, then enforce NOT NULL — never make `userId` permanently nullable as a migration workaround.
 
 ## 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.
+The dependency chain is strict: Postgres -> Auth -> Multi-user scoping -> Global items -> Community features. Attempting to parallelize across this chain creates rework. Suggested phase structure:
 
-### Phase 1: Foundation — Data Model, Infrastructure, Core Item CRUD
+### Phase 1: Database Migration (SQLite to PostgreSQL)
+**Rationale:** Everything else depends on Postgres. Auth providers require it. Concurrent access requires it. Full-text search for the global item catalog requires it. Must be done first and tested completely before any feature work begins.
+**Delivers:** Postgres running locally and in CI; schema rewritten in pg-core; all service functions async; PGlite test infrastructure replacing `bun:sqlite`; one-time data migration script for existing SQLite data; drizzle.config.ts updated; all PRAGMA statements removed
+**Addresses:** Postgres migration (FEATURES.md P1)
+**Avoids:** Pitfall 3 (schema rewrite), Pitfall 4 (test infrastructure), Pitfall 10 (SQLite-specific patterns), Pitfall 12 (existing data ownership)
+**Research flag:** Well-documented migration pattern. STACK.md and ARCHITECTURE.md agree on the approach. No additional research needed — pitfalls are comprehensively documented with GearBox-specific code references.
 
-**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.
+### Phase 2: Authentication Provider Integration
+**Rationale:** User identity must exist before userId can be added to any table. This phase also resolves the open Logto vs. Authentik decision.
+**Delivers:** External auth provider running in Docker; OIDC middleware on Hono; local `users` table with `externalId` (OIDC subject); API key system preserved and userId-scoped; E2E tests updated to use API key authentication; onboarding flow replaced with auth provider registration; MCP auth updated
+**Uses:** `jose` (JWT validation), `@logto/react` or `@hono/oidc-auth` depending on provider decision, Docker Compose
+**Avoids:** Pitfall 5 (auth breaks sessions/keys/MCP); integration gotcha (keep local users table with externalId, do not remove it)
+**Research flag:** NEEDS RESOLUTION before this phase can be planned — the Logto vs. Authentik decision. See Gaps section for resolution criteria. Once the provider is chosen, integration patterns are well-documented in official docs.
 
-**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.
+### Phase 3: Multi-User Data Model
+**Rationale:** With user identity established, all entity tables can be scoped. This is the highest-risk phase because it touches every query in the codebase and is where data leaks occur if anything is missed.
+**Delivers:** `userId` NOT NULL on items, categories, threads, setups, settings, apiKeys; composite unique on `(userId, name)` for categories; `isPublic` boolean on setups; `resolveThread` propagates userId to newly created items; all service functions filter by userId; cross-user isolation tests passing per entity; Postgres RLS policies active; MCP tools user-scoped; settings migrated to per-user
+**Addresses:** Multi-user data model, setup visibility controls, user profile data model (FEATURES.md P1)
+**Avoids:** Pitfall 1 (missing userId filters), Pitfall 2 (category uniqueness), Pitfall 8 (thread resolution userId), Pitfall 9 (public content defaults to private), Pitfall 11 (setup sync race conditions)
+**Research flag:** No additional research needed — pitfall documentation is comprehensive with specific per-table and per-function guidance for the existing GearBox codebase.
 
-**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.
+### Phase 4: Image Storage Migration (MinIO)
+**Rationale:** Move image storage before public profiles and discovery ship. Once images are served to unauthenticated users at scale, the local filesystem approach fails. Better to resolve this before public content launches.
+**Delivers:** MinIO running in Docker; Bun native S3Client configured; existing `./uploads/` migrated to MinIO bucket; image service updated; proxy route for S3 reads; MCP `upload_image_from_url` tool updated; image storage abstraction (local filesystem for dev, S3 for production)
+**Uses:** Bun native S3Client (built-in, no install), MinIO Docker container
+**Avoids:** Pitfall 7 (image URL breakage after storage migration)
+**Research flag:** Standard pattern. Bun S3Client docs and MinIO compatibility are well-documented. No research needed.
 
-**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).
+### Phase 5: Global Item Database
+**Rationale:** The global item catalog is the second major foundation. Reviews, item detail pages, owner counts, and discovery all depend on canonical product records existing before those features can be built.
+**Delivers:** `globalItems` table in pg-core; admin seeding workflow with 200-500 initial items across core categories; nullable `globalItemId` FK on user items; item linking flow in collection UI; full-text search via Postgres `tsvector`; `GET /api/global-items` endpoints (public, no auth); `globalItem.service.ts`
+**Addresses:** Global item database, link personal items to global items, search global items (FEATURES.md P1)
+**Avoids:** Pitfall 6 (data model fork — separate `globalItems` table, not a flag on user items)
+**Research flag:** May benefit from targeted research on Postgres full-text search (`tsvector`/`tsquery`) configuration — specifically index design and query tuning for the expected catalog size and query patterns (brand + model name search). Schema is specified; FTS tuning is domain-dependent.
 
-**Research flag:** Standard patterns. Schema design for inventory apps is well-documented. No research phase needed.
-
----
-
-### Phase 2: Planning Threads — The Core Differentiator
-
-**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:** 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.
-
-**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.
-
-**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).
-
-**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: Setups — Named Loadouts and Composition
-
-**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.
-
-**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.
-
-**Features from FEATURES.md:** Named setups with item selection and totals, setup weight/cost breakdown by category, automatic totals.
-
-**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).
-
-**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.
-
----
-
-### Phase 4: Dashboard and Polish
-
-**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.
-
-**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.
-
-**Features from FEATURES.md:** Dashboard home page, weight distribution visualization.
-
-**Research flag:** Standard patterns. Dashboard aggregation is a straightforward read-only endpoint. Charting is well-documented. No research phase needed.
-
----
-
-### Phase 5: v1.x Enhancements
-
-**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.
-
-**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.
-
----
+### Phase 6: Community Features (Reviews, Profiles, Discovery)
+**Rationale:** With the global item catalog seeded and users scoped, community features can be built on top. These three feature areas are bundled because they form the public-facing value proposition together — profiles without discovery, or discovery without content, delivers nothing meaningful to users.
+**Delivers:** Structured reviews (overall + dimension ratings, one per user per global item, no freeform text); user public profiles (display name, avatar, bio, joined date, public setups list); public setup detail pages; discovery browse page (recent public setups, recently reviewed items, popular items by owner count); item detail pages with aggregated stats (owner count, average ratings, crowd-verified weight)
+**Addresses:** Structured reviews, user profiles, public setup pages, item detail pages, discovery browse (FEATURES.md P1)
+**Uses:** Review schema with composite unique `(userId, globalItemId)`; denormalized `avgRating` and `ownerCount` on globalItems; cursor-paginated discovery queries; indexes on `(is_public, updated_at)` and `owner_count`
+**Avoids:** Pitfall 9 (private by default enforced in all discovery queries); N+1 query trap in feed (use joins, not per-item queries)
+**Research flag:** Discovery feed pagination (cursor vs. offset) and feed composition are well-documented standard patterns at this scale. No additional research needed for v2.0.
 
 ### 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.
+- Phases 1-3 form an unbreakable dependency chain: each phase is a prerequisite for the next. No parallelization is possible without creating rework.
+- Phase 4 (images) is inserted before community features because public profiles and discovery serve images to unauthenticated users — local filesystem is not viable at that point.
+- Phase 5 (global items) must precede Phase 6 (community features) because reviews require global item records to attach to; the dependency is one-directional.
+- Phases 5 and 6 could be split across releases (global items + linking as v2.0, community features as v2.1) if schedule pressure exists — the global item catalog delivers standalone value through item linking even before reviews exist.
 
 ### 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).
+Needs deeper research during planning:
+- **Phase 2 (Auth):** Auth provider decision (Logto vs. Authentik) must be resolved before this phase is planned. The integration pattern differs significantly between the two options — React SDK + backend JWT validation (Logto) vs. server-side middleware only (Authentik).
+- **Phase 5 (Global Items):** Postgres full-text search index design and query tuning for the global item catalog. The schema is specified; the FTS configuration (`tsvector` column type, GIN index, query parser) needs validation against expected query patterns and initial catalog size.
 
-**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 (Database):** Migration path is thoroughly documented across ARCHITECTURE.md, PITFALLS.md, and STACK.md. Per-file implementation checklist is complete.
+- **Phase 3 (Multi-user):** Per-table userId requirements are fully specified. Pitfall checklist covers all edge cases including MCP tools, thread resolution, settings, and the threadCandidates join path.
+- **Phase 4 (Images):** Bun S3Client + MinIO is documented by the Bun team. Standard proxy-then-presigned-URL migration path is specified.
+- **Phase 6 (Community):** Schema, services, and query patterns are fully specified in ARCHITECTURE.md. No novel patterns.
 
 ## 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 | All recommendations backed by official docs. Known issue #4122 (drizzle-kit + Bun SQL) is documented with a clear workaround. The Logto vs. Authentik disagreement is an open decision requiring resolution, not a confidence gap — both options are well-validated. |
+| Features | HIGH | Competitor analysis is comprehensive (LighterPack, GearGrams, Trailspace, MyGear). Feature dependency chain is fully mapped. P1/P2/P3 prioritization is grounded in implementation cost and dependency analysis. |
+| Architecture | HIGH | Based on direct codebase analysis of GearBox v1.4 plus official Drizzle and Hono docs. Component-level change inventory is complete (new files, modified files, removed files enumerated). Data flow diagrams are concrete and code-level. |
+| Pitfalls | HIGH | 12 pitfalls, each with specific GearBox v1.4 codebase context (file names, function names, column names, specific patterns). Confidence is high because research analyzed the actual codebase, not generic migration advice. |
 
-**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.
+- **Open decision — auth provider (Logto vs. Authentik):** Must be resolved before Phase 2 planning begins. Resolution criteria: (1) If the project plans to use the auth provider for infrastructure SSO beyond the GearBox app (Portainer, Grafana, Gitea, etc.), choose Authentik — it handles proxy-mode SSO that Logto does not. (2) If GearBox is the only app needing auth, choose Logto — simpler infrastructure (no Redis dependency), React SDK eliminates manual OIDC redirect handling, TypeScript-native. STACK.md's Logto recommendation is correct for the app-auth-only use case.
 
-- **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.
+- **Review dimension configuration tension:** FEATURES.md specifies "3-5 dimension ratings per product category, admin-configurable" (flexible `reviewDimensions` table with `categoryId` FK). ARCHITECTURE.md uses hardcoded columns (`weightRating`, `durabilityRating`, `valueRating`). For v2.0, use the hardcoded column approach (simpler, no dimension management UI needed). The flexible schema is a v2.x concern. This must be noted explicitly in Phase 6 planning to prevent scope creep.
 
-- **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.
+- **E2E test authentication strategy post-auth migration:** PITFALLS.md recommends switching E2E tests to API key authentication after auth moves external. The mechanism for creating a test user in the new auth system (direct Postgres insert bypassing the OIDC provider vs. auth provider admin API) needs to be decided during Phase 2 planning.
 
 ## 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
+- GearBox v1.4 codebase — Direct analysis of `src/db/schema.ts`, service files, auth middleware, MCP server, test helpers, `db/index.ts`, E2E seed (direct codebase reference)
+- [Logto official docs — React quickstart](https://docs.logto.io/quick-starts/react) — SDK setup, LogtoProvider config
+- [Logto API protection — JWT validation](https://docs.logto.io/api-protection/nodejs/express) — jose-based middleware pattern
+- [Logto OSS getting started](https://docs.logto.io/logto-oss/get-started-with-oss) — Docker deployment, Postgres requirements
+- [Drizzle ORM — Bun SQL driver](https://orm.drizzle.team/docs/connect-bun-sql) — Native Postgres via Bun
+- [Drizzle ORM — PostgreSQL column types](https://orm.drizzle.team/docs/column-types/pg) — pg-core schema definitions
+- [Bun S3 documentation](https://bun.com/docs/runtime/s3) — Native S3 client, MinIO config
+- [jose GitHub](https://github.com/panva/jose) — JWT library v6.2.2, explicit Bun support
+- [postgres.js npm](https://www.npmjs.com/package/postgres) — v3.4.8, fallback driver
 
 ### 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
+- [drizzle-kit Bun SQL issue #4122](https://github.com/drizzle-team/drizzle-orm/issues/4122) — Known CLI limitation with Bun driver
+- [Authentik vs Zitadel comparison](https://wz-it.com/en/blog/authentik-vs-zitadel-identity-provider-comparison/) — Auth provider tradeoff analysis
+- [Keycloak vs Authentik vs Zitadel 2026](https://blog.houseoffoss.com/post/keycloak-vs-authentik-vs-zitadel-2026-which-open-source-login-tool-should-you-use) — Ecosystem overview
+- [LighterPack](https://lighterpack.com/), [GearGrams](https://www.geargrams.com/), [Trailspace](https://www.trailspace.com/), [MyGear](https://mygear.world/) — Competitor feature analysis
+- [Multi-tenant architecture guide (WorkOS)](https://workos.com/blog/developers-guide-saas-multi-tenant-architecture) — Multi-user data isolation patterns
+- [SQLite to PostgreSQL migration pitfalls (Open WebUI)](https://github.com/open-webui/open-webui/discussions/21609) — Migration risk validation
+- [How to migrate from SQLite to PostgreSQL (Render)](https://render.com/articles/how-to-migrate-from-sqlite-to-postgresql) — Data migration script patterns
 
-### 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)
+- [Drizzle ORM PostgreSQL best practices 2025 (GitHub Gist)](https://gist.github.com/productdevbook/7c9ce3bbeb96b3fabc3c7c2aa2abc717) — Schema patterns (validate against official docs during implementation)
+- [GetStream Social Feed Architecture](https://getstream.io/blog/social-media-feed/) — Feed implementation patterns referenced for anti-patterns to avoid
 
 ---
-*Research completed: 2026-03-14*
+*Research completed: 2026-04-03*
 *Ready for roadmap: yes*

CLAUDE.md

@@ -9,7 +9,8 @@ GearBox is a single-user web app for managing gear collections (bikepacking, sim
 ## Commands
 
 ```bash
-# Development (run both in separate terminals)
+# Development
+bun run dev                 # Starts both Vite client (:5173) and Hono server (:3000) concurrently
 bun run dev:client          # Vite dev server on :5173 (proxies /api to :3000)
 bun run dev:server          # Hono server on :3000 with hot reload
 
@@ -18,8 +19,10 @@ bun run db:generate         # Generate Drizzle migration from schema changes
 bun run db:push             # Apply migrations to gearbox.db
 
 # Testing
-bun test                    # Run all tests
+bun test                    # Run all unit/integration tests
 bun test tests/services/item.service.test.ts  # Run single test file
+bun run test:e2e            # Run Playwright E2E tests
+bun run test:e2e:ui         # Playwright UI mode for debugging
 
 # Lint & Format
 bun run lint                # Biome check (tabs, double quotes, organized imports)
@@ -52,11 +55,32 @@ bun run build               # Vite build → dist/client/
 - **Schema**: `schema.ts` — Drizzle table definitions for SQLite.
 - **Prices stored as cents** (`priceCents: integer`) to avoid float rounding.
 - **Timestamps**: stored as integers (unix epoch) with `{ mode: "timestamp" }`.
-- Tables: `categories`, `items`, `threads`, `threadCandidates`, `setups`, `setupItems`, `settings`.
+- Tables: `categories`, `items`, `threads`, `threadCandidates`, `setups`, `setupItems`, `settings`, `users`, `sessions`, `apiKeys`.
 
-### Testing (`tests/`)
-- Bun test runner. Tests at service level and route level.
-- `tests/helpers/db.ts`: `createTestDb()` creates in-memory SQLite with full schema and seeds an "Uncategorized" category. When adding schema columns, update both `src/db/schema.ts` and the test helper's CREATE TABLE statements.
+### Testing (`tests/` and `e2e/`)
+- **Unit/integration**: Bun test runner (`bun test`). Tests at service level and route level.
+- `tests/helpers/db.ts`: `createTestDb()` creates in-memory SQLite via Drizzle migrations and seeds an "Uncategorized" category.
+- **E2E**: Playwright (`bun run test:e2e`). Tests in `e2e/` run against a seeded SQLite database with the server in production mode. Seed script: `e2e/seed.ts`.
+
+## Releasing
+
+Releases are managed by a Gitea Actions workflow (`.gitea/workflows/release.yml`). **Never create tags or releases manually** — always trigger the pipeline.
+
+The workflow runs CI (lint, test, build), computes the next version from the latest tag, generates a changelog, creates the tag, builds and pushes a Docker image, and creates a Gitea release.
+
+Trigger via Gitea API:
+```bash
+curl -s -X POST "https://gitea.jeanlucmakiola.de/api/v1/repos/makiolaj/GearBox/actions/workflows/release.yml/dispatches" \
+  -H "Authorization: token <GITEA_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"ref": "Develop", "inputs": {"bump": "patch"}}'  # patch | minor | major
+```
+
+## Branching
+
+- **Develop** is the main branch. Keep it clean — don't commit large feature work directly.
+- For each new brainstorming/implementation session, create a feature branch off Develop (e.g., `feature/setup-impact-preview`, `fix/error-handling`).
+- Merge back to Develop via PR or fast-forward merge when the work is complete and verified.
 
 ## Path Alias
 
@@ -67,4 +91,100 @@ bun run build               # Vite build → dist/client/
 - **Thread resolution**: Resolving a thread copies the winning candidate's data into a new item in the collection, sets `resolvedCandidateId`, and changes status to "resolved".
 - **Setup item sync**: `PUT /api/setups/:id/items` replaces all setup_items atomically (delete all, re-insert).
 - **Image uploads**: `POST /api/images` saves to `./uploads/` with UUID filename, returned as `imageFilename` on item/candidate records.
+- **Image URL fetching**: `POST /api/images/from-url` fetches an image from a URL, saves locally, returns `{ filename, sourceUrl }`.
 - **Aggregates** (weight/cost totals): Computed via SQL on read, not stored on records.
+- **Authentication**: Public-read, authenticated-write. Cookie sessions for web UI, API keys (`X-API-Key` header) for programmatic access. `POST /api/auth/setup` for first-time account creation. Auth middleware protects all POST/PUT/DELETE on `/api/*` except `/api/auth/*`.
+
+## Authentication
+
+- **First run**: No users exist. Visit `/login` to create your admin account.
+- **Web UI**: Cookie-based sessions (`gearbox_session`), 30-day expiry, auto-refreshed.
+- **Programmatic access**: API keys created in Settings > API Keys. Pass via `X-API-Key` header.
+- **Public read**: All GET endpoints work without auth. POST/PUT/DELETE require auth.
+- **Auth routes**: `/api/auth/login`, `/api/auth/logout`, `/api/auth/setup`, `/api/auth/me`, `/api/auth/password`, `/api/auth/keys`.
+- **MCP OAuth**: OAuth 2.1 + PKCE for Claude mobile/web. Endpoints at `/oauth/*`. Uses existing GearBox credentials.
+
+## MCP Server
+
+GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`. Authenticated via API key or OAuth 2.1 Bearer token.
+
+### Tools (19 total)
+
+| Tool | Description |
+|------|-------------|
+| `list_items` | List all items, optionally filter by category |
+| `get_item` | Get item details by ID |
+| `create_item` | Add item to collection (for decided items; use `create_thread` for research) |
+| `update_item` | Update item details |
+| `delete_item` | Remove item from collection |
+| `list_categories` | List all categories |
+| `create_category` | Create a new category |
+| `list_threads` | List research threads (recommended workflow for gear purchases) |
+| `get_thread` | Get thread with candidates |
+| `create_thread` | Start a research thread to compare gear options |
+| `resolve_thread` | Pick winning candidate, adds it to collection |
+| `add_candidate` | Add candidate to a research thread |
+| `update_candidate` | Update candidate details |
+| `remove_candidate` | Remove candidate from thread |
+| `list_setups` | List gear setups |
+| `get_setup` | Get setup with items and totals |
+| `create_setup` | Create a new setup |
+| `update_setup` | Update setup name or items |
+| `upload_image_from_url` | Fetch image from URL, save locally |
+
+### Resources
+
+- `gearbox://collection/summary` — Overview of collection: totals, items per category, active threads.
+
+### Configuration
+
+**Claude Code** (`.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "streamable-http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "streamable-http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+Generate an API key from Settings > API Keys after logging in.
+
+### OAuth Authentication (Claude Mobile / claude.ai)
+
+GearBox supports OAuth 2.1 Authorization Code + PKCE for MCP connections from Claude mobile app and claude.ai. The OAuth flow is automatic — Claude handles discovery and token exchange.
+
+**Required environment variable for production:**
+```bash
+GEARBOX_URL=https://your-gearbox-domain.com  # Used as OAuth issuer URL
+```
+
+**OAuth endpoints:**
+- `GET /.well-known/oauth-authorization-server` — Discovery metadata
+- `POST /oauth/register` — Dynamic Client Registration
+- `GET/POST /oauth/authorize` — Authorization with login form
+- `POST /oauth/token` — Token exchange and refresh
+
+**Both auth methods work simultaneously:**
+- **API key** (`X-API-Key` header) — Claude Code, scripts, programmatic access
+- **OAuth Bearer token** (`Authorization: Bearer` header) — Claude mobile, claude.ai

README.md

@@ -1,2 +1,122 @@
 # 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)
+
+### 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.
+
+## Tech Stack
+
+- **Runtime & Package Manager:** [Bun](https://bun.sh)
+- **Frontend:** React 19, Vite, TanStack Router, TanStack Query, Tailwind CSS v4, Zustand
+- **Backend:** Hono, Drizzle ORM, SQLite (`bun:sqlite`)
+
+## Local Development Setup
+
+### Prerequisites
+
+You must have [Bun](https://bun.sh/) installed on your machine. Docker is not required for local development.
+
+### Installation
+
+1. Install all dependencies:
+   ```bash
+   bun install
+   ```
+
+2. Initialize the local SQLite database (`gearbox.db`):
+   ```bash
+   bun run db:push
+   ```
+
+3. Start the development servers:
+   ```bash
+   bun run dev
+   ```
+   This single command will start both the Vite frontend server (port `5173`) and the Hono backend server (port `3000`) concurrently. 
+
+Open [http://localhost:5173](http://localhost:5173) in your browser to view the app.
+
+## Additional Commands
+
+- `bun run build` — Build the production assets into `dist/client/`
+- `bun test` — Run the test suite
+- `bun run lint` — Check formatting and lint rules using Biome
+- `bun run db:generate` — Generate Drizzle migrations after making schema changes

biome.json

@@ -7,7 +7,7 @@
 	},
 	"files": {
 		"ignoreUnknown": false,
-		"includes": ["**", "!src/client/routeTree.gen.ts"]
+		"includes": ["**", "!src/client/routeTree.gen.ts", "!drizzle", "!.planning"]
 	},
 	"formatter": {
 		"enabled": true,

bun.lock

@@ -6,21 +6,25 @@
       "name": "gearbox",
       "dependencies": {
         "@hono/zod-validator": "^0.7.6",
+        "@modelcontextprotocol/sdk": "^1.29.0",
         "@tailwindcss/vite": "^4.2.1",
         "@tanstack/react-query": "^5.90.21",
         "@tanstack/react-router": "^1.167.0",
         "clsx": "^2.1.1",
         "drizzle-orm": "^0.45.1",
+        "framer-motion": "^12.38.0",
         "hono": "^4.12.8",
         "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",
       },
       "devDependencies": {
         "@biomejs/biome": "^2.4.7",
+        "@playwright/test": "^1.59.1",
         "@tanstack/react-query-devtools": "^5.91.3",
         "@tanstack/react-router-devtools": "^1.166.7",
         "@tanstack/router-plugin": "^1.166.9",
@@ -30,6 +34,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.1",
         "better-sqlite3": "^12.8.0",
+        "concurrently": "^9.1.2",
         "drizzle-kit": "^0.31.9",
         "vite": "^8.0.0",
       },
@@ -159,6 +164,8 @@
 
     "@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.12", "", { "os": "win32", "cpu": "x64" }, "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA=="],
 
+    "@hono/node-server": ["@hono/node-server@1.19.12", "", { "peerDependencies": { "hono": "^4" } }, "sha512-txsUW4SQ1iilgE0l9/e9VQWmELXifEFvmdA1j6WFh/aFPj99hIntrSsq/if0UWyGVkmrRPKA1wCeP+UCr1B9Uw=="],
+
     "@hono/zod-validator": ["@hono/zod-validator@0.7.6", "", { "peerDependencies": { "hono": ">=3.9.0", "zod": "^3.25.0 || ^4.0.0" } }, "sha512-Io1B6d011Gj1KknV4rXYz4le5+5EubcWEU/speUjuw9XMMIaP3n78yXLhjd2A3PXaXaUwEAluOiAyLqhBEJgsw=="],
 
     "@jridgewell/gen-mapping": ["@jridgewell/gen-mapping@0.3.13", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA=="],
@@ -171,12 +178,18 @@
 
     "@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
 
+    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],
+
     "@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.1", "", { "dependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1", "@tybys/wasm-util": "^0.10.1" } }, "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A=="],
 
     "@oxc-project/runtime": ["@oxc-project/runtime@0.115.0", "", {}, "sha512-Rg8Wlt5dCbXhQnsXPrkOjL1DTSvXLgb2R/KYfnf1/K+R0k6UMLEmbQXPM+kwrWqSmWA2t0B1EtHy2/3zikQpvQ=="],
 
     "@oxc-project/types": ["@oxc-project/types@0.115.0", "", {}, "sha512-4n91DKnebUS4yjUHl2g3/b2T+IUdCfmoZGhmwsovZCDaJSs+QkVAM+0AqqTxHSsHfeiMuueT75cZaZcT/m0pSw=="],
 
+    "@playwright/test": ["@playwright/test@1.59.1", "", { "dependencies": { "playwright": "1.59.1" }, "bin": { "playwright": "cli.js" } }, "sha512-PG6q63nQg5c9rIi4/Z5lR5IVF7yU5MqmKaPOe0HSc0O2cX1fPi96sUQu5j7eo4gKCkB2AnNGoWt7y4/Xx3Kcqg=="],
+
+    "@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 +222,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,16 +292,46 @@
 
     "@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=="],
 
+    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
+
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
+    "ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
+
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
+
     "ansis": ["ansis@4.2.0", "", {}, "sha512-HqZ5rWlFjGiV0tDm3UxxgNRqsOTniqoKZu0pIAfh7TZQMGuZK+hH0drySty0si0QXj1ieop4+SkSfPZBPPkHig=="],
 
     "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="],
@@ -305,6 +352,8 @@
 
     "bl": ["bl@4.1.0", "", { "dependencies": { "buffer": "^5.5.0", "inherits": "^2.0.4", "readable-stream": "^3.4.0" } }, "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w=="],
 
+    "body-parser": ["body-parser@2.2.2", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.1", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA=="],
+
     "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
 
     "browserslist": ["browserslist@4.28.1", "", { "dependencies": { "baseline-browser-mapping": "^2.9.0", "caniuse-lite": "^1.0.30001759", "electron-to-chromium": "^1.5.263", "node-releases": "^2.0.27", "update-browserslist-db": "^1.2.0" }, "bin": { "browserslist": "cli.js" } }, "sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA=="],
@@ -315,26 +364,80 @@
 
     "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
 
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
+
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
+
     "caniuse-lite": ["caniuse-lite@1.0.30001778", "", {}, "sha512-PN7uxFL+ExFJO61aVmP1aIEG4i9whQd4eoSCebav62UwDyp5OHh06zN4jqKSMePVgxHifCw1QJxdRkA1Pisekg=="],
 
+    "chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="],
+
     "chokidar": ["chokidar@3.6.0", "", { "dependencies": { "anymatch": "~3.1.2", "braces": "~3.0.2", "glob-parent": "~5.1.2", "is-binary-path": "~2.1.0", "is-glob": "~4.0.1", "normalize-path": "~3.0.0", "readdirp": "~3.6.0" }, "optionalDependencies": { "fsevents": "~2.3.2" } }, "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw=="],
 
     "chownr": ["chownr@1.1.4", "", {}, "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg=="],
 
+    "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+
     "clsx": ["clsx@2.1.1", "", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
 
+    "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
+
+    "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
+
+    "concurrently": ["concurrently@9.2.1", "", { "dependencies": { "chalk": "4.1.2", "rxjs": "7.8.2", "shell-quote": "1.8.3", "supports-color": "8.1.1", "tree-kill": "1.2.2", "yargs": "17.7.2" }, "bin": { "conc": "dist/bin/concurrently.js", "concurrently": "dist/bin/concurrently.js" } }, "sha512-fsfrO0MxV64Znoy8/l1vVIjjHa29SZyyqPgQBwhiDcaW8wJc2W3XWVOGx4M3oJBnv/zdUZIIp1gDeS98GzP8Ng=="],
+
+    "content-disposition": ["content-disposition@1.0.1", "", {}, "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q=="],
+
+    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+
     "convert-source-map": ["convert-source-map@2.0.0", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
 
+    "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
     "cookie-es": ["cookie-es@2.0.0", "", {}, "sha512-RAj4E421UYRgqokKUmotqAwuplYw15qtdXfY+hGzgCJ/MBjCVZcSoHK/kH9kocfjRjcDME7IiDWR/1WX1TM2Pg=="],
 
+    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+
+    "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
     "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=="],
 
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
     "diff": ["diff@8.0.3", "", {}, "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ=="],
@@ -343,34 +446,84 @@
 
     "drizzle-orm": ["drizzle-orm@0.45.1", "", { "peerDependencies": { "@aws-sdk/client-rds-data": ">=3", "@cloudflare/workers-types": ">=4", "@electric-sql/pglite": ">=0.2.0", "@libsql/client": ">=0.10.0", "@libsql/client-wasm": ">=0.10.0", "@neondatabase/serverless": ">=0.10.0", "@op-engineering/op-sqlite": ">=2", "@opentelemetry/api": "^1.4.1", "@planetscale/database": ">=1.13", "@prisma/client": "*", "@tidbcloud/serverless": "*", "@types/better-sqlite3": "*", "@types/pg": "*", "@types/sql.js": "*", "@upstash/redis": ">=1.34.7", "@vercel/postgres": ">=0.8.0", "@xata.io/client": "*", "better-sqlite3": ">=7", "bun-types": "*", "expo-sqlite": ">=14.0.0", "gel": ">=2", "knex": "*", "kysely": "*", "mysql2": ">=2", "pg": ">=8", "postgres": ">=3", "sql.js": ">=1", "sqlite3": ">=5" }, "optionalPeers": ["@aws-sdk/client-rds-data", "@cloudflare/workers-types", "@electric-sql/pglite", "@libsql/client", "@libsql/client-wasm", "@neondatabase/serverless", "@op-engineering/op-sqlite", "@opentelemetry/api", "@planetscale/database", "@prisma/client", "@tidbcloud/serverless", "@types/better-sqlite3", "@types/pg", "@types/sql.js", "@upstash/redis", "@vercel/postgres", "@xata.io/client", "better-sqlite3", "bun-types", "expo-sqlite", "gel", "knex", "kysely", "mysql2", "pg", "postgres", "sql.js", "sqlite3"] }, "sha512-Te0FOdKIistGNPMq2jscdqngBRfBpC8uMFVwqjf6gtTVJHIQ/dosgV/CLBU2N4ZJBsXL5savCba9b0YJskKdcA=="],
 
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
+
     "electron-to-chromium": ["electron-to-chromium@1.5.313", "", {}, "sha512-QBMrTWEf00GXZmJyx2lbYD45jpI3TUFnNIzJ5BBc8piGUDwMPa1GV6HJWTZVvY/eiN3fSopl7NRbgGp9sZ9LTA=="],
 
+    "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
+
     "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
 
     "enhanced-resolve": ["enhanced-resolve@5.20.0", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ=="],
 
+    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
+
+    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
+
+    "es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
+
+    "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=="],
 
     "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
 
+    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
+
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
 
+    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
+
+    "eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
+
+    "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
+
+    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
     "expand-template": ["expand-template@2.0.3", "", {}, "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg=="],
 
+    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
+
+    "express-rate-limit": ["express-rate-limit@8.3.2", "", { "dependencies": { "ip-address": "10.1.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
+
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
     "file-uri-to-path": ["file-uri-to-path@1.0.0", "", {}, "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw=="],
 
     "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
 
+    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
+
+    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
+
+    "framer-motion": ["framer-motion@12.38.0", "", { "dependencies": { "motion-dom": "^12.38.0", "motion-utils": "^12.36.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-rFYkY/pigbcswl1XQSb7q424kSTQ8q6eAC+YUsSKooHQYuLdzdHjrt6uxUC+PRAO++q5IS7+TamgIw1AphxR+g=="],
+
+    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
+
     "fs-constants": ["fs-constants@1.0.0", "", {}, "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow=="],
 
     "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
 
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
     "gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
 
+    "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
+
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
     "get-tsconfig": ["get-tsconfig@4.13.6", "", { "dependencies": { "resolve-pkg-maps": "^1.0.0" } }, "sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw=="],
 
     "github-from-package": ["github-from-package@0.0.0", "", {}, "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw=="],
@@ -379,32 +532,64 @@
 
     "goober": ["goober@2.1.18", "", { "peerDependencies": { "csstype": "^3.0.10" } }, "sha512-2vFqsaDVIT9Gz7N6kAL++pLpp41l3PfDuusHcjnGLfR6+huZkl6ziX+zgVC3ZxpqWhzH6pyDdGrCeDhMIvwaxw=="],
 
+    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
+
     "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
 
+    "has-flag": ["has-flag@4.0.0", "", {}, "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ=="],
+
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
     "hono": ["hono@4.12.8", "", {}, "sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A=="],
 
+    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
+
+    "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
+
     "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=="],
+
+    "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
+
+    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
+
     "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=="],
 
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
     "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
 
     "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
 
+    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
+
     "isbot": ["isbot@5.1.36", "", {}, "sha512-C/ZtXyJqDPZ7G7JPr06ApWyYoHjYexQbS6hPYD4WYCzpv2Qes6Z+CCEfTX4Owzf+1EJ933PoI2p+B9v7wpGZBQ=="],
 
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
+    "jose": ["jose@6.2.2", "", {}, "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ=="],
+
     "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
 
     "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
 
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
+
     "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
 
     "lightningcss": ["lightningcss@1.32.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.32.0", "lightningcss-darwin-arm64": "1.32.0", "lightningcss-darwin-x64": "1.32.0", "lightningcss-freebsd-x64": "1.32.0", "lightningcss-linux-arm-gnueabihf": "1.32.0", "lightningcss-linux-arm64-gnu": "1.32.0", "lightningcss-linux-arm64-musl": "1.32.0", "lightningcss-linux-x64-gnu": "1.32.0", "lightningcss-linux-x64-musl": "1.32.0", "lightningcss-win32-arm64-msvc": "1.32.0", "lightningcss-win32-x64-msvc": "1.32.0" } }, "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ=="],
@@ -437,66 +622,150 @@
 
     "magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ=="],
 
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
+    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
+
+    "mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
+    "mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
     "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="],
 
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
     "mkdirp-classic": ["mkdirp-classic@0.5.3", "", {}, "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A=="],
 
+    "motion-dom": ["motion-dom@12.38.0", "", { "dependencies": { "motion-utils": "^12.36.0" } }, "sha512-pdkHLD8QYRp8VfiNLb8xIBJis1byQ9gPT3Jnh2jqfFtAsWUA3dEepDlsWe/xMpO8McV+VdpKVcp+E+TGJEtOoA=="],
+
+    "motion-utils": ["motion-utils@12.36.0", "", {}, "sha512-eHWisygbiwVvf6PZ1vhaHCLamvkSbPIeAYxWUuL3a2PD/TROgE7FvfHWTIH4vMl798QLfMw15nRqIaRDXTlYRg=="],
+
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
     "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
 
     "napi-build-utils": ["napi-build-utils@2.0.0", "", {}, "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA=="],
 
+    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
+
     "node-abi": ["node-abi@3.88.0", "", { "dependencies": { "semver": "^7.3.5" } }, "sha512-At6b4UqIEVudaqPsXjmUO1r/N5BUr4yhDGs5PkBE8/oG5+TfLPhFechiskFsnT6Ql0VfUXbalUUCbfXxtj7K+w=="],
 
     "node-releases": ["node-releases@2.0.36", "", {}, "sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA=="],
 
     "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
 
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+
+    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
+
     "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
 
+    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
+
     "pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
 
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
+
+    "playwright": ["playwright@1.59.1", "", { "dependencies": { "playwright-core": "1.59.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw=="],
+
+    "playwright-core": ["playwright-core@1.59.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg=="],
+
     "postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
 
     "prebuild-install": ["prebuild-install@7.1.3", "", { "dependencies": { "detect-libc": "^2.0.0", "expand-template": "^2.0.3", "github-from-package": "0.0.0", "minimist": "^1.2.3", "mkdirp-classic": "^0.5.3", "napi-build-utils": "^2.0.0", "node-abi": "^3.3.0", "pump": "^3.0.0", "rc": "^1.2.7", "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" }, "bin": { "prebuild-install": "bin.js" } }, "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug=="],
 
     "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
 
+    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
+
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
 
+    "qs": ["qs@6.15.0", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ=="],
+
+    "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
+
+    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
+
     "rc": ["rc@1.2.8", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="],
 
     "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
 
     "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=="],
+
+    "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "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=="],
 
+    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
+
+    "rxjs": ["rxjs@7.8.2", "", { "dependencies": { "tslib": "^2.1.0" } }, "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA=="],
+
     "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
 
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
 
     "semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
 
+    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
+
     "seroval": ["seroval@1.5.1", "", {}, "sha512-OwrZRZAfhHww0WEnKHDY8OM0U/Qs8OTfIDWhUD4BLpNJUfXK4cGmjiagGze086m+mhI+V2nD0gfbHEnJjb9STA=="],
 
     "seroval-plugins": ["seroval-plugins@1.5.1", "", { "peerDependencies": { "seroval": "^1.0" } }, "sha512-4FbuZ/TMl02sqv0RTFexu0SP6V+ywaIe5bAWCCEik0fk17BhALgwvUDVF7e3Uvf9pxmwCEJsRPmlkUE6HdzLAw=="],
 
+    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
+
+    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "shell-quote": ["shell-quote@1.8.3", "", {}, "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw=="],
+
+    "side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
+
+    "side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
+
+    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
+
+    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
+
     "simple-concat": ["simple-concat@1.0.1", "", {}, "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q=="],
 
     "simple-get": ["simple-get@4.0.1", "", { "dependencies": { "decompress-response": "^6.0.0", "once": "^1.3.1", "simple-concat": "^1.0.0" } }, "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA=="],
@@ -507,10 +776,18 @@
 
     "source-map-support": ["source-map-support@0.5.21", "", { "dependencies": { "buffer-from": "^1.0.0", "source-map": "^0.6.0" } }, "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w=="],
 
+    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
+
+    "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
     "string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
 
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
     "strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
 
+    "supports-color": ["supports-color@8.1.1", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q=="],
+
     "tailwindcss": ["tailwindcss@4.2.1", "", {}, "sha512-/tBrSQ36vCleJkAOsy9kbNTgaxvGbyOamC30PRePTQe/o1MFwEKHQk4Cn7BNGaPtjp+PuUrByJehM1hgxfq4sw=="],
 
     "tapable": ["tapable@2.3.0", "", {}, "sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg=="],
@@ -527,16 +804,24 @@
 
     "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
 
+    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
+
+    "tree-kill": ["tree-kill@1.2.2", "", { "bin": { "tree-kill": "cli.js" } }, "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A=="],
+
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "tsx": ["tsx@4.21.0", "", { "dependencies": { "esbuild": "~0.27.0", "get-tsconfig": "^4.7.5" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": { "tsx": "dist/cli.mjs" } }, "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw=="],
 
     "tunnel-agent": ["tunnel-agent@0.6.0", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w=="],
 
+    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
+    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
+
     "unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
 
     "update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
@@ -545,20 +830,38 @@
 
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
+    "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=="],
 
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
+
     "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
 
+    "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
+
     "yallist": ["yallist@3.1.1", "", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
 
+    "yargs": ["yargs@17.7.2", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
+
+    "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+
     "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
 
+    "zod-to-json-schema": ["zod-to-json-schema@3.25.2", "", { "peerDependencies": { "zod": "^3.25.28 || ^4" } }, "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA=="],
+
     "zustand": ["zustand@5.0.11", "", { "peerDependencies": { "@types/react": ">=18.0.0", "immer": ">=9.0.6", "react": ">=18.0.0", "use-sync-external-store": ">=1.2.0" }, "optionalPeers": ["@types/react", "immer", "react", "use-sync-external-store"] }, "sha512-fdZY+dk7zn/vbWNCYmzZULHRrss0jx5pPFiOuMZ/5HJN6Yv3u+1Wswy/4MpZEkEGhtNH+pwxZB8OKgUBPzYAGg=="],
 
     "@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=="],
@@ -579,8 +882,12 @@
 
     "anymatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
+    "chalk/supports-color": ["supports-color@7.2.0", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw=="],
+
     "node-abi/semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
 
+    "playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "readdirp/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
     "recast/source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],

bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "tests/"

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:

docs/api.md

@@ -0,0 +1,642 @@
+# API Reference
+
+Base URL: `http://localhost:3000`
+
+**Auth:** GET endpoints are public. POST, PUT, PATCH, and DELETE require authentication via session cookie or `X-API-Key` header. See [authentication.md](authentication.md) for details.
+
+**Prices** are stored and returned in cents (e.g., `2500` = $25.00).  
+**Weights** are in grams.  
+**Timestamps** are unix epoch integers.
+
+---
+
+## Table of Contents
+
+- [Health](#health)
+- [Items](#items)
+- [Categories](#categories)
+- [Threads](#threads)
+- [Setups](#setups)
+- [Images](#images)
+- [Settings](#settings)
+- [Totals](#totals)
+- [Auth](#auth)
+
+---
+
+## Health
+
+### `GET /api/health`
+
+Returns server status. Always public.
+
+**Response:**
+```json
+{ "status": "ok" }
+```
+
+---
+
+## Items
+
+### `GET /api/items`
+
+List all items in the collection.
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "name": "Revelate Tangle Frame Bag",
+    "categoryId": 2,
+    "weightGrams": 185,
+    "priceCents": 12000,
+    "notes": "Medium size, fits 2020 Surly Straggler",
+    "productUrl": "https://revelatedesigns.com/...",
+    "imageFilename": "1710000000000-uuid.jpg",
+    "imageSourceUrl": "https://example.com/image.jpg",
+    "createdAt": 1710000000,
+    "updatedAt": 1710000000
+  }
+]
+```
+
+---
+
+### `GET /api/items/:id`
+
+Get a single item by ID.
+
+**Response:** item object (see above), or `404 { "error": "Item not found" }`.
+
+---
+
+### `POST /api/items`
+
+Create a new item. Auth required.
+
+**Request:**
+```json
+{
+  "name": "Revelate Tangle Frame Bag",
+  "categoryId": 2,
+  "weightGrams": 185,
+  "priceCents": 12000,
+  "notes": "Medium size",
+  "productUrl": "https://revelatedesigns.com/...",
+  "imageFilename": "1710000000000-uuid.jpg",
+  "imageSourceUrl": "https://example.com/image.jpg"
+}
+```
+
+| Field           | Type    | Required | Description                          |
+|-----------------|---------|----------|--------------------------------------|
+| `name`          | string  | yes      | Item name                            |
+| `categoryId`    | integer | yes      | ID of an existing category           |
+| `weightGrams`   | number  | no       | Weight in grams (non-negative)       |
+| `priceCents`    | integer | no       | Price in cents (non-negative)        |
+| `notes`         | string  | no       | Free-text notes                      |
+| `productUrl`    | string  | no       | URL to product page                  |
+| `imageFilename` | string  | no       | Filename from a prior image upload   |
+| `imageSourceUrl`| string  | no       | Original URL the image came from     |
+
+**Response:** `201` — created item object.
+
+---
+
+### `PUT /api/items/:id`
+
+Update an existing item. All fields are optional. Auth required.
+
+**Request:** same fields as POST, all optional.
+
+**Response:** updated item object, or `404`.
+
+---
+
+### `DELETE /api/items/:id`
+
+Delete an item and clean up its image file if one exists. Auth required.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+Returns `404` if item not found.
+
+---
+
+## Categories
+
+### `GET /api/categories`
+
+List all categories.
+
+**Response:**
+```json
+[
+  { "id": 1, "name": "Uncategorized", "icon": "package" },
+  { "id": 2, "name": "Bags", "icon": "backpack" }
+]
+```
+
+---
+
+### `POST /api/categories`
+
+Create a new category. Auth required.
+
+**Request:**
+```json
+{ "name": "Bags", "icon": "backpack" }
+```
+
+| Field  | Type   | Required | Description                          |
+|--------|--------|----------|--------------------------------------|
+| `name` | string | yes      | Category name                        |
+| `icon` | string | no       | Icon name (defaults to `"package"`)  |
+
+**Response:** `201` — created category object.
+
+---
+
+### `PUT /api/categories/:id`
+
+Update a category. Auth required.
+
+**Request:**
+```json
+{ "name": "Carry", "icon": "bag" }
+```
+
+**Response:** updated category object, or `404`.
+
+---
+
+### `DELETE /api/categories/:id`
+
+Delete a category. Auth required.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+## Threads
+
+Research threads track multiple candidate options for a single gear slot before committing to a purchase.
+
+### `GET /api/threads`
+
+List threads. By default only active (unresolved) threads are returned.
+
+**Query parameters:**
+
+| Parameter         | Type    | Default | Description                        |
+|-------------------|---------|---------|------------------------------------|
+| `includeResolved` | boolean | `false` | Set to `true` to include resolved threads |
+
+**Example:** `GET /api/threads?includeResolved=true`
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "name": "Handlebar bag",
+    "categoryId": 2,
+    "status": "active",
+    "resolvedCandidateId": null,
+    "createdAt": 1710000000,
+    "updatedAt": 1710000000
+  }
+]
+```
+
+---
+
+### `POST /api/threads`
+
+Create a new research thread. Auth required.
+
+**Request:**
+```json
+{ "name": "Handlebar bag", "categoryId": 2 }
+```
+
+**Response:** `201` — created thread object.
+
+---
+
+### `GET /api/threads/:id`
+
+Get a thread with all its candidates.
+
+**Response:**
+```json
+{
+  "id": 1,
+  "name": "Handlebar bag",
+  "categoryId": 2,
+  "status": "active",
+  "resolvedCandidateId": null,
+  "candidates": [
+    {
+      "id": 10,
+      "threadId": 1,
+      "name": "Revelate Sweetroll",
+      "categoryId": 2,
+      "weightGrams": 290,
+      "priceCents": 13500,
+      "notes": "16L, fits most drop bars",
+      "productUrl": "https://revelatedesigns.com/...",
+      "imageFilename": null,
+      "imageSourceUrl": null,
+      "status": "researching",
+      "pros": "Waterproof, large capacity",
+      "cons": "Pricey",
+      "sortOrder": 0,
+      "createdAt": 1710000000,
+      "updatedAt": 1710000000
+    }
+  ]
+}
+```
+
+Returns `404` if thread not found.
+
+---
+
+### `PUT /api/threads/:id`
+
+Update a thread's name or category. Auth required.
+
+**Request:**
+```json
+{ "name": "Bar bag", "categoryId": 2 }
+```
+
+**Response:** updated thread object, or `404`.
+
+---
+
+### `DELETE /api/threads/:id`
+
+Delete a thread and all its candidates. Cleans up any candidate image files. Auth required.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+### `POST /api/threads/:id/candidates`
+
+Add a candidate to a thread. Auth required.
+
+**Request:**
+```json
+{
+  "name": "Revelate Sweetroll",
+  "categoryId": 2,
+  "weightGrams": 290,
+  "priceCents": 13500,
+  "notes": "16L capacity",
+  "productUrl": "https://revelatedesigns.com/...",
+  "imageFilename": "1710000000000-uuid.jpg",
+  "imageSourceUrl": "https://example.com/image.jpg",
+  "status": "researching",
+  "pros": "Waterproof, large capacity",
+  "cons": "Expensive"
+}
+```
+
+| Field           | Type    | Required | Description                                        |
+|-----------------|---------|----------|----------------------------------------------------|
+| `name`          | string  | yes      | Candidate name                                     |
+| `categoryId`    | integer | yes      | Category ID                                        |
+| `weightGrams`   | number  | no       | Weight in grams                                    |
+| `priceCents`    | integer | no       | Price in cents                                     |
+| `notes`         | string  | no       | Notes                                              |
+| `productUrl`    | string  | no       | Product URL                                        |
+| `imageFilename` | string  | no       | Filename from a prior image upload                 |
+| `imageSourceUrl`| string  | no       | Original image URL                                 |
+| `status`        | string  | no       | `"researching"`, `"ordered"`, or `"arrived"`       |
+| `pros`          | string  | no       | Pros of this option                                |
+| `cons`          | string  | no       | Cons of this option                                |
+
+**Response:** `201` — created candidate object. Returns `404` if thread not found.
+
+---
+
+### `PUT /api/threads/:threadId/candidates/:candidateId`
+
+Update a candidate. All fields optional. Auth required.
+
+**Request:** same fields as POST, all optional.
+
+**Response:** updated candidate object, or `404`.
+
+---
+
+### `DELETE /api/threads/:threadId/candidates/:candidateId`
+
+Delete a candidate and clean up its image. Auth required.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+### `PATCH /api/threads/:id/candidates/reorder`
+
+Reorder candidates within a thread. Auth required.
+
+**Request:**
+```json
+{ "orderedIds": [12, 10, 11] }
+```
+
+`orderedIds` is an array of candidate IDs in the desired display order. All IDs must belong to the thread.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+Returns `400` with an error message if validation fails.
+
+---
+
+### `POST /api/threads/:id/resolve`
+
+Resolve a thread by selecting the winning candidate. Auth required.
+
+The winning candidate's data is copied into a new item in the collection. The thread status is set to `"resolved"` and `resolvedCandidateId` is set.
+
+**Request:**
+```json
+{ "candidateId": 10 }
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "item": {
+    "id": 42,
+    "name": "Revelate Sweetroll",
+    "categoryId": 2,
+    "weightGrams": 290,
+    "priceCents": 13500
+  }
+}
+```
+
+Returns `400` if the candidate does not belong to the thread or another error occurs.
+
+---
+
+## Setups
+
+Setups are named collections of items (e.g., "Bikepacking weekend", "Commute loadout").
+
+### `GET /api/setups`
+
+List all setups with item counts and weight/cost totals.
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "name": "Bikepacking weekend",
+    "itemCount": 12,
+    "totalWeightGrams": 4800,
+    "totalPriceCents": 285000,
+    "createdAt": 1710000000,
+    "updatedAt": 1710000000
+  }
+]
+```
+
+---
+
+### `POST /api/setups`
+
+Create a new setup. Auth required.
+
+**Request:**
+```json
+{ "name": "Bikepacking weekend" }
+```
+
+**Response:** `201` — created setup object.
+
+---
+
+### `GET /api/setups/:id`
+
+Get a setup with its full item list.
+
+**Response:**
+```json
+{
+  "id": 1,
+  "name": "Bikepacking weekend",
+  "items": [
+    {
+      "id": 1,
+      "name": "Revelate Tangle Frame Bag",
+      "weightGrams": 185,
+      "priceCents": 12000,
+      "categoryId": 2,
+      "classification": "base"
+    }
+  ],
+  "totalWeightGrams": 185,
+  "totalPriceCents": 12000
+}
+```
+
+Returns `404` if setup not found.
+
+---
+
+### `PUT /api/setups/:id`
+
+Update a setup's name. Auth required.
+
+**Request:**
+```json
+{ "name": "Bikepacking overnighter" }
+```
+
+**Response:** updated setup object, or `404`.
+
+---
+
+### `PUT /api/setups/:id/items`
+
+Replace all items in a setup atomically. Deletes all existing setup-item associations and re-inserts with the provided IDs. Auth required.
+
+**Request:**
+```json
+{ "itemIds": [1, 5, 12, 17] }
+```
+
+Pass an empty array to remove all items from the setup.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+### `DELETE /api/setups/:id`
+
+Delete a setup. Does not delete the items themselves. Auth required.
+
+**Response:**
+```json
+{ "success": true }
+```
+
+---
+
+## Images
+
+### `POST /api/images`
+
+Upload an image file. Auth required.
+
+**Request:** `multipart/form-data` with an `image` field.
+
+```
+POST /api/images
+Content-Type: multipart/form-data; boundary=...
+
+--boundary
+Content-Disposition: form-data; name="image"; filename="bag.jpg"
+Content-Type: image/jpeg
+
+<binary data>
+--boundary--
+```
+
+Constraints:
+- Accepted types: `image/jpeg`, `image/png`, `image/webp`
+- Maximum size: 5MB
+- Files are saved to `./uploads/` with a UUID-based filename
+
+**Response:** `201`
+```json
+{ "filename": "1710000000000-550e8400-e29b-41d4-a716-446655440000.jpg" }
+```
+
+Use the returned `filename` as `imageFilename` when creating or updating items or candidates.
+
+---
+
+### `POST /api/images/from-url`
+
+Fetch an image from a remote URL and save it locally. Auth required.
+
+**Request:**
+```json
+{ "url": "https://example.com/product-image.jpg" }
+```
+
+**Response:** `201`
+```json
+{
+  "filename": "1710000000000-uuid.jpg",
+  "sourceUrl": "https://example.com/product-image.jpg"
+}
+```
+
+Returns `400` for invalid URLs, unsupported content types, files over 5MB, or non-200 HTTP responses.
+
+---
+
+## Settings
+
+Key-value store for application settings.
+
+### `GET /api/settings/:key`
+
+Get a setting by key. Public.
+
+**Response:**
+```json
+{ "key": "collectionName", "value": "My Bikepacking Gear" }
+```
+
+Returns `404` if the key does not exist.
+
+---
+
+### `PUT /api/settings/:key`
+
+Create or update a setting. Auth required.
+
+**Request:**
+```json
+{ "value": "My Bikepacking Gear" }
+```
+
+**Response:** updated setting object.
+
+---
+
+## Totals
+
+### `GET /api/totals`
+
+Global and per-category weight and cost totals. Computed from current item data. Public.
+
+**Response:**
+```json
+{
+  "global": {
+    "totalWeightGrams": 12500,
+    "totalPriceCents": 450000,
+    "itemCount": 34
+  },
+  "categories": [
+    {
+      "categoryId": 2,
+      "name": "Bags",
+      "icon": "backpack",
+      "totalWeightGrams": 1200,
+      "totalPriceCents": 78000,
+      "itemCount": 5
+    }
+  ]
+}
+```
+
+---
+
+## Auth
+
+Authentication endpoints are documented in [authentication.md](authentication.md).
+
+| Method | Path                    | Auth     | Description               |
+|--------|-------------------------|----------|---------------------------|
+| GET    | `/api/auth/me`          | public   | Current session state     |
+| POST   | `/api/auth/setup`       | public   | Create first admin user   |
+| POST   | `/api/auth/login`       | public   | Log in, receive cookie    |
+| POST   | `/api/auth/logout`      | public   | Clear session             |
+| PUT    | `/api/auth/password`    | session  | Change password           |
+| GET    | `/api/auth/keys`        | required | List API keys             |
+| POST   | `/api/auth/keys`        | required | Create API key            |
+| DELETE | `/api/auth/keys/:id`    | required | Revoke API key            |

docs/authentication.md

@@ -0,0 +1,281 @@
+# Authentication
+
+GearBox uses a public-read, authenticated-write model. All GET endpoints are publicly accessible with no credentials required. Any request that modifies data (POST, PUT, PATCH, DELETE) requires authentication.
+
+This is a single-user app. There is exactly one admin account.
+
+## Table of Contents
+
+- [First-Time Setup](#first-time-setup)
+- [Web UI Authentication](#web-ui-authentication)
+- [API Keys](#api-keys)
+- [Auth Middleware Behavior](#auth-middleware-behavior)
+- [Auth API Reference](#auth-api-reference)
+- [Frontend Behavior](#frontend-behavior)
+
+---
+
+## First-Time Setup
+
+When no users exist, all write endpoints return `403` with `{ "error": "setup_required" }`. To create the admin account, visit `/login` in the browser and complete the setup form, or call the setup endpoint directly:
+
+```http
+POST /api/auth/setup
+Content-Type: application/json
+
+{
+  "username": "admin",
+  "password": "yourpassword"
+}
+```
+
+Requirements:
+- `username`: any non-empty string
+- `password`: minimum 6 characters
+
+This endpoint only works when no users exist. Subsequent calls return `403 { "error": "Setup already completed" }`.
+
+On success, a session cookie is set and `201` is returned:
+
+```json
+{ "username": "admin" }
+```
+
+---
+
+## Web UI Authentication
+
+Sessions use an `httpOnly` cookie named `gearbox_session`.
+
+| Property   | Value              |
+|------------|--------------------|
+| Cookie name | `gearbox_session` |
+| httpOnly   | true               |
+| sameSite   | Lax                |
+| path       | /                  |
+| Max age    | 30 days            |
+
+The session expiry is **automatically refreshed** on each authenticated request. As long as the app is used at least once every 30 days, the session stays active.
+
+Passwords are hashed with **argon2** via `Bun.password`.
+
+### Changing Your Password
+
+Requires an active session cookie.
+
+```http
+PUT /api/auth/password
+Content-Type: application/json
+
+{
+  "currentPassword": "oldpassword",
+  "newPassword": "newpassword"
+}
+```
+
+---
+
+## API Keys
+
+API keys are intended for programmatic access (scripts, MCP clients, integrations). They are managed under **Settings > API Keys** in the web UI, or via the API endpoints listed below.
+
+### Key behavior
+
+- Keys are shown **once** at creation time. Store them securely.
+- Keys are stored as an argon2 hash. Only the 8-character prefix is stored in plaintext for display and lookup purposes.
+- Pass the key via the `X-API-Key` request header on any write request.
+
+```http
+POST /api/items
+X-API-Key: gbk_a1b2c3d4...
+Content-Type: application/json
+
+{ "name": "Revelate Tangle", "categoryId": 2 }
+```
+
+If both a session cookie and an `X-API-Key` header are present, the API key is checked first.
+
+---
+
+## Auth Middleware Behavior
+
+The middleware applied to `/api/*` (excluding `/api/auth/*`) follows these rules:
+
+1. `GET` requests — always allowed, no auth check.
+2. No users exist — returns `403 { "error": "setup_required" }`.
+3. `X-API-Key` header present — verified against stored hashes; `401` on failure.
+4. `gearbox_session` cookie present — verified against sessions table; refreshed on success; `401` on failure.
+5. Neither credential present — returns `401 { "error": "Authentication required" }`.
+
+The `/api/auth/*` routes handle their own auth logic and are excluded from the global middleware.
+
+---
+
+## Auth API Reference
+
+### `GET /api/auth/me`
+
+Returns the current session state. Always public.
+
+**Response when logged in:**
+```json
+{
+  "user": { "id": 1 },
+  "setupRequired": false
+}
+```
+
+**Response when logged out, setup complete:**
+```json
+{
+  "user": null,
+  "setupRequired": false
+}
+```
+
+**Response when no users exist:**
+```json
+{
+  "user": null,
+  "setupRequired": true
+}
+```
+
+---
+
+### `POST /api/auth/setup`
+
+Create the first admin account. Only works when no users exist.
+
+**Request:**
+```json
+{
+  "username": "admin",
+  "password": "yourpassword"
+}
+```
+
+**Response:** `201`
+```json
+{ "username": "admin" }
+```
+
+Sets `gearbox_session` cookie.
+
+---
+
+### `POST /api/auth/login`
+
+Log in with username and password.
+
+**Request:**
+```json
+{
+  "username": "admin",
+  "password": "yourpassword"
+}
+```
+
+**Response:** `200`
+```json
+{ "username": "admin" }
+```
+
+Sets `gearbox_session` cookie. Returns `401` on invalid credentials.
+
+---
+
+### `POST /api/auth/logout`
+
+Clear the current session. No request body needed.
+
+**Response:**
+```json
+{ "ok": true }
+```
+
+Clears the `gearbox_session` cookie and deletes the session from the database.
+
+---
+
+### `PUT /api/auth/password`
+
+Change the admin password. Requires an active session cookie (not API key).
+
+**Request:**
+```json
+{
+  "currentPassword": "oldpassword",
+  "newPassword": "newpassword"
+}
+```
+
+**Response:**
+```json
+{ "ok": true }
+```
+
+Returns `401` if `currentPassword` is incorrect.
+
+---
+
+### `GET /api/auth/keys`
+
+List all API keys. Returns name, prefix, and creation timestamp — never the full key.
+
+Requires auth.
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "name": "Claude Code",
+    "prefix": "gbk_a1b2",
+    "createdAt": "2025-03-01T10:00:00.000Z"
+  }
+]
+```
+
+---
+
+### `POST /api/auth/keys`
+
+Create a new API key. The full key is returned **once** and cannot be retrieved again.
+
+Requires auth.
+
+**Request:**
+```json
+{ "name": "Claude Code" }
+```
+
+**Response:** `201`
+```json
+{
+  "id": 1,
+  "name": "Claude Code",
+  "key": "gbk_a1b2c3d4e5f6g7h8i9j0...",
+  "prefix": "gbk_a1b2"
+}
+```
+
+---
+
+### `DELETE /api/auth/keys/:id`
+
+Revoke an API key by ID. Requires auth.
+
+**Response:**
+```json
+{ "ok": true }
+```
+
+---
+
+## Frontend Behavior
+
+- A login button is shown in the top-right corner of the UI (Gitea-style).
+- The floating action button (FAB) for adding items is hidden when not logged in.
+- Edit and delete actions on items, threads, and setups require auth. Unauthenticated users see read-only views.
+- When `setupRequired` is true, the UI redirects to the setup flow.

docs/mcp-server.md

@@ -0,0 +1,253 @@
+# MCP Server
+
+GearBox includes a built-in MCP (Model Context Protocol) server that exposes your gear collection to AI assistants. It runs inside the Hono process — no separate service is needed.
+
+The MCP server implements the [Streamable HTTP transport](https://modelcontextprotocol.io/specification) from `@modelcontextprotocol/sdk` and is mounted at `/mcp`.
+
+---
+
+## Table of Contents
+
+- [Enabling and Disabling](#enabling-and-disabling)
+- [Authentication](#authentication)
+- [Connecting an AI Client](#connecting-an-ai-client)
+  - [Claude Code](#claude-code)
+  - [Claude Desktop](#claude-desktop)
+- [Tools](#tools)
+- [Resources](#resources)
+- [Recommended Workflow](#recommended-workflow)
+- [Example Session](#example-session)
+- [Implementation Structure](#implementation-structure)
+
+---
+
+## Enabling and Disabling
+
+The MCP server is **enabled by default**. To disable it, set the environment variable:
+
+```bash
+GEARBOX_MCP=false bun run dev:server
+```
+
+Or in your environment file:
+
+```bash
+GEARBOX_MCP=false
+```
+
+When disabled, the `/mcp` route is not registered and any requests to it return 404.
+
+---
+
+## Authentication
+
+The MCP server requires an API key when the app has been set up (i.e., at least one user exists). Pass the key via the `X-API-Key` header in your MCP client configuration.
+
+To create an API key:
+1. Log in to the web UI.
+2. Go to **Settings > API Keys**.
+3. Click **New Key**, give it a name, and copy the full key shown.
+
+The full key is only shown once. Store it in your client configuration immediately.
+
+See [authentication.md](authentication.md) for full API key documentation.
+
+---
+
+## Connecting an AI Client
+
+### Claude Code
+
+Add the MCP server to `.claude/settings.json` in your project or globally at `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "streamable-http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add the server to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "streamable-http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+On macOS, the config file is at `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+After updating the config, restart Claude Desktop (or reload the window in Claude Code) for the server to connect.
+
+---
+
+## Tools
+
+The MCP server exposes 18 tools across five categories.
+
+### Items
+
+| Tool           | Description                                                                                                |
+|----------------|------------------------------------------------------------------------------------------------------------|
+| `list_items`   | List all items in the gear collection, optionally filtered by `categoryId`.                               |
+| `get_item`     | Get a single item by ID with all details.                                                                  |
+| `create_item`  | Add a new item directly to the collection. Use for items already decided on; use `create_thread` for research. |
+| `update_item`  | Update an existing item's fields.                                                                          |
+| `delete_item`  | Delete an item from the collection by ID.                                                                  |
+
+### Categories
+
+| Tool              | Description                          |
+|-------------------|--------------------------------------|
+| `list_categories` | List all gear categories.            |
+| `create_category` | Create a new gear category.          |
+
+### Threads
+
+| Tool             | Description                                                                                          |
+|------------------|------------------------------------------------------------------------------------------------------|
+| `list_threads`   | List research threads. Pass `includeResolved: true` to include resolved threads.                    |
+| `get_thread`     | Get a thread with all its candidates for detailed comparison.                                        |
+| `create_thread`  | Start a new research thread for a gear slot. Preferred entry point for gear research.               |
+| `resolve_thread` | Resolve a thread by picking the winning candidate. Automatically creates a new item in the collection. |
+
+### Candidates
+
+| Tool               | Description                                                           |
+|--------------------|-----------------------------------------------------------------------|
+| `add_candidate`    | Add a candidate option to a research thread for comparison.          |
+| `update_candidate` | Update a candidate's details (name, price, pros, cons, status, etc.).|
+| `remove_candidate` | Remove a candidate from a research thread.                           |
+
+### Setups
+
+| Tool            | Description                                                                                           |
+|-----------------|-------------------------------------------------------------------------------------------------------|
+| `list_setups`   | List all gear setups with item counts and weight/cost totals.                                        |
+| `get_setup`     | Get a setup with all its items and details.                                                          |
+| `create_setup`  | Create a new gear setup (e.g., "Bikepacking weekend").                                              |
+| `update_setup`  | Update a setup's name and/or replace its item list by passing `itemIds`.                            |
+
+### Images
+
+| Tool                    | Description                                                                                      |
+|-------------------------|--------------------------------------------------------------------------------------------------|
+| `upload_image_from_url` | Fetch an image from a URL and save it locally. Returns a `filename` to use with items or candidates. |
+
+---
+
+## Resources
+
+### `gearbox://collection/summary`
+
+Returns a JSON overview of the entire gear collection, including:
+- Total item count, weight, and cost
+- Per-category breakdowns
+- Active research thread count
+
+Read this resource first to orient yourself before running queries or making changes.
+
+---
+
+## Recommended Workflow
+
+Tool descriptions are written to guide AI assistants toward the research thread workflow rather than creating items directly. The intended flow for evaluating a new piece of gear is:
+
+1. **`create_thread`** — open a research thread for the gear slot (e.g., "Handlebar bag")
+2. **`add_candidate`** — add options with prices, weights, pros, and cons
+3. **`get_thread`** — review all candidates side by side
+4. **`resolve_thread`** — pick the winner; it becomes a new item in the collection automatically
+
+Use `create_item` directly only when you already know exactly what you're adding and no research is needed.
+
+---
+
+## Example Session
+
+The following illustrates a typical assistant interaction via the MCP server.
+
+**User:** "I need a new handlebar bag. Can you research some options and add them?"
+
+**Assistant actions:**
+
+```
+1. list_categories
+   -> finds "Bags" category (id: 2)
+
+2. create_thread { name: "Handlebar bag", categoryId: 2 }
+   -> thread id: 7
+
+3. upload_image_from_url { url: "https://revelatedesigns.com/sweetroll.jpg" }
+   -> filename: "1710000000000-uuid.jpg"
+
+4. add_candidate {
+     threadId: 7,
+     name: "Revelate Sweetroll",
+     categoryId: 2,
+     weightGrams: 290,
+     priceCents: 13500,
+     productUrl: "https://revelatedesigns.com/...",
+     imageFilename: "1710000000000-uuid.jpg",
+     pros: "Waterproof, 16L, fits most drop bars",
+     cons: "Expensive, bulky profile"
+   }
+
+5. add_candidate {
+     threadId: 7,
+     name: "Apidura Backcountry Handlebar Pack",
+     categoryId: 2,
+     weightGrams: 230,
+     priceCents: 11000,
+     pros: "Lighter, packable, good attachment system",
+     cons: "Smaller capacity"
+   }
+
+6. add_candidate { ... }
+
+7. get_thread { id: 7 }
+   -> presents comparison to user
+
+8. resolve_thread { threadId: 7, candidateId: 14 }
+   -> Revelate Sweetroll added to collection as item id: 42
+```
+
+---
+
+## Implementation Structure
+
+The MCP server source lives under `src/server/mcp/`:
+
+```
+src/server/mcp/
+  index.ts              # Server factory, transport handling, auth middleware, Hono route registration
+  tools/
+    items.ts            # list_items, get_item, create_item, update_item, delete_item
+    categories.ts       # list_categories, create_category
+    threads.ts          # list_threads, get_thread, create_thread, resolve_thread,
+                        # add_candidate, update_candidate, remove_candidate
+    setups.ts           # list_setups, get_setup, create_setup, update_setup
+    images.ts           # upload_image_from_url
+  resources/
+    collection.ts       # gearbox://collection/summary resource handler
+```
+
+Each tool file exports a `*ToolDefinitions` array (name, description, inputSchema) and a `register*Tools(db)` factory function that returns handler implementations. The server in `index.ts` iterates over definitions and registers each handler with the MCP `McpServer` instance.
+
+Session management uses the `WebStandardStreamableHTTPServerTransport` with UUID-based session IDs tracked in an in-memory `Map`. Sessions are cleaned up when the transport closes.

docs/superpowers/plans/2026-04-03-codebase-improvements.md

@@ -0,0 +1,661 @@
+# Codebase Improvements Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harden the server (explicit DB context, param validation, error handling, rate limiting), add client error boundaries, split the oversized collection route into focused components, and fix stale docs.
+
+**Architecture:** Server changes are middleware-level (DB context, error handler, rate limiter) plus a small utility for param parsing. Client changes are a TanStack Router error boundary on the root route and extracting three tab components from the 634-line collection route. Docs change is a one-line fix in PROJECT.md.
+
+**Tech Stack:** Hono middleware, TanStack Router errorComponent, React, TypeScript
+
+---
+
+### Task 1: Explicit DB Context Middleware
+
+**Files:**
+- Modify: `src/server/index.ts:1-59`
+- Modify: `src/server/routes/settings.ts:3,12` (remove prodDb fallback)
+
+- [ ] **Step 1: Add DB import and middleware to server index**
+
+In `src/server/index.ts`, add the import for the production database at the top, alongside existing imports:
+
+```ts
+import { db as prodDb } from "../db/index.ts";
+```
+
+Then add a middleware **before** the auth middleware (before line 26) that sets the DB on every API request:
+
+```ts
+// Inject production database into request context
+app.use("/api/*", async (c, next) => {
+	c.set("db", prodDb);
+	return next();
+});
+```
+
+- [ ] **Step 2: Fix auth middleware comment**
+
+In the same file, update the comment on the auth middleware from:
+
+```ts
+// Auth middleware for write operations (POST/PUT/DELETE) on non-auth routes
+```
+
+to:
+
+```ts
+// Auth middleware for write operations (POST/PUT/PATCH/DELETE) on non-auth routes
+```
+
+- [ ] **Step 3: Remove prodDb fallback from settings route**
+
+In `src/server/routes/settings.ts`, remove the `prodDb` import and fallback. Change:
+
+```ts
+import { db as prodDb } from "../../db/index.ts";
+```
+
+Remove this import entirely.
+
+Change both occurrences of:
+```ts
+const database = c.get("db") ?? prodDb;
+```
+to:
+```ts
+const database = c.get("db");
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass. Tests already set `c.set("db", testDb)` so this change doesn't affect them.
+
+- [ ] **Step 5: Run lint**
+
+Run: `bun run lint`
+Expected: No errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/server/index.ts src/server/routes/settings.ts
+git commit -m "fix: add explicit DB context middleware for all API routes"
+```
+
+---
+
+### Task 2: Route Parameter Validation
+
+**Files:**
+- Create: `src/server/lib/params.ts`
+- Modify: `src/server/routes/items.ts`
+- Modify: `src/server/routes/categories.ts`
+- Modify: `src/server/routes/threads.ts`
+- Modify: `src/server/routes/setups.ts`
+- Modify: `src/server/routes/auth.ts:187-189`
+
+- [ ] **Step 1: Create parseId helper**
+
+Create `src/server/lib/params.ts`:
+
+```ts
+/**
+ * Parse a route parameter as a positive integer ID.
+ * Returns the number if valid, or null if the string is not a positive integer.
+ */
+export function parseId(raw: string): number | null {
+	const id = Number(raw);
+	if (!Number.isInteger(id) || id <= 0) return null;
+	return id;
+}
+```
+
+- [ ] **Step 2: Update items routes**
+
+In `src/server/routes/items.ts`, add the import:
+
+```ts
+import { parseId } from "../lib/params.ts";
+```
+
+Replace all `Number(c.req.param("id"))` patterns. For each route that uses an ID param, add validation. Example for `GET /:id`:
+
+```ts
+app.get("/:id", (c) => {
+	const db = c.get("db");
+	const id = parseId(c.req.param("id"));
+	if (!id) return c.json({ error: "Invalid item ID" }, 400);
+	const item = getItemById(db, id);
+	if (!item) return c.json({ error: "Item not found" }, 404);
+	return c.json(item);
+});
+```
+
+Apply the same pattern to `PUT /:id` and `DELETE /:id`. In each case, add `const id = parseId(...)` + the null check returning 400 right after.
+
+- [ ] **Step 3: Update categories routes**
+
+In `src/server/routes/categories.ts`, add the import:
+
+```ts
+import { parseId } from "../lib/params.ts";
+```
+
+Replace `Number(c.req.param("id"))` with `parseId(c.req.param("id"))` in `PUT /:id` and `DELETE /:id`, adding the null check:
+
+```ts
+const id = parseId(c.req.param("id"));
+if (!id) return c.json({ error: "Invalid category ID" }, 400);
+```
+
+- [ ] **Step 4: Update threads routes**
+
+In `src/server/routes/threads.ts`, add the import:
+
+```ts
+import { parseId } from "../lib/params.ts";
+```
+
+Replace all `Number(c.req.param(...))` calls. There are 8 occurrences across these handlers:
+- `GET /:id` — `const id = parseId(c.req.param("id"))`
+- `PUT /:id` — same
+- `DELETE /:id` — same
+- `POST /:id/candidates` — `const threadId = parseId(c.req.param("id"))`
+- `PUT /:threadId/candidates/:candidateId` — `const candidateId = parseId(c.req.param("candidateId"))`
+- `DELETE /:threadId/candidates/:candidateId` — same
+- `PATCH /:id/candidates/reorder` — `const threadId = parseId(c.req.param("id"))`
+- `POST /:id/resolve` — `const threadId = parseId(c.req.param("id"))`
+
+For each, add the null check returning 400 with a descriptive message like `"Invalid thread ID"` or `"Invalid candidate ID"`.
+
+- [ ] **Step 5: Update setups routes**
+
+In `src/server/routes/setups.ts`, add the import:
+
+```ts
+import { parseId } from "../lib/params.ts";
+```
+
+Replace all `Number(c.req.param(...))` calls. There are 6 occurrences:
+- `GET /:id` — `const id = parseId(c.req.param("id"))`
+- `PUT /:id` — same
+- `DELETE /:id` — same
+- `PUT /:id/items` — same
+- `PATCH /:id/items/:itemId/classification` — both `setupId` and `itemId`
+- `DELETE /:id/items/:itemId` — both `setupId` and `itemId`
+
+For the classification and item removal routes with two params:
+
+```ts
+const setupId = parseId(c.req.param("id"));
+const itemId = parseId(c.req.param("itemId"));
+if (!setupId || !itemId) return c.json({ error: "Invalid ID" }, 400);
+```
+
+- [ ] **Step 6: Update auth routes**
+
+In `src/server/routes/auth.ts`, add the import:
+
+```ts
+import { parseId } from "../lib/params.ts";
+```
+
+Update `DELETE /keys/:id` (line 187-189):
+
+```ts
+app.delete("/keys/:id", requireAuth, (c) => {
+	const db = c.get("db");
+	const id = parseId(c.req.param("id"));
+	if (!id) return c.json({ error: "Invalid key ID" }, 400);
+	deleteApiKey(db, id);
+	return c.json({ ok: true });
+});
+```
+
+- [ ] **Step 7: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass. Existing tests use valid integer IDs so no breakage.
+
+- [ ] **Step 8: Run lint**
+
+Run: `bun run lint`
+Expected: No errors.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/server/lib/params.ts src/server/routes/items.ts src/server/routes/categories.ts src/server/routes/threads.ts src/server/routes/setups.ts src/server/routes/auth.ts
+git commit -m "fix: validate route ID parameters, return 400 for invalid IDs"
+```
+
+---
+
+### Task 3: Centralized Error Handler
+
+**Files:**
+- Modify: `src/server/index.ts`
+
+- [ ] **Step 1: Add onError handler**
+
+In `src/server/index.ts`, add the error handler after the app is created (after `const app = new Hono()`) but before any routes:
+
+```ts
+// Centralized error handler
+app.onError((err, c) => {
+	console.error(`[${c.req.method}] ${c.req.path}:`, err);
+	const message =
+		process.env.NODE_ENV === "production"
+			? "Internal server error"
+			: err.message || "Internal server error";
+	return c.json({ error: message }, 500);
+});
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/server/index.ts
+git commit -m "fix: add centralized error handler for unhandled exceptions"
+```
+
+---
+
+### Task 4: Rate Limiting on Auth Endpoints
+
+**Files:**
+- Create: `src/server/middleware/rateLimit.ts`
+- Modify: `src/server/routes/auth.ts`
+
+- [ ] **Step 1: Create rate limiter middleware**
+
+Create `src/server/middleware/rateLimit.ts`:
+
+```ts
+import type { Context, Next } from "hono";
+
+interface RateLimitEntry {
+	count: number;
+	resetAt: number;
+}
+
+const store = new Map<string, RateLimitEntry>();
+
+const MAX_ATTEMPTS = 5;
+const WINDOW_MS = 15 * 60 * 1000; // 15 minutes
+
+function getClientIp(c: Context): string {
+	return c.req.header("x-forwarded-for")?.split(",")[0]?.trim() || "unknown";
+}
+
+function cleanup() {
+	const now = Date.now();
+	for (const [key, entry] of store) {
+		if (now >= entry.resetAt) {
+			store.delete(key);
+		}
+	}
+}
+
+export async function rateLimit(c: Context, next: Next) {
+	cleanup();
+
+	const ip = getClientIp(c);
+	const key = `${ip}:${c.req.path}`;
+	const now = Date.now();
+
+	const entry = store.get(key);
+
+	if (!entry || now >= entry.resetAt) {
+		store.set(key, { count: 1, resetAt: now + WINDOW_MS });
+		return next();
+	}
+
+	if (entry.count >= MAX_ATTEMPTS) {
+		const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+		c.header("Retry-After", String(retryAfter));
+		return c.json({ error: "Too many attempts. Try again later." }, 429);
+	}
+
+	entry.count++;
+	return next();
+}
+```
+
+- [ ] **Step 2: Apply rate limiter to auth routes**
+
+In `src/server/routes/auth.ts`, add the import:
+
+```ts
+import { rateLimit } from "../middleware/rateLimit.ts";
+```
+
+Update the `POST /setup` handler to include the rate limiter:
+
+```ts
+app.post("/setup", rateLimit, zValidator("json", setupSchema), async (c) => {
+```
+
+Update the `POST /login` handler to include the rate limiter:
+
+```ts
+app.post("/login", rateLimit, zValidator("json", loginSchema), async (c) => {
+```
+
+- [ ] **Step 3: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass. Auth tests make fewer than 5 requests per endpoint so rate limiting won't trigger.
+
+- [ ] **Step 4: Run lint**
+
+Run: `bun run lint`
+Expected: No errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/middleware/rateLimit.ts src/server/routes/auth.ts
+git commit -m "feat: add rate limiting on login and setup endpoints"
+```
+
+---
+
+### Task 5: Client Error Boundary
+
+**Files:**
+- Modify: `src/client/routes/__root.tsx`
+
+- [ ] **Step 1: Add error boundary component and wire it up**
+
+In `src/client/routes/__root.tsx`, add the import for `useRouter` at the top (add to existing import from `@tanstack/react-router`):
+
+```ts
+import {
+	createRootRoute,
+	Outlet,
+	useMatchRoute,
+	useNavigate,
+	useRouter,
+	type ErrorComponentProps,
+} from "@tanstack/react-router";
+```
+
+Add the `errorComponent` to the route definition:
+
+```ts
+export const Route = createRootRoute({
+	component: RootLayout,
+	errorComponent: RootErrorBoundary,
+});
+```
+
+Add the `RootErrorBoundary` function before `RootLayout`:
+
+```tsx
+function RootErrorBoundary({ error, reset }: ErrorComponentProps) {
+	const router = useRouter();
+
+	return (
+		<div className="min-h-screen bg-gray-50 flex items-center justify-center">
+			<div className="max-w-md mx-auto text-center px-4">
+				<div className="w-12 h-12 bg-red-100 rounded-full flex items-center justify-center mx-auto mb-4">
+					<svg
+						className="w-6 h-6 text-red-600"
+						fill="none"
+						stroke="currentColor"
+						viewBox="0 0 24 24"
+					>
+						<path
+							strokeLinecap="round"
+							strokeLinejoin="round"
+							strokeWidth={2}
+							d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z"
+						/>
+					</svg>
+				</div>
+				<h1 className="text-xl font-semibold text-gray-900 mb-2">
+					Something went wrong
+				</h1>
+				<p className="text-sm text-gray-500 mb-6">
+					{error instanceof Error ? error.message : "An unexpected error occurred"}
+				</p>
+				<button
+					type="button"
+					onClick={() => {
+						reset();
+						router.invalidate();
+					}}
+					className="px-5 py-2.5 bg-gray-700 hover:bg-gray-800 text-white text-sm font-medium rounded-lg transition-colors"
+				>
+					Try again
+				</button>
+			</div>
+		</div>
+	);
+}
+```
+
+- [ ] **Step 2: Run lint**
+
+Run: `bun run lint`
+Expected: No errors.
+
+- [ ] **Step 3: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/client/routes/__root.tsx
+git commit -m "feat: add error boundary to root route for crash resilience"
+```
+
+---
+
+### Task 6: Split Collection Route into Tab Components
+
+**Files:**
+- Create: `src/client/components/CollectionView.tsx`
+- Create: `src/client/components/PlanningView.tsx`
+- Create: `src/client/components/SetupsView.tsx`
+- Modify: `src/client/routes/collection/index.tsx`
+
+- [ ] **Step 1: Create CollectionView component**
+
+Create `src/client/components/CollectionView.tsx` with the `CollectionView` function extracted from `collection/index.tsx` (lines 72-334). The component needs these imports:
+
+```tsx
+import { useMemo, useState } from "react";
+import { CategoryFilterDropdown } from "./CategoryFilterDropdown";
+import { CategoryHeader } from "./CategoryHeader";
+import { ItemCard } from "./ItemCard";
+import { useCategories } from "../hooks/useCategories";
+import { useCurrency } from "../hooks/useCurrency";
+import { useItems } from "../hooks/useItems";
+import { useTotals } from "../hooks/useTotals";
+import { useWeightUnit } from "../hooks/useWeightUnit";
+import { formatPrice, formatWeight } from "../lib/formatters";
+import { LucideIcon } from "../lib/iconData";
+import { useUIStore } from "../stores/uiStore";
+
+export function CollectionView() {
+	// ... exact same function body as lines 73-334 of collection/index.tsx
+}
+```
+
+Copy the entire `CollectionView` function body as-is. No logic changes.
+
+- [ ] **Step 2: Create PlanningView component**
+
+Create `src/client/components/PlanningView.tsx` with the `PlanningView` function extracted from `collection/index.tsx` (lines 337-523):
+
+```tsx
+import { useState } from "react";
+import { CategoryFilterDropdown } from "./CategoryFilterDropdown";
+import { CreateThreadModal } from "./CreateThreadModal";
+import { ThreadCard } from "./ThreadCard";
+import { useCategories } from "../hooks/useCategories";
+import { useThreads } from "../hooks/useThreads";
+import { useUIStore } from "../stores/uiStore";
+
+export function PlanningView() {
+	// ... exact same function body as lines 338-523 of collection/index.tsx
+}
+```
+
+Copy the entire `PlanningView` function body as-is. No logic changes.
+
+- [ ] **Step 3: Create SetupsView component**
+
+Create `src/client/components/SetupsView.tsx` with the `SetupsView` function extracted from `collection/index.tsx` (lines 526-633):
+
+```tsx
+import { useState } from "react";
+import { SetupCard } from "./SetupCard";
+import { useCreateSetup, useSetups } from "../hooks/useSetups";
+
+export function SetupsView() {
+	// ... exact same function body as lines 527-633 of collection/index.tsx
+}
+```
+
+Copy the entire `SetupsView` function body as-is. No logic changes.
+
+- [ ] **Step 4: Update collection/index.tsx**
+
+Replace the entire file content. Keep only the route definition, tab switching logic, animation constants, and imports from the new components:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { AnimatePresence, motion } from "framer-motion";
+import { useRef } from "react";
+import { z } from "zod";
+import { CollectionView } from "../../components/CollectionView";
+import { PlanningView } from "../../components/PlanningView";
+import { SetupsView } from "../../components/SetupsView";
+
+const searchSchema = z.object({
+	tab: z.enum(["gear", "planning", "setups"]).catch("gear"),
+});
+
+export const Route = createFileRoute("/collection/")({
+	validateSearch: searchSchema,
+	component: CollectionPage,
+});
+
+const TAB_ORDER = ["gear", "planning", "setups"] as const;
+
+const slideVariants = {
+	enter: (dir: number) => ({ x: `${dir * 15}%`, opacity: 0 }),
+	center: { x: 0, opacity: 1 },
+	exit: (dir: number) => ({ x: `${dir * -15}%`, opacity: 0 }),
+};
+
+function CollectionPage() {
+	const { tab } = Route.useSearch();
+	const prevTab = useRef(tab);
+
+	const direction =
+		TAB_ORDER.indexOf(tab) >= TAB_ORDER.indexOf(prevTab.current) ? 1 : -1;
+	prevTab.current = tab;
+
+	return (
+		<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6 overflow-x-hidden">
+			<AnimatePresence mode="wait" initial={false} custom={direction}>
+				<motion.div
+					key={tab}
+					custom={direction}
+					variants={slideVariants}
+					initial="enter"
+					animate="center"
+					exit="exit"
+					transition={{ duration: 0.12, ease: "easeInOut" }}
+				>
+					{tab === "gear" ? (
+						<CollectionView />
+					) : tab === "planning" ? (
+						<PlanningView />
+					) : (
+						<SetupsView />
+					)}
+				</motion.div>
+			</AnimatePresence>
+		</div>
+	);
+}
+```
+
+- [ ] **Step 5: Run lint**
+
+Run: `bun run lint`
+Expected: No errors. (Biome may flag import organization — fix if needed.)
+
+- [ ] **Step 6: Run tests**
+
+Run: `bun test`
+Expected: All 183 tests pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/client/components/CollectionView.tsx src/client/components/PlanningView.tsx src/client/components/SetupsView.tsx src/client/routes/collection/index.tsx
+git commit -m "refactor: extract tab views from collection route into separate components"
+```
+
+---
+
+### Task 7: Docs Cleanup
+
+**Files:**
+- Modify: `.planning/PROJECT.md:84`
+
+- [ ] **Step 1: Update stale constraint**
+
+In `.planning/PROJECT.md`, change line 84 from:
+
+```
+- **Scope**: No auth, single user for v1
+```
+
+to:
+
+```
+- **Scope**: Single user with cookie/API key auth
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .planning/PROJECT.md
+git commit -m "docs: update PROJECT.md constraints to reflect auth implementation"
+```
+
+---
+
+### Task 8: Final Verification
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `bun test`
+Expected: All 183 tests pass.
+
+- [ ] **Step 2: Run lint**
+
+Run: `bun run lint`
+Expected: No errors.
+
+- [ ] **Step 3: Verify dev server starts**
+
+Run: `bun run dev:server &` then `curl http://localhost:3000/api/health`
+Expected: `{"status":"ok"}`
+Then kill the background server.

docs/superpowers/plans/2026-04-03-image-url-fetching.md

@@ -0,0 +1,404 @@
+# Image URL Fetching Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `POST /api/images/from-url` endpoint that fetches an image from a URL, saves it locally, and returns the filename. Also add `imageSourceUrl` column to items and candidates.
+
+**Architecture:** New image service function handles URL fetching with validation (content-type, size, timeout). New route delegates to service. Schema changes add nullable `imageSourceUrl` to items and threadCandidates tables. Drizzle migration for the new column.
+
+**Tech Stack:** Hono routes, Zod validation, Drizzle ORM, Bun's native fetch, Bun's file I/O
+
+---
+
+## File Structure
+
+| Action | Path | Responsibility |
+|--------|------|----------------|
+| Create | `src/server/services/image.service.ts` | Image fetching logic (fetch URL, validate, save to disk) |
+| Modify | `src/server/routes/images.ts` | Add `POST /from-url` route |
+| Modify | `src/db/schema.ts` | Add `imageSourceUrl` to `items` and `threadCandidates` |
+| Modify | `src/shared/schemas.ts` | Add `imageSourceUrl` to item/candidate Zod schemas |
+| Modify | `src/server/services/item.service.ts` | Pass through `imageSourceUrl` in create/update |
+| Modify | `src/server/services/thread.service.ts` | Pass through `imageSourceUrl` in candidate create/update and thread resolution |
+| Modify | `tests/helpers/db.ts` | Add `image_source_url` column to test CREATE TABLE statements |
+| Create | `tests/services/image.service.test.ts` | Tests for image fetching service |
+| Create | `tests/routes/images.test.ts` | Route-level tests for `/api/images/from-url` |
+
+---
+
+### Task 1: Add `imageSourceUrl` Column to Database Schema
+
+**Files:**
+- Modify: `src/db/schema.ts:12-29` (items table)
+- Modify: `src/db/schema.ts:47-71` (threadCandidates table)
+- Modify: `tests/helpers/db.ts:19-32` (items CREATE TABLE)
+- Modify: `tests/helpers/db.ts:46-64` (thread_candidates CREATE TABLE)
+
+- [ ] **Step 1: Add column to Drizzle items table**
+
+In `src/db/schema.ts`, add after the `imageFilename` line in the `items` table:
+
+```typescript
+imageSourceUrl: text("image_source_url"),
+```
+
+- [ ] **Step 2: Add column to Drizzle threadCandidates table**
+
+In `src/db/schema.ts`, add after the `imageFilename` line in the `threadCandidates` table:
+
+```typescript
+imageSourceUrl: text("image_source_url"),
+```
+
+- [ ] **Step 3: Update test helper — items table**
+
+In `tests/helpers/db.ts`, add to the items CREATE TABLE statement after `image_filename TEXT,`:
+
+```sql
+image_source_url TEXT,
+```
+
+- [ ] **Step 4: Update test helper — thread_candidates table**
+
+In `tests/helpers/db.ts`, add to the thread_candidates CREATE TABLE statement after `image_filename TEXT,`:
+
+```sql
+image_source_url TEXT,
+```
+
+- [ ] **Step 5: Generate Drizzle migration**
+
+Run: `bun run db:generate`
+Expected: A new migration file created in `drizzle/` adding `image_source_url` to both tables.
+
+- [ ] **Step 6: Apply migration**
+
+Run: `bun run db:push`
+Expected: Migration applied successfully.
+
+- [ ] **Step 7: Run existing tests to verify no regressions**
+
+Run: `bun test`
+Expected: All existing tests pass.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/db/schema.ts tests/helpers/db.ts drizzle/
+git commit -m "feat: add imageSourceUrl column to items and threadCandidates"
+```
+
+---
+
+### Task 2: Update Zod Schemas and Service Functions
+
+**Files:**
+- Modify: `src/shared/schemas.ts:1-16` (item schemas)
+- Modify: `src/shared/schemas.ts:47-60` (candidate schemas)
+- Modify: `src/server/services/item.service.ts:50-71` (createItem)
+- Modify: `src/server/services/item.service.ts:73-101` (updateItem)
+
+- [ ] **Step 1: Add imageSourceUrl to createItemSchema**
+
+In `src/shared/schemas.ts`, add after the `imageFilename` line in `createItemSchema`:
+
+```typescript
+imageSourceUrl: z.string().url().optional().or(z.literal("")),
+```
+
+- [ ] **Step 2: Add imageSourceUrl to createCandidateSchema**
+
+In `src/shared/schemas.ts`, add after the `imageFilename` line in `createCandidateSchema`:
+
+```typescript
+imageSourceUrl: z.string().url().optional().or(z.literal("")),
+```
+
+- [ ] **Step 3: Update item service createItem**
+
+In `src/server/services/item.service.ts`, update the `createItem` function's `.values()` to include:
+
+```typescript
+imageSourceUrl: data.imageSourceUrl ?? null,
+```
+
+- [ ] **Step 4: Update item service updateItem**
+
+In `src/server/services/item.service.ts`, add `imageSourceUrl: string` to the `Partial<{...}>` type in `updateItem`.
+
+- [ ] **Step 5: Update item service getAllItems and getItemById**
+
+Add `imageSourceUrl: items.imageSourceUrl` to the `.select()` objects in both `getAllItems` and `getItemById`.
+
+- [ ] **Step 6: Update thread service candidate create/update**
+
+In `src/server/services/thread.service.ts`, find the candidate create and update functions. Add `imageSourceUrl` passthrough in the same pattern as `imageFilename`. Also ensure that when resolving a thread (copying candidate data to a new item), `imageSourceUrl` is copied from the winning candidate.
+
+- [ ] **Step 7: Run tests**
+
+Run: `bun test`
+Expected: All tests pass.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/shared/schemas.ts src/server/services/item.service.ts src/server/services/thread.service.ts
+git commit -m "feat: add imageSourceUrl to Zod schemas and service functions"
+```
+
+---
+
+### Task 3: Create Image Fetching Service
+
+**Files:**
+- Create: `src/server/services/image.service.ts`
+- Create: `tests/services/image.service.test.ts`
+
+- [ ] **Step 1: Write failing test — successful URL fetch**
+
+Create `tests/services/image.service.test.ts`:
+
+```typescript
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fetchImageFromUrl } from "../../src/server/services/image.service";
+
+const TEST_UPLOADS_DIR = "test-uploads";
+
+afterEach(() => {
+  if (existsSync(TEST_UPLOADS_DIR)) {
+    rmSync(TEST_UPLOADS_DIR, { recursive: true });
+  }
+});
+
+describe("fetchImageFromUrl", () => {
+  test("fetches a valid image URL and saves to disk", async () => {
+    // Use a small, reliable test image
+    const url = "https://via.placeholder.com/10x10.png";
+    const result = await fetchImageFromUrl(url, TEST_UPLOADS_DIR);
+
+    expect(result.filename).toMatch(/^\d+-[\w-]+\.png$/);
+    expect(result.sourceUrl).toBe(url);
+    expect(existsSync(join(TEST_UPLOADS_DIR, result.filename))).toBe(true);
+  });
+
+  test("rejects non-image content type", async () => {
+    const url = "https://example.com/";
+    await expect(fetchImageFromUrl(url, TEST_UPLOADS_DIR)).rejects.toThrow(
+      "Invalid content type"
+    );
+  });
+
+  test("rejects invalid URL", async () => {
+    await expect(fetchImageFromUrl("not-a-url", TEST_UPLOADS_DIR)).rejects.toThrow();
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bun test tests/services/image.service.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement image service**
+
+Create `src/server/services/image.service.ts`:
+
+```typescript
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];
+const MAX_SIZE = 5 * 1024 * 1024; // 5MB
+const FETCH_TIMEOUT = 10_000; // 10 seconds
+
+interface FetchImageResult {
+  filename: string;
+  sourceUrl: string;
+}
+
+export async function fetchImageFromUrl(
+  url: string,
+  uploadsDir = "uploads",
+): Promise<FetchImageResult> {
+  // Validate URL format
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    throw new Error("Invalid URL format");
+  }
+
+  if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+    throw new Error("URL must use HTTP or HTTPS");
+  }
+
+  // Fetch with timeout
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+  let response: Response;
+  try {
+    response = await fetch(url, { signal: controller.signal });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new Error("Request timed out");
+    }
+    throw new Error(`Failed to fetch image: ${(err as Error).message}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: Failed to fetch image`);
+  }
+
+  // Validate content type
+  const contentType = response.headers.get("content-type")?.split(";")[0].trim();
+  if (!contentType || !ALLOWED_TYPES.includes(contentType)) {
+    throw new Error(
+      `Invalid content type: ${contentType ?? "unknown"}. Accepted: jpeg, png, webp`,
+    );
+  }
+
+  // Check content length if available
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && Number.parseInt(contentLength, 10) > MAX_SIZE) {
+    throw new Error("File too large. Maximum size is 5MB");
+  }
+
+  // Read body and check actual size
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > MAX_SIZE) {
+    throw new Error("File too large. Maximum size is 5MB");
+  }
+
+  // Determine extension
+  const ext = contentType === "image/jpeg" ? "jpg" : contentType.split("/")[1];
+  const filename = `${Date.now()}-${randomUUID()}.${ext}`;
+
+  // Ensure directory exists and write
+  await mkdir(uploadsDir, { recursive: true });
+  await Bun.write(join(uploadsDir, filename), buffer);
+
+  return { filename, sourceUrl: url };
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `bun test tests/services/image.service.test.ts`
+Expected: All 3 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/services/image.service.ts tests/services/image.service.test.ts
+git commit -m "feat: add image URL fetching service with tests"
+```
+
+---
+
+### Task 4: Add Route for URL Image Fetching
+
+**Files:**
+- Modify: `src/server/routes/images.ts`
+- Create: `tests/routes/images.test.ts`
+
+- [ ] **Step 1: Write failing route test**
+
+Create `tests/routes/images.test.ts`:
+
+```typescript
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { imageRoutes } from "../../src/server/routes/images";
+
+const app = new Hono();
+app.route("/api/images", imageRoutes);
+
+describe("POST /api/images/from-url", () => {
+  test("returns 400 for missing URL", async () => {
+    const res = await app.request("/api/images/from-url", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  test("returns 400 for invalid URL", async () => {
+    const res = await app.request("/api/images/from-url", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: "not-a-url" }),
+    });
+    expect(res.status).toBe(400);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bun test tests/routes/images.test.ts`
+Expected: FAIL — route not found (404).
+
+- [ ] **Step 3: Add the from-url route**
+
+In `src/server/routes/images.ts`, add imports and the new route:
+
+```typescript
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod";
+import { fetchImageFromUrl } from "../services/image.service";
+
+const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];
+const MAX_SIZE = 5 * 1024 * 1024; // 5MB
+
+const app = new Hono();
+
+const fromUrlSchema = z.object({
+  url: z.string().url("Invalid URL"),
+});
+
+app.post("/from-url", zValidator("json", fromUrlSchema), async (c) => {
+  const { url } = c.req.valid("json");
+
+  try {
+    const result = await fetchImageFromUrl(url);
+    return c.json(result, 201);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+});
+
+// Existing file upload route stays below
+app.post("/", async (c) => {
+  // ... existing code unchanged ...
+});
+```
+
+Note: Keep the existing `app.post("/", ...)` handler exactly as-is. Just add the new `/from-url` route above it.
+
+- [ ] **Step 4: Run tests**
+
+Run: `bun test tests/routes/images.test.ts`
+Expected: Both tests pass.
+
+- [ ] **Step 5: Run all tests**
+
+Run: `bun test`
+Expected: All tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/server/routes/images.ts tests/routes/images.test.ts
+git commit -m "feat: add POST /api/images/from-url route"
+```

docs/superpowers/plans/2026-04-03-testing-improvements.md

@@ -0,0 +1,934 @@
+# Testing Improvements Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add unit tests for new server code (parseId, rate limiter, param validation routes), set up Playwright E2E testing with a seeded database, and write E2E tests covering dashboard, collection, threads, auth, and error handling.
+
+**Architecture:** Unit tests use existing Bun test runner + Hono `app.request()` pattern. E2E tests use Playwright against a real server with a pre-seeded SQLite database. A global-setup script creates the test DB using Drizzle migrations + direct inserts before Playwright runs.
+
+**Tech Stack:** Bun test runner, Playwright (Chromium only), Drizzle ORM migrations, Hono
+
+---
+
+### Task 1: Unit Tests for parseId
+
+**Files:**
+- Create: `tests/lib/params.test.ts`
+
+- [ ] **Step 1: Write tests**
+
+Create `tests/lib/params.test.ts`:
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { parseId } from "../../src/server/lib/params";
+
+describe("parseId", () => {
+	it("returns number for valid positive integers", () => {
+		expect(parseId("1")).toBe(1);
+		expect(parseId("42")).toBe(42);
+		expect(parseId("999")).toBe(999);
+	});
+
+	it("returns null for zero", () => {
+		expect(parseId("0")).toBeNull();
+	});
+
+	it("returns null for negative numbers", () => {
+		expect(parseId("-1")).toBeNull();
+		expect(parseId("-100")).toBeNull();
+	});
+
+	it("returns null for decimals", () => {
+		expect(parseId("1.5")).toBeNull();
+		expect(parseId("3.14")).toBeNull();
+	});
+
+	it("returns null for non-numeric strings", () => {
+		expect(parseId("abc")).toBeNull();
+		expect(parseId("")).toBeNull();
+		expect(parseId("hello")).toBeNull();
+		expect(parseId("12abc")).toBeNull();
+	});
+
+	it("returns null for special values", () => {
+		expect(parseId("NaN")).toBeNull();
+		expect(parseId("Infinity")).toBeNull();
+		expect(parseId("-Infinity")).toBeNull();
+	});
+});
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `bun test tests/lib/params.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/lib/params.test.ts
+git commit -m "test: add unit tests for parseId helper"
+```
+
+---
+
+### Task 2: Unit Tests for Rate Limiter
+
+**Files:**
+- Modify: `src/server/middleware/rateLimit.ts` (add test reset function)
+- Create: `tests/middleware/rateLimit.test.ts`
+
+- [ ] **Step 1: Add test reset function to rate limiter**
+
+In `src/server/middleware/rateLimit.ts`, add at the end of the file:
+
+```ts
+/** @internal — only for testing */
+export function _resetForTesting() {
+	store.clear();
+}
+```
+
+- [ ] **Step 2: Write tests**
+
+Create `tests/middleware/rateLimit.test.ts`:
+
+```ts
+import { beforeEach, describe, expect, it } from "bun:test";
+import { Hono } from "hono";
+import { _resetForTesting, rateLimit } from "../../src/server/middleware/rateLimit";
+
+function createApp() {
+	const app = new Hono();
+	app.post("/login", rateLimit, (c) => c.json({ ok: true }));
+	app.post("/setup", rateLimit, (c) => c.json({ ok: true }));
+	return app;
+}
+
+function makeRequest(app: Hono, path: string, ip = "127.0.0.1") {
+	return app.request(path, {
+		method: "POST",
+		headers: { "x-forwarded-for": ip },
+	});
+}
+
+describe("rateLimit middleware", () => {
+	beforeEach(() => {
+		_resetForTesting();
+	});
+
+	it("allows first request through", async () => {
+		const app = createApp();
+		const res = await makeRequest(app, "/login");
+		expect(res.status).toBe(200);
+	});
+
+	it("allows up to 5 requests", async () => {
+		const app = createApp();
+		for (let i = 0; i < 5; i++) {
+			const res = await makeRequest(app, "/login");
+			expect(res.status).toBe(200);
+		}
+	});
+
+	it("returns 429 after 5 requests", async () => {
+		const app = createApp();
+		for (let i = 0; i < 5; i++) {
+			await makeRequest(app, "/login");
+		}
+		const res = await makeRequest(app, "/login");
+		expect(res.status).toBe(429);
+		const body = await res.json();
+		expect(body.error).toBe("Too many attempts. Try again later.");
+	});
+
+	it("includes Retry-After header on 429", async () => {
+		const app = createApp();
+		for (let i = 0; i < 5; i++) {
+			await makeRequest(app, "/login");
+		}
+		const res = await makeRequest(app, "/login");
+		expect(res.status).toBe(429);
+		const retryAfter = res.headers.get("Retry-After");
+		expect(retryAfter).toBeTruthy();
+		expect(Number(retryAfter)).toBeGreaterThan(0);
+	});
+
+	it("tracks different IPs independently", async () => {
+		const app = createApp();
+		// Fill up IP 1
+		for (let i = 0; i < 5; i++) {
+			await makeRequest(app, "/login", "10.0.0.1");
+		}
+		// IP 1 is blocked
+		const blocked = await makeRequest(app, "/login", "10.0.0.1");
+		expect(blocked.status).toBe(429);
+
+		// IP 2 still works
+		const allowed = await makeRequest(app, "/login", "10.0.0.2");
+		expect(allowed.status).toBe(200);
+	});
+
+	it("tracks different paths independently", async () => {
+		const app = createApp();
+		// Fill up /login
+		for (let i = 0; i < 5; i++) {
+			await makeRequest(app, "/login");
+		}
+		const blockedLogin = await makeRequest(app, "/login");
+		expect(blockedLogin.status).toBe(429);
+
+		// /setup still works
+		const allowedSetup = await makeRequest(app, "/setup");
+		expect(allowedSetup.status).toBe(200);
+	});
+});
+```
+
+- [ ] **Step 3: Run tests**
+
+Run: `bun test tests/middleware/rateLimit.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 4: Run full test suite**
+
+Run: `bun test`
+Expected: All tests pass (previous 183 + new ones).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/middleware/rateLimit.ts tests/middleware/rateLimit.test.ts
+git commit -m "test: add unit tests for rate limiter middleware"
+```
+
+---
+
+### Task 3: Route-Level Tests for Invalid ID Params
+
+**Files:**
+- Create: `tests/routes/params.test.ts`
+
+- [ ] **Step 1: Write tests**
+
+Create `tests/routes/params.test.ts`:
+
+```ts
+import { beforeEach, describe, expect, it } from "bun:test";
+import { Hono } from "hono";
+import { categoryRoutes } from "../../src/server/routes/categories";
+import { itemRoutes } from "../../src/server/routes/items";
+import { setupRoutes } from "../../src/server/routes/setups";
+import { threadRoutes } from "../../src/server/routes/threads";
+import { createTestDb } from "../helpers/db";
+
+function createTestApp() {
+	const db = createTestDb();
+	const app = new Hono();
+	app.use("*", async (c, next) => {
+		c.set("db", db);
+		await next();
+	});
+	app.route("/api/items", itemRoutes);
+	app.route("/api/categories", categoryRoutes);
+	app.route("/api/threads", threadRoutes);
+	app.route("/api/setups", setupRoutes);
+	return app;
+}
+
+describe("Invalid ID parameter handling", () => {
+	let app: Hono;
+
+	beforeEach(() => {
+		app = createTestApp();
+	});
+
+	describe("items", () => {
+		it("GET /api/items/abc returns 400", async () => {
+			const res = await app.request("/api/items/abc");
+			expect(res.status).toBe(400);
+			const body = await res.json();
+			expect(body.error).toContain("Invalid");
+		});
+
+		it("GET /api/items/0 returns 400", async () => {
+			const res = await app.request("/api/items/0");
+			expect(res.status).toBe(400);
+		});
+
+		it("GET /api/items/-1 returns 400", async () => {
+			const res = await app.request("/api/items/-1");
+			expect(res.status).toBe(400);
+		});
+	});
+
+	describe("categories", () => {
+		it("DELETE /api/categories/abc returns 400", async () => {
+			const res = await app.request("/api/categories/abc", {
+				method: "DELETE",
+			});
+			expect(res.status).toBe(400);
+		});
+	});
+
+	describe("threads", () => {
+		it("GET /api/threads/abc returns 400", async () => {
+			const res = await app.request("/api/threads/abc");
+			expect(res.status).toBe(400);
+		});
+
+		it("GET /api/threads/1.5 returns 400", async () => {
+			const res = await app.request("/api/threads/1.5");
+			expect(res.status).toBe(400);
+		});
+	});
+
+	describe("setups", () => {
+		it("GET /api/setups/abc returns 400", async () => {
+			const res = await app.request("/api/setups/abc");
+			expect(res.status).toBe(400);
+		});
+
+		it("GET /api/setups/0 returns 400", async () => {
+			const res = await app.request("/api/setups/0");
+			expect(res.status).toBe(400);
+		});
+	});
+});
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `bun test tests/routes/params.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/routes/params.test.ts
+git commit -m "test: add route-level tests for invalid ID parameter handling"
+```
+
+---
+
+### Task 4: Install Playwright and Create Config
+
+**Files:**
+- Modify: `package.json` (add dep + scripts)
+- Create: `playwright.config.ts`
+- Modify: `.gitignore`
+
+- [ ] **Step 1: Install Playwright**
+
+```bash
+bun add -d @playwright/test
+bunx playwright install chromium
+```
+
+- [ ] **Step 2: Create playwright.config.ts**
+
+Create `playwright.config.ts` at project root:
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+	testDir: "./e2e",
+	fullyParallel: false,
+	retries: 0,
+	workers: 1,
+	reporter: "list",
+	globalSetup: "./e2e/global-setup.ts",
+	use: {
+		baseURL: "http://localhost:3000",
+		trace: "on-first-retry",
+	},
+	projects: [
+		{
+			name: "chromium",
+			use: { ...devices["Desktop Chrome"] },
+		},
+	],
+	webServer: {
+		command: "DATABASE_PATH=./e2e/test.db bun run dev:server",
+		port: 3000,
+		reuseExistingServer: !process.env.CI,
+		timeout: 10000,
+	},
+});
+```
+
+- [ ] **Step 3: Add scripts to package.json**
+
+Add these to the `"scripts"` section in `package.json`:
+
+```json
+"test:e2e": "bunx playwright test",
+"test:e2e:ui": "bunx playwright test --ui"
+```
+
+- [ ] **Step 4: Update .gitignore**
+
+Append to `.gitignore`:
+
+```
+# Playwright
+e2e/test.db
+test-results/
+playwright-report/
+```
+
+- [ ] **Step 5: Run lint**
+
+Run: `bun run lint`
+Expected: Clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add package.json bun.lock playwright.config.ts .gitignore
+git commit -m "chore: install Playwright and add E2E test configuration"
+```
+
+---
+
+### Task 5: E2E Database Seed and Global Setup
+
+**Files:**
+- Create: `e2e/seed.ts`
+- Create: `e2e/global-setup.ts`
+
+- [ ] **Step 1: Create seed script**
+
+Create `e2e/seed.ts`:
+
+```ts
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+import * as schema from "../src/db/schema";
+
+const DB_PATH = "./e2e/test.db";
+
+export async function seedTestDatabase() {
+	// Remove old test DB if it exists
+	try {
+		await Bun.file(DB_PATH).exists() &&
+			(await import("node:fs/promises")).then((fs) => fs.unlink(DB_PATH));
+	} catch {
+		// File doesn't exist, that's fine
+	}
+
+	const sqlite = new Database(DB_PATH);
+	sqlite.run("PRAGMA journal_mode = WAL");
+	sqlite.run("PRAGMA foreign_keys = ON");
+
+	const db = drizzle(sqlite, { schema });
+
+	// Apply all migrations
+	migrate(db, { migrationsFolder: "./drizzle" });
+
+	// ── Seed Categories ──
+	const [uncategorized] = db
+		.insert(schema.categories)
+		.values({ name: "Uncategorized", icon: "package" })
+		.returning()
+		.all();
+
+	const [shelter] = db
+		.insert(schema.categories)
+		.values({ name: "Shelter", icon: "tent" })
+		.returning()
+		.all();
+
+	const [sleep] = db
+		.insert(schema.categories)
+		.values({ name: "Sleep System", icon: "moon" })
+		.returning()
+		.all();
+
+	const [cook] = db
+		.insert(schema.categories)
+		.values({ name: "Cook Kit", icon: "flame" })
+		.returning()
+		.all();
+
+	// ── Seed Items ──
+	const tent = db
+		.insert(schema.items)
+		.values({
+			name: "Zpacks Duplex",
+			weightGrams: 539,
+			priceCents: 67900,
+			categoryId: shelter.id,
+			notes: "DCF shelter, 2-person",
+		})
+		.returning()
+		.get();
+
+	const tarp = db
+		.insert(schema.items)
+		.values({
+			name: "Borah Gear Tarp",
+			weightGrams: 156,
+			priceCents: 11000,
+			categoryId: shelter.id,
+		})
+		.returning()
+		.get();
+
+	const quilt = db
+		.insert(schema.items)
+		.values({
+			name: "Enlightened Equipment Enigma 20",
+			weightGrams: 595,
+			priceCents: 34000,
+			categoryId: sleep.id,
+			notes: "20F quilt",
+		})
+		.returning()
+		.get();
+
+	const pad = db
+		.insert(schema.items)
+		.values({
+			name: "Therm-a-Rest NeoAir XLite",
+			weightGrams: 354,
+			priceCents: 20999,
+			categoryId: sleep.id,
+		})
+		.returning()
+		.get();
+
+	const stove = db
+		.insert(schema.items)
+		.values({
+			name: "BRS-3000T Stove",
+			weightGrams: 25,
+			priceCents: 2000,
+			categoryId: cook.id,
+		})
+		.returning()
+		.get();
+
+	const pot = db
+		.insert(schema.items)
+		.values({
+			name: "Toaks 750ml Pot",
+			weightGrams: 103,
+			priceCents: 3000,
+			categoryId: cook.id,
+		})
+		.returning()
+		.get();
+
+	// ── Seed Active Thread with 3 Candidates ──
+	const activeThread = db
+		.insert(schema.threads)
+		.values({
+			name: "New Backpack",
+			status: "active",
+			categoryId: uncategorized.id,
+		})
+		.returning()
+		.get();
+
+	db.insert(schema.threadCandidates)
+		.values({
+			threadId: activeThread.id,
+			name: "ULA Circuit",
+			weightGrams: 1077,
+			priceCents: 27500,
+			categoryId: uncategorized.id,
+			pros: "Great hip belt\nLarge capacity",
+			cons: "Heavier than competitors",
+			sortOrder: 1000,
+			status: "researching",
+		})
+		.run();
+
+	db.insert(schema.threadCandidates)
+		.values({
+			threadId: activeThread.id,
+			name: "Gossamer Gear Mariposa",
+			weightGrams: 737,
+			priceCents: 28500,
+			categoryId: uncategorized.id,
+			pros: "Very lightweight\nGood ventilation",
+			cons: "Smaller hip belt pockets",
+			sortOrder: 2000,
+			status: "researching",
+		})
+		.run();
+
+	db.insert(schema.threadCandidates)
+		.values({
+			threadId: activeThread.id,
+			name: "Granite Gear Crown2 38",
+			weightGrams: 850,
+			priceCents: 18000,
+			categoryId: uncategorized.id,
+			sortOrder: 3000,
+			status: "ordered",
+		})
+		.run();
+
+	// ── Seed Resolved Thread ──
+	const resolvedThread = db
+		.insert(schema.threads)
+		.values({
+			name: "Camp Stove",
+			status: "resolved",
+			categoryId: cook.id,
+			resolvedCandidateId: 1,
+		})
+		.returning()
+		.get();
+
+	db.insert(schema.threadCandidates)
+		.values({
+			threadId: resolvedThread.id,
+			name: "BRS-3000T",
+			weightGrams: 25,
+			priceCents: 2000,
+			categoryId: cook.id,
+			sortOrder: 1000,
+			status: "arrived",
+		})
+		.run();
+
+	// ── Seed Setup with Items ──
+	const setup = db
+		.insert(schema.setups)
+		.values({ name: "Weekend Overnighter" })
+		.returning()
+		.get();
+
+	db.insert(schema.setupItems)
+		.values([
+			{ setupId: setup.id, itemId: tent.id, classification: "base" },
+			{ setupId: setup.id, itemId: quilt.id, classification: "base" },
+			{ setupId: setup.id, itemId: pad.id, classification: "base" },
+			{ setupId: setup.id, itemId: stove.id, classification: "consumable" },
+		])
+		.run();
+
+	// ── Seed User ──
+	const passwordHash = await Bun.password.hash("password123");
+	db.insert(schema.users)
+		.values({ username: "admin", passwordHash })
+		.run();
+
+	// ── Seed Settings ──
+	db.insert(schema.settings)
+		.values([
+			{ key: "weightUnit", value: "g" },
+			{ key: "currency", value: "USD" },
+			{ key: "onboardingComplete", value: "true" },
+		])
+		.run();
+
+	sqlite.close();
+	console.log("E2E test database seeded at", DB_PATH);
+}
+```
+
+- [ ] **Step 2: Create global-setup**
+
+Create `e2e/global-setup.ts`:
+
+```ts
+import { seedTestDatabase } from "./seed";
+
+export default async function globalSetup() {
+	await seedTestDatabase();
+}
+```
+
+- [ ] **Step 3: Verify seed works**
+
+Run: `bun run e2e/global-setup.ts`
+Expected: Prints "E2E test database seeded at ./e2e/test.db" and the file exists.
+
+Then clean up: `rm -f e2e/test.db`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add e2e/seed.ts e2e/global-setup.ts
+git commit -m "test: add E2E database seed and Playwright global setup"
+```
+
+---
+
+### Task 6: E2E Tests — Dashboard and Collection
+
+**Files:**
+- Create: `e2e/dashboard.spec.ts`
+- Create: `e2e/collection.spec.ts`
+
+- [ ] **Step 1: Create dashboard tests**
+
+Create `e2e/dashboard.spec.ts`:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test.describe("Dashboard", () => {
+	test("loads and shows summary cards", async ({ page }) => {
+		await page.goto("/");
+		await expect(page.locator("text=GearBox")).toBeVisible();
+		// Should show item count (we seeded 6 items)
+		await expect(page.locator("text=6")).toBeVisible();
+	});
+
+	test("has navigation to collection", async ({ page }) => {
+		await page.goto("/");
+		// Click on a dashboard card or link that goes to collection
+		const collectionLink = page.locator('a[href*="collection"]').first();
+		if (await collectionLink.isVisible()) {
+			await collectionLink.click();
+			await expect(page).toHaveURL(/collection/);
+		}
+	});
+});
+```
+
+- [ ] **Step 2: Create collection tests**
+
+Create `e2e/collection.spec.ts`:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test.describe("Collection", () => {
+	test("gear tab shows items grouped by category", async ({ page }) => {
+		await page.goto("/collection?tab=gear");
+		// Should see seeded items
+		await expect(page.locator("text=Zpacks Duplex")).toBeVisible();
+		await expect(page.locator("text=BRS-3000T Stove")).toBeVisible();
+		// Should see category headers
+		await expect(page.locator("text=Shelter")).toBeVisible();
+		await expect(page.locator("text=Cook Kit")).toBeVisible();
+	});
+
+	test("search filters items by name", async ({ page }) => {
+		await page.goto("/collection?tab=gear");
+		const searchInput = page.locator('input[placeholder*="Search"]');
+		await searchInput.fill("Zpacks");
+		// Should show matching item
+		await expect(page.locator("text=Zpacks Duplex")).toBeVisible();
+		// Should hide non-matching items
+		await expect(page.locator("text=BRS-3000T Stove")).not.toBeVisible();
+	});
+
+	test("tab switching works", async ({ page }) => {
+		await page.goto("/collection?tab=gear");
+		await expect(page.locator("text=Zpacks Duplex")).toBeVisible();
+
+		// Switch to planning tab
+		await page.goto("/collection?tab=planning");
+		await expect(page.locator("text=Planning Threads")).toBeVisible();
+		await expect(page.locator("text=New Backpack")).toBeVisible();
+
+		// Switch to setups tab
+		await page.goto("/collection?tab=setups");
+		await expect(page.locator("text=Weekend Overnighter")).toBeVisible();
+	});
+
+	test("category filter dropdown works", async ({ page }) => {
+		await page.goto("/collection?tab=gear");
+		// Open category filter
+		const filterButton = page.locator("text=All categories");
+		await filterButton.click();
+		// Select "Shelter"
+		await page.locator("li").filter({ hasText: "Shelter" }).click();
+		// Should show only shelter items
+		await expect(page.locator("text=Zpacks Duplex")).toBeVisible();
+		await expect(page.locator("text=BRS-3000T Stove")).not.toBeVisible();
+	});
+});
+```
+
+- [ ] **Step 3: Run E2E tests**
+
+Run: `bun run test:e2e`
+Expected: All tests pass. If any fail due to selector issues, adjust selectors based on actual DOM.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add e2e/dashboard.spec.ts e2e/collection.spec.ts
+git commit -m "test: add E2E tests for dashboard and collection views"
+```
+
+---
+
+### Task 7: E2E Tests — Threads, Auth, Error Handling
+
+**Files:**
+- Create: `e2e/threads.spec.ts`
+- Create: `e2e/auth.spec.ts`
+- Create: `e2e/error-handling.spec.ts`
+
+- [ ] **Step 1: Create threads tests**
+
+Create `e2e/threads.spec.ts`:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test.describe("Threads", () => {
+	test("thread detail page shows candidates", async ({ page }) => {
+		// Navigate to the active thread
+		await page.goto("/collection?tab=planning");
+		await page.locator("text=New Backpack").click();
+		// Should see candidates
+		await expect(page.locator("text=ULA Circuit")).toBeVisible();
+		await expect(page.locator("text=Gossamer Gear Mariposa")).toBeVisible();
+		await expect(page.locator("text=Granite Gear Crown2 38")).toBeVisible();
+	});
+
+	test("rank badges are visible on candidates", async ({ page }) => {
+		await page.goto("/collection?tab=planning");
+		await page.locator("text=New Backpack").click();
+		// Should see rank badges (gold, silver, bronze for top 3)
+		// The rank badges use specific colors: #D4AF37 (gold), #C0C0C0 (silver), #CD7F32 (bronze)
+		await expect(page.locator("text=#1").first()).toBeVisible();
+	});
+
+	test("comparison view toggles on", async ({ page }) => {
+		await page.goto("/collection?tab=planning");
+		await page.locator("text=New Backpack").click();
+		// Find and click the compare toggle
+		const compareButton = page.locator("button", { hasText: /compare/i });
+		if (await compareButton.isVisible()) {
+			await compareButton.click();
+			// Comparison table should appear with attribute rows
+			await expect(page.locator("text=Weight")).toBeVisible();
+			await expect(page.locator("text=Price")).toBeVisible();
+		}
+	});
+
+	test("resolved thread shows winner", async ({ page }) => {
+		await page.goto("/collection?tab=planning");
+		// Switch to resolved tab
+		await page.locator("button", { hasText: "Resolved" }).click();
+		await page.locator("text=Camp Stove").click();
+		// Should indicate resolved state
+		await expect(page.locator("text=BRS-3000T")).toBeVisible();
+	});
+});
+```
+
+- [ ] **Step 2: Create auth tests**
+
+Create `e2e/auth.spec.ts`:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test.describe("Auth", () => {
+	test("login page renders", async ({ page }) => {
+		await page.goto("/login");
+		await expect(page.locator("text=Log in")).toBeVisible();
+	});
+
+	test("login with valid credentials succeeds", async ({ page }) => {
+		await page.goto("/login");
+		await page.locator('input[name="username"], input[placeholder*="sername"]').fill("admin");
+		await page.locator('input[type="password"]').fill("password123");
+		await page.locator('button[type="submit"]').click();
+		// Should redirect away from login
+		await page.waitForURL((url) => !url.pathname.includes("/login"), {
+			timeout: 5000,
+		});
+	});
+
+	test("login with wrong password shows error", async ({ page }) => {
+		await page.goto("/login");
+		await page.locator('input[name="username"], input[placeholder*="sername"]').fill("admin");
+		await page.locator('input[type="password"]').fill("wrongpassword");
+		await page.locator('button[type="submit"]').click();
+		// Should show error message
+		await expect(page.locator("text=Invalid credentials").or(page.locator('[role="alert"]'))).toBeVisible({
+			timeout: 3000,
+		});
+	});
+});
+```
+
+- [ ] **Step 3: Create error handling tests**
+
+Create `e2e/error-handling.spec.ts`:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test.describe("Error handling", () => {
+	test("non-existent thread shows not found or error", async ({ page }) => {
+		await page.goto("/threads/99999");
+		// Should not white-screen — should show some content
+		const body = page.locator("body");
+		await expect(body).not.toBeEmpty();
+		// Either shows error boundary or "not found" text
+		const hasContent = await page
+			.locator("text=Something went wrong")
+			.or(page.locator("text=not found"))
+			.or(page.locator("text=Not Found"))
+			.isVisible()
+			.catch(() => false);
+		// At minimum, the page should not be blank
+		const bodyText = await body.textContent();
+		expect(bodyText?.length).toBeGreaterThan(0);
+	});
+
+	test("non-existent setup shows not found or error", async ({ page }) => {
+		await page.goto("/setups/99999");
+		const body = page.locator("body");
+		await expect(body).not.toBeEmpty();
+		const bodyText = await body.textContent();
+		expect(bodyText?.length).toBeGreaterThan(0);
+	});
+
+	test("app recovers from navigation errors", async ({ page }) => {
+		// Navigate to a bad route, then back to a good one
+		await page.goto("/threads/99999");
+		await page.goto("/");
+		// Dashboard should load fine
+		await expect(page.locator("text=GearBox")).toBeVisible();
+	});
+});
+```
+
+- [ ] **Step 4: Run all E2E tests**
+
+Run: `bun run test:e2e`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add e2e/threads.spec.ts e2e/auth.spec.ts e2e/error-handling.spec.ts
+git commit -m "test: add E2E tests for threads, auth, and error handling"
+```
+
+---
+
+### Task 8: Final Verification
+
+- [ ] **Step 1: Run unit tests**
+
+Run: `bun test`
+Expected: All tests pass (previous 183 + new parseId + rate limiter + param routes).
+
+- [ ] **Step 2: Run E2E tests**
+
+Run: `bun run test:e2e`
+Expected: All E2E tests pass.
+
+- [ ] **Step 3: Run lint**
+
+Run: `bun run lint`
+Expected: Clean.

docs/superpowers/specs/2026-04-03-authentication-design.md

@@ -0,0 +1,133 @@
+# Authentication — Design Spec
+
+## Overview
+
+Add authentication to GearBox with a public-read, authenticated-write model. Web UI uses cookie-based sessions. Programmatic access (MCP server, scripts) uses API keys. Single-user app — one admin account, created on first setup.
+
+## Database Schema
+
+### `users` table
+
+```typescript
+export const users = sqliteTable("users", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  username: text("username").notNull().unique(),
+  passwordHash: text("password_hash").notNull(),
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+});
+```
+
+### `sessions` table
+
+```typescript
+export const sessions = sqliteTable("sessions", {
+  id: text("id").primaryKey(), // random token
+  userId: integer("user_id").notNull().references(() => users.id),
+  expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(),
+});
+```
+
+### `apiKeys` table
+
+```typescript
+export const apiKeys = sqliteTable("api_keys", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  keyHash: text("key_hash").notNull(),
+  keyPrefix: text("key_prefix").notNull(), // first 8 chars for identification
+  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+});
+```
+
+## Password Hashing
+
+Use `Bun.password.hash()` and `Bun.password.verify()` with argon2 (Bun's default). No external dependencies needed.
+
+## Auth Middleware
+
+Hono middleware applied to all write endpoints (POST, PUT, DELETE):
+
+1. Check for `X-API-Key` header — if present, hash and compare against `api_keys` table
+2. Check for session cookie (`gearbox_session`) — if present, look up in `sessions` table, verify not expired
+3. If neither is valid, return `401 Unauthorized`
+
+GET endpoints remain public — no middleware applied.
+
+**Exempt from auth:** `/api/auth/login`, `/api/auth/setup`, and `/api/auth/me` (GET) are not protected by the write middleware.
+
+**Before setup:** If no user account exists yet, write endpoints return `403` with `{ error: "setup_required" }` so the frontend can prompt account creation.
+
+## API Endpoints
+
+### Auth routes (`/api/auth`)
+
+- `POST /api/auth/login` — accepts `{ username, password }`, creates session, sets cookie
+- `POST /api/auth/logout` — clears session cookie, deletes session record
+- `GET /api/auth/me` — returns current user info if authenticated, or `null`
+- `POST /api/auth/setup` — initial account creation (only works if no users exist)
+- `PUT /api/auth/password` — change password (requires current password)
+
+### API key routes (`/api/auth/keys`) — all authenticated
+
+- `GET /api/auth/keys` — list API keys (name, prefix, createdAt — never the full key)
+- `POST /api/auth/keys` — create new key, returns the full key once
+- `DELETE /api/auth/keys/:id` — revoke a key
+
+## Session Management
+
+- Session token: 32-byte random hex string
+- Cookie: `gearbox_session`, httpOnly, sameSite=lax, path=/
+- Session expiry: 30 days, refreshed on each authenticated request
+- Sessions stored in SQLite — simple cleanup of expired rows
+
+## Frontend Changes
+
+### Login button (top-right, Gitea-style)
+
+- When not logged in: "Sign in" button in the header/navbar
+- When logged in: username display with dropdown (logout, settings link)
+
+### Login page
+
+- Route: `/login`
+- Simple form: username + password + submit
+- Redirects back to previous page on success
+- Error message on invalid credentials
+
+### Initial setup
+
+- If `GET /api/auth/me` returns `null` and no users exist, show a setup prompt
+- Setup form: create username + password
+- Only shown once — after account creation, normal login flow applies
+
+### Conditional UI
+
+- Add/edit/delete buttons: hidden when not authenticated
+- Forms (ItemForm, CandidateForm, etc.): only accessible when authenticated
+- The app is fully browseable without login — you just can't modify anything
+
+### Auth state
+
+- `useAuth` hook using React Query: calls `GET /api/auth/me`
+- Returns `{ user, isAuthenticated, login, logout }`
+- Cached and invalidated on login/logout
+
+### Settings page additions
+
+- API key management section: list, create, revoke
+- Change password form
+
+## Testing
+
+- Auth service tests: login, logout, session creation/validation, password change
+- API key tests: create, verify, revoke
+- Middleware tests: write endpoints reject without auth, read endpoints work without auth
+- Setup flow test: first-user creation
+
+## Security Considerations
+
+- Passwords hashed with argon2 via Bun built-in
+- Session tokens are cryptographically random
+- API keys hashed before storage (only shown once on creation)
+- httpOnly cookies prevent XSS access to session
+- No CORS changes needed (single-origin app)

docs/superpowers/specs/2026-04-03-code-quality-round2-design.md

@@ -0,0 +1,74 @@
+# Code Quality Improvements (Round 2) Design
+
+**Date:** 2026-04-03
+**Scope:** Combined formatters hook, test helper schema generation, stale todo cleanup
+
+## 1. useFormatters Combined Hook
+
+**Problem:** 14 component files import the same 3-4 lines: `useWeightUnit`, `useCurrency`, `formatWeight`, `formatPrice`. This is repetitive boilerplate.
+
+**Solution:** Create `src/client/hooks/useFormatters.ts` that returns pre-bound formatting functions:
+
+```ts
+export function useFormatters() {
+  const unit = useWeightUnit();
+  const currency = useCurrency();
+  return {
+    weight: (grams: number | null) => formatWeight(grams, unit),
+    price: (cents: number | null) => formatPrice(cents, currency),
+    unit,
+    currency,
+  };
+}
+```
+
+**Consumer files to update (14):**
+- CollectionView.tsx
+- setups/$setupId.tsx
+- routes/index.tsx
+- WeightSummaryCard.tsx
+- TotalsBar.tsx
+- settings.tsx
+- ThreadCard.tsx
+- SetupCard.tsx
+- ItemPicker.tsx
+- ItemCard.tsx
+- ComparisonTable.tsx
+- CandidateCard.tsx
+- CandidateListItem.tsx
+- CategoryHeader.tsx
+
+Each file replaces 3-4 imports + 2 hook calls with 1 import + 1 destructured hook call. Components that need raw `unit` or `currency` (e.g., WeightSummaryCard uses `unit` as a type, TotalsBar has a unit toggle) get them from the return object.
+
+## 2. Test Helper Schema Generation
+
+**Problem:** `tests/helpers/db.ts` has 120 lines of hand-written CREATE TABLE SQL that must manually mirror `src/db/schema.ts`. Any schema change requires updating both files — a known source of `SqliteError: no such column` failures.
+
+**Solution:** Replace hand-written SQL with Drizzle's migration runner:
+
+```ts
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+
+export function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  const db = drizzle(sqlite, { schema });
+  migrate(db, { migrationsFolder: "./drizzle" });
+  db.insert(schema.categories).values({ name: "Uncategorized", icon: "package" }).run();
+  return db;
+}
+```
+
+This reduces the file from ~128 lines to ~15 lines and eliminates all future manual sync.
+
+## 3. Stale Todo Cleanup
+
+**Problem:** Pending todo "Replace planning category filter select with icon-aware dropdown" from 2026-03-15 is already resolved — `PlanningView.tsx` uses `<CategoryFilterDropdown>` which renders Lucide icons.
+
+**Solution:** Move the todo file from `pending/` to `done/`.
+
+## Commit Strategy
+
+1. **useFormatters hook** — create hook + update all 14 consumer files
+2. **Test helper migration** — replace hand-written SQL with migrate()
+3. **Todo cleanup** — move stale todo to done

docs/superpowers/specs/2026-04-03-codebase-improvements-design.md

@@ -0,0 +1,152 @@
+# Codebase Improvements Design
+
+**Date:** 2026-04--03
+**Scope:** General code quality, error handling, resilience, and maintainability improvements
+
+## 1. Server Hardening
+
+### 1a. Explicit DB Context Middleware
+
+**File:** `src/server/index.ts`
+
+Add middleware that explicitly sets `c.set("db", prodDb)` for all API routes. Currently routes call `c.get("db")` but nothing sets it in production — services silently fall back to `prodDb` via default parameters. This makes production behavior match the test pattern.
+
+```ts
+import { db as prodDb } from "../db/index.ts";
+
+app.use("/api/*", async (c, next) => {
+  c.set("db", prodDb);
+  return next();
+});
+```
+
+Place this **before** the auth middleware so `db` is available when auth checks run.
+
+### 1b. Route Parameter Validation
+
+**New file:** `src/server/lib/params.ts`
+
+Create a helper that validates numeric route params:
+
+```ts
+export function parseId(raw: string): number | null {
+  const id = Number(raw);
+  if (!Number.isInteger(id) || id <= 0) return null;
+  return id;
+}
+```
+
+Update all route files (`items.ts`, `threads.ts`, `categories.ts`, `setups.ts`) to replace `Number(c.req.param("id"))` with `parseId()`, returning 400 for invalid IDs.
+
+### 1c. Centralized Error Handling
+
+**File:** `src/server/index.ts`
+
+Add Hono's `onError` handler:
+
+```ts
+app.onError((err, c) => {
+  console.error(`[${c.req.method}] ${c.req.path}:`, err);
+  const status = err instanceof HTTPException ? err.status : 500;
+  const message = process.env.NODE_ENV === "production"
+    ? "Internal server error"
+    : err.message;
+  return c.json({ error: message }, status);
+});
+```
+
+### 1d. Auth Comment Fix
+
+**File:** `src/server/index.ts`
+
+Change comment from:
+```
+// Auth middleware for write operations (POST/PUT/DELETE) on non-auth routes
+```
+To:
+```
+// Auth middleware for write operations (POST/PUT/PATCH/DELETE) on non-auth routes
+```
+
+### 1e. Rate Limiting on Auth Endpoints
+
+**New file:** `src/server/middleware/rateLimit.ts`
+
+In-memory rate limiter using a `Map<string, { count: number; resetAt: number }>`:
+
+- Tracks by IP (`c.req.header("x-forwarded-for") || "unknown"`)
+- 5 attempts per 15-minute window
+- Returns 429 with `{ error: "Too many attempts. Try again later." }` and `Retry-After` header
+- Stale entries cleaned on each check
+- Applied to `POST /api/auth/login` and `POST /api/auth/setup`
+
+## 2. Client Resilience
+
+### Error Boundary
+
+**File:** `src/client/routes/__root.tsx`
+
+Add `errorComponent` to the root route definition:
+
+```ts
+export const Route = createRootRoute({
+  component: RootLayout,
+  errorComponent: RootErrorBoundary,
+});
+```
+
+`RootErrorBoundary` renders a centered error message with:
+- "Something went wrong" heading
+- Error message in dev mode
+- "Try again" button that calls `router.invalidate()` + `reset()`
+
+Uses TanStack Router's `ErrorComponentProps` which provides `error` and `reset`.
+
+## 3. Client Refactor
+
+### Split collection/index.tsx
+
+Extract the three tab-level functions into separate component files:
+
+| Source function | New file | Approx lines |
+|----------------|----------|-------------|
+| `CollectionView()` | `src/client/components/CollectionView.tsx` | ~260 |
+| `PlanningView()` | `src/client/components/PlanningView.tsx` | ~190 |
+| `SetupsView()` | `src/client/components/SetupsView.tsx` | ~110 |
+
+`collection/index.tsx` keeps:
+- Route definition with `searchSchema` and `validateSearch`
+- `CollectionPage` function (tab switcher + AnimatePresence)
+- `TAB_ORDER` and `slideVariants` constants
+- Imports from the three new component files
+
+Each extracted component is a named export, self-contained with its own hooks and local state.
+
+## 4. Docs Cleanup
+
+### PROJECT.md
+
+**File:** `.planning/PROJECT.md`
+
+Update Constraints section line:
+```
+- **Scope**: No auth, single user for v1
+```
+To:
+```
+- **Scope**: Single user with cookie/API key auth
+```
+
+## Commit Strategy
+
+Group into 3-4 commits by area:
+1. **Server hardening**: DB middleware, param validation, error handler, rate limiter, comment fix
+2. **Client resilience + refactor**: Error boundary, split collection route
+3. **Docs cleanup**: PROJECT.md update
+
+## Testing
+
+- All 183 existing tests must continue to pass
+- Rate limiter: manual verification (no automated test needed for in-memory rate limiting in a single-user app)
+- Error boundary: manual verification by triggering a render error
+- Param validation: existing route tests cover happy paths; invalid IDs are a new edge case but won't break existing tests

docs/superpowers/specs/2026-04-03-image-url-fetching-design.md

@@ -0,0 +1,87 @@
+# Image URL Fetching — Design Spec
+
+## Overview
+
+Add the ability to fetch images from external URLs via the API, download them to local storage, and preserve the original source URL as metadata. API-only feature — no frontend changes.
+
+## New Endpoint
+
+### `POST /api/images/from-url`
+
+**Request:**
+
+```json
+{ "url": "https://example.com/photo.jpg" }
+```
+
+**Validation (Zod):**
+
+- `url` — valid URL string, required
+
+**Server-side behavior:**
+
+1. Fetch the URL with a 10-second timeout
+2. Check response `Content-Type` is one of: `image/jpeg`, `image/png`, `image/webp`
+3. Check `Content-Length` does not exceed 5MB (match existing upload limit)
+4. Stream response body to `uploads/` directory using existing naming: `${Date.now()}-${randomUUID()}.${ext}`
+5. If any check fails, return 400 with descriptive error
+
+**Response:**
+
+```json
+{ "filename": "1712160000000-abc123.jpg", "sourceUrl": "https://example.com/photo.jpg" }
+```
+
+Callers can use `filename` for `imageFilename` and `sourceUrl` for `imageSourceUrl` when creating/updating items or candidates.
+
+**Error responses:**
+
+- `400` — invalid URL, unsupported content type, file too large, fetch failed
+- `500` — server error during download/save
+
+## Schema Changes
+
+### `items` table
+
+Add column:
+
+```
+imageSourceUrl: text("image_source_url")  // nullable
+```
+
+### `threadCandidates` table
+
+Add column:
+
+```
+imageSourceUrl: text("image_source_url")  // nullable
+```
+
+### Zod schemas
+
+Add `imageSourceUrl: z.string().url().optional()` to:
+
+- `createItemSchema`
+- `updateItemSchema`
+- `createCandidateSchema`
+- `updateCandidateSchema`
+
+### Types
+
+Types are inferred from Zod schemas and Drizzle tables — no manual updates needed.
+
+## Existing Behavior Unchanged
+
+- `POST /api/images` (file upload) remains as-is
+- All existing image display, cleanup, and serving logic unchanged
+- `imageFilename` continues to work identically
+
+## Test Helper Updates
+
+Add `image_source_url TEXT` column to the `items` and `thread_candidates` CREATE TABLE statements in `tests/helpers/db.ts`.
+
+## Testing
+
+- Service test: fetch from a valid URL, verify file saved and filename returned
+- Route test: POST to `/api/images/from-url` with valid/invalid URLs
+- Validation tests: wrong content type, oversized image, invalid URL format, timeout

docs/superpowers/specs/2026-04-03-mcp-server-design.md

@@ -0,0 +1,158 @@
+# MCP Server — Design Spec
+
+## Overview
+
+Built-in MCP server running inside the GearBox Hono process, exposed via SSE transport at `/mcp`. Provides tools for managing the full gear collection with workflow guidance emphasizing research threads. Authenticates via API key.
+
+## Transport & Configuration
+
+- **Transport:** SSE or Streamable HTTP at `/mcp` (use whichever the MCP SDK supports best at implementation time — the newer spec favors Streamable HTTP)
+- **Enabled by default**, disable with `GEARBOX_MCP=false` env var
+- **Authentication:** API key passed in MCP client config, sent as `X-API-Key` header
+- **SDK:** `@modelcontextprotocol/sdk` TypeScript package
+
+## Integration with Hono
+
+The MCP server mounts as a route on the existing Hono app:
+
+```typescript
+// src/server/index.ts
+if (process.env.GEARBOX_MCP !== "false") {
+  app.route("/mcp", mcpRoutes);
+}
+```
+
+The MCP route handler bridges SSE transport to the MCP server instance, which calls GearBox services directly (not via HTTP) for efficiency.
+
+## Tools
+
+All tools include descriptive names and descriptions that guide Claude toward the research thread workflow.
+
+### Item Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_items` | List all items in the gear collection. Optionally filter by category. |
+| `get_item` | Get details of a specific item by ID. |
+| `create_item` | Add a new item to the gear collection. Use this for items you've already decided on. For items you're still researching, use create_thread instead. |
+| `update_item` | Update an existing item's details. |
+| `delete_item` | Remove an item from the collection. |
+
+### Category Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_categories` | List all gear categories. |
+| `create_category` | Create a new category for organizing gear. |
+
+### Thread Tools (Primary Workflow)
+
+| Tool | Description |
+|------|-------------|
+| `list_threads` | List all research threads. Threads are the recommended way to evaluate gear purchases — create a thread, add candidates, compare them, then resolve to pick a winner. |
+| `get_thread` | Get a thread with all its candidates and comparison data. |
+| `create_thread` | Start a new research thread for evaluating a gear purchase. This is the preferred workflow: create a thread describing what you need, add candidate products, compare specs/weight/price, then resolve when you've decided. |
+| `resolve_thread` | Resolve a thread by picking the winning candidate. This adds the winner to your collection as a new item and marks the thread as resolved. |
+
+### Candidate Tools
+
+| Tool | Description |
+|------|-------------|
+| `add_candidate` | Add a candidate product to a research thread. Include weight, price, pros, cons, and optionally an image URL. |
+| `update_candidate` | Update a candidate's details — weight, price, pros, cons, etc. |
+| `remove_candidate` | Remove a candidate from a research thread. |
+
+### Setup Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_setups` | List all gear setups (named configurations of items). |
+| `get_setup` | Get a setup with all its items, total weight, and total cost. |
+| `create_setup` | Create a new gear setup. |
+| `update_setup` | Update a setup's items or details. |
+
+### Image Tools
+
+| Tool | Description |
+|------|-------------|
+| `upload_image_from_url` | Fetch an image from a URL and attach it to an item or candidate. |
+
+## Resources
+
+### `gearbox://collection-summary`
+
+Provides an overview of the current gear collection:
+
+- Total items, total weight, total cost
+- Items per category
+- Active research threads
+- Number of setups
+
+This resource gives Claude context about the collection state before making tool calls.
+
+## Workflow Guidance
+
+The MCP server's tool descriptions are crafted to guide Claude toward the research thread pattern:
+
+1. When the user asks about buying gear, Claude should prefer `create_thread` over `create_item`
+2. Candidates are added to threads for comparison before committing
+3. `resolve_thread` is the way to finalize a purchase decision
+4. Direct `create_item` is for items already owned or decided on
+
+This guidance lives in the tool descriptions themselves — no separate system prompt needed. The `collection-summary` resource helps Claude understand what's already in the collection.
+
+## Implementation Structure
+
+```
+src/server/mcp/
+  index.ts          — MCP server setup, tool/resource registration
+  tools/
+    items.ts        — Item tool handlers
+    categories.ts   — Category tool handlers
+    threads.ts      — Thread + candidate tool handlers
+    setups.ts       — Setup tool handlers
+    images.ts       — Image tool handlers
+  resources/
+    collection.ts   — Collection summary resource
+```
+
+## Client Configuration
+
+### Claude Code (`.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "sse",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "gearbox": {
+      "type": "sse",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "X-API-Key": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+## Testing
+
+- Tool handler tests: each tool with valid/invalid inputs
+- Auth test: requests without API key are rejected
+- Resource test: collection summary returns accurate data
+- Integration test: create thread -> add candidates -> resolve -> verify item created

docs/superpowers/specs/2026-04-03-testing-improvements-design.md

@@ -0,0 +1,128 @@
+# Testing Improvements Design
+
+**Date:** 2026-04-03
+**Scope:** Unit tests for new server code + Playwright E2E test setup with seeded database
+
+## Part 1: Unit/Integration Tests (Bun test runner)
+
+### tests/lib/params.test.ts
+
+Tests for `parseId` helper in `src/server/lib/params.ts`:
+- Valid positive integers (1, 42, 999) return the number
+- Zero returns null
+- Negative numbers (-1, -100) return null
+- Decimals (1.5, 3.14) return null
+- Non-numeric strings ("abc", "", "hello") return null
+- NaN-producing values return null
+
+### tests/middleware/rateLimit.test.ts
+
+Tests for rate limiter in `src/server/middleware/rateLimit.ts`:
+- First request passes through (200)
+- 5 requests succeed, 6th returns 429
+- 429 response includes `Retry-After` header
+- Different IPs tracked independently
+- After window expires, requests succeed again
+
+Since the rate limiter uses a module-level `Map`, tests need to either:
+- Reset the store between tests (export a `resetStore` for testing), OR
+- Use unique paths/IPs per test to avoid interference
+
+Recommended: export a `_resetForTesting()` function from rateLimit.ts that clears the store. Only used in tests.
+
+### tests/routes/params.test.ts
+
+Route-level integration tests verifying 400 responses for invalid IDs:
+- `GET /api/items/abc` → 400
+- `GET /api/items/-1` → 400
+- `GET /api/items/0` → 400
+- `DELETE /api/categories/notanumber` → 400
+- `GET /api/threads/abc` → 400
+- `GET /api/setups/abc` → 400
+
+Uses existing test app pattern with in-memory DB.
+
+## Part 2: Playwright E2E Setup
+
+### Installation
+
+- `bun add -d @playwright/test`
+- `bunx playwright install chromium` (only Chromium needed)
+
+### Configuration: playwright.config.ts
+
+```ts
+export default defineConfig({
+  testDir: "./e2e",
+  webServer: {
+    command: "DATABASE_PATH=./e2e/test.db bun run dev:server",
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: "http://localhost:3000",
+  },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+});
+```
+
+### Database Seeding: e2e/seed.ts
+
+Script that creates `e2e/test.db` with:
+- Run Drizzle migrations against the file
+- Seed data:
+  - 1 user (username: "admin", password: "password123")
+  - 3 categories: Shelter, Sleep System, Cook Kit
+  - 6 items across categories with realistic weights/prices
+  - 1 active thread with 3 candidates (with pros/cons, sort_order)
+  - 1 resolved thread
+  - 1 setup with 4 items (mixed classifications)
+  - Settings: weightUnit=g, currency=USD, onboardingComplete=true
+
+Run before E2E tests via `e2e/global-setup.ts` (Playwright globalSetup).
+
+### E2E Test Files
+
+**e2e/dashboard.spec.ts**
+- Dashboard page loads
+- Summary cards show item count, weight, cost
+- Navigation links to collection work
+
+**e2e/collection.spec.ts**
+- Gear tab renders items grouped by category
+- Search input filters items by name
+- Category filter dropdown works
+- Tab switching between gear/planning/setups
+
+**e2e/threads.spec.ts**
+- Thread detail page loads with candidates
+- Comparison view toggle works (shows table)
+- Rank badges visible on candidates
+
+**e2e/auth.spec.ts**
+- Login page renders
+- Login with valid credentials succeeds
+- Login with wrong password shows error
+- Rate limiting returns error after 5 attempts
+
+**e2e/error-boundary.spec.ts**
+- App doesn't white-screen on unknown routes
+- Navigating to a non-existent thread/setup shows appropriate error
+
+### Scripts
+
+Add to package.json:
+- `"test:e2e": "bunx playwright test"`
+- `"test:e2e:ui": "bunx playwright test --ui"` (for debugging)
+
+### Files to .gitignore
+
+- `e2e/test.db`
+- `test-results/`
+- `playwright-report/`
+
+## Commit Strategy
+
+1. Unit tests for parseId, rate limiter, route params
+2. Playwright setup (install, config, seed, global-setup)
+3. Playwright E2E test files

docs/superpowers/specs/2026-04-03-user-menu-design.md

@@ -0,0 +1,35 @@
+# User Menu Design
+
+## Summary
+
+Replace the plain "Sign out" button in the header with a user icon that opens a dropdown menu containing Settings and Sign out options. This provides a way to navigate to the Settings page from the header.
+
+## Components
+
+### UserMenu (`src/client/components/UserMenu.tsx`)
+
+New component rendered by `TotalsBar` when authenticated.
+
+**Trigger:** Circular `CircleUser` icon button (Lucide). Styled consistently with surrounding header elements.
+
+**Dropdown:** Absolutely-positioned popover anchored to the right edge, appearing below the icon:
+
+1. **Settings** — `Settings` (gear) icon + "Settings" label, `<Link to="/settings">`
+2. **Divider** — thin horizontal line
+3. **Sign out** — `LogOut` icon + "Sign out" label, calls `logout.mutate()` from `useLogout()`
+
+**Behavior:**
+- Click icon toggles open/close
+- Click outside closes (via `useEffect` with document click listener)
+- Clicking a menu item closes the dropdown
+- Dropdown anchored right so it doesn't overflow viewport
+
+### TotalsBar Changes (`src/client/components/TotalsBar.tsx`)
+
+- When `isAuthenticated`: render `<UserMenu />` in place of the current "Sign out" button
+- When not authenticated: keep the existing "Sign in" link unchanged
+- Remove the `useLogout` hook usage from TotalsBar (moved into UserMenu)
+
+## No Backend Changes
+
+The existing `/api/auth/me` endpoint and `useAuth` hook are sufficient. No username display needed — using a generic user icon.

docs/superpowers/specs/2026-04-03-v1.4-collection-tools-design.md

@@ -0,0 +1,114 @@
+# v1.4 Collection Tools Design
+
+**Date:** 2026-04-03
+**Milestone:** v1.4 Collection Tools
+**Scope:** Setup impact preview, item quantity, CSV import/export, item duplication
+
+## Feature 1: Setup Impact Preview
+
+Already fully designed in `.planning/phases/13-setup-impact-preview/`. Two plans exist:
+- **13-01**: Pure `computeImpactDeltas` function + `useImpactDeltas` hook + uiStore state (TDD)
+- **13-02**: `SetupImpactSelector` + `ImpactDeltaBadge` components wired into thread detail
+
+Execute the existing plans as-is. No design changes needed.
+
+## Feature 2: Item Quantity
+
+### Schema
+
+Add `quantity INTEGER NOT NULL DEFAULT 1` to `items` table via Drizzle migration.
+
+```ts
+quantity: integer("quantity").notNull().default(1),
+```
+
+### Validation
+
+Add to `createItemSchema` in `src/shared/schemas.ts`:
+```ts
+quantity: z.number().int().positive().optional(),
+```
+
+Flows to `updateItemSchema` via `.partial()` automatically.
+
+### Service Layer
+
+No special business logic — quantity is a stored field.
+
+**Totals computation changes:**
+- `totals.service.ts`: `getCategoryTotals()` and `getGlobalTotals()` must multiply `weightGrams * quantity` and `priceCents * quantity` in their SQL SUM aggregations.
+- `setup.service.ts`: `getSetupWithItems()` and `getAllSetups()` — when computing setup totals, multiply item weight/price by the item's quantity.
+
+### UI
+
+- **ItemForm**: Number input for quantity (min=1), placed below price field. Defaults to 1.
+- **ItemCard**: Show "x2" badge next to item name when quantity > 1. No badge when quantity is 1.
+- **Totals**: Already computed server-side with the quantity multiplication. No client-side changes for totals.
+- **Setup weight/cost**: The item's quantity determines its weight/cost contribution when included in a setup (one `setup_items` row, but totals reflect quantity).
+
+### Thread Resolution
+
+When a thread is resolved and a candidate is copied to an item, the new item gets `quantity: 1` (default). No special handling needed.
+
+## Feature 3: CSV Import/Export
+
+### Export
+
+**Endpoint:** `GET /api/items/export`
+- Returns CSV with headers: `name,quantity,weightGrams,priceCents,category,notes,productUrl`
+- `Content-Type: text/csv`
+- `Content-Disposition: attachment; filename="gearbox-export.csv"`
+- Weight in grams, price in cents (raw values, no formatting)
+- Category column contains category name (not ID)
+
+**Service:** `exportItemsCsv(db)` returns a CSV string. Joins items with categories for name lookup.
+
+### Import
+
+**Endpoint:** `POST /api/items/import`
+- Accepts multipart form upload (CSV file)
+- Parses rows, validates required fields (name is required, others optional)
+- Category matching: looks up by name (case-insensitive). Creates new category if not found.
+- Quantity defaults to 1 if not present in CSV
+- Returns `{ imported: number, created_categories: string[], errors: string[] }`
+- Skips rows with errors, continues processing remaining rows
+
+**Service:** `importItemsCsv(db, csvContent: string)` parses and inserts items.
+
+### UI
+
+Settings page gets an "Import/Export" section:
+- "Export CSV" button — triggers download via `GET /api/items/export`
+- "Import CSV" file input — accepts .csv files, shows count of parsed rows, confirm button to upload
+- Success/error feedback after import completes
+
+## Feature 4: Item Duplication
+
+### API
+
+**Endpoint:** `POST /api/items/:id/duplicate`
+- Copies all fields from source item: name, weightGrams, priceCents, categoryId, notes, productUrl, imageFilename, imageSourceUrl, quantity
+- Appends " (copy)" to the name
+- New `createdAt`/`updatedAt` timestamps
+- Returns the new item
+
+**Service:** `duplicateItem(db, id)` — fetches source item, inserts copy, returns new item.
+
+### UI
+
+- Add "Duplicate" action to ItemCard (alongside existing edit/delete actions)
+- Duplicating opens the edit panel pre-filled with the new item so the user can rename or adjust
+
+## Phase Ordering
+
+1. **Item Quantity** — schema change first since CSV import/export and totals depend on it
+2. **Setup Impact Preview** — execute existing Phase 13 plans
+3. **Item Duplication** — small, self-contained
+4. **CSV Import/Export** — depends on quantity field existing in schema
+
+## Out of Scope
+
+- Quantity per setup (setup_items.quantity) — items table quantity is sufficient for v1.4
+- CSV export with formatted weights/prices — raw values are more portable
+- Image export/import via CSV — images are local files, not CSV-compatible
+- Bulk edit from CSV preview — import creates, doesn't update existing items

docs/superpowers/specs/2026-04-04-mcp-oauth-design.md

@@ -0,0 +1,182 @@
+# MCP OAuth 2.1 Server Design
+
+**Date:** 2026-04-04
+**Goal:** Add OAuth 2.1 Authorization Code + PKCE support to the MCP server so it works with Claude mobile app and claude.ai remote MCP connectors.
+
+## Context
+
+The GearBox MCP server currently authenticates via `X-API-Key` header. This works for Claude Code (CLI) and scripts, but Claude mobile and claude.ai require OAuth 2.1 for remote MCP server connections. The MCP spec (2025-03-26) defines exactly which OAuth endpoints a server must expose.
+
+This is built against the current single-user auth system (username/password in SQLite). It will be replaced when the platform migrates to an external auth provider in v2.0.
+
+## OAuth Flow
+
+The MCP authorization spec requires OAuth 2.1 Authorization Code + PKCE:
+
+1. Client calls `POST /mcp` -> gets `401 Unauthorized` with `WWW-Authenticate` header
+2. Client fetches `GET /.well-known/oauth-authorization-server` for endpoint discovery
+3. Client calls `POST /oauth/register` (Dynamic Client Registration, RFC 7591) to get a `client_id`
+4. Client opens browser to `GET /oauth/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256&redirect_uri=...`
+5. User sees a login form, enters their GearBox password
+6. Server validates credentials, generates auth code, redirects to `redirect_uri?code=xyz`
+7. Client calls `POST /oauth/token` with `grant_type=authorization_code&code=xyz&code_verifier=...`
+8. Server validates PKCE, returns `{ access_token, refresh_token, token_type, expires_in }`
+9. All subsequent MCP requests use `Authorization: Bearer <access_token>`
+
+## Database Schema
+
+Three new tables in `src/db/schema.ts`:
+
+### `oauthClients`
+Stores dynamically registered OAuth clients (one per Claude instance).
+
+| Column | Type | Notes |
+|--------|------|-------|
+| id | integer PK | Auto-increment |
+| clientId | text, unique | UUID, generated on registration |
+| clientName | text | From registration request, optional |
+| redirectUris | text | JSON array of allowed redirect URIs |
+| createdAt | integer (timestamp) | |
+
+### `oauthCodes`
+Short-lived authorization codes (10 minute TTL).
+
+| Column | Type | Notes |
+|--------|------|-------|
+| id | integer PK | Auto-increment |
+| code | text, unique | Cryptographically random |
+| clientId | text | FK to oauthClients.clientId |
+| codeChallenge | text | PKCE S256 challenge |
+| codeChallengeMethod | text | Always "S256" |
+| redirectUri | text | Must match on token exchange |
+| expiresAt | integer (timestamp) | 10 minutes from creation |
+| used | integer | 0 or 1, prevents replay |
+
+### `oauthTokens`
+Access and refresh tokens.
+
+| Column | Type | Notes |
+|--------|------|-------|
+| id | integer PK | Auto-increment |
+| accessTokenHash | text, unique | SHA-256 hash of token |
+| refreshTokenHash | text, unique | SHA-256 hash of token |
+| clientId | text | FK to oauthClients.clientId |
+| expiresAt | integer (timestamp) | Access token expiry (1 hour) |
+| createdAt | integer (timestamp) | |
+
+No `userId` column -- single-user app, only one user exists. Tokens implicitly belong to them.
+
+## New Files
+
+### `src/server/services/oauth.service.ts`
+Pure business logic, no HTTP awareness. Functions:
+
+- `registerClient(name?, redirectUris)` -> `{ clientId }` - creates client record
+- `getClient(clientId)` -> client record or null
+- `createAuthorizationCode(clientId, codeChallenge, codeChallengeMethod, redirectUri)` -> `{ code }` - generates code, stores in DB
+- `exchangeCode(code, codeVerifier, clientId, redirectUri)` -> `{ accessToken, refreshToken, expiresIn }` - validates PKCE, marks code used, creates tokens
+- `refreshAccessToken(refreshToken, clientId)` -> `{ accessToken, refreshToken, expiresIn }` - rotates refresh token
+- `verifyAccessToken(token)` -> boolean - checks hash against DB, checks expiry
+- `cleanExpiredTokens()` -> void - housekeeping, called opportunistically
+
+PKCE validation: SHA-256 hash the `code_verifier`, base64url-encode it, compare to stored `code_challenge`.
+
+Token generation: `crypto.randomBytes(32).toString('hex')` for both access and refresh tokens. Stored as SHA-256 hashes.
+
+### `src/server/routes/oauth.ts`
+Hono routes mounted at `/oauth` in `src/server/index.ts`:
+
+**`GET /.well-known/oauth-authorization-server`** (mounted at app root, not under `/oauth`)
+Returns RFC 8414 metadata. The issuer URL is derived from the `GEARBOX_URL` environment variable (e.g., `https://gearbox.example.com`), falling back to the request's `Origin` or `Host` header for local development:
+```json
+{
+  "issuer": "<issuer_url>",
+  "authorization_endpoint": "<issuer_url>/oauth/authorize",
+  "token_endpoint": "<issuer_url>/oauth/token",
+  "registration_endpoint": "<issuer_url>/oauth/register",
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "code_challenge_methods_supported": ["S256"],
+  "token_endpoint_auth_methods_supported": ["none"]
+}
+```
+
+**`POST /oauth/register`** (Dynamic Client Registration, RFC 7591)
+Request: `{ client_name?, redirect_uris: string[] }`
+Response: `{ client_id, client_name, redirect_uris }`
+
+**`GET /oauth/authorize`**
+Query params: `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state`
+Validates client_id and redirect_uri, then serves a simple HTML login form.
+
+**`POST /oauth/authorize`**
+Form body: `username`, `password` (plus the OAuth params from the query string, passed as hidden fields)
+Validates credentials via existing `verifyPassword()`. On success, generates auth code and redirects: `302 redirect_uri?code=xyz&state=...`
+On failure, re-renders login form with error message.
+
+**`POST /oauth/token`**
+Handles two grant types:
+- `authorization_code`: validates code, PKCE verifier, redirect_uri, client_id. Returns tokens.
+- `refresh_token`: validates refresh token, rotates it. Returns new tokens.
+
+Response: `{ access_token, refresh_token, token_type: "Bearer", expires_in: 3600 }`
+
+### Login Form
+
+The `/oauth/authorize` GET endpoint serves a minimal HTML login page. Self-contained (inline styles), matches GearBox's clean aesthetic. Shows:
+- GearBox logo/name
+- "Authorize [client_name] to access your GearBox data"
+- Username + password fields
+- "Authorize" button
+- Error message area
+
+This is server-rendered HTML (not React) since it's a standalone page in the OAuth redirect flow.
+
+## Modified Files
+
+### `src/server/mcp/index.ts`
+Update the auth middleware to accept both auth methods:
+
+```
+1. Check Authorization: Bearer <token> -> verify via oauth.service.verifyAccessToken()
+2. Check X-API-Key header -> existing verifyApiKey() flow
+3. No auth found -> return 401 with WWW-Authenticate: Bearer header
+```
+
+The `WWW-Authenticate` header is what triggers the OAuth flow in MCP clients.
+
+### `src/server/index.ts`
+- Mount `/.well-known/oauth-authorization-server` at app root
+- Mount `/oauth` routes
+
+### `src/db/schema.ts`
+Add the 3 new table definitions.
+
+## Token Lifecycle
+
+- **Access tokens:** 1 hour expiry. Validated on every MCP request by hashing and checking DB.
+- **Refresh tokens:** 30 day expiry. Rotated on each use (old token invalidated, new one issued).
+- **Auth codes:** 10 minute expiry. Single-use (marked `used=1` after exchange).
+- **Cleanup:** Expired tokens/codes cleaned up opportunistically during token operations.
+
+## What This Does NOT Include
+
+- **Scopes/permissions:** Single user with full access. No scope restrictions.
+- **Consent screen:** Login = consent. There's only one user authorizing themselves.
+- **Token revocation endpoint:** Not required by MCP spec. Tokens expire naturally.
+- **CORS changes:** OAuth uses browser redirects, not CORS.
+- **Changes to existing API key auth:** Fully preserved, works alongside OAuth.
+
+## Testing
+
+- Unit tests for `oauth.service.ts`: PKCE validation, code exchange, token refresh, expiry
+- Route-level tests for OAuth endpoints: registration, authorize flow, token exchange, error cases
+- Integration: verify Bearer token auth works on MCP endpoint alongside API key auth
+
+## Migration Path
+
+When v2.0 replaces auth with an external OIDC provider:
+- The OAuth tables get dropped (external provider handles tokens)
+- The `/oauth/*` routes get replaced or proxied to the external provider
+- Bearer token validation on `/mcp` switches to JWT verification
+- API key auth stays (it's in the local DB regardless)

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/0004_soft_synch.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `thread_candidates` ADD `pros` text;--> statement-breakpoint
+ALTER TABLE `thread_candidates` ADD `cons` text;

drizzle/0005_clear_micromax.sql

@@ -0,0 +1 @@
+ALTER TABLE `thread_candidates` ADD `sort_order` real DEFAULT 0 NOT NULL;

drizzle/0006_hard_the_professor.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `items` ADD `image_source_url` text;--> statement-breakpoint
+ALTER TABLE `thread_candidates` ADD `image_source_url` text;

drizzle/0007_icy_prodigy.sql

@@ -0,0 +1,23 @@
+CREATE TABLE `api_keys` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`key_hash` text NOT NULL,
+	`key_prefix` text NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` integer NOT NULL,
+	`expires_at` integer NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `users` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`username` text NOT NULL,
+	`password_hash` text NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `users_username_unique` ON `users` (`username`);

drizzle/0008_loving_colossus.sql

@@ -0,0 +1 @@
+ALTER TABLE `items` ADD `quantity` integer DEFAULT 1 NOT NULL;

drizzle/0009_happy_mockingbird.sql

@@ -0,0 +1,33 @@
+CREATE TABLE `oauth_clients` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`client_id` text NOT NULL,
+	`client_name` text,
+	`redirect_uris` text NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_clients_client_id_unique` ON `oauth_clients` (`client_id`);--> statement-breakpoint
+CREATE TABLE `oauth_codes` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`code` text NOT NULL,
+	`client_id` text NOT NULL,
+	`code_challenge` text NOT NULL,
+	`code_challenge_method` text DEFAULT 'S256' NOT NULL,
+	`redirect_uri` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`used` integer DEFAULT 0 NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_codes_code_unique` ON `oauth_codes` (`code`);--> statement-breakpoint
+CREATE TABLE `oauth_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`access_token_hash` text NOT NULL,
+	`refresh_token_hash` text NOT NULL,
+	`client_id` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`refresh_expires_at` integer NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_tokens_access_token_hash_unique` ON `oauth_tokens` (`access_token_hash`);--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_tokens_refresh_token_hash_unique` ON `oauth_tokens` (`refresh_token_hash`);

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/0004_snapshot.json

@@ -0,0 +1,497 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "529d2e93-7d7f-4a83-bb29-254ce09cdef4",
+  "prevId": "628b9ef4-c715-4bbe-a118-042d80fde91e",
+  "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'"
+        },
+        "pros": {
+          "name": "pros",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "cons": {
+          "name": "cons",
+          "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": {
+        "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": {}
+  }
+}