@icebreakers/monorepo-templates 1.3.0 → 1.3.2

package/templates/vitepress/{tools → learn/tools}/pnpm.md

@@ -43,5 +43,5 @@ The `workspace:` protocol prevents accidentally resolving a local package from t
 ## Keep Reading
 
 - [Turborepo](./turborepo.md)
-- [Managing A Monorepo](../monorepo/manage.md)
-- [repoctl Commands](../repoctl/commands.md)
+- [Managing A Monorepo](/learn/monorepo/manage.md)
+- [repoctl Commands](/reference/commands)

package/templates/vitepress/{tools → learn/tools}/renovate.md

@@ -27,5 +27,5 @@ Do not rely on commit-message directives for a retired deployment provider. Depl
 ## Keep Reading
 
 - [pnpm](./pnpm.md)
-- [Workflows and CI](../repoctl/workflows.md)
-- [Troubleshooting](../repoctl/troubleshooting.md)
+- [Add checks to CI](/tasks/ci)
+- [Troubleshoot](/tasks/troubleshooting)

package/templates/vitepress/{tools → learn/tools}/turborepo.md

@@ -36,5 +36,5 @@ Use root scripts for the common entrypoints. The root script is the stable comma
 ## Keep Reading
 
 - [pnpm](./pnpm.md)
-- [Verification](../repoctl/checks.md)
-- [Managing A Monorepo](../monorepo/manage.md)
+- [Verification](/tasks/checks)
+- [Managing A Monorepo](/learn/monorepo/manage.md)

package/templates/vitepress/package.json

@@ -33,22 +33,22 @@
     "typecheck": "vue-tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "vue": "^3.5.41"
+    "vue": "^3.5.42"
   },
   "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",
+    "tsx": "^4.23.13",
     "vitepress": "^1.6.4",
     "vitepress-plugin-llms": "^1.13.5",
     "vitepress-plugin-mermaid": "^2.0.17",
-    "vue-tsc": "^3.3.10",
-    "wrangler": "^4.123.0"
+    "vue-tsc": "^3.3.11",
+    "wrangler": "^4.128.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

@@ -1,7 +1,9 @@
+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'])
@@ -83,7 +85,7 @@ async function existsAtLocale(sourceFile: string, href: string) {
 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)
+  const isExampleReadme = /(?:^|\/)learn\/packages\/examples\/.*\/README\.md$/.test(relativePath)
   if (isHome || isExampleReadme) {
     return errors
   }
@@ -115,6 +117,35 @@ 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}`)
@@ -132,6 +163,9 @@ for (const file of files) {
   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}`)
     }

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).

package/templates/vitepress/start/first-run.md

@@ -0,0 +1,39 @@
+# Your first run
+
+This is the smallest complete repoctl workflow. It makes one change, records evidence, and leaves you with a clear next action.
+
+## Install
+
+```bash
+pnpm add -D repoctl
+```
+
+## Initialize
+
+```bash
+pnpm exec repo init
+```
+
+Review the planned files before accepting writes. If the repository already has local conventions, use the adoption guide before allowing replacements.
+
+## Diagnose
+
+```bash
+pnpm exec repo doctor
+```
+
+The report checks the repository root, package manager, workspace layout, task runner, hooks, and release metadata. Fix the first reported blocker, then run the command again.
+
+## Plan checks
+
+```bash
+pnpm exec repo check --dry-run
+```
+
+This prints the commands that would run for lint, types, builds, tests, and package checks. Execute the plan only after it matches the checks your repository expects.
+
+## Next
+
+- New repository: [Create a package or app](/tasks/create-project).
+- Existing repository: [Adopt an existing workspace](/tasks/adopt-existing).
+- CI setup: [Add checks to CI](/tasks/ci).

package/templates/vitepress/start/index.md

@@ -0,0 +1,26 @@
+# Start here
+
+Use this section when repoctl is new to you. The shortest useful path is to install the CLI, run `repo init`, then run `repo doctor`.
+
+## Pick your first move
+
+- [Install and initialize](./install.md) if this is your first repoctl command.
+- [Run the first diagnosis](./diagnose.md) if repoctl is already installed.
+- [Choose the next task](./choose-next.md) after you have a diagnosis.
+
+## What repoctl does
+
+repoctl keeps common monorepo work in a small, predictable command set:
+
+| Need                            | Command                |
+| ------------------------------- | ---------------------- |
+| Add repository conventions      | `repo init`            |
+| Inspect repository health       | `repo doctor`          |
+| Create a package or app         | `repo new`             |
+| Plan checks before running them | `repo check --dry-run` |
+
+The CLI works with pnpm workspaces and understands Turborepo task graphs. It does not replace either tool.
+
+## Before you continue
+
+You need Node.js 22.12 or newer and pnpm available on your path. Run commands from the repository root so repoctl can read the workspace configuration.

