@flowapt/flowiq-cli 0.6.6 → 0.6.8

package/README.md

@@ -555,6 +555,28 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
   matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
+### Publishing (maintainers) — publish from a CLEAN checkout
+
+`npm publish` packs the **working tree**, not your branch. This repo's local
+tree is routinely dozens of commits behind `origin/main` with other sessions'
+work in it, so `cd cli && npm publish` from it ships a stale CLI under a version
+number you can never reuse. That has happened twice — **0.6.5** (8 Sep 2026) and
+**0.6.7** (9 Sep 2026) both shipped a local tree while the real work sat on
+`origin/main`.
+
+A `prepublishOnly` hook now refuses when `cli/` differs from `origin/main`:
+
+```bash
+# the safe recipe
+git clone https://github.com/MattFlowapt/flow-v1.git /tmp/pub
+cd /tmp/pub/cli && npm publish
+
+# or bring the local tree level first
+git checkout origin/main -- cli/ && cd cli && npm publish
+```
+
+`FLOWIQ_ALLOW_DIRTY_PUBLISH=1` overrides it, for a genuine emergency only.
+
 ### Links — `flowiq links shorten|list` (v0.4.8)
 
 Short links with campaign UTM tags — the terminal half of the in-app **URL
@@ -564,16 +586,53 @@ minted here is identical to one minted in the dialog.
 ```bash
 # Dry run FIRST — shows the exact destination each short link will carry
 flowiq links shorten <org> --url "https://shop.co.za/product/x" \
-  --campaign 13Aug_Seeds --content 13Aug_Seeds
+  --campaign "Spring Promotion"          # → utm_campaign=9Sep_SpringPromotion
 
 flowiq links shorten <org> --url "https://shop.co.za/product/x" \
   --url "https://shop.co.za/product/y" \
-  --campaign 13Aug_Seeds --content 13Aug_Seeds --domain linklnk.io --commit
+  --campaign "Spring Promotion" --content ViewMore --domain linklnk.io --commit
+
+# a send going out later — give the send date, not today's
+flowiq links shorten <org> --file ./slide2.txt \
+  --campaign "Heritage Day" --date 2026-09-24 --commit
 
-flowiq links shorten <org> --file ./slide2.txt --campaign 13Aug_Seeds_VM --content 13Aug_Seeds_VM --commit
-flowiq links list <org> --campaign 13Aug_Seeds
+flowiq links list <org> --campaign 9Sep_SpringPromotion
 ```
 
+#### Campaign naming — `Date_Campaign` (you do not have to type it) (v0.6.7)
+
+The house convention is **`Date_Campaign`**: the date the broadcast **goes out**
+(`9Sep` — no leading zero, three letters, `Sep` never `Sept`), an underscore,
+then the campaign title in PascalCase. A broadcast going out today for the
+Spring Promotion is **`9Sep_SpringPromotion`**.
+
+`--campaign` is normalised to it, so pass the campaign in plain words:
+
+| you type | you get |
+|---|---|
+| `--campaign "Spring Promotion"` | `9Sep_SpringPromotion` (today's date prefixed) |
+| `--campaign spring-promotion` | `9Sep_SpringPromotion` |
+| `--campaign 10JunFathersDay` | `10Jun_FathersDay` (underscore inserted) |
+| `--campaign 5Sept_BraaiDayOffer` | `5Sep_BraaiDayOffer` (`Sept` → `Sep`) |
+| `--campaign "Heritage Day" --date 24/9/2026` | `24Sep_HeritageDay` |
+
+- The resolved tag is **printed before anything is minted**, and `shorten` is
+  dry-run by default, so you always see it first.
+- `--date` takes `9Sep`, `2026-09-24` or `24/9/2026` — use it whenever the send
+  is not today.
+- `--content` is the **per-link** tag (which button, which product), so it gets
+  no date: `--content ViewMore`. Omit it and it defaults to the campaign.
+- `--raw-campaign` uses your string exactly as typed, for the rare tag that is
+  deliberately outside the convention.
+- **Not applied** to the agent's own auto-shortened links (minted server-side as
+  `ai_<org>` — a different namespace) or to `flowiq bc --campaign`, which names
+  the local `.flowiq/campaigns/<x>.json` file and the `bc-<x>` contact tag
+  rather than a UTM.
+
+Why it exists: of 1,042 distinct date-prefixed campaign tags minted in the 12
+months to 9 Sep 2026, only **27 (2.6%)** matched the convention — 924 fused the
+date onto the title (`10JunFathersDay`) and 5 wrote `Sept`.
+
 - **`utm_source=whatsapp` and `utm_medium=whatsapp_paid` are FIXED** (the dialog
   sets them too) — a link built any other way stops matching the attribution
   queries. You supply `--campaign` and `--content`, and they must be **supplied
@@ -982,17 +1041,44 @@ flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/repor
 - `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
 - Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
 
-### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
+### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
 
-Read an org's live templates straight from Meta (read-only), and submit new
-ones through the `create-meta-template` edge function.
+Read an org's live templates straight from Meta (read-only), render any single
+row **including an unsubmitted DRAFT**, and submit new ones through the
+`create-meta-template` edge function.
 
 ```bash
 flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
-flowiq templates create <organization_id> --request-file req.json
 flowiq templates status <organization_id> --name booking   # poll approval
