docs(build-an-oracle): audience-split IA + AI-agent surface + Mintlify contextual

.codex/CONTENT_INVENTORY.md

@@ -232,3 +232,28 @@
 - Additional developer guides not in nav: `/guides/dev/**` hidden subset
 - Thin but high-value hidden user page: `/guides/users/ai-companion`
 - Hidden platform pages: `/platforms/Emerging/emerging-dmrv`, `/platforms/Emerging/energy-systems`, `/platforms/Emerging/household-reporting`, `/platforms/Emerging/itmo-credentials`, `/platforms/Emerging/sample-size`, `/platforms/Emerging/distributor-onboarding`
+
+## Build an Oracle (QiForge) — audience-split IA
+
+Audience-split tab introduced in the QiForge docs redesign. Three tracks plus a single-page AI-agent surface, all under `/build-an-oracle/`. Page-type classification per `CONTENT_MODEL_AND_IA.md`.
+
+| Route | Page type | Notes |
+|---|---|---|
+| `/build-an-oracle` | Overview | 3-card landing: Build / Understand / AI agent |
+| `/build-an-oracle/quickstart` | Task guide | 10-minute path |
+| `/build-an-oracle/for-ai-agents` | Reference (dense) | Single-page for AI tools; mirrors AGENTS.md / llms.txt |
+| `/build-an-oracle/build/overview` | Overview | Build-track index |
+| `/build-an-oracle/build/create-oracle-app` | Task guide | Enumerates every `CreateOracleAppOptions` field |
+| `/build-an-oracle/build/enable-bundled-plugins` | Task guide | `features` map |
+| `/build-an-oracle/build/write-a-plugin` | Task guide | Centerpiece — Weather plugin walkthrough |
+| `/build-an-oracle/build/plugin-recipes/<8 recipes>` | Task guide (short how-to) | Atomic recipes — tool, sub-agent, middleware, HTTP, config, share-state, dependencies, visibility |
+| `/build-an-oracle/build/test-your-oracle` | Task guide | vitest + integration patterns |
+| `/build-an-oracle/build/identity-and-auth` | Task guide | UCAN + headers |
+| `/build-an-oracle/build/observability` | Task guide | LangSmith env + events |
+| `/build-an-oracle/build/deploy` | Task guide | Dockerfile, env, volumes, health |
+| `/build-an-oracle/understand/<10 concepts>` | Concept | Mental model, runtime layers, plugins-vs-skills, manifest, visibility, shared-state, contexts, meta-tools, request-lifecycle, architecture |
+| `/build-an-oracle/reference/<10 flat references>` | Reference | `createoracleapp`, `plugin-api`, contexts, manifest-schema, state-schema, env, api-endpoints, cli, client-sdk, glossary |
+| `/build-an-oracle/reference/bundled-plugins/<overview + 14>` | Reference | One page per bundled plugin |
+| `/build-an-oracle/troubleshooting` | Reference (FAQ) | Boot + runtime error catalog |
+
+**Total:** 56 MDX files. Sidebar order in `docs.json` follows the developer journey (Start here → Build → Understand → Reference → Help). All slug migrations from prior IAs (`how-it-works/`, `plugins/`, `building/`, `concepts/`, `guides/`) have redirect entries in `docs.json` and ledger rows in `REDIRECTS_AND_DEPRECATIONS.md`.

.codex/REDIRECTS_AND_DEPRECATIONS.md

@@ -70,5 +70,33 @@ Example:
 | added | n/a | `/reference/networks-and-endpoints` | Establish canonical home for endpoint and network literals | New reference route |
 | added | n/a | `/reference/authentication-matrix` | Establish canonical home for auth headers and surface-level auth ownership | New reference route |
 | added | n/a | `/reference/product-and-sdk-map` | Establish canonical home for product-to-SDK naming and route mapping | New reference route |
