@erclx/canon 4.0.0

package/tooling/astro/configs/eslint.config.js

@@ -0,0 +1,79 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import astro from 'eslint-plugin-astro'
+import prettier from 'eslint-config-prettier'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+import vitest from 'eslint-plugin-vitest'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  globalIgnores([
+    'dist',
+    '.astro',
+    'coverage',
+    '.claude',
+    '.vscode',
+    '.husky',
+    'test-results',
+    'playwright-report',
+    'blob-report',
+    'playwright/.cache',
+  ]),
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...astro.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'simple-import-sort': simpleImportSort,
+      'check-file': checkFile,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+      ],
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/*.{ts,tsx,astro}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+      'check-file/folder-naming-convention': [
+        'error',
+        { 'src/**/!(__tests__|pages)': 'KEBAB_CASE' },
+      ],
+    },
+  },
+  {
+    files: ['**/*.{jsx,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+    },
+  },
+  {
+    files: ['*.config.{js,mjs,cjs,ts}', 'astro.config.mjs'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+    ...vitest.configs.recommended,
+  },
+  prettier,
+])

package/tooling/astro/configs/playwright.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const isCI = !!process.env.CI
+const baseURL = `http://localhost:${4321 + (Number(process.env.WORKTREE_PORT_OFFSET) || 0)}`
+
+export default defineConfig({
+  testDir: 'e2e',
+  forbidOnly: isCI,
+  retries: isCI ? 2 : 0,
+  workers: isCI ? 1 : undefined,
+  reporter: isCI ? 'list' : 'html',
+  use: {
+    trace: 'on-first-retry',
+    baseURL,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+  ],
+  webServer: {
+    command: 'bun run build && bun run preview',
+    url: baseURL,
+    reuseExistingServer: false,
+  },
+})

package/tooling/astro/configs/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "astro.config.mjs", "e2e", "playwright.config.ts"],
+  "exclude": ["dist", ".astro", "vitest.config.ts"]
+}

package/tooling/astro/configs/vitest.config.ts

@@ -0,0 +1,22 @@
+import { getViteConfig } from 'astro/config'
+
+export default getViteConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['src/test/setup.ts'],
+    passWithNoTests: true,
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.astro/**',
+      '**/e2e/**',
+      '**/.{idea,git,cache,output,temp}/**',
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'src/test/setup.ts', 'e2e/', '**/*.astro'],
+    },
+  },
+})

package/tooling/astro/manifest.toml

@@ -0,0 +1,34 @@
+[stack]
+name = "astro"
+extends = "web"
+runtime = "bun"
+scaffold = "bun create astro@latest {{name}} -- --template minimal --typescript strict --no-install --no-git --skip-houston --yes"
+
+[dependencies.dev]
+packages = [
+  "astro",
+  "@astrojs/react",
+  "@astrojs/check",
+  "eslint-plugin-astro",
+  "astro-eslint-parser",
+  "prettier-plugin-astro",
+]
+
+[scripts]
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
+"build" = "astro check && astro build"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
+"astro" = "astro"
+"typecheck" = "astro check"
+"setup" = "./scripts/setup.sh"
+
+[scripts.override]
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
+
+[gitignore]
+"# Astro" = [".astro/"]
+
+[verify]
+prepare = "bunx astro add react --yes"

package/tooling/astro/reference.md

