docs: apply QA pass across dev and reference docs

.codex/UPGRADE_BACKLOG.md

@@ -212,6 +212,31 @@ Use checkboxes to track completion. Keep task summaries short and file-specific.
   - Done when:
     - each major concept has one canonical home
 
+## Developer guides audit — Apr 2026
+
+Source: `~/.cursor/plans/developer_guides_audit_b84f6fcb.plan.md`
+
+This audit reviewed every page under `guides/dev/` for duplication, broken or invented APIs, missing task scaffolding, and IA orphans. The bulk has been implemented. Items below are residual.
+
+### Decisions (recorded for future contributors)
+
+- `guides/dev/evaluation-engine.mdx` — DELETED (was empty); redirect to `/guides/dev/agent-evaluations` lives in `docs.json`.
+- `guides/dev/claims.mdx` — DELETED (invented message names and superseded by `ixo-claims.mdx`); redirect in place.
+- `guides/dev/introduction.mdx` — DELETED (duplicated `overview.mdx` with non-functional cards); redirect in place.
+- `guides/dev/identity-and-credentials.mdx` — MOVED to `articles/identity-and-credentials.mdx` per `CONTENT_MODEL_AND_IA.md` (concept article belongs in `articles/`); redirect in place; all internal links updated.
+- `guides/dev/ixo-domains.mdx` — KEPT as a routing page accessible by URL but **intentionally absent from nav**; many concept pages link to it (glossary, core-concepts, articles/cdt-systems, articles/assets, articles/domain-config). Adding it to nav would duplicate `overview.mdx`.
+- `guides/dev/ixo-stack-sdks.mdx` — REDUCED to a short pointer page; kept in nav for redirect compatibility (`/guides/dev/spatial-web-sdks` → here).
+- All canonical chain message shapes (entities, tokens, bonds, liquid-staking, smart accounts, claims, authz) — VERIFIED against `ixofoundation/ixo-blockchain` proto files. `MsgSendWithAuthenticator` and `MsgSubmitProposalUpdateLiquidStakeParams` confirmed as not existing — replaced with the `AuthenticatorTxExtension` pattern and the standard Cosmos `MsgSubmitProposal` wrapping.
+- `@ixo/oracle-agent-sdk` snippets — flagged as illustrative; npm package is not publicly published. Canonical home is `sdk-reference/oracle-adk.mdx`.
+
+### Residual / follow-up
+
+- [ ] Confirm the canonical npm slug for the Oracle ADK once the package is published; replace the illustrative snippets in `guides/dev/workflows.mdx` and `guides/dev/examples.mdx` with verified API calls.
+- [ ] Decide whether `guides/dev/ixo-stack-sdks.mdx` should be folded into `guides/dev/overview.mdx` and replaced with a redirect (currently kept as a thin pointer for backward compatibility).
+- [ ] When Mintlify nested-group nav is reviewed, validate the new sub-groups under Developer Guides (Identity and access, Domains and entities, Claims and verification, Tokens and bonds, Channels and integrations, Operate) — adjust labels if site analytics show consistent mismatch.
+- [ ] Cross-check the verified message shapes after every IXO blockchain release; update `tokens.mdx`, `bonds.mdx`, `liquid-staking.mdx`, `smart-accounts.mdx`, `entities.mdx` if proto signatures change.
+- [ ] Consider creating `reference/oracle-adk-status.mdx` with the public availability matrix so guides can defer instead of re-explaining.
+
 ## Phase 6 — Editorial polish and QA
 
 - [ ] Run a repo-wide grammar and formatting cleanup after structural fixes.

.codex/templates/guide-page-template.mdx

@@ -54,6 +54,14 @@ Describe the symptom, likely cause, and fix.
 
 ## Next steps
 
-- Link to the relevant reference page
-- Link to the next guide
-- Link to the canonical product overview
+<CardGroup cols={3}>
+  <Card title="Relevant reference page" icon="book" href="/reference/product-and-sdk-map">
+    Link to the reference surface users need after this guide.
+  </Card>
+  <Card title="Next guide" icon="route" href="/guides/dev/workflows">
+    Link to the most logical follow-on implementation guide.
+  </Card>
+  <Card title="Canonical product overview" icon="diagram-project" href="/introduction">
+    Link to the canonical product or platform overview page.
+  </Card>
+</CardGroup>

