@flowapt/flowiq-cli 0.1.6 → 0.1.7

package/README.md

@@ -1,9 +1,11 @@
 # flowiq
 
 FlowIQ staff CLI. Round-trips agent prompts, questionnaires, fine-tuning,
-contact chats, platform webhooks, outbound messaging webhooks, and FlowMod
-master-group prompts through `https://api.flowiq.live/cli/*` so the Supabase
-service role never leaves the server.
+contact chats, platform webhooks, outbound messaging webhooks, FlowMod
+master-group prompts, Pin Board tasks, WhatsApp templates, agent-update
+requests, full chat exports, and live agent testing through
+`https://api.flowiq.live/cli/*` so the Supabase service role never leaves the
+server.
 
 ## Install
 
@@ -210,6 +212,106 @@ flowiq grp pull 120363408455897717@g.us --last 48h   # or pass the group JID
   View-once/disappearing messages and raw media bodies can't be read (captions
   and text come through); history before the instance joined a group may be gappy.
 
+### Pin Board tasks — `flowiq pinboard pull|push|list|list-remote` (alias `pin`)
+
+Round-trips a single internal Pin Board task (`flowapt_tasks` row).
+
+```bash
+flowiq pin list-remote open          # find the task id you want
+flowiq pin pull <task_id>            # → ./.flowiq/pinboard/<slug>.json
+flowiq pin push <slug>               # writes editable fields back, stamps updated_at
+```
+
+Editable fields: `name`, `description`, `status` (open / in_progress / done),
+`urgency` (low / normal / high / critical), `preferred_due_date` (YYYY-MM-DD or
+null), `organizations[]`, `media[]`, `messages[]`, `created_by`. Array columns
+are full-replace within the row.
+
+### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
+
+Read an org's live templates straight from Meta (read-only), and submit new
+ones through the `create-meta-template` edge function.
+
+```bash
+flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
+flowiq templates create <organization_id> --request-file req.json
+flowiq templates status <organization_id> --name booking   # poll approval
+```
+
+`req.json` holds `{ template_request, template_data?, media_header?, cards_media? }`.
+Media headers: pass `media_header.file_url` (a public URL) — the edge function
+uploads it to Meta server-side. Approval is async; re-`pull` for the
+authoritative Meta status.
+
+### Org info — `flowiq org info <organization_id>`
+
+Read-only platform detect + active-agent lookup for an org (raw store/Meta
+credentials are stripped server-side).
+
+```bash
+flowiq org info <organization_id>       # platform, storefront url, active agent
+```
+
+### Agent config — `flowiq agent config <organization_id> [flags]`
+
+Set an allowlisted set of the active agent's config fields (the prompt-builder
+"Step 5"). With no flags, prints the current config.
+
+```bash
+flowiq agent config <organization_id>                        # show current
+flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.4-mini \
+  --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
+```
+
+Settable: `settings.use_settings_prompt`, `settings.model`, agent `--rename`,
+the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
+`view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
+`shopify_products_web_chat`), and `discount.enabled`. Anything else is rejected;
+every change is reported before → after.
+
+### Agent updates — `flowiq agent-updates pull|list` (alias `au`)
+
+Read-only pull of an org's client-raised "change the agent" requests
+(`agent_updates`), each with the chat context around the triggering message +
+the linked contact. Attachments are downloaded locally.
+
+```bash
+flowiq au pull <organization_id>                       # pending, with context
+flowiq au pull <organization_id> --status all --titles "EFT, bank"
+flowiq au pull <organization_id> --before 20 --after 10 --no-files
+# → ./.flowiq/agent-updates/<slug>.json + files/<update-id>/<attachment>
+```
+
+### Chat export — `flowiq export chats <organization_id> [--out <path>]`
+
+Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"
+(keyset-paginated server-side so it can't time out on big orgs).
+
+```bash
+flowiq export chats <organization_id>                      # → ./.flowiq/exports/<slug>-chats.txt
+flowiq export chats <organization_id> --out ./phyto-chats.txt
+```
+
+### Agent testing — `flowiq test <subcommand>`
+
+Drive an org's **live** agent through the web/test channel and read the reply
+back — **never sends a real WhatsApp** (the web branch only inserts the reply).
+
+```bash
+flowiq test send <organization_id> "What are your bestsellers?" --clear
+flowiq test send <organization_id> "What is this?" --image https://…/photo.jpg
+flowiq test qa <organization_id>                     # bundled generic smoke pack
+flowiq test scenario <organization_id> ./pack.json   # your own pack (expect/expectNot)
+flowiq test clear <organization_id>
+# phase 2 — adversarial parallel stress:
+flowiq test stress <organization_id> ./stress.json --concurrency 6
+flowiq test extract <organization_id>                # rebuild transcripts for a judge
+flowiq test cleanup <organization_id> --confirm      # delete the stress contacts
+```
+
+`--agent <id>` targets a specific (non-active) agent. `test stress cleanup` is
+destructive and requires `--confirm`.
+
 ## Environment variable overrides
 
 | Var | Default | Use |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.6",
-  "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, FlowMod master-group prompts, webhooks, and more without ever touching service-role credentials.",
+  "version": "0.1.7",
+  "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": {
     "flowiq": "bin/flowiq.js"

package/src/commands/agent-config.js

@@ -0,0 +1,95 @@
+// `flowiq agent config <organization_id> [flags]` — the prompt-builder skill's
+// Step 5 as a staff-key call. Writes an allowlisted set of agent fields
+// (use_settings_prompt, model, tool flags, discount.enabled, rename) via
+// /cli/agent-config. With no write flags, prints the current config.
+
+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;
+
+function parseBool(v, label) {
+  if (v === true) return true; // bare presence of an optional flag
+  const s = String(v).toLowerCase();
+  if (s === "true" || s === "1" || s === "yes" || s === "on") return true;
+  if (s === "false" || s === "0" || s === "no" || s === "off") return false;
+  console.error(`Error: ${label} must be true or false (got "${v}").`);
+  process.exit(1);
+}
+
+// commander collector for repeatable --tool woo_order_build=true
+export function collectTool(val, acc) {
+  acc = acc || [];
+  acc.push(val);
+  return acc;
+}
+
+function printSnapshot(title, snap) {
+  console.log(`  ${title}:`);
+  for (const [k, v] of Object.entries(snap)) {
+    console.log(`    ${k.padEnd(30)} ${v === null ? "(unset)" : v}`);
+  }
+}
+
+export async function config(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+
+  const body = { organization_id: orgId };
+  const settings = {};
+  if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
+  if (opts.model !== undefined) settings.model = opts.model;
+  if (Object.keys(settings).length) body.settings = settings;
+  if (opts.rename !== undefined) body.name = opts.rename;
+  if (opts.discount !== undefined) body.discount_enabled = parseBool(opts.discount, "--discount");
+
+  if (opts.tool && opts.tool.length) {
+    const flags = {};
+    for (const pair of opts.tool) {
+      const eq = pair.indexOf("=");
+      if (eq < 0) {
+        console.error(`Error: --tool expects flag=bool (got "${pair}").`);
+        process.exit(1);
+      }
+      const key = pair.slice(0, eq).trim();
+      flags[key] = parseBool(pair.slice(eq + 1), `--tool ${key}`);
+    }
+    body.tool_flags = flags;
+  }
+
+  const hasWrite =
+    body.settings || body.name !== undefined || body.tool_flags || body.discount_enabled !== undefined;
+
+  // No write flags → just show current config.
+  if (!hasWrite) {
+    let resp;
+    try {
+      resp = await http.get("agent-config", { organization_id: orgId });
+    } catch (e) {
+      console.error(`Lookup failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log(`${resp.organization_name} → agent ${resp.agent_id}`);
+    printSnapshot("current", resp.current);
+    console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount to change)");
+    return;
+  }
+
+  let resp;
+  try {
+    resp = await http.post("agent-config", body);
+  } catch (e) {
+    console.error(`Config update failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Updated agent ${resp.agent_id} (${resp.organization_name})`);
+  console.log(`  changed: ${resp.changed.join(", ") || "(nothing)"}`);
+  for (const k of resp.changed) {
+    const b = resp.before?.[k];
+    const a = resp.after?.[k];
+    console.log(`    ${k.padEnd(30)} ${b === null || b === undefined ? "(unset)" : b} → ${a === null || a === undefined ? "(unset)" : a}`);
+  }
+}

