@icebreakers/monorepo-templates 1.2.1 → 1.3.1

package/templates/vitepress/learn/tools/husky.md

@@ -0,0 +1,50 @@
+# Husky
+
+Husky connects Git hooks to versioned repository scripts. In a repoctl workspace it is only a trigger: the actual verification lives in `repo verify` so people, CI, and hooks use the same contract.
+
+## Recommended hooks
+
+```sh
+# .husky/pre-commit
+pnpm exec repo verify pre-commit
+
+# .husky/commit-msg
+pnpm exec repo verify commit-msg "$1"
+
+# .husky/pre-push
+pnpm exec repo verify pre-push
+```
+
+Keep hooks small. A hook should select a repository task, not duplicate lint, typecheck, or build commands that will drift from CI.
+
+## What each hook protects
+
+| Hook         | Purpose                              | Usual scope                                         |
+| ------------ | ------------------------------------ | --------------------------------------------------- |
+| `pre-commit` | Fast feedback before a commit exists | Staged formatting, lint, and typecheck              |
+| `commit-msg` | Enforce the commit message contract  | The pending commit message file                     |
+| `pre-push`   | Catch broader integration failures   | Root checks and affected build, test, and tsd tasks |
+
+`repo doctor` reports incomplete Husky and lint-staged configuration. Use `repo upgrade --no-overwrite` to preview managed hook changes before accepting them.
+
+## Install and initialize
+
+```bash
+pnpm add -D husky
+pnpm exec husky init
+```
+
+The initializer creates `.husky/pre-commit`. Replace its generated command with the repository task instead of adding a second tool-specific pipeline.
+
+## Troubleshooting
+
+- Confirm the hook file is executable after a fresh clone.
+- Run the command from the hook directly before debugging Git.
+- Do not use interactive prompts in a hook.
+- Keep network calls and release work out of `pre-commit`.
+
+## Keep Reading
+
+- [lint-staged](./lint-staged.md)
+- [Add checks to CI](/tasks/ci)
+- [Verification](/tasks/checks)

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

@@ -0,0 +1,39 @@
+# lint-staged
+
+lint-staged runs focused checks against files staged for a commit. It keeps the pre-commit hook quick while preserving the same ESLint, Stylelint, and typecheck rules used elsewhere in the workspace.
+
+## Recommended responsibility
+
+Use lint-staged for checks that can safely operate on selected files. Keep full builds, integration tests, and release checks in `repo check --full` or CI.
+
+```js
+// lint-staged.config.js
+export default {
+  '*.{js,mjs,cjs,ts,tsx,vue}': ['eslint --fix'],
+  '*.{css,scss,less,vue}': ['stylelint --fix'],
+}
+```
+
+repoctl-managed workspaces also route staged TypeScript and Vue files into the appropriate workspace typecheck command. This matters because Vue packages need `vue-tsc`, while TypeScript-only packages use `tsc`.
+
+## Pair it with Husky
+
+```sh
+# .husky/pre-commit
+pnpm exec repo verify pre-commit
+```
+
+The hook selects repoctl's pre-commit workflow. That workflow can call lint-staged without embedding a second copy of the configuration in the hook file.
+
+## Safe fixes
+
+- Use `--fix` only for deterministic formatting and lint repairs.
+- Do not stage unrelated generated output from a task.
+- Run `pnpm lint` before opening a pull request because it covers more than staged files.
+- Test hook behavior from a clean index, not only with already-staged fixes.
+
+## Keep Reading
+
+- [Husky](./husky.md)
+- [Verification](/tasks/checks)
+- [Add checks to CI](/tasks/ci)

package/templates/vitepress/{tools → learn/tools}/llms-txt.md

@@ -4,4 +4,4 @@
 
 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.
 
-See the [repoctl AI documentation](../ai/llms-txt.md) for URLs and maintenance rules.
+See the [repoctl AI documentation](/ai/llms-txt) for URLs and maintenance rules.

package/templates/vitepress/learn/tools/pnpm.md

