@drip-apex/apex-cli 0.7.0 → 0.8.1

package/AGENTS.md

@@ -24,7 +24,6 @@ Use `apex` as the canonical command name. `drip` is a compatibility alias.
   "did you mean" hints — those are stderr diagnostics for humans; machine
   callers resolve names via `apex schema --json`.
 
-
 ## Zero-Experiment Shop Bootstrap
 
 CLI-only bootstrap is supported for a fresh shop before any experiments exist.
@@ -71,7 +70,6 @@ the first writes: `apex experiments create`, `apex goals create`,
 - Do not bypass the variation artifact persistence path with direct API writes.
 - Keep generated evidence outside `qa.json`; attach it through QA commands.
 
-
 ## Project code
 
 ```sh
@@ -106,3 +104,14 @@ and `countingType` equal `delivery_type` and `counting_type` from
 `apex experiments get --json`. Omitting or setting `countingType` to null preserves
 the stored value. Classification edits invalidate QA approval; paused and running
 experiments reject these metadata changes.
+
+Experiment references accept an ID, slug, or test key (for example `BIO-085`). Test keys resolve within the selected shop; use `--shop <shop-id>` to change it. Bare lowercase references remain slugs.
+
+Filesystem apply preserves authored local bytes by default. Use
+`apex experiments apply <folder> --sync` to refresh them from stored server bytes.
+The receipt's `files` contains SHA-256 digests for every pull path; `synced` reports
+whether a full refresh succeeded. Server-owned QA and launch files are healed.
+Create/get return `dashboard_url`; apply returns `dashboardUrl`. These links
+switch the signed-in dashboard user's active shop before opening the experiment.
+
+Filesystem apply caches uploaded asset URLs by byte SHA-256 in `.apex/experiment-filesystem.json`, so unchanged images reuse their URL across applies without rewriting authored files.

package/README.md

@@ -268,7 +268,6 @@ Read the CLI reference on the docs site:
 
 Maintainers: see the [CLI release runbook](../../docs/cli-releases.md).
 
-
 ## Project code
 
 ```sh
@@ -303,3 +302,14 @@ and `countingType` equal `delivery_type` and `counting_type` from
 `apex experiments get --json`. Omitting or setting `countingType` to null preserves
 the stored value. Classification edits invalidate QA approval; paused and running
 experiments reject these metadata changes.
+
+Experiment references accept an ID, slug, or test key (for example `BIO-085`). Test keys resolve within the selected shop; use `--shop <shop-id>` to change it. Bare lowercase references remain slugs.
+
+Filesystem apply preserves authored local bytes by default. Use
+`apex experiments apply <folder> --sync` to refresh them from stored server bytes.
+The receipt's `files` contains SHA-256 digests for every pull path; `synced` reports
+whether a full refresh succeeded. Server-owned QA and launch files are healed.
+Create/get return `dashboard_url`; apply returns `dashboardUrl`. These links
+switch the signed-in dashboard user's active shop before opening the experiment.
+
+Filesystem apply caches uploaded asset URLs by byte SHA-256 in `.apex/experiment-filesystem.json`, so unchanged images reuse their URL across applies without rewriting authored files.

package/dist/cli.js

