@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/architecture.mdx

@@ -0,0 +1,174 @@
+---
+title: Architecture
+description: How the three Anchor programs, the SDK, and the facilitator-adapter layer compose into one settlement path.
+---
+
+AgentTrust is three Anchor programs plus a TypeScript surface that mounts them on any x402 facilitator. This page is the wiring. Byte-precise PDA layouts, instruction signatures, and deny-reason codes live under [Programs](/programs/policy-vault).
+
+## Composition diagram
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│  x402 Facilitator (Pay.sh ★ default · Dexter · atxp · MCPay)          │
+│                                                                       │
+│   import { mountTrustGate } from "@agenttrust-sdk/trustgate/express"  │
+│   await mountTrustGate(app, { atomicityEnforced: true, … })           │
+│                                                                       │
+│  ★ Pay.sh = Solana Foundation's first x402 facilitator (May 5, 2026)  │
+└───────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼  POST /verify | /settle | /dispute
+       ┌──────────────────────────────────────────────────────────┐
+       │  TrustGate (Anchor program)                              │
+       │  ├─ init_authority (per-facilitator PDA)                 │
+       │  ├─ emit_feedback  ── PDA-signed CPI ──┐                 │
+       │  └─ dispute_payment                    │                 │
+       └─────────────────┬──────────────────────┼─────────────────┘
+                         │                      │
+                         │ CPI                  │ CPI
+                         ▼                      ▼
+       ┌─────────────────────────────┐  ┌──────────────────────────────┐
+       │  PolicyVault                │  │  Quantu agent-registry-8004  │
+       │  ├─ gate_payment composer   │  │  ├─ give_feedback            │
+       │  │   (fail-fast 5 policies) │  │  └─ atom-engine::AtomStats   │
+       │  ├─ KillSwitch • Spending   │  │     (tier @ byte 551)        │
+       │  ├─ Velocity • Counterparty │  │                              │
+       │  └─ RequireValidation       │  │  Pinned commit: bfb09ad      │
+       │                             │  │  Read via byte-offset parser │
+       │  reads ValidationAttestation│  │     (zero Cargo dep)         │
+       └─────────────────┬───────────┘  └──────────────────────────────┘
+                         │
+                         ▼
+       ┌──────────────────────────────────────────┐
+       │  ValidationRegistry                      │
+       │  ├─ register_namespace / _attestor       │
+       │  ├─ request / respond / revoke           │
+       │  └─ ValidationAttestation PDA            │
+       │     (read by PolicyVault parser)         │
+       └──────────────────────────────────────────┘
+```
+
+A single `composeAtomicSettleTx()` call in the SDK builds one Solana transaction with three instructions in canonical order: `gate_payment_strict` → SPL `transferChecked` → `emit_feedback`. The transaction either commits all three or none — never two of three. That is the load-bearing safety property the SDK enforces at three layers.
+
+## The three programs
+
+### PolicyVault — the decision engine
+
+Five orthogonal policy kinds compose under one `gate_payment` instruction with fail-fast semantics:
+
+| Order | Policy | What it checks |
+|---|---|---|
+| 1 | `KillSwitch` | per-agent paused flag — multisig-controlled emergency stop |
+| 2 | `Spending` | per-tx, daily (UTC midnight), weekly (ISO Monday) limits |
+| 3 | `Velocity` | sliding-window cumulative spend, payer-tier-decayed limits |
+| 4 | `CounterpartyTier` | payee `AtomStats.trust_tier` (byte 551), risk score, confidence |
+| 5 | `RequireValidation` | gates against a `ValidationAttestation` PDA (capability proof) |
+
+The composer returns `Allow`, `Deny(reason)`, or `RequireValidation(capability_hash)`. State changes — daily / weekly counters, velocity ledger — apply only on `Allow`. `Deny` and `RequireValidation` mutate nothing.
+
+A strict variant — `gate_payment_strict` — converts non-`Allow` into `Err`. That is the variant the SDK's atomic composer uses: any `Deny` on the gate fails the entire bundled transaction. The Phase J5 Kani proof `gate_payment_strict_correctness` pins the biconditional — strict returns `Ok(())` if and only if the lazy composer returns `Allow` — so a future change cannot silently re-route the `Deny` arm to an `Ok` return.
+
+Byte-precise reference: [PolicyVault](/programs/policy-vault). Composer: [Composer](/programs/policy-vault/composer).
+
+### TrustGate — the facilitator-side program
+
+Two PDAs, three instructions:
+
+| PDA | Seeds | Role |
+|---|---|---|
+| `TrustGateAuthority` | `["trustgate_auth", facilitator]` | Per-facilitator PDA signer for the CPI |
+| `FeedbackEmissionLog` | `["feedback_log", payment_id_hash]` | Init-only idempotency receipt |
+
+`emit_feedback` PDA-signs a CPI into Quantu's `agent-registry-8004::give_feedback`. The `FeedbackEmissionLog` is created via Anchor's `init` constraint — a second tx with the same `payment_id_hash` fails account-already-in-use, so retries cannot double-emit. `dispute_payment` writes a negative-score variant for disputed payments.
+
+Byte-precise reference: [TrustGate](/programs/trustgate). SDK reference: [SDK → mountTrustGate](/sdk/mount-trustgate).
+
+### ValidationRegistry — the third ERC-8004 leg
+
+Five instructions over four PDAs:
+
+| Instruction | Effect |
+|---|---|
+| `register_namespace` | permissionless; caller computes `SHA256(name_utf8)` |
+| `register_attestor` | self-registration with display URI |
+| `request_validation` | open a request for `(subject, capability)` |
+| `respond_to_validation` | attestor writes the attestation PDA |
+| `revoke_validation` | original attestor sets `revoked = true` |
+
+The v1 sybil-resistance model is downstream-consumer filtering: PolicyVault stores a per-policy `accepted_attestors[]` array (length 2). Only attestations from those keys flip `RequireValidation` to `Allow`. Permissionless registration plus opinionated downstream filtering trades global gatekeeping for local trust — the only model that scales with the number of facilitators.
+
+Byte-precise reference: [ValidationRegistry](/programs/validation-registry). v1 capability namespaces seeded on devnet: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+## The FacilitatorAdapter pattern
+
+Every x402 facilitator carries the same payment intent but differs in headers, body shape, proof payload, retry behavior, and settlement metadata. The adapter layer isolates those differences in five methods:
+
+| Method | Responsibility |
+|---|---|
+| `parseRequest(req)` | translate the facilitator's request into `VerifyContext` |
+| `formatChallenge(decision, ctx)` | render `Allow` / `Deny` / `RequireValidation` in that facilitator's wire format |
+| `formatSettlement(ctx)` | produce settlement metadata or an unsigned transaction skeleton |
+| `validatePaymentProof(proof, ctx)` | verify proof shape and cross-check the verify-time context |
+| `emitFeedback(ctx, settlement)` | call the feedback CPI idempotently |
+
+Routes (`/verify`, `/settle`, `/dispute`), the policy gate, and the registry reads do not branch on facilitator name. Pay.sh is the canonical implementation in [`trustgate/server/src/facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh); Dexter, atxp, and MCPay share the same interface. Adding a fifth facilitator stays under a hundred lines.
+
+Walkthrough: [Pay.sh adapter](/integration-guides/pay-sh-adapter). Build your own: [Facilitator adapters](/integration-guides/facilitator-adapters).
+
+## The atomic-tx invariant
+
+`gate_payment_strict` mutates state on `Allow`:
+
+- `PolicyAccount.spending_today_used`, `spending_today_anchor`
+- `PolicyAccount.spending_week_used`, `spending_week_anchor`
+- `VelocityLedger.cumulative_amount`, `last_commit_slot`
+
+If the SPL transfer reverts after that mutation — and the two instructions are in *different* Solana transactions — the gate's state is durable while no value moved. Subsequent `gate_payment` calls read the inflated counters and may deny a legitimate payment, or velocity caps appear hit when nothing real has happened.
+
+The corruption vector is most cleanly triggered by a Token-2022 mint with a `TransferHook` extension that reverts on a compliance check, but it is mint-extension-agnostic: any failing inner instruction in a split flow corrupts state the same way.
+
+The SDK closes the corruption vector at three layers:
+
+1. **Compile-time literal-type guard.** `AtomicityEnforced` is the literal type `{ atomicityEnforced: true }`. TypeScript rejects callers passing `false` or omitting the field. No runtime cost.
+2. **Runtime guard.** `assertAtomicityEnforced` throws `AtomicityNotEnforcedError` for any value that isn't strictly `=== true`. Catches `as any` cast bypasses.
+3. **Composer structure.** `composeAtomicSettleTx` returns one `Transaction` with exactly three instructions in canonical order (gate, transfer, feedback). Any other shape is a programming error.
+
+Plus the on-chain Kani proof `gate_payment_strict_correctness` pins the strict handler's contract end-to-end: `Ok(())` if and only if the composer returned `Allow`. Full proof: [Verification → Atomic-tx invariant](/verification/atomic-tx-invariant). Background: [`docs/proofs/transfer-hook-atomicity.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/transfer-hook-atomicity.md).
+
+## ERC-8004 wiring
+
+Quantu Labs published two of the three ERC-8004 legs on Solana:
+
+- `agent-registry-8004` — agent identity plus the reputation surface (the `give_feedback` instruction). Each agent gets a Metaplex Core asset plus a Borsh-typed `AgentAccount` PDA.
+- `atom-engine` — confidence-weighted reputation aggregation. The `AtomStats` PDA stores `tier_immediate` and `tier_confirmed` as single bytes.
+
+The third leg — capability validation — was scaffolded in `8004-solana` v0.4 then archived in v0.5.0 pending a redesign. AgentTrust's `ValidationRegistry` productizes it. The semantics align with the ERC-8004 V variant: who attests to a capability the payer's policy requires (KYC tier, audit attestation, jurisdictional compliance, model-card provenance, payment-network membership).
+
+PolicyVault reads from both Quantu legs:
+
+| Field | Source PDA | Offset | Width |
+|---|---|---|---|
+| trust tier (immediate) | `AtomStats` | byte 551 | u8 |
+| trust tier (confirmed) | `AtomStats` | byte 555 | u8 |
+| risk score | `AtomStats` | byte 549 | u8 |
+| confidence | `AtomStats` | byte 557 | u16 LE |
+| schema version canary | `AtomStats` | byte 560 | u8 (must equal 1) |
+
+A schema bump on the Quantu side fails the canary check loud rather than silently misreading fields. Full byte-offset reference: [Reference → Byte offsets](/reference/byte-offset-reference).
+
+## Read next
+
+<Cards>
+  <Card title="PolicyVault composer" href="/programs/policy-vault/composer">
+    The pure-Rust orchestration that ties the five policy kinds together.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Three layers of proof that gate + transfer + feedback execute as one tx or none.
+  </Card>
+  <Card title="Live evidence" href="/verification/live-evidence">
+    Six Kani proofs, devnet smoke traces, the chained-validation 4-sig trace.
+  </Card>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    The canonical FacilitatorAdapter implementation, end to end.
+  </Card>
+</Cards>

