@erclx/canon 5.40.0 → 5.42.0

package/tooling/nextjs/reference.md

@@ -4,50 +4,83 @@
 
 ## Overview
 
-The nextjs stack covers Next.js + TypeScript projects using the App Router. It ships golden configs for `next.config.ts`, `vitest.config.ts` (plain `defineConfig`, no bundler merge), `playwright.config.ts` (build-then-preview), and an `.oxlintrc.json` that replaces the web layer's with `.next` ignores and an App Router override. Shared web tooling (oxlint base, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+The nextjs stack covers Next.js + TypeScript projects using the App Router. It ships golden configs for `next.config.ts`, `vitest.config.ts`, `playwright.config.ts` (build-then-preview), and an `.oxlintrc.json` that replaces the web layer's.
+
+Shared web tooling (oxlint base, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
 
 ## Scaffold checklist
 
-1. Scaffold with `bunx create-next-app@latest <name> --typescript --tailwind --no-linter --app --src-dir --import-alias "@/*" --use-bun --skip-install --disable-git --no-agents-md --yes`. `--no-agents-md` skips the scaffold-time `AGENTS.md`/`CLAUDE.md` write, which otherwise duplicates the root `CLAUDE.md`. `--no-linter` skips the scaffold's `eslint.config.mjs` and `lint` script, and is accepted though `--help` lists only `--eslint` and `--biome`.
-2. Install web tooling: `canon tooling sync web . --write`
-3. Install nextjs configs: `canon tooling sync nextjs . --write`
+1. Scaffold with `bunx create-next-app@latest <name> --typescript --tailwind --no-linter --app --src-dir --import-alias "@/*" --use-bun --skip-install --disable-git --no-agents-md --yes`.
+2. Install web tooling with `canon tooling sync web . --write`.
+3. Install nextjs configs with `canon tooling sync nextjs . --write`.
 4. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the nextjs rows below.
 5. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
+### Scaffold flags
+
+Two flags in step 1 keep the scaffold from writing what the toolkit already owns.
+
+- `--no-agents-md` skips the scaffold-time `AGENTS.md` and `CLAUDE.md` write, which would duplicate the root `CLAUDE.md`.
+- `--no-linter` skips the scaffold's `eslint.config.mjs` and `lint` script. It is accepted though `--help` lists only `--eslint` and `--biome`.
+
 ## What ships as golden configs
 
-- `next.config.ts`: `agentRules: false` stops Next from regenerating `AGENTS.md`/`CLAUDE.md` on every run, which would otherwise compete with the root `CLAUDE.md`. `turbopack.root: import.meta.dirname` pins the workspace root, silencing Next's multi-lockfile inference warning in any checkout carrying more than one lockfile above the project, a worktree included.
-- `vitest.config.ts`: plain `defineConfig`, no `mergeConfig` or `getViteConfig` since Next has no Vite config to merge from. jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `.next/**` in test excludes.
-- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `3000` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. `DIST_PREBUILT` drops the `build` half, matching the astro stack's flag.
-- `.oxlintrc.json`: replaces the web layer's whole file, since oxlint reads one config, with `.next` and `next-env.d.ts` added to `ignorePatterns`. `react/only-export-components` is `off` for `src/app/**`, since route and layout files export non-component values the rule would otherwise flag. `check-file/folder-naming-convention` is `off` for the same subtree, since App Router's bracket, paren, and at-sign folder syntax (dynamic segments, route groups, parallel slots) fails `KEBAB_CASE`.
+### next.config.ts
+
+Two settings keep Next from fighting the checkout.
+
+- `agentRules: false` stops Next regenerating `AGENTS.md` and `CLAUDE.md` on every run, which would compete with the root `CLAUDE.md`.
+- `turbopack.root: import.meta.dirname` pins the workspace root, silencing Next's multi-lockfile inference warning in a checkout with more than one lockfile above the project, a worktree included.
+
+### Test configs
+
+Both test configs differ from the other web stacks.
+
+- `vitest.config.ts` is a plain `defineConfig`, since Next has no Vite config to merge from.
+- It sets jsdom, globals, the setup file, `passWithNoTests: true`, v8 coverage, and `.next/**` in test excludes.
+- `playwright.config.ts` runs all browsers, with `webServer` running `bun run build && bun run preview` on port `3000` plus `WORKTREE_PORT_OFFSET` and `reuseExistingServer: false`.
+- `DIST_PREBUILT` drops the `build` half, matching the astro stack's flag.
+
+### Lint config
+
+`.oxlintrc.json` replaces the web layer's whole file, since oxlint reads one config. It adds `.next` and `next-env.d.ts` to `ignorePatterns`, and turns two rules off for `src/app/**`.
+
+- `react/only-export-components` is `off`, since route and layout files export non-component values the rule would flag.
+- `check-file/folder-naming-convention` is `off`, since App Router's bracket, paren, and at-sign folders (dynamic segments, route groups, parallel slots) fail `KEBAB_CASE`.
 
 ## Port
 
-Next has no config-file port hook, unlike `astro.config.mjs`'s `server.port` or `vite.config.ts`'s `server.port`. The `${base} + WORKTREE_PORT_OFFSET` formula is computed twice instead of once: in `playwright.config.ts` as a JS expression, and in `[scripts.override]` for `dev` and `preview` as shell arithmetic passed to `next`'s own `--port` flag. Default port is `3000`, Next's own default.
+Next has no config-file port hook, unlike `server.port` in `astro.config.mjs` or `vite.config.ts`. The `${base} + WORKTREE_PORT_OFFSET` formula is therefore computed twice.
+
+- `playwright.config.ts` computes it as a JS expression.
+- `[scripts.override]` computes it as shell arithmetic for `dev` and `preview`, passed to `next`'s own `--port` flag.
+- The default port is `3000`, Next's own.
 
 ## Typecheck
 
-`typecheck` runs `next typegen && tsc --noEmit`. The App Router's route-level types (`LayoutProps`, `PageProps`) are generated into `.next/types/`, gitignored and absent from a fresh checkout, and `tsc` fails on them unresolved without the typegen step first.
+`typecheck` runs `next typegen && tsc --noEmit`. The App Router's route-level types (`LayoutProps`, `PageProps`) are generated into `.next/types/`, which is gitignored and absent from a fresh checkout. Without the typegen step first, `tsc` fails on them unresolved.
 
-## No golden `tsconfig.json`
+## No golden tsconfig
 
-`create-next-app`'s own default `tsconfig.json` needs no changes beyond project-specific path aliases, so a golden copy here would ship nothing the scaffold does not already write.
+`create-next-app`'s default `tsconfig.json` needs no changes beyond project-specific path aliases, so a golden copy would ship nothing the scaffold does not already write.
 
 ## Gitignore (extend)
 
-`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+These `[gitignore]` groups mirror the manifest.
 
 - `"# Next" = [".next/"]`
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run dev` | Start the Next dev server on port 3000, plus this worktree's port offset. |
-| `bun run build` | Build the production bundle. |
-| `bun run preview` | Serve the built bundle locally, on port 3000 plus the worktree offset. |
-| `bun run typecheck` | Run `next typegen` then `tsc --noEmit`. |
+| Command             | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `bun run dev`       | Start the Next dev server on 3000 plus this worktree's offset. |
+| `bun run build`     | Build the production bundle.                                   |
+| `bun run preview`   | Serve the built bundle on 3000 plus the worktree offset.       |
+| `bun run typecheck` | Run `next typegen` then `tsc --noEmit`.                        |
 
 ## CI docs (extend)
 
-In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row asserts `` `next typegen && tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->

package/tooling/php/reference.md

@@ -9,17 +9,19 @@ The php stack covers Composer projects on PHP 8.3 or later, formatted by PHP CS
 ## Scaffold checklist
 
 1. Scaffold with `composer init -n --name <vendor>/<name> --autoload src/`. The package name and namespace are the project's own identity, so this stack never ships a `composer.json`.
-2. Seed `package.json` so the base layer's bun-side tools (husky, oxfmt, commitlint) have a target to install into: `bun init -y`.
-3. Install base tooling: `canon tooling sync base . --write`
-4. Install php tooling: `canon tooling sync php . --write`
-5. Install the dev tools: `composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit`. The manifest declares no `[dependencies.dev]`, because manifest injection runs `bun add -D`, which cannot install a Composer package. This step stays manual.
+2. Seed `package.json` with `bun init -y`, so the base layer's bun-side tools (husky, oxfmt, commitlint) have a target to install into.
+3. Install base tooling with `canon tooling sync base . --write`.
+4. Install php tooling with `canon tooling sync php . --write`.
+5. Install the dev tools with `composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit`. This stays manual, since manifest injection runs `bun add -D`.
 6. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
-Use PHP 8.3 or later, since PHPUnit 12 requires it.
+### Requirements
 
-Keep both `src/` and `tests/` in place. All three tools read both paths and fail when either is missing. The scaffold creates `src/`, but git does not commit an empty folder, so a fresh clone with no source yet fails `lint` and `typecheck` until the first class lands there.
+Use PHP 8.3 or later, since PHPUnit 12 requires it.
 
-The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run check` passes on a fresh scaffold. Delete or replace it with real tests.
+- Keep both `src/` and `tests/` in place, since all three tools read both paths and fail when either is missing.
+- The scaffold creates `src/`, but git does not commit an empty folder. A fresh clone with no source fails `lint` and `typecheck` until the first class lands there.
+- The stack ships `tests/SmokeTest.php` as a copy-once seed, so `bun run check` passes on a fresh scaffold. Delete or replace it with real tests.
 
 ## PHP CS Fixer
 
@@ -41,10 +43,21 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 
 ## verify.json
 
+### Phases
+
+The php phase list probes its tools and holds one precondition.
+
 - Probe `php` and `composer` first.
 - Hold a precondition on `vendor/bin/phpunit`, so the run stops and names `composer install` when it is missing.
-- Require Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`). Base's runner adds the four base phases wherever the folder declares their scripts, then the markdown bans stage.
-- The manifest's `[verify] prepare` runs checklist steps 2 and 5 for `canon tooling verify php`: `bun init -y`, then the `composer require --dev` line. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
+- Require Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`).
+- Base's runner adds its own four phases where the folder declares their scripts, then the markdown bans stage.
+
+### Prepare
+
+The manifest prepares a scaffold that lacks a `package.json`.
+
+- The manifest's `[verify] prepare` runs checklist steps 2 and 5 for `canon tooling verify php`, being `bun init -y` and the `composer require --dev` line.
+- The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## Gitignore
 
