@elitedcs/ghl-mcp 3.46.0 → 3.48.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 3.48.0 — Blueprint: complete workflow-building (opportunities, branching, appointment timers, opt-in publish)
+
+Completes the `apply_build_plan` executor so a Blueprint build produces workflows that
+create and move real opportunities, branch on whether a contact has one, fire on
+appointment-relative timers, and (opt-in) go live instead of staging as drafts. Every
+item below was proven live on a throwaway account and read back before shipping.
+
+- **Fixed: `create_opportunity` now actually creates an opportunity.** The executor was
+  emitting GHL's *update* node (`internal_update_opportunity`), which only updates an
+  existing opp and silently no-ops when none exists. It now emits the real
+  `internal_create_opportunity` node (pipeline hoisted to the attribute level, stage + name
+  in the custom input fields), so a new-lead workflow lands a deal in the pipeline as
+  intended.
+- **New: `wait_appointment` action** — appointment-relative reminder timers (e.g. "24 hours
+  before the appointment"), emitting GHL's appointment-relative wait node. The workflow
+  builder's action-chain validation accepts the appointment-relative `appointmentStartAfter`
+  shape alongside the standard time-based `startAfter`.
+- **New: optional `monetaryValue`** on `create_opportunity` / `update_opportunity` so a deal
+  carries its value.
+- **New: `find_opportunity` multi-path branching.** The first branching logical action: it
+  loads a contact's latest opportunity in a pipeline, then routes to a `found` / `not-found`
+  branch (each with its own actions, including waits and sends). This is what makes a
+  move-the-opp step inside a branch work — the find loads the opp the move then acts on.
+- **Fixed: backward opportunity moves (win-back / reactivation) silently no-op'd.** GHL's
+  "Move opportunity" defaults `allowBackward:false`, which lets a forward stage move through
+  but silently refuses a move to an earlier stage — breaking every reactivation build (whose
+  whole point is a backward move). The executor now emits `allowBackward:true` so the target
+  stage is honored in either direction; forward moves are unaffected.
+- **New: opt-in `publishWorkflows`.** Workflows still build as DRAFT by default (the safe
+  default). Passing `publishWorkflows:true` publishes ungated, newly-built workflows live
+  (re-syncing their triggers); a workflow gated DRAFT by an unmet handoff is never
+  auto-published, and a publish failure never halts or rolls back the build (it surfaces a
+  "publish it yourself" note and the build still succeeds).
+- **New: funnel page content template** (`templates/funnel-page-content-template.md`) —
+  brand-themeable CSS plus always-on A2P/10DLC opt-in, SEO, and AI-search (GEO) structure
+  for the manual funnel-page-content step.
+
+## 3.47.0 — Blueprint Cap-0: cross-workflow exit chaining + native trigger builders
+
+Two foundational executor fixes so `apply_build_plan` builds workflows that actually
+chain together AND actually fire — the prerequisites for a non-hollow account build.
+
+- **Fixed: a cross-workflow `remove_from_workflow` / `add_to_workflow` halted the build.**
+  When one workflow's exit action targeted another workflow in the SAME plan, execute
+  halted, reporting the (already-built) target as unresolved — so the canonical "pull the
+  lead out of nurture when they book / reply" pattern (workflows that enrol each other)
+  could not fully execute. The executor now resolves EVERY workflow's identity in a first
+  pass (never-clobber bind existing, else create an empty DRAFT) before expanding any
+  actions, so forward, backward, AND mutual cross-workflow references all resolve. Safety
+  rails intact and hardened: never-clobber (existing workflows are never modified),
+  empty-orphan detection (now halts rather than blind-binds when an existing workflow's
+  action count is unreadable), verify-after, and rollback of every unsaved shell on a halt
+  — with any orphan id that could not be deleted SURFACED in the halt message (never
+  swallowed) and dropped from the returned id map.
+- **New: native trigger builders for the trigger types real accounts actually use.**
+  Previously only `contact_tag` triggers were auto-built; every other workflow shipped
+  trigger-less (inactive) — the #1 reason builds were hollow. Blueprint now builds
+  `form_submission`, `appointment` (status-conditioned, e.g. confirmed / no-show),
+  `customer_reply`, `pipeline_stage_updated`, `inbound_webhook`, and `payment_received`
+  triggers natively. Each saved shape was CAPTURED from a real, live, UI-built trigger in a
+  reference account (not guessed) so the synthesized trigger reads back identical and fires.
+  Refs in trigger conditions (form / pipeline / stage) resolve to real GHL ids at build
+  time. A trigger type Blueprint doesn't yet build natively — or one missing the field it
+  needs (e.g. an `appointment` trigger with no status) — is still surfaced as a manual step.
+- Plan validation now rejects two workflows that share a name (the executor binds workflows
+  by name, so duplicates would collapse onto one shell).
+
 ## 3.46.0 — `verify_funnel`: prove a funnel actually captures leads (+ external-funnel wiring bundle)
 
 The live-runtime companion to `audit_workflows`. `audit_workflows` finds dead workflow

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.46.0",
+      version: "3.48.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 220 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -1237,7 +1237,9 @@ function validateActionChain(actions, existingIds) {
         if (!Array.isArray(attr.tags) || !attr.tags.length) throw new Error(`Tag action "${action.name}" missing 'tags' array.`);
         break;
       case "wait":
-        if (!attr.startAfter) throw new Error(`Wait action "${action.name}" missing required 'startAfter' in attributes.`);
+        if (!attr.startAfter && !attr.appointmentStartAfter) {
+          throw new Error(`Wait action "${action.name}" missing required 'startAfter' (or 'appointmentStartAfter' for an appointment-relative wait) in attributes.`);
+        }
         break;
       case "internal_update_opportunity": {
         const isRoundTripped = hasId(action) && (existingIds ? existingIds.has(action.id) : true);
@@ -1288,6 +1290,31 @@ function validateActionChain(actions, existingIds) {
       if (!sibling || sibling.length !== 1) throw new Error(`If/else branch "${action.name}" must have exactly one sibling id.`);
     }
   }
+  for (const action of actions) {
+    if (action.type !== "find_opportunity") continue;
+    if (existingIds && hasId(action) && existingIds.has(action.id)) continue;
+    if (!action.id) throw new Error(`find_opportunity "${action.name}" missing id.`);
+    const next = getStringArray(action.next);
+    if (!next || next.length !== 2) {
+      throw new Error(`find_opportunity "${action.name}" must have next as exactly [foundTransitionId, notFoundTransitionId].`);
+    }
+    for (const tid of next) {
+      const t = byId.get(tid);
+      if (!t || t.type !== "transition") {
+        throw new Error(`find_opportunity "${action.name}" next must reference its two transition nodes.`);
+      }
+      if (t.parent !== action.id || t.parentKey !== action.id) {
+        throw new Error(`Transition "${t.name}" of find_opportunity "${action.name}" must have parent and parentKey set to the find node id.`);
+      }
+      const firstChildId = typeof t.next === "string" ? t.next : void 0;
+      if (firstChildId) {
+        const c = byId.get(firstChildId);
+        if (!c || c.parent !== tid || c.parentKey !== tid) {
+          throw new Error(`First child of transition "${t.name}" must have parent and parentKey set to the transition id.`);
+        }
+      }
+    }
+  }
 }
 var WorkflowBuilderClient = class _WorkflowBuilderClient {
   // Active Firebase auth — swapped when operating in another company's GHL.
@@ -1891,7 +1918,12 @@ ${errorBody}`
     });
     for (let i = 0; i < linked.length; i++) {
       const action = linked[i];
-      if (action.cat || action.nodeType || action.parent) continue;
+      if (action.parent || action.nodeType) continue;
+      if (action.cat === "multi-path") {
+        if (i > 0 && !action.parentKey) action.parentKey = linked[i - 1].id;
+        continue;
+      }
+      if (action.cat) continue;
       if (i > 0 && !action.parentKey) {
         action.parentKey = linked[i - 1].id;
       }
@@ -11116,12 +11148,25 @@ var smsAssetSchema = import_zod53.z.object({
   mergeTags: import_zod53.z.array(import_zod53.z.string()).optional()
 });
 var waitUnit = import_zod53.z.enum(["minutes", "hours", "days"]);
-var actionSchema = import_zod53.z.discriminatedUnion("type", [
+var branchActionOptions = [
   import_zod53.z.object({ type: import_zod53.z.literal("add_contact_tag"), tagRef: nsRef("tag") }),
   import_zod53.z.object({ type: import_zod53.z.literal("remove_contact_tag"), tagRef: nsRef("tag") }),
   import_zod53.z.object({ type: import_zod53.z.literal("send_email"), emailRef: nsRef("email") }),
   import_zod53.z.object({ type: import_zod53.z.literal("send_sms"), smsRef: nsRef("sms") }),
   import_zod53.z.object({ type: import_zod53.z.literal("wait"), value: import_zod53.z.number().positive(), unit: waitUnit }),
+  // Appointment-relative wait ("wait until N BEFORE the appointment").
+  // Only works when the workflow has an appointment in context (i.e. an
+  // `appointment` trigger) — enforced by validateBuildPlan. Expands to GHL's
+  // appointment-wait node shape (attributes.type "appointment" +
+  // appointmentStartAfter, captured live from Lux Bio). Integer units only
+  // (GHL stores whole minutes). Only "before" is emitted today — that's the
+  // shape we captured + proved; "after" (post-appointment follow-up) is
+  // deferred until its shape is captured from a real workflow.
+  import_zod53.z.object({
+    type: import_zod53.z.literal("wait_appointment"),
+    value: import_zod53.z.number().int().positive(),
+    unit: waitUnit
+  }),
   import_zod53.z.object({
     type: import_zod53.z.literal("internal_notification"),
     to: import_zod53.z.string(),
@@ -11147,12 +11192,22 @@ var actionSchema = import_zod53.z.discriminatedUnion("type", [
     type: import_zod53.z.literal("create_opportunity"),
     pipelineRef: nsRef("pipeline"),
     stageRef: nsRef("stage"),
-    status: import_zod53.z.string().optional()
+    // Opportunity name (merge fields allowed). Defaults to the contact's name.
+    // Required by GHL's create node; without it the create silently no-ops.
+    name: import_zod53.z.string().optional(),
+    // Opportunity monetary value (the deal/sale dollar amount). A string so it
+    // can be a literal ("2500") OR a merge field ("{{contact.package_value}}").
+    // Optional — omitted → GHL leaves the value unset. Shape captured from Lux
+    // Bio "14. Package Sale". Lux models the lifecycle by pipeline STAGE, not GHL
+    // won/lost status, so a "won" opp = move to the closing stage WITH this value.
+    value: import_zod53.z.string().optional()
   }),
   import_zod53.z.object({
     type: import_zod53.z.literal("update_opportunity"),
     pipelineRef: nsRef("pipeline"),
-    stageRef: nsRef("stage")
+    stageRef: nsRef("stage"),
+    // Opportunity monetary value (see create_opportunity.value). Optional.
+    value: import_zod53.z.string().optional()
   }),
   import_zod53.z.object({
     type: import_zod53.z.literal("goal_event"),
@@ -11160,14 +11215,25 @@ var actionSchema = import_zod53.z.discriminatedUnion("type", [
     // GHL's GoalAction enum (extracted 2026-05-18): continue | wait | exit.
     action: import_zod53.z.enum(["exit", "continue", "wait"]).optional()
   })
-]);
+];
+var branchActionSchema = import_zod53.z.discriminatedUnion("type", branchActionOptions);
+var findOpportunitySchema = import_zod53.z.object({
+  type: import_zod53.z.literal("find_opportunity"),
+  pipelineRef: nsRef("pipeline"),
+  found: import_zod53.z.array(branchActionSchema).default([]),
+  notFound: import_zod53.z.array(branchActionSchema).default([])
+});
+var actionSchema = import_zod53.z.discriminatedUnion("type", [...branchActionOptions, findOpportunitySchema]);
+var APPOINTMENT_STATUSES = ["new", "confirmed", "showed", "noshow", "cancelled", "invalid"];
 var triggerSchema = import_zod53.z.object({
   type: import_zod53.z.string(),
   formRef: nsRef("form").optional(),
   tagRef: nsRef("tag").optional(),
   calendarRef: nsRef("calendar").optional(),
   pipelineRef: nsRef("pipeline").optional(),
-  stageRef: nsRef("stage").optional()
+  stageRef: nsRef("stage").optional(),
+  // Required for a native `appointment` trigger (the status it fires on).
+  appointmentStatus: import_zod53.z.enum(APPOINTMENT_STATUSES).optional()
 });
 var workflowSchema = import_zod53.z.object({
   ref: nsRef("workflow"),
@@ -11290,8 +11356,7 @@ function checkRefIntegrity(plan, defined) {
       check(t.pipelineRef, "pipeline", `workflows[${w.ref}].trigger.pipelineRef`);
       check(t.stageRef, "stage", `workflows[${w.ref}].trigger.stageRef`);
     }
-    w.actions.forEach((a, i) => {
-      const where = `workflows[${w.ref}].actions[${i}](${a.type})`;
+    const checkActionRefs = (a, where) => {
       if ("tagRef" in a) check(a.tagRef, "tag", where);
       if ("emailRef" in a) check(a.emailRef, "email", where);
       if ("smsRef" in a) check(a.smsRef, "sms", where);
@@ -11299,6 +11364,17 @@ function checkRefIntegrity(plan, defined) {
       if ("pipelineRef" in a) check(a.pipelineRef, "pipeline", where);
       if ("stageRef" in a) check(a.stageRef, "stage", where);
       if ("workflowRef" in a) check(a.workflowRef, "workflow", where);
+    };
+    w.actions.forEach((a, i) => {
+      const where = `workflows[${w.ref}].actions[${i}](${a.type})`;
+      checkActionRefs(a, where);
+      if (a.type === "find_opportunity") {
+        if (i !== w.actions.length - 1) {
+          errors.push(`${where}: find_opportunity must be the last action in the workflow (its Found/Not-Found branches do not rejoin a linear tail).`);
+        }
+        a.found.forEach((c, ci) => checkActionRefs(c, `${where}.found[${ci}](${c.type})`));
+        a.notFound.forEach((c, ci) => checkActionRefs(c, `${where}.notFound[${ci}](${c.type})`));
+      }
     });
   }
   for (const h of plan.handoffs ?? []) {
@@ -11376,7 +11452,12 @@ function validateBuildPlan(input) {
     ["customValues", (plan.customValues ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
     ["calendars", (plan.calendars ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
     ["forms", (plan.forms ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
-    ["funnels", (plan.funnels ?? []).map((x) => ({ ref: x.ref, name: x.name }))]
+    ["funnels", (plan.funnels ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    // Workflows bind by name too: the executor's two-pass build resolves each
+    // workflow's identity by name (bind same-named existing, else create a shell).
+    // Two plan workflows sharing a name would make the second bind to the FIRST's
+    // freshly-created shell — only one would ever be saved. Reject before any write.
+    ["workflows", (plan.workflows ?? []).map((x) => ({ ref: x.ref, name: x.name }))]
   ];
   for (const [type, objs] of nameGroups) {
     const seen = /* @__PURE__ */ new Map();
@@ -11425,6 +11506,32 @@ function validateBuildPlan(input) {
       );
     }
   }
+  for (const wf of plan.workflows ?? []) {
+    const hasApptWait = wf.actions.some((a) => a.type === "wait_appointment");
+    if (hasApptWait && wf.trigger?.type !== "appointment") {
+      warnings.push(
+        `workflow "${wf.ref}" uses a wait_appointment ("before appointment" timer) but its trigger is ${wf.trigger?.type ? `"${wf.trigger.type}"` : "not set to an appointment trigger"} \u2014 that timer needs an appointment in context (an "appointment" trigger), or GHL silently mis-times it`
+      );
+    }
+  }
+  const MAX_NODES = 40;
+  for (const wf of plan.workflows ?? []) {
+    let nodeCount = 0;
+    let hasBranch = false;
+    for (const a of wf.actions) {
+      if (a.type === "find_opportunity") {
+        hasBranch = true;
+        nodeCount += 3 + a.found.length + a.notFound.length;
+      } else {
+        nodeCount += 1;
+      }
+    }
+    if (hasBranch && nodeCount > MAX_NODES) {
+      allErrors.push(
+        `workflow "${wf.ref}" expands to ${nodeCount} nodes (> ${MAX_NODES}); a workflow with a find_opportunity branch cannot be auto-split \u2014 move actions into separate workflows.`
+      );
+    }
+  }
   return {
     valid: allErrors.length === 0,
     errors: allErrors,
@@ -11518,6 +11625,15 @@ function htmlWrap(text) {
   if (/^\s*<[a-z]/i.test(t)) return t;
   return `<p style="margin:0px;">${t}</p>`;
 }
+function monetaryValueField(value) {
+  return {
+    __customInputs__: { value: "numerical" },
+    filterField: "monetaryValue",
+    valueFieldType: "custom-input",
+    value,
+    dataType: "NUMERICAL"
+  };
+}
 function resolveId(ref, idMap) {
   const real = idMap.get(ref);
   return real ?? PENDING(ref);
@@ -11600,6 +11716,41 @@ function expandAction(action, idx, idMap) {
         }
       };
     }
+    case "wait_appointment": {
+      const totalMinutes = action.value * (action.unit === "days" ? 1440 : action.unit === "hours" ? 60 : 1);
+      const distributed = {
+        months: 0,
+        days: Math.floor(totalMinutes / 1440),
+        hours: Math.floor(totalMinutes % 1440 / 60),
+        minutes: totalMinutes % 60
+      };
+      const label = `Wait until ${action.value} ${action.unit} before appointment`;
+      return {
+        kind: "expanded",
+        pendingRefs: [],
+        native: {
+          type: "wait",
+          name: label,
+          attributes: {
+            type: "appointment",
+            name: label,
+            cat: "",
+            isHybridAction: true,
+            hybridActionType: "wait",
+            convertToMultipath: false,
+            transitions: [],
+            appointmentStartAfter: {
+              // Only "before" is emitted — the captured/proven shape. See plan.ts.
+              when: "before",
+              type: "minutes",
+              value: totalMinutes,
+              distributed
+            },
+            appointmentCondition: "skip"
+          }
+        }
+      };
+    }
     case "internal_notification": {
       const looksLikeUserId = /^[A-Za-z0-9]{17,}$/.test(action.to);
       return {
@@ -11690,7 +11841,40 @@ function expandAction(action, idx, idMap) {
         }
       };
     }
-    case "create_opportunity":
+    case "create_opportunity": {
+      const pipelineId = resolveId(action.pipelineRef, idMap);
+      const stageId = resolveId(action.stageRef, idMap);
+      const pendingRefs = [];
+      if (isPending(pipelineId)) pendingRefs.push(action.pipelineRef);
+      if (isPending(stageId)) pendingRefs.push(action.stageRef);
+      const pName = idx.pipelineName.get(action.pipelineRef) ?? action.pipelineRef;
+      const sName = idx.stageName.get(action.stageRef) ?? action.stageRef;
+      const oppName = action.name ?? "{{contact.first_name}} {{contact.last_name}}";
+      return {
+        kind: "expanded",
+        pendingRefs,
+        native: {
+          type: "internal_create_opportunity",
+          name: `Create opportunity: ${pName} / ${sName}`,
+          workflowsActionType: "INTERNAL",
+          attributes: {
+            type: "internal_create_opportunity",
+            pipelineId,
+            // The save-time normalizer only scaffolds internal_update_opportunity, so this
+            // create node carries GHL's full shape itself (attribute-level + per-field
+            // __customInputs__), matching the captured live node exactly.
+            __customInputs__: {},
+            __customInputFields__: [
+              { __customInputs__: {}, filterField: "pipelineStageId", value: stageId, valueFieldType: "select", dataType: "SINGLE_OPTIONS" },
+              { __customInputs__: {}, filterField: "name", value: oppName, valueFieldType: "string", dataType: "TEXT" },
+              // Optional opportunity dollar value (Lux "14. Package Sale" shape). Only
+              // emitted when the plan supplies a value; omitted → GHL leaves it unset.
+              ...action.value ? [monetaryValueField(action.value)] : []
+            ]
+          }
+        }
+      };
+    }
     case "update_opportunity": {
       const pipelineId = resolveId(action.pipelineRef, idMap);
       const stageId = resolveId(action.stageRef, idMap);
@@ -11699,26 +11883,119 @@ function expandAction(action, idx, idMap) {
       if (isPending(stageId)) pendingRefs.push(action.stageRef);
       const pName = idx.pipelineName.get(action.pipelineRef) ?? action.pipelineRef;
       const sName = idx.stageName.get(action.stageRef) ?? action.stageRef;
-      const verb = action.type === "create_opportunity" ? "Create opportunity" : "Move opportunity";
       return {
         kind: "expanded",
         pendingRefs,
         native: {
           type: "internal_update_opportunity",
-          name: `${verb}: ${pName} / ${sName}`,
-          // NODE-level discriminator (the normalizer also forces this; included so
-          // the expanded action is correct even outside the save path).
+          name: `Move opportunity: ${pName} / ${sName}`,
           workflowsActionType: "INTERNAL",
           attributes: {
             type: "internal_update_opportunity",
+            // Honor the operator's explicit target stage in EITHER direction. GHL's
+            // "Move opportunity" action defaults allowBackward:false, which SILENTLY
+            // refuses to move an opp to an EARLIER pipeline stage (lower position) —
+            // breaking win-back / reactivation moves whose whole point is to move a
+            // deal BACKWARD (e.g. Cancelled → Active). The Blueprint intent of an
+            // update_opportunity action is "put this opp in this stage" regardless of
+            // direction, so allow backward moves. (Live-caught on Cap-3 wf7 2026-06-24:
+            // the identical node moved a deal FORWARD fine in wf6 but silently no-op'd
+            // moving it BACKWARD here.) The save-time normalizer preserves an explicit
+            // boolean, so this is honored end-to-end.
+            allowBackward: true,
             __customInputFields__: [
               { filterField: "pipelineId", value: pipelineId, valueFieldType: "select", dataType: "SINGLE_OPTIONS" },
-              { filterField: "pipelineStageId", value: stageId, valueFieldType: "select", dataType: "SINGLE_OPTIONS" }
+              { filterField: "pipelineStageId", value: stageId, valueFieldType: "select", dataType: "SINGLE_OPTIONS" },
+              // Optional opportunity dollar value (Lux "14. Package Sale" shape). Only
+              // emitted when the plan supplies a value; omitted → GHL leaves it unchanged.
+              ...action.value ? [monetaryValueField(action.value)] : []
             ]
           }
         }
       };
     }
+    case "find_opportunity": {
+      const pipelineId = resolveId(action.pipelineRef, idMap);
+      const pendingRefs = [];
+      if (isPending(pipelineId)) pendingRefs.push(action.pipelineRef);
+      for (const child of [...action.found, ...action.notFound]) {
+        const probe = expandAction(child, idx, idMap);
+        if (probe.kind === "needs_content")
+          return { kind: "needs_content", logicalType: `find_opportunity \u2192 ${child.type}`, reason: probe.reason };
+        if (probe.kind === "manual")
+          return { kind: "manual", logicalType: `find_opportunity \u2192 ${child.type}`, reason: probe.reason };
+      }
+      const findId = crypto.randomUUID();
+      const foundTId = crypto.randomUUID();
+      const notFoundTId = crypto.randomUUID();
+      const wireBranch = (children, transitionId) => {
+        const out = [];
+        children.forEach((child, ci) => {
+          const exp = expandAction(child, idx, idMap);
+          if (exp.kind !== "expanded") return;
+          exp.pendingRefs.forEach((r) => pendingRefs.push(r));
+          const node = exp.native;
+          node.id = crypto.randomUUID();
+          node.parent = transitionId;
+          node.parentKey = ci === 0 ? transitionId : out[ci - 1].id;
+          node.order = ci;
+          delete node.next;
+          out.push(node);
+        });
+        for (let k = 0; k < out.length - 1; k++) out[k].next = out[k + 1].id;
+        return out;
+      };
+      const foundNodes = wireBranch(action.found, foundTId);
+      const notFoundNodes = wireBranch(action.notFound, notFoundTId);
+      const makeTransition = (id, name, firstChildId) => ({
+        id,
+        type: "transition",
+        name,
+        cat: "transition",
+        parent: findId,
+        parentKey: findId,
+        attributes: {},
+        ...firstChildId ? { next: firstChildId } : {}
+      });
+      const pName = idx.pipelineName.get(action.pipelineRef) ?? action.pipelineRef;
+      const findNode = {
+        id: findId,
+        type: "find_opportunity",
+        name: `Find opportunity: ${pName}`,
+        cat: "multi-path",
+        workflowsActionType: "INTERNAL",
+        next: [foundTId, notFoundTId],
+        attributes: {
+          sorting: "latest",
+          type: "find_opportunity",
+          // Filter shape is DISTINCT from the update/create node: the field name is
+          // `pipeline_id` (underscore), the operator lives in `value`, the id in
+          // `secondValue` (captured from Lux "01"/"02").
+          __customInputFields__: [
+            { __customInputs__: {}, filterField: "pipeline_id", value: "eq", secondValue: pipelineId }
+          ],
+          __customInputs__: {},
+          cat: "multi-path",
+          convertToMultipath: true,
+          transitions: [
+            { id: foundTId, name: "Opportunity Found", fields: [], meta: { __branchKey__: "predefined_Opportunity Found" }, conditionType: "pre-defined" },
+            { id: notFoundTId, name: "Opportunity Not Found", fields: [], meta: { __branchKey__: "predefined_Opportunity Not Found" }, conditionType: "pre-defined" }
+          ],
+          __name__: "Find Opportunity"
+        }
+      };
+      return {
+        kind: "expanded",
+        pendingRefs,
+        native: findNode,
+        extraNodes: [
+          makeTransition(foundTId, "Opportunity Found", foundNodes[0]?.id),
+          ...foundNodes,
+          makeTransition(notFoundTId, "Opportunity Not Found", notFoundNodes[0]?.id),
+          ...notFoundNodes
+        ]
+      };
+    }
     case "goal_event": {
       return {
         kind: "expanded",
@@ -11760,47 +12037,112 @@ function triggerPlainEnglish(trigger, idx) {
       return `trigger type "${trigger.type}"`;
   }
 }
-function expandTrigger(trigger, idx) {
-  if (trigger.type === "contact_tag") {
-    if (!trigger.tagRef) return { kind: "manual", reason: "Set this workflow's contact-tag trigger in the GHL UI (the plan trigger has no tag)." };
-    const tagName = idx.tagName.get(trigger.tagRef) ?? trigger.tagRef;
-    return {
-      kind: "native",
-      trigger: {
+function expandTrigger(trigger, idx, idMap) {
+  const manual = (reason) => ({ kind: "manual", reason });
+  const native = (t, pendingRefs = []) => ({ kind: "native", trigger: t, pendingRefs });
+  switch (trigger.type) {
+    case "contact_tag": {
+      if (!trigger.tagRef) return manual("Set this workflow's contact-tag trigger in the GHL UI (the plan trigger has no tag).");
+      const tagName = idx.tagName.get(trigger.tagRef) ?? trigger.tagRef;
+      return native({
         name: "Contact Tag",
         type: "contact_tag",
         conditions: [{ operator: "index-of-true", field: "tagsAdded", value: tagName, title: "Tag Added", type: "select", id: "tag-added" }]
-      }
-    };
+      });
+    }
+    case "form_submission":
+    case "form_submitted": {
+      if (!trigger.formRef) return manual("Set this workflow's form-submission trigger in the GHL UI (the plan trigger has no form).");
+      const formId = resolveId(trigger.formRef, idMap);
+      return native({
+        name: "Form Submitted",
+        type: "form_submission",
+        conditions: [{ operator: "is-any-of", field: "form.id", value: [formId], title: "Form is", type: "string" }]
+      }, isPending(formId) ? [trigger.formRef] : []);
+    }
+    case "appointment": {
+      const status = trigger.appointmentStatus;
+      if (!status) return manual(`Set this workflow's appointment trigger in the GHL UI: ${triggerPlainEnglish(trigger, idx)} (the plan trigger has no appointmentStatus to fire on, e.g. confirmed / noshow).`);
+      return native({
+        name: `Appointment Status \u2014 ${status}`,
+        type: "appointment",
+        conditions: [
+          { operator: "==", field: "appointment.eventType", value: "normal", title: "Event Type", type: "select" },
+          { operator: "==", field: "appointment.status", value: status, title: "Appointment status is", type: "select" }
+        ]
+      });
+    }
+    case "customer_reply":
+    case "contact_replied": {
+      return native({ name: "Customer Replied", type: "customer_reply", conditions: [] });
+    }
+    case "pipeline_stage_updated": {
+      if (!trigger.pipelineRef || !trigger.stageRef) return manual("Set this workflow's pipeline-stage trigger in the GHL UI (the plan trigger needs both a pipeline and a stage).");
+      const pipelineId = resolveId(trigger.pipelineRef, idMap);
+      const stageId = resolveId(trigger.stageRef, idMap);
+      const pending = [];
+      if (isPending(pipelineId)) pending.push(trigger.pipelineRef);
+      if (isPending(stageId)) pending.push(trigger.stageRef);
+      return native({
+        name: "Pipeline Stage Changed",
+        type: "pipeline_stage_updated",
+        conditions: [
+          { operator: "==", field: "opportunity.pipelineId", value: pipelineId, title: "In pipeline", type: "select" },
+          { operator: "==", field: "opportunity.pipelineStageId", value: stageId, title: "Pipeline stage", type: "select" }
+        ]
+      }, pending);
+    }
+    case "inbound_webhook": {
+      return native({ name: "Inbound Webhook", type: "inbound_webhook", conditions: [] });
+    }
+    case "payment_received": {
+      return native({ name: "Payment Received", type: "payment_received", conditions: [] });
+    }
+    default:
+      return manual(`Set this workflow's trigger in the GHL UI: ${triggerPlainEnglish(trigger, idx)}, then publish. (Blueprint builds the workflow + all its steps as DRAFT; this trigger type isn't auto-built yet.)`);
   }
