docs: add Agent Payment Guard brief and demo script

README.md

@@ -37,6 +37,11 @@ ProofPath provides that evidence.
 
 **What it does not do:** no real wallet, no token transfer, no custody, no private keys, no SDK, no RPC, no JWS, no EIP-712.
 
+External packaging:
+
+- [Agent Payment Guard brief](docs/agent-payment-guard-brief.md)
+- [90-second demo script](docs/agent-payment-guard-90-second-demo.md)
+
 ### Architecture
 
 ```mermaid
@@ -215,6 +220,8 @@ Reviewers can run the path locally without trusting a hidden service: start with
 - [ProofPath v0.1 landing](docs/LANDING_V0_1.md)
 - [Personal Agent Guard](examples/personal-agent-guard/)
 - [Agent Payment Guard](examples/agent-payment-guard/)
+- [Agent Payment Guard brief](docs/agent-payment-guard-brief.md)
+- [Agent Payment Guard 90-second demo](docs/agent-payment-guard-90-second-demo.md)
 - [Architecture diagrams](docs/architecture.md)
 - [Agent Payment Guard demo transcript](docs/demo-transcript-payment-guard.md)
 - [Agent Payment Guard service docs](docs/agent-payment-guard-service.md)

docs/agent-payment-guard-90-second-demo.md

@@ -0,0 +1,129 @@
+# ProofPath Agent Payment Guard — 90-second demo script
+
+## Command
+
+Run from the repository root:
+
+```bash
+bash examples/agent-payment-guard/run_mock_rail_demo.sh
+```
+
+## Spoken script
+
+**Opening — 10 seconds**
+
+ProofPath is the authorization and evidence layer for AI-agent payments.
+
+The key idea is simple: model output is a proposal, not authorization.
+
+An agent can propose a payment, but an external boundary should decide whether that payment is allowed to execute.
+
+**Step 1 — valid proposal — 15 seconds**
+
+Here the agent proposes a small USDC API payment.
+
+ProofPath checks the signed human intent envelope, policy, approved asset, budget, recipient, causal parent, payment mode, and nonce.
+
+This proposal is valid, so ProofPath returns:
+
+```text
+ACCEPT
+execution_allowed=true
+```
+
+The adapter receives that decision and forwards the payment to the mock rail. The mock rail records exactly one transaction.
+
+**Step 2 — replay attack — 15 seconds**
+
+Now we replay the same signed intent envelope.
+
+The payment still looks syntactically valid, but the nonce has already been used.
+
+ProofPath returns:
+
+```text
+BLOCK / INTENT_REPLAYED
+execution_allowed=false
+```
+
+The adapter does not call the mock rail. The mock rail transaction count stays at one.
+
+**Step 3 — recurring payment without approval — 15 seconds**
+
+Next, the agent proposes a recurring payment without required approval.
+
+ProofPath returns:
+
+```text
+HOLD / RECURRING_PAYMENT_REQUIRES_APPROVAL
+execution_allowed=false
+```
+
+Again, the adapter does not call the mock rail. The transaction count still stays at one.
+
+**Step 4 — evidence — 20 seconds**
+
+After the decisions, ProofPath exports a portable evidence bundle.
+
+The bundle includes:
+
+```text
+audit.jsonl
+replay-store.json
+payment_guard_service_config.json
+payment_policy.json
+verification_report.json
+```
+
+Then we verify the bundled audit log hash chain.
+
+The result is not just “the demo worked.” The result is a reviewable evidence trail showing:
+
+```text
+ACCEPT reached the rail.
+BLOCK did not reach the rail.
+HOLD did not reach the rail.
+The audit chain verifies.
+```
+
+**Close — 15 seconds**
+
+ProofPath does not move money.
+
+ProofPath proves whether an agent was allowed to move money.
+
+The product path is:
+
+```text
+proposal -> guard -> adapter -> rail/no rail -> audit -> evidence
+```
+
+That is the core authorization boundary for AI-agent payments.
+
+## Expected success summary
+
+```text
+[mock-rail-demo] ========================================
+[mock-rail-demo]  SUCCESS SUMMARY
+[mock-rail-demo] ========================================
+[mock-rail-demo]  ACCEPT reached mock rail via adapter
+[mock-rail-demo]  BLOCK did not reach mock rail
+[mock-rail-demo]  HOLD did not reach mock rail
+[mock-rail-demo]  evidence bundle exported
+[mock-rail-demo]  hash-chain verification passed
+[mock-rail-demo] ========================================
+```
+
+## What to point out while demoing
+
+- The model never directly executes a payment.
+- The adapter forwards only `ACCEPT` decisions.
+- `BLOCK / INTENT_REPLAYED` proves replay protection.
+- `HOLD / RECURRING_PAYMENT_REQUIRES_APPROVAL` proves approval gating.
+- The evidence bundle lets someone review the path without trusting the live service.
+
+## One-sentence takeaway
+
+```text
+ProofPath turns agent payment proposals into verifiable authorization decisions before execution.
+```

docs/agent-payment-guard-brief.md

@@ -0,0 +1,150 @@
+# ProofPath Agent Payment Guard
+
+## One-line
+
+ProofPath is the authorization and evidence layer for AI-agent payments.
+
+Shorter:
+
+```text
+We do not move money.
+We prove whether an agent was allowed to move money.
+```
+
+## Problem
+
+AI agents can propose payments, but model output is not authorization.
+
+A model can generate a payment request that looks syntactically valid while still being causally unsafe: wrong recipient, wrong budget, replayed intent, missing approval, stale mandate, or action outside the user's actual scope.
+
+Traditional payment rails answer:
+
+```text
+Can this credential move money?
+```
+
+ProofPath asks the missing question:
+
+```text
+Was this specific agent payment allowed to execute now — and can we prove why?
+```
+
+## Solution
+
+ProofPath inserts an external decision boundary before execution.
+
+The agent may propose a payment, but ProofPath decides whether that proposal becomes an executable action.
+
+```text
+proposal -> guard -> adapter -> rail/no rail -> audit -> evidence
+```
+
+## Demo path
+
+The current Agent Payment Guard demo runs this path locally:
+
+```text
+AI agent payment proposal
+  -> ProofPath Guard Service
+  -> signed intent + policy + replay checks
+  -> adapter
+  -> mock rail only if ACCEPT
+  -> hash-chained audit log
+  -> replay store
+  -> portable evidence bundle
+```
+
+Run it:
+
+```bash
+bash examples/agent-payment-guard/run_mock_rail_demo.sh
+```
+
+## What it proves
+
+```text
+ACCEPT reaches mock rail.
+BLOCK / INTENT_REPLAYED never reaches mock rail.
+HOLD / RECURRING_PAYMENT_REQUIRES_APPROVAL never reaches mock rail.
+Evidence bundle proves the path.
+```
+
+The important boundary is not the mock rail. The important boundary is the adapter:
+
+```text
+ProofPath decides.
+Adapter enforces.
+Mock rail executes only after ACCEPT.
+Evidence proves the path.
+```
+
+## Current surfaces
+
+| Surface | What it provides |
+|---|---|
+| Guard Service | Local HTTP authorization endpoint for payment proposals. |
+| Adapter | Execution boundary between ProofPath decisions and a payment rail. |
+| Mock Rail Demo | Demonstrates ACCEPT reaches rail while BLOCK/HOLD do not. |
+| Replay Store | Persistent nonce protection for signed intent envelopes. |
+| Hash-Chained Audit Log | Tamper-evident record of ACCEPT, BLOCK, and HOLD decisions. |
+| Evidence Export Bundle | Portable proof packet containing audit, replay store, config, policy, and verification report. |
+| OpenAPI Contract | Integration-ready API description for external agents and adapters. |
+
+## Integration targets
+
+### x402-style pay-per-request flow
+
+```text
+Agent wants to call paid API
+  -> prepares payment proposal
+  -> ProofPath evaluates signed intent, policy, budget, recipient, nonce
+  -> only ACCEPT reaches payment rail
+  -> audit/evidence packet records why
+```
+
+ProofPath does not replace x402-style payment rails. It sits before execution as authorization and evidence.
+
+### LangGraph / agent runtime flow
+
+```text
+Agent runtime emits payment tool call
+  -> tool call routed through ProofPath adapter
+  -> ACCEPT forwards to rail/tool
+  -> BLOCK/HOLD returns structured reason to runtime
+  -> audit/evidence remains outside model memory
+```
+
+The model can propose. The external boundary decides.
+
+### Generic agent-wallet SDK mock
+
+```text
+agent-wallet SDK call
+  -> ProofPath preflight decision
+  -> ACCEPT invokes SDK
+  -> BLOCK/HOLD never invoke SDK
+  -> evidence bundle can be reviewed offline
+```
+
+This lets wallet builders keep their rails while delegating decision proof to ProofPath.
+
+## Why now
+
+AI agents are moving from text generation to action execution. Payments are one of the highest-risk action classes because a mistaken or manipulated request can move real value.
+
+As agent payments grow, teams will need more than model guardrails. They will need external authorization, replay protection, auditability, and portable evidence.
+
+## Non-goals
+
+ProofPath Agent Payment Guard is not a wallet and not a payment processor.
+
+No real wallets, token transfers, custody, private keys, payment SDKs, RPC calls, smart contracts, KYC/AML, production compliance claims, JWS, or EIP-712 are included in this local demo.
+
+## Positioning
+
+```text
+AI agents will need payment rails.
+Payment rails need authorization.
+Authorization needs evidence.
+ProofPath provides that evidence.
+```