@koda-sl/baker-cli 0.307.0-dev.ce3b0e7c2 → 0.307.0

package/dist/cli.js

@@ -67,7 +67,7 @@ import {
   validateCanvasDeep,
   withoutCastName,
   ytDlpBlockSignal
-} from "./chunk-XHU3RTH7.js";
+} from "./chunk-WONWYE7B.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -12237,13 +12237,25 @@ registerSchema({
   }
 });
 function extractFields(rows) {
-  if (rows.length === 0) return [];
-  const first = rows[0];
-  return first ? Object.keys(first) : [];
+  const keys = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, keys);
+  return [...keys];
+}
+function resultColumns(gaql, rows) {
+  const observed = extractFields(rows);
+  const columns = [];
+  for (const field of parseSelectedFields(gaql)) {
+    const leaves = observed.filter((key) => key.startsWith(`${field}.`));
+    columns.push(...leaves.length > 0 ? leaves : [field]);
+  }
+  for (const key of observed) columns.push(key);
+  return [...new Set(columns)];
+}
+function isCsvPath(filePath) {
+  return filePath.split(".").pop()?.toLowerCase() === "csv";
 }
 function writeRowsToFile(filePath, rows, fields, append) {
-  const ext = filePath.split(".").pop()?.toLowerCase();
-  if (ext === "csv") {
+  if (isCsvPath(filePath)) {
     if (!append || !existsSync2(filePath)) {
       writeFileSync(filePath, `${toCsvRow(fields)}
 `, "utf-8");
@@ -12251,7 +12263,7 @@ function writeRowsToFile(filePath, rows, fields, append) {
     const csvRows = rows.map((row) => toCsvRow(fields.map((f) => String(row[f] ?? ""))));
     appendFileSync(filePath, `${csvRows.join("\n")}
 `, "utf-8");
-  } else if (ext === "jsonl") {
+  } else if (filePath.split(".").pop()?.toLowerCase() === "jsonl") {
     const lines = rows.map((row) => JSON.stringify(row));
     if (append && existsSync2(filePath)) {
       appendFileSync(filePath, `${lines.join("\n")}
@@ -12341,16 +12353,25 @@ var writeJsonlRows = (rows, _fields, notices) => {
   for (const line of notices) writeLine(line);
   for (const row of rows) writeLine(JSON.stringify(row));
 };
+var OMITTED = "(omitted)";
+var OMITTED_FALSE = `false ${OMITTED}`;
+var OMITTED_LEGEND = `> ${OMITTED} = Google left this field off the row, which is how it sends false, 0 and "not set": the field WAS read. A field with no column here was not read.`;
+function mdCell(row, field, booleanColumns) {
+  if (!(field in row)) return booleanColumns.has(field) ? OMITTED_FALSE : OMITTED;
+  return String(row[field] ?? "").replace(/\|/g, "\\|");
+}
 var writeMdRows = (rows, fields, notices) => {
+  const booleanColumns = new Set(fields.filter((f) => rows.some((row) => typeof row[f] === "boolean")));
   for (const line of notices) writeLine(line);
   writeLine(`| ${fields.join(" | ")} |`);
   writeLine(`| ${fields.map(() => "---").join(" | ")} |`);
-  for (const row of rows) writeLine(`| ${fields.map((f) => String(row[f] ?? "")).join(" | ")} |`);
+  for (const row of rows) writeLine(`| ${fields.map((f) => mdCell(row, f, booleanColumns)).join(" | ")} |`);
+  if (rows.some((row) => fields.some((f) => !(f in row)))) writeLine(OMITTED_LEGEND);
 };
 var ROW_WRITERS = { csv: writeCsvRows, jsonl: writeJsonlRows, md: writeMdRows };
-function writeRows(format, rows, notices) {
+function writeRows(format, rows, columns, notices) {
   const write2 = ROW_WRITERS[format] ?? writeMdRows;
-  write2(rows, Object.keys(rows[0] ?? {}), notices);
+  write2(rows, columns, notices);
   if (rows.length > REPEAT_NOTICE_ABOVE_ROWS) {
     for (const line of notices) writeLine(line);
   }
@@ -12377,7 +12398,7 @@ function outputResults(rows, fieldDescs, warnings, args4, cached, read) {
     );
     return;
   }
-  writeRows(format, rows, warningLines(allWarnings, format));
+  writeRows(format, rows, resultColumns(read.gaql, rows), warningLines(allWarnings, format));
 }
 function resolveGaql(args4, limit) {
   if (args4.preset) {
@@ -12496,15 +12517,27 @@ function missingFieldWarningsFor(gaql, observed, rowCount2) {
     }
   ];
 }
+function unwrittenColumnWarnings(header, observed) {
+  const written = new Set(header);
+  const unwritten = [...observed].filter((key) => !written.has(key));
+  if (unwritten.length === 0) return [];
+  return [
+    {
+      code: "UNWRITTEN_COLUMNS",
+      message: `The file has no column for ${unwritten.join(", ")}: the header was fixed on the first page, which carried none of them, so their values from later pages are NOT in the file. Do not read those columns as empty. SELECT these fields by name instead of their parent, or write to a .jsonl file, then re-run.`
+    }
+  ];
+}
 function keywordServingOptions(gaql) {
   return { statusReasonsSelected: parseSelectedFields(gaql).includes("ad_group_criterion.primary_status_reasons") };
 }
-async function fetchAllPages(body, args4, servingOptions) {
+async function fetchAllPages(gaql, body, args4, servingOptions) {
   let allRows = [];
   let pageToken = args4.cursor;
   let totalRowsWritten = 0;
   let keywordLimits;
   const observedFields = /* @__PURE__ */ new Set();
+  let fileColumns;
   do {
     const requestBody2 = { ...body };
     if (pageToken) requestBody2.pageToken = pageToken;
@@ -12513,7 +12546,8 @@ async function fetchAllPages(body, args4, servingOptions) {
     pageToken = response.pageToken;
     if (args4.out) {
       const shouldAppend = args4.append || totalRowsWritten > 0;
-      writeRowsToFile(resolve(args4.out), rows, extractFields(rows), shouldAppend);
+      fileColumns ??= resultColumns(gaql, rows);
+      writeRowsToFile(resolve(args4.out), rows, fileColumns, shouldAppend);
       totalRowsWritten += rows.length;
       keywordLimits = collectKeywordLimits(rows, servingOptions, keywordLimits);
       foldObservedFields(rows, observedFields);
@@ -12527,7 +12561,8 @@ async function fetchAllPages(body, args4, servingOptions) {
     lastPageToken: pageToken,
     totalRowsWritten,
     keywordLimits: keywordLimits ?? collectKeywordLimits([], servingOptions),
-    observedFields
+    observedFields,
+    fileColumns: fileColumns ?? []
   };
 }
 async function executeQuery(finalQuery, args4, customerId, limit, warnings, useCache, cacheKey) {
@@ -12537,7 +12572,8 @@ async function executeQuery(finalQuery, args4, customerId, limit, warnings, useC
   if (args4.cursor) body.pageToken = args4.cursor;
   if (!useCache) body.skipCache = true;
   const servingOptions = keywordServingOptions(finalQuery);
-  const { allRows, lastPageToken, totalRowsWritten, keywordLimits, observedFields } = await fetchAllPages(
+  const { allRows, lastPageToken, totalRowsWritten, keywordLimits, observedFields, fileColumns } = await fetchAllPages(
+    finalQuery,
     body,
     args4,
     servingOptions
@@ -12553,6 +12589,8 @@ async function executeQuery(finalQuery, args4, customerId, limit, warnings, useC
       ...warnings,
       ...renderKeywordLimits(keywordLimits),
       ...missingFieldWarningsFor(finalQuery, observedFields, totalRowsWritten),
+      // Only a CSV has a header to fall out of; json and jsonl files carry every row whole.
+      ...isCsvPath(args4.out) ? unwrittenColumnWarnings(fileColumns, observedFields) : [],
       ...conversionMixWarnings(finalQuery),
       ...truncation
     ];
@@ -12584,6 +12622,7 @@ async function executeQuery(finalQuery, args4, customerId, limit, warnings, useC
     args4,
     false,
     {
+      gaql: finalQuery,
       effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args4.all)),
       all: Boolean(args4.all),
       nextCursor: lastPageToken
@@ -12701,7 +12740,11 @@ Examples:
           ],
           args4,
           true,
-          { effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args4.all)), all: Boolean(args4.all) }
+          {
+            gaql: finalQuery,
+            effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args4.all)),
+            all: Boolean(args4.all)
+          }
         );
         return;
       }
@@ -13611,7 +13654,7 @@ var SEND_PLATFORM_SPECS = {
   },
   googleAds: {
     title: "Google Ads",
-    eventMeans: "The numeric id of the conversion action in Google Ads",
+    eventMeans: "The id of one of the account's conversion actions \u2014 copy it from `conversionActions`, never type one",
     eventKind: "id",
     credentialFields: ["oauthProviderId"],
     setupHint: "Connect the Google Ads conversion tag to a Google Ads account in Tracking"
@@ -13808,7 +13851,14 @@ var sendsResponseSchema = z28.object({
         title: z28.string(),
         eventMeans: z28.string(),
         setupHint: z28.string(),
-        tags: z28.array(z28.object({ tagId: z28.string(), label: z28.string() }))
+        tags: z28.array(z28.object({ tagId: z28.string(), label: z28.string() })),
+        /**
+         * The conversions the platform already holds, by the id a send's `event`
+         * takes and the name the person gave them. Google Ads only: its `event`
+         * is an id Google issued, and an id the account does not hold is
+         * accepted and files against nothing.
+         */
+        conversionActions: z28.array(z28.object({ id: z28.string(), name: z28.string(), primaryForGoal: z28.boolean() })).optional()
       })
     ),
     /** Every field a send forwards. Nothing to map. */
@@ -22235,7 +22285,26 @@ var OPTIMIZATION_GOALS = [
   "THRUPLAY",
   "VALUE",
   "CONVERSATIONS",
-  "DERIVED_EVENTS"
+  "DERIVED_EVENTS",
+  // Added 2026-09-18 from Meta's own generated enum spec
+  // (facebook-business-sdk-codegen › AdSet_optimization_goal). Every one of these
+  // is a goal Meta accepts and Baker used to refuse at stage time — the messaging
+  // and Instagram-profile goals are the ones that cost real campaigns, because a
+  // click-to-WhatsApp ad set cannot be expressed without them.
+  "ADVERTISER_SILOED_VALUE",
+  "APP_INSTALLS_AND_OFFSITE_CONVERSIONS",
+  "AUTOMATIC_OBJECTIVE",
+  "ENGAGED_PAGE_VIEWS",
+  "IN_APP_VALUE",
+  "MEANINGFUL_CALL_ATTEMPT",
+  "MESSAGING_APPOINTMENT_CONVERSION",
+  "MESSAGING_DEEP_CONVERSATION_AND_FOLLOW",
+  "MESSAGING_PURCHASE_CONVERSION",
+  "PROFILE_AND_PAGE_ENGAGEMENT",
+  "PROFILE_VISIT",
+  "REMINDERS_SET",
+  "SUBSCRIBERS",
+  "VISIT_INSTAGRAM_PROFILE"
 ];
 var OPTIMIZATION_GOALS_REQUIRING_PAGE = [
   "LEAD_GENERATION",
@@ -22257,7 +22326,23 @@ var DESTINATION_TYPES = [
   "WHATSAPP",
   "PHONE_CALL",
   "INSTAGRAM_PROFILE",
-  "SHOP_AUTOMATIC"
+  "SHOP_AUTOMATIC",
+  // Added 2026-09-18 from adcampaign_destination_type. The four MESSAGING_* values
+  // are the click-to-message destinations (Messenger / Instagram Direct / WhatsApp
+  // in every combination Meta ships); without them Baker could not stage a
+  // click-to-WhatsApp ad set at all.
+  "APPLINKS_AUTOMATIC",
+  "FACEBOOK",
+  "FACEBOOK_LIVE",
+  "FACEBOOK_PAGE",
+  "IMAGINE",
+  "INSTAGRAM_LIVE",
+  "INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE",
+  "MESSAGING_INSTAGRAM_DIRECT_MESSENGER",
+  "MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP",
+  "MESSAGING_INSTAGRAM_DIRECT_WHATSAPP",
+  "MESSAGING_MESSENGER_WHATSAPP",
+  "ON_EVENT"
 ];
 var CUSTOM_EVENT_TYPES = [
   "PURCHASE",
@@ -22271,7 +22356,28 @@ var CUSTOM_EVENT_TYPES = [
   "SUBSCRIBE",
   "START_TRIAL",
   "CONTACT",
-  "OTHER"
+  "OTHER",
+  // Added 2026-09-18 from AdPromotedObject_custom_event_type. SCHEDULE,
+  // SUBMIT_APPLICATION, SERVICE_BOOKING_REQUEST and
+  // MESSAGING_CONVERSATION_STARTED_7D are the conversions service businesses and
+  // click-to-message campaigns actually optimize toward.
+  "ACHIEVEMENT_UNLOCKED",
+  "ADD_TO_WISHLIST",
+  "AD_IMPRESSION",
+  "CUSTOMIZE_PRODUCT",
+  "D2_RETENTION",
+  "D7_RETENTION",
+  "DONATE",
+  "FIND_LOCATION",
+  "LEVEL_ACHIEVED",
+  "LISTING_INTERACTION",
+  "MESSAGING_CONVERSATION_STARTED_7D",
+  "RATE",
+  "SCHEDULE",
+  "SERVICE_BOOKING_REQUEST",
+  "SPENT_CREDITS",
+  "SUBMIT_APPLICATION",
+  "TUTORIAL_COMPLETION"
 ];
 var ATTRIBUTION_EVENT_TYPES = ["CLICK_THROUGH", "VIEW_THROUGH", "ENGAGED_VIDEO_VIEW"];
 var ADVANTAGE_AUDIENCE_OPEN_AGE_MAX = 65;
@@ -22390,7 +22496,37 @@ var CTA_TYPES2 = [
   "LINK_CARD",
   "DIAL_CODE",
   "FIND_YOUR_GROUPS",
-  "START_ORDER"
+  "START_ORDER",
+  // Added 2026-09-18 from Meta's generated enum spec
+  // (AdCreative_call_to_action_type). Additive on purpose: 37 of the values above
+  // are absent from that spec and present in the live 400, which is the
+  // disagreement the note above is about — so the spec widens this list and never
+  // prunes it.
+  "AUDIO_CALL",
+  "BROWSE_SHOP",
+  "CONTACT",
+  "FIND_A_GROUP",
+  "FIND_OUT_MORE",
+  "FOLLOW_NEWS_STORYLINE",
+  "FOLLOW_PAGE",
+  "FOLLOW_USER",
+  "GET_DETAILS",
+  "GET_STARTED",
+  "SAY_THANKS",
+  "SEE_SHOP",
+  "SEND_A_GIFT",
+  "SEND_GIFT_MONEY",
+  "SHARE",
+  "SHOP_WITH_AI",
+  "SOTTO_SUBSCRIBE",
+  "TRY_ON_WITH_AI",
+  "VIDEO_ANNOTATION",
+  "VIDEO_CALL",
+  "VIEW_CART",
+  "VIEW_IN_CART",
+  "VISIT_PAGES_FEED",
+  "VISIT_WEBSITE",
+  "WOODHENGE_SUPPORT"
 ];
 var ASSET_FEED_CTA_TYPES = [
   "OPEN_LINK",
@@ -22509,6 +22645,11 @@ var ENROLL_STATUSES = ["OPT_IN", "OPT_OUT"];
 var STAGEABLE_CREATE_STATUSES4 = ["ACTIVE", "PAUSED"];
 var UPDATE_STATUSES = ["ACTIVE", "PAUSED", "ARCHIVED"];
 var CUSTOM_AUDIENCE_SUBTYPES = ["CUSTOM", "WEBSITE", "ENGAGEMENT", "LOOKALIKE"];
+var CUSTOMER_FILE_SOURCES = [
+  "USER_PROVIDED_ONLY",
+  "PARTNER_PROVIDED_ONLY",
+  "BOTH_USER_AND_PARTNER_PROVIDED"
+];
 var MEDIA_KINDS = ["image", "video"];
 var CURRENCY_MINIMUMS2 = {
   USD: { dailyBudgetMin: 1 },
@@ -22526,6 +22667,119 @@ import { z as z31 } from "zod";
 // ../api/src/ads-meta/placements.ts
 var FACEBOOK_POSITIONS_REQUIRING_FEED = ["marketplace", "search", "profile_feed", "notification"];
 var PLACEMENT_TARGETING_DOC = "https://developers.facebook.com/docs/marketing-api/audiences/reference/placement-targeting/";
+var PUBLISHER_PLATFORMS = ["facebook", "instagram", "threads", "messenger", "audience_network"];
+var FACEBOOK_POSITIONS = [
+  "feed",
+  "right_hand_column",
+  "marketplace",
+  "video_feeds",
+  "story",
+  "search",
+  "instream_video",
+  "facebook_reels",
+  "facebook_reels_overlay",
+  "profile_feed",
+  "notification"
+];
+var INSTAGRAM_POSITIONS = [
+  "stream",
+  "story",
+  "explore",
+  "explore_home",
+  "reels",
+  "profile_feed",
+  "ig_search",
+  "profile_reels"
+];
+var AUDIENCE_NETWORK_POSITIONS = ["classic", "rewarded_video"];
+var MESSENGER_POSITIONS = ["sponsored_messages", "story"];
+var THREADS_POSITIONS = ["threads_stream"];
+var DEVICE_PLATFORMS = ["mobile", "desktop", "connected_tv"];
+var PLACEMENT_VOCABULARIES = {
+  publisher_platforms: PUBLISHER_PLATFORMS,
+  facebook_positions: FACEBOOK_POSITIONS,
+  instagram_positions: INSTAGRAM_POSITIONS,
+  audience_network_positions: AUDIENCE_NETWORK_POSITIONS,
+  messenger_positions: MESSENGER_POSITIONS,
+  threads_positions: THREADS_POSITIONS,
+  device_platforms: DEVICE_PLATFORMS
+};
+var SAME_SURFACE_ON_THIS_PLATFORM = {
+  facebook_positions: { reels: "facebook_reels", stream: "feed", stories: "story", ig_search: "search" },
+  instagram_positions: {
+    feed: "stream",
+    facebook_reels: "reels",
+    stories: "story",
+    search: "ig_search"
+  }
+};
+function placementFieldsAccepting(value, except) {
+  return Object.keys(PLACEMENT_VOCABULARIES).filter(
+    (field) => field !== except && PLACEMENT_VOCABULARIES[field].includes(value)
+  );
+}
+function placementValueIssue(field, value) {
+  const renamed = SAME_SURFACE_ON_THIS_PLATFORM[field]?.[value];
+  if (renamed) {
+    return {
+      field,
+      value,
+      kind: "wrong-field",
+      fix: `Meta calls that surface "${renamed}" in ${field} \u2014 use "${renamed}"`
+    };
+  }
+  const elsewhere = placementFieldsAccepting(value, field);
+  if (elsewhere.length > 0) {
+    return {
+      field,
+      value,
+      kind: "wrong-field",
+      fix: `"${value}" belongs to ${elsewhere.join(" / ")}, not ${field} \u2014 move it there or drop it`
+    };
+  }
+  return {
+    field,
+    value,
+    kind: "unknown",
+    fix: `"${value}" is not a placement Baker knows; ${field} accepts ${PLACEMENT_VOCABULARIES[field].join(", ")}`
+  };
+}
+function invalidPlacementValues(targeting) {
+  const issues = [];
+  for (const field of Object.keys(PLACEMENT_VOCABULARIES)) {
+    const allowed = PLACEMENT_VOCABULARIES[field];
+    const selected = targeting?.[field] ?? [];
+    for (const value of selected) {
+      if (!allowed.includes(value)) {
+        issues.push(placementValueIssue(field, value));
+      }
+    }
+  }
+  return issues;
+}
+function placementCoRequirementIssues(targeting) {
+  const facebook = targeting?.facebook_positions ?? [];
+  const instagram = targeting?.instagram_positions ?? [];
+  const threads = targeting?.threads_positions ?? [];
+  const devices = targeting?.device_platforms;
+  const issues = [];
+  if (facebook.includes("story")) {
+    if (!facebook.includes("feed") && !instagram.includes("story")) {
+      issues.push(
+        'Meta refuses Facebook "story" on its own \u2014 select "feed" in facebook_positions or "story" in instagram_positions alongside it'
+      );
+    }
+    if (devices && !devices.includes("mobile")) {
+      issues.push(
+        'Facebook "story" only runs on mobile \u2014 add "mobile" to device_platforms or drop the story placement'
+      );
+    }
+  }
+  if (threads.includes("threads_stream") && !instagram.includes("stream")) {
+    issues.push('Threads "threads_stream" cannot be selected alone \u2014 add "stream" to instagram_positions');
+  }
+  return issues;
+}
 var CONSTRAINED_PLACEMENTS = [
   {
     position: "facebook_reels_overlay",
@@ -22640,6 +22894,7 @@ var metaTargetingSchema = z31.object({
   instagram_positions: z31.array(z31.string()).optional(),
   audience_network_positions: z31.array(z31.string()).optional(),
   messenger_positions: z31.array(z31.string()).optional(),
+  threads_positions: z31.array(z31.string()).optional(),
   device_platforms: z31.array(z31.string()).optional(),
   targeting_automation: z31.object({ advantage_audience: z31.union([z31.literal(0), z31.literal(1)]) }).partial().optional()
 }).catchall(z31.unknown());
@@ -22771,6 +23026,13 @@ var adSetFields = {
   start_time: z31.number().int().positive().optional(),
   end_time: z31.number().int().positive().optional(),
   targeting: metaTargetingSchema,
+  /**
+   * The live ad set this one was copied from, verbatim, by `duplicate`. Baker
+   * only — `adSetCommonBody` never sends it to Meta. Set exclusively when the
+   * targeting IS the source's targeting, because that is what it licenses:
+   * placement validation is skipped for it (see `validateAdSetPlacements`).
+   */
+  clonedFrom: z31.string().regex(NUMERIC_ID_REGEX3).optional(),
   /** EU Digital Services Act: who benefits from / pays for the ad. Auto-filled from the account for EU geo when omitted. */
   dsa_beneficiary: z31.string().min(1).max(100).optional(),
   dsa_payor: z31.string().min(1).max(100).optional()
@@ -22871,6 +23133,9 @@ function validateAdvantageAudience(p, ctx) {
   }
 }
 function validateAdSetPlacements(p, ctx) {
+  if (p.clonedFrom) {
+    return;
+  }
   const missingFeed = positionsMissingRequiredFeed(p.targeting);
   if (missingFeed.length > 0) {
     ctx.addIssue({
@@ -22879,6 +23144,19 @@ function validateAdSetPlacements(p, ctx) {
       message: `Meta requires "feed" alongside ${missingFeed.join(", ")} \u2014 add "feed" to facebook_positions or drop those positions (${PLACEMENT_TARGETING_DOC})`
     });
   }
+  for (const issue of invalidPlacementValues(p.targeting)) {
+    if (issue.kind !== "wrong-field") {
+      continue;
+    }
+    ctx.addIssue({
+      code: "custom",
+      path: ["targeting", issue.field],
+      message: `${issue.field} does not accept "${issue.value}". ${issue.fix} (${PLACEMENT_TARGETING_DOC})`
+    });
+  }
+  for (const message of placementCoRequirementIssues(p.targeting)) {
+    ctx.addIssue({ code: "custom", path: ["targeting"], message: `${message} (${PLACEMENT_TARGETING_DOC})` });
+  }
 }
 var adSetCreateSchema = z31.object(adSetFields).superRefine((p, ctx) => {
   validateAdSetBudgetAndBid(p, ctx);
@@ -23195,7 +23473,7 @@ var customAudienceCreateSchema = z31.object({
   name: z31.string().min(1).max(META_LIMITS.audience.nameMax),
   subtype: z31.enum(CUSTOM_AUDIENCE_SUBTYPES),
   description: z31.string().max(500).optional(),
-  customer_file_source: z31.string().optional(),
+  customer_file_source: z31.enum(CUSTOMER_FILE_SOURCES).optional(),
   retention_days: z31.number().int().min(1).max(META_LIMITS.audience.retentionDaysMax).optional(),
   lookalike_spec: lookalikeSpecSchema.optional(),
   /** Website/engagement rule — structural passthrough validated by Meta. */
@@ -29296,7 +29574,7 @@ function stagedHints(definitions) {
   const staged = definitions.filter((row) => row.staged === true);
   if (staged.length === 0) return [];
   return [
-    `Staged on this chat, not counted yet: ${staged.map((row) => `"${row.name}"`).join(", ")}. The person sees ${staged.length === 1 ? "it" : "them"} under Conversions in the chat's changes, and ${staged.length === 1 ? "it counts" : "they count"} \u2014 history included \u2014 from when they publish the chat; discarding the chat drops ${staged.length === 1 ? "it" : "them"}. Tell them that, not that it is already counted.`,
+    `Staged on this chat, not counted yet: ${staged.map((row) => `"${row.name}"`).join(", ")}. The person sees ${staged.length === 1 ? "it" : "them"} under Sources in the chat's changes, on the event's own row, and ${staged.length === 1 ? "it counts" : "they count"} from when they publish the chat; discarding the chat drops ${staged.length === 1 ? "it" : "them"}. Publishing also rescores events Baker ALREADY RECORDED under the key \u2014 never anything that happened in HubSpot or elsewhere before the event existed, so an event this chat just made starts at zero. Tell them that, not that it is already counted.`,
     'When you talk to the person, call each event by its name ("Appointment scheduled"), never its key (`page:Appointment scheduled`): the key is how Baker spells it internally, and the `page:` part means nothing to them.'
   ];
 }
@@ -30044,7 +30322,7 @@ var args = {
   },
   event: {
     type: "string",
-    description: 'What the platform calls it \u2014 `platforms[].eventMeans` says what each one takes: a Meta or Google Analytics event name (Purchase, Lead, generate_lead), a Google Ads conversion action id, a LinkedIn conversion rule id, an X event tag id. On Meta and Google Analytics it may be WRITTEN FROM THE EVENT with the same {{path}} mentions --parameter takes: --event {{properties.plan}} sends each event under the plan it carries, --event "Purchase {{properties.tier}}" mixes text and a field. An event carrying nothing there is not uploaded. Google Ads, LinkedIn and X take an id THEY issued, so a template is refused there \u2014 pass what varies as a --parameter instead. For a GOOGLE ADS id, list the account\'s conversion actions first and pick by name \u2014 `baker ads google query "SELECT conversion_action.id, conversion_action.name, conversion_action.primary_for_goal FROM conversion_action WHERE conversion_action.status = \'ENABLED\'"` \u2014 never guess: Google accepts an upload against an id the account does not hold and files it against nothing',
+    description: 'What the platform calls it \u2014 `platforms[].eventMeans` says what each one takes: a Meta or Google Analytics event name (Purchase, Lead, generate_lead), a Google Ads conversion action id copied from `platforms[].conversionActions` (never typed: an id the account does not hold is refused), a LinkedIn conversion rule id, an X event tag id. On Meta and Google Analytics it may be WRITTEN FROM THE EVENT with the same {{path}} mentions --parameter takes: --event {{properties.plan}} sends each event under the plan it carries, --event "Purchase {{properties.tier}}" mixes text and a field. An event carrying nothing there is not uploaded. Google Ads, LinkedIn and X take an id THEY issued, so a template is refused there \u2014 pass what varies as a --parameter instead. For a GOOGLE ADS id, list the account\'s conversion actions first and pick by name \u2014 `baker ads google query "SELECT conversion_action.id, conversion_action.name, conversion_action.primary_for_goal FROM conversion_action WHERE conversion_action.status = \'ENABLED\'"` \u2014 never guess: Google accepts an upload against an id the account does not hold and files it against nothing',
     required: false
   },
   account: {
@@ -31472,7 +31750,7 @@ var conversionsCommand3 = (() => {
   const args4 = {
     event: {
       type: "string",
-      description: "The event to start counting, from the `candidates` or `--flow` list: form:<form>:<step>:<trigger>, submit:<form>, page:<name>, or exit:<host>. Requires --name. REPEATABLE \u2014 pass it several times with one --name to count all of them as that single outcome, which is the whole point of the name. Inside a chat it is STAGED: the chat lists it under Conversions and it counts from when the chat is published \u2014 then it scores the WHOLE history, not just from then on, so counting the right event also corrects last month's reports. An event a client's system sends (the API, HubSpot) counts here too: it is credited to the LAST LANDING its person viewed, up to 90 days before, so a deal won weeks later is that landing's conversion. A person who never saw a landing is not counted at all. Such an event is usually also a funnel step (`baker funnel`) and a send (`baker analytics sends`)",
+      description: "The event to start counting, from the `candidates` or `--flow` list: form:<form>:<step>:<trigger>, submit:<form>, page:<name>, or exit:<host>. Requires --name. REPEATABLE \u2014 pass it several times with one --name to count all of them as that single outcome, which is the whole point of the name. Inside a chat it is STAGED: the chat lists it under Sources, on its event, and it counts from when the chat is published \u2014 then it scores the WHOLE history, not just from then on, so counting the right event also corrects last month's reports. An event a client's system sends (the API, HubSpot) counts here too: it is credited to the LAST LANDING its person viewed, up to 90 days before, so a deal won weeks later is that landing's conversion. A person who never saw a landing is not counted at all. Such an event is usually also a funnel step (`baker funnel`) and a send (`baker analytics sends`)",
       required: false
     },
     name: {
@@ -31529,7 +31807,7 @@ var conversionsCommand3 = (() => {
   return defineCommand97({
     meta: {
       name: "conversions",
-      description: "What this company counts as a conversion \u2014 the numerator of every conversion rate on Measure. A page event (a Form ending, a data-baker-* event) and an event one of the client's systems sends (a HubSpot event made with `baker analytics sources --create-hubspot`, an order the server posts) both count; a system's event is credited to the last landing its person viewed. A HubSpot event is `page:<its name>` here \u2014 `--event 'page:Deal won' --name 'Deal won'`. Run with no flags first: an empty `definitions` list means every conversion number in every other report is zero \u2014 not because nobody converted, but because nothing is marked as converting, and Baker never guesses. Add `--candidates` to see everything these pages actually do (every Form step, every data-baker-* event, every outbound destination) with counts and whether it is already counted; that list is where an event key comes from, so never invent one. Then `--event <key> --name 'Booked a call'` to count it. Inside a chat a change is STAGED: the person sees it under Conversions in the chat's changes and it applies when they publish, retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers. A read shows a proposal marked `staged`. Call an event by its name when you talk to the person, never by its key. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
+      description: "What this company counts as a conversion \u2014 the numerator of every conversion rate on Measure. A page event (a Form ending, a data-baker-* event) and an event one of the client's systems sends (a HubSpot event made with `baker analytics sources --create-hubspot`, an order the server posts) both count; a system's event is credited to the last landing its person viewed. A HubSpot event is `page:<its name>` here \u2014 `--event 'page:Deal won' --name 'Deal won'`. Run with no flags first: an empty `definitions` list means every conversion number in every other report is zero \u2014 not because nobody converted, but because nothing is marked as converting, and Baker never guesses. Add `--candidates` to see everything these pages actually do (every Form step, every data-baker-* event, every outbound destination) with counts and whether it is already counted; that list is where an event key comes from, so never invent one. Then `--event <key> --name 'Booked a call'` to count it. Inside a chat a change is STAGED: the person sees it under Sources in the chat's changes, on the event's own row and it applies when they publish, retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers. A read shows a proposal marked `staged`. Call an event by its name when you talk to the person, never by its key. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
     },
     args: args4,
     run: async ({ args: raw }) => {
@@ -46440,6 +46718,9 @@ function inertSideEffectHints(tree) {
     "Fix each by setting the id its own step raises: `baker flows schema node <nodeType>` lists them."
   ];
 }
+function funnelPlacementHint(slug) {
+  return `Whether this Form moves anyone along the company funnel is not in _data.json either: \`baker funnel\` names every Form no step counts. If it names this one, place its ending on the step it moves people to \u2014 \`submit:${slug}\`, or its booking trigger, both listed by \`baker funnel --moments\` \u2014 with \`baker funnel --step\`, which replaces the step it names, so keep that step's other ways in.`;
+}
 function displayName(slug) {
   const tree = readFlowTree(slug);
   const name = tree.displayName;
@@ -46503,7 +46784,8 @@ var showCommand4 = defineCommand127({
         // an answer that is not in this file at all. What a Form counts is a
         // named event in Baker, and a Form can be perfectly configured, fire
         // every pixel it has, and still report converting nobody.
-        `What this Form counts as a conversion is NOT in _data.json and not in any side effect here: it is a named event held in Baker. Read it, and this Form's own endings spelled as event keys, with \`baker analytics conversions --flow ${slug}\`.`
+        `What this Form counts as a conversion is NOT in _data.json and not in any side effect here: it is a named event held in Baker. Read it, and this Form's own endings spelled as event keys, with \`baker analytics conversions --flow ${slug}\`.`,
+        funnelPlacementHint(slug)
       ]
     });
   }
@@ -47107,7 +47389,7 @@ function parsePreset(raw) {
 var args3 = {
   steps: {
     type: "string",
-    description: 'The WHOLE funnel, as a JSON array. One object per step: {"key":"meeting_held","displayName":"Demo held","stepClass":"engaged","after":["lead"],"triggers":[{"id":"t1","kind":"event","eventKey":"page:demo_held"}]}. It REPLACES the funnel rather than adding to it, so read first and restate everything you want to keep. `key` is permanent and reaches reporting and URLs (lowercase, digits, underscores); `displayName` is the client\'s own words and can be anything. `stepClass` is the stage, one of visited, lead, engaged, customer, repeat, lost \u2014 six plain words every business has, used to compare one company\'s funnel with another\'s. `after` is a LIST, so two ways into one step is expressible and normal. `triggers` is what MOVES somebody onto the step, any one of them being enough, and there are two kinds: `{"kind":"event","eventKey":"submit:contact"}` for an outcome the company counts, and `{"kind":"landing","landingId":"<from --moments>"}` for a landing page being viewed. A moment nobody has named yet is named first \u2014 `baker analytics conversions --event <key> --name <name>` \u2014 and then used as a conversion; there is no other kind. Take every key and id from `--moments`. A trigger carries no amount: an event is worth what it says, and a step is worth the sum. Where a step SENDS its people is not written here: a send belongs to the conversion (`baker analytics sends`), and the step reads its conversions\' sends back as `sends[]`',
+    description: 'The WHOLE funnel, as a JSON array. One object per step: {"key":"meeting_held","displayName":"Demo held","stepClass":"engaged","after":["lead"],"triggers":[{"id":"t1","kind":"event","eventKey":"page:demo_held"}]}. It REPLACES the funnel rather than adding to it, so read first and restate everything you want to keep. `key` is permanent and reaches reporting and URLs (lowercase, digits, underscores); `displayName` is the client\'s own words and can be anything. `stepClass` is the stage, one of visited, lead, engaged, customer, repeat, lost \u2014 six plain words every business has, used to compare one company\'s funnel with another\'s. `after` is a LIST, so two ways into one step is expressible and normal. `triggers` is what MOVES somebody onto the step, any one of them being enough, and there are three kinds: `{"id":"t1","kind":"event","eventKey":"submit:contact"}` for anything the company\'s Forms, pages or systems produced, used by its own key with nothing named first; `{"id":"t2","kind":"landing","landingId":"<from --moments>"}` for one landing page being viewed; `{"id":"t3","kind":"any_landing"}` for any landing being viewed. Take every key and id from `--moments`. A trigger carries no amount: an event is worth what it says, and a step is worth the sum. Where a step SENDS its people is not written here: a send belongs to the system\'s event (`baker analytics sends`), and the step reads it back as `sends[]`',
     required: false
   },
   step: {
@@ -47122,12 +47404,12 @@ var args3 = {
   },
   preset: {
     type: "string",
-    description: "Draw one of the ready-made graphs instead of stating steps: b2b_sales, b2b_inbound, saas_self_serve, saas_sales_assisted, ecommerce_purchase. Start here for a company with no funnel \u2014 pick the closest, then rename its steps with --steps. Run --templates first to see what each one contains",
+    description: "Draw one of the ready-made graphs instead of stating steps: b2b_sales, b2b_inbound, saas_self_serve, saas_sales_assisted, ecommerce_purchase. It draws over the whole funnel \u2014 every company already has one, so prefer --step to change a step. Run --templates first to see what each one contains",
     required: false
   },
   moments: {
     type: "boolean",
-    description: "Also return everything a trigger can name, so a trigger is PICKED rather than invented: `conversions` (the outcomes it counts, by key and name \u2014 a `conversion` trigger takes the key as is), `events` (every event this company's Forms, pages and systems actually produced in the window, with volume, the Form it belongs to, `origin` \u2014 `site` for a page or Form, `systems` for the client's own server, `both` \u2014 and `countedAs` when it is already a conversion; one that is not is named first with `baker analytics conversions`), `sources` (the client's own systems that post events to Baker, by the `page:<name>` key each raises, pickable before its first send arrives) and `landings` (its pages, by the id a `landing` trigger takes). Use this before writing any `triggers`: a key typed from memory saves, publishes and counts nobody forever",
+    description: "Also return everything a trigger can name, so a trigger is PICKED rather than invented: `events` (every event this company's Forms, pages and systems actually produced in the window, with volume, the Form it belongs to, `origin` \u2014 `site` for a page or Form, `systems` for the client's own server, `both` \u2014 and `countedAs` when the company also counts it as a page conversion, which a trigger does not need), `sources` (the client's own systems that post events to Baker, by the `page:<name>` key each raises, pickable before its first send arrives) and `landings` (its pages, by the id a `landing` trigger takes). Use this before writing any `triggers`: a key typed from memory saves, publishes and counts nobody forever",
     required: false
   },
   days: {
@@ -47137,7 +47419,7 @@ var args3 = {
   },
   templates: {
     type: "boolean",
-    description: "Also return the libraries: the suggested steps with their stages, and the four presets. Where a step can be sent is not here \u2014 a send belongs to the conversion, and `baker analytics sends` lists the platforms and the tags that can send",
+    description: "Also return the libraries: the suggested steps with their stages, the presets, and `stages[]` (the six stages with the test to apply). Where a step can be sent is not here \u2014 a send belongs to the system's event, and `baker analytics sends` lists the platforms and the tags that can send",
     required: false
   }
 };
@@ -47149,7 +47431,7 @@ registerSchema({
 var funnelCommand2 = defineCommand128({
   meta: {
     name: "funnel",
-    description: 'Start here: run with no flags to see the funnel this company has, with the last 30 days of PEOPLE counted beside every step \u2014 `people` reached it, `atLeast` got at least that far, `before` got as far as the step before, `share` is the ratio, and `worstStep` names where the most people are lost. An empty `steps` list means it has none, and until it does nothing can answer \'how far did the people from this campaign get\' \u2014 only how many converted. Then `--moments` for everything a trigger can name (the outcomes it counts, every event the company\'s Forms, pages and systems actually produced, its sources, its landings), `--templates` for the ready-made graphs and the step library; `--preset b2b_sales` to draw the closest one and `--steps \'<json>\'` to put it in the client\'s own words. A step is reached by two kinds of thing and nothing else: a conversion (`{"kind":"event","eventKey":"<from moments.conversions>"}`) or a landing being viewed (`{"kind":"landing","landingId":"<from moments.landings>"}`), which is where most funnels start. A moment nobody has named is named as a conversion first (`baker analytics conversions --event <key> --name <name>`), then used. Pick every trigger from `--moments`, never from memory. A step with no `triggers` advances NOBODY and reports zero forever without warning \u2014 that is what the hints keep pointing at. There is no default door: a Form is only counted where a trigger names it. Each step comes back with `sends[]`, read-only: where the people who reach it are sent and what happened, read off its conversions. A send is set on the CONVERSION with `baker analytics sends`, never on a step, and once published it spends ad budget \u2014 a failed one is named in the hints. Everything here is STAGED: it becomes the company\'s funnel in one piece when the chat is published \u2014 the client sees it on the canvas in this chat and can edit it there too \u2014 and the previous version stays on file so what was already measured under it is not lost.'
+    description: 'Start here: run with no flags to see the funnel this company has, with the last 30 days of PEOPLE counted beside every step \u2014 `people` reached it, `atLeast` got at least that far, `before` got as far as the step before, `share` is the ratio, and `worstStep` names where the most people are lost. Every company has one from the day it exists: Visited (any landing) \u2192 Became a lead \u2192 Became a customer, the last two with no way in until somebody gives them one. Then `--moments` for everything a trigger can name (every event the company\'s Forms, pages and systems actually produced, its sources, its landings), and `--step \'<json>\'` to add or change ONE step in the client\'s own words \u2014 it replaces the step with that key, so restate its `after` and the triggers it keeps. A step is reached by three kinds of thing and nothing else: an event by its own key (`{"id":"t1","kind":"event","eventKey":"<from moments.events or moments.sources>"}`), one landing being viewed (`{"id":"t2","kind":"landing","landingId":"<from moments.landings>"}`) or any landing (`{"id":"t3","kind":"any_landing"}`). Nothing has to be named first. Pick every trigger from `--moments`, never from memory. A step with no `triggers` advances NOBODY and reports zero forever without warning \u2014 that is what the hints keep pointing at. There is no default door: a Form is only counted where a trigger names it. Keep it true: a chat that adds a Form, a Source or an event that moves people forward places it on its step in the same chat. Each step comes back with `sends[]`, read-only: where the people who reach it are sent and what happened, read off the system events behind its ways in. A send is set on the event with `baker analytics sends`, never on a step, and once published it spends ad budget \u2014 a failed one is named in the hints. Everything here is STAGED: it becomes the company\'s funnel in one piece when the chat is published \u2014 the client sees it on the canvas in this chat and can edit it there too \u2014 and the previous version stays on file so what was already measured under it is not lost.'
   },
   args: args3,
   run: async ({ args: raw }) => {