@@ -0,0 +1,47 @@
+# pnpm
+
+pnpm is the package manager used by repoctl workspaces. Its workspace protocol, content-addressable store, and filter syntax make it a practical fit for repositories with several packages and applications.
+
+## Install dependencies
+
+```bash
+pnpm install
+pnpm install --frozen-lockfile
+```
+
+Use the frozen form in CI. It proves that `package.json` files and the lockfile describe the same dependency graph.
+
+## Work with one workspace
+
+```bash
+pnpm --filter repoctl build
+pnpm --filter @icebreakers/monorepo test
+pnpm --filter './packages/*' lint
+```
+
+Filters are a routing tool, not a replacement for repository scripts. Prefer an existing package script over an ad hoc command when a task should be repeatable.
+
+## Link local packages
+
+```json
+{
+  "dependencies": {
+    "@icebreakers/monorepo": "workspace:*"
+  }
+}
+```
+
+The `workspace:` protocol prevents accidentally resolving a local package from the public registry during development.
+
+## Operational guidance
+
+- Pin the package manager in the root `package.json`.
+- Commit `pnpm-lock.yaml` for applications and monorepos.
+- Use `pnpm exec` for binaries supplied by the current workspace.
+- Use `pnpm --filter` for a scoped package command and Turbo for graph-wide task orchestration.
+
+## Keep Reading
+
+- [Turborepo](./turborepo.md)
+- [Managing A Monorepo](/learn/monorepo/manage.md)
+- [repoctl Commands](/reference/commands)

package/templates/vitepress/learn/tools/renovate.md

@@ -0,0 +1,31 @@
+# Renovate
+
+Renovate keeps dependencies current through reviewable pull requests. It is most useful when the configuration groups compatible updates, lets CI prove the upgrade, and avoids mixing unrelated ecosystem changes.
+
+## Repository policy
+
+```json
+{
+  "extends": ["config:recommended", "group:allNonMajor"],
+  "rangeStrategy": "bump",
+  "automerge": true,
+  "automergeType": "pr"
+}
+```
+
+The repository groups compatible minor and patch updates. Cloudflare Workers tooling is grouped separately because Wrangler and its Vite plugin have a deliberate compatibility relationship.
+
+## Review an update
+
+1. Read the package release notes when the update changes build, test, or deployment tooling.
+2. Run the normal build and validation sequence against the updated lockfile.
+3. Check generated assets and package metadata for unexpected churn.
+4. Merge only after the configured checks prove the update is compatible.
+
+Do not rely on commit-message directives for a retired deployment provider. Deployment behavior belongs in the active platform configuration and CI settings.
+
+## Keep Reading
+
+- [pnpm](./pnpm.md)
+- [Add checks to CI](/tasks/ci)
+- [Troubleshoot](/tasks/troubleshooting)

package/templates/vitepress/learn/tools/turborepo.md

@@ -0,0 +1,40 @@
+# Turborepo
+
+Turborepo turns package scripts into a dependency-aware task graph. repoctl workspaces use it for the repository-wide work that should be cached and run in dependency order.
+
+## Define task boundaries
+
+```json
+{
+  "tasks": {
+    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
+    "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
+    "typecheck": { "dependsOn": ["^typecheck"], "outputs": [] }
+  }
+}
+```
+
+`^build` means that a package must build its workspace dependencies before its own build starts. Declare outputs accurately so the cache can restore useful artifacts and ignore transient files.
+
+## Run graph-aware tasks
+
+```bash
+pnpm turbo run build
+pnpm turbo run test --filter=repoctl
+pnpm turbo run lint typecheck
+```
+
+Use root scripts for the common entrypoints. The root script is the stable command people and CI should remember; Turbo remains the graph executor beneath it.
+
+## Cache with care
+
+- Include configuration files that materially affect output in task inputs.
+- Keep secrets out of cached output.
+- Set `outputs: []` for validation-only tasks.
+- Use `--force` only when diagnosing cache behavior.
+
+## Keep Reading
+
+- [pnpm](./pnpm.md)
+- [Verification](/tasks/checks)
+- [Managing A Monorepo](/learn/monorepo/manage.md)

