vibe-coding-master 0.6.16 → 0.6.17

package/README.md

@@ -1,48 +1,29 @@
 # VibeCodingMaster
 
-VibeCodingMaster is a local GUI workspace for managing multiple Claude Code role sessions around one engineering task.
-
-VCM is designed for long-running coding work where one Claude Code conversation is not enough. It gives the user a task workspace with four embedded Claude Code sessions:
-
-- `project-manager`
-- `architect`
-- `coder`
-- `reviewer`
-
-Each role runs as a real Claude Code process inside an embedded terminal. The GUI lets the user start, stop, resume, restart, switch, observe, and manually intervene in those sessions without juggling separate terminal windows.
-
-When Gate Review Gates are enabled for a task, or when a Gate Reviewer session already exists, the workspace can also show a fifth `Gate Reviewer` terminal role. It is an optional VCM flow role powered by Claude Code. Its session is project-scoped and reusable across tasks, but each gate turn is bound to the current task/worktree, writes reports under the task worktree, and stays outside normal PM route-file dispatch.
-
-## Current Capabilities
-
-- GUI-first task workspace.
-- Collapsible sidebar with repository connection, settings, harness status, task creation, and task list.
-- Recent repository path dropdown, stored locally with the five most recent paths.
-- Connected repository status for the base repo, including branch, upstream status, commit hash, dirty state, and fast-forward-only pull.
-- Embedded Claude Code terminals powered by `node-pty` and `xterm.js`.
-- One Claude Code session per role, with role tabs in the task header.
-- Optional Gate Reviewer VCM flow role when any Gate Review Gate is enabled.
-- Role session recovery through persisted Claude session ids and `claude --resume`.
-- Permission mode selection before start, resume, or restart:
-  - `bypassPermissions`
-  - `plan`
-  - `default`
-- PM-mediated role messaging through VCM-dispatched route files.
-- Manual and automatic orchestration modes.
-- Two-stage VCM harness setup: deterministic fixed install plus AI-assisted bootstrap.
-- VCM-managed root rules, role agents, repo-local VCM skills, Claude Code hooks, generated-context tools, and PR template.
-- Generated context for Rust and npm workspace module indexing plus public surface indexing.
-- Translation panel powered by the long-lived Translator session.
-- Mobile Gateway through Tencent iLink / Weixin DM or Lark, for talking to PM and managing tasks from a phone.
-- Durable task state, role session state, handoff artifacts, and message history.
+VibeCodingMaster is a local GUI workspace for running complex coding tasks with
+Claude Code role sessions.
+
+VCM helps you keep one task organized across dedicated roles:
+
+- Project Manager
+- Architect
+- Coder
+- Reviewer
+- optional Gate Reviewer
+
+It runs locally, connects to a local Git repository, creates a task branch and
+worktree, starts embedded Claude Code terminals, and manages handoffs,
+orchestration, translation, harness setup, and mobile gateway control.
 
 ## Requirements
 
-- Node.js 20 LTS or 22+.
-- npm.
-- Git.
-- Claude Code installed and available as `claude` in the runtime environment.
-- For Linux containers, native build/runtime basics for `node-pty`, usually:
+- Node.js 20 LTS or 22+
+- npm
+- Git
+- Claude Code installed and available as `claude`
+- Claude Code authenticated in the same environment where VCM runs
+
+For Linux containers, make sure common native build/runtime tools are available:
 
 ```bash
 python3 make g++ git bash
@@ -50,7 +31,7 @@ python3 make g++ git bash
 
 ## Install
 
-From npm:
+Install from npm:
 
 ```bash
 npm install -g vibe-coding-master
@@ -58,30 +39,28 @@ vcm --version
 vcm
 ```
 
-Useful CLI flags:
+By default, open:
 
-```bash
-vcm --help
-vcm --version
-vcm --host=127.0.0.1 --port=4173
+```text
+http://127.0.0.1:4173/
 ```
 
-From source:
+Useful flags:
 
 ```bash
-npm install
-npm run dev
+vcm --help
+vcm --version
+vcm --host=127.0.0.1 --port=5000
 ```
 
-## Run Locally
-
-Development mode:
+## Run From Source
 
 ```bash
+npm install
 npm run dev
 ```
 
-Open the Vite GUI:
+Open the development UI:
 
 ```text
 http://127.0.0.1:5173/
@@ -93,8 +72,6 @@ The backend runs at:
 http://127.0.0.1:4173/
 ```
 
-If `5173` is already in use, Vite may choose another frontend port and print it in the terminal.
-
 Production-style local run:
 
 ```bash
@@ -108,17 +85,13 @@ Then open:
 http://127.0.0.1:4173/
 ```
 
-The global `vcm` command runs the production-style app and serves the GUI from the backend port:
-
-```text
-http://127.0.0.1:4173/
-```
-
-## Run In VS Code Dev Containers
+## Recommended Sandbox
 
-VCM works inside a VS Code `devContainer` when VCM, Claude Code, and the target repository all run inside the same container filesystem.
+VCM can run Claude Code with relaxed local permissions. The recommended setup is
+to run VCM and the target repository inside a Dev Container, VM, or other local
+sandbox boundary.
 
-Add port forwarding to `.devcontainer/devcontainer.json`:
+For VS Code Dev Containers, forward the UI ports:
 
 ```json
 {
@@ -134,193 +107,243 @@ Add port forwarding to `.devcontainer/devcontainer.json`:
 }
 ```
 
-Use the path as seen from inside the container, for example `/workspace`.
+Use repository paths as seen inside the container, for example `/workspace`.
 
-Important container notes:
+If you want VCM app state to survive container rebuilds, set:
 
-- Install Claude Code inside the container, or make `claude` available in the container `PATH`.
-- Make sure Claude Code authentication works inside the container.
-- Make sure the container has network access to Claude services if translation is enabled.
-- VCM accepts normal Git repositories by checking `.git` directly. It also supports `.git` files that point to worktree gitdirs.
-- VCM uses per-command `git -c safe.directory=...` for Git metadata reads and does not require global `git config --global --add safe.directory`.
-- Treat the container as the sandbox boundary, especially when using relaxed Claude Code permission modes.
+```json
+{
+  "containerEnv": {
+    "VCM_DATA_DIR": "/workspace/.ai/vcm"
+  }
+}
+```
 
-## Basic Usage
+## Quick Start
 
-1. Start VCM.
+1. Start VCM with `vcm`.
 2. Open the GUI.
