basalt-ui 1.23.0 → 1.23.1

package/AGENTS.md

@@ -62,29 +62,38 @@ duration/spring/ease literal in a `transition={{...}}` prop (enforced by `basalt
 
 ## Key commands
 
+`init` and `tokens:css`/`fonts:css` are the only commands with no install to resolve, so `bunx` is
+correct for them and wrong for everything else — see the note below.
+
 ```bash
-bunx basalt-ui init              # FIRST STEP: scaffold .claude/rules/ + .claude/skills/, managed CLAUDE.md block, DESIGN.md seed, toolchain seeds
-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            # 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
+bunx basalt-ui init         # FIRST STEP: scaffold .claude/rules/ + .claude/skills/, managed CLAUDE.md block, DESIGN.md seed, toolchain seeds
+basalt-ui --version         # one bare line, exit 0 — which CLI is actually running (also -v / version)
+basalt-ui check-theme       # fail on off-palette colors in consumer source
+basalt-ui sync              # reconcile managed files (.claude/rules/, .claude/skills/, CLAUDE.md block)
+basalt-ui sync --check      # CI freshness gate — exits non-zero if any managed file drifted
+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
+basalt-ui info --json       # stable JSON surface map
+basalt-ui guard-hook        # PreToolUse theme-guard adapter: reads a Write/Edit payload on stdin, denies off-palette writes
 ```
 
+Every subcommand rejects a flag it does not accept, exiting 1 and naming it; an unknown command says
+so above the usage block. Neither is ever ignored — `doctor --json` used to run doctor and exit 0.
+
 `check-theme`, `doctor` and `sync` resolve their project identically: `BASALT_CWD` wins, then the
 cwd, then the workspace packages the root declares, then a two-level layout scan (which is what a
 repo with no `workspaces` field and the install one level down needs). Two candidates is ambiguous
 and reported, never guessed. `sync` on a `tokens-only` consumer prints `n/a` and exits 0.
 
-**Checking what an upgrade actually does? Run the local bin, not `bunx`.** `bunx` does not
-re-resolve a cached package, so it can execute the version you just upgraded away from.
+**Run the local bin, not `bunx`.** `bunx` does not re-resolve a cached package, so it can execute
+the version you just upgraded away from — one consumer filed a P0 against a 1.20.0 cache while
+believing it was on 1.22.0. `init` and `sync` render every seeded script, CI step and hook with the
+resolved local bin for this reason (`BASALT_BIN` overrides it). `basalt-ui --version` is the
+one-second check.
 
 Register `guard-hook` in `.claude/settings.json` under `hooks.PreToolUse` with matcher
-`Write|Edit|MultiEdit` and command `bunx basalt-ui guard-hook` so the agent can't write off-palette
+`Write|Edit|MultiEdit` and command `./node_modules/.bin/basalt-ui guard-hook` (what `init` seeds) 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 and to that one

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [1.23.1](https://github.com/jkrumm/basalt-ui/compare/v1.23.0...v1.23.1) (2026-08-22)
+
+
+### Bug Fixes
+
+* gate the two chart tag rules on where the tag came from ([0075224](https://github.com/jkrumm/basalt-ui/commit/007522416bf9a3269e5f45b7ae7f45203434bae7))
+* make the CLI answer which version ran, and stop it failing open ([0edf50e](https://github.com/jkrumm/basalt-ui/commit/0edf50e1d6f61b349f989fd10fe384d4a91a9af1))
+* stop a typo'd band state from asserting absence ([6c1515c](https://github.com/jkrumm/basalt-ui/commit/6c1515c3ecbf019d9971e5b247e81e5cce3ae316))
+
 # [1.23.0](https://github.com/jkrumm/basalt-ui/compare/v1.22.0...v1.23.0) (2026-08-22)
 
 

package/MIGRATING.md

@@ -8,9 +8,10 @@ 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. **Every replacement below
 was re-audited against the built declaration files at 1.20.0 (2026-08-22)** after round 5 caught one
-row that was wrong. That pass corrected 4 table rows and 3 prose claims. The 1.21.0, 1.22.0 and
-`Unreleased` sections were written against source, not against their commit messages. Check the
-types, not this table, if the two disagree.
+row that was wrong. That pass corrected 4 table rows and 3 prose claims. Every section from 1.21.0
+on was written against source, not against its commit messages — which is not a formality: one
+1.23.0 commit message describes a change it did not make (see `Unreleased` § Corrections). Check
+the types, not this table, if the two disagree.
 
 **The newest section is headed `## Unreleased`, and stays that way until npm serves it.** This file
 is written before `semantic-release` picks the number, so a number written here is a guess — and it
@@ -39,6 +40,85 @@ version `CHANGELOG.md` does not record. This file is not in that set; the same d
 by convention. Rename the section at release, or leave it — a reader can resolve `Unreleased`
 against `CHANGELOG.md`, and could never resolve `1.21.1`.
 
+**One type widened, nothing removed or renamed.** `BandStripSeries.formatValue` is now
+`(d: T) => string | null`. `null` renders an em dash — an absent READING — which `''` never could:
+`''` is a state whose label is the whole row. Every existing `(d) => string` still typechecks.
+
+**A typo'd `BandSpan.state` no longer renders as absence.** A state naming no `series` entry used to
+be skipped, so the band was simply not drawn — and on a measured/not-measured strip a missing band
+is a claim about the data, not an "unknown". A misspelling asserted a reading nobody took, in a mark
+indistinguishable from a real one.
+
+| Key comes off                                                 | Dev                                      | Production                                                               |
+| ------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| the DATUM — `BandSpan.state`, `marker.state`                  | throws, naming the key and the valid set | a dashed neutral outline band + an `Unknown state` / `<key>` tooltip row |
+| a PROP — `absentState`, `MirroredBars`' `up.key` / `down.key` | throws                                   | throws                                                                   |
+
+The split is the whole design. `state` comes off data, so a feed that grows a state basalt has never
+seen must degrade rather than take a dashboard down — while a typo, which is the same input, still
+fails loudly wherever it is being written. The dashed neutral outline belongs to no legend entry and
+no state fill, so it cannot read as data. Pane keys are props, never data-driven, so `assertPaneKey`
+throws in every environment: an unresolvable `up.key` used to hide the pane AND its axis, which
+reads as "that half measured zero" — the one thing `MirroredBars` exists to keep apart from absence.
+
+**`chart-missing-aria-label` and `unframed-chart` are gated on where the tag came from.** Both key
+on a JSX tag NAME, so a consumer's own 235-line `MirroredBars` — sharing nothing with the shipped
+kind but the name — was told to pass an `ariaLabel` prop it does not accept, by a rule that presents
+as a correctness finding. A tag is now skipped only when the file DEFINES a component of that name
+and does not also import it from `basalt-ui`. Deliberately one-directional: a tag imported from
+basalt-ui, one imported from a consumer barrel that re-exports it, and one the scan cannot attribute
+at all still all fire. Verified old-vs-new over **945 source files across six repos: 0 findings
+lost, 0 gained.**
+
+**CLI: `--version` exists, and no subcommand fails open on a flag.** `--version` / `-v` / `version`
+print one bare greppable line and exit 0, resolved BEFORE dispatch so it can never run a command to
+answer "which basalt-ui is this". Six consumer reports reached for it in one round; all six fell
+back to `info --json`.
+
+The larger fix sits underneath it. **Every subcommand validates its flags** and exits 1 naming the
+one it does not accept — `doctor --json` used to run doctor and exit **0**, and `check-theme
+--audit-allow` scanned and reported success. An unknown COMMAND now says so above the usage block
+instead of dumping help and letting the dump read like a choice.
+
+- **`doctor` reads `basaltAppPlugin({ icons })`** out of the consumer's vite config instead of
+  hardcoding six filenames, so adopting 1.23.0's icons array stops producing a warning to generate
+  five files you deliberately lack. A named array is checked against itself (an icon missing from
+  `public/` still warns); an unparseable or absent config falls back to the six-filename check. It
+  can only narrow, never blind.
+- **`doctor` and `sync` share one sentence about a parent install** (`parentInstallAdvice`). Run
+  from a package whose install is above it, `doctor` now names the parent and says `basalt-ui init`
+  is NOT the fix. Following its old advice literally scaffolded the second consumer that 1.22.0
+  exists to prevent.
+- **Every seeded invocation resolves the local bin** (`basaltBinCommand`, overridable via
+  `BASALT_BIN`): the `lint` script, the CI steps, the `.claude` PreToolUse hook and doctor's own
+  advice all render `./node_modules/.bin/basalt-ui`. `bunx` does not re-resolve a package it has
+  cached — that is what made a round-7 report file a P0 against a 1.20.0 cache while believing it
+  was on 1.22.0, and the seed was shipping `bunx` into consumer CI in ten places.
+  `configs/lefthook.yml`'s `${BASALT_BIN:-bunx --no-install basalt-ui}` default is unchanged and
+  deliberate: `--no-install` fails loudly instead of downloading a stranger.
+- **`tokens:css --check` blanks the provenance line (line 2) before comparing**, so a version bump
+  alone no longer forces a no-op commit in a tokens-only consumer, where the gate is byte-equality.
+  A stale provenance line is now a note on an otherwise-passing check. The `@generated` header is
+  still emitted byte-identical — the line stays, it just stops gating.
+
+### Corrections to the record
+
+- **All six round-8 reports said `basalt-ui --version` "exits 0 printing usage". It exited 1, to
+  stderr** — the dispatcher's `default:` branch has always been `console.error(USAGE); return 1`.
+  The real fail-open was an unknown FLAG, which no report tested, and the misdiagnosis was relayed
+  verbatim into the fix brief. Report the symptom you measured, not the one you inferred from it.
+- **`cb4e5b7`'s message is wrong** (`b9b99a6` on `origin/feat/round-7-band-kinds` is the same commit
+  pre-merge), and it is on `master` where it cannot be rewritten. It claims it taught
+  `unframed-chart` the two new kinds; it widened `CHART_ENTRY_POINT_TAG`, which only
+  `chart-missing-aria-label` reads. `unframed-chart` keys on `<ChartLegend items={[` and carries no
+  kind list at all — there was never an asymmetric pair to fix.
+- **Open question, not a plan.** The import gate does not make `CHART_ENTRY_POINT_TAG` or the oxlint
+  plugin's `CHART_TAGS` redundant: that list still answers _which_ tags owe an `ariaLabel`. The gate
+  only converts a kind missing from the list from a false positive into an under-report. Collapsing
+  the two lists is a separate, larger change and has not been made.
+
+## 1.23.0 — two band kinds, an x-tick seam, CLI resolution
+
 **No export removed or renamed; six new runtime exports and nine new types.** Nothing you wrote
 changed. Every entry is additive, and the batch runs the other way from the last three: those made
 the guard stricter, this one makes the framework more expressive.
