@jskit-ai/agent-docs 0.1.242 → 0.1.244

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

@@ -56,8 +56,10 @@ admission; Claude's `duplicate-checked`, `native-history-read`, `process-ready`,
 `prompt-rendered`, `metadata-ready`, `receipt-written` and `state-active`; and
 `admission-authorized` and `turn-located` before `accepted`. A bound host's
 `prepareInput(input, context, { deliveryTiming })` and Claude's
-`preparation.message(..., { deliveryTiming })` receive the same observer and may
-mark `git-actor` and `genesis-rendered`. Unknown stage names are ignored.
+`preparation.message(..., { deliveryTiming })` receive the same observer. A host
+that marks stages of its own preparation declares them with
+`createConversationRuntime({ hostDeliveryStages: ["my-step"] })`; each name is
+lowercase letters and hyphens. Undeclared stage names are ignored.
 Native acknowledgement precedes the application's receipt write. Accepted delivery
 still waits for the existing durable receipt contract.
 

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

@@ -399,7 +399,9 @@ catalog, the runtime automatically exposes compact paged action search, exact
 one-action contract lookup, and contract-gated execution tools. Search returns
 at most 20 compact matches and never includes schemas. Tool arguments and
 results are byte-bounded; an oversized result returns a controlled error so it
-cannot overflow assistant transcript storage.
+cannot overflow assistant transcript storage. Empty tool arguments mean no
+input; any other arguments must be one JSON object, so truncated JSON, arrays
+and scalars return `assistant_tool_arguments_invalid` without running the action.
 
 The runtime tells the model that discovery tools are entry points into the
 authorized action catalog. Before claiming a capability or dataset is missing,

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

@@ -40,9 +40,18 @@ new handshake establishes the current actor.
 
 When `auth.service.authenticateRequest()` is present, delivery reauthenticates
 each socket before sending and rechecks idle sockets every 30 seconds. Revoked,
-expired, or changed actors are disconnected. Workspace membership rooms are
-refreshed from the current membership repository. Authentication lookup errors
-fail closed.
+expired, or changed actors are disconnected. Authentication lookup errors fail
+closed.
+
+Packages that know which scopes an actor belongs to contribute them through
+`runtime.realtime.registerAudienceContributor({ id, resolveActorScopes })` during
+setup. `resolveActorScopes(actorId)` returns event scopes (`{ kind: "user", id }`,
+`{ kind: "workspace", id }` or `{ kind: "workspace_user", workspaceId, userId }`);
+realtime turns each into the same room an `event_scope` audience targets. Sockets
+join those rooms on connection and, on every revalidation, leave the contributed
+rooms the actor no longer belongs to; rooms joined by anything else are left
+alone. `@jskit-ai/workspaces-core` contributes the actor's active workspace
+memberships this way when realtime is installed.
 
 The authentication request includes parsed cookies, the `Host`, `Origin` and
 `X-Forwarded-Proto` headers when present, and the socket address and TLS state.

package/guide/agent/app-setup/database-layer.md

@@ -200,7 +200,7 @@ product CRUD behavior fixed.
   phases before commit share one repository transaction, and `execute` receives
   `standard(nextInput)` for retaining the normal framework write.
 - Named `actions` expose non-CRUD service methods through normal input,
-  permission, audit, event, and optional HTTP route contracts.
+  permission, event, and optional HTTP route contracts.
 
 Repositories own database access. Services and lifecycle hooks orchestrate
 repositories. External delivery belongs after commit; when it must be durable,

package/guide/agent/app-setup/existing-application-migration.md

@@ -297,13 +297,6 @@ ACL, and restrictive umask. Setup must fail if it cannot establish that
 contract. Do not make package installation, Git, agents, or preview startup run
 recursive ownership or mode repair afterward.
 
-For Vibe64-managed workspaces, the concrete contract is group `vibe64`,
-directory mode `2770`, access and inherited default group ACL `vibe64:rwx`, no
-access for other users, and process umask `0007`. The enabled human user and
-`v64d_<workspace>` identity both belong to the group. Other hosts may use
-different concrete identities, but they must provide the same creation-time
-guarantee.
-
 Do not conflate these identities:
 
 - The filesystem identity controls who may create and replace source files.

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

