Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion build-an-oracle/for-ai-agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@

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)).

Check warning on line 9 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L9

Did you really mean 'inlined'?

<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.

Check warning on line 12 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L12

Did you really mean 'scaffolded'?
</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.

Check warning on line 17 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L17

Did you really mean 'checkpointer'?

## main.ts shape

Expand Down Expand Up @@ -180,7 +180,7 @@

`silent` means *not advertised* — the tools are still bound and the agent can call them; they're just kept out of the Tier-1 prompt and `list_capabilities`. It is not a security boundary.

## Bundled plugins (15)
## Bundled plugins (16)

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

Expand All @@ -201,6 +201,7 @@
| `calls` | silent | on (placeholder stub — no tools) | — |
| `user-preferences` | always | on | — |
| `matrix-group-chats` | on-demand | on (opt out via `features`) | — (optional `CHANNEL_MEMORY_*`) |
| `vfs` | always | on (needs UCAN grant) | — (URLs from `NETWORK`) |

Toggle via `features` in `createOracleApp`: `true` forces on, `false` forces off, `'auto'` runs `autoDetect`.

Expand All @@ -210,7 +211,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.

Check warning on line 214 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L214

Did you really mean 'Zod'?

| Var | Required | Description |
| --- | --- | --- |
Expand All @@ -220,15 +221,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). |

Check warning on line 224 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L224

Did you really mean 'Blocksync'?
| `MATRIX_BASE_URL` | yes | Matrix homeserver URL. |

Check warning on line 225 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L225

Did you really mean 'homeserver'?
| `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. |

Check warning on line 232 in build-an-oracle/for-ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (ixoworld) - vale-spellcheck

build-an-oracle/for-ai-agents.mdx#L232

Did you really mean 'checkpointer'?
| `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`. |
Expand Down
2 changes: 1 addition & 1 deletion build-an-oracle/reference/plugin-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ export abstract class OraclePlugin {
- **Type:** `string`
- **Convention:** kebab-case unique identifier.

Used by `features`, `dependsOn`, `softDependsOn`, the `app.plugins.status()` report, the meta-tools. Boot fails on collision with another plugin's name.
Used by `features`, `dependsOn`, `softDependsOn`, the `app.plugins.status()` report, and the meta-tools. Boot fails on collision with another plugin's name.
</Accordion>

<Accordion title="version" icon="code-branch">
Expand Down
Loading