package/templates/vitepress/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "description": "Documentation website for repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
-  "homepage": "https://repo.icebreaker.top",
+  "homepage": "https://repoctl.icebreaker.top",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sonofmagic/repoctl.git",
@@ -22,11 +22,15 @@
   ],
   "scripts": {
     "dev": "vitepress dev",
-    "build": "vitepress build",
+    "check:locales": "tsx scripts/check-locales.ts",
+    "build": "pnpm run check:locales && vitepress build",
     "preview": "vitepress preview",
+    "deploy": "wrangler deploy",
+    "deploy:preview": "wrangler versions upload",
+    "deploy:dry-run": "wrangler deploy --dry-run",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "vue-tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "vue": "^3.5.41"
@@ -34,14 +38,17 @@
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
     "@tailwindcss/vite": "^4.3.3",
-    "cytoscape": "^3.34.1",
+    "cytoscape": "^3.34.2",
     "cytoscape-cose-bilkent": "^4.1.0",
-    "dayjs": "^1.11.21",
+    "dayjs": "^1.11.23",
     "debug": "^4.4.3",
-    "mermaid": "^11.16.1",
+    "mermaid": "^11.17.2",
     "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.12",
     "vitepress": "^1.6.4",
     "vitepress-plugin-llms": "^1.13.5",
-    "vitepress-plugin-mermaid": "^2.0.17"
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vue-tsc": "^3.3.11",
+    "wrangler": "^4.125.0"
   }
 }

package/templates/vitepress/public/brand/repoctl-lockup-dark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="300" height="64" viewBox="0 0 300 64" fill="none">
+  <g stroke="#F4F6FA" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"><path d="M14 14C22 14 24 24 32 32"/><path d="M14 32H32"/><path d="M14 50C22 50 24 40 32 32"/></g>
+  <g fill="#6F94FF"><circle cx="10" cy="14" r="4"/><circle cx="10" cy="32" r="4"/><circle cx="10" cy="50" r="4"/></g>
+  <path d="M38 22L48 32L38 42" stroke="#6F94FF" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <g stroke="#F4F6FA" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"><path d="M82 46V26M82 31C87 26 94 25 99 29"/><path d="M109 36H126C126 29 123 26 118 26C112 26 109 30 109 36C109 43 113 46 120 46H127"/><path d="M139 50V26M139 31C143 27 148 26 152 26C158 26 161 30 161 36C161 43 157 46 151 46C146 46 142 44 139 41"/><path d="M184 26C177 26 173 30 173 36C173 43 177 46 184 46C191 46 195 43 195 36C195 30 191 26 184 26Z"/><path d="M222 29C219 27 216 26 213 26C206 26 202 30 202 36C202 43 206 46 213 46C217 46 220 45 223 42"/><path d="M238 18V41C238 45 241 46 245 46H250M231 26H250"/><path d="M266 24V42C266 45 268 46 272 46H278"/></g>
+</svg>

package/templates/vitepress/public/brand/repoctl-lockup.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="300" height="64" viewBox="0 0 300 64" fill="none">
+  <g stroke="#20252D" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M14 14C22 14 24 24 32 32"/>
+    <path d="M14 32H32"/>
+    <path d="M14 50C22 50 24 40 32 32"/>
+  </g>
+  <g fill="#2457D6">
+    <circle cx="10" cy="14" r="4"/><circle cx="10" cy="32" r="4"/><circle cx="10" cy="50" r="4"/>
+  </g>
+  <path d="M38 22L48 32L38 42" stroke="#2457D6" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <g stroke="#20252D" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M82 46V26M82 31C87 26 94 25 99 29"/>
+    <path d="M109 36H126C126 29 123 26 118 26C112 26 109 30 109 36C109 43 113 46 120 46H127"/>
+    <path d="M139 50V26M139 31C143 27 148 26 152 26C158 26 161 30 161 36C161 43 157 46 151 46C146 46 142 44 139 41"/>
+    <path d="M184 26C177 26 173 30 173 36C173 43 177 46 184 46C191 46 195 43 195 36C195 30 191 26 184 26Z"/>
+    <path d="M222 29C219 27 216 26 213 26C206 26 202 30 202 36C202 43 206 46 213 46C217 46 220 45 223 42"/>
+    <path d="M238 18V41C238 45 241 46 245 46H250M231 26H250"/>
+    <path d="M266 24V42C266 45 268 46 272 46H278"/>
+  </g>
+</svg>

