gooseworks 0.4.4 → 0.4.5-dev.15.facf60fb

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

@@ -11,7 +11,7 @@ description: >
   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
+version: 0.3.0
 author: GooseWorks
 tags: [gooseworks, ads, product-photos, photoshoot, product, ecommerce, studio, lifestyle, on-model]
 ---
@@ -19,13 +19,16 @@ tags: [gooseworks, ads, product-photos, photoshoot, product, ecommerce, studio,
 # 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
+the **backend** runs the whole pipeline (compose the shot prompt → generate → 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`).
 
+It shoots a **physical catalog product** (apparel, beauty, consumer goods). A software
+screenshot or an app mockup is not a product photo: that is an image edit, not this skill.
+
 ## How to talk to the customer (applies to every message you send them)
 
 The customer is a marketer or founder, not an engineer. Everything in this skill about tools,
@@ -78,19 +81,54 @@ and approval before spending. Hosted installed snapshots use the existing Skills
 Skill content and a host's cached MCP tool schemas are separate: refreshing one does not refresh
 the other. Check the actual advertised tools before using new fields.
 
-## Prerequisite — the GooseWorks MCP server is REQUIRED
+## No GooseWorks tools in this session? Call them through the CLI
+
+The GooseWorks tools named here (for example `account_whoami`, `brand_onboarding`,
+`brand_read`) normally come from the GooseWorks connector. If they are not registered in this
+session but you have a shell with the `gooseworks` CLI signed in (a cloud sandbox such as
+ChatGPT agent, Meta AI or Grok), call the same tool from the shell:
+
+```bash
+npx gooseworks tool <name> '<arguments as a JSON object>'
+```
+
+- Run `npx gooseworks tool --list` once first. It prints the server's rules for using the tools
+  and every tool name; `npx gooseworks tool <name> --schema` shows one tool's arguments.
+- The result prints as JSON. When a tool answers with a one-line summary, the fields you act on
+  (such as `next_step` and ids) follow under "Data:". It exits 1 when the tool reports an error.
+- Nothing renders as a widget here, so tell the user the result in plain words.
+- The same rules apply as over the connector: state the credit total and get the user's yes
+  before paid work.
+- If it says you are not logged in, run `npx gooseworks login --device --no-wait`, show the
+  user the link and code it prints, and run `npx gooseworks login --device` once they approve.
+
+When the tools are registered in this session, call them directly instead.
+
+## Prerequisite — the GooseWorks connector tools
+
+Everything below runs through the GooseWorks connector's tools, by the names this skill uses.
+Match on the tool name: a coding agent may show a server prefix (for example
+`mcp__gooseworks__photos_generate`), a chat app may not.
+
+If a tool named here is missing, the GooseWorks connection or its tool list is stale: ask the
+user to reconnect or refresh GooseWorks in their app's connector settings. Installing or
+updating the `gooseworks` CLI never fixes a missing connector tool, so never send a chat-app
+user to a terminal for it. Only a terminal coding agent (Claude Code, Codex, Cursor) that has no
+GooseWorks tools at all connects them, in that terminal, with `gooseworks install --mcp` plus
+`--claude`, `--codex` or `--cursor`, then a restart.
 
-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.
+Older notes or skill copies may name tools the connector no longer lists. Use the tool this skill
+names instead; `catalog_fetch { type: "skill", slug: "gooseworks-guide" }` maps every old name.
 
 ## 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_read` yourself first. It answers most of the setup questions below, so **do not ask
-the user for them**:
+`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }` yourself first, then
+`knowledge_search { brand_id, query: "<the shoot, in the user's words>" }` for saved rules and past
+feedback (an archived photo's reason is saved as a `dont` rule). They answer 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
+- **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.
@@ -102,79 +140,90 @@ the user for 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
+## Credits — state the total, then get a yes
 
-- 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.
+- One token authenticates the tools and resolves your org; never print it. Omit `target`.
+- **Quote first.** Call `photos_generate` with the exact arguments you will submit plus
+  `dry_run: true`. It reserves nothing and returns `creditsPerOutput` and `totalCredits`. Pass
+  `count` and `quality` explicitly in both calls so the quote matches the run.
+- **Nothing paid runs without the user's explicit yes in this chat, given after you state that
+  credit total.** Then submit the same call without `dry_run`.
+- The submit reserves the quoted credits 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**. The balance is `credits.available_credits` from `account_whoami`. If the
+  wallet is short, say so plainly with the total and the balance, and stop.
 
 ## 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`.
+- `brand_read` with no `brand_id` — the user's brands (each row's `id` is the `brand_id`).
+- `brand_read { brand_id, sections: ["products"], products_query: "<name>" }` — the brand's
+  imported products in `products.items`; a product's `id` is the `product_id` to shoot.
+  `products_query` matches name / type / variant / SKU / description.
+- Import a product that isn't in the catalog yet (free):
+  `brand_update { brand_id, patch: { products: [{ import_url, import_kind, name? }] } }`.
+  `import_kind` is `product_url` (a single product page), `shopify_store` (a store URL → imports
+  the catalog), or `image_url` (a direct image; also needs `name`). It returns `jobs[]`: poll
+  `job_get { job_id, kind: "product_import" }` until it finishes, then read the products again.
+  To add a photo the user attached to an existing product:
+  `media_upload { brand_id, scope: "product", scope_id: <product_id>, kind: "reference", source: { type: "bytes", filename, content_base64 } }`.
 
 **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`.
+- `photos_generate { brand_id, product_id, variant_id?, category, controls?, prompt?, count,
+  quality, reference_image_urls?, attestation_accepted?, dry_run? }` — **the one call that makes
+  photos** (and, with `dry_run: true`, its free quote). `category` is `apparel` | `beauty` |
+  `cpg` (seeds sensible scene/framing defaults). `count` is 1, 2, 4, or 8; `quality` is
+  `low` | `medium` | `high`. 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 the
+  generation with its `id` **immediately**.
   **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
+- `photos_read { brand_id, generation_id }` — poll until `status` is `complete`,
+  `partial_failure`, or `failed` (`job_get { job_id: <generation id>, kind: "photo_generation" }`
+  works too). Each `outputs[]` entry has its own `id`, `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.
+- `photos_read { brand_id, archived?, product_id?, status? }` — the brand's generated photos
+  (`archived: false` = active, `true` = archived).
+- `photos_update { brand_id, output_id, action: "approve" }` — 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.**
+- `photos_update { brand_id, output_id, action: "archive", reason? }` — archive a photo; archived
+  photos are **excluded** from ad generation, and the reason is saved as a `dont` rule.
 
 ## Workflow — shoot a product
 
-1. **Load the brand context** (`brand_read`, 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
+1. **Load the brand context** (`brand_read` + `knowledge_search`, or reuse what the router passed
+   you) and **resolve the brand + product.** Pick a `product_id` from the catalog you already
+   know about. If the product genuinely isn't there, import it and poll the import.
+2. **Quote the cost.** `photos_generate` with `dry_run: true` and the exact `brand_id`,
+   `product_id`, `category`, `count` and `quality` → tell the user the credit total and wait
+   for their explicit yes.
+3. **Generate.** The same `photos_generate` call without `dry_run` (add `prompt` built from the
+   brand's voice/positioning you already have — don't interview the user for it). Returns a
+   generation `id` right away.
+4. **Poll.** `photos_read { brand_id, generation_id }` every ~20-30s until terminal; show 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.
+5. **Approve the keepers.** Show the results and let the user pick; `photos_update` with
+   `action: "approve"` the ones they'd publish (that's what puts them in the brand kit for ads),
+   `action: "archive"` the rest.
 
 ## Rules
 
+- **Connector tools only** — a missing tool means the GooseWorks connection is stale: ask the
+  user to reconnect or refresh GooseWorks. Never send a chat-app user to a terminal or a CLI
+  install.
 - **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_read` / 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.
+- **Ask before spending.** State the dry-run credit total and get the user's explicit yes before
+  the real `photos_generate` — 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.
+  double-bills. A `failed` generation may still hold `flagged` photos (shown, never billed):
+  show those first, and run again only after a new quote and the user's yes.
 - **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