arcane-os 0.56.0 → 0.57.0

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

@@ -1,17 +1,87 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.55.0",
+  "sdkVersion": "0.56.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 244,
+  "memberCount": 254,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-local:createCoreLocalAIProvider",
+      "name": "createCoreLocalAIProvider",
+      "displayName": "createCoreLocalAIProvider()",
+      "kind": "function",
+      "signature": "createCoreLocalAIProvider({client,id='llama.cpp'}={})",
+      "entrypoints": ["arcane-os/ai/core-local"],
+      "primaryImport": "arcane-os/ai/core-local",
+      "group": "Core local AI",
+      "summary": "Browser llama.cpp provider through an explicitly connected Core, with application-owned model selection and complete response streaming.",
+      "availability": "Browser with an available Core local AI service; construction installs no runtime or model",
+      "protocol": "arcane-ai-provider/2 LLM lifecycle over arcane/1",
+      "normalization": "Preserves complete payloads and original parsed chunks; waits for the exact requested model and cancels on observed readiness loss"
+    },
+    {
+      "id": "core-local-ai:createLocalAIService",
+      "name": "createLocalAIService",
+      "displayName": "createLocalAIService()",
+      "kind": "function",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})",
+      "entrypoints": ["arcane-os/core/local-ai"],
+      "primaryImport": "arcane-os/core/local-ai",
+      "group": "Core local AI",
+      "summary": "Composes selected native llama.cpp and Ollama engines as a Core service with retained process ownership and model lifecycle.",
+      "availability": "Node with selected upstream runtime distributions or available configured system services",
+      "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE and Ollama native HTTP/NDJSON",
+      "normalization": "Application-owned runtime and model requirements; independent startup, complete responses and exact owned-process cleanup"
+    },
+    {
+      "id": "core-local-ai:default",
+      "name": "default",
+      "displayName": "createLocalAIService default export",
+      "kind": "function",
+      "signature": "default as createLocalAIService",
+      "entrypoints": ["arcane-os/core/local-ai"],
+      "primaryImport": "arcane-os/core/local-ai",
+      "group": "Core local AI",
+      "summary": "Default binding for the same native Core local AI service factory.",
+      "availability": "Node",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createLocalAIService export"
+    },
+    {
+      "id": "local-ai:ensureLocalAIRuntimes",
+      "name": "ensureLocalAIRuntimes",
+      "displayName": "ensureLocalAIRuntimes()",
+      "kind": "function",
+      "signature": "ensureLocalAIRuntimes({runtimes=[],directory,platform,architecture,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai"],
+      "primaryImport": "arcane-os/local-ai",
+      "group": "Core local AI",
+      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp and Ollama distributions.",
+      "availability": "Node; upstream platform and architecture assets determine runtime availability",
+      "protocol": "Official upstream release downloads and host archive extraction",
+      "normalization": "Returns absolute runtime records; shares matching concurrent installs, preserves libraries and reports failures without changing global PATH or services"
+    },
+    {
+      "id": "local-ai:bundleLocalAIRuntimes",
+      "name": "bundleLocalAIRuntimes",
+      "displayName": "bundleLocalAIRuntimes()",
+      "kind": "function",
+      "signature": "bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,platform,architecture,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai"],
+      "primaryImport": "arcane-os/local-ai",
+      "group": "Core local AI",
+      "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
+      "availability": "Node; supports bundling published upstream platform assets independently of the build host",
+      "protocol": "Artifact-relative runtime/local-ai layout",
+      "normalization": "Returns {runtimes,files} with relative runtime records and the complete emitted inventory; model resources remain application-owned"
+    },
     {
       "id": "root:WS",
       "name": "WS",
@@ -380,7 +450,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Packages the selected app and builds one explicitly selected target; tests or checks run only when explicitly requested or required for the selected release output.",
+      "summary": "Packages the selected app and builds one explicitly selected target; paired native assembly applies each selected and bundled app's nativeResources and separate input output directory, preserving complete release records and explicit providers. Tests or checks run only when explicitly requested or required for the selected release output.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -937,14 +1007,14 @@
       "name": "inspectApp",
       "displayName": "inspectApp()",
       "kind": "function",
-      "signature": "async inspectApp({workspaceRoot, appId, signal}={})",
+      "signature": "async inspectApp({workspaceRoot, appId, signal, target, outputDirectory}={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/packager"
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Loads one validated packager app plan, including the shared descriptor-admitted browser document inventory and final workspace-relative output selected by app outputDirectory or default dist/appId.",
+      "summary": "Inspects one complete app plan without copying files. Target defaults to browser; nonbrowser selection adds explicit nativeResources outside browserDocuments and uses dist/.native/target/appId for a nonempty native include list. Explicit operation outputDirectory wins; other calls retain the saved outputDirectory or dist/appId.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1239,7 +1309,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Builds one selected browser application release into app outputDirectory or default dist/appId through staged whole-directory replacement, preserving source and unrelated prior destinations; it never runs tests or checks automatically.",
+      "summary": "Builds one complete app release with browser selection by default. Nonbrowser targets add explicit nativeResources through a late complete-content copy and separate native input output; moduleFormat is independent. Adapters receive actual target and effective browserPwa. Explicit operation outputDirectory wins; staged replacement preserves source and unrelated outputs. No tests or checks run automatically.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1256,7 +1326,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Runs the high-level package operation for one selected application using the same app-selected final outputDirectory, defaulting to dist/appId, with no separate destination override.",
+      "summary": "Runs the high-level browser package operation for one selected application using the saved outputDirectory or dist/appId, with no separate destination override. Paired native buildApplication separately applies actual target and nativeResources selection.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -1370,7 +1440,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Runtime and app descriptors",
-      "summary": "Projects a schema-2 descriptor into the compatible schema-1 application package contract.",
+      "summary": "Projects a schema-2 descriptor into the compatible schema-1 package contract, including optional package.nativeResources as top-level nativeResources; omitted selection stays omitted, empty include stays empty, and omitted exclude becomes an empty array.",
       "availability": "Node",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2073,7 +2143,7 @@
       ],
       "primaryImport": "arcane-os/packager",
       "group": "Packaging and release bundles",
