@mercuryo-ai/magicpay-cli 0.1.3 → 0.1.5

package/README.md

@@ -1,56 +1,96 @@
 # @mercuryo-ai/magicpay-cli
 
-Payment-only MagicPay CLI for session, secrets, and protected-form completion.
+Protected-form CLI for prepared browser pages.
 
-`magicpay` is the payment-only MagicPay CLI surface for:
+MagicPay CLI is for the part of a workflow that handles approved stored values
+on a login, identity, or payment form that is already open in the browser.
 
-- gateway setup and health checks;
-- workflow session lifecycle;
-- secret catalog, request, poll, protected fill, and guarded submit/observe flow;
-- narrow browser attachment and protected-form completion on an already prepared page.
+Use it when you need to:
+
+- attach to an already prepared browser page;
+- bind the page to a workflow session;
+- discover the supported protected form;
+- request approval for stored values;
+- fill the approved values through the guarded protected-form flow.
+
+MagicPay is focused on the protected step itself. Reach the target page first
+with another browsing tool or an existing browser session, then hand the form
+over to MagicPay.
 
 ## Install
 
 ```bash
-npm i -g @mercuryo-ai/magicpay-cli
-magicpay --help
+npm i -g @mercuryo-ai/magicpay-cli@latest
+```
+
+## API Setup
+
+Configure the API key once:
+
+Get an account and API key at `https://agents.mercuryo.io/signup`.
+
+```bash
+magicpay init <magicpay-api-key>
+magicpay status
+```
+
+`magicpay status` is the normal readiness check before a protected-form task.
+Use `magicpay doctor` only when `init` or `status` still fail and you need to
+inspect the local config.
+
+## Core Flow
+
+1. `magicpay attach <cdp-url>`
+2. `magicpay start-session [name]`
+3. `magicpay find-form`
+4. `magicpay get-secrets-catalog` only if candidates are missing or stale
+5. `magicpay request-secret <fillRef> <storedSecretRef> --merchant-name <name>`
+6. `magicpay poll-secret <requestId>`
+7. `magicpay fill-secret <fillRef> <requestId>`
+8. `magicpay submit-form <fillRef>` only if the guarded fill flow explicitly
+   leaves submission unfinished
+9. `magicpay end-session` when the protected step is complete
+
+Example:
+
+```bash
+magicpay attach <cdp-url>
+magicpay start-session "Checkout"
+magicpay find-form
+magicpay request-secret <fillRef> <storedSecretRef> --merchant-name "Example Store"
+magicpay poll-secret <requestId>
+magicpay fill-secret <fillRef> <requestId>
+```
+
+If `find-form` does not return the right candidates, refresh the catalog and
+retry:
+
+```bash
+magicpay get-secrets-catalog
+magicpay find-form
 ```
 
-## Current surface
-
-- `init`
-- `status`
-- `attach`
-- `start-session`
-- `end-session`
-- `find-form`
-- `get-secrets-catalog`
-- `request-secret`
-- `mock-approve-secret`
-- `mock-deny-secret`
-- `poll-secret`
-- `fill-secret`
-- `submit-form`
-
-Browser attach happens over CDP:
-
-- `magicpay attach <cdp-url>`
-
-`magicpay fill-secret` now performs a post-fill refresh, auto-submits when it
-can resolve one live form-bound submit control, and returns a follow-up observe
-result when submission happens. `submit-form` remains available as a manual
-recovery surface.
-
-`magicpay status` stays quiet about CLI updates by default. When a newer npm
-release is available, it includes a short English notice and the suggested
-update command.
-
-## Architecture boundary
-
-- `magicpay` is the operator CLI for workflow sessions, approvals, protected
-  secret handling, and narrow form completion on the current page.
-- `@mercuryo-ai/agentbrowse` owns browser primitives and the reusable browser
-  session store API.
-- `@mercuryo-ai/magicpay-sdk` owns reusable MagicPay API and flow helpers.
-- `@mercuryo-ai/magicpay-cli` owns branded payment CLI orchestration and the
-  payment-safe command UX on top of the shared `~/.magicpay` home.
+## Operating Rules
+
+- Start from a prepared page, not from generic browser navigation.
+- Use `magicpay status` before a new protected-form task.
+- Re-run `magicpay find-form` after meaningful page changes.
+- Treat `magicpay submit-form` as manual recovery, not as the default happy
+  path.
+- `mock-approve-secret` and `mock-deny-secret` are development-only helpers,
+  not production approval flows.
+
+## Command Groups
+
+- Setup and diagnostics: `init`, `status`, `doctor`
+- Session control: `attach`, `start-session`, `end-session`
+- Protected form flow: `find-form`, `get-secrets-catalog`, `request-secret`,
+  `poll-secret`, `fill-secret`, `submit-form`
+- Development-only helpers: `mock-approve-secret`, `mock-deny-secret`
+
+## Companion Tools
+
+- You only need browser navigation, observation, or extraction:
+  use `@mercuryo-ai/agentbrowse-cli`
+- You want one CLI for both browser work and protected fills:
+  use `@mercuryo-ai/magicpay-agent-cli`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mercuryo-ai/magicpay-cli",
-  "version": "0.1.3",
-  "description": "MagicPay CLI — payment/session/secrets shell with narrow protected-form completion",
+  "version": "0.1.5",
+  "description": "Protected-form CLI for prepared browser pages",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -23,16 +23,24 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MercuryoAI/skills.git"
+  },
+  "homepage": "https://agents.mercuryo.io/docs/agents",
+  "bugs": {
+    "url": "https://github.com/MercuryoAI/skills/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
     "@browserbasehq/stagehand": "^3.0.0",
     "dotenv": "^16.4.0",
-    "@mercuryo-ai/captcha-solver": "0.1.1",
-    "@mercuryo-ai/magicpay-sdk": "0.1.0-test.3",
-    "@mercuryo-ai/magicpay-home": "0.1.4",
-    "@mercuryo-ai/agentbrowse": "0.2.50"
+    "@mercuryo-ai/magicpay-sdk": "0.1.0-test.6",
+    "@mercuryo-ai/magicpay-home": "0.1.6",
+    "@mercuryo-ai/agentbrowse": "0.2.53",
+    "@mercuryo-ai/captcha-solver": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",