@visa/cli 4.1.0-rc.32 → 4.1.0-rc.321

package/README.md

@@ -1,21 +1,22 @@
 # @visa/cli
 
-Visa CLI v4 gives an AI agent a **Visa Verified Agent** identity and a scoped,
-human-capped signer for a Turnkey-managed wallet. Agents discover paid
-x402/MPP services and pay with USDC over MCP (Model Context Protocol); the
-human approves the limits and every payment is checked against on-device policy
-before anything is signed. Larger browser purchases use a separately approved
-VIC credential and card mandate.
-
-The v4 flow has three parts, always in this order:
-
-1. **Identity** — the human enrolls in the browser (email or Google sign-in, card on file, bank verification) and mints a `.visa` name bound to the agent.
-2. **Delegation** — a pairing ceremony gives the runtime a scoped, revocable
-   Turnkey signer with human-approved per-transaction and daily caps. The
-   runtime never receives the human wallet's root key.
-3. **Payment** — `find → inspect → pay` handles x402/MPP purchases with gasless
-   USDC and explicit maxima; `checkout` / `mandate` handles larger VIC browser
-   purchases.
+Visa CLI v4 pairs an AI runtime to a human-approved **Visa agent identity**.
+The pairing ceremony creates one stable agent ID and activates one
+runtime-custodied Ed25519 identity key. It does not create payment authority,
+a mailbox, or a `.visa` name. New paired agents request publication of their
+public key to the TAP directory by default; owners can durably remove it with
+`visa agent tap-opt-out <agent-id>`.
+
+The protected product flow has three explicit parts:
+
+1. **Enrollment** — call `agent_enroll` or have the owner run `visa agent enroll`
+   and approves the exact device and its limits in the browser. The private key
+   stays on the runtime device. Retired setup, pairing, handoff, and per-rail
+   grant names return `legacy_door_removed`; they never resume or proxy work.
+2. **Capabilities** — payment methods, spend grants, email and directory
+   bindings are configured separately, each with its own human-visible terms.
+3. **Use** — when a separately provisioned capability exists, the wallet and
+   VIC commands enforce that capability's own policy and approval boundary.
 
 ## Install
 
@@ -31,7 +32,17 @@ Windows PowerShell:
 iwr -useb https://app.visacli.sh/install.ps1 | iex
 ```
 
-Node.js 18+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
+Node.js 20+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
+
+### Managed runtime convergence
+
+The RC package also installs `visa-runtime-converge` for supervisor-owned
+OpenClaw/Hermes/Telegram deployments. A scheduled invocation resolves the
+preview server's recommended exact RC, stages and integrity-checks it, restarts
+through the configured supervisor, verifies the loaded version/environment, and
+rolls back a failed activation. It never updates an interactive owner-managed
+installation. Configuration and readiness contracts are documented in
+[`packages/visa-cli-openclaw/RUNTIMES.md`](https://github.com/Visa-Crypto-Labs/Visa-mono/blob/staging/packages/visa-cli-openclaw/RUNTIMES.md).
 
 ## MCP setup
 
@@ -65,44 +76,150 @@ args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
 
 There is no CLI subcommand for starting the MCP server directly — the MCP server is the bundled `dist/mcp-server/index.js` entrypoint, which `visa-cli connect <client>` registers for you.
 
-## Enroll a Verified Agent
+### UCP commerce bundle
 
-Enrollment starts from the agent, not the terminal: the agent calls the **`enroll_agent`** MCP tool, which opens the enrollment page in the browser and prints a 6-character confirmation code in the terminal. The human signs in with **email or Google**, chooses the agent's `.visa` name, adds a card, completes the bank's verification step, and types the confirmation code. When the browser reports the credential was sent to the CLI, the agent calls `enroll_agent` with `{"action":"claim"}` to park the credential on the device.
+Install the Visa pairing skill, discovery-first UCP shopping skill, bounded
+Shopify checkout skill, and both Visa and Shopify UCP MCP entries in one step:
 
-Only enter a confirmation code you watched your own terminal print. Enrollment
-must begin with `enroll_agent` and present Turnkey email or Google sign-in.
+```bash
+visa agent skill --commerce --runtime codex
+# runtimes with writable MCP config: codex, openclaw, hermes
 
