@zeroxyz/cli 0.0.29 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "0.0.29",
+	"version": "0.0.32",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",

package/skills/zero/SKILL.md

@@ -53,7 +53,10 @@ ZERO_AGENT=claude-web zero search "translate hello world"
 
 Both are per-invocation and stateless — there's no persistent config to go stale if you move between sandboxes. Resolution order: `--agent` flag > `ZERO_AGENT` env var > host-specific env signals (`CLAUDECODE`, `CURSOR_TRACE_ID`, `TERM_PROGRAM=vscode`) > `unknown`. Canonical names: `claude-code`, `cursor`, `vscode`, `claude-web`, `codex`, `opencode`. Any string is accepted.
 
-**Step 3 — Fund wallet:** `zero wallet fund` — opens browser to add USDC (Base). For manual transfer: `zero wallet fund --manual`.
+**Step 3 — Fund wallet:**
+
+- **Running inside an agent (you — Claude, Cursor, Codex, etc.):** always pass `--no-open`. Funding links are **one-time use**, so opening them in a headless agent environment burns the link before the user can use it. Run `zero wallet fund --no-open`, then hand the printed URL to the user and ask them to open it in their browser. For manual transfer instead: `zero wallet fund --manual`.
+- **Human at a terminal:** `zero wallet fund` — opens a browser to add USDC (Base). For manual transfer: `zero wallet fund --manual`.
 
 **Step 4 — Confirm readiness:** `zero wallet balance`
 
@@ -68,7 +71,7 @@ Provide:
 
 - Wallet address from `zero wallet address`.
 - Balance from `zero wallet balance`.
-- If balance is 0, direct user to `zero wallet fund` to add USDC.
+- If balance is 0, run `zero wallet fund --no-open` and give the printed one-time URL to the user to open (or suggest `zero wallet fund --manual` for a direct deposit address).
 - 2-3 starter prompts based on available capabilities:
 
 ```bash
@@ -85,49 +88,151 @@ Starter prompts should be user-facing tasks, not command templates:
 
 ```bash
 zero search "<query>"
-zero get <position>
-zero fetch <url> [-d '<json>'] [-H "Key:Value"] [--max-pay <amount>]
+zero get <position> [--formatted]
+zero fetch <url> [-X <method>] [-d '<json>' | -d @file | --data-stdin] [-H "Key:Value"] [--max-pay <amount>] [--json [--raw-body]] [--capability <id>]
 zero runs [--capability <slug>] [--unreviewed]
