docs(build-an-oracle): audit + fix all 60 pages against the runtime (IXO-3105)

build-an-oracle/develop/create-oracle-app.mdx

@@ -73,9 +73,9 @@
     const app = await createOracleApp({
       config,
       features: {
-        composio: false,        // force off
-        firecrawl: true,        // force on, even if env is missing (will fail env validation if so)
-        domainIndexer: 'auto',  // default — runs autoDetect(env)
+        composio: false,           // force off
+        firecrawl: true,           // force on, even if env is missing (will fail env validation if so)
+        'domain-indexer': 'auto',  // default — runs autoDetect(env)
       },
     });
     ```
@@ -87,6 +87,10 @@
     | `'auto'` | Default. Run `autoDetect(env)`. |
 
     Omitted keys are treated as `'auto'`. Recipe: [Enable bundled plugins](/build-an-oracle/develop/enable-bundled-plugins).
+
+    <Warning>
+      Feature keys are the plugin's kebab-case `name` — `'domain-indexer'`, `'user-preferences'`, `'matrix-group-chats'`. A camelCase key like `domainIndexer` type-checks (it falls into the open `string` arm) but is a silent no-op: the plugin keeps its default behaviour. Always quote the exact `name`.
+    </Warning>
   </Step>
 
   <Step title="Mount your own Nest modules" icon="cube">
@@ -168,6 +172,26 @@
     | `degradedServicesBlock` | empty | Degraded-services notice appended to system prompt |
 
     Source: [`graph/main-agent-types.ts`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/graph/main-agent-types.ts) (search `MainAgentHooks`).
+
+    **Change the AI model.** The most common reason to set `hooks` is to swap the model. The runtime resolves the main agent's model via `resolveModel('main')`; override it and spread `params` to keep the provider's fallback models and latency sort:
+
+    ```ts
+    import { createOracleApp, getProviderChatModel } from '@ixo/oracle-runtime';
+
+    const app = await createOracleApp({
+      config,
+      hooks: {
+        // role is 'main' | 'subagent' | 'utility' | (string & {}).
+        resolveModel: (role, params) =>
+          getProviderChatModel(role, {
+            ...params,
+            ...(role === 'main' && { model: 'google/gemini-3.1-flash-lite' }),
+          }),
+      },
+    });
+    ```
+
+    The provider (`LLM_PROVIDER` = `openrouter` default | `nebius`) and per-role default model ids are otherwise fixed in the runtime — there is no env var to change the main model id without this hook. You can also return any LangChain `BaseChatModel` (e.g. `new ChatOpenAI({ model: 'gpt-4o' })`), but doing so drops the OpenRouter fallback/latency wiring.
   </Step>
 
   <Step title="Run a beforeListen hook" icon="play">
@@ -201,16 +225,16 @@
     logger.log(`[boot] loaded: ${status.loaded.join(', ')}`);
     ```
 
-    `onPluginStatusChange` fires when Matrix transitions `pending → loaded` (or `failed`). `onError` catches Matrix init + lifecycle errors. `plugins.status()` returns the same shape `qiforge inspect` prints.
+    `onPluginStatusChange` fires when Matrix transitions `pending → loaded` (or `failed`). `onError` catches Matrix init + lifecycle errors. `plugins.status()` returns a snapshot of loaded, excluded, and soft-dep-gap plugins.
   </Step>
 
   <Step title="Listen" icon="rocket">
     ```ts
-    await app.listen();        // honours config.PORT, env.PORT, then 5678
-    await app.listen(3000);    // explicit port
+    await app.listen();        // uses the PORT env var (defaults to 3000)
+    await app.listen(8080);    // explicit port — overrides PORT
     ```
 
-    Calling `listen()` twice throws. Default port is **5678** — set `PORT` env or pass a number to override.
+    Calling `listen()` twice throws. Default port is **3000** — set the `PORT` env var or pass a number to `listen()` to override.
   </Step>
 </Steps>
 
@@ -289,7 +313,7 @@
 
 <CardGroup cols={2}>
   <Card title="Write a plugin" icon="puzzle-piece" href="/build-an-oracle/develop/write-a-plugin">
     End-to-end Weather plugin walkthrough.
   </Card>
   <Card title="Enable bundled plugins" icon="boxes-stacked" href="/build-an-oracle/develop/enable-bundled-plugins">
     The `features` map in detail.

