docs: sync deps and restore Agentic Oracles canonical article

.codex/CONTENT_INVENTORY.md

@@ -60,7 +60,7 @@
 /articles/ixo-blocksync
 /articles/ixo-integrations
 /articles/ixo-matrix
-/articles/ixo-oracles
+/articles/agentic-oracles
 /articles/ixo-protocol
 /articles/ixo-signx
 /articles/orchestration
@@ -191,7 +191,7 @@
 /articles/ixo-blockchain
 /articles/ixo-matrix
 /articles/ixo-blocksync
-/articles/ixo-oracles
+/articles/agentic-oracles
 /articles/pods
 /articles/projects
 /platforms/Emerging/intro-emerging

.codex/REDIRECTS_AND_DEPRECATIONS.md

@@ -98,5 +98,6 @@ Example:
 | 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 |
+| changed | `/articles/ixo-oracles` | `/articles/agentic-oracles` | Canonical concept article for Agentic Oracles | Previously redirected to `/build-an-oracle`; implementation docs remain on Build track |
 
 Update this table whenever a decision is made.

articles/agentic-oracles.mdx

@@ -0,0 +1,159 @@
+---
+title: "Agentic Oracles"
+description: "Governed AI evaluators and workflow actors that are identity-bound, evidence-grounded, protocol-governed, and audit-producing economic actors."
+icon: "sparkles"
+---
+
+<Tip>
+  An **Agentic Oracle** is a governed AI evaluator and workflow actor. It performs **P-Functions** over verifiable state—turning claims, evidence, models, and context into accountable intelligence: typed facts, predictions, recommendations, attestations, determinations, risk signals, compliance checks, payment triggers, and permitted workflow actions. It is an identity-bound, evidence-grounded, protocol-governed, and audit-producing economic actor.
+</Tip>
+
+Most AI agents are good at *doing*. Agentic Oracles are accountable for *deciding*. They are the first class of AI service designed to participate in workflows where claims must be verified, authority must be respected, decisions must be replayable, and outcomes must be inspectable by more than one party.
+
+This is the capability that IXO and Qi were built for.
+
+<Info>
+  This is a **concept and architecture article**. For implementation, see [Build an Oracle](/build-an-oracle). For the evaluation pattern, see [Claim evaluation protocol](/articles/claim-evaluation-protocol). For the cooperation layer, see [Qi: cooperation on verified workflows](/articles/qi-intelligent-cooperating-system).
+</Info>
+
+## What makes it an Agentic Oracle
+
+Five properties distinguish an Agentic Oracle from any other generic AI agents. All five must hold.
+
+| Property | What it means |
+| --- | --- |
+| **Identity-bound** | Acts through a known service identity, with a DID, and verifiable credentials. |
+| **Authority-scoped** | May only inspect evidence, call tools, issue outputs, or trigger actions that a protocol, domain, workflow, policy, or delegation permits. The oracle is not allowed to act outside its authority. |
+| **Evidence-grounded** | Operates on claims, credentials, observations, and data that can be referenced, replayed, challenged, or reviewed. |
+| **Protocol-governed** | Outputs are constrained by explicit rubrics, thresholds, schemas, and workflow states. The oracle is not allowed to make arbitrary decisions. |
+| **Audit-producing** | Emits structured outputs that can be inspected, signed, anchored, challenged, or routed to human review. |
+
+The value is not autonomy. The value is **accountable intelligence**: AI reasoning connected to verifiable evidence, governed authority, repeatable evaluation, and permitted action.
+
+## Why this is a new category
+
+The category exists because three different families of system each solve part of the problem and none solve all of it.
+
+| System | What it gives you | What it cannot do |
+| --- | --- | --- |
+| **Generic AI agent** | Productivity: drafts, searches, plans, calls tools | Cannot bind decisions to verifiable evidence or governed authority |
+| **Blockchain oracle** | Connectivity: relays external data into on-chain logic | Does not evaluate what the data *means* under a rule and the given context |
+| **Data oracle** | Availability: supplies validated data to downstream systems | Does not decide which action is permitted or by whom |
+| **Agentic Oracle** | **Accountable cooperation**: evaluates claims and context under authority, produces inspectable determinations, and triggers governed action | — |
+
+An Agentic Oracle is the role that emerges when AI reasoning, verifiable state, and delegated authority meet inside one workflow.
+
+## Why IXO is uniquely positioned
+
+Other stacks can host an AI agent. They cannot easily make that agent *accountable*. Agentic Oracles depend on primitives that the IXO and Qi stack already provides as first-class infrastructure:
+
+<CardGroup cols={2}>
+  <Card title="Verifiable identity" icon="id-badge">
+    Every oracle has an **IXO entity DID** anchored on-chain. Its actions are attributable, its keys are revocable, and its credentials are inspectable.
+  </Card>
+  <Card title="Cryptographic authority" icon="key">
+    **UCAN delegation** scopes what an oracle may do for whom. Authority is granted, attenuated, and revocable—no ambient permissions.
+  </Card>
+  <Card title="Inspectable evidence" icon="file-shield">
+    **Claims, verifiable credentials, and the IXO Graph** give the oracle evidence it can reference, replay, and cite by identifier.
+  </Card>
+  <Card title="Encrypted cooperation" icon="lock">
+    **IXO Matrix** rooms host the conversation around each workflow—per-user, end-to-end encrypted, and preserved alongside actions.
+  </Card>
+  <Card title="Governed state transitions" icon="diagram-project">
+    **IXO Protocol** records claims, evaluations, and UDIDs as state changes the network can verify and downstream systems can trust.
+  </Card>
+  <Card title="Cooperation surface" icon="brain-circuit">
+    **Qi** orchestrates humans, agents, applications, and services around that state through declared interfaces and review paths.
+  </Card>
+</CardGroup>
+
+Take any of these away and you are back to a generic AI agent that you have to trust on its word. Together they make Agentic Oracles practical.
+
+## P-Functions: what an Agentic Oracle does
+
+**P-Functions** are the capability classes an Agentic Oracle can perform. A single oracle may implement one narrow function—proofing a claim—or combine several inside a governed workflow: detect risk, predict impact, prescribe an intervention, and route the case for human review.
+
+Treat this as a **capability map**, not a list of unrestricted powers. Every function is scoped by the oracle's authority and rubric.
+
+<AccordionGroup>
+  <Accordion title="Proving and protocol conformance" icon="shield-check">
+    - **Proofing and verification** — Validate claims, evidence, credentials, or state assertions against defined rules. *Output:* verification result, evaluation claim, signed determination, reason-coded route.
+    - **Protocol adherence** — Monitor conformance to protocol rules, schemas, authorities, and state transitions. *Output:* compliance result, invalid-state flag, allowed-transition check.
+  </Accordion>
+
+  <Accordion title="Prediction and perception" icon="chart-line">
+    - **Prediction** — Estimate future states, risks, trends, demand, or outcomes from evidence and models. *Output:* forecast, confidence score, early warning.
+    - **Pattern recognition** — Detect signals, clusters, correlations, or anomalies in complex datasets. *Output:* pattern report, anomaly flag, classification.
+    - **Performance monitoring** — Track indicators, service levels, milestones, or system health. *Output:* performance score, threshold breach, alert.
+    - **Providing data analysis and insights** — Analyse claims, evidence, and context for decision-useful intelligence. *Output:* insight report, analytic summary.
+    - **Personalisation** — Adapt recommendations or workflows to a person, organisation, place, or asset. *Output:* contextual recommendation, tailored workflow.
+    - **Pathfinding** — Identify viable routes through workflows, evidence paths, or operational constraints. *Output:* route recommendation, dependency map.
+  </Accordion>
+
+  <Accordion title="Prescription and planning" icon="route">
+    - **Prescription** — Recommend interventions or next-best actions to achieve a target outcome. *Output:* recommended action, intervention plan.
+    - **Planning** — Create ordered action sequences, resource plans, or implementation strategies. *Output:* plan, task graph, milestone sequence.
+    - **Process optimisation** — Improve workflows, supply chains, verification pipelines, or resource usage. *Output:* optimisation recommendation, bottleneck diagnosis.
+  </Accordion>
+
+  <Accordion title="Protection and risk" icon="shield-halved">
+    - **Prevention of risks** — Anticipate and mitigate operational, financial, health, environmental, governance, or compliance risks. *Output:* risk forecast, mitigation plan.
+    - **Privacy protection** — Minimise exposure through redaction, selective disclosure, access control, and privacy-preserving computation. *Output:* redacted evidence package, disclosure decision.
+    - **Problem detection and resolution** — Identify anomalies, failures, blockers, or disputes and propose resolution. *Output:* problem flag, root-cause hypothesis, corrective action.
+  </Accordion>
+
+  <Accordion title="Participation and governance" icon="users">
+    - **Participation of people and organisations** — Maintain human oversight, participatory review, consent, and accountable escalation. *Output:* review request, participation prompt.
+    - **Participating in governance** — Support governance through proposal analysis, quorum checks, and decision routing. *Output:* governance brief, proposal analysis.
+  </Accordion>
+
+  <Accordion title="Payments and portfolio" icon="coins">
+    - **Payment automation** — Trigger or recommend payments when verified conditions are met. *Output:* eligibility signal, settlement instruction, hold/release recommendation.
+    - **Portfolio management** — Assess and optimise portfolios of assets, projects, claims, risks, or financing positions. *Output:* portfolio score, allocation recommendation.
+  </Accordion>
+
+  <Accordion title="Policy and compliance" icon="scale-balanced">
+    - **Policy enforcement** — Check whether actions, claims, data flows, or decisions comply with applicable policies. *Output:* policy check, compliance status, violation flag.
+    - **Providing compliance and reporting** — Produce structured reports for funders, regulators, verifiers, or operators. *Output:* compliance report, audit packet.
+  </Accordion>
+</AccordionGroup>
+
+## Where this matters
+
+Agentic Oracles unlock workflows that previously required slow, expensive, and contestable human-only review—but where automation alone has never been trusted.
+
+- **Impact verification and digital MRV** — Evaluate field evidence against a rubric, attribute outcomes to interventions, and issue evaluation claims that funders and regulators can inspect.
+- **Outcome-based financing** — Trigger or recommend payments when verified conditions are met, with the evidence and authority trail attached.
+- **Claims evaluation and credential issuance** — Apply governed rubrics to evidence packages and prepare credentials within delegated authority.
+- **Governed data sharing** — Decide what may be disclosed to whom under consent and policy, with the decision itself recorded as an artifact.
+- **Operational and governance support** — Detect risk, summarise proposals, route escalations, and prepare reports without taking final authority.
+
+In each case the oracle moves work from *opaque expert judgment* or *unverifiable automation* to **accountable, reproducible intelligence**.
+
+## Boundaries
+
+<Note>
+  **Practical rule:** An Agentic Oracle increases the speed, consistency, and scale of a workflow. It does not remove the need for evidence, authority, protocol conformance, and human review where required. The canonical source of truth is the combination of claim, evidence, authority, rubric, workflow state, signed determination, and review path—not the oracle's response.
+</Note>
+
+An Agentic Oracle **may** inspect permitted evidence, normalise it into typed facts, apply governed rubrics, generate recommendations, produce reason-coded determinations, trigger explicitly delegated actions, route ambiguous cases to human review, and prepare payment, credential, or governance outputs where allowed.
+
+It **may not** silently change its rubric, approve high-value claims from an LLM response alone, treat private reasoning as canonical state, exceed delegated authority, execute irreversible actions when evidence is ambiguous, or become the sole final authority for material settlement, credentialing, or governance.
+
+## Go here next
+
+<CardGroup cols={2}>
+  <Card title="Build an Oracle" icon="compass" href="/build-an-oracle">
+    Ship an Agentic Oracle with QiForge: identity, UCAN auth, Matrix storage, and the plugin runtime.
+  </Card>
+  <Card title="Claim evaluation protocol" icon="clipboard-check" href="/articles/claim-evaluation-protocol">
+    The reference pattern for claims, evidence, rubrics, UDIDs, and bounded agent assistance.
+  </Card>
+  <Card title="Qi cooperation layer" icon="brain-circuit" href="/articles/qi-intelligent-cooperating-system">
+    How humans, agents, and services coordinate over IXO verifiable state.
+  </Card>
+  <Card title="Digital Twin Domains" icon="brain" href="/articles/cdt-systems">
+    P-Function groupings in protocol and domain design.
+  </Card>
+</CardGroup>