@@ -7112,7 +7112,7 @@ var import_node_os3 = __toESM(require("node:os"));
 // package.json
 var package_default = {
   name: "@drip-apex/apex-cli",
-  version: "0.7.0",
+  version: "0.8.1",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -7310,6 +7310,15 @@ function classifyApiError(status2, details) {
 function confirmationRequired(command, message, retry) {
   return fail(command, message, EXIT_CODES.confirmationRequired, { retry });
 }
+var liveSpinners = /* @__PURE__ */ new Set();
+var exitFallback;
+function drainAndExit(code) {
+  for (const spinner of liveSpinners) spinner.stop();
+  process.exitCode = code;
+  if (exitFallback) clearTimeout(exitFallback);
+  exitFallback = setTimeout(() => process.exit(code), 500);
+  exitFallback.unref();
+}
 async function createSpinner(message) {
   if (jsonMode || !process.stderr.isTTY) {
     return {
@@ -7328,7 +7337,20 @@ async function createSpinner(message) {
     };
   }
   const { default: ora2 } = await Promise.resolve().then(() => (init_ora(), ora_exports));
-  return ora2(message).start();
+  const spinner = ora2(message);
+  const start = spinner.start.bind(spinner);
+  spinner.start = (...args) => {
+    liveSpinners.add(spinner);
+    return start(...args);
+  };
+  for (const method of ["stop", "succeed", "fail"]) {
+    const original = spinner[method].bind(spinner);
+    spinner[method] = (...args) => {
+      liveSpinners.delete(spinner);
+      return original(...args);
+    };
+  }
+  return spinner.start();
 }
 async function maybeCheckForUpdate() {
   if (!process.stderr.isTTY || process.env.APEX_NO_UPDATE_CHECK === "1" || CLI_VERSION === "unknown")
@@ -7350,7 +7372,8 @@ async function maybeCheckForUpdate() {
 async function handleCliError(err, command) {
   if (err && typeof err === "object" && "exitCode" in err && err.exitCode === 0) {
     flushFallbackEnvelope();
-    process.exit(0);
+    drainAndExit(0);
+    return;
   }
   const commanderExitCode = err && typeof err === "object" && "exitCode" in err && typeof err.exitCode === "number" ? err.exitCode : null;
   const cliError = err instanceof CliError ? err : new CliError(
@@ -7371,7 +7394,7 @@ async function handleCliError(err, command) {
 `);
     }
   }
-  process.exit(cliError.exitCode);
+  drainAndExit(cliError.exitCode);
 }
 
 // ../api-client/src/credentials.ts
@@ -8900,6 +8923,15 @@ var evidenceKinds = [
   "readiness"
 ];
 
+// src/lib/dashboard-url.ts
+function buildDashboardUrl(baseUrl, shopId, experimentId) {
+  if (!shopId) return null;
+  const url = new URL("/api/shops/switch", baseUrl);
+  url.searchParams.set("shopId", shopId);
+  url.searchParams.set("redirect", "/experiments/" + experimentId);
+  return url.toString();
+}
+
 // ../api-client/src/qa-preview-url.ts
 var FORCE_ALIAS_PARAM_NAMES = ["drip_experiment_id", "drip_experiment", "drip_variation_id", "drip_variation"];
 function applyQaPreviewParams(url, params) {
@@ -8937,6 +8969,22 @@ function buildQaPreviewUrl2(storeUrl, experimentId, variationId) {
   return url;
 }
 
+// src/lib/device-label.ts
+function deviceLabel(targeting) {
+  if (!targeting || typeof targeting !== "object") return void 0;
+  const device = targeting.deviceType;
+  if (device === "desktop") return "Desktop only";
+  if (device === "mobile") return "Mobile only";
+  if (device === "tablet") return "Tablet only";
+  return void 0;
+}
+
+// src/lib/test-key.ts
+var TEST_KEY_RE = /^([A-Z0-9]{2,8})-(\d+)$/;
+function isTestKeyReference(value) {
+  return value === value.toUpperCase() && TEST_KEY_RE.test(value.toUpperCase());
+}
+
 // src/lib/effective-page-targeting.ts
 var ALL_PAGES_LABEL = "All pages";
 var CHECKOUT_LABEL = "Checkout";
@@ -9023,6 +9071,20 @@ function classifyIdeaReference(reference) {
   return { kind: "invalid", value: trimmed };
 }
 
+// ../api-client/src/experiment-create.ts
+function deriveStoreUrl(patterns) {
+  for (const pattern of patterns) {
+    const trimmed = pattern.trim();
+    if (trimmed.includes("*")) continue;
+    try {
+      const url = new URL(trimmed);
+      if (url.protocol === "http:" || url.protocol === "https:") return trimmed;
+    } catch {
+    }
+  }
+  return null;
+}
+
 // src/lib/asset-upload.ts
 var import_node_crypto3 = __toESM(require("node:crypto"));
 var import_node_fs6 = __toESM(require("node:fs"));
@@ -9102,6 +9164,7 @@ function createAssetReferenceRewriter(options) {
     let pending = uploadsByHash.get(hash);
     if (!pending) {
       pending = options.upload(file).then((asset) => {
+        if (asset === null) return null;
         if (!asset.id) throw new Error(`Asset upload for ${file.name} returned no ID.`);
         const url = deliveryUrl(options.baseUrl, asset);
         options.onUpload?.({ name: file.name, url, source });
@@ -9130,7 +9193,7 @@ function createAssetReferenceRewriter(options) {
       const hash = contentHash(bytes);
       const name = `inline-${hash.slice(0, 12)}${extensionForMimeType(mimeType)}`;
       const url = await uploadOnce({ name, bytes, type: mimeType }, "inline");
-      rewritten = rewritten.split(uri).join(url);
+      if (url !== null) rewritten = rewritten.split(uri).join(url);
     }
     const localAssetUrl = async (reference) => {
       if (reference.startsWith("/") || reference.startsWith("data:") || reference.includes("://")) {
@@ -9217,16 +9280,22 @@ function formatDate(iso) {
     year: "numeric"
   });
 }
-function printExperiment(exp) {
+function printExperiment(exp, dashboardUrl = null) {
   console.log();
   console.log(source_default.bold(exp.name));
+  if (dashboardUrl) console.log(`  Dashboard: ${dashboardUrl}`);
   console.log(`  ID:      ${source_default.dim(exp.id)}`);
   if (exp.slug) console.log(`  Slug:    ${source_default.cyan(exp.slug)}`);
   console.log(`  Status:  ${statusBadge(exp.status)}`);
   console.log(`  Classification: ${exp.counting_type}`);
   console.log(`  Traffic: ${(exp.traffic_allocation * 100).toFixed(0)}%`);
+  console.log(`  QA approved: ${exp.qa_approved_at ?? "none"}`);
+  console.log(`  Scheduled: ${exp.scheduled_start_at ?? "none"}`);
+  console.log(`  Started: ${exp.started_at ?? "none"}`);
   if (exp.targeting !== void 0) {
     console.log(`  Targeting: ${effectivePageTargetingLabel(exp.targeting)}`);
+    const device = deviceLabel(exp.targeting);
+    if (device) console.log(`  Device: ${device}`);
   }
   console.log(`  Created: ${formatDate(exp.created_at)}`);
   if (exp.linked_idea) {
@@ -9450,21 +9519,26 @@ async function rewriteExperimentFilesystemAssets(input) {
     baseUrl: input.baseUrl,
     enabled: input.enabled,
     upload: async (file) => {
+      const hash = import_node_crypto4.default.createHash("sha256").update(file.bytes).digest("hex");
+      const cached = input.assets[hash];
+      if (cached) return cached;
+      if (input.upload === null) return null;
       const response = await input.upload(input.credentials, [file]);
       const asset = response.data?.assets?.[0];
       if (!response.ok || !asset?.id) {
         throw new Error(response.error ?? `Failed to upload ${file.name}.`);
       }
-      return {
+      const uploaded = {
         id: asset.id,
-        url: typeof asset.url === "string" ? asset.url : void 0,
-        deliveryUrl: typeof asset.deliveryUrl === "string" ? asset.deliveryUrl : void 0,
-        delivery_url: typeof asset.delivery_url === "string" ? asset.delivery_url : void 0
+        url: typeof asset.url === "string" ? asset.url : `${new URL(input.baseUrl).origin}/api/assets/${encodeURIComponent(asset.id)}/file`,
+        deliveryUrl: typeof asset.deliveryUrl === "string" ? asset.deliveryUrl : typeof asset.delivery_url === "string" ? asset.delivery_url : void 0
       };
-    },
-    onUpload: ({ name, url }) => {
-      process.stderr.write(`Uploaded asset ${name} -> ${url}
-`);
+      input.assets[hash] = uploaded;
+      process.stderr.write(
+        `Uploaded asset ${file.name} -> ${uploaded.deliveryUrl ?? uploaded.url}
+`
+      );
+      return uploaded;
     }
   });
   return Promise.all(
@@ -9501,6 +9575,9 @@ function printFilesystemPlan(plan) {
     console.log(source_default.dim("  No changes."));
   } else {
     plan.changes.forEach((change) => {
+      if (change.entity === "experiment.targeting" && Array.isArray(change.detail?.changedKeys)) {
+        console.log(`  Changed keys: ${change.detail.changedKeys.join(", ")}`);
+      }
       const pathLabel = change.path ? source_default.dim(` ${change.path}`) : "";
       const qa3 = change.invalidatesQa ? source_default.yellow(" invalidates QA") : "";
       console.log(
@@ -9519,11 +9596,21 @@ function blockingIssueSummary(issues) {
   return `Experiment filesystem plan has errors. ${issues[0].message}${remaining ? ` and ${remaining} more` : ""}`;
 }
 async function getQaPreviewUrls(creds, experimentId) {
+  const fallbackDashboardUrl = buildDashboardUrl(
+    creds.baseUrl,
+    creds.resolvedContext?.shopId,
+    experimentId
+  );
   try {
     const res = await getExperiment(creds, experimentId);
+    const dashboardUrl = buildDashboardUrl(
+      creds.baseUrl,
+      res.data?.shop_id ?? creds.resolvedContext?.shopId,
+      experimentId
+    );
     const storeUrl = res.data?.store_url;
     if (!res.ok || !res.data || !storeUrl) {
-      return { previewUrls: [], unavailable: true };
+      return { previewUrls: [], unavailable: true, dashboardUrl };
     }
     const experiment = res.data;
     const previewUrls = (experiment.variations ?? []).filter((variation) => !variation.is_control).map((variation) => ({
@@ -9531,9 +9618,9 @@ async function getQaPreviewUrls(creds, experimentId) {
       variationName: variation.name,
       url: buildQaPreviewUrl2(storeUrl, experiment.id, variation.id).toString()
     }));
-    return { previewUrls, unavailable: false };
+    return { previewUrls, unavailable: false, dashboardUrl };
   } catch {
-    return { previewUrls: [], unavailable: true };
+    return { previewUrls: [], unavailable: true, dashboardUrl: fallbackDashboardUrl };
   }
 }
 function printQaPreviewUrls(experimentId, result) {
@@ -9652,13 +9739,15 @@ async function resolveExperimentForFilesystemOrId(value) {
   return { experimentId: exp.id, folder: null, label: exp.name };
 }
 async function refreshExperimentFilesystemFolderIfNeeded(creds, folder, experimentId) {
-  if (!folder) return;
+  if (!folder) return false;
   try {
     const refreshed = await getExperimentFilesystem(creds, experimentId);
     if (refreshed.ok && refreshed.data) {
+      const assets = tryReadFilesystemSession(folder)?.assets;
       writeExperimentFilesystemFiles(folder, refreshed.data.files);
       writeFilesystemSession(folder, {
         schemaVersion: 1,
+        ...assets ? { assets } : {},
         baseUrl: creds.baseUrl,
         experimentId,
         pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -9666,11 +9755,13 @@ async function refreshExperimentFilesystemFolderIfNeeded(creds, folder, experime
           refreshed.data.files.map((file) => [file.path, { sha256: file.sha256 }])
         )
       });
+      return true;
     }
   } catch {
   }
+  return false;
 }
-async function refreshServerOwnedFilesIfNeeded(creds, folder, experimentId) {
+async function refreshServerOwnedFilesIfNeeded(creds, folder, experimentId, updateManifest = true) {
   if (!folder) return;
   try {
     const refreshed = await getExperimentFilesystem(creds, experimentId);
@@ -9681,23 +9772,25 @@ async function refreshServerOwnedFilesIfNeeded(creds, folder, experimentId) {
     if (serverOwned.length === 0) return;
     const session = readFilesystemSession(folder);
     writeExperimentFilesystemFiles(folder, serverOwned);
-    writeFilesystemSession(folder, {
-      ...session,
-      files: {
-        ...session.files,
-        ...Object.fromEntries(serverOwned.map((file) => [file.path, { sha256: file.sha256 }]))
-      }
-    });
+    if (updateManifest)
+      writeFilesystemSession(folder, {
+        ...session,
+        files: {
+          ...session.files,
+          ...Object.fromEntries(serverOwned.map((file) => [file.path, { sha256: file.sha256 }]))
+        }
+      });
   } catch {
   }
 }
+var EXPERIMENT_REFERENCE_DESCRIPTION = "Experiment ID, slug, or test key (for example BIO-085)";
 async function resolveExperiment(idOrSlug) {
   const creds = requireCredentials();
-  if (/^[0-9a-f-]{36}$/i.test(idOrSlug)) {
+  if (/^[0-9a-f-]{36}$/i.test(idOrSlug) || /^[1-9][0-9]{9}$/.test(idOrSlug) || isTestKeyReference(idOrSlug)) {
     const res2 = await getExperiment(creds, idOrSlug);
     if (res2.ok) return res2.data;
     throw new CliError(
-      res2.error ?? `Experiment "${idOrSlug}" not found`,
+      res2.status === 404 && isTestKeyReference(idOrSlug) ? `Experiment "${idOrSlug}" not found in selected shop ${creds.resolvedContext?.shopId ?? "(API key shop)"}. Test keys resolve within the selected shop; use --shop <shop-id> to change it.` : res2.error ?? `Experiment "${idOrSlug}" not found`,
       classifyStatus(res2.status),
       res2.errorDetails
     );
@@ -9751,16 +9844,28 @@ var list = new Command("list").alias("ls").description("List experiments (archiv
     }
   });
 });
-var get = new Command("get").description("Get experiment details by ID or slug").argument("<id-or-slug>", "Experiment ID or slug").action(async function action4(idOrSlug) {
+var get = new Command("get").description(
+  "Get experiment details by ID or slug. JSON readback always carries started_at, scheduled_start_at and qa_approved_at as ISO-8601 UTC timestamps or null (all null on a fresh draft)."
+).argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action4(idOrSlug) {
   const spinner = await createSpinner("Fetching experiment...");
   const exp = await resolveExperiment(idOrSlug);
   spinner?.stop();
   if (!exp) {
     fail(this, `Experiment "${idOrSlug}" not found.`, EXIT_CODES.validation);
   }
-  output(this, { experiment: exp }, () => printExperiment(exp));
+  const creds = requireCredentials();
+  const dashboardUrl = buildDashboardUrl(
+    creds.baseUrl,
+    exp.shop_id ?? creds.resolvedContext?.shopId,
+    exp.id
+  );
+  output(
+    this,
+    { experiment: exp, dashboard_url: dashboardUrl },
+    () => printExperiment(exp, dashboardUrl)
+  );
 });
-var attachIdea = new Command("attach-idea").description("Attach an experiment to an idea").argument("<experiment>", "Experiment ID or slug").requiredOption("--idea <key>", "Idea UUID or Apex backlog key").option("--follow-up", "Attach as a follow-up test").action(async function action5(experimentRef, opts) {
+var attachIdea = new Command("attach-idea").description("Attach an experiment to an idea").argument("<experiment>", EXPERIMENT_REFERENCE_DESCRIPTION).requiredOption("--idea <key>", "Idea UUID or Apex backlog key").option("--follow-up", "Attach as a follow-up test").action(async function action5(experimentRef, opts) {
   const experiment = await resolveExperiment(experimentRef);
   if (!experiment) fail(this, `Experiment "${experimentRef}" not found.`, EXIT_CODES.validation);
   const classified = classifyIdeaReference(opts.idea);
@@ -9780,7 +9885,7 @@ var attachIdea = new Command("attach-idea").description("Attach an experiment to
     );
   output(this, res.data, () => printSuccess("Idea attached."));
 });
-var detachIdea = new Command("detach-idea").description("Detach an experiment from its idea").argument("<experiment>", "Experiment ID or slug").action(async function action6(experimentRef) {
+var detachIdea = new Command("detach-idea").description("Detach an experiment from its idea").argument("<experiment>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action6(experimentRef) {
   const experiment = await resolveExperiment(experimentRef);
   if (!experiment) fail(this, `Experiment "${experimentRef}" not found.`, EXIT_CODES.validation);
   const res = await detachExperimentIdea(requireCredentials(), experiment.id);
@@ -9793,7 +9898,7 @@ var detachIdea = new Command("detach-idea").description("Detach an experiment fr
     );
   output(this, res.data, () => printSuccess("Idea detached."));
 });
-var results = new Command("results").description("Read experiment results and timeseries by ID or slug").argument("<id-or-slug>", "Experiment ID or slug").option("--currency <code>", "Currency code for revenue formatting").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").action(async function action7(idOrSlug, opts) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Fetching experiment results...");
   try {
@@ -9843,7 +9948,7 @@ var DAY_NAMES = {
 var countingTypes = ["standard", "setup_test", "aa_test", "non_program"];
 var update = new Command("update").description("Update an experiment").addOption(
   new Option("--counting-type <type>", "Draft experiment classification").choices(countingTypes)
-).argument("<id-or-slug>", "Experiment ID or slug").option("--results-weekdays <days>", "Comma-separated weekdays").option("--results-timezone <timezone>", "IANA timezone for the results window").option("--clear-results-weekdays", "Clear the results weekday window").action(async function action8(reference, opts) {
+).argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).option("--results-weekdays <days>", "Comma-separated weekdays").option("--results-timezone <timezone>", "IANA timezone for the results window").option("--clear-results-weekdays", "Clear the results weekday window").action(async function action8(reference, opts) {
   if (opts.clearResultsWeekdays && (opts.resultsWeekdays || opts.resultsTimezone)) {
     fail(
       this,
@@ -9896,32 +10001,240 @@ function parseHttpDestination(value) {
   }
   return trimmed;
 }
-function sourceStoreUrl(sourceRules) {
-  for (const rule of sourceRules) {
-    if (rule.includes("*")) continue;
-    try {
-      const url = new URL(rule);
-      if (url.protocol === "http:" || url.protocol === "https:") {
-        return rule;
-      }
-    } catch {
+function readCreateJson(command, reference) {
+  const file = reference.startsWith("@") ? reference.slice(1) : reference;
+  try {
+    const parsed = JSON.parse(import_node_fs7.default.readFileSync(import_node_path5.default.resolve(process.cwd(), file), "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      throw new Error("expected an object");
+    return parsed;
+  } catch (error) {
+    fail(
+      command,
+      `Invalid audience JSON ${reference}: ${error instanceof Error ? error.message : String(error)}`,
+      EXIT_CODES.validation
+    );
+  }
+}
+var GOAL_TYPES = ["click", "pageview", "custom", "revenue"];
+var GOAL_MEASUREMENTS = ["conversion", "value"];
+var GOAL_VALUE_UNITS = ["currency", "number", "duration_seconds", "percent"];
+var INLINE_GOAL_FIELDS = [
+  "name",
+  "type",
+  "measurement",
+  "value_property",
+  "value_unit",
+  "selector",
+  "text_match",
+  "url_pattern",
+  "page_id",
+  "event_name",
+  "count_once"
+];
+var GOAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var GOAL_EVENT_NAME = /^[a-zA-Z0-9_.:-]{1,120}$/;
+var GOAL_VALUE_PROPERTY = /^[A-Za-z0-9_.-]{1,120}$/;
+function normalizeNewGoalKey(key) {
+  const normalized = key.trim().toLowerCase().replace(/-/g, "_");
+  return normalized === "page" ? "page_id" : normalized;
+}
+function validateNewGoal(command, value, body5) {
+  const invalid = (reason) => fail(command, `Invalid --goal "new:${value}"; ${reason}`, EXIT_CODES.validation);
+  const text = (field) => {
+    const raw = body5[field];
+    return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+  };
+  for (const key of Object.keys(body5)) {
+    if (INLINE_GOAL_FIELDS.includes(key)) continue;
+    invalid(
+      key === "capture" || key === "filter" ? `${key} is not expressible inline; create the goal with \`apex goals create\` and pass its id` : `unknown field "${key}"; inline fields are ${INLINE_GOAL_FIELDS.join(", ")}`
+    );
+  }
+  const type = text("type");
+  const name = text("name");
+  if (!type || !name) invalid("type and name are required");
+  if (!GOAL_TYPES.includes(type)) invalid(`type must be one of ${GOAL_TYPES.join(", ")}`);
+  if (name.length > 255) invalid("name must be 255 characters or fewer");
+  const measurement = text("measurement") ?? "conversion";
+  if (!GOAL_MEASUREMENTS.includes(measurement))
+    invalid(`measurement must be one of ${GOAL_MEASUREMENTS.join(", ")}`);
+  if (body5.count_once !== void 0) {
+    const flag = String(body5.count_once).toLowerCase();
+    if (flag !== "true" && flag !== "false") invalid("count-once must be true or false");
+    body5.count_once = flag === "true";
+  }
+  if (type === "click" && !text("selector") && !text("text_match"))
+    invalid("click goals need selector=<css> or text-match=<text>");
+  if (type === "pageview" && !text("page_id") && !text("url_pattern"))
+    invalid("pageview goals need page=<page-id> or url-pattern=<pattern>");
+  if (type === "custom" && !text("event_name")) invalid("custom goals need event-name=<name>");
+  const eventName = text("event_name");
+  if (eventName && !GOAL_EVENT_NAME.test(eventName))
+    invalid("event-name must be 1-120 letters, numbers, dots, colons, underscores, or hyphens");
+  if ((type === "custom" || type === "revenue") && text("page_id"))
+    invalid(`page is not supported for ${type} goals`);
+  const pageId = text("page_id");
+  if (pageId && !GOAL_UUID.test(pageId))
+    invalid("page must be a page UUID (list them with `apex pages list`)");
+  const valueProperty = text("value_property");
+  const valueUnit = text("value_unit");
+  if (measurement !== "value" && (valueProperty || valueUnit))
+    invalid("value-property and value-unit need measurement=value");
+  if (type === "revenue" && valueProperty)
+    invalid("revenue goals read the order revenue; value-property is not supported");
+  if (valueProperty && !GOAL_VALUE_PROPERTY.test(valueProperty))
+    invalid("value-property must be 1-120 letters, numbers, dots, underscores, or hyphens");
+  if (valueUnit && !GOAL_VALUE_UNITS.includes(valueUnit))
+    invalid(`value-unit must be one of ${GOAL_VALUE_UNITS.join(", ")}`);
+}
+function parseNewGoal(command, value) {
+  const body5 = {};
+  for (const field of value.split(",")) {
+    const separator = field.indexOf("=");
+    if (separator <= 0 || separator === field.length - 1) {
+      fail(
+        command,
+        `Invalid --goal "new:${value}"; use new:type=<type>,selector=<css>,name=<text>`,
+        EXIT_CODES.validation
+      );
     }
+    body5[normalizeNewGoalKey(field.slice(0, separator))] = field.slice(separator + 1).trim();
+  }
+  validateNewGoal(command, value, body5);
+  return body5;
+}
+async function resolveNewGoalPages(command, creds, goals, interactive) {
+  const pending = goals.filter((goal) => goal.body.type === "click" && !goal.body.page_id);
+  if (pending.length === 0) return;
+  if (!interactive) {
+    fail(
+      command,
+      `Invalid --goal "${pending[0].flagValue}"; click goals are page-scoped in v1 \u2014 add page=<page-id> (see \`apex pages list\`)`,
+      EXIT_CODES.validation
+    );
+  }
+  const listed = await requestTargetingResource(creds, "GET", "pages", void 0, void 0, 100);
+  if (!listed.ok || !listed.data)
+    fail(command, listed.error ?? "Failed to list pages", classifyStatus(listed.status));
+  const rows = listed.data.data;
+  if (rows.length === 0)
+    fail(
+      command,
+      "Click goals are page-scoped in v1 and this shop has no pages yet; create one with `apex pages create`.",
+      EXIT_CODES.validation
+    );
+  printChoices("Pages (enter id/number)", rows);
+  for (const goal of pending) {
+    const answer = await askCreate(`Page for click goal "${String(goal.body.name)}": `);
+    if (!answer)
+      fail(
+        command,
+        `Invalid --goal "${goal.flagValue}"; click goals need a page`,
+        EXIT_CODES.validation
+      );
+    const chosen = /^\d+$/.test(answer) && rows[Number(answer) - 1] ? rows[Number(answer) - 1].id : answer;
+    if (!GOAL_UUID.test(chosen))
+      fail(
+        command,
+        `Invalid page "${chosen}"; pick a listed number or a page UUID`,
+        EXIT_CODES.validation
+      );
+    goal.body.page_id = chosen;
   }
-  return null;
 }
-var create = new Command("create").description("Create a new experiment").addOption(
+async function askCreate(question) {
+  const readline3 = await import("node:readline");
+  const rl = readline3.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(
+    (resolve2) => rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer.trim());
+    })
+  );
+}
+function printChoices(kind5, rows) {
+  process.stderr.write(
+    `${kind5}:
+${rows.map((row, index) => `  ${index + 1}. ${row.name} (${row.id})`).join("\n")}
+`
+  );
+}
+var create = new Command("create").description(
+  "Create a complete experiment with page targeting, audiences, goals, and an optional QA preview URL. JSON readback always carries started_at, scheduled_start_at and qa_approved_at as ISO-8601 UTC timestamps or null (all null on a fresh draft)."
+).addOption(
   new Option("--counting-type <type>", "Experiment classification").choices(countingTypes).default("standard")
-).requiredOption("--name <name>", "Experiment name").option("--slug <slug>", "URL-safe slug for GitOps").option("--description <desc>", "Description").option("--type <type>", "Experiment type: mutation or redirect", "mutation").option(
+).option("--name <name>", "Experiment name").option("--slug <slug>", "URL-safe slug for GitOps").option("--description <desc>", "Description").option("--type <type>", "Experiment type: mutation or redirect", "mutation").option(
   "--source-url <pattern>",
   "Positive source URL rule (repeatable; accepts exact URLs, paths, or wildcards)",
   collectCreateOption,
   []
+).option(
+  "--page-url <pattern>",
+  "Page URL targeting pattern (repeatable)",
+  collectCreateOption,
+  []
+).option(
+  "--audience <segment-id|new:@file.json>",
+  "Audience segment (repeatable)",
+  collectCreateOption,
+  []
+).option(
+  "--goal <goal-id|new:fields>",
+  "Goal id or new:type=...,selector=...,name=... (repeatable)",
+  collectCreateOption,
+  []
 ).option(
   "--destination <url>",
   "Redirect treatment destination (repeatable; creates one treatment per URL)",
   collectCreateOption,
   []
-).option("--traffic <pct>", "Traffic allocation (0-100)", "100").option("--idea <id>", "Idea UUID or Apex backlog key").option("--backlog-item <id>", "Alias for --idea").action(async function action9(opts) {
+).option("--traffic <pct>", "Traffic allocation (0-100)", "100").option("--idea <id>", "Idea UUID or Apex backlog key").option("--backlog-item <id>", "Alias for --idea").option("--preview", "Print a QA preview URL for the first treatment").option("--yes", "Do not prompt for missing values").action(async function action9(opts) {
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !opts.yes);
+  if (!opts.name && interactive) opts.name = await askCreate("Experiment name: ");
+  if (!opts.name?.trim()) fail(this, "Missing required value: --name", EXIT_CODES.validation);
+  if (opts.pageUrl.length === 0 && opts.sourceUrl.length === 0 && interactive) {
+    const answer = await askCreate("Page URL (--page-url): ");
+    if (answer) opts.pageUrl.push(answer);
+  }
+  const creds = requireCredentials();
+  if (opts.audience.length === 0 && interactive) {
+    const listed = await requestTargetingResource(
+      creds,
+      "GET",
+      "segments",
+      void 0,
+      void 0,
+      100
+    );
+    if (!listed.ok || !listed.data)
+      fail(this, listed.error ?? "Failed to list segments", classifyStatus(listed.status));
+    const rows = listed.data.data;
+    printChoices("Audiences (enter id/number, or none)", rows);
+    const answer = await askCreate("Audience: ");
+    if (answer && answer.toLowerCase() !== "none")
+      opts.audience.push(
+        /^\d+$/.test(answer) && rows[Number(answer) - 1] ? rows[Number(answer) - 1].id : answer
+      );
+  }
+  if (opts.goal.length === 0 && interactive) {
+    const listed = await listGoals(creds, { limit: 100 });
+    if (!listed.ok || !listed.data)
+      fail(this, listed.error ?? "Failed to list goals", classifyStatus(listed.status));
+    const rows = listed.data.data;
+    printChoices("Goals (enter ids/numbers separated by commas, or none)", rows);
+    const answer = await askCreate("Goals: ");
+    if (answer && answer.toLowerCase() !== "none")
+      opts.goal.push(
+        ...answer.split(",").map((part) => part.trim()).filter(Boolean).map(
+          (part) => /^\d+$/.test(part) && rows[Number(part) - 1] ? rows[Number(part) - 1].id : part
+        )
+      );
+  }
+  if (this.getOptionValueSource("traffic") === "default" && interactive) {
+    const answer = await askCreate("Traffic percentage [100]: ");
+    if (answer) opts.traffic = answer;
+  }
   if (opts.type !== "mutation" && opts.type !== "redirect") {
     fail(this, "--type must be mutation or redirect", EXIT_CODES.validation);
   }
@@ -9929,9 +10242,9 @@ var create = new Command("create").description("Create a new experiment").addOpt
   if (!Number.isFinite(traffic) || traffic < 0 || traffic > 100) {
     fail(this, "--traffic must be a number from 0 to 100", EXIT_CODES.validation);
   }
-  const sourceRules = opts.sourceUrl.map((value) => value.trim());
+  const sourceRules = [...opts.sourceUrl, ...opts.pageUrl].map((value) => value.trim());
   if (sourceRules.some((value) => value.length === 0)) {
-    fail(this, "--source-url cannot be empty", EXIT_CODES.validation);
+    fail(this, "--source-url/--page-url cannot be empty", EXIT_CODES.validation);
   }
   if (opts.type !== "redirect" && opts.destination.length > 0) {
     fail(this, "--destination is only valid with --type redirect", EXIT_CODES.validation);
@@ -9951,8 +10264,15 @@ var create = new Command("create").description("Create a new experiment").addOpt
     );
   }
   const destinations = opts.destination.map(parseHttpDestination);
+  const previewStoreUrl = deriveStoreUrl(sourceRules);
+  if (opts.preview && !previewStoreUrl) {
+    fail(
+      this,
+      "--preview needs an absolute page URL: pass --page-url https://store.example/path (wildcard and path-only rules cannot seed the preview link), or create the experiment without --preview and run `apex preview <id> --store-url <url>`",
+      EXIT_CODES.validation
+    );
+  }
   const armWeight = destinations.length > 0 ? 1 / (destinations.length + 1) : null;
-  const creds = requireCredentials();
   let backlogItemId;
   let ideaKey;
   if (opts.idea !== void 0 && opts.backlogItem !== void 0 && opts.idea.trim().toUpperCase() !== opts.backlogItem.trim().toUpperCase()) {
@@ -9973,47 +10293,151 @@ var create = new Command("create").description("Create a new experiment").addOpt
       fail(this, "--idea must be a UUID or Apex backlog key", EXIT_CODES.validation);
     }
   }
+  const newGoals = /* @__PURE__ */ new Map();
+  for (const [index, goal] of opts.goal.entries()) {
+    if (goal.startsWith("new:")) newGoals.set(index, parseNewGoal(this, goal.slice(4)));
+  }
+  await resolveNewGoalPages(
+    this,
+    creds,
+    [...newGoals].map(([index, body5]) => ({ flagValue: opts.goal[index], body: body5 })),
+    interactive
+  );
+  const createdSegments = [];
+  const createdGoals = [];
+  const segmentIds = [];
+  const goalIds = [];
+  const partial = () => [
+    ...createdSegments.map((item) => `segment ${item.id}`),
+    ...createdGoals.map((item) => `goal ${item.id}`)
+  ];
+  for (const audience of opts.audience) {
+    if (!audience.startsWith("new:")) {
+      segmentIds.push(audience);
+      continue;
+    }
+    const reference = audience.slice(4);
+    if (!reference.startsWith("@"))
+      fail(
+        this,
+        `Invalid --audience "${audience}"; new audiences use new:@file.json`,
+        EXIT_CODES.validation
+      );
+    const response = await requestTargetingResource(
+      creds,
+      "POST",
+      "segments",
+      void 0,
+      readCreateJson(this, reference)
+    );
+    if (!response.ok || !response.data)
+      fail(
+        this,
+        `${response.error ?? "Failed to create audience"}${partial().length ? `; already created: ${partial().join(", ")}` : ""}`,
+        classifyStatus(response.status)
+      );
+    const segment = response.data;
+    createdSegments.push(segment);
+    segmentIds.push(segment.id);
+  }
+  for (const [index, goal] of opts.goal.entries()) {
+    const body5 = newGoals.get(index);
+    if (!body5) {
+      goalIds.push(goal);
+      continue;
+    }
+    const response = await createGoal(creds, body5);
+    if (!response.ok || !response.data)
+      fail(
+        this,
+        `${response.error ?? "Failed to create goal"}${partial().length ? `; already created: ${partial().join(", ")}` : ""}`,
+        classifyStatus(response.status)
+      );
+    createdGoals.push(response.data);
+    goalIds.push(response.data.id);
+  }
   const spinner = await createSpinner("Creating experiment...");
-  const res = await createExperiment(creds, {
-    name: opts.name,
-    slug: opts.slug ?? null,
-    description: opts.description ?? null,
-    delivery_type: opts.type,
-    counting_type: opts.countingType,
-    traffic_allocation: traffic / 100,
-    ...backlogItemId ? { backlog_item_id: backlogItemId } : {},
-    ...ideaKey ? { idea_key: ideaKey } : {},
-    ...sourceRules.length > 0 ? {
-      store_url: sourceStoreUrl(sourceRules),
-      targeting: {
-        url: sourceRules.map((pattern) => ({
-          type: "simple",
-          pattern,
-          include: true
-        }))
-      }
-    } : {},
-    ...armWeight !== null ? {
-      variations: [
-        {
-          name: "Control",
-          weight: armWeight,
-          is_control: true
-        },
-        ...destinations.map((redirectUrl, index) => ({
-          name: destinations.length === 1 ? "Treatment" : `Treatment ${index + 1}`,
-          weight: armWeight,
-          is_control: false,
-          redirect_url: redirectUrl
-        }))
-      ]
-    } : {}
-  });
+  let res;
+  if (segmentIds.length === 0 && goalIds.length === 0) {
+    res = await createExperiment(creds, {
+      name: opts.name,
+      slug: opts.slug ?? null,
+      description: opts.description ?? null,
+      delivery_type: opts.type,
+      counting_type: opts.countingType,
+      traffic_allocation: traffic / 100,
+      ...backlogItemId ? { backlog_item_id: backlogItemId } : {},
+      ...ideaKey ? { idea_key: ideaKey } : {},
+      ...sourceRules.length > 0 ? {
+        store_url: previewStoreUrl,
+        targeting: {
+          url: sourceRules.map((pattern) => ({
+            type: "simple",
+            pattern,
+            include: true
+          }))
+        }
+      } : {},
+      ...armWeight !== null ? {
+        variations: [
+          {
+            name: "Control",
+            weight: armWeight,
+            is_control: true
+          },
+          ...destinations.map((redirectUrl, index) => ({
+            name: destinations.length === 1 ? "Treatment" : `Treatment ${index + 1}`,
+            weight: armWeight,
+            is_control: false,
+            redirect_url: redirectUrl
+          }))
+        ]
+      } : {}
+    });
+  } else {
+    res = await createExperiment(creds, {
+      name: opts.name,
+      slug: opts.slug ?? null,
+      description: opts.description ?? null,
+      delivery_type: opts.type,
+      counting_type: opts.countingType,
+      traffic_allocation: traffic / 100,
+      ...backlogItemId ? { backlog_item_id: backlogItemId } : {},
+      ...ideaKey ? { idea_key: ideaKey } : {},
+      ...sourceRules.length > 0 ? {
+        store_url: previewStoreUrl,
+        targeting: {
+          url: sourceRules.map((pattern) => ({
+            type: "simple",
+            pattern,
+            include: true
+          })),
+          ...segmentIds.length ? { segments: segmentIds.map((id) => ({ id, include: true })) } : {}
+        }
+      } : segmentIds.length ? { targeting: { segments: segmentIds.map((id) => ({ id, include: true })) } } : {},
+      ...goalIds.length ? { goal_ids: goalIds, primary_goal_id: goalIds[0] } : {},
+      ...armWeight !== null ? {
+        variations: [
+          {
+            name: "Control",
+            weight: armWeight,
+            is_control: true
+          },
+          ...destinations.map((redirectUrl, index) => ({
+            name: destinations.length === 1 ? "Treatment" : `Treatment ${index + 1}`,
+            weight: armWeight,
+            is_control: false,
+            redirect_url: redirectUrl
+          }))
+        ]
+      } : {}
+    });
+  }
   if (!res.ok || !res.data) {
     spinner?.fail("Failed to create experiment");
     fail(
       this,
-      res.error ?? "Failed to create experiment",
+      `${res.error ?? "Failed to create experiment"}${partial().length ? `; already created: ${partial().join(", ")}` : ""}`,
       classifyStatus(res.status),
       res.errorDetails
     );
@@ -10022,18 +10446,49 @@ var create = new Command("create").description("Create a new experiment").addOpt
   spinner?.succeed(
     outcome === "created" ? "Experiment created" : `Already linked \u2014 returning existing experiment ${res.data.test_key ?? res.data.slug ?? res.data.id}`
   );
+  let previewUrl = null;
+  let previewNote = null;
+  if (opts.preview) {
+    const variation = res.data.variations?.find((item) => !item.is_control);
+    const storeUrl = res.data.store_url ?? previewStoreUrl;
+    if (storeUrl && variation) {
+      previewUrl = buildQaPreviewUrl2(storeUrl, res.data.id, variation.id).toString();
+    } else {
+      previewNote = `No preview link: the experiment has no ${variation ? "store URL" : "treatment variation"} yet. Add one, then run \`apex preview ${res.data.id}\`.`;
+    }
+  }
   output(
     this,
     {
       outcome,
       backlog_item_id: backlogItemId ?? null,
       idea_key: ideaKey ?? null,
-      experiment: res.data
+      experiment: res.data,
+      segments: createdSegments,
+      goals: createdGoals,
+      dashboard_url: buildDashboardUrl(
+        creds.baseUrl,
+        res.data?.shop_id ?? creds.resolvedContext?.shopId,
+        res.data.id
+      ),
+      preview_url: previewUrl,
+      preview_note: previewNote
     },
-    () => printExperiment(res.data)
+    () => {
+      printExperiment(
+        res.data,
+        buildDashboardUrl(
+          creds.baseUrl,
+          res.data?.shop_id ?? creds.resolvedContext?.shopId,
+          res.data.id
+        )
+      );
+      if (previewUrl) console.log(`Preview: ${previewUrl}`);
+      if (previewNote) console.log(previewNote);
+    }
   );
 });
-var pause = new Command("pause").description("Pause a running experiment").argument("<id-or-slug>", "Experiment ID or slug").action(async function action10(idOrSlug) {
+var pause = new Command("pause").description("Pause a running experiment").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action10(idOrSlug) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Pausing experiment...");
   const exp = await resolveExperiment(idOrSlug);
@@ -10055,7 +10510,7 @@ var pause = new Command("pause").description("Pause a running experiment").argum
     spinner.succeed(`Experiment "${exp.name}" is now ${statusBadge("paused")}`);
   });
 });
