@tempoxyz/mercator 0.0.188 → 0.0.190

package/README.md

@@ -1,225 +1,51 @@
 # `@tempoxyz/mercator`
 
-Install and diagnose the Mercator remote MCP server, desktop plugin, and a session-capable payment
-wallet across supported agent clients.
+Set up the [Mercator](https://mercator.tempo.xyz) remote MCP server and its optional payment wallet
+for supported agent clients.
+
+## Install
 
 ```sh
 curl -fsSL https://mercator.tempo.xyz/install.sh | sh
-mercator doctor
 ```
 
-The installer places the CLI under `~/.local`, links `mercator` into `~/.local/bin`, and launches
-the same interactive setup flow. Pass CLI arguments after `sh -s --`, for example:
+Or install the npm package with Node.js 24 or later:
 
 ```sh
-curl -fsSL https://mercator.tempo.xyz/install.sh | sh -s -- --client codex
-```
-
-## Setup flow
-
-```mermaid
-flowchart LR
-    START["Start setup"] --> DETECT["Detect supported clients"]
-    DETECT --> PLUGIN["Bootstrap local desktop plugin"]
-    PLUGIN -->|Agent CLI found| CONFIGURE["Install Mercator MCP entry"]
-    PLUGIN -->|No agent CLI| GUIDANCE
-    CONFIGURE --> GUIDANCE["Update managed guidance"]
-    GUIDANCE --> WALLET{"Ready payment runtime?"}
-    WALLET -->|Yes| VERIFY["Run readiness checks"]
-    WALLET -->|No| CHOICE{"Enable paid jobs now?"}
-    CHOICE -->|Yes| ONBOARD["Create local wallet or connect Tempo Wallet"]
-    CHOICE -->|Not yet| VERIFY
-    ONBOARD --> VERIFY
+npm install --global @tempoxyz/mercator
+mercator setup
 ```
 
-Supported clients:
-
-- Codex
-- Claude Code
-- Gemini CLI
-- Cursor
-- VS Code
-- Windsurf
-- Cline
-- Continue
-- OpenClaw
-- Hermes
-
-Normal setup always bootstraps the bundled [Mercator plugin](../../plugins/mercator) into Codex's
-user-local plugin index. Nothing is published, and users do not need to create or manage a
-marketplace. The plugin connects Codex or ChatGPT desktop directly to the production Mercator MCP
-server without requiring the Codex CLI. Restart ChatGPT desktop after installation. Use
-`--no-plugin` for a CLI-only installation, such as CI or a headless server.
-
-Selection options:
-
-| Option | Behavior |
-| --- | --- |
-| No subcommand | Bootstrap the local plugin and run interactive `setup` |
-| No client option | Configure every detected client |
-| `--client <name>` | Configure one named client; repeatable |
-| `--dry-run` | Preview configuration changes |
-| `--force` | Recreate Mercator registrations and refresh managed guidance |
-| `--yes` | Apply setup without the interactive confirmation |
-| `--no-plugin` | Skip local desktop plugin installation |
-| `--no-agents` | Skip Codex `AGENTS.md` guidance |
-| `--remove-agents` | Remove installed Codex guidance |
-
-Setup guarantees:
-
-- Reuses matching existing configuration safely.
-- Serializes plugin index updates and preserves unrelated local plugins.
-- Shows a rotating [adamsky/globe](https://github.com/adamsky/globe) with live setup progress.
-- Keeps the globe active while the interactive client picker is open.
-- Confirms the complete setup plan before its first mutation.
-- Treats payment setup as optional: discovery, descriptions, quotes, polling, and feedback remain
-  available when wallet onboarding is deferred.
-- `--force` never removes or recreates wallets, keys, accounts, balances, sessions, or shared MPP
-  plugins.
-- Wallet and native payment checks remain read-only during forced setup.
-
-Example:
+Setup detects supported clients, installs the Mercator MCP integration, and verifies free service
+discovery. Target one client with `--client` or list available clients with `mercator clients`.
 
 ```sh
-mercator setup --client codex --force
+mercator setup --client codex
+mercator doctor
 ```
 
-## Codex guidance
-
-Codex setup maintains a bounded block in the active global `AGENTS.md`:
-
-- Explains when to use Mercator.
-- Requires quote and budget approval before paid execution.
-- Excludes local files and repository work.
-- Preserves content outside `mercator:begin` and `mercator:end` HTML comments.
-- Leaves an existing `AGENTS.override.md` untouched and reports when it shadows the guidance.
-- Applies new guidance to the next Codex session.
-
-Mercator always manages persistent `AGENTS.md`; use `--no-agents` to skip installation or
-`--remove-agents` to remove the managed block.
+## Payment wallet
 
-## Payment runtime selection
-
-Mercator uses one active payment wallet. `mercator wallet connect` and `mercator wallet create`
-record that selection. Existing installations without an active selection continue using their
-Tempo Wallet credentials when present, otherwise their local disk wallet.
-
-| Runtime | Paid-request path | Session behavior |
-| --- | --- | --- |
-| Local disk wallet | `mercator submit` | Uses Mercator-owned Accounts SDK storage |
-| Tempo Wallet | `mercator submit` | Uses a scoped access key authorized through Accounts |
-| OpenClaw | Native `mpp_fetch` | Uses official `openclaw-mpp` integration |
-| Hermes | Native `mpp_fetch` | Uses official `hermes-mpp` integration |
-
-Mercator requires neither the Tempo Wallet CLI nor the MPPX CLI. Connecting or creating an unfunded
-wallet opens Mercator's MACH funding page with its address selected. The page offers fixed amounts
-and redirects to Stripe-hosted Checkout with card and Apple Pay support. Run `mercator wallet fund`
-to open it again later.
-
-OpenClaw and Hermes setup:
-
-- Installs or verifies the official
-  [openclaw-mpp](https://github.com/tempoxyz/openclaw-mpp) or
-  [hermes-mpp](https://github.com/tempoxyz/hermes-mpp) integration.
-- Preserves existing Hermes allowed origins before adding Mercator.
-
-## Wallet onboarding
-
-Run wallet setup separately:
+Payment setup is optional. Discovery, service descriptions, quotes, result polling, and feedback do
+not require a wallet.
 
 ```sh
-mercator wallet
-mercator wallet connect
-mercator wallet create
-mercator wallet status
+mercator wallet          # Connect or create a wallet
+mercator wallet status   # Check readiness
 mercator wallet balance
 mercator wallet fund
 ```
 
-With no active wallet, normal setup asks whether to connect an existing wallet, create one on this
-machine, or defer payment setup. The standalone `mercator wallet` command requires a wallet choice.
-`wallet connect` opens the Accounts SDK device flow and stores only its Mercator access key locally.
-Local-wallet private material, connected-wallet access keys, and the active selection share the
-Accounts SDK filesystem store at `~/.mercator/wallet.json`, secured with user-only file permissions.
-
-`mercator wallet status` inspects readiness without onboarding. `mercator wallet`,
-`mercator wallet balance`, and `mercator wallet fund` report the active wallet's balances. Creating
-or connecting an unfunded wallet opens Mercator's card onramp; inspecting an existing wallet does
-not.
-
-## Paid job submission
-
-```mermaid
-flowchart LR
-    MCP["MCP: discover + quote"] --> REST["POST /v1/jobs"]
-    REST --> PAYMENT["Mercator wallet"]
-    PAYMENT --> POLL["MCP or REST: poll result"]
-```
-
-Recommended path:
-
-- Use MCP for discovery, quoting, and result polling.
-- Use the bounded `mercator submit` handoff returned by `create_job`.
-- The REST endpoint offers both `tempo/session` and `tempo/charge`.
-- Some MCP harnesses cannot answer the payment-required protocol error from `create_job`.
-- Use `mpp_fetch` in OpenClaw or Hermes.
-- Other clients use the same Mercator wallet created during setup.
-
-## Diagnostics
-
-`doctor` performs read-only checks:
-
-- MCP transport.
-- Six-tool contract.
-- Free service discovery.
-- Unsigned Mercator session challenge.
-- Local wallet session capability.
-- Local plugin path, installed and expected versions, registration state, and desktop restart
-  requirement.
-
-Plugin state is advisory so `--no-plugin` installations remain healthy. Funding is reported
-separately from session capability. Paid execution remains `not_verified`. Setup succeeds when the
-free MCP transport and discovery checks pass; `doctor` remains the strict check for transport,
-discovery, and payment-wallet readiness.
-
-Interactive setup uses stable status symbols:
-
-| Symbol | Meaning |
-| --- | --- |
-| `✓` | Ready or completed |
-| `→` | In progress or planned |
-| `!` | Action required |
-| `○` | Skipped or not checked |
-| `✗` | Failed |
+For paid jobs, use the bounded `mercator submit` command returned by Mercator's `create_job` tool.
 
 ## Uninstall
 
 ```sh
-mercator uninstall --client codex
-mercator uninstall --client openclaw --client hermes
-mercator uninstall --dry-run
 mercator uninstall
 ```
 
-Uninstall behavior:
-
-- Removes only the `mercator` MCP entry, CLI-managed local plugin bundle and registration, and
-  installer-managed Codex guidance.
-- Preserves other MCP servers, local plugin entries, and user instructions.
-- Preserves wallets, keys, balances, sessions, and shared MPP plugins.
-- `--dry-run` previews removal.
-- A scoped uninstall removes the plugin only for `--client codex`; an unscoped uninstall removes it
-  with all other Mercator integrations.
-- VS Code removal covers the default user profile; use **MCP: Open User Configuration** for other
-  profiles.
+Wallets, keys, balances, and sessions are preserved.
 
-## Command discovery
-
-```sh
-mercator clients
-mercator --help
-mercator --llms
-```
+## Documentation
 
-The CLI uses Incur for validated options, generated help, machine-readable manifests, structured
-errors, shell completions, and agent integrations.
+See the [Mercator documentation](https://mercator.tempo.xyz/docs) or run `mercator --help`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tempoxyz/mercator",
-	"version": "0.0.188",
+	"version": "0.0.190",
 	"description": "Install Mercator MCP and prepare its payment wallet",
 	"type": "module",
 	"bin": {