cmdr-mcp 0.4.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
     {
       "name": "cmdr",
       "source": "./plugins/cmdr",
-      "version": "0.4.0",
+      "version": "0.6.0",
       "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders."
     }
   ],
-  "description": "Local multi-agent squads for Claude Code, Codex, ZCode and other MCP hosts."
+  "description": "Local multi-agent squads for Claude Code, Codex, ZCode, Kimi Code and other MCP hosts."
 }

package/README.md

@@ -1,6 +1,6 @@
 # cmdr
 
-**Local squads for coding agents.** Connect existing Claude Code, Codex, ZCode and other MCP-capable Agent sessions. A commander dispatches tasks; executors report progress and ask questions. Messages persist in SQLite and arrive in priority order.
+**Local squads for coding agents.** Connect existing Claude Code, Codex, ZCode, Kimi Code and other MCP-capable Agent sessions. A commander dispatches tasks; executors report progress and ask questions. Messages persist in SQLite and arrive in priority order.
 
 [中文说明](docs/README.zh-CN.md) · [Design specification](docs/cmdr-design-v1.md) · [Host integration](docs/agent-integration.md) · [Implementation and verification](docs/implementation.md)
 
@@ -8,7 +8,7 @@
 
 Requires macOS or Linux and **Node.js ≥22.5** (24 recommended). The development branch contains source and plugin metadata. npm packages and the generated `marketplace` branch include the runtime bundles.
 
-**One-command setup (0.4.0):** replace `claude-code` with `codex` or `zcode` for your host.
+**One-command setup (0.6.0):** replace `claude-code` with `codex`, `zcode` or `kimi-code` for your host.
 
 ```sh
 npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
@@ -42,7 +42,7 @@ For distribution, `npm pack` (or `npm publish`) runs `prepack` to build the four
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.4.0.tgz
+npm install --global ./cmdr-mcp-0.6.0.tgz
 cmdr --help
 ```
 
