docs(02-02): complete fal.ai provider plan

Tasks completed: 2/2
- Create fal.ai provider implementation
- Create fal.ai models API route

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

.planning/ROADMAP.md

@@ -42,7 +42,7 @@ Plans:
 
 Plans:
 - [x] 02-01: Replicate model fetching API route
-- [ ] 02-02: fal.ai model fetching API route
+- [x] 02-02: fal.ai model fetching API route
 - [ ] 02-03: Model caching and unified model interface
 
 ### Phase 3: Generate Node Refactor
@@ -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 | 1/3 | In progress | - |
+| 2. Model Discovery | 2/3 | In progress | - |
 | 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

@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-01-09)
 ## Current Position
 
 Phase: 2 of 6 (Model Discovery)
-Plan: 1 of 3 in current phase
+Plan: 2 of 3 in current phase
 Status: In progress
-Last activity: 2026-01-09 - Completed 02-01-PLAN.md (Replicate provider)
+Last activity: 2026-01-09 - Completed 02-02-PLAN.md (fal.ai provider)
 
-Progress: [====================] 20% (3/15 plans)
+Progress: [==========================] 27% (4/15 plans)
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 3
+- Total plans completed: 4
 - Average duration: 6 min
-- Total execution time: 0.3 hours
+- Total execution time: 0.4 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 1. Provider Infrastructure | 2/2 | 14 min | 7 min |
-| 2. Model Discovery | 1/3 | 4 min | 4 min |
+| 2. Model Discovery | 2/3 | 9 min | 4.5 min |
 
 **Recent Trend:**
-- Last 5 plans: 12 min, 2 min, 4 min
+- Last 5 plans: 12 min, 2 min, 4 min, 5 min
 - Trend: improving
 
 ## Accumulated Context
@@ -48,6 +48,9 @@ Recent decisions affecting current work:
 - Provider registry uses self-registration pattern via registerProvider()
 - Gemini remains special-cased in /api/generate for now, not yet migrated
 - Capability inference from model name/description keywords
+- 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)
 
 ### Deferred Issues
 
@@ -60,6 +63,6 @@ None.
 ## Session Continuity
 
 Last session: 2026-01-09
-Stopped at: Completed 02-01-PLAN.md
+Stopped at: Completed 02-02-PLAN.md
 Resume file: None
-Next action: Execute 02-02-PLAN.md (fal.ai provider)
+Next action: Execute 02-03-PLAN.md (Model caching)

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

@@ -0,0 +1,99 @@
+---
+phase: 02-model-discovery
+plan: 02
+subsystem: api
+tags: [fal, fal-ai, provider, model-discovery, api-route]
+
+# Dependency graph
+requires:
+  - phase: 01-02
+    provides: ProviderInterface, ProviderModel, registerProvider
+  - phase: 02-01
+    provides: Provider implementation pattern, API route pattern
+provides:
+  - fal.ai provider implementing ProviderInterface
+  - API route for fetching fal.ai models server-side
+  - Category-based filtering to image/video models only
+affects: [02-03, model-browser, generate-node-refactor]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [provider self-registration, API route for server-side fetching]
+
+key-files:
+  created:
+    - src/lib/providers/fal.ts
+    - src/app/api/providers/fal/models/route.ts
+  modified: []
+
+key-decisions:
+  - "fal.ai API key is optional - works without key but with rate limits"
+  - "Category filtering uses direct API parameter (not post-processing)"
+  - "Authorization header format: Key {apiKey} (different from Replicate Bearer format)"
+
+patterns-established:
+  - "fal.ai uses category field directly as ModelCapability (no inference needed)"
+  - "Optional auth pattern - isConfigured() returns true only if key exists"
+
+issues-created: []
+
+# Metrics
+duration: 5min
+completed: 2026-01-09
+---
+
+# Phase 02-02: fal.ai Provider Summary
+
+**fal.ai provider with model discovery via REST API, filtered to image/video categories, with optional API key authentication**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-01-09T execution start
+- **Completed:** 2026-01-09T execution end
+- **Tasks:** 2
+- **Files created:** 2
+
+## Accomplishments
+- Created fal.ai provider implementing full ProviderInterface contract
+- Built API route for server-side model fetching with optional API key
+- Implemented category-based filtering to text-to-image, image-to-image, text-to-video, image-to-video
+- Provider self-registers in registry when module is imported
+- Works without API key (rate limited) unlike Replicate which requires auth
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create fal.ai provider implementation** - `523bc1f` (feat)
+2. **Task 2: Create fal.ai models API route** - `3d4a97f` (feat)
+
+## Files Created/Modified
+- `src/lib/providers/fal.ts` - fal.ai provider with listModels, searchModels, getModel, isConfigured, getApiKey
+- `src/app/api/providers/fal/models/route.ts` - GET endpoint for model fetching with optional X-API-Key auth
+
+## Decisions Made
+- fal.ai category field maps directly to ModelCapability (no keyword inference needed unlike Replicate)
+- API key authentication is optional - fal.ai works without but with lower rate limits
+- Authorization header uses "Key" prefix (fal.ai format) rather than "Bearer" (Replicate format)
+- Status filter set to "active" to exclude deprecated models
+- generate() returns stub error - implementation deferred to Phase 3
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+- fal.ai provider complete and ready for use
+- Both providers (Replicate and fal.ai) now implemented
+- Model caching to be added in 02-03
+- Two different auth patterns documented (required vs optional)
+
+---
+*Phase: 02-model-discovery*
+*Completed: 2026-01-09*