@jskit-ai/agent-docs 0.1.279 → 0.1.281

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

@@ -443,6 +443,9 @@ record declares `mode: "patch"`; a command never does.**
 
 - Patch mode skips `required`, so a service keeps its guard for a field a
   patch input lists as required.
+- An input field lists its allowed values with `enum`; the kernel refuses
+  `oneOf` on an input field at startup, because json-rest-schema checks no
+  `oneOf` and the field would accept any value.
 
 Why: a command whose required field is never enforced reaches the service
 without it.
@@ -644,7 +647,7 @@ way (is this user an operator) is a member of its owner's capability.**
 - A helper two packages of an application use lives in its shared package,
   never inside one of them.
 
-Why: copies drift, and the next reader cannot tell which one is right.
+Why: the kernel's helpers fix one meaning of empty, and a copy brings its own.
 
 ```js
 // good
@@ -673,7 +676,8 @@ helper, never by hand.**
 | the workspace a request asks for, before any action context | `requestedWorkspaceScope(request)` (`@jskit-ai/workspaces-core/server/support/workspaceRouteInput`) |
 | a context's workspace id | `resolveWorkspaceScopeValue(context)` (`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`) |
 
-Why: each hand-written copy treats a missing value its own way.
+Why: each reader knows every place JSKIT keeps its fact (`trx` or
+`transaction`, a tagged result's wrapper), and a hand read misses one.
 
 ```js
 // good
@@ -693,11 +697,17 @@ page means "the first 20 rows".**
 - json-rest-api answers a query that names no page with the resource's
   default page, 20 rows, and says nothing about the rest. The CRUD
   repository's `queryDocuments(query)` without a `limit` is the same first
-  page.
-- The helper reads cursor pages of the resource's maximum size
-  (`queryMaxLimit`, 100 unless the resource sets it) in id order until none
-  follows, keeping the call's transaction and context, so no row is skipped
-  or repeated. It sets the page and sort itself; sort the rows it returns.
+  page, and one with a `limit` above its `queryMaxLimit()` (100) throws,
+  because json-rest-api would answer only 100. A CRUD read of every record
+  uses the repository's `queryEveryDocument(query, options)`, which answers
+  one JSON:API document `{ data, included }` with no `limit`, `cursor` or
+  `sort`.
+- The helper reads cursor pages of 1,000 rows (json-rest-api's server-only
+  `pageSizeLimit`; a resource whose `queryMaxLimit` is larger uses that) in id
+  order until none follows, keeping the call's transaction and context, so no
+  row is skipped or repeated. Each page pays the row policy and linkage
+  queries once, so 480 rows cost 3 statements, not 15. It sets the page and
+  sort itself; sort the rows it returns.
 - A lookup by a unique key (an id, a slug, a token hash, a unique pair such
   as workspace and user) matches at most one row and may read `rows[0]` of a
   plain query. A read of the newest or first few rows names its own `sort`
@@ -724,33 +734,35 @@ const rows = extractJsonRestCollectionRows(await api.resources.workspaceMembersh
 }, createJsonRestContext(options.context)));
 ```
 
-### One read per table
+### Lists read related rows in batches
 
-**A read that builds a list reads each table once for the whole list: one
-query per table with an id-list filter, the rows grouped in memory. It never
-reads one row, or runs one lookup, per item of the list.**
+**A read that builds a list fetches its related rows in batches, an id-list
+query per related table, and groups them in memory, so its query count follows
+the tables and pages it reads, not the rows.**
 
-- Collect the ids from the first read, then read each related table once with
-  an id-list filter: a `searchSchema` entry
+- Collect the ids from the first read, then read each related table with an
+  id-list filter: a `searchSchema` entry
   `{ type: "array", actualField: "<column>", filterOperator: "in" }`, read
   through `queryAllJsonRestCollectionRows()`, or the resource's `include`.
   Group the rows by id with `Map.groupBy()`.
-- `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
-  single-record read inside a loop over the list is a read per row, however
-  the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
-  item). So is a single-record helper reused for a list.
+- A count that grows with the rows means something runs per row:
+  `getDocumentById()`, `queryDocuments()`, a service `get` or another owner's
+  single-record read inside a loop over the list, however the loop is spelled
+  (`for`, `map` with `Promise.all`, a helper called per item), or a
+  single-record helper reused for a list.
 - Work derived from a row (hashing, preparing a form, assembling a snapshot)
   runs once per distinct input in the call, not once per row it appears in.
