@jskit-ai/agent-docs 0.1.279 → 0.1.281

package/skills/jskit/references/client-features.md

@@ -232,7 +232,7 @@ const ConversationClientProvider = defineProvider({
   },
   /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
-    components.register("conversation.web.settings.element", ConversationSettingsElement);
+    components.register("conversation.web.status.widget", ConversationStatusWidget);
   }
 });
 
@@ -241,6 +241,40 @@ const components = new Map();
 export function registerComponent(id, component) { components.set(id, component); }
 ```
 
+### Provider subpaths
+
+**Export each client provider by a subpath of its own. The provider's file
+imports only what every page needs, such as a widget the shell always shows; a
+screen that only some routes show is imported by those routes.**
+
+Why: every page of every app loads the client providers, and what they import,
+before it shows anything. The client bootstrap imports a provider through the
+subpath export that names its file, so the screens `./client` re-exports, and
+their libraries, load only with the routes that show them. A provider without a
+subpath, or a `./client` that declares `routeComponents` or `clientRoutes` or
+uses `export *`, brings all of `./client` to every page.
+
+```json
+// good: package.json
+"exports": {
+  "./client": "./src/client/index.js",
+  "./client/providers/ConversationClientProvider": "./src/client/providers/ConversationClientProvider.js"
+}
+
+// bad: package.json, no subpath for the provider, so every page loads all of ./client
+"exports": {
+  "./client": "./src/client/index.js"
+}
+```
+
+```js
+// good: the provider's file imports the widget every page shows
+import ConversationStatusWidget from "../components/ConversationStatusWidget.vue";
+
+// bad: the provider's file imports a screen that only its route shows
+import ConversationSettingsScreen from "../components/ConversationSettingsScreen.vue";
+```
+
 ### Injected values
 
 **`inject()` takes the owner's exported key, never a literal. A required value

package/skills/jskit/references/existing-application-migration.md

@@ -128,7 +128,13 @@ The foundation servers reuse compiled response serializers for identical JSON
 schemas through `createCachedResponseSerializerFactory` from
 `@jskit-ai/kernel/server/http`. This reduces duplicate startup compilation and
 retained memory in applications with many routes. Each Fastify compiler context
-keeps its own cache; request data and response payloads are not cached.
+keeps its own cache; request data and response payloads are not cached. A
+serializer is compiled when a response first uses it, in every environment, so
+startup compiles none. Startup still checks every response schema as
+fast-json-stringify would before building it: an invalid schema or a `$ref`
+that does not resolve stops the server. A problem fast-json-stringify only
+finds while generating a serializer fails the first response that uses it, so
+keep a test that calls each route.
 
 Existing applications adopt the same setup in their own `server.js` after
 upgrading JSKIT and declaring the directly used

package/skills/jskit/references/heuristics/INDEX.md

@@ -44,7 +44,9 @@ How to use it:
   - [crud-repository-mapping.md](./crud-repository-mapping.md)
 - row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`, row policy cost, slow writes through a policy, access check per history item
   - [row-policies.md](./row-policies.md)
-- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size, read per row, N+1 queries, slow endpoint, query budget, realistic row counts, slow tests, raised timeout, `migrate.latest()` in tests, test database snapshot
+- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `api.resources.x.query`, every row, list stops at 20 rows, `queryAllJsonRestCollectionRows`, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size, read per row, N+1 queries, slow endpoint, query budget, realistic row counts, slow tests, raised timeout, `migrate.latest()` in tests, test database snapshot, `--test-concurrency=1`, `node --test`, `jskit test`, `testConcurrency()`, `V64_TEST_CONCURRENCY`, Playwright `workers`, Vitest `maxWorkers`, tests one file at a time, test files colliding in parallel, `jskit-test: alone`, `test/*` findings of `jskit check`
   - [typed-features.md](./typed-features.md)
 - client features, composable, `use<Name>`, Vue component, client provider, props, emits, `inject`, `provide`, `ref`, `reactive`, `watch`, `addEventListener`, `setInterval`, module state, `Object.freeze` on a composable, `?.()` in a template, `jskit/typed-inject`, `jskit/collaborator-props`, `jskit/fixed-result-shape`, `jskit/released-listeners`, `jskit/no-module-state`, `jskit/no-frozen-vue-state`, `clientFeaturesConfig`, `shared resource:`
   - [client-features.md](./client-features.md)