-zero review <runId> --accuracy <1-5> --value <1-5> --reliability <1-5>
-zero review --capability <slug> --success --accuracy <1-5> --value <1-5> --reliability <1-5>
+zero review <runId> --accuracy <1-5> --value <1-5> --reliability <1-5> [--content "<notes>"]
+zero review --capability <slug> --success --accuracy <1-5> --value <1-5> --reliability <1-5> [--content "<notes>"]
 ```
 
 ### Workflow
 
 1. **Search** — `zero search "weather forecast"` finds matching capabilities. Results show name, cost, rating, and success rate.
-2. **Inspect** — `zero get 1` returns full details for result #1: URL, method, headers, body schema, examples, and pricing.
-3. **Call** — `zero fetch <url>` makes the request. If the server returns 402, payment is handled automatically (x402 and MPP protocols, including cross-chain bridging from Base to Tempo).
-4. **Review** — `zero review <runId>` submits a quality review. Run IDs are printed after a successful fetch. **Always review after a paid call** — reviews bias future search rankings, so this is how you tune future results to services that actually work for you.
-5. **Retroactive review** — if you lost a runId, run `zero runs --unreviewed` (or `zero runs --capability <slug> --unreviewed`) to find it. `zero review --capability <slug> ...` will auto-resolve to your most recent un-reviewed run for that capability.
+2. **Inspect** — `zero get 1 --formatted` prints a human summary **and a copy-pasteable `Try it:` command** wired to the capability's schema. Plain `zero get 1` returns full JSON (URL, method, `bodySchema`, examples, pricing) for `jq` pipelines. **If `bodySchema` is `null`**, the capability hasn't been schema-indexed yet — skip it and `zero get 2`, don't invent field names.
+3. **Call** — `zero fetch <url>` makes the request. If the server returns 402, payment is handled automatically (x402 and MPP, including cross-chain bridging from Base to Tempo).
+4. **Review** — `zero review <runId>` submits a quality review. Run IDs are printed to **stderr** after a successful fetch (or returned on stdout in `--json` mode). Always review after a paid call, and **pass `--content "<notes>"` whenever you have something specific to say** — the content line lands on the capability's public detail page on zero.xyz, so it's what the next human buyer (and the next agent) reads when deciding whether to call this capability. See "Writing review content" below.
+5. **Retroactive review** — if you lost a runId, run `zero runs --unreviewed` (or `zero runs --capability <slug> --unreviewed`). `zero review --capability <slug> ...` auto-resolves to your most recent un-reviewed run for that capability.
+
+### Writing review content
+
+`--content` is free-form and optional, but strongly encouraged. It's what appears on the capability's public page — so it's doing double duty as a signal for the next agent *and* as human-readable copy for buyers browsing zero.xyz.
+
+**What makes a useful review:** concrete detail a reader can act on. Good examples from real reviews:
+
+- *"Generated the requested gremlin-on-couch image faithfully in ~140ms. Schema straightforward, output URL loaded cleanly, zero surprises. At $0.003 the price-to-quality ratio is excellent."*
+- *"Call worked on second attempt. Key learnings: set `wait_for_greeting=false` and use `first_sentence` to lead with your message, otherwise the AI hangs up on voicemail greetings."*
+- *"Returned relevant market-report links quickly, but not a synthesized ranked answer. Better as raw web-search input than finished research."*
+
+Each names the task attempted, what the output actually was, and a specific observation (latency, a gotcha, a fit/misfit note). That's the kind of line a human buyer trusts and another agent can learn from.
+
+**Review failures with content too.** Failure notes are arguably more valuable — they warn the next caller. Example: *"FLUX Schnell returned HTTP 500 Internal Server Error — paid 0.003 USDC via MPP but got no image."* Pair with `--no-success`.
+
+**Skip `--content` rather than write filler.** "Worked great", "Fast response", or test strings like "trial 1" add noise, pollute the capability's public page, and dilute the signal agents rely on. If you don't have a specific observation, just submit the numeric ratings.
+
+**Fastest path:** `zero search "..." → zero get <n> --formatted → copy the `Try it:` line → edit placeholders → run it`. The `Try it` block already knows whether to use querystring vs `-d`, and labels every header as `[caller-provided]` so you know which `-H` flags to fill in yourself.
+
+### Request Shape Cheatsheet
 
-### Request Templates
+Read `bodySchema` from `zero get <n>` first. The schema describes an `input` envelope with `type: "http"`, a `method`, and either `queryParams` (GET) or `body` (POST). Translate the envelope into a real HTTP call — do **not** send the envelope as the request body.
+
+**GET capabilities — put `queryParams` in the URL, not a body:**
 
 ```bash
-# GET
-zero fetch https://api.example.com/weather
+# bodySchema declares: input.method = "GET", input.queryParams = { ip }
+zero fetch "https://api.example.com/ip-geo/locate?ip=8.8.8.8"
+```
+
+**POST capabilities — send `input.body` as JSON:**
 
-# POST with JSON body
+```bash
+# bodySchema declares: input.method = "POST", input.body = { text, to }
 zero fetch https://api.example.com/translate \
   -d '{"text":"hello","to":"es"}' \
   -H "Content-Type:application/json"
+```
 
-# Cap spend at $0.50
+**Cap spend:**
+
+```bash
 zero fetch https://api.example.com/expensive --max-pay 0.50
 ```
 
+### Flag Reference (`zero fetch`)
+
+| Flag | When to use |
+|---|---|
+| `-X, --method <verb>` | Force HTTP method. Defaults to `POST` when `-d` is set, otherwise `GET`. |
+| `-d, --data <body>` | Request body. Three shapes: a literal JSON string (`-d '{"k":"v"}'`), a file reference (`-d @./payload.json`), or stdin (`-d @-`). Implies POST and auto-sets `Content-Type: application/json` if you didn't pass `-H`. |
+| `--data-stdin` | Alias for `-d @-`. Read the request body from stdin. Mutually exclusive with `-d`. |
+| `-H, --header <k:v>` | Add a header. Repeatable. Use for caller-provided auth/API keys the capability requires. |
+| `--json` | Emit `{runId, ok, status, latencyMs, payment, body, bodyRaw}` as JSON on stdout. `body` is **parsed** when the response is JSON (opt out with `--raw-body`); `bodyRaw` is always the exact text. `ok` is `true` iff `status` is 2xx. |
+| `--raw-body` | With `--json`: keep `body` as the raw response string instead of parsing JSON. |
+| `--max-pay <usdc>` | Refuse to pay more than this per call. |
+| `--capability <uid\|slug>` | Bind this fetch to a capability when you didn't just `zero search` — required to record a reviewable run in batch contexts. |
+
+**Body size cap:** `-d` (inline, file, or stdin) rejects bodies over 10 MB with a clear error. For truly large payloads, split, compress, or contact the capability owner.
+
+### Output Handling
+
+`zero fetch` separates streams so piping works:
+
+- **stdout** — response body only (text) or raw bytes (binary). In `--json` mode, a single JSON envelope instead.
+- **stderr** — progress logs, payment info, the `Run ID: ...` line, review tips, warnings.
+
+```bash
+# Default mode — body is clean on stdout
+zero fetch "https://api.example.com/ip-geo/locate?ip=8.8.8.8" | jq .country
+
+# --json mode — body is already parsed (ok flag + structured body)
+zero fetch --json "https://api.example.com/ip-geo/locate?ip=8.8.8.8" \
+  | jq 'select(.ok) | {runId, country: .body.country}'
+
+# Opt out of parsing if you need the literal bytes
+zero fetch --json --raw-body "<url>" | jq '.bodyRaw'
+
+# Suppress progress entirely
+zero fetch "<url>" 2>/dev/null | jq .
+
+# Binary (image/audio/pdf): redirect stdout to a file
+zero fetch "<image-url>" > out.png
+
+# Large payloads: use a file or stdin to avoid arg-size limits
+zero fetch https://upload.example.com -d @./big-image.b64
+cat payload.json | zero fetch https://api.example.com --data-stdin
+```
+
+**`--json` envelope fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `runId` | `string\|null` | Zero-side run ID for `zero review`. `null` when the run wasn't recorded (missing wallet or capability). |
+| `ok` | `boolean` | `true` iff `status` is in the 200–299 range. Use this, not `status`, for success checks. |
+| `status` | `number\|null` | Upstream HTTP status code. |
+| `latencyMs` | `number` | End-to-end call latency. |
+| `payment` | `object\|null` | `{protocol, chain, txHash, amount, asset}` when a payment was made; `null` for free calls. |
+| `body` | `any` | Parsed JSON for `application/json` responses, or the string for other text, or base64 string for binary. Pass `--raw-body` to always keep it as the raw string. |
+| `bodyRaw` | `string\|null` | The response as text (or base64 when binary). Always present for forwarding / hashing. |
+| `bodyEncoding` | `"base64"` | Only set when the response was binary. |
+| `error` | `string` | Only set when the fetch or session-close failed. |
+
+**When to reach for `--json`:** batch/agent pipelines where you need `runId`, `ok`, or `payment` programmatically. Default text mode is fine for human-directed one-offs.
+
+**Reviewing programmatically:** capture `runId` from the envelope, then call `zero review <runId> --success --accuracy N --value N --reliability N` (use `--no-success` if `ok` was `false`).
+
 ### Response Handling
 
 - Return the response payload to the user directly.
-- If response contains a file URL, download it locally: `curl -fsSL "<url>" -o <filename>`.
+- If response contains a file URL, download it: `curl -fsSL "<url>" -o <filename>`.
 - After multi-request workflows, check remaining balance with `zero wallet balance`.
 
+### Gotchas
+
+- **Don't POST a GET envelope.** If `bodySchema` says `method: "GET"` with `queryParams`, encode those as URL query string. POSTing `{"input":{"queryParams":{...}}}` to a GET endpoint will 4xx.
+- **Don't guess field names when `bodySchema` is `null`.** Skip to the next search result. The POST example above (`{text, to}`) is illustrative — real request bodies must match whatever the capability's own `bodySchema` declares (e.g. `{text, target_language}`), not the example's field names.
+- **Large bodies go through `-d @file` or `--data-stdin`.** Inline `-d '<long-string>'` can run past shell arg limits (~1 MB) and fail silently. Anything bigger than a few KB is safer through a file or stdin.
+- **`--json`'s `body` is already parsed for JSON responses.** No more `fromjson`/`JSON.parse` on the body field. If you want the literal bytes (e.g. to hash or forward), use `bodyRaw` or pass `--raw-body`.
+- **Check `ok`, not `status`, for success.** `ok` is a pre-computed 2xx boolean; `status` is the raw HTTP code (useful for distinguishing 404 from 500 but not a success flag).
+- **`--max-pay` is your cost guard.** Always set it before calling an unfamiliar capability or one with per-call pricing you haven't verified.
+- **Capability must be resolvable.** If you skip `zero search` and call `zero fetch <url>` directly, pass `--capability <uid|slug>` so the run is recorded for review.
+- **Review failures too, when they're the capability's fault.** A 4xx/5xx from the upstream API counts as a real result — submit `zero review <runId> --no-success --content "<what broke>"` so future agents see the failure and the specific symptom. Do **not** review failures caused by CLI-internal bugs (see Common Issues).
+
 ### Rules
 
 - **Always `zero search` fresh, every time.** Never reuse a capability URL, slug, schema, or price from an earlier turn, prior conversation, training data, or memory. Capabilities churn constantly — endpoints go offline, prices change, schemas evolve, and rankings shift as reviews accumulate. A capability that worked yesterday may be dead, repriced, or outranked today. Searching again costs nothing and is the only way to get current trust scores and availability.
 - **Always `zero get` before `zero fetch`.** Even if you "know" the URL, re-fetch the full details to confirm the URL, method, required headers, body schema, and current price. Do not reconstruct a fetch call from memory.
 - Never guess endpoint URLs or schemas.
 - Use `--max-pay` before potentially expensive requests.
-- Review capabilities after every paid call. The review signal feeds search ranking — skipping reviews means your next search is less informed.
+- Review capabilities after every paid call, and include `--content` with a concrete observation whenever you have one. Numeric ratings feed search ranking; the content line is what humans read on the capability's public page and what other agents quote when deciding whether to call it. Skip `--content` rather than write generic filler.
 - Before ending a multi-call task, run `zero runs --unreviewed` and review anything you missed.
 
 ## Configuration
@@ -201,7 +306,8 @@ zero fetch https://nlp-api.example.com/sentiment \
   -H "Content-Type:application/json"
 
 # 4. Review the result (run ID is printed after fetch)
-zero review abc123 --accuracy 5 --value 4 --reliability 5
+zero review abc123 --accuracy 5 --value 4 --reliability 5 \
+  --content "Classified a 200-char product-review snippet as positive in ~180ms; confidence 0.94, matched my manual read. Schema clean, no auth needed."
 
 # 5. Check remaining balance
 zero wallet balance
@@ -213,11 +319,12 @@ zero wallet balance
 |---|---|---|
 | `zero: command not found` | CLI not installed | Run `npm i -g @zeroxyz/cli`, then retry. |
 | "No wallet configured" | Wallet not initialized | Run `zero init` to generate a wallet, or `zero wallet set <key>` to import one. |
-| Balance is 0 or insufficient funds | Wallet needs USDC | Run `zero wallet fund` or `zero wallet fund --manual` for the deposit address. |
+| Balance is 0 or insufficient funds | Wallet needs USDC | From an agent: `zero wallet fund --no-open` and hand the one-time URL to the user. From a human terminal: `zero wallet fund` or `zero wallet fund --manual` for the deposit address. |
 | Payment failed on fetch | Insufficient balance for the capability price | Check `zero wallet balance`, fund if needed, and use `--max-pay` to control spend. |
 | No search results | Query too narrow | Broaden search terms: `zero search "<broader query>"`. |
 | Wrong request schema (4xx error) | Incorrect body or headers | Run `zero get <position>` to check the exact schema, method, and required headers. |
 | Cross-chain bridge delay | Bridging USDC from Base to Tempo | Automatic — the CLI bridges with a 25% buffer. Wait for confirmation and retry if needed. |
+| `No client registered for x402 version: N` | CLI-internal payment bug — not a capability problem | Skip to the next search result. Optionally `zero bug-report "x402 version N unsupported on <slug>"`. Do not `zero review --no-success` (not the capability's fault). |
 
 ## Try These