diff --git a/AGENTS.md b/AGENTS.md
index d9fa0833..53b77ed7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,6 +34,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 ## Critical Remote Patch Transport Rule
 
 - P0: 对 G14/D601/远端 worktree 做文本源码修改时，必须优先使用 UniDesk SSH workspace route 的 `apply-patch` 透传入口；不要优先用远端 Python/Perl/sed heredoc 或复杂 shell quoting 拼接大段文本补丁。
+- P0: 对 k3s pod 内文本热修必须把第一个 route token 直接定位到目标 pod/workspace 后再执行 `apply-patch`；禁止从 host/worktree 取 diff、改路径、再管道拼到 pod，反面案例和正确写法见 `docs/reference/cli.md`。
 - P0: 只有在 `apply-patch` 本身不可用或需要处理非文本/批量机械生成文件时，才使用其他受控方式；使用前必须说明原因，并在修改后立即用 `git diff`、语法检查或文件尾部检查确认没有截断或污染。
 - P0: `apply-patch` 一旦出现误删、尾部截断、匹配漂移或其他正确性问题，必须立即优先修复 UniDesk `apply-patch` 本身；算法必须按 Codex 开源 `apply_patch` 源码语义做 1:1 对齐，不能用局部护栏、兼容绕行、分支开关或改用其他 patch 入口掩盖基础链路缺陷。
 - P0: Codex 开源 `apply_patch` 参考源码已固定缓存到 `/tmp/codex-apply-patch/codex/codex-rs/apply-patch/`，core 侧相关文件和 commit 记录在 `/tmp/codex-apply-patch/`；排查或对齐 `apply-patch` 算法时必须先读该本地缓存，只有缓存缺失或明确需要更新时才重新联网拉取。
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 41a6ef9c..ebb143a4 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -169,6 +169,21 @@ ssh-like 远端命令如果出现 `kex_exchange_identification`、`Connection cl
 
 如果只是远端打文本补丁，不需要再手写 `ssh D601 'apply_patch' < patch.diff` 这种命令拼接；正式默认入口是 `bun scripts/cli.ts ssh D601:/absolute/workspace apply-patch < patch.diff`、`bun scripts/cli.ts ssh D601:k3s:<namespace>:<workload>/<workspace> apply-patch < patch.diff` 或 `bun scripts/cli.ts ssh D601:win/c/test apply-patch < patch.diff`。旧 helper 只有 `apply-patch-v1` 一个入口，附加参数会原样透传给远端 `apply_patch`，例如 `bun scripts/cli.ts ssh D601 apply-patch-v1 --help` 或 `bun scripts/cli.ts ssh D601 apply-patch-v1 --allow-loose < reviewed.patch`。标准单命令用法如下，不需要先创建本地 patch 临时文件：
 
+pod 内文本热修的反面案例是：先在 host/source worktree 生成 `git diff`，再用本地 `sed` 改路径、拼 `*** Begin Patch` 包头，最后管道到 `G14:k3s:<namespace>:<pod>`。这种做法把 source workspace、local shell、远端 shell 和 pod workspace 四层混在一起，容易出现 patch 格式错误、路径漂移、部分成功后误判、以及“看起来在热修 pod，实际主要在搬运 host diff”的错误行为。正确做法是把第一个 route token 直接定位到目标 pod 和 pod 内 workspace，然后在同一条 route 上写标准 Codex patch：
+
+```bash
+bun scripts/cli.ts ssh G14:k3s:hwlab-dev:pod:hwlab-cloud-web-abc/app/web/hwlab-cloud-web apply-patch <<'PATCH'
+*** Begin Patch
+*** Update File: app.mjs
+@@
+-const value = "old";
++const value = "new";
+*** End Patch
+PATCH
+```
+
+如果运行面实际加载 `dist/` 产物，同样直接定位到 `.../app/web/hwlab-cloud-web/dist apply-patch` 再改 `app.mjs`，不要从源码 worktree 生成 diff 后改路径上传。热修后立即用同一个 pod route 做 `grep`/`sha256sum`/语法检查或浏览器 smoke 确认落点；若热修内容已经等同于上传一份较大源码，优先停止热修，改走 PR/CI/CD。
+
 ```bash
 bun scripts/cli.ts ssh D601:/home/ubuntu/pipeline apply-patch <<'PATCH'
 *** Begin Patch