feat(catalog): single-source buyer prompts, docs deep links, signing metadata

[OisinKyne]

Why

Buyer-facing "how to buy" instructions were authored in three independent places: the 402 paywall page (Go string literals), the public storefront (TSX literals), and /skill.md (template funcs). They had already drifted twice — the 402 agent page taught a call path that 404s (fixed in the gateway PR), and the storefront still advertised obol buy inference --no-verify-identity, a flag the CLI removed. Every future buyer-software variant would have forked a fourth copy.

What

• internal/buyprompts is now the single authoring point for buyer instructions. It generates a machine-readable call shape (method/path/bodyKind/streaming) plus copy-paste prompts keyed by buyer-software kind (obol-agent, generic-llm, cli).
• /api/services.json entries carry a buy block (JSON Schema updated, additive). The storefront renders these prompts verbatim (with task interpolation, legacy fallback for old catalogs), the 402 page builds its prompt cards from the same package, and obol sell info's "How to buy" prefers the published block. Supporting a new kind of buying software = one new prompt key, published to every surface simultaneously.
• Docs deep links: entries gain openapiPath (key into /openapi.json paths) and docsPath (Scalar hash-routing anchor, e.g. /api#tag/agent/POST/services/x/v1/chat/completions — format centralized in the controller so consumers never hardcode it). The storefront now shows API-docs links for all offer types (was HTTP-only), and skill.md service details link the anchored docs.
• x-payment-info signing metadata: every operation now advertises accepts[] (single-payment offers included) with payTo, CAIP-2 network, atomic amount, and the asset's EIP-712 signing domain — an OpenAPI-only client can construct a valid X-PAYMENT without a second fetch of services.json. Wrong-domain signing is our top silent buyer killer.
• Scalar renderer un-staled + automated: @scalar/api-reference bumped 1.34.0 → 1.62.1 (SRI refreshed). New renovate custom manager watches the pin; postUpgradeTasks runs scripts/update-scalar-sri.sh inside the renovate branch (allow-listed via RENOVATE_ALLOWED_COMMANDS in the workflow), so bump PRs arrive with the SRI hash already correct. The script works on dev machines (openssl) and in the renovate container (node fallback, byte-identical output verified).

Testing

• New internal/buyprompts tests pin the anti-drift invariants: chat offers always teach /v1/chat/completions, all types carry all prompt keys, unknown types get safe single-shot semantics
• New OpenAPI test pins accepts[] signing metadata (payTo, CAIP-2, atomic amount, EIP-712 domain) for single-payment offers
• Generated catalogs validate against the updated JSON Schema (existing render tests)
• Storefront typechecks (tsc --noEmit); renovate regex verified to match the annotated const; SRI script round-trips to the identical hash

🤖 Generated with Claude Code

[bussyjd]

Superseded by #690.

The buyer-funnel stack (#686 → #687 → #688) and the x402 v2 PAYMENT-SIGNATURE fix (#689) are integrated into a single branch in #690, with the forwardauth.go conflict resolved keep-both and the emergent v2-metrics blind spot fixed (successful PAYMENT-SIGNATURE payments were unmetered). Whole-module build + affected suites green.

Leaving this open for the author to close in favor of #690.