arcane-os 0.56.0 → 0.58.0

package/docs/reference/sdk-api.md

@@ -47,14 +47,21 @@ runtime layouts.
 | `arcane-os/testing` | Isolated test registration and execution. |
 | `arcane-os/targets` | Target adapters and dispatch. |
 | `arcane-os/native` | Native plan and builder protocol. |
-| `arcane-os/native-provider` | SDK portable default and explicit checkout provider loader. |
+| `arcane-os/native-provider` | SDK portable/Windows/macOS defaults and registered explicit checkout provider loader. |
 | `arcane-os/native/portable-provider` | Node-only portable payload provider and explicit app-service composition; not an executable host. |
+| `arcane-os/native/windows-provider` | Selected Windows x64 executable assembly and host-owned run/drain lifecycle. |
+| `arcane-os/native/macos-provider` | Architecture-selected Mac application bundle composition and host-owned run/drain lifecycle. |
 | `arcane-os/core/client` | Browser-safe Core RPC client, application facade, readiness and request cancellation. |
 | `arcane-os/core/contracts` | Shared Core protocol, frame, method and diagnostic error contracts. |
 | `arcane-os/core/classic-source` | Node generator for the canonical classic-script Core client projection. |
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle with explicitly supplied services. |
+| `arcane-os/core/packaged-web` | Core-owned packaged web listener with a persisted loopback origin and ready/failure events. |
+| `arcane-os/core/local-ai` | Native llama.cpp, Ollama and ONNX Core service, model readiness, complete responses and owned lifecycle. See [local AI through Core](local-ai.md). |
+| `arcane-os/local-ai` | Official runtime installation and native artifact bundling for selected llama.cpp/Ollama/ONNX requirements and NeMo libraries. |
+| `arcane-os/local-ai/onnx` | Retained native ONNX worker sessions with explicit graph loading and complete tensor inference. |
+| `arcane-os/ai/core-onnx` | Optional browser access to system ONNX through an existing Core connection. |
 | `arcane-os/integrated-provider` | Fixed integrated shared-development provider. |
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
@@ -83,6 +90,7 @@ runtime layouts.
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
 | `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
+| `arcane-os/ai/core-local` | Browser llama.cpp provider through an available Core connection; browser-local Wllama and ONNX remain independently available. |
 | `arcane-os/ai/browser-decisions` | Explicit-load Laya FP16 and Julia-1 FP32 typed decisions through the shared Transformers.js Worker owner. |
 | `arcane-os/ai/tool-text-stream` | Shared selected tool-argument text observer for provider integration. |
 | `arcane-os/ai/twin-cloud` | Stateless chat, System One state/questions and image generation with explicit key/model, complete results and operation-specific retry/cancellation. |
@@ -280,6 +288,7 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `runApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `runDoctor()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `runProcess()` | function | `arcane-os` | Events, processes, and testing | Node |
+| `createGitTextSnapshot()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node with Git |
 | `runRegisteredTests()` | function | `arcane-os` | Events, processes, and testing | Node |
 | `runRepositoryAction()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `runTarget()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -362,6 +371,7 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `createCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
 | `createCoreFacade()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
 | `installCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
+| `getInstalledCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
 | `createCoreClassicSource()` | function | `arcane-os/core/classic-source` | Core classic client projection | Node; generated source runs in browser and native WebView renderers |
 | `createCoreRuntime()` | function | `arcane-os/core/runtime` | Native Core runtime | Node on Windows, Linux and macOS native hosts; Android requires host adaptation |
 | `encodeCoreFrame()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
@@ -371,6 +381,21 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `startCoreHost()` | function | `arcane-os/core/host` | Native Core host composition | Node with readable input and writable output streams |
+| `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; reads explicitly selected launch JSON |
+| `createWindowsNativeProvider()` | function | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `createMacOSNativeProvider()` | function | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `createPackagedWebService()` | function | `arcane-os/core/packaged-web` | Native packaged web serving | Node Core lifetime; actual listener readiness before navigation |
+| `createCoreLocalAIProvider()` | function | `arcane-os/ai/core-local` | Core local AI | Browser/native WebView with an available Core connection |
+| `createLocalAIService()` | function | `arcane-os/core/local-ai` | Core local AI | Node with selected llama.cpp/Ollama/ONNX runtimes |
+| `createONNXRuntime()` | function | `arcane-os/local-ai/onnx` | Core local AI | Node with prepared Microsoft ONNX runtime |
+| `createCoreONNXRuntime()` | function | `arcane-os/ai/core-onnx` | Core local AI | Browser with an available Core ONNX service |
+| `createLocalAIService default export` | function | `arcane-os/core/local-ai` | Core local AI | Same native service factory |
+| `ensureLocalAIRuntimes()` | function | `arcane-os/local-ai` | Core local AI | Node; selected upstream platform assets |
+| `bundleLocalAIRuntimes()` | function | `arcane-os/local-ai` | Core local AI | Node; complete native runtime assembly |
 | `MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
 | `MAIL_OUTBOX_PROTOCOL` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
 | `MAIL_OUTBOX_STATES` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
@@ -807,7 +832,7 @@ descriptor-selected browser document inventory.
 ### Signature and result
 
 ```text
