basalt-ui 1.19.1 → 1.21.0

package/agent/rules/basalt-app.md

@@ -69,6 +69,68 @@ The one real caveat is a plugin that **emits files from its own `closeBundle`**:
 `vite-plugin-pwa`'s, those files are written too late to be precached (the `rollup-plugin-copy`
 class of bug). `vite-plugin-pwa` exposes `integration.closeBundleOrder` to sequence against it.
 
+## What `basalt-ui init` writes into `package.json`
+
+`init` is not only a file-scaffolder. It also patches two keys, and on an existing app it is a
+**lint-debt event, not a no-op** — the shipped preset switches on whole oxlint plugins the repo was
+never linted against, so previously-clean code lands with real findings on the first run. `init`
+prints the plugin list; run `oxlint .` and triage it before your next commit rather than
+blanket-disabling a plugin.
+
+- **`basalt.roots`** — inferred from the real layout (workspace packages depending on basalt or
+  Mantine, else every workspace `src/`, else `src`). Everything derives from it: `check-theme`'s
+  scan, the seeded CI `oxfmt` globs, the default scan exemption. Correct it if your sources live
+  elsewhere; without it a workspace repo scaffolds a guard that scans zero files.
+- **`scripts["lint:basalt"]`** — `oxlint . && basalt-ui check-theme`. Previously the docs told you
+  to wire this and nothing wrote it.
+- **`basalt.profile: 'tokens-only'`** — for a consumer on the `--vx-*` layer with no Mantine. It
+  must be DECLARED (or passed as `--tokens-only`); `check-theme` deliberately never infers it,
+  because inferring from a missing `@mantine/core` would silence 17 kinds on any repo that keeps
+  Mantine in a different workspace package. `doctor` does infer it, because its profile only changes
+  which ADVICE it prints and never what it enforces — and it names the key to write down.
+
+`init` keeps an existing `.oxlintrc.json` rather than clobbering it, and now names what keeping it
+costs (the whole basalt lint half stays off). `--merge-lint` splices the preset's `extends` in; it
+refuses on a commented config rather than deleting the comments.
+
+Run `basalt-ui doctor` afterwards to confirm the wiring took. A check that cannot RUN is reported as
+`SKIPPED` and exits non-zero on its own — "All checks passed" is only printable when every check ran.
+
+### The lefthook preset overrides YOU, not the other way round
+
+New in 1.20.1: `doctor`'s `lefthook-preset` check hard-fails when the repo-root lefthook config
+`extends` a path that does not resolve. That state is otherwise invisible — lefthook merges a
+missing target into **zero** commands and exits 0, so `lefthook dump` looks clean and the repo has
+no pre-commit gate with nothing anywhere saying so. It warns on a lefthook.yml wiring its own hooks,
+and is n/a with no lefthook at all. `sync` reports the same seam, since it is the command an upgrade
+actually runs and neither file is one basalt owns.
+
+**An `extends` target WINS on a colliding key.** Declare `pre-commit.commands.oxfmt.run` (or
+`glob:`) in your own file and the preset's value is what runs — yours is discarded silently. Only
+keys the preset does not define merge in. So `env:`, `exclude:`, `skip:` and a differently-named
+command of your own are yours; `run:` and `glob:` on a shipped command are not. The sanctioned seam
+is therefore `BASALT_BIN`: the guard job runs `${BASALT_BIN:-bunx --no-install basalt-ui}`, and the
+shell default is the whole reason the seam exists at all. `init` renders it with the resolved local
+bin. `--no-install` is deliberate — a bare `bunx basalt-ui` in a repo where basalt is not resolvable
+from the root silently downloads a different copy from npm and gates the commit with a version
+nobody pinned.
+
+## `index.html` and `public/` are scanned
+
+`check-theme` resolves `.html` / `.webmanifest` / `.json` as markup (colour kinds only), and each
+`basalt.roots` entry's PARENT contributes its `index.html` and its `public/` tree — exactly the Vite
+layout above. So a raw hex in a `theme-color` meta or a webmanifest's `background_color` is a
+finding now; those are the two colours nothing re-derives on a scheme change. Nothing else in the
+parent is walked, and `.json` is never blanket-scanned — name one in `basalt.include`.
+
+## `__APP_VERSION__`
+
+`basaltViteConfig` injects the `__APP_VERSION__` define, and since 1.20.0 ships the ambient
+declaration with it (`src/register.ts` → `dist/register.d.ts`, re-exported by the root barrel). An
+app that imports anything from `basalt-ui` has it in scope — delete your hand-written ambient block
+and its `oxlint-disable`. A subpath-only consumer does not get it, which is the same set as the
+consumers not on this Vite preset anyway.
+
 ## CSS layer order (Mantine)
 
 `basalt-ui/styles.css` must load AFTER every `@mantine/*/styles.layer.css` bundle — the layered
