docs: archive v1.3 and v2.0 milestones with roadmap, requirements, and retrospective

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

@@ -0,0 +1,59 @@
+# Requirements Archive: v1.3 Research & Decision Tools
+
+**Archived:** 2026-04-08
+**Status:** SHIPPED
+
+---
+
+## v1.3 Requirements
+
+Requirements for this milestone. Each maps to roadmap phases 10-13.
+
+### Candidate Ranking
+
+- [x] **RANK-01**: User can drag a candidate card to a new position within the thread's candidate list
+- [x] **RANK-02**: The reordered sequence persists after navigating away and returning
+- [x] **RANK-03**: Database schema supports pros/cons fields and sort ordering for candidates
+- [x] **RANK-04**: Top three candidates display gold, silver, and bronze rank badges
+- [x] **RANK-05**: Drag handles and rank badges are absent on resolved threads
+
+### Comparison
+
+- [x] **COMP-01**: User can toggle a "Compare" mode to reveal a tabular view of all candidates
+- [x] **COMP-02**: Lightest candidate is highlighted with weight deltas shown for all others
+- [x] **COMP-03**: Cheapest candidate is highlighted with price deltas shown for all others
+- [x] **COMP-04**: Comparison table scrolls horizontally on narrow viewports with fixed label column
+
+### Setup Impact Preview
+
+- [x] **IMPC-01**: User can select a setup and see weight/cost deltas on each candidate
+- [x] **IMPC-02**: Delta reflects replacement when setup has an item in the same category
+- [x] **IMPC-03**: Pure addition is clearly labeled when no category match exists
+- [x] **IMPC-04**: Candidates without weight data show a "no weight data" indicator
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| RANK-01 | Phase 11 | Complete |
+| RANK-02 | Phase 11 | Complete |
+| RANK-03 | Phase 10 | Complete |
+| RANK-04 | Phase 11 | Complete |
+| RANK-05 | Phase 11 | Complete |
+| COMP-01 | Phase 12 | Complete |
+| COMP-02 | Phase 12 | Complete |
+| COMP-03 | Phase 12 | Complete |
+| COMP-04 | Phase 12 | Complete |
+| IMPC-01 | Phase 13 | Complete |
+| IMPC-02 | Phase 13 | Complete |
+| IMPC-03 | Phase 13 | Complete |
+| IMPC-04 | Phase 13 | Complete |
+
+**Coverage:**
+- v1.3 requirements: 13 total
+- Mapped to phases: 13
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-16*
+*Archived: 2026-04-08*

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

@@ -0,0 +1,62 @@
+# Roadmap Archive: v1.3 Research & Decision Tools
+
+**Archived:** 2026-04-08
+**Status:** SHIPPED
+**Phases:** 10-13 (4 phases, 6 plans)
+**Timeline:** 2026-03-16 to 2026-04-08
+
+---
+
+## 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:
+- [x] 11-01-PLAN.md — Schema migration, reorder service/route, sort_order persistence + tests
+- [x] 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:
+- [x] 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/2 plans complete
+Plans:
+- [x] 13-01-PLAN.md — TDD pure impact delta computation, uiStore state, ThreadWithCandidates type fix, useImpactDeltas hook
+- [x] 13-02-PLAN.md — SetupImpactSelector + ImpactDeltaBadge components, wire into thread detail and all candidate views

.planning/milestones/v2.0-REQUIREMENTS.md

