arcane-os 0.55.0 → 0.57.0

package/docs/publishing.md

@@ -11,8 +11,12 @@ the npm `dev` dist-tag, while bare numeric stable versions select
 
 The package version and `publishConfig.tag` must agree exactly: `-dev` uses
 `dev`, and a bare numeric stable version uses `latest`. npm is the canonical
-SDK distribution: application repositories add an exact `arcane-os` project
-dependency and invoke its local CLI with `npm exec -- arcane`. A separate
+SDK distribution: development applications declare `arcane-os` as `latest` and
+invoke its local CLI with `npm exec -- arcane`. An exact application SDK pin
+begins only when Roshi designates that application as a production build.
+Keep the lockfile and explicitly refresh and compare its resolution and the
+installed SDK with npm's published version before materializing or building;
+see [Consumer updates](consumer-updates.md). A separate
 global installer, standalone SDK executable, NuGet package, Homebrew formula,
 or OS package is not part of this release surface.
 
@@ -30,8 +34,8 @@ agreement, and required license notices. One unprivileged producer packs one
 artifact with a recorded run id, artifact id, version, and source commit. It
 does not impose byte counts, hashes, digests, provenance receipts, or unrelated
 test suites as ordinary development gates. Broader integration, regression,
-platform, browser, presentation, and documentation work remains separately
-user selected.
+and platform work remains separately user selected. Documentation and website
+updates are required post-publication follow-through as described below.
 
 `publish-dev.yml` can run only when manually dispatched from `main` in
 `TheWizardNexus/arcane-os-sdk`. Dispatch supplies the exact successful Check
@@ -59,14 +63,15 @@ The unscoped package installs both `arcane` and `arcane-os`. The short command
 is the documented default; `arcane-os` is the collision-safe fallback. npm
 package names are unique, but executable names are not globally reserved.
 
-When `npm view arcane-os@dev version` reports the package unavailable, run
-`npm run pack:local` in this SDK checkout for local development, scaffold with
-`node ./bin/arcane.mjs new ...`, and install the resulting `.tgz` into the app
+External applications consume published npm releases. An unavailable release
+does not authorize them to use an unpublished SDK checkout or tarball. Only
+tasks explicitly collaborating on an SDK update inside this project may use
+the local `npm run pack:local` workflow and its resulting `.tgz`. That local
+workflow can scaffold with `node ./bin/arcane.mjs new ...` and install the tarball
 with `npm install --save-dev --save-exact <path>`. Keep the tarball at the path
-recorded by `package-lock.json`; subsequent `npm ci` uses that declared package.
-Arcane reads the installed package's name and version against the root
-dependency declaration. A local directory `file:` install is intentionally unsupported because
-it may be linked.
+recorded by `package-lock.json` for subsequent `npm ci`. Arcane reads the installed
+package's name and version against the root dependency declaration. A local
+directory `file:` install is unsupported because it may be linked.
 
 The npm package already has its trusted-publishing relationship. Each later
 release therefore follows the same direct selected-artifact path: push the
@@ -77,9 +82,11 @@ dist-tag after publication. Never rebuild or repack the artifact under
 publication authority, and never substitute a different source revision.
 
 Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
-dependency source must be reachable by the runner. A sibling local tarball is a
-workstation workflow, not a portable GitHub dependency source; switch to the
-exact registry release (or deliberately vendor the tarball) before remote CI.
+dependency source must be reachable by the runner. External application CI uses
+the published registry package recorded in the committed lockfile. A locked
+install reproduces that selected version; it does not establish that the SDK is
+currently npm's `latest`. Complete the development refresh before preparing and
+committing managed application files and the updated lockfile for CI.
 
 ## Reusable application release workflow
 
@@ -111,8 +118,23 @@ GitHub release, and no release creates a Git branch for an npm dist-tag.
 
 ## Documentation publication
 
