arcane-os 0.64.0 → 0.65.0

package/docs/reference/core-repositories.md

@@ -13,7 +13,7 @@ methods. Importing the module and constructing an owner perform no I/O.
 | Host | Default dataRoot | repositoriesRoot |
 |---|---|---|
 | Windows | `%LOCALAPPDATA%/ArcaneData`, or `~/AppData/Local/ArcaneData` when that variable is empty | `<dataRoot>/Repos` |
-| Linux | `$XDG_DATA_HOME/ArcaneData` when XDG_DATA_HOME is absolute, otherwise `~/.local/share/ArcaneData` | `<dataRoot>/Repos` |
+| Linux | `$XDG_DATA_HOME/ArcaneData` when `XDG_DATA_HOME` is absolute, otherwise `~/.local/share/ArcaneData` | `<dataRoot>/Repos` |
 | macOS | `~/Library/Application Support/ArcaneData` | `<dataRoot>/Repos` |
 | Android or another adapted host | Explicit `dataRoot` supplied by the host, such as its app files directory followed by `ArcaneData` | `<dataRoot>/Repos` |
 
@@ -47,7 +47,7 @@ await repository.close();
 ```
 
 `createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run}={})`
-returns `{directory,open,status,pull,push,close,drain,dispose}`. The `directory`
+returns `{directory,open,status,pull,push,write,close,drain,dispose}`. The `directory`
 property is the absolute selected working path.
 
 - Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
@@ -67,7 +67,8 @@ property is the absolute selected working path.
   authentication remain with Git and the native host. The SDK adds no download,
   credential store, polling, network retry or process supervisor.
 
-All operation methods accept `{signal}={}` and return promises:
+The open/status/pull/push methods accept `{signal}={}` and return promises;
+`write` accepts the complete file/message request described below:
 
 | Method | Result and side effect |
 |---|---|
@@ -75,6 +76,7 @@ All operation methods accept `{signal}={}` and return promises:
 | `status` | Prepares the checkout if needed, then returns the existing `repositoryStatus` result unchanged. |
 | `pull` | Prepares the checkout if needed, then runs the existing clean-checkout, fast-forward-only `repositoryPull` operation unchanged. |
 | `push` | Prepares the checkout if needed, then runs the existing `repositoryPush` operation unchanged, preserving its support for unrelated uncommitted working files. |
+| `write` | Writes exact caller-selected text files, stages and commits only their literal paths, then performs one ordinary non-force push. Returns confirmed operation outcomes; see below. |
 | `close`, `drain`, `dispose` | The same idempotent operation: stop accepting new calls and await accepted work and its process/event cleanup. They retain the repository on disk. |
 
 Opening an existing repository never pulls, switches branches, resets, changes
@@ -85,6 +87,111 @@ A failed or cancelled clone reports the actual failure; any remaining directory
 is retained for application-owned inspection. There is no automatic deletion or
 destructive retry. Filesystem failures and complete Git diagnostics propagate.
 
+## Write, commit and push selected text
+
+```javascript
+const result = await repository.write({
+    files: [{path: 'dispatches/moon-cheese.md', content: completeAuthoredText}],
+    message: authoredCommitMessage,
+    signal
+});
+```
+
+`write({files:[{path,content}],message,signal}={})` requires at least one explicit
+file, a nonempty commit message and string content (including an empty string).
+Paths name working files relative to this repository, not its root, outside
+paths or Git-owned `.git` metadata. Strings must be representable as UTF-8;
+native filenames cannot contain NUL. Incompatible input reports a `TypeError`
+before any write, rather than replacing text. Content may contain NUL, BOM,
+CRLF, leading/trailing whitespace and every ordinary Unicode character.
+
+The method copies the selected records and their original strings synchronously
+when called. Later changes to the caller's array, file records or selected UI
+connection cannot alter accepted work. It does not freeze the caller's objects,
+add document labels, normalize line endings, trim content or wrap documents.
+The workspace's originally selected directory remains the operation owner.
+
+After preparing that checkout, it creates needed parent directories and writes
+each complete file using the ordinary native UTF-8 filesystem API. These are
+caller-owned replacements, not an append-only policy or a multi-file atomic
+transaction. Applications choose which paths and content may be replaced.
+Ordinary filesystem behavior, including existing symlinks, remains with the
+native host.
+
+One `git --literal-pathspecs add -- <paths>` stages only those exact names.
+One `git --literal-pathspecs commit --only --cleanup=verbatim --file - -- <paths>`
+commits only those paths, leaving unrelated staged paths staged. The original
+message is streamed unchanged through standard input. One ordinary `git push`
+then uses that repository's existing remote/ref configuration, identity,
+credentials and hooks. There is no implicit pull, branch switch, forced push,
+hook bypass, automatic retry, rollback or reset. If Git reports no changes to
+commit, that actual failure is returned; the SDK creates no empty commit.
+These are Git's documented [selected-path commit](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---only)
+and [literal pathspec](https://git-scm.com/docs/git#Documentation/git.txt---literal-pathspecs) semantics.
+
+Existing Git attributes, clean filters, EOL settings and hooks continue to apply
+when Git stages/commits content. The filesystem write preserves the original
+text; this API does not claim that repository-configured filters leave Git blob
+text identical. It preserves those settings. A push may also send existing history or other
+refs selected by the repository's ordinary push configuration.
+
+### Result and failure outcomes
+
+Successful completion returns:
+
+```text
+{
+    directory,
+    state: 'pushed',
+    stage: 'complete',
+    paths: [originalSelectedPath, ...],
+    writtenPaths: [confirmedWrittenPath, ...],
+    written: true,
+    staged: true,
+    committed: true,
+    pushed: true,
+    outputs: [{stage: 'prepare'|'stage'|'commit'|'push', stdout, stderr, code?, signal?}, ...]
+}
+```
+
+Each output record retains complete stdout/stderr. `code` and the process
+termination `signal` are included when a completed process result is available.
+An in-progress write also records its current `path` on a failure outcome.
+`writtenPaths` records successful filesystem writes in input order; `written`
+becomes true only after every requested write succeeds. The other booleans
+record successful Git command completion. **False means success is unconfirmed,
+not that files, the index, HEAD or the remote certainly remained unchanged.**
+
+- `local`: no successful commit or push has been confirmed. Inspect
+  `writtenPaths`, `written`, `staged` and `stage` for actual local progress.
+- `committed`: Git completed the commit; no successful push has been confirmed.
+  Cancellation before push keeps this result rather than claiming delivery.
+- `pushed`: Git reported successful completion of the push. A later observer
+  error retains that confirmed result while still reporting the observer error.
+- `uncertain`: an attempted file write, commit or push did not supply successful
+  completion evidence. Partial files or index changes can remain, and a remote
+  can accept updates before a connection failure hides the acknowledgement.
+  Previously confirmed `writtenPaths`, `committed` or `pushed` evidence remains
+  present. A known pre-spawn failure does not invent a dispatched side effect.
+
+After operation acceptance and execution begins, failures reject with an
+`ArcaneError` whose `cause` is the original complete failure and whose `details`
+is the outcome above. The code/message retain the original failure when
+available, and nested process details remain available through its cause.
+Input errors, a pre-aborted/queued-aborted request or a call after closing reject
+before writer execution and have the existing TypeError/cancellation/closing
+contract. No success is fabricated from an error string or callback.
+
+Cancellation is checked before each subsequent filesystem/Git action. Active
+Git cancellation drains through the existing process owner. Completion is
+recorded before checking cancellation for the next action: an accepted commit
+is retained if push has not begun, and an accepted push is retained if an
+observer subsequently fails. Failed operations leave their actual files and
+index state available for inspection; the application chooses recovery.
+Await or retain the write promise and connect the workspace's terminal drain
+to its Core service lifetime. The application still owns any decision to make
+that Core method service-lifetime rather than request-lifetime work.
+
 ## Ownership, concurrency and shutdown
 
 Calls targeting the same resolved path spelling in one Node process run in
@@ -107,6 +214,8 @@ The caller retains each operation's complete result or failure separately.
 The cold path is one selected connection, one parent-directory creation and one
 Git clone. Opening an existing checkout uses one read-only Git command. A
 prepared owner's status/pull/push use their existing repository operation graph.
+An accepted writer uses one filesystem write per explicitly selected file,
+then one add, one commit and one push, stopping at the first failure.
 There is no scan across applications, connections, models or platforms. Git
 progress, process-starting/completion, heartbeat and cancellation events use
 the existing `onEvent` owner with complete output and backpressure.

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

@@ -1,17 +1,129 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.63.0",
+  "sdkVersion": "0.64.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 278,
+  "memberCount": 288,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-whisper:createWhisperRuntime",
+      "name": "createWhisperRuntime",
+      "displayName": "createWhisperRuntime()",
+      "kind": "function",
+      "signature": "createWhisperRuntime({runtime,prepare,modelId,temporaryDirectory,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/whisper"],
+      "primaryImport": "arcane-os/local-ai/whisper",
+      "group": "Core native speech",
+      "summary": "Retains a selected native Whisper helper/model across complete recordings with actual correlated recovery and joined cancellation.",
+      "availability": "Node with prepared matching helper, Whisper libraries, decoder and model; Android needs host process adaptation",
+      "protocol": "Persistent first-party native helper with replaying whisper.state and complete transcription results",
+      "normalization": "Returns current/subscribe/load/transcribe/unload/close; preserves complete original media and text/segment results; one accepted transcription, exact requestId control metadata, eligible auto GPU-to-CPU recovery once, truthful unloaded recovery and terminal errors, joined decoder/helper cleanup"
+    },
+    {
+      "id": "local-ai-whisper:default",
+      "name": "default",
+      "displayName": "createWhisperRuntime default export",
+      "kind": "function",
+      "signature": "default as createWhisperRuntime",
+      "entrypoints": ["arcane-os/local-ai/whisper"],
+      "primaryImport": "arcane-os/local-ai/whisper",
+      "group": "Core native speech",
+      "summary": "Default binding for the same retained native Whisper engine factory.",
+      "availability": "Node with the matching prepared native resources",
+      "protocol": "Native Whisper engine lifecycle",
+      "normalization": "Binding identity equals the named createWhisperRuntime export"
+    },
+    {
+      "id": "local-ai-whisper-build:buildWhisperHelper",
+      "name": "buildWhisperHelper",
+      "displayName": "buildWhisperHelper()",
+      "kind": "function",
+      "signature": "async buildWhisperHelper({runtime,outputRoot,cmake='cmake',generator,cmakeArgs=[],env,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/whisper/build"],
+      "primaryImport": "arcane-os/local-ai/whisper/build",
+      "group": "Core native speech",
+      "summary": "Builds and installs the first-party persistent helper against matching prepared Whisper headers and runtime libraries.",
+      "availability": "Node with installed CMake/C++17 toolchain matching the selected platform and architecture",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Returns platform/architecture/root/executable/runtimeDirectory and complete configure/compile/install diagnostics; preserves cancellation and process failures, installs no model or toolchain, performs no inference"
+    },
+    {
+      "id": "codex-app-server:createCodexAppServerSession",
+      "name": "createCodexAppServerSession",
+      "displayName": "createCodexAppServerSession()",
+      "kind": "function",
+      "signature": "createCodexAppServerSession({executable,args,cwd,env,clientInfo,capabilities}={})",
+      "entrypoints": ["arcane-os/codex/app-server"],
+      "primaryImport": "arcane-os/codex/app-server",
+      "group": "Native Codex sessions",
+      "summary": "Creates an explicit native Codex App Server JSONL session without starting its process until connect.",
+      "availability": "Node with caller-selected native executable on Windows, Linux and macOS; Android requires host process adaptation",
+      "protocol": "Native Codex App Server JSONL",
+      "normalization": "Complete request/result/notification objects; ordered live delta/item callbacks, actual terminal turn outcomes and exact stored-turn recovery. Server requests retain real IDs and explicit replies. No automatic thread selection, retry, approval or desktop-task attachment."
+    },
+    {
+      "id": "codex-app-server:openCodexAppServerSession",
+      "name": "openCodexAppServerSession",
+      "displayName": "openCodexAppServerSession()",
+      "kind": "function",
+      "signature": "async openCodexAppServerSession(options)",
+      "entrypoints": ["arcane-os/codex/app-server"],
+      "primaryImport": "arcane-os/codex/app-server",
+      "group": "Native Codex sessions",
+      "summary": "Creates and connects the same explicit native session, disposing it before rejecting failed initialization.",
+      "availability": "Node with caller-selected native Codex executable",
+      "protocol": "Native Codex App Server JSONL",
+      "normalization": "Returns the connected session; creates or resumes no thread and changes no provider or authentication selection."
+    },
+    {
+      "id": "mcp-stdio:createMcpStdioServer",
+      "name": "createMcpStdioServer",
+      "displayName": "createMcpStdioServer()",
+      "kind": "function",
+      "signature": "createMcpStdioServer({serverInfo,instructions,tools=[],resources=[],onDiagnostic}={})",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "Owns one MCP STDIO session for caller-authored tools and static resources.",
+      "availability": "Node streams on Windows, Linux and macOS; Android requires host adaptation",
+      "protocol": "MCP 2025-11-25 initialize-era JSON-RPC newline transport",
+      "normalization": "Explicit CallToolResult/ReadResourceResult preserve complete content. Returns start, cancel, drain, close and closed; concurrent handlers, ordered output, cooperative cancellation and graceful EOF drain. No process launch or application-service ownership."
+    },
+    {
+      "id": "mcp-stdio:MCP_PROTOCOL_VERSION",
+      "name": "MCP_PROTOCOL_VERSION",
+      "displayName": "MCP_PROTOCOL_VERSION",
+      "kind": "constant",
+      "signature": "MCP_PROTOCOL_VERSION",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "The explicit supported MCP initialization profile, 2025-11-25.",
+      "availability": "Node",
+      "protocol": "MCP initialization version negotiation",
+      "normalization": "Later profiles and optional unimplemented capabilities are not implied."
+    },
+    {
+      "id": "mcp-stdio:McpProtocolError",
+      "name": "McpProtocolError",
+      "displayName": "McpProtocolError",
+      "kind": "class",
+      "signature": "new McpProtocolError(code,message,data)",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "Represents an explicit JSON-RPC failure with complete message and optional data.",
+      "availability": "Node",
+      "protocol": "JSON-RPC error object",
+      "normalization": "Preserves code, message and supplied data; ordinary tool domain failures use CallToolResult.isError."
+    },
     {
       "id": "core-repositories:resolveArcaneDataPaths",
       "name": "resolveArcaneDataPaths",
@@ -38,7 +150,7 @@
       "summary": "Owns one selected native working checkout with ArcaneData/Repos defaults and existing Git/process lifecycle.",
       "availability": "Node with Git on Windows, Linux and macOS; Android requires host process adaptation",
       "protocol": "Git working repository and SDK process adapter",
-      "normalization": "Returns directory, open, status, pull, push and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are inspected without rewriting, resetting or pulling. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work."
+      "normalization": "Returns directory, open, status, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are inspected without rewriting, resetting or pulling. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. write snapshots exact selected text and paths, writes files, stages/commits only literal owned paths and non-force pushes, preserving unrelated staged files and ordinary Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes."
     },
     {
       "id": "core-speech:createSpeechService",
@@ -4082,6 +4194,34 @@
       "protocol": "arcane/1 renderer client ownership",
       "normalization": "Recognizes ESM and classic SDK installation identity; returns null after close or terminal failure and does not treat a foreign Arcane facade as an SDK client"
     },
+    {
+      "id": "core-client:subscribeCoreClient",
+      "name": "subscribeCoreClient",
+      "displayName": "subscribeCoreClient()",
+      "kind": "function",
+      "signature": "subscribeCoreClient(listener,{global=globalThis,emitCurrent=true,signal}={})",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Observes exact SDK client installation and retirement with current-state replay without creating a transport.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "Core client installation lifecycle",
+      "normalization": "Preserves client and error identities; reports current, installed, closed and transport-failed with previousClient; returns idempotent unsubscribe and supports AbortSignal. Installation does not imply runtime, service or model readiness"
+    },
+    {
+      "id": "core-development:createDevelopmentCore",
+      "name": "createDevelopmentCore",
+      "displayName": "createDevelopmentCore()",
+      "kind": "function",
+      "signature": "createDevelopmentCore({appRoot=process.cwd(),application,version,services=[],serviceModules=[],context={},getReplayEvents,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/core/development", "arcane-os"],
+      "primaryImport": "arcane-os/core/development",
+      "group": "Core source development",
+      "summary": "Composes application Core services and document-owned HTTP/SSE transport independently of local AI.",
+      "availability": "Node on Windows, Linux and macOS; Android requires host adaptation",
+      "protocol": "arcane/1 over source-development HTTP/SSE",
+      "normalization": "Returns ready, handler, current and close synchronously; preserves factory options and explicit context, current lifecycle replay, correlated responses and chunks, document cancellation, accepted service work and owned drain. Explicit bootstrap does not block rendering or start application processes"
+    },
     {
       "id": "core-classic-source:createCoreClassicSource",
       "name": "createCoreClassicSource",

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

@@ -120,6 +120,7 @@
         "AI_RUNTIME_STARTUP_EVENT",
         "AI_RUNTIME_STATES",
         "AI_RUNTIME_STATE_EVENT",
+        "continuesAIRuntimeOperation",
         "getAIRuntimeState",
         "publishAIRuntimeRoleState",
         "publishAIRuntimeRolesState",
@@ -131,8 +132,8 @@
       "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; events report state but grant no authority.",
-      "surface": "Protocol/event/role/state constants; snapshot, state subscribe/publish, intent request/subscribe, and `startAIRuntime({startMuted,startTranscription,signal})` returning `{barrier,settled,cancel}`."
+      "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.",
+      "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}`."
     },
     {
       "file": "runtime/arcane/modules/AnsiText.js",

package/docs/reference/local-ai.md

@@ -1,7 +1,7 @@
 # Local AI through Core
 
-Core owns native llama.cpp and Ollama processes, ONNX worker sessions and
-selected local image generation. The browser retains its own
+Core owns native llama.cpp and Ollama processes, ONNX worker sessions,
+selected local image generation and retained Whisper transcription. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
@@ -43,7 +43,7 @@ preserved when its version cannot be established.
 
 Both public application/package schemas accept `stable-diffusion.cpp` as a
 string or runtime-record ID. Its record additionally accepts `backend`
-(`auto`, `cpu` or `metal`) and `models`, an array of `sd14`, `flux2-klein-4b` or
+(`auto`, `cpu` or `metal`) and `models`, an array of `sd14`, `flux2-klein-4b`, `sdxl-base-1.0` or
 complete model descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
 selects `auto`; omitted models leaves model selection empty. Windows/Linux
 distribution defaults use CPU; the selected universal Mac archive supports
@@ -55,6 +55,30 @@ The [FLUX.2 Klein 4B guide](local-image-flux.md) describes its diffusion model,
 VAE and Qwen text-conditioning resources, four-step defaults and `txt2img`
 operation. Each model retains its own supported operation set.
 
+The [SDXL Base 1.0 guide](local-image-sdxl.md) describes its complete checkpoint,
+embedded text encoders and original VAE, 1024-by-1024 default canvas and
+`txt2img` operation. Selecting a family retains the shared native context,
+progress, cancellation and complete PNG result contract.
+
+For native transcription, select a `whisper.cpp` runtime record with a `models`
+array and an explicit `modelId` when selecting more than one model. For example,
+`{id: 'whisper.cpp', backend: 'auto', models: ['whisper-small'], modelId: 'whisper-small'}`
+selects the multilingual small model. Installation prepares its native
+libraries, persistent SDK helper, FFmpeg decoder and selected model files;
+loading and transcription remain separate operations. Development and native
+assembly compose it through the shared speech service without changing the
+browser's selected STT route. See [native Whisper](local-whisper.md) for the
+complete configuration, platform, media and shutdown contracts.
+
+The selected model stays loaded across recordings. An eligible native
+accelerated failure may drain that helper and retry the same complete recording
+once on the prepared CPU backend. That accepted request retains its actual
+request identity while `recovering` is unloaded and busy; new inference remains
+blocked until actual readiness. Cancellation, unload, close, replacement and
+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.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
 mode. Paths resolve from the application root. Ollama accepts `url`,
@@ -193,6 +217,52 @@ Those methods use Ollama's native API. Streaming uses the existing
 such as selection, settings and brain creation remain with their existing
 owners; they are separate from this runtime service.
 
+### Selected Ollama model readiness
+
+The built-in `OLLAMA` LLM provider loads its selected model through Ollama's
+empty `generate` request and separately confirms that selected model in
+`running()` (`/api/ps`). A model catalog entry, a connected bridge, and a
+successful preload response alone do not establish a ready model. Ollama's
+empty preload response echoes the requested name; resident snapshots use its
+shortest tagged name. Comparison applies Ollama's default `registry.ollama.ai`
+host, `library` namespace and `latest` tag, so `moon-raccoon` and
+`registry.ollama.ai/library/moon-raccoon:latest` identify the same resident
+model. This comparison leaves outbound model names and payloads unchanged.
+The provider preserves Ollama's configured/default retention duration.
+
+Core refreshes and emits `localai.state` after its Ollama generation, chat,
+embedding and catalog-changing operations, including a failed or cancelled
+operation while the service remains available. Explicit `running()` inspection
+also publishes the actual resident-model snapshot. An SDK-owned process exit
+publishes its unavailable state through the existing process owner.
+Successes and failures belong to their observation order and engine lifetime;
+an older observation cannot replace newer state or a recovered engine's state.
+The complete current failure remains available through the owning state surface.
+
+The LLM provider subscribes before loading and retains that observation while
+loaded. An observed selected-model unload, replacement, unavailable service or
+service error revokes readiness and cancels the active request through the shared
+AI runtime. Each inference checks current residency before dispatch and again
+before accepting its terminal result. These `running({signal})` calls carry the
+owning request's cancellation through Core to `/api/ps`. Streaming chunks still
+arrive immediately through their existing path. Explicit provider unloading sends Ollama's
+`keep_alive: 0` release request; another client can independently reload a model.
+
+Ollama's documented public API exposes resident snapshots, not an ongoing
+resident-model event subscription. Core adds no timer polling. External changes
+between observations, including idle eviction or another client's model load,
+remain unobserved until a subsequent owned operation or explicit inspection.
+There is also an upstream race between a snapshot and the following request;
+these checks do not claim an atomic reservation of the daemon's model state.
+Applications consume the shared provider lifecycle rather than treating a stale
+idle snapshot as proof for their next inference. `Ollama.readiness()` remains a
+service-connectivity result and does not establish selected-model readiness.
+
+Upstream references: [resident models](https://docs.ollama.com/api/ps),
+[model-name defaults and comparison](https://github.com/ollama/ollama/blob/main/types/model/name.go),
+[preload response and resident-name handling](https://github.com/ollama/ollama/blob/main/server/routes.go),
+[preload and retention](https://docs.ollama.com/faq#how-can-i-preload-a-model-into-ollama-to-get-faster-response-times).
+
 ## Browser llama.cpp provider
 
 ```js

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

@@ -47,6 +47,11 @@ four-step defaults and the advertised `txt2img` operation. Keep each model's
 supported operations distinct: selecting FLUX does not enable reference-image
 editing or imply the same input path as SD1.4 img2img.
 
+`sdxl-base-1.0` selects the complete SDXL Base checkpoint, including its text
+encoders and original VAE. Its [family guide](local-image-sdxl.md) covers the
+single model resource, 1024-by-1024 default canvas and native sampling defaults.
+It advertises `txt2img`; selecting it does not enable an editing operation.
+
 The first published distribution path selects CPU on Windows and Linux.
 On macOS, `auto` selects the same upstream universal runtime's built-in Metal
 backend, with CPU fallback; explicit `cpu` remains available. A caller-supplied

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

@@ -38,7 +38,7 @@ selection alone does not establish actual execution on any device.
 ## Prepare the checkpoint and generate an image
 
 The single `model` resource is the official
-[sd_xl_base_1.0.safetensors checkpoint](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors)
+[`sd_xl_base_1.0.safetensors` checkpoint](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors)
 at revision `462165984030d82259a11f4367a4eed129e94a7b`. It includes the text
 encoders, denoiser and original VAE. Standalone base generation uses this one
 resource; a refiner, separate VAE, LoRA or Python converter is unnecessary for