gooseworks 0.4.2 → 0.5.0-dev.3.8661ef81

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,26 +19,93 @@ 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`).
 
-## 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.
+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,
+fields, files, polling, models and pipeline steps is for YOU. Never pass it on to them.
+
+- **Say what they get and what they need to decide, never how it's made.**
+  Bad: "Checking the media-proxy helpers for voiceover timestamps and lipsync." / "Generated with
+  gpt-image-2 at high quality, mouth closed, passes QC."
+  Good: "Recording the voices now." / "Here are your two hosts."
+- **Never mention** tool, file or field names, ids, JSON, commands, scripts, installed software,
+  uploads, model or vendor names, timings in seconds or frames, retries, polling, internal statuses
+  or your own quality checks. Fix what you can quietly. If they ask how something works, explain it
+  simply.
+- **Update them only at milestones they care about**: choices confirmed, script and voices done,
+  visuals done, ready to review, finished. One short line each, then stay quiet until the next
+  milestone. No update for setup, downloads, uploads or saving.
+- **Money is in credits, with a number**: "the full video uses about N credits". Never "the cheap
+  pieces" or "the expensive render".
+- **Problems:** say what it means for them and what they can do, in one or two sentences. No error
+  codes or stack traces. Only raise a problem that changes something for them.
+- **Use their words**: script, voice, hook, scene, host, ending, logo, the product shot.
+- **No filler**: no "Great question!", "Certainly!", "I hope this helps!", no restating what they
+  just said at length.
+
+Example. Instead of a dozen lines about render tools, scripts, uploads and portraits, send:
+"Got it: warm tone, home podcast studio, Brielle as the skeptic and Mark as the believer." then
+"Script and voices are done (about 34 seconds)." then "Ready for you to review: the script, voices,
+both hosts and the ending. You can also review your recipe ingredients in the app: <link>. Say go
+here and I'll make the full video (about N credits)."
+
+## Use current instructions for new work
+
+Before a new task in a terminal host, run `gooseworks skills status` once. It compares the
+installed entry files, running CLI and published npm release. An older CLI needs a package
+upgrade before `gooseworks update`; update alone only uses that CLI's bundled instructions.
+Preserve local edits or unknown install provenance. Review/back up before explicitly replacing
+modified files; never quietly reinstall over them. If the release check is unavailable, report
+that freshness is unknown rather than claiming the local copy is latest.
+
+For a new recipe run, fetch its package from the connected catalog. Retain the returned
+`version` / `contentHash` and every dependency's hash with the saved package. When reusing a
+saved fetch JSON, `gooseworks fetch <slug> --saved-package <file>` returns the current package
+and a hash comparison without changing that file. With MCP, if the advertised `catalog_fetch`
+schema accepts them, send `saved_content_hash` and `saved_dependency_hashes`; otherwise fetch
+normally and compare the returned hashes yourself. Missing hashes mean unknown, not current.
+The server cannot inspect a client's saved files; hash metadata does not certify later edits.
+Fetch current packages into a new run directory and report stale saved instructions. Preserve
+an existing approved run's recorded package; changing that harness requires a reviewed change
+and approval before spending. Hosted installed snapshots use the existing Skills Update action.
+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 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.
+
+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_get_context` 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.
@@ -50,79 +117,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_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
+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_get_context` / the brand kit. Ask only for the shot
+  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