@koda-sl/baker-cli 0.114.0-dev.249eaa8ed → 0.115.0-dev.3bcc79f9c

package/README.md

@@ -681,6 +681,12 @@ baker ads google keyword-lists add --customer-id 1234567890 --list-ref <list-id>
 baker ads google ads create --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> \
   --headlines "Fast Widgets,Buy Online,Free Shipping" --descriptions "Best widgets around.,Ships tomorrow." \
   --final-url https://example.com
+# Responsive display ad — images are fields on the ad; register each image as an asset first (returns a g_temp_* ref)
+baker ads google assets create --customer-id 1234567890 --file '{"type":"image","imageId":"<baker_image_id>","name":"Hero"}'
+baker ads google ads create --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> --format responsiveDisplay \
+  --headlines "Come back and save" --long-headline "Finish signing up and get 20% off" \
+  --descriptions "Fast setup, no card required" --business-name "Acme" --final-url https://example.com \
+  --marketing-images g_temp_<img_landscape> --square-marketing-images g_temp_<img_square> --logo-images g_temp_<img_logo>
 
 # Review / undo staged changes
 baker ads google draft list                  # readable campaign ▸ ad group ▸ ad tree + completeness advisories
@@ -2574,12 +2580,36 @@ Auth: same `BAKER_API_KEY` + `BAKER_API_URL` as the rest of the CLI.
 ```bash
 # 1. Validate (free, never calls the API)
 baker canvas validate my-canvas.json
+#    Blocking issues exit non-zero. Advisory `warnings[]` (exit 0) flag likely-wrong-but-
+#    legal config to review before billing — a frame that describes a recurring element
+#    (a pet/product) but doesn't wire its reference (VIDEO_REFERENCE_MISSING), or a scene
+#    span that exceeds the assigned model's max clip duration (VIDEO_SPAN_EXCEEDS_MODEL).
 
 # 2. Run (executes nodes, writes files to ./canvas/<run_id>/)
 baker canvas run my-canvas.json
 #    Only nodes reachable from the declared output execute (orphaned nodes are skipped,
 #    not billed). Add --keep-runs N to prune old r_* run dirs, keeping the N newest.
 
+# 2b. Independent nodes ALREADY fan out in parallel — every node in the same
+#     topological layer (e.g. all the per-clip video_generate nodes) runs concurrently
+#     up to a bound. Raise it with --parallel N (alias: --concurrency N; default 5;
+#     env BAKER_CANVAS_CONCURRENCY). A single clip failing NO LONGER strands its
+#     siblings: the whole layer settles, cached siblings survive, and a re-run resumes
+#     from cache. There is no need to render clips one at a time or pin `output` to a
+#     single node — that old serial workaround is obsolete.
+baker canvas run my-canvas.json --parallel 8
+
+# 2c. Runs persist across sandboxes/sessions by default: node results sync to a
+#     company-scoped remote cache (small JSON pointers; bytes stay in R2), so a FRESH
+#     sandbox re-runs an already-computed canvas at zero credits — assets rehydrate
+#     from R2, sha-verified. Every run also posts a durable history record (per-node
+#     outputs, credits, cached/fresh) that powers the dashboard's Creatives
+#     generations timeline. Opt out with --remote-cache off (env
+#     BAKER_CANVAS_REMOTE_CACHE=off) and --no-record. With --remote-cache off,
+#     assets are not uploaded, so a recorded run keeps its stats but has no
+#     browsable outputs — pass --no-record too if you want nothing persisted.
+baker canvas run my-canvas.json --remote-cache off --no-record
+
 # 3. Inspect a finished run (per-node timing, file list, optional video thumbs)
 baker canvas inspect <run_id>
 
@@ -3323,6 +3353,15 @@ Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`, `image/gif` (via OpenR
               "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9", "enhance_prompt": true } }
 ```
 
+> **Switching a clip's model has cross-node constraints** — validate after every model edit. `validate` gates all of these before any billed run:
+> - **One aspect_ratio for the whole canvas.** Every `video_generate` node must agree (`VIDEO_ASPECT_MISMATCH`), or the composite silently crops/letterboxes. Switching one clip to Veo (which only offers `16:9`/`9:16`) forces every other clip to a shared ratio too.
+> - **`duration` is a per-model hard enum.** Seedance `4,5,6,8,10,12,15`; Veo `4,6,8` only. A value outside the model's set is rejected; a scene whose natural span exceeds the model's max is flagged (`VIDEO_SPAN_EXCEEDS_MODEL`, advisory) — a 9.2s scene can't fit Veo's 8s cap and would truncate; split the scene or keep it on a longer-max model.
+> - **`person_generation` differs.** Veo accepts only `allow_all`.
+>
+> A scaffolded canvas carries this table inline at `metadata.todo.model_constraints`.
+
+> **Content-policy blocks are deterministic, not flaky.** fal.ai/Seedance rejects any first/last frame that reads as a real-person likeness (even an AI-generated face) — surfaced as `content_policy_blocked` (HTTP 422, **non-retryable**), even when fal's proxy chain masks it as a 5xx. Retrying **never** succeeds and wastes credits. Fix the cause: switch the clip to the other curated model (Veo routes around fal's filter), or make the source frame less photorealistic.
+
 ---
 
 ##### `tts`
@@ -3874,6 +3913,7 @@ baker canvas run ./reference-ad.video.canvas.json
 | Flag | Default | Effect |
 |---|---|---|
 | `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. |
 | `--frames <mode>` | `generate` | `generate` emits ONE recast keyframe per scene (the original frame is dropped so the dropped `el_*` assets drive identity); `reuse` wires the real extracted first+last frames straight into the clips (faithful, cheaper, no recast). |
 | `--ambient` | off | Give silent **b-roll** scenes native diegetic ambient (Seedance `generate_audio`), mixed deep under the music bed. Talking scenes already carry voice; check levels don't muddy the mix before keeping it. |
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
@@ -3915,6 +3955,7 @@ baker canvas run ./static-ad.canvas.json
 |---|---|---|
 | `--context <text>` | — | Known provenance (advertiser, category, market) to ground the describe. |
 | `--out <path>` | `<image-dir>/static-ad.canvas.json` (cwd when `<image>` is a URL) | Where to write the canvas (`prompt.json` is written alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. |
 | `--describe-model <id>` | registry default (`~google/gemini-pro-latest`) | Override the `image_describe` model. |
 | `--select-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the element-selection `text_generate` model. |
 | `--layout-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the global-layout `text_generate` model. |
@@ -4386,6 +4427,26 @@ import {
 } from "@koda-sl/baker-cli/engine";
 ```
 
+## Creatives
+
+Publish an approved canvas render as a first-class Baker creative. The image uploads to the Baker image library (tagged `creative`), a creative record is created/updated, and the command prints the creative reference JSON the dashboard renders in chat.
+
+```bash
+baker creatives publish ./canvas/<run_id>/<final>.png --title "Spring Offer 4x5" \
+  --slug spring-offer-4x5 --run-id r_01JXYZ... \
+  --source-reference-url "https://www.facebook.com/ads/library/?id=..."
+```
+
+| Flag | Effect |
+|---|---|
+| `--title <text>` | Required. Human title for the creative. |
+| `--slug <slug>` | Creative slug (`src/creatives/<slug>/`) — attaches the image to that creative's row, marks it `published`. |
+| `--run-id <r_…>` | Pins the approved generation from the creative's run history as the published one. |
+| `--source-reference-url <url>` | Original reference ad URL, recorded on the creative. |
+| `--context <text>` | Optional describe context for the uploaded image asset. |
+
+Without `--slug` the command behaves as before (one creative record per published image). With `--slug` it upserts the repo-convention row — the same one the dashboard's Creatives tab and the `src/creatives/{slug}/` folder describe — so publish, repo sync, and run history all land on a single record regardless of order.
+
 ## Help & Discovery
 
 Every command supports `--help` for usage info: