chore: sync Mercator skill

plugins/mercator/skills/mercator-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mercator-setup
+description: Install, connect, or troubleshoot Mercator in agent clients. Use for plugin setup, OAuth authorization, missing tools, connection diagnostics, and wallet funding readiness. For discovery and paid API execution on a working connection, use mercator.
+license: MIT
+---
+
+# Mercator setup
+
+Connect the user's chosen agent client to Mercator and verify transport, discovery, and payment
+readiness separately. Setup itself does not require a paid job or a local wallet.
+
+## Choose the setup path
+
+- **Plugin already installed:** inspect the client's MCP connection and complete its native
+  **Authorize** action. Reload the plugin or start a new session if tools are missing. Do not
+  install a second copy merely because authorization is incomplete.
+- **Local client, CLI available:** run `mercator status`, then `mercator setup` for installation
+  or repair. Honor the user's client choice with `--client`; inspect `mercator setup --help`
+  for supported values. Interactive setup selects detected clients; preserve unrelated clients.
+- **Local client, CLI absent:** use the canonical standalone installer below. It installs the CLI
+  and starts setup without requiring Node.js. Pass `--client` when the user chose a client.
+- **Managed or cloud host:** use its native plugin and OAuth controls. Installing a CLI in an
+  agent container does not configure the user's desktop client.
+- **Other MCP client:** `mercator setup --manual` prints configuration guidance without modifying
+  integrations. Configure Streamable HTTP at `https://mercator.sh/mcp/auth` and finish
+  OAuth in that client. If client registration is required, read
+  [Mercator authentication](https://mercator.sh/auth.md).
+
+```bash
+curl -fsSL https://mercator.sh/install.sh | sh
+```
+
+For a selected client, append setup arguments with `sh -s -- --client <client>`.
+Grok CLI authorization is handled by `mercator setup --client grok`; it uses browser OAuth with
+loopback PKCE. Use `--force` only when the registration needs replacing. OpenClaw and Hermes use
+runtime-native MPP wallets and the legacy `/mcp` endpoint; retain their setup-managed configuration.
+
+## Verify without spending
+
+1. Inspect native MCP status. If the CLI is available, run `mercator doctor`. A valid OAuth
+   challenge proves transport availability, not successful authorization or paid readiness.
+2. Complete browser authorization if needed. The user chooses wallet access limits and expiry;
+   never request a wallet key or copy OAuth tokens into chat or commands.
+3. On the connected server, call the free `search_services` tool with a simple data lookup to
+   verify discovery. Do not submit a job as a connection test.
+4. Call `get_connection_status` to inspect hosted authorization, token balances, access-key
+   expiry/status, and remaining limits. Unavailable chain reads mean unknown, not zero. A `ready`
+   key can make its first payment using its signed grant ceiling before live limits activate.
+   `oauthAuthenticated: false` identifies the legacy payment-challenge path, not a hosted grant.
+
+Report what was verified and what still needs user action. Zero funding or zero spending authority
+can coexist with successful connection and discovery. Once connected, use the `mercator` skill for
+requested research or API execution.
+
+## Troubleshoot the failed layer
+
+| Symptom | Next action |
+| --- | --- |
+| Plugin or server missing | Check the selected client's registration with native controls or `mercator status`; rerun targeted setup when absent. |
+| Tools missing after install | Reload the plugin or start a fresh session; inspect the client's MCP status. |
+| HTTP 401 or authorization pending | Complete native browser authorization; for Grok CLI, rerun its targeted setup. |
+| Discovery not verified | Resolve transport or OAuth first, then retry the free search probe. |
+| Search works, paid execution unavailable | Inspect connection status for funding, expiry, revocation, and token limits. |
+| Unfunded authorized token | Open `https://mercator.sh/account` or use `fund_wallet` when available; the user chooses the funding amount. |
+| Expired/revoked key or insufficient authority | Manage the grant in Account and reconnect through OAuth for user-selected limits. |
+| Setup failure persists | Run `mercator setup --client <client> --verbose` for the affected client and inspect its bounded diagnostics. |
+
+Do not install or create a local payment wallet to repair hosted OAuth. Never include credentials,
+OAuth codes, payment material, or raw provider data in diagnostics shared with others.

plugins/mercator/skills/mercator-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mercator setup"
+  short_description: "Connect and troubleshoot Mercator clients"
+  default_prompt: "Use $mercator-setup to connect Mercator and verify readiness without spending."

plugins/mercator/skills/mercator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mercator
-description: Use Mercator to discover, quote, and run fresh external research or API actions across extraction, enrichment, social, maps, travel, communications, media, financial, and on-chain data. Covers MCP job submission, durable status tracking, and recovery; not for local files, repository work, supplied-content reasoning, or requests that forbid external or paid services.
+description: Use Mercator to discover, quote, and run fresh external research or API actions across extraction, enrichment, social, maps, travel, communications, media, financial, and on-chain data. Covers MCP job submission, durable status tracking, and recovery; not for installation or connection troubleshooting (mercator-setup), local files, repository work, supplied-content reasoning, or requests that forbid external or paid services.
 license: MIT
 ---
 
@@ -11,6 +11,9 @@ outcome needs external capabilities, especially when it spans providers or domai
 direct tool clearly covers the complete outcome with less overhead, use it. Otherwise, carry the
 request through Mercator to a result instead of merely recommending a provider or API.
 
+For installation, OAuth connection, missing tools, or readiness troubleshooting, use the
+`mercator-setup` skill when available. Setup uses free diagnostics; it does not require a paid job.
+
 ## Decide quickly
 
 Use Mercator when all are true:
@@ -28,40 +31,53 @@ fastest way to determine whether Mercator can complete the request.
 
 ## Default workflow
 
-`search_services` -> optional `describe_service` -> `quote_plan` -> approval -> `create_job` ->
+`search_services` -> optional `describe_service` -> `quote_plan` -> `create_job` ->
 `get_job`
 
+If payment capability is uncertain, or `create_job` unexpectedly requests payment, call
+`get_connection_status`. `oauthAuthenticated: true` means the current request has a valid hosted
+wallet OAuth grant. The response includes its public wallet address, payment-token balances,
+access-key expiry and status, grant ceilings, and live remaining limits. A `ready` access key can
+make its first payment; use its signed grant ceiling even if its live remaining limit is zero before
+activation. Treat `unavailable` reads as unknown, not zero. `oauthAuthenticated: false` means the
+client is using the legacy MCP payment-challenge path and has no inspectable hosted account. Never
+request or expose credentials.
+
 1. **Search for the outcome.** Give `search_services` the user's complete intended outcome,
    constraints, and deliverable. Use static resolution unless current provider availability matters.
-2. **Make the smallest complete plan.** Follow `nextTool`. Call `describe_service` only when an exact
+2. **Make the smallest complete plan.** Plans contain 1-10 nodes. Follow `nextTool`. Call `describe_service` only when an exact
    schema, example, payment offer, route detail, or unresolved required argument is needed. Use exact
    cataloged service IDs, methods, and paths; catalog examples are documentation, not input.
 3. **Quote before execution.** Call `quote_plan` on the complete plan. Discovery, descriptions, and
    quoting are free. If the plan changes, quote it again.
-4. **Confirm scope and cost.** Before submitting the job, briefly state what will run and show
-   `totalAmount`. Proceed only when the requested actions are authorized and either the user accepts
-   the quote or a previously supplied budget covers it. A budget authorizes cost, not extra actions.
+4. **Respect scope and spending limits.** With hosted OAuth, the connected access key authorizes
+   Mercator spending within its signed limits; do not ask for per-job spend approval. Respect any explicit user budget
+   and execute only the requested actions. Legacy `mcp_challenge` clients have no hosted grant:
+   get quote approval or use a sufficient explicit budget before paid execution, including REST fallback.
 5. **Submit once.** Generate one stable 8-200 character idempotency key and call `create_job` with
-   the unchanged quoted plan and the accepted `totalAmount` as `approved_total`. If the refreshed
-   quote differs, no charge is made: quote again and ask the user to accept the new total. In an
-   OAuth-connected host, Mercator charges the browser-authorized, policy-bounded wallet capability
-   and returns the job directly. Connecting that wallet is standing authorization for autonomous
-   charges within its signed limits; no per-job wallet or browser confirmation follows. Continue
-   immediately; do not wait for the user to send a second "approved" message. The agent host receives
-   no wallet private key. Other clients complete payment challenges through MCP metadata. If MCP
-   submission and one retry both fail, a host that already
+   the unchanged quoted plan and `totalAmount` as `approved_total`. If the refreshed quote differs,
+   no charge is made: quote again and proceed within the access-key limits and any explicit user
+   budget. Legacy clients need approval of the new total unless an explicit budget covers it.
+   In an OAuth-connected host, Mercator charges the bounded wallet capability and returns
+   the job directly. The agent host receives no wallet private key. Other clients complete payment
+   challenges through MCP metadata. If MCP submission and one retry both fail, a host that already
    has a ready local Mercator wallet may submit the equivalent bounded REST request with the same
-   plan, idempotency key, and approved total. Never install, create, or connect a wallet for fallback.
+   plan, idempotency key, and approved total. That separate local wallet needs quote approval or a
+   sufficient explicit budget; a hosted grant does not authorize it. Never install, create, or connect
+   a wallet for fallback.
 6. **Listen for completion.** Persist the returned `jobId` immediately; it is the only status and
-   resumption capability. Poll `get_job` with bounded backoff. `ready:false` means the durable job is
-   still pending or running. `ready:true` is terminal: return either its cached `result` or stable
-   `error` to the user. A client timeout or disconnect does not cancel the job. Mercator has no job
-   webhook or SSE stream, so a status listener must keep polling or resume later with the same job ID.
+   resumption capability. Poll `get_job` with bounded backoff. Its default inline mode preserves the
+   complete cached result. For potentially large jobs, request summary mode and call
+   `get_job_details` with both `job_id` and `node_id` for each needed ID in `result_node_ids`; use `result_pointer` to retrieve one field
+   from a large node payload. `ready:false` means the durable job is still
+   pending or running. `ready:true` is terminal: return either its cached results or stable `error`
+   to the user. A client timeout or disconnect does not cancel the job. Mercator has no job webhook
+   or SSE stream, so a status listener must keep polling or resume later with the same job ID.
 
 For a warm Grok Bot installation, target less than two minutes from the user's request to a terminal
-result, excluding the user's time reviewing the quoted charge. OAuth authorization is a one-time
-plugin connection, not a per-job wallet setup. Run discovery and description only as needed, and
-continue automatically after every completed approval or pending status transition.
+result. OAuth authorization is a one-time plugin connection, not a per-job wallet setup. Run
+discovery and description only as needed, and
+continue automatically through submission and pending status transitions.
 
 ## Hard boundaries
 
@@ -85,9 +101,20 @@ continue automatically after every completed approval or pending status transiti
 - If status polling is interrupted, resume `get_job` with the job ID. Do not resubmit merely because a
   job remains pending; report the job ID and last status if the caller's wait limit is reached.
 - Use `create_job_review` only when the user wants to review a completed job. Run its returned
-  zero-spend REST handoff so the original job payer authorizes the review. Use
-  `send_product_feedback` only when the user explicitly asks to contact Mercator maintainers, after
-  showing the approved summary and removing sensitive data.
-
-Read [examples](references/examples.md) for compound research, external actions, approval language,
+  zero-spend REST handoff so the original job payer authorizes the review.
+- When an unexpected Mercator failure persists after one safe recovery attempt, proactively draft
+  a bug report for `send_product_feedback`. Also draft for an unexpected terminal job failure:
+  durable execution has already ended; never submit or pay again just to reproduce it. Return the
+  failure and any partial results to the user. Follow ordinary validation, funding, authorization,
+  rate-limit, and empty-search recovery guidance first; those outcomes alone are not product bugs.
+- Include the tool name, safe error code, reproduction steps, and expected/actual behavior. Provide
+  the related Mercator job ID in `job_id` when one exists; omit it if no job was created or its ID
+  is unknown. Never invent an ID or create a job just to report an issue. The job ID grants result
+  access and is shared with maintainers for diagnosis. Exclude secrets, credentials, payment
+  material, personal data, and raw tool inputs or outputs.
+  Show the draft and ask to send unless the user already authorized reporting this issue. Wallet
+  authorization is not feedback consent. Send at most once per issue in the conversation, stop
+  after a decline, and never automatically retry uncertain delivery or report feedback-tool failures.
+
+Read [examples](references/examples.md) for compound research, external actions, spending limits,
 MCP submission, status listening, and recovery patterns.

plugins/mercator/skills/mercator/agents/openai.yaml

@@ -8,6 +8,6 @@ dependencies:
       value: "mercator"
       description: "Mercator service discovery and durable job execution"
       transport: "streamable_http"
-      url: "https://mercator.tempo.xyz/mcp/auth"
+      url: "https://mercator.sh/mcp/auth"
 policy:
   allow_implicit_invocation: true

plugins/mercator/skills/mercator/references/examples.md

@@ -1,6 +1,6 @@
 # Mercator examples
 
-These examples show routing, scope, and approval decisions. Use live tool schemas; never copy
+These examples show routing, scope, and spending decisions. Use live tool schemas; never copy
 provider IDs, paths, or inputs from an example.
 
 ## Current data
@@ -51,8 +51,9 @@ Before submission, a useful confirmation is:
 > I found a five-source research plan covering flows, holders, price, news, and regulation. The
 > Mercator quote is $3.80, within your $5 budget. I’ll run it and return the requested sourced chart.
 
-Do not ask for redundant approval after the user already supplied a sufficient budget and the plan
-contains no additional actions.
+With hosted OAuth, the connected access key authorizes spending within its signed limits. Do not ask for per-job spend
+approval; respect the explicit $5 budget and the requested scope. Legacy challenge clients can also
+proceed within that explicit budget; without one, show the quote and obtain approval before paying.
 
 ## Research versus action
 
@@ -63,13 +64,13 @@ Search and quote a research plan. Do not book a flight: the user asked to find o
 **Request:** “Book the best refundable replacement under $1,200 and email me the itinerary.”
 
 The requested workflow may include booking and email actions. Before execution, show the selected
-plan and Mercator quote. The $1,200 travel limit does not automatically cover Mercator's separate
-workflow charge unless the user's wording clearly includes it; ask when ambiguous.
+plan and Mercator quote. Keep the fare within the $1,200 travel limit and Mercator's separate workflow
+charge within the connected access-key limits and any explicit workflow budget.
 
 A useful confirmation is:
 
 > The refundable fare is $1,146 and Mercator’s workflow charge is $0.42. The plan will purchase the
-> ticket and email the itinerary. Shall I execute it?
+> ticket and email the itinerary. I’ll run it using the connected wallet.
 
 ## Missing required input
 
@@ -82,9 +83,10 @@ Ask for that address; do not invent it or quietly remove the email step.
 
 ## MCP submission and status
 
-After approval, call `create_job` once with the unchanged quoted plan, a stable idempotency key, and
-the accepted `totalAmount` as `approved_total`. OAuth-connected hosts charge the bounded wallet
-inside Mercator. Other clients complete any payment challenge through MCP metadata. Never install a
+After quoting, call `create_job` once with the unchanged quoted plan, a stable idempotency key, and
+the quoted `totalAmount` as `approved_total`. OAuth-connected hosts charge the bounded wallet
+inside Mercator. Legacy challenge clients require quote approval or a sufficient explicit budget
+before completing payment through MCP metadata, including after a price change. Never install a
 CLI or translate MCP submission into a REST request.
 
 A successful submission returns either a terminal job or a pending response:
@@ -105,21 +107,32 @@ Persist the job ID and start a status listener with:
 - Request timeout or lost response: call `create_job` with the identical plan and idempotency key to
   recover the job, then listen on its returned job ID.
 
+In summary mode (`"result_mode":"summary"`), an empty `job.result` means payloads were omitted.
+Use each returned `result_node_ids` value with `get_job_details`:
+
+```json
+{"job_id":"4d9ea616-4223-4b9d-bd19-2d3f74c9fa4c","node_id":"search1"}
+```
+
+Use the actual returned node ID. Alternatively, call `get_job` with `result_mode: "inline"`.
+Both reads use cached outputs and do not charge again. Failed jobs may retain successful outputs.
+
 Do not model completion as a webhook or SSE subscription: the public status interface is polling.
 
 ## Existing local wallet fallback
 
 Use REST only when MCP submission fails, one identical retry also fails, and the host already has a
-ready local Mercator wallet. Submit the same plan to `POST https://mercator.tempo.xyz/v1/jobs` with
+ready local Mercator wallet. Submit the same plan to `POST https://mercator.sh/v1/jobs` with
 the same idempotency key and a maximum spend equal to `approved_total`. Never install, create, or
-connect a wallet for fallback. Resume job polling through MCP `get_job` with the returned job ID.
+connect a wallet for fallback. A local fallback wallet needs quote approval or a sufficient explicit
+budget; the hosted OAuth grant does not authorize a separate local wallet. Resume job polling through MCP `get_job` with the returned job ID.
 
 ## No result or stale endpoint
 
 - Unconstrained search with no result: broaden the outcome once while preserving user constraints.
 - Required service with no result: report that the constraint cannot currently be satisfied.
 - Stale endpoint or quote failure: search again for a current alternative, rebuild the plan, and
-  quote it again before seeking approval.
+  quote it again before submitting within the access-key limits and any explicit user budget.
 
 ## Do not activate