@icebreakers/monorepo-templates 1.3.0 → 1.3.2

package/templates/vitepress/{repoctl → tasks}/reports.md

@@ -4,6 +4,31 @@ outline: deep
 
 # Reports and Automation Output
 
+## When To Use
+
+Use this task when a person, CI job, or support request needs a durable record of what repoctl found or planned.
+
+## Prerequisites
+
+- Choose a `reports/` directory that is ignored or uploaded as a CI artifact.
+- Use `--redact` before sharing environment details outside the repository.
+
+## Smallest Command
+
+```bash
+repo env support --markdown --redact --out reports/support.md
+```
+
+## Expected Output
+
+The output file contains stable headings and command results that can be attached to a pull request or issue.
+
+## Common Branches
+
+- Another tool consumes the result: use JSON with `--json`.
+- You only need to inspect a plan: combine `--dry-run` with the desired format.
+- A report contains a local path or token: regenerate it with `--redact`.
+
 repoctl commands expose human-readable text for terminals, Markdown for issues and pull requests, and stable JSON for automation.
 
 ## Common Options

package/templates/vitepress/{repoctl → tasks}/troubleshooting.md

@@ -1,4 +1,30 @@
-# Troubleshooting
+# Troubleshoot
+
+## When To Use
+
+Use this task when initialization, checks, templates, or automation stop with an unexpected result.
+
+## Prerequisites
+
+- Run the command from the repository root.
+- Keep the original error and the repository revision available.
+- Remove secrets before sharing command output.
+
+## Smallest Command
+
+```bash
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+## Expected Output
+
+The report identifies the repository root, package manager, workspace configuration, tooling, and the first failing check.
+
+## Common Branches
+
+- The command is run from a child directory: change to the workspace root.
+- A config file conflicts with a managed asset: inspect the plan before overwriting.
+- A template key is unknown: list templates with `repo templates`.
 
 repoctl focuses on reports that can be reproduced, saved, and shared.
 
@@ -91,6 +117,6 @@ repo check --json --out reports/check-plan.json
 
 ## Keep Reading
 
-- [Workflows and CI](./workflows.md)
-- [Command Reference](./commands.md)
-- [Command Aliases](./aliases.md)
+- [Add checks to CI](/tasks/ci)
+- [Command Reference](/reference/commands)
+- [Command Aliases](/reference/aliases)

package/templates/vitepress/zh/ai/llms-txt.md

@@ -34,9 +34,9 @@ description: 说明这个页面解决的问题和适用场景。
 
 AI 入口应该保持显眼，但不要替代正常文档结构：
 
-| 页面类型                               | 推荐位置                             |
-| -------------------------------------- | ------------------------------------ |
-| repoctl 命令、校验、诊断、报告         | `/repoctl/`                          |
-| monorepo 和 npm 包基础知识             | `/knowledge/`、`/monorepo/`、`/why/` |
-| pnpm、Turborepo、versioning 等工具专题 | `/tools/`                            |
-| llms.txt 和 AI 工具读取约定            | `/ai/`                               |
+| 页面类型                               | 推荐位置                                          |
+| -------------------------------------- | ------------------------------------------------- |
+| repoctl 命令、校验、诊断、报告         | `/start/`                                         |
+| monorepo 和 npm 包基础知识             | `/learn/`、`/learn/monorepo/`、`/learn/packages/` |
+| pnpm、Turborepo、versioning 等工具专题 | `/learn/tools/`                                   |
+| llms.txt 和 AI 工具读取约定            | `/ai/`                                            |

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

@@ -0,0 +1,18 @@
+# 理解这套系统
+
+第一次流程跑通后，再进入 Learn。这里解释 repoctl、monorepo、包、模板和底层工具之间的边界。
+
+## 核心概念
+
+- [repoctl 如何融入仓库](./repoctl-model)
+- [Monorepo 基础](./monorepo/)
+- [现代 npm 包](./packages/)
+- [模板体系](./monorepo/templates)
+
+## 工具
+
+[工具专题](/zh/learn/tools/)解释 pnpm、Turborepo、版本管理、hooks、暂存区校验和依赖自动化。
+
+## 建议阅读顺序
+
+先了解仓库模型，再按需要选择 monorepo 基础或包发布。需要可执行步骤时，回到[任务](/zh/tasks/)章节。

package/templates/vitepress/zh/{monorepo → learn/monorepo}/commands.md

@@ -2,9 +2,9 @@
 
 repoctl 现在是这套文档的主线。完整命令说明请阅读：
 
-- [repoctl 命令速查](../repoctl/commands.md)
-- [repoctl 模板与创建](../repoctl/templates.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [repoctl 命令速查](/zh/reference/commands)
+- [repoctl 模板与创建](/zh/reference/templates)
+- [repoctl 排障](/zh/tasks/troubleshooting)
 
 ## monorepo 知识点：为什么要统一命令入口
 

package/templates/vitepress/zh/{monorepo → learn/monorepo}/manage.md

@@ -2,7 +2,7 @@
 
 这一页是 repoctl 文档后面的知识库页面。它不再重新解释所有命令参数，而是解释：为什么这些命令能让 monorepo 日常管理变简单。
 
-如果你只想查命令，直接看 [repoctl 工作流与 CI](../repoctl/workflows.md) 或 [repoctl 命令速查](../repoctl/commands.md)。
+如果你只想查命令，直接看 [把校验加入 CI](/zh/tasks/ci) 或 [repoctl 命令速查](/zh/reference/commands)。
 
 ## 先记住默认工作流
 
@@ -237,7 +237,7 @@ pnpm test
 
 ## 继续阅读
 
-- [repoctl 工作流与 CI](../repoctl/workflows.md)
-- [repoctl 命令速查](../repoctl/commands.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [把校验加入 CI](/zh/tasks/ci)
+- [repoctl 命令速查](/zh/reference/commands)
+- [repoctl 排障](/zh/tasks/troubleshooting)
 - [发包与变更日志](./publish.md)

package/templates/vitepress/zh/{monorepo → learn/monorepo}/templates.md

@@ -2,8 +2,8 @@
 
 模板创建已经收敛到 repoctl 文档：
 
-- [repoctl 模板与创建](../repoctl/templates.md)
-- [repoctl 快速开始](../repoctl/getting-started.md)
+- [repoctl 模板与创建](/zh/reference/templates)
+- [repoctl 快速开始](/zh/start/install)
 
 ## monorepo 知识点：模板为什么重要
 

package/templates/vitepress/zh/{monorepo → learn/monorepo}/troubleshooting.md

@@ -2,8 +2,8 @@
 
 repoctl 排障文档已经集中到：
 
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 排障](/zh/tasks/troubleshooting)
+- [repoctl 命令速查](/zh/reference/commands)
 
 ## monorepo 知识点：先区分问题类型
 

package/templates/vitepress/zh/{why → learn/packages}/modern/index.md

@@ -14,7 +14,7 @@ outline: [2, 4]
 
 为此我们需要提升包的质量，具体的手段如下
 
-此代码的演变用例见 [examples](https://github.com/sonofmagic/repoctl/tree/main/templates/vitepress/why/examples)
+此代码的演变用例见 [examples](https://github.com/sonofmagic/repoctl/tree/main/templates/vitepress/learn/packages/examples)
 
 ## 确定包的模块入口点
 

package/templates/vitepress/zh/{why/index.md → learn/packages/modern-overview.md}

@@ -34,5 +34,5 @@ README.md     安装和使用契约
 
 ## 继续阅读
 
-- [什么是 npm 包](./what-is-npm-package.md)
-- [发布 npm 包](./publish-basic-npm-package.md)
+- [什么是 npm 包](/zh/learn/packages/)
+- [发布 npm 包](/zh/learn/packages/publish)

package/templates/vitepress/zh/{repoctl/index.md → learn/repoctl-model.md}

@@ -67,12 +67,12 @@ repoctl 把 monorepo 里最容易分散的动作收敛为五条主线：
 
 ## 新人和维护者的边界
 
-| 角色       | 推荐只记住                                                         | 需要深入时再看                                              |
-| ---------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
-| 新成员     | `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) |
+| 角色       | 推荐只记住                                                         | 需要深入时再看                                                                |
+| ---------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| 新成员     | `pnpm run repo:doctor`、`pnpm run repo:new`、`pnpm run repo:check` | [任务索引](/zh/tasks/)                                                        |
+| 包维护者   | `repo templates`、`repo new --template`、`repo check --full`       | [模板资产治理](/zh/reference/template-assets)                                 |
+| CI 维护者  | `repo doctor --strict`、`repo check --full`、`repo env support`    | [报告与自动化输出](/zh/tasks/reports)                                         |
+| 平台维护者 | `repo init`、`repo upgrade`、`repo config inspect`                 | [执行模型](/zh/reference/execution-model) 和 [配置文件](/zh/reference/config) |
 
 ## 命令入口
 
