docs: apply QA pass and add skill-building guide

.github/workflows/docs-quality.yml

@@ -13,12 +13,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
-          node-version: "20"
+          node-version: "24"
           cache: npm
 
       - name: Install dependencies

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
@@ -346,16 +346,16 @@
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Start Building" icon="rocket" href="/start-building">
+  <Card title="Start Building" icon="rocket" href="/guides/what-you-can-build">
     Build a POD, Flow, Blueprint, or Marketplace using IXO and Qi.
   </Card>
 
   <Card title="Core Concepts" icon="lightbulb" href="/core-concepts">
     Learn the vocabulary for entities, Claims, evidence, credentials, Flows, Blueprints, and outcomes.
   </Card>
 
-  <Card title="Agent Evaluations" icon="clipboard-check" href="/guides/agent-evaluations">
+  <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">

articles/pods.mdx

@@ -19,7 +19,7 @@
 - which decisions, payments, credentials, or state changes are allowed
 
 <Tip>
   A POD is not just a workspace, DAO, database, or chatbot. It is the governed domain where shared state, human roles, agent authority, workflows, and verifiable outcomes come together.
 </Tip>
 
 ## When to build a POD
@@ -28,7 +28,7 @@
 
 <CardGroup cols={2}>
   <Card title="Program operations" icon="diagram-project">
     Coordinate funders, implementers, verifiers, researchers, agents, and services inside one program domain.
   </Card>
 
   <Card title="Verified service delivery" icon="handshake">
@@ -77,7 +77,7 @@
 
   <Accordion title="Blueprints">Protocols that define schemas, evidence rules, rubrics, authority, and outcomes</Accordion>
 
   <Accordion title="Agents">Agentic Oracles or AI services that support review, routing, analysis, monitoring, and decision support</Accordion>
 
   <Accordion title="Rooms">Secure cooperation spaces for humans, agents, and services</Accordion>
 
@@ -110,7 +110,7 @@
   </Step>
 
   <Step title="Agents support the process">
     Agentic Oracles can inspect permitted context, apply rubrics, summarize evidence, flag risks, and create Evaluation Claims.
   </Step>
 
   <Step title="Humans remain accountable">
@@ -168,7 +168,7 @@
 
   <Accordion title="`evidence_required`">Required evidence is requested or validated</Accordion>
 
   <Accordion title="`evaluating`">A human, service, or Agentic Oracle applies the rubric</Accordion>
 
   <Accordion title="`review_required`">A verifier, operator, or governance role reviews the result</Accordion>
 
@@ -176,7 +176,7 @@
 
   <Accordion title="`actioned`">Payment, credential, state update, message, or next Flow is triggered</Accordion>
 
   <Accordion title="`closed`">The process is complete and inspectable</Accordion>
 </AccordionGroup>
 
 ## PODs and agent authority
@@ -220,7 +220,7 @@
 <AccordionGroup>
   <Accordion title="Purpose">Help digital MRV programs find and pay verified field data providers</Accordion>
 
   <Accordion title="Members">Marketplace operator, service providers, buyers, verifiers, funders, agents</Accordion>
 
   <Accordion title="Entities">Providers, listings, projects, service orders, Claims, evidence, outcomes</Accordion>
 
@@ -235,7 +235,7 @@
   <Accordion title="UDID">Records whether the service was accepted and whether payment should be released</Accordion>
 </AccordionGroup>
 
 The POD gives the marketplace an operating boundary. The Flow runs the work. The Blueprint defines the rules. Claims and evidence make delivery inspectable. The UDID records the decision and impact.
 
 ## Example: digital MRV program POD
 
@@ -244,7 +244,7 @@
 <AccordionGroup>
   <Accordion title="Purpose">Verify outcomes for a clean cooking, water, energy, land restoration, or biodiversity program</Accordion>
 
   <Accordion title="Members">Program operator, field teams, device providers, communities, verifiers, funders, researchers</Accordion>
 
   <Accordion title="Entities">Households, devices, projects, reporting periods, measurements, Claims, outcomes</Accordion>
 
@@ -252,7 +252,7 @@
 
   <Accordion title="Flow">Submit measurement Claim, validate evidence, review, determine outcome, trigger settlement</Accordion>
 
   <Accordion title="Agent">Agentic Oracle summarizes evidence and flags anomalies</Accordion>
 
   <Accordion title="Human role">Verifier reviews edge cases and approves determinations</Accordion>
 
@@ -309,11 +309,11 @@
   </Accordion>
 
   <Accordion title="Separate recommendation from decision">
     Agent outputs should be recorded as Evaluation Claims. Decisions and impacts should be recorded as UDIDs when the Flow reaches a determination point.
   </Accordion>
 
   <Accordion title="Use Blueprints for repeatability">
     Put schemas, evidence requirements, rubrics, thresholds, disqualifiers, escalation rules, and outcome logic into a Blueprint.
   </Accordion>
 
   <Accordion title="Design for audit and dispute">
@@ -340,7 +340,7 @@
 - agent permissions are scoped
 - human review is required for high-risk decisions
 - Evaluation Claims have a structured schema
 - UDIDs are used for decision and impact determinations
 - payments, credentials, and state updates require valid authority
 - disputes and corrections have a path
 - participants know where to act and what happens next
@@ -349,19 +349,19 @@
 ## What to build next
 
 <CardGroup cols={2}>
-  <Card title="Build a Flow" icon="route" href="/start-building#build-a-flow">
+  <Card title="Build a Flow" icon="route" href="/guides/users/build-a-flow">
     Define the workflow that runs inside your POD.
   </Card>
 
-  <Card title="Build a Blueprint" icon="file-signature" href="/start-building#build-a-blueprint-protocol">
+  <Card title="Build a Blueprint" icon="file-signature" href="/guides/users/build-a-blueprint">
     Define the schemas, rules, evidence requirements, rubrics, and outcome logic.
   </Card>
 
-  <Card title="Build a Marketplace" icon="store" href="/start-building#build-a-marketplace">
+  <Card title="Build a Marketplace" icon="store" href="/guides/users/build-a-market">
     Create trusted exchange for services, protocols, data, agent capabilities, or verified outcomes.
   </Card>
 
-  <Card title="Agent Evaluations" icon="clipboard-check" href="/guides/agent-evaluations">
+  <Card title="Agent Evaluations" icon="clipboard-check" href="/guides/dev/agent-evaluations">
     Evaluate agent work using Claims, evidence, UCAN authority, rubrics, Flow state, and UDIDs.
   </Card>
 </CardGroup>