@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/zh/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)           | 设计 pnpm intent、版本和发布链路   |
+| [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/zh/monorepo/commands.md

@@ -0,0 +1,21 @@
+# 命令速查
+
+repoctl 现在是这套文档的主线。完整命令说明请阅读：
+
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+
+## monorepo 知识点：为什么要统一命令入口
+
+monorepo 的难点通常不是“能不能跑某个工具”，而是团队成员是否能稳定地用同一套入口完成日常动作。
+
+repoctl 把命令分成三层：
+
+| 层级     | 示例                                         | 适合场景             |
+| -------- | -------------------------------------------- | -------------------- |
+| 根脚本   | `pnpm run repo:doctor` / `pnpm run repo:new` | 日常开发和团队教程   |
+| 主 CLI   | `pnpm exec repo doctor`                      | CI、脚本、排障和文档 |
+| 分组命令 | `repo ws ls` / `repo env support`            | 维护者和自动化       |
+
+保留这个旧页面，是为了让已有链接继续可用，同时把读者导向新的 repoctl 命令文档。

package/templates/vitepress/zh/monorepo/index.md

@@ -0,0 +1,115 @@
+# 为什么往 monorepo 方向演进
+
+选择 monorepo，不是为了“更先进”，而是为了把多包协作里最常见的重复劳动砍掉。
+
+当你的仓库里同时存在应用、类库、CLI、文档站，或者多个团队要共享同一套类型、配置、脚手架时，monorepo 的收益会很快超过它的管理成本。
+
+## repoctl 面向的真实问题
+
+### 1. 依赖和脚本不再分散
+
+在 polyrepo 里，最常见的问题不是代码本身，而是：
+
+- 每个仓库都要单独装依赖
+- 每个仓库都维护一套 lint / typecheck / test 脚本
+- 同样的工具链升级要重复做很多次
+- 团队成员很难判断哪个仓库的规范才是“当前标准”
+
+在 monorepo 里，这些东西可以收敛到一个根目录。
+
+### 2. 跨包改动可以原子提交
+
+如果一个接口变更同时影响：
+
+- `packages/types`
+- `packages/sdk`
+- `apps/web`
+- `apps/server`
+
+那么在 monorepo 里，一次提交就能把它们一起改完、一起验证、一起回滚。对重构和版本审计都更友好。
+
+### 3. 构建与测试更容易增量化
+
+`pnpm` 负责 workspace 依赖管理，`turborepo` 负责任务编排和缓存，结果就是：
+
+- 没改动的包不需要重复构建
+- CI 可以按依赖图只跑受影响任务
+- 大仓库也能保持比较稳定的反馈速度
+
+## repoctl 的工程立场
+
+这不是一个“什么都能配”的框架，而是一套偏实战、偏收敛的默认值：
+
+| 维度     | 默认选择                                |
+| -------- | --------------------------------------- |
+| 包管理   | `pnpm workspace`                        |
+| 任务编排 | `turborepo`                             |
+| 语言     | TypeScript 优先                         |
+| 校验链路 | ESLint + Stylelint + typecheck + Vitest |
+| 提交规范 | Husky + lint-staged + commitlint        |
+| 发包     | pnpm versioning                         |
+| 命令入口 | `repo` 为主，`repoctl` 为完整包名入口   |
+
+这些选择的目的只有一个：减少“每个项目重新想一遍”的成本。
+
+## 什么时候适合用 monorepo
+
+下面这些情况，适合直接上：
+
+- 你要同时维护多个 npm 包
+- 你有前后端、CLI、文档站共用一套类型或工具
+- 你希望升级脚本、工程化配置时一次同步全仓
+- 你有持续重构、跨包联动改动的需求
+
+下面这些情况，不一定值得上：
+
+- 只有一个很小的应用，没有共享代码需求
+- 团队还没有接受统一规范的准备
+- 构建链路本身还不稳定，先统一仓库只会放大问题
+
+## repoctl 提供的补位能力
+
+单纯有 monorepo 还不够，真正难的是“如何让它易用”。repoctl 补充了三层能力：
+
+### 1. 更短的日常命令
+
+```bash
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
+```
+
+不用先背完整 CLI，先把日常路径跑顺。
+
+### 2. `repo doctor` 这种面向新人的诊断命令
+
+它会直接回答这些问题：
+
+- 你是不是站在仓库根目录
+- `pnpm-workspace.yaml` 在不在
+- Node 版本对不对
+- 有没有安装 CLI 依赖
+- 根脚本齐不齐
+- 是否仍残留已废弃的 `monorepo.config.ts`
+- Husky / lint-staged 链路是不是半残状态
+
+### 3. `repo upgrade` 这种面向存量仓库的同步命令
+
+当受管默认值变化时，你不需要手抄配置，只要选择性同步标准资产。
+
+## 实际收益通常体现在这里
+
+| 场景         | Polyrepo 常见成本  | Monorepo 常见收益      |
+| ------------ | ------------------ | ---------------------- |
+| 工具链升级   | 多仓重复改配置     | 一次升级，多包受益     |
+| 共享类型变更 | 多仓分别发版联调   | 一次改动，一次验证     |
+| CI 反馈      | 每仓重复跑全量     | 利用缓存和依赖图做增量 |
+| 新人接手     | 先理解多个仓库差异 | 先理解一套统一约定     |
+
+## 继续阅读
+
+- [如何管理 monorepo](./manage.md)
+- [命令速查](./commands.md)
+- [排障指南](./troubleshooting.md)
+- [发包与变更日志](./publish.md)

package/templates/vitepress/zh/monorepo/manage.md

@@ -0,0 +1,243 @@
+# 如何管理 monorepo
+
+这一页是 repoctl 文档后面的知识库页面。它不再重新解释所有命令参数，而是解释：为什么这些命令能让 monorepo 日常管理变简单。
+
+如果你只想查命令，直接看 [repoctl 工作流与 CI](../repoctl/workflows.md) 或 [repoctl 命令速查](../repoctl/commands.md)。
+
+## 先记住默认工作流
+
+```bash
+pnpm install
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
+pnpm build
+```
+
+大多数场景里，这已经够了。
+
+如果你在接入一个旧仓库，再多加一步：
+
+```bash
+pnpm exec repo init
+```
+
+这个工作流背后的顺序是：
+
+| 阶段 | 目标                                             |
+| ---- | ------------------------------------------------ |
+| 安装 | 让 workspace 依赖和本地包链接完整                |
+| 诊断 | 先确认仓库结构、Node、脚本、配置和提交链路可用   |
+| 创建 | 用模板生成新包，减少手写 package metadata 和配置 |
+| 校验 | 在提交前复现默认 hook 和 workspace typecheck     |
+| 构建 | 最后再跑更重的全仓任务                           |
+
+## 命令分层
+
+repoctl 刻意把日常入口收敛到少量任务型命令。
+
+### 第一层：根脚本
+
+这是最推荐的入口：
+
+```bash
+pnpm exec repo init
+pnpm run repo:new
+pnpm exec repo doctor
+pnpm run repo:check
+```
+
+适合：
+
+- 新人
+- 日常开发
+- 文档教程
+- 团队内部统一约定
+
+### 第二层：主 CLI
+
+当你要明确告诉别人“这是 CLI 行为，不只是 package.json 脚本”时，用：
+
+```bash
+pnpm exec repo init
+pnpm exec repo new
+pnpm exec repo doctor
+pnpm exec repo check
+pnpm exec repo upgrade
+```
+
+### 第三层：分组命令
+
+更细的高级操作保留在分组里：
+
+```bash
+repo workspace upgrade
+repo ws up
+repo tooling init eslint vitest
+repo tg init --all
+repo skills sync --codex
+repo ai prompt create --name checkout
+```
+
+## 日常任务对照表
+
+| 你想做什么             | 推荐命令                        | 说明                                                 |
+| ---------------------- | ------------------------------- | ---------------------------------------------------- |
+| 初始化一个刚接入的仓库 | `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` 的边界
+
+这是最容易混淆的三个命令。
+
+### `doctor`
+
+偏“仓库体检”。
+
+它不关心你当前改了什么代码，而是关心：
+
+- 这个仓库是不是完整
+- 当前目录是不是根目录
+- 当前机器的 Node 版本能不能跑
+- 命令入口和配置文件是不是一致
+
+### `check`
+
+偏“提交前校验”。
+
+它更像一个人工触发的推荐检查入口，适合：
+
+- 提交前自查
+- 怀疑 lint / typecheck / hooks 有问题时快速复现
+- 用 `repo check --dry-run`、`repo check --json --out reports/check-plan.json` 或 `repo check --markdown --redact --out reports/check-plan.md` 先确认校验路由
+
+### `upgrade`
+
+偏“模板资产同步”。
+
+它解决的是：
+
+- 模板最新默认脚本要不要补进来
+- 工作流、配置文件、GitHub 资产要不要同步
+- 存量仓库要不要追上现在的标准
+
+## 配置推荐
+
+推荐只保留一个文件：
+
+```ts
+// repoctl.config.ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+    clean: {
+      autoConfirm: true,
+    },
+    upgrade: {
+      skipOverwrite: true,
+    },
+  },
+})
+```
+
+说明：
+
+- 优先使用 `repoctl.config.ts`
+- `monorepo.config.ts` 已不再加载
+- 两者不能同时存在
+
+如果同时存在，现在 CLI 会直接报错，`repo doctor` 也会把它判成阻塞项。
+
+## `new` 的推荐用法
+
+### 交互式
+
+```bash
+pnpm run repo:new
+```
+
+适合第一次使用模板、想先看看有哪些模板可选。
+
+### 直接指定模板
+
+```bash
+pnpm exec repo new docs --template vitepress
+pnpm exec repo new sdk --template tsdown
+```
+
+适合你已经明确知道要创建什么。
+
+### 固化团队默认模板
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+设置后：
+
+```bash
+pnpm exec repo new utils
+```
+
+会直接按默认模板生成，不再额外询问模板类型。
+
+## 默认提交链路
+
+如果你保留模板默认生成的 `.husky` 与 `lint-staged.config.js`，通常会得到这条链路：
+
+| 阶段         | 默认行为                                                                |
+| ------------ | ----------------------------------------------------------------------- |
+| `pre-commit` | 聚焦 staged 文件运行 `stylelint`、`eslint`、workspace `typecheck`       |
+| `pre-push`   | 运行整仓 `lint`、`typecheck`，再补跑受影响包的 `build` / `test` / `tsd` |
+
+这也是为什么：
+
+- `pnpm exec repo doctor` 会检查 Husky 与 lint-staged 是否同时存在
+- `pnpm run repo:check` 会成为最自然的人工入口
+
+## 依赖与构建建议
+
+```bash
+pnpm install
+pnpm up -rLi
+pnpm build
+pnpm test
+```
+
+- `pnpm install`：统一安装 workspace 依赖
+- `pnpm up -rLi`：交互式升级依赖
+- `pnpm build` / `pnpm test`：让 Turborepo 帮你做任务编排与缓存
+
+## 工具层 API 什么时候用
+
+如果你只是要使用默认 CLI，不需要直接碰 `@icebreakers/monorepo/tooling`。
+
+只有下面两种情况建议直接使用：
+
+- 你要在仓库里手写 tooling wrapper 配置
+- 你在维护这套 CLI / 模板本身
+
+其余大多数团队，停留在 `repoctl.config.ts` 这一层就够了。
+
+## 继续阅读
+
+- [repoctl 工作流与 CI](../repoctl/workflows.md)
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [发包与变更日志](./publish.md)

package/templates/vitepress/zh/monorepo/publish.md

@@ -0,0 +1,87 @@
+# monorepo 发包与变更日志
+
+repoctl 默认使用 pnpm 原生 versioning。它保留 Changesets 格式的变更意图，同时把版本计算、依赖传播、changelog 和发布收进 pnpm 本身。
+
+## 日常流程
+
+先完成质量校验，再记录变更：
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm tsd
+pnpm test
+pnpm change
+pnpm change status
+```
+
+变更意图文件放在 `.changeset/*.md`，描述受影响包和 patch/minor/major。不要手动修改包版本。
+
+## Release PR
+
+main push 会运行：
+
+```bash
+pnpm version -r --dry-run
+pnpm version -r
+```
+
+CI 将版本号、各包 `CHANGELOG.md` 和 `.changeset/ledger.yaml` 提交到 Release PR。合并 Release PR 后，下一次 main push 执行：
+
+```bash
+pnpm publish -r --report-summary --provenance --no-git-checks
+```
+
+pnpm 根据 registry 中已有的版本自动跳过已发布包。CI 读取 `pnpm-publish-summary.json` 创建 `package@version` tag 和 GitHub Release，发布操作可以安全重试。
+
+## Workspace versioning 配置
+
+根 `pnpm-workspace.yaml` 中的关键配置：
+
+```yaml
+versioning:
+  fixed:
+    - ['@icebreakers/monorepo', repoctl]
+  ignore:
+    - '@icebreakers/client'
+  changelog:
+    storage: repository
+```
+
+`fixed` 保证组内包同版本；`ignore` 排除 private 包；`repository` 让 changelog 作为源代码提交。
+
+## Prerelease lanes
+
+预发布使用 pnpm lanes：
+
+```bash
+pnpm exec repo release pre enter beta
+git add pnpm-workspace.yaml && git commit -m "chore(release): enter beta lane"
+git push
+pnpm exec repo release pre publish
+```
+
+预发布版本为 `X.Y.Z-beta.N`，并使用 npm `beta` dist-tag。退出时运行：
+
+```bash
+pnpm exec repo release pre exit
+git add pnpm-workspace.yaml && git commit -m "chore(release): exit prerelease lane"
+```
+
+fixed group 必须整体切换 lane，不能只移动其中一个包。
+
+## 恢复未发布版本
+
+如果版本提交已合并但 npm 发布失败，在 Release workflow 手动选择 `publish-unpublished`，填入 package 和 version。CI 会校验 main 上的 manifest 版本，使用 pnpm 发布并重新生成 tag 和 GitHub Release 元数据。
+
+## repoctl 的边界
+
+生成的 GitHub Actions 只保留环境准备和一个 `pnpm exec repo release ci` 调用。
+repoctl 负责发布前 build/lint/test、lane 一致性检查、Release PR、npm
+发布、package tag 与 GitHub Release；pnpm 负责变更意图、版本计算、changelog、
+ledger 和 registry 发布细节。
+
+存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`，后续使用
+`pnpm exec repo upgrade --yes` 即可跟随 repoctl 升级。未标记的自定义 release
+workflow 默认不会被覆盖，确认后可使用 `repo upgrade --overwrite-release`。

package/templates/vitepress/zh/monorepo/templates.md

@@ -0,0 +1,21 @@
+# 模板速查
+
+模板创建已经收敛到 repoctl 文档：
+
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 快速开始](../repoctl/getting-started.md)
+
+## monorepo 知识点：模板为什么重要
+
+当仓库里存在多种产物时，模板能把重复选择前置成稳定默认值：
+
+| 产物          | 常见目录                 | 关注点                         |
+| ------------- | ------------------------ | ------------------------------ |
+| TypeScript 库 | `packages/*`             | exports、types、构建和 tsd     |
+| Vue 组件库    | `packages/*`             | SFC、样式校验、类型声明        |
+| 应用          | `apps/*`                 | dev、build、部署资产           |
+| 服务          | `apps/*`                 | API 入口、运行时类型、环境变量 |
+| 文档站        | `apps/*`                 | VitePress 配置、导航、内容结构 |
+| CLI           | `apps/*` 或 `packages/*` | bin 入口、参数解析、发布       |
+
+repoctl 的 `repo templates` 和 `repo new` 负责把这些约定落实到文件系统。

package/templates/vitepress/zh/monorepo/troubleshooting.md

@@ -0,0 +1,20 @@
+# 常见问题排障
+
+repoctl 排障文档已经集中到：
+
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [repoctl 命令速查](../repoctl/commands.md)
+
+## monorepo 知识点：先区分问题类型
+
+排障前先判断问题属于哪一类：
+
+| 类型           | 先看什么                              | 常用命令                                |
+| -------------- | ------------------------------------- | --------------------------------------- |
+| 仓库结构问题   | 根目录、workspace 文件、Node 版本     | `repo doctor`                           |
+| 模板创建问题   | 模板 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 分区。

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

@@ -0,0 +1,135 @@
+# 接入已有仓库
+
+repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
+
+## 适合接入的仓库
+
+优先满足这些条件：
+
+- 已经使用 pnpm 或准备迁移到 pnpm。
+- 有根 `package.json`。
+- 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
+- 希望统一 `repo:init`、`repo:doctor`、`repo:new`、`repo:check` 这类日常入口。
+
+如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+## 第一步：安装并初始化
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo init --yes
+```
+
+`repo init --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+
+## 第二步：保存第一次诊断
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
+pnpm exec repo doctor --json --out reports/doctor-before.json
+```
+
+建议把第一次报告提交到 PR 评论或 artifact，而不是只看终端输出。
+
+重点看这些项：
+
+| 检查项                       | 常见问题                                         |
+| ---------------------------- | ------------------------------------------------ |
+| `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 覆盖        |
+
+## 第三步：保守同步标准资产
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
+```
+
+`--no-overwrite` 适合第一次接入：它同步缺失资产，但保留已有 drifted 文件。你可以在 PR diff 里逐项看哪些配置要进一步迁移。
+
+## 第四步：预览校验计划
+
+```bash
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo check --markdown --redact --out reports/check-plan.md
+```
+
+先看 plan，再决定要不要接入 hook 或 CI。
+
+## 第五步：接入根脚本
+
+如果 `repo init` 已补齐根脚本，团队日常文档优先改成：
+
+```bash
+pnpm run repo:doctor
+pnpm run repo:new -- sdk
+pnpm run repo:check
+```
+
+CI 和自动化脚本仍建议写完整 CLI：
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+## 第六步：处理遗留配置
+
+### 遗留配置文件
+
+只保留：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 已不再加载；请改名为 `repoctl.config.ts`。
+
+### 本地 tooling loader
+
+如果 `doctor` 提示 tooling 配置引用了本地源码 loader，使用：
+
+```bash
+pnpm exec repo upgrade --yes
+```
+
+这个命令会迁移到 `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 init --yes
+```
+
+或手动扩展 `pnpm-workspace.yaml`。
+
+## 推荐 PR 结构
+
+存量仓库接入建议拆成小 PR：
+
+1. 安装 `repoctl`，补 `init/doctor/new/check` 根脚本。
+2. 提交 `doctor-before` 和 `doctor-after` 报告。
+3. 同步或迁移 tooling 配置。
+4. 接入 hook 和 CI。
+5. 用 `repo new --dry-run` 验证模板创建路径。
+
+## 下一步
+
+- [工作流与 CI](./workflows.md)
+- [排障与报告](./troubleshooting.md)
+- [配置文件](./config.md)