@@ -87,16 +87,16 @@ pnpm exec repoctl new
 
 ## 下一步
 
-- 第一次接入：[快速开始](./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)
+- 第一次接入：[安装并初始化](/zh/start/install)
+- 不知道用哪个命令：[任务索引](/zh/tasks/)
+- 理解 CLI 怎么执行：[执行模型](/zh/reference/execution-model)
+- 查命令参数：[命令速查](/zh/reference/commands)
+- 理解本地校验：[运行校验](/zh/tasks/checks)
+- 看 doctor 具体检查项：[doctor 诊断](/zh/start/diagnose)
+- 固化团队默认值：[配置文件](/zh/reference/config)
+- 看可创建的模板：[模板与创建](/zh/reference/templates)
+- 治理模板资产：[模板资产治理](/zh/reference/template-assets)
+- 接入 CI 和本地流程：[把校验加入 CI](/zh/tasks/ci)
+- 生成机器可读报告：[报告与自动化输出](/zh/tasks/reports)
+- 排查常见问题：[排障](/zh/tasks/troubleshooting)
+- 熟悉短命令：[命令别名](/zh/reference/aliases)

package/templates/vitepress/zh/{tools → learn/tools}/husky.md

@@ -15,7 +15,7 @@ repo check --staged
 repo check --full
 ```
 
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+继续看：[把校验加入 CI](/zh/tasks/ci)。
 
 ## 1. 什么是 Husky？
 

package/templates/vitepress/zh/{tools → learn/tools}/lint-staged.md

@@ -8,7 +8,7 @@ repo verify staged-typecheck packages/app/src/main.ts
 repo check --staged
 ```
 
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+继续看：[把校验加入 CI](/zh/tasks/ci)。
 
 ## 1. 什么是 lint-staged？
 

