ixoworld · mintlify · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jul 10, 2026
diff --git a/build-an-oracle/for-ai-agents.mdx b/build-an-oracle/for-ai-agents.mdx
@@ -1,20 +1,20 @@
 ---
 title: "For AI agents"
-description: "Dense single-page reference. Every signature, every option, every env var, plus a copy-pasteable plugin template. Built so an AI agent can scaffold a QiForge oracle from this page alone."
+description: "Dense single-page QiForge reference — every signature, option, and env var, plus a copy-pasteable plugin template for scaffolding an oracle."
 icon: "robot"
 ---
 
 This page is for AI tools (Cursor, Claude Code, Codex, …) scaffolding a QiForge oracle. Humans should read [Quickstart](/build-an-oracle/quickstart) and [Build a plugin](/build-an-oracle/develop/write-a-plugin) instead.

 If you are an AI agent: read top-to-bottom once. Every signature you need is inlined. Source paths cite the canonical files on the QiForge runtime ([`packages/oracle-runtime`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/packages/oracle-runtime)) and the reference oracle ([`apps/qiforge-example`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/apps/qiforge-example)).

 <Note>
 **If you are working inside a scaffolded oracle project** (one created with `qiforge-cli new`), there is already a Claude Code skill at `.claude/skills/qiforge-oracle/SKILL.md` with project-local guidance: adding plugins, adding tools, wiring env, writing tests with `createTestRuntime`. Load it first — it carries denser, scenario-specific references than this page.
 </Note>

 ## TL;DR — what you produce

 A QiForge oracle is **one `main.ts`** that calls `createOracleApp({ config, plugins, … })` plus **one folder per plugin** under `src/plugins/<name>/`. The runtime handles HTTP, auth, the agent graph, the checkpointer, Matrix, and bundles 16 plugins by default. You ship glue code, not infrastructure.

 ## main.ts shape

@@ -210,7 +210,7 @@

 From [`packages/oracle-runtime/src/config/base-env-schema.ts`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/config/base-env-schema.ts):

 These are the exact names the runtime validates — set them character-for-character or the boot-time Zod check fails.

 | Var | Required | Description |
 | --- | --- | --- |
@@ -220,15 +220,15 @@
 | `ORACLE_ENTITY_DID` | yes | The oracle's on-chain entity DID (`did:ixo:entity:...`). |
 | `SECP_MNEMONIC` | yes | Wallet mnemonic used to sign UCAN invocations to downstream services. |
 | `RPC_URL` | yes | IXO chain RPC endpoint. |
 | `BLOCKSYNC_GRAPHQL_URL` | yes | Blocksync GraphQL endpoint (UCAN validation reads it). |
 | `MATRIX_BASE_URL` | yes | Matrix homeserver URL. |
 | `MATRIX_RECOVERY_PHRASE` | yes | Recovery phrase for the oracle's Matrix encryption. |
 | `MATRIX_ORACLE_ADMIN_USER_ID` | yes | Matrix user ID the bot logs in as. |
 | `MATRIX_ORACLE_ADMIN_PASSWORD` | yes | Matrix bot password. |
 | `MATRIX_ORACLE_ADMIN_ACCESS_TOKEN` | yes | Matrix bot access token. |
 | `MATRIX_ACCOUNT_ROOM_ID` | yes | Oracle's Matrix account room (holds signing key + secrets). |
 | `MATRIX_VALUE_PIN` | yes | PIN for the oracle's Matrix value store / vault. |
 | `SQLITE_DATABASE_PATH` | yes | Path for the per-user SQLite checkpointer DB. |
 | `LLM_PROVIDER` | optional | `openrouter` (default) \| `nebius`. Selects the per-role model map. |
 | `OPEN_ROUTER_API_KEY` | conditional | Required when `LLM_PROVIDER=openrouter` (the default). |
 | `NEBIUS_API_KEY` | conditional | Required when `LLM_PROVIDER=nebius`. |

diff --git a/build-an-oracle/index.mdx b/build-an-oracle/index.mdx
@@ -1,12 +1,12 @@
 ---
 title: "Build an Oracle"
