arcane-os 0.51.0 → 0.51.2

package/docs/reference/ai/browser-speech.md

@@ -1,11 +1,26 @@
 # Browser speech providers
 
-`arcane-os/ai/browser-speech` supplies caller-selected Whisper or native Web
-Speech recognition and synthesis, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
+`arcane-os/ai/browser-speech` supplies caller-selected Whisper transcription,
+native browser recognition and synthesis, Kokoro text-to-speech, and TWiN Cloud
+text-to-speech providers. Its local model path
 provides artifact storage, live module routing, role Workers, provider/2
 adapters, bounded parallel TTS synthesis, audio normalization, cancellation,
 and cleanup.
 
+## Choose a speech provider
+
+| Need | Factory | Input or output | Runtime and locality |
+| --- | --- | --- | --- |
+| Transcribe a recorded clip | `createBrowserWhisperProvider` | Audio input, complete transcript output | Caller-selected local model and Worker runtime |
+| Recognize live microphone speech | `createBrowserSpeechRecognitionProvider` | Final segments and transient interim text | Native browser service; may use a remote service |
+| Speak with installed browser voices | `createBrowserSpeechSynthesisProvider` | Silent native playback descriptor, then explicit playback | Native voice inventory; individual voices may be remote |
+| Generate reusable audio locally | `createBrowserKokoroProvider` | Synthesized audio | Caller-selected local model, voice and Worker runtime |
+| Generate audio through TWiN Cloud | `createTwinCloudTTSProvider` | Completed remote synthesis returned as audio | Application-owned key reader and selected FAL model |
+
+STT and TTS have independent selections and lifecycles. Applications choose
+their defaults, recognition language, voice, and activation controls. Native
+browser providers need no SDK model download or DBOPFS artifact store.
+
 ## Native browser speech recognition
 
 Select the browser's `SpeechRecognition` or `webkitSpeechRecognition` service
@@ -44,6 +59,36 @@ component `transcribe(file,context)` callback retains the existing clip path.
 Final segments waiting behind an application save remain visible in that
 transient surface until the ordered queue appends them to the main transcript.
 
+### Recognition language and editable Chat drafts
+
+The shared speech control exposes `recognitionLanguage` as an editable BCP47
+tag. Its visible picker is available before live capture, shows every suggested
+language when opened, and filters after the user changes its text. Suggestions
+retain native language and region labels; callers can also supply an exact
+custom tag. The picker is disabled during capture and outside live-recognition
+mode. Recognition language is independent of Chat's conversation language.
+
+For an initialized shared Chat component, choose whether the completed
+transcription submits immediately or remains editable:
+
+```javascript
+// chat is the application's ready shared Chat component.
+chat.transcriptionMode = 'draft';
+chat.recognitionLanguage = 'es-MX';
+chat.appendDraft('Captain, the moon-powered toaster reports: ');
+```
+
+`'submit'` is the existing default. In `'draft'` mode, final and interim native
+recognition appear immediately in the composer alongside typed text. Completion
+leaves Send to the user. Interim replacement preserves user edits; cancellation
+retires only the unedited interim range and retains confirmed text. The shared
+speech component emits cumulative `speech-transcription-progress` detail with
+`text`, `interim`, and `operationId`; confirmed completion keeps the existing
+`speech-transcription-complete` event. Interim text remains transient and never
+enters a completion payload or durable history.
+
+### Direct capture
+
 For direct use, `ai.supportsTranscriptionCapture()` detects the selected
 provider's capture capability. `ai.createTranscriptionCapture(options)` returns
 `null` for a file-only provider or a single-use capture handle with