package/templates/vitepress/zh/{tools → learn/tools}/llms-txt.md

@@ -6,4 +6,4 @@ description: llms.txt 说明页已移动到独立的 AI 文档栏目。
 
 llms.txt 现在放在独立的 AI 文档栏目中维护。
 
-请阅读：[AI 文档入口：llms.txt](../ai/llms-txt.md)。
+请阅读：[AI 文档入口：llms.txt](/zh/ai/llms-txt)。

package/templates/vitepress/zh/{tools → learn/tools}/pnpm.md

@@ -24,7 +24,7 @@ pnpm check
 | `pnpm new`            | 通过根脚本运行 `repo new`     |
 | `pnpm check`          | 通过根脚本运行 `repo check`   |
 
-继续看：[repoctl 快速开始](../repoctl/getting-started.md)。
+继续看：[repoctl 快速开始](/zh/start/install)。
 
 ## 1. 什么是 pnpm？
 

package/templates/vitepress/zh/{tools → learn/tools}/turborepo.md

@@ -15,7 +15,7 @@ pnpm exec repo check --json --out reports/check-plan.json
 | 根脚本 `pnpm build` / `pnpm test` | 调用 `turbo run build` / `turbo run test` |
 | `turbo.json`                      | 定义任务依赖、缓存输出和执行策略          |
 
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+继续看：[把校验加入 CI](/zh/tasks/ci)。
 
 ## 1. 什么是 Turborepo？
 