-- The list's query count follows its tables and pages (100 rows a page unless
-  the resource sets `queryMaxLimit`), never its rows: three hundred invoices
-  and their lines take a handful of queries, not three hundred more (see
-  [Budgets at realistic counts](#budgets-at-realistic-counts)).
+- A JSON:API read also costs a few lookup and visibility queries per page and
+  relationship field, and pages hold the resource's `queryMaxLimit` (100 rows
+  unless it sets one). That cost follows pages, so three hundred invoices take
+  a few more queries than ten, not three hundred more ([Query counts at
+  realistic sizes](#query-counts-at-realistic-sizes)).
 
-Why: a read per row costs nothing with three test rows and seconds with a few
-hundred real ones, and every lookup and visibility check inside it repeats too.
+Why: each JSKIT single-record read runs its lookups and row policy too, so a
+read per row repeats all of them.
 
 ```js
-// good: one read per table, however many invoices there are
+// good: a read per related table, however many invoices there are
 const invoiceRows = await queryAllJsonRestCollectionRows(api.resources.invoices, {
   queryParams: { filters: { workspace: workspaceId } },
   transaction: resolveTransaction(options),
@@ -784,21 +796,25 @@ paying a read policy for every row it writes.**
   [row policies heuristic](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/row-policies.md)
   has the policy contract and its package composition.
 - The policy runs on every single-record read, and a CRUD write includes one:
-  `createDocument()` and `patchDocumentById()` write with `returning: "full"`
-  and read the record back through the policy, and `patch` and `delete` first
-  look the record up through it. A write therefore pays the read policy for
-  each row it writes.
-- A write path decides access once, inside its transaction. A batch write (a
-  delivery, an import, a fan-out) whose per-row read-back would pay an
-  expensive policy writes through a repository method added with
-  `decorateRepository`, on `resolveRepoClient(database.knex, options)`,
-  setting the same columns the resource would, its ownership columns
-  included, and reading back only what it returns.
-- Its test runs one read and one write for a subject with a short history and
-  with a realistic long one, and asserts the same query count.
-
-Why: a check sized by history grows with every record the subject receives,
-so the same write that takes milliseconds in a test takes seconds a year later.
+  `createDocument()` and `patchDocumentById()` default to `returning: "full"`,
+  which reads the record back through the policy, and `patch` and `delete`
+  first look the record up through it.
+- A write path decides access once, inside its transaction. A write that does
+  not use its result passes `returning: "minimal"` or `"none"`, and a batch of
+  creates (a delivery, an import, a fan-out) goes through
+  `createDocuments(payloads, { trx, context })`, which reads nothing back
+  unless asked
+  ([writes that return less](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#writes-that-return-less)).
+  Any other batch whose per-row lookup would pay an expensive policy writes
+  through a repository method added with `decorateRepository`, on
+  `resolveRepoClient(database.knex, options)`, setting the same columns the
+  resource would, its ownership columns included.
+- Its test counts the queries of one read and one write for a subject with a
+  short history and for one with a long one ([Query counts at realistic
+  sizes](#query-counts-at-realistic-sizes)).
+
+Why: the row policy runs on every read, write read-back and lookup, so every
+request pays what it costs.
 
 ```js
 // good: one predicate on the row being read
@@ -935,7 +951,8 @@ carries on.**
   (`response.body.cancel()`), for queue tails whose error reaches the queued
   caller, and for client best effort, each with a short comment saying so.
 
-Why: `() => {}` hides a wiring `TypeError` along with the failure.
+Why: a collaborator call's failure can be a wiring `TypeError`, and
+`() => {}` hides it with the rest.
 
 ```js
 // good
@@ -957,8 +974,8 @@ frame.**
 - Complete a double with the method the code calls, returning its neutral
   value; never shape production code around a double.
 
-Why: a double that mirrors internals pins them, so the test breaks on a
-refactor and passes on a real bug.
+Why: an owner's seams are its contract; its id formats and stream frames
+change with its package.
 
 ```js
 // good
@@ -977,8 +994,8 @@ double.**
 - One named clock per factory (`now = Date.now`) is a platform default, not a
   test seam.
 
-Why: a seam kept for tests is a shape no real caller uses, and a reader
-cannot tell it apart from one that matters.
+Why: a factory's parameters are its contract with the features that call it,
+and a test is not one of them.
 
 ```js
 // good
@@ -997,8 +1014,8 @@ through the feature, and pure helpers through `__testables`.**
 - `__testables` holds pure helpers only, never one that touches a
   collaborator or reads request facts.
 
-Why: a test-only export widens the module's API and invites production
-callers.
+Why: `__testables` is the one way a test reaches inside a module, so every
+other export is production API.
 
 ```js
 // good
@@ -1011,107 +1028,171 @@ export function resetInvoiceCacheForTests() {
 }
 ```
 
-### Budgets at realistic counts
-
-**A list, batch or write path has a database test at the row counts and
-history a real workspace holds, and that test fails above a fixed query
-budget, one that a read per row or a history-sized check cannot meet.**
-
-- Seed hundreds of records and long per-person histories, not one to three
-  rows: a read per row and a history-sized policy cost nothing at three.
-- Count the queries with the test Knex instance's `query` event and assert a
-  ceiling: the count the correct implementation needs at that size, which a
-  read per row overshoots by hundreds. A path that pages nothing (one read,
-  one write) asserts the same count at a short and a long history. A query
-  count is stable in CI; also report the time the call took.
-- Meet the budget by fixing the reads ([One read per
-  table](#one-read-per-table), [Bounded access checks](#bounded-access-checks)),
-  never by shrinking the data or raising the budget.
-
-Why: without a budget at real counts, a path that does one read per row ships,
-and its first sign is a request that takes seconds in production.
+### Query counts at realistic sizes
+
+**A list, batch or write path's database test counts its queries with
+`countQueries()` at a few rows and at a realistic number, and fails when the
+count grows with the rows instead of the pages.**
+
+- `countQueries(knex, work)`, from
+  `@jskit-ai/database-runtime/server/testDatabases`, runs `work` and returns
+  its `result`, the `count` of statements the Knex instance or transaction
+  sent meanwhile (a transaction's `BEGIN` and `COMMIT` included) and their
+  SQL in `queries`. Pass the Knex the path runs on: the one the test built its
+  repository or service with.
+- A route is counted through the server the test boots in its own process
+  (`createServer()`, then `app.inject()`): `countRuntimeQueries(work)`, from
+  the same module, records what the app's own `runtime.database` sends while
+  `work` runs, and leaves out the test's own Knex. A server in another process
+  is out of its reach, so the route's guard boots it in the test.
+- Pages add a few queries; rows should add none. A path that pages nothing
+  (one read, one write) compares a short and a long history.
+- When the counts differ more than the pages explain, read `queries`: the
+  statement that repeats once per row is the one to batch. Judge the
+  comparison by what the path has to read; never tune a fixed ceiling until
+  it passes.
+- When it fails, fix the reads ([Lists read related rows in
+  batches](#lists-read-related-rows-in-batches), [Bounded access
+  checks](#bounded-access-checks)).
+
+Why: JSON:API reads add queries per page and relationship field, so comparing
+two sizes separates that cost from a read per row, where one fixed number
+cannot.
 
 ```js
 // good
-test("the invoice list reads each table once", async () => {
-  await seedInvoices(knex, { workspace, count: 300, linesEach: 5 });
-  let queries = 0;
-  const count = () => { queries += 1; };
-  knex.on("query", count);
-  try {
-    await invoices.listWithLines(workspace, { context });
-  } finally {
-    knex.off("query", count);
-  }
-  // A page of each table at a time; one read per invoice would add 300.
-  assert.ok(queries <= 40, `${queries} queries`);
+import { countQueries, countRuntimeQueries } from "@jskit-ai/database-runtime/server/testDatabases";
+
+test("the invoice list's queries follow its pages, not its invoices", async () => {
+  const listAt = async (count) => {
+    const workspace = await createWorkspace(knex);
+    await seedInvoices(knex, { workspace, count, linesEach: 5 });
+    return countQueries(knex, () => invoices.listWithLines(workspace, { context }));
+  };
+  const few = await listAt(10);
+  const many = await listAt(300);
+  // Thirty times the invoices may add pages; a read per invoice would add about 290 queries.
+  assert.ok(many.count <= few.count * 2,
+    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
+});
+
+// good: the same comparison for the route, through the server this test booted
+test("GET /api/invoices reads per page, not per invoice", async () => {
+  const app = await createServer({ runtimeEnv });
+  const listAt = async (count) => {
+    const workspace = await createWorkspace(knex);
+    await seedInvoices(knex, { workspace, count, linesEach: 5 });
+    return countRuntimeQueries(() => app.inject({ url: invoicesUrl(workspace), headers: signedIn }));
+  };
+  const few = await listAt(10);
+  const many = await listAt(300);
+  assert.ok(many.count <= few.count * 2,
+    `${few.count} queries for 10 invoices, ${many.count} for 300:\n${many.queries.join("\n")}`);
 });
 
-// bad: three invoices and no budget, so a read per invoice passes
+// bad: three invoices, nothing counted, so a read per invoice passes
 test("the invoice list has its lines", async () => {
   await seedInvoices(knex, { workspace, count: 3, linesEach: 1 });
   assert.equal((await invoices.listWithLines(workspace, { context })).length, 3);
 });
 ```
 
-### Time limits are not fixes
-
-**A slow test, suite, preparation or request is a defect to find, never a time
-limit to raise. Measure where the time goes, fix that cause, and keep the
-default limits.**
-
-- Raising `--test-timeout`, a test's `{ timeout }`, Playwright's `timeout`,
-  `test.setTimeout()` or an `expect` timeout, adding retries, or calling a
-  request in a loop until it answers hides the cause and lets it grow.
-- Read the preparation phases' durations and the query counts first; the
-  cause is usually a read per row, a history-sized policy, or a database
-  prepared by replaying migrations ([Test databases are prepared
-  once](#test-databases-are-prepared-once)).
-- A longer limit is right only for work that is long by nature, such as a
-  fixture of deliberate size, and the test names that work.
-- A time limit still bounds every run, so a hang ends; it is not a speed
-  setting.
-
-Why: a raised limit absorbs today's slowness and every later one, until a run
-takes hours and nobody knows which change made it slow.
+### Test files run in parallel
+
+**A test suite runs its files in parallel, as many at a time as the machine's
+test budget allows: never one file at a time, and never more than the machine
+can take. Node's test runner runs through `jskit test`; Playwright's `workers`
+and Vitest's `maxWorkers` come from `testConcurrency()`.**
+
+- The budget is `V64_TEST_CONCURRENCY` when it is a positive whole number (a
+  test runner that hands out slots exports it for each run), otherwise half of
+  the machine's CPUs, rounded down and at least 1: a 2-vCPU VPS runs one file
+  at a time, an 8-thread machine four.
+- `jskit test` (from `@jskit-ai/jskit-catalog`) passes its arguments to
+  `node --test` and sets `--test-concurrency` to the budget.
+  `testConcurrency()` from `@jskit-ai/jskit-catalog/test-budget` returns the
+  same number for a config.
+- No script passes a fixed concurrency or worker count. `jskit check` fails a
+  package script that runs `node --test` directly or passes one, and a
+  Playwright or Vitest config those scripts use whose workers do not come from
+  `testConcurrency()` ([test-run rules](#test-run-rules)).
+- Each file isolates what it shares: a port the system picks (`listen(0)`), a
+  directory from `mkdtemp`, its own database or schema with a name no other
+  file uses, its own Vite `cacheDir` for each dev server it starts (Vite
+  replaces a shared dependency cache under servers still reading it), and no
+  writes into the source tree. Files that collide are isolated, never
+  serialised. A database test file gets its own copy of `TEST_DB_NAME` from
+  `jskit test --databases`
+  ([integration test databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)).
+- An application's `playwright.config.mjs` is
+  `defineConfig(browserTestConfig({ testDir: "./tests/e2e" }))` from
+  `@jskit-ai/jskit-catalog/browser-tests`. It builds the production frontend
+  once (reused while its sources are unchanged) and gives each worker its own
+  server, port and, through its `prepare` module, its own seeded database; a
+  spec file's tests run in order in one worker. With `PLAYWRIGHT_BASE_URL`, the
+  tests use that managed target as its host serves it. Every run is bounded by
+  a `globalTimeout` (20 minutes, or the suite's own measured bound) and ends
+  with its 10 slowest tests. With a `signIn` module, each worker's server is
+  signed in once and every test of that worker starts signed in, instead of
+  each test signing in. `jskit check` fails a webServer that runs the development server
+  (`npm run develop`, `vite`), one webServer shared by every worker, and a
+  config without a `globalTimeout`.
+- A file that truly cannot run beside others, because it holds a resource of
+  the whole machine, says why on its first line,
+  `// jskit-test: alone - <reason>`. `jskit test` runs it after the others,
+  one such file at a time, and fails on a marker without a reason or below the
+  first line.
+- `jskit test` ends with its 10 slowest test files and tests, records each
+  file's time in `node_modules/.cache/jskit-test/file-times.json`, and fails
+  when a file takes more than 10 minutes or the whole command more than 45:
+  bounds only a clearly broken suite reaches, such as a file waiting out its
+  timeouts. A suite whose measured work needs more sets `runMs`, `fileMs` or a
+  file's own bound in `test-time-bounds.json`, with the measurement in the
+  commit that raises it; a file that got slow is fixed instead. A file still
+  running at twice its bound, or sooner at ten times the time it last finished
+  in (at least two minutes), is stopped and fails the run by name, so the other
+  files still finish and report: look for what it leaves open (a server, child
+  process, timer or socket) or a test without a timeout. A file with its own
+  bound is stopped at twice that bound.
+
+Why: `jskit test` and `testConcurrency()` read one budget, so every runner
+uses the machine without starving the other runs on it.
 
 ```js
-// good: the slow step was found and fixed, so the default limit holds
-test("delivers a batch of notices", async () => {
-  await deliveries.processBatch(workspace, { context });
-});
+// good: package.json "test": "jskit test", and playwright.config.mjs
+import { browserTestConfig } from "@jskit-ai/jskit-catalog/browser-tests";
 
-// bad
-test("delivers a batch of notices", { timeout: 600_000 }, async () => {
-  await deliveries.processBatch(workspace, { context });
-});
+export default defineConfig(browserTestConfig({ testDir: "./tests/e2e" }));
+
+// bad: "test": "node --test --test-concurrency=1", and
+export default defineConfig({ workers: 1, webServer: { command: "npm run develop" } });
 ```
 
 ### Test databases are prepared once
 
-**A test run prepares each database once, from a stored snapshot of its
-schema, migration ledger and seed rows checked by a digest of their sources,
-and never replays the whole migration history inside the run.**
+**A test run prepares each database once and restores it from a stored
+snapshot of the schema and the rows the migrations write, migration ledger
+included, checked by a digest of the migrations.**
 
-- The snapshot is rebuilt only when the digest of the migration and seed
-  sources changes, once and outside the timed tests; every disposable
+- The snapshot is rebuilt only when the digest of the migrations' names and
+  contents changes, once and outside the timed tests; every disposable
   database, and every database a test migrated up or down, is restored from
-  it.
+  it. A browser run's fixture seed runs after each restore.
 - The full migration history runs once, in its own fresh-schema check
   ([database verification](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#verification)).
-- The harness reports each preparation phase and its duration, and the suite
-  has a time budget, so slow preparation shows instead of hiding inside the
+- The harness reports each preparation phase and its duration, and those
+  durations are read, so slow preparation shows instead of hiding inside the
   next test that waits for it.
 - The database layer guide's [integration test
   databases](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#integration-test-databases)
   gives the snapshot's contents per engine.
 
-Why: the migration history only grows, so a run that replays it whenever a
-schema changed gets slower with every migration the application adds.
+Why: an application's migrations include those of every installed package, so
+replaying them costs more with each package as well as each migration.
 
 ```js
-// good: the application's test support restores the snapshot its digest names
-before(async () => restoreTestDatabase(knex, await testDatabaseSnapshot()));
+// good: package.json "test": "jskit test --databases"; each file gets a restored copy of TEST_DB_NAME
+const { databases } = await prepareTestDatabases({ knexConfig, environment: process.env, count: workers, seed });
 
 // bad: every file replays every migration
 before(() => knex.migrate.latest());
@@ -1125,6 +1206,10 @@ before(() => knex.migrate.latest());
 code: server, shared, client (`.vue` and `.js`) and scripts. One concern per
 factory.**
 
+- The limit is an outer bound, not a size to aim for: a file near it usually
+  holds more than one concern. Split it by concern; never trim lines or join
+  statements to fit.
+
 Why: a reader holds one concern at a time; a 2,000-line closure holds ten.
 
 ```text
@@ -1224,8 +1309,9 @@ Why: a comment that narrates history is wrong the day after it is written.
 ### Running the checks
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
-verify` runs `jskit check` (the package graph), lint, the tests and the
-build. The foundations' `eslint.config.mjs` already holds a new
+verify` runs `jskit check` (the package graph, navigation and [test
+runs](#test-run-rules)), lint, the tests and the build. The foundations'
+`eslint.config.mjs` already holds a new
 application's code to every check:
 
 ```js
@@ -1297,6 +1383,22 @@ Every finding ends with a link to the section of this page that explains it.
 | `jskit/allow-comment-form` | a `readable-check: allow` reason without a prefix from the table below, or one that cites tests or the state of a project | [Exceptions](#exceptions) |
 | `max-lines`, `max-lines-per-function` | files over 750 lines, functions over 600 | [Size limits](#size-limits) |
 
+### Test-run rules
+
+`jskit check` reports these in every package script, and in the Playwright
+and Vitest configs those scripts use. No comment excuses them; a test file
+that must run alone says so on its own first line instead.
+
+| Rule | Reports | Section |
+| --- | --- | --- |
+| `test/node-test` | a script that runs `node --test` directly instead of `jskit test` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/fixed-concurrency` | `--test-concurrency` in a script, or a script that pins `V64_TEST_CONCURRENCY` or `PLAYWRIGHT_WORKERS` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-workers` | `--workers` or `-j` passed to `playwright test`, its config without `workers: testConcurrency()` or `browserTestConfig()`, or with `workers` set over `browserTestConfig()`'s | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-dev-server` | a Playwright webServer command that runs the development server (`npm run develop`, `npm run dev`, `bin/develop.js`, `vite`, `vite dev`) | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-isolation` | a Playwright webServer every worker shares, without `browserTestConfig()` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/playwright-global-timeout` | a Playwright config without a `globalTimeout` (or `browserTestConfig()`), or with `globalTimeout: 0` | [Test files run in parallel](#test-files-run-in-parallel) |
+| `test/vitest-workers` | `--maxWorkers`, `--minWorkers` or `--no-file-parallelism` passed to Vitest, or its config without `maxWorkers: testConcurrency()` or with `fileParallelism: false` | [Test files run in parallel](#test-files-run-in-parallel) |
+
 The rules see shapes, not intent. Feature files, owned state beyond
 registries, shutdown, loggers, shared action fields, strict inputs, the action
 policy, request context, validated input, one reader per fact, routes,

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

@@ -36,7 +36,9 @@ Cancel, Close, and a wizard's Previous step; keep existing unsaved-change
 guards.
 
 `createShellRouter()` owns scroll position (`shell/application-shell`
-pattern); never reset scroll in page components.
+pattern); never reset scroll in page components. An app's own scroll behaviour
+is its `scrollBehavior` option, never a `createRouter` wrapper's (that throws);
+a hash target opens below its `scroll-margin-top`.
 
 ## Application-owned files
 

package/guide/agent/index.md

@@ -35,6 +35,9 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 - [Material 3](/guide/framework/material-3)
 - [UI pass](/guide/framework/ui-pass): make a task's changes, a section or the
   whole app exact Material 3
+- [Sanity checks](/guide/framework/sanity-checks): JSKIT's own pitfalls, and
+  the JSKIT calls that check data access, tests, a refactor, a screen or a
+  deployment before calling it done
 - [Translating a JSKIT app](/guide/framework/translation)
 - [Complete source pattern library](/patterns/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.279",
+  "version": "0.1.281",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [
@@ -10,7 +10,7 @@
     "skills"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/*.test.js"
+    "test": "jskit test test/*.test.js"
   },
   "engines": {
     "node": "^22.13.0 || ^24.0.0 || ^26.0.0"

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

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

package/patterns/minimal-foundation/PATTERN.md

@@ -18,8 +18,12 @@ tests, browser tests, and the normal build entrypoints.
 
 The example is a concrete application named `reading-room`. Copy the useful
 files into the project root, rename the application in normal source and
-package metadata, and then edit the product-facing page. The files become
-ordinary application source immediately.
+package metadata, and then edit the product-facing page. The name is spelt in
+`package.json`, `app.json` and `index.html`'s `<title>` (the app's name, which
+the shell's messages use), and, once the app adds sign-in, in the
+`auth/auth-surface` pattern's `src/components/AppBrand.vue` (the brand on the
+sign-in screens); rename them together. The files become ordinary application
+source immediately.
 
 ## Do not use when
 

package/patterns/minimal-foundation/example/AGENTS.md

@@ -29,11 +29,28 @@ Do not install an unrelated runtime package only to read documentation.
 Before adding or changing browser-test setup, read the browser verification
 guide at
 `https://mobily-enterprises.github.io/jskit-ai/guide/framework/ui-operations#browser-verification`.
-Routine tests reuse the isolated schema and prepare fixtures once per suite
-invocation. Keep `BROWSER_TEST_DB_NAME` distinct from disposable `TEST_DB_NAME`
-and prove that disposable cleanup preserves browser migrations. Require
-repeat-start regression proof; do not rebuild the database or production
-frontend for each focused browser check.
+`playwright.config.mjs` is `browserTestConfig()` from
+`@jskit-ai/jskit-catalog/browser-tests`: every Playwright worker gets its own
+server on the production build, its own port and, through the config's
+`prepare` module, its own copy of the browser database, restored from a schema
+snapshot and seeded. A local run never starts the development server; with
+`PLAYWRIGHT_BASE_URL`, the tests use that managed target as its host serves
+it. Keep `BROWSER_TEST_DB_NAME` distinct from disposable `TEST_DB_NAME`. The build and
+the snapshot are reused while their sources are unchanged; do not rebuild the
+database or production frontend for each focused browser check. Require
+repeat-start regression proof.
+
+Tests run in parallel within the machine's test budget: run node's test
+runner through `jskit test` (`npm test`), with `--databases` once the app has a
+database so each file running at once gets its own copy of `TEST_DB_NAME`,
+Playwright through `browserTestConfig()`, and take Vitest's `maxWorkers` from
+`testConcurrency()` of
+`@jskit-ai/jskit-catalog/test-budget`; never one file at a time or a fixed
+count. Isolate files that collide (their own port, temporary directory and
+database) instead of serialising them; a file that truly must run alone says
+why on its first line, `// jskit-test: alone - <reason>`. Plain `jskit check`
+fails anything else
+(`https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features#test-files-run-in-parallel`).
 
 Keep verification output small. Run the relevant cases together, save complete
 stdout/stderr to local artifacts, and preserve the exit status. Report counts,