.codex/templates/product-overview-template.mdx

@@ -1,6 +1,6 @@
 ---
-title: "<Canonical product or SDK name>"
-description: "<One-sentence description of what this surface is and when to use it>"
+title: "Canonical product or SDK name"
+description: "One-sentence description of what this surface is and when to use it."
 ---
 
 ## What it is
@@ -58,5 +58,11 @@ npm install <verified-package-name>
 
 ## Next steps
 
-- The most important guide
-- The most important reference page
+<CardGroup cols={2}>
+  <Card title="Most important guide" icon="route" href="/guides/dev/workflows">
+    Link the highest-priority implementation guide for this product.
+  </Card>
+  <Card title="Most important reference page" icon="book" href="/reference/product-and-sdk-map">
+    Link the key reference page users need for technical integration.
+  </Card>
+</CardGroup>

guides/dev/identity-and-credentials.mdx → articles/identity-and-credentials.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Identity and credentials"
 icon: "fingerprint"
 description: "How DIDs, claims, and verifiable credentials fit together on IXO, and how they relate to controllers, subjects, and registry state."
 ---
 
 This page ties together concepts that are also described on the [Emerging digital identifiers](/platforms/Emerging/digital-identifiers) and [credential issuance](/platforms/Emerging/credential-issuance) platform pages. Read it when you need **one mental model** before diving into APIs or SDKs.
 
 <Info>
   Standards background: IXO aligns with W3C work on decentralized identifiers and verifiable credentials. See [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) and the [Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/). On-chain and interchain specifics use the **`did:ixo:`** namespace and protocol modules documented under [IXO Protocol](/protocols/ixo-protocol).
 </Info>
 
 ## Definitions
@@ -26,15 +26,15 @@
   </Accordion>
 
   <Accordion title="Subject" icon="bullseye">
