@icebreakers/monorepo-templates 1.0.4 → 1.0.5

package/templates/vitepress/repoctl/checks.md

@@ -0,0 +1,86 @@
+---
+description: 说明 repoctl check 和 verify 的校验模式、pre-commit、staged typecheck、pre-push 与 commit-msg 链路。
+---
+
+# repoctl 校验链路
+
+`repo check` 是给人使用的统一入口，`repo verify` 是给 hook、CI 和脚本复用的底层入口。
+
+## 1. 模式速查
+
+| 命令                                         | 模式         | 实际动作                                                       |
+| -------------------------------------------- | ------------ | -------------------------------------------------------------- |
+| `repo check`                                 | `default`    | 执行 `repo verify pre-commit`                                  |
+| `repo check --staged`                        | `staged`     | 执行 pre-commit，并按 staged TypeScript/Vue 文件路由 typecheck |
+| `repo check --full`                          | `full`       | 按根脚本执行 `lint`、`typecheck`、`test`、`build` 中存在的任务 |
+| `repo check --edit-file .git/COMMIT_EDITMSG` | `commit-msg` | 执行 commit message 校验                                       |
+
+预览模式不会真正执行校验：
+
+```bash
+repo check --dry-run
+repo check --full --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+## 2. pre-commit
+
+`repo verify pre-commit` 默认执行 lint-staged。适合在提交前只处理 staged 文件，避免每次提交都跑整仓校验。
+
+推荐的 lint-staged 行为包括：
+
+| 文件类型                   | 推荐处理                                 |
+| -------------------------- | ---------------------------------------- |
+| JS、TS、Vue                | ESLint 自动修复                          |
+| CSS、SCSS、Less、Vue style | Stylelint 自动修复                       |
+| TS、TSX、MTS、CTS、Vue     | 路由到最近 workspace 的 `typecheck` 脚本 |
+
+## 3. staged typecheck
+
+`repo verify staged-typecheck <files...>` 会根据文件路径向上查找最近的 workspace，并执行该 workspace 的 `typecheck`。
+
+```bash
+repo verify staged-typecheck packages/ui/src/button.ts templates/client/src/App.vue
+```
+
+它解决的是 monorepo 里常见的问题：一个提交只改了某个包，不应该让所有 Vue 和 TypeScript workspace 都重复跑类型检查。
+
+## 4. pre-push
+
+`repo verify pre-push` 面向推送前的完整保护。默认策略是：
+
+| 阶段         | 行为                                             |
+| ------------ | ------------------------------------------------ |
+| 根任务       | 强制执行整仓 `lint` 与 `typecheck`               |
+| 变更范围任务 | 按 workspace 改动范围补跑 `build`、`test`、`tsd` |
+| 失败处理     | 任一任务失败时停止并返回失败状态                 |
+
+如果 CI 想要更明确地复现整仓校验，可以使用：
+
+```bash
+repo check --full
+```
+
+## 5. commit message
+
+`repo verify commit-msg <file>` 用于 Git 的 `commit-msg` hook。未配置自定义命令时，它会执行：
+
+```bash
+pnpm exec commitlint --edit <file>
+```
+
+如果你只是手动验证当前提交信息，可以运行：
+
+```bash
+repo check --edit-file .git/COMMIT_EDITMSG
+```
+
+## 6. 选择建议
+
+| 场景               | 推荐命令                                          |
+| ------------------ | ------------------------------------------------- |
+| 本地提交前快速复现 | `repo check`                                      |
+| lint-staged 调试   | `repo check --staged --dry-run`                   |
+| 推送前完整检查     | `repo check --full`                               |
+| CI 门禁            | `repo doctor --strict` 后接 `repo check --full`   |
+| 只生成计划         | `repo check --json --out reports/check-plan.json` |

package/templates/vitepress/repoctl/commands.md

@@ -5,30 +5,30 @@
 ## 最推荐入口
 
 ```bash
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 pnpm exec repo templates
 pnpm exec repo new
 pnpm exec repo check
 ```
 
-模板生成仓库里的短脚本：
+模板生成仓库里的推荐根脚本：
 
 ```bash
-pnpm setup
-pnpm doctor
-pnpm new
-pnpm check
+pnpm run repo:init
+pnpm run repo:doctor
+pnpm run repo:new
+pnpm run repo:check
 ```
 
-## `repo setup`
+## `repo init`
 
 ```bash
