@jskit-ai/agent-docs 0.1.274 → 0.1.276

package/guide/agent/framework/typed-features.md

@@ -724,6 +724,107 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
+### One read per table
+
+**A read that builds a list reads each table once for the whole list: one
+query per table with an id-list filter, the rows grouped in memory. It never
+reads one row, or runs one lookup, per item of the list.**
+
+- Collect the ids from the first read, then read each related table once with
+  an id-list filter: a `searchSchema` entry
+  `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
+  through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
+  Group the rows by id with `Map.groupBy()`.
+- `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
+  single-record read inside a loop over the list is a read per row, however
+  the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
+  item). So is a single-record helper reused for a list.
+- Work derived from a row (hashing, preparing a form, assembling a snapshot)
+  runs once per distinct input in the call, not once per row it appears in.
+- The list's query count follows its tables and pages (100 rows a page unless
+  the resource sets `queryMaxLimit`), never its rows: three hundred invoices
+  and their lines take a handful of queries, not three hundred more (see
+  [Budgets at realistic counts](#budgets-at-realistic-counts)).
+
+Why: a read per row costs nothing with three test rows and seconds with a few
+hundred real ones, and every lookup and visibility check inside it repeats too.
+
+```js
+// good: one read per table, however many invoices there are
+const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
+  queryParams: { filters: { workspace: workspaceId } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const lineRows = await queryAllJsonRestCollectionRows(api.resources.invoiceLines, {
+  queryParams: { filters: { invoiceIds: invoiceRows.map((invoice) => invoice.id) } },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+const linesByInvoice = Map.groupBy(lineRows, (line) => line.invoiceId);
+return invoiceRows.map((invoice) => ({ ...invoice, lines: linesByInvoice.get(invoice.id) || [] }));
+
+// bad: one more query, and its lookups and row policy, for every invoice
+for (const invoice of invoiceRows) {
+  invoice.lines = await invoiceLines.queryDocuments({ invoiceId: invoice.id }, options);
+}
+```
+
+### Bounded access checks
+
+**A row policy costs what the rows its query reads cost, never what the
+subject's stored history costs, and a write decides access once instead of
+paying a read policy for every row it writes.**
+
+- A `rowPolicy` adds one predicate to the query it is given: a join, `EXISTS`
+  or subquery correlated with the row being read, on indexed columns. It never
+  loads everything the subject was ever linked to (every source, notice or
+  grant in their history) to build an `IN` list, and never calls another
+  owner's access check once per item of that history. The
+  [row policies heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/row-policies.md)
+  has the policy contract and its package composition.
+- The policy runs on every single-record read, and a CRUD write includes one:
+  `createDocument()` and `patchDocumentById()` write with `returning: "full"`
+  and read the record back through the policy, and `patch` and `delete` first
+  look the record up through it. A write therefore pays the read policy for
+  each row it writes.
+- A write path decides access once, inside its transaction. A batch write (a
+  delivery, an import, a fan-out) whose per-row read-back would pay an
+  expensive policy writes through a repository method added with
+  `decorateRepository`, on `resolveRepoClient(database.knex, options)`,
+  setting the same columns the resource would, its ownership columns
+  included, and reading back only what it returns.
+- Its test runs one read and one write for a subject with a short history and
+  with a realistic long one, and asserts the same query count.
+
+Why: a check sized by history grows with every record the subject receives,
+so the same write that takes milliseconds in a test takes seconds a year later.
+
+```js
+// good: one predicate on the row being read
+function noticeVisibilityPolicy({ query, context, column, value, db }) {
+  const userId = resolveActorId(context);
+  if (!userId) return false;
+  query.where(column("recipientId"), value("recipientId", userId)).whereExists(
+    db("sources").select(1)
+      .whereColumn("sources.id", column("sourceId"))
+      .where("sources.status", "published")
+  );
+  return true;
+}
+
+// bad: every source the recipient was ever notified about, checked one by one
+async function noticeVisibilityPolicy({ query, context, column, value }) {
+  const sourceIds = await noticeHistory.listSourceIds(resolveActorId(context));
+  const readable = [];
+  for (const sourceId of sourceIds) {
+    if (await sources.canRead(sourceId, context)) readable.push(sourceId);
+  }
+  query.whereIn(column("sourceId"), readable.map((id) => value("sourceId", id)));
+  return true;
+}
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action
@@ -910,6 +1011,112 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
+### Budgets at realistic counts
+
+**A list, batch or write path has a database test at the row counts and
+history a real workspace holds, and that test fails above a fixed query
+budget, one that a read per row or a history-sized check cannot meet.**
+
+- Seed hundreds of records and long per-person histories, not one to three
+  rows: a read per row and a history-sized policy cost nothing at three.
+- Count the queries with the test Knex instance's `query` event and assert a
+  ceiling: the count the correct implementation needs at that size, which a
+  read per row overshoots by hundreds. A path that pages nothing (one read,
+  one write) asserts the same count at a short and a long history. A query
+  count is stable in CI; also report the time the call took.
+- Meet the budget by fixing the reads ([One read per
+  table](#one-read-per-table), [Bounded access checks](#bounded-access-checks)),
+  never by shrinking the data or raising the budget.
+
+Why: without a budget at real counts, a path that does one read per row ships,
+and its first sign is a request that takes seconds in production.
+
+```js
+// good
+test("the invoice list reads each table once", async () => {
+  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
+  let queries = 0;
+  const count = () => { queries += 1; };
+  knex.on("query", count);
+  try {
+    await invoices.listWithLines(workspace, { context });
+  } finally {
+    knex.off("query", count);
+  }
+  // A page of each table at a time; one read per invoice would add 300.
+  assert.ok(queries <= 40, `${queries} queries`);
+});
+
+// bad: three invoices and no budget, so a read per invoice passes
+test("the invoice list has its lines", async () => {
+  await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
+  assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
+});
+```
+
+### Time limits are not fixes
+
+**A slow test, suite, preparation or request is a defect to find, never a time
+limit to raise. Measure where the time goes, fix that cause, and keep the
+default limits.**
+
+- Raising `--test-timeout`, a test's `{ timeout }`, Playwright's `timeout`,
+  `test.setTimeout()` or an `expect` timeout, adding retries, or calling a
+  request in a loop until it answers hides the cause and lets it grow.
+- Read the preparation phases' durations and the query counts first; the
+  cause is usually a read per row, a history-sized policy, or a database
+  prepared by replaying migrations ([Test databases are prepared
+  once](#test-databases-are-prepared-once)).
+- A longer limit is right only for work that is long by nature, such as a
+  fixture of deliberate size, and the test names that work.
+- A time limit still bounds every run, so a hang ends; it is not a speed
+  setting.
+
+Why: a raised limit absorbs today's slowness and every later one, until a run
+takes hours and nobody knows which change made it slow.
+
+```js
+// good: the slow step was found and fixed, so the default limit holds
+test("delivers a batch of notices", async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+
+// bad
+test("delivers a batch of notices", { timeout: 600_000 }, async () => {
+  await deliveries.processBatch(workspace, { context });
+});
+```
+
+### Test databases are prepared once
+
+**A test run prepares each database once, from a stored snapshot of its
+schema, migration ledger and seed rows checked by a digest of their sources,
+and never replays the whole migration history inside the run.**
+
+- The snapshot is rebuilt only when the digest of the migration and seed
+  sources changes, once and outside the timed tests; every disposable
+  database, and every database a test migrated up or down, is restored from
+  it.
+- The full migration history runs once, in its own fresh-schema check
+  ([database verification](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#verification)).
+- The harness reports each preparation phase and its duration, and the suite
+  has a time budget, so slow preparation shows instead of hiding inside the
+  next test that waits for it.
+- The database layer guide's [integration test
+  databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)
+  gives the snapshot's contents per engine.
+
+Why: the migration history only grows, so a run that replays it whenever a
+schema changed gets slower with every migration the application adds.
+
+```js
+// good: the application's test support restores the snapshot its digest names
+before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+
+// bad: every file replays every migration
+before(() => knex.migrate.latest());
+```
+
 ## Files and layout
 
 ### Size limits

package/guide/agent/framework/ui-operations.md

@@ -23,37 +23,17 @@ only when defining or diagnosing topology. Resolve current dynamic parameters
 to an absolute URL or route object for sibling/child links—never bind a route
 template or relative string raw to Vue Router `to`.
 
-## Back navigation
-
-Check every page for a visible Back button that returns to the previous page.
-Omit it only when returning makes no product sense, such as the root
-landing page or a completed flow that must not reopen an expired step. State
-the reason in the implementation or review result; a drawer link is not Back.
-
-Plain **Back** normally follows the person's actual route history, retaining
-the originating page's query, filters, tab, and pagination. Reuse the existing
-JSKIT screen/navigation owner and its public seams. For history traversal use
-the app's Vue Router instance (`useRouter()` from `vue-router`, then
-[`router.back()`](https://router.vuejs.org/guide/essentials/navigation.html#traverse-history));
-`usePaths().page()` from `@jskit-ai/shell-web/client/navigation/usePaths`
-resolves a destination, not history. Do not invent a second navigation stack.
-
-For direct links, new tabs, or no usable in-app history, use a deliberate safe
-fallback resolved through the existing surface/workspace-aware path helpers.
-Do not infer a usable previous page from `window.history.length` alone or send
-people outside the app unexpectedly. Keep existing unsaved-change guards.
-
-A fixed parent/list destination is valid when the task calls for it; name it
-explicitly, for example **Back to appointments**. It must not silently replace
-ordinary Back. Shared CRUD `listLocation`/`listUrlTemplate` links are fixed
-destinations, not proof of previous-page behavior. Keep Back distinct from
-Cancel, Close, and a wizard's Previous step.
-
-Place Back consistently near the start of the page's existing action region,
-before forward/primary actions in reading and keyboard order. Reuse shell or
-shared-screen controls; avoid duplicates, drawer-only access, or adding a page
-heading just to house it. Keep its meaning and accessible name clear at every
-supported width.
+## Navigation and Up
+
+Follow [Navigation and Up](./material-3.md#navigation-and-up), a MUST that
+plain `jskit check` enforces: the shell owns the Up arrow (one, in the top app
+bar, on every inner page) and the per-tab trail. An app declares each inner
+page's parent as route meta `jskit.parent`, resolves every inner link through
+JSKIT navigation, finishes custom forms with `useShellNavigation().finish()`,
+and never writes back logic, `router.back()`, `history.back()`,
+`window.location` navigation or a "Back to X" control. Keep Up distinct from
+Cancel, Close, and a wizard's Previous step; keep existing unsaved-change
+guards.
 
 `createShellRouter()` owns scroll position (`shell/application-shell`
 pattern); never reset scroll in page components.
@@ -95,10 +75,13 @@ pattern, never its private CSS.
 Exercise user-facing changes with Playwright at compact, medium, and expanded
 widths. Check overflow, clipped text, duplicate navigation, route placement,
 actions, skeleton replacement, error feedback, and target sizes. Use relative
-URLs. With `PLAYWRIGHT_BASE_URL` set, start no duplicate server. For Back,
-enter the same page from two origins and verify each returns to its own origin
-with context intact. Also check direct entry, reload, browser back/forward,
-fixed-destination exceptions, and any unsaved-change guard.
+URLs. With `PLAYWRIGHT_BASE_URL` set, start no duplicate server. For Up
+(`shellBackButton(page)` and `pressShellBack(page)` from
+`@jskit-ai/shell-web/test/shellNavigation`), reach a page from two origins (one
+sideways) and verify each Up returns to its own origin and that chains unwind;
+open the page directly and verify Up reaches its declared parent; verify
+main-menu destinations show no arrow, a reload keeps the trail, and Save or
+Cancel never leaves the form in it.
 
 A managed host owns its browser and may provide
 `PLAYWRIGHT_STORAGE_STATE`; never print or commit that value, bypass it,

package/guide/agent/framework/ui-pass.md

@@ -0,0 +1,155 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/framework/ui-pass.md`. Do not edit manually. -->
+
+---
+title: UI pass
+description: Make a task's changes, a section of the app, or the whole app exact Material 3 without changing behavior.
+---
+
+# UI pass
+
+A UI pass makes JSKIT UI exact Material 3 at one of three scopes: **the
+changes** a task made (the default), **a section** of the app, or **the whole
+app**. Read the complete [Material 3 rules](./material-3.md) first; navigation
+and Up come first there.
+
+## Every scope
+
+- **The same rules:** the [Material 3 rules](./material-3.md), their exact sizes,
+  `jskit check`, `jskit check m3`, and screenshots at 390, 768 and 1280 wide, in
+  light and dark.
+- **Navigation is must-fix at every scope:** fix every `nav/*` error inside the
+  scope (declare parents, resolve links through JSKIT, delete back controls and
+  back logic); never only report one. Plain `jskit check` must not end with a
+  new error. Errors outside the scope, in an app not yet converted, are
+  reported as must-fix findings.
+- **Behavior otherwise stays exactly as it is:** no feature, field, action,
+  permission, validation or data change. A defect, missing behavior or test gap
+  you notice is a finding for the report, not a fix.
+- **Exceptions:** take the [approved routes](./material-3.md#exceptions) first.
+  Add an `m3-check: allow` exception only after the person agreed to it, and
+  list every exception the changes add, with its file, line and reason, in the
+  report.
+- **JSKIT first:** if JSKIT itself blocks an exact result, report the exact JSKIT
+  change (package, file, what is missing). Never compensate with app CSS,
+  `!important` or a copied package file.
+- **Screenshots** come from the managed browser or a temporary Playwright spec.
+  Keep them out of the repository (`test-results/` is ignored) and delete the
+  temporary spec afterwards. With `defaultTheme: "system"`, `emulateMedia`
+  selects the scheme:
+
+```js
+import { test } from "@playwright/test";
+
+for (const scheme of ["light", "dark"]) {
+  for (const width of [390, 768, 1280]) {
+    test(`suppliers ${width} ${scheme}`, async ({ page }) => {
+      await page.emulateMedia({ colorScheme: scheme });
+      await page.setViewportSize({ width, height: 900 });
+      await page.goto("/home/suppliers");
+      await page.screenshot({ path: `test-results/ui-pass/after/suppliers-${width}-${scheme}.png`, fullPage: true });
+    });
+  }
+}
+```
+
+- **Look at every screenshot** before reporting. They are the only proof of
+  what the checks cannot see: layout, spacing, contrast, overflow, clipped
+  labels, borders where tones belong, colour that only works in one scheme, an
+  Up arrow where it should not be or missing where it should.
+- **Prove Up** on the screens in scope, with `shellBackButton(page)` and
+  `pressShellBack(page)` from `@jskit-ai/shell-web/test/shellNavigation`:
+  contact → supplier → Up shows the contact; a supplier opened from a pasted
+  link → Up shows the Suppliers list; no arrow on main-menu pages; no "Back to
+  X" anywhere.
+
+## 1. The changes
+
+The default, and what an automatic UI pass after a plan runs.
+
+- **In scope:** every screen, component and style the task created or edited,
+  plus the screens that render them. Explicit commits replace "the task's own
+  changes" when they are named.
+- **Method:**
+  1. List the changed UI files and the screens that render them.
+  2. Check each against the Material 3 rules and fix what is off, inside the
+     changes only.
+  3. Run `jskit check m3` on the changed UI files until it reports nothing,
+     and plain `jskit check` until it passes.
+  4. Take after screenshots of each affected screen, and look at them.
+  5. Run the focused tests of the affected screens.
+- **Report:** what was fixed; anything outside the changes that looks wrong, as
+  findings only (not fixed; navigation ones marked must-fix); the check
+  results; the screenshots; what is unverified.
+
+Example: a task added a Delete button and a "Back to suppliers" link to the
+supplier page. The pass replaces the button's `color="#d32f2f"` and
+`variant="outlined"` with the error colour role, removes the link, declares the
+page's parent (`/suppliers`), checks `src/pages/home/suppliers/[supplierId].vue`
+clean, and shows the supplier at the six sizes. It reports, unfixed, that the
+Contacts list scrolls sideways at 390.
+
+## 2. A section
+
+On request ("UI pass the Suppliers section").
+
+- **In scope:** a named area: a module, a route subtree, a set of screens or a
+  shared component family. Every screen in it, touched or not, so the section is
+  consistent.
+- **Method:**
+  1. Inventory the section's screens and the components they render.
+  2. Take before screenshots of each screen, with its empty, error and dialog
+     states where they exist.
+  3. Map each screen pattern to its Material 3 canonical layout (list-detail,
+     supporting pane, feed) and components, in a table.
+  4. Convert, navigation first: declare each inner page's parent, route every
+     inner link through JSKIT navigation, delete back handlers and "Back to X"
+     controls.
+  5. Take after screenshots beside the before ones.
+  6. Run `jskit check m3` on the section until it reports nothing.
+  7. Delete the app CSS that is no longer needed.
+  8. Change browser tests only where markup changed; every behavior assertion
+     stays.
+- **Report:** a before/after gallery, the mapping, the non-blank CSS lines
+  (`<style>` blocks and CSS files) before and after, the check results, the
+  Up proof and the test results.
+
+Example: the Suppliers section has a list, a record, a new and an edit page.
+The mapping reads: list as a list with filter chips and a FAB, list-detail on
+expanded widths; record as a header with status chips and value-first lists;
+new and edit as a form with Cancel and Save in the bar. The pass removes a
+bordered filter panel and 46 lines of CSS, declares the three inner pages'
+parents, and the check reports nothing for `src/pages/home/suppliers`.
+
+## 3. The whole app
+
+On request ("UI pass the whole app"). Every screen, the shell and navigation
+included.
+
+1. **Inventory and before screenshots** of every screen type: sign-in, home,
+   dashboard, every list, one record per module, every form type, settings, a
+   dialog, an empty state and an error state.
+2. **A short spec:** the foundation decisions (seed colour, scheme generation,
+   type, shape, icons, Vuetify defaults) and a table mapping every screen
+   pattern to its Material 3 layout and components.
+3. **Foundation first:** the theme from one seed, type, shape, icons and Vuetify
+   defaults, then the app shell and navigation (every inner page's parent, so
+   plain `jskit check` passes).
+4. **Screens in packages,** at most three at a time, never two on the same file.
+5. **After screenshots** for each package.
+6. **Delete as you go:** app CSS shrinks to almost nothing, with no hex colour
+   outside `src/theme/`; `jskit check m3` reports nothing for the whole app.
+7. **Tests:** browser tests change only where markup changed, every behavior
+   assertion stays the same, and nothing regresses.
+8. **An independent review:** a fresh agent, given only the screenshots and the
+   spec, lists every departure from Material 3 as MUST or SHOULD. Fix every MUST
+   and review again until there are none.
+
+- **Report:** the gallery, the reviewer's final pass with no MUST items, the
+  counts (screens, CSS lines before and after, check findings before and
+  after), the Up proof and the test results.
+
+Example: a twelve-screen app. The spec picks the existing brand orange as seed
+and maps four lists, four records, three forms and settings. The foundation
+package replaces a hand-picked palette and MDI icons; three screen packages
+follow. App CSS goes from 640 lines to 38, the check from 212 findings to none,
+and the second review has no MUST items.

package/guide/agent/index.md

@@ -11,6 +11,7 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 - [Quickstart](/guide/app-setup/quickstart)
 - [Application foundations](/guide/app-setup/initial-scaffolding)
 - [Upgrade JSKIT](/guide/app-setup/upgrading-jskit)
+- [Move an app to the Material 3 defaults](/guide/app-setup/material-3-migration)
 - [Migrate an existing application](/guide/app-setup/existing-application-migration)
 - [A more interesting shell](/guide/app-setup/a-more-interesting-shell)
 - [Authentication](/guide/app-setup/authentication)
@@ -32,6 +33,8 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
   composable, component, client factory or client provider
 - [UI operations](/guide/framework/ui-operations)
 - [Material 3](/guide/framework/material-3)
+- [UI pass](/guide/framework/ui-pass): make a task's changes, a section or the
+  whole app exact Material 3
 - [Translating a JSKIT app](/guide/framework/translation)
 - [Complete source pattern library](/patterns/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.274",
+  "version": "0.1.276",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.9",
+    "@jskit-ai/kernel": "0.2.10",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/example/package.json

@@ -34,7 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.9",
+    "@jskit-ai/kernel": "0.2.10",
+    "@jskit-ai/material-web": "0.1.0",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -42,14 +43,14 @@
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
-    "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.9",
+    "vuetify": "^4.3.0",
+    "@jskit-ai/http-runtime": "0.2.10",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.26",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/src/main.js

@@ -4,9 +4,11 @@ import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import { createRouter, createWebHistory } from "vue-router/auto";
 import { routes } from "vue-router/auto-routes";
 import "vuetify/styles";
+import "@jskit-ai/material-web/client/material.css";
 import { createVuetify } from "vuetify";
-import { aliases as mdiAliases, mdi } from "vuetify/iconsets/mdi-svg";
+import { createMaterialVuetifyOptions } from "@jskit-ai/material-web/client";
 import App from "./App.vue";
+import { theme } from "./theme/index.js";
 import NotFoundView from "./views/NotFound.vue";
 import { bootInstalledClientModules } from "virtual:jskit-client-bootstrap";
 import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
@@ -39,16 +41,8 @@ const { router, fallbackRoute } = createShellRouter({
   }
 });
 
-const vuetify = createVuetify({
-  theme: {
-    defaultTheme: "light"
-  },
-  icons: {
-    defaultSet: "mdi",
-    aliases: mdiAliases,
-    sets: { mdi }
-  }
-});
+// Material 3 from the app's theme (src/theme/index.js), with Material Symbols behind every icon alias.
+const vuetify = createVuetify(createMaterialVuetifyOptions(theme));
 const pinia = createPinia();
 const queryClient = new QueryClient({
   defaultOptions: {

package/patterns/minimal-foundation/example/src/pages/home/index.vue

@@ -1,21 +1,8 @@
 <template>
-  <section class="home-start-screen d-flex flex-column ga-4">
-    <v-sheet rounded="lg" border class="home-start-screen__panel">
-      <p class="text-body-2 text-medium-emphasis mb-0">
-        Recent work, saved records, and next actions will appear here once this app has data.
-      </p>
-    </v-sheet>
+  <section class="d-flex flex-column align-center ga-4 py-16 text-center on-surface-variant">
+    <v-icon icon="$inbox" size="48" />
+    <p class="text-body-large mb-0">
+      Recent work, saved records, and next actions will appear here once this app has data.
+    </p>
   </section>
 </template>
-
-<style scoped>
-.home-start-screen {
-  --home-start-panel-padding: 1rem;
-  margin-inline: auto;
-  max-width: 48rem;
-}
-
-.home-start-screen__panel {
-  padding: var(--home-start-panel-padding);
-}
-</style>

package/patterns/minimal-foundation/example/src/theme/index.js

@@ -0,0 +1,9 @@
+// The app's only theme facts. Material 3's light and dark colour schemes are generated from this one seed colour and
+// follow the device's setting: change the seed to rebrand. A colour the app really owns goes in `colors` by camelCase
+// name (it gets its own container roles, harmonized to the seed), and an icon of its own goes in `icons` as
+// `{ name: "<24x24 SVG path>" }`, used as `$name`.
+export const theme = {
+  seed: "#6750A4",
+  colors: {},
+  icons: {}
+};

package/patterns/minimal-foundation/example/src/views/NotFound.vue

@@ -5,9 +5,10 @@ const message = "The page you requested does not exist.";
 
 <template>
   <v-container class="fill-height d-flex align-center justify-center">
-    <v-card class="pa-6 text-center" max-width="560" rounded="lg">
-      <v-card-title class="text-h4">{{ title }}</v-card-title>
-      <v-card-text class="text-medium-emphasis">{{ message }}</v-card-text>
-    </v-card>
+    <section class="on-surface-variant text-center">
+      <v-icon icon="$searchOff" size="48" />
+      <h1 class="text-headline-small on-surface mt-4 mb-2">{{ title }}</h1>
+      <p class="text-body-large mb-0">{{ message }}</p>
+    </section>
   </v-container>
 </template>

package/patterns/shell-foundation/example/package.json

@@ -34,7 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.9",
+    "@jskit-ai/kernel": "0.2.10",
+    "@jskit-ai/material-web": "0.1.0",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -42,16 +43,15 @@
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
-    "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.9",
-    "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.2.10",
+    "vuetify": "^4.3.0",
+    "@jskit-ai/http-runtime": "0.2.10",
+    "@jskit-ai/shell-web": "0.2.11",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.26",
+    "@jskit-ai/jskit-catalog": "0.2.28",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.9"
+    "@jskit-ai/kernel": "0.2.10"
   },
   "jskit": {
     "kind": "runtime",