@erclx/canon 5.37.0 → 5.39.0

package/tooling/web/configs/.oxlintrc.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn"],
+  "categories": {
+    "correctness": "off"
+  },
+  "env": {
+    "builtin": true
+  },
+  "ignorePatterns": [
+    "dist",
+    "dist-ssr",
+    "coverage",
+    "release",
+    ".claude",
+    ".vscode",
+    ".husky",
+    "test-results",
+    "playwright-report",
+    "blob-report",
+    "playwright/.cache"
+  ],
+  "rules": {
+    "constructor-super": "error",
+    "for-direction": "error",
+    "getter-return": "error",
+    "no-async-promise-executor": "error",
+    "no-case-declarations": "error",
+    "no-class-assign": "error",
+    "no-compare-neg-zero": "error",
+    "no-cond-assign": "error",
+    "no-const-assign": "error",
+    "no-constant-binary-expression": "error",
+    "no-constant-condition": "error",
+    "no-control-regex": "error",
+    "no-debugger": "error",
+    "no-delete-var": "error",
+    "no-dupe-class-members": "error",
+    "no-dupe-else-if": "error",
+    "no-dupe-keys": "error",
+    "no-duplicate-case": "error",
+    "no-empty": "error",
+    "no-empty-character-class": "error",
+    "no-empty-pattern": "error",
+    "no-empty-static-block": "error",
+    "no-ex-assign": "error",
+    "no-extra-boolean-cast": "error",
+    "no-fallthrough": "error",
+    "no-func-assign": "error",
+    "no-global-assign": "error",
+    "no-import-assign": "error",
+    "no-invalid-regexp": "error",
+    "no-irregular-whitespace": "error",
+    "no-loss-of-precision": "error",
+    "no-misleading-character-class": "error",
+    "no-new-native-nonconstructor": "error",
+    "no-nonoctal-decimal-escape": "error",
+    "no-obj-calls": "error",
+    "no-prototype-builtins": "error",
+    "no-redeclare": "error",
+    "no-regex-spaces": "error",
+    "no-self-assign": "error",
+    "no-setter-return": "error",
+    "no-shadow-restricted-names": "error",
+    "no-sparse-arrays": "error",
+    "no-this-before-super": "error",
+    "no-unassigned-vars": "error",
+    "no-unreachable": "error",
+    "no-unsafe-finally": "error",
+    "no-unsafe-negation": "error",
+    "no-unsafe-optional-chaining": "error",
+    "no-unused-labels": "error",
+    "no-unused-private-class-members": "error",
+    "no-unused-vars": "error",
+    "no-useless-backreference": "error",
+    "no-useless-catch": "error",
+    "no-useless-escape": "error",
+    "no-with": "error",
+    "preserve-caught-error": "error",
+    "require-yield": "error",
+    "use-isnan": "error",
+    "valid-typeof": "error",
+    "no-array-constructor": "error",
+    "no-unused-expressions": "error",
+    "typescript/ban-ts-comment": "error",
+    "typescript/no-duplicate-enum-values": "error",
+    "typescript/no-empty-object-type": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/no-extra-non-null-assertion": "error",
+    "typescript/no-misused-new": "error",
+    "typescript/no-namespace": "error",
+    "typescript/no-non-null-asserted-optional-chain": "error",
+    "typescript/no-require-imports": "error",
+    "typescript/no-this-alias": "error",
+    "typescript/no-unnecessary-type-constraint": "error",
+    "typescript/no-unsafe-declaration-merging": "error",
+    "typescript/no-unsafe-function-type": "error",
+    "typescript/no-wrapper-object-types": "error",
+    "typescript/prefer-as-const": "error",
+    "typescript/prefer-namespace-keyword": "error",
+    "typescript/triple-slash-reference": "error"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+      "rules": {
+        "constructor-super": "off",
+        "getter-return": "off",
+        "no-class-assign": "off",
+        "no-const-assign": "off",
+        "no-dupe-class-members": "off",
+        "no-dupe-keys": "off",
+        "no-func-assign": "off",
+        "no-import-assign": "off",
+        "no-new-native-nonconstructor": "off",
+        "no-obj-calls": "off",
+        "no-redeclare": "off",
+        "no-setter-return": "off",
+        "no-this-before-super": "off",
+        "no-unreachable": "off",
+        "no-unsafe-negation": "off",
+        "no-var": "error",
+        "no-with": "off",
+        "prefer-const": "error",
+        "prefer-rest-params": "error",
+        "prefer-spread": "error"
+      }
+    },
+    {
+      "files": ["**/*.{ts,tsx,js,jsx}"],
+      "rules": {
+        "simple-import-sort/imports": "error",
+        "simple-import-sort/exports": "error",
+        "check-file/filename-naming-convention": [
+          "error",
+          {
+            "**/!(App).{ts,tsx}": "KEBAB_CASE"
+          },
+          {
+            "ignoreMiddleExtensions": true
+          }
+        ],
+        "check-file/folder-naming-convention": [
+          "error",
+          {
+            "src/**/!(__tests__)/": "KEBAB_CASE"
+          }
+        ],
+        "no-unused-vars": [
+          "error",
+          {
+            "varsIgnorePattern": "^_",
+            "argsIgnorePattern": "^_"
+          }
+        ],
+        "react/rules-of-hooks": "error",
+        "react/exhaustive-deps": "warn",
+        "react/static-components": "error",
+        "react/use-memo": "error",
+        "react/preserve-manual-memoization": "error",
+        "react/incompatible-library": "warn",
+        "react/immutability": "error",
+        "react/globals": "error",
+        "react/refs": "error",
+        "react/set-state-in-effect": "error",
+        "react/error-boundaries": "error",
+        "react/purity": "error",
+        "react/set-state-in-render": "error",
+        "react/unsupported-syntax": "warn",
+        "react/only-export-components": [
+          "warn",
+          {
+            "allowConstantExport": true
+          }
+        ]
+      },
+      "jsPlugins": [
+        "eslint-plugin-simple-import-sort",
+        "eslint-plugin-check-file"
+      ],
+      "plugins": ["react"],
+      "env": {
+        "browser": true
+      }
+    },
+    {
+      "files": ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+      "rules": {
+        "vitest/expect-expect": "error",
+        "vitest/no-identical-title": "error",
+        "vitest/no-commented-out-tests": "error",
+        "vitest/valid-title": "error",
+        "vitest/valid-expect": "error",
+        "vitest/valid-describe-callback": "error",
+        "vitest/require-local-test-context-for-concurrent-snapshots": "error",
+        "vitest/no-import-node-test": "error",
+        "vitest/no-focused-tests": "error"
+      },
+      "plugins": ["vitest"]
+    },
+    {
+      "files": [
+        "*.config.{js,mjs,cjs,ts}",
+        "vite.config.ts",
+        "vitest.config.ts",
+        "playwright.config.ts"
+      ],
+      "env": {
+        "node": true
+      }
+    }
+  ]
+}

