gooseworks 0.4.4 → 0.5.0-dev.5.1ff84a4f

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,31 @@ 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
+## 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 +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_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

package/skills/goose-video/SKILL.md

@@ -7,7 +7,7 @@ description: >
   goose-video-local; a chat host hands the same project to the GooseWorks coworker. Review
   one complete template plan and total credits before production. Custom videos retain two authenticated review gates in this chat.
 category: ads
-version: 3.0.0
+version: 3.0.5
 author: GooseWorks
 tags: [gooseworks, ads, video, local-render, coworker, chat]
 ---
@@ -78,9 +78,210 @@ and `available_here`, never a guess from the host's name. Template-remix review
 chat. Custom videos use separate authenticated script and ingredient approvals in this same chat.
 Studio is an optional review surface.
 
-## Custom videos: route before formats
+## Prepare the video workflow and brand before creative work
 
-For an original brief without a reference template, an Instagram reel/post URL or a direct video URL to study, fetch `catalog_fetch { type: "skill", slug: "make-custom-video" }` and follow it in this same session. It creates format:"custom", custom_mode:"generate" with the brief and optional reference_url. Growth executes in its managed sandbox; connected agents use their shell. Script and actual ingredients are reviewed and separately approved in the same chat before paid production; Studio is optional. Do not force a template choice or import the reference as a finished video.
+**Installed entry files are bootstrap instructions.** For new work started from an installed
+file or an old chat, fetch `catalog_fetch { type: "skill", slug: "goose-video" }` on the selected
+connection and read its returned content and dependencies before continuing. Use the already
+fetched body when this entry came from that connection in this run; do not recursively fetch
+the same entry. A CLI freshness warning does not block using the current connected package.
+Keep the fetched package and hashes in a new run folder; do not replace edited installed files.
+If current instructions cannot be loaded, resolve the connection before format suggestions,
+script writing or production. Do not continue from an old installed workflow or session notes.
+
+**Follow the connector's full-guide requirement when available.** Fetch
+`catalog_fetch { type: "skill", slug: "gooseworks-guide" }` when the connector requires it.
+The only older-server exception is below; it never removes brand preparation or approvals.
+
+| Returned guide/workflow state on the selected connection | Required action |
+| --- | --- |
+| Guide returns `not_found`, and this same connection already returned the complete current matching video entry with its required dependencies | Continue with that authoritative entry's workflow, full brand preparation and existing approvals. |
+| Guide has another error, no response, or incomplete content; or the matching entry/dependencies are missing, incomplete or from another connection | Stop before creative work, project writes or paid calls; resolve a compatible connection on this same environment. |
+
+A missing custom entry or required custom tool/schema remains unavailable: never substitute
+a template or an import to bypass it. Never hide other fetch errors or continue from cached
+instructions merely because the guide was not found.
+
+**For an existing project or batch, read `video_project_read` first.** Determine its actual
+route and saved review state before fetching a recipe or doing local work. Resume an approved
+run with its recorded packages, brand inputs, script and ingredients; do not silently replace
+them with today's release or brand rules. Follow returned preparation requirements and use
+the existing affected review/approval flow for an intentional change. Reads, free drafts,
+imports and existing-job retrieval do not grant permission for new paid production.
+
+**For every new plan, resolve the brand and call**
+`brand_read { brand_id, sections: ["summary", "kit", "products", "learnings"] }` **before**
+suggesting formats, mining video angles, writing any script, creating a production plan or
+handing the work to another agent. Use `brand_get_context` with those same four sections only
+when advertised. Reuse a complete read from this run on the same connection and brand.
+Onboarding completion, a summary-only response and earlier session notes do not supply the
+kit, selected product facts or saved rules. If the full read is unavailable, resolve it before
+creative work. Use known kit facts while research is incomplete; do not restart research
+solely because its status is pending. Never invent a product fact or accept a campaign to
+bypass preparation. Then search the Brand Brain (next section) before suggesting formats,
+choosing an angle or asking the user for a brand fact.
+
+Carry that context through custom/template/idea routing and delegation. Before writing, make
+the workflow's brand-rules file from those sources: pronunciations, required spoken copy,
+prohibited claims, real logo, font, palette and the selected product's supported facts.
+Entries prefixed `Video preference:` and visual/pacing instructions are creative direction,
+not spoken lines. Use the kit's audience, offer and voice as defaults without an interview.
+The rules file mirrors context; it is not proof of a read or permission to spend. Keep the
+route's existing script, ingredient and budget approvals, including its allowed previews.
+
+**Use the server's brand bundle when the selected API returns it.** Project create/read may
+return top-level
+`brand_context`: `{ version: 1, brand_id, digest, loaded_at, sections, brand, kit, products,
+learnings }`. Its sections cover summary, kit, products and learnings.
+
+| Returned brand/project response on the selected connection | Required action |
+| --- | --- |
+| A complete authoritative version-1 `brand_context` is returned | Binding is required: use its contents for the plan/rules and include `script_drafts.brand_context_digest = brand_context.digest` with each new/changed script save. |
+| An older API returns the actual four brand sections but no `brand_context` in either the brand read or project response | Prepare from those full sections, write the brand rules and follow the selected connection's existing approval flow and advertised fields. Do not fabricate a receipt or send nonexistent bundle/digest fields. |
+
+An incomplete/malformed bundle or missing brand section is a preparation failure, never the
+older-API exception. Once this connection returns an authoritative bundle, use its binding
+contract. `script_drafts.video_brand_context` is server-owned: do not author, replace or forge
+it, and do not invent a read receipt or hash local brand facts into one. Keep the full bundle
+out of client review payloads. If managed generation returns HTTP 409
+`video_brand_context_required`, reload the project and bind the plan to its returned bundle
+through the normal review flow before retrying. That refusal never permits the older-API
+fallback, skipping sections or retrying paid calls blindly. Unchanged approved legacy resumes
+retain their package, context and approvals; an upgrade alone needs no extra approval.
+
+**To apply a deliberate brand correction to a new or revised plan**, make a fresh, unfiltered
+`brand_read` of those four sections. When it returns the authoritative bundle, use its
+returned `brand_context.digest` in the complete revised `script_drafts` through the existing
+`video_project_upsert` `patch.script` save; the server verifies the current brand and replaces
+its snapshot with the saved plan. On an older API with no bundle contract, apply the actual
+four-section correction and save the revised draft through its existing flow without inventing
+digest fields. If a connection that already returned a bundle cannot supply the fresh bundle,
+resolve that failure before rebinding. Review and approve the affected script, ingredients and
+budget through the normal flow. Never refresh an ongoing approved run automatically; its
+recorded package and brand inputs stay pinned until an intentional change.
+
+## Search the Brand Brain, then propose — before any creative choice or question
+
+The Brand Kit is a summary. The brand's saved knowledge (its Brain) holds what the Kit does not:
+rules from past feedback, approved and rejected creatives, customer evidence, approved claims,
+reports and documents. **After `brand_read`, and before you choose an angle, claim, hook,
+product emphasis, format or source ad — and before you ask the user for any brand fact — call
+`knowledge_search { brand_id, query }`** when it is registered. It is free and read-only: no
+approval, no announcement to the customer and no questionnaire.
+
+1. **Search for this task, not the whole Brain.** Run one short query (under 500 characters) in
+   the user's own words plus the product (for example "ads for <product>: what worked, what to
+   avoid") and one with
+   `source_types: ["evidence", "claim", "learning", "creative", "document"]` for proof and past
+   creative results. Add a query only for a specific open question. Reuse results from this run.
+2. **Keep these states distinct** and record which one each query returned:
+
+| Result | Means | Do |
+| --- | --- | --- |
+| `status: "ok"` with matches | Saved knowledge exists | Use it; keep each fact's citation in your working brief |
+| `status: "empty"` | Nothing saved matches this query | Say "no saved evidence for <topic>", never "the brand has no proof" |
+| `refresh_required` | The results shown are current; some changed sources were left out | Use them; search again shortly for anything missing |
+| `building` | The index is not ready | Retry once shortly, then continue with the gap stated |
+| An error, or the tool is not registered | Retrieval failed or is unavailable | Retry an error once, then continue from `brand_read` and treat evidence as unchecked |
+| An empty Kit field | Only that field is blank | Not a search result: still search before asking |
+
+3. **Let the findings change the plan.** A `dont`/`must` learning or a rejected creative rules
+   options out; an approved or well-rated past creative is a proven angle to lead with; a report
+   shows what worked. Claim-grade proof is a result with `approved_ad_claim: true` or the kit's
+   `approvedClaims` within their stated applicability; the kit's `proofPoints` are what the
+   backend allows an ad to state, used as written. Other Kit text, documents and performance
+   numbers are context, never public claims. Never invent an offer, price or result. Judge
+   relevance and skip results about another product or business.
+4. **Propose; don't interview.** Lead with one recommended direction (angle, product, source or
+   format) and a one-line reason naming what you found, with up to two alternatives. When several
+   directions fit (two audiences, products or campaigns), pick the one the evidence favours, such
+   as an active campaign or approved past creatives, and name the other as an alternative instead
+   of asking. Ask only for a decision the brand read and the search cannot settle, or for spend
+   approval. Never ask the user for a fact the Brain already answered.
+   Keep directions already chosen (the user's words, a project's creative brief, handed-off
+   defaults, approved plans): search only to fill empty fields and to apply saved rules. When a
+   returned card or picker presents the choice, your recommendation is its one acknowledgement
+   line and the saved plan's defaults, not a separate list.
+5. **Carry an evidence brief** into the routed skill, writer or plan: findings with citations,
+   the state of each query, what it ruled out and the open gaps. Tell the customer the findings
+   in plain words; the citations stay in the brief.
+
+On an approved resume, keep the saved brief and evidence; search again only for a new decision.
+
+## Custom videos: check formats first
+
+First check the catalog: when the brief names or implies a listed format (for example a street interview, testimonial, podcast or chat video), show that format and its fit through the format flow below, including its support status. Go custom only when no format fits and the customer chooses custom after hearing why; custom keeps that format's hard constraints. For an original brief without a reference template, an Instagram reel/post URL or a direct video URL to study, fetch `catalog_fetch { type: "skill", slug: "make-custom-video" }` and follow it in this same session. It creates format:"custom", custom_mode:"generate" with the brief and optional reference_url. Growth executes in its managed sandbox; connected agents use their shell. Script and actual ingredients are reviewed and separately approved in the same chat before paid production; Studio is optional. Do not force a template that does not fit or that the customer declined, and do not import the reference as a finished video.
+
+## Run the format's route check before proposing it
+
+A catalog row says what a format is best for and ranks it for the brand. It does not say whether
+the format can make the setup the customer asked for (how many people, mic only, no product).
+Some renderers declare a route selector that decides that; today that is the street interview
+(`render-street-interview`). Before you propose, script or create a street-interview project,
+template or custom, check the request against its routes:
+
+| Street route | On screen | Needs | Makes |
+| --- | --- | --- | --- |
+| Guessing (`product-guess`) | Interviewer and up to four people | A physical product to hand over, photographed on its own | A finished video |
+| Conversation (`mic-only`, `product-sample`, `concept-challenge`) | Interviewer and one person | No product photo, phone, screen or UI | A script and prompt preview only, no finished video yet |
+| Street testimonial (its own format) | One person talking to camera, no interviewer | The creator still its recipe prescribes | A finished video, when the catalog lists it |
+
+Neither interview route takes a photo of a person: people are described in text, so never
+propose putting a founder's or creator's face in one. Keep the customer's named setup: never
+change the interaction, mode or number of people just to make a check pass.
+
+- **Without a shell** (a chat host), decide from this table. Do not fetch the renderer: its
+  package is far too large for a chat.
+- **With a shell** (the customer's computer or the coworker sandbox), also run its free
+  selector, which makes no paid call. If the fetch or the run fails, decide from the table.
+  1. Fetch the renderer to a file, not into the conversation: its inline package is over a
+     million characters. Either save the JSON from `gooseworks fetch render-street-interview > <file.json>`,
+     then write each `scripts` entry as
+     `/tmp/gooseworks-scripts/render-street-interview/scripts/<name>` and each `files` entry at
+     `/tmp/gooseworks-scripts/render-street-interview/<path>`. Or call
+     `catalog_fetch { type: "skill", slug: "render-street-interview", delivery: "archive" }`,
+     extract the ZIP, check each file against its `manifest.json` hashes and copy the contents of its
+     `agent-config/skills/render-street-interview/` folder into
+     `/tmp/gooseworks-scripts/render-street-interview/`. Either way the selector reads
+     `references/street-reference-library.json` from that folder.
+  2. Write a brief JSON. `mode` and `interaction_type` go in pairs: `product-guess` with
+     `product-guess`, or `conversation` with `mic-only`, `product-sample` or `concept-challenge`.
+     `offering_type` is exactly `physical`, `service` or `digital` (software, SaaS and apps are
+     `digital`). `participants` is a whole number: people interviewed on screen, not counting
+     the interviewer. Leave it out when the customer named no count; the selector then uses the
+     route's usual cast. When the customer named no interaction, run each mode that could fit.
+  3. Run `python3 /tmp/gooseworks-scripts/render-street-interview/scripts/prepare_script_context.py --brief <brief.json> --out <context.json>`.
+     Read `status` and `brief_gaps` in the output file, not the exit code: it exits 2 for every
+     status except `ready-for-writing`. A Python traceback is not a verdict: the brief or the
+     saved files are wrong (for example the reference library in the wrong folder). Fix them and
+     run it again.
+  4. A run with any `brief_gaps` has not checked the route. Fix every gap and run it again.
+
+**An unsupported setup is a stop.** `unsupported-route`, or a request the table rules out,
+means this setup can't be made. Tell the customer plainly, in one line, for example: "A
+three-person mic-only street interview isn't something we can make yet: that version takes one
+person, and the three-person version needs a physical product to hand over." Then offer the
+closest supported options in plain words, each with how it differs. With a shell, these are the
+selector's `alternatives`. Without one, take them from the table:
+
+- when only the number of people was the problem, the same setup within its limit: guessing
+  (a physical product only) with up to four people, a finished video; or a conversation with
+  one person, a script preview only;
+- for something people can't hold (software, a service), a one-person conversation instead
+  of guessing;
+- one person talking to camera with no interviewer, if the catalog lists that format;
+- a custom video, untested, that keeps the street format's limits.
+
+Never use route names or the script's wording. Do not create the project or write a script for
+it. Go custom only if the customer picks it; a custom video keeps the street format's hard
+constraints, which make-custom-video lists.
+
+**A supported setup.** With empty `brief_gaps`, any other status means the route exists.
+`needs-reference` means no observed reference ad matched yet: it does not block proposing the
+format; carry it into the handoff so the script step resolves or reports it before script
+approval. Carry the route too: which one, how many people, finished video or preview only, and
+no person photos. A preview-only route makes a script and prompt preview, not a finished video:
+say so before the customer chooses it.
 
 ## Route first: is this a new video?
 
@@ -90,9 +291,10 @@ Hand off to **`goose-video-local`** now, and stop following this skill, for:
 - the app's copy-for-Claude command (it names `goose-video-local`);
 - "remix this video ad template" for a specific app template.
 
-Use `goose-video-local` if it is installed; otherwise load it with
+Load the current `goose-video-local` entry with
 `catalog_fetch { type: "skill", slug: "goose-video-local" }` on the GooseWorks MCP (older clients:
-`fetch_skill("goose-video-local")`). It reads the project first and says what to do with it.
+`fetch_skill("goose-video-local")`), unless already fetched on this connection in this run.
+It reads the project first and retains an approved run's recorded recipe packages.
 
 When they ask **what** to make ("give me video ad ideas", "what angles should I use?", "what's
 working for my competitors?"), fetch **`ad-angle-miner`** (`catalog_fetch { type: "skill", slug: "ad-angle-miner" }`,
@@ -147,8 +349,9 @@ review set; do not add a separate approval round.
 ## Save durable brand answers, then verify them
 
 Read the selected brand with `brand_read { brand_id, sections: ["summary", "kit", "products", "learnings", "onboarding"] }`
-(fallback: `brand_get_context` with the same sections). Keep founder answers, user corrections,
-research and your own hypotheses distinct. Reuse matching saved answers; ask only about gaps.
+(older clients: `brand_get_context` with the same sections, only when that tool is advertised).
+Keep founder answers, user corrections, research and your own hypotheses distinct. Reuse
+matching saved answers; ask only about gaps.
 
 When the user asks to remember a rule, answers a brand interview, or explicitly corrects a
 standing fact, save that answer in the same turn. The capture request authorizes those answers;
@@ -272,14 +475,15 @@ bypass setup. Keep the original request.
 ### 2. Keep the goal and propose defaults
 
 Never ask what the ad is for before showing formats. Keep the customer's exact direction.
-Otherwise propose defaults from the verified kit's products, audience, offer and voice. Show
-those defaults in the saved plan so any can be changed. Never invent proof or product facts.
+Otherwise propose defaults from the verified kit's products, audience, offer and voice and the
+Brain search's evidence brief (proven angles, saved rules, approved claims). Show those defaults
+in the saved plan so any can be changed. Never invent proof or product facts.
 Idea requests still follow ad-angle-miner with the video output.
 
 ### 3. Show the picker or its text fallback
 
 Call `video_catalog_list { kind: "formats", brand_id }`. On the customer's computer, when you
-can actually execute shell commands, include `client: { shell: true }`; in a chat host omit
+can actually execute shell commands, you MUST choose local execution and include `client: { shell: true }`; in a chat host omit
 that claim. Inside a coworker sandbox follow its reported capabilities, never claim to be the
 customer's computer. Respect requested limit and next_cursor for more item pages; the card may
 contain a full picker independently of the item page.
@@ -291,6 +495,9 @@ contain a full picker independently of the item page.
   Write "no demo yet" when absent. Never put links only in a question control.
 - A format whose card contradicts what they asked for is never Suggested. Never offer
   available_here:false as an executable choice. Relay not_available_here in one short line.
+- `suggested` ranks a row for the brand; it never means the row makes the setup they named.
+  Never tell the customer a row is "exactly" what they asked for beyond what its card says. A
+  street interview still needs the route check above first.
 - Missing required assets are missing; unknown suitability is “needs review.” Inspect the
   selected format's candidates before spending. Never promise an unverified asset is ready.
 - Template formats use **one plan, one approval with the total in credits**, not approval for
@@ -302,7 +509,7 @@ contain a full picker independently of the item page.
   Never tell a chat host it needs Claude Code to start. Browser-only formats remain unavailable
   here; give computer setup guidance only if asked how to make one.
 - **Local shell:** run `gooseworks doctor --no-browser` for common setup (auth/MCP, Node 18+,
-  ffmpeg with libx264 + libass, ffprobe). Then fetch the selected template and its capabilities,
+  ffmpeg with libx264 (libass only for an ASS caption route), ffprobe). Then fetch the selected template and its capabilities,
   and install documented dependencies in its fetched folder. Do not guess a renderer from a
   format name. For each Node renderer using default Playwright Chromium, run
   `gooseworks doctor --renderer-script "/absolute/path/to/the/fetched/scripts/record.js"` with
