arcane-os 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.63.0
+
+- Add the approved FLUX.2 Klein 4B text-to-image model descriptor to the
+  existing retained local image runtime, with its separate diffusion, VAE
+  and text-encoder resources and four-step Euler defaults. Applications keep
+  their model choice, complete prompts and image persistence.
+- Name assembled Windows launchers from the application display name, with a
+  matching executable configuration and manifest-selected launch path.
+  Preserve supported spaces, case and Unicode, existing generic artifacts,
+  icon embedding and the unchanged shared host archive.
+- Add `createSpeechService({stt, tts, signal})` through `arcane-os/core/speech`
+  for independently supplied native engines, immediate service registration,
+  sticky role state, complete requests/results, cancellation and joined close.
+  This service does not install or select a speech engine.
+- Preserve existing image generation/editing and native host behavior. No
+  additional GPU setup, SDXL, Whisper engine, Kokoro/Sherpa adoption or browser
+  AI native-speech readiness correction is included in this increment.
+
 ## 0.62.0
 
 - Add whole-image PNG editing through the existing local image runtime, Core

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.62.0` SDK contract. Development applications declare
+This checkout defines the `0.63.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/docs/reference/README.md

@@ -55,6 +55,9 @@ alone does not make bare module names resolve in a browser.
 | Cancel one Core speech synthesis request without changing its payload | [Speech request lifetime](core-client.md#events-and-request-lifetime) and [Core facade](sdk-api.md#createcorefacade) |
 | 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) |
+| 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) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
@@ -223,6 +226,8 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | 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 application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
 | Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
+| Generate local images from complete prompts and selected model resources | [`arcane-os/local-ai/image`, `arcane-os/ai/core-image`](local-image-generation.md) | Prepared native image runtime; browser access requires its Core service. CPU Windows/Linux and Mac Metal/CPU paths have distinct actual host requirements. |
+| Supply complete stored model members to a native engine | [`arcane-os/ai/core-model-assets`, `arcane-os/core/model-assets`](model-assets.md) | Available Core service; DBOPFS originals stay authoritative while native owners retain working files. |
 | 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. |

package/docs/reference/cli.md