@@ -72,7 +152,9 @@ unchanged and still works; omit both and ticks are chosen to fit (`smartTicks`),
 Reach for it on a dense time axis: the tick choosers append the final key unconditionally, so a
 COUNT that does not land on the last index paints two labels on top of each other at the right edge
 — at every count, not at an unlucky one. On the consumer that reported it, the local tick helper
-went 200 → 160 lines; it shrinks, it does not disappear.
+went 200 → 170 lines; it shrinks, it does not disappear. (The promise was 160. The 10-line miss is
+docblock — the port's own JSDoc grew, because the helper stopped being a fallback and became the one
+seam every chart on the page passes through.)
 
 **`basaltAppPlugin`'s `icons` takes an array now.**
 

package/README.md

@@ -450,6 +450,16 @@ bar panes over one x scale and one baseline, each in its own domain. Both fold t
 width, hatch the share of a slot nothing measured, and share the page cursor like every other
 chart.
 
+On a strip, `series` IS the state set, so a `state` naming no entry has no colour, no legend entry
+and no tooltip row. It **throws in dev**, naming the key and the valid set; in production it draws a
+dashed neutral outline band — a treatment no legend entry and no state fill uses — plus an
+`Unknown state` tooltip row. Drawing nothing was the old behaviour and the wrong one: on a
+measured/not-measured strip a missing band claims a coverage gap. `absentState` and `MirroredBars`'
+`up.key`/`down.key` are PROPS rather than data, so those throw in every environment; an
+unresolvable pane key used to hide the pane and its axis, which reads as a measured zero.
+`BandStripSeries.formatValue` returns `string | null`, `null` rendering an em dash — an absent
+reading, distinct from `''`, which is a state whose label is the whole row.
+
 Which x ticks get painted is `xTickValues?: (keys, xMax) => readonly string[]`, on
 `CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine` and both band kinds.
 It resolves ahead of the `xTicks` COUNT, which is unchanged; omit both and ticks are chosen to fit.