articles/claim-evaluation-protocol.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Claim evaluation protocol"
 description: "How Claims, evidence, rubrics, Agentic Oracles, and UDID records fit together in accountable IXO evaluation workflows."
 icon: "clipboard-check"
 ---
 
@@ -36,9 +36,9 @@
 
 ## Why this matters
 
 Claims often represent real-world work, identity, compliance, impact, delivery, or eligibility. Without a governed evaluation model, verification can drift into screenshots, emails, spreadsheets, ad hoc chat messages, and opaque expert judgment.
 
 Agentic Oracles can help with evidence review and decision support, but automation introduces its own risks:
 
 - the agent may act outside delegated authority
 - evidence may be incomplete, stale, or forged
@@ -55,7 +55,7 @@
 
 ## System model
 
 The evaluation pattern connects IXO Protocol, IXO Graph, Qi Intelligent Cooperating System, and Agentic Oracles.
 
 <Steps>
   <Step title="A Claim enters a governed context">
@@ -71,7 +71,7 @@
   </Step>
 
   <Step title="The rubric evaluates the facts">
     A governed rubric applies ordered checks, thresholds, disqualifiers, escalation rules, and reason codes to the typed facts. The rubric should be explicit, ordered, and reason-coded.
   </Step>
 
   <Step title="A UDID records the determination">
