@jskit-ai/agent-docs 0.1.279 → 0.1.280

package/guide/agent/framework/material-3.md

@@ -47,7 +47,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
@@ -79,11 +80,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
@@ -95,14 +102,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),
@@ -118,11 +131,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
@@ -180,35 +194,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
 
@@ -216,35 +238,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
 
@@ -267,35 +300,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.
@@ -312,6 +351,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
 
@@ -333,16 +377,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 |
@@ -395,9 +438,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
@@ -406,19 +449,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/guide/agent/framework/sanity-checks.md

@@ -0,0 +1,180 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/framework/sanity-checks.md`. Do not edit manually. -->
+
+# Sanity checks
+
+Before calling a list, a save, a test, a refactor, a screen or a deployment
+done, measure what it actually costs and does, judge whether that is sane, and
+fix the cause when it is not. This page is the JSKIT part of that: the
+pitfalls JSKIT's own packages cause, then which JSKIT call, helper or setting
+applies each check, with one line on what the check catches and why.
+
+## JSKIT's own pitfalls
+
+### Theme and component defaults
+
+**Check:** after changing a theme, a Vuetify default, a material-web default
+or a shared component, use what it affects in a production build: open a
+select and type, press a segmented button at desktop width, tap neighbouring
+icon buttons, and leave a field to see whether the layout shifts under the
+next tap. A default reaches every component that renders the one it names, so
+a change made for one screen can break others that never import it
+([Material 3](/guide/framework/material-3)).
+
+**Examples:**
+
+- A `VMenu: { VSheet: {} }` default broke a select's typeahead.
+- A common button padding squeezed segmented buttons into slivers.
+- A field that grew 32 px on blur moved the button under a person's tap.
+
+### Navigation metadata
+
+**Check:** open each inner page directly and by link, and see its Up arrow
+and title. Some navigation declarations look right but switch Up off, and
+some shapes leave pages the navigation rules cannot judge
+([Material 3](/guide/framework/material-3)):
+
+- a parent declared beside `jskit.surface` is never read; the surface goes on
+  the layout page and the parent on the page it renders (`nav/surface-parent`
+  reports the two on one record);
+- an inner page repeating its surface becomes a root of its own, with no Up;
+- until a main-navigation placement is literal data, no page is judged for a
+  missing parent (`nav/placement-data`);
+- a layout that also renders its pages without `ShellLayout` leaves those
+  pages unjudged by `nav/missing-parent`, so a missing parent passes;
+- a package route is judged only when its client entry lists
+  `routeComponents` literally; a built map passes unjudged.
+
+**Example:** a design-system update moved a page title into a top app bar
+that one page did not have, so its title vanished; only the browser suite
+caught it.
+
+### Generated action and tool contracts
+
+**Check:** call each assistant tool the way the model will, with sparse
+`fields` and an `include`, and compare the result with the output contract it
+advertises. An action is a tool only when it has an input contract and a
+truthful model-facing output; the assistant validates the result against
+`extensions.assistant.output` and rejects unexpected fields, so a contract
+that promises what execution cannot return fails at run time, not at review
+([Assistant](/guide/app-extras/assistant#database-surface-action-tools)).
+
+**Example:** sparse primary fields stay sparse, and an included record is read
+from its lookup container (`items[0].lookups.pet.name`); a contract that
+expects the relationship id or an unselected field never gets it.
+
+## Applying each check
+
+### Every row
+
+- An unpaged JSON:API query returns the first 20 rows, and a page above the
+  resource's `queryMaxLimit` (100 unless it sets one) is cut to that size,
+  both without an error; CRUD `queryDocuments()` refuses such a `limit`. A
+  read its callers treat as complete uses `queryAllJsonRestCollectionRows()`
+  or the repository's `queryEveryDocument()`, because the missing rows
+  otherwise vanish from every picker and delivery built on it
+  ([Every row](/guide/framework/typed-features#every-row)).
+- A lookup by a unique key matches at most one row, so it may read `rows[0]`
+  of a plain query.
+
+### Query counts and batches
+
+- Count a path's queries with the test Knex instance's `query` event at a few
+  rows and at a realistic number; the count should follow tables and pages,
+  not rows ([Query counts at realistic
+  sizes](/guide/framework/typed-features#query-counts-at-realistic-sizes)).
+- A JSON:API read adds a few lookup and visibility queries per page and per
+  relationship field. That follows pages, so it is expected.
+- `getDocumentById()`, `queryDocuments()` or a service `get` inside a loop is
+  the usual per-row read; batch it with an id-list `searchSchema` filter or
+  `include`, grouped with `Map.groupBy()` ([Lists read related rows in
+  batches](/guide/framework/typed-features#lists-read-related-rows-in-batches)).
+- A `rowPolicy` adds one correlated predicate to the query it is given, so
+  its cost follows the rows read, not the subject's history. It runs on every
+  single-record read, including a write's default `returning: "full"` read
+  back, so a write that discards its result passes `returning: "minimal"` and
+  a batch of creates uses `createDocuments()`, in the owner's transaction
+  ([Bounded access
+  checks](/guide/framework/typed-features#bounded-access-checks)).
+
+### Tests
+
+- `jskit test` runs test files in parallel within the machine's test budget
+  (`V64_TEST_CONCURRENCY`, else half the CPUs), and Playwright's `workers` and
+  Vitest's `maxWorkers` come from `testConcurrency()`. `jskit check` reports a
+  script or config that runs files one at a time; a file that must run alone
+  says why on its first line, `// jskit-test: alone - <reason>` ([Test files
+  run in parallel](/guide/framework/typed-features#test-files-run-in-parallel)).
+- Tests use `TEST_DB_NAME` and `BROWSER_TEST_DB_NAME`, both different from
+  `DB_NAME`, because tests write and delete rows and would destroy the
+  developer's data. A skip for want of a test database is a failure.
+- Test databases restore a stored snapshot checked by a digest of the
+  migration and seed sources, and the harness reports each preparation phase's
+  duration, so slow preparation shows ([Test databases are prepared
+  once](/guide/framework/typed-features#test-databases-are-prepared-once),
+  [integration test
+  databases](/guide/app-setup/database-layer#integration-test-databases)).
+
+### Inputs and access
+
+- An action input declared `mode: "patch"` makes every field optional. Use it
+  only for an action that updates part of a record, and send that action
+  nothing to see what it does, because a missing field is then never refused.
+- A route that repetition can abuse declares `rateLimit`, which the kernel
+  refuses with 429 and `kernel.http.rateLimited`; auth's limits come from
+  `config.auth.rateLimits` ([Sign-in
+  protection](/guide/app-setup/authentication#sign-in-protection)). Each
+  limit needs a test expecting the 429, or a dropped one goes unseen.
+- Who acts comes from `resolveActor(context)` and the workspace from the
+  context's resolvers ([One reader per
+  fact](/guide/framework/typed-features#one-reader-per-fact)); send another
+  workspace's id in the body and see the context win.
+
+### Refactors
+
+Before changing a JSKIT feature, list where its behaviour lives, with the test
+that covers each item, and walk the list again after: routes, actions and
+their input schemas, row policies, CRUD fields, lookups and hooks, placements
+and navigation meta, messages and their codes, events, jobs and migrations.
+These are the places a consolidation drops behaviour without a failing build.
+
+### Changes others depend on
+
+- After updating JSKIT packages, read [Upgrade
+  JSKIT](/guide/app-setup/upgrading-jskit) and each package changelog's
+  "Upgrading" notes, then boot, sign in and run the browser tests before
+  anything else, because a changed default shows only at run time.
+
+### Screens
+
+- A long list renders what is visible, with pages or `v-virtual-scroll`,
+  because every row rendered costs DOM nodes and main-thread time.
+- Command feedback goes through the shell's snackbar path: `ShellErrorHost`
+  keeps it clear of the FAB and the actions it reports on, and a full-screen
+  dialog puts its confirm action in the top bar, where a snackbar never covers
+  it ([Material 3](/guide/framework/material-3)).
+- Up is the shell's, from `meta.jskit.parent`; the navigation rules forbid
+  `router.back()` and hand-made back controls, so Up lands inside the app
+  even on a page opened from a link.
+
+### Production settings
+
+- `NODE_ENV=production` is JSKIT's only production switch. Without it a
+  deployed server runs as development: no first-account setup code, and
+  development-only settings accepted.
+- On an empty production database, local auth asks for the first account's
+  setup code, so whoever reaches a new deployment first cannot own it ([The
+  first account in
+  production](/guide/app-setup/authentication#the-first-account-in-production-local-auth)).
+  Give any registration of your own the same protection.
+- `config.securityHeaders` sends the security headers, with the content
+  security policy reported, not enforced, by default; read them on a
+  production build ([Security
+  headers](/guide/app-setup/initial-scaffolding#security-headers)).
+- Email confirmation needs `auth.local.confirmation-sender` in production, or
+  the server refuses to start while anyone may register ([Email
+  confirmation](/guide/app-setup/authentication#email-confirmation-local-auth)).
+- Changing the assistant's instructions needs `assistant.settings.update` or
+  the surface's own permission ([Who may change the
+  instructions](/guide/app-extras/assistant#who-may-change-the-instructions)).
+  Its tools run as the typing user, through the `automation` channel, so an
+  action kept off that channel is never a tool.

package/guide/agent/framework/translation.md

@@ -193,6 +193,10 @@ and params to `details.fieldErrorCodes`, so an untranslated app shows exactly
 the English it showed before. The failed check's own params (for example
 `limit`) are sent too, and the coded entry's `params` win over them. JSKIT's
 own schemas use this form, which is why their field messages translate.
+With json-rest-schema 1.0.18 or later, which checks them, an array field's
+`minItems` and `maxItems` failures send `kernel.validation.field.minItems` and
+`kernel.validation.field.maxItems` with `{ min | max, actual }`, and its
+`messages.minItems` and `messages.maxItems` override them.
 
 ## Placement labels