@erclx/canon 5.36.0 → 5.38.0

package/src/sync/check.ts

@@ -531,12 +531,12 @@ export function parseNewSkills(paths: string): string[] {
 
 /**
  * What the target's `.claude/rules/` proves about its entitlement. `held` is
- * every rule name it carries and `bands` every band folder those names sit in.
+ * every rule name it carries and `folders` every rule folder those names sit in.
  *
  * Read off the installed tree rather than off a stack name, because
  * `gov install` records file hashes and never the stack it resolved, so the
  * chain a target consumed survives nowhere else. `installRules` copies each
- * rule into the subdirectory it was authored in, which is what makes the band
+ * rule into the subdirectory it was authored in, which is what makes the folder
  * folders legible as evidence.
  *
  * `successorOf` adds the name a held rule was renamed to, which the next sync
@@ -547,12 +547,12 @@ export function readInstalledRules(
   successorOf?: (name: string) => string | undefined,
 ): {
   held: Set<string>
-  bands: Set<string>
+  folders: Set<string>
 } {
   const dir = join(target, ...INSTALL_MARKERS.governance)
   const held = new Set<string>()
-  const bands = new Set<string>()
-  if (!isDirectory(dir)) return { held, bands }
+  const folders = new Set<string>()
+  if (!isDirectory(dir)) return { held, folders }
 
   for (const rel of new Bun.Glob('**/*.md').scanSync({
     cwd: dir,
@@ -566,34 +566,34 @@ export function readInstalledRules(
     held.add(name)
     const successor = successorOf?.(name)
     if (successor !== undefined) held.add(successor)
-    if (boundary > 0) bands.add(posix.slice(0, boundary))
+    if (boundary > 0) folders.add(posix.slice(0, boundary))
   }
 
-  return { held, bands }
+  return { held, folders }
 }
 
 /**
  * Narrows rules added upstream to the ones this target could receive and does
  * not already hold.
  *
- * The band test is the entitlement filter, and `bands` carries two sources: the
+ * The folder test is the entitlement filter, and `folders` carries two sources: the
  * folders the target already holds, and the folders holding a rule the base
  * stack resolves to.
  * A rule authored under `lang/` or `ui/` is named by an individual stack, so it
  * belongs to some targets and not others, and listing every added file would
  * tell a base consumer about rules it was never entitled to. The test
- * over-reports inside a band a target already carries, since one folder can be
+ * over-reports inside a folder a target already carries, since one folder can be
  * reached by more than one stack, and that costs a line where under-reporting
  * would cost the whole point of the section.
  *
- * The `held` test is what keeps a rule that moved bands upstream out. A rename
+ * The `held` test is what keeps a rule that moved folders upstream out. A rename
  * reaches this diff as an addition, and the target already has the file under
  * its old folder, so matching by name is what tells the two apart.
  */
 export function selectNewRules(
   paths: string,
   held: ReadonlySet<string>,
-  bands: ReadonlySet<string>,
+  folders: ReadonlySet<string>,
 ): string[] {
   const prefix = 'governance/rules/'
   const names = new Set<string>()
@@ -604,11 +604,11 @@ export function selectNewRules(
 
     const rel = trimmed.slice(prefix.length)
     const boundary = rel.indexOf('/')
-    const band = boundary === -1 ? '' : rel.slice(0, boundary)
+    const folder = boundary === -1 ? '' : rel.slice(0, boundary)
     const name = basename(rel, '.md')
 
     if (held.has(name)) continue
-    if (band !== '' && !bands.has(band)) continue
+    if (folder !== '' && !folders.has(folder)) continue
 
     names.add(name)
   }
@@ -617,29 +617,29 @@ export function selectNewRules(
 }
 
 /**
- * Band folders holding a rule the base stack resolves to. Every governance
+ * Rule folders holding a rule the base stack resolves to. Every governance
  * stack extends base, so a new rule authored beside one of base's rules is
  * reported to every target the fallback below reads.
  *
- * This is what covers a band no target can carry yet. Entitlement is otherwise
- * read off folders the target already holds, and a band base reaches later
+ * This is what covers a folder no target can carry yet. Entitlement is otherwise
+ * read off folders the target already holds, and a folder base reaches later
  * exists in no installed tree, so without this the rules inside it would reach
  * nobody. Read through `resolveRules` rather than off the stack's entries,
  * since base names its rules one by one and an entry is a slug rather than a
  * folder.
  *
  * A folder only a leaf stack reaches is deliberately absent. It is entitled to
- * some targets and not others, which is the distinction the band test makes and
+ * some targets and not others, which is the distinction the folder test makes and
  * the installed tree is the only evidence of.
  */
-export function baseBands(root: string): Set<string> {
+export function baseFolders(root: string): Set<string> {
   const resolution = resolveRules(root, 'base')
   if (!resolution.ok) return new Set()
 
   return new Set(
     lookupRules(root, resolution.rules)
       .found.map((source) => source.subdir.split(sep)[0] ?? '')
-      .filter((band) => band !== ''),
+      .filter((folder) => folder !== ''),
   )
 }
 
@@ -651,7 +651,7 @@ export function baseBands(root: string): Set<string> {
  * `collectMissing` reports per file through the domain scan, so a rule the
  * chain names and the target lacks reaches both surfaces the same way.
  *
- * The diff-and-bands path stays as the fallback for a target stamped before
+ * The diff-and-folder path stays as the fallback for a target stamped before
  * governance recorded a chain. Rules are domain-scoped there too, so it
  * measures from governance's own anchor rather than from the oldest anchor
  * across domains the way `readNewSkills` does. A shared anchor would let
@@ -670,7 +670,7 @@ export function baseBands(root: string): Set<string> {
  * unmeasured result from a clean one.
  *
  * A recorded chain naming a stack the toolkit no longer ships falls through to
- * the band-based path below rather than reporting the empty list an
+ * the folder-based path below rather than reporting the empty list an
  * unresolved chain would otherwise produce. That empty list reads exactly
  * like a target holding everything, which is the same failure this function
  * exists to close, so a retired stack name is read the same as no chain at
@@ -702,8 +702,8 @@ export async function readNewRules(
     'governance/rules/',
   ])
 
-  const { held, bands } = readInstalledRules(target, successorResolver(root))
-  return selectNewRules(paths, held, bands.union(baseBands(root)))
+  const { held, folders } = readInstalledRules(target, successorResolver(root))
+  return selectNewRules(paths, held, folders.union(baseFolders(root)))
 }
 
 async function readUpstream(

package/src/teach/browser/head.ts

@@ -19,12 +19,12 @@ export function head(page: 'index' | 'lesson', breakpoint: number): void {
   }
   try {
     s = localStorage.getItem('teach-sb')
-  } catch (e) {}
+  } catch {}
   var idx = r.dataset.page === 'index'
   if (s === 'shut' || (s === null && idx)) r.classList.add('sb-shut')
   var w: string | null = null
   try {
     w = localStorage.getItem('teach-sb-w')
-  } catch (e) {}
+  } catch {}
   if (w) r.style.setProperty('--sb-w', w + 'px')
 }

