@icebreakers/monorepo-templates 2.0.7 → 2.2.0

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

@@ -0,0 +1,51 @@
+# 准备构建上下文与生产产物
+
+`repo workspace prepare` 预览一个明确的工作区包。`prune` 调用本地 Turbo 2，生成部分 monorepo 与裁剪后的锁文件；`deploy` 调用根 `packageManager` 锁定的 pnpm，生成生产目录。命令只准备本地文件，不运行应用、不构建镜像，也不连接部署平台。
+
+```sh
+# 先显式构建所需产物。
+pnpm build
+repo workspace prepare @acme/service --mode prune --out ../service-build --json > ../prune-plan.json
+repo workspace prepare --apply ../prune-plan.json
+
+# 保留 Turbo 原生的 Docker full/json 缓存层。
+repo workspace prepare ./apps/service --mode prune --docker --out ../docker-context --json
+
+# 只使用本地存储，生成包含生产 workspace 依赖的目录。
+repo workspace prepare @acme/service --mode deploy --entry dist/server.js --offline --out ../service-runtime --json > ../deploy-plan.json
+repo workspace prepare --apply ../deploy-plan.json
+```
+
+预览始终只读，`--dry-run` 用于明确默认行为。原生版本、能力与路径设置探测不会安装工具。JSON 计划必须保存在源工作区外，审查后另行 `--apply`；应用不能混用目标、预览选项或 `--dry-run`。
+
+## 原生行为与前置条件
+
+两种模式都要求已有 pnpm 工作区和 `pnpm-lock.yaml`。使用准确包名或 `./目录` 选择唯一、具名的非根包，不支持 glob、多包匹配或依赖选择表达式。输出必须位于源工作区之外，父目录必须已存在；链接目标、重叠目录和无关的非空目录会被拒绝，没有强制覆盖选项。
+
+Prune 支持本地已安装的稳定 Turbo 2，保留原生构建依赖选择规则。`manifestCandidates` 仅解释清单关系，实际保留哪些包由 Turbo 决定。任务依赖、global 文件是否纳入，遵从对应版本和配置。`--docker` 保留原生 `full`、`json` 与锁文件布局。
+
+Deploy 支持明确锁定的稳定 pnpm 10、11、12，且原生命令必须提供所需选项。执行使用 `--prod`、`--ignore-scripts`、`--frozen-lockfile`，并禁用 pnpmfile hooks。`--legacy` 显式选择原生旧模式；该模式的生产目录可能没有根锁文件，只有 prune 要求产物包含该文件。pnpm 12.2 起支持非注入的 workspace 依赖；更早版本可能需要 `injectWorkspacePackages` 或 legacy 模式。peer 歧义和其他原生错误保留诊断代码并导致失败，repoctl 不自行解析或重写依赖图、锁文件。
+
+部署前会验证已构建的运行入口：显式 `--entry`、`package.main` 或唯一 `bin`。如果原生 `files`/ignore 规则未包含入口，准备失败。不会解释或执行任意 `start` 脚本。依赖生命周期脚本保持关闭；需要的原生二进制应事先准备。准备产物不等于验证应用全部运行行为。
+
+## 源目录与产物边界
+
+原生工具运行在隔离的源码副本中，不复制源 `node_modules`、`.git`、`.turbo` 和 `.repoctl` 存储。复制前排除真实 `.env`/`.env.*`、`.npmrc`、`.netrc`、`_netrc`、Yarn 认证配置及 `.aws`、`.ssh`、`.gnupg` 路径，保留公开的 `.env.example`、`.env.sample`。产物再次检查这些路径。这是明确文件名规则，不是通用秘密检测器；示例文件应使用公开占位值，部署凭据另行提供。
+
+源码副本保留被 Git 忽略的构建文件，最终是否纳入仍由原生 prune/打包规则决定。源码链接和特殊文件会被拒绝。输入和输出清单限制为 100,000 项、1 GiB；需要其他复制或存储策略的工作区可直接使用原生命令。
+
+命令读取 pnpm 有效 store/cache/state/module/lockfile 路径，不输出含凭据的完整配置。会写回源工作区的配置在 deploy 前被拒绝，module/lockfile 存储必须保持产物内的相对路径。暂存目录也必须在源工作区之外；工作区外的原生全局存储仍由 pnpm 管理。
+
+产物链接只能指向产物内部。相对链接保留；Windows 目录 junction 会针对最终产物目录重新创建。传输 Windows 产物时，使用会复制 junction 内容的复制/归档方式。集成验收会复制目录、移除源码和原产物，再独立执行生产入口。
+
+## 审查、恢复与重复应用
+
+计划包含源文件、权限、工具/版本、相关路径设置与选项的指纹。应用重新生成计划并拒绝漂移，在复制后、原生执行后、发布中及完成前复核源输入，并保留并发编辑。
+
+原生产物先进入暂存目录。发布以独占方式创建文件，记录归属和已写内容，最后提交 `.repoctl-artifact.json`。提交前文件可能已经可见，不应消费不完整目录。失败只移除本操作写入且未被修改的内容，保留并发文件并报告准确路径。成功后仅清理失败时，通过 `cleanupPending` 报告，不谎报回滚。
+
+重复应用只有在完整 receipt 与文件清单仍匹配时才返回 `unchanged`。未知或修改过的非空目录从不覆盖。`.repoctl/workspace-artifacts.lock` 覆盖重复检查、原生执行、发布与清理。进程中断后，先确认没有活动写入进程，检查并恢复不完整产物与保留暂存路径，再移除锁。
+
+公共 API：`planWorkspaceArtifact(cwd, options)`、`applyWorkspaceArtifactPlan(cwd, plan, { signal, timeoutMs })`；JSON schema 为 1。原生执行默认两分钟超时，API 可配置至十分钟。
+
+参考：[Turbo prune](https://turborepo.com/docs/reference/prune)、[pnpm deploy](https://pnpm.io/cli/deploy)。

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

@@ -1,5 +1,11 @@
 # 命令速查
 
+[`repo workspace move`](./move.md) 用 `--to`、`--name` 分别预览目录移动、包名修改或两者同时变更。审查 JSON 计划与源码人工任务后，再通过 `--apply` 显式应用。
+
+[`repo workspace remove`](./removal.md) 可按准确包名或目录预览移除单个包，检查消费者与待人工复核引用，再显式应用已审查的 JSON 计划。预览不删除文件；消费者默认阻止移除，只有明确指定 `--remove-references` 才计划删除对应清单依赖字段。
+
+[`repo workspace prepare`](./artifacts.md) 可预览原生 Turbo prune 构建上下文或锁定 pnpm deploy 生产目录，再显式应用已审查的 JSON 计划。必须选择唯一包和工作区外的空输出目录。
+
 这一页只保留 repoctl 高频、实用、容易记错的命令。
 
 ## 最推荐入口
@@ -57,6 +63,41 @@ repo doctor --markdown --redact --out reports/doctor.md
 - `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
 - `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
 
+```bash
+repo doctor --list-rules
+repo doctor --rules root-scripts,package-manager --strict
+repo doctor --rules root-scripts --fix --out plans/doctor-fix.json
+repo doctor --apply plans/doctor-fix.json --json
+```
+
+`--rules` 在执行前选择精确、稳定的检查 ID；未知 ID 会失败并列出可用规则。CLI 会替换 `commands.doctor.rules`；省略规则时执行全部检查，配置中显式空数组表示不执行检查。共享的文件发现和规则前置读取仍会执行。`manifest-health` 是静态清单检查的汇总规则。架构边界与第三方依赖准入同样使用稳定的 `boundary-*` / `admission-*` ID；单选 `boundary-policy` 或 `admission-policy` 时汇总仍保留实际失败状态，必要的配置失败不会被过滤。自定义策略名只出现在诊断详情中。
+
+在 `commands.doctor.suppressions` 配置有理由的抑制。每项必须提供 `id` 与非空 `reason`，可选 `path` 精确匹配 workspace 相对文件路径。可选 `expires` 使用 UTC 日期 `YYYY-MM-DD`，到期当天仍有效。JSON 保留原始发现的状态、`suppression`、`rawSummary`，以及全部抑制记录及命中数量。仅有效抑制从 `summary` 和 strict 退出码中排除；过期与未命中的记录仍会展示。
+
+`--fix` 仅输出 JSON 预览，不修改项目文件。首批修复器只补根 `package.json` 中缺失的 `repo:init`、`repo:new`、`repo:check`、`repo:doctor` 键。已有值（包括空值和自定义脚本）保留，由用户人工核查。未选择或有效抑制的规则不会生成修复。审核新增脚本、完整前后内容、哈希、风险与 diff 后，用 `--apply` 应用。计划包含原始清单内容，不支持脱敏或 Markdown 转换后执行。
+
+应用时复核规范化 workspace 与原始文件内容，拒绝链接文件和篡改的操作，复用暂存写入及回滚事务，再无抑制地运行根脚本检查。输入内容改变会停止修复，需要重新生成计划。重复应用已完成计划不会再改文件。文字 `fix` 建议不会作为 shell 执行，也不会自动安装依赖或修改 release workflow。
+
+Doctor 修复在输入校验、应用、验证、回滚和清理期间持有 `.repoctl/doctor-fix.lock`，防止并发写入使成功修复被另一事务回退。进程异常退出后，先确认没有活动写入者并处理保留备份，再手动移除锁。
+
+## `repo env check`
+
+```bash
+repo env check
+repo env check build test --json --strict
+repo env check --markdown --no-framework-inference
+```
+
+只读检查静态 `process.env.NAME`、`import.meta.env.NAME`、字面量属性访问与解构，并与 Turbo 环境声明对照。默认检查 `build`，包含 private 包。每个包和任务分别列出参与 hash、仅透传、框架推断、框架内置、遗漏声明及无法静态确定的访问，附源码位置。注释和普通字符串不计为引用。真实 `.env*`、`.dev.vars*` 只检查文件路径，从不读取内容；示例文件只提取键名。JSON、文本和 Markdown 不输出变量值或源码片段。
+
+支持根与包级 `turbo.json`/`turbo.jsonc`、包专属任务、按顺序继承其他包配置、数组替换、`$TURBO_EXTENDS$` 和任务继承排除。变量通配符和否定模式采用 Turbo 语义。不支持的高级 `global` 配置及对象形式输入会返回配置失败，避免猜测覆盖结果。环境文件同时核对 `globalDependencies`、任务 `inputs`、`$TURBO_ROOT$`、显式排除和 Git 默认未忽略路径；文件存在本身不表示缓存已覆盖。`passThroughEnv` 只提供运行时变量，不把值计入 hash，报告会要求复核，不会自动提升为 `globalEnv`。全局 `*` 声明会提示检查缓存失效范围。
+
+在 `repoctl.config` 的 `commands.env` 中配置 `tasks`、包相对路径的 `include`/`exclude` glob、`frameworkInference` 和 `suppressions`。每条豁免必须有稳定 `rule` 与非空 `reason`，可按 `package`、`task`、`variable` 和仓库相对 `path` glob 缩小范围。豁免诊断仍可见，未匹配豁免会产生警告。配置失败退出 1；`--strict` 同时阻断警告。`--dry-run` 表明命令始终只读。API 为 `checkEnvironmentCache(cwd, options)` 和 `formatEnvironmentCache(report, markdown?)`。
+
+静态引用只是所选任务的候选输入，不能证明脚本实际执行了该源码。扫描覆盖 JS/TS 与 Vue/Svelte script block，跳过链接和大于 2 MiB 的文件；不解析别名、被遮蔽的全局变量、模板表达式、生成代码或跨包源码导入。框架推断依据包依赖估算，运行参数、自定义前缀及 shell 脚本引入的变量需要人工复核。既有可执行 repoctl 配置本身也应避免副作用。命令不运行任务、不加载真实环境值、不重写 Turbo 配置，也不扩大全局缓存输入。
+
+参考：[Turbo 环境变量](https://turborepo.com/docs/crafting-your-repository/using-environment-variables)、[配置](https://turborepo.com/docs/reference/configuration)、[包配置继承](https://turborepo.com/docs/reference/package-configurations)。
+
 ## `repo templates`
 
 ```bash
@@ -79,9 +120,9 @@ repo templates --markdown --out docs/templates.md
 ```bash
 repo new
 repo new sdk --template tsdown
-repo new docs --template vitepress
-repo new docs --template vitepress --dry-run
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus
+repo new docs --template nimbus --dry-run
+repo new docs --template nimbus --json --out plans/docs.json
 ```
 
 用途：
@@ -91,8 +132,26 @@ repo new docs --template vitepress --json --out plans/docs.json
 - `--json` 输出结构化创建计划，隐含 `--dry-run`。
 - 显式传入的 `--template` 会先校验，拼错时会失败并提示相近 key。
 
+## `repo package check`
+
+```bash
+repo package check
+repo package check --filter '@scope/*' --strict
+repo package check --filter my-library --keep-temp --json
+```
+
+按依赖顺序构建选中的 workspace 包及其依赖，再使用 publint 0.3.25 和 ATTW 0.18.5 校验实际 `pnpm pack` tarball。构建失败后不再打包。本地开发依赖也纳入构建，private 构建依赖可以只构建、不打包或校验。private 包默认明确标记为跳过，传入 `--include-private` 可包含它们。可重复 `--filter` 合并 pnpm 选择器；`--build-script` 可替换默认 `build` 脚本，没有该脚本的包按已经准备好的发布文件处理。
+
+临时消费者独立安装 tarball 和本地运行时依赖的 tarball，执行包声明支持的 Node ESM/CJS 入口及 TypeScript NodeNext 消费检查。类型消费使用 ATTW 固定的 TypeScript 5.6.1-rc。未声明支持的模块格式不强制通过；仅供浏览器使用的入口及非 JavaScript 资源接受清单/类型分析，不执行 Node import；JavaScript bin 做语法检查，不调用应用命令。安装可能访问 registry，依赖安装脚本默认禁用；workspace 构建与 pack 生命周期脚本正常执行。
+
+JSON 包含每个包的文件清单、稳定的诊断来源/代码、上游原始细节及子进程参数数组。`--strict` 将 warning 视为失败。`--keep-temp` 保留 tarball、消费者清单和命令工作目录，方便复现；未启用时，失败后也会清理临时文件。命令不会发布包、修改版本或写入发布状态。
+
+接入发布门禁时，可以添加 `"package:check": "repoctl package check --strict"` 脚本，再把 `package:check` 加入 `commands.release.hooks.verify`。不要从 build/prepack 脚本调用本命令，以免循环执行。
+
 ## `repo check`
 
+需要显式启用闲置代码及依赖分析时，参阅 [`repo check knip`](./knip.md)。
+
 ```bash
 repo check
 repo check --staged
@@ -113,6 +172,9 @@ repo check --markdown --redact --out reports/check-plan.md
 
 ## `repo upgrade`
 
+第三方依赖声明可用 `repo deps check` 检查，使用 `repo deps plan` 生成显式只读计划，
+审阅 JSON 后再执行 `repo deps apply`。协议、版本分组及恢复方式见[依赖版本一致性](./dependencies.md)。
+
 ```bash
 repo upgrade
 repo upgrade --yes
@@ -121,6 +183,10 @@ repo upgrade --no-overwrite
 repo upgrade --core
 repo upgrade -i
 repo upgrade -s
+repo upgrade --dry-run
+repo upgrade --json > upgrade-plan.json
+repo upgrade --markdown
+repo upgrade --apply upgrade-plan.json
 ```
 
 用途：
@@ -131,8 +197,55 @@ repo upgrade -s
 - `--no-overwrite` / `-s` 保留已有 drifted 文件。
 - `--yes` / `--overwrite` 非交互覆盖 drifted 标准资产。
 
+`--dry-run`、`--json` 和 `--markdown` 始终只读预览，不写入或弹出交互选择。每个选中资产都有 `add`、`modify`、`delete`、`identical`、`skip` 或 `conflict` 状态及原因。package 脚本与依赖、workspace 设置、AGENTS 章节、gitignore 规则、工具引用和旧版本迁移都进入同一计划。文本和 Markdown 提供逐文件 unified diff；二进制文件、前后内容合计超过 256 KiB 的文本会明确标注，不伪造 diff。
+
+`--apply` 使用已审核 JSON 中的精确内容，应用全部可执行条目。普通升级仍支持交互选择语义迁移；具有历史上游基线的安全合并和已批准的新增文件可以非交互执行。所有选择都在首次写入前完成。`--no-overwrite` 和 `-s` 也保护旧版迁移元数据；自定义发布工作流需要显式 `--overwrite-release`，既有 LICENSE 始终保留。预发布 lane 迁移与元数据删除属于不可拆分的选择组；无法识别的预发布状态保留在磁盘上，等待手动迁移。
+
+根受管资产采用三方合并：比较上次上游内容、当前本地文件和新安装模板。互不重叠的修改自动合并；同一区域的修改在计划中提供旧基线、本地、上游片段及行号。二进制文件的双边修改，以及合计超过 1 MiB 的文本，需要手动处理冲突。package/workspace 配置、AGENTS、gitignore 继续使用现有语义合并策略。本能力不升级生成的 app/package 业务目录，也不执行历史模板代码。
+
+基线保存在 `.repoctl/baselines/root/<路径 SHA-256>.json`；应将此目录提交到仓库，让不同克隆共享升级历史。每条记录包含资产路径、模板包和版本、源文件 SHA-256，以及上游原文和哈希，不把定制后的合并结果当作上游。哈希用于内容完整性和本地来源追溯，并非发布者签名。保存的计划本身就是待审核的写入内容；修改内容并重算哈希后，需要重新审核，哈希不能证明其作者身份。没有历史基线且内容不同的旧文件标为 `baseline-missing` 冲突；审核后可使用 `--overwrite` 显式采用新模板，`--yes` 本身不能消除冲突。与上游完全相同的文件可以只登记基线，不重写资产。删除基线目录会丢失历史信息，下一次升级重新采用保守的首次处理规则。
+
+版本化迁移显示在计划的 `migrations` 中，包含稳定 ID、版本边界、选择原因和受影响文件。首个内置迁移 `changesets-to-pnpm-versioning` 的边界为模板 `1.1.0`，对应引入 pnpm 原生版本管理的发行版。目标版本取已安装模板包的精确版本；没有历史记录时，可用 `--from-version 1.0.15` 明确提供旧模板版本，不会从 `^1.0.0` 等依赖范围推断。未知来源只收养可识别的旧格式，原因标为 `adopt-detected-legacy-format`；格式不明和降级会阻止执行。没有旧元数据的新项目不触发历史迁移，也不初始化账本。
+
+账本创建后，应提交 `.repoctl/migrations/ledger.json`。其中 `evaluatedVersion` 仅表示迁移评估到的版本，不代表每个受管资产都已使用该模板版本。预览不写文件；完成状态以普通文件 diff 审阅，JSON 同时包含 pending/failed 中间状态的精确内容。迁移文件组成不可拆分的选择组，未选择或失败的步骤不会推进游标。执行先保存 pending，迁移文件事务最后才写 completed；完成状态写入失败会回滚并记录 failed，如果失败状态也写不进去，则保留 pending 日志供恢复。其他选中资产在迁移组之后执行，其失败不会撤销已成功完成的迁移。
+
+中断后重新预览：日志保留已审核输出及前后哈希，恢复计划会列出已经写入和仍待写入的文件。出现第三种内容就停止恢复，保留用户修改和 `*.repoctl-upgrade-<尝试ID>.bak` 原始备份。恢复要求原安装模板版本及其他已记录输入保持一致，不执行历史脚本或网络/发布操作。独占本地进程锁阻止并发应用；强制终止进程可能留下 `.repoctl/upgrade.lock`，先确认没有活动写入者并检查待恢复备份，再移除该锁、重新预览。不会按锁龄自动抢占，正常清理同时校验自身 token 和文件系统身份。没有迁移元数据的旧保存计划仍可应用，不会补记未审核账本。
+
+用户已删除的受管文件不会恢复，即使传入 `--overwrite` 也一样；需要手动恢复后才能继续升级。上游删除文件时，仅自动删除本地没有定制的版本，定制版本保留并报告冲突。每个选中文件与其已审核基线操作属于同一事务，统一回滚和检查重试。JSON 文件条目的可选 `baseline` 包含前后哈希和精确内容；部分选择不会推进其他文件的基线。旧版保存计划没有此字段时，不会额外创建未审核的记录。冲突文件不被应用；仍有冲突时 CLI 预览和应用均返回退出码 1，即使其他选中文件成功应用，API 结果仍通过 `conflicts` 列出待处理路径。
+
+计划记录目标、资产和本地配置文件的原始 hash。应用持有 `.repoctl/upgrade.lock`，直到输入校验、重复应用判断、写入、回滚和清理全部完成。它拒绝并发写入或 workspace 包集合变化；完整应用过的计划再次执行不会写入。替换前会创建 `.repoctl-upgrade-*.bak` 原始备份，失败后回滚。恢复文件和本次创建的目录只有在文件系统身份仍属于当前事务时才会清理；撞名文件、被改写的恢复内容和被替换的目录均予以保留。如果并发编辑阻止安全回滚，错误会列出保留的原始备份。进程中断后，先确认没有活动写入者，核查备份与临时文件并按需恢复原文件，然后移除锁并重新生成计划。无关文件及 Git refs/index 不会被修改。
+
+每次预览都会在内存中重新加载配置入口、继承配置和可静态解析的本地导入，包括使用字符串字面量的动态导入。这些文件也纳入输入校验，模块相对路径保持原有含义。已安装的外部包、计算生成的导入路径、环境变量及任意文件/网络读取不在此模块集合中；这些运行时输入变化后应重新生成计划。可执行配置本身也应避免副作用，才能保持预览只读。
+
+预览不会生成缺失的模板资产。出现 `assets-not-prepared` 时先修复包安装；源码贡献者可以显式运行 `pnpm --filter @icebreakers/monorepo-templates sync:assets`。计划绑定当前工作目录、输出目录和已安装资产的位置。公共 API 为 `planUpgrade(options)`、`formatUpgradePlan(plan, 'text' | 'markdown')`、`applyUpgradePlan(cwd, plan, { files? })` 和 `upgradeMonorepo({ dryRun: true })`；`UpgradePlan` 用 base64 保存精确应用内容。`repo workspace upgrade` 与 `repo ws up` 共用这些选项。
+
+## 工作区依赖查询
+
+```bash
+repo workspace graph
+repo workspace graph --json --redact
+repo workspace graph --mermaid
+repo workspace graph --package @acme/shared --type dependencies
+repo workspace why @acme/web @acme/shared --json
+repo workspace impact @acme/shared --direct --json
+```
+
+三个命令共用清单级依赖图，全部只读。默认包含 private 应用；`--exclude-private` 排除私有包，`--include-root` 加入根包。边的方向是消费者指向依赖。`--type` 可重复指定 `dependencies`、`devDependencies`、`peerDependencies`、`optionalDependencies`；不指定时包含全部四种关系。
+
+`graph --package <包名或目录>` 显示选中包及其直接入边、出边，可重复选择多个包。`why <from> <to>` 返回从消费者到目标包的一条确定性最短依赖路径，包含两端；没有路径仍是成功查询，JSON 中 `found` 为 `false`。`impact <package>` 返回直接与传递消费者、最小距离及每个消费者的一条路径；`--direct` 只返回直接消费者。查询能处理循环依赖，impact 不把目标自身列为消费者。
+
+选择器接受精确包名或 workspace 相对目录，例如 `./packages/shared`。重复包名会产生诊断；使用有歧义的名称查询会失败，需用显式目录消除歧义。未命名包也可按目录查询。强制本地引用若缺失、歧义、格式无效或版本不兼容，会进入 `diagnostics`，不会猜测依赖边。
+
+解析支持 workspace 版本范围、workspace 别名（如 `workspace:@acme/shared@^1`）、相对 workspace 路径及本地 `link:`/`file:` 目录。每条边记录 `resolution`：`workspace` 和 `local` 表示显式本地引用，`semver` 表示普通版本范围或 `npm:` 别名匹配到的本地候选。这反映清单关系，并不代表 lockfile 的实际安装结果；不解析 registry tag、catalog、远程 URL 或源码 import。catalog 引用以及存在同名本地候选但无法解析的协议会产生 `unresolved_specifier` 诊断。使用方应先检查诊断再判断图是否完整，后续 affected 校验可据此保守回退。排除 private/root 包后，指向它们的强制引用也可能无法解析。
+
+JSON 使用 schema version `1`、目录节点 ID 和稳定排序，字段名及诊断代码不随 `--lang` 改变。Mermaid 与 JSON 共用节点和依赖边，并保留孤立包。查询只输出 stdout，可用 shell 重定向保存；`--json` 与 `--mermaid` 不能组合。
+
+程序化调用可使用 `getWorkspaceGraph(cwd, options)`、`filterWorkspaceGraph(graph, options)`、`whyWorkspaceDependency(graph, from, to, options)` 和 `getWorkspaceImpact(graph, package, options)`。每次读取图时刷新发现缓存，查询函数使用公开图类型，不泄漏 pnpm 内部类型。
+
 ## 分组命令
 
+可选根目录开发环境参阅 [Dev Container 预设](./devcontainer.md)：先运行 `repo tooling devcontainer --json --out ../plan.json`，审阅后使用 `repo tooling devcontainer --apply ../plan.json`。
+
 ```bash
 repo ws ls
 repo ws ls --json --out reports/workspaces.json
@@ -166,3 +279,38 @@ repo skills sync --codex
 - [把校验加入 CI](/zh/tasks/ci)
 - [报告与自动化输出](/zh/tasks/reports)
 - [命令别名](./aliases.md)
+
+### 公共 API 基线
+
+`repoctl package api check [--package <selectors...>] [--json]` 比较已构建公开声明与显式配置的 API Extractor 报告。通过 `tooling.apiReports` 声明相对包目录的声明入口和相对工作区的 `.api.md` 基线，先安装本地稳定版 `@microsoft/api-extractor >=7.52.12 <8` 并构建。`package api update --json` 只预览；审核后使用 `package api update --apply <plan.json>` 更新。执行重新验证输入并使用文件事务，保留冲突与恢复提示。签名 diff 和未消费 change intents 仅作建议，不自动推断完整 SemVer 或发布。
+
+## `repo tooling references`
+
+`check --json` 无需启用即可检查已有引用；`plan` 和 `sync --dry-run` 只读输出稳定 JSON。显式配置 `tooling.projectReferences.enabled: true` 后，使用 `sync` 或 `apply <plan.json>` 同步受管引用。保留手工引用及 TypeScript/Vue 原有验证入口；不兼容编译选项、循环、缺失目标和过期计划会阻止应用。[配置参考](./config#typescript-project-references)说明了发现规则、显式编译关系、归属和恢复方式。
+
+### 增量接入 Playwright
+
+为已有 Vue/React Vite 应用添加浏览器测试；应用需包含 `build` 和 `preview` 脚本：
+
+```sh
+repo tooling capability list --json
+repo tooling capability plan playwright --target web --route / --role button --name Increment --expect-text 'Count: 1' --json > e2e-plan.json
+repo tooling capability apply e2e-plan.json --json
+pnpm install
+pnpm --filter @repoctl-e2e/web test:e2e:install
+pnpm test:e2e
+```
+
+使用 `--test-id` 可替代 `--role`/`--name`。路由、点击目标和预期文本必须对应应用中的真实交互。计划展示文件 diff、依赖、脚本、冲突和后续操作，预览不安装依赖。应用时使用已审阅的内容，检查过期输入和文件冲突；写入失败会回滚，重复应用不产生额外修改。首次接入请选择空目录（可用 `--directory` 指定）。应用业务文件及与生成内容不同的文件均受保护。
+
+能力包生成独立 E2E 工作区、无头 Chromium 测试、Turbo 构建依赖、CI 工作流、HTML 报告及失败 trace。浏览器需显式安装。`--port` 与 `--ci-port` 分别指定本地和 CI 端口且不能相同；CI 始终启动独立服务。本地只有显式添加 `--reuse-existing-server` 才复用服务。Playwright 在成功、失败和中断后清理自己启动的服务，保留借用的服务。安装后需提交 lockfile。
+
+公开 API：`listToolingCapabilities()`、`planToolingCapability(cwd, options)`、`applyToolingCapability(plan)`。JSON 使用 schemaVersion 1，字段名不随 CLI 语言变化。
+
+### 可选的 Storybook 组件库能力
+
+`repo tooling capability plan storybook --target <精确工作区名> --framework vue|react --component <命名导出> --example example.json --json` 预览独立的 `stories/<slug>` 工作区，再用 `repo tooling capability apply plan.json` 应用已审核计划。首版支持声明构建脚本、公开入口和明确运行时版本范围的 Vue 3、React 18/19 库。应用后安装依赖并提交 lockfile；发现与预览不会安装 Storybook 或浏览器。
+
+Vue 属性切换示例：`{"kind":"prop-update","prop":"msg","initial":"Hello Storybook","updated":"Updated component"}`。React 计数器示例：`{"kind":"click","args":{"initialCount":0},"alternateArgs":{"initialCount":4},"click":{"role":"button","name":"Increase"},"expectText":"1"}`。属性值采用 JSON 基础类型；交互断言验证所选组件的实际输出。生成 `Default`、`Alternate` 两种状态和 `Interaction` play 测试。
+
+运行 `pnpm build:storybook` 构建静态站点，再运行 `pnpm --filter @repoctl-stories/<slug> test:storybook:install` 显式安装 Chromium，最后用 `pnpm test:storybook` 执行无头交互测试。Turbo 先构建组件库依赖，并缓存 `storybook-static/**`；交互测试不缓存，输出 JUnit 报告。本地开发使用文档工作区的 `storybook` 脚本。独立的 Vitest/Vite 配置保留组件库原有测试、exports、运行时依赖与 tarball 内容。自有 stories/config 不被覆盖；生成文件出现差异会阻止应用，要求重新审核。不默认接入任何托管视觉回归服务。

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

@@ -59,18 +59,31 @@ export default defineMonorepoConfig({
 | --------------------------------- | --------------------------------------- |
 | `commands.init.preset`            | 控制初始化默认预设                      |
 | `commands.create.defaultTemplate` | 控制 `repo new <name>` 的默认模板       |
-| `commands.clean.autoConfirm`      | 清理命令是否默认确认                    |
+| `commands.clean.autoConfirm`      | 不提示并选择所有符合条件的工作区包      |
+| `commands.clean.dryRun`           | 预览删除及依赖变更，不写入文件          |
 | `commands.upgrade.skipOverwrite`  | 同步标准资产时是否保留已有 drifted 文件 |
 
 ## 查看当前配置
 
+可通过[组织预设包](./organization-presets.md)在多个仓库共享固定版本的 JSON 配置、模板、能力建议和显式受管工程文件。
+
 ```bash
 repo config inspect
 repo cfg i --json --out reports/config.json
 repo cfg i --markdown --redact --out reports/config.md
+repo config validate --json
+repo config inspect --command ai --set 'format="json"' --set 'force=false' --json
 ```
 
-`--redact` 适合把报告发到 issue、PR 或外部协作渠道。
+配置加载会在 CLI 执行，以及读取配置的 API 写入文件之前检查 repoctl 自有字段。未知字段、错误类型、非法枚举和冲突的覆盖策略会返回稳定规则 ID 与字段路径；可选字段请省略，不要填 `null`。ESLint、Stylelint、Commitlint、Vitest 原生透传、插件函数和 lint-staged 回调保留原有扩展边界，C12 配置工厂、继承配置和环境层继续可用。
+
+`config validate` 只读检查，失败退出码为 1。JSON 包含 `schemaVersion`、`valid`、`file` 和 `diagnostics`，诊断字段为 `id`、`path`、`actualType`、`expected`、`suggestion`。加载失败使用 `config.load-failed`，不输出配置代码抛出的任意内容。配置文件仍是受信任的 JavaScript，加载时会求值；本命令不会隔离配置代码自身的行为。
+
+`inspect --command` 支持 `ai`、`clean`、`create`、`deps`、`doctor`、`init`、`mirror`、`release`、`upgrade`，与命令执行复用同一个选项解析器。新增 `effective.values` 与逐字段 `effective.origins`，来源固定为 `default`、`project`、`cli`。重复传入 `--set 字段路径=JSON` 可只读预览配置覆盖；数组整体替换，显式 `false` 和空数组会保留。此处解释命令配置，实际发现的文件、选中的包和 `--all` 等运行参数请查看对应命令计划。
+
+配置 CLI 报告默认隐藏环境变量映射、脚本内容、工具原生配置及敏感键；`--redact` 额外替换 cwd、配置目录和 home 路径。程序化报告使用 `explainMonorepoConfig`、`validateConfigFile`。`loadMonorepoConfigDetails` 与原有 `inspectMonorepoConfig` 为需要回调的代码保留运行时对象，请勿直接序列化这些原始对象作为排障报告。
+
+旧版生成配置中的 `tooling.lintStaged.monorepoCommand` 应改为 `tooling.lintStaged.repoCommand`；旧字段此前被忽略，现在会明确报错。
 
 ## 配置的定位
 
@@ -88,3 +101,82 @@ repo cfg i --markdown --redact --out reports/config.md
 - [模板与创建](./templates.md)
 - [模板资产治理](./template-assets.md)
 - [报告与自动化输出](/zh/tasks/reports)
+
+## 清理工作区包
+
+先运行 `repo workspace clean --dry-run` 选择并预览；非交互场景可用
+`repo workspace clean --yes --dry-run` 预览全部符合条件的包。
+去掉 `--dry-run` 才会执行。交互初始不勾选任何包，空选或取消完全不写入。
+`--yes` 遵循 `ignorePackages` 和 `includePrivate`，不扩大到仓库文档、
+`.qoder` 或用户的全局 skills。
+即使从子包目录调用，也会读取工作区根目录的配置。
+
+预览 JSON 的 `deletions` 列出删除目录，`metadata` 列出根 `package.json`
+的依赖字段前后值。只有非空选择才会迁移旧的
+`devDependencies.@icebreakers/monorepo` 并确保 `devDependencies.repoctl`；
+默认保留已有 repoctl 版本，缺失时填入 `latest`，可通过
+`--pinned-version` 显式指定。无需修复时不重写 package.json。
+
+工作区之外的目录、符号链接目标或父路径、链接的根 package.json，以及
+会连带删除未选嵌套包的目标会在写入前被拒绝。此命令不修改消费者的依赖声明。
+
+`init` 检查上下文对应顶层 CLI，默认预设为 `standard`，项目配置和显式 CLI 选项依次覆盖默认值。公开 `init()` API 与 `workspace init` 保留仅初始化元数据的默认行为。来源路径中，动态键名内的点与反斜杠使用反斜杠转义。需要加载 repoctl 配置的命令会在执行前校验所有自有配置块，包括与当前命令无关的配置。
+
+## `commands.doctor`
+
+Doctor 先校验整份配置的 schema，再只执行选中的规则。未选策略即使存在违规，也不产生检查结果，但结构错误的配置始终会被拒绝。省略 `rules` 表示运行全部规则，`rules: []` 表示不运行任何规则。从包目录执行时，`config inspect --command doctor` 与 doctor 都使用工作区根配置，显式 CLI 规则选择优先于项目配置。
+
+在 `commands.doctor.suppressions` 配置有理由的抑制。每项必须提供 `id` 与非空 `reason`，可选 `path` 精确匹配 workspace 相对文件路径。可选 `expires` 使用 UTC 日期 `YYYY-MM-DD`，到期当天仍有效。JSON 保留原始发现的状态、`suppression`、`rawSummary`，以及全部抑制记录及命中数量。仅有效抑制从 `summary` 和 strict 退出码中排除；过期与未命中的记录仍会展示。
+
+```ts
+export default defineMonorepoConfig({
+  commands: {
+    doctor: {
+      rules: ['root-scripts', 'commit-hooks'],
+      suppressions: [{
+        id: 'commit-hooks',
+        reason: 'CI validates commits while the hooks migration is scheduled',
+        expires: '2026-12-31',
+      }],
+    },
+  },
+})
+```
+
+## TypeScript project references
+
+无需启用写入，即可检查现有引用图：
+
+```bash
+repo tooling references check --json
+repo tooling references plan > references-plan.json
+repo tooling references sync --dry-run
+repo tooling references apply references-plan.json
+repo tooling references sync
+```
+
+发现诊断或待同步差异时，`check` 返回退出码 1。所有命令输出带版本的 JSON。`check`、`plan`、`sync --dry-run` 不写文件；`apply` 和 `sync` 要求显式启用：
+
+```ts
+export default defineMonorepoConfig({
+  tooling: {
+    projectReferences: {
+      enabled: true,
+      root: 'tsconfig.json',
+      projects: ['packages/*/tsconfig.json', 'apps/*/tsconfig.build.json'],
+      exclude: ['packages/legacy/tsconfig.json'],
+      relations: [
+        { source: 'packages/app/tsconfig.json', target: 'packages/shared/tsconfig.json' },
+      ],
+    },
+  },
+})
+```
+
+根聚合配置和目标 tsconfig 必须已存在。不填 `projects` 时，发现实际 pnpm workspace 包（含 private 包）下的 `tsconfig.json`；没有 TS 配置的包会跳过。模式以 workspace 为基准，可选择同一包的多个配置。`exclude` 只排除受管发现，不删除已有手工引用。workspace 包以外的配置不自动入选，也不会把 repoctl 源仓库的引用清单复制给用户项目。
+
+根配置聚合选中的工程；只有显式 `relations` 才会添加工程之间的编译关系，npm 依赖不会自动变为 TS 引用。目标 workspace 需要安装 TypeScript，命令使用该编译器读取继承配置，在写入前检查缺失目标、循环、`composite`、声明输出与 `noEmit` 兼容性。不会强制启用 composite、修改编译选项、创建 tsconfig 或替换脚本。计划提供验证命令，优先保留包原有的 `typecheck`（包括 `vue-tsc`）入口；同步后运行这些命令验证真实源码。计划阶段检查配置，不代替完整源码编译。
+
+已有引用归用户维护。只有本功能新增的条目会记入 `.repoctl/typescript-references.json`，请将该文件与 tsconfig 一起提交。删除或排除项目只移除登记过的引用。用户编辑或移除受管条目会阻止同步：可以恢复条目，或明确删除登记记录，将该条目重新交给用户管理。保留 `references` 以外的 JSONC 字节、BOM 和换行风格，根引用与显式关系使用稳定的相对配置文件路径。
+
+保存的计划包含输入指纹和精确 diff。过期或被修改的计划在写入前失败；重复应用已完成的计划不产生变化。`.repoctl/typescript-references.lock` 进程锁覆盖重新校验、写入、验证、回滚和清理。多文件变更先准备备份，再统一替换并验证，失败会回滚。若并发编辑阻止安全回滚，错误会列出保留的恢复文件：保留这些文件，合并业务修改与原始备份，一致恢复归属登记后重新生成计划。进程被终止也可能留下 `.repoctl-references-*.bak`/`.tmp`；确认没有写入进程，恢复对应备份与归属登记后，再移除遗留锁；不会自动覆盖并发编辑。

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

@@ -0,0 +1,116 @@
+---
+title: 依赖版本一致性
+description: 比较工作区依赖声明，并应用审阅后的修复计划。
+---
+
+# 依赖版本一致性
+
+`repo deps check` 读取根目录和所有工作区清单，包含 private 包，按依赖名称、声明分区和配置的版本分组进行比较。它不查询 registry，也不自动选择最高版本。
+
+```bash
+pnpm exec repo deps check
+pnpm exec repo deps check --json
+pnpm exec repo deps plan typescript --section devDependencies --to '^5.7.0' --json > deps-plan.json
+pnpm exec repo deps apply deps-plan.json
+pnpm install --lockfile-only
+pnpm install --frozen-lockfile
+```
+
+`deps fix` 是 `deps plan` 的别名。生成计划始终只读，不加 `--dry-run` 也不会修改文件；只有 `deps apply` 才会修改清单。先审阅 JSON，再应用；锁文件更新和安装依赖由单独、显式的 pnpm 步骤完成。
+
+## 理解报告
+
+| 状态           | 含义                                   |
+| -------------- | -------------------------------------- |
+| `consistent`   | 声明相同，来源和范围可确认。           |
+| `equivalent`   | 文本不同，但允许的版本相同。           |
+| `compatible`   | 不同范围存在共同允许的版本。           |
+| `conflict`     | 没有任何版本同时满足所有声明。         |
+| `uncomparable` | 协议、来源或范围无法可靠比较。         |
+| `managed`      | workspace 引用由工作区和发布规则管理。 |
+| `exception`    | 显式例外，并显示保留原因。             |
+
+报告包含每条声明的清单路径、工作区目录、原始版本、依赖分区、协议和解析后的 semver 范围。出现等价文本差异、兼容范围差异或冲突时，检查以状态码 1 退出；例外及不可比较声明仍保留在报告中。JSON 字段名和状态值不随语言变化。
+
+`dependencies`、`devDependencies`、`peerDependencies`、`optionalDependencies` 独立比较。npm alias 保留真实来源包，指向不同来源的 alias 不可比较。默认和命名 catalog 会解析后参与比较，但修复不替换 catalog 引用。workspace、file、link、URL、Git 及未知声明仅报告。数字预发布版本遵循 semver 的预发布匹配规则。
+
+## 有意保留多个版本
+
+在工作区根目录的 `repoctl.config.ts` 中配置分组；从子包执行命令时也读取此配置：
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    deps: {
+      groups: [
+        {
+          name: 'vue2-adapter',
+          workspaces: ['packages/legacy-adapter'],
+          dependencies: ['vue'],
+          sections: ['dependencies', 'peerDependencies'],
+          reason: '适配器仍需支持 Vue 2 消费者',
+        },
+        {
+          name: 'canary',
+          workspaces: ['examples/canary'],
+          dependencies: ['vue'],
+          reason: '验证上游新版本兼容性',
+          ignore: true,
+        },
+      ],
+    },
+  },
+})
+```
+
+`workspaces` 精确匹配相对目录，`.` 表示根目录，不使用包名模式。`dependencies` 精确匹配依赖名。省略 `sections` 表示选择所有分区，各分区仍独立比较。每组必须有唯一名称和非空原因；重叠匹配会报错，未匹配的声明归入 `default`。标记 `ignore` 的例外不能修复。用 `--group vue2-adapter` 选择其他分组。
+
+## 应用与恢复
+
+计划必须指定依赖名、分区和目标声明，只接受可比较的普通 semver 或来源、协议相同的 npm alias。目标必须与整组声明存在共同允许的版本。冲突、未知协议及例外会阻止计划生成；有意保留的版本应拆分成组，不兼容升级应作为单独变更审阅。工具不自动选择版本或跨主版本升级。
+
+计划记录字段前后值、文件校验值，以及所有发现的清单、工作区设置和本地 repoctl 配置文件的校验值。应用时重新发现工作区并重新计算变更。输入被修改、新增包、篡改 diff、链接清单或部分已应用的计划都会在新增替换前被拒绝。计划绑定原工作区路径。
+
+只替换计划中的清单，保留无关字段及其他依赖分区；重复应用同一计划不会再次写入。工具先准备替换内容与原始备份，写入失败会回滚已完成的替换。若并发修改导致无法安全回滚，错误中会列出保留的 `.repoctl-deps-*.bak` 备份。进程中断后，检查清单旁的这些备份，按需恢复原文，清除遗留 `.tmp` 文件，再重新生成计划。随后可用 doctor 和 pnpm 安装步骤验证工作区。
+
+`repoctl` 导出 `checkDependencies(cwd)`、`planDependencyFix(cwd, options)`、`applyDependencyFixPlan(cwd, plan)`，以及对应的报告、配置和计划类型。
+
+## Peer 兼容性
+
+`repoctl deps peers --json` 比较每个工作区的 peer 承诺与显式 `devDependencies` 测试声明，包含 private 包和根包。必需 peer 没有测试声明时失败；optional peer 缺省时跳过，已声明测试版本时仍正常检查，不修改 pnpm 的自动安装或 strict-peer 策略。
+
+报告区分 `declared_range`、`declared_version`、`lockfile_version` 和 `workspace_version` 证据。测试声明完全包含于 peer 范围时仅判定声明兼容；部分重叠保持 `unknown`，直到可靠的 pnpm 锁定版本或内部工作区版本提供明确结果。过期/不支持的锁文件及未知协议不会被当成通过。支持默认/命名 catalog、同源 npm alias、workspace 别名、预发布和复合范围；不把自动安装的 peer 当作显式测试声明。
+
+JSON 包含稳定规则码、包和路径、peer 与测试声明、解析后的范围/版本、optional 状态及 workspace 中的 pnpm 策略值。单个测试或锁定版本不能证明全部支持范围；锁文件证据也不验证实际安装状态。检查不安装、不写文件，不替代现有发布 workspace 协议规则。失败返回非零；`--strict` 还会在 unknown 时失败。公开 API 为 `checkPeerDependencies(cwd)`。
+
+## 第三方依赖准入
+
+通过[依赖准入规则](./dependency-admission)按工作区允许或禁止第三方直接依赖，审核例外，并在 CI 中比较已审核基线。
+
+## pnpm catalog 巡检与迁移
+
+```bash
+pnpm exec repo deps catalog check --json
+pnpm exec repo deps catalog check --catalog legacy --json
+pnpm exec repo deps catalog plan typescript --section devDependencies --json > catalog-plan.json
+pnpm exec repo deps catalog plan react --section dependencies --group react18 --catalog react18 --to '^18.3.0' --json
+pnpm exec repo deps catalog apply catalog-plan.json --json
+pnpm install --lockfile-only
+pnpm install --frozen-lockfile
+```
+
+`catalog check` 巡检所有默认与命名 catalog、根包及 private workspace 消费者、缺失 catalog/条目，以及未使用条目。`catalog:` 与 `catalog:default` 等价。默认 catalog 可以位于 `catalog` 或 `catalogs.default`，同时声明两者属于 pnpm 配置错误。`--catalog` 选择直接版本绕过和迁移候选所采用的策略；引用完整性始终检查所有 catalog。直接声明的 peer 范围和显式 ignore 版本组不计为绕过。
+
+带版本结构的 JSON 包含精确清单路径、依赖分区、包名、原始声明、catalog 条目、消费者和稳定规则码。`missing_catalog`、`missing_entry`、`direct_declaration` 会令检查以状态码 1 退出。`unused_entry`、`uncomparable_entry` 是信息提示，未使用条目绝不会被自动删除。简单的 `overrides` 消费者（包括带版本的包选择器）会计入使用情况；嵌套 override 选择器明确报告 `unresolved_selector`，可能被引用的条目标记为 `usage_unknown`，不会误判为无人使用。
+
+迁移复用 `commands.deps.groups` 的依赖一致性版本组，继续区分依赖分区。相同或 semver 等价的声明可以自动提出一个 catalog 条目。兼容但不同的范围会返回 `needs_target`，需要通过 `--to` 提供**每个已选声明的共同子范围**，避免扩大允许版本或引入主版本升级。不兼容版本需要显式分组后选择不同 named catalog，或保留原样。迁移不访问 registry，也不选择最新版本。
+
+仅迁移普通 semver 范围和同源 npm alias；alias 的完整 `npm:source@range` 会保留在 catalog 中。workspace/file/link/Git/URL/tag 和未知声明保持原样。直接 `peerDependencies` 只报告，不能由此命令迁移。已有 catalog 引用保持原样；同一版本组混有其他 catalog 引用时需要明确分组。已有条目永不覆盖，即使显式 `--to` 与条目不同也会拒绝；应选择新 named catalog，或单独审阅影响全部消费者的条目变更。
+
+`catalog plan` 无论是否传 `--dry-run` 都只读。JSON 包含 YAML 与消费者清单的完整 before/after 内容、文件哈希、所有已发现输入哈希和规范化选择。审阅联动差异后再执行 `catalog apply`。YAML 通过 AST 修改以保留无关配置和注释；待编辑 catalog 映射若通过 YAML anchor/alias 共享，会明确拒绝，避免改变其他 alias 消费者。默认和命名 catalog 的已有存放位置保持不变，锁文件仍由显式 pnpm 步骤更新。
+
+应用绑定同一工作区和完整输入集合。过期 YAML、清单/策略变化、新增包、链接文件、部分应用及被篡改的计划内容都会在写入前被拒绝。YAML 与 JSON 复用依赖修复的暂存替换、原始备份和失败回滚。完整应用后的计划和重复迁移均无变化。如果回滚无法安全覆盖并发编辑，错误会列出保留的 `.repoctl-deps-*.bak` 原始备份；核对并恢复文件、清理残留临时文件，再生成新计划。并发编辑会保留。
+
+公共 API 为 `checkCatalogs(cwd, options?)`、`planCatalogMigration(cwd, options)` 和 `applyCatalogMigrationPlan(cwd, plan)`。协议语义参见 [pnpm catalogs](https://pnpm.io/catalogs)，有意版本组策略可参考 [Syncpack](https://syncpack.dev/)。

package/templates/vitepress/zh/reference/dependency-admission.md

@@ -0,0 +1,67 @@
+---
+title: 第三方依赖准入
+description: 离线检查第三方直接依赖的团队准入规则。
+---
+
+# 第三方依赖准入
+
+`repo deps policy` 读取根包及私有工作区的依赖声明，执行显式 allow/deny 规则，不修改 manifest 或 lockfile。它不访问 registry，不检查传递依赖，也不推断许可证或漏洞。
+
+```bash
+pnpm exec repo deps policy
+pnpm exec repo deps policy --json > dependency-policy.json
+pnpm exec repo deps policy --json --baseline reviewed-policy.json
+pnpm exec repo deps policy --strict
+```
+
+出现新增失败时退出码为 1；加上 `--strict` 后新增警告也返回 1。未提供基线时所有发现都视为新增。即使检查因违规返回非零，报告仍写入 stdout；配置或输入读取失败会报错，不会空白通过。
+
+## 配置规则
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  dependencyPolicy: {
+    rules: [
+      {
+        id: 'browser-sdk',
+        workspaces: ['apps/**'],
+        dependencies: ['legacy-sdk', '@obsolete/*'],
+        effect: 'deny',
+        sections: ['dependencies', 'optionalDependencies'],
+        reason: '浏览器应用统一使用仍在维护的 SDK',
+        alternative: 'modern-sdk',
+      },
+    ],
+    exceptions: [
+      {
+        rule: 'browser-sdk',
+        workspace: 'apps/legacy-web',
+        dependency: 'legacy-sdk',
+        section: 'dependencies',
+        reason: '负责团队正在迁移此应用',
+        expiresOn: '2027-01-31',
+      },
+    ],
+  },
+})
+```
+
+工作区选择器支持完整包名、相对目录、`directory/**`、根目录 `.` 和全部工作区 `*`。未匹配的选择器会警告。依赖模式支持完整名称或 `@scope/*`。`sections` 必须显式选择 `dependencies`、`devDependencies`、`peerDependencies`、`optionalDependencies`。每条规则需要唯一 ASCII ID 和理由；`severity` 默认为 `fail`，可设为 `warn`。
+
+同一工作区、同一分区的多条 allow 清单取并集。deny 同时匹配声明名称和 npm alias 的真实目标；allow 必须允许真实目标，不能通过替换 alias 名称绕过。显式 allow 与 deny 同时命中时产生 `admission-conflict`，规则顺序和例外都不能代替消除冲突。
+
+检查先解析 pnpm 默认或命名 catalog，再解析 npm alias。参与规则的声明如果存在缺失或歧义 catalog、无效 alias，将产生 `admission-resolution`。显式 `workspace:` 以及精确指向工作区目录的 file/link 声明被归为内部依赖，列在 `skipped`。普通 semver 恰好匹配本地包时，无法仅凭声明确定实际安装来源；预期内部依赖应改用 `workspace:`。其他 file、Git、URL 依赖按声明名称检查，不读取外部内容。报告不包含原始版本字符串、URL 或其中的凭据。
+
+首版读取 `package.json`，不支持或损坏的 manifest 会让检查失败。版本一致性分组 `commands.deps.groups` 与准入策略独立，不改变本项规则。
+
+## 例外与 CI 基线
+
+例外必须指定精确规则 ID、相对工作区目录、依赖声明键、分区和理由。一条 allow 清单的有效例外会显式允许该声明。到期日期按 UTC 当日结束计算，提前七天警告；过期后恢复拦截。失效的闲置例外会警告，实际使用的例外和理由保留在报告中。
+
+先审核或提交完整 `--json` 报告，再将它用作 `--baseline`。基线必须匹配当前策略指纹；修改规则或例外后需要重新审核基线。缺失、格式错误、重复发现或不兼容的基线都会失败。`--full` 显式忽略基线并全量检查。已有问题仍显示为 `baseline: "existing"`，退出码及 `summary.fail`/`warn` 只统计新增问题。基线是人工审核的数据文件，不是签名，也不能直接信任未经审核的 PR 产物。
+
+JSON 使用 `schemaVersion: 1`、`kind: "dependency-admission"`、稳定规则 ID、声明位置及策略 hash，不随 CLI 语言变化。发现保留规则理由和替代建议。只有配置了 `dependencyPolicy`，`repo doctor` 才执行全量准入检查；doctor 不会隐式读取基线。
+
+公共 API 为 `checkDependencyAdmission(cwd, { config?, baseline?, full?, now? })`，返回 `DependencyAdmissionReport`。`now` 允许集成方传入可确定的时钟。类型导出包括 `DependencyAdmissionConfig`、`DependencyAdmissionRule` 和 `DependencyAdmissionException`。

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

@@ -0,0 +1,25 @@
+# Dev Container 预设
+
+`repo tooling devcontainer` 为现有 pnpm 工作区预览可选开发容器。从子包运行也会定位到工作区根目录；预览和应用计划都不会启动 Docker 或安装依赖。
+
+```bash
+repo tooling devcontainer
+repo tooling devcontainer --json --out ../devcontainer-plan.json
+repo tooling devcontainer --apply ../devcontainer-plan.json
+```
+
+先审阅 JSON，再应用计划。预设在根 `.devcontainer` 下生成 `devcontainer.json`、`Dockerfile`、`setup.mjs` 和 `README.md`。已有自定义文件或根 `.devcontainer.json` 会阻止应用并保留原状。JSON 提供逐文件 hash 和 unified diff；完整应用过的计划再次执行不会写入。输入或目标变化后应重新预览。`--out` 只创建新计划文件，不覆盖已有文件。
+
+默认依次从 `24.21.0`、`22.23.3` 中选择满足根 `engines.node` 的固定版本。可用 `--node-version <精确版本>` 指定其他满足声明范围、至少为 `22.13.0` 的稳定 Node 版本。启动 Docker 时对应 `node:<版本>-bookworm` 镜像必须存在；预览不会访问 registry。根 `packageManager` 必须固定稳定 pnpm 版本，可以包含 Corepack integrity hash。
+
+生成配置后，通过 Dev Containers 扩展打开工作区，或主动运行 [Dev Containers CLI](https://github.com/devcontainers/cli)。创建容器会安装 Corepack `0.36.0`、启用 pnpm、检查其精确版本，并强制校验 engines 后安装工作区。存在 `pnpm-lock.yaml` 时使用 frozen lockfile；首次没有 lockfile 时创建它。Corepack 或安装失败会终止初始化。
+
+容器和远程命令均使用非 root 的 `node` 用户，Dev Containers 可将 UID 调整为宿主用户。pnpm store 位于源码外的独立命名卷。宿主和容器平台不同时使用独立 checkout，避免跨平台共享已安装的 `node_modules`。按应用需要修改 `forwardPorts`，例如 `[3000, 5173]`；默认不转发端口。初始化完成后主动启动开发服务。
+
+容器内依次运行生成项目的 `pnpm build`、`pnpm lint`、`pnpm typecheck`、`pnpm tsd`、`pnpm test` 和 `pnpm exec repo doctor`。已有容器文件由使用者维护；运行时要求变化后重新生成计划，可以审阅预设的差异。
+
+程序化 API 为 `repoctl` 导出的 `planDevContainer(cwd, { nodeVersion? })` 和 `applyDevContainerPlan(cwd, plan)`。应用使用公共文件事务，核对输入并按文件所有权恢复失败写入。容器预设独立于 `repo init` 的默认预设。
+
+进程中断后检查 `.repoctl/devcontainer.lock` 与 `.devcontainer` 下的 `.repoctl-upgrade-*.tmp`。先确认没有活跃写入进程，保留并发编辑并核对部分写入的文件，再移除残留锁并重新预览。普通失败仅删除本次应用拥有的文件和空目录。
+
+参考：[Dev Containers 配置规范](https://containers.dev/implementors/json_reference/)和[官方 Node/TypeScript 模板](https://github.com/devcontainers/templates/tree/main/src/typescript-node)。

package/templates/vitepress/zh/reference/execution-model.md

@@ -61,7 +61,7 @@ repoctl 的失败状态遵循阻塞优先：
 如果只是想知道会发生什么，先加 `--dry-run` 或输出计划：
 
 ```bash
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus --json --out plans/docs.json
 repo check --markdown --out reports/check-plan.md
 ```