-3. In the sidebar, open `Repository Path`, enter a repository path or choose one from `Recent`, then click `Connect`.
-4. Review `VCM Harness`; if fixed files need install/update, click `Install / Update`.
-5. If bootstrap checks are incomplete, click `Run Bootstrap` and let the visible Claude Code bootstrap session fill project-specific docs and generated context.
-6. Review and commit harness changes when they look right.
-7. Create a task from `New Task` with a single task name.
-8. Select the task from `Tasks`.
-9. Use the role tabs in the task header to switch between `Project Manager`, `Architect`, `Coder`, and `Reviewer`.
-10. Choose the permission mode for the active role.
-11. Click `Start`, `Resume`, `Restart`, or `Stop` as needed.
-12. Talk mostly to `project-manager`; let PM coordinate the other roles through VCM messaging.
-
-The recommended flow is:
+3. In `Repository`, enter a local Git repository path and click `Connect`.
+4. Create or select a task in the `Task` section. VCM creates a task branch and
+   worktree immediately.
+5. In `VCM Harness`, initialize or update fixed harness files if VCM reports
+   pending changes. Harness changes are written to the active task worktree.
+6. If bootstrap is incomplete, open Harness Studio and run bootstrap through
+   Harness Engineer.
+7. Review the harness/bootstrap commit diff.
+8. Start the role sessions, or use the saved launch template / one-click start.
+9. Talk mostly to Project Manager.
+10. Let PM route work to Architect, Coder, Reviewer, and Gate Reviewer when
+    enabled.
+11. Review the final result and close the task when finished.
+
+## Repository Setup
+
+VCM works with normal local Git repositories.
+
+After you create or select a task, VCM can install or update harness files in
+the active task worktree:
+
+- root `CLAUDE.md` managed block
+- `.claude/agents/**`
+- `.claude/skills/**`
+- `.claude/settings.json` hooks
+- `.ai/tools/**`
+- `.gitignore` entries for VCM runtime state and task worktrees
+- generated-context tooling
+- pull request template
+
+VCM preserves user-authored content outside VCM managed blocks.
+
+The fixed harness install is deterministic and creates a commit in the active
+task worktree. Bootstrap is AI-assisted and is run through the Harness Engineer
+role. Bootstrap fills project-specific docs and generated context such as:
+
+- `docs/ARCHITECTURE.md`
+- module-level `ARCHITECTURE.md`
+- `docs/TESTING.md`
+- `.ai/generated/module-index.json`
+- `.ai/generated/public-surface.json`
+
+## Task Workflow
+
+VCM uses one branch and one worktree for each task:
 
 ```text
-project-manager
-  -> architect architecture plan, Scaffold Manifest, and code scaffolding
-  -> coder implementation and baseline unit checks
-  -> reviewer independent validation
-  -> architect docs sync / architecture drift check
-  -> project-manager final acceptance, commit, and PR
+one task = one branch + one task worktree + one role-session set
 ```
 
-## VCM Runtime Terminology
+By default:
+
+- branch: `feature/<task-name>`
+- worktree: `<repo>/.claude/worktrees/<task-name>`
+
+Roles for the same task share the same task worktree. VCM does not create one
+worktree per role.
 
-VCM statistics use three nested terms:
+Typical flow:
 
 ```text
-Session = n x Round = m x Turn
+Project Manager
+  -> Architect
+  -> Coder
+  -> Reviewer
+  -> Architect docs sync
+  -> Project Manager final acceptance
 ```
 
-- `Session`: the whole VCM task. It aggregates all statistics for that task, from task creation until the task is closed.
-- `Round`: one user-facing VCM conversation cycle. It starts when a user prompt or VCM-delivered prompt is accepted, continues through automatic role orchestration, and normally ends when the final `project-manager` result has stopped and no next role turn starts inside the 10 second stop window.
-- `Turn`: one role-level Claude Code conversation. A turn starts when VCM or the user submits a prompt to one role session and ends when that Claude Code process emits `Stop`.
+For complex tasks, ask PM to use managed mode. PM will keep the task moving and
+ask the user only when user intent, authorization, external access, real cost,
+production permission, sensitive data, or a proven outcome change requires a
+human decision.
 
-Turns inside one Round are strictly sequential. VCM should finish one role Turn before starting the next role Turn in that Round.
+## Role Sessions
 
-Session state is intentionally small: `created` means no Round has started yet, `running` means there is a current running Round, and `stopped` means there is no current running Round after at least one Round has stopped. Starting Claude Code role sessions does not make the VCM Session `running`.
+Each role runs in an embedded Claude Code terminal.
 
-Round state is only `running` or `stopped`. After a `Stop` hook, the 10 second stop window still counts as `running`; the Round becomes `stopped` only when the timer expires without another `UserPromptSubmit`.
+Controls:
 
-In this terminology, `Session` is a VCM statistics term. It is different from a Claude Code role session. VCM still runs one Claude Code role session per role, but the sidebar task statistics treat the task itself as the VCM Session.
+- `Start`: start a new Claude Code role session
+- `Resume`: resume a saved Claude Code session
+- `Restart`: stop current process and start fresh
+- `Stop`: stop the embedded terminal process
 
-## Task Worktree Management
-
-VCM uses task-level worktree management for every task:
+Permission modes:
 
 ```text
-one task = one branch + one git worktree + one handoff directory + one role-session set
+bypassPermissions
+plan
+default
 ```
 
-- task name: `<task>`
-- branch: `feature/<task>`
-- worktree path: `.claude/worktrees/<task>` inside the connected base repository
-- role session cwd: that task worktree
-
-VCM will not create worktrees per role. `project-manager`, `architect`, `coder`, and `reviewer` for the same task share the same task worktree.
+`bypassPermissions` is the default because VCM expects a local sandbox boundary
+such as a Dev Container or VM.
 
-VCM will not offer a separate `Create task worktree` button after a task exists, and a task should not be switched to another branch/worktree mode after creation.
+Model and effort can be selected before start/resume/restart. Changes affect the
+next launched process, not a currently running Claude Code process.
 
-Because worktrees live under `.claude/worktrees/`, the connected repository must ignore both `.ai/vcm/` and `.claude/worktrees/`. Apply the VCM Harness before creating tasks so `.gitignore` contains the managed ignore block. The base repository must also be clean because the task branch/worktree is created from the connected repo's current `HEAD`.
+## Launch Template
 
