@icebreakers/monorepo-templates 1.2.1 → 1.3.0

package/templates/vitepress/.vitepress/theme/index.ts

@@ -1,4 +1,12 @@
+import type { EnhanceAppContext, Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
+import HomePage from './components/HomePage.vue'
 import './tailwind.css'
+import './home/index.css'
 
-export default DefaultTheme
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }: EnhanceAppContext) {
+    app.component('HomePage', HomePage)
+  },
+} satisfies Theme

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

@@ -9,8 +9,8 @@ The documentation build generates `/llms.txt` and `/llms-full.txt`. English is t
 ## Usage
 
 ```text
-https://repo.icebreaker.top/llms.txt
-https://repo.icebreaker.top/llms-full.txt
+https://repoctl.icebreaker.top/llms.txt
+https://repoctl.icebreaker.top/llms-full.txt
 ```
 
 Use the compact index for discovery and the full file only when the consumer has enough context budget.

package/templates/vitepress/index.md

@@ -1,63 +1,9 @@
 ---
-layout: home
-
-hero:
-  name: repoctl
-  text: Short, stable workflows for pnpm monorepos
-  tagline: Initialize, diagnose, scaffold, verify, and upgrade practical Turborepo workspaces from one CLI.
-  image:
-    src: /logo.jpg
-    alt: repoctl logo
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /repoctl/getting-started
-    - theme: alt
-      text: Commands
-      link: /repoctl/commands
-    - theme: alt
-      text: AI Docs
-      link: /ai/
-
-features:
-  - title: Adopt existing workspaces
-    details: Run setup and doctor to align workspace patterns, root scripts, config files, and commit hooks.
-  - title: Create packages and apps
-    details: Scaffold libraries, apps, services, docs, and CLIs with interactive prompts or explicit template keys.
-  - title: Make checks repeatable
-    details: Preview and run local verification plans that match your lint, typecheck, build, test, and tsd workflow.
-  - title: AI-readable documentation
-    details: Generate llms.txt, llms-full.txt, and Markdown page output so AI coding tools can read the repoctl docs directly.
+layout: page
+aside: false
+pageClass: repoctl-home-page
+title: repoctl
+description: Task-first CLI for initializing, maintaining, validating, and releasing pnpm and Turborepo monorepos.
 ---
 