-description: "QiForge is the framework for shipping Agentic Oracles — governed AI evaluators and workflow actors with verifiable identity, encrypted per-user storage, and a plugin runtime you wire up in ~30 lines of TypeScript."
+description: "Ship Agentic Oracles with QiForge — governed AI evaluators with verifiable identity, encrypted per-user storage, and a TypeScript plugin runtime."
 icon: "compass"
 ---
 
 An **Agentic Oracle** is a governed AI evaluator and workflow actor. It performs **P-Functions** over verifiable state—turning claims, evidence, models, and context into accountable intelligence: typed facts, predictions, recommendations, attestations, determinations, risk signals, compliance checks, payment triggers, and permitted workflow actions.

 Unlike a generic AI agent, an oracle is identity-bound, authority-scoped, evidence-grounded, protocol-governed, and audit-producing. Unlike a blockchain or data oracle, it does not merely relay information; it evaluates what information means, which rules apply, which actions are allowed, and what proof must be left behind.

 **QiForge** ships the runtime for that pattern: verifiable identity (IXO entity DID), UCAN delegation, encrypted per-user Matrix storage, and typed plugins ([`@ixo/oracle-runtime`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/packages/oracle-runtime)). Your oracle is a `main.ts` plus the plugins you want. For the full concept model, see [Agentic Oracles](/articles/agentic-oracles).


diff --git a/build-an-oracle/quickstart.mdx b/build-an-oracle/quickstart.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Quickstart"
-description: "Scaffold a working oracle, boot it, and watch the agent call a plugin tool — in about ten minutes."
+description: "Scaffold a working QiForge oracle, boot it, and watch the agent call a plugin tool — a ten-minute TypeScript setup walkthrough for developers."
 icon: "play"
 ---
 
@@ -183,7 +183,7 @@

 | You saw | What it proves |
 | --- | --- |
 | Boot log listing plugins | Loader + topo sort + manifest validation worked. |
 | `excluded plugins:` line with reasons | Env-driven opt-in (`autoDetect`) is wired correctly. |
 | `GET /weather/now` returning JSON | Plugin Nest modules mount + auth exclusions apply. |
 | Agent calling `load_capability` then `get_current_weather` | Dynamic discovery and `loadedPlugins` state work end-to-end. |
@@ -205,7 +205,7 @@
    The 16 plugins shipped with the runtime.
  </Card>
  <Card title="For AI agents" icon="robot" href="/build-an-oracle/for-ai-agents">
    Dense one-pager with every signature inlined.
  </Card>
  <Card title="Understand the model" icon="lightbulb" href="/build-an-oracle/understand/what-is-qiforge">
    Optional. The mental model, runtime layers, plugins vs skills.

diff --git a/build-an-oracle/reference/bundled-plugins/flows.mdx b/build-an-oracle/reference/bundled-plugins/flows.mdx
@@ -1,5 +1,5 @@
 ---
-title: "flows"
+title: "flows plugin: author Qi Flow action templates"
 description: "Opt-in flow-builder plugin: author, inspect, wire, and form-fill multi-step Qi Flow action templates on top of the editor's Qi Flow engine."
 icon: "diagram-project"
 ---
@@ -21,7 +21,7 @@

 `flows` is a flow **builder** capability. The agent designs reusable flow *templates* — steps (action blocks), the data wired between them, conditions, schedules, assignees, and forms — and reads the live state of running flows. The agent never executes, signs, mints, holds a key, or enters a PIN; **the user runs the flow in the portal**, where signing and any state transitions happen.

 It coexists with the [`editor`](/build-an-oracle/reference/bundled-plugins/editor) plugin: flows are written as documents over the `@ixo/editor` Qi Flow engine, using oracle-runtime's native yjs reads/writes. The plugin does not require `editor` to be loaded — it contributes its own tool surface.

 ## When to use it

@@ -35,7 +35,7 @@

 - Editing prose, pages, or BlockNote documents — use [`editor`](/build-an-oracle/reference/bundled-plugins/editor).
 - Actually executing, running, or signing a step — that happens in the portal, by the user. No transaction tooling lives here.
 - IXO entity lookups — use [`domain-indexer`](/build-an-oracle/reference/bundled-plugins/domain-indexer).

 ## Environment variables

@@ -43,7 +43,7 @@

 | Var | Required | Description |
 | --- | --- | --- |
 | `MATRIX_BASE_URL` | yes (base schema) | Matrix homeserver base URL. |
 | `MATRIX_ORACLE_ADMIN_USER_ID` | yes (base schema) | Admin Matrix user ID. |
 | `MATRIX_ORACLE_ADMIN_ACCESS_TOKEN` | yes (base schema) | Admin Matrix access token. |

@@ -85,10 +85,10 @@
 - `connect_steps` — wire an upstream output to a downstream input.
 - `update_step` — per-block / delta edit that never disturbs sibling steps.

 **Settings** — per-step mutators with narrow scope.

 - `set_step_inputs` — set or replace a step's static inputs.
 - `set_step_conditions` — set `props.conditions` directly in the frontend evaluator's operator vocabulary.
 - `set_step_schedule` — set or clear a step's schedule.
 - `set_step_assignment` — set or clear a step's assignee.
 - `set_step_confirmation` — toggle the user-confirmation gate before a step runs.
@@ -104,7 +104,7 @@

 Follow a tight loop: **discover → plan → confirm → build → hand off.** One discovery pass, one short plan, one user confirmation, then build with the authoring tools. The plugin injects an operating guide into the system prompt while it is loaded — see the `FLOWS_OPERATING_GUIDE` exported from the package.

 Conditions are written **directly as `props.conditions`** in the frontend evaluator's operator vocabulary; the compiler's verbatim operators never evaluate at runtime.

 ## Opt in


diff --git a/build-an-oracle/reference/bundled-plugins/vfs.mdx b/build-an-oracle/reference/bundled-plugins/vfs.mdx
@@ -1,5 +1,5 @@
 ---
-title: "vfs"
+title: "vfs plugin: read, edit, and share user files"
 description: "The user's Virtual Filesystem — read, create, edit, search, organise, and share their real files, inside the folder they granted the oracle."
 icon: "folder"
 ---
@@ -18,7 +18,7 @@

 The user's **Virtual Filesystem (VFS)** — their persistent, access-controlled home for real documents, notes, datasets, and artifacts, in folders, searchable and versioned. This is reusable context that lives across sessions — not sandbox scratch files, not chat attachments, not the web.

 The oracle acts **as the user**, inside the exact folder the user delegated to it. The **user owns their filesystem and is the sole grantor**: only their key can sign the delegation — the oracle can never grant itself access. Every file the oracle reads or writes is confined to the granted subtree and audited as `invoker=oracle, actor=user`.

 The filesystem is securely stored with managed encryption; authorized IXO services can read content to power search and previews, so it is **not** end-to-end encrypted — never describe it as zero-knowledge.


diff --git a/build-an-oracle/reference/environment-variables.mdx b/build-an-oracle/reference/environment-variables.mdx
@@ -1,12 +1,12 @@
 ---
 title: "Environment variables"
-description: "Tier-0 (core) vars the runtime always requires, plus per-plugin vars contributed by each bundled plugin's configSchema."
+description: "Tier-0 core env vars the QiForge oracle runtime always requires at boot, plus per-plugin vars contributed by each bundled plugin's configSchema."
 icon: "key"
 ---
 
 ## How env validation works

 The runtime composes one big Zod schema at boot: the **Tier-0 base schema** (always required) plus every loaded plugin's **`configSchema`**. `process.env` is validated against the merged schema. Missing required vars fail boot with `[boot-error] Plugin '<name>' env validation failed for '<field>'`.

 Disabling a plugin (via `features` or `autoDetect`) removes its env requirements automatically.

@@ -43,7 +43,7 @@
 | --- | --- | --- | --- |
 | `SQLITE_DATABASE_PATH` | string | — | Required. Must persist across restarts. |

 ### Blocksync / chain

 | Variable | Type | Default | Notes |
 | --- | --- | --- | --- |
@@ -71,7 +71,7 @@
 | `OPEN_ROUTER_API_KEY` | string | — | Required if `LLM_PROVIDER=openrouter`. |
 | `NEBIUS_API_KEY` | string | — | Required if `LLM_PROVIDER=nebius`. |

 Cross-field check (`validateLlmProviderKey`): the API key for the selected `LLM_PROVIDER` must be present — `OPEN_ROUTER_API_KEY` when `LLM_PROVIDER=openrouter` (the default), `NEBIUS_API_KEY` when `LLM_PROVIDER=nebius`. A missing key fails boot with a named-field error (e.g. `OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`) rather than a generic upstream 401 at request time. The per-role model ids are hardcoded per provider — there is no env var to swap the main model id (use the `resolveModel` hook for that).

 ### Misc

