@koda-sl/baker-cli 0.142.0 → 0.145.0

package/README.md

@@ -42,7 +42,7 @@ export BAKER_CHAT_ID="<chat-id>"
 - `BAKER_GA4_PROPERTY_ID` — default GA4 property ID. Used when `--property-id` is not passed. If neither is set and exactly one property is connected, it is auto-selected.
 - `BAKER_GSC_SITE_URL` — default GSC site URL. Used when `--site-url` is not passed. If neither is set and exactly one site is verified, it is auto-selected.
 - `BAKER_X_ADS_ACCOUNT_ID` — default X Ads account ID (base36). Used when `--account-id` is not passed. If neither is set and exactly one X Ads account is connected, it is auto-selected.
-- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled Action create/update/delete. `scheduled-actions trigger` does not require it.
+- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled Action create/update/delete. `scheduled-actions trigger` does not require it. When set, it is also sent as an `x-baker-chat-id` header on every request, so library additions that apply immediately (images, videos, followed brands) are listed in that chat's changes as already applied.
 
 ## Debug logging
 
@@ -2132,7 +2132,11 @@ baker videos search "tutorial" --tags explainer,ugc --limit 5
 
 ### `baker videos get <id>`
 
-Get a single video by ID.
+Get a single video by ID. `--full` includes the auto-generated **transcript** (Baker transcribes every upload with speech-to-text), a `transcript_segment_count`, and the titled/timestamped **scene breakdown** — so you can read what a clip says and shows without watching it. Default JSON also returns the raw `transcript` + timed `transcriptSegments`; `--full` is what surfaces them in `--output md`/`files` too.
+
+```bash
+baker videos get j571abc123 --full --output md
+```
 
 ### `baker videos upload <file>`
 
