@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/package.json

@@ -2,18 +2,24 @@
   "name": "@icebreakers/website",
   "type": "module",
   "version": "0.0.1",
-  "description": "https://repo.icebreaker.top source code",
+  "private": true,
+  "description": "Documentation website for repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "homepage": "https://repo.icebreaker.top",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "url": "git+https://github.com/sonofmagic/repoctl.git",
     "directory": "templates/vitepress"
   },
   "bugs": {
-    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+    "url": "https://github.com/sonofmagic/repoctl/issues"
   },
-  "keywords": [],
+  "keywords": [
+    "repoctl",
+    "documentation",
+    "vitepress",
+    "monorepo"
+  ],
   "scripts": {
     "dev": "vitepress dev",
     "build": "vitepress build",

package/templates/vitepress/public/_redirects

@@ -0,0 +1,3 @@
+/en / 301
+/en/ / 301
+/en/* /:splat 301

package/templates/vitepress/repoctl/adopt-existing.md

@@ -1,17 +1,17 @@
-# 接入已有仓库
+# Adopt Existing Repositories
 
-repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
+repoctl is not only for newly generated repositories. It can be adopted gradually in existing pnpm workspaces by using diagnostics and conservative asset syncs.
 
-## 适合接入的仓库
+## Good Candidates
 
-优先满足这些条件：
+A repository is a good fit when:
 
-- 已经使用 pnpm 或准备迁移到 pnpm。
-- 有根 `package.json`。
-- 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
-- 希望统一 `repo:init`、`repo:doctor`、`repo:new`、`repo:check` 这类日常入口。
+- It already uses pnpm, or is ready to move to pnpm.
+- It has a root `package.json`.
+- It can use workspace folders such as `apps/*`, `packages/*`, or `examples/*`.
+- The team wants stable daily entries such as `repo:init`, `repo:doctor`, `repo:new`, and `repo:check`.
 
-如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
+If the repository is not yet a pnpm workspace, start with a minimal `pnpm-workspace.yaml`:
 
 ```yaml
 packages:
@@ -19,47 +19,47 @@ packages:
   - packages/*
 ```
 
-## 第一步：安装并初始化
+## Step 1: Install And Setup
 
 ```bash
 pnpm add -D repoctl
 pnpm exec repo init --yes
 ```
 
-`repo init --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+`repo init --yes` uses safe defaults. It adds recommended scripts and workspace patterns, but it does not blindly overwrite existing README, package.json, pnpm-workspace.yaml, or tooling files.
 
-## 第二步：保存第一次诊断
+## Step 2: Save The First Diagnostic Report
 
 ```bash
 pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
 pnpm exec repo doctor --json --out reports/doctor-before.json
 ```
 
-建议把第一次报告提交到 PR 评论或 artifact，而不是只看终端输出。
+Prefer saving the first report as a PR comment or CI artifact instead of relying only on terminal output.
 
-重点看这些项：
+Watch these checks:
 
-| 检查项                       | 常见问题                                         |
-| ---------------------------- | ------------------------------------------------ |
-| `package-json`               | 当前目录不是仓库根目录                           |
-| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                       |
-| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配    |
-| `tool-package`               | 没安装 `repoctl`                                 |
-| `root-scripts`               | 缺少 `repo:init/repo:new/repo:check/repo:doctor` |
-| `config-file`                | 残留已废弃的 `monorepo.config.ts`                |
-| `commit-hooks`               | Husky 和 lint-staged 只接了一半                  |
-| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖        |
+| Check                        | Common Issue                                                      |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `package-json`               | Current directory is not the repository root                      |
+| `workspace-manifest`         | `pnpm-workspace.yaml` is missing                                  |
+| `node-version`               | Root package has no `engines.node`, or the version does not match |
+| `tool-package`               | `repoctl` is not installed                                        |
+| `root-scripts`               | `repo:init/repo:new/repo:check/repo:doctor` scripts are missing   |
+| `config-file`                | A stale `monorepo.config.ts` file is still present                |
+| `commit-hooks`               | Husky and lint-staged are only partially configured               |
+| `workspace-package-coverage` | Some package.json files are not covered by workspace patterns     |
 
-## 第三步：保守同步标准资产
+## Step 3: Sync Conservatively
 
 ```bash
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```
 
-`--no-overwrite` 适合第一次接入：它同步缺失资产，但保留已有 drifted 文件。你可以在 PR diff 里逐项看哪些配置要进一步迁移。
+Use `--no-overwrite` for the first adoption pass. It syncs missing assets while preserving changed managed files.
 
-## 第四步：预览校验计划
+## Step 4: Preview Verification
 
 ```bash
 pnpm exec repo check --dry-run
@@ -67,11 +67,11 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo check --markdown --redact --out reports/check-plan.md
 ```
 
-先看 plan，再决定要不要接入 hook 或 CI。
+Review the plan before wiring hooks or CI.
 
-## 第五步：接入根脚本
+## Step 5: Use Root Scripts
 
-如果 `repo init` 已补齐根脚本，团队日常文档优先改成：
+After `repo init`, team docs can use:
 
 ```bash
 pnpm run repo:doctor
@@ -79,57 +79,55 @@ pnpm run repo:new -- sdk
 pnpm run repo:check
 ```
 
-CI 和自动化脚本仍建议写完整 CLI：
+CI and automation should still prefer explicit commands:
 
 ```bash
 pnpm exec repo doctor --strict
 pnpm exec repo check --full
 ```
 
-## 第六步：处理遗留配置
+## Step 6: Resolve Legacy Config
 
-### 遗留配置文件
+### Config Conflicts
 
-只保留：
+Keep only:
 
 ```txt
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 已不再加载；请改名为 `repoctl.config.ts`。
+`monorepo.config.ts` is no longer loaded at runtime; rename it to `repoctl.config.ts`.
 
-### 本地 tooling loader
+### Local Tooling Loader
 
-如果 `doctor` 提示 tooling 配置引用了本地源码 loader，使用：
+If `doctor` reports local source tooling loaders, migrate with:
 
 ```bash
 pnpm exec repo upgrade --yes
 ```
 
-这个命令会迁移到 `repoctl/tooling` 入口。简单的 `@icebreakers/commitlint-config`、`@icebreakers/eslint-config`、`@icebreakers/stylelint-config` wrapper 也会被保守转换为 `repoctl/tooling`，复杂 ESLint 配置会保留原有 rules、ignores、overrides 和额外 flat config 语义。
+The same migration also converts simple wrappers from `@icebreakers/commitlint-config`, `@icebreakers/eslint-config`, and `@icebreakers/stylelint-config` to `repoctl/tooling`. Complex ESLint configs keep their rules, ignores, overrides, and extra flat config semantics.
 
-### workspace patterns 不覆盖包
+### Workspace Pattern Gaps
 
-运行：
+Run:
 
 ```bash
 pnpm exec repo init --yes
 ```
 
-或手动扩展 `pnpm-workspace.yaml`。
+or manually extend `pnpm-workspace.yaml`.
 
-## 推荐 PR 结构
+## Recommended PR Shape
 
-存量仓库接入建议拆成小 PR：
+1. Install `repoctl` and add root scripts.
+2. Attach `doctor-before` and `doctor-after` reports.
+3. Sync or migrate tooling config.
+4. Wire hooks and CI.
+5. Verify scaffolding paths with `repo new --dry-run`.
 
-1. 安装 `repoctl`，补 `init/doctor/new/check` 根脚本。
-2. 提交 `doctor-before` 和 `doctor-after` 报告。
-3. 同步或迁移 tooling 配置。
-4. 接入 hook 和 CI。
-5. 用 `repo new --dry-run` 验证模板创建路径。
+## Keep Reading
 
-## 下一步
-
-- [工作流与 CI](./workflows.md)
-- [排障与报告](./troubleshooting.md)
-- [配置文件](./config.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Configuration](./config.md)

package/templates/vitepress/repoctl/aliases.md

@@ -1,10 +1,10 @@
-# 命令别名
+# Command Aliases
 
-repoctl 保留了一组短别名，方便熟悉后在终端里少打字。团队文档仍建议优先写完整命令，减少新人理解成本。
+repoctl keeps several aliases for terminal convenience. Team docs should still prefer full commands because they are easier for new users to read.
 
-## 包入口别名
+## Binary Aliases
 
-`repoctl` 包提供多个 bin：
+The `repoctl` package exposes these bins:
 
 ```bash
 repo
@@ -14,9 +14,9 @@ rc
 mo
 ```
 
-文档统一推荐 `repo`。
+The docs recommend `repo`.
 
-这些 bin 都进入同一套命令实现：
+These bins all enter the same command implementation:
 
 ```bash
 repoctl doctor
@@ -25,16 +25,16 @@ rc doctor
 mo doctor
 ```
 
-## 顶层命令别名
+## Top-Level Aliases
 
-| 推荐写法         | 短写        | 说明             |
-| ---------------- | ----------- | ---------------- |
-| `repo init`      | `repo init` | 初始化仓库默认值 |
-| `repo templates` | `repo tpl`  | 查看或检查模板   |
+| Recommended      | Alias       | Purpose                       |
+| ---------------- | ----------- | ----------------------------- |
+| `repo init`      | `repo init` | Initialize workspace defaults |
+| `repo templates` | `repo tpl`  | Inspect or check templates    |
 
-## 分组命令别名
+## Group Aliases
 
-| 完整命令                       | 短写            |
+| Full Command                   | Alias           |
 | ------------------------------ | --------------- |
 | `repo workspace`               | `repo ws`       |
 | `repo workspace upgrade`       | `repo ws up`    |
@@ -62,9 +62,9 @@ mo doctor
 | `repo ai prompt`               | `repo ai p`     |
 | `repo ai prompt create`        | `repo ai p new` |
 
-## 推荐使用原则
+## Recommendation
 
-- 新手教程写完整命令，例如 `pnpm exec repo doctor`。
-- 团队 README 写根脚本，例如 `pnpm run repo:doctor`。
-- 维护者脚本可以写短别名，但要在注释或文档里说明用途。
-- CI 里优先写完整命令，方便日志搜索。
+- Use full commands in onboarding docs.
+- Use `repo:*` root scripts in project README files, for example `pnpm run repo:doctor`.
+- Use short aliases in maintainer scripts only when the surrounding docs explain them.
+- Prefer full commands in CI logs.

package/templates/vitepress/repoctl/checks.md

@@ -1,86 +1,39 @@
 ---
-description: 说明 repoctl check 和 verify 的校验模式、pre-commit、staged typecheck、pre-push 与 commit-msg 链路。
+outline: deep
 ---
 
-# repoctl 校验链路
+# repoctl Verification
 
-`repo check` 是给人使用的统一入口，`repo verify` 是给 hook、CI 和脚本复用的底层入口。
+`repo check` provides stable, task-oriented entrypoints for local and CI verification. It preserves the underlying workspace scripts and reports which commands will run before execution.
 
-## 1. 模式速查
+## Modes
 
-| 命令                                         | 模式         | 实际动作                                                       |
-| -------------------------------------------- | ------------ | -------------------------------------------------------------- |
-| `repo check`                                 | `default`    | 执行 `repo verify pre-commit`                                  |
-| `repo check --staged`                        | `staged`     | 执行 pre-commit，并按 staged TypeScript/Vue 文件路由 typecheck |
-| `repo check --full`                          | `full`       | 按根脚本执行 `lint`、`typecheck`、`test`、`build` 中存在的任务 |
-| `repo check --edit-file .git/COMMIT_EDITMSG` | `commit-msg` | 执行 commit message 校验                                       |
+| Mode           | Command                         | Purpose                                             |
+| -------------- | ------------------------------- | --------------------------------------------------- |
+| Default        | `repo check`                    | Lightweight pre-commit verification                 |
+| Staged         | `repo check --staged`           | lint-staged plus workspace-aware type checking      |
+| Full           | `repo check --full`             | Root lint, typecheck, build, test, and tsd workflow |
+| Commit message | `repo check --edit-file <file>` | Validate a commit message file                      |
 
-预览模式不会真正执行校验：
+Use `--dry-run`, `--json`, or `--markdown` to inspect the plan without running it. `--out <file>` persists the result and `--redact` removes local paths.
 
-```bash
-repo check --dry-run
-repo check --full --json --out reports/check-plan.json
-repo check --markdown --redact --out reports/check-plan.md
-```
-
-## 2. pre-commit
-
-`repo verify pre-commit` 默认执行 lint-staged。适合在提交前只处理 staged 文件，避免每次提交都跑整仓校验。
-
-推荐的 lint-staged 行为包括：
-
-| 文件类型                   | 推荐处理                                 |
-| -------------------------- | ---------------------------------------- |
-| JS、TS、Vue                | ESLint 自动修复                          |
-| CSS、SCSS、Less、Vue style | Stylelint 自动修复                       |
-| TS、TSX、MTS、CTS、Vue     | 路由到最近 workspace 的 `typecheck` 脚本 |
-
-## 3. staged typecheck
-
-`repo verify staged-typecheck <files...>` 会根据文件路径向上查找最近的 workspace，并执行该 workspace 的 `typecheck`。
-
-```bash
-repo verify staged-typecheck packages/ui/src/button.ts templates/client/src/App.vue
-```
-
-它解决的是 monorepo 里常见的问题：一个提交只改了某个包，不应该让所有 Vue 和 TypeScript workspace 都重复跑类型检查。
-
-## 4. pre-push
-
-`repo verify pre-push` 面向推送前的完整保护。默认策略是：
-
-| 阶段         | 行为                                             |
-| ------------ | ------------------------------------------------ |
-| 根任务       | 强制执行整仓 `lint` 与 `typecheck`               |
-| 变更范围任务 | 按 workspace 改动范围补跑 `build`、`test`、`tsd` |
-| 失败处理     | 任一任务失败时停止并返回失败状态                 |
+## Pre-Commit
 
-如果 CI 想要更明确地复现整仓校验，可以使用：
+`repo verify pre-commit` runs the repository's staged-file policy. JavaScript, TypeScript, Vue, and style files are routed to the configured lint tasks.
 
-```bash
-repo check --full
-```
+## Staged Type Checking
 
-## 5. commit message
+`repo verify staged-typecheck <files...>` maps changed TypeScript and Vue files to their owning workspace. Vue packages use their `vue-tsc` based typecheck script; TypeScript packages use `tsc`.
 
-`repo verify commit-msg <file>` 用于 Git 的 `commit-msg` hook。未配置自定义命令时，它会执行：
+## Pre-Push
 
-```bash
-pnpm exec commitlint --edit <file>
-```
+`repo verify pre-push` is the comprehensive delivery gate. The repository policy builds first, then runs lint, type checks, type-level tests, and test suites against built artifacts.
 
-如果你只是手动验证当前提交信息，可以运行：
+## Automation
 
 ```bash
-repo check --edit-file .git/COMMIT_EDITMSG
+repo check --full --dry-run --json --out reports/check-plan.json
+repo check --staged --markdown --redact --out reports/check-plan.md
 ```
 
-## 6. 选择建议
-
-| 场景               | 推荐命令                                          |
-| ------------------ | ------------------------------------------------- |
-| 本地提交前快速复现 | `repo check`                                      |
-| lint-staged 调试   | `repo check --staged --dry-run`                   |
-| 推送前完整检查     | `repo check --full`                               |
-| CI 门禁            | `repo doctor --strict` 后接 `repo check --full`   |
-| 只生成计划         | `repo check --json --out reports/check-plan.json` |
+JSON field names and command IDs do not change with `--lang`; only human-readable descriptions do.

package/templates/vitepress/repoctl/commands.md

@@ -1,8 +1,8 @@
-# 命令速查
+# Command Reference
 
-这一页只保留 repoctl 高频、实用、容易记错的命令。
+This page focuses on high-value repoctl commands and options.
 
-## 最推荐入口
+## Main Entry
 
 ```bash
 pnpm exec repo init
@@ -12,7 +12,7 @@ pnpm exec repo new
 pnpm exec repo check
 ```
 
-模板生成仓库里的推荐根脚本：
+Generated repositories also expose:
 
 ```bash
 pnpm run repo:init
@@ -31,31 +31,20 @@ repo init --preset standard --force
 repo init --overwrite
 ```
 
-用途：
-
-- 初始化当前 workspace 的推荐默认值。
-- 默认不覆盖已有 README、package.json、pnpm-workspace.yaml 和 tooling 配置。
-- 追加缺失的 `apps/*`、`packages/*`、`examples/*` workspace patterns。
-- `--yes` 用于 CI 或非 TTY 环境。
-- 需要重写受管理文件时显式传 `--force` 或 `--overwrite`。
+Use it to initialize recommended workspace defaults. It skips existing managed files by default, appends missing workspace patterns, and supports non-interactive CI usage with `--yes`.
 
 ## `repo doctor`
 
 ```bash
 repo doctor
 repo doctor --strict
-repo doctor --json
 repo doctor --json --out reports/doctor.json
 repo doctor --markdown --redact --out reports/doctor.md
 ```
 
-用途：
+Use it to check root workspace files, Node compatibility, CLI dependency presence, `repo:*` root scripts, stale config files, and commit hooks.
 
-- 诊断当前目录是不是可直接开始使用的 monorepo 根目录。
-- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、遗留配置和提交链路。
-- `--strict` 会把 warning 也视为失败，适合 CI 门禁。
-- `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
-- `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
+`--strict` treats warnings as failures. `--redact` removes local absolute paths from shareable reports.
 
 ## `repo templates`
 
@@ -68,11 +57,7 @@ repo templates --json
 repo templates --markdown --out docs/templates.md
 ```
 
-用途：
-
-- 查看内置模板 key、分类、默认生成目录和用途。
-- 检查模板元数据和源目录健康状态。
-- 给脚本读取 JSON，或生成 Markdown 文档片段。
+Use it to discover built-in template keys, inspect metadata, verify template health, or generate machine-readable output.
 
 ## `repo new`
 
@@ -84,12 +69,7 @@ repo new docs --template vitepress --dry-run
 repo new docs --template vitepress --json --out plans/docs.json
 ```
 
-用途：
-
-- 交互式或直接创建新的 package、app、service、docs 或 CLI。
-- `--dry-run` 只预览模板、目标目录、package name 和输出文件。
-- `--json` 输出结构化创建计划，隐含 `--dry-run`。
-- 显式传入的 `--template` 会先校验，拼错时会失败并提示相近 key。
+Use it to create packages and apps. Explicit template keys are validated first; invalid keys fail with suggestions instead of silently falling back.
 
 ## `repo check`
 
@@ -103,13 +83,7 @@ repo check --json --out reports/check-plan.json
 repo check --markdown --redact --out reports/check-plan.md
 ```
 
-用途：
-
-- 运行推荐的本地校验入口。
-- `--staged` 偏 pre-commit。
-- `--full` 偏 pre-push。
-- `--edit-file` 用于 commit message 校验。
-- `--dry-run` 只预览将要执行的校验。
+Use it to preview or run the recommended local verification flow. `--staged` is closer to pre-commit; `--full` is closer to pre-push.
 
 ## `repo upgrade`
 
@@ -123,15 +97,9 @@ repo upgrade -i
 repo upgrade -s
 ```
 
-用途：
+Use it to sync standard assets and scripts. `--core` skips GitHub-related assets. `--no-overwrite` preserves changed files.
 
-- 同步仓库标准资产与脚本。
-- `--core` 只同步核心配置，跳过 GitHub 相关资产。
-- `-i` 交互式选择。
-- `--no-overwrite` / `-s` 保留已有 drifted 文件。
-- `--yes` / `--overwrite` 非交互覆盖 drifted 标准资产。
-
-## 分组命令
+## Grouped Commands
 
 ```bash
 repo ws ls
@@ -145,24 +113,8 @@ repo config inspect
 repo skills sync --codex
 ```
 
-分组命令适合维护者和自动化脚本。日常开发优先使用顶层命令。
-
-## 输出参数速查
-
-| 参数           | 适用命令                                     | 说明                                  |
-| -------------- | -------------------------------------------- | ------------------------------------- |
-| `--json`       | `doctor`、`check`、`templates`、`new`、`env` | 输出机器可读数据                      |
-| `--markdown`   | `doctor`、`check`、`templates`、`env`        | 输出适合 PR 和 issue 的 Markdown      |
-| `--out <file>` | 多数报告和计划命令                           | 写入文件，便于 CI artifact 或脚本读取 |
-| `--redact`     | `doctor`、`check`、`env`                     | 分享报告前脱敏本机路径                |
-| `--strict`     | `doctor`、`env snapshot`、`env support`      | warning 也会导致失败                  |
-| `--dry-run`    | `check`、`new`                               | 只看计划，不执行校验或写入文件        |
-
-## 继续阅读
+## Keep Reading
 
-- [执行模型](./execution-model.md)
-- [校验链路](./checks.md)
-- [doctor 诊断](./doctor.md)
-- [工作流与 CI](./workflows.md)
-- [报告与自动化输出](./reports.md)
-- [命令别名](./aliases.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/repoctl/config.md

@@ -1,16 +1,14 @@
-# 配置文件
+# Configuration
 
-repoctl 推荐在仓库根目录使用一个配置文件：
+repoctl recommends one root config file:
 
 ```txt
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 已不再作为运行时配置入口。迁移旧仓库时请改名为 `repoctl.config.ts`。
+`monorepo.config.ts` is no longer loaded at runtime. Rename it to `repoctl.config.ts` before running repoctl.
 
-repoctl 支持 `ts`、`mts`、`cts`、`js`、`mjs`、`cjs` 等配置文件后缀。新项目优先使用 `repoctl.config.ts`，这样能保留类型提示和更清晰的迁移路径。
-
-## 最小配置
+## Minimal Config
 
 ```ts
 import { defineMonorepoConfig } from 'repoctl'
@@ -24,15 +22,13 @@ export default defineMonorepoConfig({
 })
 ```
 
-设置 `commands.create.defaultTemplate` 后：
+After setting `commands.create.defaultTemplate`, this command can create a package without asking for the template:
 
 ```bash
 repo new utils
 ```
 
-会直接按默认模板创建，不再询问模板类型。
-
-## 常用配置
+## Common Config
 
 ```ts
 import { defineMonorepoConfig } from 'repoctl'
@@ -55,14 +51,14 @@ export default defineMonorepoConfig({
 })
 ```
 
-| 配置                              | 作用                                    |
-| --------------------------------- | --------------------------------------- |
-| `commands.init.preset`            | 控制初始化默认预设                      |
-| `commands.create.defaultTemplate` | 控制 `repo new <name>` 的默认模板       |
-| `commands.clean.autoConfirm`      | 清理命令是否默认确认                    |
-| `commands.upgrade.skipOverwrite`  | 同步标准资产时是否保留已有 drifted 文件 |
+| Option                            | Purpose                                         |
+| --------------------------------- | ----------------------------------------------- |
+| `commands.init.preset`            | Default setup preset                            |
+| `commands.create.defaultTemplate` | Default template for `repo new <name>`          |
+| `commands.clean.autoConfirm`      | Whether clean commands confirm by default       |
+| `commands.upgrade.skipOverwrite`  | Whether upgrade preserves changed managed files |
 
-## 查看当前配置
+## Inspect Config
 
 ```bash
 repo config inspect
@@ -70,21 +66,4 @@ repo cfg i --json --out reports/config.json
 repo cfg i --markdown --redact --out reports/config.md
 ```
 
-`--redact` 适合把报告发到 issue、PR 或外部协作渠道。
-
-## 配置的定位
-
-配置文件只负责团队默认值，不建议把一次性命令参数都写进去。
-
-推荐做法：
-
-- 团队长期一致的选择写进 `repoctl.config.ts`。
-- 临时行为用命令参数表达，例如 `--dry-run`、`--json`、`--out`。
-- 自动化脚本优先使用显式参数，减少隐藏状态。
-
-## 继续阅读
-
-- [执行模型](./execution-model.md)
-- [模板与创建](./templates.md)
-- [模板资产治理](./template-assets.md)
-- [报告与自动化输出](./reports.md)
+Use `--redact` before sharing reports in issues, PRs, or external support channels.