basalt-ui 1.25.0 → 1.27.0

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

@@ -1,219 +1,94 @@
 ---
 name: basalt-app
-description: Scaffold or refresh a basalt-ui app — guided wrapper around 'basalt-ui init' (first-time scaffold) and 'basalt-ui sync' (drift-managed refresh). The whole agentic layer ships in the npm package — init places the skills, rules, CLAUDE block, and DESIGN.md; sync keeps the managed half fresh. Use when setting up basalt-ui in a new/existing app, wiring the provider/shell/vite preset, or when the doctrine feels missing.
-when_to_use: User is adding basalt-ui to a new or existing app, asks how to set it up / scaffold it, wants to wire BasaltProvider / BasaltShell / the vite preset, refresh the shipped rules and DESIGN.md, or run a freshness check in CI. Also when /basalt-design reports no consumer DESIGN.md (the app isn't scaffolded yet).
+description: Scaffold or refresh a basalt-ui app — the procedure around `basalt-ui init` (first-time scaffold) and `basalt-ui sync` (drift-managed refresh), plus the runtime wiring neither of them does for you (provider, shell, vite, CSS order). Use when setting up basalt-ui in a new or existing app, after upgrading it, or when the shipped doctrine seems missing.
+when_to_use: User is adding basalt-ui to a new or existing app, asks how to set it up or scaffold it, wants to wire BasaltProvider / BasaltShell / the vite preset, refresh the shipped rules after an upgrade, or wire a freshness check in CI. Also when /basalt-design reports no consumer DESIGN.md.
 ---
 
-`/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). Bun runtime.
+`/basalt-app` gets a consumer scaffolded and keeps its shipped doctrine fresh. Everything — the
+components, the toolchain presets, the rules, the skills, the templates — ships in the one npm
+package; `init` places it and `sync` refreshes it.
 
-## 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:
+## 1. Install and scaffold
 
 ```bash
 bun add basalt-ui
-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
+bunx basalt-ui init                        # 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?**
-
-| Mode        | Files                                                                                                             | Lifecycle                                                                                                                          |
-| ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| **managed** | `.claude/rules/basalt-*.md`, `.claude/skills/basalt-*/SKILL.md`, the `CLAUDE.md` block                            | basalt owns it; `sync` refreshes it; a local edit is skipped and reported (`--force` overwrites); the sync diff is the review gate |
-| **seed**    | `DESIGN.md`, `.oxlintrc.json`, `.oxfmtrc.json`, `lefthook.yml`, `.github/workflows/check.yml`, optional scaffolds | written once, then yours forever; `sync` recreates it only when missing and never reports it                                       |
-
-Claude Code cannot load rules or skills from `node_modules` — that platform limit is the only
-reason anything is copied. Everything a machine reads is a **reference** instead: the seeded
-`.oxlintrc.json` and `lefthook.yml` just `extends` the presets inside
-`node_modules/basalt-ui/configs/`, so the toolchain auto-updates with the package while you still
-own the files.
-
-## First-time scaffold: `bunx basalt-ui init`
-
-`init` writes the repo-side doctrine and toolchain into a consumer (monorepo globs supported):
-
-- `.claude/rules/basalt-*.md` — the thirteen shipped rules (`basalt-tokens`, `basalt-charts`,
-  `basalt-mantine`, `basalt-router`, `basalt-query`, `basalt-state`, `basalt-forms`,
-  `basalt-notifications`, `basalt-commands`, `basalt-data`, `basalt-agent`, `basalt-content`,
-  `basalt-app`), managed verbatim.
-- `.claude/skills/basalt-{app,charts,design}/SKILL.md` — the three skills (`/basalt-app`,
-  `/basalt-charts`, `/basalt-design`), managed verbatim, same path the rules take.
-- A managed `<!-- basalt:begin --> ... <!-- basalt:end -->` block in `CLAUDE.md`: stack facts, the
-  **DESIGN.md-is-law** pointer, and the **frontend-design restraint override** (in a dashboard, the
-  bold move is calm — defer to `/basalt-design`, not generic "make it striking" instincts).
-- A **thin** `DESIGN.md` seed (deltas only on top of the `basalt-*` rules): identity confirmation,
-  the series dictionary, app deviations. The CLAUDE block `@`-imports it, so it auto-loads.
-- Toolchain seeds: `.oxlintrc.json` and `lefthook.yml` are `extends` stubs pointing into
-  `node_modules/basalt-ui/configs/`; `.oxfmtrc.json` is a starting copy (oxfmt has no `extends`);
-  `.github/workflows/check.yml` is a starting workflow. All four are yours after the first write.
-- `.basalt/manifest.json` — a sha256 per managed file + the basalt-ui version that wrote it, so
-  `sync` can three-way diff and `doctor` can spot a stale install.
-
-It also patches `package.json`: **`basalt.roots`** inferred from the real layout (workspace packages
-depending on basalt or Mantine, else every workspace `src/`, else `src`) and a **`lint:basalt`**
-script (`oxlint . && basalt-ui check-theme`). Everything derives from `roots` — the guard's scan, the
-seeded CI `oxfmt` globs, the default exemption — so a workspace repo without it scaffolds a guard
-that scans zero files while every gate reports green. Correct it if your sources live elsewhere. A
-Mantine-free consumer adds `"basalt": { "profile": "tokens-only" }` by hand; `check-theme` never
-infers that, because inferring it from a missing `@mantine/core` would silence 17 kinds on a repo
-that simply keeps Mantine in another workspace package.
-
-**`init` on an EXISTING app is a lint-debt event, not a no-op.** Adopting the shipped preset turns
-on whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
-findings on the first run. `init` names the plugins and every file it kept — plus what keeping it
-costs (an existing `.oxlintrc.json` that does not `extends` the preset means the entire basalt lint
-half is off, and nothing else says so; `--merge-lint` splices it in). Run `oxlint .` and triage
-before the next commit; turn a rule off with a written reason rather than disabling a plugin.
-
-Then `basalt-ui doctor`. `SKIPPED` is a third outcome beside pass/warn/fail and exits non-zero on
-its own — a check that could not run is not a check that passed — and the hard checks now include
-`basalt-resolves`, `guard-scan` (would `check-theme` cover more than zero files?) and
-`oxlint-preset` (does `.oxlintrc.json` really extend the preset? JSONC is parsed, not rejected).
-Expect doctor to go red where it was green on an older basalt; that is the point.
-
-After `init`, do the runtime wiring (the CLI scaffolds files, not your app's composition):
+`init` writes the managed doctrine (`.claude/rules/basalt-*.md`, `.claude/skills/basalt-*/SKILL.md`,
+the `CLAUDE.md` block), the seeds you then own (`DESIGN.md`, `.oxlintrc.json`, `.oxfmtrc.json`,
+`lefthook.yml`, CI, optional scaffolds), and `.basalt/manifest.json` — a sha256 per managed unit so
+`sync` can three-way diff. It also patches `basalt.roots` and a `lint:basalt` script.
+
+Two modes, decided by one question — **does Claude read this file?** Managed files are
+framework-owned and meant to be overwritten (the sync diff is the review gate); seeds are written
+once and yours forever. Claude Code cannot load rules or skills out of `node_modules`, which is the
+only reason anything is copied at all; everything a MACHINE reads is an `extends` reference into
+`node_modules/basalt-ui/configs/`, so the toolchain auto-updates with the package.
+
+**`init` on an existing app is a lint-debt event, not a no-op** — read
+`.claude/rules/basalt-batteries.md` § "App bootstrapping" for what it turns on and what keeping your
+own `.oxlintrc.json` costs.
+
+## 2. Wire the runtime (the CLI scaffolds files, not your app's composition)
 
 ```tsx
-// Provider — wraps MantineProvider, injects the --vx-* palette, bridges the Vx tokens
-import { BasaltProvider } from 'basalt-ui'
-;<BasaltProvider>{/* app */}</BasaltProvider>
-
-// Shell — sidebar / mobile-nav / breadcrumbs / page-header; router-agnostic
-import { BasaltShell, NavCountBadge, ThemeToggle } from 'basalt-ui'
-// <ThemeToggle /> in globalActions — cycles light/dark/system on click, hover/focus reveals
-// a direct-select popover. Animated (motion) sun/moon glyph, never a computer/monitor icon.
-
-// Theme — start from the base, override deltas only
-import { createBasaltTheme } from 'basalt-ui'
-const theme = createBasaltTheme({
-  /* app deltas */
-})
+// main.tsx — CSS order is load-bearing: every @mantine/*/styles.layer.css, THEN basalt's
+import '@mantine/core/styles.layer.css'
+import 'basalt-ui/styles.css'
+import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
+import { BasaltOverlays } from 'basalt-ui/commands'
+;<BasaltProvider theme={createBasaltTheme(/* app deltas only */)} defaultColorScheme="dark">
+  <BasaltOverlays>{/* data layer, then the router */}</BasaltOverlays>
+</BasaltProvider>
 ```
 
 ```ts
-// vite.config.ts — basaltViteConfig (dedupe react + @mantine/*, strictPort, /api proxy,
-// BASALT_LOCAL alias) composed with basaltAppPlugin (PWA head, manifest, icon metadata)
-import react from '@vitejs/plugin-react'
-import { basaltAppPlugin, basaltViteConfig } from 'basalt-ui/vite'
-import { defineConfig } from 'vite'
-
+// vite.config.ts — the preset is config-only; the plugin half is spread into your own plugins
 export default defineConfig({
   ...basaltViteConfig({ port: 5173, apiTarget: 'http://localhost:3000' }),
   plugins: [react(), ...basaltAppPlugin({ name: 'MyApp', description: '…' })],
 })
 ```
 
-`basaltViteConfig` stays config-only (no `plugins`) by contract; `basaltAppPlugin` is the plugin
-half — spread it into your own `plugins` array. See `agent/rules/basalt-app.md` for plugin
-ordering (e.g. alongside `@content-collections/vite`) and the full head/PWA/manifest surface.
+Then `BasaltShell` with a `useNav(NAV)` spread (basalt-state.md), `PageBar` per page
+(basalt-controls.md), and `<first basalt.root>/lib/series.ts` as the app's one guard-exempt series
+source (`/basalt-charts`). There is no Tailwind.
+
+## 3. Verify the wiring took
+
+```bash
+./node_modules/.bin/basalt-ui doctor      # read it to the LAST line
+bun run lint:basalt                       # oxlint . && basalt-ui check-theme
+```
+
+`SKIPPED` is a third outcome beside pass/warn/fail and **exits non-zero on its own** — a check that
+could not run is not a check that passed. Expect doctor to go red where an older basalt was green;
+that is the point. Then triage `oxlint .` before the next commit.
+
+## 4. Refresh after every upgrade
 
-```js
-// Tailwind era is over — there is no Tailwind. Styles come from:
-import 'basalt-ui/styles.css' // @layer basalt base styles, iOS input safety net, font stack
+```bash
+./node_modules/.bin/basalt-ui sync        # --check in CI, --force to overwrite local edits
+```
+
+- Unchanged since basalt wrote it → overwritten. Locally edited → diffed and SKIPPED. Missing →
+  recreated. **Retired upstream → deleted**, and named in the output; a rule file basalt stopped
+  shipping is doctrine your agent would otherwise keep reading.
+- `sync --check` makes no writes and exits non-zero on any of that — wire it as the freshness gate.
+- Run it anywhere in the repo: it resolves the project the way `check-theme` and `doctor` do,
+  announces a relocation, refreshes a PARENT install from a sub-package, and still refuses to
+  scaffold a second consumer (that stays `init`'s decision).
+- Seeds are never reconciled or reported. They are yours.
+
+## 5. Not a React app?
+
+```bash
+bunx basalt-ui tokens:css --out src/tokens.css   # no install to resolve, so bunx is right here
+bunx basalt-ui fonts:css --out src/fonts.css
 ```
 
-Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` script) — the theme
-guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
-already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
-passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
-`basalt/shadow-basalt-export` reads all nine published barrels since 1.21.0 (the charts layer
-included), but it warns only on an **exact** name collision, in a basalt-scoped file, on a
-component-shaped declaration — round 5 found the renamed forks (`Cell`, `Box`, `Stat`) sail straight
-past it. It is a tripwire, not coverage; nothing catches the
-rest. Ask before you build; do not wait to be told.
-
-The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on
-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: `basalt-ui sync`
-
-`sync` re-applies shipped doctrine after a basalt-ui upgrade, three-way against
-`.basalt/manifest.json`:
-
-- **Unchanged since last write** → overwrite with the new version.
-- **Locally edited** → show a diff and **skip** (preserves your edits) unless `--force`.
-- **Missing** → recreate.
-- `sync --check` makes no changes and exits non-zero on drift — wire it as a CI freshness gate so a
-  consumer can't silently fall behind the shipped rules.
-
-**Run it anywhere in the repo.** `sync`, `check-theme` and `doctor` share one resolver:
-`BASALT_CWD` → the cwd → declared workspace packages → a two-level descend → an **ascend** to the
-nearest ancestor carrying a basalt project, bounded by the repo root. Both directions announce the
-relocation in one sentence. From a sub-package `sync` now refreshes the parent install rather than
-refusing — but it still **exits 1 rather than scaffolding a second consumer** where the resolved
-project has no `.basalt/manifest.json`. Creating an install stays `basalt-ui init`'s decision.
-
-Seeds (`DESIGN.md`, the toolchain files, the scaffolds) are never reconciled or drift-reported —
-they are yours. The managed files (rules, skills, the CLAUDE block) are framework-owned and meant
-to be overwritten; the sync diff is where you review a doctrine change before committing it.
-
-## Precedence the scaffold establishes
-
-After scaffolding, the doctrine resolves in this order (highest wins):
-
-> consumer `DESIGN.md` (deltas) > shipped `basalt-*` rules > skills
-
-So an app deviation goes in `DESIGN.md`; the universal law and its enforcement live in the
-`basalt-*` rules; and the skills (`/basalt-design`, `/basalt-charts`) are the method that obeys
-both.
-
-## Checklist
-
-- Ran `bun add basalt-ui && bunx basalt-ui init` — rules, skills, CLAUDE block, DESIGN.md all
-  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); 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.
-- `<first basalt.root>/lib/series.ts` exists as the one guard-exempt series source (for any app metric colors).
-- `basalt-ui sync --check` wired in CI (recommended) to catch drift on future upgrades.
-- `basalt-ui doctor` run after `init` and read to the last line — a `SKIPPED` check exits non-zero
-  and is not a pass.
-
-## Notes
-
-- `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 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 — 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 —
-  animated chrome (`ThemeToggle` today) comes for free, no consumer dependency needed. Reach for
-  the shared `MOTION_DURATION` / `MOTION_SPRING` tokens for any new animated interaction rather
-  than inventing ad hoc durations/easings or a competing animation library.
-- `vite-plugin-pwa` (`^1.3.0`) is an OPTIONAL peer, only needed when `basaltAppPlugin`'s
-  `serviceWorker` option is truthy — omit it entirely for apps that don't want an installable/
-  offline-capable app. See `agent/rules/basalt-app.md` for the full head/PWA/manifest/icons
-  surface `basaltAppPlugin` owns.
+Both carry the two-line `@generated basalt-ui` header the guard skips, and both take `--check` as a
+CI drift gate that ignores the provenance version — so a basalt bump alone never forces a no-op
+commit. Declare `"basalt": { "profile": "tokens-only" }` by hand; `check-theme` never infers it.

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

@@ -1,254 +1,74 @@
 ---
 name: basalt-charts
-description: Add or extend a chart in a basalt-ui app — pick a kind vs go bespoke (Rule of Three), register a consumer series with defineSeries/groupTokens (since VX.series is app-side, not shipped), compose CartesianChart (or ChartFrame directly for a non-single-plot shape), and respect the @visx-only-in-charts + Mantine-free boundary. Use when adding a new chart, a new metric/series color, or extracting a repeated chart shape into a kind.
-when_to_use: User wants to add a chart, restyle an existing one structurally, introduce a new metric/series and its color, extract a recurring chart shape into a reusable kind, or asks where chart series colors live / how to register them. The how-to companion to /basalt-design (which owns the aesthetic law).
+description: Add or extend a chart in a basalt-ui app — the procedure: pick a shipped kind vs extract one vs stay bespoke (Rule of Three), register the consumer series with defineSeries/groupTokens, compose CartesianChart (or ChartFrame for a non-single-plot shape), then verify against the guards. Use when adding a chart, a new metric/series color, or extracting a repeated chart shape.
+when_to_use: User wants to add a chart, restyle one structurally, introduce a new metric/series and its color, extract a recurring chart shape into a reusable kind, or asks where chart series colors live and how to register them. The how-to companion to /basalt-design, which owns the aesthetic law.
 ---
 
-`/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. `.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).
+`/basalt-charts` is the HOW. `.claude/rules/basalt-charts.md` is the contract everything below
+assumes, and `/basalt-design` owns the aesthetic law — read both before writing chart code. The
+props themselves are in the shipped types and `llms.txt` at the install directory.
 
-## The decision: kind vs bespoke (Rule of Three)
+## 1. Pick the path (Rule of Three)
 
-Before writing chart code, decide which of three paths you are on:
+1. **A shipped kind fits** → use it. `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`, `DualPanel`,
+   `Heatmap`, `Donut`, `BandStrip`, `MirroredBars`. Read their props before assuming a gap: dual
+   axis, zones, thresholds, refLines, per-point markers, folding, per-series formatting and
+   `isPending` are all declarative already.
+2. **This is the SECOND instance of a shape with no kind** → extract a kind and migrate both call
+   sites. Not on the first, not past the third.
+3. **Genuinely unique** → stay bespoke in the page's own chart file, composing the primitive
+   directly. Not in a shared kinds directory.
 
-1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`,
-   `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.
-   - **`MultiLine`** — N series on a shared y-axis (or two, via `y2`): legend-hover dimming,
-     per-series synced dots, dashed companion (MA) lines, per-point markers (PR stars / status
-     dots), zones + refLines, fixed or auto domain (also covers z-score/σ charts via a fixed
-     symmetric domain + zero refLine). Replaces bespoke multi-line / relative-progression /
-     training-load / strength-composite / fitness-trends.
-   - **`DualPanel`** — top line-pane + bottom signed-histogram pane sharing ONE x-scale and ONE
-     cursor; optional fill-between two top lines, zones, refLines. Replaces bespoke divergence /
-     momentum.
-   - **`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
-   to promote, gets contributed to basalt-ui `src/charts/kinds/`). Migrate both call sites onto it.
-   A single-plot kind composes `CartesianChart`, drawing only marks; a multi-pane or non-cartesian
-   kind composes `ChartFrame` directly (see "Compose the primitives" below).
-3. **Stay bespoke (genuinely unique).** A one-off shape (e.g. a dual-panel MACD, or two series 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.** Move real call sites onto it and ship the list of what
+it could NOT express. A demo page is written against the API that already exists, so it proves
+nothing.
 
-**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.
+## 2. Register the series (this is consumer data)
 
-> 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.**
-
-A good kind's props: `data`, `chartId`, generic `getX` accessor, `height`/`aspectRatio`/`fill`,
-zones / thresholds / refLines arrays, one `AxisConfig` object per axis, `series: ChartSeries<T>[]`
-as the single source of truth for color/label/legend/tooltip. Bespoke escape hatches
-(`tooltip.extraRows`, `tooltip.prependRows`) are fine; they must not grow into a god-object config.
-
-`ZonedLine` and `MultiLine` also take `xZones?: XZoneSpec[]` — vertical time-window bands, the
-counterpart to the horizontal zones above. `{ from?, to?, fill }` bounds are `getX` **domain keys**
-(the label string, not a date/timestamp); an omitted bound is the plot edge, a key missing from the
-domain skips the band rather than clamping to one.
-
-## Register a consumer series (VX.series is app-side)
-
-The framework ships generic primitives and the framework palette (semantic / status / neutral /
-surface) — **but not a domain series tree.** `VX.series` does not exist in basalt-ui; argo's
-`SERIES`/`ACTIVITY`/`USAGE_*` maps stayed app-side. Each consumer rebuilds its own series in **one
-guard-exempt file** (e.g. `src/lib/series.ts`), using the shipped extensibility helpers from
-`basalt-ui/tokens`:
+`VX.series` does not exist in the framework — which metric owns which hue is domain data, declared
+in ONE guard-exempt file per app:
 
 ```ts
-// src/lib/series.ts  — the ONE file exempt from `basalt-ui check-theme` (it IS the palette source)
-import { defineSeries, groupTokens, seriesTokens, buildPaletteCss } from 'basalt-ui/tokens'
-
-// 1. Author the per-theme pairs (hue keeps identity, shifts shade across schemes).
-const HEALTH = defineSeries({
-  hrv: { light: '#634DBF', dark: '#7C6BD6' }, // violet — lighter on dark to avoid glow
-  restingHr: { light: '#C22762', dark: '#E0639A' },
-})
-const WALKING = defineSeries({
-  intensityMin: { light: '#3F7D4F', dark: '#5FA372' }, // forest green — muted status hue
-})
-
-// 2. Turn the maps into namespaced token refs (var(--vx-health-hrv), ...).
-//    seriesTokens(map, prefix?) for a flat namespace; groupTokens(name, map) namespaces under name.
-export const SERIES = {
-  ...seriesTokens(HEALTH), // → { hrv: 'var(--vx-hrv)', restingHr: 'var(--vx-restingHr)' }
-  walking: groupTokens('walking', WALKING), // → { intensityMin: 'var(--vx-walking-intensityMin)', ... }
-}
+// src/lib/series.ts — the one file exempt from check-theme, because it IS the palette source
+import { buildPaletteCss, defineSeries, groupTokens, seriesTokens } from 'basalt-ui/tokens'
 
-// 3. Feed the same maps into the palette CSS so the vars exist in both schemes.
-export const PALETTE_CSS = buildPaletteCss({
-  groups: { health: HEALTH, walking: WALKING },
-  derived: ['--vx-hrv-area: 12%'], // optional scheme-independent derived vars
-})
+const HEALTH = defineSeries({ hrv: { light: '…', dark: '…' } }) // lighter on dark, deeper on light
+export const SERIES = { ...seriesTokens(HEALTH), walking: groupTokens('walking', WALKING) }
+export const PALETTE_CSS = buildPaletteCss({ groups: { '': HEALTH, 'walking-': WALKING } })
 ```
 
-- `seriesTokens` / `groupTokens` are **exact-keyed**: a typo or a stale key fails `tsc`, so the
-  token surface can't silently drift from the palette data.
-- `defineSeries` is the typed authoring entry — it returns the map (sugar; pairs feed both the CSS
-  and the tokens).
-- Inject `PALETTE_CSS` once (BasaltProvider injects the framework palette; the consumer appends its
-  series CSS — or passes `injectPalette={false}` and head-injects both).
-- Then charts read `SERIES.hrv`, never a hex. This is what keeps `basalt-ui check-theme` green.
-- A series with nothing visible to point at (flat at the domain floor, all-zero) can still carry a
-  qualifier: pass `note` on the series' `SeriesStyle` (flows to `LegendEntry.note` via
-  `deriveLegend`) and `ChartLegend` renders it, muted, after the label.
+`seriesTokens`/`groupTokens` are exact-keyed, so a stale or typo'd key fails `tsc`. Feed the SAME
+maps to `buildPaletteCss` (or `BasaltProvider`'s `paletteOptions.groups`, keyed by var PREFIX — the
+trailing dash matters) or the refs point at variables nothing declares.
 
