conduyt 1.60.0 → 1.62.0

package/README.md

@@ -34,8 +34,23 @@ conduyt whoami                          # show the authenticated user
 conduyt contacts list --limit 25        # list contacts (supports --cursor, --query)
 conduyt contacts get <id>               # fetch one contact
 conduyt deals list --pipeline <id>      # list deals
+conduyt deals list --health-summary --pipeline <id>   # Pipeline health strip for the filtered set (totalOpenDeals, atRiskValue, checks[]); add --health-check stale --health-limit 20 for one check's deals, --health-cursor <nextCursor> to page, --health-rows-only for just the page
+conduyt deals health --pipeline <id> --check needs_action   # GET /deals/inspection: the six checks over open deals; --check adds its deals, --cursor/--offset pages
+conduyt deals card-fields set value,contact,custom:next_contact_at   # the kanban card fields (1-8, built-ins or custom:<fieldKey>); `card-fields get` reads them
+conduyt pipelines stage-rules set <pipelineId> <stageId> --required-fields contactId,custom:loan_amount --required-documents 2 [--lost-reason-allow-other true]   # what a deal needs to enter the stage; other stages untouched; `stage-rules get [pipelineId] [stageId]` reads
 conduyt deals bulk-update --file updates.json   # update up to 100 deals at once ([{id, stageId, value, ...}]); per-item results, exit 1 if any failed
-conduyt pipelines                       # list pipelines and stages
+conduyt pipelines                       # list pipelines and stages (each carries color, automationOnly, sortOrder)
+conduyt pipelines list --archived       # the archived pipelines (owner / admin key): name, archivedName, openDeals, stageCount
+conduyt pipelines archive <id> --move-open-deals-to <pipelineId|none> [--expected-settings-revision N]   # archive + move the open deals in one transaction; refusals print their code (stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived) and exit 1
+conduyt pipelines settings-revision   # the account settingsRevision to pass as --expected-settings-revision to archive / delete-stage (409 stale_settings_revision when settings changed since)
+conduyt pipelines restore <id>          # bring an archived pipeline back (last in the menu, never the default; 409 name_taken)
+conduyt pipelines reorder --order id1,id2 --expected-revision id1,id2   # board-menu order in one transaction (409 order_changed prints the current revision); `reorder-stages <pipelineId>` does the same for a pipeline's columns
+conduyt pipelines delete-stage <pipelineId> <stageId> [--move-to <stageId>] [--expected-settings-revision N]   # move the live deals to another stage and delete this one; a stale revision is 409 stale_settings_revision
+conduyt pipelines rot-days set <pipelineId> 21   # days without activity (1-90) before a deal reads "Stale in stage"; `rot-days get [pipelineId]` reads
+conduyt status-metadata list --stage-id <id>   # the status codes + buckets attached to stages; `get | create | update | delete | import` (update / delete take --expected-updated-at; 409 metadata_changed)
+conduyt status-metadata import --file rows.json --mode replace   # set-based import (max 1000; an item key outside stageId, code, bucket, lifecycleStage, dripEligible, dripTrackName, isTerminal, notes is refused before any request); per-item errors print and exit 1; `--mode replace` with no items is refused unless `--confirm-empty-replace` (it deletes every row). Timeouts: archive 75 s, import and the Mailchimp write / action commands 60 s; on a timeout the server may have applied it, so read the state first
+conduyt integrations mailchimp settings  # the Mailchimp audience sync (API key scope integrations); `set | audiences | push | retry-unsubscribes | reconcile-statuses [--restart] | confirm-reconciliation`. Connecting is browser-only (OAuth): do it in the app
+conduyt pipelines update <id> --automation-only true   # only automations, API keys and owners / admins move or edit its cards (owner / admin key); also --color <palette hex> and --sort-order
 conduyt search "acme corp"              # search across the CRM
 conduyt insights summary                # run an AI insight query
 conduyt insights saved_report --report "Lead Activity" --period last_7_days   # run any saved report as a tool

package/dist/board-settings.js

@@ -0,0 +1,93 @@
+/**
+ * Deal board settings (app 10-08, BDA board): per-stage rules (settings.pipelineStageRules[pipelineId][stageId]) and the
+ * kanban card fields (settings.dealCardFields). The validators mirror the API's settingsPatchSchema entries, the source
+ * of truth: the built-in names are the app's lists, `custom:<fieldKey>` names one of the account's DEAL custom fields
+ * (the API checks it exists at save), and the stage rule object is strict (no other keys).
+ */
+export const DEAL_STAGE_REQUIRED_FIELDS = ["value", "expectedCloseDate", "contactId", "assignedTo", "lostReason"];
+export const DEAL_CARD_FIELDS = ["value", "contact", "phones", "company", "owner", "priority", "expectedCloseDate", "daysInStage", "nextAction", "tags", "stageHealth", "source"];
+export const MAX_DEAL_CARD_FIELDS = 8;
+export const MAX_STAGE_REQUIRED_FIELDS = 25;
+export const MAX_STAGE_REQUIRED_DOCUMENTS = 20;
+export const MAX_LOST_REASON_OPTIONS = 50;
+const CUSTOM_FIELD_RE = /^custom:[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions", "lostReasonAllowOther"];
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** "a,b,custom:x" → ["a","b","custom:x"]; blank items are dropped, an all-blank value is an empty list */
+export function splitList(raw) {
+    return raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+}
+export function validateRequiredFields(v, flag = "requiredFields") {
+    if (!Array.isArray(v))
+        throw new Error(`${flag} must be a list.`);
+    if (v.length > MAX_STAGE_REQUIRED_FIELDS)
+        throw new Error(`${flag} takes at most ${MAX_STAGE_REQUIRED_FIELDS} entries (got ${v.length}).`);
+    for (const f of v) {
+        if (typeof f !== "string" || !(DEAL_STAGE_REQUIRED_FIELDS.includes(f) || CUSTOM_FIELD_RE.test(f))) {
+            throw new Error(`${flag}: "${String(f)}" is not allowed. Use ${DEAL_STAGE_REQUIRED_FIELDS.join(", ")} or custom:<deal custom field key>.`);
+        }
+    }
+    return v;
+}
+export function validateCardFields(v, flag = "fields") {
+    if (!Array.isArray(v))
+        throw new Error(`${flag} must be a list.`);
+    if (v.length < 1)
+        throw new Error(`${flag} needs at least one field.`);
+    if (v.length > MAX_DEAL_CARD_FIELDS)
+        throw new Error(`${flag} takes at most ${MAX_DEAL_CARD_FIELDS} fields (got ${v.length}).`);
+    for (const f of v) {
+        if (typeof f !== "string" || !(DEAL_CARD_FIELDS.includes(f) || CUSTOM_FIELD_RE.test(f))) {
+            throw new Error(`${flag}: "${String(f)}" is not allowed. Use ${DEAL_CARD_FIELDS.join(", ")} or custom:<deal custom field key>.`);
+        }
+    }
+    return v;
+}
+/** The fields of one stage rule the caller gave, each validated like the API does. Unknown keys are refused (the rule is strict). */
+export function validateRuleChange(raw) {
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!RULE_KEYS.includes(k))
+            throw new Error(`Unknown stage rule field "${k}". A stage rule takes ${RULE_KEYS.join(", ")}.`);
+        if (v === undefined)
+            continue;
+        if (k === "requiredFields")
+            out[k] = validateRequiredFields(v);
+        else if (k === "requiredDocuments") {
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > MAX_STAGE_REQUIRED_DOCUMENTS)
+                throw new Error(`requiredDocuments must be an integer 0-${MAX_STAGE_REQUIRED_DOCUMENTS}.`);
+            out[k] = v;
+        }
+        else if (k === "lostReasonLabel") {
+            const t = typeof v === "string" ? v.trim() : "";
+            if (t.length < 1 || t.length > 60)
+                throw new Error("lostReasonLabel must be 1-60 characters.");
+            out[k] = t;
+        }
+        else if (k === "lostReasonAllowOther") {
+            if (typeof v !== "boolean")
+                throw new Error("lostReasonAllowOther must be true or false.");
+            out[k] = v;
+        }
+        else {
+            if (!Array.isArray(v) || v.some((o) => typeof o !== "string"))
+                throw new Error("lostReasonOptions must be a list of strings.");
+            if (v.length > MAX_LOST_REASON_OPTIONS)
+                throw new Error(`lostReasonOptions takes at most ${MAX_LOST_REASON_OPTIONS} entries.`);
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * The PATCH body that sets ONE stage's rule. The API merges settings.pipelineStageRules per pipeline and replaces that
+ * pipeline's stage map, so the body carries the pipeline's whole stage map with only this stage's rule changed (the given
+ * fields over the stored ones); every other pipeline is left out and therefore untouched.
+ */
+export function stageRulePatch(settings, pipelineId, stageId, change) {
+    const rules = isObj(settings.pipelineStageRules) ? settings.pipelineStageRules : {};
+    const stages = isObj(rules[pipelineId]) ? rules[pipelineId] : {};
+    const current = isObj(stages[stageId]) ? stages[stageId] : {};
+    const kept = Object.fromEntries(RULE_KEYS.filter((k) => current[k] !== undefined).map((k) => [k, current[k]]));
+    return { pipelineStageRules: { [pipelineId]: { ...stages, [stageId]: { ...kept, ...change } } } };
+}

