basalt-ui 1.27.0 → 1.29.0

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)
@@ -101,7 +101,12 @@ import { App } from './App'
 import { paletteGroups } from './theme/series'
 
 // The theme lab owns only the editing UI — the host re-applies any persisted overrides at boot, so
-// a tuning session survives a refresh.
+// a tuning session survives a refresh. `applyOverrides`/`loadOverrides` (and `readVar`) live in
+// `theme-lab/boot.ts`, a Mantine-free, SSR-safe module re-exported through this same
+// `basalt-ui/theme-lab` subpath — no `document` guard needed at the call site, and it never throws
+// under SSR. A production bundler that tree-shakes unused named exports drops `ThemeLabControls`'s
+// Mantine imports when a prod entry (like this one) only ever names these three functions; an
+// unbundled dev build still evaluates the whole subpath module.
 applyOverrides(loadOverrides())
 
 const theme = createBasaltTheme({
@@ -123,6 +128,31 @@ createRoot(document.getElementById('root')!).render(
 > `@mantine/spotlight/styles.layer.css` if you install those optional-peer batteries
 > (`./notifications` / `./commands` — see [Adapter batteries](#adapter-batteries) below).
 
+### Composition order
+
+The canonical stack, once a router and a query client join the example above:
+
+```tsx
+<BasaltProvider theme={theme}>
+  <QueryClientProvider client={queryClient}>
+    <BasaltOverlays>
+      <RouterProvider router={router} />
+    </BasaltOverlays>
+  </QueryClientProvider>
+</BasaltProvider>
+```
+
+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
+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.
+
+**No `'use client'` directive ships anywhere in the package.** A Next.js App Router consumer wraps
+this whole composition in its own client file (`'use client'` at the top) and renders that from a
+server layout — basalt stays framework-agnostic and does not guess at the boundary.
+
 ### Theming
 
 The shipped palette isn't a fixed set of hexes — it's **generated** from one accent seed + five
@@ -142,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.
@@ -215,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
@@ -302,7 +332,7 @@ deleted rather than silently surviving into the next real skew.
 | `./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`, `field`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -568,7 +598,7 @@ bun add @mantine/form
 ```
 
 ```tsx
-import { useBasaltForm, field, FormErrorSummary } from 'basalt-ui/forms'
+import { useBasaltForm, inputProps, FormErrorSummary } from 'basalt-ui/forms'
 
 const form = useBasaltForm({ initialValues: { email: '' } })
 ```
@@ -580,9 +610,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' })
 ```
@@ -795,66 +826,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
 
@@ -871,6 +847,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

package/agent/rules/basalt-batteries.md

@@ -9,197 +9,89 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — none · oxlint rules — basalt/agent-no-raw-usechat, basalt/agent-resume-guard, basalt/ai-sdk-major -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
+<!-- backed by: guard kinds — none · oxlint rules — basalt/agent-no-raw-usechat, basalt/agent-resume-guard, basalt/ai-sdk-major, basalt/forms-field-key, basalt/query-dual-import, basalt/query-fn-unwrap -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
 # Basalt Batteries — the adapter surfaces
 
-Each battery is a subpath with **one** doctrine: the shipped seam is the seam, and re-rolling it is
-the failure this rule exists to prevent. Every peer named below is OPTIONAL — install it before
-importing the battery. The API is in the shipped types, the JSDoc and `llms.txt` at the install
-directory; what follows is only what a reader gets wrong without being told.
-
-## `./query` — TanStack Query
-
-`@tanstack/react-query` is a REQUIRED peer (`BasaltProvider` needs it at build time). Import the
-hooks from `basalt-ui/query`, never dual-import from `@tanstack/react-query`.
-
-- **One factory per resource**, keyed `[resource, action, ...params]`, built with `queryOptions`;
-  components import the factory, never a raw string key.
-- **`queryFn` wraps the call in `unwrap()`** — it throws on the error branch AND on a `null` data
-  with no error (a 204, a silent transport failure). Both are caller bugs, so both must surface.
-- **Render a query with `QueryState`, don't write the switch.** Rendering only the empty branch is
-  the bug it retires: a consumer's library showed `No images` on a 500 because nobody wrote the other
-  three branches. Precedence is error-without-data → empty → loading → children, plus a cached-data
-  banner when a refresh fails over existing data. `LoadingState`/`ErrorState` ship beside it for a
-  page that must place the branches in different DOM positions.
-- **`QueryState` takes `useQuery`, not `useSuspenseQuery`** — a suspense read never hands you an
-  undefined `data` or an error branch, so there is nothing to decide. Suspense + an error boundary
-  and `QueryState` are the two ways to render a query; pick ONE per read. Inside a
-  loader-prefetched route, `useSuspenseQuery` + `ensureQueryData` is the pair.
-- **`query` is a structural subset checked at runtime** — a composed or hand-rolled result passes
-  with no cast, and a missing `isError` throws naming the field rather than rendering a false claim.
-- Decode an unknown error with `toErrorMessage(err, fallback?)` / `errorStatus(err)`; invalidate by
-  resource PREFIX after a mutation; `BasaltQueryDevtools` is lazy and production-excluded, so import
-  it unconditionally and never the raw devtools package.
+Each battery is a subpath with **one** doctrine: the shipped seam is the seam, re-rolling it is the
+failure this rule prevents. Every peer is OPTIONAL — install before importing. Full API: the
+shipped types, JSDoc and `llms.txt` at the install directory — this file is only what a reader gets
+wrong without being told.
+
+**Not guarded, honestly**: `forms`, `notifications`, `commands`, `data` and `content` carry zero
+guard kinds or oxlint rules — the `not guarded: —` line above is real, not aspirational. Nothing
+fails a build if you re-roll one of these seams by hand; follow the doctrine below on trust.
+
+**Deprecation, as a consumer sees it.** A `basalt/deprecated-export` warn means the export still
+works but leaves in a stated `removeIn` minor (autofix renames the import, keeps your local
+binding). The replacement and removal minor are always in `MIGRATING.md` § Unreleased the moment
+the deprecation ships — that file, not the warning text, is where you confirm what to migrate to.
+Maintainer mechanics: package `CLAUDE.md` § Deprecation lifecycle.
+
+## Query — `createBasaltQueryClient`/`unwrap` (root barrel, C1: `./query` dropped)
+
+`unwrap()` throws on the error branch AND on a `null` data with no error — both are caller bugs.
+Render with `QueryState`, never a hand-written switch (precedence: error-without-data → empty →
+loading → children). One factory per resource via `queryOptions`, never a raw string key.
 
 ## Eden Treaty — three silent `any`s (stated once)
 
-Stated here because they reach both `./query`'s `unwrap` and `./agent`'s transport. Three
-patterns silently degrade Treaty inference to `any`, with no TypeScript error at the point of
-breakage: a route that is not method-chained back onto the app instance; client and server packages
-whose tsconfig path aliases do not resolve identically; and a `t.Object`/`t.Union` **response schema
-on a streaming route** (Eden #231, still open). For a stream: no response schema, an explicit
-`: AsyncGenerator<AgentPart>` return annotation, and validation at yield time via `parseAgentPart`.
-Check these three first whenever Eden types regress.
+Reaches both `unwrap` and `./agent`'s transport: an un-chained route, mismatched tsconfig path
+aliases, and a response schema on a streaming route (Eden #231) all silently degrade inference to
+`any`. Check these three first when Eden types regress.
 
 ## `./forms` — `@mantine/form`
 
-- **`useBasaltForm` is the entry**: `mode: 'uncontrolled'` by default (no per-keystroke re-render)
-  and `schemaResolver(schema, { sync: true })` when a `schema` is passed. Type a schema param as
-  `StandardSchemaV1` from `basalt-ui`, never `ZodSchema` — Valibot, Zod 4, ArkType and Effect all
-  satisfy it structurally.
-- **`validate` is deliberately omitted** from its options — a cross-field or async rule that the
-  schema cannot express drops to a raw `useForm`.
-- **`field(form, path)` is the one spread** every uncontrolled Mantine field needs (it bundles
-  `getInputProps` + `key`); writing the two by hand is how one gets forgotten.
-- **`FormErrorSummary` goes at the TOP of the form** so assistive tech lands on it after a failed
-  submit. It renders `null` on a clean form, so include it unconditionally.
-- **`useFormDraft` persists through `createPersistedState`** — wire `saveDraft` into
-  `onValuesChange` for autosave, call `clearDraft()` in the success path, keep `key` stable across
-  renders (changing it recreates the store and loses the draft) and bump `version` on a shape change.
-- Errors are inline field errors; a toast is for submit-level failure only.
+`useBasaltForm` (`mode: 'uncontrolled'`, `StandardSchemaV1` never `ZodSchema`) +
+`useFormSubmit`/`useFieldArray`/`FormErrorSummary`/`useFormDraft`. A field is two calls, never one
+object (`basalt/forms-field-key` guards + autofixes it) — dropping `key` keeps stale text through
+`form.reset()`.
 
 ## `./notifications` — `@mantine/notifications`
 
-- **`notify({ intent, message })` is the surface**, plus the four `notifySuccess/Error/Warning/Info`
-  wrappers and `notifyPromise` for an async operation. Intent — not a color — is what maps to the
-  Mantine color, the correct aria `role` (polite vs assertive) and the per-intent `autoClose`, so
-  **never pass a raw color instead of an intent**.
-- **`defineNotifications` + `emit` is the typed registry**: augment `BasaltRegister.notifications`
-  once and unknown kinds become tsc errors. `defineNotification` only TYPES a single spec — only
-  `defineNotifications(map)` registers, and `emit` before that registration is a runtime no-op.
-- **A spec carries no `title`/`icon`** by design; those stay per-call so a varying title is not
-  forced into the registry.
-- **Colors beyond the four intents live OUTSIDE the registry** — call Mantine's raw
-  `notifications.show({ color })` directly, and accept the stated cost: a raw toast is invisible to
-  the persisted history, the bell and the center, because only `notify`/`notifyPromise` record.
-- History is a module-level persisted ring buffer; `useNotificationHistory` reads it, and
-  `NotificationBell` (built for the shell's `globalActions`) opens a `NotificationCenter`, which also
-  mounts standalone in any Drawer or panel.
-- The overlay MOUNT is basalt-mantine.md's — one place, one statement.
+`notify({ intent, message })` — intent, never a raw color, drives the Mantine color AND the aria
+`role`. `defineNotifications`/`emit` is the typed registry; only persisted-history calls
+(`notify`/`notifyPromise`) reach the bell/center. `notifyUndo` owns the undo-window contract.
 
 ## `./commands` — the command bus
 
-- **`defineCommands` + `runCommand`, `defineOverlays` + `overlays.open`** — augment
-  `BasaltRegister` once per registry and unknown ids are tsc errors. The augmentation is type-only
-  and erased, so both factories stash their map at module scope: call the factory once, at app boot,
-  before anything runs a command.
-- **A TS circular-inference footgun**: `overlays.open(...)` inside a `run` in the same module that
-  augments `BasaltRegister.commands` can make the map infer as `any`. Annotate that `run`'s return
-  type explicitly, or split overlay-opening commands into their own file.
-- **Projections, not parallel lists**: `toSpotlightActions()` (respecting each command's `when()`),
-  `toShortcutList()` / `ShortcutsHelp` for display, `toHotkeyBindings()` / `useCommandHotkeys()` for
-  the live keys. Never hand-author a second list of the same commands.
-- Reach for `openSpotlight`/`closeSpotlight` from `basalt-ui/commands`, not Mantine's global
-  `spotlight` — `BasaltOverlays` mounts against basalt's own store.
-- **Imperative overlay vs route**: `overlays.open` for an ephemeral confirm or quick edit; a route
-  for anything that must be shareable, refreshable or back-button-addressable.
-
-## `./data` — TanStack Table + Virtual
-
-- **Read the props before hand-rolling anything**: title/icon/subtitle + count, an `actions`
-  toolbar slot, `facets`, global search, client- or server-side pagination, column pinning, sticky
-  header, `maxHeight`/`minWidth`, per-column `meta.align` and `meta.numeral` are all there.
-  `meta.align` is a `ColumnMeta` augmentation, so a typo is a tsc error and a bad VALUE throws naming
-  the column — declare alignment once instead of on both the `th` and the `td`.
-- **Adopt it for ownership, not for a line count.** One consumer's port ran 29–38 lines LONGER:
-  accessor blocks cost more than bespoke `<Table.Td>` rows. What it buys is the `type="native"`
-  scroll footgun, alignment stated once, and sorting/filtering/pagination no longer being yours.
-  A table with no sorting, no pagination, no filter and no alignment to declare is a layout grid —
-  adopting the component there buys nothing.
-- **`manualPagination` imposes a contract on every other prop**: `data` becomes one server page
-  while the bar still claims `of N`, so sorting (`manualSorting` or `enableSorting={false}`),
-  filtering (`manualFiltering`) and the count (`rowCount`) must each be resolved explicitly.
-  Unresolved, it throws in dev naming every breach and degrades to the honest table in production.
-  Read the throw; don't work around it.
-- **The escape hatch is the same subpath**: `useReactTable`/`flexRender`/the row models are
-  re-exported, so a bespoke table needs no direct `@tanstack/react-table` import — and it scrolls
-  through the identical `Table.ScrollContainer type="native"` node.
-- **`BasaltVirtualList` above a few hundred rows**; below that a plain `Stack`/`Table` is cheaper.
-  It sets `useFlushSync: false` for React 19 itself — do not override it.
+`defineCommands`/`runCommand`, `defineOverlays`/`overlays.open` — call each factory once, at app
+boot. Project via `toSpotlightActions`/`toShortcutList`/`toHotkeyBindings`, never a hand-authored
+second list. `overlays.confirm`/`confirmDelete` need no registry entry.
+
+## `./data/table` + `./data/virtual` — TanStack Table + Virtual (C1: no bare `./data`)
+
+Read the props before hand-rolling anything (facets, pagination, `meta.align`/`meta.numeral`).
+`manualPagination` imposes a contract on sorting/filtering/count — unresolved, it throws in dev.
+`BasaltVirtualList` above a few hundred rows only.
 
 ## `./content` — prose, markdown, MDX
 
-- **Three entries, one typography layer**: `Prose` (JSX children), `Markdown` (a string — CMS,
-  files, streamed model output), `mdxComponents` (an MDX pipeline's component map). `Markdown` wraps
-  its own `Prose`; MDX output does not, so wrap it or use `ArticleLayout`.
-- **`streaming` is a RENDERING mode, not a trust claim.** `contentTrust` is the independent security
-  input and the sole input to the image-origin allowlist: **any surface rendering agent or model
-  output must pin `contentTrust="untrusted"`** — an auto-fetched image is the classic
-  prompt-injection exfiltration channel. Link/script hardening is always on, streaming or not, and
-  `sanitizeSchema` only ADDS to the default schema.
-- **Every optional peer degrades, except one.** No `shiki` (or an unknown language) renders a plain
-  mono block; no `beautiful-mermaid` leaves the fence as code; `remend`'s streaming repair and the
-  markdown renderer resolve lazily. Six mermaid diagram types are covered — anything else is a
-  consumer escape hatch outside `Markdown`.
-- **`ArticleLayout` is the docs frame** (meta header, sticky scroll-spy TOC, prev/next); every
-  linking content component takes `renderLink` as the router bridge and defaults to a plain anchor.
-- **The Article model is data + pure operators**, generic over the taxonomy — the app declares which
-  categories and tags exist (`satisfies readonly Article<Cat, Tag>[]`, deliberately no factory).
-  Filter state is store fields, and the filter UI is `FilterSet`/`ViewTabs`/`MultiSelectFilter`,
-  re-exported here so a content-only consumer has one import path (basalt-controls.md).
-- Build-time content tooling (`content-collections`) is a RECIPE, not a dependency; its vite plugin
-  must run FIRST because other transforms resolve its virtual module.
+`Prose`/`Markdown`/`mdxComponents` share one typography layer. `streaming` is a rendering mode, not
+a trust claim — any surface rendering agent/model output pins `contentTrust="untrusted"`. Every
+optional peer degrades gracefully except the sanitizer, which is always on.
 
 ## `./agent` + `./agent-chat` — streaming chat
 
-- **`./agent` is headless and Mantine-free; the chrome is `./agent-chat`.** `./agent` ships no
-  markdown renderer at all (`agent → content` is lint-blocked), so `PartList` takes a
-  consumer-supplied `components.text`; basalt's own is `./content`'s `Markdown`.
-- **Every switch over `AgentPart` ends with `default: return assertNever(part)`** — that is what
-  makes a new variant a compile error instead of a silently dropped part.
-- **`aiSdkTransport` is the recommended default** (optional peer `ai`, resolved lazily on first
-  stream); `edenTransport` is the zero-extra-dependency alternative. Neither is deprecated. The
-  transport is an injected seam, so a mock is just an object with a `stream` generator.
-- **`useAgentStream` runs ONE turn; `useAgentThreadRuns` runs N keyed by thread id.** Reach for the
-  latter for the many-short-chats shape, with `createThreadsStore` as its persisted registry.
-- **basalt ships the outcome-resolver SEAM, never an LLM call.** `heuristicOutcome` is a demo
-  fallback; production derives `{ title, summary, status }` from the finished run. The outcome shape
-  is deliberately DIFFERENT from the transcript so raw prompts and thinking cannot leak into a feed.
-- **Stream resumption is a client contract, not a backend**: a `StartPart` carries the token, the
-  transport implements `resume`, and a mount-time reconnect is attempted before an orphaned thread
-  falls back to interrupted. A transport that does neither behaves exactly as before.
-- **Three lint guards protect this discipline** — an unguarded `resume`, a raw `useChat`, and an `ai`
-  major mismatch — and they honour `basalt-agent-allow`, never `theme-allow`. `doctor`'s
-  `ai-major-parity` is the cross-package counterpart, because a lint run only ever sees one
-  package's manifest.
+`./agent` is headless/Mantine-free; `./agent-chat` is the chrome. Every `AgentPart` switch ends
+`default: return assertNever(part)`. `useAgentStream` runs one turn, `useAgentThreadRuns` runs N by
+thread id. Stream resumption reconnects a MOUNT (page reload mid-stream), it never continues a
+click — `retry()`/`regenerate()` always start a fresh stream from the cached input.
+
+**Why the three lint guards exist** (a consumer's build fails on one of these; all honour
+`basalt-agent-allow`, never `theme-allow`): `basalt/agent-resume-guard` — an unguarded
+`resumeStream()`/`useChat({ resume: true })` re-fires under StrictMode with no dedup, use
+`useAgentThreadRuns` instead. `basalt/agent-no-raw-usechat` — bypassing the basalt hooks loses the
+unmount-abort and supersede guards. `basalt/ai-sdk-major` (+ `doctor`'s `ai-major-parity`) — a v5
+stream parsed by a v7 reader throws; nothing else pins the `ai` major across packages.
 
 ## App bootstrapping — `./vite`, CSS order, `init`
 
-- **`basaltViteConfig` is config-only and always will be; `basaltAppPlugin` is the plugin half** —
-  spread it into your own `plugins` array. Keeping plugins out of the preset is why adopting it never
-  injects one you did not ask for. Position is free (`vite-plugin-pwa` self-orders by `enforce`); the
-  one real caveat is a plugin emitting files from its own `closeBundle` after the PWA plugin's.
-- **CSS layer order is load-bearing**: every `@mantine/*/styles.layer.css` first, then
-  `basalt-ui/styles.css`. An unlayered Mantine import outranks `@layer basalt` regardless of
-  specificity.
-- **Head, manifest and theme colors come from the token palette** — never hand-compute a
-  `theme-color` hex or an anti-FOUC background, and set `colorScheme` to whatever the app passes as
-  `defaultColorScheme` or you ship a flash of the wrong surface. Icons are bring-your-own: either
-  the six default filenames under `public/`, or an `icons` array naming what you actually have (an
-  entry reaches the head only when it names a `rel`; every entry becomes a manifest icon). The
-  service worker is opt-in and degrades to a warning without its peer.
-- **`init` on an existing app is a lint-debt event, not a no-op** — the shipped preset turns on
-  whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
-  findings. Triage them; do not blanket-disable a plugin. It also patches `basalt.roots` (everything
-  derives from it) and a `lint:basalt` script, and it KEEPS an existing `.oxlintrc.json`, which
-  leaves the whole basalt lint half off until you extend the preset.
-- **The lefthook preset overrides YOU on a colliding key** — a `run:`/`glob:` under one of its
-  command names is discarded silently, while `env:`, `exclude:`, `skip:` and your own command names
-  merge; `BASALT_BIN` is the sanctioned seam. A broken `extends` target is a hard fail: lefthook
-  merges a missing target into ZERO commands and still exits 0.
-- **Then run `doctor` and read it to the last line.** `SKIPPED` is a third outcome that exits
-  non-zero on its own — a check that could not run is not a check that passed.
+`basaltViteConfig` is config-only; spread `basaltAppPlugin` into your own `plugins`. CSS layer
+order is load-bearing: every `@mantine/*/styles.layer.css` first, then `basalt-ui/styles.css` — an
+unlayered Mantine import outranks `@layer basalt` regardless of specificity. `init` on an existing
+app is a lint-debt event, not a no-op — triage the new findings, don't blanket-disable a plugin.
+Run `doctor` after and read it to the last line (`SKIPPED` exits non-zero on its own).