basalt-ui 1.40.3 → 2.0.0

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

@@ -1,100 +1,257 @@
 ---
 name: basalt-app
-description: Scaffold or refresh a basalt-ui app — the procedure around `basalt-ui init` (first-time scaffold) and `basalt-ui sync` (drift-managed refresh), plus the runtime wiring neither of them does for you (provider, shell, vite, CSS order). Use when setting up basalt-ui in a new or existing app, after upgrading it, or when the shipped doctrine seems missing.
-when_to_use: User is adding basalt-ui to a new or existing app, asks how to set it up or scaffold it, wants to wire BasaltProvider / BasaltShell / the vite preset, refresh the shipped rules after an upgrade, or wire a freshness check in CI. Also when /basalt-design reports no consumer DESIGN.md.
+description: Scaffold, wire, verify or upgrade a basalt-ui app — `basalt-ui init`, `doctor`, `sync`, and the 1.x to 2.0 upgrade path.
+when_to_use: User is adding basalt-ui to an app, wiring BasaltProvider / BasaltShell / the vite preset, upgrading basalt-ui, refreshing the shipped rules, or wiring a freshness check in CI. Also when /basalt-design reports no DESIGN.md.
 ---
 
-`/basalt-app` gets a consumer scaffolded and keeps its shipped doctrine fresh. Everything — the
-components, the toolchain presets, the rules, the skills, the templates — ships in the one npm
-package; `init` places it and `sync` refreshes it.
+Procedure only; the law is `.claude/rules/basalt-*.md`.
 
-## 1. Install and scaffold
+## Scaffold
 
-```bash
-bun add basalt-ui
-bunx basalt-ui init                        # the ONE command that legitimately predates the install
-./node_modules/.bin/basalt-ui --version    # every command after it: the LOCAL bin
+1. `bun add basalt-ui && bunx basalt-ui init` (the only `bunx` call; use `./node_modules/.bin/basalt-ui` after).
+2. Check the seeded `src/main.tsx` (`init` writes it when absent); `basalt-ui/styles.css` is the only stylesheet import:
+
+```tsx
+// @check
+import 'basalt-ui/styles.css'
+import { createRoot } from 'react-dom/client'
+import { BasaltProvider, createBasaltRouter } from 'basalt-ui'
+import { routeTree } from './routeTree.gen'
+const router = createBasaltRouter({ routeTree })
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+createRoot(document.getElementById('root')!).render(<BasaltProvider router={router} />)
 ```
 
-`init` writes the managed doctrine (`.claude/rules/basalt-*.md`, `.claude/skills/basalt-*/SKILL.md`,
-the `CLAUDE.md` block), the seeds you then own (`DESIGN.md`, `.oxlintrc.json`, `.oxfmtrc.json`,
-`lefthook.yml`, CI, optional scaffolds), and `.basalt/manifest.json` — a sha256 per managed unit so
-`sync` can three-way diff. It also patches `basalt.roots` and a `lint:basalt` script.
+3. If you use `basalt-ui/controls-dates`, import `@mantine/dates/styles.layer.css` after `basalt-ui/styles.css` (core must precede dates in `@layer mantine`).
+4. Install the peers of each subpath you import: read its `Install: bun add …` line in `node_modules/basalt-ui/llms.txt`; a subpath with no `Install:` line needs only the required peers listed at the top of that file.
+5. In `vite.config.ts` spread `...basaltViteConfig({ port, apiTarget })` and register, in this order, `plugins: [tanstackRouter({ target: 'react', autoCodeSplitting: true }), react(), ...basaltAppPlugin({ name, description })]`. Run `bun add -d @tanstack/router-plugin` and import `tanstackRouter` from `@tanstack/router-plugin/vite`.
+6. Run `vite build` once so the plugin writes `src/routeTree.gen.ts`; commit it (`tsc -b` fails without it).
+7. In `src/routes/__root.tsx`: `<BasaltShell brand={{ name }} nav={NAV}><Outlet /></BasaltShell>`; build `NAV` with `defineNav` in `src/lib/nav.tsx`.
+8. Add a page as a file route, and link to it with `navTarget`:
 
-Two modes, decided by one question — **does Claude read this file?** Managed files are
-framework-owned and meant to be overwritten (the sync diff is the review gate); seeds are written
-once and yours forever. Claude Code cannot load rules or skills out of `node_modules`, which is the
-only reason anything is copied at all; everything a MACHINE reads is an `extends` reference into
-`node_modules/basalt-ui/configs/`, so the toolchain auto-updates with the package.
+```tsx
+// @check
+import { Link, createFileRoute, linkOptions } from '@tanstack/react-router'
+import { defineNav, navGroup, navTarget } from 'basalt-ui'
+// src/routes/dashboard.tsx — the breadcrumb and page title come from the nav item's `label`; export the component too (react/only-export-components)
+export const Route = createFileRoute('/dashboard')({ component: Dashboard })
+export function Dashboard() {
+  return <h2>Dashboard</h2>
+}
+// src/lib/nav.tsx
+export const NAV = defineNav({
+  groups: [
+    navGroup({ id: 'main', label: 'Main' }, [
+      { id: 'dashboard', label: 'Dashboard', link: linkOptions({ to: '/dashboard' }) },
+    ]),
+  ],
+})
 
