@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/repoctl/doctor.md

@@ -1,86 +1,46 @@
 ---
-description: 说明 repoctl doctor 的检查项、状态含义、strict 模式和修复建议。
+outline: deep
 ---
 
-# repoctl doctor 诊断
+# repoctl Doctor
 
-`repo doctor` 用来判断当前目录是不是一个可维护、可开发、可接入 repoctl 工作流的 pnpm monorepo 根目录。
+`repo doctor` diagnoses whether the current pnpm workspace is ready for development and release. It does not rewrite files.
 
-## 1. 状态含义
+## Statuses
 
-| 状态   | 含义           | 对退出码的影响                |
-| ------ | -------------- | ----------------------------- |
-| `pass` | 检查通过       | 不影响                        |
-| `warn` | 存在建议修复项 | 默认不失败，`--strict` 下失败 |
-| `fail` | 阻塞项         | 命令返回失败状态              |
+- `pass`: the check is satisfied.
+- `warn`: the repository works, but maintenance or consistency needs attention.
+- `fail`: a required workspace contract is missing or invalid.
 
-CI 中推荐使用：
+## Checks
 
-```bash
-repo doctor --strict
-```
+Doctor covers the root `package.json`, `pnpm-workspace.yaml`, Node compatibility, the `repoctl` dependency, recommended `repo:*` scripts, `repoctl.config.ts`, commit hooks, workspace pattern coverage, tooling imports, and release configuration.
 
-这样 warning 不会长期堆积成隐性风险。
+Check IDs and JSON fields remain stable in every locale.
 
-## 2. 核心检查项
-
-| 检查项                       | 通过标准                                                         | 常见修复                     |
-| ---------------------------- | ---------------------------------------------------------------- | ---------------------------- |
-| `package-json`               | 当前 workspace 根目录存在 `package.json`                         | 回到仓库根目录或先初始化项目 |
-| `workspace-manifest`         | 存在 `pnpm-workspace.yaml`                                       | `repo init --yes`            |
-| `node-version`               | 当前 Node 满足 `engines.node`                                    | 切换 Node 版本或补充 engines |
-| `tool-package`               | 根依赖包含 `repoctl`                                             | `pnpm add -D repoctl`        |
-| `root-scripts`               | 存在 `repo:init`、`repo:new`、`repo:check`、`repo:doctor` 根脚本 | `repo init --yes`            |
-| `config-file`                | 使用 `repoctl.config.ts`，且没有残留 `monorepo.config.ts`        | 保留 `repoctl.config.ts`     |
-| `commit-hooks`               | Husky 和 lint-staged 同时就绪                                    | `repo upgrade --yes`         |
-| `tooling-imports`            | 配置不再引用本地源码 loader 或旧 config wrapper                  | `repo upgrade --yes`         |
-| `workspace-patterns`         | 常见目录被 workspace patterns 覆盖                               | `repo init --yes`            |
-| `workspace-package-coverage` | 常见目录下的包都被 pnpm 覆盖                                     | `repo init --yes`            |
-
-## 3. 输出报告
+## Reports
 
 ```bash
-repo doctor
 repo doctor --json
-repo doctor --markdown --redact
-repo doctor --json --out reports/doctor.json
+repo doctor --markdown
 repo doctor --markdown --redact --out reports/doctor.md
 ```
 
-自动化脚本推荐使用 `pnpm run repo:doctor -- --json` 或 `pnpm exec repo doctor --json`。
-
-| 输出         | 适合场景                    |
-| ------------ | --------------------------- |
-| 默认交互文本 | 本地直接阅读                |
-| JSON         | CI、编辑器、脚本消费        |
-| Markdown     | 粘贴到 issue、PR 或排障文档 |
-| `--redact`   | 分享报告前隐藏本机绝对路径  |
+`--redact` replaces workspace, current-directory, and home paths before output is shared.
 
