arcane-os 0.62.0 → 0.64.0

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

@@ -1,17 +1,171 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.57.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": 267,
+  "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",
+      "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 +283,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 +315,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 +332,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",
@@ -4052,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

@@ -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,25 @@ 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`, `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
 mode. Paths resolve from the application root. Ollama accepts `url`,
@@ -55,6 +71,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 +109,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 +135,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 +336,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
@@ -35,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