@@ -63,14 +76,20 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run lint` | Run `php-cs-fixer check --diff`. |
-| `bun run lint:fix` | Auto-fix with `php-cs-fixer fix`. |
-| `bun run typecheck` | Run `phpstan analyse`. |
-| `bun run test` | Run `phpunit`. |
-| `bun run test:run` | Run `phpunit --testdox` (used by `verify`). |
+| Command             | Purpose                                     |
+| ------------------- | ------------------------------------------- |
+| `bun run lint`      | Run `php-cs-fixer check --diff`.            |
+| `bun run lint:fix`  | Auto-fix with `php-cs-fixer fix`.           |
+| `bun run typecheck` | Run `phpstan analyse`.                      |
+| `bun run test`      | Run `phpunit`.                              |
+| `bun run test:run`  | Run `phpunit --testdox` (used by `verify`). |
 
 ## CI docs (extend)
 
-In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+In `canon/context/development/ci.md`, add or change three rows. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+
+- The Typecheck row asserts `` `phpstan analyse` passes ``.
+- A Lint row asserts `` `php-cs-fixer check` passes ``.
+- A Tests row asserts `` `phpunit` exits 0 ``.

package/tooling/python/reference.md

@@ -6,60 +6,77 @@
 
 The python stack covers Python 3.13+ projects managed with `uv`. It ships golden sidecar configs for `ruff`, `mypy`, `pytest`, and `coverage`, plus a `.python-version` pin and a python phase list for base's verify runner. Framework adapters layer on top with their own deps and configs.
 
-Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coveragerc`) rather than `[tool.*]` sections in `pyproject.toml`. Sync overwrites configs on every run, so keeping them sidecar avoids stomping the user-owned `[project]` block in `pyproject.toml`.
+Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coveragerc`) rather than `[tool.*]` sections in `pyproject.toml`. Sync overwrites configs on every run, so sidecars avoid stomping the user-owned `[project]` block.
 
 ## Scaffold checklist
 
-1. Scaffold with `uv init --package <name>`. This creates `pyproject.toml` with a `uv_build` backend, `.python-version` pinned to 3.14, and `src/<name with underscores>/__init__.py` holding an annotated `def main() -> None:`, so source lands under `src/` where `mypy.ini`, `pytest.ini`, and `.coveragerc` look for it. `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, oxfmt, 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: `canon tooling sync base . --write`
-4. Install python tooling: `canon 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`.
+1. Scaffold with `uv init --package <name>`. This creates `pyproject.toml` with a `uv_build` backend and `src/<name with underscores>/__init__.py` holding an annotated `def main() -> None:`.
+2. Seed `package.json` with `bun init -y`, so the base layer's bun-side tools (husky, oxfmt, commitlint) have a target. Without it the sync skips the dep install.
+3. Install base tooling with `canon tooling sync base . --write`.
+4. Install python tooling with `canon tooling sync python . --write`.
+5. Install the deps with `uv add --dev ruff mypy pytest pytest-cov`. This stays manual, since the manifest injector hardcodes `bun add -D`.
+6. Sync the lockfile and create the venv with `uv sync`.
 7. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