package/tooling/web/manifest.toml

@@ -6,16 +6,9 @@ scaffold = ""
 
 [dependencies.dev]
 packages = [
-  "eslint@^9",
-  "eslint-config-prettier",
+  "oxlint@1.87.0",
   "eslint-plugin-check-file",
-  "eslint-plugin-react-hooks",
-  "eslint-plugin-react-refresh",
   "eslint-plugin-simple-import-sort",
-  "eslint-plugin-vitest",
-  "globals",
-  "typescript-eslint",
-  "@eslint/js",
   "typescript@^6",
   "react",
   "react-dom",
@@ -32,12 +25,9 @@ packages = [
   "@playwright/test",
   "tailwindcss",
   "@tailwindcss/vite",
-  "prettier-plugin-tailwindcss",
 ]
 
 [scripts]
-"lint" = "eslint . --max-warnings 0"
-"lint:fix" = "eslint . --fix --max-warnings 0"
 "test" = "vitest"
 "test:run" = "vitest run --reporter=verbose"
 "test:ui" = "vitest --ui"
@@ -50,12 +40,18 @@ packages = [
 "smoke:prod" = "bun e2e/screenshot.ts --check-console-clean --require-base-url"
 
 [scripts.override]
-"lint" = "eslint . --max-warnings 0"
+"lint" = "oxlint --max-warnings 0"
+"lint:fix" = "oxlint --fix --max-warnings 0"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
 "readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]
 "# Coverage" = ["coverage/"]
-"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]
+"# Playwright" = [
+  "test-results/",
+  "playwright-report/",
+  "blob-report/",
+  "playwright/.cache/",
+]
 "# Screenshots" = ["screenshots/"]

package/tooling/web/reference.md

@@ -4,13 +4,13 @@
 
 ## Overview
 
-The web layer covers web-universal tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for ESLint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework-specific wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
+The web layer covers web-universal tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for oxlint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework-specific wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
 
 ## What ships as golden configs
 
 Golden config files live in `tooling/web/configs/` and are copied into the target on `canon tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
-- `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
+- `.oxlintrc.json`: migrated from the ESLint config it replaced. Runs the recommended JS and TypeScript rules, the React hooks and refresh rules, test-scoped vitest rules plus `no-focused-tests`, and `check-file` and `simple-import-sort` as JS plugins.
 - `src/test/setup.ts`: `@testing-library/jest-dom/vitest` import, `cleanup` after each test.
 - `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
@@ -54,9 +54,8 @@ Two worktrees of one repository run the same stack, so a fixed port makes the se
 
 Sticky negative knowledge. Do not relearn.
 
-- Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and ESLint lints the emitted files. Use `tsc --noEmit`.
-- Do NOT accept `eslint@^10` alongside `typescript-eslint@^8`. Chain breaks with `TypeError: Class extends value undefined` from `LegacyESLint`. Pin `eslint@^9` until `typescript-eslint@^9` with ESLint 10 support ships.
-- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships its own `"lint": "oxlint"` under a bare `.oxlintrc.json`, which runs a different rule set from the stack's ESLint config and never gates on it. `[scripts.override]` forces the stack's own eslint invocation back over it.
+- Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and the linter lints the emitted files. Use `tsc --noEmit`.
+- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships a bare `"lint": "oxlint"`, which exits 0 on warnings. `[scripts.override]` forces `--max-warnings 0` over it, and the golden `.oxlintrc.json` overwrites the scaffold's bare one.
 - Do NOT rely on bare-folder exclude globs like `exclude: ["e2e"]`. Use `"e2e/**/*"`.
 - Do NOT ship Vitest with no-tests-fail. Fresh scaffolds have zero tests. Use `passWithNoTests: true` or equivalent until the project has at least one test.
 - Do NOT put Playwright `trace` at the top level of `defineConfig`. It lives under `use`.
@@ -68,17 +67,18 @@ Sticky negative knowledge. Do not relearn.
 - Unit tests: Vitest with jsdom, globals on, setup file at `src/test/setup.ts`, `@testing-library/react`, `@testing-library/user-event`.
 - E2E: Playwright in `e2e/`. Chromium-only for Chrome extensions, all browsers for web apps.
 - Tailwind: v4 via `@tailwindcss/vite`. Never the v3 integration.
-- Prettier: `prettier-plugin-tailwindcss` last in plugins array. Astro also adds `prettier-plugin-astro` first.
+- Lint: oxlint at an exact pin, since its JS plugin host is alpha and a minor release could break `check-file` or `simple-import-sort`. Astro keeps ESLint, which its own reference covers.
 
-## Prettier (extend)
+## oxlint
 
-- Base ships `.prettierrc` with `semi: false`, `singleQuote: true`. Web layer adds `jsxSingleQuote: true` and `prettier-plugin-tailwindcss` via the manifest.
-- Per-stack overrides go in the stack's configs (Astro adds `prettier-plugin-astro` and the `.astro` parser override).
+- Set `lint` and `lint:fix` through `[scripts.override]`, so an already-synced target stops running ESLint on its next sync.
+- Delete a leftover `eslint.config.js` or `eslint.config.mjs`, and `bun remove` the ESLint packages this stack stopped shipping, by hand after that sync. Sync deletes nothing a stack stopped shipping.
+- Keep import sorting on `simple-import-sort` rather than oxfmt's built-in sort, which orders imports differently and would rewrite every import block.
 
 ## lint-staged (extend)
 
-- Add `**/*.{js,jsx,ts,tsx}` glob running `eslint --fix --max-warnings 0`, and `prettier --write`.
-- Extend the prettier glob to include `css`: `**/*.{json,css,md,mdc}`.
+- Add `**/*.{js,jsx,ts,tsx}` glob running `oxlint --fix --max-warnings 0`, and `oxfmt --no-error-on-unmatched-pattern`.
+- Extend the oxfmt glob to include `css`: `**/*.{json,css,md}`.
 
 ## CI docs (extend)
 
@@ -87,7 +87,7 @@ Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs. <!-
 Append rows:
 
 | Typecheck | `bun run typecheck` | framework-specific typecheck passes |
-| Lint | `bun run lint` | ESLint passes with zero warnings |
+| Lint | `bun run lint` | oxlint passes with zero warnings |
 | Tests | `bun run test:coverage` | Vitest passes with coverage thresholds |
 | Build | `bun run build` | Production build succeeds |
 | E2E | `bun run test:e2e` | Playwright passes against the built preview |
@@ -100,8 +100,8 @@ Extend the `development` context entry under `canon/context/` so the `## Scripts
 
 Append rows:
 
-| `bun run lint` | Run ESLint with zero warnings allowed. |
-| `bun run lint:fix` | Auto-fix ESLint issues. |
+| `bun run lint` | Run oxlint with zero warnings allowed. |
+| `bun run lint:fix` | Auto-fix oxlint issues. |
 | `bun run test` | Run Vitest in watch mode. |
 | `bun run test:run` | Run Vitest once with verbose reporter. |
 | `bun run test:coverage` | Run Vitest with coverage. |

package/docs/agents/commands.md

@@ -1,154 +0,0 @@
----
-title: Command catalog
-description: Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
----
-
-# Command catalog
-
-Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. A pipe gets the same text without the frame glyphs. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
-
-`canon <command> --help` lists subcommands, and `canon <command> <subcommand> --help` a leaf's flags, exit codes, and examples. `canon <command> --help --all` prints both. An unknown subcommand exits 1 under a group taking no operand.
-
-## Project-level
-
-One row per top-level command, in the order `canon --help` prints them. A domain's subcommands are in `## Domain commands` below.
-
-| Command                     | Purpose                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------ |
-| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                          |
-| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`               |
-| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names                 |
-| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write`            |
-| `canon targets <verb>`      | Report the projects this toolkit installed into                                            |
-| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them                         |
-| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                                      |
-| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                                   |
-| `canon wiki <verb>`         | Scaffold the wiki pages                                                                    |
-| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them                      |
-| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                   |
-| `canon design <verb>`       | Render or regenerate `canon/DESIGN.md` tokens, emit their CSS, install the base stylesheet |
-| `canon slides <verb>`       | Render a deck folder of HTML slides, or list the decks                                     |
-| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved                          |
-| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                             |
-| `canon demo <verb>`         | Compile and record a running app                                                           |
-| `canon inventory [subject]` | Group every route's elements by one computed property, never gating                        |
-| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                              |
-| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                      |
-| `canon teach <verb>`        | Open and author learning workspaces                                                        |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them             |
-| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                                 |
-| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive                         |
-| `canon intake <verb>`       | Report intake folders and write answers into them                                          |
-| `canon records <verb>`      | Validate, size, prune, and back up the session records                                     |
-| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines                |
-| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                                      |
-| `canon hooks <verb>`        | Run the steps a git hook drives                                                            |
-| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence                |
-| `canon feedback`            | Open a GitHub issue from toolkit feedback on stdin, or print the block on failure          |
-| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline                 |
-| `canon gate <verb>`         | Run every stage that guards a branch here                                                  |
-| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                              |
-| `canon deps <verb>`         | Report published advisories against the resolved dependency set                            |
-| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text                       |
-| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git                        |
-| `canon context <verb>`      | Report context folder health, and classify changed or stale sections                       |
-| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure               |
-| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries                  |
-| `canon upstream <verb>`     | Read Claude Code releases from a cursor, and list the toolkit's own mechanisms             |
-
-`canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
-
-A port already in use is the ordinary case rather than a refusal, so it walks forward to the next free one and reports which it took. That is why a caller reads `url` off the `--json` record instead of composing one from the port it asked for. Only contention is walked past. Any other bind failure refuses as `bind-failed` carrying the error's code, rather than being retried twenty times and reported as a range being full, which names a cause nothing checked.
-
-A request naming a directory is redirected to its trailing-slash form rather than answered in place. A browser resolves a relative asset against the last slash of the URL it is on, so answering `/lesson` directly leaves the page asking for `/course.css` instead of `/lesson/course.css`, and it renders unstyled through the server that exists to prevent exactly that.
-
-Containment is tested after symlinks are followed rather than on the path as written, and the test sits immediately before the read rather than beside the request that produced it. Resolving a request lexically clears a link pointing outside the served root, and a link out of the served root is the shape it guards against. Position is what makes the property hold: a directory request appends its index after the request path has been checked, so a check placed earlier leaves that index untested. `--index` answers a directory holding no `index.html` with a listing read per request, where the default stays a 404. Every entry the listing names takes the same containment test a request for it would, so a link out of the root is absent rather than greyed, and dotfiles are hidden. With no `--entry` and no root `index.html`, the printed link is `/` and `entryExists` reads true. An `--entry` that escapes the root refuses with `no-entry` before a port is taken, because `url` is the field a caller hands to a reader.
-
-`canon demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
-
-`canon inventory` is the third and takes the same answer for the same reason. It reads `inventory.toml` at the project root for its base URL, its routes, and the element query each subject runs over, so what it walks comes from the project rather than from the toolkit. It reports how many different answers a site gives for one property and never gates, because whether five focus rings across four routes is a defect is a judgment. A missing server and an unmatched query are both refusals rather than empty listings, since a listing with no rows reads as one consistent answer.
-
-```toml
-base-url = "http://localhost:4173"
-routes = ["/", "/pricing", "/docs"]
-
-[subjects.focus]
-query = "button, a[href], input, select, textarea, [tabindex]"
-```
-
-`canon drive` is the fourth and ships for the same reason the three before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
-
-## Domain commands
-
-Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`. The page named beside a domain carries its flags, records, and refusals, and `canon <domain> --help --all` prints every subcommand's flags.
-
-- **`migrate`**, in `migrate.md`: `rename`, `skill-names`, `records`, `surface-roots`, `record-tree`, `rule-layout`, `scratch-evidence`, `record-layout`
-- **`targets`**, in `targets.md`: `list`, `pulls`
-- **`gov`**, in `install-and-sync.md`: `list`, `install`, `sync`, `build`, `regen`, `detect` (in `gov-detect.md`), `test-order`, `counts`, `superseded`, `citations`, `restated`
-- **`tooling`**, in `install-and-sync.md`: `list`, `sync`, `diff`, `reference`, `verify`, `inject`, `prune-gitignore`
-- **`claude`**, in `skills-audit.md`: `init`, `sync`, `setup`, `routing`, `plugin-update`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`
-- **`wiki`**, in `scripting.md`: `init`
-- **`indexes`**, in `indexes.md`: `regen`, `list`
-- **`docs`**, in `docs.md`: `list`, `<topic>`
-- **`design`**, in `install-and-sync.md` for `install`, `sync`, and `fonts`, and below for the rest: `render`, `regen`, `css`, `install`, `sync`, `fonts`
-- **`slides`**, described below: `render`, `list`
-- **`demo`**, in `demo.md`: `compile`, `run`, `frames`
-- **`inventory`**, described above: `run`
-- **`teach`**, in `teach.md`: `list`, `up`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
-- **`canvas`**, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `frame resize`, `fit`, `arrange`, `selection`, `edit`, `editing`, `capture`
-- **`sandbox`**, in `sandbox.md`: `run`, `equivalence`, `reset`, `clean`, `check`, `coverage`
-- **`tasks`**, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
-- **`intake`**, in `intake.md`: `list`, `answer`
-- **`records`**, in `records.md`: `validate`, `ordinal`, `size`, `stale`, `prune-tmp`, `push`, `pull`
-- **`sessions`**, in `sessions.md`: `list`, `export`, `import`
-- **`worktrees`**, in `worktrees.md`: `list`, `reclaim`, `repair-bare-flag` (hidden)
-- **`hooks`**, in `hooks.md`: `post-merge`
-- **`pr`**, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`, `lift` (in `pr-lift.md`), `tick` (in `pr-tick.md`)
-- **`upstream`**, in `upstream.md`: `fetch`, `catalog`, `due`, `advance`
-- **`audits`**, in `audits.md`: `run`, `list`
-- **`gate`**, in `gate.md`: `run`
-- **`secrets`**, in `state-scoped-risk.md`: `scan`
-- **`deps`**, in `state-scoped-risk.md`: `audit`
-- **`labels`**, in `label-coverage.md`: `audit`, `apply`, `scan`
-- **`comments`**, in `comments.md`: `scan`
-- **`context`**, in `context-audit.md`: `audit`, `classify diff`, `classify sweep`, `classifier show`, `classifier set`
-- **`markdown`**, in `markdown-audit.md`: `audit`
-
-Common patterns:
-
-- **`list --json`** → machine-readable catalog on stdout.
-- **`install <name> <path>`** → install a specific entry into a target project.
-- **`sync <path>`** → reapply all installed entries in a target project.
-- **`create [name]`** → scaffold a new authoring entry in this repo.
-
-Subcommands no other page describes:
-
-- **`claude plugin-update`** matches the installed marketplace plugin against `claude/.claude-plugin/plugin.json`'s own name and runs `claude plugin update` on it, reading the version back off `claude plugin list --json`, since the update call reports none of its own (`--json`).
-- **`claude skills rank`** scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
-- **`design regen`** rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
-- **`slides list --json`** emits one row per deck under `.canon/slides/`, carrying `name`, `title`, `slides`, and `path`.
-- **`slides render [deck]`** takes a deck name or a folder, defaulting to the only deck, and lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
-- **`slides.md`** describes a deck folder's `deck.json` and the faces it embeds, its per-slide `<body>` attributes, transitions and entrances, speaker notes, and charts.
-- **`canvas`**, with its verbs, content format, and write routes, is described in `canvas.md`.
-- **`labels apply <number>`** adds the labels this branch earns to its open pull request, refusing a pull request whose head is not the current branch or that is not open, and never creating a label the remote lacks or removing one a person added (`--check` writes nothing and exits 2 when labels are owed, `--base`, `--json`).
-- **`labels scan`** fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a banned character, a body heading outside the closed section list or a missing `## Summary` or `## Key changes`, or a title breaking `claude/skills/git-pr/references/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
-
-## Version skew
-
-`canon sync --check` and `canon claude skills drift` are the two moments a
-target already stops to reconcile with the toolkit, so each reports the
-installed version against the newest published one. No other command performs
-the lookup, which keeps a registry round trip out of the catalog reads an agent
-runs in a loop.
-
-The report carries three states and never changes an exit code. `behind` names
-`canon upgrade` as the remedy, `current` says so, and `unknown` carries the
-reason the registry could not be reached. Branch on the `skew.state` field in
-the JSON record rather than on the exit, since an offline machine has to read as
-unmeasured rather than as a failing check.
-
-`canon upgrade --json` carries one further state, `pending`, that the skew
-report does not: the working directory's checkout holds a release npm does not
-serve yet, so there is nothing to install. The record names it in `checkout`
-beside `latest`, exits 0, and its `message` starts `CLI stays at`. Outside a
-canon checkout it never reads `pending`.

package/docs/agents/docs.md

@@ -1,27 +0,0 @@
----
-title: Docs
-description: How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
----
-
-# Docs
-
-`canon docs` emits the toolkit's own reference docs so an agent in a target project can orient without the toolkit source checked out. The CLI resolves `docs/` and `canon/context/` from its install root, and which of the two it finds depends on how the CLI was installed. A registry install carries `docs/` alone, since `.claude/` is not published. A clone or a linked worktree carries both.
-
-- `canon docs list [--json]` lists the downstream catalog: the consumer-facing `docs/` surface plus per-domain narrative from `canon/context/` when that root is present. Toolkit-internal context entries (`ci`, `development`, `sandbox`) are dropped. From a registry install the context section is absent rather than empty.
-- `canon docs <topic>` prints one doc to stdout, resolved by exact name from `docs/` first, then `canon/context/`. Any doc the install carries is reachable by name, including the toolkit-internal topics the list omits.
-
-## How a name resolves
-
-A domain too large for one file splits into `<domain>/` with a generated `index.md`, and both verbs name it by the folder. `canon docs <domain>` prints that index, which is the catalog routing to the sub-area files, and the listing describes it from the index's `subtitle` where a sibling file supplies `description`. A folder carrying no `index.md` is absent from both, since a catalog is what makes the sub-areas reachable, and so are the files inside it.
-
-A sub-area file resolves by its bare name too, so `canon docs operating-model` reaches `docs/workflow/operating-model.md`. Three spellings are tried in order, being a sibling file, a folder of that name, then a sub-area file one level down, and each spelling is tried across both roots before the next one runs. A sibling file therefore wins over a folder of the same name, and both win over a sub-area file. Reading the folder last is what keeps the sub-area spelling from changing any name that resolved before it existed.
-
-The sub-area spelling keeps the root order too. The first root whose folders carry the name answers, so `canon docs indexes` reaches `docs/agents/indexes.md` even though a context folder holds an entry of the same name. A bare name carried by two folders of that one root resolves to neither, which names the available topics and exits 1 rather than answering with whichever folder sorts first.
-
-`canon docs list` stops at the folder where `canon docs <topic>` goes on to name each file inside it. The listing is the downstream catalog rather than the index of what a name reaches, so a sub-area file appears there only where it declares a target-facing `category` of its own, and no sub-area file of the context root appears at all. A name that resolves and does not list is the divergence the toolkit-internal topics already carry.
-
-## Output
-
-Data prints to stdout and the frame to stderr, so `canon docs <topic> > out.md` captures clean markdown. With no topic and no verb, `canon docs` runs `list`. An unknown topic names the available topics on stderr and exits 1.
-
-Only a `---` block opening on the first line counts as frontmatter, so a document body carrying horizontal rules emits whole.