basalt-ui 1.28.0 → 1.29.1

package/README.md

@@ -59,7 +59,7 @@ bunx basalt-ui init
 That's the whole install — there is no plugin, no marketplace, and no second version to track.
 `init` writes into the consumer repo:
 
-- `.claude/rules/basalt-*.md` — thirteen Claude Code 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`)
+- `.claude/rules/basalt-*.md` — six Claude Code rules (`basalt-tokens`, `basalt-mantine`, `basalt-charts`, `basalt-state`, `basalt-controls`, `basalt-batteries`), each with a generated coverage header naming what enforces it
 - `.claude/skills/basalt-{app,design,charts}/SKILL.md` — the three skills (`/basalt-app`, `/basalt-design`, `/basalt-charts`), same managed path as the rules
 - A managed `<!-- basalt:begin/end -->` block in `CLAUDE.md` — stack facts, the DESIGN.md pointer, and the frontend-design restraint override
 - A thin `DESIGN.md` seed — your app's deltas (series dictionary, identity, deviations)
@@ -143,8 +143,8 @@ The canonical stack, once a router and a query client join the example above:
 ```
 
 The order is load-bearing, not stylistic: `BasaltProvider` auto-mounts `ConnectivityProvider`
-(`./connectivity`), which aggregates React-Query's own status and so must sit **above** the query
-client; `BasaltOverlays` must sit **inside** the theme, since Modals/Spotlight/Notifications
+(C1: absorbed onto the root barrel from the dropped `./connectivity`), which aggregates
+React-Query's own status and so must sit **above** the query client; `BasaltOverlays` must sit **inside** the theme, since Modals/Spotlight/Notifications
 resolve `--vx-*` tokens through Mantine's context; the router goes **last** so every route
 component renders with the theme, the data layer and the overlay layer already mounted above it.
 `agent/rules/basalt-mantine.md` points here rather than restating the tree.
@@ -172,8 +172,8 @@ const theme = createBasaltTheme(
 keep the shipped default). Never hand-edit a palette hex to retune the identity.
 
 `BasaltOverlays` (from `basalt-ui/commands`) is the composable overlay mount: it bundles