@@ -2326,6 +2330,16 @@ Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winner
 baker winning-ads winners adv_123 --top 15 --output md
 ```
 
+### `baker winning-ads content <ad-id>`
+
+Read what's **inside** one ad → `GET /api/ad-library/ad-content`. `search`/`winners`/`feed` return a lean shortlist; this opens a single `ad_id` so you can understand a reference before reproducing it. For a **video** it returns the spoken `transcript`, the `on_screen_text` overlays, and the ad `copy` (`primary_text`/`headline`/`cta`); a **static** ad returns only the copy. Add `--full` for speech (voiceover style, speaker count, direct-address), pacing (scene count, shot length, key timeline moments), any recognised soundtrack, and each on-screen overlay's role + position (e.g. `GLOBAL PAYROLL @0.5s [hook, top]`) so you can place text faithfully. `--platform meta|linkedin` selects which platform the id is on (default `meta`).
+
+```bash
+baker winning-ads content adg_123                          # transcript + on-screen text + copy
+baker winning-ads content adg_123 --platform meta --full   # + speech, pacing, soundtrack
+baker winning-ads content adg_123 --full --output md
+```
+
 ### `baker winning-ads unfollow <advertiser>`
 
 Stop following a brand by advertiser id → `POST /api/ad-library/unfollow`. Returns `{ removed }`.

package/dist/{chunk-PEBP6G74.js → chunk-FBUVCOH6.js}

@@ -1,6 +1,6 @@
 import {
   apiGet
-} from "./chunk-SCI57ZZ6.js";
+} from "./chunk-LVCBCJWF.js";
 import {
   getEnv
 } from "./chunk-RK67WL4O.js";
@@ -261,4 +261,4 @@ export {
   writeAdsOutput,
   resolveCustomerId
 };
-//# sourceMappingURL=chunk-PEBP6G74.js.map
+//# sourceMappingURL=chunk-FBUVCOH6.js.map

package/dist/{chunk-SCI57ZZ6.js → chunk-LVCBCJWF.js}

@@ -62,6 +62,10 @@ function sanitizeParams(params) {
   }
   return sanitized;
 }
+function chatHeader() {
+  const chatId = getEnv().BAKER_CHAT_ID;
+  return chatId ? { "x-baker-chat-id": chatId } : {};
+}
 function mapHttpError(status) {
   if (status === 401 || status === 403) {
     return "UNAUTHORIZED";
@@ -117,7 +121,8 @@ async function apiGet(path, params) {
       method: "GET",
       headers: {
         Authorization: `Bearer ${env.BAKER_API_KEY}`,
-        Accept: "application/json"
+        Accept: "application/json",
+        ...chatHeader()
       },
       signal: AbortSignal.timeout(6e4)
     });
@@ -151,7 +156,8 @@ async function apiPost(path, body, opts) {
       headers: {
         Authorization: `Bearer ${env.BAKER_API_KEY}`,
         "Content-Type": "application/json",
-        Accept: "application/json"
+        Accept: "application/json",
+        ...chatHeader()
       },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(timeoutMs)
@@ -189,4 +195,4 @@ export {
   apiGet,
   apiPost
 };
-//# sourceMappingURL=chunk-SCI57ZZ6.js.map
+//# sourceMappingURL=chunk-LVCBCJWF.js.map

package/dist/chunk-LVCBCJWF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import { debugLogHttp, readBodyForLog } from \"./debugLog.ts\";\nimport { getEnv } from \"./env.ts\";\n\nconst MAX_RATE_LIMIT_RETRIES = 3;\nconst MAX_TOTAL_WAIT_MS = 2 * 60 * 1000;\n\nasync function fetchWithRateLimitRetry(url: string, init: RequestInit): Promise<Response> {\n  let totalWaited = 0;\n\n  for (let attempt = 0; attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {\n    const response = await fetch(url, init);\n\n    if (response.status !== 429 || attempt >= MAX_RATE_LIMIT_RETRIES) {\n      return response;\n    }\n\n    const retryAfterHeader = response.headers.get(\"Retry-After\");\n    const waitMs = retryAfterHeader ? Number(retryAfterHeader) * 1000 : 2000 * 2 ** attempt;\n\n    if (totalWaited + waitMs > MAX_TOTAL_WAIT_MS) {\n      return response;\n    }\n\n    totalWaited += waitMs;\n    await new Promise((resolve) => setTimeout(resolve, waitMs));\n  }\n\n  return fetch(url, init);\n}\n\ntype ErrorCode =\n  | \"UNAUTHORIZED\"\n  | \"NOT_FOUND\"\n  | \"VALIDATION_ERROR\"\n  | \"RATE_LIMITED\"\n  | \"INTERNAL_ERROR\"\n  | \"NETWORK_ERROR\"\n  | \"TIMEOUT\"\n  | \"IMAGE_PROCESSING_ERROR\";\n\nexport class ApiError extends Error {\n  code: ErrorCode;\n\n  constructor(code: ErrorCode, message: string) {\n    super(message);\n    this.name = \"ApiError\";\n    this.code = code;\n  }\n}\n\nconst CONVEX_ID_RE = /^[a-zA-Z0-9_]+$/;\n\nfunction hasControlCharacters(value: string): boolean {\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    // Allow tab (9), newline (10), carriage return (13)\n    if (code < 32 && code !== 9 && code !== 10 && code !== 13) {\n      return true;\n    }\n  }\n  return false;\n}\n\nfunction validateStringValue(value: string): void {\n  if (hasControlCharacters(value)) {\n    throw new ApiError(\"VALIDATION_ERROR\", \"String value contains invalid control characters\");\n  }\n}\n\nexport function validateConvexId(id: string): void {\n  if (!CONVEX_ID_RE.test(id)) {\n    throw new ApiError(\"VALIDATION_ERROR\", `Invalid ID format: \"${id}\". Expected alphanumeric string.`);\n  }\n}\n\nfunction sanitizeParams(params: Record<string, string>): Record<string, string> {\n  const sanitized: Record<string, string> = {};\n  for (const [key, value] of Object.entries(params)) {\n    validateStringValue(value);\n    sanitized[key] = value;\n  }\n  return sanitized;\n}\n\n/**\n * Sent on every call so the backend can attribute immediately-applied writes\n * (library images and videos, followed advertisers) to the Session they were\n * made from. Absent outside a chat-attached environment.\n */\nfunction chatHeader(): Record<string, string> {\n  const chatId = getEnv().BAKER_CHAT_ID;\n  return chatId ? { \"x-baker-chat-id\": chatId } : {};\n}\n\nfunction mapHttpError(status: number): ErrorCode {\n  if (status === 401 || status === 403) {\n    return \"UNAUTHORIZED\";\n  }\n  if (status === 404) {\n    return \"NOT_FOUND\";\n  }\n  if (status === 422 || status === 400) {\n    return \"VALIDATION_ERROR\";\n  }\n  if (status === 429) {\n    return \"RATE_LIMITED\";\n  }\n  return \"INTERNAL_ERROR\";\n}\n\nasync function handleResponse<T>(response: Response): Promise<T> {\n  const body = await response.text();\n\n  if (!response.ok) {\n    let message = `HTTP ${response.status}: ${response.statusText}`;\n    try {\n      const parsed = JSON.parse(body) as { error?: string | { message?: string }; message?: string };\n      if (typeof parsed.error === \"string\") {\n        message = parsed.error;\n      } else if (parsed.error?.message) {\n        message = parsed.error.message;\n      } else if (parsed.message) {\n        message = parsed.message;\n      }\n    } catch {\n      // Use default message\n    }\n    throw new ApiError(mapHttpError(response.status), message);\n  }\n\n  try {\n    return JSON.parse(body) as T;\n  } catch {\n    throw new ApiError(\"INTERNAL_ERROR\", \"Failed to parse API response as JSON\");\n  }\n}\n\nexport async function apiGet<T>(path: string, params?: Record<string, string>): Promise<T> {\n  const env = getEnv();\n  const url = new URL(path, env.BAKER_API_URL);\n  if (params) {\n    const clean = sanitizeParams(params);\n    for (const [key, value] of Object.entries(clean)) {\n      url.searchParams.set(key, value);\n    }\n  }\n\n  const urlStr = url.toString();\n  const startedAt = Date.now();\n  let response: Response;\n  try {\n    response = await fetchWithRateLimitRetry(urlStr, {\n      method: \"GET\",\n      headers: {\n        Authorization: `Bearer ${env.BAKER_API_KEY}`,\n        Accept: \"application/json\",\n        ...chatHeader(),\n      },\n      signal: AbortSignal.timeout(60_000),\n    });\n  } catch (err) {\n    debugLogHttp({ source: \"cli\", method: \"GET\", url: urlStr, durationMs: Date.now() - startedAt, error: err });\n    if (err instanceof Error && (err.name === \"TimeoutError\" || err.name === \"AbortError\")) {\n      throw new ApiError(\"TIMEOUT\", \"Request timed out after 60 seconds\");\n    }\n    throw new ApiError(\"NETWORK_ERROR\", `Request failed: ${err instanceof Error ? err.message : \"Unknown error\"}`);\n  }\n\n  debugLogHttp({\n    source: \"cli\",\n    method: \"GET\",\n    url: urlStr,\n    status: response.status,\n    ok: response.ok,\n    responseBody: await readBodyForLog(response),\n    durationMs: Date.now() - startedAt,\n  });\n  return handleResponse<T>(response);\n}\n\nexport async function apiPost<T>(path: string, body: unknown, opts?: { timeoutMs?: number }): Promise<T> {\n  const env = getEnv();\n  const timeoutMs = opts?.timeoutMs ?? 60_000;\n  const urlStr = new URL(path, env.BAKER_API_URL).toString();\n  const startedAt = Date.now();\n  let response: Response;\n  try {\n    response = await fetchWithRateLimitRetry(urlStr, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${env.BAKER_API_KEY}`,\n        \"Content-Type\": \"application/json\",\n        Accept: \"application/json\",\n        ...chatHeader(),\n      },\n      body: JSON.stringify(body),\n      signal: AbortSignal.timeout(timeoutMs),\n    });\n  } catch (err) {\n    debugLogHttp({\n      source: \"cli\",\n      method: \"POST\",\n      url: urlStr,\n      requestBody: body,\n      durationMs: Date.now() - startedAt,\n      error: err,\n    });\n    if (err instanceof Error && (err.name === \"TimeoutError\" || err.name === \"AbortError\")) {\n      throw new ApiError(\"TIMEOUT\", `Request timed out after ${Math.round(timeoutMs / 1000)} seconds`);\n    }\n    throw new ApiError(\"NETWORK_ERROR\", `Request failed: ${err instanceof Error ? err.message : \"Unknown error\"}`);\n  }\n\n  debugLogHttp({\n    source: \"cli\",\n    method: \"POST\",\n    url: urlStr,\n    requestBody: body,\n    status: response.status,\n    ok: response.ok,\n    responseBody: await readBodyForLog(response),\n    durationMs: Date.now() - startedAt,\n  });\n  return handleResponse<T>(response);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-BFZELBTE.js → chunk-UFBKUMN2.js}