package/dist/client.js

@@ -1,4 +1,12 @@
 import { requireAuth } from "./config.js";
+/** A deadline hit (only when the call set one) is "the server may have applied it", for every method: read the state first. */
+function ambiguousTimeout(err, method, path, timeoutMs, what) {
+    const name = err?.name;
+    if (timeoutMs !== undefined && (name === "TimeoutError" || name === "AbortError")) {
+        return new Error(`Conduyt API timeout: ${what} within ${timeoutMs / 1000}s for ${method} ${path}. The server may have applied it: read the current state before repeating it.`);
+    }
+    return err;
+}
 export class ConduytClient {
     baseUrl;
     apiKey;
@@ -7,17 +15,34 @@ export class ConduytClient {
         this.baseUrl = cfg.apiUrl.replace(/\/+$/, "");
         this.apiKey = cfg.apiKey;
     }
-    async request(method, path, body) {
+    /** timeoutMs: a per-call deadline for the routes whose server budget is long (archive 75 s, Mailchimp admin and
+     *  status-metadata import 60 s). Without it the request has no client-side deadline. A call that hits it may still have
+     *  been applied by the server, and the error says so. */
+    async request(method, path, body, opts) {
         const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
-        const res = await fetch(url, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-        const text = await res.text();
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                ...(opts?.timeoutMs !== undefined ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
+            });
+        }
+        catch (err) {
+            throw ambiguousTimeout(err, method, path, opts?.timeoutMs, "no answer");
+        }
+        // the headers can arrive and the body then stall until the deadline: the same ambiguity, not a raw TimeoutError
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            throw ambiguousTimeout(err, method, path, opts?.timeoutMs, "the response body did not finish");
+        }
         const json = text ? safeParse(text) : null;
         if (!res.ok) {
             // Preserve structured non-2xx bodies: several endpoints return the data
@@ -44,14 +69,14 @@ export class ConduytClient {
     get(path) {
         return this.request("GET", path);
     }
-    post(path, body) {
-        return this.request("POST", path, body);
+    post(path, body, opts) {
+        return this.request("POST", path, body, opts);
     }
     patch(path, body) {
         return this.request("PATCH", path, body);
     }
-    put(path, body) {
-        return this.request("PUT", path, body);
+    put(path, body, opts) {
+        return this.request("PUT", path, body, opts);
     }
     del(path) {
         return this.request("DELETE", path);

package/dist/index.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Command } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
+import { splitList, stageRulePatch, validateCardFields, validateRuleChange } from "./board-settings.js";
+import { ARCHIVE_PIPELINE_TIMEOUT_MS, MAILCHIMP_ADMIN_TIMEOUT_MS, STATUS_METADATA_IMPORT_TIMEOUT_MS, PIPELINE_COLORS, boolFlag, intFlag, isoDate, lifecycleStage as lifecycleStageArg, MAX_PIPELINE_ROT_DAYS, MIN_PIPELINE_ROT_DAYS, pipelineColor, settingsRevision, slug as slugArg, uuid as uuidOf, uuidList, validateImportItems, validateStatusMetadataBody } from "./pipeline-settings.js";
 import { saveConfig, resolveConfig, configPath } from "./config.js";
 import { print, fail, unwrap } from "./output.js";
 // Exit cleanly when a downstream pipe closes early (e.g. `conduyt deals list |
@@ -299,6 +301,18 @@ contacts
     };
 }));
 const deals = program.command("deals").description("Manage deals");
+/** A flag that was given but is blank (an empty shell variable) is a mistake, never "no filter": widening the read to every
+ *  pipeline or dropping the check silently would answer a different question. --cursor / --health-cursor are the exception:
+ *  a blank cursor is forwarded so the API answers health_cursor_blank. */
+function rejectBlankFlags(flags) {
+    for (const [flag, val] of flags) {
+        if (val !== undefined && val.trim() === "") {
+            throw new Error(`${flag} was provided but is blank. Omit it, or pass a real value.`);
+        }
+    }
+}
+/** The six Pipeline health checks (GET /deals health_check, GET /deals/inspection check); the API validates the value. */
+const PIPELINE_HEALTH_CHECKS = ["high_value_idle", "stale", "unassigned", "needs_action", "missing_close_date", "missing_contact"];
 deals
     .command("list")
     .description("List deals")
@@ -309,6 +323,12 @@ deals
     .option("--pipeline-name <name>", "filter by pipeline name (resolved server-side; errors if not found — never returns the whole account)")
     .option("--stage <id>", "filter by stage UUID")
     .option("--stage-name <name>", "filter by stage name (requires --pipeline or --pipeline-name)")
+    .option("--health-summary", "answer the Pipeline health of the filtered set instead of the deal list: totalOpenDeals, atRiskValue, checks[] (six checks, ordered by money at risk), deals. Each deal row also carries hasNextStep and nextAppointmentAt (null unless your key can view the calendar)")
+    .option("--health-check <check>", `with --health-summary: add this check's deals, highest value first (${PIPELINE_HEALTH_CHECKS.join(" | ")})`)
+    .option("--health-limit <n>", "with --health-summary and --health-check: deals per page, 1-100 (default 5)")
+    .option("--health-offset <n>", "with --health-summary and --health-check: deals to skip (default 0); prefer --health-cursor")
+    .option("--health-cursor <token>", "with --health-summary and --health-check: continue after this cursor, the nextCursor of the previous page, passed back UNCHANGED (opaque signed token; a blank, forged or foreign one is a 400 with health_cursor_blank / health_cursor_invalid / health_cursor_context / health_cursor_needs_check)")
+    .option("--health-rows-only", "with --health-summary and --health-check: answer only that page of the check's deals ({check, offset, items, hasMore, nextCursor}), without the summary")
     .action(run(async (client, opts) => {
     // A provided-but-blank filter must error, not silently become "no filter":
     // buildQuery drops empty strings, so a blank flag would never reach the
@@ -326,6 +346,48 @@ deals
             throw new Error(`${flag} was provided but is blank. Omit it to skip the filter, or pass a real value.`);
         }
     }
+    // Pipeline health (app 10-08): a different answer shape (no data.data / meta.total), so it never goes through the
+    // --all / truncation logic below. The API validates the check, the paging and the cursor (400 + code).
+    const healthFlags = [
+        ["--health-check", opts.healthCheck], ["--health-limit", opts.healthLimit], ["--health-offset", opts.healthOffset],
+        ["--health-cursor", opts.healthCursor], ["--health-rows-only", opts.healthRowsOnly],
+    ];
+    if (opts.healthSummary || healthFlags.some(([, v]) => v !== undefined)) {
+        rejectBlankFlags([["--health-check", opts.healthCheck], ["--health-limit", opts.healthLimit], ["--health-offset", opts.healthOffset]]);
+        if (!opts.healthSummary) {
+            throw new Error(`${healthFlags.find(([, v]) => v !== undefined)[0]} needs --health-summary.`);
+        }
+        if (opts.all || opts.limit !== undefined || opts.page !== undefined) {
+            throw new Error("--health-summary answers the Pipeline health, not the deal list: drop --all / --limit / --page (page a check's deals with --health-limit and --health-cursor).");
+        }
+        const usp = new URLSearchParams();
+        for (const [k, v] of Object.entries({ pipeline: opts.pipeline, pipeline_name: opts.pipelineName, stage: opts.stage, stage_name: opts.stageName })) {
+            if (v !== undefined)
+                usp.set(k, v);
+        }
+        usp.set("health_summary", "true");
+        if (opts.healthCheck !== undefined)
+            usp.set("health_check", opts.healthCheck);
+        if (opts.healthLimit !== undefined)
+            usp.set("health_limit", opts.healthLimit);
+        if (opts.healthOffset !== undefined)
+            usp.set("health_offset", opts.healthOffset);
+        // sent as given, even when blank, so the API answers health_cursor_blank instead of the flag vanishing
+        if (opts.healthCursor !== undefined)
+            usp.set("health_cursor", opts.healthCursor);
+        if (opts.healthRowsOnly)
+            usp.set("health_rows_only", "true");
+        const answer = await client.get(`/api/v1/deals?${usp.toString()}`);
+        // the live rows-only answer is { data: { deals: page } }: print the page itself, as the help promises
+        if (opts.healthRowsOnly) {
+            const page = answer?.data?.deals;
+            if (page === undefined || page === null || typeof page !== "object") {
+                throw new Error("--health-rows-only: the API answered without the page (data.deals). Aborting rather than print another shape.");
+            }
+            return { data: page };
+        }
+        return answer;
+    }
     const MAX_PER_PAGE = 1000; // matches the server's per_page cap
     const parsePos = (v, name) => {
         if (v === undefined)
@@ -425,6 +487,64 @@ deals
     }
     return res;
 }));