+flowiq templates show <organization_id> heritage_day_v2    # render ONE row, drafts included
+flowiq templates create <organization_id> --request-file req.json
 ```
 
+**`show` is the only way to read a DRAFT from the terminal (v0.6.7).** A draft
+never reaches Meta, so `templates pull` cannot see it and neither can the
+broadcast introspector — before this, reviewing one meant opening the dialog.
+`show` prints the body with its examples substituted (as the customer will read
+it), then every carousel card: media URL, source filename, whether the Meta
+asset handle is present, card body, and each button's resolved URL. `--raw`
+also prints the escaped body so invisible whitespace is visible; `--json` gives
+the row.
+
+It closes with **Checks** — cheap structural rules that Meta would otherwise
+catch only at review, or not at all until send:
+
+- body variables not sequential from `{{1}}`, or missing an example
+- a card URL button using anything but `{{1}}` (Meta numbers each card's
+  parameters per card, so `{{2}}` on a card breaks that card's link at send)
+- more than one variable in a card URL (Meta supports exactly one)
+- a bold/italic/strikethrough marker sitting against a space, which WhatsApp
+  does not render — the customer sees the literal `_` or `*`
+- carousel outside 2–10 cards, cards that do not share one shape, missing media,
+  body/card text over Meta's 1024 / 160 limits
+
+Checks are structural only. They cannot tell you a card names a product your
+store does not sell — `show` renders the text so you can read it against the
+shop.
+
 `req.json` holds `{ template_request, template_data?, media_header?, cards_media? }`.
 Media headers: pass `media_header.file_url` (a public URL) — the edge function
 uploads it to Meta server-side. Approval is async; re-`pull` for the
@@ -1237,7 +1323,7 @@ pairs with reasoning models like `gpt-5.6-luna`), agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
 `shopify_products_web_chat`, `ticket_tool_status`, `product_lookup`,
-`collapse_product_variants`),
+`collapse_product_variants`, `email_request_tool`),
 `discount.enabled`, and the `flowiq test` contact
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
@@ -1258,6 +1344,15 @@ agent answers product questions with "I can't pull the live menu". Found on Ouma
 Bets Gebak (11 Aug 2026): 25 product rows, 0 embeddings, and an unfunded OpenAI
 account — enabling this flag restored product answers immediately.
 
+**`--tool email_request_tool=true` (added 9 Sep 2026).** Turns on the `email_request_to_team`
+tool: once the agent has a customer's name, email and/or phone, preferred contact
+method and what they need, it emails that (plus the last few messages) to the
+addresses in `agents.settings.email_request.to`, from flowiq@flowapt.com with Reply-To
+set to the customer, and leaves an internal note on the thread. No ticket, no bot-off,
+no staff WhatsApp — built for businesses that want requests in an inbox rather than a
+human escalation (GIB Financial Services). The recipient list is set in the Tool
+Library (Agents → Tool Library → Email Request to Team); the CLI cannot set it yet.
+
 **`--tool collapse_product_variants=true` (added 4 Aug 2026).** Not a tool toggle —
 it changes what `get_product_info` RETURNS. OFF (the default) the result cap counts
 **variant rows**, so on a catalogue with several packaging/size variants per product

package/TEAM-GUIDE.md

@@ -101,10 +101,31 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Remove a conflicting built-in tool from one agent | `flowiq agent config <org_id> --disable-base-tool get_product_info` (repeatable; safety/delivery tools cannot be disabled) |
 | Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
 | Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
+| Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true`, then set the recipient list in Agents → Tool Library → Email Request to Team (no CLI path for the addresses yet) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
-| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign 13Aug_Seeds --content 13Aug_Seeds` (dry run) → `… --commit`. `utm_source`/`utm_medium` are set for you; campaign + content must be given together |
-| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
+> **Publishing the CLI (maintainers only):** publish from a clean clone, never
+> from your working tree — `npm publish` packs whatever is on disk. A
+> `prepublishOnly` check now stops you if `cli/` differs from `origin/main`.
+
+### Campaign naming — `Date_Campaign`
+
+Every campaign tag is **the date the broadcast goes out, then the campaign
+title**: a Spring Promotion going out on 9 September is `9Sep_SpringPromotion`.
+
+**You do not have to type it that way.** Pass `--campaign "Spring Promotion"`
+and the CLI builds the tag, prints it, and only mints once you add `--commit`.
+Use `--date` when the send is not today (`--date 24/9/2026`), and `--content`
+for a second link in the same send (`--content ViewMore`).
+
+Getting this right is what makes a campaign's clicks and revenue group together
+in reporting — a tag typed a different way each time splits one campaign into
+several.
+
+| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign "Spring Promotion"` (dry run) → `… --commit`. **Just type the campaign in plain words** — the CLI names it for you as `9Sep_SpringPromotion` and prints it before minting. `utm_source`/`utm_medium` are set for you |
+| A campaign going out on a later date | Add `--date`: `--campaign "Heritage Day" --date 24/9/2026` → `24Sep_HeritageDay`. Without it you get today's date |
+| A second link in the same send (e.g. a VIEW MORE button) | Same `--campaign`, different `--content`: `--content ViewMore`. Content is the per-link tag and gets no date |
+| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign "Spring Promotion" --commit` |
 | Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
 | A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit`. **v0.6.0: the commit imports every row as a contact (tag `bc-<campaign>` + the row's values as attributes) and fires ONE python broadcast** — it returns in seconds with a `broadcastId`; python sends in the background. Check delivery with `bc status`, re-fire failures with `bc retry`. A campaign that already fired refuses a re-run (`--resend` deliberately resends to everyone tagged). |
@@ -134,6 +155,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON. Ask for more than exists (`--count 100`) and you get the entire history — it says "that is ALL of them" when there is nothing older |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
+| **Read a template you have not submitted yet (a DRAFT)** | `flowiq tpl show <org_id> <template_name>` — the ONLY way to see a draft from the terminal (`pull` reads Meta, and a draft never gets there). Renders the message as the customer will read it, every carousel card, and a **Checks** list of the things Meta would bounce it for |
+| Check a carousel before submitting it | `flowiq tpl show <org_id> <name>` and read **Checks**. It catches a card link using the wrong `{{n}}`, a missing greeting example, a bold/italic marker against a space (WhatsApp shows the literal `_`), wrong card counts and over-length text. It cannot know a card names a product you do not stock — read the card text against the shop yourself |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
 | Manage outbound messaging webhooks (incl. their auth) | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
 | Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {
@@ -16,7 +16,9 @@
     "node": ">=18"
   },
   "scripts": {
-    "start": "node bin/flowiq.js"
+    "start": "node bin/flowiq.js",
+    "prepublishOnly": "node scripts/prepublish-check.mjs",
+    "test": "node --test src/*.test.mjs"
   },
   "dependencies": {
     "commander": "^12.1.0",

package/src/campaign-naming.js

@@ -0,0 +1,164 @@
+// Campaign / UTM naming convention — Date_Campaign  (Matt, 9 Sep 2026).
+// ====================================================================
+//   Date     = the physical date the broadcast GOES OUT, as `9Sep` (no
+//              leading zero, three-letter month, "Sep" never "Sept").
+//   Campaign = the broadcast title / campaign, PascalCase, no spaces.
+//   → `9Sep_SpringPromotion`
+//
+// Staff should not have to remember this, so the CLI resolves it for them:
+// `--campaign "Spring Promotion"` on a send going out today becomes
+// `9Sep_SpringPromotion`, and the resolved value is always PRINTED before a
+// --commit so it can be seen and overridden.
+//
+// Measured 9 Sep 2026, why this exists: of 1,042 distinct date-prefixed
+// campaign tags minted in 12 months, only 27 (2.6%) matched the convention —
+// 924 fused the date to the title (`10JunFathersDay`) and 5 wrote `Sept`.
+//
+// SCOPE: this is the UTM campaign tag on a STAFF-minted short link
+// (`flowiq links shorten`). It is deliberately NOT applied to:
+//   • agent auto-shortened links, tagged `ai_<org>` by api/_url-shorten-engine.js
+//     (5,337 `ai_flw`, 3,649 `ai_gf`, … — a different namespace, not a campaign)
+//   • `flowiq bc --campaign`, which names the LOCAL .flowiq/campaigns/<x>.json
+//     file and the `bc-<x>` contact tag, not a UTM.
+// `--raw-campaign` bypasses normalisation entirely when you genuinely need it.
+
+export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+const MONTH_ALIASES = new Map([
+  ["sept", "Sep"], ["january", "Jan"], ["february", "Feb"], ["march", "Mar"],
+  ["april", "Apr"], ["june", "Jun"], ["july", "Jul"], ["august", "Aug"],
+  ["september", "Sep"], ["october", "Oct"], ["november", "Nov"], ["december", "Dec"],
+]);
+
+/** `9Sep` for the given Date (default: today, local time). */
+export function dateToken(d = new Date()) {
+  return `${d.getDate()}${MONTHS[d.getMonth()]}`;
+}
+
+/**
+ * Accepts `9Sep`, `09Sep`, `9Sept`, `9 September`, `2026-09-09`, `09/09/2026`.
+ * Returns a canonical `9Sep`, or null if it is not a date at all.
+ */
+export function parseDateToken(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) return null;
+  const iso = raw.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (iso) {
+    const m = Number(iso[2]);
+    if (m < 1 || m > 12) return null;
+    return `${Number(iso[3])}${MONTHS[m - 1]}`;
+  }
+  const slash = raw.match(/^(\d{1,2})[/](\d{1,2})[/](\d{2,4})$/); // D/M/YYYY (SA order)
+  if (slash) {
+    const m = Number(slash[2]);
+    if (m < 1 || m > 12) return null;
+    return `${Number(slash[1])}${MONTHS[m - 1]}`;
+  }
+  const dm = raw.match(/^(\d{1,2})\s*([A-Za-z]+)$/);
+  if (dm) {
+    const day = Number(dm[1]);
+    if (day < 1 || day > 31) return null;
+    const mon = canonicalMonth(dm[2]);
+    return mon ? `${day}${mon}` : null;
+  }
+  return null;
+}
+
+// Longest-first alternation, so `10JunFathersDay` splits as Jun|FathersDay and
+// not as the 9-letter non-month "JunFathers" (which a greedy [A-Za-z]{3,9} does,
+// silently leaving the whole tag title-side and prefixing TODAY's date on top).
+const MONTH_ALT = [...MONTH_ALIASES.keys(), ...MONTHS.map((m) => m.toLowerCase())]
+  .sort((a, b) => b.length - a.length)
+  .join("|");
+const LEAD_RE = new RegExp(`^(\\d{1,2})\\s*(${MONTH_ALT})([_\\-\\s]*)(.*)$`, "i");
+
+function canonicalMonth(word) {
+  const w = String(word || "").toLowerCase();
+  if (MONTH_ALIASES.has(w)) return MONTH_ALIASES.get(w);
+  const hit = MONTHS.find((m) => m.toLowerCase() === w);
+  return hit || null;
+}
+
+/** "Spring Promotion" / "spring-promotion" / "spring_promotion" → "SpringPromotion". */
+export function pascal(input) {
+  return String(input ?? "")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => (/^[A-Z0-9]+$/.test(w) ? w : w[0].toUpperCase() + w.slice(1)))
+    .join("");
+}
+
+export const CAMPAIGN_RE = /^\d{1,2}(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)_[A-Za-z0-9]+$/;
+
+export function isConforming(value) {
+  return CAMPAIGN_RE.test(String(value ?? ""));
+}
+
+/**
+ * Resolve whatever the operator typed into `Date_Campaign`.
+ *
+ * @param {string} input        what they passed to --campaign
+ * @param {object} [opts]
+ * @param {string} [opts.date]  --date override (any parseDateToken form)
+ * @param {Date}   [opts.now]   injectable clock (tests)
+ * @returns {{value:string, changed:boolean, notes:string[], error?:string}}
+ */
+export function resolveCampaign(input, opts = {}) {
+  const notes = [];
+  const original = String(input ?? "").trim();
+  if (!original) return { value: "", changed: false, notes, error: "campaign is empty" };
+
+  let overrideDate = null;
+  if (opts.date) {
+    overrideDate = parseDateToken(opts.date);
+    if (!overrideDate) {
+      return { value: original, changed: false, notes, error: `--date "${opts.date}" is not a date I understand (try 9Sep, 2026-09-09 or 9/9/2026)` };
+    }
+  }
+
+  // Split a leading date off the front, however it was written / fused.
+  let datePart = null;
+  let rest = original;
+  const lead = original.match(LEAD_RE);
+  if (lead) {
+    const mon = canonicalMonth(lead[2]);
+    if (mon) {
+      datePart = `${Number(lead[1])}${mon}`;
+      rest = lead[4];
+      if (lead[2] !== mon) notes.push(`month "${lead[2]}" → "${mon}"`);
+      if (!lead[3].includes("_")) notes.push("inserted the missing underscore after the date");
+    }
+  }
+
+  if (overrideDate) {
+    if (datePart && datePart !== overrideDate) notes.push(`date ${datePart} → ${overrideDate} (--date)`);
+    datePart = overrideDate;
+  }
+  if (!datePart) {
+    datePart = dateToken(opts.now || new Date());
+    notes.push(`prefixed today's send date "${datePart}"`);
+  }
+
+  const titlePart = pascal(rest);
+  if (!titlePart) {
+    return { value: original, changed: false, notes, error: `no campaign title found in "${original}" — expected something like "Spring Promotion"` };
+  }
+  if (titlePart !== rest) notes.push(`title "${rest}" → "${titlePart}"`);
+
+  const value = `${datePart}_${titlePart}`;
+  return { value, changed: value !== original, notes };
+}
+
+/** utm_content is per-LINK (which button / which product), so no date is imposed. */
+export function resolveContent(input) {
+  const original = String(input ?? "").trim();
+  if (!original) return { value: "", changed: false, notes: [] };
+  const value = pascal(original);
+  return {
+    value: value || original,
+    changed: !!value && value !== original,
+    notes: value && value !== original ? [`content "${original}" → "${value}"`] : [],
+  };
+}

