@flowapt/flowiq-cli 0.10.0 → 0.11.0

package/src/commands/notes.js

@@ -0,0 +1,63 @@
+// `flowiq steer list|add|clear <contact_id>` + `flowiq notes list|add
+// <contact_id>` — the internal rows in a contact's chat (server: api/cli/notes.js).
+
+import { http } from "../http.js";
+import { fmtSast } from "./audit.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 fail(prefix, e) { console.error(`${prefix}: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+const requireContact = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid contact UUID.`); process.exit(1); } };
+
+async function listKind(contactId, kind, opts) {
+  requireContact(contactId);
+  let resp;
+  try { resp = await http.get("notes", { contact_id: contactId, kind, limit: opts.limit }); } catch (e) { fail("List failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const label = kind === "notes" ? "internal note" : "steer";
+  console.log(`${resp.contact_name || "(no name)"} ${resp.contact_whatsapp_id || ""} on ${resp.organization_name}: ${resp.count} ${label}(s)${kind === "steers" ? ` · AI ${resp.bot_status === false ? "OFF" : "on"}${resp.steer_messages_flag ? "" : " · steer_messages flag off (inbox hides the control; vert still applies rows)"}` : ""}`);
+  for (const r of resp.rows) {
+    const head = kind === "notes" ? `${r.author ?? "?"}` : `${r.mode}${r.mode === "once" ? (r.consumed ? ", consumed" : ", pending") : ""}`;
+    console.log(`\n  ${fmtSast(r.created_at)} SAST · ${head}${kind === "steers" && !r.active ? " · inactive" : ""}\n  ${r.id}\n    ${String(r.text).split("\n").join("\n    ")}`);
+  }
+  if (kind === "steers" && resp.rows.some((r) => r.active)) console.log(`\n  Remove: flowiq steer clear ${contactId} [--id <id>] --confirm`);
+}
+
+export const steerList = (contactId, opts = {}) => listKind(contactId, "steers", opts);
+export const notesList = (contactId, opts = {}) => listKind(contactId, "notes", opts);
+
+export async function steerAdd(contactId, textParts, opts = {}) {
+  requireContact(contactId);
+  const text = (Array.isArray(textParts) ? textParts.join(" ") : String(textParts ?? "")).trim();
+  if (!text) { console.error("Error: flowiq steer add <contact_id> \"instruction for the agent\" [--once]"); process.exit(1); }
+  let resp;
+  try { resp = await http.post("notes", { action: "add_steer", contact_id: contactId, text, mode: opts.once ? "once" : "persistent" }); } catch (e) { fail("Steer failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`✓ ${resp.mode === "once" ? "one-shot" : "ongoing"} steer added (${resp.id}) as ${resp.author}. ${resp.mode === "once" ? "The agent applies it on the next reply, then it is spent." : "The agent applies it on EVERY reply until: flowiq steer clear " + contactId + " --id " + resp.id + " --confirm"}`);
+  for (const w of resp.warnings || []) console.error(`  ⚠ ${w}`);
+}
+
+export async function steerClear(contactId, opts = {}) {
+  requireContact(contactId);
+  const ids = opts.id ? [].concat(opts.id) : undefined;
+  let resp;
+  try { resp = await http.post("notes", { action: "clear_steers", contact_id: contactId, steer_ids: ids, confirm: !!opts.confirm }); } catch (e) { fail("Clear failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.dry_run) {
+    if (!resp.count) { console.log("No steers to remove."); return; }
+    console.log(`Would delete ${resp.count} steer(s):`);
+    for (const s of resp.steers) console.log(`  ${s.id}  ${s.mode}${s.consumed ? " (consumed)" : ""}  ${String(s.text).slice(0, 80)}`);
+    console.log("Add --confirm to delete (the texts are kept in the audit row).");
+    return;
+  }
+  console.log(`✓ deleted ${resp.deleted} steer(s).`);
+}
+
+export async function notesAdd(contactId, textParts, opts = {}) {
+  requireContact(contactId);
+  const text = (Array.isArray(textParts) ? textParts.join(" ") : String(textParts ?? "")).trim();
+  if (!text) { console.error("Error: flowiq notes add <contact_id> \"note for the team\""); process.exit(1); }
+  let resp;
+  try { resp = await http.post("notes", { action: "add_note", contact_id: contactId, text }); } catch (e) { fail("Note failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`✓ internal note added (${resp.id}) as ${resp.author}; it shows on the Customer panel, never to the customer.`);
+}

package/src/commands/org.js

@@ -13,31 +13,78 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 export async function list(search, opts = {}) {
   let resp;
   try {
-    resp = await http.get("org", { list: "1", search: search || undefined });
+    resp = await http.get("org", { list: "1", search: search || undefined, number: opts.number || undefined });
   } catch (e) {
     console.error(`Lookup failed: ${e.message}`);
+    if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`);
     process.exit(1);
   }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
 
-  const orgs = (resp.orgs || []).filter((o) => (opts.all ? true : !o.inactive));
+  // A number lookup shows parked orgs too: the number is the question.
+  const orgs = (resp.orgs || []).filter((o) => (opts.all || opts.number ? true : !o.inactive));
   if (!orgs.length) {
-    console.log(search ? `No organizations match "${search}".` : "No organizations found.");
+    console.log(opts.number ? `No organization has WhatsApp number / phone id / WABA ${opts.number}.` : search ? `No organizations match "${search}".` : "No organizations found.");
     return;
   }
   const pad = (s, n) => String(s ?? "").padEnd(n);
   const nameW = Math.min(34, Math.max(4, ...orgs.map((o) => (o.name || "").length)));
-  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  ${pad("PLATFORM", 9)}STORE`);
+  const byNumber = !!opts.number;
+  console.log(`${pad("NAME", nameW)}  ${pad("ID", 36)}  ${byNumber ? `${pad("NUMBER", 16)}${pad("PHONE ID", 18)}${pad("WABA", 18)}` : `${pad("PLATFORM", 9)}STORE`}`);
   for (const o of orgs) {
     console.log(
       `${pad((o.name || "").slice(0, nameW), nameW)}  ${pad(o.id, 36)}  ` +
-      `${pad(o.platform || "—", 9)}${o.store || ""}${o.inactive ? "  (inactive)" : ""}`
+      (byNumber
+        ? `${pad(o.phone_number || "—", 16)}${pad(o.phone_id || "—", 18)}${pad(o.waba_id || "—", 18)}`
+        : `${pad(o.platform || "—", 9)}${o.store || ""}`) +
+      `${o.inactive ? "  (inactive)" : ""}`
     );
   }
   const hidden = (resp.orgs || []).length - orgs.length;
   console.log(`\n${orgs.length} organization(s)${hidden ? ` · ${hidden} inactive hidden (--all to show)` : ""}`);
 }
 
+// `flowiq org agent <org> on|off [--commit] [--yes]` — the agent master switch
+// (organizations.wati_webhook_status). Off = no customer gets the AI. On with
+// vert.active:false + an allowlist = test mode. On with vert.active true =
+// live for everyone, which is the shape that needs --yes.
+export async function agentSwitch(orgId, state, opts = {}) {
+  requireOrg(orgId);
+  const s = String(state || "").toLowerCase();
+  if (!["on", "off"].includes(s)) { console.error('Error: pass "on" or "off", e.g. flowiq org agent <org> off --commit'); process.exit(1); }
+  let resp;
+  try { resp = await http.post("org", { action: "agent_switch", organization_id: orgId, enabled: s === "on", dry_run: !opts.commit, confirm: !!opts.yes }); }
+  catch (e) { fail("Switch failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name} — agent master switch`);
+  console.log(`  now:      ${resp.from ? "ON" : "OFF"} · vert.active ${resp.vert_active ?? "unset"}${resp.allowed_whatsapp_ids?.length ? ` · allowlist ${resp.allowed_whatsapp_ids.join(", ")}` : ""} · active agent ${resp.active_whatsapp_agent ?? "NONE"}`);
+  if (resp.unchanged) { console.log(`  already ${resp.to ? "ON" : "OFF"} — nothing to do.`); return; }
+  console.log(`  ${resp.dry_run ? "would set" : "✓ set"}: ${resp.to ? "ON" : "OFF"} → ${resp.mode}`);
+  if (resp.dry_run) {
+    console.log(`\nDRY RUN — add --commit to switch${resp.needs_confirm ? ", and --yes because this makes the agent LIVE for every customer (set vert.allowed_whatsapp_ids + vert.active false first for a test mode)" : ""}.`);
+  } else {
+    console.log(`\nUndo: flowiq org agent ${orgId} ${resp.from ? "on" : "off"} --commit${resp.from ? " --yes" : ""}`);
+  }
+}
+
+// `flowiq org park <org> [--unpark] --confirm` — organizations.inactive.
+export async function park(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("org", { action: "park", organization_id: orgId, inactive: !opts.unpark, confirm: !!opts.confirm }); }
+  catch (e) { fail("Park failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.unchanged) { console.log(`${resp.organization_name} is already ${resp.inactive ? "parked (inactive)" : "active"}.`); return; }
+  const verb = opts.unpark ? "unpark" : "park";
+  if (resp.dry_run) {
+    console.log(`Would ${verb} ${resp.organization_name} (inactive ${resp.from} → ${resp.to}).${resp.master_switch && !opts.unpark ? " Its agent master switch is still ON — parking hides the org from censuses and crons, it does not switch the agent off (flowiq org agent <org> off --commit)." : ""}`);
+    console.log("Add --confirm to write.");
+    return;
+  }
+  console.log(`✓ ${verb}ed ${resp.organization_name} (inactive ${resp.from} → ${resp.to}).${resp.master_switch && !opts.unpark ? " ⚠ agent master switch still ON." : ""}`);
+  console.log(`Undo: flowiq org park ${orgId}${opts.unpark ? "" : " --unpark"} --confirm`);
+}
+
 export async function info(orgId, opts = {}) {
   if (!UUID_RE.test(orgId)) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);
@@ -175,8 +222,10 @@ export async function health(orgId, opts = {}) {
   const h = resp.health;
   console.log(`${resp.organization_name} — is the agent ready?  ${h.ready ? "✓ yes" : `✗ ${h.problems.length} problem(s)`}`);
   for (const p of h.problems) console.log(`  ✗ ${p}`);
+  for (const w of h.warnings || []) console.log(`  ⚠ ${w}`);
   console.log(`  switch:      master ${h.master_switch ? "ON" : "OFF"} · vert.active ${yn(h.vert_active)}${h.allowed_whatsapp_ids ? ` (only ${h.allowed_whatsapp_ids})` : ""} · provider ${h.provider}${h.coexistence ? ` · ${h.coexistence}` : ""}${h.phone_number ? ` · ${h.phone_number}` : ""}`);
-  console.log(`  keys:        OpenAI ${h.keys.openai.state}${h.keys.openai.detail ? ` (${h.keys.openai.detail})` : ""} · Claude ${h.keys.anthropic_present ? "present" : "none"}`);
+  const spare = h.keys.openai_spare;
+  console.log(`  keys:        OpenAI ${h.keys.openai.state}${h.keys.openai.detail ? ` (${h.keys.openai.detail})` : ""}${spare ? ` · spare ${spare.state}${spare.detail ? ` (${spare.detail})` : ""}` : ""} · Claude ${h.keys.anthropic_present ? "present" : "none"}`);
   console.log(`  agent:       ${h.agent ? `${h.agent.name} · ${h.agent.prompt_chars.toLocaleString()} prompt chars · prompt ${h.agent.use_settings_prompt === false ? "OFF" : "on"} · ${h.agent.model ?? "house model"} · product_lookup ${yn(h.agent.product_lookup)} · tickets ${yn(h.agent.ticket_tool_status)}` : "NONE"}`);
   console.log(`  catalogue:   ${h.catalogue.products} product rows · ${h.catalogue.embedded} with embeddings${h.catalogue.last_sync ? ` · last sync ${when(h.catalogue.last_sync.created_at)} ${h.catalogue.last_sync.success === false ? "FAILED" : "ok"} (+${h.catalogue.last_sync.added ?? 0} ~${h.catalogue.last_sync.updated ?? 0} -${h.catalogue.last_sync.deleted ?? 0})` : " · no sync recorded"}`);
   const s = h.store;

package/src/commands/products.js

@@ -0,0 +1,58 @@
+// `flowiq products status|search|reconcile <org>` — the synced catalogue as
+// the agent sees it (server: api/cli/products.js).
+
+import { http } from "../http.js";
+import { fmtSast } from "./audit.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const pad = (s, n) => String(s ?? "").padEnd(n);
+function fail(prefix, e) { console.error(`${prefix}: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+const requireOrg = (v) => { if (!UUID_RE.test(v || "")) { console.error(`Error: "${v}" is not a valid organization UUID.`); process.exit(1); } };
+
+export async function status(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.get("products", { organization_id: orgId, status: "1" }); } catch (e) { fail("Status failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const c = resp.counts;
+  console.log(`${resp.organization_name} — catalogue (${resp.platform ?? "no store"})${resp.sync_inactive_products ? " · sync_inactive_products on" : ""}`);
+  console.log(`  rows:        ${c.total} total · ${c.active} active · ${c.archived} archived · ${c.draft} draft${c.other ? ` · ${c.other} other` : ""}`);
+  console.log(`  embeddings:  ${c.embedded} with · ${c.missing_embedding} MISSING${c.missing_embedding ? "  ⚠ the agent cannot find these by meaning (products reconcile re-embeds)" : ""}`);
+  console.log(`  images:      ${c.with_image} with an image · prices: ${c.with_price} with a price · ${c.zero_stock} at zero stock`);
+  console.log(`  newest row:  ${resp.newest_row_updated_at ? `${fmtSast(resp.newest_row_updated_at)} SAST` : "—"}`);
+  if (resp.last_syncs.length) {
+    console.log(`  last syncs:`);
+    for (const s of resp.last_syncs) console.log(`    ${fmtSast(s.created_at)} SAST  ${(s.success ?? s.successful) === false ? "FAILED" : "ok    "}  +${s.added ?? 0} ~${s.updated ?? 0} -${s.deleted ?? 0}${s.source ? `  ${s.source}` : ""}${s.summary ? `  ${String(s.summary).slice(0, 70)}` : ""}`);
+  } else console.log(`  last syncs:  none recorded`);
+  if (resp.missing_embedding_sample.length) {
+    console.log(`  missing embedding (sample):`);
+    for (const p of resp.missing_embedding_sample) console.log(`    ${pad(p.variant_id, 16)} ${pad(p.status ?? "", 9)} ${String(p.product_title || "").slice(0, 60)}`);
+  }
+}
+
+export async function search(orgId, textParts, opts = {}) {
+  requireOrg(orgId);
+  const text = (Array.isArray(textParts) ? textParts.join(" ") : String(textParts ?? "")).trim();
+  if (text.length < 2) { console.error("Error: give at least 2 characters, e.g. flowiq products search <org> whey protein"); process.exit(1); }
+  let resp;
+  try { resp = await http.get("products", { organization_id: orgId, search: text, limit: opts.limit, min_similarity: opts.minSimilarity }); } catch (e) { fail("Search failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.count} match(es) for "${text}" via ${resp.rpc} (min similarity ${resp.min_similarity}) — what the agent's product_lookup tool sees`);
+  for (const p of resp.results) {
+    const sim = p.similarity ?? p.score ?? p.sim;
+    const stock = p.stockcount && typeof p.stockcount === "object" ? Object.values(p.stockcount).reduce((a, b) => a + (Number(b) || 0), 0) : p.stockcount;
+    console.log(`  ${pad(sim != null ? Number(sim).toFixed(2) : "", 5)} ${pad(p.variant_id ?? "", 16)} ${pad(p.price != null ? String(p.price) : "", 9)} ${pad(stock != null ? `stock ${stock}` : "", 11)} ${pad(p.status ?? "", 8)} ${String(p.product_title ?? p.title ?? "").slice(0, 70)}`);
+  }
+  if (!resp.count) console.log(`  (nothing within similarity ${resp.min_similarity}; try --min-similarity 0.05, or check embeddings with: flowiq products status ${orgId})`);
+}
+
+export async function reconcile(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("products", { action: "reconcile", organization_id: orgId, platform: opts.platform, confirm: !!opts.confirm }); } catch (e) { fail("Reconcile failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.dry_run) { console.log(`Would trigger a ${resp.platform} reconcile for ${resp.organization_name} (${resp.note}). Add --confirm.`); return; }
+  console.log(`${resp.ok ? "✓" : "✗"} products-reconcile-scheduler answered ${resp.http_status} for ${resp.organization_name} (${resp.platform})`);
+  console.log(`  ${JSON.stringify(resp.response).slice(0, 600)}`);
+  console.log(`\n  Watch it land: flowiq products status ${orgId}`);
+}

package/src/commands/prompts.js

@@ -96,7 +96,34 @@ export function mintSectionIds(sections) {
   return touched;
 }
 
-export async function push(identifier) {
+// --dry-run: what a push WOULD change, section by section, against the live
+// agent, without writing. Compares by section id (title for sections that
+// have no id yet) and reports added / removed / changed sections with the
+// character delta, plus title / hidden / channels / window changes.
+export function diffSections(live, local) {
+  const keyOf = (s) => s.id || `title:${s.title}`;
+  const liveBy = new Map((live || []).map((s) => [keyOf(s), s]));
+  const localBy = new Map((local || []).map((s) => [keyOf(s), s]));
+  const added = [], removed = [], changed = [];
+  for (const [k, s] of localBy) if (!liveBy.has(k)) added.push({ title: s.title, chars: (s.content || "").length });
+  for (const [k, s] of liveBy) if (!localBy.has(k)) removed.push({ title: s.title, chars: (s.content || "").length });
+  for (const [k, s] of localBy) {
+    const l = liveBy.get(k);
+    if (!l) continue;
+    const what = [];
+    if ((l.content || "") !== (s.content || "")) what.push(`content ${(l.content || "").length} → ${(s.content || "").length} chars`);
+    if ((l.title || "") !== (s.title || "")) what.push(`title "${l.title}" → "${s.title}"`);
+    if (!!l.hidden !== !!s.hidden) what.push(`hidden ${!!l.hidden} → ${!!s.hidden}`);
+    if (JSON.stringify(l.channels ?? null) !== JSON.stringify(s.channels ?? null)) what.push(`channels ${JSON.stringify(l.channels ?? "all")} → ${JSON.stringify(s.channels ?? "all")}`);
+    for (const f of ["active_from", "active_until", "active_tz"]) if ((l[f] ?? null) !== (s[f] ?? null)) what.push(`${f} ${l[f] ?? "unset"} → ${s[f] ?? "unset"}`);
+    if (what.length) changed.push({ title: s.title, what });
+  }
+  const order = (list) => list.map(keyOf).join("|");
+  const reordered = !added.length && !removed.length && order(live || []) !== order(local || []);
+  return { added, removed, changed, reordered, unchanged: !added.length && !removed.length && !changed.length && !reordered };
+}
+
+export async function push(identifier, opts = {}) {
   let filePath;
   try {
     filePath = await resolvePushPath(identifier);
@@ -121,6 +148,24 @@ export async function push(identifier) {
     process.exit(1);
   }
 
+  if (opts.dryRun) {
+    let live;
+    try { live = await http.get("prompts", { organization_id: data.organization_id, agent_id: data.agent_id }); }
+    catch (e) { console.error(`Dry run failed (could not read the live prompt): ${e.message}`); process.exit(1); }
+    const d = diffSections(live.prompt_sections, data.prompt_sections);
+    const liveChars = (live.prompt_sections || []).reduce((a, s) => a + (s.content || "").length, 0);
+    const localChars = data.prompt_sections.reduce((a, s) => a + (s.content || "").length, 0);
+    console.log(`DRY RUN — ${filePath} against ${live.agent_name} (${live.agent_id}) on ${live.organization_name}`);
+    console.log(`  live: ${(live.prompt_sections || []).length} sections, ${liveChars.toLocaleString()} chars · file: ${data.prompt_sections.length} sections, ${localChars.toLocaleString()} chars`);
+    if (d.unchanged) { console.log("  no differences — a push would change nothing."); return; }
+    for (const a of d.added) console.log(`  + add     "${a.title}" (${a.chars} chars)`);
+    for (const r of d.removed) console.log(`  - REMOVE  "${r.title}" (${r.chars} chars)`);
+    for (const c of d.changed) console.log(`  ~ change  "${c.title}": ${c.what.join("; ")}`);
+    if (d.reordered) console.log("  ~ sections reordered");
+    console.log(`\nNothing written. Push for real: flowiq prompts push ${identifier}`);
+    return;
+  }
+
   // A section added by hand has no id yet. Mint one and write it back to the
   // file BEFORE pushing, so a later pull or push keeps the same id.
   const minted = mintSectionIds(data.prompt_sections);

package/src/commands/segments.js

@@ -288,7 +288,20 @@ export async function plan(orgId, opts = {}) {
     console.log(`⚠ could not check existing batch tags (${e.message}) — verify with \`seg list --prefix ${prefix}\` before apply.`);
   }
 
-  const slug = slugify(opts.segment || prefix, prefix);
+  // A continuation (--start-index N) is a NEW plan, not a rewrite of the first
+  // one: the earlier file is the record of who got the earlier batches, so it
+  // is never overwritten. The continuation lands in <slug>-from-NN.json
+  // unless --segment names it.
+  const baseSlug = slugify(opts.segment || prefix, prefix);
+  const slug = !opts.segment && startIndex > 1 ? `${baseSlug}-from-${String(startIndex).padStart(2, "0")}` : baseSlug;
+  if (await fs.access(planPath(slug)).then(() => true).catch(() => false)) {
+    const prev = JSON.parse(await fs.readFile(planPath(slug), "utf8").catch(() => "{}"));
+    if (prev.applied) {
+      console.error(`Error: ${planPath(slug)} already exists AND was applied on ${prev.applied.at} — it is the record of who got those batches. Pass --segment <new-name> to write a different file.`);
+      process.exit(1);
+    }
+    console.log(`⚠ overwriting ${planPath(slug)} (never applied)`);
+  }
   const planDoc = {
     schema_version: 1,
     segment: slug,
@@ -373,24 +386,44 @@ export async function apply(orgId, identifier, opts = {}) {
     if (a !== planDoc.segment) { console.log("Mismatch — aborted, nothing tagged."); process.exit(0); }
   }
 
-  let resp;
-  try {
-    resp = await http.post("segments", {
-      mode: "apply", organization_id: orgId,
-      batches: planDoc.batches.map((b) => ({ tag: b.tag, contact_ids: b.contact_ids })),
-    });
-  } catch (e) {
-    console.error(`Apply failed: ${e.message}`);
-    if (e.body?.error) console.error(`  ${e.body.error}`);
-    process.exit(1);
+  // One HTTP request per chunk of ≤ APPLY_CHUNK ids. The server already splits
+  // its DB calls at 8,000 rows, but a big cohort in ONE request still ran past
+  // the function timeout (Zero BS 18,614 on 30 Sep 2026: two timeouts, one
+  // batch half-tagged). Smaller requests finish, and a failure names the chunk
+  // so a re-run (idempotent) picks up where it stopped.
+  const APPLY_CHUNK = 4000;
+  const chunks = [];
+  for (const b of planDoc.batches) {
+    for (let i = 0; i < b.contact_ids.length; i += APPLY_CHUNK) chunks.push({ tag: b.tag, contact_ids: b.contact_ids.slice(i, i + APPLY_CHUNK) });
+  }
+  const byTag = new Map();
+  for (const [ci, chunk] of chunks.entries()) {
+    let resp;
+    try {
+      resp = await http.post("segments", { mode: "apply", organization_id: orgId, batches: [chunk] });
+    } catch (e) {
+      const done = [...byTag.values()].reduce((a, r) => a + r.tagged, 0);
+      console.error(`Apply failed on request ${ci + 1}/${chunks.length} (${chunk.tag}, ${chunk.contact_ids.length} ids): ${e.message}`);
+      if (e.body?.error) console.error(`  ${e.body.error}`);
+      console.error(`  ${done} contact(s) tagged by the earlier requests. Re-run the same apply: it is idempotent and only the missing ones get tagged.`);
+      process.exit(1);
+    }
+    for (const r of resp.results || []) {
+      const prev = byTag.get(r.tag) ?? { tag: r.tag, tagged: 0, already_had: 0, not_found: 0 };
+      prev.tagged += r.tagged ?? 0; prev.already_had += r.already_had ?? 0; prev.not_found += r.not_found ?? 0;
+      byTag.set(r.tag, prev);
+    }
+    if (chunks.length > 1) console.log(`  request ${ci + 1}/${chunks.length}: ${chunk.tag} ${chunk.contact_ids.length} ids → tagged ${(resp.results || []).reduce((a, r) => a + (r.tagged ?? 0), 0)}`);
   }
+  const results = [...byTag.values()];
+  const totals = results.reduce((a, r) => ({ tagged: a.tagged + r.tagged, already_had: a.already_had + r.already_had, not_found: a.not_found + r.not_found }), { tagged: 0, already_had: 0, not_found: 0 });
 
-  for (const r of resp.results || []) {
+  for (const r of results) {
     console.log(`  ${r.tag.padEnd(40)} tagged ${r.tagged}${r.already_had ? ` · already_had ${r.already_had}` : ""}${r.not_found ? ` · not_found ${r.not_found}` : ""}`);
   }
-  console.log(`Totals: tagged ${resp.totals.tagged} · already_had ${resp.totals.already_had} · not_found ${resp.totals.not_found}`);
+  console.log(`Totals: tagged ${totals.tagged} · already_had ${totals.already_had} · not_found ${totals.not_found}`);
 
-  planDoc.applied = { at: new Date().toISOString(), tag_counts: Object.fromEntries((resp.results || []).map((r) => [r.tag, r.tagged + r.already_had])) };
+  planDoc.applied = { at: new Date().toISOString(), tag_counts: Object.fromEntries(results.map((r) => [r.tag, r.tagged + r.already_had])) };
   await fs.writeFile(filePath, JSON.stringify(planDoc, null, 2) + "\n", "utf8");
   console.log("");
   console.log(`Send per tag, one batch at a time: flowiq broadcast send ${orgId} --tag ${planDoc.batches[0].tag} --template <name> …`);

package/src/commands/tag.js

@@ -8,8 +8,12 @@
 //   flowiq tag segment <org> --min-orders 2 --min-spent 1000 --region ZA-GP --tag gp-repeat
 //   flowiq tag attributes <org> --filter allow_broadcast_true --tag broadcastable
 //   flowiq tag messages   <org> --min-count 3 --sender user-whatsapp --tag engaged
+//   flowiq tag ids     <org> --ids a,b,c | --ids-file ids.txt --tag <name> [--commit]
+//   flowiq tag holders <org> <tag> [--limit 200] [--all] [--csv]
+//   flowiq tag field   <org> --field whatsapp_id --any 27794975464 --exact --tag x --commit
 //   flowiq tag list    <org>
-//   flowiq tag remove  <org> <tag>[,<tag>...] --confirm
+//   flowiq tag remove  <org> <tag>[,<tag>...] --confirm              (every contact)
+//   flowiq tag remove  <org> <tag> --contacts a,b | --contacts-file f --confirm   (those only)
 //
 // Every match mode prints the dry-run count + a sample; nothing writes until
 // --commit AND (for large writes) a typed confirmation. Appends only — it
@@ -91,12 +95,76 @@ export async function field(orgId, opts = {}) {
   requireOrg(orgId);
   const keywords = splitList(opts.any || opts.all);
   if (!keywords) { console.error("Error: pass --any \"a,b\" (OR) or --all \"a,b\" (AND)."); process.exit(1); }
+  if (opts.exact && opts.all) { console.error("Error: --exact matches whole values, so it is an OR over --any (drop --all)."); process.exit(1); }
   const payload = {
     mode: "field", organization_id: orgId, field_name: opts.field || "order_history",
-    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive,
+    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive, exact: !!opts.exact,
   };
   await confirmLargeWrite(orgId, payload, opts, "Field search");
-  await runMatch("Field search", payload, opts);
+  await runMatch(opts.exact ? "Exact field match" : "Field search", payload, opts);
+}
+
+async function readIds(csv, file) {
+  const fs = await import("node:fs/promises");
+  let ids = splitList(csv) || [];
+  if (file) {
+    const text = await fs.readFile(file, "utf8").catch((e) => { console.error(`Error: cannot read ${file}: ${e.message}`); process.exit(1); });
+    ids.push(...text.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean));
+  }
+  ids = [...new Set(ids)];
+  const bad = ids.filter((id) => !UUID_RE.test(id));
+  if (bad.length) console.error(`⚠ ${bad.length} value(s) are not contact UUIDs and will be ignored (e.g. ${bad[0]})`);
+  return ids.filter((id) => UUID_RE.test(id));
+}
+
+// `flowiq tag ids <org> --ids a,b | --ids-file f --tag <name> [--commit]`
+export async function ids(orgId, opts = {}) {
+  requireOrg(orgId);
+  const list = await readIds(opts.ids, opts.idsFile);
+  if (!list.length) { console.error("Error: pass --ids a,b,c or --ids-file <path> (contact UUIDs, one per line or comma-separated)."); process.exit(1); }
+  const payload = { mode: "ids", organization_id: orgId, contact_ids: list };
+  await confirmLargeWrite(orgId, payload, opts, "Id list");
+  const commit = !!opts.commit;
+  if (commit && !opts.tag) { console.error("Error: --tag <name> is required with --commit."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("tag", { ...payload, dry_run: !commit, tag: commit ? opts.tag.trim() : undefined }); }
+  catch (e) { console.error(`Tag ids failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!commit) {
+    console.log(`Id list: ${resp.matched} of ${list.length} id(s) belong to ${resp.organization_name}${resp.not_found ? ` · ${resp.not_found} not in this org (ignored)` : ""}.`);
+    renderSample(resp.sample);
+    console.log(`\nAdd --tag <name> --commit to apply. (dry run — nothing written)`);
+    return;
+  }
+  console.log(`Id list: matched ${resp.matched} · newly tagged ${resp.tagged} · already had "${resp.tag}" ${resp.already_had}${resp.not_found ? ` · not in org ${resp.not_found}` : ""}.`);
+  console.log(`\nVerify: flowiq tag holders ${orgId} ${resp.tag}   ·   Undo: flowiq tag remove ${orgId} ${resp.tag} --contacts-file <the same file> --confirm`);
+}
+
+// `flowiq tag holders <org> <tag> [--limit] [--all] [--csv]` — who carries a tag.
+export async function holders(orgId, tagName, opts = {}) {
+  requireOrg(orgId);
+  if (!tagName) { console.error("Error: pass the tag name, e.g. flowiq tag holders <org> vip"); process.exit(1); }
+  const pageSize = opts.all ? 1000 : Math.min(Number(opts.limit) || 200, 1000);
+  const contacts = [];
+  let offset = 0, resp;
+  for (;;) {
+    try { resp = await http.post("tag", { mode: "holders", organization_id: orgId, tag: tagName, limit: pageSize, offset }); }
+    catch (e) { console.error(`Holders failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+    contacts.push(...(resp.contacts || []));
+    if (!opts.all || !resp.has_more || !(resp.contacts || []).length) break;
+    offset += resp.contacts.length;
+  }
+  if (opts.json) { console.log(JSON.stringify({ ...resp, contacts }, null, 2)); return; }
+  if (opts.csv) {
+    console.log("id,full_name,whatsapp_id,email,allow_broadcast,archived,blocked");
+    for (const c of contacts) console.log([c.id, c.full_name, c.whatsapp_id, c.email, c.allow_broadcast, c.archived, c.blocked].map((v) => { const s = v == null ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; }).join(","));
+    return;
+  }
+  console.log(`"${tagName}" on ${resp.organization_name}: ${resp.total} contact(s)${contacts.length < resp.total ? ` (showing ${contacts.length}; --all for every page, --csv to export)` : ""}`);
+  for (const c of contacts) {
+    const flags = [c.allow_broadcast === false && "no-broadcast", c.archived && "archived", c.blocked && "blocked", c.bot_status === false && "AI off"].filter(Boolean).join(", ");
+    console.log(`  ${(c.full_name || "—").slice(0, 28).padEnd(28)} ${String(c.whatsapp_id || c.email || "").padEnd(16)} ${c.id}${flags ? `  (${flags})` : ""}`);
+  }
 }
 
 export async function cohort(orgId, opts = {}) {
@@ -170,12 +238,14 @@ export async function remove(orgId, tagArg, opts = {}) {
   requireOrg(orgId);
   const tags = splitList(tagArg);
   if (!tags || !tags.length) { console.error("Error: pass one or more tag names (comma-separated)."); process.exit(1); }
+  const contactIds = opts.contacts || opts.contactsFile ? await readIds(opts.contacts, opts.contactsFile) : null;
+  if ((opts.contacts || opts.contactsFile) && !contactIds.length) { console.error("Error: --contacts / --contacts-file gave no contact UUIDs."); process.exit(1); }
   if (!opts.confirm) {
-    console.log(`DRY RUN — would remove ${tags.length} tag(s) from all contacts: ${tags.join(", ")}. Add --confirm to remove.`);
+    console.log(`DRY RUN — would remove ${tags.length} tag(s) from ${contactIds ? `${contactIds.length} listed contact(s)` : "ALL contacts"}: ${tags.join(", ")}. Add --confirm to remove.`);
     return;
   }
   let resp;
-  try { resp = await http.post("tag", { mode: "remove", organization_id: orgId, tags }); }
-  catch (e) { console.error(`Remove failed: ${e.message}`); process.exit(1); }
-  console.log(`Removed ${tags.join(", ")} from ${resp.contacts_touched} contact(s) on ${resp.organization_name}.`);
+  try { resp = await http.post("tag", { mode: "remove", organization_id: orgId, tags, ...(contactIds ? { contact_ids: contactIds } : {}) }); }
+  catch (e) { console.error(`Remove failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  console.log(`Removed ${tags.join(", ")} from ${resp.contacts_touched} contact(s) on ${resp.organization_name}${contactIds ? ` (of ${contactIds.length} listed${resp.not_found ? `, ${resp.not_found} not in this org` : ""})` : ""}.`);
 }

package/src/commands/templates.js

@@ -343,8 +343,37 @@ export async function show(orgId, name, opts = {}) {
 
   const rows = resp.templates || [];
   if (!rows.length) {
-    console.error(`No template on this org matching "${name}". List them with: flowiq templates status ${orgId}`);
-    process.exit(1);
+    // Not in FlowIQ's table is not "does not exist": a template made in Meta's
+    // own tools or on a swapped WABA lives only at Meta (Health Matrix, 22 Sep
+    // 2026). Read it from Meta before giving up.
+    let live;
+    try { live = await http.get("templates", { organization_id: orgId, name }); } catch { live = null; }
+    const liveRows = (live?.templates || []).filter((t) => t.name === name) .concat((live?.templates || []).filter((t) => t.name !== name));
+    if (!liveRows.length) {
+      console.error(`No template on this org matching "${name}", in FlowIQ or at Meta. List them with: flowiq templates status ${orgId} --live`);
+      process.exit(1);
+    }
+    const t = liveRows[0];
+    if (liveRows.length > 1 && t.name !== name) {
+      console.error(`"${name}" matches ${liveRows.length} templates at Meta — name one exactly:`);
+      for (const r of liveRows) console.error(`  ${r.name}  [${r.status}] ${r.category}`);
+      process.exit(1);
+    }
+    if (opts.json) { console.log(JSON.stringify({ source: "meta", template: t }, null, 2)); return; }
+    console.log(`${t.name}  [${t.status}] ${t.category}${t.previous_category && t.previous_category !== t.category ? ` (was ${t.previous_category})` : ""} · ${t.language}${t.parameter_format ? ` · ${t.parameter_format}` : ""}`);
+    console.log(`  org:       ${orgId}`);
+    console.log(`  source:    META ONLY — not recorded in FlowIQ's templates table (made in Meta's tools or on another WABA), so it cannot be picked in the send dialog until it is pulled in`);
+    if (t.id) console.log(`  meta id:   ${t.id}`);
+    if (t.rejected_reason && t.rejected_reason !== "NONE") console.log(`  rejected:  ${t.rejected_reason}`);
+    for (const c of t.components || []) {
+      const label = String(c.type || "").toLowerCase().padEnd(9);
+      if (c.type === "BODY" || c.type === "FOOTER") console.log(`  ${label}  ${String(c.text || "").replace(/\n/g, "\n             ")}`);
+      else if (c.type === "HEADER") console.log(`  ${label}  ${c.format}${c.text ? `: ${c.text}` : ""}`);
+      else if (c.type === "BUTTONS") for (const b of c.buttons || []) console.log(`  button     ${b.type}: ${b.text}${b.url ? ` → ${b.url}` : ""}${b.phone_number ? ` → ${b.phone_number}` : ""}`);
+      else if (c.type === "CAROUSEL") console.log(`  carousel   ${(c.cards || []).length} card(s)`);
+    }
+    console.log(`\n  The full Meta record: flowiq templates pull ${orgId}`);
+    return;
   }
   // Prefer an exact name match; otherwise if the substring is ambiguous, say so.
   let row = rows.find((r) => r.template_name === name);
@@ -444,22 +473,54 @@ export async function attempts(orgId, opts = {}) {
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
 
   const rows = resp.attempts || [];
-  if (!rows.length) {
+  const logs = resp.status_logs || [];
+  if (!rows.length && !logs.length) {
     console.log(opts.failed ? "(no failed submissions on record for this org)" : "(no template submissions on record for this org — the ledger started 21 Sep 2026)");
     return;
   }
-  console.log(`${rows.length} submission${rows.length === 1 ? "" : "s"}${opts.failed ? " (failed only)" : ""}, newest first (SAST):`);
+  // Meta's history per template, newest first: what happened AFTER submit.
+  // A category flip shows as the same status with a new category.
+  const historyOf = (name) => logs.filter((l) => l.template_name === name);
+  const describeHistory = (name, submittedCategory) => {
+    const h = historyOf(name).slice().reverse(); // oldest first
+    if (!h.length) return [];
+    const lines = [];
+    let lastCat = submittedCategory || null;
+    for (const l of h) {
+      const flipped = l.category && lastCat && l.category !== lastCat;
+      lines.push(`${sast(l.created_at)}  ${l.status}${l.category ? ` / ${l.category}` : ""}${flipped ? `  ⚠ CATEGORY MOVED ${lastCat} → ${l.category}` : ""}${l.reason ? `  (${l.reason})` : ""}`);
+      if (l.category) lastCat = l.category;
+    }
+    return lines;
+  };
+  if (rows.length) console.log(`${rows.length} submission${rows.length === 1 ? "" : "s"}${opts.failed ? " (failed only)" : ""}, newest first (SAST):`);
+  const named = new Set();
   for (const a of rows) {
     const mark = a.outcome === "submitted" ? "✓" : "✗";
     const who = a.source ? `  via ${a.source}` : "";
     console.log(`\n  ${mark} ${sast(a.created_at)}  ${a.template_name || "(unnamed)"}${a.category ? ` [${a.category}]` : ""}${who}`);
     if (a.outcome === "submitted") {
       console.log(`      submitted to Meta — id ${a.meta_template_id || "?"}, status at submit ${a.meta_status || "?"}`);
+      const hist = describeHistory(a.template_name, a.category);
+      named.add(a.template_name);
+      if (hist.length) for (const line of hist) console.log(`      then: ${line}`);
+      else console.log(`      no status webhook from Meta recorded yet (still ${a.meta_status || "PENDING"} as far as FlowIQ knows: flowiq templates status ${orgId} --live --name ${a.template_name})`);
     } else {
       console.log(`      FAILED (HTTP ${a.http_status ?? "?"}) ${a.error || ""}`);
       if (a.message && a.message !== a.error) console.log(`      ${a.message}`);
       if (a.meta_error?.error_user_msg && a.meta_error.error_user_msg !== a.message) console.log(`      Meta: ${a.meta_error.error_user_msg}`);
     }
   }
-  console.log(`\nA failed row is the reason the template is not in \`templates status\` — fix what the message names and submit again.`);
+  // Templates with Meta history but no submission row (submitted before the
+  // ledger existed, or from Meta's own tools): still worth showing when asked
+  // for by name, or when nothing else matched.
+  const orphan = [...new Set(logs.map((l) => l.template_name))].filter((n) => !named.has(n));
+  if (orphan.length && (opts.name || !rows.length)) {
+    console.log(`\nMeta status history with no submission row (older than the ledger, or submitted outside FlowIQ):`);
+    for (const n of orphan.slice(0, 20)) {
+      console.log(`\n  ${n}`);
+      for (const line of describeHistory(n, null)) console.log(`      ${line}`);
+    }
+  }
+  if (rows.length) console.log(`\nA failed row is the reason the template is not in \`templates status\` — fix what the message names and submit again.`);
 }