arcane-os 0.96.0 → 0.97.1

package/docs/reference/sdk-api.md

@@ -481,6 +481,9 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `KOKORO_SAMPLE_RATE` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Native PCM sample rate |
 | `KOKORO_VOICES` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Complete 28-voice US/GB selection |
 | `createNemotronRuntime()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation |
+| `NEMO_SPEECH_MODELS` | constant | `arcane-os/local-ai/nemotron` | Core native speech | Node; selected upstream model catalog, no acquisition at import |
+| `prepareNemotronModels()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with the shared model-assets service |
+| `prepareMagpieModels()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with the shared model-assets service |
 | `createNemotronRuntime default export` | function | `arcane-os/local-ai/nemotron` | Core native speech | Same named function |
 | `buildNemotronHelper()` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package |
 | `buildNemotronHelper default export` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Same named function |
@@ -494,6 +497,9 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `buildWhisperOpenVinoRuntime()` | function | `arcane-os/local-ai/whisper/openvino-build` | Core native speech | Windows x64 Node with installed matching Whisper/OpenVINO sources and CMake/MSVC toolchain |
 | `createSpeechService default export` | function | `arcane-os/core/speech` | Core native speech | Same shared speech service factory |
 | `prepareCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with complete Blob/File members and available Core service |
+| `discoverCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
+| `openExistingCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
+| `downloadCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
 | `createModelAssetService()` | function | `arcane-os/core/model-assets` | Core model assets | Node Core with an application-selected working directory |
 | `createModelAssetService default export` | function | `arcane-os/core/model-assets` | Core model assets | Same native working-file service factory |
 | `createLocalAIService default export` | function | `arcane-os/core/local-ai` | Core local AI | Same native service factory |
@@ -7923,7 +7929,12 @@ reports `ARCANE_NATIVE_RUN_UNSUPPORTED`.
 
 `build()` copies the complete selected app and dependency releases, the
 published SDK/runtime dependencies and the canonical Core entry/client into a
-fresh output directory. Service factories are imported only when a real native
+temporary assembly, then publishes it at `<outputRoot>/<app-id>/`. Later
+successful builds replace only that app's generated output. Publication retains
+the previous output until the completion callback and cancellation boundary
+accept the replacement; failure restores it. Models and saved state belong in
+their separate persistent directories. See [stable output and recovery](core-native-packaging.md#output-and-host-contract).
+Service factories are imported only when a real native
 host later launches the generated Core entry, never during packaging.
 
 The generated `runtime/arcane-core.mjs` also accepts
@@ -8063,6 +8074,11 @@ the selected output root. There is no compiler or OS checkout requirement for
 application builds. The build machine needs its normal Node/npm toolchain and
 `tar`; execution needs Windows x64, .NET Framework 4.6.2 or later and WebView2.
 
+Successful builds publish the complete payload at `<outputRoot>/<app-id>/`,
+replacing that app's prior generated artifact through the same
+[joined publication lifecycle](core-native-packaging.md#output-and-host-contract).
+Runtime caches, models, saved profiles and unrelated outputs remain separate.
+
 The matching Windows host consumes `appDescriptor.native.window` through
 `manifest.window`. Optional `width` and `height` select initial client dimensions
 in 96-DPI logical units; the host scales them for its actual DPI and fits the
@@ -8158,6 +8174,9 @@ asset is published or its Mac runtime has been executed.
 
 Build preserves the complete portable payload inside the bundle's Resources
 directory (`target.rootDir`) and returns its `.app` location as `bundleRoot`.
+The accepted bundle is `<outputRoot>/<app-id>.app/`; a later successful build
+replaces that bundle through the shared [publication lifecycle](core-native-packaging.md#output-and-host-contract),
+preserving separate saved state and model directories.
 The bundle supplies the SDK launcher and selected Node runtime. `verify()`
 reads assembled files; `run()` directly launches the bundled executable only on
 the matching Darwin architecture, observes diagnostics and waits for graceful
@@ -8321,8 +8340,9 @@ import createDiarizationService from 'arcane-os/core/diarization';
 
 ### Overview
 
-Resolves one application's native state, workspace and optional shared endpoint
-through the same public owner used by its packaged executable and external MCP.
+Resolves one application's native state, workspace and optional shared endpoint,
+plus a same-user shared model directory, through the same public owner used by
+its packaged executable and external MCP.
 This synchronous function performs no I/O, saved-state discovery, process start
 or migration.
 
@@ -8333,7 +8353,7 @@ resolveNativeLaunchContext({appId,context={}}={})
 ```
 
 Import from `arcane-os/core/host`. The result is a new complete context with