@@ -107,6 +152,11 @@ const unsubscribe = voicePreview.subscribeCatalog(function showVoices(models) {
 function playIntroduction(input, voice) {
   return voicePreview.play({input, voice});
 }
+
+// voiceURI comes from the real catalog or the application's saved selection.
+function selectDefaultVoice(voiceURI) {
+  return voicePreview.setDefaultVoice(voiceURI);
+}
 // The owning view unsubscribes and disposes voicePreview when it closes.
 ```
 
@@ -173,6 +223,16 @@ when the returned descriptor is played. `AI.fetchTTS()` and durable
 `ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE` for native synthesis, which exposes no
 downloadable audio file.
 
+Choose preparation according to the result the application needs:
+
+| API | Result | Playback and retention |
+| --- | --- | --- |
+| `provider.prepare(payload,{signal})` | Native speech descriptor | Silent until its explicit `play()` call; keeps the selected voice |
+| `ai.prepareTTSPlayback(payload,signal)` | Promise resolving a native descriptor or real audio Blob | Silent, provider-neutral preparation; no durable storage |
+| `ai.streamTTS(text,end,options)` | Promise resolving a preparation or playback boolean | Shared segmentation and playback in original order |
+| `ai.fetchTTS(payload,signal)` | Promise resolving a real audio Blob | Audio-file providers only; does not play |
+| `ai.prepareTTS(options)` | Preparation handle with `ready` and `getAudio(index)` | Audio-file providers only; optional caller-owned durable storage |
+
 <a id="digitalocean-fal-text-to-speech"></a>
 
 ## TWiN Cloud text-to-speech
@@ -314,18 +374,18 @@ and [multilingual-v2 model schema](https://fal.ai/models/fal-ai/elevenlabs/tts/m
 ## Quick start: say one sentence
 
 Use this in a browser application served by `arcane dev`, where the generated
-import map resolves `arcane/AI` and `arcane/DBOPFS`. These browser modules are
-not Node inference APIs. To create an application:
+import map resolves `arcane-os/ai` and `arcane-os/modules/DBOPFS.js`. These
+browser modules require a browser host. To create an application:
 
 ```bash
-npx arcane-os@0.5.18 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
 npm run dev
 ```
 
 Keep the generated page's Arcane theme and import map. The examples below go in
-`apps/hello-speech/modules/App.js` and the adjacent `speech-selection.js`.
+`modules/App.js` at the application root and the adjacent `speech-selection.js`.
 Follow the development server's printed URL. Installing the SDK supplies its
 provider, storage, and Worker code; it does not install a speech model or choose
 an upstream speech runtime for your application.
@@ -374,9 +434,9 @@ instance. Configuration selects the provider without loading it; the button
 explicitly loads and unmutes TTS before requesting speech.
 
 ```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;
@@ -445,7 +505,7 @@ name. It does not load a model or create a GPU device or WebNN context:
 ```html
 <html-import
   id="browserAISetup"
-  href="/arcane/components/browser-ai-setup.html">
+  href="/node_modules/arcane-os/runtime/arcane/components/browser-ai-setup.html">
 </html-import>
 ```
 
@@ -491,13 +551,11 @@ runtime's evidence to determine actual accelerator execution.
 
 ## Developer diagnostics
 
-The shared logging API and speech traces are available in SDK `0.5.14`.
-
 Arcane uses the existing shared `user.developer` preference for diagnostic
 logging. Enable **developer mode** in the application's profile settings; the
 logger reads that preference on every emission after the shared user is ready.
-There is no separate speech verbosity or language setting. Ordinary warnings
-and errors remain visible with developer mode disabled.
+There is no separate speech verbosity setting. Ordinary warnings and errors
+remain visible with developer mode disabled.
 
 Applications can use the same owner for their complete AI requests and parsed
 responses:
@@ -534,10 +592,12 @@ that the buffer finished; use its `playback.ended` event.
 Diagnostics do not change text, voice, speed, language selection, segmentation,
 generation capacity, or playback scheduling. They stay outside chat history.
 
-## Four synthesis slots and exact-order playback
+<a id="four-synthesis-slots-and-exact-order-playback"></a>
+
+## Local synthesis capacity and exact-order playback
 
-Capacity 4 means up to four segments synthesize at once. Segment 5 and later
-wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of
+The default Kokoro capacity of 4 means up to four segments synthesize at once.
+Segment 5 and later wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of
 order, but playback waits for earlier segments and plays exact input order.
 Each slot owns a Worker/model session, so raising capacity trades memory for
 latency.
@@ -554,7 +614,7 @@ Use this when your application already has complete segments in an array. The
 configured `ai` below is the same instance created in the quick start.
 
 ```javascript
-import SpeechPlayback from 'arcane/SpeechPlayback';
+import SpeechPlayback from 'arcane-os/speech-playback';
 
 const audio = document.body.appendChild(document.createElement('audio'));
 audio.controls = true;
@@ -575,16 +635,23 @@ speakAll.addEventListener('click', async function speakAllSegments() {
 ```
 
 `prepare()` submits all three parts immediately because this `ai` exposes
-`fetchTTS` and advertises TTS execution capacity. With the default configuration,
-the provider admits up to four synthesis requests and keeps later requests in
+`prepareTTSPlayback` and advertises TTS execution capacity. With the Kokoro
+configuration above, the provider admits up to four synthesis requests and keeps later requests in
 its FIFO queue. Completed audio remains indexed, so playback is always first,
 second, third even if the third synthesis finishes first.
 
+`SpeechPlayback` prefers `prepareTTSPlayback()` when present and also supports
+existing audio-only `fetchTTS()` clients. Native browser descriptors and real
+audio Blobs remain in the same ordered sequence, including requested pauses.
+Native segments advance only after actual utterance completion and resource
+release; they are never converted into placeholder audio files.
+
 This eager path is capability-driven. A native `Arcane.speech.synthesize`
 client, or a custom client without a positive advertised TTS execution capacity,
 retains serialized synthesis with one lookahead segment. `togglePause()` pauses
-and resumes the same `audio` element. `stop()` cancels all requests owned by the
-playback. `replay()` keeps completed and pending provider segments and retries
+and resumes the active native utterance or the same `audio` element.
+`stop()` cancels all requests owned by the playback. `replay()` keeps completed
+and pending provider segments and retries
 only failed missing segments.
 
 The default `{device:'auto',maxConcurrentRequests:4}` attempts the full ONNX
@@ -597,8 +664,6 @@ selected execution device or assess the generated audio.
 
 ## Queue complete passages and wait for playback
 
-These options are available in SDK `0.5.12`.
-
 For a complete page or passage, call
 `ai.streamTTS(text, true, {voice, speed, pauseAfterMs, waitForPlayback:true})`.
 The existing AI queue owns segmentation, concurrent synthesis, ordered
@@ -911,8 +976,8 @@ speech method retain their existing behavior.
 
 ## Automatic speech-input formatting cleanup
 
-Every TTS entrypoint removes repeated same formatting marks from the outbound
-speech-input copy automatically. No application option is required:
+The shared streaming, audio-file, and `SpeechPlayback` paths remove repeated
+same formatting marks from the outbound speech-input copy automatically:
 
 ```javascript
 ai.streamTTS('## Heading\n**Hello');
@@ -937,6 +1002,12 @@ Applications omit that internal metadata. Displayed messages, saved history,
 model input, caller payload objects, language, voice, synthesis capacity, and
 playback timing are not changed by the filter.
 
+Direct native `provider.prepare()` and `provider.play()` preserve their complete
+`input` as supplied. The native route of `ai.prepareTTSPlayback()` also preserves
+that input; shared streaming and `SpeechPlayback` perform their existing cleanup
+before calling it. Choose the high-level narration path when that speech-only
+formatting cleanup is desired.
+
 The shared helper is public for code that needs the speech-only
 transformation directly:
 
@@ -954,8 +1025,9 @@ console.log(speechText.append('ing', true)); // ing
 
 ## Choose a device or reduce memory use
 
-Both speech roles accept `execution:{device,maxConcurrentRequests}`. Omitting
-`stt.execution` selects `{device:'auto',maxConcurrentRequests:1}`; omitting
+Local Whisper and Kokoro roles accept
+`execution:{device,maxConcurrentRequests}`. Omitting `stt.execution` selects
+`{device:'auto',maxConcurrentRequests:1}`; omitting
 `tts.execution` selects `{device:'auto',maxConcurrentRequests:4}`. Whisper keeps
 one transcription slot. Kokoro accepts capacities 1 through 4.
 
@@ -1147,11 +1219,12 @@ records; this contract does not freeze them or shorten their content.
 
 | Host | Availability | Notes |
 | --- | --- | --- |
-| Browser | Shipped | Requires Workers, Fetch, Blob/File, object URLs, DBOPFS/OPFS, and Web Locks. Blob/File STT requests also require the browser audio decoder. |
+| Local browser models | Shipped | Require Workers, Fetch, Blob/File, object URLs, DBOPFS/OPFS, and Web Locks. Blob/File STT requests also require the browser audio decoder. |
 | Native WebView | Conditional | Available when the WebView exposes the browser APIs above. It does not invoke Core speech. |
 | Node | Remote adapter available; local execution unavailable | TWiN Cloud uses Fetch and Blob. The local providers have no SDK Node speech-storage, Worker, or audio-decoder host. |
 | Remote TTS | Explicitly selected | TWiN Cloud uses standard Fetch and Blob with an application-owned key; no Worker, OPFS, or local model is needed for this adapter. |
 | Native browser STT | Explicitly selected, conditional | Requires `SpeechRecognition` or `webkitSpeechRecognition` and native microphone/service availability. No Worker, OPFS, or SDK model download; locality is not promised. |
+| Native browser TTS | Explicitly selected, conditional | Requires `speechSynthesis` and `SpeechSynthesisUtterance`. Uses the native voice catalog and playback lifecycle; no Worker, OPFS, or SDK model download. Native voices expose no audio export. |
 
 STT and TTS own independent provider lifecycles. A failure or cancellation in
 one role does not disable the other role or authorize a fallback provider.
@@ -1164,12 +1237,14 @@ import {
   BROWSER_SPEECH_ARTIFACT_PROTOCOL,
   createBrowserKokoroProvider,
   createBrowserSpeechRecognitionProvider,
+  createBrowserSpeechSynthesisProvider,
   createBrowserSpeechArtifactGraph,
   createBrowserSpeechAuthority,
   createBrowserWhisperProvider,
   createDbopfsSpeechArtifactStore,
   createDigitalOceanFalTTSProvider,
-  createTwinCloudTTSProvider
+  createTwinCloudTTSProvider,
+  removeBrowserSpeechModelCache
 } from 'arcane-os/ai/browser-speech';
 ```
 
@@ -1489,7 +1564,7 @@ materialized URLs. `dispose()` performs final teardown and prevents later use.
 
 `createBrowserSpeechAuthority({providerId,role,model,runtime,security})` creates
 the ordinary single-entrypoint authority. The model descriptor is
-`{id,repository,revision,dtype?,defaultVoice?,files?}`. The runtime descriptor is
+`{id,repository,revision,dtype?,defaultVoice?,voices?,files?}`. The runtime descriptor is
 `{adapter,version,revision,entry,wasmPaths?,files}`. A file is
 `{path,url,mediaType?}`. Model files may be omitted so the selected upstream
 provider performs its normal model and voice downloads after explicit use.

package/docs/reference/ai/browser-wasm.md

@@ -3,19 +3,19 @@
 Use this browser-only entrypoint when an application deliberately owns a local
 GGUF model authority and wants provider-neutral LLM lifecycle, chat, streaming,
 cancellation, and structural tool-call results without an Arcane Core host.
-For ordinary hosted applications, start with the [Arcane AI
-contracts](../core/arcane-ai-contracts.md) and `globalThis.Arcane.ai`. This
-page is the focused local-browser path beneath the normalized AI decision
-guide.
+For a remote request with an explicit model and key, use
+[TWiN Cloud](twin-cloud.md). Applications using an Arcane Core host can use
+the [native AI contracts](../core/arcane-ai-contracts.md) through
+`globalThis.Arcane.ai`. This page covers local inference in the browser.
 
 The wiring example assumes a scaffolded or materialized Arcane application
-using the current checkout's runtime tree and browser import map.
-`arcane/DBOPFS` is a managed browser-map specifier, not an npm package export.
+using its installed SDK and managed browser import map. Browser modules use
+the published `arcane-os` exports below; DBOPFS still requires a browser host.
 See [browser runtime delivery](../protocols.md#browser-runtime-delivery) before
 using the example in a custom host or bundler.
 
 ```javascript
-import DBOPFS from 'arcane/DBOPFS';
+import DBOPFS from 'arcane-os/modules/DBOPFS.js';
 import {
     createArcaneAI,
     createBrowserModelSource,
@@ -106,7 +106,7 @@ selection; a failed GPU load does not silently switch to CPU.
 | `ai.llm.chat(request)` / `ai.fetchRequest(request)` | Validated OpenAI-like completion. |
 | `ai.llm.stream(request)` | Mutable async-iterator handle with `result` and `cancel(reason)`. |
 | `ai.streamRequest(request)` | Consumes the stream, publishes every choice's ordinary content/reasoning in provider order, and returns complete JSON text for a multi-choice terminal completion, one structural-call array for selected tool output, or ordinary single-choice text. |
-| `ai.createChatSession(options)` | Asynchronously resolves `Promise<PersistentAIChatSession>` bound to this exact controller; caller-supplied `chat` is rejected. |
+| `ai.createChatSession(options)` | Asynchronously resolves `Promise<PersistentAIChatSession>` bound to this exact controller; caller-supplied `ai` and `chat` are rejected. |
 | `ai.unload()` | Cancels active work, releases the Wllama session, and returns flat unloaded status; the DBOPFS cache remains. |
 | `ai.dispose()` | Permanently disposes the controller; explicit `store.remove(source)` is required to delete cached model content. |
 
@@ -212,7 +212,7 @@ cached entry or rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`.
 
 ```javascript
 const {security, cache} = ai.status().llm;
-console.log(security.secure); // false unless explicitly selected
+console.log(security?.secure === true); // false when the optional field is absent
 console.log(cache);
 ```
 
@@ -254,8 +254,11 @@ the selected hardware. Chromium's optional adapter `type` is a
 [developer feature](https://developer.chrome.com/docs/web-platform/webgpu/developer-features);
 the standard API does not always expose integrated or discrete classification.
 The Profile says **Already using the performance GPU.** for an explicitly
-reported discrete GPU and hides performance flag advice. Missing classification
-shows **GPU available.** without flag advice and remains unconfirmed.
+reported discrete GPU. Missing classification shows **GPU available.** and
+remains unconfirmed. On supported Windows desktop Chromium browsers, Profile
+keeps its **Copy GPU flag address** control available regardless of adapter
+classification or detection outcome. This Profile control is separate from
+the provider's conditional one-time alert described above.
 The browser does not expose the flag's current value or a reliable machine-wide
 GPU count, and a discrete adapter does not prove it is the fastest available.
 See [Chrome's GPU selection guidance](https://developer.chrome.com/docs/web-platform/webgpu/troubleshooting-tips#webgpu_is_slower_than_webgl).
@@ -349,7 +352,7 @@ connect its existing display operations without parsing provider protocol:
 ```javascript
 import {
     formatConversationClosingReportText
-} from '/arcane/modules/ConversationClosingReport.js';
+} from 'arcane-os/conversation-closing-report';
 
 async function streamClosingReport(ai, messages, closingTool, view, signal) {
     return ai.streamRequest(
@@ -415,10 +418,10 @@ explain why load is available, blocked, or not yet measured without guessing.
 `capabilities()` reports browser observations such as WebAssembly, OPFS,
 WebGPU API presence, WebGPU operation, secure context, cross-origin
 isolation, and hardware concurrency. `navigator.gpu` alone is not operational
-evidence. The authoritative runtime can operate without cross-origin isolation,
-so that flag is not a hard gate; secure context and WebGPU/full-offload support
-are platform requirements. `probe()` exercises packaged Wllama backend
-operations only while unloaded; it does not download a model.
+evidence. The authoritative runtime can operate without cross-origin isolation.
+Secure context remains required; WebGPU/full-offload support applies to the
+GPU route, while explicit `gpuLayers:0` uses CPU. `probe()` exercises packaged
+Wllama backend operations only while unloaded; it does not download a model.
 
 ## BROWSER_WASM_RUNTIME_AUTHORITY
 
@@ -427,9 +430,9 @@ operations only while unloaded; it does not download a model.
 Mutable metadata for the shipped browser runtime. Its protocol is
 `arcane-ai-browser-wasm/2`; the direct provider uses
 `arcane-ai-adapter/1` and `adaptV1LlmProvider()` projects it into
-`arcane-ai-provider/2`. It records Wllama `3.6.0`, the embedded llama.cpp
-revision, licenses, and the disabled compatibility-runtime and
-remote-model-helper policy.
+`arcane-ai-provider/2`. It records Wllama `3.6.0`, upstream license metadata,
+packaged runtime asset URLs, execution policy, and the disabled
+compatibility-runtime and remote-model-helper policy.
 
 ### Value and import
 
@@ -541,9 +544,9 @@ async function loadCachedModelAfterUserChoice() {
 `await ai.createChatSession(options)` dynamically creates a
 [`PersistentAIChatSession`](../runtime-modules.md#persistentaichatsessionjs)
 whose AI API is permanently bound to this controller. `options` must
-be a plain object and must not contain `chat`; this prevents a session from
-claiming the controller's lifecycle while sending its turns through another
-provider.
+be a plain object and must not contain `ai` or `chat`; this prevents a session
+from claiming the controller's lifecycle while sending its turns through
+another provider.
 
 ## createBrowserModelSource()
 
@@ -728,7 +731,7 @@ console.
 ### Availability and normalization
 
 The adapter is available anywhere the caller can supply a compatible
-`arcane-ai-browser-wasm/1` provider object. It performs only the versioned
+`arcane-ai-adapter/1` provider object. It performs only the versioned
 provider-shape normalization into `arcane-ai-provider/2`. The v1 ingress,
 terminal result, cancellation, and ordinary iterator projection use the same
 structural-message contract; the wrapper does not create a
@@ -741,7 +744,7 @@ provider and are forwarded through the normalized role contract.
 
 ```javascript
 import {adaptV1LlmProvider} from 'arcane-os/ai/browser-wasm';
-import {getAIProviderRuntime} from 'arcane/AIProviderRuntime';
+import {getAIProviderRuntime} from 'arcane-os/ai-provider-runtime';
 
 const runtime = getAIProviderRuntime();
 const release = runtime.register(adaptV1LlmProvider(provider));

package/docs/reference/ai/twin-cloud.md

@@ -1,12 +1,24 @@
-# TWiN Cloud: one request
+# TWiN Cloud requests, images, and state evaluation
 
 Use `fetchRequest` from `arcane-os/ai/twin-cloud` for a complete TWiN Cloud
 request in Node or a browser with an explicit key and model. It imports no
 browser profile, DOM, user singleton, or storage, and starts no work on import.
 The existing browser `AI.js` interface remains available for applications that
 already use its provider selection, lifecycle, and speech. TWiN Cloud is that
-interface's default remote LLM service, named `TWIN`; speech stays on device
-and does not use the TWiN access key.
+interface's default remote LLM service, named `TWIN`. Speech is selected
+independently: applications can use local models, native browser speech, or
+[TWiN Cloud TTS](browser-speech.md#twin-cloud-text-to-speech) with an
+application-owned key reader.
+
+| Operation | Public API | Caller supplies | Result |
+| --- | --- | --- | --- |
+| Chat completion | `fetchRequest(options)` | Key, model, complete messages, and optional tools or output schema | Complete parsed provider JSON |
+| State and questions | `fetchSystemOneRequest(options)` | Key, a System One model, complete state, and questions | Complete parsed native System One response |
+| Image generation | `generateImages(options)` | Model, prompt, provider parameters, and key or key reader | Every generated image as a Blob in provider order |
+
+These functions share no retained conversation. Choose the operation supported
+by the selected model; each section below describes its own transport,
+callbacks, cancellation, and retry behavior.
 
 ## Node: explicit key, model, and structured result
 
@@ -57,7 +69,7 @@ strict:true, schema:...}}`. `structuredOutput:true` or `'json'` instead selects
 ## Shared request behavior
 
 The focused API accepts complete `messages`, optional `tools`, `toolChoice`,
-`parallelToolCalls`, and `reasoningEffort` in addition to the explicit
+`parallelToolCalls`, `reasoningEffort`, and `temperature` in addition to the explicit
 `twinKey` and `model`. Tool options use the existing chat-completion wire fields
 `tools`, `tool_choice`, and `parallel_tool_calls` when `tools` is nonempty.
 A supplied nonempty `reasoningEffort` uses the provider's `reasoning_effort`
@@ -65,6 +77,13 @@ field; omission preserves its default. No output limit is added by this API.
 The function neither executes tools nor adds provider-response envelope
 validation.
 
+An optional caller-selected `temperature` is forwarded unchanged, including
+`0`. Omitting it or passing `undefined` leaves the field absent so the selected
+provider uses its own default. The SDK does not clamp it, persist it as a
+preference, or add an output limit. Each request and its retries keep that
+request's value. The browser `AI.fetchRequest` and `AI.streamRequest` object
+APIs support the same option on their built-in TWiN route.
+
 Optional `id`, `onRequest(request,id,metadata)`, and
 `onResponse(response,id,false)` follow the complete-response `AI.fetchRequest`
 callback shape. The request callback runs before dispatch; the response
@@ -331,17 +350,17 @@ The following browser example uses the same managed imports as the
 Create an application and start its source server:
 
 ```bash
-npx arcane-os@0.5.17 new hello-twin --path ./hello-twin --target browser
+npx arcane-os@latest new hello-twin --path ./hello-twin --target browser
 cd hello-twin
 npm install
 npm run dev
 ```
 
 Keep the generated Arcane theme and import map. Place the JavaScript below in
-`apps/hello-twin/modules/App.js`. Run it in the served browser page, not Node.
+`modules/App.js` at the application root. Run it in the served browser page.
 This first example is for the new application created above. An existing
 application must complete the saved-preference migration below before importing
-`arcane/AI` or any module that imports it.
+`arcane-os/ai` or any module that imports it.
 
 ## Supply the key at runtime and display the response
 
@@ -352,12 +371,12 @@ configuration source; do not put a real key in this module, Git, or diagnostics.
 The SDK also reads `globalThis.arcane.config.twinCloud.accessKey` when present.
 
 ```javascript
-import arcaneThemeReady from 'arcane/ThemeBootstrap';
+import arcaneThemeReady from 'arcane-os/modules/ThemeBootstrap.js';
 
 await arcaneThemeReady;
 // In an upgrade bootstrap, the existing preference owner's migration must
 // already be complete before this dynamic import evaluates AI.js.
-const { default: AI } = await import('arcane/AI');
+const { default: AI } = await import('arcane-os/ai');
 const applicationRuntime = globalThis.applicationRuntime;
 const ai = new AI();
 ai.twinKey = applicationRuntime.twinKey;
@@ -470,7 +489,7 @@ This ordering matters during module evaluation: `AI.js` installs its
 user-readiness handler immediately. If `window.user.ready` is already true, it
 can immediately read that user's preference tuple and construct `window.ai`.
 Waiting until a later `setAI()`, provider-startup call, or button click is too
-late. A static `import AI from 'arcane/AI'` evaluates before the surrounding
+late. A static `import AI from 'arcane-os/ai'` evaluates before the surrounding
 module body, even if its text appears below migration code. Keep AI and its
 importing modules out of the bootstrap's static import graph, finish the
 existing owner's migration, then cross the dynamic-import boundary:
@@ -478,7 +497,7 @@ existing owner's migration, then cross the dynamic-import boundary:
 ```javascript
 // Place these lines after the application's existing preference migration
 // has finished writing and exposing migratedTuple, not before that operation.
-const { default: AI } = await import('arcane/AI');
+const { default: AI } = await import('arcane-os/ai');
 const ai = new AI(...migratedTuple);
 ```
 

package/docs/reference/asset-versioning.md

@@ -1,50 +1,46 @@
-# Release-derived browser asset URLs
+# Clean browser resource URLs
 
-Applications that enable [PWA delivery](pwa.md) use clean local resource URLs.
-Their generated offline manifest and service worker own the selected application
-and SDK release information. In that mode, the delivery transformer removes
-only the SDK-owned `arcaneVersion` field, preserving authored query fields and fragments.
-The behavior below continues to apply when PWA delivery is disabled and to native
-packages. Workspace runtime materialization remains usable by either target;
-the selected browser delivery applies its PWA URL policy.
+The SDK's managed import maps, source server and application packager use clean
+local resource URLs for PWA, non-PWA and native delivery. Their shared
+transformation removes the SDK-owned `arcaneVersion` field. It never appends a
+release version to those URLs. Enabled [PWA delivery](pwa.md) records the
+application and SDK versions in its generated offline manifest and worker.
 
-The SDK's public import-map generator, runtime materializer, source server and
-application packager use the selected SDK package version for local browser
-resource references. The query field is `arcaneVersion`. Its value comes from
-SDK package metadata, not a timestamp, content measurement, or application
-constant.
-
-For example, an existing `./arcane/modules/HTMLImport.js?v=6#module` reference
-becomes `./arcane/modules/HTMLImport.js?v=6&arcaneVersion=${version}#module`.
-`arcaneVersion` is the SDK's resource version field: transformation updates its
-first existing value and removes duplicate `arcaneVersion` fields, or appends it
-when absent. Regenerating for another SDK release replaces only that SDK value.
+For example,
+`./node_modules/arcane-os/runtime/arcane/modules/HTMLImport.js?v=6&arcaneVersion=0.51.1#module`
+becomes
+`./node_modules/arcane-os/runtime/arcane/modules/HTMLImport.js?v=6#module`.
+Every SDK-owned field is removed, including duplicate and encoded spellings.
 Authored fields, including `v`, encoded keys and values, repeated or empty query
-segments, their source spelling, and fragments remain intact.
+segments, their source spelling, and fragments remain intact. Remote URLs and
+fragment-only references retain their existing value.
 
 ## Public tooling
 
 - Run the installed SDK's `materializeInstalledSdkRuntime()` to refresh the
-  workspace runtime from that installation. Its generated local resource
-  references use the installed package version, including npm aliases.
+  physical workspace runtime from that installation. It copies the complete
+  selected runtime; direct installed-package workspaces read their npm routes
+  without requiring this copy.
 - Run `arcane import-map` through the installed SDK to regenerate the managed
   import map and its application HTML. Named SDK imports and URL-shaped module
-  entries point to versioned resources.
+  entries point to the selected clean resource URLs.
 - `arcane dev` applies the same reference transformation to served source
-  without editing the source files. An explicit live SDK source mount uses the
-  version in that source checkout's `package.json`. Otherwise it uses the
-  materialized SDK version recorded by the workspace's existing semantic lock.
-- The application packager applies resource versioning after its selected
-  adapter finishes. The resulting application can be served by an ordinary
+  without editing the source files. An explicit live SDK source mount changes
+  the source of those resources. PWA release metadata still identifies the
+  selected source or installed SDK version.
+- The application packager applies the clean-URL transformation after its
+  selected adapter finishes. The resulting application can be served by an ordinary
   static host without a JavaScript transformation service.
 
 The shared transformation edits actual local module imports, resource URL
 construction, HTML resource attributes and CSS resource references. It does not
 change displayed text, prompts, application data, downloaded model content,
 remote provider URLs, or arbitrary strings that happen to resemble filenames.
-Worker entry references and their local module imports are versioned separately:
-Workers do not inherit a document's import map. `HTMLImport` carries its own
-release query into local dynamically loaded components and their resources.
+Worker entry references and their local module imports are handled at their
+own resource boundaries because workers do not inherit a document's import map.
+`HTMLImport` removes the SDK-owned field from same-origin component resource
+references and resolves SDK component resources from the component's actual
+runtime root, including direct installed-package paths.
 
 Computed application URLs that have no statically identifiable resource
 reference remain application-owned expressions. The SDK does not intercept
@@ -55,7 +51,7 @@ an exact matching computed module URL, but is not a wildcard query rule.
 
 The SDK server sends `Cache-Control: no-cache` for application entry/managed
 HTML and managed import-map JSON. This allows storage but requests revalidation, so an ordinary navigation
-or refresh obtains the current entry document and release URLs. Other assets
+or refresh obtains the current entry document and clean resource URLs. Other assets
 retain ordinary caching; no cache or user storage is cleared.
 
 For PWA delivery the SDK server revalidates all served resources, including
@@ -64,12 +60,13 @@ revalidate stable resource URLs. The service worker maintains its own selected
 offline resource cache independently of the HTTP cache.
 
 An independently configured static host must likewise revalidate entry HTML
-and managed import-map JSON. The generated package supplies versioned resource
-references; it cannot configure another server's HTTP headers.
+and managed import-map JSON, and set resource caching appropriate to its delivery
+workflow. The generated package supplies clean resource references; it cannot
+configure another server's HTTP headers.
 
-An already-open document keeps modules it has evaluated. Versioned references
-take effect on ordinary navigation or refresh; they do not replace live module
-instances, force a reload, restart a model, or erase a conversation. The SDK does
+An already-open document keeps modules it has evaluated. Changed files become
+available through ordinary navigation and cache revalidation; they do not replace
+live module instances, force a reload, restart a model, or erase a conversation. The SDK does
 not retain earlier installed runtime trees after materialization.
 
 `HTMLImport` registers its element once per browser custom-element registry.