-The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest` collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace the smoke test with real tests.
+### What the scaffold gives
+
+Step 1 puts source under `src/`, where `mypy.ini`, `pytest.ini`, and `.coveragerc` look for it. `uv init` also pins `.python-version` to 3.14 and defaults `requires-python` to `>=3.14`, which matches the pin this stack ships.
+
+The stack ships `tests/test_smoke.py` as a copy-once seed. `pytest` then collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace it with real tests.
 
 ## What ships as golden configs
 
-- `ruff.toml`: line length 88, target `py314`, strict lint rules (`E`, `W`, `F`, `I`, `B`, `C4`, `UP`, `N`), single-quote format, banned relative imports.
-- `mypy.ini`: strict mode, `python_version = 3.14`, `mypy_path = src`, excludes `tests/` and `docs/`.
-- `pytest.ini`: tests live under `tests/`, source under `src/`.
-- `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
-- `.python-version`: pinned to `3.14` to match `uv init` defaults.
-- `scripts/verify.json`: requires Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) on top of base's runner, and stops naming `uv` when it is not on PATH. The markdown bans phase runs as it does everywhere.
+- `ruff.toml` sets line length 88, target `py314`, strict lint rules (`E`, `W`, `F`, `I`, `B`, `C4`, `UP`, `N`), single-quote format, and banned relative imports.
+- `mypy.ini` sets strict mode, `python_version = 3.14`, and `mypy_path = src`, and excludes `tests/` and `docs/`.
+- `pytest.ini` puts tests under `tests/` and source under `src/`.
+- `.coveragerc` measures branch coverage on `src/` with the html report under `.coverage_cache/html`.
+- `.python-version` is pinned to `3.14` to match `uv init` defaults.
+
+### Verify list
+
+`scripts/verify.json` requires Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) on top of base's runner. It stops naming `uv` when `uv` is not on PATH, and the markdown bans phase runs as it does everywhere.
 
 ## Hybrid project shape
 