package/src/teach/browser/sidebar.ts

@@ -34,7 +34,7 @@ export function sidebar(breakpoint: number): void {
     root.classList.add('sb-shut')
     try {
       localStorage.setItem('teach-sb', 'shut')
-    } catch (e) {}
+    } catch {}
     if (inside && fold) fold.focus()
   }
 
@@ -46,7 +46,7 @@ export function sidebar(breakpoint: number): void {
           'teach-sb',
           root.classList.contains('sb-shut') ? 'shut' : 'open',
         )
-      } catch (e) {}
+      } catch {}
       /* An overlay takes focus with it. Without this a keyboard reader opens the
        panel and goes on tabbing through the lesson behind the scrim. */
       if (!narrow.matches || root.classList.contains('sb-shut')) return
@@ -112,7 +112,7 @@ export function sidebar(breakpoint: number): void {
     if (save) {
       try {
         localStorage.setItem('teach-sb-w', String(w))
-      } catch (e) {}
+      } catch {}
     }
   }
 

package/src/teach/browser/theme.ts

@@ -3,7 +3,7 @@ export function theme(): void {
   try {
     var s = localStorage.getItem('course-theme')
     if (s) r.dataset.theme = s
-  } catch (e) {}
+  } catch {}
   document.addEventListener('click', function (e) {
     var b = (e.target as Element).closest('.theme')
     if (!b) return
@@ -13,6 +13,6 @@ export function theme(): void {
     r.dataset.theme = d ? 'light' : 'dark'
     try {
       localStorage.setItem('course-theme', r.dataset.theme)
-    } catch (e) {}
+    } catch {}
   })
 }

