gooseworks 0.3.15 → 0.4.0

package/skills/goose-ads/SKILL.md

@@ -2,8 +2,8 @@
 name: goose-ads
 slug: goose-ads
 description: >
-  GooseWorks ads skill — create, edit, AND analyze ad creative. Remix a static (image) ad
-  template into a branded ad for the user's product, edit/re-roll an existing creative,
+  GooseWorks ads skill — create, edit, AND analyze ad creative. Turn an approved source ad
+  into a branded ad for the user's product, edit/re-roll an existing creative,
   research a brand for ads, OR analyze ad performance (Meta/Google campaign diagnostics,
   creative fatigue, CAC & lead quality, competitor ad intelligence, ad angles & hooks). Use
   when the user says "remix this ad", references a static ad template id/slug, asks to "make
@@ -12,7 +12,7 @@ description: >
   app uses) — credits are reserved and billed server-side. Analytics recipes are fetched from
   goose-skills on demand.
 category: ads
-version: 2.2.0
+version: 2.4.0
 author: GooseWorks
 tags: [gooseworks, ads, remix, static-ad, brand, creative, image, analytics, meta-ads, performance]
 ---
@@ -22,7 +22,7 @@ tags: [gooseworks, ads, remix, static-ad, brand, creative, image, analytics, met
 The GooseWorks ads skill. Two jobs:
 
 1. **Create / edit ad creative** — a **thin wrapper** over the backend's single generation
-   workflow. You pick the brand + template(s) and submit ONE batch; the **backend** runs the
+   workflow. You pick the brand + approved source ad(s) and submit ONE batch; the **backend** runs the
    whole pipeline (compose → generate → persist → judge), reserves and bills credits, and
    stores the renders. You do NOT generate images, call FAL, manage render rows, or upload
    files — those are gone. This is the exact same workflow the GooseWorks ads app uses, so the
@@ -36,6 +36,24 @@ Everything goes through the `mcp__gooseworks__*` tools. If they are not availabl
 tell the user to run `gooseworks install --claude --mcp`** (and restart Claude Code). There is
 no HTTP/file fallback — the REST ad endpoints are session-cookie-only and reject your token.
 
+## Start from the brand context — don't re-ask what it already answers
+
+If the `gooseworks` router handed you brand context, USE IT. If you were invoked directly, call
+`brand_get_context` first (falling back to `get_brand_kit` for the selected brand). It already
+answers most of what the flows below would otherwise ask the user:
+
+- **Which product to feature** → `products[]`. Offer the real catalog entries; never guess a
+  product name and never ask the user to list their products.
+- **The vibe / tone of the copy** → the brand's **voice**. Use it; don't ask "what tone?".
+- **Who the ad is for** → the brand's **audience**. Don't ask "who's the target?".
+- **The angle, offer framing, and what to claim** → **positioning**, value props, proof points.
+- **Logo, colors, fonts** → owned by the backend research pass. **Never re-derive them.**
+- **Whether the facts are trustworthy yet** → **research status**. If it isn't complete, say so in
+  one line and continue; the batch queues and runs when research finishes.
+
+Ask only for what the context genuinely doesn't answer: the specific campaign intent (season,
+promo, which of several angles), the source ad, and anything the user must consent to.
+
 ## Identity & credits
 
 - One agent-scoped token authenticates the `gooseworks` MCP tools. Never print it. The tools
@@ -46,74 +64,63 @@ no HTTP/file fallback — the REST ad endpoints are session-cookie-only and reje
   message and stop) and bills only the images that actually complete. Call
   `estimate_remix_batch` first to tell the user the cost; `gooseworks credits` shows balance.
 
-## Defaults — match the app (priority: frontend, then backend)
+## Live MCP contract — inspect it before asking
 
-When the user doesn't specify, submit with the **ads app's** defaults so skill output matches
-what they'd get in the UI. **Pass these explicitly:**
+The currently registered MCP tool schemas are the source of truth for inputs, supported choices,
+and defaults. Do not copy an exhaustive input list from this skill or rely on remembered fields.
 
-- `variants`: **1** per template
-- `ratios`: **["4:5"]** (Meta feed vertical)
-- `engine`: **"gpt_image_2"**
-- `quality`: **"medium"**
-- `preserve_source_styling`: **ASK the user** — "Keep original" (the template's own
-  colours/fonts → `preserve_source_styling: true`) vs "Match brand" (restyle to the brand
-  palette/fonts → `preserve_source_styling: false`). This mirrors the app's Styling control.
-  **The default is "Keep original"** — if the user doesn't answer or doesn't care, send `true`.
+Before each tool call:
 
-If the user asks for something the app exposes (more variants, a different ratio like 1:1 or
-9:16, a faster engine, higher quality), pass that instead. Omitting a field lets backend policy
-decide — fine, but prefer sending the app defaults for predictable parity.
+1. Inspect the live schema for the tool you are about to use.
+2. Fill required inputs already known from the Brand Kit, selected source, or conversation.
+3. Ask the user only for required inputs that cannot be inferred and for choices that materially
+   change the result. Do not turn every optional field into a questionnaire.
+4. Omit unspecified optional settings so the backend applies its current app defaults.
+5. If the live schema conflicts with this workflow, follow the live schema and report the drift
+   with `log_cli_event`.
 
 ## The generation tools (the new, single-workflow surface)
 
-- `submit_remix_batch { brand_id, items, prompt?, product_name?, preserve_source_styling?,
-  reference_image_urls?, allow_without_product_image?, engine?, quality? }` — **the one call
-  that makes ads.** `items` is `[{ template_id, variants?, ratios? }]` (≤20 templates).
+- `submit_remix_batch` — **the one call that makes ads.** Inspect its live schema and supply
+  the required brand/source inputs plus any choices the user explicitly made.
   Returns the batch with a `links` block (`brand_url` + per-creative `app_url`). If the brand's
   research isn't finished yet the batch comes back `status: "queued"` — it auto-runs the moment
   research completes; tell the user it'll appear shortly, don't error.
-- `estimate_remix_batch { items, engine?, quality? }` — cost preview (images, credits_per_image,
-  total_credits, available_credits). `template_id` accepts a uuid OR a slug. Reserves nothing. Use
-  to quote the cost first. Check `unknown_template_ids` in the response — any token there didn't
-  resolve (submit would 404 on it); don't quote a cost that silently dropped a bad id.
-- `get_remix_batch { batch_id }` — poll status. Returns each creative with its renders and
+- `estimate_remix_batch` — cost preview. Reserves nothing. Use it to quote the cost first and
+  check whether every selected source resolved before submitting.
+- `get_remix_batch` — poll status. Returns each creative with its renders and
   `completed`/`failed`/`pending` counts, plus `links`. A creative is done when its `pending` is 0
   — NOT when `current_render_url` is set (during a regenerate that field still points at the prior
   image). Each render carries `age_seconds` (since queued) and `elapsed_seconds` (time generating):
   use them to tell a slow-but-healthy render from a stuck one. A render only failed when its
   `status` is `"failed"` — never assume a stall and re-submit, that double-bills.
-- `list_brand_creatives { brand_id, limit?, offset? }` — the brand's gallery feed (newest
+- `list_brand_creatives` — the brand's gallery feed (newest
   first) + `brand_url`. Alternative poll target; also use to show everything made for a brand.
-- `surprise_me_templates { brand_id, count? }` — the **"Surprise me" recommender**. Picks
-  brand-relevant templates (SAME logic as the web /create "Surprise me" button — templates
-  whose category overlaps the brand float to the top, bucketed + shuffled so picks stay fresh).
+- `surprise_me_templates` — the **"Surprise me" recommender**. Picks
+  remixable Community creations (SAME logic as the web /create "Surprise me" button), shuffled
+  so picks stay fresh. It does not use the retired curated third-party catalog.
   Returns the picked templates (id, slug, title, image, ratio) AND a ready-to-open `create_url`
   (the /create page with `cli=true` and the picks pre-selected). This is how you recommend
   templates — do NOT hand-pick from the raw catalog yourself (see "Picking templates" below).
