@koda-sl/baker-cli 0.568.0 → 0.569.0-dev.1b455b3fe

package/dist/scaffold-static-ad-CRN5XZIZ.js

@@ -0,0 +1,1013 @@
+import {
+  withClientLogo
+} from "./chunk-GGXPO4NQ.js";
+import {
+  isValidScaffoldSlug,
+  resolveCastAvatars,
+  resolveScaffoldStaticAdPaths
+} from "./chunk-HJ3Q4NOM.js";
+import {
+  fail,
+  fileExists,
+  loadAssetText,
+  parseElements,
+  resolveModel
+} from "./chunk-SIKCVWM3.js";
+import {
+  readDefinitionPlatforms,
+  syncCreativeDefinitionBestEffort
+} from "./chunk-FTKUHGTC.js";
+import {
+  buildBackendClient
+} from "./chunk-L43B2YGZ.js";
+import "./chunk-TAGJYHVI.js";
+import "./chunk-WXSRSMY3.js";
+import "./chunk-WN4KX7GE.js";
+import "./chunk-IWNLW7ZC.js";
+import "./chunk-IVIJJXXT.js";
+import "./chunk-KKJ4KJCW.js";
+import "./chunk-Q6ULQMWG.js";
+import "./chunk-KNA3OWJC.js";
+import "./chunk-3ACMDRSE.js";
+import "./chunk-I7OJZ7QE.js";
+import {
+  deliveryDefinitionFields,
+  deliveryNote,
+  namesDelivery,
+  scaffoldDelivery
+} from "./chunk-X3L5HYQM.js";
+import "./chunk-77LXZAX2.js";
+import "./chunk-OSZOUSK5.js";
+import "./chunk-O7WRA3JU.js";
+import "./chunk-SOM4OTR5.js";
+import {
+  brandBlock,
+  brandHeadlineFont,
+  buildCreativeDefinition,
+  castAvatarsOnStaticElements,
+  castOnIdeaSpec,
+  computeSourceSha,
+  describeBlueprintIntent,
+  findBrandRoot,
+  parseDefinitionViewerFields,
+  pickImageModel,
+  readLogoFile,
+  readNamedTypefaces,
+  readStaticBrandKit,
+  rebasedDefinition,
+  recordedShape,
+  resolveFormatList,
+  scaffoldStaticAd,
+  setDefinitionDelivery,
+  setDefinitionViewer,
+  staticAdReport,
+  staticAdSpec,
+  staticAvatarsNotCast,
+  titleFromSlug,
+  webFontUrl
+} from "./chunk-ROHICQPK.js";
+import {
+  describeViewer,
+  liveViewerLookups,
+  resolveViewer
+} from "./chunk-CKHF7UXS.js";
+import "./chunk-HDMD6LXS.js";
+import "./chunk-CP6RFWLW.js";
+import "./chunk-EKX37C3T.js";
+import "./chunk-SZZ7BBED.js";
+import {
+  LIBRARY_PLATFORMS,
+  NO_FIT_HINT,
+  conceptFromFit,
+  fetchLibraryReference,
+  fitHints,
+  libraryReferenceBlock,
+  mergeReferenceIntoBlueprint,
+  notADesignReference,
+  readCachedFit,
+  referenceDescribeContext,
+  resolveSourcePlatform
+} from "./chunk-QXRSFH6M.js";
+import "./chunk-QMQSI4WA.js";
+import "./chunk-OFMFBRSL.js";
+import "./chunk-IKADYUXK.js";
+import "./chunk-46DHUWMV.js";
+import {
+  fetchJson,
+  lookupGoogleCss
+} from "./chunk-4KBTW5NE.js";
+import "./chunk-MWJ6BCZJ.js";
+import "./chunk-SYDPUGF5.js";
+import "./chunk-ESSA3AWR.js";
+import "./chunk-TQJLEVLA.js";
+import "./chunk-G6XKD7QE.js";
+import "./chunk-4H6XLX7E.js";
+import "./chunk-Y5PNLB24.js";
+import {
+  findWorkspaceRoot,
+  resolveRelativeCanvasPaths
+} from "./chunk-N3PASNUA.js";
+import {
+  ValidationError,
+  createEngineFromEnv,
+  defaultRegistry,
+  validateCanvasDeep
+} from "./chunk-IAYJKH4R.js";
+import "./chunk-7URHRPC7.js";
+import "./chunk-TW57RTKN.js";
+import "./chunk-AQNTVM6S.js";
+import "./chunk-DGCUPJZD.js";
+import "./chunk-Y2TOB4N5.js";
+import {
+  conceptClassOf,
+  conceptProblems,
+  readAdSpec
+} from "./chunk-KJ3J2DYM.js";
+import "./chunk-MTFAG6E3.js";
+import {
+  AD_DESCRIBE_FOCUS,
+  AD_DESCRIBE_MODEL,
+  AD_PLATFORM_LEAD,
+  AD_SELECT_PROMPT,
+  AD_SELECT_SYSTEM,
+  BLUEPRINT_ANALYSIS_MODEL
+} from "./chunk-F3CZFUXZ.js";
+import {
+  VIEWER_KNOWS_VALUES,
+  VIEWER_TEMPERATURE_VALUES,
+  marketFromCompanyDoc
+} from "./chunk-2WZI36D3.js";
+import "./chunk-65Y3RCWP.js";
+import "./chunk-E56V3RFO.js";
+import {
+  sha256Hex,
+  toModelSafeImage
+} from "./chunk-EL3TDR5S.js";
+import "./chunk-G6U45QD3.js";
+import {
+  MAX_REMOTE_IMAGE_BYTES,
+  fetchExternalBytes
+} from "./chunk-X6U3B6YK.js";
+import "./chunk-YOHGEF2N.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-IMS53EQU.js";
+import {
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  referenceReadResponseSchema,
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/canvas/scaffold-static-ad.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+
+// src/commands/canvas/scaffold-viewer.ts
+function flagText(value) {
+  const text = typeof value === "string" || typeof value === "number" ? String(value).trim() : "";
+  return text || void 0;
+}
+function narrows(placements) {
+  return placements.some((placement) => placement !== "automatic");
+}
+function flagList(value) {
+  const list = (flagText(value) ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  return list.length > 0 ? list : void 0;
+}
+var isTemperature = (value) => VIEWER_TEMPERATURE_VALUES.includes(value);
+var isKnows = (value) => VIEWER_KNOWS_VALUES.includes(value);
+function viewerFields(flags) {
+  const temperature = flagText(flags["viewer-temperature"]);
+  if (temperature !== void 0 && !isTemperature(temperature)) {
+    return { ok: false, message: `--viewer-temperature must be one of ${VIEWER_TEMPERATURE_VALUES.join(", ")}` };
+  }
+  const knows = flagList(flags["viewer-knows"]);
+  if (knows && !knows.every(isKnows)) {
+    return { ok: false, message: `--viewer-knows takes ${VIEWER_KNOWS_VALUES.join(", ")}` };
+  }
+  const placements = flagList(flags["viewer-placements"]);
+  return {
+    ok: true,
+    fields: {
+      ...temperature ? { temperature } : {},
+      ...knows ? { knows: knows.filter(isKnows) } : {},
+      ...placements ? { placements } : {}
+    }
+  };
+}
+function givenViewer(fields) {
+  if (!fields.temperature) return void 0;
+  return {
+    temperature: fields.temperature,
+    knows: fields.knows ?? [],
+    placements: fields.placements ?? ["automatic"],
+    source: "knowledge",
+    reasons: ["No ad set was read: this viewer was given when the ad was scaffolded, from the Knowledge."]
+  };
+}
+var FIELD_WORDS = {
+  temperature: "Temperature",
+  knows: "What they know",
+  placements: "Placements"
+};
+function correctedViewer(read, fields) {
+  const stated = Object.keys(FIELD_WORDS).filter((key) => fields[key] !== void 0);
+  if (stated.length === 0) return read;
+  return {
+    ...read,
+    ...fields,
+    reasons: [...read.reasons, ...stated.map((key) => `${FIELD_WORDS[key]} given when the ad was scaffolded.`)]
+  };
+}
+var EVERY_PLACEMENT = "so the sizes keep clear of every placement";
+async function readAdSet(adSetId, adSetViewer, notes) {
+  try {
+    const viewer = await adSetViewer(adSetId);
+    if (viewer) return viewer;
+    notes.push(`Ad set ${adSetId} is not in any connected Meta ad account, ${EVERY_PLACEMENT}.`);
+  } catch (e) {
+    notes.push(`Could not read ad set ${adSetId} (${e instanceof Error ? e.message : String(e)}), ${EVERY_PLACEMENT}.`);
+  }
+  return void 0;
+}
+async function recordedViewer(definition, adSetViewer) {
+  const { targetAdSet, viewer: recorded } = parseDefinitionViewerFields(definition);
+  if (!targetAdSet && recorded === void 0) return { ok: true, record: false, notes: [] };
+  const resolved = await resolveViewer({ recorded, targetAdSet }, { adSetViewer, personas: async () => [] });
+  const viewer = resolved.from === "recorded" || resolved.from === "ad_set" ? resolved.viewer : void 0;
+  return outcome(targetAdSet, viewer, false, resolved.notes);
+}
+function outcome(targetAdSet, viewer, record, notes) {
+  return {
+    ok: true,
+    ...targetAdSet ? { targetAdSet } : {},
+    ...viewer ? { viewer } : {},
+    record,
+    ...viewer && narrows(viewer.placements) ? { adPlacements: viewer.placements } : {},
+    notes
+  };
+}
+async function scaffoldViewer(flags, existingDefinition, adSetViewer) {
+  const targetAdSet = flagText(flags["target-adset"]);
+  const given = viewerFields(flags);
+  if (!given.ok) return given;
+  const { fields } = given;
+  if (!targetAdSet && !fields.temperature && (fields.knows || fields.placements)) {
+    return {
+      ok: false,
+      message: "--viewer-knows and --viewer-placements describe a viewer: pass --viewer-temperature too"
+    };
+  }
+  if (!targetAdSet && !fields.temperature && existingDefinition !== null) {
+    return await recordedViewer(existingDefinition, adSetViewer);
+  }
+  const notes = [];
+  const read = targetAdSet ? await readAdSet(targetAdSet, adSetViewer, notes) : void 0;
+  const viewer = read ? correctedViewer(read, fields) : givenViewer(fields);
+  return outcome(targetAdSet, viewer, targetAdSet !== void 0 || viewer !== void 0, notes);
+}
+
+// src/commands/canvas/scaffold-static-ad.ts
+function toCanvasRelative(canvasDir, file) {
+  const rel = path.relative(canvasDir, file).split(path.sep).join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+async function uploadSourceAsReference(source, isUrl, client) {
+  let bytes;
+  if (isUrl) {
+    try {
+      ({ buffer: bytes } = await fetchExternalBytes(source, { maxBytes: MAX_REMOTE_IMAGE_BYTES }));
+    } catch (e) {
+      throw new Error(`failed to download source image (${e instanceof Error ? e.message : String(e)})`);
+    }
+  } else {
+    bytes = await readFile(source);
+  }
+  const safe = await toModelSafeImage(bytes);
+  const sha256 = sha256Hex(safe.bytes);
+  const { putUrl, publicUrl } = await client.presignAssetUpload(sha256, safe.mime, void 0, "source");
+  const putRes = await fetch(putUrl, {
+    method: "PUT",
+    body: new Uint8Array(safe.bytes),
+    headers: { "Content-Type": safe.mime }
+  });
+  if (!putRes.ok) throw new Error(`source upload failed (${putRes.status})`);
+  return publicUrl;
+}
+async function brandFace(root, kit, toCanvas) {
+  const font = await brandHeadlineFont({
+    file: kit.headlineFont,
+    named: await readNamedTypefaces(root),
+    resolveUrl: (family, weight) => webFontUrl(family, weight, { lookupGoogleCss, fetchJson })
+  });
+  if (!font) return null;
+  return "path" in font.slot ? { ...font, slot: { path: toCanvas(font.slot.path) } } : font;
+}
+function staticTextNote(report) {
+  if (report.text_forward) {
+    return "The reference pictures nothing but copy, so this ad is its words on the brand's colours: keep prompt.json's `references` empty unless the concept wants a picture.";
+  }
+  const face = report.font ? `in ${report.font}, shown to it as a specimen` : "in the face `brand.typeface` names (the brand has no font file)";
+  return `The copy is set by the image model: every line of \`copy\` in prompt.json, exactly as written, once. A line marked \`"lettering": "designed"\` is set ${face}; a line marked \`"in_scene"\` is lettered on the object it names (\`on\`), the way \`look\` says. Edit the copy in prompt.json; every run compiles the render prompts from it again and the review reads every word back against it.`;
+}
+function staticFormatsNote(report, genModel, delivery) {
+  const set = delivery ? ` ${deliveryNote(delivery, report.format_plan.master.renderRatio)}` : "";
+  const banners = report.banners.length > 0 ? ` The fixed banners ${report.banners.join(", ")} are not made from the picture: make them apart, from the delivered sizes, before staging a display campaign.` : "";
+  const plan = report.format_plan;
+  const made = {
+    master: (format) => `${format} is the chosen picture (rendered at ${plan.master.renderRatio})`,
+    relayout: (format) => `${format} is the chosen ad re-laid out for that frame by the image model (one billed request): the same words, people, product and logo, re-scaled for the frame, inside its safe area`,
+    crop: (format) => `${format} is cut from it, every word kept inside its safe area (free)`,
+    adapt: (format) => `${format} is adapted from it by the reframe model (one billed request)`
+  };
+  const how = plan.sizes.map((f) => made[f.from]?.(f.format) ?? f.format).join("; ");
+  const again = plan.sizes.some((s) => s.from === "relayout") ? "" : " No size is rendered again.";
+  return `Delivers ${report.output_formats.join(", ")}, each at its exact size, all from one picture (${genModel}): ${how}.${again}${set}${banners}`;
+}
+function viewerOutput(who) {
+  return {
+    ...who.targetAdSet ? { target_adset: who.targetAdSet } : {},
+    ...who.viewer ? {
+      viewer: {
+        temperature: who.viewer.temperature,
+        knows: who.viewer.knows,
+        placements: who.viewer.placements,
+        source: who.viewer.source
+      }
+    } : {}
+  };
+}
+function viewerNote(who) {
+  if (!who.viewer) {
+    return "Nobody said who sees this ad: pass --target-adset <id> (or, with no ad account, --viewer-temperature from the Knowledge) so the sizes keep clear of its placements and every run checks the ad against that viewer. Until then it is checked against a cold stranger.";
+  }
+  const sizes = who.adPlacements ? `the sizes keep clear of ${who.adPlacements.join(", ")}` : "the sizes keep clear of every placement (Advantage+)";
+  return `Made for ${describeViewer(who.viewer)}: write prompt.json's \`viewer\` for them, ${sizes}, and every run checks the ad against this viewer before it spends.`;
+}
+function resolveModels(args) {
+  return {
+    describeModel: resolveModel("image_describe", args["describe-model"], AD_DESCRIBE_MODEL),
+    selectModel: resolveModel("text_generate", args["select-model"], BLUEPRINT_ANALYSIS_MODEL),
+    // The render model: `--gen-model`, else the router's model for the concept (decided once
+    // the blueprint is read, `renderModelFor`). Resolved here only so a bad override fails for free.
+    genModel: args["gen-model"] ? resolveModel("image_generate", args["gen-model"], String(args["gen-model"])) : void 0
+  };
+}
+async function deliveryOrFail(args, definitionText, isCreative) {
+  if (!isCreative && !namesDelivery(args)) return void 0;
+  const resolved = await scaffoldDelivery(args, definitionText);
+  if (!resolved.ok) return fail(resolved.error.code, resolved.error.message, resolved.error.fix);
+  return resolved.delivery;
+}
+function deliveryOutput(delivery) {
+  return delivery ? { platforms: delivery.platforms, lead: delivery.lead, platform_source: delivery.source } : {};
+}
+async function validateScaffoldedStaticAd(canvas, canvasDir) {
+  const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(canvas, canvasDir), defaultRegistry());
+  if (validation.ok) return { blocking: [], hints: [], estimatedCredits: validation.estimatedCredits };
+  const overCap = validation.issues.filter((i) => i.code === "PROMPT_OVER_MODEL_LIMIT");
+  return {
+    blocking: validation.issues.filter((i) => i.code !== "PROMPT_OVER_MODEL_LIMIT"),
+    hints: overCap.map((i) => `${i.code}: ${i.message} Trim prompt.json, then \`baker canvas validate\`.`)
+  };
+}
+function buildDescribeCanvas(imageSource, imageIsUrl, describeModel, selectModel, context) {
+  const originalParams = imageIsUrl ? { source: "url", url: imageSource, expect: "image" } : { source: "path", path: imageSource, expect: "image" };
+  return {
+    schema: "baker-canvas/1",
+    metadata: { name: "static-ad describe pass" },
+    nodes: [
+      { id: "original", type: "ingest", params: originalParams },
+      {
+        id: "describe",
+        type: "image_describe",
+        inputs: { image: "$ref:original.asset" },
+        params: { model: describeModel, max_tokens: 9e3, ...context ? { context } : {}, focus: AD_DESCRIBE_FOCUS }
+      },
+      {
+        id: "select",
+        type: "text_generate",
+        inputs: { blueprint: "$ref:describe.description" },
+        params: {
+          model: selectModel,
+          max_tokens: 4e3,
+          temperature: 0,
+          response_format: "json_object",
+          system: AD_SELECT_SYSTEM,
+          prompt: AD_SELECT_PROMPT
+        }
+      }
+    ]
+    // No declared output: runVisionPasses reads both node outputs after the run.
+  };
+}
+async function runVisionPasses(canvas) {
+  const engine = createEngineFromEnv({ log: (line) => process.stderr.write(`${line}
+`) });
+  let outputsByNode;
+  let creditsSpent;
+  try {
+    const result = await engine.run(canvas, {});
+    outputsByNode = result.outputs_by_node;
+    creditsSpent = result.stats?.total_credits;
+  } catch (e) {
+    if (e instanceof ValidationError) return fail("validation", JSON.stringify(e.issues));
+    return fail("describe", e instanceof Error ? e.message : String(e));
+  }
+  try {
+    const blueprint = JSON.parse(await loadAssetText(outputsByNode.describe?.description, "describe output"));
+    const elements = parseElements(await loadAssetText(outputsByNode.select?.text, "selection output"));
+    return { blueprint, elements, creditsSpent };
+  } catch (e) {
+    return fail("read_outputs", e instanceof Error ? e.message : String(e));
+  }
+}
+function noFitNote(reference) {
+  return `${NO_FIT_HINT}: \`baker winning-ads fit ${reference.ad_id} --platform ${reference.platform}\` says what it wins on and what we have for it, and re-scaffolding seeds prompt.json's \`concept\` from it.`;
+}
+function sharesLibraryRead(args, fromLibrary) {
+  return fromLibrary && !args.file && !args.context && !args["describe-model"] && !args["select-model"];
+}
+async function sharedLibraryRead(reference) {
+  try {
+    const read = referenceReadResponseSchema.parse(
+      await apiPost(
+        "/api/ad-library/reference-read",
+        { ad_id: reference.ad_id, platform: reference.platform },
+        { timeoutMs: 24e4 }
+      )
+    );
+    process.stderr.write(`[read    ] ${read.reused ? "the library's read of this ad, already made" : "read this ad for the library"}
+`);
+    return {
+      blueprint: read.blueprint,
+      elements: parseElements(JSON.stringify({ elements: read.elements })),
+      creditsSpent: read.credits_charged
+    };
+  } catch (e) {
+    process.stderr.write(`[read    ] the library's read is unavailable (${e instanceof Error ? e.message : String(e)}); reading the picture here
+`);
+    return null;
+  }
+}
+var SOURCE_AD_ID_DESCRIPTION = "The winners-library ad this creative adapts (the `ad_id` from `baker winning-ads search`). The library's read of that ad (container, layout, colours, text blocks with their roles, persuasion mechanism, offer) is fetched and written into prompt.json as `reference`, the describe pass is told it so the two reads agree, and the source is recorded on the creative from this scaffold on. With it, the image is optional: the library's picture is used when none is given. Pass it whenever the reference came from the library.";
+var PLATFORMS_DESCRIPTION = `Where the ad runs, the main platform first. Start here: --platforms meta (4:5 + 9:16), --platforms linkedin (1:1), --platforms linkedin,meta (1:1 first, then 4:5 + 9:16). Take it from the person's request, the idea or the ad set; required for a creative, never defaulted. Every size the platforms need is delivered, the platform's own size designed first, each kept clear of its placement's interface; a placement id names one placement alone (meta_stories: 9:16 only). Platforms: ${Object.entries(AD_PLATFORM_LEAD).map(([p, lead]) => `${p} (${lead})`).join(", ")}. Fixed banner sizes (728x90\u2026) are listed, not made.`;
+var FORMATS_DESCRIPTION = "Exactly the sizes to deliver, when the person asks for others than the platform's (e.g. `--platforms linkedin --formats 1:1,4:5`). A size the platform never shows is refused; leaving out one it needs is honoured with a warning naming the placements that get a cropped picture.";
+var RETIRED_PLATFORM_DESCRIPTION = "Retired: use --platforms. Still read (meta|google|linkedin|tiktok|youtube|x) and mapped onto --platforms.";
+var RETIRED_PLACEMENTS_DESCRIPTION = "Retired: use --platforms (meta_feed_stories \u2192 meta, meta_all \u2192 meta,meta_right_column). `none` is refused: name the placement instead (--platforms meta_stories).";
+var SOURCE_PLATFORM_DESCRIPTION = `Which platform the library ad is on: ${LIBRARY_PLATFORMS.join("|")} (default meta).`;
+var TARGET_ADSET_DESCRIPTION = "The Meta ad set this ad will run in (an id from `baker ads meta adsets`). Who it reaches is read off its targeting, as `baker ads meta adsets --audience` reads it, and recorded in _definition.md as `targetAdSet` and `viewer`; the sizes and the render brief keep clear of its placements, and every run checks the ad against that viewer. Free, read before anything is billed. Start here whenever the ad is for a known ad set.";
+var VIEWER_TEMPERATURE_DESCRIPTION = "With no ad set to read (no ad account, or not decided yet): how warm the viewer is, from the Knowledge (personas, funnel): cold (never heard of the brand), warm (knows the brand), hot (a customer). Recorded as `viewer` with `source: knowledge`. With --target-adset it corrects the temperature read off the ad set.";
+var VIEWER_KNOWS_DESCRIPTION = "What the viewer already knows, comma-separated from brand,offer,product (e.g. `brand,offer`). Needs --viewer-temperature or --target-adset.";
+var VIEWER_PLACEMENTS_DESCRIPTION = "Where the viewer meets the ad, comma-separated Meta placements (e.g. `instagram_feed,facebook_feed`, `instagram_stories`); default automatic (Advantage+, Reels included). The sizes keep clear of these placements' interface. Needs --viewer-temperature or --target-adset.";
+var OPERATOR = "Operator only, agents never need it.";
+var SCAFFOLD_SHAPES = ["plate", "relayout"];
+function masterShapeArg(value) {
+  if (value === void 0) return void 0;
+  const shape = SCAFFOLD_SHAPES.find((s) => s === String(value));
+  return shape ?? null;
+}
+var SOURCE_ADVERTISER_ID_DESCRIPTION = "The library advertiser id of the reference (the `advertiser_id` beside the ad in search results). Defaults to the one the library returns for the ad.";
+registerSchema({
+  command: "canvas.scaffold-static-ad",
+  description: "Turn a reference image into a runnable static-ad canvas: billed image_describe + element-selection passes, then a canvas on which the image model renders the finished ad from prompt.json. Start here for a static ad adapted from a winning ad: pass `--source-ad-id <ad_id> --source-platform <platform>` from the search result, so the library's structured read grounds the describe pass (and so prompt.json) and the source is recorded on the creative; the image may then be omitted. Use `--avatar <handle>` by default whenever the ad needs a person: inspect `baker avatars list`, choose a ready actor who fits the buyer, or create one with explicit identity and setting. Description-only casting remains available when explicitly requested.",
+  args: {
+    file: {
+      type: "positional",
+      required: false,
+      description: "Path or http(s) URL to the reference image. Optional with --source-ad-id: the library's picture is used."
+    },
+    "source-ad-id": { type: "string", required: false, description: SOURCE_AD_ID_DESCRIPTION },
+    spec: {
+      type: "string",
+      required: false,
+      description: "Start from an ad spec (a prompt.json) instead of a reference picture: no describe pass, no source. `baker creatives make` writes one from an idea when no proven ad fits. Needs --slug."
+    },
+    "source-platform": {
+      type: "string",
+      required: false,
+      description: SOURCE_PLATFORM_DESCRIPTION,
+      enum: [...LIBRARY_PLATFORMS]
+    },
+    "source-advertiser-id": { type: "string", required: false, description: SOURCE_ADVERTISER_ID_DESCRIPTION },
+    context: {
+      type: "string",
+      required: false,
+      description: "Known provenance (advertiser, category, market, their brand palette) to ground the describe pass"
+    },
+    slug: {
+      type: "string",
+      required: false,
+      description: "Creative slug: writes src/creatives/<slug>/<slug>.canvas.json, prompt.json and _definition.md"
+    },
+    title: { type: "string", required: false, description: "Creative title for _definition.md (default: title-cased slug)" },
+    platform: { type: "string", required: false, description: RETIRED_PLATFORM_DESCRIPTION },
+    advertiser: {
+      type: "string",
+      required: false,
+      description: "Source advertiser name for _definition.md (default: the library ad's advertiser when --source-ad-id is given)"
+    },
+    placements: { type: "string", required: false, description: RETIRED_PLACEMENTS_DESCRIPTION },
+    platforms: { type: "string", required: false, description: PLATFORMS_DESCRIPTION },
+    formats: { type: "string", required: false, description: FORMATS_DESCRIPTION },
+    aspect: {
+      type: "string",
+      required: false,
+      description: "Retired: adds this size when the platforms show it (never narrows). For an ad-hoc canvas with no platform, its one size."
+    },
+    "target-adset": { type: "string", required: false, description: TARGET_ADSET_DESCRIPTION },
+    "viewer-temperature": {
+      type: "string",
+      required: false,
+      description: VIEWER_TEMPERATURE_DESCRIPTION,
+      enum: [...VIEWER_TEMPERATURE_VALUES]
+    },
+    "viewer-knows": { type: "string", required: false, description: VIEWER_KNOWS_DESCRIPTION },
+    "viewer-placements": { type: "string", required: false, description: VIEWER_PLACEMENTS_DESCRIPTION },
+    takes: {
+      type: "string",
+      required: false,
+      description: "Variants of the finished ad rendered (one request each) and judged, 1-3 (default 3). 1 skips the judge."
+    },
+    avatar: {
+      type: "string",
+      required: false,
+      description: "Cast company avatars as the ad's people, comma-separated in detection order (`marta` or `marta,joan`)"
+    },
+    out: { type: "string", required: false, description: "Output canvas path (default <image-dir>/static-ad.canvas.json)" },
+    "describe-model": { type: "string", required: false, description: "Override the image_describe model id" },
+    "select-model": { type: "string", required: false, description: "Override the element-selection text_generate model id" },
+    "gen-model": { type: "string", required: false, description: "Override the image_generate model id" }
+  }
+});
+async function lookupReference(args) {
+  const adId = args["source-ad-id"] ? String(args["source-ad-id"]).trim() : "";
+  if (!adId) return { status: "none" };
+  const platformResult = resolveSourcePlatform(args["source-platform"] ? String(args["source-platform"]) : void 0);
+  if (!platformResult.ok) return fail("invalid_source_platform", platformResult.message);
+  const platform = platformResult.platform;
+  const advertiserId = args["source-advertiser-id"] ? String(args["source-advertiser-id"]).trim() : void 0;
+  try {
+    const ad = await fetchLibraryReference(adId, platform);
+    const refusal = notADesignReference(platform, adId, ad);
+    if (refusal) return { status: "refused", refusal };
+    return {
+      status: "grounded",
+      reference: libraryReferenceBlock(ad, { adId, platform, advertiserId }),
+      mediaUrl: ad.media_url ?? void 0
+    };
+  } catch (e) {
+    return { status: "unavailable", adId, platform, message: e instanceof Error ? e.message : String(e) };
+  }
+}
+async function scaffoldFromSpec(args, slug) {
+  if (!slug) return fail("missing_slug", "--spec needs --slug: an ad started from a spec is a creative.");
+  const specPath = path.resolve(process.cwd(), String(args.spec));
+  let started;
+  try {
+    started = readAdSpec(JSON.parse(await readFile(specPath, "utf8")));
+  } catch (e) {
+    return fail("invalid_spec", `${specPath} is not an ad spec: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const outPath = path.join(process.cwd(), "src", "creatives", slug, `${slug}.canvas.json`);
+  const dir = path.dirname(outPath);
+  const blueprintPath = path.join(dir, "prompt.json");
+  const definitionPath = path.join(dir, "_definition.md");
+  const existingDefinition = await fileExists(definitionPath) ? await readFile(definitionPath, "utf8") : null;
+  const delivery = await deliveryOrFail(args, existingDefinition, true);
+  const who = await scaffoldViewer(args, existingDefinition, liveViewerLookups(process.cwd()).adSetViewer);
+  if (!who.ok) return fail("invalid_viewer", who.message);
+  const avatars = await resolveCastAvatars(args.avatar);
+  if ("error" in avatars) return fail("avatar", avatars.error);
+  const persona = existingDefinition?.match(/^persona:\s*"?([^"\n]+)"?\s*$/m)?.[1] ?? started.viewer?.who;
+  const cast = castOnIdeaSpec(started, avatars.avatars, persona);
+  await mkdir(dir, { recursive: true });
+  const workspaceRoot = await findBrandRoot(dir) ?? process.cwd();
+  const found = await withClientLogo(workspaceRoot, await readStaticBrandKit(workspaceRoot), () => readStaticBrandKit(workspaceRoot));
+  const kit = found.kit;
+  const market = who.viewer?.market ?? marketFromCompanyDoc(await readFile(path.join(workspaceRoot, "COMPANY.md"), "utf8").catch(() => null));
+  const brand = brandBlock(kit);
+  const font = await brandFace(workspaceRoot, kit, (file) => toCanvasRelative(dir, file));
+  const genModel = pickImageModel(conceptClassOf(cast.spec), "generate");
+  const masterShape = masterShapeArg(args["master-shape"]);
+  if (masterShape === null) return fail("invalid_master_shape", `--master-shape is ${SCAFFOLD_SHAPES.join(" or ")}`);
+  const logo = await placedLogo(kit.logo, (file) => toCanvasRelative(dir, file));
+  const opts = {
+    genModel,
+    blueprintPath: "./prompt.json",
+    ...masterShape ? { masterShape } : {},
+    ...delivery ? { delivery } : {},
+    ...who.adPlacements ? { adPlacements: who.adPlacements } : {},
+    brand: { logoPath: kit.logo ? toCanvasRelative(dir, kit.logo) : void 0, ...logo.brand, ...font ? { font } : {} },
+    ...logo.opts
+  };
+  const report = staticAdReport({}, cast.elements, { ...opts, spec: cast.spec });
+  const spec = {
+    ...cast.spec,
+    ...brand ? { brand: { ...brand, ...cast.spec.brand } } : {},
+    formats: report.output_formats,
+    logo: Boolean(kit.logo),
+    ...market ? { viewer: { ...cast.spec.viewer ?? { who: "the people this ad is for" }, market } } : {}
+  };
+  await writeFile(blueprintPath, `${JSON.stringify(spec, null, 2)}
+`, "utf8");
+  const canvas = scaffoldStaticAd({}, cast.elements, { ...opts, spec });
+  const validation = await validateScaffoldedStaticAd(canvas, dir);
+  if (validation.blocking.length > 0) return fail("validation", validation.blocking.map((i) => i.message).join("; "));
+  await writeFile(outPath, `${JSON.stringify(canvas, null, 2)}
+`, "utf8");
+  const title = args.title ? String(args.title) : titleFromSlug(slug);
+  const recorded = who.record ? { targetAdSet: who.targetAdSet, viewer: who.viewer } : {};
+  const where = delivery ? deliveryDefinitionFields(delivery) : void 0;
+  if (existingDefinition === null) {
+    const formats = resolveFormatList(report.output_formats);
+    await writeFile(definitionPath, buildCreativeDefinition({ title, kind: "static", ...where, formats, ...recorded }), "utf8");
+  } else if (where) {
+    await writeFile(definitionPath, setDefinitionDelivery(existingDefinition, where), "utf8");
+  }
+  await syncCreativeDefinitionBestEffort({
+    slug,
+    title,
+    ...where ? { platform: where.platform } : {},
+    ...await readDefinitionPlatforms(outPath),
+    formats: resolveFormatList(report.output_formats),
+    canvas,
+    sourceSha: await computeSourceSha(outPath)
+  });
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        ok: true,
+        canvas_path: outPath,
+        prompt_path: blueprintPath,
+        definition_path: definitionPath,
+        output: canvas.output,
+        hints: [...who.notes, ...delivery?.notes ?? [], ...found.hint ? [found.hint] : [], ...validation.hints],
+        ...viewerOutput(who),
+        ...deliveryOutput(delivery),
+        output_formats: report.output_formats,
+        master_shape: report.master_shape,
+        stats: { total_nodes: canvas.nodes.length, describe_credits_spent: 0, run_estimated_credits: validation.estimatedCredits }
+      },
+      null,
+      2
+    )}
+`
+  );
+}
+var scaffoldStaticAdCommand = defineCommand({
+  meta: {
+    name: "scaffold-static-ad",
+    description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (read into prompt.json, the ad spec you rewrite) and an AI selection of the image's MAIN identity elements \u2014 then scaffolds a canvas on which the image model renders the FINISHED ad: up to three variants, one request each, from a brief compiled from prompt.json, the copy quoted verbatim, the brand's typeface shown as a specimen and the logo from src/brand/logos/ as a reference (only when prompt.json has \"logo\": true). A prefilter drops variants whose words or placement fail the checks, and a judge compares the rest pairwise against the brief; the chosen picture is delivered at the platform's lead size (4:5 on Meta, 1:1 on LinkedIn) and every other placement format is that ad re-laid out for its own frame by one image request, with the chosen picture as the reference: the same words, people, product and logo, re-scaled for the frame, never cut or shrunk onto a background. The run reads every word back and refuses to call the ad ready when one is off. No copy means the picture is the ad. Where the ad runs decides its sizes: pass --platforms (meta \u2192 4:5 + 9:16, linkedin \u2192 1:1, tiktok \u2192 9:16), from the person's request; a creative with none is refused. Edit prompt.json and drop the real assets, then `baker canvas run` it. A person is cast from a suitable company Avatar by default: pass `--avatar <handle>` (`baker avatars list`), or create one with explicit identity and buyer setting. A description-only one-off remains available when explicitly requested. Never cast a stranger from a searched photo. A reference from the library: pass `--source-ad-id <ad_id> --source-platform <platform>` so its structured read grounds the describe pass and the source is recorded on the creative."
+  },
+  args: {
+    file: {
+      type: "positional",
+      required: false,
+      description: "Path or http(s) URL to the source/inspiration image (optional with --source-ad-id)"
+    },
+    "source-ad-id": { type: "string", description: SOURCE_AD_ID_DESCRIPTION },
+    spec: {
+      type: "string",
+      description: "Start from an ad spec (a prompt.json) instead of a reference picture: no describe pass, no source. `baker creatives make` writes one from an idea when no proven ad fits. Needs --slug."
+    },
+    "source-platform": { type: "string", description: SOURCE_PLATFORM_DESCRIPTION },
+    "source-advertiser-id": { type: "string", description: SOURCE_ADVERTISER_ID_DESCRIPTION },
+    context: { type: "string", description: "Known provenance (advertiser, category, market) to ground the describe" },
+    out: { type: "string", description: "Output canvas path (default <image-dir>/static-ad.canvas.json)" },
+    slug: {
+      type: "string",
+      description: "Creative slug \u2014 writes the canvas to src/creatives/<slug>/<slug>.canvas.json (repo convention)"
+    },
+    title: { type: "string", description: "Creative title for _definition.md (default: title-cased slug)" },
+    platform: { type: "string", description: RETIRED_PLATFORM_DESCRIPTION },
+    advertiser: {
+      type: "string",
+      description: "Source advertiser recorded in _definition.md (default: the library ad's advertiser)"
+    },
+    "describe-model": { type: "string", description: "Override the image_describe model id" },
+    "select-model": { type: "string", description: "Override the text_generate model id for element selection" },
+    "gen-model": { type: "string", description: "Override the image_generate model id" },
+    aspect: {
+      type: "string",
+      description: "Retired: adds this size when the platforms show it (never narrows). For an ad-hoc canvas with no platform, its one size."
+    },
+    "target-adset": { type: "string", description: TARGET_ADSET_DESCRIPTION },
+    "viewer-temperature": { type: "string", description: VIEWER_TEMPERATURE_DESCRIPTION },
+    "viewer-knows": { type: "string", description: VIEWER_KNOWS_DESCRIPTION },
+    "viewer-placements": { type: "string", description: VIEWER_PLACEMENTS_DESCRIPTION },
+    placements: { type: "string", description: RETIRED_PLACEMENTS_DESCRIPTION },
+    platforms: { type: "string", description: PLATFORMS_DESCRIPTION },
+    formats: { type: "string", description: FORMATS_DESCRIPTION },
+    takes: {
+      type: "string",
+      description: "Variants of the finished ad to render (one request each) and judge, 1-3 (default 3). 1 skips the judge."
+    },
+    "master-shape": {
+      type: "string",
+      description: `${OPERATOR} How the sizes are made: plate (each variant's picture drawn without the ad's words, every size cut from the chosen one and its words set for it) or relayout (each size re-laid out from the chosen ad). Default: routed by the ad's kind, plate for a photo-led ad and relayout for a designed, chat, screenshot or interface one (the output's master_shape says why). On an existing creative, plate moves it onto one picture, keeping its approved size.`
+    },
+    avatar: {
+      type: "string",
+      description: "Cast company avatars as the ad's people \u2014 preferred whenever an ad needs an actor, including a single ad. Choose a ready avatar who fits the buyer, or create one with explicit identity and setting. One handle, or several comma-separated in the order the people were detected (`--avatar marta` / `--avatar marta,joan`). Each person slot grounds on that avatar's identity sheet and prompt.json describes them in the avatar's own words, so the ad shows the company's cast instead of the source ad's. `baker avatars list` shows who there is; checked before anything is billed."
+    }
+  },
+  async run({ args }) {
+    const slug = args.slug ? String(args.slug) : void 0;
+    if (slug && !isValidScaffoldSlug(slug)) {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "invalid_slug", message: "--slug must be lowercase kebab (a-z, 0-9, hyphens), max 100 chars" } }, null, 2)}
+`
+      );
+      process.exit(2);
+    }
+    if (args.spec) return scaffoldFromSpec(args, slug);
+    const lookup = await lookupReference(args);
+    if (lookup.status === "refused") return fail("not_a_design_reference", lookup.refusal.message, lookup.refusal.fix);
+    if (lookup.status === "unavailable") {
+      process.stderr.write(
+        `[warn] winners-library ad ${lookup.adId} (${lookup.platform}) could not be read (${lookup.message}); scaffolding without its structured read
+`
+      );
+    }
+    const reference = lookup.status === "grounded" ? lookup.reference : void 0;
+    const fileArg = args.file ? String(args.file) : void 0;
+    const sourceFile = fileArg ?? (lookup.status === "grounded" ? lookup.mediaUrl : void 0);
+    if (!sourceFile) {
+      if (lookup.status === "none") return fail("missing_source", "Pass the reference image, or --source-ad-id <ad_id> to use a library ad.");
+      if (lookup.status === "unavailable") return fail("source_unavailable", `No image given and the library ad could not be read (${lookup.message}).`);
+      return fail("source_unavailable", `The library holds no picture for ad ${reference?.ad_id}; pass the image.`);
+    }
+    const { imageIsUrl, imageSource, outPath, blueprintPath, definitionPath, referencesDir } = resolveScaffoldStaticAdPaths(sourceFile, args.out ? String(args.out) : void 0, process.cwd(), slug);
+    const existingDefinition = definitionPath && await fileExists(definitionPath) ? await readFile(definitionPath, "utf8") : null;
+    const delivery = await deliveryOrFail(args, existingDefinition, definitionPath !== null);
+    const who = await scaffoldViewer(args, existingDefinition, liveViewerLookups(process.cwd()).adSetViewer);
+    if (!who.ok) return fail("invalid_viewer", who.message);
+    const fitRoot = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    const fit = reference || lookup.status === "unavailable" ? await readCachedFit(fitRoot, reference?.platform ?? (lookup.status === "unavailable" ? lookup.platform : "meta"), reference?.ad_id ?? (lookup.status === "unavailable" ? lookup.adId : "")) : null;
+    const fitProblems = fit ? fitHints(fit, reference?.ad_id ?? "").filter((h) => h.startsWith("Pick another reference")) : [];
+    if (fitProblems.length > 0) return fail("concept_does_not_fit", fitProblems.join(" "));
+    await mkdir(path.dirname(outPath), { recursive: true });
+    let models;
+    try {
+      models = resolveModels(args);
+    } catch (e) {
+      return fail("unknown_model", e instanceof Error ? e.message : String(e));
+    }
+    const { describeModel, selectModel } = models;
+    const cast = await resolveCastAvatars(args.avatar);
+    if ("error" in cast) return fail("avatar", cast.error);
+    let durableSourceUrl;
+    if (referencesDir) {
+      const client = buildBackendClient();
+      if (client) {
+        try {
+          durableSourceUrl = await uploadSourceAsReference(imageSource, imageIsUrl, client);
+        } catch (e) {
+          return fail("source_unavailable", e instanceof Error ? e.message : String(e));
+        }
+      }
+    }
+    const describeCanvas = buildDescribeCanvas(
+      durableSourceUrl ?? imageSource,
+      durableSourceUrl !== void 0 || imageIsUrl,
+      describeModel,
+      selectModel,
+      referenceDescribeContext(reference, args.context ? String(args.context) : void 0)
+    );
+    const shared = reference && sharesLibraryRead(args, lookup.status === "grounded") ? await sharedLibraryRead(reference) : null;
+    const vision = shared ?? await runVisionPasses(describeCanvas);
+    const { creditsSpent } = vision;
+    const blueprint = mergeReferenceIntoBlueprint(vision.blueprint, reference);
+    const persona = existingDefinition?.match(/^persona:\s*"?([^"\n]+)"?\s*$/m)?.[1];
+    const elements = castAvatarsOnStaticElements(vision.elements, cast.avatars, persona);
+    const uncast = staticAvatarsNotCast(elements, cast.handles);
+    const canvasDir = path.dirname(outPath);
+    const workspaceRoot = await findBrandRoot(canvasDir) ?? process.cwd();
+    const found = await withClientLogo(workspaceRoot, await readStaticBrandKit(workspaceRoot), () => readStaticBrandKit(workspaceRoot));
+    const kit = found.kit;
+    const market = who.viewer?.market ?? marketFromCompanyDoc(await readFile(path.join(workspaceRoot, "COMPANY.md"), "utf8").catch(() => null));
+    const brand = brandBlock(kit);
+    let canvasImagePath = imageSource;
+    let canvasImageIsUrl = imageIsUrl;
+    let canvasBlueprintPath = blueprintPath;
+    if (referencesDir) {
+      canvasBlueprintPath = "./prompt.json";
+      if (durableSourceUrl) {
+        canvasImagePath = durableSourceUrl;
+        canvasImageIsUrl = true;
+      }
+    }
+    const where = delivery ? deliveryDefinitionFields(delivery) : void 0;
+    const relative = (file) => file ? toCanvasRelative(canvasDir, file) : void 0;
+    const takes = args.takes !== void 0 ? Number.parseInt(String(args.takes), 10) : void 0;
+    if (takes !== void 0 && !(takes >= 1 && takes <= 3)) return fail("invalid_takes", "--takes must be 1, 2 or 3");
+    const masterShape = masterShapeArg(args["master-shape"]);
+    if (masterShape === null) return fail("invalid_master_shape", `--master-shape is ${SCAFFOLD_SHAPES.join(" or ")}`);
+    const font = await brandFace(workspaceRoot, kit, (file) => toCanvasRelative(canvasDir, file));
+    const logo = await placedLogo(kit.logo, (file) => toCanvasRelative(canvasDir, file));
+    const genModel = models.genModel ?? pickImageModel(conceptClassOf(staticAdSpec(blueprint, elements)), "generate");
+    const opts = {
+      genModel,
+      imagePath: canvasImagePath,
+      imageIsUrl: canvasImageIsUrl,
+      blueprintPath: canvasBlueprintPath,
+      aspectRatio: args.aspect ? String(args.aspect) : void 0,
+      ...delivery ? { delivery } : {},
+      ...who.adPlacements ? { adPlacements: who.adPlacements } : {},
+      brand: { logoPath: relative(kit.logo), ...logo.brand, ...font ? { font } : {} },
+      ...logo.opts,
+      takes,
+      ...masterShape ? { masterShape } : {}
+    };
+    let canvas;
+    let report;
+    let conceptNotes = [];
+    try {
+      report = staticAdReport(blueprint, elements, { ...opts, spec: staticAdSpec(blueprint, elements, { logo: Boolean(kit.logo) }) });
+      const spec = staticAdSpec(blueprint, elements, {
+        brand,
+        formats: report.output_formats,
+        logo: Boolean(kit.logo),
+        ...fit ? { fit: conceptFromFit(fit, reference?.ad_id ?? "") } : {},
+        ...market ? { market } : {}
+      });
+      await writeFile(blueprintPath, `${JSON.stringify(spec, null, 2)}
+`, "utf8");
+      conceptNotes = conceptProblems(spec).map(
+        (p) => `CONCEPT: ${p} Then \`baker canvas run\`; until then it refuses to render.`
+      );
+      if (!fit && reference) {
+        conceptNotes.push(noFitNote(reference));
+      }
+      canvas = scaffoldStaticAd(blueprint, elements, { ...opts, spec });
+    } catch (e) {
+      return fail("scaffold", e instanceof Error ? e.message : String(e));
+    }
+    const validation = await validateScaffoldedStaticAd(canvas, path.dirname(outPath));
+    if (validation.blocking.length > 0) {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.blocking } }, null, 2)}
+`
+      );
+      process.exit(2);
+    }
+    await writeFile(outPath, `${JSON.stringify(canvas, null, 2)}
+`, "utf8");
+    const sourceFields = reference ? {
+      sourceAdId: reference.ad_id,
+      sourcePlatform: reference.platform,
+      ...reference.advertiser_id ? { sourceAdvertiserId: reference.advertiser_id } : {}
+    } : lookup.status === "unavailable" ? {
+      sourceAdId: lookup.adId,
+      sourcePlatform: lookup.platform,
+      ...args["source-advertiser-id"] ? { sourceAdvertiserId: String(args["source-advertiser-id"]).trim() } : {}
+    } : {};
+    const recorded = who.record ? { targetAdSet: who.targetAdSet, viewer: who.viewer } : {};
+    const sourceAdvertiser = args.advertiser ? String(args.advertiser) : reference?.advertiser;
+    const sourceReferenceUrl = durableSourceUrl ?? (imageIsUrl ? imageSource : void 0);
+    const rebased = existingDefinition !== null && sourceFields.sourceAdId && sourceFields.sourcePlatform ? rebasedDefinition(existingDefinition, {
+      ...sourceFields,
+      sourceAdId: sourceFields.sourceAdId,
+      sourcePlatform: sourceFields.sourcePlatform,
+      ...sourceAdvertiser ? { sourceAdvertiser } : {},
+      ...sourceReferenceUrl ? { sourceReferenceUrl } : {}
+    }) : existingDefinition;
+    if (definitionPath && rebased !== null && (who.record || where || rebased !== existingDefinition)) {
+      const viewed = who.record ? setDefinitionViewer(rebased, recorded) : rebased;
+      await writeFile(definitionPath, where ? setDefinitionDelivery(viewed, where) : viewed, "utf8");
+    }
+    if (definitionPath && existingDefinition === null) {
+      await writeFile(
+        definitionPath,
+        buildCreativeDefinition({
+          title: args.title ? String(args.title) : titleFromSlug(slug ?? ""),
+          kind: "static",
+          ...where,
+          formats: resolveFormatList(report.output_formats),
+          sourceReferenceUrl: durableSourceUrl ?? (imageIsUrl ? imageSource : void 0),
+          sourceAdvertiser: args.advertiser ? String(args.advertiser) : reference?.advertiser ?? (args.context ? String(args.context) : void 0),
+          ...sourceFields,
+          sourceKind: "image",
+          ...recorded,
+          description: describeBlueprintIntent(blueprint)
+        }),
+        "utf8"
+      );
+    }
+    if (slug) {
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: args.title ? String(args.title) : titleFromSlug(slug),
+        ...where ? { platform: where.platform } : {},
+        ...await readDefinitionPlatforms(outPath),
+        formats: resolveFormatList(report.output_formats),
+        sourceReferenceUrl: durableSourceUrl ?? (imageIsUrl ? imageSource : void 0),
+        ...sourceFields,
+        canvas,
+        sourceSha: await computeSourceSha(outPath)
+      });
+    }
+    const hints = [
+      ...who.notes,
+      ...delivery?.notes ?? [],
+      ...lookup.status === "unavailable" ? [
+        `REFERENCE NOT READ: the winners library could not return ad ${lookup.adId} (${lookup.message}). prompt.json is read from the picture alone and has no \`reference\` block; the source ids are still recorded. Check the ad id and platform, or continue from the picture.`
+      ] : [],
+      ...uncast.length ? [
+        `NOT CAST: ${uncast.map((h) => `\`${h}\``).join(", ")} \u2014 the element selection found fewer people than avatars passed, so ${uncast.length === 1 ? "this avatar plays" : "these avatars play"} nobody in this ad. Tell the user who is cast and who is not.`
+      ] : [],
+      ...found.hint ? [found.hint] : [],
+      ...validation.hints,
+      ...conceptNotes,
+      ...report.describe_gaps.map(
+        (gap) => gap === "winning_mechanisms" ? "The describe pass named no winning mechanism. Look at the source ad, add a `mechanism` entry to prompt.json ({ device, why_it_works }) and rebuild that device for our brand; a rewrite without it keeps the look and loses what made the ad work." : "The describe pass recorded no typefaces. The designed lines are set in the brand's font when one loads (src/brand/fonts/, tokens.json or BRAND.md); with none, name our face in prompt.json's `brand.typeface` (for example \"a heavy geometric sans\"), or they are set in a plain sans."
+      )
+    ];
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          canvas_path: outPath,
+          prompt_path: blueprintPath,
+          definition_path: definitionPath ?? void 0,
+          source_reference: durableSourceUrl ?? void 0,
+          ...reference ? {
+            reference: {
+              ad_id: reference.ad_id,
+              platform: reference.platform,
+              advertiser_id: reference.advertiser_id,
+              format_pattern: reference.format_pattern,
+              mechanism: reference.message.mechanism
+            }
+          } : {},
+          output: canvas.output,
+          ...hints.length ? { hints } : {},
+          models: { describe: describeModel, select: selectModel, gen: opts.genModel },
+          aspect_ratio: report.aspect_ratio,
+          ...deliveryOutput(delivery),
+          ...viewerOutput(who),
+          output_formats: report.output_formats,
+          // As the canvas records it: its spec carries the fit's concept, which the report's does not.
+          master_shape: recordedShape(canvas) ?? report.master_shape,
+          stats: {
+            total_nodes: canvas.nodes.length,
+            describe_credits_spent: creditsSpent,
+            run_estimated_credits: validation.estimatedCredits
+          },
+          checklist: {
+            edit_prompt: `Edit ${path.basename(blueprintPath)}: it is the ad spec, read from your image, to rewrite into the ad you want. \`viewer\` (who sees it and what they already know), \`message\` (the one thing it tells them), \`copy\` (each line, \`in_scene\` or \`designed\`), \`scene\`, \`references\` (one picture each, by role), \`colors\` (each tied to an object, from the brand) and an optional \`direction\`. You never write a model prompt: every render prompt is compiled from this file and shown on its node.${reference ? " Its `reference` block is the library's read of the source ad (container, layout, mechanism, offer, text blocks): keep it as the account of why the ad won, and rebuild it for our brand." : ""}`,
+            mechanism: report.winning_mechanisms,
+            rebuild_the_mechanism: "`mechanism` is WHY the source ad works. Rebuild each device for our brand in prompt.json's copy and scene (a rhyme stays a rhyme in our words, a before/after stays a before/after of our product); never copy the source's literal copy.",
+            assets_to_supply: report.elements,
+            summary: report.summary,
+            text: staticTextNote(report),
+            font: report.font,
+            in_scene_text: report.in_scene_text,
+            logo: report.logo.why,
+            takes: report.takes === 1 ? "1 finished ad is rendered and used as it is (no judge)." : `${report.takes} variants of the finished ad are rendered, one request each on its own direction. A prefilter drops any whose words or placement fail the checks, and the judge compares the rest pairwise against the brief (words, picture, space, one idea, the brief itself, brand); the winner becomes the ad and the others stay in the run as options the person can switch to (\`baker canvas run --use-variant\`).`,
+            pictures: "The reference's own people, products, animals and badges are not slots to fill: they are the source's world. Cast a person from a suitable ready company Avatar by default (--avatar <handle>); create one from the buyer context if none fits. A description-only one-off is available when explicitly requested; never use a stranger's found photo. To show our own product or another picture, add it to prompt.json's `references` with its `image` (a path from this folder, or a URL): every run wires it.",
+            formats: staticFormatsNote(report, opts.genModel, delivery),
+            viewer: viewerNote(who),
+            note: `Populate as you go: for each [TODO] ingest slot, source its real asset and wire it into the slot right away, one at a time. The logo is optional and never a slot to fill: it is given to the model only when prompt.json has \`"logo": true\` and src/brand/logos/ has the real file; never fetch or draw a stand-in. When every slot is filled, \`baker canvas validate\` then \`baker canvas run\`. Running generates billed images: it is not free.`
+          }
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+});
+async function placedLogo(file, relative) {
+  if (!file) return { brand: {}, opts: {} };
+  const read = await readLogoFile(file);
+  if (!read) return { brand: {}, opts: { logoComposite: false } };
+  return {
+    brand: {
+      logoAspect: read.aspect,
+      ...read.colourways.length > 0 ? { logoColourways: read.colourways.map(relative) } : {}
+    },
+    opts: {}
+  };
+}
+export {
+  buildDescribeCanvas,
+  lookupReference,
+  noFitNote,
+  scaffoldStaticAdCommand,
+  sharesLibraryRead,
+  uploadSourceAsReference,
+  validateScaffoldedStaticAd
+};
+//# sourceMappingURL=scaffold-static-ad-CRN5XZIZ.js.map