# Requirements Archive: GearBox v2.3 Global & Social Ready

**Archived:** 2026-04-19
**Milestone shipped:** v2.3

> Note: The active REQUIREMENTS.md at close was scoped to v2.1 Public Discovery requirements (all complete).
> v2.3-specific requirements (sharing, currency, i18n) were tracked as decisions in STATE.md and active items in PROJECT.md.

---

# Requirements: GearBox v2.1 Public Discovery

**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.1 Requirements

### Public Access

- [x] **PUBL-01**: User can browse the global item catalog without logging in
- [x] **PUBL-02**: User can view public setups without logging in
- [x] **PUBL-03**: User can view user profiles without logging in
- [x] **PUBL-04**: Anonymous visitors see the landing page without auth spinner or redirect
- [x] **PUBL-05**: Login is only required when user attempts to create/edit/delete their own data

### Discovery

- [x] **DISC-01**: Landing page displays an always-visible catalog search bar at the top
- [x] **DISC-02**: Landing page shows a feed of popular setups below the search
- [x] **DISC-03**: Landing page shows recently added catalog items
- [x] **DISC-04**: Landing page shows trending categories
- [x] **DISC-05**: Authenticated users see a "Go to Collection" entry point from the landing page

### Catalog Enrichment

- [x] **CATL-01**: Global items have attribution fields (sourceUrl, manufacturer, imageCredit, imageSourceUrl)
- [x] **CATL-02**: Global items have a unique constraint on (brand, model) preventing duplicates
- [x] **CATL-03**: Catalog detail pages display image attribution with credit and source link
- [x] **CATL-04**: Bulk import API endpoint accepts multiple catalog items in one request
- [x] **CATL-05**: Bulk import uses upsert semantics (ON CONFLICT update, not fail)

### Agent Seeding Tools

- [x] **SEED-01**: MCP server has a dedicated `upsert_catalog_item` tool that writes to globalItems (not user-scoped)
- [x] **SEED-02**: MCP server has a `bulk_upsert_catalog` tool for batch catalog population
- [x] **SEED-03**: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters

### Infrastructure

- [x] **INFR-01**: Public API endpoints are rate-limited to prevent abuse
- [x] **INFR-02**: Discovery feed endpoint uses cursor pagination for scalability

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| PUBL-01 | Phase 24 | Complete |
| PUBL-02 | Phase 24 | Complete |
| PUBL-03 | Phase 24 | Complete |
| PUBL-04 | Phase 24 | Complete |
| PUBL-05 | Phase 24 | Complete |
| INFR-01 | Phase 24 | Complete |
| CATL-01 | Phase 25 | Complete |
| CATL-02 | Phase 25 | Complete |
| CATL-03 | Phase 25 | Complete |
| CATL-04 | Phase 25 | Complete |
| CATL-05 | Phase 25 | Complete |
| SEED-01 | Phase 25 | Complete |
| SEED-02 | Phase 25 | Complete |
| SEED-03 | Phase 25 | Complete |
| DISC-01 | Phase 26 | Complete |
| DISC-02 | Phase 26 | Complete |
| DISC-03 | Phase 26 | Complete |
| DISC-04 | Phase 26 | Complete |
| DISC-05 | Phase 26 | Complete |
| INFR-02 | Phase 26 | Complete |

**Coverage:** 20/20 v2.1 requirements complete.