docs(25-02): complete file upload UI plan — ChatFileDropZone, useChatFileUpload, ChatInput wired

- SUMMARY.md documents XHR progress pattern and backward-compatible props
- STATE.md advanced to plan 2, decisions logged, metrics recorded
- ROADMAP.md updated with 2/4 summaries complete for phase 25
- REQUIREMENTS.md marks FILE-05 complete

.planning/REQUIREMENTS.md

@@ -87,7 +87,7 @@
 - [x] **FILE-02** — libSQL `files` table tracking all file metadata: id, filename, original_filename, mime_type, size_bytes, storage_path, git_hash, checksum, dual-scope fields (project_id, conversation_id, message_id, agent_id, workspace_id, task_id), source, category, placeholder fields, and lifecycle timestamps
 - [x] **FILE-03** — libSQL `file_references` table enabling a single file to be referenced from multiple conversations without duplication
 - [ ] **FILE-04** — Dual scoping: a file uploaded during a project-linked conversation lives in `files/projects/<slug>/` but is also referenced by the chat message; a file in a general chat (no project context) lives in `files/chat/<conversation-id>/`
-- [ ] **FILE-05** — File upload from chat input via drag-and-drop or button; file is stored on disk and its metadata is written to libSQL
+- [x] **FILE-05** — File upload from chat input via drag-and-drop or button; file is stored on disk and its metadata is written to libSQL
 - [ ] **FILE-06** — Inline file preview in chat: images render inline, PDFs show a first-page preview, code files show a syntax-highlighted preview
 - [ ] **FILE-07** — One-click file download from chat for any attached or generated file
 - [ ] **FILE-08** — Agent-generated files (code output, specs, presentations) stored in `files/projects/<slug>/generated/`, linked to the originating task and conversation in libSQL
@@ -172,7 +172,7 @@ The following are explicitly deferred:
 | FILE-02 | Phase 25 | Complete |
 | FILE-03 | Phase 25 | Complete |
 | FILE-04 | Phase 25 | Pending |
-| FILE-05 | Phase 25 | Pending |
+| FILE-05 | Phase 25 | Complete |
 | FILE-06 | Phase 25 | Pending |
 | FILE-07 | Phase 25 | Pending |
 | FILE-08 | Phase 25 | Pending |

.planning/ROADMAP.md

@@ -116,12 +116,12 @@ Plans:
   5. When an agent generates a placeholder asset, `PLACEHOLDERS.md` is updated in the project directory; when the placeholder is replaced, the DB records the replacement chain and the manifest reflects the change
   6. A file uploaded in a conversation linked to a project lives in `files/projects/<slug>/`; a file from an unlinked conversation lives in `files/chat/<conversation-id>/`; the user can promote a chat file to project scope
   7. Voice input is available when local AI is enabled: user can hold the record button, speak, see a transcription preview, and confirm to send
-**Plans:** 1/4 plans executed
+**Plans:** 2/4 plans executed
 
 Plans:
 - [x] 25-00-PLAN.md — DB schema (chat_files + chat_file_references), shared types/validators, test stubs
 - [ ] 25-01-PLAN.md — Server: chatFileService + chatFileRoutes (upload, download, list, references)
-- [ ] 25-02-PLAN.md — UI: ChatInput file upload (drag-drop, paste, file picker), useChatFileUpload hook
+- [x] 25-02-PLAN.md — UI: ChatInput file upload (drag-drop, paste, file picker), useChatFileUpload hook
 - [ ] 25-03-PLAN.md — UI: ChatFilePreview/ChatFileCard components, ChatMessage/ChatPanel wiring
 
 **UI hint**: yes
@@ -222,5 +222,5 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.
 | 22. Agent Streaming | v1.3 | 6/6 | Complete    | 2026-04-01 |
 | 23. Brainstormer Flow | v1.3 | 4/4 | Complete    | 2026-04-01 |
 | 24. Search, History & Branching | v1.3 | 4/4 | Complete    | 2026-04-01 |
-| 25. File System | v1.3 | 1/4 | In Progress|  |
+| 25. File System | v1.3 | 2/4 | In Progress|  |
 | 26. PWA & Performance | v1.3 | 0/? | Not started | - |

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: milestone
 status: executing
-stopped_at: Completed 25-file-system-25-00-PLAN.md
-last_updated: "2026-04-01T23:02:27.025Z"
+stopped_at: Completed 25-file-system-25-02-PLAN.md
+last_updated: "2026-04-01T23:13:30.538Z"
 last_activity: 2026-04-01
 progress:
   total_phases: 6
   completed_phases: 4
   total_plans: 25
-  completed_plans: 22
+  completed_plans: 23
   percent: 100
 ---
 
@@ -79,6 +79,7 @@ Progress: [██████████] 100%
 | Phase 24-search-history-branching P02 | 3min | 2 tasks | 7 files |
 | Phase 24-search-history-branching P03 | 4 | 3 tasks | 7 files |
 | Phase 25-file-system P00 | 6 | 2 tasks | 11 files |
+| Phase 25-file-system P02 | 15 | 2 tasks | 5 files |
 
 ## Accumulated Context
 
@@ -136,6 +137,8 @@ Recent decisions affecting current work:
 - [Phase 25-file-system]: Used object-syntax (table) => ({}) for Drizzle index callbacks in chat_files and chat_file_references — matches existing codebase pattern
 - [Phase 25-file-system]: chatFiles uses nullable FKs (SET NULL) for conversationId/messageId — file may exist before a conversation or message is created
 - [Phase 25-file-system]: chatFileReferences uses CASCADE deletes for fileId and conversationId — reference has no meaning without both anchors