+| changed | `/build-an-oracle/how-it-works/architecture` | `/build-an-oracle/understand/architecture` | Audience-split IA: concept pages moved under `understand/` to signal optional reading | Builder tracks live under `build/` |
+| changed | `/build-an-oracle/how-it-works/request-lifecycle` | `/build-an-oracle/understand/request-lifecycle` | Audience-split IA | Same as above |
+| changed | `/build-an-oracle/how-it-works/plugins-vs-skills` | `/build-an-oracle/understand/plugins-vs-skills` | Audience-split IA | Same as above |
+| changed | `/build-an-oracle/how-it-works/contexts` | `/build-an-oracle/understand/contexts` | Audience-split IA | Same as above |
+| changed | `/build-an-oracle/how-it-works/meta-tools-and-loading` | `/build-an-oracle/understand/meta-tools-and-loading` | Audience-split IA | Same as above |
+| changed | `/build-an-oracle/plugins/overview` | `/build-an-oracle/build/overview` | Build-track index — entry point for developers | Replaces the conceptual plugins overview |
+| changed | `/build-an-oracle/plugins/anatomy` | `/build-an-oracle/understand/plugin-anatomy` | Plugin internals are concept material | Renamed to make subject explicit |
+| changed | `/build-an-oracle/plugins/manifest` | `/build-an-oracle/understand/manifest` | Manifest is a concept; schema reference lives at `/reference/manifest-schema` | Concept vs reference split |
+| changed | `/build-an-oracle/plugins/visibility` | `/build-an-oracle/build/plugin-recipes/set-visibility` | Recipe is the developer destination | Concept half lives at `/understand/visibility-tiers` |
+| changed | `/build-an-oracle/plugins/tools` | `/build-an-oracle/build/plugin-recipes/add-a-tool` | Recipe-style task page | Code-first, code↔docs links |
+| changed | `/build-an-oracle/plugins/sub-agents` | `/build-an-oracle/build/plugin-recipes/add-a-sub-agent` | Recipe-style task page | Same |
+| changed | `/build-an-oracle/plugins/middlewares` | `/build-an-oracle/build/plugin-recipes/add-a-middleware` | Recipe-style task page | Same |
+| changed | `/build-an-oracle/plugins/http-endpoints` | `/build-an-oracle/build/plugin-recipes/add-http-endpoints` | Recipe-style task page | Same |
+| changed | `/build-an-oracle/plugins/shared-state` | `/build-an-oracle/build/plugin-recipes/share-state` | Recipe-style task page | Concept half lives at `/understand/shared-state` |
+| changed | `/build-an-oracle/plugins/config-and-env` | `/build-an-oracle/build/plugin-recipes/add-config-and-env` | Recipe-style task page | Same |
+| changed | `/build-an-oracle/plugins/dependencies` | `/build-an-oracle/build/plugin-recipes/declare-dependencies` | Recipe-style task page | Same |
+| changed | `/build-an-oracle/plugins/write-your-first` | `/build-an-oracle/build/write-a-plugin` | Centerpiece end-to-end recipe | Renamed for clarity |
+| changed | `/build-an-oracle/plugins/testing` | `/build-an-oracle/build/test-your-oracle` | Recipe-style task page | Scoped to whole-oracle testing, not plugin-only |
+| changed | `/build-an-oracle/plugins/catalog` | `/build-an-oracle/reference/bundled-plugins/overview` | Catalog accordion split into one reference page per plugin | Each bundled plugin is now individually addressable |
+| changed | `/build-an-oracle/building/create-oracle-app` | `/build-an-oracle/build/create-oracle-app` | Build-track consolidation under `build/` | Same content, shorter path |
+| changed | `/build-an-oracle/building/using-bundled-plugins` | `/build-an-oracle/build/enable-bundled-plugins` | Build-track consolidation; verb-led title | Developer-POV naming |
+| changed | `/build-an-oracle/building/identity-and-auth` | `/build-an-oracle/build/identity-and-auth` | Build-track consolidation | Same |
+| changed | `/build-an-oracle/building/observability` | `/build-an-oracle/build/observability` | Build-track consolidation | Same |
+| changed | `/build-an-oracle/building/deployment` | `/build-an-oracle/build/deploy` | Build-track consolidation; verb-led title | Same |
+| added | n/a | `/build-an-oracle/for-ai-agents` | Dense single-page entry for AI tools scaffolding oracles | Mirrors AGENTS.md / llms.txt convention |
+| added | n/a | `/build-an-oracle/build/overview` | Build-track index | Replaces conceptual plugin overview as developer entry |
+| added | n/a | `/build-an-oracle/understand/what-is-qiforge` | Extracted mental-model summary | Lets the landing stay lean |
+| added | n/a | `/build-an-oracle/reference/bundled-plugins/<plugin>` | One reference page per bundled plugin | 14 leaf pages + overview |
 
 Update this table whenever a decision is made.

AGENTS.md

@@ -157,3 +157,7 @@ At the end of each task, provide:
 Before broader rewrites, complete the items in `.codex/UPGRADE_BACKLOG.md` under:
 - Phase 0 — Governance foundation
 - Phase 1 — Canonical naming rollout
+
+## Related surfaces
+
+- `/build-an-oracle/for-ai-agents` — Dense single-page reference for AI tools (Cursor, Claude Code) scaffolding a QiForge oracle. Mirrors the AGENTS.md / `llms.txt` pattern but for end-user agents *consuming* the docs, not maintainers editing them.

api-reference/ussd-api.mdx

