@visa/cli 5.0.0-rc.408 → 5.0.0-rc.411

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

@@ -1,116 +0,0 @@
-# Running Visa agent setup in OpenClaw and Hermes
-
-`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the skill is runtime-agnostic.
-OpenClaw, Hermes, and any runtime that can execute the `visa` CLI or mount its MCP server
-all drive the same setup operation: identity plus every requested rail, behind one owner
-approval.
-
-## Plugins are runtime-specific
-
-| Axis            | OpenClaw                                                  | Hermes                                                                                          |
-| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Language        | JavaScript/TypeScript                                     | Python                                                                                          |
-| Plugin manifest | `openclaw.plugin.json` + `definePluginEntry` (`index.ts`) | `~/.hermes/plugins/<name>/plugin.yaml` + `__init__.py`, `ctx.register_tool(...)`                |
-| Config file     | `~/.openclaw/openclaw.json`                               | `~/.hermes/config.yaml`                                                                         |
-| Skills          | Markdown `SKILL.md`                                       | Markdown under `~/.hermes/skills/<name>/`                                                       |
-| MCP             | `mcp.servers.*`                                           | `mcp_servers.*`                                                                                 |
-| Migration       | —                                                         | `hermes claw migrate` imports skills, allowlists, compatible MCP servers, memory, and `SOUL.md` |
-
-The OpenClaw JavaScript tools do not load as a Hermes plugin. Portability comes from the
-Markdown skill, CLI, and MCP protocol instead.
-
-## One ceremony, two surfaces
-
-Both supported surfaces run the same protected enrollment and share the same local
-pending record:
-
-1. Visa MCP server: `agent_enroll`, then `agent_enroll` with `wait: true` once the
-   owner has the page open.
-2. Terminal: `visa connect` (add `--format json` for machine output).
-
-Each returns one link and a short code for the human. The browser receives only that
-link. The agent's keys are generated on this device and never leave it, and the
-approval page certifies only the keys this device named in the link. Calling it again
-resumes the same pending enrollment after an interruption.
-
-Use `agentId` as the stable identity. `identityKeyJkt` identifies the currently bound
-Ed25519 public key and can change after key rotation.
-
-The older plugin pairing tools and MCP enrollment tools are gone: they drove CLI
-commands that no longer exist. `agent_enroll` (MCP) and `visa connect` are the one door.
-
-## Install and mount
-
-Install the prerelease CLI, which provides both command names and the MCP server:
-
-```sh
-npm install -g @visa/cli@rc
-```
-
-There is no `visa mcp` subcommand. Run `visa-cli connect <runtime>` when supported, or
-configure `@visa/cli/dist/mcp-server/index.js` directly. Replace `<npm root -g>` below
-with the output of `npm root -g`.
-
-OpenClaw (`~/.openclaw/openclaw.json`):
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "visa-cli": {
-        "command": "node",
-        "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
-      }
-    }
-  }
-}
-```
-
-Hermes (`~/.hermes/config.yaml`). Hermes passes a filtered platform-safe baseline
-(`PATH`, `HOME`, platform variables, and `XDG_*`) plus this server's `env:` map.
-Arbitrary gateway variables are excluded, so map `VISA_RC_CODE` explicitly. The
-placeholder keeps its value in `~/.hermes/.env` instead of `config.yaml`:
-
-```yaml
-mcp_servers:
-  visa-cli:
-    command: node
-    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
-    env:
-      VISA_RC_CODE: ${VISA_RC_CODE}
-      # Optional overrides for a different state directory or toolchain:
-      # HOME: /home/<user>
-      # PATH: /usr/local/bin:/usr/bin:/bin
-```
-
-### Keep one local-state namespace
-
-The gateway shell and the Visa MCP subprocess must resolve the same `HOME` and
-`VISA_CLI_HOME`. Set that boundary before pairing and keep it stable. Changing
-`VISA_CLI_HOME` later also changes where paired identity and grant records are
-read; it is not a safe way to make an old contact file visible.
-
-For example, with `HOME=/opt/data/home` and no `VISA_CLI_HOME`, identity lives
-under `/opt/data/home/.visa-cli` and checkout contact under
-`/opt/data/home/.visa-mcp`. A profile at `/opt/data/.visa-mcp` belongs to a
-different state namespace. Do not scan, copy, or auto-adopt it: contact files
-contain owner PII. The host passes checkout details to `purchase_create` itself;
-no Visa tool writes the profile.
-
-## Runtime setup map
-
-| Runtime       | Setup surface                                                                                                                                                                                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenClaw      | Install `@visa/cli@rc` (`npm install -g @visa/cli@rc`) and run `visa connect openclaw`. It plants the skill under `~/.openclaw/skills/` and mounts the Visa MCP server into `~/.openclaw/openclaw.json`. (The `@visa/visa-cli-openclaw` plugin package is prerelease). |
-| Hermes        | Run `visa connect hermes`. It resolves the per-profile skills directory and refuses to guess when several profiles exist — set `HERMES_PROFILE` to choose one. `hermes claw migrate` can import an existing OpenClaw setup.                                            |
-| Codex         | Run `visa connect codex`. It plants the skill under `~/.codex/skills/` and mounts the Visa MCP server into `~/.codex/config.toml` in the same step.                                                                                                                    |
-| Other runtime | Put `visa` on `PATH` and mount the same MCP server by hand; `get_status` shows what is connected.                                                                                                                                                                      |
-
-The skill is planted by `visa connect <client>`, into that client's own skills
-directory. Reload the runtime afterwards.
-
-## Optional Hermes wrapper
-
-A Hermes Python plugin may wrap the canonical raw CLI commands and register tools with
-`ctx.register_tool(...)`. It is optional: the MCP server and skill already expose the
-same operation and persisted local state without a second implementation.

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

