@erclx/aitk 0.111.1 → 1.0.0

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

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

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

@@ -92,17 +92,19 @@ AITK_NON_INTERACTIVE=1 aitk init \
 
 Omit any flag whose resolved value is empty.
 
-Step 2: `aitk tooling sync <tooling-stack>` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `aitk init`).
+Step 2: `aitk tooling sync <tooling-stack> --write` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `aitk init`).
+
+`--write` is required. A headless run without it reports what it would replace and exits 1, since golden configs overwrite whatever the target holds at those paths. Scaffolding into a fresh target has nothing to lose, so pass it directly rather than reading a report first.
 
 ```bash
-AITK_NON_INTERACTIVE=1 aitk tooling sync <tooling-stack> <target>
+AITK_NON_INTERACTIVE=1 aitk tooling sync <tooling-stack> <target> --write
 ```
 
 Monorepo with multiple language roots: run `aitk init` once at the repo root so `base` (husky, prettier, cspell, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped.
 
 ```bash
-AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react ./frontend --skip base
-AITK_NON_INTERACTIVE=1 aitk tooling sync python ./backend --skip base
+AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react ./frontend --skip base --write
+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.

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

@@ -11,7 +11,7 @@ What each `aitk` sync or install command does to existing files in a target proj
 
 | Surface                                                  | Command                  | Effect on existing files                                         |
 | -------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
-| Golden configs (eslint, prettier, vite, tsconfig, ruff)  | `aitk tooling sync`      | Always overwritten. Local edits are lost. Drift is intentional.  |
+| 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                                                | `aitk standards install` | All overwritten.                                                 |
@@ -22,9 +22,77 @@ What each `aitk` sync or install command does to existing files in a target proj
 | `.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
+
+A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the CI workflow, the git hooks, the end-to-end harness, the shell scripts under `scripts/`, and the editor settings, alongside the linters and compilers a reader expects. A stack inherits its parent's configs, so syncing `astro` also writes everything `web` and `base` hold.
+
+Run `aitk tooling sync <stack> <target> --check` for the list resolved against a real target. It reports every path and writes nothing. The list below is what the stacks hold as shipped, before any chain resolution.
+
+<!-- generated:tooling-paths -->
+
+### astro
+
+- `astro.config.mjs`
+- `eslint.config.js`
+- `playwright.config.ts`
+- `tsconfig.json`
+- `vitest.config.ts`
+
+### base
+
+- `.editorconfig`
+- `.github/pull_request_template.md`
+- `.github/workflows/verify.yml`
+- `.husky/commit-msg`
+- `.husky/post-merge`
+- `.husky/post-rewrite`
+- `.husky/pre-commit`
+- `.husky/pre-push`
+- `.prettierrc`
+- `.shellcheckrc`
+- `.vscode/extensions.json`
+- `.vscode/settings.json`
+- `commitlint.config.js`
+- `scripts/clean.sh`
+- `scripts/update.sh`
+- `scripts/verify.sh`
+
+### python
+
+- `.coveragerc`
+- `.python-version`
+- `mypy.ini`
+- `pytest.ini`
+- `ruff.toml`
+- `scripts/verify.sh`
+
+### vite-react
+
+- `playwright.config.ts`
+- `tsconfig.json`
+- `vite.config.ts`
+- `vitest.config.ts`
+
+### web
+
+- `.github/workflows/verify.yml`
+- `.vscode/extensions.json`
+- `.vscode/settings.json`
+- `e2e/home.spec.ts`
+- `e2e/screenshot.ts`
+- `eslint.config.js`
+- `scripts/screenshot.sh`
+- `scripts/verify.sh`
+- `scripts/worktree-port.sh`
+- `src/test/setup.ts`
+
+<!-- /generated:tooling-paths -->
+
 ## Rules
 
-- Before `aitk tooling sync`, know golden configs always overwrite. When the project carries local edits to a golden config, warn the user before running it.
+- `aitk tooling sync` writes nothing until `--write` is passed. A headless run without it reports and exits 1, so a script that forgets the flag fails rather than silently skipping the sync.
+- Run `--check` first when the project carries local edits to any path above. The report names each file it would replace, which is the warning the user needs before the write.
+- An interactive run still prompts. `--write` skips the prompt, and `--check` refuses to write even with a TTY.
 - Seeds are user-owned. Dictionary `.txt` files merge and sort. Other seeds are copy-once, so re-seeding a structured file means deleting it and syncing again.
 - Prefer `aitk standards sync` over `install` on an existing project. `install` overwrites every standard.
 - For section-level customizations of a standard or seed doc, use the `claude-seed-sync` skill, not `aitk ... sync`. It diffs per section and preserves edits.

package/docs/agents/scripting.md

@@ -77,8 +77,11 @@ surface is in `skills-audit.md`.
 # Create a new tooling stack
 AITK_NON_INTERACTIVE=1 aitk tooling create astro
 
-# Sync a stack into a target project
-AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project
+# Report what a stack would change, writing nothing
+AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project --check
+
+# Sync a stack into a target project, overwriting its golden configs
+AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project --write
 
 # Install a governance stack (the stack argument is required headlessly)
 AITK_NON_INTERACTIVE=1 aitk gov install astro --add 260-shadcn /path/to/project
@@ -90,7 +93,7 @@ AITK_NON_INTERACTIVE=1 aitk gov sync /path/to/project
 AITK_NON_INTERACTIVE=1 aitk gov build /path/to/project
 
 # Sync a monorepo subtree, skipping the base layer the repo root already owns
-AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react /path/to/repo/frontend --skip base
+AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react /path/to/repo/frontend --skip base --write
 
 # Verify a stack end-to-end in a throwaway scaffold
 aitk tooling verify vite-react
@@ -134,3 +137,11 @@ SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
 # Read every audit as one record. Exit 2 is a fact, 3 an audit that did not report
 aitk audits run --json
 ```
+
+`aitk tooling sync` is the one verb above whose flag is mandatory headlessly. It
+overwrites every golden config a stack ships, which reaches the CI workflow, the
+git hooks, the end-to-end harness, and the shell scripts under `scripts/`, so a
+headless run carrying neither `--check` nor `--write` reports what it would
+replace and exits 1 rather than applying it. Run `--check` first to read the
+list, then `--write` to apply it. `aitk tooling sync --help` names both, and the
+full per-stack path list sits in the `toolkit-cli` skill.

package/docs/target-projects.md

@@ -45,7 +45,7 @@ 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>` adds stack-specific deps, scripts, gitignore entries, and drops `.claude/tooling/<stack>.md` (plus parents) as the agent's audit context
+- `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 -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
@@ -148,7 +148,9 @@ The same field names a proposal-only skill with a live case here under `migratio
 
 Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, tooling, or anything the reverse walk reports, since each names content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
 
-Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain. Reconcile the configs with `aitk tooling sync <stack> <path>`.
+Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain.
+
+Reconcile the configs with `aitk tooling sync <stack> <path> --check` to read which files differ, then re-run it with `--write` to apply them. The drift report counts categories and the sync names paths, which is the difference worth knowing before a golden config the project edited is replaced.
 
 ### Catch-all
 
@@ -211,8 +213,8 @@ The repo root owns the shared `base` layer, and each language lives in its own s
 
 ```bash
 aitk init --stack react .
-aitk tooling sync vite-react ./frontend --skip base
-aitk tooling sync python ./backend --skip base
+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.

package/governance/rules/claude/561-teach.md

@@ -0,0 +1,20 @@
+---
+description: Route .claude/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
+paths:
+  - '.claude/teach/**'
+---
+
+# Teach standards
+
+## What a workspace keeps
+
+- Never renumber an existing folder, lesson, or record. A later reader cites it by the name it opened under.
+- Write every success line as a task the learner can be asked to perform, never as something they will understand.
+- Keep a reference page free of the learner. A page carrying second person or a quiz belongs under `lessons/`.
+- Record the wrong answer a learner gave, never a count of what they missed.
+- Date the workspace once, in the `MISSION.md` frontmatter. Never repeat the date in the body of any file.
+
+## Authority
+
+- Follow `.claude/standards/teach.md` for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source.
+- Follow `.claude/standards/glossary.md` for the glossary every workspace carries at its root.

package/governance/rules/claude/562-session.md

@@ -0,0 +1,19 @@
+---
+description: Route .claude/tasks/ session map edits to the session standard for the filename, the core sections, and what a handoff carries
+paths:
+  - '.claude/tasks/session-*.md'
+---
+
+# Session map standards
+
+## What a handoff carries
+
+- Follow this rule rather than `555-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
+- Never write into a file another session owns. Overwrite only the file the writing session already wrote.
+- Resolve the containing folder at the main worktree root, never inside a linked worktree.
+- Write only what a compaction destroys. Do not restate the board and do not summarize what shipped.
+- Cite a commit, a task, or a file and line for every claim, so a reader can tell a read from a recall.
+
+## Authority
+
+- Follow `.claude/standards/session.md` for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source.

package/package.json

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

package/scripts/core/regen-tooling-paths.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+# Rewrites the generated path block in the shipped overwrite contract, which
+# names every file a tooling sync can replace. The category reaches past the
+# linters its name suggests, into the CI workflow, the end-to-end harness, and
+# the shell scripts under scripts/, so a reader cannot infer the list. Generating
+# it is what keeps a stack gaining a file from leaving the contract wrong.
+#
+# The stack names come from `tooling list` rather than from a directory walk,
+# so a stack the verb excludes never reaches a contract about what the verb does.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TOOLING_DIR="$PROJECT_ROOT/tooling"
+CONTRACT="$PROJECT_ROOT/claude/skills/toolkit-cli/SKILL.md"
+
+BEGIN="<!-- generated:tooling-paths -->"
+END="<!-- /generated:tooling-paths -->"
+
+[ -d "$TOOLING_DIR" ] || exit 0
+[ -f "$CONTRACT" ] || exit 0
+
+grep -qF "$BEGIN" "$CONTRACT" || {
+  echo "Missing $BEGIN marker in $CONTRACT" >&2
+  exit 1
+}
+
+block="$(mktemp)"
+trap 'rm -f "$block" "$CONTRACT.tmp"' EXIT
+
+{
+  echo "$BEGIN"
+  echo
+  while IFS= read -r stack; do
+    [ -d "$TOOLING_DIR/$stack/configs" ] || continue
+    echo "### $stack"
+    echo
+    while IFS= read -r rel; do
+      echo "- \`$rel\`"
+    done < <(cd "$TOOLING_DIR/$stack/configs" && find . -type f | sed 's|^\./||' | sort)
+    echo
+  done < <(bun "$PROJECT_ROOT/src/cli.ts" tooling list --json | jq -r '.stacks[].name' | sort)
+  echo "$END"
+} >"$block"
+
+# awk streams the file rather than editing in place, so a pattern that matches
+# nothing produces a file missing the block instead of an unchanged one that
+# exits zero.
+awk -v block_file="$block" -v begin="$BEGIN" -v end="$END" '
+  $0 == begin { while ((getline line < block_file) > 0) print line; skipping = 1; next }
+  $0 == end { skipping = 0; next }
+  !skipping { print }
+' "$CONTRACT" >"$CONTRACT.tmp"
+
+# The destination is a tracked file with a mode the copy must not inherit from
+# mktemp, so the content moves onto the original rather than replacing it.
+cat "$CONTRACT.tmp" >"$CONTRACT"
+rm -f "$CONTRACT.tmp"

package/scripts/core/verify.sh

@@ -272,6 +272,11 @@ main() {
   assert_no_drift "claude/skills/*/references" "Skill references drifted. Run bun run check and commit the updated reference files."
   log_info "Skill references clean"
 
+  log_step "Tooling paths"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-tooling-paths.sh" "Tooling-path regen failed"
+  assert_no_drift "claude/skills/toolkit-cli/SKILL.md" "The overwrite contract drifted from what the stacks hold. Run bun run check and commit claude/skills/toolkit-cli/SKILL.md."
+  log_info "Tooling paths clean"
+
   log_step "Skill paths"
   run_check "bash $PROJECT_ROOT/scripts/core/check-skill-paths.sh" "Shipped skills reference a repo-local path."
   log_info "Skill paths clean"

package/scripts/tooling/verify.sh

@@ -129,7 +129,7 @@ main() {
     run_phase "Prepare" bash -c "cd '$tmp_dir' && $prepare"
   fi
 
-  run_phase "Sync" bash -c "cd '$tmp_dir' && AITK_NON_INTERACTIVE=1 aitk tooling sync $stack ."
+  run_phase "Sync" bash -c "cd '$tmp_dir' && AITK_NON_INTERACTIVE=1 aitk tooling sync $stack . --write"
 
   if [ -f "$tmp_dir/package.json" ]; then
     run_phase "lint:fix" bash -c "cd '$tmp_dir' && bun run lint:fix"

package/src/commands/sync.ts

@@ -218,7 +218,9 @@ function renderTooling(report: CheckReport): void {
         ? 'Not stamped. No chain recorded, so tooling drift is unmeasured.'
         : `Recorded chain names no stack this toolkit ships: ${tooling.chain.join(' < ')}.`,
     )
-    logInfo('Run `aitk tooling sync <stack>` to record what this target holds.')
+    logInfo(
+      'Run `aitk tooling sync <stack> --write` to record what this target holds.',
+    )
     return
   }
 
@@ -235,7 +237,9 @@ function renderTooling(report: CheckReport): void {
   for (const [category, count] of Object.entries(tooling.counts)) {
     if (count > 0) logWarn(`${count} ${category}`)
   }
-  logInfo('Run `aitk tooling sync` to reconcile these.')
+  logInfo(
+    'Run `aitk tooling sync --check` to see which files, `--write` to apply.',
+  )
 }
 
 /**

package/src/commands/tooling.ts

@@ -20,7 +20,16 @@ import {
 } from '@/tooling/manifest'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
-import { intro, logAdd, logInfo, logStep, logWarn, outro, select } from '@/ui'
+import {
+  intro,
+  isNonInteractive,
+  logAdd,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
 
 const GREEN = '\x1b[0;32m'
 const NC = '\x1b[0m'
@@ -30,6 +39,8 @@ const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
 interface SyncOptions {
   readonly ref?: boolean
   readonly skip?: string
+  readonly check?: boolean
+  readonly write?: boolean
 }
 
 interface InjectOptions {
@@ -66,6 +77,24 @@ export function register(program: Command): void {
     .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')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  aitk tooling sync base',
+        '  aitk tooling sync base --check',
+        '  AITK_NON_INTERACTIVE=1 aitk tooling sync base --write',
+        '',
+        'To gate CI on tooling drift, run headlessly with neither flag. That',
+        'exits 1 when a file would be replaced and 0 when none would, which is',
+        'what `aitk sync --check --exit-code` spells with a flag. Pass --check',
+        'to report the same list and always exit 0.',
+        '',
+      ].join('\n'),
+    )
     .action(
       async (stack: string | undefined, target: string, opts: SyncOptions) => {
         process.exitCode = await runSync(stack, target, opts)
@@ -193,6 +222,12 @@ async function runSync(
 ): Promise<number> {
   intro('aitk tooling sync')
 
+  if (opts.check === true && opts.write === true) {
+    logWarn('Pass --check or --write, not both.')
+    outro()
+    return 1
+  }
+
   const selected = stack ?? (await promptForStack())
   if (selected === undefined) {
     logWarn('No tooling stacks found')
@@ -220,26 +255,33 @@ async function runSync(
 
   report(result, includeReferences)
 
+  const mode = resolveWriteMode(opts)
+
   if (result.totalChanges === 0) {
-    await stampChain(prepared.chain, prepared.target)
+    // The stamp is a write like any other, so a run with no authority to write
+    // leaves the target's record alone rather than claiming a sync it never
+    // performed.
+    if (mode === 'apply' || mode === 'prompt') {
+      await stampChain(prepared.chain, prepared.target)
+    }
     outro()
     process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
     return 0
   }
 
-  const shouldApply = await select({
-    message: `Apply ${result.totalChanges} changes (${summarize(result)})?`,
-    options: [
-      { value: true, label: 'Apply all' },
-      { value: false, label: 'Cancel' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const decision = await decideApply(result, mode)
 
-  if (!shouldApply) {
-    logWarn('Sync cancelled')
+  if (decision !== 'apply') {
+    logWarn(
+      decision === 'cancelled'
+        ? 'Sync cancelled'
+        : `Reported ${result.totalChanges} changes (${summarize(result)}). Nothing written.`,
+    )
+    if (decision === 'unauthorized') {
+      logInfo('Re-run with --write to apply them, or --check to silence this.')
+    }
     outro()
-    return 0
+    return decision === 'unauthorized' ? 1 : 0
   }
 
   if (result.configs.some((entry) => entry.state !== 'matching')) {
@@ -265,6 +307,46 @@ async function runSync(
   return 0
 }
 
+type WriteMode = 'apply' | 'prompt' | 'report' | 'unauthorized'
+
+type ApplyDecision = 'apply' | 'cancelled' | 'reported' | 'unauthorized'
+
+/**
+ * Golden configs carry the CI workflow, the end-to-end harness, and the shell
+ * scripts under `scripts/`, so an overwrite reaches work no one would consent
+ * to losing. A headless caller therefore has no authority to write without
+ * `--write`, since a confirm prompt carrying `nonInteractiveDefault` resolves
+ * to its first option and would read silence as consent.
+ */
+function resolveWriteMode(opts: SyncOptions): WriteMode {
+  if (opts.check === true) return 'report'
+  if (opts.write === true) return 'apply'
+  return isNonInteractive() ? 'unauthorized' : 'prompt'
+}
+
+/**
+ * Exit 1 follows `unauthorized`, so a caller that forgets `--write` fails
+ * rather than reporting a sync it never performed.
+ */
+async function decideApply(
+  result: ScanResult,
+  mode: WriteMode,
+): Promise<ApplyDecision> {
+  if (mode === 'report') return 'reported'
+  if (mode === 'apply') return 'apply'
+  if (mode === 'unauthorized') return 'unauthorized'
+
+  const shouldApply = await select({
+    message: `Apply ${result.totalChanges} changes (${summarize(result)})?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+  })
+
+  return shouldApply ? 'apply' : 'cancelled'
+}
+
 /**
  * Writes the chain after the copies land, so a partial apply that throws leaves
  * the previous record rather than a claim the target does not meet.

package/src/init/steps.ts

@@ -23,7 +23,7 @@ export function buildSteps(
     {
       kind: 'run',
       label: 'Base tooling',
-      run: child(['tooling', 'sync', 'base', resolved]),
+      run: child(['tooling', 'sync', 'base', resolved, '--write']),
     },
     {
       kind: 'run',

package/tooling/astro/configs/astro.config.mjs

@@ -5,9 +5,12 @@ import path from 'path'
 
 const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
 
+// Reserved TLD, so an unset ASTRO_SITE is visible in canonical URLs and never resolves.
+const site = process.env.ASTRO_SITE || 'https://set-astro-site.invalid'
+
 export default defineConfig({
   integrations: [react()],
-  site: process.env.ASTRO_SITE,
+  site,
   server: {
     port: 4321 + portOffset,
   },

package/tooling/astro/reference.md

@@ -10,8 +10,8 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 1. Scaffold with `bunx create-astro@latest`. Choose `TypeScript: Strict`. Skip git init and install.
 2. Add React integration: `bunx astro add react`. Do not use `astro add tailwind`. That command installs the v3 integration. Tailwind v4 arrives via the web manifest.
-3. Install web tooling: `aitk tooling sync web .`
-4. Install astro adapter: `aitk tooling sync astro .`
+3. Install web tooling: `aitk tooling sync web . --write`
+4. Install astro adapter: `aitk tooling sync astro . --write`
 5. Extend the `ci` and `development` context entries under `.claude/context/` per the web reference's extend sections plus the astro rows below.
 6. Run `bun run lint:fix` then `bun run check`.
 

package/tooling/base/reference.md

@@ -8,7 +8,7 @@ A repository with several language roots layers this stack once at the root and
 
 ## What ships as golden configs
 
-Golden config files live in `tooling/base/configs/` and are copied into the target on `aitk tooling sync base .`. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
+Golden config files live in `tooling/base/configs/` and are copied into the target on `aitk tooling sync base . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
 - `.prettierrc`: `semi: false`, `singleQuote: true`, plus a parser override per non-standard extension (`.mdx` to `markdown`).
 - `.shellcheckrc`: `external-sources=true`. Required for shellcheck to follow `source` directives.

package/tooling/python/reference.md

@@ -11,9 +11,9 @@ Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coverage
 ## Scaffold checklist
 
 1. Scaffold with `uv init --app <name>`. This creates `pyproject.toml`, `.python-version` pinned to 3.14, `src/<name>/`, and a starter `main.py`. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
-2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this `aitk tooling sync` drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
-3. Install base tooling: `aitk tooling sync base .`
-4. Install python tooling: `aitk tooling sync python .`
+2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this the sync drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
+3. Install base tooling: `aitk tooling sync base . --write`
+4. Install python tooling: `aitk tooling sync python . --write`
 5. Install Python tooling deps: `uv add --dev ruff mypy pytest pytest-cov`. v1 of this stack does not declare these in `[dependencies.dev]` because manifest injection hardcodes `bun add -D`, which can not install Python packages. Until the injector branches on `runtime`, this step is manual.
 6. Sync the lockfile and create the venv: `uv sync`.
 7. Annotate `main()` in the scaffold-generated `main.py` with `-> None`. `uv init --app` ships an unannotated `main()` that fails strict mypy on the first run.

package/tooling/vite-react/reference.md

@@ -9,8 +9,8 @@ The vite-react stack covers Vite + React + TypeScript projects: web apps and Chr
 ## Scaffold checklist
 
 1. Scaffold with `bunx create-vite@latest <name> --template react-ts` (web apps) or `bunx create-crxjs@latest` (Chrome extensions).
-2. Install base and web tooling: `aitk tooling sync web .`
-3. Install vite-react deps and configs: `aitk tooling sync vite-react .`
+2. Install base and web tooling: `aitk tooling sync web . --write`
+3. Install vite-react deps and configs: `aitk tooling sync vite-react . --write`
 4. Extend the `ci` and `development` context entries under `.claude/context/` per the web reference's extend sections plus the vite-react rows below.
 5. Run `bun run lint:fix` then `bun run check`.
 

package/tooling/web/reference.md

@@ -8,7 +8,7 @@ The web layer covers web-universal tooling shared across Vite + React, Astro, an
 
 ## What ships as golden configs
 
-Golden config files live in `tooling/web/configs/` and are copied into the target on `aitk tooling sync web .`. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
+Golden config files live in `tooling/web/configs/` and are copied into the target on `aitk tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.