@agenttrust-sdk/mcp 0.2.6 → 0.3.1

package/dist/embedded-docs/mcp/install.mdx

@@ -0,0 +1,183 @@
+---
+title: Install
+description: Wire @agenttrust-sdk/mcp into Claude Desktop, Cursor, or any MCP-capable client — stdio or hosted HTTP.
+---
+
+Three install paths: Claude Desktop (one command), Cursor, or any generic stdio MCP client. Plus the always-on hosted HTTP endpoint at [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) for cloud agents.
+
+## Claude Desktop (recommended)
+
+Add to your config — `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Eighteen tools are now available in chat. No clone, no local build.
+
+### Local clone (for development)
+
+If you want to iterate on the MCP server's source, swap the `command`/`args`:
+
+```json
+"command": "node",
+"args": ["/absolute/path/to/agenttrust/mcp/dist/index.js"]
+```
+
+Or run the helper that wires the local path automatically:
+
+```bash
+mcp/scripts/install-claude-desktop.sh
+```
+
+The script edits the Claude Desktop config in place. It backs up the prior config to `claude_desktop_config.json.bak.<timestamp>` so you can revert.
+
+## Cursor
+
+Cursor's MCP config lives at `~/.cursor/mcp.json` (or per-workspace `.cursor/mcp.json`). Same shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"]
+    }
+  }
+}
+```
+
+## Generic stdio MCP client
+
+The package ships a binary entry point. Once installed:
+
+```bash
+pnpm add @agenttrust-sdk/mcp
+node ./node_modules/@agenttrust-sdk/mcp/dist/index.js   # stdio transport, default
+```
+
+The server speaks MCP over stdin/stdout. Any compliant MCP client attaches by spawning this command.
+
+## Hosted HTTP endpoint
+
+The public hosted MCP HTTP endpoint is **already live**:
+
+```
+https://mcp.agenttrust.tech
+```
+
+Health check:
+
+```bash
+curl https://mcp.agenttrust.tech/healthz
+# → {"ok":true,"service":"agenttrust-mcp","version":"0.2.6","network":"solana-devnet","toolCount":18,…}
+```
+
+Hosted on Fly.io (Singapore region, shared-cpu-1x@256MB, always-on with auto-resume on idle). Use this URL in any MCP client that speaks `StreamableHTTPServerTransport` — no local install required. Full hosted-endpoint reference: [Hosted endpoint](/mcp/hosted-endpoint).
+
+To run your own HTTP transport locally:
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=8765 node ./mcp/dist/index.js
+```
+
+Behind any reverse proxy (Caddy, nginx, Vercel, Fly.io) this surfaces as a public hosted endpoint.
+
+## Write tools — adding a keypair
+
+The five write tools (`agenttrust_init_policy`, `agenttrust_set_killswitch`, `agenttrust_request_validation`, `agenttrust_respond_to_validation`, `agenttrust_emit_feedback`) require a signing keypair. Add `KEYPAIR_B58` to the `env` block:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL":     "https://api.devnet.solana.com",
+        "NETWORK":     "solana-devnet",
+        "KEYPAIR_B58": "<base58-encoded 64-byte secret key>"
+      }
+    }
+  }
+}
+```
+
+Without `KEYPAIR_B58`, write tools surface a clear `signer required` error. Read and discovery tools never need it.
+
+Convert a Solana CLI keypair to base58:
+
+```bash
+solana-keygen recover --output-format json -k ~/.config/solana/id.json | jq -r '.privateKey' \
+  | python3 -c "import sys, base58, json; print(base58.b58encode(bytes(json.loads(sys.stdin.read()))).decode())"
+```
+
+Or use the `bs58` CLI:
+
+```bash
+cat ~/.config/solana/id.json | jq -r '.[0:64]' | npx bs58 encode
+```
+
+## Environment variables
+
+| Var | Default | Effect |
+|---|---|---|
+| `RPC_URL` | devnet RPC | Solana RPC endpoint |
+| `NETWORK` | `solana-devnet` | `solana-devnet` or `solana-mainnet`. Drives Quantu program IDs. |
+| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. Required for write tools. |
+| `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `MCP_HTTP_PORT` | `8765` | Port for HTTP transport |
+| `POLICY_VAULT_PROGRAM_ID` | devnet ID | Override `policy_vault` program ID |
+| `TRUSTGATE_PROGRAM_ID` | devnet ID | Override `trustgate` program ID |
+| `VALIDATION_REGISTRY_PROGRAM_ID` | devnet ID | Override `validation_registry` program ID |
+| `MCP_DEFAULT_FACILITATOR` | unset | Default facilitator name in tool replies |
+| `MCP_DOCS_DIR` | repo `docs-site/content/docs` | Override the docs corpus root (tests) |
+| `PAY_SH_DEMO_STATE_FILE` | bundled demo state | Override the demo state file |
+
+## Build + test from source
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+pnpm --filter ./trustgate/sdk run build   # MCP depends on the SDK build output
+pnpm --filter ./mcp run build
+pnpm --filter ./mcp test                  # 76 unit tests, no chain access
+INTEGRATION=1 pnpm --filter ./mcp test:integration   # devnet round-trip
+```
+
+## IDL fetch (verify on-chain truth)
+
+All three Anchor IDLs are published on devnet:
+
+```bash
+anchor idl fetch 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR --provider.cluster devnet  # policy_vault
+anchor idl fetch HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N --provider.cluster devnet  # trustgate
+anchor idl fetch Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv --provider.cluster devnet  # validation_registry
+```
+
+The MCP server bundles snapshots at `mcp/src/idl/*.json` as a defensive fallback (saves an RPC round-trip on cold start; keeps the server bootable in offline / air-gapped harnesses). Latest evidence snapshot: [`docs/proofs/idl-on-chain.json`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/idl-on-chain.json).
+
+## Read next
+
+<Cards>
+  <Card title="Tools" href="/mcp/tools">
+    Eighteen tools with input/output shape.
+  </Card>
+  <Card title="Hosted endpoint" href="/mcp/hosted-endpoint">
+    HTTP transport semantics, sessions, healthz schema.
+  </Card>
+  <Card title="Prompts" href="/mcp/prompts">
+    Three guided workflows for LLM clients.
+  </Card>
+</Cards>