-When a task is complete, VCM provides a red `Close Task` action. Closing a task shows a destructive confirmation, stops VCM-managed running role sessions for that task, then deletes the task worktree, deletes the task branch by default, removes the app-local task record, and removes task runtime metadata. VCM does not preflight running sessions or uncommitted changes before closing. Project-scoped Gate Reviewer and Translator sessions are not task-owned and are not stopped by Close Task.
+The launch template stores per-role defaults:
 
-## Sidebar UI
+- permission mode
+- model
+- effort
+- auto orchestration
 
-The left sidebar is intentionally compact and collapsible:
+One-click start launches the four core roles. If any Gate Review Gate is enabled,
+it also launches Gate Reviewer.
 
-- `Repository Path`: path input on one row; `Recent` and `Connect` on the next row.
-- `Connected Repository`: connected base repo path, branch, upstream/ahead-behind status, commit hash, working tree state, and a `Pull` button.
-- `Settings`: `Theme`, `Flow pause alert`, `Try alert`, `Messages`, and `Events`.
-- `Translation`: global conversation translation, auto-send, target language, output scope, file translation, bootstrap, memory update, session status, and Translator session access.
-- `Gate Review Gates`: global gate switches for architecture plan, validation adequacy, and final diff.
-- `Gateway`: Weixin iLink or Lark setup, Gateway on/off, Gateway translation, and QR login/setup.
-- `VCM Harness`: fixed-install status, bootstrap completion checks, and the bootstrap terminal when one is running.
-- `New Task`: one `task name` input.
-- `Tasks`: task list and task status.
+Translator and Harness Engineer are tool roles. They are controlled from their
+own panels, not from the main role tab bar.
 
-All sidebar sections are collapsed by default. When no task is selected, `Repository Path` opens by default. The sidebar behaves as a single-open accordion: opening one section closes the previously open section, and clicking the open section collapses it.
+## Orchestration
 
-Opening `Connected Repository` refreshes the base repo status through the
-backend. VCM does not poll it continuously. The `Pull` button runs
-`git pull --ff-only` against the connected base repo only. It is disabled when
-the base repo has uncommitted changes or when the current branch has no
-upstream. It does not stash, merge, or mutate task worktrees.
+VCM supports manual and automatic orchestration.
 
-When VCM is connected to an active task, the bottom of the sidebar shows a task status dock. It stays outside the collapsible groups and shows the active VCM Session title, task status, start time, total elapsed time, total Round count, and role active runtime. The dock also shows the Current Round while it is running, or the Last Round after a flow pause, including start time, total elapsed time, role active runtime, Turn count, and Round status.
-
-## Mobile Gateway
+Manual mode:
 
-VCM Gateway lets mobile chat clients talk to one desktop VCM instance. It supports Weixin iLink and Lark. It is a mobile control surface for the current desktop VCM, not a remote terminal.
+- roles write route messages
+- messages appear in the Messages panel
+- the user decides what to copy, send, or clear
 
-Gateway rules:
+Automatic mode:
 
-- Weixin is DM only; Lark can receive group messages only when the bot is mentioned.
-- Weixin binds one phone identity to one desktop VCM instance.
-- Lark accepts any DM or @mention from a chat that can reach the bot; the most recent active Lark chat becomes the PM reply target.
-- The active mobile chat can manage projects and tasks available to that desktop VCM instance.
-- When the desktop UI has an active task selected, Gateway uses that task automatically.
-- After setup, VCM keeps a lightweight Gateway connection for `/start` and read-only commands even when the `Gateway` toggle is off.
-- VCM caches the latest PM reply for each task locally, so `/start` can immediately return the current task's latest PM status when available.
-- Plain text messages go only to the current task's `project-manager`.
-- Gateway never sends directly to `architect`, `coder`, or `reviewer`.
-- Gateway credentials and audit logs stay in local app state, not in connected repositories.
+- VCM dispatches route messages to idle target roles
+- the UI switches to the target role before dispatch
+- Claude Code hooks confirm whether the prompt was accepted
 
-Gateway state is stored locally under:
+If the flow stops, VCM shows a pause alert. The `Pause alert sound` setting only
+controls the sound; the stopped-flow state is still shown in the UI.
 
-```text
-<vcmDataDir>/gateway/settings.json
-<vcmDataDir>/gateway/audit.jsonl
-```
+## Gate Review Gates
 
-### Bind Weixin
+Gate Review is optional and off by default.
 
-1. Start VCM and open the GUI.
-2. Open the sidebar `Gateway` section.
-3. Click `Start QR Login`.
-4. VCM opens a global `Weixin Gateway Login` dialog with a QR code.
-5. Scan the QR code with Weixin and confirm login on the phone.
-6. Click `Confirm` in the dialog.
-7. After binding succeeds, close the dialog and turn `Gateway` on in the sidebar.
+Available gates:
 
-`Start QR Login` is shown only when Gateway is not bound. It creates a new Tencent iLink QR login session and opens the QR dialog. The dialog `Confirm` button asks iLink whether the QR code has been scanned and confirmed. After binding succeeds, the sidebar shows `Reset Binding` instead of `Start QR Login`.
+- Architecture plan
+- Validation adequacy
+- Final diff
 
-The `Gateway` toggle is disabled until a QR login has produced a usable iLink token. After binding, VCM keeps receiving `/help`, `/start`, `/status`, `/projects`, and `/tasks` even when the toggle is off. Turning `Gateway` on, either from desktop or by sending `/start`, enables PM messages, task-changing commands, and PM reply push. `Reset Binding` clears the stored token and bound Weixin identity so the desktop VCM can bind again.
+When a gate is enabled, VCM uses Gate Reviewer as an independent review role.
+Gate Reviewer reviews artifacts and diffs, writes a gate report, and returns
+only:
 
-### Bind Lark
+- `approve`
+- `request_changes`
 
-1. Open the sidebar `Gateway` section and select `Lark`.
-2. Click `Start QR Setup`.
-3. Scan the QR code with Lark and approve bot creation.
-4. Click `Confirm` in the setup dialog.
-5. Turn `Gateway` on in the sidebar.
-6. Send a DM to the bot, or @mention it from a group.
+Gate Reviewer does not run tests and does not choose owners or fixes. PM routes
+findings back to the responsible role.
 
-Lark QR setup creates/configures the bot app and stores the resulting App ID/App Secret in local VCM state. The App Secret is not shown in the UI. Any Lark chat that can message the bot can control Gateway; VCM always treats the most recent active Lark chat as the PM reply target.
+## Translation
 
