arcane-os 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.64.0
+
+- Add retained native Whisper transcription through the existing Core speech
+  service and AI API, with actual model readiness, complete recordings and
+  transcripts, native progress, joined cancellation, and one eligible
+  accelerated-inference recovery on the prepared CPU runtime.
+- Preserve the same accepted transcription through internal recovery using
+  its actual Core request identity. Shared AI and speech controls report
+  recovering/error states honestly without discarding the original request
+  or turning its terminal native failure into cancellation.
+- Add the SDXL Base 1.0 text-to-image descriptor and correct the shared native
+  image binding's asynchronous worker stack allocation while preserving
+  existing model selection, complete inputs and native lifecycle.
+- Add `arcane-os/core/repositories` with per-user `ArcaneData/Repos` defaults
+  and connected working-repository open/status/pull/push/drain ownership.
+  Explicit paths and existing data remain unchanged; applications own
+  connection selection, remotes and product records. No data migration.
+- Keep optional NPU, repository file-write orchestration, generic development
+  Core composition, Codex/MCP and Ollama lifecycle drafts outside this release.
+  The npm dependency tree is unchanged; native resources use their documented
+  upstream installation and matching numeric-release helper assets.
+
+## 0.63.0
+
+- Add the approved FLUX.2 Klein 4B text-to-image model descriptor to the
+  existing retained local image runtime, with its separate diffusion, VAE
+  and text-encoder resources and four-step Euler defaults. Applications keep
+  their model choice, complete prompts and image persistence.
+- Name assembled Windows launchers from the application display name, with a
+  matching executable configuration and manifest-selected launch path.
+  Preserve supported spaces, case and Unicode, existing generic artifacts,
+  icon embedding and the unchanged shared host archive.
+- Add `createSpeechService({stt, tts, signal})` through `arcane-os/core/speech`
+  for independently supplied native engines, immediate service registration,
+  sticky role state, complete requests/results, cancellation and joined close.
+  This service does not install or select a speech engine.
+- Preserve existing image generation/editing and native host behavior. No
+  additional GPU setup, SDXL, Whisper engine, Kokoro/Sherpa adoption or browser
+  AI native-speech readiness correction is included in this increment.
+
 ## 0.62.0
 
 - Add whole-image PNG editing through the existing local image runtime, Core

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.62.0` SDK contract. Development applications declare
+This checkout defines the `0.64.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/core/client.mjs

@@ -459,7 +459,10 @@ export function createCoreClient({
         if(eventOwnerFailure)return Promise.reject(eventOwnerFailure);
         let selected;
         try{selected=connect();}catch(error){return Promise.reject(error);}
-        const {signal,timeoutMs=10*60*1000}=options??{};
+        const {signal,timeoutMs=10*60*1000,onRequest}=options??{};
+        if(onRequest!==undefined&&typeof onRequest!=='function'){
+            return Promise.reject(new TypeError('Arcane request observer must be a function.'));
+        }
         if(signal&&(typeof signal.aborted!=='boolean'
             ||typeof signal.addEventListener!=='function'
             ||typeof signal.removeEventListener!=='function')){
@@ -483,6 +486,8 @@ export function createCoreClient({
             if(!settle(id,failure))report(failure);
         }
         try{
+            if(onRequest)Promise.resolve(onRequest({requestId:id})).catch(report);
+            if(!pending.has(id))return promise;
             Promise.resolve(selected.send(frame)).catch(sendFailed);
         }catch(error){sendFailed(error);}
         return promise;
@@ -569,7 +574,7 @@ export function createCoreFacade(client){
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
             synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
-            transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal})},
+            transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal,onRequest:options?.onRequest})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),
             ensurePlatform:()=>invoke('localai.platform.ensure',{},long),recover:request=>invoke('localai.services.recover',request??{},long),
             setParallelRequests:request=>invoke('localai.parallel.requests.set',request??{},long),

package/docs/reference/README.md

