@visa/cli 4.1.0-rc.298 → 4.1.0-rc.299

package/README.md

@@ -7,13 +7,12 @@ a mailbox, or a `.visa` name. New paired agents request publication of their
 public key to the TAP directory by default; owners can durably remove it with
 `visa agent tap-opt-out <agent-id>`.
 
-The product flow has three explicit parts:
+The protected 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. The older identity-only doors remain callable for an
-   already-started integration but are hidden from normal discovery.
+1. **Enrollment** — in this build the owner runs `visa agent enroll-protected`
+   and approves the exact device and its limits in the browser. The private key
+   stays on the runtime device. Retired setup, pairing, handoff, and per-rail
+   grant names return `legacy_door_removed`; they never resume or proxy work.
 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
@@ -134,51 +133,31 @@ Visa sidebands no longer pollute business JSON. Clients receive keys such as `io
 
 ## 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.
+There is one protected enrollment workflow. The CLI is its only entrance in
+this build; a future canonical MCP entrance may call the same workflow. Legacy
+names are hidden refusals, not compatibility paths.
 
 | 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 |
+| New agent, from any runtime | `visa agent enroll-protected --authority-url <origin> --auth-url <origin> --url <origin>` | Current entrance to protected enrollment |
+| Existing owner account on this device | `agent_login` / `visa agent login` | Canonical sign-in; adds no agent |
 | 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
-resumable setup covers identity plus every requested rail in a single owner
-approval on one review page, and `setup_status` / `setup_resume` carry it
-across restarts. From a terminal, `visa setup start "<name>"` begins the same
-operation.
-
-For a wallet setup, `completed` on the server is necessary but not sufficient
-for the runtime to report ready. `setup_status` first verifies the exact-agent
-local signing path used by wallet preflight and payments; managed runtimes make
-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 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.
+For a new agent, the owner starts the protected command with the three trusted
+origins supplied by the operator, opens the printed URL, enters its short code,
+and approves the device and limits. Repeat the same command with `--wait` to
+finish an interrupted local wait. The old setup and pairing names do not resume
+an earlier ceremony; they return one deterministic refusal and the current
+command.
 
 ```bash
-visa setup start "Name"    # one review page, one approval, every rail
+visa agent enroll-protected --authority-url <origin> --auth-url <origin> --url <origin> --wait
 visa agent list
 visa agent show <agent-id>
 ```
 
-The advanced `create` → `claim` → `verify` → `pairing-resume` commands are the
-split-device choreography of this same v2 ceremony, not a second enrollment
-system. The review shows the runtime, context, stable agent ID, full public-key
-fingerprint, and expiry. It grants identity only; no spend limits or instruments
-are implied.
-
 On macOS and Linux, the private identity key is stored under
 `~/.visa-cli/agents` in an owner-only directory with file mode `0600`. It is
 currently an exportable local file: copying it transfers identity proof, and
@@ -261,17 +240,15 @@ is required so the CLI never guesses which agent can spend.
 
 ## MCP tools (v4 surface)
 
+Rows marked **Removed** are kept so old transcripts still resolve: the tool is
+no longer in `tools/list`, and a direct call by name answers
+`legacy_door_removed` naming the one door for a new agent,
+`visa agent enroll-protected`.
+
 | Tool | Description |
 |------|-------------|
 | `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) |
-| `setup_start` | Start ONE resumable setup (identity + rails) in a single human approval; returns the review link and this device's half of the compare code |
-| `setup_status` | Read the server's one `nextAction` and polling cadence; terminal wallet results additionally require exact-agent local signing evidence before reporting ready |
-| `setup_resume` | Put the review link and compare code back in front of the human after a restart or a closed tab |
-| `setup_cancel` | Abandon a setup still waiting on the human; never undoes an approval |
-| `agent_connect` | Initiate an owner-approved spending grant for a paired agent |
-| `agent_connect_poll` | Poll that grant ceremony to activation (returns caps, and the funding address for wallet) |
 | `wallet_status` | Delegated wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |
@@ -281,6 +258,13 @@ is required so the CLI never guesses which agent can spend.
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
 | `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
+| `setup_agent` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_start` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_status` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_resume` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_cancel` | **Removed.** Use `visa agent enroll-protected` |
+| `agent_connect` | **Removed.** Authority is approved during `visa agent enroll-protected` |
+| `agent_connect_poll` | **Removed.** Authority is approved during `visa agent enroll-protected` |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |