docs(purch): clarify buy vs shop, add purchase safety notes

[lgalabru]

Summary

• x402/shop is discovery-only prose never named the actual purchase endpoint, so an agent following this skill called x402/shop expecting it to place an order — it just replied that shopping assistance is out of scope.
• Explicitly names POST x402/buy as the only endpoint that places/pays for a physical order, with its required fields.
• Adds spend-aware notes learned from a live run: the 402-quoted checkout price can differ substantially from the search-listed price (observed ~4x on an Amazon item), Shopify checkout can transiently 500 with no charge taken, and there is no address book (always collect shippingAddress explicitly).

Test plan

• pay catalog check providers/purch/marketplace/PAY.md — passes (one pre-existing warning unrelated to this change, about an OpenAPI summary string)

[greptile-apps]

Greptile Summary

This documentation update distinguishes product discovery from purchasing and adds safeguards for physical-order execution.

• Identifies POST x402/buy as the physical purchase endpoint and documents its required inputs.
• Directs agents to collect a shipping address for every purchase and confirm material differences between search and checkout prices.
• Documents the expected recovery behavior for transient Shopify failures.

Confidence Score: 5/5

The PR appears safe to merge, with no changed-code defects or independently actionable documentation issues identified.

The new guidance accurately distinguishes discovery from purchasing, matches the documented purchase request contract, and adds safeguards without changing machine-readable provider metadata.

Important Files Changed

Filename	Overview
providers/purch/marketplace/PAY.md	Clarifies the purchase flow and adds spend-aware operational guidance consistent with the committed API contract.

_{Reviews (1): Last reviewed commit: "docs(purch): clarify buy vs shop and add..." | Re-trigger Greptile}