GearBox/.planning/milestones/v2.2-phases/30-onboarding-redesign/30-CONTEXT.md

Phase 30: Onboarding Redesign - Context

Gathered: 2026-04-12 Status: Ready for planning

## 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.

## 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.)

<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>

## 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.

## 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

---

Phase: 30-onboarding-redesign Context gathered: 2026-04-12