@@ -694,19 +704,24 @@ Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `
 ## CLI
 
 ```bash
-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            # 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 init              # scaffold doctrine into a consumer repo — the one command with no install to resolve
+basalt-ui --version              # one bare line, exit 0 (also -v / version) — which CLI is actually running
+basalt-ui sync                   # three-way diff against .basalt/manifest.json after a basalt-ui upgrade
+basalt-ui sync --check           # CI drift gate — non-zero exit on any managed-file drift
+basalt-ui check-theme            # palette guard — fails on colors that bypass the central --vx-* system
+basalt-ui doctor                 # integration health: basalt-resolves, guard-scan, oxlint-preset, lefthook-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 an icon file basaltAppPlugin references and public/ does not have
+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
+basalt-ui info --json            # surface map as stable JSON (InfoOutput shape); bare `info` is the human-readable form
+basalt-ui help                   # full usage; every subcommand also takes --help / -h
 ```
 
+**Nothing fails open.** `--version` resolves before dispatch, so it can never run a command to
+answer which CLI ran. Every subcommand validates its flags and exits 1 naming the first one it does
+not accept — `doctor --json` used to run doctor and exit **0**, and `check-theme --audit-allow`
+scanned and reported success. An unknown command says so above the usage block.
+
 `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`, `doctor` and
 `sync` all resolve their project the same way**: `BASALT_CWD` wins, then the cwd itself, then the
@@ -715,13 +730,15 @@ ambiguous, never guessed. The scan is what a repo declaring **no `workspaces` fi
 the install one level down and nothing declaring it, every command answered about the root and
 found nothing there: `check-theme` printed "no off-palette colors" having scanned zero files, and
 `doctor` inferred `tokens-only` for a full Mantine consumer. `tokens:css` and `fonts:css` both take
-`--check` as a CI drift gate.
+`--check` as a CI drift gate, comparing everything but the header's provenance line — so a
+basalt-ui version bump alone never forces a no-op commit in a tokens-only consumer.
 
-**Verify an upgrade against the local bin, not `bunx`.** `bunx` does not re-resolve a package it
-has already cached, so a `bunx basalt-ui …` run can execute a version you upgraded away from —
-which is exactly how a fixed defect gets re-reported. Prefer `./node_modules/.bin/basalt-ui` (or
-`bun run` a script that does) when the point of the run is to check what the installed version
-does.
+**Run the local bin, not `bunx`.** `bunx` does not re-resolve a package it has already cached, so a
+`bunx basalt-ui …` run can execute a version you upgraded away from — which is how one consumer
+filed a P0 against a 1.20.0 cache while pinned to 1.22.0. `init` and `sync` now render every seeded
+script, CI step, hook and piece of doctor advice with the resolved `./node_modules/.bin/basalt-ui`
+(`BASALT_BIN` overrides it, and `configs/lefthook.yml` keeps `bunx --no-install` as a deliberately
+loud fallback). `basalt-ui --version` is the one-second check.
 
 `sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff);
 missing → recreate. `--force` overwrites local edits. The summary counts `created` and `recreated`
