@flowapt/flowiq-cli 0.6.8 → 0.7.1

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,102 @@ 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`).
+
+### Team updates — `flowiq updates status|uncovered|draft|asset|preview|send` (v0.7.1)
+
+The **"what changed in FlowIQ" email to the Flowapt team** — every super admin
+gets it. An *issue* is a JSON file composed from `platform_changelog` rows:
+headline sections (a screenshot straight from the app, what it does, and a
+**For the team** note: how we use it, what to tell clients), an *Also shipped*
+list, and a *CLI and MCP* block. The renderer, the send (from
+flowiq@flowapt.com, reply-to Matt) and the record (`team_updates`, with the exact
+HTML that went out) live server-side in the `team-update-email` edge function.
+
+```bash
+flowiq updates status                                   # uncovered changelog rows · recent sends · recipients
+flowiq updates uncovered                                # the rows no issue has emailed yet
+flowiq updates draft                                    # → ./.flowiq/updates/<date>.json, a default issue to enrich
+flowiq updates draft --since 2026-09-07T22:00:00+02:00  # compose from a period instead of the last covered point
+flowiq updates asset ./api-keys-card.png                # host a screenshot, prints the https URL for image.url
+flowiq updates preview .flowiq/updates/2026-09-10.json --open   # render to .html exactly as emailed
+flowiq updates send .flowiq/updates/2026-09-10.json --test      # one copy to YOU; nothing marked covered
+flowiq updates send .flowiq/updates/2026-09-10.json --test --to kiah@flowapt.com
+flowiq updates send .flowiq/updates/2026-09-10.json --yes       # the real send, to every super admin
+```
+
+- **Issue shape** (`issue` key in the file): `subject`, `preheader`, `title`,
+  `intro`, `date_label`, `headlines[]`, `also[]`, `tools[]`, `closing`,
+  `changelog_ids[]`. A headline/tool section: `type` (feature | improvement |
+  fix | ui | agent | cli | infra | db | mcp — the chip is the app's own), `major`,
+  `title`, `what[]` (paragraphs), `team[]` (bullets), `image{url,alt,caption}`,
+  `terminal{command,output}`, `link{label,url}`, `org_name`, `version`. An
+  `also[]` item: `type`, `title`, `note`, `link`. Inline markup anywhere:
+  `**bold**`, `` `code` ``, `[label](https://…)`.
+- **`preview` and `send` lint the file first** (required fields, unknown types,
+  non-https images, em dashes) and stop with line-level help.
+- **`send` without `--test` needs `--yes`**: it emails the whole team AND moves
+  the covered-up-to mark, so those changelog rows will never be auto-digested.
+  `--test` sends to you (or `--to`) and marks nothing.
+- **The safety net:** pg_cron `team-update-email-daily` (08:30 SAST) emails a
+  default digest of any changelog row that has gone un-emailed for 20h+, so a
+  ship is never silently missed. The curated `send` is what stops it firing —
+  compose the issue the same day you ship.
+- **Who may do what:** everyone with a staff key can `status`, `uncovered`,
+  `draft`, `asset`, `preview` and `send --test` (a copy to yourself, nothing
+  marked covered). **The real send is Matt only** — any other key gets
+  `403 Only matt@flowapt.com may post the team update` and the attempt is
+  audited (`ALLOWED_SENDERS` in `api/cli/team-updates.js`).
+- Every link in the email opens the app's Changelog at that entry
+  (`app.flowiq.live/?changelog=1&entry=<id>`). `send` and `asset` are audited
+  (`flowiq audit --endpoint team-updates`).
+
 ### 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 +1370,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 +1397,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

@@ -103,11 +103,31 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
 | Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true`, then set the recipient list in Agents → Tool Library → Email Request to Team (no CLI path for the addresses yet) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
+| **Tell the team what shipped** (the FlowIQ team update email) | `flowiq updates draft` → enrich the JSON (screenshots via `flowiq updates asset`, a *For the team* note per headline) → `flowiq updates preview <file> --open` → `flowiq updates send <file> --test` → `flowiq updates send <file> --yes` |
+| Can I use `flowiq updates`? | Yes: `status`, `uncovered`, `draft`, `preview` and `send --test` (a copy to yourself) work for everyone. Only the real `send --yes` to the whole team is Matt's; anyone else gets a 403 there |
+| Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never
 > from your working tree — `npm publish` packs whatever is on disk. A
 > `prepublishOnly` check now stops you if `cli/` differs from `origin/main`.
 
+### 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 +183,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.1",
   "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")`);
+  }
+}