vibe-coding-master 0.0.8 → 0.0.10

package/docs/v1-architecture-design.md

@@ -21,7 +21,7 @@ Runtime shape:
 ```text
 browser
   -> React GUI
-  -> HTTP API + WebSocket
+  -> HTTP API + terminal WebSocket
   -> Fastify backend
   -> services
   -> node-pty
@@ -94,9 +94,9 @@ Responsibilities:
 - Render repository connect form.
 - Render repository summary.
 - Render workflow panel.
-- Render settings section with Messages, Events, Auto orchestration.
+- Render settings section with Theme, Messages, Events, Auto orchestration.
 - Render harness status/actions.
-- Render task creation form with one task-name field, a checked non-optional worktree/branch indicator, and generated branch/path previews.
+- Render task creation form with one task-name field, a `Create worktree and branch` checkbox selected by default, and generated branch/path previews when selected.
 - Render task list.
 - Render Messages and Events modals.
 
@@ -140,11 +140,12 @@ File:
 Responsibilities:
 
 - Load translation settings and prompt previews.
-- Open translation WebSocket for the current terminal runtime session id.
+- Start backend transcript listening for the current terminal runtime session id.
+- Poll backend translation events with a cursor.
 - Render dark translation output panel.
 - Render translation status: `ready`, `translating <elapsed>`, or `error`.
 - Render preserved tool output as dim one-line rows.
-- Render prose source while translating, then translated text after completion.
+- Render prose source while translating, then translated text after completion, using Markdown rendering for prose.
 - Render user composer.
 - Translate on `Enter`; newline on `Shift+Enter`.
 - Replace Chinese input with English draft after translation.
@@ -186,7 +187,6 @@ Fastify registers:
 - message routes
 - translation routes
 - terminal WebSocket
-- translation WebSocket
 
 ## 5. Repository Connection
 
@@ -202,7 +202,7 @@ POST /api/projects/connect
   -> resolve path
   -> check path exists
   -> check .git marker directly
-  -> create .ai/vcm/config.json
+  -> create ~/.vcm/projects/<project-id>/config.json
   -> ensure .ai/vcm state dirs
   -> read branch and dirty state
   -> record recent repo path in ~/.vcm/settings.json
@@ -224,12 +224,12 @@ VCM does not require global `safe.directory` configuration.
 
 ## 6. Task Worktree Architecture
 
-Task-level worktree management is the current architecture for multi-task parallelism.
+Task-level worktree management is the default architecture for multi-task parallelism.
 
 Rule:
 
 ```text
-one VCM task = one branch + one git worktree + one handoff directory + one role-session set
+default VCM task = one branch + one git worktree + one handoff directory + one role-session set
 ```
 
 Branch name:
@@ -244,7 +244,15 @@ Worktree path:
 <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
 ```
 
-VCM does not support switching a task to another branch or worktree after creation. If the user needs a different branch/worktree, they should create a new task.
+VCM does not support switching a task to another branch or worktree mode after creation. If the user needs a different branch/worktree choice, they should create a new task.
+
+When `Create worktree and branch` is cleared, the task uses:
+
+```text
+branch: current connected-repo branch
+runtime repo root: <baseRepoRoot>
+worktreePath: undefined
+```
 
 VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
 
@@ -265,24 +273,33 @@ VCM distinguishes:
 - `branch`: `feature/<taskSlug>`.
 - `worktreePath`: same as `taskRepoRoot`.
 
-Project-level VCM control state stays under the base repo:
+Base repo state is only the task index and the container for nested task worktrees:
 
 ```text
-<baseRepoRoot>/.ai/vcm/config.json
 <baseRepoRoot>/.ai/vcm/tasks/<task>.json
-<baseRepoRoot>/.ai/vcm/sessions/<task>.json
-<baseRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<baseRepoRoot>/.ai/vcm/orchestration/<task>.json
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/
 ```
 
-Task source changes and handoff artifacts live in the task worktree:
+Project configuration is app-local and stored outside the repository:
+
+```text
+~/.vcm/projects/<project-id>/config.json
+~/.vcm/projects/index.json
+```
+
+Task runtime state, source changes, and handoff artifacts live in the task runtime repo. For worktree-backed tasks this is the nested task worktree:
 
 ```text
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
 ```
 