-## 4. strict 模式
-
-`--strict` 会把 warning 也视为失败。它适合放在 CI 早期阶段：
+## Strict Mode
 
 ```bash
-pnpm install --frozen-lockfile
 repo doctor --strict
-repo check --full
 ```
 
-如果你正在接入存量仓库，建议先不用 strict，把报告保存下来逐项修复：
+Normal mode exits non-zero for failures. Strict mode also treats warnings as blocking, which is useful for CI policy enforcement.
+
+## Language
 
 ```bash
-repo doctor --markdown --redact --out reports/doctor.md
-repo upgrade --no-overwrite
-repo doctor
+repo --lang zh-CN doctor
+REPOCTL_LANG=zh-CN repo doctor
 ```
 
-## 5. 排查顺序
-
-建议按阻塞程度处理：
-
-1. 先处理 `fail`，否则命令或 CI 很可能无法继续。
-2. 再处理遗留配置和 Node 版本问题。
-3. 然后补根脚本、hook 和 lint-staged。
-4. 最后整理 workspace patterns 与 tooling imports。
-
-如果不确定报告能否安全分享，使用 [报告与自动化输出](./reports.md) 里的 `--redact` 和 `env support`。
+The explicit option wins over `REPOCTL_LANG`; English is the fixed fallback.

package/templates/vitepress/repoctl/execution-model.md

@@ -1,81 +1,28 @@
 ---
-description: 说明 repoctl CLI 的入口层级、命令懒加载、非交互输出和脚本集成方式。
+outline: deep
 ---
 
-# repoctl 执行模型
+# repoctl Execution Model
 
-repoctl 的核心设计是把日常入口保持短，把细粒度能力放到分组命令里，并让 CI、编辑器和脚本可以读取结构化输出。
+repoctl is a task layer over pnpm, Turborepo, repository scripts, and managed assets. It coordinates those systems without replacing them.
 
-## 1. 入口层级
+## Entrypoints
 
-| 层级        | 示例                                                               | 使用场景                       |
-| ----------- | ------------------------------------------------------------------ | ------------------------------ |
-| 根脚本      | `pnpm run repo:doctor`、`pnpm run repo:new`、`pnpm run repo:check` | 团队日常开发、README、贡献指南 |
-| `repo` 命令 | `pnpm exec repo doctor`                                            | 文档、CI、脚本、排障           |
-| 分组命令    | `repo env support`、`repo verify pre-push`                         | 维护者、自动化和集成工具       |
+The recommended binary is `repo`. `repoctl` is an equivalent public bin. Generated workspaces also expose `repo:init`, `repo:new`, `repo:doctor`, and `repo:check` root scripts.
 
-## 2. 命令执行过程
+## Command Lifecycle
 
-repoctl 启动时只注册命令树。具体实现会在 action 执行时再加载，因此查看帮助和列出命令不会提前扫描所有 workspace、Git 状态和模板文件。
+1. Resolve locale from `--lang`, then `REPOCTL_LANG`, then English.
+2. Find the pnpm workspace root and load `repoctl.config.ts` when present.
+3. Build a deterministic plan from workspace state and command options.
+4. Prompt only when the terminal is interactive and the command needs a choice.
+5. Execute the plan or emit text, Markdown, or JSON output.
+6. Set a non-zero exit code for blocking diagnostics or command failures.
 
-```txt
-repo --help
-  -> 注册命令树
-  -> 输出帮助
+## Output Contracts
 
-repo doctor
-  -> 注册命令树
-  -> 加载 doctor 实现
-  -> 发现 workspace
-  -> 输出诊断报告
-```
+Text and Markdown are localized. JSON keys, status values, check IDs, command names, and option names are stable across locales.
 
-这种模型适合命令数量较多的 monorepo 工具：日常命令保持快，重逻辑只在真正执行时进入。
+## Configuration
 