package/templates/vitepress/{repoctl/getting-started.md → start/install.md}

@@ -1,4 +1,4 @@
-# Getting Started
+# Install and initialize
 
 This guide follows the order you would use when adding repoctl to a workspace.
 
@@ -110,7 +110,7 @@ pnpm exec repo upgrade --yes
 
 ## Next Steps
 
-- Adopt an existing repository: [Adopt Existing Repositories](./adopt-existing.md).
-- Set team defaults: [Configuration](./config.md).
-- Inspect template keys: [Templates](./templates.md).
-- Share diagnostic output: [Troubleshooting](./troubleshooting.md).
+- Adopt an existing repository: [Adopt an existing workspace](/tasks/adopt-existing).
+- Set team defaults: [Configuration](/reference/config).
+- Inspect template keys: [Templates](/reference/templates).
+- Share diagnostic output: [Troubleshoot](/tasks/troubleshooting).

package/templates/vitepress/{repoctl → tasks}/adopt-existing.md

@@ -1,4 +1,30 @@
-# Adopt Existing Repositories
+# Adopt an existing workspace
+
+## When To Use
+
+Use this task when a workspace already has scripts, hooks, or configuration that you need to keep while introducing repoctl.
+
+## Prerequisites
+
+- Run commands from the workspace root.
+- Commit or stash unrelated local changes.
+- Confirm that Node.js 22.12 or newer and pnpm are available.
+
+## Smallest Command
+
+```bash
+repo doctor --markdown --redact --out reports/baseline.md
+```
+
+## Expected Output
+
+The report records the detected package manager, workspace layout, task runner, tooling files, and release setup without exposing local paths.
+
+## Common Branches
+
+- Existing conventions are healthy: keep them and add only the missing managed assets.
+- A file is already managed locally: use `repo upgrade --no-overwrite` and review the diff.
+- Tooling is split across loaders: resolve the loader first, then rerun the diagnosis.
 
 repoctl is not only for newly generated repositories. It can be adopted gradually in existing pnpm workspaces by using diagnostics and conservative asset syncs.
 
@@ -128,6 +154,6 @@ or manually extend `pnpm-workspace.yaml`.
 
 ## Keep Reading
 
-- [Workflows and CI](./workflows.md)
-- [Troubleshooting](./troubleshooting.md)
-- [Configuration](./config.md)
+- [Add checks to CI](/tasks/ci)
+- [Troubleshoot](/tasks/troubleshooting)
+- [Configuration](/reference/config)

package/templates/vitepress/{repoctl → tasks}/checks.md

@@ -2,7 +2,33 @@
 outline: deep
 ---
 
-# repoctl Verification
+# Run checks
+
+## When To Use
+
+Use this task before a commit, before a pull request, or when you need to reproduce the repository's CI plan locally.
+
+## Prerequisites
+
+- Run `repo doctor` from the workspace root.
+- Install dependencies with the repository's pinned pnpm version.
+- Decide whether you need a fast check or the full delivery gate.
+
+## Smallest Command
+
+```bash
+repo check --dry-run
+```
+
+## Expected Output
+
+repoctl prints the selected tasks and the exact commands that would run. Remove `--dry-run` only after the plan matches the repository policy.
+
+## Common Branches
+
+- A staged file needs a focused check: use `repo check --staged`.
+- CI requires an artifact: add `--json --out reports/check-plan.json`.
+- You are preparing a release: use `repo check --full` after the fast check passes.
 
 `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.
 

package/templates/vitepress/{repoctl/workflows.md → tasks/ci.md}

@@ -1,4 +1,30 @@
-# Workflows and CI
+# Add checks to CI
+
+## When To Use
+
+Use this task when local commands are ready and the same repository policy must run on every pull request or branch.
+
+## Prerequisites
+
+- A passing `repo check --dry-run` plan.
+- A CI runner with Node.js, pnpm, and the repository lockfile.
+- Non-interactive credentials for any publish or release job.
+
+## Smallest Command
+
+```bash
+repo check --full --json --out reports/check-plan.json
+```
+
+## Expected Output
+
+CI receives a stable plan and can upload the JSON or Markdown report as an artifact. The same command remains runnable locally.
+
+## Common Branches
+
+- Pull requests need a fast gate: use `repo check --staged` or the repository's pre-commit mode.
+- Main branch needs a delivery gate: use `repo check --full`.
+- A release job needs a version plan: run `repo release --dry-run` before publishing.
 
 repoctl commands have two audiences: humans using short daily commands, and automation consuming stable reports.
 
@@ -119,6 +145,6 @@ pnpm --filter @icebreakers/website exec wrangler rollback <VERSION_ID>
 
 ## Keep Reading
 
-- [Command Reference](./commands.md)
-- [Troubleshooting](./troubleshooting.md)
-- [Command Aliases](./aliases.md)
+- [Command Reference](/reference/commands)
+- [Troubleshoot](/tasks/troubleshooting)
+- [Command Aliases](/reference/aliases)

package/templates/vitepress/tasks/create-project.md

@@ -0,0 +1,37 @@
+# Create a package or app
+
+Use this task when the workspace is ready and you need a new package, application, service, CLI, or documentation site.
+
+## Prerequisites
+
+- Run `repo doctor` from the workspace root.
+- Confirm the package name and destination directory.
+- Check the available template keys with `repo templates`.
+
+## Smallest command
+
+```bash
+repo new <name> --template <template>
+```
+
+For example:
+
+```bash
+repo new shared-config --template package
+```
+
+Use `--dry-run` when you want to inspect the file plan without writing anything.
+
+## Expected result
+
+repoctl prints the selected template, destination, and files it will create. After confirmation, the new project is added to the workspace and its package metadata is ready for the repository checks.
+
+## Common branches
+
+- Template key is unknown: run `repo templates` and choose an installed key.
+- Destination exists: choose a new name or inspect the existing project before using an overwrite option.
+- The project needs custom assets: create it first, then use [managed template assets](/reference/template-assets) for shared files.
+
+## Next
+
+Run [checks](/tasks/checks), then add the new project to the [CI workflow](/tasks/ci).

package/templates/vitepress/{repoctl/scenarios.md → tasks/index.md}

@@ -1,4 +1,4 @@
-# Choose By Scenario
+# Task index
 
 Start here when you know what you want to do, but not which repoctl command to use.
 
@@ -17,7 +17,7 @@ pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
-Keep reading: [Getting Started](./getting-started.md).
+Continue with [Install and initialize](/start/install).
 
 ## I Want To Adopt repoctl In An Existing Repo
 
@@ -29,7 +29,7 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```
 
