@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/thinking.md

@@ -1,88 +1,7 @@
-# 我对 monorepo 的一些思考
+# Project Evolution
 
-## 前言
+This repository began as a reusable monorepo template. It has since evolved into repoctl: a task-first CLI for initializing, diagnosing, creating, validating, upgrading, and releasing pnpm and Turborepo monorepos.
 
-最近在自己的新项目中，我创建并使用了 [monorepo-template](https://github.com/sonofmagic/monorepo-template) 模板，并不断地做了不少改进。
+Templates remain an important capability, but they are now private source workspaces packaged through `@icebreakers/monorepo-templates`, not the product identity or independent release units.
 
-在此，我想借此机会分享一下这个模板的演变过程，以及我对 `monorepo` 的一些思考。
-
-## 它的由来
-
-为了应对越来越多的发包场景，我创建了 [npm-lib-template](https://github.com/sonofmagic/npm-lib-template) 模板
-
-这是一个 `git` 单仓单 `npm` 包模板，使用 `rollup` 进行打包，然后再发布到 `npm` 和 `github`
-
-然而，在后续开发中，我发现单仓库的模式在某些场景下难以应对。
-
-例如，当需要引用其他自己的包，进行单元测试并再次发包时，这时候往往要在多个项目之间进行来回的切换更改，管理复杂度会迅速上升。
-
-`git submodule` 也是另外一条路子，但是我对每次都要同步 `hash` 感到深恶痛绝，遂放弃 (不过某些极其特殊场景的实现，还是只能利用这个功能)。
-
-因此，我决定要创建一个 [monorepo 项目模板](https://github.com/sonofmagic/monorepo-template) ，以应对这些需求。
-
-## 技术选型
-
-### 管理工具
-
-在 `monorepo` 的管理上，我选择了 `pnpm` 和 `turborepo` 这对组合，原因很简单：它们都非常快。
-
-- `pnpm` 又可以节省磁盘空间，又能够链接自特定的内容寻址存储库，是为快也
-- `turborepo` 有构建缓存，是为快也 `too`.
-
-### 语言与打包
-
-我选择使用纯 `TypeScript` 来编写所有类库项目，并统一使用 `tsdown` 进行打包，默认输出格式为 `cjs` 和 `esm`，并利用 `package.json` 中的 `exports` 字段进行分发。
-
-### 直接调试
-
-在直接调试时，我抛弃了 `dist` + `sourcemap` 的调试方式，使用了 `tsx`，它非常适合调试 `TypeScript` 编写的 `CLI` 项目。
-
-### 测试框架
-
-测试方面，我选择了 `vitest`。
-
-它不仅速度快，还很好地支持 `cjs`、`esm` 和 `TypeScript`，同时也适合 `monorepo` 项目。你可以利用 `turbo` 来执行单个的 `vitest` 任务，也可以利用 `vitest.workspace` 来进行多任务测试。
-
-最初我使用的是 `jest` + `ts-jest`，但它对多格式的混合模块的支持不够理想，最终我选择了 `vitest`。
-
-### 代码规范与质量控制
-
-为了保持代码质量，我使用了 `eslint` 和 `stylelint`，并基于自己的配置包 `@icebreakers/eslint-config` 和 `@icebreakers/stylelint-config` 来进行代码格式化和规范化。
-
-我还为 `.vscode` 配置了一些推荐插件和编辑器选项。
-
-此外，通过 `husky` 添加了 `git hook`，配合 `lint-staged` 对提交的代码进行校验。与 `commitlint` 结合使用，以确保 `git` 提交信息符合规范。
-
-### 本地引用与发包替换
-
-利用 `publishConfig` 会在发包的时候替换 `package.json` 字段的方式，在本地包相互引用的时候，都使用 `Typescript` 源文件的方式导出，在 `publishConfig` 里定义的导出为，真正在不同环境中，指向 `dist` 中不同格式的产物地址。
-
-通过这种方式，可以大大加速整个 `monorepo` 的开发测试速度，避免反复通过 `watch` 来构建 `dist` 和 `sourcemap`，也避免一构建出产物，对应的 `Typescript` 文件，就报错的问题。
-
-### 发包流程
-
-我采用了 `changesets`，它在 `monorepo` 环境下发布非常方便。功能非常的多，具体可以查看官方文档。
-
-### Github 相关配置
-
-在 `.github` 目录下，我提供了默认的 `CI/CD` 流程配置，以及用户提交 `issue` 时的模板。经过少量配置后，就可以实现自动发布 `npm` 包、创建 `git tag` 以及生成 `GitHub release`。
-
-此外，模板里还有许多为 `GitHub` 显示优化的 `md` 文档。
-
-## 部署
-
-文档网站通过 `netlify.toml` 配置部署在 `Netlify` 上。最初我使用的是 `Vercel`，但由于**国内**访问速度的原因，最终迁移到了 `Netlify`。
-
-而且由于我是开源项目贡献者的原因，`Netlify` 为我 `免费` 提供了 `Pro` 版本的计划 (通常这需要 `$19/per member/month`)
-
-感谢 `Netlify`! 爱你❤️😍。
-
-如果看到这里的哥们，你也有一定影响力的开源项目，也可以通过下方的链接申请。
-
-https://www.netlify.com/legal/open-source-policy/
-
-## 总结
-
-从单仓到 `monorepo` 的转变不仅仅是对工具的选择，更是对项目管理模式的优化。通过采用合适的工具链，能够更高效地管理多包项目的同时，利用 `CI/CD` 确保代码的质量和发布的顺畅。
-
-希望这些思考对你有所帮助，也欢迎大家提出各种建议和意见。
+See the [repoctl overview](./repoctl/index.md) for the current architecture and public entrypoints.

package/templates/vitepress/tools/changeset.md

@@ -1,98 +1,25 @@
-# Changesets
+# pnpm Versioning
 
-[Changesets](https://github.com/changesets/changesets)。它帮助你在 **monorepo** 或多包项目中更有条理地维护变更日志（changelog）、版本号升级策略以及自动化发布流程。
+This repository uses pnpm change intents and workspace versioning for releases.
 
-在 repoctl 体系里，Changesets 负责“版本和发布”，repoctl 负责“发布前仓库是否健康”。
+## Daily Development
 
 ```bash
-pnpm exec repo doctor --strict
-pnpm exec repo check --full
-pnpm changeset
-pnpm exec repo release stable
+pnpm change
+pnpm change status
 ```
 
-继续看：[monorepo 发包与变更日志](../monorepo/publish.md)。
+Choose every publishable package whose public behavior changed and record the correct patch, minor, or major level. Private template workspaces are not release units.
 
-## 1. 什么是 Changeset？
-
-- **核心思想**：每一次改动，不直接修改 `package.json` 里的版本号，而是通过写一个 `changeset` 文件（通常放在 `.changeset` 文件夹下）。
-- **作用**：
-  - 记录每次改动影响了哪些包（哪些需要 bump 版本）。
-  - 指定改动类型（`patch`、`minor`、`major`）。
-  - 自动生成 **Changelog**。
-  - 自动修改 `package.json` 的版本号。
-  - 与 CI/CD 集成后，可以实现一键自动发版。
-
-## 2. 如何使用 Changesets？
-
-### 安装
+## Release
 
 ```bash
-npm install --save-dev @changesets/cli
+repo release stable prepare
+repo release stable publish
 ```
 
-### 初始化
-
-```bash
-npx changeset init
-```
-
-会生成一个 `.changeset` 文件夹，里面包含配置文件。
-
-### 添加变更
-
-当你完成某个功能或修复后，运行：
-
-```bash
-npx changeset
-```
-
-它会问：
-
-1. 哪些包受影响？
-2. 这是 **patch**（补丁）、**minor**（新功能）、还是 **major**（重大变更）？
-3. 变更的描述是什么？
-
-这会生成一个类似这样的文件：
-
-```yaml
-# .changeset/sweet-pandas-sing.md
----
-my-package: patch
----
-
-修复了登录时的 bug
-```
-
-### 应用版本更新
-
-当积累了多个 changeset 后，可以执行：
-
-```bash
-npx changeset version
-```
-
-它会根据 changeset 文件：
-
-- 更新对应包的版本号。
-- 生成/更新 `CHANGELOG.md`。
-
-### 发布
-
-最后可以发布：
-
-```bash
-npx changeset publish
-```
-
-会自动调用 `npm publish`，把包发到 npm registry。
-
-## 3. 在 Monorepo 中的优势
-
-- 避免多人协作时冲突：大家都往 `.changeset` 添加文件，不会直接改 `package.json`。
-- 统一生成 changelog：自动保证每个版本的改动都被记录。
-- 自动化发布：和 GitHub Actions 等 CI 工具结合，可在合并到主分支后自动发版。
+repoctl coordinates the release workflow, validates configuration, and publishes metadata. pnpm owns the versioning state and repository changelog storage.
 
-## 总结
+## Prerelease Lanes
 
-**Changeset 就是一个版本管理与发版工具**，它通过“先记录再统一处理”的方式，帮助 npm 包（尤其是 monorepo）保持版本升级和 changelog 的一致性与可追溯性。
+Use `repo release pre enter <tag>`, `repo release pre publish`, and `repo release pre exit` for alpha, beta, rc, or next lanes.

package/templates/vitepress/tools/husky.md

@@ -1,130 +1,12 @@
 # Husky
 
-在 repoctl 体系里，Husky 是 Git hook 触发器；真正的校验逻辑尽量收口到 repoctl 命令，方便本地、CI 和手动复现使用同一套入口。
+Husky connects repository scripts to Git hooks. repoctl-managed workspaces use it as a thin entrypoint, keeping verification logic in versioned commands.
 
-```bash
-repo verify pre-commit
-repo verify commit-msg .git/COMMIT_EDITMSG
-repo verify pre-push
+```sh
+# .husky/pre-commit
+pnpm exec repo verify pre-commit
 ```
 
-如果你只想手动复现推荐校验，用：
+Use `commit-msg` for commitlint and `pre-push` for broader build and test verification. Hooks should remain fast enough for local work and should not contain duplicated task logic.
 
-```bash
-repo check --staged
-repo check --full
-```
-
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
-
-## 1. 什么是 Husky？
-
-**Husky** 是一个用于在 **Git hooks**（如 `pre-commit`、`pre-push`、`commit-msg` 等）中运行脚本的工具。
-它的作用是让你在提交代码前或推送代码前，自动执行一些校验、格式化或测试，从而保证代码质量和团队规范。
-
-> 简单来说：**Husky = Git hooks 的管理工具**。
-
-## 2. Husky 有什么用？
-
-常见用途：
-
-1. **代码格式化**
-   在提交前运行 `prettier --write .`，确保代码风格一致。
-2. **Lint 检查**
-   在 `pre-commit` 时执行 `eslint`，防止有 lint 错误的代码被提交。
-3. **推送前执行整仓校验**
-   在 `pre-push` 时执行整仓 `lint`、`typecheck`，并按需补跑 `build`、`test`、`tsd`，防止未通过校验的代码被推送。
-4. **Commit 信息校验**
-   在 `commit-msg` hook 中使用 [commitlint](https://github.com/conventional-changelog/commitlint) 强制提交信息符合规范（如 Conventional Commits）。
-
-## 3. 如何使用 Husky？
-
-### 安装
-
-```bash
-npm install husky --save-dev
-```
-
-### 初始化
-
-```bash
-npx husky init
-```
-
-这会生成一个 `.husky` 目录，并在里面创建 `pre-commit` 文件，默认内容可能是：
-
-```bash
-#!/bin/sh
-npm test
-```
-
-### 添加 Hook
-
-假设你想在提交前运行 ESLint，可以这样：
-
-```bash
-npx husky add .husky/pre-commit "npm run lint"
-```
-
-生成的 `.husky/pre-commit` 文件类似：
-
-```bash
-#!/bin/sh
-npm run lint
-```
-
-### 使用 commit-msg 校验提交信息
-
-先装 commitlint：
-
-```bash
-npm install @commitlint/{config-conventional,cli} --save-dev
-```
-
-创建配置文件 `commitlint.config.js`：
-
-```js
-module.exports = { extends: ['@commitlint/config-conventional'] }
-```
-
-添加 hook：
-
-```bash
-npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"
-```
-
-这样，若提交信息不符合规范，会被拦截。
-
-## 4. 和 lint-staged 搭配
-
-通常 Husky 会和 [lint-staged](https://github.com/okonet/lint-staged) 搭配使用：
-只检查本次改动的文件，而不是全量检查。
-
-示例：
-`package.json` 里加：
-
-```json
-{
-  "lint-staged": {
-    "*.js": "eslint --fix",
-    "*.ts": "eslint --fix"
-  }
-}
-```
-
-然后在 `.husky/pre-commit` 文件中写：
-
-```bash
-npx lint-staged
-```
-
-在本仓库默认实现里，`pre-commit` 和 `pre-push` 的职责拆分是：
-
-- `pre-commit`：只针对 staged 文件执行 `eslint`、`stylelint` 和 workspace `typecheck`
-- `pre-push`：强制执行整仓 `pnpm lint`、`pnpm typecheck`，并根据改动范围补跑 `build`、`test`、`tsd`
-
-## 总结
-
-- **Husky** 是一个 Git hooks 工具，用来在 commit、push 等阶段运行脚本。
-- 主要用于 **代码质量控制**：lint、格式化、测试、commit message 校验等。
-- 使用方式：安装 → 初始化 → 添加 hooks → 编写脚本。
+`repo doctor` reports when Husky and lint-staged are only partially configured. `repo upgrade` can synchronize the managed defaults.

package/templates/vitepress/tools/index.md

@@ -1,38 +1,19 @@
 ---
-description: repoctl 文档站的工具专题入口，汇总 pnpm、Turborepo、changeset、Husky、lint-staged 和 Renovate。
+outline: deep
 ---
 
-# 工具专题
+# Tool Guides
 
-工具专题只讲 repoctl 周边工具。repoctl 会把这些工具串成稳定工作流，但每个工具本身仍有独立的配置模型和维护边界。
+repoctl coordinates established tools instead of replacing them.
 
-## 1. 工具地图
+| Tool                              | Responsibility                                      |
+| --------------------------------- | --------------------------------------------------- |
+| [pnpm](./pnpm.md)                 | Workspaces, dependency installation, and versioning |
+| [Turborepo](./turborepo.md)       | Task graph execution and caching                    |
+| [pnpm Versioning](./changeset.md) | Change intents, versions, and changelogs            |
+| [Husky](./husky.md)               | Git hook entrypoints                                |
+| [lint-staged](./lint-staged.md)   | Checks scoped to staged files                       |
+| [Renovate](./renovate.md)         | Automated dependency updates                        |
+| [llms.txt](./llms-txt.md)         | AI-readable documentation discovery                 |
 
-| 工具        | 在 repoctl 工作流里的位置                       | 详细页面                        |
-| ----------- | ----------------------------------------------- | ------------------------------- |
-| pnpm        | workspace、依赖安装、根脚本和包内脚本执行       | [pnpm](./pnpm.md)               |
-| Turborepo   | build、lint、typecheck、test 等任务编排         | [turborepo](./turborepo.md)     |
-| changeset   | 多包版本、变更记录和发布准备                    | [changeset](./changeset.md)     |
-| Husky       | Git hook 入口                                   | [husky](./husky.md)             |
-| lint-staged | staged 文件级 lint、stylelint 和 typecheck 路由 | [lint-staged](./lint-staged.md) |
-| Renovate    | 依赖更新和升级 PR 治理                          | [renovate](./renovate.md)       |
-
-## 2. 和 repoctl 的关系
-
-repoctl 不隐藏这些工具。它主要做三件事：
-
-1. 生成推荐配置，减少每个仓库重复复制。
-2. 提供 `doctor` 和 `check`，帮助你验证配置是否接上。
-3. 提供 `upgrade`，在模板标准发生变化时同步资产。
-
-因此排障时不要只看 repoctl 命令。比如 `repo check --full` 失败时，真正失败的任务可能是 `pnpm lint`、`pnpm typecheck`、某个 workspace 的 `build` 或 `test`。
-
-## 3. 按目标阅读
-
-| 目标                      | 建议页面                                               |
-| ------------------------- | ------------------------------------------------------ |
-| 让 workspace 包能互相引用 | [pnpm](./pnpm.md)                                      |
-| 提升整仓任务速度          | [turborepo](./turborepo.md)                            |
-| 建立规范发版链路          | [changeset](./changeset.md)                            |
-| 提交前自动修复格式和 lint | [Husky](./husky.md) 与 [lint-staged](./lint-staged.md) |
-| 降低依赖升级成本          | [Renovate](./renovate.md)                              |
+Use repoctl for repository tasks and these tools directly when you need their lower-level controls.

package/templates/vitepress/tools/lint-staged.md

@@ -1,103 +1,12 @@
 # lint-staged
 
-在 repoctl 体系里，lint-staged 负责把 staged 文件交给合适的工具；repoctl 的 `verify staged-typecheck` 会根据文件所在 workspace 路由 typecheck。
+lint-staged runs checks only for files included in the next commit.
 
-```bash
-repo verify pre-commit
-repo verify staged-typecheck packages/app/src/main.ts
-repo check --staged
-```
-
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
-
-## 1. 什么是 lint-staged？
-
-**lint-staged** 是一个工具，主要功能是：
-在 **Git 暂存区（staged）里的文件** 上运行你指定的 linters 或脚本。
-
-👉 它和 **Husky** 搭配使用最常见：
-
-- Husky 负责触发 Git hooks（比如 `pre-commit`）。
-- lint-staged 负责只对 **本次提交涉及的文件** 进行检查和修复。
-- 在本仓库默认配置里，`ts` / `tsx` / `mts` / `cts` / `vue` 文件还会继续触发对应 workspace 的 `typecheck`。
-
-这样就避免了对整个项目运行 lint/format，节省时间。
-
-## 2. lint-staged 有什么用？
-
-- **提高性能**：只检查本次改动的文件，而不是全量跑 `eslint` 或 `prettier`。
-- **保证提交质量**：阻止不符合规范的代码进入仓库。
-- **常见场景**：
-  - 运行 ESLint 自动修复：`eslint --fix`
-  - 运行 Prettier 格式化：`prettier --write`
-  - 运行 workspace 级类型检查：Vue 项目通常是 `vue-tsc -b`，TS 项目通常是 `tsc -p tsconfig.json`
-  - 优化图片、转换 Markdown 等自定义脚本
-
-## 3. 如何使用 lint-staged？
-
-### 安装
-
-```bash
-npm install lint-staged --save-dev
-```
-
-### 配置
-
-lint-staged 支持在 `package.json`、`.lintstagedrc` 或 `lint-staged.config.js` 中配置。
-
-最简单的方式：在 `package.json` 加上：
-
-```json
-{
-  "lint-staged": {
-    "*.js": "eslint --fix",
-    "*.ts": "eslint --fix",
-    "*.{js,ts,json,css,md}": "prettier --write"
-  }
-}
-```
-
-### 结合 Husky
-
-一般在 `.husky/pre-commit` 中加：
+The repository policy routes JavaScript, TypeScript, and Vue files through ESLint, style files through Stylelint, and TypeScript or Vue files to the owning workspace's typecheck script.
 
 ```bash
-npx lint-staged
-```
-
-这样在提交时，lint-staged 会自动处理已暂存的文件。
-
-本仓库默认生成的规则更接近下面这种形式：
-
-```js
-export default {
-  '*.{js,jsx,mjs,ts,tsx,mts,cts}': ['eslint --fix'],
-  '*.vue': ['eslint --fix', 'stylelint --fix --allow-empty-input'],
-  '*.{ts,tsx,mts,cts,vue}': files => `pnpm exec repoctl verify staged-typecheck ${files.join(' ')}`,
-  '*.{json,md,mdx,html,yml,yaml}': ['eslint --fix'],
-  '*.{css,scss,sass,less}': ['stylelint --fix --allow-empty-input'],
-}
+pnpm exec repo verify pre-commit
+pnpm exec repo verify staged-typecheck <files...>
 ```
 
-## 4. 示例工作流
-
-假设你改了两个文件：
-
-- `src/app.js`
-- `docs/readme.md`
-
-然后执行 `git add . && git commit -m "feat: add app"`
-
-在 `pre-commit` hook 中，lint-staged 会只对这两个文件运行配置的命令，比如：
-
-- `eslint --fix src/app.js`
-- `prettier --write docs/readme.md`
-
-最终确保这两个文件在提交之前符合规范。
-
-## 总结
-
-- **lint-staged = 只在 staged 文件上运行 lint/脚本的工具**。
-- 优点：快、精准，避免全量检查。
-- 常和 **Husky** 搭配，用于 `pre-commit`。
-- 在 monorepo 里很适合把 ESLint、Stylelint 和 workspace `typecheck` 串起来。
+Vue workspaces should use `vue-tsc`; plain TypeScript workspaces should use `tsc`. Keep the routing in `lint-staged.config.js` so local hooks and CI can share the same contract.

package/templates/vitepress/tools/llms-txt.md

@@ -1,9 +1,7 @@
----
-description: llms.txt 说明页已移动到独立的 AI 文档栏目。
----
+# llms.txt
 
-# llms.txt 已移动
+`llms.txt` is a convention for publishing a compact, AI-readable map of a documentation site.
 
-llms.txt 现在放在独立的 AI 文档栏目中维护。
+This site generates an English-default `/llms.txt` and a larger `/llms-full.txt`. Simplified Chinese content is namespaced under `/zh/`, and historical or internal files are excluded from the index.
 
-请阅读：[AI 文档入口：llms.txt](../ai/llms-txt.md)。
+See the [repoctl AI documentation](../ai/llms-txt.md) for URLs and maintenance rules.

package/templates/vitepress/tools/pnpm.md

@@ -1,127 +1,15 @@
 # pnpm
 
-repoctl 默认围绕 pnpm workspace 设计。你不需要先掌握 pnpm 的所有细节，但要理解这三个事实：
-
-- `pnpm-workspace.yaml` 决定哪些目录属于 workspace。
-- `pnpm install` 会把 workspace 包链接起来。
-- 根脚本，例如 `pnpm doctor`、`pnpm new`、`pnpm check`，最终会调用 repoctl 的 `repo` CLI。
-
-## 在 repoctl 项目里怎么用 pnpm
+pnpm owns workspace discovery, dependency installation, script execution, and versioning configuration.
 
 ```bash
 pnpm install
-pnpm add -D repoctl
-pnpm doctor
-pnpm new sdk --template tsdown
-pnpm check
+pnpm --filter <package> build
+pnpm -r test
+pnpm change
+pnpm change status
 ```
 
-| 命令                  | 在 repoctl 工作流里的作用     |
-| --------------------- | ----------------------------- |
-| `pnpm install`        | 安装依赖并创建 workspace link |
-| `pnpm add -D repoctl` | 给已有仓库接入 repoctl CLI    |
-| `pnpm doctor`         | 通过根脚本运行 `repo doctor`  |
-| `pnpm new`            | 通过根脚本运行 `repo new`     |
-| `pnpm check`          | 通过根脚本运行 `repo check`   |
-
-继续看：[repoctl 快速开始](../repoctl/getting-started.md)。
-
-## 1. 什么是 pnpm？
-
-**pnpm** 是一种 Node.js 的包管理器（类似于 **npm** 和 **yarn**）。
-名字里的 **p** 代表 **Performant（高性能）**，也有人说是 **“poor man's npm”** 😂。
-
-它的核心特点是：
-
-- 使用 **硬链接 + 符号链接** 的方式来存储依赖。
-- 避免不同项目重复下载相同的依赖，大大节省磁盘空间。
-- 更快的安装速度。
-
-## 2. pnpm 有什么用？
-
-### 🚀 性能和空间优势
-
-- **npm/yarn**：每个项目都要复制一份完整的依赖到 `node_modules`。
-- **pnpm**：把所有依赖放在一个全局的 **内容可寻址存储（content-addressable store）**，项目里只是通过符号链接指向。
-
-结果就是：
-
-- 相同的依赖只会存一份。
-- 安装速度更快，磁盘占用更小。
-
-### 📦 严格的依赖隔离
-
-- 在 `npm` 或 `yarn` 中，`node_modules` 会形成一个“扁平化”结构，有时可能让项目误依赖到不是自己声明的包（幽灵依赖问题）。
-- **pnpm** 使用符号链接保持严格的依赖树，避免隐式依赖。
-  👉 如果你的 `package.json` 里没声明，就无法直接引用。
-
-### 🛠 Monorepo 支持更好
-
-- `pnpm` 原生支持 monorepo 管理（工作空间 `pnpm-workspace.yaml`）。
-- 比如在一个仓库里有多个子包，`pnpm` 可以高效地安装和链接它们，代替 Lerna、Yarn workspaces 等工具。
-
-### 🌍 与 npm 生态完全兼容
-
-- `pnpm` 底层还是调用 npm registry，所以和 npm 包生态 **100%兼容**。
-- 使用方式也和 `npm` 很接近，学习成本低。
-
-## 3. 如何使用 pnpm？
-
-### 安装 pnpm
-
-```bash
-npm install -g pnpm
-```
-
-### 常用命令对照
-
-| 操作       | npm                | pnpm             |
-| ---------- | ------------------ | ---------------- |
-| 安装依赖   | `npm install`      | `pnpm install`   |
-| 安装某个包 | `npm install xx`   | `pnpm add xx`    |
-| 移除某个包 | `npm uninstall xx` | `pnpm remove xx` |
-| 更新依赖   | `npm update`       | `pnpm update`    |
-| 初始化项目 | `npm init`         | `pnpm init`      |
-
-### Monorepo 示例
-
-创建 `pnpm-workspace.yaml`：
-
-```yaml
-packages:
-  - 'packages/*'
-  - 'apps/*'
-  - 'templates/*'
-```
-
-这样 `pnpm` 会自动管理多个子项目的依赖和链接。
-
-## 总结
-
-- **pnpm 是一种更快、更省空间、更严格的包管理器**。
-- 核心优势：
-  1. **磁盘节省**（共享依赖存储）。
-  2. **安装速度快**。
-  3. **严格依赖管理**，避免幽灵依赖。
-  4. **原生支持 monorepo**。
-
-## npm vs Yarn vs pnpm 对比表
-
-| 特性 / 工具       | **npm**                          | **Yarn**                      | **pnpm**                               |
-| ----------------- | -------------------------------- | ----------------------------- | -------------------------------------- |
-| **生态兼容性**    | ✅ 官方，100% 兼容 npm registry  | ✅ 兼容 npm registry          | ✅ 兼容 npm registry                   |
-| **安装速度**      | ⏳ 较慢（尤其是全量安装时）      | 🚀 比 npm 快，缓存优化        | ⚡ 非常快（硬链接 + 全局存储机制）     |
-| **磁盘空间占用**  | 📦 高，每个项目一份完整依赖      | 📦 中等，有缓存但依赖重复存储 | 🪶 很低，共享依赖存储，节省大量空间    |
-| **依赖结构**      | 扁平化，可能产生“幽灵依赖”       | 扁平化，依旧可能有幽灵依赖    | 严格隔离，避免幽灵依赖                 |
-| **Monorepo 支持** | 🚫 无原生支持，需要 Lerna 等工具 | ⚠️ Yarn Workspaces 支持       | ✅ 原生支持 Workspaces，管理更高效     |
-| **命令兼容性**    | 标准 npm 命令                    | 大部分与 npm 相似             | 基本兼容，部分命令略有不同（如 `add`） |
-| **锁文件**        | `package-lock.json`              | `yarn.lock`                   | `pnpm-lock.yaml`                       |
-| **稳定性**        | ✅ 官方维护，稳定性高            | ✅ 较成熟，社区维护           | ✅ 越来越流行，性能最佳                |
-| **学习成本**      | ⭐⭐ 最低                        | ⭐⭐ 略有差异（命令相似）     | ⭐⭐⭐ 略高，但上手简单                |
-| **适用场景**      | 小型项目，或默认环境             | 中大型项目，需要更快安装      | 中大型/Monorepo 项目，重视性能和空间   |
-
-## 对比总结
+`pnpm-workspace.yaml` is the source of truth for package patterns and release groups. repoctl can diagnose missing patterns and synchronize recommended defaults, but pnpm remains the package manager.
 
-- **npm**：默认选择，生态最广，适合一般小型项目。
-- **Yarn**：性能较优，适合需要加快依赖安装的团队。
-- **pnpm**：性能最好、磁盘最省、依赖最严格，特别适合 **大型项目** 和 **monorepo** 场景。
+Prefer exact workspace filters in automation and keep `packageManager` plus `engines.node` declared at the repository root.