Add public/llms.txt: a guide for agents browsing the shop

[thisispav]

What

public/llms.txt, served at https://shop.pubky.app/llms.txt (today that path returns the app shell). One URL an agent with plain fetch can start from to browse the shop: base URLs, the index's own OpenAPI as the full reference, five worked recipes with real production responses, and the rules that trip agents up. Read-only; it tells agents they cannot buy and gives them the listing/shop/drop links to hand a person. 236 lines.

Follows Chris's brief after his review of a local MCP server I'd built: the index is already public, no-key and self-documenting, so a hosted guide beats a mirror that drifts.

Why public/

Static files in public/ are served ahead of the catch-all route: https://shop.pubky.app/manifest.json returns JSON today, so /llms.txt will return the file.

Acceptance test

A fresh agent with only a fetch tool and no prior knowledge, given the single URL (a raw copy of this file), against production:

• "What's for sale under 20,000 sats?" → ?state=active&currency=BTC&max_price=0.0002 → three 1,000-sat listings, two of them flagged as "do not buy" test listings, with links.
• "Which auctions are ending soon?" → ?sorting=ends_at&order=ascending → three auctions, all with auction_ends_at in the past while still state=active; answered "none are open for bidding right now" per the guide's rule.
• "Is this seller any good?" (gujx6qd8…) → one attested 5-star review (attestor = production Shop attestor), on a self-declared test item, six-day-old shop → "nothing negative, not enough to judge".

All three correct with working links. The agent's list of 11 gaps in the first draft was folded in (auction price_amount_minor = starting price, /reviews shape, state=active rule, histogram order, unvalidated country_code, the empty-auctions case). Full transcript: https://github.com/thisispav/pubky-shop-mcp/blob/main/acceptance-2026-09-28.md

Notes

• The index base URL is the Railway host for now. A stable alias (e.g. shop-index.pubky.app) would let the guide name one URL forever; asked separately.
• The currency example in the Nexus route docs says SAT; currency=SAT returns nothing (listings are BTC, exponent 8). One-line doc fix: docs: currency filter example is BTC, not SAT pubky-nexus#17.

🤖 Generated with Claude Code

[BitcoinErrorLog]

Thanks, Pav — this landed via in-repo CI in #147 (fork PRs cannot run launch-e2e without repository secrets). Closing in favor of #147.