docs: start milestone v2.4 Admin Foundation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.planning/PROJECT.md

@@ -8,6 +8,14 @@ A gear management and discovery platform. Users catalog their gear collections (
 
 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 Milestone: v2.4 Admin Foundation
+
+**Goal:** Clear the v2.3 bug backlog and ship a catalog admin panel as the foundation for managing global catalog content in future milestones.
+
+**Target features:**
+- Bug fixes: wrong add-candidate modal, missing item images on collection overview, slow image loading, auth prompt direct Logto redirect, cursor-pointer on all clickable elements
+- Catalog admin panel: admin-gated route, global item management (browse/edit/delete), tag management (create/rename/parent-child hierarchy/delete), admin role flag on users
+
 ## Requirements
 
 ### Validated
@@ -72,14 +80,22 @@ Help people make better gear decisions — discover what others use, compare rea
 - ✓ Community price aggregation: ownership-validated submissions, median with 3-report minimum, market-aware MSRP on catalog detail — v2.3
 - ✓ i18n foundation: react-i18next, 7 namespaces, English + German translations, language picker, locale-aware formatting — v2.3
 
-### Active
+### Active (v2.4)
 
-- [ ] Freeform reviews with moderation system
-- [ ] Comments on setups
-- [ ] Follow users / activity feeds
+- [ ] Fix wrong modal on Add Candidate button (thread page) — v2.4
+- [ ] Fix item images not showing on collection overview — v2.4
+- [ ] Resolve slow image loading — v2.4
+- [ ] Auth prompt sign-in redirects directly to Logto — v2.4
+- [ ] Cursor pointer on all clickable/interactive elements — v2.4
+- [ ] Admin role flag on users table — v2.4
+- [ ] Admin-gated /admin panel route — v2.4
+- [ ] Admin: browse/edit/delete global catalog items — v2.4
+- [ ] Admin: create/rename/delete tags with parent-child hierarchy — v2.4
 
 ### Future
 
+- [ ] Tag-based spec schemas on global items (key/value typed specs per category, sub-tag hierarchy) — v2.5
+- [ ] Global item engagement stats (view count, likes/saves, setup appearances) — v2.5
 - [ ] Freeform reviews with moderation system
 - [ ] Comments on setups
 - [ ] Follow users / activity feeds
@@ -188,4 +204,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-04-19 after v2.3 milestone — Global & Social Ready*
+*Last updated: 2026-04-19 after v2.4 milestone start — Admin Foundation*

.planning/REQUIREMENTS.md

@@ -0,0 +1,95 @@
+# Requirements: GearBox v2.4
+
+**Defined:** 2026-04-19
+**Milestone:** v2.4 Admin Foundation
+**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.4 Requirements
+
+### Bug Fixes
+
+- [ ] **FIX-01**: User clicking "Add Candidate" on a thread page opens the add-candidate modal (not the wrong modal)
+- [ ] **FIX-02**: Item images display correctly on collection overview cards (no broken/missing images)
+- [ ] **FIX-03**: Catalog and collection images load without noticeable delay (slow image loading resolved)
+- [ ] **FIX-04**: Clicking the sign-in button on an auth prompt redirects the user directly to the Logto login page
+- [ ] **FIX-05**: All clickable and interactive elements show a pointer cursor on hover throughout the app
+
+### Admin Role
+
+- [ ] **ROLE-01**: The users table has an isAdmin boolean flag that identifies admin users
+- [ ] **ROLE-02**: Admin can set another user's isAdmin flag via a server-side mechanism (CLI or seed, not public UI)
+
+### Admin Panel — Global Items
+
+- [ ] **ADMN-01**: Admin user can navigate to an /admin route that is inaccessible to non-admin users
+- [ ] **ADMN-02**: Admin can browse all global catalog items with search and tag filtering
+- [ ] **ADMN-03**: Admin can edit a global catalog item's details (name, brand, model, weight, price, tags, image, attribution fields)
+- [ ] **ADMN-04**: Admin can delete a global catalog item from the catalog (with confirmation)
+
+### Admin Panel — Tag Management
+
+- [ ] **ADMN-05**: Admin can browse all tags with item counts and parent/child relationships displayed
+- [ ] **ADMN-06**: Admin can create a new tag with a name
+- [ ] **ADMN-07**: Admin can rename an existing tag
+- [ ] **ADMN-08**: Admin can assign a parent tag to a tag (enabling sub-tag hierarchy, e.g. "down" under "sleeping-bag")
+- [ ] **ADMN-09**: Admin can remove a tag's parent assignment (making it a top-level tag again)
+- [ ] **ADMN-10**: Admin can delete a tag, with a warning if items are currently using it
+
+## Future Requirements (v2.5+)
+
+### Catalog Spec System
+
+- **SPEC-01**: Tags can have typed spec field definitions (key, label, unit, type: number/text/image)
+- **SPEC-02**: Sub-tags inherit the spec schema of their parent tag
+- **SPEC-03**: Admin can create, edit, and delete spec field definitions for a tag via the admin panel
+- **SPEC-04**: Global catalog items can have spec values filled in for their tag's spec schema
+- **SPEC-05**: Catalog item detail page displays spec values in a structured spec sheet section
+- **SPEC-06**: Items are filterable/comparable by numeric spec values (e.g. R-value, comfort temp)
+
+### Engagement Stats
+
+- **STAT-01**: Global catalog item detail pages track view counts
+- **STAT-02**: Authenticated users can like/save a catalog item (wishlist-style)
+- **STAT-03**: Catalog item detail page shows owner count, view count, like count, and public setup appearances
+- **STAT-04**: User can view their list of saved/liked catalog items
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| User management in admin panel | Not needed until user base grows; Logto handles account lifecycle |
+| Moderation queue / content flagging | Deferred — requires freeform UGC first |
+| Sub-items / component attachment to items | High complexity, needs dedicated discussion and milestone |
+| Freeform reviews or comments | No moderation infrastructure yet |
+| Social login providers | Logto handles this externally |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| FIX-01 | Phase 35 | Pending |
+| FIX-02 | Phase 35 | Pending |
+| FIX-03 | Phase 35 | Pending |
+| FIX-04 | Phase 35 | Pending |
+| FIX-05 | Phase 35 | Pending |
+| ROLE-01 | Phase 36 | Pending |
+| ROLE-02 | Phase 36 | Pending |
+| ADMN-01 | Phase 36 | Pending |
+| ADMN-02 | Phase 37 | Pending |
+| ADMN-03 | Phase 37 | Pending |
+| ADMN-04 | Phase 37 | Pending |
+| ADMN-05 | Phase 38 | Pending |
+| ADMN-06 | Phase 38 | Pending |
+| ADMN-07 | Phase 38 | Pending |
+| ADMN-08 | Phase 38 | Pending |
+| ADMN-09 | Phase 38 | Pending |
+| ADMN-10 | Phase 38 | Pending |
+
+**Coverage:**
+- v2.4 requirements: 17 total
+- Mapped to phases: 17
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-04-19*
+*Last updated: 2026-04-19 — initial definition for v2.4*

.planning/STATE.md

@@ -1,34 +1,34 @@
 ---
 gsd_state_version: 1.0
-milestone: v2.3
-milestone_name: Global & Social Ready
-status: executing
-stopped_at: context exhaustion at 90% (2026-04-19)
-last_updated: "2026-04-19T14:11:38.116Z"
-last_activity: 2026-04-18
+milestone: v2.4
+milestone_name: Admin Foundation
+status: planning
+stopped_at: milestone initialized
+last_updated: "2026-04-19T00:00:00.000Z"
+last_activity: 2026-04-19
 progress:
-  total_phases: 16
-  completed_phases: 7
-  total_plans: 29
-  completed_plans: 29
-  percent: 100
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-04-09)
+See: .planning/PROJECT.md (updated 2026-04-19)
 
 **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:** Phase 34 — i18n-foundation
