@koda-sl/baker-cli 0.408.0 → 0.409.0

package/dist/cli.js

@@ -97,7 +97,7 @@ import {
   withoutCastName,
   wordCount,
   ytDlpBlockSignal
-} from "./chunk-KMCVSEGU.js";
+} from "./chunk-QWRXQ2UC.js";
 import {
   NAME_CONTAINS_ARG,
   csvOrJson,
@@ -108,7 +108,7 @@ import {
   resolveEffectiveStatus,
   statusFilterHints,
   todayIso
-} from "./chunk-3ZN2DUBU.js";
+} from "./chunk-ZIOW64BL.js";
 import {
   buildQueryCacheKey,
   cacheGet,
@@ -124,19 +124,19 @@ import {
   writeAdsJson,
   writeAdsOutput,
   writeJsonEnvelope
-} from "./chunk-X37GPJ54.js";
+} from "./chunk-VKWHVMMD.js";
 import {
   ApiError,
   apiGet,
   apiGetWithHeaders,
   apiPost,
   validateConvexId
-} from "./chunk-WQE4SRLY.js";
+} from "./chunk-S5BY45H7.js";
 import {
   installExitRecord,
   installStreamTaps,
   logInvocation
-} from "./chunk-5X5LUMVV.js";
+} from "./chunk-ISJOVAJP.js";
 import {
   __commonJS,
   __esm,
@@ -171,7 +171,7 @@ import {
   winningAdNormalizer,
   writeJson,
   writeOutput
-} from "./chunk-N72QYDJY.js";
+} from "./chunk-ISCXDKWB.js";
 
 // ../../node_modules/.pnpm/i18n-iso-countries@7.14.0/node_modules/i18n-iso-countries/langs/af.json
 var require_af = __commonJS({
@@ -21715,7 +21715,7 @@ var require_entry_node = __commonJS({
 });
 
 // src/cli.ts
-import { defineCommand as defineCommand280, runMain } from "citty";
+import { defineCommand as defineCommand278, runMain } from "citty";
 
 // src/cache-flag.ts
 var NO_CACHE_ARG = {
@@ -22118,6 +22118,7 @@ var validatedHardFiltersSchema = winnersHardFiltersSchema.extend({
   first_seen_after: firstSeenBoundSchema.optional(),
   first_seen_before: firstSeenBoundSchema.optional()
 });
+var winnersSortSchema = z2.enum(["winner", "longest_running", "newest"]);
 var winnersSearchFields = z2.object({
   free_text_query: z2.string().max(500).optional(),
   ref_ad_id: z2.string().optional(),
@@ -22133,6 +22134,10 @@ var winnersSearchFields = z2.object({
   // One page picked for variety (different brands, containers and hooks)
   // instead of rank order: a reference set for N concepts. Ignores offset.
   diverse: z2.boolean().optional(),
+  // The order of a browse (no query): by winner score (default), by how long
+  // the ad has run, or by when it was first seen. A query ranks by relevance
+  // blended with winner score, so `sort` only means something without one.
+  sort: winnersSortSchema.optional(),
   hard_filters: winnersHardFiltersSchema.optional(),
   // `score_breakdown` surfaces the "why it ranked" panel; facets drive the
   // filter rail. thumbnails/full_dna_url are opt-in extras.
@@ -22140,9 +22145,11 @@ var winnersSearchFields = z2.object({
 });
 var hasSearchInput = (b) => b.free_text_query !== void 0 || b.ref_ad_id !== void 0 || b.hard_filters !== void 0;
 var SEARCH_INPUT_MESSAGE = "Provide free_text_query, ref_ad_id, or hard_filters";
-var winnersSearchRequestSchema = winnersSearchFields.refine(hasSearchInput, { message: SEARCH_INPUT_MESSAGE });
 var winnerSearchScopeSchema = z2.enum(["all", "followed", "followed-first"]);
-var scopedWinnersSearchRequestSchema = winnersSearchFields.extend({ scope: winnerSearchScopeSchema.optional(), hard_filters: validatedHardFiltersSchema.optional() }).refine(hasSearchInput, { message: SEARCH_INPUT_MESSAGE }).refine((b) => b.scope !== "followed-first" || !b.offset, {
+var scopedWinnersSearchRequestSchema = winnersSearchFields.extend({
+  scope: winnerSearchScopeSchema.default("followed-first"),
+  hard_filters: validatedHardFiltersSchema.optional()
+}).refine(hasSearchInput, { message: SEARCH_INPUT_MESSAGE }).refine((b) => b.scope !== "followed-first" || !b.offset, {
   message: "offset is not supported with scope followed-first; raise limit instead"
 });
 var winningAdDnaSchema = z2.object({
@@ -22231,7 +22238,12 @@ var winnersSearchResponseSchema = z2.object({
   country_coverage: z2.array(z2.object({ code: z2.string(), ads: z2.number() })).nullable()
 });
 var winnerSourceSchema = z2.enum(["followed", "library"]);
-var referenceUsesSchema = z2.object({ companies: z2.number(), ours: z2.boolean() });
+var referenceUsesSchema = z2.object({
+  companies: z2.number(),
+  ours: z2.boolean(),
+  approved: z2.number(),
+  rejected: z2.number()
+});
 var scopedWinningAdSchema = winningAdSchema.extend({
   source: winnerSourceSchema,
   baker_uses: referenceUsesSchema.optional()
@@ -22277,10 +22289,6 @@ var advertiserConvergenceSchema = z2.object({
   iteration_velocity_30d: z2.number().nullable(),
   last_refresh_completed_at: z2.string().nullable()
 });
-var resolvePreviewRequestSchema = z2.object({
-  input: z2.string().min(1),
-  platform: adLibraryPlatformSchema
-});
 var resolvePreviewSchema = z2.object({
   platform: adLibraryPlatformSchema,
   external_id: z2.string(),
@@ -22365,11 +22373,6 @@ var unfollowRequestSchema = z2.object({
   advertiser_id: z2.string().optional()
 });
 var unfollowResponseSchema = z2.object({ removed: z2.boolean() });
-var advertiserWinnersRequestSchema = z2.object({
-  advertiser_id: z2.string().min(1),
-  top: z2.number().int().min(1).max(100).optional(),
-  platform: adLibraryPlatformSchema.optional()
-});
 var advertiserWinnersResponseSchema = z2.object({
   advertiser_id: z2.string(),
   winners: z2.array(winningAdSchema)
@@ -22389,7 +22392,9 @@ var feedRequestSchema = z2.object({
   limit: z2.number().int().min(1).max(200).optional()
 });
 var feedResponseSchema = z2.object({
-  winners: z2.array(winningAdSchema),
+  // The feed only ever reads followed brands, so every winner is `followed`:
+  // the same `source` a scoped search carries, so the surfaces agree.
+  winners: z2.array(winningAdSchema.extend({ source: winnerSourceSchema })),
   // How many brands the company follows (regardless of the trim).
   following_count: z2.number(),
   // The advertiser ids actually queried (follows ∩ requested subset).
@@ -22398,39 +22403,6 @@ var feedResponseSchema = z2.object({
   // followed them yet.
   unknown_requested: z2.array(z2.string())
 });
-var briefRequestSchema = z2.object({
-  // Partial DNA describing the target creative (all optional); the service
-  // pulls its own strategically-similar references.
-  target_dna: z2.record(z2.string(), z2.unknown()).optional(),
-  k_reference_ads: z2.number().int().min(1).max(50).optional(),
-  notes: z2.string().optional()
-});
-var briefResponseSchema = z2.object({
-  brief_markdown: z2.string(),
-  reference_ad_ids: z2.array(z2.string())
-});
-var cohortSelectorSchema = z2.object({
-  hard_filters: winnersHardFiltersSchema.optional(),
-  ad_ids: z2.array(z2.string()).optional()
-});
-var patternsRequestSchema = z2.object({
-  cohort_a: cohortSelectorSchema,
-  cohort_b: cohortSelectorSchema,
-  top_n: z2.number().int().min(1).max(50).optional()
-});
-var patternDiscriminatorSchema = z2.object({
-  field: z2.string(),
-  method: z2.string(),
-  score: z2.number(),
-  direction: z2.enum(["favors_a", "favors_b"]),
-  top_values_a: z2.array(z2.string()).nullable(),
-  top_values_b: z2.array(z2.string()).nullable()
-});
-var patternsResponseSchema = z2.object({
-  cohort_a_size: z2.number(),
-  cohort_b_size: z2.number(),
-  discriminators: z2.array(patternDiscriminatorSchema)
-});
 var seedCatalogFieldSchema = z2.enum(["hook_archetype", "mechanism_type", "static_format_pattern"]);
 var seedCatalogRequestSchema = z2.object({
   field: seedCatalogFieldSchema,
@@ -35334,8 +35306,8 @@ var MEMBER_ARGS = {
   },
   country: { type: "string", description: "Country of phones written without a +code, e.g. ES" }
 };
-function membersFromArgs(args8, readFile42 = (path59) => readFileSync2(path59, "utf8")) {
-  const fromFile = typeof args8.file === "string" && args8.file ? membersFromFile(readFile42(args8.file)) : { emails: [], phones: [] };
+function membersFromArgs(args8, readFile43 = (path59) => readFileSync2(path59, "utf8")) {
+  const fromFile = typeof args8.file === "string" && args8.file ? membersFromFile(readFile43(args8.file)) : { emails: [], phones: [] };
   const given = [...csvArg(args8.emails) ?? [], ...fromFile.emails];
   const givenPhones = [...csvArg(args8.phones) ?? [], ...fromFile.phones];
   const members = hashedMembers({
@@ -53530,10 +53502,10 @@ Example: baker ads meta ads retag 120252158038400247 --url-tags "utm_source={{si
     }
   },
   run: async ({ args: args8 }) => {
-    const { apiPost: apiPost2 } = await import("./client-BPKOHQWA.js");
-    const { requireChatId: requireChatId2 } = await import("./env-B7V77K6K.js");
-    const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-5M2QPMKZ.js");
-    const { handleMetaError: handleMetaError2 } = await import("./shared-OEQKSDWO.js");
+    const { apiPost: apiPost2 } = await import("./client-AY6TPFQ4.js");
+    const { requireChatId: requireChatId2 } = await import("./env-CWEGTJF3.js");
+    const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-EPF3HHJ4.js");
+    const { handleMetaError: handleMetaError2 } = await import("./shared-53G34I3U.js");
     try {
       const accountId = bareAccountId2(args8);
       const urlTags = typeof args8["url-tags"] === "string" ? args8["url-tags"] : void 0;
@@ -53684,10 +53656,10 @@ function duplicateCommand2(entity, label) {
       replace: { type: "boolean", description: "Pause the original once the copy publishes" }
     },
     run: async ({ args: args8 }) => {
-      const { apiPost: apiPost2 } = await import("./client-BPKOHQWA.js");
-      const { requireChatId: requireChatId2 } = await import("./env-B7V77K6K.js");
-      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-5M2QPMKZ.js");
-      const { handleMetaError: handleMetaError2 } = await import("./shared-OEQKSDWO.js");
+      const { apiPost: apiPost2 } = await import("./client-AY6TPFQ4.js");
+      const { requireChatId: requireChatId2 } = await import("./env-CWEGTJF3.js");
+      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-EPF3HHJ4.js");
+      const { handleMetaError: handleMetaError2 } = await import("./shared-53G34I3U.js");
       try {
         const accountId = bareAccountId2(args8);
         const chatId = requireChatId2();
@@ -71574,7 +71546,7 @@ var rerunCommand = defineCommand132({
 });
 
 // src/commands/canvas/scaffold-static-ad.ts
-import { mkdir as mkdir8, readFile as readFile23, writeFile as writeFile12 } from "fs/promises";
+import { mkdir as mkdir8, readFile as readFile24, writeFile as writeFile12 } from "fs/promises";
 import path31 from "path";
 import { defineCommand as defineCommand134 } from "citty";
 
@@ -71915,6 +71887,7 @@ function fileExists(target2) {
 
 // src/commands/canvas/creative-definition.ts
 import path28 from "path";
+import { parseDocument as parseDocument2 } from "yaml";
 var PLATFORM_VALUES = ["meta", "google", "linkedin", "tiktok", "youtube", "x", "other"];
 var FORMAT_VALUES = ["1:1", "4:5", "9:16", "16:9", "1.91:1"];
 function titleFromSlug(slug) {
@@ -71953,6 +71926,9 @@ function buildCreativeDefinition(input) {
   lines.push(`status: ${input.status ?? "draft"}`);
   if (input.sourceReferenceUrl) lines.push(`sourceReferenceUrl: ${yamlScalar(input.sourceReferenceUrl)}`);
   if (input.sourceAdvertiser) lines.push(`sourceAdvertiser: ${yamlScalar(input.sourceAdvertiser)}`);
+  if (input.sourceAdvertiserId) lines.push(`sourceAdvertiserId: ${yamlScalar(input.sourceAdvertiserId)}`);
+  if (input.sourceAdId) lines.push(`sourceAdId: ${yamlScalar(input.sourceAdId)}`);
+  if (input.sourcePlatform) lines.push(`sourcePlatform: ${input.sourcePlatform}`);
   if (input.sourceKind) lines.push(`sourceKind: ${input.sourceKind}`);
   if (input.sourcePath) lines.push(`sourcePath: ${yamlScalar(input.sourcePath)}`);
   lines.push("---", "");
@@ -71960,6 +71936,19 @@ function buildCreativeDefinition(input) {
   lines.push("");
   return lines.join("\n");
 }
+var SOURCE_FIELD_KEYS = ["sourceAdId", "sourcePlatform", "sourceAdvertiserId"];
+function parseDefinitionSourceFields(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?\r?\n)?---/);
+  if (!match) return {};
+  const doc = parseDocument2(match[1] ?? "");
+  if (doc.errors.length > 0) return {};
+  const fields = {};
+  for (const key of SOURCE_FIELD_KEYS) {
+    const value2 = doc.get(key);
+    if (typeof value2 === "string" && value2.trim()) fields[key] = value2.trim();
+  }
+  return fields;
+}
 
 // src/commands/canvas/scaffold-static-ad-paths.ts
 import path29 from "path";
@@ -71981,7 +71970,7 @@ function isValidScaffoldSlug(slug) {
 }
 
 // src/commands/canvas/sync-definition.ts
-import { readdir as readdir11, stat as stat4 } from "fs/promises";
+import { readdir as readdir11, readFile as readFile23, stat as stat4 } from "fs/promises";
 import path30 from "path";
 import { defineCommand as defineCommand133 } from "citty";
 
@@ -72029,6 +72018,21 @@ function canvasToDefinitionGraph(canvas) {
 }
 
 // src/commands/canvas/sync-definition.ts
+function buildDefinitionSyncPayload(input, graph, chatId) {
+  const { canvas: _canvas, ...fields } = input;
+  return Object.fromEntries([
+    ...Object.entries(fields).filter(([, v]) => v !== void 0),
+    ["graph", graph],
+    ["chatId", chatId]
+  ]);
+}
+async function readDefinitionSourceFields(canvasPath) {
+  try {
+    return parseDefinitionSourceFields(await readFile23(path30.join(path30.dirname(canvasPath), "_definition.md"), "utf8"));
+  } catch {
+    return {};
+  }
+}
 async function syncCreativeDefinitionBestEffort(input) {
   const chatId = process.env.BAKER_CHAT_ID;
   if (!chatId) return;
@@ -72037,16 +72041,7 @@ async function syncCreativeDefinitionBestEffort(input) {
   try {
     const creds = requireCredentialsFromEnv();
     const client = new BackendClient2({ baseUrl: creds.url, apiKey: creds.apiKey });
-    await client.syncCreativeDefinition({
-      slug: input.slug,
-      title: input.title,
-      platform: input.platform,
-      formats: input.formats,
-      sourceReferenceUrl: input.sourceReferenceUrl,
-      graph,
-      sourceSha: input.sourceSha,
-      chatId
-    });
+    await client.syncCreativeDefinition(buildDefinitionSyncPayload(input, graph, chatId));
     process.stdout.write(`[definition] synced workflow graph (${graph.nodes.length} nodes) \u2014 view it in the dashboard
 `);
   } catch (e) {
@@ -72105,7 +72100,7 @@ var syncDefinitionCommand = defineCommand133({
     } catch {
       return;
     }
-    await syncCreativeDefinitionBestEffort({ slug, canvas, sourceSha });
+    await syncCreativeDefinitionBestEffort({ slug, canvas, sourceSha, ...await readDefinitionSourceFields(canvasPath) });
   }
 });
 
@@ -72138,6 +72133,117 @@ async function resolveCastAvatars(flag) {
   return { handles, avatars };
 }
 
+// src/commands/canvas/library-reference.ts
+var LIBRARY_PLATFORMS = ["meta", "linkedin", "tiktok"];
+function resolveSourcePlatform(flag) {
+  const value2 = flag?.trim();
+  if (!value2) return { ok: true, platform: "meta" };
+  if (LIBRARY_PLATFORMS.includes(value2)) return { ok: true, platform: value2 };
+  return {
+    ok: false,
+    message: `--source-platform "${value2}" is not a library platform. Use one of: ${LIBRARY_PLATFORMS.join(", ")}.`
+  };
+}
+async function fetchLibraryReference(adId, platform) {
+  const data = await apiGet("/api/ad-library/ad-content", { id: adId, platform });
+  if (!data?.ad) throw new Error(`the library returned no ad for ${adId} on ${platform}`);
+  return data.ad;
+}
+function filled(entries) {
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, v]) => v !== null && v !== void 0 && !(Array.isArray(v) && v.length === 0))
+  );
+}
+function libraryReferenceBlock(ad, ids2) {
+  const textBlocks = ad.on_screen_text.flatMap(
+    (o) => o.text ? [{ text: o.text, ...o.role ? { role: o.role } : {}, ...o.position ? { position: o.position } : {} }] : []
+  );
+  const advertiser = ad.advertiser ?? void 0;
+  const advertiserId = ids2.advertiserId ?? ad.advertiser_id ?? void 0;
+  return {
+    ad_id: ids2.adId,
+    platform: ids2.platform,
+    ...advertiser ? { advertiser } : {},
+    ...advertiserId ? { advertiser_id: advertiserId } : {},
+    ...ad.layout.format_pattern ? { format_pattern: ad.layout.format_pattern } : {},
+    layout: filled({
+      composition: ad.layout.composition,
+      focal_subject: ad.layout.focal_subject,
+      aspect_ratio: ad.layout.aspect_ratio,
+      background: ad.layout.background,
+      palette_mood: ad.layout.palette_mood,
+      colors: ad.layout.colors,
+      production: ad.layout.production,
+      aesthetic: ad.layout.aesthetic,
+      cta_in_image: ad.layout.cta_in_image,
+      markers: ad.layout.markers
+    }),
+    message: filled({
+      mechanism: ad.message.mechanism,
+      awareness: ad.message.awareness_stage,
+      sophistication: ad.message.sophistication,
+      angle: ad.angle,
+      hook_archetype: ad.hook_archetype,
+      pain_points: ad.message.pain_points,
+      desires: ad.message.desires,
+      value_props: ad.message.value_props,
+      objections_handled: ad.message.objections_handled,
+      proof: ad.message.proof,
+      risk_reversal: ad.message.risk_reversal
+    }),
+    offer: filled({
+      offer_type: ad.offer.offer_type,
+      pricing_model: ad.offer.pricing_model,
+      entry_price: ad.offer.entry_price,
+      no_credit_card: ad.offer.no_credit_card,
+      guarantee: ad.offer.guarantee,
+      guarantee_days: ad.offer.guarantee_days,
+      urgency: ad.offer.urgency,
+      bonus: ad.offer.bonus
+    }),
+    text_blocks: textBlocks,
+    copy: filled({ primary_text: ad.primary_text, headline: ad.headline, cta: ad.cta })
+  };
+}
+function referenceDescribeContext(reference, agentContext) {
+  const own = agentContext?.trim() || void 0;
+  if (!reference) return own;
+  const facts = [];
+  if (reference.advertiser) facts.push(`advertiser: ${reference.advertiser}`);
+  if (reference.format_pattern) facts.push(`container (format_pattern): ${reference.format_pattern}`);
+  if (typeof reference.layout.composition === "string") facts.push(`composition: ${reference.layout.composition}`);
+  if (typeof reference.message.mechanism === "string") facts.push(`persuasion mechanism: ${reference.message.mechanism}`);
+  if (typeof reference.message.awareness === "string") facts.push(`awareness stage: ${reference.message.awareness}`);
+  if (typeof reference.offer.offer_type === "string") facts.push(`offer: ${reference.offer.offer_type}`);
+  if (reference.text_blocks.length > 0) {
+    facts.push(
+      `text blocks: ${reference.text_blocks.map((b) => `"${b.text}"${b.role ? ` (${b.role})` : ""}`).join("; ")}`
+    );
+  }
+  const library = `The ads library has already read this ad: ${facts.join(". ")}. Your blueprint must agree with it on the container and the mechanism; refine and detail them, never contradict them, and transcribe the text blocks exactly.`;
+  return own ? `${own}. ${library}` : library;
+}
+function mergeReferenceIntoBlueprint(blueprint, reference) {
+  if (!reference || !blueprint || typeof blueprint !== "object" || Array.isArray(blueprint)) return blueprint;
+  const merged = { ...blueprint, reference };
+  if (winningMechanisms(blueprint).length === 0) {
+    const container = reference.format_pattern;
+    const mechanism = typeof reference.message.mechanism === "string" ? reference.message.mechanism : void 0;
+    const device = container && mechanism ? `${container} container carrying ${mechanism}` : container && `${container} container` || mechanism && `${mechanism} persuasion mechanism`;
+    if (device) {
+      merged.winning_mechanisms = [
+        {
+          kind: "structural",
+          device,
+          why_it_works: "The winners library recorded this ad as a winner on this container and persuasion mechanism.",
+          source: "library"
+        }
+      ];
+    }
+  }
+  return merged;
+}
+
 // src/commands/canvas/scaffold-static-ad.ts
 function toCanvasRelative2(canvasDir, file) {
   const rel = path31.relative(canvasDir, file).split(path31.sep).join("/");
@@ -72152,7 +72258,7 @@ async function uploadSourceAsReference(source, isUrl, client) {
       throw new Error(`failed to download source image (${e instanceof Error ? e.message : String(e)})`);
     }
   } else {
-    bytes = await readFile23(source);
+    bytes = await readFile24(source);
   }
   const safe = await toModelSafeImage(bytes);
   const sha2562 = sha256Hex(safe.bytes);
@@ -72292,13 +72398,102 @@ async function runVisionPasses(canvas) {
     return fail4("read_outputs", e instanceof Error ? e.message : String(e));
   }
 }
+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 SOURCE_PLATFORM_DESCRIPTION = `Which platform the library ad is on: ${LIBRARY_PLATFORMS.join("|")} (default meta).`;
+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 blueprint and the source is recorded on the creative; the image may then be omitted. `baker avatars list`, then `--avatar <handle>` when the image shows a person.",
+  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 },
+    "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: "Ad platform for _definition.md and the default placement set (meta|google|linkedin|tiktok|youtube|x|other; default meta)"
+    },
+    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: "Formats delivered: meta_feed|meta_feed_stories|meta_all|linkedin|google_demandgen|tiktok|youtube, or none for a single base ad (default from --platform)"
+    },
+    aspect: { type: "string", required: false, description: "Force the lead format (else inferred from the image)" },
+    takes: { type: "string", required: false, description: "Finished ads rendered and judged, 1-3 (default 3)" },
+    avatar: {
+      type: "string",
+      required: false,
+      description: "Cast company avatars as the ad's people, comma-separated in detection order (`marta` or `marta,joan`)"
+    },
+    "skip-actor-sheets": {
+      type: "boolean",
+      required: false,
+      description: "Ground each animal hero on its lone dropped photo instead of a generated multi-view sheet"
+    },
+    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(args8) {
+  const adId = args8["source-ad-id"] ? String(args8["source-ad-id"]).trim() : "";
+  if (!adId) return { status: "none" };
+  const platformResult = resolveSourcePlatform(args8["source-platform"] ? String(args8["source-platform"]) : void 0);
+  if (!platformResult.ok) return fail4("invalid_source_platform", platformResult.message);
+  const platform = platformResult.platform;
+  const advertiserId = args8["source-advertiser-id"] ? String(args8["source-advertiser-id"]).trim() : void 0;
+  try {
+    const ad = await fetchLibraryReference(adId, platform);
+    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) };
+  }
+}
 var scaffoldStaticAdCommand = defineCommand134({
   meta: {
     name: "scaffold-static-ad",
-    description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (the blueprint, baked to prompt.json as the editable 'prompt') 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 candidates 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 the concept shows one), judged on one idea, exact words, layout, mechanism, brand and artifacts; every other placement format is the winner re-laid by the model, and a format the model has no shape for is cropped exact. 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. Pass --placements none for a single base ad, or a preset to pick the set. Edit prompt.json and drop the real assets, then `baker canvas run` it. Start here: `baker avatars list`, then pass `--avatar <handle>` when the image shows a person \u2014 the ad's people are played by the company's avatars, never by a photo of anyone real."
+    description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (the blueprint, baked to prompt.json as the editable 'prompt') 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 candidates 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 the concept shows one), judged on one idea, exact words, layout, mechanism, brand and artifacts; every other placement format is the winner re-laid by the model, and a format the model has no shape for is cropped exact. 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. Pass --placements none for a single base ad, or a preset to pick the set. Edit prompt.json and drop the real assets, then `baker canvas run` it. Start here: `baker avatars list`, then pass `--avatar <handle>` when the image shows a person \u2014 the ad's people are played by the company's avatars, never by a photo of anyone real. A reference from the library: pass `--source-ad-id <ad_id> --source-platform <platform>` so its structured read grounds the blueprint and the source is recorded on the creative."
   },
   args: {
-    file: { type: "positional", required: true, description: "Path or http(s) URL to the source/inspiration image" },
+    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 },
+    "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: {
@@ -72310,7 +72505,10 @@ var scaffoldStaticAdCommand = defineCommand134({
       type: "string",
       description: "Ad platform (meta|google|linkedin|tiktok|youtube|x|other; default meta). Sets _definition.md AND, unless --placements is given, the formats the ad is delivered in (meta \u2192 4:5+9:16, google \u2192 1:1+4:5+16:9, linkedin \u2192 1:1, tiktok \u2192 9:16, youtube \u2192 16:9; x/other \u2192 one format)."
     },
-    advertiser: { type: "string", description: "Source advertiser recorded in _definition.md" },
+    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" },
@@ -72344,12 +72542,22 @@ var scaffoldStaticAdCommand = defineCommand134({
       );
       process.exit(2);
     }
-    const { imageIsUrl, imageSource, outPath, blueprintPath: blueprintPath2, definitionPath, referencesDir } = resolveScaffoldStaticAdPaths(
-      String(args8.file),
-      args8.out ? String(args8.out) : void 0,
-      process.cwd(),
-      slug
-    );
+    const lookup = await lookupReference(args8);
+    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 fileArg2 = args8.file ? String(args8.file) : void 0;
+    const sourceFile = fileArg2 ?? (lookup.status === "grounded" ? lookup.mediaUrl : void 0);
+    if (!sourceFile) {
+      if (lookup.status === "none") return fail4("missing_source", "Pass the reference image, or --source-ad-id <ad_id> to use a library ad.");
+      if (lookup.status === "unavailable") return fail4("source_unavailable", `No image given and the library ad could not be read (${lookup.message}).`);
+      return fail4("source_unavailable", `The library holds no picture for ad ${reference?.ad_id}; pass the image.`);
+    }
+    const { imageIsUrl, imageSource, outPath, blueprintPath: blueprintPath2, definitionPath, referencesDir } = resolveScaffoldStaticAdPaths(sourceFile, args8.out ? String(args8.out) : void 0, process.cwd(), slug);
     if (slug) await enforceNewCreativeLimit(slug, outPath);
     await mkdir8(path31.dirname(outPath), { recursive: true });
     let models;
@@ -72377,10 +72585,11 @@ var scaffoldStaticAdCommand = defineCommand134({
       durableSourceUrl !== void 0 || imageIsUrl,
       describeModel,
       selectModel,
-      args8.context ? String(args8.context) : void 0
+      referenceDescribeContext(reference, args8.context ? String(args8.context) : void 0)
     );
     const vision = await runVisionPasses(describeCanvas);
-    const { blueprint, creditsSpent } = vision;
+    const { creditsSpent } = vision;
+    const blueprint = mergeReferenceIntoBlueprint(vision.blueprint, reference);
     const elements = castAvatarsOnStaticElements(vision.elements, cast.avatars);
     const uncast = staticAvatarsNotCast(vision.elements, cast.handles);
     const canvasDir = path31.dirname(outPath);
@@ -72441,6 +72650,15 @@ var scaffoldStaticAdCommand = defineCommand134({
     }
     await writeFile12(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,
+      ...args8["source-advertiser-id"] ? { sourceAdvertiserId: String(args8["source-advertiser-id"]).trim() } : {}
+    } : {};
     if (definitionPath && !await fileExists(definitionPath)) {
       await writeFile12(
         definitionPath,
@@ -72450,7 +72668,8 @@ var scaffoldStaticAdCommand = defineCommand134({
           platform: definitionPlatform,
           formats: resolveFormatList(report.output_formats),
           sourceReferenceUrl: durableSourceUrl ?? (imageIsUrl ? imageSource : void 0),
-          sourceAdvertiser: args8.advertiser ? String(args8.advertiser) : args8.context ? String(args8.context) : void 0,
+          sourceAdvertiser: args8.advertiser ? String(args8.advertiser) : reference?.advertiser ?? (args8.context ? String(args8.context) : void 0),
+          ...sourceFields,
           sourceKind: "image",
           description: describeBlueprintIntent(blueprint)
         }),
@@ -72464,11 +72683,15 @@ var scaffoldStaticAdCommand = defineCommand134({
         platform: definitionPlatform,
         formats: resolveFormatList(report.output_formats),
         sourceReferenceUrl: durableSourceUrl ?? (imageIsUrl ? imageSource : void 0),
+        ...sourceFields,
         canvas,
         sourceSha: await computeSourceSha(outPath)
       });
     }
     const hints2 = [
+      ...lookup.status === "unavailable" ? [
+        `REFERENCE NOT READ: the winners library could not return ad ${lookup.adId} (${lookup.message}). The blueprint is the describe pass alone and prompt.json 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.`
       ] : [],
@@ -72485,6 +72708,15 @@ var scaffoldStaticAdCommand = defineCommand134({
           prompt_path: blueprintPath2,
           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,
           ...hints2.length ? { hints: hints2 } : {},
           models: { describe: describeModel, select: selectModel, gen: opts.genModel },
@@ -72497,7 +72729,7 @@ var scaffoldStaticAdCommand = defineCommand134({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path31.basename(blueprintPath2)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
+            edit_prompt: `Edit ${path31.basename(blueprintPath2)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.${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." : ""}`,
             winning_mechanisms: report.winning_mechanisms,
             rebuild_the_mechanism: "`winning_mechanisms` is WHY the source ad works. Rewrite each one for our brand in prompt.json (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,
@@ -72558,7 +72790,7 @@ function clientLogoMissNote(decision, domain) {
 }
 
 // src/commands/canvas/scaffold-ad.ts
-import { copyFile, cp, mkdir as mkdir9, readFile as readFile25, stat as stat5, writeFile as writeFile14 } from "fs/promises";
+import { copyFile, cp, mkdir as mkdir9, readFile as readFile26, stat as stat5, writeFile as writeFile14 } from "fs/promises";
 import path33 from "path";
 import { defineCommand as defineCommand135 } from "citty";
 
@@ -73273,7 +73505,7 @@ function injectAdBrandOverlay(indexHtml, overlayHtml, style = {}) {
 }
 
 // src/commands/canvas/composition-dims.ts
-import { readFile as readFile24, writeFile as writeFile13 } from "fs/promises";
+import { readFile as readFile25, writeFile as writeFile13 } from "fs/promises";
 import path32 from "path";
 function patchCompositionMeta(metaJson, dims) {
   try {
@@ -73290,10 +73522,10 @@ function patchCompositionHtml(html, dims) {
 }
 async function stampCompositionDims(compositionDir, dims) {
   const metaPath = path32.join(compositionDir, "meta.json");
-  const rawMeta = await readFile24(metaPath, "utf8");
+  const rawMeta = await readFile25(metaPath, "utf8");
   await writeFile13(metaPath, patchCompositionMeta(rawMeta, dims), "utf8");
   const htmlPath = path32.join(compositionDir, "index.html");
-  const rawHtml = await readFile24(htmlPath, "utf8");
+  const rawHtml = await readFile25(htmlPath, "utf8");
   await writeFile13(htmlPath, patchCompositionHtml(rawHtml, dims), "utf8");
 }
 
@@ -73376,7 +73608,7 @@ var scaffoldAdCommand = defineCommand135({
     const specPath = args8.spec;
     let parsed;
     try {
-      parsed = JSON.parse(await readFile25(specPath, "utf-8"));
+      parsed = JSON.parse(await readFile26(specPath, "utf-8"));
     } catch (e) {
       writeJson({
         ok: false,
@@ -73537,7 +73769,7 @@ var scaffoldAdCommand = defineCommand135({
     ] : [];
     const markPath = spec.data.brand?.logo?.trim();
     if (!noBrand && markPath?.toLowerCase().endsWith(".svg")) {
-      const svg = await readFile25(markPath, "utf-8").catch(() => null);
+      const svg = await readFile26(markPath, "utf-8").catch(() => null);
       if (svg === null) {
         writeJson({
           ok: false,
@@ -73617,10 +73849,10 @@ var scaffoldAdCommand = defineCommand135({
     await stampCompositionDims(compositionDest, outDims);
     await stampCompositionDims(captionsDest, outDims);
     const captionsIndex = path33.join(captionsDest, "index.html");
-    await writeFile14(captionsIndex, injectAdCaptionPlacement(await readFile25(captionsIndex, "utf-8"), outAr), "utf-8");
+    await writeFile14(captionsIndex, injectAdCaptionPlacement(await readFile26(captionsIndex, "utf-8"), outAr), "utf-8");
     const face = await stageBrandDisplayFace(outDir, captionsDest);
     if (face) {
-      await writeFile14(captionsIndex, injectAdDisplayFace(await readFile25(captionsIndex, "utf-8"), face.file), "utf-8");
+      await writeFile14(captionsIndex, injectAdDisplayFace(await readFile26(captionsIndex, "utf-8"), face.file), "utf-8");
     }
     const blueprintPath2 = path33.join(outDir, "prompt.json");
     const blueprintStylePath = path33.join(outDir, "prompt.style.json");
@@ -73713,7 +73945,7 @@ var scaffoldAdCommand = defineCommand135({
     }) : "";
     if (overlayHtml && renderedDir) {
       const indexPath = path33.join(renderedDir, "index.html");
-      const html = await readFile25(indexPath, "utf-8");
+      const html = await readFile26(indexPath, "utf-8");
       await writeFile14(indexPath, injectAdBrandOverlay(html, overlayHtml, { aspect: outAr, ...face ? { face: AD_DISPLAY_FAMILY } : {} }), "utf-8");
     }
     await writeFile14(
@@ -73901,7 +74133,7 @@ async function stageBrandDisplayFace(outDir, compositionDir) {
 }
 
 // src/commands/canvas/scaffold-video.ts
-import { cp as cp2, mkdir as mkdir10, readFile as readFile28, rm as rm8, writeFile as writeFile15 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir10, readFile as readFile29, rm as rm8, writeFile as writeFile15 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
 import path35 from "path";
 import { defineCommand as defineCommand136 } from "citty";
@@ -73943,7 +74175,7 @@ function routeVideoModel(input) {
 
 // src/engine/nodes/local/lib/sceneDetect.ts
 import { execFile as execFile3 } from "child_process";
-import { mkdtemp as mkdtemp2, readdir as readdir12, readFile as readFile26, rm as rm7 } from "fs/promises";
+import { mkdtemp as mkdtemp2, readdir as readdir12, readFile as readFile27, rm as rm7 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join3 } from "path";
 import { promisify as promisify3 } from "util";
@@ -74019,7 +74251,7 @@ async function runSceneDetectOnce(filePath, threshold, minSceneLenS, timeoutMs)
     );
     const csvName = (await readdir12(outDir)).find((f) => f.toLowerCase().endsWith(".csv"));
     if (!csvName) return [];
-    return parsePySceneDetectCsvCuts(await readFile26(join3(outDir, csvName), "utf-8"));
+    return parsePySceneDetectCsvCuts(await readFile27(join3(outDir, csvName), "utf-8"));
   } finally {
     await rm7(outDir, { recursive: true, force: true });
   }
@@ -74043,7 +74275,7 @@ async function detectSceneCutsPySceneDetect(filePath, opts = {}) {
 }
 
 // src/commands/canvas/gitignore.ts
-import { appendFile, readFile as readFile27 } from "fs/promises";
+import { appendFile, readFile as readFile28 } from "fs/promises";
 import path34 from "path";
 function missingGitignoreEntries(existing, entries) {
   const present2 = new Set(
@@ -74055,7 +74287,7 @@ async function ensureGitignore(dir, entries) {
   const file = path34.join(dir, ".gitignore");
   let existing;
   try {
-    existing = await readFile27(file, "utf8");
+    existing = await readFile28(file, "utf8");
   } catch {
     return;
   }
@@ -74477,7 +74709,7 @@ var scaffoldVideoCommand = defineCommand136({
     await stampCompositionDims(compositionDest, outDims);
     const indexPath = path35.join(compositionDest, "index.html");
     const overlayHtml = buildOverlayHtml(blueprint, { captionsActive: Boolean(transcript), videoModel });
-    const indexHtml = await readFile28(indexPath, "utf8");
+    const indexHtml = await readFile29(indexPath, "utf8");
     const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
     if (injected === indexHtml && overlayHtml.trim()) {
       fail4(
@@ -74642,7 +74874,7 @@ var scaffoldVideoCommand = defineCommand136({
 });
 
 // src/commands/canvas/set-prompt.ts
-import { readFile as readFile29, writeFile as writeFile16 } from "fs/promises";
+import { readFile as readFile30, writeFile as writeFile16 } from "fs/promises";
 import path36 from "path";
 import { defineCommand as defineCommand137 } from "citty";
 function setNodePrompt(canvas, nodeId, text2) {
@@ -74673,7 +74905,7 @@ var SetPromptError = class extends Error {
 };
 async function setPromptInCanvasFile(canvasPath, nodeId, text2) {
   const filePath = path36.resolve(canvasPath);
-  const original = await readFile29(filePath, "utf8");
+  const original = await readFile30(filePath, "utf8");
   let canvas;
   try {
     canvas = JSON.parse(original);
@@ -74740,7 +74972,7 @@ var setPromptCommand = defineCommand137({
   },
   async run({ args: args8 }) {
     let text2;
-    if (args8["text-file"]) text2 = await readFile29(path36.resolve(String(args8["text-file"])), "utf8");
+    if (args8["text-file"]) text2 = await readFile30(path36.resolve(String(args8["text-file"])), "utf8");
     else if (args8.text !== void 0) text2 = String(args8.text);
     else {
       process.stderr.write(
@@ -75497,7 +75729,7 @@ import { Buffer as Buffer2 } from "buffer";
 import { defineCommand as defineCommand146 } from "citty";
 
 // src/commands/images/api.ts
-import { readFile as readFile30 } from "fs/promises";
+import { readFile as readFile31 } from "fs/promises";
 import { basename, extname } from "path";
 var imageProcessingTimeoutMs = 18e4;
 var imageReadyPollIntervalMs = 2e3;
@@ -75511,7 +75743,7 @@ var mimeMap = {
   ".avif": "image/avif"
 };
 var defaultImageApiDeps = {
-  readFile: readFile30,
+  readFile: readFile31,
   post: apiPost,
   get: apiGet,
   sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms))
@@ -75577,7 +75809,7 @@ async function waitForReadyImage(deps, imageId, opts = {}) {
 }
 
 // src/commands/videos/api.ts
-import { readFile as readFile31 } from "fs/promises";
+import { readFile as readFile32 } from "fs/promises";
 import { basename as basename2, extname as extname2 } from "path";
 var videoProcessingTimeoutMs = 18e4;
 var videoReadyPollIntervalMs = 3e3;
@@ -75589,7 +75821,7 @@ var mimeMap2 = {
   ".mkv": "video/x-matroska"
 };
 var defaultVideoApiDeps = {
-  readFile: readFile31,
+  readFile: readFile32,
   post: apiPost,
   get: apiGet,
   sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms)),
@@ -75980,11 +76212,11 @@ Full guide: __tooling__/docs/tools/baker/creatives.md`
 import { defineCommand as defineCommand149 } from "citty";
 
 // src/commands/experiment/composition.ts
-import { readdir as readdir14, readFile as readFile33 } from "fs/promises";
+import { readdir as readdir14, readFile as readFile34 } from "fs/promises";
 import path40 from "path";
 
 // src/commands/landing/import-graph.ts
-import { readdir as readdir13, readFile as readFile32, stat as stat6 } from "fs/promises";
+import { readdir as readdir13, readFile as readFile33, stat as stat6 } from "fs/promises";
 import path39 from "path";
 var SOURCE_EXT = /\.(astro|ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/;
 var RESOLVE_CANDIDATES = [
@@ -76061,7 +76293,7 @@ async function landingGraphFiles(root, slug) {
     if (file === void 0 || seen.has(file)) continue;
     let text2;
     try {
-      text2 = await readFile32(file, "utf8");
+      text2 = await readFile33(file, "utf8");
     } catch {
       continue;
     }
@@ -76126,7 +76358,7 @@ async function readForms(root, slug) {
     const [files, flows] = await Promise.all([landingGraphFiles(root, slug), knownFlows(root)]);
     if (flows.size === 0) return [];
     const texts = await Promise.all(
-      [...files].filter((file) => /\.(astro|ts|tsx|js|mjs)$/.test(file)).map((file) => readFile33(path40.join(root, file), "utf8"))
+      [...files].filter((file) => /\.(astro|ts|tsx|js|mjs)$/.test(file)).map((file) => readFile34(path40.join(root, file), "utf8"))
     );
     return formsReferenced(texts, flows);
   } catch {
@@ -76136,7 +76368,7 @@ async function readForms(root, slug) {
 
 // src/commands/experiment/fold.ts
 import { statSync } from "fs";
-import { cp as cp3, mkdir as mkdir11, readdir as readdir15, readFile as readFile34, rm as rm9, stat as stat7, writeFile as writeFile17 } from "fs/promises";
+import { cp as cp3, mkdir as mkdir11, readdir as readdir15, readFile as readFile35, rm as rm9, stat as stat7, writeFile as writeFile17 } from "fs/promises";
 import path42 from "path";
 
 // ../api/src/experiments/variants.ts
@@ -76239,7 +76471,7 @@ async function archiveArm(opts) {
     if (!TEXT_EXT.test(rel)) {
       await cp3(abs, dest);
     } else {
-      const text2 = await readFile34(abs, "utf8");
+      const text2 = await readFile35(abs, "utf8");
       await writeFile17(dest, repointIntoArchive(text2, abs, dest, archivedBySource), "utf8");
     }
     written.push(posix2(path42.relative(root, dest)));
@@ -76310,7 +76542,7 @@ async function promoteVariantFiles(opts) {
     if (!TEXT_EXT.test(rel)) {
       await cp3(from, to);
     } else {
-      const text2 = await readFile34(from, "utf8");
+      const text2 = await readFile35(from, "utf8");
       await writeFile17(
         to,
         repointMoved(text2, {
@@ -77152,11 +77384,11 @@ function parseEvidence(raw, rawArgs) {
 }
 
 // src/commands/experiment/identity.ts
-import { readFile as readFile35 } from "fs/promises";
+import { readFile as readFile36 } from "fs/promises";
 import path43 from "path";
 async function readPageInternalId(root, slug) {
   try {
-    const text2 = await readFile35(path43.resolve(root, "src", "pages", slug, "_definition.md"), "utf8");
+    const text2 = await readFile36(path43.resolve(root, "src", "pages", slug, "_definition.md"), "utf8");
     return /^internalId:\s*"?([^"\s]+)"?\s*$/m.exec(text2)?.[1];
   } catch {
     return void 0;
@@ -77164,7 +77396,7 @@ async function readPageInternalId(root, slug) {
 }
 
 // src/commands/experiment/measurement.ts
-import { readFile as readFile36 } from "fs/promises";
+import { readFile as readFile37 } from "fs/promises";
 import path44 from "path";
 function eventDeclarationsIn(source) {
   const found = [];
@@ -77225,7 +77457,7 @@ function sectionsOf(files, slug) {
   return files.filter((file) => file.startsWith(prefix) && !file.slice(prefix.length).startsWith("index."));
 }
 async function declarationsOf(root, files) {
-  const sources = await Promise.all(files.map((file) => readFile36(path44.join(root, file), "utf8").catch(() => "")));
+  const sources = await Promise.all(files.map((file) => readFile37(path44.join(root, file), "utf8").catch(() => "")));
   return sources.flatMap(eventDeclarationsIn);
 }
 
@@ -83105,7 +83337,7 @@ function cropSprite(input, region) {
 
 // src/lib/image/io.ts
 import { randomBytes } from "crypto";
-import { glob as fsGlob, readFile as readFile37, rename, stat as stat8, writeFile as writeFile18 } from "fs/promises";
+import { glob as fsGlob, readFile as readFile38, rename, stat as stat8, writeFile as writeFile18 } from "fs/promises";
 import { dirname as dirname2, extname as extname3, join as join5, resolve as resolve4 } from "path";
 var REMOTE_RE = /^https?:\/\//i;
 var GLOB_RE = /[*?[\]{}]/;
@@ -83138,7 +83370,7 @@ async function readImageBuffer(pathOrUrl) {
     const { buffer } = await fetchExternalBytes(pathOrUrl, { maxBytes: MAX_REMOTE_IMAGE_BYTES });
     return buffer;
   }
-  return readFile37(pathOrUrl);
+  return readFile38(pathOrUrl);
 }
 async function isDirectory(path59) {
   try {
@@ -86687,7 +86919,7 @@ Full guide: __tooling__/docs/tools/baker/images.md`
 import { defineCommand as defineCommand207 } from "citty";
 
 // src/commands/landing/critique.ts
-import { readdir as readdir17, readFile as readFile39, stat as stat10 } from "fs/promises";
+import { readdir as readdir17, readFile as readFile40, stat as stat10 } from "fs/promises";
 import path47 from "path";
 import { defineCommand as defineCommand196 } from "citty";
 
@@ -87898,7 +88130,7 @@ async function writeCritiqueSnapshot(projectRoot, snapshot) {
 }
 
 // src/commands/landing/source-version.ts
-import { readdir as readdir16, readFile as readFile38, stat as stat9 } from "fs/promises";
+import { readdir as readdir16, readFile as readFile39, stat as stat9 } from "fs/promises";
 import path46 from "path";
 var CRITIQUED_ROOTS = ["src/pages/", "src/components/"];
 async function landingSourceRelPaths(root, slug) {
@@ -87908,7 +88140,7 @@ async function landingSourceRelPaths(root, slug) {
 async function readLandingSources(root, slug) {
   const rel = await landingSourceRelPaths(root, slug);
   const out = [];
-  for (const r of rel) out.push({ path: r, text: await readFile38(path46.join(root, r), "utf8") });
+  for (const r of rel) out.push({ path: r, text: await readFile39(path46.join(root, r), "utf8") });
   return out;
 }
 async function computeLandingSourceSha(root, slug) {
@@ -87917,7 +88149,7 @@ async function computeLandingSourceSha(root, slug) {
   for (const r of rel) {
     let bytes;
     try {
-      bytes = await readFile38(path46.join(root, r));
+      bytes = await readFile39(path46.join(root, r));
     } catch {
       bytes = Buffer.alloc(0);
     }
@@ -87936,7 +88168,7 @@ async function computeLegacyLandingSourceSha(landingDir) {
   for (const r of rel) {
     let bytes;
     try {
-      bytes = await readFile38(path46.join(landingDir, r));
+      bytes = await readFile39(path46.join(landingDir, r));
     } catch {
       bytes = Buffer.alloc(0);
     }
@@ -88095,7 +88327,7 @@ async function readCompetitorNames(projectRoot) {
   for (const entry of entries) {
     names.push(path47.basename(entry, ".md").replace(/[-_]+/g, " "));
     try {
-      const head = (await readFile39(path47.join(dir, entry), "utf8")).slice(0, 2e3);
+      const head = (await readFile40(path47.join(dir, entry), "utf8")).slice(0, 2e3);
       const titled = /^\s*(?:title|name)\s*:\s*["']?([^"'\n]+)["']?\s*$/im.exec(head);
       if (titled?.[1]) names.push(titled[1].trim());
     } catch {
@@ -91298,7 +91530,7 @@ Full guide: __tooling__/docs/tools/baker/landing.md`
 
 // src/commands/landing/variant.ts
 import { randomUUID as randomUUID3 } from "crypto";
-import { mkdir as mkdir16, readdir as readdir18, readFile as readFile40, stat as stat11, writeFile as writeFile24 } from "fs/promises";
+import { mkdir as mkdir16, readdir as readdir18, readFile as readFile41, stat as stat11, writeFile as writeFile24 } from "fs/promises";
 import path55 from "path";
 import { defineCommand as defineCommand206 } from "citty";
 registerSchema({
@@ -91326,7 +91558,7 @@ registerSchema({
 var SLUG_RE2 = /^[a-z0-9][a-z0-9-]*$/;
 async function readInternalId(definitionPath) {
   try {
-    const text2 = await readFile40(definitionPath, "utf8");
+    const text2 = await readFile41(definitionPath, "utf8");
     return /^internalId:\s*"?([^"\s]+)"?\s*$/m.exec(text2)?.[1] ?? null;
   } catch {
     return null;
@@ -91485,7 +91717,7 @@ async function writeVariant(opts) {
   const { controlDir, variantDir, controlSlug, variantSlug: variantSlug2, forks } = opts;
   const forkedTargets = new Set(forks.map((f) => path55.join(controlDir, "_components", f)));
   const written = [];
-  const indexText = await readFile40(path55.join(controlDir, "index.astro"), "utf8");
+  const indexText = await readFile41(path55.join(controlDir, "index.astro"), "utf8");
   await mkdir16(variantDir, { recursive: true });
   await writeFile24(
     path55.join(variantDir, "index.astro"),
@@ -91496,7 +91728,7 @@ async function writeVariant(opts) {
   for (const fork of forks) {
     const fromFile = path55.join(controlDir, "_components", fork);
     const toFile = path55.join(variantDir, "_components", fork);
-    const text2 = await readFile40(fromFile, "utf8");
+    const text2 = await readFile41(fromFile, "utf8");
     await mkdir16(path55.dirname(toFile), { recursive: true });
     await writeFile24(
       toFile,
@@ -91513,7 +91745,7 @@ async function writeVariant(opts) {
   }
   const controlDefinitionPath = path55.join(controlDir, "_definition.md");
   if (await exists2(controlDefinitionPath)) {
-    const definition = buildVariantDefinition(await readFile40(controlDefinitionPath, "utf8"), {
+    const definition = buildVariantDefinition(await readFile41(controlDefinitionPath, "utf8"), {
       internalId: randomUUID3().replace(/-/g, "").slice(0, 8),
       variantSlug: variantSlug2,
       controlSlug,
@@ -94230,7 +94462,7 @@ Full guide: __tooling__/docs/tools/baker/scheduled-agents.md`
 });
 
 // src/commands/scheduled-agents/templates.ts
-import { readFile as readFile41 } from "fs/promises";
+import { readFile as readFile42 } from "fs/promises";
 import path56 from "path";
 import { defineCommand as defineCommand234 } from "citty";
 registerSchema({
@@ -94338,7 +94570,7 @@ Full guide: __tooling__/docs/tools/baker/scheduled-agents.md`
       }
       if (save.length > 0) {
         const briefFile = flag("brief-file");
-        const brief2 = briefFile.length > 0 ? await readFile41(path56.resolve(briefFile), "utf8") : flag("brief");
+        const brief2 = briefFile.length > 0 ? await readFile42(path56.resolve(briefFile), "utf8") : flag("brief");
         if (brief2.trim().length === 0) {
           failValidation4("--brief-file (preferred) or --brief is required: the brief is the recipe.");
         }
@@ -98068,7 +98300,7 @@ Full guide: __tooling__/docs/tools/baker/videos.md`
 });
 
 // src/commands/winning-ads/index.ts
-import { defineCommand as defineCommand279 } from "citty";
+import { defineCommand as defineCommand277 } from "citty";
 
 // src/commands/winning-ads/advertisers.ts
 import { defineCommand as defineCommand267 } from "citty";
@@ -98181,90 +98413,8 @@ var advertisersCommand2 = defineCommand267({
   }
 });
 
-// src/commands/winning-ads/brief.ts
-import { defineCommand as defineCommand268 } from "citty";
-registerSchema({
-  command: "winning-ads.brief",
-  description: "Generate a creative brief grounded in strategically-similar winning ads. Optionally describe the target creative with --dna (JSON) and steer with --notes.",
-  args: {
-    dna: {
-      type: "string",
-      description: `Partial target DNA as JSON, e.g. '{"angle":"cost savings","awareness_stage":"solution_aware"}'`,
-      required: false
-    },
-    notes: { type: "string", description: "Free-text guidance for the brief", required: false },
-    k: {
-      type: "number",
-      description: "Number of reference ads to pull 1-50 (default: service default)",
-      required: false
-    }
-  }
-});
-function buildBriefBody(args8) {
-  const body = {};
-  if (args8.targetDna && Object.keys(args8.targetDna).length) {
-    body.target_dna = args8.targetDna;
-  }
-  if (args8.notes) {
-    body.notes = args8.notes;
-  }
-  if (args8.k !== void 0 && args8.k !== "") {
-    body.k_reference_ads = Number(args8.k);
-  }
-  return body;
-}
-function parseDna(raw) {
-  if (!raw) {
-    return void 0;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new SyntaxError("--dna must be valid JSON");
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new SyntaxError("--dna must be a JSON object");
-  }
-  return parsed;
-}
-var briefCommand = defineCommand268({
-  meta: {
-    name: "brief",
-    description: `Generate a creative brief from winning references. Example: baker winning-ads brief --dna '{"angle":"cost savings"}' --notes "B2B, LinkedIn video" --k 8`
-  },
-  args: {
-    dna: { type: "string", description: "Partial target DNA as JSON", required: false },
-    notes: { type: "string", description: "Free-text guidance", required: false },
-    k: { type: "string", description: "Number of reference ads (1-50)", required: false }
-  },
-  run: async ({ args: args8 }) => {
-    try {
-      let targetDna;
-      try {
-        targetDna = parseDna(args8.dna);
-      } catch (err) {
-        writeJson({
-          ok: false,
-          error: { code: "VALIDATION_ERROR", message: err instanceof Error ? err.message : "Invalid --dna" }
-        });
-        process.exit(1);
-      }
-      const body = buildBriefBody({
-        targetDna,
-        notes: args8.notes,
-        k: args8.k
-      });
-      const data = await apiPost("/api/ad-library/brief", body);
-      writeJson({ ok: true, data });
-    } catch (err) {
-      reportError3(err);
-    }
-  }
-});
-
 // src/commands/winning-ads/content.ts
-import { defineCommand as defineCommand269 } from "citty";
+import { defineCommand as defineCommand268 } from "citty";
 registerSchema({
   command: "winning-ads.content",
   description: "Read what's INSIDE one winning ad: the spoken transcript, the on-screen text, and the ad copy. Use this after `search`/`winners`/`feed` return a shortlist \u2014 pass an ad_id to understand a reference before reproducing it. Static and carousel ads return the text drawn into the image with the job each piece does (headline, benefit, cta\u2026), the card it sits on, and their format_pattern. Add --full for how it is built (composition, colours, CTA, markers), how it persuades (awareness, mechanism, pains, desires, proof, objections), what it offers (offer type, price, guarantee, urgency), plus speech, pacing and soundtrack for video.",
@@ -98277,7 +98427,7 @@ registerSchema({
     }
   }
 });
-var contentCommand = defineCommand269({
+var contentCommand = defineCommand268({
   meta: {
     name: "content",
     description: "Read the transcript + on-screen text + copy of one winning ad; --full adds its build, persuasion and offer. Example: baker winning-ads content adg_123 --platform meta --full --output md"
@@ -98326,7 +98476,7 @@ var contentCommand = defineCommand269({
 });
 
 // src/commands/winning-ads/feed.ts
-import { defineCommand as defineCommand270 } from "citty";
+import { defineCommand as defineCommand269 } from "citty";
 function buildFeedParams(input) {
   const params = {};
   const advertiser = splitList4(input.advertiser);
@@ -98378,7 +98528,7 @@ registerSchema({
     format: { type: "string", description: "Comma-separated formats to include (e.g. static,video)", required: false }
   }
 });
-var feedCommand2 = defineCommand270({
+var feedCommand2 = defineCommand269({
   meta: {
     name: "feed",
     description: "Winners across every brand you follow (browse, then trim per advertiser). Example: baker winning-ads feed --per-advertiser 5 --output md"
@@ -98463,7 +98613,7 @@ var feedCommand2 = defineCommand270({
 });
 
 // src/commands/winning-ads/follow.ts
-import { defineCommand as defineCommand271 } from "citty";
+import { defineCommand as defineCommand270 } from "citty";
 var PLATFORMS = adLibraryPlatformSchema.options;
 registerSchema({
   command: "winning-ads.follow",
@@ -98478,7 +98628,7 @@ registerSchema({
     label: { type: "string", description: "Optional display label (defaults to the resolved name)", required: false }
   }
 });
-var followCommand = defineCommand271({
+var followCommand = defineCommand270({
   meta: {
     name: "follow",
     description: 'Follow a brand to track ALL its ads \u2014 every platform and country. --platform is how we read your input, not a limit. A domain tracks every platform we can resolve. Example: baker winning-ads follow "deel.com" --platform meta'
@@ -98525,7 +98675,7 @@ var followCommand = defineCommand271({
 });
 
 // src/commands/winning-ads/follow-competitors.ts
-import { defineCommand as defineCommand272 } from "citty";
+import { defineCommand as defineCommand271 } from "citty";
 var PLATFORMS2 = adLibraryPlatformSchema.options;
 var BATCH_TIMEOUT_MS = 3e5;
 function buildFollowBatchBody(input) {
@@ -98558,7 +98708,7 @@ registerSchema({
     }
   }
 });
-var followCompetitorsCommand = defineCommand272({
+var followCompetitorsCommand = defineCommand271({
   meta: {
     name: "follow-competitors",
     description: 'Follow many brands at once by domain \u2014 add every competitor in one call. Example: baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"'
@@ -98633,7 +98783,7 @@ var followCompetitorsCommand = defineCommand272({
 });
 
 // src/commands/winning-ads/following.ts
-import { defineCommand as defineCommand273 } from "citty";
+import { defineCommand as defineCommand272 } from "citty";
 registerSchema({
   command: "winning-ads.following",
   description: "List the brands you follow in your ad-dna library, with each one's status (ready vs still adding) and cached ad counts. A brand still adding has counts that are a lie in progress; one with `discovery_failed` has counts that are short because we couldn't finish looking, which is not the same as it running no ads.",
@@ -98687,7 +98837,7 @@ function followingNormalizer(record, full) {
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };
 }
-var followingCommand = defineCommand273({
+var followingCommand = defineCommand272({
   meta: {
     name: "following",
     description: "List brands you follow, with status (ready / adding\u2026) and cached counts. A brand's counts are only final once it is ready. Example: baker winning-ads following --output md"
@@ -98722,113 +98872,18 @@ var followingCommand = defineCommand273({
   }
 });
 
-// src/commands/winning-ads/patterns.ts
-import { defineCommand as defineCommand274 } from "citty";
-registerSchema({
-  command: "winning-ads.patterns",
-  description: "Mine what separates two cohorts of ads: pass a comma-list of winning ad ids (--winners) and a comma-list of weaker ad ids (--duds). Returns the discriminating DNA fields.",
-  args: {
-    winners: { type: "string", description: "Comma list of winning ad ids (cohort A)", required: true },
-    duds: { type: "string", description: "Comma list of weaker/dud ad ids (cohort B)", required: true },
-    "top-n": {
-      type: "number",
-      description: "Max discriminators to return 1-50 (default: service default)",
-      required: false
-    }
-  }
-});
-function buildPatternsBody(args8) {
-  const winners = splitList4(args8.winners);
-  const duds = splitList4(args8.duds);
-  if (!winners.length || !duds.length) {
-    throw new Error("Provide at least one ad id for both --winners and --duds");
-  }
-  const body = {
-    cohort_a: { ad_ids: winners },
-    cohort_b: { ad_ids: duds }
-  };
-  if (args8.topN !== void 0 && args8.topN !== "") {
-    body.top_n = Number(args8.topN);
-  }
-  return body;
-}
-function discriminatorRow(record) {
-  const dir = record.direction === "favors_a" ? "winners" : "duds";
-  return {
-    field: String(record.field ?? ""),
-    favors: dir,
-    score: record.score ?? null,
-    top_values_winners: Array.isArray(record.top_values_a) ? record.top_values_a.join(", ") : "",
-    top_values_duds: Array.isArray(record.top_values_b) ? record.top_values_b.join(", ") : ""
-  };
-}
-var patternsCommand = defineCommand274({
-  meta: {
-    name: "patterns",
-    description: "Discover what separates winning ads from weak ones. Example: baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --output md"
-  },
-  args: {
-    winners: { type: "string", description: "Comma list of winning ad ids (cohort A)", required: true },
-    duds: { type: "string", description: "Comma list of weaker/dud ad ids (cohort B)", required: true },
-    "top-n": { type: "string", description: "Max discriminators (1-50)", required: false },
-    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
-    fields: { type: "string", description: "Comma-separated field names to include", required: false }
-  },
-  run: async ({ args: args8 }) => {
-    try {
-      let body;
-      try {
-        body = buildPatternsBody({
-          winners: args8.winners,
-          duds: args8.duds,
-          topN: args8["top-n"]
-        });
-      } catch (err) {
-        writeJson({
-          ok: false,
-          error: { code: "VALIDATION_ERROR", message: err instanceof Error ? err.message : "Invalid cohorts" }
-        });
-        process.exit(1);
-      }
-      const data = await apiPost("/api/ad-library/patterns", body);
-      const output = args8.output || "json";
-      const rawDiscriminators = Array.isArray(data?.discriminators) ? data.discriminators : [];
-      if (output === "json") {
-        writeJson({
-          ok: true,
-          data: {
-            cohort_a_size: data?.cohort_a_size ?? 0,
-            cohort_b_size: data?.cohort_b_size ?? 0,
-            discriminators: rawDiscriminators.map((d) => discriminatorRow(d))
-          }
-        });
-        return;
-      }
-      writeOutput(
-        { ok: true, data: rawDiscriminators },
-        output,
-        args8.fields ? args8.fields.split(",") : void 0,
-        false,
-        (record) => discriminatorRow(record)
-      );
-    } catch (err) {
-      reportError3(err);
-    }
-  }
-});
-
 // src/commands/winning-ads/search.ts
-import { defineCommand as defineCommand275 } from "citty";
+import { defineCommand as defineCommand273 } from "citty";
 registerSchema({
   command: "winning-ads.search",
-  description: "Search the ad-dna corpus of scored winning ads. Returns a lean shortlist (advertiser, summary, scores, media_url, and visual/container/mechanism when known) to pick a reference to reproduce. A value outside a closed list (--platform, --format, --winner-category, --awareness, --format-pattern) is refused with error.fix.validValues.",
+  description: "Search the ad-dna corpus of scored winning ads, the company's followed brands first. Returns a lean shortlist (advertiser, summary, scores, days_active/active/winner_category as proof, media_url, and visual/container/mechanism when known) to pick a reference to reproduce. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry. A value outside a closed list (--platform, --format, --winner-category, --awareness, --format-pattern, --sort) is refused with error.fix.validValues.",
   args: {
     query: { type: "string", description: "Free-text natural-language query", required: false },
     scope: {
       type: "string",
-      description: "Which brands to draw from: all (default, the whole shared library), followed (only brands the company follows), followed-first (followed brands first, topped up from the library when too few clear the relevance floor). Every result carries source: followed|library.",
+      description: "Which brands to draw from: followed-first (default: followed brands first, topped up from the library when too few clear the relevance floor; the whole library when the company follows nobody), followed (only brands the company follows), all (the whole shared library). Every result carries source: followed|library.",
       required: false,
-      default: "all"
+      default: "followed-first"
     },
     "ref-ad-id": {
       type: "string",
@@ -98843,6 +98898,12 @@ registerSchema({
       default: 3
     },
     "min-relevance": { type: "number", description: "Relevance floor 0-1; trims weak matches", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a browse with no query: winner (default, by winner score), longest_running (by days active), newest (by first seen). Ignored when a query is given: a query ranks by relevance blended with winner score.",
+      required: false,
+      default: "winner"
+    },
     platform: {
       type: "string",
       description: "Comma list: meta,linkedin,tiktok",
@@ -98931,6 +98992,7 @@ function buildSearchBody2(args8) {
   setNumber(body, "limit", args8.limit);
   setNumber(body, "max_per_advertiser", args8.maxPerAdvertiser);
   setNumber(body, "min_relevance", args8.minRelevance);
+  setString(body, "sort", args8.sort);
   if (args8.diverse) {
     body.diverse = true;
   }
@@ -99051,6 +99113,9 @@ function searchRejection(args8, body) {
   if (args8.scope !== void 0 && !winnerSearchScopeSchema.safeParse(args8.scope).success) {
     return { message: `Unknown --scope "${args8.scope}". Use one of: ${winnerSearchScopeSchema.options.join(", ")}.` };
   }
+  if (args8.sort !== void 0 && !winnersSortSchema.safeParse(args8.sort).success) {
+    return { message: `Unknown --sort "${args8.sort}". Use one of: ${winnersSortSchema.options.join(", ")}.` };
+  }
   for (const [flag, key] of NUMERIC_FLAGS) {
     const value2 = args8[key];
     if (value2 !== void 0 && value2 !== "" && Number.isNaN(Number(value2))) {
@@ -99086,16 +99151,16 @@ function writeSearchResult(data, opts) {
   writeOutput({ ok: true, data: rawResults, ...withHints2 }, opts.output, opts.fields, opts.full, winningAdNormalizer);
 }
 var SEARCH_TIMEOUT_MS = 12e4;
-var searchCommand5 = defineCommand275({
+var searchCommand5 = defineCommand273({
   meta: {
     name: "search",
-    description: "Search winning reference ads. Start here: baker winning-ads search 'B2B SaaS before/after AI automation' --scope followed-first --platform meta --format static --exclude-advertiser adv_123 --output md. A set of references for N concepts in one call: add --diverse --limit N. The best proven ad in one container from any category: --format-pattern comparison_table (no query needed)."
+    description: "Search winning reference ads, the company's followed brands first. Start here: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --exclude-advertiser adv_123 --output md. A set of references for N concepts in one call: add --diverse --limit N. The best proven ad in one container from any category: --format-pattern comparison_table (no query needed; add --sort longest_running to order by staying power). Each search is a paid reranker + judge call: one strong search, at most one adjusted retry."
   },
   args: {
     query: { type: "positional", description: "Free-text search query", required: false },
     scope: {
       type: "string",
-      description: "all (default) | followed | followed-first. followed-first = the company's followed brands first, topped up from the whole library",
+      description: "followed-first (default) | followed | all. followed-first = the company's followed brands first, topped up from the whole library (the whole library when it follows nobody)",
       required: false
     },
     "ref-ad-id": { type: "string", description: "Find ads similar to this ad id", required: false },
@@ -99111,6 +99176,11 @@ var searchCommand5 = defineCommand275({
       required: false
     },
     "min-relevance": { type: "string", description: "Relevance floor 0-1", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a no-query browse: winner (default) | longest_running | newest. Ignored when a query is given",
+      required: false
+    },
     platform: {
       type: "string",
       description: "Comma list of platforms (meta,linkedin,tiktok) \u2014 search one or several",
@@ -99157,7 +99227,7 @@ var searchCommand5 = defineCommand275({
     fields: { type: "string", description: "Comma-separated field names to include", required: false },
     full: {
       type: "boolean",
-      description: "Include DNA detail (angle, persona, hook) + longevity; mechanism is in the default output",
+      description: "Include DNA detail (angle, persona, hook, awareness, industry) + reach and media kind; mechanism, days_active, active and winner_category are in the default output",
       required: false,
       default: false
     }
@@ -99171,6 +99241,7 @@ var searchCommand5 = defineCommand275({
         limit: args8.limit,
         maxPerAdvertiser: args8["max-per-advertiser"],
         minRelevance: args8["min-relevance"],
+        sort: args8.sort,
         platform: args8.platform,
         format: args8.format,
         winnerCategory: args8["winner-category"],
@@ -99206,7 +99277,7 @@ var searchCommand5 = defineCommand275({
 });
 
 // src/commands/winning-ads/seeds.ts
-import { defineCommand as defineCommand276 } from "citty";
+import { defineCommand as defineCommand274 } from "citty";
 function leanRow(r) {
   return {
     key: r.key,
@@ -99234,7 +99305,7 @@ function makeSeedCommand(opts) {
       limit: { type: "number", description: "Max keys 1-100 (default 20)", required: false, default: 20 }
     }
   });
-  return defineCommand276({
+  return defineCommand274({
     meta: { name: opts.name, description: opts.description },
     args: {
       platform: { type: "string", description: "Single platform to segment on", required: false },
@@ -99283,7 +99354,7 @@ var formatsCommand = makeSeedCommand({
 });
 
 // src/commands/winning-ads/unfollow.ts
-import { defineCommand as defineCommand277 } from "citty";
+import { defineCommand as defineCommand275 } from "citty";
 registerSchema({
   command: "winning-ads.unfollow",
   description: "Stop following a brand \u2014 removes it from your ad-dna library by advertiser id.",
@@ -99291,7 +99362,7 @@ registerSchema({
     advertiser: { type: "string", description: "Advertiser id to unfollow", required: true }
   }
 });
-var unfollowCommand = defineCommand277({
+var unfollowCommand = defineCommand275({
   meta: {
     name: "unfollow",
     description: "Stop following a brand by advertiser id. Example: baker winning-ads unfollow adv_123"
@@ -99312,7 +99383,7 @@ var unfollowCommand = defineCommand277({
 });
 
 // src/commands/winning-ads/winners.ts
-import { defineCommand as defineCommand278 } from "citty";
+import { defineCommand as defineCommand276 } from "citty";
 registerSchema({
   command: "winning-ads.winners",
   description: "Top winning ads for one advertiser id (from `advertisers` or `following`). Returns lean winner cards; add --full for DNA + longevity.",
@@ -99322,7 +99393,7 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin|tiktok", required: false }
   }
 });
-var winnersCommand = defineCommand278({
+var winnersCommand = defineCommand276({
   meta: {
     name: "winners",
     description: "Top winning ads for a specific advertiser id. Example: baker winning-ads winners adv_123 --top 15 --output md"
@@ -99372,7 +99443,7 @@ var winnersCommand = defineCommand278({
 });
 
 // src/commands/winning-ads/index.ts
-var winningAdsCommand = defineCommand279({
+var winningAdsCommand = defineCommand277({
   meta: {
     name: "winning-ads",
     description: `Search the ad-dna corpus of scored "winning" ads for reference creatives to reproduce, and manage the brands your library tracks. Proxied through the Baker backend (BAKER_API_KEY) \u2014 no separate token needed.
@@ -99380,7 +99451,7 @@ var winningAdsCommand = defineCommand279({
 Auth: BAKER_API_KEY (bk_ or bkr_) + BAKER_API_URL (your Convex .convex.site URL).
 
 Subcommands:
-  baker winning-ads search "<free text>"      \u2014 semantic search across the corpus; lean shortlist (advertiser, summary, scores, media_url)
+  baker winning-ads search "<free text>"      \u2014 semantic search, followed brands first; lean shortlist (advertiser, summary, scores, proof, media_url)
   baker winning-ads advertisers "<brand>"     \u2014 list corpus brands \u2192 advertiser ids (for --exclude-advertiser / --advertiser-id)
   baker winning-ads follow "<domain|url|brand>" --platform meta|linkedin|tiktok \u2014 add a brand's ads to your library
   baker winning-ads follow-competitors "<domain,domain,...>"   \u2014 add MANY brands at once (every competitor by domain)
@@ -99389,8 +99460,6 @@ Subcommands:
   baker winning-ads winners <advertiser>      \u2014 top winners for one advertiser id
   baker winning-ads content <ad-id>           \u2014 read ONE ad's transcript + on-screen text + copy (understand a reference before reproducing it)
   baker winning-ads unfollow <advertiser>     \u2014 stop following a brand
-  baker winning-ads brief                     \u2014 creative brief grounded in similar winners
-  baker winning-ads patterns --winners \u2026 --duds \u2026   \u2014 what separates a winning cohort from a weak one
   baker winning-ads hooks                     \u2014 top winner-weighted HOOK seeds for a segment (feed the seed to search --hook-archetype)
   baker winning-ads mechanisms                \u2014 top winner-weighted PRODUCT mechanism seeds (how the product claims to work)
   baker winning-ads formats                   \u2014 top winner-weighted static FORMAT patterns for a segment
@@ -99406,7 +99475,7 @@ Examples:
   baker winning-ads content adg_123 --full --output md
   baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
   baker winning-ads search "fintech onboarding" --hook-archetype callout --winner-category winner --output md
-  baker winning-ads patterns --winners a_1,a_2 --duds a_9,a_8 --output md
+  baker winning-ads search --format-pattern comparison_table --sort longest_running --output md
 Full guide: __tooling__/docs/tools/baker/winning-ads.md`
   },
   subCommands: {
@@ -99419,8 +99488,6 @@ Full guide: __tooling__/docs/tools/baker/winning-ads.md`
     winners: winnersCommand,
     content: contentCommand,
     unfollow: unfollowCommand,
-    brief: briefCommand,
-    patterns: patternsCommand,
     hooks: hooksCommand,
     mechanisms: mechanismsCommand,
     formats: formatsCommand
@@ -99444,7 +99511,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand280({
+var main = defineCommand278({
   meta: {
     name: "baker",
     version: getCliVersion(),