@@ -0,0 +1,60 @@
+# Tooling Astro reference
+
+> Extends: `web`. Apply web stack first.
+
+## Overview
+
+The astro stack covers Astro + TypeScript projects: content sites, marketing sites, blogs, and docs. Interactive islands use React only. Output is static. It ships golden configs for `astro.config.mjs`, `vitest.config.ts` (using `getViteConfig` from `astro/config`), `playwright.config.ts` (preview-server backed), a `tsconfig.json` that extends `astro/tsconfigs/strict`, and an `eslint.config.js` that overrides the web layer's config to include `eslint-plugin-astro` and exclude React-refresh rules.
+
+## Scaffold checklist
+
+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: `canon tooling sync web . --write`
+4. Install astro adapter: `canon 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`.
+
+## What ships as golden configs
+
+- `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
+- `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
+- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
+- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
+- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). `src/pages/**` exempt from filename and folder naming conventions because Astro's file-based routing ties names to URL segments.
+
+## Typecheck
+
+`astro check` replaces `tsc --noEmit` because `tsc` cannot parse `.astro` files. `build` runs `astro check && astro build`.
+
+## Vitest scope
+
+Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Page-level behavior is verified by Playwright against rendered output.
+
+Vitest is pinned to `^3` in the web manifest. Vitest `^4` bundles rolldown-vite (vite@8), which ignores the esbuild JSX config in `@vitejs/plugin-react` and breaks `.tsx` tests, plus emits deprecation warnings. Unpin once `@astrojs/react` ships a rolldown-aware plugin (or astro's bundled vite reaches 8).
+
+## Setup script
+
+- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
+- Prompt for project name, normalize to kebab-case, derive title-cased display name.
+- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
+- Update `astro.config.mjs`: set `site` if provided.
+- Update `<title>` and `<meta name="description">` in the default layout.
+
+## Prettier (extend)
+
+Add `prettier-plugin-astro` first in plugins, then `prettier-plugin-tailwindcss` last (per its docs). Add a parser override for `.astro` files.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run dev` | Start the Astro dev server on port 4321, plus this worktree's port offset. |
+| `bun run build` | Run `astro check` then build the static output. |
+| `bun run preview` | Serve the built site locally. |
+| `bun run astro` | Expose the Astro CLI. |
+| `bun run typecheck` | Run `astro check`. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.

package/tooling/base/configs/.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*.sh]
+indent_style = space
+indent_size = 2

package/tooling/base/configs/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+<!-- ## Technical Context (optional, omit for docs/config/trivial changes) -->
+<!-- - <Why this approach was taken, not what changed> -->
+
+## Testing
+
+- [ ] <Specific command or test case>
+- [ ] <Edge case verified>
+
+<!-- Visuals: include only if clarifying architecture, UI, or complex logic flows -->

package/tooling/base/configs/.github/workflows/verify.yml

@@ -0,0 +1,35 @@
+name: Verify
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  static-checks:
+    name: 🛡️ Static Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Shell Tools
+        run: sudo apt-get install -y shfmt shellcheck
+
+      - name: Check Formatting
+        run: bun run check:format
+
+      - name: Check Spelling
+        run: bun run check:spell
+
+      - name: Check Shell
+        run: bun run check:shell

package/tooling/base/configs/.husky/commit-msg

@@ -0,0 +1 @@
+bunx commitlint --edit "$1"

package/tooling/base/configs/.husky/post-merge

@@ -0,0 +1,61 @@
+#!/usr/bin/env sh
+
+# Names archive candidates after a pull merges work in.
+#
+# Every step before the merge fires from a chain and the archive fires when a
+# person remembers, so shipped tasks accumulate on a board that reads as ready
+# to hand a worker. This is the only event that lands after a merge.
+#
+# Candidates rather than closed tasks, because an all-`[x]` board entry does not
+# mean the work merged. `claude-docs` marks outcomes on the branch as step 1 of
+# the ship chain, so a task can read closed while its pull request is still open
+# or already abandoned. The board is gitignored and an archived task has nothing
+# to recover it, so `claude-tasks` confirms the work is on `main` before moving
+# anything and this output says so rather than implying the check is done.
+#
+# It announces and never moves a file. The board is gitignored, so a shell-side
+# archive leaves no diff to review with nobody watching, and `index.md` is
+# regenerated by a session-scoped hook that a `mv` from a shell never fires.
+#
+# Husky runs this as `sh -e`, so the shebang is advisory and any bare command
+# returning non-zero aborts the hook and prints a husky failure. Keep every
+# test inside an `if` condition, which errexit exempts.
+
+root=$(git worktree list --porcelain 2>/dev/null | grep -m 1 '^worktree ' | cut -d' ' -f2-) || root=''
+[ -n "$root" ] || exit 0
+
+# The board is shared scratch at the main worktree root, and `git worktree
+# list` puts that root first. A pull inside a linked worktree fires this same
+# hook, so trusting the working directory would read a board that is not there.
+board="$root/.claude/tasks"
+[ -d "$board" ] || exit 0
+
+closed=""
+count=0
+
+for file in "$board"/*.md; do
+  [ -f "$file" ] || continue
+
+  case "$file" in
+  */index.md | */priority.md) continue ;;
+  esac
+
+  # Gate on the same condition both archive verbs gate on: at least one closed
+  # outcome and none open. A file carrying no outcomes at all falls out here,
+  # which is what keeps notes on the board from being announced as tasks.
+  if grep -q '^- \[ \]' "$file"; then
+    continue
+  fi
+
+  if grep -q '^- \[x\]' "$file"; then
+    closed="$closed  $(basename "$file" .md)
+"
+    count=$((count + 1))
+  fi
+done
+
+[ "$count" -gt 0 ] || exit 0
+
+printf '\n📋 %s archive candidate(s) on the board:\n%s\n' "$count" "$closed"
+printf 'Outcomes are marked on the branch, so each still needs its work confirmed\n'
+printf 'on main. Run /claude-tasks, which checks that and sweeps the plan first.\n\n'