+**Current focus:** Milestone v2.4 — Admin Foundation
 
 ## Current Position
 
-Phase: 999.1
-Plan: Not started
-Status: Ready to execute
-Last activity: 2026-04-18
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: 2026-04-19 — Milestone v2.4 started
 
 Progress: [░░░░░░░░░░] 0%
 
@@ -36,9 +36,8 @@ Progress: [░░░░░░░░░░] 0%
 
 **Velocity:**
 
-- Total plans completed: 81 (all milestones through v2.0)
-- v1.3: 6 plans across 4 phases (2026-03-16 to 2026-04-08)
-- v2.0: 32 plans across 10 phases (2026-03-17 to 2026-04-08)
+- Total plans completed: 110+ (all milestones through v2.3)
+- v2.3: 18 plans across 3 phases (2026-04-13 → 2026-04-19)
 
 *Updated after each plan completion*
 
@@ -46,49 +45,31 @@ Progress: [░░░░░░░░░░] 0%
 
 ### Decisions
 
-Key decisions carried forward from v2.0:
+Key decisions carried forward from v2.3:
 
 - External auth provider: Logto (self-hosted OIDC) — RESOLVED
 - Structured UGC only — ratings and predefined fields, no freeform text — ACTIVE
 - Separate globalItems table — not a flag on user items table — RESOLVED
 - COALESCE merge for reference items — RESOLVED
 - Detail pages replacing slide-out panels — RESOLVED
