docs(02-03): complete model caching plan

Phase 2: Model Discovery is now complete with all 3 plans executed:
- 02-01: Replicate provider
- 02-02: fal.ai provider
- 02-03: Model caching and unified API

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -15,7 +15,7 @@ None
 - Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
 
 - [x] **Phase 1: Provider Infrastructure** - API key storage and provider settings UI ✓
-- [ ] **Phase 2: Model Discovery** - Dynamic model fetching from Replicate/fal.ai APIs
+- [x] **Phase 2: Model Discovery** - Dynamic model fetching from Replicate/fal.ai APIs ✓
 - [ ] **Phase 3: Generate Node Refactor** - Rename NanoBanana to generic Generate with multi-model support
 - [ ] **Phase 4: Model Search Dialog** - Floating action bar icons and searchable model browser
 - [ ] **Phase 5: Image URL Server** - Local endpoint serving images as URLs for providers
@@ -43,7 +43,7 @@ Plans:
 Plans:
 - [x] 02-01: Replicate model fetching API route
 - [x] 02-02: fal.ai model fetching API route
-- [ ] 02-03: Model caching and unified model interface
+- [x] 02-03: Model caching and unified model interface
 
 ### Phase 3: Generate Node Refactor
 **Goal**: NanoBanana node becomes generic Generate node supporting any provider's model
@@ -96,7 +96,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. Provider Infrastructure | 2/2 | Complete | 2026-01-09 |
-| 2. Model Discovery | 2/3 | In progress | - |
+| 2. Model Discovery | 3/3 | Complete | 2026-01-09 |
 | 3. Generate Node Refactor | 0/3 | Not started | - |
 | 4. Model Search Dialog | 0/2 | Not started | - |
 | 5. Image URL Server | 0/2 | Not started | - |

.planning/STATE.md

@@ -5,34 +5,34 @@
 See: .planning/PROJECT.md (updated 2026-01-09)
 
 **Core value:** Provider infrastructure that dynamically discovers models from external APIs, enabling users to access hundreds of image/video generation models without hardcoding schemas.
-**Current focus:** Phase 2 - Model Discovery
+**Current focus:** Phase 3 - Generate Node Refactor
 
 ## Current Position
 
-Phase: 2 of 6 (Model Discovery)
-Plan: 2 of 3 in current phase
-Status: In progress
-Last activity: 2026-01-09 - Completed 02-02-PLAN.md (fal.ai provider)
+Phase: 3 of 6 (Generate Node Refactor)
+Plan: 0 of 3 in current phase
+Status: Ready to start Phase 3
+Last activity: 2026-01-09 - Completed 02-03-PLAN.md (Model caching)
 
-Progress: [==========================] 27% (4/15 plans)
+Progress: [=================================] 33% (5/15 plans)
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 4
+- Total plans completed: 5
 - Average duration: 6 min
-- Total execution time: 0.4 hours
+- Total execution time: 0.5 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 1. Provider Infrastructure | 2/2 | 14 min | 7 min |
-| 2. Model Discovery | 2/3 | 9 min | 4.5 min |
+| 2. Model Discovery | 3/3 | 14 min | 4.7 min |
 
 **Recent Trend:**
-- Last 5 plans: 12 min, 2 min, 4 min, 5 min
-- Trend: improving
+- Last 5 plans: 2 min, 4 min, 5 min, 5 min
+- Trend: stable
 
 ## Accumulated Context
 
@@ -51,6 +51,8 @@ Recent decisions affecting current work:
 - fal.ai API key optional (works without but rate limited)
 - fal.ai auth header: "Key {apiKey}" format (not Bearer)
 - fal.ai category maps directly to ModelCapability (no inference)
+- 10-minute cache TTL for model lists
+- Unified API at /api/models with header-based auth
 
 ### Deferred Issues
 
@@ -63,6 +65,6 @@ None.
 ## Session Continuity
 
 Last session: 2026-01-09
-Stopped at: Completed 02-02-PLAN.md
+Stopped at: Completed Phase 2 (02-03-PLAN.md)
 Resume file: None
-Next action: Execute 02-03-PLAN.md (Model caching)
+Next action: Plan Phase 3 (03-01-PLAN.md - Rename NanoBanana to Generate)

