diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 87160591..9f36b396 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -113,7 +113,14 @@ GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ...
 
 `bun scripts/cli.ts ssh --help` 和 `bun scripts/cli.ts ssh <providerId> --help` 是本地 JSON 帮助命令，必须快速返回；不能把 `--help` 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。
 
-主 server 的交互式 bash 环境固定提供 `tran` alias，等价于 `bun /root/unidesk/scripts/cli.ts ssh`。日常分布式敏捷操作优先使用这个缩写减少重复前缀，例如 `tran D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch`、`tran D601:k3s kubectl get pods -n hwlab-dev` 或 `tran D601:k3s:hwlab-dev:hwlab-cloud-web/tmp pwd`。长期文档和可复制脚本仍可使用完整 `bun scripts/cli.ts ssh ...` 形式；alias 只作为本机交互效率入口，不作为远端 provider 或 CI/CD 的前置依赖。
+主 server 固定提供 `tran` 缩写，等价于 `bun /root/unidesk/scripts/cli.ts ssh`。这里必须同时保留两层入口：交互式 bash 用 `~/.bashrc` 里的 `alias tran='bun /root/unidesk/scripts/cli.ts ssh'`；Codex `exec`、脚本和其他非交互 shell 不会自动展开 alias，所以还必须有 `/root/.local/bin/tran` 可执行 wrapper，内容固定为：
+
+```sh
+#!/bin/sh
+exec bun /root/unidesk/scripts/cli.ts ssh "$@"
+```
+
+后续分布式敏捷操作优先直接写 `tran ...`，不要在 Codex 工具调用里退回完整 `bun scripts/cli.ts ssh ...` 前缀。例如 `tran D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch`、`tran D601:k3s kubectl get pods -n hwlab-dev` 或 `tran D601:k3s:hwlab-dev:hwlab-cloud-web/tmp pwd`。长期文档和可复制脚本仍可使用完整 `bun scripts/cli.ts ssh ...` 形式；`tran` 只作为本机交互效率入口，不作为远端 provider 或 CI/CD 的前置依赖。
 
 `bun scripts/cli.ts ssh D518` 应表现为登录 D518 WSL 的 shell；`bun scripts/cli.ts ssh D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `bun scripts/cli.ts ssh D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `bun scripts/cli.ts ssh D601 script <<'SCRIPT'`。