+- Setup visibility: private/link/public column + shares table — RESOLVED
+- Multi-currency: market_prices + community_prices + ECB rates — RESOLVED
+- i18n: react-i18next, 7 namespaces, English + German — RESOLVED
 
-v2.1 decisions:
+v2.4 decisions:
 
-- Product images: manufacturer images with attribution and source link, honor takedown requests — RESOLVED
-- Catalog data: open datasets + manufacturer specs + agent MCP enrichment — RESOLVED
-- Public-first: auth model rework before content features — RESOLVED
-- Phase 999.3 (Public Access Auth Model backlog item) is now Phase 24 — PROMOTED
-- [Phase 24-public-access-infrastructure]: createRateLimit factory pattern for configurable rate limiting per endpoint tier
-- [Phase 24-public-access-infrastructure]: Browse tier 120/min, detail tier 60/min — same limits for auth and anon users
-- [Phase 24]: Both auth prompt CTAs go to /login — Logto handles sign-in and sign-up at the same OIDC endpoint
-- [Phase 24]: Soft navigate() replaces hard window.location.href for private route redirect — defers until auth resolves
-- [Phase 25-catalog-enrichment-agent-tools]: Three-way tag sync: undefined=leave untouched, []=clear all, [names]=replace — enables selective tag updates from catalog agents
-- [Phase 25-catalog-enrichment-agent-tools]: unique(brand, model) constraint on globalItems: enables safe ON CONFLICT DO UPDATE for catalog enrichment agents
-- [Phase 25-catalog-enrichment-agent-tools]: Catalog MCP tools use registerCatalogTools(db) without userId — shared catalog needs no user scoping
-- [Phase 25-catalog-enrichment-agent-tools]: Attribution spacing: image div removes mb-6, attribution paragraph takes mb-6, fallback div ensures consistent spacing
-- [Phase 26-discovery-landing-page]: Composite cursor for setups uses itemCount_id format filtered post-query in JS for simplicity with grouped SQL
-- [Phase 26-discovery-landing-page]: No cursor pagination for getTrendingCategories — bounded small list, simple limit is sufficient
-- [Phase 26]: discoveryRoutes registered with browseTier rate limiting (120 req/min) for all GET discovery endpoints
-- [Phase 26-discovery-landing-page]: PublicSetupCard itemCount/creatorName fields are optional for backward compatibility with users/$userId usage
-- [Phase 26-discovery-landing-page]: Discovery sections hide entirely (return null) when not loading and data is empty — avoids empty grid layouts
-- [Phase 27]: Setups elevated to top-level /setups route; Collection page reduced to Gear and Planning tabs with .catch(gear) fallback for legacy URLs
-- [Phase 27]: Wave 0 tests use test.fixme for removed dashboard cards — preserves test intent for future reference
-- [Phase 27]: Old setups tab test replaced with fallback-to-gear assertion matching the Zod .catch('gear') behavior planned in Plans 01-03
-- [Phase 27]: Used 'house' icon instead of plan-specified 'home': lucide-react has no Home icon, only House — prevents Package fallback rendering in navigation
-- [Phase 32]: isPublic boolean replaced with visibility text column (private/link/public) on setups table — RESOLVED
-- [Phase 32]: shares table with token, permission, expiresAt, userId, revokedAt — schema future-proofed for person-specific shares and write permissions
-- [Phase 32]: Share tokens use randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe
-- [Phase 32]: Visibility→private deactivates share links; switching back reactivates non-expired ones
-- [Phase 32]: /s/:token short URL redirects to /setups/:id?share=token; /api/shared/:token returns setup data without auth
-- [Phase 32]: ShareModal replaces old globe toggle — Google Docs-style with visibility picker + link management
-- [Phase 34]: Created catalog namespace for global-items/discover page
-- [Phase 34]: Static lookup tables (icons, CSS) kept at module level; only label strings moved inside components for t() access
+- Admin role: isAdmin boolean flag on users table (simplest, no Logto role claims needed)
+- Sub-items/component attachment: explicitly deferred to a future milestone
+- Catalog spec system (typed specs per tag): deferred to v2.5
+- Engagement stats (views/likes/saves/appearances): deferred to v2.5
 
 ### Pending Todos
 
 - Fix Add Candidate button shows wrong modal on thread page (ui)
