docs(26): capture phase context

.planning/phases/26-discovery-landing-page/26-CONTEXT.md

@@ -0,0 +1,135 @@
+# Phase 26: Discovery Landing Page - Context
+
+**Gathered:** 2026-04-10
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Replace the current personal dashboard at `/` with a public-first discovery landing page. The page features a prominent catalog search bar at the top, a feed of popular public setups, recently added catalog items, and trending categories. Authenticated users see a "Go to Collection" entry point. This is the first page any visitor sees — no login required.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Page Layout & Structure
+- **D-01:** Full-width hero area with catalog search bar prominently centered. Below the hero, a vertical stack of content sections.
+- **D-02:** Section order: (1) Hero with search bar, (2) Popular Setups, (3) Recently Added Items, (4) Trending Categories. Each section has a heading and optional "View all" link.
+- **D-03:** The current `DashboardPage` component and its `DashboardCard` usage at `/` will be replaced entirely. The dashboard is now the landing page.
+
+### Search Bar Behavior
+- **D-04:** The hero search bar triggers the existing `CatalogSearchOverlay` on focus or typing. This reuses the full-featured search (tag filtering, grid/list toggle, manual entry fallback) without duplicating search UI. The search bar on the landing page is a visual entry point, not a standalone search results container.
+
+### Feed Data Sources & Ranking
+- **D-05:** "Popular setups" ranked by item count descending (proxy for effort/completeness). Only public setups are shown. No engagement tracking exists yet — item count is available via `setupItems` join table.
+- **D-06:** "Recently added items" shows the most recently created `globalItems`, ordered by `createdAt` descending.
+- **D-07:** "Trending categories" ranked by global item count per distinct `globalItems.category` value. Categories with the most catalog items appear first.
+- **D-08:** Cursor-based pagination for feed sections per INFR-02. Use `createdAt` cursor for recently added items; item count + ID cursor for popular setups.
+
+### Authenticated vs Anonymous Experience
+- **D-09:** Same page content for both authenticated and anonymous users — no personalized feed in v2.1. The difference is purely navigational.
+- **D-10:** Authenticated users see a "Go to Collection" CTA in the hero area, next to the search bar. Visible without scrolling.
+- **D-11:** Anonymous users see the search bar and content sections immediately (fire-and-forget auth from Phase 24, D-09). Sign-in button in top-right per Phase 24, D-10.
+
+### Claude's Discretion
+- Exact layout sizing, spacing, and responsive breakpoints
+- Number of items shown per section before "View all" (suggest 6-8 for items/setups, 8-12 for categories)
+- Empty states for sections with no data
+- Loading skeletons for each section
+- Whether "View all" links for setups/items route to existing pages or new dedicated feed pages
+
+### Folded Todos
+- **Add cursor pointer to all clickable links** — Ensure all clickable elements on the landing page have `cursor-pointer`. Apply broadly while building the new page.
+- **Fix item image not showing on collection overview** — Investigate and fix image display issue; relevant since landing page will show `GlobalItemCard` components with images.
+- **Investigate slow image loading** — Profile image loading performance; landing page is image-heavy with item cards and setup previews.
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Current Landing Page (to replace)
+- `src/client/routes/index.tsx` — Current dashboard page component (will be rewritten)
+- `src/client/components/DashboardCard.tsx` — Current dashboard card (will be unused after this phase)
+
+### Reusable Components
+- `src/client/components/GlobalItemCard.tsx` — Catalog item card with image, brand/model, weight/price pills
+- `src/client/components/PublicSetupCard.tsx` — Basic public setup card (name + date; may need enhancement for item count)
+- `src/client/components/CatalogSearchOverlay.tsx` — Full-screen search overlay with debounce, tag filtering, grid/list modes
+
+### Hooks & Data
+- `src/client/hooks/useGlobalItems.ts` — Search global items by query and tags
+- `src/client/hooks/useTags.ts` — Fetch tag list
+- `src/client/hooks/useAuth.ts` — Auth state (`user`, `authenticated`)
+- `src/client/stores/uiStore.ts` — UI state store including `catalogSearchOpen` / `openCatalogSearch`
+
+### Server Services
+- `src/server/services/global-item.service.ts` — `searchGlobalItems` (needs new queries: recent items, category counts)
+- `src/server/services/profile.service.ts` — `getPublicProfile`, `getPublicSetupWithItems` (setup data patterns)
+
+### Routes & API
+- `src/server/routes/global-items.ts` — Current GET endpoints (needs discovery feed endpoints)
+- `src/server/routes/setups.ts` — Public setup view endpoint (`GET /:id/public`)
+- `src/server/index.ts` — Route registration and public route allowlist
+
+### Auth & Layout
+- `src/client/routes/__root.tsx` — Root layout, auth check, `isPublicRoute` logic (root `/` already public per Phase 24)
+
+### Requirements
+- `.planning/REQUIREMENTS.md` — DISC-01 through DISC-05, INFR-02
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `GlobalItemCard` — Ready-to-use catalog item card with image placeholder, brand/model, weight/price/category pills. Can be used directly in "Recently Added" section.
+- `PublicSetupCard` — Minimal card (name + date). Needs enhancement: add item count, possibly creator name and total weight to be useful in a "Popular Setups" feed.
+- `CatalogSearchOverlay` — Full search implementation with debounce, tag chip filtering, grid/list toggle, manual entry. Landing page search bar should open this overlay rather than duplicating search logic.
+- `useFormatters` hook — Weight and price formatting, reusable across all card components.
+- `LucideIcon` component — For category icons in the "Trending Categories" section.
+
+### Established Patterns
+- TanStack Router file-based routes — new route stays at `routes/index.tsx` (same file, new content)
+- TanStack React Query for data fetching — landing page sections each get their own query hook
+- Tailwind CSS v4 with light/airy/minimalist design language — white backgrounds, gray borders, rounded-xl cards, subtle shadows on hover
+- Card pattern: `bg-white rounded-xl border border-gray-100 hover:border-gray-200 hover:shadow-md transition-all`
+
+### Integration Points
+- `routes/index.tsx` — Rewrite to render landing page instead of dashboard
+- New server endpoints needed: `GET /api/discovery/setups` (popular), `GET /api/discovery/items` (recent), `GET /api/discovery/categories` (trending)
+- `uiStore.openCatalogSearch()` — Trigger from the hero search bar
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Design should feel like a welcoming storefront, not a login gate — consistent with Phase 24's "new user experience matters more" principle
+- Tags are the public taxonomy for discovery; categories are private organizational tools — the landing page uses tags for any filtering/categorization display, not user categories
+- Hero area should be visually distinctive but not heavy — the app's DNA is "light, airy, minimalist"
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Personalized feed based on user's collection categories (PERS-01, PERS-02) — tracked in future requirements
+- SSR/static prerendering for SEO (SEO-01, SEO-02) — out of scope for v2.1
+- Engagement metrics (views, likes) for better ranking — no tracking infrastructure yet
+- Setup preview images/thumbnails — no setup image feature exists
+
+### Reviewed Todos (not folded)
+- **Add manufacturer entity with brand details** — Database schema enhancement unrelated to landing page UI; belongs in a future catalog data model phase
+- **Fix storage service tests** — Testing infrastructure concern; not related to landing page feature work
+
+</deferred>
+
+---
+
+*Phase: 26-discovery-landing-page*
+*Context gathered: 2026-04-10*

