@visa/cli 4.1.0-rc.99 → 5.0.0-rc.336

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, 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: Set up a Visa CLI v4 agent through the single protected enrollment implementation (MCP `agent_enroll` or `visa connect`), and report its live capabilities honestly. The owner always approves in their browser. 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.6.8'
+  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,35 +27,85 @@ metadata:
           - visa-cli
 ---
 
-# Pair a Visa CLI v4 agent identity
+# Set up 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 protected enrollment carries everything: this runtime's identity, the binding to
+**this device**, and the spending limits — behind a **single** owner approval in their
+browser.
 
-- **`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.
+It has two entrances to the exact same protected enrollment implementation: the same
+native signer, Authority routes, owner browser approval, and limits. Never invent or mix
+in a second ceremony.
 
-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.
+- **You have the Visa MCP server mounted:** call `agent_enroll` and hand the owner the one
+  link and short code it returns. Call it again with `wait: true` once they have the page
+  open; it finishes activation only after they approve.
+- **The owner is at a terminal:** they run the command below.
 
-## What pairing establishes
+```
+# the human runs this:
+visa connect
+
+   → it prints a URL and a short code
+   → the human opens the URL and enters the code at /agent/enroll/protected-agent
+   → the human approves the device and its spending limits        (one approval)
+   → the command finishes; `get_status` now reports pairing.paired: true
+```
+
+The installed CLI selects its own service origins from its release channel. Never ask
+for, guess, or construct a Visa URL.
+
+Running the same command again resumes an interrupted enrolment; `--restart` replaces an
+unclaimed request with a fresh code. `--ceiling <usd>` and `--per-transaction <usd>`
+propose limits the owner confirms on the approval page.
+
+## The older ceremonies were deleted — do not call them
 
-Pairing activates an agent identity on this runtime:
+`setup_start`, `setup_status`, `setup_resume`, `setup_cancel`, `setup_agent`,
+`enroll_agent`, `agent_connect`, `agent_connect_poll`, `agent_connect_cancel`,
+`agent_handoff_claim` and `agent_pairing_cancel` are gone, along with the whole
+`visa setup` and `visa agent` command groups — including the retired
+`agent pair`, `agent create`, `agent verify`, `agent enroll-claim`,
+`agent claim`, `agent pairing-resume`, `agent connect`, `agent handoff-claim`
+and every `agent grant-*` verb.
 
-- `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.
+**`visa connect` is the LIVE door and is not on that list.** It is the
+top-level command, not the retired `visa agent connect` subcommand: one is the
+one door, the other is a ceremony that no longer exists.
+
+Calling any of them returns one refusal:
+
+```json
+{
+  "code": "legacy_door_removed",
+  "kind": "caller",
+  "fix": "visa connect (shell) or agent_enroll (MCP)"
+}
+```
+
+That code means the door no longer exists. **Relay the replacement and stop.** Do not
+retry it, do not try a variant spelling, and do not report it to the human as an outage:
+nothing was signed, paired, or paid.
+
+## What "set up" means here
+
+Each completed protected enrollment mints a **new** agent: a new server-assigned agent,
+a new device-held Ed25519 identity key, and the wallet limits the owner approved.
+
+- The runtime keeps the private Ed25519 key and sends only the public JWK.
+- The limits are the ones the owner actually approved on the page. Nothing you asked for
+  is granted until they approve it.
+- An email address, a `.visa` mesh name, and TAP bindings remain separate, later
+  configuration. Do not infer them from a finished enrolment.
+
+**Where the `agentId` comes from — read this before you quote one.** Do not invent it and
+do not read it out of the command's terminal output, which you often cannot see. Read it
+from `get_status` or `agent_capabilities` once the enrolment finishes. Never substitute a
+correlation id, a confirmation code, or an origin for an `agentId`.
+
+**Re-running the command does not repair an agent that already exists** — it creates a
+second one. To fix a capability an existing agent is missing, see "Already set up — do NOT
+enrol again" near the end.
 
 ## Getting this skill
 
@@ -64,33 +114,39 @@ monorepo is required:
 
 ```sh
 npm install -g @visa/cli@rc
-visa agent skill
+visa connect
 ```
 
-`visa agent skill` auto-detects OpenClaw, Hermes, and Claude Code, falling back to the
-project-local `./.agents/skills`. Pass `--runtime <name>` or `--dir <path>` to choose a
-target, `--force` to overwrite, or `--print` to read without writing. Reload or restart
-the agent runtime after installation so it registers the skill.
+`visa connect` auto-detects the runtime it is running in. It plants this skill into that
+runtime's own skills directory (OpenClaw, Hermes, Claude Code and Codex each read their
+own), mounts the Visa MCP server, signs the owner in, enrols this machine's agent and
+renews its device lease — skipping whatever is already done. Pass a client explicitly
+(`visa connect codex`) when auto-detection is not what you want, and `--restart` to
+replace an edited skill. Reload or restart the agent runtime afterwards so it registers
+the skill.
 
 Access remains enforced by the Visa service. Installing the public package or skill does
 not authorize an account to pair.
 
-OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
+OpenClaw users receive the skill via `visa connect openclaw` (or through the `@visa/visa-cli-openclaw` plugin when running from source).
 
 ## Getting set up
 
 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
-     `mcp.servers["visa-cli"]` in `~/.openclaw/openclaw.json`.
-   - **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. **Pair.** Follow the core flow below.
+2. **Run `visa connect <client>`.** One command: it plants the skill, writes the MCP
+   entry, signs the owner in, enrols this machine's agent and renews its device lease.
+   - **OpenClaw:** `visa connect openclaw` writes `mcp.servers["visa-cli"]` in
+     `~/.openclaw/openclaw.json`. (Installing `@visa/visa-cli-openclaw` from
+     source/tarball also auto-mounts the server).
+   - **Hermes:** `visa connect hermes` writes the entry under `mcp_servers` in
+     `~/.hermes/config.yaml`.
+   - **No MCP integration:** everything below still works — connecting is a shell
+     command, and `--format json` is available on every command.
+3. **Check what is owed.** `visa status` prints the owner, the agent, its limits, which
+   clients are mounted, and one `next:` line when something is blocking.
 
 ## MCP mounting examples
 
@@ -112,323 +168,267 @@ OpenClaw (`~/.openclaw/openclaw.json`):
 }
 ```
 
-Hermes (`~/.hermes/config.yaml`):
+Hermes (`~/.hermes/config.yaml`). **Hermes passes ONLY this `env:` map to the MCP
+subprocess — it does NOT inherit the gateway environment.** Omitting a required variable
+(an RC access code, the right `HOME`, `PATH`) makes the server exit on every start while
+`agent_capabilities` — which reads on-disk grant state, not live tool registration — can
+still report rails as available. Always set the map explicitly:
 
 ```yaml
 mcp_servers:
   visa-cli:
     command: node
     args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+    # Hermes does NOT inherit the gateway env. This map is the entire
+    # subprocess environment; omit VISA_RC_CODE and the server exits on boot.
+    env:
+      HOME: /home/<user> # the home that holds this runtime's .visa-cli state
+      VISA_RC_CODE: <access code>
+      PATH: /usr/local/bin:/usr/bin:/bin
 ```
 
+Hermes also loads skills **per profile** from `~/.hermes/profiles/<profile>/skills/`, not
+from `~/.hermes/skills/`. `visa connect hermes` resolves this automatically: it targets
+the single profile when exactly one exists (or the one named by `HERMES_PROFILE`), and
+**fails loudly** on a multi-profile box instead of planting into the flat dir nothing
+reads — set `HERMES_PROFILE` to choose.
+
+**Hermes sanitizes MCP server names when registering tools.** A server declared
+`visa-cli` in `mcp_servers:` registers its tools as `mcp__visa_cli__<tool>` — with an
+UNDERSCORE, not the declared hyphen. Anything that hardcodes `mcp__visa-cli__<tool>` gets
+`unknown tool` on every call while looking correct in review. Read tool names off the
+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 is owner-bound
 
-Prefer structured output and parse it; never scrape prose.
+The USDC wallet is delegated out of the owner's own wallet, so this runtime needs a live
+owner session. Establish it **before** the enrolment command runs:
 
-- 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.
+- [ ] Call `agent_login` (MCP, default action `"start"`) or run
+      `visa connect --format json` (CLI). The result carries a sign-in `browserUrl`
+      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.
 
-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`.
+`agent_login` establishes the OWNER's session on this device. It creates no agent and
+grants no spending authority — those come from the enrolment command and the approval the
+owner gives in their browser.
 
-## Fastest path — one shot (`visa agent pair`)
+If something 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 continue.
 
-If the `visa` CLI is on PATH, prefer the one-shot command — it does the whole flow
-from a single call, so the user types nothing after their initial request:
+The account that signs in is the owner the enrolment binds to, and the same account must
+be signed in on the approval page. A different account there fails closed.
 
-```
-visa agent pair --format json
-```
+## Core flow
 