-- `regenerate_creative { project_id, mode?, prompt?, source_render_id?, ... }` — **edit / re-roll
-  one existing creative** through the same pipeline. `mode: "variation"` (default) re-rolls from
-  the template; `"edit"` makes a targeted change to a specific render (`prompt` + `source_render_id`
-  required); `"exact"` runs `prompt` verbatim against that render's references. Returns a
-  single-item batch — poll it with `get_remix_batch`.
-- `set_creative_feedback { render_id, rating?, comment?, reasons? }` — record the user's reaction
-  to a generated image (the SAME happy/neutral/sad + comment + reason chips the app captures). Use
-  it whenever the user reacts ("love this one" / "the logo is wrong"). `render_id` is a RENDER id
-  from `get_remix_batch` / `list_brand_creatives`, not a project/batch id. `reasons` are quick
-  chips (wrong_product, brand_or_logo_wrong, off_brand, text_garbled, weak_copy, ai_or_distorted).
+- `regenerate_creative` — edit or re-roll one existing creative through the same pipeline.
+  Inspect the live schema to select the supported mode and required source inputs. Returns a
+  single-item batch; poll it with `get_remix_batch`.
+- `set_creative_feedback` — record the user's reaction to a generated image. Use it whenever
+  the user reacts; inspect the schema for the current rating and reason choices.
 
 ### Plan mode — review the plan BEFORE generating (optional)
 
 For users who want to approve each ad's plan before spending credits (the app's "Plan it" flow):
 
-- `submit_remix_batch { ..., requires_approval: true }` — composes each creative's plan and PAUSES.
+- Use the approval option exposed by `submit_remix_batch` — it composes each creative's plan and PAUSES.
   **No credits are reserved and no image renders** until you approve.
-- `list_ad_approvals { brand_id? }` — poll this; returns `{ items, counts }`. While a creative is
+- `list_ad_approvals` — poll this. While a creative is
   `composing`, wait; once `awaiting_approval`, show its `plan` (composed prompt + refs + quality)
   to the user.
-- `revise_ad_plan { project_id, message?, variant_label? }` — recompose from a chat steer, still
+- `revise_ad_plan` — recompose from a chat steer, still
   free. Poll `list_ad_approvals` until it's `awaiting_approval` again.
-- `approve_ad_plan { project_id | batch_id }` — approve ONE creative (`project_id`) or the whole
-  batch (`batch_id`). **This is the step that reserves credits and renders.** Then poll
+- `approve_ad_plan` — approve one creative or the whole batch using the live schema.
+  **This is the step that reserves credits and renders.** Then poll
   `get_remix_batch` and hand back links as usual.
 
 Only offer plan mode when the user asks to review/approve first — the default path generates
@@ -121,19 +128,23 @@ immediately.
 
 ## Reading the brand & picking inputs (still MCP, read-only)
 