package/src/campaign-naming.test.mjs

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveCampaign, resolveContent, dateToken, parseDateToken, isConforming, pascal } from "./campaign-naming.js";
+
+const NOW = new Date(2026, 8, 9); // 9 Sep 2026, local
+
+test("Matt's worked example", () => {
+  const r = resolveCampaign("Spring Promotion", { now: NOW });
+  assert.equal(r.value, "9Sep_SpringPromotion");
+  assert.ok(r.changed);
+});
+
+test("already correct is left alone and reports no change", () => {
+  const r = resolveCampaign("9Sep_SpringPromotion", { now: NOW });
+  assert.equal(r.value, "9Sep_SpringPromotion");
+  assert.equal(r.changed, false);
+  assert.deepEqual(r.notes, []);
+});
+
+test("the house habit: fused date, no underscore (924 tags in 12 months)", () => {
+  assert.equal(resolveCampaign("10JunFathersDay", { now: NOW }).value, "10Jun_FathersDay");
+});
+
+test("Sept is corrected to Sep, and the date is kept", () => {
+  const r = resolveCampaign("5Sept_BraaiDayOffer", { now: NOW });
+  assert.equal(r.value, "5Sep_BraaiDayOffer");
+  assert.ok(r.notes.some((n) => n.includes("Sept")));
+});
+
+test("leading zero is dropped", () => {
+  assert.equal(resolveCampaign("09Sep_Foo", { now: NOW }).value, "9Sep_Foo");
+});
+
+test("--date overrides a send scheduled for another day", () => {
+  assert.equal(resolveCampaign("Heritage Day", { date: "2026-09-24", now: NOW }).value, "24Sep_HeritageDay");
+  assert.equal(resolveCampaign("24Sep_HeritageDay", { date: "25Sep", now: NOW }).value, "25Sep_HeritageDay");
+});
+
+test("--date accepts SA d/m/yyyy and long month names", () => {
+  assert.equal(parseDateToken("24/09/2026"), "24Sep");
+  assert.equal(parseDateToken("24 September"), "24Sep");
+  assert.equal(parseDateToken("2026-09-24"), "24Sep");
+  assert.equal(parseDateToken("banana"), null);
+  assert.equal(parseDateToken("24/13/2026"), null);
+});
+
+test("separators and casing all collapse to PascalCase", () => {
+  assert.equal(pascal("spring-promotion"), "SpringPromotion");
+  assert.equal(pascal("spring_promotion"), "SpringPromotion");
+  assert.equal(pascal("  spring   promotion "), "SpringPromotion");
+  assert.equal(pascal("R500 promo"), "R500Promo");
+});
+
+test("an acronym keeps its case", () => {
+  assert.equal(resolveCampaign("CTWA Launch", { now: NOW }).value, "9Sep_CTWALaunch");
+});
+
+test("empty and title-less inputs error rather than minting rubbish", () => {
+  assert.ok(resolveCampaign("", { now: NOW }).error);
+  assert.ok(resolveCampaign("9Sep", { now: NOW }).error);
+  assert.ok(resolveCampaign("Spring", { date: "nonsense", now: NOW }).error);
+});
+
+test("utm_content is per-link and gets no date", () => {
+  assert.equal(resolveContent("View More").value, "ViewMore");
+  assert.equal(resolveContent("").value, "");
+});
+
+test("dateToken / isConforming", () => {
+  assert.equal(dateToken(NOW), "9Sep");
+  assert.equal(dateToken(new Date(2026, 11, 25)), "25Dec");
+  assert.ok(isConforming("9Sep_SpringPromotion"));
+  assert.ok(!isConforming("9Sept_SpringPromotion"));
+  assert.ok(!isConforming("SpringPromotion"));
+  assert.ok(!isConforming("9Sep_Spring_Promotion"));
+});