-When Gateway is turned on, VCM automatically turns off the browser `Flow pause alert` and disables `Try alert`. Gateway becomes the notification path, so the browser should not show blocking flow-pause dialogs while the user is managing the task from the phone.
+Conversation translation is controlled from the sidebar `Translation` section.
 
-### Translation
+VCM uses the project-scoped Translator role and Claude transcript JSONL files,
+not raw terminal text.
 
-The Gateway section has its own `Translation` toggle.
+Common controls:
 
-When Gateway translation is on:
+- enable/disable conversation translation
+- auto-send translated user input
+- target language
+- reply scope
+- open Translator session
+- file translation
+- bootstrap translation memory
+- update memory
 
-- Mobile input is translated to English before being submitted to PM.
-- The prompt sent to PM includes only the translated English text with a `[VCM Gateway]` marker.
-- The original Chinese text is not included in the PM prompt.
-- PM replies are translated before VCM sends them to the active mobile chat.
-- If PM reply translation fails or times out, VCM sends a translation failure notice instead of the English source. The user can send `/retry` to retry the latest failed Gateway output translation.
+Supported target languages:
 
-When Gateway translation is off, plain mobile text is sent to PM as-is.
+- Chinese
+- Japanese
+- Korean
+- French
+- German
+- Spanish
 
-### Commands
+Reply scope options:
 
-After Gateway is configured, send commands in the active mobile conversation.
+- Round final reply
+- PM final reply
+- Each role final reply
+- All replies
 
-When `Gateway` is off, only these commands are accepted:
+File and conversation translation state lives under:
 
 ```text
-/help
-/start
-/status
-/projects
-/tasks
+<baseRepoRoot>/.ai/vcm/translations/
 ```
 
-When `Gateway` is on, the full command set is accepted:
+## Mobile Gateway
+
+Gateway lets a mobile chat client control the current local VCM instance.
+
+Supported channels:
+
+- Weixin iLink
+- Lark
+
+Gateway can:
+
+- show status
+- list projects and tasks
+- select a project or task
+- create a task
+- close a task with confirmation
+- send plain text to Project Manager
+- push PM replies back to the active chat
+- translate mobile messages when Gateway translation is enabled
+
+Gateway does not expose the embedded terminal and does not send directly to
+Architect, Coder, Reviewer, or Gate Reviewer.
+
+Common commands:
 
 ```text
 /help
 /start
-/retry
 /status
 /projects
 /use-project <index-or-path>
@@ -332,333 +355,105 @@ When `Gateway` is on, the full command set is accepted:
 /close-task confirm <task-slug>
 /translate on
 /translate off
+/retry
 ```
 
-Plain text that does not start with `/` is sent as a message to the current task's PM session only when `Gateway` is on.
-
-In normal use, VCM runs one project and one task at a time. If the desktop UI has a task selected, turning Gateway on syncs that project/task into Gateway automatically. `/status` also refreshes this context, so the phone usually does not need to run `/tasks` and `/use-task` before sending a PM message.
-
-Typical mobile flow:
-
-```text
-/projects
-/use-project 1
-/pull-current
-/create-task mobile-demo "Implement mobile gateway smoke test"
-/status
-继续推进这个任务，先让 PM 安排下一步。
-/close-task
-/close-task confirm mobile-demo
-```
-
-### Command Behavior
-
-- `/status`: shows Gateway, active chat, translation, current project, current task, and last poll status.
-- `/status` also adopts the current desktop project/task when one is selected.
-- `/start`: turns Gateway on from the active mobile conversation so full mobile task operations and PM messages are allowed. If the current task has a cached latest PM reply, `/start` includes it in the response.
-- `/retry`: retries the latest failed Gateway output translation in the current VCM process.
-- `/projects`: lists the current/recent repositories known by the desktop VCM.
-- `/use-project <index-or-path>`: selects the Gateway's current project context.
-- `/pull-current`: runs the same fast-forward-only connected repository pull as the desktop `Pull` button.
-- `/tasks`: lists tasks for the selected project.
-- `/use-task <index-or-task-slug>`: selects the Gateway's current task context.
-- `/create-task <task-slug> [title]`: creates a worktree-backed task and starts the four core role sessions using the saved launch template. If any Gate Review Gate is enabled, Gateway also resumes or starts Gate Reviewer from the saved template.
-- `/close-task`: starts a destructive close confirmation for the current task.
-- `/close-task confirm <task-slug>`: closes the task through VCM cleanup after exact slug confirmation.
-- `/translate on` and `/translate off`: changes Gateway translation for mobile messages.
-
-`/pull-current` only pulls the connected base repository. It does not pull task worktrees, stash local changes, merge divergent branches, or run arbitrary shell commands.
-
-`/create-task` uses the saved launch template from the desktop settings. The template controls permission mode, model, effort, and auto orchestration for the four core role sessions plus the optional Gate Reviewer. Gateway translation uses the global Gateway translation setting, not the launch template.
-
-`/close-task` is destructive. It stops VCM-managed role sessions and removes task-owned worktree/branch state according to the same cleanup behavior as the desktop `Close Task` action.
-
-### Troubleshooting
-
-- If the QR dialog does not appear, refresh the page and click `Start QR Login` again.
-- If the QR status stays `wait`, confirm the login on the phone and click `Confirm` again.
-- If the QR code expires, start a new QR login.
-- If `Gateway` cannot be enabled, bind Weixin or complete Lark QR setup first.
-- If `/start` or read-only commands do not receive replies, check that the selected channel is connected and that Lark messages are sent as DM or group @mentions.
-- If PM messages or task-changing commands are rejected, check that Gateway is on.
-- If plain text cannot be sent to PM, select a project and task first, and make sure the task's PM session is running and idle.
-- If PM replies are not pushed, check that Gateway is on and the PM session is producing normal Claude transcript output.
-- If PM reply translation fails, send `/retry` from the active mobile conversation. Retry state is memory-only and is cleared when VCM restarts.
-
-## Translation
-
-Translation is controlled from the sidebar `Translation` group. When conversation translation is enabled, each running core VCM role console shows a translation panel beside the embedded terminal. The terminal and translation panel split the available width evenly.
-
-The task header does not include a manual `Refresh` button. Task status, role status, messages, orchestration state, and flow pause state refresh automatically. The remaining `Refresh` button lives only in the sidebar `VCM Harness` section and is for rechecking harness files.
-
-Translation settings are local and stored in:
-
-```text
-<vcmDataDir>/settings.json
-```
-
-The same file stores recent repository paths and global translation preferences such as enablement, auto-send, and target language.
-
-VCM resolves `vcmDataDir` from `VCM_DATA_DIR`. If `VCM_DATA_DIR` is unset or empty, VCM uses `~/.vcm`. In Dev Containers, set `VCM_DATA_DIR=/workspace/.ai/vcm` through `containerEnv` so VCM app state survives container rebuilds.
-
-The sidebar `Settings` section also stores the UI theme preference in this file. The default is `system`, which follows the OS/browser color-scheme preference; users can cycle between `System`, `Light`, and `Dark`.
-
-The same sidebar also has a `Flow pause alert` toggle. It is on by default and controls the local alert that fires when VCM detects that the current role flow has stopped advancing. Short flows use a weak reminder: the soft two-note chime plays 3 times, 1.4 seconds apart. Flows lasting 2 minutes or longer use a strong reminder: VCM shows an alert dialog and repeats the chime until the user confirms it. The alert sound reuses one browser audio context so repeated reminders remain reliable in stricter browsers such as Safari. Safari users may still need to manually set `Safari > Website Settings > Auto-Play > Allow All Auto-Play`; Chrome is recommended for the most reliable alert sound behavior. The `Try alert` button always triggers the strong reminder for testing.
+Gateway credentials and audit logs are stored in app-local state, not connected
+repositories.
 
