basalt-ui 1.22.0 → 1.23.1

package/agent/rules/basalt-charts.md

@@ -14,8 +14,10 @@ primitives so we can build exactly the chart we want; the trade-off is that ever
 structure unless we compose shared building blocks. **`CartesianChart` plus a small kind set are
 the contract, not optional polish** — composing `CartesianChart` (single-plot) or `ChartFrame`
 directly (multi-pane/radial/matrix) is mandatory for every chart, mechanically enforced by
-`basalt/hand-rolled-plot` (see "Mechanical enforcement" below). `docs/CHARTS-SPEC.md` is the ground
-truth this doc reflects.
+`basalt/hand-rolled-plot` (see "Mechanical enforcement" below). **This file is the contract you
+receive** — the basalt-ui repo's `docs/CHARTS-SPEC.md` is the same argument at length, and it does
+not ship in the package. Read it at
+<https://github.com/jkrumm/basalt-ui/blob/master/docs/CHARTS-SPEC.md> or not at all.
 
 ## The boundary (lint-enforced)
 
@@ -58,11 +60,13 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
   compose `CartesianChart`. **Since 1.20.0 every assembly node is reported and waived on its own**
   — one comment no longer grants the whole file permanent immunity, which is how a 604-line chart
   file went unpoliced. To waive ONE node, put `theme-allow hand-rolled-plot — <why>` on it (or on a
-  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix)
-  declares the whole file with `theme-allow-file hand-rolled-plot — two panes over one x scale`,
-  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.21.0
-  spelling** — at 1.20.0 a node-scoped annotation was silently promoted to a file declaration, so
-  per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
+  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix, or a
+  strip with no y dimension) declares the whole file with `theme-allow-file hand-rolled-plot —
+<why>`, anywhere in it; basalt's own tree carries three, on `DualPanel`, `BandStrip` and
+  `MirroredBars`. `Donut` and `Heatmap` are non-single-plot too and carry none — they render no
+  assembly primitive, so the rule never fires and there is nothing to waive.
+  **`theme-allow-file` is the 1.21.0 spelling** — at 1.20.0 a node-scoped annotation was silently
+  promoted to a file declaration, so per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
   exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
   cannot fire inside X.
 - **`basalt/chart-legend-literal`** — a hand-written array literal passed to `ChartLegend`'s
@@ -160,6 +164,13 @@ ships no map kind.
    onto one domain value, silently dropping one from the plot (see #6 below for why that's the
    cursor's problem too). `Heatmap` is deliberately excluded: its existing `colLabel`/`rowLabel`
    already are that seam, and a second prop over one concern would fork them.
+   **Which x ticks get painted is a separate seam**, `xTickValues?: (keys, xMax) => readonly
+string[]`, on `CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine`
+   plus both band kinds. Resolution order is explicit VALUES → explicit COUNT (`xTicks`, unchanged)
+   → as many as fit (`smartTicks`); omit both and nothing moves. Reach for it on a dense time axis,
+   because **a count cannot express one**: `smartTicks`/`smartTicksEvery` append the final key
+   unconditionally, so any count that does not land exactly on the last index paints two labels on
+   top of each other at the right edge — at every count, not at an unlucky one.
    **The x axis is CATEGORICAL, and this is not inferable from the API.** `CartesianChart` builds
    its x scale as `scalePoint<string>`, so N points are N evenly spaced positions whatever the
    values behind the keys — there is no linear or time x scale. Correct and invisible for a domain
@@ -332,6 +343,49 @@ per-series `getValue` accessors on `ChartSeries<T>`):
   wrapper.
 - **`Donut`** — proportional donut with an optional center-content overlay. Composes `ChartFrame`
   directly (radial, not cartesian).
+- **`BandStrip`** — 1-D categorical bands over a shared x axis, **no y dimension at all**: one rect
+  per slot, `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` IS the state set —
+  it drives the legend, each band's fill and the one derived tooltip row, so a strip cannot name a
+  state it does not draw. `absentFraction` paints the share of a folded slot nothing measured as a
+  hatch; `marker` carries a fact that must not be readable off the `fill` ramp. `cursorResolution`
+  defaults `'leading'` here (a band IS a bucket), not `'nearest'`. Composes `ChartFrame` directly —
+  `CartesianChart` renders `AxisLeftNumeric` unconditionally, so this shape could never use it.
+  `BandStripSeries.formatValue` is `(d) => string | null` — `null` renders an em dash, an absent
+  READING, which `''` cannot say (`''` is a state whose label is the whole row).
+- **`MirroredBars`** — two BAR panes over one x scale, mirrored around one baseline, each pane in
+  its own domain. `up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`; `upFraction`
+  (default 0.35) is the up pane's share of the band height, which is where the shared baseline sits;
+  `getAbsentFraction` hatches an unmeasured slot and `getBarOpacity` dims one. A sibling of
+  `DualPanel`, not an extension: `DualPanel`'s top pane is a LINE pane and its bottom takes one
+  SIGNED `getBar` over a symmetric domain. Two independent magnitudes are not one signed quantity.
+  Composes `ChartFrame` directly.
+
+Both band kinds fold their domain by width (`fold: { minBandPx?, merge }`), and `foldBands` is
+exported so a consumer can test their merge against the grouping that will actually run.
+`HatchPattern` / `hatchFill` / `hatchSizeFor` ship the absence fill.
+
+**`merge` does not run on a sub-cap dataset.** `foldBands` returns `[...data]` unchanged when
+`data.length <= cap`, which on a wide viewport is the common case — so any bookkeeping the merge
+adds (how many source buckets a slot folded, how many were unmeasured) is absent exactly where you
+are least likely to look for it. Put that bookkeeping on the datum at CONSTRUCTION and have `merge`
+sum it; do not compute it from `group.length` inside the merge. Summing is also the composable
+form, and it keeps "every source bucket accounted for exactly once" true by construction.
+
+**A band state naming no `series` entry throws in dev.** `series` IS the state set, so an
+unresolvable `state` has no legend entry, no colour and no tooltip row — and the old behaviour,
+skipping the band, drew a coverage GAP, which on a measured/not-measured strip is a false claim
+about the data rather than an "unknown". Where the key comes from decides the treatment:
+
+| Key comes off                                                 | Dev                                      | Production                                                             |
+| ------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
+| the DATUM — `BandSpan.state`, `marker.state`                  | throws, naming the key and the valid set | dashed neutral outline band + an `Unknown state` / `<key>` tooltip row |
+| a PROP — `absentState`, `MirroredBars`' `up.key` / `down.key` | throws                                   | throws                                                                 |
+
+A feed that grows a state basalt has never seen must degrade rather than take a dashboard down; a
+typo, which is the same input, still fails loudly wherever it is written. The dashed neutral outline
+is used by no legend entry and no state fill, so it can never be mistaken for data. Pane keys are
+props, never data-driven — an unresolvable `up.key` used to hide the pane AND its axis, which reads
+as "that half measured zero".
 
 `ZonedLine` and `MultiLine` also accept `xZones?: XZoneSpec[]` — the vertical counterpart to a
 kind's horizontal zone bands, for marking a time window rather than a value range. Each
@@ -477,6 +531,23 @@ margin. Passing `y2` to get a dual-axis chart no longer needs a manual margin nu
 The escape hatch is `margin={{ left: n }}` (`Partial<ChartMargin>`) on `CartesianChart` — a per-side
 override applied LAST, after measurement, so it always wins.
 
+**A band plot has one extra law, because a band axis puts its FIRST tick on the plot's left edge.**
+With no left axis to measure, `autoMargin` stops at `VX.margin.left` and half the first x label
+hangs off the canvas — so `BandStrip` floors its left gutter at half the widest x label, mirroring
+what `autoMargin` already does on the right. Both terminal gutters are then capped (14% of width
+left, 12% right): uncapped, half a `DD.MM HH:MM` label is 48px of a 338px chart. `MirroredBars`
+probes real tick labels from both panes, so it takes the plain measured margin and neither the
+floor nor the cap applies.
+
+**The height law is the number you actually have to compute.** A band row is
+`height − legend − margin.top − margin.bottom`: `ChartFrame` reserves the measured legend band out
+of the plot rect first, then the kind takes the margins out of what is left. There is no
+`bandHeight` prop — to get a 44px band, hand the frame `44 + margins + legend`. `margin={{ top: 0 }}`
+reclaims the whole top gutter, which a 1-D strip draws nothing in; the bottom is not reclaimable,
+`autoMargin` floors it at `VX.margin.bottom`. Derive the constants from `VX.margin` rather than
+restating them — a consumer that copies `30` into three chart files has three silent-drift sites the
+moment the density scale is retuned.
+
 `chartMargin(opts?)` (`basalt-ui/tokens`, also re-exported from `basalt-ui/charts`) still exists,
 but only matters for a bespoke chart that composes `ChartFrame` directly (not `CartesianChart`) and
 needs a right-axis-sized margin without running its own measurement pass — `DualPanel` and `Heatmap`

package/agent/rules/basalt-content.md

@@ -1,6 +1,6 @@
 ---
 source: basalt-ui
