@erclx/canon 5.43.0 → 5.44.0

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
 

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/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.

package/governance/ledger/framework/shadcn.md

@@ -0,0 +1,60 @@
+---
+title: shadcn/ui rule ledger
+description: Sources for governance/rules/framework/shadcn.md, one row per bullet
+---
+
+# shadcn/ui rule ledger
+
+The field is front-end engineering, and the authority is the shadcn/ui documentation and changelog at ui.shadcn.com. The rewrite reads the July 2026 changelog, which made Base UI the default primitive library.
+
+## Source files
+
+| Bullet                       | Source                                                                                                                                                                                                            | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Edit installed code in place | [Introduction](https://ui.shadcn.com/docs): "This is not a component library. It is how you build your component library", and "Modify any part of a component to fit your design and functionality requirements" | 2026-10-18 |
+| Diff before overwrite        | [CLI](https://ui.shadcn.com/docs/cli): `add --overwrite` will "overwrite existing files", and `--diff` will "show diff for a file"                                                                                | 2026-10-18 |
+| Import through the aliases   | [components.json](https://ui.shadcn.com/docs/components-json): "The CLI uses these values to place generated components in the correct location and rewrite imports"                                              | 2026-10-18 |
+
+## Component authoring
+
+| Bullet                    | Source                                                                                                                | Read                       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `ComponentProps` typing   | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "Replace React.forwardRef<...> with React.ComponentProps<...>" | 2026-10-18, React 19       |
+| `data-slot` on primitives | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "Every primitive now has a data-slot attribute for styling"    | 2026-10-18, Tailwind CSS 4 |
+
+## Tokens and styling
+
+| Bullet          | Source                                                                                                                                                                                      | Read       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Semantic tokens | [Theming](https://ui.shadcn.com/docs/theming): "We use semantic background and foreground pairs", mapped "into utilities like bg-background, text-foreground, border-border, and ring-ring" | 2026-10-18 |
+| `cn()` merging  | [Manual installation](https://ui.shadcn.com/docs/installation/manual): re-export `cn` "from lib/utils.ts so your own code has a single place to import helpers from"                        | 2026-10-18 |
+
+## Composition
+
+| Bullet                       | Source                                                                                                                                                                                          | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `render` or `asChild`        | [Base UI as the default](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default): "New projects now use Base UI by default", "Radix is not being deprecated", and "asChild is now render" | 2026-10-18 |
+| `buttonVariants()` for links | [Button](https://ui.shadcn.com/docs/components/button): "The Base UI Button component always applies role="button", which overrides the semantic link role on a elements"                       | 2026-10-18 |
+| `sonner` for toasts          | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "We're deprecating the toast component in favor of sonner"                                                                               | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "do not edit installed component files, treat them as vendored". The [introduction](https://ui.shadcn.com/docs) says "The top layer of your component code is open for modification".
+- Cut "extend behavior via wrapper components over modifying installed files" for the same reason.
+- Cut "do not override component internals with arbitrary classes, extend via `className` only". Editing the variants in the owned file is what the docs describe.
+- Reworded "use `asChild` with `<Slot>` for polymorphic rendering", since Base UI projects use `render` and the scoped and open searches agreed on that split.
+
+### Cut without a source or a bug class
+
+- Cut "compose shadcn primitives as documented", which no reviewer can check against a line of code.
+- Cut "do not destructure or restructure internal component trees" for the same reason.
+- Cut "do not wrap primitives in extra DOM elements" as a style call with no page read taking a side.
+
+### Merged or reworded
+
+- Reworded "check `components.json` for the install path" to the aliases bullet, which names what the file controls.
+- Reworded "use `cn()` for all className merging" to the override it guarantees.

package/governance/ledger/framework/tailwind.md

@@ -0,0 +1,55 @@
+---
+title: Tailwind CSS rule ledger
+description: Sources for governance/rules/framework/tailwind.md, one row per bullet
+---
+
+# Tailwind CSS rule ledger
+
+The field is front-end engineering, and the authority is the Tailwind CSS documentation at tailwindcss.com, read for Tailwind CSS 4.
+
+## Theme variables
+
+| Bullet                          | Source                                                                                                                                                                                                                  | Read                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `@theme` or `:root`             | [Theme variables](https://tailwindcss.com/docs/theme): "use :root for defining regular CSS variables that shouldn't have corresponding utility classes", and theme variables must be "defined top-level and not nested" | 2026-10-18, Tailwind CSS 4 |
+| Custom dark variant for a class | [Dark mode](https://tailwindcss.com/docs/dark-mode): "By default this uses the prefers-color-scheme CSS media feature", and a selector-driven theme overrides it with `@custom-variant dark`                            | 2026-10-18, Tailwind CSS 4 |
+
+## Layout and spacing
+
+| Bullet                     | Source                                                                                                                                                                            | Read                       |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `flex` or `grid` for flow  | House choice: a floated or absolutely positioned element leaves the document flow, so its siblings overlap or collapse once the viewport width changes                            | 2026-10-18                 |
+| `gap-*` over child margins | House choice: a margin on each child leaves a stray edge when the last item wraps or a conditional item is hidden, which `gap` never does                                         | 2026-10-18                 |
+| `size-*` for equal sides   | [Width](https://tailwindcss.com/docs/width): "Use utilities like size-px, size-4, and size-full to set both the width and height of an element at the same time"                  | 2026-10-18, Tailwind CSS 4 |
+| Mobile first               | [Responsive design](https://tailwindcss.com/docs/responsive-design): "unprefixed utilities take effect on all screen sizes", and "Don't think of sm: as meaning on small screens" | 2026-10-18, Tailwind CSS 4 |
+
+## Class application
+
+| Bullet                          | Source                                                                                                                                                                                                                                           | Read                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| Complete class names            | [Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files): Tailwind "has no way of understanding string concatenation or interpolation", so "map props to complete class names"                        | 2026-10-18, Tailwind CSS 4 |
+| No conflicting utilities        | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "you should just never add two conflicting classes to the same element"                                                                               | 2026-10-18, Tailwind CSS 4 |
+| `!` only as a last resort       | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "When you really need to force a specific utility class to take effect and have no other means of managing the specificity, you can add ! to the end" | 2026-10-18, Tailwind CSS 4 |
+| Arbitrary values for one-offs   | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "When you need to use a one-off value outside of your theme, use the special square bracket syntax"                                                   | 2026-10-18, Tailwind CSS 4 |
+| Inline style for dynamic values | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): inline styles are useful "when a value is coming from a dynamic source like a database or API", and for "setting CSS variables"                       | 2026-10-18, Tailwind CSS 4 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "do not use the `!` important modifier", since the [utility classes](https://tailwindcss.com/docs/styling-with-utility-classes) page documents the trailing `!` for the case nothing else resolves.
+
+### Cut without a source or a bug class
+
+- Cut "always pair light and dark utilities explicitly". No page read requires it, and a color token redefined for dark mode switches with no `dark:` pair at all.
+- Cut "define dark mode color overrides in `.dark { }` at root level over `@layer base`", which no Tailwind page read takes a side on.
+- Cut "use `cn()` from `@/lib/utils` for all conditional class application" as the import convention the shadcn rule already owns. The kept conflict bullet names `cn()` for the override case.
+
+### Merged or reworded
+
+- Merged "use `flex` and `grid` for all layouts" and "never use floats or absolute positioning for flow" into one bullet naming the bug class.
+- Reworded "use `size-*` over `w-* h-*`" to the matching pair it replaces.
+- Reworded "mobile-first, default styles apply to mobile" to the `sm:` misreading the responsive page warns about.
+- Added "write every class name in full", the footgun the source detection page names and the old rule missed.