gooseworks 0.3.6 → 0.3.8

package/dist/skills/master-skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"master-skill.d.ts","sourceRoot":"","sources":["../../src/skills/master-skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAM7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CA8K9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAoOhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CA+MlD"}
+{"version":3,"file":"master-skill.d.ts","sourceRoot":"","sources":["../../src/skills/master-skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAM7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CA8K9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CA2QhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CA6OlD"}

package/dist/skills/master-skill.js

@@ -393,10 +393,49 @@ Then poll with \`get_remix_batch\` and hand back the links, same as above.
 
 ## Brand research
 
-Research normally runs in the GooseWorks backend (on onboarding). Just read the result with
-\`get_brand_kit\`. If a brand doesn't exist yet, you may \`create_ad_brand\` and let backend
-research run; you don't need to research locally. (A standalone local recipe still exists via
-\`gooseworks fetch brand-research\` if the user explicitly wants the agent to do it.)
+Prefer the backend's result: \`get_brand_kit { brand_id }\`. If \`researchStatus\` is
+\`complete\`, REUSE it — never re-research.
+
+**The split — backend owns visuals, you own the qualitative depth:**
+
+- **Backend LIGHT pass (automatic).** \`create_ad_brand\` with a \`website_url\` kicks off the same
+  backend research the web app uses, in \`mode: "light"\`: it resolves the **authoritative logo,
+  colors, and fonts** (Brandfetch + context.dev) plus a baseline kit, then flips
+  \`research_status\` to \`complete\` — usually under a minute. You can't reproduce those visual
+  signals locally, so **never re-derive logo/colors/fonts.** (Web onboarding via \`/api/ads/onboard\`
+  runs the full thing; nothing to do but read it.)
+- **Your DEEP pass (local, agentic).** You add the qualitative depth the light pass leaves thin —
+  positioning, audience segments, voice, brandType, value props, proof points, products — grounded
+  on the actual site.
+
+**CLI brand-research flow:**
+
+1. \`create_ad_brand { name, website_url }\` → keep \`brand_id\` + \`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\`
+   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
+   every fact on the fetched site** — if the site can't be read, say so and ask the user; never
+   guess a category from the brand name alone.
+4. **Write the pack** with \`write_file\` under \`agent-config/brands/<slug>/\`:
+   - the \`brand-research/*.md\` docs + \`brand-assets/manifest.json\` (human-readable pack), AND
+   - \`brand-research/kit-patch.json\` — the STRUCTURED fields the web UI renders. Field-for-field
+     contract; only what you put here reaches the kit. Shape:
+     \`{ positioning?: string, audience?: string, voice?: string, brandType?: string, tagline?: string, valueProps?: string[], proofPoints?: string[], products?: [{ name, description?, link?, pricing?, imageUrls?: string[] }] }\`
+     (\`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
+   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
+   before generating.
+
+**If the brand has NO website**, the backend light pass can't run (nothing to fetch) — do the whole
+thing locally (steps 3–6) and finalize; an un-finalized brand has no kit for generation and leaves
+no artifact to debug a wrong run (this is how a bad local classification, e.g. mislabelling a SaaS
+as a "drink company", used to vanish without a trace).
 
 ## Analyze / intelligence (fetched recipes — NOT generation)
 
@@ -496,9 +535,24 @@ id). The app NEVER runs you — it is the viewer + review surface; you are the r
   (the render-file route) from the org's DEFAULT agent, but MCP file writes default to your
   token's pinned agent — which can be a DIFFERENT agent, so a render written with the default
   scope is **invisible in the app**. First resolve the Ads agent: \`list_accessible_scopes\` → the
-  scope with \`is_org_default: true\` → its \`agent_id\` is \`ADS_AGENT\`. Then pass
-  \`target: { type: "agent", agent_id: ADS_AGENT }\` on EVERY \`get_upload_url\` / \`get_download_url\`
-  / \`write_file\` / \`list_directory\` / \`read_file\` — NEVER omit \`target\`.
+  scope with \`is_org_default: true\` (the ORG default — NOT the \`is_default\` / \`default_agent_id\`
+  fields, which are the *user's* default agent and are often a DIFFERENT agent). Its \`agent_id\` is
+  \`ADS_AGENT\` (name "Ads agent", slug \`org-default\`; usually also the \`agent_id\` in
+  credentials.json). Then pass \`target: { type: "agent", agent_id: ADS_AGENT }\` on EVERY
+  \`get_upload_url\` / \`get_download_url\` / \`write_file\` / \`list_directory\` / \`read_file\` — NEVER
+  omit \`target\`.
+- **CRITICAL — publish under the PROJECT FOLDER, not the workspace root (the #1 "video renders but
+  is invisible" bug).** \`get_upload_url\` stores at \`<ADS_AGENT>/files/<path>\` verbatim, but the
+  render-file route reads from
+  \`<ADS_AGENT>/files/agent-config/brands/<brand_slug>/projects/<project_id>/<path>\`
+  (see backend \`resolveProjectFileKey\`). So EVERY publish/preview \`path\` MUST be prefixed with
+  \`agent-config/brands/<brand_slug>/projects/<project_id>/\` — e.g. upload to
+  \`agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4\`, NEVER bare
+  \`working/final.mp4\`. A bare path 404s in the app even though the render row AND a bare-path
+  \`get_download_url\` both "succeed" (they resolve the wrong key). The render \`output_url\` still
+  stays the project-relative \`...render-file?path=working/final.mp4\` — the route re-prepends the
+  prefix itself. Always verify with \`get_download_url\` on the FULL \`agent-config/...\` path (must
+  be non-empty; curl it for HTTP 200) BEFORE marking the render complete.
 - Media generation (FAL / ElevenLabs) is billed to the agent through the GooseWorks proxies.
   \`submit_render { kind: "full" }\` debits **1 ad credit at row creation** — so sequence it LAST
   (render + verify a good MP4 first), and never re-submit on a guess (that double-bills). Call
@@ -513,31 +567,34 @@ id). The app NEVER runs you — it is the viewer + review surface; you are the r
    never re-research. If not, run brand research first (\`gooseworks fetch brand-research\`,
    follow it, then \`finalize_brand_research { brand_id }\`) before continuing.
 
-## Step 2 — fetch the recipe + its pack skills for the format
+## Step 2 — read the template's recipe (it carries everything; NO hardcoded format map)
 
-The video-ad format skills live in the goose-skills **\`video-ad-formats\`** pack. Map the project's
-\`format\` to its recipe slug:
+The ad format is a **template (data) in the ad_sample DB**, not a per-format skill.
+\`get_ad_template(source_sample_id)\` returns the template's \`recipe\` — a self-contained brief you
+read and execute. **Do NOT map \`format\` to a hardcoded recipe slug** (there is no such table):
 
-| format | recipe slug | renderer + atoms it drives |
-| --- | --- | --- |
-| \`imessage\` | \`remix-imessage-ad-from-sample\` | create-imessage-video-ad, create-imessage-mockup, stitch-videos-ffmpeg, mix-master, watch |
-| \`chatgpt\` | \`remix-chatgpt-ad-from-sample\` | create-chatgpt-video-ad, create-chatgpt-mockup, render-ios-keyboard, stitch-videos-ffmpeg, watch |
-| \`apple-notes\` | \`remix-apple-notes-ad-from-sample\` | create-apple-notes-video-ad, create-apple-notes-mockup, stitch-videos-ffmpeg, watch |
+- \`recipe.format\` — the format label (e.g. \`vignette\`), for display only.
+- \`recipe.atoms\` — the **capabilities** this template composes (e.g. \`create-video-seedance-2-fal\`,
+  \`create-image-gpt-image-fal\`, \`review-ugc-render\`, \`watch\`). \`gooseworks fetch <name>\` each — they
+  live in \`skills/ads/capabilities/\` and are reused across templates (so they cache).
+- \`recipe.instructions\` — the **playbook** to follow: \`instructions.inline\` prose, or
+  \`instructions.doc_url\` (an S3 markdown doc — fetch it).
+- \`recipe.config\` — every param (prompts, layout, timings, palette, model choices).
+- \`recipe.inputs\` — the brand-asset contract (which product / logo / offer this template needs).
+- \`recipe.assets\` — reference material as S3 links (reference render, style guide, example frames) —
+  fetch as needed.
 
-(photo-grid + music-video coming.) Pack skills are fetchable individually by slug but do NOT
-auto-resolve dependencies (no \`dependencySkills\`), so \`gooseworks fetch\` the recipe **and** each
-skill in its row — e.g. for iMessage:
+Runtime: **read the recipe → \`gooseworks fetch\` each capability in \`recipe.atoms\` → follow
+\`recipe.instructions\` with \`recipe.config\` + the brand's bound \`inputs\`.** The template IS the recipe;
+there is no \`format → recipe-slug\` table and no per-format skill to fetch.
 
-\`\`\`bash
-for s in remix-imessage-ad-from-sample create-imessage-video-ad create-imessage-mockup \\
-         stitch-videos-ffmpeg mix-master watch; do gooseworks fetch "$s"; done
-\`\`\`
+Save each fetched capability's scripts + files under \`/tmp/gooseworks-scripts/<name>/\`. If a capability
+is a Node package (a phone-mockup renderer), \`npm install\` in its folder so its \`generate.js\` +
+Playwright resolve, and point the recorder's \`NODE_PATH\` at it.
 
-Each prints \`{ content, scripts, files }\`. Save each skill's scripts + files under
-\`/tmp/gooseworks-scripts/<slug>/\` and FOLLOW the recipe's SKILL.md — it orchestrates the others.
-The renderer (the \`create-*-mockup\` atom for the format) is a Node package —
-\`npm install\` in its folder so its \`generate.js\` + Playwright resolve, and point the recorder's
-\`NODE_PATH\` at it.
+> **Migration note:** older phone-mockup formats (\`imessage\` / \`chatgpt\` / \`apple-notes\`) whose DB
+> recipe does not yet carry \`atoms\` / \`instructions\` still hold the legacy \`recipe.thread\` payload;
+> migrate them to this shape (capabilities + instructions in the DB) — do not reintroduce a CLI map.
 
 ## Step 3 — prepare ALL the ingredients, then review ONCE (always, before any paid render)
 
@@ -549,7 +606,10 @@ ingredients out one at a time.
    that's typically: the **script** (the bubble thread), the **image(s)** shown in the conversation
    (one or more), and the **end card**. Richer templates add more (hook frame, background, product
    shots, music bed…). Read the recipe for the exact ingredient list. Generate the visuals NOW
-   (media proxies / recipe), and \`get_upload_url\` each preview asset to \`working/review/<name>\`.
+   (media proxies / recipe), and \`get_upload_url\` each preview asset to the project folder
+   \`agent-config/brands/<brand_slug>/projects/<project_id>/working/review/<name>\` (the same
+   path-prefix rule as final publish — a bare \`working/review/<name>\` won't render in the panel).
+   In \`script_drafts\`, set each ingredient's \`path\` to the project-relative \`working/review/<name>\`.
    You may ask the user a couple of clarifying questions about the generation first if the recipe
    calls for it (angle, which product, offer/code) — batch them, then prepare everything.
 2. **Mirror the whole ingredient set for review** — \`update_ad_project_script { project_id,
@@ -581,11 +641,18 @@ ingredients out one at a time.
    \`append_project_message\` instead.
 3. QC by watching: run the \`watch\` skill on the master — verify bubble/beat order + SFX, that
    the brand's product (not the source's) is shown, the end card has the real wordmark + code,
-   and the duration is within ~20% of the source.
+   and the duration is within ~20% of the source. For UGC/Seedance formats there are no captions
+   and often no local Whisper key: extract frames with ffmpeg for the visual pass, and get the
+   spoken transcript by running \`fal-ai/whisper\` through the SAME \`fal-proxy\` (upload the audio,
+   pass its \`get_download_url\` as \`audio_url\`) — confirm the transcript matches the script and the
+   brand name is pronounced right, with no word-repeat dysfluency, BEFORE spending the render credit.
 4. Publish: \`get_upload_url { target: { type: "agent", agent_id: ADS_AGENT } }\` → PUT the master
-   to \`working/final.mp4\` and a poster to \`working/final-thumb.jpg\`. **Always target ADS_AGENT**
-   (see Identity — a file on your token's own agent is invisible to the app). Verify servable:
-   \`get_download_url { target: ADS_AGENT, path: "working/final.mp4" }\` must return a non-empty URL.
+   and poster **under the project folder** (see Identity's path-prefix rule) — to
+   \`agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4\` and
+   \`.../working/final-thumb.jpg\`. **Always target ADS_AGENT AND use the full project-folder path**
+   — a bare \`working/final.mp4\`, even on the right agent, 404s in the app. Verify servable:
+   \`get_download_url { target: ADS_AGENT, path: "agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4" }\`
+   must return a non-empty URL (curl it for HTTP 200).
    Then \`update_render_status { render_id, status: "complete", output_url, thumbnail_url }\` where
    **output_url MUST be the durable render-file URL**
    \`/api/ads/projects/<project_id>/render-file?path=working/final.mp4\` (the app re-presigns it on
@@ -643,7 +710,9 @@ def fal_generate(model_path, payload, timeout_s=180, poll_s=3):
 
 ElevenLabs (VO / music) is the same shape against \`<api_base>/api/internal/elevenlabs-proxy\`
 with \`?token=&agent_id=\`. Feed FAL a local image by storing it (\`get_upload_url\`) and passing its
-\`get_download_url\` presigned URL as an \`image_urls\` entry, or POST the bytes to \`fal-storage-proxy\`.
+\`get_download_url\` presigned URL as an \`image_urls\` / \`audio_url\` entry — this is the reliable
+path. (\`fal-storage-proxy\` may 404 depending on the install; don't block on it — prefer the
+\`get_download_url\` presigned URL.)
 
 ## Rules
 

package/dist/skills/master-skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"master-skill.js","sourceRoot":"","sources":["../../src/skills/master-skill.ts"],"names":[],"mappings":";;AA4BA,wCAMC;AAWD,sDA8KC;AAiBD,0DAoOC;AAcD,8DA+MC;AAlpBD,oDAAoD;AACpD,SAAgB,cAAc;IAC5B,OAAO;QACL,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,qBAAqB,EAAE,EAAE;QACxD,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,EAAE,EAAE;QACzD,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,yBAAyB,EAAE,EAAE;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4KR,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,uBAAuB;IACrC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkOR,CAAC;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,yBAAyB;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6MR,CAAC;AACF,CAAC"}
+{"version":3,"file":"master-skill.js","sourceRoot":"","sources":["../../src/skills/master-skill.ts"],"names":[],"mappings":";;AA4BA,wCAMC;AAWD,sDA8KC;AAiBD,0DA2QC;AAcD,8DA6OC;AAvtBD,oDAAoD;AACpD,SAAgB,cAAc;IAC5B,OAAO;QACL,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,qBAAqB,EAAE,EAAE;QACxD,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,EAAE,EAAE;QACzD,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,yBAAyB,EAAE,EAAE;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4KR,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,uBAAuB;IACrC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyQR,CAAC;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,yBAAyB;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2OR,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gooseworks",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "GooseWorks CLI — give your coding agent real data tools",
   "bin": {
     "gooseworks": "./dist/index.js"