conduyt 1.3.0 → 1.4.0

package/dist/client.js

@@ -20,7 +20,14 @@ export class ConduytClient {
         const text = await res.text();
         const json = text ? safeParse(text) : null;
         if (!res.ok) {
-            const msg = json?.error || res.statusText || `HTTP ${res.status}`;
+            // Preserve structured non-2xx bodies: several endpoints return the data
+            // a caller needs to proceed IN the error body (e.g. custom-field delete
+            // 409 carries valueCount/dependencyCount for the --confirm flow).
+            // Reducing those to statusText would strand the user.
+            const structured = json && typeof json === "object" && !json.error
+                ? JSON.stringify(json)
+                : null;
+            const msg = json?.error || structured || res.statusText || `HTTP ${res.status}`;
             throw new Error(`Conduyt API ${res.status}: ${msg}`);
         }
         return json;
@@ -37,6 +44,85 @@ export class ConduytClient {
     del(path) {
         return this.request("DELETE", path);
     }
+    // Stream `ai chat`'s text/event-stream response to stdout as clean answer
+    // text. The server frames SSE records as `data: {"text":"..."}\n\n`, ends
+    // with `data: [DONE]\n\n`, and reports in-stream failures as
+    // `data: {"error":"..."}\n\n` — so we parse events (buffering across chunk
+    // splits), print only the text deltas, stop cleanly on [DONE], and THROW on
+    // an error event so the command exits non-zero instead of "succeeding" with
+    // raw protocol noise.
+    async stream(method, path, body) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok || !res.body) {
+            const text = await res.text();
+            const json = text ? safeParse(text) : null;
+            const msg = json?.error || res.statusText || `HTTP ${res.status}`;
+            throw new Error(`Conduyt API ${res.status}: ${msg}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let wroteAny = false;
+        const handleEvent = (payload) => {
+            if (payload === "[DONE]")
+                return "done";
+            const parsed = safeParse(payload);
+            if (parsed && typeof parsed === "object") {
+                const rec = parsed;
+                if (typeof rec.error === "string" && rec.error) {
+                    if (wroteAny)
+                        process.stdout.write("\n");
+                    throw new Error(`AI stream error: ${rec.error}`);
+                }
+                if (typeof rec.text === "string" && rec.text) {
+                    process.stdout.write(rec.text);
+                    wroteAny = true;
+                }
+            }
+            return undefined;
+        };
+        const drainBuffer = () => {
+            // SSE events are separated by a blank line; fields we care about are
+            // `data: <payload>` lines (multi-line data joins with \n per spec).
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+                const rawEvent = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                const dataLines = rawEvent
+                    .split("\n")
+                    .filter((l) => l.startsWith("data:"))
+                    .map((l) => l.slice(5).replace(/^ /, ""));
+                if (dataLines.length === 0)
+                    continue;
+                if (handleEvent(dataLines.join("\n")) === "done")
+                    return "done";
+            }
+            return undefined;
+        };
+        outer: for (;;) {
+            const { done, value } = await reader.read();
+            if (value) {
+                buffer += decoder.decode(value, { stream: true });
+                if (drainBuffer() === "done")
+                    break outer;
+            }
+            if (done)
+                break;
+        }
+        buffer += decoder.decode();
+        drainBuffer();
+        if (wroteAny)
+            process.stdout.write("\n");
+    }
 }
 function safeParse(text) {
     try {

package/dist/index.js

@@ -99,6 +99,34 @@ contacts
         Object.assign(body, jsonArg(opts.json, "--json"));
     return client.post("/api/v1/contacts", body);
 }));
+contacts
+    .command("update <id>")
+    .description("Update a contact (PATCH — only the fields you pass change)")
+    .option("--first <name>", "first name")
+    .option("--last <name>", "last name")
+    .option("--email <email>", "email")
+    .option("--phone <phone>", "phone")
+    .option("--company <company>", "company name (auto-creates/links a company; pass '' to clear)")
+    .option("--json <json>", "full JSON body, merged over the flags above (for any field)")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "contact id");
+    const body = {};
+    if (opts.first !== undefined)
+        body.firstName = opts.first;
+    if (opts.last !== undefined)
+        body.lastName = opts.last;
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.company !== undefined)
+        body.company = opts.company;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/contacts/${encodeURIComponent(id)}`, body);
+}));
 contacts
     .command("delete <id>")
     .description("Delete a contact by id (soft-delete; retained for audit, the contact's deals are unaffected)")
@@ -272,6 +300,57 @@ deals
     assertFiniteValue(body.value);
     return client.post("/api/v1/deals", body);
 }));