-## 3. 输出模式
-
-很多 repoctl 命令都同时服务人和机器：
-
-| 参数           | 行为                             | 典型用途                 |
-| -------------- | -------------------------------- | ------------------------ |
-| `--json`       | 输出结构化 JSON                  | CI、编辑器、脚本         |
-| `--markdown`   | 输出 Markdown 报告               | issue、PR、协作文档      |
-| `--out <file>` | 写入文件                         | 保存 artifact 或生成计划 |
-| `--redact`     | 脱敏 cwd、workspace、home 等路径 | 分享本机报告             |
-| `--dry-run`    | 只生成计划，不写入业务文件       | 审查创建和校验动作       |
-
-`--json`、`--markdown`、`--out` 在 `repo check` 和 `repo new` 这类命令里会隐含预览语义，避免自动化读取计划时意外执行写入。
-
-## 4. 失败状态
-
-repoctl 的失败状态遵循阻塞优先：
-
-| 命令                     | 什么时候失败                                          |
-| ------------------------ | ----------------------------------------------------- |
-| `repo doctor`            | 存在 `fail` 检查项；加 `--strict` 时 warning 也会失败 |
-| `repo templates --check` | 模板健康检查出现 fail                                 |
-| `repo new`               | 模板不存在、目标校验失败或写入失败                    |
-| `repo check --full`      | 任一 root script 校验失败                             |
-| `repo verify *`          | 对应 hook 或校验命令失败                              |
-
-如果只是想知道会发生什么，先加 `--dry-run` 或输出计划：
-
-```bash
-repo new docs --template vitepress --json --out plans/docs.json
-repo check --markdown --out reports/check-plan.md
-```
-
-## 5. 和配置文件的关系
-
-repoctl 会从 workspace 根目录加载 `repoctl.config.*`。`monorepo.config.*` 已不再加载。
-
-配置加载后会影响具体命令，例如：
-
-| 配置区域           | 影响命令                                                            |
-| ------------------ | ------------------------------------------------------------------- |
-| `commands.init`    | `repo init`                                                         |
-| `commands.create`  | `repo new`                                                          |
-| `commands.upgrade` | `repo upgrade`                                                      |
-| `tooling`          | `repoctl/tooling` wrapper 生成的 ESLint、Vitest、lint-staged 等配置 |
-
-更多配置示例见：[配置文件](./config.md)。
+Configuration supplies repository defaults. Explicit CLI options take precedence. Non-interactive automation should use `--yes`, explicit template keys, and report output options instead of relying on prompts.

package/templates/vitepress/repoctl/getting-started.md

@@ -1,12 +1,12 @@
-# 快速开始
+# Getting Started
 
-这一页按“把 repoctl 接进一个仓库”的顺序写。你不需要先理解所有工具，先让仓库能被诊断、能创建包、能跑提交前校验。
+This guide follows the order you would use when adding repoctl to a workspace.
 
-## 准备环境
+## Prerequisites
 
-- Node.js 20 或更高版本。
-- pnpm。推荐通过 Corepack 启用：`corepack enable`。
-- Git。`repo doctor` 会读取仓库信息，用来补全 package metadata 和诊断提交链路。
+- Node.js 20 or newer.
+- pnpm. Corepack is recommended: `corepack enable`.
+- Git. `repo doctor` reads repository metadata and checks the commit workflow.
 
 ```bash
 node -v
@@ -14,15 +14,15 @@ pnpm -v
 git --version
 ```
 
-## 安装 repoctl
+## Install
 
 ```bash
 pnpm add -D repoctl
 ```
 
-如果你使用的是这套模板生成的新仓库，依赖和根脚本通常已经准备好了，可以直接从 `pnpm install` 开始。
+If the repository was generated from this template, the dependency and root scripts may already be present.
 
-## 初始化仓库默认值
+## Initialize Defaults
 
 ```bash
 pnpm install
@@ -30,42 +30,40 @@ pnpm exec repo init
 pnpm exec repo doctor
 ```
 
