@koda-sl/baker-cli 0.286.0-dev.93be96120 → 0.287.0-dev.93be96120

package/dist/cli.js

@@ -38796,53 +38796,32 @@ async function foldExperiment(root, target) {
   };
 }
 
-// src/commands/experiment/goal.ts
-function parseEventGoal(argument) {
-  const [name, filter] = argument.split("/");
-  if (!name) return { error: "Name the event: --goal event:request_demo" };
-  if (!filter) return { kind: "custom_event", name };
-  const separator = filter.indexOf("=");
-  if (separator === -1) {
-    return { error: `Write the property as key=value: --goal event:${name}/section=pricing` };
-  }
-  return { kind: "custom_event", name, property: filter.slice(0, separator), value: filter.slice(separator + 1) };
-}
-function parseGoal(raw) {
-  if (raw === void 0 || raw === "") return void 0;
-  const separator = raw.indexOf(":");
-  const kind = separator === -1 ? raw : raw.slice(0, separator);
-  const argument = separator === -1 ? "" : raw.slice(separator + 1);
-  if (kind === "leads") return argument ? { kind: "conversion", flowSlug: argument } : { kind: "conversion" };
-  if (kind === "click") return argument ? { kind: "outbound_click", targetHost: argument } : { kind: "outbound_click" };
-  if (kind === "event") return parseEventGoal(argument);
-  return {
-    error: `Unknown goal "${raw}". Use leads, leads:<form>, event:<name>, event:<name>/<key>=<value>, click, or click:<host>`
-  };
-}
-
 // src/commands/experiment/hints.ts
