@zeroxyz/cli 0.0.37 → 0.0.39

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { homedir as homedir7 } from "os";
-import { join as join8 } from "path";
+import { homedir as homedir8 } from "os";
+import { join as join9 } from "path";
 
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.37",
+  version: "0.0.39",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -61,12 +61,124 @@ var package_default = {
 };
 
 // src/app.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
+
+// src/commands/auth-command.ts
+import { homedir } from "os";
+import { join } from "path";
+import { Command } from "commander";
+import open from "open";
+
+// src/util/secure-config.ts
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+var SECURE_DIR_MODE = 448;
+var SECURE_FILE_MODE = 384;
+var ensureSecureDir = (path) => {
+  mkdirSync(path, { recursive: true, mode: SECURE_DIR_MODE });
+  chmodSync(path, SECURE_DIR_MODE);
+};
+var writeSecureFile = (path, contents) => {
+  writeFileSync(path, contents, { mode: SECURE_FILE_MODE });
+  chmodSync(path, SECURE_FILE_MODE);
+};
+var readConfig = (path) => {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+};
+
+// src/commands/auth-command.ts
+var getConfigPath = () => join(homedir(), ".zero", "config.json");
+var authLoginCommand = (appContext) => new Command("login").description("Sign in to Zero").option("--no-open", "Do not open the browser automatically").action(async (opts) => {
+  const { apiService } = appContext.services;
+  const start = await apiService.startDeviceLogin();
+  const url = `${start.verificationUri}?code=${start.userCode}`;
+  process.stdout.write(
+    `Open this URL to authorize:
+  ${url}
+User code: ${start.userCode}
+`
+  );
+  if (opts.open) {
+    await open(url).catch(() => {
+    });
+  }
+  while (Date.now() < start.expiresAt) {
+    await new Promise(
+      (r) => setTimeout(r, start.pollInterval * 1e3)
+    );
+    const result = await apiService.pollDeviceLogin(start.deviceCode);
+    if (result.status === "pending") {
+      process.stdout.write(".");
+      continue;
+    }
+    if (result.status === "expired") {
+      process.stderr.write(
+        "\nDevice code expired. Run `zero auth login` again.\n"
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const path = getConfigPath();
+    const current = readConfig(path);
+    const next = {
+      ...current,
+      session: {
+        userId: result.user.id,
+        authMethod: "workos",
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken
+      }
+    };
+    writeSecureFile(path, JSON.stringify(next, null, 2));
+    process.stdout.write(
+      `
+Signed in as ${result.user.email ?? result.user.id}
+`
+    );
+    return;
+  }
+  process.stderr.write(
+    "\nDevice code expired. Run `zero auth login` again.\n"
+  );
+  process.exitCode = 1;
+});
+var authLogoutCommand = (appContext) => new Command("logout").description("Sign out of Zero").action(async () => {
+  const { apiService } = appContext.services;
+  const path = getConfigPath();
+  const config = readConfig(path);
+  if (config.session) {
+    await apiService.logout(config.session.refreshToken);
+  }
+  const { session: _drop, ...rest } = config;
+  writeSecureFile(path, JSON.stringify(rest, null, 2));
+  process.stdout.write("Signed out.\n");
+});
+var authWhoamiCommand = (appContext) => new Command("whoami").description("Print the current Zero identity").action(async () => {
+  const { apiService } = appContext.services;
+  const me = await apiService.getMe();
+  process.stdout.write(
+    `${me.email ?? me.id}
+  uid: ${me.id}
+  authMethod: ${me.authMethod}
+`
+  );
+});
+var authCommand = (appContext) => {
+  const cmd = new Command("auth").description("Authentication commands");
+  cmd.addCommand(authLoginCommand(appContext));
+  cmd.addCommand(authLogoutCommand(appContext));
+  cmd.addCommand(authWhoamiCommand(appContext), { hidden: true });
+  return cmd;
+};
 
 // src/commands/bug-report-command.ts
 import { createHash as createHash2 } from "crypto";
-import { readFileSync } from "fs";
-import { Command } from "commander";
+import { readFileSync as readFileSync2 } from "fs";
+import { Command as Command2 } from "commander";
 import { z as z2 } from "zod";
 
 // src/services/api-service.ts
@@ -115,6 +227,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(),
@@ -224,18 +337,48 @@ var listRunsResponseSchema = z.object({
   runs: z.array(runListItemSchema),
   nextCursor: z.string().nullable()
 });
+var userDtoSchema = z.object({
+  id: z.string(),
+  email: z.string().nullable(),
+  authMethod: z.string(),
+  createdAt: z.union([z.string(), z.date()]).optional(),
+  lastLoginAt: z.union([z.string(), z.date()]).nullable().optional()
+});
+var deviceStartResultSchema = z.object({
+  deviceCode: z.string(),
+  userCode: z.string(),
+  verificationUri: z.string(),
+  pollInterval: z.number(),
+  expiresAt: z.number()
+});
+var devicePollResponseSchema = z.union([
+  z.object({ error: z.literal("authorization_pending") }),
+  z.object({ error: z.literal("expired_token") }),
+  z.object({
+    accessToken: z.string(),
+    refreshToken: z.string(),
+    expiresIn: z.number(),
+    user: userDtoSchema
+  })
+]);
 var buildCanonicalMessage = (method, path, body, timestamp, nonce) => {
   const bodyHash = createHash("sha256").update(body ?? "").digest("hex");
   return `${method}:${path}:${bodyHash}:${timestamp}:${nonce}`;
 };
-var ApiService = class {
-  constructor(baseUrl, account) {
+var ApiService = class _ApiService {
+  constructor(baseUrl, account, credentials = { kind: "none" }, onSessionRefreshed = async () => {
+  }) {
     this.baseUrl = baseUrl;
     this.account = account;
     this.walletAddress = this.account?.address ?? null;
+    this.credentials = credentials;
+    this.onSessionRefreshed = onSessionRefreshed;
   }
   walletAddress;
   account;
+  credentials;
+  onSessionRefreshed;
+  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();
@@ -249,21 +392,59 @@ var ApiService = class {
       "x-zero-signature": signature
     };
   };
-  request = async (method, path, body) => {
-    const url = `${this.baseUrl}${path}`;
-    const bodyStr = body ? JSON.stringify(body) : void 0;
-    const headers = {
+  // Session credentials take precedence over EIP-191. We never combine them
+  // in a single request: if the user has signed in, the JWT is the identity
+  // the API trusts, and the wallet signing path stays out of the picture.
+  buildHeaders = async (method, path, bodyStr) => {
+    const base2 = {
       "content-type": "application/json"
     };
+    if (this.credentials.kind === "session") {
+      base2.authorization = `Bearer ${this.credentials.accessToken}`;
+      return base2;
+    }
     if (this.account) {
       const walletHeaders = await this.signRequest(method, path, bodyStr);
-      Object.assign(headers, walletHeaders);
+      return { ...base2, ...walletHeaders };
     }
-    const response = await fetch(url, {
+    return base2;
+  };
+  // Rotates the in-memory tokens and fires onSessionRefreshed so the
+  // caller can persist them. Returns false on any refresh failure — the
+  // outer request then propagates the original 401 to the caller.
+  tryRefreshSession = async () => {
+    if (this.credentials.kind !== "session") return false;
+    const { refreshToken } = this.credentials;
+    const resp = await fetch(`${this.baseUrl}/v1/auth/refresh`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ refreshToken })
+    });
+    if (!resp.ok) return false;
+    const body = await resp.json();
+    this.credentials = {
+      ...this.credentials,
+      accessToken: body.accessToken,
+      refreshToken: body.refreshToken
+    };
+    await this.onSessionRefreshed(body);
+    return true;
+  };
+  request = async (method, path, body) => {
+    const url = `${this.baseUrl}${path}`;
+    const bodyStr = body ? JSON.stringify(body) : void 0;
+    const makeInit = async () => ({
       method,
-      headers,
+      headers: await this.buildHeaders(method, path, bodyStr),
       body: bodyStr
     });
+    let response = await fetch(url, await makeInit());
+    if (response.status === 401 && this.credentials.kind === "session") {
+      const refreshed = await this.tryRefreshSession();
+      if (refreshed) {
+        response = await fetch(url, await makeInit());
+      }
+    }
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({ error: "Unknown error" }));
       throw new Error(
@@ -272,6 +453,44 @@ var ApiService = class {
     }
     return response.json();
   };
+  startDeviceLogin = async () => {
+    const resp = await fetch(`${this.baseUrl}/v1/auth/device/start`, {
+      method: "POST"
+    });
+    if (!resp.ok) throw new Error(`device_start_${resp.status}`);
+    return deviceStartResultSchema.parse(await resp.json());
+  };
+  pollDeviceLogin = async (deviceCode) => {
+    const resp = await fetch(`${this.baseUrl}/v1/auth/device/poll`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceCode })
+    });
+    if (!resp.ok) throw new Error(`device_poll_${resp.status}`);
+    const parsed = devicePollResponseSchema.parse(await resp.json());
+    if ("error" in parsed) {
+      return parsed.error === "authorization_pending" ? { status: "pending" } : { status: "expired" };
+    }
+    return {
+      status: "ok",
+      accessToken: parsed.accessToken,
+      refreshToken: parsed.refreshToken,
+      expiresIn: parsed.expiresIn,
+      user: parsed.user
+    };
+  };
+  logout = async (refreshToken) => {
+    await fetch(`${this.baseUrl}/v1/auth/logout`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ refreshToken })
+    }).catch(() => {
+    });
+  };
+  getMe = async () => {
+    const json = await this.request("GET", "/v1/users/me");
+    return userDtoSchema.parse(json);
+  };
   search = async (options) => {
     const json = await this.request("POST", "/v1/search", options);
     return searchResponseSchema.parse(json);
@@ -349,7 +568,7 @@ var autoIdempotencyKey = (description, contextSeed) => {
   const seed = `${description}|${contextSeed ?? ""}|${bucket}`;
   return `auto-${createHash2("sha256").update(seed).digest("hex").slice(0, 16)}`;
 };
-var bugReportCommand = (appContext) => new Command("bug-report").description(
+var bugReportCommand = (appContext) => new Command2("bug-report").description(
   "Report a Zero platform bug \u2014 bad search ranking, wrong indexed URL, CLI bugs, billing issues. The CLI auto-attaches your most recent context (last search + last run), auto-derives a title, and lets the server classify the category. For 'this capability returned a bad result', use `zero review` instead."
 ).addHelpText(
   "after",
@@ -426,7 +645,7 @@ Categories the classifier picks from:
         return;
       }
       if (options.fromFile) {
-        const contents = readFileSync(options.fromFile, "utf8");
+        const contents = readFileSync2(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;
@@ -563,21 +782,21 @@ Bulk bug-report complete: ${ok} ok, ${failed} failed`
 );
 
 // src/commands/config-command.ts
-import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-import { Command as Command2 } from "commander";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Command as Command3 } from "commander";
 var VALID_KEYS = ["lowBalanceWarning", "auth", "telemetry"];
 var loadConfig = (configPath) => {
   try {
     if (!existsSync(configPath)) return {};
-    return JSON.parse(readFileSync2(configPath, "utf8"));
+    return JSON.parse(readFileSync3(configPath, "utf8"));
   } catch {
     return {};
   }
 };
-var configCommand = (_appContext) => new Command2("config").description("View or update CLI configuration").option("--set <keyValue>", "Set a config value (key=value)").action((options) => {
-  const configPath = join(homedir(), ".zero", "config.json");
+var configCommand = (_appContext) => new Command3("config").description("View or update CLI configuration").option("--set <keyValue>", "Set a config value (key=value)").action((options) => {
+  const configPath = join2(homedir2(), ".zero", "config.json");
   if (!options.set) {
     const config2 = loadConfig(configPath);
     console.log(JSON.stringify(config2, null, 2));
@@ -607,16 +826,16 @@ var configCommand = (_appContext) => new Command2("config").description("View or
   }
   const config = loadConfig(configPath);
   config[key] = value;
-  mkdirSync(join(homedir(), ".zero"), { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  mkdirSync2(join2(homedir2(), ".zero"), { recursive: true });
+  writeFileSync2(configPath, JSON.stringify(config, null, 2));
   console.log(`Set ${key} = ${JSON.stringify(value)}`);
 });
 
 // src/commands/fetch-command.ts
 import { createHash as createHash3 } from "crypto";
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { resolve as resolvePath } from "path";
-import { Command as Command3 } from "commander";
+import { Command as Command4 } from "commander";
 import { formatUnits as formatUnits2 } from "viem";
 
 // src/services/payment-service.ts
@@ -1120,8 +1339,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 +1351,7 @@ var PaymentService = class {
       address: token,
       abi: ERC20_BALANCE_ABI,
       functionName: "balanceOf",
-      args: [this.account.address]
+      args: [target]
     });
     return balance;
   };
@@ -1151,6 +1371,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 +1464,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 (spec === "@-") return readFileSync4(0);
+    return readFileSync4(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) {
-    body = readFileSync3(0);
+  let cap;
+  if (readStdin2) {
+    body = readFileSync4(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.`
       );
     }
   }
@@ -1300,7 +1566,7 @@ var detectPaymentRequirement = async (response) => {
   }
   return { protocol: "unknown", raw: {} };
 };