package/src/commands/agent-test.js

@@ -45,11 +45,21 @@ async function clearConv(orgId, agent) {
   return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
 }
 
+// A bare string is ONE needle, not a list of characters. Iterating a string
+// with for..of yields its characters, so a pack written as
+// `"expect": "fund rules"` used to report ten single-letter checks that all
+// trivially passed (and, for expectNot, all trivially failed) — a wrong
+// pass/fail signal that still looked like a real result.
+function needles(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
 function checkExpectations(turn, replyText) {
   const results = [];
   const hay = (replyText || "").toLowerCase();
-  for (const e of turn.expect || []) results.push({ kind: "expect", needle: e, ok: hay.includes(String(e).toLowerCase()) });
-  for (const e of turn.expectNot || []) results.push({ kind: "expectNot", needle: e, ok: !hay.includes(String(e).toLowerCase()) });
+  for (const e of needles(turn.expect)) results.push({ kind: "expect", needle: e, ok: hay.includes(String(e).toLowerCase()) });
+  for (const e of needles(turn.expectNot)) results.push({ kind: "expectNot", needle: e, ok: !hay.includes(String(e).toLowerCase()) });
   return results;
 }
 

package/src/commands/links.js

@@ -5,16 +5,26 @@
 // in the dialog: utm_source=whatsapp, utm_medium=whatsapp_paid fixed, campaign +
 // content yours.
 //
-//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign 13Aug_Seeds --content 13Aug_Seeds
-//   flowiq links shorten <org> --file ./message.txt --campaign X --content X --domain linklnk.io
+//   flowiq links shorten <org> --url <u> [--url <u2>…] --campaign "Spring Promotion"
+//   flowiq links shorten <org> --file ./message.txt --campaign X --content ViewMore --domain linklnk.io
 //   flowiq links list <org> [--campaign X] [--limit 25]
 //
+// NAMING — you do not have to get the tag right yourself. The house convention
+// is `Date_Campaign` (`9Sep_SpringPromotion`: the date the broadcast GOES OUT,
+// then the campaign title in PascalCase), and --campaign is normalised to it:
+// today's date is prefixed when you omit one, `Sept`→`Sep`, a fused
+// `10JunFathersDay` gains its underscore, and spaces/hyphens become PascalCase.
+// The resolved tag is printed before anything is minted (shorten is dry-run by
+// default). `--date <9Sep|2026-09-24|24/9/2026>` for a send going out later;
+// `--raw-campaign` to bypass normalisation entirely.
+//
 // Dry-run FIRST (`--dry-run`) on anything going into a real campaign: it shows
 // the exact destination URL each short link will carry, and whether an identical
 // row already exists (so you can see you are about to reuse an OLD campaign tag).
 
 import fs from "node:fs";
 import { http } from "../http.js";
+import { resolveCampaign, resolveContent, isConforming } from "../campaign-naming.js";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const URL_PATTERN = /(https?:\/\/[^\s\)]+)/g;
@@ -59,14 +69,50 @@ export async function shorten(orgId, opts = {}) {
 
   const dryRun = opts.dryRun !== false && opts.commit !== true;
 
+  // ── Campaign naming (Date_Campaign) ───────────────────────────────────────
+  // Normalise what was typed into the house convention so staff do not have to
+  // carry it in their heads. --raw-campaign opts out; the agent's own `ai_<org>`
+  // links are minted server-side and never come through here.
+  let campaign = opts.campaign;
+  let content = opts.content;
+  const namingNotes = [];
+  if (campaign && !opts.rawCampaign) {
+    const r = resolveCampaign(campaign, { date: opts.date });
+    if (r.error) {
+      console.error(`Error: ${r.error}`);
+      console.error(`Convention is Date_Campaign, e.g. --campaign "Spring Promotion" → 9Sep_SpringPromotion.`);
+      console.error(`Pass --raw-campaign to use "${campaign}" exactly as typed.`);
+      process.exit(1);
+    }
+    if (r.changed) namingNotes.push(`campaign "${campaign}" → ${r.value}`, ...r.notes.map((n) => `  · ${n}`));
+    campaign = r.value;
+  } else if (campaign && opts.rawCampaign && !isConforming(campaign)) {
+    namingNotes.push(`campaign "${campaign}" used raw (--raw-campaign) — does not match Date_Campaign`);
+  }
+  // utm_content is per-LINK (which button / which product). Default it to the
+  // campaign, which is what the paired-flags API expects and what most sends do.
+  if (campaign && !content) {
+    content = campaign;
+    namingNotes.push(`content defaulted to ${content} (pass --content for a per-link tag, e.g. ViewMore)`);
+  } else if (content && !opts.rawCampaign) {
+    const rc = resolveContent(content);
+    if (rc.changed) namingNotes.push(`content "${content}" → ${rc.value}`);
+    content = rc.value;
+  }
+  if (namingNotes.length && !opts.json) {
+    console.log("Naming (Date_Campaign):");
+    for (const n of namingNotes) console.log(`  ${n}`);
+    console.log("");
+  }
+
   let resp;
   try {
     resp = await http.post("links", {
       organization_id: orgId,
       action: "shorten",
       urls: unique,
-      campaign: opts.campaign,
-      content: opts.content,
+      campaign,
+      content,
       domain: opts.domain,
       dry_run: dryRun,
     });

package/src/commands/templates.js

@@ -154,3 +154,204 @@ export async function list() {
     }
   }
 }