package/templates/vitepress/public/brand/repoctl-mark-dark.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none">
+  <g stroke="#F4F6FA" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M14 14C22 14 24 24 32 32"/>
+    <path d="M14 32H32"/>
+    <path d="M14 50C22 50 24 40 32 32"/>
+  </g>
+  <g fill="#6F94FF">
+    <circle cx="10" cy="14" r="4"/>
+    <circle cx="10" cy="32" r="4"/>
+    <circle cx="10" cy="50" r="4"/>
+  </g>
+  <path d="M38 22L48 32L38 42" stroke="#6F94FF" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/templates/vitepress/public/brand/repoctl-mark.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none">
+  <g stroke="#20252D" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M14 14C22 14 24 24 32 32"/>
+    <path d="M14 32H32"/>
+    <path d="M14 50C22 50 24 40 32 32"/>
+  </g>
+  <g fill="#2457D6">
+    <circle cx="10" cy="14" r="4"/>
+    <circle cx="10" cy="32" r="4"/>
+    <circle cx="10" cy="50" r="4"/>
+  </g>
+  <path d="M38 22L48 32L38 42" stroke="#2457D6" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/templates/vitepress/{repoctl → reference}/commands.md

@@ -115,6 +115,6 @@ repo skills sync --codex
 
 ## Keep Reading
 
-- [Workflows and CI](./workflows.md)
-- [Troubleshooting](./troubleshooting.md)
+- [Add checks to CI](/tasks/ci)
+- [Troubleshoot](/tasks/troubleshooting)
 - [Command Aliases](./aliases.md)

package/templates/vitepress/reference/index.md

@@ -0,0 +1,15 @@
+# Reference
+
+Use the reference when you already know the task and need exact command names, flags, configuration keys, or output rules.
+
+## Command surface
+
+- [Command reference](./commands.md)
+- [Configuration](./config.md)
+- [Execution model](./execution-model.md)
+- [Output formats](./output.md)
+- [Command aliases](./aliases.md)
+- [Templates](./templates.md)
+- [Managed template assets](./template-assets.md)
+
+The start and task sections intentionally hide advanced grouped commands until they are useful. This section documents the full surface without changing any CLI names.

package/templates/vitepress/reference/output.md

@@ -0,0 +1,37 @@
+# Output formats
+
+repoctl can print to the terminal or write stable artifacts for automation. Pick the format at the command boundary so the same task can serve a person and CI.
+
+## Terminal
+
+The default output is concise and human-readable. It shows the plan, the commands selected, and the final status.
+
+## JSON
+
+Use JSON when another tool needs structured fields:
+
+```bash
+repo check --full --dry-run --json --out reports/check-plan.json
+```
+
+Keep the file as a CI artifact when a later job needs to inspect the plan.
+
+## Markdown
+
+Use Markdown for code review and support requests:
+
+```bash
+repo env support --markdown --redact --out reports/support.md
+```
+
+The `--redact` flag removes local paths and sensitive values before sharing the report.
+
+## Common branches
+
+- Need to compare two runs: write both to separate files and compare the JSON.
+- Need a safe support bundle: use `repo env support --redact`.
+- Need a command plan only: combine `--dry-run` with the desired output format.
+
+## Next
+
+See [reports and output tasks](/tasks/reports) for a complete support workflow.

package/templates/vitepress/{repoctl → reference}/templates.md

@@ -123,6 +123,6 @@ The check validates duplicate sources and targets, existing source directories,
 
 ## Keep Reading
 
-- [Adopt Existing Repositories](./adopt-existing.md)
-- [Workflows and CI](./workflows.md)
+- [Adopt an existing workspace](/tasks/adopt-existing)
+- [Add checks to CI](/tasks/ci)
 - [Configuration](./config.md)

package/templates/vitepress/scripts/check-locales.ts

