@elitedcs/ghl-mcp 3.32.0 → 3.34.0

package/dist/index.js

@@ -31,9 +31,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.32.0",
+      version: "3.34.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
-      description: "GoHighLevel MCP Server for Claude. 217 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
+      description: "GoHighLevel MCP Server for Claude. 218 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -47,7 +47,7 @@ var require_package = __commonJS({
         "CHANGELOG.md"
       ],
       scripts: {
-        build: "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/index.js --packages=external",
+        build: "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.js --packages=external",
         setup: "node setup-wizard.mjs",
         start: "node dist/index.js",
         dev: "tsc --watch",
@@ -85,7 +85,7 @@ var require_package = __commonJS({
         access: "public"
       },
       engines: {
-        node: ">=22"
+        node: ">=20"
       },
       dependencies: {
         "@modelcontextprotocol/sdk": "^1.12.1",
@@ -106,8 +106,8 @@ var require_package = __commonJS({
 
 // src/index.ts
 var dotenv2 = __toESM(require("dotenv"));
-var path5 = __toESM(require("path"));
-var fs5 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
+var fs6 = __toESM(require("fs"));
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
@@ -171,8 +171,8 @@ var GHLClient = class {
       Version: version || GHL_API_VERSION
     };
   }
-  buildUrl(path6, params) {
-    const url = new URL(path6, GHL_BASE_URL);
+  buildUrl(path7, params) {
+    const url = new URL(path7, GHL_BASE_URL);
     if (params) {
       for (const [key, value] of Object.entries(params)) {
         if (value !== void 0 && value !== null) {
@@ -182,8 +182,8 @@ var GHLClient = class {
     }
     return url.toString();
   }
-  async request(method, path6, options = {}, attempt = 0) {
-    const url = this.buildUrl(path6, options.params);
+  async request(method, path7, options = {}, attempt = 0) {
+    const url = this.buildUrl(path7, options.params);
     const headers = this.buildHeaders(options.version);
     const fetchOptions = {
       method,
@@ -201,14 +201,14 @@ var GHLClient = class {
     } catch (error) {
       clearTimeout(timeout);
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout (30s): ${method} ${path6}`);
+        throw new Error(`Request timeout (30s): ${method} ${path7}`);
       }
       if (!options.noRetry && attempt < MAX_RETRIES) {
         const delay4 = computeRetryDelay(null, attempt, BASE_DELAY_MS);
-        process.stderr.write(`[ghl-mcp] Network error on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
+        process.stderr.write(`[ghl-mcp] Network error on ${method} ${path7}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
         await new Promise((r) => setTimeout(r, delay4));
-        return this.request(method, path6, options, attempt + 1);
+        return this.request(method, path7, options, attempt + 1);
       }
       throw error;
     } finally {
@@ -216,10 +216,10 @@ var GHLClient = class {
     }
     if (!options.noRetry && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
       const delay4 = computeRetryDelay(response.headers.get("Retry-After"), attempt, BASE_DELAY_MS);
-      process.stderr.write(`[ghl-mcp] ${response.status} on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
+      process.stderr.write(`[ghl-mcp] ${response.status} on ${method} ${path7}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
       await new Promise((r) => setTimeout(r, delay4));
-      return this.request(method, path6, options, attempt + 1);
+      return this.request(method, path7, options, attempt + 1);
     }
     if (!response.ok) {
       let errorBody = "";
@@ -228,7 +228,7 @@ var GHLClient = class {
       } catch {
       }
       throw new Error(
-        `GHL API Error ${response.status} ${response.statusText}: ${method} ${path6}
+        `GHL API Error ${response.status} ${response.statusText}: ${method} ${path7}
 ${errorBody}`
       );
     }
@@ -240,20 +240,20 @@ ${errorBody}`
       return { message: text };
     }
   }
-  async get(path6, options) {
-    return this.request("GET", path6, options);
+  async get(path7, options) {
+    return this.request("GET", path7, options);
   }
-  async post(path6, options) {
-    return this.request("POST", path6, options);
+  async post(path7, options) {
+    return this.request("POST", path7, options);
   }
-  async put(path6, options) {
-    return this.request("PUT", path6, options);
+  async put(path7, options) {
+    return this.request("PUT", path7, options);
   }
-  async patch(path6, options) {
-    return this.request("PATCH", path6, options);
+  async patch(path7, options) {
+    return this.request("PATCH", path7, options);
   }
-  async delete(path6, options) {
-    return this.request("DELETE", path6, options);
+  async delete(path7, options) {
+    return this.request("DELETE", path7, options);
   }
   /**
    * Helper: resolves locationId from args or falls back to default
@@ -262,7 +262,7 @@ ${errorBody}`
     const id = providedId || this.defaultLocationId;
     if (!id) {
       throw new Error(
-        "locationId is required. Provide it as a parameter or set GHL_LOCATION_ID in your .env file."
+        "locationId is required. Provide it as a parameter, run switch_location to pick a registered sub-account (list_registered_locations shows what's registered), or set GHL_LOCATION_ID in your .env file."
       );
     }
     return id;
@@ -300,6 +300,15 @@ var CredentialsSchema = import_zod.z.object({
   signed_attestation: import_zod.z.string().optional()
 });
 function appDataDir() {
+  const override = process.env.GHL_MCP_CONFIG_DIR?.trim();
+  if (override) {
+    if (!path.isAbsolute(override)) {
+      throw new Error(
+        `GHL_MCP_CONFIG_DIR must be an absolute path (got "${override}"). Use e.g. /data/ghl-mcp in a container, with a volume mounted at /data.`
+      );
+    }
+    return override;
+  }
   const home = os.homedir();
   if (process.platform === "darwin") {
     return path.join(home, "Library", "Application Support", APP_NAME);
@@ -406,6 +415,8 @@ var TokenRegistryDataSchema = import_zod2.z.object({
 });
 var TokenRegistry = class _TokenRegistry {
   data;
+  loadFailure = null;
+  lastSaveError = null;
   filePath;
   constructor(filePath) {
     if (filePath) {
@@ -454,18 +465,28 @@ var TokenRegistry = class _TokenRegistry {
         return TokenRegistryDataSchema.parse(JSON.parse(raw));
       }
     } catch (error) {
+      let backupNote = "backup also failed \u2014 the corrupted file is still at " + this.filePath;
       try {
         const backupPath = this.filePath + ".corrupted." + Date.now();
         fs2.copyFileSync(this.filePath, backupPath);
+        backupNote = `backed up to ${backupPath}`;
         process.stderr.write(`[ghl-mcp] ERROR: Token registry corrupted. Backed up to ${backupPath}
 `);
       } catch {
       }
+      this.loadFailure = `Token registry could not be loaded (${backupNote}). All sub-account registrations are unavailable this session \u2014 re-register via register_location, or restore the backup over ${this.filePath} and restart.`;
       process.stderr.write(`[ghl-mcp] Warning: Could not load token registry: ${error}
 `);
     }
     return { tokens: {} };
   }
+  /**
+   * Non-null when the registry file existed but could not be parsed at
+   * startup (we fell back to an empty registry). Surfaced by health_check.
+   */
+  getLoadFailure() {
+    return this.loadFailure;
+  }
   save() {
     const tmpPath = `${this.filePath}.tmp.${process.pid}.${(0, import_crypto.randomBytes)(8).toString("hex")}`;
     try {
@@ -482,15 +503,25 @@ var TokenRegistry = class _TokenRegistry {
         fs2.chmodSync(this.filePath, 384);
       } catch {
       }
+      this.lastSaveError = null;
     } catch (error) {
       try {
         fs2.unlinkSync(tmpPath);
       } catch {
       }
+      this.lastSaveError = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[ghl-mcp] Warning: Could not save token registry: ${error}
 `);
     }
   }
+  /**
+   * Non-null when the MOST RECENT save() failed (cleared by a later success).
+   * The seed CLI checks this after every write to turn the server's
+   * warn-and-continue policy into a hard exit code.
+   */
+  getLastSaveError() {
+    return this.lastSaveError;
+  }
   /**
    * Get the API key for a specific location
    */
@@ -503,6 +534,13 @@ var TokenRegistry = class _TokenRegistry {
   getAgencyKey() {
     return this.data.agencyKey;
   }
+  /**
+   * Store the agency/company-scoped API key (snapshots, agency-wide reads).
+   */
+  setAgencyKey(key) {
+    this.data.agencyKey = key;
+    this.save();
+  }
   /**
    * Get Firebase config
    */
@@ -1412,7 +1450,7 @@ var WorkflowBuilderClient = class _WorkflowBuilderClient {
     }
   }
   async performTokenRefresh() {
-    const url = `${FIREBASE_TOKEN_URL}?key=${this.firebaseApiKey}`;
+    const url = `${FIREBASE_TOKEN_URL}?key=${encodeURIComponent(this.firebaseApiKey)}`;
     const body = `grant_type=refresh_token&refresh_token=${encodeURIComponent(this.refreshToken)}`;
     const response = await fetch(url, {
       method: "POST",
@@ -1924,6 +1962,48 @@ function escapeRegex(str) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function paginationInfo(opts) {
+  const { returned, limit, nextHint } = opts;
+  const total = typeof opts.total === "number" ? opts.total : void 0;
+  if (total !== void 0) {
+    const complete = returned >= total;
+    return {
+      returned,
+      limit,
+      total,
+      complete,
+      ...complete ? {} : {
+        note: `INCOMPLETE: showing ${returned} of ${total} total. ${nextHint ?? "Fetch further pages before treating this as the full list."}`
+      }
+    };
+  }
+  if (returned < limit) {
+    return { returned, limit, complete: true };
+  }
+  return {
+    returned,
+    limit,
+    complete: "unknown",
+    note: `POSSIBLY INCOMPLETE: returned ${returned} which hit the limit of ${limit} \u2014 more may exist. ${nextHint ?? "Fetch further pages before treating this as the full list."}`
+  };
+}
+function annotateListResponse(raw, listKey, limit, nextHint) {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const obj = raw;
+  const list = obj[listKey];
+  if (!Array.isArray(list)) return raw;
+  let total;
+  const meta = obj.meta;
+  if (typeof meta === "object" && meta !== null) {
+    const metaTotal = meta.total;
+    if (typeof metaTotal === "number") total = metaTotal;
+  }
+  if (total === void 0 && typeof obj.total === "number") total = obj.total;
+  return {
+    ...obj,
+    _pagination: paginationInfo({ returned: list.length, limit, total, nextHint })
+  };
+}
 function safeTool(server2, name, description, schema, handler) {
   server2.tool(name, description, schema, async (args) => {
     try {
@@ -2017,7 +2097,16 @@ function registerContactTools(server2, client) {
           order
         }
       });
-      return ContactSearchResponseSchema.parse(raw);
+      const parsed = ContactSearchResponseSchema.parse(raw);
+      return {
+        ...parsed,
+        _pagination: paginationInfo({
+          returned: parsed.contacts.length,
+          limit: limit ?? 20,
+          total: parsed.meta?.total,
+          nextHint: "Pass startAfter + startAfterId from this response's meta to fetch the next page (both are required to advance)."
+        })
+      };
     }
   );
   safeTool(
@@ -2308,7 +2397,7 @@ function registerConversationTools(server2, client) {
     },
     async ({ locationId: locationId2, contactId, assignedTo, query, status, limit, startAfterDate }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return await client.get("/conversations/search", {
+      const raw = await client.get("/conversations/search", {
         params: {
           locationId: resolvedLocationId,
           contactId,
@@ -2319,6 +2408,12 @@ function registerConversationTools(server2, client) {
           startAfterDate
         }
       });
+      return annotateListResponse(
+        raw,
+        "conversations",
+        limit ?? 20,
+        "Pass startAfterDate from the last conversation's dateUpdated to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -2463,7 +2558,7 @@ function registerOpportunityTools(server2, client) {
     },
     async (args) => {
       const locationId2 = client.resolveLocationId(args.locationId);
-      return await client.get("/opportunities/search", {
+      const raw = await client.get("/opportunities/search", {
         params: {
           location_id: locationId2,
           pipeline_id: args.pipelineId,
@@ -2480,6 +2575,12 @@ function registerOpportunityTools(server2, client) {
           startDate: args.startDate
         }
       });
+      return annotateListResponse(
+        raw,
+        "opportunities",
+        args.limit ?? 20,
+        "Pass startAfter + startAfterId from this response's meta to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -3581,7 +3682,13 @@ function registerInvoiceTools(server2, client) {
       if (startAt !== void 0) params.startAt = startAt;
       if (endAt !== void 0) params.endAt = endAt;
       if (search !== void 0) params.search = search;
-      return client.get("/invoices/", { params });
+      const raw = await client.get("/invoices/", { params });
+      return annotateListResponse(
+        raw,
+        "invoices",
+        limit ?? 10,
+        "Pass offset (current offset + limit) to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -3617,8 +3724,8 @@ function registerInvoiceTools(server2, client) {
         currency: import_zod17.z.string().describe("Currency code (e.g. USD)")
       })).describe("Invoice line items"),
       discount: import_zod17.z.object({
-        type: import_zod17.z.string().optional(),
-        value: import_zod17.z.number().optional()
+        type: import_zod17.z.string().optional().describe("Discount type: 'percentage' or 'fixed'."),
+        value: import_zod17.z.number().optional().describe("Discount amount: percent (0-100) when type=percentage, currency amount when type=fixed.")
       }).optional().describe("Discount to apply"),
       termsNotes: import_zod17.z.string().optional().describe("Terms and notes for the invoice"),
       title: import_zod17.z.string().optional().describe("Invoice title")
@@ -3654,8 +3761,8 @@ function registerInvoiceTools(server2, client) {
         currency: import_zod17.z.string().describe("Currency code (e.g. USD)")
       })).optional().describe("Invoice line items"),
       discount: import_zod17.z.object({
-        type: import_zod17.z.string().optional(),
-        value: import_zod17.z.number().optional()
+        type: import_zod17.z.string().optional().describe("Discount type: 'percentage' or 'fixed'."),
+        value: import_zod17.z.number().optional().describe("Discount amount: percent (0-100) when type=percentage, currency amount when type=fixed.")
       }).optional().describe("Discount to apply"),
       termsNotes: import_zod17.z.string().optional().describe("Terms and notes for the invoice"),
       title: import_zod17.z.string().optional().describe("Invoice title")
@@ -4281,16 +4388,16 @@ function registerEmailTools(server2, client) {
 function registerEmailBuilderInternalTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function builderRequest(method, path6, body) {
+  async function builderRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${EMAIL_BUILDER_BASE}${path6}`, {
+    const response = await fetch(`${EMAIL_BUILDER_BASE}${path7}`, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Email Builder API Error ${response.status}: ${method} /emails/builder${path6}
+      throw new Error(`Email Builder API Error ${response.status}: ${method} /emails/builder${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -5212,7 +5319,10 @@ function registerWorkflowBuilderTools(server2, client) {
     async ({ limit, skip }) => {
       try {
         const result = await client.listWorkflows(limit ?? 50, skip ?? 0);
-        return jsonResponse(result);
+        const hint = "Pass skip (current skip + limit) to fetch the next page.";
+        let annotated = annotateListResponse(result, "rows", limit ?? 50, hint);
+        if (annotated === result) annotated = annotateListResponse(result, "workflows", limit ?? 50, hint);
+        return jsonResponse(annotated);
       } catch (error) {
         return errorResponse(error);
       }
@@ -5544,23 +5654,23 @@ var import_zod34 = require("zod");
 function registerFunnelBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function internalGet(path6) {
-    return client.request("GET", path6);
+  async function internalGet(path7) {
+    return client.request("GET", path7);
   }
-  async function internalPost(path6, body) {
-    return client.request("POST", path6, body);
+  async function internalPost(path7, body) {
+    return client.request("POST", path7, body);
   }
-  async function internalPut(path6, body) {
-    return client.request("PUT", path6, body);
+  async function internalPut(path7, body) {
+    return client.request("PUT", path7, body);
   }
-  async function internalDelete(path6) {
-    return client.request("DELETE", path6);
+  async function internalDelete(path7) {
+    return client.request("DELETE", path7);
   }
-  async function funnelRequest(method, path6, body) {
+  async function funnelRequest(method, path7, body) {
     const headers = await client.buildHeaders();
     headers.Origin = "https://app.gohighlevel.com";
     headers.Referer = "https://app.gohighlevel.com/";
-    const url = `https://backend.leadconnectorhq.com/funnels${path6}`;
+    const url = `https://backend.leadconnectorhq.com/funnels${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -5568,7 +5678,7 @@ function registerFunnelBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Funnel API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Funnel API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -5860,9 +5970,9 @@ function buildUpdateFormBody(name, formData) {
 function registerFormBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function formRequest(method, path6, body) {
+  async function formRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `https://backend.leadconnectorhq.com/forms${path6}`;
+    const url = `https://backend.leadconnectorhq.com/forms${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -5870,7 +5980,7 @@ function registerFormBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Form API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Form API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -5984,10 +6094,10 @@ ${text2}`);
     },
     async ({ formId, limit, skip }) => {
       try {
-        let path6 = `/submissions?locationId=${client.locationId}&limit=${limit ?? 20}`;
-        if (formId) path6 += `&formId=${formId}`;
-        if (skip) path6 += `&skip=${skip}`;
-        const result = await formRequest("GET", path6);
+        let path7 = `/submissions?locationId=${client.locationId}&limit=${limit ?? 20}`;
+        if (formId) path7 += `&formId=${formId}`;
+        if (skip) path7 += `&skip=${skip}`;
+        const result = await formRequest("GET", path7);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
@@ -6003,9 +6113,9 @@ var import_zod36 = require("zod");
 function registerPipelineBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function pipelineRequest(method, path6, body) {
+  async function pipelineRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `https://backend.leadconnectorhq.com/opportunities/pipelines${path6}`;
+    const url = `https://backend.leadconnectorhq.com/opportunities/pipelines${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
       options.body = JSON.stringify(body);
@@ -6013,7 +6123,7 @@ function registerPipelineBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Pipeline API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Pipeline API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -6822,6 +6932,60 @@ The API key could not access location ${locationId2}. Make sure:
       }
     }
   );
+  server2.tool(
+    "register_agency_key",
+    "Store the AGENCY-level (company-scoped) API key in the token registry. This key powers agency-wide tools: list_snapshots, create_snapshot_share_link, and list_available_locations across all sub-accounts. Create it at the AGENCY level in GHL (Agency Settings > Private Integrations) \u2014 it is different from a sub-account's key. The key is validated before saving.",
+    {
+      apiKey: import_zod38.z.string().describe("The agency-level Private Integration API key (starts with 'pit-'). Must be created in AGENCY settings, not inside a sub-account.")
+    },
+    async ({ apiKey: apiKey2 }) => {
+      if (!registry2) {
+        return {
+          content: [{ type: "text", text: "Token registry not available. Check .ghl-tokens.json file." }],
+          isError: true
+        };
+      }
+      const testClient = new GHLClient({ apiKey: apiKey2 });
+      try {
+        const probe = await testClient.get("/locations/search", { params: { limit: 1, skip: 0 } });
+        const locations = probe?.locations;
+        if (!Array.isArray(locations)) {
+          throw new Error(
+            "the key was accepted by GHL but the response is not an agency location-search envelope (no locations array) \u2014 refusing to store it as the agency key"
+          );
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to validate the agency key: ${message}
+
+Make sure:
+1. The Private Integration was created at the AGENCY level (Agency Settings > Private Integrations), not inside a sub-account
+2. The key is correct (it can only be copied once when created)
+3. The integration has the locations scope enabled`
+            }
+          ],
+          isError: true
+        };
+      }
+      const hadKey = Boolean(registry2.getAgencyKey());
+      registry2.setAgencyKey(apiKey2);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Agency key ${hadKey ? "replaced" : "registered"}: ${apiKey2.substring(0, 12)}...
+Saved to the token registry.
+
+Agency-wide tools now available: list_snapshots, create_snapshot_share_link, and list_available_locations (across all sub-accounts).`
+          }
+        ]
+      };
+    }
+  );
   server2.tool(
     "unregister_location",
     "Remove a GHL sub-account from the token registry.",
@@ -7521,9 +7685,9 @@ var OBJECT_KEYS = ["contacts", "opportunity"];
 function registerSmartListTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function smartListRequest(method, path6, body) {
+  async function smartListRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `${SMARTLIST_BASE}${path6}`;
+    const url = `${SMARTLIST_BASE}${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -7531,7 +7695,7 @@ function registerSmartListTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Smart Lists API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Smart Lists API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -7663,12 +7827,12 @@ var REPUTATION_BASE = "https://backend.leadconnectorhq.com/reputation";
 function registerReputationTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function reputationRequest(method, path6) {
+  async function reputationRequest(method, path7) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${REPUTATION_BASE}${path6}`, { method, headers });
+    const response = await fetch(`${REPUTATION_BASE}${path7}`, { method, headers });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Reputation API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Reputation API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -7783,16 +7947,16 @@ var MEMBERSHIP_BASE = "https://backend.leadconnectorhq.com/membership";
 function registerMembershipTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function membershipRequest(path6, method = "GET", body) {
+  async function membershipRequest(path7, method = "GET", body) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${MEMBERSHIP_BASE}${path6}`, {
+    const response = await fetch(`${MEMBERSHIP_BASE}${path7}`, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Membership API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Membership API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -8345,6 +8509,11 @@ ${errors.join("\n")}` : "\nNo errors!",
 
 // src/tools/validators.ts
 var import_zod47 = require("zod");
+var ALL_CATEGORIES = ["pipeline", "stage", "custom_field", "user", "workflow", "form", "calendar", "survey"];
+var ID_SHAPE = /^[A-Za-z0-9]{17,}$/;
+function isIdShaped(s) {
+  return typeof s === "string" && ID_SHAPE.test(s);
+}
 function extractFromTrigger(trigger, refs) {
   const triggerName = String(trigger.name ?? trigger.type ?? "unnamed trigger");
   const where = `trigger "${triggerName}"`;
@@ -8354,10 +8523,21 @@ function extractFromTrigger(trigger, refs) {
     const field = typeof c.field === "string" ? c.field : null;
     const value = c.value;
     if (!field || value === void 0 || value === null) continue;
+    const childWhere = `${where} \u2192 conditions[${i}] (field=${field})`;
+    if (field.startsWith("contact.")) {
+      const suffix = field.slice("contact.".length);
+      if (suffix === "assignedTo") {
+        for (const v of Array.isArray(value) ? value : [value]) {
+          if (isIdShaped(v)) refs.push({ kind: "user", id: v, where: childWhere });
+        }
+      } else if (isIdShaped(suffix)) {
+        refs.push({ kind: "custom_field", id: suffix, where: childWhere });
+      }
+      continue;
+    }
     const valueAsArray = Array.isArray(value) ? value : [value];
     for (const v of valueAsArray) {
       if (typeof v !== "string") continue;
-      const childWhere = `${where} \u2192 conditions[${i}] (field=${field})`;
       switch (field) {
         case "opportunity.pipelineId":
           refs.push({ kind: "pipeline", id: v, where: childWhere });
@@ -8366,7 +8546,6 @@ function extractFromTrigger(trigger, refs) {
           refs.push({ kind: "stage", id: v, where: childWhere });
           break;
         case "opportunity.assignedTo":
-        case "contact.assignedTo":
           refs.push({ kind: "user", id: v, where: childWhere });
           break;
         case "workflow.id":
@@ -8384,17 +8563,18 @@ function extractFromTrigger(trigger, refs) {
       }
     }
   }
-  const triggerActions = Array.isArray(trigger.actions) ? trigger.actions : [];
-  for (let i = 0; i < triggerActions.length; i++) {
-    const a = triggerActions[i];
-    if (a.type === "add_to_workflow" && typeof a.workflow_id === "string") {
-      refs.push({
-        kind: "workflow",
-        id: a.workflow_id,
-        where: `${where} \u2192 actions[${i}] (add_to_workflow)`
-      });
+}
+function customInputId(attr, filterFields) {
+  const arr = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+  for (const raw of arr) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const c = raw;
+    if (typeof c.filterField === "string" && filterFields.includes(c.filterField)) {
+      if (isIdShaped(c.secondValue)) return c.secondValue;
+      if (isIdShaped(c.value)) return c.value;
     }
   }
+  return void 0;
 }
 function extractFromAction(action, refs) {
   const type = typeof action.type === "string" ? action.type : "unknown";
@@ -8402,258 +8582,267 @@ function extractFromAction(action, refs) {
   const where = `action "${name}" (${type})`;
   const attr = action.attributes ?? {};
   switch (type) {
-    case "update_contact_field": {
+    // ── Contact custom fields (only id-shaped values; standard names skipped) ──
+    case "update_contact_field":
+    case "create_update_contact": {
       const fields = Array.isArray(attr.fields) ? attr.fields : [];
       for (let i = 0; i < fields.length; i++) {
         const f = fields[i];
-        if (typeof f.field === "string") {
-          refs.push({
-            kind: "custom_field",
-            id: f.field,
-            where: `${where} \u2192 fields[${i}]`
-          });
-        }
+        if (isIdShaped(f?.field)) refs.push({ kind: "custom_field", id: f.field, where: `${where} \u2192 fields[${i}]` });
       }
       break;
     }
+    // ── User refs ──
     case "internal_notification": {
       const notif = attr.notification ?? {};
-      if (typeof notif.selectedUser === "string" && notif.selectedUser.trim() !== "") {
-        refs.push({
-          kind: "user",
-          id: notif.selectedUser,
-          where: `${where} \u2192 notification.selectedUser`
-        });
+      if (isIdShaped(notif.selectedUser))
+        refs.push({ kind: "user", id: notif.selectedUser, where: `${where} \u2192 notification.selectedUser` });
+      const sms = attr.sms ?? {};
+      const smsUsers = Array.isArray(sms.selectedUser) ? sms.selectedUser : [];
+      for (let i = 0; i < smsUsers.length; i++) {
+        if (isIdShaped(smsUsers[i])) refs.push({ kind: "user", id: smsUsers[i], where: `${where} \u2192 sms.selectedUser[${i}]` });
       }
       break;
     }
-    case "task_notification": {
-      if (typeof attr.assignedTo === "string" && attr.assignedTo.trim() !== "") {
-        refs.push({
-          kind: "user",
-          id: attr.assignedTo,
-          where: `${where} \u2192 assignedTo`
-        });
-      }
+    case "task_notification":
+    case "task-notification": {
+      if (isIdShaped(attr.assignedTo))
+        refs.push({ kind: "user", id: attr.assignedTo, where: `${where} \u2192 assignedTo` });
       break;
     }
+    // ── Workflow refs ──
     case "remove_from_workflow": {
-      if (typeof attr.workflowId === "string") {
-        refs.push({
-          kind: "workflow",
-          id: attr.workflowId,
-          where: `${where} \u2192 workflowId`
-        });
-      }
-      const workflowIdArr = Array.isArray(attr.workflow_id) ? attr.workflow_id : [];
-      for (let i = 0; i < workflowIdArr.length; i++) {
-        const v = workflowIdArr[i];
-        if (typeof v === "string") {
-          refs.push({
-            kind: "workflow",
-            id: v,
-            where: `${where} \u2192 workflow_id[${i}]`
-          });
-        }
-      }
+      if (typeof attr.workflowId === "string") refs.push({ kind: "workflow", id: attr.workflowId, where: `${where} \u2192 workflowId` });
+      const arr = Array.isArray(attr.workflow_id) ? attr.workflow_id : [];
+      for (let i = 0; i < arr.length; i++) if (typeof arr[i] === "string") refs.push({ kind: "workflow", id: arr[i], where: `${where} \u2192 workflow_id[${i}]` });
+      break;
+    }
+    // ── Opportunity refs — FOUR distinct shapes ──
+    case "internal_create_opportunity": {
+      if (isIdShaped(attr.pipelineId)) refs.push({ kind: "pipeline", id: attr.pipelineId, where: `${where} \u2192 pipelineId` });
+      const stage = customInputId(attr, ["pipelineStageId"]);
+      if (stage) refs.push({ kind: "stage", id: stage, where: `${where} \u2192 __customInputFields__.pipelineStageId` });
+      break;
+    }
+    case "create_opportunity": {
+      if (isIdShaped(attr.pipeline_id)) refs.push({ kind: "pipeline", id: attr.pipeline_id, where: `${where} \u2192 pipeline_id` });
+      if (isIdShaped(attr.pipeline_stage_id)) refs.push({ kind: "stage", id: attr.pipeline_stage_id, where: `${where} \u2192 pipeline_stage_id` });
       break;
     }
     case "internal_update_opportunity": {
-      const customInputs = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
-      for (let i = 0; i < customInputs.length; i++) {
-        const c = customInputs[i];
-        if (typeof c.value !== "string") continue;
-        if (c.filterField === "pipelineId") {
-          refs.push({ kind: "pipeline", id: c.value, where: `${where} \u2192 __customInputFields__[${i}].pipelineId` });
-        } else if (c.filterField === "pipelineStageId") {
-          refs.push({ kind: "stage", id: c.value, where: `${where} \u2192 __customInputFields__[${i}].pipelineStageId` });
+      const pipe = customInputId(attr, ["pipelineId"]);
+      if (pipe) refs.push({ kind: "pipeline", id: pipe, where: `${where} \u2192 __customInputFields__.pipelineId` });
+      const stage = customInputId(attr, ["pipelineStageId"]);
+      if (stage) refs.push({ kind: "stage", id: stage, where: `${where} \u2192 __customInputFields__.pipelineStageId` });
+      break;
+    }
+    case "find_opportunity": {
+      const pipe = customInputId(attr, ["pipeline_id", "pipelineId"]);
+      if (pipe) refs.push({ kind: "pipeline", id: pipe, where: `${where} \u2192 __customInputFields__.pipeline_id` });
+      break;
+    }
+    // ── if_else condition node: custom-field id is conditionSubType (NOT conditionValue) ──
+    case "if_else": {
+      const branches = Array.isArray(attr.branches) ? attr.branches : [];
+      for (const b of branches) {
+        const segs = b && typeof b === "object" && Array.isArray(b.segments) ? b.segments : [];
+        for (const s of segs) {
+          const conds = s && typeof s === "object" && Array.isArray(s.conditions) ? s.conditions : [];
+          for (const raw of conds) {
+            if (typeof raw !== "object" || raw === null) continue;
+            const c = raw;
+            if (c.conditionType === "contact_detail" && c.conditionSubType !== "tags" && isIdShaped(c.conditionSubType)) {
+              refs.push({ kind: "custom_field", id: c.conditionSubType, where: `${where} \u2192 if_else condition (custom field)` });
+            }
+          }
         }
       }
       break;
     }
   }
 }
+function collectIds(envelope, listKeys) {
+  const ids = /* @__PURE__ */ new Set();
+  let arr = null;
+  if (Array.isArray(envelope)) arr = envelope;
+  else if (envelope && typeof envelope === "object") {
+    const e = envelope;
+    for (const k of listKeys) if (Array.isArray(e[k])) {
+      arr = e[k];
+      break;
+    }
+  }
+  if (arr) for (const item of arr) {
+    if (typeof item === "object" && item !== null) {
+      const o = item;
+      const id = typeof o.id === "string" ? o.id : typeof o._id === "string" ? o._id : null;
+      if (id) ids.add(id);
+    }
+  }
+  return { ids, found: arr !== null };
+}
+async function fetchAndBuildLookups(client, builderClient, locationId2, workflowExistence) {
+  const fetches = {
+    pipelines: client.get("/opportunities/pipelines", { params: { locationId: locationId2 } }),
+    customFields: client.get(`/locations/${locationId2}/customFields`),
+    users: client.get("/users/", { params: { locationId: locationId2 } }),
+    forms: client.get("/forms/", { params: { locationId: locationId2 } }),
+    calendars: client.get("/calendars/", { params: { locationId: locationId2 } }),
+    surveys: client.get("/surveys/", { params: { locationId: locationId2 } })
+  };
+  const keys = Object.keys(fetches);
+  const settled = await Promise.allSettled(Object.values(fetches));
+  const data = {};
+  const failed = /* @__PURE__ */ new Set();
+  for (let i = 0; i < keys.length; i++) {
+    if (settled[i].status === "fulfilled") data[keys[i]] = settled[i].value;
+    else {
+      data[keys[i]] = null;
+      failed.add(keys[i]);
+    }
+  }
+  const status = {
+    pipeline: "loaded",
+    stage: "loaded",
+    custom_field: "loaded",
+    user: "loaded",
+    workflow: "loaded",
+    form: "loaded",
+    calendar: "loaded",
+    survey: "loaded"
+  };
+  const pipelines = /* @__PURE__ */ new Set();
+  const stages = /* @__PURE__ */ new Set();
+  if (failed.has("pipelines")) {
+    status.pipeline = "failed";
+    status.stage = "failed";
+  } else {
+    try {
+      const parsed = PipelinesResponseSchema.parse(data.pipelines);
+      for (const p of parsed.pipelines) {
+        pipelines.add(p.id);
+        for (const s of p.stages) stages.add(s.id);
+      }
+    } catch {
+      status.pipeline = "unparseable";
+      status.stage = "unparseable";
+    }
+  }
+  function setFrom(key, cat, listKeys) {
+    if (failed.has(key)) {
+      status[cat] = "failed";
+      return /* @__PURE__ */ new Set();
+    }
+    const { ids, found } = collectIds(data[key], listKeys);
+    if (!found) status[cat] = "unparseable";
+    return ids;
+  }
+  const custom_field = setFrom("customFields", "custom_field", ["customFields"]);
+  const user = setFrom("users", "user", ["users"]);
+  const form = setFrom("forms", "form", ["forms"]);
+  const calendar = setFrom("calendars", "calendar", ["calendars"]);
+  const survey = setFrom("surveys", "survey", ["surveys"]);
+  status.workflow = workflowExistence.complete ? "loaded" : "incomplete";
+  return { pipelines, stages, custom_field, user, workflow: workflowExistence.ids, form, calendar, survey, status };
+}
+function auditOneWorkflow(workflow, selfId, lookups) {
+  const refs = [];
+  const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
+  for (const t of triggers) extractFromTrigger(t, refs);
+  const actions = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : [];
+  for (const a of actions) extractFromAction(a, refs);
+  return refs;
+}
+function setForCategory(lookups, kind) {
+  switch (kind) {
+    case "pipeline":
+      return lookups.pipelines;
+    case "stage":
+      return lookups.stages;
+    default:
+      return lookups[kind];
+  }
+}
+function checkRefs(refs, selfId, lookups) {
+  const findings = [];
+  for (const ref of refs) {
+    const st = lookups.status[ref.kind];
+    if (st !== "loaded") {
+      findings.push({
+        severity: "unverified",
+        category: ref.kind,
+        id: ref.id,
+        where: ref.where,
+        message: `${ref.kind} reference could not be verified \u2014 the ${ref.kind} list ${st === "incomplete" ? "is too large to fully load" : "failed to load or was unreadable"}. Re-run; not reported as broken.`
+      });
+      continue;
+    }
+    const valid = setForCategory(lookups, ref.kind).has(ref.id);
+    if (valid) {
+      if (ref.kind === "workflow" && ref.id === selfId)
+        findings.push({ severity: "warning", category: ref.kind, id: ref.id, where: ref.where, message: `${ref.kind} id "${ref.id}" is valid (self-reference).` });
+    } else {
+      findings.push({
+        severity: "error",
+        category: ref.kind,
+        id: ref.id,
+        where: ref.where,
+        message: `${ref.kind} id "${ref.id}" does not exist in this location \u2014 GHL will silently skip this action and all subsequent actions when the workflow runs.`
+      });
+    }
+  }
+  return findings;
+}
+async function fullWorkflowCatalog(builderClient) {
+  const ids = /* @__PURE__ */ new Set();
+  const rows = [];
+  const limit = 100;
+  let skip = 0;
+  let complete = true;
+  for (let page = 0; page < 50; page++) {
+    const resp = await builderClient.listWorkflows(limit, skip);
+    const found = Array.isArray(resp?.rows) || Array.isArray(resp?.workflows) || Array.isArray(resp);
+    if (!found) {
+      if (page === 0) throw new Error("Could not read the workflow list (unexpected response shape) \u2014 try again.");
+      complete = false;
+      break;
+    }
+    const arr = Array.isArray(resp?.rows) ? resp.rows : Array.isArray(resp?.workflows) ? resp.workflows : Array.isArray(resp) ? resp : [];
+    for (const w of arr) {
+      if (w && typeof w === "object") {
+        const o = w;
+        const id = typeof o._id === "string" ? o._id : typeof o.id === "string" ? o.id : null;
+        if (id) {
+          ids.add(id);
+          rows.push({ id, name: typeof o.name === "string" ? o.name : id });
+        }
+      }
+    }
+    if (arr.length < limit) break;
+    skip += limit;
+    if (page === 49) complete = false;
+  }
+  return { ids, rows, complete };
+}
 function registerValidatorTools(server2, client, builderClient) {
   if (!builderClient) return;
   server2.tool(
     "validate_workflow",
-    "Pre-flight ID validation for a 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 this BEFORE publish_workflow when a workflow has been edited, or whenever a published workflow stops behaving as expected. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions without warning. Returns a structured report of valid + missing references.",
-    {
-      workflowId: import_zod47.z.string().describe("The workflow ID to validate.")
-    },
+    "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'.",
+    { workflowId: import_zod47.z.string().describe("The workflow ID to validate.") },
     async ({ workflowId }) => {
       try {
-        let collectIds2 = function(envelope, listKey) {
-          const ids = /* @__PURE__ */ new Set();
-          if (envelope && typeof envelope === "object") {
-            const e = envelope;
-            const arr = Array.isArray(e[listKey]) ? e[listKey] : Array.isArray(envelope) ? envelope : [];
-            for (const item of arr) {
-              if (typeof item === "object" && item !== null) {
-                const o = item;
-                const id = typeof o.id === "string" ? o.id : typeof o._id === "string" ? o._id : null;
-                if (id) ids.add(id);
-              }
-            }
-          }
-          return ids;
-        };
-        var collectIds = collectIds2;
         const workflow = await builderClient.getWorkflow(workflowId);
         if (!workflow) return errorResponse(new Error(`Workflow ${workflowId} not found`));
         const refs = [];
-        const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
-        for (const t of triggers) {
-          extractFromTrigger(t, refs);
-        }
-        const actions = workflow.workflowData?.templates ?? [];
-        for (const a of actions) {
-          extractFromAction(a, refs);
-        }
-        if (refs.length === 0) {
-          const empty = {
-            workflowId,
-            workflowName: workflow.name,
-            status: "ok",
-            references_scanned: 0,
-            issues_count: 0,
-            findings: []
-          };
-          return jsonResponse(empty);
-        }
-        const refCategories = new Set(refs.map((r) => r.kind));
-        const locationId2 = client.defaultLocationId;
-        const fetches = {};
-        if (refCategories.has("pipeline") || refCategories.has("stage")) {
-          fetches.pipelines = client.get("/opportunities/pipelines", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("custom_field")) {
-          fetches.customFields = client.get(`/locations/${locationId2}/customFields`);
-        }
-        if (refCategories.has("user")) {
-          fetches.users = client.get("/users/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("workflow")) {
-          fetches.workflows = builderClient.listWorkflows(200);
-        }
-        if (refCategories.has("form")) {
-          fetches.forms = client.get("/forms/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("calendar")) {
-          fetches.calendars = client.get("/calendars/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("survey")) {
-          fetches.surveys = client.get("/surveys/", { params: { locationId: locationId2 } });
-        }
-        const results = await Promise.allSettled(Object.values(fetches));
-        const keys = Object.keys(fetches);
-        const data = {};
-        for (let i = 0; i < keys.length; i++) {
-          const r = results[i];
-          data[keys[i]] = r.status === "fulfilled" ? r.value : null;
-        }
-        const validPipelineIds = /* @__PURE__ */ new Set();
-        const validStageIds = /* @__PURE__ */ new Set();
-        const stageToPipeline = /* @__PURE__ */ new Map();
-        if (data.pipelines) {
-          try {
-            const parsed = PipelinesResponseSchema.parse(data.pipelines);
-            for (const p of parsed.pipelines) {
-              validPipelineIds.add(p.id);
-              for (const s of p.stages) {
-                validStageIds.add(s.id);
-                stageToPipeline.set(s.id, p.id);
-              }
-            }
-          } catch {
-          }
-        }
-        const validCustomFieldIds = /* @__PURE__ */ new Set();
-        if (data.customFields && typeof data.customFields === "object") {
-          const cf = data.customFields;
-          const arr = Array.isArray(cf.customFields) ? cf.customFields : Array.isArray(cf) ? cf : [];
-          for (const f of arr) {
-            if (typeof f === "object" && f !== null && typeof f.id === "string") {
-              validCustomFieldIds.add(f.id);
-            }
-          }
-        }
-        const validUserIds = /* @__PURE__ */ new Set();
-        if (data.users && typeof data.users === "object") {
-          const u = data.users;
-          const arr = Array.isArray(u.users) ? u.users : Array.isArray(u) ? u : [];
-          for (const user of arr) {
-            if (typeof user === "object" && user !== null && typeof user.id === "string") {
-              validUserIds.add(user.id);
-            }
-          }
-        }
-        const validWorkflowIds = /* @__PURE__ */ new Set();
-        if (data.workflows && typeof data.workflows === "object") {
-          const w = data.workflows;
-          const arr = Array.isArray(w.rows) ? w.rows : Array.isArray(w.workflows) ? w.workflows : Array.isArray(w) ? w : [];
-          for (const wf of arr) {
-            if (typeof wf === "object" && wf !== null) {
-              const o = wf;
-              const id = typeof o._id === "string" ? o._id : typeof o.id === "string" ? o.id : null;
-              if (id) validWorkflowIds.add(id);
-            }
-          }
-        }
-        const validFormIds = collectIds2(data.forms, "forms");
-        const validCalendarIds = collectIds2(data.calendars, "calendars");
-        const validSurveyIds = collectIds2(data.surveys, "surveys");
-        const findings = [];
-        for (const ref of refs) {
-          let valid = false;
-          let extraMsg = "";
-          switch (ref.kind) {
-            case "pipeline":
-              valid = validPipelineIds.has(ref.id);
-              break;
-            case "stage":
-              valid = validStageIds.has(ref.id);
-              break;
-            case "custom_field":
-              valid = validCustomFieldIds.has(ref.id);
-              break;
-            case "user":
-              valid = validUserIds.has(ref.id);
-              break;
-            case "workflow":
-              valid = validWorkflowIds.has(ref.id);
-              if (valid && ref.id === workflowId) {
-                extraMsg = " (self-reference)";
-              }
-              break;
-            case "form":
-              valid = validFormIds.has(ref.id);
-              break;
-            case "calendar":
-              valid = validCalendarIds.has(ref.id);
-              break;
-            case "survey":
-              valid = validSurveyIds.has(ref.id);
-              break;
-          }
-          if (!valid) {
-            findings.push({
-              severity: "error",
-              category: ref.kind,
-              id: ref.id,
-              where: ref.where,
-              message: `${ref.kind} id "${ref.id}" does not exist in this location \u2014 GHL will silently skip this action and all subsequent actions when the workflow runs.`
-            });
-          } else if (extraMsg) {
-            findings.push({
-              severity: "warning",
-              category: ref.kind,
-              id: ref.id,
-              where: ref.where,
-              message: `${ref.kind} id "${ref.id}" is valid${extraMsg}.`
-            });
-          }
-        }
+        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, findings: [] });
+        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 report = {
           workflowId,
           workflowName: workflow.name,
@@ -8668,6 +8857,69 @@ 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.",
+    {},
+    async () => {
+      try {
+        const locationId2 = client.defaultLocationId;
+        const catalog = await fullWorkflowCatalog(builderClient);
+        if (catalog.rows.length === 0)
+          return jsonResponse({ location_id: locationId2, summary: { workflows_total: 0, workflows_scanned: 0, status: "ok", message: "No workflows found in this location." }, workflows_with_issues: [], unscannable: [] });
+        const lookups = await fetchAndBuildLookups(client, builderClient, locationId2, { ids: catalog.ids, complete: catalog.complete });
+        const SCAN_CAP = 300;
+        const toScan = catalog.rows.slice(0, SCAN_CAP);
+        const CONCURRENCY = 6;
+        const results = [];
+        const unscannable = [];
+        let zeroRefCount = 0;
+        for (let i = 0; i < toScan.length; i += CONCURRENCY) {
+          const batch = toScan.slice(i, i + CONCURRENCY);
+          await Promise.all(batch.map(async (row) => {
+            try {
+              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);
+              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) });
+            }
+          }));
+        }
+        const withErrors = results.filter((r) => r.findings.some((f) => f.severity === "error")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, errors: r.findings.filter((f) => f.severity === "error") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
+        const errorsTotal = withErrors.reduce((n, w) => n + w.errors.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({
+          location_id: locationId2,
+          summary: {
+            workflows_total: catalog.rows.length,
+            workflows_scanned: results.length,
+            enumeration_complete: catalog.complete,
+            capped: catalog.rows.length > SCAN_CAP,
+            workflows_with_errors: withErrors.length,
+            errors_total: errorsTotal,
+            workflows_unscannable: unscannable.length,
+            workflows_zero_references: zeroRefCount,
+            unverified: { categories_unloaded: unverifiedCats, references_unverified: unverifiedRefs },
+            status: errorsTotal > 0 ? "issues_found" : "ok"
+          },
+          workflows_with_issues: withErrors,
+          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.`] : [],
+            "workflow_goal, goto, and unrecognized condition types are not deeply checked in this version."
+          ]
+        });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
 }
 
 // src/version-check.ts
@@ -8770,6 +9022,10 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
         if (!registry2) {
           return { name: "Token registry", status: "skip", detail: "Not initialized \u2014 using env-var credentials only. switch_location won't auto-swap keys between sub-accounts." };
         }
+        const loadFailure = registry2.getLoadFailure();
+        if (loadFailure) {
+          return { name: "Token registry", status: "fail", detail: loadFailure };
+        }
         const locs = registry2.listLocations();
         const companies = registry2.listCompanyFirebases();
         const companyNote = companies.length ? ` ${companies.length} company Firebase credential(s) registered for multi-tenant workflow-builder access.` : "";
@@ -8833,7 +9089,7 @@ function resolveSnapshotAuth(client, registry2, companyIdParam) {
   const agencyKey = registry2?.getAgencyKey();
   if (!agencyKey) {
     throw new Error(
-      "Snapshots require an agency/company-scoped API key, and none is registered. This install only has sub-account Private Integration keys. Add the agency key (created at the AGENCY level in GHL Settings > Integrations) to the token registry, then retry."
+      "Snapshots require an agency/company-scoped API key, and none is registered. This install only has sub-account Private Integration keys. Create a Private Integration at the AGENCY level in GHL (Agency Settings > Private Integrations), then run register_agency_key with that key, and retry."
     );
   }
   const storedCompanyId = client.defaultLocationId ? registry2?.getToken(client.defaultLocationId)?.companyId : void 0;
@@ -9258,28 +9514,336 @@ function registerMetaTools(server2, installedVersion) {
   );
 }
 
+// src/cli.ts
+var import_node_util = require("node:util");
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+var import_crypto2 = require("crypto");
+var EXIT_OK = 0;
+var EXIT_USAGE = 2;
+var EXIT_VALIDATION = 3;
+var EXIT_FS = 4;
+var USAGE = `Usage: ghl-mcp cli <subcommand> [options]
+
+Subcommands:
+  register-location          Add a sub-account's Private Integration key
+      --location-id <id>     GHL Location ID (required)
+      --api-key <pit-...>    The sub-account's Private Integration key (required)
+      --name <name>          Friendly name (required)
+      --company-id <id>      Owning company ID (optional; auto-resolved when validating)
+      --no-validate          Skip the live GHL check (air-gapped; local-admin-only)
+
+  register-company-firebase  Add a company's workflow-builder (Firebase) credentials
+      --company-id <id>      GHL company/agency ID (required; self-corrects to the
+                             token's real company when validating)
+      --refresh-token <tok>  Firebase refresh token (required)
+      --user-id <uid>        Firebase user ID (required)
+      --api-key <AIza...>    Firebase API key (optional if the home install has one)
+      --name <name>          Friendly company name (optional)
+      --no-validate          Skip the live token-mint check
+
+  register-agency-key        Store the AGENCY-level API key (snapshots, agency reads)
+      --api-key <pit-...>    Agency-level Private Integration key (required)
+      --no-validate          Skip the live agency-scope check
+
+  list-locations             Print registered locations / companies (never prints keys)
+
+Exit codes: 0 ok, 2 usage, 3 validation failed, 4 filesystem write failed.
+Seed while the MCP server is stopped, or restart it afterwards.`;
+function errLine(msg) {
+  process.stderr.write(msg + "\n");
+}
+function preflightWritable() {
+  try {
+    const dir = ensureAppDataDir();
+    const probe = path5.join(dir, `.write-probe.${process.pid}.${(0, import_crypto2.randomBytes)(4).toString("hex")}`);
+    fs5.writeFileSync(probe, "ok");
+    fs5.unlinkSync(probe);
+    return true;
+  } catch (error) {
+    errLine(`Config dir is not writable: ${error instanceof Error ? error.message : String(error)}`);
+    errLine(`Config dir resolves to the parent of: ${tokenRegistryPath()}`);
+    errLine("If you set GHL_MCP_CONFIG_DIR, make sure it is an absolute path on a writable volume.");
+    return false;
+  }
+}
+function restartReminder() {
+  errLine("Note: if the MCP server is currently running, restart it to pick up this change");
+  errLine("(registry writes are last-writer-wins across processes \u2014 seed stopped, or restart after).");
+}
+function confirmSaved(registry2) {
+  const err = registry2.getLastSaveError();
+  if (err) {
+    errLine(`Failed to write registry: ${err}`);
+    return false;
+  }
+  return true;
+}
+function parse(argv, options, required) {
+  let parsed;
+  try {
+    parsed = (0, import_node_util.parseArgs)({ args: argv, options, strict: true, allowPositionals: false });
+  } catch (error) {
+    return { usageError: error instanceof Error ? error.message : String(error) };
+  }
+  for (const key of required) {
+    const v = parsed.values[key];
+    if (typeof v !== "string" || v.trim() === "") {
+      return { usageError: `Missing required option: --${key}` };
+    }
+  }
+  return parsed;
+}
+async function cmdRegisterLocation(argv, registry2) {
+  const p = parse(
+    argv,
+    {
+      "location-id": { type: "string" },
+      "api-key": { type: "string" },
+      name: { type: "string" },
+      "company-id": { type: "string" },
+      "no-validate": { type: "boolean" }
+    },
+    ["location-id", "api-key", "name"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const locationId2 = p.values["location-id"].trim();
+  const apiKey2 = p.values["api-key"].trim();
+  let name = p.values.name.trim();
+  let companyId = p.values["company-id"]?.trim() || void 0;
+  if (!p.values["no-validate"]) {
+    const client = new GHLClient({ apiKey: apiKey2, locationId: locationId2 });
+    try {
+      const result = await client.get(`/locations/${locationId2}`);
+      const loc = result.location ?? result;
+      if (typeof loc?.name === "string" && loc.name) name = loc.name;
+      if (!companyId && typeof loc?.companyId === "string") companyId = loc.companyId;
+    } catch (error) {
+      errLine(`Validation failed: ${error instanceof Error ? error.message : String(error)}`);
+      errLine("The key must be a Private Integration created INSIDE this sub-account, and the");
+      errLine("Location ID must match. Use --no-validate only if this machine cannot reach GHL.");
+      return EXIT_VALIDATION;
+    }
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.registerLocation(locationId2, name, apiKey2, companyId);
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(
+    `Registered location: ${name} (${locationId2})${companyId ? ` company ${companyId}` : ""} \u2192 ${tokenRegistryPath()}
+`
+  );
+  restartReminder();
+  return EXIT_OK;
+}
+async function cmdRegisterCompanyFirebase(argv, registry2) {
+  const p = parse(
+    argv,
+    {
+      "company-id": { type: "string" },
+      "refresh-token": { type: "string" },
+      "user-id": { type: "string" },
+      "api-key": { type: "string" },
+      name: { type: "string" },
+      "no-validate": { type: "boolean" }
+    },
+    ["company-id", "refresh-token", "user-id"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const typedCompanyId = p.values["company-id"].trim();
+  const refreshToken = p.values["refresh-token"].trim();
+  const userId = p.values["user-id"].trim();
+  const name = p.values.name?.trim();
+  const apiKey2 = p.values["api-key"]?.trim() || process.env.GHL_FIREBASE_API_KEY || registry2.getFirebase()?.apiKey;
+  if (!apiKey2) {
+    errLine("No Firebase API key available. Pass --api-key (starts with 'AIza'), or seed the home");
+    errLine("Firebase first (the key is identical across GHL accounts).");
+    return EXIT_USAGE;
+  }
+  let canonicalCompanyId = typedCompanyId;
+  if (!p.values["no-validate"]) {
+    const fb = await validateFirebase(apiKey2, refreshToken);
+    if (!fb.ok) {
+      errLine(`Firebase credentials rejected: ${fb.error}`);
+      errLine("Capture fresh values from a browser session logged into THIS company's GHL:");
+      errLine("https://elitedcs.com/ghl-mcp-firebase");
+      return EXIT_VALIDATION;
+    }
+    if (fb.companyId && fb.companyId !== typedCompanyId) {
+      canonicalCompanyId = fb.companyId;
+      errLine(
+        `Note: stored under company ${fb.companyId} (the ID this token actually authenticates as), not ${typedCompanyId}.`
+      );
+    }
+  } else {
+    errLine("Warning: --no-validate stores the typed company ID verbatim. If workflow-builder calls");
+    errLine("401 after seeding, re-run WITHOUT --no-validate so the ID self-corrects from the token.");
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.setCompanyFirebase(canonicalCompanyId, {
+      apiKey: apiKey2,
+      refreshToken,
+      userId,
+      ...name ? { name } : {}
+    });
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(
+    `Registered company Firebase: ${name ?? canonicalCompanyId} (${canonicalCompanyId}) \u2192 ${tokenRegistryPath()}
+`
+  );
+  restartReminder();
+  return EXIT_OK;
+}
+async function cmdRegisterAgencyKey(argv, registry2) {
+  const p = parse(
+    argv,
+    { "api-key": { type: "string" }, "no-validate": { type: "boolean" } },
+    ["api-key"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const apiKey2 = p.values["api-key"].trim();
+  if (!p.values["no-validate"]) {
+    const client = new GHLClient({ apiKey: apiKey2 });
+    try {
+      const probe = await client.get("/locations/search", { params: { limit: 1, skip: 0 } });
+      const locations = probe?.locations;
+      if (!Array.isArray(locations)) {
+        throw new Error("response is not an agency location-search envelope (no locations array)");
+      }
+    } catch (error) {
+      errLine(`Validation failed: ${error instanceof Error ? error.message : String(error)}`);
+      errLine("The key must be a Private Integration created at the AGENCY level (Agency Settings >");
+      errLine("Private Integrations), with the locations scope enabled.");
+      return EXIT_VALIDATION;
+    }
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.setAgencyKey(apiKey2);
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(`Registered agency key: ${apiKey2.substring(0, 12)}... \u2192 ${tokenRegistryPath()}
+`);
+  restartReminder();
+  return EXIT_OK;
+}
+function cmdListLocations(registry2) {
+  const locs = registry2.listLocations();
+  const companies = registry2.listCompanyFirebases();
+  const out = {
+    registryPath: tokenRegistryPath(),
+    locations: locs,
+    agencyKey: registry2.getAgencyKey() ? "registered" : "not registered",
+    homeFirebase: registry2.getFirebase() ? "registered" : "not registered",
+    // names/ids ONLY — no keys, tokens, or user ids (design contract).
+    companyFirebases: companies.map(({ companyId, name }) => ({ companyId, ...name ? { name } : {} }))
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  return EXIT_OK;
+}
+async function runCli(subcommand, argv) {
+  let registry2;
+  try {
+    registry2 = new TokenRegistry();
+  } catch (error) {
+    errLine(error instanceof Error ? error.message : String(error));
+    return EXIT_USAGE;
+  }
+  const loadFailure = registry2.getLoadFailure();
+  if (loadFailure) {
+    errLine(loadFailure);
+    return EXIT_FS;
+  }
+  switch (subcommand) {
+    case "register-location":
+      return cmdRegisterLocation(argv, registry2);
+    case "register-company-firebase":
+      return cmdRegisterCompanyFirebase(argv, registry2);
+    case "register-agency-key":
+      return cmdRegisterAgencyKey(argv, registry2);
+    case "list-locations":
+      return cmdListLocations(registry2);
+    case void 0:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(USAGE + "\n");
+      return subcommand === void 0 ? EXIT_USAGE : EXIT_OK;
+    default:
+      errLine(`Unknown subcommand: ${subcommand}`);
+      errLine(USAGE);
+      return EXIT_USAGE;
+  }
+}
+
 // src/index.ts
-var pkg = require_package();
+var bundledPkg = require_package();
+var pkg = (() => {
+  try {
+    const onDisk = JSON.parse(
+      fs6.readFileSync(path6.resolve(__dirname, "..", "package.json"), "utf8")
+    );
+    if (typeof onDisk.version === "string" && onDisk.version.length > 0) {
+      return { version: onDisk.version };
+    }
+  } catch {
+  }
+  return bundledPkg;
+})();
 dotenv2.config();
+{
+  const configDirOverride = process.env.GHL_MCP_CONFIG_DIR?.trim();
+  if (configDirOverride && !path6.isAbsolute(configDirOverride)) {
+    process.stderr.write(
+      `[ghl-mcp] GHL_MCP_CONFIG_DIR must be an absolute path (got "${configDirOverride}"). Use e.g. /data/ghl-mcp in a container, with a volume mounted at /data.
+`
+    );
+    process.exit(2);
+  }
+}
 process.on("unhandledRejection", (reason) => {
   process.stderr.write(`[ghl-mcp] Unhandled rejection: ${reason}
 `);
 });
 function hardenSecretFilePerms() {
-  const repoDir = path5.resolve(__dirname, "..");
+  const repoDir = path6.resolve(__dirname, "..");
   const candidates = [
-    { file: path5.join(repoDir, "start-mcp.sh"), mode: 448 },
+    { file: path6.join(repoDir, "start-mcp.sh"), mode: 448 },
     // Legacy registry location (pre-migration); new location lives in app-data.
-    { file: path5.join(repoDir, ".ghl-tokens.json"), mode: 384 },
+    { file: path6.join(repoDir, ".ghl-tokens.json"), mode: 384 },
     { file: tokenRegistryPath(), mode: 384 }
   ];
   for (const { file, mode } of candidates) {
     let current;
     try {
-      if (!fs5.existsSync(file)) continue;
-      current = fs5.statSync(file).mode & 511;
+      if (!fs6.existsSync(file)) continue;
+      current = fs6.statSync(file).mode & 511;
       if (current !== mode) {
-        fs5.chmodSync(file, mode);
+        fs6.chmodSync(file, mode);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -9493,9 +10057,28 @@ async function checkForUpdates() {
   }
 }
 async function main() {
+  if (process.argv[2] === "cli") {
+    process.exit(await runCli(process.argv[3], process.argv.slice(4)));
+  }
   await resolveAccessAndRegister();
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    process.stderr.write(`[ghl-mcp] ${signal} received \u2014 shutting down.
+`);
+    const deadline = setTimeout(() => process.exit(0), 3e3);
+    deadline.unref();
+    try {
+      await server.close();
+    } catch {
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
   if (inBootstrapMode) {
     process.stderr.write(`[ghl-mcp] v${pkg.version} connected (bootstrap mode \u2014 only setup_ghl_mcp available).
 `);
@@ -9504,7 +10087,9 @@ async function main() {
     process.stderr.write(`[ghl-mcp] v${pkg.version} connected. Token registry: ${locCount} location(s).
 `);
     validateApiKey();
-    checkForUpdates();
+    if (process.env.GHL_MCP_DISABLE_UPDATE_CHECK !== "1") {
+      checkForUpdates();
+    }
   }
 }
 main().catch((error) => {