@koda-sl/baker-cli 0.394.0 → 0.395.0

package/README.md

@@ -3201,17 +3201,17 @@ Search the **ad-dna** corpus of scored "winning" competitor ads for reference cr
 
 ### `baker winning-ads search <query>`
 
-Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`, and `visual` (what the viewer sees) + `container` (a static's layout pattern) when known; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `mechanism`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`, and `visual` (what the viewer sees) + `container` (a static's layout pattern) + `mechanism` (why it works) when known; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
 
 > `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
 
-> Results are already de-junked and winner-first: the corpus auto-drops measured failures (duds, thrash) and ranks `final = relevance^0.25 × winner_score^0.75`. So `--winner-category winner` is usually unnecessary — it's a stricter filter that also removes `untested` (unproven-but-maybe-fresh) ads. Rely on the default + `--min-relevance`; only add `--winner-category` to force-exclude unproven creatives. (Restricting to a single `--advertiser-id` turns the failure-exclusion off — you then see that brand's duds too.)
+> Results are already de-junked and winner-first: the corpus auto-drops measured failures (duds, thrash) and ranks `final = relevance^0.25 × winner_score^0.75`. So `--winner-category winner` is usually unnecessary — it's a stricter filter that also removes `untested` (unproven-but-maybe-fresh) ads. Rely on the default + `--min-relevance`; only add `--winner-category` to force-exclude unproven creatives. (With a query, restricting to a single `--advertiser-id` turns the failure-exclusion and the per-advertiser cap off: you then see that brand's duds too. A search with no query is a browse, which always drops failures and `untested` ads. A company that follows one brand keeps both with `--scope followed`/`followed-first`.)
 
 ```bash
 # Only LinkedIn video ads:
 baker winning-ads search "B2B lead gen demo" --platform linkedin --format video --output md
-# Cross-platform, exclude our own brand + an advertiser we already mined:
-baker winning-ads search "fintech onboarding" --exclude-advertiser adv_ourbrand,adv_usedbefore --output md
+# Cross-platform, excluding our own brand (an ad we already adapted comes back last, marked already_adapted):
+baker winning-ads search "fintech onboarding" --exclude-advertiser adv_ourbrand --output md
 # Similar-to a reference ad, recent only:
 baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00:00Z --limit 5 --output md
 # One varied reference per concept (different brands, containers, hooks) in one call:
@@ -3225,22 +3225,24 @@ baker winning-ads search --format-pattern comparison_table --platform meta --out
 | `query` (positional) | Free-text natural-language query |
 | `--ref-ad-id <id>` | Find ads similar to this ad (instead of free text) |
 | `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
-| `--max-per-advertiser <n>` | Cap results per advertiser 1–50 (default 3) |
+| `--max-per-advertiser <n>` | Cap results per advertiser 0–50 (default 3; `0` = no cap) |
 | `--min-relevance <0-1>` | Relevance floor; trims weak matches |
-| `--platform <list>` | `meta,linkedin` — pass a single value to search **only** that platform |
+| `--platform <list>` | `meta,linkedin,tiktok` — pass a single value to search **only** that platform |
 | `--format <list>` | `video,static,carousel` |
 | `--winner-category <list>` | `winner,scaled_winner,evergreen,rising,untested,dud,…` (default: all) |
 | `--awareness <list>` | `unaware,problem_aware,solution_aware,product_aware,most_aware` |
 | `--advertiser-id <list>` | **Restrict to** these advertiser ids (browse one brand's winners) |
-| `--exclude-advertiser <list>` | **Drop** these advertiser ids — your own brand + already-used references |
+| `--exclude-advertiser <list>` | **Drop** these advertiser ids, usually your own brand |
 | `--country <list>` / `--language <list>` | Filter by country / language codes |
-| `--first-seen-after` / `--first-seen-before` | ISO datetime bounds (recency) |
+| `--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) |
 | `--full` | Include DNA detail + longevity |
 
+A value outside a closed list (`--platform`, `--format`, `--winner-category`, `--awareness`, `--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).
+
 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.
 
 ### `baker winning-ads hooks|mechanisms|formats`
@@ -3253,7 +3255,7 @@ guessing. The rollup is recomputed daily. (Distinct from `winning-ads patterns`,
 
 ```bash
 # Top winning hook seeds for problem-aware SaaS on Meta:
-baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
+baker winning-ads hooks --platform meta --awareness problem_aware --industry "Software & SaaS" --output md
 # Then narrow a reference search to that proven hook:
 baker winning-ads search "onboarding demo" --hook-archetype callout --output md
 # Also: mechanisms (how the product claims to work, not the ad's device), formats (static ad layouts):
@@ -3265,7 +3267,7 @@ baker winning-ads formats --awareness solution_aware --output md
 |---|---|
 | `--platform <p>` | Segment on a single platform |
 | `--awareness <stage>` | Segment on a single awareness stage |
-| `--industry <seed>` | Segment on a single industry seed |
+| `--industry <seed>` | Segment on a single industry seed from the extractor vocabulary (`seedVocabularies.yaml`), any case; a term naming exactly one seed resolves to it (`saas` → `Software & SaaS`), an ambiguous or unknown one is refused with the valid list |
 | `--limit <n>` | Max keys 1–100 (default 20) |
 | `--full` | Include the per-key segment breakdown |
 

package/dist/{chunk-53ATKV76.js → chunk-BRIJ4OWT.js}

@@ -967,6 +967,7 @@ function compactWinningAd(record) {
     media_url: String(record.media_url ?? ""),
     ...typeof dna.visual === "string" && dna.visual ? { visual: dna.visual } : {},
     ...typeof dna.container === "string" && dna.container ? { container: dna.container } : {},
+    ...typeof dna.mechanism === "string" && dna.mechanism ? { mechanism: dna.mechanism } : {},
     ...bakerUses(record.baker_uses),
     ...record.source === "followed" || record.source === "library" ? { source: record.source } : {}
   };
@@ -1310,4 +1311,4 @@ export {
   captureVimeoCookie,
   childEnvWith
 };
-//# sourceMappingURL=chunk-53ATKV76.js.map
+//# sourceMappingURL=chunk-BRIJ4OWT.js.map