@flowapt/flowiq-cli 0.6.8 → 0.7.0

package/README.md

@@ -555,6 +555,48 @@ 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`.
 
+### Staying current — `flowiq doctor` (v0.6.9)
+
+```bash
+flowiq doctor          # version vs npm, auth, and whether the server still supports this install
+flowiq doctor --json   # same, machine-readable; exits 1 when something needs fixing
+```
+
+```
+  ✓ version    0.6.9 (latest)
+  ✓ api        https://api.flowiq.live
+  ✓ auth       you@flowapt.com · super admin
+  ✓ server     contract 0.6.8 or newer · build 1f0fd48c
+```
+
+**Three ways this install tells you it is stale**, so nobody — person or AI
+assistant — has to remember to check:
+
+1. **npm nudge.** Any command prints, on stderr, when a newer version is
+   published:
+   `⬆ FLOWIQ CLI OUT OF DATE — installed X, latest Y / Run this before continuing: npm i -g @flowapt/flowiq-cli@latest`.
+   The registry is polled at most once a day by a detached child, so the hint
+   costs nothing on the hot path and appears on the next run after a release.
+2. **Server contract.** Every `api/cli/*` response carries
+   `X-Flowiq-Min-Version` — the oldest client the deployed server still
+   supports — and the CLI warns once per process when this install is below it.
+   This is the half npm cannot tell you: the registry knows what is *published*,
+   not whether the **server** still speaks your dialect. It is instant and
+   offline-safe, riding on a request you were making anyway.
+3. **`flowiq doctor`**, when you want to ask deliberately.
+
+⚠️ Until 9 Sep 2026 the npm nudge was also gated on `process.stderr.isTTY`, so
+it was invisible to exactly the audience that most needs it — an assistant
+running `flowiq` through a tool call gets a pipe, not a TTY. Teammates' AI
+sessions could run a months-old CLI forever without ever being told. Writing to
+stderr was already the whole safety property; the TTY gate bought nothing.
+
+**Bumping `MIN_CLI_VERSION`** (`api/cli/_auth.js`): only when a server change
+would MISBEHAVE on an older client — a removed or renamed response field, a
+changed request shape, a validation rule an old client cannot satisfy. Never for
+additive work; a new endpoint or an opt-in query param leaves old clients
+correct, and crying wolf trains people to ignore the warning.
+
 ### Publishing (maintainers) — publish from a CLEAN checkout
 
 `npm publish` packs the **working tree**, not your branch. This repo's local
@@ -1041,6 +1083,54 @@ 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.
 
+### Insights — `flowiq insights status|enable|disable|run` (v0.7.0)
+
+The **Customer Insights Report** (the scheduled AI email: exec summary, top
+questions / complaints / topics, sentiment, product mentions — cron 72, 09:00
+SAST) per org. Reads and writes `feature_flags.export_insights` exactly the
+way the Insights Studio does, and fires a report the way the Profile tab's
+Run Now does.
+
+```bash
+flowiq insights status                          # every org: STATE · CHATS30D · KEY · LAST REPORT · RCPT · SCHEDULES
+flowiq insights status --off --min-chats 20     # who is missing it and has real chat volume
+flowiq insights status <organization_id>        # one org + its last 10 reports
+
+flowiq insights enable <organization_id> --weekly monday --recipient client@example.com --recipient matt@flowapt.com
+flowiq insights enable <organization_id> --daily --store-only --monthly last            # two schedules; dailies stored, not emailed
+flowiq insights enable <organization_id> --monthly 1 --report advanced                  # advanced engine (PDF + Studio config)
+flowiq insights enable <organization_id> --add-recipient kiah@flowapt.com               # edit recipients, keep the cadence
+flowiq insights enable <organization_id> --weekly friday --dry-run                      # show what would be written
+
+flowiq insights disable <organization_id>       # enabled=false; schedules + recipients kept
+
+flowiq insights run <organization_id> --period weekly --recipient matt@flowapt.com      # DRY RUN: engine, window, recipients, message count
+flowiq insights run <organization_id> --period weekly --recipient matt@flowapt.com --commit
+flowiq insights run <organization_id> --from 2026-09-01 --to 2026-09-07 --store-only --commit
+```
+
+- **`enable` composes the whole config** (`enabled` + `recipient_emails` +
+  `schedules[]`). Cadence flags (`--daily` / `--weekly [day]` / `--monthly [day]`)
+  REPLACE the schedules; none given keeps what exists, or applies the default
+  (weekly Monday, standard, emailed). `--report` and `--store-only` apply to the
+  cadence flags you pass. `--recipient` replaces the list; `--add-recipient` /
+  `--remove-recipient` edit it.
+- **It refuses the three ways an enabled org silently produces nothing**
+  (`--force` overrides): the org has **no OpenAI key** (both engines hard-require
+  `organizations.openai_api_key`); an emailing schedule with **no recipients**
+  (the engines would email a hardcoded fallback address); an **inactive** org.
+- **`status` shows schedules as the scheduler will actually run them.** An
+  enabled org with no schedules stored runs *daily standard* by default — it is
+  marked `(implicit)`; `enable` replaces that with an explicit schedule.
+- **`run` is a dry run by default** (it costs OpenAI tokens and can email a
+  client): it prints the engine, the window, who would get it and how many
+  customer messages are in the window, and refuses an empty window. `--commit`
+  fires it through python-render (fire-and-forget) and prints the job id; the
+  report shows under *Recent reports* in `status <org>` a few minutes later.
+- `--from` / `--to` are SAST calendar days. `--report` defaults to the org's
+  schedule for that period, else standard.
+- `enable` / `disable` / `run` are audited (`flowiq audit --endpoint insights`).
+
 ### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), render any single
@@ -1232,7 +1322,7 @@ Notes:
   org, which endpoint or query, how many records. **The response body is never
   stored**; the log records what was asked, not the customer data that came back.
 
-### Org — `flowiq org create` / `flowiq org info <organization_id>`
+### Org — `flowiq org create` / `flowiq org info <organization_id>` / `flowiq org flags …`
 
 Create a brand-new organization, or look one up (read-only; raw store/Meta
 credentials are stripped server-side).
@@ -1259,6 +1349,46 @@ flowiq prompts pull <new_org_id>   # edit → push
 (No `agent config` step any more — since 29 Aug 2026 a new agent is born on the
 house default: `gpt-5.6-luna`, `reasoning_effort high`, `use_settings_prompt` ON.)
 
+#### Feature flags — `flowiq org flags show|list|set|unset|keys` (v0.7.0)
+
+The Settings → Profile switches (`organizations.feature_flags`) from the
+terminal. `show` reads one org, `list --key` is the cross-org census, `set` /
+`unset` write. Only keys the Profile tab manages can be set (server-side
+allowlist + type check); anything that looks like a credential is redacted on
+read and refused on write.
+
+```bash
+flowiq org flags show <organization_id>                    # every flag, by Settings section
+flowiq org flags list --key export_insights.enabled --off   # which orgs do NOT have it (--on / --present / --absent / --all)
+flowiq org flags list --key mcp_member_access.enabled --on
+
+flowiq org flags set <organization_id> mcp_member_access.enabled true
+flowiq org flags set <organization_id> wait_for_more_messages 5            # integer, 0-60
+flowiq org flags set <organization_id> UTM.excluded_campaign_keywords "test,internal"   # string[] (comma list or JSON)
+flowiq org flags set <organization_id> integrations_visible.instagram true # wildcard keys take one more segment
+flowiq org flags set <organization_id> vert.active true --yes              # dangerous keys need --yes
+flowiq org flags set <organization_id> export_insights @insights.json      # JSON from a file (prefer `flowiq insights enable`)
+
+flowiq org flags unset <organization_id> wait_for_more_messages --yes      # remove the key (= platform default); always --yes
+flowiq org flags keys                                                      # what is settable, with type + danger notes
+flowiq org flags keys --section "members"
+```
+
+- **Values:** `true`/`false`, a whole number, JSON (`'["a","b"]'` / `'{"enabled":true}'`),
+  `@file.json`, or a comma list for list keys. The server validates against the
+  registry — a boolean given `12` is a 400, not a corrupted flag.
+- **Dangerous keys** (the Profile tab's amber-warning switches: `vert.active`,
+  `ip_whitelist`, `follow_up.enabled`, `subscriptions_test_mode`,
+  `api_key_member_access.enabled`, `export_insights`, `wait_for_more_messages`, …)
+  are refused without `--yes`, with the reason printed.
+- **Writes are atomic per path** (the same `_jsonb_deep_set` the Profile tab
+  uses), so `set a.b` never clobbers `a.c` that someone else just changed.
+- **Every set/unset is audited** (`flowiq audit --endpoint org-flags`) and the
+  response prints before → after plus the exact undo command.
+- A key that is on the org but not in the registry is shown by `show` (and
+  `--json`) but cannot be set here — it is DB-only by design; add it to the
+  Profile tab first.
+
 ### Agents — `flowiq agent list|create <org>`
 
 List an org's agents (to discover ids) and create a new one.

package/TEAM-GUIDE.md

@@ -108,6 +108,23 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 > from your working tree — `npm publish` packs whatever is on disk. A
 > `prepublishOnly` check now stops you if `cli/` differs from `origin/main`.
 
+### Keeping the CLI current
+
+Run **`flowiq doctor`** any time you are unsure — it checks your version against
+npm, your login, and whether the server still supports your install, and tells
+you the exact command to fix anything wrong.
+
+You will usually not need to: the CLI now tells you itself. If a newer version
+is out, or if your install is older than the server supports, every command
+prints a line starting `⬆ FLOWIQ CLI …` with the fix:
+
+```bash
+npm i -g @flowapt/flowiq-cli@latest
+```
+
+That warning is printed for AI assistants too, not just people — so if you work
+with Claude in this repo, it will see it and can update for you.
+
 ### Campaign naming — `Date_Campaign`
 
 Every campaign tag is **the date the broadcast goes out, then the campaign
@@ -163,6 +180,14 @@ several.
 | See a client's pending change requests | `flowiq au pull <org_id>` |
 | Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
 | Check an org's platform + active agent | `flowiq org info <org_id>` |
+| **See every Settings → Profile switch on an org** | `flowiq org flags show <org_id>` (credentials are never shown) |
+| **Which orgs have a flag on / off** (insights, MCP member access, a debounce…) | `flowiq org flags list --key export_insights.enabled --off` · `--key mcp_member_access.enabled --on` |
+| Flip a Settings → Profile switch from the terminal | `flowiq org flags set <org_id> mcp_member_access.enabled true` — `flowiq org flags keys` lists what you can set; the risky ones ask for `--yes`; the reply prints the undo |
+| Set the agent's message debounce ("customer sends 3 fragments, agent replies 3 times") | `flowiq org flags set <org_id> wait_for_more_messages 5` (seconds, 0-60) |
+| **Who is missing the Customer Insights report?** | `flowiq insights status --off --min-chats 20` — KEY `NO` means the org has no OpenAI key and the report cannot run |
+| Switch the insights report on for a client | `flowiq insights enable <org_id> --weekly monday --recipient client@example.com --recipient you@flowapt.com` — it refuses if there is no OpenAI key or nobody to email |
+| Store insights daily without emailing anyone (build history first) | `flowiq insights enable <org_id> --daily --store-only` |
+| Send one insights report right now | `flowiq insights run <org_id> --period weekly --recipient you@flowapt.com` (dry run) → add `--commit` |
 | Work a Pin Board task | `flowiq pin list-remote open` → `pull` → edit → `push` |
 | Log hours you worked for a client (every package = 10h Flowapt work/month) | `flowiq hours log <org_id> --hours 1.5 --desc "what you did"` — plain language, the client sees it on their Client Console |
 | Check a client's package hours / the month across all clients | `flowiq hours list <org_id>` / `flowiq hours summary` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "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": {

package/src/commands/doctor.js

@@ -0,0 +1,150 @@
+// `flowiq doctor` — one command that answers "is my CLI healthy and current?"
+//
+// Written because the honest answer used to need three commands and some
+// knowledge: `flowiq --version` (installed), `npm view` (latest), and nothing
+// at all for "does the SERVER still speak my dialect?". A teammate — or a
+// teammate's AI assistant — needs one place that says what is wrong and the
+// exact command to fix it.
+//
+// Read-only, no org needed, safe to run any time. Exit code 1 when something
+// actionable is wrong, so it can gate a script.
+
+import { http, serverContract, cliVersion } from "../http.js";
+import { cachedLatest, fetchLatestNow, cmpVersion } from "../update-check.js";
+import { loadConfig, configDir } from "../config.js";
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const amber = (s) => `\x1b[33m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const OK = green("✓");
+const WARN = amber("⚠");
+const BAD = red("✗");
+
+function ageLabel(ts) {
+  if (!ts) return "never";
+  const h = (Date.now() - ts) / 3600000;
+  if (h < 1) return `${Math.round(h * 60)} min ago`;
+  if (h < 48) return `${h.toFixed(1)} h ago`;
+  return `${Math.round(h / 24)} days ago`;
+}
+
+export async function doctor(opts = {}) {
+  const installed = cliVersion();
+  const problems = [];
+  const out = {
+    cli_version: installed,
+    npm_latest: null,
+    server_min_version: null,
+    api_build: null,
+    api_url: null,
+    authenticated: false,
+    user: null,
+    problems: [],
+  };
+
+  const lines = [];
+  lines.push(`flowiq doctor`);
+  lines.push("");
+
+  // ── 1. installed vs npm latest ────────────────────────────────────────────
+  // Ask the registry LIVE here (with a short timeout). The background cache is
+  // refreshed at most once a day, so on the day of a release it is stale — which
+  // is precisely when someone runs doctor.
+  const live = await fetchLatestNow(3000);
+  const cached = cachedLatest();
+  const latest = live || cached.latest;
+  out.npm_latest = latest;
+
+  if (!latest) {
+    lines.push(`  ${WARN} version    installed ${installed} · could not reach npm ${dim("(offline?)")}`);
+  } else if (cmpVersion(latest, installed) > 0) {
+    lines.push(`  ${BAD} version    installed ${installed} · latest ${latest}`);
+    problems.push({
+      what: `CLI is out of date (${installed} → ${latest})`,
+      fix: "npm i -g @flowapt/flowiq-cli@latest",
+    });
+  } else if (cmpVersion(installed, latest) > 0) {
+    // A dev machine, a worktree build, or a version bumped but not yet
+    // published. Saying "(latest)" here would be a lie, and it is exactly the
+    // state in which someone wonders why teammates do not have their feature.
+    lines.push(`  ${WARN} version    installed ${installed} is AHEAD of npm (${latest}) ${dim("— unpublished build")}`);
+  } else {
+    lines.push(`  ${OK} version    ${installed} ${dim(live ? "(latest)" : `(latest, cached ${ageLabel(cached.checkedAt)})`)}`);
+  }
+
+  // ── 2. config + auth ──────────────────────────────────────────────────────
+  let cfg = {};
+  try { cfg = await loadConfig(); } catch { /* handled below */ }
+  out.api_url = cfg.api_url || null;
+  lines.push(`  ${cfg.api_url ? OK : BAD} api        ${cfg.api_url || "not configured"} ${dim(configDir())}`);
+  if (!cfg.api_url) problems.push({ what: "no api_url configured", fix: "flowiq auth login" });
+
+  if (!cfg.token) {
+    lines.push(`  ${BAD} auth       not authenticated`);
+    problems.push({ what: "not authenticated", fix: "flowiq auth login" });
+  } else {
+    // whoami doubles as the live server probe — it is how the response headers
+    // carrying the version contract reach us at all.
+    try {
+      // `whoami` is also the live server probe: it is how the response headers
+      // carrying the version contract reach us at all.
+      const who = await http.get("whoami");
+      out.authenticated = true;
+      out.user = who?.user_email || null;
+      out.super_admin = who?.is_super_admin === true;
+      const role = who?.is_super_admin ? "super admin" : red("NOT a super admin");
+      lines.push(`  ${OK} auth       ${out.user || "authenticated"} ${dim(`· ${role}`)}`);
+      if (who && who.is_super_admin !== true) {
+        problems.push({ what: "this key is not a super-admin key — most commands will 403", fix: "ask Matt to re-issue the staff key" });
+      }
+    } catch (e) {
+      lines.push(`  ${BAD} auth       ${e.message.split("\n")[0]}`);
+      problems.push({
+        what: "the API rejected this key",
+        fix: e.status === 401 || e.status === 403 ? "flowiq auth login" : "check api_url / network, then retry",
+      });
+    }
+  }
+
+  // ── 3. the server's version contract ──────────────────────────────────────
+  out.server_min_version = serverContract.minVersion;
+  out.api_build = serverContract.apiBuild;
+
+  if (!serverContract.minVersion) {
+    lines.push(`  ${WARN} server     did not declare a minimum CLI version ${dim("(deploy predates the version contract)")}`);
+  } else if (cmpVersion(serverContract.minVersion, installed) > 0) {
+    lines.push(`  ${BAD} server     requires ${serverContract.minVersion}, you have ${installed}`);
+    problems.push({
+      what: `this CLI is older than the server's contract (needs ${serverContract.minVersion})`,
+      fix: "npm i -g @flowapt/flowiq-cli@latest",
+    });
+  } else {
+    lines.push(`  ${OK} server     contract ${serverContract.minVersion} or newer ${dim(`· build ${serverContract.apiBuild || "?"}`)}`);
+  }
+
+  // The REVERSE skew: a CLI newer than the deployment it is talking to. Not an
+  // error — it is the normal state for the minutes between a push and the
+  // Vercel deploy — but it explains "the command exists and still doesn't work".
+  if (latest && serverContract.minVersion && cmpVersion(installed, latest) === 0 && cmpVersion(installed, serverContract.minVersion) > 0) {
+    lines.push(`  ${dim("i  server     min is " + serverContract.minVersion + " while you run " + installed + " — fine; newest features need the matching deploy")}`);
+  }
+
+  out.problems = problems;
+  if (opts.json) { console.log(JSON.stringify(out, null, 2)); return problems.length ? 1 : 0; }
+
+  console.log(lines.join("\n"));
+  console.log("");
+  if (!problems.length) {
+    console.log(green("  Everything checks out."));
+  } else {
+    console.log(red(`  ${problems.length} thing${problems.length === 1 ? "" : "s"} to fix:`));
+    for (const p of problems) {
+      console.log(`    • ${p.what}`);
+      console.log(`      ${p.fix}`);
+    }
+  }
+  console.log("");
+  return problems.length ? 1 : 0;
+}

