@visa/cli 4.1.0-rc.21 → 4.1.0-rc.211

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

@@ -0,0 +1,93 @@
+# Running Visa pairing in OpenClaw and Hermes
+
+`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the pairing v2 skill is
+runtime-agnostic. OpenClaw, Hermes, and any runtime that can execute the `visa` CLI or
+mount its MCP server all use the same identity-only enrollment ceremony.
+
+## 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, three surfaces
+
+All supported surfaces share the same local pending record and pairing v2 protocol:
+
+1. OpenClaw: `pair_agent_start` / `pair_agent_poll`.
+2. Visa MCP server: `enroll_agent` with `action: "start"` / `action: "claim"`.
+3. Raw CLI: `visa agent enroll --format json` /
+   `visa agent enroll-claim --format json`.
+
+The start operation returns an authorization URL for the human. The browser receives only
+that URL. The runtime retains its private Ed25519 key and local claim material. Polling
+resumes the same pending identity and safely replays the same signed request after an
+interruption.
+
+On activation, use `agentId` as the stable identity. `identityKeyJkt` identifies the
+currently bound Ed25519 public key and can change after key rotation. Activation means the
+identity is paired only; payment methods, email, and tap bindings are separate future or
+follow-up configuration.
+
+## 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`):
+
+```yaml
+mcp_servers:
+  visa-cli:
+    command: node
+    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+```
+
+## Runtime setup map
+
+| Runtime       | Setup and pairing surface                                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| OpenClaw      | Install `@visa/visa-cli-openclaw` for the `pair_agent_*` tools and bundled skill. The plugin auto-mounts the Visa MCP server. The MCP or raw CLI surfaces remain valid alternatives. |
+| Hermes        | Run `visa-cli connect hermes`, install `pair-visa-agent/SKILL.md` under `~/.hermes/skills/`, and use `enroll_agent`. `hermes claw migrate` can import an existing OpenClaw setup.    |
+| Codex         | Run `visa agent skill --runtime 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`, mount the same MCP server if supported, or use the raw `visa agent enroll` and `visa agent enroll-claim` commands as the universal fallback.                   |
+
+The skill itself can be installed with `visa agent skill`. Pass `--runtime <name>` or
+`--dir <path>` when auto-detection is not appropriate, then reload the runtime.
+
+## Optional Hermes wrapper
+
+A Hermes Python plugin may expose the same `pair_agent_start` and `pair_agent_poll` names
+by calling the canonical raw CLI commands and registering tools with
+`ctx.register_tool(...)`. It is optional: the MCP server and skill already expose the
+same protocol and persisted pairing state without a second implementation.