@icebreakers/monorepo-templates 1.0.4 → 1.0.5

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

@@ -26,15 +26,15 @@ If the repository was generated from this template, the dependency and root scri
 
 ```bash
 pnpm install
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 ```
 
-| Command        | Purpose                                                                     |
-| -------------- | --------------------------------------------------------------------------- |
-| `pnpm install` | Install workspace dependencies and local links                              |
-| `repo setup`   | Add recommended scripts, workspace patterns, and tooling entries            |
-| `repo doctor`  | Check root files, Node version, CLI dependency, config conflicts, and hooks |
+| 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 |
 
 Fix blocking issues reported by `doctor`, then run it again.
 
@@ -61,23 +61,23 @@ pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
 
 `--json` and `--out` imply `--dry-run`, which makes them suitable for CI, editor integrations, and scripts.
 
-## Use Short Root Scripts
+## Use Root Scripts
 
-After `repo setup`, daily commands can be shorter:
+After `repo init`, daily commands can be shorter:
 
 ```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
 ```
 
-| Root script   | Equivalent CLI          |
-| ------------- | ----------------------- |
-| `pnpm setup`  | `pnpm exec repo setup`  |
-| `pnpm doctor` | `pnpm exec repo doctor` |
-| `pnpm new`    | `pnpm exec repo new`    |
-| `pnpm check`  | `pnpm exec 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
 
@@ -91,7 +91,7 @@ pnpm test
 Or use the repoctl verification entry:
 
 ```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/en/repoctl/index.md

@@ -8,7 +8,7 @@ The CLI does not replace pnpm, Turborepo, or changesets. It gives teams a stable
 
 | Goal                                                  | Command                  |
 | ----------------------------------------------------- | ------------------------ |
-| Add recommended scripts and workspace defaults        | `pnpm exec repo setup`   |
+| 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`   |
@@ -17,21 +17,21 @@ The CLI does not replace pnpm, Turborepo, or changesets. It gives teams a stable
 
 ## Recommended Command Layers
 
-### Root Scripts
+### repo:\* Root Scripts
 
 ```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
 ```
 
-These are the best commands for day-to-day team docs.
+These are the best commands for day-to-day team docs. They are short, explicit, and do not collide with pnpm built-in commands.
 
 ### Explicit CLI Calls
 
 ```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,9 +51,9 @@ pnpm exec repo config inspect
 
 Grouped commands are for maintainers and automation that need finer control.
 
-## Compatibility
+## Command Entrypoints
 
-The package still supports compatibility entry points:
+The package exposes multiple bins:
 
 ```bash
 pnpm exec repoctl doctor

package/templates/vitepress/en/repoctl/scenarios.md

@@ -6,14 +6,14 @@ Start here when you know what you want to do, but not which repoctl command to u
 
 ```bash
 pnpm install
-pnpm doctor
+pnpm run repo:doctor
 ```
 
-If `pnpm doctor` does not exist yet:
+If the `repo:*` scripts do not exist yet:
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
@@ -23,7 +23,7 @@ Keep reading: [Getting Started](./getting-started.md).
 
 ```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
 For daily development, root scripts also work:
 
 ```bash
-pnpm new sdk --template tsdown
+pnpm run repo:new -- sdk --template tsdown
 ```
 
 Keep reading: [Templates](./templates.md).
@@ -50,7 +50,7 @@ Keep reading: [Templates](./templates.md).
 ## I Want To Check Before Committing
 
 ```bash
-pnpm check
+pnpm run repo:check
 pnpm exec repo check --dry-run
 pnpm exec repo check --full
 ```

package/templates/vitepress/en/repoctl/troubleshooting.md

@@ -67,7 +67,7 @@ Keep only:
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` is for compatibility with older projects.
+`monorepo.config.ts` is no longer loaded at runtime; rename it to `repoctl.config.ts`.
 
 ### Unknown Template Key
 
@@ -84,7 +84,7 @@ Explicit `--template` values are validated first. Invalid keys fail with suggest
 Use non-interactive options:
 
 ```bash
-repo setup --yes
+repo init --yes
 repo upgrade --no-overwrite
 repo check --json --out reports/check-plan.json
 ```

package/templates/vitepress/en/repoctl/workflows.md

@@ -6,25 +6,25 @@ repoctl commands have two audiences: humans using short daily commands, and auto
 
 ```bash
 pnpm install