package/dist/embedded-docs/getting-started/quickstart.mdx

@@ -1,100 +1,123 @@
 ---
 title: Quickstart
-description: Run AgentTrust with Pay.sh in under 10 minutes.
+description: Hit the hosted devnet build, install the SDK, wire the MCP server. Three paths, no clone, under five minutes.
 ---
 
-This page gets you from a clean checkout to a Pay.sh + AgentTrust server you can hit locally. It shows the x402 challenge, the Pay.sh retry, the AgentTrust decision, and the feedback receipt path.
+Three live paths. Each runs against the hosted devnet endpoints under `*.agenttrust.tech`. None require a local clone.
 
-## 1. Install
+## 1. Hit the live demo
+
+The demo at [`demo.agenttrust.tech`](https://demo.agenttrust.tech) runs the full Pay.sh + AgentTrust flow against deployed devnet programs. With no payment proof, `/protected` returns a real x402 v2 challenge:
 
 ```bash
-pnpm install
+curl -i https://demo.agenttrust.tech/protected
 ```
 
-The public SDK package is `@agenttrust-sdk/trustgate`. The Pay.sh demo imports the server workspace package directly so it can exercise the adapter layer before packaging.
-
-## 2. Build the demo
+The response carries `HTTP/2 402` with a SERVICE-signed `payment-required` envelope (base64). To walk the full Allow → settle → emit_feedback path, install Pay.sh and let it pay:
 
 ```bash
-pnpm --filter ./examples/pay-sh-demo build
+pay --sandbox curl https://demo.agenttrust.tech/protected
 ```
 
-## 3. Start the server
+Three deterministic counterparties drive each decision branch. Fetch their pubkeys from the demo's health endpoint:
 
 ```bash
-pnpm --filter ./examples/pay-sh-demo dev
+curl -s https://demo.agenttrust.tech/health | jq '.counterparties'
 ```
 
-The server listens on `:3402` and exposes:
+| Tier | Header | Decision |
+| --- | --- | --- |
+| 0 | `X-Demo-Payer-Agent: <tier-0 pubkey>` | `402 Deny — CounterpartyTierBelowMin` |
+| 1 | `X-Demo-Payer-Agent: <tier-1 pubkey>` | `402 Deny — CounterpartyTierBelowMin` |
+| 3 | `X-Demo-Payer-Agent: <tier-3 pubkey>` | `200 Allow + X-Payment-Receipt` |
 
-| Route | Purpose |
-| --- | --- |
-| `GET /health` | deterministic demo counterparties and facilitator key |
-| `GET /protected` | Pay.sh-gated resource |
+The full atomic-settlement trace (gate, transfer, feedback) for the tier-3 path is captured under [Verification → Devnet smoke](/verification/devnet-smoke).
 
-## 4. Drive the Pay.sh path
+## 2. Install the SDK
 
-Without a payment proof, `/protected` returns `402 Payment Required` with a base64 x402 v2 challenge.
+Add [`@agenttrust-sdk/trustgate@0.2.0`](https://www.npmjs.com/package/@agenttrust-sdk/trustgate) to any Node project:
 
 ```bash
-curl -i https://demo.agenttrust.tech/protected
+pnpm add @agenttrust-sdk/trustgate
 ```
 
-With Pay.sh installed, let the CLI pay and retry.
+Mount the middleware on an Express app:
 
-```bash
-pay --sandbox curl https://demo.agenttrust.tech/protected
-```
+```ts
+import express from "express";
+import { Keypair } from "@solana/web3.js";
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
 
-For a deterministic Allow path, use the tier-3 demo counterparty.
+const app = express();
+app.use(express.json());
 
-```bash
-PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[2].agent')
-pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
-```
-
-For a deterministic Deny path, use tier 0.
+await mountTrustGate(app, {
+  rpcUrl:             "https://api.devnet.solana.com",
+  facilitatorKeypair: Keypair.fromSecretKey(/* your facilitator key */),
+  network:            "solana-devnet",
+  atomicityEnforced:  true,             // literal `true` — TS rejects `false`
+});
 
-```bash
-PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[0].agent')
-pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
+app.listen(3000);
 ```
 
-## 5. Run the same flow without the CLI
+The `atomicityEnforced: true` literal is the SDK's load-bearing guard. The compile-time type rejects callers who omit it, the runtime throws on `as any` bypasses, and the on-chain `gate_payment_strict_correctness` Kani proof binds the strict handler's return value to the composer's `Allow` arm. Full details: [Atomic-tx invariant](/verification/atomic-tx-invariant).
 
-The integration tests synthesize Pay.sh proof bodies and drive the same Express route in-process.
+You now have:
 
-```bash
-pnpm --filter ./examples/pay-sh-demo test
-```
+- `POST /verify` — read-only `gate_payment` simulation
+- `POST /settle` — one-tx atomic settle (gate + transfer + feedback)
+- `POST /dispute` — dispute path
+- `GET /receipt/:hash` — `FeedbackEmissionLog` lookup by payment hash
 
-## What happens inside
+## 3. Wire the MCP server
 
-```ts
-adapter.parseRequest(req)
-  -> VerifyContext
-  -> decide(ctx)
-  -> adapter.formatChallenge(decision, ctx)
-  -> adapter.validatePaymentProof(proof, ctx)
-  -> adapter.emitFeedback(ctx, settlement)
+[`@agenttrust-sdk/mcp@0.2.6`](https://www.npmjs.com/package/@agenttrust-sdk/mcp) exposes 18 tools to any Model Context Protocol client. For Claude Desktop, drop this into your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
 ```
 
-The local demo stubs RPC and CPI so CI can run without devnet. The server package carries the real Anchor path: `trustgate/server/src/chain.ts` loads the deployed devnet programs, `/verify` simulates `gate_payment`, and `/settle` delegates proof validation plus feedback emission through the active adapter.
+Restart Claude Desktop. Then ask:
 
-Production fills these same dependency seams:
+- *"What demo agents are available on AgentTrust?"*
+- *"Simulate a 5-USDC payment from the tier-3 demo agent to the tier-0 demo agent against policy 1. What does the gate decide?"*
+- *"Search the AgentTrust docs for the atomic-tx invariant."*
 
-| Seam | Demo implementation | Production implementation |
-| --- | --- |
-| `decide(ctx)` | static tier table | `simulateGatePayment` against devnet programs |
-| `validateOnChainTx` | synthetic confirmed tx | RPC + SPL transfer parser |
-| `emitFeedbackCpi` | synthetic feedback signature | Anchor call into `trustgate::emit_feedback` |
+A hosted HTTP transport is also live at [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) for clients that speak `StreamableHTTPServerTransport`. Full setup: [MCP → Install](/mcp/install).
 
-## Pinned devnet IDs
+## What's running where
 
 <ProgramIdsTable />
 
+| Surface | URL |
+| --- | --- |
+| Demo | [`demo.agenttrust.tech`](https://demo.agenttrust.tech) |
+| Facilitator (`/verify` + `/settle`) | [`api.agenttrust.tech`](https://api.agenttrust.tech) |
+| MCP HTTP endpoint | [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) |
+| Repo | [`github.com/agenttrust-labs/agenttrust`](https://github.com/agenttrust-labs/agenttrust) |
+
 ## Read next
 
-- [Pay.sh adapter](/integration-guides/pay-sh-adapter)
-- [Facilitator adapters](/integration-guides/facilitator-adapters)
-- [Atomic-tx invariant](/sdk/atomic-tx-invariant)
+<Cards>
+  <Card title="Architecture" href="/architecture">
+    How the three programs, the SDK, and the adapter layer compose into one settlement path.
+  </Card>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    The live Pay.sh integration end to end — challenge, retry, settle, feedback.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Why gate + transfer + feedback must execute as one Solana transaction or none.
+  </Card>
+</Cards>

package/dist/embedded-docs/index.mdx

@@ -1,64 +1,81 @@
 ---
-title: Introduction
-description: AgentTrust is the Solana policy and feedback layer for x402 facilitators.
+title: AgentTrust
+description: Three Anchor programs that complete the third leg of ERC-8004 on Solana — the policy, settlement, and feedback layer for x402 facilitators.
 ---
 
-AgentTrust is the Solana policy and feedback layer for x402 facilitators.
-
-Pay.sh is the first concrete adapter: an AgentTrust-aware service can emit a Pay.sh x402 challenge, verify the SERVICE signature, run the policy decision, and settle with feedback tied to the same payment context. The same adapter contract is designed for Dexter, atxp_ai, MCPay, and the next facilitator without rewriting the routes.
+Quantu Labs shipped two of the three ERC-8004 legs on Solana — agent identity (`agent-registry-8004`) and reputation (`atom-engine`). The third leg, capability validation, was archived in v0.5.0 pending a redesign. AgentTrust ships that third leg, plus a policy engine that reads Quantu's reputation tier byte by byte, plus a facilitator-side program that emits feedback through Quantu's existing CPI surface.
 
 <KaniProofBadge />
 
-## What AgentTrust ships today
+## Hit it now
 
-AgentTrust ships as three Anchor programs, a TypeScript SDK, and a facilitator-adapter layer.
+Three live paths against the hosted devnet build. No clone, no setup.
 
-| Part | Reads | Writes | Result |
-| --- | --- | --- | --- |
-| PolicyVault | payer and payee trust data | policy counters and velocity ledgers | `Allow`, `Deny`, or `RequireValidation` |
-| TrustGate | PolicyVault decisions | Quantu feedback logs | x402 status and ERC-8004 feedback |
-| ValidationRegistry | attestor profiles and attestations | capability attestations | reusable validation evidence |
-| Pay.sh adapter | x402 v2 `PaymentRequirements` | SERVICE-signed challenge and feedback receipt | live Pay.sh integration path |
+```bash
+# 1. See an x402 challenge from a real facilitator
+curl -i https://demo.agenttrust.tech/protected
 
-## Facilitator status
+# 2. Install the SDK
+pnpm add @agenttrust-sdk/trustgate
 
-| Facilitator | Status | Notes |
-| --- | --- | --- |
-| Pay.sh | live | First concrete adapter; launch announced by Solana Foundation with Google Cloud on May 5, 2026. |
-| Dexter | in flight | Worked example for the next adapter path; current repo carries a roadmap stub until full wiring lands. |
-| atxp_ai | roadmap | Stubbed explicitly so callers see a planned integration, not an accidental absence. |
-| MCPay | roadmap | Stubbed explicitly for the same adapter contract. |
+# 3. Wire the MCP server into Claude Desktop / Cursor
+npx -y @agenttrust-sdk/mcp
+```
 
-Pay.sh launch reference: [Solana Foundation launch note](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud).
+## What's deployed
 
-## Devnet deployment
+<ProgramIdsTable />
 
-The current Frontier build is deployed on Solana devnet and keeps the same adapter boundary for mainnet rollout.
+[SDK on npm](https://www.npmjs.com/package/@agenttrust-sdk/trustgate) ·
+[MCP on npm](https://www.npmjs.com/package/@agenttrust-sdk/mcp) ·
+[Repo](https://github.com/agenttrust-labs/agenttrust) ·
+[Hosted demo](https://demo.agenttrust.tech) ·
+[Hosted facilitator](https://api.agenttrust.tech) ·
+[Hosted MCP](https://mcp.agenttrust.tech)
 
-<ProgramIdsTable />
+## The three programs
 
-## The shortest path
+**PolicyVault** is the decision engine. Five orthogonal policy kinds — `KillSwitch`, `Spending`, `Velocity`, `CounterpartyTier`, `RequireValidation` — composed under one `gate_payment` instruction with fail-fast semantics. The composer returns `Allow`, `Deny(reason)`, or `RequireValidation(capability_hash)`. `CounterpartyTier` reads byte 551 of Quantu's `AtomStats` through a manual byte-offset parser pinned to commit `bfb09ad` (zero Cargo dep on Quantu's crate, schema-version canary at byte 560 catches drift).
 
-Run the Pay.sh demo, then copy the adapter shape into your own facilitator.
+**TrustGate** is the facilitator-side program. One PDA per facilitator (`TrustGateAuthority`) signs the CPI into Quantu's `agent-registry-8004::give_feedback`. `FeedbackEmissionLog` is the per-payment idempotency receipt — Anchor's `init` constraint fails on the second tx with the same `payment_id_hash`, so retries cannot double-emit. The TypeScript SDK, [`@agenttrust-sdk/trustgate@0.2.0`](https://www.npmjs.com/package/@agenttrust-sdk/trustgate), mounts on any Express app in five lines.
 
-```bash
-pnpm --filter ./examples/pay-sh-demo dev
-```
+**ValidationRegistry** productizes the third leg. Five instructions — `register_namespace`, `register_attestor`, `request_validation`, `respond_to_validation`, `revoke_validation` — over four PDAs. The v1 sybil-resistance model is downstream-consumer filtering: PolicyVault stores a per-policy `accepted_attestors[]` array; only attestations from those keys flip the gate to `Allow`. Permissionless registration plus opinionated downstream filtering is the only model that scales with the number of facilitators.
+
+## How they compose
 
-```bash
-pay --sandbox curl https://demo.agenttrust.tech/protected
 ```
+x402 facilitator (Pay.sh, Dexter, atxp, MCPay)
+        │
+        ▼  POST /verify | /settle | /dispute
+TrustGate ─CPI─► agent-registry-8004::give_feedback
+   │
+   │ reads
+   ▼
+PolicyVault ─reads─► AtomStats (Quantu)        ◀── byte 551 (tier)
+   │
+   └─reads─► ValidationAttestation              ◀── byte 8 / 40 / 72 / 208 / 216
+              (ValidationRegistry)
+```
+
+The full wiring story is on [Architecture](/architecture). Byte-precise PDA layouts, instruction signatures, and deny-reason codes live under [Programs](/programs/policy-vault).
 
-## Read next
+## Foundation alignment
+
+Pay.sh is the Solana Foundation's first x402 facilitator, [launched 2026-05-05 with Google Cloud](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud). AgentTrust ships day-one Pay.sh integration as the canonical adapter — Dexter, atxp, and MCPay share the same five-method `FacilitatorAdapter` contract, so adding a fifth facilitator stays under a hundred lines. Walkthrough: [Pay.sh adapter](/integration-guides/pay-sh-adapter).
+
+## Where to next
 
 <Cards>
   <Card title="Quickstart" href="/getting-started/quickstart">
-    Run the Pay.sh demo and inspect Allow / Deny paths.
+    Hit the live demo, install the SDK, wire the MCP server.
+  </Card>
+  <Card title="Architecture" href="/architecture">
+    The wiring diagram, the FacilitatorAdapter pattern, the atomic-tx invariant.
   </Card>
-  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
-    Walk through the live adapter end to end.
+  <Card title="Live evidence" href="/verification/live-evidence">
+    Six Kani proofs, devnet smoke traces, the chained-validation 4-sig trace, every claim with an Explorer URL.
   </Card>
-  <Card title="Architecture overview" href="/getting-started/architecture-overview">
-    See why the adapter layer exists and how it composes with the programs.
+  <Card title="MCP server" href="/mcp">
+    Eighteen tools that expose every SDK surface to Claude Desktop and Cursor.
   </Card>
 </Cards>

package/dist/embedded-docs/integration-guides/capability-namespaces.mdx

@@ -1,15 +1,142 @@
 ---
 title: Capability namespaces
-description: Naming and hashing convention for validation capabilities.
+description: Register a new namespace, derive its hash, gate against it from PolicyVault. Plus how the v1 sybil-resistance model devolves trust to PolicyVault's accepted_attestors[].
 ---
 
-`In progress`
+Capability namespaces are the names PolicyVault gates against in `RequireValidation`. Each namespace is identified on chain by `SHA-256(name_utf8)` — that 32-byte hash is what `PolicyAccount.required_capability_hash` stores and what the `X-Capability-Required` x402 response header carries.
 
-Capability namespaces let facilitators ask for a specific validation artifact without coupling the payment route to one attestor. The ValidationRegistry stores the namespace and the attestation PDA stores the capability hash.
+Source: [`programs/validation-registry/src/instructions/register_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/register_namespace.rs). State: [`state/capability_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/capability_namespace.rs).
 
-| Source | Path |
-| --- | --- |
-| namespace state | [`programs/validation-registry/src/state/capability_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/capability_namespace.rs) |
-| register instruction | [`programs/validation-registry/src/instructions/register_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/register_namespace.rs) |
-| x402 header | [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts) |
+## Register a namespace
 
+```ts
+import { Keypair, PublicKey, sendAndConfirmTransaction, Transaction } from "@solana/web3.js";
+import {
+  buildRegisterNamespaceIx,
+  computeCapabilityHash,
+  loadValidationRegistry,
+  makeProvider,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+} from "@agenttrust-sdk/trustgate";
+
+const creator = Keypair.fromSecretKey(/* funded devnet keypair */);
+const provider = makeProvider({
+  rpcUrl: "https://api.devnet.solana.com",
+  wallet: creator,
+});
+
+const validationRegistry = await loadValidationRegistry(
+  provider,
+  DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry,
+);
+
+const name = "my-org.attestation.v1";          // ≤ 32 bytes; min 3; no ':' allowed
+const version = "v1";                           // ≤ 16 bytes
+const schemaUri = "https://my-org.example/schemas/attestation.v1.json";
+
+const namespaceHash = computeCapabilityHash(name);  // SHA-256(name)
+
+const ix = await buildRegisterNamespaceIx({
+  program:        validationRegistry,
+  creator:        creator.publicKey,
+  namespaceHash,
+  name,
+  version,
+  schemaUri,
+});
+
+const tx = new Transaction().add(ix);
+const sig = await sendAndConfirmTransaction(provider.connection, tx, [creator]);
+console.log(`Namespace registered: ${sig}`);
+```
+
+The `register_namespace` instruction enforces:
+
+| Constraint | Limit | Error on violation |
+|---|---|---|
+| `name.len() >= 3` | min 3 | `NameTooShort` |
+| `name.len() <= 32` | max 32 | `NameTooLong` |
+| `':'` not in `name` | forbidden | `NamespaceColonForbidden` (so namespace strings pack into URIs without escaping) |
+| `version.len() <= 16` | max 16 | `VersionTooLong` |
+| `schema_uri.len() <= 160` | max 160 | `UriTooLong` |
+
+Anyone can register a namespace — rent (~0.0023 SOL) is the economic deterrent. PolicyVault decides per-policy which attestors it trusts via `accepted_attestors[]`, so a namespace registration alone confers no trust.
+
+## Derive the PDA
+
+```ts
+import { deriveCapabilityNamespacePda } from "@agenttrust-sdk/trustgate";
+
+const namespacePda = deriveCapabilityNamespacePda(
+  DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry,
+  namespaceHash, // 32 bytes
+);
+```
+
+PDA seeds: `["capability", namespace_hash]`.
+
+## Gate a policy against it
+
+Set `required_capability_hash` on `PolicyAccount` when calling `init_policy`:
+
+```ts
+import { BN } from "@coral-xyz/anchor";
+
+await policyVault.methods
+  .initPolicy({
+    policyId:                1,
+    enabledKindsBitmask:     0b11111,  // all five kinds
+    requiredCapabilityHash:  Array.from(namespaceHash),
+    acceptedAttestors:       [/* up to 2 trusted attestor pubkeys, or both PublicKey.default for permissionless */],
+    /* … other policy fields … */
+  })
+  .accounts({
+    /* … */
+  })
+  .rpc();
+```
+
+When PolicyVault's gate runs:
+
+1. If `required_capability_hash == [0; 32]` (zero) — policy is not enabled; pass-through.
+2. Else, look for a `ValidationAttestation` PDA at `["attestation", payee_asset, capability_hash, attestor]`. The `attestor` slot iterates against `accepted_attestors[]`.
+3. If no attestation exists → `RequireValidation(capability_hash)` is returned. The facilitator's `formatChallenge` includes `X-Capability-Required: <hex>` in the x402 response.
+4. After the user obtains an attestation (off-chain claim → attestor calls `respond_to_validation` → PDA written) and re-submits the payment, the gate flips to `Allow`.
+
+Full decision flow: [PolicyVault → RequireValidation policy](/programs/policy-vault/require-validation-policy).
+
+## Naming conventions
+
+The seeded v1 namespaces follow a `domain.subcategory.version` shape:
+
+- `kyc.tier-1.v1`, `kyc.tier-2.v1`, `kyc.tier-3.v1`
+- `audit.smart-contract.v1`, `audit.attestor-firm.v1`
+- `model-card.v1`
+- `jurisdiction.v1`
+- `compliance.payments.v1`
+- `agent-source.v1`
+- `usdc-payment-policy.v1` (the Phase D demo capability)
+
+Full lookup with PDAs and Explorer URLs: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+The playbook-level descriptive labels in [`docs/plan/research/06-validation-registry-class.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/plan/research/06-validation-registry-class.md) (e.g., `kyc.tier-1.v1.identity-verified`) decompose to these on-chain `name` strings plus the JSON `description` field. The chain stores the bounded name; richer metadata lives in the `schema_uri` document.
+
+## Sybil-resistance model — local trust, not global
+
+Permissionless registration plus per-policy `accepted_attestors[]` filtering. PolicyVault decides which attestors it trusts for a given capability, not a central allow-list. A policy that gates against `audit.smart-contract.v1` might only accept attestations from Halborn or OtterSec; a policy that gates against `kyc.tier-1.v1` might accept any registered KYC attestor.
+
+The trade-off is local trust over global gatekeeping — the only model that scales with the number of facilitators. Detailed rationale: [ValidationRegistry](/programs/validation-registry).
+
+## Read next
+
+<Cards>
+  <Card title="Custom attestor" href="/integration-guides/custom-attestor">
+    The other side — register an attestor profile, respond to validation requests, revoke.
+  </Card>
+  <Card title="RequireValidation policy" href="/programs/policy-vault/require-validation-policy">
+    The PolicyVault read path that consumes the attestation PDA.
+  </Card>
+  <Card title="Capability namespaces (live)" href="/reference/capability-namespaces">
+    Every seeded v1 namespace with PDA + Explorer URL.
+  </Card>
+</Cards>