@@ -6,13 +6,13 @@
 
 ## Overview
 
 The IXO USSD gateway exposes a single session endpoint that telecom gateways call for each user interaction, plus debug and health endpoints for operators.
 
 All endpoints accept and return JSON unless otherwise noted. The main session endpoint returns plain text in the USSD response format.
 
 ## Authentication
 
 The `/api/ussd` endpoint does not require authentication by default. It is intended to be called by your telecom gateway server, not directly from a browser. Restrict access at the network or reverse-proxy layer in production.
 
 ## Base URL
 
@@ -26,7 +26,7 @@
 
 ### POST /api/ussd
 
 Processes a USSD interaction. Called by the telecom gateway once per user input during a session.
 
 **Request**
 
@@ -73,10 +73,11 @@
 
 Plain text. The first word indicates whether the session continues or ends.
 
-```
+```text
 CON <menu text>
 ```
-```
+
+```text
 END <closing message>
 ```
 
@@ -104,7 +105,7 @@
 
 Response:
 
-```
+```text
 CON Welcome to IXO USSD
 1. Know More
 2. Account Menu
@@ -126,7 +127,7 @@
 
 Response:
 
-```
+```text
 CON Information Center
 1. About this service
 2. Pricing

articles/cdt-systems.mdx

@@ -5,16 +5,16 @@
 ---
 
 <Tip>
     IXO implements a systems-thinking approach to capture relationships, feedback loops, and interdependencies in real-world systems where actions are intelligently coordinated, financed, verified, and governed.
 </Tip>
 
 ## What are Cognitive Digital Twins?
 
 Cognitive Digital Twins (CDTs) are digital replicas of real-world entities that can learn from data, adapt, and support intelligent decisions. The IXO architecture implements CDTs through three core components:
 
 1. **AI/ML Models for Cognition**: CDTs integrate artificial intelligence to simulate cognition. With runtime learning, a twin can analyze streaming data and update its behavior or predictions autonomously. On IXO, Oracle Twins serve this role – they are AI-powered agent services that evaluate data, perform verifications, and automate intelligent actions within the twin system.
 
 2. **Federated Data Architecture**: CDTs draw from distributed data sources in a federated manner. IXO implements a "data matrix" layer of secure data nodes for each twin, allowing data to be shared across a network of stores rather than one silo. This federated design ensures scalability and resilience.
 
 3. **Decentralized Identity Integration**: Every twin is anchored by a decentralized identity to establish trust and uniqueness. Each Digital Entity is identified by a W3C Decentralized Identifier (DID).
 
@@ -31,34 +31,34 @@
 
 ## Digital Domain Properties
 
 Each physical or conceptual element is represented as a _Digital Entity_ with a digital **Domain**. The domain infrastructure is implemented on blockchain with the following components:
 
 ### Domain Components
 1. **Digital Identifier**  
    Created as a DID for verifiable ownership and uniqueness; can be enhanced with verifiable credentials.  
 
 2. **Domain Controllers**  
    Defined by public keys or blockchain accounts. Only those with permission can update a domain's data.  
 
 3. **Services**  
    Internet-based services tied to the domain, providing necessary functionalities (e.g., data ingestion endpoints).  
 
 4. **Linked Resources**  
    Digital materials (documents, media) referenced via URIs, often with cryptographic proofs for authenticity.  
 
 5. **Accorded Rights**  
    Object capabilities (UDIDs, zCAPs) specify who can perform what specific actions, on what objects, under what conditions, whilst preserving privacy and security in a decentralized manner.  
 
 6. **Linked Claims**  
    Verified data items that update the domain's state (e.g., device usage records, fuel delivery confirmations).  
 
 7. **Linked Entities**  
    Builds a network of related domains—such as funders, projects, or oracles—and formalizes their interconnections.  
 
 8. **Economic Accounts**  
    Domains function as economic actors with blockchain accounts, enabling DeFi-related actions (e.g., staking, payments).  
 
 9. **Non-Fungible Tokens (NFTs)**  
    Each domain is represented as an NFT, facilitating ownership transfers and interactions with other decentralized ecosystems.
 
 ### Data Security and Privacy
@@ -75,14 +75,14 @@
 Trust is established through:
 
 1. **Verifiable Claims**: Digitally signed data or assertions produced by agents or devices
 2. **Oracle Verification**: AI and/or human validators evaluate evidence and verify claims
 3. **Verifiable Credentials**: W3C-standard digital certificates that encapsulate verified claims and outcomes
 4. **End-to-End Trust Pipeline**: From data origin to verification and credential issuance
 
 ## Using Protocols
 
