@koda-sl/baker-cli 0.193.0 → 0.194.0

package/README.md

@@ -777,6 +777,12 @@ baker ads meta ads --account-id act_123 --all-statuses               # widen to
 baker ads meta creatives --creative-id 9988
 baker ads meta preview --creative-id 9988 --ad-format MOBILE_FEED_STANDARD --out-file /tmp/p.html
 
+# "Why does it show as a still image in one placement?"
+baker ads meta insights --object 9988 --level ad --intent video \
+  --breakdowns publisher_platform,platform_position --date-preset last_30d   # one ad only: hints flag placements playing far below the ad's own rate
+baker ads meta preview --creative-id 9988 --placement facebook_reels_overlay --platform facebook
+baker ads meta preview --list-formats                                        # ad_format values + placement mappings
+
 # "What audience is this targeting?"
 baker ads meta audiences --account-id act_123
 
@@ -847,10 +853,15 @@ creatives           # list per account, or fetch single via --creative-id
 audiences           # custom audiences (incl. lookalikes)
 pixels              # list, or --stats for one --pixel-id (see "Restricted pixel fields")
 activities          # account audit log, ~90d retention
-insights            # see "Smart defaults" above
-preview             # iframe HTML for a creative or ad in a given ad_format
+insights            # see "Smart defaults" above; a single-ad placement breakdown returns hints
+                    # naming placements playing far below that ad's own play rate — or saying
+                    # none is, which it never leaves unsaid
+preview             # iframe HTML for a creative or ad in a given ad_format, or in the
+                    # placement an insights breakdown reported (--placement, --list-formats)
 ```
 
+Placement diagnostics deliberately stop at evidence. `insights` names a suspect placement with its share of delivery, `preview` shows what Meta renders there, and neither asserts *why* — Meta documents an eligibility error for a video creative in a video-incompatible placement, not a silent fallback to the cover frame. Ad-set writes that pin placements warn about the learning-phase reset, and a placement set missing the `feed` Meta requires alongside `marketplace`/`search`/`profile_feed`/`notification` is rejected at stage time.
+
 The HTTP backend exposes more endpoints (catalogs, ad-studies, ad-images, labels, high-demand-periods, raw currency lookup). They're intentionally not surfaced as CLI commands because AI agents rarely need them. Hit them via curl against `/api/ads/meta/*` if needed.
 
 #### Auth + caching