marketing-mindset 1.13.0 → 1.14.1

package/README.md

@@ -17,7 +17,7 @@ npx marketing-mindset install              # copy the skill into your agent's sk
 
 `npx marketing-mindset jd --level senior` prints the JD with the artifacts due by day 90,
 the sample-size floors, the kill rule and the screening questions. Web version:
-https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html
+https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 ## Floors that do not move
 
@@ -30,11 +30,11 @@ https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-gene
 
 ## Links
 
-- Skill page: https://axelfreeman.github.io/marketing-mindset/
+- Skill page: https://axelfreeman.github.io/marketing-mindset/?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 - Source: https://github.com/axelfreeman/marketing-mindset
-- Free test-size calculator (browser, no signup): https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html
+- Free test-size calculator (browser, no signup): https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 - MCP server, same method over stdio: https://www.npmjs.com/package/marketing-mindset-mcp
-- `llms.txt` for agents: https://axelfreeman.com/llms.txt
+- `llms.txt` for agents: https://axelfreeman.com/llms.txt?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 ## Need this done for you?
 
@@ -43,8 +43,8 @@ sending setup that passes a deliverability checklist, tests with a written kill
 measurement inside your own analytics property — is sold as fixed-scope packages, with the
 scope and the prices published before you get on a call:
 
-**https://axelfreeman.com/marketing-engineer.html** — Sprint $900 · Engine $1,900/month · Full build $2,900.
-Scope: https://axelfreeman.com/scope.html · Pricing: https://axelfreeman.com/pricing.html
+**https://axelfreeman.com/marketing-engineer.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset** — Sprint $900 · Engine $1,900/month · Full build $2,900.
+Scope: https://axelfreeman.com/scope.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset · Pricing: https://axelfreeman.com/pricing.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 MIT © Axel Freeman
 