@@ -49,7 +49,7 @@ meaning and cardinality rules:
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--apps-root` | `.` or `apps` | `new`, `init`; standalone setup defaults to the repository root. |
 | `--sdk-runtime-source` | SDK checkout directory | `dev` only; maps live SDK source through the selected browser destinations for that server process. |
-| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama` and/or `onnx` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
+| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama`, `onnx` and/or `stable-diffusion.cpp` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
@@ -375,6 +375,10 @@ arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file
 reuse them. Available services and executables are reused; missing runtimes
 are installed inside the application while serving starts independently.
 Applications choose their model files and optional browser Core connection.
+`--local-ai stable-diffusion.cpp` prepares the selected native image runtime;
+configure its `models` separately in the application's runtime record.
+The [image service](local-image-generation.md) reports installation and model
+readiness independently, with complete PNG results and explicit cancellation.
 See [local AI through Core](local-ai.md) for configuration and native bundling.
 
 ### Lifecycle

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

@@ -248,8 +248,9 @@ to the artifact root. Only the explicitly configured entry imports
 `createLocalAIService` from `arcane-os/core/local-ai`. It resolves those bundled
 locations against the installed artifact and supplies them in the launch
 context's `runtimes` array, alongside `appRoot`, before applying explicit launch
-configuration. It passes the complete authored `native.localAI` record to the
-factory. Applications without that selection have no generated local-AI import
+configuration. It passes chat/ONNX requirements to that factory and routes
+selected image requirements to their separate service as described below.
+Applications without that selection have no generated local-AI import
 or service. Availability of a particular engine belongs to the selected
 local-AI installer and service; a generic ONNX runtime is not a speech model.
 
@@ -260,6 +261,25 @@ service exposes retained worker sessions through `onnx.load/run/unload/status`;
 model files remain caller-selected application resources. See
 [native ONNX sessions](local-ai.md#native-onnx-sessions).
 
+Selected `stable-diffusion.cpp` additionally composes
+`createLocalImageService` from `arcane-os/core/image` and one shared
+`createModelAssetService` from `arcane-os/core/model-assets`. The image factory
+receives the full authored selection plus that same model-assets instance.
+Library, Koffi binding and variant paths resolve from the artifact root;
+ordinary browser imports use `arcane-os/ai/core-image` and
+`arcane-os/ai/core-model-assets` through the managed import map.
+
+The runtime bundle preserves the complete selected native distribution and
+binding tree. It does not load or download a model. Original model URL
+descriptors remain available for preparation after launch; runtime-contained
+model paths relocate with the artifact. An external native working path
+reports its portability incompatibility. Supply those files through the
+application's native resources or the shared
+[stored-model projection](model-assets.md). Native use retains that projection
+until actual unload or shutdown completes. See
+[local image generation](local-image-generation.md) for selection, complete
+results and CPU/Metal platform boundaries.
+
 ## Windows executable
 
 The ordinary application command is:

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

@@ -1,17 +1,115 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.57.0",
+  "sdkVersion": "0.62.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 267,
+  "memberCount": 274,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-image:createImageRuntime",
+      "name": "createImageRuntime",
+      "displayName": "createImageRuntime()",
+      "kind": "function",
+      "signature": "createImageRuntime({libraryPath,bindingModulePath,variants=[],models=[],backend='auto',signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/image"],
+      "primaryImport": "arcane-os/local-ai/image",
+      "group": "Core local images",
+      "summary": "Retains selected stable-diffusion.cpp generation and PNG img2img execution in a shared native worker and returns complete PNG results.",
+      "availability": "Node with prepared upstream image library, Koffi binding and caller-selected model resources",
+      "protocol": "Shared per-library worker/context lifetime with ordered native operations and replaying state",
+      "normalization": "Returns load/generate/edit/unload/current/subscribe/close; edit copies complete PNG input at acceptance and takes explicit strength; prompts remain complete and cancellation/close join native completion before resource release"
+    },
+    {
+      "id": "core-image:createCoreImageRuntime",
+      "name": "createCoreImageRuntime",
+      "displayName": "createCoreImageRuntime()",
+      "kind": "function",
+      "signature": "createCoreImageRuntime({client=getInstalledCoreClient(),signal,onEvent}={})",
+      "entrypoints": ["arcane-os/ai/core-image"],
+      "primaryImport": "arcane-os/ai/core-image",
+      "group": "Core local images",
+      "summary": "Uses an available Core image service for generation and original-PNG editing with synchronous Thinking acknowledgement, lifecycle replay and complete PNG Blobs.",
+      "availability": "Browser/native WebView with an available Core image service; construction opens no connection or model",
+      "protocol": "arcane/1 image.status/load/generate/edit/unload and image.state/progress",
+      "normalization": "Returns load/generate/edit/unload/inspect/current/subscribe/close; edit preserves the complete original PNG Blob/File through transport with explicit strength; timeoutMs is zero, close cancels only this accessor and explicit unload owns the shared model"
+    },
+    {
+      "id": "core-image-service:createLocalImageService",
+      "name": "createLocalImageService",
+      "displayName": "createLocalImageService()",
+      "kind": "function",
+      "signature": "createLocalImageService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,modelAssets}={})",
+      "entrypoints": ["arcane-os/core/image"],
+      "primaryImport": "arcane-os/core/image",
+      "group": "Core local images",
+      "summary": "Composes independent image-runtime preparation, retained native model use and complete PNG transport as a Core service.",
+      "availability": "Node Core with selected stable-diffusion.cpp configuration and prepared runtime or preparation callback",
+      "protocol": "arcane/1 image lifecycle, generate/edit and progress; base64 framing only at complete PNG input/result transport boundaries",
+      "normalization": "Status remains callable during preparation; shared model-assets handles remain retained through actual model unload, worker completion and disposal"
+    },
+    {
+      "id": "core-image-service:default",
+      "name": "default",
+      "displayName": "createLocalImageService default export",
+      "kind": "function",
+      "signature": "default as createLocalImageService",
+      "entrypoints": ["arcane-os/core/image"],
+      "primaryImport": "arcane-os/core/image",
+      "group": "Core local images",
+      "summary": "Default binding for the same native image service factory.",
+      "availability": "Node Core runtime",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createLocalImageService export"
+    },
+    {
+      "id": "core-model-assets:prepareCoreModelAssets",
+      "name": "prepareCoreModelAssets",
+      "displayName": "prepareCoreModelAssets()",
+      "kind": "function",
+      "signature": "async prepareCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,signal,onProgress}={})",
+      "entrypoints": ["arcane-os/ai/core-model-assets"],
+      "primaryImport": "arcane-os/ai/core-model-assets",
+      "group": "Core model assets",
+      "summary": "Projects complete caller-owned Blob/File members through Core into native working files without changing their durable store.",
+      "availability": "Browser with an available model-assets Core service and complete selected members",
+      "protocol": "arcane/1 modelAssets open/write/complete/release operations with transport-local base64",
+      "normalization": "Returns id/directory/ordered members/release; independent files transfer concurrently, each file writes in order, and cancellation joins cleanup"
+    },
+    {
+      "id": "core-model-assets-service:createModelAssetService",
+      "name": "createModelAssetService",
+      "displayName": "createModelAssetService()",
+      "kind": "function",
+      "signature": "createModelAssetService({appRoot=process.cwd()}={})",
+      "entrypoints": ["arcane-os/core/model-assets"],
+      "primaryImport": "arcane-os/core/model-assets",
+      "group": "Core model assets",
+      "summary": "Owns selected native working-file projections and engine retain handles while original stored model files remain unchanged.",
+      "availability": "Node Core with an application-selected working directory",
+      "protocol": "arcane/1 modelAssets.open/write/complete/release/status and modelAssets.state",
+      "normalization": "Returns current/retain/dispose and Core service lifecycle; final native release joins writes and closes before deleting only its working projection"
+    },
+    {
+      "id": "core-model-assets-service:default",
+      "name": "default",
+      "displayName": "createModelAssetService default export",
+      "kind": "function",
+      "signature": "default as createModelAssetService",
+      "entrypoints": ["arcane-os/core/model-assets"],
+      "primaryImport": "arcane-os/core/model-assets",
+      "group": "Core model assets",
+      "summary": "Default binding for the same native working-file service factory.",
+      "availability": "Node Core runtime",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createModelAssetService export"
+    },
     {
       "id": "local-ai-onnx:createONNXRuntime",
       "name": "createONNXRuntime",
@@ -129,14 +227,14 @@
       "name": "createLocalAIService",
       "displayName": "createLocalAIService()",
       "kind": "function",
-      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare}={})",
       "entrypoints": ["arcane-os/core/local-ai"],
       "primaryImport": "arcane-os/core/local-ai",
       "group": "Core local AI",
       "summary": "Composes selected native llama.cpp, Ollama and ONNX engines as a Core service with retained process/worker ownership and model lifecycle.",
       "availability": "Node with selected upstream runtime distributions or available configured system services",
       "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE, Ollama native HTTP/NDJSON and ONNX tensor transport",
-      "normalization": "Application-owned runtime and model requirements; independent startup, complete responses and exact owned-process cleanup"
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup; independent services, complete responses and exact owned-process cleanup"
     },
     {
       "id": "core-local-ai:default",
@@ -161,10 +259,10 @@
       "entrypoints": ["arcane-os/local-ai"],
       "primaryImport": "arcane-os/local-ai",
       "group": "Core local AI",
-      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp/Ollama distributions, ONNX npm runtime trees or NeMo libraries.",
+      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp/Ollama/image distributions, ONNX npm runtime trees or NeMo libraries.",
       "availability": "Node; upstream platform and architecture assets determine runtime availability",
-      "protocol": "Official upstream release archives or selected ONNX npm installation",
-      "normalization": "Returns absolute runtime records; shares matching concurrent installs, preserves libraries and reports failures without changing global PATH or services"
+      "protocol": "Official upstream release archives and selected ONNX/Koffi npm runtime installations",
+      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files"
     },
     {
       "id": "local-ai:bundleLocalAIRuntimes",
@@ -178,7 +276,7 @@
       "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
       "availability": "Node; supports bundling published upstream platform assets independently of the build host",
       "protocol": "Artifact-relative runtime/local-ai layout",
-      "normalization": "Returns {runtimes,files} with relative runtime records and the complete emitted inventory; model resources remain application-owned"
+      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility"
     },
     {
       "id": "root:WS",

package/docs/reference/local-ai.md

@@ -1,6 +1,7 @@
 # Local AI through Core
 
-Core owns native llama.cpp and Ollama processes and ONNX worker sessions. The browser retains its own
+Core owns native llama.cpp and Ollama processes, ONNX worker sessions and
+selected local image generation. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
@@ -20,7 +21,8 @@ Existing native fields remain alongside this record:
   "runtimes": [
     {"id": "llama.cpp"},
     {"id": "ollama"},
-    {"id": "onnx"}
+    {"id": "onnx"},
+    {"id": "stable-diffusion.cpp", "backend": "auto", "models": ["sd14"]}
   ],
   "llamaCpp": {
     "modelsDirectory": "models/llama"
@@ -34,11 +36,22 @@ Existing native fields remain alongside this record:
 Each runtime requirement accepts `id`, optional upstream `version`, and an
 optional runtime archive `url`. ONNX resolves its official npm package or an
 explicitly supplied package archive. A string runtime ID is also accepted.
-Omitting the version allows reuse of an available runtime. Explicit versions
+For chat runtimes, omitting the version allows reuse of an available runtime. Explicit versions
 select that upstream distribution; an existing service must match the requested
 version before it is reused. A service occupying the selected address is
 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
+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).
+
 `llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
 mode. Paths resolve from the application root. Ollama accepts `url`,
