@koda-sl/baker-cli 0.237.0-dev.b9732c021 → 0.238.0-dev.43aacdb9e

package/README.md

@@ -1227,6 +1227,42 @@ 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.
+
+```bash
+baker experiment plan --landing oferta --variant oferta-b        # FIRST — can this page settle the question at all?
+baker experiment plan --landing oferta --variant oferta-b --goal event:request_demo
+baker experiment start --landing oferta --variant oferta-b --hypothesis "Price above the fold converts better"
+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 original page, record no result
+```
+
+The variant is an ordinary published landing with its own slug. 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 visitor's URL still reads `/oferta/`, because the split is a path rewrite and never a redirect. A direct visit to `/oferta-b/` is served that page with **no** assignment and stays out of the measurement, so a shared link cannot stuff one arm.
+
+**`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.
+
+**`--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.
+
 ### Google Analytics 4 (`baker ga4`)
 
 GA4 commands for multi-channel audits **and** for configuring what the property measures. Playbook-aligned report presets, property health audits, free-form Data API queries, and staged Admin API writes.