@erclx/aitk 3.20.0 → 3.21.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/setup-init/SKILL.md

@@ -107,13 +107,13 @@ AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react ./frontend --skip base --wri
 AITK_NON_INTERACTIVE=1 aitk tooling sync python ./backend --skip base --write
 ```
 
-Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs and its own `.claude/tooling/<stack>.md` audit docs.
+Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs, and its own stack reference reads through `aitk tooling reference <stack>`.
 
 Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
 
 - **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
 - **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
-- **Docs.** Open `<target>/.claude/tooling/<tooling-stack>.md` and `<target>/.claude/tooling/web.md` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
+- **Docs.** Run `aitk tooling reference <tooling-stack>` and `aitk tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
 
 Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
 

package/claude/skills/toolkit-cli/SKILL.md

@@ -9,17 +9,17 @@ What each `aitk` sync or install command does to existing files in a target proj
 
 ## Overwrite contract
 
-| Surface                                                  | Command             | Effect on existing files                                          |
-| -------------------------------------------------------- | ------------------- | ----------------------------------------------------------------- |
-| Golden configs, listed in full below                     | `aitk tooling sync` | Overwritten once `--write` is passed. Local edits are lost.       |
-| Dictionary seeds (`.cspell/*.txt`)                       | `aitk tooling sync` | Merged and sorted. Existing terms preserved.                      |
-| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `aitk tooling sync` | Copy-once. Dropped on first install, untouched after.             |
-| Standards                                                | none                | Nothing installs. `aitk standards <name>` reads and never writes. |
-| Seed docs and `CLAUDE.md`                                | `aitk claude init`  | Skipped when present. Never overwritten.                          |
-| Seed docs                                                | `aitk claude sync`  | Never touched. Only `.gitignore` is written.                      |
-| References (`.claude/tooling/<stack>.md`)                | `aitk tooling ref`  | Overwritten.                                                      |
-| `.gitignore`, deps, scripts                              | any sync            | Additive. Existing entries preserved. Deps re-pin on major skew.  |
-| Generated `index.md`                                     | any sync or regen   | Rewritten from target state. Hand edits are lost.                 |
+| Surface                                                  | Command             | Effect on existing files                                                   |
+| -------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------- |
+| Golden configs, listed in full below                     | `aitk tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                |
+| Dictionary seeds (`.cspell/*.txt`)                       | `aitk tooling sync` | Merged and sorted. Existing terms preserved.                               |
+| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `aitk tooling sync` | Copy-once. Dropped on first install, untouched after.                      |
+| Standards                                                | none                | Nothing installs. `aitk standards <name>` reads and never writes.          |
+| Seed docs and `CLAUDE.md`                                | `aitk claude init`  | Skipped when present. Never overwritten.                                   |
+| Seed docs                                                | `aitk claude sync`  | Never touched. Only `.gitignore` is written.                               |
+| Stack references                                         | none                | Nothing installs. `aitk tooling reference <stack>` reads and never writes. |
+| `.gitignore`, deps, scripts                              | any sync            | Additive. Existing entries preserved. Deps re-pin on major skew.           |
+| Generated `index.md`                                     | any sync or regen   | Rewritten from target state. Hand edits are lost.                          |
 
 ## What a tooling sync can overwrite
 

package/docs/target-projects.md

@@ -45,8 +45,8 @@ Two steps, in order:
 The chain is:
 
 - `aitk init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
-- `aitk tooling sync <stack> --write` adds stack-specific deps, scripts, gitignore entries, and drops `.claude/tooling/<stack>.md` (plus parents) as the agent's audit context
-- The agent follows the reference to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
+- `aitk tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
+- The agent reads `aitk tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
 The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:toolkit-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
@@ -175,7 +175,7 @@ Reconcile the configs with `aitk tooling sync <stack> <path> --check` to read wh
 
 `aitk sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence.
 
-It never touches user-owned seed files. Governance rules in `.claude/rules/`, tooling configs, and reference docs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
+It never touches user-owned seed files. Governance rules in `.claude/rules/` and tooling configs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
 
 Standards take no part in that run. Nothing installed them, so there is no copy to reconcile and no `aitk standards sync` to reach for.
 
@@ -184,7 +184,7 @@ Standards take no part in that run. Nothing installed them, so there is no copy
 - Claude seed docs such as `CLAUDE.md` and `.claude/REQUIREMENTS.md`: invoke `aitk:claude-seed-sync`. The skill splits each file into a preamble (between the H1 and the first H2) plus one part per `##` section, then diffs part by part and proposes per-part edits. User customizations are preserved.
 - Governance rules already installed: `aitk gov sync <path>` diffs and applies, and never adds new rules. A rule your recorded stack lists reports as `missing` instead.
 - Tooling configs and seeds: `aitk tooling <stack> <path>` overwrites golden configs and merges seeds
-- Reference docs for a stack: `aitk tooling ref <stack> <path>`
+- Reference docs for a stack: `aitk tooling reference <stack>` reads and never writes, so there is nothing to sync
 - Index regeneration after markdown edits: `aitk indexes regen`
 
 Use a targeted entry point when only one surface moved upstream. Use the catch-all when the toolkit lands a bundled release.
@@ -233,7 +233,7 @@ aitk tooling sync vite-react ./frontend --skip base --write
 aitk tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite) and its own `.claude/tooling/<stack>.md` audit docs.
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `aitk tooling reference <stack>`.
 
 ## Running sync from an agent session
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/tooling.ts

@@ -3,7 +3,6 @@ import type { Command } from 'commander'
 import { execScript } from '@/exec'
 import { PROJECT_ROOT } from '@/project-root'
 import {
-  applyReferences,
   injectConfigs,
   injectGitignore,
   injectManifest,
@@ -18,12 +17,14 @@ import {
   resolveChain,
   stackExists,
 } from '@/tooling/manifest'
+import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
 import {
   intro,
   isNonInteractive,
   logAdd,
+  logError,
   logInfo,
   logStep,
   logWarn,
@@ -32,10 +33,9 @@ import {
   select,
 } from '@/ui'
 
-const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
+const PASS_THROUGH_VERBS = ['create', 'verify'] as const
 
 interface SyncOptions {
-  readonly ref?: boolean
   readonly skip?: string
   readonly check?: boolean
   readonly write?: boolean
@@ -64,7 +64,7 @@ type Prepared =
 export function register(program: Command): void {
   const tooling = program
     .command('tooling')
-    .description('Manage tooling stacks (sync, ref, create)')
+    .description('Manage tooling stacks (sync, reference, create)')
     .helpOption('-h, --help', 'Show this help message')
 
   tooling
@@ -73,7 +73,6 @@ export function register(program: Command): void {
     .argument('[stack]', 'Tooling stack name (e.g. base, vite-react)')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
-    .option('--no-ref', 'Skip dropping reference docs')
     .option('--skip <stack>', 'Drop a layer from the extends chain')
     .option('--check', 'Report what would change and write nothing')
     .option('--write', 'Apply every change without prompting')
@@ -134,6 +133,29 @@ export function register(program: Command): void {
       process.exitCode = runList(opts)
     })
 
+  tooling
+    .command('reference')
+    .description("Print a stack's reference doc")
+    .argument('<stack>', 'Tooling stack name (e.g. base, vite-react)')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A stack resolves under tooling/ at the working root, then the corpus',
+        'inside the aitk package. No reference installs into a project, so the',
+        'package corpus is what answers there. The frame names the copy it read.',
+        '',
+        'Examples:',
+        '  aitk tooling reference base',
+        '  aitk tooling reference vite-react',
+        '',
+      ].join('\n'),
+    )
+    .action((stack: string) => {
+      process.exitCode = printReference(stack)
+    })
+
   for (const verb of PASS_THROUGH_VERBS) {
     tooling
       .command(verb)
@@ -172,6 +194,32 @@ function runList(opts: ListOptions): number {
   return 0
 }
 
+/**
+ * Writes the reference to stdout and every frame line to stderr, so a caller
+ * capturing the output with `$(...)` receives the document alone. Mirrors
+ * `print` in `src/commands/standards.ts`.
+ */
+function printReference(stack: string): number {
+  intro('aitk tooling reference')
+
+  const root = process.cwd()
+  const resolved = resolveReference(root, stack)
+
+  if (!resolved) {
+    logWarn(`Unknown stack: ${stack}`)
+    logStep('Available stacks')
+    for (const each of listStacks(PROJECT_ROOT)) logInfo(each)
+    logError("Run 'aitk tooling list' for descriptions.")
+    outro()
+    return 1
+  }
+
+  logStep(resolved.source)
+  process.stdout.write(readReference(resolved))
+  outro()
+  return 0
+}
+
 /**
  * Resolves the chain and rejects the same inputs the bash rejected, so a bad
  * stack name fails before anything touches the target.
@@ -248,10 +296,9 @@ async function runSync(
     return 1
   }
 
-  const includeReferences = opts.ref !== false
-  const result = scan(prepared.chain, prepared.target, { includeReferences })
+  const result = scan(prepared.chain, prepared.target)
 
-  report(result, includeReferences)
+  report(result)
 
   const mode = resolveWriteMode(opts)
   const { GREEN, NC } = palette(process.stderr)
@@ -290,15 +337,6 @@ async function runSync(
   await injectSeeds(prepared.chain, prepared.target)
   await injectManifest(prepared.chain, prepared.target)
 
-  const pending = result.references
-    .filter((entry) => entry.state === 'pending')
-    .map((entry) => entry.stack)
-
-  if (pending.length > 0) {
-    logStep('Applying references')
-    await applyReferences(prepared.chain, prepared.target, pending)
-  }
-
   await stampChain(prepared.chain, prepared.target)
 
   outro()
@@ -448,7 +486,7 @@ async function promptForStack(): Promise<string | undefined> {
   })
 }
 
-function report(result: ScanResult, includeReferences: boolean): void {
+function report(result: ScanResult): void {
   logStep('Scanning configs')
   for (const entry of result.configs) {
     if (entry.state === 'matching') logInfo(entry.rel)
@@ -483,16 +521,6 @@ function report(result: ScanResult, includeReferences: boolean): void {
   for (const entry of result.gitignore) {
     if (entry.state === 'missing') logAdd(entry.entry)
   }
-
-  if (!includeReferences) return
-
-  logStep('Scanning references')
-  for (const entry of result.references) {
-    if (entry.state === 'matching') logInfo(`.claude/tooling/${entry.stack}.md`)
-  }
-  for (const entry of result.references) {
-    if (entry.state === 'pending') logAdd(`.claude/tooling/${entry.stack}.md`)
-  }
 }
 
 function reportPackage(result: ScanResult): void {
@@ -540,10 +568,6 @@ function summarize(result: ScanResult): string {
     result.gitignore.filter((entry) => entry.state === 'missing').length,
     'gitignore',
   )
-  add(
-    result.references.filter((entry) => entry.state === 'pending').length,
-    'refs',
-  )
 
   return parts.join(', ')
 }

package/src/sync/check.ts

@@ -103,7 +103,6 @@ export interface ToolingCounts {
   readonly scripts: number
   readonly deps: number
   readonly gitignore: number
-  readonly references: number
 }
 
 /**
@@ -134,7 +133,6 @@ const UNMEASURED_TOOLING: ToolingReport = {
     scripts: 0,
     deps: 0,
     gitignore: 0,
-    references: 0,
   },
   changes: 0,
 }
@@ -219,7 +217,7 @@ export function buildToolingReport(
 
   if (manifests.length === 0) return { ...UNMEASURED_TOOLING, chain }
 
-  const result = scan(manifests, target, { includeReferences: true })
+  const result = scan(manifests, target)
   const record = stamp?.domains.tooling
 
   return {
@@ -236,8 +234,6 @@ export function buildToolingReport(
       deps: result.deps.filter((entry) => entry.state === 'missing').length,
       gitignore: result.gitignore.filter((entry) => entry.state === 'missing')
         .length,
-      references: result.references.filter((entry) => entry.state === 'pending')
-        .length,
     },
     changes: result.totalChanges,
   }

package/src/tooling/inject.ts

@@ -1,12 +1,5 @@
 import { existsSync } from 'node:fs'
-import {
-  copyFile,
-  mkdir,
-  readFile,
-  rm,
-  rmdir,
-  writeFile,
-} from 'node:fs/promises'
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
@@ -198,33 +191,3 @@ export async function injectManifest(
 
   await injectGitignore(chain, target)
 }
-
-/**
- * Drops reference docs into `.claude/tooling/`, clearing the legacy
- * `tooling/` location the earlier layout used.
- */
-export async function applyReferences(
-  chain: readonly Manifest[],
-  target: string,
-  stacks: readonly string[],
-): Promise<string[]> {
-  const destDir = join(target, '.claude', 'tooling')
-  await mkdir(destDir, { recursive: true })
-
-  const applied: string[] = []
-  const byName = new Map(chain.map((manifest) => [manifest.name, manifest]))
-
-  for (const stack of stacks) {
-    const manifest = byName.get(stack)
-    if (!manifest) continue
-
-    await copyFile(manifest.referenceFile, join(destDir, `${stack}.md`))
-    logAdd(`.claude/tooling/${stack}.md`)
-    applied.push(stack)
-    await rm(join(target, 'tooling', `${stack}.md`), { force: true })
-  }
-
-  await rmdir(join(target, 'tooling')).catch(() => {})
-
-  return applied
-}

