GearBox/.planning/phases/23-manual-entry-fallback/23-CONTEXT.md

Phase 23: Manual Entry Fallback - Context

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

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

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

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

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

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

---

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