+- Fix item image not showing on collection overview
+- Investigate slow image loading
+- Auth prompt sign-in button should redirect directly to Logto
+- Cursor pointer on all clickable links
 
 ### Blockers/Concerns
 
@@ -96,28 +77,18 @@ None.
 
 ## Deferred Items
 
-Items acknowledged and deferred at milestone close on 2026-04-19:
+Items carried forward from v2.3:
 
 | Category | Item | Status |
 |----------|------|--------|
-| quick_task | 260406-j44-comprehensive-dev-seed-script-for-bikepa | missing tracking marker (work complete) |
-| todo | 2026-04-10-add-cursor-pointer-to-all-clickable-links | pending |
-| todo | 2026-04-10-fix-item-image-not-showing-on-collection-overview | pending |
-| todo | 2026-04-10-investigate-slow-image-loading | pending |
-| todo | 2026-04-13-auth-prompt-sign-in-button-should-redirect-directly-to-logto | pending |
-| todo | 2026-04-13-fix-add-candidate-button-shows-wrong-modal-on-thread-page | pending |
-
-### Quick Tasks Completed
-
-| # | Description | Date | Commit | Directory |
-|---|-------------|------|--------|-----------|
-| 260411-022 | Fix global items search bar layout - too tall and hard to navigate back | 2026-04-10 | ef48891 | [260411-022-fix-global-items-search-bar-layout-too-t](./quick/260411-022-fix-global-items-search-bar-layout-too-t/) |
-| 260411-0zq | Redesign search UX — real nav search bar navigating to /global-items?q= | 2026-04-10 | 334bf33 | [260411-0zq-redesign-search-ux-bigger-nav-search-bar](./quick/260411-0zq-redesign-search-ux-bigger-nav-search-bar/) |
-| 260411-1h2 | Rebuild global items page with sticky toolbar and inline filters | 2026-04-10 | ee3b6f7 | [260411-1h2-rebuild-global-items-page-with-sticky-se](./quick/260411-1h2-rebuild-global-items-page-with-sticky-se/) |
-| Phase 34 P02 | 122 | 5 tasks | 25 files |
+| todo | 2026-04-10-add-cursor-pointer-to-all-clickable-links | promoted to v2.4 FIX-05 |
+| todo | 2026-04-10-fix-item-image-not-showing-on-collection-overview | promoted to v2.4 FIX-02 |
+| todo | 2026-04-10-investigate-slow-image-loading | promoted to v2.4 FIX-03 |
+| todo | 2026-04-13-auth-prompt-sign-in-button-should-redirect-directly-to-logto | promoted to v2.4 FIX-04 |
+| todo | 2026-04-13-fix-add-candidate-button-shows-wrong-modal-on-thread-page | promoted to v2.4 FIX-01 |
 
 ## Session Continuity
 
-Last session: 2026-04-19T14:11:38.113Z
-Stopped at: context exhaustion at 90% (2026-04-19)
+Last session: 2026-04-19
+Stopped at: milestone v2.4 initialized — roadmap pending
 Resume file: None