-var complete = new Command("complete").description("Complete/stop an experiment").argument("<id-or-slug>", "Experiment ID or slug").action(async function action11(idOrSlug) {
+var complete = new Command("complete").description("Complete/stop an experiment").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action11(idOrSlug) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Completing experiment...");
   const exp = await resolveExperiment(idOrSlug);
@@ -10077,7 +10532,7 @@ var complete = new Command("complete").description("Complete/stop an experiment"
     spinner.succeed(`Experiment "${exp.name}" is now ${statusBadge("completed")}`);
   });
 });
-var del = new Command("delete").alias("rm").description("Delete an experiment").argument("<id-or-slug>", "Experiment ID or slug").option("-f, --force", "Skip confirmation").action(async function action12(idOrSlug, opts) {
+var del = new Command("delete").alias("rm").description("Delete an experiment").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).option("-f, --force", "Skip confirmation").action(async function action12(idOrSlug, opts) {
   const creds = requireCredentials();
   const exp = await resolveExperiment(idOrSlug);
   if (!exp) {
@@ -10122,7 +10577,7 @@ var del = new Command("delete").alias("rm").description("Delete an experiment").
     () => spinner.succeed(`Experiment "${exp.name}" deleted.`)
   );
 });
-var pullFilesystem = new Command("pull").description("Pull an experiment as an editable filesystem").argument("<id-or-slug>", "Experiment ID or slug").option("--out <path>", "Target folder").action(async function action13(idOrSlug, opts) {
+var pullFilesystem = new Command("pull").description("Pull an experiment as an editable filesystem").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).option("--out <path>", "Target folder").action(async function action13(idOrSlug, opts) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Pulling experiment filesystem...");
   try {
@@ -10168,7 +10623,15 @@ var planFilesystem = new Command("plan").description("Plan experiment filesystem
   try {
     const folder = folderPath(folderArg);
     const session = readFilesystemSession(folder);
-    const files = listExperimentFilesystemFiles(folder, session);
+    const files = await rewriteExperimentFilesystemAssets({
+      files: listExperimentFilesystemFiles(folder, session),
+      folder,
+      baseUrl: creds.baseUrl,
+      enabled: true,
+      upload: null,
+      assets: session.assets ?? {},
+      credentials: creds
+    });
     const res = await planExperimentFilesystem(creds, session.experimentId, { files });
     if (!res.ok || !res.data) {
       fail(
@@ -10201,21 +10664,27 @@ var planFilesystem = new Command("plan").description("Plan experiment filesystem
     fail(this, error instanceof Error ? error.message : String(error));
   }
 });
-var applyFilesystem = new Command("apply").description("Apply experiment filesystem changes to Apex").argument("[folder]", "Experiment filesystem folder", ".").option("--accept-qa-invalidation", "Acknowledge that applying changes invalidates QA approval").addOption(new Option("-f, --force", "Deprecated alias for --accept-qa-invalidation").hideHelp()).option("--no-asset-upload", "Keep inline and local image references unchanged").action(async function action15(folderArg, opts) {
+var applyFilesystem = new Command("apply").option("--sync", "Refresh local authored files with the stored server bytes").description("Apply experiment filesystem changes to Apex").argument("[folder]", "Experiment filesystem folder", ".").option("--accept-qa-invalidation", "Acknowledge that applying changes invalidates QA approval").addOption(new Option("-f, --force", "Deprecated alias for --accept-qa-invalidation").hideHelp()).option("--no-asset-upload", "Keep inline and local image references unchanged").action(async function action15(folderArg, opts) {
   const creds = requireCredentials();
   try {
     const folder = folderPath(folderArg);
     const session = readFilesystemSession(folder);
     if (opts.force)
       process.stderr.write("--force is deprecated; use --accept-qa-invalidation instead.\n");
+    const assets = session.assets ?? {};
     const files = await rewriteExperimentFilesystemAssets({
       files: listExperimentFilesystemFiles(folder, session),
       folder,
       baseUrl: creds.baseUrl,
       enabled: opts.assetUpload !== false,
       upload: uploadAssets,
+      assets,
       credentials: creds
     });
+    if (Object.keys(assets).length > 0) {
+      session.assets = assets;
+      writeFilesystemSession(folder, session);
+    }
     const planRes = await planExperimentFilesystem(creds, session.experimentId, { files });
     if (!planRes.ok || !planRes.data) {
       fail(
@@ -10240,17 +10709,28 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
       });
     }
     if (planRes.data.changes.length === 0) {
+      const synced2 = opts.sync ? await refreshExperimentFilesystemFolderIfNeeded(creds, folder, session.experimentId) : false;
+      if (!synced2)
+        await refreshServerOwnedFilesIfNeeded(creds, folder, session.experimentId, true);
+      const { dashboardUrl: dashboardUrl2 } = await getQaPreviewUrls(creds, session.experimentId);
       output(
         this,
         {
           folder,
           experimentId: session.experimentId,
           applied: false,
+          synced: synced2,
+          dashboardUrl: dashboardUrl2,
           plan: planRes.data,
           requiredAcknowledgment: planRes.data.invalidatesQa ? "accept-qa-invalidation" : null,
           message: "No changes."
         },
-        () => printFilesystemPlan(planRes.data)
+        () => {
+          printFilesystemPlan(planRes.data);
+          console.log(
+            synced2 ? "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."
+          );
+        }
       );
       return;
     }
@@ -10278,9 +10758,29 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
       });
     }
     spinner?.succeed("Applied experiment filesystem");
-    await refreshExperimentFilesystemFolderIfNeeded(creds, folder, session.experimentId);
+    const synced = opts.sync ? await refreshExperimentFilesystemFolderIfNeeded(creds, folder, session.experimentId) : false;
+    if (!synced) {
+      await refreshServerOwnedFilesIfNeeded(
+        creds,
+        folder,
+        session.experimentId,
+        !res.data?.receipt?.files
+      );
+      if (res.data?.receipt?.files) {
+        writeFilesystemSession(folder, {
+          ...session,
+          files: {
+            ...session.files,
+            ...Object.fromEntries(
+              res.data.receipt.files.map((file) => [file.path, { sha256: file.sha256 }])
+            )
+          }
+        });
+      }
+    }
+    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 } = previewResult;
+    const { previewUrls, dashboardUrl } = previewResult;
     output(
       this,
       {
@@ -10290,6 +10790,8 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
         plan: planRes.data,
         requiredAcknowledgment: planRes.data.invalidatesQa ? "accept-qa-invalidation" : null,
         result: res.data,
+        synced,
+        dashboardUrl,
         receipt: res.data?.receipt ?? null,
         previewUrls
       },
@@ -10298,6 +10800,7 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
         const receipt = res.data?.receipt;
         if (receipt) {
           console.log("\nReceipt");
+          if (dashboardUrl) console.log(`  Dashboard: ${dashboardUrl}`);
           console.log(`  Status: ${receipt.status}`);
           console.log(`  Classification: ${receipt.delivery_type} / ${receipt.counting_type}`);
           console.log(`  Traffic: ${(receipt.traffic_allocation * 100).toFixed(0)}%`);
@@ -10315,6 +10818,7 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
           }
         }
         printQaPreviewUrls(session.experimentId, previewResult);
+        console.log(syncMessage);
       }
     );
   } catch (error) {
@@ -10322,7 +10826,11 @@ var applyFilesystem = new Command("apply").description("Apply experiment filesys
     fail(this, error instanceof Error ? error.message : String(error));
   }
 });
-var qaStatus = new Command("status").description("Show or create the latest experiment QA run").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").option("--json", "Print the QA run in the standard JSON envelope").action(async function action16(target) {
+var qaStatus = new Command("status").description("Show or create the latest experiment QA run").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).option("--json", "Print the QA run in the standard JSON envelope").action(async function action16(target) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Fetching QA run...");
   try {
@@ -10346,7 +10854,11 @@ var qaStatus = new Command("status").description("Show or create the latest expe
     throw error;
   }
 });
-var qaCheck = new Command("check").description("Update one QA checklist item with status, notes, and evidence").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").requiredOption("--item <id>", "Checklist item id").addOption(
+var qaCheck = new Command("check").description("Update one QA checklist item with status, notes, and evidence").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).requiredOption("--item <id>", "Checklist item id").addOption(
   qaChoice("--status <status>", "Checklist status", checklistStatuses).makeOptionMandatory()
 ).option("--notes <text>", "Checklist notes").option("--evidence <json-or-path>", "Evidence JSON object or @path/to/evidence.json").option("--summary", "Print a compact run and changed values").option("--json", "Print raw QA run JSON").action(async function action17(target, opts) {
   validateQaChoice(this, "--status", opts.status, checklistStatuses);
@@ -10390,7 +10902,11 @@ var qaCheck = new Command("check").description("Update one QA checklist item wit
     throw error;
   }
 });
