@elitedcs/ghl-mcp 3.69.0 → 3.70.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 3.70.0 — a clean validation now means something
+
+A subscriber built an Instagram-comment-to-DM workflow, ran `validate_workflow`, got
+back "0 issues, 0 warnings", published it, and watched the Create/Update Opportunity
+step do nothing: no card in the pipeline, no card on the contact, and the workflow
+carried on to the next step as if it had worked. They were right about why. The step
+had only a pipeline and a stage. GoHighLevel's own documentation lists Opportunity
+Name, Source and Status as mandatory for the combined Create/Update Opportunity step
+to create anything; with only pipeline and stage it moves a card the contact already
+has, and a brand-new lead has none. The
+validator was checking that every id existed. It never asked whether the step could
+do what its name says.
+
+**`validate_workflow` and `audit_workflows` now check what a step can do.** A
+Create/Update Opportunity step with only pipeline + stage and no opportunity in
+context comes back as a warning that says exactly that and names the fix. "In
+context" is worked out from the workflow itself: a create step earlier on the same
+path, a Find Opportunity step whose "Opportunity Found" branch the step sits in, or a
+trigger that fires on an opportunity. A step that carries an Opportunity Name and a
+Status is taken as one that creates and is left alone; a Name with no Status is
+reported as unverified with the thing to check. Before release the check ran against
+every workflow in five of our own accounts (106 workflows) and flagged none; the run
+is recorded in `docs/proofs/2026-08-26-validate-runtime-noop.md`. A path the validator
+cannot trace, or a field this version does not know, is reported as unverified rather
+than passed. `warnings_count` now includes these findings, the report says how many
+steps were checked (`actions_checked`), and `audit_workflows` lists them under
+`shape_warnings` with counts in its summary; `status` still flips only on an error,
+never on a warning. A `task_notification` step spelled with the underscore, which
+saves, validates and is skipped at runtime, is that kind of error now.
+
+**Claude now builds the right node.** GoHighLevel has separated Create Opportunity
+from Update Opportunity and is phasing the combined action out for new workflows. The
+builder knows the newer Create Opportunity node (`internal_create_opportunity`),
+validates it, normalizes it to the shape proven to create a card, and the reference
+material Claude reads before building a workflow now says which node creates a card
+and which one moves it, instead of pointing both jobs at the same node. (#57)
+
 ## 3.69.0 — the cockpit hardened, and the plan you approved is the plan that runs
 
 Two items in this release exist because someone tried to break the cockpit

package/dist/index.js

@@ -1118,6 +1118,35 @@ function normalizeRemoveFromWorkflowAction(action) {
   }
   return { ...action, attributes: next };
 }
+function normalizeInternalCreateOpportunityAction(action) {
+  if (action.type !== "internal_create_opportunity") return action;
+  const attrIn = action.attributes && typeof action.attributes === "object" ? action.attributes : {};
+  const fieldsIn = Array.isArray(attrIn.__customInputFields__) ? attrIn.__customInputFields__ : [];
+  let pipelineId = typeof attrIn.pipelineId === "string" ? attrIn.pipelineId : void 0;
+  const __customInputFields__ = [];
+  for (const raw of fieldsIn) {
+    const f = raw && typeof raw === "object" ? raw : {};
+    if (f.filterField === "pipelineId") {
+      if (!pipelineId && typeof f.value === "string") pipelineId = f.value;
+      continue;
+    }
+    __customInputFields__.push({
+      ...f,
+      __customInputs__: f.__customInputs__ && typeof f.__customInputs__ === "object" ? f.__customInputs__ : {},
+      dataType: typeof f.dataType === "string" ? f.dataType : "SINGLE_OPTIONS",
+      valueFieldType: typeof f.valueFieldType === "string" ? f.valueFieldType : "select"
+    });
+  }
+  const attributes = {
+    ...attrIn,
+    type: "internal_create_opportunity",
+    ...pipelineId ? { pipelineId } : {},
+    __customInputs__: attrIn.__customInputs__ && typeof attrIn.__customInputs__ === "object" ? attrIn.__customInputs__ : {},
+    __customInputFields__
+  };
+  delete attributes.workflowsActionType;
+  return { ...action, workflowsActionType: "INTERNAL", attributes };
+}
 function normalizeInternalUpdateOpportunityAction(action) {
   if (action.type !== "internal_update_opportunity") return action;
   const attrIn = action.attributes && typeof action.attributes === "object" ? action.attributes : {};
@@ -1202,6 +1231,26 @@ function validateActionChain(actions, existingIds) {
         }
         break;
       }