-A python project synced with this stack ends up with both `package.json` from base and `pyproject.toml` from `uv init`. The base layer brings oxfmt, commitlint, and husky for non-Python files. Both `node_modules/` and `.venv/` coexist at the project root. The hybrid shape gives Python projects access to the toolkit's cross-cutting tools without forking the base stack.
+A python project synced with this stack holds both `package.json` from base and `pyproject.toml` from `uv init`. Base brings oxfmt, commitlint, and husky for non-Python files, and `node_modules/` and `.venv/` coexist at the project root. That gives Python projects the toolkit's cross-cutting tools without forking the base stack.
 
 ## Dependencies
 
-The manifest declares no `[dependencies.dev]`. Manifest injection currently calls `bun add -D` for any declared deps, which would fail for Python packages. v1 sidesteps this by leaving the section empty. Framework adapters that need Python deps require the injector to branch on `runtime` or detect `pyproject.toml` and call `uv add --dev` instead.
+The manifest declares no `[dependencies.dev]`, because manifest injection calls `bun add -D` for any declared deps, which fails for Python packages. Framework adapters that need Python deps require the injector to branch on `runtime`, or to detect `pyproject.toml` and call `uv add --dev`.
 
 ## Verify command
 
-`canon tooling verify python` runs the manifest's `[verify] prepare` before Sync, which is checklist steps 2, 5, and 6: `bun init -y`, `uv add --dev ruff mypy pytest pytest-cov`, and `uv sync`. `uv init` writes no `package.json`, and a verify that reaches its end with none fails, so the prepare is what lets `bun run lint:fix`, `bun run format`, and `bun run check` run at all. Python's `verify.json` requires the `lint`, `typecheck`, and `test:run` scripts that delegate to `uv run`, so the run needs `uv` on the machine and a network for the installs. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they skip.
+`canon tooling verify python` runs the manifest's `[verify] prepare` before Sync. That covers checklist steps 2, 5, and 6, being `bun init -y`, `uv add --dev ruff mypy pytest pytest-cov`, and `uv sync`.
+
+- `uv init` writes no `package.json`, and a verify that reaches its end with none fails, so the prepare is what lets `bun run lint:fix`, `bun run format`, and `bun run check` run at all.
+- Python's `verify.json` requires the `lint`, `typecheck`, and `test:run` scripts that delegate to `uv run`, so the run needs `uv` on the machine and a network for the installs.
+- The end-to-end test and screenshot phases are gated on `package.json` script keys python does not declare, so they skip.
 
 ## Anti-patterns
 
