diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 267087e0..0d8758ad 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -14,7 +14,7 @@ - [x] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions (completed 2026-04-01) - [x] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat (completed 2026-04-01) - [x] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks (completed 2026-04-01) -- [x] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (completed 2026-04-01) +- [ ] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress) - [ ] **Phase 26: PWA & Performance** — Service worker, Web App Manifest, responsive mobile layout, push notifications, install prompt, performance targets --- @@ -116,13 +116,18 @@ 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//`; a file from an unlinked conversation lives in `files/chat//`; 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:** 4/4 plans complete +**Plans:** 9 plans (4 complete + 5 gap closure) Plans: - [x] 25-00-PLAN.md — DB schema (chat_files + chat_file_references), shared types/validators, test stubs - [x] 25-01-PLAN.md — Server: chatFileService + chatFileRoutes (upload, download, list, references) - [x] 25-02-PLAN.md — UI: ChatInput file upload (drag-drop, paste, file picker), useChatFileUpload hook - [x] 25-03-PLAN.md — UI: ChatFilePreview/ChatFileCard components, ChatMessage/ChatPanel wiring +- [ ] 25-04-PLAN.md — Gap: Code syntax-highlighted preview (FILE-06) + admin claims (FILE-07, FILE-13) +- [ ] 25-05-PLAN.md — Gap: File scope promotion API + UI (FILE-12) +- [ ] 25-06-PLAN.md — Gap: Git integration for file operations + version history (FILE-09, FILE-10) +- [ ] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11) +- [ ] 25-08-PLAN.md — Gap: Voice input via Whisper (INPUT-04) + admin claims (INPUT-02, INPUT-03) **UI hint**: yes @@ -222,5 +227,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 | 4/4 | Complete | 2026-04-01 | +| 25. File System | v1.3 | 4/9 | Gap closure | - | | 26. PWA & Performance | v1.3 | 0/? | Not started | - | diff --git a/.planning/phases/25-file-system/25-04-PLAN.md b/.planning/phases/25-file-system/25-04-PLAN.md new file mode 100644 index 00000000..4697c38a --- /dev/null +++ b/.planning/phases/25-file-system/25-04-PLAN.md @@ -0,0 +1,174 @@ +--- +phase: 25-file-system +plan: 04 +type: execute +wave: 1 +depends_on: ["25-03"] +files_modified: + - ui/src/components/ChatFilePreview.tsx + - ui/src/components/ChatCodeFilePreview.tsx + - .planning/REQUIREMENTS.md +autonomous: true +gap_closure: true +requirements: [FILE-06, FILE-07, FILE-13] + +must_haves: + truths: + - "Code files attached to messages render with syntax highlighting in the chat" + - "FILE-07 and FILE-13 are marked Complete in REQUIREMENTS.md" + artifacts: + - path: "ui/src/components/ChatCodeFilePreview.tsx" + provides: "Syntax-highlighted code file preview component" + min_lines: 40 + - path: "ui/src/components/ChatFilePreview.tsx" + provides: "Updated preview that delegates code files to ChatCodeFilePreview" + key_links: + - from: "ui/src/components/ChatFilePreview.tsx" + to: "ui/src/components/ChatCodeFilePreview.tsx" + via: "import and render for code category" + pattern: "ChatCodeFilePreview" + - from: "ui/src/components/ChatCodeFilePreview.tsx" + to: "/api/files/:fileId/content" + via: "fetch to load file text content" + pattern: "fetch.*content" +--- + + +Add syntax-highlighted code file preview to chat messages and close administrative requirement gaps. + +Purpose: FILE-06 requires "code files show a syntax-highlighted preview" but ChatFilePreview currently renders only a ChatFileCard for code files. This plan fetches code file content via the existing GET /api/files/:fileId/content endpoint and renders it with highlight.js (already installed and used by ChatMarkdownMessage via rehype-highlight). Also formally marks FILE-07 (download) and FILE-13 (cross-device access) as Complete since they are functionally implemented. + +Output: ChatCodeFilePreview component, updated ChatFilePreview, updated REQUIREMENTS.md + + + +@$HOME/.claude/get-shit-done/workflows/execute-plan.md +@$HOME/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/25-file-system/25-03-SUMMARY.md + + + + + + Task 1: Create ChatCodeFilePreview component + ui/src/components/ChatCodeFilePreview.tsx + + - ui/src/components/ChatFilePreview.tsx + - ui/src/components/ChatCodeBlock.tsx + - ui/src/components/ChatMarkdownMessage.tsx + - ui/src/index.css (for hljs theme CSS classes) + + +Create `ui/src/components/ChatCodeFilePreview.tsx` that: + +1. Accepts props: `{ file: ChatFile; contentPath: string }` (same as ChatFilePreview) +2. Uses `useState` for `content: string | null`, `loading: boolean`, `error: boolean` +3. Uses `useEffect` to fetch `contentPath` with `credentials: "include"` and read as text. Cap at 50KB (if text.length > 50000, truncate and append `\n// ... truncated`). Set loading=false after fetch. +4. While loading, render a skeleton: `
` +5. On error, fall back to `` +6. On success, render: + - A `
` wrapper (the `paperclip-markdown` class activates existing hljs theme CSS) + - A header bar: `
` with: + - Language label from file extension (use extToLang mapping function) + - Copy button using same pattern as ChatCodeBlock (Copy/Check icons from lucide-react, navigator.clipboard.writeText) + - A `
` block. Use `hljs.highlight(content, { language: lang })` from `highlight.js/lib/core` to produce highlighted HTML. Render the highlighted output safely. hljs.highlight produces only `` tokens from source code — this is the same trust model as rehype-highlight used in ChatMarkdownMessage. If the language is not registered, fall back to `hljs.highlightAuto(content)`.
+   - Max height: `max-h-[400px] overflow-auto`
+   - Below the code block, render `` for the download button
+
+Import highlight.js: `import hljs from "highlight.js/lib/core"`. Since rehype-highlight already uses highlight.js, the package is available. Register common languages explicitly (import from highlight.js/lib/languages/...) for: typescript, javascript, python, css, json, xml, bash, sql, go, rust, java, cpp, markdown, yaml.
+
+Extension-to-language map function:
+```typescript
+function extToLang(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  const map: Record = {
+    ts: "typescript", tsx: "typescript", js: "javascript", jsx: "javascript",
+    py: "python", rb: "ruby", rs: "rust", go: "go", java: "java",
+    css: "css", html: "xml", json: "json", sh: "bash", bash: "bash",
+    yaml: "yaml", yml: "yaml", toml: "ini", md: "markdown",
+    c: "c", cpp: "cpp", cs: "csharp", kt: "kotlin", swift: "swift",
+    php: "php", sql: "sql", xml: "xml",
+  };
+  return map[ext] ?? ext;
+}
+```
+  
+  
+    cd /opt/nexus && npx tsc --noEmit -p ui/tsconfig.json 2>&1 | head -20
+  
+  
+    - File `ui/src/components/ChatCodeFilePreview.tsx` exists
+    - Contains `import hljs from` for highlight.js
+    - Contains `fetch(contentPath` for loading file content
+    - Contains `hljs.highlight` for rendering highlighted code
+    - Contains `paperclip-markdown` class on wrapper div
+    - Contains `ChatFileCard` import and render for download fallback
+    - Contains `max-h-[400px]` for scroll containment
+    - Contains `extToLang` or equivalent extension mapping function
+  
+  ChatCodeFilePreview component renders fetched code content with syntax highlighting, copy button, language label, and download card
+
+
+
+  Task 2: Wire ChatCodeFilePreview into ChatFilePreview and update REQUIREMENTS.md
+  ui/src/components/ChatFilePreview.tsx, .planning/REQUIREMENTS.md
+  
+    - ui/src/components/ChatFilePreview.tsx
+    - ui/src/components/ChatCodeFilePreview.tsx
+    - .planning/REQUIREMENTS.md
+  
+  
+1. Update `ui/src/components/ChatFilePreview.tsx`:
+   - Add import: `import { ChatCodeFilePreview } from "./ChatCodeFilePreview";`
+   - Add a new branch before the fallback return, after the image branch:
+     ```
+     if (file.category === "code") {
+       return ;
+     }
+     ```
+   - Keep the existing fallback `return ` for document/other categories
+
+2. Update `.planning/REQUIREMENTS.md`:
+   - Change FILE-07 line from `- [ ] **FILE-07**` to `- [x] **FILE-07**` (ChatFileCard implements one-click download)
+   - Change FILE-13 line from `- [ ] **FILE-13**` to `- [x] **FILE-13**` (GET /api/files/:fileId/content serves files over HTTP for cross-device access)
+   - In the Traceability table, change FILE-07 status from `Pending` to `Complete`
+   - In the Traceability table, change FILE-13 status from `Pending` to `Complete`
+  
+  
+    cd /opt/nexus && grep -n "ChatCodeFilePreview" ui/src/components/ChatFilePreview.tsx && grep "FILE-07" .planning/REQUIREMENTS.md | head -3 && grep "FILE-13" .planning/REQUIREMENTS.md | head -3
+  
+  
+    - `ui/src/components/ChatFilePreview.tsx` contains `import { ChatCodeFilePreview }`
+    - `ui/src/components/ChatFilePreview.tsx` contains `file.category === "code"` branch routing to ChatCodeFilePreview
+    - `.planning/REQUIREMENTS.md` contains `- [x] **FILE-07**`
+    - `.planning/REQUIREMENTS.md` contains `- [x] **FILE-13**`
+    - REQUIREMENTS.md Traceability table shows FILE-07 as Complete
+    - REQUIREMENTS.md Traceability table shows FILE-13 as Complete
+  
+  Code files in chat messages render with syntax highlighting; FILE-07 and FILE-13 marked Complete in REQUIREMENTS.md
+
+
+
+
+
+- `npx tsc --noEmit -p ui/tsconfig.json` passes
+- `grep "ChatCodeFilePreview" ui/src/components/ChatFilePreview.tsx` shows import and usage
+- `grep "\[x\].*FILE-07" .planning/REQUIREMENTS.md` matches
+- `grep "\[x\].*FILE-13" .planning/REQUIREMENTS.md` matches
+
+
+
+- Code file attachments in chat render with syntax-highlighted preview (not just a download card)
+- FILE-07 and FILE-13 marked Complete in REQUIREMENTS.md
+- TypeScript compiles without errors
+
+
+
+After completion, create `.planning/phases/25-file-system/25-04-SUMMARY.md`
+
diff --git a/.planning/phases/25-file-system/25-05-PLAN.md b/.planning/phases/25-file-system/25-05-PLAN.md
new file mode 100644
index 00000000..e0e27e09
--- /dev/null
+++ b/.planning/phases/25-file-system/25-05-PLAN.md
@@ -0,0 +1,239 @@
+---
+phase: 25-file-system
+plan: 05
+type: execute
+wave: 1
+depends_on: ["25-01"]
+files_modified:
+  - server/src/services/chat-files.ts
+  - server/src/routes/chat-files.ts
+  - ui/src/components/ChatFileCard.tsx
+  - ui/src/api/chat.ts
+  - .planning/REQUIREMENTS.md
+autonomous: true
+gap_closure: true
+requirements: [FILE-12]
+
+must_haves:
+  truths:
+    - "User can promote a chat-scoped file to project scope via a single action"
+    - "PATCH /files/:fileId/promote endpoint sets projectId on a chat file"
+  artifacts:
+    - path: "server/src/services/chat-files.ts"
+      provides: "promoteToProject service method"
+    - path: "server/src/routes/chat-files.ts"
+      provides: "PATCH /files/:fileId/promote endpoint"
+    - path: "ui/src/components/ChatFileCard.tsx"
+      provides: "Promote button when file has no projectId"
+  key_links:
+    - from: "ui/src/components/ChatFileCard.tsx"
+      to: "ui/src/api/chat.ts"
+      via: "chatApi.promoteFile call"
+      pattern: "promoteFile"
+    - from: "server/src/routes/chat-files.ts"
+      to: "server/src/services/chat-files.ts"
+      via: "fileSvc.promoteToProject"
+      pattern: "promoteToProject"
+---
+
+
+Add file scope promotion: a chat-scoped file can be promoted to a project scope.
+
+Purpose: FILE-12 requires that chat-scoped files can be promoted to project scope. The schema already has a nullable `projectId` FK on chatFiles, but there is no API endpoint or UI to set it. This plan adds a PATCH /files/:fileId/promote endpoint and a promote button on ChatFileCard.
+
+Output: Service method, API endpoint, UI promote button, updated REQUIREMENTS.md
+
+
+
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/25-file-system/25-01-SUMMARY.md
+
+
+From packages/db/src/schema/chat_files.ts:
+```typescript
+export const chatFiles = pgTable("chat_files", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  projectId: uuid("project_id").references(() => projects.id, { onDelete: "set null" }),
+  // ... other columns
+});
+```
+
+From server/src/services/chat-files.ts:
+```typescript
+export function chatFileService(db: Db) {
+  return {
+    create(...), getById(...), listByConversation(...), listByMessage(...),
+    createReference(...), listReferences(...), attachToMessage(...)
+  };
+}
+```
+
+From ui/src/api/chat.ts:
+```typescript
+export const chatApi = {
+  uploadFile(...), attachFilesToMessage(...)
+};
+```
+
+
+
+
+
+
+  Task 1: Add promoteToProject service method and API endpoint
+  server/src/services/chat-files.ts, server/src/routes/chat-files.ts
+  
+    - server/src/services/chat-files.ts
+    - server/src/routes/chat-files.ts
+    - packages/db/src/schema/chat_files.ts
+  
+  
+1. In `server/src/services/chat-files.ts`, add a new method `promoteToProject` to the returned object:
+```typescript
+promoteToProject(fileId: string, projectId: string) {
+  return db
+    .update(chatFiles)
+    .set({ projectId, updatedAt: new Date() })
+    .where(eq(chatFiles.id, fileId))
+    .returning()
+    .then((rows) => rows[0] ?? null);
+},
+```
+
+2. In `server/src/routes/chat-files.ts`, add a new route BEFORE the existing `PATCH /files/:fileId` route:
+```typescript
+// PATCH /files/:fileId/promote — Promote chat file to project scope
+router.patch("/files/:fileId/promote", async (req, res) => {
+  assertBoard(req);
+
+  const fileId = req.params.fileId as string;
+  const chatFile = await fileSvc.getById(fileId);
+  if (!chatFile) {
+    res.status(404).json({ error: "File not found" });
+    return;
+  }
+  assertCompanyAccess(req, chatFile.companyId);
+
+  const { projectId } = req.body ?? {};
+  if (!projectId || typeof projectId !== "string") {
+    res.status(400).json({ error: "projectId is required" });
+    return;
+  }
+
+  const updated = await fileSvc.promoteToProject(fileId, projectId);
+  if (!updated) {
+    res.status(404).json({ error: "File not found" });
+    return;
+  }
+  res.json(updated);
+});
+```
+
+Place this route BEFORE the `PATCH /files/:fileId` route so Express matches `/files/:fileId/promote` before the catch-all `/files/:fileId`.
+  
+  
+    cd /opt/nexus && grep -n "promoteToProject" server/src/services/chat-files.ts server/src/routes/chat-files.ts
+  
+  
+    - `server/src/services/chat-files.ts` contains `promoteToProject(fileId: string, projectId: string)` method
+    - `server/src/routes/chat-files.ts` contains `router.patch("/files/:fileId/promote"` route
+    - The promote route appears BEFORE the generic `router.patch("/files/:fileId"` route
+    - Route validates `projectId` is present and is a string
+    - Route calls `fileSvc.promoteToProject(fileId, projectId)`
+  
+  PATCH /files/:fileId/promote endpoint exists, validates input, updates projectId on chat file
+
+
+
+  Task 2: Add promote button to ChatFileCard and API client method
+  ui/src/api/chat.ts, ui/src/components/ChatFileCard.tsx, .planning/REQUIREMENTS.md
+  
+    - ui/src/api/chat.ts
+    - ui/src/components/ChatFileCard.tsx
+    - .planning/REQUIREMENTS.md
+  
+  
+1. In `ui/src/api/chat.ts`, add a new method to `chatApi`:
+```typescript
+promoteFile(fileId: string, projectId: string) {
+  return api.patch(`/files/${fileId}/promote`, { projectId });
+},
+```
+Also add `ChatFile` to the import from `@paperclipai/shared` if not already imported.
+
+2. In `ui/src/components/ChatFileCard.tsx`:
+   - Add optional props: `projectId?: string | null` and `onPromoted?: (file: ChatFile) => void` to ChatFileCardProps
+   - Import `FolderUp` from lucide-react (for the promote icon)
+   - Import `chatApi` from `../api/chat`
+   - Import `ChatFile` from `@paperclipai/shared`
+   - Add state: `const [promoting, setPromoting] = useState(false)`
+   - Add a promote button that appears ONLY when `file.projectId === null && projectId && onPromoted`:
+     ```tsx
+     {file.projectId === null && projectId && onPromoted && (
+       
+     )}
+     ```
+   - Place this button before the download button
+
+3. Update `.planning/REQUIREMENTS.md`:
+   - Change FILE-12 line from `- [ ] **FILE-12**` to `- [x] **FILE-12**`
+   - In Traceability table, change FILE-12 status from `Pending` to `Complete`
+  
+  
+    cd /opt/nexus && grep -n "promoteFile" ui/src/api/chat.ts && grep -n "FolderUp\|onPromoted\|promoteToProject" ui/src/components/ChatFileCard.tsx && grep "FILE-12" .planning/REQUIREMENTS.md | head -3
+  
+  
+    - `ui/src/api/chat.ts` contains `promoteFile(fileId: string, projectId: string)` method
+    - `ui/src/components/ChatFileCard.tsx` contains `FolderUp` import from lucide-react
+    - `ui/src/components/ChatFileCard.tsx` contains `onPromoted` prop
+    - `ui/src/components/ChatFileCard.tsx` contains `chatApi.promoteFile` call
+    - `ui/src/components/ChatFileCard.tsx` conditionally renders promote button only when `file.projectId === null && projectId && onPromoted`
+    - `.planning/REQUIREMENTS.md` contains `- [x] **FILE-12**`
+  
+  Chat files can be promoted to project scope via UI button; FILE-12 marked Complete
+
+
+
+
+
+- `npx tsc --noEmit -p ui/tsconfig.json` passes
+- `npx tsc --noEmit -p server/tsconfig.json` passes
+- `grep "promoteToProject" server/src/services/chat-files.ts` matches
+- `grep "promoteFile" ui/src/api/chat.ts` matches
+- `grep "\[x\].*FILE-12" .planning/REQUIREMENTS.md` matches
+
+
+
+- PATCH /files/:fileId/promote endpoint sets projectId on a chat file
+- ChatFileCard shows a promote button for chat-scoped files when a project context is available
+- FILE-12 marked Complete in REQUIREMENTS.md
+- TypeScript compiles without errors
+
+
+
+After completion, create `.planning/phases/25-file-system/25-05-SUMMARY.md`
+
diff --git a/.planning/phases/25-file-system/25-06-PLAN.md b/.planning/phases/25-file-system/25-06-PLAN.md
new file mode 100644
index 00000000..0cea6767
--- /dev/null
+++ b/.planning/phases/25-file-system/25-06-PLAN.md
@@ -0,0 +1,293 @@
+---
+phase: 25-file-system
+plan: 06
+type: execute
+wave: 1
+depends_on: ["25-01"]
+files_modified:
+  - server/src/services/git-file-service.ts
+  - server/src/routes/chat-files.ts
+  - server/src/services/chat-files.ts
+  - packages/shared/src/types/chat.ts
+  - .planning/REQUIREMENTS.md
+autonomous: true
+gap_closure: true
+requirements: [FILE-09, FILE-10]
+
+must_haves:
+  truths:
+    - "Every file upload creates a git commit in the storage directory"
+    - "User can view the git log (version history) for any file"
+  artifacts:
+    - path: "server/src/services/git-file-service.ts"
+      provides: "Git operations: init, commit, log for file versioning"
+      min_lines: 50
+    - path: "server/src/routes/chat-files.ts"
+      provides: "GET /files/:fileId/history endpoint"
+    - path: "packages/shared/src/types/chat.ts"
+      provides: "ChatFileHistoryEntry type"
+  key_links:
+    - from: "server/src/routes/chat-files.ts"
+      to: "server/src/services/git-file-service.ts"
+      via: "gitFileService.commitFile and gitFileService.getLog"
+      pattern: "gitFileService"
+    - from: "server/src/routes/chat-files.ts"
+      to: "server/src/services/chat-files.ts"
+      via: "fileSvc.getById for file lookup"
+      pattern: "fileSvc.getById"
+---
+
+
+Add git versioning for file operations and version history viewing.
+
+Purpose: FILE-09 requires every file operation to produce a git commit; FILE-10 requires users to view git log for any file. The current StorageService stores files as object-keyed blobs with no git tracking. This plan creates a gitFileService that wraps git CLI commands (init, add, commit, log) operating on the storage directory, and hooks it into the upload flow. A new GET /files/:fileId/history endpoint returns the git log for a file's object key.
+
+Output: gitFileService, updated upload route with git commit, history endpoint, ChatFileHistoryEntry type
+
+
+
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/25-file-system/25-01-SUMMARY.md
+
+
+From server/src/storage/types.ts:
+```typescript
+export interface StorageService {
+  provider: StorageProviderId;
+  putFile(input: PutFileInput): Promise;
+  getObject(companyId: string, objectKey: string): Promise;
+}
+```
+
+From server/src/routes/chat-files.ts:
+```typescript
+export function chatFileRoutes(db: Db, storage: StorageService) {
+  // POST /conversations/:id/files -- upload
+  // GET /files/:fileId/content -- download
+}
+```
+
+
+
+
+
+
+  Task 1: Create gitFileService and ChatFileHistoryEntry type
+  server/src/services/git-file-service.ts, packages/shared/src/types/chat.ts, packages/shared/src/index.ts
+  
+    - server/src/storage/local-disk-provider.ts
+    - server/src/home-paths.ts
+    - packages/shared/src/types/chat.ts
+    - packages/shared/src/index.ts
+  
+  
+1. Add `ChatFileHistoryEntry` type to `packages/shared/src/types/chat.ts`:
+```typescript
+export interface ChatFileHistoryEntry {
+  hash: string;
+  date: string;
+  message: string;
+  author: string;
+}
+```
+Export it from `packages/shared/src/index.ts` alongside other chat types.
+
+2. Create `server/src/services/git-file-service.ts`:
+
+Use `node:child_process` `execFile` (NOT `exec`) to prevent shell injection. All arguments are passed as array elements, never interpolated into a shell string. The `objectKey` is always a StorageService-generated path (companyId/namespace/date/uuid-filename) so it contains no shell metacharacters, but using execFile provides defense-in-depth.
+
+```typescript
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const execFile = promisify(execFileCb);
+
+export interface GitFileService {
+  ensureRepo(storageDir: string): Promise;
+  commitFile(storageDir: string, objectKey: string, message: string): Promise;
+  getLog(storageDir: string, objectKey: string, limit?: number): Promise>;
+}
+
+export function gitFileService(): GitFileService {
+  async function git(cwd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+    return execFile("git", args, { cwd, timeout: 10000 });
+  }
+
+  return {
+    async ensureRepo(storageDir: string) {
+      const gitDir = path.join(storageDir, ".git");
+      if (existsSync(gitDir)) return;
+      await git(storageDir, ["init"]);
+      await git(storageDir, ["config", "user.email", "nexus@local"]);
+      await git(storageDir, ["config", "user.name", "Nexus File System"]);
+    },
+
+    async commitFile(storageDir: string, objectKey: string, message: string): Promise {
+      const filePath = path.join(storageDir, objectKey);
+      if (!existsSync(filePath)) return null;
+
+      await this.ensureRepo(storageDir);
+
+      try {
+        await git(storageDir, ["add", "--", objectKey]);
+        const { stdout } = await git(storageDir, ["commit", "-m", message, "--", objectKey]);
+        const match = /\[[\w\s]+\s([a-f0-9]+)\]/.exec(stdout);
+        return match?.[1] ?? null;
+      } catch (err) {
+        const errMsg = String((err as { stderr?: string }).stderr ?? (err as Error).message ?? "");
+        if (errMsg.includes("nothing to commit") || errMsg.includes("no changes added")) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async getLog(storageDir: string, objectKey: string, limit = 50) {
+      try {
+        await this.ensureRepo(storageDir);
+        const { stdout } = await git(storageDir, [
+          "log",
+          `--max-count=${limit}`,
+          "--format=%H|%aI|%s|%an",
+          "--",
+          objectKey,
+        ]);
+
+        return stdout
+          .trim()
+          .split("\n")
+          .filter(Boolean)
+          .map((line) => {
+            const [hash, date, message, author] = line.split("|");
+            return { hash: hash!, date: date!, message: message!, author: author! };
+          });
+      } catch {
+        return [];
+      }
+    },
+  };
+}
+```
+  
+  
+    cd /opt/nexus && npx tsc --noEmit -p server/tsconfig.json 2>&1 | head -10 && grep "ChatFileHistoryEntry" packages/shared/src/types/chat.ts packages/shared/src/index.ts
+  
+  
+    - File `server/src/services/git-file-service.ts` exists
+    - Contains `export function gitFileService(): GitFileService`
+    - Contains `ensureRepo`, `commitFile`, `getLog` methods
+    - Uses `execFile` from `node:child_process` (NOT `exec`) -- promisified via `node:util`
+    - Does NOT use template string interpolation for shell commands
+    - `packages/shared/src/types/chat.ts` contains `export interface ChatFileHistoryEntry`
+    - `packages/shared/src/index.ts` exports `ChatFileHistoryEntry`
+  
+  gitFileService created with init/commit/log operations using safe execFile; ChatFileHistoryEntry type exported from shared
+
+
+
+  Task 2: Wire git commits into upload flow and add history endpoint
+  server/src/routes/chat-files.ts, .planning/REQUIREMENTS.md
+  
+    - server/src/routes/chat-files.ts
+    - server/src/services/git-file-service.ts
+    - server/src/storage/local-disk-provider.ts
+    - server/src/home-paths.ts
+    - .planning/REQUIREMENTS.md
+  
+  
+1. Update `server/src/routes/chat-files.ts`:
+
+   a. Import gitFileService:
+   ```typescript
+   import { gitFileService } from "../services/git-file-service.js";
+   ```
+   Also import `path` from `node:path`.
+
+   b. Determine the storage directory. Read `server/src/storage/local-disk-provider.ts` to find how it resolves the base directory. Read `server/src/home-paths.ts` to understand how the root is resolved. Inside `chatFileRoutes` function body, compute the storage root path that matches where LocalDiskProvider writes files. For example:
+   ```typescript
+   import { getHomePath } from "../home-paths.js";
+   // Adapt to match local-disk-provider.ts directory construction
+   const storageDir = path.join(getHomePath(), "data", "storage");
+   ```
+   **IMPORTANT**: Read local-disk-provider.ts first and use the EXACT same path construction it uses. Do not guess.
+
+   Inside `chatFileRoutes`:
+   ```typescript
+   const gitSvc = gitFileService();
+   ```
+
+   c. After the `storage.putFile()` call and DB record creation in POST /conversations/:id/files, add a git commit (fire-and-forget to not block the response):
+   ```typescript
+   // Git-track the uploaded file (non-blocking)
+   gitSvc.commitFile(storageDir, stored.objectKey, `Upload: ${file.originalname ?? "file"}`).catch(() => {});
+   ```
+
+   d. Add a new route for version history, placed near the GET /files/:fileId/content route:
+   ```typescript
+   // GET /files/:fileId/history -- Git version history for a file
+   router.get("/files/:fileId/history", async (req, res) => {
+     assertBoard(req);
+
+     const fileId = req.params.fileId as string;
+     const chatFile = await fileSvc.getById(fileId);
+     if (!chatFile) {
+       res.status(404).json({ error: "File not found" });
+       return;
+     }
+     assertCompanyAccess(req, chatFile.companyId);
+
+     const limit = Math.min(parseInt(req.query.limit as string) || 50, 100);
+     const entries = await gitSvc.getLog(storageDir, chatFile.objectKey, limit);
+     res.json({ items: entries });
+   });
+   ```
+   Place this BEFORE the `/files/:fileId/content` route so Express matches `/files/:fileId/history` before any catch-all.
+
+2. Update `.planning/REQUIREMENTS.md`:
+   - Change FILE-09 from `- [ ] **FILE-09**` to `- [x] **FILE-09**`
+   - Change FILE-10 from `- [ ] **FILE-10**` to `- [x] **FILE-10**`
+   - In Traceability table, change FILE-09 and FILE-10 status from `Pending` to `Complete`
+  
+  
+    cd /opt/nexus && grep -n "gitFileService\|gitSvc\|commitFile\|getLog\|/history" server/src/routes/chat-files.ts && grep "FILE-09\|FILE-10" .planning/REQUIREMENTS.md | head -6
+  
+  
+    - `server/src/routes/chat-files.ts` imports `gitFileService`
+    - Contains `gitSvc.commitFile(storageDir` call after `storage.putFile`
+    - Contains `router.get("/files/:fileId/history"` route
+    - History route calls `gitSvc.getLog` and returns `{ items: entries }`
+    - `.planning/REQUIREMENTS.md` contains `- [x] **FILE-09**`
+    - `.planning/REQUIREMENTS.md` contains `- [x] **FILE-10**`
+  
+  File uploads create git commits; version history available via GET /files/:fileId/history; FILE-09 and FILE-10 marked Complete
+
+
+
+
+
+- `npx tsc --noEmit -p server/tsconfig.json` passes
+- `grep "commitFile" server/src/routes/chat-files.ts` matches
+- `grep "/history" server/src/routes/chat-files.ts` matches
+- `grep "\[x\].*FILE-09" .planning/REQUIREMENTS.md` matches
+- `grep "\[x\].*FILE-10" .planning/REQUIREMENTS.md` matches
+
+
+
+- File upload creates a git commit in the storage directory
+- GET /files/:fileId/history returns git log entries for a file
+- TypeScript compiles without errors
+- FILE-09 and FILE-10 marked Complete in REQUIREMENTS.md
+
+
+
+After completion, create `.planning/phases/25-file-system/25-06-SUMMARY.md`
+
diff --git a/.planning/phases/25-file-system/25-07-PLAN.md b/.planning/phases/25-file-system/25-07-PLAN.md
new file mode 100644
index 00000000..921d53ae
--- /dev/null
+++ b/.planning/phases/25-file-system/25-07-PLAN.md
@@ -0,0 +1,273 @@
+---
+phase: 25-file-system
+plan: 07
+type: execute
+wave: 2
+depends_on: ["25-06"]
+files_modified:
+  - server/src/services/chat-files.ts
+  - server/src/routes/chat-files.ts
+  - server/src/services/placeholder-service.ts
+  - packages/shared/src/types/chat.ts
+  - .planning/REQUIREMENTS.md
+autonomous: true
+gap_closure: true
+requirements: [FILE-08, FILE-11]
+
+must_haves:
+  truths:
+    - "Agent-generated files are stored via the upload API with source=agent_generated and linked to task/conversation"
+    - "Placeholder files are tracked in a PLACEHOLDERS.md manifest in the project directory"
+    - "Replacing a placeholder updates the manifest and records the replacement chain in the DB"
+  artifacts:
+    - path: "server/src/services/placeholder-service.ts"
+      provides: "PLACEHOLDERS.md manifest management: add, remove, replace entries"
+      min_lines: 40
+    - path: "server/src/services/chat-files.ts"
+      provides: "markAsPlaceholder method"
+    - path: "server/src/routes/chat-files.ts"
+      provides: "POST /files/:fileId/replace endpoint for placeholder replacement"
+  key_links:
+    - from: "server/src/routes/chat-files.ts"
+      to: "server/src/services/placeholder-service.ts"
+      via: "placeholderService.addEntry and replaceEntry"
+      pattern: "placeholderService"
+---
+
+
+Add agent-generated file support and placeholder asset tracking.
+
+Purpose: FILE-08 requires agent-generated files to be stored and linked to tasks/conversations. FILE-11 requires a PLACEHOLDERS.md manifest tracking placeholder assets with replacement chains. The upload API already supports source: "agent_generated" but no code path uses it, and no placeholder tracking exists.
+
+Output: Placeholder service, replace endpoint, updated service methods, updated REQUIREMENTS.md
+
+
+
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/25-file-system/25-01-SUMMARY.md
+
+
+From packages/db/src/schema/chat_files.ts:
+```typescript
+export const chatFiles = pgTable("chat_files", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  source: text("source").notNull(),
+  category: text("category"),
+  projectId: uuid("project_id").references(() => projects.id, { onDelete: "set null" }),
+});
+```
+
+From server/src/services/chat-files.ts:
+```typescript
+export function chatFileService(db: Db) {
+  return { create(...), getById(...), attachToMessage(...), promoteToProject(...), createReference(...) };
+}
+```
+
+From packages/shared/src/validators/chat.ts:
+```typescript
+source: z.enum(["user_upload", "agent_generated"]).default("user_upload"),
+```
+
+
+
+
+
+
+  Task 1: Create placeholderService and add markAsPlaceholder method
+  server/src/services/placeholder-service.ts, server/src/services/chat-files.ts, packages/shared/src/types/chat.ts, packages/shared/src/index.ts
+  
+    - server/src/services/chat-files.ts
+    - packages/shared/src/types/chat.ts
+    - packages/shared/src/index.ts
+    - packages/db/src/schema/chat_files.ts
+    - server/src/home-paths.ts
+  
+  
+1. Add ChatPlaceholderEntry type to packages/shared/src/types/chat.ts:
+```typescript
+export interface ChatPlaceholderEntry {
+  fileId: string;
+  filename: string;
+  description: string;
+  createdAt: string;
+  replacedByFileId?: string;
+}
+```
+Export from packages/shared/src/index.ts alongside other chat types.
+
+2. Create server/src/services/placeholder-service.ts with three methods:
+
+addEntry(projectDir, entry): Reads existing PLACEHOLDERS.md (or creates new), adds entry to Active Placeholders table, writes back.
+
+replaceEntry(projectDir, oldFileId, newFileId): Reads PLACEHOLDERS.md, moves the entry from Active to Replaced section with replacedByFileId, writes back.
+
+listEntries(projectDir): Reads and returns parsed entries.
+
+The PLACEHOLDERS.md format:
+```markdown
+# Placeholder Assets
+
+Auto-maintained by Nexus. Do not edit manually.
+
+## Active Placeholders
+
+| File | Description | File ID |
+|------|-------------|---------|
+| logo.png | Generated by agent | abc-123 |
+
+## Replaced
+
+| Original | Description | Replaced By |
+|----------|-------------|-------------|
+| old-logo.png | Generated by agent | def-456 |
+```
+
+Use readFile/writeFile from node:fs/promises. Use existsSync to check if file exists. Use mkdir with recursive:true to ensure projectDir exists before writing.
+
+The serialize function builds the markdown table strings from an array of PlaceholderEntry objects ({ fileId, filename, description, replacedByFileId? }).
+
+The parse function reads markdown tables using a regex like /^\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/ to extract rows, tracking which section (Active vs Replaced) each row belongs to.
+
+3. In server/src/services/chat-files.ts, add markAsPlaceholder method to the returned object:
+```typescript
+markAsPlaceholder(fileId: string) {
+  return db
+    .update(chatFiles)
+    .set({ category: "placeholder", updatedAt: new Date() })
+    .where(eq(chatFiles.id, fileId))
+    .returning()
+    .then((rows) => rows[0] ?? null);
+},
+```
+  
+  
+    cd /opt/nexus && test -f server/src/services/placeholder-service.ts && echo "placeholder-service exists" && grep "ChatPlaceholderEntry" packages/shared/src/types/chat.ts && grep "markAsPlaceholder" server/src/services/chat-files.ts
+  
+  
+    - File server/src/services/placeholder-service.ts exists
+    - Contains addEntry, replaceEntry, listEntries exported methods
+    - Generates PLACEHOLDERS.md with Active Placeholders and Replaced markdown tables
+    - packages/shared/src/types/chat.ts contains export interface ChatPlaceholderEntry
+    - packages/shared/src/index.ts exports ChatPlaceholderEntry
+    - server/src/services/chat-files.ts contains markAsPlaceholder method
+  
+  PlaceholderService manages PLACEHOLDERS.md manifest; chatFileService has markAsPlaceholder method
+
+
+
+  Task 2: Add placeholder and agent-generated file routes
+  server/src/routes/chat-files.ts, .planning/REQUIREMENTS.md
+  
+    - server/src/routes/chat-files.ts
+    - server/src/services/placeholder-service.ts
+    - server/src/services/chat-files.ts
+    - server/src/services/git-file-service.ts
+    - server/src/home-paths.ts
+    - .planning/REQUIREMENTS.md
+  
+  
+1. Update server/src/routes/chat-files.ts:
+
+   a. Import placeholderService:
+   ```typescript
+   import { placeholderService } from "../services/placeholder-service.js";
+   ```
+
+   b. Inside chatFileRoutes, instantiate:
+   ```typescript
+   const phSvc = placeholderService();
+   ```
+
+   c. In the existing POST /conversations/:id/files upload route, after creating the chatFile DB record (after the git commit line from Plan 25-06), add placeholder handling:
+   ```typescript
+   // Track placeholder if agent-generated and project-scoped
+   if (parsedMeta.data.source === "agent_generated" && chatFile.projectId) {
+     const projectDir = path.join(storageDir, "..", "..", "projects", chatFile.projectId);
+     phSvc.addEntry(projectDir, {
+       fileId: chatFile.id,
+       filename: chatFile.originalFilename,
+       description: "Generated by agent",
+     }).catch(() => {});
+   }
+   ```
+
+   d. Add POST /files/:fileId/replace endpoint for replacing a placeholder with a final asset. Place it near other /files/:fileId routes:
+   ```typescript
+   router.post("/files/:fileId/replace", async (req, res) => {
+     assertBoard(req);
+     const fileId = req.params.fileId as string;
+     const oldFile = await fileSvc.getById(fileId);
+     if (!oldFile) { res.status(404).json({ error: "File not found" }); return; }
+     assertCompanyAccess(req, oldFile.companyId);
+
+     const { newFileId } = req.body ?? {};
+     if (!newFileId || typeof newFileId !== "string") {
+       res.status(400).json({ error: "newFileId is required" }); return;
+     }
+     const newFile = await fileSvc.getById(newFileId);
+     if (!newFile) { res.status(404).json({ error: "Replacement file not found" }); return; }
+
+     // Update placeholder manifest if project-scoped
+     if (oldFile.projectId) {
+       const projectDir = path.join(storageDir, "..", "..", "projects", oldFile.projectId);
+       await phSvc.replaceEntry(projectDir, fileId, newFileId);
+     }
+
+     // Create reference linking replacement to original context
+     await fileSvc.createReference({
+       fileId: newFileId,
+       conversationId: oldFile.conversationId ?? "",
+       messageId: oldFile.messageId ?? undefined,
+     });
+
+     res.json({ replaced: fileId, replacedBy: newFileId });
+   });
+   ```
+
+2. Update .planning/REQUIREMENTS.md:
+   - Change FILE-08 from `- [ ] **FILE-08**` to `- [x] **FILE-08**`
+   - Change FILE-11 from `- [ ] **FILE-11**` to `- [x] **FILE-11**`
+   - In Traceability table, change FILE-08 and FILE-11 from Pending to Complete
+  
+  
+    cd /opt/nexus && grep -n "placeholderService\|phSvc\|replace\|agent_generated" server/src/routes/chat-files.ts | head -10 && grep "FILE-08\|FILE-11" .planning/REQUIREMENTS.md | head -6
+  
+  
+    - server/src/routes/chat-files.ts imports placeholderService
+    - Contains phSvc.addEntry call for agent_generated files with projectId
+    - Contains router.post("/files/:fileId/replace") endpoint
+    - Replace endpoint calls phSvc.replaceEntry and fileSvc.createReference
+    - .planning/REQUIREMENTS.md contains `- [x] **FILE-08**`
+    - .planning/REQUIREMENTS.md contains `- [x] **FILE-11**`
+  
+  Agent-generated files trigger placeholder manifest update; replacement endpoint exists; FILE-08 and FILE-11 marked Complete
+
+
+
+
+
+- npx tsc --noEmit -p server/tsconfig.json passes
+- grep "placeholderService" server/src/routes/chat-files.ts matches
+- grep "/replace" server/src/routes/chat-files.ts matches
+- grep "\[x\].*FILE-08" .planning/REQUIREMENTS.md matches
+- grep "\[x\].*FILE-11" .planning/REQUIREMENTS.md matches
+
+
+
+- Agent-generated files uploaded with source=agent_generated trigger PLACEHOLDERS.md update when project-scoped
+- POST /files/:fileId/replace updates manifest and creates reference chain
+- FILE-08 and FILE-11 marked Complete in REQUIREMENTS.md
+- TypeScript compiles without errors
+
+
+
+After completion, create `.planning/phases/25-file-system/25-07-SUMMARY.md`
+
diff --git a/.planning/phases/25-file-system/25-08-PLAN.md b/.planning/phases/25-file-system/25-08-PLAN.md
new file mode 100644
index 00000000..9be36e67
--- /dev/null
+++ b/.planning/phases/25-file-system/25-08-PLAN.md
@@ -0,0 +1,369 @@
+---
+phase: 25-file-system
+plan: 08
+type: execute
+wave: 1
+depends_on: ["25-02"]
+files_modified:
+  - ui/src/components/VoiceRecordButton.tsx
+  - ui/src/components/ChatInput.tsx
+  - server/src/routes/chat-files.ts
+  - .planning/REQUIREMENTS.md
+autonomous: true
+gap_closure: true
+requirements: [INPUT-02, INPUT-03, INPUT-04]
+
+must_haves:
+  truths:
+    - "User can hold a record button to capture voice audio"
+    - "Recorded audio is sent to the server for transcription"
+    - "Transcription preview appears in the chat input before sending"
+  artifacts:
+    - path: "ui/src/components/VoiceRecordButton.tsx"
+      provides: "Voice recording button with MediaRecorder API, preview, and confirm flow"
+      min_lines: 60
+    - path: "server/src/routes/chat-files.ts"
+      provides: "POST /transcribe endpoint for audio transcription"
+  key_links:
+    - from: "ui/src/components/ChatInput.tsx"
+      to: "ui/src/components/VoiceRecordButton.tsx"
+      via: "import and render in input toolbar"
+      pattern: "VoiceRecordButton"
+    - from: "ui/src/components/VoiceRecordButton.tsx"
+      to: "/api/transcribe"
+      via: "fetch POST with audio blob"
+      pattern: "fetch.*transcribe"
+---
+
+
+Add voice input with transcription preview to the chat input.
+
+Purpose: INPUT-04 requires voice input via Whisper when local AI is enabled: user can hold a record button, speak, see a transcription preview, and confirm to send. This plan creates a VoiceRecordButton component using the browser MediaRecorder API, a server transcription endpoint that calls a local Whisper process, and wires the transcription result into the chat input textarea.
+
+Output: VoiceRecordButton component, server transcription endpoint, ChatInput integration
+
+
+
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/25-file-system/25-02-SUMMARY.md
+
+
+From ui/src/components/ChatInput.tsx:
+- Props include onSend(content: string), onFilesPicked, pendingFiles, onRemoveFile
+- Contains Paperclip button for file upload in the button row
+- Textarea with handleKeyDown and handlePaste
+
+From server/src/routes/chat-files.ts:
+- chatFileRoutes(db, storage) returns Express Router
+- Uses multer for file upload, assertBoard for auth
+
+
+
+
+
+
+  Task 1: Create VoiceRecordButton and server transcription endpoint
+  ui/src/components/VoiceRecordButton.tsx, server/src/routes/chat-files.ts
+  
+    - ui/src/components/ChatInput.tsx
+    - server/src/routes/chat-files.ts
+    - server/src/attachment-types.ts
+  
+  
+1. Create ui/src/components/VoiceRecordButton.tsx:
+
+```typescript
+import { useState, useRef, useCallback } from "react";
+import { Mic, Square, Loader2 } from "lucide-react";
+import { Button } from "./ui/button";
+
+interface VoiceRecordButtonProps {
+  onTranscription: (text: string) => void;
+  disabled?: boolean;
+}
+
+export function VoiceRecordButton({ onTranscription, disabled }: VoiceRecordButtonProps) {
+  const [recording, setRecording] = useState(false);
+  const [transcribing, setTranscribing] = useState(false);
+  const mediaRecorderRef = useRef(null);
+  const chunksRef = useRef([]);
+
+  const startRecording = useCallback(async () => {
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      const mediaRecorder = new MediaRecorder(stream, {
+        mimeType: MediaRecorder.isTypeSupported("audio/webm;codecs=opus")
+          ? "audio/webm;codecs=opus"
+          : "audio/webm",
+      });
+
+      chunksRef.current = [];
+      mediaRecorder.ondataavailable = (e) => {
+        if (e.data.size > 0) chunksRef.current.push(e.data);
+      };
+
+      mediaRecorder.onstop = async () => {
+        stream.getTracks().forEach((t) => t.stop());
+        const blob = new Blob(chunksRef.current, { type: "audio/webm" });
+        if (blob.size === 0) return;
+
+        setTranscribing(true);
+        try {
+          const formData = new FormData();
+          formData.append("audio", blob, "recording.webm");
+
+          const res = await fetch("/api/transcribe", {
+            method: "POST",
+            credentials: "include",
+            body: formData,
+          });
+
+          if (res.ok) {
+            const data = (await res.json()) as { text: string };
+            if (data.text?.trim()) {
+              onTranscription(data.text.trim());
+            }
+          }
+        } finally {
+          setTranscribing(false);
+        }
+      };
+
+      mediaRecorderRef.current = mediaRecorder;
+      mediaRecorder.start(250); // 250ms chunks
+      setRecording(true);
+    } catch {
+      // Microphone permission denied or unavailable
+    }
+  }, [onTranscription]);
+
+  const stopRecording = useCallback(() => {
+    if (mediaRecorderRef.current?.state === "recording") {
+      mediaRecorderRef.current.stop();
+      mediaRecorderRef.current = null;
+    }
+    setRecording(false);
+  }, []);
+
+  if (transcribing) {
+    return (
+      
+    );
+  }
+
+  if (recording) {
+    return (
+      
+    );
+  }
+
+  return (
+    
+  );
+}
+```
+
+2. In server/src/routes/chat-files.ts, add a transcription endpoint. This endpoint receives audio via multer, writes it to a temp file, and shells out to the `whisper` CLI (from OpenAI's whisper or whisper.cpp). If whisper is not installed, return a 503 with a helpful message.
+
+Add this route inside chatFileRoutes, after the file upload routes:
+
+```typescript
+// POST /transcribe -- Transcribe audio via local Whisper
+router.post("/transcribe", async (req, res) => {
+  assertBoard(req);
+
+  try {
+    await runSingleFileUpload(fileUpload, req, res);
+  } catch (err) {
+    if (err instanceof multer.MulterError) {
+      res.status(400).json({ error: err.message });
+      return;
+    }
+    throw err;
+  }
+
+  const file = (req as Request & { file?: { buffer: Buffer; mimetype: string } }).file;
+  if (!file) {
+    res.status(400).json({ error: "Missing audio field" });
+    return;
+  }
+
+  // Write to temp file
+  const { writeFile, unlink } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const tmpPath = path.join(tmpdir(), `nexus-audio-${Date.now()}.webm`);
+
+  try {
+    await writeFile(tmpPath, file.buffer);
+
+    // Try whisper CLI (whisper.cpp or openai-whisper)
+    const { promisify } = await import("node:util");
+    const { execFile: execFileCb } = await import("node:child_process");
+    const execFileAsync = promisify(execFileCb);
+
+    try {
+      // Try whisper.cpp first (outputs to stdout with --output-txt --output-file -)
+      const { stdout } = await execFileAsync("whisper-cpp", [
+        "--model", "base.en",
+        "--file", tmpPath,
+        "--no-timestamps",
+        "--output-txt",
+      ], { timeout: 30000 });
+      res.json({ text: stdout.trim() });
+    } catch {
+      try {
+        // Fallback: openai-whisper Python CLI
+        const { stdout } = await execFileAsync("whisper", [
+          tmpPath,
+          "--model", "base.en",
+          "--output_format", "txt",
+          "--output_dir", tmpdir(),
+        ], { timeout: 60000 });
+        // whisper CLI outputs to a .txt file
+        const txtPath = tmpPath.replace(/\.webm$/, ".txt");
+        try {
+          const { readFile } = await import("node:fs/promises");
+          const text = await readFile(txtPath, "utf-8");
+          await unlink(txtPath).catch(() => {});
+          res.json({ text: text.trim() });
+        } catch {
+          // Parse stdout as fallback
+          res.json({ text: stdout.trim() });
+        }
+      } catch {
+        res.status(503).json({
+          error: "Whisper not available. Install whisper-cpp or openai-whisper for voice input.",
+        });
+      }
+    }
+  } finally {
+    await unlink(tmpPath).catch(() => {});
+  }
+});
+```
+
+Note: This uses execFileAsync (promisified execFile) -- NOT exec -- to avoid shell injection. The tmpPath is system-generated and safe.
+  
+  
+    cd /opt/nexus && test -f ui/src/components/VoiceRecordButton.tsx && echo "VoiceRecordButton exists" && grep -n "transcribe" server/src/routes/chat-files.ts | head -5
+  
+  
+    - File ui/src/components/VoiceRecordButton.tsx exists
+    - Contains MediaRecorder API usage (navigator.mediaDevices.getUserMedia)
+    - Contains fetch("/api/transcribe") call
+    - Contains recording/transcribing/idle states with Mic/Square/Loader2 icons
+    - server/src/routes/chat-files.ts contains router.post("/transcribe") endpoint
+    - Transcription endpoint uses execFileAsync (safe, no shell) for whisper CLI
+    - Returns 503 with helpful message if whisper is not installed
+  
+  VoiceRecordButton captures audio and sends to /api/transcribe; server transcription endpoint processes via local Whisper
+
+
+
+  Task 2: Wire VoiceRecordButton into ChatInput and update REQUIREMENTS.md
+  ui/src/components/ChatInput.tsx, .planning/REQUIREMENTS.md
+  
+    - ui/src/components/ChatInput.tsx
+    - ui/src/components/VoiceRecordButton.tsx
+    - .planning/REQUIREMENTS.md
+  
+  
+1. Update ui/src/components/ChatInput.tsx:
+   - Import VoiceRecordButton: `import { VoiceRecordButton } from "./VoiceRecordButton";`
+   - Add an optional prop `enableVoiceInput?: boolean` to ChatInput's props interface
+   - Add a handler that inserts transcription text into the textarea:
+     ```typescript
+     const handleTranscription = useCallback((text: string) => {
+       // Append transcription to current input value
+       const textarea = textareaRef.current;
+       if (textarea) {
+         const current = textarea.value;
+         const newValue = current ? `${current} ${text}` : text;
+         // Trigger onChange through native input event for controlled components
+         const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+           window.HTMLTextAreaElement.prototype, "value"
+         )?.set;
+         nativeInputValueSetter?.call(textarea, newValue);
+         textarea.dispatchEvent(new Event("input", { bubbles: true }));
+         textarea.focus();
+       }
+     }, []);
+     ```
+     Alternatively, if ChatInput uses a state variable for the input value, just update that state directly. Read ChatInput.tsx first to determine the correct approach.
+   - Render VoiceRecordButton in the button row (next to the Paperclip button), only when `enableVoiceInput` is true:
+     ```tsx
+     {enableVoiceInput && (
+       
+     )}
+     ```
+
+2. Update .planning/REQUIREMENTS.md:
+   - Change INPUT-04 from `- [ ] **INPUT-04**` to `- [x] **INPUT-04**`
+   - In Traceability table, change INPUT-04 from Pending to Complete
+   - Also change INPUT-02 and INPUT-03 from Pending to Complete if not already (they were implemented in Plan 25-02)
+  
+  
+    cd /opt/nexus && grep -n "VoiceRecordButton\|enableVoiceInput\|handleTranscription" ui/src/components/ChatInput.tsx | head -5 && grep "INPUT-02\|INPUT-03\|INPUT-04" .planning/REQUIREMENTS.md | head -6
+  
+  
+    - ui/src/components/ChatInput.tsx imports VoiceRecordButton
+    - Contains enableVoiceInput prop in the props interface
+    - Contains handleTranscription callback that inserts text into textarea
+    - Renders VoiceRecordButton conditionally when enableVoiceInput is true
+    - .planning/REQUIREMENTS.md contains `- [x] **INPUT-02**`
+    - .planning/REQUIREMENTS.md contains `- [x] **INPUT-03**`
+    - .planning/REQUIREMENTS.md contains `- [x] **INPUT-04**`
+  
+  Voice input button in chat input; transcription inserts into textarea; INPUT-02/03/04 marked Complete
+
+
+
+
+
+- npx tsc --noEmit -p ui/tsconfig.json passes
+- grep "VoiceRecordButton" ui/src/components/ChatInput.tsx matches
+- grep "\[x\].*INPUT-04" .planning/REQUIREMENTS.md matches
+
+
+
+- VoiceRecordButton appears in ChatInput when voice input is enabled
+- Recording captures audio, sends to /api/transcribe, and inserts result into textarea
+- Server returns transcription via local Whisper (or 503 if not installed)
+- INPUT-02, INPUT-03, INPUT-04 marked Complete in REQUIREMENTS.md
+- TypeScript compiles without errors
+
+
+
+After completion, create `.planning/phases/25-file-system/25-08-SUMMARY.md`
+