@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/knowledge/index.md

@@ -1,50 +1,26 @@
 ---
-description: repoctl 文档站的知识库入口，汇总 monorepo 管理、现代 npm 包和 JavaScript 模块化基础。
+outline: deep
 ---
 
-# 知识库
+# Knowledge Base
 
-知识库用于解释 repoctl 背后的工程背景。这里不放命令速查，而是回答为什么要这样组织仓库、包、构建和发布流程。
+This section explains the engineering decisions behind repoctl rather than only listing commands.
 
-## 1. monorepo 主题
+## Monorepo Topics
 
-| 页面                                               | 适合解决的问题                     |
-| -------------------------------------------------- | ---------------------------------- |
-| [为什么往 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)    | 排查依赖、构建、类型和发布问题     |
+- [Why Monorepo](../monorepo/index.md)
+- [Managing A Monorepo](../monorepo/manage.md)
+- [Publishing and Changelogs](../monorepo/publish.md)
+- [Command Reference](../monorepo/commands.md)
+- [Template Systems](../monorepo/templates.md)
+- [Troubleshooting](../monorepo/troubleshooting.md)
 
-## 2. 现代 npm 包主题
+## Modern Package Topics
 
-| 页面                                                   | 适合解决的问题                     |
-| ------------------------------------------------------ | ---------------------------------- |
-| [如何复用 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)                   | 汇总类型、入口、模块格式和构建工具 |
+- [Reusing JavaScript Code](../why/how-to-reuse-js-code.md)
+- [JavaScript Module Extensions](../why/js-cjs-mjs.md)
+- [What Is An npm Package?](../why/what-is-npm-package.md)
+- [Publishing An npm Package](../why/publish-basic-npm-package.md)
+- [Modern Package Guide](../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)        |
+Start with the repoctl guide when you need an action. Use this knowledge base when you need to understand the tradeoffs behind that action.

package/templates/vitepress/monorepo/commands.md

@@ -1,21 +1,16 @@
-# 命令速查
+# Monorepo Command Reference
 
-repoctl 现在是这套文档的主线。完整命令说明请阅读：
+| Task                           | Command                |
+| ------------------------------ | ---------------------- |
+| Initialize repository defaults | `repo init`            |
+| Diagnose workspace state       | `repo doctor`          |
+| Create a package or app        | `repo new`             |
+| Preview or run verification    | `repo check`           |
+| Synchronize managed assets     | `repo upgrade`         |
+| List workspace packages        | `repo ws ls`           |
+| Initialize tooling configs     | `repo tg init --all`   |
+| Run pre-push verification      | `repo verify pre-push` |
 