package/tooling/base/configs/.husky/post-rewrite

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+
+# Runs the `post-merge` board check for anyone pulling with rebase.
+#
+# `git pull` under `pull.rebase=true` runs `git rebase`, which fires this event
+# and never `post-merge`. Without this the trigger is a silent no-op on that
+# machine, which is the wrong failure mode for a hook whose whole purpose is to
+# stop a shipped task being forgotten. The base stack ships both hooks to every
+# target, where the pull style is not something this repository controls.
+#
+# Only the `rebase` argument delegates. `post-rewrite` also fires on
+# `commit --amend`, which rewrites nothing on the board and would print the
+# candidate list on an ordinary amend.
+
+[ "$1" = "rebase" ] || exit 0
+
+hook="$(dirname "$0")/post-merge"
+[ -f "$hook" ] || exit 0
+
+# shellcheck source=/dev/null
+. "$hook"

package/tooling/base/configs/.husky/pre-commit

@@ -0,0 +1 @@
+bunx lint-staged

package/tooling/base/configs/.husky/pre-push

@@ -0,0 +1 @@
+bun run check

package/tooling/base/configs/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "overrides": [
+    {
+      "files": "*.mdc",
+      "options": {
+        "parser": "markdown"
+      }
+    }
+  ]
+}

package/tooling/base/configs/.shellcheckrc

@@ -0,0 +1 @@
+external-sources=true

package/tooling/base/configs/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker",
+    "mkhl.shfmt",
+    "timonwong.shellcheck",
+    "mads-hartmann.bash-ide-vscode"
+  ]
+}

package/tooling/base/configs/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "shellcheck.customArgs": ["--severity=warning"]
+}

package/tooling/base/configs/commitlint.config.js

@@ -0,0 +1,11 @@
+const config = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'subject-case': [0],
+    'header-max-length': [2, 'always', 72],
+    'scope-case': [2, 'always', 'lower-case'],
+    'subject-full-stop': [2, 'never', '.'],
+  },
+}
+
+export default config

