docs(30): capture phase context

.planning/phases/30-onboarding-redesign/30-CONTEXT.md

@@ -0,0 +1,125 @@
+# Phase 30: Onboarding Redesign - Context
+
+**Gathered:** 2026-04-12
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Replace the current manual-entry onboarding wizard with a catalog-driven, hobby-personalized full-screen experience. New users pick their hobby, see popular items from that hobby's catalog, and batch-add items they own to their collection. Categories auto-created from selections.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Flow Structure
+- **D-01:** Onboarding flow: **Welcome → Pick Hobby → Browse Popular Items → Review & Confirm → Done**
+- **D-02:** Display name captured during signup (Logto field or first-login prompt) — NOT during onboarding wizard.
+- **D-03:** Profile pic is not part of onboarding — users add it later from the profile page.
+- **D-04:** Hobby selection is the key personalization step — it determines what catalog items are shown.
+- **D-05:** Categories auto-created from the user's selections (based on the tags/categories of items they add). No manual "create a category" step.
+
+### Hobby Selection
+- **D-06:** Card-based hobby picker with icons — visual cards for each hobby area (Bikepacking, Hiking, Climbing, Cycling, etc.). Not a plain tag list.
+- **D-07:** Hobbies map to catalog tags for filtering. Starting with outdoor categories, but the system is extensible to any hobby.
+- **D-08:** User can pick one or more hobbies. Multiple selections show combined results.
+
+### Catalog Integration
+- **D-09:** After hobby selection, show popular items from the most popular tags within that hobby. Not a full search — a curated, browsable grid.
+- **D-10:** "Popular" initially measured by **owner count** (how many users have linked the item). Real view analytics are a future enhancement.
+- **D-11:** User taps/checks items they own — selections collected as a batch. No immediate adds.
+- **D-12:** Summary/review screen before final commit — user confirms their selections, then all items batch-added to their collection at once.
+
+### Visual Style
+- **D-13:** Full-screen experience — each step takes the full viewport. Big visuals, generous spacing, immersive. Modern app intro feel (Notion/Linear style).
+- **D-14:** Replace the current centered modal card approach entirely.
+- **D-15:** Smooth transitions between steps. Step indicator still present but full-width, not dots.
+
+### Trigger & Skip Behavior
+- **D-16:** Triggers on first login (any auth method — email, Google, GitHub).
+- **D-17:** Hobby selection step is **required** (not skippable) — essential for personalization.
+- **D-18:** Other steps (browse items, add to collection) are skippable. Skipping marks onboarding complete.
+
+### Claude's Discretion
+- Hobby card design and icon choices
+- How many items/tags to show per hobby
+- Transition animations between steps
+- Whether to use TanStack Router routes or a single component with internal step state
+- How to handle users who sign up for a hobby with no catalog items yet (empty state)
+- Exact categories auto-created logic (group by tag, by catalog category, etc.)
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Existing Onboarding Code (to be replaced)
+- `src/client/components/OnboardingWizard.tsx` — Current 4-step modal wizard
+- `src/client/routes/__root.tsx` — Onboarding trigger logic (lines ~98-105, ~193)
+
+### Catalog Components (reusable patterns)
+- `src/client/components/CatalogSearchOverlay.tsx` — Catalog search with tag filtering
+- `src/client/components/GlobalItemCard.tsx` — Card display for catalog items
+- `src/client/hooks/useGlobalItems.ts` — Catalog data fetching hooks
+
+### Add-from-Catalog Flow
+- `src/client/components/LinkToGlobalItem.tsx` — Linking user items to global items
+
+### Settings/Onboarding State
+- `src/server/routes/settings.ts` — Settings CRUD (onboardingComplete flag)
+- `src/server/services/settings.service.ts` — Settings service
+
+### Discovery (popular items data)
+- `src/server/services/discovery.service.ts` — getRecentCatalogItems, getPopularSetups — similar patterns for popular items by tag
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `GlobalItemCard` component — card display for catalog items. Can be reused in the onboarding item grid.
+- `CatalogSearchOverlay` — tag-filtered search. Patterns reusable for hobby-filtered browsing.
+- `useGlobalItems` hook — fetches catalog items with search/filter. Can be extended for tag-based popularity queries.
+- `LucideIcon` — icon rendering for hobby cards.
+- Discovery service — `getRecentCatalogItems` pattern can be adapted for "popular items by tag".
+
+### Established Patterns
+- Onboarding state tracked via `settings` table (`onboardingComplete: "true"`)
+- Full-screen modals exist in auth flow — pattern can be adapted
+- Tag system already supports filtering catalog items by tags
+
+### Integration Points
+- `src/client/routes/__root.tsx` — Replace onboarding trigger with new full-screen experience
+- `src/server/services/discovery.service.ts` — Add "popular items by hobby/tag" query
+- `src/server/routes/discovery.ts` — Add endpoint for hobby-filtered popular items
+- `src/db/schema.ts` — May need a user_preferences or hobby_selections table
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- The hobby selection personalizes the experience from the very start — it should feel like the app is being tailored for them.
+- Starting with outdoor categories (bikepacking, hiking, climbing, cycling) but the system must easily accommodate future hobbies (sim racing, photography, etc.).
+- Owner count as the initial "popularity" metric is good enough for launch. Real analytics/view tracking comes later (backlog 999.8).
+- The current OnboardingWizard.tsx is a complete rewrite — nothing is reused from it except the onboardingComplete settings flag.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- View/click analytics for better popularity ranking — belongs in 999.8 Analytics Integration
+- Category editing UI — separate improvement, not onboarding-specific
+- Profile pic during onboarding — deferred, handled via profile page
+
+</deferred>
+
+---
+
+*Phase: 30-onboarding-redesign*
+*Context gathered: 2026-04-12*

