@koda-sl/baker-cli 0.149.0-dev.7b64ca6b5 → 0.150.0-dev.04484bc24

package/dist/cli.js

@@ -24,6 +24,7 @@ import {
   imageProfileFor,
   isPersistedAssetRef,
   looksLikeHttpUrl,
+  nearestSupportedAspectRatio,
   parseRefExpr,
   platformFormats,
   requireCredentialsFromEnv,
@@ -31,10 +32,11 @@ import {
   sha256Hex,
   spineInputFlags,
   spineInputOps,
+  supportsParam,
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-ZBRVPPJP.js";
+} from "./chunk-JBDSJZBZ.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -1295,6 +1297,15 @@ var LINKEDIN_LIMITS = {
   campaign: {
     nameMax: 255
   },
+  /**
+   * LinkedIn documents no ceiling on URL tracking parameters; these are our own
+   * guards against a payload that would build an unusable landing URL.
+   */
+  trackingParams: {
+    keyMax: 100,
+    valueMax: 500,
+    parametersMax: 20
+  },
   creative: {
     commentarySoftMax: 600,
     // feed truncates with "…see more" beyond this
@@ -1433,6 +1444,17 @@ var CONVERSION_TYPES = [
 ];
 var CONVERSION_METHODS = ["INSIGHT_TAG", "CONVERSIONS_API"];
 var ATTRIBUTION_TYPES = ["LAST_TOUCH_BY_CAMPAIGN", "LAST_TOUCH_BY_CONVERSION"];
+var TRACKING_PARAM_DYNAMIC_VALUES = [
+  "ACCOUNT_ID",
+  "ACCOUNT_NAME",
+  "CAMPAIGN_GROUP_ID",
+  "CAMPAIGN_GROUP_NAME",
+  "CAMPAIGN_ID",
+  "CAMPAIGN_NAME",
+  "CREATIVE_ID",
+  "CREATIVE_NAME"
+];
+var TRACKING_PARAM_KEY_REGEX = /^[A-Za-z0-9_.-]+$/;
 var CURRENCY_MINIMUMS = {
   USD: { dailyBudgetMin: 10, unitCostMin: 2 },
   EUR: { dailyBudgetMin: 10, unitCostMin: 2 },
@@ -1590,6 +1612,35 @@ var campaignUpdateSchema = z3.object({
   }
   validateCampaignBudgets(p, ctx, { requireBudget: false });
 });
+var trackingParamKeySchema = z3.string().min(1).max(LINKEDIN_LIMITS.trackingParams.keyMax).regex(TRACKING_PARAM_KEY_REGEX, "tracking parameter keys may only use letters, digits, _ . and -");
+var trackingParamsSetSchema = z3.object({
+  dynamicValueParameters: z3.record(trackingParamKeySchema, z3.enum(TRACKING_PARAM_DYNAMIC_VALUES)).optional(),
+  customValueParameters: z3.record(trackingParamKeySchema, z3.string().min(1).max(LINKEDIN_LIMITS.trackingParams.valueMax)).optional()
+}).superRefine((p, ctx) => {
+  if (!p.dynamicValueParameters && !p.customValueParameters) {
+    ctx.addIssue({
+      code: "custom",
+      message: "set at least one parameter \u2014 pass both maps as {} to clear the ad set's tracking parameters instead"
+    });
+  }
+  const both = Object.keys(p.dynamicValueParameters ?? {}).filter(
+    (key) => p.customValueParameters?.[key] !== void 0
+  );
+  if (both.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["customValueParameters"],
+      message: `${both.join(", ")} is set as both a dynamic and a fixed parameter \u2014 LinkedIn appends each key once, so keep only one`
+    });
+  }
+  const count = Object.keys(p.dynamicValueParameters ?? {}).length + Object.keys(p.customValueParameters ?? {}).length;
+  if (count > LINKEDIN_LIMITS.trackingParams.parametersMax) {
+    ctx.addIssue({
+      code: "custom",
+      message: `${count} parameters \u2014 keep it under ${LINKEDIN_LIMITS.trackingParams.parametersMax}`
+    });
+  }
+});
 var commentarySchema = z3.string().min(1).max(LINKEDIN_LIMITS.creative.commentaryHardMax);
 var headlineSchema = z3.string().min(1).max(LINKEDIN_LIMITS.creative.headlineMax);
 var httpsUrlSchema = z3.string().url().refine((u) => u.startsWith("https://"), "landing pages must be https");
