@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/repoctl/workflows.md

@@ -1,8 +1,8 @@
-# 工作流与 CI
+# Workflows and CI
 
-repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、脚本、编辑器用的可保存输出。
+repoctl commands have two audiences: humans using short daily commands, and automation consuming stable reports.
 
-## 本地日常工作流
+## Local Daily Workflow
 
 ```bash
 pnpm install
@@ -12,17 +12,15 @@ pnpm run repo:check
 pnpm build
 ```
 
-这条链路适合新成员第一次进入仓库：
+| Step                   | What It Proves                                          |
+| ---------------------- | ------------------------------------------------------- |
+| `pnpm install`         | Workspace dependencies and local links are ready        |
+| `pnpm run repo:doctor` | Root files, Node, scripts, config, and hooks are usable |
+| `pnpm run repo:new`    | New packages follow template conventions                |
+| `pnpm run repo:check`  | The lightweight local verification flow is reproducible |
+| `pnpm build`           | The workspace build graph has no obvious breakage       |
 
-| 步骤                   | 判断标准                                         |
-| ---------------------- | ------------------------------------------------ |
-| `pnpm install`         | workspace 依赖和本地链接完整                     |
-| `pnpm run repo:doctor` | 仓库根目录、Node、脚本、配置和提交链路可用       |
-| `pnpm run repo:new`    | 新包由模板创建，目录和 package metadata 符合约定 |
-| `pnpm run repo:check`  | 提交前轻量校验可以复现                           |
-| `pnpm build`           | 全仓构建链路没有明显断点                         |
-
-## 存量仓库接入
+## Adopt An Existing Repository
 
 ```bash
 pnpm add -D repoctl
@@ -32,9 +30,9 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor
 ```
 
-推荐先用 `--no-overwrite` 保守接入。确认标准资产差异后，再决定是否使用 `--yes` 或 `--overwrite`。
+Start conservatively with `--no-overwrite`. After reviewing asset drift, decide whether `--yes` or `--overwrite` is appropriate.
 
-## CI 快速门禁
+## Fast CI Gate
 
 ```bash
 pnpm install --frozen-lockfile
@@ -42,9 +40,9 @@ pnpm exec repo doctor --strict
 pnpm exec repo check --full
 ```
 
-适合小仓库或早期项目。`doctor --strict` 会把 warning 也当成失败，能避免配置漂移慢慢积累。
+This is a simple gate for small repositories or early projects. `doctor --strict` treats warnings as failures.
 
-## CI 报告模式
+## CI Report Mode
 
 ```bash
 pnpm exec repo doctor --json --out reports/doctor.json
@@ -52,15 +50,13 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo env support --markdown --redact --out reports/support.md
 ```
 
-这组命令适合想保存构建上下文的 CI：
-
-- `doctor.json` 给脚本判断仓库健康状态。
-- `check-plan.json` 记录本次会跑哪些校验。
-- `support.md` 适合上传为 artifact，或贴进 issue / PR。
+Use these outputs as CI artifacts:
 
-## pre-commit 与 pre-push
+- `doctor.json` for scripts.
+- `check-plan.json` to explain verification routing.
+- `support.md` for issues, PRs, and external collaboration.
 
-repoctl 暴露了底层 verify 命令，方便 hook 和脚本复用：
+## Hooks
 
 ```bash
 repo verify pre-commit
@@ -69,50 +65,25 @@ repo verify commit-msg .git/COMMIT_EDITMSG
 repo verify pre-push
 ```
 
-默认建议：
-
-| 阶段       | 推荐行为                                                |
-| ---------- | ------------------------------------------------------- |
-| pre-commit | 聚焦 staged 文件，运行格式、lint 和 workspace typecheck |
-| commit-msg | 校验 Conventional Commit 格式                           |
-| pre-push   | 跑整仓 lint/typecheck，并按变更范围补 build/test/tsd    |
-
-## 自动化创建预览
-
-```bash
-repo new dashboard --template vue-hono --json --out plans/dashboard.json
-repo templates --markdown --out docs/templates.md
-repo ws ls --json --out reports/workspaces.json
-```
-
-这些命令都不会要求人工选择，适合编辑器插件、脚本和 CI bot。
-
-## 推荐流水线拆分
-
-| 阶段 | 命令                                                            | 失败后先看                           |
-| ---- | --------------------------------------------------------------- | ------------------------------------ |
-| 安装 | `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                          |
-
-早期项目可以把计划和执行合并。成熟项目建议保留 `reports/`，方便失败时复盘实际执行路径。
+| Stage      | Recommended Behavior                                      |
+| ---------- | --------------------------------------------------------- |
+| pre-commit | Focus on staged files, lint, and workspace typecheck      |
+| commit-msg | Enforce Conventional Commit messages                      |
+| pre-push   | Run root lint/typecheck and affected build/test/tsd tasks |
 
-## 非交互参数选择
+## Non-Interactive Options
 
-| 场景               | 推荐参数                                           |
-| ------------------ | -------------------------------------------------- |
-| 初始化时接受默认值 | `repo init --yes`                                  |
-| 同步时保留已有改动 | `repo upgrade --no-overwrite`                      |
-| 明确覆盖标准资产   | `repo upgrade --yes` 或 `repo upgrade --overwrite` |
-| 只看计划不执行     | `--dry-run`                                        |
-| 输出给脚本         | `--json --out <file>`                              |
-| 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
+| Scenario                              | Option                                             |
+| ------------------------------------- | -------------------------------------------------- |
+| Accept setup defaults                 | `repo init --yes`                                  |
+| Preserve changed files during upgrade | `repo upgrade --no-overwrite`                      |
+| Explicitly overwrite standard assets  | `repo upgrade --yes` or `repo upgrade --overwrite` |
+| Preview only                          | `--dry-run`                                        |
+| Output for scripts                    | `--json --out <file>`                              |
+| Share a redacted report               | `--markdown --redact --out <file>`                 |
 
-## 下一步
+## Keep Reading
 
-- 查所有参数：[命令速查](./commands.md)
-- 理解校验链路：[校验链路](./checks.md)
-- 生成排障包：[报告与自动化输出](./reports.md)
-- 看短命令：[命令别名](./aliases.md)
+- [Command Reference](./commands.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

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` 文件，就报错的问题。
-
-### 发包流程
-
-现在使用 pnpm 原生 versioning：用 `pnpm change` 记录意图，用 `pnpm version -r` 生成版本和 changelog，再用 `pnpm publish -r` 发布。版本计划保留在 `.changeset/ledger.yaml`，预发布则由 pnpm lanes 管理。
-
-### 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,75 +1,25 @@
 # pnpm Versioning
 
