@icebreakers/monorepo-templates 1.3.0 → 1.3.2

package/templates/vitepress/.vitepress/config.ts

@@ -7,15 +7,25 @@ import { createPageHead, siteOrigin } from './seo'
 
 export default withMermaid(defineConfig({
   outDir: '.vitepress/dist',
+  srcExclude: ['CHANGELOG.md', 'learn/packages/examples/**', 'zh/learn/packages/examples/**'],
   title: 'repoctl',
-  description: 'Task-first CLI for initializing, maintaining, validating, and releasing pnpm and Turborepo monorepos.',
+  description: 'A practical CLI guide for setting up, checking, and maintaining pnpm and Turborepo monorepos.',
   lastUpdated: true,
   cleanUrls: true,
   sitemap: { hostname: siteOrigin },
   transformHead: createPageHead,
-  head: [['link', { rel: 'icon', href: '/logo.jpg' }]],
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/brand/repoctl-mark.svg' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/brand/repoctl-mark-dark.svg', media: '(prefers-color-scheme: dark)' }],
+    ['link', { rel: 'alternate icon', type: 'image/x-icon', href: '/brand/favicon.ico' }],
+    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/brand/apple-touch-icon.png' }],
+  ],
   themeConfig: {
-    logo: '/logo.jpg',
+    logo: {
+      light: '/brand/repoctl-mark.svg',
+      dark: '/brand/repoctl-mark-dark.svg',
+      alt: 'repoctl',
+    },
     search: { provider: 'local' },
     socialLinks: [{ icon: 'github', link: 'https://github.com/sonofmagic/repoctl' }],
   },