-This central base-state model lets VCM list and manage multiple tasks while each task's code changes happen in a separate worktree.
+For inline tasks, `taskRepoRoot` is the connected base repo, so these same runtime paths resolve under the connected repo's `.ai/vcm/`.
+
+This split lets VCM list tasks from the base repo after worktrees are created, while each task's runtime state follows the same root as the role sessions.
 
 ### 6.2 Git Ignore Requirement
 
@@ -301,37 +318,36 @@ The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task
 ```text
 POST /api/tasks
   -> validate taskSlug
-  -> compute branch feature/<taskSlug>
-  -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
-  -> assert branch does not already exist
-  -> assert worktreePath does not already exist
   -> assert .ai/vcm/ is ignored by Git
-  -> assert base repo has no uncommitted changes
-  -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> if createWorktree is not false:
+       -> compute branch feature/<taskSlug>
+       -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> assert branch does not already exist
+       -> assert worktreePath does not already exist
+       -> assert base repo has no uncommitted changes
+       -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> otherwise:
+       -> read current base repo branch
+       -> leave worktreePath undefined
   -> create handoff structure in taskRepoRoot
   -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
 ```
 
 The default `baseRef` is the connected repo's current `HEAD`.
 
-### 6.4 Task Cleanup Flow
+### 6.4 Task Close Flow
 
 ```text
 POST /api/tasks/:taskSlug/cleanup
-  -> require no running role sessions
   -> load task metadata
-  -> verify worktree path belongs under <baseRepoRoot>/.ai/vcm/worktrees/
-  -> check worktree status
-  -> refuse cleanup when uncommitted work exists unless force is explicitly requested
-  -> git worktree remove <worktreePath>
-  -> delete central task/session/message/orchestration metadata
+  -> when worktreePath exists, verify it belongs under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> when worktreePath exists, git worktree remove --force <worktreePath>
+  -> when worktreePath exists, delete the task branch by default
+  -> delete base task metadata
+  -> delete task runtime session/message/orchestration/translation metadata
 ```
 
-Branch deletion is intentionally separate:
-
-- Keep `feature/<taskSlug>` by default.
-- Allow branch deletion only with explicit confirmation.
-- Prefer allowing deletion only when the branch has been merged, or when the user force-confirms.
+Close Task is intentionally destructive after user confirmation. It does not preflight running role sessions or uncommitted worktree changes. Tasks created without a worktree remove VCM metadata only because there is no VCM-owned branch/worktree to delete.
 
 ## 7. Task And Artifact Model
 
@@ -474,7 +490,7 @@ Permission flags:
 Session persistence:
 
 ```text
-<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+<taskRepoRoot>/.ai/vcm/sessions/<task>.json
 ```
 
 The persisted record includes:
@@ -539,9 +555,9 @@ Files:
 State:
 
 ```text
-.ai/vcm/messages/<task>.jsonl
-.ai/vcm/orchestration/<task>.json
-.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<taskRepoRoot>/.ai/vcm/orchestration/<task>.json
+<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
 ```
 
 Policy:
@@ -570,11 +586,12 @@ Auto mode:
 send -> delivered
 ```
 
-The backend writes a `[VCM MESSAGE]` envelope to the target terminal and appends Enter.
+The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event.
 
 The backend still exposes pause/resume orchestration API routes and stores `paused` for compatibility. The current GUI only toggles `mode` between `manual` and `auto`.
 
-Messages and orchestration snapshots are central project state under `baseRepoRoot/.ai/vcm`. Message body markdown lives in the task worktree handoff directory.
+Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
+Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
 
 ## 12. Role Command Compatibility
 
@@ -602,7 +619,7 @@ The dispatcher:
 2. Reads the role command artifact.
 3. Rejects missing, empty, or placeholder role commands.
 4. Resolves primary command path `role-commands/<role>.md`, with legacy fallback `<role>-command.md`.
-5. Writes `Please read and execute the role command at: <path>` to the target terminal and submits Enter.
+5. Pastes `Please read and execute the role command at: <path>` to the target terminal, then sends Enter as a separate terminal input event.
 
 This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
 
@@ -636,7 +653,6 @@ Managed block:
 ```gitignore
 # VCM:BEGIN version=1
 .ai/vcm/
