@flowapt/flowiq-cli 0.3.6 → 0.3.8

package/README.md

@@ -88,6 +88,32 @@ Notes:
   single "Main" section from `settings.system_prompt` and returns
   `bootstrapped: true`. The CLI prints a heads-up before push.
 
+#### Prompt version history — `flowiq prompts history|restore` (v0.3.8)
+
+A push overwrites `prompt_sections` in place, so the previous prompt used to
+be gone for good. Since v0.3.8 every push **snapshots the prompt it replaced**
+into the audit log, making every past version retrievable.
+
+```bash
+flowiq prompts history <organization_id>          # every recorded push: when / who / size
+flowiq prompts restore <organization_id> <audit_id>          # DRY-RUN (writes a working copy)
+flowiq prompts restore <organization_id> <audit_id> --commit # make it live
+flowiq prompts restore <organization_id> <audit_id> --after --commit
+```
+
+- `history` lists each push as `<prior size> → <new size>` with the audit id
+  to feed `restore`. `--agent <id>` scopes to a non-active agent.
+- `restore` **defaults to the version the push REPLACED** (i.e. "undo this
+  push"). `--after` restores the version that push made live — use it to jump
+  back to a specific older prompt rather than undoing one step.
+- **Dry-run by default.** It always writes
+  `.flowiq/prompts/<org>-restore-<audit8>.json` so you can read or edit the
+  recovered version first; `--commit` pushes it.
+- A restore goes through the normal push path, so it gets the same validation
+  **and its own audit row** — a rollback is never an untracked edit.
+- History starts at the first push after v0.3.8 shipped. Versions overwritten
+  before that were never snapshotted and cannot be recovered.
+
 ### Questionnaires — `flowiq questionnaires pull|push <slug>` (alias `q`)
 
 Round-trips `agents.questionnaire` JSONB.
@@ -160,7 +186,7 @@ flowiq ct list
 - **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime — known: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
 
-### Broadcast — `flowiq broadcast map|preview|send|resume|status|list` (alias `bc`)
+### Broadcast — `flowiq broadcast map|preview|send|resume|status|retry|list` (alias `bc`)
 
 Send an **APPROVED** WhatsApp template to every row of a CSV, filling the
 template's variables **per row** from the CSV's own columns. The
@@ -198,7 +224,15 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   by its id — `read` / `delivered` / `sent` / `failed` (+ % reached) from
   `helpdesk_messages`. Built for the `--python` fire-and-forget engine (which
   returns a `broadcastId` but has no CLI status log), but works for any broadcast
-  id (dashboard sends included). `flowiq bc status <org> <broadcastId>`.
+  id (dashboard sends included). **`--failures` (v0.3.7)** additionally lists each
+  failed recipient + the Meta error reason (`error_code` / `error_title`) with a
+  by-reason rollup — makes a fire-and-forget send fully auditable.
+- **`retry <org> <broadcastId>` (v0.3.7)**: re-send a broadcast to **only its
+  failed recipients** — reconstructs the send from the `broadcasts` row (template +
+  params + header) and re-fires via the python engine, creating a NEW broadcast.
+  DRY-RUN by default (shows the failed count + reason breakdown); `--commit` fires.
+  Note: permanent failures (e.g. `131026` undeliverable, opt-outs) just fail again —
+  retry earns its keep on transient (throttle/throughput) failures. Capped at 500.
 - **Engine auto-routing (v0.3.6):** any `send --tag` of **more than 10** eligible
   recipients **always uses the python engine** (a `>2000` tag routes there too).
   Only a ≤10 send stays on the resumable per-row Node engine. `--python` forces
@@ -242,8 +276,12 @@ flowiq bc send <org_id> --tag july-promo-batch-01 --template fresh_drop_v1 \
 ```
 
 Values are shared across the tag (use `{{first_name}}` etc. for per-contact
-personalization — resolved server-side). Opted-out / archived / blocked
-contacts under the tag are excluded automatically. Tags with >2000 contacts
+personalization — resolved server-side). Supported per-contact tokens:
+`{{first_name}}` `{{full_name}}` `{{email}}` `{{phone_number}}`
+`{{whatsapp_id}}` `{{contact_id}}`, plus `{{attributes.<key>}}` for any
+top-level key of the contact's `attributes` JSON (missing / object-valued
+keys render as empty — both engines, since 21 Jul 2026). Opted-out /
+archived / blocked contacts under the tag are excluded automatically. Tags with >2000 contacts
 are refused — slice them with `flowiq segments` first.
 
 ### Segments — `flowiq segments plan|apply|list|untag` (alias `seg`)
@@ -378,6 +416,19 @@ flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from
   collapses to 1 at runtime — rejected).
 - `field:"attributes"` actions are warned (full jsonb replace; constant
   values only) but applied — this CLI is their only safe editing surface.
+- **Action types accepted** (all seven the runtime implements):
+  `send_message` · `update_contact_field` · `add_contact_tag` ·
+  `remove_contact_tag` · `set_agent` · `delay` · `combined`.
+  Per-type rules: tag actions need a non-empty `tags[]` (or a single `tag`
+  string) or the runtime writes no tag at all; `set_agent.agent_id` must be
+  an agent UUID, or `null`/`""` to CLEAR the contact's binding (warned, since
+  clearing is easy to do by accident); `delay.ms` is a number ≥ 0 and is
+  **clamped to 5000ms** at runtime (Meta's webhook ack window) — a larger
+  value is accepted with a warning that the extra wait never happens;
+  `combined.actions[]` sub-types are checked and warned, not blocked.
+  *(Before v0.3.9 only the first two + `combined` were accepted, so a
+  zero-edit pull→push failed for any org using tag / set_agent / delay
+  actions.)*
 - `action_config.link_preview: false` disables WhatsApp's link-preview card
   on that action's text send (absent/`true` = preview on, the default).
   Passed through verbatim; also toggleable per action in the dashboard.
@@ -398,6 +449,59 @@ flowiq m pull <contact_id> --count 25
 
 `--count` defaults to 25, max 200.
 
+### Audit log — `flowiq audit [org] | audit show <id>` (v0.3.8)
+
+**Who changed what, when — with the full before/after content.** Every
+mutating CLI action writes a `staff_cli_audit` row server-side: the staff user
++ key, the endpoint + action, the org / agent / target, the CLI version and
+IP, and the complete prior + new state of whatever it changed. It's what makes
+`prompts history` / `restore` possible, and it's the answer to "who pushed
+that?" and "what did this look like last week?".
+
+```bash
+flowiq audit <organization_id>                      # recent activity on an org
+flowiq audit                                        # across all orgs
+flowiq audit <org> --endpoint prompts --action push # one surface
+flowiq audit <org> --user matt --since 2026-07-01   # one person, one window
+flowiq audit <org> --status blocked                 # attempts that were REFUSED
+flowiq audit show <audit_id>                        # one entry in full
+flowiq audit show <audit_id> --content              # + the before/after payloads
+flowiq audit show <audit_id> --out entry.json       # dump the whole entry
+```
+
+Filters: `--endpoint --action --status --agent --target --user --since --until
+--limit` (default 50, max 200) `--json`.
+
+**What's captured, and how much:**
+
+| Surface | Action | Content stored |
+|---|---|---|
+| `prompts` / `questionnaires` / `fine-tuning` / `knowledge` / `custom-tools` / `keywords` / `flowmod` | push | **full before + after** |
+| `custom-tools` | enable / disable, **blocked** destructive push | full before + after |
+| `agent-config` | config | before + after snapshot + the changed keys |
+| `agents` / `org` / `meta-templates` | create | the created record / submitted request |
+| `messaging-webhooks` / `webhooks` | push, reconnect | full before + after |
+| `pinboard` | push | full prior row + the new one |
+| `agent-updates` | resolve | prior status + the client-facing note |
+| `broadcast` | **send (committed)**, retry | the exact payload sent + the resulting broadcastId |
+| `segments` | apply / untag | the batch tags + their contact ids |
+| `tag` | field/cohort/segment/attributes/messages/remove | the tag + the exact selector + counts (not per-contact) |
+| `contacts-upsert` | upsert | the upserted rows |
+| `agent-stress` | cleanup | the deleted test contacts |
+| `messages` / `export-chats` | read / export | **metadata only** — who read whose chat, never a second copy of it |
+
+Notes:
+- **Dry-runs are not audited** (they change nothing) — but a **blocked**
+  destructive push IS, with `status=blocked`.
+- Listings never include content, so they stay small over 95k-char prompts;
+  `audit show` fetches it.
+- Payloads over 2MB are stored truncated with a marker rather than dropped —
+  an oversized push is never failed by the audit layer.
+- An audit write can never break your action: it's best-effort and swallows
+  its own errors.
+- **Read-only, and there is no `audit delete`.** An audit log you can edit
+  isn't an audit log.
+
 ### Webhooks (Shopify/WooCommerce) — `flowiq webhooks pull|push|reconnect` (alias `wh`)
 
 Round-trips the **inbound** Shopify or WooCommerce platform webhooks (the

package/TEAM-GUIDE.md

@@ -77,7 +77,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit the text knowledge sources (get_more_answers playbooks) | `flowiq kn pull <org_id>` → edit `sources[]` → `flowiq kn push <slug>` |
 | Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
 | Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
-| Edit keyword auto-replies (incl. competition entry keywords) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug>` |
+| Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
@@ -90,10 +90,15 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
 | Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
-| Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` |
+| Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`) |
 | Send a broadcast whose template has an IMAGE header | Same as above — the image is automatic (the template's own header image). Override with `--header-media <public-image-url>` if needed. |
 | Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine). **Any tag send over 10 recipients uses python automatically.** |
 | Check how a broadcast is landing (read/delivered/sent/failed) | `flowiq bc status <org_id> <broadcastId>` (the `broadcastId` a `--python` send prints) |