-When Gateway is on, `Flow pause alert` is forced off because mobile notifications are delivered through Gateway and browser alerts can block normal workflow progress.
+## Harness Studio
 
-Translation behavior:
+Harness Studio is the UI for VCM harness maintenance.
 
-- Conversation translation is routed through the Translator session and result files.
-- Global translation controls live in the sidebar Translation section: enablement, auto-send, target language, output scope, bootstrap, memory update, file translation, session status, and `Open Session`.
-- File and conversation translation share `<baseRepoRoot>/.ai/vcm/translations/`; conversation result files are temporary runtime artifacts.
-- Claude Code output translation reads semantic Claude transcript JSONL files under `~/.claude/projects`, not raw PTY output.
-- Claude Code prose output waits 10 seconds before dispatch so adjacent output can be translated in one Claude Code Translator batch.
-- VCM tails those transcript files in the backend. Closing the translation panel does not stop capture; the tailer stops only when the role session is stopped/restarted or the task is closed.
-- Translation events are cached under the task runtime repo at `.ai/vcm/translation/<task>/<role>/<session-id>.jsonl` and delivered to the frontend through HTTP polling.
-- The polling cursor is the next expected seq: `after=18` acknowledges seq `1..17` and returns seq `18+`; there is no snapshot mismatch error.
-- The translation panel retains the most recent 500 entries per role session in frontend/backend memory. Older entries are pruned from the live panel state and event cache to keep long sessions responsive.
-- When new translation events arrive, the active translation panel automatically scrolls to the bottom so the latest output, retry result, or conversation boundary is visible.
-- Failed output translations are tracked in a backend failure list. When failures exist, the panel shows `Ignore N` and `Retry N`; retry reuses the original entry id so the failed row is replaced by the normal translating/translated flow. If an old failed entry is pruned by the 500-entry cap, its failure-list item is removed too.
-- Assistant prose is shown as English source while translating, then replaced by the translated Chinese result.
-- Assistant prose renders Markdown in the panel, including headings, lists, code fences, tables, and links.
-- Tool calls and tool results are preserved as dim one-line rows such as `● Bash({"command":"npm test"})`.
-- User input uses one textarea. Press `Enter` to translate or send the current English draft; press `Shift+Enter` for a newline.
-- After user input is translated, the English draft is appended after the original source text in the same textarea.
-- `Send English` writes the current English draft to the active embedded terminal and submits it.
-- Automatic terminal submission uses bracketed paste first, then sends Enter separately for Claude Code TUI reliability.
-- The sidebar `Auto-send` toggle sends the translated draft automatically when translation succeeds without warnings.
+Use it to:
 
-## Project Harness
+- inspect fixed harness status
+- run bootstrap
+- open Harness Engineer
+- review harness files
+- copy file paths for discussion
+- review task harness after a task completes
+- inspect commit diffs for harness changes
+- merge task harness commits back to the connected repository branch when
+  appropriate
 
-VCM works best when the connected repository contains VCM collaboration rules as normal project files. Harness setup has two stages.
+Harness Engineer is project-scoped and resumable. When it performs task work,
+VCM runs it from the active task worktree.
 
-Fixed install is deterministic. It installs or updates VCM-owned files and managed blocks:
+## Closing a Task
 
-```text
-CLAUDE.md
-.gitignore
-.claude/settings.json
-.claude/agents/project-manager.md
-.claude/agents/architect.md
-.claude/agents/coder.md
-.claude/agents/reviewer.md
-.claude/skills/vcm-route-message/SKILL.md
-.claude/skills/vcm-final-acceptance/SKILL.md
-.claude/skills/vcm-long-running-validation/SKILL.md
-.claude/skills/vcm-harness-bootstrap/SKILL.md
-.claude/skills/vcm-gate-review/SKILL.md
-.claude/agents/gate-reviewer.md
-.claude/agents/translator.md
-.ai/tools/request-gate-review
-.ai/tools/generate-module-index
-.ai/tools/generate-public-surface
-.ai/tools/run-long-check
-.ai/tools/watch-job
-.ai/tools/vcm-bash-guard
-.github/pull_request_template.md
-```
-
-Repo-local skills are installed as `.claude/skills/<skill-name>/SKILL.md` so
-Claude Code can register them.
-
-VCM roles must not run background Bash. A `PreToolUse` hook
-(`.ai/tools/vcm-bash-guard`) denies `run_in_background`, `nohup`, `setsid`,
-`disown`, and trailing `&` calls in VCM role sessions. The only sanctioned
-long-running mechanism is `.ai/tools/run-long-check` plus
-`.ai/tools/watch-job` through `vcm-long-running-validation`:
-
-- The detached job worker itself enforces the job ceiling (`--timeout`, max 60
-  minutes) and a supervision lease: a job left without a live foreground
-  watcher for about 2 minutes is killed and recorded as `orphaned`.
-- `watch-job` renews the lease and watches in windows of up to 8 minutes; it
-  exits `125` while the job is still running instead of killing it, and the
-  role re-runs it in the same turn until a terminal result.
-- The VCM backend blocks a role from ending its turn while one of its
-  validation jobs is still running.
-- Only one validation job may be active at a time.
-
-If a managed-block file already exists, VCM preserves user-authored content and only inserts or replaces the VCM block:
-
-```md
-<!-- VCM:BEGIN version=1 -->
-VCM-managed rules live here.
-<!-- VCM:END -->
-```
+`Close Task` is destructive.
 