package/dist/embedded-docs/mcp/prompts.mdx

@@ -0,0 +1,90 @@
+---
+title: Prompts
+description: Three guided MCP workflows — audit a payment, set up an agent, explain a failure. Each composes multiple tool calls into a structured procedure.
+---
+
+MCP prompts are reusable, parameterised templates that the server returns in response to `prompts/get`. The client (Claude Desktop, Cursor, OpenAI Agents SDK) presents the prompt's messages to the model, which then drives the tool calls. Prompts encode the right *order* of tool calls for common workflows.
+
+Source: [`mcp/src/prompts/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/prompts).
+
+## Three prompts
+
+| Name | What it walks the user through |
+|---|---|
+| [`agenttrust_audit_payment`](#agenttrust_audit_payment) | Simulate a payment, read the policy, read the payee's reputation, surface the decision |
+| [`agenttrust_setup_agent`](#agenttrust_setup_agent) | Bootstrap an agent's `PolicyAuthority` → `KillSwitchState` → first `PolicyAccount` |
+| [`agenttrust_explain_failure`](#agenttrust_explain_failure) | Given a failed payment's reason code, explain root cause + remediation |
+
+## `agenttrust_audit_payment`
+
+Required args: `payer_agent`, `payee_agent`, `amount`, `mint`, `policy_id`. Optional: `caller`.
+
+The prompt walks the model through:
+
+1. `agenttrust_get_policy({ agent_asset: payer_agent, policy_id })` — read the spending caps, velocity threshold, counterparty tier requirement, required capability.
+2. `agenttrust_get_quantu_reputation({ agent_asset: payee_agent })` — read the payee's tier, risk, confidence.
+3. `agenttrust_simulate_payment({ caller, payer_agent, payee_agent, amount, mint, policy_id })` — run the gate.
+4. Compare the simulation result to the policy thresholds + payee reputation. Surface `Allow`, `Deny(reason)`, or `RequireValidation(capability)` with the relevant numbers.
+
+Use case: "Audit this payment before I send it." The model produces a structured explanation of the decision rather than a yes/no answer.
+
+## `agenttrust_setup_agent`
+
+Required args: `agent_asset`, `use_case`. The `use_case` is free-text — the prompt uses it to suggest reasonable defaults for the policy fields (per-tx cap, velocity window, counterparty tier minimum).
+
+The prompt walks the model through:
+
+1. `agenttrust_get_killswitch({ agent_asset })` — check whether `PolicyAuthority` and `KillSwitchState` exist.
+2. If absent, instruct the model to call `init_authority` (off-band, since v1 doesn't expose this as an MCP write tool).
+3. `agenttrust_init_policy({ agent_asset, policy_id: 1, enabled_kinds_bitmask: 0b11111, … })` — initialise the first policy with use-case-tailored defaults.
+4. Confirm the result by calling `agenttrust_get_policy`.
+
+Use case: "I just got my Quantu agent identity. Set up a basic AgentTrust policy." The prompt + the write tools land a working policy in three or four turns.
+
+## `agenttrust_explain_failure`
+
+Required args: `reason_code` (1..15). Optional: `payer_agent`, `payee_agent`, `policy_id`.
+
+The prompt walks the model through:
+
+1. `agenttrust_explain_decision({ reason_code })` — translate to canonical name + remediation hint.
+2. If the optional context is present, run the relevant lookup (`get_quantu_reputation`, `get_velocity`, `get_killswitch`, `get_validation_attestation`) to inspect the actual on-chain state that drove the deny.
+3. Surface the contradiction in plain language ("the policy requires `min_counterparty_tier = 3` but the payee's `tier_immediate = 1`").
+
+Use case: "Why did my last payment fail with reason code 6?" The prompt produces an explanation grounded in real on-chain state, not training-data guesses.
+
+## How clients invoke prompts
+
+```ts
+// Pseudocode — the actual API depends on the MCP client.
+const prompts = await mcp.request("prompts/list");
+// → [{ name: "agenttrust_audit_payment", description, arguments }, …]
+
+const audit = await mcp.request("prompts/get", {
+  name:      "agenttrust_audit_payment",
+  arguments: {
+    payer_agent: "5Pfa…K8y",
+    payee_agent: "C9pY…B3dR",
+    amount:      "1000000",
+    mint:        "EPjF…Dt1v",
+    policy_id:   1,
+    caller:      "4tSE…hRG",
+  },
+});
+// → { messages: [{ role: "user", content: { type: "text", text: "Walk me through auditing this payment…" } }, … ] }
+```
+
+The model then picks tools to call, the client surfaces the tool results back to the model, and the prompt's structure produces a grounded answer.
+
+In Claude Desktop, prompts appear as slash commands when an MCP server is connected. Type `/agenttrust_audit_payment` in chat → the UI prompts for the required arguments → the model executes the workflow.
+
+## Validation
+
+Phase M validated all three prompts via direct `prompts/get` calls. All three return non-empty `messages` arrays with structured user prompts referencing the right tools. Missing-argument probes return clean `-32603 missing required argument` errors. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) §M1.5.
+
+Phase P verified `agenttrust_explain_failure` end-to-end with Claude `sonnet` driving the workflow against live devnet state — the model called `agenttrust_explain_decision(6)` then `agenttrust_get_killswitch` to inspect the actual policy fields, and produced a remediation in plain language.
+
+## Source
+
+- Prompts: [`mcp/src/prompts/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/prompts)
+- Server wiring: [`mcp/src/server.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/server.ts)

package/dist/embedded-docs/mcp/resources.mdx

@@ -0,0 +1,115 @@
+---
+title: Resources
+description: Four MCP resource URIs — devnet program manifest, docs corpus mirror, demo source files. Path-traversal-safe, MIME-typed, MCP-list-friendly.
+---
+
+The MCP server exposes four `resources/list`-able URIs. Resources are read-only by design; writes happen through tools.
+
+Source: [`mcp/src/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/resources).
+
+## URI manifest
+
+| URI scheme | Mime type | Content |
+|---|---|---|
+| `agenttrust://devnet/programs` | `application/json` | Deployed program IDs + Explorer URLs for the active cluster |
+| `agenttrust://docs/<rel-path>` | `text/markdown` | Each MDX page in the docs corpus exposed individually |
+| `agenttrust://examples/pay-sh-demo/<rel-path>` | `text/x-typescript` / `text/markdown` | Pay.sh demo source files |
+| `agenttrust://examples/attestor-demo/<rel-path>` | `text/x-typescript` / `text/markdown` | Attestor demo source files |
+
+## Devnet program manifest
+
+```json
+{
+  "uri": "agenttrust://devnet/programs",
+  "mimeType": "application/json"
+}
+```
+
+Returns:
+
+```json
+{
+  "network": "solana-devnet",
+  "programs": {
+    "policy_vault": {
+      "id": "8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR",
+      "explorerUrl": "https://explorer.solana.com/address/8Y6f…QTR?cluster=devnet"
+    },
+    "trustgate": {
+      "id": "HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N",
+      "explorerUrl": "https://explorer.solana.com/address/HF8z…ih2N?cluster=devnet"
+    },
+    "validation_registry": {
+      "id": "Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv",
+      "explorerUrl": "https://explorer.solana.com/address/Cx4R…Khtv?cluster=devnet"
+    }
+  }
+}
+```
+
+## Docs corpus mirror
+
+Every MDX page under [`docs-site/content/docs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/docs-site/content/docs) is exposed as an individual resource. Example URIs:
+
+```
+agenttrust://docs/index
+agenttrust://docs/architecture
+agenttrust://docs/programs/policy-vault/index
+agenttrust://docs/sdk/atomic-tx-invariant
+agenttrust://docs/verification/live-evidence
+```
+
+The resource body is the rendered markdown text (frontmatter included). LLM clients use `agenttrust_docs` (a discovery tool with full-text search) to find the right resource, then fetch it via `resources/read`.
+
+## Demo source mirrors
+
+The Pay.sh demo and the attestor demo are bundled in the npm tarball as of 0.2.3. URIs:
+
+```
+agenttrust://examples/pay-sh-demo/README.md
+agenttrust://examples/pay-sh-demo/src/index.ts
+agenttrust://examples/pay-sh-demo/src/middleware.ts
+agenttrust://examples/pay-sh-demo/devnet-counterparties.json
+
+agenttrust://examples/attestor-demo/README.md
+agenttrust://examples/attestor-demo/scripts/devnet-chained-validation.ts
+agenttrust://examples/attestor-demo/devnet-namespaces.json
+```
+
+Use case: an LLM asks "show me the Pay.sh demo source" and the tool returns the actual file contents rather than synthesizing a stale paraphrase from training data.
+
+## Path-traversal safety
+
+All resource URIs go through a path-normalization step before file reads. Probes like `agenttrust://docs/../../etc/passwd` return:
+
+```json
+{
+  "error": {
+    "code":    -32603,
+    "message": "unknown resource URI"
+  }
+}
+```
+
+Same protection on the `examples/` URIs. Source: [`mcp/src/resources/docs.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/resources/docs.ts) — the indexer normalises every path against the corpus root before serving bytes.
+
+Phase M validated this against a deliberate traversal probe — clean error, no escape. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) §M1.4.
+
+## How clients use resources
+
+```ts
+// Pseudocode — actual API depends on the MCP client.
+const list = await mcp.request("resources/list");
+// → [{ uri: "agenttrust://devnet/programs", … }, { uri: "agenttrust://docs/index", … }, …]
+
+const programs = await mcp.request("resources/read", { uri: "agenttrust://devnet/programs" });
+// → { contents: [{ uri, mimeType: "application/json", text: "{ …JSON… }" }] }
+```
+
+Claude Desktop and Cursor surface resources in their model-context UI — the user can attach a resource to the conversation and the LLM reads it directly, no tool round-trip needed.
+
+## Source
+
+- Resource handlers: [`mcp/src/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/resources)
+- Server wiring: [`mcp/src/server.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/server.ts)
+- Path-traversal tests: [`mcp/test/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/test/resources)

package/dist/embedded-docs/mcp/tools.mdx

@@ -0,0 +1,156 @@
+---
+title: Tools
+description: All 18 MCP tools — 10 read, 5 write, 3 discovery — with input/output shape and live devnet examples.
+---
+
+Each tool has a stable Zod schema. Input arguments are documented per tool below. Every write tool surfaces the resulting `txSignature` plus a Solana Explorer URL in its response.
+
+Source: [`mcp/src/tools/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools).
+
+## Read (10 tools — no signer required)
+
+| Tool | Input | Returns |
+|---|---|---|
+| [`agenttrust_get_policy`](#agenttrust_get_policy) | `agent_asset`, `policy_id` | Decoded `PolicyAccount` PDA — every spending cap, velocity threshold, counterparty tier requirement, required capability hash |
+| [`agenttrust_list_policies`](#agenttrust_list_policies) | `agent_asset` | Lightweight summary of all policies registered for an agent |
+| [`agenttrust_simulate_payment`](#agenttrust_simulate_payment) | `caller`, `payer_agent`, `payee_agent`, `amount`, `mint`, `policy_id` | `Allow` / `Deny(reasonCode, reasonName)` / `RequireValidation(capabilityHash)` |
+| [`agenttrust_get_killswitch`](#agenttrust_get_killswitch) | `agent_asset` | `KillSwitchState` + `PolicyAuthority` decoded |
+| [`agenttrust_get_velocity`](#agenttrust_get_velocity) | `agent_asset`, `policy_id` | `VelocityLedger` — sliding-window cumulative spend |
+| [`agenttrust_get_feedback_log`](#agenttrust_get_feedback_log) | `payment_id_hash` (32-byte hex) | `FeedbackEmissionLog` PDA |
+| [`agenttrust_get_quantu_reputation`](#agenttrust_get_quantu_reputation) | `agent_asset` | Quantu `AtomStats` decoded — `tierImmediate`, `tierConfirmed`, `riskScore`, `confidence`, `schemaVersion` |
+| [`agenttrust_get_validation_attestation`](#agenttrust_get_validation_attestation) | `subject_asset`, `capability_name` OR `capability_hash`, `attestor` | Every `ValidationAttestation` PDA matching the filter |
+| [`agenttrust_list_facilitators`](#agenttrust_list_facilitators) | — | Active facilitator adapters (Pay.sh / Dexter / atxp / MCPay) + ship status |
+| [`agenttrust_demo_state`](#agenttrust_demo_state) | — | Three pre-warmed devnet counterparties used by `examples/pay-sh-demo` |
+
+### `agenttrust_get_policy`
+
+Decodes the `PolicyAccount` PDA at `["policy", agent_asset, policy_id_le]`. Returns every byte: `enabled_kinds_bitmask`, `gate_mode`, all spending fields, all velocity fields, `min_counterparty_tier`, `max_risk_score`, `min_confidence`, `default_unrated_treatment`, `required_capability_hash` (hex), `accepted_attestors[]`, `scope_kind`. Non-existent policies return `exists: false`.
+
+### `agenttrust_list_policies`
+
+Lightweight summary across `policy_id ∈ {1..10}` for the given agent. Use `get_policy` for the full decode of a specific policy.
+
+### `agenttrust_simulate_payment`
+
+Read-only `gate_payment` simulation. Same semantics as the SDK's [`gatePayment()`](/sdk/gate-payment) — invokes the lazy variant (returns decision via Anchor's return-data channel), parses the response into the `GateDecision` union.
+
+`caller` is required; pass any funded base58 pubkey. The simulation tx isn't committed, but Solana requires a fee-payer keypair. As of 0.2.1 the tool surfaces a clear actionable error if `caller` is omitted (was a cryptic `AccountNotFound` before).
+
+### `agenttrust_get_killswitch`
+
+Returns the `KillSwitchState` for the agent's per-agent kill switch (scope_kind = 2, scope_key = agent_asset) plus the `PolicyAuthority` (multisig members + threshold). Useful when debugging "why is this agent paused?".
+
+### `agenttrust_get_velocity`
+
+Decodes the `VelocityLedger` PDA at `["velocity", agent_asset, policy_id_le]`. Returns `cumulative_amount`, `last_commit_slot`, `window_start_slot`. The window-active vs window-expired check (`elapsed >= window_slots`) is a pure-fn evaluation — match the policy's `velocity_window_secs` × `tier_decay(payer_tier) × 2 slots/sec`.
+
+### `agenttrust_get_feedback_log`
+
+`FeedbackEmissionLog` lookup by `payment_id_hash`. The PDA is at `["feedback_log", payment_id_hash]`. Returns `score`, `is_dispute`, `emitted_at_slot` if found, or `exists: false`.
+
+### `agenttrust_get_quantu_reputation`
+
+Decodes Quantu's `AtomStats` at `["atom_stats", agent_asset]`. Returns:
+
+```json
+{
+  "pda":          "4z9RiK6B49QZbmqPM9yNZWgfxYD3tvQ3NETU6X89f5mv",
+  "ownerProgram": "AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF",
+  "ownerMatches": true,
+  "rawByteLen":   561,
+  "reputation": {
+    "tierImmediate":  3,
+    "tierConfirmed":  2,
+    "riskScore":      42,
+    "confidence":     8500,
+    "schemaVersion":  1
+  }
+}
+```
+
+Mirrors the canonical byte offsets from [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs) verbatim — 549 / 551 / 555 / 557 / 560. Fixed in MCP 0.2.6 (Phase Q1) after the schema-version canary at byte 560 + the `tier ≤ 4` range check were added; v0.2.5 had fabricated offsets that returned junk values.
+
+### `agenttrust_get_validation_attestation`
+
+Returns every `ValidationAttestation` PDA matching `(subject_asset, capability_name OR capability_hash)`, optionally filtered by `attestor`. Accepts the friendly capability name (the SDK computes SHA-256 internally) or the 64-char hex hash. Added in 0.2.4 — real LLMs typically have the human-readable name; requiring the digest was a friction point.
+
+### `agenttrust_list_facilitators`
+
+Returns the active adapter set: Pay.sh (live), Dexter (in-flight), atxp (roadmap), MCPay (roadmap). Each entry includes the adapter's wire format hint and ship status.
+
+### `agenttrust_demo_state`
+
+Returns the three pre-warmed devnet counterparties used by `examples/pay-sh-demo`:
+
+| Tier | Asset pubkey | Expected gate decision |
+|---|---|---|
+| 0 (untrusted) | `C9pYqwnCVpwg7MwEbQa4XcmVVYsUcPwqHMYs999KB3dR` | `Deny(CounterpartyTierBelowMin)` |
+| 1 (low-trust) | `9894Sh7F79yDzTi4Pvfm5Jy5VmLpx2XkyhS14BFwpyrd` | `Deny(CounterpartyTierBelowMin)` |
+| 3 (Gold) | `5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y` | `Allow` (with a tier-3 policy) |
+
+The demo state is bundled in the tarball as of 0.2.3 — the published package doesn't need a separate state file.
+
+## Write (5 tools — require `KEYPAIR_B58`)
+
+| Tool | Effect |
+|---|---|
+| [`agenttrust_init_policy`](#agenttrust_init_policy) | Create `PolicyAccount` + `VelocityLedger` for the signer's agent |
+| [`agenttrust_set_killswitch`](#agenttrust_set_killswitch) | Pause / unpause the agent's `KillSwitchState` (lead-only multisig in v1) |
+| [`agenttrust_request_validation`](#agenttrust_request_validation) | Open a `ValidationRequest` PDA |
+| [`agenttrust_respond_to_validation`](#agenttrust_respond_to_validation) | Attestor writes a `ValidationAttestation` PDA |
+| [`agenttrust_emit_feedback`](#agenttrust_emit_feedback) | Facilitator-only `emit_feedback` CPI (signer must equal facilitator) |
+
+### `agenttrust_init_policy`
+
+Required args: `agent_asset`, `policy_id`, `enabled_kinds_bitmask` (e.g., `0b11111` = all five kinds). Optional: every `PolicyAccount` field — defaults are documented in [`programs/policy-vault/src/instructions/init_policy.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/init_policy.rs).
+
+### `agenttrust_set_killswitch`
+
+Required args: `agent_asset`, `paused`. Multisig-gated against `PolicyAuthority` per [KillSwitch policy](/programs/policy-vault/kill-switch-policy). v1 uses single-signer (lead-only) for hackathon-velocity reasons; v1.1+ exercises the full Kani-proven multi-signer path.
+
+### `agenttrust_request_validation`
+
+Required args: `subject_asset`, `claim_uri_hash_hex`, `deadline_slot`. The capability is implied by the active namespace context. Subject's owner OR any third party can open the request; off-chain attestors discover via the `RequestCreated` event.
+
+### `agenttrust_respond_to_validation`
+
+Required args: `subject_asset`, `claim_payload_hash_hex`, `claim_uri_hash_hex`, `expires_at_slot`. The signer (the keypair behind `KEYPAIR_B58`) is the attestor. v1 trust model: tx signature authenticates; v1.1+ adds Ed25519 sysvar verify.
+
+### `agenttrust_emit_feedback`
+
+Required args: `payment_id_hash_hex`, `payee_asset`, `base_collection`, `score`. The signer must equal the facilitator (`FacilitatorSignerMismatch` otherwise). `base_collection` is the value passed to Quantu's `register_agent` — the agent-registry-8004 collection address.
+
+## Discovery (3 tools)
+
+| Tool | Returns |
+|---|---|
+| [`agenttrust_docs`](#agenttrust_docs) | Full-text search over `docs-site/content/docs/` — ranked hits with excerpts |
+| [`agenttrust_facilitator_walkthrough`](#agenttrust_facilitator_walkthrough) | Per-adapter integration walkthrough by name |
+| [`agenttrust_explain_decision`](#agenttrust_explain_decision) | Translate a `DenyReason` code (1..15) into the enum name + remediation hint |
+
+### `agenttrust_docs`
+
+Searches the bundled docs corpus. Returns ranked hits with excerpts. Use case: an LLM asks "what's the atomic-tx invariant?" and the tool surfaces the verification page with a relevant excerpt rather than hallucinating from training data.
+
+The corpus is bundled in the tarball as of 0.2.3. `MCP_DOCS_DIR` env var lets tests point at a different root.
+
+### `agenttrust_facilitator_walkthrough`
+
+Returns the canonical guide for a named facilitator (`pay-sh`, `dexter`, `atxp`, `mcpay`, or `x402`). Falls back to the generic adapters guide for unknown names. Use case: an LLM asks "walk me through adding a new facilitator" and the tool returns the contract page.
+
+### `agenttrust_explain_decision`
+
+Maps a `DenyReason` code (`1..15`) to the canonical name + remediation hint. Same data the [Reference → DenyReason codes](/reference/deny-reason-codes) page surfaces, but tool-shaped for LLM consumption.
+
+## Validation status
+
+Phase M comprehensive E2E (2026-05-07): all 18 tools present, 10/10 read tools return live devnet state with clickable Explorer URLs, 6/6 PDAs cross-validated against on-chain ground truth, 4/4 Explorer URLs return HTTP 200. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md).
+
+Phase P real-LLM tool-routing (2026-05-08): 7/10 strict pass on natural-language scenarios via Claude `sonnet`. The three false negatives were context-gathering artefacts (the LLM called `agenttrust_demo_state` first to gather context, then the expected tool); a less agentic client would score 9/10. Full report: [`docs/proofs/phase-p-llm-routing.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-p-llm-routing.md).
+
+## Source
+
+- Read tools: [`mcp/src/tools/read/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/read)
+- Write tools: [`mcp/src/tools/write/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/write)
+- Discovery tools: [`mcp/src/tools/discovery/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/discovery)
+- Tool aggregator: [`mcp/src/tools/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/tools/index.ts)

package/dist/embedded-docs/programs/policy-vault/composer.mdx

@@ -0,0 +1,117 @@
+---
+title: Composer
+description: The pure-Rust orchestration that ties the five policy kinds together with fail-fast semantics and Allow-only state mutation.
+---
+
+`compose_decision` is the single function that runs every policy and returns the gate's verdict. The Anchor handlers (`gate_payment`, `gate_payment_strict`) are thin wrappers around it.
+
+Source: [`programs/policy-vault/src/policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs).
+
+## Signature
+
+```rust
+pub fn compose_decision(input: ComposerInput) -> ComposerResult;
+
+pub struct ComposerInput {
+    pub policy: PolicySnapshot,
+    pub ledger: VelocityLedgerSnapshot,
+    pub killswitch: KillSwitchSnapshot,
+    pub payer_atom: Option<AtomStatsView>,
+    pub payee_atom: Option<AtomStatsView>,
+    pub attestation: Option<ValidationAttestationView>,
+    pub amount: u64,
+    pub payee_agent_asset: Pubkey,
+    pub now_slot: u64,
+    pub unix_ts: i64,
+}
+
+pub struct ComposerResult {
+    pub decision: GateDecision,
+    pub spending_deltas: Option<SpendingDeltas>,
+    pub velocity_deltas: Option<VelocityDeltas>,
+}
+```
+
+The Anchor wrapper feeds the composer plain-data snapshots, never on-chain account references. That separation is what makes every policy unit-testable in plain Rust and Kani-provable without an Anchor harness.
+
+## Fail-fast order
+
+```
+KillSwitch  →  Spending  →  Velocity  →  CounterpartyTier  →  RequireValidation
+```
+
+Cheapest reads first. KillSwitch is one bool. Spending is pure arithmetic. Velocity reads one local PDA. CounterpartyTier reads two foreign `AtomStats` PDAs. RequireValidation reads one foreign `ValidationAttestation` PDA. The first policy that returns `Deny` short-circuits the rest — no foreign-PDA reads beyond the deciding policy.
+
+## State mutation rule
+
+The composer **never** mutates state. It returns *deltas* — `SpendingDeltas`, `VelocityDeltas` — that the Anchor handler applies to `PolicyAccount` and `VelocityLedger` only on the `Allow` branch.
+
+```rust
+match result.decision {
+    GateDecision::Allow => {
+        if let Some(d) = result.spending_deltas {
+            spending::apply_deltas(&mut ctx.accounts.policy_account, &d);
+        }
+        if let Some(d) = result.velocity_deltas {
+            velocity::apply_deltas(&mut ctx.accounts.velocity_ledger, &d);
+        }
+    }
+    GateDecision::Deny(_) | GateDecision::RequireValidation(_) => {
+        // Mutate nothing.
+    }
+}
+```
+
+This rule is what `velocity_counter_le_limit` (Kani #2) is inductive over: if the pre-state ledger satisfies `cumulative_amount ≤ max_in_window` and the policy returns `Allow(deltas)`, then the post-state ledger also satisfies the bound. A fresh ledger trivially satisfies the base case.
+
+## Strict variant
+
+`gate_payment_strict` converts non-`Allow` into `Err`:
+
+```rust
+pub fn gate_payment_strict(ctx: Context<GatePaymentStrict>, …) -> Result<()> {
+    let result = compose_decision(input);
+    match result.decision {
+        GateDecision::Allow => {
+            // Apply deltas, return Ok.
+            Ok(())
+        }
+        GateDecision::Deny(reason) => Err(reason.into()),
+        GateDecision::RequireValidation(_) => Err(ErrorCode::ValidationRequired.into()),
+    }
+}
+```
+
+The SDK's `composeAtomicSettleTx` calls `gate_payment_strict`. Any `Deny` on the gate fails the entire bundled transaction (`gate + transfer + emit_feedback`), which means the SPL transfer never runs and `FeedbackEmissionLog` is never created. Solana's transaction atomicity does the rest.
+
+The Phase J5 Kani proof `gate_payment_strict_correctness` pins this contract end-to-end:
+
+- `strict_returns_ok_iff_allow` — strict `Ok(())` ⇔ composer `Allow`.
+- `gate_decision_is_one_of_three_disjoint_variants` — the three `GateDecision` arms are pairwise disjoint, so a fourth variant cannot silently slip past the strict dispatch.
+
+Together: 258 sub-checks, ~0.9 s. The strict-correctness invariant is the on-chain anchor of the SDK's atomic-tx invariant.
+
+## Why pure-Rust
+
+Three reasons:
+
+1. **Kani provability.** `compose_decision` is a deterministic function over plain types. Kani's bounded model checker explores every reachable state inside the bounds in seconds. An Anchor handler with account validation, CPI, and rent calculations would not be tractable.
+2. **Unit-testability.** The same function works in `cargo test` without an Anchor program-test harness. Every policy module ships with a dense unit-test suite (Spending: 14 tests, Velocity: 14, CounterpartyTier: 13, RequireValidation: 13, KillSwitch: 2 — plus 113 module-level tests across PolicyVault).
+3. **Wrapper churn isolation.** Account-validation, IDL changes, Anchor-version bumps live in the wrapper. Decision logic doesn't move when wrappers do.
+
+## Read next
+
+<Cards>
+  <Card title="KillSwitch policy" href="/programs/policy-vault/kill-switch-policy">
+    First in the composer; one bool; multisig-gated mutation.
+  </Card>
+  <Card title="Spending policy" href="/programs/policy-vault/spending-policy">
+    Per-tx, daily (UTC), and weekly (ISO Monday) limits with anchor-rollover math.
+  </Card>
+  <Card title="Velocity policy" href="/programs/policy-vault/velocity-policy">
+    Sliding-window cumulative-spend counter with payer-tier-decayed window size.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    The strict variant is the on-chain half of the three-layer atomicity guard.
+  </Card>
+</Cards>