@koda-sl/baker-cli 0.423.0 → 0.424.0

package/README.md

@@ -3360,7 +3360,7 @@ baker winning-ads search "delivery driver recruitment" --audience-temperature 0_
 | `--scope followed-first\|followed\|all` | Which brands to draw from (default `followed-first`: the company's followed brands, topped up from the shared library; the whole library when it follows nobody) |
 | `--sort winner\|longest_running\|newest` | Order of a no-query browse (default `winner`); ignored when a query is given |
 | `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
-| `--max-per-advertiser <n>` | Cap results per advertiser 0–50 (default 3; `0` = no cap) |
+| `--max-per-advertiser <n>` | Unset (default): brands spread, each brand's best 3 first and the rest after the other brands, none dropped. `1`–`50`: drop a brand's ads past N (`1` = one reference per brand). `0`: rank order. Brands the query names ("HubSpot video ads") are never capped |
 | `--min-relevance <0-1>` | Relevance floor; trims weak matches |
 | `--platform <list>` | `meta,linkedin,tiktok` — pass a single value to search **only** that platform |
 | `--format <list>` | `video,static,carousel` |
@@ -3372,15 +3372,17 @@ baker winning-ads search "delivery driver recruitment" --audience-temperature 0_
 | `--exclude-brand-reliant` | Drop ads whose copy only works if the viewer already knows the brand (ads not judged yet are kept) |
 | `--advertiser-id <list>` | **Restrict to** these advertiser ids (browse one brand's winners) |
 | `--exclude-advertiser <list>` | **Drop** these advertiser ids, usually your own brand |
-| `--country <list>` / `--language <list>` | Filter by country / language codes |
+| `--country <list>` | ISO country codes: ads known to run there, plus ads with no country data (every Meta ad) in that country's main language |
+| `--language <list>` | ISO 639-1 codes (`es,en`) for the language of the ad's copy and voiceover |
 | `--first-seen-after` / `--first-seen-before` | ISO date (`2026-01-01`, read as the start of that day in UTC) or datetime bounds (recency) |
 | `--hook-archetype <list>` | Narrow to ads on a proven hook **seed** (from `winning-ads hooks`) |
 | `--format-pattern <list>` | Narrow to statics in these containers (from `winning-ads formats`, e.g. `comparison_table`) |
 | `--diverse` | One varied page (different brands, containers, hooks) instead of rank order; ignores paging |
 | `--output json\|md\|files` | Output format (default json) |
+| `--fields <list>` | Only these row fields (e.g. `advertiser,container,mechanism`); a `--full`-only field turns `--full` on, an unknown one is refused with `error.fix.validValues` |
 | `--full` | Include DNA detail + longevity |
 
-A value outside a closed list (`--platform`, `--format`, `--winner-category`, `--awareness`, `--audience-temperature`, `--funnel-stage`, `--advertiser-size`, `--format-pattern`), a non-numeric `--limit`/`--max-per-advertiser`/`--min-relevance`, or a bound that is not a date is refused before the search runs; a refused list value comes with `error.fix.validValues`. References this company already adapted (`already_adapted`) never take a fresh reference's place: `--limit N` returns up to N fresh ones first. The search waits up to 120 s (`followed-first` can run two library searches).
+A value outside a closed list (`--platform`, `--format`, `--winner-category`, `--awareness`, `--audience-temperature`, `--funnel-stage`, `--advertiser-size`, `--format-pattern`), a non-numeric `--limit`/`--max-per-advertiser`/`--min-relevance`, or a bound that is not a date is refused before the search runs; a refused list value comes with `error.fix.validValues`. References this company already adapted (`already_adapted`) never take a fresh reference's place: `--limit N` returns up to N fresh ones first. The search waits up to 120 s (`followed-first` can run two library searches). A library that does not answer in time is `UNAVAILABLE`, with an `error.fix` to retry once narrower. An empty answer carries a hint naming the one filter to loosen.
 
 Reading the scores: **`relevance`** (0–1) = match of the creative to your query; **`winner_score`** = how proven the ad is in-market. Pick references that are both relevant *and* proven.
 
@@ -3454,7 +3456,7 @@ Winners across **every** brand you follow, in one library → `GET /api/ad-libra
 Response `data`: `winners`, `following_count` (how many brands you follow), `advertiser_ids` (the ids actually queried = follows ∩ requested), and — when relevant — `hints` (e.g. you follow nobody yet, or a requested id isn't in your follows and was skipped). In `--output md`/`files` the table is the payload and the hints are written to **stderr** so they still surface without corrupting the output.
 
 ```bash
-baker winning-ads feed --per-advertiser 5 --output md
+baker winning-ads feed --output md
 baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
 ```
 
@@ -3462,7 +3464,7 @@ baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
 |---|---|
 | `--advertiser <ids>` | Trim to a comma-separated subset of your followed advertiser ids (ids you don't follow are skipped and reported) |
 | `--platform meta\|linkedin` | Filter to a single platform |
-| `--per-advertiser <n>` | Max winners kept per advertiser 0–50 (`0` = no cap, default 5) |
+| `--per-advertiser <n>` | Unset (default): brands spread, each brand's best 3 first and the rest after, none dropped. `1`–`50`: keep at most N per brand. `0`: rank order |
 | `--limit <n>` | Total winners across all follows 1–200 (default 40) |
 | `--winner-category <list>` | Restrict to specific winner categories |
 | `--format <list>` | Restrict to specific formats (e.g. `static,video`) |

package/dist/{chunk-5JVAP5DC.js → chunk-FQOKJYKN.js}

@@ -1391,8 +1391,11 @@ export {
   compactVideo,
   videoNormalizer,
   testimonialNormalizer,
+  compactWinningAd,
+  fullWinningAd,
   winningAdNormalizer,
   adContentNormalizer,
+  applyFieldMask,
   writeJson,
   writeOutput,
   getEnv,
@@ -1412,4 +1415,4 @@ export {
   captureVimeoCookie,
   childEnvWith
 };
-//# sourceMappingURL=chunk-5JVAP5DC.js.map
+//# sourceMappingURL=chunk-FQOKJYKN.js.map

package/dist/{chunk-S36N4SOX.js → chunk-GCTR4MDE.js}

@@ -1,6 +1,6 @@
 import {
   debugLogSetting
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // src/debugLog.ts
 import { appendFileSync, mkdirSync, renameSync, statSync } from "fs";
@@ -212,4 +212,4 @@ export {
   readBodyForLog,
   installStreamTaps
 };
-//# sourceMappingURL=chunk-S36N4SOX.js.map
+//# sourceMappingURL=chunk-GCTR4MDE.js.map

package/dist/{chunk-SWYBHYB5.js → chunk-IR4ZOEZV.js}

@@ -1,7 +1,7 @@
 import {
   debugLogHttp,
   readBodyForLog
-} from "./chunk-S36N4SOX.js";
+} from "./chunk-GCTR4MDE.js";
 import {
   API_KEY_FORMAT_MESSAGE,
   DIRECT_ROUTE,
@@ -22,7 +22,7 @@ import {
   refuseNonPublicUrl,
   requireConnection,
   shouldEscalate
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
@@ -1040,10 +1040,15 @@ var winnersSearchFields = z2.object({
   // Pagination offset for infinite scroll. The browse view (no query) scrolls
   // the whole library; a text/similar search scrolls its bounded ranked pool.
   offset: z2.number().int().min(0).optional(),
-  // Per-advertiser cap. `0` = no cap (the library browse view sends it so a
-  // facet-filtered slice shows every winner and matches the facet-rail count);
-  // omit it to keep the service default cap for diverse cross-brand discovery.
+  // Per-advertiser cap: past it a brand's ads are dropped. `0` = no cap (the
+  // library browse view sends it so a facet-filtered slice shows every winner
+  // and matches the facet-rail count); omit it to spread the brands instead,
+  // three each at the top and none dropped.
   max_per_advertiser: z2.number().int().min(0).max(50).optional(),
+  // ad-dna reads one advertiser in `advertiser_ids` as browsing that brand, and
+  // keeps its measured failures. `false` keeps it a reference search: what
+  // Baker sends when it narrowed to the company's followed brands itself.
+  brand_browse: z2.boolean().optional(),
   min_relevance: z2.number().min(0).max(1).optional(),
   // One page picked for variety (different brands, containers and hooks)
   // instead of rank order: a reference set for N concepts. Ignores offset.
@@ -24633,6 +24638,7 @@ export {
   actionTempIdSchema,
   ACTION_COMPLETE_NOTE_MIN,
   adLibraryPlatformSchema,
+  staticFormatPatternSchema,
   winnersSortSchema,
   winnerSearchScopeSchema,
   scopedWinnersSearchRequestSchema,
@@ -24916,4 +24922,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-SWYBHYB5.js.map
+//# sourceMappingURL=chunk-IR4ZOEZV.js.map