basalt-ui 1.20.0 → 1.21.0

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
@@ -163,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
 
@@ -175,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',
@@ -203,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
@@ -237,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

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

@@ -43,33 +43,76 @@ The scan reaches slightly beyond `roots`: each root's PARENT contributes its `in
 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.0 contract
+## `theme-allow` — the 1.20.1 contract
 
-Scope it. `theme-allow <rule-id> — <reason>` waives that ONE kind; the 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.
+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 }} />
 ```
 
-- **A bare `theme-allow` still waives everything**, so no upgrade takes a build down over comment
-  placement — but it now reports `theme-allow-unscoped` (`warn` for one minor, then `error`).
-  Rescope the ones you have; that is the whole migration.
+- **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.
-  Only a genuinely bare `theme-allow` is the blanket form. 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>`.
+  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.
-- **`basalt/hand-rolled-plot` no longer grants whole-file immunity** off whichever comment happened
-  to sit on the first assembly node. Every node is waived on its own; a file-scoped exception needs
-  a written declaration that both names the rule and gives a reason, anywhere in the file.
+- **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
 
@@ -91,9 +134,23 @@ Two new oxlint rules ship at `warn` alongside them: **`basalt/shadow-basalt-expo
 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 the cheap detector** — it warns when a
-local component's name collides with a live basalt export, read from the real shipped barrel. The
-habit it stands in for: check whether basalt already ships the thing before building it.
+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
 

package/agent/skills/basalt-app/SKILL.md

@@ -120,7 +120,10 @@ Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` s
 guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
 already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
 passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
-`basalt/shadow-basalt-export` warns on the name collision; nothing catches the rest.
+`basalt/shadow-basalt-export` reads all nine published barrels since 1.20.1 (the charts layer
+included), but it warns only on an **exact** name collision — round 5 found the renamed forks
+(`Cell`, `Box`, `Stat`) sail straight past it. It is a tripwire, not coverage; nothing catches the
+rest. Ask before you build; do not wait to be told.
 
 The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on
 a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is

package/agent/skills/basalt-charts/SKILL.md

@@ -210,9 +210,11 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   `AxisLeftNumeric` / `AxisRightNumeric` / `AxisBottomDate` (escape via `theme-allow`).
 - **No hand-rolled plot assembly.** `basalt/hand-rolled-plot` fails the build on a chart-assembly
   primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
-  rendered in a file that doesn't compose `CartesianChart`. Escape: a `theme-allow` comment on the
-  first such site — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`, `Donut`) declares
-  itself. The file that defines `CartesianChart` is exempt definitionally.
+  rendered in a file that doesn't compose `CartesianChart`, per NODE. Escape:
+  `theme-allow hand-rolled-plot — <why>` on the one node, or `theme-allow-file hand-rolled-plot —
+<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`,
+  `Donut`) declares itself. `-file` is the 1.20.1 spelling and it is required. The file that defines
+  `CartesianChart` is exempt definitionally.
 - **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
   array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws
   (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no

package/agent/templates/CLAUDE-block.md.tpl

@@ -2,8 +2,9 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-Scaffolded by `bunx basalt-ui init` and refreshed by `bunx basalt-ui sync` (run it after a basalt-ui
-upgrade; `basalt-ui sync --check` gates drift in CI). This block is framework-owned — edit `DESIGN.md`
+Scaffolded by `bunx basalt-ui init` (the one command that legitimately predates the install) and
+refreshed by the locally installed `basalt-ui sync` after every upgrade; `basalt-ui sync --check`
+gates drift in CI. This block is framework-owned — edit `DESIGN.md`
 or the `basalt-*` rules instead; manual changes here are overwritten on the next sync.
 
 **Stack:** React 19 + Mantine v9, themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`).
@@ -18,9 +19,14 @@ code must follow) — never import `@visx/*` outside a `charts/` directory (oxli
 Toolchain is oxlint + oxfmt (no ESLint/Biome/Prettier) and `basalt-ui check-theme` guards the
 palette. Runtime is Bun.
 
-**Before guessing an import, check the installed package's machine docs**:
-`node_modules/basalt-ui/llms.txt` (per-subpath import map), `node_modules/basalt-ui/AGENTS.md`, or
-run `bunx basalt-ui info --json`.
+**Before guessing an import, read the installed package's machine docs — `llms.txt` (per-subpath
+import map) and `AGENTS.md`, at the install directory.** That is `./node_modules/basalt-ui` only on
+a single-package app. In a workspace, basalt resolves under the package that depends on it
+(`packages/<name>/node_modules/basalt-ui`), and the repo root may have no copy at all. Run
+`basalt-ui doctor` — its `basalt-resolves` line prints the resolved install dir and version; read
+the two files there. Invoke the CLI through the **locally installed** bin (the `lint:basalt` script
+seeded by `init` shows the path); `bunx basalt-ui` fetches a second copy from npm and can answer
+for a different version than the one you are building against.
 
 **DESIGN.md is law.** `./DESIGN.md` (imported below) records this app's palette identity and series
 dictionary. Precedence: **DESIGN.md > `basalt-*` rules > skills.** When building or restyling any

package/configs/lefthook.yml

@@ -2,19 +2,32 @@
 # `basalt-ui init` seeds a lefthook.yml that references this file:
 #   extends:
 #     - node_modules/basalt-ui/configs/lefthook.yml