-这三步分别解决：
+| Command        | Purpose                                                                       |
+| -------------- | ----------------------------------------------------------------------------- |
+| `pnpm install` | Install workspace dependencies and local links                                |
+| `repo init`    | Add recommended scripts, workspace patterns, and tooling entries              |
+| `repo doctor`  | Check root files, Node version, CLI dependency, stale config files, and hooks |
 
-| 命令           | 作用                                                |
-| -------------- | --------------------------------------------------- |
-| `pnpm install` | 安装 workspace 依赖并创建本地链接                   |
-| `repo init`    | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
-| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、遗留配置和提交链路 |
+Fix blocking issues reported by `doctor`, then run it again.
 
-如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm exec repo doctor`。
+## Create A Package
 
-## 创建第一个包
-
-先看模板列表：
+List templates first:
 
 ```bash
 pnpm exec repo templates
 ```
 
-创建一个 TypeScript 库：
+Create a TypeScript library:
 
 ```bash
 pnpm exec repo new sdk --template tsdown
 ```
 
-创建前只想预览：
+Preview before writing files:
 
 ```bash
 pnpm exec repo new sdk --template tsdown --dry-run
 pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
 ```
 
-`--json` 和 `--out` 会隐含 `--dry-run`，适合 CI、编辑器和脚本读取创建计划。
+`--json` and `--out` imply `--dry-run`, which makes them suitable for CI, editor integrations, and scripts.
 
-## 使用根脚本
+## Use Root Scripts
 
-如果仓库已经通过 `repo init` 或模板生成补齐了根脚本，日常可以写得更短：
+After `repo init`, daily commands can be shorter:
 
 ```bash
 pnpm run repo:init
@@ -74,16 +72,14 @@ pnpm run repo:new -- sdk --template tsdown
 pnpm run repo:check
 ```
 
-对应关系：
-
-| 根脚本                         | 等价命令                     |
+| Root script                    | Equivalent CLI               |
 | ------------------------------ | ---------------------------- |
 | `pnpm run repo:init`           | `pnpm exec repo init`        |
 | `pnpm run repo:doctor -- args` | `pnpm exec repo doctor args` |
 | `pnpm run repo:new -- args`    | `pnpm exec repo new args`    |
 | `pnpm run repo:check`          | `pnpm exec repo check`       |
 
-## 提交前检查
+## Verify Before Committing
 
 ```bash
 pnpm build
@@ -92,7 +88,7 @@ pnpm typecheck
 pnpm test
 ```
 
-如果只想走 repoctl 推荐的本地检查入口：
+Or use the repoctl verification entry:
 
 ```bash
 pnpm run repo:check
@@ -100,9 +96,7 @@ pnpm exec repo check --dry-run
 pnpm exec repo check --json --out reports/check-plan.json
 ```
 
-## 同步模板标准资产
-
-当模板升级后，用 `upgrade` 同步新的默认配置和脚本：
+## Sync Template Assets
 
 ```bash
 pnpm exec repo upgrade