@@ -70,6 +70,10 @@ Open a workspace, then **Settings → Plugins → Create → Add plugin marketpl
 
 The native `.zcode-plugin` manifest sets up MCP, commands and skills; ZCode discovers the four supported lifecycle hooks automatically. Local developers can still select a built checkout or installed npm package root. See [ZCode setup and verification](docs/agent-integration.md#zcode-desktop).
 
+**Kimi Code desktop**
+
+Run `npx -y --package=cmdr-mcp@latest cmdr setup --agent kimi-code`, then restart the Kimi Code app (its hook executor caches `config.toml` at startup). Setup writes the cmdr MCP server into `~/.kimi-code/mcp.json`, five lifecycle hooks into `~/.kimi-code/config.toml` and links the `cmdr` and `cmdr-identity` skills into `~/.kimi-code/skills/`. Kimi pools one MCP process per workspace, so every cmdr call must carry your session identity: the `cmdr-identity` skill renders your real session id (`${KIMI_SESSION_ID}`) and instructs the model to pass it as `_cmdr_session` on every call. The native `.kimi-plugin` manifest declares MCP, commands, skills and the same hooks for installation through the host plugin manager, with `sessionStart.skill` injecting the identity skill into every new or resumed session. See [Kimi Code setup and verification](docs/agent-integration.md#kimi-code-desktop).
+
 **Other Agents**
 
 Use any MCP stdio client. Generate a configuration with an absolute executable path:
@@ -94,32 +98,55 @@ Joining by name atomically creates or finds a persistent channel and defaults to
 2. The commander inspects `list`, then `send`s clear tasks with acceptance criteria.
 3. Executors `read`, immediately acknowledge with `report(status="working", reply_to=<command id>)`, do the work, then report done/failed/cancelled with the same `reply_to`.
 4. Executors use `ask` when blocked; the commander responds with `send(type="answer", reply_to=<ask id>)`.
-5. Use `join(..., standby="auto")`. Claude/ZCode then arm `listener.arm.command` with its indicated native tool. Inspect `list` for listener health. With `can_auto_respond=true`, end the idle turn. Unsupported hosts remain manual; the skills bound fallback polling to two waits and explain manual continuation.
+5. Use `join(..., standby="auto")`. Claude/ZCode/Kimi then arm `listener.arm.command` with its indicated native tool. Inspect `list` for listener health. With `can_auto_respond=true`, end the idle turn. Unsupported hosts remain manual; the skills bound fallback polling to two waits and explain manual continuation.
 6. `leave` preserves queued messages. Commander departure orphans the squad; `leave(dissolve=true)` disbands it.
 
-Codex wakes through app-server proxy or the `codex queue` fallback. Claude uses Monitor and ZCode uses background Bash completion through the built-in `cmdr standby watch`; re-arm after task termination. See [Long-running collaboration](docs/long-running-collaboration.md) for capabilities, recovery, handover and compatibility requirements.
+Codex wakes through app-server proxy or the `codex queue` fallback. Claude uses Monitor; ZCode and Kimi Code use background Bash completion through the built-in `cmdr standby watch`; re-arm after task termination. See [Long-running collaboration](docs/long-running-collaboration.md) for capabilities, recovery, handover and compatibility requirements.
 
 ## Tools
 
-Exactly seven MCP tools are exposed, independently of the host:
+Exactly nine MCP tools are exposed, independently of the host:
 
-| Tool | Purpose |
-| --- | --- |
-| `join` | Atomic join/create by `squad_name`, or explicit `role` and squad ID |
-| `list` | Task ownership, unacknowledged age, progress, connection state and listener health |
-| `send` | Commands, cancel, answers and info; task_key deduplication and gated reassign |
-| `report` | Executor ready, working, blocked, done, failed or cancelled reports |
-| `ask` | Executor questions, optionally waiting for a correlated answer |
-| `read` | Priority dequeue, peek/history, recover, ID lookup and long polling |
-| `leave` | Leave, orphan or dissolve a squad |
+| Tool       | Purpose                                                                                  |
+| ---------- | ---------------------------------------------------------------------------------------- |
+| `join`     | Atomic join/create by `squad_name`, or explicit `role` and squad ID                      |
+| `list`     | Task ownership, unacknowledged age, progress, connection state and listener health       |
+| `send`     | Commands, cancel, answers and info; task_key deduplication and gated reassign            |
+| `report`   | Executor ready, working, blocked, done, failed or cancelled reports                      |
+| `ask`      | Executor questions, or commander `target=user` dashboard questions and handling receipts |
+| `read`     | Priority dequeue, peek/history, recover, ID lookup and long polling                      |
+| `leave`    | Leave, orphan or dissolve a squad                                                        |
+| `task`     | Create, update, query and archive persistent dashboard tasks                             |
+| `artifact` | Publish/query isolated HTML explanations for tasks and questions                         |
 
 Every successful tool result includes identity, recommended wait and unread count. Reports carry their status in `message.data.status`. Unread messages are retained across daemon restarts; reads mark them delivered and leave history. Delivery is distinct from acceptance and completion. `read(recover=true)` non-destructively lists all unfinished commands, including already-read work. `pending=0`, `unread=0` and `offline` never release task ownership. `read`/`list` are compact by default; use `full=true` for expanded metadata. ID lookups also enforce the reassignment gate before exposing queued replacement work. Listings never include command bodies; use `read(id=...)` for your own inbox or operator `tail --full` for observation. No exactly-once execution guarantee is made.
 
+## Local dashboard
+
+Run `cmdr dashboard` (or the stable CLI path printed by setup) to open the built-in React dashboard. `--no-open` prints short-lived access URLs for `127.0.0.1` and the machine’s non-loopback IPv4 addresses. The server binds to `0.0.0.0` on a system-assigned port; each address has its own single-use token, so opening the local link does not consume the LAN links. One page switches between squads, with a task workspace, a member/activity dock, and a persistent confirmation panel. Users can submit structured answers or send a note to the selected squad’s commander; notes enter the existing user-message queue without directly changing tasks. The HTTP/SSE service runs inside the existing daemon; closing the page does not stop collaboration.
+
+Dashboard UI copy follows the system/browser’s preferred language: Chinese (`zh-*`) uses Simplified Chinese; other languages use English. Agent/user content and HTML artifacts remain unchanged. Reload after changing the browser language.
+
+Example dashboard with demo data: multiple squads, task progress, member status, HTML explanations and user answers. Agent content in this example was written in English; it is not automatically translated.
+
+![English dashboard showing the task board and user decision panel](.github/assets/dashboard/main-en.png)
+
+<details>
+<summary>Task details with the answer form kept open</summary>
+
+![English task details, execution history and user answer form](.github/assets/dashboard/detail-en.png)
+
+</details>
+
+[View the Chinese dashboard example](.github/assets/dashboard/main.jpg).
+
+Commanders create tasks with `task(action="create", title=...)`, dispatch using `send(task_id=..., to=..., message=...)`, and ask the user with `ask(target="user", question=..., kind="single|multiple|text|confirm")`. Answers enter the stable commander inbox; explicitly use `ask(target="user", action="handle", id=..., version=..., result=...)` after processing. `artifact` publishes self-contained sandboxed HTML explanations. See [dashboard operations and limits](docs/dashboard.md).
+
 ## Installation diagnostics and member CLI
 
 If cmdr tools are absent, inspect the host's actual plugin cache with `cmdr doctor --plugin-root /path/to/cached/plugin`. Add `--deep` to check MCP and daemon access in a temporary state directory. The checker works even when the inspected CLI bundle is missing. Refresh/reinstall damaged caches from the complete npm package and start a new session.
 
-`cmdr session join|list|send|report|ask|read|leave` provides member operations when MCP tools are unavailable. Supply `--agent` and `--native-id` (or `CMDR_AGENT`/`CMDR_SESSION_ID`); use the same native ID as the host. These commands retain membership and messages after exit, and display connection presence as `cli`; execution state is reported separately.
+`cmdr session join|list|send|report|ask|read|leave|task|artifact` provides member operations when MCP tools are unavailable. Supply `--agent` and `--native-id` (or `CMDR_AGENT`/`CMDR_SESSION_ID`); use the same native ID as the host. These commands retain membership and messages after exit, and display connection presence as `cli`; execution state is reported separately.
 
 ```sh
 cmdr session join --agent zcode --native-id YOUR_SESSION_ID --squad-name my-project
@@ -172,7 +199,7 @@ npm run check
 npm run verify:zcode   # optional: requires the locally installed ZCode desktop runtime
 ```
 
-`npm run check` checks formatting/types, builds the four entry points, runs unit/real-process tests, then packs and installs the npm tarball offline in a temporary prefix to verify the CLI and seven MCP tools. CI runs on macOS/Linux with Node 22/24 and checks generated bundles are not tracked by Git. The optional ZCode check validates, installs and connects the plugin using an isolated desktop runtime, without making a model request.
+`npm run check` checks formatting/types, builds the four entry points, runs unit/real-process tests, then packs and installs the npm tarball offline in a temporary prefix to verify the CLI and nine MCP tools. CI runs on macOS/Linux with Node 22/24 and checks generated bundles are not tracked by Git. The optional ZCode check validates, installs and connects the plugin using an isolated desktop runtime, without making a model request.
 
 For development, `claude --plugin-dir ./plugins/cmdr` loads the plugin directly. Installed hosts use cached copies: reinstall/refresh after changing a plugin. Version numbers come from `package.json`; after same-version changes, restart the daemon explicitly. Generated bundles and third-party license notices are ignored by Git and included in the npm package.
 

package/docs/README.zh-CN.md

@@ -1,6 +1,6 @@
 # cmdr
 
-让本机已经打开的 **Claude Code、Codex、ZCode 和其他支持 MCP 的 Agent** 组成小队：指挥官发任务，执行方汇报、提问，消息按优先级持久化到 SQLite。
+让本机已经打开的 **Claude Code、Codex、ZCode、Kimi Code 和其他支持 MCP 的 Agent** 组成小队：指挥官发任务，执行方汇报、提问，消息按优先级持久化到 SQLite。
 
 [English](../README.md) · [设计方案](cmdr-design-v1.md) · [接入指南](agent-integration.md) · [实现与验证记录](implementation.md)
 
@@ -8,7 +8,7 @@
 
 支持 macOS / Linux，需要 Node.js ≥22.5（推荐 24）。开发分支保存源码和插件元数据；npm 发布包及自动生成的 `marketplace` 分支包含完整运行时。
 
-**一条命令完整安装（0.4.0）**，将 `claude-code` 换成实际使用的 `codex` 或 `zcode`：
+**一条命令完整安装（0.6.0）**，将 `claude-code` 换成实际使用的 `codex`、`zcode` 或 `kimi-code`：
 
 ```sh
 npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
@@ -42,7 +42,7 @@ npm run build
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.4.0.tgz
+npm install --global ./cmdr-mcp-0.6.0.tgz
 cmdr --help
 ```
 
@@ -68,6 +68,8 @@ ZCode 桌面端：打开工作区，在 **设置 → 插件 → 创建 → 添
 
 原生 `.zcode-plugin` 清单负责 MCP、命令和技能，ZCode 自动发现 4 类受支持的 hooks。本地开发仍可选择已构建的仓库或已安装 npm 包根目录。
 
+Kimi Code 桌面端：运行 `npx -y --package=cmdr-mcp@latest cmdr setup --agent kimi-code`，然后重启 Kimi Code 应用（其 hook 执行器启动时缓存 `config.toml`）。setup 会把 cmdr MCP server 写入 `~/.kimi-code/mcp.json`、把 5 个生命周期 hooks 写入 `~/.kimi-code/config.toml`，并把 `cmdr` 与 `cmdr-identity` 技能链接到 `~/.kimi-code/skills/`。Kimi 按工作区共享一个 MCP 进程，所以每次调用 cmdr 都必须携带会话身份：`cmdr-identity` 技能会把你的真实会话 ID（`${KIMI_SESSION_ID}`）渲染出来，并要求模型在每次调用时以 `_cmdr_session` 传入。原生 `.kimi-plugin` 清单通过宿主插件管理器声明 MCP、命令、技能和同样的 hooks，并用 `sessionStart.skill` 在每个新建或恢复的会话自动注入身份技能。详见[接入指南的 Kimi Code 章节](agent-integration.md)。旧的手动配置如果在 `mcp.json` 里固定过 `CMDR_SESSION_ID`，请移除后重跑 setup。
+
 其他 Agent：
 
 ```sh
@@ -88,11 +90,11 @@ ZCode 桌面端：打开工作区，在 **设置 → 插件 → 创建 → 添
 
 执行方加入后 `report(ready)` 报到，说明目录、能力和当前上下文。指挥官通过 `list` 看成员，用 `send` 下发可验证任务。执行方 `read` 读取任务后立即用 `report(working, reply_to=<command id>)` 接单，再带相同 `reply_to` 汇报 done/failed/cancelled，遇到阻塞用 `ask` 提问；指挥官通过 `send(type="answer", reply_to=<ask id>)` 回答。
 
-加入时设置 `standby="auto"`，再按 `listener.arm` 和 `list` 的健康状态操作。Codex 由 daemon 自动探测 proxy，并在不可用时尝试 `codex queue`；Claude 使用原生 Monitor，ZCode 使用 `run_in_background=true` 的后台 Bash，两者都运行内置 `cmdr standby watch`。宿主 watcher 真正挂载后才显示 `can_auto_respond=true`，此时可结束空闲回合；任务完成、失败、到期或宿主重启后重新挂载。只有不支持原生通知或挂载失败时，才退回两次有限轮询并说明需人工续接。完整操作与边界见[长期协作](long-running-collaboration.md)。
+加入时设置 `standby="auto"`，再按 `listener.arm` 和 `list` 的健康状态操作。Codex 由 daemon 自动探测 proxy，并在不可用时尝试 `codex queue`；Claude 使用原生 Monitor，ZCode 和 Kimi Code 使用 `run_in_background=true` 的后台 Bash，都运行内置 `cmdr standby watch`。宿主 watcher 真正挂载后才显示 `can_auto_respond=true`，此时可结束空闲回合；任务完成、失败、到期或宿主重启后重新挂载。只有不支持原生通知或挂载失败时，才退回两次有限轮询并说明需人工续接。完整操作与边界见[长期协作](long-running-collaboration.md)。
 
 ## 工具和运维
 
-固定 7 个 MCP 工具：`join`、`list`、`send`、`report`、`ask`、`read`、`leave`。读取即出队，`peek` 不出队，`history` 可回看。报告状态保存在 `message.data.status`。指挥官离队后小队变为 orphaned，可按原 ID 接管；`leave(dissolve=true)` 解散小队，但已经排队的消息仍可读取。
+固定 9 个 MCP 工具：`join`、`list`、`send`、`report`、`ask`、`read`、`leave`、`task`、`artifact`。读取即出队，`peek` 不出队，`history` 可回看。报告状态保存在 `message.data.status`。指挥官离队后小队变为 orphaned，可按原 ID 接管；`leave(dissolve=true)` 解散小队，但已经排队的消息仍可读取。
 
 ```sh
 plugins/cmdr/bin/cmdr status
@@ -122,7 +124,7 @@ npm run check
 npm run verify:zcode
 ```
 
-`check` 包括格式、类型、打包、单元/真实进程测试，以及 npm tarball 在临时目录中的离线安装和 7 个工具验证。ZCode 验证可选，需要已安装桌面端；它在临时目录使用 App 内置运行时验证插件和 7 个 MCP 工具连接，不发起模型请求。
+`check` 包括格式、类型、打包、单元/真实进程测试，以及 npm tarball 在临时目录中的离线安装和 9 个工具验证。ZCode 验证可选，需要已安装桌面端；它在临时目录使用 App 内置运行时验证插件和 9 个 MCP 工具连接，不发起模型请求。
 
 插件版本由 `package.json` 统一生成。源码修改后需重新打包，并更新宿主缓存；同版本代码变更需手动重启 daemon。CI 验证 macOS/Linux、Node 22/24、npm 包可运行性，并确保生成产物没有被 Git 跟踪。
 
@@ -130,9 +132,9 @@ npm run verify:zcode
 
 ## 安装诊断与成员 CLI
 
-工具未出现时，用 `cmdr doctor --plugin-root /实际宿主缓存中的插件目录` 检查缓存里的文件校验和与版本。加 `--deep` 会在临时数据目录中完成 MCP 握手、7 个工具检查及 daemon 访问，不操作正常小队。基础检查器独立于 dist，CLI bundle 缺失时仍可诊断；Node 缺失时先安装 Node。修复采用完整 npm 包重新注册市场、刷新/重装缓存并打开新会话，不跨安装目录链接 dist。
+工具未出现时，用 `cmdr doctor --plugin-root /实际宿主缓存中的插件目录` 检查缓存里的文件校验和与版本。加 `--deep` 会在临时数据目录中完成 MCP 握手、9 个工具检查及 daemon 访问，不操作正常小队。基础检查器独立于 dist，CLI bundle 缺失时仍可诊断；Node 缺失时先安装 Node。修复采用完整 npm 包重新注册市场、刷新/重装缓存并打开新会话，不跨安装目录链接 dist。
 
-`cmdr session join|list|send|report|ask|read|leave` 提供完整成员操作，原有运维命令含义不变。显式传 `--agent`、`--native-id`，或设置 `CMDR_AGENT`、`CMDR_SESSION_ID`；与 MCP/hook 共享会话时必须使用相同原生 ID，共享 MCP 进程不能配置一个固定 ID。CLI 显示 `presence=cli`，退出后保留成员关系和任务状态；连接结束不代表模型停工。监听由 daemon 独立管理。
+`cmdr session join|list|send|report|ask|read|leave|task|artifact` 提供完整成员操作，原有运维命令含义不变。显式传 `--agent`、`--native-id`，或设置 `CMDR_AGENT`、`CMDR_SESSION_ID`；与 MCP/hook 共享会话时必须使用相同原生 ID，共享 MCP 进程不能配置一个固定 ID。CLI 显示 `presence=cli`，退出后保留成员关系和任务状态；连接结束不代表模型停工。监听由 daemon 独立管理。
 
 ```sh
 cmdr session join --agent zcode --native-id YOUR_SESSION_ID --squad-name my-project
@@ -143,3 +145,26 @@ cmdr session report --agent zcode --native-id YOUR_SESSION_ID --status done --re
 指挥官必须显式声明 role=commander，report/ask 由执行者调用。结果为 JSON，失败使用非零退出码。`--input` 接受该操作完整 JSON 参数；`--timeout`、SIGINT/SIGTERM 可取消等待，等待中的 read 取消不消费后续消息。ask 取消前可能已发送，不能盲目重试。
 
 `CMDR_HOME/logs/diagnostics/` 保存有界、限频的元数据快照。hook 仍失败放行，不写消息正文；unknown 表示尚未观察到，配置存在不代表真实触发。doctor 显示 provisional 会话及等待推荐来源；升级诊断不进入任务消息队列。详细案例见[排障说明](troubleshooting.md)。
+
+## 内置看板
+
+运行 `cmdr dashboard` 打开本机看板；setup 安装使用其返回的稳定 CLI 路径。`--no-open` 输出 `127.0.0.1` 及本机非回环网卡 IPv4 的短时访问地址。服务默认监听 `0.0.0.0`，端口由系统分配；各地址使用独立的一次性凭证，本机自动打开不影响局域网链接使用。单个 React 页面切换多个小队，以任务工作区、底部成员／活动坞和常驻确认面板展示进展。用户通过内置表单提交答复，也可向当前小队的指挥官留言；留言复用现有用户消息队列，不直接修改任务。普通进展更新不会整页刷新，切换小队保留表单草稿。
+
+看板文案默认跟随系统／浏览器首选语言：中文（`zh-*`）显示简体中文，其他语言显示英文。Agent／用户内容与 HTML 展示保持原样；更改浏览器语言后刷新页面生效。
+
+看板示例（演示数据）：同页查看多个小队、任务进展和成员状态，通过右侧表单回复问题或向指挥官留言。
+
+![中文看板：任务进展、成员状态和用户答复面板](../.github/assets/dashboard/main.jpg)
+
+<details>
+<summary>查看英文版看板及任务详情</summary>
+
+英文示例的任务、问题和 HTML 内容使用预先准备的英文演示数据，不是自动翻译的 Agent 消息。
+
+![英文看板示例](../.github/assets/dashboard/main-en.png)
+
+![英文任务详情与常驻答复表单](../.github/assets/dashboard/detail-en.png)
+
+</details>
+
+指挥官通过 `task` 管理任务，`send(task_id=...)` 关联派发，`ask(target="user")` 创建问题，`artifact` 发布隔离的 HTML 补充说明。用户答案持久化后进入当前指挥官收件箱；读取不代表处理，使用 `ask(target="user", action="handle", id=..., version=..., result=...)` 明确记录结果。关闭页面不结束小队。数据隔离、重试、恢复、HTML 限制和升级见[看板使用说明](dashboard.md)。

package/docs/agent-integration.md

@@ -2,7 +2,7 @@
 
 Build a source checkout with `npm ci && npm run build`, or use the unpacked/installed npm package. Git does not contain generated runtime bundles. `npm pack` / `npm publish` builds and includes them automatically.
 
-The daemon and message model accept arbitrary lowercase Agent IDs (`[a-z][a-z0-9_-]{0,63}`), not a closed Claude/Codex enum. All hosts share the same seven MCP tools. Specialized adapters add identity, working-directory discovery and lifecycle reminders; none is required to use the queue.
+The daemon and message model accept arbitrary lowercase Agent IDs (`[a-z][a-z0-9_-]{0,63}`), not a closed Claude/Codex enum. All hosts share the same nine MCP tools. Specialized adapters add identity, working-directory discovery and lifecycle reminders; none is required to use the queue.
 
 For automatic runtime, skill and user MCP/hooks installation, use [standalone setup](setup.md). The manual and native-plugin contracts follow below.
 
@@ -16,14 +16,14 @@ The output uses an absolute executable path and a conventional `mcpServers` obje
 
 Environment contract:
 
-| Variable | Meaning |
-| --- | --- |
-| `CMDR_AGENT` | Stable host identifier, e.g. `opencode`, `zcode`, `my-agent`; default `generic` when undetected |
-| `CMDR_SESSION_ID` | Optional unique native session ID, stable across resume; never reuse one ID for concurrent independent sessions |
-| `CMDR_CWD` | Optional actual session directory, useful when MCP launches in a plugin directory |
-| `CMDR_SESSION_TITLE` | Optional session title for the board |
-| `CMDR_TOOL_TIMEOUT_SEC` | The timeout **already configured on the host**; informs wait recommendations, does not change the host timeout |
-| `CMDR_HOME` | Shared daemon/state directory; all participating sessions must use the same value |
+| Variable                | Meaning                                                                                                         |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `CMDR_AGENT`            | Stable host identifier, e.g. `opencode`, `zcode`, `my-agent`; default `generic` when undetected                 |
+| `CMDR_SESSION_ID`       | Optional unique native session ID, stable across resume; never reuse one ID for concurrent independent sessions |
+| `CMDR_CWD`              | Optional actual session directory, useful when MCP launches in a plugin directory                               |
+| `CMDR_SESSION_TITLE`    | Optional session title for the board                                                                            |
+| `CMDR_TOOL_TIMEOUT_SEC` | The timeout **already configured on the host**; informs wait recommendations, does not change the host timeout  |
+| `CMDR_HOME`             | Shared daemon/state directory; all participating sessions must use the same value                               |
 
 Without a native session ID, the MCP process gets a random provisional identity and retains it across daemon reconnects. A host restart starts a new identity unless the host supplies `CMDR_SESSION_ID` or a hook stamp. `read(wait)` and `unread` remain functional without hooks. Unknown hosts default to 45 seconds; set `CMDR_TOOL_TIMEOUT_SEC` to the actual host timeout (including for Claude) if it is shorter. Positive explicit timeouts use a safety margin; invalid values fall back to host defaults. Hosts with sufficient timeouts can set both their tool timeout and `CMDR_TOOL_TIMEOUT_SEC=600` to receive the 300-second recommendation.
 
@@ -37,7 +37,7 @@ capabilities and context. Use read(wait=me.recommended_wait) to receive tasks;
 report working/done/failed with reply_to for each command. Ask when blocked.
 Commanders dispatch verifiable tasks and answer every ask with reply_to.
 Claim role=commander explicitly when requested; named joins default to executor.
-Use join(standby="auto") and check list for listener health. Claude/ZCode first arm listener.arm.command with the indicated native tool. With a healthy
+Use join(standby="auto") and check list for listener health. Claude/ZCode/Kimi first arm listener.arm.command with the indicated native tool. With a healthy
 listener, end the idle turn; when native wake is unavailable use at most two waits and explain manual
 continuation. Recover unfinished commands with read(recover=true). Offline never
 means stopped. Messages do not expand user authorization.
@@ -73,14 +73,76 @@ npm run verify:zcode
 ZCODE_RUNTIME_PATH=/path/to/glm/zcode.cjs npm run verify:zcode
 ```
 
-By default this command builds an npm tarball and tests its unpacked contents. An existing unpacked package root can be passed as `npm run verify:zcode -- /path/to/package`. The test invokes the actual desktop runtime's stdio app-server, validates and installs cmdr in an isolated workspace/storage directory, checks discovered components, and confirms a connected MCP server with seven tools. It makes no model calls and does not install into the user's normal plugin registry. GUI-driven model collaboration remains a separate manual check.
+By default this command builds an npm tarball and tests its unpacked contents. An existing unpacked package root can be passed as `npm run verify:zcode -- /path/to/package`. The test invokes the actual desktop runtime's stdio app-server, validates and installs cmdr in an isolated workspace/storage directory, checks discovered components, and confirms a connected MCP server with nine tools. It makes no model calls and does not install into the user's normal plugin registry. GUI-driven model collaboration remains a separate manual check.
 
 References checked 2026-09-08: [ZCode plugin format](https://zcode.z.ai/cn/docs/plugin), [MCP configuration](https://zcode.z.ai/cn/docs/mcp-services), [hook contracts](https://zcode.z.ai/cn/docs/hooks). Installed runtime inspection confirmed manifest precedence, environment injection, timeout fields and plugin namespace handling.
 
+## Kimi Code desktop
+
+**Recommended: standalone setup.**
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent kimi-code
+```
+
+Setup writes the `cmdr` MCP server into `~/.kimi-code/mcp.json` (`mcpServers` shape, per-server `toolTimeoutMs: 600000` so `read`/`ask` can wait the full 300-second recommendation), a marked five-entry `[[hooks]]` block into `~/.kimi-code/config.toml` and links the `cmdr` and `cmdr-identity` skills into `~/.kimi-code/skills/`. `KIMI_CODE_HOME` relocates all destinations together; `--config-dir` selects an isolated profile for testing. `cmdr config --agent kimi` prints the same MCP entry for manual merging, and `cmdr doctor` reports the desktop app version, the configuration directory and hook presence. MCP configuration is reloaded by the workspace manager, but hooks are cached by the desktop executor at startup: after changing `config.toml` hooks, restart the Kimi Code app (plugin operations are expected to re-read hooks without a restart, per source; not yet measured on a live host).
+
+The native `.kimi-plugin/plugin.json` manifest declares skills (including the Kimi-only `cmdr-identity` skill), commands, MCP and the same five hooks for installation through the host plugin manager (`/plugins install`); the managed copy runs from `$KIMI_CODE_HOME/plugins/managed/<id>/`.
+
+Facts below are split by evidence class. Some were observed on a live **Kimi Code desktop 1.0.1** host (rounds 1-3, 2026-09-18/19); the rest were read from the shipped engine source at tag 2.0.0 (`1b89e4b0`).
+
+**Observed on the live host:**
+
+- Hooks written to `config.toml` need an app restart. `mcp.json` changes take effect without one: a restored `mcp.json` replaced the running MCP processes in place.
+- Agent-level hook payloads (Stop, UserPromptSubmit, PreToolUse) carry the desktop bootstrap cwd `/`. SessionStart carries the workspace cwd, with `source=resume` for sessions restored at app start and `source=startup` for new ones.
+- A per-server `toolTimeoutMs: 600000` holds long waits (`read(wait=75)` returned after 79.7s), so the 300-second recommendation is safe.
+- Two sessions in one workspace share a single MCP process. With `_cmdr_session` stamps they still act as distinct members: in round 3, sessions A and B used one MCP process, and neither ever received a command addressed to the other.
+- Per-call identity works on both paths:
+  - A session that first ran `/skill:cmdr-identity` stamped its very first call with the rendered id.
+  - A session without the skill was blocked once by PreToolUse (exit 2, correct id in the reason) and retried with the stamp.
+- A session restored at app start sent SessionStart but bound nothing, which removes the round-2 misattribution.
+- UserPromptSubmit stdout reaches the model. A typed message surfaced "1 unread" and the session read the message and reported. Activating a skill with `/skill:` does not fire UserPromptSubmit.
+- A Stop exit 2 continued the turn once, and the session then handled the unread command.
+- Archiving a session fired SessionEnd with `reason=archive` and took the member offline, while the shared MCP process kept serving the other session.
+- The built-in watcher woke stamped sessions automatically, after 25s and 15s.
+
+**From the engine source (kimi-code 2.0.0):**
+
+- The shared MCP process is started per workspace from `mcp.json` (`workspaceMcpService.ts:58-70`, `:110-117`); the child environment carries no session id (`client-stdio.ts:191`, `:292-304`), and neither `initialize` nor `callTool` carries one (`client-stdio.ts:58-61`, `:122`). The MCP cwd is the workspace root.
+- `${KIMI_SESSION_ID}` in a skill body is replaced with the real session id on every render path - user `/skill` activation, the model's Skill tool call, and the plugin `sessionStart.skill` injection (`registry.ts:60-70`, `:166-168`; `agentPluginService.ts:121-132`, `:246-255`). The `cmdr-identity` skill (plugin-only file, plus setup-linked user skill) carries the per-call stamping rules; the `sessionStart.skill` manifest field injects it into the **main agent only**, so the main agent makes cmdr calls on behalf of subagents with the same stamp. Slash-command rendering of the placeholder is unverified - the identity source is the skill, not the `/cmdr` command.
+- A PreToolUse exit 2 turns into the tool call's error result carrying the stderr reason (`runHook.ts:140-151`; `beforeToolExecuteEvent.ts:19-21`), evaluated before permission approval; hooks cannot rewrite tool input (`runHook.ts:43-56`). The cmdr bridge independently rejects an unstamped kimi call with `SESSION_STAMP_REQUIRED` explaining the shared process and where to obtain the id.
+- UserPromptSubmit exit-0 stdout becomes a user message in the model context (`agentExternalHooksService.ts:370-385`) and fires only on real user input, never on watcher-woken turns; SessionStart stdout is dropped by the host (#2873).
+- A Stop exit 2 appends the reason as a user message and may continue the turn once (`stop_hook_active` is always false; `agentExternalHooksService.ts:235-260`, `:389-423`).
+- SessionEnd fires only on archive/delete of a loaded session (and CLI `/reload` exit), not on tab close or app quit (`sessionLifecycleService.ts:414-474`); plugin install/enable/disable or reload re-reads hooks (`pluginService.ts:91-167`).
+- Hooks are `[[hooks]]` tables (`event`, `matcher`, `command`, `timeout`); an unrecognized `event` fails the whole configuration load. All hook payloads carry the running session's `session_id` and `hook_event_name`. The five installed hooks:
+
+  | Event            | Role                                                                                                                                                                                                                                 |
+  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | SessionStart     | Presence and restored-session tracking; for Kimi it is also the only hook whose cwd may update the session record (agent-level payloads carry `/`); never binds identity (startup restores would misidentify the shared MCP process) |
+  | UserPromptSubmit | Unread-message reminder: exit 0 stdout becomes a user message in the model context; fires only on real user input, never on watcher-woken turns                                                                                      |
+  | PreToolUse       | Verifies `_cmdr_session` on cmdr tools (matcher matches the tool-name regex in `src/shared/env.ts`); silent on match, exit 2 + reason naming the expected id otherwise                                                               |
+  | Stop             | exit 2 + reason appends a user message and may continue the turn once; throttled per sequence                                                                                                                                        |
+  | SessionEnd       | Presence only; fires on archive/delete of a loaded session (and CLI `/reload` exit)                                                                                                                                                  |
+
+- **Wake** uses the same built-in watcher as ZCode: run `listener.arm.command` with Bash `run_in_background=true`; the watcher stays silent and exits on actionable work, and the completion notification starts the next turn. Re-arm after every completion, failure or kill.
+
+**Migration.** Earlier manual Kimi setups that pinned `CMDR_SESSION_ID` in `mcp.json` must remove it: the workspace-pooled MCP would otherwise route every session to one fixed member. Rerun `cmdr setup --agent kimi-code` to obtain the stamping hooks and the identity skill.
+
+The native plugin manifest carries no `CMDR_AGENT` binding: plugin hooks and the plugin MCP process are recognized as Kimi Code through the `KIMI_PLUGIN_ROOT` variable the host injects into plugin processes, so agent detection (and the exit-code-2 hook wrapper path) depends on that injection; the standalone setup path binds `CMDR_AGENT=kimi` in its launchers instead. Standalone setup and the native plugin are mutually exclusive — setup refuses to run while a managed `cmdr` plugin copy exists under `$KIMI_CODE_HOME/plugins/managed/`.
+
+### Remaining real-host checks
+
+Observed and source-verified semantics are above. Still open for live confirmation:
+
+1. Watcher re-arm after a daemon restart.
+2. Plugin install/enable reloading hooks without an app restart (expected from source; unconfirmed).
+3. `${KIMI_SESSION_ID}` substitution through the plugin `sessionStart.skill` in newly created, resumed and compacted sessions. The `/skill:cmdr-identity` path is confirmed.
+4. Whether slash-command files render `${KIMI_SESSION_ID}` (if they do, the identity paragraph can move into the `/cmdr` command too).
+
 ## Diagnostics and CLI members
 
 See [Troubleshooting](troubleshooting.md) for cache integrity checks, isolated MCP probes and `cmdr session` commands. Member CLI uses protocol 1, `kind=mcp` and `transport=cli` registration. Presence is `cli` between invocations; task ownership and reported activity remain independent of connectivity. The daemon supports `admin.standby`, `admin.events` and `admin.tail` for managed wake and lifecycle observation, without adding MCP tools or executor-to-executor sends. See [long-running collaboration](long-running-collaboration.md). `_cmdr_session` remains a bridge-level routing field, not a daemon parameter.
 
 ## Automatic wake
 
-Codex supports proxy and queue compatibility paths. Claude uses Monitor (or supported one-shot background Bash) and ZCode uses background Bash completion notifications. Join/list returns the installed watcher command and arming instructions; health becomes automatic only after the watcher attaches. Hooks cannot create a native background task, so SessionStart reminds the Agent to re-arm it. Unknown MCP hosts remain manual. See [automatic standby](long-running-collaboration.md#automatic-standby).
+Codex supports proxy and queue compatibility paths. Claude uses Monitor (or supported one-shot background Bash); ZCode and Kimi Code use background Bash completion notifications. Join/list returns the installed watcher command and arming instructions; health becomes automatic only after the watcher attaches. Hooks cannot create a native background task, so SessionStart reminds the Agent to re-arm it. Unknown MCP hosts remain manual. See [automatic standby](long-running-collaboration.md#automatic-standby).