package/src/tooling/inject.ts

@@ -16,7 +16,6 @@ import {
 import {
   applyScripts,
   collectDeps,
-  collectScripts,
   readPackage,
   serializePackage,
 } from '@/tooling/package'
@@ -198,7 +197,8 @@ export async function injectManifest(
 
 function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
   const deps = collectDeps(chain, {}).map((dep) => dep.spec)
-  const scripts = collectScripts(chain, {}).map((script) => script.key)
+  const skipped = applyScripts({}, chain)
+  const scripts = [...new Set([...skipped.added, ...skipped.overridden])]
   if (deps.length === 0 && scripts.length === 0) return
 
   logStep('Skipped installs')

package/src/tooling/package.ts

@@ -101,34 +101,31 @@ export function collectDeps(
 }
 
 /**
- * Compares manifest scripts against package.json, nearest stack first, so a
- * child definition shadows the parent it extends.
+ * Compares manifest scripts and `[scripts.override]` keys against
+ * package.json. The expected value of each key comes from `applyScripts`, so
+ * the scan and the write path agree on which stack wins. Plain keys come
+ * first, nearest stack first, then override-only keys.
  */
 export function collectScripts(
   chain: readonly Manifest[],
   pkg: PackageJson,
 ): ScriptState[] {
   const scripts = pkg.scripts ?? {}
-  const seen = new Set<string>()
-  const states: ScriptState[] = []
+  const expected = applyScripts({}, chain).pkg.scripts ?? {}
+  const keys = new Set<string>()
 
   for (const manifest of chain) {
-    for (const [key, value] of Object.entries(manifest.scripts)) {
-      if (seen.has(key)) continue
-      seen.add(key)
-
-      const current = scripts[key]
-      if (current === undefined) {
-        states.push({ key, state: 'missing' })
-      } else if (current !== value) {
-        states.push({ key, state: 'drifted' })
-      } else {
-        states.push({ key, state: 'matching' })
-      }
-    }
+    for (const key of Object.keys(manifest.scripts)) keys.add(key)
+  }
+  for (const manifest of chain) {
+    for (const key of Object.keys(manifest.scriptOverrides)) keys.add(key)
   }
 
-  return states
+  return [...keys].map((key): ScriptState => {
+    const current = scripts[key]
+    if (current === undefined) return { key, state: 'missing' }
+    return { key, state: current === expected[key] ? 'matching' : 'drifted' }
+  })
 }
 
 /**

package/src/tooling/verify-stack.ts

@@ -32,7 +32,8 @@ interface Run {
 /**
  * Scaffolds a stack into `.canon/tmp/runs/verify-<stack>/`, syncs its chain
  * from the checkout at `root`, and runs the scaffold's own `lint:fix`,
- * `check`, `test:e2e`, and `screenshot` scripts. Every line goes to stderr.
+ * `format`, `check`, `test:e2e`, and `screenshot` scripts. Every line goes
+ * to stderr.
  *
  * A failed phase is recorded and the run carries on, so the Results block
  * reports every phase rather than the first failure. The tmp dir is removed
@@ -153,11 +154,13 @@ async function run({
 }
 
 /**
- * `lint:fix` runs first and reformats the scaffold, so `check` reads the
- * reformatted tree.
+ * `lint:fix` and `format` run first and rewrite the scaffold, so `check`
+ * reads the tree a project would commit. `check` itself writes nothing, and a
+ * fresh scaffold ships files its own generator formatted another way.
  */
 async function runScripts(state: Run, scripts: Set<string>): Promise<void> {
   await phase(state, 'lint:fix', () => bunRun('lint:fix', state.dir))
+  await phase(state, 'format', () => bunRun('format', state.dir))
   await phase(state, 'check', () => bunRun('check', state.dir))
 
   if (scripts.has('test:e2e')) {

package/tooling/astro/configs/.oxfmtrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "sortPackageJson": false,
+  "ignorePatterns": ["**/*.astro"]
+}

package/tooling/astro/configs/.prettierrc

@@ -0,0 +1,13 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    }
+  ]
+}