-omitted fields filled. Windows defaults to `%LOCALAPPDATA%/Arcane/<appId>`
+omitted fields filled. `stateRoot` defaults on Windows to `%LOCALAPPDATA%/Arcane/<appId>`
 (home `AppData/Local` fallback), macOS to
 `~/Library/Application Support/Arcane/<appId>`, and portable Linux Node to
 absolute `$XDG_DATA_HOME/Arcane/<appId>` or `~/.local/share/Arcane/<appId>`.
@@ -8341,6 +8361,21 @@ Android and other adapted hosts provide their actual `stateRoot` and own native
 IPC/process adaptation.
 
 An omitted `workspaceRoot` becomes `<absolute selected stateRoot>/Workspace`.
+An omitted `modelsDirectory` uses the operating-system user's shared Arcane
+model directory: `%LOCALAPPDATA%/Arcane/Models` on Windows (home `AppData/Local`
+fallback), `~/Library/Application Support/Arcane/Models` on macOS, and absolute
+`$XDG_DATA_HOME/Arcane/Models` or `~/.local/share/Arcane/Models` on Linux. This
+default remains shared when the application explicitly selects another
+`stateRoot`; application state and workspace stay separate. Explicit
+`modelsDirectory` values remain unchanged. Other adapted hosts may supply a
+shared directory explicitly; their omitted value remains
+`<absolute selected stateRoot>/Models`.
+
+This resolver supplies a location to its consumers; it neither changes every
+provider's store nor creates, moves or migrates model files. Services select
+that directory as the shared model-assets working directory, while applications
+may also discover their existing app-local originals. Model storage remains
+separate from replaceable native build output. See [persistent model locations](model-assets.md).
 Only a selected `sharedHost` object receives a default endpoint and log file:
 Windows uses a named pipe containing the URL-encoded complete absolute state
 path; Linux/macOS use `<absolute selected stateRoot>/core.sock`. The log is
@@ -8667,7 +8702,7 @@ separate states; prompts, models and application policy remain caller-owned.
 ### Signature and result
 
 ```text
-createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices}={})
+createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices,autoStart=true}={})
 ```
 
 Import it from `arcane-os/core/local-ai`. `configuration` is the authored local-AI
@@ -8691,6 +8726,16 @@ asset services keep their own lifetimes. Pass only llama.cpp/Ollama/ONNX
 requirements to this factory; `createLocalImageService()` owns selected image
 requirements. The managed development and native entrypoints separate them.
 
+`autoStart:false` leaves these selected engines unprepared and unstarted during
+Core startup. Call `client.invoke('localai.prepare', {}, {signal})` when the
+application explicitly requests preparation. The operation invokes the
+configured `prepare` owner, emits its complete events as `localai.preparation`,
+starts configured engines and returns current state. Concurrent callers share
+in-flight preparation; completed preparation is reused. Engine/model readiness
+remains separate, so this result alone does not establish inference readiness.
+The default `autoStart:true` preserves startup preparation. No model is selected
+by this option.
+
 The service provides `localai.status`, explicit `localai.services.recover`,
 `llama.status/models/load/unload/chat`, `onnx.status/load/run/unload`, and the documented native Ollama methods.
 `localai.state` reports runtime/model changes. `llama.status` and `llama.models`
