EitanWong · EitanWong · Aug 4, 2026 · Aug 4, 2026 · Aug 4, 2026 · Aug 4, 2026
@@ -1,106 +1,71 @@
 # Remote Dev Skillkit
 
-让 AI Agent 安全地在你的 Mac、Windows、Linux 主机上做真实开发工作。
+[中文](README.zh-CN.md)
 
-**你遇到的场景**：Agent 有模型、有代码能力，但没有一台"能干活的主机"——或者你不想给 Agent 一把能碰所有东西的钥匙。Remote Dev Skillkit 是两者之间的受控通道：Agent 通过 MCP 提交**有边界、可审计、可中断**的任务，主机用**短期 join code** 加入会话、在本地策略内执行、回报事件与产物。
+**Remote control for AI agents.** Claude Code, Codex, Hermes, OpenCode — or any MCP-capable agent — operate your Mac, Windows, and Linux machines to get complex work done: coding, repair, ops, automation, anything that needs a real computer.
 
 ```text
-Agent (MCP client) ──rdev mcp serve──> Control Plane ──long-poll──> Host
-                                     (gateway)                (rdev host serve)
-                                        │
-                                        └── 每个动作：策略 + 审计 + 事件推送
+Agent (MCP client) ── rdev mcp serve ──> Control Plane ── long-poll ──> Host
+                                          (rdev gateway)             (rdev host serve)
 ```
 
-## 它解决什么
+## Why
 
-- **给 Agent 一台受控主机**：临时任务用 join code，长期任务用 Windows 服务（浏览器 handoff 一键安装），全部策略约束。
-- **不给 Agent 不受限访问**：无入站端口、无隐藏持久化、不绕过本地安全控制（UAC/TCC/Gatekeeper）。
-- **Agent 能感知进展**：事件推送（webhook）让 Agent 及时知道主机上线、任务完成、产物就绪，而不是轮询。
+Agents have models and reasoning — but no machine of their own, and you shouldn't hand them the keys to everything. Remote Dev Skillkit is the controlled remote-control layer between them.
 
-## 快速开始（按你的角色）
+- **Scoped sessions** — hosts join with short-lived join codes; every task is bounded by policy and capability ceilings.
+- **Audited & interruptible** — every action is recorded and can be interrupted or revoked at any time.
+- **Managed hosts** — Windows hosts install as a service via a browser handoff (copy-paste PowerShell), auto-reconnect, control-plane host updates.
+- **Event-driven** — agents get push events (webhooks) instead of polling for host status, task results, and artifacts.
+- **No exposure** — outbound-only connections, no inbound ports, no hidden persistence, no bypassing UAC, TCC, Gatekeeper, or Defender.
 
-### 🖥️ 我是开发者，想让 Agent 用我的电脑
+## Quick start
+
+**Host side** — let an agent use this machine:
 
 ```bash
-go install github.com/EitanWong/remote-dev-skillkit/cmd/rdev@latest   # Go 1.25+
+go install github.com/EitanWong/remote-dev-skillkit/cmd/rdev@latest
 rdev host serve --join-code CODE --gateway https://your-gateway
 ```
 
-- 一次性的临时支持：加 `--once`（打印连接状态后退出）。
-- 长期托管（Windows）：让操作员发你一个浏览器 handoff 链接，页面自动生成可复制 PowerShell，粘贴 → 可见确认 → 装成服务，之后开机自启、断线重连。
-
-### 🤖 我是 Agent（或运行 Agent 的人），想驱动远程主机
+**Agent side** — connect to hosts through the control plane:
 
 ```bash
-rdev mcp serve                                  # 本地控制平面
-rdev mcp serve --gateway-url URL --operator-token-file PATH   # 代理到远程 gateway
+rdev mcp serve --gateway-url URL --operator-token-file PATH
 ```
 
-然后把 `rdev mcp serve` 注册进你的 MCP 客户端（Claude Code / Codex / Hermes / OpenCode 均可）。工具自描述：每个工具都带 `safety` 说明和 `user_summary`/`agent_next_action` 引导，Agent 无需读文档即可正确使用。
+Register `rdev mcp serve` in your MCP client. Tools are self-describing with safety notes and agent guidance.
 