@@ -13,7 +13,7 @@ Adopt the foundation's accessible HTML skeleton, inline styles, Reload link and
 startup-error message; package updates do not rewrite existing app HTML. Follow
 its cold-browser proof at compact, medium and expanded widths: delay JavaScript,
 check loading feedback, then release it and check app mount, including production
-builds. Compression belongs to hosting, not Genesis.
+builds. Response compression belongs to hosting.
 
 ## Establish a new application
 

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

@@ -150,16 +150,15 @@ need cross-owner denial tests.
 `useCrudAddEditScreen()` accepts `saveSuccess` at the top level. After saving,
 the default behaviour invalidates `saveSuccess.invalidateQueryKey`, navigates
 to a configured record-view URL when one resolves, and otherwise falls back to
-the list URL. For a create-and-list app, use `navigateToView: false` and the
-configured `listUrlTemplate`, as in the public example above. The list URL may
-also come from `addEditOptions.listUrlTemplate`.
+the list URL. For a create-and-list app, use `navigateToView: false` and
+`saveSuccess.listUrlTemplate`, the only list URL save navigation reads, as in the
+public example above.
 
 To keep the saved form open, set both `saveSuccess.navigateToView` and
 `saveSuccess.navigateToList` to `false`. `addEditOptions.onSaveSuccess` replaces
 the default success handling, including query invalidation and navigation;
 reserve it for custom success behaviour. Returning to the list needs only the
-documented `saveSuccess` options, not a custom router callback or inspection of
-the shared form implementation.
+`saveSuccess` options, not a router callback.
 
 ## Browser routes and responsive lists
 
@@ -307,17 +306,18 @@ this raw test encoding into page code.
 Deletion requires an explicit shared `DELETE` operation and confirmation
 decision. Use `CrudDeleteAction` and `useCrudDeleteAction()` through the view
 actions slot; do not rebuild their confirmation, request, invalidation, and
-navigation flow.
+navigation flow. After a delete it returns to the list before invalidating the
+resource's queries, so the deleted record never refetches as "Record not found."
 
 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.
+behavior. An explicit `client` override receives the same request options.
+Server authorization is unchanged.
 
 For custom form actions, see
