@flowapt/flowiq-cli 0.6.7 → 0.7.0

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/flag-values.js

@@ -0,0 +1,42 @@
+// Parse the VALUE argument of `flowiq org flags set <org> <key> <value>`.
+//
+// The SERVER is the validator (api/cli/_org-flags-registry.js type-checks
+// against the registry), so this only has to turn what a human typed into the
+// most obvious JSON: `true`/`false` → booleans, a bare integer → number,
+// `[…]`/`{…}` → parsed JSON, `@file.json` → that file's JSON, `null` → null,
+// everything else → the string as typed (the server splits "a,b" for list
+// keys and coerces "true" for booleans, so a plain string is never wrong).
+
+import { readFileSync } from "node:fs";
+
+export function parseFlagValue(raw) {
+  if (raw === undefined || raw === null) throw new Error("a value is required");
+  const s = String(raw).trim();
+  if (s === "") throw new Error("value must not be empty (use `unset` to remove a key)");
+
+  if (s.startsWith("@")) {
+    const file = s.slice(1);
+    let text;
+    try { text = readFileSync(file, "utf8"); } catch (e) { throw new Error(`cannot read ${file}: ${e.message}`); }
+    try { return JSON.parse(text); } catch (e) { throw new Error(`${file} is not valid JSON: ${e.message}`); }
+  }
+  const lower = s.toLowerCase();
+  if (["true", "yes", "on"].includes(lower)) return true;
+  if (["false", "no", "off"].includes(lower)) return false;
+  if (lower === "null") return null;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (s.startsWith("[") || s.startsWith("{")) {
+    try { return JSON.parse(s); } catch (e) { throw new Error(`value looks like JSON but does not parse: ${e.message}`); }
+  }
+  return s;
+}
+
+/** Render a flag value for a table cell: short, one line, no surprises. */
+export function fmtValue(v, width = 60) {
+  if (v === undefined) return "(absent)";
+  if (v === null) return "null";
+  if (typeof v === "string") return v.length > width ? `${v.slice(0, width - 1)}…` : v;
+  if (typeof v !== "object") return String(v);
+  const s = JSON.stringify(v);
+  return s.length > width ? `${s.slice(0, width - 1)}…` : s;
+}

package/src/flag-values.test.mjs

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { parseFlagValue, fmtValue } from "./flag-values.js";
+
+test("booleans in every spelling a human types", () => {
+  for (const t of ["true", "TRUE", "yes", "on"]) assert.equal(parseFlagValue(t), true);
+  for (const f of ["false", "no", "off", "OFF"]) assert.equal(parseFlagValue(f), false);
+});
+
+test("integers become numbers, decimals stay strings (the server decides)", () => {
+  assert.equal(parseFlagValue("5"), 5);
+  assert.equal(parseFlagValue("-1"), -1);
+  assert.equal(parseFlagValue("1.5"), "1.5");
+});
+
+test("JSON arrays and objects parse; a broken one is an error, not a string", () => {
+  assert.deepEqual(parseFlagValue('["a","b"]'), ["a", "b"]);
+  assert.deepEqual(parseFlagValue('{"enabled":true}'), { enabled: true });
+  assert.throws(() => parseFlagValue("[a,b"), /does not parse/);
+});
+
+test("comma lists stay strings — the server splits them for string[] keys", () => {
+  assert.equal(parseFlagValue("summer,winter"), "summer,winter");
+});
+
+test("@file reads JSON from disk", () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "flowiq-flags-"));
+  const f = path.join(dir, "v.json");
+  writeFileSync(f, JSON.stringify({ enabled: true, schedules: [] }));
+  assert.deepEqual(parseFlagValue(`@${f}`), { enabled: true, schedules: [] });
+  assert.throws(() => parseFlagValue("@/nonexistent/x.json"), /cannot read/);
+});
+
+test("empty is refused (unset is a separate verb)", () => {
+  assert.throws(() => parseFlagValue(""), /unset/);
+  assert.throws(() => parseFlagValue("   "), /unset/);
+});
+
+test("null is explicit null", () => {
+  assert.equal(parseFlagValue("null"), null);
+});
+
+test("fmtValue keeps table cells on one line and marks absence", () => {
+  assert.equal(fmtValue(undefined), "(absent)");
+  assert.equal(fmtValue(true), "true");
+  assert.equal(fmtValue({ a: 1 }), '{"a":1}');
+  assert.equal(fmtValue("x".repeat(80), 10).length, 10);
+});

