docs: start milestone v2.0 Platform Foundation

.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, search and filter by name or category, and use planning threads to research and compare new purchases with status tracking. Named setups let users compose loadouts with weight classification (base/worn/consumable), donut chart visualization, and live totals in selectable units. Built as a single-user app with a clean, minimalist interface.
+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
 
@@ -42,45 +42,58 @@ Make it effortless to manage gear and plan new purchases — see how a potential
 
 ### Active
 
-## Current Milestone: v1.3 Research & Decision Tools
+## Current Milestone: v2.0 Platform Foundation
 
-**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.
+**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:**
-- Full-detail side-by-side candidate comparison (weight, price, images, notes, links, status)
+- External auth provider (self-hosted, open-source) for multi-user registration
-- Impact preview: pick a setup, see +/- weight and cost delta for each candidate
+- Migrate from SQLite to Postgres
-- Candidate ranking (drag-to-reorder) with pros/cons text fields per candidate
+- 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
 
-- [ ] CSV import/export for gear collections
+- [ ] Freeform reviews with moderation system
-- [ ] Multi-user accounts with authentication
+- [ ] Comments on setups
-- [ ] Collection sharing and social features (public profiles, shared setups)
+- [ ] Follow users / activity feeds
-- [ ] Auto-fill product information (price, weight, images) from external sources
+- [ ] OAuth / social login providers
+- [ ] User-to-user messaging
 
 ### Out of Scope
 
 - Custom comparison parameters — complexity trap, weight/price covers 80% of cases
 - Mobile native app — web-first, responsive design sufficient
 - Price tracking / deal alerts — requires scraping, fragile
-- Barcode scanning / product database — requires external database
+- Barcode scanning — poor UX, manual entry is fine with global database
-- Community gear database — requires moderation, accounts
 - 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.2 with 7,310 LOC TypeScript. Starting v1.3 to enhance thread decision workflow.
+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, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, all on Bun.
+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.
-121 tests (service-level and route-level integration).
+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**: Single user with cookie/API key auth
+- **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
 
@@ -105,6 +118,12 @@ 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 |
@@ -115,5 +134,22 @@ Replaces spreadsheet-based gear tracking workflow.
 | 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-16 after v1.3 milestone start*
+*Last updated: 2026-04-03 after v2.0 milestone start*

.planning/STATE.md

@@ -1,16 +1,16 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.3
+milestone: v2.0
-milestone_name: Research & Decision Tools
+milestone_name: Platform Foundation
 status: planning
-stopped_at: Completed 12-comparison-view/12-01-PLAN.md
+stopped_at: null
-last_updated: "2026-03-17T14:35:39.075Z"
+last_updated: "2026-04-03"
-last_activity: 2026-03-16 — Roadmap created for v1.3 milestone
+last_activity: 2026-04-03 — Milestone v2.0 started
 progress:
-  total_phases: 4
+  total_phases: 0
-  completed_phases: 3
+  completed_phases: 0
-  total_plans: 4
+  total_plans: 0
-  completed_plans: 4
+  completed_plans: 0
   percent: 0
 ---
 
@@ -18,19 +18,17 @@ progress:
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-03-16)
+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.
+**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:** v1.3 Research & Decision Tools — Phase 10 ready to plan
+**Current focus:** v2.0 Platform Foundation — Defining requirements
 
 ## Current Position
 
-Phase: 10 of 13 (Schema Foundation + Pros/Cons Fields)
+Phase: Not started (defining requirements)
 Plan: —
-Status: Ready to plan
+Status: Defining requirements
-Last activity: 2026-03-16 — Roadmap created for v1.3 milestone
+Last activity: 2026-04-03 — Milestone v2.0 started
-
-Progress: [░░░░░░░░░░] 0%
 
 ## Performance Metrics
 
@@ -39,43 +37,19 @@ Progress: [░░░░░░░░░░] 0%
 - Average duration: —
 - Total execution time: —
 
-**By Phase:**
-
-| Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
-| - | - | - | - |
-
-**Recent Trend:**
-- Last 5 plans: —
-- Trend: —
-
 *Updated after each plan completion*
-| Phase 10-schema-foundation-pros-cons-fields P01 | 6min | 2 tasks | 9 files |
-| Phase 11-candidate-ranking P01 | 4min | 2 tasks | 8 files |
-| Phase 11-candidate-ranking P02 | 4min | 3 tasks | 7 files |
-| Phase 12-comparison-view P01 | 2min | 2 tasks | 3 files |
 
 ## Accumulated Context
 
 ### Decisions
 
-Cleared at milestone boundary. v1.2 decisions archived in milestones/v1.2-ROADMAP.md.
+Key decisions made during v2.0 planning:
-
+- Platform pivot: single-user → multi-user with discovery-first approach
-Key v1.3 research findings (see research/SUMMARY.md):
+- External auth provider (self-hosted, open-source) — avoid in-house auth burden
-- framer-motion@12.37.0 (already installed) handles drag-to-reorder via Reorder component — no new deps
+- SQLite → Postgres migration — multi-user concurrency + auth provider dependency
-- sort_order must use REAL (float) type, not INTEGER, to avoid bulk writes on every drag
+- Structured UGC only — ratings and predefined fields, no freeform text until moderation exists
-- Impact preview must distinguish add-mode vs replace-mode by category match — pure addition misleads
+- Global item database seeded from manufacturer data, enriched by user contributions
-- [Phase 10-schema-foundation-pros-cons-fields]: Empty string for pros/cons stored as-is (not normalized to null); test accepts either empty string or null as cleared state
+- Single-user SQLite mode diverges at v2.0 boundary
-- [Phase 10-schema-foundation-pros-cons-fields]: Pros/Cons badge uses purple color to distinguish from weight (blue), price (green), category (gray), and status badges
-- [Phase 10-schema-foundation-pros-cons-fields]: Field-addition ladder pattern: schema -> migration -> test helper -> service -> Zod -> types -> hook -> form -> card indicator
-- [Phase 11-candidate-ranking]: sortOrder uses REAL type for future fractional midpoint insertions without bulk rewrites
-- [Phase 11-candidate-ranking]: 1000-gap sort_order strategy: first=1000, append=max+1000, reorder resets to (index+1)*1000
-- [Phase 11-candidate-ranking]: Applied sort_order migration via sqlite3 CLI directly to avoid Drizzle data-loss warning on existing rows
-- [Phase 11-candidate-ranking]: Resolved thread list view uses plain div (not Reorder.Group) — no drag, rank badges visible
-- [Phase 11-candidate-ranking]: RankBadge exported from CandidateListItem for reuse in CandidateCard grid view
-- [Phase 12-comparison-view]: ATTRIBUTE_ROWS declarative array pattern for ComparisonTable keeps JSX clean and row reordering trivial
-- [Phase 12-comparison-view]: Compare toggle only shown for 2+ candidates; Add Candidate hidden in compare view (read-only intent)
-- [Phase 12-comparison-view]: Weight/price highlight color takes priority over amber winner tint when both apply (more informative)
 
 ### Pending Todos
 
@@ -87,6 +61,6 @@ None active.
 
 ## Session Continuity
 
-Last session: 2026-03-17T14:32:04.702Z
+Last session: 2026-04-03
-Stopped at: Completed 12-comparison-view/12-01-PLAN.md
+Stopped at: Defining requirements for v2.0
 Resume file: None