@@ -0,0 +1,196 @@
+import type { DocsLocale } from '../.vitepress/navigation/routes'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { homeContent } from '../.vitepress/home/content'
+import { routePath, routeSections } from '../.vitepress/navigation/routes'
+
+const root = process.cwd()
+const ignoredDirectories = new Set(['.vitepress', 'node_modules'])
+const ignoredFiles = new Set(['CHANGELOG.md'])
+
+function toPosixPath(value: string) {
+  return value.replaceAll('\\', '/')
+}
+
+function relativePath(file: string) {
+  return toPosixPath(path.relative(root, file))
+}
+
+async function markdownFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory)
+  const files = await Promise.all(entries.map(async (entry) => {
+    if (ignoredDirectories.has(entry)) {
+      return []
+    }
+    const absolute = path.join(directory, entry)
+    const metadata = await stat(absolute)
+    if (metadata.isDirectory()) {
+      return markdownFiles(absolute)
+    }
+    return entry.endsWith('.md') && !ignoredFiles.has(entry) ? [absolute] : []
+  }))
+  return files.flat()
+}
+
+function normalizeRoute(route: string) {
+  const withoutHash = toPosixPath(route).split('#', 1)[0]!.split('?', 1)[0]!
+  const withoutLocale = withoutHash.replace(/^\/zh(?=\/|$)/, '')
+  return withoutLocale.replace(/\/index(?:\.md)?$/, '/').replace(/\.md$/, '').replace(/\/$/, '') || '/'
+}
+
+function localLinks(markdown: string) {
+  const links = [...markdown.matchAll(/\[[^\]]+\]\(([^)\s]+)(?:\s[^)]*)?\)/g)]
+    .map(match => match[1]!)
+    .filter(link => !/^(?:https?:|mailto:|#)/.test(link))
+  return links
+}
+
+function headingLevels(markdown: string) {
+  const withoutCode = markdown.replace(/```[\s\S]*?```/g, '')
+  return [...withoutCode.matchAll(/^(#{1,6})\s+(?:\S.*|[\t\v\f \xA0\u1680\u2000-\u200A\u202F\u205F\u3000\uFEFF])$/gm)].map(match => match[1]!.length)
+}
+
+function fencedLanguages(markdown: string) {
+  return [...markdown.matchAll(/^```([^\s`]*)/gm)]
+    .map(match => match[1]!)
+    .filter((_, index) => index % 2 === 0)
+}
+
+function contentKeys(value: unknown, prefix = ''): string[] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return [prefix]
+  }
+  return Object.entries(value).flatMap(([key, nested]) => contentKeys(nested, prefix ? `${prefix}.${key}` : key))
+}
+
+async function existsAtLocale(sourceFile: string, href: string) {
+  const route = href.split('#', 1)[0]!.split('?', 1)[0]!
+  const resolved = route.startsWith('/')
+    ? path.join(root, route.replace(/^\//, ''))
+    : path.resolve(path.dirname(sourceFile), route)
+  const candidates = route.endsWith('/')
+    ? [path.join(resolved, 'index.md')]
+    : [resolved, `${resolved}.md`, path.join(resolved, 'index.md')]
+  return (await Promise.all(candidates.map(async (candidate) => {
+    try {
+      return (await stat(candidate)).isFile()
+    }
+    catch {
+      return false
+    }
+  }))).some(Boolean)
+}
+
+function validateDocument(relativePath: string, markdown: string) {
+  const errors: string[] = []
+  const isHome = relativePath === 'index.md' || relativePath === 'zh/index.md'
+  const isExampleReadme = /(?:^|\/)learn\/packages\/examples\/.*\/README\.md$/.test(relativePath)
+  if (isHome || isExampleReadme) {
+    return errors
+  }
+  const headings = headingLevels(markdown)
+  if (headings.filter(level => level === 1).length !== 1) {
+    errors.push(`${relativePath}: expected one H1`)
+  }
+  for (let index = 1; index < headings.length; index += 1) {
+    if (headings[index]! > headings[index - 1]! + 1) {
+      errors.push(`${relativePath}: heading level jumps from H${headings[index - 1]} to H${headings[index]}`)
+    }
+  }
+  const fenceLines = [...markdown.matchAll(/^```([^\s`]*)/gm)]
+  if (fenceLines.length % 2 !== 0) {
+    errors.push(`${relativePath}: unbalanced code fence`)
+  }
+  for (const language of fencedLanguages(markdown)) {
+    if (!language) {
+      errors.push(`${relativePath}: code fences require a language marker`)
+    }
+  }
+  return errors
+}
+
+const files = await markdownFiles(root)
+const englishFiles = files.filter(file => !relativePath(file).startsWith('zh/'))
+const chineseFiles = files.filter(file => relativePath(file).startsWith('zh/'))
+const englishPaths = new Set(englishFiles.map(relativePath))
+const chinesePaths = new Set(chineseFiles.map(file => relativePath(file).replace(/^zh\//, '')))
+const errors: string[] = []
+
+function routeToRelativeFile(route: string) {
+  const clean = route.replace(/^\//, '')
+  return clean.endsWith('/') ? `${clean}index.md` : `${clean}.md`
+}
+
+for (const locale of ['en', 'zh'] as const satisfies readonly DocsLocale[]) {
+  const prefix = locale === 'zh' ? '/zh' : ''
+  for (const section of routeSections) {
+    for (const item of section.items) {
+      const route = routePath(section.id, item.slug, locale)
+      const relative = routeToRelativeFile(route)
+      try {
+        if (!(await stat(path.join(root, relative))).isFile()) {
+          errors.push(`${locale}: route ${route} is not backed by a Markdown file`)
+        }
+      }
+      catch {
+        errors.push(`${locale}: route ${route} is not backed by a Markdown file`)
+      }
+    }
+  }
+  if (prefix) {
+    const englishRouteCount = routeSections.reduce((count, section) => count + section.items.length, 0)
+    if (englishRouteCount === 0) {
+      errors.push('route manifest is empty')
+    }
+  }
+}
+
+for (const relativePath of englishPaths) {
+  if (!chinesePaths.has(relativePath)) {
+    errors.push(`missing Chinese counterpart: zh/${relativePath}`)
+  }
+}
+for (const relativePath of chinesePaths) {
+  if (!englishPaths.has(relativePath)) {
+    errors.push(`missing English counterpart: ${relativePath}`)
+  }
+}
+
+for (const file of files) {
+  const relative = relativePath(file)
+  const markdown = await readFile(file, 'utf8')
+  errors.push(...validateDocument(relative, markdown))
+  const links = localLinks(markdown)
+  for (const href of links) {
+    if (/^(?:\/|\.\.\/)(?:repoctl|knowledge|monorepo|why|tools)(?:\/|$)/.test(href)) {
+      errors.push(`${relativePath}: link uses a retired route ${href}`)
+    }
+    if (!await existsAtLocale(file, href)) {
+      errors.push(`${relative}: unresolved internal link ${href}`)
+    }
+  }
+
+  const counterpart = relative.startsWith('zh/')
+    ? path.join(root, relative.slice(3))
+    : path.join(root, 'zh', relative)
+  const counterpartRoute = `/${normalizeRoute(relativePath(counterpart))}`
+  if (await existsAtLocale(file, counterpartRoute === '/' ? '/' : counterpartRoute)) {
+    continue
+  }
+  errors.push(`${relative}: counterpart route cannot be resolved`)
+}
+
+const englishKeys = contentKeys(homeContent.en).sort()
+const chineseKeys = contentKeys(homeContent.zh).sort()
+if (englishKeys.join('\n') !== chineseKeys.join('\n')) {
+  errors.push('homepage locale content keys differ')
+}
+
+if (errors.length > 0) {
+  console.error(`Locale parity failed with ${errors.length} issue(s):\n${errors.map(error => `- ${error}`).join('\n')}`)
+  process.exitCode = 1
+}
+else {
+  console.log(`Locale parity passed for ${englishPaths.size} English and ${chinesePaths.size} Chinese Markdown pages.`)
+}

package/templates/vitepress/start/choose-next.md

@@ -0,0 +1,14 @@
+# Choose the next task
+
+Start with the outcome you need. Each task page includes prerequisites, the smallest command, expected output, common branches, and a next step.
+
+| Outcome                                      | Go to                                                |
+| -------------------------------------------- | ---------------------------------------------------- |
+| Add repoctl to an existing workspace         | [Adopt an existing workspace](/tasks/adopt-existing) |
+| Create a package, app, service, or docs site | [Create a package or app](/tasks/create-project)     |
+| Run local verification before a commit       | [Run checks](/tasks/checks)                          |
+| Save output for a review or support request  | [Reports and output](/tasks/reports)                 |
+| Add the same workflow to CI                  | [Add checks to CI](/tasks/ci)                        |
+| Prepare a package release                    | [Release packages](/tasks/release)                   |
+
+For command flags and grouped commands, use the [command reference](/reference/commands). For the reasoning behind the workflow, read [how repoctl executes](/reference/execution-model).