-- `get_brand_kit { brand_id }` — the CANONICAL brand context (name, description, audience,
-  voice, brandType, valueProps, colors, typography, logoUrl, `products[]`, presigned
-  `referenceImages[]`). Read this to choose `product_name` and any `reference_image_urls`.
-- `list_ad_brands { query? }` / `get_ad_brand { brand_id }` — find/fetch a brand. Pass `query` to
-  filter by name (case-insensitive) instead of listing every brand; rows are lean (no `brand_kit` —
-  read `get_brand_kit` for the full kit).
-- `get_static_ad_template { template_id }` — resolve a template (slug OR uuid; public catalog
-  AND your org's private templates). Confirms it exists before you submit.
-- `remix_community_ad { community_id }` — a **Community** ad id is an `ad_project` id, not a
+- `get_brand_kit` — read the canonical brand context and available products/assets.
+- `list_ad_brands` / `get_ad_brand` — find and fetch the active brand.
+- `list_user_ad_templates` — list the org's own uploads and
+  imported ads. Prefer `relationship: "self"` when the user wants to reuse their own ads;
+  `relationship: "competitor"` is research/inspiration, never proof that the user owns the ad.
+- `search_ad_templates` — search remixable Community generations. The
+  retired curated third-party catalog is not returned.
+- `get_static_ad_template` — resolve a source already owned by
+  the org, including an own upload or a snapshotted Community creative. It does not resolve the
+  retired curated third-party catalog.
+- `remix_community_ad` — turn a selected Community creative into a private remix source before
+  submitting it. A Community ad id is an `ad_project` id, not a
   template id. Call this FIRST to snapshot it into a private template, then use the returned
   template `id` in `items`.
-- `create_user_ad_template { workspace_path }` — "bring your own ad": upload the user's own
-  image as a private template, then remix it like any other.
+- `create_user_ad_template` — upload a source image as a private template. Answer any
+  ownership/rights input only from the user's explicit confirmation. Never claim rights for a
+  competitor ad or an image found online.
 - `get_ad_project` / `append_project_message` — inspect a creative / leave a note on its thread.
 
 ## Keep the brand kit in sync — reconcile, then update (ASK first)
@@ -144,7 +155,7 @@ tagline, audience, voice, a product's name/price/description, "our logo is X", "
 anymore", a new product photo — treat it as a possible kit update, don't just use it for this one
 ad and forget it:
 
-1. **Check it against the kit.** `get_brand_kit { brand_id }` and see whether what the user said
+1. **Check it against the kit.** Call `get_brand_kit` for the active brand and see whether what the user said
    matches, is missing from, or contradicts the kit.
 2. **If it's already in the kit and matches** — nothing to do; proceed.
 3. **If it's new or different — ASK before writing.** Confirm in one line: *"Want me to update
@@ -152,65 +163,74 @@ ad and forget it:
    asked you to change the brand). Don't silently mutate the kit, and don't nag on trivia.
 4. **Persist with the write tools** (partial — only the fields you pass are touched; each edit is
    recorded as a user override that later re-research won't clobber):
-   - `update_brand_kit { brand_id, description?, audience?, voice?, instructions?, brand_type?,
-     value_props?, primary_color?, accent_color? }` — the structured kit fields.
-   - `upsert_brand_product { brand_id, ... }` / `delete_brand_product` — manage products.
-   - `add_brand_product_image { brand_id, ... }` / `remove_brand_reference_image` — product /
-     reference photos.
+   - `update_brand_kit` — structured brand fields.
+   - `upsert_brand_product` / `delete_brand_product` — products.
+   - `add_brand_product_image` / `remove_brand_reference_image` — product and reference photos.
+   Inspect each live schema and send only the fields needed for the confirmed change.
 5. **Confirm what changed** and continue the task. (Logo, colors, and fonts are owned by the
    backend research pass — prefer `update_ad_brand` / the research flow for those, not free text.)
 
 This is the parity gap the app closes in-product: a brand fact the user gives mid-task should be
 able to flow back into the kit — with their ok — instead of being lost.
 
-## Picking templates — ASK the user; don't freelance from the catalog
+## Picking source ads — use approved sources, not the retired catalog
 
 When the user wants to make ads but has NOT named a specific template (id/slug/Community
 ad/upload), do NOT silently browse the raw catalog and hand-pick for them. Instead run this
 short ask flow — it mirrors the web app and keeps the human in the loop:
 
-1. **Ask what kind of ads they want** — the angle/offer/theme/season, the vibe, and which
-   product from the brand kit to feature. This shapes both the template choice and your steering
-   `prompt`. Keep it to one or two quick questions.
-2. **Ask how to pick templates: "Choose explicitly" or "Surprise me".**
-   - **Surprise me** (they want you/the app to pick) → call
-     `surprise_me_templates { brand_id, count }` and hand the user the returned `create_url`.
+1. **Ask what kind of ads they want** — the angle/offer/theme/season. **The brand context already
+   gives you the vibe (voice), the audience, and the product catalog — do NOT ask for those.**
+   Offer the real `products[]` to pick from rather than asking "which product?", and derive the
+   tone from the brand's voice. This shapes both the source choice and your steering `prompt`.
+   Keep it to one quick question about campaign intent.
+2. **Ask how to pick a source: their own ads, Community, upload, or "Surprise me".**
+   - **Their own ads** → use `list_user_ad_templates` to load the active brand's own sources and
+     let them choose from the results.
+   - **Community** → `search_ad_templates`, let them choose, then call `remix_community_ad`
+     before submitting.
+   - **Upload** → upload through the workspace and call `create_user_ad_template`. If its live
+     schema requires an ownership or permission answer, only supply it after explicit confirmation.
+   - **Surprise me** (they want you/the app to pick) → call `surprise_me_templates` for the active
+     brand and hand the user the returned `create_url`.
      It opens /create in **CLI mode** with the picks pre-selected, a preview modal, and the
      **copyable remix prompt at the bottom** (in place of the Generate input). They can swap
      picks and copy that prompt. If they'd rather you "just make them" without reviewing in the
      app, you MAY submit the `surprise_me_templates` picks directly (skip to submit).
-   - **Choose explicitly** (they want to browse and select) → hand the user this URL, with the
+   - **Browse in the app** → hand the user this URL, with the
      active brand's slug filled in:
      `https://make.gooseworks.ai/create?brand=<brand-slug>&cli=true`
      In CLI mode the app shows the copyable remix prompt at the bottom (dismissable / switchable
-     back to the UI composer). They browse, select templates, and copy the prompt.
-3. **Ask the styling** — "Keep original" (default) vs "Match brand" — per the Defaults section.
-4. **Close the loop.** When the user **pastes back the copyable remix prompt** from the app
+     back to the UI composer). They browse the available own/Community sources and copy the prompt.
+3. **Close the loop.** When the user **pastes back the copyable remix prompt** from the app
    (it names the brand + the templates they chose), THAT is your cue to generate: resolve the