.planning/phases/26-discovery-landing-page/26-DISCUSSION-LOG.md

@@ -0,0 +1,103 @@
+# Phase 26: Discovery Landing Page - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-04-10
+**Phase:** 26-discovery-landing-page
+**Areas discussed:** Page Structure & Section Order, Search Bar Behavior, Feed Data & Ranking, Auth-Variant Experience
+**Mode:** --batch --auto (all decisions auto-selected)
+
+---
+
+## Page Structure & Section Order
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Hero search + vertical sections | Full-width hero with search bar, vertical stack of content sections below | ✓ |
+| Grid dashboard | Multi-column grid of section cards (like current dashboard) | |
+| Single infinite feed | One merged feed of all content types | |
+
+**User's choice:** [auto] Hero search + vertical sections (recommended default)
+**Notes:** Reuses existing visual patterns (cards, rounded-xl, light borders). Section order: Search → Setups → Items → Categories, prioritizing social content first.
+
+---
+
+## Search Bar Behavior
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Open CatalogSearchOverlay | Hero search bar triggers existing overlay on focus/type | ✓ |
+| Inline search results | Show results directly below the search bar on the landing page | |
+| Dedicated search route | Navigate to /search with query params | |
+
+**User's choice:** [auto] Open CatalogSearchOverlay (recommended default)
+**Notes:** Avoids duplicating the full-featured search UI (tag filtering, grid/list toggle, manual entry fallback). CatalogSearchOverlay is already built and tested.
+
+---
+
+## Feed Data & Ranking
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Item count proxy (setups) | Rank popular setups by number of items — more items = more effort/completeness | ✓ |
+| Creation date (setups) | Show most recently created setups | |
+| Random rotation | Rotate featured setups randomly | |
+
+**User's choice:** [auto] Item count proxy (recommended default)
+**Notes:** No engagement metrics exist. Item count is the best available proxy and is trivially queryable via setupItems join.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Global item count per category | Trending = categories with most catalog items | ✓ |
+| Recent growth rate | Categories with most new items in last 7 days | |
+
+**User's choice:** [auto] Global item count per category (recommended default)
+**Notes:** Simpler query, no time-windowed aggregation needed. Growth-based trending can be added later when catalog is larger.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Cursor-based pagination | Use cursor pagination per INFR-02 requirement | ✓ |
+| Offset pagination | Traditional LIMIT/OFFSET | |
+
+**User's choice:** [auto] Cursor-based pagination (recommended default — required by INFR-02)
+
+---
+
+## Auth-Variant Experience
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Same page + Collection CTA | Identical content, authenticated users get "Go to Collection" button in hero | ✓ |
+| Dual-mode page | Show personal stats/shortcuts for authenticated users | |
+| Redirect authenticated to dashboard | Authenticated users skip landing page entirely | |
+
+**User's choice:** [auto] Same page + Collection CTA (recommended default)
+**Notes:** Per DISC-05, the difference is a single navigational CTA. No personalized feed in v2.1 (PERS-01/PERS-02 deferred).
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| In hero area next to search | CTA visible without scrolling, adjacent to primary action | ✓ |
+| Floating sidebar | Persistent side panel for authenticated users | |
+| Below hero | Separate banner below search area | |
+
+**User's choice:** [auto] In hero area next to search (recommended default)
+
+---
+
+## Claude's Discretion
+
+- Exact layout sizing, spacing, and responsive breakpoints
+- Number of items shown per section before "View all"
+- Empty states for sections with no data
+- Loading skeletons for each section
+- Whether "View all" links route to existing pages or new feed pages
+
+## Deferred Ideas
+
+- Personalized feed (PERS-01, PERS-02)
+- SSR/static prerendering for SEO (SEO-01, SEO-02)
+- Engagement metrics for ranking
+- Setup preview images
+- Manufacturer entity (todo — different domain)
+- Storage service tests (todo — testing concern)