@visa/cli 4.1.0-rc.331 → 4.1.0-rc.333

package/README.md

@@ -367,6 +367,34 @@ That URL isn't payment-gated — probe the service's actual paid route (`wallet_
 The ceremony timed out — restart with `visa agent enroll --wait`. Do not retry
 `visa setup start`; that door is removed.
 
+**`session` is false with a certificate error, but the website works**
+Codes like `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `SELF_SIGNED_CERT_IN_CHAIN` or
+`DEPTH_ZERO_SELF_SIGNED_CERT` mean this machine would not trust the connection,
+so the request never left it. Visa is not down, no status page can show it, and
+neither retrying nor signing in again will help. A network that inspects TLS
+traffic does this, and browsers on the same machine still work because they read
+the OS trust store and Node does not. Point Node at your network's root
+certificate and run the command again:
+
+```bash
+# macOS: export the roots your organization installed
+security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
+export NODE_EXTRA_CA_CERTS=~/corp-ca.pem
+visa agent preflight
+```
+
+Add the `export` line to your shell profile to keep it. If your IT team supplies
+the root certificate as a file, point `NODE_EXTRA_CA_CERTS` at that instead.
+Never disable certificate verification to get past this.
+
+**`visa agent list` prints nothing but the Console shows an agent**
+Agent records live on the machine that enrolled them, and the identity key never
+leaves it. A second machine legitimately holds none. `visa agent list` asks the
+server and says which case you are in: your account is empty, your agents are
+enrolled elsewhere (it names them), or the server could not be reached. Only the
+first means `visa agent enroll` is the right next step; running it in the other
+two adds another agent rather than recovering the one you have.
+
 **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.