arcane-os 0.64.0 → 0.66.0

package/docs/reference/README.md

@@ -54,15 +54,23 @@ alone does not make bare module names resolve in a browser.
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
 | Cancel one Core speech synthesis request without changing its payload | [Speech request lifetime](core-client.md#events-and-request-lifetime) and [Core facade](sdk-api.md#createcorefacade) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
+| Compose application Core services during source development, independently of local AI | [Development Core services](core-development.md) |
+| Own an explicitly selected native Codex App Server session | [Codex App Server](codex-app-server.md) |
+| Expose application-owned tools and static resources through Node STDIO | [MCP STDIO server](mcp-stdio.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
 | Generate complete local PNG images with a retained native model | [Local image generation](local-image-generation.md) |
 | Select FLUX.2 Klein 4B and its three complementary model resources | [FLUX.2 Klein 4B through Core](local-image-flux.md) |
+| Select the complete SDXL Base 1.0 checkpoint for text-to-image generation | [SDXL Base 1.0 through Core](local-image-sdxl.md) |
 | Compose independently loaded transcription and synthesis engines | [Native speech service](native-speech.md) |
+| Keep a native Whisper model loaded across complete recordings | [Native Whisper transcription](local-whisper.md) |
+| Select the optional Intel NPU encoder with independent CUDA or CPU decoding | [Intel NPU Whisper](../guides/native-whisper-openvino.md) |
 | Edit an original PNG with a complete prompt and explicit strength | [Local image editing](local-image-editing.md) |
 | Project complete stored model files into native working files | [Model assets through Core](model-assets.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
+| Own a native working checkout under per-user ArcaneData/Repos | [Native repository workspaces](core-repositories.md) |
+| Write, commit and push complete selected repository text | [Selected-text repository writing](core-repositories.md#write-commit-and-push-selected-text) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
 | Pass host-selected state defaults and unchanged explicit launch values to services | [Launch-time locations](core-native-packaging.md#launch-time-locations) |
 | Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
@@ -139,7 +147,8 @@ node tools/build-reference-site.mjs --write --source-ref <documentation-commit>
 
 The same option is accepted by `createReferenceSite({sourceRef})` and
 `writeReferenceSite({sourceRef})`. It reads the selected commit's package
-version, complete reference documents and inventories, inventory-selected
+version, complete reference documents and inventories, the canonical
+`docs/guides/native-whisper-openvino.md` guide when present, inventory-selected
 runtime sources, and authored site inputs directly from Git in memory. It
 creates no checkout or export and leaves source drafts untouched. Rendering
 uses the current canonical generator and its authored semantic contracts;
@@ -227,6 +236,7 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
 | Run application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
+| Transcribe complete recordings with a retained native Whisper model | [`arcane-os/local-ai/whisper`](local-whisper.md) and [Core speech](native-speech.md) | Matching native helper, Whisper libraries, decoder and selected model; Windows defaults and explicit other-platform distributions have distinct preparation requirements. |
 | Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
 | Generate local images from complete prompts and selected model resources | [`arcane-os/local-ai/image`, `arcane-os/ai/core-image`](local-image-generation.md) | Prepared native image runtime; browser access requires its Core service. CPU Windows/Linux and Mac Metal/CPU paths have distinct actual host requirements. |
 | Supply complete stored model members to a native engine | [`arcane-os/ai/core-model-assets`, `arcane-os/core/model-assets`](model-assets.md) | Available Core service; DBOPFS originals stay authoritative while native owners retain working files. |

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

@@ -1,7 +1,8 @@
 # Browser typed decisions
 
-`arcane-os/ai/browser-decisions` owns browser-local Laya typed-decisions FP16
-and Julia-1 FP32 inference. It is separate from chat and speech because these
+`arcane-os/ai/browser-decisions` owns browser-local Laya typed decisions
+and Julia-1 inference. Laya defaults to FP16 and Julia to FP32; an explicit
+`dtype` is forwarded unchanged to the selected upstream loader. It is separate from chat and speech because these
 models score caller-supplied options instead of generating conversational text.
 Applications supply the model repository, state, questions, option meanings and
 policy; the SDK owns the reusable tokenizer, tensors, inference and lifecycle.
@@ -66,6 +67,7 @@ it does not substitute a quantized graph or another model.
 | `model` | Required upstream repository/base URL accepted by Transformers.js. The application owns its selection. |
 | `revision` | Upstream revision, default `main`; select a stable revision when repeatable model selection is needed. |
 | `device` | Transformers.js backend, default `webgpu`; an explicit supported alternative is caller-owned. No automatic backend fallback. |
+| `dtype` | Exact upstream precision selection; defaults to `fp16` for Laya and `fp32` for Julia. For Laya FP32, supply `dtype: 'fp32'`. Unsupported selections fail at the selected upstream loader rather than being replaced. |
 | `runtime.moduleUrl` | Defaults to the self-contained CDN entry `https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.min.js`. The `.web.js` build expects a bundler to resolve its bare ONNX Runtime import and is unsuitable for a native module Worker. An explicit compatible public runtime URL may be supplied. |
 | `runtime.wasmPaths` | Optional upstream ONNX WASM location passed to the selected runtime's public environment API. |
 
@@ -75,10 +77,11 @@ network, cross-origin and backend availability still apply. WebGPU needs a
 compatible browser/device context. Unsupported precision or backend errors
 are returned, not replaced with a different model, backend or precision.
 
-Laya selects `dtype: 'fp16'`, loading `onnx/model_fp16.onnx` and its
+Laya defaults to `dtype: 'fp16'`, loading `onnx/model_fp16.onnx` and its
 `model_fp16.onnx_data` companion through Transformers.js. The published mixed
 precision graph retains selected operations/outputs in FP32; FP16 selection
-does not claim every graph operation runs in half precision.
+does not claim every graph operation runs in half precision. Explicit
+`dtype: 'fp32'` selects the repository's FP32 graph through that same loader.
 
 Julia selects `dtype: 'fp32'`, loading root `model.onnx` with the exact
 `model.onnx.data` external-data name. Its custom five-input graph is loaded

package/docs/reference/arcane-ollama.md

@@ -120,7 +120,7 @@ non-writable `globalThis.arcaneOllama` convenience and emits
 | `version()` | `Arcane.ollama.version()` | Raw service version diagnostic. | [version](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaversion) |
 | `models()` | `Arcane.ollama.models()` | Raw installed-model diagnostic. | [models](core/reference/arcane-api/ai-and-ollama.md#arcaneollamamodels) |
 | `list()` | Calls `Arcane.ollama.models()` | Module alias for `models()`; it does not call the bridge's separate `list` alias. | [list](core/reference/arcane-api/ai-and-ollama.md#arcaneollamalist) |
-| `running()` | `Arcane.ollama.running()` | Raw resident-model diagnostic. | [running](core/reference/arcane-api/ai-and-ollama.md#arcaneollamarunning) |
+| `running(options?)` | `Arcane.ollama.running(options?)` | Raw resident-model diagnostic; optional `{signal, timeoutMs, onRequest}` uses the Core request lifetime. No-argument calls remain supported. | [running](core/reference/arcane-api/ai-and-ollama.md#arcaneollamarunning) |
 | `show(model, options)` | `Arcane.ollama.show(...)` | Raw bounded model metadata. | [show](core/reference/arcane-api/ai-and-ollama.md#arcaneollamashow) |
 | `generate(request, options)` | `Arcane.ollama.generate(...)` | Admitted generation; optional chunk callback/signal/timeout. | [generate](core/reference/arcane-api/ai-and-ollama.md#arcaneollamagenerate) |
 | `chat(request, options)` | `Arcane.ollama.chat(...)` | Admitted chat/tools; optional chunk callback/signal/timeout. | [chat](core/reference/arcane-api/ai-and-ollama.md#arcaneollamachat) |

package/docs/reference/codex-app-server.md

@@ -0,0 +1,269 @@
+# Native Codex App Server sessions
+
+`arcane-os/codex/app-server` is an optional Node entrypoint for an explicitly
+selected native Codex App Server. It exports
+`createCodexAppServerSession(options)` and
+`openCodexAppServerSession(options)`.
+
+The adapter owns JSONL correlation and session lifecycle, reusing the SDK's
+`runProcess` and semantic event manager. Applications own connection selection,
+thread routing, prompts, approval decisions, visible presentation and explicit
+send actions. It does not install Codex, authenticate an account, attach to a
+desktop chat, start a thread during connection, or choose a model.
+
+The [official Codex App Server documentation](https://learn.chatgpt.com/docs/app-server)
+defines the external protocol: stdio JSONL frames omit `jsonrpc`; initialization
+uses `initialize` followed by `initialized`; `turn/start` acceptance is distinct
+from the terminal `turn/completed` notification. This transport is separate from
+Core's Content-Length-framed `arcane/1` connection.
+
+The source baseline is the current, unversioned official App Server page read
+on October 6, 2026, specifically its Protocol, Initialization, Threads, Events
+and approval/request sections. This adapter does not claim a pinned Codex CLI
+release or generated-schema revision. The documentation describes schema
+generation as specific to the CLI version used; no CLI or schema generator was
+executed to establish this source contract.
+
+## Open an explicitly selected connection
+
+```javascript
+import {createCodexAppServerSession} from 'arcane-os/codex/app-server';
+
+const session = createCodexAppServerSession(
+    {
+        executable: selectedCodexExecutable,
+        args: ['app-server', '--listen', 'stdio://'],
+        cwd: selectedWorkingDirectory,
+        clientInfo: {name: 'moon_cheese_inventory', title: 'Moon Cheese Inventory', version: '1'}
+    }
+);
+
+// Store the handle before awaiting so the host can dispose during initialization.
+connectionOwner.session = session;
+session.subscribe('status', showConnectionStatus);
+session.subscribe('serverRequest', askForActualDecision);
+await session.connect();
+
+const {thread} = await session.createThread(selectedThreadOptions);
+const result = await session.runTurn(
+    {
+        threadId: thread.id,
+        input: 'Count the moon cheese and explain the missing wheel.',
+        signal: requestController.signal,
+        onDelta: showSelectedLiveDelta,
+        onItem: updateSelectedItem,
+        onTurn: showTurnStatus
+    }
+);
+
+// These records contain assistant text, not commands, reasoning or tool envelopes.
+showVisibleResult(result.visibleItems, result.status);
+await session.dispose();
+```
+
+The example's named callbacks and owners belong to the application. Keep a
+session alive across related operations; it launches one process per connection,
+not one per request. `openCodexAppServerSession(options)` creates a session,
+awaits connection readiness and returns it; use the synchronous factory when
+the host needs the handle during connection or needs initialization events.
+If opening fails, the convenience function disposes the owned process before
+rejecting.
+
+Options are `executable` (required), `args` (defaults shown above), `cwd`, `env`,
+`clientInfo` and `capabilities`. `env` uses `runProcess`'s environment overrides.
+Arguments are actual executable arguments; there is no shell command parser.
+On Windows, select an actual native executable or explicitly select Node and
+the installed CLI entry script in `args`, instead of passing a `.cmd` launcher.
+No operating-system-specific credential store or home-directory assumption is
+introduced. Node and the caller-selected native executable are required on
+Windows, Linux and macOS; Android requires a host that supplies those process
+facilities. A browser renderer cannot import or launch this Node-only adapter.
+
+The default client identity is
+`{name:'arcane_sdk',title:'Arcane SDK',version:'1'}`. Caller-supplied identity and
+capabilities are forwarded to initialization. Experimental methods require the
+server's corresponding capability selection. Avoid opting out of the turn/item
+notifications that `runTurn` needs; the adapter does not override your selection
+or manufacture missing events.
+
+## Session methods
+
+| Method | Result and ownership |
+| --- | --- |
+| `connect()` | Promise of the same session after initialization; concurrent calls share the in-flight connection. Ready calls reuse it. |
+| `listThreads(params)` | Complete native `thread/list` result, including `data` and cursor. The caller owns pagination. |
+| `readThread({threadId,includeTurns,...options})` | Complete native `thread/read` result. No thread resume or event subscription. |
+| `readTurn({threadId,turnId})` | Reads the thread with `includeTurns:true`, selects the exact turn, and returns the response shape below. No new turn or thread resume. |
+| `createThread(params)` | Complete native `thread/start` result, including `thread`; the server subscribes the connection to that new thread. |
+| `resumeThread({threadId,...options})` | Complete native `thread/resume` result for the caller's explicitly selected existing thread. |
+| `request(method,params)` | Complete native result, or a correlated RPC error. Use for additional provider methods; no automatic retries. |
+| `runTurn(options)` | Waits for the exact accepted turn's terminal notification. Does not create, resume or select a thread. |
+| `interrupt({threadId,turnId})` | Native interrupt acknowledgement only; the terminal notification establishes the actual outcome. |
+| `respond({id,result},context)` / `respond({id,error},context)` | Queues the actual correlated server-request reply and returns `{id,submitted:true}`. Retain the originating context across asynchronous work. Submission is not resolution. |
+| `subscribe(type,listener,options)` | Returns an unsubscribe function; supports the shared event owner's `once` and `signal`. `status` replays immediately. |
+| `reconnect()` | Drains the old owned process and initializes a new one. Never replays requests or resumes threads. |
+| `dispose()` | Cancels the owned process tree, drains input/output/process completion, releases subscriptions and permanently disposes this session. |
+
+Requests require a ready connection and do not implicitly connect.
+`readThread` returns native `{thread:{turns:[{id,status,items,...}],...},...}`
+when turns are requested. `readTurn` returns the stored status as supplied,
+including an in-progress status if that is what the server returns. A missing
+exact ID rejects with `ARCANE_CODEX_TURN_NOT_FOUND`; it never picks another turn.
+Neither read operation claims the returned conversation belongs to the desktop
+application. Access and available records depend on the selected App Server.
+
+## Input, live callbacks and complete output
+
+`runTurn({threadId,input,signal,onDelta,onItem,onTurn,...turnOptions})` forwards
+the remaining options to native `turn/start`. A native input array is sent
+unchanged. A string receives only the required native text-item envelope
+`[{type:'text',text:input}]`; the string itself is unchanged. No prompt prefix,
+trimming, classification, normalization or implicit tool selection occurs.
+
+Register or resume the selected thread before running a turn so the connection
+receives its item/turn notifications. Local correlation listeners are installed
+before submission. Events that arrive ahead of the acceptance response are
+retained in order until the returned turn ID can correlate them.
+
+- `onDelta({threadId,turnId,itemId,delta,phase,method,params})` receives complete
+  `item/agentMessage/delta` or `item/commandExecution/outputDelta` content. Use
+  `method` to select assistant text for the ordinary UI; command output belongs
+  in an explicitly selected inspection surface. `params` preserves all native
+  fields. Other delta methods remain available through `notification`.
+- `onItem({threadId,turnId,itemId,text,phase,stage,item,params})` receives item
+  starts and completions. `stage` is `started` or `completed`; `phase` is the
+  provider's phase or `null`, not the lifecycle stage. `text` is agent-message
+  text, and is `null` for other item types. `item` remains the complete native
+  object, including extension fields.
+- `onTurn({threadId,turnId,status,turn})` receives actual turn lifecycle events.
+  The `turnAccepted` session event separately carries the start response.
+
+The resolved result is
+`{threadId,turnId,status,items,visibleItems,error,turn}`:
+
+- `status` is the actual terminal status: `completed`, `interrupted` or `failed`.
+  A provider failure resolves this terminal result with its actual `error`;
+  transport and start-request errors reject. Inspect status before committing a
+  successful application response.
+- `items` contains complete native item objects in first-observed order, updated
+  by their final item snapshots and any terminal turn items. It includes commands
+  and other diagnostic/protocol item types; it is not durable chat history.
+- `visibleItems` contains only agent-message projections
+  `{itemId,text,phase}`. Text is complete and unchanged. All supplied phases,
+  including `commentary`, `final_answer` or `null`, remain distinct. The app
+  decides which phases belong in its visible response; the adapter never joins
+  items, inserts separators or rewrites text.
+- `turn` and `error` preserve the complete terminal provider objects. There is
+  no synthesized successful turn or substituted assistant failure message.
+
+Callbacks are observational and invoked in incoming order, without awaiting
+returned promises. This allows an approval owner to await another RPC without
+deadlocking stdout. Synchronous failures and rejected callback promises produce
+`observerError`; a rejection arriving after disposal goes to `console.error`.
+Applications own completion of their asynchronous presentation/decision work.
+
+## Events and server requests
+
+`session.status` is `{state,...details}`, with states `disconnected`,
+`connecting`, `ready`, and `disposed`. Ready includes the complete `initialized`
+result; connection failure includes `error`. There is no implied authentication,
+model readiness, thread ownership or persistence guarantee in a ready status.
+
+Session event names are `status`, `message`, `notification`, `stderr`, `process`,
+`error`, `serverRequest`, `serverRequestResponded`, `serverRequestResolved`,
+`turnAccepted`, `delta`, `item`, `turn` and `observerError`. Listener arguments
+are detail objects directly, not DOM events. Shared semantic event names use
+the `arcane.codex.app-server.` prefix and lowercase hyphen-separated suffixes.
+The public subscription aliases retain their original spelling:
+
+| Session alias | Shared semantic event |
+| --- | --- |
+| `serverRequest` | `arcane.codex.app-server.server-request` |
+| `serverRequestResponded` | `arcane.codex.app-server.server-request-responded` |
+| `serverRequestResolved` | `arcane.codex.app-server.server-request-resolved` |
+| `turnAccepted` | `arcane.codex.app-server.turn-accepted` |
+| `observerError` | `arcane.codex.app-server.observer-error` |
+
+The other aliases are already lowercase and are appended unchanged to the
+prefix. Declaration, subscription and publication share this same mapping;
+native Codex wire method names and payload fields are unchanged.
+
+`message` exposes every complete decoded JSONL envelope; `notification` exposes
+all native notification methods. `stderr` preserves complete `{stream,chunk}`
+records. `process` forwards the SDK process owner's lifecycle events. These
+diagnostics are neither application conversation text nor saved chat history.
+
+Every inbound request with a method and ID emits `serverRequest`. Its listener
+receives the complete native envelope as its first argument and a separate
+origin-bound reply context as its second. This includes approvals, permissions, user input,
+MCP elicitation and experimental tool calls. The adapter does not approve,
+decline, fabricate tool results or invoke application tools itself. The
+application returns the exact native result or error for that request method:
+
+```javascript
+async function askForActualDecision(request, context) {
+    const result = await applicationDecisionOwner.answer(request);
+    context.respond(
+        {result}
+    );
+}
+```
+
+The stdout reader keeps consuming while that decision is pending.
+The context is `{id,respond}`. `context.respond({result})` or
+`context.respond({error})` binds the reply to that exact request and its native
+ID. Equivalently, pass the same context object as the second argument to
+`session.respond({id:request.id,result},context)`. Retain it before awaiting a
+human decision or other work. It is SDK control metadata, not part of the native
+request or reply payload.
+
+ID-only `session.respond({id,result})` remains supported while that native ID
+has appeared only once in this session. Once an ID is reused, including after
+reconnect, ID-only replies throw `ARCANE_CODEX_REQUEST_CONTEXT_REQUIRED` rather
+than selecting an origin implicitly. A context from an older request throws
+`ARCANE_CODEX_STALE_REQUEST_CONTEXT` when a current request reuses its ID. If
+there is no corresponding current request, the existing not-ready/not-found
+error applies. No such failure writes a reply to the new process. This also
+handles ID reuse within one connection after a request resolves.
+
+`pendingServerRequests` contains `{request,responded,context,contextRequired}`
+entries for the current connection. An attention owner can retain that same
+context when presenting an already pending request. Submission changes
+`responded`; the server's
+`serverRequest/resolved` notification removes the entry. A late reply after
+resolution, disconnect, or a prior submitted reply is reported explicitly.
+Disconnection clears pending requests and includes their complete prior entries
+in the connection `error` event as `pendingServerRequests`.
+`serverRequestResolved` receives the native `{threadId,requestId}` params after
+the corresponding pending entry is removed. The `serverRequestResponded` event
+receives `{request,response}`, while `serverRequest` receives the raw request
+envelope directly. Clear application attention from actual pending state or
+resolution/disconnection, rather than treating local submission as resolution.
+
+## Cancellation and unknown results
+
+A pre-aborted turn rejects with `ARCANE_CANCELLED` and
+`details.outcome:'not-submitted'`. After submission, abort requests interruption
+as soon as the accepted turn ID is known. It stops that call's `onDelta` and
+`onItem` delivery; raw session events and actual `onTurn` terminal status remain
+observable. A successful interrupt acknowledgement is not a terminal result.
+If interruption itself fails, the operation rejects with an unknown outcome.
+
+Connection loss or disposal before terminal completion rejects a turn with
+`ARCANE_CODEX_TURN_UNKNOWN`, `details.outcome:'unknown'`, the actual thread ID,
+the turn ID when known, and observed native items. Ordinary pending RPCs reject
+with `ARCANE_CODEX_CONNECTION_LOST` and unknown outcome. Native RPC rejection
+uses `ARCANE_CODEX_RPC` and retains `details.error`, `response`, `method`,
+`requestId`, `params` and `outcome:'rejected'`.
+
+There are no implicit retries, timer-based completions, generic shutdown RPCs,
+or claims that stdin EOF durably saves a turn. After reconnecting, use the known
+thread and turn IDs with `readTurn` to reconcile. If acceptance was never
+observed and no turn ID is known, inspect `readThread({threadId,includeTurns:true})`
+and let the application resolve that ambiguity. Never automatically repeat
+`turn/start` because its outcome is uncertain. Resume a selected thread only
+when the application explicitly intends further work on it.
+
+This page describes the SDK source contract. Native Codex, authentication,
+provider behavior and platform execution require evidence from the selected
+installed runtime; authored fixture coverage is not evidence of those outcomes.

package/docs/reference/core-client.md

@@ -1,8 +1,8 @@
 # Core browser client
 
 `arcane-os/core/client` is the browser-safe `arcane/1` RPC owner. It exports
-`createCoreClient`, `createCoreFacade`, `installCoreClient` and
-`getInstalledCoreClient`.
+`createCoreClient`, `createCoreFacade`, `installCoreClient`,
+`getInstalledCoreClient` and `subscribeCoreClient`.
 `arcane-os/core/contracts` exports `CORE_PROTOCOL`, `CORE_READY_EVENTS`,
 `CORE_FRAME_CONTRACTS`, `CORE_METHOD_CONTRACTS`, `CoreError` and
 `serializeCoreError`. Contracts describe transport and existing method shapes;
@@ -43,6 +43,57 @@ need not inspect private installation fields. It returns `null` after that
 installation closes or fails. A
 foreign application's `Arcane` object is not evidence of an SDK installation.
 
+### Observe installation and retirement
+
+```js
+import {subscribeCoreClient} from 'arcane-os/core/client';
+
+const lifetime=new AbortController();
+const stop=subscribeCoreClient(function useCurrentClient({client,reason,error}){
+    console.log('Moon-base connection owner:',client,reason);
+    if(error)console.error('Core transport failed:',error);
+},{signal:lifetime.signal});
+// Call stop() or lifetime.abort() when this observer's owner ends its lifetime.
+```
+
+`subscribeCoreClient(listener, {global=globalThis, emitCurrent=true, signal}={})`
+observes the exact SDK-installed client for that global without installing or
+connecting one. By default it synchronously replays
+`{client, previousClient:null, reason:'current', error:null}` after subscribing.
+`client` is the same live object returned by `getInstalledCoreClient`, or `null`.
+Set `emitCurrent:false` to observe only subsequent changes. The returned
+unsubscribe function is idempotent; aborting `signal` removes the subscription.
+A pre-aborted signal registers nothing and emits no replay.
+
+Later notifications use the same fields. `reason:'installed'` follows the
+connection attempt while that installation is still live, with
+`previousClient:null` and `error:null`. Installation does not imply a connected
+transport: a standalone client retains its ordinary disconnected capabilities.
+Repeated installation returns the existing client without another notification.
+`reason:'closed'` and `reason:'transport-failed'` identify the retired client in
+`previousClient`; a transport failure retains its complete actual `CoreError`
+in `error`, while ordinary close uses `null`.
+
+Retirement releases and restores owned globals before notifying, once per
+installation. `client` is read again after cleanup, so a replacement installed
+reentrantly during cleanup or error reporting remains the current client.
+Notifications do not restore or close that replacement. A listener may also
+install a replacement after observing retirement; its installation produces
+the normal next notification. Reentrant changes queue until the current
+notification finishes reaching its observers. Each notification retains the
+exact client and error references captured for that transition, so observers
+receive retirement before a replacement installed by another observer. Global
+installation changes remain synchronous; reading the accessor inside a callback
+may therefore show a newer client than that callback's transition snapshot.
+
+The existing shared SDK event owner delivers changes without polling or a
+second event bus. Classic host injection may install synchronously before that
+event owner is available. The first ESM subscriber attaches the shared event
+source lazily and reads the exact classic-installed client from the live
+installation. Source-scoped delivery preserves the client and error references;
+it does not use the event owner's global diagnostic snapshots. No historical
+installation record is retained for replay.
+
 The native adapters select WebView2, WebKitGTK or Android WebView. Ordinary
 browsers remain `standalone`; they do not probe a local server. Development
 HTTP is selected only by the existing explicit `__ARCANE_DEV_HTTP__` flag.
@@ -73,6 +124,13 @@ event data retain their complete supplied content. JSON encoding belongs only
 to transports that require it; values crossing those transports must be
 JSON-compatible. There is no client method allowlist or content limit.
 The default request timeout is ten minutes; `timeoutMs:0` disables that timer.
+
+`Arcane.ollama.running({signal, timeoutMs, onRequest}={})` forwards these request
+options to the existing Core invocation without putting them in the Ollama
+payload. It returns the complete resident-model snapshot; aborting its signal
+cancels that inspection through the same request control path. Existing
+`Arcane.ollama.running()` calls remain supported.
+
 The compatibility facade retains its operation-specific timeouts and streaming
 callbacks. Streaming IDs and isolated-operation IDs are separate protocol
 correlation fields alongside the supplied request fields.

package/docs/reference/core-development.md

@@ -0,0 +1,157 @@
+# Application Core services during source development
+
+`developApplication()` can compose an application's Core services without
+selecting, installing or loading a local AI engine. It uses the existing SDK
+source server and one app-scoped Core dispatcher; the app owns its service
+implementations and the explicit actions that start native work.
+
+## Select services
+
+The ordinary `arcane dev` command reads `native.services` from the selected
+application descriptor:
+
+```json
+{
+    "native": {
+        "services": [
+            {"module": "bridge/moon-cheese.mjs", "options": {"shelf": "Lunar cheddar"}}
+        ]
+    }
+}
+```
+
+This is the `native` portion of the application's existing descriptor, not a
+complete descriptor. Module paths resolve from the selected app root. Each
+module exports its factory as default, using the same native packaging contract:
+
+```javascript
+export default function createMoonCheese(options, context) {
+    return {
+        name: 'moon-cheese',
+        methods: {
+            'moon-cheese.current': function current() {
+                return {shelf: options.shelf, message: 'The Moon is ready for cheese.'};
+            }
+        }
+    };
+}
+```
+
+The factory receives `(options, context)` without changing authored options.
+Context supplies `appRoot`, the operation `signal`, and `onEvent`; a programmatic
+call's explicit `context` fields take precedence, matching the native
+launch-context convention. A factory may return a service promise. Service
+definitions retain the Core `name`, `methods`, `start`, `drain` and `dispose`
+contract. Services start independently after composition; a method waits only
+for its own service's startup. A process such as Codex starts only when the
+application service's explicit connect method requests it, not because the
+development listener opened.
+
+Programmatic composition uses:
+
+```javascript
+import {developApplication} from 'arcane-os';
+
+const development = await developApplication({
+    workspaceRoot: process.cwd(),
+    serviceModules: [{module: 'bridge/moon-cheese.mjs', options: {shelf: 'Lunar cheddar'}}],
+    context: {stateRoot: './selected-app-state'}
+});
+// Application work proceeds. Its owner later calls await development.close().
+```
+
+`serviceModules` replaces the descriptor's module list when supplied, including
+an explicitly empty array. `services` adds already-constructed Core service
+definitions. Both can coexist with configured native local-AI services inside
+one dispatcher. No services and no selected local AI preserves ordinary static
+source serving. The result adds `core` when composition is selected and retains
+the existing `localAI` result when local AI is selected.
+
+## Connect the page without blocking rendering
+
+Load `/arcane-core.js` as an independent module. It immediately exports `client`
+after synchronous installation, without awaiting SSE connection or Core/service
+readiness. The existing `/arcane-local-ai.js` URL remains an alias for the same
+bootstrap behavior. Managed import maps resolve its public Core-client import.
+
+```javascript
+import {client} from '/arcane-core.js';
+
+client.events.when('core.ready', function dispatcherReady() {
+    client.invoke('moon-cheese.current').then(
+        function showCheese(result) { console.log(result); },
+        function reportCheeseFailure(error) { console.error(error); }
+    );
+});
+```
+
+The SDK does not inject a script or hold the page's first render. Existing native
+clients remain installed; a disconnected standalone client can be replaced by
+this explicitly selected development connection. `core.ready` establishes
+dispatcher readiness, not a connected application process or loaded model.
+Application status methods remain the owner of application state and pending
+requests. Generic replay supplies current Core/service lifecycle, not historical
+responses, a repository catalog or an application's operation journal.
+
+A page module that loads independently of the bootstrap can use
+`subscribeCoreClient()` from `arcane-os/core/client`. It immediately replays the
+installed client (or `null`), then reports installation, close and terminal
+transport failure. This lets rendering proceed before the connection exists.
+Installation alone is not service readiness; observe the returned client's
+runtime and service events. Retire subscriptions with the page's owning lifetime.
+
+The development transport uses `/events` for ordered SSE frames and `/rpc` for
+JSON requests. The shared Core client owns correlation, timeout and cancellation.
+Responses and correlated streaming events return to their originating document.
+Uncorrelated service lifecycle events reach connected documents. The payload
+is passed unchanged to the service; the adapter adds no application policy.
+Connection and complete parsing/transport errors reach the client's existing
+failure/diagnostic boundary. Reopening a page creates a new document connection,
+not a second service runtime.
+
+## Direct composition
+
+`createDevelopmentCore()` is exported from `arcane-os` and
+`arcane-os/core/development`. It accepts
+`{appRoot=process.cwd(), application, version, services=[], serviceModules=[],
+context={}, getReplayEvents, signal, onEvent}` and returns synchronously:
+
+- `ready`: the runtime after service modules are composed and dispatcher startup
+  is accepted; individual services may still be starting or may fail separately;
+- `handler(request,response)`: an asynchronous boolean indicating whether an SDK
+  Core route was consumed;
+- `current()`: `{state,error,core}`, with complete Core service/lifecycle state;
+- `close()`: one idempotent shutdown promise.
+
+Use `startDevServer({..., core})` to give that server the handler and shutdown
+owner. A failed server start remains the caller's cleanup responsibility for
+direct composition; `developApplication()` performs this cleanup itself.
+`getReplayEvents()` optionally returns complete current `{event,data}` snapshots
+for service-specific replay. It neither stores history nor replaces application
+status methods. Existing local-AI composition uses it for its established model,
+image and speech snapshots.
+
+## Cancellation and shutdown
+
+A document disconnect or its `requests.cancelAll` cancels only its own
+request-lifetime operations. Another document's work remains active. An accepted
+`lifetime:'service'` operation survives renderer cancellation; the service owns
+its durable completion. A disconnected document receives no later response,
+and reconnecting does not automatically repeat the operation.
+
+Closing the development owner stops new Core requests, cancels request-lifetime
+work, waits for accepted service work, drains and disposes services, and joins
+queued SSE writes before ending remaining connections. Failures remain complete
+and observable. The SDK claims no completion for a service that ignores its
+cancellation or never settles. It never kills the application process merely
+because one page disconnects.
+
+Definitions supplied in `services` belong to this cleanup owner as soon as the
+handle is returned. Calling `close()` before its preparation microtask still
+drains and disposes those definitions without starting them or loading modules.
+
+This is one development-server process on Windows, Linux or macOS. It is not a
+cross-process host discovery/start-or-reuse service, nor control of existing
+Codex desktop tasks. Android requires its separate host adaptation. See
+[Core runtime](core-runtime.md) and [Core client](core-client.md) for the underlying
+public contracts.

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

@@ -282,6 +282,19 @@ results and CPU/Metal platform boundaries.
 
 ### Injected native speech engines
 
+Selecting `whisper.cpp` in `native.localAI.runtimes` composes the SDK's retained
+Whisper engine as STT in the shared speech service. Portable assembly retains
+the selected helper, runtime variants and their libraries, FFmpeg decoder and
+configured model files under the app's native runtime tree. The executable
+host, helper, decoder and models remain separate files; selecting speech does
+not embed them inside one application executable. Runtime paths relocate with
+the payload. The default Windows x64 preparation uses the matching SDK release's
+helper plus its MSVC/OpenMP redistributable closure. Other platforms require
+their matching helper, runtime variants and decoder; the public helper builder
+uses matching Whisper headers/libraries with the caller's native toolchain.
+See [native Whisper preparation and packaging](local-whisper.md). Assembly is
+distinct from execution on the target host.
+
 An application-owned service factory can return
 `createSpeechService({stt,tts,signal})` from `arcane-os/core/speech`, supplying
 either role or both. Include that factory through the existing