+deals
+    .command("health")
+    .description(`Pipeline health for one pipeline (or every visible active pipeline) over its open deals (GET /deals/inspection): totalOpenDeals, atRiskValue, checks[] (${PIPELINE_HEALTH_CHECKS.join(", ")}; ordered by money at risk), deals (null without --check), summary, labels. With --check, deals is that check's page {check, offset, items, hasMore, nextCursor, total}, highest value first. For the board's other filters use \`deals list --health-summary\``)
+    .option("--pipeline <id>", "pipeline UUID; omit for every visible active pipeline")
+    .option("--check <check>", `adds that check's deals (${PIPELINE_HEALTH_CHECKS.join(" | ")})`)
+    .option("--limit <n>", "with --check: deals per page, 1-100 (default 5)")
+    .option("--offset <n>", "with --check: deals to skip (default 0); not combined with --cursor")
+    .option("--cursor <token>", "with --check: continue after this cursor, the nextCursor of the previous page, passed back UNCHANGED (opaque signed token; 400 health_cursor_invalid / health_cursor_context / health_cursor_blank / health_cursor_needs_check)")
+    .action(run(async (client, opts) => {
+    rejectBlankFlags([["--pipeline", opts.pipeline], ["--check", opts.check], ["--limit", opts.limit], ["--offset", opts.offset]]);
+    const usp = new URLSearchParams();
+    if (opts.pipeline !== undefined)
+        usp.set("pipeline", opts.pipeline);
+    if (opts.check !== undefined)
+        usp.set("check", opts.check);
+    if (opts.limit !== undefined)
+        usp.set("limit", opts.limit);
+    if (opts.offset !== undefined)
+        usp.set("offset", opts.offset);
+    // sent as given, even when blank, so the API answers health_cursor_blank
+    if (opts.cursor !== undefined)
+        usp.set("cursor", opts.cursor);
+    const qs = usp.toString();
+    return client.get(`/api/v1/deals/inspection${qs ? `?${qs}` : ""}`);
+}));
+// (BDA board 10-08) settings.dealCardFields: the fields on each kanban deal card, in order
+const cardFields = deals
+    .command("card-fields")
+    .description("The fields shown on each kanban deal card, in order (settings.dealCardFields, max 8)");
+cardFields
+    .command("get")
+    .description("Read the card fields: built-ins (value, contact, phones, company, owner, priority, expectedCloseDate, daysInStage, nextAction, tags, stageHealth, source) and custom:<fieldKey> entries")
+    .action(run(async (client) => {
+    const res = (await client.get("/api/v1/settings"));
+    return { data: { dealCardFields: res?.data?.dealCardFields ?? null } };
+}));
+cardFields
+    .command("set [fields]")
+    .description("REPLACE the card fields (admin key, settings:edit): a comma-separated list of 1 to 8, each a built-in (value, contact, phones, company, owner, priority, expectedCloseDate, daysInStage, nextAction, tags, stageHealth, source) or custom:<deal custom field key>, e.g. `value,contact,custom:next_contact_at`. Or pass the list as a JSON array with --json")
+    .option("--json <json>", "the complete list as a JSON array, e.g. '[\"value\",\"custom:next_contact_at\"]' (instead of the positional list)")
+    .action(run(async (client, fields, opts) => {
+    if ((fields === undefined) === (opts.json === undefined))
+        throw new Error("Pass the fields as a comma-separated list or as --json '[...]', not both and not neither.");
+    let list;
+    if (opts.json !== undefined) {
+        try {
+            list = JSON.parse(opts.json);
+        }
+        catch {
+            throw new Error("--json must be valid JSON.");
+        }
+    }
+    else {
+        list = splitList(fields);
+    }
+    const dealCardFields = validateCardFields(list);
+    return patchGeneralSettingsMerged(client, () => ({ dealCardFields }));
+}));
 deals
     .command("create")
     .description("Create a deal (use `pipelines list` to get pipeline/stage ids)")
@@ -639,18 +759,22 @@ const pipelines = program
     .action(run(async (client) => client.get("/api/v1/pipelines")));
 pipelines
     .command("list")
-    .description("List pipelines and their stages")
-    .action(run(async (client) => client.get("/api/v1/pipelines")));
+    .description("List pipelines and their stages (each pipeline carries color, automationOnly, sortOrder). --archived lists the ARCHIVED pipelines instead (owner / admin key): id, name (the pre-archive name), archivedName, color, archivedAt, openDeals, stageCount")
+    .option("--archived", "list the archived pipelines (GET /pipelines?archived=true) instead of the active ones")
+    .action(run(async (client, opts) => client.get(opts.archived ? "/api/v1/pipelines?archived=true" : "/api/v1/pipelines")));
 pipelines
     .command("create")
     .description("Create a pipeline with stages")
     .option("--name <name>", "pipeline name")
     .option("--stages <json>", "JSON array of stages, e.g. '[{\"name\":\"Lead\"},{\"name\":\"Won\",\"isWon\":true}]'")
+    .option("--color <hex>", `pipeline colour, one of the palette: ${PIPELINE_COLORS.join(" ")}`)
     .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.color !== undefined)
+        body.color = pipelineColor(opts.color);
     if (opts.stages !== undefined) {
         if (opts.stages.trim() === "")
             throw new Error("--stages must be valid JSON (got an empty string).");
@@ -675,6 +799,116 @@ pipelines
     assertStagesShape(body.stages);
     return client.post("/api/v1/pipelines", body);
 }));