-## Connect an agent runtime (pairing)
+# Inspect the installed local bundle without changing skills or MCP config:
+visa agent skill --commerce --runtime codex --check
+```
 
-Enrollment mints identity; **pairing is what lets a runtime sign payments.**
+The shopping skill turns broad requests into a short seller/variant list and
+requires an exact selection plus an all-in ceiling before checkout. The pinned
+Shopify UCP server requires Node.js 22 or newer. A successful run
+reports both MCP entries as mounted or already mounted; restart or reload the
+agent before using the new tools. The installer never performs discovery or a
+checkout itself. The install-only command exits successfully after writing the
+bundle, but reports `commerceReady: false` / `ucp_check_required` until the
+explicit `--check` gate passes. `commerceReady` is a compatibility alias for
+local bundle readiness only; it never proves that a merchant purchase can be
+completed. The JSON result keeps `purchase.ready: false` until a separate live
+checkout preflight is performed.
+
+Checked readiness is read-only: missing or modified skills and missing,
+conflicting, or malformed MCP entries are reported without installing or
+rewriting anything. It parses the active local profile and its pinned Shopify
+profile contract directly from disk, without starting `npx`, and reports the
+exact profile initialization command if local state is missing or invalid. It
+also refuses to claim local natural-language shopping readiness when a
+top-level `ucp` or `shop` skill with a `SKILL.md` is present in the same runtime
+directory. The installer reports those paths but never deletes or disables
+user-owned skills.
+
+If the selected runtime already has a non-equivalent `shopify-ucp` entry, the
+command fails without changing that entry or its environment, authentication,
+timeout, or filtering fields. Rename or remove the existing entry explicitly
+before rerunning; the installer does not silently replace or downgrade it.
+
+### MCP 2026-07-28 compatibility
+
+This release speaks the modern, stateless MCP `2026-07-28` protocol over stdio and deliberately rejects the legacy `initialize` handshake. Your client must support per-request protocol envelopes and `server/discover`; update the client before upgrading Visa CLI if it still sends MCP `2025-*` traffic. `visa-cli connect` can write configuration for every listed client, but configuration support does not imply that an older installed client understands the new wire revision.
+
+The server now exposes:
+
+- JSON Schema 2020-12 tool inputs and outputs, `structuredContent`, namespaced result metadata, cache hints, and receipt `resource_link` blocks.
+- Resources for agent status, capabilities, recent activity, and canonical `visa://receipt/{transactionId}` receipts.
+- Prompts for pairing/funding, spend inspection, safe purchasing, and receipt reconciliation, with completion support.
+- The `io.modelcontextprotocol/tasks` extension for durable, pollable `pay_merchant` approval work. Task lifecycle is owner-scoped in the auth service; an MCP-process restart fails an in-flight checkout closed instead of replaying it.
+- Multi-round-trip `input_required` URL elicitation with HMAC-protected, client-bound request state when the client supports URL elicitation but not Tasks.
+- The `io.modelcontextprotocol/ui` Visa Control Center MCP App at `ui://visa/control-center`.
+
+Visa sidebands no longer pollute business JSON. Clients receive keys such as `io.visa/visa-receipt` and `io.visa/update-available` in result `_meta`.
+
+## Setup doors
+
+There is one protected enrollment workflow. The CLI is its only entrance in
+this build; a future canonical MCP entrance may call the same workflow. Legacy
+names are hidden refusals, not compatibility paths.
+
+| Transition | Blessed door | Status |
+|---|---|---|
+| New agent, from any runtime | `visa agent enroll` / `agent_enroll` | One protected enrollment implementation; owner approves in the browser |
+| Existing owner account on this device | `agent_login` / `visa agent login` | Canonical sign-in; adds no agent |
+| Resume a paused agent | `visa agent resume <agent-id>` | Live lifecycle control, not enrollment |
+
+## Pair an agent identity
+
+For a new agent, the owner starts the protected command with the three trusted
+origins supplied by the operator, opens the printed URL, enters its short code,
+and approves the device and limits. Repeat the same command with `--wait` to
+finish an interrupted local wait. The old setup and pairing names do not resume
+an earlier ceremony; they return one deterministic refusal and the current
+command.
 
 ```bash
-visa agent create                                                # in the human's terminal — prints the pairing id
-visa agent claim <pairing-id> --runtime <name> --context "<one-line purpose>"
-visa agent verify <pairing-id> <code>                            # verifies the channel, opens the authorization page
-visa agent list                                                  # shows the activated runtime
+visa agent enroll --wait
+visa agent list
+visa agent show <agent-id>
 ```
 
