@visa/cli 4.1.0-rc.246 → 4.1.0-rc.247

package/README.md

@@ -12,8 +12,8 @@ The product flow has three explicit parts:
 1. **Identity** — `setup_start` (or `visa setup start`) opens ONE browser
    review that covers the exact runtime, its public-key fingerprint, and every
    requested rail in a single owner approval. The private key stays on the
-   runtime device. (`enroll_agent` / `visa agent enroll` remains the
-   identity-only legacy door.)
+   runtime device. The older identity-only doors remain callable for an
+   already-started integration but are hidden from normal discovery.
 2. **Capabilities** — payment methods, spend grants, email and directory
    bindings are configured separately, each with its own human-visible terms.
 3. **Use** — when a separately provisioned capability exists, the wallet and
@@ -122,6 +122,22 @@ The server now exposes:
 
 Visa sidebands no longer pollute business JSON. Clients receive keys such as `io.visa/visa-receipt` and `io.visa/update-available` in result `_meta`.
 
+## Setup doors
+
+There is one blessed door for each transition. Recovery commands are kept
+discoverable only where a shipped flow prints them; legacy starts remain callable
+for compatibility but do not appear in normal CLI or MCP discovery.
+
+| Transition | Blessed door | Status |
+|---|---|---|
+| New agent from an AI runtime or terminal | `setup_start` / `visa setup start` | Canonical: identity and requested rails on one review page |
+| Agent already created in Console | `agent_handoff_claim` / `visa agent handoff-claim <code>` | Canonical Console handoff |
+| Existing owner account on this device | `agent_login` / `visa agent login` | Canonical sign-in |
+| Resume the canonical setup after restart | `setup_status`, then `setup_resume` / `visa setup status`, then `visa setup open` | Canonical recovery |
+| Finish an already-started legacy pairing | `enroll_agent` action `claim` / `visa agent enroll-claim`, `claim`, or `pairing-resume` as printed | Recovery compatibility only |
+| Resume a paused agent | `visa agent resume <agent-id>` | Live lifecycle control, not enrollment |
+| Start an identity-only legacy pairing | `enroll_agent` / `visa agent enroll`, `pair`, `create`, `verify` | Hidden compatibility; do not start here |
+
 ## Pair an agent identity
 
 For a NEW agent, call **`setup_start`** with the name the human chooses: one
@@ -137,15 +153,12 @@ one bounded recovery attempt. Until that evidence is readable, the result is
 `wallet_runtime_not_ready`, no payment is attempted, and the setup record stays
 available for a later resume.
 
-The identity-only legacy door remains for existing integrations: `enroll_agent`
-with `{"action":"start"}` creates the runtime's Ed25519 key locally, verifies
-the terminal/browser channel, and opens the identity-only review; after the
-human approves, `{"action":"claim"}` activates and durably stores the identity.
+The identity-only legacy handler remains callable for an existing integration or
+an already-started ceremony, but it is deliberately absent from normal discovery.
+Do not start a new agent there.
 
 ```bash
 visa setup start "Name"    # one review page, one approval, every rail
-visa agent enroll          # legacy identity-only review page
-visa agent enroll-claim    # resumes delivery/activation after approval
 visa agent list
 visa agent show <agent-id>
 ```
@@ -240,7 +253,6 @@ is required so the CLI never guesses which agent can spend.
 
 | Tool | Description |
 |------|-------------|
-| `enroll_agent` | Two-step identity-only pairing: start opens the exact runtime/key review; `{"action":"claim"}` activates and stores the agent identity |
 | `agent_capabilities` | Derived live capability map (identity, wallet, card, mail, tap, subway) with upgrade paths |
 | `setup_agent` | Next-step resolver for the wallet rail: `{state, nextAction, blockedBy, steps}`; never spends |
 | `agent_login` | Start/claim the owner's device account session (required before a grant) |
@@ -293,16 +305,15 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Primary same-machine v2 identity pairing
-visa agent enroll
-visa agent enroll-claim
-visa agent connect --authority both --ceiling 25 --per-transaction 1
+# Primary same-machine setup
+visa setup start "Name" --rails card,wallet
+visa setup status
 
 # Existing-account session recovery (separate from identity pairing)
 visa agent login
 visa agent login-claim
 
-# Advanced split-device form of the same v2 ceremony
+# Recovery compatibility for a legacy split-device ceremony already in flight
 visa agent create
 visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
 visa agent verify <pairing-id> <code>
@@ -359,9 +370,9 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 **`expected 402 from <url>`**
 That URL isn't payment-gated — probe the service's actual paid route (`wallet_probe` / `visa find`).
 
-**Pairing ended `expired` or `cancelled`**
-The ceremony timed out — restart with `visa agent enroll`, then run
-`visa agent enroll-claim` after approving the new browser review.
+**Setup ended `expired` or `cancelled`**
+The ceremony timed out — restart with `visa setup start "Name"`, then follow
+`visa setup status` until it reports the next action.
 
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.