@@ -147,17 +147,17 @@ npx turbo link
 
 ## Turborepo vs Lerna vs Nx
 
-| 特性 / 工具       | **Turborepo**                            | **Lerna**                                   | **Nx**                                          |
-| ----------------- | ---------------------------------------- | ------------------------------------------- | ----------------------------------------------- |
-| **定位**          | 高性能构建系统，专注缓存、并行和增量构建 | 最早的 JS monorepo 工具，专注版本管理和发布 | 企业级开发平台，集成构建、测试、代码生成等功能  |
+| 特性 / 工具       | **Turborepo**                            | **Lerna**                                   | **Nx**                                         |
+| ----------------- | ---------------------------------------- | ------------------------------------------- | ---------------------------------------------- |
+| **定位**          | 高性能构建系统，专注缓存、并行和增量构建 | 最早的 JS monorepo 工具，专注版本管理和发布 | 企业级开发平台，集成构建、测试、代码生成等功能 |
 | **核心优势**      | ⚡ 高速缓存（本地 & 远程）、并行任务执行 | 📦 包版本管理（独立/统一模式）、发布到 npm  | 🛠 丰富的插件生态、代码生成器、强大的依赖图分析 |
-| **依赖管理**      | 基于 pnpm/yarn/npm workspaces            | 基于 npm/yarn workspaces                    | 内置强依赖图（project graph）管理               |
-| **构建/缓存机制** | ✅ 智能缓存 & 增量构建                   | ❌ 无缓存机制                               | ✅ 强大缓存 & 增量构建（类似 Bazel）            |
-| **任务编排**      | pipeline 模式（`turbo.json`）            | 简单顺序执行                                | 高度可配置任务调度器（依赖感知）                |
-| **语言支持**      | 主要是 JS/TS 生态                        | 主要是 JS/TS 生态                           | 多语言支持（JS/TS/Go/Rust/Python 等）           |
-| **学习成本**      | ⭐⭐ 低（配置简洁，前端友好）            | ⭐⭐ 低（老牌工具，功能单一）               | ⭐⭐⭐ 高（功能多，配置复杂）                   |
-| **社区活跃度**    | 🚀 高（Vercel 维护，发展迅速）           | ⚠️ 中等（已过巅峰，更多用于发布流程）       | 🚀 高（企业应用广泛，社区和插件丰富）           |
-| **适合场景**      | 前端/全栈项目，追求构建速度 & CI/CD 效率 | 多包库发布（如 npm 包集合项目）             | 大型企业级 monorepo，跨语言/跨团队复杂项目      |
+| **依赖管理**      | 基于 pnpm/yarn/npm workspaces            | 基于 npm/yarn workspaces                    | 内置强依赖图（project graph）管理              |
+| **构建/缓存机制** | ✅ 智能缓存 & 增量构建                   | ❌ 无缓存机制                               | ✅ 强大缓存 & 增量构建（类似 Bazel）           |
+| **任务编排**      | pipeline 模式（`turbo.json`）            | 简单顺序执行                                | 高度可配置任务调度器（依赖感知）               |
+| **语言支持**      | 主要是 JS/TS 生态                        | 主要是 JS/TS 生态                           | 多语言支持（JS/TS/Go/Rust/Python 等）          |
+| **学习成本**      | ⭐⭐ 低（配置简洁，前端友好）            | ⭐⭐ 低（老牌工具，功能单一）               | ⭐⭐⭐ 高（功能多，配置复杂）                  |
+| **社区活跃度**    | 🚀 高（Vercel 维护，发展迅速）           | ⚠️ 中等（已过巅峰，更多用于发布流程）       | 🚀 高（企业应用广泛，社区和插件丰富）          |
+| **适合场景**      | 前端/全栈项目，追求构建速度 & CI/CD 效率 | 多包库发布（如 npm 包集合项目）             | 大型企业级 monorepo，跨语言/跨团队复杂项目     |
 
 ## 对比总结
 

