@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/reference/changelog.mdx

@@ -1,19 +1,236 @@
 ---
 title: Changelog
-description: Documentation-facing release notes for the Frontier build.
+description: Release notes for @agenttrust-sdk/trustgate and @agenttrust-sdk/mcp — auto-generated from each package's CHANGELOG.md.
 ---
 
-`In progress`
+The published packages keep their own `CHANGELOG.md` (Keep-a-Changelog format) under [`trustgate/sdk/`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/CHANGELOG.md) and [`mcp/`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/CHANGELOG.md). This page is built from those files at lint time so the docs never drift.
 
-| Date | Change |
-| --- | --- |
-| 2026-05-06 | Pay.sh adapter layer documented with SERVICE-signed challenges and proof validation. |
-| 2026-05-06 | `examples/pay-sh-demo` added as the Pay.sh + AgentTrust x402 walkthrough. |
-| 2026-05-06 | FacilitatorAdapter contract added for Pay.sh today and Dexter / atxp_ai / MCPay roadmap adapters. |
-| 2026-05-06 | Atomic settlement narrative updated: policy check, SPL transfer, and feedback stay tied to one settlement path. |
-| 2026-05-02 | PolicyVault composer and all five policies completed. |
-| 2026-05-02 | Five Kani invariants proved green in CI. |
-| 2026-05-02 | TrustGate Anchor program and Express x402 service shipped. |
-| 2026-05-02 | `@agenttrust-sdk/trustgate@0.1.0` published. |
+Phase reports (Phase F → Phase Q) live separately under [`docs/proofs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/docs/proofs); the [Live evidence](/verification/live-evidence) page indexes them.
 
-Source: [`execution.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/execution.md)
+{/* BEGIN AUTO-GEN: changelog */}
+
+> Auto-generated from upstream package `CHANGELOG.md` files at build time.
+> If you spot drift, the `mcp/` and `trustgate/sdk/` sources are authoritative.
+
+## @agenttrust-sdk/trustgate
+
+Source of truth: [`trustgate/sdk/CHANGELOG.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/CHANGELOG.md).
+
+### [Unreleased]
+
+### [0.2.0] — 2026-05-07
+
+Tag: [`sdk-v0.2.0`](https://github.com/agenttrust-labs/agenttrust/releases/tag/sdk-v0.2.0)
+· Commit: `00ca222`
+
+#### Changed (breaking)
+
+- `ProgramIds.trustgate` renamed to `ProgramIds.trustGate` (camelCase,
+  matches `policyVault`). Same value (the deployed-devnet trustgate
+  program ID) — only the field name changed. One-line consumer
+  migration: `.trustgate` → `.trustGate`.
+
+#### Added
+
+- `ProgramIds.validationRegistry` — populated by default with the
+  deployed-devnet validation-registry program ID
+  `Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`. Previously consumers
+  had to import `VALIDATION_REGISTRY_DEVNET_ID` separately; that import
+  still works but `DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry` is the
+  preferred entry point.
+
+### [0.1.1] — 2026-05-04
+
+Tag: [`sdk-v0.1.1`](https://github.com/agenttrust-labs/agenttrust/releases/tag/sdk-v0.1.1)
+· Commit: `64fe14d`
+
+#### Changed
+
+- Metadata refresh after the org rebrand to
+  [`agenttrust-labs`](https://github.com/agenttrust-labs). `homepage`,
+  `repository`, and `bugs` URLs now point at the new repo. No code
+  changes.
+
+### [0.1.0] — 2026-05-02
+
+Tag: [`sdk-v0.1.0`](https://github.com/agenttrust-labs/agenttrust/releases/tag/sdk-v0.1.0)
+· Commit: `29f9961`
+
+#### Added
+
+- Initial publish of the TrustGate SDK as a drop-in middleware for x402
+  facilitators on Solana.
+- Express middleware: `mountTrustGate(app, …)` adds `POST /verify`,
+  `POST /settle`, `POST /dispute`, `GET /receipt/:hash`.
+- Client helpers: `gatePayment`, `settle`, `dispute`.
+- Atomic-tx invariant: `AtomicityEnforced` literal-true marker +
+  `assertAtomicityEnforced` runtime guard + `composeAtomicSettleTx`
+  that bundles `gate_payment_strict + SPL transferChecked +
+  emit_feedback` into one Solana transaction.
+- ValidationRegistry surface: `register_namespace` / `register_attestor`
+  / `request_validation` / `respond_to_validation` / `revoke_validation`
+  instruction builders + PDA derivers + read fetchers.
+- PolicyVault surface: `simulateGatePayment`, `parseGateDecision`, all
+  PDA derivers (`derivePolicyPda`, `deriveVelocityPda`,
+  `deriveKillSwitchPda`, `deriveFeedbackLogPda`,
+  `deriveTrustGateAuthorityPda`).
+- Quantu helpers: `deriveAgentAccountPda`, `deriveAtomStatsPda`,
+  `deriveQuantuFeedbackAccounts`, `DEFAULT_DEVNET_QUANTU_IDS`,
+  `MAINNET_QUANTU_IDS`.
+- Production factories: `makeValidateOnChainTx`, `makeEmitFeedbackCpi`,
+  `makePriorEmissionLookup`.
+
+## @agenttrust-sdk/mcp
+
+Source of truth: [`mcp/CHANGELOG.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/CHANGELOG.md).
+
+### [Unreleased]
+
+#### Planned
+
+- `agenttrust_lookup_feedback_by_tx({ tx_signature })` — resolve a Solana
+  transaction signature to its `emit_feedback` payment_id_hash by parsing
+  the tx's inner instructions. Useful when an integrator has the settle
+  signature but not the digest. Targeted for v0.3.0.
+
+### [0.2.6] — 2026-05-08
+
+Tag: `mcp-v0.2.6` · Phase Q1 — fixes the only data-correctness bug Phase P uncovered. The MCP catalog now produces correct on-chain values for every tool that returns data.
+
+#### Fixed
+
+- `agenttrust_get_quantu_reputation` was reading Quantu `AtomStats` at fabricated byte offsets (`40 / 41 / 49 / 50 / 51`) and returning bogus values — Phase P E2E showed `tier: 164` for an actually-tier-0 agent, plus a u64-max-ish `feedbackCount` that was junk re-interpretation of the asset-pubkey region. The PDA address, owner, and account size were correct; only the field decoding was wrong.
+
+  0.2.6 mirrors the canonical offsets from `programs/policy-vault/src/ext/atom_engine.rs` verbatim:
+
+  | offset | width | field            |
+  |-------:|------:|------------------|
+  |    549 |   u8  | `risk_score`     |
+  |    551 |   u8  | `tier_immediate` |
+  |    555 |   u8  | `tier_confirmed` |
+  |    557 |   u16 LE | `confidence`  |
+  |    560 |   u8  | `schema_version` (canary, must equal 1) |
+
+  Adds the schema-version canary at byte 560 and the `tier ≤ ATOM_TIER_MAX = 4` range check the on-chain parser uses, so a future Quantu layout change fails loud rather than silently emitting garbage.
+
+#### Changed (breaking, response shape)
+
+- `agenttrust_get_quantu_reputation` response `reputation` block now contains:
+  - `tierImmediate` (number, 0..=4) — v1 fast-path tier; what `CounterpartyTier` reads in v1 demo mode
+  - `tierConfirmed` (number, 0..=4) — post-vesting tier; production policies prefer this
+  - `riskScore` (number, 0..=255 — lower is better)
+  - `confidence` (number, 0..=10_000 basis points)
+  - `schemaVersion` (number, always 1 in v1)
+- Removed `feedbackCount` and `averageScore` — those fields were not in the canonical `AtomStats` struct; values were nonsense reinterpretations of unrelated bytes.
+- Added an `error` field on the top-level response when the schema-version canary or size check fails — populated in place of `reputation`.
+
+#### Tests
+
+- `mcp/test/tools/read/get-quantu-reputation.test.ts` now asserts the canonical offsets match the on-chain Rust source exactly, plus 8 byte-level decode cases (zero-state, populated state, undersized buffer, schema-version mismatch, tier overflow on both fields, boundary case at `ATOM_TIER_MAX`, u16-LE confidence reads in the correct byte order).
+
+### [0.2.5] — 2026-05-08
+
+Tag: `mcp-v0.2.5` · Phase O — description copy polish surfaced by the Phase N+ real-user UX pass.
+
+#### Changed
+
+- Tool descriptions no longer reference internal repo paths. `agenttrust_demo_state`, `agenttrust_docs`, and `agenttrust_emit_feedback`'s `base_collection` arg now read as standalone product copy without `examples/pay-sh-demo/...` / `docs-site/content/docs/...` leaks. Resource `name` fields under `agenttrust://examples/*` use human-readable labels ("pay-sh-demo README" instead of `examples/pay-sh-demo/README.md`).
+- `agenttrust_emit_feedback.base_collection` description now points production integrators at their Quantu agent-registry collection address (the value passed to `agent_registry::register_agent`), not just at demo state.
+- `agenttrust_demo_state` error message — when the bundled snapshot is unreachable — drops the internal path and explains that the published package bundles it; only mentions `PAY_SH_DEMO_STATE_FILE` as the override hook.
+
+No behaviour changes; tools/list output cleaner for Claude Desktop / Cursor / any LLM doing tool-routing from natural-language questions.
+
+### [0.2.4] — 2026-05-07
+
+Tag: `mcp-v0.2.4` · UX-pass fix: real-user audit found `agenttrust_get_validation_attestation` requires a 64-char hex `capability_hash` while its sibling `agenttrust_request_validation` accepts the friendly `capability_name`. Real users / LLMs typically have the human-readable capability name; requiring the digest was a Claude-Desktop-level friction point.
+
+#### Added
+
+- `agenttrust_get_validation_attestation` now accepts either `capability_name` (preferred — the SDK computes SHA256(name)) or `capability_hash`. At least one is required; `capability_name` wins when both are passed. Mirrors the existing `agenttrust_request_validation` ergonomics.
+
+### [0.2.3] — 2026-05-07
+
+Tag: `mcp-v0.2.3` · Path-resolution fix follow-up to 0.2.2.
+
+#### Fixed
+
+- 0.2.2 bundled the embedded-docs / embedded-examples assets correctly but the consumer `path.resolve(__dirname, "…")` had an off-by-one — `dist/tools/discovery/__dirname + "../../../embedded-docs"` resolved to `<package-root>/embedded-docs`, missing the `dist/` segment. Files were in the tarball but the loaders couldn't find them. Three relative paths corrected (discovery/docs.ts, discovery/facilitator-walkthrough.ts, resources/docs.ts). Fresh `npx` install now returns full corpus + walkthrough content.
+
+### [0.2.2] — 2026-05-07
+
+Tag: `mcp-v0.2.2` · Phase N — Phase M E2E surfaced three bugs; this release closes all three plus the SERVER_VERSION fix that landed in 0.2.1.
+
+#### Fixed
+
+- `agenttrust_demo_state` no longer reports `available: false` on a fresh `npx` install. The build script now bundles the live devnet JSON snapshots (counterparties, demo-policies, smoke, attestor-trace, namespaces, chained-validation) into `dist/embedded-data/`. The tool prefers the bundled path; a local clone still wins the source-of-truth `examples/.../...json` lookup. (Phase M Bug #2)
+- `agenttrust_docs` now returns ranked hits from the full MDX corpus (27 pages) on `npx` installs. The build script materialises `docs-site/content/docs/**/*.mdx` into `dist/embedded-docs/`; the doc loader prefers that directory and falls back to the live tree on a local clone. The `agenttrust://docs/*` resource scheme works the same way. (Phase M Bug #3)
+- `agenttrust_facilitator_walkthrough` reads its source MDX + the trustgate facilitators README from `dist/embedded-docs/` first; no more "no walkthrough bundled" responses. (Phase M Bug #3)
+- The `agenttrust://examples/*` resource scheme now reads from `dist/embedded-examples/` (READMEs + `src/*.ts` for both pay-sh-demo and attestor-demo). (Phase M Bug #3)
+- HTTP transport now spins up one `Server` + `StreamableHTTPServerTransport` pair per `Mcp-Session-Id` instead of a singleton. Concurrent clients no longer interfere; second `initialize` no longer errors `-32600 Server already initialized`. Idle sessions evict after 30 minutes. (Phase M Bug #4)
+
+#### Changed
+
+- Build pipeline: `pnpm --filter ./mcp run build` now runs `tsc && node scripts/copy-embedded-assets.js`. The copy script prints a per-bucket count summary so regressions in the bundled set are visible at build time.
+
+#### Note
+
+The bundled `dist/embedded-docs/` is a **publish-time snapshot**. The live docs at `docs.agenttrust.tech` evolve independently — clients that need fresh docs should set `MCP_DOCS_DIR` to a checkout's `docs-site/content/docs/` directory, or use the hosted MCP at `mcp.agenttrust.tech` (redeployed on every `main` push).
+
+### [0.2.1] — 2026-05-07
+
+Tag: `mcp-v0.2.1` · `simulate_payment` clearer error when no caller / KEYPAIR_B58 set.
+
+#### Fixed
+
+- `agenttrust_simulate_payment` returns an actionable error ("requires a funded fee-payer on devnet — pass `caller` or set `KEYPAIR_B58`") instead of cryptic `AccountNotFound` when neither input is provided. Phase M E2E driver verified the fix via stdio + HTTP.
+- `serverInfo.version` now reads from `package.json` so MCP clients see the same version as `npm view`. Previously hardcoded to `0.1.0` — drifted across 0.1.0 → 0.2.0 → 0.2.1.
+
+### [0.2.0] — 2026-05-07
+
+Tag: [`mcp-v0.2.0`](https://github.com/agenttrust-labs/agenttrust/releases/tag/mcp-v0.2.0)
+· Commit: `00ca222`
+
+#### Changed
+
+- Re-pinned the `@agenttrust-sdk/trustgate` dep from `workspace:*` to
+  `workspace:^`, so the published tarball ranges to `^0.2.0` (matches
+  the SDK's own 0.2.0 bump). MCP code itself swept to the renamed
+  `programs.trustGate` field + the new `programs.validationRegistry`
+  field that the SDK 0.2.0 release added.
+- `AgentTrustConfig.validationRegistryId` (top-level field) folded into
+  `AgentTrustConfig.programs.validationRegistry` — single source of
+  truth, matches the SDK's `ProgramIds` shape. The
+  `VALIDATION_REGISTRY_PROGRAM_ID` env override is unchanged.
+
+No new tools, no protocol-conformance changes — every MCP tool surface
+behaves identically to 0.1.0. 76 unit tests + 21 protocol-conformance
+checks still green.
+
+### [0.1.0] — 2026-05-04
+
+Tag: [`mcp-v0.1.0`](https://github.com/agenttrust-labs/agenttrust/releases/tag/mcp-v0.1.0)
+· Commit: `66d4f04`
+
+#### Added
+
+- Initial publish of the AgentTrust MCP server. 18 tools across three
+  categories:
+  - **Read** (10): `get_policy`, `get_velocity_ledger`, `get_killswitch`,
+    `get_authority`, `get_feedback_log`, `get_capability_namespace`,
+    `get_attestor_profile`, `get_validation_request`,
+    `get_validation_attestation`, `simulate_gate_payment`.
+  - **Write** (5): `init_authority`, `init_killswitch`, `set_killswitch`,
+    `request_validation`, `respond_to_validation`, `emit_feedback`.
+  - **Discovery** (3): `list_facilitators`, `health`, plus an MCP
+    resource at `agenttrust://programs` exposing program IDs and
+    explorer URLs.
+- Two transports: stdio (default; `npx -y @agenttrust-sdk/mcp`) and
+  HTTP (`MCP_TRANSPORT=http MCP_HTTP_PORT=8765`).
+- Bundled IDLs for `policy_vault`, `trustgate`, `validation_registry`
+  so the server boots against a freshly-redeployed program before
+  `anchor idl init` lands.
+- Optional signer via `KEYPAIR_B58` for write tools; read tools work
+  with no env beyond defaults.
+- Network selection via `NETWORK=solana-devnet | solana-mainnet`.
+
+{/* END AUTO-GEN: changelog */}

package/dist/embedded-docs/reference/deny-reason-codes.mdx

@@ -0,0 +1,86 @@
+---
+title: DenyReason codes
+description: All fifteen DenyReason discriminants the gate can return — code, name, originating policy, remediation hint.
+---
+
+`DenyReason` is the enum returned in the `Deny` arm of `GateDecision`. The Borsh wire format follows declaration order, but clients consume the stable numeric `code()` instead — it is decoupled from Borsh field order.
+
+```rust
+pub enum GateDecision {
+    Allow,
+    Deny(DenyReason),
+    RequireValidation([u8; 32]),
+}
+```
+
+Source: [`programs/policy-vault/src/state/decision.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/decision.rs).
+
+## All fifteen codes
+
+| Code | Variant | Originating policy | What triggered it | Remediation |
+|---:|---|---|---|---|
+| 1 | `KillSwitchEngaged` | [KillSwitch](/programs/policy-vault/kill-switch-policy) | Agent's `KillSwitchState.paused == true` | Multisig-call `set_killswitch(paused=false)` |
+| 2 | `SpendingPerTxExceeded` | [Spending](/programs/policy-vault/spending-policy) | `amount > spending_per_tx_max` | Lower the amount or raise the per-tx cap |
+| 3 | `SpendingDailyExceeded` | Spending | `today_used + amount > spending_daily_max` (UTC midnight rollover) | Wait for daily reset or raise the daily cap |
+| 4 | `SpendingWeeklyExceeded` | Spending | `week_used + amount > spending_weekly_max` (ISO Monday rollover) | Wait for weekly reset or raise the weekly cap |
+| 5 | `VelocityWindowExceeded` | [Velocity](/programs/policy-vault/velocity-policy) | `cumulative_amount + amount > velocity_max_in_window` (within sliding window) | Wait for window expiry (`window_secs × tier_decay × 2 slots/sec`) or raise the cap |
+| 6 | `CounterpartyTierBelowMin` | [CounterpartyTier](/programs/policy-vault/counterparty-tier-policy) | Payee's `tier < min_counterparty_tier` (per `gate_mode`) | Build payee reputation via Quantu's `give_feedback`, or lower `min_tier`, or switch from `IMMEDIATE` to `CONFIRMED` |
+| 7 | `CounterpartyRiskAboveMax` | CounterpartyTier | Payee's `risk_score > max_risk_score` (when constraint active) | Use a different payee or relax `max_risk_score` |
+| 8 | `CounterpartyConfidenceBelow` | CounterpartyTier | Payee's `confidence < min_confidence` (basis points; when constraint active) | Wait for more reputation samples on the payee, or relax `min_confidence` |
+| 9 | `AtomStatsWrongOwner` | CounterpartyTier (defensive) | Payee's `AtomStats` PDA is not owned by Quantu's `atom-engine` | Check the program ID; this is fail-loud against tampering or the wrong cluster |
+| 10 | `AtomStatsSchemaMismatch` | CounterpartyTier (defensive) | Size mismatch (`!= 561`), schema-version canary (`byte 560 != 1`), OR tier byte > `ATOM_TIER_MAX = 4` | Quantu may have bumped its layout — check `bfb09ad` pin |
+| 11 | `AttestationMissing` | [RequireValidation](/programs/policy-vault/require-validation-policy) | Attestation PDA's `subject_asset` or `capability_hash` doesn't match the expected values | Re-issue the attestation against the correct subject/capability |
+| 12 | `AttestationExpired` | RequireValidation | `expires_at != 0 AND expires_at <= now_slot` | Refresh the attestation via `respond_to_validation` with a future `expires_at` |
+| 13 | `AttestationRevoked` | RequireValidation | Attestation's `revoked == true` | Re-attest if appropriate, or use a different attestor |
+| 14 | `AttestationAttestorRejected` | RequireValidation | Attestation issued by an attestor not in the policy's `accepted_attestors[]` | Use an attestor on the whitelist, or update the policy's whitelist |
+| 15 | `UnratedTreatmentDeny` | CounterpartyTier (Unrated → Deny resolution) | Payee's `AtomStats` is uninitialised AND policy's `default_unrated_treatment == UNRATED_DENY` | Initialise the payee's `AtomStats` (typically by routing one feedback through them), or change the policy's `default_unrated_treatment` to `UNRATED_ALLOW` or `UNRATED_REQUIRE_VALIDATION` |
+
+## SDK consumption
+
+```ts
+import type { GateDecision, DenyReasonCode } from "@agenttrust-sdk/trustgate";
+import { denyReasonName } from "@agenttrust-sdk/trustgate";
+
+const decision: GateDecision = await gatePayment(/* … */);
+
+if (decision.kind === "Deny") {
+  // decision.reasonCode: DenyReasonCode (number, 1..=15)
+  // decision.reasonName: string (e.g., "CounterpartyTierBelowMin")
+  // Both populated automatically; reasonName == denyReasonName(reasonCode).
+}
+```
+
+The decision union is documented in [SDK → gatePayment](/sdk/gate-payment).
+
+## x402 response shape
+
+For a `Deny`, the SDK's `mountTrustGate` middleware emits:
+
+```http
+HTTP/1.1 402 Payment Required
+X-Agent-Trust-Decision: Deny
+X-Payment-Required: denied
+X-Payment-Reason-Code: 6
+X-Payment-Reason-Name: CounterpartyTierBelowMin
+X-Payment-Network: solana-devnet
+```
+
+Headers are built via `buildHeadersForDecision` in [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts).
+
+## MCP tool
+
+The MCP server exposes `agenttrust_explain_decision({ reason_code })` — translates `1..15` into the canonical name + remediation hint. Same data as this page, but tool-shaped for LLM consumption: [MCP → Tools](/mcp/tools#agenttrust_explain_decision).
+
+## Read next
+
+<Cards>
+  <Card title="Composer" href="/programs/policy-vault/composer">
+    The fail-fast order that determines which reason code surfaces.
+  </Card>
+  <Card title="gatePayment" href="/sdk/gate-payment">
+    The SDK call that returns the decision union.
+  </Card>
+  <Card title="Adversarial harness" href="/verification/adversarial-harness">
+    Hostile-scenario tests asserting each defensive reason code.
+  </Card>
+</Cards>

package/dist/embedded-docs/reference/devnet-program-ids.mdx

@@ -1,9 +1,9 @@
 ---
 title: Devnet program IDs
-description: Current AgentTrust devnet deployment addresses.
+description: Deployed AgentTrust program addresses on Solana devnet, with Explorer links and Anchor IDL fetch instructions.
 ---
 
-These are the pinned devnet program IDs for the Frontier build.
+The pinned devnet deployment of the three AgentTrust programs. The SDK ships these as `DEFAULT_DEVNET_PROGRAM_IDS`.
 
 <ProgramIdsTable />
 
@@ -11,14 +11,56 @@ These are the pinned devnet program IDs for the Frontier build.
 
 ```ts
 import { DEFAULT_DEVNET_PROGRAM_IDS } from "@agenttrust-sdk/trustgate";
+
+DEFAULT_DEVNET_PROGRAM_IDS.policyVault;          // PublicKey
+DEFAULT_DEVNET_PROGRAM_IDS.trustGate;            // PublicKey (camelCase as of 0.2.0)
+DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry;   // PublicKey (new in 0.2.0)
 ```
 
-The SDK currently exposes PolicyVault and TrustGate by default. ValidationRegistry is read by PolicyVault through its account parser and is listed here for deploy verification.
+Note: as of SDK 0.2.0, `ProgramIds.trustgate` (lowercase) was renamed to `ProgramIds.trustGate` (camelCase) to match `policyVault`. The new `validationRegistry` field is populated by default. Migration: search-and-replace `.trustgate` → `.trustGate`. See [Reference → Changelog](/reference/changelog).
 
 ## Anchor declarations
 
-| Program | Source |
-| --- | --- |
-| `policy_vault` | `programs/policy-vault/src/lib.rs` |
-| `trustgate` | `programs/trustgate/src/lib.rs` |
-| `validation_registry` | `programs/validation-registry/src/lib.rs` |
+| Program | Source | Devnet ID |
+|---|---|---|
+| `policy_vault` | [`programs/policy-vault/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/lib.rs) | `8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR` |
+| `trustgate` | [`programs/trustgate/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/lib.rs) | `HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N` |
+| `validation_registry` | [`programs/validation-registry/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/lib.rs) | `Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv` |
+
+## Verify executable status
+
+```bash
+for p in 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR \
+         HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N \
+         Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv; do
+  solana program show "$p" --url devnet | grep Executable
+done
+```
+
+## Fetch IDLs
+
+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 SDK's `loadPolicyVault` / `loadTrustGate` / `loadValidationRegistry` fetch the IDL from chain by default. Pass an explicit `idl` argument to use a bundled snapshot — useful for latency-sensitive paths or freshly-redeployed programs.
+
+Latest evidence snapshot (SHA-256 hashes + instruction counts): [`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="Mainnet program IDs" href="/reference/mainnet-program-ids">
+    Quantu's pinned mainnet IDs that PolicyVault reads from.
+  </Card>
+  <Card title="Discriminator constants" href="/reference/discriminator-constants">
+    PDA seed prefixes + give_feedback discriminator.
+  </Card>
+  <Card title="Live evidence" href="/verification/live-evidence">
+    Every load-bearing claim with an Explorer URL.
+  </Card>
+</Cards>

package/dist/embedded-docs/reference/discriminator-constants.mdx

@@ -1,16 +1,110 @@
 ---
 title: Discriminator constants
-description: Pinned instruction and account constants used across AgentTrust.
+description: Pinned instruction discriminators, PDA seed prefixes, and account size canaries used across AgentTrust.
 ---
 
-`In progress`
+The constants below are the load-bearing discriminators and seeds AgentTrust depends on. Anything that drifts here breaks downstream tooling.
 
-| Constant | Value |
-| --- | --- |
-| Quantu `give_feedback` discriminator | `[145, 136, 123, 3, 215, 165, 98, 41]` |
-| TrustGate authority seed | `trustgate_auth` |
-| Feedback log seed | `feedback_log` |
-| Capability namespace seed | `capability` |
-| Validation attestation parser size | `290` bytes |
+## Quantu CPI discriminator
 
-Sources: [`programs/trustgate/src/ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs), [`programs/validation-registry/src/state`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/validation-registry/src/state)
+| Value | Notes |
+|---|---|
+| `[145, 136, 123, 3, 215, 165, 98, 41]` | `agent_registry_8004::give_feedback` 8-byte instruction discriminator. TrustGate's `emit_feedback` and `dispute_payment` invoke this via `invoke_signed`. |
+
+Source: [`programs/trustgate/src/ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs). Pinned to Quantu commit `bfb09ad`.
+
+## AgentTrust PDA seed prefixes
+
+| Program | Seed prefix | Seeds | What it identifies |
+|---|---|---|---|
+| `policy_vault` | `b"policy"` | `["policy", agent_asset, policy_id_le]` | `PolicyAccount` |
+| `policy_vault` | `b"velocity"` | `["velocity", agent_asset, policy_id_le]` | `VelocityLedger` |
+| `policy_vault` | `b"killswitch"` | `["killswitch", &[scope_kind], scope_key]` | `KillSwitchState` |
+| `policy_vault` | `b"policy_authority"` | `["policy_authority", agent_asset]` | `PolicyAuthority` |
+| `trustgate` | `b"trustgate_auth"` | `["trustgate_auth", facilitator]` | `TrustGateAuthority` |
+| `trustgate` | `b"feedback_log"` | `["feedback_log", payment_id_hash]` | `FeedbackEmissionLog` |
+| `validation_registry` | `b"capability"` | `["capability", capability_hash]` | `CapabilityNamespace` |
+| `validation_registry` | `b"attestor"` | `["attestor", attestor_pubkey]` | `AttestorProfile` |
+| `validation_registry` | `b"request"` | `["request", subject_asset, capability_hash, requester]` | `ValidationRequest` |
+| `validation_registry` | `b"attestation"` | `["attestation", subject_asset, capability_hash, attestor]` | `ValidationAttestation` |
+
+The SDK exposes derivers for every PDA: [SDK → Exports reference](/sdk/exports-reference#pda-derivers--anchor-loaders).
+
+## Account size canaries
+
+| Account | Size | Source |
+|---|---:|---|
+| `PolicyAccount` | 240 | [`policy_account.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_account.rs) |
+| `VelocityLedger` | 80 | [`velocity_ledger.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/velocity_ledger.rs) |
+| `KillSwitchState` | 96 | [`kill_switch_state.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/kill_switch_state.rs) |
+| `PolicyAuthority` | 272 | [`policy_authority.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_authority.rs) |
+| `TrustGateAuthority` | 104 | [`trustgate_authority.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/state/trustgate_authority.rs) |
+| `FeedbackEmissionLog` | 72 | [`feedback_emission_log.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/state/feedback_emission_log.rs) |
+| `ValidationAttestation` | 290 | [`validation_attestation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/validation_attestation.rs) |
+| `AtomStats` (Quantu) | 561 | upstream-pinned at commit `bfb09ad`; canary at byte 560 |
+
+Sizes are validated at parse time — a size mismatch fails loud rather than silently misread.
+
+## TrustGate `emit_feedback` field bounds
+
+| Field | Limit | Error |
+|---|---:|---|
+| `score` | ≤ 100 | `ScoreOutOfRange` |
+| `tag1` | ≤ 32 bytes | `TagTooLong` |
+| `tag2` | ≤ 32 bytes | `TagTooLong` |
+| `endpoint` | ≤ 64 bytes | `EndpointTooLong` |
+| `feedback_uri` | ≤ 256 bytes | `UriTooLong` |
+
+`DISPUTE_SCORE` (the score `dispute_payment` hard-codes for negative feedback) lives at [`programs/trustgate/src/constants.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/constants.rs).
+
+## ValidationRegistry name + URI bounds
+
+| Field | Limit | Error |
+|---|---:|---|
+| `CapabilityNamespace.name` | min 3, max 32 bytes; no `':'` | `NameTooShort` / `NameTooLong` / `NamespaceColonForbidden` |
+| `CapabilityNamespace.version` | ≤ 16 bytes | `VersionTooLong` |
+| `CapabilityNamespace.schema_uri` | ≤ 160 bytes | `UriTooLong` |
+| `AttestorProfile.display_name_uri` | ≤ 100 bytes | `UriTooLong` |
+
+## PolicyVault constants module
+
+Bitmask flags for `PolicyAccount.enabled_kinds_bitmask`:
+
+| Flag | Value | Policy |
+|---|---:|---|
+| `KIND_KILLSWITCH` | `0b00001` (1) | KillSwitch |
+| `KIND_SPENDING` | `0b00010` (2) | Spending |
+| `KIND_VELOCITY` | `0b00100` (4) | Velocity |
+| `KIND_COUNTERPARTY_TIER` | `0b01000` (8) | CounterpartyTier |
+| `KIND_REQUIRE_VALIDATION` | `0b10000` (16) | RequireValidation |
+
+`gate_mode` enum:
+
+| Value | Constant | Reads |
+|---:|---|---|
+| `0` | `GATE_MODE_IMMEDIATE` | `AtomStats.tier_immediate` (byte 551) |
+| `1` | `GATE_MODE_CONFIRMED` | `AtomStats.tier_confirmed` (byte 555) |
+
+`default_unrated_treatment` enum:
+
+| Value | Constant | Composer maps to |
+|---:|---|---|
+| `0` | `UNRATED_DENY` | `Deny(UnratedTreatmentDeny)` (code 15) |
+| `1` | `UNRATED_ALLOW` | `Allow` |
+| `2` | `UNRATED_REQUIRE_VALIDATION` | `RequireValidation(capability_hash)` |
+
+Constants module: [`programs/policy-vault/src/constants.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/constants.rs).
+
+## Read next
+
+<Cards>
+  <Card title="Byte-offset reference" href="/reference/byte-offset-reference">
+    Per-account byte-offset tables.
+  </Card>
+  <Card title="Devnet program IDs" href="/reference/devnet-program-ids">
+    Deployed program addresses on devnet.
+  </Card>
+  <Card title="DenyReason codes" href="/reference/deny-reason-codes">
+    The 15 reason codes the gate can return.
+  </Card>
+</Cards>

package/dist/embedded-docs/reference/mainnet-program-ids.mdx

@@ -1,16 +1,100 @@
 ---
 title: Mainnet program IDs
-description: Quantu program IDs used by AgentTrust on Solana mainnet.
+description: Quantu's pinned mainnet program IDs that PolicyVault reads via byte-offset parsers — and AgentTrust's mainnet deployment posture.
 ---
 
-`In progress`
+AgentTrust's three programs are deployed on Solana **devnet** for v1 (the Frontier 2026 build). Mainnet deployment is post-hackathon. PolicyVault reads Quantu's mainnet program IDs via the byte-offset parser pinned to commit `bfb09ad`.
 
-AgentTrust currently targets its own programs on devnet and reads Quantu trust data from the Quantu registry and Atom engine IDs below.
+## Quantu mainnet IDs
 
 | Program | Mainnet ID |
-| --- | --- |
+|---|---|
 | `agent-registry-8004` | `8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ` |
 | `atom-engine` | `AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb` |
 
-Source: [`docs/plan/research/02-quantu-erc8004-archaeology.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/plan/research/02-quantu-erc8004-archaeology.md)
+These are the addresses Quantu Labs published in their `8004-solana` repository. Both programs are MIT-licensed. AgentTrust pins to commit `bfb09ad` for the byte-offset reads — bumping that commit pin is documented inline at [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs).
 
+## TypeScript constants
+
+```ts
+import { MAINNET_QUANTU_IDS } from "@agenttrust-sdk/trustgate";
+
+MAINNET_QUANTU_IDS.agentRegistry8004; // PublicKey
+MAINNET_QUANTU_IDS.atomEngine;        // PublicKey
+```
+
+For devnet:
+
+```ts
+import { DEFAULT_DEVNET_QUANTU_IDS } from "@agenttrust-sdk/trustgate";
+```
+
+Source: [`trustgate/sdk/src/quantu.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/quantu.ts).
+
+## AgentTrust mainnet posture
+
+The AgentTrust programs target mainnet redeploy as a post-Frontier deliverable. The byte-offset parsers and the SDK's `ProgramIds` config already accept mainnet overrides — the SDK is mainnet-ready; the programs aren't deployed there yet.
+
+Override the program IDs for a mainnet redeploy:
+
+```ts
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+import { PublicKey } from "@solana/web3.js";
+
+await mountTrustGate(app, {
+  rpcUrl:             "https://api.mainnet-beta.solana.com",
+  facilitatorKeypair: /* … */,
+  programIds: {
+    policyVault:        new PublicKey("<your mainnet policy_vault>"),
+    trustGate:          new PublicKey("<your mainnet trustgate>"),
+    validationRegistry: new PublicKey("<your mainnet validation_registry>"),
+  },
+  network:            "solana-mainnet",
+  atomicityEnforced:  true,
+});
+```
+
+Each program is `cluster`-agnostic — the build artefact is the same; only the deploy target changes.
+
+## Verifying Quantu's mainnet deployment
+
+```bash
+solana program show 8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ --url mainnet-beta | grep Executable
+solana program show AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb --url mainnet-beta | grep Executable
+```
+
+PolicyVault's mainnet `AtomStats` reads target `AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb`. Devnet uses `AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF` (different ID). The byte layout (561 bytes, schema-version canary at byte 560) is identical across clusters.
+
+Reference: [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs).
+
+## Localnet validator clones
+
+For local testing, the Anchor validator clones Quantu's mainnet programs into the localnet:
+
+```toml
+# Anchor.toml
+[test.validator]
+url = "https://api.mainnet-beta.solana.com"
+
+[[test.validator.clone]]
+address = "8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ"
+
+[[test.validator.clone]]
+address = "AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb"
+```
+
+`anchor test --validator legacy` then exercises the full flow against real Quantu state without devnet RPC dependencies.
+
+## Read next
+
+<Cards>
+  <Card title="Devnet program IDs" href="/reference/devnet-program-ids">
+    Deployed AgentTrust + Quantu IDs on devnet.
+  </Card>
+  <Card title="Quantu agent registry" href="/reference/quantu-agent-registry">
+    The CPI surface PolicyVault + TrustGate consume.
+  </Card>
+  <Card title="Byte-offset reference" href="/reference/byte-offset-reference">
+    The byte-precise reads PolicyVault performs.
+  </Card>
+</Cards>