@@ -110,13 +104,13 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo upgrade --yes
 ```
 
-- `--no-overwrite`：保留已有 drifted 文件。
-- `--yes` / `--overwrite`：适合明确要覆盖标准资产的自动化场景。
-- 非 TTY 环境不会弹出交互提示。
+- `--no-overwrite` preserves changed managed files.
+- `--yes` or `--overwrite` is for explicit automated overwrites.
+- Non-TTY environments do not open interactive prompts.
 
-## 常见下一步
+## Next Steps
 
-- 已有仓库渐进接入：阅读 [接入已有仓库](./adopt-existing.md)。
-- 想固定默认模板：阅读 [配置文件](./config.md)。
-- 想查看所有模板：阅读 [模板与创建](./templates.md)。
-- 想把诊断结果发给同事：阅读 [排障与报告](./troubleshooting.md)。
+- Adopt an existing repository: [Adopt Existing Repositories](./adopt-existing.md).
+- Set team defaults: [Configuration](./config.md).
+- Inspect template keys: [Templates](./templates.md).
+- Share diagnostic output: [Troubleshooting](./troubleshooting.md).

package/templates/vitepress/repoctl/index.md

@@ -1,23 +1,23 @@
-# repoctl 概览
+# repoctl Overview
 
-`repoctl` 是这套模板推荐给使用者的包名。默认命令是 `repo`，目标是把 pnpm workspace、Turborepo、模板创建、诊断报告和提交前校验收敛到一组稳定入口里。
+`repoctl` is the user-facing package name for this monorepo toolkit. Its recommended command is `repo`.
 
-它不替代 pnpm、Turbo 或 pnpm versioning，而是把这些工具在 monorepo 里的常见动作串起来。
+The CLI does not replace pnpm, Turborepo, or pnpm versioning. It gives teams a stable layer for common monorepo actions: setup, diagnostics, scaffolding, local verification, and template asset upgrades.
 
-## 什么时候使用 repoctl
+## When To Use It
 
-| 场景                                     | 推荐入口                 |
-| ---------------------------------------- | ------------------------ |
-| 给已有 pnpm workspace 补齐标准脚本和配置 | `pnpm exec repo init`    |
-| 判断当前仓库是不是能顺利开发             | `pnpm exec repo doctor`  |
-| 创建新的包、应用、文档站或 CLI           | `pnpm exec repo new`     |
-| 提交前复现推荐校验链路                   | `pnpm exec repo check`   |
-| 同步模板最新标准资产                     | `pnpm exec repo upgrade` |
-| 给 CI、编辑器或脚本读取结构化结果        | `--json --out <file>`    |
+| Goal                                                  | Command                  |
+| ----------------------------------------------------- | ------------------------ |
+| Add recommended scripts and workspace defaults        | `pnpm exec repo init`    |
+| Check whether a repository is ready to develop        | `pnpm exec repo doctor`  |
+| Create a package, app, docs site, service, or CLI     | `pnpm exec repo new`     |
+| Reproduce the recommended pre-commit or pre-push flow | `pnpm exec repo check`   |
+| Sync newer standard assets from the template          | `pnpm exec repo upgrade` |
+| Persist output for CI, editors, or issue reports      | `--json --out <file>`    |
 
-## 推荐命令层级
+## Recommended Command Layers
 
-### 1. 生成仓库里的 repo:\* 根脚本
+### repo:\* Root Scripts
 
 ```bash
 pnpm run repo:init
@@ -26,9 +26,9 @@ pnpm run repo:new
 pnpm run repo:check
 ```
 
-这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名，也不会和 pnpm 内置命令冲突。
+These are the best commands for day-to-day team docs. They are short, explicit, and do not collide with pnpm built-in commands.
 
-### 2. 明确调用 repo CLI
+### Explicit CLI Calls
 
 ```bash
 pnpm exec repo init
@@ -38,9 +38,9 @@ pnpm exec repo new sdk --template tsdown
 pnpm exec repo check --dry-run
 ```
 
-这是文档、CI、脚本和排障里最清楚的写法。
+Use this form in CI, scripts, troubleshooting docs, and reproducible examples.
 
-### 3. 分组命令
+### Grouped Commands
 
 ```bash
 pnpm exec repo ws ls