-async inspectApp({workspaceRoot, appId, signal}={})
+async inspectApp({workspaceRoot, appId, signal, target, outputDirectory}={})
 ```
 
 Import it from `arcane-os` or `arcane-os/packager`. The result includes the
@@ -834,9 +859,18 @@ such as `apps/hello-world/index.html`. The complete `files` inventory uses
 package-relative paths and includes the root `index.html`. Shared
 files retain their configured route destinations.
 
-`output` is the selected workspace-relative final package directory. It uses
-the app's optional `arcane-package.json` `outputDirectory` directly, or
-`dist/<app-id>` when omitted; the SDK appends no app ID to an explicit value.
+`target` defaults to `'browser'`. A selected nonbrowser target adds the app's
+explicit `nativeResources` to `files`, without adding those native-only paths
+to `browserDocuments`. The optional normalized `nativeResources` record is
+returned when authored. This inspection copies or executes no resources.
+
+`output` is the selected workspace-relative final package directory. An explicit
+operation `outputDirectory` wins. Otherwise, a nonbrowser target with a nonempty
+native include list uses `dist/.native/<target>/<app-id>`; the app's saved browser
+destination remains separate. Browser selection, omitted native resources and
+an empty native include list use the app's saved `outputDirectory` or
+`dist/<app-id>`. The SDK appends no app ID to an explicit destination. See
+[native-only application resources](protocols.md#native-only-application-resources).
 
 ### Availability and normalization
 
@@ -881,9 +915,10 @@ console.log(normalizeRelativePath('apps/example/index.html'));
 
 ### Overview
 
-Builds one complete browser application release through the low-level packager
-API. It does not run tests or checks automatically; verification occurs only
-when explicitly requested or when required for this selected release output.
+Builds one complete selected application release through the low-level packager
+API, with browser selection by default. It does not run tests or checks
+automatically; verification occurs only when explicitly requested or when
+required for this selected release output.
 
 ### Signature and result
 
@@ -898,6 +933,21 @@ The package preserves the complete selected content, applying the documented
 asset-version and enabled browser-PWA transformations to resource references.
 Malformed configuration or descriptors fail while preserving the prior output.
 
+`target` defaults to `'browser'`; supported target names are `browser`,
+`portable`, `windows-x64`, `linux-x64`, `linux-arm64` and `android-arm64`.
+A nonbrowser target adds the app's explicit `nativeResources` selection and
+sets the effective `browserPwa` value to `false`. It does not compile or launch
+that platform. Browser calls preserve the existing `browserPwa` default and
+explicit setting. The app adapter's `buildArcanePackage()` context receives
+the actual `target` and effective `browserPwa` alongside its existing fields.
+`copyBase()` retains the browser/shared selection; native-only resources are
+copied afterward, outside browser rewriting and PWA processing.
+
+`moduleFormat` controls browser module representation independently of `target`.
+In particular, `moduleFormat:'native'` alone remains a browser package and does
+not add native resources. The complete selection and separate-output rules are
+documented under [native-only application resources](protocols.md#native-only-application-resources).
+
 `moduleFormat` defaults to `'import-map'`, preserving the ordinary browser
 package. Select `'native'` to resolve saved document import maps into native
 module URLs in the package stage and emit executable inline scripts as external
@@ -938,8 +988,8 @@ manifest or an operating-system launcher. Native-mode dry runs report selected
 input files; generated script/context files are included in the completed
 package's full returned inventory.
 
-The app's optional schema-1 `outputDirectory` selects the final
-workspace-relative destination. For example, `"ai"` emits directly into
+For browser selection, the app's optional schema-1 `outputDirectory` selects the
+final workspace-relative destination. For example, `"ai"` emits directly into
 `<workspace>/ai`; omission retains `dist/<app-id>`. The selected directory is
 wholly replaced through the existing staged swap, not merged. Changing the
 destination preserves the former output and siblings. Conflicting source,
@@ -947,6 +997,13 @@ selected input, or required control paths fail before output writes. Source
 layout, app identity, OPFS scope, and internal package paths remain unchanged.
 See [app-selected package output](protocols.md#app-selected-package-output).
 
+For a nonbrowser target with a nonempty native include list, the default is
+instead `dist/.native/<target>/<app-id>`, preserving a separately emitted browser
+output even when its saved destination is custom. An explicit operation
+`outputDirectory` still wins; choose a dedicated destination because packaging
+replaces that selected directory. Omitted or empty native resources retain the
+existing destination rules.
+
 Root app files retain their paths at the output root; explicitly nested apps
 retain their `apps/<id>/` paths. Shared files retain their configured route
 destinations. When the selected content supplies no root `index.html`, the SDK
@@ -1147,9 +1204,15 @@ console.log(validateAppBundlePath('payload/apps/example/index.html'));
 
 Validates one schema-1 packager app configuration and its relationship to the root config.
 
-Optional `outputDirectory` is the final workspace-relative package directory;
-omission preserves `dist/<app-id>`. It is an app package field, not a change to
-the root configuration's `distRoot` or the schema-2 app identity. Packaging
+Optional `nativeResources` contains a required literal-path `include` array
+(which may be empty) and optional `exclude` array (default `[]`). It selects
+additional app-owned resources only for a nonbrowser packaging target. Ordinary
+`include`, `exclude`, shared routes and document selection remain unchanged.
+
+Optional `outputDirectory` is the saved workspace-relative browser package
+directory; omission preserves `dist/<app-id>`. Nonempty native selection uses
+the separate target-selected default described above. It is an app package
+field, not a change to the root configuration's `distRoot` or the schema-2 app identity. Packaging
 reports conflicting output/input selections with `ARCANE_PACKAGE_INVALID`
 before output writes. Authored-descriptor comparison treats the destination
 as package-local, and descriptor refresh preserves the existing setting.
@@ -1216,7 +1279,8 @@ async function usevalidateRootConfig(...arguments_) {
 
 ### Overview
 
-Authenticates one existing browser app release through the low-level packager API.
+Reads one existing application release and compares its complete file inventory
+with its release manifest through the low-level packager API.
 
 ### Signature and result
 
@@ -1228,6 +1292,9 @@ Import it from `arcane-os` or `arcane-os/packager`. The signature above states w
 
 Optional `outputDirectory` selects the same workspace-relative override accepted
 by `packageApp`, without changing the app's saved destination.
+For a target-selected native input release, pass the returned `release.output`
+as this override. `verifyApp` has no target option and does not infer the native
+directory or execute the application, its services or a platform host.
 
 ### Availability and normalization
 
@@ -1238,9 +1305,13 @@ by `packageApp`, without changing the app's saved destination.
 ```javascript
 import {verifyApp} from 'arcane-os';
 