-var RUNNING_HINT = {
+var LIVE_HINT = {
   keep_running: (row) => `${row.experimentId} cannot yet tell the two pages apart \u2014 do not read its numbers as a result, and do not end it hoping for one. ${describeWait(row)}`,
-  winner: (row) => `${row.experimentId} has a winner. Run \`baker experiment finish --id ${row.experimentId}\` to send all the traffic to it. That only re-routes between two pages already published \u2014 it does not edit either.`,
-  no_difference: (row) => `${row.experimentId} measured the two pages as alike \u2014 it collected enough traffic to see the change it was looking for, and there was none. Finish it (the page you have stays live) and test a bigger change \u2014 a headline, an offer, the shape of the page, not a button colour.`,
-  stopped_early_harmful: (row) => `${row.experimentId} is doing damage. Finish it now \u2014 traffic goes back to the original page.`,
-  // Unreachable in practice — only `finish --abandon` produces it, and that
-  // leaves the test finished. The Record is exhaustive by type so a verdict
-  // added upstream fails to compile here rather than printing nothing.
-  abandoned: (row) => `${row.experimentId} was stopped before it concluded and found nothing.`,
-  invalid: (row) => `${row.experimentId} cannot be read: ${row.invalidReason === "crossover" ? "too many visitors saw both versions" : "the traffic did not split evenly"}. Finish it and start again rather than reporting anything from it.`
+  winner: (row) => row.winner === "variant" ? `${row.experimentId} has a winner: the new variant. Run \`baker experiment finish --id ${row.experimentId} --keep variant\` to show it to everyone, then \`baker experiment fold\`.` : `${row.experimentId} has a winner: the page as it is. Run \`baker experiment finish --id ${row.experimentId} --keep original\` to put all the traffic back on it.`,
+  no_difference: (row) => `${row.experimentId} measured the two pages as alike \u2014 it collected enough traffic to see the change it was looking for, and there was none. End it with \`--keep original\` and test a bigger change \u2014 a headline, an offer, the shape of the page, not a button colour.`,
+  stopped_early_harmful: (row) => `${row.experimentId} is doing damage and is STILL being shown to half the visitors. Run \`baker experiment finish --id ${row.experimentId} --keep original\` now.`,
+  // Unreachable on a live test — only ending one produces it. The Record is
+  // exhaustive by type so a verdict added upstream fails to compile here rather
+  // than printing nothing.
+  inconclusive: (row) => `${row.experimentId} was ended before it concluded and found nothing.`,
+  invalid: (row) => `${row.experimentId} cannot be read: ${row.invalidReason === "crossover" ? "too many visitors saw both versions" : "the traffic did not split evenly"}. End it with \`--keep original\` and start again rather than reporting anything from it.`
 };
 function describeWait(row) {
   if (row.willNotConclude) {
-    return "This page's traffic will not settle it at any point, so abandon it with `--abandon` and test a bigger change.";
+    return "This page's traffic will not settle it at any point, so end it with `--keep original` and test a bigger change.";
   }
   if (row.earliestDecisionAt === null) {
     return "This page has produced no visitors yet, so there is nothing to project a finish date from.";
   }
   return `Earliest it could say anything: ${new Date(row.earliestDecisionAt).toISOString().slice(0, 10)}.`;
 }
+function pausedNote(row) {
+  return row.status === "paused" ? `${row.experimentId} is paused \u2014 everyone sees the original. \`baker experiment resume --id ${row.experimentId}\` restarts the split with the same sides. ` : "";
+}
 function buildStatusHints(experiments) {
-  const hints2 = experiments.filter((row) => row.status === "running").map((row) => RUNNING_HINT[row.verdict](row));
+  const hints2 = experiments.filter((row) => row.status !== "finished").map((row) => pausedNote(row) + LIVE_HINT[row.verdict](row));
   if (experiments.length === 0) {
     hints2.push(
       "No tests yet. `baker experiment plan --landing <slug> --variant <slug>` says whether a page has enough traffic for one before you build the alternative."
@@ -38853,40 +38832,48 @@ function buildStatusHints(experiments) {
 function asLift(value) {
   return `+${Math.round(value * 100)}%`;
 }
-function windowHint(days, detectable) {
-  if (days === void 0) return null;
-  if (detectable === null || detectable === void 0) {
-    return `In ${days} days this page would not gather enough visitors to settle anything, at any size of change. The constraint is the traffic, not the test.`;
+function horizonsHint(plan) {
+  const settled = plan.horizons.filter((horizon) => horizon.detectableLift !== null);
+  if (settled.length === 0) {
+    return "At this page's traffic no window up to 90 days would gather enough visitors to settle anything, at any size of change. The constraint is the traffic, not the test.";
   }
-  return `In ${days} days this page could only settle a change of ${asLift(detectable)} or more. Design the alternative to be at least that different \u2014 a smaller change needs traffic these ${days} days will not deliver, and the test would end saying nothing.`;
+  const parts = settled.map((horizon) => `${horizon.days} days \u2192 ${asLift(horizon.detectableLift ?? 0)}`);
+  return `The smallest change each window could settle on this page's traffic: ${parts.join(", ")}. Design the alternative to be at least that different.`;
 }
-function buildPlanHints(plan, days) {
-  const window2 = windowHint(days, plan.detectableLiftInDays);
+function conversionsHint(plan) {
+  if (plan.conversions.length <= 1) return null;
+  const others = plan.conversions.filter((entry) => entry.name !== plan.goal);
+  return `This page's visitors also went on to: ${others.map((entry) => `\u201C${entry.name}\u201D (${entry.convertingVisitors})`).join(", ")}. They are reported beside the goal on every result, and decide nothing.`;
+}
+function buildPlanHints(plan) {
+  const horizons = horizonsHint(plan);
   if (!plan.canRun) {
     return [
       plan.reason ?? "This test cannot run on this page.",
-      ...window2 ? [window2] : [],
+      ...horizons && plan.visitors > 0 ? [horizons] : [],
       "A test that cannot conclude is worse than no test \u2014 it still produces a number, and somebody acts on it."
     ];
   }
   const hints2 = [
-    `This test measures ${plan.goalLabel}. That is fixed when it starts and cannot be changed later.`,
+    `This test is read on \u201C${plan.goal}\u201D. That is fixed when it starts and cannot be changed later.`,
     // Fires at the exact moment the hypothesis gets invented, whether or not
     // the agent read the family doc. `plan` says a question CAN be settled here
     // and says nothing about which question is worth asking — and a well-run
     // test of a bad idea costs three weeks and returns `no_difference`.
-    "Now decide WHAT to change, from evidence rather than taste. These numbers say which page and which step; they cannot say why. A second opinion answers why \u2014 Microsoft Clarity for what visitors actually do on the page, `baker gsc` for what they searched, `baker ads <platform>` for what the ad promised, `baker ga4` for the client's own measurement. `baker capabilities` lists everything this client has in one call \u2014 the surfaces, and under `tools` everything else that is reachable. Message match \u2014 what the ad or the search promised against what the page opens with \u2014 is the cheapest hypothesis worth testing and is wrong surprisingly often.",
+    "Now decide WHAT to change, from evidence rather than taste. These numbers say which page and which step; they cannot say why. A second opinion answers why \u2014 Microsoft Clarity for what visitors actually do on the page, `baker gsc` for what they searched, `baker ads <platform>` for what the ad promised, `baker ga4` for the client's own measurement. `baker capabilities` lists everything this client has in one call. Message match \u2014 what the ad or the search promised against what the page opens with \u2014 is the cheapest hypothesis worth testing and is wrong surprisingly often.",
     // The base always works, so a missing integration is never a reason to
     // stop. Naming what it would have shown is worth more to the client than
     // either a silent gap or a run that waited.
     "If none of that is connected, this page's own drop-off is enough to test on \u2014 say which source you lacked and what it would have told you, then run the test anyway. A test never waits on an integration."
   ];
+  const conversions = conversionsHint(plan);
+  if (conversions) hints2.push(conversions);
   if (plan.estimatedDays !== null && plan.estimatedDays > 60) {
     hints2.push(
       `At this page's traffic it would take about ${plan.estimatedDays} days. Consider testing a bigger change, which needs less traffic to detect.`
     );
   }
-  if (window2) hints2.push(window2);
+  if (horizons) hints2.push(horizons);
   return hints2;
 }
 
@@ -38901,45 +38888,7 @@ var experimentCompositionSchema = z35.object({
 
 // ../api/src/experiments/goal.ts
 import { z as z36 } from "zod";
-var eventNameSchema = z36.string().min(1).max(120);
-var experimentGoalSchema = z36.discriminatedUnion("kind", [
-  z36.object({
-    kind: z36.literal("conversion"),
-    /**
-     * Narrow to one Form, by the slug that is its identity.
-     *
-     * Absent means every marked conversion on the page counts, which is the
-     * right default for a landing with one Form and the wrong one for a page
-     * carrying both a newsletter signup and a demo request.
-     */
-    flowSlug: z36.string().max(120).optional()
-  }),
-  z36.object({
-    kind: z36.literal("custom_event"),
-    name: eventNameSchema,
-    /**
-     * Narrow to one value of one of the event's own properties.
-     *
-     * `section_view` on its own is every section; `section_view` where
-     * `section = pricing` is the one that matters. Without this a page would
-     * have to encode the answer into the event name to be testable against it,
-     * which is precisely what the properties map exists to stop.
-     */
-    property: z36.string().max(64).optional(),
-    value: z36.string().max(255).optional()
-  }),
-  z36.object({
-    kind: z36.literal("outbound_click"),
-    /**
-     * The destination host, as the row records it. Absent means any exit.
-     *
-     * A host rather than a full URL because that is what `event_name` carries
-     * on an `outbound_click` row — `target_url` has the rest, and matching on
-     * it would make the goal depend on query parameters a campaign rewrites.
-     */
-    targetHost: z36.string().max(255).optional()
-  })
-]);
+var experimentGoalSchema = z36.string().trim().min(1).max(MAX_CONVERSION_NAME);
 
 // ../api/src/experiments/hypothesis.ts
 import { z as z37 } from "zod";
@@ -38997,6 +38946,14 @@ var slugSchema = z38.string().min(1).max(120).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/
 var experimentPlanRequestSchema = z38.object({
   landingSlug: slugSchema,
   variantSlug: slugSchema,
+  /**
+   * Which of the company's conversions the test is about.
+   *
+   * Optional only when the company counts exactly one outcome, in which case
+   * it is that one. A company counting several has to say which — a test that
+   * "measures conversions" on a page with a newsletter box and a demo request
+   * is measuring two things and deciding on their sum.
+   */
   goal: experimentGoalSchema.optional(),
   /**
    * The smallest lift worth detecting, relative to the baseline. `0.2` is +20%.
@@ -39006,18 +38963,7 @@ var experimentPlanRequestSchema = z38.object({
    * quarter of a million visitors per arm; `plan` will say so rather than
    * running it.
    */
-  minDetectableRelativeLift: z38.number().gt(0).max(10).optional(),
-  /**
-   * "I have this many days — what could I even see?"
-   *
-   * Read-only, and deliberately not a setting. It does NOT shorten the test:
-   * the finish line is a number of visitors fixed before the test starts, and a
-   * horizon that can be moved is not a horizon. What it does is answer the
-   * question a refusal leaves hanging — `plan` says a +20% lift needs three
-   * weeks this page will not deliver, and this says what those weeks WOULD
-   * settle, which is a change somebody can actually go and make.
-   */
-  days: z38.number().int().gt(0).max(365).optional()
+  minDetectableRelativeLift: z38.number().gt(0).max(10).optional()
 });
 var experimentStartRequestSchema = experimentPlanRequestSchema.extend({
   hypothesis: experimentHypothesisSchema,
@@ -39032,28 +38978,13 @@ var experimentStartRequestSchema = experimentPlanRequestSchema.extend({
    */
   composition: experimentCompositionSchema.optional()
 });
+var experimentKeepSchema = z38.enum(["original", "variant"]);
 var experimentFinishRequestSchema = z38.object({
   experimentId: z38.string().min(1).max(64),
-  /**
-   * Stop the test, keep the page that is live, and record no result.
-   *
-   * The only way a person or an agent can end a test that is still
-   * `keep_running`, and it is deliberately its own field rather than a
-   * `survivor` they get to pick: an abandoned test has no winner, keeps the
-   * control, and is recorded as `abandoned` so it can never be reported later
-   * as a result. Without the separate flag, "stop this" and "the variant won"
-   * would be the same call.
-   *
-   * **It overrides the verdict, and does not defer to it.** The only outcome it
-   * can actually disagree with is a variant win — every other one keeps the
-   * control anyway — so reading it as "apply only when the numbers have nothing
-   * to say" meant that abandoning a won test handed all the traffic to the
-   * variant instead of keeping the original: the opposite of what this field
-   * promises, on live visitors, from a flag whose whole purpose is to be the
-   * conservative choice. The response reports `discardedVerdict` when it did
-   * override one, because throwing away a real finding should be said out loud.
-   */
-  abandon: z38.boolean().optional()
+  keep: experimentKeepSchema
+});
+var experimentPauseRequestSchema = z38.object({
+  experimentId: z38.string().min(1).max(64)
 });
 var experimentFoldRequestSchema = z38.object({
   /** Which test to fold. Omitted ⇒ every fold this company owes. */
@@ -39081,10 +39012,26 @@ var experimentStatusRequestSchema = z38.object({
   experimentId: z38.string().max(64).optional(),
   full: z38.boolean().optional()
 });
+var experimentPageConversionSchema = z38.object({
+  name: z38.string(),
+  /** Distinct visitors to the page who went on to do this. */
+  convertingVisitors: z38.number()
+});
+var experimentHorizonSchema = z38.object({
+  days: z38.number(),
+  /** The smallest relative lift detectable in that many days. `null` when none would be. */
+  detectableLift: z38.number().nullable()
+});
 var experimentPlanResponseSchema = z38.object({
   canRun: z38.boolean(),
   /** Present when `canRun` is false. Product language, ready to show. */
   reason: z38.string().optional(),
+  /** The conversion the test would be read on. Absent when none could be chosen. */
+  goal: experimentGoalSchema.optional(),
+  /** Every conversion this page produced over the sizing window, most common first. */
+  conversions: z38.array(experimentPageConversionSchema),
+  /** Distinct visitors the page had over the sizing window. */
+  visitors: z38.number(),
   baselineRate: z38.number(),
   minDetectableRelativeLift: z38.number(),
   /** `null` when no amount of traffic could settle the hypothesis. */
@@ -39093,14 +39040,7 @@ var experimentPlanResponseSchema = z38.object({
   dailyVisitorsPerVariant: z38.number(),
   /** `null` when the page has no traffic to project from. */
   estimatedDays: z38.number().nullable(),
-  goal: experimentGoalSchema,
-  goalLabel: z38.string(),
-  /**
-   * The smallest lift `days` of this page's traffic could detect, when `days`
-   * was asked for. `null` when it was not, or when no lift at all would be
-   * detectable in that window.
-   */
-  detectableLiftInDays: z38.number().nullable().optional()
+  horizons: z38.array(experimentHorizonSchema)
 });
 var experimentVerdictSchema = z38.enum([
   "keep_running",
@@ -39109,16 +39049,17 @@ var experimentVerdictSchema = z38.enum([
   "invalid",
   "stopped_early_harmful",
   /**
-   * Stopped by a person before it concluded. Never produced by the stopping
-   * rule — only by `finish --abandon`.
+   * Ended before the numbers could say anything. Never produced by the
+   * stopping rule — only by ending a `keep_running` test.
    *
    * Its own verdict rather than folded into `no_difference`, because they are
    * opposite claims: one says the two versions were measured and found alike,
    * the other says nobody ever found out. Collapsing them would manufacture the
    * exact finding this feature exists to refuse.
    */
-  "abandoned"
+  "inconclusive"
 ]);
+var experimentStatusValueSchema = z38.enum(["running", "paused", "finished"]);
 var experimentArmSchema = z38.object({
   slug: z38.string(),
   visitors: z38.number(),
@@ -39134,6 +39075,16 @@ var experimentArmSchema = z38.object({
    */
   previewUrl: z38.string().nullable().optional()
 });
+var experimentMetricSchema = z38.object({
+  name: z38.string(),
+  control: z38.object({ conversions: z38.number(), rate: z38.number() }),
+  variant: z38.object({ conversions: z38.number(), rate: z38.number() }),
+  relativeLift: z38.number(),
+  /** The anytime-valid interval on the relative lift. */
+  liftInterval: z38.tuple([z38.number(), z38.number()]),
+  /** `better` when the interval sits above zero, `worse` below it, `unclear` across it. */
+  reading: z38.enum(["better", "worse", "unclear"])
+});
 var experimentTimelineArmSchema = z38.object({
   visitors: z38.number(),
   conversions: z38.number(),
@@ -39173,19 +39124,29 @@ var experimentStatusRowSchema = z38.object({
    * is not a hypothesis, "leads should go up by at least 20%" is.
    */
   minDetectableRelativeLift: z38.number(),
-  goalLabel: z38.string(),
-  status: z38.enum(["running", "finished"]),
+  /** The conversion the verdict is read from. The company's own name for it. */
+  goal: experimentGoalSchema,
+  status: experimentStatusValueSchema,
   startedAt: z38.number(),
+  /** Set while paused. The split is off and everyone sees the original. */
+  pausedAt: z38.number().nullable(),
   finishedAt: z38.number().nullable(),
   verdict: experimentVerdictSchema,
-  /** Set only on `winner`. Which page to keep. */
+  /** Set only on `winner`. Which version the numbers favour. */
   winner: z38.enum(["control", "variant"]).nullable(),
+  /**
+   * Which version is live, once the test has ended. Chosen by whoever ended it,
+   * and allowed to disagree with `winner` — the card says so when it does.
+   */
+  survivor: z38.enum(["control", "variant"]).nullable(),
   /** Set only on `invalid`. Why the numbers cannot be read. */
   invalidReason: z38.enum(["sample_ratio_mismatch", "crossover"]).nullable(),
   /** What a person should be told, in one sentence, in product language. */
   summary: z38.string(),
   control: experimentArmSchema,
   variant: experimentArmSchema,
+  /** Every other conversion the company counts, on the same two arms. */
+  secondary: z38.array(experimentMetricSchema),
   /**
    * How close this test is to being able to say anything at all, 0 to 1.
    *
@@ -39199,8 +39160,8 @@ var experimentStatusRowSchema = z38.object({
   earliestDecisionAt: z38.number().nullable(),
   /**
    * True when no amount of this page's traffic would settle the comparison.
-   * A different thing from a page that is merely slow, and the reason to
-   * abandon a test rather than leave it running.
+   * A different thing from a page that is merely slow, and the reason to end
+   * a test rather than leave it running.
    */
   willNotConclude: z38.boolean(),
   /**
@@ -39225,6 +39186,13 @@ var experimentStatusRowSchema = z38.object({
 var experimentStatusResponseSchema = z38.object({
   experiments: z38.array(experimentStatusRowSchema)
 });
+var experimentFinishResponseSchema = z38.object({
+  verdict: experimentVerdictSchema,
+  survivor: z38.enum(["control", "variant"]),
+  /** True when `keep` went against a verdict the numbers had reached. */
+  againstVerdict: z38.boolean(),
+  summary: z38.string()
+});
 
 // src/commands/experiment/hypothesis.ts
 var SOURCES = experimentEvidenceSourceSchema.options.join(", ");
@@ -39262,7 +39230,7 @@ function parseEvidence(raw) {
 // src/commands/experiment/index.ts
 var GOAL_ARG = {
   type: "string",
-  description: "What counts as success, and it is fixed for the life of the test. `leads` (default \u2014 whatever this company already marks as a conversion), `leads:<form>`, `event:<name>` for an event the page declares itself (see `baker analytics events`), `event:<name>/<key>=<value>` to narrow it, `click` or `click:<host>` for leaving the site. Pick the thing the business actually wants; a test that measures the wrong outcome can have the variant win and the revenue fall.",
+  description: "Which of this company's conversions the test is about, by the name on the Conversions screen \u2014 \u201CBooked a call\u201D, \u201CQuote requested\u201D. Fixed for the life of the test. Optional when the company counts exactly one outcome; required when it counts several, and `plan` lists them. Every other conversion is reported beside the goal on every result and decides nothing. If the outcome you need is not defined yet, define it first with `baker analytics conversions` \u2014 it applies to history, so no traffic is lost.",
   required: false
 };
 var LIFT_ARG = {
@@ -39270,11 +39238,6 @@ var LIFT_ARG = {
   description: "The smallest improvement worth detecting, relative \u2014 0.2 is +20% (default). The single most consequential number here: halving it roughly quadruples the traffic needed. Ask for the smallest lift that would actually change what the client does, not the smallest one you would like to see.",
   required: false
 };
-var DAYS_ARG = {
-  type: "string",
-  description: "How many days you have, if that is the constraint. This does NOT shorten the test \u2014 the finish line is a visitor count fixed before it starts \u2014 it answers the other question: what a window that long could settle on this page's traffic. Use it when `plan` refuses and you need to know what WOULD fit.",
-  required: false
-};
 var BECAUSE_ARG = {
   type: "string",
   description: "What you SAW that makes this worth testing \u2014 the observation, not the change. \u201C60% of visitors never scroll past the hero\u201D, \u201CCPL doubled after the new headline\u201D. This is the field that makes a losing test worth something: without it there is no belief for the result to be evidence against, and the next test is no better informed than this one.",
@@ -39295,6 +39258,7 @@ var EVIDENCE_ARG = {
   description: "Where the observation came from, as `source:what it showed`, optionally `|link`. Repeatable. Sources: baker_analytics, clarity, ads, search_console, research, inspiration, client, hunch. Use `hunch` honestly when there is no data \u2014 a stated guess is worth more than a guess dressed as analytics.",
   required: false
 };
+var ID_ARG = { type: "string", description: "The test, by its id", required: true };
 function fail5(message) {
   writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
   process.exit(1);
@@ -39311,40 +39275,31 @@ registerSchema({
   description: "Whether a page has enough traffic to settle a question, before anything is built",
   args: {
     landing: { type: "string", description: "The page under test, by slug", required: true },
-    variant: { type: "string", description: "The alternative page's slug", required: true },
+    variant: { type: "string", description: "The new variant's slug, `<page>--<n>`", required: true },
     goal: GOAL_ARG,
-    lift: LIFT_ARG,
-    days: DAYS_ARG
+    lift: LIFT_ARG
   }
 });
 var planCommand = defineCommand119({
   meta: {
     name: "plan",
-    description: "Start here, BEFORE building the alternative page. Says whether this page gets enough traffic to settle the question, how long it would take, and whether the thing you want to measure has ever happened on it. Most landing pages cannot run most tests \u2014 finding that out now costs one call, and finding it out later costs three weeks and a decision made on noise."
+    description: "Start here, BEFORE building the alternative page. Says whether this page gets enough traffic to settle the question, how long it would take, which conversions the page's visitors actually go on to do, and what a 14, 28, 56 or 90-day window could settle. Most landing pages cannot run most tests \u2014 finding that out now costs one call, and finding it out later costs three weeks and a decision made on noise."
   },
   args: {
     landing: { type: "string", description: "The page under test, by slug", required: true },
-    variant: { type: "string", description: "The alternative page's slug", required: true },
+    variant: { type: "string", description: "The new variant's slug, `<page>--<n>`", required: true },
     goal: GOAL_ARG,
-    lift: LIFT_ARG,
-    days: DAYS_ARG
+    lift: LIFT_ARG
   },
   run: async ({ args }) => {
-    const goal = parseGoal(args.goal ? String(args.goal) : void 0);
-    if (goal && "error" in goal) fail5(goal.error);
     try {
       const response = await apiPost("/api/experiments/plan", {
         landingSlug: String(args.landing),
         variantSlug: String(args.variant),
-        ...goal ? { goal } : {},
-        ...args.lift ? { minDetectableRelativeLift: Number(args.lift) } : {},
-        ...args.days ? { days: Number(args.days) } : {}
-      });
-      writeJsonEnvelope({
-        ok: true,
-        data: response.data,
-        hints: buildPlanHints(response.data, args.days ? Number(args.days) : void 0)
+        ...args.goal ? { goal: String(args.goal) } : {},
+        ...args.lift ? { minDetectableRelativeLift: Number(args.lift) } : {}
       });
+      writeJsonEnvelope({ ok: true, data: response.data, hints: buildPlanHints(response.data) });
     } catch (error) {
       reportApiError(error);
     }
@@ -39352,10 +39307,10 @@ var planCommand = defineCommand119({
 });
 registerSchema({
   command: "experiment.start",
-  description: "Stage an A/B test between a page and its alternative",
+  description: "Stage an A/B test between a page and a new variant of it",
   args: {
     landing: { type: "string", description: "The page under test, by slug", required: true },
-    variant: { type: "string", description: "The alternative page's slug", required: true },
+    variant: { type: "string", description: "The new variant's slug, `<page>--<n>`", required: true },
     because: BECAUSE_ARG,
     change: CHANGE_ARG,
     expect: EXPECT_ARG,
@@ -39367,11 +39322,11 @@ registerSchema({
 var startCommand = defineCommand119({
   meta: {
     name: "start",
-    description: "Stage a test between the page and its alternative. Both are ordinary published pages; visitors are split 50/50 at the edge, so there is no flicker and nothing for an ad blocker to suppress. Nothing goes live until the session is published \u2014 the person publishing is the review of the alternative page. Re-runs `plan` first and refuses on the same grounds."
+    description: "Stage a test between the page and its new variant. Visitors are split 50/50 at the edge, so there is no flicker and nothing for an ad blocker to suppress. Nothing goes live until the session is published \u2014 the person publishing is the review of the new variant. Re-runs `plan` first and refuses on the same grounds."
   },
   args: {
     landing: { type: "string", description: "The page under test, by slug", required: true },
-    variant: { type: "string", description: "The alternative page's slug", required: true },
+    variant: { type: "string", description: "The new variant's slug, `<page>--<n>`", required: true },
     because: BECAUSE_ARG,
     change: CHANGE_ARG,
     expect: EXPECT_ARG,
@@ -39380,8 +39335,6 @@ var startCommand = defineCommand119({
     lift: LIFT_ARG
   },
   run: async ({ args }) => {
-    const goal = parseGoal(args.goal ? String(args.goal) : void 0);
-    if (goal && "error" in goal) fail5(goal.error);
     const expect = args.expect === void 0 ? "increase" : String(args.expect);
     if (expect !== "increase" && expect !== "decrease") {
       fail5("`--expect` is either `increase` or `decrease` \u2014 which way should the goal move if you are right?");
@@ -39400,7 +39353,7 @@ var startCommand = defineCommand119({
           ...evidence ? { evidence } : {}
         },
         ...composition ? { composition } : {},
-        ...goal ? { goal } : {},
+        ...args.goal ? { goal: String(args.goal) } : {},
         ...args.lift ? { minDetectableRelativeLift: Number(args.lift) } : {}
       });
       writeJsonEnvelope({
@@ -39411,9 +39364,9 @@ var startCommand = defineCommand119({
           // with no `--fork` succeeds and produces a page that renders exactly
           // the control, so the test would run for weeks against itself.
           ...composition && composition.forked.length === 0 ? [
-            `\u201C${String(args.variant)}\u201D does not have its own copy of any section \u2014 it renders exactly the same page as \u201C${String(args.landing)}\u201D, so this test cannot find anything. Fork the section you want to test (\`baker landing variant ${String(args.landing)} ${String(args.variant)} --fork Hero.astro\`) and edit only that file.`
+            `\u201C${String(args.variant)}\u201D does not have its own copy of any section \u2014 it renders exactly the same page as \u201C${String(args.landing)}\u201D, so this test cannot find anything. Fork the section you want to test (\`baker landing variant ${String(args.landing)} --fork Hero.astro\`) and edit only that file.`
           ] : [],
-          "Staged. The split starts when this session is published \u2014 publishing is the review of the alternative page.",
+          "Staged. The split starts when this session is published \u2014 publishing is the review of the new variant.",
           "Check it as often as you like \u2014 `baker experiment status` is safe to read at any moment and holds its error rate however often you ask. What is never safe is reading the numbers instead of the verdict: `keep_running` means this test cannot yet tell the two pages apart, whatever the rates happen to say today."
         ]
       });
@@ -39424,7 +39377,7 @@ var startCommand = defineCommand119({
 });
 registerSchema({
   command: "experiment.status",
-  description: "The verdict on every A/B test, running and finished",
+  description: "The verdict on every A/B test, running, paused and finished",
   args: {
     id: { type: "string", description: "One test, by its id", required: false },
     full: { type: "boolean", description: "Include the posteriors behind the verdict", required: false }
@@ -39433,7 +39386,7 @@ registerSchema({
 var statusCommand6 = defineCommand119({
   meta: {
     name: "status",
-    description: "The verdict on each test. Read `verdict` and nothing else to decide: keep_running | winner | no_difference | invalid | stopped_early_harmful. `summary` is one sentence you can show the client. The numbers under `--full` are for printing, never for deciding \u2014 a test that says keep_running has not finished, however good its numbers look."
+    description: "The verdict on each test. Read `verdict` and nothing else to decide: keep_running | winner | no_difference | invalid | stopped_early_harmful. `summary` is one sentence you can show the client, and `secondary` lists every other conversion the company counts on the same two arms \u2014 context, never a second decision. The numbers under `--full` are for printing, never for deciding \u2014 a test that says keep_running has not finished, however good its numbers look."
   },
   args: {
     id: { type: "string", description: "One test, by its id", required: false },
@@ -39457,44 +39410,88 @@ var statusCommand6 = defineCommand119({
 });
 registerSchema({
   command: "experiment.finish",
-  description: "End a test and send all its traffic to the surviving page",
+  description: "End a test now and send all its traffic to the version you name",
   args: {
-    id: { type: "string", description: "The test, by its id", required: true },
-    abandon: {
-      type: "boolean",
-      description: "Stop the test, keep the original page, and record no result. The only way to end a test that has not concluded \u2014 and it OVERRIDES a verdict if there is one, throwing that finding away. Do not pass it by reflex.",
-      required: false
+    id: ID_ARG,
+    keep: {
+      type: "string",
+      description: "Which version stays live: `original` or `variant`. Required \u2014 the verdict is a recommendation and this is the decision. A test that has not concluded can be ended too; it is recorded as inconclusive, never as a finding. Going against a verdict is allowed and is recorded as such.",
+      required: true
     }
   }
 });
 var finishCommand = defineCommand119({
   meta: {
     name: "finish",
-    description: "End a test and send all its traffic to whichever page survived. Only a test whose verdict has concluded can be finished with a result \u2014 a `keep_running` test can only be `--abandon`ed, which keeps the original page and records no finding. Promotion is a traffic change over two pages that were both already published and reviewed; it does not edit either page."
+    description: "End a test now and send all its traffic to the version you name. Takes effect within seconds \u2014 nothing to publish. Read `baker experiment status` first: `winner` says which version the numbers favour, `keep_running` means they have not spoken yet and ending records `inconclusive`. Keeping the variant owes a `fold`. A test staged in this session and not yet published is simply taken back off it."
   },
   args: {
-    id: { type: "string", description: "The test, by its id", required: true },
-    abandon: {
-      type: "boolean",
-      description: "Stop the test, keep the original page, and record no result. The only way to end a test that has not concluded \u2014 and it OVERRIDES a verdict if there is one, throwing that finding away. Do not pass it by reflex.",
-      required: false
+    id: ID_ARG,
+    keep: {
+      type: "string",
+      description: "Which version stays live: `original` or `variant`.",
+      required: true
     }
   },
   run: async ({ args }) => {
+    const keep = String(args.keep);
+    if (keep !== "original" && keep !== "variant") {
+      fail5("`--keep` is either `original` or `variant` \u2014 which version should everyone see from now on?");
+    }
     try {
-      const response = await apiPost("/api/experiments/finish", {
-        experimentId: String(args.id),
-        ...args.abandon === true ? { abandon: true } : {}
-      });
+      const response = await apiPost(
+        "/api/experiments/finish",
+        { experimentId: String(args.id), keep }
+      );
+      if ("unstaged" in response.data) {
+        writeJsonEnvelope({
+          ok: true,
+          data: response.data,
+          hints: ["That test had not been published yet, so it was taken back off this session. Nothing was split."]
+        });
+        return;
+      }
+      const data = response.data;
       writeJsonEnvelope({
         ok: true,
-        data: response.data,
+        data,
         hints: [
-          `Staged. All the traffic goes to the ${response.data.survivor === "variant" ? "alternative" : "original"} page when this session is published.`,
-          ...response.data.discardedVerdict ? [
-            `You abandoned a test that HAD concluded (${response.data.discardedVerdict}). The original page keeps the traffic and no result is recorded \u2014 the finding is gone. If that was not what you meant, run this again without --abandon.`
+          `Done. Everyone now sees the ${data.survivor === "variant" ? "new variant" : "original"}.`,
+          ...data.againstVerdict ? [
+            `You kept the ${data.survivor === "variant" ? "new variant" : "original"} although the numbers favoured the other version (${data.verdict}). That is recorded on the test \u2014 say why in the write-up.`
+          ] : [],
+          ...data.verdict === "keep_running" ? [
+            "This test had not concluded, so it is recorded as inconclusive \u2014 nobody found out. Never report it as no difference."
           ] : [],
-          "Then run `baker experiment fold` \u2014 it moves the winning version into the page itself and archives the other one, so the page's own content is what visitors get. Until that lands the page is served by a rewrite, and it cannot be tested again."
+          ...data.survivor === "variant" ? [
+            "Now run `baker experiment fold` \u2014 it moves the winning version into the page itself and archives the other one. Until that lands the page is served by a rewrite, and it cannot be tested again."
+          ] : []
+        ]
+      });
+    } catch (error) {
+      reportApiError(error);
+    }
+  }
+});
+registerSchema({
+  command: "experiment.pause",
+  description: "Switch a test's split off \u2014 everyone sees the original until it is resumed",
+  args: { id: ID_ARG }
+});
+var pauseCommand = defineCommand119({
+  meta: {
+    name: "pause",
+    description: "Switch the split off now. Everyone sees the original; visitors already assigned keep their side, so resuming continues the same test rather than starting a new one. Use it when the new variant has to come down for a while \u2014 a broken price, a campaign that needs the original \u2014 without throwing the test away."
+  },
+  args: { id: ID_ARG },
+  run: async ({ args }) => {
+    try {
+      await apiPost("/api/experiments/pause", { experimentId: String(args.id) });
+      writeJsonEnvelope({
+        ok: true,
+        data: { paused: true },
+        hints: [
+          `Paused. Everyone sees the original page now. \`baker experiment resume --id ${String(args.id)}\` restarts the split with the same sides.`
         ]
       });
     } catch (error) {
@@ -39502,6 +39499,30 @@ var finishCommand = defineCommand119({
     }
   }
 });
+registerSchema({
+  command: "experiment.resume",
+  description: "Switch a paused test's split back on",
+  args: { id: ID_ARG }
+});
+var resumeCommand = defineCommand119({
+  meta: {
+    name: "resume",
+    description: "Switch a paused test's split back on. Visitors already assigned see the same side they saw before."
+  },
+  args: { id: ID_ARG },
+  run: async ({ args }) => {
+    try {
+      await apiPost("/api/experiments/resume", { experimentId: String(args.id) });
+      writeJsonEnvelope({
+        ok: true,
+        data: { resumed: true },
+        hints: ["Resumed. Half the visitors see the new variant again."]
+      });
+    } catch (error) {
+      reportApiError(error);
+    }
+  }
+});
 registerSchema({
   command: "experiment.fold",
   description: "Make the page's own content the version that won, and archive the one that lost",
@@ -39563,12 +39584,14 @@ var foldCommand = defineCommand119({
 var experimentCommand = defineCommand119({
   meta: {
     name: "experiment",
-    description: "Run an A/B test between a landing page and an alternative version of it, and be told which one is better. Always `plan` first: most pages do not get enough traffic to settle most questions, and a test that cannot conclude still produces a number somebody will act on."
+    description: "Run an A/B test between a landing page and a new variant of it, and be told which one is better. Always `plan` first: most pages do not get enough traffic to settle most questions, and a test that cannot conclude still produces a number somebody will act on. Nothing ends a test on its own \u2014 `finish` does, when you or the client decide."
   },
   subCommands: {
     plan: planCommand,
     start: startCommand,
     status: statusCommand6,
+    pause: pauseCommand,
+    resume: resumeCommand,
     finish: finishCommand,
     fold: foldCommand
   }