@koda-sl/baker-cli 0.139.0 → 0.140.1-dev.253d2418a

package/dist/cli.js

@@ -34,7 +34,7 @@ import {
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-TAGQCU36.js";
+} from "./chunk-TXNOPO6P.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -73,7 +73,7 @@ import {
 } from "./chunk-RK67WL4O.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand174, runMain } from "citty";
+import { defineCommand as defineCommand175, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand18 } from "citty";
@@ -1008,6 +1008,33 @@ var followResponseSchema = z2.object({
   preview: resolvePreviewSchema.nullable(),
   candidates: z2.array(corpusAdvertiserSchema).nullable()
 });
+var FOLLOW_BATCH_MAX = 50;
+var followBatchRequestSchema = z2.object({
+  // One entry per brand — a domain (best; resolves both Meta + LinkedIn), a
+  // profile / ad-library URL, or a brand name.
+  inputs: z2.array(z2.string().min(1)).min(1).max(FOLLOW_BATCH_MAX),
+  // How to read every input (not a tracking limit — a domain still resolves
+  // every platform we can). Defaults to reading inputs as Meta identities.
+  platform: adLibraryPlatformSchema.default("meta")
+});
+var followBatchResultSchema = z2.object({
+  // Echoes the input so the caller can line results up with what it sent.
+  input: z2.string(),
+  // "following"/"added" mirror the single-follow statuses; "ambiguous" needs a
+  // manual pick; "failed" = we couldn't resolve or add it (see `error`).
+  status: z2.enum(["following", "added", "ambiguous", "failed"]),
+  advertiser: followedAdvertiserSchema.nullable(),
+  // Present only when status is "failed" — a plain-language reason.
+  error: z2.string().nullable()
+});
+var followBatchResponseSchema = z2.object({
+  results: z2.array(followBatchResultSchema),
+  // Rollup counts across the batch for a one-glance summary.
+  followed_count: z2.number(),
+  added_count: z2.number(),
+  ambiguous_count: z2.number(),
+  failed_count: z2.number()
+});
 var unfollowRequestSchema = z2.object({
   // Accept either the Baker subscription id or the corpus advertiser id.
   followed_id: z2.string().optional(),
@@ -3684,7 +3711,8 @@ Examples:
   baker actions claim <id>
   baker actions create --name "Build hero" --tags landing,creative --description "..."
   baker actions complete <id>
-  baker actions discard <id> --reason "obsolete"`
+  baker actions discard <id> --reason "obsolete"
+Full guide: __tooling__/docs/tools/baker/actions.md`
   },
   subCommands: {
     list: listCommand2,
@@ -7657,7 +7685,8 @@ Staged writes (never touch Google until the chat is published):
   baker ads google budgets create --customer-id 1234567890 --name "Search" --amount 50
   baker ads google campaigns create --customer-id 1234567890 --name "Brand" --channel-type SEARCH --budget-ref g_temp_\u2026 --bidding-strategy MANUAL_CPC
   baker ads google keyword-lists create --customer-id 1234567890 --name "Brand exclusions"
-  baker ads google draft list                  \u2014 review staged Google Ads changes`
+  baker ads google draft list                  \u2014 review staged Google Ads changes
+Full guide: __tooling__/docs/tools/baker/ads-google.md`
   },
   subCommands: {
     accounts: accountsCommand,
@@ -11117,7 +11146,8 @@ published; if the company's LinkedIn-write flag is off the publish is simulated)
 
 Account ID format:
   --account-id accepts numeric (503001492) or URN (urn:li:sponsoredAccount:503001492).
-  Set BAKER_LINKEDIN_AD_ACCOUNT_ID env to skip --account-id on every call.`
+  Set BAKER_LINKEDIN_AD_ACCOUNT_ID env to skip --account-id on every call.
+Full guide: __tooling__/docs/tools/baker/ads-linkedin.md`
   },
   subCommands: {
     accounts: accountsCommand2,
@@ -11318,11 +11348,13 @@ var SPECIAL_AD_CATEGORIES = [
   "NONE",
   "HOUSING",
   "EMPLOYMENT",
+  /** Deprecated by Meta on 2025-01-14 — replaced by FINANCIAL_PRODUCTS_SERVICES. Still accepted as input and mapped on the wire. */
   "CREDIT",
   "ISSUES_ELECTIONS_POLITICS",
   "FINANCIAL_PRODUCTS_SERVICES",
   "ONLINE_GAMBLING_AND_GAMING"
 ];
+var SPECIAL_CATEGORIES_REQUIRING_COUNTRY = ["ISSUES_ELECTIONS_POLITICS"];
 var BUYING_TYPES = ["AUCTION", "RESERVED"];
 var BID_STRATEGIES = [
   "LOWEST_COST_WITHOUT_CAP",
@@ -11331,6 +11363,10 @@ var BID_STRATEGIES = [
   "LOWEST_COST_WITH_MIN_ROAS"
 ];
 var BID_STRATEGIES_REQUIRING_AMOUNT = ["LOWEST_COST_WITH_BID_CAP", "COST_CAP"];
+var BID_STRATEGIES_FORBIDDING_AMOUNT = [
+  "LOWEST_COST_WITHOUT_CAP",
+  "LOWEST_COST_WITH_MIN_ROAS"
+];
 var BILLING_EVENTS = [
   "APP_INSTALLS",
   "CLICKS",
@@ -11365,6 +11401,14 @@ var OPTIMIZATION_GOALS = [
   "CONVERSATIONS",
   "DERIVED_EVENTS"
 ];
+var OPTIMIZATION_GOALS_REQUIRING_PAGE = [
+  "LEAD_GENERATION",
+  "QUALITY_LEAD",
+  "PAGE_LIKES"
+];
+var OPTIMIZATION_GOALS_REQUIRING_PIXEL = ["OFFSITE_CONVERSIONS"];
+var OPTIMIZATION_GOALS_REQUIRING_CONVERSION_SOURCE = ["VALUE"];
+var OPTIMIZATION_GOALS_REQUIRING_APP = ["APP_INSTALLS"];
 var DESTINATION_TYPES = [
   "WEBSITE",
   "APP",
@@ -11394,6 +11438,8 @@ var CUSTOM_EVENT_TYPES = [
   "OTHER"
 ];
 var ATTRIBUTION_EVENT_TYPES = ["CLICK_THROUGH", "VIEW_THROUGH", "ENGAGED_VIDEO_VIEW"];
+var ADVANTAGE_AUDIENCE_OPEN_AGE_MAX = 65;
+var ADVANTAGE_AUDIENCE_MAX_HARD_AGE_MIN = 25;
 var CTA_TYPES2 = [
   "LEARN_MORE",
   "SHOP_NOW",
@@ -11491,6 +11537,44 @@ var metaTargetingSchema = z14.object({
   device_platforms: z14.array(z14.string()).optional(),
   targeting_automation: z14.object({ advantage_audience: z14.union([z14.literal(0), z14.literal(1)]) }).partial().optional()
 }).catchall(z14.unknown());
+var GEO_INCLUSION_KEYS = [
+  "countries",
+  "country_groups",
+  "regions",
+  "cities",
+  "zips",
+  "geo_markets",
+  "places",
+  "custom_locations",
+  "electoral_districts",
+  "subcities",
+  "neighborhoods"
+];
+function targetingHasGeo(t) {
+  const geo = t?.geo_locations;
+  return Boolean(
+    geo && GEO_INCLUSION_KEYS.some((key) => Array.isArray(geo[key]) && geo[key].length > 0)
+  );
+}
+function targetingHasGeoOrAudience(t) {
+  if (!t) {
+    return false;
+  }
+  return targetingHasGeo(t) || Boolean(t.custom_audiences?.length);
+}
+function advantageAudienceSetting(t) {
+  const value = t.targeting_automation?.advantage_audience;
+  return value === 0 || value === 1 ? value : void 0;
+}
+function targetingHardLimitsDemographics(t) {
+  if (!t) {
+    return false;
+  }
+  const narrowsAgeMax = typeof t.age_max === "number" && t.age_max < ADVANTAGE_AUDIENCE_OPEN_AGE_MAX;
+  const narrowsAgeMin = typeof t.age_min === "number" && t.age_min > ADVANTAGE_AUDIENCE_MAX_HARD_AGE_MIN;
+  const narrowsGender = Array.isArray(t.genders) && t.genders.length === 1;
+  return narrowsAgeMax || narrowsAgeMin || narrowsGender;
+}
 var specialAdCategoriesSchema = z14.array(z14.enum(SPECIAL_AD_CATEGORIES)).default(["NONE"]);
 var campaignCreateSchema3 = z14.object({
   name: z14.string().min(1).max(META_LIMITS.campaign.nameMax),
@@ -11514,6 +11598,14 @@ var campaignCreateSchema3 = z14.object({
   if (p.stop_time && p.start_time && p.stop_time <= p.start_time) {
     ctx.addIssue({ code: "custom", path: ["stop_time"], message: "stop_time must be after start_time" });
   }
+  const needsCountry = p.special_ad_categories.some((c) => SPECIAL_CATEGORIES_REQUIRING_COUNTRY.includes(c));
+  if (needsCountry && !p.special_ad_category_country?.length) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["special_ad_category_country"],
+      message: "ISSUES_ELECTIONS_POLITICS campaigns need special_ad_category_country \u2014 pass the 2-letter country code(s) the ads run in"
+    });
+  }
 });
 var campaignUpdateSchema3 = z14.object({
   name: z14.string().min(1).max(META_LIMITS.campaign.nameMax).optional(),
@@ -11565,8 +11657,41 @@ var adSetFields = {
   attribution_spec: attributionSpecSchema.optional(),
   start_time: z14.number().int().positive().optional(),
   end_time: z14.number().int().positive().optional(),
-  targeting: metaTargetingSchema
+  targeting: metaTargetingSchema,
+  /** EU Digital Services Act: who benefits from / pays for the ad. Auto-filled from the account for EU geo when omitted. */
+  dsa_beneficiary: z14.string().min(1).max(100).optional(),
+  dsa_payor: z14.string().min(1).max(100).optional()
 };
+function validateBidStrategy(p, ctx) {
+  const strategy = p.bid_strategy;
+  if (!strategy) {
+    return;
+  }
+  if (BID_STRATEGIES_REQUIRING_AMOUNT.includes(strategy) && !p.bidAmount) {
+    ctx.addIssue({ code: "custom", path: ["bidAmount"], message: `${strategy} requires a bidAmount` });
+  }
+  if (BID_STRATEGIES_FORBIDDING_AMOUNT.includes(strategy) && p.bidAmount) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["bidAmount"],
+      message: `${strategy} must not set a bidAmount \u2014 Meta rejects one (it bids automatically)`
+    });
+  }
+  if (strategy === "COST_CAP" && p.billing_event && p.billing_event !== "IMPRESSIONS") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["billing_event"],
+      message: "COST_CAP requires billing_event IMPRESSIONS"
+    });
+  }
+  if (strategy === "LOWEST_COST_WITH_MIN_ROAS" && p.optimization_goal && p.optimization_goal !== "VALUE") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["bid_strategy"],
+      message: "LOWEST_COST_WITH_MIN_ROAS requires optimization_goal VALUE"
+    });
+  }
+}
 function validateAdSetBudgetAndBid(p, ctx) {
   if (p.dailyBudget && p.lifetimeBudget) {
     ctx.addIssue({ code: "custom", path: ["dailyBudget"], message: "set only one of dailyBudget or lifetimeBudget" });
@@ -11575,15 +11700,74 @@ function validateAdSetBudgetAndBid(p, ctx) {
   if (p.lifetimeBudget && !p.end_time) {
     ctx.addIssue({ code: "custom", path: ["end_time"], message: "lifetimeBudget ad sets need an end_time" });
   }
-  if (p.bid_strategy && BID_STRATEGIES_REQUIRING_AMOUNT.includes(p.bid_strategy) && !p.bidAmount) {
-    ctx.addIssue({ code: "custom", path: ["bidAmount"], message: `${p.bid_strategy} requires a bidAmount` });
-  }
+  validateBidStrategy(p, ctx);
   if (p.end_time && p.start_time && p.end_time <= p.start_time) {
     ctx.addIssue({ code: "custom", path: ["end_time"], message: "end_time must be after start_time" });
   }
 }
+function validateAdSetPromotedObject(p, ctx) {
+  const goal = p.optimization_goal;
+  if (!goal) {
+    return;
+  }
+  const po = p.promoted_object;
+  if (OPTIMIZATION_GOALS_REQUIRING_PAGE.includes(goal) && !po?.page_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["promoted_object", "page_id"],
+      message: `optimization_goal ${goal} needs promoted_object.page_id \u2014 pass --page-id with the Facebook Page the leads/likes belong to`
+    });
+  }
+  if (OPTIMIZATION_GOALS_REQUIRING_PIXEL.includes(goal) && !po?.pixel_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["promoted_object", "pixel_id"],
+      message: `optimization_goal ${goal} needs promoted_object.pixel_id \u2014 pass --pixel-id with the conversion pixel`
+    });
+  }
+  if (OPTIMIZATION_GOALS_REQUIRING_CONVERSION_SOURCE.includes(goal) && !po?.pixel_id && !po?.application_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["promoted_object", "pixel_id"],
+      message: `optimization_goal ${goal} needs a conversion source \u2014 pass promoted_object.pixel_id (web value optimization) or promoted_object.application_id (app value optimization)`
+    });
+  }
+  if ((OPTIMIZATION_GOALS_REQUIRING_PIXEL.includes(goal) || OPTIMIZATION_GOALS_REQUIRING_CONVERSION_SOURCE.includes(goal)) && !po?.custom_event_type) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["promoted_object", "custom_event_type"],
+      message: `optimization_goal ${goal} needs promoted_object.custom_event_type \u2014 pass --custom-event-type (e.g. PURCHASE, LEAD)`
+    });
+  }
+  if (OPTIMIZATION_GOALS_REQUIRING_APP.includes(goal) && !po?.application_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["promoted_object", "application_id"],
+      message: `optimization_goal ${goal} needs promoted_object.application_id`
+    });
+  }
+}
+function validateAdvantageAudience(p, ctx) {
+  const t = p.targeting;
+  if (t && targetingHardLimitsDemographics(t) && advantageAudienceSetting(t) === 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["targeting", "targeting_automation", "advantage_audience"],
+      message: "Advantage+ Audience (advantage_audience: 1) treats age and gender as suggestions, so a hard age/gender limit is rejected \u2014 set advantage_audience: 0 to enforce the limit, or drop the age_max/age_min/gender restriction"
+    });
+  }
+}
 var adSetCreateSchema = z14.object(adSetFields).superRefine((p, ctx) => {
   validateAdSetBudgetAndBid(p, ctx);
+  validateAdSetPromotedObject(p, ctx);
+  validateAdvantageAudience(p, ctx);
+  if (!targetingHasGeoOrAudience(p.targeting)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["targeting", "geo_locations"],
+      message: 'targeting needs a location \u2014 set targeting.geo_locations (e.g. countries: ["US"]) or include a custom audience; Meta rejects an ad set with no geo'
+    });
+  }
 });
 var adSetUpdateSchema = z14.object({
   name: adSetFields.name.optional(),
@@ -11598,12 +11782,18 @@ var adSetUpdateSchema = z14.object({
   attribution_spec: attributionSpecSchema.optional(),
   start_time: z14.number().int().positive().optional(),
   end_time: z14.number().int().positive().optional(),
-  targeting: metaTargetingSchema.optional()
+  targeting: metaTargetingSchema.optional(),
+  dsa_beneficiary: z14.string().min(1).max(100).optional(),
+  dsa_payor: z14.string().min(1).max(100).optional()
 }).superRefine((p, ctx) => {
   if (!Object.values(p).some((val) => val !== void 0)) {
     ctx.addIssue({ code: "custom", message: "update needs at least one field" });
   }
   validateAdSetBudgetAndBid(p, ctx);
+  if (p.optimization_goal) {
+    validateAdSetPromotedObject(p, ctx);
+  }
+  validateAdvantageAudience(p, ctx);
 });
 var messageSchema = z14.string().min(1).max(META_LIMITS.creative.messageHardMax);
 var headlineSchema2 = z14.string().min(1).max(META_LIMITS.creative.headlineMax);
@@ -12191,7 +12381,10 @@ var adSetWriteArgs = {
   end: { type: "string", description: "End time" },
   "targeting-file": { type: "string", description: "JSON file with the full Meta targeting spec" },
   "promoted-object-file": { type: "string", description: "JSON file with the promoted_object" },
-  "page-id": { type: "string", description: "promoted_object.page_id shortcut" },
+  "page-id": {
+    type: "string",
+    description: "promoted_object.page_id shortcut (required for LEAD_GENERATION / QUALITY_LEAD / PAGE_LIKES goals)"
+  },
   "pixel-id": { type: "string", description: "promoted_object.pixel_id shortcut" },
   "custom-event-type": { type: "string", description: "promoted_object.custom_event_type (PURCHASE|LEAD|\u2026)" },
   file: { type: "string", description: "JSON file with the full payload; flags override" }
@@ -12201,6 +12394,7 @@ var adSetsCreateCommand = defineCommand54({
     name: "create",
     description: `Stage a new ad set. ${STAGED_NOTE2}
 Chain to a campaign with --campaign (real id or meta_temp_* ref).
+Lead-form goals (LEAD_GENERATION, QUALITY_LEAD) and PAGE_LIKES need --page-id (the Facebook Page the leads/likes belong to).
 Example: baker ads meta adsets create --campaign meta_temp_ab12 --name "US 25-54" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --daily-budget 50 --targeting-file t.json`
   },
   args: { campaign: { type: "string", description: "Parent campaign id or meta_temp_* ref" }, ...adSetWriteArgs },
@@ -12214,6 +12408,7 @@ var adSetsUpdateCommand = defineCommand54({
   meta: {
     name: "update",
     description: `Stage changes to an ad set. ${STAGED_NOTE2}
+Switching --optimization-goal to a lead-form goal (LEAD_GENERATION, QUALITY_LEAD) or PAGE_LIKES needs --page-id in the same change.
 Example: baker ads meta adsets update 6123 --daily-budget 80`
   },
   args: { id: { type: "positional", description: "Ad set id or meta_temp_* ref", required: true }, ...adSetWriteArgs },
@@ -13377,7 +13572,8 @@ Performance (the workhorse):
 
 Audit & review:
   baker ads meta activities --account-id act_123 --days 14
-  baker ads meta preview --creative-id 9988 --ad-format MOBILE_FEED_STANDARD --out-file /tmp/p.html`
+  baker ads meta preview --creative-id 9988 --ad-format MOBILE_FEED_STANDARD --out-file /tmp/p.html
+Full guide: __tooling__/docs/tools/baker/ads-meta.md`
   },
   subCommands: {
     accounts: accountsCommand3,
@@ -14841,7 +15037,8 @@ Examples:
     --start-time 2026-04-01T00:00:00Z --end-time 2026-05-01T00:00:00Z \\
     --metric-groups ENGAGEMENT,BILLING --segmentation-type LOCATIONS
 
-The CLI auto-detects --account-id when exactly one X Ads account is connected, or via BAKER_X_ADS_ACCOUNT_ID.`
+The CLI auto-detects --account-id when exactly one X Ads account is connected, or via BAKER_X_ADS_ACCOUNT_ID.
+Full guide: __tooling__/docs/tools/baker/ads-x.md`
   },
   subCommands: {
     accounts: accountsCommand4,
@@ -14879,7 +15076,8 @@ Examples:
   baker ads meta insights --object act_123 --level ad --date-preset last_7d --fields impressions,spend,ctr
   baker ads linkedin accounts
   baker ads x accounts
-  baker ads x stats sync --preset campaign-engagement-7d --entity-ids abc,def`
+  baker ads x stats sync --preset campaign-engagement-7d --entity-ids abc,def
+Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedin|x)`
   },
   subCommands: {
     google: googleCommand,
@@ -21576,7 +21774,8 @@ Subcommands:
   baker canvas catalog                \u2014 print the agent-facing node + composition catalog (JSON Schema)
   baker canvas inspect <run_id>       \u2014 one-page summary of a completed run
   baker canvas scaffold-video <video>                \u2014 turn a reference video into a runnable reproduction canvas (deconstruct + recurring-element detection)
-  baker canvas scaffold-static-ad <image>            \u2014 turn a source image into a runnable static-ad canvas (describe + element detection)`
+  baker canvas scaffold-static-ad <image>            \u2014 turn a source image into a runnable static-ad canvas (describe + element detection)
+Full guide: __tooling__/docs/tools/baker/canvas.md`
   },
   subCommands: {
     run: runCommand,
@@ -21813,7 +22012,8 @@ var diffCommand = defineCommand96({
 var chatsCommand = defineCommand96({
   meta: {
     name: "chats",
-    description: "Inspect other Sessions on this account (read-only): list them, view what they produced, read their conversation, and see their real file changes \u2014 so you can reuse past work for a new goal."
+    description: `Inspect other Sessions on this account (read-only): list them, view what they produced, read their conversation, and see their real file changes \u2014 so you can reuse past work for a new goal.
+Full guide: __tooling__/docs/tools/baker/chats.md`
   },
   subCommands: {
     list: listCommand5,
@@ -22037,7 +22237,8 @@ var creativesCommand3 = defineCommand98({
 Static creative handoff:
   baker creatives publish ./canvas/run/final.png --title "Spring Offer Static Ad"
 
-Publishing uploads the image to the Company image library, applies the official creative tag, and returns an image reference for chat previews.`
+Publishing uploads the image to the Company image library, applies the official creative tag, and returns an image reference for chat previews.
+Full guide: __tooling__/docs/tools/baker/creatives.md`
   },
   subCommands: {
     publish: publishCommand
@@ -22245,7 +22446,8 @@ This command is READ-ONLY and never reveals secret values. Author a Form's struc
 Examples:
   baker flows list            # every Form + how many confidential fields still need setup
   baker flows show contact    # one Form's confidential fields and their status
-  baker flows show contact --full`
+  baker flows show contact --full
+Full guide: __tooling__/docs/tools/baker/flows.md`
   },
   subCommands: {
     list: listCommand6,
@@ -22654,7 +22856,8 @@ Examples:
   baker ga4 audit                                                    \u2014 full property health check
   baker ga4 query --preset tracking-health                           \u2014 compare GA4 vs GAds data
   baker ga4 query --preset lp-performance --days 14                  \u2014 landing page UX audit
-  baker ga4 query --dimensions "date" --metrics "sessions" --days 7  \u2014 free-form query`
+  baker ga4 query --dimensions "date" --metrics "sessions" --days 7  \u2014 free-form query
+Full guide: __tooling__/docs/tools/baker/ga4.md`
   },
   subCommands: {
     properties: propertiesCommand,
@@ -23063,7 +23266,8 @@ Examples:
   baker gsc query --preset cannibalization                          \u2014 find PPC-SEO overlap
   baker gsc query --preset brand-halo --brand "Acme" --days 90      \u2014 brand search trends
   baker gsc query --dimensions "query,page" --days 28               \u2014 free-form query
-  baker gsc sitemaps                                                \u2014 check sitemap health`
+  baker gsc sitemaps                                                \u2014 check sitemap health
+Full guide: __tooling__/docs/tools/baker/gsc.md`
   },
   subCommands: {
     sites: sitesCommand,
@@ -23177,7 +23381,8 @@ var listCommand7 = defineCommand108({
 var historyCommand = defineCommand108({
   meta: {
     name: "history",
-    description: "Unified account history (audit log): what changed, who did it, and when."
+    description: `Unified account history (audit log): what changed, who did it, and when.
+Full guide: __tooling__/docs/tools/baker/history.md`
   },
   subCommands: { list: listCommand7 }
 });
@@ -25775,7 +25980,8 @@ Taxonomy:
   baker images tags                                    List available image tag names (defaults + company custom tags)
 
 Paid transforms (run on the Convex backend, cost-tracked):
-  baker images upscale <imageId>                       Real-ESRGAN super-resolution ($0.05/image, waits for completion)`
+  baker images upscale <imageId>                       Real-ESRGAN super-resolution ($0.05/image, waits for completion)
+Full guide: __tooling__/docs/tools/baker/images.md`
   },
   subCommands: {
     get: getCommand2,
@@ -25946,7 +26152,8 @@ Start here:
 Examples:
   baker mcp add --name weather --url https://mcp.example.com/mcp
   baker mcp add --name acme --url https://acme.dev/mcp --header "Authorization: Bearer sk-\u2026"
-  baker mcp remove --name weather`
+  baker mcp remove --name weather
+Full guide: __tooling__/docs/tools/baker/mcp.md`
   },
   subCommands: {
     list: listCommand8,
@@ -26820,7 +27027,8 @@ Examples:
   baker research advertisers "running shoes"
   baker research intent "buy running shoes,best running shoes 2026"
   baker research keywords-for-site "competitor.com"
-  baker research keyword-gap "them.com" "us.com"`
+  baker research keyword-gap "them.com" "us.com"
+Full guide: __tooling__/docs/tools/baker/research.md`
   },
   subCommands: {
     web: webCommand,
@@ -27267,7 +27475,8 @@ Examples:
   baker scheduled-actions create --name "Weekly report" --description "Prepare weekly report" --cron "0 9 * * MON"
   baker scheduled-actions update <id-or-temp_sched_id> --enabled false
   baker scheduled-actions delete <id-or-temp_sched_id>
-  baker scheduled-actions trigger <id>`
+  baker scheduled-actions trigger <id>
+Full guide: __tooling__/docs/tools/baker/scheduled-actions.md`
   },
   subCommands: {
     list: listCommand9,
@@ -27303,11 +27512,17 @@ var schemaCommand = defineCommand152({
     const schema = getSchema(commandName);
     if (!schema) {
       const available = listSchemas();
+      const segments = commandName.split(".");
+      const family = segments[0] === "ads" && segments[1] ? `ads-${segments[1]}` : segments[0];
       writeJson({
         ok: false,
         error: {
           code: "NOT_FOUND",
-          message: `Schema "${commandName}" not found. Available: ${available.join(", ")}`
+          message: `Schema "${commandName}" not found. Available: ${available.join(", ")}`,
+          fix: {
+            action: `Run the command with --help for exact args, and read __tooling__/docs/tools/baker/${family}.md`,
+            explanation: "Not every command registers a schema; --help and the family doc are the ground truth for those."
+          }
         }
       });
       process.exit(1);
@@ -27424,7 +27639,8 @@ Refs: \`baker tags list\` prints each tag's ref \u2014 a real tag id, or tag_tem
 
 Examples:
   baker tags list       # production + staged, full readable config + secret status
-  baker tags draft      # review the staged changes awaiting publish`
+  baker tags draft      # review the staged changes awaiting publish
+Full guide: __tooling__/docs/tools/baker/tags.md`
   },
   subCommands: {
     list: listCommand10,
@@ -27707,7 +27923,8 @@ Examples:
   baker testimonials search "value for money" --rating-min 4
   baker testimonials get <testimonial-id>
   baker testimonials list --source google --sentiment positive
-  baker testimonials tags`
+  baker testimonials tags
+Full guide: __tooling__/docs/tools/baker/testimonials.md`
   },
   subCommands: {
     get: getCommand4,
@@ -27982,7 +28199,8 @@ Examples:
   baker videos get <video-id>
   baker videos upload ./demo.mp4
   baker videos delete <video-id> --dry-run
-  baker videos tags`
+  baker videos tags
+Full guide: __tooling__/docs/tools/baker/videos.md`
   },
   subCommands: {
     get: getCommand5,
@@ -27994,7 +28212,7 @@ Examples:
 });
 
 // src/commands/winning-ads/index.ts
-import { defineCommand as defineCommand173 } from "citty";
+import { defineCommand as defineCommand174 } from "citty";
 
 // src/commands/winning-ads/advertisers.ts
 import { defineCommand as defineCommand163 } from "citty";
@@ -28388,8 +28606,116 @@ var followCommand = defineCommand166({
   }
 });
 
-// src/commands/winning-ads/following.ts
+// src/commands/winning-ads/follow-competitors.ts
 import { defineCommand as defineCommand167 } from "citty";
+var PLATFORMS2 = ["meta", "linkedin"];
+var BATCH_TIMEOUT_MS = 3e5;
+function buildFollowBatchBody(input) {
+  const seen = /* @__PURE__ */ new Set();
+  const inputs = [];
+  for (const domain of splitList(input.domains)) {
+    const key = domain.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    inputs.push(domain);
+  }
+  return { inputs, platform: input.platform ?? "meta" };
+}
+registerSchema({
+  command: "winning-ads.follow-competitors",
+  description: "Follow MANY brands at once \u2014 the fast way to add every competitor to your library. Pass a comma-separated list of domains (best \u2014 each resolves both Meta + LinkedIn, every country). One brand failing never blocks the others: the response reports per-brand status (following/added/ambiguous/failed) plus rollup counts. Ideal right after a competitor scan.",
+  args: {
+    domains: {
+      type: "string",
+      description: `Comma-separated domains (best), profile/ad-library URLs, or brand names \u2014 up to ${FOLLOW_BATCH_MAX}. e.g. "deel.com,notion.so,hubspot.com"`,
+      required: true
+    },
+    platform: {
+      type: "string",
+      description: "meta|linkedin \u2014 how to read each input, not a tracking limit (default meta). Domains resolve both.",
+      required: false,
+      default: "meta"
+    }
+  }
+});
+var followCompetitorsCommand = defineCommand167({
+  meta: {
+    name: "follow-competitors",
+    description: 'Follow many brands at once by domain \u2014 add every competitor in one call. Example: baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"'
+  },
+  args: {
+    domains: {
+      type: "positional",
+      description: "Comma-separated domains (best), URLs, or brand names",
+      required: true
+    },
+    platform: {
+      type: "string",
+      description: "meta|linkedin \u2014 how to read each input, not a tracking limit (default meta).",
+      required: false,
+      default: "meta"
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const platform = String(args.platform ?? "meta");
+      if (!PLATFORMS2.includes(platform)) {
+        writeJson({
+          ok: false,
+          error: { code: "VALIDATION_ERROR", message: "--platform must be one of: meta, linkedin" }
+        });
+        process.exit(1);
+      }
+      const body = buildFollowBatchBody({ domains: String(args.domains ?? ""), platform });
+      if (body.inputs.length === 0) {
+        writeJson({
+          ok: false,
+          error: { code: "VALIDATION_ERROR", message: "Pass at least one domain in --domains." }
+        });
+        process.exit(1);
+      }
+      if (body.inputs.length > FOLLOW_BATCH_MAX) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `Too many brands (${body.inputs.length}). Follow at most ${FOLLOW_BATCH_MAX} per call.`
+          }
+        });
+        process.exit(1);
+      }
+      const data = await apiPost("/api/ad-library/follow-batch", body, {
+        timeoutMs: BATCH_TIMEOUT_MS
+      });
+      const hints = [];
+      if (data.failed_count > 0) {
+        const failed = data.results.filter((r) => r.status === "failed").map((r) => r.input);
+        hints.push(
+          `${data.failed_count} brand(s) couldn't be added: ${failed.join(", ")}. Retry each with its website or Facebook/LinkedIn URL via \`baker winning-ads follow\`.`
+        );
+      }
+      if (data.ambiguous_count > 0) {
+        const ambiguous = data.results.filter((r) => r.status === "ambiguous").map((r) => r.input);
+        hints.push(
+          `${data.ambiguous_count} brand(s) matched multiple advertisers: ${ambiguous.join(", ")}. Re-run \`baker winning-ads follow\` with an exact domain/URL to pick one.`
+        );
+      }
+      if (data.added_count > 0) {
+        hints.push(
+          "Newly added brands are ingesting now \u2014 their winners fill in over the next few minutes. Check `baker winning-ads following` or `baker winning-ads feed`."
+        );
+      }
+      writeJson({ ok: true, data, hints: hints.length > 0 ? hints : void 0 });
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+
+// src/commands/winning-ads/following.ts
+import { defineCommand as defineCommand168 } from "citty";
 registerSchema({
   command: "winning-ads.following",
   description: "List the brands you follow in your ad-dna library, with each one's status (ready vs still adding) and cached ad counts.",
@@ -28422,7 +28748,7 @@ function followingNormalizer(record, full) {
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };
 }
-var followingCommand = defineCommand167({
+var followingCommand = defineCommand168({
   meta: {
     name: "following",
     description: "List brands you follow, with status (ready / adding\u2026) and cached counts. Example: baker winning-ads following --output md"
@@ -28457,7 +28783,7 @@ var followingCommand = defineCommand167({
 });
 
 // src/commands/winning-ads/patterns.ts
-import { defineCommand as defineCommand168 } from "citty";
+import { defineCommand as defineCommand169 } from "citty";
 registerSchema({
   command: "winning-ads.patterns",
   description: "Mine what separates two cohorts of ads: pass a comma-list of winning ad ids (--winners) and a comma-list of weaker ad ids (--duds). Returns the discriminating DNA fields.",
@@ -28496,7 +28822,7 @@ function discriminatorRow(record) {
     top_values_duds: Array.isArray(record.top_values_b) ? record.top_values_b.join(", ") : ""
   };
 }
-var patternsCommand = defineCommand168({
+var patternsCommand = defineCommand169({
   meta: {
     name: "patterns",
     description: "Discover what separates winning ads from weak ones. Example: baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --output md"
@@ -28552,7 +28878,7 @@ var patternsCommand = defineCommand168({
 });
 
 // src/commands/winning-ads/search.ts
-import { defineCommand as defineCommand169 } from "citty";
+import { defineCommand as defineCommand170 } from "citty";
 registerSchema({
   command: "winning-ads.search",
   description: "Search the ad-dna corpus of scored winning ads. Returns a lean shortlist (advertiser, summary, scores, media_url) to pick a reference to reproduce.",
@@ -28660,7 +28986,7 @@ function buildSearchBody(args) {
   }
   return body;
 }
-var searchCommand4 = defineCommand169({
+var searchCommand4 = defineCommand170({
   meta: {
     name: "search",
     description: "Search winning reference ads. Example: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --winner-category winner --exclude-advertiser adv_123 --output md"
@@ -28775,7 +29101,7 @@ var searchCommand4 = defineCommand169({
 });
 
 // src/commands/winning-ads/seeds.ts
-import { defineCommand as defineCommand170 } from "citty";
+import { defineCommand as defineCommand171 } from "citty";
 function leanRow(r) {
   return {
     key: r.key,
@@ -28803,7 +29129,7 @@ function makeSeedCommand(opts) {
       limit: { type: "number", description: "Max keys 1-100 (default 20)", required: false, default: 20 }
     }
   });
-  return defineCommand170({
+  return defineCommand171({
     meta: { name: opts.name, description: opts.description },
     args: {
       platform: { type: "string", description: "Single platform to segment on", required: false },
@@ -28852,7 +29178,7 @@ var formatsCommand = makeSeedCommand({
 });
 
 // src/commands/winning-ads/unfollow.ts
-import { defineCommand as defineCommand171 } from "citty";
+import { defineCommand as defineCommand172 } from "citty";
 registerSchema({
   command: "winning-ads.unfollow",
   description: "Stop following a brand \u2014 removes it from your ad-dna library by advertiser id.",
@@ -28860,7 +29186,7 @@ registerSchema({
     advertiser: { type: "string", description: "Advertiser id to unfollow", required: true }
   }
 });
-var unfollowCommand = defineCommand171({
+var unfollowCommand = defineCommand172({
   meta: {
     name: "unfollow",
     description: "Stop following a brand by advertiser id. Example: baker winning-ads unfollow adv_123"
@@ -28881,7 +29207,7 @@ var unfollowCommand = defineCommand171({
 });
 
 // src/commands/winning-ads/winners.ts
-import { defineCommand as defineCommand172 } from "citty";
+import { defineCommand as defineCommand173 } from "citty";
 registerSchema({
   command: "winning-ads.winners",
   description: "Top winning ads for one advertiser id (from `advertisers` or `following`). Returns lean winner cards; add --full for DNA + longevity.",
@@ -28891,7 +29217,7 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false }
   }
 });
-var winnersCommand = defineCommand172({
+var winnersCommand = defineCommand173({
   meta: {
     name: "winners",
     description: "Top winning ads for a specific advertiser id. Example: baker winning-ads winners adv_123 --top 15 --output md"
@@ -28941,7 +29267,7 @@ var winnersCommand = defineCommand172({
 });
 
 // src/commands/winning-ads/index.ts
-var winningAdsCommand = defineCommand173({
+var winningAdsCommand = defineCommand174({
   meta: {
     name: "winning-ads",
     description: `Search the ad-dna corpus of scored "winning" ads for reference creatives to reproduce, and manage the brands your library tracks. Proxied through the Baker backend (BAKER_API_KEY) \u2014 no separate token needed.
@@ -28952,6 +29278,7 @@ Subcommands:
   baker winning-ads search "<free text>"      \u2014 semantic search across the corpus; lean shortlist (advertiser, summary, scores, media_url)
   baker winning-ads advertisers "<brand>"     \u2014 list corpus brands \u2192 advertiser ids (for --exclude-advertiser / --advertiser-id)
   baker winning-ads follow "<domain|url|brand>" --platform meta|linkedin   \u2014 add a brand's ads to your library
+  baker winning-ads follow-competitors "<domain,domain,...>"   \u2014 add MANY brands at once (every competitor by domain)
   baker winning-ads following                 \u2014 list brands you follow (status + counts)
   baker winning-ads feed                      \u2014 winners across EVERY brand you follow; trim with --advertiser
   baker winning-ads winners <advertiser>      \u2014 top winners for one advertiser id
@@ -28966,17 +29293,20 @@ Examples:
   baker winning-ads search "B2B SaaS before/after AI automation" --platform meta --format static --output md
   baker winning-ads advertisers "Acme" --output md
   baker winning-ads follow "deel.com" --platform meta
+  baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"
   baker winning-ads feed --per-advertiser 5 --output md
   baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
   baker winning-ads winners adv_123 --top 15 --output md
   baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
   baker winning-ads search "fintech onboarding" --hook-archetype callout --winner-category winner --output md
-  baker winning-ads patterns --winners a_1,a_2 --duds a_9,a_8 --output md`
+  baker winning-ads patterns --winners a_1,a_2 --duds a_9,a_8 --output md
+Full guide: __tooling__/docs/tools/baker/winning-ads.md`
   },
   subCommands: {
     search: searchCommand4,
     advertisers: advertisersCommand2,
     follow: followCommand,
+    "follow-competitors": followCompetitorsCommand,
     following: followingCommand,
     feed: feedCommand,
     winners: winnersCommand,
@@ -29006,7 +29336,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand174({
+var main = defineCommand175({
   meta: {
     name: "baker",
     version: getCliVersion(),