+| See WHO failed on a broadcast + why (Meta error) | `flowiq bc status <org_id> <broadcastId> --failures` |
+| Re-send a broadcast to only the ones that failed | `flowiq bc retry <org_id> <broadcastId>` (dry-run) → `… --commit` |
+| **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |
+| **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
+| See exactly what a change looked like (before → after) | `flowiq audit show <audit_id> --content` (or `--out entry.json`) |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/audit.js

@@ -0,0 +1,170 @@
+// `flowiq audit` — read the staff-CLI audit trail.
+//
+// Every mutating CLI action writes a `staff_cli_audit` row server-side
+// (api/cli/_audit.js) carrying who / what / when / where PLUS the full
+// before+after content. This command is the read side:
+//
+//   flowiq audit <org>                       — recent activity on an org
+//   flowiq audit --endpoint prompts          — filter by surface
+//   flowiq audit --user matt --since 2026-07-01
+//   flowiq audit show <audit_id>             — one entry, full detail
+//   flowiq audit show <audit_id> --content   — + the before/after payloads
+//   flowiq audit show <audit_id> --out f.json — dump the entry to a file
+//
+// Read-only by design: there is no `audit delete`. An audit log you can edit
+// isn't an audit log.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.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;
+
+/** 2026-07-27 14:32 SAST — the log is read by humans in SAST. */
+export function fmtSast(iso) {
+  if (!iso) return "—";
+  try {
+    const d = new Date(iso);
+    const s = new Intl.DateTimeFormat("en-ZA", {
+      timeZone: "Africa/Johannesburg",
+      year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", hour12: false,
+    }).format(d);
+    // en-ZA gives "2026/07/27, 14:32"
+    return s.replace(/\//g, "-").replace(",", "");
+  } catch {
+    return iso;
+  }
+}
+
+function pad(s, n) {
+  const str = String(s ?? "");
+  return str.length >= n ? str.slice(0, n) : str + " ".repeat(n - str.length);
+}
+
+const STATUS_MARK = { ok: " ", blocked: "⛔", failed: "✗" };
+
+export async function list(orgId, opts = {}) {
+  if (orgId && !UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("audit", {
+      organization_id: orgId,
+      agent_id: opts.agent,
+      endpoint: opts.endpoint,
+      action: opts.action,
+      status: opts.status,
+      target_id: opts.target,
+      user: opts.user,
+      since: opts.since,
+      until: opts.until,
+      limit: opts.limit,
+    });
+  } catch (e) {
+    console.error(`Audit query failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const entries = resp.entries || [];
+  if (!entries.length) {
+    console.log("No audit entries match those filters.");
+    return;
+  }
+
+  console.log("");
+  console.log(`${entries.length} entr${entries.length === 1 ? "y" : "ies"} (newest first)`);
+  console.log("");
+  console.log(`  ${pad("WHEN (SAST)", 17)} ${pad("WHO", 24)} ${pad("WHAT", 26)} SUMMARY`);
+  console.log(`  ${"-".repeat(17)} ${"-".repeat(24)} ${"-".repeat(26)} ${"-".repeat(40)}`);
+  for (const e of entries) {
+    const who = (e.user_email || "—").replace(/@.*$/, "");
+    const what = `${e.endpoint} ${e.action}`;
+    const mark = STATUS_MARK[e.status] ?? " ";
+    console.log(`${mark} ${pad(fmtSast(e.created_at), 17)} ${pad(who, 24)} ${pad(what, 26)} ${e.summary ?? ""}`);
+    if (!orgId && e.organization_name) {
+      console.log(`  ${" ".repeat(17)} ${" ".repeat(24)} ${" ".repeat(26)} └ org: ${e.organization_name}`);
+    }
+  }
+  console.log("");
+  console.log(`  ids: ${entries.map((e) => e.id.slice(0, 8)).join(" ")}`);
+  console.log(`  detail: flowiq audit show <audit_id>   (full id, or the 8-char prefix won't work — copy from --json)`);
+  console.log("");
+}
+
+export async function show(auditId, opts = {}) {
+  if (!UUID_RE.test(auditId)) {
+    console.error(`Error: "${auditId}" is not a valid audit entry id (uuid).`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("audit", { id: auditId });
+  } catch (e) {
+    console.error(`Audit lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  const e = resp.entry;
+
+  if (opts.out) {
+    const outPath = path.resolve(opts.out);
+    await fs.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, JSON.stringify(e, null, 2) + "\n", "utf8");
+    console.log(`Wrote ${outPath}`);
+    return;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(e, null, 2));
+    return;
+  }
+
+  console.log("");
+  console.log(`  ${e.endpoint} ${e.action}${e.status !== "ok" ? `  [${e.status.toUpperCase()}]` : ""}`);
+  console.log(`  ${e.summary ?? ""}`);
+  console.log("");
+  console.log(`  when:    ${fmtSast(e.created_at)} SAST`);
+  console.log(`  who:     ${e.user_email ?? "—"}`);
+  if (e.organization_name || e.organization_id) {
+    console.log(`  org:     ${e.organization_name ?? "—"} (${e.organization_id ?? "—"})`);
+  }
+  if (e.agent_id) console.log(`  agent:   ${e.agent_name ?? "—"} (${e.agent_id})`);
+  if (e.target_id) console.log(`  target:  ${e.target_id}`);
+  if (e.cli_version) console.log(`  cli:     v${e.cli_version}`);
+  if (e.ip) console.log(`  ip:      ${e.ip}`);
+  if (e.error) console.log(`  error:   ${e.error}`);
+  console.log(`  id:      ${e.id}`);
+
+  if (e.metadata && Object.keys(e.metadata).length) {
+    console.log("");
+    console.log("  metadata:");
+    for (const line of JSON.stringify(e.metadata, null, 2).split("\n")) console.log(`    ${line}`);
+  }
+
+  const beforeChars = e.before_content ? JSON.stringify(e.before_content).length : 0;
+  const afterChars = e.after_content ? JSON.stringify(e.after_content).length : 0;
+  console.log("");
+  console.log(`  content: before ${beforeChars.toLocaleString()} chars · after ${afterChars.toLocaleString()} chars`);
+
+  if (opts.content) {
+    if (e.before_content) {
+      console.log("");
+      console.log("  ── BEFORE ──────────────────────────────────────────────");
+      console.log(JSON.stringify(e.before_content, null, 2));
+    }
+    if (e.after_content) {
+      console.log("");
+      console.log("  ── AFTER ───────────────────────────────────────────────");
+      console.log(JSON.stringify(e.after_content, null, 2));
+    }
+  } else if (beforeChars || afterChars) {
+    console.log(`  (use --content to print them, or --out <file>.json to dump the whole entry)`);
+  }
+  console.log("");
+}

package/src/commands/broadcast.js

@@ -962,7 +962,7 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
   if (!UUID_RE.test(broadcastId)) { console.error("Error: broadcast id must be a UUID (the broadcastId a --python send printed)."); process.exit(1); }
   let resp;
-  try { resp = await http.post("broadcast", { action: "status", organization_id: orgId, broadcast_id: broadcastId }); }
+  try { resp = await http.post("broadcast", { action: "status", organization_id: orgId, broadcast_id: broadcastId, include_failures: !!opts.failures }); }
   catch (e) { console.error(`Status failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
   const b = resp.broadcast, d = resp.delivery;
@@ -976,6 +976,47 @@ export async function status(orgId, broadcastId, opts = {}) {
   if (b.total_recipients) {
     console.log(`    ${((reached / b.total_recipients) * 100).toFixed(1)}% of ${b.total_recipients} recipients reached${d.linked < b.total_recipients ? "  (still sending?)" : ""}`);
   }
+  if (opts.failures && resp.failures) {
+    console.log("");
+    console.log(`  Failures by reason:`);
+    for (const [reason, n] of Object.entries(resp.failure_reasons || {}).sort((a, b2) => b2[1] - a[1])) console.log(`    ${String(n).padStart(5)} × ${reason}`);
+    const cap = opts.limit ? Number(opts.limit) : 40;
+    console.log("");
+    console.log(`  Failed recipients${resp.failures.length > cap ? ` (showing ${cap} of ${resp.failures.length}; --json for all)` : ` (${resp.failures.length})`}:`);
+    for (const f of resp.failures.slice(0, cap)) {
+      console.log(`    ${(f.number || "—").padEnd(14)} ${(f.name || "").slice(0, 22).padEnd(22)} ${f.error_code ?? "?"} ${f.error_title || ""}`);
+    }
+  }
+}
+
+/** Re-send a broadcast to ONLY its failed recipients (transient-failure recovery).
+ *  Reconstructs the send from the broadcasts row + re-fires via python. The dry-run
+ *  shows the failed count + reason breakdown; --commit creates a NEW broadcast. */
+export async function retry(orgId, broadcastId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(broadcastId)) { console.error("Error: broadcast id must be a UUID (the broadcastId to retry)."); process.exit(1); }
+  let dry;
+  try { dry = await http.post("broadcast", { action: "retry", organization_id: orgId, broadcast_id: broadcastId, dry_run: true }); }
+  catch (e) { console.error(`Retry check failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log(`Broadcast ${broadcastId} (${dry.broadcast?.template_name ?? "?"}) — ${dry.failed_count} failed recipient(s).`);
+  for (const [reason, n] of Object.entries(dry.failure_reasons || {}).sort((a, b) => b[1] - a[1])) console.log(`    ${String(n).padStart(5)} × ${reason}`);
+  if (!dry.failed_count) { console.log("Nothing to retry."); return; }
+  console.log("");
+  console.log("Note: permanent failures (131026 undeliverable / opt-outs) just fail again — retry helps transient (throttle/throughput) failures.");
+  if (!opts.commit) {
+    console.log(`DRY RUN — would re-send to ${dry.failed_count} failed recipient(s) via the python engine. Add --commit to retry.`);
+    return;
+  }
+  if (!opts.yes) {
+    const a = await ask(`Type "retry" to re-send to ${dry.failed_count} failed recipient(s): `);
+    if (a !== "retry") { console.log("Aborted — nothing re-sent."); process.exit(0); }
+  }
+  let out;
+  try { out = await http.post("broadcast", { action: "retry", organization_id: orgId, broadcast_id: broadcastId, dry_run: false }); }
+  catch (e) { console.error(`Retry failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log("");
+  console.log(`✅ ${out.message || `Retry fired for ${out.retried} recipient(s)`}${out.broadcastId ? `  ·  new broadcastId ${out.broadcastId}` : ""}`);
+  if (out.broadcastId) console.log(`   Watch it: flowiq bc status ${orgId} ${out.broadcastId} --failures`);
 }
 
 export async function list() {

package/src/commands/prompts.js

@@ -6,6 +6,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { http } from "../http.js";
+import { fmtSast } from "./audit.js";
 
 const PROMPTS_DIR = path.resolve(process.cwd(), ".flowiq", "prompts");
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -125,3 +126,175 @@ export async function push(identifier) {
   console.log(`  content:    ${resp.total_chars.toLocaleString()} chars`);
   console.log(`  prompt now: ${resp.system_prompt_chars.toLocaleString()} chars`);
 }
+
+// ---------------------------------------------------------------------------
+// history / restore — powered by the staff-CLI audit log (staff_cli_audit).
+// Every `prompts push` snapshots the prompt it replaced, so every past version
+// is retrievable even though the agents row itself only holds the latest.
+// ---------------------------------------------------------------------------
+
+/** `flowiq prompts history <org>` — every recorded push, newest first. */
+export async function history(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("audit", {
+      organization_id: orgId,
+      agent_id: opts.agent,
+      endpoint: "prompts",
+      action: "push",
+      limit: opts.limit,
+    });
+  } catch (e) {
+    console.error(`History lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const entries = resp.entries || [];
+  if (!entries.length) {
+    console.log("");
+    console.log("No prompt-push history recorded for this org yet.");
+    console.log("(History starts from the first push after the audit log shipped —");
+    console.log(" earlier versions were never snapshotted and can't be recovered.)");
+    console.log("");
+    return;
+  }
+
+  console.log("");
+  console.log(`Prompt history — ${entries[0].organization_name ?? orgId} (${entries.length} push${entries.length === 1 ? "" : "es"}, newest first)`);
+  console.log("");
+  for (const e of entries) {
+    const m = e.metadata || {};
+    const from = `${m.prior_sections ?? "?"} sec / ${(m.prior_total_chars ?? 0).toLocaleString()} chars`;
+    const to = `${m.sections ?? "?"} sec / ${(m.total_chars ?? 0).toLocaleString()} chars`;
+    console.log(`  ${fmtSast(e.created_at)} SAST  ${e.user_email ?? "—"}`);
+    console.log(`    ${from}  →  ${to}${e.agent_name ? `   [agent: ${e.agent_name}]` : ""}`);
+    console.log(`    ${e.id}`);
+    console.log("");
+  }
+  console.log("  Restore the prompt as it was BEFORE one of these pushes:");
+  console.log(`    flowiq prompts restore ${orgId} <id>`);
+  console.log("  …or re-install the version a push made live:");
+  console.log(`    flowiq prompts restore ${orgId} <id> --after`);
+  console.log("");
+}
+
+/**
+ * `flowiq prompts restore <org> <audit_id>` — re-push a past version.
+ *
+ * Default restores `before_content` ("undo this push"); `--after` restores the
+ * version that push made live. The restore itself goes through the ordinary
+ * /cli/prompts POST, so it gets the same validation AND its own audit row —
+ * a rollback is never an untracked edit.
+ */
+export async function restore(orgId, auditId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  if (!UUID_RE.test(auditId)) {
+    console.error(`Error: "${auditId}" is not a valid audit entry id (get one from \`flowiq prompts history\`).`);
+    process.exit(1);
+  }
+
+  let entry;
+  try {
+    entry = (await http.get("audit", { id: auditId })).entry;
+  } catch (e) {
+    console.error(`Audit lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (entry.endpoint !== "prompts") {
+    console.error(`Error: audit entry ${auditId} is a "${entry.endpoint} ${entry.action}", not a prompt push.`);
+    process.exit(1);
+  }
+  if (entry.organization_id !== orgId) {
+    console.error(`Error: that audit entry belongs to a different org (${entry.organization_name ?? entry.organization_id}).`);
+    process.exit(1);
+  }
+
+  const side = opts.after ? "after_content" : "before_content";
+  const label = opts.after ? "the version this push MADE LIVE" : "the version this push REPLACED";
+  const snapshot = entry[side];
+  const sections = snapshot?.prompt_sections;
+  if (!Array.isArray(sections) || sections.length === 0) {
+    console.error(`Error: that entry has no ${opts.after ? "after" : "before"} prompt to restore.`);
+    if (!opts.after) console.error("(If this was the very first recorded push, there was no prior version — try --after on an older entry.)");
+    process.exit(1);
+  }
+  if (snapshot._truncated) {
+    console.error("Error: that snapshot was truncated when stored (oversized payload) and can't be restored safely.");
+    process.exit(1);
+  }
+
+  const totalChars = sections.reduce((a, s) => a + (s.content?.length || 0), 0);
+  console.log("");
+  console.log(`Restoring ${label}:`);
+  console.log(`  from push:  ${fmtSast(entry.created_at)} SAST by ${entry.user_email ?? "—"}`);
+  console.log(`  org:        ${entry.organization_name ?? orgId}`);
+  console.log(`  agent:      ${entry.agent_name ?? "—"} (${entry.agent_id})`);
+  console.log(`  sections:   ${sections.length}`);
+  console.log(`  content:    ${totalChars.toLocaleString()} chars`);
+  console.log("");
+
+  // Always write the working copy — even on a dry run, so the restored version
+  // can be inspected/edited before it goes live.
+  await fs.mkdir(PROMPTS_DIR, { recursive: true });
+  const orgSlug = slugify(entry.organization_name, orgId);
+  const filePath = path.join(PROMPTS_DIR, `${orgSlug}-restore-${auditId.slice(0, 8)}.json`);
+  await fs.writeFile(
+    filePath,
+    JSON.stringify(
+      {
+        organization_id: orgId,
+        organization_name: entry.organization_name,
+        agent_id: entry.agent_id,
+        agent_name: entry.agent_name,
+        restored_from_audit_id: auditId,
+        restored_side: opts.after ? "after" : "before",
+        prompt_sections: sections,
+      },
+      null,
+      2
+    ) + "\n",
+    "utf8"
+  );
+  console.log(`  working copy: ${filePath}`);
+
+  if (!opts.commit) {
+    console.log("");
+    console.log("  DRY RUN — nothing was pushed. Re-run with --commit to make this live:");
+    console.log(`    flowiq prompts restore ${orgId} ${auditId}${opts.after ? " --after" : ""} --commit`);
+    console.log(`  …or edit the file above and \`flowiq prompts push ${path.basename(filePath, ".json")}\`.`);
+    console.log("");
+    return;
+  }
+
+  let resp;
+  try {
+    resp = await http.post("prompts", {
+      organization_id: orgId,
+      prompt_sections: sections,
+      agent_id: entry.agent_id,
+    });
+  } catch (e) {
+    console.error(`Restore push failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(`  ✓ Restored — ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`    sections:   ${resp.sections}`);
+  console.log(`    prompt now: ${resp.system_prompt_chars.toLocaleString()} chars`);
+  console.log(`    (this restore is itself recorded in the audit log)`);
+  console.log("");
+}

package/src/http.js

@@ -3,8 +3,20 @@
 //   - carry Authorization: Bearer <token>
 //   - parse JSON, surfacing { error, message } shape with a readable error.
 
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
 import { loadConfig } from "./config.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
+// surprising pushes).
+let CLI_VERSION = "unknown";
+try {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  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 */ }
+
 async function call(method, endpoint, { query, body } = {}) {
   const cfg = await loadConfig();
   if (!cfg.token) {
@@ -27,6 +39,7 @@ async function call(method, endpoint, { query, body } = {}) {
     headers: {
       Authorization: `Bearer ${cfg.token}`,
       Accept: "application/json",
+      "X-Flowiq-Cli-Version": CLI_VERSION,
     },
   };
   if (body !== undefined) {
@@ -36,8 +49,8 @@ async function call(method, endpoint, { query, body } = {}) {
 
   const resp = await fetch(url, init);
   const text = await resp.text();
-  let parsed;
-  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; }
+  let parsed, isJson = true;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { _raw: text }; isJson = false; }
   if (!resp.ok) {
     const err = new Error(
       parsed.message || parsed.error || `${method} ${endpoint} → HTTP ${resp.status}`
@@ -46,6 +59,28 @@ async function call(method, endpoint, { query, body } = {}) {
     err.body = parsed;
     throw err;
   }
+  // A 2xx that is not JSON is never a real API response — it is an HTML page
+  // (Vercel SSO / login / error page, or the SPA's index.html served for an
+  // endpoint that doesn't exist on that deployment). Returning it let callers
+  // "succeed" on garbage: a pull wrote `.flowiq/<topic>/undefined.json` with the
+  // HTML stuffed in `_raw`, masking an auth or deploy failure as a good pull.
+  if (!isJson) {
+    const ctype = resp.headers.get("content-type") || "none";
+    const looksHtml = /^\s*<(?:!doctype|html)\b/i.test(text);
+    const err = new Error(
+      `${method} ${endpoint} → HTTP ${resp.status} returned ${looksHtml ? "an HTML page" : "a non-JSON body"} ` +
+      `(content-type: ${ctype}), not an API response.\n` +
+      `  URL:     ${url}\n` +
+      `  Likely:  an SSO / login / error page at that host, a wrong api_url, or this endpoint ` +
+      `isn't deployed there.\n` +
+      `  Check:   flowiq auth whoami  ·  api_url in ~/.config/flowiq/auth.json\n` +
+      `  Body:    ${text.slice(0, 140).replace(/\s+/g, " ").trim()}…`
+    );
+    err.status = resp.status;
+    err.code = "ENONJSON";
+    err.body = parsed;
+    throw err;
+  }
   return parsed;
 }
 

package/src/index.js

@@ -29,6 +29,7 @@ import * as segmentsCmd from "./commands/segments.js";
 import * as tagCmd from "./commands/tag.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
+import * as auditCmd from "./commands/audit.js";
 import { maybeNotifyUpdate } from "./update-check.js";
 
 // Read version from package.json so it stays in sync with the published npm
@@ -67,6 +68,17 @@ export function run(argv) {
     .description("Fetch an agent's prompt_sections into a local JSON file (default: active agent)")
     .option("--agent <id>", "target a specific agent instead of the org's active one")
     .action((orgId, opts) => promptsCmd.pull(orgId, opts));
+  prompts.command("history <organization_id>")
+    .description("Every recorded prompt push (who / when / size) — the version list for `restore`")
+    .option("--agent <id>", "history for a specific (non-active) agent")
+    .option("--limit <n>", "max entries (default 50, max 200)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => promptsCmd.history(orgId, opts));
+  prompts.command("restore <organization_id> <audit_id>")
+    .description("Re-push a past prompt version from the audit log (DRY-RUN unless --commit)")
+    .option("--after", "restore the version that push MADE LIVE (default: the one it REPLACED)")
+    .option("--commit", "actually push it (default writes a working copy only)")
+    .action((orgId, auditId, opts) => promptsCmd.restore(orgId, auditId, opts));
   prompts.command("push <slug-or-path>")
     .description("Apply a local JSON file's prompt_sections back to the agent it was pulled from (regenerates system_prompt server-side)")
     .action((id) => promptsCmd.push(id));
@@ -261,6 +273,28 @@ export function run(argv) {
     .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
     .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
+  // audit (who did what, when — with the full before/after content)
+  const audit = program.command("audit")
+    .description("Staff-CLI audit trail: who changed what, when — with full before/after content")
+    .argument("[organization_id]", "scope to one org (omit for all orgs)")
+    .option("--endpoint <name>", "prompts | questionnaires | fine-tuning | knowledge | custom-tools | keywords | agent-config | broadcast | tag | …")
+    .option("--action <name>", "push | create | config | resolve | send | apply | read | …")
+    .option("--status <s>", "ok | blocked | failed")
+    .option("--agent <id>", "scope to one agent")
+    .option("--target <id>", "scope to one target (task id, tool name, tag, broadcast id)")
+    .option("--user <substr>", "filter by staff email (substring)")
+    .option("--since <date>", "YYYY-MM-DD or ISO")
+    .option("--until <date>", "YYYY-MM-DD or ISO")
+    .option("--limit <n>", "max entries (default 50, max 200)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => auditCmd.list(orgId, opts));
+  audit.command("show <audit_id>")
+    .description("One audit entry in full")
+    .option("--content", "also print the before/after payloads")
+    .option("--out <path>", "write the whole entry (incl. content) to a JSON file")
+    .option("--json", "raw JSON")
+    .action((auditId, opts) => auditCmd.show(auditId, opts));
+
   // export (full chat history → TXT, byte-identical to the in-app export)
   const exp = program.command("export").description("Export data to local files");
   exp.command("chats <organization_id>")
@@ -413,8 +447,15 @@ export function run(argv) {
     .action((orgId, opts) => broadcastCmd.resume(orgId, opts));
   broadcast.command("status <organization_id> <broadcast_id>")
     .description("Live delivery counts (read/delivered/sent/failed) for a broadcast by its broadcastId — e.g. from a --python fire-and-forget send")
+    .option("--failures", "also list each FAILED recipient + the Meta error reason (makes a python send auditable)")
+    .option("--limit <n>", "with --failures: how many failed rows to print", "40")
     .option("--json", "raw JSON")
     .action((orgId, broadcastId, opts) => broadcastCmd.status(orgId, broadcastId, opts));
+  broadcast.command("retry <organization_id> <broadcast_id>")
+    .description("Re-send a broadcast to ONLY its failed recipients (transient-failure recovery). DRY-RUN by default; --commit re-fires via python")
+    .option("--commit", "actually re-send (omit to see the failed count + reasons)")
+    .option("--yes", "skip the type-'retry' confirm gate")
+    .action((orgId, broadcastId, opts) => broadcastCmd.retry(orgId, broadcastId, opts));
   broadcast.command("list")
     .description("List local campaigns + sent counts")
     .action(() => broadcastCmd.list());