marketing-mindset 1.4.0 → 1.5.0

package/README.md

@@ -67,3 +67,11 @@ npx -y marketing-mindset@1.4.0 warmup --start 2026-09-21 --target 200 --days 21
 ```
 
 Day-by-day ramp for a new sending domain: starts at 20/day (or the target, if smaller), grows by half a day, never above the target, and prints the four stop rules (bounce >2%/day, complaints >0.1%, any reply ends that sequence, opens halving with flat sends -> drop back two ramp days). `--json` gives the machine-readable schedule. Work with me: https://axelfreeman.com/marketing-engineer.html
+
+### Test budget: `budget`
+
+```
+npx -y marketing-mindset@1.5.0 budget --base 0.03 --lift 0.2 --cpl 4 --daily 500
+```
+
+The money side of the same floor `sample` computes: contacts needed in both arms, cost per arm and cost to read the test at your cost per contact, days to the floor at a given daily volume, and the spend guard (below the floor the difference is noise, not a result). `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html

package/bin/cli.js

@@ -233,6 +233,63 @@ function runWarmup(opts) {
   return 0;
 }
 
+/* budget — the money it takes to read a test, from the same sample-size floor as `sample`. */
+function runBudget(opts) {
+  const base = Number(opts.base === undefined ? 0 : opts.base);
+  const lift = Number(opts.lift === undefined ? 0 : opts.lift);
+  if (!isFinite(base) || base <= 0 || base >= 1) {
+    console.error("budget: --base must be a rate between 0 and 1 (got: " + JSON.stringify(opts.base) + ")");
+    return 1;
+  }
+  if (!isFinite(lift) || lift <= 0) {
+    console.error("budget: --lift must be a positive relative lift, e.g. 0.2 for +20% (got: " + JSON.stringify(opts.lift) + ")");
+    return 1;
+  }
+  const cpl = Number(opts.cpl === undefined ? 0 : opts.cpl);
+  if (!isFinite(cpl) || cpl <= 0) {
+    console.error("budget: --cpl must be a positive cost per contact (got: " + JSON.stringify(opts.cpl) + ")");
+    return 1;
+  }
+  const power = opts.power === undefined ? 0.8 : opts.power;
+  const alpha = opts.alpha === undefined ? 0.05 : opts.alpha;
+  const daily = opts.daily === undefined ? 0 : Number(opts.daily);
+  if (opts.daily !== undefined && (!isFinite(daily) || daily <= 0)) {
+    console.error("budget: --daily must be a positive number of contacts per day");
+    return 1;
+  }
+  const perArm = sampleSize(base, lift, power, alpha);
+  const bothArms = perArm * 2;
+  const perArmCost = Math.round(perArm * cpl * 100) / 100;
+  const totalCost = Math.round(bothArms * cpl * 100) / 100;
+  const days = daily > 0 ? Math.ceil(bothArms / daily) : null;
+  const p2 = base * (1 + lift);
+  const expectedLift = Math.round((p2 - base) * 10000) / 10000;
+  if (opts.json) {
+    console.log(JSON.stringify({
+      base_rate: base, target_rate: Math.round(p2 * 10000) / 10000, relative_lift: lift, power: power, alpha: alpha,
+      per_arm: perArm, contacts_needed: bothArms, cost_per_contact: cpl,
+      cost_per_arm: perArmCost, cost_to_read_the_test: totalCost,
+      daily_contacts: daily > 0 ? daily : null, days_to_read: days,
+      spend_guard: [
+        "below the per-arm floor the difference is noise, not a result - that spend is a donation",
+        "decide the kill rule before the first send: what result ends the test and what result doubles it",
+        "if cost_to_read_the_test is more than the deal is worth, change the base rate or the channel, not the sample"
+      ],
+      method: "two-proportion sample size; same formula as `marketing-mindset sample`"
+    }, null, 2));
+    return 0;
+  }
+  console.log("Honest test budget: base " + (base * 100).toFixed(2) + "% -> target " + (p2 * 100).toFixed(2)
+    + "% (relative lift " + lift + "), power " + power + ", alpha " + alpha);
+  console.log("Per arm: " + perArm + " contacts  |  both arms: " + bothArms + " contacts");
+  console.log("At $" + cpl + " per contact: $" + perArmCost + " per arm, $" + totalCost + " to read the test");
+  if (days) console.log("At " + daily + " contacts/day: " + days + " days to reach the floor");
+  console.log("Spend guard: under the floor the difference is noise, not a result - that spend is a donation.");
+  console.log("Kill rule first: what result ends the test, what result doubles it.");
+  console.log("Method and packages: https://axelfreeman.com/marketing-engineer.html");
+  return 0;
+}
+
 const cmd = (process.argv[2] || "").toLowerCase();
 const rest = process.argv.slice(3);
 
@@ -267,6 +324,8 @@ if (cmd === "sample") {
   }, null, 2));
 } else if (cmd === "aeo") {
   process.exit(runAeo(flags(rest)));
+} else if (cmd === "budget") {
+  process.exit(runBudget(flags(rest)));
 } else if (cmd === "warmup") {
   process.exit(runWarmup(flags(rest)));
 } else if (cmd === "jd") {
@@ -293,6 +352,8 @@ Usage:
       --base 0.03 --lift 0.2 --power 0.8 --alpha 0.05
   npx marketing-mindset kill            kill rule for a running test
       --base 0.03 --n 1500 --lift 0.2
+  npx marketing-mindset budget          what an honest test costs before you can read it
+      --base 0.03 --lift 0.2 --cpl 4 [--daily 500]
   npx marketing-mindset warmup          day-by-day sending ramp with stop rules
       --start 2026-09-21 --target 200 --days 21 --mailboxes 4
   npx marketing-mindset jd              marketing engineer job description

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-mindset",
-  "version": "1.4.0",
-  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|warmup|aeo|jd|sections|read|install.",
+  "version": "1.5.0",
+  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|budget|warmup|aeo|jd|sections|read|install.",
   "keywords": [
     "agent-skill",
     "skill",
@@ -16,7 +16,10 @@
     "job-description",
     "cold-email",
     "deliverability",
-    "warmup"
+    "warmup",
+    "budget",
+    "cac",
+    "unit-economics"
   ],
   "license": "MIT",
   "author": "Axel Freeman",