-description: Content/prose surface from basalt-ui/content — Prose, CodeBlock, Callout, TableOfContents, ReadingProgress, Markdown (streaming-aware), MermaidDiagram, MDX component map, ArticleLayout, ArticleCard/Grid, GuideLink/GuideDrawer, and the content-collections + TanStack Start recipe. Mantine-coupled (docs/CONTENT-SPEC.md in the basalt-ui repo).
+description: Content/prose surface from basalt-ui/content — Prose, CodeBlock, Callout, TableOfContents, ReadingProgress, Markdown (streaming-aware), MermaidDiagram, MDX component map, ArticleLayout, ArticleCard/Grid, GuideLink/GuideDrawer, and the content-collections + TanStack Start recipe. Mantine-coupled.
 paths:
   - 'src/content/**'
   - 'apps/**/src/**/*content*'
@@ -253,7 +253,7 @@ step 3).
 surface (`basalt-ui/commands`) — the same tier as `toRouteActions`. It joins title, description,
 category, tags, and slug into a `keywords` string for substring search; it does not tokenize, rank,
 index, or persist. An app that outgrows substring matching over a client-side array brings its own
-search index — see docs/CONTENT-SPEC.md §9 (Non-goals) in the basalt-ui repo.
+search index — see <https://github.com/jkrumm/basalt-ui/blob/master/docs/CONTENT-SPEC.md> §9 (Non-goals), which is not in the package.
 
 `ArticleGrid` stays a dumb layout wrapper — deliberate, so callers keep composition (sorting,
 filtering, and pagination all happen above it, not inside it).
@@ -406,4 +406,4 @@ const articleActions = toRouteActions(
 
 KaTeX/math, full mermaid grammar bundling (d2, pintora), Vega-Lite streamed specs, versioned docs/
 i18n routing, and a `create-basalt-docs` scaffold are all out of scope for 1.0 — see
-`docs/CONTENT-SPEC.md` §9 in the basalt-ui repo for the full non-goals list and rationale.
+<https://github.com/jkrumm/basalt-ui/blob/master/docs/CONTENT-SPEC.md> §9 for the full non-goals list and rationale (not in the package).

package/agent/rules/basalt-mantine.md

@@ -30,15 +30,15 @@ renders.
 
 - Use `createBasaltTheme(overrides?)` for the theme — it merges your overrides over `baseTheme`
   (last-wins), so you can retune any field without forking. Don't hand-build `createTheme`.
-- The theme reskins **every** Mantine accent to the modern-zinc identity (`docs/DESIGN-SPEC.md` in
-  the basalt-ui repo) —
+- The theme reskins **every** Mantine accent to the modern-zinc identity (long form:
+  <https://github.com/jkrumm/basalt-ui/blob/master/docs/DESIGN-SPEC.md>, not shipped in the package) —
   **cool-neutral zinc** ramps on both light and dark — plus a **single saturated sky-blue accent**
   — split by role: as INK (links, active-nav icon, chart lines, focus ring) `#0077bd` light /
   `#8ec5ff` dark; as a FILLED SURFACE `#0077bd` in BOTH schemes with a white label — and binds
   Mantine's surface vars AND its color families to the same `--vx-*` tokens
   the charts use (`cssVariablesResolver`, pre-wired in `BasaltProvider`), so chrome and charts share
   one scheme-reactive identity. (Blueprint / Basalt zinc-charcoal are the historical hue-tuning
-  ancestors; `docs/DESIGN-SPEC.md` in the basalt-ui repo supersedes both.) Don't add a second
+  ancestors; DESIGN-SPEC supersedes both.) Don't add a second
   `cssVariablesResolver`.
 - Color scheme: read/write via `useMantineColorScheme()`. **Never** read the color scheme from
   localStorage directly, and never `localStorage.getItem('theme')` — see basalt-state.md.
@@ -220,7 +220,7 @@ shape doctrine lives here; the spacing/radius/type **tokens** are in basalt-toke
   Mechanically enforced by `basalt-ui check-theme`'s `raw-surface` guard. Outer spacing comes from the
   parent `Stack`/`SimpleGrid` gap, not an intrinsic card margin.
 - **Depth = a whisper shadow with a 1px ring baked in, not a plain hairline** (see
-  `docs/DESIGN-SPEC.md` in the basalt-ui repo, doctrine inversion #1 — this supersedes the old
+  <https://github.com/jkrumm/basalt-ui/blob/master/docs/DESIGN-SPEC.md>, doctrine inversion #1 — this supersedes the old
   "never a drop shadow" rule). **Three depth tiers, split control-vs-panel-vs-floating:**
   - **`shadow-card` — panels.** A surface that HOLDS content: `Card`, `Paper`, `Notification`,
     `ChartCard`, `SettingsSection`. Its light-mode ring is an **outset** 1px hairline; dark is a

package/agent/rules/basalt-tokens.md

@@ -10,7 +10,8 @@ paths:
 # Basalt Tokens — Color, Spacing, Radius, Type
 
 basalt-ui ships one color/type/spacing/radius identity shared by the Mantine chrome and the visx
-charts. The **identity is modern zinc** (see `docs/DESIGN-SPEC.md` in the basalt-ui repo) —
+charts. The **identity is modern zinc** (long form: <https://github.com/jkrumm/basalt-ui/blob/master/docs/DESIGN-SPEC.md>, which does not ship in the
+package) —
 **cool-neutral zinc surfaces**
 (Tailwind zinc family) on both light and dark, low-contrast panel lift on a slightly darker page,
 depth via a whisper shadow + 1px ring (`shadow-card` on panels, `shadow-raised` on interactive
@@ -21,8 +22,7 @@ lines, focus ring) it is `#0077bd` light / `#8ec5ff` dark; as a FILLED SURFACE i
 `#0077bd` in BOTH schemes with a WHITE label (`--vx-accent-fill`, never `--vx-accent`). Neutrals do ~90% of the
 surface (60/30/10, pushed toward 90/10); the accent only points — primary CTA, focus, links, small
 status pops — never floods. (Blueprint/Basalt zinc-charcoal are the historical hue-tuning
-ancestors; `docs/DESIGN-SPEC.md` in the basalt-ui repo supersedes both — see its "Doctrine
-inversions" section.) This
+ancestors; DESIGN-SPEC supersedes both — see its "Doctrine inversions" section.) This
 rule is the operational checklist; it is enforced mechanically by **`basalt-ui check-theme`**
 (wire it into `lint`: `oxlint . && basalt-ui check-theme`; `init` seeds that as `lint:basalt`). A
 violation fails the build. Escape hatch: a scoped `theme-allow <rule-id> — <reason>` comment
@@ -96,6 +96,22 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
   still ends the block; that is how you say "this comment is not about the next statement".
 - **`basalt/hand-rolled-plot` grants whole-file immunity only through `theme-allow-file`.** Every
   assembly node is otherwise waived on its own.
+- **Eight shapes are asserted NOT to waive, in both halves.** They are pinned as unsupported rather
+  than merely left out, so "unsupported" and "silently broken" stop reading the same. Don't write
+  them:
+
+  | Shape                                                                                                                              | Why it does not waive                                                                                               |
+  | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+  | a blank line between the annotation and the code — after `//`, after `{/* */}`, or after a `{/*` whose closer sits on its own line | a blank line is how you say "this comment is not about the next statement"                                          |
+  | the token mid-sentence in a line comment, a docblock gutter, or a JSX expression comment                                           | prose that MENTIONS the token is not an annotation — the reason it must START its comment                           |
+  | the token inside a string literal                                                                                                  | same                                                                                                                |
+  | above a multi-line OPENING tag, when the finding sits on a later attribute line                                                    | a waiver reaches the first line below its comment, not an arbitrary line further down — put it beside the attribute |
+
+  The whole grid — four axes, comment style × token position × where the closer falls × what
+  follows — is pinned row for row in `src/guard/check-source.test.ts` (37 supported + these 8) and
+  `configs/oxlint-plugin.test.ts` (32 + 8; five of the guard's rows are CSS/HTML/JSON dialects
+  oxlint never sees). Zero disagreements between the two, and no waiver tally moved in any of the
+  seven consumer repos.
 
 ### Audit them: `basalt-ui check-theme --audit-allows`
 
@@ -104,13 +120,26 @@ the guard with that one occurrence neutralized, so the verdict comes from the sc
 parsing the waiver's text:
 
 ```text
+theme-allow annotations (3):
 src/shell/x.tsx:42    suppresses raw-surface@43
 src/theme/y.ts:18     SUPPRESSES NOTHING — dead, delete it
-src/charts/z.tsx:7    scoped to hand-rolled-plot — not a check-theme kind, so this audit cannot judge it
+src/charts/z.tsx:7    suppresses hand-rolled-plot@8 (oxlint)
+
+basalt.exemptRules entries (1):
 raw-hex: "site.webmanifest"  suppresses findings in public/site.webmanifest — <the recorded reason>
+
+3 live, 1 dead, 0 unjudgeable, 0 unaccountable (reported as theme-allow-unscoped by a normal run).
+Scope: the N file(s) check-theme scans — everything under basalt.roots (…), plus each root's
+sibling index.html and public/ tree, plus anything named in basalt.include (none). …
 ```
 
-It closes with a `live / dead / outside reach / unaccountable` tally and **exits 1 on a dead
+**Two sections, not one list** — annotations first, then `basalt.exemptRules`, each with its own
+count. A plugin-rule annotation is judged too (since 1.22.0, by re-running oxlint over one
+neutralized sibling file), so `unjudgeable` now means only "names no rule at all" or "oxlint could
+not be run here" — never "not a check-theme kind". The scope line is part of the report: `0 dead`
+is not `0 dead anywhere`.
+
+It closes with a `live / dead / unjudgeable / unaccountable` tally and **exits 1 on a dead
 waiver**, so it wires into CI. A waiver that stopped covering anything is not harmless: it silently
 covers the next real finding on that line. Basalt's own source had one; it is deleted.
 
@@ -141,7 +170,7 @@ nothing is forked.
 - **Exact name match only** — the one limit that is structural. Round 5 confirmed the miss rate:
   linewatch's forks are named `Cell` and `Box`, rb's is `Stat`. Rename the fork and the rule goes
   quiet, which is what a fork's author naturally does.
-- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.21.1 the rule
+- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.22.0 the rule
   gates on `isBasaltScopedFile` like every other rule in the file, and needs a function, an arrow, a
   `memo`/`forwardRef` wrapper or a class extending one. A plain data class sharing a name with a
   shipped export is a collision, not a fork — it fired on a `SlugTracker` class in a React-free

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

@@ -6,18 +6,26 @@ when_to_use: User is adding basalt-ui to a new or existing app, asks how to set
 
 `/basalt-app` scaffolds a basalt-ui consumer and keeps its shipped doctrine fresh. It wraps the two
 CLI subcommands — `basalt-ui init` (first run) and `basalt-ui sync` (refresh) — and explains the
-wiring they don't do for you (provider, shell, vite). All of it via `bunx basalt-ui` (Bun runtime).
+wiring they don't do for you (provider, shell, vite). Bun runtime.
 
 ## One package, one command, one version
 
 Everything ships in the `basalt-ui` npm package — components, toolchain presets, rules, skills,
 templates. Becoming a consumer is exactly two steps:
 
-```
+```bash
 bun add basalt-ui
-bunx basalt-ui init
+bunx basalt-ui init            # `init` is the ONE command that legitimately predates the install
+./node_modules/.bin/basalt-ui --version   # every command after it: the LOCAL bin
 ```
 
+**After `init`, never `bunx`.** `bunx` does not re-resolve a package it has cached, so it can run
+a months-old CLI against a freshly-pinned install and report a green gate you did not configure —
+which is exactly how one consumer filed a P0 against a 1.20.0 cache while believing it was on
+1.22.0. Use `./node_modules/.bin/basalt-ui` (or a `package.json` script, which `bun run` resolves
+from the same place). `basalt-ui --version` / `-v` prints one bare line and exits 0; that is the
+check, and it costs nothing to run first.
+
 There is no plugin and no marketplace. `init`/`sync` place every file with one of two modes, and
 which mode a file gets answers a single question — **does Claude read it?**
 
@@ -130,7 +138,7 @@ The consumer series file (`<first basalt.root>/lib/series.ts` by default — so
 a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is
 the single guard-exempt palette source — see `/basalt-charts`.
 
-## Refresh: `bunx basalt-ui sync`
+## Refresh: `basalt-ui sync`
 
 `sync` re-applies shipped doctrine after a basalt-ui upgrade, three-way against
 `.basalt/manifest.json`:
@@ -158,14 +166,15 @@ both.
 ## Checklist
 
 - Ran `bun add basalt-ui && bunx basalt-ui init` — rules, skills, CLAUDE block, DESIGN.md all
-  present from the one package.
+  present from the one package. Every command after it runs the local bin, not `bunx`.
 - `BasaltProvider` wraps the app; `createBasaltTheme` used for theme deltas; `basalt-ui/styles.css`
   imported.
 - `basaltViteConfig` adopted; `oxlint . && basalt-ui check-theme` is the lint command.
-- `basaltAppPlugin` composed into `plugins` (see the vite.config.ts snippet above); icon files
-  (`favicon.ico`, `favicon.svg`, `favicon-96x96.png`, `apple-touch-icon.png`,
-  `web-app-manifest-192x192.png`, `web-app-manifest-512x512.png`) generated and placed under
-  `public/` — `basalt-ui doctor` warns if any are missing.
+- `basaltAppPlugin` composed into `plugins` (see the vite.config.ts snippet above); either the six
+  default icon files (`favicon.ico`, `favicon.svg`, `favicon-96x96.png`, `apple-touch-icon.png`,
+  `web-app-manifest-192x192.png`, `web-app-manifest-512x512.png`) under `public/`, or an `icons`
+  array naming the ones you actually have. `doctor` reads the option out of your vite config, so an
+  app that names one SVG is not told to generate five PNGs it does not want.
 - `site.webmanifest` is emitted by `basaltAppPlugin` — no manual manifest file needed unless
   `manifest: false` was passed.
 - A thin `DESIGN.md` (deltas) + the thirteen `basalt-*` rules + the managed CLAUDE block are present.
@@ -179,14 +188,18 @@ both.
 - `init`, `sync`, and `check-theme` are all **real**. `sync` reconciles via a sha256 three-way diff
   (`--check` is a CI drift gate, `--force` overwrites local edits); `check-theme` is the palette
   guard; `doctor` checks resolution, version, guard scan, oxlint preset, spacing-scale drift and
-  cross-package `ai` major parity. All via `bunx basalt-ui …`.
-- **Not a React app?** `bunx basalt-ui tokens:css --out src/tokens.css` emits the `--vx-*` layer with
+  cross-package `ai` major parity. All via the local bin. An unrecognized flag exits 1 naming it
+  (`doctor --json` used to run doctor and exit 0), and an unknown command says so above the usage
+  block.
+- **Not a React app?** `bunx basalt-ui tokens:css --out src/tokens.css` (no install to resolve, so
+  `bunx` is right here) emits the `--vx-*` layer with
   no package in your dependency tree, `--selector-class dark` for the Tailwind `<html class="dark">`
   convention, and `fonts:css` emits the shipped `--basalt-font-*` stacks. Both carry the two-line
   `@generated basalt-ui` header the guard skips on — that header verbatim, and then only the LINES
   that are basalt custom properties, selectors, `}` or self-closing comments, so the marker pasted
   into a `.tsx` suppresses nothing and a declaration added to such a file is still reported — and
-  both take `--check` as a CI drift gate. See `docs/FRAMEWORK-FREE.md` in the basalt-ui repo.
+  both take `--check` as a CI drift gate — which compares everything but the header's provenance
+  line, so a basalt-ui version bump alone never forces a no-op commit. See <https://github.com/jkrumm/basalt-ui/blob/master/docs/FRAMEWORK-FREE.md> (not in the package).
 - The framework ships **no** icon or notification dep — pass icons as `ReactNode` and wire toasts
   yourself (e.g. `ThemeLabControls`' `copyIcon` / `onCopy`).
 - The framework DOES ship `motion` (motion.dev, formerly framer-motion) as a bundled dependency —

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

@@ -7,8 +7,10 @@ when_to_use: User wants to add a chart, restyle an existing one structurally, in
 `/basalt-charts` is the how-to for the chart system. `/basalt-design` owns the aesthetic law
 (palette, restraint, the theme-lab loop) and the DESIGN.md precedence — read it for "what color /
 how should this look". This skill answers "how do I wire it" with basalt-ui's `./charts` and
-`./tokens` surfaces. `docs/CHARTS-SPEC.md` is the ground truth for the chart-primitive contract
-everything below assumes — composing `CartesianChart` (single-plot) or `ChartFrame` directly
+`./tokens` surfaces. `.claude/rules/basalt-charts.md` — which you have — is the chart-primitive
+contract everything below assumes (the repo's `docs/CHARTS-SPEC.md` is the long form and is not in
+the package:
+<https://github.com/jkrumm/basalt-ui/blob/master/docs/CHARTS-SPEC.md>) — composing `CartesianChart` (single-plot) or `ChartFrame` directly
 (multi-pane/radial/matrix) is mandatory, mechanically enforced (see "Respect the boundary" below).
 
 ## The decision: kind vs bespoke (Rule of Three)
@@ -16,9 +18,9 @@ everything below assumes — composing `CartesianChart` (single-plot) or `ChartF
 Before writing chart code, decide which of three paths you are on:
 
 1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`,
-   `DualPanel`, `Heatmap`, `Donut`. If the shape matches, use it — props are declarative (`data`,
-   `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per axis, zones/thresholds/refLines
-   as plain arrays). Done.
+   `DualPanel`, `Heatmap`, `Donut`, `BandStrip`, `MirroredBars`. If the shape matches, use it —
+   props are declarative (`data`, `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per
+   axis, zones/thresholds/refLines as plain arrays). Done.
    - **`ZonedLine`** — a single-series line with zone bands, thresholds, x-zones, refLines.
    - **`Bars`** — 1+ stacked positive/negative bar series, optional line overlays, dual-axis config.
    - **`StackedArea`** — opaque stacked bands, auto cumulative-top y-domain.
@@ -33,6 +35,13 @@ Before writing chart code, decide which of three paths you are on:
    - **`Heatmap`** — category×category intensity grid (`color-mix` alpha), per-cell tooltip,
      optional gradient legend strip. Replaces bespoke time-of-day.
    - **`Donut`** — proportional donut, optional `centerContent` overlay.
+   - **`BandStrip`** — 1-D categorical bands, no y dimension: one rect per slot,
+     `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` is the state set and
+     drives legend, fill and the one derived tooltip row. Replaces a bespoke state/availability
+     strip.
+   - **`MirroredBars`** — two BAR panes over one x scale and one baseline, each in its own domain
+     (`up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`). Not `DualPanel`, whose top
+     pane is a LINE and whose bottom takes one SIGNED accessor.
 2. **Extract a new kind (second instance of a pattern).** When you are about to build the _second_
    chart of a shape that has no shipped kind, extract a kind. Don't extract on the first; don't
    wait past the third. A new kind lives in the consumer's chart kinds dir (or, if generic enough
@@ -43,6 +52,12 @@ Before writing chart code, decide which of three paths you are on:
    genuinely different scales that don't fit any kind's config surface) composes `CartesianChart`
    or `ChartFrame` directly in the page's chart file — not in `kinds/`.
 
+**Extracting a kind? Prove it by porting.** A kind is proven by moving a real consumer's call
+sites onto it and reporting what it could NOT express — not by a demo page, which is written
+against the API that already exists. The two band kinds were built that way (linewatch, 1884 → 957
+source lines, 11 `hand-rolled-plot` waivers retired, two live `NaN`-geometry bugs found). Ship the
+"still cannot express" list with the kind.
+
 > Anti-pattern: a single `<Chart type="..." config={...} />` god-component that switches by kind.
 > That is the Recharts trap. Prefer N small kinds. **If a chart doesn't fit the primitives, add a
 > kind — don't loosen the primitives.**
@@ -109,8 +124,9 @@ Theme tuning of these series happens in the theme lab — pass them as `groups`
 ## Compose the primitives (never hand-roll)
 
 Every chart — kind or bespoke — composes `CartesianChart` for a single plot rect, or `ChartFrame`
-directly for a multi-pane / non-cartesian shape (`DualPanel`'s two panes, `Heatmap`'s grid,
-`Donut`'s ring). Either way the contract is the same: the primitive owns margin, scales, grid,
+directly for a multi-pane / non-cartesian shape — five of them ship: `DualPanel`'s two panes,
+`MirroredBars`' two bar panes, `BandStrip`'s missing y dimension, `Heatmap`'s grid, `Donut`'s ring.
+Either way the contract is the same: the primitive owns margin, scales, grid,
 axes, legend, the shared cursor, and the tooltip; you supply `series` and draw ONLY marks. This is
 mandatory, not a convention — `basalt/hand-rolled-plot` fails the build on a bypass (see "Respect
 the boundary" below); it is easier to compose it than to work around it.
@@ -212,9 +228,10 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
   rendered in a file that doesn't compose `CartesianChart`, per NODE. Escape:
   `theme-allow hand-rolled-plot — <why>` on the one node, or `theme-allow-file hand-rolled-plot —
-<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`,
-  `Donut`) declares itself. `-file` is the 1.21.0 spelling and it is required. The file that defines
-  `CartesianChart` is exempt definitionally.
+<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `MirroredBars`,
+  `BandStrip`; `Heatmap` and `Donut` render no assembly primitive and need none) declares itself.
+  `-file` is the 1.21.0 spelling and it is required. The file that defines `CartesianChart` is
+  exempt definitionally.
 - **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
   array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws
   (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no

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

@@ -12,8 +12,9 @@ Colors come from the three-tier `--vx-*` token system — read `VX.*` / a `defin
 never a raw hex/`rgb()`/`hsl()`. Charts are visx via `basalt-ui/charts`: every single-plot chart
 composes `CartesianChart` (owns margins, scales, axes, grid, cursor, tooltip — draw only marks);
 legends/tooltip rows are DERIVED from `series`, never hand-authored (`basalt/hand-rolled-plot` +
-`basalt/chart-legend-literal` enforce both); `DualPanel`/`Donut`/`Heatmap` are the declared
-exceptions. Add a kind on the third repeat, don't loosen the primitives. `basalt-ui/charts` and
+`basalt/chart-legend-literal` enforce both); `DualPanel`/`BandStrip`/`MirroredBars` declare
+themselves exceptions, and `Donut`/`Heatmap` render no plot-assembly element so the rule never
+fires on them. Add a kind on the third repeat, don't loosen the primitives. `basalt-ui/charts` and
 `basalt-ui/tokens` are Mantine-free internally (a framework invariant, not something your own app
 code must follow) — never import `@visx/*` outside a `charts/` directory (oxlint-enforced).
 Toolchain is oxlint + oxfmt (no ESLint/Biome/Prettier) and `basalt-ui check-theme` guards the

