Docs: composing payable agent endpoints via metaDataUrl + ANS_DNSAID (no code change)

[sparkmastergrape]

Summary

An ANS-registered agent can already be made payable without adding a payment protocol, extending the schema, or touching a line of ANS code. The mechanism is the existing optional metaDataUrl on an A2A/MCP AgentEndpoint: point it at an agent descriptor that itself advertises payment (an A2A agent-card exposing x402 tools, or a /.well-known/x402 manifest), pin it with metaDataHash, and the RA publishes a cap locator through the default ANS_DNSAID discovery profile. A resolver discovers the agent by name, follows the integrity-pinned cap to the descriptor, and learns how to pay — all over machinery that ships today.

What I'd like to contribute

A single docs/pr-specs/ design-of-record doc (matching the FINDER-ard-discovery-service.md house style) that writes this composition down with a live, independently verifiable worked example (a real A2A agent-card whose metaDataHash a reviewer can reproduce with curl … | sha256sum).

Zero code and zero schema change. No new Protocol enum member, no new DiscoveryProfile, no change to the RA/TL/verifier or the wire contract. It documents existing behavior and respects the current constraints (catalog eligibility is A2A/MCP-only; metaDataUrl host must equal agentHost).

Open design question (deliberately deferred in the doc)

ANS_DNSAID publishes SVCB at the bare agent FQDN (1 .) carrying the cap locator. An operator can separately publish a payments-native discovery leaf under a service prefix (e.g. _pay._agents.<domain>) following the DNS-AID service-label convention. The doc frames that operator-published record as complementary and explicitly does not propose that ANS emit such rows or add a discovery profile for them. Whether a payments service token should ever live in the ANS_DNSAID emit path is flagged as an open question for maintainers, not resolved here.

Ask

Per CONTRIBUTING (issue-first, consensus on new material): does a docs-only contribution of this shape sound welcome before I open the PR? Happy to adjust framing or placement to fit house conventions.

[csnitker-godaddy]

Thanks @sparkmastergrape, this is a well-researched ask and you've got the details right. Speaking for myself: yes, a docs contribution of this shape sounds welcome. I'll flag it to the other maintainers, but I don't expect something with no schema impact to be controversial.

On placement, an honest caveat: there isn't much docs house style to match yet, that folder holds one design doc and an implementation plan. How this repo teaches things today is runnable demos under scripts/demo. Would it work to ship this as a small demo whose example card is committed to the repo as a fixture, with your writeup as its README? A committed fixture also keeps the worked example verifiable over time, since a printed hash breaks as soon as the live card changes, whether that's drift or a legitimate new version.

Would you also be open to framing it protocol-neutral, composing descriptors via metaDataUrl, with x402 as the worked example rather than the headline?

Agreed on deferring the pay.agents question, that can be its own discussion.