basalt-ui 1.19.1 → 1.20.0

package/AGENTS.md

@@ -67,7 +67,9 @@ bunx basalt-ui init              # FIRST STEP: scaffold .claude/rules/ + .claude
 bunx basalt-ui check-theme       # fail on off-palette colors in consumer source
 bunx basalt-ui sync              # reconcile managed files (.claude/rules/, .claude/skills/, CLAUDE.md block)
 bunx basalt-ui sync --check      # CI freshness gate — exits non-zero if any managed file drifted
-bunx basalt-ui doctor            # check consumer repo basalt integration health
+bunx basalt-ui doctor            # integration health — SKIPPED is a third outcome and exits non-zero
+bunx basalt-ui tokens:css        # emit the --vx-* stylesheet (no React, no Mantine, no bundler)
+bunx basalt-ui fonts:css         # emit the shipped --basalt-font-* stacks
 bunx basalt-ui info              # print published surface map
 bunx basalt-ui info --json       # stable JSON surface map
 bunx basalt-ui guard-hook        # PreToolUse theme-guard adapter: reads a Write/Edit payload on stdin, denies off-palette writes
@@ -77,6 +79,12 @@ 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.
+
 > **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
 > is not a consumer command and will skip assertion 3 outside the framework repo.
@@ -85,3 +93,9 @@ colors without a `theme-allow` comment.
 
 See `basalt-ui/llms.txt` (importable via the package specifier) for the full surface map: one
 entry per published subpath with import specifier, description, layer, and optional peer packages.
+
+## Upgrading across minors
+
+`CHANGELOG.md` lists every release; `MIGRATING.md` lists what **broke** — removed and renamed
+exports per minor, with the replacement. No majors ship here, so a minor bump can require code
+changes. Read `MIGRATING.md` before jumping more than one minor.

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [1.20.0](https://github.com/jkrumm/basalt-ui/compare/v1.19.1...v1.20.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* exempt generated LINES, not files, and stop flagging prose as a typo'd id ([a83abfb](https://github.com/jkrumm/basalt-ui/commit/a83abfb77888f31528f44e5923b26d3710ddf005))
+* give the mobile-nav-pill demo row its own glyph ([4620590](https://github.com/jkrumm/basalt-ui/commit/4620590204a99afd07ec27eb923cd229acdfce84))
+* hold basalt to its own scoped theme-allow contract ([b67718c](https://github.com/jkrumm/basalt-ui/commit/b67718cecf8e7ce60b61b7481bcdbd4795f79d40))
+* make the escape hatch and the generated-file marker fail closed ([526cdb7](https://github.com/jkrumm/basalt-ui/commit/526cdb7f11395f27183828e34297b0ac6bc846c8))
+* make the mobile-nav active pill track density and survive an icon-less app ([0a7d756](https://github.com/jkrumm/basalt-ui/commit/0a7d7560f9eae6db4c02ff029ba47088a084e511))
+* snapshot the tokens-only guard export ([b63dc24](https://github.com/jkrumm/basalt-ui/commit/b63dc242bfd46359476f7fcae80957db244f727f))
+
+
+### Features
+
+* demo the mobile-nav active pill with and without an icon dependency ([9620905](https://github.com/jkrumm/basalt-ui/commit/9620905409efdf39bb10b40edaa128ce2b61c741))
+* make the escape hatch usable and close the holes round 4 found ([5b8420d](https://github.com/jkrumm/basalt-ui/commit/5b8420d24647b84818dfbb65e9f0c52ea1e79c2c))
+* scan the app shell, wire the tokens-only profile, ship __APP_VERSION__ ([61b1792](https://github.com/jkrumm/basalt-ui/commit/61b1792e8ea1bff3c59128ba65137b27d40df81a))
+* stop the toolchain reporting green while enforcing nothing ([d3d8e34](https://github.com/jkrumm/basalt-ui/commit/d3d8e3434893516e62413acafdd166be13b86541))
+
 ## [1.19.1](https://github.com/jkrumm/basalt-ui/compare/v1.19.0...v1.19.1) (2026-08-20)
 
 

package/MIGRATING.md

@@ -0,0 +1,228 @@
+# Migrating basalt-ui
+
+`CHANGELOG.md` ships in this package and lists every release. It cannot tell you what **broke**:
+semantic-release writes one line per commit, and "make the mobile bar navigate, driven by one typed
+nav definition" does not say `ChartHoverSync` was deleted. This file is that half — removed and
+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.
+
+**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
+between your version and the target.
+
+> Reading the CHANGELOG: minors and majors are `#` (h1), patches are `##` (h2). Grepping for
+> `## [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`
+at 1.3.0, `./agent-chat` at 1.10.0.
+
+---
+
+## 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.
+
+| Change                                                           | What you'll see                                                                                                 | What to do                                                                                |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `basalt/raw-size-literal` `warn` → **`error`**                   | CSS-length strings on `size`/`fz`/`fontSize` now fail lint                                                      | use a token (`size="sm"`); `warn` since 1.7.0, zero violations across all seven consumers |
+| Five new guard kinds (`warn`)                                    | `theme-allow-unscoped`, `surface-shadow-override`, `css-raw-surface`, `inline-font-size`, `hidden-inline-style` | see below; promotion is tracked in `GRACE_PERIOD_KINDS`                                   |
+| Two new oxlint rules (`warn`)                                    | `basalt/shadow-basalt-export`, `basalt/hand-rolled-shell`                                                       | import the shipped component instead of the fork                                          |
+| `basalt/hand-rolled-plot`, `basalt/chart-legend-literal` widened | more sites report; both stay `warn`                                                                             | a widened rule does not promote in the minor that widens it                               |
+| `doctor` `SKIPPED` exits non-zero, + 3 new hard checks           | doctor goes red where it was green                                                                              | that is the finding — see below                                                           |
+
+**`theme-allow` has a new contract, and one comment shape stops waiving.** A bare `theme-allow`
+still waives every kind, but now reports `theme-allow-unscoped`. Rescope it — and spell the id
+right, because a word in the id slot that names no rule now waives NOTHING rather than degrading to
+the blanket form:
+
+```diff
+-// theme-allow
++// theme-allow raw-surface — third-party widget needs a literal corner
+```
+
+**The break: a reason with no separator introducing it.** `// theme-allow legacy vendor asset` used
+to waive the line; it now waives nothing and the un-suppressed finding reports at its own severity
+(`error` for `raw-hex`). The first word after the token is read as a rule id, and an id that names
+no rule fails closed — that is the whole point, since the alternative is one mistyped character
+silently widening a scoped waiver into a blanket one. No annotation in any of the seven consumer
+repos writes that shape; every one of them introduces its reason with `—`, `–`, `-` or `:`. Add a
+separator, or an id:
+
+```diff
+-// theme-allow legacy vendor asset
++// theme-allow raw-hex — legacy vendor asset
+```
+
+Prose AFTER a resolved id is safe and needs no separator —
+`// theme-allow raw-surface sub-scale legend corner` waives `raw-surface` and reports nothing. Only
+a comma keeps the id list open past the first id.
+
+Two placements that used to fail now work, both matching what the oxlint plugin always did: a
+comment-ONLY line directly above the reported line (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, 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`.
+
+**`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:
+`basalt-resolves` (walks cwd → ancestors → workspace packages), `guard-scan` (would `check-theme`
+cover more than zero files?), `oxlint-preset` (does `.oxlintrc.json` really extend the shipped
+preset? JSONC is parsed, not rejected — `init` keeps an existing config, so one repo ran five minors
+with the whole lint half off).
+
+**New, additive:**
+
+| Surface                                                          | Note                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `basalt.profile: 'tokens-only'` / `--tokens-only`                | disables the 17 kinds whose remedy is a Mantine component, prop or the React theme factory. `check-theme` requires it DECLARED; `doctor` infers it, because its profile only changes advice, never enforcement                                                                                                                                                                                                                               |
+| `basalt.include: [...]`                                          | scan a named file outside `roots` — and the only route to a `.json`, which is never blanket-scanned                                                                                                                                                                                                                                                                                                                                          |
+| `basalt.roots` + a `lint:basalt` script                          | written by `init` from the real layout; `init` on an existing app is a lint-debt event, not a no-op                                                                                                                                                                                                                                                                                                                                          |
+| `tokens:css --check`, `--selector-class <c>` (+ `--light-class`) | drift gate; the Tailwind `<html class="dark">` convention. There is no `scheme: { class }` API — the class form is CLI-only                                                                                                                                                                                                                                                                                                                  |
+| `fonts:css [--out] [--check]`                                    | the shipped `--basalt-font-*` stacks as plain CSS, read out of `styles.css` — the only route to basalt's typefaces without the Mantine-coupled `styles.css`                                                                                                                                                                                                                                                                                  |
+| `__APP_VERSION__` ambient declaration                            | ships via `src/register.ts`, re-exported by the root barrel: delete your hand-written ambient block. A subpath-only consumer does not get it                                                                                                                                                                                                                                                                                                 |
+| `BASALT_CWD`                                                     | `check-theme`/`doctor` honour it, and relocate to the single workspace package carrying a basalt config when invoked from a root that has none                                                                                                                                                                                                                                                                                               |
+| `@generated basalt-ui` header                                    | `tokens:css`/`fonts:css` output carries it on line 1, the version + invocation line on line 2, and `check-theme`, in a `.css` file with that exact header, skips the LINES that are basalt custom properties, selectors, `}` or self-closing comments — this is what fixed 116 violations reported inside the stylesheet `tokens:css` had just written. Committed output emitted by 1.19.1 has no header: re-run the command to get the skip |
+
+`check-theme` also resolves `.html` / `.webmanifest` / `.json` as markup (colour kinds only), and
+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)  |                                                                     |
+
+A consumer with no router needs no migration — `href` + `onClick` still work.
+
+**Expect new type errors, and read them.** `renderNavLink` took `to` as an opaque value, which is
+why consumers reached for `to={target.to as never}`. `defineNav` types it, so a destination missing
+a required `search` now fails to compile — in one repo that surfaced two nav links that had been
+shipping without required params. Fix with a click-time thunk (`search: () => Schema.parse({})`),
+never `search: true`.
+
+## 1.17.0 — behaviour only, no export removed
+
+| Changed                                              | Effect                                                       | Opt out                          |
+| ---------------------------------------------------- | ------------------------------------------------------------ | -------------------------------- |
+| `resolveAxisDomain` clamps before padding, not after | the axis top moves on any chart with an `autoMaxFloor`       | lower the floor, or pin `domain` |
+| `ChartFrame` `role="img"` → `role="group"`           | `role="img"` pruned the keyboard slider out of the a11y tree | —                                |
+
+## 1.15.0 — chart layer rebuilt
+
+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`                                          |                                                                                                  |
+
+## 1.12.0 — agent-chat, behaviour only
+
+| Changed                                                                    | Effect                                                                                                                                              |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `streaming` no longer selects the image allowlist                          | **security-relevant.** Model output must now pass `contentTrust="untrusted"`; leaving it unset silently reopens prompt-injection image exfiltration |
+| consumer `rehypePlugins` output is now sanitized, `clobberPrefix` is empty | a consumer injecting non-default elements must pass a matching `sanitizeSchema`                                                                     |
+
+## 1.11.0 — agent parts
+
+Semver-breaking in a minor; the commit body says so.
+
+| Removed / renamed                                        | Replacement                                                                                           | Note                                                                                        |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `ToolCallPart` flat `{ type, toolName, input, output? }` | `ToolCallPart` as a 7-arm union discriminated on `state` (`input-streaming` … `output-error`)         | mirrors the AI SDK v7 lifecycle                                                             |
+| the error field named `error`                            | `errorText`                                                                                           | the SDK union has no `error`                                                                |
+| flattened approval fields                                | nested `approval: ToolApproval`, carried verbatim                                                     | flattening dropped `isAutomatic` / `signature`                                              |
+| —                                                        | every `AgentPart` now extends `PartBase` with a **required `id`**; `withPartIds` mints them on drafts | a 1.10-shaped part rehydrated from localStorage no longer throws, but id-less parts collide |
+| `ToolChip` threw `assertNever` on an unknown state       | now falls back instead of throwing                                                                    |                                                                                             |
+
+## 1.0.0 — the Mantine pivot
+
+| Removed / renamed                                                                             | Replacement                                                               | Note                                                                             |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `./css` subpath (877 lines: 307 custom props, 19 utilities, a reset, the Tailwind entrypoint) | `basalt-ui tokens:css` / `basalt-ui/tokens.css` — **but only from 1.3.0** | between 1.0.0 and 1.2.x the only CSS door was `styles.css` + `buildPaletteCss()` |
+| `./starlight` subpath                                                                         | —                                                                         | no replacement                                                                   |
+| the OKLCH foundation palette, ShadCN/Tremor/Starlight doctrine                                | the three-tier `--vx-*` system                                            | see `docs/FRAMEWORK-FREE.md` for the token-only route                            |
+
+Names that have no 1.x equivalent: the `--chart-blue-1..8` sequential ramp (1.x is categorical
+`--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`.
+
+## 1.0.1 — CLI binary renamed
+
+`basalt` → **`basalt-ui`**. Never `bunx basalt`.
+
+---
+
+## Lint and guard rules that tightened
+
+Two independent mechanisms, each with its own ledger — read the ledger, not this table, for what is
+in grace TODAY. `GuardKind` severities (`basalt-ui check-theme`) default to `error` and are
+downgraded only by `GRACE_PERIOD_KINDS` (`src/guard/index.ts`). `basalt/*` oxlint rule severities
+live in `configs/oxlint.json`, and since 1.20.0 their grace is tracked by `PLUGIN_RULE_GRACE`, a
+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` | —                                  |
+
+`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.
+Guard findings only gained a severity field at all in 1.4.0; before that every finding was fatal.
+
+**Rule-id rename at 1.1.0:** `basalt/import-boundary` split into `basalt/visx-boundary`,
+`basalt/visx-tooltip` and `basalt/token-layer-boundary` (the last is repo-local and deliberately not
+in the shipped preset). A config still naming `import-boundary` after 1.1.0 disables nothing.
+
+## Deprecated, not yet removed
+
+The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.20.0**.
+`buildPaletteCss({ legacyAliases: false })` / `tokens:css --no-legacy-aliases` opts out now; a later
+minor flips the default.
+
+## Not verified
+
+- 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.

package/README.md

@@ -65,6 +65,15 @@ That's the whole install — there is no plugin, no marketplace, and no second v
 - A thin `DESIGN.md` seed — your app's deltas (series dictionary, identity, deviations)
 - Toolchain seeds: `.oxlintrc.json` and `lefthook.yml` as `extends` stubs into `node_modules/basalt-ui/configs/` (the presets auto-update with the package), plus `.oxfmtrc.json` and `.github/workflows/check.yml` as starting copies
 - `.basalt/manifest.json` — sha256 per managed file + the basalt-ui version, for `sync` three-way diff and `doctor`
+- Two `package.json` patches: `basalt.roots` inferred from the real layout, and a `lint:basalt` script
+
+`init` on an **existing** app 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` names those plugins, and names every file it kept along with what
+keeping it costs — an `.oxlintrc.json` that does not extend the preset means the entire basalt lint
+half is inert and nothing else says so (`--merge-lint` splices the `extends` in; it refuses on a
+commented config rather than deleting the comments). Run `oxlint .` and triage before your next
+commit.
 
 Every file is either **managed** (basalt owns it, `sync` refreshes it, local edits are skipped and
 reported — exactly the files Claude reads, which cannot load from `node_modules`) or a **seed**
@@ -175,25 +184,50 @@ half — see the `./vite` adapter battery under [Adapter batteries](#adapter-bat
 
 ```ts
 // Lint — theme guard is the teeth behind the token doctrine
-// package.json scripts:
+// package.json scripts (init seeds this as "lint:basalt"):
 "lint": "oxlint . && basalt-ui check-theme"
 ```
 
-`check-theme` scans `src/` by default — a monorepo points it at its real roots via a `"basalt"`
-key in your `package.json`:
+`check-theme` scans `src/` by default; `init` writes a real `"basalt"` key from your actual layout,
+and everything derives from it — the guard's scan, the seeded CI `oxfmt` globs, the default scan
+exemption:
 
 ```json
-// package.json
+// package.json — `roots` is written by init; the rest are yours to add
 {
   "basalt": {
-    "roots": ["src"]
+    "roots": ["apps/web/src"],
+    "include": ["app/manifest.json"],
+    "profile": "tokens-only"
   }
 }
 ```
 
 `check-theme` fails loudly (instead of a false `✓`) when the configured roots resolve to zero
-scanned files. Other `"basalt"` config keys (`exempt`,
-`spacingSteps`, `forbiddenAccents`, …) are documented on the `BasaltConfig` type.
+scanned files, and `doctor`'s `guard-scan` check agrees with it. Each root's **parent** also
+contributes its `index.html` and its `public/` tree — the Vite layout `basaltViteConfig` assumes,
+and where a raw `theme-color` or webmanifest `background_color` actually lives. `.json` is never
+blanket-scanned; `include` names one explicitly and is the only route to it. `profile:
+"tokens-only"` turns off the 17 kinds whose remedy is a Mantine component or prop, and must be
+declared (or `--tokens-only`) — it is deliberately never inferred from a missing `@mantine/core`,
+which would silence half the guard on any repo keeping Mantine in a different workspace package.
+Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are documented on the
+`BasaltConfig` type.
+
+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
+a `--vx-*` / `--basalt-*` declaration whose value carries no `;`, a `}`, or a comment. So the
+stylesheet `tokens:css` just wrote is not reported back at you, pasting the marker into a `.tsx`
+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.
 
 `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
@@ -241,7 +275,7 @@ deleted rather than silently surviving into the next real skew.
 | `./connectivity`    | coupled  | `ConnectivityProvider` (aggregates browser/React-Query/SSE/health-check status), `useConnectivity`, `ConnectivityIndicator` — auto-mounted by `BasaltProvider`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `./content`         | coupled  | `Prose`, `CodeBlock`, `Callout`, `TableOfContents`, `ReadingProgress`, `Markdown`, `MermaidDiagram`, `ArticleLayout`, `ArticleCard` / `ArticleGrid`, `GuideLink` / `GuideDrawer`, `mdxComponents`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `./styles.css`      | —        | `@layer basalt` base styles, iOS input safety net, font stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `./tokens.css`      | **free** | Prebuilt `--vx-*` stylesheet — the default `buildPaletteCss()` output as a plain file, for a consumer with no bundler, React or Mantine; `basalt-ui tokens:css` re-emits it with a custom scheme selector                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./tokens.css`      | **free** | Prebuilt `--vx-*` stylesheet — the default `buildPaletteCss()` output as a plain file, for a consumer with a bundler but no React or Mantine. **With no bundler, use the `basalt-ui tokens:css` CLI instead** and commit the emitted file: importing this subpath needs bare-specifier resolution. See [`docs/FRAMEWORK-FREE.md`](https://github.com/jkrumm/basalt-ui/blob/master/docs/FRAMEWORK-FREE.md)                                                                                                                                                                                                                                             |
 | `./configs/*`       | —        | Raw toolchain presets — oxlint, oxfmt, tsconfig (base/react-app/node), lefthook                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `./llms.txt`        | —        | Machine-readable surface map — one entry per published subpath with import specifier, description, layer, and optional peers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
@@ -606,11 +640,21 @@ bunx basalt-ui init              # scaffold doctrine into a consumer repo
 bunx basalt-ui sync              # three-way diff against .basalt/manifest.json after a basalt-ui upgrade
 bunx basalt-ui sync --check      # CI drift gate — non-zero exit on any managed-file drift
 bunx basalt-ui check-theme       # palette guard — fails on colors that bypass the central --vx-* system
-bunx basalt-ui doctor            # check consumer repo basalt integration health: manifest presence, node_modules-vs-manifest version, spacing-scale drift, and a cross-package `ai` major-version parity check (HARD failure — walks every workspace manifest, exemptable via `basalt.aiMajorSkewReason` — see above) + warn on missing basaltAppPlugin icon files under public/
+bunx basalt-ui doctor            # integration health: basalt-resolves, guard-scan, oxlint-preset, manifest presence, node_modules-vs-manifest version, spacing-scale drift, and a cross-package `ai` major-version parity check (HARD failure — walks every workspace manifest, exemptable via `basalt.aiMajorSkewReason` — see above) + warn on missing basaltAppPlugin icon files under public/
+bunx basalt-ui doctor --tokens-only   # force the Mantine-free profile (auto-detected otherwise; --framework forces the full set)
+bunx basalt-ui tokens:css --out src/tokens.css     # emit the --vx-* stylesheet as a file you own
+bunx basalt-ui fonts:css --out src/fonts.css       # emit the shipped --basalt-font-* stacks
 bunx basalt-ui info              # human-readable surface map: subpath, layer, rule, skills, optional peers
 bunx basalt-ui info --json       # same map as stable JSON (InfoOutput shape)
+bunx basalt-ui help              # full usage; every subcommand also takes --help / -h
 ```
 
+`doctor` reports **`SKIPPED`** as a third outcome beside pass/warn/fail and exits non-zero on it —
+"All checks passed" is only printable when every check actually ran. `check-theme` and `doctor`
+honour `BASALT_CWD`, and relocate to the single workspace package carrying a basalt config when
+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.
 
 ---

package/agent/rules/basalt-app.md

@@ -69,6 +69,49 @@ 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.
+
+## `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

package/agent/rules/basalt-charts.md

@@ -55,19 +55,31 @@ 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"
-  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
+  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. A genuinely non-single-plot shape (multi-pane, radial, matrix) declares
+  itself with a written file declaration — a `theme-allow` that both names the rule and gives a
+  reason, anywhere in the file (`theme-allow hand-rolled-plot — two panes over one x scale`);
+  `DualPanel` carries the repo's only one. 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`** — 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
 
@@ -85,8 +97,8 @@ ships no map kind.
   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.
+  regex sees the line, not the binding. 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 +167,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-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`)