arcane-os 0.1.0-dev.5

package/docs/publishing.md

@@ -0,0 +1,203 @@
+# Development publication
+
+## Current branch stage
+
+Until the first official SDK release, `main` is the single canonical working,
+integration, publication, and documentation branch. Pull requests and pushes
+target `main`, and the complete Node/platform matrix runs there. Do not use a
+separate development branch during this prerelease stage.
+
+After the first official release, ordinary work will move to a long-lived
+`dev` branch while `main` remains the canonical released line. That transition
+must be made as one explicit release change that updates branch protections,
+checks, trusted publication rules, documentation channels, and contributor
+instructions together. The future branch name alone grants no authority.
+
+## Development npm publication
+
+The current development npm version is `0.1.0-dev.5` and `publishConfig.tag` is
+`dev`, so a development publication does not become the default `latest`
+release. Query `npm view arcane-os@dev version` for current registry
+availability; immutable package documentation does not assert mutable registry
+state. 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 global installer, standalone SDK executable,
+NuGet package, Homebrew formula, or OS package is not part of this release
+surface. Vanilla Test's C# and Rust lifecycles do not turn this JavaScript SDK
+into a .NET or Rust package.
+
+`Check` first runs the development suite, then one unprivileged producer packs
+one `.tgz` under pinned Node and npm versions. The producer writes a canonical
+manifest containing the source SHA, clean-checkout flag, package inventory,
+byte length, SHA-256, npm SHA-1 shasum, and SHA-512 integrity. Windows x64,
+Linux x64, and a real macOS arm64 runner use the declared Node `22.23.2` floor
+and each download that same Actions
+artifact by immutable artifact id. They never repack it. Each runner verifies
+the receipt, installs the tarball into a disposable project, exercises
+`npm exec --offline -- arcane`, and runs a test imported from
+`arcane-os/testing` through the installed package's `arcane-test.mjs`. A final
+readiness job fails unless the producer and the complete native matrix pass.
+
+`publish-dev.yml` can run only when manually dispatched from `main` in
+`TheWizardNexus/arcane-os-sdk`. Dispatch requires an authorized npm content
+classification. `unresolved` fails closed. `standard` permits the workflow's
+direct trusted-publishing path only when the package has no conflicting
+dual-use declaration. `dual-use` fails closed until the package includes npm's
+persistent `contentPolicy.class=dual-use` metadata and root `DISCLOSURE`, and
+the workflow is deliberately changed to `npm stage publish` plus human 2FA
+promotion. Direct trusted publishing is not permitted for that class.
+
+For the standard path, the workflow authenticates a successful `Check` push
+run for that exact `main` SHA, downloads its immutable package artifact,
+reverifies the manifest and bytes, and publishes the downloaded `.tgz`. It
+never invokes `npm pack` or `npm publish .` under publication authority. A
+repository-wide concurrency group prevents simultaneous publication jobs;
+GitHub may replace an older pending dispatch, and each surviving dispatch is
+safe to rerun. Preflight rejects byte mismatches, a backward `dev` move, or any
+dist-tag other than `dev`; an already-published matching version is an
+idempotent success. Post-publication
+verification tolerates npm's publish-time scanning for up to 15 minutes. If
+scanning or manual review remains pending, the workflow reports that state and
+a rerun safely resumes verification without republishing immutable bytes.
+
+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
+with `npm install --save-dev --save-exact <path>`. Keep the tarball at the path
+recorded by `package-lock.json`; subsequent `npm ci` verifies its recorded npm
+integrity. Arcane separately requires the installed package to identify exactly
+as `arcane-os@0.1.0-dev.5` and verifies the locked runtime. A local directory
+`file:` install is intentionally unsupported because it may be linked.
+
+Before the first development publish, or while the registry package is absent:
+
+1. Push the intended clean `main` commit and require the complete Check workflow,
+   including the exact-artifact Windows/Linux/macOS matrix, to pass.
+2. Review the uploaded tarball inventory, manifest, checksum, and license
+   notices. Ensure the Arcane OS monorepo package is private so it cannot publish
+   the same npm name accidentally.
+3. Make and record the npm content-policy decision before packing the bootstrap
+   bytes. A `standard` decision permits direct OIDC after bootstrap. A
+   `dual-use` decision requires `contentPolicy.class=dual-use`, a root
+   `DISCLOSURE` in the tarball, and staged publication with human 2FA promotion;
+   npm treats that declaration as persistent across versions.
+4. Because npm requires a package to exist before trusted or staged publishing
+   can be configured, an authorized npm maintainer must download that exact
+   green Actions artifact and publish its `.tgz` once under `dev` through an
+   interactive session with 2FA. That method is permitted for either content
+   class; the dual-use metadata and disclosure must already be inside the exact
+   tarball. Do not rebuild or repack it for this bootstrap. After the package
+   exists, standard releases may publish directly through OIDC, while dual-use
+   releases must use `npm stage publish` and human 2FA promotion.
+5. Allow for npm publish-time scanning, then verify the registry's
+   `dist.integrity` equals the manifest, verify `dev` is
+   the only dist-tag, add a second appropriate owner, and configure npm trusted
+   publishing for the exact `publish-dev.yml` workflow and `npm` environment.
+   For a dual-use classification, grant stage-only trust instead of direct
+   publish authority.
+6. Later standard development versions may use the workflow's direct OIDC
+   authority. A dual-use version must be staged and promoted with human 2FA.
+   Any missing policy decision, package bootstrap, environment, publisher
+   binding, or exact-SHA artifact is a publication blocker rather than a reason
+   to fall back to a token or repack.
+
+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.
+
+## Reusable application release workflow
+
+External app repositories can call `.github/workflows/release-app.yml` by an
+immutable SDK repository revision. The reusable workflow checks out the exact
+caller SHA, installs only the caller's committed dependency lock, requires
+`arcane-os@0.1.0-dev.5`, and checks, packages, bundles, independently verifies,
+and uploads one explicitly selected app. Every third-party action reference is
+pinned to a full commit SHA. The workflow never publishes npm, creates a GitHub
+Release, loops across apps, or changes Arcane admission state.
+
+The build job holds only `contents: read`; its caller-owned checks, package
+scripts, and adapters never receive `id-token: write` or `attestations: write`.
+It uploads the exact bundle together with canonical metadata. A fresh
+caller-code-free job downloads that upload by immutable artifact id, checks out
+the called workflow's exact SDK revision, directly imports its verifier under
+supported Node 24, binds the receipt app id to the requested app, and exposes
+the independently reverified artifact, descriptor, and release identities as
+the reusable workflow outputs. This post-upload boundary prevents a background
+caller process from making the published outputs describe pre-upload bytes.
+
+GitHub artifact attestation is an explicit `attest: true` input and is false by
+default because availability for private repositories depends on the caller's
+GitHub plan. A caller that requests an unsupported attestation fails instead of
+silently producing weaker provenance. GitHub does not let a called workflow
+raise the caller job's permission ceiling. An attesting caller must therefore
+grant these permissions on the reusable-workflow job itself (prefer this
+job-scoped grant over workflow-wide authority):
+
+```yaml
+jobs:
+  release-app:
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    uses: TheWizardNexus/arcane-os-sdk/.github/workflows/release-app.yml@<FULL_40_CHARACTER_COMMIT_SHA>
+    with:
+      app-id: example-app
+      attest: true
+```
+
+Without that caller grant, `attest: true` fails even when the repository plan
+supports artifact attestations. When requested, a fresh privileged job
+depends on the successful post-upload verifier, downloads the same immutable
+artifact id with the pinned `actions/download-artifact` revision, checks out only
+`job.workflow_repository` at `job.workflow_sha`, selects supported Node 24 via
+the pinned `actions/setup-node` revision, and directly imports the
+dependency-free verifier from those trusted SDK source bytes. It rechecks the
+app id, bundle structure, digest, byte length, complete
+canonical metadata, and every post-upload workflow output. No package manager,
+dependency resolution, caller checkout, or caller-owned code runs while that job
+holds OIDC and attestation permissions. Whether attested or not, the upload is a
+build output.
+Arcane must verify an approved provenance or independent signature and an
+Arcane-owned authorization-lock entry before installation; the archive's
+internal checksums alone do not grant authority.
+
+Stable versioning, the npm `latest` tag, and an official GitHub release remain a
+separate explicit release decision. Current `main` development does not
+silently convert a `-dev` package into an official release. A stable release
+must publish the same matrix-tested `.tgz` under `latest`; only after registry
+integrity matches may GitHub attach that `.tgz`, manifest, and checksum. Its Git
+tag and GitHub release title must both be the same bare numeric
+`MAJOR.MINOR.PATCH`. The first stable change must also activate the documented
+`dev`/`main` branch transition and protections; prerelease versions do not get a
+misleading numeric GitHub release.
+
+## Documentation publication
+
+GitHub Pages publishes the static `site/` tree from the newest successful
+`main` push `Check`. A completed Check triggers the Pages job, which resolves
+the newest successful receipt at deployment time so out-of-order completion
+cannot roll the site backward. It checks out that authenticated SHA without
+persistent credentials, validates the static tree, and uploads only `site/`.
+It does not rerun the SDK test suite or execute repository build code.
+
+The deployment job holds only the read, Pages, and OIDC permissions required by
+that single checked artifact. The `github-pages` environment remains the final
+deployment authority. A separate `/dev/` documentation channel is deferred to
+the same explicit post-release branch transition described above.
+
+## Work-amplification record
+
+The prerelease branch cardinality is one checked `main` SHA, one npm release
+candidate, one static site, and one Pages artifact. Four source-check jobs cover
+two supported Node lines on Windows and Linux. One producer creates the npm
+tarball once; three native consumers execute those exact bytes on Windows,
+Linux, and macOS; one readiness gate aggregates them. Development publication
+and Pages authenticate and reuse that successful exact-SHA evidence. Neither
+rebuilds the SDK package or reruns the suite, and Pages does not create a second
+site placement.

