basalt-ui 1.20.0 → 1.22.0

package/AGENTS.md

@@ -79,11 +79,17 @@ Register `guard-hook` in `.claude/settings.json` under `hooks.PreToolUse` with m
 `Write|Edit|MultiEdit` and command `bunx basalt-ui guard-hook` so the agent can't write off-palette
 colors without a `theme-allow` comment.
 
-**The escape hatch is `theme-allow <rule-id> — <reason>`**, scoped to that one kind. It is honoured
-on the reported line, on a comment-only line directly above it, and — in CSS — from a trailing
-comment back over the declaration it terminates. A bare `theme-allow` still waives everything but
-reports `theme-allow-unscoped`. A word in the id slot that names no rule waives nothing — only a
-genuinely bare comment is the blanket form.
+**The escape hatch is `theme-allow <rule-id> — <reason>`**, scoped to that one kind and to that one
+node/line. It must START its comment (after `//`, `/*`, `<!--`, a block gutter `*`, or whitespace),
+and is honoured on the reported line, on a comment-only line directly above it (reaching the first
+CODE line below, through the rest of its comment block), and — in CSS — from a trailing comment back
+over the declaration it terminates. Whole-file scope is `theme-allow-file <id>… — <why>`; a bare
+`theme-allow-file` waives nothing. A bare `theme-allow` still waives everything on its placement but
+reports `theme-allow-unscoped`. A word in the id slot that names no rule waives nothing.
+`.json`/`.webmanifest` use a `"basalt:theme-allow[-file]"` member. Audit them all with
+`basalt-ui check-theme --audit-allows`, which exits 1 on a waiver that suppresses nothing. It judges
+plugin-rule waivers too (since 1.21.1), by re-running oxlint — so it needs oxlint reachable;
+otherwise the verdict is "cannot judge", never "dead".
 
 > **Framework-internal only** — `bunx basalt-ui check-coverage` is a self-consistency gate for the
 > basalt-ui repo itself (asserts SURFACES ↔ rule files ↔ skill files ↔ package.json exports). It

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+# [1.22.0](https://github.com/jkrumm/basalt-ui/compare/v1.21.0...v1.22.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* let `icons: false` reach the manifest it was only skipping in the head ([58abe27](https://github.com/jkrumm/basalt-ui/commit/58abe27be10e5baf7c4659aa79904a7646ff092d))
+* scope the shadow-export tripwire to basalt consumers, and to components ([60716d4](https://github.com/jkrumm/basalt-ui/commit/60716d4ba00908c1a157f5568e192c6c50e438ec))
+* stop sync scaffolding a second consumer, and give the audit the oxlint half ([45cf3d3](https://github.com/jkrumm/basalt-ui/commit/45cf3d340f081e61f3f10f852d12f79928993d2a))
+
+
+### Features
+
+* give the waiver audit an annotation reader, and fix two shapes ([0dde850](https://github.com/jkrumm/basalt-ui/commit/0dde85052269780a61ead0688005db16e24f009a))
+
+# [1.21.0](https://github.com/jkrumm/basalt-ui/compare/v1.20.0...v1.21.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* delete a waiver that stopped covering anything ([3984281](https://github.com/jkrumm/basalt-ui/commit/3984281fff6313c225bdf1e185de4a427d2ef4df))
+* emit 0.1, not 0.10, from the shadow palette itself ([48adfff](https://github.com/jkrumm/basalt-ui/commit/48adfffcc9ad7713cacc07c1fc090b219fd175fa))
+* let the real color scheme win, and keep <meta charset> in its window ([8708c85](https://github.com/jkrumm/basalt-ui/commit/8708c85f1488b25e6a059ee879dcadf6350278a2))
+* make an annotation start its comment, and let it scope to one node ([a4cf78c](https://github.com/jkrumm/basalt-ui/commit/a4cf78c546d291c33a27bf94d7636758072a1005))
+* persist sidebar collapse through basalt's own state primitive ([c576040](https://github.com/jkrumm/basalt-ui/commit/c576040172dfeb8d66b52909bbcf55b7b1f91c70))
+* resolve the paths the wiring checks only matched, and audit the waivers ([c595181](https://github.com/jkrumm/basalt-ui/commit/c5951817ed01d7729f031bba2f3da50c3bf60666))
+* restore the palette fixture to emitter bytes ([605e240](https://github.com/jkrumm/basalt-ui/commit/605e240387a417f57ae8070f97bad79d97545d60))
+
+
+### Features
+
+* give the type ladder the two rungs consumers could only waive ([29b9ef3](https://github.com/jkrumm/basalt-ui/commit/29b9ef3767282dffb51fb52138d6ae4f1d24dd62))
+* make the search-param store's reader reachable from the API ([6924970](https://github.com/jkrumm/basalt-ui/commit/6924970f410b82ba5cfc65fd1d5088124934fc8f))
+
 # [1.20.0](https://github.com/jkrumm/basalt-ui/compare/v1.19.1...v1.20.0) (2026-08-22)
 
 

package/MIGRATING.md

@@ -6,8 +6,11 @@ nav definition" does not say `ChartHoverSync` was deleted. This file is that hal
 renamed exports per minor, with the replacement.
 
 Reconstructed from `git diff` over the published export surface across `v1.0.0..v1.19.1`, then
-cross-checked against the repo's `scripts/export-surface.json` snapshot. Verified 2026-08-22; the
-1.20.0 section below is written from the commits on `master` that produce it.
+cross-checked against the repo's `scripts/export-surface.json` snapshot. **Every replacement below
+was re-audited against the built declaration files at 1.20.0 (2026-08-22)** after round 5 caught one
+row that was wrong. That pass corrected 4 table rows and 3 prose claims. The 1.21.0 and 1.21.1
+sections were written against source, not against their commit messages. Check the types, not this
+table, if the two disagree.
 
 **No majors, by policy.** A rename or a removal ships as a plain `feat:` on the 1.x line, so a minor
 bump can require code changes. Skipping several at once is the expensive case — read every section
@@ -17,16 +20,174 @@ between your version and the target.
 > `## [1.` finds only the patches.
 
 **Minors with no public API delta:** 1.1.0, 1.3.0, 1.4.0, 1.5.0, 1.6.0, 1.7.0, 1.8.0, 1.9.0,
-1.10.0, 1.13.0, 1.14.0, 1.16.0, 1.18.0 — and every patch. Additive-only subpaths: `./tokens.css`
+1.10.0, 1.13.0, 1.14.0, 1.16.0, 1.18.0 — and every patch except 1.21.1. Additive-only subpaths: `./tokens.css`
 at 1.3.0, `./agent-chat` at 1.10.0.
 
 ---
 
+## 1.21.1 — the toolchain stops overclaiming
+
+**No export removed or renamed; four added.** Nothing you wrote changed. Every entry below is a
+check that reported an answer it had not earned, so a green CI on 1.21.0 was, for several of them,
+green over an empty set.
+
+**`sync` refuses where it used to scaffold.** Run from a sub-package that depends on basalt-ui but
+holds no `.basalt/manifest.json` — `apps/dashboard`, `apps/web` — it printed `0 updated, 20
+recreated`, wrote a second `basalt` key, and stood up a complete competing install beside the real
+one at the repo root. argo and rb both reverted it by hand. It now resolves its project exactly as
+`check-theme` and `doctor` do, and **exits 1** when the resolved project has no manifest, naming the
+install it found above instead. The refusal runs before the `basalt.roots` backfill, which was half
+the damage. Two ways to unblock it:
+
+```bash
+cd <the package holding .basalt/manifest.json> && bunx basalt-ui sync
+BASALT_CWD=<that package> bunx basalt-ui sync   # or from anywhere
+```
+
+The summary line gained a `created` counter. **`recreated` now means what it always claimed** — the
+ledger placed that file once and it went missing. Twenty first-time writes were never that.
+
+**`--audit-allows` judges plugin-rule annotations.** They used to print "not a check-theme kind" and
+drop out of the exit-1 gate, so the gate covered an empty set wherever the waivers were plugin
+rules: argo's whole tally was `0 live, 0 dead, 8 outside reach`, and 11 of linewatch's 14 went the
+same way. Each is now probed by re-running oxlint over that one file with the annotation
+neutralized. Judged now: argo 8 of 8, linewatch 14 of 14, basalt's own tree 23 of 23.
+
+**It requires oxlint to be reachable.** The probe writes one neutralized sibling file and re-runs
+oxlint over it (oxlint has no stdin mode), removing it in a `finally`. Where oxlint cannot run, the
+annotation is reported as **"cannot judge"**, never as dead. The report now also prints the scope it
+audited — `0 dead` over `basalt.roots` was reading as `0 dead anywhere`.
+
+**`doctor`'s `lefthook-preset` check asks a different question.** It tested whether the config text
+contained the `extends` string. It now asks whether the gate EXISTS, via `lefthook dump`, which
+resolves `extends`, `include` and per-command `root:`. linewatch wires all three jobs with
+`root: 'web/'` precisely because `extends` merges commands _without_ their working directory — it
+was correctly configured, got warned, and the old advice would have broken it. Three outcomes: a
+broken `extends` target is still a hard fail, a provably absent gate is a warn, and where
+`lefthook dump` could not run you get an advisory warning naming what it could not see.
+
+**`basalt/shadow-basalt-export` narrowed twice.** It now gates on `isBasaltScopedFile` like every
+other rule in the file, and needs a component-SHAPED declaration — a function, an arrow, a
+`memo`/`forwardRef` wrapper, or a class extending one. It had been firing on a `SlugTracker` class
+in a React-free package carrying no basalt-ui dependency, telling it to import from basalt-ui. The
+stated limit is unchanged: exact-name-only, a tripwire, not coverage.
+
+**`basaltAppPlugin({ icons: false })` now omits the manifest's `icons` member too.** It skipped the
+head `<link>` icons and emitted the two PNG manifest entries anyway, so `{ manifest: true, icons:
+false }` shipped an installable app pointing at two 404s. **If you went hybrid over this** — the
+plugin for the head, a hand-written manifest for the rest — **you can drop the hand-written half.**
+The option's JSDoc said "skips the head `<link>` icons"; it now says what the option does.
+
+**Two `theme-allow` comment shapes were silently broken and now work.** Plainly: this is the fourth
+hole found in this one contract in three rounds. The full thirteen-shape matrix is now pinned in
+both halves — `src/guard/check-source.test.ts` and `configs/oxlint-plugin.test.ts` — so the two
+parsers can no longer disagree about what an annotation IS.
+
+| Shape                                         | What it did                                                                                                                | Now                                     |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `/** theme-allow <id> — <why> */` on one line | waived under oxlint, reported under `check-theme`                                                                          | both halves honour it                   |
+| `{/*` + token on the next line + `*/}`        | comment-stripping left a bare `}`, so the line read as CODE and the annotation was classified trailing — scoped to a brace | scoped to the node below it, as written |
+
+**linewatch writes that wrapped shape for every hand-composed chart axis**, so any _guard_ kind
+annotated that way was silently unwaivable. It only appeared to work because the rules it names
+(`hand-rolled-plot`) live in the oxlint plugin, whose placement test is comment-node-based and never
+saw the brace.
+
+**New, additive — `./guard` gains four runtime exports**, the reader half of the audit:
+
+| Export                                       | Note                                                                                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `findAllowAnnotations(text, relPath, cfg)`   | every annotation as written, ids split into `guardKinds` / `pluginRules` / `unknownRules`. Shares `collectAllowAnnotations` with `checkSource`, so it cannot list a line the scan does not honour |
+| `neutralizeAllowAnnotation(text, line, cfg)` | one annotation rewritten to the token below, every other left intact — the probe half of an audit                                                                                                 |
+| `NEUTRALIZED_ALLOW_TOKEN`                    | so a guard probe and an oxlint probe neutralize identically                                                                                                                                       |
+| `PLUGIN_RULE_IDS`                            | the ids only oxlint can judge                                                                                                                                                                     |
+
+The `AllowAnnotationSite` type ships alongside them.
+
+**Known gaps, reported and not fixed:** `--audit-allows` says nothing about `basalt.exempt` — a
+whole file removed from the scan, the broadest exception the config surface has — and its
+`scoped to …` line does not distinguish `theme-allow` from `theme-allow-file`.
+
+## 1.21.0 — the `theme-allow` grammar
+
+**No export removed or renamed.** One break, and it is in the escape hatch itself: **file scope must
+now be spelled `theme-allow-file`.** At 1.20.0 an annotation that named a rule and gave a reason —
+the exact shape the rule's own message asks for — was promoted to a whole-file declaration, which is
+why per-node scoping never actually shipped. The two forms are now distinct:
+
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules
+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
+```
+
+**The migration is one word per file declaration.** Measured across the consumer sweep: linewatch
+0 → 11 findings, argo 0 → 6, rb 0 → 0 — all `warn`, so **no build changes colour**.
+
+```diff
+-// theme-allow hand-rolled-plot — two panes over one x scale
++// theme-allow-file hand-rolled-plot — two panes over one x scale
+```
+
+**An annotation must now START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
+or nothing but whitespace. Both parsers used a bare substring search, so a comment that merely
+_mentioned_ the token parsed as the legacy blanket form and switched every rule off on the line
+below. linewatch documented its own waivers in a docblock and thereby disarmed the file — a false
+NEGATIVE, and the reason this ships as a break rather than a grace period. Every annotation anyone
+actually writes still qualifies; a sentence about the escape hatch no longer waives anything.
+
+**A comment-only annotation now reaches the first CODE line below it**, walking through the rest of
+its own comment block. Before, a reason that wrapped onto a second line, or a docblock's `*/`,
+absorbed the waiver and the natural shape silently waived nothing — argo hit that three times in one
+upgrade. A blank line still ends the block.
+
+**`.json` / `.webmanifest` finally have a waiver.** They have been scanned since 1.20.0 and cannot
+hold a comment, so their findings were unwaivable and the printed remedy prescribed something
+impossible; both consumers fell back to a blanket `exemptRules`. Use a member key — but for a
+manifest, `basaltAppPlugin` is the first remedy, since a hand-copied hex drifts from the palette:
+
+```json
+{ "basalt:theme-allow-file": "raw-hex — a PWA manifest theme_color must be a literal hex" }
+```
+
+**Two API-shaped fixes worth acting on:**
+
+| Change                                                                     | What to do                                                                                                                                                                                                                                                |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createSearchParamStore` / `createMultiSearchParamStore` gain `linkSearch` | replace every nav link's `search: { <param>: '<literal>' }` with `search: <store>.linkSearch`, passed BY REFERENCE. A module-scope literal pins the fallback on every click — argo's reader had ZERO call sites, so "remember my window" had never worked |
+| `BasaltShell` collapse moves to `createPersistedState`                     | the key is now `basalt:<storageKey>` holding `{ v, value }`; read it with `readPersistedValue(storageKey, 1)`. A one-time migration adopts the raw pre-1.21.0 value, so the sidebar does not re-expand on upgrade                                         |
+
+**New, additive:**
+
+| Surface                                              | Note                                                                                                                                                                                                                                          |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check-theme --audit-allows`                         | every waiver and every `exemptRules` entry with what it still suppresses, proved by re-running the guard with that one occurrence neutralized. Exits 1 on a dead waiver — wire it into CI                                                     |
+| `basalt.exemptRules` takes paths, globs and a reason | relative paths and directory prefixes (`public/site.webmanifest`, `src/agent`), globs (`*` stops at `/`, `**` does not, a slash-free glob also matches the basename), and `{ paths, reason }`. Entries that suppress nothing are now reported |
+| `doctor` → `lefthook-preset`                         | hard-fails a broken `extends` target. lefthook merges a missing target into ZERO commands and exits 0, so a stale path leaves a repo with no pre-commit gate and a clean `lefthook dump`. `sync` reports the same seam                        |
+| `basaltAppPlugin({ colorScheme })`                   | `'dark'` (default) / `'light'` / `'auto'` / `false`. Set it to whatever the app passes as `defaultColorScheme` — before this, a light-scheme consumer got dark native controls permanently                                                    |
+| `VX.text.nano` (10px) + `VX.text.display` (30px)     | the two rungs `inline-font-size` could previously only be waived for. A 20px rung was rejected: 21/20 = 1.05 is below the ladder's 1.06×–1.17× band, so `h2` is the remedy                                                                    |
+| `sync` backfills `basalt.roots`                      | only `init` wrote it, so every existing consumer sat on the undeclared `src` default while `guard-scan` passed. A declared value is never overwritten                                                                                         |
+| `basalt/shadow-basalt-export` reads all nine barrels | the charts layer included. Still exact-name-only — a **tripwire, not coverage**                                                                                                                                                               |
+
+Also: `check-theme`'s `inline-spacing` no longer reads a unitless number in a plain options bag as
+CSS (`fitBounds({ padding: 48 })` stops reporting); the shipped `oxfmt` pre-commit job drops back to
+`*.{ts,tsx,js,jsx,css}` and gains `--no-error-on-unmatched-pattern`; `tokens:css` emits `0.1` rather
+than `0.10`, so a committed sheet stops failing prettier — re-run the command to pick it up.
+
+**The lefthook preset overrides YOU, not the other way round.** An `extends` target wins on a
+colliding key: declare `pre-commit.commands.oxfmt.run` (or `glob:`) in your own file and **yours**
+is the one silently discarded. Only keys the preset does not define merge in. The guard job runs
+`${BASALT_BIN:-bunx --no-install basalt-ui}`; that shell default is the sanctioned seam, set via
+`env:`, which does merge.
+
 ## 1.20.0 — enforcement
 
 **No export removed or renamed.** The whole delta is that things which used to pass now report. If
-your build goes red on this upgrade, that is the release working; every new kind and rule lands
-`warn`, so nothing here fails a build on its own.
+your build goes red on this upgrade, that is the release working. Every new **kind** and **rule**
+lands `warn` — but two other changes in this release do fail a build: `basalt/raw-size-literal`
+promotes to `error`, and the widened markup scan reads `index.html` / `.webmanifest`, where a raw
+hex is an `error`-severity colour kind. Two consumers exited 1 on exactly that.
 
 | Change                                                           | What you'll see                                                                                                 | What to do                                                                                |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
@@ -69,9 +230,18 @@ line is usually a multi-line opening tag or a `{expr}` child), and in CSS a trai
 reaching back over the declaration it terminates, which 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.** Every assembly node is reported
-and waived individually. A file-scoped exception now needs a written declaration naming the rule and
-giving a reason, anywhere in the file: `// theme-allow hand-rolled-plot — two panes over one x scale`.
+**`basalt/hand-rolled-plot` waivers must now be written deliberately.** Every assembly node is
+reported individually, and a waiver is no longer picked up off whatever comment happened to sit on
+the file's first assembly node — it needs a written declaration naming the rule and giving a reason,
+anywhere in the file: `// theme-allow hand-rolled-plot — two panes over one x scale`.
+
+**But the waiver is still whole-file, and per-node scoping is not expressible at 1.20.0.** Naming
+the rule AND giving a reason is what `hasFileDeclaration` matches, at any line — so a comment
+intended for one node silences the file. Dropping the reason keeps it node-scoped in the oxlint
+plugin, but then `check-theme` reports `theme-allow-unscoped ("no reason")`. The two halves of the
+contract intersect at exactly one legal shape and that shape is whole-file. Write the declaration in
+the component's docblock, where it reads as the file-level decision it is. **Fixed in 1.21.0** —
+see that section; the declaration moves to `theme-allow-file`.
 
 **`doctor` will go red.** `SKIPPED` is a third outcome beside pass/warn/fail and exits non-zero on
 its own — "All checks passed" is only printable when every check RAN. Three new hard checks:
@@ -98,18 +268,18 @@ each root's PARENT now contributes its `index.html` and `public/` tree.
 
 ## 1.19.0 — nav
 
-| Removed / renamed                                                 | Replacement                                                                             | Note                                                                |
-| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `NavLinkRenderer` (type)                                          | `defineNav` + `{...useNav(NAV)}` (`basalt-ui/router-tanstack`), or `SidebarItem.Anchor` | basalt now paints every nav pixel                                   |
-| `BasaltShellProps.renderNavLink`, `AppSidebarProps.renderNavLink` | same                                                                                    |                                                                     |
-| `BreadcrumbLinkRenderer` (type)                                   | `AppBreadcrumbs.parentAnchor`                                                           |                                                                     |
-| `BasaltShellProps.renderBreadcrumbLink`                           | same                                                                                    |                                                                     |
-| `BasaltShellProps.sidebarFooterExtra`                             | `mobileNav.moreExtra`                                                                   | its only host was the mobile drawer; it rendered nowhere on desktop |
-| `AppSidebarProps.footerExtra`, `AppSidebarProps.onClose`          | —                                                                                       | the full-height mobile sidebar drawer is deleted                    |
-| `MobileNavItem` (type)                                            | `MobileNavSlot`                                                                         |                                                                     |
-| `MobileNavSection` (type)                                         | `MobileNavGroup`                                                                        |                                                                     |
-| `MobileNavLinkRenderer` (type)                                    | `MobileNavModel`                                                                        |                                                                     |
-| `SidebarSection.mobileTab`                                        | `SidebarSection.mobile`: `'tab' \| 'more' \| 'hidden'` (`true`/`false` still accepted)  |                                                                     |
+| Removed / renamed                                                 | Replacement                                                                                                                      | Note                                                                                                                                                        |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NavLinkRenderer` (type)                                          | `defineNav` + `{...useNav(NAV)}` (`basalt-ui/router-tanstack`), or `SidebarItem.Anchor`                                          | basalt now paints every nav pixel                                                                                                                           |
+| `BasaltShellProps.renderNavLink`, `AppSidebarProps.renderNavLink` | same                                                                                                                             |                                                                                                                                                             |
+| `BreadcrumbLinkRenderer` (type)                                   | `AppBreadcrumbs.parentAnchor`                                                                                                    |                                                                                                                                                             |
+| `BasaltShellProps.renderBreadcrumbLink`                           | same                                                                                                                             |                                                                                                                                                             |
+| `BasaltShellProps.sidebarFooterExtra`                             | `mobileNav.moreExtra`                                                                                                            | its only host was the mobile drawer; it rendered nowhere on desktop                                                                                         |
+| `AppSidebarProps.footerExtra`, `AppSidebarProps.onClose`          | —                                                                                                                                | the full-height mobile sidebar drawer is deleted                                                                                                            |
+| `MobileNavItem` (type)                                            | `MobileNavSlot`                                                                                                                  |                                                                                                                                                             |
+| `MobileNavSection` (type)                                         | `MobileNavGroup`                                                                                                                 |                                                                                                                                                             |
+| `MobileNavLinkRenderer` (type)                                    | `MobileNavModel`                                                                                                                 |                                                                                                                                                             |
+| `SidebarSection.mobileTab`                                        | `SidebarSection.mobile?: false \| NavSectionMobile` — an OBJECT (`{ tab: true, label?, icon? }`), or `false` to hide the section | `'tab' \| 'more' \| 'hidden'` is `SidebarItem.mobile` (`NavMobilePlacement`, `true` ≡ `'tab'`, `false` ≡ `'hidden'`) — a different prop on a different type |
 
 A consumer with no router needs no migration — `href` + `onClick` still work.
 
@@ -130,20 +300,21 @@ never `search: true`.
 
 The largest delta in the 1.x line. No shims were shipped.
 
-| Removed / renamed                                                                                                                                                    | Replacement                                                                                       | Note                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `ChartHoverSync`, `ChartHoverSyncProps`                                                                                                                              | `globalCursorStore` / `createCursorStore` / `useChartCursor` / `useCursorState` — **no provider** | `ChartCursorScope` now _isolates_ a subtree; it is the inverse of the old provider, not a rename |
-| `HoverContext`, `HoverCtx`, `useHoverSync`, `DEFAULT_NO_OP_SET_HOVER`                                                                                                | `useChartCursor`, `useCursorState`, `CursorState`, `CursorStore`                                  | context → `useSyncExternalStore`                                                                 |
-| `ResponsiveChart`, `ResponsiveChartProps`                                                                                                                            | `CartesianChart` / `CartesianChartProps` (+ `autoMargin`, `PlotContext`, `PlotRect`)              | now mandatory for every single-plot cartesian chart, enforced by `basalt/hand-rolled-plot`       |
-| `ChartTooltip` (tip-based), `useChartTooltip`, `useTooltipStyles`                                                                                                    | `ChartTooltipFloat` + the `tooltip: CartesianTooltipConfig` prop                                  | portal / flip / clamp done once                                                                  |
-| `BarsAxisConfig`                                                                                                                                                     | `AxisConfig` + `resolveAxisDomain`                                                                |                                                                                                  |
-| `ZonedLineTooltipLabel`                                                                                                                                              | `tooltip` config on the kind                                                                      |                                                                                                  |
-| `ZonedLine`/`MultiLine`: `yDomain`, `yAutoPad`, `yAutoMaxFloor`, `yAutoMinCeil`, `numTicksY`, `formatYTick`                                                          | one `y?: AxisConfig<T>`                                                                           | `y` is **optional** where `yDomain` was required                                                 |
-| `ZonedLine`/`MultiLine`: `formatValue`, `tooltipLabel`, `renderExtraTooltipRows`                                                                                     | `tooltip?: CartesianTooltipConfig`                                                                | **not** `y` — these are tooltip concerns                                                         |
-| `ZonedLine`/`MultiLine`: `numTicksX`                                                                                                                                 | `xTicks`                                                                                          | `xZones` added alongside                                                                         |
-| `Bars`: `formatValue`, `hideBarTooltipRows`, `leftAxis`, `rightAxis`, `marginLeft`, `numTicksX`, `tooltipLabel`, `renderExtraTooltipRows`, `renderPrefixTooltipRows` | `y` / `y2` (`AxisConfig`), `tooltip`, `SeriesStyle.tooltip`, measured `autoMargin`                | passing `y2` is what makes a chart dual-axis; `chartMargin({ rightAxis })` is gone               |
-| `StackedArea`: `formatValue`, `numTicksX`, `numTicksY`, `yAutoMaxFloor`, `yLabel`                                                                                    | `y`, `tooltip`, `xTicks`                                                                          |                                                                                                  |
-| `Heatmap.width`                                                                                                                                                      | measures itself; takes `height` / `aspectRatio` / `fill`                                          |                                                                                                  |
+| Removed / renamed                                                                                                                                                    | Replacement                                                                                                                                                | Note                                                                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ChartHoverSync`, `ChartHoverSyncProps`                                                                                                                              | `globalCursorStore` / `createCursorStore` / `useChartCursor` / `useCursorState` — **no provider**                                                          | `ChartCursorScope` now _isolates_ a subtree; it is the inverse of the old provider, not a rename                                                                                                                                             |
+| `HoverContext`, `HoverCtx`, `useHoverSync`, `DEFAULT_NO_OP_SET_HOVER`                                                                                                | `useChartCursor`, `useCursorState`, `CursorState`, `CursorStore`                                                                                           | context → `useSyncExternalStore`                                                                                                                                                                                                             |
+| `ResponsiveChart`, `ResponsiveChartProps`                                                                                                                            | `CartesianChart` / `CartesianChartProps` (+ `autoMargin`, `PlotContext`, `PlotRect`)                                                                       | now mandatory for every single-plot cartesian chart, enforced by `basalt/hand-rolled-plot`                                                                                                                                                   |
+| `ChartTooltip` (tip-based), `useChartTooltip`, `useTooltipStyles`                                                                                                    | `ChartTooltipFloat` + the `tooltip: CartesianTooltipConfig` prop                                                                                           | portal / flip / clamp done once                                                                                                                                                                                                              |
+| `BarsAxisConfig`                                                                                                                                                     | `AxisConfig` + `resolveAxisDomain`                                                                                                                         |                                                                                                                                                                                                                                              |
+| `ZonedLineTooltipLabel`                                                                                                                                              | `tooltip` config on the kind                                                                                                                               |                                                                                                                                                                                                                                              |
+| `ZonedLine`/`MultiLine`: `yDomain`, `yAutoPad`, `yAutoMaxFloor`, `yAutoMinCeil`, `numTicksY`, `formatYTick`                                                          | one `y?: AxisConfig<T>`                                                                                                                                    | `y` is **optional** where `yDomain` was required                                                                                                                                                                                             |
+| `ZonedLine`/`MultiLine`: `tooltipLabel`, `renderExtraTooltipRows`                                                                                                    | `tooltip.label`, `tooltip.extraRows` (`CartesianTooltipConfig`)                                                                                            | there is no `appendRows`; the field is `extraRows`                                                                                                                                                                                           |
+| `ZonedLine`/`MultiLine`: `formatValue`                                                                                                                               | **`y.format`** — or per-series `ChartSeries.formatValue` for one row                                                                                       | `CartesianTooltipConfig` has no value formatter: the axis format IS the tooltip value format                                                                                                                                                 |
+| `ZonedLine`/`MultiLine`: `numTicksX`                                                                                                                                 | `xTicks`                                                                                                                                                   | `xZones` added alongside                                                                                                                                                                                                                     |
+| `Bars`: `formatValue`, `hideBarTooltipRows`, `leftAxis`, `rightAxis`, `marginLeft`, `numTicksX`, `tooltipLabel`, `renderExtraTooltipRows`, `renderPrefixTooltipRows` | `y` / `y2` (`AxisConfig`), `xTicks`, `tooltip.{label,extraRows,prependRows}`, per-bar `BarsBar.formatValue` / `.tooltip`, measured `autoMargin` + `margin` | passing `y2` is what makes a chart dual-axis. `chartMargin({ rightAxis })` is **not** removed — it is still exported from `basalt-ui` and `basalt-ui/charts`; it is simply no longer needed, since the right gutter follows from measurement |
+| `StackedArea`: `formatValue`, `numTicksX`, `numTicksY`, `yAutoMaxFloor`, `yLabel`                                                                                    | `y` (incl. `y.format`), `xTicks`; per-series `ChartSeries.formatValue`                                                                                     | `StackedAreaProps` has **no** `tooltip` prop — its tooltip is entirely derived from `series`                                                                                                                                                 |
+| `Heatmap.width`                                                                                                                                                      | measures itself; takes `height` / `aspectRatio` / `fill`                                                                                                   |                                                                                                                                                                                                                                              |
 
 ## 1.12.0 — agent-chat, behaviour only
 
@@ -176,6 +347,12 @@ Names that have no 1.x equivalent: the `--chart-blue-1..8` sequential ramp (1.x
 `--vx-fill-*` only), the default font stacks as a token (they live in `styles.css`), `purple` as a
 text color, `black`, `blue-400`/`green-400`.
 
+**The typefaces changed at 1.0, not just their delivery.** 0.4.2 shipped Instrument Sans; 1.x ships
+Nunito Sans (body) + Hubot Sans (condensed headings), mono unchanged at JetBrains Mono. `fonts:css`
+emits the 1.x stacks — for a 0.4.2 migrant that is a **rebrand**, not a restoration. It also emits
+`--basalt-font-head-stretch: 88%`, tuned for Hubot Sans specifically; pointed at another face it
+silently condenses it.
+
 ## 1.0.1 — CLI binary renamed
 
 `basalt` → **`basalt-ui`**. Never `bunx basalt`.
@@ -191,18 +368,18 @@ live in `configs/oxlint.json`, and since 1.20.0 their grace is tracked by `PLUGI
 named export beside the plugin — a test asserts it against the shipped preset in both directions, so
 deleting an entry forces the level flip in the same commit.
 
-| Rule                               | Landed           | Became `error`                     |
-| ---------------------------------- | ---------------- | ---------------------------------- |
-| `mantine-shade-index` (guard kind) | 1.7.0 as `warn`  | **1.11.0**                         |
-| `basalt/raw-scroll-container`      | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0** |
-| `basalt/ai-sdk-major`              | 1.10.0 as `warn` | **1.13.0**                         |
-| `basalt/agent-no-raw-usechat`      | 1.10.0 as `warn` | **1.13.0**                         |
-| `basalt/agent-resume-guard`        | 1.10.0 as `warn` | **1.13.0**                         |
-| `basalt/raw-size-literal`          | 1.7.0 as `warn`  | **1.20.0**                         |
-| `basalt/hand-rolled-plot`          | 1.15.0 as `warn` | still `warn` — widened at 1.20.0   |
-| `basalt/chart-legend-literal`      | 1.15.0 as `warn` | still `warn` — widened at 1.20.0   |
-| `basalt/shadow-basalt-export`      | 1.20.0 as `warn` | may stay `warn` permanently        |
-| `basalt/hand-rolled-shell`         | 1.20.0 as `warn` | —                                  |
+| Rule                               | Landed           | Became `error`                                                           |
+| ---------------------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `mantine-shade-index` (guard kind) | 1.7.0 as `warn`  | **1.11.0**                                                               |
+| `basalt/raw-scroll-container`      | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0**                                       |
+| `basalt/ai-sdk-major`              | 1.10.0 as `warn` | **1.13.0**                                                               |
+| `basalt/agent-no-raw-usechat`      | 1.10.0 as `warn` | **1.13.0**                                                               |
+| `basalt/agent-resume-guard`        | 1.10.0 as `warn` | **1.13.0**                                                               |
+| `basalt/raw-size-literal`          | 1.7.0 as `warn`  | **1.20.0**                                                               |
+| `basalt/hand-rolled-plot`          | 1.15.0 as `warn` | still `warn` — widened again at 1.21.0; grace restarts with the widening |
+| `basalt/chart-legend-literal`      | 1.15.0 as `warn` | still `warn` — widened at 1.20.0                                         |
+| `basalt/shadow-basalt-export`      | 1.20.0 as `warn` | may stay `warn` permanently — widened at 1.21.0, narrowed at 1.21.1      |
+| `basalt/hand-rolled-shell`         | 1.20.0 as `warn` | —                                                                        |
 
 `card-with-border`, `inline-display`, `raw-html-layout`, `raw-form-control`, `raw-font-family` and
 the other original guard kinds have been `error` since before 1.2.0 — they never had a grace minor.
@@ -214,7 +391,7 @@ in the shipped preset). A config still naming `import-boundary` after 1.1.0 disa
 
 ## Deprecated, not yet removed
 
-The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.20.0**.
+The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.21.0**.
 `buildPaletteCss({ legacyAliases: false })` / `tokens:css --no-legacy-aliases` opts out now; a later
 minor flips the default.
 
@@ -223,6 +400,10 @@ minor flips the default.
 - Props declared inline on a component (`function X({ a }: { a: string })`) rather than on an
   exported type are outside the diff method used here. Spot checks on the shell and charts modules
   found none, but the negative is unproven.
-- `AppBreadcrumbs.parentAnchor` as the replacement for `renderBreadcrumbLink` comes from the 1.19.0
-  commit body, not from a diffable exported type — `AppBreadcrumbsProps` is not in the public export
-  set at either tag.
+- The 0.4.2 `./css` line counts in the 1.0.0 table (877 lines / 307 custom props / 19 utilities) come
+  from the removal commit, not from a re-read of the 0.4.2 tarball.
+
+`AppBreadcrumbs.parentAnchor` was listed here through 1.20.0 and is now verified: it is declared on
+the shipped `dist/shell/app-breadcrumbs.d.ts` (`parentAnchor?: NavAnchor`, with `parentHref` as the
+no-router fallback). The type is inline on the component rather than an exported `AppBreadcrumbsProps`,
+which is why the export-surface diff never saw it.

package/README.md

@@ -193,12 +193,19 @@ and everything derives from it — the guard's scan, the seeded CI `oxfmt` globs
 exemption:
 
 ```json
-// package.json — `roots` is written by init; the rest are yours to add
+// package.json — `roots` is written by init and backfilled by sync; the rest are yours to add
 {
   "basalt": {
     "roots": ["apps/web/src"],
     "include": ["app/manifest.json"],
-    "profile": "tokens-only"
+    "profile": "tokens-only",
+    "exemptRules": {
+      "inline-display": ["agent"],
+      "raw-hex": {
+        "paths": ["public/site.webmanifest"],
+        "reason": "a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var"
+      }
+    }
   }
 }
 ```
@@ -214,6 +221,19 @@ which would silence half the guard on any repo keeping Mantine in a different wo
 Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are documented on the
 `BasaltConfig` type.
 
+**`exemptRules`** turns one kind off along a path. A pattern is a relative path
+(`public/site.webmanifest`, or `src/agent` for everything under it), a glob (`*` stops at `/`, `**`
+does not, and a slash-free glob is also tried against the basename, so `*.module.css` works), or a
+bare path segment — the legacy shape, and the one nobody guesses, since before 1.21.0 it was the
+ONLY shape and a real relative path matched nothing and said nothing. The object form records the
+reason, which is what a `theme-allow` always carried and this key could not. A pattern that
+suppresses nothing is now reported by a normal run and fails `--audit-allows`.
+
+`sync` **backfills `roots`** when the key is absent — only `init` used to write it, so every
+existing consumer stayed on the undeclared `src` default while `guard-scan` passed anyway. A
+declared value is never overwritten; a layout it does not cover is reported as one line, because
+`roots` being a subset is the normal case in a monorepo, not drift.
+
 Basalt-emitted LINES are skipped, not whole files. The file has to earn it first — a `.css` path,
 the `@generated basalt-ui` header verbatim on line 1, the version + invocation line on line 2 — and
 then each line does too: at brace depth 0 a selector or a self-closing comment, inside a block only
@@ -222,12 +242,31 @@ stylesheet `tokens:css` just wrote is not reported back at you, pasting the mark
 suppresses nothing, and an ordinary declaration smuggled into a sheet wearing the header is
 reported on its own line.
 
-**The escape hatch is scoped.** `theme-allow <rule-id> — <reason>` waives that one kind, on the
-reported line, on a comment-only line directly above it (the only form JSX can express), or — in
-CSS — from a trailing comment back over the declaration it terminates. A bare `theme-allow` still
-waives everything but reports `theme-allow-unscoped`. The id slot is read strictly: a word there
-that names no rule waives nothing, so an annotation covers exactly the ids it got right and a typo
-is never the blanket form.
+**The escape hatch is scoped, and since 1.21.0 the two scopes are spelled apart:**
+
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules
+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 annotation must **start** its comment (after `//`, `/*`, `<!--`, a block gutter `*`, or
+whitespace) — before 1.21.0 any comment merely mentioning the token parsed as the bare blanket form,
+so a file documenting its own waivers disarmed itself. Placements: the reported line, a comment-only
+line directly above it (the only form JSX can express, and it reaches the first CODE line below,
+walking through the rest of its comment block), or — in CSS — a trailing comment reaching back over
+the declaration it terminates. The id slot is read strictly: a word there that names no rule waives
+nothing, so a typo is never the blanket form.
+
+`basalt-ui check-theme --audit-allows` reports every annotation and every `exemptRules` entry with
+what it still suppresses, proved by re-running the scan with that one waiver neutralized. Exits 1 on
+a dead waiver, so it is usable as a CI gate. Since 1.21.1 it runs **both** halves — `checkSource` for
+a guard kind, oxlint over one neutralized sibling file for a plugin rule — so a waiver naming
+`hand-rolled-plot` is judged rather than skipped. **It needs oxlint reachable**; where it is not, the
+verdict is "cannot judge", never "dead". The report prints the scope it audited, because `0 dead`
+over `basalt.roots` is not `0 dead anywhere`. Two known gaps: `basalt.exempt` is not audited at all,
+and the `scoped to …` line does not distinguish `theme-allow` from `theme-allow-file`.
 
 `doctor`'s `ai-major-parity` hard check fails a monorepo where workspace packages declare different
 `ai` package majors — unless the split is intentional and written down. A producer pinned to an
@@ -260,7 +299,7 @@ deleted rather than silently surviving into the next real skew.
 | `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                      |
 | `./query`           | **free** | `createBasaltQueryClient`, transport-agnostic `unwrap`, lazy `BasaltQueryDevtools`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `./router-tanstack` | **free** | TanStack Router bridge: `useBasaltNav` (active route) + `useRouterBreadcrumbs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `field`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -655,7 +694,15 @@ honour `BASALT_CWD`, and relocate to the single workspace package carrying a bas
 invoked from a repo root that has none (two candidates is reported as ambiguous, never guessed).
 `tokens:css` and `fonts:css` both take `--check` as a CI drift gate.
 
-`sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff); missing → recreate. `--force` overwrites local edits.
+`sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff);
+missing → recreate. `--force` overwrites local edits. The summary counts `created` and `recreated`
+apart: `recreated` means the ledger placed that file once and it went missing.
+
+**`sync` refreshes an existing install; it does not create one.** It resolves its project exactly as
+`check-theme` and `doctor` do, and since 1.21.1 **exits 1** when the resolved project has no
+`.basalt/manifest.json`, naming the install it found above instead of scaffolding a second one
+beside it. Run it at the package that holds the manifest, or point `BASALT_CWD` at that package.
+Creating an install is `basalt-ui init`'s decision.
 
 ---