@zeroxyz/cli 0.0.28 → 0.0.30

package/README.md

@@ -56,11 +56,11 @@ Get full details for a capability from the last search results.
 zero get 1
 ```
 
-Outputs the capability as JSON (URL, method, headers, body schema, cost, payment methods, etc.).
+Outputs the capability as JSON (URL, method, headers, body schema, cost, supported protocols, etc.).
 
 ### `zero fetch <url>`
 
-Fetch a capability URL. Automatically detects `402 Payment Required` responses and reports the payment protocol (x402, MPP, etc.).
+Fetch a capability URL. Automatically detects `402 Payment Required` responses and reports the protocol in use (x402, MPP, etc.).
 
 ```bash
 # GET request

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command as Command12 } from "commander";
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.28",
+  version: "0.0.30",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -119,10 +119,14 @@ var capabilityResponseSchema = z.object({
     state: z.enum(["unrated", "rated"]).optional()
   }),
   priceObserved: z.object({
-    medianCents: z.string(),
-    p95Cents: z.string(),
+    minCents: z.string().nullable(),
+    medianCents: z.string().nullable(),
+    maxCents: z.string().nullable(),
+    // Deprecated alias for maxCents; kept for backward compat.
+    p95Cents: z.string().nullable(),
     sampleCount: z.number(),
-    varies: z.boolean()
+    varies: z.boolean(),
+    failureChargeRate: z.number().nullable()
   }).nullable().optional(),
   paymentMethods: z.array(
     z.object({
@@ -149,7 +153,31 @@ var createRunResponseSchema = z.object({
 });
 var createReviewResponseSchema = z.object({
   reviewId: z.string(),
-  recorded: z.boolean()
+  recorded: z.boolean(),
+  updated: z.boolean().optional()
+});
+var batchReviewResponseSchema = z.object({
+  results: z.array(
+    z.union([
+      z.object({
+        runId: z.string(),
+        ok: z.literal(true),
+        reviewId: z.string(),
+        updated: z.boolean()
+      }),
+      z.object({
+        runId: z.string(),
+        ok: z.literal(false),
+        status: z.number(),
+        error: z.string()
+      })
+    ])
+  ),
+  summary: z.object({
+    total: z.number(),
+    ok: z.number(),
+    failed: z.number()
+  })
 });
 var BUG_REPORT_CATEGORIES = [
   "search_relevance",
@@ -275,6 +303,10 @@ var ApiService = class {
     const json = await this.request("POST", "/v1/reviews", data);
     return createReviewResponseSchema.parse(json);
   };
+  createReviewsBatch = async (reviews) => {
+    const json = await this.request("POST", "/v1/reviews/batch", { reviews });
+    return batchReviewResponseSchema.parse(json);
+  };
   createBugReport = async (data) => {
     const json = await this.request("POST", "/v1/bug-reports", data);
     return createBugReportResponseSchema.parse(json);
@@ -582,6 +614,8 @@ var configCommand = (_appContext) => new Command2("config").description("View or
 });
 
 // src/commands/fetch-command.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { resolve as resolvePath } from "path";
 import { Command as Command3 } from "commander";
 import { formatUnits as formatUnits2 } from "viem";
 
@@ -626,7 +660,9 @@ var PATHUSD_TEMPO = "0x20c0000000000000000000000000000000000000";
 var BASE_CHAIN_ID = 8453;
 var TEMPO_CHAIN_ID = 4217;
 var TEMPO_TESTNET_CHAIN_ID = 42431;
-var DEFAULT_MAX_DEPOSIT = "100";
+var DEFAULT_PREFUND_NO_COST_INFO = "1";
+var ADAPTIVE_PREFUND_MULTIPLIER = 10;
+var ADAPTIVE_PREFUND_CEILING = "100";
 var KNOWN_EIP712_DOMAINS = {
   // USDC on Base
   [USDC_BASE.toLowerCase()]: { name: "USDC", version: "2" },
@@ -643,6 +679,16 @@ var calculateBuffer = (baseBalance) => {
   const twoDollars = 2000000n;
   return twentyFivePercent < twoDollars ? twentyFivePercent : twoDollars;
 };
+var resolveDefaultPrefund = (displayCostAmount) => {
+  const floor = Number.parseFloat(DEFAULT_PREFUND_NO_COST_INFO);
+  const ceiling = Number.parseFloat(ADAPTIVE_PREFUND_CEILING);
+  if (!displayCostAmount) return DEFAULT_PREFUND_NO_COST_INFO;
+  const cost = Number.parseFloat(displayCostAmount);
+  if (!Number.isFinite(cost) || cost <= 0) return DEFAULT_PREFUND_NO_COST_INFO;
+  const scaled = cost * ADAPTIVE_PREFUND_MULTIPLIER;
+  const bounded = scaled < floor ? floor : scaled > ceiling ? ceiling : scaled;
+  return bounded.toFixed(6).replace(/\.?0+$/, "");
+};
 var tempoChain = {
   id: TEMPO_CHAIN_ID,
   name: "Tempo",
@@ -723,7 +769,7 @@ var PaymentService = class {
     const bridgeAmount = requiredAmount + buffer;
     if (baseBalance < bridgeAmount) {
       throw new Error(
-        `Insufficient Base USDC to bridge: have ${formatUnits(baseBalance, 6)}, need ${formatUnits(bridgeAmount, 6)} (${formatUnits(requiredAmount, 6)} + ${formatUnits(buffer, 6)} buffer)`
+        `Insufficient Base USDC to bridge: have ${formatUnits(baseBalance, 6)}, need ${formatUnits(bridgeAmount, 6)} (${formatUnits(requiredAmount, 6)} + ${formatUnits(buffer, 6)} buffer). This gateway uses an MPP payment channel, which is pre-funded up front. Either fund your wallet on Base, or pass \`--max-pay <amount>\` to use a smaller channel (e.g. \`--max-pay 0.05\` for a ~5-cent channel sized for a single cheap call).`
       );
     }
     onProgress?.(
@@ -759,7 +805,7 @@ var PaymentService = class {
     });
     return bridgeTxHash;
   };
-  handlePayment = async (url, request, paymentRequirement, maxPay, onProgress) => {
+  handlePayment = async (url, request, paymentRequirement, maxPay, onProgress, displayCostAmount) => {
     if (!this.account) {
       throw new Error(
         "No wallet configured \u2014 run `zero init` or set ZERO_PRIVATE_KEY"
@@ -776,7 +822,8 @@ var PaymentService = class {
         request,
         paymentRequirement.raw,
         maxPay,
-        onProgress
+        onProgress,
+        displayCostAmount
       );
     }
     throw new Error("Unrecognized 402 payment protocol");
@@ -840,15 +887,14 @@ var PaymentService = class {
    * BEFORE mppx signs a credential — so balance/bridge logic runs in-band
    * without adding a pre-probe round-trip.
    */
-  prepareTempoFunds = async (challenge, maxPay, onProgress) => {
+  prepareTempoFunds = async (challenge, maxPay, onProgress, displayCostAmount) => {
     const challengeRequest = challenge.request;
     let requiredRaw;
     if (challenge.intent === "session") {
       const suggestedDeposit = challengeRequest.suggestedDeposit;
+      const defaultPrefund = resolveDefaultPrefund(displayCostAmount);
       requiredRaw = suggestedDeposit ? BigInt(suggestedDeposit) : BigInt(
-        Math.floor(
-          Number.parseFloat(maxPay ?? DEFAULT_MAX_DEPOSIT) * 1e6
-        )
+        Math.floor(Number.parseFloat(maxPay ?? defaultPrefund) * 1e6)
       );
     } else {
       requiredRaw = BigInt(challengeRequest.amount);
@@ -889,7 +935,7 @@ var PaymentService = class {
    * the extra state and return `410 "channel not found"` on the close.
    * This mirrors the working production v0.0.21 single-fetch flow.
    */
-  payMpp = async (url, request, _raw, maxPay, onProgress) => {
+  payMpp = async (url, request, _raw, maxPay, onProgress, displayCostAmount) => {
     const account = this.account;
     if (!account) throw new Error("No wallet configured");
     let capturedAmount = "0";
@@ -901,7 +947,7 @@ var PaymentService = class {
       methods: [
         tempo({
           account,
-          maxDeposit: maxPay ?? DEFAULT_MAX_DEPOSIT,
+          maxDeposit: maxPay ?? resolveDefaultPrefund(displayCostAmount),
           onChannelUpdate: (entry) => {
             channelEntry = {
               channelId: entry.channelId,
@@ -917,7 +963,8 @@ var PaymentService = class {
         capturedAmount = await this.prepareTempoFunds(
           challenge,
           maxPay,
-          onProgress
+          onProgress,
+          displayCostAmount
         );
         return void 0;
       }
@@ -1167,6 +1214,43 @@ var isTextContentType = (contentType) => {
   if (ct === "application/x-www-form-urlencoded") return true;
   return false;
 };
+var isJsonContentType = (contentType) => {
+  if (!contentType) return false;
+  const ct = contentType.toLowerCase().split(";")[0]?.trim() ?? "";
+  return ct === "application/json" || ct.endsWith("+json");
+};
+var MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024;
+var resolveRequestBody = (rawData, readStdin) => {
+  const fromFile = (spec) => {
+    if (spec === "@-") {
+      return readFileSync3(0, "utf8");
+    }
+    const path = resolvePath(spec.slice(1));
+    return readFileSync3(path, "utf8");
+  };
+  let body;
+  if (readStdin && rawData !== void 0) {
+    throw new Error(
+      "Conflicting body sources: use either --data-stdin or -d, not both."
+    );
+  }
+  if (readStdin) {
+    body = readFileSync3(0, "utf8");
+  } else if (rawData?.startsWith("@")) {
+    body = fromFile(rawData);
+  } else {
+    body = rawData;
+  }
+  if (body !== void 0) {
+    const bytes = Buffer.byteLength(body, "utf8");
+    if (bytes > MAX_REQUEST_BODY_BYTES) {
+      throw new Error(
+        `Request body is ${bytes} bytes \u2014 exceeds the ${MAX_REQUEST_BODY_BYTES} byte limit. Split the payload, compress it, or contact the capability owner about raising the cap.`
+      );
+    }
+  }
+  return body;
+};
 var looksLikeX402V1Body = (body) => {
   if (!body || typeof body !== "object") return false;
   const b = body;
@@ -1201,15 +1285,26 @@ var detectPaymentRequirement = async (response) => {
   }
   return { protocol: "unknown", raw: {} };
 };
-var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a capability URL with automatic payment handling").argument("<url>", "URL to fetch").option(
+var fetchCommand = (appContext) => new Command3("fetch").description(
+  "Fetch a capability URL, handling 402 challenges automatically"
+).argument("<url>", "URL to fetch").option(
   "-X, --method <method>",
   "HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to POST when -d is set, otherwise GET"
-).option("-d, --data <body>", "Request body (JSON string)").option("-H, --header <header...>", "Headers in Key:Value format").option("--max-pay <amount>", "Maximum amount willing to pay (USDC)").option(
+).option(
+  "-d, --data <body>",
+  "Request body. Pass a literal JSON string, or `@path/to/file` to read from a file, or `@-` to read from stdin."
+).option(
+  "--data-stdin",
+  "Read the request body from stdin (equivalent to `-d @-`)."
+).option("-H, --header <header...>", "Headers in Key:Value format").option("--max-pay <amount>", "Maximum per-call spend limit (USDC)").option(
   "--capability <id>",
   "Bind this fetch to a capability (uid or slug) so a reviewable run is recorded even without a prior `zero search`"
 ).option(
   "--json",
-  "Emit {runId, status, latencyMs, payment, body} as JSON on stdout (for batch/non-TTY use)"
+  "Emit {runId, ok, status, latencyMs, payment, body, bodyRaw} as JSON on stdout (for batch/non-TTY use)"
+).option(
+  "--raw-body",
+  "With --json: keep `body` as the raw response string instead of parsing JSON. `bodyRaw` still reflects the raw text."
 ).option(
   "--agent <name>",
   "Identify your agent host for this invocation (e.g. claude-web, codex). Overrides auto-detect for this call only."
@@ -1224,6 +1319,19 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
         walletService
       } = appContext.services;
       const startTime = Date.now();
+      let resolvedBody;
+      try {
+        resolvedBody = resolveRequestBody(
+          options.data,
+          options.dataStdin ?? false
+        );
+      } catch (err) {
+        console.error(
+          err instanceof Error ? err.message : "Failed to read request body"
+        );
+        process.exitCode = 1;
+        return;
+      }
       const headers = {};
       if (options.header) {
         for (const h of options.header) {
@@ -1236,15 +1344,15 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
       const hasContentType = Object.keys(headers).some(
         (k) => k.toLowerCase() === "content-type"
       );
-      if (options.data && !hasContentType) {
+      if (resolvedBody && !hasContentType) {
         headers["content-type"] = "application/json";
       }
       const log = (msg) => console.error(`  ${msg}`);
-      const method = options.method ? options.method.toUpperCase() : options.data ? "POST" : "GET";
+      const method = options.method ? options.method.toUpperCase() : resolvedBody ? "POST" : "GET";
       const requestInit = {
         method,
         headers,
-        body: options.data
+        body: resolvedBody
       };
       const lastSearch = stateService.loadLastSearch();
       const matchedCapability = lastSearch?.capabilities.find(
@@ -1283,7 +1391,8 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
             requestInit,
             paymentReq,
             options.maxPay,
-            log
+            log,
+            matchedCapability?.displayCostAmount
           );
           finalResponse = result.response;
           paymentMeta = {
@@ -1384,8 +1493,8 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
       if (capabilityId && apiService.walletAddress) {
         let requestSchema;
         let responseSchema;
-        if (options.data) {
-          const parsedReq = tryParseJson(options.data);
+        if (resolvedBody) {
+          const parsedReq = tryParseJson(resolvedBody);
           if (parsedReq !== null && typeof parsedReq === "object") {
             requestSchema = inferSchema(parsedReq);
           }
@@ -1440,14 +1549,30 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
         console.error(`  Fetch failed: ${fetchError.message}`);
       }
       if (options.json) {
-        const jsonBody = !finalResponse ? null : bodyIsBinary ? (bodyBytes ?? Buffer.alloc(0)).toString("base64") : body;
+        const responseStatus = finalResponse?.status ?? null;
+        const ok = responseStatus !== null && responseStatus >= 200 && responseStatus < 300;
+        const responseCt = finalResponse?.headers.get("content-type") ?? null;
+        const bodyString = bodyIsBinary ? (bodyBytes ?? Buffer.alloc(0)).toString("base64") : body;
+        let parsedBody = null;
+        if (finalResponse && !bodyIsBinary && !options.rawBody) {
+          if (isJsonContentType(responseCt)) {
+            const parsed = tryParseJson(body);
+            parsedBody = parsed === null ? body : parsed;
+          } else {
+            parsedBody = body;
+          }
+        } else if (finalResponse) {
+          parsedBody = bodyString;
+        }
         console.log(
           JSON.stringify({
             runId,
-            status: finalResponse?.status ?? null,
+            ok,
+            status: responseStatus,
             latencyMs,
             payment: paymentMeta ?? null,
-            body: jsonBody,
+            body: parsedBody,
+            bodyRaw: finalResponse ? bodyString : null,
             ...bodyIsBinary && { bodyEncoding: "base64" },
             ...fetchError && { error: fetchError.message },
             ...skipReasons.length > 0 && {
@@ -1508,6 +1633,30 @@ var formatTrustComponent = (label, value) => {
   const display = value != null ? `${value}/100` : "--";
   return `    ${label.padEnd(22)}${display}`;
 };
+var centsToDollars = (cents) => {
+  const value = Number.parseFloat(cents) / 100;
+  if (value < 0.01) return value.toFixed(4);
+  if (value < 1) return value.toFixed(3);
+  return value.toFixed(2);
+};
+var formatCost = (capability) => {
+  const lines = [];
+  const observed = capability.priceObserved;
+  if (observed && observed.sampleCount > 0 && observed.varies && observed.minCents && observed.maxCents) {
+    const min = centsToDollars(observed.minCents);
+    const max = centsToDollars(observed.maxCents);
+    const median = observed.medianCents ? centsToDollars(observed.medianCents) : null;
+    const detail = median ? `median $${median}, n=${observed.sampleCount}` : `n=${observed.sampleCount}`;
+    lines.push(`  Cost: $${min}\u2013$${max}/call (${detail})`);
+  } else {
+    lines.push(`  Cost: $${capability.displayCostAmount}/call`);
+  }
+  if (observed?.failureChargeRate != null && observed.failureChargeRate > 0) {
+    const pct = Math.round(observed.failureChargeRate * 100);
+    lines.push(`  \u26A0  ~${pct}% of failed runs still charged the wallet`);
+  }
+  return lines;
+};
 var formatRating = (rating) => {
   if (rating.state === "unrated") return "unrated";
   const successPct = `${Math.round(Number.parseFloat(rating.successRate) * 100)}%`;
@@ -1517,6 +1666,81 @@ var formatRating = (rating) => {
   }
   return `${successPct} success, ${reviews} reviews`;
 };
+var asNode = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+var placeholderFor = (fieldName, propSchema) => {
+  const node = asNode(propSchema);
+  const example = node?.example ?? node?.default;
+  if (typeof example === "string") return example;
+  if (typeof example === "number" || typeof example === "boolean") {
+    return String(example);
+  }
+  return `<${fieldName.toUpperCase()}>`;
+};
+var extractInputEnvelope = (bodySchema, method) => {
+  if (!bodySchema) return {};
+  const props = asNode(bodySchema.properties);
+  if (!props) return {};
+  const inputProps = asNode(asNode(props.input)?.properties);
+  if (inputProps) {
+    return {
+      queryParams: asNode(asNode(inputProps.queryParams)?.properties) ?? void 0,
+      body: asNode(asNode(inputProps.body)?.properties) ?? void 0
+    };
+  }
+  const upperMethod = method.toUpperCase();
+  const isGetLike = upperMethod === "GET" || upperMethod === "DELETE";
+  return isGetLike ? { queryParams: props } : { body: props };
+};
+var buildTryItExample = (capability) => {
+  const method = capability.method.toUpperCase();
+  const lines = ["", "Try it:"];
+  const { queryParams, body } = extractInputEnvelope(
+    capability.bodySchema,
+    capability.method
+  );
+  const callerHeaders = Object.entries(capability.headers ?? {});
+  const headerFlags = callerHeaders.map(
+    ([k, v]) => `-H "${k}: ${v}"  # [caller-provided]`
+  );
+  if (method === "GET" || queryParams && !body) {
+    const qs = queryParams ? Object.entries(queryParams).map(
+      ([k, schema]) => `${encodeURIComponent(k)}=${encodeURIComponent(placeholderFor(k, schema))}`
+    ).join("&") : "";
+    const url = qs ? `${capability.url}?${qs}` : capability.url;
+    const urlLine = `  zero fetch "${url}"`;
+    if (headerFlags.length === 0) {
+      lines.push(urlLine);
+    } else {
+      lines.push(`  zero fetch \\`);
+      for (const h of headerFlags) lines.push(`    ${h} \\`);
+      lines.push(`    "${url}"`);
+    }
+    if (!queryParams && method === "GET") {
+      lines.push(
+        "  # bodySchema did not expose queryParams \u2014 call the URL as-is or inspect the raw schema above."
+      );
+    }
+    return lines;
+  }
+  const samplePayload = body ? Object.fromEntries(
+    Object.entries(body).map(([k, schema]) => [
+      k,
+      placeholderFor(k, schema)
+    ])
+  ) : null;
+  const bodyJson = samplePayload ? JSON.stringify(samplePayload) : "<BODY_JSON>";
+  lines.push(`  zero fetch \\`);
+  if (method !== "POST") lines.push(`    -X ${method} \\`);
+  for (const h of headerFlags) lines.push(`    ${h} \\`);
+  lines.push(`    -d '${bodyJson}' \\`);
+  lines.push(`    ${capability.url}`);
+  if (!body) {
+    lines.push(
+      "  # bodySchema did not expose input.body \u2014 replace <BODY_JSON> with the exact shape shown above."
+    );
+  }
+  return lines;
+};
 var formatCapability = (capability) => {
   const lines = [];
   lines.push(capability.name);
@@ -1543,9 +1767,10 @@ var formatCapability = (capability) => {
   }
   lines.push(`  Rating: ${formatRating(capability.rating)}`);
   lines.push(`  Status: ${capability.availabilityStatus ?? "unknown"}`);
-  lines.push(`  Cost: $${capability.displayCostAmount}/call`);
+  lines.push(...formatCost(capability));
   lines.push(`  URL: ${capability.url}`);
   lines.push(`  Method: ${capability.method}`);
+  lines.push(...buildTryItExample(capability));
   return lines.join("\n");
 };
 var getCommand = (appContext) => new Command4("get").description(
@@ -1614,8 +1839,9 @@ import {
   existsSync as existsSync2,
   mkdirSync as mkdirSync2,
   readdirSync,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   rmSync,
+  statSync,
   writeFileSync as writeFileSync2
 } from "fs";
 import { homedir as homedir2 } from "os";
@@ -1647,7 +1873,7 @@ var getPackageRoot = () => {
   }
   return dir;
 };
-var sha256File = (filePath) => createHash3("sha256").update(readFileSync3(filePath)).digest("hex");
+var sha256File = (filePath) => createHash3("sha256").update(readFileSync4(filePath)).digest("hex");
 var verifyFileCopy = (src, dest) => {
   if (!existsSync2(dest)) return false;
   return sha256File(src) === sha256File(dest);
@@ -1664,6 +1890,24 @@ var collectAllFiles = (dir) => {
   }
   return files;
 };
+var copyDirRecursive = (src, dest) => {
+  mkdirSync2(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join2(src, entry.name);
+    const destPath = join2(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      const data = readFileSync4(srcPath);
+      writeFileSync2(destPath, data);
+      try {
+        const mode = statSync(srcPath).mode;
+        chmodSync(destPath, mode);
+      } catch {
+      }
+    }
+  }
+};
 var installHook = (home) => {
   const claudeDir = join2(home, ".claude");
   if (!existsSync2(claudeDir)) {
@@ -1689,7 +1933,7 @@ var installHook = (home) => {
   let settings = {};
   if (existsSync2(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
     } catch {
     }
   }
@@ -1800,30 +2044,38 @@ var installSkills = (home) => {
   const skillsSourceDir = join2(getPackageRoot(), "skills");
   const skillDirs = readdirSync(skillsSourceDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   const installed = [];
+  const errors = [];
   for (const tool of AGENT_TOOLS) {
     const toolDetectPath = join2(home, tool.detectDir);
     if (!existsSync2(toolDetectPath)) {
       continue;
     }
-    const toolSkillsPath = join2(home, tool.skillsDir);
-    mkdirSync2(toolSkillsPath, { recursive: true });
-    for (const skillDir of skillDirs) {
-      const src = join2(skillsSourceDir, skillDir);
-      const dest = join2(toolSkillsPath, skillDir);
-      cpSync(src, dest, { recursive: true });
-      for (const srcFile of collectAllFiles(src)) {
-        const relPath = relative(src, srcFile);
-        const destFile = join2(dest, relPath);
-        if (!verifyFileCopy(srcFile, destFile)) {
-          throw new Error(
-            `Integrity check failed: ${destFile} does not match source`
-          );
+    try {
+      const toolSkillsPath = join2(home, tool.skillsDir);
+      mkdirSync2(toolSkillsPath, { recursive: true });
+      for (const skillDir of skillDirs) {
+        const src = join2(skillsSourceDir, skillDir);
+        const dest = join2(toolSkillsPath, skillDir);
+        copyDirRecursive(src, dest);
+        for (const srcFile of collectAllFiles(src)) {
+          const relPath = relative(src, srcFile);
+          const destFile = join2(dest, relPath);
+          if (!verifyFileCopy(srcFile, destFile)) {
+            throw new Error(
+              `Integrity check failed: ${destFile} does not match source`
+            );
+          }
         }
+        installed.push(`${tool.name}: ${dest}`);
       }
-      installed.push(`${tool.name}: ${dest}`);
+    } catch (err) {
+      errors.push({
+        tool: tool.name,
+        message: err instanceof Error ? err.message : String(err)
+      });
     }
   }
-  return installed;
+  return { installed, errors };
 };
 var runInit = async (appContext, options = {}) => {
   appContext.services.analyticsService.capture("init_started", {
@@ -1839,7 +2091,7 @@ var runInit = async (appContext, options = {}) => {
     const walletExists = (() => {
       if (!existsSync2(configPath)) return false;
       try {
-        const existing = JSON.parse(readFileSync3(configPath, "utf8"));
+        const existing = JSON.parse(readFileSync4(configPath, "utf8"));
         return !!existing.privateKey;
       } catch {
         return false;
@@ -1849,7 +2101,7 @@ var runInit = async (appContext, options = {}) => {
       const privateKey = generatePrivateKey();
       const account = privateKeyToAccount(privateKey);
       mkdirSync2(zeroDir, { recursive: true });
-      const existing = existsSync2(configPath) ? JSON.parse(readFileSync3(configPath, "utf8")) : {};
+      const existing = existsSync2(configPath) ? JSON.parse(readFileSync4(configPath, "utf8")) : {};
       writeFileSync2(
         configPath,
         JSON.stringify(
@@ -1863,7 +2115,7 @@ var runInit = async (appContext, options = {}) => {
       console.log(`Wallet address: ${account.address}`);
     } else {
       try {
-        const existing = JSON.parse(readFileSync3(configPath, "utf8"));
+        const existing = JSON.parse(readFileSync4(configPath, "utf8"));
         const account = privateKeyToAccount(existing.privateKey);
         walletAddress = account.address;
       } catch {
@@ -1881,15 +2133,24 @@ var runInit = async (appContext, options = {}) => {
     }
     currentStep = "skills";
     try {
-      const installed = installSkills(home);
+      const { installed, errors } = installSkills(home);
       for (const entry of installed) {
         const toolName = entry.split(":")[0];
         if (toolName && !agentsWithSkills.includes(toolName)) {
           agentsWithSkills.push(toolName);
         }
       }
+      if (errors.length > 0) {
+        skillsError = errors.map((e) => `${e.tool}: ${e.message}`).join("; ");
+        for (const e of errors) {
+          console.error(
+            `Warning: failed to install skills for ${e.tool}: ${e.message}`
+          );
+        }
+      }
     } catch (err) {
       skillsError = err instanceof Error ? err.message : "unknown skills error";
+      console.error(`Warning: skills install failed: ${skillsError}`);
     }
     currentStep = "hook";
     try {
@@ -1971,7 +2232,7 @@ ${removedList}`);
 );
 
 // src/commands/review-command.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 import { Command as Command6 } from "commander";
 import { z as z3 } from "zod";
 var bulkEntrySchema2 = z3.object({
@@ -2013,35 +2274,66 @@ Examples:
     try {
       const { analyticsService, apiService } = appContext.services;
       if (options.fromFile) {
-        const contents = readFileSync4(options.fromFile, "utf8");
+        const contents = readFileSync5(options.fromFile, "utf8");
         const lines = contents.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
-        let ok = 0;
-        let failed = 0;
+        const parsed = [];
+        let parseFailures = 0;
         for (const [idx, line] of lines.entries()) {
           const lineNum = idx + 1;
           try {
-            const parsed = bulkEntrySchema2.parse(JSON.parse(line));
-            const result2 = await apiService.createReview(parsed);
-            ok += 1;
-            console.log(
-              `[${lineNum}] ${parsed.runId} -> ${result2.reviewId}`
-            );
-            analyticsService.capture("review_submitted", {
-              runId: parsed.runId,
-              success: parsed.success,
-              accuracy: parsed.accuracy,
-              value: parsed.value,
-              reliability: parsed.reliability,
-              hasContent: !!parsed.content,
-              bulk: true
+            parsed.push({
+              lineNum,
+              entry: bulkEntrySchema2.parse(JSON.parse(line))
             });
           } catch (err) {
-            failed += 1;
+            parseFailures += 1;
             console.error(
-              `[${lineNum}] FAILED: ${err instanceof Error ? err.message : String(err)}`
+              `[${lineNum}] PARSE FAILED: ${err instanceof Error ? err.message : String(err)}`
             );
           }
         }
+        if (parsed.length === 0) {
+          console.error("No valid review lines found in file.");
+          process.exitCode = 1;
+          return;
+        }
+        const Chunk = 100;
+        let ok = 0;
+        let failed = parseFailures;
+        for (let i = 0; i < parsed.length; i += Chunk) {
+          const chunk = parsed.slice(i, i + Chunk);
+          const response = await apiService.createReviewsBatch(
+            chunk.map((p) => p.entry)
+          );
+          for (const [chunkIdx, item] of response.results.entries()) {
+            const lineNum = chunk[chunkIdx]?.lineNum ?? i + chunkIdx + 1;
+            if (item.ok) {
+              ok += 1;
+              const suffix = item.updated ? " (updated)" : "";
+              console.log(
+                `[${lineNum}] ${item.runId} -> ${item.reviewId}${suffix}`
+              );
+              const entry = chunk[chunkIdx]?.entry;
+              if (entry) {
+                analyticsService.capture("review_submitted", {
+                  runId: entry.runId,
+                  success: entry.success,
+                  accuracy: entry.accuracy,
+                  value: entry.value,
+                  reliability: entry.reliability,
+                  hasContent: !!entry.content,
+                  bulk: true,
+                  updated: item.updated
+                });
+              }
+            } else {
+              failed += 1;
+              console.error(
+                `[${lineNum}] FAILED (${item.status}): ${item.error}`
+              );
+            }
+          }
+        }
         console.log(`
 Bulk review complete: ${ok} ok, ${failed} failed`);
         if (failed > 0) process.exitCode = 1;
@@ -2080,7 +2372,7 @@ Bulk review complete: ${ok} ok, ${failed} failed`);
         }
         if (list.runs.length > 1) {
           console.error(
-            `Multiple un-reviewed runs for "${options.capability}". Run "zero runs --capability ${options.capability} --unreviewed" and pass the runId explicitly.`
+            `Multiple un-reviewed runs for "${options.capability}". Either pass a runId explicitly (see "zero runs --capability ${options.capability} --unreviewed"), or review them in one call via "zero review --from-file <reviews.jsonl>".`
           );
           process.exitCode = 1;
           return;
@@ -2294,7 +2586,8 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         capabilities: result.capabilities.map((c) => ({
           position: c.position,
           id: c.id,
-          url: c.url
+          url: c.url,
+          displayCostAmount: c.cost.amount
         }))
       });
       console.log(formatSearchResults(result.capabilities));
@@ -2337,7 +2630,7 @@ Read the full terms at: ${TERMS_URL}
 });
 
 // src/commands/wallet-command.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
 import { Command as Command10 } from "commander";
@@ -2432,7 +2725,7 @@ var walletSetCommand = (appContext) => new Command10("set").description("Set wal
   const configPath = join3(zeroDir, "config.json");
   if (!options.force && existsSync3(configPath)) {
     try {
-      const existing2 = JSON.parse(readFileSync5(configPath, "utf8"));
+      const existing2 = JSON.parse(readFileSync6(configPath, "utf8"));
       if (existing2.privateKey) {
         console.error(
           "Wallet already configured. Use --force to overwrite."
@@ -2444,7 +2737,7 @@ var walletSetCommand = (appContext) => new Command10("set").description("Set wal
     }
   }
   mkdirSync3(zeroDir, { recursive: true });
-  const existing = existsSync3(configPath) ? JSON.parse(readFileSync5(configPath, "utf8")) : {};
+  const existing = existsSync3(configPath) ? JSON.parse(readFileSync6(configPath, "utf8")) : {};
   writeFileSync3(
     configPath,
     JSON.stringify(
@@ -2474,7 +2767,7 @@ var walletCommand = (appContext) => {
 };
 
 // src/commands/welcome-command.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join4 } from "path";
 import { Command as Command11 } from "commander";
@@ -2485,7 +2778,7 @@ var readPrivateKey = () => {
   const configPath = join4(homedir4(), ".zero", "config.json");
   if (!existsSync4(configPath)) return null;
   try {
-    const config = JSON.parse(readFileSync6(configPath, "utf8"));
+    const config = JSON.parse(readFileSync7(configPath, "utf8"));
     if (typeof config.privateKey === "string") {
       return config.privateKey;
     }
@@ -2537,7 +2830,7 @@ If your browser didn't open, paste the URL above.`
 // src/app.ts
 var createApp = (appContext) => {
   const { analyticsService } = appContext.services;
-  const program = new Command12().name("zero").description("Zero CLI \u2014 Search engine and payment platform for AI agents").version(package_default.version, "-v, --version").exitOverride().hook("preAction", async (_thisCommand, actionCommand) => {
+  const program = new Command12().name("zero").description("Zero CLI \u2014 Search engine for AI agents").version(package_default.version, "-v, --version").exitOverride().hook("preAction", async (_thisCommand, actionCommand) => {
     const agentFlag = actionCommand.opts().agent;
     if (typeof agentFlag === "string" && agentFlag.trim().length > 0) {
       analyticsService.setAgentHost(agentFlag.trim());
@@ -2584,14 +2877,14 @@ var getEnv = () => {
 
 // src/app/app-services.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join6 } from "path";
 import { privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
 
 // src/services/analytics-service.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname2 } from "path";
 import { PostHog } from "posthog-node";
 var POSTHOG_API_KEY = "phc_B2vLyNxAf2mnqvdPQajf4d4b2iXc35dep2ZrvebMJLuX";
@@ -2614,7 +2907,7 @@ var AnalyticsService = class {
     let persistedAnonId;
     try {
       if (existsSync5(opts.configPath)) {
-        const config = JSON.parse(readFileSync7(opts.configPath, "utf8"));
+        const config = JSON.parse(readFileSync8(opts.configPath, "utf8"));
         if (config.telemetry === false) {
           telemetryEnabled = false;
         }
@@ -2639,7 +2932,7 @@ var AnalyticsService = class {
       try {
         const dir = dirname2(opts.configPath);
         mkdirSync4(dir, { recursive: true });
-        const existing = existsSync5(opts.configPath) ? JSON.parse(readFileSync7(opts.configPath, "utf8")) : {};
+        const existing = existsSync5(opts.configPath) ? JSON.parse(readFileSync8(opts.configPath, "utf8")) : {};
         writeFileSync4(
           opts.configPath,
           JSON.stringify({ ...existing, anonId: newAnonId }, null, 2)
@@ -2675,7 +2968,7 @@ var AnalyticsService = class {
     if (anonId === walletAddress) return;
     let aliasedTo;
     try {
-      const config = JSON.parse(readFileSync7(configPath, "utf8"));
+      const config = JSON.parse(readFileSync8(configPath, "utf8"));
       if (typeof config.aliasedTo === "string") {
         aliasedTo = config.aliasedTo;
       }
@@ -2684,7 +2977,7 @@ var AnalyticsService = class {
     if (aliasedTo === walletAddress) return;
     this.posthog.alias({ distinctId: walletAddress, alias: anonId });
     try {
-      const config = existsSync5(configPath) ? JSON.parse(readFileSync7(configPath, "utf8")) : {};
+      const config = existsSync5(configPath) ? JSON.parse(readFileSync8(configPath, "utf8")) : {};
       writeFileSync4(
         configPath,
         JSON.stringify({ ...config, aliasedTo: walletAddress }, null, 2)
@@ -2727,7 +3020,7 @@ var AnalyticsService = class {
 };
 
 // src/services/state-service.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
 var StateService = class {
   constructor(zeroDir) {
@@ -2742,7 +3035,7 @@ var StateService = class {
   loadLastSearch = () => {
     try {
       if (!existsSync6(this.lastSearchPath)) return null;
-      const raw = readFileSync8(this.lastSearchPath, "utf8");
+      const raw = readFileSync9(this.lastSearchPath, "utf8");
       return JSON.parse(raw);
     } catch {
       return null;
@@ -2795,7 +3088,7 @@ var getServices = (env) => {
   if (!privateKey) {
     try {
       if (existsSync7(configPath)) {
-        const config = JSON.parse(readFileSync9(configPath, "utf8"));
+        const config = JSON.parse(readFileSync10(configPath, "utf8"));
         if (typeof config.privateKey === "string") {
           privateKey = config.privateKey;
         }
@@ -2807,7 +3100,7 @@ var getServices = (env) => {
   let lowBalanceWarning = 1;
   try {
     if (existsSync7(configPath)) {
-      const config = JSON.parse(readFileSync9(configPath, "utf8"));
+      const config = JSON.parse(readFileSync10(configPath, "utf8"));
       if (typeof config.lowBalanceWarning === "number") {
         lowBalanceWarning = config.lowBalanceWarning;
       }

package/package.json

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

package/skills/zero/SKILL.md

@@ -85,8 +85,8 @@ 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>
@@ -95,32 +95,118 @@ zero review --capability <slug> --success --accuracy <1-5> --value <1-5> --relia
 ### 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.
+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.
 
-### Request Templates
+**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
+
+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 with JSON body
+**POST capabilities — send `input.body` as JSON:**
+
+```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:**
 
-# Cap spend at $0.50
+```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` so future agents see the failure. 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.
@@ -218,6 +304,7 @@ zero wallet balance
 | 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