feat(challenge): emit compatible_clients in 402 agent_instructions

Mirror the node-commerce gain — add a `compatible_clients` field to the 402 body
via build_agent_instructions, derived per-rail from how_to_pay. Same default
client list, same shape, same vendor-override pattern via
BuildAgentInstructionsInput(compatible_clients={...}).

CLAUDE.md gets the symmetric documentation section + structural alignment with
node-commerce/CLAUDE.md (Examples table + peer-dep paragraph + "Every helper lifts
from production code" mantra at the top, matching node-commerce).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

CLAUDE.md

@@ -2,6 +2,8 @@
 
 Agent commerce SDK for Python. The full merchant-side toolkit: identity gating + payment helpers + 402 builders + discovery + Stripe multichain. One install, submodule imports per concern.
 
+Every helper lifts directly from working production code (`agentscore/martin-estate`) — extract from real consumers, not speculation.
+
 ## Submodules
 
 | Submodule | What it is |
@@ -25,9 +27,23 @@ Single Python package, hatchling-built, published to PyPI as `agentscore-commerc
 | `agentscore_commerce/challenge/` | 402-body builders |
 | `agentscore_commerce/stripe_multichain/` | Stripe multichain PaymentIntent helpers |
 | `agentscore_commerce/api/` | `AgentScore` re-export |
+| `examples/` | Runnable single-file FastAPI apps for each common scenario |
 | `tests/` | pytest, one file per surface |
 
-Every helper lifts from working production code (`agentscore/martin-estate`) — extract from real consumers, not speculation.
+Peer-dep pattern: payment/x402/mppx/stripe modules import lazily at runtime — vendors install only what they use via extras (`pip install agentscore-commerce[fastapi,stripe]` etc.). Underlying packages: `x402[evm,svm]`, `pympp[server,tempo,stripe]`, `stripe`. Missing peer dep raises a guiding `ImportError` with the install command.
+
+## Examples
+
+`examples/` contains full single-file FastAPI apps for the most common merchant scenarios — copy-paste templates, not frameworks:
+
+| Example | Scenario |
+|---|---|
+| `api_provider.py` | Per-call API billing on multiple rails: Tempo MPP + x402 (Base + Solana); no compliance gate |
+| `identity_only.py` | Compliance gate without payment (vendor handles their own) |
+| `multi_rail_merchant.py` | Full agent-commerce: identity + Tempo MPP + x402 + Stripe SPT |
+| `stripe_multichain_merchant.py` | Stripe-anchored multichain (PaymentIntent → tempo/base/solana deposit addresses) |
+| `variable_cost_merchant.py` | Pay-per-actual-usage on **two protocols**: x402 upto (Permit2 + Settlement-Overrides) AND MPP tempo session (channel + SSE + mid-stream vouchers) |
+| `compliance_merchant.py` | Regulated-goods merchant — full compliance gate + custom `on_denied` composing the denial helpers (`verification_agent_instructions`, `is_fixable_denial`, `build_signer_mismatch_body`, `build_contact_support_next_steps`, `denial_reason_to_body`/`denial_reason_status`) |
 
 ## Identity model
 
@@ -62,6 +78,10 @@ async def purchase(...): ...
 
 Anonymous POST flows through to the handler unauthenticated and gets a 402 with all rails + per-order pricing. Identity is verified at settle time on the retry leg (when the agent submits `X-Payment` / `Authorization: Payment`); `create_session_on_missing` still auto-mints a verification session there. The same wrap pattern works identically across all 6 framework adapters (fastapi, flask, django, aiohttp, sanic, middleware/ASGI). See `examples/multi_rail_merchant.py` and `examples/compliance_merchant.py`.
 
+### `compatible_clients` field on emitted 402s
+
+`build_agent_instructions` emits a `compatible_clients` field in the 402 body, derived automatically from `how_to_pay` — per-rail list of CLIs the AgentScore team has smoke-verified end-to-end. Vendors override with `BuildAgentInstructionsInput(compatible_clients={...})` to add their own tested clients. Set to an empty dict `{}` to suppress the default. Same data is published as `core/docs/integrations/x402-clients.mdx` for human-side rationale + per-rail commands.
+
 ## Tooling
 
 - **uv** — package manager.

agentscore_commerce/challenge/agent_instructions.py

@@ -46,6 +46,30 @@ def _default_warnings(how_to_pay: dict[str, Any]) -> list[str]:
     return w
 
 
+def _default_compatible_clients(how_to_pay: dict[str, Any]) -> dict[str, list[str]] | None:
+    """Default ``compatible_clients`` derived from the rails declared in ``how_to_pay``.
+
+    Lists clients the AgentScore team has smoke-verified end-to-end against an
+    ``agentscore-commerce`` merchant; entries appear only for rails the vendor actually
+    offers. Vendors override this in ``BuildAgentInstructionsInput(compatible_clients=...)``
+    to add their own tested clients or remove entries that don't fit their endpoint.
+
+    Verified state as of the SDK release. The same data is also published as a docs page
+    for humans (rationale, per-rail commands, why some clients don't fully work, last
+    verified date) — this default keeps the merchant-side surface in sync.
+    """
+    out: dict[str, list[str]] = {}
+    if "tempo" in how_to_pay:
+        out["tempo_mpp"] = ["agentscore-pay", "tempo request", "x402-proxy"]
+    if "x402_base" in how_to_pay:
+        out["x402_base"] = ["agentscore-pay", "x402-proxy", "purl (omit --network flag)"]
+    if "x402_solana" in how_to_pay:
+        out["x402_solana"] = ["agentscore-pay"]
+    if "stripe" in how_to_pay:
+        out["stripe"] = ["link-cli"]
+    return out or None
+
+
 @dataclass
 class BuildAgentInstructionsInput:
     how_to_pay: dict[str, Any]
@@ -54,6 +78,11 @@ class BuildAgentInstructionsInput:
     timeout_seconds: int = 300
     warnings: list[str] | None = None
     recommended: str | None = None
+    # Per-rail list of client names the merchant has verified work end-to-end.
+    # Vendors set this from their own smoke matrix — defaults to None, in which case
+    # the field is not emitted (avoids vouching for clients the merchant has not tested).
+    # Keys are rail identifiers (e.g. "x402_base", "tempo_mpp"); values are display labels.
+    compatible_clients: dict[str, list[str]] | None = None
     extra: dict[str, Any] = field(default_factory=dict)
 
 
@@ -68,6 +97,11 @@ def build_agent_instructions(input: BuildAgentInstructionsInput) -> dict[str, An
         input.recommended_tools if input.recommended_tools is not None else _default_recommended_tools(input.how_to_pay)
     )
     warnings = input.warnings if input.warnings is not None else _default_warnings(input.how_to_pay)
+    compatible_clients = (
+        input.compatible_clients
+        if input.compatible_clients is not None
+        else _default_compatible_clients(input.how_to_pay)
+    )
     out: dict[str, Any] = {
         "how_to_pay": input.how_to_pay,
         "recommended_tools": recommended_tools,
@@ -77,5 +111,7 @@ def build_agent_instructions(input: BuildAgentInstructionsInput) -> dict[str, An
     }
     if input.recommended:
         out["recommended"] = input.recommended
+    if compatible_clients:
+        out["compatible_clients"] = compatible_clients
     out.update(input.extra)
     return out