arcane-os 0.1.0-dev.5

package/docs/reference/core/arcane-entities.md

@@ -0,0 +1,65 @@
+# Arcane Shared Entities
+
+## Purpose
+
+The modules under `arcane/entities/` provide shared JavaScript records, value
+objects, validation helpers, and contract vocabularies for Arcane applications.
+This reference is the canonical inventory of their public module exports. The
+export key is `<module path>#<export name>`; `default` denotes a module's default
+export. Import only the exports listed here, and do not depend on unexported
+implementation details.
+
+The `Kind` column describes the exported JavaScript value: `class`, `function`,
+or `constant`. Detailed, versioned rules for intent envelopes and TWiN policy
+decisions remain authoritative in the linked contract documents.
+
+## Export inventory
+
+| Export key | Kind | Runtime symbol | Public contract |
+|---|---|---|---|
+| `arcane/entities/ApiModelRecord.js#default` | class | `ApiModelRecord` | Validates and freezes an HTTP(S) API response snapshot containing its endpoint, fetch time, metadata, and value. |
+| `arcane/entities/Calculation.js#default` | class | `Calculation` | Validates and freezes a bounded expression, finite numeric result, and creation time. |
+| `arcane/entities/Chat.js#default` | class | `ChatEntity` | Owns a browser chat session's messages, tool exchanges, memory extraction, and optional DBOPFS persistence in the `chats` table. |
+| `arcane/entities/CommunicationMessage.js#default` | class | `CommunicationMessage` | Normalizes and freezes one provider message, including addressing, channel, direction, delivery state, timestamp, and attachment metadata. |
+| `arcane/entities/CommunicationMessage.js#communicationChannels` | constant | `communicationChannels` | Shared `Set` of recognized message-channel identifiers: `email`, `sms`, `mms`, `rcs`, `whatsapp`, and `other`; consumers must not mutate it. |
+| `arcane/entities/CommunicationThread.js#default` | class | `CommunicationThread` | Normalizes and freezes a provider conversation snapshot with participants, unread state, and `CommunicationMessage` records. |
+| `arcane/entities/Document.js#default` | class | `DocumentEntity` | Specializes `FileEntity` with `documents` as its default DBOPFS table. |
+| `arcane/entities/File.js#default` | class | `FileEntity` | Addresses a DBOPFS file by table and name, saves supported file data, and opens files with MIME and format-aware parsing metadata. |
+| `arcane/entities/Image.js#default` | class | `ImageEntity` | Specializes `FileEntity` for the `images` table and exposes image validation, storage, data-URL, and blob-URL helpers. |
+| `arcane/entities/IntentEnvelope.js#IntentEnvelopeValidationError` | class | `IntentEnvelopeValidationError` | Privacy-safe validation error with stable `code` and structural `path` fields; see the [intent-envelope contract](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/intent-envelope.md#errors). |
+| `arcane/entities/IntentEnvelope.js#createIntentEnvelope` | function | `createIntentEnvelope` | Validates an intake payload separately from trusted identity, time, and provenance context, then returns an immutable v1 envelope; see the [creation authority boundary](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/intent-envelope.md#creation-authority-boundary). |
+| `arcane/entities/IntentEnvelope.js#rehydrateIntentEnvelope` | function | `rehydrateIntentEnvelope` | Validates and reconstructs a canonical v1 envelope object or JSON string without asserting authenticity or authority. |
+| `arcane/entities/IntentEnvelope.js#serializeIntentEnvelope` | function | `serializeIntentEnvelope` | Produces deterministic canonical JSON for a valid v1 intent envelope. |
+| `arcane/entities/IntentEnvelope.js#intentEnvelopeAuditProjection` | function | `intentEnvelopeAuditProjection` | Produces a frozen, bounded structural projection that excludes original expression and other documented content fields; see the [public API contract](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/intent-envelope.md#public-api). |
+| `arcane/entities/IntentEnvelope.js#intentEnvelopeContract` | constant | `intentEnvelopeContract` | Frozen v1 schema identifier, version, closed enum vocabularies, and size/count limits. |
+| `arcane/entities/Preference.js#default` | class | `Preference` | Validates and freezes one typed preference definition and normalizes candidate values against its type, bounds, and options. |
+| `arcane/entities/Preference.js#preferenceSchema` | function | `preferenceSchema` | Converts definitions to `Preference` instances, rejects duplicate keys, and returns a frozen schema array. |
+| `arcane/entities/TerminalSession.js#default` | class | `TerminalSession` | Validates terminal identity, shell, and lifecycle state and supports immutable-style patched copies through `with()`. |
+| `arcane/entities/TerminalSession.js#terminalShells` | constant | `terminalShells` | Frozen array of supported shell identifiers: `auto`, `powershell`, `cmd`, `bash`, and `sh`. |
+| `arcane/entities/Theme.js#arcaneLightThemeTokens` | constant | `arcaneLightThemeTokens` | Frozen map of the default light-scheme semantic color tokens. |
+| `arcane/entities/Theme.js#arcaneDarkThemeTokens` | constant | `arcaneDarkThemeTokens` | Frozen map of the default dark-scheme semantic color tokens. |
+| `arcane/entities/Theme.js#themeTokens` | constant | `themeTokens` | Frozen ordered definitions that map public theme-token keys to CSS custom properties, labels, and defaults. |
+| `arcane/entities/Theme.js#themeColorToHex` | function | `themeColorToHex` | Validates an RGB, RGBA, or six-digit hexadecimal color and returns its RGB channels as a normalized six-digit hexadecimal color. |
+| `arcane/entities/Theme.js#default` | class | `Theme` | Validates and freezes a named light or dark token set and can serialize, restore, apply, or clear that theme on a document root. |
+| `arcane/entities/TWiNPolicyDecision.js#TWiNPolicyDecisionValidationError` | class | `TWiNPolicyDecisionValidationError` | Privacy-safe policy-decision validation error with stable `code` and structural `path` fields; see the [TWiN error contract](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/twin-policy-decision.md#failure-and-recovery). |
+| `arcane/entities/TWiNPolicyDecision.js#createTWiNPolicyDecision` | function | `createTWiNPolicyDecision` | Validates an evaluator payload separately from trusted decision and policy provenance, then returns an immutable v1 decision; see the [trusted creation boundary](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/twin-policy-decision.md#trusted-creation-boundary). |
+| `arcane/entities/TWiNPolicyDecision.js#rehydrateTWiNPolicyDecision` | function | `rehydrateTWiNPolicyDecision` | Validates and reconstructs a canonical v1 policy-decision object or exact canonical JSON without asserting authenticity, freshness, or authority. |
+| `arcane/entities/TWiNPolicyDecision.js#serializeTWiNPolicyDecision` | function | `serializeTWiNPolicyDecision` | Produces deterministic canonical JSON for a valid v1 TWiN policy decision. |
+| `arcane/entities/TWiNPolicyDecision.js#twinPolicyDecisionAuditProjection` | function | `twinPolicyDecisionAuditProjection` | Produces a frozen structural audit projection that omits requirement targets and values; see [privacy and audit behavior](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/twin-policy-decision.md#privacy-and-audit-behavior). |
+| `arcane/entities/TWiNPolicyDecision.js#twinPolicyDecisionContract` | constant | `twinPolicyDecisionContract` | Frozen v1 schema identifier, version, layers, outcomes, core reason codes, and size/count limits. |
+| `arcane/entities/User.js#default` | class | `UserEntity` | Owns the browser user's validated settings and profile record, including DBOPFS load, refresh, serialized updates, and optional persistence. |
+| `arcane/entities/Weather.js#WeatherLocation` | class | `WeatherLocation` | Validates and freezes geographic identity, coordinates, and timezone metadata for a weather location. |
+| `arcane/entities/Weather.js#WeatherObservation` | class | `WeatherObservation` | Validates and freezes one timestamped current-weather observation and its units. |
+| `arcane/entities/Weather.js#WeatherDay` | class | `WeatherDay` | Validates and freezes one daily forecast with temperature, precipitation, and optional sunrise and sunset times. |
+| `arcane/entities/Weather.js#WeatherSnapshot` | class | `WeatherSnapshot` | Validates and freezes a location, current observation, daily forecast list, source, and fetch time as one weather snapshot. |
+
+## Compatibility boundary
+
+An exported entity validates and represents data; it does not grant a capability,
+authorization, native resource handle, provider credential, or policy approval.
+Consumers must preserve the separate Arcane capability and trust boundaries that
+govern persistence, networking, native execution, and protected data.
+
+Changing an export name, kind, meaning, enum, accepted shape, serialization, or
+validation invariant is a public-contract change. Update the implementation,
+this inventory, its focused tests, and any linked versioned contract together.

package/docs/reference/core/arcane-events.md

@@ -0,0 +1,134 @@
+# Arcane events
+
+`Arcane.events` delivers renderer-visible host and Core events. A named subscription such as `Arcane.events.on('operation.progress', listener)` receives that event's payload object directly. A wildcard subscription made with `Arcane.events.on('*', listener)` receives an envelope shaped as `{ event, data }`; `*` is a subscription selector, not an emitted event name.
+
+`Arcane.events.on()` and `Arcane.events.once()` observe only future deliveries. `Arcane.events.once()` removes its subscription before invoking the listener and therefore observes only the next matching delivery. Most events are live notifications and are not replayed, so subscribe before starting the work that can emit them.
+
+`transport.ready` and `core.ready` are the two durable completion events. `Arcane.events.when(name, listener)` accepts only those names. It waits once when completion has not happened, or asynchronously replays the first deeply frozen JSON snapshot when completion has already happened. `Arcane.events.completed(name)` reports whether a designated durable event has completed; it is not a payload accessor.
+
+Every subscription method returns an unsubscribe function. Call it when the owning view or task is torn down. An exception thrown by one listener is caught and reported to the console, and does not stop the remaining named or wildcard listeners.
+
+## Event inventory
+
+| Event | Delivery | Hosts | Trigger | Payload |
+| --- | --- | --- | --- | --- |
+| `transport.ready` | Durable completion. The first payload is frozen; a late `when()` subscriber receives an asynchronous replay. | Every initialized Arcane transport: Microsoft NT WebView2, Linux WebKitGTK, Android WebView, and development HTTP. | The renderer initializes the bridge and selects its available transport. | `protocol` is the selected wire-protocol identifier; `transport` is `webview2`, `webkitgtk`, `android-webview`, or `development-http`. |
+| `core.ready` | Durable completion. The first payload is frozen; a late `when()` subscriber receives an asynchronous replay. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | The Core has installed its input handlers and is ready to accept requests. | `pid` is the Core process ID; `version` is its Arcane version; `app` is the active application mode; `platform` is the public operating-system snapshot; `elevated` reports elevated execution; `simulation` reports simulation mode. |
+| `core.error` | Live, future-only notification. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | The Core cannot decode or handle an inbound control frame. | A normalized error object: `code` and `message` identify the failure; fields such as `resolution`, `technicalMessage`, `status`, `retryable`, and `diagnosticId` provide recovery and diagnostic context when available. |
+| `operation.started` | Live, future-only operation notification. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | A tracked Core operation is created. | `requestId` correlates the initiating API request; `operationId` identifies the tracked operation; `operationType` names its kind; `time` is the operation start timestamp. |
+| `operation.log` | Live, future-only operation notification; one operation can emit many entries. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | A tracked operation records a log entry. | `requestId`, `operationId`, and `operationType` correlate the operation; `time` timestamps the entry; `level` classifies it; `message` is the readable entry; `details` carries optional structured context. |
+| `operation.progress` | Live, future-only operation notification; one operation can emit many updates. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | A tracked operation advances or reports its current step. | `requestId`, `operationId`, and `operationType` correlate the operation; `progress` is its nondecreasing percentage; `message` describes the current step; `details` is optional structured progress context. |
+| `operation.completed` | Live, future-only terminal operation notification. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | A tracked operation finishes successfully, including success with warnings. | `requestId`, `operationId`, and `operationType` correlate the operation; `result` is its public result; `credentials` carries any operation-issued credentials and must be treated as sensitive; `details` is final progress context; `warningCount` counts warnings; `message` summarizes completion; `time` is the completion timestamp. |
+| `operation.failed` | Live, future-only terminal operation notification. | Core-backed Microsoft NT, Linux, and development HTTP hosts. | A tracked operation reaches its failure path. | `requestId`, `operationId`, and `operationType` correlate the operation; `error` is the normalized failure object; `details` is final progress context; `time` is the failure timestamp. |
+| `ollama.chunk` | Live, future-only correlated stream notification. | Core-backed hosts and admitted Android application hosts for proxied chat streaming. | An Ollama streaming operation receives its next response chunk. | `streamId` identifies the stream selected by the caller or Arcane; `operation` names the streamed Ollama operation; `chunk` is the provider response object for that delivery. |
+| `localai.isolated.phase` | Live, future-only correlated operation notification. | Core-backed hosts for an application admitted to isolated inference. | An isolated-model question enters a lifecycle phase or emits a chat heartbeat. | `operationId` correlates the request; `phase` is `unload_before`, `verify_before`, `chat`, `unload_after`, or `verify_after`; chat heartbeats additionally set `heartbeat` to `true`, report `elapsedMs`, and timestamp themselves with `at`. |
+| `terminal.output` | Live, future-only correlated session stream. | Core-backed Arcane Terminal and Android Arcane Terminal hosts. | A terminal process produces standard output or standard error. | `sessionId` identifies the terminal session; `stream` is `stdout` or `stderr`; `data` is a UTF-8 text chunk and is not guaranteed to be a complete line. |
+| `terminal.exit` | Live, future-only terminal session notification. | Core-backed Arcane Terminal and Android Arcane Terminal hosts. | A terminal process exits and the host removes its session. | `sessionId` identifies the terminal session; `exitCode` is the process exit code when available; `signal` is the terminating signal name or `null`. |
+| `terminal.error` | Live, future-only terminal session notification. | Android Arcane Terminal hosts. | Android stops a session at its output limit or cannot read one of its output streams. | `sessionId` identifies the terminal session; `message` explains the output-limit or stream-reading failure. |
+| `appearance.changed` | Live, future-only host notification. | Microsoft NT WebView2 hosts. | The host observes an operating-system appearance change. | `scheme` is the configured host scheme; `effectiveScheme` is the resolved `dark` or `light` scheme; `source` is `windows`. |
+
+### Subscribe and clean up
+
+Keep the returned function with the UI or operation that owns the subscription:
+
+```js
+const stopProgress = Arcane.events.on('operation.progress', function handleOperationProgress(data) {
+  console.info(`${data.operationId}: ${data.progress}%`, data.message);
+});
+
+window.addEventListener('pagehide', stopProgress, { once: true });
+```
+
+A wildcard listener is useful for routing or diagnostics, but its callback shape differs from a named listener. Avoid logging payloads indiscriminately because results can contain credentials or other sensitive values.
+
+```js
+const observedEventNames = [];
+const stopObserving = Arcane.events.on('*', function handleAnyArcaneEvent({ event, data }) {
+  observedEventNames.push(event);
+  routeArcaneEvent(event, data);
+});
+
+window.addEventListener('pagehide', stopObserving, { once: true });
+```
+
+### Wait for durable readiness
+
+Use `when()` when a component can mount before or after readiness. The callback is still asynchronous when the durable completion already exists.
+
+```js
+const stopReady = Arcane.events.when('core.ready', function handleCoreReady({ version, platform }) {
+  showRuntimeReady({ version, platform });
+});
+
+if (Arcane.events.completed('core.ready')) {
+  showRuntimeConnecting(false);
+}
+
+window.addEventListener('pagehide', stopReady, { once: true });
+```
+
+Do not use `when()` for operation, streaming, terminal, appearance, or error events. Those events have no retained completion value.
+
+### Follow a terminal lifecycle
+
+Subscribe before `Arcane.terminal.start()`. Output, exit, or error delivery can race the start response, so buffer by `sessionId` until the returned session identifies the stream to keep. Append `data` chunks as delivered rather than assuming one event equals one line.
+
+```js
+const terminalOutput = document.querySelector('[data-terminal-output]');
+const buffered = [];
+const maxBufferedEvents = 128;
+let sessionId = null;
+
+function handleTerminalEvent(event, data) {
+  if (sessionId === null) {
+    buffered.push({ event, data });
+    // Bound pre-identification buffering; surface truncation in a real UI.
+    if (buffered.length > maxBufferedEvents) buffered.shift();
+    return;
+  }
+  if (data.sessionId !== sessionId) return;
+  if (event === 'terminal.output') {
+    terminalOutput?.append(document.createTextNode(data.data));
+  } else if (event === 'terminal.exit') {
+    terminalOutput?.append(document.createTextNode(`\n[exit ${data.exitCode}]`));
+  } else {
+    terminalOutput?.append(document.createTextNode(`\n[terminal error: ${data.message}]`));
+  }
+}
+
+const stopTerminalEvents = [
+  Arcane.events.on('terminal.output', function handleTerminalOutput(data) {
+    handleTerminalEvent('terminal.output', data);
+  }),
+  Arcane.events.on('terminal.exit', function handleTerminalExit(data) {
+    handleTerminalEvent('terminal.exit', data);
+  }),
+  Arcane.events.on('terminal.error', function handleTerminalError(data) {
+    handleTerminalEvent('terminal.error', data);
+  }),
+];
+
+try {
+  const session = await Arcane.terminal.start({ shell: 'auto' });
+  sessionId = session.id;
+  for (const item of buffered.splice(0)) handleTerminalEvent(item.event, item.data);
+  const lineEnding = ['powershell', 'cmd'].includes(session.shell) ? '\r\n' : '\n';
+  await Arcane.terminal.write(sessionId, `echo ready${lineEnding}`);
+} finally {
+  if (sessionId !== null) {
+    await Arcane.terminal.close(sessionId).catch(function ignoreTerminalCloseFailure() {});
+  }
+  for (const stop of stopTerminalEvents) stop();
+}
+```
+
+Use the host-appropriate line ending when submitting interactive commands: `\r\n` for PowerShell or Command Prompt and `\n` for POSIX shells.
+
+### Event lifecycle guidance
+
+- Subscribe before starting work, then correlate with `requestId`, `operationId`, `streamId`, or `sessionId`. Unrelated work can emit the same named event concurrently.
+- Treat `operation.completed` and `operation.failed` as the terminal event for an `operationId`; progress and log events are intermediate and are not retained.
+- Treat `operation.completed.credentials` as sensitive. Do not write it to logs or durable application storage.
+- Treat streaming and terminal payloads as ordered deliveries for their correlation ID, not as complete messages or lines. Apply resource bounds when buffering.
+- Unsubscribe on teardown even after a one-shot workflow. `once()` and a pending `when()` clean themselves up when invoked, but their returned unsubscribe function cancels an abandoned wait.
+- Host scope describes where an event can be emitted; it does not grant the capability needed to start the underlying operation.

package/docs/reference/core/ollama-module.md

@@ -0,0 +1,181 @@
+# Arcane Ollama module
+
+Arcane applications can use the managed, machine-wide Ollama service only
+through their app-scoped Core, without connecting directly to
+`localhost:11434`. Import the shared module and let Core enforce the packaged
+application policy, native resource admission, and declared capabilities. An
+ordinary browser has no Core local-model authority and is OpenAI-only.
+
+## Upstream Arcane OS model
+
+This section describes assets and maintainer commands in the pinned upstream
+[ARCANE-OS repository](https://github.com/TheWizardNexus/ARCANE-OS/tree/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e),
+not files or npm scripts supplied by `arcane-os`. SDK application developers
+use the browser module and an external Core/service only after this SDK's
+current native plan admits the selected checkout and Core through its exact
+protocol, version, feature, capability, method, provider, and identity-bound
+receipt checks. That admission is current-build evidence, not a future SDK/Core
+compatibility promise. Developers do not run these repository-maintenance
+commands from an app or SDK checkout.
+
+Arcane OS includes `arcane/models/Arcane-3B.Modelfile`, `arcane/models/Arcane-8B.Modelfile`, `arcane/models/Arcane-12B.Modelfile`, `arcane/models/Arcane-20B.Modelfile`, and `arcane/models/Arcane-120B.Modelfile`. They create the durable `arcane:3b`, `arcane:8b`, `arcane:12b`, `arcane:20b`, and `arcane:120b` variants, while `arcane:latest` points to the user's effective choice through the machine-wide `ArcaneOllama` service. The 3B definition uses `granite4.1:3b-q4_K_M` with a memory-bounded 16,384-token context.
+
+After base installation succeeds and its installation transaction is complete,
+opening Provisioner performs one fresh live machine-requirement check. On
+Microsoft NT, if the installed Arcane identity is valid and the candidate is trusted, global Ollama is missing or
+unhealthy, and the user-scoped Ollama process is confirmed inactive, Provisioner
+starts exactly one noninterrupting verified global ensure. An installed
+user-scoped copy neither satisfies nor blocks that action. An active or unknown
+process state requires explicit close-and-retry confirmation, and the automatic
+request carries a native deny-user-process-interruption policy so a process that
+appears or restarts at the mutation boundary is not terminated. Provisioner open
+never starts model reconciliation. A separate explicit post-install flow may
+request one non-privileged model reconciliation after Core verifies that the
+machine-wide service is ready. Arcane Shell is the sole automatic boot-recovery owner and
+idempotently reconciles the selected model after Core is ready. The Shell's
+Settings dialog lets the user
+choose Automatic or an explicit 3B, 8B, 12B, 20B, or 120B variant. Automatic
+considers only 8B and then 3B; 12B, 20B, and 120B are explicit choices and are
+not probed or downloaded by the automatic policy. Core admits a candidate from
+actual installed model bytes and metadata, requested context and K/V-cache
+estimate, current free system and GPU memory, loaded-model residency, safety
+reserves, and pull storage when applicable. Missing evidence fails closed; a
+GPU name or variant label is never fit evidence.
+
+When 8B and 3B both receive conclusive native capacity rejections, the user may
+explicitly select a configured account-accessible OpenAI model. Arcane never
+rewrites the provider automatically. Missing credentials, an unavailable
+account model, unreachable local services, registry or metadata failures, and
+unavailable resource evidence do not prove that no local model fits and never
+authorize cloud use.
+
+Only the effective Arcane candidate is processed. Core reports owned model
+progress through `operation.progress`, creates the named variant from an
+already-installed admitted base when needed, selects it as `arcane:latest`, and
+verifies both names through the service API. For a missing base, the managed
+path uses bounded library-registry manifest/configuration evidence and GGUF
+prefix ranges up to 256 KiB for pull admission. A range is not full integrity
+proof: Ollama must complete full-layer digest verification before Core creates
+or verifies an alias. Missing pre-download bytes or metadata fails closed. Model
+progress is coalesced to at most four transfer updates per second, with a
+five-second heartbeat while Ollama is silent. Its structured
+`details` distinguish overall setup progress from the current layer and expose
+phase, model and digest identity, per-layer and observed aggregate bytes,
+elapsed time, evidence-based rate and layer ETA, and truthful
+interruption/resume guidance. Unknown totals remain unknown.
+
+When the Provisioner explicitly starts its post-install reconciliation after the global service requirement succeeds, it renders those details as a dedicated model-transfer bar beside the already-completed installation result. Opening Provisioner may run the single guarded global-service ensure described above, but it never starts model reconciliation. The Shell uses the same progress contract for its automatic idempotent recovery and for Settings changes. The Microsoft NT and Linux hosts warn before closing a host during a managed model request. A download retry reuses Ollama's saved partial data; an interrupted model load restarts when Arcane reopens.
+
+Each application's supported model list exists only in its
+`arcane-package.json.localAIModelPolicy`, and every product definition remains
+under its owning app. The app release carries the policy as native admission metadata;
+the native packager injects it only into compiled Core. Profile controls render
+the ordered, filtered, and admitted `Arcane.localAI.status().models.ollama`
+catalog without a second renderer list. Product aliases are lazy: Core creates
+or repairs only the exact selected declared alias from an installed admitted
+base on first native inference. Ordinary browsers have no local-model authority.
+
+The service is configured with the global `OLLAMA_MODELS` directory. Arcane clients never write model layers directly into that protected directory. Fresh installation and verified service repair choose bounded service capacity from hardware evidence; ordinary startup and model selection do not rewrite service settings. An explicitly authorized application may call `Arcane.localAI.setParallelRequests({model,parallelRequests,contextTokens?})`: Core solves the current model-specific memory ceiling directly from model and machine evidence without a product-defined parallelism cap, changes only the global `OLLAMA_NUM_PARALLEL` value when necessary, restarts the managed service only on a tentative change, re-evaluates once while stopped, and then ensures, loads, and confirms that model. Automatic mutation is currently Microsoft NT-only; Linux returns administrator-managed systemd guidance and Android user-managed loopback sessions do not call it. A restart unloads other resident Ollama models and can interrupt in-flight local inference. In the upstream ARCANE-OS maintainer checkout only, a maintenance run follows the saved Arcane preference with `npm run model:ensure`. To pull the one 3B base and build both aliases without running Provisioner, an upstream maintainer uses:
+
+```powershell
+# Run only from the canonical upstream ARCANE-OS repository.
+npm run model:ensure -- --target=all --model=3b --smoke
+```
+
+`--target=arcane` is the backward-compatible platform default. Product-specific targets and definitions remain documented by their owning applications. `--target=all` reuses one base pull across both currently configured targets, selects `arcane:3b` as `arcane:latest`, and preserves unrelated settings. `--smoke` adds one bounded local inference probe per selected alias. The equivalent platform-only raw Ollama sequence is `ollama pull granite4.1:3b-q4_K_M` followed by `ollama create arcane:3b -f arcane/models/Arcane-3B.Modelfile`; the npm command additionally verifies lineage and is the supported repository workflow.
+
+The managed service's aliases and model layers are machine-wide, while Arcane model preference and application profile selection remain per-user. `model:ensure` does not install or attest `ArcaneOllama`, does not update an already installed Core or UI after a source pull, and does not create application aliases outside the selected target set. Use the verified Provisioner to establish or repair the machine service and to install current application/runtime bytes. The public [Device and model support](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/apps/docs/guides/device-support.md) page tracks the exact product matrix, platform maturity, and COTS physical-validation backlog; 16B and 30B are validation targets, not managed variants.
+
+```js
+import ollama from '/arcane/modules/Ollama.js'
+
+const reply = await ollama.chatText({
+  model: 'arcane:latest',
+  messages: [{ role: 'user', content: 'Summarize this record.' }],
+})
+```
+
+## Capabilities
+
+Add only the capabilities the application needs to its native app descriptor:
+
+- `ai.inference` — admitted `localAI.status`, `generate`, `chat`, and `embed`
+- `ai.models.read` — raw `version`, `models`, `running`, and `show` diagnostics,
+  restricted to Settings, Terminal, and Shell
+- `ai.models.manage` — policy-bound model-management operations
+- `ai.models.unverified.inference` — inference-only access to
+  already-installed, hardware-admitted unverified models, valid only with
+  `localAIModelPolicy.verified_only:false`
+- `ai.runtime.manage` — model-bound managed Ollama parallel-request changes;
+  currently Core-only, privileged/exclusive, and granted only to the registered
+  owning application
+
+The sole model declaration remains `apps/<id>/arcane-package.json`:
+
+```json
+{
+  "localAIModelPolicy": {
+    "verified_only": true,
+    "models": [
+      {"name": "EXAMPLE:8b", "definition": "Example-8B.Modelfile"}
+    ]
+  }
+}
+```
+
+Verified-only Core may create or repair only an exact declared alias. False
+mode never pulls, creates, repairs, copies, pushes, or deletes an unverified
+model. Browser runtime and generic metadata APIs do not consume or project this
+policy or declared mapping; the generated release-root record still physically
+contains it.
+
+The pinned runtime also exposes `Arcane.ai.chat()`. Applications populate local
+model controls from `Arcane.localAI.status()` and use admitted inference
+methods; raw `Arcane.ai.models()` and Ollama inventory methods are diagnostic
+surfaces for Settings, Terminal, and Shell only.
+
+## Streaming
+
+Pass an `onChunk` callback as the second argument to `chat` or `generate`.
+Mutation streaming remains subject to verified package policy and native
+admission. Direct application pull fails closed; Core's separate managed
+lifecycle owns bounded preflight and the full-digest-verified pull.
+
+```js
+await ollama.chat({
+  model: 'EXAMPLE:8b',
+  messages: [{ role: 'user', content: 'Hello' }],
+}, {
+  onChunk(chunk) {
+    output.append(chunk.message?.content || '')
+  },
+})
+```
+
+Chunk callbacks run as `ollama.chunk` events arrive from Arcane Core. The returned promise resolves with Ollama's final chunk. All operations are bounded by Arcane request and response limits and remain restricted to the loopback ArcaneOllama service.
+
+## API
+
+The pinned `Ollama` class exposes exactly 24 public methods:
+
+- 20 bridge delegates: `version()`, `models()`, `list()`, `running()`,
+  `show()`, `generate()`, `chat()`, `embed()`, `pull()`, `push()`, `create()`,
+  `copy()`, `delete()`, `selection()`, `select()`, `settings()`,
+  `saveSettings()`, `createBrain()`, `serviceSettings()`, and
+  `saveServiceSettings()`.
+- Four helpers: `readiness()`, `generateText()`, `chatText()`, and `unload()`.
+
+`generateText()` returns `String(response?.response || '')`, and `chatText()`
+returns `String(response?.message?.content || '')`. Valid provider envelopes
+document both fields as strings. For an out-of-contract envelope, a truthy
+nonstring value is stringified, while a missing, null, undefined, or other
+falsy nonstring value becomes an empty string.
+
+Exposure of a method does not grant its effect: Core applies capability,
+package-policy, exact-definition, mutation, and resource-admission checks. The
+selection methods are restricted to Arcane Shell. See
+[Arcane AI Data Contracts](arcane-ai-contracts.md#direct-ollama-api) for every
+accepted top-level request field, argument type, streaming callback, settings
+range, raw-management restriction, and the boundary between normalized Arcane
+results and version-dependent Ollama response envelopes. Arcane forces
+non-streaming mode unless a chunk callback is supplied.