package/src/commands/insights.js

@@ -0,0 +1,201 @@
+// `flowiq insights …` — the Customer Insights Report from the terminal.
+//
+//   flowiq insights status [org_id] [--off|--on] [--min-chats N] [--all]   who has it, who does not, last report, chat volume
+//   flowiq insights enable <org_id> [--daily] [--weekly [day]] [--monthly [day]] [--report standard|advanced]
+//                                   [--store-only] [--recipient a@b.com …] [--dry-run] [--force]
+//   flowiq insights disable <org_id>
+//   flowiq insights run <org_id> [--period daily|weekly|monthly | --from D --to D] [--report …]
+//                                [--recipient …] [--store-only] --commit
+//
+// `run` is DRY-RUN by default (it prints the exact engine, window and
+// recipients) and fires only with --commit — it costs OpenAI tokens and can
+// email a client. The server refuses the three ways an enabled org silently
+// produces nothing (no OpenAI key, emailing with no recipients, an empty
+// window); --force overrides all but an inactive org.
+
+import { http } from "../http.js";
+import { schedulesFromOpts, describeSchedule, sastRange } from "../insights-config.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 pad = (s, n) => String(s ?? "").padEnd(n);
+const padL = (s, n) => String(s ?? "").padStart(n);
+
+function requireUuid(orgId) {
+  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);
+  }
+}
+
+function fmtWhen(iso) {
+  if (!iso) return "never";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  // SAST, minute precision
+  const s = new Date(d.getTime() + 2 * 3600 * 1000).toISOString();
+  return `${s.slice(0, 10)} ${s.slice(11, 16)}`;
+}
+
+function daysAgo(iso) {
+  if (!iso) return null;
+  return Math.floor((Date.now() - new Date(iso).getTime()) / 86400000);
+}
+
+function printProblems(body) {
+  for (const e of body.errors || []) console.error(`  ✗ ${e}`);
+  for (const w of body.warnings || []) console.error(`  ⚠ ${w}`);
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  const b = e.body || {};
+  if (b.errors?.length || b.warnings?.length) printProblems(b);
+  if (b.needs_force) console.error("  Fix the cause, or re-run with --force to write anyway.");
+  process.exit(1);
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+
+export async function status(orgId, opts = {}) {
+  if (orgId) return statusOne(orgId, opts);
+  let resp;
+  try { resp = await http.get("insights", { status: "1", all: opts.all ? "1" : undefined }); } catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  let orgs = resp.orgs || [];
+  const total = orgs.length;
+  const enabledTotal = orgs.filter((o) => o.enabled).length;
+  if (opts.on) orgs = orgs.filter((o) => o.enabled);
+  if (opts.off) orgs = orgs.filter((o) => !o.enabled);
+  const minChats = Number(opts.minChats ?? 0);
+  if (minChats > 0) orgs = orgs.filter((o) => o.contacts_30d >= minChats);
+  const sort = opts.sort || "chats";
+  orgs.sort((a, b) =>
+    sort === "name" ? a.name.localeCompare(b.name)
+    : sort === "last" ? (new Date(b.last_report?.at || 0) - new Date(a.last_report?.at || 0))
+    : (b.contacts_30d - a.contacts_30d) || a.name.localeCompare(b.name));
+
+  console.log(`Customer Insights Report — ${enabledTotal} of ${total} org(s) enabled${resp.include_inactive ? " (incl. inactive)" : ""}` +
+    `${opts.on ? " · showing ON" : opts.off ? " · showing OFF" : ""}${minChats ? ` · ≥${minChats} chatting contacts/30d` : ""}\n`);
+  if (!orgs.length) { console.log("(no orgs match the filter)"); return; }
+
+  const nameW = Math.min(28, Math.max(4, ...orgs.map((o) => o.name.length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("STATE", 5)}  ${padL("CHATS30D", 8)}  ${pad("KEY", 3)}  ${pad("LAST REPORT", 18)}  ${pad("RCPT", 4)}  SCHEDULES`);
+  for (const o of orgs) {
+    const state = o.enabled ? "ON" : o.configured ? "off" : "—";
+    const last = o.last_report ? `${fmtWhen(o.last_report.at)}${o.last_report.store_only ? " s" : ""}` : "never";
+    const sched = o.enabled ? o.schedules_described.join(", ") + (o.schedules_source === "implicit-daily" ? " (implicit)" : "") : "";
+    console.log(
+      `${pad(o.name.slice(0, nameW), nameW)}  ${pad(state, 5)}  ${padL(o.contacts_30d, 8)}  ${pad(o.has_openai_key ? "yes" : "NO", 3)}  ${pad(last, 18)}  ${padL(o.recipients.length, 4)}  ${sched}${o.inactive ? "  (inactive)" : ""}`
+    );
+  }
+  console.log(`\n${orgs.length} org(s) shown · CHATS30D = distinct contacts who messaged in the last 30 days · KEY = has its own OpenAI key (required) · "s" = store-only`);
+  console.log("Enable one:  flowiq insights enable <org_id> --weekly monday --recipient client@example.com");
+}
+
+async function statusOne(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.get("insights", { organization_id: orgId }); } catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  console.log(`${resp.name} (${resp.id})${resp.inactive ? "  [INACTIVE]" : ""}`);
+  console.log(`  insights:       ${resp.enabled ? "ENABLED" : resp.configured ? "disabled (config kept)" : "never configured"}`);
+  if (resp.enabled || resp.configured) {
+    console.log(`  schedules:      ${resp.schedules_described.join(", ") || "(none)"}${resp.schedules_source === "implicit-daily" ? "  ⚠ no schedules stored — the scheduler runs DAILY standard by default" : resp.schedules_source === "legacy" ? "  (legacy single-config shape)" : ""}`);
+    console.log(`  recipients:     ${resp.recipients.length ? resp.recipients.join(", ") : `(none — emails would go to ${resp.engine_fallback_email})`}`);
+  }
+  console.log(`  openai key:     ${resp.has_openai_key ? "own key present" : "NONE — the engines refuse to run"}${resp.has_spare_openai_key ? " (+ spare)" : ""}`);
+  console.log(`  studio config:  ${resp.studio_configured_at ? `saved ${fmtWhen(resp.studio_configured_at)} (advanced engine)` : "none (advanced runs on engine defaults)"}`);
+  console.log(`  chats (30d):    ${resp.contacts_30d} contacts · ${resp.messages_30d} messages · last inbound ${fmtWhen(resp.last_inbound_at)}`);
+  console.log(`  reports (30d):  ${resp.reports_30d}`);
+  if (resp.reports?.length) {
+    console.log("\n  Recent reports (SAST):");
+    for (const r of resp.reports) {
+      console.log(`    ${fmtWhen(r.at)}  ${pad(r.kind || "?", 8)} ${padL(r.contacts ?? "?", 5)} contacts ${padL(r.messages ?? "?", 6)} msgs  ` +
+        `${r.store_only ? "stored only" : `${r.emails_sent ?? 0} email(s)${r.emails_failed ? `, ${r.emails_failed} failed` : ""}`}` +
+        `${r.recipients?.length && !r.store_only ? ` → ${r.recipients.join(", ")}` : ""}${r.source && r.source !== "edge" ? `  [${r.source}]` : ""}`);
+    }
+  } else {
+    console.log("\n  No reports yet.");
+  }
+}
+
+// ── enable / disable ─────────────────────────────────────────────────────────
+
+export async function enable(orgId, opts = {}) {
+  requireUuid(orgId);
+  let schedules;
+  try { schedules = schedulesFromOpts({ daily: opts.daily, weekly: opts.weekly, monthly: opts.monthly, report: opts.report, storeOnly: opts.storeOnly }); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  if (!schedules && (opts.report || opts.storeOnly)) {
+    console.error("Error: --report / --store-only describe a schedule — add --daily, --weekly or --monthly to say which.");
+    process.exit(1);
+  }
+  const recipients = {};
+  if (opts.recipient?.length) recipients.replace = opts.recipient;
+  if (opts.addRecipient?.length) recipients.add = opts.addRecipient;
+  if (opts.removeRecipient?.length) recipients.remove = opts.removeRecipient;
+
+  const body = { organization_id: orgId, action: "enable", dry_run: opts.dryRun === true, force: opts.force === true };
+  if (schedules) body.schedules = schedules;
+  if (Object.keys(recipients).length) body.recipients = recipients;
+
+  let resp;
+  try { resp = await http.post("insights", body); } catch (e) { fail("Enable failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  const after = resp.after;
+  console.log(`${resp.dry_run ? "DRY RUN — " : ""}${o.name}: insights ${resp.before?.enabled ? "already on, config updated" : "ENABLED"}${resp.forced ? "  (FORCED past pre-flight)" : ""}`);
+  console.log(`  schedules:   ${(after.schedules || []).map(describeSchedule).join(", ")}  [${resp.schedules_source}]`);
+  console.log(`  recipients:  ${after.recipient_emails?.length ? after.recipient_emails.join(", ") : "(none)"}`);
+  printProblems(resp);
+  if (resp.dry_run) {
+    console.log(resp.would_write ? "\n  Would write. Re-run without --dry-run." : "\n  Would NOT write — fix the ✗ items (or --force).");
+  } else {
+    console.log("\n  Next run: 09:00 SAST on the next matching day (cron 72). Fire one now: flowiq insights run " + orgId + " --commit");
+    console.log("  Undo:     flowiq insights disable " + orgId);
+  }
+}
+
+export async function disable(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.post("insights", { organization_id: orgId, action: "disable" }); } catch (e) { fail("Disable failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name}: insights ${resp.changed ? "DISABLED" : "already disabled"} (schedules + recipients kept; re-enable with \`flowiq insights enable\`)`);
+}
+
+// ── run (Run Now) ────────────────────────────────────────────────────────────
+
+export async function run(orgId, opts = {}) {
+  requireUuid(orgId);
+  const body = { organization_id: orgId, action: "run", commit: opts.commit === true, force: opts.force === true, store_only: opts.storeOnly === true };
+  if (opts.from || opts.to) {
+    if (!opts.from || !opts.to) { console.error("Error: --from and --to go together (YYYY-MM-DD, SAST days)."); process.exit(1); }
+    try { const r = sastRange(opts.from, opts.to); body.start_date = r.start; body.end_date = r.end; }
+    catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  } else if (opts.period) {
+    if (!["daily", "weekly", "monthly"].includes(opts.period)) { console.error("Error: --period must be daily, weekly or monthly."); process.exit(1); }
+    body.period = opts.period;
+  }
+  if (opts.report) body.report_type = opts.report;
+  if (opts.recipient?.length) body.recipients = opts.recipient;
+
+  let resp;
+  try { resp = await http.post("insights", body); } catch (e) { fail("Run failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  console.log(`${resp.dry_run ? "DRY RUN — " : "STARTED — "}${o.name}: ${resp.period} ${resp.report_type} report via ${resp.engine}`);
+  console.log(`  window:      ${fmtWhen(resp.window.start)} → ${fmtWhen(resp.window.end)} SAST  (${resp.messages_in_window ?? "?"} customer messages)`);
+  console.log(`  delivery:    ${resp.store_only ? "store only — no emails" : `email → ${resp.recipients.join(", ")}`}`);
+  printProblems(resp);
+  if (resp.dry_run) {
+    console.log(resp.would_run ? "\n  Would run. Add --commit to fire it." : "\n  Would NOT run — fix the ✗ items (or --force).");
+  } else {
+    console.log(`\n  job ${resp.job_id || "?"} — python-render is working in the background (a few minutes for a large org).`);
+    console.log(`  Check:  flowiq insights status ${orgId}   (the report appears under "Recent reports")`);
+  }
+}

package/src/commands/org-flags.js

@@ -0,0 +1,151 @@
+// `flowiq org flags …` — an org's feature flags (the Settings → Profile
+// switches) from the terminal.
+//
+//   flowiq org flags show <org_id>                     what this org carries (secrets redacted)
+//   flowiq org flags list --key <path> [--all]         which orgs carry ONE flag, and its value
+//   flowiq org flags set <org_id> <key> <value> [--yes] write a registered key (type-checked server-side)
+//   flowiq org flags unset <org_id> <key> --yes         remove a key (revert to the platform default)
+//   flowiq org flags keys                               what is settable, by Settings section
+//
+// The server (api/cli/org-flags + _org-flags-registry) is the only validator:
+// only keys the Profile tab manages can be set, credentials are never shown
+// or written, dangerous keys need --yes.
+
+import { http } from "../http.js";
+import { parseFlagValue, fmtValue } from "../flag-values.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 pad = (s, n) => String(s ?? "").padEnd(n);
+
+function requireUuid(orgId) {
+  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);
+  }
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  const b = e.body || {};
+  if (b.needs_confirm) {
+    if (b.danger) console.error(`  ⚠ ${b.danger}`);
+    if (b.before !== undefined) console.error(`  current: ${fmtValue(b.before)}`);
+    if (b.would_set !== undefined) console.error(`  would set: ${fmtValue(b.would_set)}`);
+    console.error("  Re-run with --yes to confirm.");
+  } else if (b.settable === false) {
+    console.error("  `flowiq org flags keys` lists what can be set; `flowiq org flags show <org>` still READS it.");
+  }
+  process.exit(1);
+}
+
+export async function keys(opts = {}) {
+  let resp;
+  try { resp = await http.get("org-flags", { keys: "1" }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const rows = (resp.keys || []).filter((k) => !opts.section || k.section.toLowerCase().includes(opts.section.toLowerCase()));
+  const bySection = new Map();
+  for (const k of rows) {
+    if (!bySection.has(k.section)) bySection.set(k.section, []);
+    bySection.get(k.section).push(k);
+  }
+  console.log(`Settable feature flags (${rows.length}) — the Settings → Profile switches, by section.\n`);
+  for (const [section, list] of bySection) {
+    console.log(`${section}`);
+    for (const k of list) {
+      const type = k.type === "integer" && k.min !== undefined ? `integer ${k.min}-${k.max}` : k.type;
+      console.log(`  ${pad(k.key, 46)} ${pad(type, 14)}${k.danger ? " ⚠ needs --yes" : ""}`);
+      if (k.note) console.log(`  ${pad("", 46)} ${k.note}`);
+    }
+    console.log("");
+  }
+  console.log("Wildcards (`x.*`) take one more segment, e.g. integrations_visible.instagram.");
+  console.log("Anything else on an org is readable via `flowiq org flags show` but not settable here.");
+}
+
+export async function show(orgId, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try { resp = await http.get("org-flags", { organization_id: orgId }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  const o = resp.organization;
+  console.log(`${o.name} (${o.id})${o.inactive ? "  [INACTIVE]" : ""} — ${resp.key_count} top-level flag key(s)\n`);
+  const known = Object.entries(resp.known || {});
+  if (known.length) {
+    const bySection = new Map();
+    for (const [key, v] of known) {
+      if (!bySection.has(v.section)) bySection.set(v.section, []);
+      bySection.get(v.section).push([key, v.value]);
+    }
+    for (const [section, list] of bySection) {
+      console.log(section);
+      for (const [key, value] of list) console.log(`  ${pad(key, 46)} ${fmtValue(value, 70)}`);
+      console.log("");
+    }
+  } else {
+    console.log("(none of the registered flags are set on this org)\n");
+  }
+  if (resp.unknown_keys?.length) {
+    console.log(`Other keys on this org (readable with --json, not settable from the CLI): ${resp.unknown_keys.join(", ")}`);
+  }
+  if (resp.secret_keys?.length) {
+    console.log(`Credentials present (never shown): ${resp.secret_keys.join(", ")}`);
+  }
+  console.log("\nChange one:  flowiq org flags set <org_id> <key> <value>   (see `flowiq org flags keys`)");
+}
+
+export async function list(opts = {}) {
+  if (!opts.key) { console.error("Error: --key <path> is required (e.g. --key export_insights.enabled)."); process.exit(1); }
+  let resp;
+  try { resp = await http.get("org-flags", { list: "1", key: opts.key, all: opts.all ? "1" : undefined }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+
+  let rows = resp.rows || [];
+  if (opts.on) rows = rows.filter((r) => r.value === true);
+  if (opts.off) rows = rows.filter((r) => r.value !== true);
+  if (opts.present) rows = rows.filter((r) => r.present);
+  if (opts.absent) rows = rows.filter((r) => !r.present);
+
+  const s = resp.summary;
+  const label = resp.registered ? ""
+    : resp.registered_parent ? `  (sub-key of \`${resp.registered_parent}\` — set it through the parent${resp.registered_parent === "export_insights" ? ", or \`flowiq insights enable\`" : ""})`
+    : "  (not a registered key — read-only)";
+  console.log(`${resp.key}${label} across ${s.orgs} org(s)${resp.include_inactive ? " incl. inactive" : ""}: ` +
+    `${s.present} present · ${s.absent} absent` + (s.true || s.false ? ` · ${s.true} true · ${s.false} false` : "") + "\n");
+  if (!rows.length) { console.log("(no orgs match the filter)"); return; }
+  const nameW = Math.min(34, Math.max(4, ...rows.map((r) => (r.name || "").length)));
+  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  VALUE`);
+  for (const r of rows) {
+    console.log(`${pad((r.name || "").slice(0, nameW), nameW)}  ${pad(r.id, 36)}  ${r.present ? fmtValue(r.value, 60) : "(absent)"}${r.inactive ? "  (inactive)" : ""}`);
+  }
+  console.log(`\n${rows.length} org(s) shown`);
+}
+
+export async function set(orgId, key, value, opts = {}) {
+  requireUuid(orgId);
+  let parsed;
+  try { parsed = parseFlagValue(value); } catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "set", key, value: parsed, confirm: opts.yes === true });
+  } catch (e) { fail("Set failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — ${resp.key}`);
+  console.log(`  ${fmtValue(resp.before, 70)} → ${fmtValue(resp.after, 70)}${resp.changed ? "" : "   (no change)"}`);
+  if (resp.danger) console.log(`  ⚠ ${resp.danger}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags ${resp.before === null ? `unset ${orgId} ${resp.key} --yes` : `set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`}`);
+}
+
+export async function unset(orgId, key, opts = {}) {
+  requireUuid(orgId);
+  let resp;
+  try {
+    resp = await http.post("org-flags", { organization_id: orgId, action: "unset", key, confirm: opts.yes === true });
+  } catch (e) { fail("Unset failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization.name} — removed ${resp.key}`);
+  console.log(`  was: ${fmtValue(resp.before, 70)}`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  console.log(`  Undo: flowiq org flags set ${orgId} ${resp.key} '${JSON.stringify(resp.before)}'${resp.danger ? " --yes" : ""}`);
+}

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
@@ -291,7 +294,7 @@ export function run(argv) {
     .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")
@@ -309,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>")
@@ -783,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/);
+});

package/src/update-check.js

@@ -4,6 +4,14 @@
 // can never corrupt piped / --json output) when the installed version is older
 // than the latest published on npm.
 //
+// ⚠️ It used to be gated on `process.stderr.isTTY` as well, which meant it was
+// invisible to exactly the audience that most needs it: an AI assistant running
+// `flowiq` through a tool call gets a PIPE, not a TTY, so isTTY is undefined and
+// the hint never printed. Teammates' Claude sessions could therefore run a
+// months-old CLI forever without ever being told. Writing to stderr is already
+// the whole safety property (it cannot corrupt piped stdout or --json), so the
+// TTY gate bought nothing and cost everything. Removed 9 Sep 2026.
+//
 // The nudge is driven by a CACHED value read SYNCHRONOUSLY — zero network on the
 // hot path, so no command is ever slowed. The cache is refreshed at most once a
 // day by a DETACHED, unref'd child process, so even `flowiq --version` returns
@@ -88,16 +96,42 @@ async function refreshLatest(prevLatest) {
 
 // Print the nudge (from cache, synchronously) and, if the cache is stale, spawn
 // a detached child to refresh it for the NEXT run. Never throws, never blocks.
+/** The cached npm `latest` + when it was refreshed — used by `flowiq doctor`. */
+export function cachedLatest() {
+  const c = readCacheSync();
+  return { latest: c?.latest || null, checkedAt: c?.checked_at || null };
+}
+
+/** Ask npm for the latest version NOW (doctor only — never on the hot path). */
+export async function fetchLatestNow(timeoutMs = FETCH_TIMEOUT_MS) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(REGISTRY, { signal: ctrl.signal, headers: { Accept: "application/json" } });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (body?.version) await writeCache({ checked_at: Date.now(), latest: body.version });
+    return body?.version || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function maybeNotifyUpdate(currentVersion) {
   try {
     if (disabled()) return;
     const cache = readCacheSync();
     const latest = cache?.latest;
 
-    if (latest && process.stderr.isTTY && cmpVersion(latest, currentVersion) > 0) {
+    if (latest && cmpVersion(latest, currentVersion) > 0) {
+      // The marker line is deliberately stable and unambiguous: an assistant
+      // reading this in a tool result should update without needing to be asked.
       process.stderr.write(
-        `\n  ⬆ flowiq ${latest} is available (you're on ${currentVersion})\n` +
-        `    update:  npm i -g ${PKG}\n\n`
+        `\n  ⬆ FLOWIQ CLI OUT OF DATE — installed ${currentVersion}, latest ${latest}\n` +
+        `    Run this before continuing:  npm i -g ${PKG}@latest\n` +
+        `    (commands still work; newer ones may be missing or behave differently)\n\n`
       );
     }