+- sanity checks, is this sane, query count that grows with the rows, a list that stops at 20 or 100 rows, `createDocument()` per row of a batch, `jskit test`, one file at a time, test database preparation, `TEST_DB_NAME`, `mode: "patch"`, a route `rateLimit` nothing tests, `input.workspaceId`, a refactor or consolidation that drops behaviour, a JSKIT update, a changed theme or Vuetify default, `jskit.surface` with a parent, an assistant tool's output contract, a screen that renders everything, feedback covering an action, `NODE_ENV=production`, a production start
+  - [Sanity checks](../sanity-checks.md)

package/skills/jskit/references/heuristics/row-policies.md

@@ -39,9 +39,9 @@ Package composition:
 
 Cost:
 
-- a policy's cost follows the rows its query reads: add a join, `EXISTS` or subquery correlated with the row through `column()` and `value()`, on indexed columns
+- a policy's cost follows the rows its query reads: add a join, `EXISTS` or subquery correlated with the row through `column()` and `value()`, on indexed columns; look at its SQL too, since a statement that runs to kilobytes is planned again on every read that carries it
 - never load the subject's whole history (every source, notice or grant they were ever linked to) to build an `IN` list, and never call another owner's access check per item of it; another package's grant is a predicate contribution
-- the policy runs on every single-record read, including the read-back after `createDocument()` and `patchDocumentById()` (`returning: "full"`) and the lookup before `patch` and `delete`, so a write pays it once per row it writes
+- the policy runs on every single-record read, including the read-back after `createDocument()` and `patchDocumentById()` (`returning: "full"`, their default) and the lookup before `patch` and `delete`, so a write pays it once per row it writes
 - a write decides access once, inside its transaction; a batch write that would pay an expensive read-back per row follows the typed features guide's [Bounded access checks](../typed-features.md#bounded-access-checks)
 
 Child-resource rules:
@@ -58,7 +58,7 @@ Testing:
 - assert hidden direct records behave as not found
 - assert children and includes do not leak records
 - assert package and provider dependencies stay one-way
-- run one read and one write for a subject with a short history and with a realistic long one (hundreds of linked rows), and assert the same query count
+- count the queries of one read and one write for a subject with a short history and with a realistic long one (hundreds of linked rows), and fail when the count grows with the history
 
 AnyAPI boundary:
 

package/skills/jskit/references/heuristics/typed-features.md