package/tooling/base/configs/scripts/verify.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+main() {
+  check_dependencies
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Formatting${NC}"
+  run_check "bun run format" "Format failed"
+  log_info "Format applied"
+
+  log_step "Format check"
+  run_check "bun run check:format" "Format check failed"
+  log_info "Format check passed"
+
+  log_step "Spelling"
+  run_check "bun run check:spell" "Spell check failed"
+  log_info "Spell check passed"
+
+  log_step "Shell"
+  run_check "bun run check:shell" "Shell check failed"
+  log_info "Shell check passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/base/manifest.toml

@@ -0,0 +1,30 @@
+[stack]
+name = "base"
+extends = ""
+runtime = "bun"
+scaffold = ""
+
+[sync]
+source = "configs"
+
+[dependencies.dev]
+packages = [
+    "prettier",
+    "cspell",
+    "husky",
+    "@commitlint/cli",
+    "@commitlint/config-conventional",
+]
+
+[scripts]
+"check:spell" = "cspell '**' '.*/**' '.*' --no-progress --color --show-context"
+"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/"
+"check:shell" = "find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
+"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/"
+"prepare" = "husky"
+"check" = "./scripts/verify.sh"
+
+[gitignore]
+"# System" = [".DS_Store"]
+"# Dependencies" = ["node_modules/"]
+"# Secrets" = [".env", ".env.*", "*.local", "!.env.example"]

package/tooling/base/reference.md

@@ -0,0 +1,98 @@
+# Tooling base reference
+
+## Overview
+
+The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
+
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `docs/target-projects.md` carries the recipe.
+
+## What ships as golden configs
+
+Golden config files live in `tooling/base/configs/` and are copied into the target on `canon 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.
+- `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
+- `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, and `subject-case` disabled.
+- `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
+- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
+- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
+- `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
+- `scripts/verify.sh`: the maintenance entry point behind `check`.
+
+## What ships as user-owned seeds
+
+Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and never overwrites it, so a project extends them freely.
+
+- `cspell.json`: `version: "0.2"`, `language: "en"`, `useGitignore: true`, `gitignoreRoot: ["."]`, dictionary definitions for `project-terms` and `tech-stack` with `addWords: true` on both, and `ignorePaths: [".cspell/**", ".git/**"]` to skip dictionary self-checks and git object files.
+- `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
+- `.lintstagedrc`: the glob map below.
+- `.prettierignore`: created empty. Projects add their own entries.
+- `.claude/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
+
+## Tool pairing
+
+- Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
+- Formatting: Prettier for what it parses, shfmt for shell. Two formatters because Prettier has no shell parser.
+- Spelling: cspell over the whole tree, with project vocabulary split into a project-terms dictionary and a tech-stack one.
+- Shell: shfmt formats and shellcheck lints at warning severity. shfmt takes a directory argument, shellcheck has no directory mode and needs `find`.
+- Commits: commitlint against conventional commits, wired through the husky `commit-msg` hook. Format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
+- Dev dependencies: `prettier`, `cspell`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
+
+## File layout
+
+- All shell scripts live in `scripts/`. Do not place a `.sh` file outside it.
+- Dictionaries live in `.cspell/`, hooks in `.husky/`, seeded context docs in `.claude/context/`.
+- The `.claude/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md`, `.claude/REQUIREMENTS.md`, and `.claude/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `.claude/context/`. Indexes stay opt-in.
+
+## Hooks
+
+- `pre-commit` runs `bunx lint-staged`.
+- `commit-msg` runs `bunx commitlint --edit "$1"`.
+- `pre-push` runs `bun run check`.
+- `post-merge` names `.claude/tasks/` archive candidates, staying silent otherwise and when the board is absent.
+- `post-rewrite` delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check.
+
+## lint-staged
+
+Seeded baseline globs:
+
+- `**/*.{json,md,mdc}` runs `prettier --write --ignore-path .gitignore --ignore-path .prettierignore` then `cspell --no-must-find-files`
+- `**/*.md` runs `canon indexes regen`
+- `**/*.sh` runs `shfmt --write --indent 2` then `shellcheck --severity=warning`
+
+## CI
+
+- Steps: checkout, setup Bun at latest, `bun install --frozen-lockfile`, install `shfmt` and `shellcheck` via apt, then `check:format`, `check:spell`, and `check:shell`.
+- CI asserts and never writes. Format must be clean before push.
+
+## Gitignore
+
+- `# System`: `.DS_Store`
+- `# Dependencies`: `node_modules/`
+- `# Secrets`: `.env`, `.env.*`, `*.local`, `!.env.example`
+
+## Anti-patterns
+
+Sticky negative knowledge. Do not relearn.
+
+- Do NOT drop `gitignoreRoot: ["."]` from `cspell.json`. Without it, cspell run from inside a linked worktree under `.claude/worktrees/` walks up into the parent repo's `.gitignore`, resolves every worktree file as living under the ignored worktree path, and checks zero files. New words then pass locally and fail in CI.
+- Do NOT rely on the default `**` glob for spelling. It skips dot-prefixed folders, leaving `.claude/`, `.github/`, and `.husky/` unchecked. Pass `'**' '.*/**' '.*'` explicitly.
+- Do NOT invoke prettier without both `--ignore-path .gitignore --ignore-path .prettierignore`. Passing one drops the other, since the flag replaces the default rather than adding to it.
+- Do NOT omit `--log-level warn` from a prettier invocation. The default prints a line per unchanged file.
+- Do NOT put logic in a husky hook and expect its shebang to hold. Husky runs hooks as `sh -e`, so a hook carrying logic is POSIX sh under errexit whatever the first line says.
+- Do NOT drop the `[*.sh]` block from `.editorconfig` because shfmt already sets indentation. The editor and shfmt then disagree and produce spurious git diffs.
+- Do NOT copy lint-staged's `**/*.sh` glob into a package.json script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
+
+## CLI
+
+| Script                 | What it does                                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `bun run check`        | Repairs a checkout via `scripts/verify.sh`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                 |
+| `bun run check:spell`  | Runs cspell across every file, with context on failures                                                                               |
+| `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                   |
+| `bun run format`       | Writes prettier and shfmt formatting in place                                                                                         |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                           |
+
+`bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.