@@ -99,7 +99,7 @@
   </Accordion>
 
   <Accordion title="Agentic Oracle" icon="robot">
     An autonomous or semi-autonomous evaluator that operates with identity, scoped authority, permitted tools, and auditable output. An Agentic Oracle should not become the sole final authority for high-value or irreversible decisions. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
   </Accordion>
 
   <Accordion title="Evaluation kit" icon="toolbox">
@@ -107,7 +107,7 @@
   </Accordion>
 
   <Accordion title="Rubric" icon="table">
     The governed rulebook used to evaluate typed facts. A practical rubric defines required evidence, disqualifiers, thresholds, escalation rules, reason codes, and allowed outcomes. The rubric should be explicit, ordered, and reason-coded.
   </Accordion>
 
   <Accordion title="Fact ledger" icon="list-check">
@@ -141,7 +141,7 @@
 
   <Accordion title="Agentic Oracles" icon="robot">
     - **Owns:** Evidence review, fact production, rubric application, recommendations, and Evaluation Claims.
     - **Does not own:** Unbounded authority to approve, pay, issue credentials, or update high-value state. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
   </Accordion>
 
   <Accordion title="IXO Matrix" icon="comments">
@@ -163,7 +163,7 @@
 
 <CardGroup cols={2}>
   <Card title="Shared runtime artifacts" icon="gears">
     Claim loader, context resolver, evidence resolver, fact-ledger validator, rubric interpreter, trace store, UDID compiler, signing adapter, and human-review notifier.
   </Card>
 
   <Card title="Domain-specific kit artifacts" icon="boxes-stacked">
