# Phase 23: Manual Entry Fallback - Context

**Gathered:** 2026-04-06
**Status:** Ready for planning

<domain>
## Phase Boundary

Users can still add items not found in the catalog via manual entry. The catalog search overlay gets an "Add Manually" fallback link. Manual entry saves a standalone collection item (no globalItemId). After saving, a non-functional "Submit to catalog?" prompt is shown (no backend action — future feature).

</domain>

<decisions>
## Implementation Decisions

### Entry Point Placement
- **D-01:** "Add Manually" link appears in the catalog search empty state (when no results match) AND as a subtle persistent link below search results, so users can always reach manual entry regardless of whether results exist.
- **D-02:** The link text is "Add Manually" or "Can't find it? Add manually" — context-sensitive based on whether a search query exists.

### Form Presentation
- **D-03:** Manual entry form replaces the search results area inline within the CatalogSearchOverlay. The user stays in the overlay context — no navigation away or additional modal.
- **D-04:** Back arrow at the top returns from the manual form to search results (like navigating within the overlay).
- **D-05:** The form is a dedicated ManualEntryForm component rendered inside CatalogSearchOverlay when a `manualEntryMode` state is active.

### Form Fields
- **D-06:** Required: name. Optional: category (via CategoryPicker), weight (grams), price (cents), notes, purchase price, image upload, product link.
- **D-07:** Reuse field patterns from ItemForm (CategoryPicker, weight/price inputs) but keep the form focused and compact — not the full 315-line ItemForm.
- **D-08:** Submit calls `POST /api/items` without `globalItemId` — creates a standalone collection item.

### Post-Save Catalog Prompt
- **D-09:** After successful save, show an inline success card within the overlay: "Added [item name] to collection" with a "Submit to Catalog?" button.
- **D-10:** The "Submit to Catalog?" button is non-functional — shows a toast "Coming soon" or similar when clicked. No backend action.
- **D-11:** Below the prompt, show "Add Another" (returns to search) and "Done" (closes overlay) buttons.

### Claude's Discretion
- Exact form layout proportions and field ordering
- Whether weight/price fields use formatted inputs or plain number inputs
- Animation transitions between search results and manual entry form
- Success card visual styling
- Whether the search query auto-populates the item name field when entering manual mode

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Design Spec
- `docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md` — Full catalog-driven gear flow vision. Phase 23 implements the manual entry fallback path.

### Key Components to Modify
- `src/client/components/CatalogSearchOverlay.tsx` — Add "Add Manually" link to EmptyState (line 667), add persistent link below results, add ManualEntryForm rendering
- `src/client/stores/uiStore.ts` — May need `manualEntryMode` state or can be local to CatalogSearchOverlay

### Existing Components to Reuse
- `src/client/components/ItemForm.tsx` — Field patterns (CategoryPicker usage, weight/price inputs) to adapt for manual entry form
- `src/client/components/AddToCollectionModal.tsx` — Lightweight add pattern with CategoryPicker, notes, purchase price
- `src/client/components/CategoryPicker.tsx` — Reusable category selector
- `src/client/components/ImageUpload.tsx` — Image upload component

### Hooks
- `src/client/hooks/useItems.ts` — `useCreateItem()` for creating standalone items (no globalItemId)
- `src/client/hooks/useCategories.ts` — Category list for CategoryPicker

### Schemas
- `src/shared/schemas.ts` — `createItemSchema` already supports items without `globalItemId`

### Prior Phase Context
- `.planning/phases/20-fab-full-screen-catalog-search/20-CONTEXT.md` — Catalog search overlay design (D-12: empty state with "Add Manually" link noted)
- `.planning/phases/22-add-from-catalog-thread-integration/22-CONTEXT.md` — Deferred "Add Manually" link to this phase

### Requirements
- `.planning/REQUIREMENTS.md` — CATFLOW-07, CATFLOW-08

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `useCreateItem()` hook — creates items via POST /api/items, works without `globalItemId` for standalone items
- `CategoryPicker` — drop-in category selector with search and inline create
- `ImageUpload` — image upload with preview
- `AddToCollectionModal` — reference for lightweight form pattern (category + notes + purchase price)
- `ItemForm` — full item form with all fields, good reference for field patterns

### Established Patterns
- CatalogSearchOverlay manages internal view state (search input, filters, view mode) via local useState
- Zustand UIStore for overlay open/close state
- `toast()` from sonner for success/error notifications
- TanStack React Query mutations with `invalidateQueries` on success

### Integration Points
- `CatalogSearchOverlay.tsx` — EmptyState component (line 667) needs "Add Manually" link
- `CatalogSearchOverlay.tsx` — Results area needs persistent "Add Manually" link
- `CatalogSearchOverlay.tsx` — New ManualEntryForm component rendered conditionally
- No new routes needed — everything happens within the overlay

</code_context>

<specifics>
## Specific Ideas

- The manual entry form should feel like a natural extension of the catalog search flow — "couldn't find it? no problem, add it yourself"
- Search query should auto-populate the item name field when transitioning to manual entry
- The "Submit to Catalog?" prompt plants the seed for the future catalog submission system without promising functionality

</specifics>

<deferred>
## Deferred Ideas

- Actual catalog submission backend (admin review, convert to global item) — future phase
- Bulk manual entry — future phase
- Image search / URL paste to auto-populate item details — future phase

</deferred>

---

*Phase: 23-manual-entry-fallback*
*Context gathered: 2026-04-06*