package/docs/reference/README.md

@@ -0,0 +1,117 @@
+# Arcane OS SDK developer reference
+
+This reference answers developer questions in this order:
+
+1. **What can the application or tool do?**
+2. **What should I import or call?**
+3. **What does a successful result look like?**
+4. **Where does it run?**
+5. **Only when needed: which transport, host, provider, or kernel boundary implements it?**
+
+The default path is capability-first. Transport and implementation detail is
+kept in the [protocol and host architecture guide](protocols.md), and every
+high-level page links to the relevant deep section instead of repeating it.
+
+## Reference map
+
+| Need | Start here |
+| --- | --- |
+| Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
+| Publish central events, capture bounded time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
+| Use the `arcane` command | [CLI reference](cli.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) |
+| Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
+| Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
+| Use provider-neutral AI | [Arcane AI contracts](core/arcane-ai-contracts.md) |
+| Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
+| Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
+| Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
+
+## Version scope and provenance
+
+This repository contains two related, explicitly versioned surfaces:
+
+| Surface | Source identity | Meaning |
+| --- | --- | --- |
+| SDK and CLI | `arcane-os` `0.1.0-dev.5` | The Node.js toolchain and package exports in this checkout. |
+| Browser runtime | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, bundle `0.8.12`, protocol `arcane/1` | The exact 155-file runtime snapshot shipped under `runtime/`. |
+| Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract derived into `docs/reference/core/`. Canonical inventory and focused-member content was verified unchanged at Arcane OS `main` commit `13f3ce0ae34f77a3495331c8b4c30b1bb105f8ed`; SDK-local provenance, link, and package-boundary annotations are added explicitly. |
+
+The runtime receipt and Core reference remain distinct evidence even though
+they currently share one pinned upstream source identity. A browser module's
+bytes come from the generated runtime receipt. A native build selects one
+explicit Arcane OS checkout and Core. This SDK version accepts that selection
+only after its current native plan checks the exact declared protocol, version,
+features, capabilities, methods, provider contract, and identity-bound
+receipts. That current-build admission does not promise that a future SDK will
+accept this Core or that this SDK will accept a future Core. A matching protocol
+name or higher version alone is not compatibility or authority.
+
+See [Core reference provenance](core/README.md) for the imported inventory and
+the exact distinction between a documentation snapshot and shipped runtime
+bytes.
+
+## MDN-style page contract
+
+Public reference entries follow the established Arcane documentation model:
+
+- one canonical, mechanically readable inventory owns each public name;
+- every public member or module has one guide entry headed by its exact name;
+- each guide leads with an overview and the shortest safe working example;
+- parameters, return values, errors, side effects, cancellation, and events are
+  stated when they apply;
+- availability is summarized near the call, while transport mechanics are
+  folded into or deep-linked from the entry;
+- normalized results are distinguished from provider- or platform-native
+  envelopes;
+- examples do not trigger destructive, privileged, expensive, or external
+  actions merely by being copied.
+
+## Public runtime inventory
+
+The Node package exposes 158 semantic JavaScript records across 11 JavaScript
+entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
+metadata. The [machine-readable package inventory](inventory/package-api.json)
+and [SDK member reference](sdk-api.md) are checked bidirectionally against every
+declared JavaScript export.
+
+The seven update-check records are explicit on-demand checks; they do not poll,
+download, install, or self-update.
+
+The synchronized browser payload exposes:
+
+- 78 JavaScript module artifacts under `runtime/arcane/modules/`, including
+  ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
+  mail transport;
+- 15 shared entity modules under `runtime/arcane/entities/`;
+- 39 reusable HTML-import components under `runtime/arcane/components/`;
+- seven shared CSS artifacts, security policy, images, and the vendored
+  `strong-type` dependency.
+
+The module and component catalogs enumerate every shipped artifact, including
+vendor support files that are not ESM imports. The runtime manifest remains the
+byte-level source of truth; the catalogs explain what those bytes let a
+developer do.
+
+## Authority and feature detection
+
+The presence of a JavaScript function is not permission to use it. Native
+applications should inspect `Arcane.capabilities.list()` where available and
+then call the relevant status method. Android callers with `system.read` obtain
+the nested capability snapshot through `Arcane.platform.status()`.
+
+Do not infer local-AI readiness from `Arcane.runtime.current().managedLocalAI`,
+infer authorization from a transport name, or treat an Ollama model inventory
+as package admission. Each method rechecks native policy at invocation time.
+
+## Source, receipts, and licensing
+
+- [Pinned upstream ARCANE-OS source](https://github.com/TheWizardNexus/ARCANE-OS/tree/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e)
+- [Exact runtime release manifest](../../runtime/ARCANE_RUNTIME_RELEASE.json)
+- [Reviewed runtime source pin](../../tools/runtime-source.json)
+- [AGPL license](../../LICENSE)
+- [Commercial-license notice](../../COMMERCIAL-LICENSE.md)
+- [Third-party and distribution notice](../../NOTICE)

package/docs/reference/arcane-ollama.md

@@ -0,0 +1,288 @@
+# Arcane Ollama
+
+Arcane Ollama lets an admitted application use local Ollama without knowing the
+service port, service account, model directory, host process, or native
+transport. Application code imports one browser module and calls one API:
+
+```javascript
+import ollama from '/arcane/modules/Ollama.js';
+
+const reply = await ollama.chatText({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Summarize this record.'}]
+});
+
+console.log(reply);
+```
+
+The module never connects directly to `localhost:11434`. It delegates to the
+capability-gated `globalThis.Arcane.ollama` bridge. Core binds application
+identity, checks the exact method and package-owned model policy, admits native
+resources, and calls the managed ArcaneOllama service.
+
+This npm package exposes the synchronized browser client only. It does not
+bundle, install, start, or grant an Arcane Core or ArcaneOllama service. Every
+native call therefore requires a separately installed, compatible Arcane host,
+an app-scoped admitted Core session, the required capabilities, and a service
+that is ready under native policy. Import success alone proves none of those
+conditions.
+
+## What developers can do
+
+| Capability | Preferred call | Result style |
+| --- | --- | --- |
+| Check whether the admitted service answers | `ollama.readiness()` | Arcane-normalized frozen readiness snapshot |
+| Generate text | `ollama.generateText(request)` | Arcane helper string |
+| Chat and return only assistant text | `ollama.chatText(request)` | Arcane helper string |
+| Use full generation/chat/tool/provider fields | `ollama.generate()` / `ollama.chat()` | Bounded Ollama provider-native envelope |
+| Create embeddings | `ollama.embed()` | Bounded Ollama provider-native envelope |
+| Read raw version/model/running/show inventory | `version()`, `models()`, `list()`, `running()`, `show()` | Provider-native diagnostic envelope |
+| Unload one model | `ollama.unload(model)` | Translates to generate with `prompt: ""` and `keep_alive: 0` |
+| Read managed selection/runtime/service settings | `selection()`, `settings()`, `serviceSettings()` | Arcane-managed snapshot; some service fields are platform-dependent |
+| Change managed selection/runtime/service settings | `select()`, `saveSettings()`, `saveServiceSettings()` | Arcane-managed result plus operation receipt |
+| Run admitted raw model mutations | `pull()`, `push()`, `create()`, `copy()`, `delete()` | Policy-bound provider-native result; several calls are intentionally denied to ordinary apps |
+| Create an Arcane-managed brain alias | `createBrain()` | Arcane-managed model/default result plus operation receipt |
+
+## Fast start
+
+### 1. Feature-detect the module
+
+```javascript
+import ollama from '/arcane/modules/Ollama.js';
+
+const readiness = await ollama.readiness();
+
+if (!readiness.ready) {
+    console.info('Local AI is unavailable:', readiness.errorCode);
+}
+```
+
+`readiness()` catches a failed `version()` call and returns a frozen object:
+
+```text
+{ ready: boolean, version: string|null, errorCode: string|null }
+```
+
+It is a connectivity convenience, not model admission or inference readiness.
+Use `Arcane.localAI.status()` when the application needs the package-filtered
+runnable model catalog.
+
+### 2. Read admitted models
+
+```javascript
+const access = await globalThis.Arcane.capabilities.list();
+
+if (!access.methods.includes('localAI.status')) {
+    throw new Error('This application is not admitted for local AI.');
+}
+
+const status = await globalThis.Arcane.localAI.status();
+console.table(status.models.ollama);
+```
+
+Populate product UI from this filtered catalog. `ollama.models()` is the raw
+diagnostic inventory for admitted Settings, Shell, or Terminal journeys; it is
+not the application's package-admitted model list.
+
+### 3. Stream a chat response
+
+```javascript
+let text = '';
+
+const final = await ollama.chat({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Explain the evidence.'}]
+}, {
+    onChunk(chunk) {
+        text += chunk.message?.content ?? '';
+    },
+    signal: AbortSignal.timeout(60_000)
+});
+
+console.log(text, final.done);
+```
+
+Arcane correlates chunks to the originating request. The final promise resolves
+with Ollama's final bounded chunk/envelope.
+
+## Complete module API
+
+`/arcane/modules/Ollama.js` exports the `Ollama` class, a frozen `ollama`
+singleton, and that singleton as the default export. It also installs the
+non-writable `globalThis.arcaneOllama` convenience and emits
+`arcane-ollama-ready`. The pinned class defines exactly 24 public methods: the
+20 bridge delegates below and the four normalized helpers that follow.
+
+### Raw bridge methods
+
+| Module method | Delegation | Capability/use | Detailed Core guide |
+| --- | --- | --- | --- |
+| `version()` | `Arcane.ollama.version()` | Raw service version diagnostic. | [version](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaversion) |
+| `models()` | `Arcane.ollama.models()` | Raw installed-model diagnostic. | [models](core/reference/arcane-api/ai-and-ollama.md#arcaneollamamodels) |
+| `list()` | Calls `Arcane.ollama.models()` | Module alias for `models()`; it does not call the bridge's separate `list` alias. | [list](core/reference/arcane-api/ai-and-ollama.md#arcaneollamalist) |
+| `running()` | `Arcane.ollama.running()` | Raw resident-model diagnostic. | [running](core/reference/arcane-api/ai-and-ollama.md#arcaneollamarunning) |
+| `show(model, options)` | `Arcane.ollama.show(...)` | Raw bounded model metadata. | [show](core/reference/arcane-api/ai-and-ollama.md#arcaneollamashow) |
+| `generate(request, options)` | `Arcane.ollama.generate(...)` | Admitted generation; optional chunk callback/signal/timeout. | [generate](core/reference/arcane-api/ai-and-ollama.md#arcaneollamagenerate) |
+| `chat(request, options)` | `Arcane.ollama.chat(...)` | Admitted chat/tools; optional chunk callback/signal/timeout. | [chat](core/reference/arcane-api/ai-and-ollama.md#arcaneollamachat) |
+| `embed(request)` | `Arcane.ollama.embed(...)` | Admitted embeddings. | [embed](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaembed) |
+| `pull(model, options, streamOptions)` | `Arcane.ollama.pull(...)` | Managed/policy-bound pull; denied to ordinary raw app flow. | [pull](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapull) |
+| `push(model, options, streamOptions)` | `Arcane.ollama.push(...)` | Raw push is policy-restricted/denied where documented. | [push](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapush) |
+| `create(request, options)` | `Arcane.ollama.create(...)` | Exact package-owned verified definition only. | [create](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreate) |
+| `copy(source, destination)` | `Arcane.ollama.copy(...)` | Intentionally denied to applications; managed selection owns aliases. | [copy](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacopy) |
+| `delete(model)` | `Arcane.ollama.delete(...)` | Destructive exact package-owned verified model deletion. | [delete](core/reference/arcane-api/ai-and-ollama.md#arcaneollamadelete) |
+| `selection()` | `Arcane.ollama.selection()` | Reads managed model preference/effective state. | [selection](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselection) |
+| `select(preference)` | `Arcane.ollama.select(...)` | Runs managed size-selection/download/alias workflow. | [select](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselect) |
+| `settings()` | `Arcane.ollama.settings()` | Reads managed runtime/provider settings. | [settings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasettings) |
+| `saveSettings(settings)` | `Arcane.ollama.saveSettings(...)` | Saves runtime-owned default/load/context settings. | [saveSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasavesettings) |
+| `createBrain(definition)` | `Arcane.ollama.createBrain(...)` | Creates a managed `arcane-<slug>:latest` alias. | [createBrain](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreatebrain) |
+| `serviceSettings()` | `Arcane.ollama.serviceSettings()` | Reads host-level Ollama service configuration/support. | [serviceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaservicesettings) |
+| `saveServiceSettings(settings)` | `Arcane.ollama.saveServiceSettings(...)` | Applies privileged machine-wide service settings/restart. | [saveServiceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasaveservicesettings) |
+
+### Normalized helper methods
+
+## `ollama.readiness()`
+
+### Overview
+
+Calls `version()` and converts success/failure into a frozen readiness snapshot.
+It never throws for service unavailability.
+
+### Return value
+
+`{ready:true, version, errorCode:null}` on success, or
+`{ready:false, version:null, errorCode}` on failure. A string version and an
+object `{version}` are both accepted.
+
+### Example
+
+```javascript
+const {ready, version, errorCode} = await ollama.readiness();
+console.log(ready ? version : errorCode);
+```
+
+## `ollama.generateText()`
+
+### Overview
+
+Calls `generate()` and coerces the final envelope's `response` field to a
+string with `String(response?.response || '')`. Valid Ollama responses document
+`response` as a string. If an out-of-contract response supplies a truthy
+nonstring, the helper stringifies it; a missing, null, undefined, or other
+falsy nonstring value becomes an empty string.
+
+### Example
+
+```javascript
+const text = await ollama.generateText({
+    model: 'arcane:latest',
+    prompt: 'Write one sentence.'
+});
+```
+
+## `ollama.chatText()`
+
+### Overview
+
+Calls `chat()` and coerces the final envelope's `message.content` field to a
+string with `String(response?.message?.content || '')`. Valid Ollama responses
+document `message.content` as a string. If an out-of-contract response supplies
+a truthy nonstring, the helper stringifies it; a missing, null, undefined, or
+other falsy nonstring value becomes an empty string. Use `chat()` when tool
+calls, metrics, context, or optional provider fields matter.
+
+### Example
+
+```javascript
+const text = await ollama.chatText({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Hello'}]
+});
+```
+
+## `ollama.unload()`
+
+### Overview
+
+Translates `unload(model)` to:
+
+```javascript
+ollama.generate({model, prompt: '', keep_alive: 0});
+```
+
+It returns the raw final generation envelope. It is a convenience request, not
+a proof that no other admitted client reloaded the model concurrently.
+
+### Example
+
+```javascript
+async function unloadAfterTheUserChooses(model) {
+    return ollama.unload(model);
+}
+```
+
+## Availability matrix
+
+| Host | Inference | Raw inventory | Managed model/settings mutation | Notes |
+| --- | --- | --- | --- | --- |
+| Microsoft NT desktop Core | Yes when `ai.inference` is admitted | Settings/Shell/Terminal with `ai.models.read` | Admitted Settings/Shell journeys with management capabilities and privilege where required | Full managed ArcaneOllama service path. |
+| Linux desktop Core | Yes when admitted | Admitted diagnostics | Managed workflows where implemented; administrator-owned service settings can return manual/unsupported guidance | Same application API, different host/service implementation. |
+| Android WebView | Narrow admitted chat/inference projection for configured user-managed loopback | No general desktop raw inventory | No desktop model/service management | `managedLocalAI` remains false; listener reachability is not management authority. |
+| Development HTTP bridge | Only when connected to an admitted Core-backed development host | Host/method dependent | Host/method dependent; never production authority | Development transport, not a standalone-browser upgrade. |
+| Standalone browser | No Arcane Ollama | No | No | `ARCANE_OLLAMA_UNAVAILABLE`. |
+| Cloud/OpenAI | Not through `Arcane.ollama` | No | No | Use an explicitly selected `AI.js` cloud profile; no automatic fallback. |
+
+## Capabilities and policy
+
+- `ai.inference` admits package-filtered local generation, chat, and embeddings.
+- `ai.models.read` admits raw model diagnostics only to authorized system apps.
+- `ai.models.manage` admits policy-bound managed model lifecycle operations.
+- `ai.settings.manage` admits Settings-owned runtime/service configuration.
+- `ai.models.unverified.inference` is an explicit inference-only exception for
+  already installed, hardware-admitted unverified models when the package says
+  `verified_only:false`; it does not admit model mutation.
+
+The method allowlist is necessary but not sufficient. Exact package-owned model
+definitions, reserved aliases, native resources, platform support, installed
+state, and exclusive mutation policy remain authoritative.
+
+## Raw versus normalized behavior
+
+The module intentionally has two levels:
+
+| Boundary | Normalized by Arcane | Intentionally preserved |
+| --- | --- | --- |
+| Missing bridge | Throws coded `ARCANE_OLLAMA_UNAVAILABLE`. | Nothing reaches a provider. |
+| Core call | Promise settlement, capability/policy errors, request limits, diagnostics, stream ids/chunks. | Bounded Ollama success fields and optional provider detail. |
+| `readiness()` | Frozen Boolean/version/error-code snapshot. | Provider error detail is reduced to `errorCode`. |
+| `generateText()` / `chatText()` | Uses `String(value || '')`: documented string values pass through, truthy nonstrings stringify, and falsy nonstrings become empty. | Tool calls, timings, context, and other fields are discarded. |
+| `unload()` | Stable translation to `keep_alive:0`. | Final generation envelope remains provider-native. |
+
+## Streaming, cancellation, and uncertain mutation state
+
+`generate`, `chat`, `pull`, `push`, and `create` accept stream controls through
+the bridge forms documented on their detailed pages. Core cooperatively cancels
+admitted inference methods where documented. For pull, push, create, selection,
+settings, or service mutation, abort/timeout/page teardown can stop renderer
+observation without proving host work rolled back.
+
+After an uncertain model mutation, refresh the relevant raw inventory,
+`selection()`, `settings()`, `serviceSettings()`, or `localAI.status()` before
+retrying. Do not stack a second mutation merely because the renderer timed out.
+
+## Behavioral testing
+
+The SDK behavior suite uses an explicit fake `Arcane.ollama` to prove:
+
+- every wrapper forwards the exact argument objects and provider-native result;
+- stream options and signals are not rewritten;
+- bridge absence throws `ARCANE_OLLAMA_UNAVAILABLE` before provider work;
+- `readiness()` returns frozen success/failure snapshots;
+- `generateText()` and `chatText()` use the pinned `String(value || '')`
+  behavior: truthy nonstrings stringify and falsy nonstrings become empty;
+- `unload()` sends exactly `{model, prompt: "", keep_alive: 0}`.
+
+Those tests prove the shipped renderer module. Live Core dispatch, cancellation,
+ArcaneOllama health, real model pulls, GPU admission, service restart, and
+rollback remain Arcane OS host/integration evidence.
+
+Deep implementation path: [Arcane Ollama protocol](protocols.md#arcane-ollama-protocol-path).