-var qaNotes = new Command("notes").description("Update QA run notes or acceptance criteria summary").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").option("--notes <text>", "QA run notes").option("--acceptance <text>", "Acceptance criteria summary").option("--summary", "Print a compact run and changed values").option("--json", "Print raw QA run JSON").action(async function action18(target, opts) {
+var qaNotes = new Command("notes").description("Update QA run notes or acceptance criteria summary").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).option("--notes <text>", "QA run notes").option("--acceptance <text>", "Acceptance criteria summary").option("--summary", "Print a compact run and changed values").option("--json", "Print raw QA run JSON").action(async function action18(target, opts) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Updating QA notes...");
   try {
@@ -10435,7 +10951,11 @@ var qaNotes = new Command("notes").description("Update QA run notes or acceptanc
     throw error;
   }
 });
-var qaApprove = new Command("approve").description("Approve QA and move the experiment to ready_to_launch; qa reopen returns it to QA").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").action(async function action19(target) {
+var qaApprove = new Command("approve").description("Approve QA and move the experiment to ready_to_launch; qa reopen returns it to QA").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).action(async function action19(target) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Approving QA...");
   try {
@@ -10465,6 +10985,7 @@ var qaApprove = new Command("approve").description("Approve QA and move the expe
       {
         experimentId: resolved.experimentId,
         qaStatus: "done",
+        experiment: res.data,
         experiment_status_before: before.status,
         experiment_status_after: res.data.status,
         transition
@@ -10478,7 +10999,11 @@ var qaApprove = new Command("approve").description("Approve QA and move the expe
     throw error;
   }
 });
-var qaReopen = new Command("reopen").description("Reopen QA and clear scheduled launch state").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").action(async function action20(target) {
+var qaReopen = new Command("reopen").description("Reopen QA and clear scheduled launch state").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).action(async function action20(target) {
   const creds = requireCredentials();
   const spinner = await createSpinner("Reopening QA...");
   try {
@@ -10536,7 +11061,11 @@ function resolveEvidenceVariation(experiment, ref) {
   }
   throw new Error(`Unknown --variation value: ${ref}`);
 }
-var qaEvidence = new Command("evidence").description("Attach screenshot jobs or upload typed QA evidence").argument("[folder-or-id]", "Experiment filesystem folder, ID, or slug", ".").option("--job <jobId>", "Attach a terminal screenshot job").option("--file <path>", "Upload an evidence image; repeat for more files", collectFile, []).option("--label <text>", "Evidence label").option("--device <device>", "desktop, mobile, tablet, or a raw device value").option("--variation <ref>", "Variation ID, slug, or name").addOption(qaChoice("--status <status>", "Evidence status", evidenceStatuses)).addOption(qaChoice("--kind <kind>", "Evidence kind", evidenceKinds).default("screenshot")).option("--records <json-or-@path>", "Typed evidence record array").option("--summary", "Print a compact run and newly added evidence").option("--json", "Print the QA run in the standard JSON envelope").action(async function action21(target, opts) {
+var qaEvidence = new Command("evidence").description("Attach screenshot jobs or upload typed QA evidence").argument(
+  "[folder-or-id]",
+  "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
+  "."
+).option("--job <jobId>", "Attach a terminal screenshot job").option("--file <path>", "Upload an evidence image; repeat for more files", collectFile, []).option("--label <text>", "Evidence label").option("--device <device>", "desktop, mobile, tablet, or a raw device value").option("--variation <ref>", "Variation ID, slug, or name").addOption(qaChoice("--status <status>", "Evidence status", evidenceStatuses)).addOption(qaChoice("--kind <kind>", "Evidence kind", evidenceKinds).default("screenshot")).option("--records <json-or-@path>", "Typed evidence record array").option("--summary", "Print a compact run and newly added evidence").option("--json", "Print the QA run in the standard JSON envelope").action(async function action21(target, opts) {
   validateQaChoice(this, "--status", opts.status, evidenceStatuses);
   validateQaChoice(this, "--kind", opts.kind, evidenceKinds);
   const modes = Number(Boolean(opts.job)) + Number(opts.file.length > 0) + Number(Boolean(opts.records));
@@ -10642,7 +11171,7 @@ function screenshotTimeoutMessage(job, experimentRef, out, seconds, flags = {})
 }
 var screenshots = new Command("screenshots").description(
   "Force-assign every capture, including control, to its variation server-side for deterministic screenshots"
-).argument("<experimentRef>", "Experiment ID or slug").option("--url <target>", "Target URL override (not supported by the current v1 API)").option("--devices <list>", `Comma-separated devices (default: ${SCREENSHOT_DEVICES.join(",")})`).option(
+).argument("<experimentRef>", EXPERIMENT_REFERENCE_DESCRIPTION).option("--url <target>", "Target URL override (not supported by the current v1 API)").option("--devices <list>", `Comma-separated devices (default: ${SCREENSHOT_DEVICES.join(",")})`).option(
   "--variations <list>",
   "Comma-separated treatment IDs, slugs, or names; control is always included and force-assigned"
 ).option("--out <dir>", "Download directory", ".").option("--job <id>", "Resume an existing screenshot job instead of creating one").option("--json", "Print the completed raw job payload with signed URLs").option("--no-attach-qa", "Do not attach the completed job to the QA run").option("--no-label-pairs", "Keep legacy screenshot filenames without before/after labels").option(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drip-apex/apex-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "license": "MIT",
   "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   "private": false,

package/skills/apex-cli/SKILL.md

@@ -13,7 +13,6 @@ apex schema --json
 
 Prefer JSON output. When stdout is piped, Apex emits JSON by default.
 
-
 ## Zero-Experiment Shop Bootstrap
 
 CLI-only bootstrap is supported for a fresh shop before any experiments exist.
@@ -64,7 +63,6 @@ Platform administrators can archive a mistakenly created shop with
 stop those tests rather than retrying or overriding the refusal. Restore leaves
 delivery controlled by the runtime kill switch.
 
-
 ## Project code
 
 ```sh
@@ -91,3 +89,14 @@ A successful write returns `saved`, its diff, backup path, current version, writ
 and precompile result. A failed precompile is a saved-write warning. All warnings remain
 in JSON and are also written to stderr. User keys resolve domains or pin UUID context;
 shop keys must match the requested identity before any backup or write.
+
+Experiment references accept an ID, slug, or test key (for example `BIO-085`). Test keys resolve within the selected shop; use `--shop <shop-id>` to change it. Bare lowercase references remain slugs.
+
+Filesystem apply preserves authored local bytes by default. Use
+`apex experiments apply <folder> --sync` to refresh them from stored server bytes.
+The receipt's `files` contains SHA-256 digests for every pull path; `synced` reports
+whether a full refresh succeeded. Server-owned QA and launch files are healed.
+Create/get return `dashboard_url`; apply returns `dashboardUrl`. These links
+switch the signed-in dashboard user's active shop before opening the experiment.
+
+Filesystem apply caches uploaded asset URLs by byte SHA-256 in `.apex/experiment-filesystem.json`, so unchanged images reuse their URL across applies without rewriting authored files.