-[record form actions](https://mobily-enterprises.github.io/jskit-ai/guide/framework/crud-form-actions).
+[record form actions](./crud-form-actions.md).
 
 ## Strict temporal values
 

package/guide/agent/index.md

@@ -25,6 +25,7 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 
 - [Application operations](/guide/framework/application-operations)
 - [CRUD operations](/guide/framework/crud-operations)
+- [Record form actions](/guide/framework/crud-form-actions)
 - [UI operations](/guide/framework/ui-operations)
 - [Material 3](/guide/framework/material-3)
 - [Complete source pattern library](/patterns/)
@@ -34,6 +35,7 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 - [Mobile Capacitor](/guide/app-extras/mobile-capacitor)
 - [Realtime](/guide/app-extras/realtime)
 - [Assistant](/guide/app-extras/assistant)
+- [Embeddable assistant conversations](/guide/app-extras/assistant-conversation)
 - [Voice conversations](/guide/app-extras/assistant-voice)
 
 ## How to use the guide

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.242",
+  "version": "0.1.244",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [
     "guide",
     "patterns",
     "reference",
-    "skills",
-    "templates"
+    "skills"
   ],
   "scripts": {
     "test": "node --test --test-concurrency=1 test/*.test.js"

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

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

package/patterns/feature-package/example/booking-engine/src/server/actions.js

@@ -14,8 +14,6 @@ function createActions({ bookingEngine } = {}) {
       input: statusQueryInputValidator,
       output: null,
       idempotency: "none",
-      audit: { actionName: ACTION_GET_STATUS },
-      observability: {},
       async execute(input) {
         return bookingEngine.readStatus(input);
       }

package/patterns/feature-package/example/variations/AvailabilityEngineProvider.js

@@ -1,5 +1,5 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { emptyInputValidator } from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { createService } from "./orchestratorService.js";
 
 const AvailabilityEngineProvider = defineFeature({

package/patterns/feature-package/example/variations/InvoiceRollupProvider.js

@@ -1,5 +1,5 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { emptyInputValidator } from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { createRepository } from "./repository.js";
 
 const InvoiceRollupProvider = defineFeature({

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

@@ -12,6 +12,25 @@ Before implementation, read the narrow relevant source pattern completely. If
 its owner package is installed, prefer that version-matched package-owned copy.
 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.
+
+Keep verification output small. Run the relevant cases together, save complete
+stdout/stderr to local artifacts, and preserve the exit status. Report counts,
+duration, failed case names and artifact paths; read only actionable failure
+excerpts. Do not dump full JSON/TAP reports, passing assertions, request logs or
+traces into agent context. Wait on the existing run instead of restarting it or
+repeatedly printing unchanged output. Keep startup and cleanup errors visible.
+For browser evidence, use existing automated cases, targeted locators and
+meaningful visual checkpoints. Avoid a full DOM snapshot or screenshot after
+every action; retain the required viewport, identity and security checks.
+
 Pages never start with a page header, title block, welcome heading, or other
 standalone heading copy. Start with the useful content and actions. If the user
 wants a heading, they will ask for or add one.

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.245",
+    "@jskit-ai/kernel": "0.1.246",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,13 +42,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.243",
+    "@jskit-ai/http-runtime": "0.1.244",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.295",
+    "@jskit-ai/jskit-catalog": "0.1.297",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/server/lib/runtimeEnv.js

@@ -1,8 +1,6 @@
-import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
 import { surfaceRuntime } from "./surfaceRuntime.js";
 
-const require = createRequire(import.meta.url);
-
 function toPort(value, fallback = 3000) {
   const parsed = Number.parseInt(String(value || "").trim(), 10);
   if (Number.isInteger(parsed) && parsed > 0) {
@@ -17,14 +15,8 @@ function ensureRuntimeEnvLoaded() {
   if (envLoaded) {
     return;
   }
-  try {
-    const dotenvModule = require("dotenv");
-    const loadDotEnv = dotenvModule?.config;
-    if (typeof loadDotEnv === "function") {
-      loadDotEnv();
-    }
-  } catch {
-    // dotenv is optional in base-shell; bundles can add it when needed.
+  if (existsSync(".env")) {
+    process.loadEnvFile(".env");
   }
   envLoaded = true;
 }

package/patterns/minimal-foundation/example/src/main.js

@@ -35,8 +35,6 @@ const { router, fallbackRoute } = createShellRouter({
   surfaceMode,
   notFoundComponent: NotFoundView,
   guard: {
-    surfaceDefinitions: config.surfaceDefinitions,
-    defaultSurfaceId: config.surfaceDefaultId,
     webRootAllowed: config.webRootAllowed
   }
 });

package/patterns/shell-foundation/PATTERN.md

@@ -74,6 +74,10 @@ source files.
 `.gitignore` when copying it to an app. Managed preview identity belongs to the
 authentication surface pattern, not the shell foundation.
 
+The shell files are the `shell/application-shell` pattern's example from
+`@jskit-ai/shell-web`, and the remaining files are the minimal foundation's,
+byte for byte. Change those owners first and keep the copies identical.
+
 Read these together before adapting the shell:
 
 - `example/src/App.vue`
@@ -94,29 +98,16 @@ Do not preinstall capabilities solely because they appear in another app.
 
 ## Development warmup
 
-Keep development-server warmup limited to the selected application entry.
-Warming every page and component transforms and caches screens before they are
-visited, increasing startup work and memory as the application grows. Add a
-specific frequently used file only when a measured loading delay justifies it.
-Keep dependency optimization separate: reducing warmup does not require disabling
-the dependency scanner or JSKIT's installed-package optimization settings.
-The bootstrap plugin scans local client entries and their shared imports before
-page loading. Do not exclude local package roots from optimization: Vite already
-keeps their real paths as source, and exclusions hide their dependency imports.
-Keep the example's Vuetify component/directive includes because auto-imports are
-introduced after the initial scan.
+Keep the development-server warmup, dependency optimization, and Vuetify
+includes exactly as the
+[minimal foundation](../minimal-foundation/PATTERN.md) describes in its
+Development warmup section.
 
 ## Verification
 
-Keep the initial loading shell in `index.html`, with its critical inline styles
-and Reload link. It must not depend on JavaScript, external fonts, or framework
-components. Adapt its skeleton to the product without adding host branding.
-Vue replaces it on mount; the bootstrap failure handler retains an actionable
-error. A failed module download still leaves the static Reload link available.
-Preserve `tests/e2e/startup.spec.ts`: it holds JavaScript requests while proving
-visible loading feedback at three widths, then releases them and proves mounting.
-Run this check against the production build as part of the application's release
-verification, not only against Vite development mode.
+Keep the initial loading shell in `index.html` and preserve
+`tests/e2e/startup.spec.ts` as the minimal foundation's Verification section
+describes, including its production-build check.
 
 Install the declared packages once, run `npm run develop` for the live
 application, then run lint, server tests, client tests, the production build,

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

@@ -12,6 +12,25 @@ Before implementation, read the narrow relevant source pattern completely. If
 its owner package is installed, prefer that version-matched package-owned copy.
 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.
+
+Keep verification output small. Run the relevant cases together, save complete
+stdout/stderr to local artifacts, and preserve the exit status. Report counts,
+duration, failed case names and artifact paths; read only actionable failure
+excerpts. Do not dump full JSON/TAP reports, passing assertions, request logs or
+traces into agent context. Wait on the existing run instead of restarting it or
+repeatedly printing unchanged output. Keep startup and cleanup errors visible.
+For browser evidence, use existing automated cases, targeted locators and
+meaningful visual checkpoints. Avoid a full DOM snapshot or screenshot after
+every action; retain the required viewport, identity and security checks.
+
 Pages never start with a page header, title block, welcome heading, or other
 standalone heading copy. Start with the useful content and actions. If the user
 wants a heading, they will ask for or add one.

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.245",
+    "@jskit-ai/kernel": "0.1.246",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.243",
+    "@jskit-ai/http-runtime": "0.1.244",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.251",
+    "@jskit-ai/shell-web": "0.1.252",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.295",
+    "@jskit-ai/jskit-catalog": "0.1.297",
     "@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.245"
+    "@jskit-ai/kernel": "0.1.246"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/shell-foundation/example/server/lib/runtimeEnv.js

@@ -1,8 +1,6 @@
-import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
 import { surfaceRuntime } from "./surfaceRuntime.js";
 
-const require = createRequire(import.meta.url);
-
 function toPort(value, fallback = 3000) {
   const parsed = Number.parseInt(String(value || "").trim(), 10);
   if (Number.isInteger(parsed) && parsed > 0) {
@@ -17,14 +15,8 @@ function ensureRuntimeEnvLoaded() {
   if (envLoaded) {
     return;
   }
-  try {
-    const dotenvModule = require("dotenv");
-    const loadDotEnv = dotenvModule?.config;
-    if (typeof loadDotEnv === "function") {
-      loadDotEnv();
-    }
-  } catch {
-    // dotenv is optional in base-shell; bundles can add it when needed.
+  if (existsSync(".env")) {
+    process.loadEnvFile(".env");
   }
   envLoaded = true;
 }

package/patterns/shell-foundation/example/src/components/ShellLayout.vue

@@ -6,6 +6,7 @@ export default {
   name: "ShellLayout",
   inheritAttrs: false,
   setup(_, { attrs, slots }) {
+    // Keep drawerWidth, railWidth, navigationItemSpacing, and future shell props package-owned.
     return () => h(PackageShellLayout, attrs, slots);
   }
 };

package/patterns/shell-foundation/example/src/main.js

@@ -35,8 +35,6 @@ const { router, fallbackRoute } = createShellRouter({
   surfaceMode,
   notFoundComponent: NotFoundView,
   guard: {
-    surfaceDefinitions: config.surfaceDefinitions,
-    defaultSurfaceId: config.surfaceDefaultId,
     webRootAllowed: config.webRootAllowed
   }
 });

package/patterns/shell-foundation/example/src/pages/home/settings.vue

@@ -23,7 +23,7 @@ import { RouterView } from "vue-router";
 
 <style scoped>
 .settings-shell {
-  --settings-panel-padding: 1rem;
+  --settings-shell-panel-padding: 1rem;
 }
 
 .settings-shell__panel {
@@ -34,7 +34,7 @@ import { RouterView } from "vue-router";
   display: grid;
   gap: 1rem;
   grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
-  padding: var(--settings-panel-padding);
+  padding: var(--settings-shell-panel-padding);
 }
 
 .settings-shell__content {