@erclx/canon 5.43.0 → 5.45.0

package/docs/agents/output-shape.md

@@ -62,14 +62,13 @@ Discover names at runtime rather than hardcoding them.
 Set `CANON_NON_INTERACTIVE=1` to refuse every prompt.
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon init --stack node --skip wiki /path/to/project
+CANON_NON_INTERACTIVE=1 canon init --stack node --skip records /path/to/project
 CANON_NON_INTERACTIVE=1 canon sync /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
 CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
 CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
-CANON_NON_INTERACTIVE=1 canon wiki init /path/to/project
 canon tooling inject base /path/to/project --configs --seeds
 canon tooling prune-gitignore base /path/to/project
 canon tooling verify vite-react

package/docs/target/migrations.md

@@ -46,9 +46,22 @@ Run it once, ahead of `canon gov sync` or `canon gov install`.
 
 ## Rename the skill citations, once
 
-Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. The five per-kind drafters merged into `draft-doc`, and no pointer under an old name ships. <!-- canon-keep-retired -->
+Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. The five per-kind drafters merged into `write-doc`, and no pointer under an old name ships. <!-- canon-keep-retired -->
+
+The seven `draft-` skills took verb-first names for what each makes. `canon migrate skill-names --write` carries a project across, and a pointer under each old name answers a typed invocation until it retires.
+
+| Old name           | New name                                        |
+| ------------------ | ----------------------------------------------- |
+| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
+| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
+| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
+| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
+| `draft-and-pick`   | `pick-by-eye` <!-- canon-keep-retired -->       |
+| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
+| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
 
 - `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare prose mention by hand. <!-- canon-keep-retired -->
+- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request. Replace a bare mention of the skill by hand. <!-- canon-keep-retired -->
 - `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
 - `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
 - `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, and `ux-walkthrough` have no successor <!-- canon-keep-retired -->
@@ -108,7 +121,7 @@ From the registry the walk reports `historyUnavailable`, so check both paths by
 | `context-fold`    | `context`                                                     |
 | `canvas-board`    | `canvas`, `design`                                            |
 | `docs-sync`       | `docs`, `readme`                                              |
-| `draft-figure`    | `figures`, `mermaid`                                          |
+| `draw-figure`     | `figures`, `mermaid`                                          |
 | `create-rule`     | `rule`                                                        |
 | `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
 | `git-branch`      | `branch`, `slug`                                              |
@@ -119,8 +132,8 @@ From the registry the walk reports `historyUnavailable`, so check both paths by
 | `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
 | `plan-intake`     | `intake`                                                      |
 | `plan-feature`    | `plan`, `plan-lifecycle`                                      |
-| `draft-ready`     | `ready`                                                       |
-| `draft-doc`       | `requirements`, `wiki`                                        |
+| `plan-ready`      | `ready`                                                       |
+| `write-doc`       | `requirements`, `wiki`                                        |
 | `session-map`     | `session`                                                     |
 
 The `standard` name became `skill-reference.md` in `create-skill`.
@@ -147,3 +160,21 @@ canon migrate session-defaults --write --json
 ```
 
 The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+
+## Move the capture cases out of the harness, once
+
+A web project's `e2e/screenshot.ts` is a config, so sync overwrites it. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. Cases edited in the old harness leave the working tree on the first sync and stay in git history.
+
+- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts` before the next sync.
+- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
+- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
+
+## Add the keyboard rule beside a held a11y rule, once
+
+The `a11y` rule split in two. Focus styles, Escape and shortcuts, composite widgets, focus management, and pointer target size moved to a new `keyboard` rule. `canon gov sync` refreshes only the rules a project holds, so it rewrites `a11y.md` without those bullets and never adds `keyboard.md`.
+
+A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
+
+```bash
+canon gov install --add keyboard --yes .
+```

package/docs/target/projects.md

@@ -57,7 +57,7 @@ Before the first feature session:
 
 1. Fill `canon/REQUIREMENTS.md` with the problem, goals, and non-goals. The seed's 600-word cap gates under `canon context audit`.
 2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:canvas-board`
-3. Optionally invoke `canon:draft-figure` for an architecture view. The Mermaid CLI downloads on first use.
+3. Optionally invoke `canon:draw-figure` for an architecture view. The Mermaid CLI downloads on first use.
 4. Start the feature loop in [AI workflow](../workflow/ai-workflow.md)
 
 ### Stack decision
@@ -70,10 +70,9 @@ The default is `base`. Escalate only for a project writing code, and `target-set
 
 ### Core domains and skips
 