@@ -0,0 +1,145 @@
+# Requirements Archive: v2.0 Platform Foundation
+
+**Archived:** 2026-04-08
+**Status:** SHIPPED
+
+---
+
+# 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
+
+### Database Migration
+
+- [x] **DB-01**: Application runs on PostgreSQL instead of SQLite
+- [x] **DB-02**: All service functions use async database operations
+- [x] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
+- [x] **DB-04**: Existing SQLite data can be migrated to Postgres via a one-time script
+- [x] **DB-05**: Docker Compose provides Postgres for local development
+
+### Authentication
+
+- [x] **AUTH-01**: User can register an account via external OIDC auth provider
+- [x] **AUTH-02**: User can log in via external auth provider and access their data
+- [x] **AUTH-03**: API keys remain functional for programmatic access (MCP, scripts)
+- [x] **AUTH-04**: Auth provider runs self-hosted alongside the application
+- [x] **AUTH-05**: E2E tests authenticate via API keys without depending on the auth provider
+
+### Multi-User Data Model
+
+- [x] **MULTI-01**: Every item, category, thread, and setup is owned by a specific user
+- [x] **MULTI-02**: User can only see and modify their own data (cross-user isolation)
+- [x] **MULTI-03**: Categories use composite unique constraint (userId + name)
+- [x] **MULTI-04**: Existing data is assigned to the original user during migration
+- [x] **MULTI-05**: MCP tools operate within the authenticated user's scope
+- [x] **MULTI-06**: Settings are per-user rather than global
+
+### Image Storage
+
+- [x] **IMG-01**: Images are stored in MinIO (S3-compatible) instead of local filesystem
+- [x] **IMG-02**: Existing uploaded images are migrated to MinIO
+- [x] **IMG-03**: Image upload and retrieval work through the new storage layer
+- [x] **IMG-04**: Docker Compose provides MinIO for local development
+
+### Global Item Database
+
+- [x] **GLOB-01**: A global item catalog exists with brand, model, category, manufacturer specs, and image
+- [x] **GLOB-02**: Global catalog is seeded with initial items from manufacturer data
+- [x] **GLOB-03**: User can search the global catalog by name or brand
+- [x] **GLOB-04**: User can link a personal collection item to a global catalog entry
+- [x] **GLOB-05**: Global item pages show basic info and owner count
+
+### Catalog-Driven Gear Flow
+
+- [x] **CATFLOW-01**: FAB shows mini menu with "Add to Collection" and "Start Thread" globally, plus "New Setup" on setups page
+- [x] **CATFLOW-02**: Full-screen catalog search with tag chip filtering
+- [x] **CATFLOW-03**: User can add a catalog item to collection as a reference item with personal fields
+- [x] **CATFLOW-04**: Collection items referencing global items display merged data (global base + personal overlay)
+- [x] **CATFLOW-05**: Thread candidates can be added from catalog with global item link
+- [x] **CATFLOW-06**: Thread resolution with catalog-linked candidate creates reference item with auto-link
+- [x] **CATFLOW-07**: Manual entry fallback when item not in catalog
+- [x] **CATFLOW-08**: Non-functional "Submit to catalog?" prompt shown after manual save
+
+### Item & Catalog Detail Pages
+
+- [x] **DETAIL-01**: Clicking a collection item navigates to a full detail page (`/items/:id`)
+- [x] **DETAIL-02**: Clicking a catalog search result navigates to a public detail page (`/global-items/:id`)
+- [x] **DETAIL-03**: Item detail page has edit mode toggle for modifying personal fields
+- [x] **DETAIL-04**: Thread candidates navigate to detail pages instead of opening slide-out panels
+- [x] **DETAIL-05**: Slide-out panels for items and candidates are removed from the application
+
+### Tags
+
+- [x] **TAG-01**: Tags table seeded with curated tag set for outdoor/adventure gear
+- [x] **TAG-02**: Global items have multiple tags, searchable and filterable via API
+
+### User Profiles & Sharing
+
+- [x] **PROF-01**: User has a profile with display name, avatar, and bio
+- [x] **PROF-02**: User can view their own public profile page
+- [x] **PROF-03**: User can set a setup as public or private
+- [x] **PROF-04**: Public setups are viewable by anyone without authentication
+- [x] **PROF-05**: Public profile page lists the user's public setups
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DB-01 | Phase 14 | Complete |
+| DB-02 | Phase 14 | Complete |
+| DB-03 | Phase 14 | Complete |
+| DB-04 | Phase 14 | Complete |
+| DB-05 | Phase 14 | Complete |
+| AUTH-01 | Phase 15 | Complete |
+| AUTH-02 | Phase 15 | Complete |
+| AUTH-03 | Phase 15 | Complete |
+| AUTH-04 | Phase 15 | Complete |
+| AUTH-05 | Phase 15 | Complete |
+| MULTI-01 | Phase 16 | Complete |
+| MULTI-02 | Phase 16 | Complete |
+| MULTI-03 | Phase 16 | Complete |
+| MULTI-04 | Phase 16 | Complete |
+| MULTI-05 | Phase 16 | Complete |
+| MULTI-06 | Phase 16 | Complete |
+| IMG-01 | Phase 17 | Complete |
+| IMG-02 | Phase 17 | Complete |
+| IMG-03 | Phase 17 | Complete |
+| IMG-04 | Phase 17 | Complete |
+| GLOB-01 | Phase 18 | Complete |
+| GLOB-02 | Phase 18 | Complete |
+| GLOB-03 | Phase 18 | Complete |
+| GLOB-04 | Phase 18 | Complete |
+| GLOB-05 | Phase 18 | Complete |
+| PROF-01 | Phase 18 | Complete |
+| PROF-02 | Phase 18 | Complete |
+| PROF-03 | Phase 18 | Complete |
+| PROF-04 | Phase 18 | Complete |
+| PROF-05 | Phase 18 | Complete |
+| CATFLOW-01 | Phase 20 | Complete |
+| CATFLOW-02 | Phase 20 | Complete |
+| CATFLOW-03 | Phase 19, 22 | Complete |
+| CATFLOW-04 | Phase 19 | Complete |
+| CATFLOW-05 | Phase 19, 22 | Complete |
+| CATFLOW-06 | Phase 19, 22 | Complete |
+| CATFLOW-07 | Phase 23 | Complete |
+| CATFLOW-08 | Phase 23 | Complete |
+| TAG-01 | Phase 19 | Complete |
+| TAG-02 | Phase 19 | Complete |
+| DETAIL-01 | Phase 21 | Complete |
+| DETAIL-02 | Phase 21 | Complete |
+| DETAIL-03 | Phase 21 | Complete |
+| DETAIL-04 | Phase 21 | Complete |
+| DETAIL-05 | Phase 21 | Complete |
+
+**Coverage:**
+- v2.0 requirements: 45 total
+- Mapped to phases: 45
+- Complete: 45
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-04-03*
+*Archived: 2026-04-08*