-Manually configuring domains can be intricate, so the IXO platform offers _Protocols_ to streamline the process, and Agentic Oracles to automate steps in the creation of domains. 
+Manually configuring domains can be intricate, so the IXO platform offers _Protocols_ to streamline the process, and Agentic Oracles to automate steps in the creation of domains.
 A protocol is a predefined template of properties, relationships, and data models for a specific type of domain, and an Agentic Oracle is an autonomous AI agent that can be configured to perform specific **P-Functions**—capability classes that are named with *P* for easier grouping. Expand a class below to see examples.
 
 <AccordionGroup>
   <Accordion title="Prediction and perception">
@@ -90,7 +90,7 @@
     - Pattern recognition
     - Providing data analysis and insights
     - Personalizing recommendations
     - Pathfinding
     - Performance monitoring
   </Accordion>
 
@@ -140,7 +140,7 @@
 Example: Climate Mitigation Project Protocol  
 A protocol designed for clean cooking initiatives can include:  
 - Default data fields (fuel types, reporting standards, usage metrics)
 - Relationships (verification oracles, project developers, funders)
 - Services (data analytics, payment frameworks, governance tools)
 
 ## Go here next

articles/ixo-graph.mdx

@@ -17,7 +17,7 @@
 - what has been verified
 - what should happen next
 
 Use the IXO Graph when your system needs more than private data storage. Use it when multiple participants, applications, services, or agents need to coordinate around the same inspectable reality, and when you need to trace changes over time.
 
 <Tip>
   Think of the IXO Graph as the shared operating map for intelligent cooperation. IXO Protocol records verifiable state. Qi uses that state to coordinate humans, agents, applications, and services.
@@ -25,7 +25,7 @@
 
 ## Why it matters
 
 Most real-world work is fragmented across spreadsheets, documents, chats, CRMs, dashboards, blockchains, APIs, and institutional records.
 
 That fragmentation creates coordination failures:
 
@@ -58,7 +58,7 @@
     Transactions, attestations, Flow events, state transitions, and decisions.
   </Accordion>
   <Accordion title="What was determined?" icon="scale-balanced">
     Evaluation Claims, approvals, rejections, disputes, UDIDs, and outcomes.
   </Accordion>
   <Accordion title="What happens next?" icon="route">
     Flow state, allowed actions, assigned roles, agent tools, and settlement rules.
@@ -113,11 +113,11 @@
   </Step>
 
   <Step title="Record change over time">
     Transactions, attestations, Flow events, Evaluation Claims, and UDIDs create an inspectable history of what changed and why.
   </Step>
 
   <Step title="Enable the next action">
     Humans, services, and Agentic Oracles use the graph to decide what is allowed, what needs review, what can be settled, and what should happen next.
   </Step>
 </Steps>
 
@@ -143,7 +143,7 @@
   </Step>
 
   <Step title="An agent evaluates the Claim">
     An Agentic Oracle inspects only the context it is authorized to access, applies the active rubric, and creates an Evaluation Claim.
   </Step>
 
   <Step title="A verifier makes a determination">
@@ -206,7 +206,7 @@
 - resolve which entities are involved in a Flow
 - retrieve Claims, evidence, credentials, and workflow history
 - check whether a participant, service, or agent has authority
 - give Agentic Oracles structured context instead of disconnected prompts
 - separate submitted information from verified state
 - record Evaluation Claims and UDID-backed determinations
 - trigger allowed state transitions, messages, payments, credentials, or next actions
@@ -298,7 +298,7 @@
   </Accordion>
 
   <Accordion title="Record decisions separately">
     Keep recommendations, reviews, approvals, disputes, UDIDs, and state transitions distinct so decisions can be audited and challenged.
   </Accordion>
 
   <Accordion title="Design for replay">
@@ -317,8 +317,8 @@
 - [ ] agent permissions are scoped
 - [ ] workflow states are defined
 - [ ] Evaluation Claims have a structured schema
 - [ ] UDIDs record decision and impact determinations
 - [ ] state transitions are inspectable
 - [ ] disputes and corrections have a path
 - [ ] applications and agents can query only what they are allowed to access
 - [ ] verified outcomes can feed reporting, settlement, research, or learning loops
@@ -355,10 +355,10 @@
   </Card>
 
   <Card title="Agent Evaluations" icon="clipboard-check" href="/guides/dev/agent-evaluations">
     Evaluate agent work using UCAN authority, Claims, rubrics, evidence, Flow state, and UDIDs.
   </Card>
 
   <Card title="What You Can Build" icon="shapes" href="/guides/what-you-can-build">
     Explore practical use cases for verified cooperation, digital MRV, outcome finance, marketplaces, and agent workflows.
   </Card>
-</CardGroup>
+</CardGroup>