-  return {
-    kind: "manual",
-    reason: `Set this workflow's trigger in the GHL UI: ${triggerPlainEnglish(trigger, idx)}, then publish. (Blueprint builds the workflow + all its steps as DRAFT; only this trigger type isn't auto-built yet.)`
-  };
 }
 function expandWorkflow(workflow, idx, idMap, gatedBy) {
   const nativeActions = [];
   const manual = [];
   const needsContent = [];
   const pendingRefs = /* @__PURE__ */ new Set();
+  let branchEmitted = false;
   workflow.actions.forEach((a, i) => {
+    if (branchEmitted) {
+      manual.push({ index: i, logicalType: a.type, reason: "action follows a find_opportunity branch (which must be the last action) \u2014 not emitted to avoid an orphaned node" });
+      return;
+    }
     const exp = expandAction(a, idx, idMap);
     if (exp.kind === "expanded") {
       nativeActions.push(exp.native);
       exp.pendingRefs.forEach((r) => pendingRefs.add(r));
+      if (exp.extraNodes && exp.extraNodes.length) {
+        const baseOrder = nativeActions.length - 1;
+        exp.native.order = baseOrder;
+        for (const n of exp.extraNodes) {
+          if (n.cat === "transition") n.order = baseOrder + 1;
+          nativeActions.push(n);
+        }
+      }
     } else if (exp.kind === "manual") {
       manual.push({ index: i, logicalType: exp.logicalType, reason: exp.reason });
     } else {
       needsContent.push({ index: i, logicalType: exp.logicalType, reason: exp.reason });
     }
+    if (a.type === "find_opportunity") branchEmitted = true;
   });
   const splitInto = Math.max(1, Math.ceil(nativeActions.length / MAX_ACTIONS_PER_WORKFLOW));
   let nativeTrigger;
   let triggerManual;
   if (workflow.trigger) {
-    const t = expandTrigger(workflow.trigger, idx);
-    if (t.kind === "native") nativeTrigger = t.trigger;
-    else triggerManual = t.reason;
+    const t = expandTrigger(workflow.trigger, idx, idMap);
+    if (t.kind === "native") {
+      nativeTrigger = t.trigger;
+      t.pendingRefs.forEach((r) => pendingRefs.add(r));
+    } else {
+      triggerManual = t.reason;
+    }
   }
   return {
     ref: workflow.ref,
@@ -12078,11 +12420,13 @@ async function executeBackbone(plan, deps, opts = {}) {
   const idMap = {};
   const built = [];
   const manual = [];
+  const published = [];
   const halt = (atRef, type, reason) => ({
     ok: false,
     idMap,
     built,
     manual,
+    published,
     halted: { atRef, type, reason },
     deferred: deferredSections(plan)
   });
@@ -12375,35 +12719,56 @@ async function executeBackbone(plan, deps, opts = {}) {
   }
   const wfIndex = buildRefIndex(plan);
   const wfIdMap = new Map(Object.entries(idMap));
-  for (const wf of plan.workflows ?? []) {
+  const planWorkflows = plan.workflows ?? [];
+  const createdSlots = [];
+  const savedWfIds = /* @__PURE__ */ new Set();
+  const rollbackUnsavedShells = async () => {
+    const failedDeletes = [];
+    for (const slot of createdSlots) {
+      if (savedWfIds.has(slot.id)) continue;
+      try {
+        await deps.deleteWorkflow(slot.id);
+      } catch {
+        failedDeletes.push(slot.id);
+      }
+      delete idMap[slot.ref];
+      wfIdMap.delete(slot.ref);
+    }
+    return failedDeletes;
+  };
+  const orphanSuffix = (failed) => failed.length ? ` WARNING: could not delete orphan shell workflow(s) ${failed.join(", ")} \u2014 delete them in GHL before re-running.` : "";
+  const toSave = [];
+  for (const wf of planWorkflows) {
     let workflows;
     try {
       workflows = await deps.listWorkflows();
     } catch (e) {
-      return halt(wf.ref, "workflow", `could not read existing workflows: ${msg(e)}`);
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `could not read existing workflows: ${msg(e)}.${orphanSuffix(f)}`);
     }
     const matches = workflows.filter((w) => norm2(w.name) === norm2(wf.name));
     if (matches.length > 1) {
-      return halt(wf.ref, "workflow", `${matches.length} existing workflows are named "${wf.name}" \u2014 ambiguous, cannot safely bind ${wf.ref}. Resolve the duplicate in GHL, then re-run.`);
-    }
-    const expansion = expandWorkflow(wf, wfIndex, wfIdMap, []);
-    if (expansion.pendingRefs.length) {
-      return halt(wf.ref, "workflow", `workflow "${wf.name}" references objects that weren't built/resolved: ${expansion.pendingRefs.join(", ")}. Cannot build it.`);
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `${matches.length} existing workflows are named "${wf.name}" \u2014 ambiguous, cannot safely bind ${wf.ref}. Resolve the duplicate in GHL, then re-run.${orphanSuffix(f)}`);
     }
     if (matches.length === 1) {
       const exId = matches[0].id;
-      if (expansion.nativeActions.length > 0) {
-        let existingCount = -1;
+      const planHasActions = expandWorkflow(wf, wfIndex, wfIdMap, []).nativeActions.length > 0;
+      if (planHasActions) {
+        let existingCount;
         try {
           existingCount = await deps.getWorkflowActionCount(exId);
-        } catch {
-          existingCount = -1;
+        } catch (e) {
+          const f = await rollbackUnsavedShells();
+          return halt(wf.ref, "workflow", `could not read the existing workflow named "${wf.name}" to tell whether it's an empty orphan (${msg(e)}) \u2014 refusing to bind it blindly (Blueprint never modifies an existing workflow, and binding an orphan would ship a stepless workflow). Re-run.${orphanSuffix(f)}`);
         }
         if (existingCount === 0) {
-          return halt(wf.ref, "workflow", `a workflow named "${wf.name}" already exists but has NO actions \u2014 likely an empty orphan from a failed prior run (or a name collision). Delete it in GHL, then re-run. (Blueprint never modifies an existing workflow.)`);
+          const f = await rollbackUnsavedShells();
+          return halt(wf.ref, "workflow", `a workflow named "${wf.name}" already exists but has NO actions \u2014 likely an empty orphan from a failed prior run (or a name collision). Delete it in GHL, then re-run. (Blueprint never modifies an existing workflow.)${orphanSuffix(f)}`);
         }
       }
       idMap[wf.ref] = exId;
+      wfIdMap.set(wf.ref, exId);
       built.push({ ref: wf.ref, type: "workflow", name: wf.name, status: "existing", realId: exId });
       continue;
     }
@@ -12411,9 +12776,24 @@ async function executeBackbone(plan, deps, opts = {}) {
     try {
       wfId = await deps.createWorkflow(wf.name);
     } catch (e) {
-      return halt(wf.ref, "workflow", `create failed: ${msg(e)}`);
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `create failed: ${msg(e)}.${orphanSuffix(f)}`);
+    }
+    if (!wfId) {
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `workflow create returned no id.${orphanSuffix(f)}`);
+    }
+    createdSlots.push({ ref: wf.ref, id: wfId });
+    idMap[wf.ref] = wfId;
+    wfIdMap.set(wf.ref, wfId);
+    toSave.push({ wf, id: wfId });
+  }
+  for (const { wf, id: wfId } of toSave) {
+    const expansion = expandWorkflow(wf, wfIndex, wfIdMap, []);
+    if (expansion.pendingRefs.length) {
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `workflow "${wf.name}" references objects that weren't built/resolved: ${expansion.pendingRefs.join(", ")}. Cannot build it.${orphanSuffix(f)}`);
     }
-    if (!wfId) return halt(wf.ref, "workflow", "workflow create returned no id");
     const triggers = expansion.nativeTrigger ? [expansion.nativeTrigger] : [];
     try {
       await deps.saveWorkflow(wfId, { actions: expansion.nativeActions, triggers, stopOnResponse: wf.stopOnResponse });
@@ -12422,25 +12802,24 @@ async function executeBackbone(plan, deps, opts = {}) {
         if (count === 0) throw new Error("saved but no actions persisted (read-after-write)");
       }
     } catch (e) {
-      let rolledBack = false;
+      const f = await rollbackUnsavedShells();
+      return halt(wf.ref, "workflow", `actions/trigger save failed; the partial workflow${createdSlots.length > 1 ? " (and any other unsaved shells)" : ""} was rolled back: ${msg(e)}.${orphanSuffix(f)}`);
+    }
+    savedWfIds.add(wfId);
+    built.push({ ref: wf.ref, type: "workflow", name: wf.name, status: "created", realId: wfId });
+    if (opts.publishWorkflows && !opts.gatedWorkflowRefs?.has(wf.ref)) {
       try {
-        await deps.deleteWorkflow(wfId);
-        rolledBack = true;
-      } catch {
+        await deps.publishWorkflow(wfId);
+        published.push(wf.ref);
+      } catch (e) {
+        manual.push({ ref: wf.ref, type: "workflow-publish", name: wf.name, reason: `[${wf.name}] built successfully but auto-publish failed (${msg(e)}) \u2014 publish it manually in GHL.` });
       }
-      return halt(
-        wf.ref,
-        "workflow",
-        rolledBack ? `actions/trigger save failed; the partial workflow was rolled back (deleted): ${msg(e)}` : `actions/trigger save failed AND the rollback delete also failed \u2014 manually delete the orphan workflow (id ${wfId}) in GHL before re-running: ${msg(e)}`
-      );
     }
-    idMap[wf.ref] = wfId;
-    built.push({ ref: wf.ref, type: "workflow", name: wf.name, status: "created", realId: wfId });
     if (expansion.triggerManual) manual.push({ ref: wf.ref, type: "workflow-trigger", name: wf.name, reason: `[${wf.name}] ${expansion.triggerManual}` });
     for (const nc of expansion.needsContent) manual.push({ ref: wf.ref, type: "workflow-action", name: wf.name, reason: `[${wf.name}] ${nc.reason}` });
     for (const m of expansion.manual) manual.push({ ref: wf.ref, type: "workflow-action", name: wf.name, reason: `[${wf.name}] ${m.reason}` });
   }
-  return { ok: true, idMap, built, manual, deferred: deferredSections(plan) };
+  return { ok: true, idMap, built, manual, published, deferred: deferredSections(plan) };
 }
 async function buildSimple(objects, type, list, create, nameOf, pollForNew, idMap, built) {
   if (objects.length === 0) return null;
@@ -12854,6 +13233,9 @@ ${text2.slice(0, 300)}`);
     },
     deleteWorkflow: async (workflowId) => {
       await builderClient.deleteWorkflow(workflowId);
+    },
+    publishWorkflow: async (workflowId) => {
+      await builderClient.publishWorkflow(workflowId);
     }
   };
 }
@@ -12986,7 +13368,11 @@ function registerIntakeToBuildTools(server2, client, builderClient) {
             }
           }
           const deps = makeExecuteDeps(client, builderClient, activeLocation);
-          const exec = await executeBackbone(typedPlan, deps);
+          const gatedWorkflowRefs = new Set(result.workflows.filter((w) => w.gatedBy.length > 0).map((w) => w.ref));
+          const exec = await executeBackbone(typedPlan, deps, {
+            publishWorkflows: publishWorkflows ?? false,
+            gatedWorkflowRefs
+          });
           const externalWiring = buildExternalWiring(typedPlan, exec.idMap, activeLocation);
           const execManualLines = exec.manual.map((m) => `[${m.type}] ${m.reason}`);
           const manualLines = result.workflows.flatMap((w) => [
@@ -13005,12 +13391,14 @@ function registerIntakeToBuildTools(server2, client, builderClient) {
             built: exec.built,
             manual: exec.manual,
             idMap: exec.idMap,
+            published: exec.published,
+            publishNote: exec.published.length ? `Auto-published ${exec.published.length} workflow(s) live (you opted in). Any gated workflow stays DRAFT until its handoff is met.` : exec.built.some((b) => b.type === "workflow" && b.status === "created") ? "Workflows were built as DRAFT (the safe default). Review them in GHL and publish, or re-run with publishWorkflows:true to auto-publish ungated ones." : "No workflows were built in this run (none in the plan, or all already existed and were left untouched).",
             externalWiring,
             externalWiringNote: externalWiring ? "For each target:\"external\" funnel: plug these into your self-hosted site form + lead bridge (templates/external-funnel/). custom formFields carry the VERIFIED GHL field id your form's `custom` object must send (never name-guess keys); add a triggerTag to start the speed-to-lead workflow; bookingUrl is the GHL calendar widget for the CTA. Anything in `unresolved` wasn't built yet \u2014 re-run after it is." : void 0,
             deferred: exec.deferred,
             deferredNote: 'execute builds the WHOLE plan live: CRM backbone (pipelines, custom fields, tags, custom values), calendars, forms, funnels (GHL-built = funnel + named steps), and workflows (DRAFT, with all steps incl. opportunity create/move). Remaining manual steps are surfaced per item: staff-requiring calendars in multi-user accounts, GHL funnel page content/design, EXTERNAL funnels (target:"external" \u2014 the user builds + hosts the site themselves and wires it back; not built here), workflow triggers other than contact_tag, and publishing the DRAFT workflows.',
             nextManualSteps: [...execManualLines, ...manualLines, ...handoffLines],
-            summary: exec.ok ? `Built ${exec.built.filter((b) => b.status === "created").length} new object(s), bound ${exec.built.filter((b) => b.status === "existing").length} existing.${exec.manual.length ? ` ${exec.manual.length} item(s) need a manual step (see nextManualSteps).` : ""}${exec.deferred.length ? " Deferred: " + exec.deferred.map((d) => `${d.count} ${d.section}`).join(", ") + " (manual)." : ""}` : `HALTED at ${exec.halted?.atRef} (${exec.halted?.reason}). ${exec.built.length} object(s) were created before the halt \u2014 see idMap to resume or clean up. NEVER-CLOBBER means a re-run will bind those, not duplicate them.`
+            summary: exec.ok ? `Built ${exec.built.filter((b) => b.status === "created").length} new object(s), bound ${exec.built.filter((b) => b.status === "existing").length} existing.${exec.published.length ? ` Published ${exec.published.length} workflow(s) live.` : exec.built.some((b) => b.type === "workflow" && b.status === "created") ? " Workflows are DRAFT (opt in with publishWorkflows to auto-publish)." : ""}${exec.manual.length ? ` ${exec.manual.length} item(s) need a manual step (see nextManualSteps).` : ""}${exec.deferred.length ? " Deferred: " + exec.deferred.map((d) => `${d.count} ${d.section}`).join(", ") + " (manual)." : ""}` : `HALTED at ${exec.halted?.atRef} (${exec.halted?.reason}). ${exec.built.length} object(s) were created before the halt \u2014 see idMap to resume or clean up. NEVER-CLOBBER means a re-run will bind those, not duplicate them.`
           });
         }
         const collisions = result.items.filter((i) => i.status === "existing");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.46.0",
+  "version": "3.48.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 220 tools — full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",