@@ -1968,6 +2019,7 @@ var LINKEDIN_DRAFT_OP_KINDS = [
   "campaignGroup.update",
   "campaign.create",
   "campaign.update",
+  "trackingParams.set",
   "creative.create",
   "creative.update",
   "audience.create",
@@ -1991,6 +2043,7 @@ var linkedinDraftOpInputSchema = z3.discriminatedUnion("kind", [
   updateOp("campaignGroup.update", campaignGroupUpdateSchema),
   createOp("campaign.create", campaignCreateSchema),
   updateOp("campaign.update", campaignUpdateSchema),
+  updateOp("trackingParams.set", trackingParamsSetSchema),
   createOp("creative.create", creativeCreateSchema),
   updateOp("creative.update", creativeUpdateSchema),
   createOp("audience.create", audienceCreateSchema),
@@ -2544,13 +2597,6 @@ var imageDocSchema = z8.object({
   width: z8.number().optional(),
   height: z8.number().optional(),
   aspectRatio: z8.number().optional(),
-  /** Any non-opaque pixel in the decoded image. */
-  hasAlpha: z8.boolean().optional(),
-  /** Opaque pixels ÷ their bounding-box area, 0..1. Feed with `aspectRatio`
-   * into `classifyLogoShape` to tell a brand wordmark from an app-icon plate
-   * before placing it — the library keeps assets forever, so a bad ingest is
-   * otherwise indistinguishable from a good one months later. */
-  solidity: z8.number().optional(),
   dominantColor: z8.string().optional(),
   imagePalette: z8.array(z8.string()).optional(),
   thumbhashDataUri: z8.string().optional(),
@@ -2633,13 +2679,6 @@ var imageSearchResultSchema = z8.object({
   width: z8.number().optional(),
   height: z8.number().optional(),
   aspectRatio: z8.number().optional(),
-  /** Any non-opaque pixel in the decoded image. */
-  hasAlpha: z8.boolean().optional(),
-  /** Opaque pixels ÷ their bounding-box area, 0..1. Feed with `aspectRatio`
-   * into `classifyLogoShape` to tell a brand wordmark from an app-icon plate
-   * before placing it — the library keeps assets forever, so a bad ingest is
-   * otherwise indistinguishable from a good one months later. */
-  solidity: z8.number().optional(),
   dominantColor: z8.string().optional(),
   imagePalette: z8.array(z8.string()).optional(),
   source: z8.string(),
@@ -2721,8 +2760,9 @@ var rgbTriple = z8.tuple([
   z8.number().int().min(0).max(255)
 ]);
 var imageGenerateModelSchema = z8.enum([
+  "openai/gpt-image-2",
+  // Legacy — see the registry entry; kept so pre-switch canvases still run.
   "openai/gpt-5.4-image-2",
-  "google/gemini-3.5-flash",
   "google/gemini-3.1-flash-image-preview",
   "google/gemini-3-pro-image-preview",
   "recraft/recraft-v4.1-pro-vector"
@@ -2763,13 +2803,10 @@ var imagesLogoRequestSchema = z8.object({
   descriptionContext: z8.string().optional()
 });
 var imagesLogoResponseSchema = providerHitsResponseSchema();
-var hexColorSchema = z8.string().transform((value) => value.trim().replace(/^%23/i, "#")).refine((value) => /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value), {
-  message: "Expected a hex color like #D7FFA4"
-}).transform((value) => value.startsWith("#") ? value : `#${value}`);
 var imagesIconRequestSchema = z8.object({
   name: z8.string().min(1),
   set: z8.string().optional(),
-  color: hexColorSchema.optional(),
+  color: z8.string().optional(),
   width: z8.coerce.number().int().positive().optional(),
   autoIngest: z8.coerce.number().int().min(0).max(20).optional(),
   descriptionContext: z8.string().optional()
@@ -2819,19 +2856,6 @@ var imagesIngestResponseSchema = z8.object({
   contentHash: z8.string()
 });
 
-// ../api/src/logoShape.ts
-var PLATE_SOLIDITY_THRESHOLD = 0.6;
-var WORDMARK_MIN_ASPECT = 1.8;
-function classifyLogoShape({
-  aspectRatio: aspectRatio2,
-  hasAlpha,
-  solidity
-}) {
-  if (solidity === void 0 || aspectRatio2 === void 0) return "unknown";
-  if (solidity >= PLATE_SOLIDITY_THRESHOLD || hasAlpha === false) return "plated-icon";
-  return aspectRatio2 >= WORDMARK_MIN_ASPECT ? "wordmark" : "symbol";
-}
-
 // ../api/src/tags.ts
 import { z as z9 } from "zod";
 var TAG_TYPES = [
@@ -5425,17 +5449,27 @@ var googleDraftStageRequestSchema = z13.object({
   chatId: z13.string(),
   op: googleDraftOpInputSchema
 });
-var googleDraftStageResponseSchema = z13.object({
-  staged: z13.literal(true),
-  ref: z13.string(),
-  kind: googleDraftOpKindSchema,
-  mode: googleWriteModeSchema,
-  dependsOn: z13.array(z13.string()),
-  summary: z13.string(),
-  warnings: z13.array(z13.string()),
-  /** True when the op amended an already-staged op in place instead of appending a new one. */
-  amended: z13.boolean().optional()
-});
+var googleDraftStageResponseSchema = z13.discriminatedUnion("staged", [
+  z13.object({
+    staged: z13.literal(true),
+    ref: z13.string(),
+    kind: googleDraftOpKindSchema,
+    mode: googleWriteModeSchema,
+    dependsOn: z13.array(z13.string()),
+    summary: z13.string(),
+    warnings: z13.array(z13.string()),
+    /** True when the op amended an already-staged op in place instead of appending a new one. */
+    amended: z13.boolean().optional()
+  }),
+  z13.object({
+    staged: z13.literal(false),
+    noop: z13.literal(true),
+    kind: googleDraftOpKindSchema,
+    mode: googleWriteModeSchema,
+    summary: z13.string(),
+    reason: z13.string()
+  })
+]);
 var googleDraftAmendRequestSchema = z13.object({
   chatId: z13.string(),
   ref: z13.string(),
@@ -5462,7 +5496,8 @@ var googleDraftStageBatchResponseSchema = z13.object({
       summary: z13.string(),
       warnings: z13.array(z13.string())
     })
-  )
+  ),
+  skipped: z13.array(z13.object({ kind: googleDraftOpKindSchema, summary: z13.string(), reason: z13.string() })).optional()
 });
 var googleDraftOpViewSchema = z13.object({
   ref: z13.string(),
@@ -5721,7 +5756,7 @@ function keywordEntries(args) {
   const seen = /* @__PURE__ */ new Set();
   for (const item of raw) {
     const entry = parseKeywordEntry(item, defaultMatch);
-    const key = `${entry.text}\0${entry.matchType}`;
+    const key = JSON.stringify([entry.text, entry.matchType]);
     if (!seen.has(key)) {
       seen.add(key);
       entries.push(entry);
@@ -5788,6 +5823,9 @@ function handleGoogleError(err) {
   });
   process.exit(1);
 }
+function noopHints(data) {
+  return data.staged ? [] : [`NOT STAGED \u2014 ${data.reason}. Nothing to publish for this change; say so rather than reporting it as done.`];
+}
 async function stageGoogleOp(raw, hints) {
   const preflight = googleDraftOpInputSchema.safeParse(raw);
   if (!preflight.success) {
@@ -5805,7 +5843,8 @@ async function stageGoogleOp(raw, hints) {
   try {
     const chatId = requireChatId();
     const response = await apiPost("/api/ads/google/draft/stage", { chatId, op: preflight.data });
-    writeJsonEnvelope(hints && hints.length > 0 ? { ...response, hints } : response);
+    const allHints = [...noopHints(response.data), ...hints ?? []];
+    writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleGoogleError(err);
   }
@@ -5841,7 +5880,14 @@ async function stageGoogleOps(rawOps, hints) {
   try {
     const chatId = requireChatId();
     const response = await apiPost("/api/ads/google/draft/stage-batch", { chatId, ops });
-    writeJsonEnvelope(hints && hints.length > 0 ? { ...response, hints } : response);
+    const skipped = response.data.skipped ?? [];
+    const allHints = [
+      ...skipped.length > 0 ? [
+        `${skipped.length} of ${ops.length} op(s) NOT STAGED \u2014 already in the requested state: ${skipped.map((s) => s.reason).join("; ")}`
+      ] : [],
+      ...hints ?? []
+    ];
+    writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleGoogleError(err);
   }
@@ -8310,6 +8356,26 @@ registerSchema({
     file: { type: "string", description: "JSON file with fields to change", required: false }
   }
 });
+registerSchema({
+  command: "ads.linkedin.campaigns.url-params",
+  description: "Start here for UTMs: stage the URL tracking parameters on an ad set. LinkedIn appends them to the link of EVERY ad in the ad set, including ads already running, so this is the level to set campaign-wide UTMs at \u2014 editing each ad's landing URL instead risks the same key landing twice. --param takes fixed values (repeatable or &-joined); --dynamic takes a value LinkedIn fills in per ad (ACCOUNT_ID, ACCOUNT_NAME, CAMPAIGN_GROUP_ID, CAMPAIGN_GROUP_NAME, CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, CREATIVE_NAME). Applies on chat publish; message and conversation ads are unaffected.",
+  args: {
+    id: { type: "positional", description: "Ad set (campaign) id or URN", required: true },
+    ...writeAccountArgs,
+    param: {
+      type: "string",
+      description: 'Fixed key=value, repeatable or &-joined \u2014 e.g. "utm_source=linkedin&utm_medium=paid-social"',
+      required: false
+    },
+    dynamic: {
+      type: "string",
+      description: "key=PLACEHOLDER filled in per ad, repeatable \u2014 e.g. utm_campaign=CAMPAIGN_NAME",
+      required: false
+    },
+    clear: { type: "boolean", description: "Remove every tracking parameter from this ad set", required: false },
+    file: { type: "string", description: "JSON payload file; flags override file keys", required: false }
+  }
+});
 var statusSugarArgs = {
   id: { type: "positional", description: "Entity id or URN", required: true },
   ...writeAccountArgs
@@ -9834,6 +9900,88 @@ Example: baker ads linkedin ${entity} ${name} 123456`
     }
   });
 }
+function trackingPairs(value, flag) {
+  const raw = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+  return raw.flatMap(
+    (entry) => String(entry).split("&").filter((pair) => pair.length > 0).map((pair) => {
+      const at = pair.indexOf("=");
+      if (at < 1 || at === pair.length - 1) {
+        failWriteValidation2(`${flag} expects key=value pairs \u2014 got "${pair}"`);
+      }
+      return [pair.slice(0, at).trim(), pair.slice(at + 1).trim()];
+    })
+  );
+}
+function asDynamicValue(value) {
+  const bare = value.replace(/^\{+|\}+$/g, "").toUpperCase();
+  return TRACKING_PARAM_DYNAMIC_VALUES.includes(bare) ? bare : void 0;
+}
+function trackingParamsPayload(args) {
+  if (args.clear) {
+    return { dynamicValueParameters: {}, customValueParameters: {} };
+  }
+  const customValueParameters = {};
+  for (const [key, value] of trackingPairs(args.param, "--param")) {
+    if (asDynamicValue(value)) {
+      failWriteValidation2(
+        `--param ${key}=${value} names a value LinkedIn fills in per ad \u2014 pass it as --dynamic ${key}=${value.replace(/^\{+|\}+$/g, "").toUpperCase()}`
+      );
+    }
+    customValueParameters[key] = value;
+  }
+  const dynamicValueParameters = {};
+  for (const [key, value] of trackingPairs(args.dynamic, "--dynamic")) {
+    const resolved = asDynamicValue(value);
+    if (!resolved) {
+      failWriteValidation2(
+        `--dynamic ${key}=${value} is not a value LinkedIn can fill in \u2014 use one of ${TRACKING_PARAM_DYNAMIC_VALUES.join(", ")}, or pass a fixed value with --param`
+      );
+    }
+    dynamicValueParameters[key] = resolved;
+  }
+  return mergePayload2(loadJsonFileArg2(args.file), {
+    customValueParameters: Object.keys(customValueParameters).length > 0 ? customValueParameters : void 0,
+    dynamicValueParameters: Object.keys(dynamicValueParameters).length > 0 ? dynamicValueParameters : void 0
+  });
+}
+var campaignsUrlParamsCommand = defineCommand37({
+  meta: {
+    name: "url-params",
+    description: `Stage the URL tracking parameters on an ad set \u2014 LinkedIn appends them to the link of EVERY ad in it, including ads already running. ${STAGED_NOTE}
+
+Start here: set UTMs at this level, not per ad. A per-ad landing URL is only for a genuinely different destination \u2014 LinkedIn appends the ad set's parameters on top of whatever the ad's own URL carries, so the same key set in both places lands twice.
+
+Values LinkedIn fills in per ad (--dynamic): ACCOUNT_ID, ACCOUNT_NAME, CAMPAIGN_GROUP_ID, CAMPAIGN_GROUP_NAME, CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, CREATIVE_NAME.
+
+Examples:
+  baker ads linkedin campaigns url-params 123456 --param "utm_source=linkedin&utm_medium=paid-social" --dynamic utm_campaign=CAMPAIGN_NAME --dynamic utm_content=CREATIVE_ID
+  baker ads linkedin campaigns url-params 123456 --param utm_agency=baker
+  baker ads linkedin campaigns url-params 123456 --clear`
+  },
+  args: {
+    id: { type: "positional", description: "Ad set (campaign) id or URN", required: true },
+    ...accountArgs,
+    param: {
+      type: "string",
+      description: 'Fixed key=value, repeatable or &-joined (e.g. --param "utm_source=linkedin&utm_medium=paid")'
+    },
+    dynamic: {
+      type: "string",
+      description: "key=PLACEHOLDER LinkedIn fills in per ad, repeatable (e.g. --dynamic utm_campaign=CAMPAIGN_NAME)"
+    },
+    clear: { type: "boolean", description: "Remove every tracking parameter from this ad set" },
+    file: { type: "string", description: "JSON file with the full payload; flags override file keys" }
+  },
+  run: async ({ args }) => {
+    const accountId = bareAccountId(args);
+    await stageOp({
+      kind: "trackingParams.set",
+      accountId,
+      target: requireTarget2(args, "ad set"),
+      payload: trackingParamsPayload(args)
+    });
+  }
+});
 var campaignsPauseCommand = statusSugarCommand("campaigns", "campaign.update", "pause");
 var campaignsResumeCommand = statusSugarCommand("campaigns", "campaign.update", "resume");
 var campaignsArchiveCommand = statusSugarCommand("campaigns", "campaign.update", "archive");
@@ -10366,7 +10514,8 @@ Examples:
   baker ads linkedin campaigns --account-id 503001492
   baker ads linkedin campaigns --account-id 503001492 --all-statuses --output csv
   baker ads linkedin campaigns update 123456 --daily-budget 100 --currency EUR
-  baker ads linkedin campaigns pause 123456`
+  baker ads linkedin campaigns pause 123456
+  baker ads linkedin campaigns url-params 123456 --param utm_source=linkedin   \u2014 UTMs for every ad in the ad set`
   },
   subCommands: {
     create: campaignsCreateCommand,
@@ -10374,7 +10523,8 @@ Examples:
     pause: campaignsPauseCommand,
     resume: campaignsResumeCommand,
     archive: campaignsArchiveCommand,
-    duplicate: campaignsDuplicateCommand
+    duplicate: campaignsDuplicateCommand,
+    "url-params": campaignsUrlParamsCommand
   },
   args: {
     "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },
@@ -16661,7 +16811,9 @@ function buildFrameRef(edge, url, framePrompt, present2, ctx, nodes) {
   const imageProfile = imageProfileFor(ctx.imageModel);
   const genParams = {
     model: ctx.imageModel,
-    image_size: "2K",
+    // gpt-image-2 derives pixel dimensions from the ratio and has no size knob,
+    // so asking for 2K there is an `unknown_param` at validate.
+    ...supportsParam("image_generate", ctx.imageModel, "image_size") ? { image_size: "2K" } : {},
     // Per-model image defaults (gpt-image: quality=high — OpenRouter forwards it; we do
     // NOT send input_fidelity, which gpt-image-2 forces high automatically).
     ...imageProfile?.paramDefaults ?? {},
@@ -16676,7 +16828,7 @@ function buildFrameRef(edge, url, framePrompt, present2, ctx, nodes) {
       ctx.imageModel
     )
   };
-  if (ctx.genAr) genParams.aspect_ratio = ctx.genAr;
+  if (ctx.genAr) genParams.aspect_ratio = nearestSupportedAspectRatio("image_generate", ctx.imageModel, ctx.genAr);
   const genId = `s${ctx.sceneIndex}${tag}_${edge}`;
   nodes.push({
     id: genId,
@@ -20403,8 +20555,13 @@ function scaffoldStaticAd(input, elementsInput, opts) {
     inputs: { reference, target_blueprint: "$ref:prompt.asset" },
     params: {
       model: opts.genModel,
-      aspect_ratio: baseAspectRatio(blueprint, opts),
-      image_size: "2K",
+      // The hero renders at the closest ratio its model actually accepts; the
+      // placement fan-out below adapts it to the exact platform formats, which
+      // is also how a 4:5 Meta feed ad gets made on a model that has no 4:5.
+      aspect_ratio: nearestSupportedAspectRatio("image_generate", opts.genModel, baseAspectRatio(blueprint, opts)),
+      ...supportsParam("image_generate", opts.genModel, "image_size") ? { image_size: "2K" } : {},
+      // Per-model image defaults (gpt-image: quality=high).
+      ...imageProfileFor(opts.genModel)?.paramDefaults ?? {},
       prompt
     }
   });
@@ -20771,7 +20928,7 @@ function resolveModels(args) {
     describeModel: pick("describe-model", "image_describe", "~google/gemini-pro-latest"),
     selectModel: pick("select-model", "text_generate", "~google/gemini-flash-latest"),
     layoutModel: pick("layout-model", "text_generate", "~google/gemini-flash-latest"),
-    genModel: pick("gen-model", "image_generate", "openai/gpt-5.4-image-2")
+    genModel: pick("gen-model", "image_generate", "openai/gpt-image-2")
   };
 }
 var PLATFORM_PLACEMENTS = {
@@ -21413,7 +21570,7 @@ function resolveModels2(args) {
     // Default to the strongest image model (matches the static-ad scaffold); the
     // frame generators need the most faithful text/identity reproduction. Override
     // with --image-model for a cheaper/faster pass.
-    imageModel: pick("image-model", "image_generate", "openai/gpt-5.4-image-2")
+    imageModel: pick("image-model", "image_generate", "openai/gpt-image-2")
   };
 }
 function hasPhotorealCast(elements) {
@@ -24123,7 +24280,7 @@ async function resolveReferences(spec) {
 var generateCommand = defineCommand114({
   meta: {
     name: "generate",
-    description: "Generate an image with AI and store it in the library (cost-tracked per request via OpenRouter usage). Models mirror the canvas: google/gemini-3.1-flash-image-preview (Nano Banana flash \u2014 default, fast, extreme aspect ratios) & google/gemini-3.5-flash (fast), google/gemini-3-pro-image-preview (Nano Banana Pro \u2014 highest fidelity), openai/gpt-5.4-image-2 (photoreal, cleanest in-image text, best for ad/landing reproduction), recraft/recraft-v4.1-pro-vector (vector/SVG-style with palette control). The result is auto-ingested (describe + embed), so the next `baker images library` query finds it. Pass --reference with image URLs and/or local file paths (Pinterest, stock, brand assets, sandbox files) to ground generation in reality.\n\nExamples:\n  baker images generate 'a friendly golden retriever sitting in a bright modern living room' --aspect-ratio 16:9\n  baker images generate 'hero shot of a matte black water bottle on marble' --model openai/gpt-5.4-image-2 --image-size 2K\n  baker images generate 'lifestyle photo matching this mood' --reference 'https://\u2026/ref1.jpg,https://\u2026/ref2.jpg'\n  baker images generate 'put this product on a marble countertop, soft daylight' --reference './src/brand/logos/product.png,./refs/kitchen-mood.jpg'\n  baker images generate 'flat geometric mascot, brand palette' --model recraft/recraft-v4.1-pro-vector --rgb-colors '[[10,10,10],[255,80,0]]'"
+    description: "Generate an image with AI and store it in the library (cost-tracked per request via OpenRouter usage). Models mirror the canvas: google/gemini-3.1-flash-image-preview (Nano Banana flash \u2014 default, fast, extreme aspect ratios), google/gemini-3-pro-image-preview (Nano Banana Pro \u2014 highest fidelity), openai/gpt-image-2 (photoreal, cleanest in-image text, best for ad/landing reproduction \u2014 no --image-size, and no 4:5 / 5:4), recraft/recraft-v4.1-pro-vector (vector/SVG-style with palette control). The result is auto-ingested (describe + embed), so the next `baker images library` query finds it. Pass --reference with image URLs and/or local file paths (Pinterest, stock, brand assets, sandbox files) to ground generation in reality.\n\nExamples:\n  baker images generate 'a friendly golden retriever sitting in a bright modern living room' --aspect-ratio 16:9\n  baker images generate 'hero shot of a matte black water bottle on marble' --model openai/gpt-image-2 --aspect-ratio 3:2\n  baker images generate 'lifestyle photo matching this mood' --reference 'https://\u2026/ref1.jpg,https://\u2026/ref2.jpg'\n  baker images generate 'put this product on a marble countertop, soft daylight' --reference './src/brand/logos/product.png,./refs/kitchen-mood.jpg'\n  baker images generate 'flat geometric mascot, brand palette' --model recraft/recraft-v4.1-pro-vector --rgb-colors '[[10,10,10],[255,80,0]]'"
   },
   args: {
     prompt: { type: "positional", description: "What to generate", required: false },
@@ -24296,6 +24453,34 @@ var gifCommand = defineCommand116({
 
 // src/commands/images/google.ts
 import { defineCommand as defineCommand117 } from "citty";
+
+// src/commands/images/searchHints.ts
+var FALLBACK = {
+  stock: "Still empty \u2192 `baker images find <query> --sources library,pinterest,google` (one call across the providers stock does not cover \u2014 `--sources` is required, `find` alone searches the library only) or `baker images generate` to make the asset. Do not re-run this search with reshuffled flags.",
+  google: "Still empty \u2192 `baker images generate` to make the asset. Google is the last-resort provider; there is nothing below it to retry."
+};
+function emptyResultHints({ provider, hitCount, activeFilters }) {
+  if (hitCount > 0) {
+    return [];
+  }
+  const hints = [];
+  if (activeFilters.length > 0) {
+    hints.push(
+      `No hits. Drop the filters before touching the query \u2014 ${activeFilters.join(", ")} narrowed this search and filter combinations are the usual cause of an empty result.`
+    );
+  }
+  hints.push(FALLBACK[provider]);
+  return hints;
+}
+function activeFilterFlags(args, candidates) {
+  return candidates.filter((flag) => args[flag] !== void 0 && args[flag] !== "").map((flag) => `--${flag}`);
+}
+
+// src/commands/images/google.ts
+var GOOGLE_ERROR_FIX = {
+  action: "use_different_resource",
+  explanation: "Generate the asset instead of retrying Google. Google is the last-resort image provider. Run `baker images generate` to make the asset. Never sleep-and-retry this command \u2014 the CLI already backs off on rate limits. If no image can be sourced, continue the rest of the task with a placeholder rather than aborting it."
+};
 registerSchema({
   command: "images.google",
   description: "Google Images search via the official Custom Search JSON API. Unverified source \u2014 inspect before placing.",
@@ -24366,10 +24551,18 @@ var googleCommand2 = defineCommand117({
       if (args["auto-ingest"]) body.autoIngest = Number(args["auto-ingest"]);
       if (args.context) body.descriptionContext = args.context;
       const data = await apiPost("/api/images/google", body);
-      writeJson({ ok: true, data });
+      const hints = emptyResultHints({
+        provider: "google",
+        hitCount: data.hits.length,
+        activeFilters: activeFilterFlags(args, ["type", "size", "color", "safe"])
+      });
+      writeJson({ ok: true, data, ...hints.length ? { hints } : {} });
     } catch (err) {
       if (err instanceof ApiError) {
-        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        writeJson({
+          ok: false,
+          error: { code: err.code, message: err.message, fix: GOOGLE_ERROR_FIX }
+        });
         process.exit(1);
       }
       writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
@@ -24500,31 +24693,6 @@ var ingestCommand = defineCommand119({
 
 // src/commands/images/library.ts
 import { defineCommand as defineCommand120 } from "citty";
-
-// src/commands/images/logoHints.ts
-var LOGO_QUERY_RE = /\blogos?\b|\bwordmark\b|\bbrand mark\b/i;
-function withLogoShape(row) {
-  return {
-    ...row,
-    logoShape: classifyLogoShape({
-      aspectRatio: row.aspectRatio,
-      hasAlpha: row.hasAlpha,
-      solidity: row.solidity
-    })
-  };
-}
-function buildLogoLibraryHints(query, rows) {
-  if (!LOGO_QUERY_RE.test(query)) return [];
-  const plates = rows.filter((row) => row.logoShape === "plated-icon");
-  if (plates.length === 0) return [];
-  const names = plates.map((row) => row.name).filter((name) => Boolean(name)).slice(0, 4);
-  const subject = names.length > 0 ? names.join(", ") : `${plates.length} result(s)`;
-  return [
-    `PLATED ICON: ${subject} \u2014 solid tile with the mark knocked out, not a wordmark. In a logo strip it renders as a filled box and verify blocks it (logo-plate). Re-source with 'baker images logo <domain> --variant logo', or strip the plate with 'baker images normalize <file> --remove-bg --shrink-to-content'. Only use a plate in slots under ~32px.`
-  ];
-}
-
-// src/commands/images/library.ts
 registerSchema({
   command: "images.library",
   description: "Search the company image library. Returns only ready images.",
@@ -24589,10 +24757,8 @@ var libraryCommand = defineCommand120({
       if (minScore !== void 0) {
         data = data.filter((r) => typeof r.score === "number" && r.score >= minScore);
       }
-      const shaped = data.map(withLogoShape);
-      const hints = buildLogoLibraryHints(query, shaped);
       writeOutput(
-        { ok: true, data: shaped, ...hints.length > 0 ? { hints } : {} },
+        { ok: true, data },
         args.output || "json",
         args.fields ? args.fields.split(",") : void 0,
         args.full
@@ -24610,16 +24776,11 @@ var libraryCommand = defineCommand120({
 
 // src/commands/images/logo.ts
 import { defineCommand as defineCommand121 } from "citty";
-var MAX_DOMAINS = 20;
 registerSchema({
   command: "images.logo",
   description: "Brand logo lookup via Brandfetch CDN (fallback/404). Auto-ingests by default.",
   args: {
-    domain: {
-      type: "string",
-      description: "Brand domain, or a comma-separated list for a whole strip (e.g. stripe.com,intercom.com)",
-      required: true
-    },
+    domain: { type: "string", description: "Brand domain (e.g. stripe.com)", required: true },
     variant: { type: "string", description: "icon | logo | symbol", required: false },
     "auto-ingest": {
       type: "number",
@@ -24642,10 +24803,10 @@ registerSchema({
 var logoCommand = defineCommand121({
   meta: {
     name: "logo",
-    description: "Brand logo via Brandfetch CDN. Returns up to 5 variants (icon, light/dark logo, light/dark symbol). Auto-ingests the first variant.\n\nSource a whole strip in one call by passing a comma-separated list \u2014 a text-rendered brand name is never the cheaper option.\n\nExamples:\n  baker images logo stripe.com --variant logo\n  baker images logo stripe.com,intercom.com,notion.so --variant logo"
+    description: "Brand logo via Brandfetch CDN. Returns up to 5 variants (icon, light/dark logo, light/dark symbol). Auto-ingests the first variant.\n\nExample: baker images logo stripe.com --variant logo"
   },
   args: {
-    domain: { type: "positional", description: "Brand domain, or a comma-separated list", required: false },
+    domain: { type: "positional", description: "Brand domain", required: false },
     variant: { type: "string", description: "icon|logo|symbol", required: false },
     "auto-ingest": { type: "string", description: "Ingest top N (0-20, default 1)", required: false },
     "no-auto-ingest": { type: "boolean", description: "Skip auto-ingest", required: false },
@@ -24653,50 +24814,18 @@ var logoCommand = defineCommand121({
   },
   run: async ({ args }) => {
     try {
-      const raw = args.domain;
-      const domains = [
-        ...new Set(
-          (raw ?? "").split(",").map((d) => d.trim()).filter(Boolean)
-        )
-      ];
-      if (domains.length === 0) {
+      const domain = args.domain;
+      if (!domain) {
         writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Domain is required" } });
         process.exit(1);
       }
-      if (domains.length > MAX_DOMAINS) {
-        writeJson({
-          ok: false,
-          error: {
-            code: "VALIDATION_ERROR",
-            message: `Too many domains (${domains.length}); pass at most ${MAX_DOMAINS} per call`
-          }
-        });
-        process.exit(1);
-      }
-      const base = {};
-      if (args.variant) base.variant = args.variant;
-      if (args["auto-ingest"] !== void 0) base.autoIngest = Number(args["auto-ingest"]);
-      else if (args["no-auto-ingest"]) base.autoIngest = 0;
-      if (args.context) base.descriptionContext = args.context;
-      const fetchOne = (domain) => apiPost("/api/images/logo", { ...base, domain });
-      if (domains.length === 1) {
-        writeJson({ ok: true, data: await fetchOne(domains[0]) });
-        return;
-      }
-      const settled = await Promise.all(
-        domains.map(async (domain) => {
-          try {
-            return { domain, ...await fetchOne(domain) };
-          } catch (err) {
-            return { domain, hits: [], error: err instanceof ApiError ? err.message : "Lookup failed" };
-          }
-        })
-      );
-      const empty = settled.filter((r) => r.hits.length === 0).map((r) => r.domain);
-      const hints = empty.length > 0 ? [
-        `NO LOGO: ${empty.join(", ")} \u2014 Brandfetch doesn't know ${empty.length === 1 ? "this brand" : "these brands"}. Fall back per domain: 'baker images extract <domain> --auto-ingest 5', then 'baker images icon <brand> --set simple-icons'. Still nothing \u2192 'baker actions create' to acquire the file. Do not render the name as text.`
-      ] : [];
-      writeJson({ ok: true, data: { results: settled }, ...hints.length > 0 ? { hints } : {} });
+      const body = { domain };
+      if (args.variant) body.variant = args.variant;
+      if (args["auto-ingest"] !== void 0) body.autoIngest = Number(args["auto-ingest"]);
+      else if (args["no-auto-ingest"]) body.autoIngest = 0;
+      if (args.context) body.descriptionContext = args.context;
+      const data = await apiPost("/api/images/logo", body);
+      writeJson({ ok: true, data });
     } catch (err) {
       if (err instanceof ApiError) {
         writeJson({ ok: false, error: { code: err.code, message: err.message } });
@@ -24740,7 +24869,6 @@ function getDominantEdgeColor(data, width, height) {
   const colorCount = {};
   function accumulateColor(i, j) {
     const idx = (i * width + j) * 4;
-    if ((data[idx + 3] ?? 0) < 10) return;
     const colorKey = `${data[idx]},${data[idx + 1]},${data[idx + 2]}`;
     colorCount[colorKey] = (colorCount[colorKey] ?? 0) + 1;
   }
@@ -24753,7 +24881,7 @@ function getDominantEdgeColor(data, width, height) {
     accumulateColor(i, width - 1);
   }
   let maxCount = 0;
-  let dominantColor = null;
+  let dominantColor = { r: 0, g: 0, b: 0 };
   for (const key in colorCount) {
     const count = colorCount[key];
     if (count > maxCount) {
@@ -24764,27 +24892,6 @@ function getDominantEdgeColor(data, width, height) {
   }
   return dominantColor;
 }
-function opaqueSolidity(data, width, height) {
-  let minX = width;
-  let minY = height;
-  let maxX = -1;
-  let maxY = -1;
-  let opaque = 0;
-  for (let y = 0; y < height; y++) {
-    for (let x = 0; x < width; x++) {
-      if ((data[(y * width + x) * 4 + 3] ?? 0) <= 200) continue;
-      opaque++;
-      if (x < minX) minX = x;
-      if (x > maxX) maxX = x;
-      if (y < minY) minY = y;
-      if (y > maxY) maxY = y;
-    }
-  }
-  if (maxX < 0) return 0;
-  const boxArea = (maxX - minX + 1) * (maxY - minY + 1);
-  return boxArea === 0 ? 0 : opaque / boxArea;
-}
-var PLATE_SOLIDITY_THRESHOLD2 = 0.6;
 function hasTransparency(data, threshold = 0.02) {
   let transparentPixels = 0;
   let totalPixels = 0;
@@ -24849,9 +24956,6 @@ function removeBackground(data, width, height, colorRangeThreshold = COLOR_RANGE
     return data;
   }
   const dominantEdgeColor = getDominantEdgeColor(data, width, height);
-  if (!dominantEdgeColor) {
-    return data;
-  }
   const isGradient = hasGradientColors(data);
   const result = Buffer.from(data);
   if (isGradient) {
@@ -25129,8 +25233,8 @@ async function processInternal(inputBuffer, isSVG, options) {
   const metadata = await sharp3(inputBuffer).metadata();
   let alreadyTransparent = false;
   if (metadata.hasAlpha) {
-    const { data: alphaData, info: info2 } = await sharp3(inputBuffer).raw().toBuffer({ resolveWithObject: true });
-    alreadyTransparent = opaqueSolidity(alphaData, info2.width, info2.height) < PLATE_SOLIDITY_THRESHOLD2;
+    const { data: alphaData } = await sharp3(inputBuffer).raw().toBuffer({ resolveWithObject: true });
+    alreadyTransparent = hasTransparency(alphaData, 0.05);
   }
   let { data: processedData, info } = await sharp3(inputBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
   if (options.color) {
@@ -25816,6 +25920,10 @@ var stickerCommand = defineCommand126({
 
 // src/commands/images/stock.ts
 import { defineCommand as defineCommand127 } from "citty";
+var STOCK_ERROR_FIX = {
+  action: "use_different_resource",
+  explanation: "Switch provider instead of retrying stock search. Stock search is one of several image sources. Run `baker images find <query> --sources library,pinterest,google` (`--sources` is required \u2014 `find` alone searches the library only) or `baker images generate` to make the asset. Never sleep-and-retry this command \u2014 the CLI already backs off on rate limits. If no image can be sourced, continue the rest of the task with a placeholder rather than aborting it."
+};
 registerSchema({
   command: "images.stock",
   description: "Stock photo, vector illustration, icon-set, and PSD search via Magnific (Freepik's developer API).",
@@ -25873,6 +25981,21 @@ registerSchema({
     }
   }
 });
+function buildStockRequest(query, args) {
+  const body = { query };
+  if (args.type) body.contentType = args.type;
+  if (args.orientation) body.orientation = args.orientation;
+  if (args.license) body.license = args.license;
+  if (args.color) body.color = args.color;
+  if (args.ai) body.aiGenerated = args.ai;
+  if (args.people) body.people = args.people;
+  if (args.order) body.order = args.order;
+  if (args.limit) body.limit = Number(args.limit);
+  if (args.page) body.page = Number(args.page);
+  if (args["auto-ingest"]) body.autoIngest = Number(args["auto-ingest"]);
+  if (args.context) body.descriptionContext = args.context;
+  return body;
+}
 var stockCommand = defineCommand127({
   meta: {
     name: "stock",
@@ -25903,23 +26026,23 @@ var stockCommand = defineCommand127({
         writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Query is required" } });
         process.exit(1);
       }
-      const body = { query };
-      if (args.type) body.contentType = args.type;
-      if (args.orientation) body.orientation = args.orientation;
-      if (args.license) body.license = args.license;
-      if (args.color) body.color = args.color;
-      if (args.ai) body.aiGenerated = args.ai;
-      if (args.people) body.people = args.people;
-      if (args.order) body.order = args.order;
-      if (args.limit) body.limit = Number(args.limit);
-      if (args.page) body.page = Number(args.page);
-      if (args["auto-ingest"]) body.autoIngest = Number(args["auto-ingest"]);
-      if (args.context) body.descriptionContext = args.context;
-      const data = await apiPost("/api/images/stock", body);
-      writeJson({ ok: true, data });
+      const data = await apiPost("/api/images/stock", buildStockRequest(query, args));
+      const hints = emptyResultHints({
+        provider: "stock",
+        hitCount: data.hits.length,
+        activeFilters: activeFilterFlags(args, ["type", "orientation", "license", "color", "ai", "people"])
+      });
+      writeJson({ ok: true, data, ...hints.length ? { hints } : {} });
     } catch (err) {
       if (err instanceof ApiError) {
-        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        writeJson({
+          ok: false,
+          error: {
+            code: err.code,
+            message: err.message,
+            fix: STOCK_ERROR_FIX
+          }
+        });
         process.exit(1);
       }
       writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });