docs(build-an-oracle): audience-split IA + AI-agent surface + Mintlify contextual#22
Merged
Merged
Conversation
…y contextual
Replaces the legacy oracle docs with a single "Build an Oracle" tab structured for
three readers:
- Build track (task-oriented, code-first recipes; <Steps> components)
- Deep dive (concepts, optional)
- Reference (signature-first; one page per bundled plugin)
Plus /build-an-oracle/for-ai-agents — a dense single-page surface for AI tools.
56 mdx files under build-an-oracle/: landing (3-card), quickstart, for-ai-agents,
build/{overview, create-oracle-app, write-a-plugin, enable-bundled-plugins,
test-your-oracle, identity-and-auth, observability, deploy} + 8 plugin recipes,
10 deep-dive concept pages, 11 reference pages + reference/bundled-plugins/
(overview + one page per plugin x 14), troubleshooting.
createOracleApp reference enumerates every option (config, features, plugins,
nestModules, authExcludedRoutes, hooks - all 10 MainAgentHooks fields, logger,
test-only flags) sourced from packages/oracle-runtime/src/bootstrap.
Every recipe is code-first with GitHub source links to apps/qiforge-example and
packages/oracle-runtime.
Mintlify:
- contextual.options: copy / view / chatgpt / claude - every page now has the
Copy as markdown / Open in Claude / Open in ChatGPT menu, and /llms.txt
+ .md URL variants are served on deploy.
- mint pinned ^4.2.573, eslint-plugin-mdx 3.7, markdownlint-cli2 0.22.
- pnpm-workspace.yaml added for pnpm 11 allowBuilds (keytar/puppeteer/sharp).
- lint:style glob extended to cover build-an-oracle/.
CLI reference refreshed to match shipped qiforge-cli: new, plugin new,
create-composio-key, setup-encryption-key, update-entity, update-oracle-api-url,
create-user - plus the existing init, create-entity, chat, offline-login, logout.
Documents the project-local .claude/skills/qiforge-oracle/ skill the CLI
scaffolds into every new oracle.
Governance: 28 redirect ledger rows in .codex/REDIRECTS_AND_DEPRECATIONS.md;
Build-an-Oracle section added to .codex/CONTENT_INVENTORY.md; 89 redirects in
docs.json (every legacy slug -> final destination, no chained redirects).
Removed: articles/ixo-oracles.mdx, guides/ixo-oracles-architecture.mdx,
guides/what-you-can-build.mdx, sdk-reference/{agentic-oracles-adk, oracle-adk,
oracles-client-sdk}.mdx - replaced by build-an-oracle/.
Lockfile: package-lock.json removed; pnpm-lock.yaml is now the single source
of truth (repo had both, inconsistent with pnpm-based scripts).
ORA-248
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…k + fix stale catalog links - Mintlify reserves /build/* — every page under build-an-oracle/build/ 404'd on the preview deploy. Renamed build/ -> develop/ throughout (files, docs.json nav, internal links, redirect destinations). - Restored package-lock.json so the docs-quality CI's actions/setup-node npm cache resolves. - Fixed 3 stale /build-an-oracle/plugins/catalog links in develop/enable-bundled-plugins.mdx -> /build-an-oracle/reference/bundled-plugins/overview.
Walks through: - Preconditions: caller must be owner/controller on the oracle's IXO entity. - Plugin config: instantiate MemoryPlugin with selectedTools spread to include MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME (not in DEFAULT_MEMORY_TOOLS). - Portal connect URL per network (dev/test/main). - Chat workflow: drop content, ask the oracle to save it, wait ~5 min for indexing. Plus warning that oracle-knowledge writes are visible to every user (public KB).
15th bundled plugin: per-turn gating middleware for Matrix group rooms + FTS5-searchable per-room compacted memory + pinned facts. - New build-an-oracle/reference/bundled-plugins/matrix-group-chats.mdx - Added to docs.json nav + overview table/cards - Bumped 14 -> 15 across index, quickstart, for-ai-agents, architecture, what-is-qiforge, plugins-vs-skills, plugin-api, enable-bundled-plugins
Add fenced-code language tags, trailing newlines, and whitespace fixes so npm run lint:style passes across guides, articles, and API reference.
ig-shaun
added a commit
that referenced
this pull request
May 26, 2026
Regenerate npm lockfile for markdownlint-cli2@0.22.1, eslint-plugin-mdx@3.7.0, and mint after merging PR #22. Drops guides/what-you-can-build.mdx (removed on main).
3 tasks
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
3 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.
Closes ORA-248 (https://linear.app/ixo-world/issue/ORA-248).
Replaces the legacy oracle docs with a single Build an Oracle tab structured for three readers:
<Steps>components; GitHub source links per step/build-an-oracle/for-ai-agents— dense single-page surface for AI tools scaffolding oraclesWhat changed
build-an-oracle/: 3-card landing, 10-min quickstart, 8 plugin recipes, 10 Deep-dive concept pages, 15 bundled-plugin reference pages, 11 flat reference pages, troubleshooting.createOracleAppreference enumerates every option (config,features,plugins,nestModules,authExcludedRoutes,hooks— all 10MainAgentHooksfields —logger, test-only flags) sourced frompackages/oracle-runtime/src/bootstrap.qiforge-clicommands:new,plugin new,create-composio-key,setup-encryption-key,update-entity,update-oracle-api-url,create-user— plus the existing--init,create-entity,chat,offline-login,logout. Documents the project-local.claude/skills/qiforge-oracle/skill the CLI scaffolds into every new oracle.qiforge-cli new(modern plugin-runtime-shaped scaffold).Mintlify config + tooling
contextual.options: ["copy","view","chatgpt","claude"]— every page gets a "Copy as markdown / Open in Claude / Open in ChatGPT" menu, plus/llms.txtand<page>.mdURL variants on deploy.mintpinned^4.2.573;eslint-plugin-mdx3.1→3.7;markdownlint-cli20.18→0.22.pnpm-workspace.yamladded withallowBuildsfor keytar/puppeteer/sharp (pnpm 11 requirement).lint:styleglob extended to coverbuild-an-oracle/.Governance
.codex/REDIRECTS_AND_DEPRECATIONS.md— 28 ledger rows for slug migrations..codex/CONTENT_INVENTORY.md— Build-an-Oracle section with page-type per route.docs.json— 89 redirects total; every legacy slug (concepts/*,guides/*,how-it-works/*,plugins/*,building/*) routes directly to a final destination (no chained redirects).AGENTS.md— cross-links/build-an-oracle/for-ai-agents.Removed
Legacy oracle pages replaced by content under
build-an-oracle/:articles/ixo-oracles.mdxguides/ixo-oracles-architecture.mdxguides/what-you-can-build.mdxsdk-reference/{agentic-oracles-adk, oracle-adk, oracles-client-sdk}.mdxLockfile note
package-lock.jsonremoved;pnpm-lock.yamlis now the single source of truth — the repo had both before, inconsistent with the pnpm-based scripts.Test plan
pnpm install— clean (with newpnpm-workspace.yaml)pnpm preview— every page renders 200pnpm lint:mdx— cleanpnpm lint:terminology—build-an-oracle/clean (pre-existing JAMBO violations elsewhere are out of scope)pnpm lint:links—build-an-oracle/clean (17 legacy broken links inguides/users/build-a-*andarticles/intro-articlesare pre-existing, not introduced here)/build-an-oracle/how-it-works/architecture→/build-an-oracle/understand/architecture)/llms.txtand per-page.mdURLs served by Mintlify hosting after deploybuild/write-a-pluginreproduces the Weather plugin without opening any Deep-dive pagefor-ai-agents.mdxinto a fresh Claude window with the prompt "scaffold a weather plugin" produces a compilable skeleton with no clarifying questions