-repo setup
-repo setup --yes
-repo setup --preset minimal
-repo setup --preset standard --force
-repo setup --overwrite
+repo init
+repo init --yes
+repo init --preset minimal
+repo init --preset standard --force
+repo init --overwrite
 ```
 
 用途：
@@ -52,7 +52,7 @@ repo doctor --markdown --redact --out reports/doctor.md
 用途：
 
 - 诊断当前目录是不是可直接开始使用的 monorepo 根目录。
-- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、配置冲突和提交链路。
+- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、遗留配置和提交链路。
 - `--strict` 会把 warning 也视为失败，适合 CI 门禁。
 - `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
 - `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
@@ -147,8 +147,22 @@ repo skills sync --codex
 
 分组命令适合维护者和自动化脚本。日常开发优先使用顶层命令。
 
+## 输出参数速查
+
+| 参数           | 适用命令                                     | 说明                                  |
+| -------------- | -------------------------------------------- | ------------------------------------- |
+| `--json`       | `doctor`、`check`、`templates`、`new`、`env` | 输出机器可读数据                      |
+| `--markdown`   | `doctor`、`check`、`templates`、`env`        | 输出适合 PR 和 issue 的 Markdown      |
+| `--out <file>` | 多数报告和计划命令                           | 写入文件，便于 CI artifact 或脚本读取 |
+| `--redact`     | `doctor`、`check`、`env`                     | 分享报告前脱敏本机路径                |
+| `--strict`     | `doctor`、`env snapshot`、`env support`      | warning 也会导致失败                  |
+| `--dry-run`    | `check`、`new`                               | 只看计划，不执行校验或写入文件        |
+
 ## 继续阅读
 
+- [执行模型](./execution-model.md)
+- [校验链路](./checks.md)
+- [doctor 诊断](./doctor.md)
 - [工作流与 CI](./workflows.md)
-- [排障与报告](./troubleshooting.md)
+- [报告与自动化输出](./reports.md)
 - [命令别名](./aliases.md)

package/templates/vitepress/repoctl/config.md

@@ -6,7 +6,9 @@ repoctl 推荐在仓库根目录使用一个配置文件：
 repoctl.config.ts
 ```
 
-旧文件名 `monorepo.config.ts` 继续兼容，但两者不能同时存在。`repo doctor` 会把冲突配置标记为阻塞问题。
+`monorepo.config.ts` 已不再作为运行时配置入口。迁移旧仓库时请改名为 `repoctl.config.ts`。
+
+repoctl 支持 `ts`、`mts`、`cts`、`js`、`mjs`、`cjs` 等配置文件后缀。新项目优先使用 `repoctl.config.ts`，这样能保留类型提示和更清晰的迁移路径。
 
 ## 最小配置
 
@@ -79,3 +81,10 @@ repo cfg i --markdown --redact --out reports/config.md
 - 团队长期一致的选择写进 `repoctl.config.ts`。
 - 临时行为用命令参数表达，例如 `--dry-run`、`--json`、`--out`。
 - 自动化脚本优先使用显式参数，减少隐藏状态。
+
+## 继续阅读
+
+- [执行模型](./execution-model.md)
+- [模板与创建](./templates.md)
+- [模板资产治理](./template-assets.md)
+- [报告与自动化输出](./reports.md)

package/templates/vitepress/repoctl/doctor.md