package/src/commands/agent-test.js

@@ -0,0 +1,232 @@
+// `flowiq test <subcommand>` — drive an org's LIVE agent through the web/test
+// channel (never sends a real WhatsApp). The server (/cli/agent-test,
+// /cli/agent-stress) does one turn per request; this CLI loops turns, runs the
+// expect/expectNot checks client-side, and prints the transcript.
+//
+//   test resolve  <org_id> [--agent <id>]
+//   test send     <org_id> <message...> [--agent] [--clear] [--sender] [--image] [--timeout] [--json]
+//   test scenario <org_id> <file.json> [--agent] [--no-clear-between] [--json] [--sender] [--timeout]
+//   test qa       <org_id> [--agent] ...           (bundled generic smoke pack)
+//   test clear    <org_id> [--agent]
+//   test stress   <org_id> [pack.json] [--agent] [--concurrency 6] [--timeout] [--out] [--contact]
+//   test cleanup  <org_id> [--agent] --confirm     (deletes stress contacts)
+//   test extract  <org_id> [--out]                 (rebuild transcripts from DB)
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { http } from "../http.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const QA_PACK = path.resolve(__dirname, "..", "data", "scenarios.qa.json");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+}
+
+async function runTurn(orgId, { agent, message, image, clear, sender, timeout }) {
+  return http.post("agent-test", {
+    action: "send",
+    organization_id: orgId,
+    agent_id: agent,
+    message,
+    image_url: image,
+    clear: !!clear,
+    sender,
+    timeout_ms: timeout,
+  });
+}
+
+async function clearConv(orgId, agent) {
+  return http.post("agent-test", { action: "clear", organization_id: orgId, agent_id: agent });
+}
+
+function checkExpectations(turn, replyText) {
+  const results = [];
+  const hay = (replyText || "").toLowerCase();
+  for (const e of turn.expect || []) results.push({ kind: "expect", needle: e, ok: hay.includes(String(e).toLowerCase()) });
+  for (const e of turn.expectNot || []) results.push({ kind: "expectNot", needle: e, ok: !hay.includes(String(e).toLowerCase()) });
+  return results;
+}
+
+function printTurn(sc, t, userText, r, checks) {
+  if (t === 0) console.log(`\n━━ ${sc.tq ? sc.tq + " · " : ""}${sc.title || sc.id} ━━`);
+  console.log(`\n  🧑 ${userText}`);
+  if (r.tool_calls?.length) console.log(`  ⚙  tools: ${r.tool_calls.join(", ")}`);
+  if (r.reply) console.log(`  🤖 ${r.reply.split("\n").join("\n     ")}`);
+  else console.log(`  ⚠  no reply — status=${r.status}${r.raw?.error ? " (" + r.raw.error + ")" : ""}`);
+  for (const c of checks || []) {
+    console.log(`     ${c.ok ? "✅" : "❌"} ${c.kind === "expectNot" ? "must NOT contain" : "contains"} "${c.needle}"`);
+  }
+}
+
+export async function resolve(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("agent-test", { organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Resolve failed: ${e.message}`); process.exit(1); }
+  console.log(JSON.stringify(resp, null, 2));
+}
+
+export async function send(orgId, messageParts, opts = {}) {
+  requireOrg(orgId);
+  const message = (messageParts || []).join(" ");
+  if (!message) { console.error("usage: test send <org_id> <message...>"); process.exit(1); }
+  let r;
+  try {
+    r = await runTurn(orgId, { agent: opts.agent, message, image: opts.image, clear: opts.clear, sender: opts.sender, timeout: opts.timeout });
+  } catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`# org=${r.org?.name} agent=${r.agent?.name}${r.agent?.is_active ? " (active)" : " (override)"} contact=${r.contact?.id}`);
+  printTurn({ title: "send", tq: "" }, 0, message, r, []);
+}
+
+async function runPack(orgId, pack, opts) {
+  const scenarios = pack.scenarios || pack;
+  const clearBetween = !opts.noClearBetween;
+  console.log(`# ${pack.name || "pack"} — ${scenarios.length} scenarios · org ${orgId}`);
+  const results = [];
+  for (let s = 0; s < scenarios.length; s++) {
+    const sc = scenarios[s];
+    if (clearBetween) {
+      try { await clearConv(orgId, opts.agent); } catch (e) { console.error(`  (clear failed: ${e.message})`); }
+    }
+    const scResult = { id: sc.id, tq: sc.tq, title: sc.title, turns: [] };
+    for (let t = 0; t < sc.turns.length; t++) {
+      const turn = sc.turns[t];
+      let r;
+      try {
+        r = await runTurn(orgId, { agent: opts.agent, message: turn.text, sender: opts.sender, timeout: opts.timeout });
+      } catch (e) {
+        r = { status: "error", reply: null, tool_calls: [], raw: { error: e.message } };
+      }
+      const checks = checkExpectations(turn, r.reply);
+      scResult.turns.push({ ...r, checks });
+      if (!opts.json) printTurn(sc, t, turn.text, r, checks);
+    }
+    results.push(scResult);
+  }
+  let pass = 0, fail = 0;
+  for (const sc of results) for (const t of sc.turns) for (const c of t.checks || []) (c.ok ? pass++ : fail++);
+  if (opts.json) console.log(JSON.stringify(results, null, 2));
+  else console.log(`\n━━ assertions: ${pass} passed, ${fail} failed ━━`);
+}
+
+export async function scenario(orgId, file, opts = {}) {
+  requireOrg(orgId);
+  const filePath = path.isAbsolute(file) ? file : path.resolve(process.cwd(), file);
+  let pack;
+  try { pack = JSON.parse(await fs.readFile(filePath, "utf8")); }
+  catch (e) { console.error(`Cannot read scenario file ${filePath}: ${e.message}`); process.exit(1); }
+  await runPack(orgId, pack, opts);
+}
+
+export async function qa(orgId, opts = {}) {
+  requireOrg(orgId);
+  const pack = JSON.parse(await fs.readFile(QA_PACK, "utf8"));
+  await runPack(orgId, pack, opts);
+}
+
+export async function clear(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await clearConv(orgId, opts.agent); }
+  catch (e) { console.error(`Clear failed: ${e.message}`); process.exit(1); }
+  console.log(`Cleared web conversation for contact ${resp.contact_id} (history hidden via memory_cutoff; onboarding/disclaimer state NOT reset).`);
+}
+
+// ---------- phase 2: stress + extract ----------
+
+async function pool(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function lane() {
+    while (next < items.length) {
+      const i = next++;
+      try { results[i] = await worker(items[i], i); }
+      catch (e) { results[i] = { id: items[i].id, error: String(e?.message || e) }; }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+  return results;
+}
+
+export async function stress(orgId, file, opts = {}) {
+  requireOrg(orgId);
+  const packFile = file || "scenarios.stress.json";
+  const filePath = path.isAbsolute(packFile) ? packFile : path.resolve(process.cwd(), packFile);
+  let pack;
+  try { pack = JSON.parse(await fs.readFile(filePath, "utf8")); }
+  catch (e) { console.error(`Cannot read stress pack ${filePath}: ${e.message}`); process.exit(1); }
+  const scenarios = pack.scenarios || pack;
+
+  let head;
+  try { head = await http.get("agent-stress", { organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Resolve failed: ${e.message}`); process.exit(1); }
+
+  const fixedContact = opts.contact || null;
+  const concurrency = fixedContact ? 1 : (opts.concurrency ? Number.parseInt(opts.concurrency, 10) : 6);
+  const timeout = opts.timeout;
+  const t0 = Date.now();
+  console.error(`# ${pack.name || packFile}: ${scenarios.length} scenarios · org=${head.org.name} agent=${head.agent.name} · concurrency=${concurrency}`);
+
+  let done = 0;
+  const results = await pool(scenarios, concurrency, async (sc) => {
+    let contactId = fixedContact;
+    if (!contactId) {
+      const ec = await http.post("agent-stress", { action: "ensure_contact", organization_id: orgId, agent_id: opts.agent, scenario_id: sc.id, fresh: !!sc.fresh });
+      contactId = ec.contact_id;
+    }
+    const turns = [];
+    for (let i = 0; i < sc.turns.length; i++) {
+      const r = await http.post("agent-stress", {
+        action: "turn", organization_id: orgId, agent_id: opts.agent, contact_id: contactId,
+        text: sc.turns[i].text, sender: "Stress Tester", idx: `${sc.id}_${i}`, timeout_ms: timeout, reenable_bot: !!fixedContact,
+      });
+      turns.push(r);
+    }
+    const rec = { id: sc.id, category: sc.category, severity: sc.severity || "medium", tq: sc.tq || null, title: sc.title, criteria: sc.criteria, fresh: !!sc.fresh, contactId, turns };
+    done++;
+    const last = rec.turns[rec.turns.length - 1];
+    const snippet = last?.reply ? last.reply.replace(/\s+/g, " ").slice(0, 70) : `⚠ ${last?.status}`;
+    console.error(`  [${done}/${scenarios.length}] ${String(rec.severity).toUpperCase().padEnd(8)} ${String(rec.id).padEnd(22)} ${snippet}`);
+    return rec;
+  });
+
+  const outPath = opts.out ? path.resolve(opts.out) : path.resolve(process.cwd(), ".flowiq", "agent-test", "stress-results.json");
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  const payload = {
+    org: head.org, agent: head.agent, ran_at: new Date().toISOString(),
+    duration_ms: Date.now() - t0, scenario_count: scenarios.length, results,
+  };
+  await fs.writeFile(outPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  const noReply = results.filter((r) => r.turns?.some((t) => !t.reply)).length;
+  console.error(`\n# done in ${Math.round((Date.now() - t0) / 1000)}s · ${results.length} scenarios · ${noReply} with a no-reply turn · → ${outPath}`);
+}
+
+export async function cleanup(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (!opts.confirm) {
+    console.error("Refusing to delete stress contacts without --confirm (this DELETEs contacts + their messages/sessions).");
+    process.exit(1);
+  }
+  let resp;
+  try { resp = await http.post("agent-stress", { action: "cleanup", organization_id: orgId, agent_id: opts.agent, confirm: true }); }
+  catch (e) { console.error(`Cleanup failed: ${e.message}`); process.exit(1); }
+  console.error(`Cleaned up ${resp.deleted} stress contact${resp.deleted === 1 ? "" : "s"} + their messages/sessions.`);
+}
+
+export async function extract(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("agent-stress", { action: "extract", organization_id: orgId, agent_id: opts.agent }); }
+  catch (e) { console.error(`Extract failed: ${e.message}`); process.exit(1); }
+  const outPath = opts.out ? path.resolve(opts.out) : path.resolve(process.cwd(), ".flowiq", "agent-test", "judge_input.json");
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  await fs.writeFile(outPath, JSON.stringify(resp.scenarios, null, 2) + "\n", "utf8");
+  console.log(`Wrote ${outPath} — ${resp.scenarios.length} scenario transcript${resp.scenarios.length === 1 ? "" : "s"}.`);
+}

package/src/commands/agent-updates.js

@@ -0,0 +1,186 @@
+// `flowiq agent-updates pull <org_id> [flags]` / `list`.
+// Read-only: fetches an org's agent_updates + chat context via /cli/agent-updates,
+// then downloads any attachments client-side into ./.flowiq/agent-updates/files/.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const AU_DIR = path.resolve(process.cwd(), ".flowiq", "agent-updates");
+const FILES_DIRNAME = "files";
+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 DEFAULT_MAX_MB = 25;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+function oneLine(s, n = 120) {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// Filesystem-safe filename (strip path, control chars, separators).
+function safeFilename(name, fallback) {
+  const base = String(name || "").split("?")[0].split(/[\\/]/).pop().trim();
+  const cleaned = base.replace(/[\x00-\x1f]/g, "").replace(/[\\/]/g, "_");
+  return cleaned || fallback;
+}
+
+// Download one URL to destPath, respecting a byte cap. Never throws.
+async function downloadOne(url, destPath, maxBytes) {
+  let res;
+  try { res = await fetch(url); }
+  catch (e) { return { ok: false, reason: `fetch error: ${e.message}` }; }
+  if (!res.ok) return { ok: false, reason: `http ${res.status}` };
+  const len = Number(res.headers.get("content-length") || 0);
+  if (len && len > maxBytes) return { ok: false, reason: `too large (${len} bytes > cap)` };
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length > maxBytes) return { ok: false, reason: `too large (${buf.length} bytes > cap)` };
+  await fs.mkdir(path.dirname(destPath), { recursive: true });
+  await fs.writeFile(destPath, buf);
+  return { ok: true, bytes: buf.length };
+}
+
+async function downloadUpdateFiles(update, maxBytes) {
+  const baseDir = path.join(AU_DIR, FILES_DIRNAME, update.id);
+  const atts = Array.isArray(update.attachments) ? update.attachments : [];
+  for (let i = 0; i < atts.length; i++) {
+    const a = atts[i];
+    if (!a || !a.url) continue;
+    const fname = safeFilename(a.filename, `attachment-${i + 1}`);
+    if (a.size && a.size > maxBytes) {
+      a.download = { ok: false, reason: `declared size ${a.size} bytes > cap` };
+      continue;
+    }
+    const r = await downloadOne(a.url, path.join(baseDir, fname), maxBytes);
+    a.download = r;
+    if (r.ok) a.local_path = path.join(baseDir, fname);
+  }
+  if (update.superadmin_response_image) {
+    const fname = "admin-" + safeFilename(update.superadmin_response_image, "response-image");
+    const r = await downloadOne(update.superadmin_response_image, path.join(baseDir, fname), maxBytes);
+    update.superadmin_response_image_download = r;
+    if (r.ok) update.superadmin_response_image_local = path.join(baseDir, fname);
+  }
+}
+
+export async function pull(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+
+  const downloadFiles = !opts.noFiles;
+  const maxMb = opts.maxMb != null ? Number.parseFloat(opts.maxMb) : DEFAULT_MAX_MB;
+  if (!Number.isFinite(maxMb) || maxMb <= 0) {
+    console.error(`Invalid --max-mb: ${opts.maxMb}`);
+    process.exit(1);
+  }
+  const maxBytes = Math.round(maxMb * 1024 * 1024);
+
+  const query = { organization_id: orgId };
+  if (opts.status) query.status = opts.status;
+  if (opts.titles) query.titles = opts.titles;
+  if (opts.before != null) query.before = String(opts.before);
+  if (opts.after != null) query.after = String(opts.after);
+  if (opts.recent != null) query.recent = String(opts.recent);
+
+  let resp;
+  try {
+    resp = await http.get("agent-updates", query);
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Download attachments client-side (mutates the update objects with local_path).
+  if (downloadFiles) {
+    for (const u of resp.updates || []) {
+      try { await downloadUpdateFiles(u, maxBytes); }
+      catch (e) { u._file_download_error = e.message; }
+    }
+  }
+  resp.attachments_downloaded = downloadFiles;
+  resp.attachment_max_mb = maxMb;
+
+  await fs.mkdir(AU_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(AU_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const updates = resp.updates || [];
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:            ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  status filter:  ${resp.status_filter}`);
+  console.log(`  title filter:   ${resp.title_filter ? resp.title_filter.join(" | ") : "(none — all)"}`);
+  console.log(`  attachments:    ${downloadFiles ? `auto-download ON (cap ${maxMb}MB)` : "OFF (--no-files)"}`);
+  console.log(`  updates:        ${updates.length}`);
+  if (!updates.length) {
+    console.log("  (no matching updates)");
+    return;
+  }
+  console.log("");
+  updates.forEach((u, i) => {
+    const date = String(u.created_at || "").slice(0, 16).replace("T", " ");
+    console.log(`  [${i + 1}] ${u.title}`);
+    console.log(`      priority=${u.priority}  status=${u.status}  raised=${date}${u.created_by_name ? ` by ${u.created_by_name}` : ""}`);
+    console.log(`      desc: ${oneLine(u.description, 140)}`);
+    if (u.contact) console.log(`      contact: ${u.contact.full_name ?? "(no name)"} (${u.contact.whatsapp_id ?? u.contact.id})`);
+    if (u.attachments && u.attachments.length) {
+      console.log(`      attachments: ${u.attachments.length} (${u.attachments.map((a) => a.filename || a.type || "file").join(", ")})`);
+      for (const a of u.attachments) {
+        if (a.local_path) console.log(`        ↓ ${a.local_path}`);
+        else if (a.download && !a.download.ok) console.log(`        ✗ ${a.filename || "file"}: ${a.download.reason}`);
+      }
+    }
+    if (u.superadmin_response_image_local) console.log(`      admin response image: ↓ ${u.superadmin_response_image_local}`);
+    if (u.context && u.context.messages && u.context.messages.length) {
+      const trig = u.context.messages.find((m) => m.is_trigger);
+      console.log(`      context: ${u.context.total} msgs (anchor=${u.context.anchor})${trig ? ` · trigger: "${oneLine(trig.message, 80)}"` : ""}`);
+    } else {
+      console.log(`      context: (none linked)`);
+    }
+    console.log("");
+  });
+  console.log("Read the JSON for full update text + chat context. Attachments (paths marked ↓) were downloaded to");
+  console.log(`${path.join(AU_DIR, FILES_DIRNAME)}/<update-id>/ — Read those files for visual context, then act.`);
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(AU_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local snapshots — run `agent-updates pull <organization_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local snapshots — run `agent-updates pull <organization_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(AU_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  org:        ${d.organization_name ?? "(unknown)"} (${d.organization_id ?? "?"})`);
+      console.log(`  filter:     status=${d.status_filter ?? "?"} title=${d.title_filter ? d.title_filter.join("|") : "(all)"}`);
+      console.log(`  updates:    ${d.total_updates ?? "?"}`);
+      console.log(`  pulled:     ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/commands/export.js

@@ -0,0 +1,131 @@
+// `flowiq export chats <organization_id> [--out <path>]`.
+// Full chat export → TXT, byte-identical to the in-app "Export Settings TXT".
+// The server (/cli/export-chats) supplies keyset pages (ordered, whatsapp_id
+// resolved); ALL grouping + formatting happens here, verbatim from the legacy
+// export-chats.mjs, so the output matches the deployed feature exactly.
+
+import fs from "node:fs";
+import fsp 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;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+// Verbatim from export-chats.mjs.
+function getSenderLabel(senderType) {
+  if (senderType.startsWith("user-")) return "customer";
+  if (senderType.startsWith("bot-")) return "bot";
+  if (senderType.startsWith("human-")) return "agent";
+  if (senderType.startsWith("flowmod-")) return "flowmod";
+  if (senderType.startsWith("call-")) return "call";
+  if (senderType === "tool-call") return "tool";
+  return senderType;
+}
+
+export async function chats(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+
+  const t0 = Date.now();
+
+  // --- Drive the keyset page loop, accumulating messages in global order ---
+  const messages = [];
+  let organizationName = null;
+  let cursor = null;
+  let pages = 0;
+  for (;;) {
+    const query = { organization_id: orgId };
+    if (cursor) {
+      query.cursor_created_at = cursor.created_at;
+      query.cursor_id = cursor.id;
+    }
+    let resp;
+    try {
+      resp = await http.get("export-chats", query);
+    } catch (e) {
+      console.error(`Export failed on page ${pages + 1}: ${e.message}`);
+      process.exit(1);
+    }
+    if (resp.organization_name != null) organizationName = resp.organization_name;
+    const page = resp.page || [];
+    for (const r of page) messages.push(r);
+    pages++;
+    if (pages % 20 === 0) {
+      console.log(`  ...${messages.length.toLocaleString("en-US")} messages (${pages} pages)`);
+    }
+    if (resp.done || !resp.next_cursor) break;
+    cursor = resp.next_cursor;
+  }
+  console.log(`Messages fetched: ${messages.length} in ${pages} page${pages === 1 ? "" : "s"}`);
+
+  // --- Group exactly like the deployed exportTXT: plain object, waId key ---
+  const grouped = {};
+  for (const row of messages) {
+    const whatsappId = row.whatsapp_id ?? null;
+    const waId = (whatsappId || "unknown").replace(/[+ ]/g, "");
+    if (!grouped[waId]) grouped[waId] = [];
+    grouped[waId].push(row);
+  }
+  const uniqueContacts = Object.keys(grouped).length;
+
+  // --- Resolve output path ---
+  let outPath = opts.out;
+  if (!outPath) {
+    const dir = path.resolve(process.cwd(), ".flowiq", "exports");
+    await fsp.mkdir(dir, { recursive: true });
+    outPath = path.join(dir, `${slugify(organizationName, orgId)}-chats.txt`);
+  } else {
+    outPath = path.resolve(outPath);
+    await fsp.mkdir(path.dirname(outPath), { recursive: true });
+  }
+
+  // --- Write the TXT (streamed; content identical to the deployed string build) ---
+  const out = fs.createWriteStream(outPath, { encoding: "utf8" });
+  const write = (s) =>
+    new Promise((resolve, reject) => {
+      if (out.write(s)) resolve();
+      else out.once("drain", resolve);
+      out.once("error", reject);
+    });
+
+  let header = `${organizationName || "Organization"} — Chat Export\n`;
+  header += `Total messages: ${messages.length.toLocaleString()} | Contacts: ${uniqueContacts}\n`;
+  header += `Exported: ${new Date().toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg" })}\n`;
+  header += `${"=".repeat(60)}\n\n`;
+  await write(header);
+
+  for (const [waId, msgs] of Object.entries(grouped)) {
+    let chunk = `--- ${waId} ---\n`;
+    for (const msg of msgs) {
+      const date = msg.created_at
+        ? new Date(msg.created_at).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg" })
+        : "unknown";
+      const label = getSenderLabel(msg.sender_type || "");
+      let line = `[${date}] (${label}) ${msg.message || ""}`;
+      if (msg.media_url) line += ` [Media: ${msg.media_type || "file"} - ${msg.media_url}]`;
+      if (msg.voice_note_transcription) line += ` [Voice: ${msg.voice_note_transcription}]`;
+      chunk += `${line}\n`;
+    }
+    chunk += `\n`;
+    await write(chunk);
+  }
+
+  await new Promise((resolve, reject) => out.end((err) => (err ? reject(err) : resolve())));
+
+  const secs = ((Date.now() - t0) / 1000).toFixed(1);
+  console.log(`\nDone in ${secs}s`);
+  console.log(`  total messages: ${messages.length.toLocaleString()}`);
+  console.log(`  groups:         ${uniqueContacts}`);
+  console.log(`  file:           ${outPath}`);
+}

package/src/commands/org.js

@@ -0,0 +1,33 @@
+// `flowiq org info <organization_id>` — read-only org summary (platform detect
+// + active agent) for the prompt-builder skill's Step 0. Raw store/Meta creds
+// are stripped server-side; this only prints derived booleans + public urls.
+
+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;
+
+export async function info(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("org", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  console.log(`${resp.name} (${resp.id})`);
+  console.log(`  platform:      ${resp.platform || "(neither shopify nor woo)"}${resp.ip_whitelist ? " [ip_whitelist]" : ""}`);
+  if (resp.shopify_domain) console.log(`  shopify:       ${resp.shopify_domain}`);
+  if (resp.woo_store_url) console.log(`  woo store:     ${resp.woo_store_url}`);
+  console.log(`  provider:      ${resp.provider || "(unset → meta)"}`);
+  console.log(`  active agent:  ${resp.active_whatsapp_agent || "(NONE — set one before building a prompt)"}`);
+}

package/src/commands/pinboard.js

@@ -0,0 +1,174 @@
+// `flowiq pinboard pull <task_id>` / `push <slug>` / `list` / `list-remote [status]`.
+// Round-trips a single Pin Board task (flowapt_tasks row) via /cli/pinboard.
+// No DB credentials on disk — all work happens server-side.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const PIN_DIR = path.resolve(process.cwd(), ".flowiq", "pinboard");
+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 VALID_STATUS = ["open", "in_progress", "done"];
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return (s || fallback).slice(0, 60);
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function resolvePushPath(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) {
+    candidates.push(identifier);
+  } else if (identifier.includes("/") || identifier.includes("\\")) {
+    candidates.push(path.resolve(identifier));
+  } else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(PIN_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) {
+    if (await fileExists(c)) return c;
+  }
+  throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+export async function pull(taskId) {
+  if (!UUID_RE.test(taskId)) {
+    console.error(`Error: "${taskId}" is not a valid task UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("pinboard", { task_id: taskId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(PIN_DIR, { recursive: true });
+  const slug = slugify(resp.name, resp.id);
+  const filePath = path.join(PIN_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  const orgs = resp.organizations_resolved || [];
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  name:      ${resp.name}`);
+  console.log(`  status:    ${resp.status} / ${resp.urgency}`);
+  console.log(`  due:       ${resp.preferred_due_date || "(none)"}`);
+  console.log(`  orgs:      ${(resp.organizations || []).length}${orgs.length ? " (" + orgs.map((o) => o.name || o.id.slice(0, 8)).join(", ") + ")" : ""}`);
+  console.log(`  media:     ${(resp.media || []).length}`);
+  console.log(`  messages:  ${(resp.messages || []).length}`);
+  console.log(`  created:   ${resp.created_by} @ ${resp.created_at}`);
+}
+
+export async function push(identifier) {
+  let filePath;
+  try {
+    filePath = await resolvePushPath(identifier);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+  const raw = await fs.readFile(filePath, "utf8");
+  let data;
+  try { data = JSON.parse(raw); }
+  catch (e) {
+    console.error(`Invalid JSON in ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+  if (!data.id || !UUID_RE.test(data.id)) {
+    console.error(`${filePath}: id missing or invalid`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("pinboard", {
+      id: data.id,
+      name: data.name,
+      description: data.description ?? null,
+      status: data.status,
+      urgency: data.urgency,
+      preferred_due_date: data.preferred_due_date ?? null,
+      organizations: data.organizations ?? [],
+      media: data.media ?? [],
+      messages: data.messages ?? [],
+      created_by: data.created_by,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Pushed ${filePath}`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  name:      ${resp.name}`);
+  console.log(`  status:    ${resp.status} / ${resp.urgency}`);
+  console.log(`  due:       ${resp.preferred_due_date || "(none)"}`);
+  console.log(`  orgs:      ${resp.orgs}`);
+  console.log(`  media:     ${resp.media}`);
+  console.log(`  messages:  ${resp.messages}`);
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(PIN_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local task files; run `pinboard pull <task_id>`, or `pinboard list-remote` to see ids)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local task files; run `pinboard pull <task_id>`, or `pinboard list-remote` to see ids)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(PIN_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  id:       ${d.id || "?"}`);
+      console.log(`  name:     ${d.name || "(unknown)"}`);
+      console.log(`  status:   ${d.status || "?"} / ${d.urgency || "?"}`);
+      console.log(`  msgs:     ${Array.isArray(d.messages) ? d.messages.length : "?"}`);
+      console.log(`  pulled:   ${d.pulled_at || "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}
+
+export async function listRemote(statusFilter) {
+  if (statusFilter && !VALID_STATUS.includes(statusFilter)) {
+    console.error(`Invalid status filter "${statusFilter}". Use one of ${VALID_STATUS.join(" | ")}.`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("pinboard", { list: "1", status: statusFilter });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+  const tasks = resp.tasks || [];
+  if (!tasks.length) {
+    console.log(statusFilter ? `(no tasks with status=${statusFilter})` : "(no tasks in flowapt_tasks)");
+    return;
+  }
+  console.log(`Found ${tasks.length} task${tasks.length === 1 ? "" : "s"}${statusFilter ? ` (status=${statusFilter})` : ""}:\n`);
+  for (const t of tasks) {
+    const updated = t.updated_at ? new Date(t.updated_at).toISOString().replace("T", " ").slice(0, 16) : "?";
+    console.log(`  ${t.id}  [${String(t.status).padEnd(11)}] [${String(t.urgency).padEnd(8)}]  ${updated}  ${t.created_by} — ${t.name}`);
+  }
+}

package/src/commands/templates.js

@@ -0,0 +1,156 @@
+// `flowiq templates pull <org_id>` / `list` — read WhatsApp templates from Meta.
+// `flowiq templates create <org> --request-file f.json` / `status` — §12 (create).
+// Pull is read-only via /cli/templates; create proxies /cli/meta-templates.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const TPL_DIR = path.resolve(process.cwd(), ".flowiq", "templates");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function slugify(name, fallback) {
+  const s = String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+export async function pull(orgId) {
+  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("templates", { organization_id: orgId });
+  } catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(TPL_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(TPL_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  waba:      ${resp.waba_id}`);
+  if (resp.meta_phone_number) console.log(`  phone:     ${resp.meta_phone_number}`);
+  console.log(`  templates: ${resp.template_count}`);
+  console.log(`  status:    ${JSON.stringify(resp.summary?.byStatus || {})}`);
+  console.log(`  category:  ${JSON.stringify(resp.summary?.byCategory || {})}`);
+  console.log(`  language:  ${JSON.stringify(resp.summary?.byLanguage || {})}`);
+}
+
+export async function create(orgId, opts = {}) {
+  if (!opts.requestFile) {
+    console.error("Error: --request-file <path> is required (JSON with template_request, optional template_data/media_header/cards_media).");
+    process.exit(1);
+  }
+  let filePath = opts.requestFile;
+  if (!path.isAbsolute(filePath)) filePath = path.resolve(filePath);
+  let data;
+  try {
+    data = JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (e) {
+    console.error(`Cannot read request file ${filePath}: ${e.message}`);
+    process.exit(1);
+  }
+
+  // The file may be the full edge-fn body, or just the inner template_request.
+  const organizationId = orgId || data.organization_id;
+  if (!organizationId || !UUID_RE.test(organizationId)) {
+    console.error("Error: organization_id missing/invalid (pass <org_id> or include it in the request file).");
+    process.exit(1);
+  }
+  const templateRequest = data.template_request || (data.name ? data : null);
+  if (!templateRequest) {
+    console.error("Error: request file must contain a `template_request` object (or be one, with a `name`).");
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("meta-templates", {
+      organization_id: organizationId,
+      template_request: templateRequest,
+      template_data: data.template_data,
+      media_header: data.media_header,
+      cards_media: data.cards_media,
+    });
+  } catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    if (e.body) console.error(JSON.stringify(e.body, null, 2));
+    process.exit(1);
+  }
+
+  console.log(`Submitted template "${templateRequest.name}" for org ${organizationId}`);
+  console.log(JSON.stringify(resp, null, 2));
+}
+
+export async function status(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("meta-templates", { organization_id: orgId, name: opts.name });
+  } catch (e) {
+    console.error(`Status lookup failed: ${e.message}`);
+    process.exit(1);
+  }
+  const rows = resp.templates || [];
+  if (!rows.length) {
+    console.log(opts.name ? `(no templates matching "${opts.name}")` : "(no templates on record for this org)");
+    return;
+  }
+  console.log(`${rows.length} template row${rows.length === 1 ? "" : "s"}${opts.name ? ` matching "${opts.name}"` : ""}:`);
+  for (const t of rows) {
+    const name = t.template_name || t.name || "(unnamed)";
+    const st = t.status || "(no status)";
+    const cat = t.category ? ` [${t.category}]` : "";
+    console.log(`  ${name.padEnd(40)} ${String(st).padEnd(16)}${cat}`);
+  }
+  console.log("\nNote: status is captured at submit time (older rows may be null). For the live");
+  console.log("Meta-side status + rejection reasons, run `templates pull <org_id>`.");
+}
+
+export async function list() {
+  let files;
+  try {
+    files = (await fs.readdir(TPL_DIR)).filter((f) => f.endsWith(".json"));
+  } catch {
+    console.log("(no local template files; run `templates pull <org_id>`)");
+    return;
+  }
+  if (!files.length) {
+    console.log("(no local template files; run `templates pull <org_id>`)");
+    return;
+  }
+  files.sort();
+  for (const f of files) {
+    const fp = path.join(TPL_DIR, f);
+    try {
+      const d = JSON.parse(await fs.readFile(fp, "utf8"));
+      console.log(f);
+      console.log(`  org:       ${d.organization_name ?? "(unknown)"} (${d.organization_id ?? "?"})`);
+      console.log(`  waba:      ${d.waba_id ?? "?"}`);
+      console.log(`  phone:     ${d.meta_phone_number ?? "(none)"}`);
+      console.log(`  templates: ${d.template_count ?? (Array.isArray(d.templates) ? d.templates.length : "?")}`);
+      if (d.summary?.byStatus) console.log(`  status:    ${JSON.stringify(d.summary.byStatus)}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "(unknown)"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/data/scenarios.qa.json

@@ -0,0 +1,41 @@
+{
+  "name": "Generic agent smoke pack (org-agnostic)",
+  "note": "Universal FlowIQ-agent behaviours. Assertion-light on purpose — replies are dumped for inspection since exact copy varies per org. Safe to run against any org via `qa <org_id>`. For org-specific assertions, author a pack and run it with `scenario <org_id> <file>`.",
+  "scenarios": [
+    {
+      "id": "greeting",
+      "title": "Greeting / warmth",
+      "turns": [
+        { "text": "Hi there, how are you doing today?", "expectNot": ["👉"] }
+      ]
+    },
+    {
+      "id": "off-topic",
+      "title": "Off-topic request (should decline in one message)",
+      "turns": [
+        { "text": "What's the weather like today?" }
+      ]
+    },
+    {
+      "id": "product-basic",
+      "title": "Basic product question",
+      "turns": [
+        { "text": "What are your best-selling products?" }
+      ]
+    },
+    {
+      "id": "human-handover",
+      "title": "Request a human",
+      "turns": [
+        { "text": "This isn't helping. Can I please speak to a real person?" }
+      ]
+    },
+    {
+      "id": "rating-reply",
+      "title": "End-of-chat rating reply",
+      "turns": [
+        { "text": "I'd rate this chat a 3 out of 5." }
+      ]
+    }
+  ]
+}

package/src/index.js

@@ -14,6 +14,13 @@ import * as messagingWebhooksCmd from "./commands/messaging-webhooks.js";
 import * as webhooksCmd from "./commands/webhooks.js";
 import * as flowmodCmd from "./commands/flowmod.js";
 import * as groupsCmd from "./commands/groups.js";
+import * as pinboardCmd from "./commands/pinboard.js";
+import * as templatesCmd from "./commands/templates.js";
+import * as orgCmd from "./commands/org.js";
+import * as agentConfigCmd from "./commands/agent-config.js";
+import * as agentUpdatesCmd from "./commands/agent-updates.js";
+import * as exportCmd from "./commands/export.js";
+import * as testCmd from "./commands/agent-test.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
@@ -134,5 +141,138 @@ export function run(argv) {
     .option("--json", "print the full JSON payload to stdout instead of the timeline")
     .action((nameOrJid, opts) => groupsCmd.pull(nameOrJid, opts));
 
+  // pinboard (one flowapt_tasks row: Pin Board team task board)
+  const pinboard = program.command("pinboard")
+    .alias("pin")
+    .description("Round-trip a single Pin Board task (flowapt_tasks row)");
+  pinboard.command("pull <task_id>")
+    .description("Fetch one task into a local JSON file")
+    .action((taskId) => pinboardCmd.pull(taskId));
+  pinboard.command("push <slug-or-path>")
+    .description("Apply a local JSON file's editable fields back to the task row (stamps updated_at)")
+    .action((id) => pinboardCmd.push(id));
+  pinboard.command("list")
+    .description("List local task JSON files")
+    .action(() => pinboardCmd.list());
+  pinboard.command("list-remote [status]")
+    .description("List every task in the DB (optionally filter: open | in_progress | done) to find an id")
+    .action((status) => pinboardCmd.listRemote(status));
+
+  // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
+  const templates = program.command("templates")
+    .alias("tpl")
+    .description("Read an org's WhatsApp templates from Meta (pull/list); create + submit to Meta (create/status)");
+  templates.command("pull <organization_id>")
+    .description("Fetch every live WhatsApp template from Meta into a local JSON snapshot")
+    .action((orgId) => templatesCmd.pull(orgId));
+  templates.command("list")
+    .description("List local template snapshots")
+    .action(() => templatesCmd.list());
+  templates.command("create [organization_id]")
+    .description("Submit a new WhatsApp template to Meta via the create-meta-template edge fn")
+    .requiredOption("--request-file <path>", "JSON file with template_request (+ optional template_data/media_header/cards_media)")
+    .action((orgId, opts) => templatesCmd.create(orgId, opts));
+  templates.command("status <organization_id>")
+    .description("List the org's template rows (name + status) to poll Meta approval")
+    .option("--name <substr>", "filter by template name substring")
+    .action((orgId, opts) => templatesCmd.status(orgId, opts));
+
+  // org (read-only org summary for the prompt-builder skill, creds stripped)
+  const org = program.command("org").description("Read-only org info (platform detect + active agent)");
+  org.command("info <organization_id>")
+    .description("Show the org's platform, storefront url + active agent (raw creds stripped)")
+    .option("--json", "print the raw JSON payload")
+    .action((orgId, opts) => orgCmd.info(orgId, opts));
+
+  // agent (agent-level config writes: the prompt-builder skill's Step 5)
+  const agent = program.command("agent").description("Configure the org's active agent");
+  agent.command("config <organization_id>")
+    .description("Set allowlisted agent config (no flags = show current)")
+    .option("--use-settings-prompt [bool]", "settings.use_settings_prompt (true if bare)")
+    .option("--model <model>", "settings.model (e.g. gpt-5.4-mini)")
+    .option("--rename <name>", "rename the agent")
+    .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat", agentConfigCmd.collectTool, [])
+    .option("--discount [bool]", "agent.discount.enabled (true if bare)")
+    .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
+
+  // agent-updates (pending client change-requests + chat context; read-only)
+  const au = program.command("agent-updates")
+    .alias("au")
+    .description("Pull pending agent_updates + the chat context around each (read-only)");
+  au.command("pull <organization_id>")
+    .description("Fetch updates + linked contact + trigger-message window; downloads attachments locally")
+    .option("--status <status>", "pending (default) | resolved | in_progress | all")
+    .option("--titles <list>", "only updates whose title contains any of these (comma-separated, ci substring)")
+    .option("--before <n>", "context messages before the trigger (default 12)")
+    .option("--after <n>", "context messages after the trigger (default 8)")
+    .option("--recent <n>", "fallback window when no linked message but a contact exists (default 20)")
+    .option("--no-files", "do NOT download attachments (default: download is ON)")
+    .option("--max-mb <n>", "skip attachments larger than N MB (default 25)")
+    .action((orgId, opts) => agentUpdatesCmd.pull(orgId, opts));
+  au.command("list")
+    .description("List local agent-updates snapshots")
+    .action(() => agentUpdatesCmd.list());
+
+  // 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>")
+    .description("Export the org's full chat history to a TXT file (keyset-paginated, byte-matches the in-app export)")
+    .option("--out <path>", "output path (default .flowiq/exports/<slug>-chats.txt)")
+    .action((orgId, opts) => exportCmd.chats(orgId, opts));
+
+  // test (drive the org's LIVE agent through the web/test channel; no real WhatsApp)
+  const test = program.command("test").description("Test an org's live agent via the web/test channel (never sends a real WhatsApp)");
+  test.command("resolve <organization_id>")
+    .description("Print the resolved agent + test contact + endpoint")
+    .option("--agent <id>", "test a specific (non-active) agent in the org")
+    .action((orgId, opts) => testCmd.resolve(orgId, opts));
+  test.command("send <organization_id> <message...>")
+    .description("Send one message, print the reply + any tool calls")
+    .option("--agent <id>", "test a specific (non-active) agent")
+    .option("--clear", "clear the conversation before the run")
+    .option("--sender <name>", "senderName in the payload (default the test contact's name)")
+    .option("--image <url>", "attach a publicly-fetchable image URL (text is the caption)")
+    .option("--timeout <ms>", "per-turn HTTP timeout (default 120000)")
+    .option("--json", "print raw JSON instead of the transcript")
+    .action((orgId, message, opts) => testCmd.send(orgId, message, opts));
+  test.command("scenario <organization_id> <file>")
+    .description("Run a scenario pack (JSON: {scenarios:[{id,title,turns:[{text,expect?,expectNot?}]}]})")
+    .option("--agent <id>", "test a specific agent")
+    .option("--no-clear-between", "do NOT clear between scenarios (one long thread)")
+    .option("--sender <name>", "senderName")
+    .option("--timeout <ms>", "per-turn HTTP timeout (default 120000)")
+    .option("--json", "print raw JSON results")
+    .action((orgId, file, opts) => testCmd.scenario(orgId, file, opts));
+  test.command("qa <organization_id>")
+    .description("Run the bundled generic smoke pack")
+    .option("--agent <id>", "test a specific agent")
+    .option("--no-clear-between", "do NOT clear between scenarios")
+    .option("--sender <name>", "senderName")
+    .option("--timeout <ms>", "per-turn HTTP timeout")
+    .option("--json", "print raw JSON results")
+    .action((orgId, opts) => testCmd.qa(orgId, opts));
+  test.command("clear <organization_id>")
+    .description("Clear the test conversation (hide history via memory_cutoff)")
+    .option("--agent <id>", "target a specific agent's test contact")
+    .action((orgId, opts) => testCmd.clear(orgId, opts));
+  test.command("stress <organization_id> [pack]")
+    .description("Run an adversarial pack in parallel, one isolated contact per scenario (phase 2)")
+    .option("--agent <id>", "test a specific agent")
+    .option("--concurrency <n>", "parallel scenarios (default 6)")
+    .option("--timeout <ms>", "per-turn HTTP timeout")
+    .option("--out <path>", "results file (default .flowiq/agent-test/stress-results.json)")
+    .option("--contact <id>", "use a fixed real contact instead of isolated ones (forces concurrency 1)")
+    .action((orgId, pack, opts) => testCmd.stress(orgId, pack, opts));
+  test.command("cleanup <organization_id>")
+    .description("DELETE the stress test contacts + their messages/sessions")
+    .option("--agent <id>", "target a specific agent's stress contacts")
+    .option("--confirm", "required — confirms the destructive delete")
+    .action((orgId, opts) => testCmd.cleanup(orgId, opts));
+  test.command("extract <organization_id>")
+    .description("Rebuild full stress transcripts from the DB (for an LLM judge)")
+    .option("--agent <id>", "target a specific agent's stress contacts")
+    .option("--out <path>", "output file (default .flowiq/agent-test/judge_input.json)")
+    .action((orgId, opts) => testCmd.extract(orgId, opts));
+
   program.parseAsync(argv);
 }