@happyvertical/smrt-svelte 0.55.9 → 0.55.11

package/AGENTS.md

@@ -19,7 +19,8 @@ subpath you are editing. This file keeps what holds in every module.
 | `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/components/cookbook/` (`./cookbook` + `./cookbook/server`) | cookbook-driven app shell: pure `buildCookbookShell` (cookbook + recipe catalog to `AppShell` sections, entries, layout, theme, section overviews, recipe surfaces), `CookbookApp` / `CookbookSectionPage`, and the server `loadCookbookApp` (file + installed manifests + validation); ported from smrt-planner (#3749) | [agents/cookbook-shell.md](agents/cookbook-shell.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); production persistence is `@happyvertical/smrt-preferences` (kind `overview`) | [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`) | 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) | — |

package/agents/cookbook-shell.md

@@ -0,0 +1,176 @@
+# smrt-svelte/cookbook
+
+Module semantics for `src/components/cookbook/` (`./cookbook` and
+`./cookbook/server`, #3749). Package orientation and cross-module invariants are
+in [../AGENTS.md](../AGENTS.md); the document it reads is the cookbook v1
+contract ([core cookbook.md](../../core/agents/cookbook.md)).
+
+A **cookbook-driven app shell**: given `smrt.cookbook.json` and the installed
+packages' recipes, render the navigation sections, recipe entries, layout, theme
+and section overview pages that smrt-planner showed, so a generated app and the
+planner preview draw the same shell. Logic ported from smrt-planner
+(`+layout.svelte`, `recipes/sections.ts`, `sections/*`, `overviews/*`,
+`theme/*`); the planner-only editor, option/help pages, package browser and
+sample data source are not part of it.
+
+## Entries
+
+| Entry | Contents |
+|---|---|
+| `./cookbook/server` | Svelte-free and Node-safe. `loadCookbookApp` (file + manifests + validation), `readInstalledManifests`, `hasCookbook`, and the pure builder/catalog/theme functions and types. Use it in `+layout.server.ts`. |
+| `./cookbook` | Everything above that is browser-safe, plus `CookbookApp`, `CookbookSectionPage`, `applyCookbookTheme`, `createCookbookRegistry`, `createSectionOverview`. |
+
+## Pure core (no DOM, Node-testable)
+
+- **`catalogFromManifests(manifests)`** turns package `manifest.json` objects
+  into a `CookbookCatalog` (`recipes` trimmed to what the shell reads, `models`
+  with package id, description and `exposed`). Recipe order is manifest order;
+  a repeated id keeps the first. `narrowCatalog(catalog, cookbook)` keeps only
+  the selected recipes and the models they or the cookbook's `features` name, so
+  a load serializes a few KB instead of the whole workspace.
+- **`buildCookbookShell({ cookbook, catalog, ... })`** returns a `CookbookShell`:
+  `navGroups` for `AppShell` (`navMode: 'sections'`, one group per suggested
+  section, icon and section-page `href`), `layout` (the cookbook's, passed to
+  the shell, which applies order/hidden/labels itself), `sections` and `entries`
+  (every entry by stable id), `theme`, `overviews`, recipe surfaces
+  (`shellWidgets`, `routes`, `settingsPanels`, `widgets`), `policies`, and
+  `issues`. It never throws for cookbook content: an unknown recipe, a nav model
+  the catalog lacks or a feature that is not exposed becomes an `issues` entry
+  and is left out.
+- **Ids are the contract.** Section layout ids are `section:<id>` (a recipe's
+  `section`, else its `group`, else the recipe) or `custom:<slug>` (the layout's
+  own); entries are `item:<package>:<Model>[:<key>]`. They never name labels or
+  hrefs, so renames and route changes keep a saved layout valid. Do not change
+  `navItemId`/`buildNavSections` without the planner: both read the same
+  cookbooks.
+- **Section order** follows the first recipe of each section in **catalog
+  order** (not the cookbook's sorted list), then the cookbook layout's
+  `sectionOrder`. Pass `recipeOrder` to pin it (the planner's overlay order).
+- **Entries**: label, icon (`fileText` when the recipe names none), description
+  (recipe text, else the model description, else a plain fallback), `noun` and
+  `filter` carried through. Feature models share the `More` section after the
+  recipes' sections.
+- **Paths** are options: `entryPath` (default `/m/<package>/<Model>/[<key>/]`),
+  `sectionPath` (default `/s/<slug>/`, slug = layout id with the first `:`
+  turned into `-`), and `href` (a prefix or query helper applied to both).
+- **Overviews**: one definition per suggested section and per layout custom
+  section (`defineOverview`), id = the section's layout id, so a cookbook's
+  `overviews` key survives a section rename. Defaults are a `shortcuts` widget;
+  with `dataWidgets: true` they add a `metric` count and `records` list of the
+  section's lead model (first nav model of its first recipe), which need the
+  host's loaders. The cookbook's stored override is carried untouched
+  (untrusted JSON, `null` when absent or empty) for `resolveOverview` /
+  `createOverview` to validate; an override for an unknown page, or a malformed
+  one, is an `issues` entry.
+- **Theme**: `resolveCookbookTheme` is lenient (a bad colour or font is ignored;
+  `validateCookbook` is where it is rejected). A brand colour becomes the preset
+  id `cookbook-brand-<hex>[-<font>]`; the colour/font pair is encoded in the id
+  because `ThemeProvider` looks a registered theme up once per id.
+- **Recipe surfaces**: `shell-widget` surfaces are returned with their slot (a
+  smrt-svelte `ShellSlot`; the equality with `RecipeShellSlot` is a typechecked
+  assertion), `route` and `settings-panel` as data, `widget` surfaces grouped by
+  recipe for `registerRecipeWidgets`. The builder never imports a component.
+
+## `CookbookApp`
+
+`AppShell` with the builder's output. Props: `cookbook`, `catalog`, any
+`AppShell` prop (title, logo, `storageKey`, `user`, `permissions`, `dock`,
+`slotItems`, `settingsHref`, ...), and:
+
+- `loaders` (`metric` / `records` / `chart` data loaders; with `metric` and
+  `records` the section pages add the count and latest records),
+- `widgetContext` (host capabilities for browser-side widget loads),
+- `resolveExport` (a static map of dynamic imports; turns a recipe export
+  reference into a component, used for `shell-widget` slot items and recipe
+  `widget` registration; without it those surfaces are ignored),
+- `oncookbookchange(cookbook)` called with the full cookbook after a layout or
+  overview edit (layout edits come from the shell's pencil toggle, enabled with
+  `layoutEditing`). Without it edits live in memory. Persisting them is the
+  host's job; feeding the result back as `cookbook` is safe.
+
+Layout and overview edits are kept in local `$state.raw` copies that follow the
+`cookbook` prop whenever it changes. The widget registry is rebuilt only when
+the recipes' widget surfaces change by content, not on every edit.
+
+Theme: `applyCookbookTheme` registers a brand colour with smrt-ui
+(`createThemeFromColor` + `registerTheme`) and returns the preset for
+`ThemeProvider`; an unknown preset name falls back to `smrt`.
+
+**SSR**: the shell, nav, title and theme render on the server. The widget
+registry, recipe widgets and slot items are resolved in effects (a bundled
+`resolveExport` is async), so a section page's overview appears after hydration,
+not in the server HTML.
+
+## `CookbookSectionPage`
+
+A section's own page: title, icon and description (the user's renames win over
+the suggestion), the overview grid, and, in the shell's layout edit mode, the
+section's entries as a sortable menu. A section without an overview (a custom id
+outside the overview id pattern) shows its menu as cards. Mount it from one
+route: `s/[slug]/+page.svelte` renders
+`<CookbookSectionPage slug={page.params.slug} />`. It must be inside
+`CookbookApp`.
+
+## Using it in an app
+
+```ts
+// +layout.server.ts
+import { loadCookbookApp } from '@happyvertical/smrt-svelte/cookbook/server';
+export const load = async () => loadCookbookApp(); // { cookbook, catalog, warnings }
+```
+
+```svelte
+<!-- +layout.svelte -->
+<script lang="ts">
+import { CookbookApp } from '@happyvertical/smrt-svelte/cookbook';
+let { data, children } = $props();
+</script>
+<CookbookApp cookbook={data.cookbook} catalog={data.catalog} layoutEditing>
+  {@render children()}
+</CookbookApp>
+```
+
+`loadCookbookApp` reads `smrt.cookbook.json`, reads the `manifest.json` of the
+project's dependencies that export one, validates with `validateCookbook` from
+`@happyvertical/smrt-core/cookbook` (resolved at call time: the app depends on
+core; smrt-svelte does not, `validate` can be injected), and throws one error
+listing every problem, including a recipe no installed package declares.
+
+## Not done here
+
+- **Field policies** (`cookbook.policies`) are returned as `policies` but not
+  applied; applying them to the runtime is `smrt cookbook apply` and the
+  runtime's job. The shell does not render a settings page; pass `settingsHref`.
+- **Entry pages** (`/m/<package>/<Model>/`) are the app's routes; `./screens`
+  (`RecipeScreens`) is the default content for them. Their data comes from the
+  package model's generated REST route and its `@smrt/web` definition (#3749).
+  The app does nothing beyond listing the package in `smrt.config.ts`
+  `consumer.packages`: the `smrt()` Vite preset hosts the models of the
+  cookbook's recipes and `features` (core
+  [build-knowledge.md](../../core/agents/build-knowledge.md), "Package models
+  over REST"), skipping `api: false` models and any the cookbook's `exposure`
+  turns off for `api`. In the entry route, take
+  `collectionDefinitions[<collection>]` from `@smrt/web` (not
+  `@happyvertical/smrt-virt-web`, which holds only the app's own models) as the
+  `definition`, and build the `RecipeScreensSource` over
+  `GET /api/<collection>` and `/api/<collection>/<id>` (offer writes only when
+  the definition's `actions` include them). A model with no definition is not
+  exposed over the API; show the notice.
+- **Options/Help gear** on a recipe's first entry (the planner's `action`) is
+  planner-only and not emitted.
+- **Legacy id migrations** (`migrateLegacySections`/`NavItemIds`) stay in the
+  planner; they depend on its recipe catalog.
+
+## Tests
+
+`src/components/cookbook/__tests__/`: `build.test.ts` builds the four fixture
+cookbooks in `packages/core/src/cookbook/__fixtures__/` against the real
+workspace recipes (every package that declares a `SmrtRecipe`, scanned and
+converted to manifests the way the build does, in `workspace-catalog.ts`, so no
+sibling `dist/` is needed), asserts no issues, that every layout id resolves,
+and the exact bakery sections and labels. `contract-types.ts` (not a `*.test.ts`:
+tsc excludes test files) holds the type assertions that smrt-types'
+`CookbookLayout`/`CookbookOverviewOverride` equal `ShellLayout`/
+`OverviewOverride`. `CookbookApp.test.ts` mounts the shell with the bakery
+cookbook (nav, section page, brand theme, edit callback); `server.test.ts` runs
+the loader over a temp project with a fake installed package.

package/agents/overview-presentation.md

@@ -0,0 +1,8 @@
+# SMRT #3759 test design
+| Behavior | Trigger | Positive | Negative/default | Actor/context | Executor | Runtime | Edge | Level | Command |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Accessible host heading | heading snippet | linked h3 names article | omitted snippet retains title | browser reader | N/A presentation | Svelte5/browser+SSR | optional snippet | component+a11y | pnpm --filter @happyvertical/smrt-svelte exec vitest run src/components/overview/__tests__/OverviewGrid.test.ts |
+| Plain view, editable frame | presentation plain/editing toggle | plain attribute, toolbar and inert edit preview | default card unchanged | authorized editor | N/A presentation | Svelte5/browser | optional enum typed | component | same |
+No persistence/auth/executor changes. Existing grid suite covers denied editor, widget failures, keyboard edits. New behavior is additive, no bug-fix base comparison required.
+
+Validation: OverviewGrid component suite passed on this change (includes linked article headings, a11y, edit chrome and existing default regressions). Package typecheck and aggregate release checks are recorded in release evidence.

package/agents/overview-surfaces.md

@@ -11,15 +11,16 @@ its default arrangement; admins (or users, per role) add, reorder, resize,
 configure and remove widgets inside that confined set, and reset returns to the
 default. Phase 1 (this module) is the surface, the registry, the data model, the
 server load contract and five core widgets; phase 2 adds package widgets from
-recipes ("Recipe widgets"). Persistence and assistant operations are later
-phases (see "Extension points").
+recipes ("Recipe widgets"); phase 3 is production persistence in
+`@happyvertical/smrt-preferences` ("Production persistence"); phase 4 adds
+assistant operations with Undo ("Assistant operations").
 
 ## Two entries
 
 | Entry | Contents |
 |---|---|
-| `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`. Safe in a `+page.server.ts` or a save endpoint. |
-| `./overview` (`index.ts`) | Everything above plus `OverviewGrid`, `createOverview` (controller), `WidgetOptionsForm`, the core widgets and `registerCoreWidgets`, `shortcutsFromNav`, `formatWidgetValue`, `parseMarkdown` / `safeHref`. |
+| `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`, the operations (`planOverviewOperations`, `describeOverview`) and `createOverviewAssistantSurface`. Safe in a `+page.server.ts` or a save endpoint. |
+| `./overview` (`index.ts`) | Everything above plus `OverviewGrid`, `createOverview` (controller), `WidgetOptionsForm`, the core widgets and `registerCoreWidgets`, `shortcutsFromNav`, `formatWidgetValue`, `parseMarkdown` / `safeHref`, `createOverviewAssistant` / `useOverviewAssistantTools` / `OverviewAssistantUndo`. |
 
 ## Data model (`types.ts`, `model.ts`)
 
@@ -50,7 +51,8 @@ against (absent means 1).
   (they would stop incrementing), and an exhausted high end restarts at `w1`.
 - **Tiers.** `resolveOverview` merges one override. A host with tenant defaults
   and user overrides merges the tenant tier into the definition's `defaults`
-  first (phase 3); the user override then applies to that.
+  first; the user override then applies to that (smrt-preferences'
+  `withTenantDefaults`).
 - **Reset** is `controller.reset()` (store `null`) or `resetWidget(id)`.
 
 ## Validation: what keeps a stored overview from running anything
@@ -136,7 +138,11 @@ return { overview };   // LoadedOverview: JSON, serializable
 loaded?, loadWidget? })`, the `ShellLayout` pattern: **persistence is host-owned**.
 With an `override` getter the host is the source of truth and feeds each edit back
 (`onchange(override | null)`); without it the value is kept in memory. Reactive
-reads: `document`, `base`, `override`, `issues`, `customized`, `canCustomize`,
+reads: `document`, `base`, `override`, `committedOverride` (with a host-owned
+getter: the newest value handed to `onchange` that the getter has not fed back
+yet, else `override`; emissions are acknowledged in order, so several saves in
+flight never regress it, and a getter value matching none of them and not the
+value before them is a change from elsewhere that drops the queue), `issues`, `customized`, `canCustomize`,
 `addable`, `full`, `entry(widget)`. Operations, each returning
 `{ ok: true, id } | { ok: false, reason, issues? }` and refused with
 `not_allowed` when `canCustomize()` is false (the role gate; the server must check
@@ -239,17 +245,127 @@ turns the manifest's widget surfaces into `registry.register(...)` calls:
   and a type-level assertion here keeps `RecipeWidgetOptionType` equal to
   `WidgetOptionType`.
 
+## Production persistence (phase 3, `@happyvertical/smrt-preferences`)
+
+Overrides are stored as the `overview` kind of the generic user-interface
+preference table `_smrt_ui_preferences` in
+[smrt-preferences](../../preferences/AGENTS.md) (one row per tenant, kind,
+surface id = `OverviewDefinition.id`, and tier; the kind contract is in its
+[preference-kinds.md](../../preferences/agents/preference-kinds.md)). This
+package stays free of database code: its overview entries import nothing from
+core, tenancy or users. The `overview` kind validates with this package's
+`checkOverviewOverride` on save (only the canonical override is stored) and
+`resolveOverview` on load (bad entries dropped and reported per tier).
+`createOverviewStore({ db })` is the overview-shaped layer over the generic
+store and acts as the ambient principal:
+
+| Call | Does |
+| --- | --- |
+| `load(definition, registry)` | Both tiers resolved page defaults < tenant < user; each tier's `override`, `revision`, `issues`, the merged `document` and `canCustomize: { tenant, user }` |
+| `save(definition, registry, { scope, override, revision })` | Strict validation against the tier's definition (user: tenant-merged); `invalid` / `conflict` / `not_allowed` otherwise |
+| `reset(definition, { scope, revision? })` | Deletes that tier's row |
+| `loadPage(definition, registry, ctx, { scope? })` | `load` plus `loadOverview` of the tier's document, for `+page.server.ts` |
+| `loadWidget(definition, registry, widget, ctx)` | One widget's data for the controller's `loadWidget` remote function (throw on `ok: false`) |
+
+Host wiring for the personal layer: `createOverview({ definition:
+withTenantDefaults(definition, data.overview.tenant.document), override: () =>
+data.overview.user?.override ?? null, onchange: (next) => save({ scope:
+'user', override: next, revision }), canCustomize: () =>
+data.overview.canCustomize.user, loaded: data.overview.loaded, loadWidget })`;
+the organization layer uses the page definition, `tenant.override` and
+`canCustomize.tenant`. Keep the returned `revision` for the next save; on
+`conflict` reload the page data. Permissions are `overviews.customize` (tenant
+default) and `overviews.personalize` (own layout).
+
+Known model limit: a tenant default that later adds a widget whose id equals
+an id a user override already added hides the user's widget (an added widget
+colliding with a base id is skipped). `nextWidgetId` avoids it within one tier
+only.
+
+## Assistant operations (`operations.ts`, `assistant-surface.ts`, `assistant.svelte.ts`)
+
+Phase 4: the assistant adds and configures widgets with structured operations,
+and the person can undo the change.
+
+- **Operations** are data: `add { type, span?, options?, index? }`,
+  `configure { id, options }` (merged onto the current options; `null` clears a
+  key to its default), `move { id, index }`, `resize { id, span }`,
+  `remove { id }`. `OVERVIEW_OPERATION_SCHEMA` is their JSON schema.
+- **`planOverviewOperations({ definition, registry, override, operations })`**
+  plans a batch (at most 20) against the current override. Strict: unknown ops
+  or fields, unregistered or disallowed types (`allowed`, `allowedIn`), invalid
+  options (including a `model` outside `definition.models`), spans outside the
+  type's range, unknown widget ids and the cap are `OverviewOperationIssue`s
+  (`index`, `op`, `widgetId`, `code`, `message`, `options`). The result is then
+  run through `checkOverviewOverride`, so it is always an override a save
+  accepts. **Atomic**: any issue rejects the batch and returns nothing to
+  apply. Later operations see earlier ones; an `add` takes the next free id
+  (`nextWidgetId`, never a removed default's). Total, never throws.
+- **`describeOverview(...)`** is what a model reads first: allowed types with
+  option fields (type, required, default, range, `choices`, the page
+  `models`), span ranges, the current widgets with their index and title.
+  `translate` resolves i18n-key titles and labels.
+- **Server: `createOverviewAssistantSurface({ definition, registry, override,
+  revision, canCustomize, persist })`** is one page for one principal:
+  `describe`, `current`, `plan`, `check` and `persist`. Writes are
+  conditional: `persist(override, { revision })` must write only if the
+  stored row is still the loaded `revision` and answer
+  `{ ok: false, reason: 'conflict' }` otherwise
+  (`OverviewAssistantPersistResult`, structurally `OverviewSaveResult` of
+  `@happyvertical/smrt-preferences`); on success the surface follows the
+  returned `revision`. With phase 3:
+  `persist: (override, { revision }) => store.save(definition, registry, { scope: 'user', override, revision })`
+  where `store = createOverviewStore({ db })` from `@happyvertical/smrt-preferences`,
+  `override` / `revision` come from `store.load(...)`'s `state.user`, and the
+  surface's `definition` is `withTenantDefaults(definition, state.tenant.document)`. It is the adapter
+  `@happyvertical/smrt-chat`'s `createOverviewTools()` drives (typed
+  structurally there; see
+  [chat overview-tools.md](../../chat/agents/overview-tools.md) for the tool
+  contract, error codes and principal/page-scoped Undo). Phase 3 supplies the
+  stored override, the role and `persist`.
+- **Browser: `createOverviewAssistant(controller, { toolPrefix?, toaster?,
+  translate? })`** applies a batch through `controller.restore(plan.override)`,
+  so the grid updates live and the host's `onchange` persists it like any edit.
+  It refuses with `not_allowed` when `canCustomize` is false. `lastBatch`
+  (reactive) keeps `{ id, results, counts, before, after }`; `undo(id?)`
+  restores `before` exactly, once, and refuses with `changed_since` when the
+  override is no longer `after` (the person edited since). Both read
+  `controller.committedOverride`, so in host-owned mode a batch whose save the
+  host has not fed back yet is not mistaken for a change made elsewhere.
+  `useOverviewAssistantTools(assistant)` registers `<prefix>_describe` (read),
+  `<prefix>_apply` and `<prefix>_undo` (write) through `useWebMcpTool`, so the
+  AssistantDock offers them as page tools: the Provider's `webmcp.effects` must
+  allow `write`, the server's `clientToolAllowList` must list `overview_*`, and
+  the dock asks the person to Allow each write unless the host policy says
+  otherwise. Results are JSON strings (`{ ok: false, error, issues }` on a
+  rejected batch).
+- **Undo affordance.** `OverviewAssistantUndo` (`assistant`, optional
+  `message`) shows the last batch with Undo and Dismiss buttons and announces
+  the outcome in its own polite live region; or pass a smrt-ui `toaster` and
+  each batch shows as a toast with an Undo action (the host mounts
+  `ToastViewport`). Strings are `ui.overview.assistant_*`.
+- Tests: `__tests__/operations.test.ts`, `__tests__/assistant.test.ts` (live
+  grid update, Undo, the component with axe) and
+  `__tests__/assistant-tools.integration.test.ts` (chat's tools over this
+  model).
+
 ## Extension points left for later phases
 
-- **Phase 2, package widgets (#3727, done).** See "Recipe widgets" below.
-- **Phase 3, production persistence.** Implement the `override` getter /
-  `onchange` pair against the `_smrt_` table (tenant tier merged into
-  `definition.defaults`, user tier as the override), validate saves with
-  `checkOverviewOverride` and persist its canonical `override`, run
-  `loadOverview` in the page load, and supply `loadWidget` as a remote function
-  that calls the same `load`. Role gating = `canCustomize` plus the same check in
-  the save endpoint. No migration or table lives in this package.
-- **Phase 4, assistant.** The controller methods are the structured operations;
-  `restore(override)` plus the `override` getter give Undo (snapshot before,
-  restore after). `OverviewOpResult.issues` is the validation feedback to return.
+- **Phase 2, package widgets (#3727, done).** See "Recipe widgets" above.
+- **Phase 3, production persistence (#3727, done).** See "Production
+  persistence" above.
+- **Phase 4, assistant (#3727, done).** See "Assistant operations" above;
+  `createOverviewAssistantSurface` is wired to the stored user tier through
+  `createOverviewStore(...).save` as shown there.
 - **Not built:** the activity widget (Track B, #3710) and agenda.
+
+## Host section presentation
+
+`OverviewGrid` defaults to framed cards. Pass `presentation="plain"` for
+unframed page sections; editing restores the visible tile frame and controls.
+The optional `heading(widget, title)` snippet supplies heading content, such as
+an application-owned link. The grid still renders its `headingLevel` element
+and generated id used by the article's accessible name; the snippet must not
+supply another heading. Use trusted application routes for links. Widget bodies
+should omit duplicate section headings. Default titles remain unchanged when
+no snippet is supplied.

package/agents/screens.md

@@ -55,3 +55,8 @@ stays below the domain layer, and the app passes both in as props.
   default and does not replace it. Not wired into recipe surfaces yet (#3708).
 - Component props live in `types.ts`, not in the `.svelte` files, so the barrel
   never re-exports types from a component.
+- **Where a package model's definition and data come from (#3749).** A cookbook
+  app's `smrt()` preset hosts the cookbook's package models; the definition is
+  `collectionDefinitions[<collection>]` from `@smrt/web` and the source is the
+  model's `/api/<collection>` route (see [cookbook-shell.md](cookbook-shell.md)).
+  A model the API does not expose has neither, so the entry page shows its notice.

package/agents/workspace.md

@@ -32,6 +32,12 @@ them from the published artifact versus exporting them is tracked in #2286.
 - App-owned configuration for hidden edges, push/overlay presentation, and
   exclusivity groups
 - User-owned preferences persist as sparse `ShellSettingsDelta` values
+  through a `ShellSettingsAdapter` (`LocalStorageShellSettingsAdapter` by
+  default). Server-side, per tenant and user, they can persist as the
+  `shell-layout` kind of `@happyvertical/smrt-preferences`
+  (`createShellSettingsPreferences`, the server half of an adapter); it
+  validates with `sanitizeShellSettingsDelta`, the untrusted-input reader on
+  the Node-safe `./workspace/server` entry (with `mergeShellSettingsDelta`)
 - Focus tools may register imperatively through `ShellState` or declaratively
   through Svelte helpers
 - Shell activities are client-side records; server jobs, polling, WebSockets,

package/dist/components/activity/ActivityList.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+import WorkspaceActivityList from '../workspace/admin-shell/ActivityList.svelte';
+import { tryUseAdminShell } from '../workspace/admin-shell/context.js';
+import { safeActivityHref } from './safe-href.js';
+import type { ActivityListEntry } from './types.js';
+
+interface Props {
+  /** Already-authorized activity rows to display. */
+  entries: ActivityListEntry[];
+  /** Message displayed by the shell list when no activities match. */
+  emptyLabel?: string;
+}
+let { entries, emptyLabel = 'No activity.' }: Props = $props();
+const shell = tryUseAdminShell();
+const prefix = `audit-feed:${crypto.randomUUID()}:`;
+$effect(() => {
+  if (!shell) return;
+  const ids = new Set(entries.map((entry) => `${prefix}${entry.id}`));
+  for (const entry of entries)
+    shell.upsertActivity({
+      id: `${prefix}${entry.id}`,
+      label: entry.title,
+      message: entry.detail,
+      detailHref: safeActivityHref(entry.href),
+      kind: prefix,
+      scope: 'system',
+      status: 'completed',
+      createdAt: entry.occurredAt,
+    });
+  return () => {
+    for (const id of ids) shell.removeActivity(id);
+  };
+});
+</script>
+{#if shell}<WorkspaceActivityList filter={{ kind: prefix }} {emptyLabel} />{:else}<p>{emptyLabel}</p>{/if}

package/dist/components/activity/ActivityList.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { ActivityListEntry } from './types.js';
+interface Props {
+    /** Already-authorized activity rows to display. */
+    entries: ActivityListEntry[];
+    /** Message displayed by the shell list when no activities match. */
+    emptyLabel?: string;
+}
+declare const ActivityList: import("svelte").Component<Props, {}, "">;
+type ActivityList = ReturnType<typeof ActivityList>;
+export default ActivityList;
+//# sourceMappingURL=ActivityList.svelte.d.ts.map

package/dist/components/activity/ActivityList.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityList.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/activity/ActivityList.svelte.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,UAAU,KAAK;IACb,mDAAmD;IACnD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiCD,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/activity/index.d.ts

@@ -0,0 +1,3 @@
+export { default as ActivityList } from './ActivityList.svelte';
+export type { ActivityListEntry } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/activity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/activity/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/activity/index.js

@@ -0,0 +1 @@
+export { default as ActivityList } from './ActivityList.svelte';

package/dist/components/activity/safe-href.d.ts

@@ -0,0 +1,3 @@
+/** Accept ordinary web links, never executable schemes or protocol-relative URLs. */
+export declare function safeActivityHref(value: string | null | undefined): string | undefined;
+//# sourceMappingURL=safe-href.d.ts.map

package/dist/components/activity/safe-href.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-href.d.ts","sourceRoot":"","sources":["../../../src/components/activity/safe-href.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CASpB"}

package/dist/components/activity/safe-href.js

@@ -0,0 +1,12 @@
+/** Accept ordinary web links, never executable schemes or protocol-relative URLs. */
+export function safeActivityHref(value) {
+    if (!value || value.startsWith('//') || value.includes('\\'))
+        return undefined;
+    try {
+        const url = new URL(value, 'https://smrt.invalid');
+        return ['https:', 'http:'].includes(url.protocol) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/components/activity/types.d.ts

@@ -0,0 +1,9 @@
+/** Authorized activity projected by an owning domain package. */
+export interface ActivityListEntry {
+    id: string;
+    title: string;
+    detail?: string;
+    occurredAt: string;
+    href?: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/activity/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/activity/types.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB"}

package/dist/components/activity/types.js

@@ -0,0 +1 @@
+export {};