diff --git a/.agents/skills/unidesk-gh/SKILL.md b/.agents/skills/unidesk-gh/SKILL.md
index 077f5200..4d86c859 100644
--- a/.agents/skills/unidesk-gh/SKILL.md
+++ b/.agents/skills/unidesk-gh/SKILL.md
@@ -17,7 +17,11 @@ GitHub issue/PR 正式读写必须走 `bun scripts/cli.ts gh ...` 或 `trans gh:
 - `P0 SPEC 先行` 段不得写入硬编码阈值、采样周期、重试次数、并发数等可调参数；必须写明这些参数由指定 YAML/source-of-truth 控制，issue 只列配置路径、字段族和验收读取方式。
 - `gh` 默认输出是 k8s 风格 text/table/summary/Next/Disclosure；脚本消费或全量排障必须显式用 `--json`、`--full` 或 `--raw`。
 - `gh issue view` / `gh pr view` 显式请求 `--json body,...` 时，完整正文只在 `.data.issue.body` / `.data.pullRequest.body` 出现一次；兼容 `.data.json.body` 不再复制大字段，迁移路径由 `.data.compatibility.bodyPath` / `bodyMigrationHint` 披露。
-- 多行正文使用 quoted heredoc：`--body-stdin <<'EOF'`；issue close/reopen 生命周期评论只用 `--comment-stdin <<'EOF'`。不要把 Markdown 塞进 shell 参数。
+- 多行正文使用 quoted heredoc：
+  - 正文使用 `--body-stdin <<'EOF'`；issue close/reopen 生命周期评论只用 `--comment-stdin <<'EOF'`。
+  - 单次正文或 patch 必须直接从 heredoc 进入 stdin，禁止先写 `/tmp` 或工作区临时文件再用 `< file` 转交。
+  - 只有需要复用或正式保留的文件才使用 `--body-file`。
+  - 不要把 Markdown 塞进 shell 参数。
 - PR merge 只走 guarded `gh pr merge`；`gh pr create` 的 Next 默认是 `--merge --delete-branch`，只有确认 ancestry 可丢弃时才显式 `--squash`。
 
 ## 常用入口
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 37ad922d..ffab34eb 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -10,6 +10,12 @@ UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式
   - 默认输出或帮助输出触发 dump 视为 CLI 缺陷，必须收敛信息结构，禁止用提高 stdout 阈值掩盖。
   - dump 只允许用于用户显式请求的 `--full`、`--raw`、机器完整输出，或确实无法预先界定的一次性异常证据。
 
+- stdin 文本输入默认直接使用 quoted heredoc：
+  - 单次使用的正文、评论、prompt、patch、脚本或 JSON 必须直接写成 `--*-stdin <<'EOF'` 或等价 stdin heredoc。
+  - 禁止先把同一段文本写入 `/tmp` 或工作区临时文件，再用 `< file` 传给支持 stdin 的命令。
+  - 只有内容需要复用、作为正式工件保留、属于二进制，或目标工具明确只接受文件路径时，才使用 `--*-file`、upload 或文件重定向。
+  - heredoc delimiter 必须引用，避免 `$()`、反引号、变量和反斜杠被本地 shell 提前展开。
+
 主 server 必须在 PATH 上提供 `/root/.local/bin/trans` 可执行 wrapper，内容委托 repo 内版本化 `scripts/trans` 并执行 `bun scripts/ssh-cli.ts ssh "$@"`；交互 shell 可额外提供 alias，但非交互 Codex `exec` 和脚本不能依赖 alias 展开。
 
 主 server 固定提供 PATH 可见的 `/usr/local/bin/unidesk`，委托版本化 `scripts/unidesk` 执行根 CLI；`/root/.local/bin/unidesk` 可以保留为用户级兼容链接，但不能作为非交互入口的唯一安装位置。高频人工入口优先写 `unidesk <command>`；仓库内验证和未安装 wrapper 的 checkout 使用等价的 `bun scripts/cli.ts <command>`。