@@ -55,6 +55,11 @@ alone does not make bare module names resolve in a browser.
 | Cancel one Core speech synthesis request without changing its payload | [Speech request lifetime](core-client.md#events-and-request-lifetime) and [Core facade](sdk-api.md#createcorefacade) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
+| Generate complete local PNG images with a retained native model | [Local image generation](local-image-generation.md) |
+| Select FLUX.2 Klein 4B and its three complementary model resources | [FLUX.2 Klein 4B through Core](local-image-flux.md) |
+| Compose independently loaded transcription and synthesis engines | [Native speech service](native-speech.md) |
+| Edit an original PNG with a complete prompt and explicit strength | [Local image editing](local-image-editing.md) |
+| Project complete stored model files into native working files | [Model assets through Core](model-assets.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
@@ -223,6 +228,8 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
 | Run application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
 | Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
+| Generate local images from complete prompts and selected model resources | [`arcane-os/local-ai/image`, `arcane-os/ai/core-image`](local-image-generation.md) | Prepared native image runtime; browser access requires its Core service. CPU Windows/Linux and Mac Metal/CPU paths have distinct actual host requirements. |
+| Supply complete stored model members to a native engine | [`arcane-os/ai/core-model-assets`, `arcane-os/core/model-assets`](model-assets.md) | Available Core service; DBOPFS originals stay authoritative while native owners retain working files. |
 | Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers and selected upstream sources; automatic WebNN NPU, WebGPU, then WASM loading, or an explicit backend. |
 | Use native browser recognition/voices or selected cloud TTS | [Speech provider choices](ai/browser-speech.md) | Native APIs depend on the browser and may use remote services; cloud TTS requires the application key and endpoint access. |
 | Send complete chat, System One or image requests without retained history | [`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) | Node or browser with Fetch and explicit model/credentials; image results contain every returned image as a Blob. |

package/docs/reference/cli.md

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

package/docs/reference/core-client.md

@@ -67,7 +67,7 @@ current dispatcher and service state for a newly connected document, without
 restarting services. Repeated `connect()` calls on the same connection do not
 send another replay. See [runtime replay](core-runtime.md#state-and-frames).
 
-`client.invoke(method, parameters, {signal, timeoutMs})` returns the actual
+`client.invoke(method, parameters, {signal, timeoutMs, onRequest})` returns the actual
 response result or rejects with `CoreError`. Parameters, result fields and
 event data retain their complete supplied content. JSON encoding belongs only
 to transports that require it; values crossing those transports must be
@@ -77,6 +77,14 @@ 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.
 
+The optional `onRequest({requestId})` observer runs synchronously after the
+client owns the request and before transport dispatch. It exposes the actual
+Core correlation ID without adding fields to the supplied payload. A
+pre-aborted request never calls the observer. A synchronous observer failure
+rejects the request before sending; a returned promise is observed for errors
+without delaying dispatch. If the observer cancels or closes the request,
+the client does not subsequently send it.
+
 `Arcane.speech.synthesize(request, {signal})` forwards the optional cancellation
 signal through the same request lifetime. Existing one-argument calls retain
 the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
@@ -87,12 +95,13 @@ registered speech service and its engine; the facade supplies no speech engine.
 call and normalizes cancellation to `AbortError` with
 `ARCANE_AI_REQUEST_ABORTED`, preserving the original error as its cause.
 
-`Arcane.speech.transcribe(request, {signal})` forwards cancellation through the
+`Arcane.speech.transcribe(request, {signal, onRequest})` forwards cancellation through the
 same request lifetime and retains its 180,000 ms timeout and complete request.
 `AI.fetchSTT(audio, signal)` carries that signal into the native call. A
 pre-aborted signal sends no transcription request; an in-flight abort sends
 `request.cancel` and suppresses late responses. The registered transcription
 service owns interruption and release of its actual engine operation.
+Its optional request observer uses the same pre-dispatch correlation contract.
 
 ## Current-window theme
 

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

@@ -248,8 +248,9 @@ to the artifact root. Only the explicitly configured entry imports
 `createLocalAIService` from `arcane-os/core/local-ai`. It resolves those bundled
 locations against the installed artifact and supplies them in the launch
 context's `runtimes` array, alongside `appRoot`, before applying explicit launch
-configuration. It passes the complete authored `native.localAI` record to the
-factory. Applications without that selection have no generated local-AI import
+configuration. It passes chat/ONNX requirements to that factory and routes
+selected image requirements to their separate service as described below.
+Applications without that selection have no generated local-AI import
 or service. Availability of a particular engine belongs to the selected
 local-AI installer and service; a generic ONNX runtime is not a speech model.
 
@@ -260,6 +261,42 @@ service exposes retained worker sessions through `onnx.load/run/unload/status`;
 model files remain caller-selected application resources. See
 [native ONNX sessions](local-ai.md#native-onnx-sessions).
 
+Selected `stable-diffusion.cpp` additionally composes
+`createLocalImageService` from `arcane-os/core/image` and one shared
+`createModelAssetService` from `arcane-os/core/model-assets`. The image factory
+receives the full authored selection plus that same model-assets instance.
+Library, Koffi binding and variant paths resolve from the artifact root;
+ordinary browser imports use `arcane-os/ai/core-image` and
+`arcane-os/ai/core-model-assets` through the managed import map.
+
+The runtime bundle preserves the complete selected native distribution and
+binding tree. It does not load or download a model. Original model URL
+descriptors remain available for preparation after launch; runtime-contained
+model paths relocate with the artifact. An external native working path
+reports its portability incompatibility. Supply those files through the
+application's native resources or the shared
+[stored-model projection](model-assets.md). Native use retains that projection
+until actual unload or shutdown completes. See
+[local image generation](local-image-generation.md) for selection, complete
+results and CPU/Metal platform boundaries.
+
+### Injected native speech engines
+
+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
+`native.services` and `package.nativeResources` composition above. The host
+constructs its selected engines; this shared service installs no engine,
+downloads no model and selects no browser or native speech default.
+
+Core starts both configured role loads independently and remains responsive.
+`speech.status` and replaying service subscriptions report actual loaded-model
+state separately for transcription and synthesis. Complete requests/results
+are forwarded unchanged. Request cancellation reaches its engine independently
+of the service lifetime; `close`/`drain` abort and join both engines and their
+pending work. Engines must settle cancelled inference before Core reaches
+service cleanup. See the [engine interface, progress and shutdown contract](native-speech.md).
+
 ## Windows executable
 
 The ordinary application command is:
@@ -293,12 +330,24 @@ host output; downstream applications use the published package and matching
 release asset. `doctor()` reports the selected prerequisites and missing files;
 it does not download the host or probe the installed WebView runtime.
 
-The assembled directory contains `Arcane.exe`, the unchanged `app/` payload,
-Core runtime and semantic `arcane-native.json`. Launch `Arcane.exe` on Windows
-x64 with the Microsoft Edge WebView2 Runtime installed. It opens the selected
+The assembled directory contains the app-named launcher, its matching
+`.exe.config`, the unchanged `app/` payload, Core runtime and semantic
+`arcane-native.json`. `manifest.host.executable` is the authoritative relative
+launcher name for shortcuts and direct launch. Assembly uses
+`appDescriptor.displayName` plus `.exe`, such as `Moon Cheese Hotline.exe`;
+low-level compositions without a nonempty string display name use the app ID.
+Windows-reserved filename characters and controls become underscores, and
+reserved DOS device basenames receive an underscore prefix. Supported Unicode,
+case and spaces remain; the original descriptor and title are unchanged.
+The reusable host archive/cache retains `Arcane.exe` and `Arcane.exe.config`;
+the internal `runtime/ArcaneCore.exe` also keeps its original name.
+
+Launch the manifest-selected executable on Windows x64 with the Microsoft
+Edge WebView2 Runtime installed. It opens the selected
 app in WebView2 and owns its framed connection to the bundled Core process.
 `verify()` observes the assembled files and manifest; it does not execute the
-window or prove application behavior. `run()` launches the executable and
+window or prove application behavior. `run()` reads the saved manifest and
+launches that executable, so existing generic-name artifacts remain usable. It
 observes complete diagnostics and exit. Cancelling that operation closes its
 input, allowing the window and accepted Core service work to drain without a
 forced process termination.
@@ -311,7 +360,7 @@ into a derived `runtime/arcane-app.ico` with 16, 32, 48 and 256-pixel images.
 Aspect ratio and transparency are preserved. An ICO selection keeps its
 authored image set. The original application asset remains unchanged.
 
-The provider embeds the selected images in the copied `Arcane.exe` and records
+The provider embeds the selected images in the copied app-named executable and records
 `manifest.host.icon` and `manifest.host.executableIcon:true`. It replaces the
 executable's main icon group while preserving other groups, languages, resources
 and file content. Conversion uses Node standard capabilities on every assembly
@@ -370,7 +419,7 @@ for the facade and browser behavior.
 For explicit user-selected workspace/state locations, launch:
 
 ```sh
-Arcane.exe --arcane-launch-config path/to/launch.json
+"Moon Cheese Hotline.exe" --arcane-launch-config path/to/launch.json
 ```
 
 The complete JSON object reaches the service factories as their second

package/docs/reference/core-repositories.md

@@ -0,0 +1,149 @@
+# Native repository workspaces
+
+`arcane-os/core/repositories` owns a persistent native location for connected
+repositories, separate from application code and application preferences.
+Applications choose their connection names, remotes, branches, files and Core
+methods. Importing the module and constructing an owner perform no I/O.
+
+## Persistent locations
+
+`resolveArcaneDataPaths({dataRoot}={})` returns absolute
+`{dataRoot,repositoriesRoot}` paths without creating directories:
+
+| 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` |
+| 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` |
+
+An explicit `dataRoot` selects that directory directly; the SDK does not append
+another `ArcaneData`. Relative explicit paths resolve from the process working
+directory. Unsupported default platforms report `ARCANE_DATA_ROOT_REQUIRED`.
+The Android host also supplies Git/process execution through the existing
+process-adapter contract; this module does not install Git or choose shared
+Android storage.
+
+The factory's first actual operation creates necessary parent directories.
+No existing data is moved, copied, deleted, renamed or migrated. `appRoot`,
+`stateRoot`, preferences, OPFS and the existing CLI/workspace defaults remain
+independent and unchanged.
+
+## One connected working checkout
+
+```javascript
+import {createRepositoryWorkspace} from 'arcane-os/core/repositories';
+
+const repository = createRepositoryWorkspace({
+    name: 'moon-cheese-dispatches',
+    remote: applicationConnection.remote,
+    branch: applicationConnection.branch
+});
+
+const opened = await repository.open({signal});
+// opened.directory is <ArcaneData>/Repos/moon-cheese-dispatches.
+const status = await repository.status({signal});
+await repository.close();
+```
+
+`createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run}={})`
+returns `{directory,open,status,pull,push,close,drain,dispose}`. The `directory`
+property is the absolute selected working path.
+
+- Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
+  one nonempty directory name for each distinct connection; the SDK neither
+  derives it from a remote nor maintains a connection registry. Names are one
+  component, excluding `.`/`..` and slash/backslash separators. Choose distinct
+  names under the host filesystem's ordinary case rules.
+- Supply `directory` to use an existing application-selected path instead.
+  This takes precedence over `name` and `dataRoot`; relative paths resolve from
+  the process working directory. The path is not relocated or rewritten.
+- `remote` is required only when a missing or empty destination needs cloning.
+  `branch`, when supplied, is passed unchanged to Git's `clone --branch` option;
+  otherwise Git selects the remote's default branch. Existing checkouts keep
+  their own branch, remote, tracked files, untracked files and local changes.
+- `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,
+  credential store, polling, network retry or process supervisor.
+
+All operation methods accept `{signal}={}` and return promises:
+
+| Method | Result and side effect |
+|---|---|
+| `open` | For a missing/empty destination, runs one clone and returns `{directory,cloned:true,stdout,stderr}` with complete process output. For an existing working repository root, returns `{directory,cloned:false}` after read-only inspection. Later opens on that owner reuse preparation. |
+| `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. |
+| `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
+its remote or rewrites files. A nonempty destination that is a bare repository,
+a subdirectory of another checkout, or ordinary non-repository data is left
+untouched and reports its Git error or `ARCANE_REPOSITORY_DIRECTORY_INVALID`.
+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.
+
+## Ownership, concurrency and shutdown
+
+Calls targeting the same resolved path spelling in one Node process run in
+acceptance order, including separate owners selecting that path. Windows keys
+are case-insensitive. The queue does not resolve symlink aliases or macOS case
+variants; applications use one consistent path for a shared connection.
+This prevents overlapping Git/index writes and duplicate successful cloning.
+Different directories proceed
+independently. Applications coordinate separate processes and their own direct
+file/Git writes; this module does not create a daemon or cross-process lock.
+
+A pre-aborted call starts no work. A queued aborted operation does not run when
+its turn arrives. Active cancellation reaches the existing process owner, which
+terminates its owned process tree and joins complete output/event cleanup.
+Shutdown drains accepted operations rather than deleting data or terminating
+the host early. Calls after close reject with `CORE_CLOSING`; a failed operation
+still pending when close begins rejects that drain through an `AggregateError`.
+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.
+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.
+An awaited event callback must not await another operation or shutdown for the
+same directory, including calls through another workspace owner: that operation
+needs the observing callback to finish. Schedule such follow-up without awaiting
+it inside that callback, and retain/observe its promise at the application owner.
+
+Compose this owner inside an application-selected Core service. Bind only the
+application's chosen methods, pass each request's `context.signal`, and return
+`drain: repository.drain` and `dispose: repository.dispose` from that service.
+Keep initialization at the repository operation that needs it; page rendering
+and unrelated services do not wait for a clone. This module installs no browser
+RPC, chooses no application service and changes no Core launch configuration.
+
+## Bare snapshots stay separate
+
+[`createGitTextSnapshot`](git-text-snapshot.md) continues to require its explicit
+dedicated bare `cacheDirectory`. It neither becomes a working checkout nor
+changes existing callers' caches. A new native caller can place that distinct
+cache under the shared location without changing the snapshot contract:
+
+```javascript
+import path from 'node:path';
+import {createGitTextSnapshot} from 'arcane-os';
+import {resolveArcaneDataPaths} from 'arcane-os/core/repositories';
+
+const {repositoriesRoot} = resolveArcaneDataPaths();
+const snapshot = createGitTextSnapshot({
+    cacheDirectory: path.join(repositoriesRoot, 'moon-cheese-reader-cache'),
+    remote: applicationConnection.remote,
+    ref: applicationConnection.ref,
+    selectPath: applicationSelectPath
+});
+```
+
+Never assign the same directory to a bare snapshot and a writable workspace.
+Applications retain remote/ref selection, document parsing, scores, messages,
+saved connection state and refresh policy. Existing explicit repository paths
+continue to operate where they already are.