zuckerbot-mcp 0.4.1 → 0.4.3

package/dist/tools.js

@@ -130,14 +130,14 @@ function buildQuickstartPayload(client) {
             {
                 step: 4,
                 tool: "zuckerbot_create_campaign",
-                description: "Full campaign strategy with audience tiers",
+                description: "Create a reviewed launch-ready campaign draft",
                 requires_key: true,
                 flow: "quick_launch",
             },
             {
                 step: 5,
                 tool: "zuckerbot_launch_campaign",
-                description: "Go live on Meta",
+                description: "Launch the reviewed legacy draft on Meta",
                 requires_key: true,
                 flow: "quick_launch",
             },
@@ -367,7 +367,7 @@ function registerCreativeGenerationTools(server, client) {
             if (creative_handoff)
                 body.creative_handoff = creative_handoff;
             const result = await client.post(`/campaigns/${campaign_id}/request-creative`, body);
-            return formatResult(appendHint(result, "Creative request dispatched. Monitor progress with zuckerbot_get_creative_status. Once all_complete is true, call zuckerbot_activate_campaign to go live."));
+            return formatResult(appendHint(result, "Creative request dispatched for planning/review. Monitor progress with zuckerbot_get_creative_status. Multi-tier activation is temporarily disabled; use a legacy campaign draft for a live launch."));
         }
         catch (err) {
             return formatError(err);
@@ -433,26 +433,53 @@ export function registerTools(server, client) {
     registerQuickstartTool(server, client);
     registerBillingStatusTool(server, client);
     // ── 0a. Account Audit ───────────────────────────────────────────
-    server.tool("zuckerbot_audit_account", "Run a full audit of the connected Meta ad account: wasted spend detection, creative fatigue, opportunity score (0-100), projected CPL improvement, and prioritised action items. Read-only and available on every tier — the recommended FIRST call for any new account or when a user asks 'how are my ads doing?'.", {
+    server.tool("zuckerbot_audit_account", "Run a full audit of the connected Meta ad account: wasted spend detection, creative fatigue, a complete-account opportunity score (0-100 when all inputs return), and prioritised action items. Saves a shareable web report when the API key resolves to one saved business. Read-only and available on every tier — the recommended FIRST call for any new account or when a user asks 'how are my ads doing?'.", {
         meta_ad_account_id: z.string().optional().describe("Meta ad account ID to audit (format: act_XXXXX). Defaults to the connected account."),
         company_name: z.string().optional().describe("Company name used in the audit narrative. Defaults to the connected business name."),
     }, async ({ meta_ad_account_id, company_name }) => {
         try {
             client.requireAuth();
-            const body = {};
+            // Ask the API to persist when one business is resolvable, but keep the
+            // audit itself available when setup/selection is still incomplete.
+            // This stays one metered request and one Meta audit in both cases.
+            const body = {
+                save_report: true,
+                save_report_if_available: true,
+            };
             if (meta_ad_account_id)
                 body.meta_ad_account_id = meta_ad_account_id;
             if (company_name)
                 body.company_name = company_name;
             const result = await client.post("/audit", body);
-            return formatResult(appendHint(result, "Audit complete. Present opportunityScore, wastedSpendEstCents, and audit.rawInsights.action_items to the user, then act on the findings: zuckerbot_get_performance to drill into a specific campaign, zuckerbot_pause_campaign to stop wasted spend, or zuckerbot_creative_analysis to diagnose fatigued creatives."));
+            const record = asRecord(result);
+            const audit = asRecord(record?.audit);
+            const raw = asRecord(audit?.rawInsights);
+            const dataCompleteness = asRecord(raw?.data_completeness);
+            // Raw Meta insight rows drown the agent's context; the summarised
+            // findings above them carry everything the report presents.
+            if (raw && "campaign_rows" in raw)
+                delete raw.campaign_rows;
+            const reportUrl = typeof record?.report_url === "string" ? `https://zuckerbot.ai${record.report_url}` : null;
+            const partialDataHint = raw?.data_truncated === true
+                ? " NOTE: Meta returned incomplete data. Check audit.rawInsights.data_completeness and do not present opportunityScore or exact spend/fatigue ratios as complete-account measures."
+                : "";
+            const scoreHint = typeof audit?.opportunityScore !== "number"
+                ? " NOTE: No opportunity score is available for this result. Do not present or infer a numeric account rating."
+                : "";
+            const currencyHint = dataCompleteness?.account_currency_available === false
+                ? " NOTE: Meta did not return the account currency. Describe money as account-currency units; do not label it AUD or invent another currency code."
+                : "";
+            const reportHint = reportUrl
+                ? ` A shareable web report was saved — give the user this link: ${reportUrl}`
+                : " No shareable report was saved because this API key does not resolve to one saved business.";
+            return formatResult(appendHint(result, `Audit complete.${reportHint}${partialDataHint}${scoreHint}${currencyHint} Present complete observed findings and audit.rawInsights.action_items to the user, then act on them: zuckerbot_get_performance to drill into a specific campaign, zuckerbot_pause_campaign to stop wasted spend, or zuckerbot_creative_analysis to diagnose fatigued creatives.`));
         }
         catch (err) {
             return formatError(err);
         }
     });
     // ── 0b. Redeem Lifetime Licence ─────────────────────────────────
-    server.tool("zuckerbot_redeem_license", "Redeem a ZuckerBot lifetime licence code (format ZB-XXXXX-XXXXX-XXXXX) purchased on Dealify or AppSumo. Codes stack on one account: 1 code = Lifetime Tier 1 (1 ad account, 2,500 calls/mo), 2 codes = Tier 2 (3 accounts, 10K calls/mo), 3 codes = Tier 3 (10 accounts, 30K calls/mo). Redeeming upgrades ALL of the account's API keys to the new tier immediately.", {
+    server.tool("zuckerbot_redeem_license", "Redeem a ZuckerBot lifetime licence code (format ZB-XXXXX-XXXXX-XXXXX) purchased on Dealify or AppSumo. Each code activates the plan it was purchased for: Tier 1 (1 ad account, 2,500 calls/mo), Tier 2 (3 accounts, 10K calls/mo) or Tier 3 (10 accounts, 30K calls/mo). Codes also stack additively on one account up to Tier 3 — e.g. two Tier 1 codes = Tier 2. Redeeming upgrades ALL of the account's API keys to the new tier immediately.", {
         code: z.string().describe("Lifetime licence code in the format ZB-XXXXX-XXXXX-XXXXX"),
     }, async ({ code }) => {
         try {
@@ -462,7 +489,7 @@ export function registerTools(server, client) {
             const mintedKey = asRecord(record?.api_key);
             const hint = mintedKey
                 ? "IMPORTANT: a new API key was minted during redemption. Show the full api_key.key value to the user IMMEDIATELY and tell them to store it securely — it will NEVER be shown again. Then follow the next_steps in the response."
-                : "Licence redeemed — all of this account's API keys are upgraded to the new tier. Compare codes_redeemed with max_stack: stacking another code unlocks the next tier. Run zuckerbot_audit_account to put the new limits to work.";
+                : "Licence redeemed — all of this account's API keys are upgraded to the new tier. If the tier is below Lifetime Tier 3, stacking another code raises it. Run zuckerbot_audit_account to put the new limits to work.";
             return formatResult(appendHint(result, hint));
         }
         catch (err) {
@@ -608,15 +635,15 @@ export function registerTools(server, client) {
         }
     });
     // ── 7. Create Full Campaign ─────────────────────────────────────
-    server.tool("zuckerbot_create_full_campaign", "Build a complete Meta campaign from an approved Campaign Architect session. IMPORTANT: dry_run defaults to TRUE. When dry_run=true, returns the exact campaign structure that WOULD be created without calling Meta — safe, free, no side effects. Present this to the customer first. Only set dry_run=false after explicit customer approval. When dry_run=false, creates live Meta objects (campaign + ad sets + ads) in PAUSED state. Generated videos get linked for rejection tracking automatically.", {
+    server.tool("zuckerbot_create_full_campaign", "Build a complete PAUSED Meta campaign from an approved Campaign Architect session. IMPORTANT: dry_run defaults to TRUE. When dry_run=true, returns the exact campaign structure that WOULD be created without calling Meta — safe, free, no side effects. Present this to the customer first. Only set dry_run=false after explicit customer approval. When dry_run=false, creates Meta objects in PAUSED state for review; Architect auto-activation is temporarily disabled. Generated videos get linked for rejection tracking automatically.", {
         session_id: z.string().describe("Campaign Architect session ID with approved strategy and creatives"),
         dry_run: z.boolean().default(true)
             .describe("DEFAULT TRUE. Set to false ONLY after customer has approved the dry-run preview. Live mode creates real Meta objects."),
         meta_access_token: z.string().optional().describe("Meta access token override (live mode only)"),
         meta_ad_account_id: z.string().optional().describe("Meta ad account ID override (live mode only)"),
         meta_page_id: z.string().optional().describe("Facebook Page ID override (live mode only)"),
-        activate: z.boolean().default(false)
-            .describe("If true AND dry_run=false, activate immediately after creation. Default false — stays PAUSED for customer approval."),
+        activate: z.literal(false).default(false)
+            .describe("Must remain false. Architect auto-activation is temporarily disabled; live mode creates PAUSED Meta objects only."),
     }, async ({ session_id, dry_run, meta_access_token, meta_ad_account_id, meta_page_id, activate }) => {
         try {
             client.requireAuth();
@@ -632,9 +659,7 @@ export function registerTools(server, client) {
             const isDryRun = record.dry_run === true;
             const hint = isDryRun
                 ? "DRY RUN — no Meta objects were created. Present the would_create structure to the customer. If they approve, call again with dry_run=false to create live Meta objects."
-                : activate
-                    ? "Campaign built and activated on Meta. Monitor performance with zuckerbot_get_performance. Generated videos are linked for rejection tracking."
-                    : "Campaign built in PAUSED state on Meta. Present the meta_structure to the customer, then resume the campaign on Meta only after approval. Videos linked for rejection tracking.";
+                : "Campaign built in PAUSED state on Meta for review. Architect auto-activation and campaign resume are temporarily disabled; use a reviewed legacy draft with zuckerbot_launch_campaign for the supported live path. Videos linked for rejection tracking.";
             return formatResult(appendHint(result, hint));
         }
         catch (err) {
@@ -657,14 +682,14 @@ export function registerTools(server, client) {
                 url,
                 ad_count,
             });
-            return formatResult(appendHint(result, "Preview generated. Call zuckerbot_create_campaign with the same URL to build a full intelligence strategy with audience tiers and budget guidance."));
+            return formatResult(appendHint(result, "Preview generated. Call zuckerbot_create_campaign with the same URL; it defaults to the reviewed legacy draft path that can be launched safely."));
         }
         catch (err) {
             return formatError(err);
         }
     });
     // ── 7. Create Campaign ──────────────────────────────────────────
-    server.tool("zuckerbot_create_campaign", "Create a new campaign draft for a business. In intelligence mode (preferred when a business_id is available) this returns context-aware audience tiers, creative angles, budget guidance, projected CPL, and phased next steps. Does NOT spend money or create anything on Meta — it's purely a planning step. Use zuckerbot_launch_campaign to go live after strategy approval.", {
+    server.tool("zuckerbot_create_campaign", "Create a new campaign draft for a business. Defaults to legacy mode, the only launch-ready path during Dealify hardening. Intelligence mode remains available for planning only and cannot be activated. This tool does not spend money or create anything on Meta; review the draft, then use zuckerbot_launch_campaign.", {
         url: z.string().describe("Business website URL"),
         business_id: z.string().optional().describe("Existing ZuckerBot business ID to anchor intelligence mode"),
         architect_session_id: z.string().optional()
@@ -682,8 +707,8 @@ export function registerTools(server, client) {
             .describe("Daily budget in cents (e.g., 2000 = $20/day)"),
         mode: z
             .enum(["auto", "legacy", "intelligence"])
-            .optional()
-            .describe("Campaign planning mode. auto prefers intelligence when a business can be resolved"),
+            .default("legacy")
+            .describe("Campaign planning mode. Default legacy is the only launch-ready path. auto/intelligence are planning-only while multi-tier activation is disabled."),
         objective: z
             .enum(["leads", "traffic", "conversions", "awareness"])
             .optional()
@@ -713,8 +738,7 @@ export function registerTools(server, client) {
                 body.location = location;
             if (budget_daily_cents !== undefined)
                 body.budget_daily_cents = budget_daily_cents;
-            if (mode)
-                body.mode = mode;
+            body.mode = mode ?? "legacy";
             if (objective)
                 body.objective = objective;
             if (lead_destination)
@@ -726,7 +750,9 @@ export function registerTools(server, client) {
             if (creative_handoff)
                 body.creative_handoff = creative_handoff;
             const result = await client.post("/campaigns/create", body);
-            return formatResult(appendHint(result, "Campaign draft created. For intelligence campaigns: call zuckerbot_approve_campaign_strategy to confirm audience tiers and angles, then zuckerbot_request_creative or zuckerbot_upload_creative to attach creatives before launch."));
+            return formatResult(appendHint(result, mode === "legacy"
+                ? "Launch-ready legacy draft created. Review it, confirm Meta credentials and budget, then call zuckerbot_launch_campaign."
+                : "Planning-only intelligence draft created. Multi-tier activation is temporarily disabled; create a legacy-mode draft when the user is ready to launch."));
         }
         catch (err) {
             return formatError(err);
@@ -789,7 +815,7 @@ export function registerTools(server, client) {
     }, async ({ campaign_id }) => {
         try {
             const result = await client.get(`/campaigns/${campaign_id}`);
-            return formatResult(appendHint(result, "Inspect creative_status and workflow state. Next steps depend on campaign_version: intelligence campaigns → approve strategy → upload creatives → activate. Legacy campaigns → launch directly."));
+            return formatResult(appendHint(result, "Inspect creative_status and workflow state. Legacy campaigns can launch directly after review. Intelligence campaigns are planning-only while multi-tier activation is disabled."));
         }
         catch (err) {
             return formatError(err);
@@ -833,7 +859,7 @@ export function registerTools(server, client) {
             const creativeStatus = typeof payload?.creative_status === "string" ? payload.creative_status : null;
             const queuedJobs = Array.isArray(payload?.queued_jobs) ? payload.queued_jobs : [];
             if (creativeStatus !== "uploading" || queuedJobs.length === 0) {
-                return formatResult(appendHint(result, "Creatives uploaded. Call zuckerbot_get_creative_status to check processing status, then zuckerbot_activate_campaign once all_complete is true."));
+                return formatResult(appendHint(result, "Creatives uploaded. Call zuckerbot_get_creative_status to check processing status. Intelligence activation is temporarily disabled; use a reviewed legacy draft for live launch."));
             }
             try {
                 const polled = await pollCreativeStatus(client, campaign_id);
@@ -847,7 +873,7 @@ export function registerTools(server, client) {
                             interval_seconds: CREATIVE_STATUS_POLL_INTERVAL_MS / 1000,
                         },
                         final_status: polled.lastStatus,
-                    }, "All creatives uploaded and processed. Call zuckerbot_activate_campaign to turn on the paused Meta ad sets and go live."));
+                    }, "All creatives uploaded and processed for review. Intelligence activation is temporarily disabled; use a reviewed legacy draft for live launch."));
                 }
                 return formatResult(appendHint({
                     initial_response: payload,
@@ -860,7 +886,7 @@ export function registerTools(server, client) {
                         suggested_tool: "zuckerbot_get_creative_status",
                     },
                     last_status: polled.lastStatus,
-                }, "Uploads still processing. Call zuckerbot_get_creative_status in 15–30 seconds to check progress. Once all_complete is true, call zuckerbot_activate_campaign."));
+                }, "Uploads still processing. Call zuckerbot_get_creative_status in 15–30 seconds to check progress. Completed intelligence creatives remain review-only while activation is disabled."));
             }
             catch (pollError) {
                 return formatResult(appendHint({
@@ -876,40 +902,36 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool("zuckerbot_get_creative_status", "Check the asynchronous upload queue for an intelligence campaign to see if Meta ad-creation jobs are complete. Poll this after zuckerbot_upload_creative when the initial response shows creative_status='uploading'. Returns all_complete=true when every queued job has finished and the campaign is ready to activate.", {
+    server.tool("zuckerbot_get_creative_status", "Check the asynchronous upload queue for an intelligence campaign to see if Meta ad-creation jobs are complete. Poll this after zuckerbot_upload_creative when the initial response shows creative_status='uploading'. Returns all_complete=true when every queued job has finished for review; intelligence activation is temporarily disabled.", {
         campaign_id: z.string().describe("Intelligence campaign ID"),
     }, async ({ campaign_id }) => {
         try {
             const result = await client.get(`/campaigns/${campaign_id}/creative-status`);
-            return formatResult(appendHint(result, "If all_complete is true, call zuckerbot_activate_campaign to turn on the paused Meta ad sets. If still uploading, poll again in 15–30 seconds."));
+            return formatResult(appendHint(result, "If still uploading, poll again in 15–30 seconds. Completed intelligence creatives remain available for review, but multi-tier activation is temporarily disabled; use a legacy draft for live launch."));
         }
         catch (err) {
             return formatError(err);
         }
     });
-    server.tool("zuckerbot_activate_campaign", "Activate the ready audience tiers for an intelligence campaign after strategy approval and creative upload. Turns on paused Meta ad sets for each approved tier. Only tiers with valid paused executions and uploaded creatives are activated. Use this as the final step before a campaign goes live on Meta.", {
+    server.tool("zuckerbot_activate_campaign", "Temporarily unavailable during Dealify launch hardening. Intelligence campaigns are planning-only; create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.", {
         campaign_id: z.string().describe("Intelligence campaign ID"),
         tier_names: z.array(z.string()).optional().describe("Optional subset of approved tiers to activate"),
         meta_access_token: z.string().optional().describe("Optional Meta/Facebook access token override"),
         meta_ad_account_id: z.string().optional().describe("Optional Meta ad account ID override (format: act_XXXXX)"),
         meta_page_id: z.string().optional().describe("Optional Facebook Page ID override"),
     }, async ({ campaign_id, tier_names, meta_access_token, meta_ad_account_id, meta_page_id }) => {
-        try {
-            const body = {};
-            if (tier_names?.length)
-                body.tier_names = tier_names;
-            if (meta_access_token)
-                body.meta_access_token = meta_access_token;
-            if (meta_ad_account_id)
-                body.meta_ad_account_id = meta_ad_account_id;
-            if (meta_page_id)
-                body.meta_page_id = meta_page_id;
-            const result = await client.post(`/campaigns/${campaign_id}/activate`, body);
-            return formatResult(appendHint(result, "Campaign activated on Meta. Monitor with zuckerbot_get_performance. If budget needs adjusting, use zuckerbot_pause_campaign to stop spend, or zuckerbot_rebalance_portfolio if this campaign belongs to a portfolio."));
-        }
-        catch (err) {
-            return formatError(err);
-        }
+        void tier_names;
+        void meta_access_token;
+        void meta_ad_account_id;
+        void meta_page_id;
+        return formatResult({
+            error: true,
+            code: "intelligence_activation_temporarily_disabled",
+            message: "Multi-tier activation is temporarily disabled. Create a campaign with mode='legacy', review it, then call zuckerbot_launch_campaign.",
+            campaign_id,
+            supported_create_mode: "legacy",
+            supported_launch_tool: "zuckerbot_launch_campaign",
+        });
     });
     server.tool("zuckerbot_suggest_angles", "Return only the creative angles and audience tiers for a campaign draft — a lightweight alternative to zuckerbot_get_campaign when you need just the strategy summary without the full campaign payload, stored creatives, or tier execution details.", {
         campaign_id: z.string().describe("Campaign ID"),
@@ -976,19 +998,19 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    // ── 4. Pause / Resume Campaign ─────────────────────────────────
-    server.tool("zuckerbot_pause_campaign", "Pause or resume a running Meta ad campaign. Pausing stops ad delivery and spend immediately — the campaign stays in Meta but goes dark. Resuming restarts delivery without relaunching. Use pause when creative needs refreshing, budget is exhausted, or the user asks to stop spending.", {
+    // ── 4. Pause Campaign ──────────────────────────────────────────
+    server.tool("zuckerbot_pause_campaign", "Pause a running Meta ad campaign. Pausing stops ad delivery and spend immediately while leaving the campaign in Meta. Use this when creative needs refreshing, budget is exhausted, entitlement is withdrawn, or the user asks to stop spending. Resume is temporarily disabled during Dealify launch hardening.", {
         campaign_id: z.string().describe("ZuckerBot campaign ID"),
         action: z
-            .enum(["pause", "resume"])
+            .literal("pause")
             .default("pause")
-            .describe("Whether to pause or resume the campaign"),
+            .describe("Pause the campaign"),
     }, async ({ campaign_id, action }) => {
         try {
             const result = await client.post(`/campaigns/${campaign_id}/pause`, {
                 action,
             });
-            return formatResult(appendHint(result, "Campaign paused/resumed. Call zuckerbot_get_performance to see the current delivery status, or zuckerbot_get_campaign to check the full workflow state."));
+            return formatResult(appendHint(result, "Campaign paused. Call zuckerbot_get_performance to confirm delivery has stopped, or zuckerbot_get_campaign to inspect the full workflow state."));
         }
         catch (err) {
             return formatError(err);
@@ -1253,7 +1275,7 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool("zuckerbot_get_campaign_insights", "Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta's Ads Manager \"Results\" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl. meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries.", {
+    server.tool("zuckerbot_get_campaign_insights", "Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta's Ads Manager \"Results\" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl (the response's metric_semantics object labels every lead field). meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries. Adset/ad rows report their OWN status — status_scope says which entity a row's status belongs to, statuses are as of status_synced_at, and refresh=true re-syncs them; spend-by-date is authoritative for whether delivery actually happened.", {
         business_id: z.string().optional().describe("Optional business ID override linked to the connected Meta ad account"),
         date_from: z.string().optional().describe("Optional start date in YYYY-MM-DD format. Defaults to 7 days ago."),
         date_to: z.string().optional().describe("Optional end date in YYYY-MM-DD format. Defaults to today."),
@@ -1319,7 +1341,10 @@ export function registerTools(server, client) {
         })
             .optional()
             .describe("Optional user data to improve match rate"),
-    }, async ({ campaign_id, lead_id, quality, meta_access_token, user_data }) => {
+        fbclid: z.string().optional().describe("Optional Facebook click ID; the server builds a well-formed fbc cookie from it"),
+        fbc: z.string().optional().describe("Optional pre-formatted fbc cookie, forwarded raw — never hashed"),
+        fbp: z.string().optional().describe("Optional _fbp browser cookie, forwarded raw — never hashed. Improves match quality"),
+    }, async ({ campaign_id, lead_id, quality, meta_access_token, user_data, fbclid, fbc, fbp }) => {
         try {
             const body = {
                 lead_id,
@@ -1328,6 +1353,12 @@ export function registerTools(server, client) {
             };
             if (user_data)
                 body.user_data = user_data;
+            if (fbclid)
+                body.fbclid = fbclid;
+            if (fbc)
+                body.fbc = fbc;
+            if (fbp)
+                body.fbp = fbp;
             const result = await client.post(`/campaigns/${campaign_id}/conversions`, body);
             return formatResult(appendHint(result, "Conversion signal sent. Use zuckerbot_capi_status to view aggregate CAPI delivery and attribution, or zuckerbot_get_performance to see updated CPL and lead metrics."));
         }
@@ -1472,7 +1503,7 @@ export function registerTools(server, client) {
         }
     });
     // ── 18. CAPI Config — Read ─────────────────────────────────────
-    server.tool("zuckerbot_get_capi_config", "Fetch the current Conversions API configuration for a business: whether CAPI delivery is enabled, CRM source, currency, stage-to-event mappings, action source, and webhook URL. Use this before configuring CAPI to see what is already set, or to audit the current event mapping.", {
+    server.tool("zuckerbot_get_capi_config", "Fetch the current Conversions API configuration for a business: whether CAPI delivery is enabled, CRM source, currency, stage-to-event mappings, action source, and webhook URL. Use this before configuring CAPI to see what is already set, or to audit the current event mapping. The webhook secret is write-only: reads return webhook_secret_set and webhook_secret_last4, never the full value — use zuckerbot_rotate_webhook_secret to mint a new one.", {
         business_id: z.string().optional().describe("Optional business ID override for the authenticated API key"),
     }, async ({ business_id }) => {
         try {
@@ -1496,14 +1527,14 @@ export function registerTools(server, client) {
             .enum(["website", "app", "email", "phone_call", "chat", "physical_store", "system_generated", "business_messaging", "other"])
             .optional()
             .describe("Meta Conversions API action_source. Defaults to website for CRM events"),
-        rotate_webhook_secret: z.boolean().optional().describe("Rotate the webhook secret on update"),
+        rotate_webhook_secret: z.boolean().optional().describe("Rotate the webhook secret on update. The new secret is returned exactly once in the response; prefer zuckerbot_rotate_webhook_secret for a dedicated rotation"),
         event_mapping: z
             .record(z.string(), z.object({
-            meta_event: z.string().describe("Meta standard event name"),
+            meta_event: z.string().describe("Meta event name: standard names (Lead, Purchase, StartTrial, …) are canonicalised case-insensitively; custom names (e.g. plg_signup_completed) are stored verbatim — start with a letter, letters/digits/underscore/hyphen/period/space only, max 50 chars"),
             value: z.number().optional().describe("Event value in major currency units"),
         }))
             .optional()
-            .describe("CRM stage mapping object keyed by source stage"),
+            .describe("CRM stage mapping object keyed by source stage. Stage keys are normalised (lower-cased, non-alphanumerics stripped: signup_completed → signupcompleted); inbound webhook source_stage values are normalised identically before matching, and any renamed keys are reported back as normalised_keys in the response"),
     }, async ({ business_id, is_enabled, currency, crm_source, optimise_for, action_source, rotate_webhook_secret, event_mapping }) => {
         try {
             const resolvedBusinessId = await client.resolveBusinessId(business_id);
@@ -1529,6 +1560,19 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
+    // ── 19b. CAPI Webhook Secret — Rotate ──────────────────────────
+    server.tool("zuckerbot_rotate_webhook_secret", "Rotate the Conversions API webhook secret for a business. The new secret is returned exactly once, in this response only — every other read shows just webhook_secret_set and webhook_secret_last4. The old secret stops authenticating immediately, so update the system that signs your inbound webhooks (for example your CRM workflow's stored secret) in the same sitting.", {
+        business_id: z.string().optional().describe("Optional business ID override for the authenticated API key"),
+    }, async ({ business_id }) => {
+        try {
+            const resolvedBusinessId = await client.resolveBusinessId(business_id);
+            const result = await client.put("/capi/config", { business_id: resolvedBusinessId, rotate_webhook_secret: true });
+            return formatResult(appendHint(result, "Copy webhook_secret from this response now — it is not shown again. The old secret is already invalid, so update your webhook sender's stored secret immediately, then call zuckerbot_capi_test to verify delivery."));
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
     // ── 20. CAPI Status ────────────────────────────────────────────
     server.tool("zuckerbot_capi_status", "Get 7-day and 30-day CAPI delivery statistics for the business: total events sent, events by type (Lead/Contact/Purchase), match quality breakdown, and attribution counts. Use this to confirm CAPI is functioning and that events are being matched by Meta.", {
         business_id: z.string().optional().describe("Optional business ID override"),
@@ -1558,7 +1602,10 @@ export function registerTools(server, client) {
         })
             .optional()
             .describe("Optional user data to hash into the test payload"),
-    }, async ({ business_id, source_stage, crm_source, value, user_data }) => {
+        fbclid: z.string().optional().describe("Optional Facebook click ID to verify fbc construction/passthrough"),
+        fbc: z.string().optional().describe("Optional pre-formatted fbc cookie to verify raw passthrough"),
+        fbp: z.string().optional().describe("Optional _fbp cookie to verify raw passthrough"),
+    }, async ({ business_id, source_stage, crm_source, value, user_data, fbclid, fbc, fbp }) => {
         try {
             const resolvedBusinessId = await client.resolveBusinessId(business_id);
             const body = {
@@ -1572,6 +1619,12 @@ export function registerTools(server, client) {
                 body.value = value;
             if (user_data)
                 body.user_data = user_data;
+            if (fbclid)
+                body.fbclid = fbclid;
+            if (fbc)
+                body.fbc = fbc;
+            if (fbp)
+                body.fbp = fbp;
             const result = await client.post("/capi/config/test", body);
             return formatResult(appendHint(result, "Test event sent. Check status in the response — if 'sent', CAPI is working. If 'skipped' or 'failed', review the config with zuckerbot_get_capi_config and fix the event mapping."));
         }
@@ -1580,7 +1633,7 @@ export function registerTools(server, client) {
         }
     });
     // ── 22. Create Portfolio ───────────────────────────────────────
-    server.tool("zuckerbot_create_portfolio", "Create a multi-tier audience portfolio for a business from a shared template (e.g., 'Local Services', 'eCommerce') or a custom tier array. Portfolios split the total budget across prospecting, retargeting, and reactivation tiers with per-tier CPA targets. After creating, call zuckerbot_launch_portfolio to launch all tiers on Meta.", {
+    server.tool("zuckerbot_create_portfolio", "Create a planning and monitoring-only multi-tier audience portfolio for a business from a shared template (e.g., 'Local Services', 'eCommerce') or a custom tier array. Portfolios split a proposed total budget across prospecting, retargeting, and reactivation tiers with per-tier CPA targets. Portfolio launch is temporarily disabled during Dealify hardening.", {
         business_id: z.string().optional().describe("Optional business ID override"),
         template_id: z.string().optional().describe("Optional portfolio template ID"),
         template_name: z.string().optional().describe("Optional portfolio template name, such as 'Local Services'"),
@@ -1615,19 +1668,19 @@ export function registerTools(server, client) {
             if (tiers)
                 body.tiers = tiers;
             const result = await client.post("/portfolios/create", body);
-            return formatResult(appendHint(result, "Portfolio created. Call zuckerbot_launch_portfolio with the returned portfolio_id to launch all tiers on Meta, or zuckerbot_get_portfolio to review the tier configuration."));
+            return formatResult(appendHint(result, "Planning portfolio created. Call zuckerbot_get_portfolio to review the tier configuration. Portfolio launch is temporarily disabled; use a reviewed legacy draft for live launch."));
         }
         catch (err) {
             return formatError(err);
         }
     });
     // ── 23. Get Portfolio ─────────────────────────────────────────
-    server.tool("zuckerbot_get_portfolio", "Fetch the configuration and current performance snapshot for an audience portfolio by ID. Returns tier definitions, budget allocations, CPA targets, and live performance data. Use this to inspect a portfolio before launching or rebalancing.", {
+    server.tool("zuckerbot_get_portfolio", "Fetch the configuration and current performance snapshot for an audience portfolio by ID. Returns tier definitions, budget allocations, CPA targets, and any existing performance data. Use this to inspect a portfolio for planning, monitoring, or rebalancing an already-active portfolio.", {
         portfolio_id: z.string().describe("Audience portfolio ID"),
     }, async ({ portfolio_id }) => {
         try {
             const result = await client.get(`/portfolios/${portfolio_id}`);
-            return formatResult(appendHint(result, "Review tier config and performance. To adjust settings, call zuckerbot_update_portfolio. To launch on Meta, call zuckerbot_launch_portfolio. To rebalance active tier budgets, call zuckerbot_rebalance_portfolio."));
+            return formatResult(appendHint(result, "Review tier config and performance. To adjust planning settings, call zuckerbot_update_portfolio. Existing active portfolios can be monitored or rebalanced, but new portfolio launch is temporarily disabled."));
         }
         catch (err) {
             return formatError(err);
@@ -1696,26 +1749,23 @@ export function registerTools(server, client) {
         }
     });
     // ── 27. Launch Portfolio ──────────────────────────────────────
-    server.tool("zuckerbot_launch_portfolio", "Launch all tiers in an audience portfolio on Meta. Creates separate Meta campaigns for each tier (prospecting, retargeting, reactivation) using the portfolio's budget allocations and CPA targets. Stored Meta credentials are auto-resolved. Tiers that lack required data (e.g., retargeting without a pixel, lookalike without enough seed events) are skipped with a reason.", {
+    server.tool("zuckerbot_launch_portfolio", "Temporarily unavailable during Dealify launch hardening. Portfolio planning and monitoring remain available, but new multi-tier launches must not create Meta objects. Create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.", {
         portfolio_id: z.string().describe("Audience portfolio ID to launch"),
         meta_access_token: z.string().optional().describe("Optional Meta/Facebook access token override"),
         meta_ad_account_id: z.string().optional().describe("Optional Meta ad account ID override (format: act_XXXXX)"),
         meta_page_id: z.string().optional().describe("Optional Facebook Page ID override"),
     }, async ({ portfolio_id, meta_access_token, meta_ad_account_id, meta_page_id }) => {
-        try {
-            const body = {};
-            if (meta_access_token)
-                body.meta_access_token = meta_access_token;
-            if (meta_ad_account_id)
-                body.meta_ad_account_id = meta_ad_account_id;
-            if (meta_page_id)
-                body.meta_page_id = meta_page_id;
-            const result = await client.post(`/portfolios/${portfolio_id}/launch`, body);
-            return formatResult(appendHint(result, "Portfolio launched. Call zuckerbot_portfolio_performance to monitor tier delivery. Use zuckerbot_rebalance_portfolio weekly to redistribute budgets based on CPA performance."));
-        }
-        catch (err) {
-            return formatError(err);
-        }
+        void meta_access_token;
+        void meta_ad_account_id;
+        void meta_page_id;
+        return formatResult({
+            error: true,
+            code: "portfolio_launch_temporarily_disabled",
+            message: "Portfolio launch is temporarily disabled. Create a campaign with mode='legacy', review it, then call zuckerbot_launch_campaign.",
+            portfolio_id,
+            supported_create_mode: "legacy",
+            supported_launch_tool: "zuckerbot_launch_campaign",
+        });
     });
     // ── 28. Tag Creative ──────────────────────────────────────────
     server.tool("zuckerbot_tag_creative", "Tag Meta ads with creative attributes (hook type, visual style, product focus, CTA type, copy tone, setting) by providing ad metadata and optional asset URLs. ZuckerBot uses Claude vision to analyze the creative and store structured tags. These tags feed the zuckerbot_creative_analysis pipeline. Run this after launching new ads to keep the creative intelligence database current.", {
@@ -1759,8 +1809,10 @@ export function registerTools(server, client) {
         last_name: z.string().optional().describe("Optional last name for identity matching"),
         value: z.number().optional().describe("Optional event value override in major currency units"),
         event_time: z.string().optional().describe("Optional ISO 8601 event timestamp. Defaults to now."),
-        fbclid: z.string().optional().describe("Optional Facebook click ID for fbc cookie attribution"),
-    }, async ({ business_id, source_stage, crm_source, lead_id, meta_lead_id, email, phone, first_name, last_name, value, event_time, fbclid }) => {
+        fbclid: z.string().optional().describe("Optional Facebook click ID; the server builds a well-formed fbc cookie from it"),
+        fbc: z.string().optional().describe("Optional pre-formatted Facebook click cookie (fb.1.<ms>.<fbclid>), forwarded raw — never hashed"),
+        fbp: z.string().optional().describe("Optional Facebook browser ID cookie (_fbp), forwarded raw — never hashed. Improves match quality for every event"),
+    }, async ({ business_id, source_stage, crm_source, lead_id, meta_lead_id, email, phone, first_name, last_name, value, event_time, fbclid, fbc, fbp }) => {
         try {
             const resolvedBusinessId = await client.resolveBusinessId(business_id);
             const body = {
@@ -1787,6 +1839,10 @@ export function registerTools(server, client) {
                 body.event_time = event_time;
             if (fbclid)
                 body.fbclid = fbclid;
+            if (fbc)
+                body.fbc = fbc;
+            if (fbp)
+                body.fbp = fbp;
             const result = await client.post("/capi/events", body);
             return formatResult(appendHint(result, "Event dispatched. Check the status field: 'sent' = successfully delivered to Meta, 'skipped' = CAPI disabled or stage unmapped, 'failed' = Meta rejected the event. Use zuckerbot_capi_status for aggregate delivery metrics."));
         }
@@ -1794,5 +1850,59 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
+    // ── 26. Spec Mode — Campaign From Spec ─────────────────────────
+    server.tool("zuckerbot_create_campaign_from_spec", "Build a complete Meta campaign VERBATIM from a declarative JSON spec — no strategy generation, no copy authoring. Everything is created PAUSED, always; launching remains a separate deliberate call. Recommended flow: send with dry_run=true first to get the fully resolved Graph API payloads without creating anything, review them, then re-send without dry_run to build. Validation failures return per-field errors (path + message). Spec shape: campaign {name, objective OUTCOME_LEADS|OUTCOME_SALES, budget {type CBO_DAILY, amount, bid_strategy HIGHEST_VOLUME|LOWEST_COST_WITHOUT_CAP|COST_CAP}, special_ad_categories}, ad_sets [{name, conversion_location WEBSITE, pixel_id, optimisation_event {type CUSTOM_CONVERSION, id}|{type STANDARD, event}, performance_goal, attribution {click_days, view_days}, targeting {geo, age_min, advantage_audience, excluded_custom_audiences}, placements {mode MANUAL, exclude}}], ads [{name, asset {type IMAGE_SET, refs {1x1,4x5,9x16 — https URLs or uploaded image hashes}}|{type VIDEO, ref — pre-uploaded Meta video id}, primary_text, headline, description, cta, final_url, ad_set_name?}]. Use zuckerbot_list_custom_conversions to find custom conversion ids.", {
+        business_id: z.string().optional().describe("Optional business ID override for the authenticated API key"),
+        spec: z.record(z.string(), z.any()).describe("The declarative campaign spec (see tool description for the shape)"),
+        dry_run: z.boolean().optional().describe("true = return the resolved Graph payloads without creating anything. Strongly recommended before a real build"),
+    }, async ({ business_id, spec, dry_run }) => {
+        try {
+            const resolvedBusinessId = await client.resolveBusinessId(business_id);
+            const body = { business_id: resolvedBusinessId, spec };
+            if (dry_run !== undefined)
+                body.dry_run = dry_run;
+            const result = await client.post("/campaigns/from-spec", body);
+            return formatResult(appendHint(result, "If this was a dry run, review would_create then re-send without dry_run. If it built: the campaign is PAUSED and spends nothing — inspect it in Ads Manager, then launch deliberately when ready."));
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 27. Custom Conversions — List ──────────────────────────────
+    server.tool("zuckerbot_list_custom_conversions", "List the custom conversions on the connected ad account: id, name, rule, source event and pixel. Use this to find the custom conversion id a campaign spec's optimisation_event should reference.", {
+        business_id: z.string().optional().describe("Optional business ID override for the authenticated API key"),
+    }, async ({ business_id }) => {
+        try {
+            const resolvedBusinessId = await client.resolveBusinessId(business_id);
+            const params = new URLSearchParams({ business_id: resolvedBusinessId });
+            const result = await client.get(`/custom-conversions?${params.toString()}`);
+            return formatResult(appendHint(result, "Reference a conversion by id in a spec's optimisation_event: { type: 'CUSTOM_CONVERSION', id }. To create one, call zuckerbot_create_custom_conversion."));
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ── 28. Custom Conversions — Create ────────────────────────────
+    server.tool("zuckerbot_create_custom_conversion", "Create a custom conversion on the connected ad account (requires sufficient Graph permissions on the Meta token — returns insufficient_permission if Meta refuses). Provide the pixel, a name, optionally a rule (e.g. URL contains ...) and the source event type.", {
+        business_id: z.string().optional().describe("Optional business ID override for the authenticated API key"),
+        name: z.string().describe("Display name for the custom conversion"),
+        pixel_id: z.string().describe("Pixel (event source) the conversion is based on"),
+        custom_event_type: z.string().optional().describe("Source event type, defaults to OTHER"),
+        rule: z.record(z.string(), z.any()).optional().describe("Optional Meta rule object, e.g. {\"url\":{\"i_contains\":\"/thank-you\"}}"),
+    }, async ({ business_id, name, pixel_id, custom_event_type, rule }) => {
+        try {
+            const resolvedBusinessId = await client.resolveBusinessId(business_id);
+            const body = { business_id: resolvedBusinessId, name, pixel_id };
+            if (custom_event_type)
+                body.custom_event_type = custom_event_type;
+            if (rule)
+                body.rule = rule;
+            const result = await client.post("/custom-conversions", body);
+            return formatResult(appendHint(result, "Custom conversion created. Reference it in a campaign spec as optimisation_event { type: 'CUSTOM_CONVERSION', id }."));
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
 }
 //# sourceMappingURL=tools.js.map