.planning/milestones/v2.0-ROADMAP.md

@@ -0,0 +1,121 @@
+# Roadmap Archive: v2.0 Platform Foundation
+
+**Archived:** 2026-04-08
+**Status:** SHIPPED
+**Phases:** 14-23 (10 phases, 32 plans)
+**Timeline:** 2026-03-17 to 2026-04-08
+
+---
+
+## 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:** 6/6 plans complete
+
+## 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:** 3/3 plans complete
+
+## 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:** 4/4 plans complete
+
+## 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:** 3/3 plans complete
+
+## 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:** 5/5 plans complete
+
+## Phase 19: Reference Item Model & Tags Schema
+**Goal**: Collection items can be references to global catalog entries, and global items support tags for discovery
+**Depends on**: Phase 18
+**Requirements**: CATFLOW-03, CATFLOW-04, CATFLOW-05, CATFLOW-06, TAG-01, TAG-02
+**Success Criteria** (what must be TRUE):
+  1. A collection item can reference a global item and displays merged data (global base + personal fields)
+  2. Global items can have multiple tags, searchable via API
+  3. Thread candidates can link to a global item via globalItemId
+  4. Resolving a thread with a catalog-linked candidate creates a reference item with auto-link
+**Plans:** 3/3 plans complete
+
+## Phase 20: FAB & Full-Screen Catalog Search
+**Goal**: Users discover and add gear through a catalog-first search experience with tag filtering
+**Depends on**: Phase 19
+**Requirements**: CATFLOW-01, CATFLOW-02
+**Success Criteria** (what must be TRUE):
+  1. FAB visible on all pages with mini menu showing "Add to Collection" and "Start Thread"
+  2. "New Setup" option appears in FAB on setups page only
+  3. Full-screen catalog search overlay opens from either add option
+  4. Search results display catalog items with name, weight, price, owner count
+  5. Tag chips filter search results
+**Plans:** 2/2 plans complete
+
+## Phase 21: Item & Catalog Detail Pages
+**Goal**: Collection items and catalog entries have full detail pages, replacing the slide-out panel pattern
+**Depends on**: Phase 20
+**Requirements**: DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04, DETAIL-05
+**Success Criteria** (what must be TRUE):
+  1. Clicking a collection item card navigates to `/items/:id` showing full item details with edit toggle
+  2. Clicking a catalog search result card navigates to `/global-items/:id` showing public catalog details with "Add to Collection" button
+  3. Thread candidates navigate to detail pages instead of opening slide-out panels
+  4. Item slide-out panel and candidate slide-out panel are removed from the root layout
+  5. No visual distinction between reference items and standalone items — same layout, some fields may be empty
+**Plans:** 3/3 plans complete
+
+## Phase 22: Add-from-Catalog & Thread Integration
+**Goal**: Users can add catalog items to their collection and to threads directly from search
+**Depends on**: Phase 21
+**Requirements**: CATFLOW-03, CATFLOW-05, CATFLOW-06
+**Success Criteria** (what must be TRUE):
+  1. User can add a catalog item to collection with one confirmation step (category picker + notes)
+  2. User can add catalog items as thread candidates instantly from search
+  3. Resolving a catalog-linked candidate creates a properly linked reference item in collection
+**Plans:** 2/2 plans complete
+
+## Phase 23: Manual Entry Fallback
+**Goal**: Users can still add items not found in the catalog via manual entry
+**Depends on**: Phase 22
+**Requirements**: CATFLOW-07, CATFLOW-08
+**Success Criteria** (what must be TRUE):
+  1. User can fall back to manual entry from catalog search via "Add Manually" link
+  2. Manual entry saves a standalone collection item (no globalItemId)
+  3. "Submit to catalog?" prompt appears after manual save but takes no backend action
+**Plans:** 1/1 plans complete