-.vcm/
 # VCM:END
 ```
 
@@ -659,7 +675,6 @@ Files:
 - `src/backend/services/translation-prompts.ts`
 - `src/backend/services/claude-transcript-service.ts`
 - `src/backend/adapters/translation-provider.ts`
-- `src/backend/ws/translation-ws.ts`
 - `src/backend/api/translation-routes.ts`
 - `src/frontend/components/translation-panel.tsx`
 - `src/frontend/components/translation-settings-modal.tsx`
@@ -678,15 +693,11 @@ Storage:
 
 Stored data:
 
+- UI theme preference: `system`, `light`, or `dark`
 - translation settings
 - translation secrets
 - recent repository paths, max 5
 
-Legacy migration:
-
-- `~/.vibe-coding-master/settings.json`
-- `~/.vibe-coding-master/translation.json`
-
 ### Provider
 
 Provider type:
@@ -718,8 +729,11 @@ Tailer:
 - validates file exists
 - can replay history since session start minus a grace window
 - uses `fs.watch`
-- also polls every 500ms
+- also polls every 200ms
 - parses only complete newline-delimited JSON records
+- is owned by the backend translation service, not the frontend panel
+- stays running after the panel closes
+- stops only when the role session is stopped/restarted or the task is closed
 
 Parsed transcript events:
 
@@ -736,9 +750,21 @@ Translation service behavior:
 - ignores thinking
 - translates text/question/todo/agent as prose
 - preserves tool_use/tool_result as tool-output
-- queues translation per runtime session id
-- emits WebSocket `translation-entry`
-- emits WebSocket `translation-status`
+- queues provider translation per runtime session id
+- pushes prose entries before provider translation starts
+- pushes tool_use/tool_result immediately without entering the translation queue
+- writes translation events to `<taskRepoRoot>/.ai/vcm/translation/<task>/<role>/<session-id>.jsonl`
+- exposes HTTP polling for frontend rendering
+
+Polling protocol:
+
+- `seq` starts at 1 for each translation session cache.
+- the frontend calls `GET /api/translation/sessions/:sessionId/events?after=<cursor>`.
+- `after` is the next expected seq, not the last displayed seq.
+- `after=18` lets the backend delete cached events with `seq < 18` and return events with `seq >= 18`.
+- if `after` is older than the retained cache, the backend returns whatever newer events still exist.
+- no snapshot mismatch error is used.
+- translated prose replacement is a later `entry` event with the same translation entry id and a newer `seq`.
 
 ### User Input Path
 
@@ -749,10 +775,10 @@ textarea -> POST translation/input -> provider -> English draft in the same text
 Send path:
 
 ```text
-POST translation/send -> runtime.write(session.id, englishText + "\r")
+POST translation/send -> bracketed paste English text -> short delay -> runtime.write(session.id, "\r")
 ```
 
-The backend strips trailing newlines before appending `\r`.
+The backend strips trailing newlines before pasting and sends Enter separately. This avoids Claude Code TUI cases where a single large PTY write containing both text and `\r` fills the input line but does not submit it.
 
 ## 15. API Surface
 
@@ -819,6 +845,13 @@ POST /api/tasks/:taskSlug/orchestration/pause
 POST /api/tasks/:taskSlug/orchestration/resume
 ```
 
+App settings:
+
+```text
+GET  /api/settings/preferences
+PUT  /api/settings/preferences
+```
+
 Translation:
 
 ```text
@@ -826,6 +859,8 @@ GET  /api/translation/settings
 PUT  /api/translation/settings
 GET  /api/translation/prompts
 POST /api/translation/test
+POST /api/tasks/:taskSlug/sessions/:role/translation/start
+GET  /api/translation/sessions/:sessionId/events?after=<cursor>&limit=<n>
 POST /api/tasks/:taskSlug/sessions/:role/translation/input
 POST /api/tasks/:taskSlug/sessions/:role/translation/send
 POST /api/translation/sessions/:sessionId/clear
@@ -836,7 +871,6 @@ WebSockets:
 
 ```text
 /ws/terminal/:sessionId