package/templates/vitepress/zh/{repoctl → reference}/commands.md

@@ -161,8 +161,8 @@ repo skills sync --codex
 ## 继续阅读
 
 - [执行模型](./execution-model.md)
-- [校验链路](./checks.md)
-- [doctor 诊断](./doctor.md)
-- [工作流与 CI](./workflows.md)
-- [报告与自动化输出](./reports.md)
+- [运行校验](/zh/tasks/checks)
+- [doctor 诊断](/zh/start/diagnose)
+- [把校验加入 CI](/zh/tasks/ci)
+- [报告与自动化输出](/zh/tasks/reports)
 - [命令别名](./aliases.md)

package/templates/vitepress/zh/{repoctl → reference}/config.md

@@ -87,4 +87,4 @@ repo cfg i --markdown --redact --out reports/config.md
 - [执行模型](./execution-model.md)
 - [模板与创建](./templates.md)
 - [模板资产治理](./template-assets.md)
-- [报告与自动化输出](./reports.md)
+- [报告与自动化输出](/zh/tasks/reports)

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

@@ -0,0 +1,15 @@
+# 参考
+
+当你已经知道要做什么，只需要确认命令、参数、配置键或输出规则时，进入参考章节。
+
+## 命令与配置
+
+- [命令参考](./commands.md)
+- [配置文件](./config.md)
+- [执行模型](./execution-model.md)
+- [输出格式](./output.md)
+- [命令别名](./aliases.md)
+- [模板](./templates.md)
+- [受管模板资产](./template-assets.md)
+
+新手章节会先隐藏高级分组命令，等它们真正有用时再展开。这里记录完整命令面，不会改变 CLI 的命令名称。

package/templates/vitepress/zh/reference/output.md

@@ -0,0 +1,37 @@
+# 输出格式
+
+repoctl 可以输出到终端，也可以保存为供自动化使用的稳定产物。选择命令边界的输出格式，同一项任务就能服务人和 CI。
+
+## 终端
+
+默认输出适合人阅读，会显示计划、选中的命令和最终状态。
+
+## JSON
+
+其他工具需要结构化字段时使用 JSON：
+
+```bash
+repo check --full --dry-run --json --out reports/check-plan.json
+```
+
+后续 job 需要检查计划时，可以把文件作为 CI 产物保存。
+
+## Markdown
+
+代码评审和支持请求适合使用 Markdown：
+
+```bash
+repo env support --markdown --redact --out reports/support.md
+```
+
+`--redact` 会在分享前移除本地路径和敏感值。
+
+## 常见分支
+
+- 需要比较两次运行：分别写入不同文件，再比较 JSON。
+- 需要安全的排障包：使用 `repo env support --redact`。
+- 只需要命令计划：把 `--dry-run` 和目标输出格式一起使用。
+
+## 下一步
+
+完整支持流程请看[报告与输出任务](/zh/tasks/reports)。

package/templates/vitepress/zh/{repoctl → reference}/templates.md

@@ -2,7 +2,7 @@
 
 repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。CLI、脚手架和文档都复用同一份模板元数据。
 
-更偏维护者视角的模板元数据、健康检查和自定义模板说明见：[模板资产治理](./template-assets.md)。
+更偏维护者视角的模板元数据、健康检查和自定义模板说明见：[模板资产治理](/zh/reference/template-assets)。
 
 ## 内置模板
 
@@ -153,7 +153,7 @@ repo templates --check --json
 
 ## 继续阅读
 
-- [接入已有仓库](./adopt-existing.md)
-- [工作流与 CI](./workflows.md)
+- [接入已有 workspace](/zh/tasks/adopt-existing)
+- [把校验加入 CI](/zh/tasks/ci)
 - [配置文件](./config.md)
-- [模板资产治理](./template-assets.md)
+- [模板资产治理](/zh/reference/template-assets)

package/templates/vitepress/zh/start/choose-next.md