.planning/phases/30-onboarding-redesign/30-DISCUSSION-LOG.md

@@ -0,0 +1,93 @@
+# Phase 30: Onboarding Redesign - 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-12
+**Phase:** 30-onboarding-redesign
+**Areas discussed:** Flow structure, Catalog integration, Visual style & tone, Trigger & skip behavior
+
+---
+
+## Flow Structure
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Welcome → Pick hobby → Browse catalog → Done | Hobby personalizes catalog, categories auto-created | ✓ (hybrid) |
+| Welcome → Search catalog → Done | Skip hobby, direct search | |
+| Welcome → Profile → First setup → Done | Profile-first, then setup building | |
+
+**User's choice:** Hybrid — display name in signup, hobby selection for personalization, catalog browse, auto-create categories. Quick but captures the important stuff.
+**Notes:** User wants display name captured at signup (Logto), not during wizard. Profile pic is post-signup, not important for onboarding. Liked hobby question and category auto-creation. Noted that category editing needs to be available (separate concern).
+
+## Hobby Selection
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Predefined grid of hobbies | Visual grid with icons | |
+| Free text + suggestions | Type hobby, get suggestions | |
+| Tag-based selection | Show catalog tags grouped by hobby | |
+| Hybrid (cards + tags) | Card-based layout backed by catalog tags | ✓ |
+
+**User's choice:** Between options 1 and 3 — card-based layout backed by tags. Starting with outdoor stuff (climbing, hiking, bikepacking, cycling) but extensible.
+
+---
+
+## Catalog Integration
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Curated picks grid | Popular/essential items, tap to check off | ✓ (adapted) |
+| Full catalog search | Drop into CatalogSearchOverlay | |
+| Category-first browse | Browse by category then items | |
+
+**User's choice:** Show popular items from most popular tags for that hobby. Not full search — too overwhelming. Popular = owner count for now, real analytics later.
+**Notes:** User sees value in tracking views/popularity long-term but acknowledged it's a future enhancement.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Batch at end | Collect selections, confirm on summary screen | ✓ |
+| Immediate add | Each tap adds instantly | |
+| You decide | Claude picks | |
+
+**User's choice:** Batch at end
+
+---
+
+## Visual Style & Tone
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Full-screen experience | Each step full viewport, big visuals, immersive | ✓ |
+| Card modal (refreshed) | Keep centered card, update visually | |
+| Inline page flow | Real routes, not modal | |
+
+**User's choice:** Full-screen experience
+
+---
+
+## Trigger & Skip Behavior
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| First login, skippable | Shows after first login, all steps skippable | |
+| First login, hobby required | Hobby step required, others skippable | ✓ |
+| You decide | Claude picks | |
+
+**User's choice:** Hobby step required (essential for personalization), other steps skippable
+
+---
+
+## Claude's Discretion
+
+- Hobby card design and icons
+- Number of items/tags per hobby
+- Step transitions and animations
+- Router integration approach
+- Empty hobby handling
+
+## Deferred Ideas
+
+- View/click analytics for popularity ranking (→ 999.8)
+- Category editing UI (separate improvement)
+- Profile pic during onboarding (→ profile page)