@@ -185,7 +185,7 @@
 
 The fact ledger is the bridge between messy evidence and repeatable decisions.
 
 Raw evidence can include PDFs, images, sensor logs, API responses, credentials, signatures, spreadsheets, Matrix events, and external attestations. A rubric should not need to know how each source was parsed. It should receive stable facts with provenance. The fact ledger should be deterministic, reproducible, and cryptographically signed.
 
 ```json
 {
@@ -290,7 +290,7 @@
 
 - Claim ID and Claim Collection
 - Claim subject and type
 - evaluator DID or service identity (the Agentic Oracle DID)
 - rubric ID and version (the rubric JSON file)
 - reason code (the reason code for the outcome)
 - evidence references or redacted evidence links (the evidence that was inspected)
@@ -304,11 +304,11 @@
 
 ## Safety rules
 
 Use these rules before allowing an Agentic Oracle to affect value, credentials, or state.
 
 <AccordionGroup>
   <Accordion title="Do not let an LLM directly approve a Claim" icon="triangle-exclamation">
     The model may extract, classify, summarize, or recommend. Approval should pass through governed rubric logic and the workflow authority model. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
   </Accordion>
 
   <Accordion title="Do not treat a CID as authenticity proof" icon="link">
@@ -316,7 +316,7 @@
   </Accordion>
 
   <Accordion title="Do not let the evaluator change its own rubric" icon="lock">
     Rubric changes require proposal, review, versioning, and governance. Runtime optimization should not silently change thresholds, disqualifiers, or reason-code mappings. The rubric should be deterministic, reproducible, and reason-coded.
   </Accordion>
 
   <Accordion title="Do not commit high-value actions on ambiguous evidence" icon="hand">
@@ -340,7 +340,7 @@
 - one rubric (the rubric JSON file)
 - one evidence schema (the evidence schema JSON file)
 - one fact ledger schema (the fact ledger schema JSON file)
 - one Agentic Oracle or evaluator identity (the Agentic Oracle DID)
 - one human review path (the human review JSON file)
 - one dispute or correction path (the dispute or correction JSON file)
 - one test suite with approval, rejection, ambiguity, and adversarial cases (the test suite JSON file)
@@ -366,7 +366,7 @@
     Understand the shared graph of entities, Claims, evidence, authority, workflows, decisions, and outcomes.
   </Card>
 
-  <Card title="Agentic Oracles" icon="robot" href="/articles/ixo-oracles">
+  <Card title="Agentic Oracles" icon="robot" href="/articles/agentic-oracles">
     Learn how oracle and agent services fit into the IXO stack.
   </Card>
 

articles/intro-articles.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Articles"
 icon: "book-open"
 description: "Two reading paths: outcome-first workflows, then deeper stack articles for IXO Graph, protocol, Matrix, Blocksync, oracles, and Qi."
 ---
 
 <Tip>
@@ -23,7 +23,7 @@
     First-touch domain and digital twin setup.
   </Card>
   <Card title="Developer overview" icon="code" href="/guides/dev/overview">
     SDKs, APIs, and implementation entry points.
   </Card>
 </CardGroup>
 
@@ -34,7 +34,7 @@
     Vocabulary, lifecycle, layers, and how state and cooperation relate.
   </Card>
   <Card title="Technical deep-dives" icon="diagram-project" href="/articles/ixo-graph">
     Start with the IXO Graph, then protocol, Matrix, Blocksync, oracles, and Qi articles from the groups below.
   </Card>
 </CardGroup>
 
@@ -45,8 +45,8 @@
     - **IXO Graph**: shared map of entities, claims, evidence, and outcomes — [`/articles/ixo-graph`](/articles/ixo-graph)
     - **IXO Protocol**: identity, claims, coordination primitives — [`/protocols/ixo-protocol`](/protocols/ixo-protocol)
     - **IXO Matrix**: encrypted cooperation rooms and communication — [`/articles/ixo-matrix`](/articles/ixo-matrix)
     - **IXO Blocksync**: indexed blockchain data access — [`/articles/ixo-blocksync`](/articles/ixo-blocksync)
-    - **Agentic Oracles**: AI-assisted verification and automation — [`/articles/ixo-oracles`](/articles/ixo-oracles)
+    - **Agentic Oracles**: AI-assisted verification and automation — [`/articles/agentic-oracles`](/articles/agentic-oracles)
   </Accordion>
   <Accordion title="Qi components" icon="window">
     - [Qi: cooperation on verified workflows](/articles/qi-intelligent-cooperating-system) (**Qi Intelligent Cooperating System**)

articles/intro-platforms.mdx

@@ -150,7 +150,7 @@
   </Accordion>
 
   <Accordion title="Transaction Layer">
     * Blockchain networks
     * Smart contract execution
     * State management
     * Consensus mechanisms
@@ -194,19 +194,19 @@
 
 <CardGroup>
   <Card title="IXO Protocol" icon="cube" href="/protocols/ixo-protocol">
     Blockchain network for digital twins, impact claims, and tokenization
   </Card>
 
   <Card title="IXO Matrix" icon="database" href="/articles/ixo-matrix">
     Secure data storage and messaging with end-to-end encryption
   </Card>
 
-  <Card title="Agentic Oracles" icon="brain" href="/articles/ixo-oracles">
+  <Card title="Agentic Oracles" icon="brain" href="/articles/agentic-oracles">
     AI-powered agent services that perform evaluations, verifications, and intelligent automations
   </Card>
 
   <Card title="Blocksync" icon="sync" href="/articles/ixo-blocksync">
     Indexing and query service for blockchain data
   </Card>
 </CardGroup>
 
@@ -218,7 +218,7 @@
     Open platforms with public verification
   </Card>
   <Card title="Private Networks" icon="lock">
     Permissioned access and governance
   </Card>
   <Card title="Hybrid Systems" icon="toggle-on">
     Combined public/private features

articles/qi-intelligent-cooperating-system.mdx

@@ -10,7 +10,7 @@
 
 **Qi** helps **humans and AI agents work together** on **verified workflows**: shared context, clear permissions, messages and rooms where coordination lives, and actions taken through **declared interfaces**—not by inventing facts or bypassing governance.
 
 Qi gives agents what they need to **act on IXO state** responsibly: context, tools, workflow surfaces, and auditability, instead of isolated prompts or opaque tool chains.
 
 A useful rule:
 
@@ -39,13 +39,13 @@
   </Accordion>
 
   <Accordion title="Agentic Oracles" icon="sparkles">
     Agentic Oracles are the service family for intelligent observation, evaluation, decision support, and workflow automation.
 
     They connect agent behavior to IXO-backed context, evidence, and state transitions.
   </Accordion>
 
   <Accordion title="Qi Agents" icon="robot">
     Qi Agents are productized agent surfaces built on the Qi cooperation model.
 
     They help users and systems act on IXO-backed context through guided reasoning, secure coordination, and declared tools.
   </Accordion>
@@ -94,7 +94,7 @@
   </Step>
 
   <Step title="Act through declared interfaces">
     Actions are performed through documented SDKs, APIs, MCP tools, protocol operations, or workflow-specific services.
   </Step>
 
   <Step title="Feed results back into state">
@@ -102,25 +102,25 @@
   </Step>
 </Steps>
 
 The important principle is that Qi actors should not invent state or act outside the workflow model. They should discover state, respect authority, use declared interfaces, and make results inspectable.
 
 ## Agentic Oracles and Qi Agents
 
 Agentic Oracles and Qi Agents are related, but they should not be treated as interchangeable terms.
 
 <CardGroup cols={2}>
-  <Card title="Agentic Oracles" icon="sparkles" href="/articles/ixo-oracles">
+  <Card title="Agentic Oracles" icon="sparkles" href="/articles/agentic-oracles">
     The oracle and agent service family for observing state, evaluating evidence, supporting decisions, and automating workflow actions.
   </Card>
 
   <Card title="Qi Agents" icon="robot" href="/articles/qi-intelligent-cooperating-system">
     Productized agent experiences that use Qi cooperation patterns to help humans and systems work with IXO-backed context.
   </Card>
 </CardGroup>
 
 Use Agentic Oracles when describing the architecture and service pattern.
 
 Use Qi Agents when describing user-facing or productized agent surfaces.
 
 Use the SDK and API references when implementing either pattern.
 
@@ -131,7 +131,7 @@
 Examples include:
 
 <CardGroup cols={2}>
-  <Card title="Evidence review agents" icon="file-shield" href="/articles/ixo-oracles">
+  <Card title="Evidence review agents" icon="file-shield" href="/articles/agentic-oracles">
     Agents that inspect evidence, compare it with workflow rules, and support claim review or verification.
   </Card>
 
@@ -163,7 +163,7 @@
     Learn the vocabulary for IXO state, Qi cooperation, claims, credentials, workflows, evidence, and agents.
   </Card>
 
-  <Card title="Agentic Oracles" icon="sparkles" href="/articles/ixo-oracles">
+  <Card title="Agentic Oracles" icon="sparkles" href="/articles/agentic-oracles">
     Understand the conceptual model for intelligent oracle services, agent capabilities, and automation patterns.
   </Card>
 
@@ -176,7 +176,7 @@
   </Card>
 
   <Card title="Agentic Oracles ADK" icon="code" href="/sdk-reference/agentic-oracles-adk">
     Use the development kit for oracle-powered services and agentic automation patterns.
   </Card>
 
   <Card title="Personal Agent ADK" icon="wand-magic-sparkles" href="/sdk-reference/oracle-adk">

build-an-oracle/develop/plugin-recipes/add-a-middleware.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Add a middleware"
 description: "Hook into every LLM call via beforeModel, afterModel, and onError using createMiddleware."
 icon: "filter"
 ---
 
@@ -55,7 +55,7 @@
   </Step>
 
   <Step title="Return it from getMiddlewares(ctx)">
-    The runtime appends your middlewares after the four always-on framework middlewares.
+    The runtime appends your middleware after the four always-on framework middleware.
 
     ```ts
     import { OraclePlugin, type AgentMiddleware, type PluginContext } from '@ixo/oracle-runtime';
