basalt-ui 1.23.0 → 1.24.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `basalt-ui/charts`          | headless        | CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -62,29 +62,43 @@ 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 only while basalt is not installed here** — once it is, they run through the
+local bin like 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 ONLY if basalt is not installed
+bunx basalt-ui fonts:css    # emit the shipped --basalt-font-* stacks — same exception
+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.
+repo with no `workspaces` field and the install one level down needs), then an **ascend** to the
+nearest ancestor carrying a basalt project, bounded by the repo root. Both directions announce the
+relocation in one sentence — `check-theme` used to fabricate `roots: ["src"]` on the ascend path and
+pass silently. Two candidates is ambiguous and reported, never guessed. `sync` on a `tokens-only`
+consumer prints `n/a` and exits 0; from a sub-package it refreshes the parent install rather than
+refusing, and still will not scaffold a second consumer.
+
+**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,26 @@
+# [1.24.0](https://github.com/jkrumm/basalt-ui/compare/v1.23.1...v1.24.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* stop check-theme fabricating a config, and re-gate the provenance line ([99a45c0](https://github.com/jkrumm/basalt-ui/commit/99a45c0dc284850b4140a6ff7719dbade4795f09))
+* stop raw-hex reading HTML entities, and teach the guard the SFC dialect ([f1b0562](https://github.com/jkrumm/basalt-ui/commit/f1b0562efeb718921509253f9ee215bf461c3c01)), closes [#123](https://github.com/jkrumm/basalt-ui/issues/123) [#125](https://github.com/jkrumm/basalt-ui/issues/125)
+
+
+### Features
+
+* playground routes for QueryState and the table body chrome ([e150a00](https://github.com/jkrumm/basalt-ui/commit/e150a0051bf743137751a3d5c17f202c0984aaa7))
+* ship the query loading/error branch and the table body chrome ([963bf04](https://github.com/jkrumm/basalt-ui/commit/963bf047cf9ac4fac3cecceecbd0c378ee37f79d))
+
+## [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 `1.23.1` § 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,219 @@ 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`.
 
+**Nothing removed or renamed. Twelve new runtime exports on `.`/`./query`, plus table props.** Every
+API entry is additive; the behaviour changes are in the guard and the CLI, listed after them.
+
+### `QueryState` — the branch precedence, shipped as a component
+
+`QueryState`, `LoadingState`, `ErrorState` (+ `QueryStateProps`, `QueryStateLike`,
+`QueryStateVariant`, `QueryEmptyCopy`, `LoadingStateProps`, `ErrorStateProps`) on the root barrel,
+beside `EmptyState`. `toErrorMessage` and `errorStatus` on `basalt-ui/query`.
+
+basalt owned both ends of this file — `EmptyState` and `toErrorMessage` — and nothing in between, so
+a consumer wrote the four-way switch and got it wrong in the direction the shape suggested:
+image-share's library rendered `No images` on a **500** and a share detail rendered
+`Share not found` on a dropped connection, until 204 hand-rolled lines stopped it. Open since round
+4, re-reported in round 6.
+
+- **A component, not a hook** — the product IS the precedence, and a hook returns the same four-way
+  switch to every call site.
+- **It lives under `src/dashboard/`, not `src/query/`**: `check-dist-layering.mjs` asserts
+  `dist/query/index.js` reaches no `@mantine/*`, and this renders Mantine. `query` is typed as a
+  five-field structural subset (`QueryStateLike`), so basalt couples to no query-library version and
+  a hand-composed object is legal. The subset gives up the compiler, so the shape is asserted at
+  **runtime**: a missing `isError` throws naming the field, because a missing `isError` is precisely
+  the "500 renders _No images_" bug.
+- `errorTitle` / `errorFallback` / `errorAction` apply to the no-cached-data error branch only; the
+  error-with-cached-data branch renders a fixed section banner above `children`.
+- **`EmptyState.description` is now optional.** Five argo features wrapped the component solely
+  because a compact panel had to invent a second sentence. Existing calls are unaffected.
+- `toErrorMessage(err, fallback?)` and `errorStatus(err)` had two live bugs the port found: an
+  opaque envelope rendered the literal `"{}"`, and `toErrorMessage(undefined)` returned the
+  `undefined` VALUE despite a `string` return type. Both fixed; a status is folded into the fallback
+  when the body decodes to nothing readable. Split into `src/query/error-message.ts` so the
+  dashboard decodes without importing the peer.
+
+**Port result:** image-share, all 10 call sites plus a standalone `ErrorState`, **by changing one
+import line each** — no renames, no prop changes, no casts. Total 2467 → 2221; code-only 2056 →
+1882, **−174**; `query-state.tsx` 204 → 0.
+
+### `BasaltDataTable` body chrome — and the honest number
+
+New: `maxHeight`, `minWidth`, `stickyHeader`, `stickyHeaderOffset`, `verticalSpacing`,
+`horizontalSpacing`, `withRowBorders`, `withTableBorder`, per-column `meta.align` and
+`meta.numeral`; `striped` widens from `boolean` to `boolean | 'odd' | 'even'`. `withTableBorder`
+defaults to `true` in basalt, overriding Mantine's `false`; every other one is a conditional
+pass-through, so omitting it keeps Mantine's default.
+
+**Porting argo's three tables onto them made them 341 → 370 lines. 29 LONGER.** argo named these
+props as the reason the tables stayed hand-rolled, and adding them shortened nothing: column defs
+cost more than JSX rows when every cell is bespoke — eight accessor blocks at 4–6 lines each against
+an eight-`<Table.Td>` row at ~3. **The ask was mis-specified.** Adopt them for what they buy —
+the `type="native"` footgun, alignment stated once instead of on both `th` and `td` six times in one
+file, and sorting/filtering/pagination no longer consumer-owned — not for a line count. This is the
+counterexample to the band kinds, and the reason the port-before-shipping rule earns its keep.
+
+- `maxHeight` (or `minWidth`) renders **`Table.ScrollContainer type="native"`**, and
+  `agent/rules/basalt-data.md` now prescribes that same node for a bespoke table — so the blessed
+  lane and the escape cannot contradict, and `type="scrollarea"`, which breaks a sticky `thead`, is
+  unreachable through the props. (The prop's JSDoc claimed the docs already sanctioned it; they had
+  never named `Table.ScrollContainer` at all.)
+- `meta.align` is a `ColumnMeta` module augmentation: a typo'd key is a tsc error, a wrong value
+  throws naming the column. `meta.numeral` is read only as `!== false` — an opt-OUT of the
+  mono-numeral cell style, never an opt-in.
+- **Not shipped, known:** `emptyState` renders inside a `<td colSpan>` so the header row survives an
+  empty table — there is no `emptyState="replace"` mode. No per-column `enableSorting` of basalt's
+  own; TanStack's `ColumnDef.enableSorting` still reaches `getCanSort()` and works.
+
+### Four false greens
+
+1. **`check-theme` fabricated a config on the ascend path and passed silently.** From a package with
+   no `basalt` key it invented `roots: ["src"]` and reported the invention back under the name
+   `basalt.roots`. In `basalt-ui-obsidian`, run from `apps/demo`, that scanned **22 of 44** guarded
+   files and made `--audit-allows` report **0 live waivers in a repo carrying 1** — exit 0, no note.
+   The audit exists so `0 dead` cannot read as `0 dead anywhere`, and it could be made to say zero
+   by standing in the wrong directory. `resolveProjectDir` now ascends to the nearest ancestor
+   carrying a basalt project, bounded by the repo root, and announces it in the sentence descend
+   already used. **No `.git` above cwd means no ascend**, so a standalone consumer keeps the
+   built-in defaults exactly as before. After: 44 files, the real 1.
+2. **`tokens:css --check` stopped verifying the regeneration command.** 1.23.1 blanked all of line 2
+   so a version bump would stop forcing a no-op commit — but line 2 also carries the exact
+   invocation line 1 tells the reader to regenerate with. Rewriting `--only core` to `--only all` in
+   that line **passed clean**. Only the version token is neutralized now; a line that does not parse
+   as a provenance line is compared verbatim, so a deleted or reworded header fails. The success
+   message also **parses** the versions instead of asserting them — it used to claim the file "still
+   names an older basalt-ui" without reading it, so `0.0.1-nonsense` earned the same sentence.
+3. **`doctor`'s icons check was unreachable from the only directory where `doctor` exits 0.** On a
+   monorepo the root run omitted it with no `⊘ SKIPPED` line — the exact failure mode `SKIPPED` was
+   introduced to eliminate — while the app-package run failed on artefacts of standing in a
+   non-install package. It resolves the app package off `basalt.roots` now. No `basaltAppPlugin(`
+   anywhere and no `public/` is a pass that says so; a plugin call with no `public/` beside it is a
+   `⊘ SKIPPED`, which exits non-zero on its own.
+4. **`SCANNABLE_EXT` gained `.astro`, `.jsx` and `.vue`.** rollhook's marketing site is Astro and its
+   two `.astro` templates are its entire markup layer — unguarded, while `check-theme` reported a
+   clean 4-file scan. It scans 6 now.
+
+**Behaviour change to name: `sync` ascends too.** It shares the resolver, so from a sub-package it
+relocates to the parent install and refreshes it — announced — rather than refusing. It still cannot
+scaffold a second consumer: the refusal is keyed on the RESOLVED project and runs before the
+`basalt.roots` backfill.
+
+### Guard changes the widening exposed
+
+- **`raw-hex` no longer matches inside an HTML numeric character reference.** `&#123;` — the escaped
+  brace a template writes to show a literal `${…}` in prose — read as the hex colour `#123`. The
+  hole was in the KIND, not the extension: the same string produced the same findings in `.html`,
+  `.tsx`, `.css` and `.vue`, so `.astro` only walked into it first. The fix is precise, not blanket:
+  `HEX` rejects a full reference (`&#`, digits, `;`), so **`color: red&#fff` still flags** and
+  nothing is exempted by file type. Every neighbouring raw-text kind was checked and structurally
+  cannot share the blind spot — a character reference contains no `(`, and the rest anchor on a
+  property name, `var(`, or a JSX `=`.
+- **A fourth guard syntax, `sfc`, for `.astro`/`.vue`.** They used to fall through to the `ts`
+  dialect, so `<!-- … -->` was never stripped: a `theme-allow` written in an HTML comment waived
+  nothing and a colour inside a commented-out block still reported. `sfc` strips both regions —
+  markup first, so an HTML comment holding an unterminated `/*` cannot open one that runs to EOF —
+  and keeps the **full 25-kind set**. A `markup` classification would have dropped 22 of them: an
+  `.astro` template is JSX-shaped and a `.vue` `<script setup>` is real TS. `.jsx` needs no branch.
+  Both the scan and `--audit-allows` now share one `stripGuardComments`, so they cannot disagree
+  about what a comment is.
+- **Two limits, asserted rather than left ambiguous, both false-negative-only:** `css-raw-surface`
+  does not fire inside a `<style>` fence, and stripping is region-blind, so a `<!--` inside a script
+  string over-strips.
+- **A known non-fix, deliberate:** an all-hex URL fragment or SVG reference (`href="#cafe"`,
+  `fill="url(#abcdef)"`) still reports. It is text-indistinguishable from a colour, so a fix would
+  cost real findings; `theme-allow` is the escape.
+- **The widening ships at `error` with no `GRACE_PERIOD_KINDS` entry, and that table cannot express
+  it.** The table is keyed per KIND; widening `SCANNABLE_EXT` widens the file set for all 25 at
+  once. An entry for `raw-hex` — the kind that actually fired — would demote basalt's most
+  load-bearing kind to `warn` across every `.tsx` and `.css` in all seven consumers to buy runway on
+  a file type one consumer has. Measured: rollhook's marketing site scans 6 files with 0 findings,
+  and no other consumer holds a single `.astro`, `.vue` or `.jsx` file, so grace would have covered
+  zero incumbent violations.
+
+## 1.23.1 — the band-state throw, the tag gate, a CLI that answers
+
+**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. **Superseded in `Unreleased`:
+  blanking the WHOLE line also stopped gating the regeneration command it carries. Only the version
+  token is neutralized now.**
+
+### 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 +286,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.**
 
@@ -147,8 +363,8 @@ install it found above instead. The refusal runs before the `basalt.roots` backf
 the damage. Two ways to unblock it:
 
 ```bash
-cd <the package holding .basalt/manifest.json> && bunx basalt-ui sync
-BASALT_CWD=<that package> bunx basalt-ui sync   # or from anywhere
+cd <the package holding .basalt/manifest.json> && ./node_modules/.bin/basalt-ui sync
+BASALT_CWD=<that package> ./node_modules/.bin/basalt-ui sync   # or from anywhere
 ```
 
 The summary line gained a `created` counter. **`recreated` now means what it always claimed** — the