@@ -0,0 +1,14 @@
+# 选择下一项任务
+
+先按你要得到的结果选择任务。每个任务页都包含适用场景、前置条件、最小命令、预期输出、常见分支和下一步。
+
+| 目标                          | 进入                                           |
+| ----------------------------- | ---------------------------------------------- |
+| 把 repoctl 接入已有 workspace | [接入已有 workspace](/zh/tasks/adopt-existing) |
+| 创建包、应用、服务或文档站    | [创建包或应用](/zh/tasks/create-project)       |
+| 提交前运行本地校验            | [运行校验](/zh/tasks/checks)                   |
+| 保存评审或排障需要的输出      | [报告与输出](/zh/tasks/reports)                |
+| 把同一套流程接入 CI           | [把校验加入 CI](/zh/tasks/ci)                  |
+| 准备发布包                    | [发布包](/zh/tasks/release)                    |
+
+参数和分组命令请查看[命令参考](/zh/reference/commands)。想了解命令为什么这样执行，可以阅读[repoctl 执行模型](/zh/reference/execution-model)。

package/templates/vitepress/zh/{repoctl/doctor.md → start/diagnose.md}

@@ -83,4 +83,4 @@ repo doctor
 3. 然后补根脚本、hook 和 lint-staged。
 4. 最后整理 workspace patterns 与 tooling imports。
 
-如果不确定报告能否安全分享，使用 [报告与自动化输出](./reports.md) 里的 `--redact` 和 `env support`。
+如果不确定报告能否安全分享，使用 [报告与自动化输出](/zh/tasks/reports) 里的 `--redact` 和 `env support`。

package/templates/vitepress/zh/start/first-run.md

@@ -0,0 +1,39 @@
+# 第一次运行
+
+这是最小的完整 repoctl 流程。它先做一次可审查的变更，保存证据，再给出下一步。
+
+## 安装
+
+```bash
+pnpm add -D repoctl
+```
+
+## 初始化
+
+```bash
+pnpm exec repo init
+```
+
+接受写入前先检查计划。如果仓库已有自己的约定，先阅读接入指南，再决定是否替换文件。
+
+## 诊断
+
+```bash
+pnpm exec repo doctor
+```
+
+报告会检查仓库根目录、包管理器、workspace 结构、任务运行器、hooks 和发布元数据。先修复第一个阻塞项，再重新执行命令。
+
+## 规划校验
+
+```bash
+pnpm exec repo check --dry-run
+```
+
+这会列出 lint、类型检查、构建、测试和包检查将要执行的命令。确认计划符合仓库约定后，再执行完整校验。
+
+## 下一步
+
+- 新建仓库：[创建包或应用](/zh/tasks/create-project)。
+- 已有仓库：[接入已有 workspace](/zh/tasks/adopt-existing)。
+- 配置 CI：[把校验加入 CI](/zh/tasks/ci)。

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

@@ -0,0 +1,26 @@
+# 从这里开始
+
+如果你第一次使用 repoctl，请从这一节开始。最短的有效路径是安装 CLI，执行 `repo init`，再执行 `repo doctor`。
+
+## 选择第一次操作
+
+- 如果还没有运行过命令，阅读[安装并初始化](./install.md)。
+- 如果已经安装 repoctl，直接[运行第一次诊断](./diagnose.md)。
+- 得到诊断结果后，进入[选择下一项任务](./choose-next.md)。
+
+## repoctl 做什么
+
+repoctl 把常见 monorepo 工作收敛为一组容易记忆的命令：
+
+| 需求             | 命令                   |
+| ---------------- | ---------------------- |
+| 加入仓库约定     | `repo init`            |
+| 检查仓库健康状态 | `repo doctor`          |
+| 创建包或应用     | `repo new`             |
+| 执行前规划校验   | `repo check --dry-run` |
+
+CLI 支持 pnpm workspace，并能理解 Turborepo 任务图，但不会替代这两个工具。
+
+## 开始前确认
+
+你需要 Node.js 22.12 或更新版本，并确保 pnpm 在 PATH 中。从仓库根目录执行命令，这样 repoctl 才能读取 workspace 配置。