-async function useverifyApp(...arguments_) {
-    return verifyApp(...arguments_);
-}
+// release is the result of packageApp() for this app and workspace.
+const inspected = await verifyApp({
+    workspaceRoot,
+    appId: 'moon-dashboard',
+    outputDirectory: release.output
+});
+console.log(inspected.files);
 ```
 
 ## verifyAppReleaseBundle()
@@ -2210,6 +2281,13 @@ omitted and an authored empty list stays `[]`, so projection preserves automatic
 discovery versus entry-only selection. See
 [application document selection](protocols.md#application-document-selection).
 
+Optional `package.nativeResources` becomes top-level `nativeResources`.
+Omission remains omitted, an empty include remains `[]`, and an omitted exclude
+becomes `[]`. Package-only descriptor synthesis preserves the same selection.
+This is a packaging contract; `projectNativeDescriptor()` keeps its existing
+registry shape and ordinary include list. See
+[native-only application resources](protocols.md#native-only-application-resources).
+
 ### Signature and result
 
 ```text
@@ -2666,10 +2744,12 @@ async function useloadArcaneIntegratedProvider(...arguments_) {
 
 ### Overview
 
-Loads the package-owned portable provider when `arcaneRoot` is omitted and
-`target` is `portable`. An explicit root retains the fixed Arcane OS checkout
-provider route, including its errors; there is no silent fallback. Other native
-targets still require that root. Normal Node module resolution owns imports.
+Loads the package-owned provider when `arcaneRoot` is omitted and `target` is
+`portable` or `windows-x64`. Portable produces a non-executable payload; Windows
+assembles the matching precompiled SDK host. An explicit root retains the fixed
+Arcane OS checkout provider route, including its errors; there is no silent
+fallback. Other native targets still require that root. Normal Node module
+resolution owns imports.
 
 ### Signature and result
 
@@ -4056,7 +4136,7 @@ Import it from `arcane-os`. Source mode accepts
 `{workspaceRoot=process.cwd(), appId, mode='source', host='127.0.0.1', port=0, httpPort=0, http=false,
 certPath, keyPath, tls, signal, onEvent}` and serves one validated
 workspace application plus its complete SDK or integrated runtime. Packaged mode uses
-`{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, certPath, keyPath, tls,
+`{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, http=false, certPath, keyPath, tls,
 signal, onEvent}` and serves the complete selected release files.
 External source mode accepts both the installed-package route layout and the
 existing physical runtime layout. Installed-package mode serves the configured
@@ -4071,8 +4151,8 @@ The SDK request hook returns `308` for HTTP with a `Location` pointing to the
 actual HTTPS port while preserving the original request path and query. Both listeners
 use the selected host.
 
-Source servers default to HTTPS, including localhost; packaged browser previews
-require HTTPS. The existing `https` option is accepted; `https:false` and
+Source servers and packaged browser previews default to HTTPS, including
+localhost. The existing `https` option is accepted; `https:false` and
 `tls:false` alone do not disable HTTPS. HTTPS startup reads `.arcane/dev/server-cert.pem` and
 `.arcane/dev/server-key.pem` relative to `workspaceRoot` unless explicit
 `certPath` and `keyPath` are supplied together; relative paths resolve from the
@@ -4084,10 +4164,15 @@ handshake; browser trust and address matching are evaluated when a client
 connects. The CLI's `--public` selects the wildcard bind;
 the API's `host` option alone changes only the bind address.
 
-Explicit `http:true` selects one HTTP content listener in source mode and skips
+Explicit `http:true` selects one HTTP content listener in source or packaged mode and skips
 certificate loading. `port` selects that listener's port, including `0` for an
-available port. The same application, runtime and generated PWA routes are
-served. `http` must be boolean; `http:true` rejects packaged mode, `https:true`,
+available port. Source mode keeps the same application, runtime and generated PWA routes.
+Packaged mode serves the complete selected `releaseRoot`; pass the artifact's
+web-root directory, not its enclosing native package directory. Its declared
+application start path, query and fragment are preserved. A caller requiring a
+stable origin must reuse its selected host and port; a bind conflict rejects
+startup rather than silently choosing another port.
+`http` must be boolean; `http:true` rejects `https:true`,
 explicit certificate/key paths, a `tls` value other than `undefined`, `null` or
 `false`, and a nonzero `httpPort`. Browser secure-context and installation
 requirements remain browser-owned; see [explicit HTTP development](cli.md#explicit-http-development).
@@ -4097,10 +4182,10 @@ The promise settles after all selected listeners are ready and resolves to
 networkUrls, httpPort, httpOrigin, httpUrl, close, closed, lifecycle}`. `server` is the raw Node
 server for application content: `Http2SecureServer` for PEM-backed HTTPS,
 `https.Server` for explicit raw `tls` options, or `http.Server` for explicit
-HTTP source mode. HTTP/2 uses Node's compatibility request/response APIs;
+HTTP mode. HTTP/2 uses Node's compatibility request/response APIs;
 callers accessing the raw server must account for its native type.
 `protocol` describes the URL scheme: `'https:'` for either negotiated HTTPS
-protocol or `'http:'` with explicit HTTP source mode.
+protocol or `'http:'` with explicit HTTP mode.
 `url` and `cleanUrl` are the same application URL. Wildcard listeners use
 `localhost` in that local URL; `host` retains the actual bound address.
 `httpPort` is the actual HTTP listener port, `httpOrigin` is its HTTP origin,
@@ -4336,7 +4421,17 @@ console.log(validation.sdkInstallation?.packageVersion);
 
 ### Overview
 
-Builds and retained-verifies one explicitly selected native target through one paired provider.
+Builds one explicitly selected target through its adapter. A paired native
+builder packages the selected app and its explicit bundled-app closure, then
+passes those complete releases to the provider. Provider verification and host
+launch remain separate operations.
+
+The selected target reaches each app's packager, so every app's own
+`nativeResources` and separate native input directory apply consistently to
+both copying and output-overlap calculations. The provider receives the actual
+release roots, manifests and complete file readers. An explicit `nativeBuilder`
+retains its existing identity and contract. See
+[portable Core packaging](core-native-packaging.md#native-only-application-resources).
 
 ### Signature and result
 
@@ -4632,8 +4727,10 @@ described by `packageApp()`.
 The same low-level operation resolves the app's optional `outputDirectory`;
 there is no separate high-level destination override. `release.outputRoot`
 names the resulting complete release directory, with omitted configuration
-retaining `dist/<app-id>`. Browser preview, bundle creation, and native
-browser-content input use that selected root.
+retaining `dist/<app-id>`. Browser preview and bundle creation use that selected
+root. This ordinary package operation retains browser selection; paired native
+assembly through `buildApplication()` separately passes its actual target and
+applies each app's native-resource output selection.
 
 Packaging does not automatically run tests or checks. Verification occurs only
 when explicitly requested or when required for the selected release output.
@@ -5023,24 +5120,85 @@ import {registeredTestCount} from 'arcane-os';
 console.log(registeredTestCount());
 ```
 
+## createGitTextSnapshot()
+
+### Overview
+
+Reads complete application-selected UTF-8 text from one fetched revision using
+a dedicated bare Git cache. It does not create or alter a working checkout.
+
+### Signature, lifecycle, and result
+
+```text
+createGitTextSnapshot({cacheDirectory,remote,ref,selectPath,onEvent,run=runProcess}={})
+```
+
+Import from `arcane-os`. The application owns the cache location, remote, ref,
+path predicate and service factory. The returned `refresh({signal}={})` returns
+`{revision,files:[{path,content}]}` in Git tree order. Concurrent calls share work;
+unchanged fetched revisions reuse completed text retrieval. Caller cancellation
+ends only that wait. `close()`, `drain()` and `dispose()` stop acceptance and
+await accepted refresh/process cleanup. Errors remain observable instead of
+returning stale or partial success. See [Git text snapshots](git-text-snapshot.md)
+for complete inputs, text semantics, errors, events and Core service composition.
+
+### Example
+
+```js
+import {createGitTextSnapshot} from 'arcane-os';
+
+const dispatches = createGitTextSnapshot({
+    cacheDirectory: applicationCacheDirectory,
+    remote: applicationRepository,
+    ref: applicationRef,
+    selectPath: function selectDispatch(filename) {
+        return filename.startsWith('dispatches/') && filename.endsWith('.md');
+    }
+});
+const snapshot = await dispatches.refresh({signal});
+await dispatches.close();
+```
+
 ## runProcess()
 
 ### Overview
 
-Runs one shell-free child command with complete stdout and stderr, ordered stream events, heartbeats, and process-tree cancellation.
+Runs one shell-free child command with complete stdout and stderr, ordered stream
+events, heartbeats, and explicitly selected process cancellation behavior.
 
 ### Signature, parameters, and result
 
 ```text
-async runProcess(command, args=[], { cwd, env, signal, onEvent, heartbeatMs=5000, terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS, allowNonzero=false, input }={})
+async runProcess(command, args=[], { cwd, env, signal, onEvent, onOutput, captureOutput=true, emitOutputEvents=true, outputEncoding='utf8', heartbeatMs=5000, terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS, allowNonzero=false, input, cancellationMode='terminate-tree' }={})
 ```
 
 Import it from `arcane-os`. `command` is executed directly with `shell:false`;
 `args` must be a fixed array of strings, so shell expansion, pipelines, and
 redirection never occur. `cwd` selects the child directory. `env` is shallowly
-merged over `process.env`. When supplied, `input` is written once and stdin is
-closed; otherwise stdin is closed immediately. On Microsoft NT, `npm` and `npx`
-are normalized to their Node CLI entrypoints.
+merged over `process.env`. In the default `cancellationMode:'terminate-tree'`,
+supplied `input` is written once and stdin is closed; otherwise stdin closes
+immediately. With `cancellationMode:'close-input'`, optional input is written
+once and stdin remains open until cancellation or a callback/input failure
+requests shutdown. On Microsoft NT, `npm` and `npx` are normalized to their Node
+CLI entrypoints.
+
+An `AsyncIterable` input instead feeds stdin with awaited writes and closes it
+when the producer finishes. Its `return()` must cooperate with cancellation of
+an outstanding `next()`; the process owner drains both input and output work.
+`onOutput({stream,chunk})` receives complete ordered chunks and is awaited with
+backpressure for each stream. UTF-8 decoding retains split characters. The
+default capture and nonempty-line events remain unchanged; line events are not
+a substitute for lossless chunk delivery.
+
+`captureOutput` and `emitOutputEvents` accept booleans or per-stream selections,
+for example `{stdout:false}` while stderr retains its default. A stream with
+capture disabled returns `null` and requires an `onOutput` consumer.
+`outputEncoding` defaults to `'utf8'`; explicitly selecting `null`, globally or
+per stream such as `{stdout:null}`, delivers native `Buffer` chunks unchanged.
+A raw stream requires capture and line events explicitly disabled for that
+stream plus an `onOutput` owner. It is never decoded or sent as text implicitly.
+Complete failed chunks, original callback failures, process diagnostics and
+exit results remain available through the normal error record after drain.
 
 `onEvent` is awaited in order for `process.starting`, nonempty
 `process.stdout`/`process.stderr` lines, coalesced `process.heartbeat`, and the
@@ -5060,12 +5218,21 @@ text stream preserves its complete content. A missing executable rejects with
 and spawn/runtime failures use the normalized SDK error boundary, with the
 nonzero result retained in error details.
 
-Aborting `signal` emits cancellation-requested state, terminates the owned
-process tree, escalates to a forced tree termination after the grace interval,
-drains event delivery, and rejects with `ARCANE_CANCELLED` and exit code 130.
-An `onEvent` failure also stops the tree and rejects with that callback failure.
-Cancellation proves only that the local process tree was stopped; it cannot
-reverse external effects already performed by the command.
+Aborting `signal` emits cancellation-requested state. The default mode terminates
+the owned process tree and escalates after the grace interval. `close-input`
+instead closes only the child's stdin, with no forced termination or deadline;
+the selected child must own EOF shutdown. This lets a native host finish
+accepted service work before exiting. Both paths continue observing output and
+drain event delivery before rejection with `ARCANE_CANCELLED` and exit code 130.
+An abort after the child's close event does not cancel already completed work.
+
+An `onEvent` failure requests shutdown through the same selected mode. The
+close-input failure retains the child's complete result in `details` and
+additional failures in `errors`, with the original primary error as `cause`
+when wrapping is needed. A cancellation rejection can therefore contain a
+successful child exit code `0`; that is the child's drained result, distinct
+from the cancelled caller operation. Cancellation cannot reverse external
+effects already performed by the command.
 
 ### Availability and normalization
 
@@ -6505,8 +6672,8 @@ console.log(CORE_READY_EVENTS.includes('core.ready')); // true
 ### Overview
 
 Describes the public fields for request, response, event, single-request
-cancellation and all-request cancellation frames. These are wire descriptions,
-not application validation or method admission.
+cancellation, all-request cancellation and `runtime.replay` control frames.
+These are wire descriptions, not application validation or method admission.
 
 ### Value and import
 
@@ -6640,11 +6807,11 @@ the client.
 ### Signature and result
 
 ```text
-createCoreClient({global=globalThis, transport=null, eventOwner=arcaneEvents, eventOwnerReady, autoConnect=true, onError}={})
+createCoreClient({global=globalThis, transport=null, eventOwner=arcaneEvents, eventOwnerReady, autoConnect=true, replayRuntimeState=false, onError}={})
 ```
 
 Import it from `arcane-os/core/client`. The result exposes `invoke`, `receive`,
-`connect`, `close`, `cancelAll`, `events`, `eventsReady`, `runtime.current()`,
+`connect`, `close`, `failTransport`, `cancelAll`, `events`, `eventsReady`, `runtime.current()`,
 `uuid`, `protocol` and `Error`. A supplied transport must provide callable
 `send(frame)`; an invalid transport stays disconnected and reports
 `ARCANE_TRANSPORT_INVALID`. Optional `subscribe(receive)` may return its cleanup
@@ -6656,6 +6823,21 @@ its still-pending request; a failure arriving after response, cancellation or
 timeout reaches `onError`. Deferred event-owner connection preserves the FIFO
 order of queued frames and subscription actions, including reentrant delivery.
 
+`replayRuntimeState:true` sends one observed `runtime.replay` control after the
+receive listener and `transport.ready` are established, without delaying page
+startup. The default is `false`; select replay only with a supporting host.
+Repeated connection calls do not repeat that control, and send failures reach
+`onError`. The host replays actual dispatcher and service state without
+restarting services; transport, Core and service readiness remain distinct.
+
+`failTransport(error)` ends the client after an actual terminal transport
+failure. Pending RPCs and WebKit acknowledgements reject with the complete
+`CoreError`, future invocations reject with that failure, and `onError` observes
+it once. The client releases its owned listeners, callbacks and timers without
+sending cancellation frames to the failed transport. The first terminal failure
+returns `true`; an already closed client returns `false`. Ordinary `close()`
+retains its separate cancellation behavior.
+
 ### Availability and normalization
 
 **Browser and native WebView JavaScript hosts.** Built-in transports select
@@ -6729,8 +6911,8 @@ client.close();
 ### Overview
 
 Installs one synchronous `globalThis.Arcane` facade and native
-`__arcaneReceive` callback. Repeated installation returns the same client for
-that global lifetime.
+`__arcaneReceive` and `__arcaneTransportFailed` callbacks. Repeated installation
+returns the same client for that global lifetime.
 
 ### Signature and result
 
@@ -6742,6 +6924,12 @@ Import it from `arcane-os/core/client`. The returned client is the same contract
 as `createCoreClient()`. Closing it releases subscriptions, native callbacks,
 timers and pending renderer requests; it does not kill Core.
 
+`__arcaneTransportFailed(error)` delegates actual terminal host failures to
+`client.failTransport(error)`. Closing or failing restores previous facade and
+callback globals only while the installation still owns them, preserving later
+replacements. `getInstalledCoreClient()` returns `null` after release, including
+before an installed terminal failure reaches `onError`.
+
 ### Availability and normalization
 
 **Browser and native WebView JavaScript hosts.** Installation makes synchronous
@@ -6761,6 +6949,41 @@ try {
 }
 ```
 
+## getInstalledCoreClient()
+
+### Overview
+
+Reads the existing live SDK-installed client without installing, connecting or
+replacing a facade. Applications use this accessor instead of private fields.
+
+### Signature and result
+
+```text
+getInstalledCoreClient(global=globalThis)
+```
+
+Import it from `arcane-os/core/client`. It returns the exact client installed in
+the selected global, including a classic document-created installation, or
+`null` when no live SDK installation exists. A foreign `Arcane` facade does not
+constitute an SDK installation. Close and terminal failure release the
+installation before subsequent reads.
+
+### Availability and normalization
+
+**Browser and native WebView JavaScript hosts.** This synchronous read changes
+no globals and starts no service, transport or model. The returned client's
+`runtime.current()` describes transport state; service readiness remains with
+its authoritative owner. See [Core browser client](core-client.md).
+
+### Example
+
+```javascript
+import {getInstalledCoreClient} from 'arcane-os/core/client';
+
+const client = getInstalledCoreClient();
+console.log(client ? client.runtime.current() : 'No SDK client is installed.');
+```
+
 ## createCoreClassicSource()
 
 ### Overview
@@ -6771,13 +6994,17 @@ client and contracts. It creates no copied client implementation or bundler.
 ### Signature and result
 
 ```text
-async createCoreClassicSource({eventOwnerModuleURL}={})
+async createCoreClassicSource({eventOwnerModuleURL,replayRuntimeState=false}={})
 ```
 
 Import it from `arcane-os/core/classic-source`. Supply the actual served URL for
 the selected SDK event-manager module. The promise resolves to the complete
 classic-script source.
 
+Optional `replayRuntimeState:true` forwards the current runtime-replay selection
+to the installed client. Omission retains the existing no-replay behavior; use
+`true` only when the composing host supports `runtime.replay`.
+
 ### Availability and normalization
 
 **Node; generated source runs in browser and native WebView renderers.** The
@@ -6821,6 +7048,11 @@ Shutdown stops admission, waits accepted responses, then runs each service's
 startup, drain and dispose in order while independent services close
 concurrently.
 
+The `runtime.replay` control publishes current dispatcher and service state
+without restarting services. Its snapshot preserves complete service errors
+and active request state; see [runtime replay](core-runtime.md#state-and-frames)
+for authoritative readiness and reentrant lifecycle ordering.
+
 ### Availability and normalization
 
 **Node on Windows, Linux and macOS native hosts; Android requires its native host
@@ -6976,17 +7208,24 @@ await transport.closed;
 
 Creates the SDK-owned native builder for one portable Core payload. The caller
 selects application service modules already present in the app release. The
-provider does not load Arcane OS source, choose a model, download a runtime,
-compile an executable or substitute for an unavailable platform host.
+provider does not load Arcane OS source, choose a model, compile an executable
+or substitute for an unavailable platform host. An explicit `native.localAI`
+selection prepares and bundles its selected official runtime distributions;
+without that selection, no local-AI runtime is downloaded.
 
 ### Signature and result
 
 ```text
-createPortableNativeProvider({services=[]}={})
+createPortableNativeProvider({services,packagedWeb=false,webKitDocumentLifecycle=false}={})
 ```
 
 Import it from `arcane-os/native/portable-provider`. Each service selection is
-`{module, options}`. The returned `arcane-native-builder/1` provider exposes
+`{module, options}`. Omitted `services` uses `appDescriptor.native.services`;
+an explicit array, including `[]`, overrides the descriptor selection.
+The Mac composition selects `packagedWeb:true` for the SDK-owned serving service
+and `webKitDocumentLifecycle:true` for the canonical client projection. Defaults
+retain the existing portable and Windows behavior.
+The returned `arcane-native-builder/1` provider exposes
 `describe()`, `doctor()`, `prepare()`, `build()`, `verify()` and `run()`.
 `describe()` and successful payload results report `executable:false`; `run()`
 reports `ARCANE_NATIVE_RUN_UNSUPPORTED`.
@@ -7022,8 +7261,10 @@ console.log(await provider.describe());
 
 ### Overview
 
-Package-owned portable provider with no preconfigured application services. It
-is the named binding for the same object exposed as this subpath's default.
+Package-owned provider with no preconfigured application services. Each native
+provider subpath exports its own singleton and exposes that same object as its
+default binding. The ordinary singleton uses the app descriptor's service
+selection.
 
 ### Value and import
 
@@ -7031,13 +7272,16 @@ is the named binding for the same object exposed as this subpath's default.
 const arcaneNativeBuilderProvider
 ```
 
-Import it from `arcane-os/native/portable-provider`.
+Import it from `arcane-os/native/portable-provider` for a non-executable payload,
+or `arcane-os/native/windows-provider` for the Windows x64 executable contract.
 
 ### Availability and normalization
 
-**Node; produces a portable payload rather than an executable host.** The
-singleton retains the complete `arcane-native-builder/1` portable-provider
-contract described by `createPortableNativeProvider()`.
+**Node for assembly.** The portable singleton retains the contract described by
+`createPortableNativeProvider()`. The Windows singleton retains
+`createWindowsNativeProvider()` and needs Windows x64/WebView2 for execution.
+The two providers are distinct objects; named/default identity holds within
+each selected subpath.
 
 ### Example
 
@@ -7061,12 +7305,14 @@ Default package binding for the same object exposed as
 default as arcaneNativeBuilderProvider
 ```
 
-Import it from `arcane-os/native/portable-provider`.
+Import it from `arcane-os/native/portable-provider` or
+`arcane-os/native/windows-provider`, selecting that subpath's provider.
 
 ### Availability and normalization
 
-**Node; produces a portable payload rather than an executable host.** The
-default and named bindings have exact object identity and the same lifecycle.
+**Node for assembly; execution depends on the selected provider.** Within each
+subpath the default and named bindings have exact object identity and the same
+lifecycle; portable remains a non-executable payload.
 
 ### Example
 
@@ -7078,6 +7324,303 @@ import portableProvider, {
 console.log(portableProvider === arcaneNativeBuilderProvider); // true
 ```
 
+## createWindowsNativeProvider()
+
+### Overview
+
+Creates the SDK-owned Windows x64 provider. It assembles the selected app's
+complete portable payload with the precompiled WebView2 launcher and Node SEA
+Core from the numeric release matching the installed SDK version.
+
+### Signature and result
+
+```text
+createWindowsNativeProvider({services,hostDirectory}={})
+```
+
+Import it from `arcane-os/native/windows-provider`. `services` has the same
+descriptor/explicit-array semantics as the portable provider. An optional
+`hostDirectory` selects an already-built complete host tree; otherwise `build()`
+downloads and extracts the matching `arcane-native-windows-x64.tar.gz` beneath
+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.
+
+The returned `arcane-native-builder/1` provider exposes `describe`, `doctor`,
+`prepare`, `build`, `verify` and `run`. Build returns `{app,target,manifest}`
+with the actual directory at `target.rootDir`. Verification reads the artifact;
+it does not launch the window. Run launches `Arcane.exe` and observes complete
+diagnostics and exit. Cancellation closes input and waits for host-owned drain,
+including accepted service work, without a forced termination deadline. Missing
+prerequisites, download/extraction failures and host failures remain observable
+through the operation's error/event boundary.
+
+### Example
+
+```javascript
+import {createWindowsNativeProvider} from 'arcane-os/native/windows-provider';
+
+const nativeBuilder = createWindowsNativeProvider({
+    services: [{module: 'native/moon-ledger.mjs', options: {ledgerName: 'Cheese debts'}}]
+});
+```
+
+Pass `nativeBuilder` to the existing native build-plan contract. For the ordinary
+CLI route and the complete artifact/launch contract, see
+[Windows executable packaging](core-native-packaging.md#windows-executable).
+
+## createMacOSNativeProvider()
+
+```text
+createMacOSNativeProvider({services,hostDirectory}={})
+```
+
+Import from `arcane-os/native/macos-provider`. The named
+`arcaneNativeBuilderProvider` and default export are the same provider with
+descriptor-owned services and the exact SDK release's selected host asset.
+The six-method `arcane-native-builder/1` contract supports `macos-arm64` and
+`macos-x64`, platform `macos`, format `app`. A selected `hostDirectory` allows
+same-project collaboration on host output; otherwise assembly downloads the
+matching numeric SDK release's `arcane-native-macos-<architecture>.tar.gz`.
+Neither an available source implementation nor `doctor()` proves that the
+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 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
+Core/listener drain on cancellation. See the complete
+[macOS composition and prerequisite contract](core-native-packaging.md#macos-application-composition).
+
+## createPackagedWebService()
+
+```text
+createPackagedWebService({artifactRoot}, context={})
+```
+
+Import from `arcane-os/core/packaged-web`. Returns the Core service
+`{name:'packaged-web', start, drain}`. Start reads the native manifest, serves
+its complete web root with the existing explicit HTTP packaged server on
+`127.0.0.1`, and emits `core.web.ready` with `{origin,url,port}` only after the
+actual listener is ready and its first selected port is saved. The complete
+manifest start URL is resolved against that origin.
+
+State uses `context.stateRoot` or the native launcher's separate
+`--arcane-host-state-root` argument. The saved `packaged-web-origin.json` keeps
+the same port on subsequent launches; unreadable state or port conflicts remain
+errors, with no silent new origin. Startup rejection belongs to the Core
+`core.service.state` event; an unexpected post-start close/failure emits
+`core.web.failed` with the complete serialized error. Drain owns listener close
+and lifecycle completion. No application launch payload is rewritten, no model
+is loaded, and the ordinary server's HTTPS default is unchanged.
+
+## readCoreLaunchContext()
+
+### Overview
+
+Reads only the complete JSON object explicitly selected by
+`--arcane-launch-config <path>`; it does not search for application configuration.
+
+### Signature and result
+
+```text
+async readCoreLaunchContext({argv=process.argv.slice(2)}={})
+```
+
+Import it from `arcane-os/core/host`. The promise resolves to `{}` when the flag
+is absent, or the complete parsed object when present. A missing flag value,
+unreadable file, malformed JSON or non-object value rejects. Relative paths use
+the process working directory. The reader does not rewrite content or mutate
+the environment.
+
+```javascript
+import {readCoreLaunchContext} from 'arcane-os/core/host';
+
+const launchContext = await readCoreLaunchContext();
+```
+
+The generated entry supplies artifact-derived `appRoot`, then applies the whole
+explicit context and passes the same object as every service factory's second
+argument. Authored service options remain the first argument. Workspace/state
+locations and additional fields belong to the launcher/application. See
+[launch-time locations](core-native-packaging.md#launch-time-locations).
+
+## createCoreLocalAIProvider()
+
+### Overview
+
+Creates a browser-safe llama.cpp LLM provider through an existing Core client.
+Construction selects no model and installs no runtime or transport.
+
+### Signature and result
+
+```text
+createCoreLocalAIProvider({client=getInstalledCoreClient(),id='llama.cpp'}={})
+```
+
+Import it from `arcane-os/ai/core-local`. The provider implements
+`arcane-ai-provider/2` and exposes `catalog`, `status`, `inspect`, `load`,
+`request`, `unload` and `dispose`. Register it with the shared AI provider runtime,
+select the exact provider/model with `localOnly:true`, and load that selection.
+Requests wait for the requested model's actual readiness, preserve complete
+payloads and parsed streaming chunks, and cancel on observed readiness loss.
+Missing Core reports unavailability; it does not choose a browser or cloud route.
+Dispose/unregister at the caller's owning lifecycle boundary.
+
+```javascript
+import {createCoreLocalAIProvider} from 'arcane-os/ai/core-local';
+import {getAIProviderRuntime} from 'arcane-os/ai-provider-runtime';
+
+const provider = createCoreLocalAIProvider();
+const unregister = getAIProviderRuntime().register(provider);
+```
+
+See [the browser provider guide](local-ai.md#browser-llamacpp-provider) for model
+selection, streaming, cancellation and primary-model reload behavior.
+
+## createLocalAIService()
+
+### Overview
+
+Composes application-selected llama.cpp, Ollama and ONNX engines as a native Core
+service. Runtime installation, process availability and model readiness remain
+separate states; prompts, models and application policy remain caller-owned.
+
+### Signature and result
+
+```text
+createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})
+```
+
+Import it from `arcane-os/core/local-ai`. `configuration` is the authored local-AI
+record; `appRoot` resolves its relative model paths and `runtimes` supplies
+resolved installed runtime records. It returns a Core service definition with
+`current()` and independent selected-engine startup. Compose it through the
+existing Core lifecycle. Shutdown cancels owned work and joins owned processes;
+an already running external service remains under its external owner.
+
+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.chunk` and `ollama.chunk`
+carry original parsed chunks with `streamId`; terminal responses remain complete.
+There is no background health polling or implicit model choice.
+
+```javascript
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const service = createLocalAIService(application.native.localAI, {appRoot, runtimes});
+```
+
+See [Core service configuration, results and failures](local-ai.md#core-service)
+and [native bundling](local-ai.md#native-bundling).
+
+## createONNXRuntime()
+
+`createONNXRuntime({modulePath,signal?,onEvent?})` from `arcane-os/local-ai/onnx`
+owns retained native ONNX sessions in workers. It exposes `load({id,model,
+sessionOptions?,signal?})`, `run({id,feeds,fetches?,runOptions?,signal?})`,
+`unload({id,signal?})`, `current()`, replaying `subscribe(listener)` and `close()`.
+The direct model path is absolute. Complete typed tensor records use
+`{type,dims,data}`; callers own the actual graph's inputs and preprocessing.
+
+Models load only on explicit requests. A live session ID requires unloading
+before replacement. Independent sessions run concurrently; same-session work
+waits at that session's loading/execution boundary. Queued cancellation removes
+that request; active cancellation retires the affected worker and suppresses
+its response. Native code can delay termination; cleanup waits for actual exit.
+See [complete signatures, readiness, cancellation and usage](local-ai.md#native-onnx-sessions).
+
+## createCoreONNXRuntime()
+
+`createCoreONNXRuntime({client=getInstalledCoreClient()}={})` from
+`arcane-os/ai/core-onnx` accesses an available Core ONNX service. Its `load`,
+`run`, and `unload` mirror the native session selection and accept `signal` and
+`timeoutMs` (default `0`). Relative model paths resolve at Core's `appRoot`.
+The accessor owns complete tensor transport encoding/decoding, `inspect()`,
+`current()`, replaying `subscribe(listener)` and `close()`. Closing cancels this
+accessor's requests and subscriptions; unloading shared models is explicit.
+Construction installs no runtime and opens no transport. Existing browser
+ONNX/Wllama remain independent. See [Core and browser usage](local-ai.md#onnx-through-core-and-the-browser).
+
+## createLocalAIService default export
+
+The default binding from `arcane-os/core/local-ai` is exactly the named
+`createLocalAIService` factory above, with the same arguments, return value and
+lifecycle:
+
+```javascript
+import createLocalAIService from 'arcane-os/core/local-ai';
+```
+
+## ensureLocalAIRuntimes()
+
+### Overview
+
+Reuses matching managed runtimes or installs complete selected official
+llama.cpp/Ollama/ONNX distributions or NeMo libraries in an explicitly supplied directory.
+
+### Signature and result
+
+```text
+async ensureLocalAIRuntimes({runtimes=[],directory,platform=process.platform,architecture=process.arch,signal,onEvent}={})
+```
+
+Import it from `arcane-os/local-ai`. Runtime requirements accept IDs or
+`{id,version?,url?}` records. The result is an array of absolute
+`{id,version,platform,architecture,root}` records, with `executable` for servers,
+`modulePath` for ONNX, or NeMo library directories. Matching concurrent
+installs share their work. Downloads retain runtime libraries and surface
+network/archive failures; cancellation and operation events remain observable.
+Installation changes no global PATH or system service and loads no model.
+Supported assets belong to the selected upstream distribution; see
+[platform and archive requirements](local-ai.md#native-bundling).
+
+```javascript
+import {ensureLocalAIRuntimes} from 'arcane-os/local-ai';
+
+// Call explicitly when the app needs its selected official runtime installed.
+async function prepareMoonCheeseRuntime(){
+    return ensureLocalAIRuntimes({
+        runtimes: ['llama.cpp'], directory: '.arcane/local-ai/runtimes'
+    });
+}
+```
+
+## bundleLocalAIRuntimes()
+
+### Overview
+
+Prepares selected runtimes through the same installer and copies their complete
+trees into one fresh native staging destination.
+
+### Signature and result
+
+```text
+async bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,platform=process.platform,architecture=process.arch,signal,onEvent}={})
+```
+
+Import it from `arcane-os/local-ai`. `directory` owns the reusable installation;
+`outputRoot` owns the fresh artifact. The promise resolves to `{runtimes,files}`:
+runtime paths are artifact-relative under `runtime/local-ai/<id>`, and `files`
+contains the complete emitted inventory. Existing runtime destinations are
+preserved and reported as a conflict. Copying settles all started work and
+reports failures/cancellation without executing app services or models.
+
+```javascript
+import {bundleLocalAIRuntimes} from 'arcane-os/local-ai';
+
+// Call explicitly with a fresh output directory for this native assembly.
+async function bundleMoonCheeseRuntime(outputRoot){
+    return bundleLocalAIRuntimes({
+        runtimes: ['llama.cpp'], directory: '.arcane/local-ai/runtimes', outputRoot
+    });
+}
+```
+
+The ordinary provider invokes this owner only for an explicit native local-AI
+selection. See [selected local-AI runtimes](core-native-packaging.md#selected-local-ai-runtimes).
+
 ## startCoreHost()
 
 ### Overview
@@ -9419,3 +9962,8 @@ const cancelled = normalizeAIRequestAbort(new DOMException('Cancelled', 'AbortEr
 ## Data export subpaths
 
 The package also exposes eight JSON Schemas (including `arcane-os/schemas/event-stack.json`) and its package manifest. These are data contracts, not callable JavaScript members. See [schema contracts](../architecture.md) and the files under `schemas/`.
+
+`arcane-os/schemas/arcane-app.json` describes schema-2 `package.nativeResources`;
+`arcane-os/schemas/arcane-package.json` describes the projected schema-1
+`nativeResources`. Both use the existing literal application-relative path
+contract. See [native-only application resources](protocols.md#native-only-application-resources).