-`canon init` installs base tooling, the Claude workflow, and governance, and scaffolds `.claude/wiki/`. Pass `--stack <name>` for a language stack.
+`canon init` installs base tooling, the Claude workflow, and governance. Pass `--stack <name>` for a language stack.
 
 - `--skip governance` leaves `.claude/rules/` empty. The run prints the `canon gov install <stack> <path>` command that restores the rules it dropped.
-- `--skip wiki` skips the `.claude/wiki/` scaffold. A root `wiki/` is kept.
 
 ## Add a domain later
 

package/docs/target/scenarios.md

@@ -42,4 +42,7 @@ canon tooling sync python ./backend --skip base --write
 
 `--skip base` keeps husky, oxfmt, commitlint, and CI at the root. Every subtree still receives `scripts/verify.ts` and `scripts/verify.json`, and its own framework configs.
 
-A sync into a subfolder withholds `.github/`, so run the subtree from the root workflow with `working-directory` set to the path the sync prints. It installs nothing into a subtree without a `package.json` and ends on `run 'bun init' in <path>, then sync again`. Run `bun scripts/verify.ts` in the subtree, since the `check` script lives at the root.
+A sync into a subfolder withholds `.github/`, so run the subtree from the root workflow with `working-directory` set to the path the sync prints. Run `bun scripts/verify.ts` in the subtree, since the `check` script lives at the root.
+
+- A subtree with no `package.json` gets a minimal one holding the folder's name, version `0.0.0`, and `type: module`, then the install runs into it
+- An existing file is never rewritten, and one that is not valid JSON ends the sync on `package.json is not valid JSON: fix it in <path>, then sync again`

package/docs/workflow/parallel-features.md

@@ -49,13 +49,14 @@ Merge order matters only when two branches touch the same file. Expect to rebase
 
 ## The task board
 
-`.canon/tasks/` is gitignored and resolves at the main worktree root, one file per task. A hook generates `index.md`, and `priority.md` carries execution order and blockers.
+`.canon/tasks/` is gitignored and resolves at the main worktree root, one file per task. A hook generates `index.md`, and `priority.md` carries execution order and blockers. `canon tasks place`, `promote`, `move`, and `block` write it, deriving every cell but `Waiting on`.
 
 `canon tasks validate` reports and never writes:
 
 - A row's cell count must match its header, and a `## Needs a plan` row stating its position is checked against where it sits
 - Every plan pointer resolves, every task file is named once, and every ready row names its files
-- A parked row is reported when its cited task reached the trunk
+- A parked row is reported when its cited task reached the trunk, whether the cell links it or names its bare label
+- A group header must be the columns the group owns, a `Touches` cell must match its plan, and a `Waiting on` cell renders at most 120 characters
 
 `canon:task-board` creates a task file, and `canon:task-complete` marks outcomes. The `post-merge` hook archives the task a merged pull request closed, with its plan, and a `post-rewrite` hook does the same for a rebase pull. Both archive only when the merge carried a PR number and the task is closed.
 

package/docs/workflow/skill-map-on-request.md

