@koda-sl/baker-cli 0.198.0-dev.6d2f498f5 → 0.199.0

package/README.md

@@ -781,6 +781,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
 
@@ -851,10 +857,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
@@ -1827,6 +1838,8 @@ Each external source is its own subcommand. Pick the verb that matches the sourc
 | `baker images delete <id>` | Delete a record | n/a |
 | `baker images normalize <files>` | Local recolor + bg removal + trim + resize | n/a (operates on disk, no upload) |
 | `baker images upscale <imageId>` | Real-ESRGAN super-resolution via backend ($0.05/image, cost-tracked) | n/a (operates on library image) |
+| `baker images layerize <imageId>` | Split into editable layers — transparent cutouts per element plus baked-in copy recovered as editable text (costs credits) | n/a (operates on library image) |
+| `baker images layers <imageId>` | Read the layers of an already-split image (free) | n/a (operates on library image) |
 | `baker images crop <file>` | Coordinate-based rectangular extract — local file or URL | n/a |
 | `baker images dimensions <file\|url>` | Read width / height / aspect / format without decoding | n/a |
 | `baker images download <targets>` | Remote URLs and/or library ids → local files, so the local transforms can read them | n/a (writes to disk, no upload) |
@@ -2306,6 +2319,23 @@ Validation errors return `VALIDATION_ERROR`:
 - Malformed `--color` (must be `#RGB` or `#RRGGBB`)
 - Empty file pattern or no matches
 
+### `baker images layerize <imageId>`
+
+Splits a library image into editable layers and waits for completion (~90s). Returns a transparent PNG per element — each at a permanent URL usable as a canvas input — plus any headline that was drawn into the picture, recovered as real copy with its font, size, weight and colour.
+
+```bash
+baker images layerize j571abc123def
+baker images layerize j571abc123def --full                       # geometry + typography
+baker images layerize j571abc123def --instructions "keep the bottle and its shadow together"
+baker images layerize j571abc123def --max-wait 0                 # fire-and-forget
+```
+
+The model separates what was *visible* and does not repaint what sat behind a subject, so the flat picture is kept as an `Original image` layer underneath.
+
+### `baker images layers <imageId>`
+
+Reads back the layers of an image already split with `layerize`. Free — no provider call. `--full` includes geometry and typography.
+
 ### `baker images upscale <imageId>`
 
 Super-resolution via the Convex backend (Replicate, cost-tracked at $0.05/image). Operates on a library image by ID — upload the file first via `baker images upload`, then upscale.
@@ -2383,6 +2413,8 @@ baker images download https://…/hero.png --out ./hero.png
 
 Response lists what landed and what didn't — a partial failure is still `ok: true`, with the failures in `failed[]` and a hint saying so. Every target failing is `DOWNLOAD_FAILED`. Passing a path that is already on disk is a `VALIDATION_ERROR` whose `fix` points at using the local transforms directly.
 
+Only addresses on the public web are fetched. A URL pointing at loopback, a private range or a link-local address is declined before any request is made — it holds nothing this command could usefully download. The same rule covers the canvas scaffolders and the shared image reader.
+
 ```json
 {
   "ok": true,

package/dist/{chunk-ZBS53HJF.js → chunk-2R2DEPG7.js}

@@ -1,10 +1,10 @@
 import {
   debugLogHttp,
   readBodyForLog
-} from "./chunk-RN2XKQIJ.js";
+} from "./chunk-UZYVSPCA.js";
 import {
   getEnv
-} from "./chunk-MVCCSWDE.js";
+} from "./chunk-6NZG2TCM.js";
 
 // src/client.ts
 var MAX_RATE_LIMIT_RETRIES = 3;
@@ -198,4 +198,4 @@ export {
   apiGet,
   apiPost
 };
-//# sourceMappingURL=chunk-ZBS53HJF.js.map
+//# sourceMappingURL=chunk-2R2DEPG7.js.map