arcane-os 0.88.1 → 0.89.0

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

@@ -149,6 +149,37 @@ same owner with an origin-root URL, including on nested pages. It does not creat
 a second event implementation. A plain file-URL launch without this host mapping
 is not the native serving contract. No host is launched during packaging.
 
+## App-owned runtime entry
+
+The generated `runtime/arcane-core.mjs` also accepts
+`--arcane-app-entry <app-relative-module>`. This explicit mode imports the
+selected file from the artifact's `app/` directory before ordinary launch-context
+or service initialization. It preserves the complete original `process.argv`
+and converts the native path to a file URL without treating filename characters
+as URL query or fragment syntax. Missing/empty selections and actual import
+failures propagate; there is no fallback to ordinary Core.
+
+Use the existing Windows `runtime/ArcaneCore.exe` with that flag and module path
+directly. On macOS, use bundled `runtime/node` with `runtime/arcane-core.mjs`
+followed by the flag and module path. Portable payloads use the host's supported
+Node executable with that same generated entry. The macOS artifact root is its
+`.app/Contents/Resources` directory. This mode needs no new executable, SEA
+loader, GUI launcher, or copied runtime.
+
+The app includes the module and its complete source closure through
+[`package.nativeResources`](#native-only-application-resources). The imported
+entry starts its own top-level work, not an `import.meta.main`-guarded entry or
+an automatically invoked export. It owns any explicit launch-context read,
+application services, MCP tools, signals and shutdown. No ordinary Core host,
+shared-host bridge, manifest services, model startup or Core pipe framing is
+started by this branch. Static SDK definition imports remain available; the
+ordinary parallel service imports and host lifetime stay unchanged when the
+flag is absent.
+
+For complete client command arrays, optional `--arcane-launch-config` handling,
+and MCP STDIO lifetime ownership, see
+[launch from a native package](mcp-stdio.md#launch-from-a-native-package).
+
 ## Explicit application services
 
 For the ordinary SDK build command, select native service modules in the
@@ -489,7 +520,7 @@ forced process termination.
 
 ### Initial native window size
 
-An application can select its initial client area and resizing behavior in
+An application can select its initial client area, resizing behavior and state in
 `arcane-app.json`, independently of its page layout:
 
 ```json
@@ -499,15 +530,17 @@ An application can select its initial client area and resizing behavior in
     "icon": "img/icon.png",
     "order": 100,
     "bundledApps": [],
-    "window": {"width": 1280, "height": 800, "resizable": true}
+    "window": {"width": 1280, "height": 800, "resizable": true, "state": "normal"}
   }
 }
 ```
 
 This is the `native` portion of the existing app descriptor. Each `window`
 member is optional. `width` and `height` are positive integral client dimensions
-in logical pixels at 96 DPI; `resizable` is a boolean. Omitting a member retains
-the host's existing choice, and omitting `window` preserves existing startup.
+in logical pixels at 96 DPI; `resizable` is a boolean. Optional `state` is
+`normal`, `maximized`, or `fullscreen`. These example dimensions are an explicit
+application choice, not SDK-wide defaults. Omitting a member retains the host's
+existing choice, and omitting `window` preserves existing startup.
 The native registry projection preserves the record; the browser package
 projection gains no window controls. Portable and Windows assembly copy the
 record to `arcane-native.json` as `window`, without changing page or service
@@ -517,16 +550,30 @@ The matching Windows host applies the dimensions once on initial load, using
 the display DPI and fitting the outer window within the selected monitor's
 usable work area. This fit does not impose a persistent maximum size. Explicit
 `resizable:false` uses a fixed frame and disables the maximize control; `true`
-permits ordinary resizing and maximizing. Later app/user resizing remains
-untouched. A composing launcher's `Load` handler runs after this initial sizing
-and can restore its own saved window state. The SDK adds no saved-bounds store.
+permits ordinary resizing and maximizing. The selected initial state is applied
+after this normal-window sizing, so those normal bounds remain available when
+returning from maximized or fullscreen. Fullscreen uses a borderless window at
+the selected monitor's full bounds, including the taskbar area, without setting
+TopMost or requesting activation. Returning to normal restores the retained
+normal bounds and original frame, minimize/maximize and control-box settings.
+Selecting maximized from fullscreen restores them before maximizing.
+
+Later app/user resizing remains untouched. A composing launcher's `Load` handler
+runs after the initial sizing and optional state selection. Applications can
+read or change their own window through
+[`Arcane.window.state()` and `setState({state})`](core-client.md#current-window-state).
+The application's saved Settings and their application remain application-owned;
+the SDK adds no saved-state or saved-bounds store and does not delay rendering
+for those settings. The window's profile, origin and Core lifetime are unchanged.
 
 Direct Windows host composition uses nullable `ArcaneHostOptions` members
-`InitialClientWidth`, `InitialClientHeight`, and `Resizable` with the same
-semantics. Older precompiled Windows hosts do not read these options; use the
+`InitialClientWidth`, `InitialClientHeight`, `Resizable`, and optional string
+`InitialWindowState` with the same semantics. Older precompiled Windows hosts
+do not read these options; use the
 matching SDK host archive when rebuilding an application. The portable record
 is available to platform adapters; this addition implements its Windows host
-behavior and leaves window sizing on other platforms unchanged.
+behavior and leaves window sizing/state on other platforms unchanged. The current
+other-platform hosts do not implement this state selection.
 
 ### Application icon and window colors
 

package/docs/reference/core-repositories.md

@@ -47,7 +47,7 @@ const status = await repository.status({signal});
 await repository.close();
 ```
 
-`createRepositoryWorkspace({name,directory,dataRoot,remote,branch,longPaths,gitIdentity,onEvent,run}={})`
+`createRepositoryWorkspace({name,directory,dataRoot,remote,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run}={})`
 returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. The `directory`
 property is the absolute selected working path.
 
@@ -68,6 +68,10 @@ property is the absolute selected working path.
   writes that choice to the new repository before its first checkout. Omission
   leaves Git's configuration unchanged. The option does not rewrite an existing
   checkout, change a global setting, or alter non-Windows clone commands.
+- Optional `cloneIdentity:{name?,email?}` persists explicitly selected author
+  fields in a newly cloned repository's local Git configuration. Omitted fields
+  keep Git's ordinary inheritance; existing checkouts retain their configuration.
+  See [clone-local author selection](#clone-local-author-selection).
 - `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,
@@ -304,8 +308,8 @@ Each supplied name/email becomes command-local `-c user.name=...` or
 `GIT_COMMITTER_*` fields. Those selected fields take precedence over inherited
 author/committer settings and environment values; omitted fields, dates and
 unrelated environment remain inherited. Git retains its ordinary commit
-identity formatting and may reject an unusable identity. The SDK changes
-neither `process.env` nor global/local Git files.
+identity formatting and may reject an unusable identity. This command-local
+selection changes neither `process.env` nor global/local Git files.
 
 `username` supplies only command-local `credential.username`. Git's existing
 credential helper and remote protocol still own actual authentication. A
@@ -322,6 +326,46 @@ fetch. Existing arguments, content, output, errors, queue and cancellation
 semantics remain unchanged. Other repository helpers and CLI cwd defaults keep
 their existing behavior.
 
+### Clone-local author selection
+
+`createRepositoryWorkspace` also accepts `cloneIdentity:{name?,email?}` when the
+application wants its explicit selection retained by a newly owned clone:
+
+```javascript
+const repository = createRepositoryWorkspace({
+    name: 'moon-cheese-dispatches',
+    remote: applicationConnection.remote,
+    cloneIdentity: {name: 'Moon Dispatcher', email: 'moon@example.invalid'}
+});
+await repository.open({signal});
+```
+
+Each supplied field becomes `clone --config user.name=<name>` or
+`clone --config user.email=<email>`. Git writes these choices to the new local
+configuration before the initial checkout, on every supported platform. This
+adds no separate configuration command or post-clone initialization. It applies
+whenever the owner's first preparing operation needs a clone, including `write`.
+
+The exact strings are captured during I/O-free construction. Empty strings are
+explicit values; omitted or `undefined` fields add no setting, preserving Git's
+global inheritance, includes and any template configuration. Later caller edits
+do not alter an accepted owner. Non-string fields, NUL and text that the native
+process transport cannot represent report `TypeError` instead of changing input.
+Git retains ordinary configuration precedence, author formatting and failures.
+
+An existing checkout is never reconfigured by `cloneIdentity`, even when it is
+supplied. Changing or omitting the selection on a later owner does not remove a
+previously stored local setting. This option changes no global configuration,
+credentials, username selection, branch or remote. A failed or cancelled clone
+retains its actual diagnostics and any partial directory for the caller.
+
+`gitIdentity` remains the separate command-local selection described above.
+When both options are supplied, `cloneIdentity` selects the new clone's saved
+name/email while `gitIdentity` controls the selected child commands and their
+author/committer environment. Application defaults and per-repository choices
+remain application-owned. Neither option identifies the authenticated GitHub
+account or establishes who submitted a historical record.
+
 ## Write, commit and push selected text
 
 ```javascript

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.87.0",
+  "sdkVersion": "0.88.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -94,7 +94,7 @@
       "summary": "Connects to one explicit running native window for background document inspection, viewport capture, targeted DOM actions, fixed keys and Normal-window client resizing.",
       "availability": "Node local IPC on Windows, Linux and macOS; the current window adapter is Windows WebView2, with other native adapters unavailable",
       "protocol": "arcane/1 app.control.status, app.control.inspect, app.control.capture, app.control.act, app.control.key and app.control.resize over the existing framed local connection. The window host selects native.launchContext.appControl.endpoint and preserves its existing Core child, origin, profile and lifetime; assembly requires a matching published Windows host asset.",
-      "normalization": "Returns endpoint, closed, status(options), inspect(parameters={},options), capture(parameters={},options), act(parameters,options), key(parameters,options), resize(parameters,options), and close(). Parameters pass unchanged; per-operation options preserve Core signal/timeout behavior. Status reports actual app/window/document readiness. Inspect returns complete selected DOM HTML/text and live control state with DOM-derived role/name hints, plus top-level viewport CSS dimensions/devicePixelRatio, documentHasFocus and focusPath through the active open-shadow branch; focus records are observations with null selectors, separate from the selected root's activeElement. Optional shadowPath on inspect and act is an ordered array of unique CSS host selectors through open shadow roots; selector resolves in the final root, with omitted/empty paths retaining top-level light DOM. Whole-shadow-root inspection returns complete innerHTML/textContent with null selector/state; nested shadow-host descriptors provide their full path. Frames remain descriptors and closed roots are unavailable. Capture returns mimeType image/png, complete base64 data, documentGeneration and URL for the rendered viewport. Act requires documentGeneration and one CSS selector with click, exact-string fill, exact-value select or absolute-offset scroll. Key requires documentGeneration and Tab, Enter or Space; shiftKey:true is supported only for Tab. One keyboard owner keeps each press/release pair ordered at the selected WebView's current focus. An attempted press owns a matching release even after cancellation, navigation or failure; no failed or ambiguous press is replayed. Generation checks bracket native input without atomic document binding. Resize accepts positive integral native client width/height supported by WinForms and optional documentGeneration, changes only a Normal window's ClientSize, and returns immediate previous/actual native dimensions plus the later observed CSS viewport. Native and CSS snapshots are not atomic; platform constraints may change actual dimensions. Restoration is an explicit resize using the operation's previous native dimensions; unsupported window states fail before mutation. The native document marker prevents queued DOM actions crossing replacement; cancellation before dispatch prevents execution while dispatched work is observed through completion without retry or reversal, including owned key release. Partial results remain in actual errors and complete later responses remain in host diagnostics after cancellation or disconnection. Dispatch completion does not establish application handler completion or a successful business action. close() cancels only this connection, never the application or Core. No launch, automatic reconnect, desktop activation, global input or public arbitrary evaluator. CLI inspection accepts either --selector or a complete --request JSON object; act, key and resize forward their complete --request parameter objects. See native-app-control.md for complete result fields, CLI and platform scope."
+      "normalization": "Returns endpoint, closed, status(options), inspect(parameters={},options), capture(parameters={},options), act(parameters,options), key(parameters,options), resize(parameters,options), and close(). Parameters pass unchanged; per-operation options preserve Core signal/timeout behavior. Status reports actual app/window/document readiness and window state Normal, Maximized, Minimized or Fullscreen. Inspect returns complete selected DOM HTML/text and live control state with DOM-derived role/name hints, plus top-level viewport CSS dimensions/devicePixelRatio, documentHasFocus and focusPath through the active open-shadow branch; focus records are observations with null selectors, separate from the selected root's activeElement. Optional shadowPath on inspect and act is an ordered array of unique CSS host selectors through open shadow roots; selector resolves in the final root, with omitted/empty paths retaining top-level light DOM. Whole-shadow-root inspection returns complete innerHTML/textContent with null selector/state; nested shadow-host descriptors provide their full path. Frames remain descriptors and closed roots are unavailable. Capture returns mimeType image/png, complete base64 data, documentGeneration and URL for the rendered viewport. Act requires documentGeneration and one CSS selector with click, exact-string fill, exact-value select or absolute-offset scroll. Key requires documentGeneration and Tab, Enter, Space or Escape; shiftKey:true is supported only for Tab. One keyboard owner keeps each press/release pair ordered at the selected WebView's current focus. An attempted press owns a matching release even after cancellation, navigation or failure; no failed or ambiguous press is replayed. Generation checks bracket native input without atomic document binding. Resize accepts positive integral native client width/height supported by WinForms and optional documentGeneration, changes only a Normal window's ClientSize, and returns immediate previous/actual native dimensions plus the later observed CSS viewport. Native and CSS snapshots are not atomic; platform constraints may change actual dimensions. Restoration is an explicit resize using the operation's previous native dimensions; Maximized, Minimized and Fullscreen states fail before size mutation. The native document marker prevents queued DOM actions crossing replacement; cancellation before dispatch prevents execution while dispatched work is observed through completion without retry or reversal, including owned key release. Partial results remain in actual errors and complete later responses remain in host diagnostics after cancellation or disconnection. Dispatch completion does not establish application handler completion or a successful business action. close() cancels only this connection, never the application or Core. No launch, automatic reconnect, desktop activation, global input or public arbitrary evaluator. CLI inspection accepts either --selector or a complete --request JSON object; act, key and resize forward their complete --request parameter objects. See native-app-control.md for complete result fields, CLI and platform scope."
     },
     {
       "id": "local-ai-execution-devices:createExecutionDeviceCatalog",
@@ -311,14 +311,14 @@
       "name": "createRepositoryWorkspace",
       "displayName": "createRepositoryWorkspace()",
       "kind": "function",
-      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,branch,longPaths,gitIdentity,onEvent,run=runProcess}={})",
+      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,branch,longPaths,cloneIdentity,gitIdentity,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, configuration, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are preserved. Optional longPaths captures a boolean: explicit Windows true/false supplies clone-local core.longpaths before the first checkout, persisting only in the new repository under ordinary Git configuration precedence. Omission preserves configuration; existing repositories and non-Windows clone commands remain unchanged. No global setting or migration. configuration observes the existing root, symbolic HEAD, origin URL/pushURL arrays and branch remote/merge/upstream URL arrays without clone/init/fetch, preserving unset, empty and repeated values. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. pull/push/write accept a captured target {remote,ref} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. write snapshots exact text and paths, stages/commits only literal owned paths and preserves unrelated staged files and Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes plus the supplied target. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and identity selection writes no config file."
+      "normalization": "Returns directory, open, status, configuration, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are preserved. Optional longPaths captures a boolean: explicit Windows true/false supplies clone-local core.longpaths before the first checkout, persisting only in the new repository under ordinary Git configuration precedence. Omission preserves configuration; existing repositories and non-Windows clone commands remain unchanged. No global setting or migration. configuration observes the existing root, symbolic HEAD, origin URL/pushURL arrays and branch remote/merge/upstream URL arrays without clone/init/fetch, preserving unset, empty and repeated values. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. pull/push/write accept a captured target {remote,ref} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. write snapshots exact text and paths, stages/commits only literal owned paths and preserves unrelated staged files and Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes plus the supplied target. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and identity selection writes no config file. Optional cloneIdentity captures exact name/email strings and persists only supplied fields through clone --config before the first checkout on every supported platform. Empty strings are explicit; omitted or undefined fields preserve inherited/template configuration. Existing checkouts are never reconfigured. Unrepresentable process arguments fail honestly without transforming them. This option changes no global configuration or credentials and does not identify an authenticated account; command-local gitIdentity remains independent."
     },
     {
       "id": "core-repositories:readGitIdentity",
@@ -563,14 +563,14 @@
       "name": "createCoreLocalAIProvider",
       "displayName": "createCoreLocalAIProvider()",
       "kind": "function",
-      "signature": "createCoreLocalAIProvider({client,id='llama.cpp'}={})",
+      "signature": "createCoreLocalAIProvider({client,id='llama.cpp',prepareModel}={})",
       "entrypoints": ["arcane-os/ai/core-local"],
       "primaryImport": "arcane-os/ai/core-local",
       "group": "Core local AI",
       "summary": "Browser llama.cpp provider through an explicitly connected Core, with application-owned model selection and complete response streaming.",
       "availability": "Browser with an available Core local AI service; construction installs no runtime or model",
       "protocol": "arcane-ai-provider/2 LLM lifecycle over arcane/1",
-      "normalization": "Preserves complete payloads and original parsed chunks; waits for the exact requested model and cancels on observed readiness loss. Omitted client follows installation/replacement/retirement; explicit client including null stays fixed. Inspect reports load capability separately from loaded readiness; disposal releases only an actually retained selection through its captured client. Provider/2 role state reconciles at existing operation boundaries, not through an idle state subscription."
+      "normalization": "Preserves complete payloads and original parsed chunks; load waits for the exact requested model and inference cancels on observed readiness loss. Omitted client follows installation/replacement/retirement; explicit client including null stays fixed. Optional prepareModel({selection,signal,progress}) runs at load and returns assetProjectionId, resourcePaths, executionTarget and optional release; load({selection,signal,progress,assetProjectionId,resourcePaths,executionTarget}) lets defined direct fields override preparation, including an explicit null target. Preparation release is awaited on success, failure and cancellation, including late preparation results. Inspect reports managed preparation/load capability separately from readiness. Only the current successfully completed load accepts readiness and inference; failed same-name replacement cannot reuse prior readiness. status().execution forwards complete native execution diagnostics. Unload releases the last dispatched selection only while its owning connection remains current; disposal uses its captured client. Preparation alone creates no native release ownership. Provider/2 role state reconciles at existing operation boundaries, not through an idle state subscription."
     },
     {
       "id": "core-local-ai:createLocalAIService",
@@ -584,7 +584,7 @@
       "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; optional prepare supplies installed records during this service startup. Optional executionDevices supplies a borrowed catalog to ONNX; its supplying owner retains catalog disposal responsibility. onnx.load forwards executionPreference and executionTarget with existing model-path resolution, cancellation and omitted-target behavior. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. Optional executionDevices supplies a borrowed catalog to ONNX and llama.cpp; its supplying owner retains catalog disposal responsibility. onnx.load forwards executionPreference and executionTarget with existing model-path resolution, cancellation and omitted-target behavior. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.load({model,assetProjectionId,resourcePaths,executionTarget}) retains resourcePaths.model from the existing model-assets owner through actual managed process exit. Omitted target retains the same model's selection or configured default; null requests the runtime default. Explicit Windows NVIDIA targets resolve this host's deviceId to its CUDA device identity; unsupported or unavailable selections report their actual failure without substitution. execution distinguishes requested/resolved/configured targets from observedTarget:null. Existing external listeners retain their model/device ownership and reject managed reconfiguration. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
     },
     {
       "id": "core-local-ai:default",
@@ -654,7 +654,7 @@
       "summary": "Explicit-load Laya and Julia-1 decisions with caller-selected precision, complete inputs and graph results.",
       "availability": "Browser module Workers and the selected Transformers.js backend; import/construction starts no model load",
       "protocol": "Caller-owned state/question/options rows; five-input decision graph; native Worker request/result lifecycle",
-      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged. Optional existing SDK store routes the complete selected runtime entry and actual loader resources through fetchResource outside cloned Worker configuration. Each activation materializes unchanged entry source with JavaScript MIME and retains its original configured URL for later loads; its object URL is revoked after Worker termination. Stored mode disables competing model caches, preserves complete HTTP responses and joins runtime-entry/resource cleanup before outstanding calls settle. Runtime-entry HTTP failures retain error.response. Custom stored entries must support an object URL and changed import.meta.url; native absolute dependencies and custom factory imports outside upstream preloads remain browser-owned. Omission retains direct native module and upstream model loading; no decision-result persistence or precision fallback"
+      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged. Optional existing SDK store routes actual loader resources through fetchResource outside cloned Worker configuration. By default stored activation also materializes the unchanged runtime entry as a JavaScript object URL, retains its configured URL for later loads and revokes the object URL after Worker termination. Explicit runtime.local:true instead imports same-deployment moduleUrl and wasmPaths.mjs/wasm directly, defaulting to ai/decisions-runtime installed by browserDecisions:true materialization; only those exact executable URLs bypass the model store. It disables upstream executable WASM caching/proxy and selects one WASM thread, preserving the requested inference backend. Stored mode disables competing model caches, preserves complete HTTP responses and joins resource cleanup before outstanding calls settle. Default runtime-entry HTTP failures retain error.response; custom stored entries must support an object URL and changed import.meta.url. Omission retains existing browser behavior; no decision-result persistence or precision fallback"
     },
     {
       "id": "root:acceptWebSocket",
@@ -1734,7 +1734,7 @@
       "name": "materializeInstalledSdkRuntime",
       "displayName": "materializeInstalledSdkRuntime()",
       "kind": "function",
-      "signature": "async materializeInstalledSdkRuntime({workspaceRoot,sdkPackageSource,workspaceOperationLease,signal,onEvent}={})",
+      "signature": "async materializeInstalledSdkRuntime({workspaceRoot,sdkPackageSource,browserDecisions=false,workspaceOperationLease,signal,onEvent}={})",
       "entrypoints": [
         "arcane-os"
       ],
@@ -1743,14 +1743,14 @@
       "summary": "Materializes the complete installed SDK runtime and browser runtime, then replaces semantic arcane.lock.json metadata from the actual installed dependency and package.",
       "availability": "Node",
       "protocol": "Installed SDK runtime materialization",
-      "normalization": "Complete installed runtime content and a mutable materialization result"
+      "normalization": "Complete installed runtime content and a mutable materialization result. Explicit browserDecisions:true acquires the upstream bundled Transformers.js 4.3.0 and matched ONNX Runtime 1.31.0-dev.20260914-8d85527a0 asyncify module/WASM plus licenses into arcane/sdk/ai/decisions-runtime before replacement. The optional workspaceRuntime.browserDecisions result contains directory, versions and filenames. Default false performs no optional acquisition. Progress counts completed files; signal, HTTP and observer failures abort/join acquisition and preserve the previous projection. Select the option on each refresh that should retain the closure; model/tokenizer data remain upstream/cache-owned"
     },
     {
       "id": "root:materializeWorkspaceRuntimeContent",
       "name": "materializeWorkspaceRuntimeContent",
       "displayName": "materializeWorkspaceRuntimeContent()",
       "kind": "function",
-      "signature": "async materializeWorkspaceRuntimeContent({workspaceRoot,runtimeRoot=path.join(getSdkRoot(), 'runtime'),browserRuntimeRoot=getSdkBrowserRuntimeRoot(),signal,onEvent}={})",
+      "signature": "async materializeWorkspaceRuntimeContent({workspaceRoot,runtimeRoot=path.join(getSdkRoot(), 'runtime'),browserRuntimeRoot=getSdkBrowserRuntimeRoot(),sdkVersion=SDK_VERSION,browserDecisions=false,signal,onEvent}={})",
       "entrypoints": [
         "arcane-os"
       ],
@@ -1759,7 +1759,7 @@
       "summary": "Replaces one workspace's complete projected runtime and browser-runtime content from selected source roots.",
       "availability": "Node",
       "protocol": "Workspace runtime materialization",
-      "normalization": "Complete workspace runtime content and a mutable materialization result"
+      "normalization": "Complete workspace runtime content and a mutable materialization result. browserDecisions:true adds the same explicit upstream browser executable acquisition as materializeInstalledSdkRuntime; the optional browserDecisions result contains directory, transformersVersion, onnxRuntimeVersion and files. Default false leaves acquisition disabled. Complete distribution content is copied without source rewriting, with cancellation/error cleanup before staged replacement and no model/tokenizer packaging"
     },
     {
       "id": "root:NATIVE_BUILD_PLAN_PROTOCOL",
@@ -4360,7 +4360,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance"
     },
     {
       "id": "core-client:installCoreClient",
@@ -4500,7 +4500,7 @@
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height, optional resizable and optional state normal/maximized/fullscreen into manifest.window with omitted fields preserved; the selected platform host owns the applied behavior. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Generated runtime/arcane-core.mjs accepts --arcane-app-entry <app-relative-module> through the host's supported Node executable. It imports the packaged app/ module's top-level work with complete process.argv unchanged and no automatic export call; the app owns launch-context reads, services, signals and shutdown. Include the entry and complete source closure through package.nativeResources. The flag skips ordinary Core startup; omission retains it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry. Reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -4542,7 +4542,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; 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; native.window selects initial 96-DPI logical client width/height and optional resizable through manifest.window, the matching host scales to actual DPI and fits initial placement to the usable screen while omitted fields and existing restored non-normal state remain unchanged; no saved-bounds subsystem is added and initial-fit logic is not reapplied during later resizing; 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; native.window selects initial 96-DPI logical client width/height, optional resizable and optional state normal/maximized/fullscreen through manifest.window. The matching host scales dimensions to actual DPI, fits initial placement to the usable screen and applies an explicit state afterward; omitted fields preserve existing host behavior. Fullscreen fills the selected monitor without a frame and retains normal bounds/frame controls for restoration. Requesting-window window.state/window.setState observe actual minimized/maximized state and prevent activation/focus assignment during visible transitions without selecting TopMost or changing Core, origin or profile. Saved Settings remain application-owned; no saved-bounds subsystem is added and initial-fit logic is not reapplied during later resizing; run cancellation closes stdin and waits for host-owned graceful shutdown. Packaged runtime/ArcaneCore.exe accepts --arcane-app-entry <app-relative-module> directly, without a script argument or GUI launcher; it imports the packaged app/ module's top-level work, preserves complete process.argv and invokes no export. Include the entry and complete source closure through package.nativeResources. The app owns launch-context reads, services, signals and shutdown; the flag skips ordinary Core startup, while omission preserves it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry"
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",

package/docs/reference/inventory/runtime-components.json

@@ -981,7 +981,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Preference/native appearance behavior mixed; selected button background, text and outline remain visible during hover while the hover fill applies only to unselected enabled buttons; no component-ready contract"
+      "normalization": "Preference/native appearance behavior mixed; selected button background, text and outline remain visible during hover while the hover fill applies only to unselected enabled buttons; no component-ready contract; pending choices expose aria-disabled and ignore repeated activation while staying in the keyboard focus flow; completion and failure do not move focus, and an unavailable Skin choice retains native disabling"
     },
     {
       "file": "runtime/arcane/components/unified-inbox.html",

package/docs/reference/inventory/runtime-modules.json

@@ -30,8 +30,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
-      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph. High-level LLM selection defaults to eager activation; startLanguageModel:false preserves the selected tuple and registered adapters without preloading through later readiness callbacks. Caller cancellation waits for accepted old-role cleanup and prevents later configuration/preload, or reaches the first owned load after selection commits. Newer accepted selections supersede older continuations; deferred or cancelled activation stays inactive until explicit load/startup, and a caller abort after successful settlement never unloads the ready model. Separate callers joining an existing runtime load retain their current cancellation ownership.",
+      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -133,7 +133,7 @@
       "summary": "Sticky mutable LLM, speech-to-text, and text-to-speech lifecycle snapshots, intents, subscriptions, and startup-settlement barriers.",
       "availability": "Cross-host in-process state contract; actual role readiness remains provider specific",
       "protocol": "arcane-ai-runtime-state/1 over the per-realm globalThis.arcaneEvents authority",
-      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; unloaded recovery/error may retain the exact busy operation until settlement, without readiness for new inference.",
+      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; unloaded recovery/error may retain the exact busy operation until settlement, without readiness for new inference. During unloading, an already loaded role may retain busy:true with its actual operationId while captured requests settle; this grants no readiness or new-request permission and is not a continuesAIRuntimeOperation recovery state.",
       "surface": "Protocol/event/role/state constants; snapshot, state subscribe/publish, intent request/subscribe, continuesAIRuntimeOperation(previous,current,operationId) for the real continuing runtime operation, and `startAIRuntime({startMuted,startTranscription,signal})` returning `{barrier,settled,cancel}`."
     },
     {
@@ -1201,7 +1201,7 @@
       "summary": "Matches configured risk signals and levels against complete text.",
       "availability": "Cross-host",
       "protocol": "In-process only",
-      "normalization": "Fully normalized.",
+      "normalization": "Complete literal text; existing non-string conversion only.",
       "surface": "`DEFAULT_LEVELS`, `analyzeRiskSignals()`."
     },
     {

package/docs/reference/local-ai.md

@@ -86,7 +86,8 @@ transport loss retain their owning cancellation behavior. A terminal engine
 failure reaches the original request as its actual error rather than a
 fabricated readiness success. See [native speech reconciliation](native-speech.md).
 
-`llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
+`llamaCpp` accepts `url`, `model`, `alias`, `modelsDirectory`, `executionTarget`,
+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`,
 `modelsDirectory`, and `args`. The default endpoints are
@@ -94,6 +95,24 @@ mode. Paths resolve from the application root. Ollama accepts `url`,
 directories are `.arcane/models/llama.cpp` and `.arcane/models/ollama` inside the
 application. Applications choose and provision their models explicitly.
 
+A llama runtime requirement accepts `backend: 'auto' | 'cpu' | 'cuda'`, with
+`auto` preserving the ordinary platform distribution. Explicit `cpu` also
+configures CPU execution, including on a Metal-capable macOS distribution.
+`cuda` currently selects the official Windows x64 CUDA 13.4 engine and its
+matching same-release CUDA companion archive. For example:
+
+```json
+{"runtimes": [{"id": "llama.cpp", "backend": "cuda"}]}
+```
+
+Development prepares this explicit distribution instead of treating an unknown
+PATH executable or external listener as proof of its backend. Native packaging
+bundles the selected runtime tree and companion libraries through the existing
+runtime workflow. A custom CUDA `url` also needs its explicit `companionUrl`;
+the SDK does not guess a companion location. Installation records distinguish
+the distribution's `backend` from its `requestedBackend` execution mode.
+Selecting an unavailable distribution reports its actual error.
+
 ## Development
 
 ```sh
@@ -226,7 +245,7 @@ background health polling.
 | --- | --- | --- |
 | `llama.status` | `{}` | Runtime state and model catalog |
 | `llama.models` | `{}` | `{models}` |
-| `llama.load` | `{model}` | State after the exact model reports loaded |
+| `llama.load` | `{model,assetProjectionId?,resourcePaths?,executionTarget?}` | State after the exact model reports loaded |
 | `llama.unload` | `{model}` | Current state after release |
 | `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
 
@@ -238,6 +257,36 @@ only after Core successfully closes its owned single-model server. Explicit
 load, inference or recovery can resume that engine; observation cannot.
 Status observation adds no background polling.
 
+For a saved browser GGUF, prepare its complete file through the existing
+[`model-assets` owner](model-assets.md), then call `llama.load` with its
+`assetProjectionId` and `resourcePaths: {model: 'selected.gguf'}`. Core retains
+that member before replacing its owned server, uses the exact `model` value as
+the server alias, and releases the retained use only after actual process exit.
+The preparation owner can release its use when loading settles. Replacement,
+cancelled loading, unload and shutdown all preserve this lifetime. A cancelled
+projected load joins process shutdown before returning. Ordinary router loads
+retain their existing shared-load behavior.
+
+`executionTarget: {deviceId}` uses the identifier from this computer's execution
+device catalog. Windows CPU selection disables GPU offload; Windows NVIDIA GPU
+selection requires the CUDA distribution and resolves the current adapter LUID
+to its CUDA UUID. The new server sees that one physical GPU as `CUDA0`.
+No machine-specific device ID is embedded in configuration examples. Each host
+resolves its own saved selection; an absent or unsupported device reports an
+error. Other host adapters remain subject to their declared catalog support.
+`executionTarget: null` uses the configured runtime default. Omission preserves
+an active selection's target. Runtime `execution` separates `requestedTarget`,
+`resolvedDevice` and `configuredTarget`; `observedTarget: null` means actual
+inference placement has not been observed. Configuration is not placement proof.
+
+An external server keeps ownership of its model and device. Projected loading
+or explicit target changes report `LOCAL_AI_EXTERNAL_SELECTION_UNSUPPORTED`
+without stopping it or changing a working Core observation. `managed` describes
+whether an installed executable can be managed at this listener; `owned` reports
+an actual SDK-owned process. Recovery retains a live projection across process
+replacement. If the projection was already released after exit, prepare it again;
+resuming never substitutes another model or target.
+
 The `payload` is the complete request. SDK option names are translated only at
 the upstream protocol boundary; messages, tool definitions and documents remain
 unchanged. An explicit `payload.model` selects that request's model. Core waits
@@ -365,10 +414,44 @@ runtime still reconciles the provider at its existing operation boundaries.
 permits that load preflight even before its catalog arrives; Core's `llama.load`
 waits for startup and verifies the exact requested model. An owned, successfully
 released service permits loading only a model retained in its actual catalog.
-An available service still requires that catalog membership. These observations
+With `prepareModel`, an installed `managed` service also admits an explicit
+load before the requested model exists in its catalog. An available external
+service still requires catalog membership. These observations
 do not fabricate model records or readiness, and unavailable external services,
 closed services and actual errors remain unavailable.
 
+The optional `prepareModel({selection,signal,progress})` callback runs only at
+an actual provider load. Return `{assetProjectionId,resourcePaths,executionTarget,release?}`;
+direct `provider.load` fields override the corresponding callback
+fields, including an explicit null target. The provider awaits `release()`
+after Core loading settles and before reporting readiness. Preparation must
+observe cancellation and settle so even a late returned projection is released.
+Only a dispatched Core selection owns a native unload; cancelled preparation
+alone does not unload another model.
+
+```js
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+
+// modelFile is the complete GGUF Blob/File read from the application's store.
+// selectedDeviceId came from this host's execution-device catalog.
+const provider = createCoreLocalAIProvider({
+  client,
+  async prepareModel({signal, progress}) {
+    const projection = await prepareCoreModelAssets({
+      client, workingDirectory: '.arcane/model-work', signal,
+      members: [{path: 'moon-raccoon.gguf', file: modelFile}],
+      onProgress: progress
+    });
+    return {
+      assetProjectionId: projection.id,
+      resourcePaths: {model: 'moon-raccoon.gguf'},
+      executionTarget: {deviceId: selectedDeviceId},
+      release: projection.release
+    };
+  }
+});
+```
+
 `dispose()` removes installation and service subscriptions and cancels owned
 operations synchronously, then attempts its actually retained model's release
 through its captured client. A configured selection alone does not own a native