-   named template(s), then `submit_remix_batch` with the app defaults + the styling they chose.
+   named source(s), inspect `submit_remix_batch`, and collect only its unresolved required inputs.
 
-If the user already named a template (id/slug), a Community ad, or an upload, skip the ask flow
-for template choice — they've chosen — but still confirm the styling default and steer the prompt.
+If the user already named an owned source (id/slug), a Community ad, or an upload, skip the source
+choice. Competitor ads may inform the angle or structure, but describe them as inspiration, never
+claim ownership, and never attest rights for the user.
 
 ## Workflow — make ads from a template
 
-1. **Resolve the brand.** `list_ad_brands` by name/site → `get_brand_kit { brand_id }`. If the
+1. **Resolve the brand.** Use `list_ad_brands` by name/site, then call `get_brand_kit` for the
+   selected brand. If the
    kit's `researchStatus` isn't `complete`, you can still submit (the batch queues and runs when
    research finishes) — just tell the user. Use the kit to pick `product_name` (a real entry from
    `products[]`, not a guess) and, if the user supplied product photos, `reference_image_urls`.
-2. **Pick the template(s) via the ask flow above** (kind of ads → Choose explicitly vs Surprise
-   me → styling). Once you have concrete ids: `get_static_ad_template { template_id }` for each.
+2. **Pick the source ad(s) via the ask flow above.** Once you have concrete ids:
+   call `get_static_ad_template` for each.
    For a Community ad, `remix_community_ad` first; for an uploaded image, `create_user_ad_template`
    first.
 3. **(Optional) Craft the steering prompt.** The `prompt` is OPTIONAL — this is where the skill
    adds value: turn the user's intent (from step 1) into a concise steering note (e.g. tone,
    season, emphasis). Don't over-specify; the backend pipeline + brand kit handle palette, fonts,
    product swap.
-4. **(Optional) Quote the cost.** `estimate_remix_batch { items, engine, quality }` → tell the user.
-5. **Submit ONE batch.** `submit_remix_batch { brand_id, items, prompt?, product_name?, engine,
-   quality, preserve_source_styling }` using the app defaults above and the styling the user chose.
-   Keep the returned `batch_id` and `links`.
-6. **Poll until done.** `get_remix_batch { batch_id }` (or `list_brand_creatives`) every ~20-30s
+4. **Quote the cost.** Inspect and call `estimate_remix_batch`, then tell the user.
+5. **Submit ONE batch.** Inspect the current `submit_remix_batch` schema, fill known required
+   inputs, ask only for unresolved user decisions, and omit unspecified optional settings. Keep
+   the returned `batch_id` and `links`.
+6. **Poll until done.** Call `get_remix_batch` for the returned batch (or use
+   `list_brand_creatives`) every ~20-30s
    until every creative's `pending` is 0. Most images finish in a few minutes; text-heavy templates
    and `quality: high` take longer. Read each render's `elapsed_seconds` rather than guessing — a
    render that's still `running` is healthy; do NOT re-submit thinking it stalled (that double-bills).
@@ -219,17 +239,14 @@ for template choice — they've chosen — but still confirm the styling default
 
 ## Workflow — edit an existing ad
 
