@jskit-ai/agent-docs 0.1.265 → 0.1.267

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

@@ -486,7 +486,13 @@ fact cannot repair an older saved uncertain request or grant actor access.
 When `draftStorage` restores a page, known failed deliveries remain failed and
 accepted receipts remain accepted. Saved uncertain, pending or unrecognised
 delivery states stay uncertain with the exact original ID, payload and draft;
-closing a page during HTTP is not proof of rejection. Only the transient
+closing a page during HTTP is not proof of rejection. A draft message that was
+never dispatched (one deferred behind a working turn, for example) can no longer
+be sent once its conversation is released: its words return to the saved draft,
+ahead of anything typed after it, and no delivery is saved for it. A draft
+submission that settles undelivered without leaving a delivery record (refused
+before one was recorded) gives its words back to the composer, as a steer
+already did. Only the transient
 inspection flag is reset so **Retry** is reachable again. A matching
 canonical row marked `receipt: false` cannot settle delivery. Unknown inspection
 never retries; an actual accepted receipt is required to acknowledge the request.
@@ -3425,8 +3431,13 @@ at shutdown each native owner stops the processes this server runs, since none
 outlives the server that started it, and saved conversations are not reopened to
 be stopped. Claude stops its sessions together, leaves an idle chat untouched
 (nothing to stop, nothing written) and reports a session that cannot stop by ID
-in `failed` while the others still stop. It stops them even when its
-account-query cleanup fails; that failure is still the call's result. Once
+in `failed` while the others still stop. A turn still running when its process
+stops is not ended at shutdown: its saved record keeps the execution and the
+active turn, as after a crash, so the next server's recovery proves that exit,
+interrupts the turn and runs the host's interrupted checkpoint. A slow host
+checkpoint, such as a Git snapshot, never holds up shutdown. Claude stops its
+sessions even when its account-query cleanup fails; that failure is still the
+call's result. Once
 shutdown has invalidated the owner, a later session close only releases retained
 work. Failed cleanup can be retried after runtime closure. This is not a browser
 operation or a way to submit a caller-selected native owner.
@@ -3453,7 +3464,10 @@ owners. The host synchronously supplies `{ engine, native, context, sessions,
 options }` for operation `"reconcileSessions"`. The application retains its
 session inventory, authorization and storage codecs. Codex retains its original
 concurrent recovery and prune coordination; OpenCode retains per-session failure
-results and continues; Claude retains sequential, fail-fast restoration.
+results and continues; Claude retains sequential, fail-fast restoration. Like a
+session close, Claude reconciliation reopens only the saved custody an earlier
+server left, so a verified stop can retire it; idle saved conversations stay
+closed and unwritten.
 
 `runtime.unsubscribeNativeSessions({ context, sessions })` supplies startup
 subscription reset for Codex through operation `"unsubscribeSessions"` and a

package/guide/agent/app-setup/authentication.md

@@ -236,5 +236,13 @@ A managed host instead supplies authenticated state through
 file as a temporary secret, use relative URLs, and do not call the localhost
 login helper or start a duplicate server.
 
+The login state belongs to the host, which already fits it to the tested site.
+Pass `process.env.PLAYWRIGHT_STORAGE_STATE` unchanged to `use.storageState`:
+the config never reads, parses or edits that file or its `cookies` or
+`origins`. `jskit/playwright-login-unchanged` reports a config that does, and
+the host refuses to run its tests. If tests run signed out with the unchanged
+state, that is a host defect: report it with the evidence; do not work around
+it.
+
 Never commit provider secrets, copy auth repositories into the app, or add an
 installation questionnaire, mutation record, or setup receipt.

package/guide/agent/app-setup/multi-homing.md

