@erclx/canon 5.39.0 → 5.41.0

package/tooling/claude/reference.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The claude stack installs the `.claude/` workflow directory into a project. State docs are seeds, written once and never overwritten by tooling. `CLAUDE.md` is a seed, filled in per project after init.
+The claude stack installs the `.claude/` workflow directory into a project. Tooling writes state docs once and never overwrites them. `CLAUDE.md` is one of those seeds, and a project fills it in after init.
 
 ## Structure
 
@@ -26,52 +26,70 @@ canon/
 └── tmp/               ← ephemeral scratch space, safe to delete without loss
 ```
 
-One ignore entry covers `.canon/` whole, so nothing under it is named separately and nothing tracked may ever land there. A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root.
+One ignore entry covers `.canon/` whole, so nothing under it is named separately and nothing tracked may land there. A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root.
 
 ## Moving the records to `.canon/`
 
-A project installed before the split still holds its records under `.claude/`. `canon migrate records` moves them and repoints every tracked file that cites one, reporting the plan until `--write` is passed.
+A project installed before the split holds its records under `.claude/`. `canon migrate records` moves them and repoints every tracked file that cites one, reporting the plan until `--write` is passed.
 
-Run `canon tooling sync claude . --write` first. The verb refuses while the project does not ignore `.canon/`, because every folder it relocates is ignored where it stands and landing one under a tracked root commits the task board and the plans. Until the move runs, this project's records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
-
-The verb ships with the change that split the roots and is not in a published release yet, so an installed binary answers `unknown command` until one carries it. Run it out of a canon checkout in the meantime, as `bun src/cli.ts migrate records --root <project> --write`, and read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten.
+- Run `canon tooling sync claude . --write` first. The verb refuses until the project ignores `.canon/`, since a relocated folder under a tracked root commits the task board and plans.
+- Until the move runs, the records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
+- An installed binary answers `unknown command` until a published release carries the verb. Meanwhile run `bun src/cli.ts migrate records --root <project> --write` from a canon checkout.
+- Read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten.
 
 ## Upgrading from a single-file board
 
-A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
+A project installed before the board became a folder still holds `.claude/TASKS.md`, and nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
 
-Convert by hand, once per project:
+Convert by hand, once per project.
 
-1. Split each `###` block into `.canon/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks reference in the `task-board` skill requires. Compare each new file against the block it came from rather than checking that every block landed somewhere.
+1. Split each `###` block into `.canon/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the `task-board` skill requires. Compare each new file against its source block.
 2. Run `canon indexes regen --no-stage --root . .canon/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.canon/tasks/`.
 
 ## Gitignore
 
-- `# Claude`: `.canon/`, `.claude/worktrees/`, `.claude/.tmp/` <!-- canon-keep-record-root -->
+The `# Claude` group holds three entries, being `.canon/`, `.claude/worktrees/`, and `.claude/.tmp/`. <!-- canon-keep-record-root -->
 
-The first entry covers the whole record root, so a record folder added later needs no line here and no sync. The second is the carve-out the harness owns, since it creates a worktree under `.claude/` and requires its target to sit there. The third is the scratch rule's fallback spelling, carried for a project the record move has not reached and retired once none is left to reach.
+- The first entry covers the whole record root, so a record folder added later needs no line here and no sync.
+- The second is the carve-out the harness owns, since it creates a worktree under `.claude/` and requires its target to sit there.
+- The third is the scratch rule's fallback spelling, carried for a project the record move has not reached and retired once none is left.
 
 ## CLI
 