-### 🏗️ 我是网关操作者，想跑一个多主机控制面
+**Gateway operator** — run a multi-host control plane:
 
 ```bash
-rdev gateway serve --dev                                     # 本机试验
+rdev gateway serve --dev                                    # local trial
 rdev gateway serve --operator-auth-file ops.token --state-file state.json \
-    --signing-key-file key.pem --public-base-url https://gw.example \
-    --windows-amd64-host-binary rdev-host.exe               # 生产形态
+    --signing-key-file key.pem --public-base-url https://gw.example
 ```
 
-生产网关只监听 loopback，由你自己的 HTTPS 反向代理对外；operator 认证、持久化状态、签名密钥、审计全部显式配置。
-
-## 2 分钟最小演示（全本机）
-
-```bash
-# 终端 1：起本地 gateway
-rdev gateway serve --dev --addr 127.0.0.1:8788
-
-# 终端 2：Agent 视角——建会话、拿 join code（也可用 rdev mcp tools 查看完整 MCP）
-curl -X POST http://127.0.0.1:8788/v1/sessions -H 'Content-Type: application/json' \
-     -d '{"reason":"first demo"}'                    # 返回 session id + join code
-
-# 终端 3：主机视角——加入会话
-rdev host serve --join-code CODE --gateway http://127.0.0.1:8788 --once
-
-# 终端 2：看到 hello 事件，提交一个只读任务，收到结果事件
-```
-
-## 安装
-
-最快（一条命令，自动装 Go，无需管理员）：
+## Install
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/EitanWong/remote-dev-skillkit/main/scripts/install.sh | bash
 ```
 
-或手动（需要 Go 1.25+）：
-
-```bash
-go install github.com/EitanWong/remote-dev-skillkit/cmd/rdev@latest
-```
-
-Windows 目标主机无需手动下载：浏览器 handoff 会自动获取并校验主机二进制。
+Manual install requires Go 1.25+. Windows target hosts need no manual download — the browser handoff fetches and verifies the host binary.
 
-## 排障速查
+## Security model
 
-| 症状 | 原因与解法 |
-|---|---|
-| `bind: address already in use` | 端口被占用（如 Cloudflare 等常驻服务）。换端口：`--addr 127.0.0.1:8789` |
-| host join 一直失败 | gateway 不可达或 join code 过期。join code 短时有效，重新建会话再试 |
-| Agent 报 `403` | operator token 未配置/不匹配。确认 `--operator-token-file` 指向受保护文件 |
-| Windows 上没装成服务 | handoff 链接需在**目标 Windows 主机**的浏览器打开，且同意 UAC |
-| 收不到事件推送 | webhook 需 HTTPS（本机 Hermes 可用 loopback HTTP）；见 `rdev.sessions.notify` |
+- Outbound-only connections; no inbound public ports.
+- Policy-bound, scoped, auditable, interruptible tasks; temporary sessions are non-persistent by default.
+- Never bypasses local security controls (UAC, sudo, TCC, Gatekeeper, Windows Defender).
 
-## 安全边界
+## Documentation
 
-- 主机不暴露任何入站公网端口；所有连接由主机主动外连（long-poll）。
-- 每个任务都受策略约束、限定作用域、可审计、可中断；临时会话默认不持久。
-- 不绕过 UAC、sudo、TCC、Gatekeeper、Windows Defender 等本地安全控制。
+- Architecture: [SESSION_CONTROL_PLANE.md](docs/architecture/SESSION_CONTROL_PLANE.md)
+- Safety boundaries: [BOUNDARIES.md](docs/security/BOUNDARIES.md)
+- Quality matrix (live E2E status): [QUALITY_MATRIX.md](docs/development/QUALITY_MATRIX.md)
+- Host update runbook: [UPDATE_RUNBOOK.md](docs/operations/UPDATE_RUNBOOK.md)
+- Quality gate: `./scripts/check.sh`
 
-## 验证与文档
+## License
 
-- 质量门禁：`./scripts/check.sh`（gofmt、测试、vet、覆盖率门禁、surface 审计、release smoke）。
-- 架构：[SESSION_CONTROL_PLANE.md](docs/architecture/SESSION_CONTROL_PLANE.md)
-- 安全边界：[BOUNDARIES.md](docs/security/BOUNDARIES.md)
-- 质量矩阵（live E2E 状态）：[QUALITY_MATRIX.md](docs/development/QUALITY_MATRIX.md)
-- 贡献：[CONTRIBUTING.md](CONTRIBUTING.md)
+MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,71 @@
+# Remote Dev Skillkit
+
+[English](README.md)
+
+**给 AI Agent 用的远程电脑操控工具。** Claude Code、Codex、Hermes、OpenCode 或任意支持 MCP 的 Agent，可以操控你的 Mac、Windows、Linux 主机，帮你完成各种复杂任务 —— 写代码、修故障、跑运维、做自动化，凡是需要一台真实电脑的事。
+
+```text
+Agent (MCP client) ── rdev mcp serve ──> 控制面 ── long-poll ──> 主机
+                                          (rdev gateway)         (rdev host serve)
+```
+
+## 为什么
+
+Agent 有模型、有推理能力，但没有一台"能干活的主机"——你也不该给它一把能碰所有东西的钥匙。Remote Dev Skillkit 就是它们之间的受控远程操控层。
+
+- **有边界** —— 主机用短期 join code 加入会话，每个任务受策略与能力上限约束。
+- **可审计、可中断** —— 每个动作都有记录，随时可以中断或撤销。
+- **托管主机** —— Windows 主机通过浏览器 handoff（复制粘贴 PowerShell）装成服务，开机自启、断线重连、控制面远程升级。
+- **事件驱动** —— Agent 通过 webhook 收到推送（主机上线、任务完成、产物就绪），无需轮询。
+- **零暴露** —— 主机只外连，无入站端口、无隐藏持久化、不绕过 UAC / TCC / Gatekeeper / Defender。
+
+## 快速开始
+
+**主机侧** —— 让 Agent 用这台机器：
+
+```bash
+go install github.com/EitanWong/remote-dev-skillkit/cmd/rdev@latest
+rdev host serve --join-code CODE --gateway https://your-gateway
+```
+
+**Agent 侧** —— 通过控制面驱动远程主机：
+
+```bash
+rdev mcp serve --gateway-url URL --operator-token-file PATH
+```
+
+把 `rdev mcp serve` 注册进你的 MCP 客户端即可。工具自带安全说明与 Agent 引导，无需读文档。
+
+**网关运维** —— 跑一个多主机控制面：
+
+```bash
+rdev gateway serve --dev                                    # 本机试验
+rdev gateway serve --operator-auth-file ops.token --state-file state.json \
+    --signing-key-file key.pem --public-base-url https://gw.example
+```
+
+## 安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/EitanWong/remote-dev-skillkit/main/scripts/install.sh | bash
+```
+
+手动安装需 Go 1.25+。Windows 目标主机无需手动下载 —— 浏览器 handoff 会自动获取并校验主机二进制。
+
+## 安全模型
+
+- 仅出站连接，无入站公网端口。
+- 任务受策略约束、限定作用域、可审计、可中断；临时会话默认不持久。
+- 绝不绕过本地安全控制（UAC、sudo、TCC、Gatekeeper、Windows Defender）。
+
+## 文档
+
+- 架构：[SESSION_CONTROL_PLANE.md](docs/architecture/SESSION_CONTROL_PLANE.md)
+- 安全边界：[BOUNDARIES.md](docs/security/BOUNDARIES.md)
+- 质量矩阵（live E2E 状态）：[QUALITY_MATRIX.md](docs/development/QUALITY_MATRIX.md)
+- 主机更新手册：[UPDATE_RUNBOOK.md](docs/operations/UPDATE_RUNBOOK.md)
+- 质量门禁：`./scripts/check.sh`
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)。
@@ -26,18 +26,18 @@ Status: ✅ covered · 🟡 partial · ❌ gap · ⚙️ live-only (real host/sy
 | `internal/update` | version compare (pre-release, v-prefix, malformed, empty), URL building (trailing slash, escaping, bad repo), HTTP non-200 / bad JSON / unreachable, token header, asset selection (dash vs underscore slug, case, no match), digest presence, shell quoting of adversarial names, plan when no update | ✅ 98% |
 | `internal/operatorauth` | file load errors (missing/bad JSON/wrong schema), JWKS fetch failure at load, claim types (aud string/array/mixed/nil, exp float64/int64/Number/garbage), roles claim forms (`[]any`/`[]string`/space-separated string/non-string), hash validation (prefix/length/hex), clock skew boundaries (OIDC exp/nbf at skew edge; hosted exp/nbf strict), wrong audience/issuer, expired/nbf token, duplicate key IDs, SAML response corners (expired assertion, wrong recipient, bad signature, empty response) | ✅ 78.0% |
 | `internal/hosttrust` | noop store, file missing/corrupt/wrong schema, atomic write + 0600, rollback rejection, same-sequence content tamper, signature from stored root (not caller-supplied), protected-store backends (keychain/DPAPI/libsecret), malformed protected ref | ✅ 78.8% |
-| `internal/httpapi` | session create/join/close/revoke, event replay after cursor, long-poll wait parsing, artifact write authorization (operator path + endpoint lease + task ownership), task resume (operator role, checkpoint/idempotency validation, unknown task), persist-state failure (failing StateStore → 500) | ✅ 71.0% — artifact auth (#19), join/resume, persist-failure covered; `persistStateNoResponse` removed as dead code |
+| `internal/httpapi` | session create/join/close/revoke, event replay after cursor, long-poll wait parsing, artifact write authorization (operator path + endpoint lease + task ownership), task resume (operator role, checkpoint/idempotency validation, unknown task), persist-state failure (failing StateStore → 500), session-scoped host-update artifact route (lease auth, digest header, audit) | ✅ 71.0% — artifact auth (#19), join/resume, persist-failure covered; `persistStateNoResponse` removed as dead code |
 | `internal/protectedstore` | ref parsing (URL-like, missing account, unknown prefix), backend fallthrough, per-platform backends (keychain/DPAPI/libsecret/keyctl/TPM/MDM), empty service/account, backend error propagation | 🟡 36.8% — platform backends are ⚙️ live-only (real keyring/TPM) or need mock seam; parse/open/store logic ✅ |
 | `internal/policy` | capability checks, shell allow/deny, scoping, unknown capability handling | 🟡 73.2% |
 | `internal/audit` | chain integrity, JSONL append, redaction of secrets, tamper detection | ✅ 76.5% |
 | `internal/model` | trust bundle validity windows, key status transitions, hash consistency | ✅ 71.7% |
-| `internal/contracts` | tool schema round-trip, required fields, enum constraints, MCP surface parity with `mcp/tools.json` | ✅ 77.6% |
+| `internal/contracts` | tool schema round-trip, required fields, enum constraints, MCP surface parity with `mcp/tools.json`, adapter profiles document `workspace_root_required` + complete payload examples (incl. Windows `powershell_command` allowlist contract) | ✅ 77.6% |
 | `internal/hostidentity` | key generation, fingerprint, validation of malformed keys | 🟡 69.0% |
 | `internal/workspace` | worktree create/cleanup/rollback, lock contention, write-scope enforcement (absolute/`..`/drive-letter paths, escaping symlinks, scope membership), snapshot diffing (change detection, truncation at 200 files, .git exclusion, escaping scopes), dirty policy | ✅ 71.7% |
 | `internal/toolchain` + `internal/depsinstall` | node/toolchain bootstrap, idempotency, failure mid-install, archive security (zip-slip, escaping symlinks, byte limits, HTTPS-only sources + same-host redirects, SHA-256 verify), retry classification and retry loops, atomic copy | ✅ 67–69% — network fetch paths covered with httptest |
-| `internal/hostcmd` | managed service start/stop/retry, route pool concurrency, exit codes | ✅ 75.7% |
+| `internal/hostcmd` | managed service start/stop/retry, route pool concurrency, exit codes, service update (staged release verify, SCM switch, health window, auto-rollback, result marker), host version/commit join reporting | ✅ 75.7% |
 | `internal/gateway` + `internal/controlplane` | session state machine, lease binding, reconnect, revocation, persistence, snapshot/event sequencing | ✅ 80–81% |
-| `internal/hostrunner` | engineering loop, progress, limits (duration/output/attempts), isolation, runtime profiles | ✅ 81.2% |
+| `internal/hostrunner` | engineering loop, progress, limits (duration/output/attempts), isolation, runtime profiles, preflight denials carry agent-actionable `hint` (workspace/capability/allowlist classes), host-update adapter (lease-authed download, digest verify, idempotency, detached updater, workspace exemption) | ✅ 81.2% |
 | `internal/shelladapter` + `internal/powershelladapter` | process groups, redaction, output caps, verification commands | ✅ 68–78% |
 | `internal/hostawake` | wake on LAN / platform wake, error fallback | ⚙️ 15.8% — live-only |
 | `internal/acceptance` | managed Mac/Windows verification reports, session evidence | ⚙️ 7.3% — live E2E harness, exercised on real hosts |