@jskit-ai/agent-docs 0.1.194 → 0.1.196

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

@@ -0,0 +1,244 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-extras/assistant-voice.md`. Do not edit manually. -->
+
+# Voice conversations
+
+`@jskit-ai/assistant-voice` adds push-to-talk, hands-free conversation, captions,
+transcript review, streamed playback and interruption to an application's existing
+conversations. One controller and one modal live above the routed screens. The
+application keeps its agent, history, message admission and authorization.
+
+The optional `@jskit-ai/assistant-voice-sherpa` package supplies native speech
+recognition, synthesis and explicit model preparation. Installing the browser
+package does not install native inference or download models.
+
+## Application integration
+
+Install `@jskit-ai/assistant-voice` in a Vue 3/Vuetify application. Mount
+`VoiceConversationHost` once inside the root `v-app`, and create its controller
+in that root's setup scope:
+
+```js
+import { onScopeDispose } from "vue";
+import { createVoiceConversationController, VoiceConversationHost }
+  from "@jskit-ai/assistant-voice/client";
+
+const voice = createVoiceConversationController({
+  connectSpeech: binding => `/api/conversations/${encodeURIComponent(binding.id)}/voice`
+});
+onScopeDispose(() => { void voice.dispose(); });
+```
+
+```vue
+<VoiceConversationHost :controller="voice" />
+```
+
+For the ordinary setup, use the [standard Assistant integration](./assistant.md).
+`AssistantConversationClientElement` supplies the same retained `runtime` to its
+`composer-tools` slot. The five-chat example in
+`@jskit-ai/assistant-voice/examples/conversation` retains that runtime for voice,
+projects its canonical turns with `projectConversationVoiceState`, and forwards
+text and Stop through `runtime.send()` and `runtime.cancel()`. The application
+supplies the speech URL, target label and text-view navigation; it does not build
+another transcript, delivery ledger or realtime subscription.
+
+### Custom conversation binding
+
+Applications with an existing authorized conversation reader can instead supply
+this binding contract to the same voice controller:
+
+```js
+await voice.open({ conversation: {
+  id: conversationId,
+  label: "Planning",
+  get state() { return store.conversations[conversationId]; },
+  get available() { return store.canUse(conversationId); },
+  captureContext: () => ({ conversationId }),
+  submitText: (text, { messageId, context }) =>
+    store.send(context.conversationId, { text, messageId }),
+  cancelWork: () => store.stop(conversationId)
+} });
+```
+
+The store and its operations are application-owned. `state` exposes `messages`,
+an optional `streamingReply`, and `status: "working"` while the agent is running.
+Each message has a stable `id`, `role` and `text`. A streaming answer and its saved
+replacement use the same ID. Supply user and assistant content; exclude tool
+output, reasoning and private operational details.
+
+`submitText` resolves when the application's normal server operation accepts the
+message. Reject failures and deduplicate retries by `messageId` in that operation.
+Voice preserves the captured destination and message identity; it does not create
+another history or infer whether an uncertain server request was accepted.
+
+Optional `openText()` opens the application's text conversation. It adds Talk and
+Text controls at the top of the modal. Selecting Text calls that operation and
+minimizes voice while capture and playback retain their current state. An
+application can open this modal as its default conversation view; opening never
+starts the microphone.
+
+Optional synchronous `retain()` and `release()` keep a conversation reader alive
+outside its screen. A binding's `available` value must reflect access loss.
+Include the current identity scope in the binding ID when IDs can overlap between
+people; dispose the controller on identity replacement. Server authorization is
+still required for every message and speech connection.
+
+## Interaction ownership
+
+Opening voice shows its controls without acquiring the microphone. The single
+Talk button connects automatically: tap for hands-free, hold for push-to-talk,
+and release to send. Tap Pause to pause hands-free capture. Hands-free can listen
+while answers play. The browser
+requires microphone permission and a secure origin, including recognized localhost
+origins for development.
+
+Opening the same binding ID reveals the existing modal. Minimizing or changing
+the visible screen preserves its destination. Opening another target first
+releases the old audio. Unfinished words must be sent or explicitly discarded
+before switching. A send in progress cannot be discarded to switch targets.
+
+Stop speaking cancels playback and queued speech. Stop agent work calls the
+binding's separate `cancelWork` operation. `end()` releases voice after pending
+words are resolved; `dispose()` always releases it. Reconnection does not replay
+messages, resend captured audio or automatically restart the microphone.
+
+Bindings may supply `defaults.mode` (`push-to-talk` or `hands-free`),
+`defaults.reviewBeforeSend`, and `defaults.voiceId`. Recordings started through
+`startHeldRecording()` require review; the modal's push-to-talk gesture uses
+`reviewBeforeSend`. The Talk/Pause microphone icon and speaker toggle show their states. The
+Voice settings cog loads the service's installed voices without recording.
+Pause finalizes the current utterance before muting, including buffered audio,
+and applies the recording's review preference. Resume starts a fresh recording.
+The review panel stays hidden during automatic admission; failed admission keeps
+the words and message identity available for review and retry.
+The portrait and controls stay fixed while captions scroll. A voice selection affects the next reply; streamed
+phrases of a reply retain the original speaker. Voice does not change the agent's
+reasoning model.
+
+`ConversationDialog` is the shared Vue frame for voice and application Text views.
+It fixes header/tab geometry, uses full screen below 600 pixels, and switches
+without content or backdrop transitions. It accepts `title`, `mode`, `showModes`, `minimizable` and
+`closeLabel`; `update:modelValue`, `update:mode` and `minimize` report actions.
+The host's X calls `end({ discard: true })`; minus preserves capture/playback.
+Both `VoiceConversationHost` and `ConversationDialog` accept an optional
+`activator` DOM element. A click over that launcher while the dialog is open
+minimizes it; the backdrop cannot turn that gesture into an audio shutdown.
+An application can replace the host's default floating reopen control through
+the `reopen` slot and use `controller.reveal()` from its own header indicator.
+
+The host's `avatar` slot receives `state`, `mouthLevel`, `mouthPose`, `avatar` and
+`binding`. `VoiceAvatar` and `useVoiceAvatar` supply generic presentation; an
+application may provide artwork without acquiring audio ownership.
+
+## Authorized speech connection
+
+Register the WebSocket plugin on the application's Fastify server, then expose a
+proxy route through `@jskit-ai/assistant-voice/server`:
+
+```js
+registerVoiceProxyRoute(fastify, {
+  route: "/api/conversations/:id/voice",
+  proxyConfig: resolveVoiceProxyConfig({ endpoint, accessTokenFile }),
+  async authorize(request) {
+    await checkOrigin(request);
+    await requireConversationAccess(request.user, request.params.id);
+  }
+});
+```
+
+Import `registerVoiceProxyRoute` and `resolveVoiceProxyConfig` from that server
+entrypoint. The endpoint and protected token file are operator inputs. The
+application supplies the illustrated origin and conversation checks; authorization
+runs before connecting upstream. No service key or token belongs in browser code.
+A speech grant does not authorize access to a conversation or execution of tools.
+
+Register the WebSocket plugin before starting the supplied realtime provider.
+The existing realtime attachment hands only `/socket.io` WebSocket upgrades to
+Socket.IO, so Fastify does not close that connection as an unknown speech route.
+Other upgrades remain with their application routes and authorization. The
+application does not need a separate upgrade handler.
+
+`createVoiceDaemon({ engine, accessKey, ... })` supplies the bounded service.
+The engine owns recognition and asynchronous synthesis. A host may supply its
+own `authorize(token)` and `handleRequest(request, response)` grant policy.
+Principals contain `tenant` and optional `parentTenant`; connection limits apply
+to both. `revokeTenant(id)` terminates existing sessions and queued work. The
+host's authorizer must also reject subsequent use of a revoked grant.
+
+## Native service and configurable voices
+
+Install `@jskit-ai/assistant-voice-sherpa` where the service will run. Model
+preparation requires Bash, tar with bzip2, sha256sum, Node and curl unless the
+archives are cached. Models have separate upstream licenses and are not bundled
+in npm. Preparation verifies pinned archives and installed files.
+
+```sh
+npx jskit-assistant-voice prepare --models-root /srv/speech/models --pack cori
+npx jskit-assistant-voice verify --models-root /srv/speech/models
+npx jskit-assistant-voice serve --models-root /srv/speech/models --key-file /run/secrets/speech-key
+```
+
+The signing key is an operator-created random secret of at least 32 bytes in a
+protected file. `jskit-assistant-voice token --key-file PATH --tenant NAME` emits
+an application token; redirect it into a separate protected file. The standalone
+token command does not implement a revocation store. Service defaults are
+`127.0.0.1:3092`, `/v1/voice` and readiness at `/health`.
+
+The `cori` preparation preset supplies one English voice. `piper` adds Alba
+(female, Scottish English), Joe and Bryce (male, American English) and
+Northern English (male, British English), retaining
+Cori (female, British English) as the default. These are separate Piper medium
+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.
+`kokoro` supplies Heart, Bella,
+Emma, Michael, Adam, George and Daniel. All presets use the English streaming
+Zipformer recognizer. Operators can supply
+`prepare --sources-file FILE` for pinned model archives and `serve --config FILE`
+for native recognition/synthesis settings, voice IDs, labels and speaker IDs.
+`recognitionVocabulary` maps literal phrases to application spellings, for example
+`{ "acme labs": "Acme Labs" }`. It applies when normalizing uppercase recognition;
+mixed-case input remains intact. CLI hosts can supply the same option as a
+default, overridden by an explicit speech configuration vocabulary.
+A voice's optional `speed` sets its synthesis pace from `0.5` to `2`, default `1`.
+Multiple native models use a `synthesizers` map and a `modelId` on each voice;
+their output sample rates must match unless `outputSampleRate` configures a shared
+rate. The worker then uses Sherpa's resampler before sending audio.
+`kitten` provides Kitten Micro 0.8 Bella, Luna, Rosie and Kiki (female), and
+Jasper, Bruno, Hugo and Leo (male). All eight share one model. Bella uses
+`speed: 1.15`; the others use normal speed. Their upstream catalogue does not
+identify British or Australian accents.
+`piper-kitten` lists Kitten before the five Piper voices, defaults to Cori and
+normalizes output to 22,050 Hz. One synthesis model remains resident across
+engine changes. The settings cog lists installed voices.
+The package README documents the exact source manifest and configuration fields.
+Stop the service before replacing its prepared pack, verify it, then restart.
+
+Measure first-audio latency and sustained synthesis on the intended host. Voice
+quality, language support and CPU cost depend on the configured models. Browser
+echo cancellation and text filtering need physical microphone/speaker testing;
+generated audio cannot prove acoustic isolation. The recognizer's configurable
+onset RMS floor prevents silence from starting an utterance, but is not a
+speech-versus-noise classifier.
+
+The published package's `examples/conversation/` directory contains an independent
+five-conversation Vue/Fastify application using the supplied file storage and
+retained binding, plus a separately addressed headless task. Model credentials
+and an optional speech endpoint are explicit setup inputs. Use it to check
+installation, retained targets, interruption and recovery.
+
+### Application-owned voice preferences
+
+`VoiceConversationHost` has an optional `settings` slot for an application-owned
+selector. Persist the voice choice in your application, then supply its current
+value through reactive `binding.defaults.voiceId`. Changes apply to subsequent
+replies. An unavailable ID uses the server default without rewriting the saved
+choice; reconnecting can restore it if the voice returns. An empty string selects
+the server default. The built-in selector remains local to the voice session.
+
+`readVoiceCatalogue(proxyConfig)` from `/server` retrieves the daemon's authorized
+`GET /voices` metadata without reserving an audio connection. Expose it only
+through an application-authorized route; credentials stay on the server. The
+result contains `voices` (IDs, labels and optional languages) and `defaultVoice`,
+matching the WebSocket greeting. Listing voices does not synthesize or load
+additional voice models.

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

@@ -2,22 +2,137 @@
 
 # Assistant
 
-`@jskit-ai/assistant-runtime` supplies a reusable assistant runtime, client
-elements, actions, persistence, and settings behavior. The application decides
-where an assistant belongs and composes its pages directly.
+JSKIT provides one conversation runtime and a supplied browser integration.
+`@jskit-ai/assistant-core` owns conversation execution and storage contracts;
+`@jskit-ai/assistant-runtime` exposes that runtime through authorized HTTP
+operations, shared realtime subscriptions and a Vue/Vuetify conversation component.
+File storage requires no database, Knex or database migrations. File and
+application-owned adapters retain their own persisted-state upgrade policy.
+
+## The ordinary API
+
+The standard setup uses five entrypoints from three modules. Native engines use
+this same setup; they do not add engine-specific imports.
+
+| Entrypoint | Module | Use |
+| --- | --- | --- |
+| `createConversationRuntime` | `@jskit-ai/assistant-core/server/conversation` | Create the authorized conversation owner. Headless tasks call its handles directly. |
+| `createFileConversationStorage` | `@jskit-ai/assistant-core/server/conversation` | Use the supplied single-writer file store, or supply the application's transactional store. |
+| `registerFastifyConversations` | `@jskit-ai/assistant-runtime/server` | Host the supplied transport on plain Fastify. An existing JSKIT host instead supplies `assistant.conversations` to its discovered `AssistantFeature`. |
+| `AssistantConversationClientElement` | `@jskit-ai/assistant-runtime/client` | Render the standard conversation with its retained draft, delivery and subscription owner. |
+| `useAssistantConversation` | `@jskit-ai/assistant-runtime/client` | Optional custom layout or retained text/voice access to that same owner. The standard element already calls it. |
+
+Start with those entrypoints. [Optional UI primitives](./assistant-conversation.md#client-contract)
+serve custom presentation; [advanced host facilities](./assistant-conversation.md#advanced-host-facilities)
+serve an application that already owns execution, credential homes or native
+history preservation. [Testing entries](./assistant-conversation.md#testing-entrypoints)
+exercise isolated storage and native-host contracts. These are separate uses,
+not extra setup steps for an ordinary conversation.
+
+## Standard integration
+
+1. Create `createConversationRuntime` with your conversation storage, instructions,
+   selected engine/connections and application authorization. Initialize each
+   conversation with its own ID and server-owned configuration. The application
+   controls which authenticated actors may read or operate each conversation.
+2. Supply that runtime as the `assistant.conversations` capability on your JSKIT
+   host. Package discovery registers `AssistantFeature` once; it uses the host's
+   existing HTTP, action and realtime services. Multiple conversations share the
+   connection, with separate authorization, subscriptions and controls.
+3. Render `AssistantConversationClientElement` for each conversation. The supplied
+   binding handles its draft, delivery receipts, streaming, reconnect and controls.
+   Supply presentation props and any optional capabilities the application needs.
+
+```vue
+<script setup>
+import { AssistantConversationClientElement } from "@jskit-ai/assistant-runtime/client";
+
+defineProps({ conversationId: { type: String, required: true } });
+</script>
+
+<template>
+  <AssistantConversationClientElement :conversation-id="conversationId" />
+</template>
+```
+
+The current configured surface determines the endpoint and placement. An app with
+one surface can use `defineAssistantSurface("home")` from
+`@jskit-ai/assistant-runtime/shared` in its application configuration instead of
+writing both surface maps. This explicitly declares that surface; authentication
+and conversation access remain application policy. `surface-id`, `endpoint`,
+`hostSurfaceId` and `workspaceSlug` are explicit overrides for an existing host's
+mapping. An authenticated request supplies the actor; browser fields never grant
+access. Opening the same conversation in another view does not create another
+server runtime or transcript.
+
+The standard binding uses the host's authenticated placement identity and HTTP
+client. An application with its own bootstrap subject or request policy can call
+`configureAssistantConversations(app, { actorKey, request })` from the same client
+entry once, before mounting. `actorKey` may be a reactive value or getter; changing
+or clearing it retires the previous actor's browser state. Standard cards inherit
+those settings while retaining explicit per-card overrides. See
+[client defaults](./assistant-conversation.md#supplied-client-integration) for the
+complete example. This does not change server authentication or create another
+realtime connection.
+
+For a plain Fastify app, call `registerFastifyConversations(app, { runtime, config,
+authenticate, bootstrap, env })` once. This is configurable shorthand for that
+same hosting assembly. Runtime/storage selection, trusted authentication,
+application configuration and shutdown remain explicit; custom hosts retain the
+lower-level registration facilities. See the complete
+[server integration and Fastify example](./assistant-conversation.md#supplied-server-integration).
+
+Use the [supplied client binding](./assistant-conversation.md#supplied-client-integration)
+for custom layouts or retained text/voice readers. It produces the element's
+adapter; an ordinary application does not implement its own generic adapter,
+routes or reconnect loop. A lost acknowledgement offers delivery inspection;
+reconnect does not silently resend uncertain work.
+
+For an executable setup, use the five-chat example in
+`@jskit-ai/assistant-voice/examples/conversation`. It uses file storage, the same
+supplied integration and one shared realtime connection. Its separately addressed
+headless task calls the runtime directly. Speech is optional; model credentials,
+authentication and speech setup remain explicit application configuration.
+
+## Configuration and customization
+
+- [Runtime and storage](./assistant-conversation.md#application-conversation-operations):
+  configure an API or native engine and use file, memory or application-owned
+  storage. Preserve one transcript owner for each conversation.
+- [Optional controls](./assistant-conversation.md#optional-shared-capabilities):
+  enable attachments, model choices, suggestions, questions and goals only when
+  supported. Applications keep upload storage, model-selection policy and product
+  actions; unused adapter areas need no implementation.
+- [Application tools](./assistant-conversation.md#application-tools): supply actions
+  and tool policy to the runtime. The common runtime owns the inference/tool loop;
+  the application authorizes each action and owns its effects.
+- [Voice](./assistant-voice.md): add push-to-talk and hands-free interaction to the
+  same retained conversation binding. Mounting or closing a text view does not
+  change the active voice target.
+
+The operation and host-facility reference follows the standard setup in
+[Conversation integration](./assistant-conversation.md). Native engine internals
+are not required for ordinary application setup.
+
+## Optional database-backed surface
+
+The existing SQL integration is an optional storage and application surface over
+the same common runtime. It retains database conversation selection, settings,
+actions and its existing request-streaming contract. Choose it when those SQL
+contracts are required; custom or file storage uses the standard integration
+above. This section documents that existing surface's behavior and migration
+constraints, not a second engine/tool implementation.
 
 ```bash
 npm install @jskit-ai/assistant-runtime
 npm run db:migrate
 ```
 
-Use the `assistant/assistant-surface` pattern. There is no assistant generator.
-
-For an app-owned backend or custom conversation storage, use the
-[embeddable conversation element and backend contracts](./assistant-conversation.md).
-The package includes a standalone application template.
+These migration instructions apply only to an application selecting the database
+integration. Its `assistant/assistant-surface` pattern composes the SQL surface;
+there is no assistant generator.
 
-## Product decisions
+### Database surface decisions
 
 Choose:
 
@@ -31,18 +146,54 @@ The application selects an AI integration ID in server configuration. Credential
 come from that integration's authorized shared or per-user account. Existing
 environment-prefix configurations remain supported.
 
-## Composition
+### Database surface composition
 
 Use `AssistantSurfaceClientElement` and
 `AssistantSettingsClientElement` from `@jskit-ai/assistant-runtime/client`.
 Configure public surface behavior and server settings in ordinary app-owned
 config, then register routes and placements like any other feature.
 
+For an application-supplied `assistant.conversations` common runtime, use
+`AssistantConversationClientElement` or `useAssistantConversation` from that
+same client entry. This path shares the existing HTTP/action and realtime owners
+and accepts file/custom storage without database repositories or migrations.
+See [supplied client integration](./assistant-conversation.md#supplied-client-integration)
+for captured conversation identity, optional controls and retained readers.
+
 Workspace scope is valid only when both the runtime and its settings surface
 are workspace-aware. Requests must retain the selected workspace through the
 server action boundary.
 
-## AI integration: the short setup path
+### Existing SQL conversations
+
+The optional database integration uses the common conversation runtime for
+inference, cancellation and application tools. Its existing settings, actions,
+NDJSON routes, conversation IDs, message rows and request-claim table remain the
+integration boundary. A tool reservation is committed to its original
+`tool_call` row before execution; the matching `tool_result` row retains the
+verified result. No second transcript is stored in conversation metadata.
+
+The surface's bounded, client-selected history remains request context. It is
+authorized for attachments and sent to the API model without being inserted into
+saved conversation history. Existing environment clients and the surface's
+cached tool exclusions retain their existing owners.
+
+Before adopting historical SQL rows, the storage owner checks their turn and
+tool associations without rewriting them. Unambiguous history stays readable in
+place. If historical output has no clear authored owner, or a tool call has no
+confirmed result, Send fails with `assistant_history_inspection_required` and
+row IDs in the error details. Previous history remains available through
+**Conversations**. Use **Start new conversation** to continue separately, or ask
+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.
+
+New runtime metadata uses the existing JSON fields, so this ownership move adds
+no database schema migration. Stop old assistant requests before switching
+server versions; keep applying the package's existing migrations normally.
+
+### Database surface AI integration
 
 1. Configure an `ai` integration using JSKIT's existing integration editor or
    portable `integrations.json`. Its provider/model, account mode and credential
@@ -52,7 +203,9 @@ server action boundary.
    from `@jskit-ai/connectors-catalog/server/ai`. `authorize` derives the trusted
    `{ applicationId, subjectId }` from the authenticated request. Use the normal
    environment reference resolver for shared keys and your account resolver for
-   per-user keys. Never return credentials to the browser.
+   per-user keys. The resolved connection also supplies `modelLimits` from the
+   catalogue for native engines that need an explicit model definition. Never
+   return credentials to the browser.
 3. Select it in server config:
 
 ```js
