@icebreakers/monorepo-templates 1.2.1 → 1.3.1

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/learn/packages/examples/2.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://repoctl.icebreaker.top/

package/templates/vitepress/zh/learn/packages/examples/3.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://repoctl.icebreaker.top/

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/learn/packages/modern-overview.md

@@ -0,0 +1,38 @@
+# 包的演进
+
+一个可发布的 npm 包不只是源代码目录。消费者依赖它的运行时格式、类型声明、入口点、发布文件和兼容性承诺。这里按这些公开边界整理现代包的基础知识。
+
+## 先从消费者开始
+
+在选择打包器或模块格式前，先回答：
+
+- 消费者使用 ESM、CommonJS，还是两者都需要？
+- 包发布运行时代码、类型、CLI、配置预设还是资源？
+- 需要支持哪些 Node 版本？
+- 对外只暴露一个入口，还是需要明确的子路径？
+
+这些答案定义了包的边界。工具链应该实现边界，而不是替代边界决策。
+
+## 推荐目录
+
+```text
+src/          源代码
+dist/         生成的 ESM、CommonJS 与声明文件
+package.json  公开 metadata 与 exports 映射
+README.md     安装和使用契约
+```
+
+使用 `files` 控制发布内容，并在发布前执行 `npm pack --dry-run` 检查实际 tarball。
+
+## 专题
+
+- [ESM 与 CommonJS](./modern/esm-vs-cjs.md)
+- [类型声明](./modern/dts.md)
+- [包入口](./modern/package-entry-points.md)
+- [构建工具](./modern/bundlers.md)
+- [TypeScript](./modern/typescript.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？
 

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 和脚本复用的底层入口。
 

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

@@ -1,4 +1,30 @@
-# 工作流与 CI
+# 把校验加入 CI
+
+## 适用场景
+
+当本地命令已经稳定，需要在每个 pull request 或分支上执行同一套仓库策略时，使用这个任务。
+
+## 前置条件
+
+- 已经生成通过检查的 `repo check --dry-run` 计划。
+- CI runner 具备 Node.js、pnpm 和仓库锁文件。
+- 发布或发版 job 使用非交互凭据。
+
+## 最小命令
+
+```bash
+repo check --full --json --out reports/check-plan.json
+```
+
+## 预期输出
+
+CI 会得到稳定的计划，并可以把 JSON 或 Markdown 报告作为 artifact 上传。同一条命令也可以在本地执行。
+
+## 常见分支
+
+- pull request 需要快速门禁：使用 `repo check --staged` 或仓库的 pre-commit 模式。
+- main 分支需要完整门禁：使用 `repo check --full`。
+- 发布 job 需要版本计划：发布前执行 `repo release --dry-run`。
 
 repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、脚本、编辑器用的可保存输出。
 
@@ -89,13 +115,13 @@ repo ws ls --json --out reports/workspaces.json
 
 ## 推荐流水线拆分
 
-| 阶段 | 命令                                                            | 失败后先看                           |
-| ---- | --------------------------------------------------------------- | ------------------------------------ |
-| 安装 | `pnpm install --frozen-lockfile`                                | lockfile、Node、pnpm 版本            |
-| 诊断 | `repo doctor --strict`                                          | [doctor 诊断](./doctor.md)           |
-| 计划 | `repo check --full --json --out reports/check-plan.json`        | [报告与自动化输出](./reports.md)     |
-| 执行 | `repo check --full`                                             | 失败的 root script 或 workspace 任务 |
-| 留证 | `repo env support --markdown --redact --out reports/support.md` | CI artifact                          |
+| 阶段 | 命令                                                            | 失败后先看                            |
+| ---- | --------------------------------------------------------------- | ------------------------------------- |
+| 安装 | `pnpm install --frozen-lockfile`                                | lockfile、Node、pnpm 版本             |
+| 诊断 | `repo doctor --strict`                                          | [doctor 诊断](/zh/start/diagnose)     |
+| 计划 | `repo check --full --json --out reports/check-plan.json`        | [报告与自动化输出](/zh/tasks/reports) |
+| 执行 | `repo check --full`                                             | 失败的 root script 或 workspace 任务  |
+| 留证 | `repo env support --markdown --redact --out reports/support.md` | CI artifact                           |
 
 早期项目可以把计划和执行合并。成熟项目建议保留 `reports/`，方便失败时复盘实际执行路径。
 
@@ -110,9 +136,44 @@ repo ws ls --json --out reports/workspaces.json
 | 输出给脚本         | `--json --out <file>`                              |
 | 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
 
+## 文档 Worker
+
+repoctl 文档通过名为 `repoctl-docs` 的 Cloudflare Worker 部署。VitePress 只生成静态资产，Workers Static Assets 直接提供这些文件，因此不需要应用 handler，也不声明 `ASSETS` binding。
+
+### Workers Builds 配置
+
+| 配置项     | 值                                                      |
+| ---------- | ------------------------------------------------------- |
+| 仓库根目录 | 仓库根目录                                              |
+| 生产分支   | `main`                                                  |
+| 构建命令   | `pnpm --filter @icebreakers/website build`              |
+| 生产部署   | `pnpm --filter @icebreakers/website run deploy`         |
+| 非生产部署 | `pnpm --filter @icebreakers/website run deploy:preview` |
+
+构建命令会先校验双语页面，再由 VitePress 生成 `.vitepress/dist`。Worker 配置会为不存在的路由返回生成后的 `404.html`，并继续读取 `public/_redirects`，兼容旧的 `/en/*` 链接。
+
+### 预览、发布与回滚
+
+修改生产部署前，先完成本地验证：
+
+```bash
+pnpm --filter @icebreakers/website build
+pnpm --filter @icebreakers/website run deploy:dry-run
+pnpm --filter @icebreakers/website exec wrangler dev
+```
+
+非生产 Workers Builds 上传预览版本。验证通过后再执行生产部署。需要回滚时，先查看版本历史，再选择最近的稳定版本：
+
+```bash
+pnpm --filter @icebreakers/website exec wrangler versions list
+pnpm --filter @icebreakers/website exec wrangler rollback <VERSION_ID>
+```
+
+`repoctl.icebreaker.top` 是唯一 canonical custom domain。Cloudflare Redirect Rules 把 `repo.icebreaker.top/*` 和 `monorepo.icebreaker.top/*` 永久跳转到主域名，同时保留路径和查询参数。
+
 ## 下一步
 
-- 查所有参数：[命令速查](./commands.md)
-- 理解校验链路：[校验链路](./checks.md)
-- 生成排障包：[报告与自动化输出](./reports.md)
-- 看短命令：[命令别名](./aliases.md)
+- 查所有参数：[命令速查](/zh/reference/commands)
+- 理解本地校验：[运行校验](/zh/tasks/checks)
+- 生成排障包：[报告与自动化输出](/zh/tasks/reports)
+- 看短命令：[命令别名](/zh/reference/aliases)

package/templates/vitepress/zh/tasks/create-project.md

@@ -0,0 +1,37 @@
+# 创建包或应用
+
+当 workspace 已经准备好，需要创建新的包、应用、服务、CLI 或文档站时，使用这个任务页。
+
+## 前置条件
+
+- 在 workspace 根目录运行过 `repo doctor`。
+- 确认包名和目标目录。
+- 使用 `repo templates` 查看可用模板键。
+
+## 最小命令
+
+```bash
+repo new <name> --template <template>
+```
+
+例如：
+
+```bash
+repo new shared-config --template package
+```
+
+只想查看文件计划时，加入 `--dry-run`，不会写入文件。
+
+## 预期结果
+
+repoctl 会输出选中的模板、目标目录和将要创建的文件。确认后，新项目加入 workspace，包元数据可以直接进入仓库校验。
+
+## 常见分支
+
+- 模板键不存在：先运行 `repo templates`，选择已安装的键。
+- 目标目录已存在：换一个名称，或检查现有项目后再决定是否覆盖。
+- 需要自定义共享文件：先创建项目，再通过[受管模板资产](/zh/reference/template-assets)同步公共文件。
+
+## 下一步
+
+运行[校验](/zh/tasks/checks)，再把新项目加入 [CI 工作流](/zh/tasks/ci)。

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

@@ -1,4 +1,4 @@
-# 按场景选命令
+# 任务索引
 
 如果你不确定该用哪个 repoctl 命令，先从这一页开始。
 
@@ -17,7 +17,7 @@ pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
-继续看：[快速开始](./getting-started.md)。
+继续看：[安装并初始化](/zh/start/install)。
 
 ## 我要把 repoctl 接入旧仓库
 
@@ -29,7 +29,7 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```
 
-继续看：[接入已有仓库](./adopt-existing.md)。
+继续看：[接入已有 workspace](/zh/tasks/adopt-existing)。
 
 ## 我要创建新包或应用
 
@@ -45,7 +45,7 @@ pnpm exec repo new docs --template vitepress --dry-run
 pnpm run repo:new -- sdk --template tsdown
 ```
 
-继续看：[模板与创建](./templates.md)。
+继续看：[模板与创建](/zh/reference/templates)。
 
 ## 我要提交前自查
 
@@ -62,7 +62,7 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo check --markdown --redact --out reports/check-plan.md
 ```
 
-继续看：[工作流与 CI](./workflows.md)。
+继续看：[把校验加入 CI](/zh/tasks/ci)。
 
 ## 我要调试 CI 或同事机器问题
 
@@ -72,7 +72,7 @@ pnpm exec repo env support --markdown --redact --out reports/support.md
 pnpm exec repo env snapshot --json --out reports/snapshot.json
 ```
 
-继续看：[排障与报告](./troubleshooting.md)。
+继续看：[排障](/zh/tasks/troubleshooting)。
 
 ## 我要同步模板标准资产
 
@@ -105,7 +105,7 @@ pnpm exec repo config inspect
 pnpm exec repo cfg i --json --out reports/config.json
 ```
 
-继续看：[配置文件](./config.md)。
+继续看：[配置文件](/zh/reference/config)。
 
 ## 我要写更短的命令
 
@@ -116,4 +116,4 @@ repo e support --markdown --redact
 repo cfg i
 ```
 
-继续看：[命令别名](./aliases.md)。
+继续看：[命令别名](/zh/reference/aliases)。