+deals
+    .command("get <id>")
+    .description("Get a single deal by id")
+    .action(run(async (client, id) => {
+    assertUuid(id, "deal id");
+    return client.get(`/api/v1/deals/${encodeURIComponent(id)}`);
+}));
+deals
+    .command("update <id>")
+    .description("Update a deal (PATCH — only the fields you pass change). --stage moves the deal (won/lost status auto-derives from the target stage's flags)")
+    .option("--title <title>", "deal title")
+    .option("--value <n>", "deal value (number)")
+    .option("--currency <code>", "ISO currency, e.g. GBP")
+    .option("--stage <name-or-uuid>", "move to this stage — accepts a stage name (resolved via /automations/resolve) or a stage UUID")
+    .option("--pipeline <id>", "move to this pipeline UUID")
+    .option("--contact <id>", "primary contact UUID")
+    .option("--status <status>", "explicit status (open|won|lost); overrides the status auto-derived from --stage")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "deal id");
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.value !== undefined) {
+        const trimmed = opts.value.trim();
+        const n = Number(trimmed);
+        if (trimmed === "" || !Number.isFinite(n)) {
+            throw new Error("--value must be a finite number.");
+        }
+        body.value = n;
+    }
+    if (opts.currency !== undefined)
+        body.currency = opts.currency;
+    if (opts.pipeline !== undefined)
+        body.pipelineId = opts.pipeline;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.stage !== undefined) {
+        if (opts.stage.trim() === "")
+            throw new Error("--stage was provided but is blank. Omit it or pass a stage name/UUID.");
+        body.stageId = await resolveStageId(client, opts.stage);
+    }
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    assertFiniteValue(body.value);
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/deals/${encodeURIComponent(id)}`, body);
+}));
 deals
     .command("delete <id>")
     .description("Delete a deal by id (soft-delete; drops out of lists/boards and pipeline totals, retained for audit)")
@@ -335,7 +414,9 @@ program
 // ---- insights ----
 program
     .command("insights <type>")
-    .description("Run an AI insight query (e.g. summary, forecast)")
+    .description("Run an AI insight query. Types: sms_drip_status, sms_responses_untouched, " +
+    "agent_followups, pipeline_health, email_performance, smart_view_summary, " +
+    "team_activity, contact_import_history")
     .option("--input <json>", "JSON payload to send with the request")
     .action(run(async (client, type, opts) => {
     let extra = {};
@@ -347,7 +428,10 @@ program
             fail("--input must be valid JSON");
         }
     }
-    return client.post("/api/v1/ai/insights", { type, ...extra });
+    // The /ai/insights endpoint reads the insight name from `query`, not
+    // `type` — sending `type` returned "Unsupported query type" for every
+    // call, so the CLI's insights command was fully broken.
+    return client.post("/api/v1/ai/insights", { query: type, ...extra });
 }));
 // ---- users (team members) ----
 const users = program.command("users").description("Manage team members");
@@ -436,6 +520,1030 @@ customFields
     assertOptionsShape(body.options);
     return client.post("/api/v1/custom-fields", body);
 }));
+// ---- tasks ----
+const tasks = program.command("tasks").description("Manage tasks");
+tasks
+    .command("list")
+    .description("List tasks")
+    .option("--status <status>", "filter by status, e.g. todo|in_progress|done")
+    .option("--priority <priority>", "filter by priority, e.g. low|medium|high|urgent")
+    .option("--assigned <id>", "filter by assignee user UUID")
+    .option("--contact <id>", "filter by contact UUID")
+    .option("--deal <id>", "filter by deal UUID")
+    .option("--search <q>", "search title/description")
+    .option("--tab <tab>", "my_tasks | all | completed")
+    .option("--overdue", "only overdue, not-done tasks")
+    .option("--due-from <date>", "due on/after this date")
+    .option("--due-to <date>", "due on/before this date")
+    .option("--sort <field>", "sort field (e.g. dueDate, priority, createdAt)")
+    .option("--order <dir>", "asc | desc")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/tasks${buildQuery({
+    status: opts.status,
+    priority: opts.priority,
+    assigned_to: opts.assigned,
+    contact_id: opts.contact,
+    deal_id: opts.deal,
+    search: opts.search,
+    tab: opts.tab,
+    overdue: opts.overdue ? "true" : undefined,
+    dueFrom: opts.dueFrom,
+    dueTo: opts.dueTo,
+    sort: opts.sort,
+    order: opts.order,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+tasks
+    .command("get <id>")
+    .description("Get a single task by id")
+    .action(run(async (client, id) => {
+    assertUuid(id, "task id");
+    return client.get(`/api/v1/tasks/${encodeURIComponent(id)}`);
+}));
+tasks
+    .command("create")
+    .description("Create a task (--assigned accepts a user UUID, or the magic strings @me / @owner)")
+    .option("--title <title>", "task title (required)")
+    .option("--description <text>", "description")
+    .option("--status <status>", "todo|in_progress|done (default todo)")
+    .option("--priority <priority>", "low|medium|high|urgent (default medium)")
+    .option("--due <date>", "due date (ISO or date string)")
+    .option("--assigned <id>", "assignee user UUID, or @me / @owner")
+    .option("--contact <id>", "link to contact UUID")
+    .option("--deal <id>", "link to deal UUID")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.priority !== undefined)
+        body.priority = opts.priority;
+    if (opts.due !== undefined)
+        body.dueDate = opts.due;
+    if (opts.assigned !== undefined)
+        body.assignedTo = opts.assigned;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.deal !== undefined)
+        body.dealId = opts.deal;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/tasks", body);
+}));
+tasks
+    .command("update <id>")
+    .description("Update a task (PATCH — only the fields you pass change)")
+    .option("--title <title>", "task title")
+    .option("--description <text>", "description")
+    .option("--status <status>", "todo|in_progress|done")
+    .option("--priority <priority>", "low|medium|high|urgent")
+    .option("--due <date>", "due date")
+    .option("--assigned <id>", "assignee user UUID, or @me / @owner")
+    .option("--contact <id>", "link to contact UUID")
+    .option("--deal <id>", "link to deal UUID")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "task id");
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.priority !== undefined)
+        body.priority = opts.priority;
+    if (opts.due !== undefined)
+        body.dueDate = opts.due;
+    if (opts.assigned !== undefined)
+        body.assignedTo = opts.assigned;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.deal !== undefined)
+        body.dealId = opts.deal;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/tasks/${encodeURIComponent(id)}`, body);
+}));
+tasks
+    .command("complete <id>")
+    .description("Mark a task done (PATCH status=done)")
+    .action(run(async (client, id) => {
+    assertUuid(id, "task id");
+    return client.patch(`/api/v1/tasks/${encodeURIComponent(id)}`, { status: "done" });
+}));
+tasks
+    .command("delete <id>")
+    .description("Delete a task by id (hard delete)")
+    .action(run(async (client, id) => {
+    assertUuid(id, "task id");
+    return client.del(`/api/v1/tasks/${encodeURIComponent(id)}`);
+}));
+// ---- messages / conversations ----
+const messages = program.command("messages").description("Send and read messages");
+messages
+    .command("list")
+    .description("List logged messages")
+    .option("--contact <id>", "filter by contact UUID")
+    .option("--channel <channel>", "sms | email")
+    .option("--direction <direction>", "inbound | outbound")
+    .option("--status <status>", "filter by status")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/messages${buildQuery({
+    contactId: opts.contact,
+    channel: opts.channel,
+    direction: opts.direction,
+    status: opts.status,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+messages
+    .command("send")
+    .description("Log/create a message (POST /messages). NOTE: outbound SMS is rejected here — use `messages send-sms` for real SMS delivery")
+    .option("--contact <id>", "contact UUID (required)")
+    .option("--channel <channel>", "sms | email (required)")
+    .option("--direction <direction>", "inbound | outbound (required)")
+    .option("--body <text>", "message body (required)")
+    .option("--subject <subject>", "subject (email)")
+    .option("--from <from>", "from number/email")
+    .option("--to <to>", "to number/email")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.channel !== undefined)
+        body.channel = opts.channel;
+    if (opts.direction !== undefined)
+        body.direction = opts.direction;
+    if (opts.body !== undefined)
+        body.body = opts.body;
+    if (opts.subject !== undefined)
+        body.subject = opts.subject;
+    if (opts.from !== undefined) {
+        if (opts.channel === "email")
+            body.fromEmail = opts.from;
+        else
+            body.fromNumber = opts.from;
+    }
+    if (opts.to !== undefined) {
+        if (opts.channel === "email")
+            body.toEmail = opts.to;
+        else
+            body.toNumber = opts.to;
+    }
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/messages", body);
+}));
+messages
+    .command("send-sms")
+    .description("Send an outbound SMS via Twilio (POST /messages/sms/send)")
+    .option("--contact <id>", "contact UUID (required)")
+    .option("--body <text>", "SMS body, 1-1600 chars (required)")
+    .option("--from <number>", "from number — must be an account-owned Twilio number/agent DID")
+    .option("--provider <id>", "smsProviderId UUID")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.body !== undefined)
+        body.body = opts.body;
+    if (opts.from !== undefined)
+        body.fromNumber = opts.from;
+    if (opts.provider !== undefined)
+        body.smsProviderId = opts.provider;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/messages/sms/send", body);
+}));
+messages
+    .command("conversations")
+    .description("List conversation threads")
+    .option("--channel <channel>", "sms | email")
+    .option("--search <q>", "search query")
+    .option("--status <status>", "filter by conversation status")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/conversations${buildQuery({
+    channel: opts.channel,
+    search: opts.search,
+    status: opts.status,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+messages
+    .command("conversation <contactId>")
+    .description("Read a contact's conversation (messages + notes)")
+    .option("--channel <channel>", "sms | email")
+    .option("--cursor <messageId>", "paginate backward from this message id")
+    .option("--around <messageId>", "center the window on this message id")
+    .option("--limit <n>", "messages per page (per_page)")
+    .action(run(async (client, contactId, opts) => {
+    assertUuid(contactId, "contact id");
+    return client.get(`/api/v1/conversations/${encodeURIComponent(contactId)}${buildQuery({
+        channel: opts.channel,
+        cursor: opts.cursor,
+        around: opts.around,
+        per_page: opts.limit,
+    })}`);
+}));
+// ---- appointments ----
+const appointments = program.command("appointments").description("Manage appointments");
+appointments
+    .command("list")
+    .description("List appointments")
+    .option("--status <status>", "filter by status")
+    .option("--calendar <id>", "filter by calendar UUID")
+    .option("--contact <id>", "filter by contact UUID")
+    .option("--assigned <id>", "filter by assignee user UUID")
+    .option("--booking-page <id>", "filter by booking page UUID")
+    .option("--from <date>", "start of date range")
+    .option("--to <date>", "end of date range")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/appointments${buildQuery({
+    status: opts.status,
+    calendar_id: opts.calendar,
+    contact_id: opts.contact,
+    assigned_to: opts.assigned,
+    booking_page_id: opts.bookingPage,
+    from: opts.from,
+    to: opts.to,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+appointments
+    .command("get <id>")
+    .description("Get a single appointment by id")
+    .action(run(async (client, id) => {
+    assertUuid(id, "appointment id");
+    return client.get(`/api/v1/appointments/${encodeURIComponent(id)}`);
+}));
+appointments
+    .command("create")
+    .description("Create an appointment. --start/--end must be ISO-8601 WITH a timezone offset (e.g. 2026-07-10T15:00:00-07:00)")
+    .option("--title <title>", "title (required)")
+    .option("--start <iso>", "start time, ISO-8601 with tz offset (required)")
+    .option("--end <iso>", "end time, ISO-8601 with tz offset (required)")
+    .option("--description <text>", "description")
+    .option("--calendar <id>", "calendar UUID")
+    .option("--contact <id>", "contact UUID")
+    .option("--assigned <id>", "assignee user UUID")
+    .option("--location <location>", "location")
+    .option("--status <status>", "status (default confirmed)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.start !== undefined)
+        body.startTime = opts.start;
+    if (opts.end !== undefined)
+        body.endTime = opts.end;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.calendar !== undefined)
+        body.calendarId = opts.calendar;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.assigned !== undefined)
+        body.assignedTo = opts.assigned;
+    if (opts.location !== undefined)
+        body.location = opts.location;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/appointments", body);
+}));
+appointments
+    .command("update <id>")
+    .description("Update an appointment (PATCH). --start/--end reschedule; ISO-8601 with tz offset")
+    .option("--title <title>", "title")
+    .option("--start <iso>", "start time, ISO-8601 with tz offset")
+    .option("--end <iso>", "end time, ISO-8601 with tz offset")
+    .option("--description <text>", "description")
+    .option("--location <location>", "location")
+    .option("--status <status>", "status (e.g. confirmed, cancelled)")
+    .option("--assigned <id>", "assignee user UUID (or empty to unassign)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "appointment id");
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.start !== undefined)
+        body.startTime = opts.start;
+    if (opts.end !== undefined)
+        body.endTime = opts.end;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.location !== undefined)
+        body.location = opts.location;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.assigned !== undefined)
+        body.assignedTo = opts.assigned;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/appointments/${encodeURIComponent(id)}`, body);
+}));
+appointments
+    .command("cancel <id>")
+    .description("Cancel an appointment (soft-cancel; sets status=cancelled)")
+    .action(run(async (client, id) => {
+    assertUuid(id, "appointment id");
+    return client.del(`/api/v1/appointments/${encodeURIComponent(id)}`);
+}));
+// ---- calendars ----
+const calendars = program.command("calendars").description("Manage calendars");
+calendars
+    .command("list")
+    .description("List calendars")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/calendars${buildQuery({ page: opts.page, per_page: opts.limit })}`)));
+calendars
+    .command("create")
+    .description("Create a calendar")
+    .option("--name <name>", "calendar name (required)")
+    .option("--description <text>", "description")
+    .option("--timezone <tz>", "IANA timezone (default America/Los_Angeles)")
+    .option("--default", "make this the default calendar")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.timezone !== undefined)
+        body.timezone = opts.timezone;
+    if (opts.default)
+        body.isDefault = true;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/calendars", body);
+}));
+// ---- automations (the "AI builds a workflow" loop) ----
+const automations = program.command("automations").description("Build and run automations/workflows");
+automations
+    .command("list")
+    .description("List automations")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/automations${buildQuery({ page: opts.page, per_page: opts.limit })}`)));
+automations
+    .command("schema")
+    .description("Get the node/field/operator schema catalog (node types, action rules, graph shape)")
+    .action(run(async (client) => client.get("/api/v1/automations/schema")));
+automations
+    .command("resolve")
+    .description("Resolve human-readable names to UUIDs. Pass comma lists via flags and/or a full JSON body")
+    .option("--tags <list>", "comma-separated tag names")
+    .option("--pipelines <list>", "comma-separated pipeline names")
+    .option("--stages <list>", "comma-separated stage names")
+    .option("--users <list>", "comma-separated user names or emails")
+    .option("--json <json>", "full JSON body (e.g. {\"templates\":[\"Welcome\"]}), merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.tags !== undefined)
+        body.tags = csvArg(opts.tags, "--tags");
+    if (opts.pipelines !== undefined)
+        body.pipelines = csvArg(opts.pipelines, "--pipelines");
+    if (opts.stages !== undefined)
+        body.stages = csvArg(opts.stages, "--stages");
+    if (opts.users !== undefined)
+        body.users = csvArg(opts.users, "--users");
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to resolve. Pass --tags/--pipelines/--stages/--users or --json.");
+    return client.post("/api/v1/automations/resolve", body);
+}));
+automations
+    .command("validate")
+    .description("Validate a workflow graph before saving. Provide the body via --json or --file (needs triggerEvent + graph)")
+    .option("--json <json>", "full request body as JSON")
+    .option("--file <path>", "read the request body from a JSON file")
+    .action(run(async (client, opts) => client.post("/api/v1/automations/validate", bodyFromJsonOrFile(opts))));
+automations
+    .command("import")
+    .description("Create a workflow (with optional name resolution). Provide the body via --json or --file (needs name + triggerEvent + graph)")
+    .option("--json <json>", "full request body as JSON")
+    .option("--file <path>", "read the request body from a JSON file")
+    .option("--resolve-names", "set resolveNames=true so name fields in node configs are converted to ids")
+    .action(run(async (client, opts) => {
+    const body = bodyFromJsonOrFile(opts);
+    if (opts.resolveNames)
+        body.resolveNames = true;
+    return client.post("/api/v1/automations/import", body);
+}));
+automations
+    .command("dry-run <id>")
+    .description("Test a workflow without side effects")
+    .option("--contact <id>", "run against this contact UUID")
+    .option("--appointment <id>", "seed with this appointment UUID")
+    .option("--source <source>", "draft | published (default draft)")
+    .option("--mode <mode>", "single | all-paths (default single)")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "automation id");
+    const body = {};
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.appointment !== undefined)
+        body.appointmentId = opts.appointment;
+    return client.post(`/api/v1/automations/${encodeURIComponent(id)}/dry-run${buildQuery({ source: opts.source, mode: opts.mode })}`, body);
+}));
+automations
+    .command("publish <id>")
+    .description("Publish a draft workflow to live")
+    .action(run(async (client, id) => {
+    assertUuid(id, "automation id");
+    return client.post(`/api/v1/automations/${encodeURIComponent(id)}/publish`, {});
+}));
+automations
+    .command("step-logs [id]")
+    .description("Execution step logs. With an automation id, logs for that one; without, account-wide (filter with --automation)")
+    .option("--automation <id>", "account-wide: filter to this automation UUID (ignored when [id] is given)")
+    .option("--status <status>", "filter by step status")
+    .option("--action-type <type>", "filter by action type")
+    .option("--search <q>", "fuzzy search on contact / automation name")
+    .option("--date-from <iso>", "startedAt >= this")
+    .option("--date-to <iso>", "startedAt <= this")
+    .option("--limit <n>", "max results (default 50, max 200)")
+    .option("--offset <n>", "pagination offset")
+    .action(run(async (client, id, opts) => {
+    if (id !== undefined)
+        assertUuid(id, "automation id");
+    const q = buildQuery({
+        automationId: id === undefined ? opts.automation : undefined,
+        status: opts.status,
+        actionType: opts.actionType,
+        search: opts.search,
+        dateFrom: opts.dateFrom,
+        dateTo: opts.dateTo,
+        limit: opts.limit,
+        offset: opts.offset,
+    });
+    const path = id !== undefined
+        ? `/api/v1/automations/${encodeURIComponent(id)}/step-logs${q}`
+        : `/api/v1/automations/step-logs${q}`;
+    return client.get(path);
+}));
+// ---- companies ----
+const companies = program.command("companies").description("Manage companies");
+companies
+    .command("list")
+    .description("List companies")
+    .option("--search <q>", "search by name/domain")
+    .option("--industry <industry>", "filter by industry")
+    .option("--size <size>", "filter by size band (e.g. 11-50)")
+    .option("--sort <field>", "createdAt|updatedAt|name|healthScore|annualRevenue|totalValue|dealCount")
+    .option("--order <dir>", "asc | desc")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/companies${buildQuery({
+    search: opts.search,
+    industry: opts.industry,
+    size: opts.size,
+    sort: opts.sort,
+    order: opts.order,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+companies
+    .command("get <id>")
+    .description("Get a single company by id")
+    .action(run(async (client, id) => {
+    assertUuid(id, "company id");
+    return client.get(`/api/v1/companies/${encodeURIComponent(id)}`);
+}));
+companies
+    .command("create")
+    .description("Create a company")
+    .option("--name <name>", "company name (required)")
+    .option("--domain <domain>", "domain")
+    .option("--industry <industry>", "industry")
+    .option("--size <size>", "size band: 1-10|11-50|51-200|201-500|501-1000|1001+")
+    .option("--website <url>", "website URL")
+    .option("--phone <phone>", "phone")
+    .option("--city <city>", "city")
+    .option("--state <state>", "state")
+    .option("--country <cc>", "ISO-3166 alpha-2 country code (default US)")
+    .option("--description <text>", "description")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.domain !== undefined)
+        body.domain = opts.domain;
+    if (opts.industry !== undefined)
+        body.industry = opts.industry;
+    if (opts.size !== undefined)
+        body.size = opts.size;
+    if (opts.website !== undefined)
+        body.website = opts.website;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.city !== undefined)
+        body.city = opts.city;
+    if (opts.state !== undefined)
+        body.state = opts.state;
+    if (opts.country !== undefined)
+        body.country = opts.country;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/companies", body);
+}));
+companies
+    .command("update <id>")
+    .description("Update a company (PATCH — only the fields you pass change)")
+    .option("--name <name>", "company name")
+    .option("--domain <domain>", "domain")
+    .option("--industry <industry>", "industry")
+    .option("--size <size>", "size band")
+    .option("--website <url>", "website URL")
+    .option("--phone <phone>", "phone")
+    .option("--city <city>", "city")
+    .option("--state <state>", "state")
+    .option("--country <cc>", "ISO-3166 alpha-2 country code")
+    .option("--description <text>", "description")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "company id");
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.domain !== undefined)
+        body.domain = opts.domain;
+    if (opts.industry !== undefined)
+        body.industry = opts.industry;
+    if (opts.size !== undefined)
+        body.size = opts.size;
+    if (opts.website !== undefined)
+        body.website = opts.website;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.city !== undefined)
+        body.city = opts.city;
+    if (opts.state !== undefined)
+        body.state = opts.state;
+    if (opts.country !== undefined)
+        body.country = opts.country;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/companies/${encodeURIComponent(id)}`, body);
+}));
+// ---- tags ----
+// ---- saved filters (personal, Velocify-style) ----
+const savedFilters = program
+    .command("saved-filters")
+    .description("Manage YOUR personal saved contact filters (the web app's Saved dropdown; requires the 'saved-filters' key scope)");
+savedFilters
+    .command("list")
+    .description("List your saved filters")
+    .option("--entity <type>", "entity type (default contact)")
+    .action(run(async (client, opts) => client.get(`/api/v1/saved-filters${buildQuery({ entity_type: opts.entity })}`)));
+savedFilters
+    .command("create")
+    .description("Save a named filter (grouped payload via --filters JSON)")
+    .option("--name <name>", "display name (required, unique per user, max 60 chars)")
+    .option("--filters <json>", `grouped filter payload JSON, e.g. [{"conjunction":"AND","rules":[{"field":"source","operator":"equals","value":"facebook"}]}]`)
+    .option("--sort-field <field>", "sort field (default createdAt)")
+    .option("--sort-order <dir>", "asc | desc (default desc)")
+    .option("--entity <type>", "entity type (default contact)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.filters !== undefined)
+        body.filters = jsonArrayArg(opts.filters, "--filters");
+    if (opts.sortField !== undefined)
+        body.sortField = opts.sortField;
+    if (opts.sortOrder !== undefined)
+        body.sortOrder = opts.sortOrder;
+    if (opts.entity !== undefined)
+        body.entityType = opts.entity;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    // A --json merge can clobber filters with a non-array; re-assert the
+    // shape after ALL merges so a malformed payload fails locally.
+    if (body.filters !== undefined && !Array.isArray(body.filters)) {
+        throw new Error("filters must be a JSON ARRAY (grouped payload or flat rules).");
+    }
+    return client.post("/api/v1/saved-filters", body);
+}));
+savedFilters
+    .command("update <id>")
+    .description("Rename a saved filter or replace its filters/sort (owner-only)")
+    .option("--name <name>", "new display name")
+    .option("--filters <json>", "grouped filter payload JSON")
+    .option("--sort-field <field>", "sort field")
+    .option("--sort-order <dir>", "asc | desc")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "saved filter id");
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.filters !== undefined)
+        body.filters = jsonArrayArg(opts.filters, "--filters");
+    if (opts.sortField !== undefined)
+        body.sortField = opts.sortField;
+    if (opts.sortOrder !== undefined)
+        body.sortOrder = opts.sortOrder;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    // Same post-merge shape assertion as create — see above.
+    if (body.filters !== undefined && !Array.isArray(body.filters)) {
+        throw new Error("filters must be a JSON ARRAY (grouped payload or flat rules).");
+    }
+    return client.patch(`/api/v1/saved-filters/${encodeURIComponent(id)}`, body);
+}));
+savedFilters
+    .command("delete <id>")
+    .description("Delete one of your saved filters (owner-only)")
+    .action(run(async (client, id) => {
+    assertUuid(id, "saved filter id");
+    return client.del(`/api/v1/saved-filters/${encodeURIComponent(id)}`);
+}));
+const tags = program.command("tags").description("Manage tags");
+tags
+    .command("list")
+    .description("List tags")
+    .option("--name <name>", "exact (case-insensitive) name match")
+    .option("--search <q>", "name contains")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/tags${buildQuery({ name: opts.name, search: opts.search, page: opts.page, per_page: opts.limit })}`)));
+tags
+    .command("create")
+    .description("Create a tag")
+    .option("--name <name>", "tag name (required)")
+    .option("--color <hex>", "hex color (default #6B7280)")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.color !== undefined)
+        body.color = opts.color;
+    return client.post("/api/v1/tags", body);
+}));
+// ---- notes ----
+const notes = program.command("notes").description("Manage notes");
+notes
+    .command("list")
+    .description("List notes (filter by contact or deal)")
+    .option("--contact <id>", "filter by contact UUID")
+    .option("--deal <id>", "filter by deal UUID")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/notes${buildQuery({ contact_id: opts.contact, deal_id: opts.deal, page: opts.page, per_page: opts.limit })}`)));
+notes
+    .command("create")
+    .description("Create a note on a contact and/or deal")
+    .option("--body <text>", "note body (required)")
+    .option("--contact <id>", "attach to contact UUID")
+    .option("--deal <id>", "attach to deal UUID")
+    .option("--pinned", "pin the note")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.body !== undefined)
+        body.body = opts.body;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.deal !== undefined)
+        body.dealId = opts.deal;
+    if (opts.pinned)
+        body.isPinned = true;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/notes", body);
+}));
+// ---- activities ----
+const activities = program.command("activities").description("Manage activities (timeline events)");
+activities
+    .command("list")
+    .description("List activities")
+    .option("--contact <id>", "filter by contact UUID")
+    .option("--deal <id>", "filter by deal UUID")
+    .option("--type <type>", "filter by type (buckets: task, deal_update)")
+    .option("--search <q>", "search")
+    .option("--from <date>", "fromDate YYYY-MM-DD")
+    .option("--to <date>", "toDate YYYY-MM-DD")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/activities${buildQuery({
+    contact_id: opts.contact,
+    deal_id: opts.deal,
+    type: opts.type,
+    search: opts.search,
+    fromDate: opts.from,
+    toDate: opts.to,
+    page: opts.page,
+    per_page: opts.limit,
+})}`)));
+activities
+    .command("create")
+    .description("Log an activity (type call/email/sms/meeting are stored as manual activities)")
+    .option("--type <type>", "activity type (required)")
+    .option("--title <title>", "title (required)")
+    .option("--description <text>", "description")
+    .option("--contact <id>", "contact UUID")
+    .option("--deal <id>", "deal UUID")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.type !== undefined)
+        body.type = opts.type;
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.deal !== undefined)
+        body.dealId = opts.deal;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/activities", body);
+}));
+// ---- users: update / deactivate (added to the existing `users` group) ----
+users
+    .command("update <id>")
+    .description("Update a team member (PATCH). Cannot change active status here — use `users deactivate`")
+    .option("--first <name>", "first name")
+    .option("--last <name>", "last name")
+    .option("--email <email>", "email")
+    .option("--role <role>", "member | admin | owner")
+    .option("--phone <phone>", "phone")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "user id");
+    const body = {};
+    if (opts.first !== undefined)
+        body.firstName = opts.first;
+    if (opts.last !== undefined)
+        body.lastName = opts.last;
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.role !== undefined)
+        body.role = opts.role;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/users/${encodeURIComponent(id)}`, body);
+}));
+users
+    .command("deactivate <id>")
+    .description("Soft-deactivate a team member (revokes access; use --reassign to hand off their records)")
+    .option("--reassign <id>", "reassign this user's records to this user UUID")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "user id");
+    return client.post(`/api/v1/users/${encodeURIComponent(id)}/deactivate${buildQuery({ reassign_to: opts.reassign })}`, {});
+}));
+// ---- custom-fields: list / update / delete (added to the existing group) ----
+customFields
+    .command("list")
+    .description("List custom field definitions")
+    .option("--entity <type>", "entityType: contact | deal | company")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/custom-fields${buildQuery({ entityType: opts.entity, page: opts.page, per_page: opts.limit })}`)));
+customFields
+    .command("update <id>")
+    .description("Update a custom field definition (label/section/options/required/order are mutable; type & key are not)")
+    .option("--label <label>", "display label")
+    .option("--section <section>", "section grouping")
+    .option("--options <json>", "JSON array of options (for select/radio/multiselect)")
+    .option("--required", "mark the field required")
+    .option("--not-required", "mark the field not required")
+    .option("--sort <n>", "sort order (integer)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "custom field id");
+    const body = {};
+    if (opts.label !== undefined)
+        body.label = opts.label;
+    if (opts.section !== undefined)
+        body.section = opts.section;
+    if (opts.options !== undefined) {
+        if (opts.options.trim() === "")
+            throw new Error("--options must be valid JSON (got an empty string).");
+        let o;
+        try {
+            o = JSON.parse(opts.options);
+        }
+        catch {
+            throw new Error("--options must be valid JSON.");
+        }
+        if (!Array.isArray(o) || o.length === 0) {
+            throw new Error("--options must be a non-empty JSON array.");
+        }
+        body.options = o;
+    }
+    if (opts.required)
+        body.isRequired = true;
+    if (opts.notRequired)
+        body.isRequired = false;
+    if (opts.sort !== undefined) {
+        const n = Number(opts.sort);
+        if (!Number.isInteger(n))
+            throw new Error("--sort must be an integer.");
+        body.sortOrder = n;
+    }
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/custom-fields/${encodeURIComponent(id)}`, body);
+}));
+customFields
+    .command("delete <id>")
+    .description("Delete a custom field definition. If it has stored values/dependencies the API returns a 409 with the counts — re-run with --confirm --values <n> --deps <n>")
+    .option("--confirm", "confirm deletion of a field that has impact")
+    .option("--values <n>", "expectedValueCount (from the 409 response)")
+    .option("--deps <n>", "expectedDependencyCount (from the 409 response)")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "custom field id");
+    let body;
+    if (opts.confirm || opts.values !== undefined || opts.deps !== undefined) {
+        body = { confirmImpact: true };
+        if (opts.values !== undefined) {
+            const n = Number(opts.values);
+            if (!Number.isInteger(n) || n < 0)
+                throw new Error("--values must be a non-negative integer.");
+            body.expectedValueCount = n;
+        }
+        if (opts.deps !== undefined) {
+            const n = Number(opts.deps);
+            if (!Number.isInteger(n) || n < 0)
+                throw new Error("--deps must be a non-negative integer.");
+            body.expectedDependencyCount = n;
+        }
+    }
+    return client.request("DELETE", `/api/v1/custom-fields/${encodeURIComponent(id)}`, body);
+}));
+// ---- webhooks ----
+const webhooks = program.command("webhooks").description("Manage outbound webhooks");
+webhooks
+    .command("list")
+    .description("List registered webhooks (secrets omitted)")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/webhooks/manage${buildQuery({ page: opts.page, per_page: opts.limit })}`)));
+webhooks
+    .command("register")
+    .description("Register an outbound webhook. The signing secret (whsec_...) is returned ONCE in the response — store it now")
+    .option("--url <url>", "delivery URL (https in prod) (required)")
+    .option("--events <list>", "comma-separated event names (required)")
+    .option("--description <text>", "description")
+    .option("--inactive", "create it disabled (isActive=false)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.url !== undefined)
+        body.url = opts.url;
+    if (opts.events !== undefined)
+        body.events = csvArg(opts.events, "--events");
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.inactive)
+        body.isActive = false;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/webhooks/manage", body);
+}));
+// ---- dnc (Do Not Call) ----
+// NOTE: an AI agent's API key must be granted the `dnc` scope to manage the DNC
+// list. Reading also requires dialer:view; adding a litigator entry and removals
+// are admin/owner. A non-admin agent may only DNC a number on a contact it owns
+// or a number it recently called.
+const dnc = program.command("dnc").description("Manage the Do Not Call list (API key needs the `dnc` scope)");
+dnc
+    .command("list")
+    .description("List/search DNC entries. Non-admins must pass --phone (block check only); account-wide browse needs broader access")
+    .option("--phone <number>", "phone number to check/search")
+    .option("--tier <tier>", "dnc | litigator")
+    .option("--search <q>", "search by contact name/phone (admin)")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page)")
+    .action(run(async (client, opts) => client.get(`/api/v1/dnc${buildQuery({ phone: opts.phone, tier: opts.tier, search: opts.search, page: opts.page, per_page: opts.limit })}`)));
+dnc
+    .command("add")
+    .description("Add a number/contact to the DNC list (needs the `dnc` scope; litigator tier is admin-only)")
+    .option("--contact <id>", "contact UUID (contactId or --phone required)")
+    .option("--phone <number>", "phone number (contactId or --phone required)")
+    .option("--tier <tier>", "dnc | litigator (default dnc)")
+    .option("--reason <text>", "reason")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    body.tier = opts.tier ?? "dnc";
+    if (opts.reason !== undefined)
+        body.reason = opts.reason;
+    return client.post("/api/v1/dnc", body);
+}));
+dnc
+    .command("remove <id>")
+    .description("Remove a DNC entry by id (admin/owner)")
+    .action(run(async (client, id) => {
+    assertUuid(id, "dnc id");
+    return client.del(`/api/v1/dnc/${encodeURIComponent(id)}`);
+}));
+// ---- ai ----
+const ai = program.command("ai").description("AI assistant and insight endpoints");
+ai
+    .command("chat <message>")
+    .description("Ask the CRM AI assistant. Streams a server-sent event (SSE) response straight to stdout")
+    .option("--context <text>", "extra page/context string (treated as untrusted data by the assistant)")
+    .action(async (message, opts) => {
+    try {
+        if (message.trim() === "")
+            throw new Error("message must not be empty.");
+        const client = new ConduytClient();
+        const body = { messages: [{ role: "user", content: message }] };
+        if (opts.context !== undefined)
+            body.context = opts.context;
+        await client.stream("POST", "/api/v1/ai/chat", body);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+ai
+    .command("next-actions")
+    .description("AI-recommended next actions for a user (defaults to you; other users need admin/owner)")
+    .option("--user <id>", "user UUID")
+    .action(run(async (client, opts) => client.get(`/api/v1/ai/next-actions${buildQuery({ userId: opts.user })}`)));
+ai
+    .command("daily-brief")
+    .description("Your AI daily brief (task-focused summary)")
+    .action(run(async (client) => client.get("/api/v1/ai/daily-brief")));
+ai
+    .command("summarize-contact <contactId>")
+    .description("Generate an AI summary of a contact")
+    .action(run(async (client, contactId) => {
+    assertUuid(contactId, "contact id");
+    return client.post("/api/v1/ai/summarize-contact", { contactId });
+}));
+ai
+    .command("enrich")
+    .description("AI-enrich a contact identity (needs at least one of --email / --first / --company)")
+    .option("--email <email>", "email")
+    .option("--first <name>", "first name")
+    .option("--last <name>", "last name")
+    .option("--company <company>", "company")
+    .option("--title <title>", "job title")
+    .option("--phone <phone>", "phone")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.first !== undefined)
+        body.firstName = opts.first;
+    if (opts.last !== undefined)
+        body.lastName = opts.last;
+    if (opts.company !== undefined)
+        body.company = opts.company;
+    if (opts.title !== undefined)
+        body.jobTitle = opts.title;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/ai/enrich-contact", body);
+}));
 // ---- raw escape hatch ----
 program
     .command("api <method> <path>")
@@ -523,6 +1631,22 @@ function rejectProtoPollution(obj, flag) {
         }
     }
 }
+function jsonArrayArg(raw, flag) {
+    if (raw.trim() === "") {
+        throw new Error(`${flag} must be valid JSON (got an empty string).`);
+    }
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${flag} must be valid JSON.`);
+    }
+    if (!Array.isArray(v)) {
+        throw new Error(`${flag} must be a JSON ARRAY (e.g. [{"conjunction":"AND","rules":[...]}]).`);
+    }
+    return v;
+}
 function jsonArg(raw, flag) {
     if (raw.trim() === "") {
         throw new Error(`${flag} must be valid JSON (got an empty string).`);
@@ -543,6 +1667,58 @@ function jsonArg(raw, flag) {
     rejectProtoPollution(v, flag);
     return v;
 }
+// Non-throwing UUID check (assertUuid throws; this just tests). Used to decide
+// whether a value is already an id or a human name that needs resolving.
+function looksLikeUuid(s) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s.trim());
+}
+// Resolve a stage name-or-UUID to a stage UUID, mirroring how the API/MCP let an
+// agent use human-readable names: a UUID passes through; a name is resolved via
+// POST /automations/resolve (the canonical name->id endpoint). Fails closed with
+// a clear message rather than PATCHing a bad stageId.
+async function resolveStageId(client, value) {
+    const v = value.trim();
+    if (looksLikeUuid(v))
+        return v;
+    const res = (await client.post("/api/v1/automations/resolve", { stages: [v] }));
+    const id = res?.data?.stages?.[v];
+    if (typeof id === "string" && looksLikeUuid(id))
+        return id;
+    throw new Error(`Could not resolve stage "${v}" to a stage id. Check the name (see \`conduyt pipelines list\`) or pass a stage UUID to --stage.`);
+}
+// Split a comma-separated flag value into a non-empty array of trimmed strings.
+// Used for array-valued request fields (webhook events, resolve name lists).
+function csvArg(raw, flag) {
+    const items = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+    if (items.length === 0) {
+        throw new Error(`${flag} must be a non-empty comma-separated list.`);
+    }
+    return items;
+}
+// Build a full request body from either --json (inline) or --file (a path to a
+// JSON file), requiring exactly one. Used by automations validate/import whose
+// bodies (a workflow graph) are too large to express as flat flags. The parsed
+// value must be a plain JSON object; proto-polluting keys are rejected.
+function bodyFromJsonOrFile(opts) {
+    if (opts.json !== undefined && opts.file !== undefined) {
+        throw new Error("Pass either --json or --file, not both.");
+    }
+    if (opts.json !== undefined)
+        return jsonArg(opts.json, "--json");
+    if (opts.file !== undefined) {
+        if (opts.file.trim() === "")
+            throw new Error("--file must be a path (got an empty string).");
+        let raw;
+        try {
+            raw = readFileSync(opts.file, "utf8");
+        }
+        catch {
+            throw new Error(`--file could not be read: ${opts.file}`);
+        }
+        return jsonArg(raw, "--file");
+    }
+    throw new Error("A request body is required. Pass --json '<json>' or --file <path>.");
+}
 function run(handler) {
     return async (...args) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Command-line interface for Conduyt CRM — manage contacts, deals, pipelines, and run insight queries from your terminal.",
   "type": "module",
   "main": "dist/index.js",