-Theme tuning of these series happens in the theme lab — pass them as `groups` to
-`ThemeLabControls` (see `/basalt-design`).
+## 3. Compose the primitive
 
-## 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 — 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.
-
-**The common case — a single-plot chart:**
+A single-plot chart composes `CartesianChart` and draws only marks in the render prop — margins,
+scales, axes, grid, the shared cursor, crosshair, dots and tooltip are already done:
 
 ```tsx
-import { CartesianChart, LinePath, curveMonotoneX, VX } from 'basalt-ui/charts'
-import type { ChartSeries } from 'basalt-ui/charts'
-import { SERIES } from '../lib/series'
-
-type HrvPoint = { date: string; hrv: number }
-
-const HRV_SERIES: ChartSeries<HrvPoint>[] = [
-  { key: 'hrv', label: 'HRV', color: SERIES.hrv, mark: 'line', getValue: (d) => d.hrv },
-]
-
-function HrvChart({ data }: { data: HrvPoint[] }) {
-  return (
-    <CartesianChart
-      data={data}
-      chartId="hrv"
-      getX={(d) => d.date}
-      series={HRV_SERIES}
-      y={{ domain: 'auto', format: (v) => `${Math.round(v)} ms` }}
-      height={240}
-    >
-      {({ xScale, yScale, visible }) =>
-        visible.map((s) => (
-          <LinePath<HrvPoint>
-            key={s.key}
-            data={data}
-            x={(d) => xScale(d.date) ?? 0}
-            y={(d) => yScale(s.getValue(d) ?? 0)}
-            stroke={s.color}
-            strokeWidth={VX.lineWidth}
-            curve={curveMonotoneX}
-          />
-        ))
-      }
-    </CartesianChart>
-  )
-}
+<CartesianChart data={data} chartId="hrv" getX={(d) => d.date} series={HRV} y={{ domain: 'auto' }} height={240}>
+  {({ xScale, yScale, visible }) =>
+    visible.map((s) => <LinePath key={s.key} data={data} x={…} y={…} stroke={s.color} />)
+  }
+</CartesianChart>
 ```
 
-`CartesianChart` draws the grid, both axes, the shared cursor + crosshair + dots, and the derived
-tooltip for you — `HrvChart` above draws nothing but the line: no hover wiring, no manual
-`<AxisLeft>`/`<AxisBottom>`, no tooltip assembly.
-
-**Dual-axis is `y2`, not a flag.** Passing `y2` is what turns on the right axis (margin widens by
-measurement); a series opts in with `axis: 'right'` on its `ChartSeries` entry. See
-`apps/playground/src/demo/ChartsPage.tsx`'s `SessionsRevenueChart` for a full worked example (two
-series on genuinely different scales — session counts vs. `$k` revenue — composed directly from
-`CartesianChart` because no shipped kind's config surface covers a dual-axis line pair).
-
-Never substitute: hand-rolled legend markup, a raw `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>`, a
-direct `@visx/tooltip` import, or an `rgba()` fill. Sparklines (`charts/sparklines/`) are the one
-exemption from the `CartesianChart`/legend/tooltip composition — but they still use `VX.*` tokens.
-
-## The cursor is shared by default
-
-No provider needed. `useChartCursor` reads a module-level external store, so every chart on the
-page — kind or bespoke, `CartesianChart` or `ChartFrame` — shares one cursor out of the box, and
-resolution is **domain-aware** (nearest parsed date/number within a chart's own step, not exact
-string match), so a chart that folds its calendar into weekly buckets still tracks a hover from an
-unfolded daily sibling.
-
-Wrap a subtree in `ChartCursorScope` to **isolate** it onto a private cursor instead — the inverse
-of the old opt-in pattern, for e.g. two independent dashboards rendered side by side over the same
-calendar that must NOT sync with each other:
-
-```tsx
-import { ChartCursorScope } from 'basalt-ui/charts'
-;<ChartCursorScope>
-  <ChartCard>…</ChartCard>
-  <ChartCard>…</ChartCard>
-</ChartCursorScope>
-```
-
-## Respect the boundary (oxlint-enforced)
-
-- **`@visx/*` may only be imported inside chart files.** The shipped consumer oxlint preset bans
-  direct `@visx/*` outside `**/charts/**`. Need a raw visx primitive for a bespoke chart? Pull it
-  from basalt-ui's curated re-export in `basalt-ui/charts`, or keep the chart under a charts dir.
-- **basalt-ui's own `./charts` and `./tokens` are Mantine-free** — zero `@mantine/*` imports,
-  keeping the token layer upstream of Mantine inside the framework itself (`cssVariablesResolver`
-  reads `--vx-*` tokens to bind Mantine's surfaces to them; a chart importing `@mantine/*` directly
-  would fork chrome and charts apart), AND letting `basalt-ui/charts`/`basalt-ui/tokens` resolve and
-  render with no `@mantine/*` installed (real, CI-tested — `scripts/pack-test.sh`'s
-  "charts/tokens-only (no-Mantine) resolution + render" step). This is a basalt-internal invariant,
-  not a rule enforced on your own app code — compose the shipped primitives from
-  `basalt-ui/charts`/`basalt-ui/tokens` and you inherit it for free.
-- **No raw color literals** anywhere except the one guard-exempt series file (and a deliberate
-  `theme-allow` line). `basalt-ui check-theme` is the teeth; run it before committing.
-- **No raw visx axes.** `basalt-ui check-theme`'s `raw-visx-axis` guard fails the build on a raw
-  `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>` inside any `/charts/` file — use the tokenized
-  `AxisLeftNumeric` / `AxisRightNumeric` / `AxisBottomDate` (escape via `theme-allow`).
-- **No hand-rolled plot assembly.** `basalt/hand-rolled-plot` fails the build on a chart-assembly
-  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`, `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
-  longer draws.
-- Both ship at `warn` in the consumer preset (`configs/oxlint.json`) for one minor and `error`
-  repo-local (the "grace minor" doctrine in `packages/basalt-ui/CLAUDE.md`) — promoting to `error`
-  in the next minor.
-
-## Checklist for a new chart
-
-- Picked the right path: reused a kind / extracted on the second instance / stayed bespoke for a
-  true one-off.
-- Composed `CartesianChart` (single plot) or `ChartFrame` directly (multi-pane / non-cartesian) —
-  never hand-assembled margin/scales/axes/cursor/tooltip.
-- Any new metric color is a `{ light, dark }` pair in the consumer series file, exposed via
-  `seriesTokens`/`groupTokens`, and wired into `PALETTE_CSS` via `buildPaletteCss`.
-- Charts read `SERIES.*` / `VX.*` — `basalt-ui check-theme` green, zero raw hex.
-- Marks draw `ctx.visible`, never the `series` prop, so a legend toggle actually removes them.
-- `@visx/*` stays inside chart files; chart code imports no `@mantine/*`.
-- Tuned both schemes via the theme lab where the hue needed it (defer to `/basalt-design`).
+- **Draw `visible`, never the `series` prop** — otherwise a legend toggle hides nothing.
+- **Dual axis is `y2`**, not a flag; a series opts in with `axis: 'right'`.
+- **A multi-pane, radial or matrix shape composes `ChartFrame`** + `useChartCursor` + `autoMargin` +
+  `ChartTooltipFloat` and declares itself with `theme-allow-file hand-rolled-plot — <why>`.
+- **Size is `height` / `aspectRatio` / `fill`** — one of the three, nothing else. Charts measure
+  themselves.
+- Never substitute a raw visx axis, a hand-written legend array, a `@visx/tooltip` import, an
+  `rgba()` fill or a hex.
+
+## 4. Verify
+
+- `oxlint .` green — no `basalt/hand-rolled-plot`, no `basalt/chart-legend-literal`, no
+  `basalt/chart-in-raw-surface`, no `@visx/*` import outside a `charts/` segment.
+- `basalt-ui check-theme` green — no raw hex, no raw axis, every chart entry point has an
+  `ariaLabel`.
+- Every new color is a `{ light, dark }` pair in the series file and wired into the palette CSS.
+- Tooltip rows and the legend are DERIVED from `series`; the plot draws `visible`.
+- Checked in both schemes, and with a pending query (`isPending`, not `data ?? []`).