@@ -24,7 +34,7 @@ export default withMermaid(defineConfig({
       label: 'English',
       lang: 'en-US',
       title: 'repoctl',
-      description: 'Task-first CLI for practical pnpm and Turborepo monorepos.',
+      description: 'A practical CLI guide for setting up, checking, and maintaining pnpm and Turborepo monorepos.',
       themeConfig: {
         nav: createNav('en'),
         outline: { label: 'On This Page', level: [2, 3] },
@@ -42,7 +52,7 @@ export default withMermaid(defineConfig({
       lang: 'zh-CN',
       link: '/zh/',
       title: 'repoctl',
-      description: '面向 pnpm 与 Turborepo monorepo 的任务型 CLI。',
+      description: '面向 pnpm 与 Turborepo monorepo 的实用 CLI 文档。',
       themeConfig: {
         nav: createNav('zh'),
         outline: { label: '目录', level: [2, 3] },
@@ -62,14 +72,14 @@ export default withMermaid(defineConfig({
       Tailwindcss(),
       llmstxt({
         title: 'repoctl',
-        description: 'Task-first CLI for pnpm and Turborepo monorepos. Simplified Chinese documentation is available under /zh/.',
+        description: 'Practical documentation for setting up, checking, and maintaining pnpm and Turborepo monorepos. Chinese documentation is available under /zh/.',
         domain: siteOrigin,
         ignoreFiles: [
           'zh/**',
           'en/**',
           'CHANGELOG.md',
           'thinking.md',
-          'why/examples/**',
+          'learn/packages/examples/**',
           '.vitepress/**',
           '**/node_modules/**',
           '**/internal/**',

package/templates/vitepress/.vitepress/home/content.ts

@@ -3,182 +3,90 @@ import type { HomeContent } from './types'
 
 const english = {
   hero: {
-    label: 'Task-first monorepo operations',
-    title: 'Run monorepo work.',
-    description: 'One CLI for setup, diagnosis, scaffolding, verification, and release work in pnpm monorepos.',
-    primary: { label: 'Get Started', href: '/repoctl/getting-started' },
-    secondary: { label: 'Explore Commands', href: '/repoctl/commands' },
-    imageAlt: 'A real repoctl doctor report for this workspace',
-  },
-  proof: ['pnpm-native', 'Turborepo-aware', 'Dry-run first', 'JSON and Markdown reports', 'Built for CI'],
-  lifecycle: {
-    title: 'A stable task lifecycle',
-    description: 'Each command answers one repository question and leaves a reportable result.',
-    steps: [
-      { title: 'Initialize', body: 'Install managed root assets and the standard repo scripts.', command: 'repo init' },
-      { title: 'Diagnose', body: 'Inspect workspace structure, tool versions, hooks, and release configuration.', command: 'repo doctor' },
-      { title: 'Create', body: 'Choose a known template and preview every planned file before writing.', command: 'repo new' },
-      { title: 'Verify', body: 'Route lint, typecheck, build, test, and tsd through one repeatable plan.', command: 'repo check' },
-      { title: 'Release', body: 'Record change intent, version fixed groups, publish, and complete hooks.', command: 'repo release' },
-    ],
-  },
-  paths: {
-    title: 'Start where your repository is',
-    description: 'repoctl supports greenfield workspaces and careful adoption without forcing the same migration path.',
-    items: [
-      {
-        title: 'Create a new workspace',
-        body: 'Bootstrap the managed conventions, then scaffold only the packages and applications you need.',
-        commands: ['pnpm create repoctl', 'pnpm run repo:new'],
-        href: '/repoctl/getting-started',
-        linkLabel: 'Create a repository',
-      },
-      {
-        title: 'Adopt an existing workspace',
-        body: 'Capture a redacted baseline, preview asset drift, and opt into changes in reviewable steps.',
-        commands: ['repo doctor --markdown --redact', 'repo upgrade --no-overwrite'],
-        href: '/repoctl/adopt-existing',
-        linkLabel: 'Plan an adoption',
-      },
-    ],
-  },
-  capabilities: {
-    title: 'Repository work with explicit boundaries',
-    description: 'The CLI keeps templates, managed assets, checks, and reports separate so automation stays understandable.',
+    label: 'repoctl documentation',
+    title: 'What does your repository need next?',
+    description: 'Initialize, diagnose, create, check, and release pnpm or Turborepo workspaces from one task-first CLI.',
+    primaryAction: { label: 'Get started', href: '/start/' },
+    secondaryAction: { label: 'Browse commands', href: '/reference/commands' },
+    imageAlt: 'A real repoctl doctor report showing repository checks and findings',
+  },
+  tasks: {
+    title: 'Choose a task',
+    description: 'Pick the result you need. Each path begins with the smallest safe command.',
     items: [
-      { title: 'Managed assets', body: 'Compare standard root files before replacing local decisions.' },
-      { title: 'Template catalog', body: 'Create libraries, CLIs, services, clients, and docs from named templates.' },
-      { title: 'Verification planner', body: 'See the exact task graph in dry-run, JSON, or Markdown before execution.' },
-      { title: 'Environment reports', body: 'Share redacted support context without leaking repository paths or tokens.' },
+      { title: 'Start a new repository', body: 'Set up the shared conventions before you add projects.', command: 'repo init', link: { label: 'Start here', href: '/start/' } },
+      { title: 'Adopt an existing repository', body: 'Inspect current choices and preview changes before writing.', command: 'repo doctor', link: { label: 'Plan adoption', href: '/tasks/adopt-existing' } },
+      { title: 'Create a package or app', body: 'Use a known template so names, scripts, and boundaries stay consistent.', command: 'repo new', link: { label: 'Create a project', href: '/tasks/create-project' } },
+      { title: 'Run a repository check', body: 'Plan lint, types, builds, and tests before a commit or CI run.', command: 'repo check', link: { label: 'Run checks', href: '/tasks/checks' } },
     ],
   },
-  commands: {
-    title: 'A command map you can remember',
-    description: 'Daily commands stay short. Explicit modes are available when scripts need stable output.',
-    items: [
-      { command: 'repo init', purpose: 'Set up conventions' },
-      { command: 'repo doctor', purpose: 'Diagnose repository health' },
-      { command: 'repo templates', purpose: 'Inspect available templates' },
-      { command: 'repo new', purpose: 'Create a workspace project' },
-      { command: 'repo check', purpose: 'Plan or run verification' },
-      { command: 'repo env', purpose: 'Report runtime context' },
-      { command: 'repo upgrade', purpose: 'Reconcile managed assets' },
-      { command: 'repo release', purpose: 'Version and publish packages' },
+  firstRun: {
+    title: 'Three commands to a useful baseline',
+    description: 'Install repoctl, initialize its managed defaults, then diagnose the workspace.',
+    steps: [
+      { title: 'Install', command: 'pnpm add -D repoctl', body: 'Keep repoctl with the repository so teammates and CI use the same version.' },
+      { title: 'Initialize', command: 'pnpm exec repo init', body: 'Review the file plan before adding managed scripts and configuration.' },
+      { title: 'Diagnose', command: 'pnpm exec repo doctor', body: 'Use the first blocker as your next task. Run the diagnosis again after each fix.' },
     ],
   },
-  automation: {
-    title: 'Readable by people and automation',
-    description: 'Preview destructive work, write stable artifacts, and redact support output at the command boundary.',
-    formats: ['Terminal', 'JSON', 'Markdown', 'File output'],
-    code: 'repo check --full --dry-run --json --out reports/check-plan.json\nrepo env support --markdown --redact --out reports/support.md',
-  },
-  quickstart: {
-    title: 'Get to a useful diagnosis first',
-    description: 'Install repoctl locally, inspect the repository, then choose the next task from evidence.',
-    code: 'pnpm add -D repoctl\npnpm exec repo init\npnpm exec repo doctor\npnpm exec repo check --dry-run',
-    link: { label: 'Read the full setup guide', href: '/repoctl/getting-started' },
+  evidence: {
+    title: 'See the plan before the repository changes',
+    description: 'Preview work, redact local paths, and keep the exact command sequence with the report.',
+    code: 'pnpm exec repo new docs --template vitepress --dry-run\npnpm exec repo check --dry-run\npnpm exec repo doctor --markdown --redact',
+    link: { label: 'See how diagnosis works', href: '/start/diagnose' },
   },
-  docs: {
-    title: 'Continue with the task in front of you',
-    description: 'The documentation is organized by repository outcome, with deeper references when you need implementation details.',
+  layers: {
+    title: 'Continue with the decision in front of you',
+    description: 'Move from the current task to the level of detail you need.',
     items: [
-      { label: 'Choose by scenario', href: '/repoctl/scenarios', body: 'Map a repository goal to the smallest command sequence.' },
-      { label: 'Execution model', href: '/repoctl/execution-model', body: 'Understand planning, writes, subprocesses, and output.' },
-      { label: 'Configuration', href: '/repoctl/config', body: 'Set defaults without hiding command-line overrides.' },
-      { label: 'Workflows and CI', href: '/repoctl/workflows', body: 'Build local and automated verification paths.' },
-      { label: 'Troubleshooting', href: '/repoctl/troubleshooting', body: 'Diagnose common setup, template, and release failures.' },
-      { label: 'AI documentation', href: '/ai/', body: 'Give coding tools concise or full Markdown context.' },
+      { title: 'Daily tasks', body: 'Adoption, project creation, checks, CI, reports, releases, and troubleshooting.', link: { label: 'Open tasks', href: '/tasks/' } },
+      { title: 'Understand the system', body: 'Monorepo boundaries, modern npm packages, templates, and the tools underneath.', link: { label: 'Open Learn', href: '/learn/' } },
+      { title: 'Look up exact behavior', body: 'Commands, configuration, output formats, aliases, and execution details.', link: { label: 'Open Reference', href: '/reference/' } },
     ],
   },
 } satisfies HomeContent
 
 const chinese = {
   hero: {
-    label: '面向任务的 monorepo 操作入口',
-    title: '运行 monorepo 工作。',
-    description: '用一套 CLI 完成 pnpm monorepo 的初始化、诊断、创建、校验与发布。',
-    primary: { label: '快速开始', href: '/zh/repoctl/getting-started' },
-    secondary: { label: '查看命令', href: '/zh/repoctl/commands' },
-    imageAlt: 'repoctl 对当前仓库生成的真实 doctor 报告',
-  },
-  proof: ['原生支持 pnpm', '理解 Turborepo', '优先 dry-run', 'JSON 与 Markdown 报告', '适用于 CI'],
-  lifecycle: {
-    title: '稳定的任务生命周期',
-    description: '每条命令回答一个仓库问题，并留下可以复查和保存的结果。',
-    steps: [
-      { title: '初始化', body: '安装受管根目录资产和标准 repo 脚本。', command: 'repo init' },
-      { title: '诊断', body: '检查 workspace 结构、工具版本、hooks 与发布配置。', command: 'repo doctor' },
-      { title: '创建', body: '选择已知模板，在写入前预览完整文件计划。', command: 'repo new' },
-      { title: '校验', body: '用一份可复现计划串联 lint、typecheck、build、test 与 tsd。', command: 'repo check' },
-      { title: '发布', body: '记录变更意图、更新固定版本组、发布并执行收尾 hook。', command: 'repo release' },
-    ],
-  },
-  paths: {
-    title: '从仓库当前状态开始',
-    description: 'repoctl 同时支持新建项目和渐进接入，不强迫两类仓库走同一条迁移路线。',
-    items: [
-      {
-        title: '创建新 workspace',
-        body: '先生成受管约定，再按需创建具体的包和应用。',
-        commands: ['pnpm create repoctl', 'pnpm run repo:new'],
-        href: '/zh/repoctl/getting-started',
-        linkLabel: '创建仓库',
-      },
-      {
-        title: '接入已有 workspace',
-        body: '保存脱敏基线，预览资产差异，再用可审查的小步骤逐项接入。',
-        commands: ['repo doctor --markdown --redact', 'repo upgrade --no-overwrite'],
-        href: '/zh/repoctl/adopt-existing',
-        linkLabel: '制定接入计划',
-      },
-    ],
-  },
-  capabilities: {
-    title: '边界清楚的仓库任务',
-    description: '模板、受管资产、校验与报告相互独立，让自动化保持透明。',
+    label: 'repoctl 文档',
+    title: '仓库下一步，该做什么？',
+    description: '用一个任务型 CLI 初始化、诊断、创建、校验与发布 pnpm 和 Turborepo 工作区。',
+    primaryAction: { label: '开始使用', href: '/zh/start/' },
+    secondaryAction: { label: '查看命令', href: '/zh/reference/commands' },
+    imageAlt: '真实的 repoctl doctor 报告，展示仓库检查结果与发现项',
+  },
+  tasks: {
+    title: '选择一项任务',
+    description: '选择你要得到的结果，每条路径都从最小的安全命令开始。',
     items: [
-      { title: '受管资产', body: '覆盖本地决策前，先比较标准根目录文件。' },
-      { title: '模板目录', body: '按名称创建类库、CLI、服务、客户端与文档站。' },
-      { title: '校验计划', body: '执行前通过 dry-run、JSON 或 Markdown 查看完整任务图。' },
-      { title: '环境报告', body: '隐藏仓库路径和 token 后再共享排障上下文。' },
+      { title: '新建仓库', body: '先建立共享约定，再开始添加项目。', command: 'repo init', link: { label: '从这里开始', href: '/zh/start/' } },
+      { title: '接入已有仓库', body: '先检查当前决策，预览变化后再写入。', command: 'repo doctor', link: { label: '制定接入计划', href: '/zh/tasks/adopt-existing' } },
+      { title: '创建包或应用', body: '使用已知模板，让名称、脚本和边界保持一致。', command: 'repo new', link: { label: '创建项目', href: '/zh/tasks/create-project' } },
+      { title: '运行仓库校验', body: '提交或运行 CI 前，先规划 lint、类型、构建和测试。', command: 'repo check', link: { label: '运行校验', href: '/zh/tasks/checks' } },
     ],
   },
-  commands: {
-    title: '记得住的命令地图',
-    description: '日常入口保持简短，脚本需要稳定输出时再使用显式模式。',
-    items: [
-      { command: 'repo init', purpose: '建立仓库约定' },
-      { command: 'repo doctor', purpose: '诊断仓库健康状态' },
-      { command: 'repo templates', purpose: '查看可用模板' },
-      { command: 'repo new', purpose: '创建 workspace 项目' },
-      { command: 'repo check', purpose: '规划或执行校验' },
-      { command: 'repo env', purpose: '输出运行环境' },
-      { command: 'repo upgrade', purpose: '同步受管资产' },
-      { command: 'repo release', purpose: '更新版本并发布' },
+  firstRun: {
+    title: '三条命令，建立可用基线',
+    description: '安装 repoctl，初始化受管默认值，再诊断当前工作区。',
+    steps: [
+      { title: '安装', command: 'pnpm add -D repoctl', body: '把 repoctl 保存在仓库中，让成员和 CI 使用相同版本。' },
+      { title: '初始化', command: 'pnpm exec repo init', body: '写入受管脚本和配置前，先检查文件计划。' },
+      { title: '诊断', command: 'pnpm exec repo doctor', body: '把第一个阻塞项作为下一项任务，修复后再次运行诊断。' },
     ],
   },
-  automation: {
-    title: '同时服务人和自动化',
-    description: '在命令边界预览写入、保存稳定产物，并对支持信息执行脱敏。',
-    formats: ['终端', 'JSON', 'Markdown', '文件输出'],
-    code: 'repo check --full --dry-run --json --out reports/check-plan.json\nrepo env support --markdown --redact --out reports/support.md',
-  },
-  quickstart: {
-    title: '先得到一份有效诊断',
-    description: '本地安装 repoctl，检查仓库，再根据证据选择下一项任务。',
-    code: 'pnpm add -D repoctl\npnpm exec repo init\npnpm exec repo doctor\npnpm exec repo check --dry-run',
-    link: { label: '阅读完整安装指南', href: '/zh/repoctl/getting-started' },
+  evidence: {
+    title: '仓库变化前，先看清执行计划',
+    description: '预览操作、脱敏本地路径，并让报告保留准确的命令顺序。',
+    code: 'pnpm exec repo new docs --template vitepress --dry-run\npnpm exec repo check --dry-run\npnpm exec repo doctor --markdown --redact',
+    link: { label: '了解诊断流程', href: '/zh/start/diagnose' },
   },
-  docs: {
-    title: '继续处理眼前的任务',
-    description: '文档按仓库目标组织，需要实现细节时再进入对应参考页。',
+  layers: {
+    title: '沿着当前决策继续深入',
+    description: '从手头任务出发，只进入你现在需要的细节层级。',
     items: [
-      { label: '按场景选命令', href: '/zh/repoctl/scenarios', body: '把仓库目标映射为最短命令链路。' },
-      { label: '执行模型', href: '/zh/repoctl/execution-model', body: '理解计划、写入、子进程和输出。' },
-      { label: '配置文件', href: '/zh/repoctl/config', body: '设置默认值，同时保留命令行覆盖。' },
-      { label: '工作流与 CI', href: '/zh/repoctl/workflows', body: '建立本地和自动化校验路径。' },
-      { label: '排障', href: '/zh/repoctl/troubleshooting', body: '诊断常见的安装、模板与发布问题。' },
-      { label: 'AI 文档', href: '/zh/ai/', body: '为编程工具提供精简或完整 Markdown 上下文。' },
+      { title: '日常任务', body: '接入、创建项目、校验、CI、报告、发布和排障。', link: { label: '打开任务', href: '/zh/tasks/' } },
+      { title: '理解系统', body: 'Monorepo 边界、现代 npm 包、模板和底层工具。', link: { label: '打开理解', href: '/zh/learn/' } },
+      { title: '查找准确行为', body: '命令、配置、输出格式、别名和执行细节。', link: { label: '打开参考', href: '/zh/reference/' } },
     ],
   },
 } satisfies HomeContent

package/templates/vitepress/.vitepress/home/types.ts

@@ -3,63 +3,47 @@ export interface HomeLink {
   href: string
 }
 
-export interface HomeStep {
-  title: string
-  body: string
-  command: string
-}
-
 export interface HomeContent {
   hero: {
     label: string
     title: string
     description: string
-    primary: HomeLink
-    secondary: HomeLink
+    primaryAction: HomeLink
+    secondaryAction: HomeLink
     imageAlt: string
   }
-  proof: string[]
-  lifecycle: {
-    title: string
-    description: string
-    steps: HomeStep[]
-  }
-  paths: {
+  tasks: {
     title: string
     description: string
     items: Array<{
       title: string
       body: string
-      commands: string[]
-      href: string
-      linkLabel: string
+      command: string
+      link: HomeLink
     }>
   }
-  capabilities: {
+  firstRun: {
     title: string
     description: string
-    items: Array<{ title: string, body: string }>
-  }
-  commands: {
-    title: string
-    description: string
-    items: Array<{ command: string, purpose: string }>
-  }
-  automation: {
-    title: string
-    description: string
-    formats: string[]
-    code: string
+    steps: Array<{
+      title: string
+      command: string
+      body: string
+    }>
   }
-  quickstart: {
+  evidence: {
     title: string
     description: string
     code: string
     link: HomeLink
   }
-  docs: {
+  layers: {
     title: string
     description: string
-    items: Array<HomeLink & { body: string }>
+    items: Array<{
+      title: string
+      body: string
+      link: HomeLink
+    }>
   }
 }

package/templates/vitepress/.vitepress/navigation/routes.ts

@@ -7,132 +7,140 @@ interface LocalizedText {
   zh: string
 }
 
-interface RouteItem {
+export interface RouteItem {
   slug: string
   label: LocalizedText
 }
 
-interface RouteSection {
-  id: 'repoctl' | 'monorepo' | 'why' | 'ai' | 'tools'
+export interface RouteSection {
+  id: 'start' | 'tasks' | 'reference' | 'learn' | 'ai'
   label: LocalizedText
-  items: RouteItem[]
+  items: readonly RouteItem[]
 }
 
 const item = (slug: string, en: string, zh: string): RouteItem => ({ slug, label: { en, zh } })
 
 export const routeSections = [
   {
-    id: 'repoctl',
-    label: { en: 'repoctl', zh: 'repoctl' },
+    id: 'start',
+    label: { en: 'Start', zh: '开始' },
     items: [
-      item('', 'Overview', '概览'),
-      item('getting-started', 'Getting Started', '快速开始'),
-      item('adopt-existing', 'Adopt Existing Repos', '接入已有仓库'),
-      item('scenarios', 'Choose By Scenario', '按场景选命令'),
-      item('execution-model', 'Execution Model', '执行模型'),
-      item('commands', 'Command Reference', '命令速查'),
-      item('checks', 'Verification', '校验链路'),
-      item('doctor', 'Doctor', 'Doctor 诊断'),
-      item('config', 'Configuration', '配置文件'),
-      item('templates', 'Templates', '模板与创建'),
-      item('template-assets', 'Template Assets', '模板资产治理'),
-      item('workflows', 'Workflows and CI', '工作流与 CI'),
-      item('reports', 'Reports', '报告与自动化输出'),
-      item('troubleshooting', 'Troubleshooting', '排障'),
-      item('aliases', 'Command Aliases', '命令别名'),
+      item('', 'Start here', '从这里开始'),
+      item('install', 'Install and initialize', '安装并初始化'),
+      item('first-run', 'Your first run', '第一次运行'),
+      item('diagnose', 'Run a diagnosis', '运行诊断'),
+      item('choose-next', 'Choose the next task', '选择下一项任务'),
     ],
   },
   {
-    id: 'monorepo',
-    label: { en: 'Knowledge Base', zh: '知识库' },
+    id: 'tasks',
+    label: { en: 'Tasks', zh: '任务' },
     items: [
-      item('', 'Why Monorepo', '为什么使用 Monorepo'),
-      item('manage', 'Managing A Monorepo', '管理 Monorepo'),
-      item('publish', 'Publishing and Changelogs', '发包与变更日志'),
-      item('commands', 'Monorepo Commands', 'Monorepo 命令'),
-      item('templates', 'Template Systems', '模板体系'),
-      item('troubleshooting', 'Troubleshooting', '常见问题排障'),
+      item('', 'Task index', '任务索引'),
+      item('adopt-existing', 'Adopt an existing workspace', '接入已有 workspace'),
+      item('create-project', 'Create a package or app', '创建包或应用'),
+      item('checks', 'Run checks', '运行校验'),
+      item('reports', 'Reports and output', '报告与输出'),
+      item('ci', 'Add checks to CI', '把校验加入 CI'),
+      item('release', 'Release packages', '发布包'),
+      item('troubleshooting', 'Troubleshoot', '排障'),
     ],
   },
   {
-    id: 'why',
-    label: { en: 'Modern Packages', zh: '现代 npm 包' },
+    id: 'reference',
+    label: { en: 'Reference', zh: '参考' },
     items: [
-      item('how-to-reuse-js-code', 'Reusing JavaScript', '复用 JavaScript'),
-      item('js-cjs-mjs', 'Module Extensions', '模块文件后缀'),
-      item('js-keywords', 'Runtime Globals', '运行时关键字'),
-      item('what-is-npm-package', 'What Is An npm Package?', '什么是 npm 包'),
-      item('publish-basic-npm-package', 'Publishing A Package', '发布 npm 包'),
-      item('', 'Package Evolution', '包的演进'),
-      item('modern/', 'Modern Package Guide', '现代包指南'),
-      item('modern/esm-vs-cjs', 'ESM vs CommonJS', 'ESM 与 CommonJS'),
-      item('modern/dts', 'Type Declarations', '类型声明'),
-      item('modern/package-entry-points', 'Package Entry Points', '包入口'),
-      item('modern/bundlers', 'Bundlers', '构建工具'),
-      item('modern/typescript', 'TypeScript', 'TypeScript'),
+      item('', 'Reference overview', '参考总览'),
+      item('commands', 'Command reference', '命令参考'),
+      item('config', 'Configuration', '配置文件'),
+      item('execution-model', 'Execution model', '执行模型'),
+      item('output', 'Output formats', '输出格式'),
+      item('aliases', 'Command aliases', '命令别名'),
+      item('templates', 'Templates', '模板'),
+      item('template-assets', 'Managed template assets', '受管模板资产'),
     ],
   },
   {
-    id: 'ai',
-    label: { en: 'AI', zh: 'AI' },
-    items: [item('', 'AI Documentation', 'AI 文档'), item('llms-txt', 'llms.txt', 'llms.txt')],
+    id: 'learn',
+    label: { en: 'Learn', zh: '理解' },
+    items: [
+      item('', 'Learn overview', '理解总览'),
+      item('repoctl-model', 'How repoctl fits in', 'repoctl 如何融入仓库'),
+      item('monorepo/', 'Monorepo foundations', 'Monorepo 基础'),
+      item('monorepo/manage', 'Manage a monorepo', '管理 Monorepo'),
+      item('monorepo/publish', 'Publishing and changelogs', '发包与变更日志'),
+      item('monorepo/commands', 'Monorepo commands', 'Monorepo 命令'),
+      item('monorepo/templates', 'Template systems', '模板体系'),
+      item('monorepo/troubleshooting', 'Monorepo troubleshooting', 'Monorepo 排障'),
+      item('packages/', 'Modern npm packages', '现代 npm 包'),
+      item('packages/modern-overview', 'Modern package guide', '现代包指南'),
+      item('packages/reuse-javascript', 'Reuse JavaScript', '复用 JavaScript'),
+      item('packages/module-extensions', 'Module extensions', '模块文件后缀'),
+      item('packages/runtime-globals', 'Runtime globals', '运行时关键字'),
+      item('packages/publish', 'Publish a package', '发布 npm 包'),
+      item('packages/modern/', 'Package details', '现代包细节'),
+      item('packages/modern/esm-vs-cjs', 'ESM and CommonJS', 'ESM 与 CommonJS'),
+      item('packages/modern/dts', 'Type declarations', '类型声明'),
+      item('packages/modern/package-entry-points', 'Package entry points', '包入口'),
+      item('packages/modern/bundlers', 'Bundlers', '构建工具'),
+      item('packages/modern/typescript', 'TypeScript', 'TypeScript'),
+      item('tools/', 'Tool guides', '工具专题'),
+      item('tools/pnpm', 'pnpm', 'pnpm'),
+      item('tools/turborepo', 'Turborepo', 'Turborepo'),
+      item('tools/changeset', 'Versioning', '版本管理'),
+      item('tools/husky', 'Husky', 'Husky'),
+      item('tools/lint-staged', 'lint-staged', 'lint-staged'),
+      item('tools/renovate', 'Renovate', 'Renovate'),
+      item('tools/llms-txt', 'llms.txt', 'llms.txt'),
+    ],
   },
   {
-    id: 'tools',
-    label: { en: 'Tool Guides', zh: '工具专题' },
+    id: 'ai',
+    label: { en: 'AI', zh: 'AI' },
     items: [
-      item('', 'Overview', '概览'),
-      item('pnpm', 'pnpm', 'pnpm'),
-      item('turborepo', 'Turborepo', 'Turborepo'),
-      item('changeset', 'pnpm Versioning', 'pnpm Versioning'),
-      item('husky', 'Husky', 'Husky'),
-      item('lint-staged', 'lint-staged', 'lint-staged'),
-      item('renovate', 'Renovate', 'Renovate'),
+      item('', 'AI documentation', 'AI 文档'),
       item('llms-txt', 'llms.txt', 'llms.txt'),
     ],
   },
 ] as const satisfies readonly RouteSection[]
 
+export type RouteSectionId = (typeof routeSections)[number]['id']
+
 function prefixFor(locale: DocsLocale) {
   return locale === 'zh' ? '/zh' : ''
 }
 
-function sectionItems(section: RouteSection, locale: DocsLocale): DefaultTheme.SidebarItem[] {
+export function routePath(section: RouteSectionId, slug: string, locale: DocsLocale) {
   const prefix = prefixFor(locale)
+  return `${prefix}/${section}/${slug}`.replace(/\/+/g, '/')
+}
+
+function sectionItems(section: RouteSection, locale: DocsLocale): DefaultTheme.SidebarItem[] {
   return section.items.map(route => ({
     text: route.label[locale],
-    link: `${prefix}/${section.id}/${route.slug}`.replace(/\/+/g, '/'),
+    link: routePath(section.id, route.slug, locale),
   }))
 }
 
 export function createSidebars(locale: DocsLocale): DefaultTheme.SidebarMulti {
   const prefix = prefixFor(locale)
-  const groups = Object.fromEntries(routeSections.map(section => [
-    section.id,
-    { text: section.label[locale], items: sectionItems(section, locale) },
-  ])) as Record<RouteSection['id'], DefaultTheme.SidebarItem>
-  const knowledge = [groups.monorepo, groups.why]
-
-  return {
-    [`${prefix}/repoctl/`]: [groups.repoctl],
-    [`${prefix}/knowledge/`]: knowledge,
-    [`${prefix}/monorepo/`]: knowledge,
-    [`${prefix}/why/`]: knowledge,
-    [`${prefix}/ai/`]: [groups.ai],
-    [`${prefix}/tools/`]: [groups.tools],
-    [`${prefix || ''}/`]: [groups.repoctl],
-  }
+  return Object.fromEntries(routeSections.map(section => [
+    `${prefix}/${section.id}/`,
+    [{ text: section.label[locale], items: sectionItems(section, locale) }],
+  ]))
 }
 
 export function createNav(locale: DocsLocale): DefaultTheme.NavItem[] {
-  const zh = locale === 'zh'
   const prefix = prefixFor(locale)
-  return [
-    { text: 'repoctl', link: `${prefix}/repoctl/` },
-    { text: zh ? '快速开始' : 'Getting Started', link: `${prefix}/repoctl/getting-started` },
-    { text: zh ? '命令' : 'Commands', link: `${prefix}/repoctl/commands` },
-    { text: zh ? '知识库' : 'Knowledge Base', link: `${prefix}/knowledge/` },
-    { text: zh ? 'AI 文档' : 'AI Docs', link: `${prefix}/ai/` },
-    { text: zh ? '工具专题' : 'Tool Guides', link: `${prefix}/tools/` },
-  ]
+  const text = locale === 'zh'
+    ? { start: '开始', tasks: '任务', reference: '参考', learn: '理解', ai: 'AI 文档' }
+    : { start: 'Start', tasks: 'Tasks', reference: 'Reference', learn: 'Learn', ai: 'AI Docs' }
+  return (Object.keys(text) as RouteSectionId[]).map(section => ({
+    text: text[section],
+    link: `${prefix}/${section}/`.replace(/\/+/g, '/'),
+  }))
+}
+
+export function allDocumentRoutes(locale: DocsLocale) {
+  return routeSections.flatMap(section => section.items.map(item => routePath(section.id, item.slug, locale)))
 }