@wrangled/cli 0.3.162 → 0.3.164

package/dist/guide.js

@@ -7,17 +7,30 @@ import { PULL_STATE_FILE } from "./pull.js";
 const cli = brand.slug;
 /** The funnel test the guide shows; the app's parser must accept it (src/lib/cli-consistency.test.ts). */
 export const funnelTestExample = {
-    hypothesis: "A video at the top of the sign-up page will get more people to sign up, because buyers on calls say they did not know what the webinar was about.",
+    name: "Video at the top of the sign-up page",
     funnel_key: "webinar",
     step_key: "signup",
-    variable: "top of the page: letter to video",
-    control: { label: "letter at the top", url: "https://example.com/signup" },
-    variants: [{ label: "video at the top", url: "https://example.com/signup-video" }],
-    metric: "step_conversion",
-    expected_change: "sign-ups per visitor from 22% to 26%",
-    min_people_per_arm: 400,
-    split_method: "adzara_ads",
+    change: "top of the page: letter to video",
+    because: "Buyers on sales calls say they did not know what the webinar was about, and sign-ups per visitor fell from 30% to 22% this month.",
+    audience: "new visitors from Facebook ads",
+    expected_lift: 0.18,
+    prediction_confidence: "medium",
+    disproved_if: "sign-ups per visitor rise less than 5% after 400 people each side",
     evidence: [{ kind: "customer_words", ref: "sales call 2026-09-30", note: "I didn't know what the webinar was about." }],
+    design_type: "ad_split_duplicated",
+    metric: "step_conversion",
+    unit: "people",
+    guardrails: ["cost per sale"],
+    baseline_rate: 0.22,
+    baseline_from: "2026-09-01",
+    baseline_to: "2026-09-30",
+    min_lift: 0.1,
+    people_per_arm: 400,
+    decision_rule: "Scale the video if sign-ups per visitor rise at least 10% with cost per sale no worse.",
+    elements: ["hero"],
+    levers: ["clarity"],
+    control: { label: "letter at the top", content: "A letter from the founder: why this webinar exists.", url: "https://example.com/signup" },
+    variants: [{ label: "video at the top", content: "A 90-second video of the founder saying what the webinar covers.", url: "https://example.com/signup-video" }],
 };
 /** The dashboard the guide shows; the app's parser must accept it (src/lib/cli-consistency.test.ts). */
 export const dashboardExample = {
@@ -90,7 +103,7 @@ ${brand.name} writes and sends no emails or texts; the client's own tool (GoHigh
 
 ## What winners and flops taught: lessons
 
-Lessons are short plain sentences about why the winners won and the flops flopped, such as "Ads that open with a retiree's own money worry beat ads that open with a statistic: 4 of the top 5 this week, cost per sale $180 vs $410." A finished page or funnel test, something learned about a funnel step, or a follow-up email, text or sequence that helps sales makes a lesson too. Each lists what proves it: ads, pages, funnel steps, tests, emails, texts or sequences. A lesson that holds on an ad and an email is one lesson with both as proof. Read them before writing ads or pages: \`${cli} lessons\` lists the ones that hold, the most often seen first (\`--status retired\` lists the ones no longer true, with why; \`--about ads|pages|funnel|messages\` only the ones with a proof of that kind, \`--about cross_channel\` only the ones proven on two or more of ads, pages and messages; \`--dimension <d>\`, repeatable, only the ones along that dimension), and the brief carries them too. No person approves a lesson.
+Lessons are short plain sentences about why the winners won and the flops flopped, such as "Ads that open with a retiree's own money worry beat ads that open with a statistic: 4 of the top 5 this week, cost per sale $180 vs $410." A finished page or funnel test, something learned about a funnel step, or a follow-up email, text or sequence that helps sales makes a lesson too. Each lists what proves it: ads, pages, funnel steps, tests, emails, texts or sequences. A lesson that holds on an ad and an email is one lesson with both as proof. Read them before writing ads or pages: \`${cli} lessons\` lists the ones that hold, the most often seen first (\`--status retired\` lists the ones no longer true, with why; \`--about ads|pages|funnel|messages\` only the ones with a proof of that kind, \`--about cross_channel\` only the ones proven on two or more of ads, pages and messages; \`--dimension <d>\`, repeatable, only the ones along that dimension), and the brief carries them too. No person approves a lesson. Lessons are kept in the workspace's warehouse table \`lessons\`, so you can join them with the tests and numbers behind them in one query: \`${cli} warehouse query "SELECT text, dimension, status FROM lessons"\`.
 
 Write one as JSON, \`{"text": "...", "dimension": "hook", "evidence": [{"ad": "<Meta ad id or SKU>", "numbers": "cost per sale $180 vs $410"}], "week": "2026-09-28"}\`, and run \`${cli} lessons add --file lesson.json\`. Each proof names exactly one of \`ad\`, \`page\` (a page's URL, kept as its page key, or a content item id), \`step\` (\`<funnel_key>.<step_key>\`), \`test\` (a funnel test id or Adzara test_id), \`message\` (an email or text's content item id, or its SKU, kept as its item id; one the content library does not have is refused) or \`sequence\` (\`ghl:<workflow id>\` or \`klaviyo:<flow id>\`), with its \`numbers\`. \`dimension\` (hook, angle, format, offer, persona, page, funnel_step, follow_up or other) and \`week\` (any day of the winners report's week; default the latest complete week) are optional. A lesson with the same words that still holds, or the one named in \`"reinforces": "<id>"\`, is reinforced instead of copied: it counts once more for a week it had not counted, so running the same week again changes no count. \`${cli} lessons retire <id> --note "<why>"\` retires one the numbers no longer back; it is kept with why. The \`lessons\` playbook (\`${cli} skill install lessons\` installs it as the \`${LESSONS_SKILL_NAME}\` skill) writes the week's lessons from the winners report.
 
@@ -102,17 +115,21 @@ Write one as JSON, \`{"text": "...", "dimension": "hook", "evidence": [{"ad": "<
 
 The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it as the \`${WEEKLY_LOOP_SKILL_NAME}\` skill; \`${cli} docs weekly-loop\` prints it) is a sample to borrow from, not a schedule, for a local agent that runs a client's Facebook ads with its owner: its steps can run daily, several times a week or weekly, and the winners report covers whatever dates are asked for. It names the command and the MCP tool for each step: the winners and flops report, lessons, fresh customer words, the brief, the offers and funnels map, making ads (Exodus, paid tools or the agent's own skills), publishing approved ads, pauses and budget changes with ${brand.name}'s Meta commands, and the results of what was published (Adzara's labels for ads it published before the switch). Judge winners by ${brand.name}'s Winners and flops report, which judges each client on its goal (\`${cli} winners\`); Meta's own results are Meta's count. Approvals and decisions happen in the agent's own session with the owner; ${brand.name} records none. Ads are published and changed through ${brand.name}'s Meta commands, only after the owner approves and only inside the client's control list.
 
-## Trying one change: funnel tests
+## Trying one change: tests
+
+A test writes down one change to a page or funnel step, tried against what runs now. Each test is kept in the workspace's warehouse, in \`cro_tests\` (one row per test), \`cro_test_arms\` (its sides) and \`cro_test_events\` (its history), so you can join tests with visits, sign-ups and sales in one query: \`${cli} warehouse query "SELECT test_id, status, elements FROM cro_tests"\`.
+
+A test moves through these stages: \`idea\` (only the one change and where are needed), \`planned\` (the full plan is in and the owner said yes), \`running\` (its plan is frozen), then \`decided\`, \`abandoned\` or \`invalid\` (the tracking broke or traffic did not split as planned). Where is a funnel step (\`funnel_key\` and \`step_key\` from the funnels map), a page by its address (\`page_url\`, even one not on the map yet), or both. The full plan is: \`because\` (what led to the idea), \`audience\`, \`expected_lift\` (relative, 0.18 for 18%), \`prediction_confidence\` (low, medium or high), \`disproved_if\`, \`design_type\` (how traffic is split: ad_split_randomized, Meta's own A/B test; ad_split_duplicated, two copies of a campaign, one to each page, which is not a true random split; tool_split, inside a page builder or webinar tool named in a \`design_note\`; link_split; before_after; or adaptive), \`traffic\` (\`{campaigns, optimization_goal, note}\`: which campaigns feed it and what they optimize for, frozen with the plan), \`metric\` (step_conversion, which needs a step, sales_per_visitor, revenue_per_visitor, cost_per_sale or cost_per_lead, spend per sign-up) and \`unit\` (people or sessions), \`guardrails\` (numbers that must not get worse), \`baseline_rate\` with \`baseline_from\` and \`baseline_to\`, \`min_lift\`, \`people_per_arm\`, \`min_days\` and \`max_days\` (14 and 56 unless set), \`decision_rule\`, \`concurrent_changes\`, and the control and 1 to 3 \`variants\`, each with the exact \`content\` it shows and, when a tool runs the split, its \`platform_ref\` (the tool's own id for the side). Tags come from fixed lists: \`elements\` (what changes: headline, subheadline, hero, call_to_action, form, offer, price, guarantee, proof, urgency, page_length, layout, checkout, order_bump, follow_up, tool_or_platform, other) and \`levers\` (why it should work: clarity, relevance, trust, value, urgency, less_effort, motivation, other). \`ice_impact\`, \`ice_confidence\` and \`ice_ease\` (1 to 10) sort the idea list. \`evidence\` quotes the proof, each \`{kind, ref, note}\`, kind one of leak, lesson, customer_words, page, ad or other. A test changes one thing: a \`change\` naming two is refused.
 
-A funnel test writes down one change to a page or funnel step, tried against what runs now: the idea, the funnel and step (\`funnel_key\` and \`step_key\` from the funnels map), the one thing that changes, the control and 1 to 3 changed versions, the number that judges it (\`metric\`: step_conversion, sales_per_visitor, revenue_per_visitor or cost_per_sale) with the change expected and the people each side needs, how traffic is split (\`split_method\`: adzara_ads, before_after, or other with a \`split_note\`), and the evidence it should work (each \`{kind, ref, note}\`, kind one of leak, lesson, customer_words, page, ad or other). A test changes one thing: a \`variable\` naming two is refused, and so is a test with no metric.
+Write it as JSON, such as \`${JSON.stringify(funnelTestExample)}\`, and run \`${cli} tests draft --file test.json\`. It gets Adzara-style labels from the change and this month (\`hyp-<slug>\` and \`test-<yyyy-mm>-<slug>\`); give \`hypothesis_id\` and \`test_id\` to reuse Adzara's own, so the results of the ads Adzara published for the test (\`ad_test_results_daily\`, \`ad_hypothesis_results_daily\`) join on the same label. \`${cli} tests edit <test_id> --file changes.json\` changes some fields (null clears one). ${brand.name} shows no approval screen: ask the owner in your own session, then record the yes with \`${cli} tests plan <test_id> --approved-by "<owner>"\`, which refuses a plan with a gap and names every missing field. \`${cli} tests start <test_id>\` marks a planned test as running from today and freezes its plan; an edit after that is still saved, and its history and results say so. Starting changes nothing live: the page still goes live through its own approval, and the ads through ${brand.name}'s Meta commands. Until #2202, an ad split test can be measured only on ads Adzara made before the switch, because its sides are counted from Adzara's labels; a \`before_after\` test still works. \`${cli} tests abandon <test_id> --note "<why>"\` drops one that has not ended, \`${cli} tests invalidate <test_id> --note "<what went wrong>"\` ends a running one whose numbers cannot be trusted, and \`${cli} tests note <test_id> --note "<note>"\` adds to its history. \`${cli} tests [--status <status>] [--funnel <funnel_key>] [--limit <n>]\` lists them, newest first (50 unless \`--limit\`, at most 200), and \`${cli} tests show <test_id>\` shows one with its history.
 
-Write it as JSON, such as \`${JSON.stringify(funnelTestExample)}\`, and run \`${cli} tests draft --file test.json\`. It gets Adzara-style labels from the change and this month (\`hyp-<slug>\` and \`test-<yyyy-mm>-<slug>\`); give \`hypothesis_id\` and \`test_id\` to reuse Adzara's own, so the results of the ads Adzara published for the test (\`ad_test_results_daily\`, \`ad_hypothesis_results_daily\`) join on the same label. Approving a test happens outside ${brand.name} for now. \`${cli} tests start <test_id>\` marks a draft as running from today, and changes nothing live: the page still goes live through its own approval, and the ads through ${brand.name}'s Meta commands. Until #2202, an \`adzara_ads\` test can be measured only on ads Adzara made before the switch, because its sides are counted from Adzara's labels; a \`before_after\` test still works. \`${cli} tests abandon <test_id> --note "<why>"\` drops a draft or running test. \`${cli} tests [--status <status>] [--funnel <funnel_key>] [--limit <n>]\` lists them, newest first (50 unless \`--limit\`, at most 200), and \`${cli} tests show <test_id>\` shows one.
+A test that already ran, such as one from before ${brand.name}, goes in with \`logged_after: true\` and its \`started_on\` and \`ended_on\`; it goes straight from idea to decided with \`${cli} tests decide <test_id> --decision <d> --outcome <o>\`.
 
-\`${cli} tests results <test_id>\` reads a started test: each side's people, how many moved on to the next step, how many of those people bought (each once, however many times they bought) and what they paid, spend and the test's metric, over the days since it started (a \`before_after\` test compares the same number of days before it started). People are counted by their first visit: the landing page they arrived on, or the Adzara ad (by \`asset_version\` and the test's \`test_id\`) that brought them; a page no one's first visit was recorded on is counted by its site visitors instead. Then it says plainly whether the test can be called yet: "Not enough people yet: 210 of the 400 each side needs.", "Video at the top is ahead, 36% vs 30%, and that gap is big enough to trust." or "No real difference after 900 people each side". A gap counts when a two-proportion test says it is real at 95%; cost per sale and revenue per visitor are judged on sales per visitor under them.
+\`${cli} tests results <test_id>\` reads a started test: each side's people, how many moved on to the next step, how many of those people bought (each once, however many times they bought) and what they paid, spend and the test's metric, over the days since it started (a \`before_after\` test compares the same number of days before it started). People are counted by their first visit: the landing page they arrived on, or the Adzara ad (by \`asset_version\` and the test's \`test_id\`) that brought them; a page no one's first visit was recorded on is counted by its site visitors instead. Then it says plainly whether the test can be called yet: "Not enough people yet: 210 of the 400 each side needs.", "Video at the top is ahead, 36% vs 30%, and that gap is big enough to trust." or "No real difference after 900 people each side". A gap counts when a two-proportion test says it is real at 95%; cost per sale and revenue per visitor are judged on sales per visitor under them, and cost per lead on sign-ups per visitor.
 
-\`${cli} tests decide <test_id> --decision <d> --note "<why>"\` records the decision on a running test: \`scale\` (the new version won; use it everywhere), \`continue\` (keep running), \`iterate\` (promising; it also drafts a sharper version linked to this one), \`hold\` (pause it; something outside the test got in the way) or \`stop\` (it lost or made no difference). Each decision writes a lesson with the test, its pages and its step as proof. Deciding changes nothing live: switching a page or ads still goes through approval.
+\`${cli} tests decide <test_id> --decision <d> --outcome <won|lost|inconclusive|invalid> --note "<why>"\` records the decision on a running test: \`scale\` (the new version won; use it everywhere), \`continue\` (keep running), \`iterate\` (promising; it also writes down a sharper version linked to this one), \`hold\` (pause it; something outside the test got in the way) or \`stop\` (it lost or made no difference). scale, iterate and stop need \`--outcome\`. Each decision writes a lesson with the test, its pages and its step as proof, in one go with the decision. Deciding changes nothing live: switching a page or ads still goes through approval.
 
-The \`cro\` playbook (\`${cli} skill install cro\` installs it as the \`${CRO_SKILL_NAME}\` skill; \`${cli} docs cro\` prints it) runs this once a week: it turns the costliest leaks from \`${cli} funnels leaks\` into at most 3 test drafts, each with one change and its proof, for the owner to approve in the agent's own session, and reads the tests already running. It never publishes, edits a live page, or touches ads or messages.
+The \`cro\` playbook (\`${cli} skill install cro\` installs it as the \`${CRO_SKILL_NAME}\` skill; \`${cli} docs cro\` prints it) runs this once a week: it turns the costliest leaks from \`${cli} funnels leaks\` into at most 3 test ideas, each with one change, its full plan and its proof, for the owner to approve in the agent's own session, and reads the tests already running. It never publishes, edits a live page, or touches ads or messages.
 
 ## Content: search before SQL
 

package/dist/main.js

@@ -3220,32 +3220,55 @@ const commands = {
         },
     },
     "tests show": {
-        usage: "tests show <id|test_id>   one funnel test in full",
+        usage: "tests show <test_id>   one funnel test in full, with its history",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: tests show <id|test_id>", exitCodes.usage);
-            const { test } = await api(await resolveConnection(options), testPath(args[0]));
+                throw new CliError("Usage: tests show <test_id>", exitCodes.usage);
+            const shown = await api(await resolveConnection(options), testPath(args[0]));
             if (options.format === "json")
-                return printJson({ test });
-            printTest(test);
+                return printJson(shown);
+            printTest(shown.test, shown.events);
         },
     },
     "tests draft": {
-        usage: "tests draft --file <test.json> | < test.json   write down a funnel test: one change against a control, a metric and the evidence",
+        usage: "tests draft --file <test.json> | < test.json   write down a test idea: the one change and where (a funnel step or a page); the rest of the plan may come later with tests edit",
         async run(args, options) {
             if (args.length > 0)
                 throw new CliError("Usage: tests draft --file <test.json> | < test.json", exitCodes.usage);
             const { test } = await api(await resolveConnection(options), TESTS_PATH, await readToolInput(options));
             if (options.format === "json")
                 return printJson({ test });
-            console.log(`Drafted test ${test.test_id} (${test.id}).`);
+            console.log(`Wrote down test ${test.test_id} as an idea.`);
+        },
+    },
+    "tests edit": {
+        usage: "tests edit <test_id> --file <changes.json> | < changes.json   change some of a test's fields (null clears one); a change to the plan after the start is kept and marked in its history",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: tests edit <test_id> --file <changes.json> | < changes.json", exitCodes.usage);
+            const { test } = await api(await resolveConnection(options), testPath(args[0]), await readToolInput(options), "PATCH");
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Changed test ${test.test_id} (${test.status}).`);
+        },
+    },
+    "tests plan": {
+        usage: 'tests plan <test_id> --approved-by "<owner>" [--note "<what they said>"]   record the owner\'s yes to a test\'s full plan, after asking them in your session',
+        async run(args, options) {
+            if (args.length !== 1 || !options.approvedBy)
+                throw new CliError('Usage: tests plan <test_id> --approved-by "<owner>" [--note "<what they said>"]', exitCodes.usage);
+            const body = { approved_by: options.approvedBy, ...(options.note ? { note: options.note } : {}) };
+            const { test } = await api(await resolveConnection(options), `${testPath(args[0])}/plan`, body);
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Test ${test.test_id} is planned; ${options.approvedBy} said yes.`);
         },
     },
     "tests start": {
-        usage: "tests start <id|test_id>   mark a draft test as running from today; nothing goes live",
+        usage: "tests start <test_id>   mark a planned test as running from today and freeze its plan; nothing goes live",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: tests start <id|test_id>", exitCodes.usage);
+                throw new CliError("Usage: tests start <test_id>", exitCodes.usage);
             const { test } = await api(await resolveConnection(options), `${testPath(args[0])}/start`, {});
             if (options.format === "json")
                 return printJson({ test });
@@ -3253,21 +3276,43 @@ const commands = {
         },
     },
     "tests abandon": {
-        usage: 'tests abandon <id|test_id> [--note "<why>"]   drop a test that has not ended',
+        usage: 'tests abandon <test_id> [--note "<why>"]   drop a test that has not ended',
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError('Usage: tests abandon <id|test_id> [--note "<why>"]', exitCodes.usage);
+                throw new CliError('Usage: tests abandon <test_id> [--note "<why>"]', exitCodes.usage);
             const { test } = await api(await resolveConnection(options), `${testPath(args[0])}/abandon`, options.note ? { note: options.note } : {});
             if (options.format === "json")
                 return printJson({ test });
             console.log(`Abandoned test ${test.test_id}.`);
         },
     },
+    "tests invalidate": {
+        usage: 'tests invalidate <test_id> --note "<what went wrong>"   end a running test whose tracking broke or whose traffic did not split as planned',
+        async run(args, options) {
+            if (args.length !== 1 || !options.note)
+                throw new CliError('Usage: tests invalidate <test_id> --note "<what went wrong>"', exitCodes.usage);
+            const { test } = await api(await resolveConnection(options), `${testPath(args[0])}/invalidate`, { note: options.note });
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Test ${test.test_id} is invalid from ${test.ended_on}.`);
+        },
+    },
+    "tests note": {
+        usage: 'tests note <test_id> --note "<note>"   add a note to a test\'s history',
+        async run(args, options) {
+            if (args.length !== 1 || !options.note)
+                throw new CliError('Usage: tests note <test_id> --note "<note>"', exitCodes.usage);
+            const { events } = await api(await resolveConnection(options), `${testPath(args[0])}/notes`, { note: options.note });
+            if (options.format === "json")
+                return printJson({ events });
+            console.log(`Noted on test ${args[0]}.`);
+        },
+    },
     "tests results": {
-        usage: "tests results <id|test_id>   a started test's numbers per side and whether it can be called yet",
+        usage: "tests results <test_id>   a started test's numbers per side and whether it can be called yet",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: tests results <id|test_id>", exitCodes.usage);
+                throw new CliError("Usage: tests results <test_id>", exitCodes.usage);
             const { results } = await api(await resolveConnection(options), `${testPath(args[0])}/results`);
             if (options.format === "json")
                 return printJson({ results });
@@ -3275,20 +3320,26 @@ const commands = {
         },
     },
     "tests decide": {
-        usage: 'tests decide <id|test_id> --decision <scale|continue|iterate|hold|stop> [--note "<why>"]   record the decision on a running test, with its lesson; nothing goes live',
+        usage: 'tests decide <test_id> --decision <scale|continue|iterate|hold|stop> [--outcome <won|lost|inconclusive|invalid>] [--note "<why>"] [--learning "<what it taught>"]   record the decision, with its lesson; scale, iterate and stop need --outcome; nothing goes live',
         async run(args, options) {
-            if (args.length !== 1 || !options.decision) {
-                throw new CliError('Usage: tests decide <id|test_id> --decision <scale|continue|iterate|hold|stop> [--note "<why>"]', exitCodes.usage);
-            }
-            const decided = await api(await resolveConnection(options), `${testPath(args[0])}/decide`, options.note ? { decision: options.decision, note: options.note } : { decision: options.decision });
+            const usage = 'Usage: tests decide <test_id> --decision <scale|continue|iterate|hold|stop> [--outcome <won|lost|inconclusive|invalid>] [--note "<why>"] [--learning "<what it taught>"]';
+            if (args.length !== 1 || !options.decision)
+                throw new CliError(usage, exitCodes.usage);
+            const body = {
+                decision: options.decision,
+                ...(options.outcome ? { outcome: options.outcome } : {}),
+                ...(options.note ? { note: options.note } : {}),
+                ...(options.learning ? { learning: options.learning } : {}),
+            };
+            const decided = await api(await resolveConnection(options), `${testPath(args[0])}/decide`, body);
             if (options.format === "json")
                 return printJson(decided);
             const { test, lesson, next_test: next } = decided;
             console.log(test.decision === options.decision
-                ? `Test ${test.test_id}: ${test.decision}, now ${test.status}. Lesson ${lesson.id}.`
+                ? `Test ${test.test_id}: ${test.decision}${test.outcome ? ` (${test.outcome})` : ""}, now ${test.status}. Lesson ${lesson.id}.`
                 : `Test ${test.test_id}: ${options.decision} recorded; it stays ${test.status} (${test.decision}). Lesson ${lesson.id}.`);
             if (next)
-                console.log(`Drafted the next version as ${next.test_id} (${next.id}).`);
+                console.log(`Wrote down the next version as ${next.test_id}.`);
         },
     },
     "lessons retire": {
@@ -4746,32 +4797,73 @@ const RULE_LIST_IDS = ["banned_claims", "words_to_avoid", "required_disclaimers"
 const VOICE_SUGGESTIONS_PATH = "/api/v1/voice-lists/suggestions";
 const LESSONS_PATH = "/api/v1/lessons";
 const TESTS_PATH = "/api/v1/funnel-tests";
-const TEST_COLUMNS = ["test_id", "status", "funnel", "step", "change", "metric"];
+const TEST_COLUMNS = ["test_id", "status", "where", "change", "metric"];
 const testPath = (ref) => `${TESTS_PATH}/${encodeURIComponent(ref)}`;
 function testRow(t) {
-    return { test_id: t.test_id, status: t.status, funnel: t.funnel_key, step: t.step_key, change: excerpt(t.variable, 50), metric: t.metric };
-}
-function printTest(t) {
-    const arm = (a) => [a.label, a.page && `page ${a.page}`, a.url, a.item_id && `item ${a.item_id}`, a.asset_version && `version ${a.asset_version}`].filter(Boolean).join(" · ");
+    return { test_id: t.test_id, status: t.status, where: testWhere(t), change: excerpt(t.change, 50), metric: t.metric ?? "" };
+}
+const testWhere = (t) => [t.step_key && `${t.funnel_key} / ${t.step_key}`, t.page_key].filter(Boolean).join(", ");
+function printTest(t, events) {
+    const arm = (a) => [
+        a.label,
+        a.page_key ?? a.url,
+        a.item_id && `item ${a.item_id}`,
+        a.asset_version && `version ${a.asset_version}`,
+        a.platform_ref && `tool id ${a.platform_ref}`,
+        a.weight !== null && `${Math.round(a.weight * 100)}% of traffic`,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const pct = (n) => (n === null ? null : `${Math.round(n * 1000) / 10}%`);
+    const line = (label, value) => (value === null || value === undefined || value === "" ? [] : [`${label}: ${value}`]);
+    const variants = t.arms.filter((a) => a.arm !== "control");
     const lines = [
-        `${t.test_id} (${t.status})   idea ${t.hypothesis_id}   id ${t.id}`,
-        `Idea: ${t.hypothesis}`,
-        `Where: ${t.funnel_key} / ${t.step_key}`,
-        `The one change: ${t.variable}`,
-        `Stays the same: ${arm(t.control)}`,
-        ...t.variants.map((v, i) => `${t.variants.length === 1 ? "Changed" : `Changed ${i + 1}`}: ${arm(v)}`),
-        `Judged by: ${t.metric}, ${t.expected_change}, ${t.min_people_per_arm} people each side`,
-        `Split: ${t.split_method}${t.split_note ? `, ${t.split_note}` : ""}`,
-        "Evidence:",
-        ...t.evidence.map((e) => `  ${e.kind}: ${e.ref}${e.note ? ` (${e.note})` : ""}`),
+        `${t.test_id} (${t.status})   idea ${t.hypothesis_id}${t.logged_after ? "   written down after it ran" : ""}`,
+        ...line("Name", t.name === t.change ? null : t.name),
+        `Where: ${testWhere(t)}`,
+        `The one change: ${t.change}`,
+        ...line("Because", t.because),
+        ...line("Who sees it", t.audience),
+        ...line("Expected lift", pct(t.expected_lift) && `${pct(t.expected_lift)}${t.prediction_confidence ? `, ${t.prediction_confidence} confidence` : ""}`),
+        ...line("Wrong if", t.disproved_if),
+        ...t.arms.filter((a) => a.arm === "control").map((a) => `Stays the same: ${arm(a)}`),
+        ...variants.map((v, i) => `${variants.length === 1 ? "Changed" : `Changed ${i + 1}`}: ${arm(v)}`),
+        ...t.arms.filter((a) => a.content !== null).map((a) => `  ${a.arm} shows: ${excerpt(a.content, 100)}`),
+        ...line("Split", t.design_type && `${t.design_type}${t.design_note ? `, ${t.design_note}` : ""}`),
+        ...line("Judged by", t.metric && `${t.metric} by ${t.unit ?? "people"}${t.people_per_arm ? `, ${t.people_per_arm} each side` : ""}, ${t.min_days} to ${t.max_days} days`),
+        ...line("Today", pct(t.baseline_rate) && `${pct(t.baseline_rate)} from ${t.baseline_from} to ${t.baseline_to}; smallest lift worth finding ${pct(t.min_lift)}`),
+        ...line("Must not get worse", t.guardrails.join(", ")),
+        ...line("Decision rule", t.decision_rule),
+        ...line("Also changing", t.concurrent_changes),
+        ...line("Traffic", t.traffic && [t.traffic.campaigns?.length && `campaigns ${t.traffic.campaigns.join(", ")}`, t.traffic.optimization_goal && `optimized for ${t.traffic.optimization_goal}`, t.traffic.note].filter(Boolean).join("; ")),
+        ...line("Tags", [...t.elements, ...t.levers].join(", ")),
+        ...line("ICE", t.ice_impact !== null || t.ice_confidence !== null || t.ice_ease !== null ? `${t.ice_impact ?? "-"} / ${t.ice_confidence ?? "-"} / ${t.ice_ease ?? "-"}` : null),
+        ...(t.evidence.length > 0 ? ["Evidence:", ...t.evidence.map((e) => `  ${e.kind}: ${e.ref}${e.note ? ` (${e.note})` : ""}`)] : []),
+        ...line("Started", t.started_on && `${t.started_on}${t.ended_on ? `, ended ${t.ended_on}` : ""}`),
+        ...line("Decided", t.decision && `${t.decision}${t.outcome ? `, ${t.outcome}` : ""}`),
+        ...line("Note", t.decision_note),
+        ...line("Learned", t.learning),
     ];
-    if (t.started_on)
-        lines.push(`Started: ${t.started_on}${t.ended_on ? `, ended ${t.ended_on}` : ""}`);
-    if (t.decision_note)
-        lines.push(`Note: ${t.decision_note}`);
+    if (events.length > 0)
+        lines.push("History:", ...events.map((e) => `  ${e.at.slice(0, 16).replace("T", " ")}  ${eventWords(e)}  (${e.author})`));
     console.log(lines.join("\n"));
 }
-const RESULT_COLUMNS = ["side", "label", "counted by", "people", "moved on", "buyers", "revenue", "spend", "metric", "dates"];
+function eventWords(e) {
+    const d = e.detail;
+    switch (e.kind) {
+        case "created":
+            return "written down";
+        case "edited":
+            return `changed ${Object.keys(d.fields ?? {}).join(", ")}${d.after_start ? " after it started" : ""}`;
+        case "status":
+            return `${d.from} to ${d.to}${d.approved_by ? `, ${d.approved_by} said yes` : ""}${d.note ? `: ${d.note}` : ""}`;
+        case "note":
+            return `note: ${d.note}`;
+        case "decided":
+            return `decided ${d.decision}${d.outcome ? ` (${d.outcome})` : ""}${d.note ? `: ${d.note}` : ""}`;
+    }
+}
+const RESULT_COLUMNS = ["side", "label", "counted by", "people", "moved on", "sign-ups", "buyers", "revenue", "spend", "metric", "dates"];
 function printResults(r) {
     const money = (n, currency) => (n === null ? "" : `${n.toFixed(2)}${currency ? ` ${currency}` : ""}`);
     const rows = r.arms.map((a) => ({
@@ -4780,13 +4872,14 @@ function printResults(r) {
         "counted by": a.counted_by,
         people: a.people,
         "moved on": a.moved_on ?? "",
+        "sign-ups": a.leads ?? "",
         buyers: a.buyers ?? "",
         revenue: money(a.revenue, a.currency),
         spend: money(a.spend, a.currency),
-        metric: a.metric_value === null ? "" : r.test.metric === "cost_per_sale" || r.test.metric === "revenue_per_visitor" ? money(a.metric_value, a.currency) : `${(a.metric_value * 100).toFixed(1)}%`,
+        metric: a.metric_value === null ? "" : r.test.metric === "cost_per_sale" || r.test.metric === "cost_per_lead" || r.test.metric === "revenue_per_visitor" ? money(a.metric_value, a.currency) : `${(a.metric_value * 100).toFixed(1)}%`,
         dates: `${a.window.from} to ${a.window.to}`,
     }));
-    const lines = [`${r.test.test_id} (${r.test.status})   judged by ${r.test.metric}, ${r.test.min_people_per_arm} people each side`, renderTable(RESULT_COLUMNS, rows), "", ...r.calls.map((c) => c.words)];
+    const lines = [`${r.test.test_id} (${r.test.status})   judged by ${r.test.metric ?? "no main number"}, ${r.test.people_per_arm ?? "no count of"} people each side`, renderTable(RESULT_COLUMNS, rows), "", ...r.calls.map((c) => c.words)];
     if (r.caveats.length > 0)
         lines.push("", ...r.caveats.map((c) => `Note: ${c}`));
     console.log(lines.join("\n"));
@@ -5196,9 +5289,13 @@ Options:
                         the sync matches several kinds, so its next read joins the item
   --notes <text>        what changed in the version skill publish adds
   --note <why>          why: what content create and edit changed, why lessons retire says a lesson is no longer true,
-                        or why tests abandon drops one; for profile upload, what the files are, in the client's words;
+                        why tests abandon drops one, what tests invalidate says went wrong, the note tests note adds, or what the
+                        owner said with tests plan; for profile upload, what the files are, in the client's words;
                         for meta ad promote into a campaign, a few words on the new ad set's audience;
                         for scorecard record, what was checked and what was found; for repairs open and update, a progress line
+  --approved-by <name>  tests plan: who said yes to the test's plan, as the owner gave their name in your session
+  --outcome <o>         tests decide: what the test found, won, lost, inconclusive or invalid; needed with scale, iterate and stop
+  --learning <text>     tests decide: what the test taught, in a sentence, kept on the test
   --about <a>           with lessons, only the lessons with a proof about ads, pages, funnel (steps and tests) or messages
                         (emails, texts and sequences), or cross_channel: proven on two or more of ads, pages and messages
   --dimension <d>       with lessons, only the lessons along that dimension (hook, angle, format, offer, persona, page, funnel_step, follow_up, other); repeat for several
@@ -5436,6 +5533,9 @@ function parseOptions(argv) {
             "merged-at": { type: "string" },
             probes: { type: "string" },
             decision: { type: "string" },
+            outcome: { type: "string" },
+            learning: { type: "string" },
+            "approved-by": { type: "string" },
             harness: { type: "string" },
             platform: { type: "string" },
             library: { type: "string" },
@@ -5664,6 +5764,9 @@ function parseOptions(argv) {
             mergedAt: values["merged-at"],
             probes: values.probes,
             decision: values.decision,
+            outcome: values.outcome,
+            learning: values.learning,
+            approvedBy: values["approved-by"],
             notes: values.notes,
             harness: values.harness,
             platform: values.platform,

package/dist/playbooks.js

@@ -1994,21 +1994,33 @@ ${pagesPlaybook}`;
 export const CRO_SKILL_NAME = `${cli}-cro`;
 /** The test the cro playbook shows, exported so a test checks the server accepts it. */
 export const croTestExample = {
-    hypothesis: "A text 15 minutes before the webinar will get more sign-ups to show up, because people on sales calls say they did not know it was live.",
     funnel_key: "webinar_to_course",
     step_key: "attend",
-    variable: "a reminder text 15 minutes before the start",
-    control: { label: "today's reminders: an email the day before and an hour before" },
-    variants: [{ label: "the same reminders plus a text 15 minutes before" }],
-    metric: "step_conversion",
-    expected_change: "sign-ups who attend from 30% to 35%",
-    min_people_per_arm: 300,
-    split_method: "other",
-    split_note: "The reminder workflow sends the text to every other new sign-up.",
+    change: "a reminder text 15 minutes before the start",
+    because: "Attendance fell from 38% to 30% of sign-ups, and people on sales calls say they did not know the webinar was live.",
+    audience: "everyone who signs up for the webinar",
+    expected_lift: 0.15,
+    prediction_confidence: "medium",
+    disproved_if: "attendance rises less than 5% after 300 sign-ups each side",
     evidence: [
         { kind: "leak", ref: "webinar_to_course.attend", note: "Attendance fell from 38% to 30% of sign-ups, about $2,300 a month." },
         { kind: "customer_words", ref: "sales call 2026-10-02", note: "I didn't know the webinar was live." },
     ],
+    design_type: "link_split",
+    design_note: "The reminder workflow sends the text to every other new sign-up.",
+    metric: "step_conversion",
+    unit: "people",
+    guardrails: ["unsubscribes"],
+    baseline_rate: 0.3,
+    baseline_from: "2026-09-01",
+    baseline_to: "2026-09-30",
+    min_lift: 0.1,
+    people_per_arm: 300,
+    decision_rule: "Keep the text if attendance rises at least 10% with unsubscribes no higher.",
+    elements: ["follow_up"],
+    levers: ["urgency"],
+    control: { label: "today's reminders: an email the day before and an hour before", content: "Email the day before and an hour before; no text." },
+    variants: [{ label: "the same reminders plus a text 15 minutes before", content: "We're live in 15 minutes: {link}" }],
 };
 export const croPlaybook = `# Funnel test playbook
 
@@ -2039,7 +2051,7 @@ Without a shell: MCP \`get_funnel_leaks\`, then MCP \`list_funnel_tests\` with \
 
 In \`leaks.json\`, \`leaks.leaks\` lists every step doing worse than its normal, costliest first. Each has its \`funnel_key\` and \`step_key\`, its \`recent\` and \`baseline\` rates, \`people_lost_vs_baseline\`, \`money_at_stake\` per currency (an estimate; never add currencies together) and, for some steps, \`splits\` by channel, campaign and ad. An empty list means no step is leaking: write no ideas and go to step 5.
 
-\`tests.json\` holds the tests already written, newest first, each with its \`status\`, \`funnel_key\`, \`step_key\` and \`created_at\`. Pick the 1 to 3 costliest leaks you can act on whose step has no \`draft\` or \`running\` test. Count every test created since Monday toward the 3, whatever its status now, abandoned ones included: with 3 already, write no new ideas this week.
+\`tests.json\` holds the tests already written, newest first, each with its \`status\`, \`funnel_key\`, \`step_key\` and \`created_at\`. Pick the 1 to 3 costliest leaks you can act on whose step has no \`idea\`, \`planned\` or \`running\` test. Count every test created since Monday toward the 3, whatever its status now, abandoned ones included: with 3 already, write no new ideas this week.
 
 ## 2. Gather proof for each leak
 
@@ -2066,9 +2078,11 @@ Write each test to its own file with your file tool, such as \`test-1.json\`:
 ${JSON.stringify(croTestExample)}
 \`\`\`
 
-- \`variable\` is the one change. \`control\` is what runs now; \`variants\` is the changed version, each \`{label, page?, url?, item_id?, asset_version?}\`.
-- \`metric\` is the number that should move: \`step_conversion\`, \`sales_per_visitor\`, \`revenue_per_visitor\` or \`cost_per_sale\`. \`expected_change\` says how much, and \`min_people_per_arm\` how many people each side needs before deciding.
-- \`split_method\` is \`adzara_ads\` (two ads, one to each page), \`before_after\`, or \`other\` with a \`split_note\`. Until #2202, an \`adzara_ads\` test is counted only from Adzara's labels, so it can be measured only on ads Adzara made before the switch; for a new test, use \`before_after\`.
+- \`change\` is the one change. \`because\` is what led to it, \`audience\` who sees it, \`expected_lift\` how much it should move (0.15 for 15%) and \`prediction_confidence\` how sure you are; \`disproved_if\` says what result would prove it wrong.
+- \`control\` is what runs now; \`variants\` is the changed version, each \`{label, content, page?, url?, item_id?, asset_version?}\`. \`content\` is the exact words or change each side shows.
+- \`metric\` is the number that should move: \`step_conversion\` (only with a \`step_key\`), \`sales_per_visitor\`, \`revenue_per_visitor\`, \`cost_per_sale\` or \`cost_per_lead\` (spend per sign-up), counted by \`unit\` (people or sessions). \`baseline_rate\` is today's rate over \`baseline_from\` to \`baseline_to\`, \`min_lift\` the smallest lift worth finding, \`people_per_arm\` how many each side needs, \`guardrails\` the numbers that must not get worse, and \`decision_rule\` how you will call it. \`min_days\` and \`max_days\` are 14 and 56 unless set.
+- \`design_type\` is how traffic is split: \`ad_split_randomized\` (Meta's own A/B test), \`ad_split_duplicated\` (two copies of a campaign, one to each page; not a true random split), \`tool_split\` (inside a page builder or webinar tool, named in \`design_note\`), \`link_split\`, \`before_after\` or \`adaptive\`. \`traffic\` says which campaigns feed it and what they optimize for. Until #2202, an ad split test is counted only from Adzara's labels, so it can be measured only on ads Adzara made before the switch; for a new test, use \`before_after\`.
+- \`elements\` and \`levers\` tag what changes and why it should work, from \`${cli} guide\`'s fixed lists.
 - \`evidence\` quotes the proof, each \`{kind, ref, note}\` with kind \`leak\`, \`lesson\`, \`customer_words\`, \`page\`, \`ad\` or \`other\`. Start with the leak itself.
 - Give \`hypothesis_id\` and \`test_id\` only to reuse Adzara's own labels; left out, they are made for you.
 
@@ -2080,13 +2094,21 @@ ${cli} tests draft --file test-1.json --format json > drafted-1.json
 
 Without a shell: MCP \`draft_funnel_test\` with the same JSON.
 
-A test that changes two things is refused: split it into two tests and keep the stronger one.
+It is written down as an \`idea\`. A test that changes two things is refused: split it into two tests and keep the stronger one.
 
 ## 4. Put the ideas to the owner
 
-Approvals happen in your own session with the owner. ${brand.name} has no approval step and records none. For each draft, give the owner the leak and what it costs, the one change, the number that should move, and the proof in a line. The owner says yes or no.
+Approvals happen in your own session with the owner. ${brand.name} shows no approval screen. For each idea, give the owner the leak and what it costs, the one change, the number that should move, and the proof in a line. The owner says yes or no.
+
+When the owner says yes, record who said it. It refuses a plan with a gap and names each missing field; fill them in with \`${cli} tests edit <test_id> --file changes.json\` and try again.
+
+\`\`\`sh
+${cli} tests plan <test_id> --approved-by "<the owner's name>"
+\`\`\`
+
+Without a shell: MCP \`plan_funnel_test\` with \`{"id": "<test_id>", "approved_by": "<the owner's name>"}\`.
 
-When the owner says yes, the change goes live through its own path: a page through its own approval (the pages playbook), ads through ${brand.name}'s Meta commands (an \`adzara_ads\` split cannot be measured on those new ads until #2202). Once it is actually live, and no other test runs on the same step, mark it running. This changes nothing live; it only records the start day.
+Then the change goes live through its own path: a page through its own approval (the pages playbook), ads through ${brand.name}'s Meta commands (an \`adzara_ads\` split cannot be measured on those new ads until #2202). Once it is actually live, and no other test runs on the same step, mark it running. This changes nothing live; it records the start day and freezes the plan.
 
 \`\`\`sh
 ${cli} tests start <test_id>
@@ -2115,15 +2137,15 @@ Without a shell: MCP \`get_funnel_test_results\` with \`{"id": "<test_id>"}\`.
 \`calls\` has one call for each changed version against the control: \`not_enough_yet\` (with the \`people\` each side has and the \`need\`), \`variant_ahead\`, \`control_ahead\` or \`no_real_difference\`, and \`words\` says it plainly. \`caveats\` names what weakens the call.
 
 - **Every call is \`not_enough_yet\`:** leave the test running; that needs no command. Only when something outside the test got in the way (the page broke, a price changed, the ads stopped), suggest \`hold\` to the owner.
-- **A call is ready:** suggest \`scale\` (the new version won), \`stop\` (it lost or made no difference) or \`iterate\` (promising; it drafts a sharper version). \`iterate\` drafts a new test, so suggest it only while the week is under its 3; otherwise suggest \`stop\` and draft the sharper version next week.
+- **A call is ready:** suggest \`scale\` (the new version won), \`stop\` (it lost or made no difference) or \`iterate\` (promising; it writes down a sharper version). \`iterate\` writes a new test, so suggest it only while the week is under its 3; otherwise suggest \`stop\` and draft the sharper version next week.
 
 Put each suggestion to the owner with the ideas from step 4, then record the owner's decision:
 
 \`\`\`sh
-${cli} tests decide <test_id> --decision <scale|iterate|stop|hold> --note "<why, in a sentence>"
+${cli} tests decide <test_id> --decision <scale|iterate|stop|hold> --outcome <won|lost|inconclusive> --note "<why, in a sentence>"
 \`\`\`
 
-Without a shell: MCP \`decide_funnel_test\` with \`{"id": "<test_id>", "decision": "<scale|iterate|stop|hold>", "note": "<why, in a sentence>"}\`.
+Without a shell: MCP \`decide_funnel_test\` with \`{"id": "<test_id>", "decision": "<scale|iterate|stop|hold>", "outcome": "<won|lost|inconclusive>", "note": "<why, in a sentence>"}\`. scale, iterate and stop need the outcome; hold does not.
 
 Deciding changes nothing live. It writes the lesson itself, with the test, its pages and its step as proof, so write no lesson of your own for it.
 
@@ -2140,11 +2162,13 @@ ${cli} lessons [--about pages|funnel] --format json        what earlier tests ta
 ${cli} voice --since <YYYY-MM-DD> --sort useful --json     fresh customer words
 ${cli} pages results --format json                         which landing pages bring real sales
 ${cli} pages brief --step <key> [--funnel <key>] --format json   the step's current page and the ads that send people there
-${cli} tests draft --file <test.json>                      write down a test
-${cli} tests start <test_id>                               record that an approved, live test is running
+${cli} tests draft --file <test.json>                      write down a test idea
+${cli} tests edit <test_id> --file <changes.json>          fill in or change its plan
+${cli} tests plan <test_id> --approved-by "<owner>"        record the owner's yes to the full plan
+${cli} tests start <test_id>                               record that a planned, live test is running
 ${cli} tests abandon <test_id> --note "<why>"              drop a test the owner rejected
 ${cli} tests results <test_id> --format json              a running test's numbers per side and whether it can be called
-${cli} tests decide <test_id> --decision <d> --note "<why>"   record the owner's decision; it writes the lesson
+${cli} tests decide <test_id> --decision <d> --outcome <o> --note "<why>"   record the owner's decision; it writes the lesson
 \`\`\`
 `;
 export const croSkill = `---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.162",
+  "version": "0.3.164",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {