arcane-os 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.64.0
+
+- Add retained native Whisper transcription through the existing Core speech
+  service and AI API, with actual model readiness, complete recordings and
+  transcripts, native progress, joined cancellation, and one eligible
+  accelerated-inference recovery on the prepared CPU runtime.
+- Preserve the same accepted transcription through internal recovery using
+  its actual Core request identity. Shared AI and speech controls report
+  recovering/error states honestly without discarding the original request
+  or turning its terminal native failure into cancellation.
+- Add the SDXL Base 1.0 text-to-image descriptor and correct the shared native
+  image binding's asynchronous worker stack allocation while preserving
+  existing model selection, complete inputs and native lifecycle.
+- Add `arcane-os/core/repositories` with per-user `ArcaneData/Repos` defaults
+  and connected working-repository open/status/pull/push/drain ownership.
+  Explicit paths and existing data remain unchanged; applications own
+  connection selection, remotes and product records. No data migration.
+- Keep optional NPU, repository file-write orchestration, generic development
+  Core composition, Codex/MCP and Ollama lifecycle drafts outside this release.
+  The npm dependency tree is unchanged; native resources use their documented
+  upstream installation and matching numeric-release helper assets.
+
 ## 0.63.0
 
 - Add the approved FLUX.2 Klein 4B text-to-image model descriptor to the

package/README.md

@@ -20,7 +20,7 @@ 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.63.0` SDK contract. Development applications declare
+This checkout defines the `0.64.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/core/client.mjs

@@ -459,7 +459,10 @@ export function createCoreClient({
         if(eventOwnerFailure)return Promise.reject(eventOwnerFailure);
         let selected;
         try{selected=connect();}catch(error){return Promise.reject(error);}
-        const {signal,timeoutMs=10*60*1000}=options??{};
+        const {signal,timeoutMs=10*60*1000,onRequest}=options??{};
+        if(onRequest!==undefined&&typeof onRequest!=='function'){
+            return Promise.reject(new TypeError('Arcane request observer must be a function.'));
+        }
         if(signal&&(typeof signal.aborted!=='boolean'
             ||typeof signal.addEventListener!=='function'
             ||typeof signal.removeEventListener!=='function')){
@@ -483,6 +486,8 @@ export function createCoreClient({
             if(!settle(id,failure))report(failure);
         }
         try{
+            if(onRequest)Promise.resolve(onRequest({requestId:id})).catch(report);
+            if(!pending.has(id))return promise;
             Promise.resolve(selected.send(frame)).catch(sendFailed);
         }catch(error){sendFailed(error);}
         return promise;
@@ -569,7 +574,7 @@ export function createCoreFacade(client){
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
             synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
-            transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal})},
+            transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal,onRequest:options?.onRequest})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),
             ensurePlatform:()=>invoke('localai.platform.ensure',{},long),recover:request=>invoke('localai.services.recover',request??{},long),
             setParallelRequests:request=>invoke('localai.parallel.requests.set',request??{},long),

package/docs/reference/README.md

@@ -56,6 +56,8 @@ alone does not make bare module names resolve in a browser.
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
 | Generate complete local PNG images with a retained native model | [Local image generation](local-image-generation.md) |
+| Select FLUX.2 Klein 4B and its three complementary model resources | [FLUX.2 Klein 4B through Core](local-image-flux.md) |
+| Compose independently loaded transcription and synthesis engines | [Native speech service](native-speech.md) |
 | Edit an original PNG with a complete prompt and explicit strength | [Local image editing](local-image-editing.md) |
 | Project complete stored model files into native working files | [Model assets through Core](model-assets.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |

package/docs/reference/core-client.md

@@ -67,7 +67,7 @@ current dispatcher and service state for a newly connected document, without
 restarting services. Repeated `connect()` calls on the same connection do not
 send another replay. See [runtime replay](core-runtime.md#state-and-frames).
 
-`client.invoke(method, parameters, {signal, timeoutMs})` returns the actual
+`client.invoke(method, parameters, {signal, timeoutMs, onRequest})` returns the actual
 response result or rejects with `CoreError`. Parameters, result fields and
 event data retain their complete supplied content. JSON encoding belongs only
 to transports that require it; values crossing those transports must be
@@ -77,6 +77,14 @@ The compatibility facade retains its operation-specific timeouts and streaming
 callbacks. Streaming IDs and isolated-operation IDs are separate protocol
 correlation fields alongside the supplied request fields.
 
+The optional `onRequest({requestId})` observer runs synchronously after the
+client owns the request and before transport dispatch. It exposes the actual
+Core correlation ID without adding fields to the supplied payload. A
+pre-aborted request never calls the observer. A synchronous observer failure
+rejects the request before sending; a returned promise is observed for errors
+without delaying dispatch. If the observer cancels or closes the request,
+the client does not subsequently send it.
+
 `Arcane.speech.synthesize(request, {signal})` forwards the optional cancellation
 signal through the same request lifetime. Existing one-argument calls retain
 the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
@@ -87,12 +95,13 @@ registered speech service and its engine; the facade supplies no speech engine.
 call and normalizes cancellation to `AbortError` with
 `ARCANE_AI_REQUEST_ABORTED`, preserving the original error as its cause.
 
-`Arcane.speech.transcribe(request, {signal})` forwards cancellation through the
+`Arcane.speech.transcribe(request, {signal, onRequest})` forwards cancellation through the
 same request lifetime and retains its 180,000 ms timeout and complete request.
 `AI.fetchSTT(audio, signal)` carries that signal into the native call. A
 pre-aborted signal sends no transcription request; an in-flight abort sends
 `request.cancel` and suppresses late responses. The registered transcription
 service owns interruption and release of its actual engine operation.
+Its optional request observer uses the same pre-dispatch correlation contract.
 
 ## Current-window theme
 

package/docs/reference/core-native-packaging.md

@@ -280,6 +280,23 @@ until actual unload or shutdown completes. See
 [local image generation](local-image-generation.md) for selection, complete
 results and CPU/Metal platform boundaries.
 
+### Injected native speech engines
+
+An application-owned service factory can return
+`createSpeechService({stt,tts,signal})` from `arcane-os/core/speech`, supplying
+either role or both. Include that factory through the existing
+`native.services` and `package.nativeResources` composition above. The host
+constructs its selected engines; this shared service installs no engine,
+downloads no model and selects no browser or native speech default.
+
+Core starts both configured role loads independently and remains responsive.
+`speech.status` and replaying service subscriptions report actual loaded-model
+state separately for transcription and synthesis. Complete requests/results
+are forwarded unchanged. Request cancellation reaches its engine independently
+of the service lifetime; `close`/`drain` abort and join both engines and their
+pending work. Engines must settle cancelled inference before Core reaches
+service cleanup. See the [engine interface, progress and shutdown contract](native-speech.md).
+
 ## Windows executable
 
 The ordinary application command is:
@@ -313,12 +330,24 @@ host output; downstream applications use the published package and matching
 release asset. `doctor()` reports the selected prerequisites and missing files;
 it does not download the host or probe the installed WebView runtime.
 
-The assembled directory contains `Arcane.exe`, the unchanged `app/` payload,
-Core runtime and semantic `arcane-native.json`. Launch `Arcane.exe` on Windows
-x64 with the Microsoft Edge WebView2 Runtime installed. It opens the selected
+The assembled directory contains the app-named launcher, its matching
+`.exe.config`, the unchanged `app/` payload, Core runtime and semantic
+`arcane-native.json`. `manifest.host.executable` is the authoritative relative
+launcher name for shortcuts and direct launch. Assembly uses
+`appDescriptor.displayName` plus `.exe`, such as `Moon Cheese Hotline.exe`;
+low-level compositions without a nonempty string display name use the app ID.
+Windows-reserved filename characters and controls become underscores, and
+reserved DOS device basenames receive an underscore prefix. Supported Unicode,
+case and spaces remain; the original descriptor and title are unchanged.
+The reusable host archive/cache retains `Arcane.exe` and `Arcane.exe.config`;
+the internal `runtime/ArcaneCore.exe` also keeps its original name.
+
+Launch the manifest-selected executable on Windows x64 with the Microsoft
+Edge WebView2 Runtime installed. It opens the selected
 app in WebView2 and owns its framed connection to the bundled Core process.
 `verify()` observes the assembled files and manifest; it does not execute the
-window or prove application behavior. `run()` launches the executable and
+window or prove application behavior. `run()` reads the saved manifest and
+launches that executable, so existing generic-name artifacts remain usable. It
 observes complete diagnostics and exit. Cancelling that operation closes its
 input, allowing the window and accepted Core service work to drain without a
 forced process termination.
@@ -331,7 +360,7 @@ into a derived `runtime/arcane-app.ico` with 16, 32, 48 and 256-pixel images.
 Aspect ratio and transparency are preserved. An ICO selection keeps its
 authored image set. The original application asset remains unchanged.
 
-The provider embeds the selected images in the copied `Arcane.exe` and records
+The provider embeds the selected images in the copied app-named executable and records
 `manifest.host.icon` and `manifest.host.executableIcon:true`. It replaces the
 executable's main icon group while preserving other groups, languages, resources
 and file content. Conversion uses Node standard capabilities on every assembly
@@ -390,7 +419,7 @@ for the facade and browser behavior.
 For explicit user-selected workspace/state locations, launch:
 
 ```sh
-Arcane.exe --arcane-launch-config path/to/launch.json
+"Moon Cheese Hotline.exe" --arcane-launch-config path/to/launch.json
 ```
 
 The complete JSON object reaches the service factories as their second

package/docs/reference/core-repositories.md

@@ -0,0 +1,149 @@
+# Native repository workspaces
+
+`arcane-os/core/repositories` owns a persistent native location for connected
+repositories, separate from application code and application preferences.
+Applications choose their connection names, remotes, branches, files and Core
+methods. Importing the module and constructing an owner perform no I/O.
+
+## Persistent locations
+
+`resolveArcaneDataPaths({dataRoot}={})` returns absolute
+`{dataRoot,repositoriesRoot}` paths without creating directories:
+
+| Host | Default dataRoot | repositoriesRoot |
+|---|---|---|
+| Windows | `%LOCALAPPDATA%/ArcaneData`, or `~/AppData/Local/ArcaneData` when that variable is empty | `<dataRoot>/Repos` |
+| Linux | `$XDG_DATA_HOME/ArcaneData` when XDG_DATA_HOME is absolute, otherwise `~/.local/share/ArcaneData` | `<dataRoot>/Repos` |
+| macOS | `~/Library/Application Support/ArcaneData` | `<dataRoot>/Repos` |
+| Android or another adapted host | Explicit `dataRoot` supplied by the host, such as its app files directory followed by `ArcaneData` | `<dataRoot>/Repos` |
+
+An explicit `dataRoot` selects that directory directly; the SDK does not append
+another `ArcaneData`. Relative explicit paths resolve from the process working
+directory. Unsupported default platforms report `ARCANE_DATA_ROOT_REQUIRED`.
+The Android host also supplies Git/process execution through the existing
+process-adapter contract; this module does not install Git or choose shared
+Android storage.
+
+The factory's first actual operation creates necessary parent directories.
+No existing data is moved, copied, deleted, renamed or migrated. `appRoot`,
+`stateRoot`, preferences, OPFS and the existing CLI/workspace defaults remain
+independent and unchanged.
+
+## One connected working checkout
+
+```javascript
+import {createRepositoryWorkspace} from 'arcane-os/core/repositories';
+
+const repository = createRepositoryWorkspace({
+    name: 'moon-cheese-dispatches',
+    remote: applicationConnection.remote,
+    branch: applicationConnection.branch
+});
+
+const opened = await repository.open({signal});
+// opened.directory is <ArcaneData>/Repos/moon-cheese-dispatches.
+const status = await repository.status({signal});
+await repository.close();
+```
+
+`createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run}={})`
+returns `{directory,open,status,pull,push,close,drain,dispose}`. The `directory`
+property is the absolute selected working path.
+
+- Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
+  one nonempty directory name for each distinct connection; the SDK neither
+  derives it from a remote nor maintains a connection registry. Names are one
+  component, excluding `.`/`..` and slash/backslash separators. Choose distinct
+  names under the host filesystem's ordinary case rules.
+- Supply `directory` to use an existing application-selected path instead.
+  This takes precedence over `name` and `dataRoot`; relative paths resolve from
+  the process working directory. The path is not relocated or rewritten.
+- `remote` is required only when a missing or empty destination needs cloning.
+  `branch`, when supplied, is passed unchanged to Git's `clone --branch` option;
+  otherwise Git selects the remote's default branch. Existing checkouts keep
+  their own branch, remote, tracked files, untracked files and local changes.
+- `onEvent` and optional `run` use the existing SDK process owner. The default
+  adapter is `runProcess`; Git must be available on PATH. Credentials and
+  authentication remain with Git and the native host. The SDK adds no download,
+  credential store, polling, network retry or process supervisor.
+
+All operation methods accept `{signal}={}` and return promises:
+
+| Method | Result and side effect |
+|---|---|
+| `open` | For a missing/empty destination, runs one clone and returns `{directory,cloned:true,stdout,stderr}` with complete process output. For an existing working repository root, returns `{directory,cloned:false}` after read-only inspection. Later opens on that owner reuse preparation. |
+| `status` | Prepares the checkout if needed, then returns the existing `repositoryStatus` result unchanged. |
+| `pull` | Prepares the checkout if needed, then runs the existing clean-checkout, fast-forward-only `repositoryPull` operation unchanged. |
+| `push` | Prepares the checkout if needed, then runs the existing `repositoryPush` operation unchanged, preserving its support for unrelated uncommitted working files. |
+| `close`, `drain`, `dispose` | The same idempotent operation: stop accepting new calls and await accepted work and its process/event cleanup. They retain the repository on disk. |
+
+Opening an existing repository never pulls, switches branches, resets, changes
+its remote or rewrites files. A nonempty destination that is a bare repository,
+a subdirectory of another checkout, or ordinary non-repository data is left
+untouched and reports its Git error or `ARCANE_REPOSITORY_DIRECTORY_INVALID`.
+A failed or cancelled clone reports the actual failure; any remaining directory
+is retained for application-owned inspection. There is no automatic deletion or
+destructive retry. Filesystem failures and complete Git diagnostics propagate.
+
+## Ownership, concurrency and shutdown
+
+Calls targeting the same resolved path spelling in one Node process run in
+acceptance order, including separate owners selecting that path. Windows keys
+are case-insensitive. The queue does not resolve symlink aliases or macOS case
+variants; applications use one consistent path for a shared connection.
+This prevents overlapping Git/index writes and duplicate successful cloning.
+Different directories proceed
+independently. Applications coordinate separate processes and their own direct
+file/Git writes; this module does not create a daemon or cross-process lock.
+
+A pre-aborted call starts no work. A queued aborted operation does not run when
+its turn arrives. Active cancellation reaches the existing process owner, which
+terminates its owned process tree and joins complete output/event cleanup.
+Shutdown drains accepted operations rather than deleting data or terminating
+the host early. Calls after close reject with `CORE_CLOSING`; a failed operation
+still pending when close begins rejects that drain through an `AggregateError`.
+The caller retains each operation's complete result or failure separately.
+
+The cold path is one selected connection, one parent-directory creation and one
+Git clone. Opening an existing checkout uses one read-only Git command. A
+prepared owner's status/pull/push use their existing repository operation graph.
+There is no scan across applications, connections, models or platforms. Git
+progress, process-starting/completion, heartbeat and cancellation events use
+the existing `onEvent` owner with complete output and backpressure.
+An awaited event callback must not await another operation or shutdown for the
+same directory, including calls through another workspace owner: that operation
+needs the observing callback to finish. Schedule such follow-up without awaiting
+it inside that callback, and retain/observe its promise at the application owner.
+
+Compose this owner inside an application-selected Core service. Bind only the
+application's chosen methods, pass each request's `context.signal`, and return
+`drain: repository.drain` and `dispose: repository.dispose` from that service.
+Keep initialization at the repository operation that needs it; page rendering
+and unrelated services do not wait for a clone. This module installs no browser
+RPC, chooses no application service and changes no Core launch configuration.
+
+## Bare snapshots stay separate
+
+[`createGitTextSnapshot`](git-text-snapshot.md) continues to require its explicit
+dedicated bare `cacheDirectory`. It neither becomes a working checkout nor
+changes existing callers' caches. A new native caller can place that distinct
+cache under the shared location without changing the snapshot contract:
+
+```javascript
+import path from 'node:path';
+import {createGitTextSnapshot} from 'arcane-os';
+import {resolveArcaneDataPaths} from 'arcane-os/core/repositories';
+
+const {repositoriesRoot} = resolveArcaneDataPaths();
+const snapshot = createGitTextSnapshot({
+    cacheDirectory: path.join(repositoriesRoot, 'moon-cheese-reader-cache'),
+    remote: applicationConnection.remote,
+    ref: applicationConnection.ref,
+    selectPath: applicationSelectPath
+});
+```
+
+Never assign the same directory to a bare snapshot and a writable workspace.
+Applications retain remote/ref selection, document parsing, scores, messages,
+saved connection state and refresh policy. Existing explicit repository paths
+continue to operate where they already are.

package/docs/reference/inventory/package-api.json

@@ -1,17 +1,73 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.62.0",
+  "sdkVersion": "0.63.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 274,
+  "memberCount": 278,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-repositories:resolveArcaneDataPaths",
+      "name": "resolveArcaneDataPaths",
+      "displayName": "resolveArcaneDataPaths()",
+      "kind": "function",
+      "signature": "resolveArcaneDataPaths({dataRoot}={})",
+      "entrypoints": ["arcane-os/core/repositories"],
+      "primaryImport": "arcane-os/core/repositories",
+      "group": "Native repository workspaces",
+      "summary": "Resolves persistent per-user ArcaneData and Repos locations without I/O or migration.",
+      "availability": "Node on Windows, Linux and macOS; Android supplies its persistent dataRoot",
+      "protocol": "Native filesystem paths",
+      "normalization": "Returns absolute dataRoot and repositoriesRoot; explicit dataRoot takes precedence, otherwise uses LocalAppData, XDG data home or user Application Support. Changes no launch, preference, workspace or user data."
+    },
+    {
+      "id": "core-repositories:createRepositoryWorkspace",
+      "name": "createRepositoryWorkspace",
+      "displayName": "createRepositoryWorkspace()",
+      "kind": "function",
+      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run=runProcess}={})",
+      "entrypoints": ["arcane-os/core/repositories"],
+      "primaryImport": "arcane-os/core/repositories",
+      "group": "Native repository workspaces",
+      "summary": "Owns one selected native working checkout with ArcaneData/Repos defaults and existing Git/process lifecycle.",
+      "availability": "Node with Git on Windows, Linux and macOS; Android requires host process adaptation",
+      "protocol": "Git working repository and SDK process adapter",
+      "normalization": "Returns directory, open, status, pull, push and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are inspected without rewriting, resetting or pulling. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work."
+    },
+    {
+      "id": "core-speech:createSpeechService",
+      "name": "createSpeechService",
+      "displayName": "createSpeechService()",
+      "kind": "function",
+      "signature": "createSpeechService({stt,tts,signal}={})",
+      "entrypoints": ["arcane-os/core/speech"],
+      "primaryImport": "arcane-os/core/speech",
+      "group": "Core native speech",
+      "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
+      "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
+      "protocol": "arcane/1 speech.status/transcribe/synthesize with speech.state/progress",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown; no engine installation or automatic provider selection"
+    },
+    {
+      "id": "core-speech:default",
+      "name": "default",
+      "displayName": "createSpeechService default export",
+      "kind": "function",
+      "signature": "default as createSpeechService",
+      "entrypoints": ["arcane-os/core/speech"],
+      "primaryImport": "arcane-os/core/speech",
+      "group": "Core native speech",
+      "summary": "Default binding for the same injected-engine native speech service factory.",
+      "availability": "Node Core with host-supplied engines",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createSpeechService export"
+    },
     {
       "id": "local-ai-image:createImageRuntime",
       "name": "createImageRuntime",
@@ -4150,7 +4206,7 @@
       "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
       "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
       "protocol": "arcane-native-builder/1 windows-x64 provider",
-      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",

package/docs/reference/local-ai.md

@@ -43,14 +43,17 @@ preserved when its version cannot be established.
 
 Both public application/package schemas accept `stable-diffusion.cpp` as a
 string or runtime-record ID. Its record additionally accepts `backend`
-(`auto`, `cpu` or `metal`) and `models`, an array of `sd14` or complete model
-descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
+(`auto`, `cpu` or `metal`) and `models`, an array of `sd14`, `flux2-klein-4b` or
+complete model descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
 selects `auto`; omitted models leaves model selection empty. Windows/Linux
 distribution defaults use CPU; the selected universal Mac archive supports
 Metal with CPU fallback. Installation obtains the upstream library and its
 managed `koffi@3.3.2` binding, without installing a model. Complete model
 descriptors keep their resources, context, defaults and operations separate.
 See [image selection and model preparation](local-image-generation.md#selection-and-model-assets).
+The [FLUX.2 Klein 4B guide](local-image-flux.md) describes its diffusion model,
+VAE and Qwen text-conditioning resources, four-step defaults and `txt2img`
+operation. Each model retains its own supported operation set.
 
 `llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router

package/docs/reference/local-image-flux.md

@@ -45,7 +45,7 @@ model pipeline, rather than three independent image generators.
 | Native role | Resource | Purpose |
 | --- | --- | --- |
 | `diffusion_model` | [flux-2-klein-4b.safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B/resolve/e7b7dc27f91deacad38e78976d1f2b499d76a294/flux-2-klein-4b.safetensors) | Distilled image generation model. |
-| `vae` | [full_encoder_small_decoder.safetensors](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/resolve/a3efc24f613ef42d9428af62fdbd6f5fd8856c4a/full_encoder_small_decoder.safetensors) | Complete image encoder and the smaller FLUX.2 decoder. |
+| `vae` | [`full_encoder_small_decoder.safetensors`](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/resolve/a3efc24f613ef42d9428af62fdbd6f5fd8856c4a/full_encoder_small_decoder.safetensors) | Complete image encoder and the smaller FLUX.2 decoder. |
 | `llm` | [Qwen3-4B-Q8_0.gguf](https://huggingface.co/Qwen/Qwen3-4B-GGUF/resolve/bc640142c66e1fdd12af0bd68f40445458f3869b/Qwen3-4B-Q8_0.gguf) | Qwen3-4B text conditioning inside the image engine. |
 
 The selected upstream records identify these resources as Apache-2.0. The

package/docs/reference/local-image-generation.md

@@ -41,6 +41,12 @@ model's resource metadata; runtime installation does not independently download
 or bundle model files. The shared model asset owner prepares selected browser
 assets and supplies a Core working projection for native path-based loading.
 
+`flux2-klein-4b` selects the three-resource distilled FLUX.2 Klein definition.
+Its [family guide](local-image-flux.md) covers diffusion/VAE/Qwen preparation,
+four-step defaults and the advertised `txt2img` operation. Keep each model's
+supported operations distinct: selecting FLUX does not enable reference-image
+editing or imply the same input path as SD1.4 img2img.
+
 The first published distribution path selects CPU on Windows and Linux.
 On macOS, `auto` selects the same upstream universal runtime's built-in Metal
 backend, with CPU fallback; explicit `cpu` remains available. A caller-supplied

package/docs/reference/local-image-sdxl.md

@@ -0,0 +1,139 @@
+# SDXL Base 1.0 through Core
+
+The `sdxl-base-1.0` model definition selects Stability AI's complete SDXL Base
+1.0 checkpoint for text-to-image generation through the shared
+[local image runtime](local-image-generation.md). Applications supply their
+own complete prompts and own the resulting images and saved associations.
+The model uses the shared retained native context, progress, cancellation
+and complete PNG result contract.
+
+## Model selection
+
+Select this runtime record under `native.localAI` in `arcane-app.json`, or
+the corresponding package projection's `localAI` record:
+
+```json
+{
+    "runtimes": [
+        {
+            "id": "stable-diffusion.cpp",
+            "version": "master-929-3f8527a",
+            "backend": "auto",
+            "models": ["sdxl-base-1.0"]
+        }
+    ]
+}
+```
+
+The built-in ID supplies the cohesive `SDXL_BASE_1_0_MODEL` definition from
+`src/local-ai/image-models/sdxl.mjs`. The shared service exposes its resource
+metadata through `image.status` and `images.inspect()`.
+
+Backend discovery, accelerated-device selection and CPU fallback belong to
+the shared runtime. This model definition leaves `context` empty and adds no
+device or precision override. Available acceleration depends on the selected
+runtime distribution; see the shared guide's platform availability. Model
+selection alone does not establish actual execution on any device.
+
+## Prepare the checkpoint and generate an image
+
+The single `model` resource is the official
+[sd_xl_base_1.0.safetensors checkpoint](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors)
+at revision `462165984030d82259a11f4367a4eed129e94a7b`. It includes the text
+encoders, denoiser and original VAE. Standalone base generation uses this one
+resource; a refiner, separate VAE, LoRA or Python converter is unnecessary for
+this selection. The upstream model carries the
+[CreativeML Open RAIL++-M license](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/462165984030d82259a11f4367a4eed129e94a7b/LICENSE.md).
+
+The existing DBOPFS model store owns the authoritative download. The shared
+[model-assets service](model-assets.md) prepares complete native working files
+when the application loads the model. Installing the native runtime does not
+download a second model copy.
+
+This example extends the shared generation guide. It uses an existing `images`
+accessor, DBOPFS-backed `modelStore`, application-selected `workingDirectory`
+and request `signal`:
+
+```javascript
+import {createBrowserModelSource} from 'arcane-os/ai/browser-wasm';
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+
+const selected = (await images.inspect({signal})).models.find(
+    function selectedSDXL(model) {
+        return model.id === 'sdxl-base-1.0';
+    }
+);
+const resource = selected.resources.model;
+const source = createBrowserModelSource({
+    id: selected.id,
+    files: [{name: resource.filename, url: resource.url}]
+});
+const stored = await modelStore.ensure(source, {signal});
+const projection = await prepareCoreModelAssets({
+    workingDirectory,
+    members: source.files.map(function workingMember(member, index) {
+        return {path: member.name, file: stored.files[index]};
+    }),
+    signal
+});
+
+try {
+    await images.load({
+        model: selected.id,
+        assetProjectionId: projection.id,
+        resourcePaths: {model: resource.filename},
+        signal
+    });
+} finally {
+    await projection.release();
+}
+
+const result = await images.generate({
+    model: selected.id,
+    prompt: 'An octopus librarian shelving tiny books inside a glass submarine.',
+    signal
+});
+// Display result.images using the shared guide's Blob preview example.
+```
+
+Change the prompt to request another scene. The model defaults to a
+1024-by-1024 canvas; pass `parameters: {width, height}` to select other native
+dimensions. Display or save every returned image using its actual width and
+height. Each result contains the complete PNG Blob.
+
+Successful loading retains the working projection in the native model owner.
+Releasing the caller's preparation handle preserves that native retain.
+Repeated generation reuses the loaded context; unload it when the application
+no longer needs it. Follow the shared lifecycle contract for request
+cancellation, state subscriptions, unloading and accessor closure.
+
+## Defaults and operation scope
+
+Only canvas dimensions are model-specific defaults here. Sampling parameters
+remain owned by the selected native engine and can be supplied through
+`parameters.sample_params`. At `master-929-3f8527a`, SDXL resolves the native
+default sampler to Euler A and scheduler to discrete, with 20 steps and CFG 7.
+These are native defaults; Stability AI's separate base-plus-refiner example
+and Python pipeline have their own sampling configuration.
+
+The selected engine has an explicit path for SDXL's embedded original VAE,
+including its native convolution scaling. The model definition leaves that
+treatment with the engine and supplies no guessed weight-type override or
+separate VAE checkpoint. Output quality, speed and device behavior depend on
+the actual selected runtime and generation parameters.
+
+The SDK forwards the complete caller prompt to the native API. The engine
+applies its own text conditioning and prompt-weighting syntax; see the shared
+guide for native string-boundary limitations. The SDK adds no avatar wording,
+style instructions or application-specific content.
+
+This definition advertises `txt2img`. Whole-image editing, masked editing and
+reference-image editing are separate operations with their own model and
+runtime requirements. This base selection does not advertise those operations.
+
+The model resource and standalone use follow the
+[official model card](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/462165984030d82259a11f4367a4eed129e94a7b/README.md).
+Native defaults and embedded-VAE behavior follow the selected engine's
+[request implementation](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/pipeline/request.cpp),
+[parameter initialization](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/stable-diffusion.cpp)
+and [model construction](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/pipeline/model_builders.cpp).