-    The entity a statement is **about**. In a verifiable credential, the **credential subject** is identified by a DID (often the holder’s DID).
+    The entity a statement is **about**. In a verifiable credential, the **credential subject** is identified by a DID (often the holder's DID).
   </Accordion>
 
   <Accordion title="Claim" icon="file-signature">
     A structured assertion about reality—typically about a domain or entity—that can be evaluated, disputed, or accepted against a protocol or rubric. Claims carry or reference **evidence**.
   </Accordion>
 
   <Accordion title="Verifiable credential (VC)" icon="id-card">
-    A tamper-evident, issuer-signed bundle of claims about a subject, usable by **verifiers** without trusting only the holder’s copy. Status and revocation may be checked against registry or service endpoints.
+    A tamper-evident, issuer-signed bundle of claims about a subject, usable by **verifiers** without trusting only the holder's copy. Status and revocation may be checked against registry or service endpoints.
   </Accordion>
 
   <Accordion title="Issuer" icon="pen-nib">
@@ -54,8 +54,8 @@
 
 1. **Register identity** — Create or obtain a DID and domain record so the entity exists in the shared model ([digital twins](/guides/digital-twins), [domain registration](/guides/domain-registration)).
 2. **Submit a claim** — Assert something about that entity with evidence and context ([claims](/guides/dev/ixo-claims)).
 3. **Validate / evaluate** — Humans, services, or Agentic Oracles check the claim against program rules; outcomes may be recorded on-chain or in linked services.
-4. **Issue a VC** — After validation, an issuer may bind selected assertions into a verifiable credential whose **subject** is the holder’s DID ([credential issuance](/platforms/Emerging/credential-issuance)).
+4. **Issue a VC** — After validation, an issuer may bind selected assertions into a verifiable credential whose **subject** is the holder's DID ([credential issuance](/platforms/Emerging/credential-issuance)).
 5. **Verify or revoke** — Verifiers check proofs and status; issuers or governance may revoke or supersede credentials when state changes.
 
 ## How the pieces relate
@@ -98,6 +98,14 @@
 
 ## See also
 
-- [Core concepts](/core-concepts) — vocabulary for domains, PODs, cooperation, and Qi
-- [Glossary](/reference/glossary) — short definitions with links
-- [Authentication](/guides/dev/authentication) — credentials and session patterns for developers
+<CardGroup cols={3}>
+  <Card title="Core concepts" icon="lightbulb" href="/core-concepts">
+    Vocabulary for domains, PODs, cooperation, and Qi.
+  </Card>
+  <Card title="Glossary" icon="book" href="/reference/glossary">
+    Short definitions with links to deeper pages.
+  </Card>
+  <Card title="Authentication" icon="key" href="/guides/dev/authentication">
+    Credentials and session patterns for developers.
+  </Card>
+</CardGroup>

core-concepts.mdx

@@ -5,18 +5,18 @@
 ---
 
 <Info>
-  This page is **definitions and structure**: what words mean and how layers fit together. For motivation, positioning, and a short worked example, read [Act on Reality](/introduction) first. When you are ready to pick a first artifact (POD, Flow, Blueprint, and so on), use [What you can build](/guides/what-you-can-build). For DIDs, claims, and verifiable credentials in one place, read [Identity and credentials](/guides/dev/identity-and-credentials). For quick term lookup, use the [Glossary](/reference/glossary).
+  This page is **definitions and structure**: what words mean and how layers fit together. For motivation, positioning, and a short worked example, read [Act on Reality](/introduction) first. When you are ready to pick a first artifact (POD, Flow, Blueprint, and so on), use [What you can build](/guides/what-you-can-build). For DIDs, claims, and verifiable credentials in one place, read [Identity and credentials](/articles/identity-and-credentials). For quick term lookup, use the [Glossary](/reference/glossary).
 </Info>
 
 ## The problem space
 
 If you are building or buying systems for real-world work, you are usually asking how to **trust agents** with consequential work, **verify outcomes** before releasing money or authority, **coordinate** across organizations, and know **what changed**, **who did it**, and **whether it worked**.
 
 IXO and Qi target that class of problem—not generic chat over siloed documents.
 
 Most software tracks **internal** application state. Most AI systems reason over **generated** context. This stack coordinates many actors around **shared, verifiable reality**.
 
 - **State** — Structured information that can be identified, permissioned, queried, verified, and updated through protocol-defined actions: you can say what is true and what changed.
 - **Intelligence** — Humans and AI agents interpret state, coordinate with others, and take accountable action.
 - **Cooperation** — Alignment of people, organizations, agents, services, evidence, and workflows around a shared map of work.
 
@@ -30,7 +30,7 @@
 
 <AccordionGroup>
   <Accordion title="IXO" icon="grid">
     **Problem:** AI agents and partners cannot safely act on **fragmented, unverifiable** data scattered across orgs and tools.
 
     **What the component does:** IXO (including the [IXO Graph](/articles/ixo-graph) and [IXO Protocol](/protocols/ixo-protocol)) connects **entities, identities, claims, evidence, credentials, transactions, and outcomes** into structured state that can be shared, queried, and verified.
 
@@ -65,13 +65,13 @@
 
 In IXO, an **entity domain** (often shortened to **domain**) is the standardized way to register and manage a **digital twin** of a real-world subject on the stack: decentralized identity, verifiable credentials, linked claims and resources, services, and relationships—see [Entity Domains](/guides/dev/ixo-domains) for the developer-oriented model and [Domain registration](/guides/domain-registration) for how domains are created and typed.
 
 Each domain is anchored by a **digital identifier (DID)** following the interchain identifier pattern, has an **entity type** (what class of thing it is), and is associated with a **protocol** that defines the entity **class** and inherited properties. **Controllers** manage the on-chain domain record (DID document), and **metadata** carries standard settings for that type.
 
 Common **domain types** used across solutions include the following (wording aligned with [Domain registration](/guides/domain-registration) and the [Emerging platform domain model](/platforms/Emerging/domain-registration)):
 
 <AccordionGroup>
   <Accordion title="Organisation" icon="building">
     **Organisation** domains represent legal or virtual entities that operate programs, hold rights, or participate in governance—often managed as or alongside DAOs.
 
     They anchor who is accountable, who can act for the entity, and how the organisation connects to projects, assets, and markets.
   </Accordion>
@@ -131,7 +131,7 @@
   </Accordion>
 
   <Accordion title="Flow" icon="route">
     A **Flow** is a **governed workflow**: triggers, states, actions, evidence gates, reviews, and outcomes that move real work forward in an inspectable way.
 
     Hands-on: [Build a Flow](/guides/users/build-a-flow).
   </Accordion>
@@ -155,7 +155,7 @@
   </Accordion>
 
   <Accordion title="IXO Graph" icon="circle-nodes">
     The **IXO Graph** is the shared, queryable map of entities, relationships, claims, evidence, credentials, and outcomes your applications and agents read from. It is the practical “shape” of IXO-backed state. More detail: [IXO Graph](/articles/ixo-graph).
   </Accordion>
 
   <Accordion title="Digital twin" icon="diagram-project">
@@ -203,7 +203,7 @@
   </Accordion>
 
   <Accordion title="Directed acyclic graph (DAG) of state" icon="timeline">
     First-impression phrase: **tamper-resistant history** of important changes. Technically: how certain state transitions are recorded so history stays inspectable and consistent with protocol rules.
   </Accordion>
 
   <Accordion title="Linked data" icon="link">
@@ -259,7 +259,7 @@
   </Accordion>
 
   <Accordion title="2. Identity and authority" icon="fingerprint">
     Domains, DIDs, verification methods, roles, and delegated rights establish who or what can act.
 
     This layer answers questions such as:
 
@@ -294,13 +294,13 @@
   </Accordion>
 
   <Accordion title="6. Intelligence and automation" icon="sparkles">
     Qi Agents and Agentic Oracles evaluate context, reason over evidence, support decisions, and trigger workflow actions.
 
     This layer should not invent state. It should discover relevant state, respect permissions, use declared tools, and act through verifiable processes.
   </Accordion>
 
   <Accordion title="7. Applications and interfaces" icon="window">
     Applications, dashboards, SDKs, APIs, MCP servers, and developer tools expose the stack to builders and users.
 
     This layer turns IXO state and Qi cooperation into usable products, workflows, and services.
   </Accordion>
@@ -322,7 +322,7 @@
   </Step>
 
   <Step title="Read state before acting">
     Use IXO-backed sources, SDKs, APIs, indexed data, or MCP tools to inspect the current state.
   </Step>
 
   <Step title="Separate verified state from assumptions">
@@ -330,7 +330,7 @@
   </Step>
 
   <Step title="Use declared interfaces">
     Do not invent protocol actions, API shapes, permissions, or workflow steps. Use the documented SDKs, APIs, MCP tools, and workflow definitions.
   </Step>
 
   <Step title="Act through accountable workflows">
@@ -338,7 +338,7 @@
   </Step>
 
   <Step title="Record what changed">
     When an action changes state, make the result inspectable, attributable, and available for the next actor.
   </Step>
 </Steps>
 
@@ -348,7 +348,7 @@
 
 <CardGroup cols={2}>
   <Card title="Act on Reality" icon="earth-africa" href="/introduction">
     Outcome-first positioning and a short walkthrough of a verified claims path.
   </Card>
 
   <Card title="What you can build" icon="rocket" href="/guides/what-you-can-build">
@@ -396,7 +396,7 @@
   </Card>
 
   <Card title="Developer overview" icon="hand-pointer" href="/guides/dev/overview">
     SDKs, setup, and implementation entry points.
   </Card>
 
   <Card title="Claims developer guide" icon="file-check" href="/guides/dev/ixo-claims">

docs.json

@@ -79,18 +79,59 @@
               "guides/dev/overview",
               "guides/dev/ixo-stack-sdks",
               "guides/dev/workflows",
-              "mcp/model-context-protocol",
-              "guides/dev/ussd-gateway",
-              "guides/dev/authentication",
-              "guides/dev/identity-and-credentials",
-              "guides/dev/ixo-claims",
-              "guides/digital-twins",
-              "guides/domain-registration",
-              "guides/dev/domain-settings",
-              "guides/dev/domain-privacy",
-              "guides/digital-mrv",
-              "guides/registry",
-              "guides/ixo-oracles-architecture"
+              "guides/dev/examples",
+              {
+                "group": "Identity and access",
+                "pages": [
+                  "guides/dev/authentication",
+                  "articles/identity-and-credentials",
+                  "guides/dev/session-keys",
+                  "guides/dev/smart-accounts",
+                  "guides/dev/authz",
+                  "guides/dev/authz-custom"
+                ]
+              },
+              {
+                "group": "Domains and entities",
+                "pages": [
+                  "guides/digital-twins",
+                  "guides/dev/entities",
+                  "guides/domain-registration",
+                  "guides/dev/domain-settings",
+                  "guides/dev/domain-privacy"
+                ]
+              },
+              {
+                "group": "Claims and verification",
+                "pages": [
+                  "guides/dev/ixo-claims",
+                  "guides/dev/agent-evaluations",
+                  "guides/digital-mrv"
+                ]
+              },
+              {
+                "group": "Tokens and bonds",
+                "pages": [
+                  "guides/dev/tokens",
+                  "guides/dev/bonds",
+                  "guides/dev/liquid-staking"
+                ]
+              },
+              {
+                "group": "Channels and integrations",
+                "pages": [
+                  "mcp/model-context-protocol",
+                  "guides/dev/ussd-gateway",
+                  "guides/dev/image-handling"
+                ]
+              },
+              {
+                "group": "Operate",
+                "pages": [
+                  "guides/registry",
+                  "guides/ixo-oracles-architecture"
+                ]
+              }
             ]
           }
         ]