-/ws/translation/:sessionId
 ```
 
 ## 16. Error Handling

package/docs/v1-implementation-plan.md

@@ -17,7 +17,7 @@ V1 is implemented as a local GUI app with:
 - API-driven message bus.
 - Translation panel based on Claude transcript JSONL tailing.
 - npm packaging with built `dist` and `dist-frontend` output.
-- Task creation creates one `feature/<task>` branch and one `.ai/vcm/worktrees/<task>` git worktree.
+- Task creation creates one `feature/<task>` branch and one `.ai/vcm/worktrees/<task>` git worktree by default; users may clear `Create worktree and branch` to create an inline task in the connected repository/current branch.
 
 ## 2. Package And Build
 
@@ -187,16 +187,16 @@ Defines:
 - `TaskRecord`
 - `CreateTaskRequest`
 
-Current UI sends only `taskSlug`, although the API type still permits optional `title` and `specPath`.
+Current UI sends `taskSlug` and `createWorktree`; the API type still permits optional `title` and `specPath`.
 
 Worktree fields:
 
-- `worktreePath: string`
-- `branch: feature/<taskSlug>`
+- `worktreePath?: string`
+- `branch: feature/<taskSlug>` when worktree creation is selected, otherwise the connected repo's current branch
 - `cleanupStatus?: "active" | "cleaned"`
 - `cleanedAt?: string`
 
-`CreateTaskRequest` creates a worktree and branch by default. The UI shows a checked `Create worktree and branch` indicator, but task worktree creation is the normal VCM task path and does not require a separate later action or a user-visible off switch.
+`CreateTaskRequest` supports `createWorktree?: boolean`. It creates a worktree and branch by default, and skips both when `createWorktree === false`.
 
 ### `src/shared/types/session.ts`
 
@@ -244,7 +244,10 @@ Defines:
 - `SendTranslatedInputRequest`
 - `TranslationProviderTestResult`
 - `TranslationPromptPreview`
-- `TranslationWsMessage`
+- `TranslationSessionStatus`
+- `TranslationSessionEvent`
+- `StartTranslationSessionResult`
+- `PollTranslationSessionResult`
 
 Prompt keys:
 
@@ -484,7 +487,7 @@ Responsibilities:
 - connect repo
 - store current project in process memory
 - record recent repo paths in app settings
-- create `.ai/vcm/config.json`
+- create `~/.vcm/projects/<project-id>/config.json`
 - ensure base state directories
 - ensure `.ai/vcm/` is ignored by Git before task-worktree creation
 - expose base repo as the project control root
@@ -520,39 +523,41 @@ Create flow:
 ```text
 createTask(baseRepoRoot, { taskSlug })
   -> assertValidTaskSlug(taskSlug)
-  -> branch = feature/<taskSlug>
-  -> worktreePath = <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
   -> assert .ai/vcm/ is ignored
-  -> assert base repo has no uncommitted changes
-  -> assert branch does not exist
-  -> assert worktree path does not exist
-  -> git.createWorktree({ baseRepoRoot, branch, worktreePath, baseRef: HEAD })
-  -> artifactService.ensureHandoffStructure({ repoRoot: worktreePath, handoffDir })
-  -> artifactService.createArtifactTemplates({ repoRoot: worktreePath, handoffDir })
+  -> if createWorktree is not false:
+       -> branch = feature/<taskSlug>
+       -> worktreePath = <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> assert base repo has no uncommitted changes
+       -> assert branch does not exist
+       -> assert worktree path does not exist
+       -> git.createWorktree({ baseRepoRoot, branch, worktreePath, baseRef: HEAD })
+       -> taskRepoRoot = worktreePath
+  -> otherwise:
+       -> branch = current base repo branch
+       -> worktreePath = undefined
+       -> taskRepoRoot = baseRepoRoot
+  -> artifactService.ensureHandoffStructure({ repoRoot: taskRepoRoot, handoffDir })
+  -> artifactService.createArtifactTemplates({ repoRoot: taskRepoRoot, handoffDir })
+  -> ensure task runtime state dirs under <taskRepoRoot>/.ai/vcm/
   -> write central task record under <baseRepoRoot>/.ai/vcm/tasks/<task>.json
 ```
 
-Cleanup flow:
+Close Task flow:
 
 ```text
 cleanupTask(baseRepoRoot, taskSlug, options)
-  -> require all role sessions stopped
   -> load central task record