@@ -0,0 +1,86 @@
+---
+description: 说明 repoctl doctor 的检查项、状态含义、strict 模式和修复建议。
+---
+
+# repoctl doctor 诊断
+
+`repo doctor` 用来判断当前目录是不是一个可维护、可开发、可接入 repoctl 工作流的 pnpm monorepo 根目录。
+
+## 1. 状态含义
+
+| 状态   | 含义           | 对退出码的影响                |
+| ------ | -------------- | ----------------------------- |
+| `pass` | 检查通过       | 不影响                        |
+| `warn` | 存在建议修复项 | 默认不失败，`--strict` 下失败 |
+| `fail` | 阻塞项         | 命令返回失败状态              |
+
+CI 中推荐使用：
+
+```bash
+repo doctor --strict
+```
+
+这样 warning 不会长期堆积成隐性风险。
+
+## 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. 输出报告
+
+```bash
+repo doctor
+repo doctor --json
+repo doctor --markdown --redact
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+自动化脚本推荐使用 `pnpm run repo:doctor -- --json` 或 `pnpm exec repo doctor --json`。
+
+| 输出         | 适合场景                    |
+| ------------ | --------------------------- |
+| 默认交互文本 | 本地直接阅读                |
+| JSON         | CI、编辑器、脚本消费        |
+| Markdown     | 粘贴到 issue、PR 或排障文档 |
+| `--redact`   | 分享报告前隐藏本机绝对路径  |
+
+## 4. strict 模式
+
+`--strict` 会把 warning 也视为失败。它适合放在 CI 早期阶段：
+
+```bash
+pnpm install --frozen-lockfile
+repo doctor --strict
+repo check --full
+```
+
+如果你正在接入存量仓库，建议先不用 strict，把报告保存下来逐项修复：
+
+```bash
+repo doctor --markdown --redact --out reports/doctor.md
+repo upgrade --no-overwrite
+repo doctor
+```
+
+## 5. 排查顺序
+
+建议按阻塞程度处理：
+
+1. 先处理 `fail`，否则命令或 CI 很可能无法继续。
+2. 再处理遗留配置和 Node 版本问题。
+3. 然后补根脚本、hook 和 lint-staged。
+4. 最后整理 workspace patterns 与 tooling imports。
+
+如果不确定报告能否安全分享，使用 [报告与自动化输出](./reports.md) 里的 `--redact` 和 `env support`。

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

@@ -0,0 +1,81 @@
+---
+description: 说明 repoctl CLI 的入口层级、命令懒加载、非交互输出和脚本集成方式。
+---
+
+# repoctl 执行模型
+
+repoctl 的核心设计是把日常入口保持短，把细粒度能力放到分组命令里，并让 CI、编辑器和脚本可以读取结构化输出。
+
+## 1. 入口层级
+
+| 层级        | 示例                                                               | 使用场景                       |
+| ----------- | ------------------------------------------------------------------ | ------------------------------ |
+| 根脚本      | `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`                         | 维护者、自动化和集成工具       |
+
+## 2. 命令执行过程
+
+repoctl 启动时只注册命令树。具体实现会在 action 执行时再加载，因此查看帮助和列出命令不会提前扫描所有 workspace、Git 状态和模板文件。
+
+```txt
+repo --help
+  -> 注册命令树
+  -> 输出帮助
+
+repo doctor
+  -> 注册命令树
+  -> 加载 doctor 实现
+  -> 发现 workspace
+  -> 输出诊断报告
+```
+
+这种模型适合命令数量较多的 monorepo 工具：日常命令保持快，重逻辑只在真正执行时进入。
+
+## 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)。

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

@@ -26,7 +26,7 @@ pnpm add -D repoctl
 
 ```bash
 pnpm install
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 ```
 
@@ -35,8 +35,8 @@ pnpm exec repo doctor
 | 命令           | 作用                                                |
 | -------------- | --------------------------------------------------- |
 | `pnpm install` | 安装 workspace 依赖并创建本地链接                   |
-| `repo setup`   | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
-| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、配置冲突和提交链路 |
+| `repo init`    | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
+| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、遗留配置和提交链路 |
 
 如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm exec repo doctor`。
 
@@ -63,25 +63,25 @@ pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
 
 `--json` 和 `--out` 会隐含 `--dry-run`，适合 CI、编辑器和脚本读取创建计划。
 
-## 使用短脚本
+## 使用根脚本
 
-如果仓库已经通过 `repo setup` 或模板生成补齐了根脚本，日常可以写得更短：
+如果仓库已经通过 `repo init` 或模板生成补齐了根脚本，日常可以写得更短：
 
 ```bash
-pnpm setup
-pnpm doctor
-pnpm new sdk --template tsdown
-pnpm check
+pnpm run repo:init
+pnpm run repo:doctor -- --json
+pnpm run repo:new -- sdk --template tsdown
+pnpm run repo:check
 ```
 
 对应关系：
 
-| 短脚本        | 等价命令                |
-| ------------- | ----------------------- |
-| `pnpm setup`  | `pnpm exec repo setup`  |
-| `pnpm doctor` | `pnpm exec repo doctor` |
-| `pnpm new`    | `pnpm exec repo new`    |
-| `pnpm check`  | `pnpm exec repo check`  |
+| 根脚本                         | 等价命令                     |
+| ------------------------------ | ---------------------------- |
+| `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`       |
 
 ## 提交前检查
 
@@ -95,7 +95,7 @@ pnpm test
 如果只想走 repoctl 推荐的本地检查入口：
 
 ```bash
-pnpm check
+pnpm run repo:check
 pnpm exec repo check --dry-run
 pnpm exec repo check --json --out reports/check-plan.json
 ```

package/templates/vitepress/repoctl/index.md

@@ -8,7 +8,7 @@
 
 | 场景                                     | 推荐入口                 |
 | ---------------------------------------- | ------------------------ |