@@ -105,7 +105,7 @@
 | `composio` | `COMPOSIO_BASE_URL` | No | Defaults to `https://composio.ixo.earth`. |
 | `sandbox` | `SANDBOX_MCP_URL` | Yes | Must be a valid URL. |
 | `skills` | `SKILLS_CAPSULES_BASE_URL` | No | URL. Defaults to `https://capsules.skills.ixo.earth`. |
 | `slack` | `SLACK_BOT_OAUTH_TOKEN` | Yes | Triggers autoDetect. |
 | `slack` | `SLACK_APP_TOKEN` | No | |
 | `slack` | `SLACK_USE_SOCKET_MODE` | No | Defaults to `'true'`. |
 | `slack` | `SLACK_MAX_RECONNECT_ATTEMPTS` | No | Coerced to number; default `10`. |
@@ -113,14 +113,14 @@
 | `credits` | `SUBSCRIPTION_URL` | No | URL. |
 | `credits` | `SUBSCRIPTION_ORACLE_MCP_URL` | No | URL. |
 | `credits` | `DISABLE_CREDITS` | No | Enum — exactly `'true'` or `'false'` (any other value fails env validation). `'true'` disables the credit-enforcement middleware; the plugin's `autoDetect` also excludes the whole plugin when `DISABLE_CREDITS=true`. |
 | `tasks` | `REDIS_URL` | Yes (when loaded) | Triggers autoDetect. |
 | `tasks` | `TASKS_MAX_PER_USER` | No | Coerced positive int; default `50`. Max scheduled tasks per user. |
 | `tasks` | `TASKS_RUN_LOCK_TTL_SEC` | No | Coerced positive int; default `600`. Per-run lock TTL (seconds). |
 | `tasks` | `TASKS_MIN_CRON_INTERVAL_SEC` | No | Coerced positive int; default `300`. Minimum allowed cron interval (seconds). |
 | `matrix-group-chats` | `CHANNEL_MEMORY_SYNC_INTERVAL_MS` | No | Coerced int, min `1000`; default `60000`. Debounce window between a write and the Matrix snapshot upload. |
 | `matrix-group-chats` | `GROUP_CHAT_ACTIVE_THREAD_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long a thread stays "active with the bot" after a reply. |
 | `matrix-group-chats` | `GROUP_CHAT_REQUIRE_POWER_LEVEL` | No | Coerced int, min `0`; default `0`. Extra minimum power level the bot must have before posting (`0` = use the room default). |
 | `matrix-group-chats` | `GROUP_CHAT_ROOM_INFO_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long roomInfo (membership, DM flag) stays cached. |
 | `vfs` | `VFS_MAX_READ_LINES` | No | Coerced positive int; default `2000`. Max lines a single `vfs_read` window returns. |
 | `vfs` | `VFS_REQUEST_TIMEOUT_MS` | No | Coerced positive int; default `20000`. Per-request timeout to the VFS worker. |


diff --git a/build-an-oracle/reference/manifest-schema.mdx b/build-an-oracle/reference/manifest-schema.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Manifest schema"
-description: "Field-by-field reference for PluginManifest — every field, type, constraint, and validation rule the runtime enforces at boot."
+description: "Field-by-field reference for the PluginManifest schema — every field, type, constraint, and validation rule the oracle runtime enforces at boot."
 icon: "scroll"
 ---
 

diff --git a/build-an-oracle/reference/runtime-context.mdx b/build-an-oracle/reference/runtime-context.mdx
@@ -1,6 +1,6 @@
 ---
 title: "RuntimeContext"
-description: "The per-request context. Every tool handler, sub-agent handler, middleware hook, and request-time builder receives one. Carries user, session, history, secrets, Matrix, UCAN, LLM, events."
+description: "The per-request RuntimeContext passed to every tool handler, sub-agent, middleware hook, and builder — user, session, history, secrets, UCAN, LLM."
 icon: "user-gear"
 ---
 
@@ -107,7 +107,7 @@
  </Accordion>

  <Accordion title="history" icon="clock">
    - `messages` — readonly array of `BaseMessage` (LangChain). The full thread history loaded by the checkpointer.
    - `recent(n)` — convenience method returning the most recent `n` messages.
    - `userContext` — enrichment object from `state.userContext` (typically populated by the Memory plugin).
    - `state` — `ReadonlyState`, a typed view over the LangGraph annotation state. See [State schema](/build-an-oracle/reference/state-schema).
@@ -139,7 +139,7 @@
  </Accordion>

  <Accordion title="blobStore" icon="box-archive">
    Short-TTL, user-namespaced store for content the LLM must **never relay verbatim** — UCAN invocation CARs, JWTs, signed envelopes. A producing tool stores the value and returns a short opaque ID; a consuming tool looks it up server-side and forwards it on. The model only ever sees the ID.

    - `put({ userDid, name, value, ttlSeconds? })` — store a value, returns a fresh `blob_<16 hex>` ID. TTL defaults to 1h and is clamped to the service max (24h). Pass `userDid` from a **trusted source** (e.g. `rtCtx.user.did`) — never from LLM-supplied tool args.
    - `get({ userDid, blobId })` — retrieve a blob scoped to the requesting user. Returns `null` if it doesn't exist, has expired, or belongs to a different user (cross-user reads always miss).
@@ -231,7 +231,7 @@
  </Accordion>

  <Accordion title="shared" icon="share-nodes">
    Read accessors for state owned by other plugins (registered via `getSharedState()`). Typed via declaration merging on the `SharedAccessors` interface — see [Plugin shared state guide](/build-an-oracle/develop/plugin-recipes/share-state).
  </Accordion>

  <Accordion title="toolCallId" icon="hashtag">

diff --git a/build-an-oracle/understand/architecture.mdx b/build-an-oracle/understand/architecture.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Architecture"
-description: "The three layers — your oracle, the runtime, the bundled plugins — and how they fit together."
+description: "The three QiForge layers — your oracle, the runtime, and the bundled plugins — how they fit together, and the boot sequence the runtime executes."
 icon: "diagram-project"
 ---
 
@@ -41,17 +41,17 @@

 **You own:** the entry point, your oracle's identity, custom plugins, custom Nest modules.

 **You don't own:** the agent loop, the graph state shape, the checkpointer, the auth flow, the meta-tools, the bundled plugins' internals.

 ### Layer 2 — `@ixo/oracle-runtime`

 The framework. Owns the bootstrap (`createOracleApp`), the always-on Nest modules (Sessions, Messages, WebSocket, Secrets, UCAN, Auth, Subscription, Throttler, Health), the per-request agent builder, the four always-on agent middleware (capability gate, tool validation, tool-repetition guard, tool retry — plus page-context and safety-guardrail when their hooks are set), the Matrix-backed SQLite checkpointer, and the plugin API.

 You never edit this layer. Updates come via `pnpm update @ixo/oracle-runtime`.

 ### Layer 3 — Bundled plugins

 16 plugins shipped inside the runtime package, each independently toggleable via `features`. See the [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) for what each one does.

 ## Bootstrap, in one picture

@@ -77,22 +77,22 @@

 | Registry | Holds | Collision rule |
 | --- | --- | --- |
 | ToolRegistry | All plugin tools | Flat namespace — collision is a boot error |
 | SubAgentRegistry | All plugin sub-agents | Flat namespace — collision is a boot error |
 | MiddlewareRegistry | All plugin middleware | Ordered topologically; no names |
 | ManifestRegistry | All plugin manifests | Title collision = soft warn |
 | ConfigSchemaRegistry | All plugin Zod schemas | Merged; later wins with warning |
 | SharedStateRegistry | Plugin shared-state accessors | Flat namespace — collision is a boot error |

 Source: [`packages/oracle-runtime/src/registries/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/registries/).

 ## What's pluggable vs fixed

 | Pluggable | Fixed |
 | --- | --- |
 | Plugin set (bundled toggles + your plugins) | Agent loop (LangChain `createAgent`) |
 | `nestModules` (your Nest modules) | Graph state shape (except one new `loadedPlugins` field) |
 | `authExcludedRoutes` (host + plugin) | Checkpointer (Matrix-backed SQLite) |
 | LLM provider (env-driven) | Auth flow (UCAN delegation) |
 | `hooks.checkpointerForUser` (advanced) | The four always-on middleware |
 | System prompt (via `OracleConfig.prompt`) | The Tier-1 block format |
@@ -130,7 +130,7 @@

 The runtime only calls `resolveModel('main')` itself, so a hook that special-cases `'main'` swaps **only the main agent's model**; sub-agents and utility calls keep the provider defaults unless your own code routes them through the hook too.

 `resolveModel` is one of several `hooks` — the framework's advanced extension surface. Others include `checkpointerForUser` (swap the per-user checkpointer), `safetyModel` (enable the safety-guardrail middleware), `getRoomTitle` (enable the page-context middleware), and prompt-block overrides like `operationalMode`. See the [`createOracleApp` reference](/build-an-oracle/reference/createoracleapp) for the full list.

 ## Read next