build-an-oracle/develop/deploy.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Deploy your oracle"
 description: "Build a production bundle, persist the Matrix store, wire health probes. Platform-agnostic with a reference Dockerfile."
 icon: "rocket-launch"
 ---
 
 ## Reference Dockerfile
 
 QiForge has no runtime dependency on itself — anywhere Node 22+ runs, an oracle runs. This Dockerfile is the shortest path from `pnpm dev` to a container you can ship.
 
 ```dockerfile
 FROM node:22-slim AS builder
@@ -24,7 +24,7 @@
 RUN mkdir -p /data
 ENV MATRIX_STORE_PATH=/data/matrix-storage
 ENV SQLITE_DATABASE_PATH=/data/sqlite
-EXPOSE 5678
+EXPOSE 3000
 CMD ["node", "dist/main.js"]
 ```
 
@@ -33,8 +33,8 @@
 ## Prerequisites
 
 - Node.js 22+
 - A reachable Matrix homeserver
 - A persistent volume for the Matrix store and SQLite checkpointer
 - Core env vars (per [`baseEnvSchema`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/config/base-env-schema.ts))
 - Optional: Redis (only if `credits` or `tasks` plugins are loaded)
 
@@ -55,7 +55,7 @@
 
     ```text
     NODE_ENV=production
-    PORT=5678
+    PORT=3000
     ORACLE_NAME=My Oracle
     CORS_ORIGIN=https://your-portal.example
     NETWORK=mainnet
@@ -67,6 +67,10 @@
     RPC_URL=https://rpc.ixo.world
     BLOCKSYNC_GRAPHQL_URL=https://blocksync.ixo.world/graphql
 
+    # Auth tuning (optional — safe defaults)
+    UCAN_AUTH_MAX_TTL_SECONDS=900               # max accepted lifetime of a user auth invocation (default 15 min)
+    UCAN_REAUTH_PROMPT_THROTTLE_SECONDS=21600   # gap between re-authorize prompts (default 6 hours)
+
     # Matrix
     MATRIX_BASE_URL=https://matrix.ixo.world
     MATRIX_ORACLE_ADMIN_USER_ID=@my-oracle-bot:ixo.world
@@ -98,8 +102,8 @@
     Identity and Matrix keys are provisioned via the CLI — see [identity and auth](/build-an-oracle/develop/identity-and-auth) for the full flow.
 
     ```sh
-    qiforge create-entity --no-interactive --network mainnet ...
-    qiforge setup-encryption-key
+    qiforge-cli create-entity --no-interactive --network mainnet ...
+    qiforge-cli setup-encryption-key
     ```
   </Step>
 </Steps>
@@ -159,13 +163,13 @@
 
 <Steps>
   <Step title="Use /health as the liveness probe">
-    The framework exposes `GET /health`, always public, never goes through `AuthHeaderMiddleware`. Returns 200 once Nest is up.
+    The framework exposes `GET /health`, always public, never goes through `AuthHeaderMiddleware`. Returns 200 once Nest is up. The built-in auth-excluded routes are `/` (a JSON landing payload), `/health`, `/docs`, and `/docs/(.*)` — everything else requires auth.
 
     Docker:
 
     ```dockerfile
     HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
-      CMD curl -fsS http://localhost:5678/health || exit 1
+      CMD curl -fsS http://localhost:3000/health || exit 1
     ```
 
     Kubernetes:
@@ -174,7 +178,7 @@
     livenessProbe:
       httpGet:
         path: /health
-        port: 5678
+        port: 3000
     ```
   </Step>
 
@@ -201,9 +205,11 @@
 ```text
 Content-Type, Authorization,
 x-ucan-delegation, x-matrix-access-token, x-matrix-homeserver,
-x-did, x-request-id, x-timezone
+x-did, x-request-id, x-auth-type, x-timezone
 ```
 
+`Authorization` and `x-auth-type` carry the primary invocation-auth path (`Authorization: Bearer <invocation>` + `X-Auth-Type: ucan`); `x-ucan-delegation` carries the downstream-authorization delegation. If you replicate CORS at a reverse proxy, mirror this full list — dropping `x-auth-type` breaks browser clients on the primary auth path.
+
 ## Logging
 
 The runtime uses NestJS's default `Logger`. Pipe stdout/stderr to your aggregator. Override the bootstrap logger with `createOracleApp({ logger })` if you need a custom format — see [createOracleApp reference](/build-an-oracle/reference/createoracleapp).
@@ -212,7 +218,9 @@
 
 ## Graceful shutdown
 
-The runtime registers a `SIGTERM` / `SIGINT` handler that closes the Nest app and disconnects Matrix.
+The runtime registers a `SIGTERM` / `SIGINT` handler that drains in order: (1) **flushes the per-user checkpoint to Matrix**, (2) closes the Nest app, (3) shuts down the Matrix client, (4) runs any plugin teardowns. Each step is isolated — a failure in one is logged and the rest still run.
+
+That first step is why a clean `SIGTERM` matters: an abrupt `SIGKILL` skips the checkpoint upload and loses recent thread state. See [`graceful-shutdown.ts`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/bootstrap/graceful-shutdown.ts).
 
 ```ts
 // To disable (rare — only when your platform's process manager
@@ -224,7 +232,7 @@
 ```
 
 <Warning>
-Disable graceful shutdown only when your platform's process manager guarantees a clean `app.close()` on termination. Otherwise you'll get partial flushes and Matrix sync corruption.
+Disable graceful shutdown only when your platform's process manager guarantees a clean `app.close()` on termination. Otherwise you'll skip the checkpoint flush and risk Matrix sync corruption.
 </Warning>
 
 ## Where to read next

build-an-oracle/develop/enable-bundled-plugins.mdx

@@ -31,7 +31,7 @@
 
 <Steps>
   <Step title="The runtime starts with the bundled list">
     [`BUNDLED_PLUGINS`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/index.ts) is a fixed 15-plugin tuple — memory, portal, firecrawl, domain-indexer, composio, sandbox, skills, editor, agui, slack, tasks, credits, calls, user-preferences, matrix-group-chats.
 
     You do not import or instantiate the plugins you want at defaults — they are already there.
   </Step>
@@ -53,11 +53,11 @@
   </Step>
 
   <Step title="Your own plugins are added next">
     Plugins from the `plugins: []` array are always loaded — they're not gated by `features`. If a name collides with a bundled plugin, your instance wins (the loader dedupes by `name`).
   </Step>
 
   <Step title="Hard-dep cascades resolve transitively">
     If a loaded plugin has `dependsOn: ['removed-plugin']` and that dep ended up excluded, the dependent cascades off too. Soft deps (`softDependsOn`) only log a warning.
   </Step>
 </Steps>
 
@@ -67,7 +67,7 @@
 
 | Plugin | Auto-detects when | Notes |
 | --- | --- | --- |
-| `memory` | `MEMORY_MCP_URL` and `MEMORY_ENGINE_URL` set | Visibility `always` |
+| `memory` | `MEMORY_MCP_URL` set | Visibility `always` |
 | `portal` | always on | Visibility `on-demand` |
 | `firecrawl` | `FIRECRAWL_MCP_URL` set | Visibility `on-demand` |
 | `domain-indexer` | always on | Visibility `always` |
@@ -77,9 +77,9 @@
 | `editor` | always on | Needs `matrixClient` — instantiate explicitly |
 | `agui` | always on | Visibility `on-demand` |
 | `slack` | `SLACK_BOT_OAUTH_TOKEN` set | Visibility `silent` (transport) |
-| `tasks` | `REDIS_URL` set | Stub |
+| `tasks` | `REDIS_URL` set | Visibility `on-demand`; BullMQ-backed async tasks (needs `REDIS_URL`) |
 | `credits` | always on | Visibility `silent`; pass `redis` for production |
-| `calls` | always on | Stub |
+| `calls` | always on | Visibility `silent`; placeholder stub (no tools yet) |
 | `user-preferences` | always on | Visibility `always` |
 | `matrix-group-chats` | always on | Visibility `on-demand`; gating middleware + tools fire only in Matrix group rooms (`memberCount > 2`) |
 
@@ -176,22 +176,14 @@
     // {
     //   loaded: ['memory', 'domain-indexer', 'editor', 'user-preferences', 'weather'],
     //   excluded: [
-    //     { plugin: 'composio', reason: 'auto-detect precondition not met (COMPOSIO_API_KEY)', cause: 'auto_detect_missing' },
-    //     { plugin: 'slack',    reason: 'feature flag set to false',                              cause: 'feature_false' },
+    //     { plugin: 'composio', reason: 'auto-detect precondition not met (COMPOSIO_API_KEY)' },
+    //     { plugin: 'slack',    reason: 'feature flag set to false' },
     //   ],
     //   softDepGaps: [],
     // }
     ```
 
-    `cause` is one of `'feature_false'`, `'auto_detect_missing'`, `'cascaded'`. Surface this in your boot logs so operators see what came up.
-  </Step>
-
-  <Step title="Or use the CLI">
-    ```sh
-    qiforge inspect
-    ```
-
-    Same data, formatted for the terminal. See the [CLI reference](/build-an-oracle/reference/cli).
+    Each `excluded` entry is `{ plugin, reason }` — surface the `reason` in your boot logs so operators see why a plugin came up missing. (`softDepGaps` entries are `{ plugin, missing }`.)
   </Step>
 </Steps>