-| 给已有 pnpm workspace 补齐标准脚本和配置 | `pnpm exec repo setup`   |
+| 给已有 pnpm workspace 补齐标准脚本和配置 | `pnpm exec repo init`    |
 | 判断当前仓库是不是能顺利开发             | `pnpm exec repo doctor`  |
 | 创建新的包、应用、文档站或 CLI           | `pnpm exec repo new`     |
 | 提交前复现推荐校验链路                   | `pnpm exec repo check`   |
@@ -17,21 +17,21 @@
 
 ## 推荐命令层级
 
-### 1. 生成仓库里的短脚本
+### 1. 生成仓库里的 repo:\* 根脚本
 
 ```bash
-pnpm setup
-pnpm doctor
-pnpm new
-pnpm check
+pnpm run repo:init
+pnpm run repo:doctor
+pnpm run repo:new
+pnpm run repo:check
 ```
 
-这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名。
+这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名，也不会和 pnpm 内置命令冲突。
 
 ### 2. 明确调用 repo CLI
 
 ```bash
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 pnpm exec repo templates
 pnpm exec repo new sdk --template tsdown
@@ -51,24 +51,52 @@ pnpm exec repo config inspect
 
 这些入口适合已经熟悉 repoctl 的维护者，用来做更细的 workspace、tooling、环境和配置操作。
 
-## 和旧入口的关系
+## repoctl 管什么
 
-`repoctl` 包仍然提供兼容入口，例如：
+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，例如：
 
 ```bash
 pnpm exec repoctl doctor
 pnpm exec repoctl new
 ```
 
-文档统一推荐 `repo`，是为了减少新人需要记住的名字。底层实现仍来自同一套 CLI。
+文档统一推荐 `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)
-- 生成排障报告：[排障与报告](./troubleshooting.md)
+- 生成机器可读报告：[报告与自动化输出](./reports.md)
+- 排查常见问题：[排障与报告](./troubleshooting.md)
 - 熟悉短命令：[命令别名](./aliases.md)

package/templates/vitepress/repoctl/reports.md

@@ -0,0 +1,94 @@
+---
+description: 说明 repoctl 的 JSON、Markdown、out、redact、env info、env snapshot 和 env support 报告能力。
+---
+
+# 报告与自动化输出
+
+repoctl 的报告能力用于把本地上下文变成可保存、可脱敏、可给脚本读取的文件。它适合 CI artifact、issue 模板、编辑器集成和跨机器排障。
+
+## 1. 通用输出参数
+
+| 参数           | 支持命令示例                            | 作用                           |
+| -------------- | --------------------------------------- | ------------------------------ |
+| `--json`       | `doctor`、`check`、`templates`、`env`   | 输出结构化数据                 |
+| `--markdown`   | `doctor`、`check`、`templates`、`env`   | 输出便于阅读和粘贴的报告       |
+| `--out <file>` | 多数报告命令                            | 把输出写入文件                 |
+| `--redact`     | `doctor`、`check`、`env`                | 脱敏本机路径                   |
+| `--strict`     | `doctor`、`env snapshot`、`env support` | 有 fail 或 warn 时返回失败状态 |
+
+## 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 示例
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo check --full --json --out reports/check-plan.json
+repo env support --markdown --redact --out reports/support.md
+```
+
+建议把 `reports/` 上传为 artifact。这样 CI 失败时，不需要重新询问维护者使用了什么 Node、pnpm、workspace 根目录和校验计划。
+
+## 4. issue 排障模板
+
+当你需要把问题交给同事或维护者时，可以先生成 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 适合机器判断，不适合人工长时间阅读：
+
+```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
+```
+
+常见消费方式：
+
+| 目标                | 使用方式                             |
+| ------------------- | ------------------------------------ |
+| 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
+```
+
+如果报告要离开本机，默认加 `--redact`。

package/templates/vitepress/repoctl/scenarios.md

@@ -6,14 +6,14 @@
 
 ```bash
 pnpm install
-pnpm doctor
+pnpm run repo:doctor
 ```
 
-如果 `pnpm doctor` 不存在：
+如果 `repo:*` 根脚本还不存在：
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
@@ -23,7 +23,7 @@ pnpm exec repo doctor
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
@@ -42,7 +42,7 @@ pnpm exec repo new docs --template vitepress --dry-run
 如果只是日常开发，根脚本也可以：
 
 ```bash
-pnpm new sdk --template tsdown
+pnpm run repo:new -- sdk --template tsdown
 ```
 
 继续看：[模板与创建](./templates.md)。
@@ -50,7 +50,7 @@ pnpm new sdk --template tsdown
 ## 我要提交前自查
 
 ```bash
-pnpm check
+pnpm run repo:check
 pnpm exec repo check --dry-run
 pnpm exec repo check --full
 ```