package/tooling/astro/configs/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "skipLibCheck": true,
-    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "types": ["vitest/globals", "@testing-library/jest-dom/vitest"],
     "paths": {
       "@/*": ["./src/*"]
     }

package/tooling/astro/manifest.toml

@@ -9,9 +9,18 @@ packages = [
   "astro",
   "@astrojs/react",
   "@astrojs/check",
+  "eslint@^9",
+  "@eslint/js",
+  "typescript-eslint",
+  "eslint-config-prettier",
+  "eslint-plugin-react-hooks",
+  "eslint-plugin-vitest",
+  "globals",
   "eslint-plugin-astro",
   "astro-eslint-parser",
+  "prettier",
   "prettier-plugin-astro",
+  "prettier-plugin-tailwindcss",
 ]
 
 [scripts]
@@ -24,6 +33,10 @@ packages = [
 "card:check" = "bash scripts/check-card-exclusion.sh"
 
 [scripts.override]
+"lint" = "eslint . --max-warnings 0"
+"lint:fix" = "eslint . --fix --max-warnings 0"
+"check:format" = "oxfmt --check . && prettier --check --log-level warn '**/*.astro'"
+"format" = "oxfmt . && prettier --write --log-level warn '**/*.astro'"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
 "readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"

package/tooling/astro/reference.md

@@ -4,7 +4,7 @@
 
 ## 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.
+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`, an `eslint.config.js` that keeps ESLint for this stack alone, and a `.prettierrc` that formats `.astro` files alone.
 
 ## Scaffold checklist
 
@@ -13,16 +13,16 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 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 `canon/context/` per the web reference's extend sections plus the astro rows below.
-6. Run `bun run lint:fix` then `bun run check`.
+6. Run `bun run lint:fix`, then `bun run format`, 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/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
-- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
+- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, `@/` paths.
 - `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
-- `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). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling/stacks.md` for the measurement.
+- `eslint.config.js`: this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling/stacks.md` for the measurement.
 
 ## Typecheck
 
@@ -32,11 +32,21 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 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).
+Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin avoided `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro now bundles Vite 8 itself, so that conflict no longer applies.
 
-## Prettier (extend)
+## Formatting (extend)
 
-Add `prettier-plugin-astro` first in plugins, then `prettier-plugin-tailwindcss` last (per its docs). Add a parser override for `.astro` files.
+- Format `.astro` files with Prettier and every other file with oxfmt. oxfmt loads no Prettier plugin, so it cannot parse `.astro`.
+- Load `prettier-plugin-astro` first in `.prettierrc`'s plugins, then `prettier-plugin-tailwindcss` last (per its docs), with a parser override for `.astro` files.
+- Ignore `**/*.astro` in this stack's `.oxfmtrc.json`, so the two formatters never touch one file.
+- Copy every other option from base's `.oxfmtrc.json` into this one by hand. Scan takes the child config over the parent's whole file, so a change to base's options is lost here until it is copied.
+- Override `check:format` and `format` to run oxfmt, then Prettier over `**/*.astro`.
+
+## ESLint
+
+- Override `lint` and `lint:fix` back to `eslint . --max-warnings 0`, since the web layer sets them to oxlint.
+- Install the ESLint packages here (`eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, `globals`), since the web layer no longer ships them. Pin `eslint@^9`: ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports.
+- Expect the web layer's `.oxlintrc.json` in the target. Nothing runs it here.
 
 ## Development docs (extend)
 

package/tooling/base/configs/.oxfmtrc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "sortPackageJson": false
+}

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

@@ -1,3 +1,3 @@
 {
-  "require": ["format", "check:format"]
+  "require": ["check:format"]
 }

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

@@ -1,6 +1,6 @@
 // Runs this folder's verify phases in a fixed order. The phases a stack
 // requires come from scripts/verify.json, which each stack ships and the
-// nearest one wins. Only node: modules, since a target's own eslint and
+// nearest one wins. Only node: modules, since a target's own linter and
 // tsc --noEmit read this file with no Bun types.
 import { spawnSync } from 'node:child_process'
 import { accessSync, constants, existsSync, readFileSync } from 'node:fs'
@@ -46,16 +46,10 @@ const PHASES: readonly Phase[] = [
     failed: 'Lint failed',
     passed: 'Lint passed',
   },
-  {
-    script: 'format',
-    title: 'Formatting',
-    failed: 'Format failed',
-    passed: 'Format applied',
-  },
   {
     script: 'check:format',
     title: 'Format check',
-    failed: 'Format check failed',
+    failed: "Format check failed. Run 'bun run format' to fix it",
     passed: 'Format check passed',
   },
   {
@@ -85,7 +79,7 @@ const PHASES: readonly Phase[] = [
 // A subfolder synced with --skip base declares none of these, since the
 // repository root owns them, so a list that does not require one runs it only
 // where the folder declares it.
-const BASE_PHASES = new Set(['format', 'check:format'])
+const BASE_PHASES = new Set(['check:format'])
 
 // An add-on stack declares these, keyed to the stack that ships each, so a
 // folder that never synced the add-on skips the phase rather than failing it.

package/tooling/base/manifest.toml

@@ -10,19 +10,19 @@ per_root = ["scripts/verify.ts", "scripts/verify.json"]
 
 [dependencies.dev]
 packages = [
-    "prettier",
-    "husky",
-    "@commitlint/cli",
-    "@commitlint/config-conventional",
+  "oxfmt@0.72.0",
+  "husky",
+  "@commitlint/cli",
+  "@commitlint/config-conventional",
 ]
 
 [scripts]
-"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore ."
-"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore ."
 "prepare" = "husky"
 
 [scripts.override]
 "check" = "bun scripts/verify.ts"
+"check:format" = "oxfmt --check ."
+"format" = "oxfmt ."
 
 [gitignore]
 "# System" = [".DS_Store"]

package/tooling/base/reference.md

@@ -10,18 +10,17 @@ A repository with several language roots layers this stack once at the root and
 
 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`).
+- `.oxfmtrc.json`: `semi: false`, `singleQuote: true`, `printWidth: 80`, and `sortPackageJson: false`, which keep the output Prettier wrote. The `astro` stack repeats these options in its own copy, so copy a change here into it.
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, `subject-case` disabled, and a local `no-claude-co-author` rule refusing a `Co-authored-by` trailer that names Claude or Anthropic.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `scripts/verify.ts`: the one verify runner every stack shares, and the command behind `check`. It runs typecheck, lint, format, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
-- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires its two phases, so a base-only target still fails on a missing one. The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first. These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
+- `scripts/verify.ts`: the one verify runner every stack shares, and the command behind `check`. It runs typecheck, lint, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
+- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires `check:format`, so a base-only target still fails on a missing one. The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first. These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
 
 ## 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.
 
 - `.lintstagedrc`: the glob map below.
-- `.prettierignore`: created empty. Projects add their own entries.
 - `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`. A project with more than one language root adds its own jobs here.
 - `.github/pull_request_template.md`: `## Summary`, `## Key changes`, `## Technical context`, `## Testing`. A project adds the checklist lines its own review needs.
 - `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
@@ -29,9 +28,14 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 ## Tool pairing
 
 - Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
-- Formatting: Prettier for what it parses. Prettier has no shell parser, so shell formatting is the `shell` stack's.
+- Formatting: oxfmt for what it parses, pinned to an exact version so an upgrade arrives as a reviewed diff. oxfmt has no shell parser, so shell formatting is the `shell` stack's.
 - 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`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
+- Dev dependencies: `oxfmt`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
+
+## oxfmt
+
+- Add a project's own ignores to `.prettierignore`, which oxfmt reads beside `.gitignore` by default. Sync overwrites `.oxfmtrc.json`, so an entry in its `ignorePatterns` is lost on the next sync.
+- Delete a leftover `.prettierrc` and run `bun remove prettier` by hand after the first sync onto oxfmt. Sync deletes nothing a stack stopped shipping, and the script overrides already stop Prettier from running.
 
 ## File layout
 
@@ -50,7 +54,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 
 Seeded baseline globs:
 
-- `**/*.{json,md,mdc}` runs `prettier --write --ignore-path .gitignore --ignore-path .prettierignore`
+- `**/*.{json,md}` runs `oxfmt --no-error-on-unmatched-pattern`. Without the flag, a staged file every pattern ignores, such as `CHANGELOG.md`, exits 2 and fails the commit.
 - `**/*.md` runs `canon indexes regen`
 
 ## CI
@@ -69,21 +73,20 @@ Seeded baseline globs:
 
 Sticky negative knowledge. Do not relearn.
 
-- 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 pass `--ignore-path` to oxfmt. It replaces the default `.gitignore` and `.prettierignore` pair rather than adding to it.
 - 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.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Repairs a checkout through `scripts/verify.ts`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
-| `bun run check:format` | Asserts prettier formatting without writing                                                                                               |
-| `bun run format`       | Writes prettier formatting in place                                                                                                       |
-| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                               |
+| Script                 | What it does                                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bun run check`        | Gates a checkout through `scripts/verify.ts` and writes nothing. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check:format` | Asserts oxfmt formatting without writing                                                                                                                   |
+| `bun run format`       | Writes oxfmt formatting in place                                                                                                                           |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                                                |
 
 Base writes `check` as a `[scripts.override]`, so a sync replaces whatever `check` a target declared, including one that chained further checks after the runner. Re-add a chained check as its own script after a sync.
 
-`bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatter could not fix. The pull request workflow calls `check:format` directly, and that is the gate.
+`bun run check` gates a checkout and writes nothing. Formatting drift fails it at `check:format`, and the failure line names `bun run format`, the one command that writes. It once ran `format` first to auto-fix drift, which rewrote files in a checkout several sessions share on every push and left a gate that could not fail. That was rejected, so the writing pass stays in `bun run format` and a push fails until it runs. The pull request workflow calls `check:format` directly as well.
 
-`scripts/verify.ts`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the format check above.
+`scripts/verify.ts`'s `Markdown bans` stage gates on banned characters. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the format check above.

package/tooling/base/seeds/.lintstagedrc

@@ -1,6 +1,4 @@
 {
-  "**/*.{json,md,mdc}": [
-    "prettier --write --ignore-path .gitignore --ignore-path .prettierignore"
-  ],
+  "**/*.{json,md}": ["oxfmt --no-error-on-unmatched-pattern"],
   "**/*.md": ["canon indexes regen"]
 }

package/tooling/base/seeds/canon/context/ci.md

@@ -13,19 +13,19 @@ Owns the GitHub Actions workflow that gates a merge: which events start a run, a
 
 - `.github/workflows/` owns the workflow definitions a trigger below starts
 
-## Triggers
+### Triggers
 
 - Pull requests targeting `main`
 - `workflow_dispatch` (manual run from the Actions tab)
 
-## Checks
+### Checks
 
 Defined in `.github/workflows/verify.yml`. All jobs must pass before merge.
 
-| Check  | Command                | What it asserts   |
-| ------ | ---------------------- | ----------------- |
-| Format | `bun run check:format` | prettier is clean |
+| Check  | Command                | What it asserts |
+| ------ | ---------------------- | --------------- |
+| Format | `bun run check:format` | oxfmt is clean  |
 
-## Running CI locally
+### Running CI locally
 
-`bun run check` runs the same assert plus auto-formats first. If CI fails on format, run `bun run check` locally and commit the diff.
+`bun run check` runs the same assert and writes nothing. If CI fails on format, run `bun run format` locally and commit the diff.