-| Command              | What it does                                                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                                                                                                 |
-| `canon claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status.                                                                            |
-| `canon claude setup` | Installs user-level config to `~/.claude/`: statusline, attribution, and the `permissions.allow` and `permissions.deny` lists. Run once per machine. |
+| Command              | What it does                                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `canon claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                                                                            |
+| `canon claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status.                                                       |
+| `canon claude setup` | Installs user-level config to `~/.claude/` once per machine: statusline, attribution, and the permissions allow and deny lists. |
 
 ## CLAUDE.md
 
-- Ships as a seed with placeholder project name, description, and key paths. Fill these in after init.
-- Section layout: `Context`, `Commands`, `Key paths`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
-- The `Context` section points at `.claude/` state docs one line. `plan-feature` does the parallel read when invoked. The seed intentionally does not re-list every file.
+- It ships as a seed with placeholder project name, description, and key paths, to fill in after init.
+- Its sections are `Context`, `Commands`, and `Key paths`. Each groups rules that share a surface, so skills can detect, extend, or skip by heading.
+- The `Context` section points at `.claude/` state docs in one line. `plan-feature` does the parallel read when invoked, so the seed does not re-list every file.
 
 ## Seed docs
 
-- Seed docs ship with a guidelines preamble above the first H2. These are instructions Claude internalizes before filling in the sections below. They are not sections to populate.
+Seed docs ship with a guidelines preamble above the first H2. Claude internalizes those instructions before filling in the sections below, and they are not sections to populate.
 
 ## settings.json
 
-- Project seed at `tooling/claude/seeds/.claude/settings.json` ships three PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh`, `.claude/hooks/search-reminder.sh`, and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
-- User-level template at `tooling/claude/user/settings.template.json` carries `attribution.commit` and `attribution.pr` (empty strings to suppress co-author tags), `permissions.allow` with `Bash(bun run *)`, and `permissions.deny` with `Read(**/.env)` and `Read(**/.env.*)` to block accidental secret exposure across any project. Installed once per machine via `canon claude setup`.
+The project and user files split what is project-specific from what is personal.
+
+### Project seed
+
+The seed at `tooling/claude/seeds/.claude/settings.json` ships hooks that pair with scripts under `.claude/hooks/`.
+
+- Three PreToolUse hooks pair with `index-reminder.sh`, `search-reminder.sh`, and `scratch-guard.sh`.
+- A PostToolUse hook pairs with `standards-audit.sh`.
+- Project settings layer over user settings, so a project file carries only what is project-specific.
+
+### User template
+
+The template at `tooling/claude/user/settings.template.json` is installed once per machine by `canon claude setup`.
+
+- It sets `attribution.commit` and `attribution.pr` to empty strings to suppress co-author tags.
+- It allows `Bash(bun run *)` under `permissions.allow`.
+- Its `permissions.deny` holds `Read(**/.env)` and `Read(**/.env.*)`, blocking accidental secret exposure across any project.
 - The deprecated `includeCoAuthoredBy` key is not used.

package/tooling/cloudflare/reference.md

@@ -2,25 +2,44 @@
 
 ## Overview
 
-The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies, seeds, or scripts of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack at the same root without colliding.
+The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies, seeds, or scripts of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack without colliding.
 
 ## Deploy workflow
 
-- Separate `build` and `deploy` jobs, connected by an uploaded artifact, converged on the shape already running in the closest prior art rather than invented fresh.
-- The deploy job checks for `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` before doing anything else, and skips with a `::notice::` rather than failing when either is absent. A first merge lands ahead of the Pages project existing, and this guard is what keeps that push green.
-- `--branch=${{ github.ref_name }}` on every deploy, which gives every branch a Cloudflare preview URL rather than only `main`. A `workflow_dispatch` run from a branch therefore lands on a preview and never on production, which is what makes dispatching the workflow from an unmerged branch safe.
-- The Publish step carries `id: publish` and pins `wranglerVersion`, since the `pages-deployment-alias-url` output it reads first appears in wrangler 3.78. A step after it prints that alias to the job log as `canon-preview-alias: <url>` and to the step summary. `canon pr preview` reads the line out of the run log, so the marker text is a contract with the CLI rather than decoration.
-- The concurrency group carries `${{ github.ref_name }}`. GitHub cancels a pending run when a newer one queues in the same group, so a shared group would let a branch preview displace a production deploy waiting its turn.
-- A `pull_request` trigger on `closed` runs only the `cleanup-preview` job, which deletes every preview deployment Cloudflare holds for that branch. It lists them through the Pages REST API, because the wrangler listing has no branch filter, and deletes each with `force=true` so a deployment still holding the branch alias goes too. It skips with a notice when the secrets are absent, the same as the deploy job.
-- The deploy job checks out the repository and installs Bun even though it builds nothing. `wrangler-action` resolves its package manager from `bun.lock` in the checkout, and dropping that step breaks the deploy on every push once the toolchain it relies on silently goes missing.
+### Job shape
+
+Separate `build` and `deploy` jobs connect through an uploaded artifact, converged on the shape already running in the closest prior art rather than invented fresh.
+
+- The deploy job checks for `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` first, and skips with a `::notice::` when either is absent, so a first merge ahead of the Pages project stays green.
+- The deploy job checks out the repository and installs Bun though it builds nothing, since `wrangler-action` resolves its package manager from `bun.lock` in the checkout.
+- The concurrency group carries `${{ github.ref_name }}`. GitHub cancels a pending run when a newer one queues in its group, so a shared group lets a preview displace a production deploy.
+
+### Previews
+
+Every branch gets a preview URL rather than only `main`.
+
+- `--branch=${{ github.ref_name }}` on every deploy gives each branch a Cloudflare preview URL.
+- A `workflow_dispatch` run from an unmerged branch therefore lands on a preview and never on production, which makes dispatching it safe.
+- The Publish step carries `id: publish` and pins `wranglerVersion`, since the `pages-deployment-alias-url` output it reads first appears in wrangler 3.78.
+- A step after Publish prints the alias to the job log as `canon-preview-alias: <url>` and to the step summary.
+- `canon pr preview` reads that line out of the run log, so the marker text is a contract with the CLI.
+
+### Cleanup
+
+A `pull_request` trigger on `closed` runs only the `cleanup-preview` job, which deletes every preview deployment Cloudflare holds for that branch.
+
+- It lists them through the Pages REST API, because the wrangler listing has no branch filter.
+- It deletes each with `force=true`, so a deployment still holding the branch alias goes too.
+- It skips with a notice when the secrets are absent, the same as the deploy job.
 
 ## Parameters a project fills in by hand
 