-pnpm doctor
-pnpm new sdk --template tsdown
-pnpm check
+pnpm run repo:doctor
+pnpm run repo:new -- sdk --template tsdown
+pnpm run repo:check
 pnpm build
 ```
 
-| Step           | What It Proves                                          |
-| -------------- | ------------------------------------------------------- |
-| `pnpm install` | Workspace dependencies and local links are ready        |
-| `pnpm doctor`  | Root files, Node, scripts, config, and hooks are usable |
-| `pnpm new`     | New packages follow template conventions                |
-| `pnpm check`   | The lightweight local verification flow is reproducible |
-| `pnpm build`   | The workspace build graph has no obvious breakage       |
+| Step                   | What It Proves                                          |
+| ---------------------- | ------------------------------------------------------- |
+| `pnpm install`         | Workspace dependencies and local links are ready        |
+| `pnpm run repo:doctor` | Root files, Node, scripts, config, and hooks are usable |
+| `pnpm run repo:new`    | New packages follow template conventions                |
+| `pnpm run repo:check`  | The lightweight local verification flow is reproducible |
+| `pnpm build`           | The workspace build graph has no obvious breakage       |
 
 ## Adopt An Existing Repository
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor --markdown --out reports/doctor.md
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor
@@ -75,7 +75,7 @@ repo verify pre-push
 
 | Scenario                              | Option                                             |
 | ------------------------------------- | -------------------------------------------------- |
-| Accept setup defaults                 | `repo setup --yes`                                 |
+| Accept setup defaults                 | `repo init --yes`                                  |
 | Preserve changed files during upgrade | `repo upgrade --no-overwrite`                      |
 | Explicitly overwrite standard assets  | `repo upgrade --yes` or `repo upgrade --overwrite` |
 | Preview only                          | `--dry-run`                                        |

package/templates/vitepress/getting-started.md

@@ -10,7 +10,7 @@
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 pnpm exec repo new
 pnpm exec repo check
@@ -19,7 +19,7 @@ pnpm exec repo check
 模板生成仓库里可以使用更短的根脚本：
 
 ```bash
-pnpm setup
+pnpm run repo:init
 pnpm doctor
 pnpm new
 pnpm check
@@ -31,7 +31,7 @@ pnpm check
 
 | 命令           | 解决的问题                                            |
 | -------------- | ----------------------------------------------------- |
-| `repo setup`   | 补齐仓库默认脚本、workspace patterns 和基础工具链入口 |
+| `repo init`    | 补齐仓库默认脚本、workspace patterns 和基础工具链入口 |
 | `repo doctor`  | 判断仓库当前是否可用，并输出可保存的诊断报告          |
 | `repo new`     | 从内置模板创建包、应用、服务、文档站或 CLI            |
 | `repo check`   | 预览或执行提交前推荐校验                              |

package/templates/vitepress/index.md

@@ -17,7 +17,7 @@ hero:
       link: /repoctl/commands
     - theme: alt
       text: AI 文档入口
-      link: /tools/llms-txt
+      link: /ai/
 
 features:
   - title: 从已有仓库开始
@@ -34,7 +34,7 @@ features:
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo doctor
 pnpm exec repo new
 pnpm exec repo check