+      case "internal_create_opportunity": {
+        const isRoundTripped = hasId(action) && (existingIds ? existingIds.has(action.id) : true);
+        if (!isRoundTripped) {
+          const cif = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+          const listed = (ff) => cif.find((f) => f && f.filterField === ff);
+          const pipelineId = typeof attr.pipelineId === "string" ? attr.pipelineId : listed("pipelineId")?.value;
+          if (!isIdShaped(pipelineId)) {
+            throw new Error(
+              `Create opportunity action "${action.name}" needs a valid 'pipelineId' (an id, not a name) in attributes. Use get_pipelines / list_pipelines_full to find it.`
+            );
+          }
+          const stage = listed("pipelineStageId");
+          if (!stage || !isIdShaped(stage.value)) {
+            throw new Error(
+              `Create opportunity action "${action.name}" needs a valid pipelineStageId entry (an id, not a name) in '__customInputFields__'. Use get_pipelines / list_pipelines_full to find the IDs. (A missing or non-existent id makes GHL silently fail this action and can kill the rest.)`
+            );
+          }
+        }
+        break;
+      }
       case "remove_from_workflow":
         if (!attr.workflowId || !Array.isArray(attr.workflow_id)) throw new Error(`Remove from workflow action "${action.name}" needs BOTH 'workflowId' string AND 'workflow_id' array.`);
         break;