-Three values in the seeded file have no generic default and are set once, right after sync:
+Three values in the seeded file have no generic default, and a project sets them once right after sync.
 
-- The `paths:` filter under the `push` trigger. The shipped default is a single `src/**` glob. Widen it to cover every path the build reads when the build draws on catalogs or generated content living outside `src/`.
-- The `concurrency.group` name. The shipped default is `deploy-${{ github.ref_name }}`, which is enough for a single-deploy project. Give the `deploy` prefix a project-specific name only if the project runs more than one deploy workflow, and keep the ref suffix.
-- The Pages project name, written twice as `REPLACE_WITH_PROJECT_NAME`: once in the `--project-name` flag on the `wrangler pages deploy` command and once as `PROJECT_NAME` in the cleanup job. Set both to the name the `deploy-app` skill creates the Pages project under.
+- The `paths:` filter under the `push` trigger ships as a single `src/**` glob. Widen it to every path the build reads when the build draws on catalogs or generated content outside `src/`.
+- The `concurrency.group` name ships as `deploy-${{ github.ref_name }}`, enough for one deploy. Rename the `deploy` prefix only for a second deploy workflow, and keep the ref suffix.
+- The Pages project name appears twice as `REPLACE_WITH_PROJECT_NAME`, in the `--project-name` flag and as `PROJECT_NAME` in the cleanup job.
+- Set both to the name the `deploy-app` skill creates the project under.
 
 ## Re-sync
 

package/tooling/go/reference.md

@@ -9,30 +9,48 @@ The go stack covers Go modules linted and formatted by `golangci-lint` v2, type-
 ## Scaffold checklist
 
 1. Scaffold with `go mod init <module-path>`. The module path is the project's own identity, so this stack never ships a `go.mod`.
-2. Keep `./...` out of `node_modules`: `go mod edit -ignore=./node_modules`. At a root sync the base layer installs `node_modules/` inside the module, and a package there can ship a `.go` file that `go vet`, `go test`, and `golangci-lint` would otherwise walk. The directive needs Go 1.25 or later.
-3. Seed `package.json` so the base layer's bun-side tools (husky, oxfmt, commitlint) have a target to install into: `bun init -y`.
-4. Install base tooling: `canon tooling sync base . --write`
-5. Install go tooling: `canon tooling sync go . --write`
-6. Install the linter: `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`. The manifest declares no `[dependencies.dev]`, because manifest injection runs `bun add -D`, which cannot install a Go tool. This step stays manual.
+2. Keep `./...` out of `node_modules` with `go mod edit -ignore=./node_modules` (Go 1.25 or later). A root sync installs `node_modules/` in the module, and a package there can ship `.go` files.
+3. Seed `package.json` with `bun init -y`, so the base layer's bun-side tools (husky, oxfmt, commitlint) have a target to install into.
+4. Install base tooling with `canon tooling sync base . --write`.
+5. Install go tooling with `canon tooling sync go . --write`.
+6. Install the linter with `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`. This stays manual, since manifest injection runs `bun add -D`, which cannot install a Go tool.
 7. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
-The go stack also ships `smoke_test.go` at the module root as a copy-once seed. A module with no `.go` file fails `golangci-lint run`, `go vet`, and `go test` on an empty package list, so the seed is what lets `bun run check` pass on a fresh scaffold. It declares `package main`, so delete or rename it once the root package takes another name, or the build reports two packages in one folder.
+### The smoke test seed
+
+The stack ships `smoke_test.go` at the module root as a copy-once seed. A module with no `.go` file fails the linter, `go vet`, and `go test` on an empty package list, so the seed lets `bun run check` pass on a fresh scaffold.
+
+It declares `package main`. Delete or rename it once the root package takes another name, or the build reports two packages in one folder.
 
 ## golangci-lint
 
