arcane-os 0.51.1 → 0.51.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.51.2
+
+- Forward caller-selected `temperature` through the focused TWiN Cloud
+  `fetchRequest` and the full AI TWiN fetch/stream paths, including their
+  built-in provider adapters. Preserve explicit `0`; omission or `undefined`
+  leaves the provider default in effect. The value remains request-local and
+  is retained by existing observers and retries. No clamp, saved preference,
+  output limit, native Ollama option mapping, or new dependency is introduced.
+  Complete messages, selected model, reasoning behavior, response content,
+  cancellation, other providers, and existing positional APIs stay unchanged.
+
 ## 0.51.1
 
 - Restore the published `node-http-server` MIME map in development and packaged

package/README.md

@@ -15,11 +15,12 @@
 
 `arcane-os` is the application SDK and command-line toolchain for Arcane OS. It
 supports two explicit workspace profiles: an external app repository uses the
-version-locked SDK runtime, while an integrated Arcane checkout uses its live
-`arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
+version-locked SDK runtime, while an integrated Arcane checkout consumes its
+selected SDK projection or an explicit live SDK source mount. Both profiles
+share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.51.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.51.2` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -73,19 +74,35 @@ Enabled browser delivery also mounts the shared, themed installation suggestion.
 It appears when the browser offers installation, includes Install and Close,
 and remembers dismissal for the tab session without interrupting page startup.
 
-That registry query is a maintainer action, not an application behavior. Apps
+Registry queries are maintainer actions. Apps
 never poll npm for SDK updates or replace their own SDK or synchronized runtime.
 The app repository's exact dependency and lockfile select the SDK; changing that
 selection is an explicit repository update. Tests and checks run only when the
 user expressly selects them, or when required for a selected release output.
 
+## Current capabilities
+
+| Build this | Start here |
+| --- | --- |
+| A standalone browser app with shared theme, components, source serving and PWA resources | [Beginner quick start](#beginner-quick-start), [CLI](docs/reference/cli.md), [PWA](docs/reference/pwa.md) |
+| Streaming or complete AI responses, structural tools and a model selected for one request | [AI runtime](docs/reference/runtime-modules.md#aijs), [TWiN Cloud](docs/reference/ai/twin-cloud.md) |
+| Stateless state-and-questions evaluation or image generation | [`fetchSystemOneRequest`](docs/reference/ai/twin-cloud.md#evaluate-caller-owned-state-with-system-one), [`generateImages`](docs/reference/ai/twin-cloud.md#generate-images-with-an-application-selected-model) |
+| Browser-local language models with an application-owned model catalog | [Browser-WASM AI](docs/reference/ai/browser-wasm.md) |
+| Local Whisper/Kokoro, native browser recognition and voices, or selected cloud speech | [Speech provider guide](docs/reference/ai/browser-speech.md) |
+| Editable live transcription, ordered speech playback and printed conversations | [Chat](docs/reference/runtime-components.md#chathtml), [SpeechPlayback](docs/reference/runtime-modules.md#speechplaybackjs) |
+| Complete saved conversations, request-only turns, document retrieval and stored Markdown images | [Chat sessions](docs/reference/runtime-modules.md#persistentaichatsessionjs), [document library](docs/reference/runtime-modules.md#dbopfsdocumentlibraryjs), [MarkdownMedia](docs/reference/runtime-modules.md#markdownmediajs) |
+| Windows, Linux or Android development output from the same app | [Native target matrix](docs/platform-targets.md) |
+
+Provider and platform availability are documented at each surface. Applications
+own model selection, credentials, prompts, saved data and product behavior.
+
 ## Beginner quick start
 
 Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.34.1 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@latest new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```
@@ -135,24 +152,26 @@ PWA and storage availability still depend on the browser's secure-context
 rules; see [HTTP development](docs/reference/cli.md#explicit-http-development).
 
 Open the URL printed by the server. The generated page owns its import map and
-Arcane theme; its application module is `apps/hello-speech/modules/App.js`.
-`arcane/AI` is a managed **browser import**, not an npm-exported Node inference
-module.
+Arcane theme; its application module is `modules/App.js` at the repository root.
+Root applications use managed `arcane-os/*` browser imports. Importing
+`arcane-os/ai` resolves the shared AI module; its browser lifecycle still
+requires the documented browser environment. For a stateless Node request,
+use `arcane-os/ai/twin-cloud`.
 
 For a first spoken sentence, copy the application-owned
 [`speech-selection.js` configuration from the speech quick start](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/browser-speech.md#quick-start-say-one-sentence)
 beside `App.js`, then use this module. That one configuration file defines the
 upstream runtime, model, dtype, and voice. This module creates the application's
 DBOPFS store; the SDK creates and manages its speech providers and Workers.
-The linked automatic/WebGPU-first selection uses `fp32` because
+The linked automatic NPU/GPU/CPU selection uses `fp32` because
 [Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage).
 Its `selectedDevice` status reports the loaded route, not speech correctness or
 audio quality.
 
 ```javascript
-import arcaneThemeReady from 'arcane/ThemeBootstrap';
-import AI, { AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL } from 'arcane/AI';
-import DBOPFS from 'arcane/DBOPFS';
+import arcaneThemeReady from 'arcane-os/modules/ThemeBootstrap.js';
+import AI, { AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL } from 'arcane-os/ai';
+import DBOPFS from 'arcane-os/modules/DBOPFS.js';
 import { speechSelection } from './speech-selection.js';
 
 await arcaneThemeReady;
@@ -204,7 +223,7 @@ If your app already has complete segments in an array, let the shared
 `SpeechPlayback` owner submit them as soon as they are available:
 
 ```javascript
-import SpeechPlayback from 'arcane/SpeechPlayback';
+import SpeechPlayback from 'arcane-os/speech-playback';
 
 const audio = document.body.appendChild(document.createElement('audio'));
 audio.controls = true;
@@ -239,7 +258,7 @@ the application or prove that a selected provider supports one:
 import {
   SPEECH_VOICE_ALIASES,
   SPEECH_VOICE_OPTIONS
-} from 'arcane/SpeechPlayback';
+} from 'arcane-os/speech-playback';
 
 console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}
 console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true
@@ -308,11 +327,13 @@ TWiN Cloud is the SDK's default remote language-model service, identified by
 `openai-gpt-oss-120b`. Supply the bearer credential through `ai.twinKey` or
 `globalThis.arcane.config.twinCloud.accessKey`. The established `ai.license`
 property remains available. Applications should present the service and
-credential as **TWiN Cloud** and **TWiN access key**. The TWiN key is used only
-for remote LLM chat. Audio stays
-on device: Whisper (`LOCAL_SPEACH` / `whisper-small`) owns transcription and
-Kokoro (`LOCAL_SPEACH` / `kokoro`) owns speech synthesis. Neither audio route
-uses the TWiN key, and neither requires a cloud audio key.
+credential as **TWiN Cloud** and **TWiN access key**. Explicit cloud speech,
+System One and image requests also use application-supplied credentials.
+The built-in local speech selections remain Whisper (`LOCAL_SPEACH` /
+`whisper-small`) for transcription and Kokoro (`LOCAL_SPEACH` / `kokoro`) for
+synthesis. Those local routes use no TWiN key. Applications may separately
+select native browser speech or TWiN Cloud TTS; browser-native services may
+process speech remotely.
 
 The built-in provider and default-model preference sentinel are both `TWIN`.
 Applications upgrading saved preference tuples must replace only uppercase
@@ -334,6 +355,12 @@ Cloud maps it to DigitalOcean Serverless Inference `reasoning_effort`; omitting
 it preserves the provider default. TWiN Cloud defaults to
 `openai-gpt-oss-120b`, and applications may explicitly select
 `openai-gpt-oss-20b` without changing streaming or structural-tool behavior.
+An explicit request `model` selects that call's model without changing saved
+preferences. The stateless `fetchRequest`, `fetchSystemOneRequest` and
+`generateImages` exports in `arcane-os/ai/twin-cloud` require a caller-selected
+model and return the complete documented provider result. They retain no chat
+history. See the [TWiN Cloud guide](docs/reference/ai/twin-cloud.md) for each
+request shape, diagnostic callbacks, cancellation and image-job behavior.
 
 ## Browser-local AI
 
@@ -387,8 +414,9 @@ Capability reports evaluate each
 app-supplied model as `compatible`, `incompatible`, or `unknown`; the app can
 render that result without the SDK inventing or filtering its catalog.
 
-`arcane-os/ai/browser-speech` exposes independent Whisper STT and Kokoro TTS
-provider factories. The package contains the plain-JavaScript provider and
+`arcane-os/ai/browser-speech` exposes independent Whisper STT, Kokoro TTS,
+native browser recognition, native browser synthesis and TWiN Cloud TTS
+provider factories. The local-model path contains the plain-JavaScript provider and
 Worker machinery, not speech runtimes, models, voices, or a CDN default. An app
 must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
@@ -403,6 +431,16 @@ requested and selected devices through execution status. A selected backend
 reports successful upstream loading, not physical accelerator use for every
 operation; model and hardware compatibility remain upstream.
 
+Native speech requires the browser's actual recognition or synthesis API.
+Voice discovery and preparation are silent; explicit playback owns completion,
+pause, resume, cancellation and release. `provider.setDefaultVoice(voiceURI|null)`
+changes future native preparations while preserving explicit choices and
+already prepared speech. `ai.prepareTTSPlayback(payload,signal)` returns a native
+playback descriptor or real Blob audio; `fetchTTS()` and durable `prepareTTS()` require real
+audio and report native audio-export unavailability. Cloud TTS queues complete
+jobs and preserves original-order playback. See the [speech guide](docs/reference/ai/browser-speech.md)
+for voice catalogs, recognition language and provider-specific limits.
+
 Applications that need faster spoken-response onset can configure the shared
 TTS stream without taking over synthesis or playback:
 
@@ -453,12 +491,14 @@ uses the same controller for automatic memory extraction.
 
 ## Install
 
-Create a new repository-shaped Arcane application with the exact stable SDK:
+Create a standalone Arcane application from the current stable SDK. The scaffold
+records the selected exact version:
 
 ```bash
-npx arcane-os@0.12.0 new my-app --path ./my-app --target portable --git
+npx arcane-os@latest new my-app --path ./my-app --target browser --git
 cd my-app
 npm install
+# Configure HTTPS as described above, then start source development.
 npm run dev
 ```
 
@@ -466,8 +506,8 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.12.0
-npm exec -- arcane init my-app --target portable
+npm install --save-exact arcane-os@latest
+npm exec -- arcane init my-app --target browser
 ```
 
 The npm package is named `arcane-os`. Its primary executable is `arcane`, and
@@ -482,7 +522,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.12.0` for the initial bootstrap because it names this npm
+Use `npx arcane-os@latest` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -498,11 +538,11 @@ tarball install in the app's package manifest and lock:
 # From the arcane-os-sdk checkout
 npm ci
 npm run pack:local
-node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
+node ./bin/arcane.mjs new local-app --path ../local-app --target browser --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.12.0.tgz
+npm install --save-exact "../arcane-os-sdk/arcane-os-<selected-version>.tgz"
 npm ci
 ```
 
@@ -511,7 +551,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.12.0` registry package and
+the local declaration with the selected exact registry version and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -622,16 +662,11 @@ Portable path validation rejects file/directory prefix conflicts,
 case-colliding prefix spellings, and Windows device aliases including
 superscript COM/LPT digits.
 
-The reusable `.github/workflows/release-app.yml` workflow
-builds one selected app in a `contents: read` job with no OIDC or attestation
-authority. An always-run fresh job downloads the uploaded artifact by immutable
-artifact id, checks out only the reusable workflow's selected SDK revision, uses
-supported Node 24, and checks the selected app id and complete inventory.
-When requested, a third job downloads that same artifact id, independently
-repeats those checks against the post-upload outputs, and alone receives narrow
-OIDC/attestation permissions. No package manager, dependency resolution, caller
-checkout, check, or adapter runs with that authority. An unattested uploaded
-artifact remains an ordinary build output.
+Use the public package and bundle commands for the selected app output.
+The checked-in reusable `release-app.yml` workflow still pins an older SDK and
+is outside the current supported release path. See
+[publication scope](docs/publishing.md#reusable-application-release-workflow)
+before selecting a repository release workflow.
 
 ## SDK test sets
 
@@ -654,7 +689,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.12.0` exposes one browser target and five explicitly paired
+The SDK exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The
@@ -764,7 +799,8 @@ extraction sequence is tracked in [docs/roadmap.md](https://github.com/TheWizard
 
 ## Canonical app descriptor
 
-New apps own `apps/<id>/arcane-app.json` schema 2. It contains publisher,
+New standalone apps own root `arcane-app.json` schema 2; explicitly selected
+multi-app layouts use `apps/<id>/arcane-app.json`. It contains publisher,
 optional permissions and security declarations, native presentation, optional
 Core requirements, and target intent, and deterministically projects the schema-1
 `arcane-package.json` required by the current browser packager. The pinned
@@ -793,6 +829,7 @@ The synchronized Arcane runtime and packager are currently distributed under
 AGPL-3.0-only. The commercial-license notice does not itself grant proprietary
 distribution rights. Resolve the applicable Arcane commercial or open-source
 license before distributing a closed-source app that bundles this runtime. Each
-browser release carries `LICENSE`, `COMMERCIAL-LICENSE.md`, and `NOTICE` under
-`licenses/arcane-os/`; the notice includes the complete bundled Marked and
-QRCode.js MIT terms.
+browser release carries `LICENSE`, `COMMERCIAL-LICENSE.md`, and `NOTICE` at the
+configured SDK package route: `node_modules/<dependency>/` for direct installed
+routes, or `licenses/arcane-os/` for a configured physical runtime layout. The
+notice includes the complete bundled Marked and QRCode.js MIT terms.

package/browser-runtime/ai/twin-cloud.mjs

@@ -15,6 +15,7 @@ export async function fetchRequest({
     toolChoice = 'auto',
     parallelToolCalls,
     reasoningEffort,
+    temperature,
     signal = null,
     id = Date.now(),
     onRequest = function observeTWiNRequest(){},
@@ -48,6 +49,9 @@ export async function fetchRequest({
     if(reasoningEffort){
         request.reasoning_effort = reasoningEffort;
     }
+    if(temperature !== undefined){
+        request.temperature = temperature;
+    }
 
     try{
         await onRequest(

package/docs/architecture.md

@@ -90,8 +90,8 @@ An external workspace can select `installed-v1` routes directly from its
 runtime, browser runtime, runtime dependency, and licenses to the configured
 browser destinations. Direct destinations are the real npm paths. Existing
 `physical-v1` workspaces, virtual installed routes, and the explicit materializer
-remain supported. Root scaffolding selects direct npm routes; the existing
-multi-app scaffold retains its physical layout. See [installed-package routes](reference/protocols.md#installed-package-browser-routes)
+remain supported. Root scaffolding selects direct npm routes; an explicitly
+selected multi-app scaffold retains its physical layout. See [installed-package routes](reference/protocols.md#installed-package-browser-routes)
 for the configuration and npm-alias form.
 
 An Arcane OS checkout is an integrated SDK consumer, not the owner
@@ -156,6 +156,9 @@ selected source route and the last successful check when evaluating freshness.
 
 The shared dev server uses RIAEvangelist's published `node-http-server` 10.0.0
 public interface for HTTPS and conditional responses on those selected routes.
+Source files, generated resources and packaged previews use the module's complete
+published MIME map, including PDF, Markdown, audio and video. Unknown file
+extensions use `application/octet-stream`.
 PEM-backed HTTPS uses Node's `Http2SecureServer` with HTTP/1.1 compatibility;
 clients negotiate either protocol on the same HTTPS port. The SDK
 owns source selection and generated representations. By default, source development
@@ -213,8 +216,20 @@ release artifact.
 
 ## App and release contract
 
-The first SDK version deliberately preserves Arcane's current repository-shaped
-URLs and release schema:
+Standalone applications use their repository root as their app root. The default
+scaffold uses `appsRoot: "."` and direct installed-package SDK routes:
+
+```text
+arcane-app.json
+arcane-package.json
+index.html
+node_modules/arcane-os/
+dist/<id>/index.html
+dist/<id>/node_modules/arcane-os/
+dist/<id>/ARCANE_APP_RELEASE.json
+```
+
+Explicit multi-app and integrated workspaces retain `appsRoot: "apps"`:
 
 ```text
 apps/<id>/arcane-app.json
@@ -236,20 +251,20 @@ release URLs. Preview, verification, bundling, and native browser-content input
 consume that same selected release root; native executable output remains
 separate. See the [complete output contract](reference/protocols.md#app-selected-package-output).
 
-Packaging places each selected app file beneath `apps/<id>/` in the release
-and preserves every shared route destination. When no selected shared payload
-supplies a root `index.html`, the SDK generates one that opens the selected app
-entry. Authored document bases, app URLs, relative module imports, and shared
-runtime paths therefore resolve through the same layout in
+Packaging keeps standalone app files at the release root and places an explicitly
+nested app beneath `apps/<id>/`. It preserves every shared route destination.
+When selected content supplies no root `index.html`, the SDK generates one that
+opens the selected app entry. Authored document bases, app URLs, relative module
+imports and shared runtime paths therefore resolve through the same layout in
 source development and packaged delivery. Packaging consumes the saved source
 and managed import maps; use `arcane import-map` to refresh those maps, or the
 ordinary `arcane dev` startup that performs that refresh.
 
 The release manifest keeps `app.entry` relative to the app directory and records
-the package launch URL in `app.start`, such as
-`./apps/hello-world/index.html`. Its complete `files` inventory includes the
-root `index.html` and the prefixed app files. Packaged browser serving opens
-`app.start`; a previously generated flat release without `app.start` retains
+the package launch URL in `app.start`: `./index.html` for a root app with that
+entry, or `./apps/hello-world/index.html` for a nested app. Its complete `files`
+inventory follows the selected layout and includes the root `index.html`.
+Packaged browser serving opens `app.start`; a previously generated flat release without `app.start` retains
 its `app.entry` launch path.
 
 The authored schema-2 descriptor is canonical for new apps and projects an
@@ -271,8 +286,9 @@ same URLs. Existing physical `arcane/` routes retain their behavior.
 `appsRoot: "."` places one standalone application at the workspace root while
 retaining its declared ID and app-relative entries. The existing `apps` option
 keeps multi-app and integrated layouts. Root static hosting consumes the same
-npm URLs, managed maps, generated PWA files, and compatibility navigation pages
-as SDK development. TWiN's ordinary static host needs no additional server;
+npm URLs, managed maps and generated PWA files as SDK development. It generates
+no nested `apps/<id>/` navigation pages or redirects. TWiN's ordinary static
+host needs no additional server;
 separate Node API hosts such as Stripe keep their existing server and SDK mail
 imports. Application location does not change their listeners or configuration.
 
@@ -400,8 +416,8 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.9.0` runtime requires Arcane `0.8.12` or newer. Compatibility
-is contractual rather than exact-version pinning: the prepared Core must meet
+The current native build contract requires Arcane Core `0.8.12` or newer.
+Compatibility is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every
 declared feature, capability, and method. Missing requirements stop before

package/docs/platform-targets.md

@@ -5,6 +5,7 @@ named operations:
 
 ```text
 describe -> doctor -> prepare -> plan -> build -> run
+                                           \-> verify (explicit selection)
 ```
 
 The available browser adapter plans from the selected workspace and schema-1
@@ -24,9 +25,10 @@ output. For example:
 
 ```bash
 # Choose one target when creating each app repository.
-npx arcane-os@dev new my-app --path ./my-app --target portable --git
+npx arcane-os@latest new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
+npm run import-map
 npm exec -- arcane native-doctor --target portable --arcane-root "../Arcane OS"
 npm exec -- arcane build --target portable --arcane-root "../Arcane OS"
 
@@ -52,7 +54,12 @@ npm exec -- arcane run --target android-arm64 --arcane-root "../Arcane OS" --for
 
 Every native scaffold also declares the browser target, so one repository can
 use the normal browser development loop and its one selected native build. It
-includes the raster icon required by the current native platform. Use the
+uses the repository root by default (`appsRoot: "."`) and reads SDK resources
+from its installed npm dependency. After `npm install`, run
+`npm run import-map` before the first package or build so the root app's managed
+browser maps are present. The initial scaffold reports that map as pending while
+the SDK dependency is absent. The scaffold includes the raster icon required
+by the current native platform. Use the
 matching scaffold target (`portable`, `windows-x64`, `linux-x64`, `linux-arm64`,
 or `android-arm64`) before running the corresponding command.
 
@@ -80,6 +87,12 @@ for the complete compatibility and breaking-change rule.
 | `linux-arm64` | `deb` | Available with explicit `--arcane-root` on a compatible native ARM64 toolchain; unsigned local development only |
 | `android-arm64` | `apk` | Available with explicit `--arcane-root`; development-signed, architecture-neutral, and physical/native ARM64 for run |
 
+macOS can consume browser applications and portable JavaScript capabilities
+within their declared runtimes. The current target registry has no macOS native
+package adapter; it exposes only the six targets above. A source-development
+native wrapper is also not an exposed `arcane dev` target. Native `run` uses the
+selected packaged application through its paired provider.
+
 Every native target accepts one selected app release and its complete bundled
 dependency closure through the provider boundary. The providers retain the
 toolchain state required for build and, where supported, launch; app source and

package/docs/reference/README.md

@@ -17,15 +17,15 @@ high-level page links to the relevant deep section instead of repeating it.
 Install the SDK in your application:
 
 ```sh
-npm install --save-exact arcane-os@0.5.17
+npm install --save-exact arcane-os@latest
 ```
 
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
-For on-device speech, follow the [browser speech quick start](ai/browser-speech.md)
+For local models, native browser voices or cloud speech, follow the [browser speech guide](ai/browser-speech.md)
 and the complete [browser AI demo](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
 Each guide names the application configuration you supply and shows the public
 call, response, cancellation, and error handling. Browser module imports use
-the SDK's [materialized import map](cli.md#arcane-import-map); installing npm
+the SDK's [managed import map](cli.md#arcane-import-map); installing npm
 alone does not make bare module names resolve in a browser.
 
 ## Reference map
@@ -47,8 +47,11 @@ alone does not make bare module names resolve in a browser.
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
 | Run a caller-selected local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
-| Run caller-selected Whisper or Kokoro in the browser | [Browser speech providers](ai/browser-speech.md) |
-| Send one TWiN Cloud request or migrate saved LLM preferences | [TWiN Cloud quick start](ai/twin-cloud.md) |
+| Run caller-selected Whisper/Kokoro, native browser recognition/voices or cloud TTS | [Browser speech providers](ai/browser-speech.md) |
+| Send TWiN chat, System One state/questions or image requests | [TWiN Cloud guide](ai/twin-cloud.md) |
+| Edit live transcription before Send, or print a complete conversation | [Chat component](runtime-components.md#chathtml) |
+| Store images outside Markdown and hydrate them in previews | [MarkdownMedia](runtime-modules.md#markdownmediajs) |
+| Print complete rendered documents, previews and conversations | [PrintView](runtime-modules.md#printviewjs) |
 | Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
 | Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
 | Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
@@ -59,9 +62,9 @@ This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.5.17` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, `arcane-os/speech-playback`, and `arcane-os/speech-text` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
-| Browser runtime | SDK `0.5.17`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
-| Browser SDK runtime | SDK `0.5.17`, `browser-runtime/` | The browser closure for events, shared logging, speech-text cleanup, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| SDK and CLI | `arcane-os`; version in [`package.json`](../../package.json) | The Node.js toolchain and focused public entrypoints listed in the [SDK API](sdk-api.md). Each entrypoint retains its own runtime requirements. |
+| Browser runtime | Selected SDK, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| Browser SDK runtime | Selected SDK, `browser-runtime/` | Events, logging, Wllama, local/native/cloud speech, TWiN requests and PWA mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract imported into `docs/reference/core/`, with SDK-local links and package-boundary notes added explicitly. |
 
 The SDK runtime source and Core reference have different owners. A browser
@@ -76,7 +79,9 @@ and the distinction between a documentation snapshot and the selected runtime.
 
 ## Installed documentation and release identity
 
-This reference accompanies `arcane-os@0.5.17`. The installed package includes
+The repository reference follows the current committed SDK capabilities. A
+documentation-only repository update can be newer than the text bundled in an
+already published package. The installed package includes
 the maintained `docs/` tree and `examples/wasm-ai-demo/` source alongside
 README and CHANGELOG. Open `node_modules/arcane-os/docs/reference/README.md`
 for the matching local reference. The generated website and test suites remain
@@ -125,28 +130,26 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 205 semantic JavaScript records across 20 JavaScript
-entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are
-Node.js control-plane surfaces,
-`arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and
-`arcane-os/speech-playback`, `arcane-os/speech-text`, and `arcane-os/browser-device`
-run in Node and browsers, and
-`arcane-os/pwa`, `arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
-The [machine-readable package
-inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
-are checked bidirectionally against every declared JavaScript export.
+The public export map is maintained in [`package.json`](../../package.json).
+It includes Node tooling, focused portable/browser entrypoints, direct runtime
+module and entity patterns, eight JSON Schemas and package metadata. The
+[SDK member reference](sdk-api.md) and [package inventory](inventory/package-api.json)
+describe focused functions; the runtime catalogs document the existing
+namespaces exposed through lowercase aliases and filename-based imports.
+Resolving a package name in Node does not supply browser, media, storage or
+Core capabilities. See the [availability matrix](availability-and-normalization.md).
 
 The seven update-check records are explicit on-demand checks; they do not poll,
 download, install, or self-update.
 
 The synchronized browser payload exposes:
 
-- 83 JavaScript module artifacts under `runtime/arcane/modules/`, including
+- JavaScript modules under `runtime/arcane/modules/`, including
   ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
   mail transport;
-- 14 shared entity modules under `runtime/arcane/entities/`;
-- 40 reusable HTML-import components under `runtime/arcane/components/`;
-- seven shared CSS artifacts, images, optional physical-workspace security
+- shared entity modules under `runtime/arcane/entities/`;
+- reusable HTML-import components under `runtime/arcane/components/`;
+- shared CSS artifacts, images, optional physical-workspace security
   files where present, and the vendored `strong-type` dependency.
 
 The module and component catalogs enumerate every shipped artifact, including
@@ -165,9 +168,11 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Observe sticky role state and startup settlement | [`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs) | Cross-host EventTarget state; observation grants no authority. |
 | Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
 | Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
-| Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebGPU full-offload availability, WebAssembly, and OPFS/DBOPFS. |
-| Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers, and caller-supplied runtime and model sources; Kokoro supports bounded Worker/session concurrency with automatic WebGPU-first execution and complete WASM-pool fallback. |
-| Add bounded persistent history and memory | [`PersistentAIChatSession.js`](runtime-modules.md#persistentaichatsessionjs) | Browser/native WebView runtime with ChatEntity/DBOPFS and a configured chat function. |
+| Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
+| Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers and selected upstream sources; automatic WebNN NPU, WebGPU, then WASM loading, or an explicit backend. |
+| Use native browser recognition/voices or selected cloud TTS | [Speech provider choices](ai/browser-speech.md) | Native APIs depend on the browser and may use remote services; cloud TTS requires the application key and endpoint access. |
+| Send complete chat, System One or image requests without retained history | [`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) | Node or browser with Fetch and explicit model/credentials; image results contain every returned image as a Blob. |
+| Add persistent history and memory | [`PersistentAIChatSession.js`](runtime-modules.md#persistentaichatsessionjs) | Browser/native WebView runtime with ChatEntity/DBOPFS and a configured chat function; `persist:false` ends retention when the operation settles. |
 | Add explicit document search/context | [`DBOPFSDocumentLibrary.js`](runtime-modules.md#dbopfsdocumentlibraryjs) | Existing DBOPFS-style adapter; search occurs only after the app calls it or deliberately wires its context builder into chat. |
 
 There is no automatic local-to-cloud, browser-to-Core, provider-to-provider, or