fix: 补强 Windows rg 与 PowerShell 诊断

docs/reference/cli.md

@@ -12,6 +12,12 @@ UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式
 
 Windows `ps` 的参数语义分为两种：单个参数是完整 PowerShell source；多个参数是边界明确的 argv。后者对 native application 使用 Windows 命令行引用规则，必须保留 `python -c` 代码中的路径、`encoding="utf-8"`、字典 key 和嵌套引号，并继承 route 对应的 Windows workspace。PowerShell prelude 将 `Get-Content` 默认编码固定为 UTF-8；Windows fs helper 的 `head` / `tail` 同时支持 `-n N`、`-nN`、`--lines=N` 和 GNU `-N`，`wc -l` 必须把选项与路径分开解析。
 
+- Windows `rg` / PowerShell 本地边界：
+  - broad `rg` 超时必须先输出 `UNIDESK_WINDOWS_RG_SUMMARY ... timeout=true`，再输出 `UNIDESK_WINDOWS_RG_HINT code=timeout exitCode=124 action=narrow-scope-or-add-glob` 并返回 124；无匹配仍返回 1，二者不能混淆。
+  - 一行 PowerShell source 必须用本地单引号，例如 `trans G14-WSL:win/d/Work/demo ps '$p = Start-Process python -PassThru; $p.Id'` 和 `trans G14-WSL:win/d/Work/demo ps 'Get-Process | Where-Object { $_.CPU -gt 0 }'`。
+  - 多行 PowerShell 使用 `trans <route> ps <<'PS'`；quoted delimiter 保证 `$p`、`$_`、反斜杠和代码块不会被本地 shell 提前解释。
+  - 源码因本地展开而以缺失左值的 `=` 开始时，CLI 必须在远端执行前返回 `ssh-windows-powershell-local-expansion`、单引号示例和 quoted heredoc 示例。
+
 - Windows/WSL `apply-patch v2` 文本完整性合同：
   - localized replacement 必须保留纯 CRLF 文件的 CRLF 风格，不能把新增行写成 bare LF，也不能把整个文件静默改写为 LF。
   - original/final integrity mismatch 后必须重新只读采集当前文件，输出 adapter、stage、expected/current bytes、SHA-256、newline 和 encoding；摘要不得包含文件正文。