@icebreakers/monorepo-templates 1.2.0 → 1.3.0

package/templates/vitepress/.vitepress/theme/home/sections.css

@@ -0,0 +1,153 @@
+.repoctl-home__path-grid,
+.repoctl-home__automation {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 20px;
+}
+
+.repoctl-home__path-grid article {
+  padding: 28px;
+  background: color-mix(in srgb, var(--vp-c-bg-soft) 72%, transparent);
+  border-left: 3px solid var(--home-accent);
+}
+
+.repoctl-home__path-grid h3 {
+  font-size: 22px;
+}
+
+.repoctl-home__path-grid p,
+.repoctl-home__capability-grid p {
+  margin-top: 10px !important;
+}
+
+.repoctl-home__path-grid pre,
+.repoctl-home__automation pre,
+.repoctl-home__quickstart pre {
+  padding: 16px;
+  margin-top: 20px !important;
+  overflow-x: auto;
+  background: var(--vp-code-block-bg);
+  border: 1px solid var(--home-border);
+  border-radius: 6px;
+}
+
+.repoctl-home__path-grid a {
+  display: inline-block;
+  margin-top: 18px;
+  font-weight: 650;
+}
+
+.repoctl-home__capability-grid {
+  display: grid;
+  grid-template-columns: 1.3fr 0.7fr;
+  gap: 1px;
+  background: var(--home-border);
+  border: 1px solid var(--home-border);
+}
+
+.repoctl-home__capability-grid article {
+  min-height: 152px;
+  padding: 24px;
+  background: var(--vp-c-bg);
+}
+
+.repoctl-home__capability-grid article:nth-child(2),
+.repoctl-home__capability-grid article:nth-child(3) {
+  background: var(--vp-c-bg-soft);
+}
+
+.repoctl-home__commands dl {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0 32px;
+  margin: 0;
+}
+
+.repoctl-home__commands dl > div {
+  display: flex;
+  gap: 16px;
+  justify-content: space-between;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--home-border);
+}
+
+.repoctl-home__commands dd {
+  margin: 0;
+  color: var(--home-muted);
+  text-align: right;
+}
+
+.repoctl-home__automation {
+  align-items: center;
+  padding: 38px;
+  background: color-mix(in srgb, var(--vp-c-bg-soft) 80%, transparent);
+  border: 1px solid var(--home-border);
+  border-radius: 6px;
+}
+
+.repoctl-home__automation ul {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 18px;
+  padding: 0;
+  color: var(--home-muted);
+  list-style: none;
+}
+
+.repoctl-home__automation li::before {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  margin-right: 7px;
+  content: ' ';
+  background: var(--home-accent);
+  border-radius: 50%;
+}
+
+.repoctl-home__automation pre,
+.repoctl-home__quickstart pre {
+  margin: 0 !important;
+}
+
+.repoctl-home__quickstart {
+  display: grid;
+  grid-template-columns: 0.85fr 1.15fr;
+  gap: 24px;
+  align-items: end;
+}
+
+.repoctl-home__quickstart .repoctl-home__button {
+  grid-column: 2;
+  justify-self: start;
+}
+
+.repoctl-home__docs > div {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 1px;
+  background: var(--home-border);
+  border: 1px solid var(--home-border);
+}
+
+.repoctl-home__docs a {
+  min-height: 144px;
+  padding: 20px;
+  text-decoration: none !important;
+  background: var(--vp-c-bg);
+}
+
+.repoctl-home__docs a:hover {
+  background: var(--vp-c-bg-soft);
+}
+
+.repoctl-home__docs strong,
+.repoctl-home__docs span {
+  display: block;
+}
+
+.repoctl-home__docs span {
+  margin-top: 8px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--home-muted);
+}

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)