docs: define milestone v2.1 requirements

.planning/REQUIREMENTS.md

@@ -1,114 +1,91 @@
-# Requirements: GearBox v2.0 Platform Foundation
+# Requirements: GearBox v2.1 Public Discovery
 
-**Defined:** 2026-04-03
+**Defined:** 2026-04-09
 **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
+## v2.1 Requirements
 
-Requirements for this milestone. Each maps to roadmap phases.
+Requirements for Public Discovery milestone. Each maps to roadmap phases.
 
-### Database Migration
+### Public Access
 
-- [x] **DB-01**: Application runs on PostgreSQL instead of SQLite
+- [ ] **PUBL-01**: User can browse the global item catalog without logging in
-- [x] **DB-02**: All service functions use async database operations
+- [ ] **PUBL-02**: User can view public setups without logging in
-- [x] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
+- [ ] **PUBL-03**: User can view user profiles without logging in
-- [x] **DB-04**: Existing SQLite data can be migrated to Postgres via a one-time script
+- [ ] **PUBL-04**: Anonymous visitors see the landing page without auth spinner or redirect
-- [x] **DB-05**: Docker Compose provides Postgres for local development
+- [ ] **PUBL-05**: Login is only required when user attempts to create/edit/delete their own data
 
-### Authentication
+### Discovery
 
-- [x] **AUTH-01**: User can register an account via external OIDC auth provider
+- [ ] **DISC-01**: Landing page displays an always-visible catalog search bar at the top
-- [x] **AUTH-02**: User can log in via external auth provider and access their data
+- [ ] **DISC-02**: Landing page shows a feed of popular setups below the search
-- [x] **AUTH-03**: API keys remain functional for programmatic access (MCP, scripts)
+- [ ] **DISC-03**: Landing page shows recently added catalog items
-- [x] **AUTH-04**: Auth provider runs self-hosted alongside the application
+- [ ] **DISC-04**: Landing page shows trending categories
-- [x] **AUTH-05**: E2E tests authenticate via API keys without depending on the auth provider
+- [ ] **DISC-05**: Authenticated users see a "Go to Collection" entry point from the landing page
 
-### Multi-User Data Model
+### Catalog Enrichment
 
-- [x] **MULTI-01**: Every item, category, thread, and setup is owned by a specific user
+- [ ] **CATL-01**: Global items have attribution fields (sourceUrl, manufacturer, imageCredit, imageSourceUrl)
-- [x] **MULTI-02**: User can only see and modify their own data (cross-user isolation)
+- [ ] **CATL-02**: Global items have a unique constraint on (brand, model) preventing duplicates
-- [x] **MULTI-03**: Categories use composite unique constraint (userId + name)
+- [ ] **CATL-03**: Catalog detail pages display image attribution with credit and source link
-- [x] **MULTI-04**: Existing data is assigned to the original user during migration
+- [ ] **CATL-04**: Bulk import API endpoint accepts multiple catalog items in one request
-- [x] **MULTI-05**: MCP tools operate within the authenticated user's scope
+- [ ] **CATL-05**: Bulk import uses upsert semantics (ON CONFLICT update, not fail)
-- [x] **MULTI-06**: Settings are per-user rather than global
 
-### Image Storage
+### Agent Seeding Tools
 
-- [x] **IMG-01**: Images are stored in MinIO (S3-compatible) instead of local filesystem
+- [ ] **SEED-01**: MCP server has a dedicated `upsert_catalog_item` tool that writes to globalItems (not user-scoped)
-- [x] **IMG-02**: Existing uploaded images are migrated to MinIO
+- [ ] **SEED-02**: MCP server has a `bulk_upsert_catalog` tool for batch catalog population
-- [x] **IMG-03**: Image upload and retrieval work through the new storage layer
+- [ ] **SEED-03**: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters
-- [x] **IMG-04**: Docker Compose provides MinIO for local development
 
-### Global Item Database
+### Infrastructure
 
