@flowapt/flowiq-cli 0.1.12 → 0.2.4

package/src/commands/custom-tools.js

@@ -129,6 +129,7 @@ export async function push(identifier, opts = {}) {
       agent_id: data.agent_id, // push back to the agent this file was pulled from
       tools: data.tools,
       dry_run: !!opts.dryRun,
+      confirm: !!opts.confirm,
     });
   } catch (e) {
     console.error(`Push failed: ${e.message}`);
@@ -142,6 +143,16 @@ export async function push(identifier, opts = {}) {
   console.log(`  tools:     ${resp.tool_count}`);
   printDiff(resp.diff);
   printWarnings(resp.warnings);
+  if (resp.requires_confirm) {
+    const d = resp.destructive || {};
+    console.log("");
+    console.log("  ⛔ DESTRUCTIVE PUSH — nothing was written:");
+    if (d.wipe_all) console.log("     this file would WIPE EVERY custom tool off the agent");
+    if (d.removed?.length) console.log(`     removes: ${d.removed.join(", ")}`);
+    if (d.disabled?.length) console.log(`     disables: ${d.disabled.join(", ")}`);
+    console.log("  Re-run with --confirm if this is intentional.");
+    process.exit(1);
+  }
   if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
 }
 

package/src/commands/keywords.js

@@ -0,0 +1,135 @@
+// `flowiq keywords pull <org_id>` / `push <slug> [--prune] [--dry-run]` / `list`.
+// Round-trips an org's keyword auto-replies (keywords + keyword_actions rows)
+// via /cli/keywords — the SAFE editing path for the attribute-write actions
+// the dashboard editor corrupts.
+//
+// Push is an ID-KEYED diff upsert: keep an `id` to update, drop the `id` to
+// create, remove an ACTION from a kept keyword to delete it. A DB keyword
+// absent from the file is left alone unless --prune. ALWAYS pull right before
+// editing (clients edit auto-reply copy live) and --dry-run before --prune.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const KW_DIR = path.resolve(process.cwd(), ".flowiq", "keywords");
+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; }
+}
+
+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(KW_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(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("keywords", { organization_id: orgId }); }
+  catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(KW_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(KW_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(`  keywords:  ${resp.keyword_count}`);
+  for (const k of resp.keywords || []) {
+    const acts = (k.keyword_actions || []).length;
+    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${k.end_date ? ` · ends ${k.end_date.slice(0, 10)}` : ""}`);
+  }
+  if (resp.has_attribute_actions) {
+    console.log("");
+    console.log("  ⚠ this org has attribute-write keyword action(s) — the dashboard editor");
+    console.log("    CANNOT render field:\"attributes\" and corrupts it on save. Edit those");
+    console.log("    keywords via this CLI only.");
+  }
+}
+
+export async function push(identifier, opts = {}) {
+  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.organization_id || !UUID_RE.test(data.organization_id)) {
+    console.error(`${filePath}: organization_id missing or invalid`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.keywords)) {
+    console.error(`${filePath}: keywords must be an array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("keywords", {
+      organization_id: data.organization_id,
+      keywords: data.keywords,
+      prune: !!opts.prune,
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  const p = resp.plan;
+  console.log(`${resp.dry_run ? "DRY RUN (nothing written) —" : "Pushed"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${data.organization_id})`);
+  console.log(`  keywords:  +${p.keywords.create} created · ~${p.keywords.update} updated · ${p.keywords.unchanged} unchanged · -${p.keywords.delete} deleted · ${p.keywords.orphan_kept} orphan(s) kept`);
+  console.log(`  actions:   +${p.actions.create} created · ~${p.actions.update} updated · ${p.actions.unchanged} unchanged · -${p.actions.delete} deleted`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
+  else if (resp.prune && p.keywords.delete) console.log(`  pruned ${p.keywords.delete} keyword(s) — re-pull to confirm.`);
+  if (!resp.dry_run && p.keywords.orphan_kept) {
+    console.log(`  note: ${p.keywords.orphan_kept} DB keyword(s) not in the file were left untouched (--prune to delete).`);
+  }
+}
+
+export async function list() {
+  let files;
+  try { files = (await fs.readdir(KW_DIR)).filter((f) => f.endsWith(".json")); }
+  catch { console.log("(no local keyword snapshots; run `keywords pull <org_id>`)"); return; }
+  if (!files.length) { console.log("(no local keyword snapshots)"); return; }
+  files.sort();
+  for (const f of files) {
+    try {
+      const d = JSON.parse(await fs.readFile(path.join(KW_DIR, f), "utf8"));
+      console.log(f);
+      console.log(`  org:       ${d.organization_name ?? "?"} (${d.organization_id ?? "?"})`);
+      console.log(`  keywords:  ${d.keyword_count ?? (Array.isArray(d.keywords) ? d.keywords.length : "?")}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "?"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/commands/org.js

@@ -31,3 +31,39 @@ export async function info(orgId, opts = {}) {
   console.log(`  provider:      ${resp.provider || "(unset → meta)"}`);
   console.log(`  active agent:  ${resp.active_whatsapp_agent || "(NONE — set one before building a prompt)"}`);
 }
+
+// `flowiq org create --name "…" [--slug …] [--owner email] [--provider meta|wati]`
+// Creates a NEW organization (org row + admin membership), mirroring the app's
+// Create Organization dialog. Owner defaults to YOU (the staff key's user) —
+// the client gets invited later via the app's member invite flow.
+export async function create(opts = {}) {
+  if (!opts.name || !opts.name.trim()) {
+    console.error("Error: --name is required.");
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("org", {
+      action: "create",
+      name: opts.name.trim(),
+      slug: opts.slug,
+      owner_email: opts.owner,
+      provider: opts.provider,
+    });
+  } catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Created "${resp.name}"`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  slug:      ${resp.slug}`);
+  console.log(`  owner:     ${resp.owner_email ?? resp.owner_id}${resp.member_added ? " (admin member)" : "  ⚠ membership insert failed — add via the app"}`);
+  console.log(`  provider:  ${resp.provider}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  flowiq agent create ${resp.id} --name "<AgentName>" --make-active`);
+  console.log(`  flowiq agent config ${resp.id} --model gpt-5.4-mini --use-settings-prompt`);
+  console.log(`  flowiq prompts pull ${resp.id}   # then edit + push`);
+}

package/src/commands/segments.js

@@ -0,0 +1,252 @@
+// `flowiq segments` (alias `seg`) — slice a contact cohort into fixed-size
+// batch tags and bulk-apply them (spec 01 / the broadcast-tag-batching
+// runbook). This command TAGS ONLY — it never sends. The send per tag is
+// `flowiq broadcast send --tag <batch-tag>` (or the dashboard broadcaster).
+//
+//   plan  <org> --tag-prefix X (--from-segment file | --ids-file file)  # exclusions → slice → plan file (no DB write)
+//   apply <org> <slug>  [--commit] [--yes]                              # append the batch tags (dry-run default)
+//   list  <org> [--prefix X]                                            # VERIFY: tag → contact count
+//   untag <org> <slug> --commit --confirm                               # ROLLBACK: remove the plan's own tags
+//
+// Golden rules encoded: exclusions (opt-out/archived/blocked) are applied
+// BEFORE slicing; apply is append-only + idempotent (`already_had` reported,
+// never double-added); untag only ever removes the plan's own tags.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { http } from "../http.js";
+
+const SEG_DIR = path.resolve(process.cwd(), ".flowiq", "segments");
+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 TAG_PREFIX_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+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; }
+}
+
+const planPath = (slug) => path.join(SEG_DIR, `${slug}.json`);
+
+async function resolvePlan(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) candidates.push(identifier);
+  else if (identifier.includes("/")) candidates.push(path.resolve(identifier));
+  else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(SEG_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) if (await fileExists(c)) return c;
+  throw new Error(`Plan file not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+/** Read the cohort ids from a christiaan/segments snapshot or a plain file. */
+async function readCohort(opts, orgId) {
+  if (!!opts.fromSegment === !!opts.idsFile) {
+    throw new Error("provide exactly one of --from-segment / --ids-file");
+  }
+  let ids = [], sourceMeta;
+  if (opts.fromSegment) {
+    const raw = JSON.parse(await fs.readFile(path.resolve(opts.fromSegment), "utf8"));
+    if (raw.organization_id && raw.organization_id !== orgId) {
+      throw new Error(`snapshot organization_id (${raw.organization_id}) ≠ the org you passed (${orgId}) — refusing (V-3)`);
+    }
+    ids = Array.isArray(raw.contact_ids) ? raw.contact_ids : [];
+    sourceMeta = { type: "segment_file", path: opts.fromSegment, input_count: ids.length, generated_at: raw.generated_at ?? null, definition: raw.definition ?? null };
+  } else {
+    const text = await fs.readFile(path.resolve(opts.idsFile), "utf8");
+    ids = text.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+    sourceMeta = { type: "ids_file", path: opts.idsFile, input_count: ids.length };
+  }
+  const bad = ids.filter((id) => !UUID_RE.test(id));
+  const good = ids.filter((id) => UUID_RE.test(id));
+  return { ids: good, badUuids: bad, sourceMeta };
+}
+
+export async function plan(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const prefix = String(opts.tagPrefix || "").trim();
+  if (!TAG_PREFIX_RE.test(prefix)) {
+    console.error(`Error: --tag-prefix must be slug-safe lowercase ([a-z0-9-], got "${prefix}").`);
+    process.exit(1);
+  }
+  const batchSize = Number(opts.batchSize ?? 75);
+  if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
+  if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
+
+  let cohort;
+  try { cohort = await readCohort(opts, orgId); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  if (cohort.badUuids.length) console.log(`⚠ skipped ${cohort.badUuids.length} non-UUID line(s) in the cohort source.`);
+  if (!cohort.ids.length) { console.error("Error: no valid contact ids in the cohort source."); process.exit(1); }
+
+  let resp;
+  try {
+    resp = await http.post("segments", {
+      mode: "plan", organization_id: orgId,
+      contact_ids: cohort.ids, include_unsafe: !!opts.includeUnsafe,
+    });
+  } catch (e) {
+    console.error(`Plan failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+  if (!resp.safe_count) { console.error("Nothing to tag — 0 safe contacts after exclusions (V-13)."); process.exit(1); }
+
+  // Slice safe_ids into contiguous batches (client-side, per the spec split).
+  const batches = [];
+  for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
+    const nn = String(batches.length + 1).padStart(2, "0");
+    batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
+  }
+
+  const slug = slugify(opts.segment || prefix, prefix);
+  const planDoc = {
+    schema_version: 1,
+    segment: slug,
+    organization_id: resp.organization_id,
+    organization_slug: slugify(resp.organization_name, resp.organization_id.slice(0, 8)),
+    tag_prefix: prefix,
+    batch_size: batchSize,
+    created_at: new Date().toISOString(),
+    source: cohort.sourceMeta,
+    exclusions: {
+      policy: opts.includeUnsafe ? "include_unsafe" : "broadcast_safe",
+      excluded_counts: Object.fromEntries(Object.entries(resp.excluded).map(([k, v]) => [k, v.length])),
+      excluded_ids: resp.excluded,
+    },
+    safe_count: resp.safe_count,
+    batch_count: batches.length,
+    batches,
+    applied: null,
+  };
+  await fs.mkdir(SEG_DIR, { recursive: true });
+  await fs.writeFile(planPath(slug), JSON.stringify(planDoc, null, 2) + "\n", "utf8");
+
+  const ex = planDoc.exclusions.excluded_counts;
+  console.log(`Wrote ${planPath(slug)}`);
+  console.log(`  org:      ${resp.organization_name}`);
+  console.log(`  input:    ${resp.input_count} · safe: ${resp.safe_count} · excluded: ${ex.not_allow_broadcast + ex.archived + ex.blocked} (allow_broadcast ${ex.not_allow_broadcast}, archived ${ex.archived}, blocked ${ex.blocked}) · not_found ${ex.not_found_in_org} · dupes ${ex.duplicate_in_input}`);
+  console.log(`  batches:  ${batches.length} × ≤${batchSize}  (${batches[0].tag} … ${batches[batches.length - 1].tag})`);
+  if (cohort.sourceMeta.generated_at) {
+    console.log(`  ⚠ tagging point-in-time ids from ${cohort.sourceMeta.generated_at} — re-derive the cohort SQL if freshness matters.`);
+  }
+  console.log("");
+  console.log(`Next: flowiq segments apply ${orgId} ${slug} [--commit]`);
+}
+
+export async function apply(orgId, identifier, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let filePath;
+  try { filePath = await resolvePlan(identifier); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  const planDoc = JSON.parse(await fs.readFile(filePath, "utf8"));
+  if (planDoc.organization_id !== orgId) {
+    console.error(`Plan is for org ${planDoc.organization_id}, you passed ${orgId} — refusing (V-10).`);
+    process.exit(1);
+  }
+  if (!Array.isArray(planDoc.batches) || !planDoc.batches.length) {
+    console.error("Plan has no batches — re-run `segments plan` (V-10).");
+    process.exit(1);
+  }
+
+  const total = planDoc.batches.reduce((a, b) => a + b.contact_ids.length, 0);
+  console.log(`Plan ${planDoc.segment}: ${planDoc.batches.length} batch tag(s), ${total} contact(s) on ${planDoc.organization_slug}.`);
+
+  // V-11: warn when the batch tags already carry members (tag reuse merges counts).
+  try {
+    const before = await http.post("segments", { mode: "list", organization_id: orgId, prefix: planDoc.tag_prefix });
+    const existing = (before.tags || []).filter((t) => Number(t.count) > 0);
+    if (existing.length) {
+      console.log(`⚠ ${existing.length} of these tags already have members (counts will MERGE):`);
+      for (const t of existing.slice(0, 5)) console.log(`    ${t.tag}: ${t.count}`);
+      if (!opts.yes && opts.commit) {
+        const a = await ask("Type y to proceed anyway: ");
+        if (a.toLowerCase() !== "y") { console.log("Aborted — nothing tagged."); process.exit(0); }
+      }
+    }
+  } catch { /* the pre-check is best-effort */ }
+
+  if (!opts.commit) {
+    console.log(`DRY RUN — would tag ${total} contact(s) across ${planDoc.batches.length} batch tag(s). Add --commit to apply.`);
+    return;
+  }
+  if (!opts.yes) {
+    const a = await ask(`Type the segment name ("${planDoc.segment}") to tag ${total} contact(s): `);
+    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);
+  }
+
+  for (const r of resp.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}`);
+
+  planDoc.applied = { at: new Date().toISOString(), tag_counts: Object.fromEntries((resp.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> …`);
+}
+
+export async function list(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.post("segments", { mode: "list", organization_id: orgId, prefix: opts.prefix }); }
+  catch (e) { console.error(`List failed: ${e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.tags?.length) { console.log(`(no tags${opts.prefix ? ` with prefix "${opts.prefix}"` : ""} on ${resp.organization_name})`); return; }
+  for (const t of resp.tags) console.log(`  ${String(t.tag).padEnd(44)} ${t.count}`);
+  console.log(`  ${"TOTAL".padEnd(44)} ${resp.total_tagged}`);
+}
+
+export async function untag(orgId, identifier, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let filePath;
+  try { filePath = await resolvePlan(identifier); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  const planDoc = JSON.parse(await fs.readFile(filePath, "utf8"));
+  if (planDoc.organization_id !== orgId) {
+    console.error(`Plan is for org ${planDoc.organization_id}, you passed ${orgId} — refusing.`);
+    process.exit(1);
+  }
+  const tags = (planDoc.batches || []).map((b) => b.tag);
+  if (!tags.length) { console.error("Plan has no batch tags."); process.exit(1); }
+
+  if (!opts.commit) {
+    console.log(`DRY RUN — would remove ${tags.length} batch tag(s): ${tags.join(", ")}. Add --commit --confirm to remove.`);
+    return;
+  }
+  if (!opts.confirm) {
+    console.error("untag is destructive — add --confirm alongside --commit (V-12).");
+    process.exit(1);
+  }
+
+  let resp;
+  try { resp = await http.post("segments", { mode: "untag", organization_id: orgId, tags }); }
+  catch (e) { console.error(`Untag failed: ${e.message}`); process.exit(1); }
+  for (const r of resp.results || []) console.log(`  ${r.tag.padEnd(40)} removed ${r.removed}`);
+  console.log(`Totals: removed ${resp.totals.removed}`);
+}

package/src/index.js

@@ -24,6 +24,9 @@ import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
 import * as customToolsCmd from "./commands/custom-tools.js";
+import * as broadcastCmd from "./commands/broadcast.js";
+import * as segmentsCmd from "./commands/segments.js";
+import * as keywordsCmd from "./commands/keywords.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
@@ -188,7 +191,14 @@ export function run(argv) {
     .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)");
+  const org = program.command("org").description("Org info (read) + create a new organization");
+  org.command("create")
+    .description("Create a NEW organization (org row + admin membership; owner defaults to you)")
+    .requiredOption("--name <name>", "organization name")
+    .option("--slug <slug>", "URL slug (default: name lowercased, spaces→dashes; must be unique)")
+    .option("--owner <email>", "owner's auth email (must already have an account; default: you)")
+    .option("--provider <p>", "meta (default) | wati")
+    .action((opts) => orgCmd.create(opts));
   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")
@@ -217,10 +227,10 @@ export function run(argv) {
     .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)
+  // agent-updates (pending client change-requests + chat context; pull + resolve)
   const au = program.command("agent-updates")
     .alias("au")
-    .description("Pull pending agent_updates + the chat context around each (read-only)");
+    .description("Pull pending agent_updates + the chat context around each; resolve a ticket with a client-facing note");
   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")
@@ -234,6 +244,14 @@ export function run(argv) {
   au.command("list")
     .description("List local agent-updates snapshots")
     .action(() => agentUpdatesCmd.list());
+  au.command("resolve <update_id>")
+    .description("Flip a client-raised ticket to resolved/declined + write the client-facing note (the client reads \"FlowIQ: <note>\")")
+    .option("--note <text>", "client-facing note (required when resolving)")
+    .option("--internal <text>", "staff-only note (never shown to the client)")
+    .option("--image <url>", "client-facing response image URL")
+    .option("--status <status>", "resolved (default) | declined", "resolved")
+    .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
+    .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
   // export (full chat history → TXT, byte-identical to the in-app export)
   const exp = program.command("export").description("Export data to local files");
@@ -320,8 +338,9 @@ export function run(argv) {
     .option("--agent <id>", "target a specific agent instead of the org's active one")
     .action((orgId, opts) => customToolsCmd.pull(orgId, opts));
   customTools.command("push <slug-or-path>")
-    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side)")
+    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side). Destructive pushes (remove/disable/wipe) are BLOCKED unless --confirm.")
     .option("--dry-run", "validate + print the per-tool diff WITHOUT writing")
+    .option("--confirm", "required when the push removes or disables tools, or sends an empty tools[]")
     .action((id, opts) => customToolsCmd.push(id, opts));
   customTools.command("enable <organization_id> <tool_name>")
     .description("Enable one custom tool by name (no round-trip)")
@@ -335,5 +354,99 @@ export function run(argv) {
     .description("List local custom-tools snapshots")
     .action(() => customToolsCmd.list());
 
+  // broadcast (CSV → per-row WhatsApp template broadcast; spec: flowiq-broadcast-send-SPEC)
+  const broadcast = program.command("broadcast")
+    .alias("bc")
+    .description("Send an APPROVED WhatsApp template to every row of a CSV (per-row column→param mapping)");
+  broadcast.command("map <organization_id>")
+    .description("Introspect the template + CSV and build/refresh the saved mapping interactively (no send)")
+    .requiredOption("--template <name>", "approved Meta template name")
+    .requiredOption("--csv <file>", "path to the recipients CSV")
+    .option("--campaign <name>", "campaign id / config file slug (default: CSV filename)")
+    .option("--force-remap", "ignore the saved mapping and rebuild interactively")
+    .action((orgId, opts) => broadcastCmd.map(orgId, opts));
+  broadcast.command("preview <organization_id>")
+    .description("Dry-run render of sample rows (exact message text + resolved button URL); never sends")
+    .option("--template <name>", "template (default: from the saved campaign)")
+    .option("--csv <file>", "CSV (default: from the saved campaign)")
+    .option("--campaign <name>", "campaign id / config file slug")
+    .option("--rows <n>", "how many sample rows to render", "3")
+    .action((orgId, opts) => broadcastCmd.preview(orgId, opts));
+  broadcast.command("send <organization_id>")
+    .description("Run the full pipeline. DRY-RUN by default; --commit sends (type the campaign name to confirm). Recipients from --csv OR --tag.")
+    .requiredOption("--template <name>", "approved Meta template name")
+    .option("--csv <file>", "path to the recipients CSV (per-row values)")
+    .option("--tag <tag>", "send to every broadcast-safe contact carrying this tag (e.g. a segments batch tag)")
+    .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
+    .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
+    .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
+    .option("--commit", "actually send (omit to dry-run)")
+    .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
+    .option("--force-remap", "ignore the saved mapping and rebuild interactively")
+    .option("--illegal-chars <mode>", "reject | strip — newlines/tabs/4+ spaces in values (Meta #100)", "reject")
+    .option("--rate <n>", "max messages per second (hard cap 10)", "8")
+    .option("--upsert-batch <n>", "contacts per upsert call (max 4000)", "4000")
+    .option("--skip-upsert", "assume contacts already exist; skip the upsert stage")
+    .option("--limit <n>", "only process the first N valid rows (smoke test)")
+    .option("--resume", "continue from the existing status log instead of starting fresh")
+    .option("--retry-failed", "with --resume: also re-attempt rows previously marked failed")
+    .action((orgId, opts) => broadcastCmd.send(orgId, opts));
+  broadcast.command("resume <organization_id>")
+    .description("Continue an interrupted campaign: only unsent rows from the status log; ambiguous in-flight rows are NEVER auto-resent")
+    .requiredOption("--campaign <name>", "campaign id / config file slug")
+    .option("--commit", "actually send (omit to dry-run the remaining rows)")
+    .option("--yes", "skip the confirm gate")
+    .option("--rate <n>", "max messages per second (hard cap 10)", "8")
+    .option("--retry-failed", "also re-attempt rows previously marked failed (confirmed failures only)")
+    .action((orgId, opts) => broadcastCmd.resume(orgId, opts));
+  broadcast.command("list")
+    .description("List local campaigns + sent counts")
+    .action(() => broadcastCmd.list());
+
+  // segments (cohort → batch tags; tags only — the send is `broadcast send --tag`)
+  const segments = program.command("segments")
+    .alias("seg")
+    .description("Slice a contact cohort into fixed-size batch tags and bulk-apply them (broadcast batching)");
+  segments.command("plan <organization_id>")
+    .description("Ingest a cohort id list, apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .requiredOption("--tag-prefix <name>", "campaign tag stem; batches become <prefix>-batch-NN")
+    .option("--from-segment <path>", "a segments snapshot JSON (uses its contact_ids[])")
+    .option("--ids-file <path>", "a plain newline/CSV file of contact UUIDs")
+    .option("--batch-size <n>", "contacts per batch tag", "75")
+    .option("--segment <name>", "plan file slug (default: the tag prefix)")
+    .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
+    .action((orgId, opts) => segmentsCmd.plan(orgId, opts));
+  segments.command("apply <organization_id> <slug-or-path>")
+    .description("Append the plan's batch tags to their contacts. DRY-RUN by default; --commit to write (append-only, idempotent)")
+    .option("--commit", "actually write the tags")
+    .option("--yes", "skip the type-the-segment-name confirm gate")
+    .action((orgId, id, opts) => segmentsCmd.apply(orgId, id, opts));
+  segments.command("list <organization_id>")
+    .description("VERIFY: print tag → contact count (read-only)")
+    .option("--prefix <substr>", "only tags starting with this prefix (recommended)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => segmentsCmd.list(orgId, opts));
+  segments.command("untag <organization_id> <slug-or-path>")
+    .description("ROLLBACK: remove the plan's own batch tags. Destructive — needs --commit AND --confirm")
+    .option("--commit", "actually remove (omit to dry-run)")
+    .option("--confirm", "required alongside --commit")
+    .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
+
+  // keywords (org auto-reply engine: keywords + keyword_actions; id-keyed diff push)
+  const keywords = program.command("keywords")
+    .alias("kw")
+    .description("Round-trip an org's keyword auto-replies + actions (the safe editor for attribute-write actions)");
+  keywords.command("pull <organization_id>")
+    .description("Fetch every keyword + its actions into a local JSON file (ALWAYS pull right before editing)")
+    .action((orgId) => keywordsCmd.pull(orgId));
+  keywords.command("push <slug-or-path>")
+    .description("Apply the local JSON: id-keyed UPSERT (keep ids to update, drop ids to create). --prune also DELETES keywords absent from the file.")
+    .option("--prune", "also delete DB keywords whose id is not in the file (destructive; cascade-deletes their actions)")
+    .option("--dry-run", "compute + print the plan without writing (ALWAYS before --prune)")
+    .action((id, opts) => keywordsCmd.push(id, opts));
+  keywords.command("list")
+    .description("List local keyword snapshots")
+    .action(() => keywordsCmd.list());
+
   program.parseAsync(argv);
 }