@@ -1,10 +1,10 @@
 import {
   handleConnectionError,
   writeAdsJson
-} from "./chunk-PEBP6G74.js";
+} from "./chunk-FBUVCOH6.js";
 import {
   ApiError
-} from "./chunk-SCI57ZZ6.js";
+} from "./chunk-LVCBCJWF.js";
 import {
   getEnv
 } from "./chunk-RK67WL4O.js";
@@ -94,4 +94,4 @@ export {
   csvOrJson,
   resolveEffectiveStatus
 };
-//# sourceMappingURL=chunk-BFZELBTE.js.map
+//# sourceMappingURL=chunk-UFBKUMN2.js.map

package/dist/cli.js

@@ -43,7 +43,7 @@ import {
   resolveAccountIdArg,
   resolveEffectiveStatus,
   todayIso
-} from "./chunk-BFZELBTE.js";
+} from "./chunk-UFBKUMN2.js";
 import {
   buildQueryCacheKey,
   cacheGet,
@@ -56,13 +56,13 @@ import {
   writeAdsJson,
   writeAdsOutput,
   writeJsonEnvelope
-} from "./chunk-PEBP6G74.js";
+} from "./chunk-FBUVCOH6.js";
 import {
   ApiError,
   apiGet,
   apiPost,
   validateConvexId
-} from "./chunk-SCI57ZZ6.js";
+} from "./chunk-LVCBCJWF.js";
 import {
   installStreamTaps,
   logInvocation
@@ -73,7 +73,7 @@ import {
 } from "./chunk-RK67WL4O.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand177, runMain } from "citty";
+import { defineCommand as defineCommand178, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand18 } from "citty";
@@ -145,6 +145,22 @@ function compactVideo(video) {
     status: String(video.status ?? "")
   };
 }