-Documentation publication occurs only when the user explicitly selects it. The
-Pages job checks out that selected `main` revision without persistent
+After every successful npm release and its applicable requester notices, the
+SDK owner updates documentation and the existing SDK website for all added,
+removed, or modified features, APIs, members, methods, and affected public
+contracts. Include the relevant signatures, inputs, outputs, defaults,
+lifecycle, errors, platform availability, and usage examples. This standing
+duty also applies when a release has no requesting applications. Record the
+actual documentation and website delivery outcomes in the release handoff and
+report any unfinished work. See [Consumer updates](consumer-updates.md) for
+request intake and notice requirements.
+
+Documentation and website content outside the selected npm payload does not
+block npm publication. Prepare and deliver those updates through the existing
+documentation/site workflow after publication; do not wait for consumer
+adoption or application tests. This duty does not authorize ChatGPT Sites or
+production-server administration.
+
+The Pages job checks out the selected `main` revision without persistent
 credentials and uploads only the static `site/` tree. It does not automatically
 run the SDK test suite, checks, generators, or repository build code.
 
@@ -128,5 +150,6 @@ One producer creates the tarball. Publication names that producer's exact Check
 run, artifact, and version and does not rebuild from a later checkout. The
 release workflow checks only the publication contract and required legal
 inventory for that selected output.
-Platform matrices, full product regressions, Pages, and broader presentation
-work remain separate user-selected operations.
+Platform matrices and full product regressions remain separate user-selected
+operations. Documentation and the existing website are required post-release
+follow-through, with their outcomes recorded separately from npm publication.

package/docs/reference/README.md

@@ -17,9 +17,14 @@ high-level page links to the relevant deep section instead of repeating it.
 Install the SDK in your application:
 
 ```sh
-npm install --save-exact arcane-os@latest
+npm pkg set dependencies.arcane-os=latest
+npm install
 ```
 