+// (BDA board 10-08) PATCH /pipelines/:id: name, description, isDefault, sortOrder and automationOnly (owner / admin key)
+pipelines
+    .command("update <id>")
+    .description("Update a pipeline (PATCH: only the fields you pass change). --automation-only true makes it an automation-only pipeline: its cards are moved and edited only by automations, API keys and owners / admins, a member's edit is refused with 403 pipeline_automation_only (owner / admin key only; `pipelines list` shows the flag)")
+    .option("--name <name>", "pipeline name")
+    .option("--description <text>", "pipeline description")
+    .option("--is-default <bool>", "true|false: the account's default pipeline")
+    .option("--automation-only <bool>", "true|false: only automations, API keys and owners / admins move or edit its cards")
+    .option("--sort-order <n>", "position among the pipelines (integer)")
+    .option("--color <hex>", `pipeline colour, one of the palette: ${PIPELINE_COLORS.join(" ")}`)
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "pipeline id");
+    const flag = (raw, name) => {
+        if (raw === undefined)
+            return undefined;
+        const v = raw.trim().toLowerCase();
+        if (v === "true")
+            return true;
+        if (v === "false")
+            return false;
+        throw new Error(`${name} must be true or false.`);
+    };
+    // --json is parsed FIRST and wins: a flag is read (and validated) only when the JSON does not carry its key, so
+    // --json can override a flag whose value would not have parsed
+    const fromJson = opts.json !== undefined ? jsonArg(opts.json, "--json") : {};
+    const body = {};
+    const unlessJson = (key) => !Object.prototype.hasOwnProperty.call(fromJson, key);
+    if (opts.name !== undefined && unlessJson("name"))
+        body.name = opts.name;
+    if (opts.description !== undefined && unlessJson("description"))
+        body.description = opts.description;
+    if (unlessJson("isDefault")) {
+        const isDefault = flag(opts.isDefault, "--is-default");
+        if (isDefault !== undefined)
+            body.isDefault = isDefault;
+    }
+    if (unlessJson("automationOnly")) {
+        const automationOnly = flag(opts.automationOnly, "--automation-only");
+        if (automationOnly !== undefined)
+            body.automationOnly = automationOnly;
+    }
+    if (opts.sortOrder !== undefined && unlessJson("sortOrder")) {
+        const n = Number(opts.sortOrder.trim());
+        if (opts.sortOrder.trim() === "" || !Number.isInteger(n))
+            throw new Error("--sort-order must be an integer.");
+        body.sortOrder = n;
+    }
+    if (opts.color !== undefined && unlessJson("color"))
+        body.color = pipelineColor(opts.color);
+    Object.assign(body, fromJson);
+    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/pipelines/${encodeURIComponent(id)}`, body);
+}));
+// (BDA board 10-08) settings.pipelineStageRules: what a deal needs before it may enter a stage. Read-merge-write with the
+// settings revision (a 409 is re-read and retried once); other stages and pipelines are untouched.
+const stageRules = pipelines
+    .command("stage-rules")
+    .description("Per-stage rules (settings.pipelineStageRules): the fields and documents a deal needs before it may enter a stage");
+stageRules
+    .command("get [pipelineId] [stageId]")
+    .description("Read the stage rules as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther } } }, for everything, one pipeline, or one stage")
+    .action(run(async (client, pipelineId, stageId) => {
+    if (pipelineId !== undefined)
+        assertUuid(pipelineId, "pipeline id");
+    if (stageId !== undefined) {
+        if (pipelineId === undefined)
+            throw new Error("stage id needs a pipeline id.");
+        assertUuid(stageId, "stage id");
+    }
+    const res = (await client.get("/api/v1/settings"));
+    const all = res?.data?.pipelineStageRules && typeof res.data.pipelineStageRules === "object" ? res.data.pipelineStageRules : {};
+    if (pipelineId === undefined)
+        return { data: all };
+    const stages = all[pipelineId] ?? {};
+    return { data: { [pipelineId]: stageId === undefined ? stages : stages[stageId] !== undefined ? { [stageId]: stages[stageId] } : {} } };
+}));
+stageRules
+    .command("set <pipelineId> <stageId>")
+    .description("Set ONE stage's rule (admin key, settings:edit). Only the fields you pass change; they are merged into the stage's current rule. --required-fields REPLACES the list (max 25: value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<deal custom field key>; an empty value clears it). --required-documents is how many documents must be attached before a deal may enter the stage (integer 0-20)")
+    .option("--required-fields <list>", "comma-separated, e.g. contactId,custom:next_contact_at (empty clears)")
+    .option("--required-documents <n>", "integer 0-20")
+    .option("--lost-reason-label <text>", "label of the stage's lost-reason prompt (1-60 chars)")
+    .option("--lost-reason-options <list>", "comma-separated dropdown options of the lost-reason prompt (max 50; empty clears)")
+    .option("--lost-reason-allow-other <bool>", "true|false: the rep may also pick \"Other\" and type the reason (stored as the reason text; takes effect while the stage has lost-reason options)")
+    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther}), merged over the flags")
+    .action(run(async (client, pipelineId, stageId, opts) => {
+    assertUuid(pipelineId, "pipeline id");
+    assertUuid(stageId, "stage id");
+    const raw = {};
+    if (opts.requiredFields !== undefined)
+        raw.requiredFields = splitList(opts.requiredFields);
+    if (opts.requiredDocuments !== undefined) {
+        const t = opts.requiredDocuments.trim();
+        raw.requiredDocuments = t === "" ? NaN : Number(t);
+    }
+    if (opts.lostReasonLabel !== undefined)
+        raw.lostReasonLabel = opts.lostReasonLabel;
+    if (opts.lostReasonOptions !== undefined)
+        raw.lostReasonOptions = splitList(opts.lostReasonOptions);
+    if (opts.lostReasonAllowOther !== undefined)
+        raw.lostReasonAllowOther = boolFlag(opts.lostReasonAllowOther, "--lost-reason-allow-other");
+    if (opts.json !== undefined)
+        Object.assign(raw, jsonArg(opts.json, "--json"));
+    const change = validateRuleChange(raw);
+    if (Object.keys(change).length === 0)
+        throw new Error("Nothing to set. Pass --required-fields, --required-documents, --lost-reason-label, --lost-reason-options, --lost-reason-allow-other or --json.");
+    return patchGeneralSettingsMerged(client, (settings) => stageRulePatch(settings, pipelineId, stageId, change));
+}));
 // (system stages 2026-09-24) tri-surface parity: the stage flags the API takes on PATCH /pipelines/:id/stages/:stageId,
 // isSystem included (a system holding stage automations route deals through; hidden from rep pickers, never won or lost)
 pipelines
@@ -728,6 +962,245 @@ pipelines
         throw new Error("Nothing to update. Pass at least one field flag or --json.");
     return client.patch(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}/stages/${encodeURIComponent(stageId)}`, body);
 }));