package/agent/templates/DESIGN.md.tpl

@@ -1,6 +1,8 @@
 # {{APP_NAME}} — Design
 
-> Managed by basalt-ui ({{BASALT_VERSION}}). This is a **thin** instantiation — it records this
+> Managed by basalt-ui — run `basalt-ui doctor` for the version, never trust a number written into
+> a file (this one is a seed: written once at `init`, then owned by you, so any version stamped
+> here would be frozen at scaffold time). This is a **thin** instantiation — it records this
 > app's **deltas only** on top of the shipped `basalt-*` rules. The universal law (earned color,
 > neutral-by-default, three-tier `--vx-*` tokens, theme-is-data, the chart primitive contract, the
 > elevation/density/shape doctrine) lives in those rules and the `/basalt:design` skill, and is

package/configs/oxlint-plugin.js

@@ -245,8 +245,49 @@ function allComments(context) {
 }
 
 /**
- * True when a NODE-scoped `theme-allow` covering `ruleId` sits on `node`'s own source line or the
- * line above — or when the file carries a `theme-allow-file` declaration for it.
+ * Every comment that REACHES `nodeLine` — the comment on the node's own line, the one directly
+ * above it, and any further comment separated from that one by nothing but comment.
+ *
+ * This is the plugin's half of "which node does this annotation scope to", and it has to answer the
+ * same question `src/guard`'s forward walk answers: **an annotation reaches the first line below its
+ * comment that is not itself comment.** The test used to be a flat `end.line === nodeLine ||
+ * nodeLine - 1`, which is the same rule only when the annotation is the LAST comment above the node
+ * — so anything sitting between the annotation and the node, comment included, was reported here
+ * while the guard waived it:
+ *
+ * ```text
+ * // theme-allow raw-hex — the vendor brand hex, kept in sync with     ← a reason that wrapped
+ * // the marketing site's own palette                                     onto a second comment
+ * const BRAND = '#ff0000'
+ *
+ * {/* theme-allow card-inset — … *\/}
+ * {/* 3. the density row *\/}                                            ← an unrelated note
+ * <Card p={0} />
+ * ```
+ *
+ * The wrapped-reason one is not hypothetical: it is pinned in the guard's tests as a shape argo
+ * writes. A blank line still separates, because a blank line is not comment — which is what makes
+ * "this comment is not about the next statement" expressible in both halves.
+ *
+ * Returned bottom-up, which is also the cheap order to walk: stop at the first gap.
+ */
+function reachingComments(context, nodeLine) {
+  const comments = allComments(context).toSorted((a, b) => a.loc.start.line - b.loc.start.line)
+  const out = []
+  let reach = nodeLine
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const comment = comments[i]
+    if (comment.loc.end.line > nodeLine) continue
+    if (comment.loc.end.line < reach - 1) break
+    out.push(comment)
+    reach = Math.min(reach, comment.loc.start.line)
+  }
+  return out
+}
+
+/**
+ * True when a NODE-scoped `theme-allow` covering `ruleId` reaches `node` (see
+ * {@link reachingComments}) — or when the file carries a `theme-allow-file` declaration for it.
  *
  * The `ruleId` argument is what stops one exemption from being a blanket one: a `theme-allow
  * raw-hex — …` written for a color no longer silently switches off `card-inset` on the same line.
@@ -254,13 +295,11 @@ function allComments(context) {
  */
 function hasThemeAllow(context, node, ruleId) {
   if (hasFileDeclaration(context, ruleId)) return true
-  const nodeLine = node.loc.start.line
-  return allComments(context).some((comment) => {
-    if (comment.loc.end.line !== nodeLine && comment.loc.end.line !== nodeLine - 1) return false
-    return parseThemeAllows(comment.value).some(
+  return reachingComments(context, node.loc.start.line).some((comment) =>
+    parseThemeAllows(comment.value).some(
       (allow) => allow.scope === 'line' && allowCovers(allow, ruleId),
-    )
-  })
+    ),
+  )
 }
 
 /**
@@ -535,10 +574,12 @@ const cardInset = {
 // ── Rule 3 — chart-in-raw-surface ───────────────────────────────────────────────────────────────
 
 const CHART_TAGS = new Set([
+  'BandStrip',
   'Bars',
   'Donut',
   'DualPanel',
   'Heatmap',
+  'MirroredBars',
   'MultiLine',
   'StackedArea',
   'ZonedLine',