+The development declaration tracks the current `latest` channel. The lockfile
+and installed package record the exact version actually selected for the
+workspace.
+
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
 For local models, native browser voices or cloud speech, follow the [browser speech guide](ai/browser-speech.md)
 and the complete [browser AI demo](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
@@ -38,14 +43,19 @@ alone does not make bare module names resolve in a browser.
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
+| Connect an application through the shared WebSocket transport | [Shared WebSocket clients](websocket-client.md) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
 | Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
 | Use a shared entity | [Runtime entity modules](runtime-entities.md) and [exact export contracts](core/arcane-entities.md) |
 | Load a reusable HTML component | [Runtime component catalog](runtime-components.md) |
 | Submit complete speech parts immediately and play them in order | [`SpeechPlayback`](runtime-modules.md#speechplaybackjs) and the [basic browser example](ai/browser-speech.md#play-a-complete-array-with-speechplayback) |
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
+| Connect a browser to one Core transport | [Core browser client](core-client.md) |
+| Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
+| Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
+| Choose a normalized typed browser decision surface | [Browser typed decisions](ai/browser-decisions.md) |
 | Run a caller-selected local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
 | Run caller-selected Whisper/Kokoro, native browser recognition/voices or cloud TTS | [Browser speech providers](ai/browser-speech.md) |
 | Send TWiN chat, System One state/questions or image requests | [TWiN Cloud guide](ai/twin-cloud.md) |
@@ -101,6 +111,26 @@ The [changelog](../../CHANGELOG.md) records changes by version; the
 identify the corresponding published package source. A newer website does not
 change the version installed in your application.
 
+### Generate the selected reference site
+
+The existing `node tools/build-reference-site.mjs --write` command reads the
+live checkout. For release documentation while disjoint source work continues,
+select the reviewed documentation commit explicitly:
+
+```sh
+node tools/build-reference-site.mjs --write --source-ref <documentation-commit>
+```
+
+The same option is accepted by `createReferenceSite({sourceRef})` and
+`writeReferenceSite({sourceRef})`. It reads the selected commit's package
+version, complete reference documents and inventories, inventory-selected
+runtime sources, and authored site inputs directly from Git in memory. It
+creates no checkout or export and leaves source drafts untouched. Rendering
+uses the current canonical generator and its authored semantic contracts;
+select a documentation commit whose contracts match the published package.
+Generated output still belongs to the canonical `site/` tree and requires its
+usual coordinated output ownership. Generation does not publish hosted Pages.
+
 ### Historical 0.3.4 publication record
 
 The following records describe that earlier release only. They do not identify

package/docs/reference/availability-and-normalization.md

@@ -58,9 +58,12 @@ false when a probe throws; SDK branching continues through its owning error path
 policy, package-owned model policy, platform support, and dependency readiness
 are independent checks.
 
-The current native host/target matrix covers Microsoft NT, Linux, and Android
-where listed. It exposes no macOS target or Core host contract in this SDK
-version; WebKitGTK availability must not be generalized to macOS.
+The current executable host/target matrix covers Microsoft NT, Linux, and
+Android where listed. This SDK exposes no macOS executable target, native
+bridge, artifact, or run contract; WebKitGTK availability must not be
+generalized to macOS. The reusable Node Core runtime, framed stdio transport,
+host composition, and portable payload can be used by a separately composed
+macOS host, but they do not supply that native platform host or bridge.
 
 ## Capability-first matrix
 
@@ -68,7 +71,9 @@ version; WebKitGTK availability must not be generalized to macOS.
 | --- | --- | --- | --- |
 | Scaffold, inspect, test, package, bundle, build, verify, or run an app | `arcane` CLI or `arcane-os` package functions | **Node**; native targets invoke one explicit provider | CLI events and SDK errors/results are normalized by versioned SDK contracts. Tests and checks run only when explicitly selected; verification is separate and selected-output-specific. |
 | Publish application events or review a complete event history | `arcane-os/event-manager` | **Node** and **Browser**; optional DOM capture needs a browser DOM or compatible host | Live listeners receive original arguments. Ordinary `secure:false` recording preserves complete URLs, public details, and captured stack text in deeply frozen `arcane-event-stack/1` snapshots while credential-named fields remain redacted. The stack format is local diagnostic data, not a host transport. |
+| Share one native WebSocket by exact URI and ordered protocols | `arcane-os/websocket-client` | **Node** and **Browser**, using the host's native `WebSocket` | The selected upstream `ws-share` instance owns the connection pool and global observation. Native socket messages and events remain unchanged; there is no reconnect, heartbeat, application envelope, storage, or fallback. |
 | Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
+| Score caller-supplied typed options with Laya or Julia | `arcane-os/ai/browser-decisions` | **Browser** only; caller-selected upstream runtime/model and backend | Typed decisions retain complete rows and return typed values, scores, probabilities, and diagnostics in caller order. This surface is separate from chat and speech and does not silently change model, precision, backend, or family. |
 | Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, route/configuration records, and status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` creates no fallback. |
 | Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, and OPFS/DBOPFS; full WebGPU offload by default or explicit CPU with `gpuLayers:0` | The public AI API module normalizes multi-model lifecycle, status, complete all-choice streaming, cancellation, exact ordered structural tool-call visibility, and session persistence. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
 | Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | Independent provider/2 lifecycle and status, with `auto`, `webnn-npu`, `webgpu`, or `wasm` execution. Whisper owns one Worker/session; Kokoro defaults to four and accepts one through four. Complete model/runtime selection, offline behavior, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model content or cloud fallback is supplied. |
@@ -81,6 +86,9 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Print rendered editor content or file previews | `/arcane/modules/PrintView.js`, editor `print()`, and file/history `printPreview()` | **Browser / native WebView** with DOM and browser printing | Complete current rendered content, fonts, and resolved media are captured for print. Explicit requests await view preparation; native Print captures synchronously. Shared `print.css` supplies a light paper palette and one-inch margins; snapshots stay owned through `afterprint`. |
 | Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, complete lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs retrieval for each prepared chat send. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
+| Connect browser code to an existing Core transport | `arcane-os/core/client` and `arcane-os/core/contracts` | **Browser / native WebView** with an admitted transport; explicit development HTTP remains opt-in | The reusable client owns `arcane/1` correlation, readiness, cancellation, events, facades, and complete native error fidelity. It supplies no service, policy, or host process. |
+| Compose native Core services and framed stdio hosting | `arcane-os/core/runtime`, `arcane-os/core/stdio`, and `arcane-os/core/host` | **Node** on Windows, Linux, or macOS; the composing native host supplies its process and bridge | The SDK owns reusable dispatch, per-service lifecycle, request/service work ownership, cooperative cancellation, drain, and stdio framing. Product identity, policy, privileges, models, storage, and services remain host-owned. |
+| Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; portable platform selection is currently Windows or Linux, while separately composed hosts may use the payload | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |

package/docs/reference/cli.md

@@ -49,6 +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` and/or `ollama` 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. |
@@ -366,9 +367,16 @@ An explicit live-source SDK mapping follows the selected browser destinations
 while reading canonical SDK source; it never replaces installed files.
 
 ```text
-arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
+arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>] [--local-ai llama.cpp,ollama]
 ```
 
+`--local-ai` saves the selected requirements in `native.localAI`, or in
+`arcane-package.json.localAI` for a package-only app. Later development runs
+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.
+See [local AI through Core](local-ai.md) for configuration and native bundling.
+
 ### Lifecycle
 
 Startup refreshes the selected authored `arcane-app.json` projection into

package/docs/reference/core-client.md

@@ -1,7 +1,8 @@
 # Core browser client
 
 `arcane-os/core/client` is the browser-safe `arcane/1` RPC owner. It exports
-`createCoreClient`, `createCoreFacade` and `installCoreClient`.
+`createCoreClient`, `createCoreFacade`, `installCoreClient` and
+`getInstalledCoreClient`.
 `arcane-os/core/contracts` exports `CORE_PROTOCOL`, `CORE_READY_EVENTS`,
 `CORE_FRAME_CONTRACTS`, `CORE_METHOD_CONTRACTS`, `CoreError` and
 `serializeCoreError`. Contracts describe transport and existing method shapes;
@@ -25,6 +26,23 @@ remain available through this facade; their implementations and availability
 belong to the selected host. No repository, app list, model selection or service
 implementation is installed by importing this client.
 
+An application using a host-installed client can read it without installing or
+replacing anything:
+
+```js
+import {getInstalledCoreClient} from 'arcane-os/core/client';
+
+const client=getInstalledCoreClient();
+// null means this global has no live SDK-installed client.
+```
+
+`getInstalledCoreClient(global=globalThis)` returns the exact live SDK-installed
+client, including one installed by classic document-created injection. It does
+not connect, install a client or replace an existing `Arcane` object. Applications
+need not inspect private installation fields. It returns `null` after that
+installation closes or fails. A
+foreign application's `Arcane` object is not evidence of an SDK installation.
+
 The native adapters select WebView2, WebKitGTK or Android WebView. Ordinary
 browsers remain `standalone`; they do not probe a local server. Development
 HTTP is selected only by the existing explicit `__ARCANE_DEV_HTTP__` flag.
@@ -41,6 +59,14 @@ without callable `send(frame)` remains disconnected and reports
 `ARCANE_TRANSPORT_INVALID`; it does not announce `transport.ready`.
 `autoConnect:false` defers connection until `connect()` or the first invocation.
 
+`replayRuntimeState:true` sends one `runtime.replay` control after the transport's
+receive listener and `transport.ready` are established. The default is `false`,
+preserving existing hosts. The send is observed without delaying page startup;
+delivery errors reach `onError`. A host supporting this control supplies its
+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
 response result or rejects with `CoreError`. Parameters, result fields and
 event data retain their complete supplied content. JSON encoding belongs only
@@ -75,6 +101,20 @@ native callbacks, timers and pending renderer requests; it does not kill Core.
 Call `stop()` to remove an individual subscription and `client.close()` when
 the client owner ends its lifetime.
 
+For an actual terminal child-process or transport failure, the host calls
+`client.failTransport(error)`. Installed clients also own the native callback
+`globalThis.__arcaneTransportFailed(error)`. This boundary rejects pending RPCs
+and WebKit acknowledgements with the complete actual `CoreError`, reports that
+failure once, releases callbacks/subscriptions/timers and rejects future
+invocations with the same failure. It sends no cancellation frames to a failed
+transport and does not invent response identifiers or results. A normal close
+still uses cancellation rather than reporting a transport failure.
+
+Closing or failing an installation restores its previous `Arcane` object and
+native callbacks only when those globals still belong to that installation.
+Another owner's later replacements remain unchanged. The read-only accessor
+returns `null` before the installed failure is reported to `onError`.
+
 Errors retain complete native fields, including diagnostics and stack/cause
 information. WebView2 and Android bridge failures retain native error codes,
 messages and diagnostic fields; the request method and transport are added
@@ -90,7 +130,8 @@ transport/event-owner failures outside individual request promises.
 import {createCoreClassicSource} from 'arcane-os/core/classic-source';
 
 const source=await createCoreClassicSource({
-    eventOwnerModuleURL:'/arcane/sdk/event-manager.mjs'
+    eventOwnerModuleURL:'/arcane/sdk/event-manager.mjs',
+    replayRuntimeState:true
 });
 // Supply source to the native host's existing classic-script injection owner.
 ```
@@ -100,6 +141,8 @@ installed SDK. It emits the same implementation as a classic script, without
 copying another client or adding a bundler. The caller supplies the actual
 served SDK event-manager URL; the example URL must match its selected layout.
 That module and its existing managed import map must be included by packaging.
+Select `replayRuntimeState:true` only when composing a host with the current
+runtime replay control; omitting it preserves the existing no-replay default.
 
 The generated facade, native receive callback and current-state methods install
 synchronously. When the shared event owner already exists, it is reused

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

@@ -1,22 +1,28 @@
 # Portable Core packaging
 
 `arcane-os/native/portable-provider` owns the portable native payload in the SDK
-package. It does not load Arcane OS source, choose models, download a runtime,
-or compile an executable. Windows, Linux and macOS hosts may compose this
+package. It does not load Arcane OS source, choose models or compile an
+executable. An application's explicit `native.localAI` selection can include
+its selected upstream runtimes through the SDK local-AI installer. Without that
+selection, assembly does no local-AI runtime preparation. Windows, Linux and macOS hosts may compose this
 Node-based payload; Android needs its separate native host adaptation. The
 current CLI's portable platform selections remain Windows and Linux. A portable
 artifact is not a Windows executable, Linux package or Android application.
 
 `loadArcaneNativeProvider({target:'portable'})` selects the installed SDK provider
 without an `arcaneRoot`. Supplying an explicit `arcaneRoot` retains the existing
-checkout-provider route. Other native targets remain with their actual platform
+checkout-provider route. The SDK also owns the `windows-x64` executable provider
+described below. Other native targets remain with their actual platform
 providers; the loader does not substitute this payload for an unavailable host.
 
 ## Provider and selected input
 
 The default export and `arcaneNativeBuilderProvider` are the same provider.
-`createPortableNativeProvider({services:[]})` creates one with application-owned
-service configuration. All implement `arcane-native-builder/1`:
+`createPortableNativeProvider({services})` creates one with application-owned
+service configuration. Without that override, the provider uses the selected
+app descriptor's `native.services`, or an empty selection when omitted. An
+explicit `services:[]` overrides the descriptor with no app services.
+All implement `arcane-native-builder/1`:
 
 - `describe()` identifies the portable target and `executable:false`.
 - `doctor({targetRequest, signal, onEvent})` reports missing SDK Core source files.
@@ -42,6 +48,45 @@ receipts, hashes, content limits or security policy. The package-relative source
 root comes from the provider module's own location, not `toolchainRoot` or an
 Arcane OS machine bundle.
 
+## Native-only application resources
+
+Select application service modules and their complete local source closure in
+the authored schema-2 descriptor's `package.nativeResources`, separately from
+its browser `include`/`exclude` selection:
+
+```json
+{
+  "package": {
+    "nativeResources": {
+      "include": ["native", "src", "package.json"],
+      "exclude": ["native/drafts"]
+    }
+  }
+}
+```
+
+This is a descriptor excerpt for the app-owned service example below. The
+projected schema-1 field is top-level `nativeResources`. Paths are literal and
+app-relative; directories include descendants. Omission or an empty include
+keeps previous selection and output behavior. The app supplies every required
+source file explicitly; packaging does not discover or execute services.
+
+Paired `buildApplication()` passes the actual native target to the selected app
+and every explicitly bundled app. With a nonempty native include list, their
+input releases use `dist/.native/<target>/<app-id>` instead of the saved browser
+output, preserving existing browser/PWA artifacts. Each app's own selection is
+applied; complete releases and actual roots are forwarded to the provider.
+The provider then copies them unchanged into its artifact layout described below.
+
+At the low-level `packageApp()` boundary, `target` defaults to `'browser'` and
+is independent of `moduleFormat`. Nonbrowser selection disables generated PWA
+content. Native-only files bypass browser document/module/asset transformations;
+a file also in the ordinary browser selection retains that existing processing.
+An explicit low-level `outputDirectory` still wins. Inspect the emitted input
+with `verifyApp({workspaceRoot,appId,outputDirectory:release.output})`; neither
+that inventory verification nor packaging launches the service or platform host.
+See [the complete selection contract](protocols.md#native-only-application-resources).
+
 ## Output and host contract
 
 Each build creates a fresh `arcane-portable-*` directory beneath `outputRoot`.
@@ -85,7 +130,9 @@ host must:
 1. Mount `app/` at the root of its local application URL origin, preserving the
    selected start path and all navigable documents.
 2. Inject `runtime/arcane-api.js` at document creation. It is produced by the
-   canonical `createCoreClassicSource()` generator, not a copied OS client.
+   canonical `createCoreClassicSource()` generator with `replayRuntimeState:true`.
+   Once its transport listener is attached, each document requests the current
+   Core and service state without starting services again.
 3. Start `runtime/arcane-core.mjs` with the host's supported Node runtime and
    connect the existing framed stdin/stdout transport.
 4. Close input and await Core's drain before terminating the child process.
@@ -100,7 +147,21 @@ is not the native serving contract. No host is launched during packaging.
 
 ## Explicit application services
 
-Pass native service modules already included in the selected app release:
+For the ordinary SDK build command, select native service modules in the
+application's authored descriptor. Include their source closure through
+`package.nativeResources` as described above:
+
+```json
+{
+  "native": {
+    "services": [
+      {"module":"native/moon-ledger.mjs", "options":{"ledgerName":"Cheese debts"}}
+    ]
+  }
+}
+```
+
+Direct SDK compositions can instead pass that selection to the provider:
 
 ```js
 import {createPortableNativeProvider} from 'arcane-os/native/portable-provider';
@@ -111,7 +172,8 @@ const nativeBuilder = createPortableNativeProvider({
 ```
 
 Each module default-exports a synchronous factory returning the existing Core
-service definition. Its options must be JSON-serializable data. Module imports
+service definition. Its first argument is the complete authored options record;
+its second is the shared launch context described below. Options must be JSON-serializable data. Module imports
 and factories run only when the generated Core entry is launched, never during
 packaging. Put asynchronous initialization in `start()`, not a top-level await
 or asynchronous factory, so unrelated services and dispatcher readiness remain
@@ -142,8 +204,130 @@ observable through `onError` and `closed`; no process is killed or forcibly exit
 See [the Core runtime contract](core-runtime.md) for request and service lifetime
 details and [the client contract](core-client.md) for native bridge integration.
 
-This source increment supplies portable assembly and service composition.
-Desktop WebView executables, platform child-process ownership, Android dispatch
-and executable build toolchains require their own completed adapters. Published
+## Launch-time locations
+
+The generated Core entry accepts `--arcane-launch-config <path>`. The public
+`readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
+`arcane-os/core/host` reads that explicitly selected JSON object. Without the
+flag it returns `{}`. Missing files, missing flag values and malformed JSON
+report their actual errors; the reader does not search for configuration,
+rewrite it or change the process environment.
+
+The generated entry supplies an artifact-derived `appRoot` and then applies the
+complete explicit launch context. Every service factory receives that same
+object as its second argument, preserving its authored first argument. A
+launcher can supply the user's selected `workspaceRoot` and writable
+`stateRoot` at launch instead of embedding this machine's paths in an app
+package. The host owns those selections; the SDK does not choose a product's
+workspace, namespace, saved preferences or models. JSON values and additional
+application-owned fields remain unchanged.
+
+## Selected local-AI runtimes
+
+When `appDescriptor.native.localAI` is present, portable assembly calls the
+SDK's `bundleLocalAIRuntimes()` owner with its `runtimes` selection and the
+requested target platform/architecture. Its reusable installation directory is
+`<outputRoot>/local-ai-runtimes`; each new payload receives the complete selected
+runtime trees beneath `runtime/local-ai/`. Runtime preparation and app copying
+proceed independently and both settle before assembly can clean up an incomplete
+output. No application service or model executes during packaging.
+
+`manifest.core.localAIRuntimes` records the bundled runtime locations relative
+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
+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.
+
+## Windows executable
+
+The ordinary application command is:
+
+```sh
+npm exec -- arcane build --target windows-x64
+```
+
+`loadArcaneNativeProvider({target:'windows-x64'})` selects the SDK's own
+`arcane-os/native/windows-provider` without an OS checkout or `arcaneRoot`.
+Its default export and `arcaneNativeBuilderProvider` are the same provider;
+`createWindowsNativeProvider({services,hostDirectory})` permits explicit
+same-project composition. Service selection follows the portable provider's
+descriptor/override contract above.
+
+The provider assembles the selected app with the precompiled host asset
+`arcane-native-windows-x64.tar.gz` from the numeric GitHub release matching the
+builder's installed SDK version. The asset contains the launcher, WebView2
+support libraries, Node SEA Core executable and required license files. It does
+not select the newest host independently of that package. Downloads occur only
+during `build()`, use the caller's output directory, and are reused from
+`<outputRoot>/.arcane-native-hosts/<sdk-version>/windows-x64`. The build machine
+needs the standard `tar` command for extraction; application builds do not need
+a C# compiler, system Node installation for the generated executable, or host
+source scripts. The SDK build command itself still runs through the application's
+normal Node/npm toolchain.
+
+An explicit `hostDirectory` selects an already-built complete host tree instead
+of downloading one. This is useful for SDK collaborators verifying the next
+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
+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
+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.
+
+For explicit user-selected workspace/state locations, launch:
+
+```sh
+Arcane.exe --arcane-launch-config path/to/launch.json
+```
+
+The complete JSON object reaches the service factories as their second
+argument. A supplied `stateRoot` also owns the WebView2 profile and diagnostic
+directory. Otherwise the launcher uses the current user's local application
+data under `Arcane/<app-id>`. The launcher does not invent an application
+workspace. Relative launch-file paths resolve from the invocation's working
+directory. `--close-on-stdin-eof` is an explicit process-owner option used by the
+SDK runner; an ordinary double-clicked window closes through its own UI.
+
+## Windows host source and selected output
+
+The SDK's `src/core/hosts/windows/ArcaneCoreProcess.cs` owns an explicitly
+selected executable, argument string and working directory. It reads complete
+framed Core messages and diagnostics, acknowledges ordered asynchronous writes,
+and closes stdin before awaiting accepted Core work, final output and process
+exit. It does not kill the child on an ordinary close.
+
+`ArcaneHost.cs` composes that process with a WebView2 window through
+`ArcaneHost.Run(options,onDiagnostic,onError)` or `ArcaneHostForm`. Options
+select the app root/start path, stable virtual HTTPS origin, profile directory,
+title, canonical classic-client source and Core process inputs. The form exposes
+`Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
+Core readiness and service readiness are separate states. Accepted work drains
+before the window closes; complete engineering errors go to the supplied
+diagnostic/error callbacks. Callbacks must not synchronously wait for the
+window's lifetime promises.
+
+`ArcaneLauncher.cs` supplies the executable entry point for that composition.
+`tools/build-core-windows-host.mjs` builds the selected SDK host output from the
+approved WebView2 package, existing .NET Framework compiler and selected Node
+SEA output. It retains complete compiler diagnostics and produces a fresh
+directory rather than overwriting an earlier artifact. The host requires
+.NET Framework 4.6.2 or later. This is SDK release tooling, not an application
+build requirement. Source compilation, selected host execution and real
+application behavior are separate evidence boundaries; an assembled app is not
+an installer or proof of its domain behavior.
+
+Linux, macOS, Android dispatch and each platform's output verification retain
+their separate delivery boundaries. Published
 consumers must adopt the numeric package that includes this increment; a source
 checkout or a successful source push is not that public package authority.

package/docs/reference/core-runtime.md

@@ -107,6 +107,16 @@ Events have `{protocol, type:'event', event, data, time}`:
 - `core.service.state`: a service's name, state and serialized error when present.
 - `core.error`: a lifecycle or transport diagnostic.
 
+A newly connected document may send
+`{protocol:'arcane/1', type:'control', control:'runtime.replay'}`. The runtime
+publishes one current snapshot: `core.ready` only when the dispatcher is ready,
+then `core.state`, followed by `core.service.state` for every registered service.
+Complete service errors and active request state are retained. Replay does not
+start or restart services, dispatch a request, poll readiness or create a second
+lifecycle owner. The runtime completes that snapshot before publishing lifecycle
+changes triggered reentrantly by its listeners. A draining runtime reports its
+draining state rather than announcing readiness.
+
 Service states are `registered`, `starting`, `ready`, `failed`, `draining` and
 `closed`. Dispatcher states are `created`, `ready`, `draining` and `closed`.
 Complete diagnostics belong in the host's developer-facing error handling, not