@@ -49,54 +49,26 @@ pnpm exec repo env support --markdown --redact
 pnpm exec repo config inspect
 ```
 
-这些入口适合已经熟悉 repoctl 的维护者，用来做更细的 workspace、tooling、环境和配置操作。
+Grouped commands are for maintainers and automation that need finer control.
 
-## repoctl 管什么
+## Command Entrypoints
 
-repoctl 把 monorepo 里最容易分散的动作收敛为五条主线：
-
-| 主线   | 代表命令                      | 解决的问题                                                |
-| ------ | ----------------------------- | --------------------------------------------------------- |
-| 初始化 | `repo init` / `repo upgrade`  | 生成或同步 workspace、根脚本、Husky、lint-staged 等资产   |
-| 诊断   | `repo doctor`                 | 判断仓库根目录、运行时、脚本、配置和提交链路是否就绪      |
-| 创建   | `repo templates` / `repo new` | 使用内置模板生成库、应用、服务、文档站和 CLI              |
-| 校验   | `repo check` / `repo verify`  | 统一 pre-commit、staged typecheck、pre-push 和 commit-msg |
-| 报告   | `repo env support`            | 输出可保存、可脱敏、可给 CI 和协作者读取的上下文          |
-
-这几条主线都支持非交互参数。需要自动化时，优先使用 `--json`、`--markdown`、`--out <file>`、`--redact` 和 `--dry-run` 组合。
-
-## 新人和维护者的边界
-
-| 角色       | 推荐只记住                                                         | 需要深入时再看                                              |
-| ---------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
-| 新成员     | `pnpm run repo:doctor`、`pnpm run repo:new`、`pnpm run repo:check` | [按场景选命令](./scenarios.md)                              |
-| 包维护者   | `repo templates`、`repo new --template`、`repo check --full`       | [模板资产治理](./template-assets.md)                        |
-| CI 维护者  | `repo doctor --strict`、`repo check --full`、`repo env support`    | [报告与自动化输出](./reports.md)                            |
-| 平台维护者 | `repo init`、`repo upgrade`、`repo config inspect`                 | [执行模型](./execution-model.md) 和 [配置文件](./config.md) |
-
-## 命令入口
-
-`repoctl` 包提供多个 bin，例如：
+The package exposes multiple bins:
 
 ```bash
 pnpm exec repoctl doctor
 pnpm exec repoctl new
 ```
 
-文档统一推荐 `repo`，是为了减少新人需要记住的名字。底层实现来自同一套 CLI。
-
-## 下一步
-
-- 第一次接入：[快速开始](./getting-started.md)
-- 不知道用哪个命令：[按场景选命令](./scenarios.md)
-- 理解 CLI 怎么执行：[执行模型](./execution-model.md)
-- 查命令参数：[命令速查](./commands.md)
-- 理解本地校验：[校验链路](./checks.md)
-- 看 doctor 具体检查项：[doctor 诊断](./doctor.md)
-- 固化团队默认值：[配置文件](./config.md)
-- 看可创建的模板：[模板与创建](./templates.md)
-- 治理模板资产：[模板资产治理](./template-assets.md)
-- 接入 CI 和本地流程：[工作流与 CI](./workflows.md)
-- 生成机器可读报告：[报告与自动化输出](./reports.md)
-- 排查常见问题：[排障与报告](./troubleshooting.md)
-- 熟悉短命令：[命令别名](./aliases.md)
+The docs prefer `repo` so new users only need to remember one command name.
+
+## Keep Reading
+
+- [Getting Started](./getting-started.md)
+- [Choose By Scenario](./scenarios.md)
+- [Command Reference](./commands.md)
+- [Configuration](./config.md)
+- [Templates](./templates.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/repoctl/reports.md

@@ -1,94 +1,40 @@
 ---
-description: 说明 repoctl 的 JSON、Markdown、out、redact、env info、env snapshot 和 env support 报告能力。
+outline: deep
 ---
 
-# 报告与自动化输出
+# Reports and Automation Output
 
-repoctl 的报告能力用于把本地上下文变成可保存、可脱敏、可给脚本读取的文件。它适合 CI artifact、issue 模板、编辑器集成和跨机器排障。
+repoctl commands expose human-readable text for terminals, Markdown for issues and pull requests, and stable JSON for automation.
 
-## 1. 通用输出参数
+## Common Options
 
-| 参数           | 支持命令示例                            | 作用                           |
-| -------------- | --------------------------------------- | ------------------------------ |
-| `--json`       | `doctor`、`check`、`templates`、`env`   | 输出结构化数据                 |
-| `--markdown`   | `doctor`、`check`、`templates`、`env`   | 输出便于阅读和粘贴的报告       |
-| `--out <file>` | 多数报告命令                            | 把输出写入文件                 |
-| `--redact`     | `doctor`、`check`、`env`                | 脱敏本机路径                   |
-| `--strict`     | `doctor`、`env snapshot`、`env support` | 有 fail 或 warn 时返回失败状态 |
+- `--json`: emit structured data with stable field names.
+- `--markdown`: emit a shareable report.
+- `--out <file>`: write output to a file.
+- `--redact`: replace local absolute paths.
+- `--strict`: treat doctor warnings as failures where supported.
 
-## 2. env 子命令
-
-| 命令                | 内容                                         | 适合用途         |
-| ------------------- | -------------------------------------------- | ---------------- |
-| `repo env info`     | cwd、workspace、Node、pnpm、包数量等环境摘要 | 快速确认环境     |
-| `repo env paths`    | 关键路径和建议报告路径                       | 统一报告落盘位置 |
-| `repo env snapshot` | 环境、doctor 和 check plan                   | CI 快照          |
-| `repo env support`  | 环境、路径、配置、doctor 和 check plan       | 完整排障包       |
-| `repo env mirror`   | VS Code binary mirror 设置                   | 国内网络环境优化 |
-
-常用组合：
-
-```bash
-repo env info --json --out reports/env.json
-repo env snapshot --markdown --redact --out reports/snapshot.md
-repo env support --markdown --redact --out reports/support.md
-```
-
-## 3. CI artifact 示例
+## Environment Commands
 
 ```bash
