@happyvertical/smrt-svelte 0.55.7 → 0.55.9

package/AGENTS.md

@@ -13,11 +13,15 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/i18n/` (`./i18n` + `./i18n/server`) | `defineMessages` / `useI18n` / `<Trans>` / `buildI18nSnapshot`, the template-vs-render split, and hardcoded-string enforcement | [agents/i18n.md](agents/i18n.md) |
 | `src/themes/` + `src/theme/` | which theme system is canonical and the full `--smrt-*` design-token vocabulary with its alias rules | [agents/themes.md](agents/themes.md) |
 | `src/test-support/` + `__tests__/` | the golden-test harness and pattern for Svelte component tests | [agents/testing.md](agents/testing.md) |
+| `src/components/import-export/` (`./import-export`) | `ImportExport` CSV/TSV import (column mapping, validation preview, error report) and export (column selection) driven by collection definitions + resolved field policy, over a pure Node-tested CSV layer (#3715) | [agents/import-export.md](agents/import-export.md) |
 | `src/components/settings/` (`./settings`) | `SettingsCatalog`, `paginateSettingsCatalog`, and the summary-vs-detail scalability contract | [agents/settings.md](agents/settings.md) |
+| `src/components/screens/` (`./screens`) | `RecipeScreens` / `ListScreen` / `DetailScreen` / `EditForm`: list, view, create and edit derived from a generated web definition plus resolved field policy; pure `deriveScreenFields` selection, minor-unit money handling, transport-neutral source (#3718) | [agents/screens.md](agents/screens.md) |
 | `src/components/app/` (`./app`) | `AppShell` (Provider + ThemeProvider + theme CSS + AdminShell + nav/dock slots), `OwnerSetupForm` (props-driven first-run owner form), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp`. Browser-only; no `$app/*` or server imports | [agents/workspace.md](agents/workspace.md#app-shell-and-owner-setup-app) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
+| `src/components/command-palette/` (`./command-palette`) | `CommandPalette` trigger + dialog, `PaletteProvider` contract, nav and manifest providers (#3713) | [agents/command-palette.md](agents/command-palette.md) |
+| `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
 | `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
-| `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | One-call registration of an existing, non-`DataTable` list (already mirroring a headless `DataTableController`) as a mounted `DataSurfaceDescriptor` — a same-behavior port of `registerContentListDataSurface`'s registration/translation logic (`@happyvertical/smrt-content/svelte`), generalized off ContentList's view-mode concept, so any custom list markup can adopt it directly instead of hand-mirroring the registry contract. Not yet unified behind a shared `@happyvertical/smrt-ui/data` implementation (#2917) — this copy is currently ahead; see its own module doc comment for the current, authoritative list of divergences #2917 must adopt rather than assume parity (#2906) | — |
+| `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | Registers an existing non-`DataTable` list (mirroring a `DataTableController`) as a mounted `DataSurfaceDescriptor`; a same-behavior port of `registerContentListDataSurface`, not yet unified behind smrt-ui (#2917). The module doc comment is the authoritative list of divergences (#2906) | — |
 | `src/web/webmcp-provider.ts` | Provider config for generated data/model WebMCP tools: definitions, effect policy, namespace, budget, legacy/canonical filters, and fetcher seams (#2520) | — |
 | `src/web/webmcp-ui.ts` | Fixed, low-cardinality WebMCP adapter over the Provider's mounted form-control and data-surface registries (#2521) | — |
 | `src/web/webmcp.svelte.ts` (`useWebMcpTool`) | Component-owned bespoke WebMCP tool. Routes through `@happyvertical/smrt-web`'s `registerWebMcpBespokeTool`, so it shares the fail-closed effect classification and `effects` exposure policy of generated tools — undeclared `annotations` classify destructive and are excluded by default. `namespace` and `maxTools` never apply to a bespoke tool (#2586) | — |
@@ -206,49 +210,8 @@ for a data-surface one — for exactly the component's lifetime.
 - **Preload strategies**: `none`, `eager`, `idle` (recommended), `on-visible`
 - **Warm client cache**: module-level Map survives navigation/remounts -- avoids re-downloading WASM/models
 - **Adapters**: STT (browser-speech, whisper-cpp, whisper-local = alias whisper-wasm), TTS (browser-synthesis), LLM (webllm, transformers-llm)
-- **On-device speech** (`whisper-local` = alias `whisper-wasm`, and `moonshine`): thin adapters over
-  `@happyvertical/speech/local` (`LocalTranscriber`, or its worker host `serveLocalTranscriber`).
-  Push-to-talk (record on `start()`, transcribe on `stop()`, one final result) plus `transcribePcm()`
-  for smrt-ui's hands-free mode. Default `onnx-community/whisper-tiny.en` q8 (~45 MB, Cache
-  Storage); `model: 'moonshine-tiny'` (~32 MB) / `'moonshine-base'` (~67 MB) or any HF id
-  (`LOCAL_SPEECH_MODELS`); WebGPU else single-thread WASM (no COOP/COEP needed). The package never
-  imports the peers: a host passes `createWorker` (build it from
-  `@happyvertical/smrt-svelte/browser-ai/whisper-worker?worker`, alias `speech-worker`, the one module
-  that imports `@happyvertical/speech/local` and `@huggingface/transformers` statically) plus
-  `loadSpeech: () => import('@happyvertical/speech/local')`, or `loadModule` for the page thread.
-  `createLocalSpeechModel()` (alias `createWhisperLocalModel()`) / `adapter.model` is the consent API
-  (`estimateSize`, `isCached`, `load({ onProgress, signal })` with `downloading` -> `extracting` ->
-  `complete`); share it via `modelHandle`. English-only handling of `language`/`task` lives in the speech
-  package. `probeBrowserSpeech()` -> `works | missing | unreliable` (no network, no mic prompt)
-  decides whether to offer it. Sources set `stopTimeoutMs` so `Dictation` waits for the transcription.
 - Cache API: `getCachedSTT()`, `getCachedTTS()`, `getCachedLLM()`, `getCacheStats()`, `clearAllCaches()`
-- **Inference backends (browser-ai)**: two `@happyvertical/smrt-web/ai` `InferenceBackend`s, both
-  `kind: 'local'`, both refusing `tool`/`function` messages, non-string content, `tool_calls` and
-  `options.tools` with `InferencePathError` (`unsupported_message`) through the SHARED
-  `assertTextOnlyTurn`, so a per-call switch between backends never changes what a turn means.
-  - `createWebLlmInferenceBackend()` wraps an `LLMAdapter` — `status` derives from the adapter's
-  `initState` (plus an explicit in-flight flag, because the adapter only flips to `initializing`
-  after its own awaits), `progress` mirrors `DownloadProgressInfo`, and `load()`/`unload()` drive
-  `ensureInitialized`/`unloadModel`. It reports `unavailable` without WebGPU so an `auto` path skips
-  it. Pass `adapter` to share the app-state-managed warm-cached adapter; construct once, so two
-  callers cannot each start an unshared adapter and a second download.
-  Its `loadModule` option matters: the default `importOptional()` resolves a VARIABLE specifier,
-  which a browser cannot resolve (`TypeError: Failed to resolve module specifier`) — a host that has
-  `@mlc-ai/web-llm` must pass `() => import('@mlc-ai/web-llm')` so the bundler rewrites a static one.
-  It does NOT forward `signal` (the adapter has no cancellation seam).
-  - `createBitGpuInferenceBackend()` wraps `bitgpu` (MIT, optional peer), the engine behind the
-    Bonsai WebGPU demo PrismML's own docs list as their in-browser option. `loadBitGpu`/`loadChat`
-    are REQUIRED loaders (`() => import('bitgpu')`, `() => import('bitgpu/chat')`) — a static import
-    here would fail the build for every consumer without the optional peer, and a bare specifier is
-    not resolvable by a browser either. `bitgpu`'s `LoadProgress.phase` maps to `InferenceProgress`
-    (`manifest`/`weights` → `downloading`, `pipelines` → `extracting`). Unlike the WebLLM backend it
-    **forwards `signal`** — bitgpu aborts a live generation — and it does NOT lazily load: weights
-    run to GBs, so a turn before `load()` fails with a named reason. `model` in the per-call options
-    is ignored (one engine binds one model), and bitgpu's tools/JSON-schema/think support is
-    deliberately left unexposed for now so the text-only invariant holds across backends.
-- **`ModelStatusControl.svelte`**: the user-facing model lifecycle surface (state, Load/Unload,
-  download progress) driven entirely by a backend's own `status`/`progress`/`subscribe`, so it works
-  without a `<Provider>` ancestor. `unavailable` is a first-class state that offers NO load action.
+- **On-device speech and inference backends** (`whisper-local`/`moonshine` adapters, `createWebLlmInferenceBackend`, `createBitGpuInferenceBackend`, `ModelStatusControl`): see [agents/browser-ai.md](agents/browser-ai.md).
 
 ## Permission Action
 
@@ -272,5 +235,5 @@ for a data-surface one — for exactly the component's lifetime.
 - `@happyvertical/smrt-types` (shared types) — includes the identity data contracts (`User`, `Role`, `Membership`, `Tenant`) the role/membership components type against, so no dependency on `smrt-users` / `smrt-profiles` is needed
 - `@happyvertical/smrt-ui` (UI runtime: primitives, theme system, i18n client, module registry) is a hard `dependency`. The agent-admin shells that used to type against `@happyvertical/smrt-agents/ui` moved to `@happyvertical/smrt-agents/svelte` (#1589), so `smrt-agents` is no longer a dependency here — this drops smrt-svelte below smrt-agents in the package DAG.
 - `@happyvertical/smrt-languages` is a hard `dependency` (not an optional peer): the Node-only `/i18n/server` subpath imports its resolver. The browser bundle still excludes it — the client `/i18n` layer never imports the languages root, so it tree-shakes out.
-- `@happyvertical/logger` (SDK) is a `dependency` — the console logger used for voice/AI error reporting in the form components. Consume it **only** through `src/internal/logger.ts`, never `createLogger()` at module scope: `createLogger()` reads `HAVE_LOGGER_LEVEL` from `process.env`, so a top-level call throws `ReferenceError: process is not defined` in the browser and kills client-side hydration under `vite dev` (prod builds tree-shake/define it away, so this only bites in dev). The `internal/logger` wrapper constructs the logger lazily and falls back to a bare `ConsoleLogger` when `process.env` is absent, keeping this browser-reachable module (imported by `Provider` + the form primitives) safe.
+- `@happyvertical/logger` (SDK) is a `dependency` for voice/AI error reporting in the form components. Consume it **only** through `src/internal/logger.ts`, never `createLogger()` at module scope: it reads `process.env`, which throws `ReferenceError` in the browser under `vite dev` and kills hydration. The wrapper builds the logger lazily and falls back to a bare `ConsoleLogger`.
 - Peer (all optional): `svelte` >=5.18.2, plus the browser-AI engines (`@happyvertical/speech`, `@huggingface/transformers`, `@mlc-ai/web-llm`, `@remotion/whisper-web`) and `chrono-node`.

package/README.md

@@ -32,6 +32,50 @@ pipeline (`opportunity.stage`) without importing `@happyvertical/smrt-projects`.
 
 Svelte 5 component library for the s-m-r-t framework. Provides UI components, browser AI integration (STT/TTS/LLM with warm cache), a theme system, permission-aware rendering, and module UI registry for agent admin panels.
 
+## Import and export
+
+`@happyvertical/smrt-svelte/import-export` provides `ImportExport`, a CSV and
+TSV import/export panel for any collection. Spreadsheet users save as CSV;
+there is no `.xlsx` reader. Import is a guided flow: pick a file, map each
+column to a field (auto-detected from the field name, label, or alias),
+check a validation preview, then import. The preview is the dry run and writes
+nothing. Rows that fail validation are listed by file line with the offending
+value, and are downloadable as a CSV error report. Valid rows are created one
+request each, so a server rejection fails only that row. Export lets the user
+choose columns, delimiter, and header style; the default `name` headers
+re-import cleanly.
+
+The columns come from the same sources as the generated forms:
+`fieldsFromCollectionDefinition(definition, { policy })` reads the collection
+definition (the manifest) and a resolved field policy. A policy-`hidden` field
+is neither imported nor exported, a `locked` field is never overwritten, and a
+resolved default fills an empty or unmapped cell. `createCollectionImportExport`
+binds the panel to the generated CRUD fetchers, so import and export go through
+the same authorized REST routes as every other client.
+
+```svelte
+<script lang="ts">
+  import {
+    ImportExport,
+    createCollectionImportExport,
+  } from '@happyvertical/smrt-svelte/import-export';
+
+  const io = createCollectionImportExport({ definition, fetchers, fieldOptions: { policy } });
+</script>
+
+<ImportExport
+  fields={io.fields}
+  createRecord={io.createRecord}
+  loadRows={io.loadRows}
+  filename="products"
+/>
+```
+
+The CSV layer (`parseTable`, `validateRows`, `buildExportFile`, `runImport`)
+is pure and runs in Node. Exports neutralize spreadsheet formulas in text
+cells. See [agents/import-export.md](./agents/import-export.md) for the
+contract.
+
 ## Sortable and shell layout
 
 `@happyvertical/smrt-svelte/sortable` provides `Sortable`, an accessible
@@ -590,10 +634,67 @@ keys the shell renders exactly as before.
 - **Migration guide** (first-generation `WorkspaceShell`/`RoleShell` →
   `AdminShell`; adoption is additive and non-breaking):
   [`src/components/workspace/MIGRATION.md`](./src/components/workspace/MIGRATION.md)
-- **Playground demos**: `playground/src/routes/admin-shell` exercises all four
+- **Playground demos**: `playground/src/routes/command-palette` shows the palette in the header slot;
+  `playground/src/routes/admin-shell` exercises all four
   scopes, focus tools, and activities; `admin-shell-activity-feed` and
   `admin-shell-system-feed` show live feeds.
 
+### Command palette and global search
+
+`@happyvertical/smrt-svelte/command-palette` is a keyboard-first "find anything"
+dialog (Ctrl/Cmd+K) with a provider contract. Anything can register rows: the
+shell navigation, "New invoice" commands and cross-model record search derived
+from the manifest, or your own commands.
+
+```ts
+import {
+  CommandPalette,
+  createCommandPalette,
+  createModelProviders,
+  createNavigationProvider,
+} from '@happyvertical/smrt-svelte/command-palette';
+
+const palette = createCommandPalette({
+  navigate: goto,
+  providers: [
+    createNavigationProvider({ nav, groups }),
+    ...createModelProviders({ manifest, pagesBasePath: '/app' }),
+  ],
+});
+```
+
+Render `<CommandPalette {palette} />` as an `AppShell` `slotItems` entry
+(usually `header.center`). See
+[`agents/command-palette.md`](./agents/command-palette.md) for the provider
+contract, accessibility behavior, and the record-search limits.
+
+### Customizable overviews
+
+`@happyvertical/smrt-svelte/overview` turns an overview page into a grid of
+registered widgets (metric, chart, record list, shortcuts, note) that admins
+reorder, resize, configure, add and remove in the shell's layout edit mode,
+inside an allowed set the page declares. A saved overview is declarative data:
+widget options are validated against versioned schemas on save and on load, and
+widget data comes from a server `load(options, ctx)` that runs inside the page's
+load with the user's permissions, so the page renders fully on the server.
+Persistence is host-owned (the same pattern as the shell layout).
+
+```ts
+import {
+  createOverview,
+  OverviewGrid,
+  registerCoreWidgets,
+} from '@happyvertical/smrt-svelte/overview';
+import {
+  defineOverview,
+  loadOverview,
+  resolveOverview,
+} from '@happyvertical/smrt-svelte/overview/server';
+```
+
+See [`agents/overview-surfaces.md`](./agents/overview-surfaces.md) for the data
+model, the validation rules, the server load contract and the extension points.
+
 ## Exports
 
 ### Entry Points
@@ -605,10 +706,15 @@ importable, even if it appears in `dist/`.
 |-------------|----------|
 | `@happyvertical/smrt-svelte` | `Provider`, hooks (`useAppState`, `useAuth`, `useLLM`, `useSocket`, `useSTT`, `useTheme`, `useTTS`), app state/context, `ModulePanel`, and the form components below |
 | `@happyvertical/smrt-svelte/forms` | Form inputs (TextInput, Select, MoneyInput, DateTimeInput, Toggle, etc.) |
+| `@happyvertical/smrt-svelte/import-export` | `ImportExport` (CSV/TSV import with column mapping, validation preview and error report; export with column selection), `createCollectionImportExport`, `fieldsFromCollectionDefinition`, and the pure CSV layer |
 | `@happyvertical/smrt-svelte/settings` | Server-paged settings search, selection, and list/detail layout (`SettingsCatalog`, `paginateSettingsCatalog`) |
+| `@happyvertical/smrt-svelte/screens` | List, view, create and edit screens derived from a generated web definition and resolved field policy (`RecipeScreens`, `ListScreen`, `DetailScreen`, `EditForm`) |
 | `@happyvertical/smrt-svelte/workspace` | AdminShell, ShellState, tenant nav, focus tools, settings, activities, and system/app panels |
 | `@happyvertical/smrt-svelte/app` | `AppShell` (Provider + themes + AdminShell + nav/dock slots, `dockToggles` buttons and host `slots` for the header/footer/sidebar regions), `OwnerSetupForm` (first-run owner setup), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp` |
 | `@happyvertical/smrt-svelte/app/runtime-diagnostics` | Svelte-free diagnostics WebMCP registration and its tool name/endpoint constants, importable from server routes |
+| `@happyvertical/smrt-svelte/command-palette` | Global search and command palette: `CommandPalette` (shell-slot trigger plus dialog), `createCommandPalette`, the provider contract, and the navigation and manifest-driven model providers |
+| `@happyvertical/smrt-svelte/overview` | Customizable overview surfaces: `OverviewGrid` (flow grid with keyboard reorder and resize), `createOverview` (host-owned controller), the widget registry (`registerWidget`), `registerCoreWidgets` (metric, chart, record list, shortcuts, note) and `shortcutsFromNav` |
+| `@happyvertical/smrt-svelte/overview/server` | Svelte-free half of the overview surface: the data model (`resolveOverview`, `checkOverviewOverride`), option-schema validation, `WidgetRegistry`, and `loadOverview` for a page's server load |
 | `@happyvertical/smrt-svelte/workspace/legacy` | Opt-in ToolsDock compatibility surface for applications migrating to AdminShell |
 | `@happyvertical/smrt-svelte/workspace/server` | Server-side workspace helpers (Node only) |
 | `@happyvertical/smrt-svelte/workspace/live` | `systemFeed` — the AdminShell system scope (jobs/schedules/dispatch) polled from an app status endpoint; deliberately carries no `smrt-web` dependency |
@@ -704,6 +810,11 @@ all other currencies render their ISO code for deterministic SSR hydration.
 
 `getCachedSTT`, `getCachedTTS`, `getCachedLLM`, `getCacheStats`, `clearAllCaches`
 
+Browser speech synthesis honors `stop()`, replacement `speak()` calls, and
+`dispose()` while voices are loading. Canceled `speak()` promises resolve even
+when the browser emits no completion event; `onEnd` is reserved for natural
+completion. Events from canceled utterances are ignored.
+
 ## Dependencies
 
 - `@happyvertical/smrt-types` -- shared type definitions

package/agents/browser-ai.md

@@ -0,0 +1,47 @@
+# smrt-svelte/browser-ai
+
+Module semantics for `src/browser-ai/`. Package orientation and cross-module
+invariants live in [../AGENTS.md](../AGENTS.md); read that first.
+
+- **On-device speech** (`whisper-local` = alias `whisper-wasm`, and `moonshine`): thin adapters over
+  `@happyvertical/speech/local` (`LocalTranscriber`, or its worker host `serveLocalTranscriber`).
+  Push-to-talk (record on `start()`, transcribe on `stop()`, one final result) plus `transcribePcm()`
+  for smrt-ui's hands-free mode. Default `onnx-community/whisper-tiny.en` q8 (~45 MB, Cache
+  Storage); `model: 'moonshine-tiny'` (~32 MB) / `'moonshine-base'` (~67 MB) or any HF id
+  (`LOCAL_SPEECH_MODELS`); WebGPU else single-thread WASM (no COOP/COEP needed). The package never
+  imports the peers: a host passes `createWorker` (build it from
+  `@happyvertical/smrt-svelte/browser-ai/whisper-worker?worker`, alias `speech-worker`, the one module
+  that imports `@happyvertical/speech/local` and `@huggingface/transformers` statically) plus
+  `loadSpeech: () => import('@happyvertical/speech/local')`, or `loadModule` for the page thread.
+  `createLocalSpeechModel()` (alias `createWhisperLocalModel()`) / `adapter.model` is the consent API
+  (`estimateSize`, `isCached`, `load({ onProgress, signal })` with `downloading` -> `extracting` ->
+  `complete`); share it via `modelHandle`. English-only handling of `language`/`task` lives in the speech
+  package. `probeBrowserSpeech()` -> `works | missing | unreliable` (no network, no mic prompt)
+  decides whether to offer it. Sources set `stopTimeoutMs` so `Dictation` waits for the transcription.
+- **Inference backends (browser-ai)**: two `@happyvertical/smrt-web/ai` `InferenceBackend`s, both
+  `kind: 'local'`, both refusing `tool`/`function` messages, non-string content, `tool_calls` and
+  `options.tools` with `InferencePathError` (`unsupported_message`) through the SHARED
+  `assertTextOnlyTurn`, so a per-call switch between backends never changes what a turn means.
+  - `createWebLlmInferenceBackend()` wraps an `LLMAdapter` — `status` derives from the adapter's
+  `initState` (plus an explicit in-flight flag, because the adapter only flips to `initializing`
+  after its own awaits), `progress` mirrors `DownloadProgressInfo`, and `load()`/`unload()` drive
+  `ensureInitialized`/`unloadModel`. It reports `unavailable` without WebGPU so an `auto` path skips
+  it. Pass `adapter` to share the app-state-managed warm-cached adapter; construct once, so two
+  callers cannot each start an unshared adapter and a second download.
+  Its `loadModule` option matters: the default `importOptional()` resolves a VARIABLE specifier,
+  which a browser cannot resolve (`TypeError: Failed to resolve module specifier`) — a host that has
+  `@mlc-ai/web-llm` must pass `() => import('@mlc-ai/web-llm')` so the bundler rewrites a static one.
+  It does NOT forward `signal` (the adapter has no cancellation seam).
+  - `createBitGpuInferenceBackend()` wraps `bitgpu` (MIT, optional peer), the engine behind the
+    Bonsai WebGPU demo PrismML's own docs list as their in-browser option. `loadBitGpu`/`loadChat`
+    are REQUIRED loaders (`() => import('bitgpu')`, `() => import('bitgpu/chat')`) — a static import
+    here would fail the build for every consumer without the optional peer, and a bare specifier is
+    not resolvable by a browser either. `bitgpu`'s `LoadProgress.phase` maps to `InferenceProgress`
+    (`manifest`/`weights` → `downloading`, `pipelines` → `extracting`). Unlike the WebLLM backend it
+    **forwards `signal`** — bitgpu aborts a live generation — and it does NOT lazily load: weights
+    run to GBs, so a turn before `load()` fails with a named reason. `model` in the per-call options
+    is ignored (one engine binds one model), and bitgpu's tools/JSON-schema/think support is
+    deliberately left unexposed for now so the text-only invariant holds across backends.
+- **`ModelStatusControl.svelte`**: the user-facing model lifecycle surface (state, Load/Unload,
+  download progress) driven entirely by a backend's own `status`/`progress`/`subscribe`, so it works
+  without a `<Provider>` ancestor. `unavailable` is a first-class state that offers NO load action.

package/agents/command-palette.md

@@ -0,0 +1,85 @@
+# smrt-svelte/command-palette
+
+Module semantics for `src/components/command-palette/` (`./command-palette`).
+Package orientation and cross-module invariants live in
+[../AGENTS.md](../AGENTS.md); the shell it sits in is in
+[workspace.md](workspace.md).
+
+## Shape
+
+- **Controller** (`controller.svelte.ts`): `createCommandPalette({ providers,
+  navigate, onError, searchDebounceMs, maxPerGroup })`. Owns open/query state,
+  the provider registry, local and remote rows, the highlight, and `activate`.
+  `setCommandPalette(controller)` puts it on context (call it above the
+  `AppShell`) so any descendant can `useCommandPaletteProvider(provider)`; that
+  hook is a no-op without a palette.
+- **Components**: `CommandPalette` = `CommandPaletteTrigger` + `CommandPaletteDialog`.
+  Mount it **once**: the dialog owns the global shortcut (`hotkeys`, default
+  `['Mod+K']`; `false` for none). Place it with `AppShell` `slotItems`
+  (`header.center` is the usual slot); it is a movable item like any other.
+  Without a `palette` prop or context it builds one from `providers`/`navigate`.
+- **Pure core**: `match.ts` (accent/case-insensitive, multi-term, word-start
+  then in-order fuzzy; returns title ranges), `rank.ts` (groups, limits,
+  boost), `hotkeys.ts` (`Mod` = Ctrl or Meta). Node-testable, no Svelte.
+
+## Provider contract (`types.ts`)
+
+A `PaletteProvider` is `{ id, label, order?, items?, search?, minQueryLength?,
+limit? }`.
+
+- `items(ctx)` rows are re-read **every time the palette opens** and matched
+  locally by the palette. Sync results land in the same tick; async ones fill
+  in (`busy`).
+- `search(query, { signal, limit })` runs after the debounce with an abort
+  signal that fires on the next keystroke or close. Its rows are shown as
+  returned (not re-filtered); earlier rows stay until the new ones arrive. A
+  superseded result is dropped, never shown.
+- Registering an id again replaces the provider; a stale disposer is a no-op.
+  The replaced provider's cached rows are cleared and its in-flight `items` or
+  `search` results (and failures) are dropped, never shown or reported.
+- Authorization stays with the provider. A failing provider is reported through
+  `onError` (default: logger warning) and marked in `failedProviders`; the
+  palette keeps working. The palette is not a security boundary.
+- A row with `run` runs; else a row with `href` goes through `navigate`
+  (default `window.location.assign`; SvelteKit apps pass `goto`). The palette
+  closes first, then runs.
+
+## Shipped providers (`providers.ts`)
+
+- `createNavigationProvider({ nav, groups })`: rows for the shell nav. Pass
+  getters over `useShellLayout().applied` to honor sections a user hid.
+- `createModelProviders({ manifest, ... })` returns `[commands, records]`:
+  - eligibility is `navigableManifestEntries` (exported from
+    `workspace/manifest-nav.ts`), so it agrees with manifest-derived nav;
+  - commands: "New <noun>" for models whose REST `create` route exists;
+    destinations come from `hrefs` or the `<pagesBasePath>/<collection>[/new|/id]`
+    convention (the app owns its page routes);
+  - records: `GET <apiBasePath>/<collection>?<field>[like]=%q%` per model, one
+    text field each (first of `title`, `name`, `displayName`, ... that is a
+    non-sensitive, non-enum text field; override with `searchFields`), capped by
+    `maxModels` and `concurrency`, interleaved so one model cannot crowd out
+    the rest. The default fetch reads the generated list envelope
+    `{ items, count, limit, offset }` (a bare array also works; any other body
+    counts as no results). 401/403/404 mean "no results" for that model; the search throws
+    only when **every** request fails.
+  - Known limit: `LIKE` is case-insensitive on SQLite and case-sensitive on
+    PostgreSQL (sdk#1192). Supply `searchRows` to use a server search endpoint
+    instead.
+
+## Accessibility and keyboard
+
+WAI-ARIA combobox: focus stays in the search box; `aria-activedescendant`
+names the highlighted option; options sit in labelled groups inside a
+`listbox`; a polite status region announces counts and "no results". Up/Down
+(wrapping, skipping disabled rows), PageUp/PageDown, Enter, Escape (the
+`Modal` closes). Disabled rows stay visible with their reason as the tooltip.
+A bare-key shortcut (`/`) never fires while typing in a field or during IME
+composition; a modified one (`Mod+K`) does. Strings are in
+`src/i18n/strings.palette.ts` (registered in `i18n/server.ts`); provider group
+labels default to English and are options on the shipped providers.
+
+## Not yet wired
+
+Recipe surfaces (#3708): a recipe will declare the palette as a shell widget
+and its own providers (for example an assistant provider) once non-model
+surfaces exist. Until then hosts mount `CommandPalette` themselves.

package/agents/import-export.md

@@ -0,0 +1,62 @@
+# smrt-svelte/import-export
+
+Module semantics for `src/components/import-export/` (`./import-export`).
+Package orientation and cross-module invariants live in
+[../AGENTS.md](../AGENTS.md); read that first.
+
+## Shape
+
+`ImportExport.svelte` is a thin shell over a pure layer. The pure files import
+no Svelte or DOM API and are unit-tested in Node; keep logic there, not in the
+component.
+
+| File | Owns |
+|------|------|
+| `csv.ts` | RFC 4180 parse/format, delimiter detection, BOM, formula neutralization |
+| `validate.ts` | `coerceCell`, `validateMapping`, `validateRows` (the dry run) |
+| `mapping.ts` | `autoMapColumns`, `setColumnTarget` |
+| `fields.ts` | `fieldsFromCollectionDefinition`: manifest + resolved field policy to `ImportExportField[]` |
+| `collection-adapter.ts` | `createCollectionImportExport`: generated CRUD fetchers to `createRecord` / `loadRows` |
+| `runner.ts` | `runImport`: bounded-concurrency create, per-row failures, abort |
+| `export.ts` / `report.ts` | `buildExportFile`, `buildErrorReport` |
+| `download.ts` | the only DOM touch: Blob download (overridable via `ondownload`) |
+
+## Invariants
+
+- **Field policy is a hard boundary.** A supplied resolved policy is an
+  allowlist: a field it omits is neither importable nor exportable (manifest
+  defaults apply only with no policy). `hidden` fields are neither importable
+  nor exportable; `locked` fields are not importable but keep their resolved
+  default; tenant fields (`tenantId`) are never imported (the server sets
+  them). `id` is export-only. Do not add a path that writes a non-importable
+  field: only importable and `locked` fields take a default; hidden and tenant
+  defaults never enter the payload.
+- **Nothing is written during validation.** `validateRows` returns no records
+  while `mappingIssues` is non-empty (an unmapped required field would be
+  written without its value). `records` only ever holds fully valid rows;
+  there is no partial-row import.
+- **Strict typing.** Integers must be JavaScript-safe integers (money is
+  integer minor units, never decimals); datetimes are strict ISO 8601 with a
+  missing offset meaning UTC; `3/5/2026` is rejected, not guessed. Booleans
+  accept `true/false/yes/no/y/n/1/0/on/off`. Enum matching is
+  case-insensitive and writes the canonical option.
+- **Defaults fill empties.** An empty or unmapped cell takes the field's
+  resolved default; a required field with a default is satisfied.
+- **Exports are spreadsheet-safe.** Text cells starting with `= + - @`, tab or
+  CR are prefixed with `'`; numeric and boolean columns are exempt so negative
+  numbers survive. Import strips that prefix back off text cells. The error
+  report is neutralized too, because it echoes user data.
+- **Export never truncates silently.** `loadRows` pages with `limit`/`offset`
+  and throws `ExportLimitError` past `maxRows` (default 50,000).
+- **Row failures are per row.** `runImport` continues past a rejected row and
+  reports it by file line; abort stops starting new rows and counts in-flight
+  ones.
+- **Messages are i18n keys.** Issue text lives under `ui.importExport.issue.*`
+  in `src/i18n/strings.import-export.ts` (registered in `i18n/server.ts`);
+  `describeIssue` falls back to English defaults for the pure layer.
+
+## Not here
+
+Native `.xlsx` read/write (save as CSV first), server-side dry-run endpoints,
+upsert-by-key, and recipe/nav wiring (offering the panel on list screens waits
+on the recipe surface contract, #3708).