-      "summary": "Validates one schema-1 packager app configuration and its relationship to the root config, including optional workspace-relative final outputDirectory without changing source layout or app identity.",
+      "summary": "Validates one schema-1 packager app configuration, optional nativeResources literal include/exclude selection and workspace-relative outputDirectory without changing source layout or app identity. Native include may be empty; exclude defaults to an empty array.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -2172,7 +2242,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Authenticates one existing browser app release through the low-level packager API.",
+      "summary": "Reads an existing app release and compares its complete file inventory with its manifest. Pass a target-selected native release's output as outputDirectory; this API does not infer a native target or execute services or hosts.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -3835,14 +3905,14 @@
       "name": "createPortableNativeProvider",
       "displayName": "createPortableNativeProvider()",
       "kind": "function",
-      "signature": "createPortableNativeProvider({services=[]}={})",
+      "signature": "createPortableNativeProvider({services}={})",
       "entrypoints": ["arcane-os/native/portable-provider"],
       "primaryImport": "arcane-os/native/portable-provider",
       "group": "Portable native provider",
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases, uses explicit service module factories, reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -3872,6 +3942,62 @@
       "protocol": "arcane-native-builder/1 portable provider",
       "normalization": "Binding identity is exactly equal to the named arcaneNativeBuilderProvider export"
     },
