demo: compose capability descriptors via metaDataUrl + ANS_DNSAID

[sparkmastergrape]

Adds a small runnable demo showing that an ANS-registered agent can advertise arbitrary capabilities through the existing AgentEndpoint.metaDataUrl, pinned with metaDataHash and published as a cap locator by ANS_DNSAID. Zero code, schema, or wire changes.

Fixes #95

Addresses both points from the issue discussion

Runnable demo with a committed fixture, not a docs file — scripts/demo/payable-endpoints/, with the example card committed as testdata/agent-card.json. As you noted, a hash printed against a live card breaks as soon as that card changes, and drift is indistinguishable from a legitimate new version. The demo asserts against the fixture, so the worked example stays verifiable over time; --live fetches the real descriptor and reports a mismatch without failing, with that ambiguity spelled out as the teaching point.

Protocol-neutral framing — the README leads on metaDataUrl composing capability descriptors generally. x402 appears only as the worked example, called out as the case people most often assume needs new protocol machinery.

The expected SVCB row is recorded output, not a derivation

testdata/expected-svcb.txt was captured by running scripts/demo/start.sh against main at d8ed4bb, registering the endpoint, driving it to PENDING_DNS, and taking dns-records.sh --json verbatim:

1 . alpn=a2a port=443 key65400=https://api.dnsofmoney.com/.well-known/agent-card.json key65401=IxM_ZcwgCgb3kAnTtD5l3XQ_t9CpFBCSdKbFtanA1Bs key65402=a2a key65409=agent-card.json

verify.sh derives cap-sha256 from the fixture and asserts it against that row, so if the emit path in internal/adapter/discovery/ans/dnsaid.go changes shape the demo fails rather than agreeing with its own arithmetic. Reproduction steps are in the README.

Note that register.sh does not send metaDataHash, so the fixture was produced by POSTing /v2/ans/agents directly.

Run it

scripts/demo/payable-endpoints/verify.sh

No running stack required — it asserts against the committed fixtures.

---

Per the pay.agents question — agreed, keeping that out of scope for its own discussion.

AI assistance: Assisted-by: Claude Code (claude-opus-5)

[csnitker-godaddy]

Thanks for the quick turnaround, and incorporating the feedback from the issue. Verified the hashes and the recorded row, it all lines up. Left a few inline asks. One naming thought, your call: capability-descriptors might age better than payable-endpoints as the directory name.

Kicking off CI now.

[csnitker-godaddy]

This hardcodes your production host, and the fixture looks like a snapshot of your real card (--live is already reporting different bytes today). Live modes are a feature here, but the other demos take the host from the runner, register.sh honors AGENT_HOST and defaults to a random example.com name. Would you be open to a neutral fixture, with --live taking the descriptor URL as an argument?

[sparkmastergrape]

Done in 93df02e — the fixture is now a neutral card for agent.example.com (nothing serves it, so the offline assertion can't drift), and --live takes the descriptor URL as an argument: it fetches your card and prints its pin, cap-sha256, and the registration body you'd POST. expected-svcb.txt was re-recorded against a fresh ans-ra run with the new card's pin, same recipe as the README's reproduction section.

[csnitker-godaddy]

sha256sum isn't on stock macOS, so this dies at the dependency check there. Can you add a shasum -a 256 fallback?

[sparkmastergrape]

Added — sha256_file() prefers sha256sum and falls back to shasum -a 256, with a clear failure if neither exists.

[csnitker-godaddy]

I'd drop this line, git history already carries the provenance and it goes stale on the first re-record.

[sparkmastergrape]

Dropped.

[sparkmastergrape]

All four addressed in 93df02e:

• Neutral fixture — the card is now a generic agent at agent.example.com (nothing serves it, so the offline assertion stays deterministic), and expected-svcb.txt was re-recorded against a fresh ans-ra run with the new card's pin — same recipe as the README's "Reproducing the fixtures" section, so the asserted row is still recorded reference output rather than script-derived.
• --live takes the descriptor URL as an argument and composes a registration for it: pin, cap-sha256, and the body you'd POST.
• macOS — sha256sum falls back to shasum -a 256.
• Provenance line dropped.

Took the capability-descriptors rename too — it does age better. Ready for another CI kick whenever you are.