package/src/tooling/manifest.ts

@@ -14,7 +14,6 @@ export interface Manifest {
   readonly dir: string
   readonly configsDir: string
   readonly seedsDir: string
-  readonly referenceFile: string
   readonly scripts: Readonly<Record<string, string>>
   readonly scriptOverrides: Readonly<Record<string, string>>
   readonly gitignore: readonly GitignoreSection[]
@@ -100,7 +99,6 @@ export function loadManifest(
     dir,
     configsDir: join(dir, 'configs'),
     seedsDir: join(dir, 'seeds'),
-    referenceFile: join(dir, 'reference.md'),
     scripts: pickStrings(scriptsTable),
     scriptOverrides: pickStrings(asTable(scriptsTable.override)),
     gitignore: readGitignoreSections(asTable(parsed.gitignore)),

package/src/tooling/read.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+
+/**
+ * Spells the package root in a report where every other root spells a
+ * project-relative path. The `source` field promises a path inside the project
+ * and a package copy is the one source that promise cannot cover, so the
+ * spelling has to be one nothing will join to a project root.
+ */
+const PACKAGE_LABEL = '<aitk>'
+
+export interface ReferenceRoot {
+  /** Absolute `tooling/` directory to search. */
+  readonly dir: string
+  /** How a report spells a copy found under this root. */
+  readonly label: string
+}
+
+export interface ResolvedReference {
+  readonly path: string
+  /** The label of the root that won, joined to the stack and filename. */
+  readonly source: string
+}
+
+function toolingSourceDir(root: string): string {
+  return join(root, 'tooling')
+}
+
+/**
+ * The roots a stack reference resolves against, mirroring `standardRoots` in
+ * `src/standards/read.ts`. No stack reference installs into a project any
+ * more, so the package corpus is the only root that answers there. The
+ * authoring root stays ahead of it for the toolkit's own repository, which
+ * authors the corpus this reads, and for a project authoring stacks of its
+ * own under the same layout.
+ */
+export function referenceRoots(root: string): ReferenceRoot[] {
+  return [
+    { dir: toolingSourceDir(root), label: 'tooling' },
+    {
+      dir: toolingSourceDir(PROJECT_ROOT),
+      label: join(PACKAGE_LABEL, 'tooling'),
+    },
+  ]
+}
+
+/** Resolves a stack's reference doc, working root first. */
+export function resolveReference(
+  root: string,
+  stack: string,
+): ResolvedReference | undefined {
+  for (const { dir, label } of referenceRoots(root)) {
+    const path = join(dir, stack, 'reference.md')
+    if (existsSync(path)) {
+      return { path, source: join(label, stack, 'reference.md') }
+    }
+  }
+
+  return undefined
+}
+
+export function readReference(reference: ResolvedReference): string {
+  return readFileSync(reference.path, 'utf8')
+}

package/src/tooling/scan.ts

@@ -26,26 +26,16 @@ export interface EntryState {
   readonly state: 'missing' | 'present'
 }
 
-export interface ReferenceState {
-  readonly stack: string
-  readonly state: 'pending' | 'matching'
-}
-
 export interface ScanResult {
   readonly configs: readonly ConfigState[]
   readonly seeds: readonly SeedState[]
   readonly scripts: readonly ScriptState[]
   readonly deps: readonly DepState[]
   readonly gitignore: readonly EntryState[]
-  readonly references: readonly ReferenceState[]
   readonly hasPackageJson: boolean
   readonly totalChanges: number
 }
 
-export interface ScanOptions {
-  readonly includeReferences: boolean
-}
-
 function isIdentical(a: string, b: string): boolean {
   if (!existsSync(b)) return false
   return readFileSync(a).equals(readFileSync(b))
@@ -55,14 +45,10 @@ function isIdentical(a: string, b: string): boolean {
  * Compares every stack in the chain against the target and reports what would
  * change. Nothing is written. Which stack wins a duplicate differs per
  * category and mirrors the bash: configs, seeds, and scripts resolve nearest
- * stack first, while dependencies, gitignore entries, and references resolve
- * from the furthest ancestor inward.
+ * stack first, while dependencies and gitignore entries resolve from the
+ * furthest ancestor inward.
  */
-export function scan(
-  chain: readonly Manifest[],
-  target: string,
-  options: ScanOptions,
-): ScanResult {
+export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const configs: ConfigState[] = []
   const seenConfigs = new Set<string>()
 
@@ -109,17 +95,12 @@ export function scan(
     : ''
   const gitignore = scanGitignore(chain, gitignoreContent)
 
-  const references = options.includeReferences
-    ? scanReferences(chain, target)
-    : []
-
   const totalChanges =
     configs.filter((entry) => entry.state !== 'matching').length +
     seeds.filter((entry) => entry.state === 'missing').length +
     scripts.filter((entry) => entry.state !== 'matching').length +
     deps.filter((entry) => entry.state === 'missing').length +
-    gitignore.filter((entry) => entry.state === 'missing').length +
-    references.filter((entry) => entry.state === 'pending').length
+    gitignore.filter((entry) => entry.state === 'missing').length
 
   return {
     configs,
@@ -127,7 +108,6 @@ export function scan(
     scripts,
     deps,
     gitignore,
-    references,
     hasPackageJson: pkg !== undefined,
     totalChanges,
   }
@@ -165,22 +145,3 @@ function scanGitignore(
 
   return states
 }
-
-function scanReferences(
-  chain: readonly Manifest[],
-  target: string,
-): ReferenceState[] {
-  const states: ReferenceState[] = []
-
-  for (const manifest of ancestorsFirst(chain)) {
-    if (!existsSync(manifest.referenceFile)) continue
-
-    const dest = join(target, '.claude', 'tooling', `${manifest.name}.md`)
-    states.push({
-      stack: manifest.name,
-      state: isIdentical(manifest.referenceFile, dest) ? 'matching' : 'pending',
-    })
-  }
-
-  return states
-}

package/scripts/tooling/ref.sh

@@ -1,147 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/tooling.sh"
-trap close_timeline EXIT
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  log_step "Tooling ref usage"
-  echo -e "${GREY}│${NC}  ${WHITE}Usage:${NC} aitk tooling ref [stack] [target-path]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Drops reference docs only. No config or dependency changes."
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Arguments:${NC}"
-  echo -e "${GREY}│${NC}    stack         Name of the tooling stack (e.g., base, vite-react)"
-  echo -e "${GREY}│${NC}    target-path   Target directory (default: current directory)"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-select_stack() {
-  local stacks=()
-  mapfile -t stacks < <(list_tooling_stacks)
-
-  if [ ${#stacks[@]} -eq 0 ]; then
-    log_error "No tooling stacks found in $PROJECT_ROOT/tooling"
-  fi
-
-  select_option "Select tooling stack:" "${stacks[@]}"
-  echo "$SELECTED_OPTION"
-}
-
-collect_references() {
-  local stack="$1"
-  local target="$2"
-  local -n _pending=$3
-
-  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
-  [ ! -f "$manifest" ] && return
-
-  local extends
-  extends=$(grep '^extends' "$manifest" 2>/dev/null | cut -d'"' -f2)
-
-  if [ -n "$extends" ]; then
-    collect_references "$extends" "$target" "$3"
-  fi
-
-  local reference_file="$PROJECT_ROOT/tooling/$stack/reference.md"
-  [ ! -f "$reference_file" ] && return
-
-  local dest="$target/.claude/tooling/$stack.md"
-
-  if [ -f "$dest" ] && diff -q "$reference_file" "$dest" >/dev/null 2>&1; then
-    log_info ".claude/tooling/$stack.md"
-    return
-  fi
-
-  log_add ".claude/tooling/$stack.md"
-  _pending+=("$stack")
-}
-
-apply_references() {
-  local target="$1"
-  shift
-  local stacks=("$@")
-
-  mkdir -p "$target/.claude/tooling"
-
-  for stack in "${stacks[@]}"; do
-    local src="$PROJECT_ROOT/tooling/$stack/reference.md"
-    cp "$src" "$target/.claude/tooling/$stack.md"
-    log_add ".claude/tooling/$stack.md"
-    rm -f "$target/tooling/$stack.md"
-  done
-  rmdir "$target/tooling" 2>/dev/null || true
-}
-
-main() {
-  if [[ "$1" == "-h" || "$1" == "--help" ]]; then
-    show_help
-  fi
-
-  local stack="$1"
-  local target="${2:-.}"
-
-  # Every frame below goes to stderr, so it asks about that stream rather than
-  # reading the source-time answer, which is for stdout and is what `show_help`
-  # above wants. Declared after the help branch so that call keeps it.
-  local GREEN RED YELLOW WHITE GREY NC
-  set_palette 2
-
-  echo -e "${GREY}┌${NC}" >&2
-  echo -e "${GREY}│${NC} ${WHITE}aitk tooling ref${NC}" >&2
-
-  if [ -z "$stack" ]; then
-    stack=$(select_stack)
-  fi
-
-  if is_tooling_stack_excluded "$stack"; then
-    log_error "Claude is managed by \`aitk claude\`, not \`aitk tooling\`."
-  fi
-
-  if [ ! -d "$PROJECT_ROOT/tooling/$stack" ]; then
-    log_error "Stack not found: $stack"
-  fi
-
-  guard_root "$target"
-
-  local pending=()
-
-  echo -e "${GREY}├${NC} ${WHITE}Scanning references: $stack${NC}" >&2
-  collect_references "$stack" "$target" pending
-
-  if [ "${#pending[@]}" -eq 0 ]; then
-    trap - EXIT
-    echo -e "${GREY}└${NC}\n" >&2
-    echo -e "${GREEN}✓ References up to date${NC}" >&2
-    exit 0
-  fi
-
-  local dest_display="$target/.claude/tooling/"
-  dest_display="${dest_display#./}"
-
-  select_option "Sync ${#pending[@]} reference(s) to $dest_display?" "Yes" "No"
-
-  if [ "$SELECTED_OPTION" = "No" ]; then
-    log_warn "Cancelled"
-    exit 0
-  fi
-
-  log_step "Applying changes"
-  apply_references "$target" "${pending[@]}"
-
-  trap - EXIT
-  echo -e "${GREY}└${NC}\n" >&2
-  echo -e "${GREEN}✓ References synced${NC}" >&2
-}
-
-main "$@"