@visa/cli 4.1.0-rc.225 → 4.1.0-rc.227

package/dist/skills/pair-visa-agent/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: pair-visa-agent
-description: Pair a Visa CLI v4 agent identity to this runtime. Present one authorization link, the returned public confirmation code, and the full public request-key fingerprint to the human (or claim a Console handoff code directly without local owner login), then poll until the runtime's local Ed25519 identity is activated. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa agent", or "set up my agent identity".
-compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to install it if missing — plus network access to the Visa authorization service. Works in OpenClaw, Hermes, or any Agent Skills runtime.
+description: Connect a Visa CLI v4 agent — identity plus every payment rail it needs — through ONE setup operation the human approves once in their browser. Ask what to call the agent, call setup_start, relay the review link, then poll setup_status until it is ready. Use when the user says "pair my agent", "connect Visa", "enroll my Visa CLI", "set up my agent", or "let this agent pay".
+compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to install it if missing — plus network access to the Visa authorization service. Works in OpenClaw, Hermes, Claude Code, Codex, or any Agent Skills runtime.
 allowed-tools: Bash(visa:*) Bash(visa-cli:*) Bash(node:*) Bash(npm:*) Bash(npx:*)
 metadata:
   author: visa
   homepage: https://visacli.sh/agents
-  version: '0.7.1'
+  version: '0.8.0'
   # OpenClaw-namespaced extension (agentskills.io keeps `metadata` free-form, so
   # non-standard runtime config lives here — `user-invocable` is not a standard
   # top-level field). OpenClaw auto-installs `install[]` when `requires.bins` are
@@ -27,45 +27,52 @@ metadata:
           - visa-cli
 ---
 
-# Pair a Visa CLI v4 agent identity
+# Connect a Visa agent
 
-Pair this runtime's locally generated identity with a human-approved Visa agent. Pairing
-protocol v2 has one ceremony and three equivalent ways to drive it:
+One setup operation carries everything: this runtime's identity **and** every payment
+rail the agent needs, behind a **single** owner approval on a single review page. You ask
+once, the human clicks Connect once, and you finish the rest yourself.
 
-- **`pair_agent_start` / `pair_agent_poll`** — OpenClaw plugin tools.
-- **`enroll_agent` with `action: "start"` / `action: "claim"`** — the `visa` MCP server tool.
-- **`visa agent enroll --format json` / `visa agent enroll-claim --format json`** — the raw
-  CLI and universal fallback.
+**The whole flow is two tool calls and, for the human, one or two clicks.**
 
-Use the first surface available. Do not mix this flow with older pairing or login flows;
-all three surfaces above wrap the same v2 enrollment ceremony and local pending state.
+```
+setup_start {"name": "<what they call it>", "rails": ["card", "wallet"]}
+   → relay the returned browserUrl to the human
+   → human clicks "Connect agent"        (click 1)
+   → for the wallet rail, one "Approve"  (click 2 — same page, no second budget)
+setup_status                              (repeat at the returned pollAfterMs)
+   → each call drives the agent's own steps; stop when nextAction.kind is "done"
+```
 
-**Console handoff codes are a separate, compound ceremony.** When the human brings a
-one-time code minted by the Console's Create-agent flow, claim it instead of pairing:
-the code carries server-held, pre-approved terms and resolves identity + spending in one
-run (card auto-activates from the mint consent; wallet still needs one browser approval).
-The MCP tool `agent_handoff_claim` exists only on `@visa/cli` **4.1.0-rc.159 and newer**
-— on an older CLI it is absent from the served tool list and the only path is shelling
-`visa agent handoff-claim <code> --format json`, a different integration with different
-failure modes (the approval URL and verification code arrive mid-run as a structured
-stderr frame). Never assume the tool from documentation alone: check the served list.
+Nothing else. Do **not** walk `enroll_agent` → `agent_connect` → `agent_connect_poll` →
+`start_card_mandate` for a new agent: that legacy sequence spends three extra owner
+approvals reaching the same place, and this skill replaces it.
+
+## What "connected" means here
+
+`setup_start` mints a **new** agent: a new server-assigned agent, a new device-held Ed25519
+identity key, and whichever rails you asked for. When the operation reports ready:
 
-## What pairing establishes
+- The runtime keeps the private Ed25519 key and sends only the public JWK.
+- The rails in `readiness.rails` are the ones the owner actually approved. A rail you did
+  not request is not configured, and pairing has never implied one.
+- An email address, a `.visa` mesh name, and TAP bindings remain separate, later
+  configuration. Do not infer them from a finished setup.
 
-Pairing activates an agent identity on this runtime:
+**Where the `agentId` comes from — read this before you quote one.** The setup status body
+carries `operationId`, `state`, `readiness`, `nextAction`, `pollAfterMs`, `correlationId`
+and `agent: {name, runtime?, device?}`. It does **not** carry `agentId`, and it never
+carries `identityKeyJkt` (that is a field of the older pairing flow). `agentId` appears on
+exactly one result: the `setup_status` call that performed the activation, which returns it
+alongside `walked`. If you need the id and that call is not the one in front of you — the
+background watcher often finishes the last rung — read it from `get_status` or
+`agent_capabilities` rather than guessing. **Never substitute the `so_…` operation id or a
+`correlationId` for an `agentId`:** they are different things, and feeding an operation id
+to a grant ceremony fails in a way that looks like a Visa outage.
 