@@ -55,6 +68,10 @@ arcane dev --local-ai llama.cpp,ollama,onnx
 
 The option adds those runtime requirements to the authored application
 configuration. Subsequent `arcane dev` runs reuse the saved requirements.
+`--local-ai stable-diffusion.cpp` also selects image runtime preparation; the
+application selects its `models` in the runtime record before requesting a
+load or generation. The development owner composes separate image and
+model-assets services alongside the existing chat/ONNX service.
 Development checks selected endpoints and existing executable paths, then
 installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
 Runtime preparation runs alongside HTTP serving. Browser rendering continues
@@ -89,9 +106,12 @@ processes. An already running external service remains running.
 
 `developApplication()` returns its usual server handle and an optional `localAI`
 handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
-means installation and Core composition completed. Runtime/model readiness is
-reported separately by Core status and lifecycle events. Preparation failures
-remain on that promise and the operation event stream.
+means Core composition has started, not that installation or a selected model
+is ready. Runtime preparation continues at each owning service. `current()`
+includes separate `core`, `localAI` and optional `image` state; image status
+remains callable during preparation. Composition failures reject `ready`;
+later service preparation failures remain on Core lifecycle and diagnostic
+events. Page rendering waits for neither.
 
 ## Core service
 
@@ -112,6 +132,14 @@ application. `current()` returns the current snapshot without starting another
 process. The service starts each selected runtime independently, retains its
 process between requests, and joins cleanup during disposal.
 