@@ -1,464 +0,0 @@
----
-name: pair-visa-agent
-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.9.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
-  # missing; other runtimes (Hermes, Claude Code, …) self-provision via the
-  # bundled `scripts/setup.mjs` (see compatibility + Getting set up). @rc pinned
-  # until 4.1.0 is promoted to latest.
-  openclaw:
-    user-invocable: true
-    emoji: '🔐'
-    requires:
-      bins:
-        - visa
-    install:
-      - kind: node
-        package: '@visa/cli@rc'
-        bins:
-          - visa
-          - visa-cli
----
-
-# Set up a Visa agent
-
-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.
-
-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.
-
-- **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.
-
-```
-# 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 tools the Visa MCP server serves
-
-The Visa MCP server serves exactly these tools: `get_status`, `agent_enroll`,
-`discover`, `pay` and `history`, plus the card preview's
-`purchase_create`, `purchase_retrieve` and `purchase_cancel` where the build lists
-them. Call no other Visa tool name, whatever an older guide, a memory or another
-agent says: every earlier setup, login, pairing, capability and wallet tool is gone.
-Read the live tool list if in doubt.
-
-## The older ceremonies were deleted — do not call them
-
-The whole `visa setup` and `visa agent` command groups are gone too — 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.
-
-**`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.
-
-A retired command, or an older build still answering a retired tool name, 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` 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
-
-The skill ships inside the public `@visa/cli` npm package. No clone of the private
-monorepo is required:
-
-```sh
-npm install -g @visa/cli@rc
-visa connect
-```
-
-`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 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 setup tools. Installation puts `visa` and `visa-cli` on `PATH` and includes
-   `@visa/cli/dist/mcp-server/index.js`.
-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.** `get_status` reports the owner, the agent, its limits, which
-   clients are mounted, and one `next:` line when something is blocking.
-
-## MCP mounting examples
-
-Both runtimes use the same server entrypoint. Replace `<npm root -g>` with the output of
-`npm root -g`.
-
-OpenClaw (`~/.openclaw/openclaw.json`):
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "visa-cli": {
-        "command": "node",
-        "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
-      }
-    }
-  }
-}
-```
-
-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, so no
-Visa tool registers at all, while the terminal — which reads on-disk state with the
-gateway's own environment — can still look healthy. 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.
-
-## Sign in first — the wallet is owner-bound
-
-The USDC wallet is delegated out of the owner's own wallet, so this runtime needs a live
-owner session. The one door takes care of the order: `agent_enroll` (and `visa connect`)
-signs the owner in first whenever the session is missing or has lapsed, and only then
-starts the enrolment.
-
-- [ ] Call `agent_enroll` (MCP) or run `visa connect --format json` (CLI). When a sign-in
-      is owed, 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.
-- [ ] Call `agent_enroll` again once they have (the CLI command polls on its own). It
-      picks up the approved sign-in on this device and moves on to the enrolment link.
-
-Signing in establishes the OWNER's session on this device. It creates no agent and grants
-no spending authority — those come from the enrolment and the approval the owner gives in
-their browser.
-
-If something reports `{"code":"session_required"}` or "Not logged in", that is this
-ordering rule, not a fault: call `agent_enroll` (or run `visa connect`), drive the sign-in
-above, then continue.
-
-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.
-
-## Core flow
-
-- [ ] **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`; the same `get_status` says 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 `get_status`, 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)
-
-```
-get_status {}                 # owner, agent, limits, mounts, every readiness gate
-history    {}                 # this agent's payments
-# Caps are the owner's, in the Visa Console: /agent/enroll/limits?agent=<agent-id>
-# Spend across every rail is the Console's Activity feed.
-visa disconnect --revoke      # drop this machine's spending authority
-```
-
-`get_status` is the one call 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 `get_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 `get_status` rather than guessing
-   from prose: it reports pairing, account and version, and answers "can it spend, and
-   what is missing".
-   - **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 or self-mint a wallet: the wallet arrives only by the owner's delegation.
-   - **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.
-
-## An existing agent is missing a capability
-
-There is no rail-add ceremony any more: `visa agent grant-card` / `grant-wallet` /
-`grant-activate` / `grant-claim` were deleted, and calling one returns
-`legacy_door_removed`.
-
-What to do instead:
-
-- [ ] **Diagnose first.** `get_status` says
-      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.
-
-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: `discover` finds what to buy (a query, or a listing id to read one without
-paying), `pay` pays it with a mandatory `max` ceiling, and `history` reads this agent's
-payments. The limits are the ones the owner approved; the owner changes them in the Visa
-Console, never you. Funding is the owner's, in the Console.
-
-Card: Visa-operated browser checkout is retired; another enrollment will not repair it.
-The retired browser-checkout tools refuse with `card_browser_checkout_removed`.
-On local builds that list `purchase_create`,
-`purchase_retrieve` and `purchase_cancel`, the protected card preview uses the
-host's checkout tools and the existing eligible card and agent identity. Follow
-`next`: relay the single owner setup or limits URL, let the owner act, then repeat
-the same purchase call. Never ask for funding-card secrets in chat. Explicit
-`include:"card"` may put the issued purchase credential in model/chat history,
-under the owner's disclosure consent. A saved card or tester flag alone does
-not establish eligibility or merchant credential compatibility. UCP discovery
-and preparation remain separate from payment execution; a `not_ready` handoff
-is not permission to pay or to revive the retired browser flow.
-
-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, and no Visa tool
-connects or reads one. There is no terminal command for this either. Do not claim setup
-set up mail, and do not improvise a mailbox. A mailbox would grant an email address and
-nothing more: it never authorizes a payment.
-
-## Optional checkout profile (separate from setup)
-
-Do not collect a checkout profile to revive Visa browser checkout: it
-is retired. On local builds that list `purchase_create`, `purchase_retrieve` and
-`purchase_cancel`, the protected card preview reuses this identity and verified
-card. The host supplies checkout and billing details, owns browser submission,
-and follows the returned `next` action. Fixed protocol fields and `requestKey`
-may be omitted; retain the same checkout reference and terms on retry. Explicit
-`include:"card"` returns issued purchase credentials under owner consent and may
-put them in model/chat history. Never request original funding-card details in
-chat, bypass eligibility, or retry an uncertain merchant submission. Existing
-`~/.visa-mcp/contact.json` files use the format below; preserve them with mode `0600`.
-Never infer or invent identity or address data.
-
-No Visa tool writes this profile; the host passes checkout and billing details to
-`purchase_create` itself. Any shell that reads an existing profile must have 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.
-
-```jsonc
-{
-  "fullName": "Ada Lovelace",
-  "email": "ada@example.com",
-  "addressLine1": "1 Analytical Way",
-  "addressLine2": "",
-  "city": "San Francisco",
-  "state": "CA",
-  "postalCode": "94105",
-  "country": "US",
-}
-```
-
-`fullName` must be non-blank; `firstName` plus `lastName` is also accepted. The engine reads
-the exact keys `fullName`, `firstName`, `lastName`, `email`, `addressLine1`, `addressLine2`,
-`city`, `state`, `postalCode`, and `country`. The profile supplies checkout/cardholder and
-billing data only. Its `email` value is not the account's verified owner email, an agent
-mailbox, key proof, recovery factor, or permission to spend.
-
-## Security rules
-
-- 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 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 enrolment sits in the v4 request paths.
-- `visacli.sh/agents` — product-facing agent documentation.