-- Use config `version: '2'`.
-- Start from `default: standard`.
-- Enable `bodyclose`, `errorlint`, `gosec`, `misspell`, `noctx`, `revive`, `sqlclosecheck`, `rowserrcheck`, and `unconvert`. The two SQL linters report only on `database/sql` call sites, so they cost nothing in a module without a database.
-- Enable formatters `gofmt` and `goimports`. `lint:fix` runs `golangci-lint fmt` ahead of `golangci-lint run --fix`.
-- Exclude `node_modules` from both linters and formatters. The `go.mod` `ignore` directive in the checklist covers every Go tool, but `go.mod` belongs to the project and sync cannot write it, so the config keeps `golangci-lint run` from reporting and `golangci-lint fmt` from rewriting a vendored `.go` file in a module that never added the directive.
+The config uses `version: '2'` and starts from `default: standard`.
+
+- Enable `bodyclose`, `errorlint`, `gosec`, `misspell`, `noctx`, `revive`, `sqlclosecheck`, `rowserrcheck`, and `unconvert`.
+- The two SQL linters report only on `database/sql` call sites, so they cost nothing without a database.
+- Enable formatters `gofmt` and `goimports`, with `lint:fix` running `golangci-lint fmt` ahead of `golangci-lint run --fix`.
+- Exclude `node_modules` from both linters and formatters. The `go.mod` `ignore` directive covers every Go tool, but `go.mod` belongs to the project and sync cannot write it.
+- That exclusion keeps `golangci-lint run` from reporting, and `golangci-lint fmt` from rewriting, a vendored `.go` file in a module that never added the directive.
 
 ## verify.json
 
-- Require Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`). Base's runner adds the four base phases wherever the folder declares their scripts, then the markdown bans stage.
+### Phases
+
+The go phase list requires three phases and probes the tools first.
+
+- Require Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`).
+- Base's runner adds the four base phases where the folder declares their scripts, then the markdown bans stage.
 - Probe `go` and `golangci-lint` first, and name the `go install` command when `golangci-lint` is missing.
-- Keep `build` out of `verify.json`, even though the stack declares the script. `go build ./...` exits 1 with `no packages to build` on a module holding only a test file, and a seeded `main.go` would assume every module is a binary rather than a library.
-- Keep `-race` out of `test:run`. The race detector needs cgo and a C toolchain, so it belongs in CI rather than in a local `bun run check`.
-- The manifest's `[verify] prepare` runs checklist steps 3 and 6 for `canon tooling verify go`: `bun init -y`, then the `golangci-lint` `go install` when the binary is not already on PATH. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
+
+### Left out and prepared
+
+Two things stay out of the list, and one step runs before it.
+
+- Keep `build` out, though the stack declares the script. `go build ./...` exits 1 with `no packages to build` on a module holding only a test file.
+- A seeded `main.go` would assume every module is a binary rather than a library.
+- Keep `-race` out of `test:run`. The race detector needs cgo and a C toolchain, so it belongs in CI rather than a local `bun run check`.
+- The manifest's `[verify] prepare` runs checklist steps 3 and 6 for `canon tooling verify go`, being `bun init -y` and the `go install` when the binary is not on PATH.
+- The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## CI
 
@@ -48,15 +66,21 @@ The go stack also ships `smoke_test.go` at the module root as a copy-once seed.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run lint` | Run `golangci-lint run`. |
-| `bun run lint:fix` | Format with `golangci-lint fmt`, then auto-fix with `golangci-lint run --fix`. |
-| `bun run typecheck` | Run `go vet`. |
-| `bun run test` | Run `go test`. |
-| `bun run test:run` | Run `go test -v` (used by `verify`). |
-| `bun run build` | Run `go build`. |
+| Command             | Purpose                                                                        |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `bun run lint`      | Run `golangci-lint run`.                                                       |
+| `bun run lint:fix`  | Format with `golangci-lint fmt`, then auto-fix with `golangci-lint run --fix`. |
+| `bun run typecheck` | Run `go vet`.                                                                  |
+| `bun run test`      | Run `go test`.                                                                 |
+| `bun run test:run`  | Run `go test -v` (used by `verify`).                                           |
+| `bun run build`     | Run `go build`.                                                                |
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``. <!-- audit-ignore-citations: canon/context/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 `` `go vet ./...` passes ``.
+- A Lint row asserts `` `golangci-lint run` passes ``.
+- A Tests row asserts `` `go test -race ./...` exits 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/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/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/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/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/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/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 ``.