@@ -55,10 +55,30 @@ npx marketing-mindset aeo          # 23 weighted checks, grouped, with the max s
 npx marketing-mindset aeo --json   # same data for a script or an agent
 ```
 
+### Tag every outbound link before it ships
+
+A channel you cannot attribute is a channel you cannot kill, so the rule is mechanical:
+links that leave for your own property carry UTM, internal links never do.
+
+```
+npx marketing-mindset utm https://axelfreeman.com/offer.html --source devto --medium article --campaign mindset
+npx marketing-mindset utm --file article.md --source devto --medium article --campaign mindset
+```
+
+`--file` rewrites the file in place and reports how many links it tagged; a second run tags nothing
+(idempotent). Third-party links are left alone, existing query params are kept, and sentence
+punctuation after a URL stays where it belongs. The convention it writes:
+
+| parameter | what it holds | examples |
+|---|---|---|
+| `utm_source` | the channel that sent the click | `devto`, `github`, `npm`, `telegram`, `habr`, `reddit` |
+| `utm_medium` | the placement | `article`, `readme`, `package`, `post`, `profile` |
+| `utm_campaign` | the product or the cluster | `mindset`, `tapac`, `hire`, `lyzhi`, `engine` |
+
 The same checklist is a browser tool with a live score:
-<https://axelfreeman.github.io/marketing-mindset/tools/aeo-readiness-checklist.html>.
+<https://axelfreeman.github.io/marketing-mindset/tools/aeo-readiness-checklist.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset>.
 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.
+`llms.txt`, IndexNow, the tracked event), packages are published at https://axelfreeman.com/marketing-engineer.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset.
 
 ### Sending ramp: `warmup`
 
@@ -66,7 +86,7 @@ If you want the plumbing in that checklist built for you (offer page, query-inte
 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
+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?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 ### Test budget: `budget`
 
@@ -74,14 +94,14 @@ Day-by-day ramp for a new sending domain: starts at 20/day (or the target, if sm
 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
+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?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 ### Dated plan: `plan`
 
 ```
 npx -y marketing-mindset plan --base 0.03 --lift 0.2 --daily 500 --weeks 4
 ```
 
-The floor from `sample`/`budget` laid out on a calendar: contacts per week, cumulative volume against the floor, the first date the test can honestly be read, the mechanics-only first week, and an honest verdict when the volume cannot reach the floor inside the plan. `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html
+The floor from `sample`/`budget` laid out on a calendar: contacts per week, cumulative volume against the floor, the first date the test can honestly be read, the mechanics-only first week, and an honest verdict when the volume cannot reach the floor inside the plan. `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 ## `brief` — the plan as markdown you can send
 
@@ -93,7 +113,7 @@ One page: the floor in contacts per arm and in total, what reaching it costs at
 the dated read, a week-by-week table with the percentage of the floor covered, the three gates, and the
 kill rule. `--json` returns the same object for an agent or a script.
 
-Method, packages and the paid version of this work: https://axelfreeman.com/marketing-engineer.html
+Method, packages and the paid version of this work: https://axelfreeman.com/marketing-engineer.html?utm_source=npm&utm_medium=readme&utm_campaign=mindset
 
 ## `mde` — what a volume you can afford can actually read
 

package/bin/cli.js

@@ -66,6 +66,107 @@ function readSkill() {
   return fs.readFileSync(SKILL, "utf8");
 }
 
+/* --- UTM tagging: every OUTBOUND link carries source, medium, campaign -------------------
+ * Rule: tag links that leave for our own domains; never touch internal site links,
+ * never tag a link twice, never drop existing query params.
+ */
+const OUR_HOSTS = [
+  "axelfreeman.com", "axelfreeman.ru", "axelfreeman.github.io", "tapacapi.com", "tapac.ai",
+  "gymcamanalytics.com", "releazer.online", "dublicator.online", "spbilo.ru", "avtootkliki.ru",
+];
+
+function utmTag(url, source, medium, campaign, content) {
+  if (!/^https?:\/\//i.test(url)) return url;
+  let host;
+  try {
+    host = new URL(url).hostname.replace(/^www\./, "");
+  } catch (e) {
+    return url;
+  }
+  if (OUR_HOSTS.indexOf(host) === -1) return url; // only our own destinations
+  if (/[?&]utm_source=/i.test(url)) return url; // idempotent
+  const parts = [];
+  if (source) parts.push("utm_source=" + encodeURIComponent(source));
+  if (medium) parts.push("utm_medium=" + encodeURIComponent(medium));
+  if (campaign) parts.push("utm_campaign=" + encodeURIComponent(campaign));
+  if (content) parts.push("utm_content=" + encodeURIComponent(content));
+  if (!parts.length) return url;
+  return url + (url.indexOf("?") === -1 ? "?" : "&") + parts.join("&");
+}
+
+function runUtm(opts) {
+  const source = opts.source ? String(opts.source) : null;
+  const medium = opts.medium ? String(opts.medium) : "referral";
+  const campaign = opts.campaign ? String(opts.campaign) : null;
+  const content = opts.content ? String(opts.content) : null;
+
+  // Tag links in prose, but never inside fenced blocks or `inline code` — those are examples.
+  function tagText(text) {
+    let n = 0;
+    let inFence = false;
+    const lines = text.split("\n").map((line) => {
+      if (/^\s*(```|~~~)/.test(line)) {
+        inFence = !inFence;
+        return line;
+      }
+      if (inFence) return line;
+      const parts = line.split("`");
+      return parts
+        .map((seg, i) => {
+          if (i % 2 === 1) return seg; // inline code — leave as is
+          return seg.replace(/https?:\/\/[^\s)>"'*`]+/g, (u) => {
+            const tailMatch = /[.,;:!?]+$/.exec(u); // sentence punctuation is not part of the url
+            const tail = tailMatch ? tailMatch[0] : "";
+            const core = tail ? u.slice(0, -tail.length) : u;
+            const t = utmTag(core, source, medium, campaign, content);
+            if (t !== core) n++;
+            return t + tail;
+          });
+        })
+        .join("`");
+    });
+    return { text: lines.join("\n"), count: n };
+  }
+
+  if (opts.file) {
+    const p = String(opts.file);
+    const src = fs.readFileSync(p, "utf8");
+    const res = tagText(src);
+    if (res.count) fs.writeFileSync(p, res.text);
+    console.log("tagged links: " + res.count + (res.count ? " in " + p : " (nothing to tag)"));
+    console.log("utm_source=" + (source || "-") + " utm_medium=" + medium + " utm_campaign=" + (campaign || "-"));
+    return 0;
+  }
+
+  const url = opts.url ? String(opts.url) : (opts._ ? String(opts._) : null);
+  if (!url) {
+    console.log(`utm — tag every outbound link, once, before it ships
+
+  Usage:
+    npx marketing-mindset utm <url> --source devto --medium article --campaign mindset
+    npx marketing-mindset utm --file article.md --source devto --medium article --campaign mindset
+
+  Convention:
+    utm_source    the channel that sent the click   devto | github | npm | telegram | habr | reddit | colony
+    utm_medium    the placement                      article | readme | package | post | comment | profile | bio
+    utm_campaign  the product or cluster             mindset | tapac | hire | lyzhi | engine
+
+  Rules:
+    - internal links of your own site carry NO utm — they would restart the session
+    - tag only links that leave for our own domains; a third-party link stays clean
+    - never tag twice: a url that already has utm_source is returned untouched
+    - existing query params are kept`);
+    return 1;
+  }
+  const tagged = utmTag(url, source, medium, campaign, content);
+  console.log(tagged);
+  if (tagged === url) {
+    console.error("(not tagged: internal/no-own-domain/already tagged — see rules)");
+    return 1;
+  }
+  return 0;
+}
+
 
 /* --- agent-readiness / AEO checklist (23 weighted checks) -------------------------------
  * The same checklist that runs in the browser tool, as data: agents can read it and score
@@ -1015,6 +1116,8 @@ if (cmd === "sample") {
     process.exit(1);
   }
   console.log("## " + hit.title + "\n" + hit.body.join("\n").trim());
+} else if (cmd === "utm") {
+  process.exit(runUtm(flags(rest)));
 } else if (cmd === "install") {
   require(path.join(__dirname, "install.js"));
 } else {
@@ -1050,6 +1153,8 @@ Usage:
       --level senior --mode fulltime --surfaces seo,out,analytics
   npx marketing-mindset aeo             agent-readiness / AEO checklist (23 weighted checks)
       --json                            machine-readable
+  npx marketing-mindset utm             tag every outbound link, once, before it ships
+      --source devto --medium article --campaign mindset [--url <url> | --file article.md]
   npx marketing-mindset sections        every section of the skill
   npx marketing-mindset read numbers    print one section
   npx marketing-mindset install         copy the skill into your agent's skills dir

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "marketing-mindset",
-  "version": "1.13.0",
-  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, honest verdicts on finished tests, which funnel step can fund a verdict, which channel can actually fund a verdict, the lift a volume can read, a queue of readable tests with read-out dates, the cost of one readable verdict. npx marketing-mindset sample|kill|verdict|unit|fit|queue|cost|mde|budget|brief|plan|warmup|aeo|jd|sections|read|install.",
+  "version": "1.14.1",
+  "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, honest verdicts on finished tests, which funnel step can fund a verdict, which channel can actually fund a verdict, the lift a volume can read, a queue of readable tests with read-out dates, the cost of one readable verdict, and UTM tagging on every outbound link. npx marketing-mindset sample|kill|verdict|unit|fit|queue|cost|mde|budget|brief|plan|warmup|aeo|utm|jd|sections|read|install.",
   "keywords": [
     "agent-skill",
     "skill",
     "marketing",
     "growth",
     "aeo",
+    "utm",
+    "attribution",
+    "link-tagging",
     "claude-code",
     "codex",
     "llm",

package/skill/SKILL.md

@@ -236,6 +236,25 @@ Sharp, honest, zero fluff. No corporate-speak, no generic templates, no hedging.
 - Using paid data sources when free ones exist
 - Working for free — zero-exchange tasks, "for the portfolio", or treating training time as free
 
+## Tagging: Every Outbound Link Carries UTM
+
+A campaign you cannot attribute is a campaign you cannot kill. The rule is mechanical:
+**every link that leaves for your own property carries UTM; internal links never do.**
+
+- `utm_source` — the channel that sent the click: `devto`, `github`, `npm`, `telegram`, `habr`, `reddit`, `colony`.
+- `utm_medium` — the placement: `article`, `readme`, `package`, `post`, `comment`, `profile`, `bio`.
+- `utm_campaign` — the product or cluster: `mindset`, `tapac`, `hire`, `lyzhi`, `engine`.
+
+Rules that keep the data clean:
+
+- Tag only destinations you own. A third-party link stays clean.
+- **Never tag internal site links.** An internal link with UTM restarts the session, so one visit looks like two and the page's own report becomes wrong.
+- Never tag twice: a URL that already has `utm_source` is done. Tagging happens before the text ships, not after.
+- Keep existing query params — append, never rebuild the URL.
+- Run it: `npx marketing-mindset utm --file article.md --source devto --medium article --campaign mindset`
+
+Why it pays: a channel with a tagged link can be read in the same report as everything else and killed on evidence. An untagged one only feels like it is working.
+
 ## Pitfalls
 
 - The temptation to answer from general marketing knowledge is strong — resist it; check fresh, recent context first.