@@ -198,9 +198,11 @@ const InviteMailerProvider = defineProvider({
 
 The optional `workspaces.invite-email-template` capability is a function that
 renders that inner message; it receives `{ email, inviteUrl, workspace, inviter,
-roleSid, roleLabel, expiresAt, locale, t }` (`roleLabel` only when configured).
-Provide it from an application feature, as for the mailer; without it the
-built-in template renders the message. Invitation links use `/invite/:token` unless
+roleSid, roleLabel, expiresAt, locale, timeZone, t }` (`roleLabel` only when
+configured; `locale` and `timeZone` are the recipient's saved settings, else
+`en` and `UTC`). Provide it from an application feature, as for the mailer;
+without it the built-in template renders the message, with the expiry written
+as a date in that locale and time zone. Invitation links use `/invite/:token` unless
 `workspaceInvitations.invitePath` names another path. The
 `workspaces/workspace-server` pattern includes an example renderer.
 

package/guide/agent/framework/translation.md

@@ -135,6 +135,9 @@ the English `message`:
   values and render from `jskit.errors.<code>`.
 - Validation errors keep `details.fieldErrors` (English) and add
   `details.fieldErrorCodes: { field: { code, params } }`.
+- A schema's field `messages` may give a message as a string or as
+  `{ code, message, params }` (see below); the coded form travels as that
+  field's code.
 - Where one code covers several different sentences (for example
   `connector_input_invalid`), the response also has `messageCode` and
   `messageParams` for the exact sentence.
@@ -164,6 +167,33 @@ throw new AppError(409, "That slug is taken.", { code: "app.project.slugTaken" }
 // en: { jskit: { app: { project: { slugTaken: "That slug is taken." } } } }
 ```
 
+### Field messages in schemas
+
+A field's `messages` in a resource or command schema map a validation keyword
+(or `default`) to the message shown when that check fails. A plain string is
+sent as written and is never translated. To make it translatable, give the
+coded form instead: the code, the English (exactly the catalog's English with
+the params filled in) and any params.
+
+```js
+const NAME_MESSAGES = Object.freeze({
+  required: { code: "app.project.nameRequired", message: "Name is required." },
+  maxLength: { code: "app.project.nameTooLong", message: "Use at most 80 characters.", params: { max: 80 } }
+});
+
+const schema = {
+  name: { type: "string", required: true, maxLength: 80, messages: NAME_MESSAGES }
+};
+// en: { jskit: { app: { project: {
+//   nameRequired: "Name is required.", nameTooLong: "Use at most {max} characters." } } } }
+```
+
+The server still sends the English in `details.fieldErrors` and adds the code
+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.
+
 ## Placement labels
 
 A placement `label` or `title` may be a message key, `{ key, fallback, params }`
@@ -186,12 +216,21 @@ App code can use the same helpers from `useJskitText()`: `formatDate`,
 
 ## Emails
 
-The workspace invitation email is rendered in the recipient's saved
-`user_settings.locale` when the recipient already has an account, and in English
-otherwise. The server reads the same `src/locales/<code>/jskit.json` files the
-client uses, so translating `jskit.workspaces.inviteEmail.*` there translates
-the email too. It looks for the exact locale (`it-IT`), then the language
-(`it`), then English. The app's invite mailer also receives the chosen `locale`.
+The server reads the same `src/locales/<code>/jskit.json` files the client
+uses, so translating a JSKIT email's keys there translates the email too. It
+looks for the exact locale (`it-IT`), then the language (`it`), then English.
+
+- The workspace invitation email (`jskit.workspaces.inviteEmail.*`) is rendered
+  in the recipient's saved `user_settings.locale` when the recipient already
+  has an account, and in English otherwise. Its expiry date is written with
+  `Intl` in that locale and the recipient's saved time zone (UTC otherwise).
+  The app's invite mailer also receives the chosen `locale`.
+- JSKIT's accounts hub (`@jskit-ai/oidc-issuer-core`) sends the account
+  confirmation, password recovery, Google link and test emails itself, from
+  `jskit.accounts.*`. Hub accounts keep no saved language, so each email
+  follows the request that sent it: the app's `ui_locales`, then the browser's
+  `Accept-Language`, then English. The hub reads the hub project's
+  `src/locales/<code>/jskit.json`; its README has the details.
 
 Server code that renders JSKIT-style messages itself uses the same lookup:
 
@@ -202,9 +241,10 @@ const i18n = createServerI18n({ appRoot, catalogs: [english] });
 i18n.t("it-IT", "jskit.workspaces.inviteEmail.subject", { workspace: "Acme" });
 ```
 
-Password-reset emails are sent by the app's own recovery sender (local
-accounts) or by the identity provider (Supabase, OIDC), so their language is
-the app's or the provider's choice.
+An app that signs in through JSKIT's accounts hub gets its password-reset
+email from the hub, translated as above. With another identity provider
+(Supabase, a third-party OIDC issuer) the provider sends it, so its language is
+the provider's choice.
 
 ## What the app translates itself
 
@@ -223,6 +263,12 @@ JSKIT's catalogs cover JSKIT's own code. These texts belong to the app:
 
 Each JSKIT package with a catalog has a test that compiles every message with
 vue-i18n, requires every key and dotted code its source uses to exist, rejects
-unused keys and refuses a key another package already defines. ESLint's
+unused keys and refuses a key another package already defines. It also requires
+an undotted code sent with fixed English to have its `jskit.errors.<code>`
+entry (or a `messageCode`), and a literal `{ code, message }` to send its
+catalog's English. A browser test exports a pseudo-locale with
+`jskit i18n export`, switches a fixture app to it, and fails on any English left
+on the sign-in, registration, password reset, sign-out, profile menu, account
+settings and error screens. ESLint's
 `@intlify/vue-i18n/no-raw-text` rule rejects untranslated template text in JSKIT
 client code.

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

@@ -26,7 +26,7 @@ template or relative string raw to Vue Router `to`.
 ## Back navigation
 
 Check every page for a visible Back button that returns to the previous page.
-Omit it only when returning makes no product sense, such as the app's root
+Omit it only when returning makes no product sense, such as the root
 landing page or a completed flow that must not reopen an expired step. State
 the reason in the implementation or review result; a drawer link is not Back.
 
@@ -70,7 +70,6 @@ hash, pattern receipt, or tool-owned source declaration.
 - Keep screens phone/task-first with drawer-independent primary actions.
 - Use direct surfaces instead of needless nested cards.
 - Render all meaningful loading, empty, error, permission, and retry states.
-- Follow the Material 3 contract for targets, loading and failure feedback.
 - Extend shared CRUD screens through public slots and composables.
 - Keep row actions and filters near the screen unless the framework owns them.
 - Import neutral request and CRUD UI APIs from `@jskit-ai/http-web`. Install
@@ -87,25 +86,25 @@ when another navigation affordance remains.
 The drawer omits the app bar's surface label. Open and rail icons share a
 centreline. It uses a 12px outer item inset; `navigationItemSpacing` controls
 icon/label and label/end gaps. The normal 80px rail centres 48px targets;
-`railWidth` and `drawerWidth` are public density/width controls. Do not override
-the shell's private implementation CSS.
-
-Restyle shell chrome only through the `--shell-*` tokens in the
-`shell/application-shell` pattern.
+`railWidth` and `drawerWidth` are public density/width controls. Restyle shell
+chrome only through the `--shell-*` tokens in the `shell/application-shell`
+pattern, never its private CSS.
 
 ## Browser verification
 
 Exercise user-facing changes with Playwright at compact, medium, and expanded
 widths. Check overflow, clipped text, duplicate navigation, route placement,
 actions, skeleton replacement, error feedback, and target sizes. Use relative
-URLs. When `PLAYWRIGHT_BASE_URL` is provided, start no duplicate server.
-For Back, enter the same page from two different origins and verify each
-returns to its own origin with context intact. Also check direct entry, reload,
-browser back/forward, fixed-destination exceptions, and any unsaved-change guard.
+URLs. With `PLAYWRIGHT_BASE_URL` set, start no duplicate server. For Back,
+enter the same page from two origins and verify each returns to its own origin
+with context intact. Also check direct entry, reload, browser back/forward,
+fixed-destination exceptions, and any unsaved-change guard.
 
 A managed host owns its browser and may provide
 `PLAYWRIGHT_STORAGE_STATE`; never print or commit that value, bypass it,
-or install another browser. For explicitly enabled direct-local auth, use
+or install another browser. If tests run signed out despite that state, report
+the host defect with evidence and stop; never rewrite its cookies or add a login.
+For explicitly enabled direct-local auth, use
 `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; never expose
 the exchange secret to browser code, URLs, or client environment.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.265",
+  "version": "0.1.267",
   "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.2.5",
+    "@jskit-ai/kernel": "0.2.6",
     "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.2.5",
+    "@jskit-ai/kernel": "0.2.6",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "pino": "^10.3.1",
@@ -43,13 +43,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.5",
+    "@jskit-ai/http-runtime": "0.2.6",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.244",
-    "@jskit-ai/jskit-catalog": "0.2.17",
+    "@jskit-ai/config-eslint": "0.1.245",
+    "@jskit-ai/jskit-catalog": "0.2.19",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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.2.5",
+    "@jskit-ai/kernel": "0.2.6",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "pino": "^10.3.1",
@@ -43,15 +43,15 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.5",
+    "@jskit-ai/http-runtime": "0.2.6",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.2.6",
+    "@jskit-ai/shell-web": "0.2.7",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.244",
-    "@jskit-ai/jskit-catalog": "0.2.17",
+    "@jskit-ai/config-eslint": "0.1.245",
+    "@jskit-ai/jskit-catalog": "0.2.19",
     "@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.2.5"
+    "@jskit-ai/kernel": "0.2.6"
   },
   "jskit": {
     "kind": "runtime",