@@ -43,10 +43,10 @@ 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
 ```
 
 ## 你可以继续阅读
@@ -55,9 +55,12 @@ pnpm check
 - [快速开始](./repoctl/getting-started.md)
 - [接入已有仓库](./repoctl/adopt-existing.md)
 - [按场景选命令](./repoctl/scenarios.md)
+- [执行模型](./repoctl/execution-model.md)
 - [命令速查](./repoctl/commands.md)
+- [校验链路](./repoctl/checks.md)
+- [doctor 诊断](./repoctl/doctor.md)
 - [配置文件](./repoctl/config.md)
 - [模板与创建](./repoctl/templates.md)
+- [模板资产治理](./repoctl/template-assets.md)
 - [工作流与 CI](./repoctl/workflows.md)
-- [AI 文档入口：llms.txt](./tools/llms-txt.md)
-- [知识库：为什么往 monorepo 方向演进](./monorepo/index.md)
+- [报告与自动化输出](./repoctl/reports.md)

package/templates/vitepress/knowledge/index.md

@@ -0,0 +1,50 @@
+---
+description: repoctl 文档站的知识库入口，汇总 monorepo 管理、现代 npm 包和 JavaScript 模块化基础。
+---
+
+# 知识库
+
+知识库用于解释 repoctl 背后的工程背景。这里不放命令速查，而是回答为什么要这样组织仓库、包、构建和发布流程。
+
+## 1. monorepo 主题
+
+| 页面                                               | 适合解决的问题                     |
+| -------------------------------------------------- | ---------------------------------- |
+| [为什么往 monorepo 方向演进](../monorepo/index.md) | 判断多包仓库是否值得合并管理       |
+| [如何管理 monorepo](../monorepo/manage.md)         | 理解 workspace、任务编排和依赖边界 |
+| [发包与变更日志](../monorepo/publish.md)           | 设计 changeset、版本和发布链路     |
+| [monorepo 命令参考](../monorepo/commands.md)       | 查看通用 monorepo 操作命令         |
+| [monorepo 模板体系](../monorepo/templates.md)      | 理解模板如何减少重复初始化         |
+| [monorepo 排障](../monorepo/troubleshooting.md)    | 排查依赖、构建、类型和发布问题     |
+
+## 2. 现代 npm 包主题
+
+| 页面                                                   | 适合解决的问题                     |
+| ------------------------------------------------------ | ---------------------------------- |
+| [如何复用 js 代码](../why/how-to-reuse-js-code.md)     | 从复制文件演进到发布包             |
+| [什么是 npm 包](../why/what-is-npm-package.md)         | 理解 package.json、入口和安装方式  |
+| [如何发布 npm 包](../why/publish-basic-npm-package.md) | 走通最小 npm 发布流程              |
+| [改进并发布现代 npm 包](../why/index.md)               | 把普通包升级成更规范的现代包       |
+| [现代包指南](../why/modern/index.md)                   | 汇总类型、入口、模块格式和构建工具 |
+
+## 3. 阅读顺序
+
+如果你第一次接触 monorepo，建议按下面顺序阅读：
+
+```txt
+为什么 monorepo
+  -> 如何管理 monorepo
+  -> 什么是 npm 包
+  -> 现代包指南
+  -> 发包与变更日志
+```
+
+如果你已经在维护仓库，可以直接从具体问题进入：
+
+| 你遇到的问题                  | 建议入口                                        |
+| ----------------------------- | ----------------------------------------------- |
+| workspace 包互相引用不清楚    | [如何管理 monorepo](../monorepo/manage.md)      |
+| 不确定 CJS、ESM、types 怎么配 | [现代包指南](../why/modern/index.md)            |
+| 发布后使用方拿不到类型        | [类型声明](../why/modern/dts.md)                |
+| 包入口太多、导入路径混乱      | [包入口](../why/modern/package-entry-points.md) |
+| CI 和发版流程容易漂移         | [发包与变更日志](../monorepo/publish.md)        |

package/templates/vitepress/monorepo/commands.md

@@ -12,10 +12,10 @@ monorepo 的难点通常不是“能不能跑某个工具”，而是团队成
 
 repoctl 把命令分成三层：
 
-| 层级     | 示例                              | 适合场景             |
-| -------- | --------------------------------- | -------------------- |
-| 根脚本   | `pnpm doctor` / `pnpm new`        | 日常开发和团队教程   |
-| 主 CLI   | `pnpm exec repo doctor`           | CI、脚本、排障和文档 |
-| 分组命令 | `repo ws ls` / `repo env support` | 维护者和自动化       |
+| 层级     | 示例                                         | 适合场景             |
+| -------- | -------------------------------------------- | -------------------- |
+| 根脚本   | `pnpm run repo:doctor` / `pnpm run repo:new` | 日常开发和团队教程   |
+| 主 CLI   | `pnpm exec repo doctor`                      | CI、脚本、排障和文档 |
+| 分组命令 | `repo ws ls` / `repo env support`            | 维护者和自动化       |
 
 保留这个旧页面，是为了让已有链接继续可用，同时把读者导向新的 repoctl 命令文档。

package/templates/vitepress/monorepo/index.md

@@ -40,15 +40,15 @@
 
 这不是一个“什么都能配”的框架，而是一套偏实战、偏收敛的默认值：
 
-| 维度     | 默认选择                                       |
-| -------- | ---------------------------------------------- |
-| 包管理   | `pnpm workspace`                               |
-| 任务编排 | `turborepo`                                    |
-| 语言     | TypeScript 优先                                |
-| 校验链路 | ESLint + Stylelint + typecheck + Vitest        |
-| 提交规范 | Husky + lint-staged + commitlint               |
-| 发包     | changesets                                     |
-| 命令入口 | `repo` 为主，`repoctl` / `monorepo` 为兼容入口 |
+| 维度     | 默认选择                                |
+| -------- | --------------------------------------- |
+| 包管理   | `pnpm workspace`                        |
+| 任务编排 | `turborepo`                             |
+| 语言     | TypeScript 优先                         |
+| 校验链路 | ESLint + Stylelint + typecheck + Vitest |
+| 提交规范 | Husky + lint-staged + commitlint        |
+| 发包     | changesets                              |
+| 命令入口 | `repo` 为主，`repoctl` 为完整包名入口   |
 
 这些选择的目的只有一个：减少“每个项目重新想一遍”的成本。
 
@@ -74,10 +74,10 @@
 ### 1. 更短的日常命令
 
 ```bash