-- [x] **GLOB-01**: A global item catalog exists with brand, model, category, manufacturer specs, and image
+- [ ] **INFR-01**: Public API endpoints are rate-limited to prevent abuse
-- [x] **GLOB-02**: Global catalog is seeded with initial items from manufacturer data
+- [ ] **INFR-02**: Discovery feed endpoint uses cursor pagination for scalability
-- [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 (category, notes, purchase price, image, quantity)
-- [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`) showing all item data
-- [x] **DETAIL-02**: Clicking a catalog search result navigates to a public detail page (`/global-items/:id`) with "Add to Collection" button
-- [x] **DETAIL-03**: Item detail page has edit mode toggle for modifying personal fields (notes, category, quantity, purchase price)
-- [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
 
 ## Future Requirements
 
 Deferred to future milestones. Tracked but not in current roadmap.
 
-### Reviews & Ratings
+### Personalization
+
+- **PERS-01**: Logged-in users see a feed tuned to their collection categories
+- **PERS-02**: Feed algorithm recommends content based on user's hobby interests
+
+### Reviews & Content
+
+- **REVW-01**: Users can write structured reviews on catalog items
+- **REVW-02**: Reviews appear in the discovery feed
+- **REVW-03**: Curated/linked external reviews surface in feed
+
+### SEO
+
+- **SEO-01**: Catalog pages are crawlable by search engine bots
+- **SEO-02**: Catalog pages have proper meta tags and structured data
+
+### Catalog Seeding
+
+- **SEED-04**: Initial seeding run populates 100+ items across key categories via agent swarm
+
+### Reviews & Ratings (from v2.0)
 
 - **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
+### Aggregation (from v2.0)
-
-- **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
+### Social (from v2.0)
 
 - **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
+### Content Moderation (from v2.0)
 
 - **MOD-01**: User can submit freeform text reviews
 - **MOD-02**: User can report inappropriate content
@@ -120,19 +97,18 @@ Explicitly excluded. Documented to prevent scope creep.
 
 | Feature | Reason |
 |---------|--------|
-| Freeform text reviews | Requires moderation infrastructure not yet built |
+| Personalized feed algorithm | Requires usage data and collection analysis — build simple feed first |
-| Comments on setups | Moderation burden, notification system needed |
+| SSR / static prerendering for SEO | Needs dedicated research on approach for TanStack Router — defer to v2.2+ |
+| Freeform reviews / comments | No moderation infrastructure yet — structured UGC only |
+| Admin role / permission system | Current auth model has no role distinction — API key sufficient for v2.1 |
+| Image scraping automation | Legal gray area — agent seeding uses manufacturer-provided images with attribution |
 | 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
 
@@ -140,57 +116,32 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| DB-01 | Phase 14 | Complete |
+| PUBL-01 | — | Pending |
-| DB-02 | Phase 14 | Complete |
+| PUBL-02 | — | Pending |
-| DB-03 | Phase 14 | Complete |
+| PUBL-03 | — | Pending |
-| DB-04 | Phase 14 | Complete |
+| PUBL-04 | — | Pending |
-| DB-05 | Phase 14 | Complete |
+| PUBL-05 | — | Pending |
-| AUTH-01 | Phase 15 | Complete |
+| DISC-01 | — | Pending |
-| AUTH-02 | Phase 15 | Complete |
+| DISC-02 | — | Pending |
-| AUTH-03 | Phase 15 | Complete |
+| DISC-03 | — | Pending |
-| AUTH-04 | Phase 15 | Complete |
+| DISC-04 | — | Pending |
-| AUTH-05 | Phase 15 | Complete |
+| DISC-05 | — | Pending |
-| MULTI-01 | Phase 16 | Complete |
+| CATL-01 | — | Pending |
-| MULTI-02 | Phase 16 | Complete |
+| CATL-02 | — | Pending |
-| MULTI-03 | Phase 16 | Complete |
+| CATL-03 | — | Pending |
-| MULTI-04 | Phase 16 | Complete |
+| CATL-04 | — | Pending |
-| MULTI-05 | Phase 16 | Complete |
+| CATL-05 | — | Pending |
-| MULTI-06 | Phase 16 | Complete |
+| SEED-01 | — | Pending |
-| IMG-01 | Phase 17 | Complete |
+| SEED-02 | — | Pending |
-| IMG-02 | Phase 17 | Complete |
+| SEED-03 | — | Pending |
-| IMG-03 | Phase 17 | Complete |
+| INFR-01 | — | Pending |
-| IMG-04 | Phase 17 | Complete |
+| INFR-02 | — | Pending |
-| 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
+- v2.1 requirements: 20 total
-- Mapped to phases: 45
+- Mapped to phases: 0
-- Unmapped: 0
+- Unmapped: 20
 
 ---
-*Requirements defined: 2026-04-03*
+*Requirements defined: 2026-04-09*
-*Last updated: 2026-04-08 — all v2.0 requirements complete*
+*Last updated: 2026-04-09 after initial definition*