+// (pipeline settings 10-08) archive / restore / reorder, stage delete with a move, the stale-in-stage days.
+pipelines
+    .command("archive <id>")
+    .description("Archive a pipeline (owner / admin key): renamed with the archived prefix, never deleted; its closed deals stay as history and `pipelines restore` brings it back. Every OPEN deal moves in the same transaction to --move-open-deals-to's first stage through the normal stage-entry rules; any refusal aborts all of it. Pass --move-open-deals-to none only when there are no open deals. Waits up to 75 s; if it times out the archive may have committed, so run `pipelines list` / `pipelines list --archived` before retrying. The default pipeline cannot be archived. Refusal codes are printed with the error and the command exits 1: stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived, open_deals, default_pipeline, stage_requirements, archive_raced, pipeline_automation_only. An already-archived pipeline answers { archived: true, alreadyArchived: true }")
+    .requiredOption("--move-open-deals-to <pipelineId|none>", "the active pipeline the open deals move to (its first stage must be open), or none when the pipeline has no open deals")
+    .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
+    .action(run(async (client, id, opts) => {
+    const pid = uuidOf(id, "pipeline id");
+    const target = opts.moveOpenDealsTo.trim().toLowerCase();
+    const moveOpenDealsTo = target === "none" ? null : uuidOf(opts.moveOpenDealsTo, "--move-open-deals-to");
+    const body = { moveOpenDealsTo };
+    if (opts.expectedSettingsRevision !== undefined)
+        body.expectedSettingsRevision = settingsRevision(opts.expectedSettingsRevision);
+    return client.post(`/api/v1/pipelines/${pid}/archive`, body, { timeoutMs: ARCHIVE_PIPELINE_TIMEOUT_MS });
+}));
+pipelines
+    .command("restore <id>")
+    .description("Restore an ARCHIVED pipeline (owner / admin key): it loses the archived prefix, goes last in the board menu and is never the default; its stages and closed deals come back with it. 404 when it is not an archived pipeline of this account; 409 name_taken when an active pipeline has its name (rename that one first); 403 PLAN_LIMIT_REACHED when the plan's pipeline limit is full")
+    .action(run(async (client, id) => client.post(`/api/v1/pipelines/${uuidOf(id, "pipeline id")}/restore`, {})));
+pipelines
+    .command("reorder")
+    .description("Set the board-menu order of the active pipelines in one transaction (owner / admin key). --order must list EVERY active pipeline exactly once; --expected-revision is the order you last read (the pipeline ids by position, comma-joined). 409 order_changed (with the current revision) when the order moved since; nothing is written. Prints { order, revision }")
+    .requiredOption("--order <ids>", "comma-separated pipeline ids in the new order")
+    .requiredOption("--expected-revision <revision>", "the current order: the pipeline ids by position, comma-joined")
+    .action(run(async (client, opts) => {
+    const order = uuidList(opts.order, "--order");
+    if (opts.expectedRevision.trim() === "")
+        throw new Error("--expected-revision must be the current order (the pipeline ids by position, comma-joined).");
+    return client.post("/api/v1/pipelines/reorder", { order, expectedRevision: opts.expectedRevision.trim().toLowerCase() });
+}));
+pipelines
+    .command("reorder-stages <pipelineId>")
+    .description("Set a pipeline's column order in one transaction (owner / admin key). --order must list EVERY stage of the pipeline exactly once and may not put a system holding stage first that was not first; --expected-revision is the stage ids by position, comma-joined. 409 order_changed (with the current revision) when it moved since, 409 pipeline_archived when the pipeline was archived meanwhile. Prints { order, revision }")
+    .requiredOption("--order <ids>", "comma-separated stage ids in the new order")
+    .requiredOption("--expected-revision <revision>", "the current order: the stage ids by position, comma-joined")
+    .action(run(async (client, pipelineId, opts) => {
+    const pid = uuidOf(pipelineId, "pipeline id");
+    const order = uuidList(opts.order, "--order");
+    if (opts.expectedRevision.trim() === "")
+        throw new Error("--expected-revision must be the current order (the stage ids by position, comma-joined).");
+    return client.post(`/api/v1/pipelines/${pid}/stages/reorder`, { order, expectedRevision: opts.expectedRevision.trim().toLowerCase() });
+}));
+pipelines
+    .command("delete-stage <pipelineId> <stageId>")
+    .description("Delete a stage (owner / admin key). Without --move-to the stage must have no deals; with it the live deals move to another stage of the SAME pipeline (same won / lost setting, not a system stage) and the stage is deleted in one transaction. A stage a soft-deleted deal still points at is refused. With --expected-settings-revision the answer is { id, deleted: true, settingsRevision }. Refusals exit 1 with the code printed: stale_settings_revision, pipeline_archived, intake_target (other 409s name the cause)")
+    .option("--move-to <stageId>", "another stage of the same pipeline the live deals move to")
+    .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
+    .action(run(async (client, pipelineId, stageId, opts) => {
+    const qs = new URLSearchParams();
+    if (opts.moveTo !== undefined)
+        qs.set("move_to", uuidOf(opts.moveTo, "--move-to"));
+    if (opts.expectedSettingsRevision !== undefined)
+        qs.set("expected_settings_revision", settingsRevision(opts.expectedSettingsRevision));
+    const q = qs.toString();
+    const res = await client.del(`/api/v1/pipelines/${uuidOf(pipelineId, "pipeline id")}/stages/${uuidOf(stageId, "stage id")}${q ? `?${q}` : ""}`);
+    return res ?? { data: { deleted: true, id: stageId } };
+}));
+pipelines
+    .command("settings-revision")
+    .description("The account settingsRevision (plus the stored stage rules and rot days): pass it as --expected-settings-revision to `pipelines archive` / `pipelines delete-stage` so they are refused (409 stale_settings_revision) when settings changed after you read it. Read it right before the mutation")
+    .action(run(async (client) => {
+    const res = (await client.get("/api/v1/settings"));
+    const d = res?.data ?? {};
+    return { data: { settingsRevision: typeof d.settingsRevision === "string" ? d.settingsRevision : null, pipelineStageRules: d.pipelineStageRules ?? null, pipelineRotDays: d.pipelineRotDays ?? null } };
+}));
+// settings.pipelineRotDays: days without activity before a deal reads "Stale in stage" (per pipeline, 1-90)
+const rotDays = pipelines
+    .command("rot-days")
+    .description("Stale-in-stage threshold per pipeline (settings.pipelineRotDays): days without activity (1-90) before a deal reads \"Stale in stage\"");
+rotDays
+    .command("get [pipelineId]")
+    .description("Read the thresholds as { pipelineId: days }, for every pipeline that has one or just the one given")
+    .action(run(async (client, pipelineId) => {
+    const pid = pipelineId === undefined ? undefined : uuidOf(pipelineId, "pipeline id");
+    const res = (await client.get("/api/v1/settings"));
+    const all = res?.data?.pipelineRotDays && typeof res.data.pipelineRotDays === "object" ? res.data.pipelineRotDays : {};
+    return { data: { pipelineRotDays: pid === undefined ? all : all[pid] !== undefined ? { [pid]: all[pid] } : {} } };
+}));
+rotDays
+    .command("set <pipelineId> <days>")
+    .description(`Set one pipeline's threshold (admin key, settings:edit): an integer ${MIN_PIPELINE_ROT_DAYS}-${MAX_PIPELINE_ROT_DAYS}. Only that pipeline changes. The pipeline must be an ACTIVE pipeline of the account (422 for an unknown or archived one). Saved with the settings revision; a 409 is re-read and retried once`)
+    .action(run(async (client, pipelineId, days) => {
+    const pid = uuidOf(pipelineId, "pipeline id");
+    const n = intFlag(days, "days", MIN_PIPELINE_ROT_DAYS, MAX_PIPELINE_ROT_DAYS);
+    return patchGeneralSettingsMerged(client, () => ({ pipelineRotDays: { [pid]: n } }));
+}));
+// ---- status metadata (app 10-08): the status taxonomy rows attached to a pipeline stage ----
+const statusMetadata = program
+    .command("status-metadata")
+    .description("Status metadata: the status codes and buckets attached to pipeline stages (one row per stage and code). update / delete take --expected-updated-at (the row's updatedAt as read): 409 metadata_changed (with the current row) when it changed or moved since, 404 status_metadata_not_found");
+statusMetadata
+    .command("list")
+    .description("List the rows (settings:view); updatedAt is the version for --expected-updated-at")
+    .option("--stage-id <id>", "only this stage's rows")
+    .option("--bucket <bucket>", "only this bucket")
+    .option("--code <code>", "only this code")
+    .action(run(async (client, opts) => client.get(`/api/v1/status-metadata${buildQuery({ stageId: opts.stageId === undefined ? undefined : uuidOf(opts.stageId, "--stage-id"), bucket: opts.bucket, code: opts.code })}`)));
+statusMetadata
+    .command("get <id>")
+    .description("One row with its stage and drip track")
+    .action(run(async (client, id) => client.get(`/api/v1/status-metadata/${uuidOf(id, "id")}`)));
+/** the row fields shared by create and update; "null" clears a nullable one */
+function statusMetadataFields(opts) {
+    const body = {};
+    if (opts.stageId !== undefined)
+        body.stageId = uuidOf(opts.stageId, "--stage-id");
+    if (opts.code !== undefined)
+        body.code = slugArg(opts.code, "--code");
+    if (opts.bucket !== undefined)
+        body.bucket = slugArg(opts.bucket, "--bucket");
+    if (opts.lifecycleStage !== undefined)
+        body.lifecycleStage = opts.lifecycleStage === "null" ? null : lifecycleStageArg(opts.lifecycleStage);
+    if (opts.dripEligible !== undefined)
+        body.dripEligible = boolFlag(opts.dripEligible, "--drip-eligible");
+    if (opts.dripTrackId !== undefined)
+        body.dripTrackId = opts.dripTrackId === "null" ? null : uuidOf(opts.dripTrackId, "--drip-track-id");
+    if (opts.isTerminal !== undefined)
+        body.isTerminal = boolFlag(opts.isTerminal, "--is-terminal");
+    if (opts.notes !== undefined) {
+        if (opts.notes !== "null" && opts.notes.length > 5000)
+            throw new Error("--notes must be at most 5000 characters.");
+        body.notes = opts.notes === "null" ? null : opts.notes;
+    }
+    return body;
+}
+statusMetadata
+    .command("create")
+    .description("Create a row (settings:edit, active billing). --code and --bucket are lowercase slugs (letters, numbers, underscores, max 80); one row per stage and code (a duplicate is a 409)")
+    .requiredOption("--stage-id <id>", "pipeline stage the row attaches to")
+    .requiredOption("--code <slug>", "status code, e.g. appt_set")
+    .requiredOption("--bucket <slug>", "bucket, e.g. working")
+    .option("--lifecycle-stage <stage>", `one of ${["pre_sale", "sale", "underwriting", "active", "resolution", "terminal"].join(", ")}, or null`)
+    .option("--drip-eligible <bool>", "true|false")
+    .option("--drip-track-id <id>", "drip track id, or null")
+    .option("--is-terminal <bool>", "true|false")
+    .option("--notes <text>", "free text (max 5000), or null")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = statusMetadataFields(opts);
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    // flags + --json together, against the exact field list and types: the API ignores a misspelled key and applies the rest
+    return client.post("/api/v1/status-metadata", validateStatusMetadataBody(body, "create"));
+}));
+statusMetadata
+    .command("update <id>")
+    .description("Update a row (settings:edit, active billing): only the fields you pass change. --expected-updated-at refuses the update when the row was changed or moved since you read it (409 metadata_changed, the current row is in the error)")
+    .option("--expected-updated-at <iso>", "the row's updatedAt as you read it")
+    .option("--stage-id <id>", "move the row to another stage")
+    .option("--code <slug>", "status code")
+    .option("--bucket <slug>", "bucket")
+    .option("--lifecycle-stage <stage>", "lifecycle stage, or null")
+    .option("--drip-eligible <bool>", "true|false")
+    .option("--drip-track-id <id>", "drip track id, or null")
+    .option("--is-terminal <bool>", "true|false")
+    .option("--notes <text>", "free text (max 5000), or null")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    const rowId = uuidOf(id, "id");
+    const body = statusMetadataFields(opts);
+    if (opts.expectedUpdatedAt !== undefined)
+        body.expectedUpdatedAt = isoDate(opts.expectedUpdatedAt, "--expected-updated-at");
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    validateStatusMetadataBody(body, "update");
+    if (Object.keys(body).filter((k) => k !== "expectedUpdatedAt").length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/status-metadata/${rowId}`, body);
+}));
+statusMetadata
+    .command("delete <id>")
+    .description("Delete a row (settings:edit, active billing). --expected-updated-at refuses the delete when the row changed or moved since you read it (409 metadata_changed)")
+    .option("--expected-updated-at <iso>", "the row's updatedAt as you read it")
+    .action(run(async (client, id, opts) => {
+    const rowId = uuidOf(id, "id");
+    const q = opts.expectedUpdatedAt === undefined ? "" : `?expected_updated_at=${encodeURIComponent(isoDate(opts.expectedUpdatedAt, "--expected-updated-at"))}`;
+    const res = await client.del(`/api/v1/status-metadata/${rowId}${q}`);
+    return res ?? { data: { deleted: true, id: rowId } };
+}));
+statusMetadata
+    .command("import")
+    .description(`Set-based import (owner / admin key, active billing; max 1000 items) from a JSON array of { stageId, code, bucket, lifecycleStage?, dripEligible?, dripTrackName?, isTerminal?, notes? } via --items or --file. merge (default) upserts the valid items and reports the rest in errors[]; replace replaces the rows of the ACTIVE pipelines and imports nothing if any item is invalid (rows of archived pipelines are kept). With --mode replace and NO items nothing is sent unless --confirm-empty-replace is given (it would delete every row). Prints { imported, skipped, errors } and exits 1 when errors is not empty (the full result is still printed). 409 pipeline_archived when an item names a stage of an archived pipeline`)
+    .option("--mode <mode>", "merge (default) | replace")
+    .option("--items <json>", "the items as a JSON array (or @file)")
+    .option("--file <path>", "read the items JSON array from a file")
+    .option("--confirm-empty-replace", "allow --mode replace with NO items, which deletes every status metadata row of the active pipelines")
+    .action(async (opts) => {
+    try {
+        if (opts.items !== undefined && opts.file !== undefined)
+            throw new Error("Pass either --items or --file, not both.");
+        if (opts.mode !== undefined && opts.mode !== "merge" && opts.mode !== "replace")
+            throw new Error("--mode must be merge or replace.");
+        let raw;
+        if (opts.file !== undefined) {
+            try {
+                raw = readFileSync(opts.file, "utf8");
+            }
+            catch {
+                throw new Error(`--file could not be read: ${opts.file}`);
+            }
+        }
+        else if (opts.items !== undefined) {
+            raw = opts.items.startsWith("@") ? readFileSync(opts.items.slice(1), "utf8") : opts.items;
+        }
+        else {
+            throw new Error("The items are required. Pass --items '<json array>' or --file <path>.");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("The items must be valid JSON.");
+        }
+        const items = validateImportItems(parsed);
+        // checked before any request; the flag is only a local confirmation and is never sent
+        if (opts.mode === "replace" && items.length === 0 && !opts.confirmEmptyReplace) {
+            throw new Error("replace with no items would delete every status metadata row; pass --confirm-empty-replace to do that on purpose");
+        }
+        const client = new ConduytClient();
+        const res = await client.post("/api/v1/status-metadata/import", { ...(opts.mode !== undefined ? { mode: opts.mode } : {}), items }, { timeoutMs: STATUS_METADATA_IMPORT_TIMEOUT_MS });
+        print(res);
+        // a 200 can still carry per-item errors (merge) or a refused replace (imported 0): that is a refusal, exit 1
+        const data = unwrap(res);
+        if (!data || typeof data !== "object" || typeof data.imported !== "number" || !Array.isArray(data.errors)) {
+            process.stderr.write("Error: Unexpected response shape from the API: expected { imported, skipped, errors }.\n");
+            process.exitCode = 1;
+        }
+        else if (data.errors.length > 0) {
+            for (const e of data.errors)
+                process.stderr.write(`Skipped ${String(e?.stageId ?? "?")}: ${String(e?.reason ?? "unknown reason")}\n`);
+            process.stderr.write(`Error: ${data.errors.length} item(s) were not imported (${data.imported} imported).\n`);
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        fail(err);
+    }
+});
 // ---- search ----
 program
     .command("search <query>")
@@ -1519,13 +1992,13 @@ automations
 }));
 automations
     .command("validate")
-    .description("Validate a workflow graph before saving. Provide the body via --json or --file (needs triggerEvent + graph)")
+    .description("Validate a workflow graph before saving. Provide the body via --json or --file (needs triggerEvent + graph). A delay node waits for a fixed duration by default; waitType \"until_field_date\" (with fieldKey = a deal DATE / DATETIME custom field key and offsetHours = signed hours added to its date, default 0, e.g. 24 = a day after it) waits until that date stored on the deal, re-read at every wake (an empty or past value continues immediately).")
     .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). A sequence step is the action enroll_in_sequence with config {sequenceId, enrollAction: add (default) | remove}; add needs the sequence to allow automation enrollment")
+    .description("Create a workflow (with optional name resolution). Provide the body via --json or --file (needs name + triggerEvent + graph). A sequence step is the action enroll_in_sequence with config {sequenceId, enrollAction: add (default) | remove}; add needs the sequence to allow automation enrollment. A delay node waits for a fixed duration by default; waitType \"until_field_date\" (with fieldKey = a deal DATE / DATETIME custom field key and offsetHours = signed hours added to its date, default 0, e.g. 24 = a day after it) waits until that date stored on the deal, re-read at every wake (an empty or past value continues immediately).")
     .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")
@@ -2250,6 +2723,69 @@ wordpressForms
     .command("revoke <id>")
     .description("Revoke an intake address: submissions to it answer 404 from now on. The row is kept (status revoked) for history")
     .action(run(async (client, id) => client.del(`/api/v1/integrations/wordpress-forms/intakes/${uuidArg(id, "id")}`)));
+// Integrations -> Mailchimp (app 10-07/10-08, API key scope `integrations`): the audience sync. The OAuth connect and
+// callback are browser-only (connect Mailchimp in the app: Settings > Integrations), so there is no `connect` here.
+const mailchimp = integrations
+    .command("mailchimp")
+    .description("Mailchimp audience sync (API key scope integrations). Connecting is browser-only (OAuth): do it in the app, then configure it here. Errors exit 1 with the server's message and code (404 not connected, 409 revoked: reconnect in the app)");
+mailchimp
+    .command("settings")
+    .description("The Mailchimp connection: the audience, the source (one smart list or one tag), statusIfNew, unsubscribeSetsOptOut and the sync status (backfill progress, pending pushes, last pushed, last webhook, the last Mailchimp error, statusSweepBlocked). connected: false when there is none")
+    .action(run(async (client) => client.get("/api/v1/integrations/mailchimp/settings")));
+mailchimp
+    .command("set")
+    .description("Configure the sync (PUT; settings:edit, active billing): only the flags you pass change. A new audience gets Conduyt's webhook and starts the backfill; a new source starts the backfill. --source-type and --source-id go together")
+    .option("--list-id <id>", "Mailchimp audience id (see `audiences`)")
+    .option("--source-type <type>", "smart_list | tag")
+    .option("--source-id <id>", "the smart list or tag UUID")
+    .option("--status-if-new <status>", "subscribed (default) | pending (Mailchimp sends a confirmation email)")
+    .option("--unsubscribe-sets-opt-out <bool>", "true|false (default true): a Mailchimp unsubscribe also opts the contact out of Conduyt email")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.listId !== undefined) {
+        if (opts.listId.trim() === "")
+            throw new Error("--list-id was provided but is blank.");
+        body.listId = opts.listId.trim();
+    }
+    if ((opts.sourceType === undefined) !== (opts.sourceId === undefined))
+        throw new Error("--source-type and --source-id go together.");
+    if (opts.sourceType !== undefined) {
+        if (opts.sourceType !== "smart_list" && opts.sourceType !== "tag")
+            throw new Error('--source-type must be "smart_list" or "tag".');
+        body.source = { type: opts.sourceType, id: uuidOf(opts.sourceId, "--source-id") };
+    }
+    if (opts.statusIfNew !== undefined) {
+        if (opts.statusIfNew !== "subscribed" && opts.statusIfNew !== "pending")
+            throw new Error('--status-if-new must be "subscribed" or "pending".');
+        body.statusIfNew = opts.statusIfNew;
+    }
+    if (opts.unsubscribeSetsOptOut !== undefined)
+        body.unsubscribeSetsOptOut = boolFlag(opts.unsubscribeSetsOptOut, "--unsubscribe-sets-opt-out");
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to set. Pass --list-id, --source-type with --source-id, --status-if-new or --unsubscribe-sets-opt-out.");
+    return client.put("/api/v1/integrations/mailchimp/settings", body, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS });
+}));
+mailchimp
+    .command("audiences")
+    .description("The connected account's audiences: id, name, memberCount (use an id as --list-id)")
+    .action(run(async (client) => client.get("/api/v1/integrations/mailchimp/audiences")));
+mailchimp
+    .command("push")
+    .description("Run one sync pass now instead of waiting for the next minute (settings:edit, active billing): queue the contacts newly in the source, take a backfill step, send due pushes. Waits up to 60 s (if it times out the server may have applied it: read `settings`). Prints { ran, result, settings }; ran false means another pass holds the connection or Mailchimp asked to slow down")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/push", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("retry-unsubscribes")
+    .description("Try again, in one pass now, the unsubscribes Conduyt could not deliver to Mailchimp (also retried daily). Prints { ran, pending, delivered, undelivered, result, settings }; pending true = nothing was tried. One retry per account per 10 minutes: otherwise exit 1 with 429 retry_cooldown")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/unsubscribes/retry", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("reconcile-statuses")
+    .description("Full reconciliation when Conduyt's check of Mailchimp's unsubscribes is blocked (statusSweepBlocked in `settings`; owner / admin key): reads every member Mailchimp shows as unsubscribed or cleaned up to the blocked second and applies them (it only ever OPTS OUT), then records a report; it never resumes the check on its own, review the report and run `confirm-reconciliation`. Starts or resumes the run and runs one pass: repeat until done is true. --restart replaces a completed run's report with a new run; without it a completed run exits 1 with 409 reconciliation_completed")
+    .option("--restart", "replace a completed run's report with a new run")
+    .action(run(async (client, opts) => client.post("/api/v1/integrations/mailchimp/reconcile-statuses", opts.restart ? { restart: true } : {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("confirm-reconciliation")
+    .description("Confirm the completed reconciliation's report and resume the unsubscribe check after the blocked second (owner / admin key; audited with the report's counts). 409 when nothing is blocked, a reconciliation is still running, or none completed since the block began")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/confirm-reconciliation", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
 // ---------------------------------------------------------------------------
 // Sequences (one model for Email and SMS since 2026-09-30): steps send saved templates of the sequence's channel a
 // number of days apart inside a send window; a run stops on a reply, a booked meeting, an opt-out, a closed deal or a
@@ -3035,12 +3571,17 @@ replyCapture
 // (400 expected_settings_revision_required) and answers 409 when another save landed first. Every general
 // write below reads the revision first and sends it; a 409 is re-raised with the current settings so the
 // caller re-derives the change instead of overwriting a newer save.
+// the ONE place a general-settings PATCH is sent: it always carries the revision it was derived from (lifecycle-guards.test.ts
+// pins this single call site and that both helpers hand it their revision)
+function patchSettingsWithRevision(client, body, expectedSettingsRevision) {
+    return client.patch("/api/v1/settings", { ...body, ...(expectedSettingsRevision ? { expectedSettingsRevision } : {}) });
+}
 async function patchGeneralSettings(client, body) {
     const read = async () => (await client.get("/api/v1/settings"));
     const before = await read();
     const expectedSettingsRevision = typeof before?.data?.settingsRevision === "string" ? before.data.settingsRevision : null;
     try {
-        return await client.patch("/api/v1/settings", { ...body, ...(expectedSettingsRevision ? { expectedSettingsRevision } : {}) });
+        return await patchSettingsWithRevision(client, body, expectedSettingsRevision);
     }
     catch (err) {
         if (err instanceof Error && /^Conduyt API 409/.test(err.message)) {
@@ -3050,6 +3591,30 @@ async function patchGeneralSettings(client, body) {
         throw err;
     }
 }
+// read-merge-write for a change that depends on what is stored (a per-stage rule): `build` derives the PATCH body from the
+// settings just read and the save carries that read's settingsRevision. A 409 (another save landed first) re-reads and
+// re-derives ONCE; a second 409 is re-raised with the current settings, like patchGeneralSettings.
+async function patchGeneralSettingsMerged(client, build) {
+    const read = async () => (await client.get("/api/v1/settings"));
+    let revision = null;
+    for (let attempt = 0;; attempt += 1) {
+        const before = await read();
+        const settings = before?.data ?? {};
+        revision = typeof settings.settingsRevision === "string" ? settings.settingsRevision : null;
+        const body = build(settings);
+        try {
+            return await patchSettingsWithRevision(client, body, revision);
+        }
+        catch (err) {
+            if (!(err instanceof Error && /^Conduyt API 409/.test(err.message)))
+                throw err;
+            if (attempt === 1) {
+                const current = await read();
+                throw new Error(`${err.message} — the account settings changed twice while this was being saved (last revision read ${revision ?? "?"}); re-run the command (current: ${JSON.stringify(current?.data ?? null).slice(0, 1500)})`);
+            }
+        }
+    }
+}
 function poolFilterOf(settings) {
     const raw = settings.poolFilter;
     const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};

package/dist/pipeline-settings.js

@@ -0,0 +1,155 @@
+/**
+ * Pipeline settings release (app 10-08), status metadata and Mailchimp: the validators the commands run before any
+ * request. They mirror the API (the source of truth) so a bad value fails locally with the same words; the API still
+ * re-checks everything and its refusal codes are printed with the error.
+ */
+export const PIPELINE_COLORS = ["#3845C9", "#43DFF6", "#2DD6B5", "#22C58B", "#9BD13B", "#F2B544", "#F07A2F", "#E6465A", "#FD88C0", "#956EFA"];
+export const LIFECYCLE_STAGES = ["pre_sale", "sale", "underwriting", "active", "resolution", "terminal"];
+export const MAX_STATUS_METADATA_IMPORT = 1000;
+/** per-call deadlines above the server budgets (archive tx 60 s; Mailchimp admin 60 s; import tx 20 s plus locks) */
+export const ARCHIVE_PIPELINE_TIMEOUT_MS = 75_000;
+export const MAILCHIMP_ADMIN_TIMEOUT_MS = 60_000;
+export const STATUS_METADATA_IMPORT_TIMEOUT_MS = 60_000;
+/** the exact fields an import item takes; anything else (a misspelled isTerminal, say) would be dropped by the API and stored as defaults */
+export const IMPORT_ITEM_KEYS = ["stageId", "code", "bucket", "lifecycleStage", "dripEligible", "dripTrackName", "isTerminal", "notes"];
+export const MIN_PIPELINE_ROT_DAYS = 1;
+export const MAX_PIPELINE_ROT_DAYS = 90;
+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 SLUG_RE = /^[a-z0-9][a-z0-9_]{0,79}$/;
+const SETTINGS_REVISION_RE = /^\d+$/;
+export const isUuid = (v) => typeof v === "string" && UUID_RE.test(v.trim());
+export function uuid(raw, name) {
+    if (!isUuid(raw))
+        throw new Error(`${name} must be a UUID.`);
+    return raw.trim().toLowerCase();
+}
+/** true | false (any case) */
+export function boolFlag(raw, name) {
+    const v = raw.trim().toLowerCase();
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    throw new Error(`${name} must be true or false.`);
+}
+export function intFlag(raw, name, min, max) {
+    const t = raw.trim();
+    const n = Number(t);
+    if (t === "" || !Number.isInteger(n) || n < min || n > max)
+        throw new Error(`${name} must be an integer ${min}-${max}.`);
+    return n;
+}
+/** A pipeline colour is one of the 10 palette colours (case-insensitive); the API answers 400 for anything else. */
+export function pipelineColor(raw, name = "--color") {
+    const upper = raw.trim().toUpperCase();
+    const hit = PIPELINE_COLORS.find((c) => c === upper);
+    if (!hit)
+        throw new Error(`${name} must be one of the pipeline palette colours: ${PIPELINE_COLORS.join(", ")}.`);
+    return hit;
+}
+/** The settingsRevision a settings-backed write was read at: digits only (the API's pattern). */
+export function settingsRevision(raw, name = "--expected-settings-revision") {
+    const t = raw.trim();
+    if (!SETTINGS_REVISION_RE.test(t))
+        throw new Error(`${name} must be the settingsRevision you read (digits only).`);
+    return t;
+}
+/** An ISO date (the row's updatedAt as read); the API answers 400 for anything else. */
+export function isoDate(raw, name) {
+    const t = raw.trim();
+    if (t === "" || Number.isNaN(new Date(t).getTime()))
+        throw new Error(`${name} must be the updatedAt you read (an ISO date).`);
+    return t;
+}
+export function slug(raw, name) {
+    if (!SLUG_RE.test(raw))
+        throw new Error(`${name} must be a lowercase machine slug using letters, numbers and underscores (max 80).`);
+    return raw;
+}
+export function lifecycleStage(raw, name = "--lifecycle-stage") {
+    if (!LIFECYCLE_STAGES.includes(raw))
+        throw new Error(`${name} must be one of: ${LIFECYCLE_STAGES.join(", ")}.`);
+    return raw;
+}
+/** A comma-separated order list of UUIDs, no duplicates. */
+export function uuidList(raw, name) {
+    const ids = raw.split(",").map((s) => s.trim()).filter((s) => s !== "").map((s) => uuid(s, `${name} entry`));
+    if (ids.length === 0)
+        throw new Error(`${name} needs at least one id.`);
+    if (new Set(ids).size !== ids.length)
+        throw new Error(`${name} lists an id more than once.`);
+    return ids;
+}
+/** The fields of a status metadata row for create / update / get (a drip track is named by id); import names it by dripTrackName instead. */
+export const ROW_FIELD_KEYS = IMPORT_ITEM_KEYS.map((k) => (k === "dripTrackName" ? "dripTrackId" : k));
+/**
+ * THE one definition of a status metadata row's fields and types, shared by import items and the create / update bodies:
+ * unknown keys are refused naming the key (the API drops them and applies the rest of the call), and each present value is
+ * type-checked like the API does. `required`: stageId, code and bucket must be present. `trackKey` is the drip track field.
+ */
+function checkRowFields(o, at, allowed, required, trackKey, what) {
+    for (const k of Object.keys(o)) {
+        if (!allowed.includes(k))
+            throw new Error(`${at}: unknown field "${k}". ${what} takes ${allowed.join(", ")}; nothing was sent.`);
+    }
+    const has = (k) => o[k] !== undefined;
+    if (required || has("stageId")) {
+        if (typeof o.stageId !== "string" || !isUuid(o.stageId))
+            throw new Error(`${at}.stageId must be a UUID.`);
+    }
+    for (const k of ["code", "bucket"]) {
+        if (required || has(k)) {
+            if (typeof o[k] !== "string")
+                throw new Error(`${at}.${k} must be a slug.`);
+            slug(o[k], `${at}.${k}`);
+        }
+    }
+    if (has("lifecycleStage") && o.lifecycleStage !== null) {
+        if (typeof o.lifecycleStage !== "string")
+            throw new Error(`${at}.lifecycleStage must be one of: ${LIFECYCLE_STAGES.join(", ")}, or null.`);
+        lifecycleStage(o.lifecycleStage, `${at}.lifecycleStage`);
+    }
+    if (has("dripEligible") && typeof o.dripEligible !== "boolean")
+        throw new Error(`${at}.dripEligible must be a boolean.`);
+    if (has("isTerminal") && typeof o.isTerminal !== "boolean")
+        throw new Error(`${at}.isTerminal must be a boolean.`);
+    if (has(trackKey) && o[trackKey] !== null) {
+        const v = o[trackKey];
+        if (typeof v !== "string")
+            throw new Error(`${at}.${trackKey} must be ${trackKey === "dripTrackId" ? "a UUID" : "a slug"} or null.`);
+        if (trackKey === "dripTrackId") {
+            if (!isUuid(v))
+                throw new Error(`${at}.dripTrackId must be a UUID or null.`);
+        }
+        else
+            slug(v, `${at}.dripTrackName`);
+    }
+    if (has("notes") && o.notes !== null && (typeof o.notes !== "string" || o.notes.trim().length > 5000))
+        throw new Error(`${at}.notes must be text of at most 5000 characters.`);
+}
+/** One status metadata item, as the import route takes it. */
+export function validateImportItem(raw, index) {
+    const at = `items[${index}]`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${at} must be an object.`);
+    checkRowFields(raw, at, IMPORT_ITEM_KEYS, true, "dripTrackName", "An import item");
+    return raw;
+}
+/** The COMPLETE body of `status-metadata create` / `update` (flags + --json merged), checked before any request. */
+export function validateStatusMetadataBody(body, mode) {
+    const allowed = mode === "update" ? [...ROW_FIELD_KEYS, "expectedUpdatedAt"] : ROW_FIELD_KEYS;
+    checkRowFields(body, "body", allowed, mode === "create", "dripTrackId", mode === "create" ? "A status metadata row" : "A status metadata update");
+    if (body.expectedUpdatedAt !== undefined) {
+        if (typeof body.expectedUpdatedAt !== "string")
+            throw new Error("body.expectedUpdatedAt must be the updatedAt you read (an ISO date).");
+        isoDate(body.expectedUpdatedAt, "body.expectedUpdatedAt");
+    }
+    return body;
+}
+export function validateImportItems(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("items must be a JSON array.");
+    if (raw.length > MAX_STATUS_METADATA_IMPORT)
+        throw new Error(`items takes at most ${MAX_STATUS_METADATA_IMPORT} entries (got ${raw.length}).`);
+    return raw.map((item, i) => validateImportItem(item, i));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.60.0",
+  "version": "1.62.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",