-pnpm setup
-pnpm doctor
-pnpm new
-pnpm check
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
 ```
 
 不用先背完整 CLI，先把日常路径跑顺。
@@ -91,7 +91,7 @@ pnpm check
 - Node 版本对不对
 - 有没有安装 CLI 依赖
 - 根脚本齐不齐
-- `repoctl.config.ts` 和 `monorepo.config.ts` 有没有冲突
+- 是否仍残留已废弃的 `monorepo.config.ts`
 - Husky / lint-staged 链路是不是半残状态
 
 ### 3. `repo upgrade` 这种面向存量仓库的同步命令

package/templates/vitepress/monorepo/manage.md

@@ -8,9 +8,9 @@
 
 ```bash
 pnpm install
-pnpm doctor
-pnpm new
-pnpm check
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
 pnpm build
 ```
 
@@ -19,7 +19,7 @@ pnpm build
 如果你在接入一个旧仓库，再多加一步：
 
 ```bash
-pnpm setup
+pnpm exec repo init
 ```
 
 这个工作流背后的顺序是：
@@ -41,10 +41,10 @@ pnpm setup
 这是最推荐的入口：
 
 ```bash
-pnpm setup
-pnpm new
-pnpm doctor
-pnpm check
+pnpm exec repo init
+pnpm run repo:new
+pnpm exec repo doctor
+pnpm run repo:check
 ```
 
 适合：
@@ -59,7 +59,7 @@ pnpm check
 当你要明确告诉别人“这是 CLI 行为，不只是 package.json 脚本”时，用：
 
 ```bash
-pnpm exec repo setup
+pnpm exec repo init
 pnpm exec repo new
 pnpm exec repo doctor
 pnpm exec repo check
@@ -81,14 +81,14 @@ repo ai prompt create --name checkout
 
 ## 日常任务对照表
 