-User wants to tweak a creative they already made → `regenerate_creative`:
-- "make another version / different take" → `mode: "variation"` (optionally new `prompt`,
-  `product_name`, `ratios`).
-- "change X in this exact image" → `mode: "edit"`, `source_render_id` = the render to edit,
-  `prompt` = the change.
-- "run exactly this prompt on the product" → `mode: "exact"`, `source_render_id` + `prompt`.
-Then poll with `get_remix_batch` and hand back the links, same as above.
+User wants to tweak a creative they already made → use `regenerate_creative`. Infer whether they
+want another take, a targeted edit, or an exact instructed change from their request. Then inspect
+the live schema, ask only for any required source or instruction that is still missing, submit,
+poll with `get_remix_batch`, and hand back the links.
 
 ## Brand research
 
-Prefer the backend's result: `get_brand_kit { brand_id }`. If `researchStatus` is
+Prefer the backend's result: call `get_brand_kit` for the selected brand. If `researchStatus` is
 `complete`, REUSE it — never re-research.
 
 **The split — backend owns visuals, you own the qualitative depth:**
@@ -246,9 +263,10 @@ Prefer the backend's result: `get_brand_kit { brand_id }`. If `researchStatus` i
 
 **CLI brand-research flow:**
 
-1. `create_ad_brand { name, website_url }` → keep `brand_id` + `slug`. The brand comes back with
+1. Inspect and call `create_ad_brand` with the known brand identity and website, then keep its id
+   and slug. The brand comes back with
    `research_status: "pending"` (light pass in flight).
-2. **Wait for the backend light pass:** poll `get_brand_kit { brand_id }` until `researchStatus`
+2. **Wait for the backend light pass:** poll `get_brand_kit` for that brand until `researchStatus`
    is `complete` (usually <60s). Now the kit has authoritative logo/colors/fonts + a baseline.
    At this point generation is already unblocked — but do the deep pass to make it good.
 3. **Deep research locally:** `gooseworks fetch brand-research` and follow its phases. **Ground
@@ -262,10 +280,10 @@ Prefer the backend's result: `get_brand_kit { brand_id }`. If `researchStatus` i
      (`brandType` ∈ product | saas | service | agency | restaurant | fashion | beauty | fitness |
      finance | education | health). Only URLs already in our storage for product images.
    - **Do NOT set logo / colors / fonts here** — the backend light pass already owns those.
-5. **Persist it:** `finalize_brand_research { brand_id }` merges `kit-patch.json` into the kit
+5. **Persist it:** call `finalize_brand_research` for the brand. It merges `kit-patch.json` into the kit
    NON-CLOBBERINGLY (it will NOT overwrite the backend's visuals or any user edit), then re-confirms
    `research_status: complete`.
-6. **Verify:** `get_brand_kit { brand_id }` — confirm the qualitative fields you wrote are present
+6. **Verify:** call `get_brand_kit` again and confirm the qualitative fields you wrote are present
    before generating.
 
 **If the brand has NO website**, the backend light pass can't run (nothing to fetch) — do the whole
@@ -305,20 +323,22 @@ run through the `gooseworks` CLI (`gooseworks fetch` / `gooseworks call`), like
   each creative's `app_url`), copied verbatim. Never end on just "done" or a file path.
 - **Quote cost before generating** when it's non-trivial (use `estimate_remix_batch`), and
   relay `insufficient_credits` plainly if the submit is rejected — don't retry blindly.
-- **Don't hand-pick templates silently.** If the user didn't name a template, run the ask flow
-  (kind of ads → Choose explicitly vs Surprise me → styling). "Surprise me" goes through
-  `surprise_me_templates`; "Choose explicitly" sends them to `/create?brand=<slug>&cli=true`.
+- **Use approved source paths.** If the user didn't name a source, run the ask flow (own ads,
+  Community, upload, Surprise me, or browse in the app). "Surprise me" goes through
+  `surprise_me_templates`; browsing uses `/create?brand=<slug>&cli=true`. Never use the retired
+  curated third-party catalog.
   Generate when they paste the app's copyable remix prompt back (or submit the surprise picks
   directly if they'd rather not review).
-- **Ask the styling** — Keep original (default) vs Match brand — before you submit.
+- **Treat competitor ads as inspiration** — never attest rights, imply ownership, or promise to
+  copy a competitor's distinctive expression.
 - **Reconcile brand facts into the kit** — when the user states or changes something brand-level
   mid-task, check it against `get_brand_kit` and, with their ok, persist it via `update_brand_kit`
   / `upsert_brand_product` / `add_brand_product_image` so it sticks for future ads. Ask first;
   never silently mutate the kit.