@@ -1941,7 +1990,7 @@ ${errorBody}`
        */
       buildActionChain(actions, existingIds) {
         validateActionChain(actions, existingIds);
-        const linked = actions.map(normalizeRemoveFromWorkflowAction).map(normalizeInternalUpdateOpportunityAction).map((action, i) => {
+        const linked = actions.map(normalizeRemoveFromWorkflowAction).map(normalizeInternalUpdateOpportunityAction).map(normalizeInternalCreateOpportunityAction).map((action, i) => {
           const copy = { ...action };
           if (!copy.id) {
             copy.id = crypto.randomUUID();
@@ -12881,6 +12930,109 @@ var init_template_deployer = __esm({
 });
 
 // src/tools/validators.ts
+function traceOpportunityContext(node, byId2) {
+  let cur = node;
+  const seen = /* @__PURE__ */ new Set();
+  for (let hops = 0; hops < MAX_TRACE_HOPS; hops++) {
+    const pk = cur.parentKey;
+    if (typeof pk !== "string" || !pk) return "none";
+    if (seen.has(pk)) return "dangling";
+    seen.add(pk);
+    const parent = byId2.get(pk);
+    if (!parent) return "dangling";
+    const ptype = typeof parent.type === "string" ? parent.type : "";
+    if (OPPORTUNITY_CREATING_TYPES.has(ptype)) return "create";
+    if (ptype === "transition") {
+      const ownerId = typeof parent.parentKey === "string" ? parent.parentKey : typeof parent.parent === "string" ? parent.parent : "";
+      const owner = ownerId ? byId2.get(ownerId) : void 0;
+      if (owner && owner.type === "find_opportunity") {
+        const meta = parent.attributes?.meta ?? {};
+        const label = `${typeof parent.name === "string" ? parent.name : ""} ${typeof meta.__branchKey__ === "string" ? meta.__branchKey__ : ""}`.toLowerCase();
+        if (label.includes("opportunity not found")) return "not_found";
+        if (label.includes("opportunity found")) return "found";
+      }
+    }
+    cur = parent;
+  }
+  return "dangling";
+}
+function checkActionShapes(workflow) {
+  const findings = [];
+  const actions = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : [];
+  const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
+  const triggerGivesOpportunity = triggers.some((t) => typeof t.type === "string" && OPPORTUNITY_CONTEXT_TRIGGERS.has(t.type));
+  const byId2 = /* @__PURE__ */ new Map();
+  for (const a of actions) if (typeof a.id === "string") byId2.set(a.id, a);
+  for (const a of actions) {
+    const type = typeof a.type === "string" ? a.type : "unknown";
+    const name = typeof a.name === "string" ? a.name : "unnamed action";
+    const id = typeof a.id === "string" ? a.id : name;
+    const where = `action "${name}" (${type})`;
+    if (type === "task_notification") {
+      findings.push({
+        severity: "error",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} saves and validates but is SKIPPED at runtime \u2014 the type must be "task-notification" (hyphen). Re-save it with the hyphenated type.`
+      });
+      continue;
+    }
+    if (type !== "internal_update_opportunity") continue;
+    const attr = a.attributes ?? {};
+    const cif = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+    const keys = cif.map((f) => f && typeof f.filterField === "string" ? f.filterField : "").filter(Boolean);
+    const has = (k) => cif.some((f) => f && f.filterField === k && typeof f.value === "string" && f.value.trim() !== "");
+    if (has("name") && has("status")) continue;
+    if (has("name")) {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} carries an opportunity name but no status \u2014 GoHighLevel lists Name, Source and Status as mandatory to create a card. Open the step in the GHL builder and confirm Status (and Source) are set, or use Create Opportunity (internal_create_opportunity).`
+      });
+      continue;
+    }
+    const unknown = keys.filter((k) => !KNOWN_UPDATE_OPP_FIELDS.has(k));
+    if (unknown.length) {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} carries field(s) this version does not know (${unknown.join(", ")}) \u2014 could not judge whether it can create an opportunity.`
+      });
+      continue;
+    }
+    const ctx = traceOpportunityContext(a, byId2);
+    if (ctx === "create" || ctx === "found") continue;
+    if (ctx === "dangling") {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} could not be traced back to the trigger (a parentKey points to a missing step) \u2014 could not judge whether an opportunity is in context.`
+      });
+      continue;
+    }
+    if (ctx === "none" && triggerGivesOpportunity) continue;
+    findings.push({
+      severity: "warning",
+      category: "action_shape",
+      id,
+      where,
+      message: `${where} cannot create an opportunity: it has only pipeline + stage${has("status") ? " + status" : ""}. It moves a card the contact already has in that pipeline; a contact without one (a new lead) gets no card and the workflow continues as if it worked. To create a card use Create Opportunity (internal_create_opportunity); to move one, put Find Opportunity before this step or trigger on the opportunity. GoHighLevel is phasing the combined Create/Update action out.`
+    });
+  }
+  return findings;
+}
+function summarizeFindings(findings) {
+  const issues = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.filter((f) => f.severity === "warning" && (f.category === "custom_field" || f.category === "action_shape")).length;
+  return { status: issues > 0 ? "issues_found" : "ok", issues_count: issues, warnings_count: warnings };
+}
 function collectMergeTagKeys(value, out) {
   if (typeof value === "string") {
     MERGE_TAG_RE.lastIndex = 0;
@@ -13294,28 +13446,29 @@ function registerValidatorTools(server2, client, builderClient) {
   }
   server2.tool(
     "validate_workflow",
-    "Pre-flight ID validation for ONE deployed GHL workflow. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use BEFORE publish_workflow when a workflow was edited, or when a published workflow stops behaving. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions. Never reports a false break \u2014 anything it cannot fully verify is marked 'unverified', not 'error'.",
+    "Pre-flight validation for ONE deployed GHL workflow. Also flags steps that cannot do what their name says at runtime (a Create/Update Opportunity step with only pipeline + stage cannot create a card; task_notification is skipped) \u2014 read every finding with severity warning, not just issues_count. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use BEFORE publish_workflow when a workflow was edited, or when a published workflow stops behaving. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions. Never reports a false break \u2014 anything it cannot fully verify is marked 'unverified', not 'error'.",
     { workflowId: import_zod53.z.string().describe("The workflow ID to validate.") },
     async ({ workflowId }) => {
       try {
         const workflow = await builderClient.getWorkflow(workflowId);
         if (!workflow) return errorResponse(new Error(`Workflow ${workflowId} not found`));
         const refs = [];
+        const shape = checkActionShapes(workflow);
+        const actionsChecked = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates.length : 0;
         for (const t of Array.isArray(workflow.triggers) ? workflow.triggers : []) extractFromTrigger(t, refs);
         for (const a of Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : []) extractFromAction(a, refs);
         if (refs.length === 0)
-          return jsonResponse({ workflowId, workflowName: workflow.name, status: "ok", references_scanned: 0, issues_count: 0, warnings_count: 0, findings: [] });
+          return jsonResponse({ workflowId, workflowName: workflow.name, ...summarizeFindings(shape), references_scanned: 0, actions_checked: actionsChecked, findings: shape });
         const needWorkflows = refs.some((r) => r.kind === "workflow");
         const catalog = needWorkflows ? await fullWorkflowCatalog(builderClient) : { ids: /* @__PURE__ */ new Set(), complete: true };
         const lookups = await fetchAndBuildLookups(client, builderClient, client.defaultLocationId, { ids: catalog.ids, complete: catalog.complete });
-        const findings = checkRefs(refs, workflowId, lookups);
+        const findings = [...shape, ...checkRefs(refs, workflowId, lookups)];
         const report = {
           workflowId,
           workflowName: workflow.name,
-          status: findings.some((f) => f.severity === "error") ? "issues_found" : "ok",
+          ...summarizeFindings(findings),
           references_scanned: refs.length,
-          issues_count: findings.filter((f) => f.severity === "error").length,
-          warnings_count: findings.filter((f) => f.severity === "warning" && f.category === "custom_field").length,
+          actions_checked: actionsChecked,
           findings
         };
         return jsonResponse(report);
@@ -13326,7 +13479,7 @@ function registerValidatorTools(server2, client, builderClient) {
   );
   server2.tool(
     "audit_workflows",
-    "Account-wide silent-failure audit: scans EVERY workflow in the current location for references to pipelines/stages/custom-fields/users/workflows/forms/calendars/surveys that don't exist \u2014 the GHL bug where one bad ID silently kills that action and all actions after it. Returns a prioritized report of what's broken, what couldn't be scanned, and what couldn't be fully verified. Conservative: never reports a false break (uncertain checks are 'unverified', not 'broken'). Read-only.",
+    "Account-wide silent-failure audit: also flags steps that cannot do what their name says (a Create/Update Opportunity step with only pipeline + stage cannot create a card) under shape_warnings \u2014 read them. Scans EVERY workflow in the current location for references to pipelines/stages/custom-fields/users/workflows/forms/calendars/surveys that don't exist \u2014 the GHL bug where one bad ID silently kills that action and all actions after it. Returns a prioritized report of what's broken, what couldn't be scanned, and what couldn't be fully verified. Conservative: never reports a false break (uncertain checks are 'unverified', not 'broken'). Read-only.",
     {},
     async () => {
       try {
@@ -13348,7 +13501,7 @@ function registerValidatorTools(server2, client, builderClient) {
               const wf = await builderClient.getWorkflow(row.id);
               const refs = auditOneWorkflow(wf, row.id, lookups);
               if (refs.length === 0) zeroRefCount++;
-              const findings = checkRefs(refs, row.id, lookups);
+              const findings = [...checkActionShapes(wf), ...checkRefs(refs, row.id, lookups)];
               results.push({ id: row.id, name: wf.name ?? row.name, status: wf.status, refs: refs.length, findings });
             } catch (e) {
               unscannable.push({ id: row.id, name: row.name, reason: e instanceof Error ? e.message : String(e) });
@@ -13359,6 +13512,8 @@ function registerValidatorTools(server2, client, builderClient) {
         const errorsTotal = withErrors.reduce((n, w) => n + w.errors.length, 0);
         const withWarnings = results.filter((r) => r.findings.some((f) => f.severity === "warning" && f.category === "custom_field")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, warnings: r.findings.filter((f) => f.severity === "warning" && f.category === "custom_field") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
         const warningsTotal = withWarnings.reduce((n, w) => n + w.warnings.length, 0);
+        const withShapeWarnings = results.filter((r) => r.findings.some((f) => f.severity === "warning" && f.category === "action_shape")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, warnings: r.findings.filter((f) => f.severity === "warning" && f.category === "action_shape") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
+        const shapeWarningsTotal = withShapeWarnings.reduce((n, w) => n + w.warnings.length, 0);
         const unverifiedCats = ALL_CATEGORIES.filter((c) => lookups.status[c] !== "loaded");
         const unverifiedRefs = results.reduce((n, r) => n + r.findings.filter((f) => f.severity === "unverified").length, 0);
         return jsonResponse({
@@ -13372,6 +13527,8 @@ function registerValidatorTools(server2, client, builderClient) {
             errors_total: errorsTotal,
             workflows_with_merge_field_warnings: withWarnings.length,
             merge_field_warnings_total: warningsTotal,
+            workflows_with_shape_warnings: withShapeWarnings.length,
+            shape_warnings_total: shapeWarningsTotal,
             workflows_unscannable: unscannable.length,
             workflows_zero_references: zeroRefCount,
             unverified: { categories_unloaded: unverifiedCats, references_unverified: unverifiedRefs },
@@ -13379,12 +13536,14 @@ function registerValidatorTools(server2, client, builderClient) {
           },
           workflows_with_issues: withErrors,
           merge_field_warnings: withWarnings,
+          shape_warnings: withShapeWarnings,
           unscannable,
           notes: [
             ...catalog.complete ? [] : ["Workflow catalog exceeded the pagination backstop \u2014 some workflow-id references shown as unverified."],
             ...catalog.rows.length > SCAN_CAP ? [`Only the first ${SCAN_CAP} workflows were scanned (account has ${catalog.rows.length}).`] : [],
             ...unverifiedCats.length ? [`Could not fully load: ${unverifiedCats.join(", ")} \u2014 references to those are 'unverified', not 'broken'. Re-run.`] : [],
             ...warningsTotal ? [`${warningsTotal} {{contact.X}} merge tag(s) reference a field that no longer exists \u2014 these render BLANK in the message but do NOT stop the workflow (warning, not a break). See merge_field_warnings.`] : [],
+            ...shapeWarningsTotal ? [`${shapeWarningsTotal} Create/Update Opportunity step(s) have only pipeline + stage \u2014 they cannot create a card for a new contact (see shape_warnings).`] : [],
             "workflow_goal, goto, and unrecognized condition types are not deeply checked in this version."
           ]
         });
@@ -13394,7 +13553,7 @@ function registerValidatorTools(server2, client, builderClient) {
     }
   );
 }
-var import_zod53, ALL_CATEGORIES, STANDARD_CONTACT_FIELDS, MERGE_TAG_RE;
+var import_zod53, ALL_CATEGORIES, OPPORTUNITY_CONTEXT_TRIGGERS, OPPORTUNITY_CREATING_TYPES, KNOWN_UPDATE_OPP_FIELDS, MAX_TRACE_HOPS, STANDARD_CONTACT_FIELDS, MERGE_TAG_RE;
 var init_validators = __esm({
   "src/tools/validators.ts"() {
     "use strict";
@@ -13403,6 +13562,16 @@ var init_validators = __esm({
     init_api_schemas();
     init_id_shape();
     ALL_CATEGORIES = ["pipeline", "stage", "custom_field", "user", "workflow", "form", "calendar", "survey"];
+    OPPORTUNITY_CONTEXT_TRIGGERS = /* @__PURE__ */ new Set([
+      "opportunity_status_changed",
+      "opportunity_created",
+      "opportunity_changed",
+      "pipeline_stage_updated",
+      "opportunity_decay"
+    ]);
+    OPPORTUNITY_CREATING_TYPES = /* @__PURE__ */ new Set(["internal_create_opportunity", "create_opportunity"]);
+    KNOWN_UPDATE_OPP_FIELDS = /* @__PURE__ */ new Set(["pipelineId", "pipelineStageId", "name", "status", "source", "monetaryValue"]);
+    MAX_TRACE_HOPS = 200;
     STANDARD_CONTACT_FIELDS = /* @__PURE__ */ new Set([
       "first_name",
       "firstname",
@@ -18799,7 +18968,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.69.0",
+      version: "3.70.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 242 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.69.0",
+  "version": "3.70.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 242 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",

package/templates/action-schemas.json

@@ -106,7 +106,7 @@
         "selectedUser": "USER_ID"
       }
     },
-    "notes": "Nested 'notification' object REQUIRED. selectedUser MUST be a real user ID — GHL now REJECTS an empty string (live-verified 2026-08-06; the old 'empty = all users' behavior is gone). Use get_users to find IDs. EMAIL CHANNEL (verified live 2026-07-20, PWDJ workflow e91f28da): attributes.type is 'email' (NOT 'notification'), nested key is 'email' (NOT 'notification'), body field is 'html' (NOT 'body'), selectedUser is an ARRAY of user IDs, include attachments:[] and isCloned:false. A 'send_email' discriminator inside a 'notification' object saves but silently never sends.",
+    "notes": "Nested 'notification' object REQUIRED. selectedUser MUST be a real user ID \u2014 GHL now REJECTS an empty string (live-verified 2026-08-06; the old 'empty = all users' behavior is gone). Use get_users to find IDs. EMAIL CHANNEL (verified live 2026-07-20, PWDJ workflow e91f28da): attributes.type is 'email' (NOT 'notification'), nested key is 'email' (NOT 'notification'), body field is 'html' (NOT 'body'), selectedUser is an ARRAY of user IDs, include attachments:[] and isCloned:false. A 'send_email' discriminator inside a 'notification' object saves but silently never sends.",
     "emailChannelExample": {
       "type": "email",
       "email": {
@@ -166,6 +166,27 @@
     },
     "notes": "Requires BOTH workflowId (string) AND workflow_id (ARRAY with same ID). Also needs type: 'remove_from_workflow' inside attributes. Derived from GHL UI."
   },
+  "internal_create_opportunity": {
+    "example": {
+      "type": "internal_create_opportunity",
+      "workflowsActionType": "INTERNAL",
+      "attributes": {
+        "type": "internal_create_opportunity",
+        "pipelineId": "PIPELINE_ID",
+        "__customInputFields__": [
+          {
+            "__customInputs__": {},
+            "dataType": "SINGLE_OPTIONS",
+            "filterField": "pipelineStageId",
+            "value": "STAGE_ID",
+            "valueFieldType": "select"
+          }
+        ],
+        "__customInputs__": {}
+      }
+    },
+    "notes": "CREATES a card (GHL's newer separate 'Create Opportunity' action). This minimal shape is live-proven to create at runtime (2026-07-24): pipelineId at the ATTRIBUTES level (not inside __customInputFields__), __customInputFields__ carrying pipelineStageId, workflowsActionType:'INTERNAL' at the NODE level. UI-built nodes also carry name/status/monetaryValue entries and work \u2014 copy a working node field-for-field rather than inventing entries. Without a name entry the card is named from the contact (observed live 2026-07-24). Use THIS for 'create an opportunity for the new lead'."
+  },
   "internal_update_opportunity": {
     "example": {
       "__customInputFields__": [
@@ -185,7 +206,7 @@
       "workflowsActionType": "INTERNAL",
       "type": "internal_update_opportunity"
     },
-    "notes": "CREATABLE from scratch (re-enabled v3.41.0). The discriminator workflowsActionType:'INTERNAL' MUST sit at the NODE level, never nested in attributes \u2014 a nested copy makes GHL reject the node as 'action has a corrupted type' and silently fail the whole save. update_workflow_actions normalizes this for you (hoists workflowsActionType to the node level, scaffolds allowBackward + __customInputs__, gives each __customInputFields__ entry an __customInputs__). The shape below (workflowsActionType at the node level alongside type/name/attributes) is correct for both creating and round-tripping. Use pipeline and stage IDs (not names) \u2014 get_pipelines / list_pipelines_full to find them FIRST. CRITICAL: if the pipelineId or pipelineStageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions. A synthesized node needs BOTH a pipelineId and a pipelineStageId entry; a node round-tripped via get_workflow_full keeps its id and passes through unchanged."
+    "notes": "GHL's combined 'Create/Update Opportunity'. With only pipelineId + pipelineStageId it CANNOT create a card \u2014 it moves one the contact already has; a contact with no opportunity (a new lead) gets nothing and the workflow continues as if it worked (customer report 2026-08-26). It creates only when __customInputFields__ also carry Opportunity name (GHL's doc: Name, Source, Status mandatory to create). GoHighLevel is phasing this combined action out for new workflows, so prefer internal_create_opportunity to create; use this node after find_opportunity, after a create step in the same workflow, or on an opportunity trigger. CREATABLE from scratch (re-enabled v3.41.0). The discriminator workflowsActionType:'INTERNAL' MUST sit at the NODE level, never nested in attributes \u2014 a nested copy makes GHL reject the node as 'action has a corrupted type' and silently fail the whole save. update_workflow_actions normalizes this for you (hoists workflowsActionType to the node level, scaffolds allowBackward + __customInputs__, gives each __customInputFields__ entry an __customInputs__). The shape below (workflowsActionType at the node level alongside type/name/attributes) is correct for both creating and round-tripping. Use pipeline and stage IDs (not names) \u2014 get_pipelines / list_pipelines_full to find them FIRST. CRITICAL: if the pipelineId or pipelineStageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions. A synthesized node needs BOTH a pipelineId and a pipelineStageId entry; a node round-tripped via get_workflow_full keeps its id and passes through unchanged."
   },
   "_if_else_branching": {
     "notes": "if_else is a node type discriminator only. Do not send a single flat if_else action.",