@zeroxyz/cli 0.0.37 → 0.0.38

package/dist/index.js

@@ -7,7 +7,7 @@ import { join as join8 } from "path";
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.37",
+  version: "0.0.38",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -115,6 +115,7 @@ var capabilityResponseSchema = z.object({
   responseSchema: z.record(z.string(), z.unknown()).nullable(),
   example: z.object({ request: z.unknown(), response: z.unknown() }).nullable(),
   tags: z.array(z.string()).nullable(),
+  exampleAgentPrompt: z.string().nullable().optional(),
   displayCostAmount: z.string(),
   displayCostAsset: z.string(),
   reviewCount: z.number(),
@@ -228,7 +229,7 @@ var buildCanonicalMessage = (method, path, body, timestamp, nonce) => {
   const bodyHash = createHash("sha256").update(body ?? "").digest("hex");
   return `${method}:${path}:${bodyHash}:${timestamp}:${nonce}`;
 };
-var ApiService = class {
+var ApiService = class _ApiService {
   constructor(baseUrl, account) {
     this.baseUrl = baseUrl;
     this.account = account;
@@ -236,6 +237,7 @@ var ApiService = class {
   }
   walletAddress;
   account;
+  withAccount = (account) => new _ApiService(this.baseUrl, account);
   signRequest = async (method, path, body) => {
     if (!this.account) throw new Error("No private key configured");
     const timestamp = Math.floor(Date.now() / 1e3).toString();
@@ -1120,8 +1122,9 @@ var PaymentService = class {
         return { viemChain: tempoTestnetChain, token: PATHUSD_TEMPO };
     }
   };
-  getBalanceRaw = async (chain) => {
-    if (!this.account) return 0n;
+  getBalanceRaw = async (chain, address) => {
+    const target = address ?? this.account?.address;
+    if (!target) return 0n;
     const { viemChain, token } = this.resolveChainConfig(chain);
     const client = createPublicClient({
       chain: viemChain,
@@ -1131,7 +1134,7 @@ var PaymentService = class {
       address: token,
       abi: ERC20_BALANCE_ABI,
       functionName: "balanceOf",
-      args: [this.account.address]
+      args: [target]
     });
     return balance;
   };
@@ -1151,6 +1154,13 @@ var PaymentService = class {
     ]);
     return { amount: formatUnits(baseRaw + tempoRaw, 6), asset: "USDC" };
   };
+  getTotalBalanceForAddress = async (address) => {
+    const [baseRaw, tempoRaw] = await Promise.all([
+      this.getBalanceRaw("base", address),
+      this.getBalanceRaw("tempo", address)
+    ]);
+    return { amount: formatUnits(baseRaw + tempoRaw, 6), asset: "USDC" };
+  };
 };
 
 // src/util/infer-schema.ts
@@ -1237,30 +1247,69 @@ var isJsonContentType = (contentType) => {
   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) => {
+var MAX_INLINE_REQUEST_BODY_BYTES = 10 * 1024 * 1024;
+var MAX_FILE_REQUEST_BODY_BYTES = 500 * 1024 * 1024;
+var UPSTREAM_ERROR_FIELDS = [
+  "error",
+  "message",
+  "detail",
+  "reason",
+  "error_description"
+];
+var UPSTREAM_ERROR_MAX_LEN = 200;
+var clampUpstreamMessage = (value) => {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  return trimmed.length > UPSTREAM_ERROR_MAX_LEN ? `${trimmed.slice(0, UPSTREAM_ERROR_MAX_LEN)}\u2026` : trimmed;
+};
+var extractUpstreamErrorMessage = (body) => {
+  const parsed = tryParseJson(body);
+  if (parsed === null || typeof parsed !== "object") {
+    const clipped = clampUpstreamMessage(body);
+    return clipped || void 0;
+  }
+  const record = parsed;
+  for (const field of UPSTREAM_ERROR_FIELDS) {
+    const value = record[field];
+    if (typeof value === "string" && value.length > 0) {
+      return clampUpstreamMessage(value);
+    }
+    if (value && typeof value === "object") {
+      const nested = value.message;
+      if (typeof nested === "string" && nested.length > 0) {
+        return clampUpstreamMessage(nested);
+      }
+    }
+  }
+  return void 0;
+};
+var resolveRequestBody = (rawData, readStdin2) => {
   const fromFile = (spec) => {
     if (spec === "@-") return readFileSync3(0);
     return readFileSync3(resolvePath(spec.slice(1)));
   };
-  if (readStdin && rawData !== void 0) {
+  if (readStdin2 && rawData !== void 0) {
     throw new Error(
       "Conflicting body sources: use either --data-stdin or -d, not both."
     );
   }
   let body;
-  if (readStdin) {
+  let cap;
+  if (readStdin2) {
     body = readFileSync3(0);
+    cap = MAX_FILE_REQUEST_BODY_BYTES;
   } else if (rawData?.startsWith("@")) {
     body = fromFile(rawData);
+    cap = MAX_FILE_REQUEST_BODY_BYTES;
   } else {
     body = rawData;
+    cap = MAX_INLINE_REQUEST_BODY_BYTES;
   }
   if (body !== void 0) {
     const bytes = Buffer.isBuffer(body) ? body.length : Buffer.byteLength(body, "utf8");
-    if (bytes > MAX_REQUEST_BODY_BYTES) {
+    if (bytes > cap) {
       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.`
+        `Request body is ${bytes} bytes \u2014 exceeds the ${cap} byte local cap. This is a CLI-side guard, not a protocol limit. Compress the payload or contact us if you need it raised.`
       );
     }
   }
@@ -1371,14 +1420,16 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
             capName = cap.name;
           }
           const searchResult = await apiService.search({ query: capName });
-          const slugFoundInResults = searchResult.capabilities.some(
+          const matchedEntry = searchResult.capabilities.find(
             (c) => c.slug === options.capability || c.id === options.capability
           );
+          const slugFoundInResults = Boolean(matchedEntry);
           stateService.saveLastSearch({
             searchId: searchResult.searchId,
             capabilities: searchResult.capabilities.map((c) => ({
               position: c.position,
               id: c.id,
+              slug: c.slug,
               url: c.url,
               urlTemplate: c.urlTemplate ?? null,
               displayCostAmount: c.cost.amount
@@ -1396,7 +1447,13 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
             slugFoundInResults
           });
           analyticsService.capture("capability_viewed", {
+            // Existing field preserved as the raw --capability
+            // input for back-compat.
             capabilityId: options.capability,
+            // New canonical identifier fields hydrated from the
+            // resolved search result (when the slug was found).
+            capabilityUid: matchedEntry?.id,
+            capabilitySlug: matchedEntry?.slug,
             fromLastSearch: false,
             searchId: searchResult.searchId,
             triggeredBy: "slug_handoff"
@@ -1413,7 +1470,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       } catch (err) {
         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",
+          cliErrorClass: /exceeds the .* byte local cap/.test(message) ? "payload_too_large" : "schema_validation_failed",
           url: redactUrl(resolvedUrl),
           error: truncateError(message)
         });
@@ -1455,6 +1512,8 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       });
       const matchCtx = explicitCapabilityCtx ?? urlCtx;
       const capabilityId = options.capability ?? matchCtx?.capabilityId ?? null;
+      const capabilityUid = matchCtx?.capabilityUid ?? null;
+      const capabilitySlug = matchCtx?.capabilitySlug ?? null;
       const searchId = matchCtx?.searchId;
       const resultRank = matchCtx?.resultRank;
       const matchedDisplayCostAmount = matchCtx?.displayCostAmount;
@@ -1604,10 +1663,12 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       const isFailure = !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
       let errorSnippetHash;
       let errorSnippetLength;
+      let upstreamErrorMessage;
       if (isFailure && body && !bodyIsBinary) {
         const snippet = body.slice(0, 500);
         errorSnippetHash = createHash3("sha256").update(snippet).digest("hex");
         errorSnippetLength = snippet.length;
+        upstreamErrorMessage = extractUpstreamErrorMessage(body);
       }
       let runId = null;
       if (capabilityId && apiService.walletAddress) {
@@ -1651,7 +1712,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           );
         }
       }
-      const outcome = !finalResponse ? "network_error" : status === 402 && !paymentMeta ? "payment_failed" : status !== void 0 && status >= 400 && status !== 402 ? "server_error" : "success";
+      const outcome = !finalResponse ? "network_error" : status === 402 && !paymentMeta ? "payment_failed" : status === 402 && paymentMeta ? "payment_rejected" : status !== void 0 && status >= 400 && status !== 402 ? "server_error" : "success";
       analyticsService.capture("fetch_executed", {
         url: redactUrl(resolvedUrl),
         status,
@@ -1660,6 +1721,13 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         hasPayment: !!paymentMeta,
         paymentProtocol: paymentMeta?.protocol,
         paymentAmount: paymentMeta?.amount,
+        // Canonical join keys — capabilitySlug is the dashboard
+        // breakdown dimension; capabilityUid is the stable join
+        // key with the capabilities table. capabilityId is the
+        // back-compat alias (same value as capabilityUid when
+        // resolved, else the raw --capability input).
+        capabilityUid: capabilityUid ?? void 0,
+        capabilitySlug: capabilitySlug ?? void 0,
         capabilityId: capabilityId ?? void 0,
         searchId: searchId ?? void 0,
         resultRank: resultRank ?? void 0,
@@ -1669,15 +1737,21 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       });
       const isFetchFailure = Boolean(fetchError) || !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
       if (isFetchFailure) {
-        const cliErrorClass = fetchError || !finalResponse ? "network" : !apiService.walletAddress ? "auth_missing" : "unknown";
+        const cliErrorClass = fetchError || !finalResponse ? "network" : !apiService.walletAddress ? "auth_missing" : status === 402 && paymentMeta ? "payment_rejected" : typeof status === "number" && status >= 500 ? "upstream_5xx" : typeof status === "number" && status >= 400 ? "upstream_4xx" : "unknown";
         analyticsService.capture("fetch_error", {
           cliErrorClass,
+          capabilityUid: capabilityUid ?? void 0,
+          capabilitySlug: capabilitySlug ?? void 0,
           capabilityId: capabilityId ?? void 0,
           searchId: searchId ?? void 0,
           resultRank: resultRank ?? void 0,
           url: redactUrl(resolvedUrl),
+          status: typeof status === "number" ? status : void 0,
+          upstreamErrorMessage,
+          errorSnippetHash,
+          errorSnippetLength,
           error: truncateError(
-            fetchError?.message ?? skipReasons.join("; ")
+            fetchError?.message ?? upstreamErrorMessage ?? skipReasons.join("; ")
           ),
           skippedRun: !runId && skipReasons.length > 0
         });
@@ -1685,6 +1759,16 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       if (fetchError && !options.json) {
         console.error(`  Fetch failed: ${fetchError.message}`);
       }
+      if (finalResponse && !fetchError && !options.json && typeof status === "number" && (status < 200 || status >= 300)) {
+        const messageSuffix = upstreamErrorMessage ? ` \u2014 ${upstreamErrorMessage}` : "";
+        if (status === 402 && paymentMeta) {
+          console.error(
+            `  Upstream returned 402 after payment was sent \u2014 the seller's facilitator rejected the credential${messageSuffix}`
+          );
+        } else {
+          console.error(`  Upstream returned ${status}${messageSuffix}`);
+        }
+      }
       if (options.json) {
         const responseStatus = finalResponse?.status ?? null;
         const ok = responseStatus !== null && responseStatus >= 200 && responseStatus < 300;
@@ -1765,6 +1849,19 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
 
 // src/commands/get-command.ts
 import { Command as Command4 } from "commander";
+
+// src/util/format-price.ts
+var centsToDollars = (cents) => {
+  const value = Number.parseFloat(cents) / 100;
+  if (!Number.isFinite(value) || value === 0) return "0.00";
+  if (value < 1e-4) return value.toFixed(6);
+  if (value < 1e-3) return value.toFixed(5);
+  if (value < 0.01) return value.toFixed(4);
+  if (value < 1) return value.toFixed(3);
+  return value.toFixed(2);
+};
+
+// src/commands/get-command.ts
 var formatRelativeTimestamp = (iso) => {
   if (!iso) return "never";
   const then = new Date(iso).getTime();
@@ -1781,12 +1878,6 @@ var formatRelativeTimestamp = (iso) => {
   if (diffMo < 12) return `${diffMo}mo ago`;
   return `${Math.round(diffMo / 12)}y ago`;
 };
-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;
@@ -1796,6 +1887,10 @@ var formatCost = (capability) => {
     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 if (capability.displayCostAmount === "0") {
+    lines.push(`  Cost: Free`);
+  } else if (capability.displayCostAmount === "unknown") {
+    lines.push(`  Cost: variable pricing`);
   } else {
     lines.push(`  Cost: $${capability.displayCostAmount}/call`);
   }
@@ -1903,6 +1998,12 @@ var formatCapability = (capability) => {
   lines.push(
     `  Last successful run: ${formatRelativeTimestamp(capability.lastSuccessfullyRanAt)}`
   );
+  if (capability.exampleAgentPrompt?.trim()) {
+    lines.push("  Example prompt:");
+    for (const promptLine of capability.exampleAgentPrompt.split("\n")) {
+      lines.push(`    ${promptLine}`);
+    }
+  }
   lines.push(...buildTryItExample(capability));
   return lines.join("\n");
 };
@@ -1955,7 +2056,15 @@ var getCommand = (appContext) => new Command4("get").description(
       console.log(JSON.stringify(capability, null, 2));
     }
     analyticsService.capture("capability_viewed", {
+      // Existing field — raw user input (uid, slug, or position
+      // resolved to uid via the last-search cache). Preserved
+      // for back-compat with existing dashboards.
       capabilityId,
+      // New canonical identifier fields read off the API response,
+      // so they are always populated regardless of how the user
+      // referenced the capability.
+      capabilityUid: capability.uid,
+      capabilitySlug: capability.slug,
       fromLastSearch: isPosition,
       ...isPosition ? { position } : {},
       ...searchId ? { searchId } : {}
@@ -2089,7 +2198,12 @@ var printReadyFooter = () => {
   const lines = [
     "",
     `  ${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`,
+    "",
+    "  First, claim your $5 welcome bonus \u2014 run this now, before opening your agent:",
+    "",
+    `    ${color.cyan("zero welcome")}`,
+    "",
+    `  Then open ${color.boldRed("Claude Code")}, Codex, Cursor, Blackbox, or your agent of choice`,
     "  and try this prompt to get started:",
     "",
     `    ${color.cyan("What is zero and how do I use it?")}`,
@@ -2552,12 +2666,13 @@ To remove them, run: ${color.cyan("zero init cleanup")}`
     sectionDivider();
     console.error(printReadyFooter());
     currentStep = "complete";
+    if (walletAddress) {
+      appContext.services.analyticsService.setWalletAddress(walletAddress);
+    }
     appContext.services.analyticsService.capture("wallet_initialized", {
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
       wallet_created: walletCreated,
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-      wallet_address: walletAddress,
-      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
       agents_detected: agentsDetected,
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
       agents_detected_count: agentsDetected.length,
@@ -2901,7 +3016,8 @@ var formatSearchResults = (results) => {
     const displayDescription = r.whatItDoes ?? r.description;
     const ratingBadge = formatRatingBadge(r.rating);
     const statusBadge = formatStatusBadge(r.displayStatus);
-    return `  ${r.position}. ${displayName} \u2014 $${r.cost.amount}/call \u2014 ${ratingBadge}${statusBadge}
+    const costLabel = r.cost.amount === "0" ? "Free" : r.cost.amount === "unknown" ? "variable pricing" : `$${r.cost.amount}/call`;
+    return `  ${r.position}. ${displayName} \u2014 ${costLabel} \u2014 ${ratingBadge}${statusBadge}
      "${displayDescription}"`;
   }).join("\n");
 };
@@ -2972,8 +3088,8 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         protocol: options.protocol,
         availabilityStatus: options.status,
         includeAll: options.all ?? false,
-        source: options.source,
-        excludeSource: options.excludeSource,
+        listingSource: options.source,
+        excludeListingSource: options.excludeSource,
         json: options.json ?? false
       });
       if (options.json) {
@@ -2995,6 +3111,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         capabilities: result.capabilities.map((c) => ({
           position: c.position,
           id: c.id,
+          slug: c.slug,
           url: c.url,
           urlTemplate: c.urlTemplate ?? null,
           displayCostAmount: c.cost.amount
@@ -3045,9 +3162,43 @@ import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
 import { Command as Command10 } from "commander";
 import open from "open";
-import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
-var walletBalanceCommand = (appContext) => new Command10("balance").description("Show wallet balance").action(async () => {
-  const { walletService } = appContext.services;
+import { isAddress } from "viem";
+import { generatePrivateKey as generatePrivateKey2, privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
+
+// src/util/stdin.ts
+var readStdin = async () => {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+// src/commands/wallet-command.ts
+var PRIVATE_KEY_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+var parseProvider = (raw) => raw === "stripe" ? "stripe" : "coinbase";
+var walletBalanceCommand = (appContext) => new Command10("balance").description("Show wallet balance").option(
+  "--address <address>",
+  "Check balance for an arbitrary address (no key needed). Useful with `zero wallet generate` \u2014 verify funds arrived without setting the wallet as your default."
+).action(async (options) => {
+  const { walletService, paymentService } = appContext.services;
+  if (options.address) {
+    if (!isAddress(options.address)) {
+      console.error("Invalid address (expected 0x + 40 hex chars).");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const balance2 = await paymentService.getTotalBalanceForAddress(
+        options.address
+      );
+      console.log(`${balance2.amount} ${balance2.asset}`);
+    } catch {
+      console.error("Failed to fetch balance");
+      process.exitCode = 1;
+    }
+    return;
+  }
   const balance = await walletService.getBalance();
   if (balance === null) {
     console.error("No wallet configured. Run `zero init` first.");
@@ -3061,6 +3212,20 @@ var walletBalanceCommand = (appContext) => new Command10("balance").description(
   }
   console.log(`${balance.amount} ${balance.asset}`);
 });
+var readPrivateKeyFromStdin = async () => {
+  if (process.stdin.isTTY) {
+    console.error(
+      "Expected a private key on stdin. Example:\n  zero wallet generate --json | jq -r .privateKey | zero wallet fund --key-stdin"
+    );
+    return null;
+  }
+  const raw = (await readStdin()).trim();
+  if (!PRIVATE_KEY_PATTERN.test(raw)) {
+    console.error("Invalid private key on stdin (expected 0x + 64 hex chars).");
+    return null;
+  }
+  return raw;
+};
 var walletFundCommand = (appContext) => new Command10("fund").description("Fund your wallet").argument("[amount]", "Amount to fund in USDC").option("--manual", "Show wallet address for manual transfer").option(
   "--no-open",
   "Print the funding URL instead of opening a browser (for agents \u2014 funding links are one-time use, hand the URL to the user)"
@@ -3068,9 +3233,55 @@ var walletFundCommand = (appContext) => new Command10("fund").description("Fund
   "--use <provider>",
   "Onramp provider: coinbase or stripe",
   "coinbase"
+).option(
+  "--key-stdin",
+  "Read a private key from stdin and mint a funding URL for that wallet instead of your configured one. Useful with `zero wallet generate`. Does not modify your config."
 ).action(
   async (amount, options) => {
-    const { analyticsService, walletService } = appContext.services;
+    const { analyticsService, apiService, walletService } = appContext.services;
+    const provider = parseProvider(options.use);
+    if (options.keyStdin) {
+      const key = await readPrivateKeyFromStdin();
+      if (!key) {
+        process.exitCode = 1;
+        return;
+      }
+      const altAccount = privateKeyToAccount2(key);
+      const altApi = apiService.withAccount(altAccount);
+      if (options.manual) {
+        console.log(`Send USDC (Base) to:
+${altAccount.address}`);
+        analyticsService.capture("wallet_funded", {
+          method: "manual",
+          amount,
+          // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+          alt_wallet: true
+        });
+        return;
+      }
+      const url2 = await altApi.getFundingUrl(amount, provider);
+      if (!url2) {
+        console.log(`Send USDC (Base) to:
+${altAccount.address}`);
+        console.error(
+          "Could not get funding URL. Send USDC (Base) manually."
+        );
+        process.exitCode = 1;
+        return;
+      }
+      console.log(
+        "Funding URL (one-time use \u2014 open it in a browser to fund):"
+      );
+      console.log(url2);
+      console.log(`Wallet address: ${altAccount.address}`);
+      analyticsService.capture("wallet_funded", {
+        method: "url",
+        amount,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        alt_wallet: true
+      });
+      return;
+    }
     const address = walletService.getAddress();
     if (!address) {
       console.error("No wallet configured. Run `zero init` first.");
@@ -3086,11 +3297,7 @@ ${address}`);
       });
       return;
     }
-    const provider = options.use === "stripe" ? "stripe" : "coinbase";
-    const url = await appContext.services.apiService.getFundingUrl(
-      amount,
-      provider
-    );
+    const url = await apiService.getFundingUrl(amount, provider);
     if (url) {
       if (options.open) {
         await open(url);
@@ -3171,18 +3378,95 @@ var walletSetCommand = (appContext) => new Command10("set").description("Set wal
     )
   );
   console.log(`Wallet set: ${account.address}`);
+  analyticsService.setWalletAddress(account.address);
   analyticsService.capture("wallet_set", {
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    wallet_address: account.address,
     force: options.force ?? false
   });
 });
+var walletGenerateCommand = (appContext) => new Command10("generate").description(
+  "Generate a fresh wallet (address + private key) without touching your configured wallet"
+).option("--json", "Emit { address, privateKey } as JSON").option(
+  "--fund",
+  "Also mint a one-time onramp URL for the new wallet (does not auto-open)"
+).option("--amount <amount>", "With --fund: USDC amount to pre-fill").option(
+  "--use <provider>",
+  "With --fund: onramp provider (coinbase | stripe)",
+  "coinbase"
+).action(
+  async (options) => {
+    const { analyticsService, apiService } = appContext.services;
+    const privateKey = generatePrivateKey2();
+    const account = privateKeyToAccount2(privateKey);
+    let fundingUrl = null;
+    if (options.fund) {
+      const provider = parseProvider(options.use);
+      fundingUrl = await apiService.withAccount(account).getFundingUrl(options.amount, provider);
+    }
+    if (options.json) {
+      const payload = {
+        address: account.address,
+        privateKey
+      };
+      if (options.fund) {
+        payload.fundingUrl = fundingUrl;
+      }
+      console.log(JSON.stringify(payload));
+    } else {
+      console.log("");
+      console.log(
+        "New wallet generated. Save these \u2014 they are NOT stored anywhere."
+      );
+      console.log("");
+      console.log(
+        "  WARNING: Anyone with this private key can spend any funds sent"
+      );
+      console.log(
+        "  to the address. Don't paste it into chat, commit it to git, or"
+      );
+      console.log("  share your screen with it visible.");
+      console.log("");
+      console.log(`  Address:     ${account.address}`);
+      console.log(`  Private key: ${privateKey}`);
+      console.log("");
+      if (options.fund) {
+        if (fundingUrl) {
+          console.log("Funding URL (one-time use):");
+          console.log(`  ${fundingUrl}`);
+          console.log("");
+        } else {
+          console.log(
+            "Could not mint a funding URL \u2014 fund the address manually with USDC (Base)."
+          );
+          console.log("");
+        }
+      }
+      console.log("Next steps:");
+      if (!options.fund) {
+        console.log("  - Fund the address with USDC (Base) before use.");
+      }
+      console.log(
+        `  - Use it for a single command: ZERO_PRIVATE_KEY=${privateKey} zero <command>`
+      );
+      console.log(
+        "  - Or make it your default wallet: zero wallet set <privateKey> --force"
+      );
+      console.log("");
+    }
+    analyticsService.capture("wallet_generated", {
+      format: options.json ? "json" : "text",
+      funded: options.fund ?? false,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      funding_url_minted: options.fund ? fundingUrl !== null : false
+    });
+  }
+);
 var walletCommand = (appContext) => {
   const cmd = new Command10("wallet").description("Manage your wallet");
   cmd.addCommand(walletBalanceCommand(appContext));
   cmd.addCommand(walletFundCommand(appContext));
   cmd.addCommand(walletAddressCommand(appContext));
   cmd.addCommand(walletSetCommand(appContext));
+  cmd.addCommand(walletGenerateCommand(appContext));
   return cmd;
 };
 
@@ -3207,9 +3491,37 @@ var readPrivateKey = () => {
   }
   return null;
 };
+var linuxInstallHint = () => {
+  return [
+    "    On Debian/Ubuntu: sudo apt install xdg-utils",
+    "    On RHEL/Fedora:   sudo dnf install xdg-utils"
+  ].join("\n");
+};
+var printManualFallback = (url) => {
+  const lines = [
+    "",
+    "\u26A0\uFE0F  Couldn't auto-open your browser (this is common on WSL, SSH, or",
+    "    containers \u2014 no xdg-open installed).",
+    "",
+    "Copy and paste this URL into your browser to claim:",
+    "",
+    `    ${url}`,
+    ""
+  ];
+  if (process.platform === "linux") {
+    lines.push(
+      "Tip: install xdg-utils so 'zero welcome' can open the browser for you:",
+      linuxInstallHint(),
+      ""
+    );
+  }
+  console.log(lines.join("\n"));
+};
 var welcomeCommand = (appContext) => new Command11("welcome").description("Claim your $5 welcome bonus.").action(async () => {
   const { analyticsService } = appContext.services;
   analyticsService.capture("welcome_started", {});
+  let walletAddress;
+  let url;
   try {
     let privateKey = readPrivateKey();
     if (!privateKey) {
@@ -3220,30 +3532,45 @@ var welcomeCommand = (appContext) => new Command11("welcome").description("Claim
       }
     }
     const account = privateKeyToAccount3(privateKey);
-    const walletAddress = getAddress(account.address);
+    walletAddress = getAddress(account.address);
     const walletSignature = await account.signMessage({
       message: walletAddress
     });
-    const url = new URL("/welcome", appContext.env.ZERO_WEB_URL);
+    url = new URL("/welcome", appContext.env.ZERO_WEB_URL);
     url.searchParams.set("wallet", walletAddress);
     url.searchParams.set("walletSignature", walletSignature);
+  } catch (err) {
+    analyticsService.capture("welcome_failed", {
+      error: truncateError(
+        err instanceof Error ? err.message : String(err)
+      )
+    });
+    throw err;
+  }
+  const urlString = url.toString();
+  analyticsService.setWalletAddress(walletAddress);
+  try {
+    await open2(urlString);
     console.log(
-      `Opening ${url.toString()}
+      `Opening ${urlString}
 
 If your browser didn't open, paste the URL above.`
     );
-    await open2(url.toString());
     analyticsService.capture("welcome_link_opened", {
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-      wallet_address: walletAddress
+      open_method: "auto"
     });
   } catch (err) {
-    analyticsService.capture("welcome_failed", {
-      error: truncateError(
+    printManualFallback(urlString);
+    analyticsService.capture("welcome_link_opened", {
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      open_method: "manual_copy",
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      open_error: truncateError(
         err instanceof Error ? err.message : String(err)
-      )
+      ),
+      platform: process.platform
     });
-    throw err;
   }
 });
 
@@ -3414,12 +3741,30 @@ var AnalyticsService = class {
   setAgentHost(next) {
     this.agentHost = next;
   }
+  // Per-invocation override for the `wallet_address` super-prop. Used by
+  // commands that mint or load a wallet mid-process (init, wallet set,
+  // welcome) so subsequent captures carry the now-known address without
+  // needing to pass it as a per-event prop (which would collide with the
+  // super-prop — see ZERO-43). distinctId is intentionally NOT changed:
+  // the anon→wallet identity merge happens on the next CLI invocation
+  // via PostHog alias, when AnalyticsService is constructed with both
+  // the persisted anonId and the new walletAddress.
+  setWalletAddress(walletAddress) {
+    this.walletAddress = walletAddress;
+  }
   capture(event, properties) {
     if (!this.posthog) return;
     this.posthog.capture({
       distinctId: this.distinctId,
       event,
+      // Super-props are spread LAST so they always win against a same-
+      // named per-event prop (see ZERO-43: a `source: undefined` on
+      // `search_executed` was silently clobbering the `cli` surface stamp).
+      // The reserved super-prop names are enforced by the events registry
+      // test in `analytics/__tests__/events.test.ts` — any new event prop
+      // that collides will fail CI.
       properties: {
+        ...properties,
         source: "cli",
         // biome-ignore lint/style/useNamingConvention: snake_case is standard for analytics event properties
         cli_version: this.cliVersion,
@@ -3429,14 +3774,14 @@ var AnalyticsService = class {
         // 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
+        agent_host: this.agentHost
       }
     });
   }
   captureException(error, properties) {
     if (!this.posthog) return;
     this.posthog.captureException(error, this.distinctId, {
+      ...properties,
       source: "cli",
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
       cli_version: this.cliVersion,
@@ -3446,8 +3791,7 @@ var AnalyticsService = class {
       // 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
+      agent_host: this.agentHost
     });
   }
   async shutdown() {
@@ -3507,18 +3851,23 @@ var StateService = class {
     }
   };
   // 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) => {
+  // results contain `capabilityRef` (matches against uid OR slug).
+  // Preferred over "loadLastSearch" for attributing rank — handles the
+  // parallel-search case where the most recent search isn't the one being
+  // fetched.
+  findSearchContextByCapability = (capabilityRef) => {
     const recent = this.loadRecentSearches();
     for (const search of recent.searches) {
-      const entry = search.capabilities.find((c) => c.id === capabilityId);
+      const entry = search.capabilities.find(
+        (c) => c.id === capabilityRef || c.slug === capabilityRef
+      );
       if (entry) {
         return {
           searchId: search.searchId,
           resultRank: entry.position,
           capabilityId: entry.id,
+          capabilityUid: entry.id,
+          capabilitySlug: entry.slug ?? null,
           url: entry.url,
           displayCostAmount: entry.displayCostAmount
         };
@@ -3543,6 +3892,8 @@ var StateService = class {
           searchId: search.searchId,
           resultRank: entry.position,
           capabilityId: entry.id,
+          capabilityUid: entry.id,
+          capabilitySlug: entry.slug ?? null,
           url: entry.url,
           displayCostAmount: entry.displayCostAmount
         };

package/package.json

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