diff --git a/.agents/skills/unidesk-trans/SKILL.md b/.agents/skills/unidesk-trans/SKILL.md
index 800e3117..c2b9a43f 100644
--- a/.agents/skills/unidesk-trans/SKILL.md
+++ b/.agents/skills/unidesk-trans/SKILL.md
@@ -32,8 +32,9 @@ Host workspace、k3s、Windows、GitHub issue/PR route 见 [references/routes.md
 ## P0 边界
 
 - `trans --help` 是高频直接阅读入口：
-  - 顶层只展示 route 语法、operation 分组和 `trans --help <operation>` 下钻索引。
+  - 顶层默认使用紧凑文本，只展示 route 语法、operation 分组和 `trans --help <operation>` 下钻索引；JSON 必须由显式机器输出参数请求。
   - 顶层与 scoped help 都必须有界且直接返回；出现 `outputTruncated` 或 dump 即视为 CLI 缺陷。
+  - 未知 help scope 和可预测参数错误必须紧凑、无 stack；只有显式 debug/raw 错误模式可以披露 stack，内部异常不得冒充输入错误。
   - 修复帮助过长时必须收敛信息结构，禁止提高 stdout 阈值。
   - dump 只允许用于显式 `--full`、`--raw` 或确实无法预先界定的一次性异常证据。
 - 远端文本修改优先 `trans <route> apply-patch`；不要 download/upload/sed 拼临时 diff 代替 patch。
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 902e2a8b..0c321ce9 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -4,7 +4,9 @@ UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式
 
 - 高频 CLI 默认输出与帮助输出是直接阅读入口：
   - 必须保持有界、低噪声并直接展示，不得触发 `outputTruncated` 或 `/tmp/unidesk-cli-output` dump。
+  - 面向人工的高频 `--help` 必须默认输出紧凑文本；机器 JSON 只能由显式 `--json`、`-o json` 或等价参数请求，不能把 JSON envelope 当作帮助页直接倾倒。
   - 顶层帮助只展示分组索引和可执行的下钻命令，详细合同通过 `<command> --help <operation>` 或等价 scoped help 获取。
+  - 未知子命令、未知 help scope 和可预测 option 校验失败必须返回紧凑、结构化且无 stack 的输入错误；stack 只允许在显式 debug/raw 错误模式下披露，内部异常不得伪装成输入错误。
   - 默认输出或帮助输出触发 dump 视为 CLI 缺陷，必须收敛信息结构，禁止用提高 stdout 阈值掩盖。
   - dump 只允许用于用户显式请求的 `--full`、`--raw`、机器完整输出，或确实无法预先界定的一次性异常证据。