-# lefthook merges these commands with the consumer's own, so this preset auto-updates
-# with the package. Runs oxlint + oxfmt on staged files and the theme guard on the whole
-# tree, pre-commit. Assumes oxlint/oxfmt are installed.
+# so this preset auto-updates with the package. Runs oxlint + oxfmt on staged files and the theme
+# guard on the whole tree, pre-commit. Assumes oxlint/oxfmt are installed.
+#
+# ── HOW OVERRIDING ACTUALLY WORKS (read before trying) ───────────────────────────────────────────
+# An `extends` target WINS over your own lefthook.yml on a colliding key. Verified with
+# `lefthook dump`: declare `pre-commit.commands.oxfmt.run` (or `glob:`) in your file and the
+# preset's value is what runs — yours is discarded silently, with no warning. Only keys this preset
+# does NOT define merge in from yours. So:
+#   • `env:`, `exclude:`, `skip:` and any command name not used here — yours, they merge.
+#   • `run:` and `glob:` on a command below — NOT overridable. Do not try.
+# The sanctioned seams are therefore:
+#   • `BASALT_BIN` (below) — set it via `env:` to point the guard at a specific CLI.
+#   • `exclude:` — carve files out of a glob you cannot narrow.
+#   • a differently-named command of your own, plus `skip: true` on the one here you are replacing.
 #
 # It does NOT assume your `.oxlintrc.json` extends the shipped preset — that assumption was
 # false for exactly the repos this seed exists for, since `init` KEEPS an existing oxlint
-# config. `basalt-ui doctor` now checks the extends and hard-fails when it is missing; run it
-# in CI (the seeded check.yml does) rather than trusting a comment nobody reads.
+# config. `basalt-ui doctor` now checks the extends and hard-fails when it is missing OR when it
+# points at a path that does not resolve; run it in CI (the seeded check.yml does) rather than
+# trusting a comment nobody reads.
 #
 # `init` seeds the path RESOLVED from where basalt actually installed. Under bun's isolated
 # linker basalt lives beside the package that depends on it, not at the repo root, and a
-# root-relative `extends` there resolves to nothing — silently, because lefthook merges an
-# empty file without complaint.
+# root-relative `extends` there resolves to nothing — silently, because lefthook merges a missing
+# file into ZERO commands and exits 0. `basalt-ui doctor`'s `lefthook-preset` check is the only
+# thing that can see that state; nothing else errors.
 pre-commit:
   parallel: true
   commands:
@@ -24,9 +37,20 @@ pre-commit:
     # `css` is load-bearing, not tidiness: oxfmt formats stylesheets, so without it a CSS-only
     # commit passes the hook and then fails the same check in CI. `oxlint` above deliberately
     # stops at JS — it has nothing to say about CSS.
+    #
+    # SOURCE EXTENSIONS ONLY, deliberately. This glob used to include `json,md,yml,yaml`, which
+    # reached every staged file at the repo ROOT — and oxfmt pads markdown table separators, so it
+    # blocked commits on a consumer's CLAUDE.md and docs/ over a house style basalt has no opinion
+    # about, in files their own `format` script does not own. Since you cannot narrow this glob
+    # (see the override note above), the preset has to be the one that is narrow. Markdown, YAML
+    # and JSON stay yours: add them to your own `format` script if you want them formatted.
+    #
+    # `--no-error-on-unmatched-pattern` covers the case where every staged file is excluded by an
+    # ignore file: oxfmt exits 2 on "Expected at least one target file", which failed a docs-only
+    # commit for any consumer carrying a .prettierignore — and, again, they could not add the flag.
     oxfmt:
-      glob: '*.{ts,tsx,js,jsx,css,json,md,yml,yaml}'
-      run: bunx oxfmt --check {staged_files}
+      glob: '*.{ts,tsx,js,jsx,css}'
+      run: bunx oxfmt --check --no-error-on-unmatched-pattern {staged_files}
 
     # NO glob, deliberately. This command scans the configured `basalt.roots` — it never reads
     # {staged_files} — so any glob here is a gate on WHETHER the guard runs, decided by the file
@@ -38,14 +62,23 @@ pre-commit:
     # Without this, a consumer accumulates violations indefinitely while `check-theme` is never
     # invoked, and the kinds it never ran are indistinguishable from the kinds that found nothing.
     #
+    # `$BASALT_BIN` is the one sanctioned override seam here, because `run:` itself is not
+    # overridable (see the note at the top). It defaults to `bunx --no-install basalt-ui`:
+    #   • `--no-install` because a plain `bunx basalt-ui` in a repo where basalt is not resolvable
+    #     from the ROOT (bun's isolated linker puts it beside the package that depends on it)
+    #     silently downloads a DIFFERENT copy from npm and gates the commit with a version nobody
+    #     pinned. With the flag it fails loudly instead, which is the answer you can act on.
+    #   • point it at the local bin to fix that, exactly as the seeded check.yml does:
+    #       pre-commit:
+    #         commands:
+    #           check-theme:
+    #             env: { BASALT_BIN: ./packages/web/node_modules/.bin/basalt-ui }
+    #
     # Lefthook runs commands at the REPO ROOT, while in a monorepo the `basalt` config and the
     # manifest live in a package below it — verified to produce `0 files scanned`, i.e. following
     # this preset installed a gate that never gated. `check-theme` now relocates to the single
     # workspace package carrying a basalt config and says so; with more than one, set BASALT_CWD
-    # in your own lefthook.yml to name the package:
-    #   pre-commit:
-    #     commands:
-    #       check-theme:
-    #         env: { BASALT_CWD: apps/web }
+    # in the same `env:` block to name the package:
+    #   env: { BASALT_CWD: apps/web }
     check-theme:
-      run: bunx basalt-ui check-theme
+      run: ${BASALT_BIN:-bunx --no-install basalt-ui} check-theme