package/templates/vitepress/zh/{repoctl/getting-started.md → start/install.md}

@@ -1,4 +1,4 @@
-# 快速开始
+# 安装并初始化
 
 这一页按“把 repoctl 接进一个仓库”的顺序写。你不需要先理解所有工具，先让仓库能被诊断、能创建包、能跑提交前校验。
 
@@ -116,7 +116,7 @@ pnpm exec repo upgrade --yes
 
 ## 常见下一步
 
-- 已有仓库渐进接入：阅读 [接入已有仓库](./adopt-existing.md)。
-- 想固定默认模板：阅读 [配置文件](./config.md)。
-- 想查看所有模板：阅读 [模板与创建](./templates.md)。
-- 想把诊断结果发给同事：阅读 [排障与报告](./troubleshooting.md)。
+- 已有仓库渐进接入：阅读 [接入已有仓库](/zh/tasks/adopt-existing)。
+- 想固定默认模板：阅读 [配置文件](/zh/reference/config)。
+- 想查看所有模板：阅读 [模板与创建](/zh/reference/templates)。
+- 想把诊断结果发给同事：阅读 [排障](/zh/tasks/troubleshooting)。

package/templates/vitepress/zh/{repoctl → tasks}/adopt-existing.md

@@ -1,4 +1,30 @@
-# 接入已有仓库
+# 接入已有 workspace
+
+## 适用场景
+
+当 workspace 已经有脚本、hooks 或配置，需要保留现有约定并逐步接入 repoctl 时，使用这个任务。
+
+## 前置条件
+
+- 在 workspace 根目录执行命令。
+- 提交或暂存与本次接入无关的本地改动。
+- 确认 Node.js 22.12 或更新版本以及 pnpm 可用。
+
+## 最小命令
+
+```bash
+repo doctor --markdown --redact --out reports/baseline.md
+```
+
+## 预期输出
+
+报告会记录包管理器、workspace 结构、任务运行器、工具文件和发布设置，并隐藏本地路径。
+
+## 常见分支
+
+- 现有约定健康：保留它们，只补齐缺少的受管资产。
+- 文件已经由本地管理：使用 `repo upgrade --no-overwrite` 并检查差异。
+- tooling 分散在多个 loader：先统一 loader，再重新运行诊断。
 
 repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
 
@@ -130,6 +156,6 @@ pnpm exec repo init --yes
 
 ## 下一步
 
-- [工作流与 CI](./workflows.md)
-- [排障与报告](./troubleshooting.md)
-- [配置文件](./config.md)
+- [把校验加入 CI](/zh/tasks/ci)
+- [排障](/zh/tasks/troubleshooting)
+- [配置文件](/zh/reference/config)

package/templates/vitepress/zh/{repoctl → tasks}/checks.md

@@ -2,7 +2,33 @@
 description: 说明 repoctl check 和 verify 的校验模式、pre-commit、staged typecheck、pre-push 与 commit-msg 链路。
 ---
 
-# repoctl 校验链路
+# 运行校验
+
+## 适用场景
+
+提交、创建 pull request 或需要在本地复现 CI 计划前，使用这个任务。
+
+## 前置条件
+
+- 在 workspace 根目录运行 `repo doctor`。
+- 使用仓库锁定的 pnpm 版本安装依赖。
+- 先决定需要快速校验还是完整交付门禁。
+
+## 最小命令
+
+```bash
+repo check --dry-run
+```
+
+## 预期输出
+
+repoctl 会列出选中的任务和将要执行的确切命令。确认计划符合仓库策略后，再移除 `--dry-run`。
+
+## 常见分支
+
+- 只检查暂存文件：使用 `repo check --staged`。
+- CI 需要产物：加入 `--json --out reports/check-plan.json`。
+- 准备发布：快速校验通过后，再执行 `repo check --full`。
 
 `repo check` 是给人使用的统一入口，`repo verify` 是给 hook、CI 和脚本复用的底层入口。