-- **Record feedback** — when the user reacts to a generated image, capture it with
-  `set_creative_feedback { render_id, rating/comment/reasons }` so the quality loop learns.
-- **Plan mode is opt-in** — only compose-and-pause (`requires_approval: true` → `list_ad_approvals`
-  → `approve_ad_plan`) when the user wants to review before spending credits; otherwise generate
+- **Record feedback** — when the user reacts to a generated image, inspect and call
+  `set_creative_feedback` so the quality loop learns.
+- **Plan mode is opt-in** — only use the live approval option, then `list_ad_approvals` and
+  `approve_ad_plan`, when the user wants to review before spending credits; otherwise generate
   immediately.
 - **Don't busy-loop** — poll `get_remix_batch` on a sensible interval (~20-30s); a `queued`
   batch is waiting on research and will start on its own.

package/skills/goose-product-photos/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: goose-product-photos
+slug: goose-product-photos
+description: >
+  GooseWorks Product Photos — turn a brand's product images into publish-ready photography
+  (clean studio shots, lifestyle scenes, on-model looks) while keeping the product faithful
+  (silhouette, materials, logo, colorway). You pick a brand + product and submit; the GooseWorks
+  backend runs the SAME server-side pipeline the Product Photos studio uses (compose → generate →
+  judge → auto-retry) and bills credits. Use when the user says "make product photos", "shoot my
+  product", "studio/lifestyle/on-model photo of <product>", "generate product photography", or
+  references a product to photograph. Unlike goose-ads (ad creative) this produces clean PRODUCT
+  photos that can then feed the ad workflow.
+category: ads
+version: 0.2.0
+author: GooseWorks
+tags: [gooseworks, ads, product-photos, photoshoot, product, ecommerce, studio, lifestyle, on-model]
+---
+
+# GooseWorks Product Photos — branded product photography
+
+The GooseWorks Product Photos skill. You **pick a brand + product and submit one generation**;
+the **backend** runs the whole pipeline (compose the shot prompt → generate on `gpt_image_2` →
+judge for product fidelity → auto-retry a few times for free) and stores the results. You do NOT
+generate images, call a model, or manage files — this is the exact same workflow the Product
+Photos studio uses, so the skill and the app can never drift. The point is to **enrich a brand's
+usable product imagery** — approved photos join the brand kit and can then feed the ad workflow
+(`goose-ads`).
+
+## Prerequisite — the GooseWorks MCP server is REQUIRED
+
+Everything goes through the `mcp__gooseworks__*` tools. If they are not available, **stop and
+tell the user to run `gooseworks install --claude --mcp`** (and restart Claude Code). There is no
+HTTP/file fallback.
+
+## Start from the brand context — don't re-ask what it already answers
+
+If the `gooseworks` router handed you brand context, USE IT. If you were invoked directly, call
+`brand_get_context` yourself first. It answers most of the setup questions below, so **do not ask
+the user for them**:
+
+- **Which product?** — the context's `products[]` are the real catalog entries. Offer them; never
+  invent a product or ask the user to describe one you can already see.
+- **What does it look like / what is it made of?** — grounded in the product's stored images and
+  description. Never guess a material, colorway, or silhouette.
+- **What vibe / who is it for?** — the context's voice, positioning, and audience already say. Let
+  them shape the scene and styling instead of asking "what mood do you want?".
+- **Brand look** — logo, colors, and fonts are owned by the backend research pass. Read them, never
+  re-derive them.
+
+Ask only for the genuinely open choices: the shot `category`, how many photos, quality, and
+whether a human model is wanted (which needs explicit consent — see the rules).
+
+## Identity & credits
+
+- One agent-scoped token authenticates the tools; they resolve your org automatically. Never
+  print the token. (You may pass an optional `target` to operate on a specific agent/org, exactly
+  as the other GooseWorks tools; omit it to use your pinned scope.)
+- **Credits are handled by the backend.** `generate_product_photos` reserves the estimated cost up
+  front and bills only the photos that pass the judge — **automatic retries are free**, and a photo
+  the judge can't get right (`flagged`) is shown but **never billed**. Call
+  `estimate_product_photos` first to quote the cost; `get_ad_credits` shows the balance.
+
+## The tools
+
+**Pick the brand + product**
+- `list_ad_brands` — the user's ad brands (get a `brand_id`; also carries `slug`).
+- `list_brand_products { brand_id, search?, page?, page_size? }` — the brand's imported products.
+  Pick a `product_id` to shoot. `search` matches name / type / variant / SKU.
+- `import_product { brand_id, kind, url, product_name? }` — import a product if it isn't in the
+  catalog yet. `kind` is `product_url` (a single product page), `shopify_store` (a store URL →
+  imports the catalog), or `image_url` (a direct image; requires `product_name`). Returns an import
+  row with an `id`; if its `status` isn't `complete`, poll `get_product_import` until it is, then
+  `list_brand_products` to find the new product. (File uploads aren't available over MCP — use a URL.)
+- `get_product_import { import_id }` — poll an import until `status` is `complete` or `failed`.
+
+**Generate**
+- `estimate_product_photos { count, quality? }` — cost preview (per-photo + total credits). `count`
+  is 1, 2, 4, or 8; `quality` is `low` | `medium` | `high` (default `medium`). Reserves nothing.
+- `generate_product_photos { brand_id, product_id, variant_id?, category, controls?, prompt?,
+  count?, quality?, reference_image_urls?, attestation_accepted? }` — **the one call that makes
+  photos.** `category` is `apparel` | `beauty` | `cpg` (seeds sensible scene/framing defaults).
+  Omit `controls` to use the category preset; pass `prompt` as free-text steering **added on top of**
+  the settings (it doesn't replace them). Returns a generation with an `id` **immediately** — poll
+  `get_product_photo_generation` until done, then read each `outputs[].final_image_url`.
+  **If you request a human model** (`controls.model.presence` is not `none`) you MUST pass
+  `attestation_accepted: true` to confirm the user has the rights for model imagery.
+- `get_product_photo_generation { generation_id }` — poll until `status` is `complete`,
+  `partial_failure`, or `failed`. Each `outputs[]` entry has its own `status` and, once ready, a
+  `final_image_url`. A `flagged` output is the best attempt but wasn't billed.
+
+**Use the results**
+- `list_product_photos { brand_id, archived? }` — the brand's generated photos (`archived: false`
+  = active, `true` = archived).
+- `approve_product_photo { output_id }` — approve a photo: links it to the product and makes it
+  available in the **brand kit**, so `goose-ads` can use it. **Photos are not used anywhere until
+  approved.**
+- `archive_product_photo { output_id, reason? }` — archive a photo; archived photos are **excluded**
+  from ad generation.
+
+## Workflow — shoot a product
+
+1. **Load the brand context** (`brand_get_context`, or reuse what the router passed you) and
+   **resolve the brand + product.** `list_ad_brands` → `brand_id`. `list_brand_products` → pick a
+   `product_id` from the catalog you already know about. If the product genuinely isn't there,
+   `import_product` (poll `get_product_import`).
+2. **Quote the cost.** `estimate_product_photos { count, quality }` → tell the user credits.
+3. **Generate.** `generate_product_photos { brand_id, product_id, category, count, quality, prompt? }`.
+   Build `prompt` from the brand's voice/positioning you already have — don't interview the user for it.
+   Returns a generation `id` right away.
+4. **Poll.** `get_product_photo_generation { generation_id }` until terminal; hand back each
+   `final_image_url`.
+5. **Approve the keepers.** Show the results and let the user pick; `approve_product_photo` the ones
+   they'd publish (that's what puts them in the brand kit for ads), `archive_product_photo` the rest.
+
+## Rules
+
+- **Never invent product facts.** The backend grounds the shot on the product's real images; don't
+  describe a product you can't see.
+- **Use the brand context instead of interviewing the user.** Product, audience, voice, positioning,
+  logo/colors/fonts all come from `brand_get_context` / the brand kit. Ask only for the shot
+  category, count, quality, and model consent.
+- **Ask before spending.** Quote the estimate and confirm `count` / `quality` before
+  `generate_product_photos` — it reserves credits.
+- **Poll, don't re-submit.** A generation that's still `running` is not stuck; re-submitting
+  double-bills. Only a `failed` generation should be retried.
+- **Model imagery needs consent.** Only set a human model when the user asks, and pass
+  `attestation_accepted: true`.
+- **Approval is the hand-off to ads.** Remind the user that only **approved** photos reach the brand
+  kit / ad workflow; archived ones never do.