@@ -10,18 +10,24 @@ These skills serve a request rather than a moment. With the [skill map](skill-ma
 
 ## Generate an artifact on demand
 
-| Skill                     | When to use                                       |
-| ------------------------- | ------------------------------------------------- |
-| `canon:create-rule`       | A project rule the toolkit does not ship          |
-| `canon:create-skill`      | A new `SKILL.md`                                  |
-| `canon:draft-doc`         | A new `docs/` page, context entry, or `README.md` |
-| `canon:draft-ready`       | Finished files a worker should copy               |
-| `canon:draft-figure`      | A figure or architecture view inside a doc        |
-| `canon:ci-workflow`       | A GitHub Actions workflow file                    |
-| `canon:draft-slides`      | A deck rendered to editable PowerPoint            |
-| `canon:draft-screencast`  | A recording script with beats seeded              |
-| `canon:record-screencast` | Recording a screencast draft into a finished mp4  |
-| `canon:draft-identity`    | A logo mark and social card                       |
+| Skill                     | When to use                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| `canon:create-rule`       | A project rule the toolkit does not ship                                           |
+| `canon:create-skill`      | A new `SKILL.md`                                                                   |
+| `canon:write-doc`         | A new `docs/` page, context entry, or `README.md`                                  |
+| `canon:draft-doc`         | Never on purpose. A pointer naming `write-doc` <!-- canon-keep-retired -->         |
+| `canon:plan-ready`        | Finished files a worker should copy                                                |
+| `canon:draft-ready`       | Never on purpose. A pointer naming `plan-ready` <!-- canon-keep-retired -->        |
+| `canon:draw-figure`       | A figure or architecture view inside a doc                                         |
+| `canon:draft-figure`      | Never on purpose. A pointer naming `draw-figure` <!-- canon-keep-retired -->       |
+| `canon:ci-workflow`       | A GitHub Actions workflow file                                                     |
+| `canon:make-deck`         | A deck rendered to editable PowerPoint                                             |
+| `canon:draft-slides`      | Never on purpose. A pointer naming `make-deck` <!-- canon-keep-retired -->         |
+| `canon:script-screencast` | A recording script with beats seeded                                               |
+| `canon:draft-screencast`  | Never on purpose. A pointer naming `script-screencast` <!-- canon-keep-retired --> |
+| `canon:record-screencast` | Recording a screencast draft into a finished mp4                                   |
+| `canon:design-identity`   | A logo mark and social card                                                        |
+| `canon:draft-identity`    | Never on purpose. A pointer naming `design-identity` <!-- canon-keep-retired -->   |
 
 ## Answer a question at any point
 
@@ -34,4 +40,4 @@ These skills serve a request rather than a moment. With the [skill map](skill-ma
 | `canon:markdown-craft`      | Before a substantial markdown edit                    |
 | `canon:write-human`         | Before drafting or revising prose                     |
 
-Ask `canon:teach-workspace` to promote a learning workspace's reference pages and glossaries. It proposes a destination per page and waits. An Anthropic-owned subject goes to the wiki, an internal one to the matching context entry, and the rest to the public docs. A project with no wiki folder gets a refusal naming `canon wiki init`.
+Ask `canon:teach-workspace` to promote a learning workspace's reference pages and glossaries. It proposes a destination per page and waits. An Anthropic-owned subject goes to the wiki, an internal one to the matching context entry, and the rest to the public docs. A project with no wiki folder gets a refusal naming the folder to create.

package/docs/workflow/skill-map.md

@@ -17,18 +17,19 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 ## Decide what to build
 
-| Skill                      | When to use                                        |
-| -------------------------- | -------------------------------------------------- |
-| `canon:plan-intake`        | The input is a pile of findings                    |
-| `canon:plan-intake-answer` | An intake folder holds unread slots                |
-| `canon:backlog-triage`     | The backlog needs pruning                          |
-| `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
-| `canon:decision-escalate`  | Open decisions turn on your preference             |
-| `canon:draft-and-pick`     | The call is taste, wanting candidates side by side |
-| `canon:canvas-board`       | A direction should be drawn as editable frames     |
-| `canon:task-board`         | A decided item needs a file on the board           |
-| `canon:plan-feature`       | The approach is settled and needs a plan           |
-| `canon:codebase-layout`    | A change adds a file and needs a folder            |
+| Skill                      | When to use                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------- |
+| `canon:plan-intake`        | The input is a pile of findings                                              |
+| `canon:plan-intake-answer` | An intake folder holds unread slots                                          |
+| `canon:backlog-triage`     | The backlog needs pruning                                                    |
+| `canon:plan-groundwork`    | The state is unmeasured and approaches compete                               |
+| `canon:decision-escalate`  | Open decisions turn on your preference                                       |
+| `canon:pick-by-eye`        | The call is taste, wanting candidates side by side                           |
+| `canon:draft-and-pick`     | Never on purpose. A pointer naming `pick-by-eye` <!-- canon-keep-retired --> |
+| `canon:canvas-board`       | A direction should be drawn as editable frames                               |
+| `canon:task-board`         | A decided item needs a file on the board                                     |
+| `canon:plan-feature`       | The approach is settled and needs a plan                                     |
+| `canon:codebase-layout`    | A change adds a file and needs a folder                                      |
 
 ## Build the feature
 

package/docs/workflow/visual-design-workflow.md

@@ -19,9 +19,9 @@ The default. `canon/DESIGN.md` holds visual intent as one Overview paragraph, at
 These skills cover the tier:
 
 - `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
-- `canon:draft-and-pick` drafts candidates as frames on the canvas and takes your pick
+- `canon:pick-by-eye` drafts candidates as frames on the canvas and takes your pick
 - `canon:canvas-board` works a direction out as HTML frames you edit in the browser. Only the pick moves into `canon/DESIGN.md`.
-- `canon:draft-identity` drafts a logo mark and social card
+- `canon:design-identity` drafts a logo mark and social card
 
 Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.
 

package/governance/detect.toml

@@ -169,6 +169,10 @@ files = ["index.html", "*/index.html"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
+["keyboard"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
 ["forms"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]

package/governance/ledger/framework/astro.md

@@ -0,0 +1,73 @@
+---
+title: Astro rule ledger
+description: Sources for governance/rules/framework/astro.md, one row per bullet
+---
+
+# Astro rule ledger
+
+The field is front-end engineering, and the authority is the Astro documentation at docs.astro.build. The pages read name no current major, so most rows record the read date alone. The content rows follow the Astro 6 upgrade guide, which removed the legacy collection location.
+
+## Static first
+
+| Bullet                        | Source                                                                                                                                                                               | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| `.astro` without client state | [Islands architecture](https://docs.astro.build/en/concepts/islands/): Astro components "render to static HTML with no client-side runtime"                                          | 2026-10-18 |
+| Fetch in the frontmatter      | [Data fetching](https://docs.astro.build/en/guides/data-fetching/): "All Astro components have access to the global fetch() function in their component script", run "at build time" | 2026-10-18 |
+
+## Islands
+
+| Bullet                         | Source                                                                                                                                                                                                                            | Read       |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Directive on the component     | [Template directives](https://docs.astro.build/en/reference/directives-reference/): "A client directive can only be used on a UI framework component that is directly imported into a .astro component"                           | 2026-10-18 |
+| Pick the directive by priority | [Template directives](https://docs.astro.build/en/reference/directives-reference/): `client:load` is for "Immediately-visible UI elements", `client:idle` for "Lower-priority UI elements", `client:visible` for "below the fold" | 2026-10-18 |
+
+## Routing and layouts
+
+| Bullet                        | Source                                                                                                                                                                                                    | Read       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `getStaticPaths()` for params | [Routing](https://docs.astro.build/en/guides/routing/): in static mode every parameter value needing a page comes from `getStaticPaths()`, while "In SSR mode, a page will be generated on request"       | 2026-10-18 |
+| Layouts with `<slot />`       | [Layouts](https://docs.astro.build/en/basics/layouts/): "Layouts are Astro components used to provide a reusable UI structure", with "a slot to specify where individual page content should be injected" | 2026-10-18 |
+
+## Content
+
+| Bullet                          | Source                                                                                                                                                                                                                            | Read                |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `src/content.config.ts` loaders | [Content collections](https://docs.astro.build/en/guides/content-collections/): "All of your build-time content collections are defined in a special src/content.config.ts file", with "two built-in loaders (glob() and file())" | 2026-10-18, Astro 6 |
+| Query through the API           | [Content collections](https://docs.astro.build/en/guides/content-collections/): "getCollection() fetches an entire collection and returns an array of entries"                                                                    | 2026-10-18          |
+
+## Styles and assets
+
+| Bullet            | Source                                                                                                                                                                       | Read       |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Scoped by default | [Styles and CSS](https://docs.astro.build/en/guides/styling/): "Scoped styles should be used as often as possible" and "Global styles should be used only as-needed"         | 2026-10-18 |
+| Images in `src/`  | [Images](https://docs.astro.build/en/guides/images/): "We recommend that local images are kept in src/ when possible so that Astro can transform, optimize, and bundle them" | 2026-10-18 |
+
+## Environment
+
+| Bullet                    | Source                                                                                                                                                                                                                | Read       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `astro:env` and `PUBLIC_` | [Environment variables](https://docs.astro.build/en/guides/environment-variables/): "only environment variables prefixed with PUBLIC\_ are available in client-side code", and `astro:env` gives "a type-safe schema" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "content collections in `src/content/` with a `config.ts` schema". The [Astro 6 upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v6/) removed that location in favor of `src/content.config.ts`.
+
+### Cut without a source or a bug class
+
+- Cut "do not add a framework integration until the first island needs it" as a dependency call with no page read taking a side.
+- Cut "keep islands leaf-level, never wrap layout chrome to enable nested islands", which no reviewer can check against one line.
+- Cut "use `[param].astro` and `[...rest].astro`" as the file convention Claude already follows. The kept routing bullet names the `getStaticPaths()` footgun instead.
+
+### Merged or reworded
+
+- Reworded the hedged "write pages and components as `.astro` unless interactivity requires an island" to a test on client state and event handlers.
+- Reworded the hedged "prefer server-rendered content over client-fetched data" to where the fetch call sits.
+- Reworded "apply `client:*` directives on the component boundary, not on parents" to the rule the directives reference states.
+- Reworded "prefer `client:visible` or `client:idle` over `client:load`" to the priority each directive is documented for.
+- Merged "access collection entries via `getCollection` and `getEntry`" into the query bullet.
+- Reworded "use `is:global` only in layouts" to include `:global()`, the selector the styling page names for the same case.
+- Extended "read environment variables via `import.meta.env`" with `astro:env`, the typed schema the docs now offer.

package/governance/ledger/framework/fastapi.md

@@ -0,0 +1,76 @@
+---
+title: FastAPI rule ledger
+description: Sources for governance/rules/framework/fastapi.md, one row per bullet
+---
+
+# FastAPI rule ledger
+
+The field is back-end Python web engineering, and the authority is the FastAPI documentation at fastapi.tiangolo.com. None of the pages read names a FastAPI major, so the rows record the read date alone.
+
+## Routers
+
+| Bullet                      | Source                                                                                                                                                                                              | Read       |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One `APIRouter` per feature | [Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/): "You can think of APIRouter as a mini FastAPI class", and "With app.include_router() we can add each APIRouter"  | 2026-10-18 |
+| Router-level dependencies   | [Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/): router `dependencies` "can be used, for example, to require authentication for a whole group of path operations" | 2026-10-18 |
+
+## Path operations
+
+| Bullet                        | Source                                                                                                                                                                                                                                    | Read       |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `async def` only when awaited | [Concurrency and async / await](https://fastapi.tiangolo.com/async/): a plain `def` "is run in an external threadpool that is then awaited", and "use async def unless your path operation functions use code that performs blocking I/O" | 2026-10-18 |
+| Response model omits secrets  | [Response Model](https://fastapi.tiangolo.com/tutorial/response-model/): FastAPI "will limit and filter the output data to what is defined in the return type"                                                                            | 2026-10-18 |
+| Body as a Pydantic model      | [Request Body](https://fastapi.tiangolo.com/tutorial/body/): "To declare a request body, you use Pydantic models", which validate it and return "a nice and clear error" when it is invalid                                               | 2026-10-18 |
+
+## Dependencies
+
+| Bullet                          | Source                                                                                                                                                                                            | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `Annotated` and type aliases    | [Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/): "Prefer to use the Annotated version if possible", and the value can be stored "in a variable and use it in multiple places" | 2026-10-18 |
+| Session per request via `yield` | [Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/): "you could use this to create a database session and close it after finishing"            | 2026-10-18 |
+| Overrides in tests              | [Testing Dependencies with Overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/): "your FastAPI application has an attribute app.dependency_overrides"                          | 2026-10-18 |
+
+## Lifespan and settings
+
+| Bullet                     | Source                                                                                                                                                                                                         | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `lifespan`, not `on_event` | [Lifespan Events](https://fastapi.tiangolo.com/advanced/events/): "If you provide a lifespan parameter, startup and shutdown event handlers will no longer be called"                                          | 2026-10-18 |
+| Cached `BaseSettings`      | [Settings and Environment Variables](https://fastapi.tiangolo.com/advanced/settings/): with `@lru_cache` "the Settings object will be created only once", and a dependency override replaces it during testing | 2026-10-18 |
+
+## Errors
+
+| Bullet                | Source                                                                                                                                                | Read       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Raise `HTTPException` | [Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/): "To return HTTP responses with errors to the client you use HTTPException" | 2026-10-18 |
+| One exception handler | [Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/): "You could add a custom exception handler with @app.exception_handler()"   | 2026-10-18 |
+| Safe summaries only   | House choice: an exception message or traceback in a response leaks internals such as SQL, file paths, and library versions to the caller             | 2026-10-18 |
+
+## Middleware
+
+| Bullet                | Source                                                                                                                                                                | Read       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Explicit CORS origins | [CORS](https://fastapi.tiangolo.com/tutorial/cors/): "None of allow_origins, allow_methods and allow_headers can be set to ['*'] if allow_credentials is set to True" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "define path operations as `async def` unless purely CPU-bound". The [async page](https://fastapi.tiangolo.com/async/) says "If you just don't know, use normal def", and CPU work in `async def` blocks the loop too.
+- Cut "an `app_factory()` callable over a module-level `app` for testability". Every docs example uses a module-level `app` and tests through `app.dependency_overrides`, which the kept bullet names.
+
+### Cut without a source or a bug class
+
+- Cut "group routers by feature under `src/<pkg>/api/`" as a layout call, which the `codebase-layout` skill owns.
+- Cut "annotate path, query, and body parameters, never `**kwargs`", since FastAPI cannot read `**kwargs` and Claude already annotates them.
+- Cut "configure trusted hosts and HTTPS redirects through middleware" as a deployment choice with no page read taking a side.
+
+### Merged or reworded
+
+- Merged "mount routes through `APIRouter`, never directly on `FastAPI()`" into the router bullet.
+- Reworded "return pydantic models and set `response_model=`" to name the filter, which is the footgun the [Response Model](https://fastapi.tiangolo.com/tutorial/response-model/) page warns about with passwords.
+- Merged "express shared logic as `Depends(...)` over decorators or globals" into the `Annotated` bullet.
+- Merged "do not perform blocking I/O inside `async def`" into the `async def` bullet.
+- Narrowed "configure CORS through middleware, not per-route checks" to the credentials footgun the CORS page states.
+- Moved "apply `dependencies=[Depends(auth)]` at the router or app level" to the routers section.

package/governance/ledger/framework/nextjs.md

@@ -0,0 +1,86 @@
+---
+title: Next.js rule ledger
+description: Sources for governance/rules/framework/nextjs.md, one row per bullet
+---
+
+# Next.js rule ledger
+
+The field is front-end engineering, and the authority is the Next.js documentation at nextjs.org, read against the App Router docs for Next.js 16. The rule loads on every `.ts` and `.tsx` file in a target, so the rewrite cut it from 352 words to under 250.
+
+## Routing
+
+| Bullet                   | Source                                                                                                                                                                                      | Read                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| App Router, not `pages/` | House choice: a second router in one app splits layouts, data fetching, and caching across two models, so a change made in one never reaches routes in the other                            | 2026-10-18             |
+| Await `params`           | [route.js](https://nextjs.org/docs/app/api-reference/file-conventions/route): "`context.params` is now a promise" since v15, and every page example types `params: Promise<{ id: string }>` | 2026-10-18, Next.js 16 |
+
+## Server and client components
+
+| Bullet                          | Source                                                                                                                                                                                                                                                      | Read                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| Server by default               | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "By default, layouts and pages are Server Components", with Client Components for state, event handlers, lifecycle logic, and browser-only APIs   | 2026-10-18, Next.js 16 |
+| `'use client'` at the leaf      | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "add 'use client' at the top of the files that define your interactive components instead of marking large parts of your UI as Client Components" | 2026-10-18, Next.js 16 |
+| Serializable, minimal props     | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): props "need to be serializable", and [Data Security](https://nextjs.org/docs/app/guides/data-security) marks passing a whole row as "EXPOSED"     | 2026-10-18, Next.js 16 |
+| `server-only` on secret modules | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "To prevent accidental usage in Client Components, you can use the server-only package"                                                           | 2026-10-18, Next.js 16 |
+
+## Data and caching
+
+| Bullet                           | Source                                                                                                                                                                                                                                                    | Read                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `'use cache'` with `cacheLife`   | [Fetching Data](https://nextjs.org/docs/app/getting-started/fetching-data): "fetch requests are not cached by default", and [Caching](https://nextjs.org/docs/app/getting-started/caching): "We recommend pairing every cache directive with a cacheLife" | 2026-10-18, Next.js 16 |
+| `<Suspense>` around runtime data | [Caching](https://nextjs.org/docs/app/getting-started/caching): "Components that access runtime APIs should be wrapped in Suspense"                                                                                                                       | 2026-10-18, Next.js 16 |
+| Revalidate after a mutation      | [Mutating Data](https://nextjs.org/docs/app/getting-started/mutating-data): "you can revalidate the Next.js cache and show the updated data by calling revalidatePath or revalidateTag within the Server Function"                                        | 2026-10-18, Next.js 16 |
+
+## Mutations
+
+| Bullet                        | Source                                                                                                                                                                                                                                                      | Read                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| Verify auth inside the action | [Mutating Data](https://nextjs.org/docs/app/getting-started/mutating-data): "Server Functions are reachable via direct POST requests, not just through your application's UI. Always verify authentication and authorization inside every Server Function." | 2026-10-18, Next.js 16 |
+| Validate input, trim output   | [Data Security](https://nextjs.org/docs/app/guides/data-security): "You should always validate input from client", and "Only return what the UI needs, not raw database records"                                                                            | 2026-10-18, Next.js 16 |
+
+## Built-in primitives
+
+| Bullet                       | Source                                                                                                                                                                                                                                  | Read                   |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `next/link` and `next/image` | [Linking and Navigating](https://nextjs.org/docs/app/getting-started/linking-and-navigating): "Next.js automatically prefetches routes linked with the Link component", and a plain anchor gets "No prefetching"                        | 2026-10-18, Next.js 16 |
+| Image dimensions or `fill`   | [Image Component](https://nextjs.org/docs/app/api-reference/components/image): "If the source image is a dynamic or a remote URL, you must provide the width and height props", and with `fill` "the parent element must be positioned" | 2026-10-18, Next.js 16 |
+
+## Environment
+
+| Bullet                          | Source                                                                                                                                                                                                                                                 | Read                   |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `NEXT_PUBLIC_` only when needed | [Environment Variables](https://nextjs.org/docs/app/guides/environment-variables): Next.js can "inline a value, at build time, into the js bundle that is delivered to the client", and the values are "frozen with the value evaluated at build time" | 2026-10-18, Next.js 16 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "set explicit caching on every `fetch`" with the `'use cache'` bullet. New apps run Cache Components, which [Caching](https://nextjs.org/docs/app/getting-started/caching) drives through the directive.
+- Cut "return `NextResponse` over raw `Response`", since the [route.js](https://nextjs.org/docs/app/api-reference/file-conventions/route) reference returns the Web `Response` throughout.
+- Cut "read params from the function signature, not the request URL" as stale. The signature form holds, and the kept bullet adds the `await` the current major requires.
+- Cut "return no `Response` or stream from a Server Action". No page read forbids it, and the kept bullet states what the docs do say about return values.
+
+### Cut without a source or a bug class
+
+- Cut "use route segment files for their documented purpose" as a convention Claude already follows.
+- Cut "place HTTP endpoints in `app/**/route.ts`, never `pages/api/`" as covered by the App Router bullet.
+- Cut "export named HTTP methods" as enforced by the framework, which only routes the named exports.
+- Cut "export `metadata` or `generateMetadata` over manual head tags" as a convention Claude already follows.
+
+### Cut for the word budget
+
+A sourced practice cut only because the rule loads on every TypeScript file. A later pass with room can bring it back.
+
+- Cut "use `next/font` over manual link tags", which the docs still recommend.
+
+### Merged or reworded
+
+- Merged "do not fetch in client components when a server alternative exists" into the server-by-default bullet, since the docs list fetching among a Server Component's uses.
+- Merged "do not introduce `pages/` in new code" into the App Router bullet.
+- Merged "push the boundary as deep as possible" into the leaf bullet.
+- Merged "mark Server Actions with `'use server'`", which the build requires, into the mutation bullets.
+- Reworded "validate Server Action inputs with a Zod schema" to any validation, since [Data Security](https://nextjs.org/docs/app/guides/data-security) names no library.
+- Reworded "use `revalidatePath` or `revalidateTag` over manual refetch loops" to the call the mutation page shows.
+- Merged "never read unprefixed env vars in a client component" into the env bullet, since [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) says "If variables are not prefixed, Next.js replaces them with an empty string".

package/governance/ledger/framework/react.md

@@ -0,0 +1,83 @@
+---
+title: React rule ledger
+description: Sources for governance/rules/framework/react.md, one row per bullet
+---
+
+# React rule ledger
+
+The field is front-end engineering, and the authority is the React team's documentation at react.dev. The rewrite started from groundwork spike S2's draft and reads its three unread leads.
+
+## Rendering
+
+| Bullet                      | Source                                                                                                                                                                                           | Read                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Pure during render          | [Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure): side effects "should not run in render, as React can render components multiple times" | 2026-10-18, React 19 |
+| Never mutate props or state | [Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure): "A component's props and state are immutable snapshots. Never mutate them directly."   | 2026-10-18, React 19 |
+| Stable data keys, not index | [Rendering lists](https://react.dev/learn/rendering-lists): "Index as a key often leads to subtle and confusing bugs" and "do not generate keys on the fly"                                      | 2026-10-18, React 19 |
+
+## State and effects
+
+| Bullet                                        | Source                                                                                                                                                                                                                                                                | Read                 |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Derive during render                          | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): "When something can be calculated from the existing props or state, don't put it in state. Instead, calculate it during rendering."                                             | 2026-10-18, React 19 |
+| Reset with `key`                              | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): "To reset the state of an entire component tree, pass a different key to it."                                                                                                   | 2026-10-18, React 19 |
+| External store through `useSyncExternalStore` | [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore): a browser value "can change without React's knowledge, so you should read it with useSyncExternalStore", and the server snapshot "must be the same between the client and the server" | 2026-10-18, React 19 |
+| Fetching effect in a custom hook              | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): a race "needs a cleanup function to ignore stale responses", and moving fetching "into a custom Hook will make it easier to adopt an efficient data fetching strategy later"    | 2026-10-18, React 19 |
+
+## Memoization
+
+| Bullet                           | Source                                                                                                                                                                                                                                              | Read                         |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Leave it to the compiler         | [React Compiler introduction](https://react.dev/learn/react-compiler/introduction): "For new code, we recommend relying on the compiler for memoization and using useMemo/useCallback where needed to achieve precise control."                     | 2026-10-18, React Compiler 1 |
+| Without it, memoize only by need | [useMemo](https://react.dev/reference/react/useMemo): worth it for a noticeably slow calculation, "say, 1ms or more", a prop to a `memo` child, or a Hook dependency, and "There is no benefit to wrapping a calculation in useMemo in other cases" | 2026-10-18, React 19         |
+
+## Composition
+
+| Bullet                        | Source                                                                                                                                                                                                                                                | Read                 |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Props, children, then context | [Passing data deeply with context](https://react.dev/learn/passing-data-deeply-with-context): "Start by passing props", then "Extract components and pass JSX as children", and "If neither of these approaches works well for you, consider context" | 2026-10-18, React 19 |
+
+## Error and loading boundaries
+
+| Bullet                                       | Source                                                                                                                                                                                                             | Read                 |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Error boundaries where a message makes sense | [Component](https://react.dev/reference/react/Component): "consider where it makes sense to display an error message", around the conversation list and each message, and "You don't need to wrap every component" | 2026-10-18, React 19 |
+| What activates Suspense                      | [Suspense](https://react.dev/reference/react/Suspense): "Suspense does not detect when data is fetched inside an Effect or event handler"                                                                          | 2026-10-18, React 19 |
+| Boundaries follow the loading sequence       | [Suspense](https://react.dev/reference/react/Suspense): "Suspense boundaries should not be more granular than the loading sequence that you want the user to experience"                                           | 2026-10-18, React 19 |
+
+## Exports
+
+| Bullet        | Source                                                                                                   | Read       |
+| ------------- | -------------------------------------------------------------------------------------------------------- | ---------- |
+| Named exports | House choice: a default export renamed at import drifts from the component's name, so a search misses it | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "`useMemo` for derived state over `useEffect`" with the derive bullet. The effect page says "calculate it during rendering" and keeps `useMemo` for a slow calculation.
+- Cut "memoize components receiving non-primitive props" as contradicted. [memo](https://react.dev/reference/react/memo) is "completely useless if the props passed to your component are always different, such as if you pass an object".
+- Cut "memoize every handler passed to a child" as contradicted. [useCallback](https://react.dev/reference/react/useCallback) says "There is no benefit to wrapping a function in useCallback in other cases" than a `memo` child or a Hook dependency.
+- Cut "no passing props past two levels" as contradicted, since the context page says "it's not unusual to pass a dozen props down through a dozen components".
+
+### Cut without a source or a bug class
+
+- Cut "domain logic in `src/features/`, shared UI in `src/components/`" as a layout call, which the `codebase-layout` skill owns.
+- Cut "no feature components in the global components folder" as the same layout call.
+- Cut "environment variables only from the validated config module", which is no React practice and which no react.dev page takes a side on.
+- Cut "function declarations over arrow functions" as style with no bug class, and no react.dev page takes a side.
+- Cut "props interface directly above the component" as style with no bug class.
+- Cut "extract components when JSX exceeds one responsibility", which no reviewer can check against a line of code.
+- Cut "compare the previous value and set state during render", since [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) says "most components shouldn't need it either" and ranks it after a key reset.
+- Cut "use `<>` unless a key is needed" as a convention Claude already follows. [Rendering lists](https://react.dev/learn/rendering-lists) says the shorthand "won't let you pass a key".
+
+### Merged or reworded
+
+- Merged "no default exports" into the named-exports bullet, which states the same choice.
+- Narrowed "custom hooks for all fetching and complex effects" to data fetching, since [Reusing logic with custom hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) says "you can (but don't have to) extract custom Hooks".
+- Merged "no `setState` in an effect to sync derived state" into the derive bullet, the same ban. Only the `web` and `nextjs` oxlint configs error on `react/set-state-in-effect`.
+- Reworded "a sentinel from asynchronously hydrating hooks" to `useSyncExternalStore` with a matching server snapshot, the API the reference names for a value React does not own.
+- Reworded "error boundaries at route level", since the reference places a boundary by where a message makes sense rather than at a fixed level.
+- Merged "no single root error boundary as the only net" into the placement bullet.