-  -> verify worktreePath is under <baseRepoRoot>/.ai/vcm/worktrees/
-  -> inspect git status in worktree
-  -> refuse uncommitted changes unless options.force
-  -> git.removeWorktree(baseRepoRoot, worktreePath)
-  -> delete .ai/vcm/tasks/<task>.json
-  -> delete .ai/vcm/sessions/<task>.json
-  -> delete .ai/vcm/messages/<task>.jsonl
-  -> delete .ai/vcm/orchestration/<task>.json
+  -> if worktreePath exists, verify it is under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> if worktreePath exists, git.removeWorktree(baseRepoRoot, worktreePath, force=true)
+  -> if worktreePath exists, git.deleteBranch(baseRepoRoot, task.branch, force=true) by default
+  -> delete <baseRepoRoot>/.ai/vcm/tasks/<task>.json
+  -> delete <taskRepoRoot>/.ai/vcm/sessions/<task>.json
+  -> delete <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
+  -> delete <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
+  -> delete <taskRepoRoot>/.ai/vcm/translation/<task>/
 ```
 
-Branch cleanup:
-
-- keep `feature/<taskSlug>` by default
-- optional `deleteBranch` only with explicit confirmation
-- prefer requiring merged branch unless force-confirmed
+The UI labels this operation `Close Task`, styles it as a red destructive action, and shows a browser confirmation that names the worktree, branch, and metadata that will be deleted. VCM does not check running sessions or uncommitted changes before closing. Tasks created without a worktree remove VCM metadata only.
 
 ### `src/backend/services/artifact-service.ts`
 
@@ -621,7 +626,7 @@ Responsibilities:
 Persistence:
 
 ```text
-<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+<taskRepoRoot>/.ai/vcm/sessions/<task>.json
 ```
 
 Environment passed to Claude Code:
@@ -634,7 +639,7 @@ Environment passed to Claude Code:
 In task-worktree mode:
 
 - session cwd is `task.worktreePath`
-- session persistence remains central under `baseRepoRoot/.ai/vcm/sessions`
+- session persistence is written under `task.worktreePath/.ai/vcm/sessions`
 - raw logs and handoff artifacts are written under the task worktree
 
 ### `src/backend/services/message-service.ts`
@@ -658,7 +663,8 @@ Responsibilities:
 
 In task-worktree mode:
 
-- message snapshots remain central under `baseRepoRoot/.ai/vcm/messages`
+- message snapshots live under `task.worktreePath/.ai/vcm/messages`
+- orchestration state lives under `task.worktreePath/.ai/vcm/orchestration`
 - message body files live under `task.worktreePath/.ai/handoffs/<task>/messages`
 - terminal delivery uses the runtime session for the role, whose cwd is the task worktree
 
@@ -700,17 +706,16 @@ Exports:
 - `AppSettingsServiceDeps`
 - `createAppSettingsService(deps)`
 
-Storage:
+Settings responsibilities:
 
-```text
-~/.vcm/settings.json
-```
+- persist UI theme mode: `system`, `light`, or `dark`
+- persist translation settings and translation secrets
+- persist up to five recent repository paths
 
-Also migrates legacy:
+Storage:
 
 ```text
