diff --git a/AGENTS.md b/AGENTS.md
index 9680ed8f..460c99ce 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
 - 架构和 M3 主线：[docs/reference/architecture.md](docs/reference/architecture.md)
 - DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
 - 部署正规化、镜像发布、回滚和 Cloud Web 路径：[docs/reference/deployment-publish.md](docs/reference/deployment-publish.md)
+- Code Agent chat readiness 与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
 - 指挥官协作、PR 和 runner handoff：[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
 - M3 闭环 rollout runbook：[docs/reference/m3-loop-rollout-runbook.md](docs/reference/m3-loop-rollout-runbook.md)
 - runner issue 可见性与 prompt handoff：[docs/reference/runner-issue-visibility-handoff.md](docs/reference/runner-issue-visibility-handoff.md)
diff --git a/docs/reference/README.md b/docs/reference/README.md
index 18396d89..f6f9d6a6 100644
--- a/docs/reference/README.md
+++ b/docs/reference/README.md
@@ -13,6 +13,7 @@
 | DEV 运行态、端口、k3s、DB DNS 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) |
 | 部署正规化、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) |
 | Cloud Workbench 默认界面和 UX 边界 | [cloud-workbench.md](cloud-workbench.md) |
+| Code Agent chat readiness 与真实回复判定 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
 | 指挥官/runner 协作、PR 和 prompt handoff | [commander-collaboration.md](commander-collaboration.md) |
 | M3 闭环 rollout runbook | [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md) |
 | runner GitHub 可见性与 prompt handoff | [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md) |
diff --git a/docs/reference/code-agent-chat-readiness.md b/docs/reference/code-agent-chat-readiness.md
new file mode 100644
index 00000000..f89807bf
--- /dev/null
+++ b/docs/reference/code-agent-chat-readiness.md
@@ -0,0 +1,85 @@
+# Code Agent Chat Readiness Runbook
+
+本文定义 Cloud Workbench `POST /v1/agent/chat` 的 readiness 判定。它只处理
+Code Agent 回复链路是否具备复测条件，不修复、不读取、不打印、不创建也不修改任何
+Secret 或 token。
+
+## 运行边界
+
+- DEV Cloud Web 入口是 `http://74.48.78.17:16666/`，同源代理到
+  `/v1/agent/chat`。
+- DEV API/edge 入口是 `http://74.48.78.17:16667/`；它不能替代 Workbench
+  同源聊天入口的真实回复证据。
+- `internal/cloud/code-agent-chat.mjs` 是 `/v1/agent/chat` 的后端处理入口。
+- `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness
+  gate。
+- `scripts/dev-cloud-workbench-smoke.mjs --static` 只验证 Workbench 源码合同和
+  `/v1/agent/chat` 前端接线；它不是 DEV-LIVE 回复证明。
+
+## Provider 前置条件
+
+当前 DEV 部署合同中 `hwlab-cloud-api` 的 Code Agent provider 使用 OpenAI
+provider，运行时通过 `OPENAI_API_KEY` 读取 provider 凭证。该环境变量应由授权路径把
+`hwlab-code-agent-provider/openai-api-key` 注入到 DEV runtime。
+
+Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入，
+`provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为
+`BLOCKED/credential`。
+
+## 判定标准
+
+| 观测结果 | readiness |
+| --- | --- |
+| `status: "failed"`，`error.code: "provider_unavailable"`，且 `error.missingEnv` 包含 `OPENAI_API_KEY` | `BLOCKED/credential`；provider 凭证缺失，不能标真实回复通过。 |
+| `status: "completed"`，但来自 mock、fixture、本地 stub、source-only smoke、浏览器本地回显或人工拼接 | 不是 DEV-LIVE reply pass。 |
+| 真实 DEV `POST /v1/agent/chat` 返回 `status: "completed"`，且 `reply.content` 是非空 assistant 回复 | 可标 DEV-LIVE reply pass。 |
+| 传输失败、schema 不完整、HTTP 非预期、`reply.content` 为空或缺失 | `BLOCKED`，按 runtime/schema/transport 分析。 |
+
+只有“真实 DEV 路由 + `completed` + 非空 assistant reply”能作为 DEV-LIVE 回复通过依据。
+不得把 mock、fixture、本地 echo、source report、静态检查或前端状态当作通过。
+
+## Smoke Gate
+
+本地合同检查：
+
+```sh
+node scripts/code-agent-chat-smoke.mjs
+```
+
+该命令验证 schema、`provider_unavailable` provider gap、`OPENAI_API_KEY`
+missing-env 分类，以及本地 stub completion 不能升级为 DEV-LIVE pass。
+
+Workbench 静态接线检查：
+
+```sh
+node scripts/dev-cloud-workbench-smoke.mjs --static
+```
+
+该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出
+`SOURCE` 级证据。
+
+授权凭证注入后的真实 DEV 复测：
+
+```sh
+node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:16666/
+```
+
+`--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含
+readiness、provider/model/backend、assistant 回复是否非空和长度、错误分类等摘要；不打印
+assistant 回复正文，不读取或打印任何 Secret 值。
+
+## 复测结果解释
+
+- 若输出 `readiness.level: "BLOCKED/credential"`，后续动作是由授权路径注入
+  `hwlab-code-agent-provider/openai-api-key`，不是由 runner 临时补 Secret。
+- 若输出 `readiness.level: "#143 DEV-LIVE reply pass"`，只说明真实回复链路通过；
+  它不自动证明 M3、M4、M5 或硬件闭环通过。
+- 若 `scripts/dev-cloud-workbench-smoke.mjs --static` 通过，而 `--live` 未通过，结论是
+  Workbench 接线和源合同通过，但真实 provider readiness 仍 blocked。
+
+## 稳定来源
+
+- [docs/reference/cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认页和同源边界。
+- [docs/reference/dev-runtime-boundary.md](dev-runtime-boundary.md)：DEV 端口、k3s 与运行态边界。
+- [docs/reference/architecture.md](architecture.md)：`SOURCE`、`LOCAL`、`DRY-RUN`、
+  `DEV-LIVE`、`BLOCKED` 证据分级。