@drip-apex/apex-cli 0.15.3 → 0.15.4

package/dist/cli.js

@@ -6564,11 +6564,11 @@ var init_is_wsl = __esm({
 });
 
 // node_modules/wsl-utils/index.js
-var import_node_process9, import_promises2, wslDrivesMountPoint, powerShellPathFromWsl, powerShellPath;
+var import_node_process9, import_promises, wslDrivesMountPoint, powerShellPathFromWsl, powerShellPath;
 var init_wsl_utils = __esm({
   "node_modules/wsl-utils/index.js"() {
     import_node_process9 = __toESM(require("node:process"), 1);
-    import_promises2 = __toESM(require("node:fs/promises"), 1);
+    import_promises = __toESM(require("node:fs/promises"), 1);
     init_is_wsl();
     init_is_wsl();
     wslDrivesMountPoint = /* @__PURE__ */ (() => {
@@ -6581,14 +6581,14 @@ var init_wsl_utils = __esm({
         const configFilePath = "/etc/wsl.conf";
         let isConfigFileExists = false;
         try {
-          await import_promises2.default.access(configFilePath, import_promises2.constants.F_OK);
+          await import_promises.default.access(configFilePath, import_promises.constants.F_OK);
           isConfigFileExists = true;
         } catch {
         }
         if (!isConfigFileExists) {
           return defaultMountPoint;
         }
-        const configContent = await import_promises2.default.readFile(configFilePath, { encoding: "utf8" });
+        const configContent = await import_promises.default.readFile(configFilePath, { encoding: "utf8" });
         const configMountPoint = /(?<!#.*)root\s*=\s*(?<mountPoint>.*)/g.exec(configContent);
         if (!configMountPoint) {
           return defaultMountPoint;
@@ -6823,7 +6823,7 @@ function detectPlatformBinary({ [platform]: platformBinary }, { wsl }) {
   }
   return detectArchBinary(platformBinary);
 }
-var import_node_process13, import_node_buffer, import_node_path4, import_node_url, import_node_util5, import_node_child_process5, import_promises3, import_meta, execFile5, __dirname2, localXdgOpenPath, platform, arch, pTryEach, baseOpen, open, openApp, apps, open_default;
+var import_node_process13, import_node_buffer, import_node_path4, import_node_url, import_node_util5, import_node_child_process5, import_promises2, import_meta, execFile5, __dirname2, localXdgOpenPath, platform, arch, pTryEach, baseOpen, open, openApp, apps, open_default;
 var init_open = __esm({
   "node_modules/open/index.js"() {
     import_node_process13 = __toESM(require("node:process"), 1);
@@ -6832,7 +6832,7 @@ var init_open = __esm({
     import_node_url = require("node:url");
     import_node_util5 = require("node:util");
     import_node_child_process5 = __toESM(require("node:child_process"), 1);
-    import_promises3 = __toESM(require("node:fs/promises"), 1);
+    import_promises2 = __toESM(require("node:fs/promises"), 1);
     init_wsl_utils();
     init_define_lazy_prop();
     init_default_browser();
@@ -6965,7 +6965,7 @@ var init_open = __esm({
           const isBundled = !__dirname2 || __dirname2 === "/";
           let exeLocalXdgOpen = false;
           try {
-            await import_promises3.default.access(localXdgOpenPath, import_promises3.constants.X_OK);
+            await import_promises2.default.access(localXdgOpenPath, import_promises2.constants.X_OK);
             exeLocalXdgOpen = true;
           } catch {
           }
@@ -7085,6 +7085,9 @@ var {
   Help
 } = import_index.default;
 
+// src/telemetry.ts
+var import_node_crypto2 = require("node:crypto");
+
 // ../api-client/src/client-identity.ts
 var import_node_crypto = require("node:crypto");
 var invocationId = (0, import_node_crypto.randomUUID)();
@@ -7137,18 +7140,25 @@ function createHttpClient(creds, options) {
     warnedAboutVersionSkew = true;
     warn3(version > 1 ? "CLI is behind the server \u2014 update.\n" : "Server API is older than this CLI supports.\n");
   }
-  async function request2(method, path26, body5, requestTimeoutMs, form = false) {
+  async function request2(method, path26, body5, requestTimeoutMs, form = false, requestOptions) {
     const started2 = performance.now();
-    const observe = (status4, requestId2, errorCode) => {
+    const observe = (status4, requestId2, errorCode, responseHeaders) => {
+      const semver = (name) => {
+        const value = responseHeaders?.get(name) ?? void 0;
+        return value && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value) ? value : void 0;
+      };
+      const serverTiming = responseHeaders?.get("server-timing");
       try {
-        options.onResponse?.({ method, path: path26, status: status4, requestId: requestId2, errorCode: typeof errorCode === "string" ? errorCode : void 0, durationMs: Math.max(0, Math.round(performance.now() - started2)) });
+        options.onResponse?.({ method, path: path26, status: status4, requestId: requestId2, errorCode: typeof errorCode === "string" ? errorCode : void 0, durationMs: Math.max(0, Math.round(performance.now() - started2)), serverTiming: serverTiming?.slice(0, 300) || void 0, cliLatest: semver("x-apex-cli-latest"), cliMinimum: semver("x-apex-cli-minimum") });
       } catch {
       }
     };
     const fallback2 = form ? 12e4 : 3e4;
+    const hasConfiguredTimeout = process.env.APEX_TIMEOUT_MS !== void 0;
     const configured = Number(process.env.APEX_TIMEOUT_MS ?? fallback2);
     const defaultMs = Number.isFinite(configured) && configured > 0 ? configured : fallback2;
-    const timeoutMs = requestTimeoutMs === void 0 ? defaultMs : Math.max(1, Math.min(defaultMs, requestTimeoutMs));
+    const minimumMs = !hasConfiguredTimeout && requestOptions?.minTimeoutMs !== void 0 ? Math.max(defaultMs, requestOptions.minTimeoutMs) : defaultMs;
+    const timeoutMs = requestTimeoutMs === void 0 ? minimumMs : Math.max(1, Math.min(minimumMs, requestTimeoutMs));
     const headers = { ...clientIdentityHeaders(), Authorization: `Bearer ${creds.apiKey}` };
     if (!form) headers["Content-Type"] = "application/json";
     if (creds.credentialKind === "user" || creds.apiKey.startsWith("apx_uk_")) {
@@ -7168,6 +7178,7 @@ function createHttpClient(creds, options) {
     } catch (error) {
       const outer = error && typeof error === "object" ? error : void 0;
       const nested = outer?.cause && typeof outer.cause === "object" ? outer.cause : void 0;
+      if (options.observeNetworkErrors) observe(0);
       return options.onNetworkError({
         baseUrl: creds.baseUrl,
         timeoutMs,
@@ -7180,11 +7191,11 @@ function createHttpClient(creds, options) {
     inspectVersion(response.headers);
     const json = await response.json().catch(() => null);
     const requestId = response.headers.get("x-request-id") ?? response.headers.get("x-vercel-id") ?? response.headers.get("cf-ray");
-    observe(response.status, requestId, extractErrorDetails(json)?.code);
+    observe(response.status, requestId, extractErrorDetails(json)?.code, response.headers);
     if (!response.ok) return { ok: false, status: response.status, data: json, error: extractErrorMessage(json, response.status), errorDetails: extractErrorDetails(json), requestId, retryAfter: response.headers.get("retry-after"), rateLimit: { limit: response.headers.get("x-ratelimit-limit"), remaining: response.headers.get("x-ratelimit-remaining"), reset: response.headers.get("x-ratelimit-reset") } };
     return { ok: true, status: response.status, data: json };
   }
-  return { request: (method, path26, body5, timeoutMs) => request2(method, path26, body5, timeoutMs), requestForm: (method, path26, body5) => request2(method, path26, body5, void 0, true) };
+  return { request: (method, path26, body5, timeoutMs, requestOptions) => request2(method, path26, body5, timeoutMs, false, requestOptions), requestForm: (method, path26, body5) => request2(method, path26, body5, void 0, true) };
 }
 
 // ../api-client/src/credentials.ts
@@ -7233,90 +7244,177 @@ var import_node_os4 = __toESM(require("node:os"));
 
 // src/update.ts
 var import_node_fs2 = require("node:fs");
-var import_promises = require("node:fs/promises");
 var import_node_os2 = require("node:os");
 var import_node_path2 = __toESM(require("node:path"));
+var UPGRADE_COMMAND = "npm install -g @drip-apex/apex-cli@latest";
+var NOTES_URL = "https://docs.drip-apex.com/docs/cli/commands-output";
 var TTL = 24 * 60 * 60 * 1e3;
 var FAILURE_TTL = 60 * 60 * 1e3;
+var SERVER_TTL = 7 * 24 * 60 * 60 * 1e3;
+var cachePath = () => import_node_path2.default.join((0, import_node_os2.homedir)(), ".drip", "update-check.json");
+var npmLatest;
+var serverLatest;
+var serverMinimum;
+var VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
 function versionParts(version) {
-  return /^\d+\.\d+\.\d+$/.test(version) ? version.split(".").map(Number) : void 0;
+  const match2 = VERSION_PATTERN.exec(version);
+  return match2 ? match2.slice(1, 4).map(Number) : void 0;
+}
+function prereleaseOf(version) {
+  return VERSION_PATTERN.exec(version)?.[4]?.split(".") ?? [];
+}
+function comparePrerelease(left, right) {
+  if (!left.length || !right.length) return right.length - left.length;
+  for (let index = 0; index < Math.min(left.length, right.length); index++) {
+    const a = left[index];
+    const b = right[index];
+    if (a === b) continue;
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) return Number(a) - Number(b);
+    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+    return a < b ? -1 : 1;
+  }
+  return left.length - right.length;
+}
+function compareVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return a[index] - b[index];
+  return comparePrerelease(prereleaseOf(left), prereleaseOf(right));
+}
+function readCache() {
+  try {
+    const value = JSON.parse((0, import_node_fs2.readFileSync)(cachePath(), "utf8"));
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+function writeCache(patch, remove5 = []) {
+  try {
+    const value = { ...readCache(), ...patch };
+    for (const key of remove5) delete value[key];
+    (0, import_node_fs2.mkdirSync)(import_node_path2.default.dirname(cachePath()), { recursive: true });
+    (0, import_node_fs2.writeFileSync)(cachePath(), JSON.stringify(value), { mode: 384 });
+  } catch {
+  }
+}
+function serverFresh(checkedAt) {
+  if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt)) return false;
+  const age = Date.now() - checkedAt;
+  return age >= 0 && age < SERVER_TTL;
+}
+function serverAges(cache) {
+  return {
+    latest: cache.server_latest_checked_at ?? cache.server_checked_at,
+    minimum: cache.server_minimum_checked_at ?? cache.server_checked_at
+  };
+}
+function loadServerCache() {
+  const cache = readCache();
+  const ages = serverAges(cache);
+  if (serverFresh(ages.latest) && cache.server_latest && versionParts(cache.server_latest))
+    serverLatest = cache.server_latest;
+  if (serverFresh(ages.minimum) && cache.server_minimum && versionParts(cache.server_minimum))
+    serverMinimum = cache.server_minimum;
+}
+loadServerCache();
+function recordServerCliPolicy(observation) {
+  const latestSeen = Boolean(observation.cliLatest && versionParts(observation.cliLatest));
+  const minimumSeen = Boolean(observation.cliMinimum && versionParts(observation.cliMinimum));
+  if (!latestSeen && !minimumSeen) return;
+  if (latestSeen && (!serverLatest || compareVersions(observation.cliLatest, serverLatest) > 0))
+    serverLatest = observation.cliLatest;
+  if (minimumSeen) serverMinimum = observation.cliMinimum;
+  const now = Date.now();
+  const ages = serverAges(readCache());
+  const patch = {};
+  const remove5 = ["server_checked_at"];
+  if (latestSeen)
+    Object.assign(patch, { server_latest: serverLatest, server_latest_checked_at: now });
+  else if (serverLatest && serverFresh(ages.latest))
+    Object.assign(patch, { server_latest: serverLatest, server_latest_checked_at: ages.latest });
+  else remove5.push("server_latest", "server_latest_checked_at");
+  if (minimumSeen)
+    Object.assign(patch, { server_minimum: serverMinimum, server_minimum_checked_at: now });
+  else if (serverMinimum && serverFresh(ages.minimum))
+    Object.assign(patch, {
+      server_minimum: serverMinimum,
+      server_minimum_checked_at: ages.minimum
+    });
+  else remove5.push("server_minimum", "server_minimum_checked_at");
+  writeCache(patch, remove5);
+}
+function clearUpdateCache() {
+  writeCache({}, [
+    "latest",
+    "checked_at",
+    "server_latest",
+    "server_minimum",
+    "server_latest_checked_at",
+    "server_minimum_checked_at",
+    "server_checked_at"
+  ]);
+  npmLatest = serverLatest = serverMinimum = void 0;
+}
+function currentUpdateState(current, minimumOverride) {
+  if (minimumOverride && versionParts(minimumOverride))
+    recordServerCliPolicy({ cliMinimum: minimumOverride });
+  const latest = [npmLatest, serverLatest, serverMinimum, current].filter((value) => Boolean(value)).reduce((highest, value) => compareVersions(value, highest) > 0 ? value : highest, current);
+  const minimum = serverMinimum;
+  const required = Boolean(minimum && compareVersions(current, minimum) < 0);
+  if (!required && process.env.APEX_NO_UPDATE_CHECK === "1") return;
+  if (!required && compareVersions(latest, current) <= 0) return;
+  const installed = versionParts(current);
+  const available = versionParts(latest);
+  return {
+    current,
+    latest,
+    ...minimum ? { minimum } : {},
+    required,
+    breaking: available[0] !== installed[0] || installed[0] === 0 && available[1] !== installed[1],
+    command: UPGRADE_COMMAND,
+    notes_url: NOTES_URL
+  };
 }
 async function checkForUpdate(current) {
   if (process.env.APEX_NO_UPDATE_CHECK === "1") return;
   if (process.env[["APEX", "CLI", "MOCK", "API"].join("_")] === "1" || process.env.CI) return;
-  const installed = versionParts(current);
-  if (!installed) return;
+  if (!versionParts(current)) return;
+  const cache = readCache();
+  const age = Date.now() - (cache.checked_at ?? 0);
+  if (age >= 0 && cache.latest === null && age < FAILURE_TTL) return;
+  if (age >= 0 && age < TTL && cache.latest && versionParts(cache.latest)) {
+    npmLatest = cache.latest;
+    return;
+  }
   const controller = new AbortController();
   let timer;
-  const cachePath = import_node_path2.default.join((0, import_node_os2.homedir)(), ".drip", "update-check.json");
-  const lookup2 = async () => {
-    let latest;
-    const remember = async (value) => {
-      try {
-        await (0, import_promises.mkdir)(import_node_path2.default.dirname(cachePath), { recursive: true });
-        await (0, import_promises.writeFile)(cachePath, JSON.stringify({ latest: value, checked_at: Date.now() }), {
-          mode: 384
-        });
-      } catch {
-      }
-    };
-    try {
-      const cache = JSON.parse(await (0, import_promises.readFile)(cachePath, "utf8"));
-      const age = Date.now() - cache.checked_at;
-      if (cache.latest === null && typeof cache.checked_at === "number" && age >= 0 && age < FAILURE_TTL)
-        return;
-      if (typeof cache.checked_at === "number" && age >= 0 && age < TTL && typeof cache.latest === "string" && versionParts(cache.latest))
-        latest = cache.latest;
-    } catch {
-    }
-    if (!latest && !controller.signal.aborted) {
-      let body5;
-      try {
-        const response = await fetch("https://registry.npmjs.org/@drip-apex%2Fapex-cli/latest", {
-          headers: { Accept: "application/json" },
-          signal: controller.signal
-        });
-        body5 = response.ok ? await response.json() : void 0;
-      } catch {
-        body5 = void 0;
-      }
-      if (typeof body5?.version !== "string" || !versionParts(body5.version)) {
-        await remember(null);
-        return;
-      }
-      latest = body5.version;
-      await remember(latest);
-    }
-    if (!latest) return;
-    const available = versionParts(latest);
-    const difference = available.findIndex((part, index) => part !== installed[index]);
-    if (difference < 0 || available[difference] < installed[difference]) return;
-    return {
-      current,
-      latest,
-      breaking: available[0] !== installed[0] || installed[0] === 0 && available[1] !== installed[1],
-      notes_url: "https://docs.drip-apex.com/docs/cli/commands-output"
-    };
-  };
   try {
-    return await Promise.race([
-      lookup2(),
+    const body5 = await Promise.race([
+      fetch("https://registry.npmjs.org/@drip-apex%2Fapex-cli/latest", {
+        headers: { Accept: "application/json" },
+        signal: controller.signal
+      }).then(
+        async (response) => response.ok ? await response.json() : void 0
+      ).catch(() => void 0),
       new Promise((resolve2) => {
         timer = setTimeout(() => {
           controller.abort();
-          try {
-            (0, import_node_fs2.mkdirSync)(import_node_path2.default.dirname(cachePath), { recursive: true });
-            (0, import_node_fs2.writeFileSync)(cachePath, JSON.stringify({ latest: null, checked_at: Date.now() }), {
-              mode: 384
-            });
-          } catch {
-          }
           resolve2(void 0);
         }, 900);
       })
     ]);
+    if (!body5?.version || !versionParts(body5.version)) {
+      writeCache({ latest: null, checked_at: Date.now() });
+      return;
+    }
+    npmLatest = body5.version;
+    writeCache({ latest: npmLatest, checked_at: Date.now() });
   } catch {
-    return;
+    writeCache({ latest: null, checked_at: Date.now() });
   } finally {
     if (timer) clearTimeout(timer);
   }
@@ -7325,7 +7423,7 @@ async function checkForUpdate(current) {
 // package.json
 var package_default = {
   name: "@drip-apex/apex-cli",
-  version: "0.15.3",
+  version: "0.15.4",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -7383,7 +7481,9 @@ var EXIT_CODES = {
   auth: 2,
   validation: 3,
   confirmationRequired: 4,
-  conflict: 5
+  conflict: 5,
+  // A check command ran and reported a definite failing verdict.
+  checkFailed: 6
 };
 var MAX_RECORDED_API_FAILURES = 32;
 var recentApiFailures = [];
@@ -7495,7 +7595,13 @@ function configureRuntime(command) {
   };
 }
 function writeJsonDocument(envelope) {
-  const text2 = `${JSON.stringify({ ...envelope, ...updateNotice ? { update: updateNotice } : {} }, null, 2)}
+  const update6 = currentUpdateState(
+    CLI_VERSION,
+    envelope.ok ? void 0 : minimumFromError(envelope.error, envelope.error.reason)
+  );
+  const warnings = update6 ? [updateWarning(update6)] : [];
+  writeUpdateNotice(update6);
+  const text2 = `${JSON.stringify({ ...envelope, ...update6 ? { update: update6 } : {}, ...warnings.length ? { warnings } : {} }, null, 2)}
 `;
   if (wroteEnvelope) {
     process.stderr.write(text2);
@@ -7600,6 +7706,7 @@ var liveSpinners = /* @__PURE__ */ new Set();
 var exitFallback;
 function drainAndExit(code) {
   for (const spinner of liveSpinners) spinner.stop();
+  writePendingUpdateNotice();
   process.exitCode = code;
   if (exitFallback) clearTimeout(exitFallback);
   exitFallback = setTimeout(() => process.exit(code), 500);
@@ -7638,13 +7745,35 @@ async function createSpinner(message) {
   }
   return spinner.start();
 }
-var updateNotice;
 async function maybeCheckForUpdate() {
-  updateNotice = await checkForUpdate(CLI_VERSION);
-  if (updateNotice)
-    process.stderr.write(`Apex CLI ${updateNotice.latest} is available; current ${CLI_VERSION}.
+  await checkForUpdate(CLI_VERSION);
+}
+var wroteUpdateNotice = false;
+function updateWarning(update6) {
+  return update6.required ? {
+    code: "cli_upgrade_required",
+    message: `Apex CLI ${update6.current} is below the minimum supported version ${update6.minimum}. Run: ${UPGRADE_COMMAND} (or apex upgrade), then retry.`
+  } : {
+    code: "cli_update_available",
+    message: `Apex CLI ${update6.latest} is available (current ${update6.current}). Run: ${UPGRADE_COMMAND}`
+  };
+}
+function writeUpdateNotice(update6) {
+  if (!update6 || wroteUpdateNotice) return;
+  wroteUpdateNotice = true;
+  process.stderr.write(`${updateWarning(update6).message}
 `);
 }
+function writePendingUpdateNotice() {
+  writeUpdateNotice(currentUpdateState(CLI_VERSION));
+}
+process.on?.("beforeExit", writePendingUpdateNotice);
+function minimumFromError(error, reason2) {
+  if (reason2 !== "cli_upgrade_required") return;
+  const api = error.api?.body;
+  const value = error.details?.minimum ?? api?.error?.details?.minimum;
+  return typeof value === "string" ? value : void 0;
+}
 async function handleCliError(err, command) {
   if (err && typeof err === "object" && "exitCode" in err && err.exitCode === 0) {
     flushFallbackEnvelope();
@@ -7676,6 +7805,9 @@ async function handleCliError(err, command) {
       process.stderr.write(`Retry: ${String(cliError.details.retry)}
 `);
     }
+    writeUpdateNotice(
+      currentUpdateState(CLI_VERSION, minimumFromError(cliError, errorReason(cliError)))
+    );
   }
   await finishInvocation({ exitCode: cliError.exitCode, error: err });
   drainAndExit(cliError.exitCode);
@@ -7687,9 +7819,20 @@ function errorReason(error) {
   const body5 = error.api?.body;
   const code = body5?.code ?? body5?.error?.code ?? (error.api ? details?.code : void 0);
   if (typeof code === "string" && code) return code;
-  if (["shop_context_required", "local_file_error", "validation_failed", "member_suspended"].includes(
-    String(details?.code)
-  ))
+  if ([
+    "shop_context_required",
+    "shop_context_mismatch",
+    "install_check_failed",
+    "local_file_error",
+    "validation_failed",
+    "member_suspended",
+    "upgrade_failed",
+    "conflicting_context_input",
+    "context_not_persistable",
+    "context_selection_required",
+    "invalid_window",
+    "output_exists"
+  ].includes(String(details?.code)))
     return String(details?.code);
   const status4 = error.api?.status;
   if (status4 === 401) return "auth_required";
@@ -7705,6 +7848,14 @@ function errorReason(error) {
 function errorNextSteps(error) {
   const reason2 = errorReason(error);
   const steps = [];
+  if (reason2 === "cli_upgrade_required")
+    steps.push(
+      {
+        command: UPGRADE_COMMAND,
+        why: "This CLI version is below the server's minimum for changes; upgrade, then retry the same command."
+      },
+      { command: "apex upgrade", why: "Runs the same install for you." }
+    );
   if (reason2 === "member_suspended")
     return [
       {
@@ -7712,6 +7863,14 @@ function errorNextSteps(error) {
         why: "Ask an organization owner or admin to reinstate your membership."
       }
     ];
+  if (reason2 === "feature_disabled") {
+    const label = typeof error.details?.label === "string" ? error.details.label : "this feature";
+    const setting = typeof error.details?.setting === "string" ? ` (shop setting ${error.details.setting})` : "";
+    steps.push({
+      command: "ask your Apex contact",
+      why: `Turn on ${label} for this shop${setting}.`
+    });
+  }
   if (reason2 === "auth_required" || error.api?.status === 401) {
     steps.push({ command: "apex login", why: "Authenticate with a valid API key." });
     if (!error.api)
@@ -7751,8 +7910,10 @@ function errorNextSteps(error) {
   const hints = error.details?.next_steps;
   if (Array.isArray(hints))
     for (const hint of hints) {
-      if (hint && typeof hint.command === "string" && typeof hint.why === "string")
-        steps.push({ command: hint.command, why: hint.why });
+      if (hint && typeof hint.command === "string" && typeof hint.why === "string") {
+        if (!steps.some((step) => step.command === hint.command))
+          steps.push({ command: hint.command, why: hint.why });
+      }
     }
   if (reason2 === "validation_failed" && error.details?.plan)
     steps.push({
@@ -7869,7 +8030,7 @@ function clearCredentials() {
   } catch {
   }
 }
-function requireCredentials() {
+function requireCredentials(fallbackShopId) {
   const creds = getCredentials();
   if (!creds) {
     throw new CliError(
@@ -7878,6 +8039,7 @@ function requireCredentials() {
     );
   }
   const context = resolveContext(creds, void 0, defaultCredentialKind(creds));
+  if (!context.shopId) context.shopId = fallbackShopId?.trim() || void 0;
   if (defaultCredentialKind(creds) === "user") {
     setEnvelopeContext({
       credential: "user",
@@ -7917,6 +8079,53 @@ function requireCredentials() {
   });
   return { ...creds, credentialKind: "shop", resolvedContext: context };
 }
+function resolveCheckShop(explicitShopId, fallbackShopId) {
+  const explicit = explicitShopId?.trim() || null;
+  const fallback2 = fallbackShopId?.trim() || null;
+  const creds = requireCredentials(explicit ?? fallback2 ?? void 0);
+  const selectedFlag = argvOption("shop")?.trim() || null;
+  if (explicit && selectedFlag && explicit.toLowerCase() !== selectedFlag.toLowerCase()) {
+    throw new CliError(
+      `--shop-id ${explicit} does not match --shop ${selectedFlag}; pass the same shop to both or drop one.`,
+      EXIT_CODES.validation,
+      {
+        code: "shop_context_mismatch",
+        field: "shop-id",
+        requested_shop_id: explicit,
+        selected_shop_id: selectedFlag
+      }
+    );
+  }
+  const previous = creds.resolvedContext?.shopId?.trim() || null;
+  const shopId = explicit ?? previous ?? fallback2;
+  if (creds.credentialKind !== "user" || !shopId) return { creds, shopId };
+  const resolvedContext = { ...creds.resolvedContext, shopId };
+  setEnvelopeContext({
+    credential: "user",
+    org_id: resolvedContext.orgId ?? null,
+    shop_id: shopId
+  });
+  return {
+    creds: { ...creds, resolvedContext },
+    shopId,
+    ...previous && previous.toLowerCase() !== shopId.toLowerCase() ? { overriddenShopId: previous } : {}
+  };
+}
+function assertResponseShop(apiShopId, requestedShopId, credentialKind) {
+  const api = apiShopId?.trim();
+  const requested = requestedShopId?.trim();
+  if (!requested || api && api.toLowerCase() === requested.toLowerCase()) return;
+  throw new CliError(
+    !api ? `The API returned no shop identity; cannot verify that it answered for the requested shop ${requested}.` : credentialKind === "shop" ? `This API key is bound to shop ${api}, not the requested shop ${requested}; use a key for that shop or drop --shop-id.` : `The API answered for shop ${api}, not the requested shop ${requested}.`,
+    EXIT_CODES.validation,
+    {
+      code: "shop_context_mismatch",
+      field: "shop-id",
+      requested_shop_id: requested,
+      api_shop_id: api || null
+    }
+  );
+}
 function requireUserCredentials() {
   const creds = getCredentials();
   const environmentUserKey = creds?.credentialKind === "user" ? creds.apiKey : void 0;
@@ -7977,7 +8186,65 @@ var invocation;
 var firstError;
 var apiCalls = 0;
 var finished = false;
+var resolvedPath = "";
+var helpPath;
+var attempted;
+var apiCallTimings = [];
+var entity;
+function registerTelemetryProgram(program3) {
+  program3.hook("preAction", (_command, actionCommand) => {
+    resolvedPath = telemetryCommandPath(actionCommand);
+  });
+  const registerHelp = (command) => {
+    command.on("beforeHelp", () => {
+      helpPath = telemetryCommandPath(command);
+    });
+    for (const child of command.commands) registerHelp(child);
+  };
+  registerHelp(program3);
+}
+function telemetryCommandPath(command) {
+  return commandPath(command).replace(/^apex(?:\s+|$)/, "");
+}
+function recordCommanderExit(error, command) {
+  resolvedPath = telemetryCommandPath(command);
+  attempted = error.code === "commander.unknownCommand" && command.args[0] ? [resolvedPath, redactAttempted(command.args[0])].filter(Boolean).join(" ").slice(0, 200) : resolvedPath || void 0;
+}
+var agentHosts = /* @__PURE__ */ new Set([
+  "claude-code",
+  "codex",
+  "cursor",
+  "grok",
+  "gemini",
+  "copilot",
+  "other"
+]);
+function detectAgentHost(env2, tty2) {
+  if (env2.APEX_AGENT_HOST && agentHosts.has(env2.APEX_AGENT_HOST)) return env2.APEX_AGENT_HOST;
+  if (env2.CLAUDECODE === "1") return "claude-code";
+  if (env2.CODEX_THREAD_ID || env2.CODEX_SANDBOX) return "codex";
+  if (env2.CURSOR_AGENT || env2.CURSOR_TRACE_ID) return "cursor";
+  if (Object.keys(env2).some((name) => name.startsWith("GROK_"))) return "grok";
+  if (env2.AI_AGENT) {
+    const token = env2.AI_AGENT.match(/^[a-z-]+/)?.[0];
+    return token && agentHosts.has(token) ? token : "other";
+  }
+  return tty2 ? "terminal" : void 0;
+}
+function detectSessionId(env2) {
+  if (/^[A-Za-z0-9._:-]{1,128}$/.test(env2.APEX_SESSION_ID ?? "")) return env2.APEX_SESSION_ID;
+  const hostId = env2.CLAUDE_CODE_SESSION_ID || env2.CODEX_THREAD_ID;
+  return hostId ? `h_${(0, import_node_crypto2.createHash)("sha256").update(hostId).digest("hex").slice(0, 32)}` : void 0;
+}
 function beginInvocation(command, context = {}) {
+  resolvedPath = telemetryCommandPath(command);
+  helpPath = void 0;
+  attempted = void 0;
+  firstError = void 0;
+  apiCalls = 0;
+  finished = false;
+  apiCallTimings.length = 0;
+  entity = void 0;
   const names = /* @__PURE__ */ new Set();
   for (let current = command; current; current = current.parent) {
     for (const option of current.options) {
@@ -8030,7 +8297,9 @@ var staticRouteSegments = /* @__PURE__ */ new Set([
   "duplicate",
   "entry-exit",
   "environments",
+  "events",
   "evidence",
+  "export",
   "exclusion-groups",
   "experiments",
   "external-pixels",
@@ -8124,6 +8393,24 @@ function normalizeRoute(path26) {
 }
 function recordApiResponse2(response) {
   apiCalls++;
+  if (apiCallTimings.length < 25)
+    apiCallTimings.push({
+      method: response.method,
+      route: normalizeRoute(response.path),
+      status: response.status,
+      duration_ms: response.durationMs,
+      ...response.serverTiming ? { server_timing: response.serverTiming } : {}
+    });
+  if (!entity) {
+    const match2 = response.path.match(
+      /^\/api\/v1\/(experiments|landing-pages)\/([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})(?=\/|\?|$)/i
+    );
+    if (match2)
+      entity = {
+        entity_type: match2[1] === "experiments" ? "experiment" : "landing_page",
+        entity_id: match2[2]
+      };
+  }
   if (response.status >= 400 && !firstError)
     firstError = { ...response, path: normalizeRoute(response.path) };
 }
@@ -8133,20 +8420,62 @@ function classifyError(exitCode, error, status4) {
   if (detail5.code === "commander.unknownCommand") return "unknown_command";
   if (detail5.code?.startsWith("commander.")) return "validation";
   if (exitCode === 4) return "confirmation_required";
+  if (exitCode === EXIT_CODES.checkFailed) return "check_failed";
   if (status4 === 401 || status4 === 403 || exitCode === 2) return "auth";
-  if (status4 === 404) return "not_found";
+  if (status4 === 404 || status4 === 410) return "not_found";
   if (status4 === 429) return "rate_limited";
   if (status4 === 409 || exitCode === 5) return "conflict";
   if (status4 && status4 >= 500) return "server";
   if (status4 === 400 || status4 === 422 || exitCode === 3) return "validation";
+  if (detail5.details?.reason === "timeout" || detail5.details?.reason === "connect_timeout" || detail5.name === "TimeoutError")
+    return "timeout";
   if (Boolean(
-    detail5.details?.reason && ["network", "dns", "timeout", "tls", "refused", "reset", "unknown"].includes(
-      detail5.details.reason
-    )
-  ) || detail5.details?.code === "network_error" || detail5.name === "TimeoutError")
+    detail5.details?.reason && ["network", "dns", "tls", "refused", "reset", "unknown"].includes(detail5.details.reason)
+  ) || detail5.details?.code === "network_error")
     return "network";
   return "internal";
 }
+function redactAttempted(token) {
+  return /^(?:apx_|sk_|pk_|rk_|ghp_|gho_|xox|Bearer)/.test(token) || /^[A-Za-z0-9_-]{24,}$/.test(token) || /:\/\/|[/\\@=]/.test(token) || token.length > 40 ? "(redacted)" : token;
+}
+function normalizeErrorCode(value, exitCode) {
+  const normalized = value.toLowerCase();
+  return normalized.length <= 64 && /^[a-z0-9._-]+$/.test(normalized) ? normalized : `exit_${exitCode}`;
+}
+function invocationErrorCode(exitCode, error, commanderExit) {
+  if (exitCode === 0) return void 0;
+  let value = firstError?.errorCode;
+  if (!value && firstError)
+    value = firstError.status === 410 ? "gone" : `http_${firstError.status}`;
+  const detail5 = error && typeof error === "object" ? error : {};
+  if (!value && typeof detail5.details?.reason === "string" && !detail5.api) {
+    const reason2 = detail5.details.reason.toLowerCase();
+    value = [
+      "network",
+      "dns",
+      "timeout",
+      "connect_timeout",
+      "tls",
+      "refused",
+      "reset",
+      "unknown"
+    ].includes(reason2) ? `network_${reason2}` : reason2 || void 0;
+  }
+  if (!value && commanderExit && typeof detail5.code === "string")
+    value = detail5.code.slice("commander.".length).replace(/([a-z])([A-Z])/g, "$1_$2");
+  if (!value) {
+    const apiCode = detail5.api?.body?.code ?? detail5.api?.body?.error?.code ?? detail5.details?.code;
+    if (typeof apiCode === "string" && apiCode) value = apiCode;
+    else if (detail5.api?.status === 401 || exitCode === 2) value = "auth_required";
+    else if (detail5.api?.status === 403) value = "auth_forbidden";
+    else if (detail5.api?.status === 404) value = "not_found";
+    else if (detail5.api?.status === 429) value = "rate_limited";
+    else if (detail5.api?.status === 409 || exitCode === 5) value = "conflict";
+    else if (exitCode === 4) value = "confirmation_required";
+    else if (exitCode === 3) value = "validation_failed";
+  }
+  return normalizeErrorCode(value ?? `exit_${exitCode}`, exitCode);
+}
 async function finishInvocation({
   exitCode: rawExitCode,
   error
@@ -8168,10 +8497,8 @@ async function finishInvocation({
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
     const commanderExit = code.startsWith("commander.");
     const parse3 = commanderExit && exitCode !== 0;
-    const token = commanderExit ? process.argv.slice(2).find((token2) => !token2.startsWith("-")) : void 0;
-    const attempted = token && (/^(?:apx_|sk_|pk_|rk_|ghp_|gho_|xox|Bearer)/.test(token) || /^[A-Za-z0-9_-]{24,}$/.test(token) || /:\/\/|[/\\@=]/.test(token) || token.length > 40) ? "(redacted)" : token;
-    if (attempted === "login" || attempted === "logout") return;
-    const command = parse3 ? "(parse)" : invocation?.command ?? (commanderExit && exitCode === 0 ? attempted ?? (code === "commander.version" ? "(version)" : "(help)") : void 0);
+    if (resolvedPath === "login" || resolvedPath === "logout") return;
+    const command = parse3 ? "(parse)" : invocation?.command ?? (commanderExit && exitCode === 0 ? code === "commander.version" ? "(version)" : ["(help)", helpPath].filter(Boolean).join(" ") : void 0);
     if (!command || command === "login" || command === "logout") return;
     if (!getClientIdentity()) setClientIdentity({ client: "apex-cli", version: CLI_VERSION });
     const payload = {
@@ -8185,8 +8512,12 @@ async function finishInvocation({
       exit_code: exitCode,
       error_class: classifyError(exitCode, error, firstError?.status),
       api_calls: apiCalls,
+      ...apiCallTimings.length ? { api_call_timings: [...apiCallTimings] } : {},
+      ...entity,
+      ...detectAgentHost(process.env, process.stdout.isTTY === true) ? { agent_host: detectAgentHost(process.env, process.stdout.isTTY === true) } : {},
+      ...detectSessionId(process.env) ? { session_id: detectSessionId(process.env) } : {},
       first_error_status: firstError?.status,
-      first_error_code: firstError?.errorCode,
+      first_error_code: invocationErrorCode(exitCode, error, commanderExit),
       first_error_request_id: firstError?.requestId,
       first_error_route: firstError?.path,
       duration_ms: Math.max(0, Math.round(performance.now() - started))
@@ -8207,13 +8538,13 @@ init_source();
 
 // src/commands/login.ts
 init_source();
-var import_node_crypto3 = __toESM(require("node:crypto"));
+var import_node_crypto4 = __toESM(require("node:crypto"));
 var import_node_http = __toESM(require("node:http"));
 var import_node_os6 = __toESM(require("node:os"));
 var import_node_readline2 = __toESM(require("node:readline"));
 
 // src/api.ts
-var import_node_crypto2 = require("node:crypto");
+var import_node_crypto3 = require("node:crypto");
 
 // ../api-client/src/landing-pages.ts
 var LANDING_PAGE_MANIFEST_FILE = "apex-landing-page.json";
@@ -8378,7 +8709,11 @@ function sharedClient(creds) {
   let client = sharedClients.get(creds);
   if (!client) {
     client = createHttpClient(creds, {
-      onResponse: recordApiResponse2,
+      onResponse: (observation) => {
+        recordApiResponse2(observation);
+        recordServerCliPolicy?.(observation);
+      },
+      observeNetworkErrors: true,
       transport: testTransport,
       testTransportVersion: () => testTransport ? process.env[["APEX", "CLI", "MOCK", "API", "VERSION"].join("_")] : void 0,
       onNetworkError: (info) => {
@@ -8428,8 +8763,14 @@ function sharedClient(creds) {
   }
   return client;
 }
-async function request(creds, method, path26, body5, requestTimeoutMs) {
-  const response = await sharedClient(creds).request(method, path26, body5, requestTimeoutMs);
+async function request(creds, method, path26, body5, requestTimeoutMs, options) {
+  const response = await sharedClient(creds).request(
+    method,
+    path26,
+    body5,
+    requestTimeoutMs,
+    options
+  );
   recordApiResponse(response);
   return response;
 }
@@ -8534,6 +8875,7 @@ function planExperimentFilesystem(creds, id, body5) {
     body5
   );
 }
+var APPLY_TIMEOUT_MS = 9e4;
 function applyExperimentFilesystem(creds, id, body5) {
   return request(
     creds,
@@ -8543,7 +8885,9 @@ function applyExperimentFilesystem(creds, id, body5) {
       files: body5.files,
       ...body5.accept_qa_invalidation !== void 0 ? { accept_qa_invalidation: body5.accept_qa_invalidation } : {},
       ...body5.confirmTargetingReplace === true ? { confirmTargetingReplace: true } : {}
-    }
+    },
+    void 0,
+    { minTimeoutMs: APPLY_TIMEOUT_MS }
   );
 }
 function getExperimentQaRun(creds, id) {
@@ -8569,8 +8913,9 @@ function attachExperimentQaEvidence(creds, id, body5) {
 function uploadExperimentQaEvidence(creds, id, form) {
   return requestForm(creds, "POST", `/api/v1/experiments/${id}/qa/evidence`, form);
 }
-function approveExperimentQa(creds, id) {
-  return request(creds, "PATCH", `/api/v1/experiments/${id}/qa`);
+function approveExperimentQa(creds, id, acknowledgement) {
+  if (!acknowledgement) return request(creds, "PATCH", `/api/v1/experiments/${id}/qa`);
+  return request(creds, "PATCH", `/api/v1/experiments/${id}/qa`, acknowledgement);
 }
 function reopenExperimentQa(creds, id) {
   return request(creds, "DELETE", `/api/v1/experiments/${id}/qa`);
@@ -8770,7 +9115,7 @@ function testTargeting(creds, url, opts) {
   return request(creds, "GET", `/api/v1/targeting/test?${params.toString()}`);
 }
 function createSos(creds, body5, options = {}) {
-  const idempotency_key = body5.idempotency_key ?? (0, import_node_crypto2.createHash)("sha256").update(
+  const idempotency_key = body5.idempotency_key ?? (0, import_node_crypto3.createHash)("sha256").update(
     [
       body5.type,
       body5.experiment_id ?? "",
@@ -9267,6 +9612,16 @@ function resolveSelection(tree, input) {
   const shop = shopValue ? match(shopValue, org.shops, "shop") : void 0;
   return { orgId: org.id, ...shop ? { shopId: shop.id } : {} };
 }
+function resolveFlagSelection(tree, values) {
+  if (values.org) {
+    const org = match(values.org, tree.orgs, "organization");
+    const shop2 = values.shop ? match(values.shop, org.shops, "shop") : void 0;
+    return { orgId: org.id, ...shop2 ? { shopId: shop2.id } : {} };
+  }
+  const shops2 = tree.orgs.flatMap((org) => org.shops.map((shop2) => ({ ...shop2, orgId: org.id })));
+  const shop = match(values.shop, shops2, "shop");
+  return { orgId: shop.orgId, shopId: shop.id };
+}
 function ask(question) {
   const rl = import_node_readline.default.createInterface({ input: process.stdin, output: process.stderr });
   return new Promise(
@@ -9279,8 +9634,23 @@ function ask(question) {
 async function pickContext(tree) {
   if (!process.stdin.isTTY || !process.stdout.isTTY)
     throw new CliError(
-      "Interactive context selection requires a TTY. Pass an org/shop to apex use, or use --org/--shop.",
-      EXIT_CODES.validation
+      "Interactive context selection requires a TTY. Pass <org>[/<shop>] to apex use, or use --org/--shop.",
+      EXIT_CODES.validation,
+      {
+        code: "context_selection_required",
+        candidates: tree.orgs.slice(0, 20).map((org2) => ({
+          org_id: org2.id,
+          org_name: org2.name,
+          shops: org2.shops.slice(0, 20).map((shop2) => ({ id: shop2.id, name: shop2.name }))
+        })),
+        truncated: tree.orgs.length > 20 || tree.orgs.some((org2) => org2.shops.length > 20),
+        next_steps: [
+          {
+            command: "apex use <org-id>/<shop-id>",
+            why: "Choose one of error.details.candidates."
+          }
+        ]
+      }
     );
   let org = tree.orgs.length === 1 ? tree.orgs[0] : void 0;
   if (!org) {
@@ -9400,7 +9770,7 @@ function parseFormBody(body5) {
   return new URLSearchParams(body5);
 }
 async function waitForBrowserLogin(baseUrl, userMode = false) {
-  const state = import_node_crypto3.default.randomBytes(24).toString("base64url");
+  const state = import_node_crypto4.default.randomBytes(24).toString("base64url");
   const clientName = import_node_os6.default.hostname() || "Local machine";
   return new Promise((resolve2, reject) => {
     let settled = false;
@@ -9710,6 +10080,14 @@ Context: ${current.orgId ?? "none"}${current.shopId ? ` / ${current.shopId}` : "
 
 // src/commands/use.ts
 var useCommand = new Command("use").description("Set the current Apex organization and shop context").argument("[context]", "<org-id-or-name>[/shop-id-or-name]").action(async function(input) {
+  const flags = this.optsWithGlobals();
+  if (input && (flags.org || flags.shop))
+    fail(
+      this,
+      "Pass the context either as <org>[/<shop>] or with --org/--shop, not both.",
+      EXIT_CODES.validation,
+      { code: "conflicting_context_input" }
+    );
   const creds = requireUserCredentials();
   const response = await getAccountContext(creds);
   if (!response.ok || !response.data)
@@ -9719,9 +10097,32 @@ var useCommand = new Command("use").description("Set the current Apex organizati
       classifyApiError(response.status, response.errorDetails),
       response.errorDetails
     );
-  const selected2 = input ? resolveSelection(response.data.data, input) : await pickContext(response.data.data);
+  const selected2 = input ? resolveSelection(response.data.data, input) : flags.org || flags.shop ? resolveFlagSelection(response.data.data, flags) : await pickContext(response.data.data);
   const stored = getStoredCredentials();
-  if (!stored) fail(this, "No stored credential to update. Run apex login first.");
+  if (!stored) {
+    const env2 = {
+      DRIP_ORG: selected2.orgId,
+      ...selected2.shopId ? { DRIP_SHOP: selected2.shopId } : {}
+    };
+    const exportCommand = `export DRIP_ORG=${selected2.orgId}${selected2.shopId ? ` DRIP_SHOP=${selected2.shopId}` : " && unset DRIP_SHOP"}`;
+    fail(
+      this,
+      `apex use cannot save a context: this run authenticates with an API key from the environment (APEX_API_KEY or DRIP_API_KEY) and no apex login credential file exists. Set DRIP_ORG=${selected2.orgId}${selected2.shopId ? ` and DRIP_SHOP=${selected2.shopId}` : " and unset DRIP_SHOP"} in the environment, or pass --org/--shop on each command.`,
+      EXIT_CODES.validation,
+      {
+        code: "context_not_persistable",
+        org_id: selected2.orgId,
+        shop_id: selected2.shopId ?? null,
+        env: env2,
+        next_steps: [
+          {
+            command: exportCommand,
+            why: "Selects this context for every later apex command in this environment."
+          }
+        ]
+      }
+    );
+  }
   saveCredentials({ ...stored, context: selected2 });
   setEnvelopeContext({
     credential: "user",
@@ -9737,7 +10138,7 @@ var useCommand = new Command("use").description("Set the current Apex organizati
 
 // src/commands/experiments.ts
 init_source();
-var import_node_crypto5 = __toESM(require("node:crypto"));
+var import_node_crypto6 = __toESM(require("node:crypto"));
 var import_node_fs8 = __toESM(require("node:fs"));
 var import_node_path6 = __toESM(require("node:path"));
 
@@ -10052,7 +10453,7 @@ function deriveStoreUrl(patterns) {
 }
 
 // src/lib/asset-upload.ts
-var import_node_crypto4 = __toESM(require("node:crypto"));
+var import_node_crypto5 = __toESM(require("node:crypto"));
 var import_node_fs7 = __toESM(require("node:fs"));
 var import_node_path5 = __toESM(require("node:path"));
 var INLINE_DATA_URI_MAX_CHARS = 4096;
@@ -10077,7 +10478,7 @@ var EXTENSION_BY_MIME = {
   "image/avif": ".avif"
 };
 function contentHash(bytes) {
-  return import_node_crypto4.default.createHash("sha256").update(bytes).digest("hex");
+  return import_node_crypto5.default.createHash("sha256").update(bytes).digest("hex");
 }
 function deliveryUrl(baseUrl, asset) {
   const returnedUrl = asset.deliveryUrl ?? asset.delivery_url ?? asset.url;
@@ -11063,6 +11464,16 @@ function printExperimentResults(results2, currency) {
   const outcomeProvenance = summary.outcome.provenance === "manager_decided" ? " (manager decided)" : "";
   console.log();
   console.log(source_default.bold(String(experiment2.name ?? experiment2.id ?? "Experiment results")));
+  if (typeof results2.computed_at === "string") {
+    const ageSeconds = Math.max(
+      0,
+      Math.round((Date.now() - Date.parse(results2.computed_at)) / 1e3)
+    );
+    const age = ageSeconds < 60 ? `${ageSeconds}s ago` : ageSeconds < 3600 ? `${Math.floor(ageSeconds / 60)}m ago` : `${Math.floor(ageSeconds / 3600)}h ago`;
+    console.log(
+      `  Computed:    ${results2.computed_at} (${age}, from ${String(results2.results_source ?? "unknown")})`
+    );
+  }
   console.log(`  Status:      ${statusBadge(String(experiment2.status ?? "unknown"))}`);
   const audience = audienceLine(results2.segment_applied);
   if (audience) console.log(`  Audience:    ${audience}`);
@@ -11142,7 +11553,7 @@ var FILESYSTEM_FILE_RE = new RegExp(
   `^(?:${pathAlternation(EXPERIMENT_FILESYSTEM_PATH_SCHEMA.topLevel)}|experiment/(?:${pathAlternation(EXPERIMENT_FILESYSTEM_PATH_SCHEMA.experiment)})|variations/[^/]+/(?:${pathAlternation(EXPERIMENT_FILESYSTEM_PATH_SCHEMA.variation)}))$`
 );
 function sha256Text(value) {
-  return import_node_crypto5.default.createHash("sha256").update(value).digest("hex");
+  return import_node_crypto6.default.createHash("sha256").update(value).digest("hex");
 }
 function folderPath(folder) {
   return import_node_path6.default.resolve(process.cwd(), folder);
@@ -11261,7 +11672,7 @@ async function rewriteExperimentFilesystemAssets(input) {
     baseUrl: input.baseUrl,
     enabled: input.enabled,
     upload: async (file) => {
-      const hash = import_node_crypto5.default.createHash("sha256").update(file.bytes).digest("hex");
+      const hash = import_node_crypto6.default.createHash("sha256").update(file.bytes).digest("hex");
       const cached = input.assets[hash];
       if (cached) return cached;
       if (input.upload === null) return null;
@@ -11591,7 +12002,7 @@ var list = new Command("list").alias("ls").description(
   "Filter by effective storefront URL targeting (applied server-side)"
 ).option("-n, --limit <n>", "Max results", "20").option("--include-archived", "Include archived experiments").option("--full", "Return full experiment details instead of the default summary").option(
   "--fields <list>",
-  "Comma-separated fields to return and table columns in order (JSON always keeps id)"
+  "Comma-separated fields to return and table columns in order (JSON always keeps id; fields outside the summary switch to full details automatically)"
 ).action(async function action3(opts) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Fetching experiments...");
@@ -11747,7 +12158,7 @@ ${JSON.stringify(data.order, null, 2)}`);
   console.log(`
 Definitions: ${data.definitions_url}`);
 }
-var results = new Command("results").description("Read experiment results and timeseries by ID or slug").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).option("--currency <code>", "Currency code for revenue formatting").option("--segment <dim:value>", "Include one audience segment").option("--exclude-segment <dim:value>", "Exclude one audience segment (include wins)").option("--explain", "Explain raw-event exclusions and residuals").option("--goal <id>", "Goal ID or event key for --explain").option("--order <key>", "Order label trail for --explain").option("--samples", "Show sample identifiers with --explain").action(async function action7(idOrSlug, opts) {
+var results = new Command("results").description("Read experiment results and timeseries by ID or slug").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).option("--currency <code>", "Currency code for revenue formatting").option("--segment <dim:value>", "Include one audience segment").option("--exclude-segment <dim:value>", "Exclude one audience segment (include wins)").option("--explain", "Explain raw-event exclusions and residuals").option("--goal <id>", "Goal ID or event key for --explain").option("--order <key>", "Order label trail for --explain").option("--samples", "Show sample identifiers with --explain").option("--wait <seconds>", "Wait for a cold server-side results build", "120").action(async function action7(idOrSlug, opts) {
   if (opts.explain && (opts.segment !== void 0 || opts.excludeSegment !== void 0))
     fail(
       this,
@@ -11764,16 +12175,38 @@ var results = new Command("results").description("Read experiment results and ti
       spinner?.fail(`Experiment "${idOrSlug}" not found`);
       fail(this, `Experiment "${idOrSlug}" not found.`, EXIT_CODES.validation);
     }
-    const res = opts.explain ? await getExperimentResultsExplain(creds, exp.id, opts) : await getExperimentResults(creds, exp.id, {
+    const waitSeconds = Number(opts.wait ?? "120");
+    if (!Number.isFinite(waitSeconds) || waitSeconds < 0) {
+      fail(this, "--wait must be a non-negative number of seconds", EXIT_CODES.validation);
+    }
+    const startedWaitingAt = Date.now();
+    let res = opts.explain ? await getExperimentResultsExplain(creds, exp.id, opts) : await getExperimentResults(creds, exp.id, {
       currency: opts.currency,
       segment: opts.segment,
       exclude_segment: opts.excludeSegment
     });
+    while (!opts.explain && isResultsComputing(res)) {
+      const elapsedSeconds = (Date.now() - startedWaitingAt) / 1e3;
+      const remainingSeconds = waitSeconds - elapsedSeconds;
+      if (remainingSeconds <= 0) break;
+      const requestedDelay = Number(
+        res.retryAfter ?? res.errorDetails?.retry_after_seconds ?? 15
+      );
+      const delaySeconds = Math.min(30, Math.max(0, requestedDelay), remainingSeconds);
+      if (!shouldUseJson(this))
+        console.error(`Results are computing on the server; retrying in ${delaySeconds} s`);
+      await new Promise((resolve2) => setTimeout(resolve2, delaySeconds * 1e3));
+      res = await getExperimentResults(creds, exp.id, {
+        currency: opts.currency,
+        segment: opts.segment,
+        exclude_segment: opts.excludeSegment
+      });
+    }
     if (!res.ok || !res.data) {
       spinner?.fail("Failed to fetch experiment results");
       fail(
         this,
-        res.error ?? "Failed to fetch experiment results",
+        `${res.error ?? "Failed to fetch experiment results"}${isResultsComputing(res) ? "; increase --wait to keep retrying" : ""}`,
         classifyStatus(res.status),
         res.errorDetails
       );
@@ -11790,6 +12223,11 @@ var results = new Command("results").description("Read experiment results and ti
     fail(this, error instanceof Error ? error.message : String(error));
   }
 });
+function isResultsComputing(res) {
+  if (res.status !== 503) return false;
+  const body5 = res.data;
+  return body5?.error?.code === "results_computing" || res.errorDetails?.code === "results_computing";
+}
 var DAY_NAMES = {
   mon: "monday",
   monday: "monday",
@@ -12864,7 +13302,45 @@ var applyFilesystem = new Command("apply").option(
       acceptQaInvalidation = true;
     }
     const spinner = process.stderr.isTTY ? await createSpinner("Applying experiment filesystem...") : null;
-    let res = await applyExperimentFilesystem(creds, session.experimentId, {
+    let verifiedAfterTimeout = false;
+    let verifiedTimeoutMs;
+    let publicationUnconfirmed = false;
+    const applyWithVerification = async (body5) => {
+      try {
+        return await applyExperimentFilesystem(creds, session.experimentId, body5);
+      } catch (error) {
+        if (!(error instanceof CliError) || error.details?.reason !== "timeout" && error.details?.reason !== "reset")
+          throw error;
+        const reason2 = error.details.reason;
+        const timeoutMs = typeof error.details.timeoutMs === "number" ? error.details.timeoutMs : APPLY_TIMEOUT_MS;
+        const verification = await planExperimentFilesystem(creds, session.experimentId, {
+          files
+        }).catch(() => null);
+        if (verification?.ok && verification.data?.ok === true && verification.data.changes.length === 0) {
+          verifiedAfterTimeout = true;
+          verifiedTimeoutMs = timeoutMs;
+          publicationUnconfirmed = verification.data.qaApproval?.status !== "draft";
+          return {
+            ok: true,
+            status: 200,
+            data: { applied: true, plan: verification.data }
+          };
+        }
+        const rerun = `apex experiments apply ${shellQuote(folderArg)}`;
+        throw new CliError(
+          `Apply did not confirm within ${timeoutMs / 1e3}s and the server does not yet hold these changes; re-run ${rerun}`,
+          EXIT_CODES.general,
+          {
+            code: "apply_unconfirmed",
+            reason: reason2,
+            timeoutMs,
+            pendingChanges: verification?.ok && verification.data ? verification.data.changes.length : null,
+            next_steps: [{ command: rerun, why: "Re-run the unconfirmed apply." }]
+          }
+        );
+      }
+    };
+    let res = await applyWithVerification({
       files,
       accept_qa_invalidation: acceptQaInvalidation,
       ...opts.confirmTargetingReplace ? { confirmTargetingReplace: true } : {}
@@ -12885,7 +13361,7 @@ var applyFilesystem = new Command("apply").option(
         output(this, { aborted: true }, () => console.log("Aborted."));
         return;
       }
-      res = await applyExperimentFilesystem(creds, session.experimentId, {
+      res = await applyWithVerification({
         files,
         accept_qa_invalidation: acceptQaInvalidation,
         confirmTargetingReplace: true
@@ -12907,7 +13383,8 @@ var applyFilesystem = new Command("apply").option(
         plan: res.data?.plan
       });
     }
-    spinner?.succeed("Applied experiment filesystem");
+    if (publicationUnconfirmed) spinner?.stop();
+    else spinner?.succeed("Applied experiment filesystem");
     const synced = opts.sync ? await refreshExperimentFilesystemFolderIfNeeded(creds, folder, session.experimentId) : false;
     if (!synced) {
       await refreshServerOwnedFilesIfNeeded(
@@ -12931,6 +13408,11 @@ var applyFilesystem = new Command("apply").option(
     const syncMessage = synced ? "Local files were synced." : opts.sync ? "Local file sync failed; retry --sync or apex experiments pull." : "Local authored files were left unchanged; use --sync or apex experiments pull to refresh." + (res.data?.receipt?.files ? "" : " No receipt file digests; authored-file manifest entries left unchanged.");
     const previewResult = await getQaPreviewUrls(creds, session.experimentId);
     const { previewUrls, dashboardUrl } = previewResult;
+    const publicationWarning = "Storefront publication is unconfirmed; visitors may still receive the previous treatment.";
+    const publicationNextStep = {
+      command: `apex experiments status ${shellQuote(folderArg)} --json`,
+      why: "Check experiment status before handover; persisted files do not confirm storefront publication."
+    };
     output(
       this,
       {
@@ -12939,14 +13421,30 @@ var applyFilesystem = new Command("apply").option(
         applied: true,
         plan: planRes.data,
         requiredAcknowledgment: requiredQaAcknowledgment(planRes.data),
-        result: res.data,
+        result: verifiedAfterTimeout ? null : res.data,
         synced,
         dashboardUrl,
-        receipt: res.data?.receipt ?? null,
-        previewUrls
+        receipt: verifiedAfterTimeout ? null : res.data?.receipt ?? null,
+        previewUrls,
+        ...verifiedAfterTimeout ? { verifiedAfterTimeout: true, timeoutMs: verifiedTimeoutMs } : {},
+        ...publicationUnconfirmed ? {
+          persisted: true,
+          publication: "unconfirmed",
+          warnings: [publicationWarning],
+          next_steps: [publicationNextStep]
+        } : {}
       },
       () => {
         printFilesystemPlan(planRes.data);
+        if (verifiedAfterTimeout) {
+          console.log(
+            `${publicationUnconfirmed ? "Apply saved" : "Apply confirmed"}: the server already holds these changes (the response timed out after ${verifiedTimeoutMs / 1e3}s).`
+          );
+        }
+        if (publicationUnconfirmed) {
+          console.log(`Warning: ${publicationWarning}`);
+          console.log(`Next: ${publicationNextStep.command} (${publicationNextStep.why})`);
+        }
         const receipt = res.data?.receipt;
         if (receipt) {
           console.log("\nReceipt");
@@ -13107,6 +13605,9 @@ var qaApprove = new Command("approve").description("Approve QA and move the expe
   "[folder-or-id]",
   "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
   "."
+).option(
+  "--acknowledge-zero-traffic",
+  "Acknowledge variations that receive no traffic for this split (Apex staff only)"
 ).action(async function action19(target) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Approving QA...");
@@ -13114,7 +13615,40 @@ var qaApprove = new Command("approve").description("Approve QA and move the expe
     const resolved = await resolveExperimentForFilesystemOrId(target);
     const before = await resolveExperiment(resolved.experimentId);
     if (!before) fail(this, "Experiment not found.", EXIT_CODES.validation);
-    const res = await approveExperimentQa(creds, resolved.experimentId);
+    let res = await approveExperimentQa(creds, resolved.experimentId);
+    const details = res.errorDetails;
+    if (!res.ok && res.status === 409 && details?.code === "degenerate_weights_ack_required") {
+      if (!this.opts().acknowledgeZeroTraffic) {
+        throw new CliError(
+          `${res.error ?? "QA approval requires acknowledgement"} Rerun with --acknowledge-zero-traffic.`,
+          classifyStatus(res.status),
+          details
+        );
+      }
+      if (details.internal_only === true) {
+        throw new CliError(
+          res.error ?? "Only Apex Admin or Internal users can acknowledge zero traffic.",
+          classifyStatus(res.status),
+          details
+        );
+      }
+      if (typeof details.split_hash === "string" && details.split_hash.length > 0) {
+        const weights = Array.isArray(details.variation_weights) ? details.variation_weights : [];
+        for (const value of weights) {
+          if (value && typeof value === "object") {
+            const variation = value;
+            process.stderr.write(
+              `${variation.name ?? variation.id ?? "Variation"}: ${(variation.weight ?? 0) * 100}%${variation.weight === 0 ? " (no traffic)" : ""}
+`
+            );
+          }
+        }
+        res = await approveExperimentQa(creds, resolved.experimentId, {
+          acknowledge_degenerate_weights: true,
+          acknowledge_degenerate_weights_hash: details.split_hash
+        });
+      }
+    }
     if (!res.ok)
       throw new CliError(
         res.error ?? "Failed to approve QA",
@@ -13419,7 +13953,7 @@ var screenshots = new Command("screenshots").description(
             Math.min(resumeDelayMs, Math.max(0, resumeDeadline - screenshotNow()))
           )
         );
-        resumeDelayMs = Math.min(Math.round(resumeDelayMs * 1.6), 1e4);
+        resumeDelayMs = Math.min(Math.round(resumeDelayMs * 1.6), 4e3);
         continue;
       }
       if (!existing.ok && isTransientResumeStatus(existing.status) && attempt <= 3 && screenshotNow() < resumeDeadline) {
@@ -13429,7 +13963,7 @@ var screenshots = new Command("screenshots").description(
             Math.min(resumeDelayMs, Math.max(0, resumeDeadline - screenshotNow()))
           )
         );
-        resumeDelayMs = Math.min(Math.round(resumeDelayMs * 1.6), 1e4);
+        resumeDelayMs = Math.min(Math.round(resumeDelayMs * 1.6), 4e3);
         continue;
       }
       break;
@@ -13583,7 +14117,7 @@ var screenshots = new Command("screenshots").description(
         );
       consecutiveTransientFailures += 1;
       if (consecutiveTransientFailures > 3) throw error;
-      delayMs = Math.min(Math.round(delayMs * 1.6), 1e4);
+      delayMs = Math.min(Math.round(delayMs * 1.6), 4e3);
       continue;
     }
     const polledToTerminalState = polled.ok && polled.data && polled.data.status !== "queued" && polled.data.status !== "processing";
@@ -13608,11 +14142,11 @@ var screenshots = new Command("screenshots").description(
           polled.errorDetails
         );
       }
-      delayMs = Math.min(Math.round(delayMs * 1.6), 1e4);
+      delayMs = Math.min(Math.round(delayMs * 1.6), 4e3);
       continue;
     }
     consecutiveTransientFailures = 0;
-    delayMs = Math.min(Math.round(delayMs * 1.6), 1e4);
+    delayMs = Math.min(Math.round(delayMs * 1.6), 4e3);
   }
   if (opts.attachQa !== false) {
     const attached = await attachExperimentQaEvidence(creds, experiment2.id, {
@@ -13990,6 +14524,8 @@ init_source();
 async function signedPreviewFromReadiness(creds, experimentId, variationId, targetUrl) {
   try {
     const client = createHttpClient(creds, {
+      onResponse: recordApiResponse2,
+      observeNetworkErrors: true,
       onNetworkError: (info) => {
         throw new Error(info.cause);
       }
@@ -14233,8 +14769,7 @@ function loadHarnessConfig(folder) {
       experimentName: experiment2.name ?? id,
       variationSlug: slugify(variation, "variant-a"),
       variationName: `Variant ${variation}`,
-      targetUrl,
-      antiFlickerSelectors: []
+      targetUrl
     }
   };
 }
@@ -14318,14 +14853,15 @@ async function createSession(folder) {
   if (!apex.targetUrl) {
     throw new Error("Missing targetUrl. Run `apex harness init` and set targetUrl.");
   }
+  const resetJs = cleanupResetJs(experiment2);
   const res = await createHarnessSession(creds, {
     experimentSlug: apex.experimentSlug,
     experimentName: apex.experimentName,
     variationSlug: apex.variationSlug,
     variationName: apex.variationName,
     targetUrl: apex.targetUrl,
-    resetJs: cleanupResetJs(experiment2),
-    antiFlickerSelectors: apex.antiFlickerSelectors ?? []
+    ...typeof resetJs === "string" ? { resetJs } : {},
+    ...Array.isArray(apex.antiFlickerSelectors) ? { antiFlickerSelectors: apex.antiFlickerSelectors } : {}
   });
   if (!res.ok)
     throw new CliError(
@@ -14453,7 +14989,7 @@ harnessCommand.command("publish").argument("<folder>", "AB Test Harness experime
 
 // src/commands/operator.ts
 init_source();
-var import_node_crypto6 = __toESM(require("node:crypto"));
+var import_node_crypto7 = __toESM(require("node:crypto"));
 var import_node_fs11 = __toESM(require("node:fs"));
 var import_node_path9 = __toESM(require("node:path"));
 var CANONICAL_FILE_RE = /^(src\/(?:index\.js|index\.scss|info\.js|mutations\.json)|experiment\.config\.json|metrics\.json|targeting\.json|dev-doc\.md|brand\.md|goals\/[a-zA-Z0-9_.-]+\.json|segments\/[a-zA-Z0-9_.-]+\.json|network\/[a-zA-Z0-9_.-]+\.recipe\.json)$/;
@@ -14498,8 +15034,13 @@ function formatWorkspaceBlockingIssues(value) {
     return lines.join("\n");
   }).join("\n");
 }
+function formatHarnessRefusal(message, details) {
+  const issues = formatWorkspaceBlockingIssues(details);
+  return issues ? `${message}
+${issues}` : message;
+}
 function sha256Text2(value) {
-  return import_node_crypto6.default.createHash("sha256").update(value).digest("hex");
+  return import_node_crypto7.default.createHash("sha256").update(value).digest("hex");
 }
 function byteLength(value) {
   return Buffer.byteLength(value, "utf8");
@@ -14692,12 +15233,11 @@ async function createExactHarnessSession(folder, session) {
     experimentName: expRes.data.name,
     variationSlug: config.variationSlug ?? variation.slug ?? slugify2(variation.name, "variation"),
     variationName: variation.name,
-    targetUrl,
-    antiFlickerSelectors: []
+    targetUrl
   });
   if (!res.ok || !res.data)
     throw new CliError(
-      res.error ?? "Failed to create harness session",
+      formatHarnessRefusal(res.error ?? "Failed to create harness session", res.errorDetails),
       classifyStatus(res.status),
       res.errorDetails
     );
@@ -14789,7 +15329,15 @@ async function runPublish(folderArg, opts = {}) {
     const harnessSession = await createExactHarnessSession(folder, session);
     const version = await uploadCurrentArtifactVersion(folder, harnessSession.sessionId);
     const published = await publishHarnessSession(creds, harnessSession.sessionId);
-    if (!published.ok) throw new Error(published.error ?? "Failed to publish external artifacts");
+    if (!published.ok)
+      throw new CliError(
+        formatHarnessRefusal(
+          published.error ?? "Failed to publish external artifacts",
+          published.errorDetails
+        ),
+        classifyStatus(published.status),
+        published.errorDetails
+      );
     external = {
       sessionId: harnessSession.sessionId,
       version: version.version,
@@ -15436,10 +15984,81 @@ trackingCommand.command("latency").description("Measure forced-preview versus na
 
 // src/commands/events.ts
 var import_node_fs14 = __toESM(require("node:fs"));
+var maxWindowMs = 31 * 864e5;
+function correctedWindowStep(opts, nowMs) {
+  const fromMs = Date.parse(opts.from);
+  const endMs = Math.min(fromMs + maxWindowMs, nowMs);
+  if (endMs <= fromMs) {
+    return {
+      command: "Choose a --from start before now.",
+      why: "No valid export window exists from this start; --to must be after --from and at or before now."
+    };
+  }
+  const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+  const args = [
+    "apex events export",
+    `--from ${quote(opts.from)}`,
+    `--to ${quote(new Date(endMs).toISOString())}`,
+    `--out ${quote(opts.out ?? "events.ndjson")}`
+  ];
+  if (opts.experiment !== void 0) args.push(`--experiment ${quote(opts.experiment)}`);
+  if (opts.eventType !== void 0) args.push(`--event-type ${quote(opts.eventType)}`);
+  args.push(`--qa ${quote(opts.qa)}`, `--limit ${quote(opts.limit)}`);
+  if (opts.jsonSummary) args.push("--json-summary");
+  return {
+    command: args.join(" "),
+    why: endMs === nowMs ? "Exports events through the current time with the same filters." : "Exports the first 31 days with the same filters; repeat with the next window."
+  };
+}
 var eventsCommand = new Command("events").description("Export raw tracking events");
-eventsCommand.command("export").description("Export every raw event in an absolute time window").requiredOption("--from <iso>", "Inclusive ISO 8601 window start").requiredOption("--to <iso>", "Exclusive ISO 8601 window end").option("--experiment <id>", "Filter by experiment ID").option("--event-type <types>", "Comma-separated event types").option("--qa <scope>", "QA scope: exclude, include, or only", "include").option("--limit <count>", "Page size from 1 to 1000", "500").option("--out <path>", "Write event rows to a file instead of stdout").option("--json-summary", "Print a JSON summary on stdout; requires --out for the NDJSON rows").action(async (opts, command) => {
+eventsCommand.command("export").description(
+  "Export every raw event in a window of at most 31 days that does not end in the future"
+).requiredOption(
+  "--from <iso>",
+  "Inclusive ISO 8601 window start; the window spans at most 31 days"
+).requiredOption("--to <iso>", "Exclusive ISO 8601 window end; not in the future").option("--experiment <id>", "Filter by experiment ID").option("--event-type <types>", "Comma-separated event types").option("--qa <scope>", "QA scope: exclude, include, or only", "include").option("--limit <count>", "Page size from 1 to 1000", "500").option("--out <path>", "Write event rows to a file instead of stdout").option("--json-summary", "Print a JSON summary on stdout; requires --out for the NDJSON rows").action(async (opts, command) => {
   if (!Number.isFinite(Date.parse(opts.from)) || !Number.isFinite(Date.parse(opts.to))) {
-    fail(command, "--from and --to must be ISO 8601 timestamps", EXIT_CODES.validation);
+    fail(command, "--from and --to must be ISO 8601 timestamps", EXIT_CODES.validation, {
+      code: "invalid_window",
+      reason: "invalid_timestamp"
+    });
+  }
+  const fromMs = Date.parse(opts.from);
+  const toMs = Date.parse(opts.to);
+  if (toMs <= fromMs)
+    fail(command, "--to must be after --from.", EXIT_CODES.validation, {
+      code: "invalid_window",
+      reason: "to_not_after_from"
+    });
+  const now = /* @__PURE__ */ new Date();
+  if (toMs - fromMs > maxWindowMs) {
+    const requestedDays = ((toMs - fromMs) / 864e5).toFixed(2);
+    fail(
+      command,
+      `The export window is ${requestedDays} days; the maximum is 31. Export in windows of at most 31 days.`,
+      EXIT_CODES.validation,
+      {
+        code: "invalid_window",
+        reason: "window_too_long",
+        max_days: 31,
+        requested_days: requestedDays,
+        next_steps: [correctedWindowStep(opts, now.getTime())]
+      }
+    );
+  }
+  if (toMs > now.getTime()) {
+    const nowIso = now.toISOString();
+    fail(
+      command,
+      `--to is in the future; use a time at or before now (${nowIso}).`,
+      EXIT_CODES.validation,
+      {
+        code: "invalid_window",
+        reason: "to_in_future",
+        now: nowIso,
+        next_steps: [correctedWindowStep(opts, now.getTime())]
+      }
+    );
   }
   if (!["exclude", "include", "only"].includes(opts.qa)) {
     fail(command, "--qa must be exclude, include, or only", EXIT_CODES.validation);
@@ -15479,129 +16098,150 @@ eventsCommand.command("export").description("Export every raw event in an absolu
         output2.once("error", reject);
       });
     } catch (error) {
+      const exists = error?.code === "EEXIST";
       fail(
         command,
-        `Cannot write ${opts.out}: ${error instanceof Error ? error.message : String(error)}`,
-        EXIT_CODES.general,
-        { code: "local_file_error" }
+        exists ? `Cannot write ${opts.out}: the file already exists. Choose a new --out path or delete the file first.` : `Cannot write ${opts.out}: ${error instanceof Error ? error.message : String(error)}`,
+        exists ? EXIT_CODES.validation : EXIT_CODES.general,
+        { code: exists ? "output_exists" : "local_file_error", path: opts.out }
       );
     }
   }
-  const writeLine = async (line) => {
-    const stream = output2 ?? process.stdout;
-    const accepted = output2 ? output2.write(line) : writeRawCommandOutput(line);
-    if (accepted) return;
-    await new Promise((resolve2, reject) => {
-      const onDrain = () => {
-        stream.off("error", onError);
-        resolve2();
-      };
-      const onError = (error) => {
-        stream.off("drain", onDrain);
-        reject(error);
-      };
-      stream.once("drain", onDrain);
-      stream.once("error", onError);
-    });
-  };
-  let cursor;
-  let written = 0;
-  let pages = 0;
-  let totals;
-  do {
-    const response = await exportEventsPage(requireCredentials(), {
-      from: opts.from,
-      to: opts.to,
-      experiment: opts.experiment,
-      eventTypes: opts.eventType?.split(",").map((value) => value.trim()).filter(Boolean),
-      qa: opts.qa,
-      limit,
-      cursor
-    });
-    if (!response.ok || !response.data) {
-      output2?.destroy();
-      fail(
-        command,
-        response.error ?? "Event export page failed",
-        classifyStatus(response.status),
-        response.errorDetails
-      );
-    }
-    if (outputError)
-      fail(
-        command,
-        `Cannot write ${opts.out}: ${outputError.message}`,
-        EXIT_CODES.general,
-        {
-          code: "local_file_error"
-        }
-      );
-    const page = response.data.data;
-    totals ??= page.totals;
-    for (const event of page.events) {
-      try {
-        await writeLine(`${JSON.stringify(event)}
-`);
-      } catch (error) {
+  try {
+    const writeLine = async (line) => {
+      const stream = output2 ?? process.stdout;
+      const accepted = output2 ? output2.write(line) : writeRawCommandOutput(line);
+      if (accepted) return;
+      await new Promise((resolve2, reject) => {
+        const onDrain = () => {
+          stream.off("error", onError);
+          resolve2();
+        };
+        const onError = (error) => {
+          stream.off("drain", onDrain);
+          reject(error);
+        };
+        stream.once("drain", onDrain);
+        stream.once("error", onError);
+      });
+    };
+    let cursor;
+    let written = 0;
+    let pages = 0;
+    let totals;
+    do {
+      const response = await exportEventsPage(requireCredentials(), {
+        from: opts.from,
+        to: opts.to,
+        experiment: opts.experiment,
+        eventTypes: opts.eventType?.split(",").map((value) => value.trim()).filter(Boolean),
+        qa: opts.qa,
+        limit,
+        cursor
+      });
+      if (!response.ok || !response.data) {
         fail(
           command,
-          `Cannot write ${opts.out ?? "stdout"}: ${error instanceof Error ? error.message : String(error)}`,
-          EXIT_CODES.general,
-          { code: "local_file_error" }
+          response.error ?? "Event export page failed",
+          classifyStatus(response.status),
+          response.errorDetails
         );
       }
-      written += 1;
-    }
-    pages += 1;
-    cursor = page.next_cursor ?? void 0;
-  } while (cursor);
-  if (output2) {
-    try {
-      await new Promise((resolve2, reject) => {
-        if (outputError) return reject(outputError);
-        output2.once("error", reject);
-        output2.end(resolve2);
-      });
-    } catch (error) {
-      fail(
-        command,
-        `Cannot write ${opts.out}: ${error instanceof Error ? error.message : String(error)}`,
-        EXIT_CODES.general,
-        { code: "local_file_error" }
-      );
+      if (outputError)
+        fail(
+          command,
+          `Cannot write ${opts.out}: ${outputError.message}`,
+          EXIT_CODES.general,
+          {
+            code: "local_file_error"
+          }
+        );
+      const page = response.data.data;
+      totals ??= page.totals;
+      for (const event of page.events) {
+        try {
+          await writeLine(`${JSON.stringify(event)}
+`);
+        } catch (error) {
+          fail(
+            command,
+            `Cannot write ${opts.out ?? "stdout"}: ${error instanceof Error ? error.message : String(error)}`,
+            EXIT_CODES.general,
+            { code: "local_file_error" }
+          );
+        }
+        written += 1;
+      }
+      pages += 1;
+      cursor = page.next_cursor ?? void 0;
+    } while (cursor);
+    if (output2) {
+      try {
+        await new Promise((resolve2, reject) => {
+          if (outputError) return reject(outputError);
+          output2.once("error", reject);
+          output2.end(resolve2);
+        });
+      } catch (error) {
+        fail(
+          command,
+          `Cannot write ${opts.out}: ${error instanceof Error ? error.message : String(error)}`,
+          EXIT_CODES.general,
+          { code: "local_file_error" }
+        );
+      }
+      if (outputError)
+        fail(
+          command,
+          `Cannot write ${opts.out}: ${outputError.message}`,
+          EXIT_CODES.general,
+          {
+            code: "local_file_error"
+          }
+        );
     }
-    if (outputError)
+    const matches = totals ? written === totals.events : false;
+    const summary = {
+      events_written: written,
+      pages,
+      totals: totals ?? null,
+      count_matches: matches
+    };
+    if (!matches)
       fail(
         command,
-        `Cannot write ${opts.out}: ${outputError.message}`,
+        "Exported event count does not match the server total. Totals are counted when the first page is read, so events that arrive late for a window ending in the last few minutes, or rows sharing one timestamp and event ID, can cause a difference. Re-run for a window that ended at least 15 minutes ago.",
         EXIT_CODES.general,
         {
-          code: "local_file_error"
+          reason: "export_count_mismatch",
+          ...summary
         }
       );
-  }
-  const matches = totals ? written === totals.events : false;
-  const summary = {
-    events_written: written,
-    pages,
-    totals: totals ?? null,
-    count_matches: matches
-  };
-  if (!matches)
-    fail(
-      command,
-      "Exported event count does not match the server total. Totals are counted when the first page is read, so events that arrive late for a window ending in the last few minutes, or rows sharing one timestamp and event ID, can cause a difference. Re-run for a window that ended at least 15 minutes ago.",
-      EXIT_CODES.general,
-      {
-        reason: "export_count_mismatch",
-        ...summary
-      }
-    );
-  if (summaryOnStdout) writeEnvelope(summary, "apex events export");
-  process.stderr.write(
-    `Exported ${written} events across ${pages} page(s); total ${totals?.events ?? "unknown"}; count matches: ${matches}.
+    if (summaryOnStdout) writeEnvelope(summary, "apex events export");
+    process.stderr.write(
+      `Exported ${written} events across ${pages} page(s); total ${totals?.events ?? "unknown"}; count matches: ${matches}.
 `
-  );
+    );
+  } catch (error) {
+    if (output2 && opts.out) {
+      output2.destroy();
+      import_node_fs14.default.rmSync(opts.out, { force: true });
+      const suffix = `The partial file ${opts.out} was removed.`;
+      if (error instanceof CliError)
+        throw new CliError(
+          `${error.message} ${suffix}`,
+          error.exitCode,
+          { ...error.details, partial_file_removed: true },
+          error.api
+        );
+      throw new CliError(
+        `${error instanceof Error ? error.message : String(error)} ${suffix}`,
+        EXIT_CODES.general,
+        { code: "local_file_error", partial_file_removed: true }
+      );
+    }
+    throw error;
+  }
 });
 
 // src/commands/goals.ts
@@ -15652,6 +16292,10 @@ function sdkPageviewGoalMatch(urlPattern, href) {
 var INVENTORY_PAGE_SIZE = 100;
 var GOALS_PAGE_SIZE = 100;
 var MAX_GOAL_PAGES = 100;
+var MAX_PAGE_LOOKUP_PAGES = 1e3;
+var UUID_V1_TO_V8 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var PAGE_OPTION_DESCRIPTION = "Page scope: page ID or page key (required for click goals, optional for pageview; a page key needs pages:read; a page ID does not; list pages with apex pages list)";
+var PAGE_NEXT_STEPS = [{ command: "apex pages list", why: "Find the page ID or key." }];
 var NON_QUANTIFIABLE = /* @__PURE__ */ new Set(["(", "|", "^", "$"]);
 function urlPatternDependence(pattern) {
   let fragment = false;
@@ -15794,6 +16438,58 @@ function parseCapture(command, value) {
 function cleanBody(input) {
   return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
 }
+async function resolveGoalPageId(command, creds, value) {
+  if (UUID_V1_TO_V8.test(value)) return value;
+  let cursor;
+  for (let page = 0; page < MAX_PAGE_LOOKUP_PAGES; page += 1) {
+    const response = await requestTargetingResource(
+      creds,
+      "GET",
+      "pages",
+      void 0,
+      void 0,
+      100,
+      cursor
+    );
+    if (!response.ok || !response.data) {
+      if (response.status === 403) {
+        fail(
+          command,
+          "Resolving a page key needs the pages:read permission. Pass the page ID instead (find it with apex pages list using a key that has pages:read, or in the dashboard).",
+          EXIT_CODES.auth,
+          {
+            code: "page_lookup_forbidden",
+            next_steps: [
+              {
+                command: "apex pages list",
+                why: "Use a key with pages:read to find the page ID, or get it from the dashboard; pass --page <page ID> instead."
+              }
+            ]
+          }
+        );
+      }
+      fail(
+        command,
+        response.error ?? "Failed to list pages",
+        classifyStatus(response.status),
+        response.errorDetails
+      );
+    }
+    if (!("data" in response.data) || !Array.isArray(response.data.data)) break;
+    const pageData = response.data;
+    const match2 = pageData.data.find((item) => item.key === value);
+    if (match2) return match2.id;
+    const next = pageData.pagination?.next_cursor ?? null;
+    if (!pageData.pagination?.has_more || !next || next === cursor) break;
+    cursor = next;
+  }
+  fail(
+    command,
+    `No active page with key ${value} in this shop; list pages with apex pages list`,
+    EXIT_CODES.validation,
+    { code: "page_not_found", next_steps: PAGE_NEXT_STEPS }
+  );
+}
 function printGoal(goal) {
   console.log();
   console.log(source_default.bold(goal.name));
@@ -15806,6 +16502,7 @@ function printGoal(goal) {
   if (goal.text_match) console.log(`  Text match: ${goal.text_match}`);
   if (goal.url_pattern) console.log(`  URL:        ${goal.url_pattern}`);
   if (goal.event_name) console.log(`  Event:      ${goal.event_name}`);
+  if (goal.page_id) console.log(`  Page:       ${goal.page_id}`);
   console.log(`  Count once: ${goal.count_once ? "yes" : "no"}`);
   console.log();
 }
@@ -15833,8 +16530,22 @@ var list2 = new Command("list").alias("ls").description("List goals").option("-n
     );
   });
 });
-var create2 = new Command("create").description("Create a goal").requiredOption("--name <name>", "Goal name").requiredOption("--type <type>", "click|pageview|custom|revenue").option("--measurement <measurement>", "conversion|value", "conversion").option("--value-property <property>", "Numeric event property for value goals").option("--value-unit <unit>", "currency|number|duration_seconds|percent").option("--selector <selector>", "CSS selector for click goals").option("--text-match <text>", "Text match for click goals").option("--url-pattern <pattern>", "URL pattern for pageview goals").option("--event-name <name>", "Event name for custom goals").option("--count-once", "Count only once per visitor").option("--capture <json-or-path>", "Capture JSON array or @path").action(async function action35(opts) {
+var create2 = new Command("create").description("Create a goal").requiredOption("--name <name>", "Goal name").requiredOption("--type <type>", "click|pageview|custom|revenue").option("--measurement <measurement>", "conversion|value", "conversion").option("--value-property <property>", "Numeric event property for value goals").option("--value-unit <unit>", "currency|number|duration_seconds|percent").option("--selector <selector>", "CSS selector for click goals").option("--text-match <text>", "Text match for click goals").option("--url-pattern <pattern>", "URL pattern for pageview goals").option("--event-name <name>", "Event name for custom goals").option("--page <id-or-key>", PAGE_OPTION_DESCRIPTION).option("--count-once", "Count only once per visitor").option("--capture <json-or-path>", "Capture JSON array or @path").action(async function action35(opts) {
   const creds = requireCredentials();
+  if (opts.type === "click" && !opts.page) {
+    fail(
+      this,
+      "Click goals need a page: pass --page <page id or key> (list pages with apex pages list)",
+      EXIT_CODES.validation,
+      { code: "page_required", next_steps: PAGE_NEXT_STEPS }
+    );
+  }
+  if ((opts.type === "custom" || opts.type === "revenue") && opts.page) {
+    fail(this, `--page is not supported for ${opts.type} goals`, EXIT_CODES.validation, {
+      code: "page_not_supported"
+    });
+  }
+  const pageId = typeof opts.page === "string" ? await resolveGoalPageId(this, creds, opts.page) : void 0;
   const body5 = cleanBody({
     name: opts.name,
     type: opts.type,
@@ -15845,6 +16556,7 @@ var create2 = new Command("create").description("Create a goal").requiredOption(
     text_match: opts.textMatch,
     url_pattern: opts.urlPattern,
     event_name: opts.eventName,
+    page_id: pageId,
     count_once: opts.countOnce === true,
     capture: parseCapture(this, typeof opts.capture === "string" ? opts.capture : void 0)
   });
@@ -15862,8 +16574,9 @@ var create2 = new Command("create").description("Create a goal").requiredOption(
 var update2 = new Command("update").description("Update a goal").argument("<id>", "Goal ID").option("--name <name>", "Goal name").option("--type <type>", "click|pageview|custom|revenue").option("--measurement <measurement>", "conversion|value").option(
   "--value-property <property>",
   "Numeric event property for value goals; pass null to clear"
-).option("--value-unit <unit>", "currency|number|duration_seconds|percent; pass null to clear").option("--selector <selector>", "CSS selector for click goals").option("--text-match <text>", "Text match for click goals").option("--url-pattern <pattern>", "URL pattern for pageview goals").option("--event-name <name>", "Event name for custom goals").option("--count-once", "Count only once per visitor").option("--no-count-once", "Do not count only once per visitor").option("--capture <json-or-path>", "Capture JSON array or @path").action(async function action36(id, opts) {
+).option("--value-unit <unit>", "currency|number|duration_seconds|percent; pass null to clear").option("--selector <selector>", "CSS selector for click goals").option("--text-match <text>", "Text match for click goals").option("--url-pattern <pattern>", "URL pattern for pageview goals").option("--event-name <name>", "Event name for custom goals").option("--page <id-or-key>", `${PAGE_OPTION_DESCRIPTION}; pass null to clear`).option("--count-once", "Count only once per visitor").option("--no-count-once", "Do not count only once per visitor").option("--capture <json-or-path>", "Capture JSON array or @path").action(async function action36(id, opts) {
   const creds = requireCredentials();
+  const pageId = opts.page === "null" ? null : typeof opts.page === "string" ? await resolveGoalPageId(this, creds, opts.page) : void 0;
   const body5 = cleanBody({
     name: opts.name,
     type: opts.type,
@@ -15874,6 +16587,7 @@ var update2 = new Command("update").description("Update a goal").argument("<id>"
     text_match: opts.textMatch,
     url_pattern: opts.urlPattern,
     event_name: opts.eventName,
+    page_id: pageId,
     count_once: opts.countOnce,
     capture: parseCapture(this, typeof opts.capture === "string" ? opts.capture : void 0)
   });
@@ -17518,13 +18232,13 @@ var NAMED_HTML_ENTITIES = {
   nbsp: "\xA0"
 };
 function decodeHtmlEntities(value) {
-  return value.replace(/&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z]+);/g, (match2, entity) => {
-    if (entity.startsWith("#")) {
-      const hex = entity[1] === "x" || entity[1] === "X";
-      const code = Number.parseInt(hex ? entity.slice(2) : entity.slice(1), hex ? 16 : 10);
+  return value.replace(/&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z]+);/g, (match2, entity2) => {
+    if (entity2.startsWith("#")) {
+      const hex = entity2[1] === "x" || entity2[1] === "X";
+      const code = Number.parseInt(hex ? entity2.slice(2) : entity2.slice(1), hex ? 16 : 10);
       return Number.isInteger(code) && code >= 0 && code <= 1114111 ? String.fromCodePoint(code) : match2;
     }
-    return NAMED_HTML_ENTITIES[entity.toLowerCase()] ?? match2;
+    return NAMED_HTML_ENTITIES[entity2.toLowerCase()] ?? match2;
   });
 }
 function printSettings(settings2) {
@@ -18294,9 +19008,6 @@ function resolveWorkerBase(options) {
   const raw = options.worker ?? process.env.DRIP_WORKER_URL ?? PRODUCTION_WORKER_BASE_URL;
   return raw.trim().replace(/\/+$/, "");
 }
-function resolveShopId(options) {
-  return (options.shopId ?? process.env.DRIP_SHOP_ID ?? "").trim() || null;
-}
 function servedConfigUrl(workerBase, shopId) {
   return `${workerBase}/config?shopId=${encodeURIComponent(shopId)}&env=${PRODUCTION_ENVIRONMENT_KEY}`;
 }
@@ -18469,7 +19180,8 @@ async function readGoals(creds) {
   return { goals };
 }
 async function runDoctor(options = {}) {
-  const creds = requireCredentials();
+  const resolved = resolveCheckShop(options.shopId, process.env.DRIP_SHOP_ID);
+  const { creds } = resolved;
   if (options.check === "purchase_capture") {
     const domainsRes2 = await getInstallDomains(creds);
     if (!domainsRes2.ok || !domainsRes2.data)
@@ -18479,7 +19191,9 @@ async function runDoctor(options = {}) {
         classifyStatus(domainsRes2.status),
         domainsRes2.errorDetails
       );
-    const shopId2 = resolveShopId(options) ?? domainsRes2.data.shop_id;
+    if (resolved.shopId)
+      assertResponseShop(domainsRes2.data.shop_id, resolved.shopId, creds.credentialKind);
+    const shopId2 = resolved.shopId ?? domainsRes2.data.shop_id;
     const servedResult2 = shopId2 ? await fetchServedConfig(resolveWorkerBase(options), shopId2) : {};
     const readTracking = async (minutes) => {
       try {
@@ -18530,6 +19244,7 @@ async function runDoctor(options = {}) {
         apiFailureOf(res)
       );
   }
+  assertResponseShop(domainsRes.data.shop_id, resolved.shopId, creds.credentialKind);
   for (const [label, res] of [
     ["url inventory", inventory],
     ["goals", goals]
@@ -18573,7 +19288,7 @@ async function runDoctor(options = {}) {
     withCaveat(devPollutionCheck(eventHosts, envsRes.data, unparsedRows), inventoryCaveat)
   );
   const primary = hostOnly(domainsRes.data.domain) ?? eventHosts[0];
-  const shopId = resolveShopId(options) ?? domainsRes.data.shop_id;
+  const shopId = resolved.shopId ?? domainsRes.data.shop_id;
   const workerBase = resolveWorkerBase(options);
   const [page, servedResult] = await Promise.all([
     primary ? fetchPrimaryHtml(primary) : Promise.resolve({}),
@@ -18794,7 +19509,7 @@ function consentRateCheck(items) {
 }
 var doctorCommand = new Command("doctor").description("Check shop configuration against observed analytics").option(
   "--shop-id <uuid>",
-  "Override the shop ID discovered from the API (DRIP_SHOP_ID also overrides it)"
+  "Apex shop ID to check; API requests use it too (DRIP_SHOP_ID is the fallback when no shop is selected)"
 ).option("--check <id>", "Run one check (for example purchase_capture)").option(
   "--worker <url>",
   `Apex Worker base URL; defaults to DRIP_WORKER_URL or ${PRODUCTION_WORKER_BASE_URL}`
@@ -18803,7 +19518,7 @@ var doctorCommand = new Command("doctor").description("Check shop configuration
   if (options.check && data.checks.length === 0)
     fail(this, `Unknown doctor check: ${options.check}`, EXIT_CODES.validation);
   output(this, data, () => printDoctorReport(data.checks));
-  if (data.checks.some((c) => c.status === "FAIL")) process.exitCode = EXIT_CODES.general;
+  if (data.checks.some((c) => c.status === "FAIL")) process.exitCode = EXIT_CODES.checkFailed;
 });
 function printDoctorReport(checks) {
   printTable(
@@ -18987,7 +19702,7 @@ Examples:
 );
 
 // src/commands/install.ts
-var import_promises4 = require("node:dns/promises");
+var import_promises3 = require("node:dns/promises");
 var import_node_http2 = require("node:http");
 var import_node_https = require("node:https");
 var import_node_net = require("node:net");
@@ -19045,7 +19760,7 @@ var testResolver;
 var testFetch;
 async function resolveHost(hostname) {
   const mocked = testResolver?.(hostname) ?? null;
-  const addresses = mocked ?? await (0, import_promises4.lookup)(hostname, { all: true });
+  const addresses = mocked ?? await (0, import_promises3.lookup)(hostname, { all: true });
   return addresses.map((entry) => entry.address);
 }
 async function validateUrl(raw, allowedHosts) {
@@ -19525,16 +20240,16 @@ async function checkServedConfig(configUrl, workerBaseUrl, workerBaseSource) {
   };
 }
 var installCommand = new Command("install").description("Check Apex storefront installation").command("check").description(
-  "Verify snippet, served config, and recent tracking using --shop-id, the selected shop, or DRIP_SHOP_ID"
+  "Verify snippet, served config, and recent tracking for --shop-id (which also selects the shop for API requests), the selected shop, or DRIP_SHOP_ID"
 ).option("--url <url>", "Check one explicit bound storefront URL").option(
   "--shop-id <id>",
-  "Apex shop ID to verify (falls back to --shop/apex use, then DRIP_SHOP_ID)"
+  "Apex shop ID to verify; API requests use it too (falls back to --shop/apex use, then DRIP_SHOP_ID)"
 ).option(
   "--worker-url <url>",
   "Apex Worker base URL that serves /config (defaults to the URL in the served snippet, then DRIP_WORKER_URL, then the production worker)"
 ).option("--environment <key>", "Environment key to request from the worker", "production").action(async function action65(opts) {
-  const creds = requireCredentials();
-  const shopId = opts.shopId?.trim() || resolveContext(creds).shopId?.trim() || process.env.DRIP_SHOP_ID?.trim() || null;
+  const resolved = resolveCheckShop(opts.shopId, process.env.DRIP_SHOP_ID);
+  const { creds, shopId, overriddenShopId } = resolved;
   if (!shopId)
     fail(
       this,
@@ -19542,6 +20257,10 @@ var installCommand = new Command("install").description("Check Apex storefront i
       EXIT_CODES.validation,
       { field: "shop-id" }
     );
+  if (overriddenShopId)
+    console.error(
+      `Checking shop ${shopId} from --shop-id instead of the selected shop ${overriddenShopId}.`
+    );
   const domains = await getInstallDomains(creds);
   if (!domains.ok || !domains.data)
     fail(
@@ -19550,6 +20269,7 @@ var installCommand = new Command("install").description("Check Apex storefront i
       classifyStatus(domains.status),
       domains.errorDetails
     );
+  assertResponseShop(domains.data.shop_id, shopId, creds.credentialKind);
   const mockStoreOrigins = cliTestSetting("STORE_ORIGINS");
   const storeOrigins = cliTestSetting("API") === "1" && mockStoreOrigins ? mockStoreOrigins.split(",") : domains.data.storeOrigins;
   const origins = opts.url ? [opts.url] : storeOrigins;
@@ -19581,7 +20301,16 @@ var installCommand = new Command("install").description("Check Apex storefront i
         });
         continue;
       }
-      if (error instanceof UrlPolicyError) fail(this, error.message, EXIT_CODES.validation);
+      if (error instanceof UrlPolicyError) {
+        const boundHosts = [...allowedHosts].sort();
+        const unbound = error.message.includes("host is not bound to this shop");
+        fail(
+          this,
+          unbound ? `${error.message} (shop ${shopId} is bound to: ${boundHosts.join(", ")})` : error.message,
+          EXIT_CODES.validation,
+          unbound ? { code: "url_not_bound", field: "url", shop_id: shopId, bound_hosts: boundHosts } : { field: "url" }
+        );
+      }
       if (error instanceof BodyDecodeError) {
         pages.push({
           url,
@@ -19618,10 +20347,12 @@ var installCommand = new Command("install").description("Check Apex storefront i
   );
   let tracking;
   let trackingExitCode = null;
+  let trackingApiFailure;
   try {
     const result = await verifyTracking(creds);
     if (!result.ok || !result.data) {
       trackingExitCode = classifyStatus(result.status);
+      trackingApiFailure = apiFailureOf(result);
       tracking = {
         status: "FAIL",
         message: result.error ?? "Failed to verify tracking",
@@ -19645,6 +20376,11 @@ var installCommand = new Command("install").description("Check Apex storefront i
   if (servedConfig.status !== "PASS") warnings.push(servedConfig.message);
   if (tracking.status === "WARN") warnings.push(tracking.message);
   const failed = pages.some((page) => page.status === "FAIL") || servedConfig.status === "FAIL" || tracking.status === "FAIL";
+  const failedChecks = [
+    ...pages.filter((page) => page.status === "FAIL").map((page) => ({ check: "page", url: page.url, message: page.message })),
+    ...servedConfig.status === "FAIL" ? [{ check: "served_config", url: servedConfig.url, message: servedConfig.message }] : [],
+    ...tracking.status === "FAIL" ? [{ check: "tracking", message: tracking.message }] : []
+  ];
   const data = { ok: !failed, pages, warnings, servedConfig, tracking };
   const renderReport = () => {
     printTable(
@@ -19676,12 +20412,24 @@ var installCommand = new Command("install").description("Check Apex storefront i
   };
   if (failed) {
     if (!shouldUseJson(this)) renderReport();
-    fail(
-      this,
-      "Apex install check found a definite failure",
-      trackingExitCode ?? EXIT_CODES.general,
-      data
-    );
+    if (trackingExitCode !== null)
+      fail(
+        this,
+        `Apex install check could not verify tracking: ${tracking.message}`,
+        trackingExitCode,
+        { ...data, shop_id: shopId, failed_checks: failedChecks },
+        trackingApiFailure
+      );
+    const summaries = failedChecks.map((entry) => {
+      const label = entry.check === "page" && "url" in entry ? `page ${entry.url}` : entry.check === "served_config" ? "served config" : "tracking";
+      return `${label}: ${entry.message.replace(/\.$/, "")}`;
+    });
+    fail(this, `Apex install check failed: ${summaries.join("; ")}`, EXIT_CODES.checkFailed, {
+      ...data,
+      code: "install_check_failed",
+      shop_id: shopId,
+      failed_checks: failedChecks
+    });
   }
   output(this, data, renderReport);
 }).parent;
@@ -20332,6 +21080,258 @@ var personalizationsCommand = new Command("personalizations").description("Manag
 init_source();
 var import_node_fs23 = __toESM(require("node:fs"));
 var import_node_path20 = __toESM(require("node:path"));
+
+// src/generated/exclusion-group-body.schema.json
+var exclusion_group_body_schema_default = {
+  create: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      name: {
+        type: "string",
+        minLength: 1,
+        maxLength: 120,
+        description: "Group name, 1 to 120 characters."
+      },
+      description: {
+        type: ["string", "null"]
+      },
+      members: {
+        type: "array",
+        minItems: 2,
+        description: "At least 2 distinct experiments. Use one shape per member: experiment_id with traffic_share as a fraction (0 to 1, shares total 1), or the dashboard shape experimentId with share as a percentage (0 to 100, shares total 100). Shares use 0.1 percent steps.",
+        items: {
+          oneOf: [
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experiment_id: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                traffic_share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 1
+                }
+              },
+              required: ["experiment_id", "traffic_share"]
+            },
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experimentId: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 100
+                }
+              },
+              required: ["experimentId", "share"]
+            }
+          ]
+        }
+      }
+    },
+    required: ["name", "members"]
+  },
+  update: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      name: {
+        type: "string",
+        minLength: 1,
+        maxLength: 120,
+        description: "Group name, 1 to 120 characters."
+      },
+      description: {
+        type: ["string", "null"]
+      },
+      members: {
+        type: "array",
+        minItems: 2,
+        description: "At least 2 distinct experiments. Use one shape per member: experiment_id with traffic_share as a fraction (0 to 1, shares total 1), or the dashboard shape experimentId with share as a percentage (0 to 100, shares total 100). Shares use 0.1 percent steps.",
+        items: {
+          oneOf: [
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experiment_id: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                traffic_share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 1
+                }
+              },
+              required: ["experiment_id", "traffic_share"]
+            },
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experimentId: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 100
+                }
+              },
+              required: ["experimentId", "share"]
+            }
+          ]
+        }
+      }
+    }
+  },
+  "replace-members": {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      members: {
+        type: "array",
+        minItems: 2,
+        description: "At least 2 distinct experiments. Use one shape per member: experiment_id with traffic_share as a fraction (0 to 1, shares total 1), or the dashboard shape experimentId with share as a percentage (0 to 100, shares total 100). Shares use 0.1 percent steps.",
+        items: {
+          oneOf: [
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experiment_id: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                traffic_share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 1
+                }
+              },
+              required: ["experiment_id", "traffic_share"]
+            },
+            {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                experimentId: {
+                  type: "string",
+                  format: "uuid",
+                  description: "Internal experiment UUID. Public ids and test keys are not resolved here."
+                },
+                share: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 100
+                }
+              },
+              required: ["experimentId", "share"]
+            }
+          ]
+        }
+      }
+    },
+    required: ["members"]
+  }
+};
+
+// src/commands/schema.ts
+var commandBodySchemas = /* @__PURE__ */ new WeakMap();
+function setCommandBodySchema(command, schema) {
+  commandBodySchemas.set(command, schema);
+  return command;
+}
+function optionSchema(option) {
+  return {
+    flags: option.flags,
+    ...option.argChoices ? { choices: option.argChoices } : {},
+    description: option.description,
+    required: option.required,
+    optional: option.optional,
+    mandatory: Boolean(option.mandatory),
+    variadic: option.variadic,
+    ...option.defaultValue === void 0 ? {} : { defaultValue: option.defaultValue }
+  };
+}
+function commandSchema(command) {
+  return {
+    name: command.name(),
+    aliases: command.aliases(),
+    description: command.description(),
+    usage: command.usage(),
+    arguments: command.registeredArguments.map((arg) => ({
+      name: arg.name(),
+      required: arg.required,
+      variadic: arg.variadic,
+      description: arg.description,
+      ...arg.defaultValue === void 0 ? {} : { defaultValue: arg.defaultValue }
+    })),
+    options: command.options.map(optionSchema),
+    ...commandBodySchemas.has(command) ? { body: commandBodySchemas.get(command) } : {},
+    commands: command.commands.map(commandSchema)
+  };
+}
+function createSchemaCommand(program3) {
+  return new Command("schema").description("Print the current Apex CLI command, flag, and mandatory-option schema").option("--json", "Print JSON schema").action(function action78() {
+    const schema = {
+      schemaVersion: 2,
+      contract: {
+        optionValueArity: "Options' required and optional fields describe whether the option's value is required or optional when the flag is given.",
+        mandatoryOptions: "An option's mandatory field is true only when the flag itself must be passed.",
+        requiredArguments: "An argument's required field means the positional is mandatory.",
+        body: "A command's body field is the JSON Schema of the JSON document it sends."
+      },
+      ...commandSchema(program3),
+      files: experiment_filesystem_schema_default
+    };
+    output(this, schema, () => {
+      process.stdout.write(`${JSON.stringify(schema, null, 2)}
+`);
+    });
+  });
+}
+
+// src/commands/targeting-resources.ts
+var exclusionHelp = `Body shape: {"name":"...","members":[...]} (update fields are optional)
+Members: at least 2 distinct experiments; use experiment_id + traffic_share (0 to 1, total 1) or experimentId + share (0 to 100, total 100). Shares use 0.1 percent steps.
+Find experiment ids with: apex experiments list --fields id,name
+Example: apex exclusion-groups create '{"name":"PDP tests","members":[{"experiment_id":"<id-1>","traffic_share":0.5},{"experiment_id":"<id-2>","traffic_share":0.5}]}'
+Full JSON Schema: apex schema --json (this command's body key)`;
+function withBodyHelp(command, action78) {
+  setCommandBodySchema(command, exclusion_group_body_schema_default[action78]);
+  command.addHelpText("after", `
+${exclusionHelp}
+`);
+}
+function exclusionFailureDetails(kind5, action78, status4, details) {
+  if (kind5 !== "exclusion-groups" || status4 !== 400 && status4 !== 422) return details;
+  return {
+    ...details,
+    next_steps: [
+      {
+        command: `apex exclusion-groups ${action78} --help`,
+        why: "Shows the body shape, member rules and an example; error.details.issues names each failing field."
+      }
+    ]
+  };
+}
 function body3(command, value) {
   if (!value) return {};
   const source = value.startsWith("@") ? value.slice(1) : value;
@@ -20409,7 +21409,10 @@ function targetingResourceCommand(kind5) {
       `${action78 === "create" ? "Create" : "Update"} a ${singular3}`
     );
     if (action78 === "update") command.argument("<id>");
-    command.argument("[json]", "Inline JSON, @file, or file path").option("--file <path>", "JSON body file").action(async function(...args) {
+    command.argument(
+      "[json]",
+      kind5 === "exclusion-groups" ? "Request body as inline JSON, @file, or a file path (shape below)" : "Inline JSON, @file, or file path"
+    ).option("--file <path>", "JSON body file").action(async function(...args) {
       const opts = this.opts();
       const id = action78 === "update" ? String(args[0]) : void 0;
       const value = opts.file ? `@${opts.file}` : String(args[action78 === "update" ? 1 : 0] ?? "") || void 0;
@@ -20428,10 +21431,11 @@ function targetingResourceCommand(kind5) {
           this,
           response.error ?? `Failed to ${action78}`,
           classifyStatus(response.status),
-          response.errorDetails
+          exclusionFailureDetails(kind5, action78, response.status, response.errorDetails)
         );
       output(this, response.data, () => console.log(source_default.green(`${action78}d ${singular3}`)));
     });
+    if (kind5 === "exclusion-groups") withBodyHelp(command, action78);
     root.addCommand(command);
   }
   const deleteCommand = new Command("delete").description(`Delete a ${singular3}`).argument("<id>");
@@ -20470,9 +21474,9 @@ function targetingResourceCommand(kind5) {
       output(this, response.data ?? null, () => console.log(source_default.green(`Deleted ${singular3}`)));
     })
   );
-  if (kind5 === "exclusion-groups")
+  if (kind5 === "exclusion-groups") {
     root.addCommand(
-      new Command("replace-members").description("Replace exclusion group members").argument("<id>").argument("<json>", "Inline JSON, @file, or file path").action(async function(id, value) {
+      new Command("replace-members").description("Replace exclusion group members").argument("<id>").argument("<json>", "Request body as inline JSON, @file, or a file path (shape below)").action(async function(id, value) {
         const response = await requestTargetingResource(
           requireCredentials(),
           "PUT",
@@ -20485,11 +21489,18 @@ function targetingResourceCommand(kind5) {
             this,
             response.error ?? "Failed to replace members",
             classifyStatus(response.status),
-            response.errorDetails
+            exclusionFailureDetails(
+              kind5,
+              "replace-members",
+              response.status,
+              response.errorDetails
+            )
           );
         output(this, response.data, () => console.log(source_default.green("Replaced members")));
       })
     );
+    withBodyHelp(root.commands.at(-1), "replace-members");
+  }
   return root;
 }
 var pagesCommand = targetingResourceCommand("pages");
@@ -20578,7 +21589,7 @@ var test2 = new Command("test").description("Evaluate experiment URL targeting f
 var targetingCommand = new Command("targeting").description("Test experiment targeting").addCommand(test2);
 
 // src/commands/sos.ts
-var import_node_crypto7 = require("node:crypto");
+var import_node_crypto8 = require("node:crypto");
 init_source();
 var import_node_fs24 = __toESM(require("node:fs"));
 var import_node_path21 = __toESM(require("node:path"));
@@ -20689,7 +21700,7 @@ var create4 = new Command("create").description("Create an Apex SOS ticket").opt
       const bytes = file.bytes;
       await uploadSosAttachment(grant.signed_url, file.content_type, bytes);
       attachmentPaths.push(grant.path);
-      attachmentDigests.push((0, import_node_crypto7.createHash)("sha256").update(bytes).digest("hex"));
+      attachmentDigests.push((0, import_node_crypto8.createHash)("sha256").update(bytes).digest("hex"));
     }
   }
   const description = readText(opts.description) ?? descriptionArg ?? `Apex CLI ${opts.type} SOS request${opts.loom ? ` with Loom evidence: ${opts.loom}` : "."}`;
@@ -21002,55 +22013,6 @@ var shopsCommand = new Command("shops").description("Manage organization shops")
   settings("auto-stop", "Read or update auto-stop defaults", { on: "enable", off: "disable" })
 ).addCommand(settings("testing-defaults", "Read or update testing defaults")).addCommand(settings("guardian", "Read or update guardian defaults", { on: "on", off: "off" })).addCommand(profile).addCommand(shopware);
 
-// src/commands/schema.ts
-function optionSchema(option) {
-  return {
-    flags: option.flags,
-    ...option.argChoices ? { choices: option.argChoices } : {},
-    description: option.description,
-    required: option.required,
-    optional: option.optional,
-    mandatory: Boolean(option.mandatory),
-    variadic: option.variadic,
-    ...option.defaultValue === void 0 ? {} : { defaultValue: option.defaultValue }
-  };
-}
-function commandSchema(command) {
-  return {
-    name: command.name(),
-    aliases: command.aliases(),
-    description: command.description(),
-    usage: command.usage(),
-    arguments: command.registeredArguments.map((arg) => ({
-      name: arg.name(),
-      required: arg.required,
-      variadic: arg.variadic,
-      description: arg.description,
-      ...arg.defaultValue === void 0 ? {} : { defaultValue: arg.defaultValue }
-    })),
-    options: command.options.map(optionSchema),
-    commands: command.commands.map(commandSchema)
-  };
-}
-function createSchemaCommand(program3) {
-  return new Command("schema").description("Print the current Apex CLI command, flag, and mandatory-option schema").option("--json", "Print JSON schema").action(function action78() {
-    const schema = {
-      schemaVersion: 2,
-      contract: {
-        optionValueArity: "Options' required and optional fields describe whether the option's value is required or optional when the flag is given.",
-        mandatoryOptions: "An option's mandatory field is true only when the flag itself must be passed.",
-        requiredArguments: "An argument's required field means the positional is mandatory."
-      },
-      ...commandSchema(program3),
-      files: experiment_filesystem_schema_default
-    };
-    output(this, schema, () => {
-      process.stdout.write(`${JSON.stringify(schema, null, 2)}
-`);
-    });
-  });
-}
-
 // src/lib/gtm-miner.ts
 function extractContainerReferences(html) {
   const results2 = /* @__PURE__ */ new Map();
@@ -22085,7 +23047,7 @@ async function confirm(c, force, label, retry) {
   }
   return true;
 }
-var orgCommand = new Command("org").description("Manage the current organization");
+var orgCommand = new Command("org").alias("orgs").description("Manage the current organization");
 orgCommand.command("get").action(async function() {
   await run2(this, getOrg(requireUserCredentials()), "get organization");
 });
@@ -22188,23 +23150,38 @@ orgCommand.command("remove-member").argument("<memberId>").option("-f, --force")
     return;
   await run2(this, removeOrgMember(requireUserCredentials(), id), "remove member");
 });
-var teamCommand = new Command("team").description("Manage a shop team");
-teamCommand.command("members").requiredOption("--shop <id>").action(async function(o) {
+var teamCommand = new Command("team").alias("teams").description("Manage a shop team");
+var teamShopDescription = "Shop ID; defaults to the selected shop (--shop before the subcommand, DRIP_SHOP, or apex use)";
+function teamShop(command, explicit) {
+  if (explicit) return explicit;
+  const selected2 = requireUserCredentials().resolvedContext?.shopId;
+  if (selected2) return selected2;
+  fail(
+    command,
+    "apex team needs a shop. Pass --shop <id>, or select one with apex use <org>/<shop>.",
+    3,
+    { code: "shop_context_required", retry: "apex use <org>/<shop>", flag: "--shop" }
+  );
+}
+teamCommand.command("members").option("--shop <id>", teamShopDescription).action(async function(o) {
+  o.shop = teamShop(this, o.shop);
   await run2(this, listTeamMembers(requireUserCredentials(), o.shop), "list team");
 });
-teamCommand.command("invite").argument("<email>").requiredOption("--shop <id>").addOption(
+teamCommand.command("invite").argument("<email>").option("--shop <id>", teamShopDescription).addOption(
   new Option(
     "--role <role>",
     "Role: editor (create and run tests, manage settings, invite people) or client_viewer (view tests, results and pipeline)"
   ).choices(["editor", "client_viewer"]).makeOptionMandatory()
 ).action(async function(email, o) {
+  o.shop = teamShop(this, o.shop);
   await run2(
     this,
     inviteTeam(requireUserCredentials(), email, o.shop, o.role),
     "invite team member"
   );
 });
-teamCommand.command("revoke-invite").argument("<id>").requiredOption("--shop <id>").action(async function(id, o) {
+teamCommand.command("revoke-invite").argument("<id>").option("--shop <id>", teamShopDescription).action(async function(id, o) {
+  o.shop = teamShop(this, o.shop);
   await run2(
     this,
     revokeTeamInvite(requireUserCredentials(), id, o.shop),
@@ -22216,10 +23193,12 @@ teamCommand.command("set-role").argument("<memberId>").addArgument(
     "<role>",
     "Role: editor (create and run tests, manage settings, invite people) or client_viewer (view tests, results and pipeline)"
   ).choices(["editor", "client_viewer"])
-).requiredOption("--shop <id>").action(async function(id, role, o) {
+).option("--shop <id>", teamShopDescription).action(async function(id, role, o) {
+  o.shop = teamShop(this, o.shop);
   await run2(this, setTeamMember(requireUserCredentials(), id, o.shop, role), "set role");
 });
-teamCommand.command("remove").argument("<memberId>").requiredOption("--shop <id>").option("-f, --force").action(async function(id, o) {
+teamCommand.command("remove").argument("<memberId>").option("--shop <id>", teamShopDescription).option("-f, --force").action(async function(id, o) {
+  o.shop = teamShop(this, o.shop);
   if (!await confirm(
     this,
     o.force,
@@ -22230,6 +23209,38 @@ teamCommand.command("remove").argument("<memberId>").requiredOption("--shop <id>
   await run2(this, removeTeamMember(requireUserCredentials(), id, o.shop), "remove member");
 });
 
+// src/commands/upgrade.ts
+var import_node_child_process7 = require("node:child_process");
+var upgradeCommand = new Command("upgrade").description("Install the latest Apex CLI version").option("--dry-run", "Print the install command without running it").action(function(options) {
+  if (options.dryRun) {
+    output(
+      this,
+      { command: UPGRADE_COMMAND, ran: false, exit_code: null, previous_version: CLI_VERSION },
+      () => console.log(UPGRADE_COMMAND)
+    );
+    return;
+  }
+  const npmBinary = process.env.APEX_NPM_BIN || (process.platform === "win32" ? "npm.cmd" : "npm");
+  const json = shouldUseJson(this);
+  const windows = process.platform === "win32";
+  const command = windows ? `"${npmBinary}"` : npmBinary;
+  const result = (0, import_node_child_process7.spawnSync)(command, ["install", "-g", "@drip-apex/apex-cli@latest"], {
+    stdio: json ? ["inherit", 2, 2] : "inherit",
+    shell: windows
+  });
+  if (result.error || result.status !== 0)
+    fail(this, result.error?.message || "Apex CLI upgrade failed", EXIT_CODES.general, {
+      code: "upgrade_failed",
+      next_steps: [{ command: UPGRADE_COMMAND, why: "Run the install command manually." }]
+    });
+  clearUpdateCache();
+  output(
+    this,
+    { command: UPGRADE_COMMAND, ran: true, exit_code: 0, previous_version: CLI_VERSION },
+    () => console.log("Apex CLI upgraded.")
+  );
+});
+
 // src/commands/account.ts
 function userCredentials2() {
   return requireUserCredentials();
@@ -22835,7 +23846,7 @@ var import_node_fs29 = __toESM(require("node:fs"));
 var import_node_path26 = __toESM(require("node:path"));
 
 // src/commands/landing-pages.ts
-var import_node_crypto8 = __toESM(require("node:crypto"));
+var import_node_crypto9 = __toESM(require("node:crypto"));
 var import_node_fs28 = __toESM(require("node:fs"));
 var import_node_path25 = __toESM(require("node:path"));
 function apiFailure(command, response, fallback2) {
@@ -22849,7 +23860,7 @@ function apiFailure(command, response, fallback2) {
   }
 }
 function sha256(body5) {
-  return import_node_crypto8.default.createHash("sha256").update(body5).digest("hex");
+  return import_node_crypto9.default.createHash("sha256").update(body5).digest("hex");
 }
 function markerPath(folder) {
   return import_node_path25.default.join(folder, LANDING_PAGE_CHECKOUT_MARKER);
@@ -23598,7 +24609,10 @@ function addJsonOption(command) {
     if (!command.options.some((option) => option.long === "--shop"))
       command.option("--shop <id>", "Use a shop for this invocation");
   }
-  command.exitOverride((err) => interceptCliError(err, command));
+  command.exitOverride((err) => {
+    recordCommanderExit(err, command);
+    interceptCliError(err, command);
+  });
   for (const child of command.commands) addJsonOption(child);
 }
 var program2 = new Command().name("apex").description(source_default.bold("Apex CLI") + " \u2014 A/B testing experiments from the command line").version(CLI_VERSION).showSuggestionAfterError(true).showHelpAfterError(true);
@@ -23654,7 +24668,9 @@ program2.addCommand(skillsCommand);
 program2.addCommand(adminCommand, { hidden: true });
 program2.addCommand(orgCommand);
 program2.addCommand(teamCommand);
+program2.addCommand(upgradeCommand);
 addJsonOption(program2);
+registerTelemetryProgram(program2);
 var optionTerminatorIndex = process.argv.indexOf("--");
 var optionArgv = optionTerminatorIndex === -1 ? process.argv : process.argv.slice(0, optionTerminatorIndex);
 if (optionArgv.includes("--json")) program2.setOptionValue("json", true);