@jskit-ai/agent-docs 0.1.278 → 0.1.280

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,31 +75,49 @@ 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
-   top-level: no arrow, a fresh trail.
+   top-level: no arrow, a fresh trail. Placements are literal declarative data,
+   one `addPlacement({ ... })` per destination with plain string `surface`,
+   `scopedSuffix` and `unscopedSuffix`, never built by a helper, a spread or a
+   template, so a reader and `jskit check` can map every destination.
 3. **Every in-app link and navigation goes through JSKIT navigation:**
    `: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),
-   from `@jskit-ai/shell-web/client/navigation/documentNavigation`.
+   from `@jskit-ai/shell-web/client/navigation/documentNavigation`. `leaveApp`
+   opens the site with a push, so Back returns to the page; a hand-off page
+   that only forwards (to an OAuth consent screen) uses
+   `leaveApp(url, { replace: true })`, so Back from the site doesn't rerun it.
 
 ### Forbidden in app code
 
@@ -107,9 +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
@@ -167,29 +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):
-
-- 40dp buttons with a 48dp touch target, icon buttons included;
-- 12dp cards;
+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. 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 16dp FABs;
+- 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
 
@@ -197,29 +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.
-- **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`. `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.
+  `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.
 - **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). 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
 
@@ -242,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.
@@ -287,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
 
@@ -308,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` in an app that uses the JSKIT shell |
-| `m3/raw-hex` | a hex colour outside `src/theme/` |
+| `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 |
@@ -338,19 +401,41 @@ Take the approved route first; none needs an exception:
   `<v-chip color="partner">`. A hex string is harmonized toward the seed; a
   colour that must keep its hue is `{ value: "#F5C518", blend: false }`
   (Material Theme Builder's Blend switched off), with the same four roles.
-- **Chart and data colours** come from the theme: `const theme = useTheme()`,
-  then `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
+- **Content colours**, colours that are content rather than UI, keep one
+  value in both schemes: an identity palette a person picks and the server
+  stores, avatar and illustration artwork, brand marks (a language's
+  file-type tint), fixed chart series, QR codes, colours written into
+  exported files. They are named exports of plain hex values in
+  `src/theme/palettes.js`, used as they are, never for UI chrome (a theme
+  colour is toned per scheme, so it can't keep an identity the same).
+  Components read them through bindings:
+
+  ```vue
+  <script setup>
+  // src/theme/palettes.js: export const botColours = ["#6750A4", "#B3261E"];
+  import { botColours } from "@/theme/palettes.js";
+  const props = defineProps({ bot: Object });
+  const ring = botColours[props.bot.colour];
+  </script>
+  <template>
+    <v-avatar :style="{ backgroundColor: ring }"><svg><path :fill="ring" /></svg></v-avatar>
+  </template>
+  <style scoped>.v-avatar { outline: 2px solid v-bind(ring); }</style>
+  ```
+- **Chart and data colours** that follow the scheme come from the theme:
+  `const theme = useTheme()`, then
+  `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
 - **A third-party widget** lives in one wrapper component, such as
   `src/components/RouteMap.vue`, that hands it theme colours; pages use only
   the wrapper.
 
-What is left 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 -->`
+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
@@ -359,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

@@ -174,6 +174,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 +458,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
 ```