-For `.gitignore`, VCM uses a gitignore-native managed block:
+It stops task-owned VCM role sessions and removes task-owned worktree/branch
+state. Commit or preserve anything important before closing.
 
-```gitignore
-# VCM:BEGIN version=1
-.ai/vcm/
-.claude/worktrees/
-# VCM:END
-```
+Project-scoped tool sessions such as Translator and Harness Engineer are not
+ordinary task deliverables. VCM may move them to a safe cwd when task context
+changes.
 
-`.ai/vcm/` is the active VCM local control area, and `.claude/worktrees/` is the Claude-compatible task worktree area. VCM keeps the task index in app-local project state under `<vcmDataDir>/projects/`; each task runtime repo keeps its own session, message, orchestration, and translation state.
+## Troubleshooting
 
-VCM also JSON-merges `.claude/settings.json` to install Claude Code `PreToolUse`, `UserPromptSubmit`, `Stop`, and `PermissionRequest` hooks plus a managed `env.BASH_DEFAULT_TIMEOUT_MS` so foreground watch windows fit inside the Bash tool timeout. The hooks post directly to the local VCM backend, so roles do not need a VCM CLI command to confirm delivery or report turn completion. The `Stop` hook forwards the backend response to Claude Code, which lets VCM block turn-end while a validation job is still running.
+### The page does not open
 
-Bootstrap is AI-assisted. VCM starts or resumes the project-scoped Harness Engineer Claude Code session in the connected repository and asks it to use the `vcm-harness-bootstrap` skill. Bootstrap fills project-specific content and generated context:
+Check the port printed by VCM. If you start with:
 
