@jskit-ai/agent-docs 0.1.207 → 0.1.208

package/guide/agent/app-extras/assistant-voice.md

@@ -175,7 +175,13 @@ committing or sending messages. An optional synchronous `transfer(text)` must
 recheck the host's empty typed draft, set it through its original setter, and
 return true; false leaves speech untouched. Taking an active partial uses the
 original capture cancellation and guarded hands-free restart, preserving the
-session and playback. Taking a pending review clears only that review. Hosts
+session and playback. Taking a pending review clears only that review. Once an
+interrupted review is resolved, stale partial words from its idle capture do not
+block a fresh Talk gesture or become a new request. If capture interrupts an
+endpoint commitment, only that recording's unfinished commitment is retired;
+its retained words stay available for explicit Send, Edit or Discard. Late finals
+and resets cannot admit or replace the retained review. Active capture, including
+transcription, and pending startup, review and delivery retain their guards. Hosts
 also gate these controls while their canonical delivery has uncertain admission.
 
 For custom compositions, its optional `toolsTarget` is a DOM element belonging
@@ -381,6 +387,15 @@ models; one synthesis worker retains only the selected model. Changing models
 releases the previous worker and its native caches before loading the next, while
 recognition and the connection stay running. The first reply after a change
 includes loading time. Extra choices require disk space, not resident model RAM.
+The native engine advertises a bounded 120-second first-audio allowance at each
+new phrase's acquired queue slot: its unchanged load and generation requests each
+have a 60-second deadline. The browser returns to its original 20-second progress
+watchdog on actual PCM and after chunk completion. This allowance does not change
+microphone controls, playback cancellation or the separate connection heartbeat.
+Other engines omit `synthesisTimeoutMs` and retain the original 20-second policy;
+optional segment metadata must be an integer above 20,000 and at most 120,000 ms.
+Only the current turn's advancing segment can arm it; duplicate or stale metadata
+and pongs cannot extend generation indefinitely.
 `kokoro` supplies Heart, Bella,
 Emma, Michael, Adam, George and Daniel. `kokoro-q8f16` offers all 28 English
 Kokoro voices using the exact pinned `model_q8f16.onnx` (86 MB). Its preparation

package/guide/agent/app-extras/assistant.md

@@ -188,6 +188,8 @@ the application operator to inspect the reported rows and any affected action
 target. Do not delete a request claim or infer that an action with no result did
 nothing. Repairs require the application's offline upgrade procedure and a
 database backup; requests and startup never backfill these rows.
+Retrying the same rejected message ID preserves that inspection code and its row
+IDs without running inference or actions again. A retry is not a history repair.
 
 New runtime metadata uses the existing JSON fields, so this ownership move adds
 no database schema migration. Stop old assistant requests before switching
@@ -487,6 +489,12 @@ message-ID key. The database arbitrates concurrent requests across server
 processes before provider or tool execution. A reused ID with a different request
 returns a conflict. An identical retry replays the recorded answer or failure
 without calling the provider or tools again, including after a process restart.
+Pre-stream `AppError` failures retain their public code and details in the same
+request receipt. `ACTION_PERMISSION_DENIED` details remain private, and arbitrary
+non-`AppError` diagnostics are not added to the receipt. Older failure receipts
+without these optional fields replay their original message and status; missing
+diagnostics are not invented or backfilled. No database schema upgrade is needed
+for these optional fields in the existing response JSON.
 
 The acceptance receipt is stored before execution; completion is stored before
 sending the final stream event. If a request is still running, or its process

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

@@ -43,6 +43,35 @@ their own exact versions in dependency declarations; do not replace them with
 The copied files immediately belong to the application. Do not add pattern
 receipts, generator provenance, completion ledgers, or hidden operation state.
 
+## Implement before investigating internals
+
+Use the relevant public API contract and one matching example to build the
+smallest working slice, then verify its observable result. When the documented
+contract answers the task, stop reading and implement it. Do not trace framework
+or dependency internals to confirm documented options, routing, package
+discovery, transport, or lifecycle behaviour before trying that API.
+
+Implementation source is for a concrete failure or an API question the guide
+and example cannot answer. Name that failure or question before investigating,
+inspect only the relevant owner, and return to implementation and verification
+as soon as it is resolved. Do not tour a dependency tree for confidence. This
+applies to all features and dependencies, not only CRUD screens.
+
+## Discover files before reading them
+
+Discover the file, then read it. Do not infer its location from a convention.
+Use paths identified in the current tree, installed metadata, or the relevant
+example. When inspecting an unfamiliar package, list its files with
+`rg --files <observed-package-directory>` and select the relevant paths from
+that inventory before reading or searching source. Do not try guessed source
+directories. An import subpath is an `exports` alias, not necessarily a physical
+path; resolve it through the installed `package.json#exports` or
+`import.meta.resolve()` when following an import.
+
+This applies to every package and task, including third-party dependencies.
+Use a documented option directly when it already answers the question; source
+inspection is a fallback for a concrete unresolved fact.
+
 ## Install and compose capabilities
 
 Install selected capabilities together at the exact versions in the matching

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

