remix-graphic-ad-from-reference

# remix-graphic-ad-from-reference

## Purpose

Given **one reference ad image** + a **target product** + **new copy**, produce a finished static ad
that keeps the reference's *layout and composition* but swaps the product and words for the new brand.
This powers the app's "pick a Pinterest ad you like → get the same ad for your product" flow.

It does **not** invent layouts and it does **not** regenerate the whole scene from scratch. It reads
the reference, then recreates it with GPT Image 2:

- **GPT Image 2 (edit the reference) — ALWAYS use this as the generator.** Run it in **image-edit
 mode on the reference itself** to preserve the layout/composition and swap in the new product +
 copy. This is the engine for EVERY remix (premium look). FAL slug `fal-ai/gpt-image-1/edit-image`.
- **HTML overlay (goose-graphics) — NOT a generation engine.** It is only an optional FINISHING
 step: if GPT bakes garbled/misspelled copy, overlay crisp text on top of the GPT output. Never use
 it as the primary generator — a remix must always be generated by GPT Image 2.


## Inputs

| Input | Required | Notes |
|---|---|---|
| `reference_image` | yes | The ad to recreate (local path or URL). One image. |
| `product` | yes | Target product: a clean product render/photo (PNG/webp). Pull the **real** brand asset; grounding/swapping on it is what keeps the label correct. **If the brand asset is a multi-product lineup, crop to the ONE relevant product first** — the remix grounds on a single clean product per `product_slot` (use `product_images_needed` from the slot map for how many distinct products the layout needs). |
| `copy_changes` | optional | If omitted, **the agent auto-writes it** from the brand pack mapped to the template's `slot_map` (see Phase 0.5). New headline, benefit callouts, social-proof line, discount/badge text. Keep the reference's *structure* (same zones), swap the words. |
| `brand` | recommended | Palette (hex), font, logo/wordmark, voice — from `get_brand_kit` / a `brand-research` pack. |
| `style_source` | optional | **`template` (DEFAULT)** keeps the reference ad's palette/theme; **`brand`** recolours to the brand kit's documented palette. See "Brand grounding" below. The caller sets it (e.g. the user asks to "match my brand colours" → `brand`); absent → `template`. |
| `route_hint` | optional | Engine override. Default is **always `gpt_image_2`**; `html` is only a text-overlay finishing step, never the generator. |
| `aspect` | optional | Inherit from the reference; map to the renderer canvas. Default 4:5 / 1080×1350. |
| `remix_spec` | optional | The precomputed spec from the template library (`slot_map` + `gen_prompt` + `remix_engine`). **If present, SKIP Phase 0 re-analysis** — the slots and prompt are already authored. This is the normal path when remixing a library template. |
| `remix_mode` | from template | `product` (swap a physical product) or `ui` (SaaS/app ad — swap the app screenshot/UI, NEVER insert a product). Tagged on the template. |
| `app_screenshot` | for `ui` mode | The brand's app/UI screenshot to drop into the device frame (used instead of `product` when `remix_mode:ui`). |

## Brand grounding — read the kit, never improvise (do this before generating)

The brand context comes from `get_brand_kit` (structured): `colors` (palette hex), `typography`,
`products[]` (with `imageUrls` + `name`/`description`), `screenshotUrls`, and `referenceImages[]`
(each tagged with `productName` + `kind: "product" | "website_screenshot"`). **Read the full kit, not
a preview.**

### Palette — by `style_source` (default `template`)
**Default to `template`. Use `brand` ONLY when the user explicitly asks** (e.g. "use/match my brand
colours", "make it on-brand"). Do NOT switch to `brand` on your own judgment — keeping the reference's
look is the expected default.
- **`template` (default):** keep the **reference ad's** colours/theme; the brand contributes only its
  product image, logo, and copy/voice — NOT its colours.
- **`brand` (only on explicit user request):** recolour the layout to the brand kit's `colors`
  (primary/accent/bg/text).
- **NEVER invent a colour.** Every colour in the output must come from EITHER the reference
  (`template`) OR the kit's documented `colors` (`brand`). Do **not** pull an accent off the logo, a
  mascot, a product, or "what looks nice." If `style_source: brand` but the kit has no palette, fall
  back to `template` (don't guess). This is the #1 off-brand failure.

### Which image to feature — select from the kit, send ONLY the relevant one(s)
- **Physical-product brand:** the hero is the brand's product. Pick from `referenceImages` where
  `productName` matches the slot's product and `kind` is `"product"` (hero = that product's
  `imageUrls[0]`). Send only that product's image(s) for the slot — **not** all reference images.
- **SaaS / software / app brand** (`brandType` ∈ saas/software/service/app/platform, or
  `remix_mode: ui`): the hero is the brand's **app UI** — use `referenceImages` with
  `kind: "website_screenshot"` (i.e. `screenshotUrls`). **NEVER insert a physical product or a
  mascot** for a SaaS ad. If there is no screenshot, rebrand the existing UI (recolor/logo/copy).
- Don't substitute a mascot/logo for the product unless the brand genuinely has no product/app image
  and the layout's product slot can't be filled — and if so, say so to the user, don't silently swap.

## Composed Atoms

- `goose-graphics` (`skills/design/composites/goose-graphics`) — renders the HTML-overlay path to PNG via the goose-graphics Playwright pipeline.
- `create-image-gpt-image-fal` (`skills/ads/capabilities/create-image-gpt-image-fal`) — GPT Image 2, run in **edit mode on the reference** for the photographic path.
- `create-product-images-higgsfield-product-photoshoot` — OPTIONAL: only when no clean product render exists and one must be generated first. Not bundled in goose-skills yet; if absent, require the caller to supply a clean product image.

## Workf