@visa/cli 5.0.0-rc.339 → 5.0.0-rc.340

package/README.md

@@ -18,11 +18,12 @@ The protected product flow has three explicit parts:
 2. **Limits** — spending authority is a separate owner approval with its own
    visible terms. Enrollment alone can spend nothing.
 3. **Use** — `visa pay` and the `pay` tool enforce that authority's own policy
-   and approval boundary on every call.
+   and approval boundary on every call. Both are the WALLET rail; card
+   checkouts are the `purchase` resource below.
 
 ## Protected card purchase preview
 
-This is an explicit gated preview exception to the eight general commands and six general tools. It does not change the general `pay` URL dispatcher. The `capabilities.capabilities.card.preview` block returned by `get_status` separates callable tools and the selected protected device proof; current authority is checked per purchase, and live payment readiness remains unverified.
+This is an explicit gated preview exception to the general commands and tools. `pay` no longer dispatches card at all: it is the wallet door, and a merchant checkout URL aimed at it refuses with `card_checkout_not_on_pay` naming this resource. The `capabilities.capabilities.card.preview` block returned by `get_status` separates callable tools and the selected protected device proof; current authority is checked per purchase, and live payment readiness remains unverified.
 
 For the initial **Codex + local MCP on your own device** cohort, builds that list
 `purchase_create`, `purchase_retrieve`, and `purchase_cancel` expose one protected
@@ -279,7 +280,7 @@ a name that was ever real has to stay readable here.
 | `get_status` | Everything about this machine in one answer: the owner signed in, the agent this machine holds, its limits, its capabilities, and what is owed next |
 | `agent_enroll` | The one door. Idempotent, and runs whichever of three legs is owed: signs the owner in when the session lapsed, RECONNECTS this machine's wallet key when it is missing or revoked (that key is held in this machine's own custody, so nothing on a server can repair it), and enrolls when no agent is held. It checks the repair before enrolling, so an agent that already exists is never answered by minting a second one; pass `restart: true` to force a fresh enrollment |
 | `discover` | Find something to pay for. Takes search text, or one listing to read its live challenge without paying |
-| `pay` | Pay. The RAIL COMES FROM THE TARGET: search text searches, a listing id pays over the wallet, a payment-gated URL pays over whichever rail its challenge asks for |
+| `pay` | Pay **from the agent wallet** (x402, USDC). Search text searches; a listing id or an x402 URL pays. A merchant checkout URL is refused by name — that is `purchase_create` |
 | `history` | Receipts, across every rail, with reconciliation when a payment's outcome is unresolved |
 | `purchase_create` | Gated device preview: create/resume exact checkout using existing owner setup |
 | `purchase_retrieve` | Preview: ordinary status, bounded host observation, or explicit include:card credential delivery |
@@ -322,13 +323,19 @@ AI client and leaves the HUD alone, because the HUD is not that client's.
 
 ## CLI commands
 
-Eight, and that is the whole terminal surface. `visa` and `visa-cli` are the
+Nine, and that is the whole terminal surface. `visa` and `visa-cli` are the
 same binary.
 
+**`pay` is the wallet. `purchase` is the card.** They never overlap: `pay`
+spends USDC over x402 in one call, and `purchase` is a card resource you
+create, poll and complete with your own browser. Point a merchant checkout URL
+at `pay` and it refuses by naming `purchase` rather than failing at the end.
+
 ```bash
 visa connect [client]               # mount + sign in + enroll + device + HUD, skipping what is done
 visa status                         # this machine: owner, agent, limits, mounts, HUD, what is blocking
-visa pay <target>                   # a phrase searches; a listing id or URL pays on whichever rail it speaks
+visa pay <target>                   # WALLET (x402/USDC): a phrase searches; a listing id or x402 URL pays
+visa purchase <create|retrieve|cancel>  # CARD: create a purchase, poll it, your agent drives the browser
 visa limits                         # show or change what may be spent (changing needs owner approval)
 visa fund                           # where to add USDC, and on which network
 visa activity [id]                  # payments across every rail; with an id, that one receipt