package/src/http.js

@@ -7,6 +7,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadConfig } from "./config.js";
+import { cmpVersion } from "./update-check.js";
 
 // Sent on every request as X-Flowiq-Cli-Version so the server-side audit log
 // records WHICH CLI version made a change (a stale install is a real source of
@@ -17,6 +18,42 @@ try {
   CLI_VERSION = JSON.parse(readFileSync(path.join(dir, "..", "package.json"), "utf8")).version || "unknown";
 } catch { /* version is a nice-to-have; never block a request on it */ }
 
+export const cliVersion = () => CLI_VERSION;
+
+// ── Server version contract ─────────────────────────────────────────────────
+// Every api/cli/* response carries X-Flowiq-Min-Version (the oldest client the
+// current server contract supports) and X-Flowiq-Api-Build. We record them on
+// every call, and warn ONCE per process when this install is below the minimum.
+//
+// This is the half npm cannot tell you: `npm i -g` compares against the
+// registry, which says nothing about whether the SERVER still speaks your
+// dialect. It is also instant and offline-safe — it rides on a request you were
+// making anyway, with no registry round-trip and no 24h cache to go stale.
+export const serverContract = { minVersion: null, apiBuild: null };
+let warnedBelowMinimum = false;
+
+function noteServerContract(resp) {
+  const min = resp.headers.get("x-flowiq-min-version");
+  const build = resp.headers.get("x-flowiq-api-build");
+  if (min) serverContract.minVersion = min;
+  if (build) serverContract.apiBuild = build;
+
+  if (min && CLI_VERSION !== "unknown" && cmpVersion(min, CLI_VERSION) > 0 && !warnedBelowMinimum) {
+    warnedBelowMinimum = true;
+    process.stderr.write(
+      `\n  ⬆ FLOWIQ CLI TOO OLD FOR THE SERVER — installed ${CLI_VERSION}, server requires ${min}\n` +
+      `    Run this before continuing:  npm i -g @flowapt/flowiq-cli@latest\n` +
+      `    (results from this run may be wrong or incomplete)\n\n`
+    );
+  }
+}
+
+/** True when this install is older than the server's declared minimum. */
+export function isBelowServerMinimum() {
+  const min = serverContract.minVersion;
+  return !!(min && CLI_VERSION !== "unknown" && cmpVersion(min, CLI_VERSION) > 0);
+}
+
 /**
  * Turn an error body into a STRING a human can act on.
  *
@@ -97,6 +134,7 @@ async function call(method, endpoint, { query, body } = {}) {
   }
 
   const resp = await fetch(url, init);
+  noteServerContract(resp);
   const text = await resp.text();
   let parsed, isJson = true;
   try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }

package/src/index.js

@@ -19,6 +19,8 @@ import * as hoursCmd from "./commands/hours.js";
 import * as reportCmd from "./commands/report.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
+import * as orgFlagsCmd from "./commands/org-flags.js";
+import * as insightsCmd from "./commands/insights.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
@@ -35,6 +37,7 @@ import * as guideCmd from "./commands/guide.js";
 import * as auditCmd from "./commands/audit.js";
 import * as storeApiCmd from "./commands/store-api.js";
 import { maybeNotifyUpdate } from "./update-check.js";
+import * as doctorCmd from "./commands/doctor.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -269,7 +272,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,9 +287,14 @@ 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");
+  const org = program.command("org").description("Org info (read), create a new organization, read/set its feature flags");
   org.command("list [search]")
     .description("List organizations with their UUIDs — the lookup every other command needs (filter by name/slug)")
     .option("--all", "include inactive organizations")
@@ -304,6 +312,84 @@ export function run(argv) {
     .option("--json", "print the raw JSON payload")
     .action((orgId, opts) => orgCmd.info(orgId, opts));
 
+  // org flags — organizations.feature_flags (the Settings → Profile switches).
+  // Registry-allowlisted writes, credentials never read or written, dangerous
+  // keys need --yes. `list --key` is the cross-org census that was SQL-only
+  // until 10 Sep 2026.
+  const orgFlags = org.command("flags").description("Read + set an org's feature flags (Settings → Profile switches); `list --key` = cross-org census");
+  orgFlags.command("show <organization_id>")
+    .description("Every flag on the org, by Settings section (credentials redacted)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => orgFlagsCmd.show(orgId, opts));
+  orgFlags.command("list")
+    .description("Cross-org census of ONE flag: which orgs carry it, and its value")
+    .requiredOption("--key <path>", "dotted flag path, e.g. export_insights.enabled or mcp_member_access.enabled")
+    .option("--all", "include inactive organizations")
+    .option("--on", "only orgs where the value is true")
+    .option("--off", "only orgs where the value is not true (false or absent)")
+    .option("--present", "only orgs that carry the key")
+    .option("--absent", "only orgs that do not carry the key")
+    .option("--json", "raw JSON")
+    .action((opts) => orgFlagsCmd.list(opts));
+  orgFlags.command("set <organization_id> <key> <value>")
+    .description("Set a registered flag (true/false, a number, JSON, or @file.json); type-checked server-side")
+    .option("--yes", "confirm a dangerous flag (the Profile tab's amber-warning switches)")
+    .option("--json", "raw JSON")
+    .action((orgId, key, value, opts) => orgFlagsCmd.set(orgId, key, value, opts));
+  orgFlags.command("unset <organization_id> <key>")
+    .description("Remove a flag key from the org (reverts to the platform default) — always needs --yes")
+    .option("--yes", "confirm")
+    .option("--json", "raw JSON")
+    .action((orgId, key, opts) => orgFlagsCmd.unset(orgId, key, opts));
+  orgFlags.command("keys")
+    .description("What is settable: every registered flag with its type, section and danger note")
+    .option("--section <name>", "filter by Settings section (substring)")
+    .option("--json", "raw JSON")
+    .action((opts) => orgFlagsCmd.keys(opts));
+
+  // insights — the Customer Insights Report (feature_flags.export_insights)
+  const collectEmail = (v, acc) => (acc || []).concat(v);
+  const insights = program.command("insights").description("Customer Insights Report: who has it, enable/disable per org, run one now");
+  insights.command("status [organization_id]")
+    .description("All orgs (or one): enabled, schedules as the scheduler reads them, recipients, own OpenAI key, last report, chats in 30d")
+    .option("--all", "include inactive organizations")
+    .option("--on", "only orgs with insights enabled")
+    .option("--off", "only orgs with insights NOT enabled")
+    .option("--min-chats <n>", "only orgs with at least n chatting contacts in the last 30 days")
+    .option("--sort <by>", "chats (default) | name | last")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.status(orgId, opts));
+  insights.command("enable <organization_id>")
+    .description("Enable the report (or update its config). Cadence flags REPLACE the schedules; none given = keep existing, else weekly Monday")
+    .option("--daily", "add a daily schedule")
+    .option("--weekly [day]", "add a weekly schedule (day: monday … sunday; default monday)")
+    .option("--monthly [day]", "add a monthly schedule (day: 1-28 or last; default last)")
+    .option("--report <type>", "standard (default) | advanced — applies to the cadence flags given")
+    .option("--store-only", "the schedules given store the report without emailing anyone")
+    .option("--recipient <email>", "recipient list (repeatable; REPLACES the existing list)", collectEmail)
+    .option("--add-recipient <email>", "add to the existing recipients (repeatable)", collectEmail)
+    .option("--remove-recipient <email>", "remove from the existing recipients (repeatable)", collectEmail)
+    .option("--dry-run", "show what would be written, write nothing")
+    .option("--force", "write even if pre-flight fails (no OpenAI key / no recipients)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.enable(orgId, opts));
+  insights.command("disable <organization_id>")
+    .description("Turn the scheduled report off (schedules + recipients are kept)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.disable(orgId, opts));
+  insights.command("run <organization_id>")
+    .description("Run one report now (DRY RUN by default — add --commit). Same path as the Profile tab's Run Now")
+    .option("--period <p>", "daily (default: last 24h) | weekly (7d) | monthly (30d)")
+    .option("--from <date>", "custom window start (YYYY-MM-DD, SAST) — with --to")
+    .option("--to <date>", "custom window end (YYYY-MM-DD, SAST) — with --from")
+    .option("--report <type>", "standard | advanced (default: the org's schedule for that period, else standard)")
+    .option("--recipient <email>", "send to these instead of the configured recipients (repeatable)", collectEmail)
+    .option("--store-only", "store the report, email nobody")
+    .option("--commit", "actually fire it")
+    .option("--force", "fire even if pre-flight fails")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => insightsCmd.run(orgId, opts));
+
   // agent (list / create / config — config defaults to the active agent, or --agent <id>)
   const agent = program.command("agent").description("List, create, and configure an org's agents");
   agent.command("list <organization_id>")
@@ -625,8 +711,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")
@@ -776,6 +864,12 @@ export function run(argv) {
     .option("--out <file>", "write the JSON to a file instead of stdout")
     .action((orgId, path, opts) => storeApiCmd.wooGet(orgId, path, opts));
 
+  // doctor (version + auth + server contract in one read-only command)
+  program.command("doctor")
+    .description("Check this install: version vs npm, auth, and whether the server still supports it. Exits 1 if something needs fixing")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => { process.exitCode = await doctorCmd.doctor(opts); });
+
   // guide (bundled docs — always match the installed version)
   program.command("guide")
     .description("Read the team guide (how we use this CLI); --reference for the full command reference")

package/src/insights-config.js

@@ -0,0 +1,69 @@
+// Pure helpers for `flowiq insights` — turning flags a human types
+// (`--weekly monday`, `--monthly last`) into the `schedules[]` entries the
+// export-insights scheduler reads, and describing a config the way the
+// scheduler will actually run it. No I/O; unit-tested in insights-config.test.mjs.
+
+export const DOW = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+export const DOW_LABEL = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+
+/** "monday" | "mon" | "1" → 1. Bare `--weekly` (true) → Monday, the scheduler's default. */
+export function parseWeekday(v) {
+  if (v === true || v === undefined || v === null || v === "") return 1;
+  const s = String(v).trim().toLowerCase();
+  if (/^[0-6]$/.test(s)) return Number(s);
+  const idx = DOW.findIndex((d) => d === s || d.slice(0, 3) === s);
+  if (idx >= 0) return idx;
+  throw new Error(`--weekly expects a day (monday … sunday, or 0-6), got "${v}"`);
+}
+
+/** "last" | "15" → "last" | 15. Bare `--monthly` (true) → "last", the scheduler's default. */
+export function parseMonthlyDay(v) {
+  if (v === true || v === undefined || v === null || v === "") return "last";
+  const s = String(v).trim().toLowerCase();
+  if (s === "last") return "last";
+  if (/^\d{1,2}$/.test(s)) {
+    const n = Number(s);
+    if (n >= 1 && n <= 28) return n;
+  }
+  throw new Error(`--monthly expects a day of the month (1-28) or "last", got "${v}"`);
+}
+
+/**
+ * Build schedules[] from the enable flags. Returns null when no cadence flag
+ * was given (the server then keeps what exists, or applies its default).
+ *   opts: { daily?, weekly?, monthly?, report?, storeOnly? }
+ */
+export function schedulesFromOpts(opts = {}) {
+  const report = opts.report ?? "standard";
+  if (!["standard", "advanced"].includes(report)) throw new Error(`--report must be standard or advanced, got "${report}"`);
+  const storeOnly = opts.storeOnly === true;
+  const out = [];
+  if (opts.daily) out.push({ frequency: "daily", report_type: report, store_only: storeOnly });
+  if (opts.weekly !== undefined) out.push({ frequency: "weekly", weekly_day: parseWeekday(opts.weekly), report_type: report, store_only: storeOnly });
+  if (opts.monthly !== undefined) out.push({ frequency: "monthly", monthly_day: parseMonthlyDay(opts.monthly), report_type: report, store_only: storeOnly });
+  return out.length ? out : null;
+}
+
+/** One line per schedule, in the scheduler's own vocabulary. */
+export function describeSchedule(s) {
+  const tag = `${s.report_type ?? "standard"}${s.store_only ? "/store-only" : ""}`;
+  if (s.frequency === "daily") return `daily [${tag}]`;
+  if (s.frequency === "weekly") return `weekly ${DOW_LABEL[typeof s.weekly_day === "number" ? s.weekly_day : 1]} [${tag}]`;
+  if (s.frequency === "monthly") return `monthly day=${s.monthly_day ?? "last"} [${tag}]`;
+  return `${s.frequency} [${tag}]`;
+}
+
+/**
+ * A YYYY-MM-DD typed by a South African becomes the SAST day boundary, not
+ * UTC's — otherwise `--from 2026-09-01` silently starts at 02:00 SAST.
+ * `end` covers the whole day. Full ISO strings pass through untouched.
+ */
+export function sastRange(from, to) {
+  const day = /^\d{4}-\d{2}-\d{2}$/;
+  const start = day.test(from) ? new Date(`${from}T00:00:00+02:00`) : new Date(from);
+  const end = day.test(to) ? new Date(`${to}T23:59:59.999+02:00`) : new Date(to);
+  if (Number.isNaN(start.getTime())) throw new Error(`--from "${from}" is not a date`);
+  if (Number.isNaN(end.getTime())) throw new Error(`--to "${to}" is not a date`);
+  if (start >= end) throw new Error("--from must be before --to");
+  return { start: start.toISOString(), end: end.toISOString() };
+}