-~/.vibe-coding-master/settings.json
-~/.vibe-coding-master/translation.json
+~/.vcm/settings.json
 ```
 
 ### `src/backend/services/translation-prompts.ts`
@@ -777,10 +782,12 @@ Responsibilities:
 - load/update translation settings
 - expose prompt previews
 - test provider
+- start backend transcript listening for a role session
+- poll cached translation events by cursor
 - translate user input
 - send English text to active terminal
-- subscribe to session translation events
-- clear session entries
+- clear session entries and cached events
+- stop session/task translation listeners
 - retry failed output translation
 - subscribe to Claude transcript service
 - translate prose output and preserve tool output
@@ -799,17 +806,17 @@ Exports:
 - `createDefaultServerDeps(options)`
 - `getDefaultStaticDir()`
 
-Registers all routes and WebSockets.
+Registers HTTP routes and the terminal WebSocket.
 
 ### Route files
 
 - `src/backend/api/project-routes.ts`: health, recent paths, connect/current project
 - `src/backend/api/harness-routes.ts`: harness status/apply
-- `src/backend/api/task-routes.ts`: tasks, task status, task cleanup
+- `src/backend/api/task-routes.ts`: tasks, task status, and Close Task cleanup endpoint
 - `src/backend/api/session-routes.ts`: session lifecycle and dispatch compatibility endpoint
 - `src/backend/api/artifact-routes.ts`: artifact, role command, and log reads/writes
 - `src/backend/api/message-routes.ts`: messages and orchestration
-- `src/backend/api/translation-routes.ts`: settings, prompt previews, provider test, input/send, clear/retry
+- `src/backend/api/translation-routes.ts`: settings, prompt previews, provider test, start/poll, input/send, clear/retry
 
 Worktree task API:
 
@@ -822,11 +829,10 @@ Do not add a "switch task worktree" endpoint. Worktree assignment happens only d
 ### WebSocket files
 
 - `src/backend/ws/terminal-ws.ts`
-- `src/backend/ws/translation-ws.ts`
 
 Terminal WebSocket forwards PTY output/input/resize.
 
-Translation WebSocket subscribes to translation entries/status for a runtime session id.
+Translation does not use WebSocket. The backend writes cached translation events under `<taskRepoRoot>/.ai/vcm/translation/<task>/<role>/<session-id>.jsonl`; the frontend polls `GET /api/translation/sessions/:sessionId/events?after=<cursor>`. The cursor is the next expected seq, so `after=18` means seq `1..17` can be removed and seq `18+` should be returned.
 
 ## 10. Backend Templates
 
@@ -938,9 +944,9 @@ Responsibilities:
 - messages modal
 - events modal
 - harness panel
-- task creation with one task-name field, checked non-optional worktree/branch indicator, branch preview, and worktree path preview
+- task creation with one task-name field, `Create worktree and branch` checkbox selected by default, branch preview, and worktree path preview
 - task navigation
-- completed-task cleanup action
+- red `Close Task` action with destructive confirmation
 
 ### `src/frontend/routes/task-workspace.tsx`
 
@@ -1075,6 +1081,7 @@ Important current behavior:
 - no `Original` buttons
 - tool output is preserved, dim, one-line
 - prose source is replaced by translated text after completion
+- prose renders Markdown with GFM support
 - no separate translated-English textarea
 
 ### `src/frontend/components/translation-settings-modal.tsx`
@@ -1086,18 +1093,15 @@ Exports:
 
 Settings:
 
-- enable translation
 - base URL
 - API key as text input
 - model
 - target language
-- input mode
 - context
-- translate output
-- translate user input
 - timeout
 - temperature
-- prompt slot overrides
+- direct editors for `zh-to-en`, `zh-to-en-with-context`, and `en-to-zh`
+- reset prompts to built-in defaults
 - provider test
 
 ### `src/frontend/components/status-badge.tsx`
@@ -1121,7 +1125,8 @@ Sidebar:
 
 - all groups default collapsed
 - `Repository Path` default open only when no task is selected
-- `Settings` includes `Messages`, `Events`, and `Auto orchestration`
+- `Settings` includes `Theme`, `Messages`, `Events`, and `Auto orchestration`
+- `Theme` cycles through `System`, `Light`, and `Dark`; `System` follows the browser/OS color-scheme preference
 
 Task workspace:
 
@@ -1146,35 +1151,44 @@ App settings:
 ~/.vcm/settings.json
 ```
 
+Contains UI theme preference, translation settings/secrets, and recent repository paths.
+
 Project config:
 
 ```text
-.ai/vcm/config.json
+~/.vcm/projects/<project-id>/config.json
+~/.vcm/projects/index.json
 ```
 
 Task state:
 
 ```text
-.ai/vcm/tasks/<task>.json
+<baseRepoRoot>/.ai/vcm/tasks/<task>.json
 ```
 
 Session state:
 
 ```text
-.ai/vcm/sessions/<task>.json
+<taskRepoRoot>/.ai/vcm/sessions/<task>.json
 ```
 
 Messages:
 
 ```text
-.ai/vcm/messages/<task>.jsonl
-.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
 ```
 
 Orchestration:
 
 ```text
-.ai/vcm/orchestration/<task>.json
+<taskRepoRoot>/.ai/vcm/orchestration/<task>.json
+```
+
+Translation cache:
+
+```text
+<taskRepoRoot>/.ai/vcm/translation/<task>/
 ```
 
 Task worktrees:
@@ -1223,7 +1237,7 @@ For frontend layout changes, also verify manually:
 - Auto orchestration toggles on/off
 - `Enter` in translation composer translates/sends
 - `Shift+Enter` inserts newline
-- mark task complete and verify cleanup removes the worktree and central task metadata
+- close a worktree-backed task and verify it removes the worktree, deletes the task branch, and removes central task metadata
 
 ## 17. V1 Boundaries To Preserve