marketing-mindset 1.3.2 → 1.5.0

package/README.md

@@ -59,3 +59,19 @@ The same checklist is a browser tool with a live score:
 <https://axelfreeman.github.io/marketing-mindset/tools/aeo-readiness-checklist.html>.
 If you want the plumbing in that checklist built for you (offer page, query-intent pages, schema,
 `llms.txt`, IndexNow, the tracked event), packages are published at https://axelfreeman.com/marketing-engineer.html.
+
+### Sending ramp: `warmup`
+
+```
+npx -y marketing-mindset@1.4.0 warmup --start 2026-09-21 --target 200 --days 21 --mailboxes 4
+```
+
+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

@@ -167,6 +167,129 @@ function runJd(opts) {
   return 0;
 }
 
+/* warmup — day-by-day sending ramp. Deterministic: same inputs, same schedule. */
+function runWarmup(opts) {
+  const start = opts.start === undefined ? "" : String(opts.start);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(start) || isNaN(Date.parse(start))) {
+    console.error("warmup: --start must be YYYY-MM-DD (got: " + JSON.stringify(start) + ")");
+    return 1;
+  }
+  const target = Number(opts.target === undefined ? 0 : opts.target);
+  if (!isFinite(target) || target <= 0) {
+    console.error("warmup: --target must be a positive number of sends per day (got: " + JSON.stringify(opts.target) + ")");
+    return 1;
+  }
+  const days = Number(opts.days === undefined ? 21 : opts.days);
+  if (!isFinite(days) || days < 1 || days > 180) {
+    console.error("warmup: --days must be between 1 and 180 (got: " + JSON.stringify(opts.days) + ")");
+    return 1;
+  }
+  const mailboxes = Number(opts.mailboxes === undefined ? 1 : opts.mailboxes);
+  if (!isFinite(mailboxes) || mailboxes < 1) {
+    console.error("warmup: --mailboxes must be >= 1");
+    return 1;
+  }
+  const date0 = new Date(start + "T00:00:00Z");
+  const rows = [];
+  let prev = Math.min(20, target);
+  let cumulative = 0;
+  let reached = 0;
+  for (let i = 0; i < days; i++) {
+    const vol = i === 0 ? prev : Math.min(target, Math.max(prev, Math.round(prev * 1.5)));
+    const d = new Date(date0.getTime() + i * 86400000);
+    if (vol >= target && !reached) reached = i + 1;
+    cumulative += vol;
+    rows.push({ day: i + 1, date: d.toISOString().slice(0, 10), sends: vol, cumulative: cumulative });
+    prev = vol;
+  }
+  const perMailbox = Math.round((target / mailboxes) * 10) / 10;
+  if (opts.json) {
+    console.log(JSON.stringify({
+      start: start, target_per_day: target, days: days, mailboxes: mailboxes,
+      first_day: rows[0].sends, full_volume_day: reached || null,
+      total_sends: cumulative, per_mailbox_at_target: perMailbox,
+      schedule: rows,
+      stop_rules: [
+        "hard bounce rate over 2% in a day: stop the day, find the source",
+        "spam complaint over 0.1%: stop the campaign, not the day",
+        "any reply: the sequence stops for that person, replied is the goal",
+        "deliverability dip (opens down by half with sends flat): drop back two ramp days"
+      ]
+    }, null, 2));
+    return 0;
+  }
+  console.log("Warmup plan: start " + start + ", target " + target + " sends/day over " + days + " days"
+    + (mailboxes > 1 ? ", " + mailboxes + " mailboxes (" + perMailbox + "/mailbox/day)" : ""));
+  console.log("day  date        sends  cumulative");
+  rows.forEach(function (r) {
+    console.log(String(r.day).padStart(3) + "  " + r.date + "  " + String(r.sends).padStart(5)
+      + "  " + String(r.cumulative).padStart(10));
+  });
+  console.log("day 1 starts at " + rows[0].sends + "; full volume on day " + (reached || "not reached within --days")
+    + "; " + cumulative + " sends total in the window.");
+  console.log("Stop rules: bounce >2%/day -> stop the day; complaints >0.1% -> stop the campaign;"
+    + " any reply -> that person's sequence ends; opens halving with flat sends -> drop back two ramp days.");
+  console.log("-- Method and packages: https://axelfreeman.com/marketing-engineer.html");
+  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);
 
@@ -201,6 +324,10 @@ 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") {
   process.exit(runJd(flags(rest)));
 } else if (cmd === "sections") {
@@ -225,6 +352,10 @@ 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
       --level senior --mode fulltime --surfaces seo,out,analytics
   npx marketing-mindset aeo             agent-readiness / AEO checklist (23 weighted checks)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-mindset",
-  "version": "1.3.2",
-  "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|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",
@@ -13,7 +13,13 @@
     "llm",
     "prompt",
     "sample-size",
-    "job-description"
+    "job-description",
+    "cold-email",
+    "deliverability",
+    "warmup",
+    "budget",
+    "cac",
+    "unit-economics"
   ],
   "license": "MIT",
   "author": "Axel Freeman",