@@ -90,6 +152,28 @@ they track the palette automatically. It also injects the `apple-mobile-web-app-
 `viewport-fit=cover` (skipped when the consumer's own `index.html` already declares one), and
 site-wide OG/Twitter defaults from `options.seo`.
 
+**Set `colorScheme` to whatever the app passes as `defaultColorScheme`** — `'dark'` (the default),
+`'light'`, `'auto'` (declares `color-scheme: light dark` and picks the pre-boot background off
+`prefers-color-scheme`), or `false` (paint the background, declare no `color-scheme`).
+
+```ts
+plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })]
+```
+
+Before 1.20.1 the anti-FOUC rule emitted `html{color-scheme:dark}` **unlayered**, which outranks
+Mantine's own `@layer mantine` declaration regardless of specificity — a light-scheme consumer got
+dark scrollbars, dark `<select>` popups and dark date pickers permanently, with no opt-out. The rule
+is now scoped to `html:not([data-mantine-color-scheme])`, so it expires the instant MantineProvider
+resolves the real scheme. A mismatched `colorScheme` is therefore a flash of the wrong surface, not
+a stuck one.
+
+**The plugin hoists your `<meta charset>`.** Every injected tag defaults to `head-prepend`, which
+landed ~20 tags ahead of the consumer's own encoding declaration — measured at byte 1653 on a
+realistic shell, past the 1024-byte window the HTML spec gives it, with no consumer-side fix
+available. The plugin now re-emits the declaration as its own first head-prepend tag (46 bytes after
+the fix) and runs `order: 'pre'` so nothing else can land ahead of it. The legacy `http-equiv` form
+is detected and left verbatim.
+
 Icons are **bring-your-own** — basalt-ui takes no `sharp`/image-processing dependency. The plugin
 expects these filenames under `public/` (or `icons.dir` if customized):
 

package/agent/rules/basalt-charts.md

@@ -55,19 +55,33 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
 
 - **`basalt/hand-rolled-plot`** — rendering a chart-assembly primitive (`AxisLeftNumeric`,
   `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`) in a file that does not
-  compose `CartesianChart` fails the build. Escape: a `theme-allow` comment on the first such
-  site — that is how a genuinely non-single-plot shape (multi-pane, radial, matrix) declares
-  itself; `DualPanel` carries the repo's one such comment. The file that DEFINES `CartesianChart`
-  is exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
+  compose `CartesianChart`. **Since 1.20.0 every assembly node is reported and waived on its own**
+  — one comment no longer grants the whole file permanent immunity, which is how a 604-line chart
+  file went unpoliced. To waive ONE node, put `theme-allow hand-rolled-plot — <why>` on it (or on a
+  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix)
+  declares the whole file with `theme-allow-file hand-rolled-plot — two panes over one x scale`,
+  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.20.1
+  spelling** — at 1.20.0 a node-scoped annotation was silently promoted to a file declaration, so
+  per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
+  exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
   cannot fire inside X.
-- **`basalt/chart-legend-literal`** — passing a hand-written array literal to `ChartLegend`'s
-  `items` fails the build; the legend must be derived from the same `series` array the chart draws
-  (`deriveLegend`, or just let `ChartFrame`/`CartesianChart` do it), so it cannot go stale and keep
+- **`basalt/chart-legend-literal`** — a hand-written array literal passed to `ChartLegend`'s
+  `items`; **since 1.20.0 also a `.map()` over a non-`series` array**, because deriving from AN
+  array is not deriving from THE series. The legend must come from the same `series` the chart
+  draws (`deriveLegend`, or just let `ChartFrame`/`CartesianChart` do it), so it cannot go stale
   naming a series the plot no longer draws.
 
-Both ship at `warn` in the consumer preset (`configs/oxlint.json`) for one minor and `error`
-repo-local, per the "Shipping a stricter guard — the grace minor" doctrine in
-`packages/basalt-ui/CLAUDE.md`. They promote to `error` in the next minor.
+Both ship `warn` in the consumer preset (`configs/oxlint.json`) and `error` repo-local, per the
+"Shipping a stricter guard — the grace minor" doctrine in `packages/basalt-ui/CLAUDE.md`. 1.20.0
+WIDENS both, so both restart their grace rather than promoting — the live ledger with the promotion
+note per rule is `PLUGIN_RULE_GRACE`, exported beside the plugin in `configs/oxlint-plugin.js`, and
+a test asserts it against the shipped preset in both directions.
+
+**A documented limit:** `hand-rolled-plot` keys on those visx primitives, so a chart drawn with DOM
+nodes (divs sized in percent, an SVG assembled by hand) is structurally invisible to it. That is a
+deliberate trade — every alternative detector tried either flagged basalt's own `Donut`/`Heatmap` or
+an icon in a card header, and a noisy shipped rule gets switched off. Compose `CartesianChart`
+because it is the contract, not because lint will catch you.
 
 ## Maps are not charts
 
@@ -81,12 +95,13 @@ ships no map kind.
 - **Want `@visx/geo` anyway?** Install it yourself — basalt doesn't pin it — and keep it under a
   `charts/` segment like every other visx import, same as any bespoke chart.
 - **Style map chrome with `--vx-*` tokens** (`VX.*`/`alpha()`) so it matches the rest of the app.
-- **The guard trap:** `check-theme`'s `inline-spacing` kind is a per-line regex over raw source, not
-  an AST pass — it flags any `padding:`/`gap:`/`margin:` followed by a number in _any_ object
-  literal, in any file. A map's pixel geometry (`fitBounds({ padding: 48 })`, marker offsets) trips
-  it even though it isn't spacing, and hoisting the value to a module-scope const doesn't help — the
-  regex sees the line, not the binding. Use a `theme-allow` line comment; that's the sanctioned
-  answer, not a bug to file.
+- **The guard trap, narrowed at 1.20.1:** `check-theme`'s `inline-spacing` kind is a per-line regex
+  over raw source, not an AST pass. A **unitless** number now only reports inside a style-object
+  context (a `style=`/`sx=`/`css=` attribute, or a const whose name or type says styles), so a map's
+  pixel geometry — `fitBounds({ padding: 48 })`, marker offsets — no longer trips it: an options bag
+  is not CSS. A value carrying a unit is CSS wherever it was written and still reports. Where it
+  does fire on genuine map chrome, scope a `theme-allow inline-spacing — map geometry` comment to
+  it; that's the sanctioned answer, not a bug to file.
 
 ## Every chart has
 
@@ -155,7 +170,7 @@ ships no map kind.
    in the geometry; and because the domain value must be unique, two events at the same instant
    collapse onto one position and one stops being drawn. `getX` returning a date string reads like a
    time axis and is not one. Tracked as issue #52; a chart whose x is a measured quantity currently
-   needs a `basalt/hand-rolled-plot` exemption.
+   needs a `basalt/hand-rolled-plot` file declaration.
 
 6. **The cursor is shared by default.** No provider needed — `useChartCursor` reads a module-level
    external store (`useSyncExternalStore`), so every `CartesianChart`/`ChartFrame`-composed chart on

package/agent/rules/basalt-content.md

@@ -208,6 +208,10 @@ axes AND together — matching the existing multi-facet `filterFn` semantics in
 
 **Filter state is URL state.** Single-select axes (category) use `createSearchParamStore`;
 multi-select axes (tags) use `createMultiSearchParamStore` — both from `basalt-ui/router-tanstack`.
+That holds for the enum-shaped axes an article filter has. **It is not a general URL-state mandate**:
+a route whose `validateSearch` is a real Zod object is hand-written, and `createSearchSchemaStore`
+is planned, not shipped — see `basalt-router.md` → "validateSearch".
+
 Two stores compose on one route by spreading both `validateSearch` results:
 
 ```ts

package/agent/rules/basalt-mantine.md

@@ -149,14 +149,26 @@ section divider, not card depth) are both fine.
   consumer code must compose Mantine layout/surface primitives — `Box`, `Flex`, `Grid`,
   `SimpleGrid`, `Stack`, `Group`, `Paper`, `Card` — instead of raw `<div>`/`<span>` with inline
   `style`. Raw HTML with inline layout/surface styling defeats the token system.
-- **Mechanical enforcement.** `basalt-ui check-theme` adds six surface guard kinds (each a config knob,
-  default ON; `theme-allow` line-comment escape): `off-system-surface-var` (raw ramp-step vars),
-  `card-with-border` (`withBorder` on a `Card`/`Paper`), `mantine-shade-index` (a shade-pinned color —
-  see below), `raw-html-layout` (raw `<div>`/`<span>` with inline layout/surface styling),
-  `inline-spacing` (inline spacing literals), `inline-display` (inline `display` literals). The
-  Mantine-free `src/charts/**` is the only place raw `<div>` is allowed — and it must still use `VX.*`
-  tokens. `oxlint` adds `basalt/card-inset`, which catches the other half of the same card drift: an
-  explicit `p`/`padding`/`radius` on a `Card`/`Paper` instead of the xs/sm inset and the theme radius.
+  - **The second fix is a CSS Module, and it is the right one in list code.** What
+    `raw-html-layout` actually objects to is the inline `style` literal, not the `<div>`. Moving the
+    rule into a `.module.css` class that reads `var(--vx-*)` satisfies the guard, keeps the values
+    in the token system, and costs zero runtime — where a Mantine primitive costs one component
+    instance per row. In a row renderer that paints hundreds of items, or in a downstream library
+    that must not force `@mantine/core` on its consumers, take the CSS Module. `check-theme` scans
+    `.css` and `.module.css`, so the tokens stay policed there. The guard's fix text names only the
+    Mantine route; both are sanctioned.
+- **Mechanical enforcement.** `basalt-ui check-theme` adds eight surface guard kinds (each a config
+  knob, default ON; scoped `theme-allow <rule-id> — <reason>` escape): `off-system-surface-var` (raw
+  ramp-step vars), `card-with-border` (`withBorder` on a `Card`/`Paper`), `mantine-shade-index` (a
+  shade-pinned color — see below), `raw-html-layout` (raw `<div>`/`<span>` with inline layout/surface
+  styling), `inline-spacing` (inline spacing literals), `inline-display` (inline `display` literals),
+  and since 1.20.0 `css-raw-surface` (the same surface kinds in their kebab CSS dialect, so
+  `border-radius: 4px` in a CSS module is no longer invisible beside a flagged `borderRadius: 2`) and
+  `hidden-inline-style` (`raw-html-layout`'s formatting-independent half — a multi-line opening tag,
+  or a style object hoisted to a const). The Mantine-free `src/charts/**` is the only place raw
+  `<div>` is allowed — and it must still use `VX.*` tokens. `oxlint` adds `basalt/card-inset`, which
+  catches the other half of the same card drift: an explicit `p`/`padding`/`radius` on a
+  `Card`/`Paper` instead of the xs/sm inset and the theme radius.
 
 **Never pin a shade index on a color.** `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)` —
 each names one fixed swatch that is identical in light and dark, so a shade legible on the dark page