@@ -159,6 +200,22 @@
       "source": "/guides/dev/spatial-web-sdks",
       "destination": "/guides/dev/ixo-stack-sdks"
     },
+    {
+      "source": "/guides/dev/introduction",
+      "destination": "/guides/dev/overview"
+    },
+    {
+      "source": "/guides/dev/identity-and-credentials",
+      "destination": "/articles/identity-and-credentials"
+    },
+    {
+      "source": "/guides/dev/evaluation-engine",
+      "destination": "/guides/dev/agent-evaluations"
+    },
+    {
+      "source": "/guides/dev/claims",
+      "destination": "/guides/dev/ixo-claims"
+    },
     {
       "source": "/sdk-reference/oracle-ai-sdk",
       "destination": "/sdk-reference/oracle-adk"

guides/dev/authentication.mdx

@@ -53,6 +53,14 @@ The surface-level rate policy has been exceeded. Apply retry/backoff per API gui
 
 ## Next steps
 
-- API authentication reference: `/api-reference/authentication`
-- Networks and endpoints: `/reference/networks-and-endpoints`
-- Product and SDK map: `/reference/product-and-sdk-map`
+<CardGroup cols={3}>
+  <Card title="API authentication reference" icon="key" href="/api-reference/authentication">
+    Apply endpoint-specific authentication requirements and headers.
+  </Card>
+  <Card title="Networks and endpoints" icon="network-wired" href="/reference/networks-and-endpoints">
+    Select chain IDs and base URLs for your environment.
+  </Card>
+  <Card title="Product and SDK map" icon="diagram-project" href="/reference/product-and-sdk-map">
+    Confirm canonical product names, SDK names, and routes.
+  </Card>
+</CardGroup>

guides/dev/authz-custom.mdx

@@ -1,17 +1,17 @@
 ---
 title: 'Authorization (Authz)'
 description: 'Understanding the core concepts and implementation of authorization in the IXO ecosystem'
 ---
 
 # Authorization (Authz)
 
 The authorization (authz) system is a fundamental concept in the IXO ecosystem, built on top of the Cosmos SDK's authz module. This guide explains the core concepts and implementation details that developers need to understand when working with authorization.
 
 ## Core Concepts
 
 ### Basic Structure
 
 Authorization in IXO follows the Cosmos SDK's authz module implementation (ADR 30), which enables one account (granter) to grant specific privileges to another account (grantee). Each authorization is stored on-chain with three key components:
 
 ```json
 {
@@ -84,5 +84,5 @@
 ## Related Resources
 
 - [Cosmos SDK Authz Module Documentation](https://docs.cosmos.network/main/build/modules/authz)
-- [IXO Claims Module Documentation](/guides/dev/claims)
+- [Claims management](/guides/dev/ixo-claims)
 - [Digital vouchers workflow](/platforms/Emerging/digital-vouchers)