+    {
+      "id": "native-windows-provider:createWindowsNativeProvider",
+      "name": "createWindowsNativeProvider",
+      "displayName": "createWindowsNativeProvider()",
+      "kind": "function",
+      "signature": "createWindowsNativeProvider({services,hostDirectory}={})",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; run cancellation closes stdin and waits for host-owned graceful shutdown"
+    },
+    {
+      "id": "native-windows-provider:arcaneNativeBuilderProvider",
+      "name": "arcaneNativeBuilderProvider",
+      "displayName": "arcaneNativeBuilderProvider",
+      "kind": "singleton",
+      "signature": "const arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "SDK-owned Windows provider selected by the ordinary windows-x64 build command without an OS checkout.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Uses appDescriptor.native.services and the exact SDK release host asset; binding is identical to the default export"
+    },
+    {
+      "id": "native-windows-provider:default",
+      "name": "default",
+      "displayName": "arcaneNativeBuilderProvider default export",
+      "kind": "singleton",
+      "signature": "default as arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "Default binding for the SDK Windows executable provider.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Binding identity is exactly equal to the named arcaneNativeBuilderProvider export"
+    },
+    {
+      "id": "core-host:readCoreLaunchContext",
+      "name": "readCoreLaunchContext",
+      "displayName": "readCoreLaunchContext()",
+      "kind": "function",
+      "signature": "readCoreLaunchContext({argv=process.argv.slice(2)}={})",
+      "entrypoints": ["arcane-os/core/host"],
+      "primaryImport": "arcane-os/core/host",
+      "group": "Native Core host composition",
+      "summary": "Reads the complete JSON object explicitly selected by --arcane-launch-config for native service launch context.",
+      "availability": "Node, including the selected external-entry SEA launcher",
+      "protocol": "Explicit launch arguments and JSON configuration",
+      "normalization": "Returns an empty record without the flag; preserves every supplied field and value, surfaces file and JSON failures, and performs no configuration search, rewrite or environment mutation"
+    },
     {
       "id": "core-host:startCoreHost",
       "name": "startCoreHost",

package/docs/reference/local-ai.md

@@ -0,0 +1,197 @@
+# Local AI through Core
+
+Core owns native llama.cpp and Ollama processes. The browser retains its own
+Wllama and ONNX implementations, and can also use an explicitly connected Core
+when that system service is available. Runtime installation, model loading and
+inference are separate operations.
+
+This native service currently implements llama.cpp and Ollama. Native ONNX
+inference remains separate unfinished work. Browser ONNX continues through its
+existing browser implementation.
+
+## Application requirements
+
+Declare required native runtimes in `arcane-app.json` under `native.localAI`.
+The package projection retains the same record as `arcane-package.json.localAI`.
+Existing native fields remain alongside this record:
+
+```json
+{
+  "runtimes": [
+    {"id": "llama.cpp"},
+    {"id": "ollama"}
+  ],
+  "llamaCpp": {
+    "modelsDirectory": "models/llama"
+  },
+  "ollama": {
+    "modelsDirectory": "models/ollama"
+  }
+}
+```
+
+Each runtime requirement accepts `id`, optional upstream `version`, and an
+optional runtime archive `url`. A string runtime ID is also accepted.
+Omitting the version allows reuse of an available runtime. Explicit versions
+select that upstream distribution; an existing service must match the requested
+version before it is reused. A service occupying the selected address is
+preserved when its version cannot be established.
+
+`llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
+`model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
+mode. Paths resolve from the application root. Ollama accepts `url`,
+`modelsDirectory`, and `args`. The default endpoints are
+`http://127.0.0.1:8080` and `http://127.0.0.1:11434`, respectively. Default model
+directories are `.arcane/models/llama.cpp` and `.arcane/models/ollama` inside the
+application. Applications choose and provision their models explicitly.
+
+## Development
+
+```sh
+arcane dev --local-ai llama.cpp,ollama
+```
+
+The option adds those runtime requirements to the authored application
+configuration. Subsequent `arcane dev` runs reuse the saved requirements.
+Development checks selected endpoints and existing executable paths, then
+installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
+Runtime preparation runs alongside HTTP serving. Browser rendering continues
+while installation and model readiness are pending.
+
+The SDK downloads the official llama.cpp or Ollama distribution directly and
+preserves its runtime libraries. Installation changes no global PATH, system
+service or machine environment. Windows and macOS use the host archive utility;
+Linux requires `tar`, and `unzip` when extracting a selected Windows ZIP.
+Zstandard archives use the supported Node runtime's decompressor.
+
+For the optional development browser connection, load the bootstrap after the
+managed import map and before creating a Core-backed provider:
+
+```js
+const {client} = await import('/arcane-local-ai.js');
+const status = await client.invoke('localai.status');
+console.log(status);
+```
+
+The bootstrap uses the existing Core client with RPC and ordered SSE events.
+Each browser connection owns its requests and cancellation. Closing a tab
+cancels that tab's requests; closing development stops its owned runtime
+processes. An already running external service remains running.
+
+`developApplication()` returns its usual server handle and an optional `localAI`
+handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
+means installation and Core composition completed. Runtime/model readiness is
+reported separately by Core status and lifecycle events. Preparation failures
+remain on that promise and the operation event stream.
+
+## Core service
+
+```js
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const service = createLocalAIService(application.native.localAI, {
+  appRoot,
+  runtimes,
+  signal,
+  onEvent
+});
+```
+
+The result is a Core service definition. The launch context contains resolved
+runtime records; the native builder supplies them automatically for a selected
+application. `current()` returns the current snapshot without starting another
+process. The service starts each selected runtime independently, retains its
+process between requests, and joins cleanup during disposal.
+
+`localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
+`ollama` and `models.ollama` catalog fields. Runtime records distinguish
+`installed`, `available`, `state`, `models`, ownership and errors. A listening
+service and a loaded model are separate facts.
+
+`localai.services.recover({runtimes: ['llama.cpp']})` makes one explicit recovery
+attempt for the selected runtimes; omission selects all configured runtimes.
+Recovery restarts only SDK-owned processes and reconnects to external services.
+An external llama.cpp server returns HTTP 503 during initial model loading and
+offers no readiness subscription at that stage. Core retains `state: 'loading'`;
+a subsequent explicit load or recovery request checks again. There is no
+background health polling.
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `llama.status` | `{}` | Runtime state and model catalog |
+| `llama.models` | `{}` | `{models}` |
+| `llama.load` | `{model}` | State after the exact model reports loaded |
+| `llama.unload` | `{model}` | Current state after release |
+| `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
+
+The `payload` is the complete request. SDK option names are translated only at
+the upstream protocol boundary; messages, tool definitions and documents remain
+unchanged. An explicit `payload.model` selects that request's model. Core waits
+for its actual readiness before inference. Router model-load work is shared
+between concurrent callers for the same model. Cancelling a caller stops its
+wait; explicit unloading releases the model.
+
+Streaming publishes every actual parsed upstream chunk as
+`llama.chunk: {streamId,chunk}` and assembles the terminal completion. Upstream
+stream errors remain visible as their original chunks and fail the request.
+`localai.state` carries current runtime/model state. Router lifecycle events
+observe load, sleep and unload changes. Direct servers expose readiness at
+request boundaries; they do not offer the router's passive model event stream.
+
+Unloading a model from an owned single-model server closes that owned process;
+a subsequent load can start it again. Releasing an externally owned direct
+server returns `released: true, unloaded: false`, retaining the real catalog
+and leaving that server running.
+
+Ollama retains the existing Core calls for `version`, `models`/`list`, `running`,
+`show`, `chat`, `generate`, `embed`, `pull`, `push`, `create`, `copy`, and `delete`.
+Those methods use Ollama's native API. Streaming uses the existing
+`ollama.chunk: {streamId,chunk}` event. Application/OS preference operations
+such as selection, settings and brain creation remain with their existing
+owners; they are separate from this runtime service.
+
+## Browser llama.cpp provider
+
+```js
+import {createCoreLocalAIProvider} from 'arcane-os/ai/core-local';
+import {getAIProviderRuntime} from 'arcane-os/ai-provider-runtime';
+
+const provider = createCoreLocalAIProvider({client});
+const runtime = getAIProviderRuntime();
+const unregister = runtime.register(provider);
+```
+
+The provider implements `arcane-ai-provider/2` for the LLM role, with ID
+`llama.cpp` by default. Configure an exact model through the existing provider
+runtime, then load it. `catalog()`, `status()`, `inspect()`, `load()`, `request()`,
+`unload()` and `dispose()` retain the shared lifecycle. Creating the provider
+does not install software or select a model. A missing Core connection reports
+unavailability, leaving browser Wllama/ONNX routes available for the application
+to select.
+
+If a router evicts the primary model while serving a request-specific model,
+reload the primary selection before its next request. The provider does not
+silently change the application's saved model choice. Release registration
+with `unregister()` and dispose the provider at the application's owning
+lifecycle boundary.
+
+## Native bundling
+
+The SDK portable native build includes selected official runtime trees under
+`runtime/local-ai/<runtime-id>`. Runtime records in the artifact are relative
+to the artifact root and resolve on the destination machine. The generated
+Core entry composes the local AI service only when the application selects it.
+Model files remain application-selected native resources.
+
+`ensureLocalAIRuntimes()` and `bundleLocalAIRuntimes()` are exported from
+`arcane-os/local-ai`. Both accept `{runtimes,directory,platform,architecture,
+signal,onEvent}`; bundling also requires `outputRoot`. Platform names follow
+Node: `win32`, `linux`, `darwin`, and supported Android distributions.
+Architectures are `x64` or `arm64`. Availability depends on the upstream
+runtime's published platform assets; Ollama has no official Android runtime
+archive in this installer.
+
+Ensure returns absolute `{id,version,platform,architecture,root,executable}`
+records. Bundle returns `{runtimes,files}`, with artifact-relative runtime paths
+and a complete emitted file inventory. Bundling requires a fresh native staging
+destination, preserving existing completed outputs.

package/docs/reference/protocols.md

@@ -147,9 +147,70 @@ included resources without receiving application-document processing.
 Component processing and shared runtime-resource traversal retain their existing
 behavior. Offline inclusion still follows the app's PWA resource selection.
 
+## Native-only application resources
+
+An application's schema-2 `arcane-app.json` can explicitly select server modules
+and their complete app-owned source closure without adding them to its browser
+or PWA output:
+
+```json
+{
+  "package": {
+    "include": ["index.html", "modules", "css"],
+    "nativeResources": {
+      "include": ["server", "src", "package.json"],
+      "exclude": ["server/drafts"]
+    }
+  }
+}
+```
+
+This is a package excerpt. Each path is literal and relative to the application
+root; a directory includes its descendants. The app selects the full required
+closure explicitly. The SDK does not crawl imports to discover server source,
+filter it by extension, install app dependencies or execute a service.
+`nativeResources.include` is required and may be empty; `exclude` defaults to
+`[]`. Descriptor projection writes the same record at the top level of schema-1
+`arcane-package.json`, and package-only apps may author it there directly.
+Omission remains omission. The native registry descriptor is unchanged.
+
+`packageApp({target})` and `inspectApp({target})` default to `'browser'`. A
+nonbrowser SDK target adds these resources to the ordinary app/shared selection.
+Native exclusions apply only to the additional selection, not the browser
+selection. A file selected by both is emitted once through its ordinary browser
+processing. Files selected only as native resources retain their complete
+original content, including imports, HTML, line endings and data. They are copied
+after browser document discovery, module projection, asset rewriting and PWA
+processing, and appear in the complete release inventory. A collision with
+generated output reports an error instead of replacing that output.
+
+Target and module representation are independent: `moduleFormat:'native'`
+controls browser module/script packaging and does not select native resources.
+Nonbrowser targets use effective `browserPwa:false`; ordinary browser calls keep
+their configured PWA behavior. An app adapter receives `target` and effective
+`browserPwa` in its existing `buildArcanePackage()` context. Its `copyBase()`
+copies ordinary browser/shared files; the packager appends native-only files
+after the adapter and browser transformations finish.
+
+A nonbrowser target with a nonempty native include list writes its app input to
+`dist/.native/<target>/<app-id>`, even when the saved browser `outputDirectory`
+is custom. This keeps an existing browser/PWA output separate. An explicit
+low-level `outputDirectory` override takes precedence; it must name the
+dedicated output the caller intends to replace. Omitted or empty native
+resources preserve the existing output rules. `inspectApp()` reports the
+effective `output` and complete selected files without writing them.
+
+Paired native `buildApplication()` applies the same selected target and output
+resolution to the selected app and every explicitly bundled app. Each app keeps
+its own declaration; the provider receives actual release roots and complete
+release records. Native artifact `outputRoot` remains a different directory.
+Use `verifyApp({workspaceRoot,appId,outputDirectory:release.output})` to inspect
+that emitted app release; verification does not launch its services or host.
+See [the portable service composition guide](core-native-packaging.md#native-only-application-resources).
+
 ## App-selected package output
 
-An app may set `"outputDirectory": "ai"` in its schema-1
+For browser selection, an app may set `"outputDirectory": "ai"` in its schema-1
 `arcane-package.json`. This selects the final directory relative to the
 workspace: `<workspace>/ai`, not `<workspace>/ai/<app-id>`. Omitting the
 field retains `dist/<app-id>`. The root `arcane-packager.json` configuration
@@ -185,6 +246,10 @@ output must remain separate; a conflicting native assembly fails before it
 packages any app. App launch paths, resource URLs, and enabled PWA
 representations retain their package-relative layout.
 
+The [native-only resource selection](#native-only-application-resources) above
+adds a separate default native input directory when its include list is nonempty.
+An explicit low-level output override still selects the exact directory to replace.
+
 ## Native-module package output
 
 The public `packageApp` operation accepts `moduleFormat:'native'`. Omission, or
@@ -193,6 +258,9 @@ The public `packageApp` operation accepts `moduleFormat:'native'`. Omission, or
 accepts that same override. Configuration, source layout, app identity, storage
 scope and previously generated sibling outputs remain unchanged.
 
+This module format does not select a native target. Use the separate `target`
+option for [native-only resources](#native-only-application-resources).
+
 The native transformation runs in the selected package stage after application
 adapter work, before the final inventory and any enabled PWA artifacts. It uses
 the existing selected document/runtime records and shared lexical/HTML owners.

package/docs/reference/runtime-modules.md

@@ -2252,10 +2252,11 @@ and `read`, filters source metadata before calling
 ### Availability and normalization
 
 **Browser or compatible host with an injected DBOPFS adapter.** The adapter
-keeps the existing `get`, `set`, `getAllKeys`, and `delete` method names; Node
-can use the same class only through an explicitly imported runtime module and a
-compatible storage adapter; SDK `0.5.12` publishes no Node package subpath or
-Node storage implementation for it. Bootstrap uses a concurrent
+keeps the existing `get`, `set`, `getAllKeys`, and `delete` method names. Node
+callers import the same class and factory from the public
+`arcane-os/dbopfs-document-library` subpath and supply a compatible storage
+adapter. That export supplies no Node filesystem storage implementation.
+Bootstrap uses a concurrent
 generation, commits its manifest last, cleans partial data on failure, and
 rejects case-colliding IDs. Search
 returns `{failures,matches,total}` so one malformed record remains visible
@@ -2414,7 +2415,7 @@ const search = new DocumentLexicalSearch([{
   kind: 'guide',
   tags: ['intro']
 }]);
-console.log(search.search('portable', {limit: 5}));
+console.log(search.search('portable'));
 ```
 
 ## DocumentNavigation.js