@zeroxyz/cli 0.0.33 → 0.0.36

package/README.md

@@ -48,6 +48,16 @@ zero search "image classification"
 
 Results are numbered. Use `zero get <number>` to view details.
 
+**Cost filtering.** By default, results are filtered to capabilities priced **≤ $30/call** as a wallet-safety cap. Override per-call:
+
+```bash
+zero search "image classification" --max-cost 5      # cap at $5/call
+zero search "expensive deep research" --max-cost 100 # raise the cap for hard tasks
+zero search "image classification" --free            # only free capabilities
+```
+
+Other useful filters: `--min-rating <1-5>`, `--min-trust <0-100>`, `--protocol x402|mpp`, `--status healthy|degraded|down`, `--source <name>`, `--all` (no trust/health filtering).
+
 ### `zero get <position>`
 
 Get full details for a capability from the last search results.

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
-// src/app.ts
-import { Command as Command12 } from "commander";
+// src/index.ts
+import { homedir as homedir7 } from "os";
+import { join as join8 } from "path";
 
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.33",
+  version: "0.0.36",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -59,6 +60,9 @@ var package_default = {
   }
 };
 
+// src/app.ts
+import { Command as Command12 } from "commander";
+
 // src/commands/bug-report-command.ts
 import { createHash as createHash2 } from "crypto";
 import { readFileSync } from "fs";