-- `agentId` is the server-assigned, stable identifier for the agent.
-- The runtime creates and retains the private Ed25519 identity key. It sends only the
-  public JWK to the service.
-- `identityKeyJkt` is the thumbprint of the currently bound Ed25519 public key. It can
-  change when that key rotates, so it must never be presented or stored as the stable
-  agent identifier.
-- The human receives the authorization URL, stable agent ID, and full public request-key
-  fingerprint for exact comparison. Private key material, the local claim token, and signed
-  protocol messages stay with the runtime.
-- An `activated` result means **identity paired only**. Payment methods, an email address,
-  and tap bindings are separate configuration that may be added later. Do not infer any
-  of those capabilities from pairing success.
+**`setup_start` cannot add a rail to an agent that already exists** — it always creates a
+new one. To give an already-connected agent another rail, see "Adding a rail to an agent
+that already exists" near the end.
 
 ## Getting this skill
 
@@ -91,7 +98,7 @@ OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
 
 1. **Install the prerelease CLI.** Run `npm install -g @visa/cli@rc`, or run the bundled
    idempotent provisioner `node scripts/setup.mjs`. The `@latest` tag may not yet expose
-   the v4 agent commands. Installation puts `visa` and `visa-cli` on `PATH` and includes
+   the v4 setup tools. Installation puts `visa` and `visa-cli` on `PATH` and includes
    `@visa/cli/dist/mcp-server/index.js`.
 2. **Mount the MCP server when the runtime supports MCP.**
    - **OpenClaw:** installing `@visa/visa-cli-openclaw` auto-mounts the server by writing
@@ -99,10 +106,10 @@ OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
    - **Hermes or another supported runtime:** run `visa-cli connect hermes` or
      `visa-cli connect <runtime>`. For Hermes, the entry is written under `mcp_servers`
      in `~/.hermes/config.yaml`.
-   - **No MCP integration:** use the raw `visa agent …` commands.
-3. **Sign the owner in.** Pairing starts are owner-bound — see "Sign in first" below. On a
-   fresh runtime using direct pairing, this step is required before any pairing command will succeed. When claiming a Console handoff code, skip sign-in and claim the handoff directly.
-4. **Pair.** Follow the core flow below.
+   - **No MCP integration:** use the raw `visa setup …` commands.
+3. **Sign the owner in** when the setup includes the wallet rail — see "Sign in first"
+   below.
+4. **Connect.** Follow the core flow below.
 
 ## MCP mounting examples
 
@@ -158,325 +165,271 @@ live registry; never derive them from the config key.
 In Hermes, `hermes claw migrate` can also import this skill and MCP configuration from an
 existing OpenClaw installation. See `RUNTIMES.md` for the complete runtime map.
 
-## JSON and exit-code contract
+## Sign in first — the wallet rail is owner-bound
 
-Prefer structured output and parse it; never scrape prose.
-
-- The OpenClaw and MCP tools return structured objects directly.
-- Raw CLI commands support `--format json`.
-- `visa agent enroll-claim` exits `0` when activated, `3` when the human has not finished,
-  and `1` on a terminal failure.
-
-The start result includes protocol version `2`, `pairingId`, stable `agentId`, full
-`requestKeyFingerprint`, `browserUrl`, and expiry information. Newer builds also return
-`confirmationCode`, a short public code the browser review page displays for comparison.
-Present it when the field is present and skip it when it is absent; an older server or CLI
-simply omits it, which is not an error. The activation result includes protocol version
-`2`, `pairingId`, stable `agentId`, the display name, and `identityKeyJkt`.
-
-## Sign in first — pairing is owner-bound
-
-Pairing starts are authenticated as the owner: the service pins the owner account at
-initiation, and the browser review page rejects any other signed-in account
-(`owner_profile_mismatch`). So on a fresh runtime the ceremony has a mandatory first leg —
-establish the owner session **before** any runtime-initiated pairing command (Console handoff codes
-are owner-pinned by the code itself and do NOT require an active owner session):
+The USDC wallet rail is delegated out of the owner's own wallet, so this runtime needs a
+live owner session before that leg can run. Establish it **before** calling `setup_start`
+with `"wallet"` in `rails`:
 
 - [ ] Call `agent_login` (MCP, default action `"start"`) or run
       `visa agent login --format json` (CLI). The result carries a sign-in `browserUrl`
-      and a short 6-character confirmation code.
+      and a short 6-character `confirmCode`.
 - [ ] Relay **both** to the human in your reply — the bare URL on its own line, and the
       code. You are very often not in a terminal they can see; the chat message is the
       only place these values reach them.
 - [ ] The human opens the link, signs in (Google or email), and **types the confirmation
       code into the sign-in page** — into the browser, never back to you in chat.
 - [ ] Claim the session: `agent_login {"action":"claim"}` (the CLI command polls on its
-      own). Once claimed, the session token is stored locally and pairing can start.
+      own). Once claimed, the session token is stored locally.
 
-If a pairing command returns "An owner profile is required before pairing" or
-`{"code":"session_required"}`, that is this ordering rule — not a fault. Run `agent_login`,
-drive the sign-in above to a claimed session, then retry the same pairing command once.
+If a wallet leg reports `{"code":"session_required"}` or "Not logged in", that is this
+ordering rule, not a fault: run `agent_login`, drive the sign-in above to a claimed
+session, then call `setup_status` again — the walk resumes where it stopped.
 
-The account that signs in here is the owner the pairing binds to. The same person must
-approve the pairing link in the next step from that same signed-in browser session;
-a different account on the review page fails closed.
+The account that signs in is the owner the setup binds to, and the same account must be
+signed in on the review page. A different account there fails closed with
+`owner_profile_mismatch`. The **card-only** setup does not need this leg first.
 
-## Fastest path — one shot (`visa agent pair`)
-
-If the `visa` CLI is on PATH, prefer the one-shot command — after the owner session above
-exists, it does the whole flow from a single call, so the user types nothing after their
-initial request:
-
-```
-visa agent pair --format json
-```
-
-On a runtime with no owner session it fails with "An owner profile is required before
-pairing" — run the sign-in leg above first, then re-run it.
-
-It returns `browserUrl`, `pairingId`, stable `agentId`, the full public
-`requestKeyFingerprint`, and — on newer builds — `confirmationCode` **immediately**. It
-starts a detached activation process only after the pending identity and private key are
-durable. Present the link, returned confirmation code, and fingerprint for browser
-comparison; omit only a confirmation code the result did not provide. When driving `visa agent pair --format json` and `claiming` is `background`,
-activation completes after approval without another command; if it is `manual`, run the
-returned `recoveryCommand` after approval. Use the step-by-step flow
-below when `pair` is unavailable or when driving the plugin/MCP tools — `enroll_agent` and `visa agent enroll`
-are explicit two-step flows (`start` returns `state: "needs_owner"` and `nextAction: {tool: "enroll_agent", action: "claim"}`; `claim` completes activation after human approval). There is no detached background poller for `enroll_agent` or `visa agent enroll`.
-
-## Returning & already-connected — do NOT re-pair
-
-If `pair`/`enroll` returns **`already_connected`** (or `alreadyConnected: true`), this
-device is **already set up** as an agent — a fresh pairing is neither needed nor
-possible (re-pairing an existing identity silently dead-ends). Do this instead:
-
-1. **Tell the user plainly:** "This device is already connected as `<name>.visa`."
-   Read the name from the response. Do **not** start another hand-off. `--new` /
-   `force:true` exists only if they explicitly want a _second, separate_ agent.
-2. **Report status honestly — "connected" is five separate things**, not one. Never
-   imply the agent can spend just because it's connected. Don't guess from prose —
-   read it live from tools: `agent_capabilities` returns the DERIVED capability map
-   (the identity + wallet + mail base plus card/tap/subway availability),
-   `get_status` reports enrollment / account / version, and `agent_login` establishes
-   or confirms the account session that spending grants require.
-   - **Identity** — connected (`.visa` name bound to _this user's_ account). ✓ once `already_connected`.
-   - **Spending** — a _separate human approval_, and there are two rails, each
-     approved on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`) — not any
-     account-settings page (that legacy surface is retired). The Turnkey
-     **wallet:x402** rail (stablecoin) is approved with the owner's **sign-in session**
-     (the Google/email auth-proxy) — **no passkey**. The **card:vic** rail is approved
-     with a **passkey**. You **cannot** self-grant either; there is no
-     `visa agent add-rail` command, and never self-mint a wallet with `wallet_init` on
-     mainnet — it throws until the owner's delegation lands.
-   - **Mesh (`.visa` messaging)** — with `SUBWAY_MESH=visa`, a returning device now
-     registers on `pair`; if `meshRegistered` is false, `visa register <name>` joins it.
-   - **Trusted (TAP)** — follows spend/provisioning; don't promise it before then.
-3. **Scope everything to the user.** The identity is bound to the account the user
-   signed in with (their email); the wallet + spend limits are theirs. Speak in terms
-   of "your agent / your account / the limits you approved," never a shared identity.
-
-Missing **spend** blocks _checkout mandates_, not a delegated x402 wallet — but that
-wallet must first be acquired by owner approval (below); it is never self-minted.
-
-## What you can do once paired — granting spend authority (card or wallet)
-
-Pairing binds **identity only**. To let this agent pay, the human owner must **delegate**
-a spend rail — the runtime never self-mints one. There are two rails, and **one** ceremony
-drives both:
-
-- **`wallet:x402`** (Turnkey stablecoin) — owner approves with their **sign-in session, no
-  passkey**. On mainnet `wallet_init` throws `WalletCredentialRequiredError` until this
-  delegation lands, so never call it as a setup step.
-- **`card:vic`** (Visa card checkout) — owner approves with a **passkey**.
-
-The contract is identical for both rails, and it is **one command from you, one approval
-from the owner**. You never hand a command, code, or URL back to the human after they
-approve — you poll to completion yourself:
-
-1. **You run one command** naming the rail and caps.
-2. **The owner opens the returned link and approves once** (they may adjust the amount).
-3. **You poll to activation** — the owner does nothing further.
-
-- [ ] **Pair** the identity (the flow above). Identity only — no rail yet.
-- [ ] **Establish the owner session once.** Grant creation is an account operation, so this
-      runtime needs a live owner session: `agent_login` (MCP) or `visa agent login` (CLI).
-      If you just paired, the session from the sign-in-first leg is usually still live —
-      no re-login needed. This is a short-lived session established once — **not** a
-      re-pair, and **not** something the owner repeats per payment. If `agent_connect`
-      later returns `{"code":"session_required"}`, the session lapsed — run `agent_login`
-      again.
-- [ ] **Initiate the grant from MCP — no shelling, no invented URLs.** Call `agent_connect`
-      with the rail, caps, and exact `agentId` returned by pairing:
-      `{"agentId":"<agentId>","rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
-      (or `"rail":"wallet"`; `agentId` is optional only when exactly one eligible paired agent
-      exists on this runtime). It returns `{ url, code, attachId, willGrant, expiresAt }`. Present the
-      **bare `url` and `code` exactly as returned** — never construct, shorten, or guess a Visa URL, and
-      never open it yourself. The crypto approval happens in the owner's browser and cannot run
-      inline in chat. (`setup_agent {"rail":"card"|"wallet"}` returns the same next-step map
-      if you need it.)
-- [ ] **Owner approves once** on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`),
-      confirming the caps — **card with a passkey, wallet with their sign-in session**. You
-      cannot approve on their behalf.
-- [ ] **Poll to activation from MCP.** Call `agent_connect_poll` (`{"attachId":"<from
-agent_connect>"}`; or resume by `agentId`) — one bounded poll per call. It returns
-      `{"ok":false,"state":"...","blockedByKind":"awaiting_human_approval"}` while pending;
-      call again until `{"ok":true,"state":"grant_activated","caps":...}` (wallet also
-      returns `fundAddress`). Activation registers the delegated signer + caps: wallet writes
-      the Turnkey credential (`turnkey.json`); card writes the card pointer. It never spends.
-- [ ] **Confirm the rail is live.** Wallet: `wallet_status` / `visa wallet show`
-      (`agent_capabilities.wallet.available`). Card: `agent_capabilities.card.available`.
-      Only a delegated credential — not the served tool list — means the rail is usable.
-- [ ] **Then spend against the owner-approved caps.** Wallet: set the policy with
-      `wallet_policy_set` (per-transaction / daily / session USD caps + optional network and
-      merchant allow/deny lists that refuse an x402 payment BEFORE it is signed), then
-      `wallet_pay`. Card: `start_card_mandate` then `pay_merchant`. Never raise a
-      human-approved limit yourself.
-
-**Raw CLI equivalent (one shot).** If you cannot drive MCP, the same ceremony runs from the
-CLI and `--wait` polls to activation in a single call. Present the URL it prints — don't
-invent one:
-
-```
-visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
-visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
-```
-
-Rail selection is the owner's call — wallet only, card only, or both. Newer builds also
-accept one compound command that runs the same ceremony per rail in sequence
-(`both` = card, then wallet, under the same caps — expect one extra approval trip):
-
-```
-visa agent connect --authority <card|wallet|both> --ceiling <usd> --per-transaction <usd> --wait
-```
+## Core flow
 
-Use the stable `agentId` from pairing or `visa agent list` — never invent or alter the id.
-A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
-with a different command or a reconstructed URL.
+- [ ] **Ask what to call the agent.** `name` is required, and it is what the human sees on
+      the approval page. Do not invent one.
+- [ ] **Ask which rails**, unless they already said. `"card"` is the Visa card rail,
+      `"wallet"` is the USDC (x402) rail; `rails` defaults to `["card"]`. Both in one
+      request costs the owner no extra approval — they share one budget.
+- [ ] **Call `setup_start`** with the name and rails. It mints the identity key, creates
+      the operation, and opens the owner's browser at the review page.
+- [ ] **Relay `browserUrl` to the human**, with `compareCode` when the result carries one
+      (see below). Never open it "for them" in place of showing it, and never approve.
+- [ ] **Call `setup_status`** at the returned `pollAfterMs`, repeatedly. Each call also
+      executes the runtime's own steps — this is how the agent gets connected, so a setup
+      you never poll is a setup that never finishes.
+- [ ] **Render `nextAction.label` verbatim** to the human each time it changes.
+- [ ] **Stop when `nextAction.kind` is `done`** (or any terminal state). Then report.
+
+### The one rule for reading a status
+
+**`nextAction` is the server's decision. Render it; never compute your own.** Every
+surface — this runtime, the review page, the Console — says the same sentence about the
+same operation because they all render this one field. `nextAction.actor` tells you whose
+turn it is:
+
+- `actor: "agent"` — **yours**. Keep calling `setup_status`; it performs the step. Do not
+  ask the human for anything, and do not end your turn waiting to be told they are done.
+- `actor: "human"` — **theirs**. Show `nextAction.label`, plus `nextAction.url` when the
+  action carries one. Then keep polling: they act in the browser, not in chat.
+- `actor: "none"` — finished (`kind: "done"`) or terminal. Stop polling and report.
+
+Honour `pollAfterMs` (`0` means stop) and `nextAction.afterAction` (`"poll"`, `"stop"`,
+`"open_url_again"`). An agent that honours both cannot spin or give up early.
+
+### Relaying the link and the compare code
+
+The review page shows a short code to compare **unless** it can tell by machine that the
+agent asking is the one that opened it — in which case it says "Opened from this device by
+the agent that asked" and shows no code. Which of the two happens is not knowable when you
+call `setup_start`: the page has not been opened yet, so the server carries no verdict, and
+neither does this runtime (launching a browser is not proof one loaded it).
+
+So the rule is: **relay `compareCode` whenever the result carries one, and phrase it as a
+condition.** Never announce that there will be no code — being wrong that way leaves the
+human staring at an anti-phishing code with nothing to check it against. The tool result's
+`message` is already written this way; prefer it verbatim.
+
+> 🔐 Connect your Visa agent — open this page to review and approve:
+>
+> 👉 &lt;browserUrl, bare and on its own line&gt;
+>
+> If the page shows a code, check it matches this one and don't approve if it differs:
+> &lt;compareCode&gt;
+> If it says it was opened from this device, that check was already made for you.
+>
+> I'll keep watching and confirm here the moment it's ready.
 
-Once a wallet is delegated and a policy is set, these are the served wallet tools this agent
-can actually call: `wallet_discover` (search the public x402 Bazaar), `wallet_probe` (read a
-challenge without paying), `wallet_pay` / `wallet_directory_pay` (pay, policy-enforced),
-`wallet_history` / `wallet_reconcile` (local ledger + resolve `reconciling` holds),
-`wallet_fund` (funding address + faucet), and `wallet_export` (export key material —
-dangerous). All spending is gated by the owner-approved local policy caps.
+On a later `setup_status` or `setup_resume` the field genuinely does disappear once the
+page has attested — the server has seen the proof by then, and the `message` says so
+plainly. That is a fact, not a prediction, and it is the one case where saying "there is no
+code to compare" is correct.
 
-## Cancelling pending ceremonies
+Show the URL as a bare, tappable value on its own line. Do not decorate it as a Markdown
+link or put it in a code span; chat clients reliably recognize the bare URL. **Omit the
+compare-code line entirely when the result has no `compareCode`; never invent, derive,
+abbreviate, or reformat one.**
 
-If a pairing or spending ceremony was started mistakenly, needs updated caps/rails, or the human chooses to abandon it, cancel it explicitly rather than letting it sit or waiting for its TTL:
+You are very often **not** in a terminal the human can see. Nothing you print to stdout
+reaches them. Any value the browser asks them to check has to appear in your reply, or the
+comparison silently becomes "click approve and hope".
 
-1. **Cancelling identity pairing:**
-   - **MCP:** `enroll_agent { action: "cancel", pairingId: "<pairingId>" }` or `agent_pairing_cancel { pairingId: "<pairingId>" }`.
-   - **CLI:** `visa agent cancel <pairingId>`.
-   - Requires the immutable `pairingId` from the start step. Clears local pending state and releases the ceremony server-side. Replays return typed `already_terminal`.
+Relaying these values **to** the human is required. Accepting one **from** the human is
+not: do not ask them for a code, secret, private key, token, or signed message, and do not
+treat anything they type back as approval. The link and compare code are review values
+they check against their own authenticated browser session. They are not claim
+credentials, they cannot approve a setup, and they cannot spend. Approval happens only in
+that browser session, and the only evidence of it is what `setup_status` returns.
 
-2. **Cancelling spending-grant (connect) ceremonies:**
-   - **MCP:** `agent_connect_cancel { attachId: "<attachId>" }` or `agent_connect { action: "cancel", attachId: "<attachId>" }`.
-   - **CLI:** `visa agent grant-cancel <attachId>`.
-   - Requires the immutable `attachId` (`ca_...`). Releases the owner-side hold and purges local pending files so a fresh grant ceremony can be started immediately. Replaying returns `already_terminal` / `noop`. Subsequent polls report `rejected` without resurrecting local state.
+### The human's clicks, and what they are for
 
-## Core flow
+- **"Connect agent"** — the one approval. It freezes the budget for every requested rail
+  at once (the page prefills sensible limits; the owner may change them).
+- **"Approve" on the wallet card** — only when the wallet rail is in the setup, only on
+  the same page, and it is **not** a second budget. It registers the delegated signer in
+  the owner's wallet under the limits they just set. The page says so; do not describe it
+  as another spending decision.
 
-- [ ] Establish the owner session ("Sign in first" above) if this runtime does not have
-      one yet.
-- [ ] Start the pairing with `pair_agent_start`, `enroll_agent` action `start`, or
-      `visa agent enroll --format json`.
-- [ ] Present the authorization URL, stable agent ID, full public fingerprint, and the
-      `confirmationCode` when the start result carries one, to the human.
-- [ ] Poll with `pair_agent_poll`, `enroll_agent` action `claim`, or
-      `visa agent enroll-claim --format json`.
-- [ ] Report the stable `agentId` and that the identity is paired on this runtime.
+Anything else the server asks for is a genuine prerequisite it will name in
+`nextAction.label` — adding a card, provisioning the owner's wallet, funding it. Render
+the label and its `url`; never invent a step of your own.
 
-### Completion is `activated` — nothing else
+### Completion is what `readiness` says — nothing else
 
-Only a poll result of `activated` means this runtime is paired. Until you have one, do not
-tell the human the agent is connected, paired, enrolled, set up, ready, or good to go, and
-do not move on to spending, mail, or mesh steps that assume an identity.
+Do not tell the human the agent is connected, paired, set up, ready, or good to go until
+`setup_status` returns a terminal `nextAction` of `kind: "done"`. A created operation is
+not a finished one: `setup_start` returns an `operationId` **before any human has approved
+anything**, and reporting that id as though it were a result is the most likely way to
+mislead them, because the string looks like an answer.
 
-`start` returning successfully is not completion. It returns a stable `agentId` and a
-`requestKeyFingerprint` **before any human has approved anything** — those are review
-values for the browser comparison, not evidence of pairing. Reporting an `agentId` as
-though it were a finished pairing is the most likely way to mislead the human here, because
-the number looks like a result.
+If you cannot get there, say plainly what state you did reach and what the human should do
+next. An honest "approved, still provisioning the wallet — I'm still watching" is correct;
+"you're all set" without a finished operation is not.
 
-If you cannot reach `activated`, say plainly what state you did reach and what the human
-should do next. An honest "approved but not yet activated — I'm still polling" is correct;
-"you're all set" without an `activated` result is not.
+On success, report the agent's name and the rails that are actually ready:
 
-### 1. Start
+> Visa agent &lt;agent.name&gt; is connected. Ready to pay by &lt;card and/or USDC wallet&gt;, within
+> the limits you approved.
 
-Start once. If there is already a pending pairing, poll it before creating another.
+Quote an `agentId` only if the result you are holding actually carries one (see "Where the
+`agentId` comes from" above). It is not needed to tell the human they are done.
 
-The result provides `browserUrl`, stable `agentId`, `requestKeyFingerprint`, and — on newer
-builds — `confirmationCode`. Show the URL as a bare, tappable value on its own line. Do not
-decorate it as a Markdown link or put it in a code span; chat clients reliably recognize the
-bare URL. Show the complete fingerprint without truncation and tell the human to approve
-only when every character matches the browser review page.
+## Interruption and resume
 
-You are very often **not** in a terminal the human can see. Nothing you print to stdout
-reaches them. Every value the browser asks them to compare has to appear in your reply, or
-the comparison silently becomes "click approve and hope" — which is the whole failure this
-step exists to prevent.
+The runtime persists the operation before it starts, so an interrupted call is safe to
+repeat: the same `operationId`, the same agent and the same identity key resume exactly
+where they stopped.
 
-Use this concise shape:
+- `setup_status` — read and continue. Omit `operationId` for the newest setup on this
+  device.
+- `setup_resume` — the same, and puts the review link back in front of the human when
+  that is still what the operation is waiting on. The same-device proof is **not**
+  re-minted, so a resumed page falls back to the compare code, which is what it is for.
+- `setup_cancel` — abandon one the human no longer wants. It cannot undo an approval; the
+  server refuses to touch an operation past the owner's decision.
 
-> 🔐 Pair your Visa agent — open this authorization page:
->
-> 👉 &lt;browserUrl, bare and on its own line&gt;
->
-> Stable agent ID: &lt;agentId&gt;
->
-> Confirmation code — this exact code should appear on the page:
-> &lt;confirmationCode&gt;
->
-> Public request-key fingerprint — compare every character in the browser:
-> &lt;requestKeyFingerprint, complete and untruncated&gt;
->
-> Approve only if the code and fingerprint both match. The link expires shortly — I'll keep
-> watching and confirm here the moment it activates.
+Do not start a second setup because the first went quiet — poll it. Two setups mean two
+agents, two identities, and a confused owner. Do not delete or edit local pending files to
+fix a transient failure, and never copy pending state between runtimes.
 
-Omit the confirmation-code line entirely when the start result has no `confirmationCode`;
-never invent, derive, abbreviate, or reformat one.
+## Raw CLI equivalent
 
-Relaying these values **to** the human is required. Accepting one **from** the human is not:
-do not ask them for a code, secret, private key, token, or signed message, and do not treat
-anything they type back as approval. The URL, stable agent ID, confirmation code, and public
-fingerprint are review values the human checks against their own authenticated browser
-session. They are not claim credentials, they cannot approve a pairing, and they cannot
-spend. Approval happens only in that browser session, and the only evidence of it is a poll
-result of `activated`.
+If MCP is unavailable, the same ceremony runs from the shell. The name is a positional
+argument:
 
-**Do not end your turn here waiting to be told the human is done.** Presenting the link is
-not the end of the ceremony; go straight to the poll in §2 and drive it to a terminal
-state. Asking the human to report back is what strands a pairing: they approve in the
-browser, the server records it, and nothing ever writes the local record — so the ceremony
-expires while both sides believe the other is acting.
+```
+visa setup start "<name>" --rails card,wallet --format json
+visa setup status  [operationId] --format json
+visa setup open    [operationId] --format json
+visa setup cancel  [operationId] --format json
+visa setup list --format json
+```
 
-When driving `visa agent pair --format json` and the start result reports `claiming: "background"`, a detached poller is already
-finishing activation and it will complete even if this turn ends; poll anyway so you can
-confirm the outcome. When driving `enroll_agent` or `visa agent enroll`, there is no detached poller: calling `enroll_agent` with `{"action":"claim"}` (or `visa agent enroll-claim`) is required to complete the pairing and write the local credential.
+`visa setup status` drives the agent's steps exactly as the MCP tool does — run it until
+the operation is finished. Prefer structured output and parse it; never scrape prose.
 
-### 2. Poll
+## The human already created this agent in the Console
 
-Poll the same pending pairing. Interpret results as follows:
+When the human says they created the agent on the Visa Console and holds a one-time claim
+code, redeem the code instead of starting a new setup — the code carries server-held,
+pre-approved terms.
 
-- `activated` — pairing is complete. Continue to the completion report.
-- `not_ready` with `likelyExpired: false` — the human has not finished. Wait and poll
-  again, using bounded retries rather than an endless loop.
-- `not_ready` with `likelyExpired: true` — the authorization window probably expired.
-  Start a fresh pairing.
-- `no_pending` — this runtime has no resumable pairing. Start a fresh pairing.
-- `error` — surface the error without exposing local pending data. Retry once if it is a
-  transient network failure; otherwise stop and ask the human to start again.
+The MCP tool `agent_handoff_claim` exists only on `@visa/cli` **4.1.0-rc.159 and newer**
+— on an older CLI it is absent from the served tool list and the only path is shelling
+`visa agent handoff-claim <code> --format json`, a different integration with different
+failure modes (the approval URL and verification code arrive mid-run as a structured
+stderr frame). Never assume the tool from documentation alone: check the served list.
+In a handoff claim the card auto-activates from the mint consent, and the
+wallet still needs one browser approval. Console handoff codes are owner-pinned by the
+code itself and do NOT require an active owner session.
+
+If they created it in the Console but have **no** code, still call `setup_start`: it
+adopts the request they already made — their Create click was the approval — rather than
+asking them to approve a second time.
+
+## Already connected — do NOT connect again
+
+If this device already holds an agent, a fresh setup is not needed and creates a
+*second, separate* agent. Do this instead:
+
+1. **Tell the user plainly:** "This device is already connected as `<name>.visa`." Read
+   the name from the response. Start another setup only if they explicitly want a second
+   agent.
+2. **Report status honestly — "connected" is several separate things.** Never imply the
+   agent can spend just because it is connected. Read it live from tools rather than
+   guessing from prose: `agent_capabilities` returns the DERIVED capability map (the
+   identity + wallet + mail base plus card/tap/subway availability), `get_status` reports
+   enrollment / account / version, and `agent_login` establishes or confirms the account
+   session.
+   - **Identity** — connected (`.visa` name bound to _this user's_ account).
+   - **Spending** — the rails the owner actually approved. The Turnkey **wallet:x402**
+     rail (stablecoin) is approved with the owner's **sign-in session** — **no passkey**.
+     The **card:vic** rail is approved on the **v4 agent dashboard**
+     (`app.visacli.sh/agent/enroll`), never any account-settings page (that legacy surface
+     is retired). You **cannot** self-grant either, and never self-mint a wallet with
+     `wallet_init` on mainnet — it throws `WalletCredentialRequiredError` until the
+     owner's delegation lands.
+   - **Mesh (`.visa` messaging)** — separate; `visa register <name>` joins it.
+   - **Trusted (TAP)** — follows spend/provisioning; don't promise it before then.
+3. **Scope everything to the user.** The identity is bound to the account they signed in
+   with; the wallet and limits are theirs. Speak in terms of "your agent / your account /
+   the limits you approved", never a shared identity.
 
-### 3. Report completion
+## Adding a rail to an agent that already exists
 
-On `activated`, report the display name when present and the stable `agentId`. You may
-also report `identityKeyJkt` as the current key fingerprint, but label it clearly as a
-rotatable key identifier.
+`setup_start` always mints a new agent, so it is the wrong tool here. For an
+already-connected agent that needs another rail, run the single-rail grant ceremony
+against its **exact `agentId`** — never a name, never "the most recent one":
 
-Use precise completion language:
+- [ ] **Establish the owner session** if this runtime does not have one: `agent_login`
+      (MCP) or `visa agent login` (CLI). Short-lived, established once — not a re-pair,
+      and not something the owner repeats per payment.
+- [ ] **Initiate the grant from MCP.** `agent_connect` with the rail, caps, and the exact
+      `agentId`:
+      `{"agentId":"<agentId>","rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
+      (or `"rail":"wallet"`). It returns `{ url, code, attachId, willGrant, expiresAt }`.
+      Present the **bare `url` and `code` exactly as returned** — never construct,
+      shorten, or guess a Visa URL, and never open it yourself.
+- [ ] **The owner approves once** on the v4 agent dashboard, confirming the caps.
+- [ ] **Poll to activation** with `agent_connect_poll` (`{"attachId":"<from
+      agent_connect>"}`) — one bounded poll per call, until
+      `{"ok":true,"state":"grant_activated"}`.
+- [ ] **Confirm the rail is live.** Wallet: `wallet_status` / `visa wallet show`
+      (`agent_capabilities.wallet.available`). Card: `agent_capabilities.card.available`.
+      Only a delegated credential — not the served tool list — means the rail is usable.
 
-> Visa agent &lt;displayName&gt; is paired to this runtime. Stable agent ID: &lt;agentId&gt;.
+Shell equivalents, which poll to activation in one call:
 
-Do not claim that activation configured payments, email, tap bindings, or any other
-product capability. Those are separate follow-up configuration flows.
+```
+visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
+visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
+```
 
-## Interruption and replay safety
+A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
+with a different command or a reconstructed URL. Never raise a human-approved limit
+yourself.
 
-The runtime persists its v2 pending record before sending the signed claim. If a request
-or response is interrupted, the next poll resumes the exact same `pairingId`, `agentId`,
-Ed25519 identity, and claim material. This makes an identical retry safe and avoids
-creating a second identity because a response was lost.
+## Spending, once a rail is live
 
-The pending record remains until the activated agent record has been written durably.
-Therefore:
+Wallet: set the policy with `wallet_policy_set` (per-transaction / daily / session USD
+caps plus optional network and merchant allow/deny lists that refuse an x402 payment
+BEFORE it is signed), then `wallet_pay`. The served wallet tools are `wallet_discover`
+(search the public x402 Bazaar), `wallet_probe` (read a challenge without paying),
+`wallet_pay` / `wallet_directory_pay` (pay, policy-enforced), `wallet_history` /
+`wallet_reconcile` (local ledger + resolve `reconciling` holds), `wallet_fund` (funding
+address + faucet), and `wallet_export` (export key material — dangerous). All spending is
+gated by the owner-approved local policy caps.
 
-- Poll before starting over.
-- Do not delete or edit pending files to fix a transient failure.
-- Do not regenerate keys for an existing pairing.
-- Do not copy pending state between runtimes.
+Card: `start_card_mandate`, then `pay_merchant`. The first card purchase asks the owner
+for a spending mandate within the budget they already approved.
 
-## Optional `.visa` mesh binding (separate from pairing)
+## Optional `.visa` mesh binding (separate from setup)
 
 Pairing does not register a `.visa` name, TAP key, or Subway peer. If the operator has
 separately enabled and registered those channel bindings, the mounted `visa-cli` MCP server
@@ -484,40 +437,40 @@ may expose `subway_register`, `subway_send`, `subway_inbox`, and `subway_find`.
 
 Mesh messaging is available only on a compatible RC/dev build with `SUBWAY_MESH=visa` and
 a reachable `SUBWAY_RELAY_MULTIADDR`. If those tools or the relay are unavailable, report
-that clearly and stop. Do not imply that identity pairing alone granted directory or
+that clearly and stop. Do not imply that connecting an agent granted directory or
 messaging authority, and do not improvise another transport.
 
-## Optional agent mailbox (separate from pairing)
+## Optional agent mailbox (separate from setup)
 
-Pairing does not provision an email address or inbox. If the agent needs a
+Connecting an agent does not provision an email address or inbox. If the agent needs a
 mailbox — e.g. to receive a merchant's account-signup or one-time-code email —
-connect one explicitly, from the paired runtime, with the raw CLI:
+connect one explicitly, from the connected runtime, with the raw CLI:
 
 ```
 visa agent mail-connect <agentId>
 ```
 
 This is CLI-only; no pairing step or MCP tool connects a mailbox. It requires an
-already-paired stable-agent identity on this runtime — it reads the local agent
+already-connected stable-agent identity on this runtime — it reads the local agent
 record and proves the Ed25519 identity to the service. It issues the stable
 agent mailbox if one does not exist, then stores an inbox-scoped credential in an
 owner-only `0600` runtime file so this runtime can read that one inbox.
 
 Be honest about scope. A mailbox grants an email address and the ability to read
 that inbox — nothing more. It is **not** identity, a wallet, spend authority, a
-card, or a `.visa` name, and it never authorizes a payment. Do not claim pairing
+card, or a `.visa` name, and it never authorizes a payment. Do not claim setup
 set up mail. Once connected, the MCP `wallet_mail_status`, `wallet_mail_read`,
 and `wallet_mail_await_otp` tools read the inbox (e.g. to await a sender-checked
 one-time code); without the scoped credential those reads fail closed. Keep the
 org-wide AgentMail key off the runtime — provisioning happens only through
 `mail-connect` under operator control.
 
-## Optional checkout profile (separate from pairing)
+## Optional checkout profile (separate from setup)
 
-Pairing does not enable card checkout. If the operator has separately provisioned card
-authority and enabled `checkout_agent_access`, the experimental `pay_merchant` flow also needs a local
-`~/.visa-mcp/contact.json` file. Collect every value from the human before the first review;
-never infer or invent identity or address data. Write the file with mode `0600`.
+The experimental `pay_merchant` flow also needs a local `~/.visa-mcp/contact.json` file
+once card authority exists and `checkout_agent_access` is enabled. Collect every value
+from the human before the first review; never infer or invent identity or address data.
+Write the file with mode `0600`.
 
 ```jsonc
 {
@@ -540,18 +493,18 @@ mailbox, key proof, recovery factor, or permission to spend.
 
 ## Security rules
 
-- Never read, print, log, paste, or transmit the private Ed25519 JWK or local claim token.
-- Never read or echo the pending pairing file. Present only the authorization URL returned
-  by the supported command or tool.
+- Never read, print, log, paste, or transmit the private Ed25519 JWK or any local claim
+  token.
+- Never read or echo local pending files. Present only the URL returned by the tool.
 - Never treat `identityKeyJkt` as the stable identity. Use `agentId` for references and
   persistence.
-- Never fetch the authorization URL on the human's behalf. The human reviews and approves
-  it in their browser.
-- Never invent a secondary pairing path when polling fails. Preserve the pending state,
-  surface the error, and retry or restart through the same canonical enrollment flow.
+- Never fetch or submit the review URL on the human's behalf. They review and approve it
+  in their own browser.
+- Never invent a secondary path when a call fails. Preserve the local state, surface the
+  error, and resume through `setup_status` / `setup_resume`.
 
 ## Further docs
 
 - `RUNTIMES.md` — OpenClaw, Hermes, and raw CLI setup.
-- `docs/agents/ARCHITECTURE.md` — where enrollment sits in the v4 request paths.
+- `docs/agents/ARCHITECTURE.md` — where setup sits in the v4 request paths.
 - `visacli.sh/agents` — product-facing agent documentation.