@flowapt/flowiq-cli 0.10.0 → 0.12.0

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/store-api.js

@@ -107,7 +107,7 @@ function banner(resp) {
 
   if (resp.truncated) {
     console.error(`⚠ TRUNCATED — ${resp.truncated_reason}. Not all records were returned.`);
-    console.error("  Narrow the query, or raise --max-pages and page through with the store's own cursor.");
+    console.error("  Narrow the query, trim records with --fields id,name,…, or raise --max-pages and page through with the store's own cursor.");
   }
   // Shopify's *Count fields return {count, precision}. `AT_LEAST` means the
   // number is a CAP (10,000), not an answer — and it is quiet enough to be read
@@ -213,6 +213,14 @@ async function send(payload, opts, sentQuery) {
 // shopify
 // ---------------------------------------------------------------------------
 
+// --fields id,name,… = the platform's own field-trim parameter (Shopify REST
+// `fields`, Woo `_fields`): the way past the 3.5 MB response cap on a fat
+// record type (Revive's 894 products stopped at 200 without it, 30 Sep 2026).
+export function withFields(query, fields, key) {
+  if (!fields) return query;
+  return { ...(query || {}), [key]: String(fields).split(",").map((s) => s.trim()).filter(Boolean).join(",") };
+}
+
 export async function shopifyGet(orgId, path, opts = {}) {
   requireOrg(orgId);
   await send({
@@ -220,7 +228,7 @@ export async function shopifyGet(orgId, path, opts = {}) {
     organization_id: orgId,
     mode: "rest",
     path,
-    query: opts.q || {},
+    query: withFields(opts.q, opts.fields, "fields"),
     all: !!opts.all,
     max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
     api_version: opts.apiVersion,
@@ -446,7 +454,7 @@ export async function wooGet(orgId, path, opts = {}) {
     mode: "rest",
     path,
     namespace: opts.namespace,
-    query: opts.q || {},
+    query: withFields(opts.q, opts.fields, "_fields"),
     all: !!opts.all,
     max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
   }, opts);

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,87 @@ 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); }
+  // A list of phone numbers against whatsapp_id / phone_number is a whole-value
+  // match by nature. The substring RPC runs one ILIKE per keyword over every
+  // contact and timed out at 77 numbers on a 95k-contact org (Kiah, 30 Sep
+  // 2026: 8.2 s measured); the exact path is an indexed IN and is what
+  // everyone meant anyway, so it is chosen for a digit-only list.
+  let exact = !!opts.exact;
+  const field = opts.field || "order_history";
+  if (!exact && !opts.all && ["whatsapp_id", "phone_number"].includes(field) && keywords.every((k) => /^\d{8,15}$/.test(k))) {
+    exact = true;
+    console.error(`(whole-number match: ${keywords.length} number(s) against ${field}; the substring search would scan every contact. Pass --any with a partial number for a substring match.)`);
+  }
   const payload = {
-    mode: "field", organization_id: orgId, field_name: opts.field || "order_history",
-    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive,
+    mode: "field", organization_id: orgId, field_name: field,
+    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive, exact,
   };
   await confirmLargeWrite(orgId, payload, opts, "Field search");
-  await runMatch("Field search", payload, opts);
+  await runMatch(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 +249,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.`);
 }