-- [repoctl 命令速查](../repoctl/commands.md)
-- [repoctl 模板与创建](../repoctl/templates.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+One command layer matters because scripts, documentation, CI, and contributor expectations otherwise drift independently. repoctl keeps task names stable while pnpm and Turborepo continue to perform dependency installation and task execution.
 
-## monorepo 知识点：为什么要统一命令入口
-
-monorepo 的难点通常不是“能不能跑某个工具”，而是团队成员是否能稳定地用同一套入口完成日常动作。
-
-repoctl 把命令分成三层：
-
-| 层级     | 示例                                         | 适合场景             |
-| -------- | -------------------------------------------- | -------------------- |
-| 根脚本   | `pnpm run repo:doctor` / `pnpm run repo:new` | 日常开发和团队教程   |
-| 主 CLI   | `pnpm exec repo doctor`                      | CI、脚本、排障和文档 |
-| 分组命令 | `repo ws ls` / `repo env support`            | 维护者和自动化       |
-
-保留这个旧页面，是为了让已有链接继续可用，同时把读者导向新的 repoctl 命令文档。
+See the complete [repoctl command reference](../repoctl/commands.md).

package/templates/vitepress/monorepo/index.md

@@ -1,115 +1,37 @@
-# 为什么往 monorepo 方向演进
+# Why Monorepo
 
-选择 monorepo，不是为了“更先进”，而是为了把多包协作里最常见的重复劳动砍掉。
+This project uses monorepo practices because multiple packages, applications, CLIs, and docs sites usually share the same engineering rules.
 
-当你的仓库里同时存在应用、类库、CLI、文档站，或者多个团队要共享同一套类型、配置、脚手架时，monorepo 的收益会很快超过它的管理成本。
+The goal is not to make the repository look more complex. The goal is to reduce repeated setup work.
 
-## 这套模板解决的真实问题
+## Problems A Monorepo Solves
 
-### 1. 依赖和脚本不再分散
+### Shared Tooling
 
-在 polyrepo 里，最常见的问题不是代码本身，而是：
+In separate repositories, each package tends to maintain its own lint, typecheck, test, release, and commit setup. That makes upgrades slow and inconsistent.
 
-- 每个仓库都要单独装依赖
-- 每个仓库都维护一套 lint / typecheck / test 脚本
-- 同样的工具链升级要重复做很多次
-- 团队成员很难判断哪个仓库的规范才是“当前标准”
+In a pnpm workspace, those rules can be centralized at the root and reused by every package.
 
-在 monorepo 里，这些东西可以收敛到一个根目录。
+### Atomic Cross-Package Changes
 
-### 2. 跨包改动可以原子提交
+When one type change affects a library, an app, and a CLI, a monorepo lets you update, verify, review, and revert that change together.
 
-如果一个接口变更同时影响：
+### Incremental Builds
 
-- `packages/types`
-- `packages/sdk`
-- `apps/web`
-- `apps/server`
+pnpm handles workspace dependencies. Turborepo coordinates tasks and caching. Together they make it practical to run build, lint, test, and typecheck flows across many packages.
 
-那么在 monorepo 里，一次提交就能把它们一起改完、一起验证、一起回滚。对重构和版本审计都更友好。
+## Where repoctl Fits
 
-### 3. 构建与测试更容易增量化
+repoctl adds the missing workflow layer:
 
-`pnpm` 负责 workspace 依赖管理，`turborepo` 负责任务编排和缓存，结果就是：
+- `repo init` aligns root scripts and standard files.
+- `repo doctor` checks whether the workspace is ready.
+- `repo new` creates packages and apps from known templates.
+- `repo check` previews and runs local verification.
+- `repo upgrade` syncs standard assets as the template evolves.
 
-- 没改动的包不需要重复构建
-- CI 可以按依赖图只跑受影响任务
-- 大仓库也能保持比较稳定的反馈速度
+## Keep Reading
 
-## 这套模板的立场
-
-这不是一个“什么都能配”的框架，而是一套偏实战、偏收敛的默认值：
-
-| 维度     | 默认选择                                |
-| -------- | --------------------------------------- |
-| 包管理   | `pnpm workspace`                        |
-| 任务编排 | `turborepo`                             |
-| 语言     | TypeScript 优先                         |
-| 校验链路 | ESLint + Stylelint + typecheck + Vitest |
-| 提交规范 | Husky + lint-staged + commitlint        |
-| 发包     | pnpm versioning                         |
-| 命令入口 | `repo` 为主，`repoctl` 为完整包名入口   |
-
-这些选择的目的只有一个：减少“每个项目重新想一遍”的成本。
-
-## 什么时候适合用 monorepo
-
-下面这些情况，适合直接上：
-
-- 你要同时维护多个 npm 包
-- 你有前后端、CLI、文档站共用一套类型或工具
-- 你希望升级脚本、工程化配置时一次同步全仓
-- 你有持续重构、跨包联动改动的需求
-
-下面这些情况，不一定值得上：
-
-- 只有一个很小的应用，没有共享代码需求
-- 团队还没有接受统一规范的准备
-- 构建链路本身还不稳定，先统一仓库只会放大问题
-
-## 模板提供的补位能力
-
-单纯有 monorepo 还不够，真正难的是“如何让它易用”。这个模板多补了三层东西：
-
-### 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)
+- [repoctl Overview](../repoctl/index.md)
+- [Command Reference](../repoctl/commands.md)
+- [Templates](../repoctl/templates.md)

package/templates/vitepress/monorepo/manage.md

@@ -1,243 +1,31 @@
-# 如何管理 monorepo
+# Managing A Monorepo
 
-这一页是 repoctl 文档后面的知识库页面。它不再重新解释所有命令参数，而是解释：为什么这些命令能让 monorepo 日常管理变简单。
+repoctl gives a pnpm and Turborepo workspace a predictable operating model without hiding the underlying tools.
 
-如果你只想查命令，直接看 [repoctl 工作流与 CI](../repoctl/workflows.md) 或 [repoctl 命令速查](../repoctl/commands.md)。
-
-## 先记住默认工作流
+## Daily Workflow
 
 ```bash
 pnpm install
-pnpm exec repo doctor
-pnpm run repo:new
+pnpm run repo:doctor
+pnpm run repo:new -- sdk
 pnpm run repo:check
 pnpm build
-```
-
-大多数场景里，这已经够了。
-
-如果你在接入一个旧仓库，再多加一步：
-
-```bash
-pnpm exec repo init
-```
-
-这个工作流背后的顺序是：
-
-| 阶段 | 目标                                             |
-| ---- | ------------------------------------------------ |
-| 安装 | 让 workspace 依赖和本地包链接完整                |
-| 诊断 | 先确认仓库结构、Node、脚本、配置和提交链路可用   |
-| 创建 | 用模板生成新包，减少手写 package metadata 和配置 |
-| 校验 | 在提交前复现默认 hook 和 workspace typecheck     |
-| 构建 | 最后再跑更重的全仓任务                           |
-
-## 命令分层
-
-这套模板故意把入口做得很少。
-
-### 第一层：根脚本
-
-这是最推荐的入口：
-
-```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 什么时候用
+Use root `repo:*` scripts in team documentation, direct `repo` commands in automation, and grouped commands such as `repo ws ls` when maintainers need finer control.
 
-如果你只是要使用默认 CLI，不需要直接碰 `@icebreakers/monorepo/tooling`。
+## Command Boundaries
 
-只有下面两种情况建议直接使用：
+- `doctor` reads repository state and reports drift.
+- `check` previews or runs verification.
+- `upgrade` synchronizes managed assets while preserving custom files by default.
+- `new` creates packages and applications from the shared template registry.
 
-- 你要在仓库里手写 tooling wrapper 配置
-- 你在维护这套 CLI / 模板本身
+## Configuration
 
-其余大多数团队，停留在 `repoctl.config.ts` 这一层就够了。
+Store team defaults in `repoctl.config.ts`. Explicit CLI options override configuration, which keeps CI reproducible without making local interactive use verbose.
 
-## 继续阅读
+## Dependency and Build Guidance
 
-- [repoctl 工作流与 CI](../repoctl/workflows.md)
-- [repoctl 命令速查](../repoctl/commands.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [发包与变更日志](./publish.md)
+Keep shared dependency versions aligned through pnpm workspace policy. Let Turborepo model task dependencies and caching. Build publishable packages before testing their delivery artifacts.

package/templates/vitepress/monorepo/publish.md

@@ -1,87 +1,32 @@
-# monorepo 发包与变更日志
+# Publishing and Changelogs
 
-这套模板默认使用 pnpm 原生 versioning。它保留 Changesets 格式的变更意图，同时把版本计算、依赖传播、changelog 和发布收进 pnpm 本身。
+repoctl coordinates release tasks with pnpm versioning. It does not replace the registry, GitHub Actions, or package build scripts.
 
-## 日常流程
-
-先完成质量校验，再记录变更：
+## Development Flow
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm tsd
-pnpm test
 pnpm change
 pnpm change status
+repo release stable prepare
+repo release stable publish
 ```
 
-变更意图文件放在 `.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，发布操作可以安全重试。
+Change intents record the affected package and release level. The release preparation step updates versions and repository changelogs; publish sends built packages to the configured registry.
 
-## Workspace versioning 配置
+## Versioning Configuration
 
-根 `pnpm-workspace.yaml` 中的关键配置：
+Fixed groups and repository changelog storage live in `pnpm-workspace.yaml`. `repo doctor` reports missing or legacy release configuration.
 
-```yaml
-versioning:
-  fixed:
-    - ['@icebreakers/monorepo', repoctl]
-  ignore:
-    - '@icebreakers/client'
-  changelog:
-    storage: repository
-```
-
-`fixed` 保证组内包同版本；`ignore` 排除 private 包；`repository` 让 changelog 作为源代码提交。
-
-## Prerelease lanes
-
-预发布使用 pnpm lanes：
+## Prerelease 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
+repo release pre enter beta
+repo release pre publish
+repo release pre exit
 ```
 
-预发布版本为 `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 的边界
+Supported lane names include `alpha`, `beta`, `rc`, and `next`.
 
-生成的 GitHub Actions 只保留环境准备和一个 `pnpm exec repo release ci` 调用。
-repoctl 负责发布前 build/lint/test、lane 一致性检查、Release PR、npm
-发布、package tag 与 GitHub Release；pnpm 负责变更意图、版本计算、changelog、
-ledger 和 registry 发布细节。
+## Recovery
 
-存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`，后续使用
-`pnpm exec repo upgrade --yes` 即可跟随 repoctl 升级。未标记的自定义 release
-workflow 默认不会被覆盖，确认后可使用 `repo upgrade --overwrite-release`。
+Use the publish-unpublished release mode to recover versions that were prepared but not published. Inspect the generated report before retrying a partial release.

package/templates/vitepress/monorepo/templates.md

@@ -1,21 +1,14 @@
-# 模板速查
+# Template Systems
 
-模板创建已经收敛到 repoctl 文档：
+Templates make repository conventions executable. repoctl ships internal source workspaces for libraries, Vue components, apps, services, documentation sites, and CLIs.
 
-- [repoctl 模板与创建](../repoctl/templates.md)
-- [repoctl 快速开始](../repoctl/getting-started.md)
+```bash
+repo templates
+repo templates --category library
+repo new sdk --template tsdown --dry-run
+repo templates --check
+```
 
-## monorepo 知识点：模板为什么重要
+The publishable `@icebreakers/monorepo-templates` package owns the registry and packaged assets. Individual `templates/*` workspaces are private and are not release units.
 
-当仓库里存在多种产物时，模板能把重复选择前置成稳定默认值：
-
-| 产物          | 常见目录                 | 关注点                         |
-| ------------- | ------------------------ | ------------------------------ |
-| TypeScript 库 | `packages/*`             | exports、types、构建和 tsd     |
-| Vue 组件库    | `packages/*`             | SFC、样式校验、类型声明        |
-| 应用          | `apps/*`                 | dev、build、部署资产           |
-| 服务          | `apps/*`                 | API 入口、运行时类型、环境变量 |
-| 文档站        | `apps/*`                 | VitePress 配置、导航、内容结构 |
-| CLI           | `apps/*` 或 `packages/*` | bin 入口、参数解析、发布       |
-
-repoctl 的 `repo templates` 和 `repo new` 负责把这些约定落实到文件系统。
+See [Templates](../repoctl/templates.md) and [Template Asset Management](../repoctl/template-assets.md).

package/templates/vitepress/monorepo/troubleshooting.md

@@ -1,20 +1,17 @@
-# 常见问题排障
+# Monorepo Troubleshooting
 
-repoctl 排障文档已经集中到：
+Start by identifying the problem class: workspace discovery, dependency installation, task orchestration, repository policy, or release state.
 
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [repoctl 命令速查](../repoctl/commands.md)
+```bash
+repo doctor
+repo env support --markdown --redact --out reports/support.md
+repo check --full --dry-run
+pnpm change status
+```
 
-## monorepo 知识点：先区分问题类型
+- Workspace discovery failures usually point to `pnpm-workspace.yaml` patterns.
+- Missing task output or cache behavior belongs to Turbo task configuration.
+- Tooling drift belongs to managed config and `repo upgrade`.
+- Release failures require checking both versioning state and registry publication.
 
-排障前先判断问题属于哪一类：
-
-| 类型           | 先看什么                              | 常用命令                                |
-| -------------- | ------------------------------------- | --------------------------------------- |
-| 仓库结构问题   | 根目录、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 分区。
+Do not overwrite custom files until the diagnostic report and planned changes are understood.