+function sceneLines(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((s) => {
+    const scene = asRecord(s);
+    const title = typeof scene.title === "string" ? scene.title : "";
+    if (!title) {
+      return [];
+    }
+    const start = round2(scene.startSecond);
+    const end = round2(scene.endSecond);
+    const range = start !== null && end !== null ? ` (${start}-${end}s)` : "";
+    return [`${title}${range}`];
+  });
+}
 function fullVideo(video) {
   const compact = compactVideo(video);
   return {
@@ -152,6 +168,12 @@ function fullVideo(video) {
     duration: video.duration ?? null,
     muxPlaybackId: String(video.muxPlaybackId ?? ""),
     source: String(video.source ?? ""),
+    // The spoken transcript + AI scene breakdown of the client's own clip — the
+    // "understand what's in this video" payload. Kept out of the compact/search
+    // projection (too large for a list) and surfaced here on --full.
+    transcript: video.transcript ?? null,
+    transcript_segment_count: Array.isArray(video.transcriptSegments) ? video.transcriptSegments.length : 0,
+    scenes: sceneLines(video.scenes),
     createdAt: video.createdAt ?? null
   };
 }
@@ -243,6 +265,76 @@ function winningAdNormalizer(record, full) {
   }
   return compactWinningAd(record);
 }
