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

package/README.md

@@ -1311,45 +1311,29 @@ Data is retained for 400 days; a window reaching further back comes back with a
 
 ### A/B tests (`baker experiment`)
 
-Two versions of one landing page, split 50/50 at the edge, decided by a verdict rather than by two rates somebody reads.
+Two versions of one landing page, split 50/50 at the edge, read on one of the conversions the company already counts, and decided by a person on a verdict rather than by two rates somebody reads.
 
 ```bash
 baker experiment plan --landing oferta --variant oferta--1        # FIRST — can this page settle the question at all?
-baker experiment plan --landing oferta --variant oferta--1 --goal event:request_demo
-baker experiment plan --landing oferta --variant oferta--1 --days 21          # what could 21 days settle?
+baker experiment plan --landing oferta --variant oferta--1 --goal "Booked a call"
 baker experiment start --landing oferta --variant oferta--1 --because "60% of visitors never scroll past the hero" --change "put the price in the headline"
 baker experiment status                                          # the verdict on every test
 baker experiment status --id a3f91c2b --full                     # one test, with the posteriors behind it
-baker experiment finish --id a3f91c2b                            # send all the traffic to whichever won
-baker experiment finish --id a3f91c2b --abandon                  # stop it, keep the page as it is, record no result
-baker experiment fold                                            # make the page's own content the version that won
+baker experiment pause --id a3f91c2b                             # everyone sees the original for now
+baker experiment resume --id a3f91c2b                            # the split picks up with the same sides
+baker experiment finish --id a3f91c2b --keep variant             # end it now; say which version stays
+baker experiment fold                                            # make the page's own content the version that was kept
 ```
 
-**A page has variants. A variant is never a page.** The variant is a real built folder at `src/pages/oferta--1/`, so it gets every quality gate a page gets — which matters, because it is about to be shown to half the client's visitors. What it does not get is a public address: it is absent from the Landings list and the sitemap, carries `noindex`, and `/oferta--1/` returns **404** at the edge. Both versions answer at `/oferta/`. Assignment happens while the HTML is served, so there is no flicker, no client JavaScript and nothing for an ad blocker to suppress, and the split is a path rewrite and never a redirect. To look at one side deliberately, `/oferta/?_bkr_preview=a` and `?_bkr_preview=b` serve it exactly, with no assignment and no cookie.
+**A page has variants. A variant is never a page.** The variant is a real built folder at `src/pages/oferta--1/`, so it gets every quality gate a page gets — which matters, because it is about to be shown to half the client's visitors. What it does not get is a public address: it is absent from the Landings list and the sitemap, carries `noindex`, and `/oferta--1/` returns **404** at the edge. Both versions answer at `/oferta/`. Assignment happens while the HTML is served, so there is no flicker and nothing for an ad blocker to suppress, and the split is a path rewrite and never a redirect. To look at one side deliberately, `/oferta/?_bkr_preview=a` and `?_bkr_preview=b` serve it exactly, with no assignment and no cookie.
 
-**Finishing takes two beats, and `fold` is the second.** `finish` records which version won, and the edge serves it to everyone within the hour — that is all a decision made with nobody present can do, because it has no workspace and cannot move a file. `baker experiment fold` moves the winning version into the page's own folder, archives the one that lost as a self-contained snapshot under `src/_variants/<page id>/<n>/`, and deletes the variant folder. Until it runs, the page is served by a rewrite while its own source renders the version that lost, and it cannot be tested again. Run `fold` with no arguments after any test ends, then publish; Baker drops the rewrite by itself once the new pages are live.
+**The goal is one of the company's conversions, by name.** `--goal "Booked a call"` — spelled as the Conversions screen spells it. It is fixed for the life of the test and the verdict is read on it alone. Every other conversion the company counts comes back under `secondary` on every result, with the same interval and a one-word reading, and decides nothing. A conversion counts for a visitor wherever it happens after they were shown a version — on the page, on another page, in a delivered lead, or in a deal the CRM posted a week later by email.
 
-**`--days` answers the other question.** You cannot set how long a test runs — the finish line is a visitor count fixed before it starts, and a horizon that moves is not a horizon. But `--days 21` says what a window that long *could* settle on this page's traffic: *"in 21 days this page could only settle a change of +31% or more"*. That turns a refusal into a brief, because the lever is the size of the change, not the calendar.
+**Nothing ends a test on its own.** `status` returns a verdict; `finish --keep original|variant` is the decision, and it takes effect within seconds with nothing to publish. Ending a `keep_running` test records `inconclusive`. Going against the verdict is allowed and recorded. `pause` and `resume` switch the split off and on without losing the test.
 
-**`plan` before building anything.** At a 3% conversion rate a +20% lift needs roughly 14,000 visitors *per variant*; most landing pages will never get there, and `plan` refuses rather than letting a test run for three weeks and report a conclusion made on noise. `--lift` sets the smallest lift worth detecting (default `0.2`), and it is the most consequential flag here — halving it roughly quadruples the traffic needed.
+**Finishing with the variant takes two beats, and `fold` is the second.** `finish --keep variant` records which version is live and the edge serves it to everyone at once. `baker experiment fold` moves that version into the page's own folder, archives the one that lost as a self-contained snapshot under `src/_variants/<page id>/<n>/`, and deletes the variant folder. Until it runs, the page is served by a rewrite and cannot be tested again. Run `fold` with no arguments after any test ends, then publish; Baker drops the rewrite by itself once the new pages are live.
 
-**`--goal` decides what "better" means, and it is fixed for the life of the test.**
-
-| `--goal` | Counts |
-|---|---|
-| `leads` (default) | Whatever this company already marks as a conversion |
-| `leads:<form>` | The same, one Form only |
-| `event:<name>` | An event the page declares for itself (`data-baker-click="request_demo"`) |
-| `event:<name>/<key>=<value>` | The same, narrowed by one of its own properties |
-| `click` / `click:<host>` | Leaving the site, optionally for one destination |
-
-`baker analytics events` lists what a page already reports. A goal that has never fired on the page is **refused**, not run — it would return zero on both sides forever, and that reads as a tie rather than as "not measured".
-
-**Read `verdict` and nothing else** to decide: `keep_running` | `winner` | `no_difference` | `invalid` | `stopped_early_harmful`. `summary` is one sentence fit to show a client. The numbers under `--full` are for printing — a test that says `keep_running` has not finished however good they look, and only `finish` on a concluded test can record a result.
-
-**`--abandon` overrides the verdict.** It stops the test, keeps the original page and records no result — the only way to end one that has not concluded, and it applies even when the test *has*. That is deliberate: the only outcome it can disagree with is a variant win, so deferring to the verdict would mean a flag asking to keep the original page handed all the traffic to the alternative instead. The response reports `discardedVerdict` when a real finding was thrown away.
-
-Nothing goes live until the session is published: starting stages onto the session, and the person publishing is the review of the variant page.
+**`plan` before building anything.** At a 3% conversion rate a +20% lift needs roughly 14,000 visitors *per variant*; most landing pages will never get there, and `plan` refuses rather than letting a test run for three weeks and report a conclusion made on noise. It also lists what this page's visitors actually went on to do, and what a 14, 28, 56 or 90-day window could settle. `--lift` sets the smallest lift worth detecting (default `0.2`) — halving it roughly quadruples the traffic needed.
 
 ### Google Analytics 4 (`baker ga4`)