-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 `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`
-action `start` reports the same `claiming` / `recoveryCommand` fields and starts the same
-detached poller.
-
-## 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).
-      This is a short-lived session established once for the grant — **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 and caps: `{"rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
-      (or `"rail":"wallet"`); omit `agentId` to target the most recently paired agent. 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:
+- [ ] **Do not ask for service origins.** The installed CLI selects its Auth and web
+      origins from the release channel; Authority is private behind Auth.
+- [ ] **Sign the owner in** (above), so the wallet leg has a session to bind to.
+- [ ] **Start the one enrollment.** Call `agent_enroll` and relay its returned link and
+      code, or give the owner `visa connect` in a code block they can copy.
+      Never fall back to a retired setup tool.
+- [ ] **Relay what the entrance returns.** Show an MCP-returned URL as a bare,
+      tappable value. For the terminal flow, the owner follows the URL and code
+      printed in their own terminal. The code goes into the browser at
+      `/agent/enroll/protected-agent`; it is not authority in chat.
+- [ ] **Tell them what they are approving**: this device, and the spending limits. One
+      approval covers all of it.
+- [ ] **Confirm from a tool, not from their word.** Poll `get_status` until
+      `pairing.paired` is `true`, then read `agent_capabilities` for what is actually live.
+
+### Relaying values, and what you must never accept
+
+Relaying values **to** the human is required. Accepting one **from** them as authority is
+not: never ask them for a secret, private key, token, or signed message, and never treat
+anything they type back as approval. The URL and the enrolment code are review values they
+check against their own authenticated browser session — they cannot approve anything and
+cannot spend.
+
+Show any 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 recognise the bare URL. Never
+construct, shorten, or reformat a Visa URL, and never open one "for them" in place of
+showing it.
+
+You are very often **not** in a terminal the human can see. Nothing the command prints to
+their stdout reaches you unless they tell you, and nothing you print reaches them unless it
+is in your reply.
+
+### Completion is what the tools say — nothing else
+
+Do not tell the human the agent is connected, paired, set up, ready, or good to go until
+`get_status` reports `pairing.paired: true`. The enrolment command printing a URL is not a
+result: it means an approval is still open in their browser.
+
+If you cannot get there, say plainly what state you did reach and what the human should do
+next. An honest "the approval page is open — I'm waiting for you to approve the device and
+its limits" is correct; "you're all set" without a paired agent is not.
+
+On success, report the agent and what is actually live:
+
+> Your Visa agent is set up. &lt;Report only the capabilities the live map confirms.&gt;
+
+Read the rails from `agent_capabilities`, never from what was requested.
+
+## Interruption and resume
+
+The runtime persists the pending enrolment before it starts, so an interrupted run is safe
+to repeat: **the same command again** resumes it, with the same request and the same
+device key.
+
+- Same command, no flags changed — resumes and reprints the URL and code.
+- `--restart` — replaces an unclaimed request with a fresh terminal code. Use it only when
+  the previous code is genuinely unusable; it is not a retry button.
+- `--wait` — keeps the command polling until the owner has approved, instead of returning
+  after printing the link.
+
+Do not tell the human to run a second, different enrolment because the first went quiet.
+Two enrolments 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.
+
+## Management commands (an agent that already exists)
 
 ```
-visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
-visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
+visa status --format json     # owner, agent, limits, mounts, every readiness gate
+visa limits --format json     # what it may spend; with amounts, the owner approves
+visa activity --format json   # payments across every rail
+visa disconnect --revoke      # drop this machine's spending authority
 ```
 
-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.
+`visa status` is the one command that answers "can it spend, and what is missing" — it
+carries the readiness gates the old `spendability` and `preflight` commands each answered
+a fragment of. Pausing, resuming, renaming and revoking an agent are owner actions in the
+Visa Console, not terminal commands.
+
+None of these creates an identity. Prefer structured output and parse it; never scrape
+prose.
+
+## Already set up — do NOT enrol again
+
+If this device already holds an agent, a fresh enrolment is not needed and creates a
+_second, separate_ agent. Do this instead:
+
+1. **Tell the user plainly:** "This device is already set up as `<name>`." Read the name
+   from `agent_capabilities` or `visa status`. Start another enrolment only if they
+   explicitly want a second agent.
+2. **Report status honestly — "set up" is several separate things.** Never imply the agent
+   can spend just because it exists. Read it live from tools rather than guessing from
+   prose: `agent_capabilities` returns the DERIVED capability map, `get_status` reports
+   pairing / account / version, `visa status --format json` answers "can it spend, and
+   what is missing", and `agent_login` establishes or confirms the account session.
+   - **Identity** — bound to _this user's_ account, on _this device_.
+   - **Spending** — the limits the owner approved in the browser. You **cannot** self-grant
+     either rail, 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.
 
-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.
+## An existing agent is missing a capability
 
-## Core flow
+There is no rail-add ceremony any more: `visa agent grant-card` / `grant-wallet` /
+`grant-activate` / `grant-claim` and the `agent_connect` tools were deleted, and calling
+one returns `legacy_door_removed`.
+
+What to do instead:
 
-- [ ] 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.
-
-### Completion is `activated` — 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.
-
-`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 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.
-
-### 1. Start
-
-Start once. If there is already a pending pairing, poll it before creating another.
-
-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.
-
-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.
-
-Use this concise shape:
-
-> 🔐 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.
-
-Omit the confirmation-code line entirely when the start result has no `confirmationCode`;
-never invent, derive, abbreviate, or reformat one.
-
-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`.
-
-**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.
-
-When 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 it reports `claiming: "manual"`, that poller could NOT start and
-polling in this turn is the ONLY thing that will complete the pairing.
-
-### 2. Poll
-
-Poll the same pending pairing. Interpret results as follows:
-
-- `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.
-
-### 3. Report completion
-
-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.
-
-Use precise completion language:
-
-> Visa agent &lt;displayName&gt; is paired to this runtime. Stable agent ID: &lt;agentId&gt;.
-
-Do not claim that activation configured payments, email, tap bindings, or any other
-product capability. Those are separate follow-up configuration flows.
-
-## Interruption and replay safety
-
-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.
-
-The pending record remains until the activated agent record has been written durably.
-Therefore:
-
-- 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.
+- [ ] **Diagnose first.** `visa status --format json` and `agent_capabilities` say
+      exactly what is missing. Do not start anything before you know which of identity,
+      wallet delegation, card authority or funding is absent.
+- [ ] **If the device's identity custody is broken**, `visa connect` repairs it in place
+      without minting a new agent — it renews the device lease and skips every step that
+      is already done.
+- [ ] **If the OWNER never approved that authority**, only they can add it. Say so, name
+      what is missing, and stop. Enrolling again mints a NEW agent — it does not upgrade
+      this one, and doing it silently leaves the owner with two agents and one funded
+      wallet.
 