+function overlayLines(value, detailed = false) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((o) => {
+    const item = asRecord(o);
+    const text = typeof item.text === "string" ? item.text : "";
+    if (!text) {
+      return [];
+    }
+    const at = round2(item.appears_at_s);
+    let line = at !== null ? `${text} @${at}s` : text;
+    if (detailed) {
+      const tags = [item.role, item.position].filter((t) => typeof t === "string" && t.length > 0);
+      if (tags.length) {
+        line += ` [${tags.join(", ")}]`;
+      }
+    }
+    return [line];
+  });
+}
+function compactAdContent(record) {
+  return {
+    ad_id: record.ad_id ?? null,
+    advertiser: record.advertiser ?? null,
+    format: record.format ?? null,
+    media_kind: record.media_kind ?? null,
+    media_url: record.media_url ?? null,
+    summary: record.summary ?? null,
+    transcript: record.transcript ?? null,
+    on_screen_text: overlayLines(record.on_screen_text),
+    has_captions: typeof record.has_captions === "boolean" ? record.has_captions : null,
+    primary_text: record.primary_text ?? null,
+    headline: record.headline ?? null,
+    cta: record.cta ?? null
+  };
+}
+function fullAdContent(record) {
+  const speech = asRecord(record.speech);
+  const pacing = asRecord(record.pacing);
+  const music = asRecord(record.music);
+  return {
+    ...compactAdContent(record),
+    platform: record.platform ?? null,
+    // Re-derive with role/position tags — the lean compact version dropped them.
+    on_screen_text: overlayLines(record.on_screen_text, true),
+    winner_score: round2(record.winner_score),
+    winner_category: record.winner_category ?? null,
+    angle: record.angle ?? null,
+    hook_archetype: record.hook_archetype ?? null,
+    caption_style: record.caption_style ?? null,
+    has_speech: typeof record.has_speech === "boolean" ? record.has_speech : null,
+    speech_pct_of_runtime: round2(speech.speech_pct_of_runtime),
+    speaker_count: speech.speaker_count ?? null,
+    voiceover_vs_sync: speech.voiceover_vs_sync ?? null,
+    is_direct_address: typeof speech.is_direct_address === "boolean" ? speech.is_direct_address : null,
+    speech_emotion_dominant: speech.speech_emotion_dominant ?? null,
+    scene_count: pacing.scene_count ?? null,
+    avg_shot_length_s: round2(pacing.avg_shot_length_s),
+    pacing_shape: pacing.pacing_shape ?? null,
+    hook_ends_at_s: round2(pacing.hook_ends_at_s),
+    cta_first_shown_at_s: round2(pacing.cta_first_shown_at_s),
+    product_first_appears_at_s: round2(pacing.product_first_appears_at_s),
+    music_track_title: music.track_title ?? null,
+    music_track_artist: music.track_artist ?? null
+  };
+}
+function adContentNormalizer(record, full) {
+  return full ? fullAdContent(record) : compactAdContent(record);
+}
 function applyFieldMask(data, fields) {
   const result = {};
   for (const field of fields) {
@@ -1135,6 +1227,65 @@ var seedCatalogResponseSchema = z2.object({
   segment: seedCatalogSegmentSchema.nullable(),
   patterns: z2.array(patternSeedSchema)
 });
+var adContentRequestSchema = z2.object({
+  ad_id: z2.string().min(1),
+  platform: adLibraryPlatformSchema.optional()
+});
+var adContentOverlaySchema = z2.object({
+  text: z2.string(),
+  appears_at_s: z2.number().nullable(),
+  position: z2.string().nullable(),
+  role: z2.string().nullable()
+});
+var adContentSpeechSchema = z2.object({
+  speech_pct_of_runtime: z2.number().nullable(),
+  speaker_count: z2.number().nullable(),
+  voiceover_vs_sync: z2.string().nullable(),
+  is_direct_address: z2.boolean().nullable(),
+  speech_emotion_dominant: z2.string().nullable()
+});
+var adContentPacingSchema = z2.object({
+  scene_count: z2.number().nullable(),
+  avg_shot_length_s: z2.number().nullable(),
+  pacing_shape: z2.string().nullable(),
+  hook_ends_at_s: z2.number().nullable(),
+  cta_first_shown_at_s: z2.number().nullable(),
+  product_first_appears_at_s: z2.number().nullable()
+});
+var adContentMusicSchema = z2.object({
+  track_title: z2.string().nullable(),
+  track_artist: z2.string().nullable()
+});
+var adContentSchema = z2.object({
+  ad_id: z2.string().nullable(),
+  advertiser: z2.string().nullable(),
+  advertiser_id: z2.string().nullable(),
+  platform: z2.string().nullable(),
+  format: z2.string().nullable(),
+  media_kind: z2.string().nullable(),
+  media_url: z2.string().nullable(),
+  winner_score: z2.number().nullable(),
+  winner_category: z2.string().nullable(),
+  summary: z2.string().nullable(),
+  angle: z2.string().nullable(),
+  hook_archetype: z2.string().nullable(),
+  // Spoken words (video only; null when the ad has no speech track).
+  transcript: z2.string().nullable(),
+  has_speech: z2.boolean().nullable(),
+  speech: adContentSpeechSchema,
+  // On-screen text / captions.
+  has_captions: z2.boolean().nullable(),
+  caption_style: z2.string().nullable(),
+  on_screen_text: z2.array(adContentOverlaySchema),
+  // Copy the viewer reads outside the media.
+  primary_text: z2.string().nullable(),
+  headline: z2.string().nullable(),
+  cta: z2.string().nullable(),
+  // Structure + soundtrack.
+  pacing: adContentPacingSchema,
+  music: adContentMusicSchema
+});
+var adContentResponseSchema = z2.object({ ad: adContentSchema });
 
 // ../api/src/ads-linkedin/limits.ts
 var LINKEDIN_LIMITS = {
@@ -1980,6 +2131,10 @@ var chatChangeTypeSchema = z5.enum([
   "linkedin-ads",
   "google-ads",
   "meta-ads",
+  // Immediate (already-applied) library effects — see lib/chatChanges.ts.
+  "image",
+  "video",
+  "followed-advertiser",
   "briefs"
 ]);
 var chatChangeActionSchema = z5.enum(["created", "updated", "deleted"]);
@@ -4923,7 +5078,7 @@ var demandGenAdSchema = z12.object({
   squareImageAssets: z12.array(refSchema).optional(),
   logoImageAssets: z12.array(refSchema).optional()
 });
-var adContentSchema = z12.discriminatedUnion("format", [
+var adContentSchema2 = z12.discriminatedUnion("format", [
   responsiveSearchAdSchema,
   responsiveDisplayAdSchema,
   callAdSchema,
@@ -4934,7 +5089,7 @@ var adContentSchema = z12.discriminatedUnion("format", [
 var adCreateSchema = z12.object({
   adGroup: refSchema,
   status: stageableStatusSchema2.default("PAUSED"),
-  content: adContentSchema
+  content: adContentSchema2
 });
 var adUpdateSchema = z12.object({
   status: z12.enum(["ENABLED", "PAUSED", "REMOVED"]).optional(),
@@ -12684,10 +12839,10 @@ function duplicateCommand2(entity, label) {
       replace: { type: "boolean", description: "Pause the original once the copy publishes" }
     },
     run: async ({ args }) => {
-      const { apiPost: apiPost2 } = await import("./client-N7XWYCHT.js");
+      const { apiPost: apiPost2 } = await import("./client-R5ZSVIK3.js");
       const { requireChatId: requireChatId2 } = await import("./env-3JMYIH25.js");
-      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-7M5VQPTZ.js");
-      const { handleMetaError: handleMetaError2 } = await import("./shared-6SZHAUM2.js");
+      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-R534QTMO.js");
+      const { handleMetaError: handleMetaError2 } = await import("./shared-MUWU7BK5.js");
       try {
         const accountId = bareAccountId2(args);
         const chatId = requireChatId2();
@@ -29434,7 +29589,7 @@ Full guide: __tooling__/docs/tools/baker/videos.md`
 });
 
 // src/commands/winning-ads/index.ts
-import { defineCommand as defineCommand176 } from "citty";
+import { defineCommand as defineCommand177 } from "citty";
 
 // src/commands/winning-ads/advertisers.ts
 import { defineCommand as defineCommand165 } from "citty";
@@ -29629,8 +29784,70 @@ var briefCommand = defineCommand166({
   }
 });
 
-// src/commands/winning-ads/feed.ts
+// src/commands/winning-ads/content.ts
 import { defineCommand as defineCommand167 } 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. Add --full for speech, pacing, and soundtrack detail. Video ads carry the transcript/on-screen text; static ads carry only the copy.",
+  args: {
+    "ad-id": { type: "string", description: "The ad id to open (from search/winners/feed results)", required: true },
+    platform: {
+      type: "string",
+      description: "Which platform the ad id is on: meta|linkedin (default meta)",
+      required: false
+    }
+  }
+});
+var contentCommand = defineCommand167({
+  meta: {
+    name: "content",
+    description: "Read the transcript + on-screen text + copy of one winning ad. Example: baker winning-ads content adg_123 --platform meta --full --output md"
+  },
+  args: {
+    "ad-id": { type: "positional", description: "Ad id (from search/winners/feed)", required: true },
+    platform: {
+      type: "string",
+      description: "Platform the ad id is on: meta|linkedin (default meta)",
+      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 },
+    full: {
+      type: "boolean",
+      description: "Include speech, pacing, and soundtrack detail",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = { id: String(args["ad-id"]) };
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const data = await apiGet("/api/ad-library/ad-content", params);
+      const output = args.output || "json";
+      const full = args.full;
+      const ad = data?.ad ?? {};
+      if (output === "json") {
+        writeJson({ ok: true, data: { ad: adContentNormalizer(ad, full) } });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: ad },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        adContentNormalizer
+      );
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+
+// src/commands/winning-ads/feed.ts
+import { defineCommand as defineCommand168 } from "citty";
 function buildFeedParams(input) {
   const params = {};
   const advertiser = splitList(input.advertiser);
@@ -29682,7 +29899,7 @@ registerSchema({
     format: { type: "string", description: "Comma-separated formats to include (e.g. static,video)", required: false }
   }
 });
-var feedCommand = defineCommand167({
+var feedCommand = defineCommand168({
   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"
@@ -29767,7 +29984,7 @@ var feedCommand = defineCommand167({
 });
 
 // src/commands/winning-ads/follow.ts
-import { defineCommand as defineCommand168 } from "citty";
+import { defineCommand as defineCommand169 } from "citty";
 var PLATFORMS = ["meta", "linkedin"];
 registerSchema({
   command: "winning-ads.follow",
@@ -29782,7 +29999,7 @@ registerSchema({
     label: { type: "string", description: "Optional display label (defaults to the resolved name)", required: false }
   }
 });
-var followCommand = defineCommand168({
+var followCommand = defineCommand169({
   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 both Meta + LinkedIn. Example: baker winning-ads follow "deel.com" --platform meta'
@@ -29829,7 +30046,7 @@ var followCommand = defineCommand168({
 });
 
 // src/commands/winning-ads/follow-competitors.ts
-import { defineCommand as defineCommand169 } from "citty";
+import { defineCommand as defineCommand170 } from "citty";
 var PLATFORMS2 = ["meta", "linkedin"];
 var BATCH_TIMEOUT_MS = 3e5;
 function buildFollowBatchBody(input) {
@@ -29862,7 +30079,7 @@ registerSchema({
     }
   }
 });
-var followCompetitorsCommand = defineCommand169({
+var followCompetitorsCommand = defineCommand170({
   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"'
@@ -29937,7 +30154,7 @@ var followCompetitorsCommand = defineCommand169({
 });
 
 // src/commands/winning-ads/following.ts
-import { defineCommand as defineCommand170 } from "citty";
+import { defineCommand as defineCommand171 } 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.",
@@ -29970,7 +30187,7 @@ function followingNormalizer(record, full) {
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };
 }
-var followingCommand = defineCommand170({
+var followingCommand = defineCommand171({
   meta: {
     name: "following",
     description: "List brands you follow, with status (ready / adding\u2026) and cached counts. Example: baker winning-ads following --output md"
@@ -30005,7 +30222,7 @@ var followingCommand = defineCommand170({
 });
 
 // src/commands/winning-ads/patterns.ts
-import { defineCommand as defineCommand171 } from "citty";
+import { defineCommand as defineCommand172 } 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.",
@@ -30044,7 +30261,7 @@ function discriminatorRow(record) {
     top_values_duds: Array.isArray(record.top_values_b) ? record.top_values_b.join(", ") : ""
   };
 }
-var patternsCommand = defineCommand171({
+var patternsCommand = defineCommand172({
   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"
@@ -30100,7 +30317,7 @@ var patternsCommand = defineCommand171({
 });
 
 // src/commands/winning-ads/search.ts
-import { defineCommand as defineCommand172 } from "citty";
+import { defineCommand as defineCommand173 } from "citty";
 registerSchema({
   command: "winning-ads.search",
   description: "Search the ad-dna corpus of scored winning ads. Returns a lean shortlist (advertiser, summary, scores, media_url) to pick a reference to reproduce.",
@@ -30208,7 +30425,7 @@ function buildSearchBody(args) {
   }
   return body;
 }
-var searchCommand4 = defineCommand172({
+var searchCommand4 = defineCommand173({
   meta: {
     name: "search",
     description: "Search winning reference ads. Example: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --winner-category winner --exclude-advertiser adv_123 --output md"
@@ -30323,7 +30540,7 @@ var searchCommand4 = defineCommand172({
 });
 
 // src/commands/winning-ads/seeds.ts
-import { defineCommand as defineCommand173 } from "citty";
+import { defineCommand as defineCommand174 } from "citty";
 function leanRow(r) {
   return {
     key: r.key,
@@ -30351,7 +30568,7 @@ function makeSeedCommand(opts) {
       limit: { type: "number", description: "Max keys 1-100 (default 20)", required: false, default: 20 }
     }
   });
-  return defineCommand173({
+  return defineCommand174({
     meta: { name: opts.name, description: opts.description },
     args: {
       platform: { type: "string", description: "Single platform to segment on", required: false },
@@ -30400,7 +30617,7 @@ var formatsCommand = makeSeedCommand({
 });
 
 // src/commands/winning-ads/unfollow.ts
-import { defineCommand as defineCommand174 } from "citty";
+import { defineCommand as defineCommand175 } from "citty";
 registerSchema({
   command: "winning-ads.unfollow",
   description: "Stop following a brand \u2014 removes it from your ad-dna library by advertiser id.",
@@ -30408,7 +30625,7 @@ registerSchema({
     advertiser: { type: "string", description: "Advertiser id to unfollow", required: true }
   }
 });
-var unfollowCommand = defineCommand174({
+var unfollowCommand = defineCommand175({
   meta: {
     name: "unfollow",
     description: "Stop following a brand by advertiser id. Example: baker winning-ads unfollow adv_123"
@@ -30429,7 +30646,7 @@ var unfollowCommand = defineCommand174({
 });
 
 // src/commands/winning-ads/winners.ts
-import { defineCommand as defineCommand175 } from "citty";
+import { defineCommand as defineCommand176 } 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.",
@@ -30439,7 +30656,7 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false }
   }
 });
-var winnersCommand = defineCommand175({
+var winnersCommand = defineCommand176({
   meta: {
     name: "winners",
     description: "Top winning ads for a specific advertiser id. Example: baker winning-ads winners adv_123 --top 15 --output md"
@@ -30489,7 +30706,7 @@ var winnersCommand = defineCommand175({
 });
 
 // src/commands/winning-ads/index.ts
-var winningAdsCommand = defineCommand176({
+var winningAdsCommand = defineCommand177({
   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.
@@ -30504,6 +30721,7 @@ Subcommands:
   baker winning-ads following                 \u2014 list brands you follow (status + counts)
   baker winning-ads feed                      \u2014 winners across EVERY brand you follow; trim with --advertiser
   baker winning-ads winners <advertiser>      \u2014 top winners for one advertiser id
+  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
@@ -30519,6 +30737,7 @@ Examples:
   baker winning-ads feed --per-advertiser 5 --output md
   baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
   baker winning-ads winners adv_123 --top 15 --output md
+  baker winning-ads 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
@@ -30532,6 +30751,7 @@ Full guide: __tooling__/docs/tools/baker/winning-ads.md`
     following: followingCommand,
     feed: feedCommand,
     winners: winnersCommand,
+    content: contentCommand,
     unfollow: unfollowCommand,
     brief: briefCommand,
     patterns: patternsCommand,
@@ -30558,7 +30778,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand177({
+var main = defineCommand178({
   meta: {
     name: "baker",
     version: getCliVersion(),