+Optional `prepare({signal,onEvent})` returns resolved runtime records before
+this service starts its selected engines. The managed development owner uses
+that callback without delaying the HTTP listener or independent services.
+This factory accepts chat/ONNX requirements; the separate
+[`createLocalImageService()`](local-image-generation.md#core-service-and-transport)
+owns image requirements. The development and generated native composition
+split the shared application record accordingly.
+
 `localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
 `ollama` and `models.ollama` catalog fields. Runtime records distinguish
 `installed`, `available`, `state`, `models`, ownership and errors. A listening
@@ -305,11 +333,24 @@ archive in this installer.
 
 Ensure returns absolute `{id,version,platform,architecture,root}` records.
 Server runtimes also include `executable`; ONNX includes `modulePath` pointing
-to its public package entry. Bundle returns `{runtimes,files}`,
+to its public package entry. Image records include `libraryPath`,
+`bindingModulePath`, requested `backend`, installed `variants` and selected
+`models` metadata. Variant records carry backend, runtime root and library path.
+Bundle returns `{runtimes,files}`,
 with artifact-relative runtime paths and a complete emitted file inventory.
 Bundling requires a fresh native staging destination, preserving existing
 completed outputs.
 
+Image assembly preserves the complete runtime/binding tree and relocates
+library, binding and variant paths into the artifact. It retains original
+model URL descriptors for preparation after launch. A model file already
+inside the runtime tree becomes artifact-relative; an external native working
+path reports its portability incompatibility. Use the explicit native-resource
+workflow or [model-assets preparation](model-assets.md) for those files.
+Model acquisition, context loading and inference remain separate from runtime
+assembly. Platform availability depends on the selected upstream archive;
+this contract does not establish execution on every supported host.
+
 ### NeMo Speech library runtime
 
 The runtime helpers also accept `{id: 'nemo-speech', version: '0.2.0'}` to

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

@@ -0,0 +1,154 @@
+# FLUX.2 Klein 4B through Core
+
+The `flux2-klein-4b` model definition selects distilled FLUX.2 Klein 4B for
+text-to-image generation through the shared
+[local image runtime](local-image-generation.md). It uses the same retained
+native context, progress, cancellation and complete PNG result contract as
+other selected image models. Applications own prompts, image associations and
+saved results.
+
+## 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": ["flux2-klein-4b"]
+        }
+    ]
+}
+```
+
+The definition is a single `FLUX2_KLEIN_4B_MODEL` record in
+`src/local-ai/image-models/flux.mjs`. The built-in model ID supplies that record
+through normal runtime configuration; the shared service exposes its resource
+metadata through `image.status` and `images.inspect()`.
+
+Backend selection belongs to the shared runtime. This definition adds no CPU
+offload setting or device override. `auto` uses the available runtime's
+accelerated backend with CPU fallback; actual support depends on the installed
+runtime distribution. See the shared guide for platform distribution
+availability. Selecting the model does not establish that it has loaded or run
+on a GPU, CPU or NPU.
+
+## Required model resources
+
+Prepare all three resources together. They are complementary parts of one
+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. |
+| `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
+engine supplies its embedded Qwen tokenizer. This definition needs no separate
+tokenizer download, chat server or LoRA. The full encoder in the selected VAE
+also retains the model's image-encoding capability; a decoder-only file is a
+different resource.
+
+The existing DBOPFS model store owns authoritative model files and resumable
+downloads. The shared [model-assets service](model-assets.md) prepares complete
+native working files. Runtime installation does not download another copy of
+these models. Resource roles map to the exact filenames returned by that
+preparation.
+
+The following 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 selectedKlein(model) {
+        return model.id === 'flux2-klein-4b';
+    }
+);
+const resources = Object.entries(selected.resources);
+const source = createBrowserModelSource({
+    id: selected.id,
+    files: resources.map(function modelFile([role, resource]) {
+        return {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: Object.fromEntries(
+            resources.map(function nativeRole([role, resource]) {
+                return [role, resource.filename];
+            })
+        ),
+        signal
+    });
+} finally {
+    await projection.release();
+}
+
+const result = await images.generate({
+    model: selected.id,
+    prompt: 'A dignified raccoon astronaut watering a moon cactus in a teacup.',
+    parameters: {width: 768, height: 768},
+    signal
+});
+// Display result.images using the shared guide's Blob preview example.
+```
+
+Change the prompt to request another scene and the dimensions to select its
+canvas. Successful loading retains the working projection inside the native
+model owner; releasing the caller's preparation handle leaves that native
+retain intact. Repeated generation reuses the loaded context. Explicitly
+unload it when the application no longer needs it, following the shared
+lifecycle contract.
+
+## Defaults and model behavior
+
+The definition supplies four sampling steps, the Euler sampler and
+`sample_params.guidance.txt_cfg: 1`. Omitted native options retain their native
+initializer defaults, including automatic FLUX.2 scheduler selection. These
+settings belong to the distilled 4B checkpoint; the separate Klein base and
+9B variants have their own model requirements.
+
+The native default canvas is 512 by 512. Klein's native preparation aligns
+dimensions upward to multiples of 16; use the returned image dimensions when
+displaying or saving results. The example already selects aligned dimensions.
+At the default CFG value of 1, the native text-to-image path does not apply
+negative-prompt conditioning.
+
+The SDK forwards the caller's complete prompt to the native API. The engine
+then applies its prompt-weighting syntax and Qwen conditioning format.
+Parentheses and brackets can affect weighting. The selected native API has no
+public switch for literal text conditioning, so exact SDK transport does not
+imply literal interpretation by the model. The shared guide describes inputs
+that cannot pass unchanged through its native C-string boundary.
+
+This definition advertises `txt2img`. The upstream Klein model also supports
+reference-image editing, while the SDK's separate whole-image `img2img`
+operation uses a different input path. Reference editing becomes an SDK
+capability when the shared runtime implements its reference-image dispatch;
+selecting this model alone does not add that operation.
+
+These settings and resource roles follow the
+[tagged FLUX.2 instructions](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/docs/flux2.md),
+the [official Klein model](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B),
+the [official small decoder](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder)
+and the [official Qwen model files](https://huggingface.co/Qwen/Qwen3-4B-GGUF).

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

@@ -5,6 +5,12 @@ retained native context. The browser uses Core for model lifecycle and complete
 PNG results. Applications own image prompts, style choices, character identity,
 associations and saved results.
 
+The same public runtime also exposes whole-image `edit()` for an original PNG,
+complete prompt and explicit strength. It reuses this model/context lifecycle;
+applications retain the original and choose whether to save the separate
+result. See [local image editing](local-image-editing.md) for supported inputs,
+lossless transport, native preprocessing and cancellation.
+
 Runtime installation, model asset preparation, model loading and image
 generation are separate operations. The service starts promptly and retains
 runtime preparation in the background. `image.status` remains callable during