-| 你想做什么             | 推荐命令                     | 说明                                              |
-| ---------------------- | ---------------------------- | ------------------------------------------------- |
-| 初始化一个刚接入的仓库 | `pnpm setup`                 | 同步推荐的仓库元信息和基础工程化配置              |
-| 看仓库当前状态是否健康 | `pnpm doctor`                | 先排根目录、Node、脚本、配置冲突、提交链路        |
-| 创建一个新的包或应用   | `pnpm new`                   | 支持交互式选择，也支持 `--template`               |
-| 提交前做本地校验       | `pnpm check`                 | 默认对齐推荐 pre-commit / pre-push 逻辑           |
-| 同步模板最新标准资产   | `pnpm exec repo upgrade`     | 适合模板升级、老仓库补齐                          |
-| 清理演示仓库或非必要包 | `pnpm exec repo clean --yes` | 零安装也可以用 `pnpm dlx repo@latest clean --yes` |
+| 你想做什么             | 推荐命令                        | 说明                                                 |
+| ---------------------- | ------------------------------- | ---------------------------------------------------- |
+| 初始化一个刚接入的仓库 | `pnpm exec repo init`           | 同步推荐的仓库元信息和基础工程化配置                 |
+| 看仓库当前状态是否健康 | `pnpm exec repo doctor`         | 先排根目录、Node、脚本、遗留配置、提交链路           |
+| 创建一个新的包或应用   | `pnpm run repo:new`             | 支持交互式选择，也支持 `-- --template`               |
+| 提交前做本地校验       | `pnpm run repo:check`           | 默认对齐推荐 pre-commit / pre-push 逻辑              |
+| 同步模板最新标准资产   | `pnpm exec repo upgrade`        | 适合模板升级、老仓库补齐                             |
+| 清理演示仓库或非必要包 | `pnpm exec repo ws clean --yes` | 零安装也可以用 `pnpm dlx repo@latest ws clean --yes` |
 
 ## `doctor`、`check`、`upgrade` 的边界
 