+- [Phase 25-file-system]: Used XHR instead of fetch for chatApi.uploadFile to enable upload progress events (fetch lacks upload.onprogress)
+- [Phase 25-file-system]: ChatInput onFilesPicked/pendingFiles/onRemoveFile props are all optional for backward compatibility
 
 ### Pending Todos
 
@@ -148,6 +151,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-01T23:02:27.021Z
-Stopped at: Completed 25-file-system-25-00-PLAN.md
+Last session: 2026-04-01T23:13:30.535Z
+Stopped at: Completed 25-file-system-25-02-PLAN.md
 Resume file: None

.planning/phases/25-file-system/25-02-SUMMARY.md

@@ -0,0 +1,108 @@
+---
+phase: 25-file-system
+plan: 02
+subsystem: ui
+tags: [react, file-upload, drag-and-drop, clipboard, xhr, lucide]
+
+# Dependency graph
+requires:
+  - phase: 25-file-system-00
+    provides: shared types (ChatFile, ChatFileUploadResponse), validators
+  - phase: 25-file-system-01
+    provides: server endpoint POST /api/conversations/:id/files
+provides:
+  - ChatFileDropZone component with drag-and-drop overlay
+  - useChatFileUpload hook with upload lifecycle (uploading/done/error)
+  - chatApi.uploadFile using XHR with progress callbacks
+  - ChatInput updated with file picker button, paste handler, and pending file chips
+affects: [25-03, 25-04, chat-panel-integration]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - XHR for upload progress tracking (not fetch, which lacks upload progress)
+    - PendingFile client-side state lifecycle before server confirmation
+    - ChatFileDropZone wraps children with drag overlay without breaking layout
+
+key-files:
+  created:
+    - ui/src/components/ChatFileDropZone.tsx
+    - ui/src/hooks/useChatFileUpload.ts
+  modified:
+    - ui/src/api/chat.ts
+    - ui/src/components/ChatInput.tsx
+    - ui/src/components/ChatInput.test.tsx
+
+key-decisions:
+  - "Used XHR instead of fetch for chatApi.uploadFile to enable upload progress events (fetch lacks upload.onprogress)"
+  - "ChatFileDropZone checks e.currentTarget.contains(e.relatedTarget) to avoid false drag-leave when crossing child elements"
+  - "onFilesPicked is optional — ChatInput works without file support when prop not provided (backward compatible)"
+
+patterns-established:
+  - "PendingFile pattern: temp client ID assigned immediately, replaced with server ChatFile.id on completion"
+  - "Drop zone overlay uses bg-primary/10 and border-primary for theme-neutral visual feedback"
+
+requirements-completed: [FILE-05]
+
+# Metrics
+duration: 15min
+completed: 2026-04-01
+---
+
+# Phase 25 Plan 02: File Upload UI Summary
+
+**Drag-and-drop, clipboard paste, and file picker wired into ChatInput via ChatFileDropZone and useChatFileUpload with XHR progress tracking**
+
+## Performance
+
+- **Duration:** ~15 min
+- **Started:** 2026-04-01T23:10:00Z
+- **Completed:** 2026-04-01T23:25:00Z
+- **Tasks:** 2
+- **Files modified:** 5
+
+## Accomplishments
+- chatApi.uploadFile implemented with XMLHttpRequest for upload progress callbacks
+- useChatFileUpload hook manages PendingFile lifecycle (uploading → done/error)
+- ChatFileDropZone component provides drag-over overlay with dashed border and theme-neutral colors
+- ChatInput now accepts all three file input methods: drag-and-drop, clipboard paste (onPaste), file picker (Paperclip button)
+- Pending file chips shown above textarea with spinner, progress %, and remove button
+- 3 new tests added: file attach button presence, onFilesPicked callback, pending chip rendering
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add chatApi.uploadFile and create useChatFileUpload hook** - `6a83a362` (feat)
+2. **Task 2: Create ChatFileDropZone and integrate into ChatInput** - `6b530afa` (feat)
+
+## Files Created/Modified
+- `ui/src/api/chat.ts` - Added uploadFile method using XHR with FormData and progress callbacks
+- `ui/src/hooks/useChatFileUpload.ts` - Created PendingFile state management hook
+- `ui/src/components/ChatFileDropZone.tsx` - Created drag-and-drop wrapper with overlay
+- `ui/src/components/ChatInput.tsx` - Added file props, paste handler, Paperclip button, pending chips, ChatFileDropZone wrapper
+- `ui/src/components/ChatInput.test.tsx` - Added 3 file upload tests
+
+## Decisions Made
+- Used XHR for uploadFile to get upload progress events (fetch API doesn't expose upload.onprogress)
+- ChatFileDropZone uses `e.currentTarget.contains(e.relatedTarget)` guard on dragLeave to prevent flicker when cursor moves over child elements
+- ChatInput backward-compatible: onFilesPicked/pendingFiles/onRemoveFile are all optional props
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None — no external service configuration required.
+
+## Next Phase Readiness
+- File upload UI complete; ChatPanel needs wiring to call useChatFileUpload and pass pendingFiles/onFilesPicked/onRemoveFile to ChatInput
+- Plan 25-03 (server routes) and Plan 25-04 (ChatPanel wiring) can proceed
+
+---
+*Phase: 25-file-system*
+*Completed: 2026-04-01*