@@ -8995,7 +9040,8 @@ microphone, loading a model or starting inference at construction.
 ```javascript
 createNemotronRuntime({
     runtime, prepare, modelId = 'nemotron-3.5-asr-streaming-0.6b',
-    modelPath, diarizationModelPath, gpu, onEvent
+    modelPath, diarizationModelPath, modelAssets, assetProjectionId,
+    resourcePaths, gpu, onEvent
 } = {})
 ```
 
@@ -9005,6 +9051,14 @@ explicitly (native ordinal, or `-1` for CPU). Model paths may come from the
 descriptor; omit the diarization path when speaker labels are not requested.
 Preparation, models and device selection remain caller-owned.
 
+Alternatively supply the existing `modelAssets` service and a completed
+`assetProjectionId`, with `resourcePaths:{model,diarization?}` naming exact
+projection members. `load()` retains that projection before yielding and keeps
+it through actual helper cleanup; the caller can release preparation ownership
+after loading begins. Explicit load accepts these selection fields, and an
+active selection must be unloaded before replacement. Direct paths remain
+supported. See [shared catalog preparation](#preparenemotronmodels).
+
 ### Returned members and lifetime
 
 The engine exposes `current/subscribe/load/unload/transcribe/openStream/close`.
@@ -9057,6 +9111,58 @@ callback rules and cancellation/reset outcomes.
 The default export from `arcane-os/local-ai/nemotron` is the same
 `createNemotronRuntime` function, with identical inputs, results and lifetime.
 
+## `NEMO_SPEECH_MODELS`
+
+Import this catalog from `arcane-os/local-ai/nemotron`. `stt` describes the
+selected Nemotron ASR and diarization GGUF companions; `tts` describes Magpie,
+NanoCodec and the matching ten tokenizer/configuration members. Each selection
+contains `modelId`, `providerId`, `name`, ordinary `members`, `resourcePaths`
+and optional `archives`. The upstream selections come from NVIDIA's
+NeMo-Speech.cpp 0.2.0 catalog. Importing the catalog performs no I/O and installs
+no runtime or model. See [the exact companion contract](native-speech.md#selected-nemo-model-acquisition).
+
+## prepareNemotronModels()
+
+```text
+prepareNemotronModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})
+```
+
+Import from `arcane-os/local-ai/nemotron`. Explicitly prepares the catalog's
+complete ASR and diarization selection through the existing model-assets
+service. Optional `directories` are searched first when `refresh` is false;
+the first complete matching catalog record is opened without downloading.
+Otherwise the shared `prepare` owner acquires the complete selection beneath
+`workingDirectory/model-assets/`. `refresh:true` requests a separate acquisition.
+
+The promise resolves to `{assetProjectionId,directory,members,resourcePaths,release}`.
+An omitted `id` is generated. Ordered asynchronous `onProgress` receives full
+file-based semantic progress; existing selections report `reuse` then `ready`.
+Native acquisition additionally reports its shared resume, ownership-wait,
+activity and terminal states described under [`createModelAssetService()`](#createmodelassetservice).
+Completed members and saved partial transfers remain available for retry;
+HTTP continuation depends on the source response. Direct installed-directory
+reuse keeps its existing phase/file-count callback shape.
+Call the idempotent asynchronous `release()` to relinquish preparation ownership
+after the engine has retained it. Complete acquisitions and borrowed originals
+remain stored. Cancellation and callback failures join cleanup and preserve
+actual failures. The wrapper selects no device, installs no native runtime and
+starts no microphone or inference. See [native model acquisition](native-speech.md#selected-nemo-model-acquisition).
+
+## prepareMagpieModels()
+
+```text
+prepareMagpieModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})
+```
+
+Import from `arcane-os/local-ai/nemotron`. It has the same preparation,
+discovery, progress, cancellation and release contract as `prepareNemotronModels`,
+using the catalog's complete Magpie/NanoCodec/tokenizer selection. Its returned
+`resourcePaths` contains `model`, `codec` and `tokenizerConfig`. The shared TAR
+reader extracts the ten selected tokenizer members from the catalog's selected
+upstream archive ranges; offsets stay transport-local. Pass the completed
+projection to the existing Magpie engine. Voice, language and device selection
+remain caller-owned; preparation performs no synthesis.
+
 ## buildNemotronHelper()
 
 ### Overview and syntax
@@ -9320,7 +9426,7 @@ through `encoder: 'openvino-npu'`; they do not run this producer at startup.
 
 ### Overview and usage
 
-`createSpeechService({stt,tts,signal}={})` from `arcane-os/core/speech` composes
+`createSpeechService({stt,tts,signal,autoLoad=true}={})` from `arcane-os/core/speech` composes
 independently selected STT and TTS engines as one Core service. Supply either
 role or both. Construction downloads, installs and loads nothing; the host
 owns engine creation, model/device selection and supported formats.
@@ -9363,6 +9469,9 @@ The returned object has `name: 'speech'`, `current`, `subscribe`, `close`,
 - `start(context)` subscribes and starts both configured engine loads
   independently, returning immediately. Core and status remain responsive
   during loading; one role's failure leaves the other usable.
+  With `autoLoad:false`, subscriptions and role capabilities remain available
+  while startup requests no engine load. Explicit `speech.load` activates
+  the selected role. The default preserves automatic startup loading.
 - `current()` and `methods['speech.status']()` return the same snapshot:
   `ready`, `transcriptionAvailable`, `synthesisAvailable`, `status`,
   `sttEngine`, `ttsEngine`, `roles.stt`, `roles.tts` and `closed`.
@@ -9443,24 +9552,82 @@ engine. See [complete preparation and cleanup usage](model-assets.md).
 
 `createModelAssetService({appRoot=process.cwd()}={})` from
 `arcane-os/core/model-assets` returns the Core service for
-`modelAssets.open/write/complete/release/status` and `modelAssets.state`.
+`modelAssets.open/write/complete/release/status`,
+`modelAssets.discover/openExisting/prepare/cancelPrepare`, and `modelAssets.state`.
 Relative working directories resolve from `appRoot`; explicit absolute
 directories remain caller-selected. Each projection has its own child
 directory and complete member files.
 
 `current()` returns `{closing,projections}`. `retain(id)` accepts a completed
 projection and returns `{id,directory,members,release}` for a native owner.
-Native `prepare({id,workingDirectory,members,signal,onProgress,refresh=false})`
-accepts ordered `{path,url}` members and returns their ready projection.
+Native `prepare({id,workingDirectory,members=[],archives=[],signal,onProgress,refresh=false})`
+accepts ordered `{path,url}` members and optional uncompressed TAR selections,
+returning their complete ready projection. An archive declares
+`{url,format:'tar',ranges?,members:[{path,member}]}`. Optional inclusive
+`{start,end,stopBefore?}` ranges use HTTP partial responses; the parser handles
+ordinary and PAX member paths and preserves each selected file completely.
+All declared companions must finish before readiness. Range framing stays
+transport-local.
 Complete native acquisitions persist beneath `workingDirectory/model-assets/`
 through unload, disposal and restart; ordinary calls reuse the exact complete
 ordered source selection without a network freshness check. Explicit
 `refresh:true` acquires a separate complete set without replacing active files.
-Independent members transfer concurrently and progress reports phases and
-completed files. Matching same-process preparations share acquisition with
-independent callbacks and cancellation; the last interested cancellation joins
-unfinished I/O and removes only that attempt. Separate processes may acquire
-the same selection independently. Startup downloads nothing.
+Independent members transfer concurrently. Interrupted or cancelled acquisitions
+retain completed members and closed partial files for retry. A retry reuses the
+same recorded attempt and downloads only missing members. Ordinary-file HTTP
+continuation uses its retained strong ETag or Last-Modified validator with
+`Range` and `If-Range`; a matching `206` response appends. A full `200`, `416`,
+missing validator or prior encoded response restarts only that member and
+reports `restart`. One prior partial remains until its replacement completes.
+TAR selections replay the required segment framing while preserving already
+completed companions. HTTP framing remains internal to the transfer, not
+model identity or user-facing progress.
+
+Matching same-process preparations share acquisition with independent callbacks
+and cancellation; cancelling one interested caller leaves the others running.
+The last interested cancellation joins I/O while retaining resumable data.
+Matching selections in separate processes coordinate their recorded transfer
+owner, report `waiting`, then reuse or resume after that owner releases or exits.
+Unrelated acquisitions remain concurrent. Member completion follows stream/file
+closure and promotion; whole-acquisition readiness follows all selected members.
+Startup downloads nothing, and retry remains an explicit preparation request.
+
+Native acquisition progress is
+`{phase,state,message,completed,total,unit:'files',memberIndex?,path?,reason?,recovery?,error?,activity?}`.
+Phases are `open`, `download`, `reuse`, `resume`, `restart`, `complete`, `ready`,
+`waiting`, `heartbeat`, `stalled`, `interrupted`, `cancelled` and `failed`.
+States are `waiting`, `downloading`, `stalled`, `interrupted`, `cancelled`,
+`failed` and `ready`. A five-second heartbeat keeps active work observable;
+`stalled` means no source activity arrived for fifteen seconds, not a diagnosed
+outage. Waiting may include the other owner's observed `activity`. Plain
+`message` and `recovery` belong in ordinary status; complete `error` details
+remain diagnostic data. Progress uses phases and completed-file counts, not
+invented percentages. Terminal acquisition state does not imply that a
+cancelled subscriber receives callbacks after its cancellation boundary.
+
+`discover({directories,catalog=[],recursive=true,signal})` reads only explicit
+installed directories and returns `{directories,models}`. Directory observations
+contain `{directory,exists,error?}`. Each model record has
+`{directory,entryPath,members:[{path,nativePath,available}],missingMembers,complete,source,catalogId?}`.
+The source is `directory`, `catalog` or `acquisition`. Split GGUF filename sets
+are one numerically ordered selection, including missing expected shards and
+the first shard as entry. This grouping also applies to completed acquisitions;
+all declared companions remain present. Ordinary readable symlinked files and
+directories are followed, with real-path cycle detection.
+
+Catalog entries `{id,members,archives?,entryPath?}` declare exact companion sets.
+Acquisition-backed matching honors supplied source URLs and archive member
+names; path-only catalogs and ordinary directory discovery make no origin or
+runtime-readiness claim. No files are downloaded, loaded or moved by discovery.
+
+`openExisting({id,directory,members:[{path}],signal})` opens a complete borrowed
+projection using those existing files. Missing members reject with
+`MODEL_ASSET_MEMBERS_MISSING` and the complete missing-member list. Release
+never deletes or copies borrowed originals. The three new operations also have
+matching Core RPC methods. Request-scoped `modelAssets.progress` carries
+`{id,progress}` with full file-based semantic progress; `cancelPrepare` aborts
+and joins actual acquisition cleanup. The browser helpers below preserve the
+request correlation and cancellation joins.
 `release(id)` relinquishes live preparation ownership. Native retains continue
 through actual engine release; completed native acquisitions remain stored.
 Browser `open/write/complete` projections retain their temporary lifetime and
@@ -9472,6 +9639,53 @@ handle only after its actual context/worker use ends. Original stored model
 files remain with their application owner. See
 [working-file service and wire operations](model-assets.md#native-ownership).
 
+## discoverCoreModelAssets()
+
+```text
+discoverCoreModelAssets({client=getInstalledCoreClient(),directories,catalog,recursive,signal}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Resolves the native `discover`
+result described above through the installed Core connection. Directories and
+catalog selections remain application-owned. Complete shard and companion
+availability is filesystem evidence, not a selected or loaded model. See
+[discovery records](model-assets.md).
+
+## openExistingCoreModelAssets()
+
+```text
+openExistingCoreModelAssets({client=getInstalledCoreClient(),directory,members,signal}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Opens selected complete existing
+files through Core and returns `{id,directory,members,release}`. The helper
+generates its projection ID; `release()` is asynchronous and idempotent.
+Native engines retain their own use; borrowed original files remain intact.
+Cancellation joins uncancelled cleanup before rejecting.
+
+## downloadCoreModelAssets()
+
+```text
+downloadCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,archives,refresh=false,signal,onProgress}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Explicitly invokes native
+acquisition for complete ordinary and optional TAR-selected members and returns
+`{id,directory,members,release}`. It generates the ID, observes only that request's
+complete progress, and awaits asynchronous callbacks in order. Cancellation or
+a callback failure joins native `cancelPrepare` cleanup and local callback
+delivery before settlement; actual cleanup failures remain observable.
+When Core rejects preparation, the helper first delivers already queued
+terminal progress before its internal cleanup cancellation and rejection.
+Explicit caller cancellation retains its no-late-callback boundary.
+Release relinquishes preparation ownership while completed downloads remain
+stored. Interrupted/cancelled native transfers retain completed members and
+saved partials for an explicit retry; the shared owner's HTTP continuation and
+member-restart rules apply. Progress forwards its full ownership-wait,
+heartbeat/stall and terminal records without inventing completion. No model,
+runtime or device is selected implicitly. See
+[download and progress usage](model-assets.md).
+
 ## createModelAssetService default export
 
 The default export from `arcane-os/core/model-assets` is the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.96.0",
+  "version": "0.97.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/core/host.mjs

@@ -9,37 +9,41 @@ export {startCoreListener, startSharedCoreHost, connectSharedCoreHost, runShared
 
 const is = new Is(false);
 
-/** Resolve one app's native locations without creating or migrating data. */
+function userDataDirectory() {
+    const home = homedir();
+    switch (process.platform) {
+        case 'win32': return process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+        case 'darwin': return path.join(home, 'Library', 'Application Support');
+        case 'linux': {
+            const xdg = process.env.XDG_DATA_HOME;
+            return xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share');
+        }
+        default: return null;
+    }
+}
+
+/** Resolve app-private state and same-user shared models without moving data. */
 export function resolveNativeLaunchContext({appId, context = {}} = {}) {
     if (!is.string(appId) || !appId) throw new TypeError('Native launch resolution requires an appId.');
     if (context === null || !is.object(context) || is.array(context)) {
         throw new TypeError('Native launch context must be an object.');
     }
+    const userDirectory = userDataDirectory();
     let stateRoot = context.stateRoot;
     if (stateRoot === undefined) {
-        const home = homedir();
-        switch (process.platform) {
-            case 'win32':
-                stateRoot = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Arcane', appId);
-                break;
-            case 'darwin':
-                stateRoot = path.join(home, 'Library', 'Application Support', 'Arcane', appId);
-                break;
-            case 'linux': {
-                const xdg = process.env.XDG_DATA_HOME;
-                stateRoot = path.join(xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share'), 'Arcane', appId);
-                break;
-            }
-            default:
-                throw new TypeError('This native host must supply its persistent stateRoot.');
-        }
+        if (!userDirectory) throw new TypeError('This native host must supply its persistent stateRoot.');
+        stateRoot = path.join(userDirectory, 'Arcane', appId);
     }
     if (!is.string(stateRoot) || !stateRoot) throw new TypeError('Native stateRoot must be a nonempty directory path.');
     const root = path.resolve(stateRoot);
     const resolved = {
         ...context,
         stateRoot,
-        modelsDirectory: context.modelsDirectory === undefined ? path.join(root, 'Models') : context.modelsDirectory,
+        // Model files are reusable resources; preferences, profiles and chat stay
+        // under the application's stateRoot. Other hosts supply their shared path.
+        modelsDirectory: context.modelsDirectory === undefined
+            ? userDirectory ? path.join(userDirectory, 'Arcane', 'Models') : path.join(root, 'Models')
+            : context.modelsDirectory,
         workspaceRoot: context.workspaceRoot === undefined ? path.join(root, 'Workspace') : context.workspaceRoot
     };
     if (context.sharedHost !== undefined) {