-var fetchCommand = (appContext) => new Command3("fetch").description(
+var fetchCommand = (appContext) => new Command4("fetch").description(
   "Fetch a capability URL, handling 402 challenges automatically"
 ).argument(
   "[url]",
@@ -1371,14 +1637,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 +1664,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 +1687,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 +1729,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 +1880,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 +1929,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 +1938,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 +1954,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 +1976,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;
@@ -1764,7 +2065,20 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
 );
 
 // src/commands/get-command.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } 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 +2095,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 +2104,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,10 +2215,16 @@ 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");
 };
-var getCommand = (appContext) => new Command4("get").description(
+var getCommand = (appContext) => new Command5("get").description(
   "Get details for a capability by position from last search, or by slug"
 ).argument(
   "<identifier>",
@@ -1955,7 +2273,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 } : {}
@@ -1973,15 +2299,15 @@ import {
   existsSync as existsSync2,
   mkdirSync as mkdirSync3,
   readdirSync,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   rmSync,
   statSync,
   writeFileSync as writeFileSync3
 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname, join as join2, relative } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname, join as join3, relative } from "path";
 import { fileURLToPath } from "url";
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 
 // src/util/install-banner.ts
@@ -2089,7 +2415,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?")}`,
@@ -2108,19 +2439,6 @@ var printReadyFooter = () => {
   return lines.join("\n");
 };
 