@@ -71,7 +71,7 @@
   </Step>
 
   <Step title="Attach a middleware to a sub-agent (optional)">
-    A sub-agent can carry its own middlewares — they only run inside that sub-agent's loop.
+    A sub-agent can carry its own middleware — it only runs inside that sub-agent's loop.
 
     ```ts
     import { createSummarizationMiddleware } from '@ixo/oracle-runtime';
@@ -87,17 +87,17 @@
 
 ## What to know before shipping
 
-- The four always-on middlewares (`tool-validation`, `tool-retry`, `page-context`, `safety-guardrail`) always run first. They are not removable.
-- Plugin middlewares run in topological dependency order — encode ordering via `dependsOn` if it matters.
-- Middlewares fire per LLM turn, not per individual tool invocation. Wrap the tool handler directly for per-tool behaviour.
+- The four always-on middleware (`tool-validation`, `tool-retry`, `page-context`, `safety-guardrail`) always run first. They are not removable.
+- Plugin middleware runs in topological dependency order — encode ordering via `dependsOn` if it matters.
+- Middleware fires per LLM turn, not per individual tool invocation. Wrap the tool handler directly for per-tool behaviour.
 - Closure-scoped timers interleave across concurrent model calls. For accurate timing, push start times onto a per-call ID.
 - Don't reimplement auth in a middleware — auth runs at the HTTP layer (`AuthHeaderMiddleware`), not in the agent loop.
 
 ## Where to read next
 
 <CardGroup cols={2}>
   <Card title="Add a sub-agent" icon="sitemap" href="/build-an-oracle/develop/plugin-recipes/add-a-sub-agent">
-    Sub-agent-scoped middlewares.
+    Sub-agent-scoped middleware.
   </Card>
   <Card title="State schema" icon="table" href="/build-an-oracle/reference/state-schema">
     What's in `state` when your hooks fire.