-**`init` on an existing app is a lint-debt event, not a no-op** — `.claude/rules/basalt-batteries.md`
-§ "App bootstrapping" says what it turns on. Too much at once? Extend `configs/oxlint-basalt.json`
-(the basalt/\* guards alone, no generic jsx-a11y/unicorn set) first, `configs/oxlint.json` later —
-the full one pairs with the shipped `tsconfig.react-app.json` (ES2023 lib: `unicorn/no-array-sort`
-steers to `toSorted()`).
+// anywhere
+export const ToDashboard = () => <Link {...navTarget(NAV, 'dashboard')}>Dashboard</Link>
+```
 
-## 2. Wire the runtime (the CLI scaffolds files, not your app's composition)
+9. Fill in `DESIGN.md` (identity, series dictionary, deviations).
+
+## Add a table
+
+A table is `BasaltDataTable` with columns from `createColumnHelper`; it has no `count` prop (with `title`, the header counts the rows itself):
 
 ```tsx
-// main.tsx — CSS order is load-bearing: every @mantine/*/styles.layer.css, THEN basalt's
-import '@mantine/core/styles.layer.css'
-import '@mantine/notifications/styles.layer.css' // one per MOUNTED battery: notifications, spotlight…
-import '@mantine/spotlight/styles.layer.css'
-import 'basalt-ui/styles.css'
-import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
-import { BasaltOverlays } from 'basalt-ui/commands'
-;<BasaltProvider theme={createBasaltTheme(/* app deltas only */)} defaultColorScheme="dark">
-  <BasaltOverlays>{/* data layer, then the router */}</BasaltOverlays>
-</BasaltProvider>
+// @check
+import { money } from 'basalt-ui/format'
+import { BasaltDataTable, createColumnHelper } from 'basalt-ui/table'
+
+type Row = { id: string; name: string; revenue: number }
+const col = createColumnHelper<Row>()
+const columns = [
+  col.accessor('name', { header: 'Name' }),
+  col.accessor('revenue', {
+    header: 'Revenue',
+    sortFn: 'basic', // v9 `sortFn`, not v8 `sortingFn`
+    meta: { align: 'right' }, // numbers are mono-numeral by default; `numeral: false` opts out
+    cell: (c) => money(c.getValue(), { currency: 'USD' }),
+  }),
+]
+export const Revenue = ({ rows }: { rows: Row[] }) => (
+  <BasaltDataTable data={rows} columns={columns} getRowId={(r) => r.id} />
+)
 ```
 
-```ts
-// vite.config.ts — the preset is config-only; the plugin half is spread into your own plugins
-export default defineConfig({
-  ...basaltViteConfig({ port: 5173, apiTarget: 'http://localhost:3000' }),
-  plugins: [react(), ...basaltAppPlugin({ name: 'MyApp', description: '…' })],
+## Stream a slow section
+
+The shell holds no promise; the loader returns the slow promise unawaited (settled, so a failure renders the chart's error state), and the fallback is the same chart pending (it fills the final box):
+
+```tsx
+// @check
+import { Await, createFileRoute } from '@tanstack/react-router'
+import { Suspense } from 'react'
+import { Lines } from 'basalt-ui/charts'
+import type { ChartSeries, ChartState } from 'basalt-ui/charts'
+import { VX } from 'basalt-ui/tokens'
+type P = { t: number; v: number }
+declare const fetchPoints: () => Promise<P[]>
+const series = [
+  { key: 'v', label: 'Value', color: VX.accent, getValue: (p) => p.v },
+] satisfies ChartSeries<P>[]
+const chart = (data: P[], state: ChartState) => (
+  <Lines ariaLabel="Value" data={data} x={(p) => p.t} series={series} state={state} />
+)
+export const Route = createFileRoute('/live')({
+  loader: () => ({
+    points: fetchPoints().then(
+      (data) => ({ data }),
+      (error: unknown) => ({ data: [], error }),
+    ),
+  }),
+  component: Live,
 })
+export function Live() {
+  const { points } = Route.useLoaderData()
+  return (
+    <Suspense fallback={chart([], { pending: true })}>
+      <Await promise={points}>
+        {(r) => chart(r.data, { error: r.error, empty: r.data.length === 0 })}
+      </Await>
+    </Suspense>
+  )
+}
 ```
 
-Then `BasaltShell` with a `useNav(NAV)` spread (basalt-state.md), `PageBar` per page
-(basalt-controls.md), `PageAside` on any page that needs a right-hand inspector — a region a ROUTE
-claims rather than a shell prop, so it never appears in `BasaltShell`'s props — and
-`<first basalt.root>/lib/series.ts` as the app's one guard-exempt series source (`/basalt-charts`).
-There is no Tailwind.
+## Add a chat
 
-## 3. Verify the wiring took
+1. Install the `basalt-ui/agent` peers from its `Install:` line in `llms.txt`.
+2. Implement `ThreadsStore` (in memory here), bind one transport per thread, compose the feed:
 
-```bash
-./node_modules/.bin/basalt-ui doctor      # read it to the LAST line
-bun run lint:basalt                       # oxlint . && basalt-ui check-theme
-```
+```tsx
+// @check
+import { Button } from '@mantine/core'
+import { useState } from 'react'
+import { ThreadFeed, ThreadFeedRow, aiSdkTransport, useAgentThreadRuns } from 'basalt-ui/agent'
+import type { AgentPart, AgentThread, AgentTransport, ThreadsStore } from 'basalt-ui/agent'
+
+type Thread = AgentThread<AgentPart>
 
-`SKIPPED` is a third outcome beside pass/warn/fail and **exits non-zero on its own** — a check that
-could not run is not a check that passed. Expect doctor to go red where an older basalt was green;
-that is the point. Then triage `oxlint .` before the next commit.
+function useMemoryStore(): ThreadsStore<AgentPart> {
+  const [threads, setThreads] = useState<Thread[]>([])
+  const [activeId, select] = useState<string | null>(null)
+  const patch = (id: string, change: (t: Thread) => Thread) =>
+    setThreads((all) => all.map((t) => (t.id === id ? { ...change(t), updatedAt: Date.now() } : t)))
+  return {
+    threads,
+    activeId,
+    select,
+    hydrated: true,
+    error: undefined,
+    create: () => {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const blank: Thread = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: true,
+        createdAt: now,
+        updatedAt: now,
+      }
+      setThreads((all) => [blank, ...all])
+      return id
+    },
+    appendMessage: (id, m) => patch(id, (t) => ({ ...t, messages: [...t.messages, m] })),
+    setOutcome: (id, outcome) => patch(id, (t) => ({ ...t, outcome })),
+    setStatus: (id, status) => patch(id, (t) => ({ ...t, status })),
+    setResumeToken: (id, token) =>
+      patch(id, ({ resumeToken: _old, ...t }) =>
+        token === undefined ? t : { ...t, resumeToken: token },
+      ),
+    markRead: (id) => patch(id, (t) => ({ ...t, read: true })),
+    remove: (id) => {
+      setThreads((all) => all.filter((t) => t.id !== id))
+      select((current) => (current === id ? null : current))
+    },
+    clear: () => {
+      setThreads([])
+      select(null)
+    },
+  }
+}
 
-## 4. Refresh after every upgrade
+const base = aiSdkTransport<AgentPart>({ api: '/api/chat' })
+// A mock (swap it in for `base.forThread(threadId)`). A text part is a DELTA: parts with the same
+// `id` are appended in order.
+export const mock: AgentTransport<AgentPart> = {
+  async *stream(input) {
+    const id = crypto.randomUUID()
+    for (const word of `Echo: ${input}`.split(' ')) yield { id, type: 'text', text: `${word} ` }
+  },
+}
 
-```bash
-./node_modules/.bin/basalt-ui sync        # --check in CI, --force to overwrite local edits
+export function Chat() {
+  const store = useMemoryStore()
+  const { runs, start, stop } = useAgentThreadRuns({
+    transport: (threadId) => base.forThread(threadId),
+    store,
+    resolveOutcome: (t) => ({
+      title: 'Chat',
+      summary: `${t.messages.length} turns`,
+      status: 'done',
+    }),
+  })
+  return (
+    <>
+      <Button onClick={() => store.select(store.create())}>New chat</Button>
+      <ThreadFeed
+        threads={store.threads}
+        activeId={store.activeId}
+        onSelect={store.select}
+        renderRow={(t) => {
+          const run = runs.get(t.id)
+          const live = run === undefined ? {} : { liveParts: run.parts, liveStatus: run.status }
+          return (
+            <ThreadFeedRow
+              key={t.id}
+              thread={t}
+              expanded={t.id === store.activeId}
+              onToggle={() => store.select(t.id === store.activeId ? null : t.id)}
+              {...live}
+              onSend={({ text }) => start(t.id, text)}
+              onStop={() => stop(t.id)}
+            />
+          )
+        }}
+      />
+    </>
+  )
+}
 ```
 
-- Unchanged since basalt wrote it → overwritten. Locally edited → diffed and SKIPPED. Missing →
-  recreated. **Retired upstream → deleted**, and named in the output; a rule file basalt stopped
-  shipping is doctrine your agent would otherwise keep reading.
-- `sync --check` makes no writes and exits non-zero on any of that — wire it as the freshness gate.
-- Run it anywhere in the repo: it resolves the project the way `check-theme` and `doctor` do,
-  announces a relocation, refreshes a PARENT install from a sub-package, and still refuses to
-  scaffold a second consumer (that stays `init`'s decision).
-- Seeds are never reconciled or reported. They are yours.
+3. `ThreadFeedRow` carries the `Composer`; tune it with `composerProps`.
 
-## 5. Not a React app?
+## Verify
 
-```bash
-bunx basalt-ui tokens:css --out src/tokens.css   # no install to resolve, so bunx is right here
-bunx basalt-ui fonts:css --out src/fonts.css
-```
+1. `./node_modules/.bin/basalt-ui doctor`; read to the last line. `SKIPPED` exits non-zero.
+2. Fix every finding doctor prints, then rerun until it is clean.
+3. `bun run lint:basalt` (`oxlint . && basalt-ui check-theme`); fix every finding at its source.
+4. `bunx tsc --noEmit`; fix every error without `as never` or `any`.
+
+## Refresh after any upgrade
+
+1. `./node_modules/.bin/basalt-ui sync` (`--check` in CI, `--force` overwrites local edits).
+2. Read its output: edited files are skipped, retired files are deleted, the AGENTS.md block is rewritten.
+
+## Upgrade 1.x to 2.0
+
+1. `bun add basalt-ui@latest`, then `./node_modules/.bin/basalt-ui sync`; it prunes retired managed files and rewrites the AGENTS.md block.
+2. `./node_modules/.bin/basalt-ui doctor`; fix each of doctor's checks: a tsconfig that does not extend the shipped base, `basalt/*` rule ids the plugin no longer has, and imports of subpaths 2.0 dropped.
+3. Work through `MIGRATING.md` § 2.0 (in the installed package): one row per removal or move; apply each that your code touches.
+4. Run the Verify steps above.
+
+## Not a React app
 
-Both carry the two-line `@generated basalt-ui` header the guard skips, and both take `--check` as a
-CI drift gate that ignores the provenance version — so a basalt bump alone never forces a no-op
-commit. Declare `"basalt": { "profile": "tokens-only" }` by hand; `check-theme` never infers it.
+1. `bunx basalt-ui tokens:css --out src/tokens.css` and `bunx basalt-ui fonts:css --out src/fonts.css`.
+2. Set `"basalt": { "profile": "tokens-only" }` in `package.json` by hand.

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

@@ -1,74 +1,40 @@
 ---
 name: basalt-charts
-description: Add or extend a chart in a basalt-ui app — the procedure: pick a shipped kind vs extract one vs stay bespoke (Rule of Three), register the consumer series with defineSeries/groupTokens, compose CartesianChart (or ChartFrame for a non-single-plot shape), then verify against the guards. Use when adding a chart, a new metric/series color, or extracting a repeated chart shape.
-when_to_use: User wants to add a chart, restyle one structurally, introduce a new metric/series and its color, extract a recurring chart shape into a reusable kind, or asks where chart series colors live and how to register them. The how-to companion to /basalt-design, which owns the aesthetic law.
+description: Add or extend a chart in a basalt-ui app — pick a shipped kind or compose CartesianChart, register series colors, verify.
+when_to_use: User wants to add or restyle a chart, introduce a metric and its color, or extract a repeated chart shape. Companion to /basalt-design.
 ---
 
-`/basalt-charts` is the HOW. `.claude/rules/basalt-charts.md` is the contract everything below
-assumes, and `/basalt-design` owns the aesthetic law — read both before writing chart code. The
-props themselves are in the shipped types and `llms.txt` at the install directory.
+Procedure only; the contract is `.claude/rules/basalt-charts.md`.
 
-## 1. Pick the path (Rule of Three)
+## Steps
 
-1. **A shipped kind fits** → use it. `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`, `DualPanel`,
-   `Heatmap`, `Donut`, `BandStrip`, `MirroredBars`. Read their props before assuming a gap: dual
-   axis, zones, thresholds, refLines, per-point markers, folding, per-series formatting and
-   `isPending` are all declarative already.
-2. **This is the SECOND instance of a shape with no kind** → extract a kind and migrate both call
-   sites. Not on the first, not past the third.
-3. **Genuinely unique** → stay bespoke in the page's own chart file, composing the primitive
-   directly. Not in a shared kinds directory.
-
-**Extracting a kind? Prove it by porting.** Move real call sites onto it and ship the list of what
-it could NOT express. A demo page is written against the API that already exists, so it proves
-nothing.
-
-## 2. Register the series (this is consumer data)
-
-`VX.series` does not exist in the framework — which metric owns which hue is domain data, declared
-in ONE guard-exempt file per app:
+1. Pick the path: a shipped kind fits (`Lines`, `Bars`, `Sparkline`, `StackedArea`, `DualPanel`, `MirroredBars`, `BandStrip`, `Donut`, `Heatmap`) → use it. A second chart of a shape with no kind → extract a kind and migrate both call sites. Otherwise compose `CartesianChart` in the page's own chart file.
+2. Register each new series color in the app's one series file (exempt from `check-theme`):
 
 ```ts
-// src/lib/series.ts — the one file exempt from check-theme, because it IS the palette source
-import { buildPaletteCss, defineSeries, groupTokens, seriesTokens } from 'basalt-ui/tokens'
+import { defineSeries, groupTokens } from 'basalt-ui/tokens'
 
 const HEALTH = defineSeries({ hrv: { light: '…', dark: '…' } }) // lighter on dark, deeper on light
-export const SERIES = { ...seriesTokens(HEALTH), walking: groupTokens('walking', WALKING) }
-export const PALETTE_CSS = buildPaletteCss({ groups: { '': HEALTH, 'walking-': WALKING } })
+export const SERIES = groupTokens('health', HEALTH)
 ```
 
-`seriesTokens`/`groupTokens` are exact-keyed, so a stale or typo'd key fails `tsc`. Feed the SAME
-maps to `buildPaletteCss` (or `BasaltProvider`'s `paletteOptions.groups`, keyed by var PREFIX — the
-trailing dash matters) or the refs point at variables nothing declares.
-
-## 3. Compose the primitive
-
-A single-plot chart composes `CartesianChart` and draws only marks in the render prop — margins,
-scales, axes, grid, the shared cursor, crosshair, dots and tooltip are already done:
+3. Pass the group as `<BasaltProvider paletteOptions={{ groups: [SERIES] }} />` (or `buildPaletteCss` for SSR) so its vars are declared.
+4. Compose the chart; import marks from the allowed `@tanstack/charts/*` subpaths:
 
 ```tsx
-<CartesianChart data={data} chartId="hrv" getX={(d) => d.date} series={HRV} y={{ domain: 'auto' }} height={240}>
-  {({ xScale, yScale, visible }) =>
-    visible.map((s) => <LinePath key={s.key} data={data} x={…} y={…} stroke={s.color} />)
+import { lineY } from '@tanstack/charts/line'
+
+;<CartesianChart
+  ariaLabel="HRV"
+  data={data}
+  x={(d) => d.date}
+  series={[{ key: 'hrv', label: 'HRV', color: SERIES.hrv, getValue: (d) => d.hrv }]}
+  marks={(plot) =>
+    plot.visible.map((s) => lineY(plot.rows(s.key), { x: 'x', y: 'y', stroke: s.color }))
   }
-</CartesianChart>
+/>
 ```
 
-- **Draw `visible`, never the `series` prop** — otherwise a legend toggle hides nothing.
-- **Dual axis is `y2`**, not a flag; a series opts in with `axis: 'right'`.
-- **A multi-pane, radial or matrix shape composes `ChartFrame`** + `useChartCursor` + `autoMargin` +
-  `ChartTooltipFloat` and declares itself with `theme-allow-file hand-rolled-plot — <why>`.
-- **Size is `height` / `aspectRatio` / `fill`** — one of the three, nothing else. Charts measure
-  themselves.
-- Never substitute a raw visx axis, a hand-written legend array, a `@visx/tooltip` import, an
-  `rgba()` fill or a hex.
-
-## 4. Verify
-
-- `oxlint .` green — no `basalt/hand-rolled-plot`, no `basalt/chart-legend-literal`, no
-  `basalt/chart-in-raw-surface`, no `@visx/*` import outside a `charts/` segment.
-- `basalt-ui check-theme` green — no raw hex, no raw axis, every chart entry point has an
-  `ariaLabel`.
-- Every new color is a `{ light, dark }` pair in the series file and wired into the palette CSS.
-- Tooltip rows and the legend are DERIVED from `series`; the plot draws `visible`.
-- Checked in both schemes, and with a pending query (`isPending`, not `data ?? []`).
+5. Wrap it in `ChartCard`; pass `state={{ pending, error, empty }}` from the query.
+6. Run `bun run lint:basalt` and `bunx tsc --noEmit`; fix every finding at its source.
+7. Check both color schemes and a pending query.

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

@@ -1,76 +1,18 @@
 ---
 name: basalt-design
-description: Design and restyle dashboards, charts and metric UIs in a basalt-ui app (Mantine v9 + visx) — the procedure: read the law, decide before coding, tune by eye in the theme lab, bake the values back into the palette. Use when building or restyling charts/dashboards, choosing or tuning a palette, or when a UI looks childish / inconsistent / over-colored.
-when_to_use: User is building or restyling charts, dashboards or metric UIs in a basalt-ui consumer; picking or tuning a palette; deciding dark/light shades; or complaining that a UI looks "AI default", inconsistent across tabs or over-saturated. Also the entry point for any "make this look professional" request in a Mantine + visx app.
+description: Build or restyle dashboards and metric UIs in a basalt-ui app — read the law, decide, build, tune in the theme lab, verify.
+when_to_use: User is building or restyling dashboards, charts or metric UIs; tuning a palette; or says a UI looks inconsistent, over-colored or "AI default". Entry point for "make this look professional".
 ---
 
-`/basalt-design` is the METHOD. The law is the `basalt-*` rules plus this app's `DESIGN.md`, and the
-managed `CLAUDE.md` block states which wins — read them, do not re-derive them here. This skill is
-the sequence to follow and the loop to run.
+Method only; the law is `.claude/rules/basalt-*.md` and `./DESIGN.md`.
 
-## 1. Load the law before touching code
+## Steps
 
-- `.claude/rules/basalt-tokens.md` — the identity, the color/spacing/type law, `theme-allow`.
-- `.claude/rules/basalt-mantine.md` — provider, shell, surfaces, depth, motion.
-- `.claude/rules/basalt-controls.md` — where a control lives and what sizes it.
-- `.claude/rules/basalt-charts.md` — the chart contract. `/basalt-charts` is the how-to.
-- `./DESIGN.md` — this app's deltas: identity confirmation, series dictionary, deviations.
-
-**No `DESIGN.md` means the app was never scaffolded** — run `/basalt-app` first. Never invent a
-palette ad hoc.
-
-## 2. Decide before coding
-
-Answer these four in one pass; each one is a decision, not a preference:
-
-1. **What earns a hue here?** Trend, signal/status, or genuine categorical separation. Everything
-   else is neutral. One hue per metric, stable across every view.
-2. **Where does each control live?** One home per control, and the home sets its size (law C1/C5).
-3. **What is the one primary action on this view?** Exactly one filled accent; everything else
-   neutral.
-4. **What does this surface reuse?** Check the shipped composite FIRST — `StatCard`, `ChartCard`,
-   `Section`, `BasaltDataTable`, `QueryState`, `EmptyState`. A fork by a token-fluent author passes
-   every gate, so no guard will tell you; asking is the control. If a composite genuinely cannot
-   express the case, that is a gap to REPORT, not to route around.
-
-## 3. Build it
-
-Compose Mantine primitives and shipped composites; pull every color from `VX.*` / a series token.
-Let the theme carry size, radius, depth and font — a prop you did not have to pass is the point.
-
-## 4. Tune by eye, then bake
-
-A static POC never translates 1:1 to visx + Mantine. Tune in the REAL app with the shipped lab
-(`basalt-ui/theme-lab`), which writes inline `--vx-*` overrides on `<html>` — they beat the
-stylesheet, so everything restyles instantly with no React re-render.
-
-```tsx
-import { ThemeLabControls, applyOverrides, loadOverrides } from 'basalt-ui/theme-lab'
-
-applyOverrides(loadOverrides()) // at boot — the control body does NOT do the initial apply
-;<ThemeLabControls groups={[...COLOR_GROUPS, appSeriesGroup]} onCopy={notifyCopied} />
-```
-
-1. Adjust colors and the area-gradient strength by eye — in BOTH schemes.
-2. Toggle the scheme and re-check: a saturated mid-tone glows on dark (step lighter, slightly
-   desaturated) and washes out on light (step deeper). Same hue, different shade, **never the same
-   value in both**.
-3. Copy the JSON and hand the values back into the palette as `{ light, dark }` pairs — or, for the
-   identity itself, into the derive config's knobs rather than a hand-picked hex.
-4. Remove the override and confirm the baked palette matches.
-
-`DeriveControls` is the identity/colour knobs (seed + the bounded levels + radius + density) and is
-faithful to `createBasaltTheme`; `ThemeLabControls` is the low-level inspector for the non-derived
-structural tokens. Both are DEV tools and inert in a production build — run the dev server.
-
-## 5. Verify before calling it done
-
-- `basalt-ui check-theme` green: zero raw hex, zero `rgba()`, nothing reading `localStorage['theme']`.
-- `oxlint .` green on the `basalt/*` rules — no hand-rolled filter (in a slot) and no in-body
-  `<Title order={1|2}>`. Hand-rolled section headings are NOT lint-visible (see the `not guarded`
-  line in `basalt-controls.md`'s coverage header): grep the diff for `fw={600}` / `<Title order={3`
-  headings by hand and replace them with `WidgetHeader` / `Section`.
-- One hue per metric; neutral structure; the accent only points.
-- Checked in BOTH schemes, and below `sm` as well as on a wide viewport.
-- Any new color landed as a `{ light, dark }` pair in the consumer series file, never inline.
-- Nothing you built duplicates a shipped composite.
+1. Read `./DESIGN.md` and the rules `basalt-tokens.md`, `basalt-mantine.md`, `basalt-controls.md`, `basalt-charts.md`. No `DESIGN.md`: run `/basalt-app` first.
+2. Decide before coding: which metrics earn a hue (trend, status, separation; the rest neutral), the one primary action per view, each control's home.
+3. Check the shipped composites first: `StatCard`, `ChartCard`, `Section`, `WidgetHeader`, `BasaltDataTable`, `EmptyState`. A gap is reported, not routed around.
+4. Build with Mantine primitives and the composites; take every color from `VX.*` or a series token.
+5. Tune by eye in the running app: open the theme lab with the `dev.theme` Spotlight command (dev only) and adjust in both color schemes.
+6. Bake the values back: identity changes go into the `derive` knobs of `createBasaltTheme`, series colors into `src/lib/series.ts` as `{ light, dark }` pairs. Clear the lab overrides and confirm the baked result matches.
+7. Run `bun run lint:basalt`; fix every finding at its source.
+8. Check both schemes, and below and above the `sm` breakpoint.

package/agent/templates/AGENTS-block.md.tpl

@@ -0,0 +1,30 @@
+<!-- basalt:begin {{BASALT_VERSION}} -->
+
+## basalt-ui (managed — do not hand-edit)
+
+Placed by `basalt-ui init`, refreshed by `basalt-ui sync` (`--check` gates drift in CI); edit `DESIGN.md`, not this block.
+
+**Stack:** React 19 + Mantine v9 via `basalt-ui` (`BasaltProvider`, `BasaltShell`), TanStack Router and
+Query, TanStack Charts via `basalt-ui/charts`, Bun, oxlint + oxfmt, no Tailwind. Color is `VX.*` or a
+series token, never a literal.
+
+**Precedence** (highest wins): consumer `DESIGN.md` > the six shipped `basalt-*` rules in
+`.claude/rules/` > the `basalt-*` skills. Each rule bullet ends in the lint rule, guard kind or type
+that enforces it; skills are procedure, not law.
+
+**Run the local bin** (`./node_modules/.bin/basalt-ui` or a package script), never `bunx`; `init` is the
+one exception.
+
+**Before guessing an import, read the installed `llms.txt`** at the install directory (in a workspace,
+under the depending package; `basalt-ui doctor` prints where).
+
+@./DESIGN.md
+
+**Restraint override (supersedes `/frontend-design`).** This is a calm, data-dense professional
+surface: no "bold aesthetic direction", gradient meshes, grain or dramatic motion. Neutral by default,
+the single accent spent only when earned.
+
+**Chart override.** The `basalt-charts` rule supersedes any global visx or chart rule: compose
+`CartesianChart`.
+
+<!-- basalt:end -->

package/agent/templates/DESIGN.md.tpl

@@ -3,7 +3,7 @@
 > Seeded by basalt-ui `init`, then owned by you — `sync` never touches it again, and no version is
 > stamped here (run `basalt-ui doctor` for the version; a number written into a file is frozen at
 > scaffold time). It records this app's **deltas only**: the law lives in `.claude/rules/basalt-*.md`,
-> and the precedence between this file, those rules and the skills is stated once in `CLAUDE.md`.
+> and the precedence between this file, those rules and the skills is stated once in the managed `AGENTS.md` block.
 
 ## Identity
 
@@ -32,7 +32,7 @@ const SERIES_MAP = defineSeries({
   // requests: { light: '…', dark: '…' },   // deeper on light, lighter on dark — never one value
 })
 export const series = groupTokens('app', SERIES_MAP) // { requests: 'var(--vx-app-requests)', … }
-export const paletteGroups = { 'app-': SERIES_MAP } // the trailing dash is a CSS-var prefix
+export const paletteGroups = [series] // the groupTokens result, never a retyped key
 // <BasaltProvider paletteOptions={{ groups: paletteGroups }} …/> — then charts read `series.requests`
 ```
 

package/agent/templates/__root.tpl

@@ -1,30 +1,23 @@
 /**
- * TanStack Router root route — wires QueryClient into the router context so
- * loader functions and components can call `Route.useRouteContext()`.
+ * TanStack Router root route. `BasaltRouterContext` types the context `createBasaltRouter` fills
+ * (the QueryClient); extend it for your own context and pass the value to
+ * `createBasaltRouter({ routeTree, context })`.
  *
  * Scaffold written by `basalt-ui init`. This file is yours — `basalt-ui sync` will not overwrite it.
  */
 import { Outlet, createRootRouteWithContext } from '@tanstack/react-router'
-import type { QueryClient } from '@tanstack/react-query'
-
 import { BasaltShell } from 'basalt-ui'
+import type { BasaltRouterContext } from 'basalt-ui'
+import { NAV } from '../lib/nav'
 
-type RouterContext = {
-  queryClient: QueryClient
-}
-
-export const Route = createRootRouteWithContext<RouterContext>()({
+export const Route = createRootRouteWithContext<BasaltRouterContext>()({
   component: RootComponent,
 })
 
-function RootComponent() {
+// Exported: react/only-export-components flags a non-exported component in a file that exports `Route`.
+export function RootComponent() {
   return (
-    <BasaltShell
-      brand={{ name: '{{APP_NAME}}' }}
-      sections={[
-        // { label: 'Section', items: [{ label: 'Page', to: '/page', icon: <Icon /> }] }
-      ]}
-    >
+    <BasaltShell brand={{ name: '{{APP_NAME}}' }} nav={NAV}>
       <Outlet />
     </BasaltShell>
   )