-Keep reading: [Adopt Existing Repositories](./adopt-existing.md).
+Continue with [Adopt an existing workspace](/tasks/adopt-existing).
 
 ## I Want To Create A Package Or App
 
@@ -45,7 +45,7 @@ For daily development, root scripts also work:
 pnpm run repo:new -- sdk --template tsdown
 ```
 
-Keep reading: [Templates](./templates.md).
+Keep reading: [Templates](/reference/templates).
 
 ## I Want To Check Before Committing
 
@@ -62,7 +62,7 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo check --markdown --redact --out reports/check-plan.md
 ```
 
-Keep reading: [Workflows and CI](./workflows.md).
+Continue with [Add checks to CI](/tasks/ci).
 
 ## I Want To Debug CI Or Another Machine
 
@@ -72,7 +72,7 @@ pnpm exec repo env support --markdown --redact --out reports/support.md
 pnpm exec repo env snapshot --json --out reports/snapshot.json
 ```
 
-Keep reading: [Troubleshooting](./troubleshooting.md).
+Continue with [Troubleshoot](/tasks/troubleshooting).
 
 ## I Want To Sync Standard Assets
 
@@ -103,7 +103,7 @@ pnpm exec repo config inspect
 pnpm exec repo cfg i --json --out reports/config.json
 ```
 
-Keep reading: [Configuration](./config.md).
+Keep reading: [Configuration](/reference/config).
 
 ## I Want Shorter Commands
 
@@ -114,4 +114,4 @@ repo e support --markdown --redact
 repo cfg i
 ```
 
-Keep reading: [Command Aliases](./aliases.md).
+Keep reading: [Command Aliases](/reference/aliases).

package/templates/vitepress/tasks/release.md

@@ -0,0 +1,31 @@
+# Release packages
+
+Use this task when a change is ready to version and publish. Keep the release plan reviewable before any registry write.
+
+## Prerequisites
+
+- `repo doctor` reports a valid package manager and release configuration.
+- The working tree is clean except for the intended changes.
+- Every publishable change has a changeset or the repository's chosen intent file.
+
+## Smallest command
+
+```bash
+repo release --dry-run
+```
+
+Review the package groups, versions, changelog entries, and publish commands. Run the same command without `--dry-run` only after the plan is approved.
+
+## Expected result
+
+The release report names the packages that will change, the version decisions, and each subprocess that will run. A successful release also completes the configured post-publish hooks.
+
+## Common branches
+
+- Missing intent: add a changeset and rerun the plan.
+- Fixed group mismatch: inspect the package relationships before editing versions.
+- Registry authentication failure: refresh the local token and rerun the publish step; do not commit credentials.
+
+## Next
+
+Read [publishing and changelogs](/learn/monorepo/publish) for repository policy and [reports and output](/tasks/reports) for CI artifacts.