# Phase 1: Foundation and Collection - Context

**Gathered:** 2026-03-14
**Status:** Ready for planning

<domain>
## Phase Boundary

Project scaffolding (Bun + Hono + React + Vite + SQLite via Drizzle), database schema for items and categories, and complete gear collection CRUD with category management and aggregate totals. No threads, no setups, no dashboard — those are later phases.

</domain>

<decisions>
## Implementation Decisions

### Collection Layout
- Card grid layout, grouped by category headers
- Each card shows: item name (prominent), then tag-style chips for weight, price, and category
- Item image displayed on the card for visual identification
- Items grouped under category headers with per-category weight/cost subtotals
- Global sticky totals bar at the top showing total items, weight, and cost
- Empty categories are hidden from the collection view (not shown)

### Item Editing Flow
- Slide-out panel from the right side for both adding and editing items
- Same panel component for add (empty) and edit (pre-filled)
- Collection remains visible behind the panel for context
- Confirmation dialog before deleting items ("Are you sure?")

### Category Management
- Single-level categories only (no subcategories)
- Searchable category picker in the item form — type to find existing or create new
- Categories editable from the collection overview (rename, delete, change icon)
- Each category gets an emoji/icon for visual distinction
- Deleting a category moves its items to "Uncategorized" default category

### First-Run Experience
- Step-by-step onboarding wizard for first-time users
- Guides through: create first category, add first item
- After onboarding, normal collection view takes over

### Claude's Discretion
- Form layout for item add/edit panel (all fields visible vs grouped sections)
- Loading states and skeleton design
- Exact spacing, typography, and Tailwind styling choices
- Error state handling and validation feedback
- Weight unit storage (grams internally, display in user's preferred unit can be deferred to v2)

</decisions>

<specifics>
## Specific Ideas

- Cards should feel clean and minimal — "light and airy" aesthetic with white/light backgrounds, lots of whitespace
- Item info displayed as tag-style chips (not labels with values) — compact, scannable
- Category picker should work like a combobox: type to search, select existing, or create new inline
- Photos on cards are important for visual identification even in v1

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- None — greenfield project, no existing code

### Established Patterns
- None yet — Phase 1 establishes all patterns

### Integration Points
- Bun runtime with bun:sqlite for database
- Hono for API server
- React 19 + Vite 8 for frontend
- Drizzle ORM for type-safe database access
- Tailwind v4 for styling
- TanStack Router for client-side routing

</code_context>

<deferred>
## Deferred Ideas

- Subcategories (e.g. "Bags" → "Handlebar Bag") — revisit if single-level feels limiting
- Photos are noted as important for cards; image upload implementation is technically in scope (COLL-01 mentions item details) but full photo management is v2

</deferred>

---

*Phase: 01-foundation-and-collection*
*Context gathered: 2026-03-14*