@@ -121,7 +274,16 @@ event. It retains failed uploads and permits typing while uploads are pending.
 Supply the controller with an upload scope that changes with user, workspace and
 conversation ownership. The server must enforce those boundaries independently.
 
-## Action tools
+The supplied canonical client accepts `useAssistantAttachments()` and
+`useAssistantSuggestions()` results directly. It clears only captured attachment
+IDs after HTTP, canonical history or explicit **Check delivery** confirms
+acceptance; newer uploads remain in the composer. Its suggestion owner binds to
+the canonical draft and complete target identity, while the host supplies a
+separate authorized generator and its configuration. Selecting a suggestion
+edits the draft and never sends it. These controls reuse the same shared
+[attachment and suggestion contracts](./assistant-conversation.md#optional-shared-capabilities).
+
+### Database surface action tools
 
 The assistant reads automation-capable actions from `runtime.actions`. It keeps
 the typing user's actor, permissions, target surface, and workspace context,
@@ -274,12 +436,13 @@ the three discovery tools. Permission, surface, channel, actor, and trusted
 workspace enforcement remain unchanged. Other actions still require contract
 lookup before discovery-mode execution.
 
-## Conversation lifecycle
+### Database surface conversation lifecycle
 
 The client receives answer text incrementally and shows working status before
 text arrives. Tool calls produce timeline events. Internal reasoning tags and raw
 tool arguments do not become visible answer text. A tool/recovery round replaces
-its provisional answer; only the completed answer is persisted. Progress-only
+its provisional answer; completed answers occupy the existing chat rows.
+Common runtime commentary is retained separately from those chat rows. Progress-only
 responses such as “Let me query…” may appear provisionally while streaming but
 are retried internally and never stored or replayed as final chat history.
 
@@ -333,6 +496,11 @@ a request automatically: a tool may already have changed application data.
 This protects against duplicate execution; it cannot guarantee completion after
 a process crash. The browser does not automatically resubmit ambiguous work.
 
+An application action whose outcome cannot be verified stops inference and
+keeps its durable reservation. Inspect the action's target before requesting a
+new execution; ordinary model retry and failure recovery cannot turn an unknown
+outcome into permission to repeat the action.
+
 Request records contain the submitted text/history and the replay response.
 They survive conversation removal so an old request cannot become executable
 again, and are deleted when their actor is deleted. Application retention or
@@ -340,13 +508,14 @@ privacy jobs must account for this table and must not remove active request
 identities. Custom transports using only `assistant-core` still own equivalent
 server-side protection; the UI controller alone cannot prevent duplicate work.
 
-## Shared conversation UI
+### Database surface client behavior
 
 `AssistantSurfaceClientElement` connects `useAssistantRuntime` to
 `AssistantConversationElement`. There is one maintained conversation renderer
-and composer. Applications that own a separate conversation operation use the
-[embeddable element](./assistant-conversation.md) directly through their own
-adapter; they do not need the generic assistant's database or tool loop.
+and composer. Applications supplying a conversation runtime use
+`AssistantConversationClientElement` and its supplied binding, described above.
+A hand-written adapter is an advanced presentation integration, not a prerequisite
+for custom storage or native engines.
 
 The runtime owns the draft, requests, saved conversations, history selection,
 provider settings, authorization scope and action tools. Its adapter maps
@@ -428,7 +597,7 @@ classes or pass the retired renderer's `variant`, `features`, `ui`, or `copy`
 objects. `AssistantClientElement` and its Markdown/keyboard helpers have been
 removed; there is no forwarding alias.
 
-## Verification
+### Database surface verification
 
 Run migrations, load assistant and settings pages through normal navigation,
 test missing credentials without exposing values, exercise one successful and

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

@@ -26,6 +26,12 @@ generic “something changed” escape hatch.
 Client features register listeners through `@jskit-ai/realtime`. Keep query
 invalidation close to the resource that owns the query keys.
 
+`useRealtimeEvent()` follows its Vue effect scope. Ordinary component listeners
+detach when that component unmounts. A listener created inside an application-owned
+detached scope remains active after its original screen unmounts and detaches when
+that scope is stopped. Retain and release that scope with the resource's actual
+owners; a hidden screen alone must not dispose a conversation still used by voice.
+
 When the entire realtime surface is authenticated, the selected `auth.service`
 can expose `realtime.requireAuthentication: true`. The realtime server then
 rejects unauthenticated handshakes before a socket joins any broadcast room.

package/guide/agent/index.md

@@ -32,6 +32,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)
+- [Voice conversations](/guide/app-extras/assistant-voice)
 
 ## How to use the guide
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.194",
+  "version": "0.1.196",
   "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.222",
+    "@jskit-ai/kernel": "0.1.224",
     "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.222",
+    "@jskit-ai/kernel": "0.1.224",
     "@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.220",
+    "@jskit-ai/http-runtime": "0.1.222",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.219",
-    "@jskit-ai/jskit-catalog": "0.1.247",
+    "@jskit-ai/config-eslint": "0.1.221",
+    "@jskit-ai/jskit-catalog": "0.1.249",
     "@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.1.222",
+    "@jskit-ai/kernel": "0.1.224",
     "@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.220",
+    "@jskit-ai/http-runtime": "0.1.222",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.226",
+    "@jskit-ai/shell-web": "0.1.228",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.219",
-    "@jskit-ai/jskit-catalog": "0.1.247",
+    "@jskit-ai/config-eslint": "0.1.221",
+    "@jskit-ai/jskit-catalog": "0.1.249",
     "@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.222"
+    "@jskit-ai/kernel": "0.1.224"
   },
   "jskit": {
     "kind": "runtime",