-```text
-CLAUDE.md project context outside the VCM managed block
-docs/ARCHITECTURE.md
-<module>/ARCHITECTURE.md
-docs/TESTING.md
-.ai/generated/module-index.json
-.ai/generated/public-surface.json
+```bash
+vcm --port=5000
 ```
 
-The generated-context tools support Rust/Cargo projects and npm workspace TypeScript/JavaScript projects. Other repository shapes can still install the fixed harness, but generated context should be treated as unsupported until project-specific generators exist.
-
-After applying harness changes or completing bootstrap, VCM reports the exact files changed or checks completed and reminds the user to review and commit them before starting long-running work.
-
-Role sessions learn VCM rules from `CLAUDE.md` and `.claude/agents/*.md`. VCM does not paste a long context block into the terminal at session start.
-
-## Message Bus
-
-The message bus is file-driven and dispatched by VCM after Claude Code turn completion. Roles do not call a VCM CLI to send messages.
-
-Role communication works like this:
+open:
 
 ```text
-Claude Code role
-  -> writes or updates .ai/vcm/handoffs/messages/<from-role>-<to-role>.md
-  -> ends the Claude Code turn
-  -> Stop hook calls VCM backend directly
-  -> VCM scans pending route files
-  -> VCM validates and dispatches at most one pending route file
-  -> VCM records dispatchingAt and the GUI switches to the target role
-  -> VCM snapshots only actually delivered message history
-  -> UserPromptSubmit hook records acceptedAt and clears the matching route file
+http://127.0.0.1:5000/
 ```
 
-Examples:
+### Claude Code cannot start
 
-```text
-.ai/vcm/handoffs/messages/project-manager-coder.md
-.ai/vcm/handoffs/messages/coder-project-manager.md
-.ai/vcm/handoffs/messages/project-manager-reviewer.md
-```
-
-Runtime message and handoff files:
+Check that `claude` is available in the same shell/container where VCM runs:
 
-```text
-.ai/vcm/messages/<task>.jsonl                 # under the task runtime repo
-.ai/vcm/orchestration/<task>.json             # under the task runtime repo
-.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
+```bash
+claude --version
 ```
 
-Each directed role route has exactly one message file. Route messages are the only dynamic task-dispatch files. If a role changes its mind during one turn, it edits the same route file instead of creating another message. A blank file means no pending message; a non-empty file means pending work for VCM to submit.
-
-## Orchestration Modes
-
-VCM has a task-level `Auto orchestration` switch in the role console toolbar. New tasks default to auto orchestration.
-
-When it is off, VCM is in manual mode:
-
-- Roles may write pending route files under `.ai/vcm/handoffs/messages/`.
-- Messages appear in the `Messages` modal.
-- The user can inspect them.
-- The current GUI shows newest message history first with stable increasing sequence numbers, timestamp, body preview, path, `Copy`, `Mark All Done`, and `Delete All`.
-- `Mark All Done` clears non-empty pending route files after the user manually copied or handled stuck handoff content.
-- `Delete All` removes message history from the Messages modal without touching pending route files.
-- The user decides what to do next by copying or manually acting on the message.
-- VCM does not write to the target terminal or press Enter for the user.
+Also confirm Claude Code authentication works in that environment.
 
-When it is on, VCM is in auto mode:
+### Repository cannot create a task
 
-- Backend policy still applies.
-- Roles write pending route files under `.ai/vcm/handoffs/messages/`.
-- On Claude Code `Stop`, VCM scans pending route files.
-- If the target role session is running and idle, VCM writes a `[VCM MESSAGE]` envelope to the target terminal and submits it.
-- Just before terminal submission, VCM records `dispatchingAt`, waits briefly for the GUI to switch tabs, then writes to the embedded terminal.
-- After successful terminal write, VCM snapshots the delivered body as message history.
-- Claude Code `UserPromptSubmit` confirms that the prompt was accepted; VCM stores `acceptedAt` and clears the source route file if it still contains the same message.
-- If `UserPromptSubmit` does not confirm the auto-delivered message, VCM retries Enter from the backend PTY and finally records `failureReason` on the message if submission is still not confirmed.
-- When the GUI observes a newly dispatching auto message, it switches the active role tab to that message's target role before the message is submitted.
-- VCM enforces sequential turn-taking from hook state: a role that has accepted a prompt is busy until its `Stop` hook fires.
-- Additional pending files to a busy target role remain non-empty and are not written to that terminal.
-- When the target role later reaches `Stop`, VCM scans again and may deliver the next pending route file.
-- If auto orchestration gets stuck after a manual copy/paste recovery, `Mark All Done` clears pending route files. It does not mutate message history.
+Make sure:
 
-VCM Harness injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`. Role tabs become `running` when Claude Code accepts a prompt and `idle` after `Stop`; VCM also marks a role `running` immediately after it writes a message to that embedded terminal. Gate Reviewer uses the same Claude hook/Round/translation path as other VCM flow roles, while VCM still owns gate report polling and the PM callback. The terminal process status is tracked separately. Claude role rules require a role to end its turn after writing or updating a message route file, rather than polling, looping, or waiting for another role inside the same Claude Code turn.
+- the repository is a Git repository
+- the connected base repo is clean
+- no other task is currently active for this project
+- the derived `feature/<task>` branch does not already exist
+- the derived `.claude/worktrees/<task>` directory does not already exist
 
-The implementation keeps only the active manual/auto orchestration mode. It does not expose pause/resume, stage/approve/reject, or a separate agent-facing message CLI.
+### Resume fails
 
-## Flow Pause Alerts
+Claude Code only resumes conversations it actually saved. VCM records a Claude
+session id after the first accepted prompt. If a session never received a prompt,
+start a fresh session instead of resuming.
 
-VCM detects flow pauses from Claude Code hook events, not PTY silence, message history, or pending route files. `UserPromptSubmit` starts a new Round when there is no current running Round, or continues the current Round when it fires within the 10 second stop window.
+### Translation does not appear
 
-When a `Stop` hook fires, VCM ends the current Turn and starts a 10 second timer. During that timer, the Round is still `running`. If another `UserPromptSubmit` fires inside that window, the same Round continues and VCM increments the Turn count. If no new prompt is accepted before the deadline, VCM marks the Round as `stopped`.
+Check that:
 
-The normal path is timer-driven: `Stop` starts a backend timer, and `UserPromptSubmit` cancels it.
+- conversation translation is enabled
+- Translator session is running
+- the target role has an active Claude Code transcript
+- reply scope includes the content you expect to translate
 
-When `Flow pause alert` is enabled, the frontend polls the task Round state and deduplicates each stopped Round so the same stopped state does not alert on every poll. Flow duration is measured from the first `UserPromptSubmit` to `stoppedAt`, falling back to the last `Stop` when needed. If the flow lasted less than 2 minutes, it plays the local chime 3 times at 1.4 second intervals. If the flow lasted 2 minutes or longer, it shows a modal alert and repeats the local chime until the user clicks `Confirm`. A stopped Round can mean normal completion, user decision needed, dispatch failure, or another workflow interruption; the point is to get the user to look with the right amount of urgency.
+### Gateway cannot send messages
 
-The Round dock separates wall-clock Round duration from role active runtime. For a running Round, `Total` is `now - Round.startedAt`; for a stopped Round, it is `stoppedAt - Round.startedAt`. `Role runtime` is only the accumulated time between each Turn's `UserPromptSubmit` and `Stop`; `Turn count` is the number of accepted prompts inside the Round.
+Check that:
 
-## Resume Behavior
+- Gateway connection is configured
+- Gateway is turned on for task-changing commands
+- a project and task are selected
+- the PM session is running and idle
 
-Each role session stores its Claude session id and transcript path under:
+## Development
 
-```text
-.ai/vcm/sessions/<task>.json                  # under the task runtime repo
-```
-
-Session buttons behave as follows:
-
-- `Start`: creates a fresh UUID, builds `claude --agent <role> --session-id <uuid>`, and stores the transcript path.
-- `Resume`: reuses the persisted Claude session id and builds `claude --agent <role> --resume <uuid>`.
-- `Restart`: stops the current process if needed, creates a new UUID, and starts a fresh Claude session.
-- `Stop`: stops the embedded terminal process and leaves the persisted Claude session id resumable.
-
-Ordinary VCM role sessions do not persist raw terminal logs under handoff state. Claude Code transcript JSONL files under `~/.claude/projects/` are the semantic record used for output translation and recovery.
-
-## Local Project Files
-
-For a connected repository, VCM uses:
-
-```text
-<vcmDataDir>/projects/<project-id>/config.json
-<vcmDataDir>/projects/<project-id>/tasks/<task>.json
-<baseRepoRoot>/.claude/worktrees/<task>/
-<taskRepoRoot>/.ai/vcm/sessions/<task>.json
-<taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<taskRepoRoot>/.ai/vcm/orchestration/<task>.json
-<taskRepoRoot>/.ai/vcm/translation/<task>/
-<taskRepoRoot>/.ai/vcm/handoffs/architecture-plan.md
-<taskRepoRoot>/.ai/vcm/handoffs/known-issues.md
-<taskRepoRoot>/.ai/vcm/handoffs/review-report.md
-<taskRepoRoot>/.ai/vcm/handoffs/docs-sync-report.md
-<taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
-<taskRepoRoot>/.ai/vcm/gate-reviews/
-<baseRepoRoot>/.ai/vcm/gate-reviewer/session.json
-<baseRepoRoot>/.ai/vcm/translations/
-```
-
-The project config is stored under `vcmDataDir` so it is durable local app state. `vcmDataDir` is `VCM_DATA_DIR` when set, otherwise `~/.vcm`. For Dev Containers, prefer:
-
-```json
-{
-  "containerEnv": {
-    "VCM_DATA_DIR": "/workspace/.ai/vcm"
-  }
-}
-```
-
-For every task, `taskRepoRoot` is `<baseRepoRoot>/.claude/worktrees/<task>`.
-
-## Packaging
-
-The npm package publishes built output, not raw TypeScript entry files. `package.json` includes:
-
-- `bin.vcm`: `dist/main.js`
-- `files`: `dist`, `dist-frontend`, `scripts`, `README.md`
-- `prepack`: `npm run build && npm run verify:package`
-
-Use this before publishing:
+Useful commands:
 
 ```bash
 npm run typecheck
@@ -667,30 +462,23 @@ npm run build
 npm run verify:package
 ```
 
-## Validation
+Development server:
+
+```bash
+npm run dev
+```
+
+Production-style run:
 
 ```bash
-npm run typecheck
-npm test
 npm run build
+npm start
 ```
 
-## Current Boundaries
-
-- VCM does not use tmux.
-- VCM does not auto-confirm Claude Code permission prompts.
-- VCM does not isolate roles with separate worktrees; roles for one task share one task worktree.
-- VCM does not translate Claude output from raw PTY output; translation reads Claude transcript JSONL files.
-- VCM does not write translation output into handoff artifacts unless a user or role explicitly copies it there.
-- Role file writes happen in the task worktree when a task has a worktree.
-- The safest sandbox today is a container or VM boundary controlled by the user.
-
-See also:
-
-- `docs/product-design.md`
-- `docs/v0.2-implementation-plan.md`
-- `docs/vcm-cc-best-practices.md`
-- `docs/full-harness-baseline.md`
-- `docs/gate-review-gates.md`
-- `docs/claude-code-translation-plan.md`
-- `docs/cc-best-practices.md` is archived and no longer maintained.
+## Documentation
+
+- `docs/ARCHITECTURE.md`: repository architecture
+- `docs/TESTING.md`: validation strategy
+- `docs/vcm-cc-best-practices.md`: current VCM Claude Code harness practice
+- `docs/v0.5-custom-workflow-plan.md`: future custom workflow plan
+- `docs/cc-best-practices.md`: archived generic Claude Code harness notes

package/dist/backend/services/harness-service.js

@@ -1656,7 +1656,7 @@ Required work:
 - Run .ai/tools/generate-public-surface from the target task worktree after module-index.json exists.
 - Add or update project-specific Project Context and Project Constraints in target CLAUDE.md above the VCM managed block.
 - Fill target docs/ARCHITECTURE.md with project-level module overview, responsibilities, relationships, dependency direction, project-wide constraints, and links to module-level architecture docs.
-- Create or update target module-level ARCHITECTURE.md files for clear module boundaries listed by module-index.json.
+- Create or update target module-level ARCHITECTURE.md files for clear non-root module boundaries with architectureDoc paths in module-index.json.
 - Fill target docs/TESTING.md with project-native validation levels, commands, validation selection rules, final-validation cleanup, test layout, integration/E2E case lists, generated-context freshness checks, and known testing gaps.
 - Review git status and git diff in the target task worktree.
 - Stage only allowed bootstrap harness changes and create a commit in the target task worktree.

package/dist/backend/templates/harness/vcm-harness-bootstrap-skill.js

@@ -17,7 +17,7 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 1. Generate context when supported: run \`.ai/tools/generate-module-index\`, then run \`.ai/tools/generate-public-surface\` after \`module-index.json\` exists.
 2. Inspect the project:  read \`README.md\`, read \`CLAUDE.md\`, durable project docs, project manifests/config, source layout, tests, and existing validation commands.
 3. Fill project context: add or update non-managed project facts in \`CLAUDE.md\` above the VCM managed block.
-4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files, and \`docs/TESTING.md\` with detailed project-specific content.
+4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files for clear non-root module boundaries, and \`docs/TESTING.md\` with detailed project-specific content.
 5. Preserve user-authored content and VCM managed blocks.
 6. Review \`git status\` and \`git diff\`.
 7. Stage only allowed bootstrap harness changes and create a commit in the active task worktree.
@@ -29,7 +29,7 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 - \`docs/ARCHITECTURE.md\`
 - \`docs/TESTING.md\`
 - \`docs/known-issues.md\` only for confirmed durable issues
-- module-level \`ARCHITECTURE.md\` files
+- module-level \`ARCHITECTURE.md\` files for clear non-root module boundaries
 - \`.ai/generated/module-index.json\`
 - \`.ai/generated/public-surface.json\`
 
@@ -55,7 +55,8 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 
 ### Module-Level \`ARCHITECTURE.md\`
 
-- Create or update one module-level \`ARCHITECTURE.md\` for each clear module boundary.
+- Create or update one module-level \`ARCHITECTURE.md\` for each clear non-root module boundary with an \`architectureDoc\` path in \`.ai/generated/module-index.json\`.
+- Do not create a root-level \`ARCHITECTURE.md\` only because the root package exists.
 - Document module boundaries, responsibilities, allowed dependencies, important behavior, important public surface explanations, risks, and update triggers.
 - Keep complete public API listings in \`.ai/generated/public-surface.json\`; module docs should explain meaning and design intent, not duplicate the full generated index.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.6.16",
+  "version": "0.6.17",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/harness-tools/generate-module-index

@@ -327,22 +327,21 @@ def build_node_index(project_root: Path, node_root: Path) -> dict:
             layer_by_name[layer_name] = layer
             layers.append(layer)
 
-        layer_by_name[layer_name]["modules"].append(
-            {
-                "name": record["name"],
-                "path": module_path,
-                "manifest": manifest_rel,
-                "architectureDoc": f"{module_path}/ARCHITECTURE.md"
-                if module_path != "."
-                else "ARCHITECTURE.md",
-                "workspaceDependencies": record["workspaceDependencies"],
-                "language": "typescript",
-                "files": {
-                    "source": source_files,
-                    "tests": test_files,
-                },
-            }
-        )
+        module_entry = {
+            "name": record["name"],
+            "path": module_path,
+            "manifest": manifest_rel,
+            "workspaceDependencies": record["workspaceDependencies"],
+            "language": "typescript",
+            "files": {
+                "source": source_files,
+                "tests": test_files,
+            },
+        }
+        if module_path != ".":
+            module_entry["architectureDoc"] = f"{module_path}/ARCHITECTURE.md"
+
+        layer_by_name[layer_name]["modules"].append(module_entry)
 
     return {
         "schemaVersion": 1,
@@ -441,21 +440,20 @@ def build_cargo_index(project_root: Path, cargo_root: Path) -> dict:
             layer_by_name[layer_name] = layer
             layers.append(layer)
 
-        layer_by_name[layer_name]["modules"].append(
-            {
-                "name": record["name"],
-                "path": module_path,
-                "manifest": manifest_rel,
-                "architectureDoc": f"{module_path}/ARCHITECTURE.md"
-                if module_path != "."
-                else "ARCHITECTURE.md",
-                "workspaceDependencies": record["workspaceDependencies"],
-                "files": {
-                    "source": rust_files_under(module_dir, project_root, "src"),
-                    "tests": rust_files_under(module_dir, project_root, "tests"),
-                },
-            }
-        )
+        module_entry = {
+            "name": record["name"],
+            "path": module_path,
+            "manifest": manifest_rel,
+            "workspaceDependencies": record["workspaceDependencies"],
+            "files": {
+                "source": rust_files_under(module_dir, project_root, "src"),
+                "tests": rust_files_under(module_dir, project_root, "tests"),
+            },
+        }
+        if module_path != ".":
+            module_entry["architectureDoc"] = f"{module_path}/ARCHITECTURE.md"
+
+        layer_by_name[layer_name]["modules"].append(module_entry)
 
     return {
         "schemaVersion": 1,