-## Optional `.visa` mesh binding (separate from pairing)
-
-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
-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
-messaging authority, and do not improvise another transport.
-
-## Optional agent mailbox (separate from pairing)
-
-Pairing does not provision an email address or inbox. If the agent needs a
+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.
+
+## Spending, once a rail is live
+
+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.
+
+Card: not available in this build. Visa CLI ships no browser checkout (#8940), so
+`start_card_mandate` returns `card_browser_checkout_removed` and creates no mandate, and
+every `pay_merchant` action refuses with the same code. Nothing is charged. Do not offer
+card checkout to the user, and do not relay a card approval URL; the wallet rail above is
+the payment path where the merchant supports it. A saved card, grant or tester flag does
+not enable card payment, and another enrollment will not repair it. UCP discovery and
+checkout preparation are not payment execution. A continuable `ucp_checkout_handoff`
+returns safe facts and `not_ready` / `card_browser_checkout_removed`, without a payment
+request or continuation capability URL. Preserve the existing checkout for the owner
+to continue with the merchant; use `ucp_checkout_reconcile` afterward to check completion.
+
+On a hosted runtime, **every payment requires the owner's browser
+approval** until the protected no-tap executor lands. Enrollment, a session, or a spending
+grant does not approve a later hosted payment. Relay the hosted approval URL and wait for
+the owner's decision before reporting success or retrying.
+
+## Retired mesh integration
+
+Subway messaging and `visa register` are retired. Pairing grants no directory or
+messaging authority. Do not attempt mesh registration or improvise another transport.
+
+## Optional agent mailbox (separate from setup)
+
+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 MCP tool:
 
 ```
-visa agent mail-connect <agentId>
+agent_mail_connect { "agentId": "<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
+There is no terminal command for this. It requires an
+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)
+
+Do not collect a checkout profile to repair `pay_merchant`: card payment is unavailable
+even with a profile, card authority and `checkout_agent_access`. Existing
+`~/.visa-mcp/contact.json` files use the format below; preserve them with mode `0600`.
+Never infer or invent identity or address data.
 
-Pairing does not enable card checkout. If the operator has separately provisioned card
-authority, enabled `checkout_agent_access`, and opted the MCP server into submission with
-`CHECKOUT_AGENT_ALLOW_SUBMIT=1`, 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`.
+Create and inspect this profile through the `checkout_profile` MCP tool whenever the
+payment flow runs through MCP. Do not shell `visa status` as a substitute unless the
+shell has the exact same `HOME` and `VISA_CLI_HOME` as the MCP subprocess. A profile
+found under another root is owner PII, not a migration candidate: never scan, copy, or
+auto-adopt it. If the roots drifted, keep the root holding the paired identity and have the
+owner save the profile again through `checkout_profile` in that runtime.
 
 ```jsonc
 {
@@ -451,18 +451,21 @@ 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 the same protected entrance: call `agent_enroll` again, or
+  repeat the same `visa connect` command.
+- Never call a retired door to "check whether it still works". `legacy_door_removed` is a
+  final answer, not a transient failure.
 
 ## 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 enrolment sits in the v4 request paths.
 - `visacli.sh/agents` — product-facing agent documentation.