@@ -63,10 +63,10 @@ ends with the same link.
   - [One helper per package](../typed-features.md#one-helper-per-package)
 - `options?.trx || options?.transaction`, a hand-read actor, cursor or created id
   - [One reader per fact](../typed-features.md#one-reader-per-fact)
-- `api.resources.x.query(…)` with no `page` for a list, `queryDocuments(query)` with no `limit` in a service, a list that stops at 20 rows
+- `api.resources.x.query(…)` with no `page` for a list, `queryDocuments(query)` with no `limit` in a service, a list that stops at 20 rows, `page: { size: 500 }` or `limit: 500` that returns 100 rows
   - [Every row](../typed-features.md#every-row)
-- `await getDocumentById(…)`, `queryDocuments(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a slow list endpoint
-  - [One read per table](../typed-features.md#one-read-per-table)
+- `await getDocumentById(…)`, `queryDocuments(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a list whose query count grows with its rows, a slow list endpoint
+  - [Lists read related rows in batches](../typed-features.md#lists-read-related-rows-in-batches)
 - a `rowPolicy` that loads a person's whole history or calls an access check per item, `createDocument` per row of a batch, a write that gets slower as history grows
   - [Bounded access checks](../typed-features.md#bounded-access-checks)
 - a route that queries storage, `boot*.js` holding routes
@@ -85,10 +85,10 @@ ends with the same link.
   - [Tests are not callers](../typed-features.md#tests-are-not-callers)
 - `…ForTests`, `__reset…`, `testOnly…` exports (`jskit/no-test-only-export`)
   - [No test-only exports](../typed-features.md#no-test-only-exports)
-- a list, batch or write test with one to three rows, no query count, a slow endpoint first seen with real data
-  - [Budgets at realistic counts](../typed-features.md#budgets-at-realistic-counts)
-- a raised `{ timeout }`, `test.setTimeout()`, `--test-timeout` or Playwright `timeout`, retries or a request loop that absorbs slowness, a slow suite
-  - [Time limits are not fixes](../typed-features.md#time-limits-are-not-fixes)
+- a list, batch or write test with one to three rows, no query count, a fixed query ceiling tuned to pass, a slow endpoint first seen with real data, a hand-written `knex.on("query")` counter, a patched `Client.prototype.query`, `countQueries`, `countRuntimeQueries`, a route's query count
+  - [Query counts at realistic sizes](../typed-features.md#query-counts-at-realistic-sizes)
+- `node --test --test-concurrency=1`, `workers: 1`, `fileParallelism: false`, a suite that runs one file at a time, test files that collide when run together, a Playwright webServer running `npm run develop` or `vite`, a browser suite that takes hours, `test/*` findings of `jskit check`
+  - [Test files run in parallel](../typed-features.md#test-files-run-in-parallel)
 - `knex.migrate.latest()` in each test file, a template database rebuilt by migrating, test preparation slower than its tests
   - [Test databases are prepared once](../typed-features.md#test-databases-are-prepared-once)
 - a file over 750 lines, a function over 600 (`max-lines`, `max-lines-per-function`), a data module

package/skills/jskit/references/heuristics/ui-testing.md

@@ -50,30 +50,36 @@ Rules:
 ## Keep startup incremental
 
 Run related cases in one suite invocation. Prepare the isolated database and
-fixtures once for that invocation, never once per test. Retain the test schema
-and migration ledger, apply only pending migrations, and reset fixture data
-deterministically. Restore any migration-owned baseline rows through the test
-seed. MySQL applications start from the `database/mysql-application` pattern's
-`example/tests/browser/database.js`. Require a repeat-start regression test that
-proves unchanged migration history, removal of stale data, pending migration
-application, and isolation from the normal database.
-
-Use `BROWSER_TEST_DB_NAME` for that retained schema and a different
-`TEST_DB_NAME` for disposable integration and migration tests. Reject a name
-collision before connecting. Include disposable cleanup between browser starts
-in the regression: one test's teardown must not erase another test's migrations.
-
-Do not drop/recreate the database, replay completed migrations, build every
-module fixture, or run a production frontend build for each focused check.
-Choose small fixture sets for the selected suite; realistic row counts belong
-in the database tests that hold each endpoint's query budget. Fresh-schema
+fixtures once for that invocation, never once per test. An app's
+`playwright.config.mjs` is `browserTestConfig()` from
+`@jskit-ai/jskit-catalog/browser-tests`: the production build, made once and
+reused while its sources are unchanged, and one server, port and database per
+worker. Its `prepare` module (the `database/mysql-application` and
+`database/postgres-application` patterns' `example/tests/e2e/databases.js`)
+restores each worker's copy of `BROWSER_TEST_DB_NAME` from the stored schema
+snapshot and runs the fixture seed, which restores any migration-owned
+baseline rows. The migrations are replayed only when one changes, so a second
+run reports a stored snapshot, no stale rows, and an unchanged normal
+database.
+
+Use `BROWSER_TEST_DB_NAME` for the browser copies and a different
+`TEST_DB_NAME` for disposable integration and migration tests; the harness
+refuses a collision, or one with the application's database, before
+connecting.
+
+Do not replay completed migrations, build every module fixture, or run a
+production frontend build for each focused check. A
+build made once for a whole run is different: it is the fix when a development
+server makes every page load slow, and browser tests never run on the
+development server. Choose small fixture sets for the selected
+suite; realistic row counts belong in the database tests that compare each
+endpoint's query counts. Fresh-schema
 migration tests and production-artifact tests are separate operations. Measure
 migration, fixture, and server startup time and fix the slow phase; never retry
 a slow launch, or raise its deadline or a spec's timeout, to absorb it. A page
-that needs a longer timeout to load is a slow endpoint to fix (typed features'
-Time limits are not fixes). When a host supplies a managed target, use its
-scoped suite command so one startup serves the whole batch and cleanup
-restores normal Preview.
+that needs a longer timeout to load is a slow endpoint to fix. When a host
+supplies a managed target, use its scoped suite command so one startup serves
+the whole batch and cleanup restores normal Preview.
 
 ## Keep browser evidence focused
 

package/skills/jskit/references/material-3.md

@@ -42,7 +42,8 @@ app and never leaves it.
 - **What the person sees:** one Up arrow on every inner page, also when opened
   directly: icon only (`$arrowBack`), accessible name "Back" (localized), a
   tooltip on pointer devices. None on top-level destinations, and no other
-  back control anywhere; the bar title says where the person is. A list-detail
+  back control anywhere; the bar title says where the person is. A new or edit
+  form shows a close (X) in the arrow's place, which cancels. A list-detail
   layout showing the parent beside the page needs no arrow for that step;
   collapsed to one pane, the record pane gets it back.
 - **Where Up goes:** to the previous trail entry while it is valid, so inside
@@ -74,11 +75,17 @@ Exactly this, and nothing more:
    </script>
    ```
 
-   The same key works in a `<route lang="json">` block. A record names its
-   list, an edit page its record, a sub-page its page. Tabs under a layout
+   The same key works in a `<route lang="json">` block. Tabs under a layout
    (`settings.vue` rendering `<RouterView>` for `settings/`) declare nothing:
    they inherit the nearest layout's declaration, and moving between them keeps
-   the trail.
+   the trail and the scroll. A folder without a layout (`bookings/` with no
+   `bookings.vue`) only groups routes: its pages are different pages, each
+   opening at the top. The parent is read from the page up to its surface root, the
+   record that declares `jskit.surface`, and stops there. So the surface goes
+   only on the surface's layout page (`account.vue`: `ShellLayout` around
+   `<RouterView />`) and the parent on the page it renders
+   (`account/index.vue`). A package route declares its parent in its
+   `package.json` `meta`; under no layout, its component draws `ShellLayout`.
 2. **Each top-level destination is a main-navigation item** (a `kind: "link"`
    placement with `target: "shell.primary-nav"` or `"shell.secondary-nav"`) and
    declares no parent; nor do its tabs. A shell page with no parent is
@@ -90,14 +97,20 @@ Exactly this, and nothing more:
    `:to="paths.page('/suppliers')"` and `router.push(paths.page(...))` with
    `usePaths()`, the CRUD runtime's `resolveViewUrl()`, `resolveEditUrl()` and
    `resolveParams()`, and link placements (`surface` with `scopedSuffix` and
-   `unscopedSuffix`; `to` only for a global route such as `/auth/login`). The
-   trail follows the router, so there is no special link component.
+   `unscopedSuffix`; `to` only for a global route). A global route
+   (`scope: "global"`, on no surface) is
+   `paths.page("/auth/login", { scope: "global" })`; `explicitTo` only passes
+   through a finished target that arrives as data, never a hand-written path.
+   The trail follows the router, so there is no special link component.
 4. **A custom new or edit page finishes through the shell:**
    `useShellNavigation()` (`@jskit-ai/shell-web/client/navigation/useShellNavigation`)
    gives `finish(target)` for Save (the target replaces the form in the trail)
    and `finish()` for Cancel (back to where the form was opened, else its
-   parent). A page whose record turns out deleted or forbidden calls
-   `pageUnavailable()`. JSKIT's CRUD screens already do both.
+   parent); `useShellPageClose({ label, close })`
+   (`@jskit-ai/shell-web/client/composables/useShellPageClose`) makes the
+   arrow its Cancel, never an X beside it. A page whose
+   record turns out deleted or forbidden calls `pageUnavailable()`. JSKIT's
+   CRUD screens already do all three.
 5. **A full page load goes through the shell too:** `reloadAppPage(path)`
    (after sign-in or a user switch, to rebuild client state) and
    `leaveApp(url)` (an external site in the same tab, such as a payment page),
@@ -113,11 +126,12 @@ Exactly this, and nothing more:
 | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
 | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
 | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
-| `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
-| `nav/missing-parent` | an inner page of a shell surface without a declared parent |
+| `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component (`<ContextBackButton />` or `<page-back-link>`, and its import), a `goBack()`-style handler |
+| `nav/missing-parent` | an inner page of a shell surface without a declared parent, when it always renders under the shell's top app bar (a layout that also renders its pages without `ShellLayout`, such as a shop device's sign-in in a `v-if`, leaves its pages unjudged) |
 | `nav/top-level-parent` | a main-navigation destination that declares a parent |
 | `nav/placement-data` | a main-navigation placement that isn't literal data (no page is judged for a missing parent until it is) |
 | `nav/missing-shell-layout` | a page that declares a parent with no shell layout rendering it, so its title, Up and actions never show |
+| `nav/surface-parent` | a parent declared beside `jskit.surface`, which the shell never reads |
 | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
 
 ### Each rule, right and wrong
@@ -175,35 +189,43 @@ Exactly this, and nothing more:
 - **Type:** Vuetify 4 Material 3 roles (`text-headline-small`,
   `text-title-large`, `text-body-medium`, `text-label-large`). Never the
   Material 2 scale (`text-h5`, `text-body-2`) or a page-local type system.
-  Roboto Flex is the font.
+  Material 3 has two typefaces, both Roboto Flex unless the app names its own
+  in `src/theme/index.js`:
+  `typography: { brand: '"Fraunces", serif', plain: '"Inter", sans-serif' }`.
+  `brand` sets display, headline and title-large, `plain` the rest (title-medium
+  and -small, body, label); each is a CSS font-family value, and the app loads
+  the font. Never set `font-family` or `--v-font-body` in app CSS.
 - **Icons:** Material Symbols Rounded through Vuetify `$` aliases: Vuetify's
   standard ones (`$close`, `$menu`, `$delete`, `$prev`, `$next`) and JSKIT's
   camelCase names (`$add`, `$edit`, `$search`, `$moreVert`, `$filterList`,
   `$arrowBack`); `$homeFilled`-style `Filled` variants mark active navigation.
   An app adds an icon under `theme.icons` in `src/theme/index.js` as
   `{ name: "<24x24 path data>" }` from Material Symbols Rounded, then uses
-  `$name`. No `mdi-*` strings and no `@mdi/js` imports in app code.
+  `$name`. No `mdi-*` strings and no `@mdi/js` imports in app code. Material
+  Symbols has no brand marks (Google, GitHub, a payment network): a brand's
+  logo is the brand's own artwork, a content image or SVG used as its owner
+  publishes it, not an icon alias.
 
 ## Exact sizes
 
-JSKIT ships these exact sizes; an app never re-implements or overrides them,
-and needs no Sass and no `!important` (Vuetify 4 keeps its CSS in cascade
-layers):
+JSKIT ships these exact sizes; an app never re-implements or overrides them:
 
 - 40dp buttons with a 48dp touch target, icon buttons included; a smaller
   button is `size="small"` or `size="x-small"`, which keeps its smaller look
-  and the 48dp target;
-- one-line button labels: a label longer than its button ends in an ellipsis.
-  Keep labels short, and give a button whose label can run long, such as a
-  name, the full label as its `title`;
-- 12dp cards: elevated (the default) at level 1, flat and tonal at level 0;
+  and the 48dp target. No icon button is under 32dp, and a target stops at
+  the edge of a button beside it, so each of a row's touching icon buttons
+  answers its own press;
+- one-line button labels, ending in an ellipsis: keep labels short, and give
+  one that can run long, such as a name, its full label as `title`;
+- 12dp cards: flat (the default) and tonal at level 0, `variant="elevated"`
+  at level 1; flat expansion panels;
 - 28dp dialogs and bottom-sheet top corners, square full-screen dialogs;
 - 8dp chips, and FABs of 56dp (small 40dp, large 96dp; extended 56dp tall)
   with 16dp corners;
 - emphasized easing, with reduced motion honoured.
 
 So never set `height` or `min-height` on a button, or a radius on a card,
-dialog, chip or FAB. A missing size is a JSKIT defect.
+dialog, chip or FAB.
 
 ## The top app bar carries the page
 
@@ -211,35 +233,46 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   `useShellPageTitle(title)` (`@jskit-ai/shell-web/client/composables/useShellPageTitle`)
   for a runtime title such as the record's name. The shell renders it as the
   app bar's only `h1`; pages add no `h1`, page header, title block or
-  standalone heading. A section inside a page uses a title role. A page with
-  no top app bar (a hero front page, an intro, an invite or hand-off page)
-  has its own one `h1`.
-- **Up** sits in the bar on every inner page (see Navigation and Up). On phones
-  it replaces the menu icon.
+  standalone heading. Route pages own the title: a section or a nested
+  component uses a title role (a component's claim gives the title back when
+  it goes). A page with no top app bar (a hero front page, an intro, an invite
+  or hand-off page) has its own one `h1`.
+- **Up** leads the bar on every inner page; on phones it replaces the menu
+  icon.
 - **A layout that draws its own top app bar** (a workspace bar with the
   app's own controls, instead of `ShellLayout`) builds it from `ShellLayout`'s
   own pieces, from `@jskit-ai/shell-web/client`. It calls `useShellAppBar()`
   once, so its pages enter the trail and their `ShellPageActions` show in its
   bar, and renders `ShellUpButton` first, then `ShellPageTitle` (the page's one
-  `h1`: `useShellPageTitle()`, else the route's `jskit.title`, else its `title`
-  prop) and `ShellPageActionsTarget`. A title that is also a switcher, such as a
+  `h1`) and `ShellPageActionsTarget`. A title that is also a switcher, such as a
   project menu, goes in `ShellPageTitle`'s default slot (given `{ title }`) as
-  the menu's activator, so it stays the one `h1`. `jskit check` counts it as a shell
-  layout, so its inner pages need parents; an Up the app draws itself is a
-  `nav/back-control` finding.
+  the menu's activator, so it stays the one `h1`. `jskit check` counts it as a
+  shell layout, so its inner pages need parents.
 - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
   (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
   `ShellPageAction` with `icon`, `label` (also its accessible name and compact
-  tooltip), and `primary`, `to`, `replace`, `disabled`, `loading` or `color`.
-  On compact widths every action shows only its icon except the single
-  `primary` one.
+  tooltip), and `primary`, `to`, `replace`, `href` (with `download` for a
+  file, such as a CSV export), `disabled`, `loading` or `color` (`error` for a
+  destructive one); attributes such as `target` reach its button. On compact
+  widths the bar keeps one trailing item after the title: the single
+  `primary` action when the page has one (a form's Save), otherwise its own
+  item nearest the corner (a top-right placement such as the account avatar).
+  Every other action and the bar's other items (a notification bell, tools)
+  go to its "More actions" menu, where `overflow` actions always are. Medium
+  and wider bars show them all.
 - **Window size classes:** compact under 600 (navigation bar), medium 600–839
-  (navigation rail), expanded 840–1199 and large from 1200 (drawer). A surface
-  with no navigation destinations, such as an account surface, draws no
-  navigation bar, rail or drawer; its pages keep the app bar. Read them
-  from `useShellWindowSizeClass()`
+  (navigation rail), expanded 840–1199 and large from 1200 (drawer), read from
+  `useShellWindowSizeClass()`
   (`@jskit-ai/shell-web/client/composables/useShellWindowSizeClass`), never from
-  copied breakpoint numbers.
+  copied breakpoint numbers. A surface with fewer than two navigation
+  destinations (none, as on an account surface, or Home alone) draws no
+  navigation bar, rail or drawer; its pages keep the app bar.
+- **Section tabs:** a page's own sections (`page.section-nav`) are Material 3
+  primary tabs: the topology names `ShellSectionTabLinkItem`'s token (the
+  starter registers it as `local.main.ui.section-tab-link-item`), and the page
+  draws one tab row, `display: flex; overflow-x: auto` over a 1dp
+  `outline-variant` bottom border. `ShellTabLinkItem` is the navigation bar's
+  destination; placed in a page it draws a section tab.
 
 ## Colour
 
@@ -262,35 +295,41 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   control; never a permanent panel of outlined fields. A card opens its record
   when tapped (a stretched title link); a table row opens on click. Row actions
   are trailing icon buttons (edit, a `$moreVert` overflow menu, a chevron to
-  open), never "View" or "Edit" text buttons on every row. "New" is an extended
-  FAB on compact and medium widths and a filled bar button on expanded. Empty
-  and error states carry an icon.
+  open), never "View" or "Edit" text buttons on every row. "New" is
+  `ShellPrimaryAction` (`label`, and `to` or a click handler): an extended FAB
+  on compact and medium widths, a filled bar button on expanded. On/off filters
+  are `aria-pressed` chips, or chips in a `v-chip-group`; JSKIT draws them as
+  filter chips. Empty and error states carry an icon.
 - **A list never scrolls sideways, at any width.** The list's own width (a
   container query, not the window) chooses cards or table. Cards flow into a
   grid; tables use a fixed layout with an ellipsis on long values, and fold
   low-priority columns into a stronger column's second line. Lists show figures
   ("120 kg", tabular and right-aligned) and names, never ids.
 - **Record:** a header (avatar, title, status chips) and value-first detail
-  lists, never a grid of label/value text. Edit sits in the bar; the record's
+  lists, never a grid of label/value text. Edit sits in the bar, its secondary
+  actions in the bar's overflow menu, never in the content; the record's
   next workflow step is the one filled button, shown in context rather than a
   row of mostly disabled actions.
-- **Form:** Cancel and Save sit in the bar. Fields use `hideDetails: "auto"`.
-  Nothing moves under a finger: a multi-select chip field keeps its input width
-  when it loses focus. A pick-one-of-N choice is a segmented button with
-  `role="radiogroup"` and `role="radio"`/`aria-checked` buttons.
+- **Form:** the bar's close (X) cancels and Save is its filled action. Fields
+  use `hideDetails: "auto"`. Nothing moves under a finger: a multi-select chip
+  field keeps its input width when it loses focus. A pick-one-of-N choice is a
+  segmented button (`v-btn-toggle`, drawn by JSKIT, with 12dp segment sides as
+  in any `v-btn-group`) with `role="radiogroup"` and
+  `role="radio"`/`aria-checked` buttons.
 - **Dialogs:** plain `v-dialog` and `v-bottom-sheet`; JSKIT gives them their
   Material 3 shapes. A full-screen dialog (compact and medium) puts close, title
   and its confirm action in a top bar, never at the bottom where a snackbar
   covers them.
 - **Menus and badges:** a menu's list has `role="menu"` and its items
   `role="menuitem"`, with `aria-disabled` on unavailable ones; a badge has a
-  `label` such as "3 batches".
+  `label` such as "3 batches". JSKIT draws a menu's list and a dialog's card;
+  an app sets no `VMenu` or `VDialog` defaults, under which
+  Vuetify 4.2.1 to 4.3.2 loses a `v-select`'s typeahead match, or a dialog's
+  virtual list, when an ancestor re-renders.
 
 ## Components, state, and feedback
 
-- Choose components by purpose. Prefer standard buttons, fields, lists,
-  tables, sheets, dialogs, menus, navigation, progress, alerts, snackbars, and
-  tooltips over custom imitations.
+- Choose standard components by purpose over custom imitations.
 - Give one primary action emphasis. Distinguish destructive, secondary, and
   icon-only actions without relying on color; give icon controls accessible
   names and fields meaningful labels, errors, and autocomplete behavior.
@@ -307,6 +346,11 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   field. A user-triggered command uses JSKIT's shared action
   feedback/snackbar path. Never insert a transient command-error alert above
   page content where it shifts the working layout.
+- A snackbar never covers the FAB or the actions it reports on. `ShellErrorHost`
+  centres it above the navigation bar on compact windows and starts it at the
+  content's start edge, at most half its width, on wider ones. A FAB takes
+  layout room (`<v-fab app layout>`, as `ShellPrimaryAction`'s does), so the
+  snackbar shows above it.
 
 ## Adaptive layout
 
@@ -328,16 +372,15 @@ npx jskit check m3 src/pages/home/books  # a section
 npx jskit check m3 $(git diff --name-only --diff-filter=d main)  # changed files
 ```
 
-Plain `jskit check` fails on the [navigation rules](#forbidden-in-app-code);
-fix every one, because nothing excuses them. `jskit check m3` lists those and
-the visual rules below. The visual rules are a report until every JSKIT app has
-been converted to them; the JSKIT release after that makes plain `jskit check`,
-and so every app's verify, fail on them too:
+Plain `jskit check` fails on the [navigation rules](#forbidden-in-app-code).
+`jskit check m3` lists those and the visual rules below. The visual rules are a
+report until every JSKIT app has been converted to them; the JSKIT release after
+that makes plain `jskit check`, and so every app's verify, fail on them too:
 
 | Rule | Finds |
 |---|---|
-| `m3/duplicate-h1` | a second `h1`, or an in-page `h1` under the shell's page title |
-| `m3/raw-hex` | a hex colour outside `src/theme/` (`palettes.js` holds content colours) |
+| `m3/duplicate-h1` | a second `h1` that can show beside the first (one per `v-if` branch is one), or an in-page `h1` under a layout that always shows the shell's page title |
+| `m3/raw-hex` | a hex colour, or one written as channels (`rgba(0, 0, 0, 0.15)`, as in a hand-made shadow), outside `src/theme/` (`palettes.js` holds content colours); `rgba(var(--v-theme-shadow), 0.2)` reads a role and passes |
 | `m3/dark-scheme` | no dark scheme, or the theme pinned to light |
 | `m3/outlined-card` | `variant="outlined"` or `border` on a card or sheet |
 | `m3/mdi-icon` | `mdi-*` icon strings and `@mdi/js` imports |
@@ -390,9 +433,9 @@ What is left, such as a colour inside static SVG markup that can't import,
 may be excused one line at a time, on its line or the line before: `<!-- m3-check: allow m3/raw-hex - the partner's contractual logo colour -->`
 (`// m3-check: ...` in scripts, `/* ... */` in CSS). **Never add one on your
 own:** ask the person first, naming the rule and the reason. A comment with no
-reason (`m3/allow-reason`) or an unknown rule (`m3/allow-rule`), and any
-`m3-check: allow nav/...` (`nav/allow`), is itself a finding; nothing turns the
-check off for a file, a folder or the app. `jskit check m3` lists every
+reason (`m3/allow-reason`) or an unknown rule (`m3/allow-rule`) is itself a
+finding, as any `nav/allow` is; nothing turns the check off for a file, a
+folder or the app. `jskit check m3` lists every
 exception with its file, line and reason, and their total.
 
 ## Material 3 audit
@@ -401,19 +444,16 @@ Run this behavior-preserving audit over every affected screen:
 
 1. Identify the owning JSKIT surface, shared screen, shell, placement, theme,
    and Vuetify components before judging local markup.
-2. Check navigation and Up first, as must-fix: plain `jskit check` passes;
-   every inner page has a parent and one Up arrow in the bar; main-menu
-   destinations have none; no inner link is hand-built; nothing writes back
-   logic.
+2. Check navigation and Up first, as must-fix: plain `jskit check` passes and
+   every rule in Navigation and Up holds.
 3. Find parallel components, duplicated state chrome, page-local themes, raw
    visual constants, CSS against Vuetify internals, nested generic cards,
-   borders instead of tones, Material 2 typography, and desktop-only layout.
-4. Check hierarchy, token use, component purpose, responsive presentation,
-   interaction states, keyboard/focus behavior, labels, targets, contrast, and
-   reduced motion against the rules above.
-5. Correct issues at the narrowest established owner. Consolidate only truly
+   borders instead of tones, Material 2 typography, and desktop-only layout;
+   check states, focus, labels, targets, contrast and reduced motion against
+   the rules above.
+4. Correct issues at the narrowest established owner. Consolidate only truly
    repeated policy; avoid pass-through wrappers and speculative abstractions.
-6. Run `jskit check` and `jskit check m3` on the affected files, then focused
+5. Run `jskit check` and `jskit check m3` on the affected files, then focused
    tests and Playwright at compact, medium, and expanded widths in light and
    dark (`shellBackButton(page)` and `pressShellBack(page)` from
    `@jskit-ai/shell-web/test/shellNavigation` drive Up).

package/skills/jskit/references/multi-homing.md

@@ -56,8 +56,12 @@ config.tenancyPolicy = {
 ```
 
 Provisioning runs in the users profile-sync lifecycle after registration and
-sign-in. The first run creates the personal workspace, its owner membership and
-its settings; later runs reuse it. The default name is the user's display name,
+sign-in, at each session refresh, and on a request whose identity's email or
+display name changed. The first run creates the personal workspace, its owner
+membership and its settings; later runs reuse it. An ordinary request only reads
+the existing profile, so a personal workspace, owner membership or settings row
+deleted while the person is signed in comes back at their next sign-in or
+session refresh, not at their next request. The default name is the user's display name,
 or email, followed by "'s Workspace". To choose another, provide the
 `workspaces.personal-workspace-name` capability from an application feature. It
 receives the synchronized profile (`id`, `displayName`, `email`, `username`), and
@@ -174,6 +178,12 @@ capability provides:
 | `workspaces.repositories.workspaces`, `.workspaceMemberships`, `.workspaceSettings`, `.workspaceInvites` | Repository access inside the application's own transactions |
 | `workspaces.tenancyProfile` | The resolved tenancy mode and workspace policy |
 
+To check one person's membership, for example a notification recipient, call
+`workspaces.services.members.getMember(workspace, userId, options)`. It answers
+that member's `listMembers` entry, or `null` for a removed or unknown member,
+and reads only that membership. Do not list every member to find one: the list
+grows with the workspace, and a lookup per row multiplies it.
+
 ### Invitation email
 
 To send invitation email, provide the optional `workspaces.invite-mailer`
@@ -452,9 +462,9 @@ Use only a verified empty disposable database named
 reports its engine version, applies package migrations and drops fixture tables.
 
 ```sh
-node --test packages/workspaces-core/test/*.test.js
+npx jskit test packages/workspaces-core/test/*.test.js
 # Set JSKIT_REPOSITORY_TEST_DATABASE_URL to the verified empty disposable target.
-node --test packages/workspaces-core/test/repositories.integration.test.js
+npx jskit test packages/workspaces-core/test/repositories.integration.test.js
 npm run verify
 ```