.planning/phases/02-model-discovery/02-03-SUMMARY.md

@@ -0,0 +1,141 @@
+---
+phase: 02-model-discovery
+plan: 03
+subsystem: api
+tags: [caching, unified-api, model-discovery, providers]
+
+# Dependency graph
+requires:
+  - phase: 02-01
+    provides: Replicate provider implementation
+  - phase: 02-02
+    provides: fal.ai provider implementation
+provides:
+  - In-memory model caching with TTL
+  - Unified /api/models endpoint for all providers
+  - Multi-provider helper functions (listAllModels, searchAllModels)
+  - Cache utilities (getCachedModels, setCachedModels, invalidateCache)
+affects: [model-browser, generate-node, phase-3]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [in-memory caching with TTL, unified API aggregation, partial failure handling]
+
+key-files:
+  created:
+    - src/lib/providers/cache.ts
+    - src/app/api/models/route.ts
+  modified:
+    - src/lib/providers/index.ts
+
+key-decisions:
+  - "10-minute default cache TTL (configurable per call)"
+  - "Cache key format: {provider}:models or {provider}:search:{query}"
+  - "Unified API uses header-based auth (X-Replicate-Key, X-Fal-Key)"
+  - "fal.ai always included in unified response (works without key)"
+  - "Partial failures return successful providers with errors array"
+
+patterns-established:
+  - "Cache utilities exported from @/lib/providers for reuse"
+  - "Unified API endpoint pattern at /api/models"
+  - "Multi-provider aggregation with Promise.allSettled"
+
+issues-created: []
+
+# Metrics
+duration: 5min
+completed: 2026-01-09
+---
+
+# Phase 02-03: Model Caching and Unified API Summary
+
+**In-memory caching layer and unified /api/models endpoint aggregating Replicate and fal.ai models**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-01-09
+- **Completed:** 2026-01-09
+- **Tasks:** 3
+- **Files created:** 2
+- **Files modified:** 1
+
+## Accomplishments
+
+- Created in-memory cache utility with 10-minute TTL for model lists
+- Built unified /api/models endpoint aggregating all configured providers
+- Added cache utilities export from provider index
+- Implemented listAllModels and searchAllModels helper functions
+- Partial failure handling - returns models from successful providers with errors array
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create model caching utility** - `83ef0b4` (feat)
+2. **Task 2: Create unified models API endpoint** - `421620c` (feat)
+3. **Task 3: Add provider module exports** - `91a5449` (feat)
+
+## Files Created/Modified
+
+- `src/lib/providers/cache.ts` - In-memory cache with get/set/invalidate and TTL support
+- `src/app/api/models/route.ts` - Unified API aggregating Replicate and fal.ai models
+- `src/lib/providers/index.ts` - Added cache exports and multi-provider helper functions
+
+## API Reference
+
+### GET /api/models
+
+**Query Parameters:**
+- `provider`: Optional, filter to "replicate" or "fal"
+- `search`: Optional, search query
+- `refresh`: Optional, set to "true" to bypass cache
+
+**Headers:**
+- `X-Replicate-Key`: Replicate API key
+- `X-Fal-Key`: fal.ai API key (optional)
+
+**Response:**
+```json
+{
+  "success": true,
+  "models": [...],
+  "cached": false,
+  "providers": {
+    "replicate": { "success": true, "count": 50, "cached": false },
+    "fal": { "success": true, "count": 100, "cached": true }
+  },
+  "errors": []
+}
+```
+
+## Decisions Made
+
+- Cache uses simple in-memory Map (no LRU, no persistence)
+- Default TTL is 10 minutes - balance between freshness and API quota
+- Cache key includes search query for separate caching of search results
+- fal.ai always included in unified results (works without API key)
+- Unified API returns sorted models (by provider, then name)
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Phase 2 Complete
+
+This plan completes Phase 2: Model Discovery. All three plans are now done:
+
+1. **02-01**: Replicate provider with model fetching
+2. **02-02**: fal.ai provider with model fetching
+3. **02-03**: Model caching and unified API
+
+The model discovery infrastructure is ready for Phase 3: Generate Node Refactor.
+
+---
+*Phase: 02-model-discovery*
+*Completed: 2026-01-09*