-## Fast Path
-
-```bash
-pnpm add -D repoctl
-pnpm exec repo init
-pnpm exec repo doctor
-pnpm exec repo new
-pnpm exec repo check
-```
-
-Generated repositories expose the same workflow as shorter root scripts:
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor
-pnpm run repo:new
-pnpm run repo:check
-```
-
-## Keep Reading
-
-- [repoctl Overview](./repoctl/index.md)
-- [Getting Started](./repoctl/getting-started.md)
-- [Adopt Existing Repositories](./repoctl/adopt-existing.md)
-- [Choose By Scenario](./repoctl/scenarios.md)
-- [Command Reference](./repoctl/commands.md)
-- [Configuration](./repoctl/config.md)
-- [Templates](./repoctl/templates.md)
-- [Workflows and CI](./repoctl/workflows.md)
-- [AI Docs: llms.txt](./ai/llms-txt.md)
-- [Knowledge Base](./knowledge/index.md)
+<HomePage locale="en" />

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"
@@ -40,8 +44,11 @@
     "debug": "^4.4.3",
     "mermaid": "^11.16.1",
     "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.10",
+    "wrangler": "^4.123.0"
   }
 }

package/templates/vitepress/repoctl/workflows.md

@@ -82,6 +82,41 @@ repo verify pre-push
 | Output for scripts                    | `--json --out <file>`                              |
 | Share a redacted report               | `--markdown --redact --out <file>`                 |
 
+## Documentation Worker
+
+The repoctl documentation is deployed as the `repoctl-docs` Cloudflare Worker. VitePress produces static assets, and Workers Static Assets serves them without an application handler or an `ASSETS` binding.
+
+### Workers Builds settings
+
+| Setting               | Value                                                   |
+| --------------------- | ------------------------------------------------------- |
+| Repository root       | Repository root                                         |
+| Production branch     | `main`                                                  |
+| Build command         | `pnpm --filter @icebreakers/website build`              |
+| Production deploy     | `pnpm --filter @icebreakers/website run deploy`         |
+| Non-production deploy | `pnpm --filter @icebreakers/website run deploy:preview` |
+
+The build command checks locale parity before VitePress generates `.vitepress/dist`. The Worker config serves the generated `404.html` for missing routes and keeps `public/_redirects` active for legacy `/en/*` links.
+
+### Preview, release, and rollback
+
+Run a local validation before changing production:
+
+```bash
+pnpm --filter @icebreakers/website build
+pnpm --filter @icebreakers/website run deploy:dry-run
+pnpm --filter @icebreakers/website exec wrangler dev
+```
+
+Non-production Workers Builds upload a preview version. Promote a validated build through the production deploy command. To roll back, inspect the version history and select the last known-good version:
+
+```bash
+pnpm --filter @icebreakers/website exec wrangler versions list
+pnpm --filter @icebreakers/website exec wrangler rollback <VERSION_ID>
+```
+
+`repoctl.icebreaker.top` is the canonical custom domain. Cloudflare Redirect Rules send `repo.icebreaker.top/*` and `monorepo.icebreaker.top/*` to the canonical host with a permanent redirect while preserving the path and query string.
+
 ## Keep Reading
 
 - [Command Reference](./commands.md)

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

@@ -0,0 +1,162 @@
+import { readdir, readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { homeContent } from '../.vitepress/home/content'
+
+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 = /(?:^|\/)why\/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[] = []
+
+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 (!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/thinking.md

@@ -5,3 +5,18 @@ This repository began as a reusable monorepo template. It has since evolved into
 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.
 
 See the [repoctl overview](./repoctl/index.md) for the current architecture and public entrypoints.
+
+## Documentation Deployment
+
+The documentation is a VitePress static site deployed as a Cloudflare Worker named `repoctl-docs`. Workers Static Assets serves the generated `.vitepress/dist` directory directly, including the custom 404 page and `_redirects` compatibility rules. There is no application Worker handler because the site has no dynamic request path.
+
+Cloudflare Workers Builds uses the repository root and runs these commands:
+
+```bash
+pnpm --filter @icebreakers/website build
+pnpm --filter @icebreakers/website run deploy
+```
+
+Non-production branches upload preview versions with `pnpm --filter @icebreakers/website run deploy:preview`. Before a production change, `pnpm --filter @icebreakers/website run deploy:dry-run` validates the asset manifest and Wrangler configuration. A production rollback uses `wrangler rollback <VERSION_ID>` after reviewing `wrangler versions list`.
+
+The canonical host is `https://repoctl.icebreaker.top`. The legacy `repo.icebreaker.top` and `monorepo.icebreaker.top` hosts are redirect-only entrypoints and preserve the original path and query string.

package/templates/vitepress/tools/changeset.md

@@ -1,25 +1,30 @@
 # pnpm Versioning
 
-This repository uses pnpm change intents and workspace versioning for releases.
+repoctl uses pnpm's native versioning workflow. A change intent records why a publishable package needs a release, and the repository ledger keeps that intent with the source change.
 
-## Daily Development
+## Record release intent
 
 ```bash
 pnpm change
-pnpm change status
+pnpm version -r
+pnpm publish -r
 ```
 
-Choose every publishable package whose public behavior changed and record the correct patch, minor, or major level. Private template workspaces are not release units.
+Choose the smallest version bump that matches the public contract. Removing a managed asset from a published template package is a minor change because consumers no longer receive that asset. Metadata-only URL changes are patch changes.
 
-## Release
+## Fixed packages
 
-```bash
-repo release stable prepare
-repo release stable publish
-```
+Some packages version together because they share a public contract. The versioning configuration defines those groups; do not manually align versions in package manifests.
+
+## Before publishing
 
-repoctl coordinates the release workflow, validates configuration, and publishes metadata. pnpm owns the versioning state and repository changelog storage.
+1. Build the affected packages.
+2. Run lint and typecheck.
+3. Run unit, integration, and end-to-end tests where available.
+4. Confirm the generated changelog and package contents match the intent.
 
-## Prerelease Lanes
+## Keep Reading
 
-Use `repo release pre enter <tag>`, `repo release pre publish`, and `repo release pre exit` for alpha, beta, rc, or next lanes.
+- [Publishing and Changelogs](../monorepo/publish.md)
+- [Workflows and CI](../repoctl/workflows.md)
+- [Template Assets](../repoctl/template-assets.md)

package/templates/vitepress/tools/husky.md

@@ -1,12 +1,50 @@
 # Husky
 
-Husky connects repository scripts to Git hooks. repoctl-managed workspaces use it as a thin entrypoint, keeping verification logic in versioned commands.
+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
 ```
 
-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.
+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
 
-`repo doctor` reports when Husky and lint-staged are only partially configured. `repo upgrade` can synchronize the managed defaults.
+- [lint-staged](./lint-staged.md)
+- [Workflows and CI](../repoctl/workflows.md)
+- [Verification](../repoctl/checks.md)

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

@@ -1,12 +1,39 @@
 # lint-staged
 
-lint-staged runs checks only for files included in the next commit.
+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.
 
-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.
+## Recommended responsibility
 
-```bash
+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
-pnpm exec repo verify staged-typecheck <files...>
 ```
 
-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.
+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](../repoctl/checks.md)
+- [Workflows and CI](../repoctl/workflows.md)

package/templates/vitepress/tools/pnpm.md

@@ -1,15 +1,47 @@
 # pnpm
 
-pnpm owns workspace discovery, dependency installation, script execution, and versioning configuration.
+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 --filter <package> build
-pnpm -r test
-pnpm change
-pnpm change status
+pnpm install --frozen-lockfile
 ```
 
-`pnpm-workspace.yaml` is the source of truth for package patterns and release groups. repoctl can diagnose missing patterns and synchronize recommended defaults, but pnpm remains the package manager.
+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
 
-Prefer exact workspace filters in automation and keep `packageManager` plus `engines.node` declared at the repository root.
+- [Turborepo](./turborepo.md)
+- [Managing A Monorepo](../monorepo/manage.md)
+- [repoctl Commands](../repoctl/commands.md)

package/templates/vitepress/tools/renovate.md

@@ -1,7 +1,31 @@
 # Renovate
 
-Renovate opens dependency update pull requests according to repository policy.
+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.
 
-Group related tooling updates, respect pnpm workspace constraints, and let the normal build, lint, typecheck, tsd, and test matrix validate each update. Avoid combining unrelated runtime and tooling upgrades when separate review makes regressions easier to isolate.
+## Repository policy
 
-repoctl does not replace Renovate. It provides the diagnostic and verification commands that Renovate pull requests can run consistently.
+```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)
+- [Workflows and CI](../repoctl/workflows.md)
+- [Troubleshooting](../repoctl/troubleshooting.md)

package/templates/vitepress/tools/turborepo.md

@@ -1,14 +1,40 @@
 # Turborepo
 
-Turborepo runs the monorepo task graph and caches repeatable work.
+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 build
-pnpm lint
-pnpm typecheck
-pnpm test
+pnpm turbo run build
+pnpm turbo run test --filter=repoctl
+pnpm turbo run lint typecheck
 ```
 
-Root scripts delegate to `turbo run`. Package scripts define the actual build, lint, typecheck, and test commands; `turbo.json` defines dependencies, inputs, outputs, and cache behavior.
+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
 
-Mark generated artifacts as task outputs and declare upstream dependencies such as `build` before tests that consume built packages.
+- [pnpm](./pnpm.md)
+- [Verification](../repoctl/checks.md)
+- [Managing A Monorepo](../monorepo/manage.md)

package/templates/vitepress/tsconfig.json

@@ -9,6 +9,13 @@
     "skipLibCheck": true
   },
   "include": [
+    ".vitepress/home/**/*.ts",
+    ".vitepress/navigation/**/*.ts",
+    ".vitepress/seo.ts",
+    ".vitepress/theme/**/*.ts",
+    ".vitepress/theme/**/*.vue",
+    ".vitepress/env.d.ts",
+    "scripts/**/*.ts",
     "why/examples/2.npm-basic-package/src/**/*.ts",
     "why/examples/3.npm-basic-package/src/**/*.ts"
   ]