-repo doctor --json --out reports/doctor.json
-repo check --full --json --out reports/check-plan.json
+repo env info --json
+repo env paths --markdown
+repo env snapshot --json --out reports/snapshot.json
 repo env support --markdown --redact --out reports/support.md
 ```
 
-建议把 `reports/` 上传为 artifact。这样 CI 失败时，不需要重新询问维护者使用了什么 Node、pnpm、workspace 根目录和校验计划。
-
-## 4. issue 排障模板
+The support bundle combines environment facts, resolved configuration, doctor results, the check plan, and report paths.
 
-当你需要把问题交给同事或维护者时，可以先生成 Markdown：
-
-```bash
-repo env support --markdown --redact --out reports/support.md
-```
-
-然后在 issue 里附上：
-
-| 内容          | 来源              |
-| ------------- | ----------------- |
-| 环境摘要      | `env info`        |
-| 配置命中情况  | `config inspect`  |
-| doctor 失败项 | `doctor`          |
-| check 计划    | `check --dry-run` |
-| 推荐报告路径  | `env paths`       |
-
-## 5. 什么时候使用 JSON
-
-JSON 适合机器判断，不适合人工长时间阅读：
+## CI Example
 
 ```bash
 repo doctor --json --out reports/doctor.json
-repo templates --check --json --out reports/templates.json
-repo new docs --template vitepress --json --out plans/docs.json
+repo check --full --dry-run --json --out reports/check-plan.json
+repo env support --markdown --redact --out reports/support.md
 ```
 
-常见消费方式：
+Upload `reports/` as a CI artifact so failures can be inspected without exposing local paths.
 
-| 目标                | 使用方式                             |
-| ------------------- | ------------------------------------ |
-| CI 判断是否有阻塞项 | 读取 `doctor.summary.fail`           |
-| 编辑器展示模板列表  | 读取 `repo templates --json`         |
-| 预览创建结果        | 读取 `repo new --json`               |
-| 审计模板健康状态    | 读取 `repo templates --check --json` |
-
-## 6. 什么时候使用 Markdown
-
-Markdown 适合给人看，尤其适合 PR、issue 和协作文档：
-
-```bash
-repo doctor --markdown --redact --out reports/doctor.md
-repo check --markdown --redact --out reports/check-plan.md
-repo templates --markdown --out docs/templates.md
-```
+## Choosing A Format
 
-如果报告要离开本机，默认加 `--redact`。
+Use JSON when another program consumes the result. Use Markdown when a person will read or paste the report. Locale only changes human-readable strings; JSON field names and status codes stay unchanged.