@@ -77,6 +81,7 @@ var searchResultSchema = z.object({
   description: z.string(),
   whatItDoes: z.string().nullable().optional(),
   url: z.string(),
+  urlTemplate: z.string().nullable().optional(),
   cost: z.object({ amount: z.string(), asset: z.string() }),
   rating: z.object({
     score: z.string(),
@@ -103,6 +108,7 @@ var capabilityResponseSchema = z.object({
   name: z.string(),
   description: z.string(),
   url: z.string(),
+  urlTemplate: z.string().nullable().optional(),
   method: z.string(),
   headers: z.record(z.string(), z.string()).nullable(),
   bodySchema: z.record(z.string(), z.unknown()).nullable(),
@@ -146,7 +152,10 @@ var capabilityResponseSchema = z.object({
     blockchainActivity: z.number().nullable(),
     performance: z.number().nullable()
   }).nullable().optional(),
-  availabilityStatus: z.enum(["healthy", "degraded", "down", "unknown"]).nullable().optional()
+  availabilityStatus: z.enum(["healthy", "degraded", "down", "unknown"]).nullable().optional(),
+  activationCount: z.number().optional(),
+  lastUsedAt: z.string().nullable().optional(),
+  lastSuccessfullyRanAt: z.string().nullable().optional()
 });
 var createRunResponseSchema = z.object({
   runId: z.string()
@@ -614,6 +623,7 @@ var configCommand = (_appContext) => new Command2("config").description("View or
 });
 
 // src/commands/fetch-command.ts
+import { createHash as createHash3 } from "crypto";
 import { readFileSync as readFileSync3 } from "fs";
 import { resolve as resolvePath } from "path";
 import { Command as Command3 } from "commander";
@@ -737,6 +747,7 @@ var pickSessionCloseAmount = (receipt, openTimeCumulative) => {
   const accepted = BigInt(receipt.acceptedCumulative);
   const spent = BigInt(receipt.spent);
   const fromReceipt = accepted > spent ? accepted : spent;
+  if (receipt.metered === true) return fromReceipt;
   return fromReceipt > openTimeCumulative ? fromReceipt : openTimeCumulative;
 };
 var PaymentService = class {
@@ -1203,6 +1214,22 @@ var truncateQuery = (raw) => raw.length > QUERY_MAX ? `${raw.slice(0, QUERY_MAX)
 var truncateError = (raw) => raw.length > ERROR_MAX ? `${raw.slice(0, ERROR_MAX)}\u2026` : raw;
 
 // src/commands/fetch-command.ts
+var sniffJsonShape = (buf) => {
+  let i = 0;
+  if (buf.length >= 3 && buf[0] === 239 && buf[1] === 187 && buf[2] === 191) {
+    i = 3;
+  }
+  while (i < buf.length && (buf[i] === 32 || buf[i] === 9 || buf[i] === 10 || buf[i] === 13)) {
+    i++;
+  }
+  if (i >= buf.length) return false;
+  return buf[i] === 123 || buf[i] === 91;
+};
+var urlMatchesTemplate = (url, template) => {
+  const escaped = template.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const withCaptures = escaped.replace(/\\\{[^/\\}]+\\\}/g, "[^/]+");
+  return new RegExp(`^${withCaptures}$`).test(url);
+};
 var isTextContentType = (contentType) => {
   if (!contentType) return true;
   const ct = contentType.toLowerCase().split(";")[0]?.trim() ?? "";
@@ -1285,7 +1312,10 @@ var detectPaymentRequirement = async (response) => {
 };
 var fetchCommand = (appContext) => new Command3("fetch").description(
   "Fetch a capability URL, handling 402 challenges automatically"
-).argument("<url>", "URL to fetch").option(
+).argument(
+  "[url]",
+  "URL to fetch. Optional when --capability is provided \u2014 the URL is resolved from the capability."
+).option(
   "-X, --method <method>",
   "HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to POST when -d is set, otherwise GET"
 ).option(
@@ -1317,6 +1347,73 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         walletService
       } = appContext.services;
       const startTime = Date.now();
+      let resolvedUrl;
+      let resolvedMethodFromCapability;
+      let resolvedCapabilityName;
+      if (!url) {
+        if (!options.capability) {
+          console.error(
+            "Missing URL. Pass a URL argument or --capability <uid|slug> so the URL can be resolved from the capability."
+          );
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          const cap = await apiService.getCapability(options.capability);
+          resolvedUrl = cap.url;
+          resolvedMethodFromCapability = cap.method;
+          resolvedCapabilityName = cap.name;
+        } catch (err) {
+          console.error(
+            `Failed to resolve --capability ${options.capability}: ${err instanceof Error ? err.message : String(err)}`
+          );
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        resolvedUrl = url;
+      }
+      if (!url && options.capability && !stateService.findSearchContextByCapability(options.capability)) {
+        try {
+          let capName = resolvedCapabilityName;
+          if (capName === void 0) {
+            const cap = await apiService.getCapability(options.capability);
+            capName = cap.name;
+          }
+          const searchResult = await apiService.search({ query: capName });
+          const slugFoundInResults = searchResult.capabilities.some(
+            (c) => c.slug === options.capability || c.id === options.capability
+          );
+          stateService.saveLastSearch({
+            searchId: searchResult.searchId,
+            capabilities: searchResult.capabilities.map((c) => ({
+              position: c.position,
+              id: c.id,
+              url: c.url,
+              urlTemplate: c.urlTemplate ?? null,
+              displayCostAmount: c.cost.amount
+            }))
+          });
+          analyticsService.capture("search_executed", {
+            query: truncateQuery(capName),
+            queryLength: capName.length,
+            resultCount: searchResult.capabilities.length,
+            searchId: searchResult.searchId,
+            total: searchResult.total,
+            hasMore: searchResult.hasMore,
+            json: false,
+            triggeredBy: "slug_handoff",
+            slugFoundInResults
+          });
+          analyticsService.capture("capability_viewed", {
+            capabilityId: options.capability,
+            fromLastSearch: false,
+            searchId: searchResult.searchId,
+            triggeredBy: "slug_handoff"
+          });
+        } catch {
+        }
+      }
       let resolvedBody;
       try {
         resolvedBody = resolveRequestBody(
@@ -1324,9 +1421,13 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           options.dataStdin ?? false
         );
       } catch (err) {
-        console.error(
-          err instanceof Error ? err.message : "Failed to read request body"
-        );
+        const message = err instanceof Error ? err.message : "Failed to read request body";
+        analyticsService.capture("fetch_error", {
+          cliErrorClass: /exceeds the .* byte limit/.test(message) ? "payload_too_large" : "schema_validation_failed",
+          url: redactUrl(resolvedUrl),
+          error: truncateError(message)
+        });
+        console.error(message);
         process.exitCode = 1;
         return;
       }
@@ -1343,21 +1444,30 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         (k) => k.toLowerCase() === "content-type"
       );
       if (resolvedBody && !hasContentType) {
-        headers["content-type"] = Buffer.isBuffer(resolvedBody) ? "application/octet-stream" : "application/json";
+        headers["content-type"] = Buffer.isBuffer(resolvedBody) ? sniffJsonShape(resolvedBody) ? "application/json" : "application/octet-stream" : "application/json";
       }
       const log = (msg) => console.error(`  ${msg}`);
-      const method = options.method ? options.method.toUpperCase() : resolvedBody ? "POST" : "GET";
+      const method = options.method ? options.method.toUpperCase() : resolvedMethodFromCapability && !resolvedBody ? resolvedMethodFromCapability.toUpperCase() : resolvedBody ? "POST" : "GET";
       const requestInit = {
         method,
         headers,
         body: resolvedBody
       };
-      const lastSearch = stateService.loadLastSearch();
-      const matchedCapability = lastSearch?.capabilities.find(
-        (c) => url.startsWith(c.url)
-      );
-      const capabilityId = options.capability ?? matchedCapability?.id ?? null;
-      const searchId = matchedCapability ? lastSearch?.searchId : void 0;
+      const explicitCapabilityCtx = options.capability ? stateService.findSearchContextByCapability(options.capability) : null;
+      const urlCtx = stateService.findSearchContextByUrl(resolvedUrl, {
+        matchTemplate: (template) => {
+          try {
+            return urlMatchesTemplate(resolvedUrl, template);
+          } catch {
+            return false;
+          }
+        }
+      });
+      const matchCtx = explicitCapabilityCtx ?? urlCtx;
+      const capabilityId = options.capability ?? matchCtx?.capabilityId ?? null;
+      const searchId = matchCtx?.searchId;
+      const resultRank = matchCtx?.resultRank;
+      const matchedDisplayCostAmount = matchCtx?.displayCostAmount;
       const skipReasons = [];
       if (!apiService.walletAddress) {
         skipReasons.push(
@@ -1368,6 +1478,19 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         skipReasons.push(
           "no capability resolved \u2014 pass --capability <uid|slug> or run `zero search` first so the URL can be matched"
         );
+        if (!options.capability) {
+          const lastSearch = stateService.loadLastSearch();
+          const cached = lastSearch?.capabilities ?? [];
+          analyticsService.capture("capability_resolution_missed", {
+            url: redactUrl(resolvedUrl),
+            method,
+            hasLastSearch: lastSearch !== null,
+            lastSearchSize: cached.length,
+            lastSearchHasTemplates: cached.some(
+              (c) => Boolean(c.urlTemplate)
+            )
+          });
+        }
       }
       let finalResponse;
       let bodyBytes;
@@ -1377,20 +1500,20 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       let sessionMeta;
       let fetchError;
       try {
-        log(`Calling ${url}...`);
-        const response = await fetch(url, requestInit);
+        log(`Calling ${resolvedUrl}...`);
+        const response = await fetch(resolvedUrl, requestInit);
         const paymentReq = await detectPaymentRequirement(response);
         if (paymentReq) {
           log(
             `Payment required (${paymentReq.protocol}) \u2014 preparing payment...`
           );
           const result = await paymentService.handlePayment(
-            url,
+            resolvedUrl,
             requestInit,
             paymentReq,
             options.maxPay,
             log,
-            matchedCapability?.displayCostAmount
+            matchedDisplayCostAmount
           );
           finalResponse = result.response;
           paymentMeta = {
@@ -1487,6 +1610,15 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         } catch {
         }
       }
+      const status = finalResponse?.status;
+      const isFailure = !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
+      let errorSnippetHash;
+      let errorSnippetLength;
+      if (isFailure && body && !bodyIsBinary) {
+        const snippet = body.slice(0, 500);
+        errorSnippetHash = createHash3("sha256").update(snippet).digest("hex");
+        errorSnippetLength = snippet.length;
+      }
       let runId = null;
       if (capabilityId && apiService.walletAddress) {
         let requestSchema;
@@ -1511,6 +1643,8 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
             latencyMs,
             requestSchema,
             responseSchema,
+            errorSnippetHash,
+            errorSnippetLength,
             ...paymentMeta && {
               costAmount: paymentMeta.amount,
               costAsset: paymentMeta.asset,
@@ -1527,10 +1661,9 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           );
         }
       }
-      const status = finalResponse?.status;
       const outcome = !finalResponse ? "network_error" : status === 402 && !paymentMeta ? "payment_failed" : status !== void 0 && status >= 400 && status !== 402 ? "server_error" : "success";
       analyticsService.capture("fetch_executed", {
-        url: redactUrl(url),
+        url: redactUrl(resolvedUrl),
         status,
         outcome,
         latencyMs,
@@ -1539,10 +1672,26 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         paymentAmount: paymentMeta?.amount,
         capabilityId: capabilityId ?? void 0,
         searchId: searchId ?? void 0,
+        resultRank: resultRank ?? void 0,
         runId: runId ?? void 0,
         runTracked: !!runId,
         ...fetchError && { error: truncateError(fetchError.message) }
       });
+      const isFetchFailure = Boolean(fetchError) || !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
+      if (isFetchFailure) {
+        const cliErrorClass = fetchError || !finalResponse ? "network" : !apiService.walletAddress ? "auth_missing" : "unknown";
+        analyticsService.capture("fetch_error", {
+          cliErrorClass,
+          capabilityId: capabilityId ?? void 0,
+          searchId: searchId ?? void 0,
+          resultRank: resultRank ?? void 0,
+          url: redactUrl(resolvedUrl),
+          error: truncateError(
+            fetchError?.message ?? skipReasons.join("; ")
+          ),
+          skippedRun: !runId && skipReasons.length > 0
+        });
+      }
       if (fetchError && !options.json) {
         console.error(`  Fetch failed: ${fetchError.message}`);
       }
@@ -1609,7 +1758,16 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         process.exitCode = 1;
       }
     } catch (err) {
-      console.error(err instanceof Error ? err.message : "Fetch failed");
+      const message = err instanceof Error ? err.message : "Fetch failed";
+      try {
+        appContext.services.analyticsService.capture("fetch_error", {
+          cliErrorClass: "unknown",
+          url: url ? redactUrl(url) : "unknown",
+          error: truncateError(message)
+        });
+      } catch {
+      }
+      console.error(message);
       process.exitCode = 1;
     }
   }
@@ -1621,6 +1779,22 @@ var formatReviewCount = (count) => {
   if (count >= 1e3) return `${(count / 1e3).toFixed(1)}k`;
   return count.toString();
 };
+var formatRelativeTimestamp = (iso) => {
+  if (!iso) return "never";
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "never";
+  const diffSec = Math.max(0, Math.round((Date.now() - then) / 1e3));
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.round(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.round(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.round(diffHr / 24);
+  if (diffDay < 30) return `${diffDay}d ago`;
+  const diffMo = Math.round(diffDay / 30);
+  if (diffMo < 12) return `${diffMo}mo ago`;
+  return `${Math.round(diffMo / 12)}y ago`;
+};
 var formatTrustScore = (capability) => {
   if (capability.trustScore != null) {
     return `Trust Score: ${capability.trustScore}/100`;
@@ -1705,11 +1879,11 @@ var buildTryItExample = (capability) => {
       ([k, schema]) => `${encodeURIComponent(k)}=${encodeURIComponent(placeholderFor(k, schema))}`
     ).join("&") : "";
     const url = qs ? `${capability.url}?${qs}` : capability.url;
-    const urlLine = `  zero fetch "${url}"`;
+    const urlLine = `  zero fetch --capability ${capability.slug} "${url}"`;
     if (headerFlags.length === 0) {
       lines.push(urlLine);
     } else {
-      lines.push(`  zero fetch \\`);
+      lines.push(`  zero fetch --capability ${capability.slug} \\`);
       for (const h of headerFlags) lines.push(`    ${h} \\`);
       lines.push(`    "${url}"`);
     }
@@ -1727,11 +1901,10 @@ var buildTryItExample = (capability) => {
     ])
   ) : null;
   const bodyJson = samplePayload ? JSON.stringify(samplePayload) : "<BODY_JSON>";
-  lines.push(`  zero fetch \\`);
+  lines.push(`  zero fetch --capability ${capability.slug} \\`);
   if (method !== "POST") lines.push(`    -X ${method} \\`);
   for (const h of headerFlags) lines.push(`    ${h} \\`);
-  lines.push(`    -d '${bodyJson}' \\`);
-  lines.push(`    ${capability.url}`);
+  lines.push(`    -d '${bodyJson}'`);
   if (!body) {
     lines.push(
       "  # bodySchema did not expose input.body \u2014 replace <BODY_JSON> with the exact shape shown above."
@@ -1768,6 +1941,9 @@ var formatCapability = (capability) => {
   lines.push(...formatCost(capability));
   lines.push(`  URL: ${capability.url}`);
   lines.push(`  Method: ${capability.method}`);
+  lines.push(
+    `  Last successful run: ${formatRelativeTimestamp(capability.lastSuccessfullyRanAt)}`
+  );
   lines.push(...buildTryItExample(capability));
   return lines.join("\n");
 };
@@ -1807,6 +1983,8 @@ var getCommand = (appContext) => new Command4("get").description(
       searchId = lastSearch.searchId;
     } else {
       capabilityId = identifier;
+      const ctx = stateService.findSearchContextByCapability(identifier);
+      if (ctx) searchId = ctx.searchId;
     }
     const capability = await apiService.getCapability(
       capabilityId,
@@ -1830,7 +2008,7 @@ var getCommand = (appContext) => new Command4("get").description(
 });
 
 // src/commands/init-command.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import {
   chmodSync as chmodSync2,
   existsSync as existsSync2,
@@ -1904,10 +2082,12 @@ var color = {
   magenta: (s) => wrap("35", s),
   green: (s) => wrap("32", s),
   yellow: (s) => wrap("33", s),
+  red: (s) => wrap("31", s),
   gray: (s) => wrap("90", s),
   boldCyan: (s) => wrap("1;36", s),
   boldMagenta: (s) => wrap("1;35", s),
-  boldGreen: (s) => wrap("1;32", s)
+  boldGreen: (s) => wrap("1;32", s),
+  boldRed: (s) => wrap("1;31", s)
 };
 var printZeroBanner = () => {
   console.log("");
@@ -1949,12 +2129,17 @@ var sectionDivider = () => {
 var printReadyFooter = () => {
   const lines = [
     "",
-    `  ${color.boldGreen("Zero is ready!")} Run ${color.cyan("`zero search`")} to find capabilities.`,
+    `  ${color.boldGreen("Zero is ready!")} Zero works best with an AI agent.`,
+    `  Open ${color.boldRed("Claude Code")}, Codex, Cursor, Blackbox, or your agent of choice`,
+    "  and try this prompt to get started:",
     "",
-    `  ${color.dim("Try:")}`,
-    `    ${color.cyan('zero search "translate text to Spanish"')}`,
-    `    ${color.cyan('zero search "generate an image"')}`,
-    `    ${color.cyan('zero search "weather forecast"')}`,
+    `    ${color.cyan("What is zero and how do I use it?")}`,
+    "",
+    "  You can also just tell your agent examples of what you are trying to do:",
+    "",
+    `    ${color.cyan("Can you use zero to deploy an NYC weather website")}`,
+    `    ${color.cyan("Email me an image of a crystalline rocket ship with zero")}`,
+    `    ${color.cyan("Create a demo video with real voiceover for my project using zero")}`,
     "",
     `  ${color.dim("By using Zero, you agree to our Terms of Service:")}`,
     `    ${color.dim("https://zero.xyz/terms-of-service")}`,
@@ -2010,7 +2195,7 @@ var getCliModuleDir = () => {
   }
   return __dirname;
 };
-var sha256File = (filePath) => createHash3("sha256").update(readFileSync4(filePath)).digest("hex");
+var sha256File = (filePath) => createHash4("sha256").update(readFileSync4(filePath)).digest("hex");
 var verifyFileCopy = (src, dest) => {
   if (!existsSync2(dest)) return false;
   return sha256File(src) === sha256File(dest);
@@ -2658,6 +2843,20 @@ Bulk review complete: ${ok} ok, ${failed} failed`);
 
 // src/commands/runs-command.ts
 import { Command as Command7 } from "commander";
+var USD_ASSETS = /* @__PURE__ */ new Set(["USD", "USDC"]);
+var formatCost2 = (cost) => {
+  if (!cost) return "free";
+  const { amount, asset } = cost;
+  const prefix = asset && USD_ASSETS.has(asset.toUpperCase()) ? "$" : "";
+  const priced = asset ? `${prefix}${amount} ${asset}` : amount;
+  return Number(amount) === 0 ? `free (${priced})` : priced;
+};
+var formatPayment = (payment) => {
+  if (!payment) return "\u2014";
+  const chain = payment.chain ? `:${payment.chain}` : "";
+  const mode = payment.mode ? ` (${payment.mode})` : "";
+  return `${payment.protocol}${chain}${mode}`;
+};
 var runsCommand = (appContext) => new Command7("runs").description("List your recent capability runs").addHelpText(
   "after",
   `
@@ -2667,12 +2866,13 @@ A leading [\u2713] means the run already has a review; [ ] means it does not.
 Examples:
   zero runs                            # most recent runs
   zero runs --unreviewed               # filter to runs without a review
-  zero runs --capability translate-en  # filter to one capability (uid or slug)`
+  zero runs --capability translate-en  # filter to one capability (uid or slug)
+  zero runs --json                     # full structured output for scripts`
 ).option("--capability <id>", "Filter by capability uid or slug").option("--unreviewed", "Only show runs without a review").option(
   "--limit <n>",
   "Max rows (1-100, default 25)",
   (v) => Number.parseInt(v, 10)
-).option(
+).option("--json", "Output raw JSON to stdout").option(
   "--agent <name>",
   "Identify your agent host for this invocation. Overrides auto-detect for this call only."
 ).action(
@@ -2684,6 +2884,10 @@ Examples:
         unreviewed: options.unreviewed,
         limit: options.limit
       });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
       if (result.runs.length === 0) {
         console.log("No runs found.");
         return;
@@ -2693,8 +2897,10 @@ Examples:
         const mark = r.reviewed ? "\u2713" : " ";
         const status = r.status ?? "\u2014";
         const latency = r.latencyMs != null ? `${r.latencyMs}ms` : "\u2014";
+        const cost = formatCost2(r.cost);
+        const payment = formatPayment(r.payment);
         console.log(
-          `[${mark}] ${r.uid}  ${r.capabilitySlug}  status=${status}  ${latency}  ${when}`
+          `[${mark}] ${r.uid}  ${r.capabilitySlug}  status=${status}  ${latency}  ${cost}  ${payment}  ${when}`
         );
       }
       if (result.nextCursor) {
@@ -2710,6 +2916,7 @@ Examples:
 
 // src/commands/search-command.ts
 import { Command as Command8 } from "commander";
+var DEFAULT_MAX_COST_USD = "30";
 var formatReviewCount2 = (count) => {
   if (count >= 1e3) return `${(count / 1e3).toFixed(1)}k`;
   return count.toString();
@@ -2747,7 +2954,10 @@ var formatSearchResults = (results) => {
      "${displayDescription}"`;
   }).join("\n");
 };
-var searchCommand = (appContext) => new Command8("search").description("Search for capabilities").argument("<query>", "Search query").option("--json", "Output raw JSON to stdout").option("--offset <n>", "Pagination offset", Number).option("--limit <n>", "Results per page", Number).option("--free", "Only show free capabilities").option("--max-cost <amount>", "Maximum cost per call").option("--min-rating <stars>", "Minimum star rating (1-5)", Number).option("--protocol <protocol>", "Payment protocol (x402 or mpp)").option("--min-trust <n>", "Minimum trust score (0-100)", Number).option(
+var searchCommand = (appContext) => new Command8("search").description("Search for capabilities").argument("<query>", "Search query").option("--json", "Output raw JSON to stdout").option("--offset <n>", "Pagination offset", Number).option("--limit <n>", "Results per page", Number).option("--free", "Only show free capabilities").option(
+  "--max-cost <amount>",
+  `Maximum cost per call in USD (default: ${DEFAULT_MAX_COST_USD})`
+).option("--min-rating <stars>", "Minimum star rating (1-5)", Number).option("--protocol <protocol>", "Payment protocol (x402 or mpp)").option("--min-trust <n>", "Minimum trust score (0-100)", Number).option(
   "--status <status>",
   "Filter by availability (healthy, degraded, down)"
 ).option("--all", "Show all results (no trust or health filtering)").option(
@@ -2770,6 +2980,12 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         process.exitCode = 1;
         return;
       }
+      let effectiveMaxCost = options.maxCost;
+      let appliedDefaultMaxCost = false;
+      if (effectiveMaxCost === void 0 && !options.free) {
+        effectiveMaxCost = DEFAULT_MAX_COST_USD;
+        appliedDefaultMaxCost = true;
+      }
       const validStatuses = ["healthy", "degraded", "down"];
       if (options.status && !validStatuses.includes(options.status)) {
         console.error(
@@ -2783,7 +2999,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         offset: options.offset,
         limit: options.limit,
         freeOnly: options.free,
-        maxCost: options.maxCost,
+        maxCost: effectiveMaxCost,
         minRating: options.minRating,
         protocol: options.protocol,
         minTrust: options.minTrust,
@@ -2802,7 +3018,8 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         offset: options.offset,
         limit: options.limit,
         freeOnly: options.free ?? false,
-        maxCost: options.maxCost,
+        maxCost: effectiveMaxCost,
+        maxCostDefaulted: appliedDefaultMaxCost,
         minRating: options.minRating,
         protocol: options.protocol,
         minTrust: options.minTrust,
@@ -2813,7 +3030,17 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         json: options.json ?? false
       });
       if (options.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(
+          JSON.stringify(
+            {
+              ...result,
+              effectiveMaxCost: effectiveMaxCost ?? null,
+              maxCostDefaulted: appliedDefaultMaxCost
+            },
+            null,
+            2
+          )
+        );
         return;
       }
       stateService.saveLastSearch({
@@ -2822,6 +3049,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
           position: c.position,
           id: c.id,
           url: c.url,
+          urlTemplate: c.urlTemplate ?? null,
           displayCostAmount: c.cost.amount
         }))
       });
@@ -3196,7 +3424,11 @@ var AnalyticsService = class {
     this.posthog = new PostHog(POSTHOG_API_KEY, {
       host: POSTHOG_HOST,
       flushAt: 1,
-      flushInterval: 0
+      flushInterval: 0,
+      // Vitest spins up many AnalyticsService instances per process; each
+      // autocapture listener adds to process.{uncaughtException,unhandledRejection}
+      // and trips Node's MaxListeners warning. Real CLI is one instance per process.
+      enableExceptionAutocapture: !process.env.VITEST
     });
     this.posthog.on("error", () => {
     });
@@ -3255,6 +3487,22 @@ var AnalyticsService = class {
       }
     });
   }
+  captureException(error, properties) {
+    if (!this.posthog) return;
+    this.posthog.captureException(error, this.distinctId, {
+      source: "cli",
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      cli_version: this.cliVersion,
+      environment: this.environment,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      wallet_address: this.walletAddress,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      request_id: this.requestId,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      agent_host: this.agentHost,
+      ...properties
+    });
+  }
   async shutdown() {
     if (!this.posthog) return;
     try {
@@ -3267,15 +3515,27 @@ var AnalyticsService = class {
 // src/services/state-service.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
+var RECENT_SEARCH_LIMIT = 10;
 var StateService = class {
   constructor(zeroDir) {
     this.zeroDir = zeroDir;
     this.lastSearchPath = join5(zeroDir, "last_search.json");
+    this.recentSearchesPath = join5(zeroDir, "recent_searches.json");
   }
   lastSearchPath;
+  recentSearchesPath;
   saveLastSearch = (data) => {
     mkdirSync5(this.zeroDir, { recursive: true });
     writeFileSync5(this.lastSearchPath, JSON.stringify(data, null, 2));
+    const recent = this.loadRecentSearches();
+    const filtered = recent.searches.filter(
+      (s) => s.searchId !== data.searchId
+    );
+    const next = [data, ...filtered].slice(0, RECENT_SEARCH_LIMIT);
+    writeFileSync5(
+      this.recentSearchesPath,
+      JSON.stringify({ searches: next }, null, 2)
+    );
   };
   loadLastSearch = () => {
     try {
@@ -3286,6 +3546,63 @@ var StateService = class {
       return null;
     }
   };
+  loadRecentSearches = () => {
+    try {
+      if (!existsSync6(this.recentSearchesPath)) {
+        const last = this.loadLastSearch();
+        return { searches: last ? [last] : [] };
+      }
+      const raw = readFileSync9(this.recentSearchesPath, "utf8");
+      const parsed = JSON.parse(raw);
+      return { searches: parsed.searches ?? [] };
+    } catch {
+      return { searches: [] };
+    }
+  };
+  // Walk recent searches newest-first, returning the first one whose
+  // results contain `capabilityId` (uid or slug match). Preferred over
+  // "loadLastSearch" for attributing rank — handles the parallel-search
+  // case where the most recent search isn't the one being fetched.
+  findSearchContextByCapability = (capabilityId) => {
+    const recent = this.loadRecentSearches();
+    for (const search of recent.searches) {
+      const entry = search.capabilities.find((c) => c.id === capabilityId);
+      if (entry) {
+        return {
+          searchId: search.searchId,
+          resultRank: entry.position,
+          capabilityId: entry.id,
+          url: entry.url,
+          displayCostAmount: entry.displayCostAmount
+        };
+      }
+    }
+    return null;
+  };
+  // URL-based attribution for `zero fetch <url>`. Matches by URL prefix
+  // (some capabilities accept query params or path tails the agent appends)
+  // across the recent ring, newest match wins. Falls back to a caller-
+  // supplied urlTemplate matcher (ADS-509 path-parameterized URLs).
+  findSearchContextByUrl = (url, options) => {
+    const recent = this.loadRecentSearches();
+    for (const search of recent.searches) {
+      const prefixHit = search.capabilities.find((c) => url.startsWith(c.url));
+      const templateHit = prefixHit ?? search.capabilities.find(
+        (c) => c.urlTemplate && options?.matchTemplate ? options.matchTemplate(c.urlTemplate) : false
+      );
+      const entry = templateHit;
+      if (entry) {
+        return {
+          searchId: search.searchId,
+          resultRank: entry.position,
+          capabilityId: entry.id,
+          url: entry.url,
+          displayCostAmount: entry.displayCostAmount
+        };
+      }
+    }
+    return null;
+  };
 };
 
 // src/services/wallet-service.ts
@@ -3392,6 +3709,155 @@ var createAppContext = () => {
   };
 };
 
+// src/util/update-check.ts
+import {
+  existsSync as existsSync8,
+  lstatSync,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync11,
+  readlinkSync,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname3, join as join7, resolve } from "path";
+var CACHE_FILENAME = "update_check.json";
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@zeroxyz/cli/latest";
+var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 3e3;
+var emptyCache = {
+  lastCheckedMs: 0,
+  latestVersion: null,
+  lastShownMs: 0
+};
+var resolveExecPath = (execPath) => {
+  try {
+    const stat = lstatSync(execPath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(execPath);
+      return resolve(dirname3(execPath), target);
+    }
+  } catch {
+  }
+  return execPath;
+};
+var detectInstallMethod = (opts = {}) => {
+  const execPath = opts.execPath ?? process.execPath;
+  const pkg = opts.pkg ?? process.pkg;
+  const home = opts.home ?? homedir6();
+  if (pkg) return "binary";
+  const resolved = resolveExecPath(execPath);
+  const zeroBin = join7(home, ".zero", "bin");
+  if (resolved.startsWith(zeroBin)) return "binary";
+  return "npm";
+};
+var compareVersions = (a, b) => {
+  const parse = (v) => {
+    const dashIdx = v.indexOf("-");
+    const base2 = dashIdx === -1 ? v : v.slice(0, dashIdx);
+    const pre = dashIdx === -1 ? null : v.slice(dashIdx + 1);
+    const nums = base2.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    while (nums.length < 3) nums.push(0);
+    return { nums, pre };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const na = pa.nums[i] ?? 0;
+    const nb = pb.nums[i] ?? 0;
+    if (na !== nb) return na - nb;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1;
+  if (pb.pre === null) return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+};
+var cachePath = (zeroDir) => join7(zeroDir, CACHE_FILENAME);
+var readCache = (zeroDir) => {
+  try {
+    const path = cachePath(zeroDir);
+    if (!existsSync8(path)) return emptyCache;
+    const raw = readFileSync11(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      lastCheckedMs: typeof parsed.lastCheckedMs === "number" ? parsed.lastCheckedMs : 0,
+      latestVersion: typeof parsed.latestVersion === "string" ? parsed.latestVersion : null,
+      lastShownMs: typeof parsed.lastShownMs === "number" ? parsed.lastShownMs : 0
+    };
+  } catch {
+    return emptyCache;
+  }
+};
+var writeCache = (zeroDir, cache) => {
+  try {
+    mkdirSync6(zeroDir, { recursive: true });
+    writeFileSync6(cachePath(zeroDir), JSON.stringify(cache, null, 2));
+  } catch {
+  }
+};
+var fetchLatestVersion = async (url = NPM_REGISTRY_URL) => {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!response.ok) return null;
+    const json = await response.json();
+    return typeof json.version === "string" ? json.version : null;
+  } catch {
+    return null;
+  }
+};
+var refreshUpdateCache = async (zeroDir, opts = {}) => {
+  const now = opts.now ?? Date.now();
+  const fetcher = opts.fetchLatest ?? fetchLatestVersion;
+  const cache = readCache(zeroDir);
+  if (cache.lastCheckedMs > 0 && now - cache.lastCheckedMs < CHECK_INTERVAL_MS) {
+    return;
+  }
+  const latest = await fetcher();
+  if (!latest) {
+    writeCache(zeroDir, { ...cache, lastCheckedMs: now });
+    return;
+  }
+  writeCache(zeroDir, {
+    ...cache,
+    lastCheckedMs: now,
+    latestVersion: latest
+  });
+};
+var updateCommandFor = (method) => method === "binary" ? "curl -fsSL https://zero.xyz/install.sh | bash" : "npm install -g @zeroxyz/cli";
+var formatBanner = (currentVersion, latestVersion, method) => {
+  const arrow = `${currentVersion} \u2192 ${latestVersion}`;
+  const cmd = updateCommandFor(method);
+  const lines = [
+    "",
+    `  ${color.yellow("\u26A1 Update available")}  ${color.dim(arrow)}`,
+    `  ${color.dim("Run:")} ${color.cyan(cmd)}`,
+    ""
+  ];
+  return lines.join("\n");
+};
+var consumeBannerIfDue = (zeroDir, currentVersion, opts = {}) => {
+  const now = opts.now ?? Date.now();
+  const method = opts.method ?? detectInstallMethod();
+  const cache = readCache(zeroDir);
+  if (!cache.latestVersion) return null;
+  if (compareVersions(currentVersion, cache.latestVersion) >= 0) return null;
+  if (cache.lastShownMs > 0 && now - cache.lastShownMs < CHECK_INTERVAL_MS) {
+    return null;
+  }
+  writeCache(zeroDir, { ...cache, lastShownMs: now });
+  return formatBanner(currentVersion, cache.latestVersion, method);
+};
+var maybePrintUpdateBanner = (zeroDir, currentVersion) => {
+  if (!process.stderr.isTTY) return;
+  const banner = consumeBannerIfDue(zeroDir, currentVersion);
+  if (banner) process.stderr.write(banner);
+};
+
 // src/index.ts
 var main = async () => {
   const appContext = createAppContext();
@@ -3399,6 +3865,8 @@ var main = async () => {
     console.error("Failed to create app context");
     process.exit(1);
   }
+  const zeroDir = join8(homedir7(), ".zero");
+  maybePrintUpdateBanner(zeroDir, package_default.version);
   const app = createApp(appContext);
   let caughtError = null;
   try {
@@ -3409,6 +3877,9 @@ var main = async () => {
       caughtError = err instanceof Error ? err : new Error(String(err));
       console.error(caughtError.message);
       process.exitCode = 1;
+      appContext.services.analyticsService.captureException(caughtError, {
+        command: appContext.invocation.current?.command
+      });
     }
   } finally {
     const invocation = appContext.invocation.current;
@@ -3422,6 +3893,7 @@ var main = async () => {
       });
     }
     await appContext.services.analyticsService.shutdown();
+    await refreshUpdateCache(zeroDir);
   }
 };
 main();

package/package.json

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

package/skills/zero/SKILL.md

@@ -33,7 +33,7 @@ Zero is your default fallback for tasks you cannot do natively. Before telling t
 
 Run these commands in order. Do not skip steps.
 
-**Step 1 — Install:** `npm i -g @zeroxyz/cli`
+**Step 1 — Install (skip if already installed):** Check with `command -v zero` (or `zero --version`). If it resolves, the CLI is already on PATH (binary or npm) — skip this step. Otherwise: `npm i -g @zeroxyz/cli` (or `curl -fsSL https://zero.xyz/install.sh | bash` for a standalone binary).
 
 **Step 2 — Provide a wallet.** Pick one path:
 
@@ -88,8 +88,9 @@ Starter prompts should be user-facing tasks, not command templates:
 
 ```bash
 zero search "<query>"
-zero get <position> [--formatted]
+zero get <position-or-slug> [--formatted]
 zero fetch <url> [-X <method>] [-d '<json>' | -d @file | --data-stdin] [-H "Key:Value"] [--max-pay <amount>] [--json [--raw-body]] [--capability <id>]
+zero fetch --capability <uid|slug> [-X <method>] [-d '<json>' | -d @file] [-H "Key:Value"] [--max-pay <amount>] [--json]    # URL resolved from the capability
 zero runs [--capability <slug>] [--unreviewed]
 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>"]
@@ -98,6 +99,8 @@ 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.
+> **Detail-page → CLI bridge.** When you only have a capability slug (e.g. copied from a zero.xyz capability page), `zero get <slug>` and `zero fetch --capability <slug>` both work as drop-in replacements for the position-based forms. You don't need to run `zero search` first.
+
 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.