-The browser authorization is the human gate: it shows the runtime and context and sets the **per-transaction and daily spend caps**. If the runtime lost its network response, `visa agent resume <pairing-id>` reprints the code and resumes delivery; `visa agent cancel [pairing-id]` abandons an unapproved request. Pairing credentials are stored on the agent machine with mode `0600`; the pairing link contains no credential.
+On macOS and Linux, the private identity key is stored under
+`~/.visa-cli/agents` in an owner-only directory with file mode `0600`. It is
+currently an exportable local file: copying it transfers identity proof, and
+losing it blocks new proofs because same-agent key recovery is not yet
+available. Protocol-v2 identity pairing fails closed on Windows until the CLI
+can apply and verify an owner-only Windows ACL. The pairing link contains no
+credential or private key.
 
-## Caps, then funding — strict order
+## Recover an existing account session
+
+`visa agent login` opens the Turnkey-first web sign-in for an existing v4
+account, then `visa agent login-claim` stores the returned account session in
+the OS keychain. `--wait` keeps the first command polling for the full
+15-minute browser window.
 
 ```bash
-visa wallet limits --per-transaction 0.25 --daily 2.00   # BEFORE any funds arrive
-visa wallet show                                          # address, network, policy
-visa wallet fund                                          # funding instructions
+visa agent login          # sign in and display the terminal confirmation code
+visa agent login-claim    # resume pickup after returning from the browser
+```
+
+This is account-session recovery, not agent pairing. It does not create or
+replace an identity key, delegate a wallet, select a card, set a budget, or
+grant spend authority. The pending PKCE verifier is kept under
+`~/.visa-cli/session-recovery/` in owner-only local state and is pinned to the
+exact web origin that started the flow.
+Session recovery currently fails closed on Windows until the CLI can apply and
+verify an owner-only ACL for this pending verifier.
+
+## Wallet capability: grant, caps, then funding
+
+Pairing never creates or repairs payment authority — the owner delegates it in
+a separate grant ceremony, and re-pairing is not a substitute:
+
+```bash
+visa agent login                                          # owner account session, once
+visa agent grant-wallet <agent-id> --ceiling 25 --per-transaction 1 --wait
+```
+
+The owner approves once in the browser; the runtime polls to activation and
+receives a delegated, capped, revocable signer (it can never mint one itself).
+`visa agent pause <agent-id>` temporarily blocks new Visa CLI card and wallet payments at the canonical authority service (mandates remain intact; resume with `visa agent resume <agent-id>`). `visa agent revoke <agent-id>` withdraws the current server grant without touching identity; provider-credential removal is a separate lifecycle.
+
+With a wallet delegated, set caps before funding:
+
+```bash
+visa wallet limits --agent <agent-id> --per-transaction 0.25 --daily 2.00
+visa wallet show --agent <agent-id>                       # address, network, policy
+visa wallet fund --agent <agent-id>                       # funding instructions
 ```
 
 Fund the wallet with USDC only after limits are set. Payments are gasless — no ETH is ever needed. Mainnet (Base) is the production default; set `VISA_V4_NETWORK=base-sepolia` for testnet, where `visa wallet fund` points at the faucet.
 