-`ModalsProvider`, `Spotlight`, and `Notifications` into a single mount point and replaces a
-standalone `<BasaltNotifications />`. `paletteOptions={{ groups: paletteGroups }}` emits your
+`ModalsProvider`, `Spotlight`, and `Notifications` into a single mount point — it is the one
+notifications mount. `paletteOptions={{ groups: paletteGroups }}` emits your
 app-specific series colors (see
 [Consumer-series extensibility](#consumer-series-extensibility) below) alongside the framework
 palette. Skip both — `BasaltOverlays` and `paletteGroups` — if you don't use those batteries yet.
@@ -245,7 +245,7 @@ scanned files, and `doctor`'s `guard-scan` check agrees with it. Each root's **p
 contributes its `index.html` and its `public/` tree — the Vite layout `basaltViteConfig` assumes,
 and where a raw `theme-color` or webmanifest `background_color` actually lives. `.json` is never
 blanket-scanned; `include` names one explicitly and is the only route to it. `profile:
-"tokens-only"` turns off the 19 kinds whose remedy is a Mantine component or prop, and must be
+"tokens-only"` turns off the 18 kinds whose remedy is a Mantine component or prop, and must be
 declared (or `--tokens-only`) — it is deliberately never inferred from a missing `@mantine/core`,
 which would silence half the guard on any repo keeping Mantine in a different workspace package.
 Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are documented on the
@@ -322,31 +322,31 @@ deleted rather than silently surviving into the next real skew.
 
 ## Subpath exports
 
-| Subpath             | Mantine? | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.`                 | coupled  | `BasaltProvider`, `createBasaltTheme` / `baseTheme` / `cssVariablesResolver`, `BasaltShell` + sidebar / mobile nav / breadcrumbs / `PageBar`, `Section` / `WidgetHeader`, `NavCountBadge`, `SidebarAccount` + the provider-agnostic account contract (`BasaltAccountProps`/`State`/`Actions`), `ThreadWorkspace` + thread-chat components, dashboard composites (`DeltaBadge`, `StatCard`, `EmptyState`, `SettingsSection`/`SettingsRow`/`DangerZone`) and the query-branch trio `QueryState` / `LoadingState` / `ErrorState`, shell types — the root entry still re-exports the thread-chat components; `./agent-chat` takes the same components standalone, without `BasaltProvider`, the shell, the dashboard composites, or `./connectivity` |
-| `./charts`          | **free** | `CartesianChart` + visx primitives, kinds, sparklines, hooks, token re-exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `./query`           | **free** | `createBasaltQueryClient`, transport-agnostic `unwrap`, lazy `BasaltQueryDevtools`, `toErrorMessage` / `errorStatus` — the only route to those two; the root barrel does not re-export them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `./router-tanstack` | **free** | TanStack Router bridge: `defineNav`/`navGroup`/`navTarget`/`flattenNav` + `useNav` (→ `{ sections, mobileNav }`), `useBasaltNav` (active route), `useRouterBreadcrumbs`, and `createSearchStore` + the `field.*` vocabulary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `inputProps`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `./notifications`   | coupled  | Mantine notifications: `notify` helpers, typed registry, persisted history, `NotificationBell`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `./commands`        | coupled  | Typed command bus + overlay controller, `toSpotlightActions`, `ShortcutsHelp`, `BasaltOverlays`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./data`            | coupled  | Convenience barrel pulling both peer groups: `BasaltDataTable`, `BasaltVirtualList` (Mantine-rendered) — prefer `./data/table` / `./data/virtual` for per-feature opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `./data/table`      | coupled  | `BasaltDataTable` — sortable data table over TanStack Table, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `./data/virtual`    | coupled  | `BasaltVirtualList` — windowed virtual list over TanStack Virtual, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `./agent`           | **free** | Headless streaming layer (`useAgentStream`, `PartList`) + multi-thread `createThreadsStore` / `useAgentThreadRuns` / outcome seam                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `./agent-chat`      | coupled  | Mantine-styled thread-chat components over `./agent`: `ThreadWorkspace`, `ThreadFeed` (`variant`/`renderRow`), `ThreadFeedRow` (inline-expanding Slack row, lazily mounted + kept mounted), `ThreadOutcomeCard`, `ThreadDetailPanel`, `Composer`, `ThreadTranscript` (`groupConsecutive`/`affordances`/`virtualize` — windowed transcripts open at the newest message unless `initialScroll: 'start'`; `virtualize` is enabled by the optional `@tanstack/react-virtual` peer, absent it degrades to an unwindowed, height-bound pane), `threadPartRenderers` — **requires `motion`**, not merely an optional peer; see [Requirements](#requirements)                                                                                            |
-| `./state`           | **free** | createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `./connectivity`    | coupled  | `ConnectivityProvider` (aggregates browser/React-Query/SSE/health-check status), `useConnectivity`, `ConnectivityIndicator` — auto-mounted by `BasaltProvider`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `./content`         | coupled  | `Prose`, `CodeBlock`, `Callout`, `TableOfContents`, `ReadingProgress`, `Markdown`, `MermaidDiagram`, `ArticleLayout`, `ArticleCard` / `ArticleGrid`, `GuideLink` / `GuideDrawer`, `mdxComponents`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `./styles.css`      | —        | `@layer basalt` base styles, iOS input safety net, font stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `./tokens.css`      | **free** | Prebuilt `--vx-*` stylesheet — the default `buildPaletteCss()` output as a plain file, for a consumer with a bundler but no React or Mantine. **With no bundler, use the `basalt-ui tokens:css` CLI instead** and commit the emitted file: importing this subpath needs bare-specifier resolution. See [`docs/FRAMEWORK-FREE.md`](https://github.com/jkrumm/basalt-ui/blob/master/docs/FRAMEWORK-FREE.md)                                                                                                                                                                                                                                                                                                                                        |
-| `./configs/*`       | —        | Raw toolchain presets — oxlint, oxfmt, tsconfig (base/react-app/node), lefthook                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./llms.txt`        | —        | Machine-readable surface map — one entry per published subpath with import specifier, description, layer, and optional peers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Subpath             | Mantine? | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`                 | coupled  | `BasaltProvider`, `createBasaltTheme` / `baseTheme` / `cssVariablesResolver`, `BasaltShell` + sidebar / mobile nav / breadcrumbs / `PageBar` / `PageAside`, `Section` / `WidgetHeader`, `NavCountBadge`, `SidebarAccount` + the provider-agnostic account contract (`BasaltAccountProps`/`State`/`Actions`), `ThreadWorkspace` + thread-chat components, dashboard composites (`DeltaBadge`, `StatCard`, `EmptyState`, `SettingsSection`/`SettingsRow`/`DangerZone`), the query-branch trio `QueryState` / `LoadingState` / `ErrorState`, `createBasaltQueryClient` / `unwrap` / `toErrorMessage` / `errorStatus` / `BasaltQueryDevtools` (C1: absorbed from the dropped `./query`), `ConnectivityProvider` (auto-mounted) / `useConnectivity` / `ConnectivityIndicator` (C1: absorbed from the dropped `./connectivity`), shell types — the root entry still re-exports the thread-chat components; `./agent-chat` takes the same components standalone, without `BasaltProvider`, the shell, or the dashboard composites |
+| `./charts`          | **free** | `CartesianChart` + visx primitives, kinds, sparklines, hooks, token re-exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `./format`          | **free** | `Intl`-backed, Mantine-free, React-free formatting: `money`/`percent`/`integer`/`compact`/`deltaPct`, `duration`/`durationClock`/`clock`/`weekday`/`relativeTime`, `km`/`kcal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./router-tanstack` | **free** | TanStack Router bridge: `defineNav`/`navGroup`/`navTarget`/`flattenNav` + `useNav` (→ `{ sections, mobileNav }`), `useBasaltNav` (active route), `useRouterBreadcrumbs`, and `createSearchStore` + the `field.*` vocabulary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `inputProps`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `./notifications`   | coupled  | Mantine notifications: `notify` helpers, typed registry, persisted history, `NotificationBell`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./commands`        | coupled  | Typed command bus + overlay controller, `toSpotlightActions`, `ShortcutsHelp`, `BasaltOverlays`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `./data/table`      | coupled  | `BasaltDataTable` — sortable data table over TanStack Table, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `./data/virtual`    | coupled  | `BasaltVirtualList` — windowed virtual list over TanStack Virtual, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `./agent`           | **free** | Headless streaming layer (`useAgentStream`, `PartList`) + multi-thread `createThreadsStore` / `useAgentThreadRuns` / outcome seam                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `./agent-chat`      | coupled  | Mantine-styled thread-chat components over `./agent`: `ThreadWorkspace`, `ThreadFeed` (`variant`/`renderRow`), `ThreadFeedRow` (inline-expanding Slack row, lazily mounted + kept mounted), `ThreadOutcomeCard`, `ThreadDetailPanel`, `Composer`, `ThreadTranscript` (`groupConsecutive`/`affordances`/`virtualize` — windowed transcripts open at the newest message unless `initialScroll: 'start'`; `virtualize` is enabled by the optional `@tanstack/react-virtual` peer, absent it degrades to an unwindowed, height-bound pane), `threadPartRenderers` — **requires `motion`**, not merely an optional peer; see [Requirements](#requirements)                                                                                                                                                                                                                                                                                                                                                                      |
+| `./content`         | coupled  | `Prose`, `CodeBlock`, `Callout`, `TableOfContents`, `ReadingProgress`, `Markdown`, `MermaidDiagram`, `ArticleLayout`, `ArticleCard` / `ArticleGrid`, `GuideLink` / `GuideDrawer`, `mdxComponents`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `./controls`        | coupled  | The control tier: `FilterSet` + the `FieldHandle`-bound filters (`RangeFilter`/`CompareFilter`/`SelectFilter`/`MultiSelectFilter`/`NumberFilter`/`SearchFilter`/`ToggleFilter`), `ViewTabs`, `ActionGroup`/`OverflowMenu`/`SyncButton`, plus the aside's `PanelRow`/`SliderControl` row primitives — `pill`/`sheet`/`panel` surfaces, picked by the home, never a prop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `./controls-dates`  | coupled  | `DateRangePicker` — the `@mantine/dates` implementation of `RangeFilter`'s `customPicker` seam; its own subpath so `./controls` resolves and renders with no `@mantine/dates` installed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `./state`           | **free** | createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `./styles.css`      | —        | `@layer basalt` base styles, iOS input safety net, font stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `./tokens.css`      | **free** | Prebuilt `--vx-*` stylesheet — the default `buildPaletteCss()` output as a plain file, for a consumer with a bundler but no React or Mantine. **With no bundler, use the `basalt-ui tokens:css` CLI instead** and commit the emitted file: importing this subpath needs bare-specifier resolution. See [`docs/FRAMEWORK-FREE.md`](https://github.com/jkrumm/basalt-ui/blob/master/docs/FRAMEWORK-FREE.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `./configs/*`       | —        | Raw toolchain presets — oxlint, oxfmt, tsconfig (base/react-app/node), lefthook                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `./llms.txt`        | —        | Machine-readable surface map — one entry per published subpath with import specifier, description, layer, and optional peers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 Named exports only — no default exports.
 
@@ -496,28 +496,32 @@ It resolves ahead of the `xTicks` COUNT, which is unchanged; omit both and ticks
 Reach for values on a dense time axis — the tick chooser appends the final key unconditionally, so
 a count that misses the last index collides two labels at the right edge at every count.
 
-### `./query` — TanStack Query adapter
+### Query — `createBasaltQueryClient` / `unwrap` (root barrel)
+
+`./query` was dropped in 1.29.0 (C1 consolidation) — its two exports moved onto the root barrel,
+which already requires `@tanstack/react-query` as a peer. TanStack itself
+(`QueryClientProvider`, hooks, `queryOptions`) is imported straight from `@tanstack/react-query`,
+never re-exported by basalt.
 
 ```bash
 bun add @tanstack/react-query @tanstack/react-query-devtools
 ```
 
 ```tsx
-import { createBasaltQueryClient, QueryClientProvider, unwrap } from 'basalt-ui/query'
+import { createBasaltQueryClient } from 'basalt-ui'
+import { QueryClientProvider } from '@tanstack/react-query'
 
 const [client] = useState(() => createBasaltQueryClient())
 // queryFn: () => unwrap(api.users.get())
 ```
 
-`toErrorMessage(err, fallback?)` and `errorStatus(err)` also live here — decode an unknown thrown
-value into something renderable, folding an HTTP status into the fallback when the body decodes to
-nothing usable (`''`, `'{}'`, `'[object Object]'`, …).
+`toErrorMessage(err, fallback?)` and `errorStatus(err)` also live on the root barrel — decode an
+unknown thrown value into something renderable, folding an HTTP status into the fallback when the
+body decodes to nothing usable (`''`, `'{}'`, `'[object Object]'`, …). `BasaltQueryDevtools` (lazy)
+is there too.
 
 #### Rendering a query — `QueryState`
 
-Imported from **`basalt-ui`**, not `basalt-ui/query`: it renders Mantine, and `./query` is a
-guard-enforced Mantine-free entry.
-
 ```tsx
 import { QueryState } from 'basalt-ui'
 
@@ -610,9 +614,10 @@ bun add @mantine/notifications
 ```
 
 ```tsx
-import { BasaltNotifications, notifySuccess, notifyError } from 'basalt-ui/notifications'
+import { notifySuccess, notifyError } from 'basalt-ui/notifications'
+import { BasaltOverlays } from 'basalt-ui/commands'
 
-// in main.tsx: <BasaltProvider><BasaltNotifications /><App /></BasaltProvider>
+// in main.tsx: <BasaltProvider><BasaltOverlays notifications><App /></BasaltOverlays></BasaltProvider>
 notifySuccess('Saved')
 notifyError('Upload failed', { title: 'Error' })
 ```
@@ -633,17 +638,17 @@ export const COMMANDS = defineCommands({
 runCommand('file:save')
 ```
 
-### `./data` — TanStack Table + Virtual
+### `./data/table` + `./data/virtual` — TanStack Table + Virtual
 
-`./data` is a convenience barrel that pulls in both peer groups. Prefer the fine subpaths below
-for per-feature opt-in — each only requires its own peer.
+Two subpaths, one per peer group (C1: there is no bare `./data` barrel) — install only what you
+use.
 
 ```bash
 bun add @tanstack/react-table @tanstack/react-virtual
 ```
 
 ```tsx
-import { BasaltDataTable, BasaltVirtualList, createColumnHelper } from 'basalt-ui/data'
+import { BasaltDataTable, createColumnHelper } from 'basalt-ui/data/table'
 
 const col = createColumnHelper<Row>()
 const columns = [
@@ -825,66 +830,11 @@ Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `
 
 ## CLI
 
-```bash
-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` ONLY if basalt is not installed here
-bunx basalt-ui fonts:css --out src/fonts.css       # emit the shipped --basalt-font-* stacks — same exception
-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
-workspace packages the root declares, then a two-level layout scan. Two candidates is reported as
-ambiguous, never guessed. The scan is what a repo declaring **no `workspaces` field** needs — with
-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, 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.
-
-**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.
-
-**Three commands are the sanctioned exception, and only when basalt is not installed in the repo:**
-`init` (which predates the install by definition) and `tokens:css` / `fonts:css` (the framework-free
-route, where there is nothing to install). In a repo that _does_ carry basalt — which includes every
-tokens-only consumer that keeps it as a devDependency — run those through the local bin too.
-
-`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`
-apart: `recreated` means the ledger placed that file once and it went missing. On a
-`"basalt": { "profile": "tokens-only" }` consumer there is no scaffold to reconcile, so `sync`
-prints `n/a` and exits 0 — `sync --check` is wirable into a tokens-only repo's CI without a
-special case. `sync` also heals a `DESIGN.md` opener that still names a version: the file is a
-**seed**, written once and never reconciled, so any number stamped into it was stale by the next
-release.
-
-**`sync` refreshes an existing install; it does not create one.** It resolves its project exactly as
-`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 — 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.
-
----
+`basalt-ui help` prints full usage (every subcommand also takes `--help`/`-h`); `AGENTS.md` at the
+install directory is the machine-readable companion. Run the **local bin, not `bunx`** —
+`./node_modules/.bin/basalt-ui` or a `package.json` script; `bunx` can silently run a cached version
+you've upgraded away from. The one sanctioned `bunx` invocation is `init`, because nothing is
+installed yet.
 
 ## Toolchain
 
@@ -901,6 +851,17 @@ The `./configs/*` export gives consumer apps raw presets to `extends` or copy vi
 { "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }
 ```
 
+`tsconfig.json` `extends` resolves the SAME way, through package exports (`bundler`
+`moduleResolution`, CI-verified by `scripts/pack-test.sh`) — three raw presets, `base` (the shared
+strict flags), `react-app` (`base` + DOM/JSX libs) and `node` (`base` + Node types):
+
+```json
+{ "extends": "basalt-ui/configs/tsconfig.react-app.json" }
+```
+
+`.oxfmtrc.json` has no `extends` of its own — copy `configs/oxfmt.json` verbatim (`basalt-ui init`
+does this for you).
+
 ---
 
 ## `basalt-ui sync` in CI