basalt-ui 1.25.0 → 1.26.0

package/agent/rules/basalt-app.md

@@ -1,246 +0,0 @@
----
-source: basalt-ui
-description: App bootstrapping for basalt-ui consumers — composing basaltViteConfig + basaltAppPlugin in vite.config.ts, plugin ordering, the required Mantine CSS layer order, and the PWA/favicon/manifest surface (bring-your-own icons, opt-in serviceWorker).
-paths:
-  - 'vite.config.ts'
-  - 'apps/**/vite.config.ts'
-  - 'index.html'
-  - 'apps/**/index.html'
-  - 'src/main.tsx'
-  - 'apps/**/src/main.tsx'
----
-
-# Basalt App — Bootstrapping & Vite Config
-
-`basalt-ui/vite` ships two entry points with a deliberate split: `basaltViteConfig` is **config
-only**, `basaltAppPlugin` is the **plugin** half. This rule covers composing them, where
-`basaltAppPlugin` sits relative to other plugins, and the head/PWA/manifest surface it generates.
-
-## Composing the vite config
-
-```ts
-// vite.config.ts
-import react from '@vitejs/plugin-react'
-import { basaltAppPlugin, basaltViteConfig } from 'basalt-ui/vite'
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  ...basaltViteConfig({ port: 5173, apiTarget: 'http://localhost:3000' }),
-  plugins: [react(), ...basaltAppPlugin({ name: 'MyApp', description: '…' })],
-})
-```
-
-`basaltAppPlugin(opts)` returns `PluginOption[]` (a Vite plugin array, not a single plugin) — spread
-it into your own `plugins` array with `...basaltAppPlugin({...})`, same as any other Vite plugin
-that ships more than one plugin instance.
-
-`basaltViteConfig` **never returns `plugins`** and never will — it stays config-only by contract.
-Plugins carry app-specific concerns (router codegen, PWA, `react-compiler` babel options) that don't
-belong in a shared, app-agnostic spine; keeping them out of `basaltViteConfig` means adopting the
-preset never silently injects a plugin you didn't ask for, and `basaltAppPlugin` can be adopted (or
-skipped) independently of the rest of the preset.
-
-## Plugin ordering
-
-`basaltAppPlugin`'s hooks (`transformIndexHtml`, `generateBundle`, `configureServer`) don't
-generate a virtual module another plugin resolves against — unlike
-`@content-collections/vite`, whose plugin-ordering rule (agent/rules/basalt-content.md) requires
-`contentCollections()` to run FIRST because it generates the virtual `content-collections` module
-other plugins/transforms may depend on. `basaltAppPlugin` has no equivalent requirement, so when
-composing both:
-
-```ts
-plugins: [
-  contentCollections(), // FIRST — see basalt-content.md
-  react(), // or tanstackStart()
-  ...basaltAppPlugin({ name: 'MyApp' }), // position is free — see below
-]
-```
-
-Position is a readability convention here, not a correctness requirement — including with
-`serviceWorker` enabled. `vite-plugin-pwa` expands to five plugins that **self-order** via
-`enforce` (`vite-plugin-pwa` is `enforce: 'pre'`; `:build`, `:info` and `:pwa-assets` are
-`enforce: 'post'`), and Vite sorts by `enforce` before array position. Its precache manifest is
-built in `closeBundle`, where `workbox-build` globs the **output directory on disk** — every other
-plugin's transforms and emits have already landed there. So no ordering relationship exists between
-`basaltAppPlugin` and `react()`/`tanstackStart()`.
-
-The one real caveat is a plugin that **emits files from its own `closeBundle`**: if it runs after
-`vite-plugin-pwa`'s, those files are written too late to be precached (the `rollup-plugin-copy`
-class of bug). `vite-plugin-pwa` exposes `integration.closeBundleOrder` to sequence against it.
-
-## What `basalt-ui init` writes into `package.json`
-
-`init` is not only a file-scaffolder. It also patches two keys, and on an existing app it is a
-**lint-debt event, not a no-op** — the shipped preset switches on whole oxlint plugins the repo was
-never linted against, so previously-clean code lands with real findings on the first run. `init`
-prints the plugin list; run `oxlint .` and triage it before your next commit rather than
-blanket-disabling a plugin.
-
-- **`basalt.roots`** — inferred from the real layout (workspace packages depending on basalt or
-  Mantine, else every workspace `src/`, else `src`). Everything derives from it: `check-theme`'s
-  scan, the seeded CI `oxfmt` globs, the default scan exemption. Correct it if your sources live
-  elsewhere; without it a workspace repo scaffolds a guard that scans zero files.
-- **`scripts["lint:basalt"]`** — `oxlint . && basalt-ui check-theme`. Previously the docs told you
-  to wire this and nothing wrote it.
-- **`basalt.profile: 'tokens-only'`** — for a consumer on the `--vx-*` layer with no Mantine. It
-  must be DECLARED (or passed as `--tokens-only`); `check-theme` deliberately never infers it,
-  because inferring from a missing `@mantine/core` would silence 17 kinds on any repo that keeps
-  Mantine in a different workspace package. `doctor` does infer it, because its profile only changes
-  which ADVICE it prints and never what it enforces — and it names the key to write down.
-
-`init` keeps an existing `.oxlintrc.json` rather than clobbering it, and now names what keeping it
-costs (the whole basalt lint half stays off). `--merge-lint` splices the preset's `extends` in; it
-refuses on a commented config rather than deleting the comments.
-
-Run `basalt-ui doctor` afterwards to confirm the wiring took. A check that cannot RUN is reported as
-`SKIPPED` and exits non-zero on its own — "All checks passed" is only printable when every check ran.
-
-### The lefthook preset overrides YOU, not the other way round
-
-`doctor`'s `lefthook-preset` check asks whether a pre-commit gate EXISTS — not whether your config
-contains the extends string. Since 1.22.0 it asks `lefthook dump`, which resolves `extends`,
-`include` and per-command `root:`. **Wiring the jobs yourself passes**: linewatch runs all three with
-`root: 'web/'` precisely because `extends` merges commands _without_ their working directory, and the
-old text match warned there and prescribed a change that would have broken it.
-
-A broken `extends` target is still a hard fail — lefthook merges a missing target into **zero**
-commands and exits 0, so `lefthook dump` looks clean and the repo has no gate with nothing saying so.
-A provably absent gate is a warn; a repo where `lefthook dump` could not run gets an advisory warning
-naming what it could not see. n/a with no lefthook at all. `sync` reports the same seam, since it is
-the command an upgrade actually runs and neither file is one basalt owns.
-
-**An `extends` target WINS on a colliding key.** Declare `pre-commit.commands.oxfmt.run` (or
-`glob:`) in your own file and the preset's value is what runs — yours is discarded silently. Only
-keys the preset does not define merge in. So `env:`, `exclude:`, `skip:` and a differently-named
-command of your own are yours; `run:` and `glob:` on a shipped command are not. The sanctioned seam
-is therefore `BASALT_BIN`: the guard job runs `${BASALT_BIN:-bunx --no-install basalt-ui}`, and the
-shell default is the whole reason the seam exists at all. `init` renders it with the resolved local
-bin. `--no-install` is deliberate — a bare `bunx basalt-ui` in a repo where basalt is not resolvable
-from the root silently downloads a different copy from npm and gates the commit with a version
-nobody pinned.
-
-## `index.html` and `public/` are scanned
-
-`check-theme` resolves `.html` / `.webmanifest` / `.json` as markup (colour kinds only), and each
-`basalt.roots` entry's PARENT contributes its `index.html` and its `public/` tree — exactly the Vite
-layout above. So a raw hex in a `theme-color` meta or a webmanifest's `background_color` is a
-finding now; those are the two colours nothing re-derives on a scheme change. Nothing else in the
-parent is walked, and `.json` is never blanket-scanned — name one in `basalt.include`.
-
-## `__APP_VERSION__`
-
-`basaltViteConfig` injects the `__APP_VERSION__` define, and since 1.20.0 ships the ambient
-declaration with it (`src/register.ts` → `dist/register.d.ts`, re-exported by the root barrel). An
-app that imports anything from `basalt-ui` has it in scope — delete your hand-written ambient block
-and its `oxlint-disable`. A subpath-only consumer does not get it, which is the same set as the
-consumers not on this Vite preset anyway.
-
-## CSS layer order (Mantine)
-
-`basalt-ui/styles.css` must load AFTER every `@mantine/*/styles.layer.css` bundle — the layered
-bundles order `@layer mantine, basalt` so basalt's rules (including the iOS 16px input floor) win;
-an unlayered Mantine import outranks `@layer basalt` regardless of specificity. In `main.tsx`:
-
-```ts
-import '@mantine/core/styles.layer.css'
-// ...other @mantine/*/styles.layer.css bundles for any batteries you install
-import 'basalt-ui/styles.css'
-```
-
-## Head, manifest, and icons — bring your own
-
-`basaltAppPlugin` injects dual `theme-color` tags (light/dark media queries) and an anti-FOUC inline
-`<style>` background, both resolved from the `SURFACE.bg` token — never hand-compute these hexes,
-they track the palette automatically. It also injects the `apple-mobile-web-app-*` /
-`mobile-web-app-capable` meta set, a `darkreader-lock` meta (default on), a viewport tag with
-`viewport-fit=cover` (skipped when the consumer's own `index.html` already declares one), and
-site-wide OG/Twitter defaults from `options.seo`.
-
-**Set `colorScheme` to whatever the app passes as `defaultColorScheme`** — `'dark'` (the default),
-`'light'`, `'auto'` (declares `color-scheme: light dark` and picks the pre-boot background off
-`prefers-color-scheme`), or `false` (paint the background, declare no `color-scheme`).
-
-```ts
-plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })]
-```
-
-Before 1.21.0 the anti-FOUC rule emitted `html{color-scheme:dark}` **unlayered**, which outranks
-Mantine's own `@layer mantine` declaration regardless of specificity — a light-scheme consumer got
-dark scrollbars, dark `<select>` popups and dark date pickers permanently, with no opt-out. The rule
-is now scoped to `html:not([data-mantine-color-scheme])`, so it expires the instant MantineProvider
-resolves the real scheme. A mismatched `colorScheme` is therefore a flash of the wrong surface, not
-a stuck one.
-
-**The plugin hoists your `<meta charset>`.** Every injected tag defaults to `head-prepend`, which
-landed ~20 tags ahead of the consumer's own encoding declaration — measured at byte 1653 on a
-realistic shell, past the 1024-byte window the HTML spec gives it, with no consumer-side fix
-available. The plugin now re-emits the declaration as its own first head-prepend tag (46 bytes after
-the fix) and runs `order: 'pre'` so nothing else can land ahead of it. The legacy `http-equiv` form
-is detected and left verbatim.
-
-Icons are **bring-your-own** — basalt-ui takes no `sharp`/image-processing dependency. The plugin
-expects these filenames under `public/` (or `icons.dir` if customized):
-
-```text
-favicon.ico
-favicon.svg
-favicon-96x96.png
-apple-touch-icon.png
-web-app-manifest-192x192.png
-web-app-manifest-512x512.png
-```
-
-Generate the set with `@vite-pwa/assets-generator` (or realfavicongenerator.net) from a single
-source image — it lives in the CONSUMER's own devDependencies, not basalt-ui's. `basalt-ui doctor`
-warns (does not fail) when `public/` exists but is missing one of these files — and it now
-parses `basaltAppPlugin`'s `icons` option out of your vite config first, so it checks the files you
-declared rather than the six it assumes. `icons: false` or an empty array is "nothing to check"; an
-unparseable or absent config falls back to the six defaults. Adopting the array is no longer a way
-to earn a warning.
-
-**If your `public/` does not match those six filenames, name your icons instead.** `icons` takes
-`false | { dir?: string } | readonly BasaltAppIcon[]`, and an array uses the manifest's own field
-names verbatim:
-
-```ts
-basaltAppPlugin({
-  name: 'rb',
-  icons: [{ src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' }],
-})
-```
-
-`BasaltAppIcon` is `{ src, sizes?, type?, purpose?, rel? }`, `rel` being one of `'icon'`,
-`'shortcut icon'`, `'apple-touch-icon'`, `'mask-icon'`. **Every entry becomes a manifest icon; an
-entry reaches the head only when it names a `rel`** — which is what lets an app whose `index.html`
-already links its favicon take the generated manifest without a duplicate tag. An empty array reads
-as `false` (no `icons` member, rather than an empty one). `{ dir }` and the default are byte-identical
-to what they always emitted.
-
-One SVG at `sizes: 'any'` is a complete, installable icon set for a single-page app — and it is the
-shape every non-scaffolded consumer already has. If you keep a hand-written `manifest.webmanifest`
-only because the plugin could not name your icon, delete it: the generated manifest reproduces it
-member for member, including the two hexes derived from `SURFACE.bg` rather than hand-copied, and it
-takes the permanent `theme-allow-file` on that file with it. **Delete that app's own
-`<link rel="manifest">` in the same change** — the plugin injects its own, so leaving both ships two
-manifest links pointing at different files, one of them a 404 the moment the hand-written file goes.
-
-`basaltAppPlugin` also emits `site.webmanifest` (served in dev too) with explicit `id`/`scope`/
-`start_url` — pass `manifest: false` to skip it, or `icons: false` to skip the icons. Since 1.22.0
-`icons: false` omits BOTH the head `<link>` tags and the manifest's `icons` member; before that it
-skipped only the head, so a manifest shipped naming two PNGs the app never builds.
-
-## Service worker (opt-in)
-
-`serviceWorker` defaults to `false` — no service worker unless you ask for it. `true` composes the
-optional peer `vite-plugin-pwa` with argo-derived workbox defaults (`autoUpdate` registration,
-`cleanupOutdatedCaches`, a `/index.html` navigate fallback that denies `/api/*`); pass an object to
-deep-merge overrides on top. When the peer (plus its own peers `workbox-build`/`workbox-window`) is
-not installed, the plugin degrades to a one-line console warning — no service worker, no throw:
-
-```bash
-bun add -D vite-plugin-pwa workbox-build workbox-window
-```
-
-`basaltAppPlugin` always emits its own `site.webmanifest` — `serviceWorker`'s `manifest: false` is
-baked into the defaults so `vite-plugin-pwa` never emits a competing one.

package/agent/rules/basalt-commands.md

@@ -1,320 +0,0 @@
----
-source: basalt-ui
-description: Command bus, overlay controller, Spotlight projection, shortcuts display, and composable overlay mount from the shipped ./commands battery. @mantine/modals + @mantine/spotlight are optional peers; @mantine/notifications is already a peer from ./notifications.
-paths:
-  - 'src/**'
-  - 'apps/**/src/**'
----
-
-# Basalt Commands
-
-basalt-ui ships `./commands` — a Mantine-coupled command bus + overlay controller battery providing
-`defineCommands`, `runCommand`, `defineOverlays`, `overlays`, `toSpotlightActions`,
-`toShortcutList`, `ShortcutsHelp`, and `BasaltOverlays` on top of `@mantine/modals` and
-`@mantine/spotlight`. Both are **optional peers** — install them before using this battery. The
-default `BasaltOverlays` also mounts `<Notifications>` (or pass `notifications={false}`), so
-`@mantine/notifications` is needed too:
-
-```bash
-bun add @mantine/modals @mantine/spotlight @mantine/notifications
-```
-
-Also import Spotlight styles in `main.tsx` — use the **layered** bundle, since the unlayered one
-outranks basalt's `@layer basalt` styles regardless of specificity:
-
-```tsx
-import '@mantine/spotlight/styles.layer.css'
-```
-
-## Mount BasaltOverlays
-
-`BasaltOverlays` is the composable overlay mount — it bundles `ModalsProvider`, `Spotlight`, and
-`Notifications` into a single mount point. Put it inside `BasaltProvider`, before the router. It
-**replaces** `<BasaltNotifications />` from `basalt-ui/notifications` — do NOT mount both in the
-same tree (that would double-mount `<Notifications />`).
-
-```tsx
-import { BasaltOverlays } from 'basalt-ui/commands'
-import { BasaltProvider } from 'basalt-ui'
-import '@mantine/spotlight/styles.layer.css'
-
-createRoot(root).render(
-  <BasaltProvider>
-    <BasaltOverlays>
-      <App />
-    </BasaltOverlays>
-  </BasaltProvider>,
-)
-```
-
-Each layer is enabled by default; pass `false` to disable:
-
-```tsx
-<BasaltOverlays spotlight={false} notifications={false}>
-  <App />
-</BasaltOverlays>
-```
-
-## defineCommands + runCommand
-
-`defineCommands` is a const-generic factory (mirrors `defineSeries`/`defineNotifications`) for
-typed command registries. Augment `BasaltRegister.commands` once, then use `runCommand` — unknown
-ids are tsc errors.
-
-```ts
-// commands.ts (app-side) — define and augment once:
-import { defineCommands } from 'basalt-ui/commands'
-
-export const COMMANDS = defineCommands({
-  'file:save': { label: 'Save file', group: 'File', shortcut: 'Mod+S', run: () => save() },
-  'file:open': { label: 'Open file', group: 'File', shortcut: 'Mod+O', run: () => open() },
-  'data:sync': { label: 'Sync data', group: 'Data', run: async () => sync() },
-  'help:docs': { label: 'Open docs', group: 'Help', run: () => window.open('/docs') },
-  'edit:focus': {
-    label: 'Focus editor',
-    group: 'Edit',
-    shortcut: 'Mod+E',
-    when: () => isEditorPage(), // hides from palette when not on editor page
-    run: () => focusEditor(),
-  },
-})
-
-declare module 'basalt-ui' {
-  interface BasaltRegister {
-    commands: typeof COMMANDS
-  }
-}
-```
-
-```ts
-// usage.ts — typed runCommand; unknown ids are tsc errors:
-import { runCommand } from 'basalt-ui/commands'
-
-runCommand('file:save') // ✓ sync
-await runCommand('data:sync') // ✓ async
-runCommand('nonexistent') // ✗ tsc error
-```
-
-### CommandId + CommandRunContext
-
-`CommandId` is `Extract<keyof Slot<'commands', CommandMap>, string>`.
-Un-augmented: `never` → `runCommand` is effectively uncallable.
-Augmented: the exact registered key literal union.
-
-`CommandRunContext` is minimal (`{ close?: () => void }`) — pass it to close the command palette
-before executing:
-
-```ts
-runCommand('file:save', { close: () => spotlight.close() })
-```
-
-### CRITICAL — runtime stash pattern
-
-The `BasaltRegister` slot augmentation is **type-only and erased at runtime**. `defineCommands`
-stashes the spec map in a module-level `activeCommands` variable; `runCommand` reads from THAT
-stash — NOT from `{} as Commands`. This is the same pattern as `defineNotifications` / `emit`.
-Always call `defineCommands` once before any call to `runCommand` (typically imported at app boot).
-
-### TS circular-inference footgun
-
-Calling `overlays.open(...)` inside a `run` handler, in the **same module that also augments**
-`BasaltRegister.commands` (i.e. the file with `declare module 'basalt-ui' { interface
-BasaltRegister { commands: typeof COMMANDS } }`), can trip TS into inferring `COMMANDS` as
-`implicitly has type 'any'` — the `run` return type and the `commands` slot type end up in a
-circular inference loop. Fix: give that `run` an explicit `: void` (or `: Promise<void>` for async)
-return annotation. Prefer splitting overlay-opening commands into a separate file from the
-`defineCommands`/`declare module` augmentation when practical — it sidesteps the cycle entirely.
-
-## defineOverlays + overlays
-
-`defineOverlays` registers ephemeral modal overlays. `overlays.open` is the imperative controller.
-
-```ts
-// overlays.ts (app-side) — define and augment once:
-import { defineOverlays } from 'basalt-ui/commands'
-
-export const OVERLAYS = defineOverlays({
-  'user:edit': {
-    title: 'Edit user',
-    render: (p: { id: string; name: string }) => <UserEditForm id={p.id} name={p.name} />,
-  },
-  'confirm:delete': {
-    title: 'Delete item?',
-    render: (p: { name: string }) => <ConfirmBody name={p.name} />,
-  },
-})
-
-declare module 'basalt-ui' {
-  interface BasaltRegister { overlays: typeof OVERLAYS }
-}
-```
-
-```ts
-// usage.ts — typed overlays.open; unknown keys are tsc errors:
-import { overlays } from 'basalt-ui/commands'
-
-overlays.open('user:edit', { id: '42', name: 'Alice' }) // ✓ typed
-overlays.open('confirm:delete', { name: 'photo.jpg' }) // ✓
-overlays.open('nonexistent', {}) // ✗ tsc error
-overlays.close() // close all open modals
-```
-
-`OverlayKey` is `Extract<keyof Slot<'overlays', OverlayMap>, string>`.
-The same runtime-stash pattern applies — `defineOverlays` stashes to `activeOverlays`.
-
-### Imperative vs route (when to use each)
-
-| Use `overlays.open`                   | Use route mask (`./router-tanstack`)       |
-| ------------------------------------- | ------------------------------------------ |
-| Ephemeral confirms, quick-edit panels | Shareable/back-button/refreshable overlays |
-| No URL needed                         | URL-addressable dialogs                    |
-| Triggered from commands or buttons    | Triggered by navigation                    |
-
-## Spotlight projection (toSpotlightActions)
-
-`toSpotlightActions()` projects the active command registry to `SpotlightActionData[]` for Mantine
-Spotlight. Commands where `when()` returns `false` are excluded. `BasaltOverlays` calls it
-automatically with `shortcut="mod + K"`.
-
-```ts
-import { toSpotlightActions } from 'basalt-ui/commands'
-import { Spotlight, spotlight } from '@mantine/spotlight'
-
-// Manual Spotlight mount (if not using BasaltOverlays):
-<Spotlight actions={toSpotlightActions()} shortcut="mod + K" />
-
-// Programmatically open the palette:
-spotlight.open()
-```
-
-## Shortcut display (toShortcutList + ShortcutsHelp)
-
-`toShortcutList()` returns commands with a `shortcut` field as a flat list. `ShortcutsHelp`
-renders them in a grouped Mantine layout with platform-aware labels (⌘ on mac, Ctrl elsewhere).
-
-**Display + live binding.** `ShortcutsHelp` renders the shortcuts for reference, and the same
-`shortcut` field is bound to live keys by `useCommandHotkeys()` (via the `@tanstack/react-hotkeys`
-optional peer). Spotlight `mod + K` covers the palette trigger.
-
-```tsx
-import { ShortcutsHelp } from 'basalt-ui/commands'
-
-// In a help modal or settings panel:
-;<ShortcutsHelp title="Keyboard shortcuts" maw={480} />
-```
-
-```ts
-import { toShortcutList } from 'basalt-ui/commands'
-const list = toShortcutList()
-// [{ id: 'file:save', label: 'Save file', shortcut: 'Mod+S', group: 'File' }, ...]
-```
-
-## Live keybindings (useCommandHotkeys)
-
-`useCommandHotkeys()` binds all registered command shortcuts to their `run()` functions via
-`@tanstack/react-hotkeys`. It is an **optional-peer** hook — degrades to a no-op when the peer is
-absent; core resolves cleanly either way. No `HotkeysProvider` wrapper is required.
-
-Install the optional peer:
-
-```bash
-bun add @tanstack/react-hotkeys
-```
-
-### Mount pattern
-
-**BasaltOverlays mounts it automatically** (via the internal `HotkeysMount` component) when
-`hotkeys={true}` (default). No extra setup needed if using `BasaltOverlays`.
-
-For manual mounting, call `useCommandHotkeys()` once in the component tree, after `defineCommands`:
-
-```tsx
-import { useCommandHotkeys } from 'basalt-ui/commands'
-
-function App() {
-  // Activate all registered command shortcuts — call once per tree, not per-command.
-  useCommandHotkeys()
-  return <RouterProvider router={router} />
-}
-```
-
-If you want hotkeys active only on a specific page:
-
-```tsx
-function EditorPage() {
-  useCommandHotkeys()
-  return <EditorLayout />
-}
-```
-
-### toHotkeyBindings
-
-`toHotkeyBindings()` projects the command registry into the `UseHotkeyDefinition[]` array that
-`useHotkeys` from `@tanstack/react-hotkeys` expects. Commands without a `shortcut` are skipped.
-Commands where `when()` returns false at press time are silently skipped.
-
-```ts
-import { toHotkeyBindings } from 'basalt-ui/commands'
-import { useHotkeys } from '@tanstack/react-hotkeys'
-
-// Manual binding — equivalent to useCommandHotkeys() but you control the options:
-function MyHotkeys() {
-  useHotkeys(toHotkeyBindings(), { preventDefault: true })
-}
-```
-
-### Shortcut string format
-
-Shortcut strings use the `Mod+Key` convention: `Mod` resolves to `⌘` on macOS and `Ctrl`
-elsewhere. The `@tanstack/hotkeys` package handles platform resolution at runtime.
-
-```ts
-defineCommands({
-  'file:save': { label: 'Save', shortcut: 'Mod+S', run: () => save() },
-  'file:close': { label: 'Close', shortcut: 'Mod+W', run: () => close() },
-  'edit:find': { label: 'Find', shortcut: 'Mod+F', run: () => find() },
-  'view:zoom': { label: 'Zoom', shortcut: 'Mod+Shift+Z', run: () => zoom() },
-})
-```
-
-## Spotlight live store (basaltSpotlight)
-
-`BasaltOverlays` mounts Spotlight against a basalt-owned store (`createSpotlight()` singleton).
-Import `openSpotlight` / `closeSpotlight` from `basalt-ui/commands` instead of Mantine's global
-`spotlight` to target this instance:
-
-```ts
-import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
-
-// Open the palette programmatically:
-openSpotlight()
-
-// From a command handler (close palette, then run):
-runCommand('palette:open', { close: () => closeSpotlight() })
-```
-
-Spotlight actions are synced from the registry via `toSpotlightActions()` at mount time. Shortcuts
-displayed in the Spotlight action description are platform-formatted via `formatShortcutDisplay`
-(`⌘S` on mac, `Ctrl+S` on windows).
-
-## defineOverlay (single-overlay helper)
-
-Mirror of `defineCommand` — types a single overlay without registering it. Use when splitting
-overlay definitions across files.
-
-```ts
-import { defineOverlay } from 'basalt-ui/commands'
-
-const confirmDelete = defineOverlay<{ name: string }>({
-  title: 'Confirm delete',
-  render: ({ name }) => <Text>Delete "{name}"?</Text>,
-})
-// Then include in defineOverlays({ 'confirm:delete': confirmDelete })
-```
-
-WARNING: `defineOverlay` only TYPES — it does NOT register. Only `defineOverlays(map)` registers.
-
-## Deferred
-
-- **`SidebarItem.command?: CommandId`** — cross-ref between the shell sidebar and the command bus
-  is a later integration step. Do not add it now.