@@ -85,6 +85,15 @@ const bookResource = defineCrudResource({
         create: { required: true }
       }
     }
+  },
+  searchSchema: {
+    q: {
+      type: "string",
+      oneOf: ["title"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
   }
 });
 ```
@@ -170,6 +179,90 @@ When the same create action appears in more than one visible location, choose
 one visible action deliberately; do not relax the expected label to accept an
 unrelated fallback.
 
+## Browser tests verify validation and persistence
+
+Exercise rejected and accepted input through the same form. Check the rendered
+validation message and that rejection keeps the form open; then save an accepted
+value and prove it appears in the list after reloading. Use the resource's
+configured messages, the screen's `saveLabel`, and its actual browser routes.
+Do not infer an `aria-invalid` attribute from the fact that validation exists:
+the chosen field must actually implement that attribute contract before a test
+can assert it.
+
+For the public title-only Books variant above, using the pattern's
+`saveLabel: "Save book"`, default minimum-length message, and a root public
+surface:
+
+```ts
+await page.goto("/books");
+await page.getByRole("link", { name: "Add book", exact: true }).filter({ visible: true }).first().click();
+await expect(page).toHaveURL(/\/books\/new$/);
+await page.reload();
+const title = page.getByRole("textbox", { name: "Title", exact: true });
+const save = page.getByRole("button", { name: "Save book", exact: true });
+await title.fill("");
+await save.click();
+await expect(page.getByText("Length must be at least 1 characters.", { exact: true })).toBeVisible();
+await expect(page).toHaveURL(/\/books\/new$/);
+
+await title.fill("A saved book");
+await save.click();
+await expect(page).toHaveURL(/\/books$/);
+await expect(page.getByText("A saved book", { exact: true }).filter({ visible: true })).toBeVisible();
+await page.reload();
+await expect(page.getByText("A saved book", { exact: true }).filter({ visible: true })).toBeVisible();
+```
+
+For client-side routing, a click finishing does not prove the route has changed.
+Before reloading after a navigation control, wait for the destination with
+`await expect(page).toHaveURL(...)`, as above. Otherwise reload can reopen the
+origin page and a later form or Back locator waits on the wrong screen. Use the
+actual destination URL, including required context; do not add fixed sleeps or
+increase timeouts to hide this race. For a contextual Back check, wait for the
+form route, reload, click Back, and assert the original list URL. Test direct
+entry separately against the configured fallback.
+
+Keep the application's existing browser configuration and isolated fixtures.
+Adapt the route, labels and configured error message to that application's
+contract, and retain compact, medium and expanded layout coverage. Direct API
+checks additionally prove rejected input is not persisted.
+
+## Wire list search with the initial resource
+
+`useCrudListScreen()` enables query search and the shared list renders a Search
+box. When using that screen, configure `resource.searchSchema.q` with the
+searchable fields from the start, as in the title-only Books resource above.
+Showing a Search box alone does not implement storage filtering. Keep the
+mapping in the resource; do not add page-local filtering or duplicate request
+code. The full Books source example maps `q` to title, author and notes; narrow
+it when adapting the example to fewer fields.
+
+The browser page's route query and internal CRUD query use plain `q`. The
+JSON:API HTTP transport uses `filter[q]`. Shared CRUD clients encode and decode
+this automatically. Raw HTTP/API tests must send the transport key themselves:
+
+```ts
+const headers = { Accept: "application/vnd.api+json" };
+const matches = await request.get("/api/books", {
+  headers, params: { "filter[q]": "A saved book" }
+});
+expect(matches.status()).toBe(200);
+expect((await matches.json()).data.some(book => book.attributes.title === "A saved book")).toBe(true);
+
+const noMatches = await request.get("/api/books", {
+  headers, params: { "filter[q]": "no-matching-fixture-title" }
+});
+expect(noMatches.status()).toBe(200);
+expect((await noMatches.json()).data).toEqual([]);
+```
+
+Use controlled fixtures with a known matching and nonmatching value. A matching
+row alone does not prove search works: an unfiltered response also includes it.
+In the browser, fill Search, assert the expected visible rows and excluded rows,
+then clear it and assert the list returns. Verify route/reload behaviour when
+the screen synchronizes search to the route. Add these checks to the initial
+create/list flow rather than discovering an unwired control at final review.
+
 ## Direct API tests use JSON:API documents
 
 JSKIT's CRUD screens and HTTP client apply the resource's JSON:API transport
@@ -216,6 +309,13 @@ decision. Use `CrudDeleteAction` and `useCrudDeleteAction()` through the view
 actions slot; do not rebuild their confirmation, request, invalidation, and
 navigation flow.
 
+The delete action resolves its HTTP client from the resource's `apiAccess`, just
+like the list, view and form helpers. For `apiAccess: "public"`, DELETE requests
+skip session CSRF discovery; no `/api/session` endpoint or page-local client
+wiring is required. Authenticated resources retain the configured client's CSRF
+behavior. An explicit `client` override is supported and receives the same
+resource-aware public request options. This does not change server authorization.
+
 For custom form actions, see
 [record form actions](https://mobily-enterprises.github.io/jskit-ai/guide/framework/crud-form-actions).
 

package/package.json

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

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

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

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

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.235",
+    "@jskit-ai/kernel": "0.1.236",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,13 +42,13 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.233",
+    "@jskit-ai/http-runtime": "0.1.234",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.232",
-    "@jskit-ai/jskit-catalog": "0.1.260",
+    "@jskit-ai/config-eslint": "0.1.233",
+    "@jskit-ai/jskit-catalog": "0.1.261",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/server-search.md

@@ -26,6 +26,22 @@ The normal layer split is:
 2. `repository.js`: add internal-only filter keys such as visibility scope, or call `listFilterContract.toJsonRestQuery(query)` for structured filters
 3. provider/resource registration: merge backend filter behavior into JSON REST with `createJsonRestResourceScopeOptions(resource, { searchSchema })`
 
+### Shared list and HTTP transport
+
+`useCrudListScreen()` enables query-backed search. Configure
+`resource.searchSchema.q` when composing the initial resource so its visible
+Search control actually filters storage. Narrow the example's `oneOf` fields
+when adapting a resource; do not drop search while retaining the control.
+
+Names in this pattern's schemas and internal queries are plain keys such as
+`q` and `archived`. Public JSON:API HTTP queries encode them as `filter[q]`
+and `filter[archived]`. The browser page route may still use `?q=...`; it is
+not the API transport. Shared CRUD clients perform the conversion. Direct
+HTTP clients use, for example, `params: { "filter[q]": "Ada" }` against the
+actual scoped API URL. Standard CRUD query validators already accept `q`
+through this transport; only additional public filter keys need their own
+filter validator. Verify matching and nonmatching results plus clearing Search.
+
 ## Decision Rules
 
 Use `search: true` on a schema field when:

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

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.235",
+    "@jskit-ai/kernel": "0.1.236",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.233",
+    "@jskit-ai/http-runtime": "0.1.234",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.239",
+    "@jskit-ai/shell-web": "0.1.240",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.232",
-    "@jskit-ai/jskit-catalog": "0.1.260",
+    "@jskit-ai/config-eslint": "0.1.233",
+    "@jskit-ai/jskit-catalog": "0.1.261",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

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

package/patterns/ui-testing.md

@@ -18,6 +18,11 @@ Rules:
   app-owned. Do not duplicate base-URL, web-server, or storage-state logic in
   individual tests.
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
+- After clicking a client-side navigation control, wait for its destination
+  with `await expect(page).toHaveURL(...)` before reloading. Awaiting the click
+  alone does not wait for Vue Router to complete. Contextual Back tests must
+  reach the form before reload, then assert the original list URL; direct entry
+  checks the configured fallback separately. Do not replace this wait with sleeps.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
 - Vibe64 supplies an authenticated context through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
 - Do not install a browser when the environment provides a managed browser runner.
@@ -28,6 +33,14 @@ Rules:
   Keep the expected text and persistence assertion. If repeated create controls
   perform the same action, select one visible control deliberately rather than
   accepting a different label to make a test pass.
+- For CRUD validation, follow the generic CRUD guide's **Browser tests verify
+  validation and persistence** example: assert the visible configured error,
+  retained form, accepted save and reload persistence. Assert `aria-invalid`
+  only when the selected field implements that contract.
+- Include the shared list's Search control in the initial feature flow: prove
+  matching rows, excluded rows and clearing the query. Raw JSON:API requests
+  send `filter[q]`; page-route and internal queries use plain `q`. See the CRUD
+  guide's **Wire list search with the initial resource** example.
 
 ## Keep startup incremental