-- Do not use `pip` directly. Always go through `uv add` / `uv sync` / `uv run`.
-- Do not move `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`, or `[tool.coverage.*]` into `pyproject.toml`. Sync owns the sidecar files. Editing `pyproject.toml` tool sections will conflict with the sidecars and produce silent precedence bugs.
-- Do not pin Python via `[project] requires-python` and `.python-version` independently. Treat `.python-version` as the source of truth and let `requires-python` in `pyproject.toml` track it.
-- Do not add `commitizen` for conventional commits. The base stack already ships commitlint + husky. Two enforcers is one too many.
-- Do not ship a `Dockerfile` or `mkdocs` config under tooling. Those are framework or deployment choices and belong in the project itself or in a future adapter stack.
+- Do not use `pip` directly. Always go through `uv add`, `uv sync`, or `uv run`.
+- Do not move `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`, or `[tool.coverage.*]` into `pyproject.toml`. Sync owns the sidecars, and tool sections there cause silent precedence bugs.
+- Do not pin Python via `[project] requires-python` and `.python-version` independently. Treat `.python-version` as the source of truth and let `requires-python` track it.
+- Do not add `commitizen` for conventional commits. The base stack already ships commitlint + husky, and two enforcers is one too many.
+- Do not ship a `Dockerfile` or `mkdocs` config under tooling. Those are framework or deployment choices and belong in the project or a future adapter stack.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run lint` | Run `ruff check` and `ruff format --check`. |
-| `bun run lint:fix` | Auto-fix with `ruff check --fix` then `ruff format`. |
-| `bun run typecheck` | Run `mypy` in strict mode. |
-| `bun run test` | Run `pytest`. |
-| `bun run test:run` | Run `pytest -v` (used by `verify`). |
-| `bun run test:cov` | Run `pytest` with branch coverage and HTML report. |
+| Command             | Purpose                                              |
+| ------------------- | ---------------------------------------------------- |
+| `bun run lint`      | Run `ruff check` and `ruff format --check`.          |
+| `bun run lint:fix`  | Auto-fix with `ruff check --fix` then `ruff format`. |
+| `bun run typecheck` | Run `mypy` in strict mode.                           |
+| `bun run test`      | Run `pytest`.                                        |
+| `bun run test:run`  | Run `pytest -v` (used by `verify`).                  |
+| `bun run test:cov`  | Run `pytest` with branch coverage and HTML report.   |
 
 ## CI docs (extend)
 
-In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+In `canon/context/development/ci.md`, add or change three rows. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+
+- The Typecheck row asserts `` `mypy .` passes ``.
+- A Lint row asserts `` `ruff check` and `ruff format --check` pass ``.
+- A Tests row asserts `` `pytest` exits 0 ``.

package/tooling/shell/reference.md

@@ -6,13 +6,13 @@ The shell stack is an add-on that formats and lints the shell scripts a project
 
 ## Install
 
-- Install `shfmt` and `shellcheck` by hand, through `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither tool ships through the registry.
+- Install `shfmt` and `shellcheck` by hand with `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither ships through the registry.
 - `scripts/verify.ts` probes both before the `Shell` phase and names the install command when one is missing, rather than letting `find` report a missing executable.
 
 ## shfmt
 
 - Indent with 2 spaces, set through `--indent 2` on every call.
-- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping the block because shfmt already sets indentation produces spurious diffs.
+- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping it because shfmt sets indentation produces spurious diffs.
 
 ## shellcheck
 
@@ -27,16 +27,17 @@ The shell stack is an add-on that formats and lints the shell scripts a project
 
 ## Verify
 
-- `scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
+`scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
 
 ## lint-staged
 
-- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand, running `shfmt --write --indent 2` then `shellcheck --severity=warning`, to run the checks on commit.
+- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand to run the checks on commit.
+- That entry runs `shfmt --write --indent 2` then `shellcheck --severity=warning`.
 - Do NOT copy that 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.
 
 ## CI
 
-- `.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`: checkout, setup Bun, `bun install --frozen-lockfile`, install both tools through apt, then `check:shell`.
+`.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`. Its steps are checkout, setup Bun, `bun install --frozen-lockfile`, installing both tools through apt, then `check:shell`.
 
 ## CLI
 

package/tooling/vite-react/reference.md

@@ -4,44 +4,72 @@
 
 ## Overview
 
-The vite-react stack covers Vite + React + TypeScript projects: web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts` (merging from vite config), `playwright.config.ts`, and a unified `tsconfig.json` with `@/` path alias. Shared web tooling (oxlint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+The vite-react stack covers Vite + React + TypeScript web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts`, `playwright.config.ts`, and a unified `tsconfig.json` with an `@/` path alias. Shared web tooling (oxlint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
 
 ## 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: `canon tooling sync web . --write`
-3. Install vite-react deps and configs: `canon tooling sync vite-react . --write`
+2. Install base and web tooling with `canon tooling sync web . --write`.
+3. Install vite-react deps and configs with `canon tooling sync vite-react . --write`.
 4. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the vite-react rows below.
 5. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
 ## What ships as golden configs
 
-- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path. Dev port `5173` and preview port `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
-- `vitest.config.ts`: merges from `vite.config.ts` (imported with its `.ts` extension, which Vite 8 requires), jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
-- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, trace under `use`.
-- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
+- `vite.config.ts` adds `@vitejs/plugin-react`, `@tailwindcss/vite`, the `@` alias to `./src`, and `VITE_BASE_URL` for the base path.
+- It serves dev on port `5173` and preview on `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
+- `vitest.config.ts` merges from `vite.config.ts`, imported with its `.ts` extension, which Vite 8 requires. It sets jsdom, globals, the setup file, `passWithNoTests: true`, and v8 coverage.
+- `playwright.config.ts` runs all browsers, with `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, and trace under `use`.
+- `tsconfig.json` is unified, with `noEmit: true`, `skipLibCheck: true`, `@/` paths, and `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
 
 ## Chrome extension variant
 
-When scaffolding a Chrome extension, override the installed golden configs:
+When scaffolding a Chrome extension, override the installed golden configs.
 
-- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins. Drop `VITE_BASE_URL`.
-- `vitest.config.ts`: use a standalone `defineConfig` (no `mergeConfig`). crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly. Add `**/release/**` to excludes and `manifest.config.ts`, `**/*.d.ts` to coverage excludes.
-- `playwright.config.ts`: chromium-only (Firefox and WebKit cannot run extensions). Bundled `chromium` channel. No `baseURL` or `webServer`. Tests load the built extension directly from `dist/`.
-- `e2e/fixtures.ts`: extend Playwright base `test` with `context` (persistent context loading the extension from `dist/`) and `extensionId` (extracted from service worker URL). Rename `use` to `apply` to avoid oxlint's `react/rules-of-hooks`. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
-- `manifest.config.ts`: use `defineManifest` from `@crxjs/vite-plugin`. Read `name` and `version` from `package.json`. Entry points `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, `src/content/main.tsx`. Permissions `sidePanel`, `contentSettings`, `storage`. Icon `public/logo.png` at size 48.
-- `screenshot` script: `bun run build && bun e2e/screenshot.ts` (no preview server).
-- Additional gitignore entries: `*.crx`, `*.pem`, `release/`.
+### Build config
+
+The crxjs plugin replaces the plain React build.
+
+- `vite.config.ts` uses `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Drop `VITE_BASE_URL`.
+- Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins.
+
+### Test configs
+
+The plugin also changes how Vitest and Playwright run.
+
+- `vitest.config.ts` uses a standalone `defineConfig` with no `mergeConfig`, since the crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly.
+- It also adds `**/release/**` to excludes, and `manifest.config.ts` and `**/*.d.ts` to coverage excludes.
+- `playwright.config.ts` is chromium-only, since Firefox and WebKit cannot run extensions.
+- It uses the bundled `chromium` channel with no `baseURL` or `webServer`, and tests load the built extension from `dist/`.
+
+### Fixtures and manifest
+
+The extension needs a fixture file and a manifest config.
+
+- `e2e/fixtures.ts` extends Playwright's base `test` with `context`, a persistent context loading the extension from `dist/`, and `extensionId`, extracted from the service worker URL.
+- Rename `use` to `apply` in that file to avoid oxlint's `react/rules-of-hooks`. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
+- `manifest.config.ts` uses `defineManifest` from `@crxjs/vite-plugin` and reads `name` and `version` from `package.json`.
+- Its entry points are `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, and `src/content/main.tsx`.
+- Its permissions are `sidePanel`, `contentSettings`, and `storage`, with icon `public/logo.png` at size 48.
+
+### Scripts and ignores
+
+The extension build changes one script and adds ignores.
+
+- The `screenshot` script is `bun run build && bun e2e/screenshot.ts`, with no preview server.
+- Add `*.crx`, `*.pem`, and `release/` to gitignore.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run dev` | Start the Vite dev server on port 5173, plus this worktree's port offset. |
-| `bun run build` | Typecheck then build the production bundle. |
-| `bun run preview` | Serve the built bundle locally. |
-| `bun run typecheck` | Run `tsc --noEmit`. |
+| Command             | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `bun run dev`       | Start the Vite dev server on 5173 plus this worktree's offset. |
+| `bun run build`     | Typecheck then build the production bundle.                    |
+| `bun run preview`   | Serve the built bundle locally.                                |
+| `bun run typecheck` | Run `tsc --noEmit`.                                            |
 
 ## CI docs (extend)
 
-In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row asserts `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->