-本模板使用 pnpm 11 原生 versioning 管理 monorepo 的变更意图、版本号、changelog 和发布。变更意图仍然使用 `.changeset/*.md` 格式，因此每次改动可以独立提交，不会直接修改包版本。
+This repository uses pnpm change intents and workspace versioning for releases.
 
-## 日常开发
+## Daily Development
 
 ```bash
 pnpm change
 pnpm change status
 ```
 
-`pnpm change` 会询问受影响的包、patch/minor/major 类型和 changelog 摘要。脚本或自动化场景可以直接指定：
+Choose every publishable package whose public behavior changed and record the correct patch, minor, or major level. Private template workspaces are not release units.
 
-```bash
-pnpm change --bump patch --summary "修复空输入崩溃" repoctl
-```
-
-变更意图会写入 `.changeset/`，与代码一起提交。`pnpm change status` 只预览计划，不会修改文件。
-
-## 版本与 changelog
-
-在 Release PR 中由 CI 消费变更意图：
-
-```bash
-pnpm version -r --dry-run
-pnpm version -r
-```
-
-`pnpm version -r` 会更新受影响包、传播 workspace 依赖、生成 `CHANGELOG.md`，并把消费记录追加到 `.changeset/ledger.yaml`。仓库配置使用 `versioning.changelog.storage: repository`，所以 changelog 会和版本提交一起审查。
-
-`@icebreakers/monorepo` 与 `repoctl` 属于 pnpm fixed group，任一包需要发布时两者始终使用同一个版本。
-
-## 发布
-
-正式发布由 Release PR 合并后的 main workflow 完成：
+## Release
 
 ```bash
-pnpm publish -r --report-summary --provenance --no-git-checks
+repo release stable prepare
+repo release stable publish
 ```
 
-pnpm 会跳过 registry 中已经存在的版本，并把新发布包写入 `pnpm-publish-summary.json`。CI 根据 summary 创建 `package@version` Git tag 和 GitHub Release，因此重复执行不会重新发布已存在版本。
-
-本地推荐使用 repoctl 包装命令：
-
-```bash
-pnpm exec repo release stable prepare
-pnpm exec repo release stable publish
-```
-
-## Prerelease lanes
-
-alpha、beta、rc、next 是 pnpm lanes，而不是 Changesets pre 状态：
-
-```bash
-pnpm exec repo release pre enter alpha
-git add pnpm-workspace.yaml && git commit -m "chore(release): enter alpha lane"
-git push
-
-pnpm exec repo release pre publish
-```
-
-退出预发布轨道时执行 `pnpm exec repo release pre exit`，提交 `pnpm-workspace.yaml` 后合并回 main。lane 切换必须覆盖 fixed group 的全部包。
-
-## CI 约定
+repoctl coordinates the release workflow, validates configuration, and publishes metadata. pnpm owns the versioning state and repository changelog storage.
 
-- 生成的 release workflow 只负责 checkout、安装依赖和权限声明，全部业务统一由 `pnpm exec repo release ci` 执行。
-- main push 先生成或更新 Release PR；Release PR 合并后才发布 npm。
-- alpha、beta、rc、next 分支要求所有可发布包位于对应 lane。
-- npm 发布使用 GitHub OIDC provenance，不需要长期保存 `NPM_TOKEN`。
-- 未发布版本恢复使用 workflow dispatch 的 `publish-unpublished` 模式，并按 package/version 校验后发布。
-- repoctl 通过 GitHub REST API 幂等创建或更新 Release PR、package tag 和 GitHub Release，重复执行不会重复创建元数据。
+## Prerelease Lanes
 
-存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`。带有
-`repoctl-managed: release/v2` 的 workflow 会自动升级；未标记的自定义
-workflow 默认保留，可在确认后使用 `repo upgrade --overwrite-release`。
+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、版本管理、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)     |
-| pnpm versioning | 多包版本、变更记录和发布准备                    | [versioning](./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)                            |
-| 建立规范发版链路          | [pnpm versioning](./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.