@@ -736,7 +753,9 @@ release.
 `check-theme` and `doctor` do, and since 1.22.0 **exits 1** when the resolved project has no
 `.basalt/manifest.json`, naming the install it found above instead of scaffolding a second one
 beside it. Run it at the package that holds the manifest, or point `BASALT_CWD` at that package.
-Creating an install is `basalt-ui init`'s decision.
+Creating an install is `basalt-ui init`'s decision — and `doctor` now says the same sentence from
+the same directory, where it used to prescribe `init` and so recommend the very scaffold that
+refusal exists to prevent.
 
 ---
 

package/agent/rules/basalt-app.md

@@ -193,7 +193,11 @@ web-app-manifest-512x512.png
 
 Generate the set with `@vite-pwa/assets-generator` (or realfavicongenerator.net) from a single
 source image — it lives in the CONSUMER's own devDependencies, not basalt-ui's. `basalt-ui doctor`
-warns (does not fail) when `public/` exists but is missing one of these files.
+warns (does not fail) when `public/` exists but is missing one of these files — and it now
+parses `basaltAppPlugin`'s `icons` option out of your vite config first, so it checks the files you
+declared rather than the six it assumes. `icons: false` or an empty array is "nothing to check"; an
+unparseable or absent config falls back to the six defaults. Adopting the array is no longer a way
+to earn a warning.
 
 **If your `public/` does not match those six filenames, name your icons instead.** `icons` takes
 `false | { dir?: string } | readonly BasaltAppIcon[]`, and an array uses the manifest's own field
@@ -217,7 +221,9 @@ One SVG at `sizes: 'any'` is a complete, installable icon set for a single-page
 shape every non-scaffolded consumer already has. If you keep a hand-written `manifest.webmanifest`
 only because the plugin could not name your icon, delete it: the generated manifest reproduces it
 member for member, including the two hexes derived from `SURFACE.bg` rather than hand-copied, and it
-takes the permanent `theme-allow-file` on that file with it.
+takes the permanent `theme-allow-file` on that file with it. **Delete that app's own
+`<link rel="manifest">` in the same change** — the plugin injects its own, so leaving both ships two
+manifest links pointing at different files, one of them a 404 the moment the hand-written file goes.
 
 `basaltAppPlugin` also emits `site.webmanifest` (served in dev too) with explicit `id`/`scope`/
 `start_url` — pass `manifest: false` to skip it, or `icons: false` to skip the icons. Since 1.22.0

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)
 
@@ -348,6 +350,8 @@ per-series `getValue` accessors on `ChartSeries<T>`):
   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;
@@ -360,6 +364,29 @@ Both band kinds fold their domain by width (`fold: { minBandPx?, merge }`), and
 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
 `{ from?, to?, fill, align? }` bound is a `getX` **domain key** (the label string the kind's
@@ -512,6 +539,15 @@ left, 12% right): uncapped, half a `DD.MM HH:MM` label is 48px of a 338px chart.
 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
@@ -120,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.
 

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)

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