@koda-sl/baker-cli 0.133.3 → 0.135.0

package/README.md

@@ -2185,7 +2185,7 @@ baker testimonials tags
 
 ### Winning Ads (`baker winning-ads`)
 
-Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`), and manage the brands your library tracks (`follow` / `following` / `unfollow`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
+Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`), and manage the brands your library tracks (`follow` / `following` / `feed` / `unfollow`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
 
 > The corpus has **Meta + LinkedIn** connectors, so `--platform` inputs are limited to `meta,linkedin`. (Older result rows may still carry a legacy platform string.)
 
@@ -2289,9 +2289,29 @@ List the brands you follow → `GET /api/ad-library/following`. Each row shows `
 baker winning-ads following --output md
 ```
 
+### `baker winning-ads feed`
+
+Winners across **every** brand you follow, in one library → `GET /api/ad-library/feed`. The advertiser set is derived server-side from your follows (never a client-supplied list), so this is the "what's winning across everyone I track" view. Start here, then trim to specific brands with `--advertiser adv_1,adv_2`. Capped per advertiser (`--per-advertiser`, default 5, `0` = no cap) so no single brand floods the feed — the cap is enforced server-side, so it holds even when you narrow to one advertiser. Same lean winner cards as `search` / `winners` (add `--full` for DNA + longevity).
+
+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 --advertiser adv_123,adv_456 --platform meta --output md
+```
+
+| Flag | Purpose |
+|---|---|
+| `--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) |
+| `--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`) |
+
 ### `baker winning-ads winners <advertiser>`
 
-Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winners`. Same lean winner cards as `search` (add `--full` for DNA + longevity). Supports `--top N` and `--platform meta|linkedin`.
+Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winners` (use `feed` for all your follows at once). Same lean winner cards as `search` (add `--full` for DNA + longevity). Supports `--top N` and `--platform meta|linkedin`.
 
 ```bash
 baker winning-ads winners adv_123 --top 15 --output md
@@ -2487,7 +2507,8 @@ Permissions enforced server-side:
 
 - Only `claim`/`release` mutate live state.
 - `claim` returns action details (`id`, `name`, `description`) plus `recommendedSkills` — a fast model reads the action's name/description/tags against the local `.claude/skills/` catalog and returns the skills (`{ name, reason }`) most worth loading for the work, echoed as `/skill — reason` lines in `hints`. It is best-effort: if the catalog is absent or the model call fails, the claim still succeeds and falls back to the generic "review and load relevant skills" hint.
-- `update`, `complete`, `discard`, `unlink` require the action to be claimed by the current chat — otherwise the API returns `FORBIDDEN` with a hint to claim first.
+- `complete` and `unlink` require the action to be claimed by the current chat — otherwise the API returns `FORBIDDEN` with a hint to claim first. Completing is the record that the work is done, so it stays claim-gated.
+- `update` and `discard` do NOT require a claim — a chat may edit or retire an action it never claimed. They are blocked only when another chat currently holds the claim (`CONFLICT` with that chat's title).
 - Claiming an action already claimed by another chat returns `CONFLICT` with the other chat's title — pick a different action.
 - All staged ops are reverted automatically when the chat is discarded.
 

package/dist/cli.js

@@ -73,7 +73,7 @@ import {
 } from "./chunk-RK67WL4O.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand171, runMain } from "citty";
+import { defineCommand as defineCommand172, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand18 } from "citty";
@@ -507,7 +507,7 @@ function readSkillCatalog(startDir) {
 // src/commands/actions/claim.ts
 registerSchema({
   command: "actions.claim",
-  description: "Claim an action for the current chat (live \u2014 visible to other chats immediately). Returns action details plus a fast-model recommendation of which skills to load for the work (`recommendedSkills`).",
+  description: "Claim an action for the current chat (live \u2014 visible to other chats immediately). Claim only what you're actively working on now: it's required before `complete`, but NOT for `update` or `discard` (those stage without a claim). Returns action details plus a fast-model recommendation of which skills to load for the work (`recommendedSkills`).",
   args: {
     id: { type: "string", description: "Action ID", required: true }
   }
@@ -536,7 +536,7 @@ function buildHints(recommendations) {
 var claimCommand = defineCommand({
   meta: {
     name: "claim",
-    description: "Claim an action so other chats see you're working on it. Required before update/complete/discard. Example: baker actions claim <action-id>"
+    description: "Claim an action so other chats see you're working on it. Required before `complete` (update and discard don't need a claim). Example: baker actions claim <action-id>"
   },
   args: {
     id: { type: "positional", description: "Action ID", required: false },
@@ -1023,6 +1023,30 @@ var advertiserWinnersResponseSchema = z2.object({
   advertiser_id: z2.string(),
   winners: z2.array(winningAdSchema)
 });
+var feedRequestSchema = z2.object({
+  // Optional subset of your followed advertiser ids to narrow to ("trim down
+  // per advertiser"). Ids you don't follow are ignored and echoed back in
+  // `unknown_requested`. Omit to browse winners across every brand you follow.
+  advertiser_ids: z2.array(z2.string()).optional(),
+  platform: adLibraryPlatformSchema.optional(),
+  winner_category: z2.array(z2.string()).optional(),
+  format: z2.array(z2.string()).optional(),
+  // Winners kept per advertiser so no single brand floods the feed. `0` = no
+  // cap. Default applied by the route.
+  per_advertiser: z2.number().int().min(0).max(50).optional(),
+  // Total winners returned across all followed advertisers.
+  limit: z2.number().int().min(1).max(200).optional()
+});
+var feedResponseSchema = z2.object({
+  winners: z2.array(winningAdSchema),
+  // How many brands the company follows (regardless of the trim).
+  following_count: z2.number(),
+  // The advertiser ids actually queried (follows ∩ requested subset).
+  advertiser_ids: z2.array(z2.string()),
+  // Requested ids that aren't followed — a hint the caller mistyped or hasn't
+  // 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.
@@ -2728,16 +2752,16 @@ var createCommand = defineCommand3({
 import { defineCommand as defineCommand4 } from "citty";
 registerSchema({
   command: "actions.discard",
-  description: "Stage discard of a claimed action. Applies on chat publish.",
+  description: "Stage discard of an action \u2014 no claim needed; retire any action you're not working on. Applies on chat publish. Blocked only if another chat currently has it claimed.",
   args: {
-    id: { type: "string", description: "Action ID (must be claimed by current chat)", required: true },
+    id: { type: "string", description: "Action ID", required: true },
     reason: { type: "string", description: "Optional reason", required: false }
   }
 });
 var discardCommand = defineCommand4({
   meta: {
     name: "discard",
-    description: 'Stage discard of a claimed action. Example: baker actions discard <id> --reason "obsolete"'
+    description: 'Stage discard of an action (no claim needed). Example: baker actions discard <id> --reason "obsolete"'
   },
   args: {
     id: { type: "positional", description: "Action ID", required: false },
@@ -3316,9 +3340,9 @@ var unlinkCommand = defineCommand16({
 import { defineCommand as defineCommand17 } from "citty";
 registerSchema({
   command: "actions.update",
-  description: "Stage an update on a claimed action (name, description, tags, and/or priority). Applies on publish. --tags REPLACES the tag set; pass --tags '' to clear. --priority accepts urgent|high|medium|low or 'none' to clear back to unset (== normal).",
+  description: "Stage an update on an action (name, description, tags, and/or priority) \u2014 no claim needed; edit any action you're not working on. Applies on publish. Blocked only if another chat currently has it claimed. --tags REPLACES the tag set; pass --tags '' to clear. --priority accepts urgent|high|medium|low or 'none' to clear back to unset (== normal).",
   args: {
-    id: { type: "string", description: "Action ID (must be claimed by current chat)", required: true },
+    id: { type: "string", description: "Action ID", required: true },
     name: { type: "string", description: "New name", required: false },
     description: { type: "string", description: "New description", required: false },
     tags: {
@@ -3336,7 +3360,7 @@ registerSchema({
 var updateCommand = defineCommand17({
   meta: {
     name: "update",
-    description: 'Stage an update on a claimed action. Example: baker actions update <id> --name "New name"'
+    description: 'Stage an update on an action (no claim needed). Example: baker actions update <id> --name "New name"'
   },
   args: {
     id: { type: "positional", description: "Action ID", required: false },
@@ -27258,7 +27282,7 @@ Examples:
 });
 
 // src/commands/winning-ads/index.ts
-import { defineCommand as defineCommand170 } from "citty";
+import { defineCommand as defineCommand171 } from "citty";
 
 // src/commands/winning-ads/advertisers.ts
 import { defineCommand as defineCommand161 } from "citty";
@@ -27453,8 +27477,145 @@ var briefCommand = defineCommand162({
   }
 });
 
-// src/commands/winning-ads/follow.ts
+// src/commands/winning-ads/feed.ts
 import { defineCommand as defineCommand163 } from "citty";
+function buildFeedParams(input) {
+  const params = {};
+  const advertiser = splitList(input.advertiser);
+  if (advertiser.length > 0) {
+    params.advertiser = advertiser.join(",");
+  }
+  if (input.platform) {
+    params.platform = input.platform;
+  }
+  if (input.perAdvertiser !== void 0 && input.perAdvertiser !== "") {
+    params.per_advertiser = input.perAdvertiser;
+  }
+  if (input.limit !== void 0 && input.limit !== "") {
+    params.limit = input.limit;
+  }
+  const winnerCategory = splitList(input.winnerCategory);
+  if (winnerCategory.length > 0) {
+    params.winner_category = winnerCategory.join(",");
+  }
+  const format = splitList(input.format);
+  if (format.length > 0) {
+    params.format = format.join(",");
+  }
+  return params;
+}
+registerSchema({
+  command: "winning-ads.feed",
+  description: "Winners across EVERY brand you follow, in one library. Start here to review your followed advertisers, then trim to specific ones with --advertiser. Capped per advertiser so no single brand floods the feed. Lean winner cards; add --full for DNA + longevity.",
+  args: {
+    advertiser: {
+      type: "string",
+      description: "Comma-separated followed advertiser ids to narrow to (from `following`). Omit for all follows.",
+      required: false
+    },
+    platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false },
+    "per-advertiser": {
+      type: "number",
+      description: "Max winners kept per advertiser 0-50 (0 = no cap, default 5)",
+      required: false,
+      default: 5
+    },
+    limit: {
+      type: "number",
+      description: "Total winners across all follows 1-200 (default 40)",
+      required: false,
+      default: 40
+    },
+    "winner-category": { type: "string", description: "Comma-separated winner categories to include", required: false },
+    format: { type: "string", description: "Comma-separated formats to include (e.g. static,video)", required: false }
+  }
+});
+var feedCommand = defineCommand163({
+  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"
+  },
+  args: {
+    advertiser: {
+      type: "string",
+      description: "Comma-separated followed advertiser ids to narrow to",
+      required: false
+    },
+    platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false },
+    "per-advertiser": {
+      type: "string",
+      description: "Max winners per advertiser 0-50 (0 = no cap, default 5)",
+      required: false
+    },
+    limit: { type: "string", description: "Total winners 1-200 (default 40)", required: false },
+    "winner-category": { type: "string", description: "Comma-separated winner categories", required: false },
+    format: { type: "string", description: "Comma-separated formats", 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 DNA detail (angle, persona, hook) + longevity",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = buildFeedParams({
+        advertiser: args.advertiser,
+        platform: args.platform,
+        perAdvertiser: args["per-advertiser"],
+        limit: args.limit,
+        winnerCategory: args["winner-category"],
+        format: args.format
+      });
+      const data = await apiGet("/api/ad-library/feed", params);
+      const output = args.output || "json";
+      const full = args.full;
+      const rawWinners = Array.isArray(data?.winners) ? data.winners : [];
+      const hints = [];
+      if ((data?.following_count ?? 0) === 0) {
+        hints.push(
+          'You don\'t follow any brands yet. Run `baker winning-ads follow "<domain>" --platform meta` first.'
+        );
+      }
+      if (Array.isArray(data?.unknown_requested) && data.unknown_requested.length > 0) {
+        hints.push(
+          `Not in your follows (skipped): ${data.unknown_requested.join(", ")}. Check ids with \`baker winning-ads following\`.`
+        );
+      }
+      if (output === "json") {
+        const winners = rawWinners.map((w) => winningAdNormalizer(w, full));
+        writeJson({
+          ok: true,
+          data: {
+            winners,
+            following_count: data?.following_count ?? 0,
+            advertiser_ids: Array.isArray(data?.advertiser_ids) ? data.advertiser_ids : [],
+            ...hints.length > 0 ? { hints } : {}
+          }
+        });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: rawWinners },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        winningAdNormalizer
+      );
+      for (const hint of hints) {
+        process.stderr.write(`${hint}
+`);
+      }
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+
+// src/commands/winning-ads/follow.ts
+import { defineCommand as defineCommand164 } from "citty";
 var PLATFORMS = ["meta", "linkedin"];
 registerSchema({
   command: "winning-ads.follow",
@@ -27469,7 +27630,7 @@ registerSchema({
     label: { type: "string", description: "Optional display label (defaults to the resolved name)", required: false }
   }
 });
-var followCommand = defineCommand163({
+var followCommand = defineCommand164({
   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'
@@ -27516,7 +27677,7 @@ var followCommand = defineCommand163({
 });
 
 // src/commands/winning-ads/following.ts
-import { defineCommand as defineCommand164 } from "citty";
+import { defineCommand as defineCommand165 } 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.",
@@ -27549,7 +27710,7 @@ function followingNormalizer(record, full) {
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };
 }
-var followingCommand = defineCommand164({
+var followingCommand = defineCommand165({
   meta: {
     name: "following",
     description: "List brands you follow, with status (ready / adding\u2026) and cached counts. Example: baker winning-ads following --output md"
@@ -27584,7 +27745,7 @@ var followingCommand = defineCommand164({
 });
 
 // src/commands/winning-ads/patterns.ts
-import { defineCommand as defineCommand165 } from "citty";
+import { defineCommand as defineCommand166 } 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.",
@@ -27623,7 +27784,7 @@ function discriminatorRow(record) {
     top_values_duds: Array.isArray(record.top_values_b) ? record.top_values_b.join(", ") : ""
   };
 }
-var patternsCommand = defineCommand165({
+var patternsCommand = defineCommand166({
   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"
@@ -27679,7 +27840,7 @@ var patternsCommand = defineCommand165({
 });
 
 // src/commands/winning-ads/search.ts
-import { defineCommand as defineCommand166 } from "citty";
+import { defineCommand as defineCommand167 } 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.",
@@ -27787,7 +27948,7 @@ function buildSearchBody(args) {
   }
   return body;
 }
-var searchCommand4 = defineCommand166({
+var searchCommand4 = defineCommand167({
   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"
@@ -27902,7 +28063,7 @@ var searchCommand4 = defineCommand166({
 });
 
 // src/commands/winning-ads/seeds.ts
-import { defineCommand as defineCommand167 } from "citty";
+import { defineCommand as defineCommand168 } from "citty";
 function leanRow(r) {
   return {
     key: r.key,
@@ -27930,7 +28091,7 @@ function makeSeedCommand(opts) {
       limit: { type: "number", description: "Max keys 1-100 (default 20)", required: false, default: 20 }
     }
   });
-  return defineCommand167({
+  return defineCommand168({
     meta: { name: opts.name, description: opts.description },
     args: {
       platform: { type: "string", description: "Single platform to segment on", required: false },
@@ -27979,7 +28140,7 @@ var formatsCommand = makeSeedCommand({
 });
 
 // src/commands/winning-ads/unfollow.ts
-import { defineCommand as defineCommand168 } from "citty";
+import { defineCommand as defineCommand169 } from "citty";
 registerSchema({
   command: "winning-ads.unfollow",
   description: "Stop following a brand \u2014 removes it from your ad-dna library by advertiser id.",
@@ -27987,7 +28148,7 @@ registerSchema({
     advertiser: { type: "string", description: "Advertiser id to unfollow", required: true }
   }
 });
-var unfollowCommand = defineCommand168({
+var unfollowCommand = defineCommand169({
   meta: {
     name: "unfollow",
     description: "Stop following a brand by advertiser id. Example: baker winning-ads unfollow adv_123"
@@ -28008,7 +28169,7 @@ var unfollowCommand = defineCommand168({
 });
 
 // src/commands/winning-ads/winners.ts
-import { defineCommand as defineCommand169 } from "citty";
+import { defineCommand as defineCommand170 } 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.",
@@ -28018,7 +28179,7 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false }
   }
 });
-var winnersCommand = defineCommand169({
+var winnersCommand = defineCommand170({
   meta: {
     name: "winners",
     description: "Top winning ads for a specific advertiser id. Example: baker winning-ads winners adv_123 --top 15 --output md"
@@ -28068,7 +28229,7 @@ var winnersCommand = defineCommand169({
 });
 
 // src/commands/winning-ads/index.ts
-var winningAdsCommand = defineCommand170({
+var winningAdsCommand = defineCommand171({
   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.
@@ -28080,6 +28241,7 @@ Subcommands:
   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   \u2014 add a brand's ads to your library
   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 unfollow <advertiser>     \u2014 stop following a brand
   baker winning-ads brief                     \u2014 creative brief grounded in similar winners
@@ -28092,6 +28254,8 @@ Examples:
   baker winning-ads search "B2B SaaS before/after AI automation" --platform meta --format static --output md
   baker winning-ads advertisers "Acme" --output md
   baker winning-ads follow "deel.com" --platform meta
+  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 hooks --platform meta --awareness problem_aware --industry saas --output md
   baker winning-ads search "fintech onboarding" --hook-archetype callout --winner-category winner --output md
@@ -28102,6 +28266,7 @@ Examples:
     advertisers: advertisersCommand2,
     follow: followCommand,
     following: followingCommand,
+    feed: feedCommand,
     winners: winnersCommand,
     unfollow: unfollowCommand,
     brief: briefCommand,
@@ -28129,7 +28294,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand171({
+var main = defineCommand172({
   meta: {
     name: "baker",
     version: getCliVersion(),