+Updating wallet limits preserves the active session budget window and its spent exposure. Reapplying the same limits is a no-op; `wallet limits` does not provide an implicit session-spend reset.
+
 ## Discover and pay
 
 ```bash
 visa find "current weather by city" --max 0.10   # discovery; spends nothing
 visa inspect <listing-id>                        # fetches the live 402 challenge; spends nothing
-visa pay <listing-id> --max 0.05                 # policy check → sign → settle
-visa activity                                    # recent payments
-visa receipt <receipt-id>                        # journaled proof with on-chain tx
+visa pay <listing-id> --agent <agent-id> --max 0.05 # policy check → sign → settle
+visa activity --agent <agent-id>                    # recent payments
+visa receipt <receipt-id> --agent <agent-id>        # journaled proof with on-chain tx
 
 # Advanced direct-URL mode uses the same probe, policy, and receipt path.
 visa inspect --url https://provider.example/paid
@@ -116,12 +233,33 @@ owned by `apps/mpp`, and VIC uses the checkout/mandate surface. Unsupported
 rails are refused before signing. The wallet exposes no agent key-export
 command.
 
+Each wallet-enabled agent has an isolated Turnkey credential, policy, journal,
+receipts, and paid-response directory. `--agent` / the MCP `agent` field may be
+omitted while exactly one wallet authority exists; with multiple authorities it
+is required so the CLI never guesses which agent can spend.
+
 ## MCP tools (v4 surface)
 
+Rows marked **Removed** are kept so old transcripts still resolve: the tool is
+no longer in `tools/list`, and a direct call by name answers
+`legacy_door_removed` naming the one door for a new agent,
+`visa agent enroll-protected`.
+
+A leftover direct-mode `turnkey.json` is not usable wallet authority.
+`agent_capabilities` reports wallet status `legacy_direct_mode` and unavailable;
+`get_status` directs even an already paired agent to `agent_enroll`. Have the
+owner complete `visa agent enroll` before attempting payment.
+
+Auth HTTP 410 responses with `code: route_retired` or `error: route_retired`
+are classified as `legacy_door_removed`. Follow `agent_enroll` /
+`visa agent enroll`; retrying the retired route does not restore it.
+
+
 | Tool | Description |
 |------|-------------|
-| `enroll_agent` | Two-step Verified Agent enrollment: default opens the browser flow with a hand-off challenge; `{"action":"claim"}` stores the enrollment credential on this device |
-| `wallet_status` | Wallet address, network, policy, and pairing state |
+| `agent_capabilities` | Derived live capability map (identity, wallet, card, mail, tap, subway) with upgrade paths |
+| `agent_login` | Start/claim the owner's device account session (required before a grant) |
+| `wallet_status` | Delegated wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |
 | `wallet_probe` | Fetch a service's live 402 challenge without paying |
@@ -129,6 +267,14 @@ command.
 | `wallet_directory_pay` | Directory find + pay in one call, same policy path |
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
+| `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
+| `setup_agent` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_start` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_status` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_resume` | **Removed.** Use `visa agent enroll-protected` |
+| `setup_cancel` | **Removed.** Use `visa agent enroll-protected` |
+| `agent_connect` | **Removed.** Authority is approved during `visa agent enroll-protected` |
+| `agent_connect_poll` | **Removed.** Authority is approved during `visa agent enroll-protected` |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |
@@ -163,23 +309,19 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Human-approved agent runtime pairing
-visa agent create
-visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
-visa agent verify <pairing-id> <code>
-visa agent resume <pairing-id>
-visa agent cancel [pairing-id]
+# Primary same-machine setup
+visa agent enroll --wait
+
+# Existing-account session
+visa agent login
 visa agent list
 
-# Human-approved VIC browser purchase
-visa checkout review <checkout-url> <amount>
-visa checkout pay <review-id>
-visa mandate start <checkout-url> <ceiling>
-visa mandate budget <ceiling>
-visa mandate list
+# Retired doors (they refuse — do not retry)
+# visa setup start / visa checkout pay / visa mandate start
 
 # MCP client connections
-visa connections
+visa connections                    # detected / configured / loaded
+visa connections --probe            # also start the Visa MCP server once and confirm it serves tools
 visa connect codex
 visa disconnect codex
 
@@ -200,14 +342,19 @@ visa-cli feedback                   # submit feedback
 
 | Path | Contents |
 |------|----------|
-| `~/.visa-mcp/agent-credential.json` | Verified Agent enrollment credential (mode 0600) |
-| `~/.visa-cli/` | Pairing / delegated signer credentials (mode 0600) |
-| `~/.visa-v4/policy.json` | Wallet spend policy — never edit by hand; use `visa wallet limits` |
+| `~/.visa-cli/pairings/` | Pending ceremony verifier or runtime identity key (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/agents/` | Activated agent identity, runtime private key, and signed activation credentials (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/session-recovery/` | Pending login-only PKCE verifier and pinned web origin (owner-only mode 0600 on macOS/Linux) |
+| `~/.visa-cli/removed-agents/` | Records of agents deleted on the server, kept 30 days then dropped. Written automatically; nothing reads it |
+| `~/.visa-mcp/agent-credential.json` | Legacy checkout-credential compatibility record (mode 0600) |
+| `~/.visa-v4/agents/<agentId>/` | Per-agent Turnkey credential, spend policy, reservation journal, receipts, and paid responses — never edit by hand |
 
 ## Troubleshooting
 
-**Wallet commands report pairing is required**
-Payments on a production network require the paired delegated credential — complete enrollment and pairing first. There is no local fallback wallet on mainnet, by design.
+**Wallet commands report that payment setup is required**
+Identity pairing deliberately grants no payment authority. Complete the
+separate wallet/instrument and spend-policy setup when available; pairing again
+will not upgrade an identity into a signer.
 
 **`policy refused` from `pay`**
 A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet limits` with the human's approval.
@@ -215,12 +362,101 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 **`expected 402 from <url>`**
 That URL isn't payment-gated — probe the service's actual paid route (`wallet_probe` / `visa find`).
 
-**Pairing ended `expired` or `cancelled`**
-The ceremony timed out — re-run `visa agent create` and claim the new pairing id.
+**Setup ended `expired` or `cancelled`**
+The ceremony timed out — restart with `visa agent enroll --wait`. Do not retry
+`visa setup start`; that door is removed.
 
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.
 
+**Branching on failures from `--format json`**
+Every failure envelope carries `code`, `kind`, `fix`, and `nextAction`. Branch on
+`code` (stable, append-only) and `kind` (`caller` = fix it yourself and retry;
+`platform` = stop and escalate to a human), never on the English `error` text.
+Deterministic preconditions always resolve to a specific code:
+
+| Condition | `code` | `kind` |
+|-----------|--------|--------|
+| Not logged in (`find`, `activity`, `receipt`) | `session_required` | `caller` |
+| No wallet grant on this runtime (`wallet show\|fund\|limits`, `pay`, `--local` reads) | `wallet_credential_required` | `platform` |
+| Wallet grant approved but not fully delivered (`pay`) | `wallet_delivery_required` | `platform` |
+| Local identity record missing for the selected agent (`pay`) | `identity_required` | `caller` |
+| Identity root migrated; direct signing retired (`pay`) | `universal_required_managed_only` | `platform` |
+| Managed wallet limits are owner-set (`wallet limits` with caps) | `managed_limits_owner_controlled` | `platform` |
+| Listing is not x402 (`pay <listing-id>`) | `invalid_argument` | `caller` |
+| Activity id not found or not attributable (`receipt`) | `activity_entry_not_found` | `caller` |
+
+`unspecified_error` (`platform`) is reserved for failures the CLI cannot
+classify and is intentionally kept on two guards: a wallet binding that does not
+match the signed-in owner profile (an integrity refusal, not a caller state),
+and a `wallet limits` change that would broaden policy without the operator's
+`VISA_V4_WALLET_ALLOW_POLICY_RAISE=1`. Both need a human; escalate rather than retry.
+
 ## Monorepo context
 
 Request routing (MCP vs MPP vs web): [docs/agents/ARCHITECTURE.md](../../docs/agents/ARCHITECTURE.md). Branches and deploy: [docs/agents/PIPELINE.md](../../docs/agents/PIPELINE.md). Contributor workflow: [AGENTS.md](../../AGENTS.md), doc index: [docs/agents/README.md](../../docs/agents/README.md).
+
+### Native device TAP lifecycle
+
+`visa agent keychain connect-device --agent <name-or-id>` selects this device for
+identity-only TAP signing after the existing browser owner ceremony verifies its
+certificate, delegation, Gate authorization and native key binding. The selected
+native profile serves actual TAP consumers; unavailable custody or invalid selected
+metadata fails closed. Wallet/card keys and payment authority remain separate.
+
+`--agent` accepts either a locally paired agent or the stable UUID of a protected
+agent created by `visa agent enroll`; the latter has no Auth-paired record
+and resolves its owner root from the independently claimed selection. The device
+ceremonies (`connect-device`, `renew`, `resume`, `revoke --purpose tap`) travel the
+public identity-device relay with native possession proofs, so a missing or expired
+`visa agent login` never blocks them; the owner approval and owner revocation pages
+remain required. Hosted purposes (`card:vic`, `wallet:x402`, hosted `tap`, `subway`)
+still need a locally paired agent and its Auth session.
+
+`visa agent keychain renew --agent <name-or-id> --purpose tap` creates an independently
+addressed successor for the same runtime and opens the owner review page. Both keys
+survive interruption. `visa agent keychain resume --agent <name-or-id>` resumes the
+exact pending operation, including a locked-keychain cleanup retry. `--no-open`
+prints the owner URL. Expired locators require another owner ceremony using the
+preserved successor key. `keychain status` reports the selected profile and local
+renewal phase; it is a local projection, not a live authority check.
+
+Only public certificates/proposals and opaque native handles enter the durable
+renewal journal. Selection changes after verified owner activation. The previous
+handle is deleted only after possession-authenticated protected readback proves
+that exact prior generation retired; uncertain readback preserves it. Native
+custody uses the configured OS store or explicit headless KEK descriptor.
+
+`visa agent keychain revoke --agent <name-or-id> --purpose tap` opens an independent
+owner review for the selected native runtime. The protected owner action stops current
+and pending TAP authority, including an interrupted renewal. Local locks or unreadable
+recovery journals do not prevent opening the owner review. The CLI preserves every known
+handle until exact terminal readback, then deletes keys idempotently; `keychain resume`
+retries locked cleanup. A public revoked selection tombstone prevents legacy TAP fallback.
+After cleanup completes, `connect-device` explicitly enrolls a new runtime.
+
+### Native Subway owner certificates
+
+Subway certificate issuance and renewal retired with the runtime certificate plane
+(UNIFY D2); `agent keychain renew` and `revoke` accept only `--purpose tap`. A Subway
+certificate an earlier build already selected keeps signing through the native
+financial-presence key while its owner signature stays valid: WebSocket messages and
+direct libp2p Noise authentication use structured native signing operations, and an
+invalid, expired, revoked, or unavailable selection fails closed. Existing unpaired
+mesh usage retains its current behavior.
+
+### Protected managed-wallet rollout
+
+Protected authority onboarding is opt-in with `visa config set wallet.protectedAuthority true` until its deployment is ready. The default retains the existing fresh-enrollment and locally verified legacy managed-wallet path. This setting never downgrades saved protected devices: native pending/active/history records and protected wallet bindings always require protected recovery, including when the authority is unavailable. Existing direct configurations retain their scoped local-credential checks.
+
+A managed reconnect without verifiable local enrollment history requires recovery; restore the saved device records or complete independent owner classification through the protected authority deployment. Auth's execution-mode response alone cannot classify that missing history. No automatic retry through legacy setup occurs after an authority error.
+
+### Fresh protected native agent
+
+Start from an empty CLI home with:
+
+```sh
+visa agent enroll --wait
+```
+
+Enter the terminal code in the existing browser owner ceremony, then approve the native device and its spending limits. Repeat the same command to resume after interruption; use `--no-open` to print links. The CLI uses its build-channel Auth and web origins; there is no caller-selected Authority origin. Auth forwards the exact protected request bytes to the private Authority, while the owner stamps and device proofs remain end-to-end. No Auth login is needed. An unclaimed expired request can be replaced with `--restart`. This path creates a new protected namespace and preserves any existing Auth login profile.