package/src/insights-config.test.mjs

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseWeekday, parseMonthlyDay, schedulesFromOpts, describeSchedule, sastRange } from "./insights-config.js";
+
+test("weekday parsing: names, abbreviations, digits, and the bare default", () => {
+  assert.equal(parseWeekday("monday"), 1);
+  assert.equal(parseWeekday("Fri"), 5);
+  assert.equal(parseWeekday("0"), 0);
+  assert.equal(parseWeekday(true), 1);
+  assert.throws(() => parseWeekday("someday"), /--weekly expects/);
+});
+
+test("monthly day: last, 1-28, bare default; 29+ refused (the scheduler never fires them)", () => {
+  assert.equal(parseMonthlyDay("last"), "last");
+  assert.equal(parseMonthlyDay("15"), 15);
+  assert.equal(parseMonthlyDay(true), "last");
+  assert.throws(() => parseMonthlyDay("31"), /1-28/);
+});
+
+test("no cadence flag → null (server keeps existing / applies default)", () => {
+  assert.equal(schedulesFromOpts({}), null);
+  assert.equal(schedulesFromOpts({ report: "advanced" }), null);
+});
+
+test("cadence flags build scheduler-shaped entries, store-only applies to all", () => {
+  const s = schedulesFromOpts({ daily: true, weekly: "monday", monthly: "last", report: "advanced", storeOnly: true });
+  assert.deepEqual(s, [
+    { frequency: "daily", report_type: "advanced", store_only: true },
+    { frequency: "weekly", weekly_day: 1, report_type: "advanced", store_only: true },
+    { frequency: "monthly", monthly_day: "last", report_type: "advanced", store_only: true },
+  ]);
+});
+
+test("bad report type is refused before anything reaches the server", () => {
+  assert.throws(() => schedulesFromOpts({ daily: true, report: "fancy" }), /--report must be/);
+});
+
+test("describeSchedule speaks the scheduler's vocabulary", () => {
+  assert.equal(describeSchedule({ frequency: "daily", report_type: "standard", store_only: true }), "daily [standard/store-only]");
+  assert.equal(describeSchedule({ frequency: "weekly", weekly_day: 3 }), "weekly Wednesday [standard]");
+  assert.equal(describeSchedule({ frequency: "weekly" }), "weekly Monday [standard]");
+  assert.equal(describeSchedule({ frequency: "monthly", report_type: "advanced" }), "monthly day=last [advanced]");
+});
+
+test("date-only --from/--to are SAST day boundaries, not UTC", () => {
+  const r = sastRange("2026-09-01", "2026-09-07");
+  assert.equal(r.start, "2026-08-31T22:00:00.000Z");
+  assert.equal(r.end, "2026-09-07T21:59:59.999Z");
+  assert.throws(() => sastRange("2026-09-07", "2026-09-01"), /before/);
+  assert.throws(() => sastRange("yesterday", "2026-09-01"), /not a date/);
+});