@@ -278,8 +290,11 @@ shadow-surfaces.test.ts` mechanically enumerates every site that applies either
 
 ## Composing the shell from sub-components
 
-`BasaltShell` is the canonical single-mount. When a fully custom layout is needed, the shell
-sub-components are available individually from `basalt-ui`:
+`BasaltShell` is the canonical single-mount, and since 1.20.0 `basalt/hand-rolled-shell` (`warn`)
+says so mechanically: `AppShell.*` parts or a `Burger` in a file that does not render `BasaltShell`
+is the layer the 1.19 nav contract replaces. It is file-scoped and reported once — which shell a
+file uses is one decision. When a fully custom layout is genuinely needed, the shell sub-components
+are available individually from `basalt-ui`:
 
 - `AppSidebar` — desktop sidebar (sections, collapse, brand, settings/account extras)
 - `MobileNav` — the bottom tab bar (takes a `MobileNavModel` from `projectMobileNav`)

package/agent/rules/basalt-router.md

@@ -65,12 +65,59 @@ function ResourcePage() {
 
 ## validateSearch
 
+**Scope of the `createSearchParamStore` mandate — read this before reaching for the store.**
+`createSearchParamStore` covers ONE param whose values are a string enum
+(`{ key, param, values, fallback }`); `createMultiSearchParamStore` is the multi-select of the same
+shape. Where that fits — a range picker, a tab, a single filter — it is **mandatory**: use it, don't
+hand-roll persistence.
+
+Where it doesn't fit, it doesn't apply. A route whose `validateSearch` is a real Zod object (10+
+keys, nested shapes, cross-field defaults) cannot be expressed through the store at all — three
+consumers hit that wall. **Hand-write `validateSearch` there**, per the rules below. There is no
+schema-backed store: `createSearchSchemaStore` is planned and **not shipped** — do not write code
+against it.
+
 - Always parse with the schema-function form: `(raw) => SearchSchema.parse(raw)`.
 - Default values live in the schema (`.default()`), not in the component.
 - Access via `const search = Route.useSearch()`.
 - Update via `navigate({ search: { window: 'all', from: undefined, to: undefined } })` — prefer plain
   objects over reducers to avoid `| undefined` assignability errors when the schema has defaults.
 
+### Wire the reader, or the store does nothing (1.20.1)
+
+`validateSearch` is only half the store. It restores the value when you arrive with **no** param —
+it cannot do anything about a nav link that declares the param itself, and a link written
+`search: { window: '30d' }` at module scope pins the fallback on every click. That is not
+hypothetical: the reference consumer adopted the store in three features, hand-rolled the
+persistence in all three, and its reader had **zero** call sites. "Remember my window" had never
+once worked, with every individual piece looking correct.
+
+`store.linkSearch` is the fix, and it is on the object the factory already returns:
+
+```ts
+const dashboardRange = createSearchParamStore({
+  key: 'dashboard-range',
+  param: 'range',
+  values: ['1d', '7d', '30d'] as const,
+  fallback: '30d',
+})
+// → { validateSearch, useStore, readStored, linkSearch }
+
+link: linkOptions({ to: '/dashboard', search: dashboardRange.linkSearch })
+```
+
+**Pass it by reference, never call it.** It is the click-time thunk
+(`() => ({ [param]: readStored() ?? fallback })`); `<Link>` re-evaluates it on every click, so
+arriving from outside the sub-tree restores the last selection. A value computed once at module
+scope goes stale immediately. Hand-rolling the thunk over `readStored()` still works and is what
+you need when the link carries other params too.
+
+In dev, `validateSearch` warns once per store when the URL pins the fallback, a different value is
+persisted, and neither public reader has ever been called — the one combination that has exactly
+this cause. Silent in production, silent on a deliberate deep link.
+`createMultiSearchParamStore` gets `linkSearch` but no warning: an empty array in the URL is
+indistinguishable from an absent param, so a literal link there still restores correctly.
+
 ## loaderDeps
 
 - Define `loaderDeps` whenever the loader depends on search params. Without it, search-param changes do
@@ -104,10 +151,16 @@ Install `@tanstack/react-router` as a peer, then import from `basalt-ui/router-t
 
 **Prerequisites:**
 
-- `@tanstack/router-plugin/vite` must be configured in your Vite config and `tsr generate` must
-  have run at least once — the `StaticDataRouteOption` augmentation only takes effect once the route
-  tree (`src/routeTree.gen.ts`) has been generated. In CI and after adding routes, run
-  `tsr generate` (or `bun run typecheck`, which triggers it) before relying on breadcrumb or nav data.
+- **The only hard prerequisite is the `Register` module augmentation** (see "The prerequisite that
+  makes all of this real" below). `defineNav` / `navGroup` / `navTarget` / `flattenNav` / `useNav` /
+  `createSearchParamStore` all work against a hand-written `createRouter({ routeTree })` with
+  code-defined routes, no Vite plugin and no generated tree — verified end-to-end in a consumer,
+  including that a bad `to` still prints the real route-path union.
+- **`@tanstack/router-plugin/vite` + `tsr generate` are needed only for `staticData`** — that is,
+  for `useRouterBreadcrumbs` and any nav metadata read off the route tree. The
+  `StaticDataRouteOption` augmentation takes effect once `src/routeTree.gen.ts` exists. In CI and
+  after adding routes, run `tsr generate` (or `bun run typecheck`, which triggers it) before relying
+  on breadcrumb data.
 - The loader's `context.queryClient` requires `createRootRouteWithContext<{ queryClient: QueryClient }>()`.
   Run `basalt-ui init` to scaffold a `query-client.ts` + `__root.tsx` seed that wires the TanStack
   Router + Query context correctly — the generated `__root.tsx` uses
@@ -157,6 +210,7 @@ closing a cycle.
 ```tsx
 import { linkOptions } from '@tanstack/react-router'
 import { defineNav, navGroup } from 'basalt-ui/router-tanstack'
+import { garminWindow } from './search-params' // a createSearchParamStore
 
 const ICON = 18
 
@@ -169,7 +223,9 @@ export const NAV = defineNav({
         short: 'Garmin', // bar/menu label — keep it ≤ 10 chars
         mobile: 'tab', // give this destination its own slot on the mobile bar
         icon: <IconHeartbeat size={ICON} />,
-        link: linkOptions({ to: '/garmin-health', search: { window: '30d' } }),
+        // NOT `search: { window: '30d' }` — a module-scope literal pins the fallback on
+        // every click and silently overrides the store. Pass the reader by reference.
+        link: linkOptions({ to: '/garmin-health', search: garminWindow.linkSearch }),
       },
       {
         id: 'reading',
@@ -197,9 +253,11 @@ Rules that are not stylistic:
   `label`, `short`, `icon`, `mobile`, `disabled` and `exact` ride outside it. A flat shape
   (`{ id, label, to }`) validates `to` by ASSIGNABILITY, which does no excess-property checking, so
   a typo'd metadata key would compile silently. A top-level `to:` is a compile error by design.
-- **`search` may be a thunk** — `search: () => ({ date: format(new Date(), 'yyyy-MM-dd') })`
-  compiles without `as const` and re-evaluates at click time, so "today" never goes stale in a
-  long-lived tab.
+- **`search` may be a thunk, and for a store-backed param it MUST be** —
+  `search: () => ({ date: format(new Date(), 'yyyy-MM-dd') })` compiles without `as const` and
+  re-evaluates at click time, so "today" never goes stale in a long-lived tab. A param backed by
+  `createSearchParamStore` takes the store's own `linkSearch` (see "validateSearch" above); a
+  literal there is the one shape that defeats the store.
 - **Nesting is `children`**, and nested destinations are indexed by id just like top-level ones.
 - **`NavItemMeta`**'s `mobile` field places the destination on the bar: `'tab'` (own slot),
   `'more'` (the default — reachable through the More overlay) or `'hidden'`. A group claims a slot
@@ -231,7 +289,7 @@ unreadable in a 56px tab.
 `router.navigate()` or `redirect()` instead of restating the route and its default search:
 
 ```ts
-throw redirect(navTarget(NAV, 'garmin')) // exactly { to: '/garmin-health', search: { window: '30d' } }
+throw redirect(navTarget(NAV, 'garmin')) // exactly { to: '/garmin-health', search: garminWindow.linkSearch }
 ```
 
 **`flattenNav`** walks the definition depth-first (parent, then children), tagging each destination
@@ -255,12 +313,18 @@ With that missing, every `to` widens to `string`, a nonexistent route path compi
 required `search` compiles, and the API looks like it is working while catching nothing. This is
 the single highest-value thing to verify when adopting the config: change one `to` to a garbage
 path and confirm you get a compile error listing the real route paths. If you don't, the
-augmentation is missing or `tsr generate` has not run.
-
-Second thing to know before you migrate: TypeScript cannot catch a destination that FORGETS a
-default `search` when the route validates with `validateSearch: (raw: Record<string, unknown>) => T`
-— that gives TanStack an input type where no key is required. Diff an old hand-written target table
-against the new definition by hand, key by key.
+augmentation is missing (or, on a file-route setup, `tsr generate` has not run).
+
+Second thing to know before you migrate: whether a missing `search` is caught depends on the
+schema's OUTPUT type, not on the `validateSearch` signature. If every key of `T` is required —
+which is what a Zod object with defaults produces, since defaults apply on parse and the output has
+no optionals — TanStack raises `MakeRequiredSearchParams` and the compiler catches it. Two routes in
+one consumer had been shipping nav links with no search params behind a `to={target.to as never}`
+cast; removing the callback surfaced both immediately.
+
+**The caveat holds only when `T` has no required keys** (every key optional, or the validator
+returns a partial). There, a forgotten `search` compiles — diff the old target table against the new
+definition by hand, key by key. Everywhere else, trust the error.
 
 Error messages here are the router's own and they are large: one wrong `to` prints the whole
 route-path union plus a `RouterCore<…>` blob, because TanStack's `Constrain` falls back to the

package/agent/rules/basalt-state.md

@@ -24,9 +24,10 @@ Pick the right home for each kind of state — don't dump everything into one st
   `--vx-*` tokens via CSS; reading it any other way breaks scheme reactivity and trips `basalt-ui check-theme`.
 - **UI preferences that must survive navigation but aren't URL-worthy** (sidebar collapsed, panel
   layout, draft filters) → `createPersistedState` from `basalt-ui/state` — the framework's own
-  versioned localStorage primitive (see below). `BasaltShell` already persists its own collapse state
-  internally; use `createPersistedState` for app-level preferences. Reach for a third-party store
-  only when complex cross-component state genuinely warrants it (see escape hatch below).
+  versioned localStorage primitive (see below). `BasaltShell` persists its own collapse state
+  through that same primitive since 1.20.1; use `createPersistedState` for app-level preferences.
+  Reach for a third-party store only when complex cross-component state genuinely warrants it (see
+  escape hatch below).
 
 ## useOnlineStatus — SSR-safe online/offline hook
 
@@ -66,6 +67,23 @@ const [layout, setLayout] = usePanelLayout()
 Keys are namespaced `basalt:<key>` automatically and never collide with the theme-scheme guard.
 Pass a `schema` (Standard Schema) to validate persisted values and fall back to `initial` on mismatch.
 
+### Mirroring `BasaltShell`'s collapse (changed key at 1.20.1)
+
+`BasaltShell` used `@mantine/hooks`' `useLocalStorage` while `createPersistedState` was the
+documented house API — so a consumer reading the raw key was complying with the shipped component,
+not drifting from it. It now stores through `createPersistedState`, which makes it SSR-safe and
+moves the key:
+
+```ts
+import { readPersistedValue } from 'basalt-ui/state'
+
+// 1.20.1: localStorage['basalt:<storageKey>'] === '{"v":1,"value":true}'
+const collapsed = readPersistedValue('basalt-sidebar-collapsed', 1)
+```
+
+A one-time migration adopts the raw pre-1.20.1 value, so an upgrade does not silently re-expand
+every sidebar. It is a bridge, not a format — do not write against it.
+
 ## Zustand escape hatch (complex cross-component stores)
 
 Reach for Zustand only when `createPersistedState` is insufficient — typically when multiple

package/agent/rules/basalt-tokens.md

@@ -24,12 +24,133 @@ status pops — never floods. (Blueprint/Basalt zinc-charcoal are the historical
 ancestors; `docs/DESIGN-SPEC.md` in the basalt-ui repo supersedes both — see its "Doctrine
 inversions" section.) This
 rule is the operational checklist; it is enforced mechanically by **`basalt-ui check-theme`**
-(wire it into `lint`: `oxlint . && basalt-ui check-theme`). A violation fails the build. Escape hatch: a
-`theme-allow` line comment (diff-visible, deliberate).
+(wire it into `lint`: `oxlint . && basalt-ui check-theme`; `init` seeds that as `lint:basalt`). A
+violation fails the build. Escape hatch: a scoped `theme-allow <rule-id> — <reason>` comment
+(diff-visible, deliberate) — see the contract below.
 
 `check-theme` reads its config from your `package.json` `"basalt"` key
-(`{ roots?, exempt?, spacingSteps?, forbiddenAccents? }`); set `roots` to your source dirs and `exempt`
-to the files that legitimately define palette values.
+(`{ roots?, exempt?, include?, profile?, severity?, spacingSteps?, forbiddenAccents? }`); set `roots`
+to your source dirs and `exempt` to the files that legitimately define palette values.
+
+**`roots` is not optional in practice.** Omitted it falls back to `src` relative to the cwd — fine
+for a single-app repo, zero files for anything under `apps/*/src`, and `check-theme` then exits 1
+with `0 files scanned`. Since 1.20.0 `init` writes a real `roots` from the detected layout and
+`doctor`'s `guard-scan` check fails when the configured roots resolve to nothing; before that a repo
+could look fully wired while the gate scanned nothing.
+
+The scan reaches slightly beyond `roots`: each root's PARENT contributes its `index.html` and its
+`public/` tree (the Vite layout basalt's own preset assumes), because that is where a `theme-color`
+meta and a webmanifest's `background_color` actually live. `.json` is never blanket-scanned — name a
+design-surface JSON in `basalt.include`, the only route to one.
+
+## `theme-allow` — the 1.20.1 contract
+
+The full grammar, in both engines:
+
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules  (unscoped without a why)
+theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
+"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
+```
+
+An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin rule
+(`hand-rolled-plot`, `raw-scroll-container`, …), with or without the `basalt/` prefix.
+
+```tsx
+// theme-allow raw-surface — third-party widget needs a literal corner
+<Widget style={{ borderRadius: 3 }} />
+```
+
+- **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
+  or nothing but whitespace. Before 1.20.1 any comment that merely _mentioned_ the token parsed as
+  the bare blanket form and switched every rule off on the line below: linewatch documented its own
+  waivers in a docblock and thereby disarmed the file. Prose about the escape hatch no longer waives
+  anything; everything a consumer actually writes still qualifies.
+- **File scope is spelled, not inferred.** `theme-allow-file <id>… — <why>`, anywhere in the file.
+  Plain `theme-allow` is the node/line waiver in both engines. At 1.20.0 the two halves of the
+  contract intersected at exactly one legal shape and that shape was whole-file — naming a rule and
+  giving a reason was read as a file declaration, which is why per-node scoping did not actually
+  ship. **This is the consumer break in 1.20.1**: move each existing file declaration one word.
+- **A bare `theme-allow` still waives everything on its placement** but reports
+  `theme-allow-unscoped` (`warn` for one minor, then `error`). A bare `theme-allow-file` waives
+  nothing at all — whole-file blanket immunity off one unnamed comment is the thing this contract
+  exists to price.
+- **Spell the id right — a typo waives nothing.** A word in the id slot that names no rule is
+  recorded as unknown and suppresses nothing; the annotation covers exactly the ids it got right.
+  Because the id slot is read strictly, a prose reason has to be introduced by a separator:
+  `theme-allow: <why>` or `theme-allow <id> — <why>`, never `theme-allow <why>`.
+- **JSON and `.webmanifest` get a member key**, since they have been scanned since 1.20.0 and cannot
+  hold a comment — their findings were unwaivable and the printed remedy prescribed something
+  impossible. `"basalt:theme-allow-file": "raw-hex — a PWA manifest theme_color must be a literal"`
+  carries the same grammar. For a manifest the first remedy is `basaltAppPlugin`, not a waiver: a
+  hand-copied hex drifts from the palette.
+- **Three placements work and both engines agree on all three**: the reported line, a comment-ONLY
+  line directly above it (the only form JSX can express — the reported line is usually a multi-line
+  opening tag or a `{expr}` child), and in CSS a trailing annotation reaching back over the
+  declaration it terminates. The third is what survives the shipped `oxfmt` reflowing a long
+  `background-color` so the hex lands ABOVE the comment.
+- **A comment-only annotation reaches the first CODE line below it**, walking through the rest of
+  its own comment block. A wrapped reason, or a docblock's `*/`, used to absorb the waiver so the
+  natural shape silently waived nothing — argo hit that three times in one upgrade. A blank line
+  still ends the block; that is how you say "this comment is not about the next statement".
+- **`basalt/hand-rolled-plot` grants whole-file immunity only through `theme-allow-file`.** Every
+  assembly node is otherwise waived on its own.
+
+### Audit them: `basalt-ui check-theme --audit-allows`
+
+Reports instead of scanning. For every annotation and every `basalt.exemptRules` entry it re-runs
+the guard with that one occurrence neutralized, so the verdict comes from the scan rather than from
+parsing the waiver's text:
+
+```text
+src/shell/x.tsx:42    suppresses raw-surface@43
+src/theme/y.ts:18     SUPPRESSES NOTHING — dead, delete it
+src/charts/z.tsx:7    scoped to hand-rolled-plot — not a check-theme kind, so this audit cannot judge it
+raw-hex: "site.webmanifest"  suppresses findings in public/site.webmanifest — <the recorded reason>
+```
+
+It closes with a `live / dead / outside reach / unaccountable` tally and **exits 1 on a dead
+waiver**, so it wires into CI. A waiver that stopped covering anything is not harmless: it silently
+covers the next real finding on that line. Basalt's own source had one; it is deleted.
+
+### New in 1.20.0 — five guard kinds, all `warn` for one minor
+
+| Kind                      | Fires on                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `theme-allow-unscoped`    | a `theme-allow` with no rule id, no reason, or an id that names no rule                                             |
+| `surface-shadow-override` | a `boxShadow` built FROM tokens that REPLACES `--vx-shadow-card` instead of composing with it                       |
+| `css-raw-surface`         | the kebab dialect of the surface kinds in CSS (`border-radius: 6px`); sub-scale corners and circle/pill values pass |
+| `inline-font-size`        | `style={{ fontSize: 11 }}` — the `check-theme` half of `basalt/no-raw-font-size`, for a CI that runs only the guard |
+| `hidden-inline-style`     | a multi-line opening tag, or a style object hoisted to a const — `raw-html-layout`'s formatting-independent half    |
+
+Two new oxlint rules ship at `warn` alongside them: **`basalt/shadow-basalt-export`** (below) and
+**`basalt/hand-rolled-shell`** (`AppShell` parts or `Burger` in a file that does not render
+`BasaltShell`). **`basalt/raw-size-literal` is now `error`** — CSS-length strings on
+`size`/`fz`/`fontSize`. Every kind keeps its own boolean, `basalt.severity` and `exemptRules`.
+
+## The guard sees palette, not vocabulary
+
+Round 4 swept seven consumer repos: every gate green, and ~15 independently re-rolled copies of
+components basalt already ships (`StatCard` in 4 of 4 apps, `EmptyState`, a 266-line hand-rolled
+`AppShell`). A fork written by a token-fluent author uses exactly the right tokens, so no palette
+guard can ever see it. **`basalt/shadow-basalt-export` is a cheap detector, not a safety net** — the
+rule says so in its own message: it is a **tripwire, not coverage**, and silence is not evidence that
+nothing is forked.
+
+- **Exact name match only** — the one limit that is structural. Round 5 confirmed the miss rate:
+  linewatch's forks are named `Cell` and `Box`, rb's is `Stat`. Rename the fork and the rule goes
+  quiet, which is what a fork's author naturally does.
+- **Scope: everything importable.** Since 1.20.1 it reads all nine published barrels, not just
+  `dist/index.d.ts` — so the `basalt-ui/charts` layer, which is where forks actually live, is finally
+  covered. Names a barrel merely re-exports from a third party are skipped: `./charts` passes
+  `Bar` / `Line` / `Pie` straight through from `@visx/shape`, and a local `Bar` is not a fork of
+  anything basalt wrote.
+
+So the renamed majority goes unreported. **Detection does not substitute for expressiveness**: a
+composite that cannot express a common case gets routed around by compliant-looking code, and a
+name-collision rule only catches the authors who did not bother to rename. The habit it stands in
+for is the actual control: check whether basalt already ships the thing before building it.
 
 ## Filled surfaces — the fill band
 
@@ -158,5 +279,10 @@ export const paletteGroups = { [`${GROUP}-`]: SERIES } // -> { 'activity-': SERI
 ## When the guard fires
 
 Fix the source, don't silence it — reach for the right token first. Only add `theme-allow` for a
-genuine, documented exception (e.g. a third-party widget needing a literal). The palette-definition
-files are listed in your `exempt` set so they don't self-trip.
+genuine, documented exception (a third-party widget needing a literal), scoped to the rule id, with
+a reason: a bare `// theme-allow` passes the check, tells the next reader nothing, and now reports
+`theme-allow-unscoped` besides. The palette-definition files are listed in your `exempt` set so they
+don't self-trip. A stylesheet emitted by `basalt-ui tokens:css` needs no entry — in a `.css` file
+carrying that exact two-line `@generated basalt-ui` header, the guard skips the LINES that are
+basalt custom properties, selectors, `}` or self-closing comments. Pasting the marker anywhere else
+suppresses nothing, and an ordinary declaration added to such a file is still reported.