@@ -318,7 +525,8 @@ contain a full picker independently of the item page.
 ### 5. Create the project and hand it off, in this session
 
 1. `video_project_upsert { brand_id, name, format: <template_id> }` with no brief (a brief creates
-   a concept batch). Include client:{shell:true} only for real local execution. Default
+   a concept batch). A street interview is created only after its route check found a supported
+   setup. Include client:{shell:true} only for real local execution. Default
    creation_intent:"format" keeps the style with this brand's content; source_remix requires an
    explicit choice to use source content.
    If they already chose a campaign/concept, include its verified campaign_id and optional
@@ -326,9 +534,10 @@ contain a full picker independently of the item page.
    to it. Omit unknown IDs and never infer a link or create a campaign solely to file a video.
 2. **Verified local shell or coworker sandbox:** load
    `catalog_fetch { type: "skill", slug: "goose-video-local" }` and follow it on the same project_id.
-   Carry the customer's words, verified defaults, campaign and selected angle into its brief.
+   Carry the customer's words, verified defaults, campaign, selected angle and a street
+   interview's route check result into its brief.
 3. **Chat host:** `goose_run_task { brand_id, project_id, message }` with the request, selected
-   format and defaults. Keep task_id. Continue questions/edits with the same task and project.
+   format, defaults and a street interview's route check result. Keep task_id. Continue questions/edits with the same task and project.
    A saved free draft is not a started worker or a complete plan. Follow actual saved state.
 4. When follow.card_follows is true, the card follows progress: do not re-read it in a loop.
    Read again on a customer reply, card action or requested update. A failure or missing saved