@@ -151,7 +151,7 @@ export default defineMonorepoConfig({
 说明：
 
 - 优先使用 `repoctl.config.ts`
-- `monorepo.config.ts` 继续兼容
+- `monorepo.config.ts` 已不再加载
 - 两者不能同时存在
 
 如果同时存在，现在 CLI 会直接报错，`repo doctor` 也会把它判成阻塞项。
@@ -161,7 +161,7 @@ export default defineMonorepoConfig({
 ### 交互式
 
 ```bash
-pnpm new
+pnpm run repo:new
 ```
 
 适合第一次使用模板、想先看看有哪些模板可选。
@@ -208,8 +208,8 @@ pnpm exec repo new utils
 
 这也是为什么：
 
-- `pnpm doctor` 会检查 Husky 与 lint-staged 是否同时存在
-- `pnpm check` 会成为最自然的人工入口
+- `pnpm exec repo doctor` 会检查 Husky 与 lint-staged 是否同时存在
+- `pnpm run repo:check` 会成为最自然的人工入口
 
 ## 依赖与构建建议
 

package/templates/vitepress/monorepo/troubleshooting.md

@@ -15,6 +15,6 @@ repoctl 排障文档已经集中到：
 | 模板创建问题   | 模板 key、目标目录、创建计划          | `repo templates` / `repo new --dry-run` |
 | 提交前校验问题 | staged 文件、workspace 归属、任务路由 | `repo check --dry-run`                  |
 | 环境差异问题   | Node、pnpm、Git、CI、路径             | `repo env support --markdown --redact`  |
-| 配置冲突问题   | `repoctl.config.ts` 与旧配置文件      | `repo config inspect`                   |
+| 遗留配置问题   | `repoctl.config.ts` 与旧配置文件      | `repo config inspect`                   |
 
 旧页面继续保留为知识点索引，具体排查步骤以后优先维护在 repoctl 分区。

package/templates/vitepress/repoctl/adopt-existing.md

@@ -9,7 +9,7 @@ repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm worksp
 - 已经使用 pnpm 或准备迁移到 pnpm。
 - 有根 `package.json`。
 - 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
-- 希望统一 `setup`、`doctor`、`new`、`check` 这类日常入口。
+- 希望统一 `repo:init`、`repo:doctor`、`repo:new`、`repo:check` 这类日常入口。
 
 如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
 
@@ -23,10 +23,10 @@ packages:
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 ```
 
-`setup --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+`repo init --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
 
 ## 第二步：保存第一次诊断
 
@@ -39,16 +39,16 @@ pnpm exec repo doctor --json --out reports/doctor-before.json
 
 重点看这些项：
 
-| 检查项                       | 常见问题                                             |
-| ---------------------------- | ---------------------------------------------------- |
-| `package-json`               | 当前目录不是仓库根目录                               |
-| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                           |
-| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配        |
-| `tool-package`               | 没安装 `repoctl`                                     |
-| `root-scripts`               | 缺少 `setup/new/check/doctor`                        |
-| `config-file`                | `repoctl.config.ts` 和 `monorepo.config.ts` 同时存在 |
-| `commit-hooks`               | Husky 和 lint-staged 只接了一半                      |
-| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖            |
+| 检查项                       | 常见问题                                         |
+| ---------------------------- | ------------------------------------------------ |
+| `package-json`               | 当前目录不是仓库根目录                           |
+| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                       |
+| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配    |
+| `tool-package`               | 没安装 `repoctl`                                 |
+| `root-scripts`               | 缺少 `repo:init/repo:new/repo:check/repo:doctor` |
+| `config-file`                | 残留已废弃的 `monorepo.config.ts`                |
+| `commit-hooks`               | Husky 和 lint-staged 只接了一半                  |
+| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖        |
 
 ## 第三步：保守同步标准资产
 
@@ -71,12 +71,12 @@ pnpm exec repo check --markdown --redact --out reports/check-plan.md
 
 ## 第五步：接入根脚本
 
-如果 `setup` 已补齐根脚本，团队日常文档就可以改成：
+如果 `repo init` 已补齐根脚本，团队日常文档优先改成：
 
 ```bash
-pnpm doctor
-pnpm new
-pnpm check
+pnpm run repo:doctor
+pnpm run repo:new -- sdk
+pnpm run repo:check
 ```
 
 CI 和自动化脚本仍建议写完整 CLI：
@@ -88,7 +88,7 @@ pnpm exec repo check --full
 
 ## 第六步：处理遗留配置
 
-### 配置文件冲突
+### 遗留配置文件
 
 只保留：
 
@@ -96,7 +96,7 @@ pnpm exec repo check --full
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 只是兼容旧项目。
+`monorepo.config.ts` 已不再加载；请改名为 `repoctl.config.ts`。
 
 ### 本地 tooling loader
 
@@ -106,14 +106,14 @@ repoctl.config.ts
 pnpm exec repo upgrade --yes
 ```
 
-这个命令会迁移到 `repoctl/tooling` 入口。
+这个命令会迁移到 `repoctl/tooling` 入口。简单的 `@icebreakers/commitlint-config`、`@icebreakers/eslint-config`、`@icebreakers/stylelint-config` wrapper 也会被保守转换为 `repoctl/tooling`，复杂 ESLint 配置会保留原有 rules、ignores、overrides 和额外 flat config 语义。
 
 ### workspace patterns 不覆盖包
 
 运行：
 
 ```bash
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 ```
 
 或手动扩展 `pnpm-workspace.yaml`。
@@ -122,7 +122,7 @@ pnpm exec repo setup --yes
 
 存量仓库接入建议拆成小 PR：
 
-1. 安装 `repoctl`，补 `setup/doctor/new/check` 根脚本。
+1. 安装 `repoctl`，补 `init/doctor/new/check` 根脚本。
 2. 提交 `doctor-before` 和 `doctor-after` 报告。
 3. 同步或迁移 tooling 配置。
 4. 接入 hook 和 CI。

package/templates/vitepress/repoctl/aliases.md

@@ -16,7 +16,7 @@ mo
 
 文档统一推荐 `repo`。
 
-兼容入口仍然可用：
+这些 bin 都进入同一套命令实现：
 
 ```bash
 repoctl doctor
@@ -27,10 +27,9 @@ mo doctor
 
 ## 顶层命令别名
 
-| 推荐写法         | 兼容或短写  | 说明             |
+| 推荐写法         | 短写        | 说明             |
 | ---------------- | ----------- | ---------------- |
-| `repo setup`     | `repo init` | 初始化仓库默认值 |
-| `repo upgrade`   | `repo sync` | 同步模板标准资产 |
+| `repo init`      | `repo init` | 初始化仓库默认值 |
 | `repo templates` | `repo tpl`  | 查看或检查模板   |
 
 ## 分组命令别名
@@ -66,6 +65,6 @@ mo doctor
 ## 推荐使用原则
 
 - 新手教程写完整命令，例如 `pnpm exec repo doctor`。
-- 团队 README 写根脚本，例如 `pnpm doctor`。
+- 团队 README 写根脚本，例如 `pnpm run repo:doctor`。
 - 维护者脚本可以写短别名，但要在注释或文档里说明用途。
 - CI 里优先写完整命令，方便日志搜索。