docs(build-an-oracle): audit + fix all 60 pages against the runtime (IXO-3105)#25
Merged
Merged
Conversation
Full audit of the Build-an-Oracle guide against the live runtime
(packages/oracle-runtime), the reference oracle (apps/qiforge-example),
and the CLI (ixo-oracles-cli). 78 findings fixed across 49 of 60 pages.
Highlights:
- Document changing the AI model via createOracleApp({ hooks: { resolveModel } });
enumerate all createOracleApp options, the OracleApp surface, and all 10
MainAgentHooks fields with examples.
- Correct the auth model everywhere: invocation-primary (Authorization: Bearer
+ X-Auth-Type: ucan), x-ucan-delegation as downstream-authz/fallback; add
x-auth-type to CORS; document /delegation endpoints and real WS events.
- Remove the fabricated onError middleware hook; fix the always-on middleware
list; correct dangerous middleware state-mutation guidance.
- Rewrite tasks.mdx for the shipped v2.0.0 plugin; fix editor/composio/sandbox/
skills plugin pages; plugin count is 15.
- Fix env/state/manifest reference drift (missing UCAN vars, phantom state
channel, tags = hard boot error).
- Correct the client SDK API and the CLI: binary is qiforge-cli, scaffold is
'new', chat is the --chat flag, set-URL is update-oracle-api-url; remove
fabricated commands; normalize default PORT to 3000.
- Add the create-entity localhost:4000 vs PORT=3000 reconciliation note.
Refs IXO-3105.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
ig-shaun
approved these changes
Jun 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
For everyone (plain-language summary)
The Build-an-Oracle guide is what developers follow to build an AI agent ("Oracle") on QiForge. Over time it had drifted out of sync with the actual software — some pages described things that had changed, named settings that no longer exist, or showed example code that wouldn't run, and the most-asked question ("how do I change the AI model?") wasn't answered anywhere. This PR reviews every page (all 60) against the real software, the working example project, and the CLI, then corrects what was wrong, fills in what was missing, and makes sure every example actually runs.
By the numbers: 78 issues fixed across 49 of 60 pages.
What changed
createOracleApp({ hooks: { resolveModel } })with a copy-paste example; enumerated allcreateOracleAppoptions, the fullOracleAppreturn surface, and all 10MainAgentHooksfields.Authorization: Bearer <invocation>+X-Auth-Type: ucan), withx-ucan-delegationas downstream-authorization + migration fallback; exact 401 strings;x-auth-typeadded to CORS; documented/delegationendpoints + real WebSocket events.onErrorhook (real hooks:beforeAgent/beforeModel/wrapModelCall/wrapToolCall/afterModel/afterAgent); corrected the always-on stack; fixed dangerous "return a partial state object" guidance.tasks.mdxfor the shipped v2.0.0 plugin; fixed editor/composio/sandbox/skills pages; plugin count is 15.tagsrule (hard boot error).@ixo/oracles-client-sdkAPI; fixed the CLI to the realqiforge-clibinary (scaffoldnew, chat--chat, set-URLupdate-oracle-api-url); removed fabricated commands; normalized defaultPORTto 3000.create-entityregisters the oracle URL ashttp://localhost:4000by default while the runtime defaultPORTis3000— setPORT=4000to match or change it withqiforge-cli update-oracle-api-url.How it was verified
Every code example checked against runtime source. Cross-page sweeps clean: no stale port
5678, no@ixo/commonmis-import, no "14 plugins",onErroronly as the realOracleApp.onErrormethod,qiforge-clionly as binary/package name. Frontmatter intact; nav (docs.json) has no orphans/broken links.Tracking
Linear: IXO-3105. Per-finding detail (severity, runtime
path:line, suggested fix) lives in the boilerplate repo atdocs/docs-audit/.A few source-side follow-ups (runtime code, not docs) are listed in IXO-3105 — e.g. the example app's stale port comment, two inaccurate JSDoc blocks, and a boot warning that still prints the legacy CLI command.