+
+// ── show ────────────────────────────────────────────────────────────────────
+// Render ONE template row — including a DRAFT, which nothing else in the CLI
+// can see. `templates pull` reads Meta and a draft never reaches Meta;
+// api/cli/_introspect.js also starts from Meta by name, so it is blind too.
+// Until this existed, reviewing a draft meant the dialog or raw SQL.
+const MONTH_RE = /\{\{(\d+)\}\}/g;
+
+function substitute(text, examples) {
+  return String(text ?? "").replace(MONTH_RE, (m, n) => {
+    const v = examples?.[n];
+    return v ? String(v) : m;
+  });
+}
+
+function indent(text, pad = "    ") {
+  return String(text ?? "").split("\n").map((l) => pad + l).join("\n");
+}
+
+/** Cheap structural checks — the ones that are free while rendering. */
+function lintDraft(d) {
+  const warn = [];
+  const body = (d.components || []).find((c) => c.type === "BODY");
+
+  if (body?.text) {
+    const nums = [...new Set([...body.text.matchAll(/\{\{(\d+)\}\}/g)].map((m) => Number(m[1])))].sort((a, b) => a - b);
+    if (nums.some((n, i) => n !== i + 1)) {
+      warn.push(`BODY variables are not sequential from {{1}} — found ${nums.map((n) => `{{${n}}}`).join(", ")}. Meta rejects this as "BODY is missing expected field(s) (example)".`);
+    }
+    for (const n of nums) {
+      if (!d.parameterExamples?.[n]) {
+        warn.push(`BODY {{${n}}} has no example — Meta's reviewers will see the placeholder text instead of a real value.`);
+      }
+    }
+    // WhatsApp formatting: a marker pair only renders when neither marker sits
+    // against whitespace on the inside. `👇_ Swipe …below._` shipped in this very
+    // template and renders as literal underscores. Deliberately only checked on
+    // lines that look like a PAIR (>=2 of the same marker), so a lone `*` used
+    // as a bullet or a `~` in a URL is not flagged.
+    for (const [mark, name] of [["_", "an italic"], ["*", "a bold"], ["~", "a strikethrough"]]) {
+      for (const line of body.text.split("\n")) {
+        // Iterate CODE POINTS, not UTF-16 units: `👇` is a surrogate pair, so
+        // mixing [...line] positions with line[i] lookups reads the wrong char
+        // and the check silently never fires (which is how 👇_ shipped).
+        const chars = [...line];
+        const idxs = chars.reduce((a, ch, i) => (ch === mark ? (a.push(i), a) : a), []);
+        if (idxs.length < 2) continue;
+        const opensBad = /\s/.test(chars[idxs[0] + 1] || "");
+        const closesBad = /\s/.test(chars[idxs[idxs.length - 1] - 1] || "");
+        if (opensBad || closesBad) {
+          warn.push(`BODY line has ${name} marker "${mark}" against a space (${opensBad ? "after the opening" : "before the closing"} ${mark}) — WhatsApp will not render it and the customer sees the literal ${mark}: ${JSON.stringify(line.trim().slice(0, 70))}`);
+          break;
+        }
+      }
+    }
+    if (/\s$/.test(body.text)) warn.push("BODY ends with trailing whitespace/newline.");
+    if (body.text.length > 1024) warn.push(`BODY is ${body.text.length} chars (Meta limit 1024).`);
+  }
+
+  const cards = Array.isArray(d.carouselCards) ? d.carouselCards : [];
+  if (d.templateMode === "carousel") {
+    if (cards.length < 2 || cards.length > 10) warn.push(`Carousel has ${cards.length} card(s) — Meta requires 2-10.`);
+    const urlVars = new Set();
+    cards.forEach((c, i) => {
+      if (!c.media?.media_url && !c.media?.asset_handle) warn.push(`Card ${i + 1} has no media.`);
+      if ((c.body || "").length > 160) warn.push(`Card ${i + 1} body is ${c.body.length} chars (Meta limit 160).`);
+      for (const b of c.buttons || []) {
+        if (b.type === "URL" && b.url) {
+          const vars = [...b.url.matchAll(/\{\{(\d+)\}\}/g)].map((m) => m[1]);
+          vars.forEach((v) => urlVars.add(v));
+          if (vars.length > 1) warn.push(`Card ${i + 1} button "${b.text}" has ${vars.length} URL variables — Meta supports exactly 1.`);
+          if (vars.length === 1 && vars[0] !== "1") {
+            warn.push(`Card ${i + 1} button "${b.text}" uses {{${vars[0]}}} — each card's URL variable must be {{1}} (Meta numbers card params per card). This card's link will break at send.`);
+          }
+        }
+      }
+    });
+    const shapes = new Set(cards.map((c) => `${c.headerFormat}|${(c.buttons || []).map((b) => b.type).join(",")}`));
+    if (shapes.size > 1) warn.push(`Cards do not share one shape (${[...shapes].join("  vs  ")}) — Meta requires every card to have the same header format and button set.`);
+  }
+  return warn;
+}
+
+function renderDraft(d, opts) {
+  console.log(`  mode:      ${d.templateMode || "standard"}`);
+  console.log(`  language:  ${d.language || "(unset)"}   parameters: ${d.parameterFormat || "POSITIONAL"}`);
+  const ex = d.parameterExamples || {};
+  const exKeys = Object.keys(ex);
+  if (exKeys.length) {
+    console.log(`  examples:  ${exKeys.map((k) => `{{${k}}} = ${ex[k] === "" ? "(EMPTY)" : JSON.stringify(ex[k])}`).join("  ")}`);
+  }
+
+  for (const c of d.components || []) {
+    console.log(`\n  ${c.type}${c.format ? ` (${c.format})` : ""}`);
+    if (c.text) {
+      console.log(indent(substitute(c.text, ex)));
+      if (opts.raw) { console.log("\n  raw:"); console.log(indent(JSON.stringify(c.text))); }
+    }
+    for (const b of c.buttons || []) {
+      console.log(`    [${b.type}] ${b.text}${b.url ? `  → ${b.url}` : ""}${b.phone_number ? `  → ${b.phone_number}` : ""}`);
+    }
+  }
+
+  const cards = Array.isArray(d.carouselCards) ? d.carouselCards : [];
+  if (cards.length) {
+    console.log(`\n  CAROUSEL — ${cards.length} card(s)`);
+    cards.forEach((c, i) => {
+      console.log(`\n  ── card ${i + 1} ──`);
+      console.log(`    header:  ${c.headerFormat || "?"}`);
+      if (c.media) {
+        console.log(`    media:   ${c.media.media_url || "(none)"}`);
+        if (c.media.original_filename) console.log(`             file: ${c.media.original_filename}${c.media.file_type ? ` (${c.media.file_type})` : ""}`);
+        console.log(`             asset handle: ${c.media.asset_handle ? "present" : "MISSING"}`);
+      }
+      if (c.body) console.log(`    body:    ${substitute(c.body, ex)}`);
+      for (const b of c.buttons || []) {
+        console.log(`    [${b.type}] ${b.text}${b.url ? `  → ${b.url}` : ""}${b.example ? `   example: ${b.example}` : ""}`);
+      }
+    });
+  }
+}
+
+export async function show(orgId, name, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID. Find it with: flowiq org list <name>`);
+    process.exit(1);
+  }
+  if (!name) {
+    console.error("Error: pass the template name, e.g. flowiq templates show <org> heritage_day_v2");
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.get("meta-templates", { organization_id: orgId, name, full: "1" });
+  } catch (e) {
+    console.error(`Show failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  const rows = resp.templates || [];
+  if (!rows.length) {
+    console.error(`No template on this org matching "${name}". List them with: flowiq templates status ${orgId}`);
+    process.exit(1);
+  }
+  // Prefer an exact name match; otherwise if the substring is ambiguous, say so.
+  let row = rows.find((r) => r.template_name === name);
+  if (!row) {
+    if (rows.length > 1) {
+      console.error(`"${name}" matches ${rows.length} templates — name one exactly:`);
+      for (const r of rows) console.error(`  ${r.template_name}  [${r.status || "no status"}]`);
+      process.exit(1);
+    }
+    row = rows[0];
+  }
+
+  if (opts.json) { console.log(JSON.stringify(row, null, 2)); return; }
+
+  // Version skew: `template_data` only comes back when the server understands
+  // ?full=1. An older api/cli deploy answers the row without it, and rendering
+  // that silently produces a confident, EMPTY draft — so refuse instead.
+  if (!("template_data" in row)) {
+    console.error(`The API did not return this template's content.`);
+    console.error(`api/cli/meta-templates.js on the server is older than this CLI (it needs the ?full=1 branch, shipped with CLI v0.6.7).`);
+    console.error(`Everything else still works — retry once the Vercel deploy of origin/main has landed.`);
+    process.exit(1);
+  }
+  const td = row.template_data || {};
+  const isDraft = td.is_draft === true || row.status === "DRAFT";
+  console.log(`${row.template_name}  [${row.status || "no status"}]${row.category ? ` ${row.category}` : ""}`);
+  console.log(`  org:       ${resp.organization_id}`);
+  console.log(`  created:   ${row.created_at || "?"}${row.updated_at && row.updated_at !== row.created_at ? `   updated: ${row.updated_at}` : ""}`);
+
+  if (isDraft) {
+    const d = td.draft || {};
+    console.log(`  source:    DRAFT (never submitted to Meta — this content exists only here)`);
+    renderDraft(d, opts);
+    const warn = lintDraft(d);
+    console.log(`\n  Checks`);
+    if (!warn.length) {
+      console.log(`    ✓ nothing obvious — these are structural checks only; Meta's review is still the authority.`);
+    } else {
+      for (const w of warn) console.log(`    ⚠ ${w}`);
+    }
+    console.log(`\n  This is a draft: edit it in Broadcasts → Templates, then submit with`);
+    console.log(`  flowiq templates create ${orgId} --request-file <file>  (submitting is irreversible — it burns the name).`);
+    return;
+  }
+
+  // A LIVE row's template_data is only the send-time MAPPING; the structure
+  // (body text, buttons, cards) lives at Meta, so point at the tool that reads it.
+  console.log(`  source:    live row — template_data here is the send-time mapping, not the message structure`);
+  if (td.meta_template_id) console.log(`  meta id:   ${td.meta_template_id}`);
+  if (td.meta_status) console.log(`  meta:      ${td.meta_status}${td.meta_category ? ` / ${td.meta_category}` : ""}`);
+  if (td.parameter_format) console.log(`  params:    ${td.parameter_format}`);
+  if (td.header) console.log(`  header:    ${JSON.stringify(td.header)}`);
+  if (td.body_params && Object.keys(td.body_params).length) console.log(`  body:      ${JSON.stringify(td.body_params)}`);
+  if (td.button_params && Object.keys(td.button_params).length) console.log(`  buttons:   ${JSON.stringify(td.button_params)}`);
+  if (td.carousel?.cards) console.log(`  carousel:  ${td.carousel.cards.length} card(s) with stored header media`);
+  console.log(`\n  For the message structure as Meta holds it: flowiq templates pull ${orgId}`);
+}

package/src/index.js

@@ -269,7 +269,7 @@ export function run(argv) {
   // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
   const templates = program.command("templates")
     .alias("tpl")
-    .description("Read an org's WhatsApp templates from Meta (pull/list); create + submit to Meta (create/status)");
+    .description("Read an org's WhatsApp templates (pull/list/show — show also reads DRAFTS); create + submit to Meta (create/status)");
   templates.command("pull <organization_id>")
     .description("Fetch every live WhatsApp template from Meta into a local JSON snapshot")
     .action((orgId) => templatesCmd.pull(orgId));
@@ -284,6 +284,11 @@ export function run(argv) {
     .description("List the org's template rows (name + status) to poll Meta approval")
     .option("--name <substr>", "filter by template name substring")
     .action((orgId, opts) => templatesCmd.status(orgId, opts));
+  templates.command("show <organization_id> <name>")
+    .description("Render ONE template row in full — including a DRAFT, which `pull` cannot see (drafts never reach Meta)")
+    .option("--raw", "also print the raw body text (escaped), so invisible whitespace is visible")
+    .option("--json", "raw JSON row output")
+    .action((orgId, name, opts) => templatesCmd.show(orgId, name, opts));
 
   // org (read-only org summary for the prompt-builder skill, creds stripped)
   const org = program.command("org").description("Org info (read) + create a new organization");
@@ -625,8 +630,10 @@ export function run(argv) {
     .description("Shorten one or more URLs, tagging each with utm_campaign/utm_content")
     .option("--url <url>", "URL to shorten (repeatable)", (v, acc) => (acc || []).concat([v]), [])
     .option("--file <path>", "shorten every URL found in this text file")
-    .option("--campaign <value>", "utm_campaign (e.g. 13Aug_Seeds) — must be paired with --content")
-    .option("--content <value>", "utm_content — must be paired with --campaign")
+    .option("--campaign <value>", "campaign title — normalised to the house Date_Campaign convention (\"Spring Promotion\" → 9Sep_SpringPromotion)")
+    .option("--content <value>", "utm_content, the per-link tag (e.g. ViewMore); defaults to the campaign")
+    .option("--date <value>", "send date for the campaign tag when it is not today: 9Sep | 2026-09-24 | 24/9/2026")
+    .option("--raw-campaign", "use --campaign exactly as typed, bypassing the Date_Campaign normalisation")
     .option("--domain <host>", "short domain: chatcart.io (default) | linklnk.io | yapi.store")
     .option("--commit", "actually mint the links (omit = dry-run preview)")
     .option("--json", "raw JSON output")