-// src/util/secure-config.ts
-import { chmodSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-var SECURE_DIR_MODE = 448;
-var SECURE_FILE_MODE = 384;
-var ensureSecureDir = (path) => {
-  mkdirSync2(path, { recursive: true, mode: SECURE_DIR_MODE });
-  chmodSync(path, SECURE_DIR_MODE);
-};
-var writeSecureFile = (path, contents) => {
-  writeFileSync2(path, contents, { mode: SECURE_FILE_MODE });
-  chmodSync(path, SECURE_FILE_MODE);
-};
-
 // src/commands/init-command.ts
 var AGENT_TOOLS = [
   { name: "Claude Code", detectDir: ".claude", skillsDir: ".claude/skills" },
@@ -2135,7 +2453,7 @@ var AGENT_TOOLS = [
 var findResourceDir = (startDir, resourceName) => {
   let current = startDir;
   while (true) {
-    const candidate = join2(current, resourceName);
+    const candidate = join3(current, resourceName);
     if (existsSync2(candidate)) {
       return candidate;
     }
@@ -2154,7 +2472,7 @@ var getCliModuleDir = () => {
   }
   return __dirname;
 };
-var sha256File = (filePath) => createHash4("sha256").update(readFileSync4(filePath)).digest("hex");
+var sha256File = (filePath) => createHash4("sha256").update(readFileSync5(filePath)).digest("hex");
 var verifyFileCopy = (src, dest) => {
   if (!existsSync2(dest)) return false;
   return sha256File(src) === sha256File(dest);
@@ -2162,7 +2480,7 @@ var verifyFileCopy = (src, dest) => {
 var collectAllFiles = (dir) => {
   const files = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = join2(dir, entry.name);
+    const fullPath = join3(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...collectAllFiles(fullPath));
     } else {
@@ -2172,7 +2490,7 @@ var collectAllFiles = (dir) => {
   return files;
 };
 var copyFile = (src, dest) => {
-  writeFileSync3(dest, readFileSync4(src));
+  writeFileSync3(dest, readFileSync5(src));
   try {
     chmodSync2(dest, statSync(src).mode);
   } catch {
@@ -2181,8 +2499,8 @@ var copyFile = (src, dest) => {
 var copyDirRecursive = (src, dest) => {
   mkdirSync3(dest, { recursive: true });
   for (const entry of readdirSync(src, { withFileTypes: true })) {
-    const srcPath = join2(src, entry.name);
-    const destPath = join2(dest, entry.name);
+    const srcPath = join3(src, entry.name);
+    const destPath = join3(dest, entry.name);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
@@ -2191,22 +2509,22 @@ var copyDirRecursive = (src, dest) => {
   }
 };
 var installHook = (home, verbose = false) => {
-  const claudeDir = join2(home, ".claude");
+  const claudeDir = join3(home, ".claude");
   if (!existsSync2(claudeDir)) {
     if (verbose) {
       stepInfo(`~/.claude not found \u2014 Claude Code not installed, skipping`);
     }
     return false;
   }
-  const zeroHooksDir = join2(home, ".zero", "hooks");
+  const zeroHooksDir = join3(home, ".zero", "hooks");
   mkdirSync3(zeroHooksDir, { recursive: true });
   if (verbose) stepInfo(`staged hook dir at ${zeroHooksDir}`);
   const hookFiles = ["auto-approve-zero.sh", "zero-context.sh"];
   const hookDests = {};
   const hooksSourceDir = findResourceDir(getCliModuleDir(), "hooks");
   for (const hookFile of hookFiles) {
-    const hookSource = join2(hooksSourceDir, hookFile);
-    const hookDest = join2(zeroHooksDir, hookFile);
+    const hookSource = join3(hooksSourceDir, hookFile);
+    const hookDest = join3(zeroHooksDir, hookFile);
     copyFile(hookSource, hookDest);
     chmodSync2(hookDest, 493);
     if (!verifyFileCopy(hookSource, hookDest)) {
@@ -2217,14 +2535,14 @@ var installHook = (home, verbose = false) => {
     hookDests[hookFile] = hookDest;
     if (verbose) stepInfo(`copied ${hookFile} \u2192 ${hookDest} (verified)`);
   }
-  const settingsPath = join2(claudeDir, "settings.json");
+  const settingsPath = join3(claudeDir, "settings.json");
   let settings = {};
   let settingsExisted = false;
   let settingsCorrupted = false;
   if (existsSync2(settingsPath)) {
     settingsExisted = true;
     try {
-      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync5(settingsPath, "utf-8"));
     } catch {
       settingsCorrupted = true;
     }
@@ -2322,7 +2640,7 @@ var CONFLICTING_SKILL_PATTERNS = ["zam"];
 var findConflictingSkills = (home) => {
   const found = [];
   for (const tool of AGENT_TOOLS) {
-    const toolSkillsPath = join2(home, tool.skillsDir);
+    const toolSkillsPath = join3(home, tool.skillsDir);
     if (!existsSync2(toolSkillsPath)) continue;
     const entries = readdirSync(toolSkillsPath, { withFileTypes: true });
     for (const entry of entries) {
@@ -2331,7 +2649,7 @@ var findConflictingSkills = (home) => {
       if (CONFLICTING_SKILL_PATTERNS.some((p) => lower.includes(p))) {
         found.push({
           tool: tool.name,
-          skillPath: join2(toolSkillsPath, entry.name),
+          skillPath: join3(toolSkillsPath, entry.name),
           skillName: entry.name
         });
       }
@@ -2359,7 +2677,7 @@ var installSkills = (home, verbose = false) => {
   const installed = [];
   const errors = [];
   for (const tool of AGENT_TOOLS) {
-    const toolDetectPath = join2(home, tool.detectDir);
+    const toolDetectPath = join3(home, tool.detectDir);
     if (!existsSync2(toolDetectPath)) {
       if (verbose) {
         stepInfo(
@@ -2374,16 +2692,16 @@ var installSkills = (home, verbose = false) => {
       );
     }
     try {
-      const toolSkillsPath = join2(home, tool.skillsDir);
+      const toolSkillsPath = join3(home, tool.skillsDir);
       mkdirSync3(toolSkillsPath, { recursive: true });
       for (const skillDir of skillDirs) {
-        const src = join2(skillsSourceDir, skillDir);
-        const dest = join2(toolSkillsPath, skillDir);
+        const src = join3(skillsSourceDir, skillDir);
+        const dest = join3(toolSkillsPath, skillDir);
         const existed = existsSync2(dest);
         copyDirRecursive(src, dest);
         for (const srcFile of collectAllFiles(src)) {
           const relPath = relative(src, srcFile);
-          const destFile = join2(dest, relPath);
+          const destFile = join3(dest, relPath);
           if (!verifyFileCopy(srcFile, destFile)) {
             throw new Error(
               `Integrity check failed: ${destFile} does not match source`
@@ -2414,15 +2732,15 @@ var runInit = async (appContext, options = {}) => {
   let currentStep = "wallet";
   try {
     printZeroBanner();
-    const home = homedir2();
-    const zeroDir = join2(home, ".zero");
-    const configPath = join2(zeroDir, "config.json");
+    const home = homedir3();
+    const zeroDir = join3(home, ".zero");
+    const configPath = join3(zeroDir, "config.json");
     let walletCreated = false;
     let walletAddress = null;
     const walletExists = (() => {
       if (!existsSync2(configPath)) return false;
       try {
-        const existing = JSON.parse(readFileSync4(configPath, "utf8"));
+        const existing = JSON.parse(readFileSync5(configPath, "utf8"));
         return !!existing.privateKey;
       } catch {
         return false;
@@ -2432,7 +2750,7 @@ var runInit = async (appContext, options = {}) => {
       const privateKey = generatePrivateKey();
       const account = privateKeyToAccount(privateKey);
       ensureSecureDir(zeroDir);
-      const existing = existsSync2(configPath) ? JSON.parse(readFileSync4(configPath, "utf8")) : {};
+      const existing = existsSync2(configPath) ? JSON.parse(readFileSync5(configPath, "utf8")) : {};
       writeSecureFile(
         configPath,
         JSON.stringify(
@@ -2455,7 +2773,7 @@ var runInit = async (appContext, options = {}) => {
       }
     } else {
       try {
-        const existing = JSON.parse(readFileSync4(configPath, "utf8"));
+        const existing = JSON.parse(readFileSync5(configPath, "utf8"));
         const account = privateKeyToAccount(existing.privateKey);
         walletAddress = account.address;
       } catch {
@@ -2476,7 +2794,7 @@ var runInit = async (appContext, options = {}) => {
     let hookInstalled = false;
     let hookError = null;
     for (const tool of AGENT_TOOLS) {
-      if (existsSync2(join2(home, tool.detectDir))) {
+      if (existsSync2(join3(home, tool.detectDir))) {
         agentsDetected.push(tool.name);
       }
     }
@@ -2552,12 +2870,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,
@@ -2585,14 +2904,14 @@ To remove them, run: ${color.cyan("zero init cleanup")}`
     throw err;
   }
 };
-var initCommand = (appContext) => new Command5("init").description("Initialize Zero CLI for usage").option("--force", "Overwrite existing configuration").option(
+var initCommand = (appContext) => new Command6("init").description("Initialize Zero CLI for usage").option("--force", "Overwrite existing configuration").option(
   "-v, --verbose",
   "Explain why each install step was taken or skipped"
 ).action(async (options) => {
   await runInit(appContext, options);
 }).addCommand(
-  new Command5("cleanup").description("Remove deprecated skills (zam) that conflict with Zero").action(() => {
-    const home = homedir2();
+  new Command6("cleanup").description("Remove deprecated skills (zam) that conflict with Zero").action(() => {
+    const home = homedir3();
     const removed = removeConflictingSkills(home);
     if (removed.length === 0) {
       console.error("No conflicting skills found. Nothing to remove.");
@@ -2611,8 +2930,8 @@ ${removedList}`);
 );
 
 // src/commands/review-command.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { Command as Command6 } from "commander";
+import { readFileSync as readFileSync6 } from "fs";
+import { Command as Command7 } from "commander";
 import { z as z3 } from "zod";
 var bulkEntrySchema2 = z3.object({
   runId: z3.string(),
@@ -2622,7 +2941,7 @@ var bulkEntrySchema2 = z3.object({
   reliability: z3.number().int().min(1).max(5),
   content: z3.string().optional()
 });
-var reviewCommand = (appContext) => new Command6("review").description("Submit a review for a capability run").addHelpText(
+var reviewCommand = (appContext) => new Command7("review").description("Submit a review for a capability run").addHelpText(
   "after",
   `
 Tips for a great review:
@@ -2653,7 +2972,7 @@ Examples:
     try {
       const { analyticsService, apiService } = appContext.services;
       if (options.fromFile) {
-        const contents = readFileSync5(options.fromFile, "utf8");
+        const contents = readFileSync6(options.fromFile, "utf8");
         const lines = contents.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
         const parsed = [];
         let parseFailures = 0;
@@ -2801,7 +3120,7 @@ Bulk review complete: ${ok} ok, ${failed} failed`);
 );
 
 // src/commands/runs-command.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 var USD_ASSETS = /* @__PURE__ */ new Set(["USD", "USDC"]);
 var formatCost2 = (cost) => {
   if (!cost) return "free";
@@ -2816,7 +3135,7 @@ var formatPayment = (payment) => {
   const mode = payment.mode ? ` (${payment.mode})` : "";
   return `${payment.protocol}${chain}${mode}`;
 };
-var runsCommand = (appContext) => new Command7("runs").description("List your recent capability runs").addHelpText(
+var runsCommand = (appContext) => new Command8("runs").description("List your recent capability runs").addHelpText(
   "after",
   `
 View your recent capability runs \u2014 status, latency, cost, and payment info.
@@ -2874,7 +3193,7 @@ Examples:
 );
 
 // src/commands/search-command.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 var DEFAULT_MAX_COST_USD = "30";
 var formatReviewCount2 = (count) => {
   if (count >= 1e3) return `${(count / 1e3).toFixed(1)}k`;
@@ -2901,16 +3220,17 @@ 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");
 };
-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(
+var searchCommand = (appContext) => new Command9("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("--protocol <protocol>", "Payment protocol (x402 or mpp)").option(
   "--status <status>",
-  "Filter by availability (healthy, degraded, down)"
+  "Filter by availability (healthy, unknown, down). Defaults to healthy when neither --status nor --all is set; pass --all to see everything."
 ).option("--all", "Disable default quality filtering").option(
   "--source <source>",
   "Only show results from this crawl source (e.g. mpp, bazaar)"
@@ -2937,14 +3257,20 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         effectiveMaxCost = DEFAULT_MAX_COST_USD;
         appliedDefaultMaxCost = true;
       }
-      const validStatuses = ["healthy", "degraded", "down"];
+      const validStatuses = ["healthy", "unknown", "degraded", "down"];
       if (options.status && !validStatuses.includes(options.status)) {
         console.error(
-          `Invalid status "${options.status}". Must be one of: healthy, degraded, down.`
+          `Invalid status "${options.status}". Must be one of: ${validStatuses.join(", ")}.`
         );
         process.exitCode = 1;
         return;
       }
+      let effectiveStatus = options.status;
+      let appliedDefaultStatus = false;
+      if (effectiveStatus === void 0 && !options.all) {
+        effectiveStatus = "healthy";
+        appliedDefaultStatus = true;
+      }
       const result = await apiService.search({
         query,
         offset: options.offset,
@@ -2952,7 +3278,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         freeOnly: options.free,
         maxCost: effectiveMaxCost,
         protocol: options.protocol,
-        availabilityStatus: options.status,
+        availabilityStatus: effectiveStatus,
         includeAll: options.all,
         source: options.source,
         excludeSource: options.excludeSource
@@ -2970,10 +3296,11 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         maxCost: effectiveMaxCost,
         maxCostDefaulted: appliedDefaultMaxCost,
         protocol: options.protocol,
-        availabilityStatus: options.status,
+        availabilityStatus: effectiveStatus,
+        availabilityStatusDefaulted: appliedDefaultStatus,
         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 +3322,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
@@ -3020,9 +3348,9 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
 );
 
 // src/commands/terms-command.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 var TERMS_URL = "https://zero.xyz/terms-of-service";
-var termsCommand = (_appContext) => new Command9("terms").description("View the ZeroClick Terms of Service").action(async () => {
+var termsCommand = (_appContext) => new Command10("terms").description("View the ZeroClick Terms of Service").action(async () => {
   console.log(
     `ZeroClick Agentic Capability Search \u2014 Terms of Service
 
@@ -3040,14 +3368,48 @@ Read the full terms at: ${TERMS_URL}
 });
 
 // src/commands/wallet-command.ts
-import { existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
-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 { existsSync as existsSync3, readFileSync as readFileSync7 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join4 } from "path";
+import { Command as Command11 } from "commander";
+import open2 from "open";
+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 Command11("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,16 +3423,76 @@ var walletBalanceCommand = (appContext) => new Command10("balance").description(
   }
   console.log(`${balance.amount} ${balance.asset}`);
 });
-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(
+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 Command11("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)"
 ).option(
   "--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,14 +3508,10 @@ ${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);
+        await open2(url);
         console.log("Opened funding page in your browser.");
         console.log(`If it didn't open, visit: ${url}`);
       } else {
@@ -3116,7 +3534,7 @@ ${address}`);
     }
   }
 );
-var walletAddressCommand = (appContext) => new Command10("address").description("Show wallet address").action(() => {
+var walletAddressCommand = (appContext) => new Command11("address").description("Show wallet address").action(() => {
   const { walletService } = appContext.services;
   const address = walletService.getAddress();
   if (!address) {
@@ -3126,7 +3544,7 @@ var walletAddressCommand = (appContext) => new Command10("address").description(
   }
   console.log(address);
 });
-var walletSetCommand = (appContext) => new Command10("set").description("Set wallet from an existing private key").argument("<privateKey>", "Hex-encoded private key (0x-prefixed)").option("--force", "Overwrite existing wallet without prompting").action(async (privateKey, options) => {
+var walletSetCommand = (appContext) => new Command11("set").description("Set wallet from an existing private key").argument("<privateKey>", "Hex-encoded private key (0x-prefixed)").option("--force", "Overwrite existing wallet without prompting").action(async (privateKey, options) => {
   const { analyticsService } = appContext.services;
   if (!privateKey.startsWith("0x")) {
     console.error("Private key must be 0x-prefixed hex string.");
@@ -3141,11 +3559,11 @@ var walletSetCommand = (appContext) => new Command10("set").description("Set wal
     process.exitCode = 1;
     return;
   }
-  const zeroDir = join3(homedir3(), ".zero");
-  const configPath = join3(zeroDir, "config.json");
+  const zeroDir = join4(homedir4(), ".zero");
+  const configPath = join4(zeroDir, "config.json");
   if (!options.force && existsSync3(configPath)) {
     try {
-      const existing2 = JSON.parse(readFileSync6(configPath, "utf8"));
+      const existing2 = JSON.parse(readFileSync7(configPath, "utf8"));
       if (existing2.privateKey) {
         console.error(
           "Wallet already configured. Use --force to overwrite."
@@ -3157,7 +3575,7 @@ var walletSetCommand = (appContext) => new Command10("set").description("Set wal
     }
   }
   ensureSecureDir(zeroDir);
-  const existing = existsSync3(configPath) ? JSON.parse(readFileSync6(configPath, "utf8")) : {};
+  const existing = existsSync3(configPath) ? JSON.parse(readFileSync7(configPath, "utf8")) : {};
   writeSecureFile(
     configPath,
     JSON.stringify(
@@ -3171,34 +3589,111 @@ 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 Command11("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");
+  const cmd = new Command11("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;
 };
 
 // src/commands/welcome-command.ts
-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";
-import open2 from "open";
+import { existsSync as existsSync4, readFileSync as readFileSync8 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
+import { Command as Command12 } from "commander";
+import open3 from "open";
 import { getAddress } from "viem";
 import { privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
 var readPrivateKey = () => {
-  const configPath = join4(homedir4(), ".zero", "config.json");
+  const configPath = join5(homedir5(), ".zero", "config.json");
   if (!existsSync4(configPath)) return null;
   try {
-    const config = JSON.parse(readFileSync7(configPath, "utf8"));
+    const config = JSON.parse(readFileSync8(configPath, "utf8"));
     if (typeof config.privateKey === "string") {
       return config.privateKey;
     }
@@ -3207,9 +3702,37 @@ var readPrivateKey = () => {
   }
   return null;
 };
-var welcomeCommand = (appContext) => new Command11("welcome").description("Claim your $5 welcome bonus.").action(async () => {
+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 Command12("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,37 +3743,52 @@ 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 open3(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;
   }
 });
 
 // src/app.ts
 var createApp = (appContext) => {
   const { analyticsService } = appContext.services;
-  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 program = new Command13().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());
@@ -3274,6 +3812,7 @@ var createApp = (appContext) => {
   program.addCommand(configCommand(appContext));
   program.addCommand(termsCommand(appContext));
   program.addCommand(welcomeCommand(appContext));
+  program.addCommand(authCommand(appContext), { hidden: true });
   return program;
 };
 
@@ -3297,14 +3836,14 @@ var getEnv = () => {
 
 // src/app/app-services.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
-import { homedir as homedir5 } from "os";
-import { join as join6 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { homedir as homedir6 } from "os";
+import { join as join7 } 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 readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname2 } from "path";
 import { PostHog } from "posthog-node";
 var POSTHOG_API_KEY = "phc_B2vLyNxAf2mnqvdPQajf4d4b2iXc35dep2ZrvebMJLuX";
@@ -3327,7 +3866,7 @@ var AnalyticsService = class {
     let persistedAnonId;
     try {
       if (existsSync5(opts.configPath)) {
-        const config = JSON.parse(readFileSync8(opts.configPath, "utf8"));
+        const config = JSON.parse(readFileSync9(opts.configPath, "utf8"));
         if (config.telemetry === false) {
           telemetryEnabled = false;
         }
@@ -3352,7 +3891,7 @@ var AnalyticsService = class {
       try {
         const dir = dirname2(opts.configPath);
         mkdirSync4(dir, { recursive: true });
-        const existing = existsSync5(opts.configPath) ? JSON.parse(readFileSync8(opts.configPath, "utf8")) : {};
+        const existing = existsSync5(opts.configPath) ? JSON.parse(readFileSync9(opts.configPath, "utf8")) : {};
         writeFileSync4(
           opts.configPath,
           JSON.stringify({ ...existing, anonId: newAnonId }, null, 2)
@@ -3392,7 +3931,7 @@ var AnalyticsService = class {
     if (anonId === walletAddress) return;
     let aliasedTo;
     try {
-      const config = JSON.parse(readFileSync8(configPath, "utf8"));
+      const config = JSON.parse(readFileSync9(configPath, "utf8"));
       if (typeof config.aliasedTo === "string") {
         aliasedTo = config.aliasedTo;
       }
@@ -3401,7 +3940,7 @@ var AnalyticsService = class {
     if (aliasedTo === walletAddress) return;
     this.posthog.alias({ distinctId: walletAddress, alias: anonId });
     try {
-      const config = existsSync5(configPath) ? JSON.parse(readFileSync8(configPath, "utf8")) : {};
+      const config = existsSync5(configPath) ? JSON.parse(readFileSync9(configPath, "utf8")) : {};
       writeFileSync4(
         configPath,
         JSON.stringify({ ...config, aliasedTo: walletAddress }, null, 2)
@@ -3414,12 +3953,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 +3986,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 +4003,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() {
@@ -3460,14 +4016,14 @@ 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";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "fs";
+import { join as join6 } 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");
+    this.lastSearchPath = join6(zeroDir, "last_search.json");
+    this.recentSearchesPath = join6(zeroDir, "recent_searches.json");
   }
   lastSearchPath;
   recentSearchesPath;
@@ -3487,7 +4043,7 @@ var StateService = class {
   loadLastSearch = () => {
     try {
       if (!existsSync6(this.lastSearchPath)) return null;
-      const raw = readFileSync9(this.lastSearchPath, "utf8");
+      const raw = readFileSync10(this.lastSearchPath, "utf8");
       return JSON.parse(raw);
     } catch {
       return null;
@@ -3499,7 +4055,7 @@ var StateService = class {
         const last = this.loadLastSearch();
         return { searches: last ? [last] : [] };
       }
-      const raw = readFileSync9(this.recentSearchesPath, "utf8");
+      const raw = readFileSync10(this.recentSearchesPath, "utf8");
       const parsed = JSON.parse(raw);
       return { searches: parsed.searches ?? [] };
     } catch {
@@ -3507,18 +4063,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 +4104,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
         };
@@ -3590,40 +4153,63 @@ var detectAgentHost = (env = process.env) => {
 
 // src/app/app-services.ts
 var CLI_VERSION = package_default.version;
-var getServices = (env) => {
-  let privateKey = env.ZERO_PRIVATE_KEY ? env.ZERO_PRIVATE_KEY : null;
-  const zeroDir = join6(homedir5(), ".zero");
-  const configPath = join6(zeroDir, "config.json");
-  if (!privateKey) {
-    try {
-      if (existsSync7(configPath)) {
-        const config = JSON.parse(readFileSync10(configPath, "utf8"));
-        if (typeof config.privateKey === "string") {
-          privateKey = config.privateKey;
-        }
-      }
-    } catch {
-    }
+var resolveCredentials = (env, config) => {
+  if (config.session) {
+    return {
+      credentials: {
+        kind: "session",
+        accessToken: config.session.accessToken,
+        refreshToken: config.session.refreshToken,
+        userId: config.session.userId
+      },
+      privateKey: null
+    };
   }
-  const account = privateKey ? privateKeyToAccount4(privateKey) : null;
-  let lowBalanceWarning = 1;
-  try {
-    if (existsSync7(configPath)) {
-      const config = JSON.parse(readFileSync10(configPath, "utf8"));
-      if (typeof config.lowBalanceWarning === "number") {
-        lowBalanceWarning = config.lowBalanceWarning;
-      }
-    }
-  } catch {
+  if (env.ZERO_PRIVATE_KEY) {
+    return {
+      credentials: { kind: "none" },
+      privateKey: env.ZERO_PRIVATE_KEY
+    };
+  }
+  if (config.privateKey) {
+    return {
+      credentials: { kind: "none" },
+      privateKey: config.privateKey
+    };
   }
-  const apiService = new ApiService(env.ZERO_API_URL, account);
+  return { credentials: { kind: "none" }, privateKey: null };
+};
+var buildOnSessionRefreshed = (configPath) => async (tokens) => {
+  const current = readConfig(configPath);
+  if (!current.session) return;
+  const next = {
+    ...current,
+    session: {
+      ...current.session,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken
+    }
+  };
+  writeSecureFile(configPath, JSON.stringify(next, null, 2));
+};
+var getServices = (env) => {
+  const zeroDir = join7(homedir6(), ".zero");
+  const configPath = join7(zeroDir, "config.json");
+  const config = existsSync7(configPath) ? readConfig(configPath) : {};
+  const { credentials, privateKey } = resolveCredentials(env, config);
+  const account = privateKey ? privateKeyToAccount4(privateKey) : null;
+  const lowBalanceWarning = typeof config.lowBalanceWarning === "number" ? config.lowBalanceWarning : 1;
+  const apiService = new ApiService(
+    env.ZERO_API_URL,
+    account,
+    credentials,
+    buildOnSessionRefreshed(configPath)
+  );
   const paymentService = new PaymentService(account, { lowBalanceWarning });
   const stateService = new StateService(zeroDir);
   const walletService = new WalletService(
     apiService.walletAddress,
-    {
-      lowBalanceWarning
-    },
+    { lowBalanceWarning },
     paymentService.getTotalBalance
   );
   const analyticsService = new AnalyticsService({
@@ -3665,8 +4251,8 @@ import {
   readlinkSync,
   writeFileSync as writeFileSync6
 } from "fs";
-import { homedir as homedir6 } from "os";
-import { dirname as dirname3, join as join7, resolve } from "path";
+import { homedir as homedir7 } from "os";
+import { dirname as dirname3, join as join8, 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;
@@ -3690,10 +4276,10 @@ var resolveExecPath = (execPath) => {
 var detectInstallMethod = (opts = {}) => {
   const execPath = opts.execPath ?? process.execPath;
   const pkg = opts.pkg ?? process.pkg;
-  const home = opts.home ?? homedir6();
+  const home = opts.home ?? homedir7();
   if (pkg) return "binary";
   const resolved = resolveExecPath(execPath);
-  const zeroBin = join7(home, ".zero", "bin");
+  const zeroBin = join8(home, ".zero", "bin");
   if (resolved.startsWith(zeroBin)) return "binary";
   return "npm";
 };
@@ -3718,7 +4304,7 @@ var compareVersions = (a, b) => {
   if (pb.pre === null) return -1;
   return pa.pre < pb.pre ? -1 : 1;
 };
-var cachePath = (zeroDir) => join7(zeroDir, CACHE_FILENAME);
+var cachePath = (zeroDir) => join8(zeroDir, CACHE_FILENAME);
 var readCache = (zeroDir) => {
   try {
     const path = cachePath(zeroDir);
@@ -3812,7 +4398,7 @@ var main = async () => {
     console.error("Failed to create app context");
     process.exit(1);
   }
-  const zeroDir = join8(homedir7(), ".zero");
+  const zeroDir = join9(homedir8(), ".zero");
   maybePrintUpdateBanner(zeroDir, package_default.version);
   const app = createApp(appContext);
   let caughtError = null;