@kolbo/mcp 1.21.0 → 1.22.0

package/skill/references/workflows/marketing-studio.md

@@ -0,0 +1,157 @@
+# Marketing Studio — UGC, Ads & Branded Video
+
+Load this file when the user wants **branded ad video** — UGC, unboxing, product showcase, TV spot, virtual try-on, or any "make me an ad / commercial / creator video" request.
+
+For ad **images** (Pinterest pin, hero banner, ad creative pack) see `workflows/product-photoshoot.md`.
+For **marketplace listings** (Amazon main + secondary + A+ content) see `workflows/marketplace-cards.md`.
+For the **DTC ads engine flow** (brand kit + ad format + avatar + product) see `workflows/dtc-ads.md`.
+
+## The 9 Marketing Modes
+
+| Mode | What it's for | Hook/Setting allowed? |
+|---|---|:-:|
+| `ugc` | **Default.** Casual, organic-feel content from a presenter | ✅ |
+| `ugc_how_to` | Tutorial / explainer — "here's how to use this" | ✅ |
+| `ugc_unboxing` | Unboxing reveal — "just got this in the mail" | ✅ |
+| `product_showcase` | Clean product highlight, polished | ❌ |
+| `product_review` | Presenter giving an opinion on the product | ✅ |
+| `tv_spot` | Broadcast-style commercial, higher production | ❌ |
+| `wild_card` | Experimental — model picks the vibe | ❌ |
+| `ugc_virtual_try_on` | Person trying on clothing / accessories — UGC vibe | ✅ |
+| `virtual_try_on` | Same but polished, model-driven | ❌ |
+
+**"Hook/Setting allowed"** = whether reusable opening hook prompts and scene-setting prompts can be prepended to the user prompt. Polished modes (`product_showcase`, `tv_spot`, `wild_card`, `virtual_try_on`) ignore hooks/settings.
+
+**Default when the user doesn't specify a mode:** `ugc`.
+
+## Picking the Mode
+
+| User phrasing | Mode |
+|---|---|
+| "UGC", "creator video", "talking head", "phone-shot", "selfie video", "vlogger" | `ugc` |
+| "tutorial", "how to use", "demonstrate", "walkthrough", "explainer" | `ugc_how_to` |
+| "unboxing", "just got this", "reveal", "first impression" | `ugc_unboxing` |
+| "product showcase", "highlight reel", "showroom" | `product_showcase` |
+| "review", "my take on", "comparing X to Y", "honest opinion" | `product_review` |
+| "TV ad", "commercial", "broadcast", "polished ad spot" | `tv_spot` |
+| "surprise me", "something different", "experimental" | `wild_card` |
+| "try on" / "wearing the X" + organic vibe | `ugc_virtual_try_on` |
+| "fashion shoot", "lookbook", polished try-on | `virtual_try_on` |
+
+If the user mentions a product / brand but no mode word, default to `ugc`. If they say "ad" without "TV ad" / "commercial" / "broadcast", default to `ugc` (most modern ads are UGC-shaped).
+
+## Mode → Kolbo MCP Routing
+
+The mode determines which Kolbo MCP tool to call, what defaults to set, and what's forbidden.
+
+| Mode | Primary tool | aspect_ratio | duration | sound_enabled | Captions / watermarks |
+|---|---|---|---|:-:|:-:|
+| `ugc`, `ugc_how_to`, `ugc_unboxing`, `ugc_virtual_try_on`, `product_review` | `generate_video_from_image` (frame-first) OR `generate_elements` (Visual DNA → video) | **`9:16`** | model's `default_duration` (5–8s) | OFF | **Never add** |
+| `product_showcase` | `generate_creative_director` with `workflow_type: "video"` (for multi-shot) OR `generate_video` (single) | `16:9` or `1:1` | 5–10s | ON if model supports `sound_generation_type: "native"` | Allowed if user asks |
+| `tv_spot` | `generate_creative_director` with `workflow_type: "video"` (3–6 shots for a beat structure) | `16:9` | 15–30s total | ON (full audio + dialogue) | Allowed if part of the spot |
+| `virtual_try_on` | `generate_elements` with character Visual DNA + product as `reference_images` | `9:16` or `4:5` | 5–8s | OFF | Never add |
+| `wild_card` | User's chosen model with broader prompt latitude (no mode-specific defaults) | User's pick | User's pick | User's pick | User's pick |
+
+**Pick the actual model** with `list_models({ type: "..." })` and validate caps before firing — see SKILL.md "Resolution / Aspect / Duration — validate against caps".
+
+## UGC Family Defaults (CRITICAL)
+
+When ANY `ugc*` mode is selected, snap to these unless the user explicitly overrides:
+
+| Setting | UGC default | Why |
+|---|---|---|
+| `aspect_ratio` | `9:16` | TikTok / Reels / Shorts are vertical-first |
+| Visual aesthetic | Phone-shot, handheld, natural lighting | UGC works because it doesn't look produced |
+| Camera language | Slight handheld sway, selfie-arm framing, key light from window/screen | NOT slow dollies, NOT crane moves, NOT studio key |
+| Energy | "Talking to a friend" — casual, direct-to-camera, occasional gestures | Not theatrical, not staged |
+| **Captions / subtitles / text overlays** | **NEVER add** unless explicitly requested | Users add captions in CapCut / native editor; baked-in captions limit reuse |
+| **Brand watermarks / lower-thirds / banners** | **NEVER add** unless explicitly requested | Same reason |
+| Music / SFX | OFF by default unless asked | They'll layer their own audio in post |
+| Length | Model's `default_duration` (typically 5–8s) | Shorter = more usable for the algorithm |
+
+**Phrases that activate UGC defaults:** "UGC", "user-generated", "creator video", "TikTok", "Reels", "Shorts", "POV", "selfie video", "phone-shot", "vlogger", "talking head" (when context implies social media), "for social", "Instagram video", "YouTube short".
+
+**Phrases that OVERRIDE UGC defaults** (use them as-given, not as UGC): "commercial", "ad spot" (without UGC), "cinematic", "broadcast", "TV ad", "horizontal", "16:9", "landscape", "billboard". When the user uses one of these, switch to `product_showcase` or `tv_spot` mode.
+
+## Hooks & Settings (concept)
+
+Hooks and settings are **reusable opening angles / scene contexts** that get prepended to the user's prompt. Kolbo does not yet expose these as first-class MCP primitives, but the concept is portable:
+
+- **Hook** = the opening line / angle of the ad (the first 1–2 seconds that earn the scroll). Example hooks: "POV: you just discovered X", "Why I stopped buying Y", "3 reasons this X is worth it", "Watch this before you buy a Y".
+- **Setting** = the scene/environment context. Example settings: "in a bright minimalist kitchen", "walking in a busy city street", "on a yoga mat at golden hour".
+
+**When the user asks for an ad and doesn't specify the opening**, offer 2–3 hook options (one-liner each) in a labeled-question style — never freeform "what hook?" Same for setting if the brief is location-agnostic.
+
+**Whitelist rule:** hooks/settings only make sense for `ugc`, `ugc_how_to`, `ugc_unboxing`, `product_review`, `ugc_virtual_try_on`. For `product_showcase`, `tv_spot`, `wild_card`, `virtual_try_on` — skip hooks/settings; those modes are concept-driven not hook-driven.
+
+**Mutually exclusive with ad references** (next section). Pick one path per generation.
+
+## Ad References (modeling new ads after existing ones)
+
+Sometimes the user has a reference ad they want to model the new ad after — their own previous winning ad, a competitor's ad, or a viral video. Kolbo path:
+
+1. **Upload the reference video** via `upload_media` (returns CDN URL).
+2. **Pass it as `reference_videos`** to `generate_elements`, OR as `source_video` to `generate_video_from_video` (if you want to actually restyle / re-shoot the reference).
+3. **Describe in the prompt** what to preserve from the reference (`@video1`'s pacing / camera move / lighting / cut rhythm) and what to change (subject / product / setting).
+4. **Tag with `@video1`** per `workflows/visual-dna.md` reference-tagging rules.
+
+**Mutually exclusive with hooks/settings** — pick one composition path per generation. Either reference-driven (use `@video1`) or composed-from-blocks (hook + setting + product). Mixing produces muddled output.
+
+## Avatars (= Visual DNA characters)
+
+What other platforms call "preset avatars" or "custom avatars" Kolbo calls **Visual DNA characters**. Two ways to get one:
+
+- **Existing character** — use `list_visual_dnas` to find one the user has already created.
+- **New character** — create with `create_visual_dna({ type: "character", name, images: [...] })`. See `workflows/visual-dna.md` for the full creation flow (pre-flight, naming rule, generate-reference-images-first).
+
+**For UGC modes:** an avatar is optional if the brief clearly mentions a person (the model can synthesize one). Pass `visual_dna_ids` when the user wants a *specific* presenter — their face, the brand founder, a previously trained character.
+
+**Always use `@<dna-name>` in the prompt** when passing `visual_dna_ids` — see `workflows/visual-dna.md` `@name` rules.
+
+## Products (image upload + reference)
+
+For ads that feature a specific product:
+
+1. **Upload product photo** via `upload_media` → Kolbo CDN URL.
+2. **Pass as `reference_images`** to `generate_creative_director` / `generate_elements` / `generate_video_from_image`.
+3. **Tag with `@image1`** in the prompt.
+4. **Log in `.kolbo/production.md`** under a `### Products` subsection so future ads in the same workspace reuse the same CDN URL (don't re-upload).
+
+If the user gives a **product URL** instead of a photo, see `workflows/research-first.md` — scrape, extract images, re-host via `upload_media`, persist as a brand kit at `.kolbo/brand-kits/<slug>.md`.
+
+## UX Rules
+
+1. **Always pick a mode explicitly.** Don't auto-pick from one ambiguous word. If the user said "make me an ad" with no other signal, offer labeled options: `[UGC / TV Spot / Product Showcase / Surprise me]`.
+2. **Always confirm aspect ratio + duration + sound** before firing — these materially change output and cost. One question, labeled options.
+3. **Default UGC settings are hard rules** — captions OFF, music OFF, watermarks OFF — even when the user doesn't mention them. Only flip when they ask.
+4. **No auto-retry on failure.** If the generation fails (content policy, model OOM), surface the reason and let the user adjust prompt or product.
+5. **Show results without dumping URLs** — see SKILL.md "Generated URLs in chat".
+
+## Prompt Template Seed for UGC
+
+```
+UGC selfie video, vertical 9:16, handheld phone aesthetic.
+{presenter description or @<dna-name>} in {everyday setting},
+{energy level: relaxed | enthusiastic | curious | reactive}.
+They {natural action with the product/subject},
+talking directly to camera.
+Phone-shot lighting (window/screen key light),
+slight handheld sway, no cinematic moves.
+Style: authentic creator content, NOT polished commercial.
+Sound: ambient room tone only, no music, no SFX overlay.
+```
+
+## Prompt Template Seed for TV Spot
+
+```
+3-shot broadcast commercial, cinematic 16:9.
+
+Shot 1 [0–5s] — {establishing hook}: {wide angle subject + camera move}, {lighting}, {tone setter}.
+Shot 2 [5–15s] — {product reveal / demo}: {medium shot with product in focus}, {practical action}, {emotional beat}.
+Shot 3 [15–25s] — {payoff + CTA}: {close-up or pull-back}, {brand line in dialogue or SFX}, {final hold}.
+
+Style: {brand mood — e.g., warm + premium / clean + modern / bold + youthful}.
+Audio: full mix — dialogue + score + SFX. Music: {genre/tempo}.
+```
+
+(Run via `generate_creative_director` with `workflow_type: "video"`, `scene_count: 3`.)

package/skill/references/workflows/marketplace-cards.md

@@ -0,0 +1,146 @@
+# Marketplace Cards — Amazon / Shopify / eBay Listings
+
+Load this file when the user wants **marketplace listing visuals** — main image, secondary product images, infographics, or A+ content modules for Amazon, Shopify, eBay, Etsy, Walmart, or similar.
+
+For generic brand product photography (Pinterest, hero banner, lifestyle, ad pack) see `workflows/product-photoshoot.md`. For ad video see `workflows/marketing-studio.md`. For composed DTC ads see `workflows/dtc-ads.md`.
+
+## What This Is
+
+Marketplace listings need a **specific, compliance-aware visual system** that's different from brand campaign imagery:
+
+- **Main image** — strict marketplace rules (typically pure white background, product fills 85% of frame, no text, no props, no shadows). This is the conversion-critical thumbnail.
+- **Secondary product images** — multi-angle, detail shots, lifestyle, "what's in the box". Show the product from every angle a shopper needs before clicking buy.
+- **A+ content / Enhanced Brand Content (Amazon)** — long-form modules below the fold: hero banner, pain-point grid, feature comparison, ingredients breakdown, efficacy proof, how-to-use steps, brand endorsement / founder story.
+
+## The 4 Bundle Scopes
+
+When the user asks for a common bundle, fire one call per scope:
+
+| Scope | Creates |
+|---|---|
+| `main` | 1 marketplace main image |
+| `product-images` | main image + 5 secondary images |
+| `aplus` | main image + 7 A+ content modules |
+| `full-set` | main image + 5 secondary + 7 A+ modules (13 assets total) |
+
+Use a **custom subset** of the asset list below when the user wants a non-standard combination (e.g. "just main + infographic + lifestyle").
+
+## The 13 Asset Types
+
+| Asset | Purpose | Aspect ratio | Model preference |
+|---|---|---|---|
+| `main_image` | Marketplace thumbnail — strict compliance: pure white bg, product fills 85% of frame, no text, no props | `1:1` | Nano Banana 2 (clean studio render) |
+| `infographic` | Feature callouts with text labels and product hero | `1:1` or `4:5` | **GPT Image 2** (dense on-image text) |
+| `multi_angle` | 4-up grid showing front / back / sides of product | `1:1` | Nano Banana 2 |
+| `detail_shot` | Macro shot of texture / material / mechanism | `1:1` | Nano Banana 2 |
+| `lifestyle` | Product in use in real environment | `1:1` or `4:5` | Nano Banana 2 |
+| `whats_in_box` | Flat-lay showing the product + accessories laid out neatly | `1:1` | Nano Banana 2 |
+| `aplus_hero_banner` | Wide A+ header — brand identity hit | `3:1` | GPT Image 2 |
+| `aplus_pain_points` | 3-up grid showing the problem this product solves | `16:9` | GPT Image 2 (text) |
+| `aplus_features` | 3-up or 4-up feature breakdown with labels | `16:9` | GPT Image 2 |
+| `aplus_ingredients` | Ingredients / materials breakdown (skincare, food, supplements) | `16:9` | GPT Image 2 |
+| `aplus_efficacy` | Before/after, % stats, clinical results — proof block | `16:9` | GPT Image 2 (charts + text) |
+| `aplus_how_to_use` | Numbered step-by-step usage instructions | `16:9` | GPT Image 2 |
+| `aplus_endorsement` | Founder story, brand mission, testimonial-style | `16:9` | Nano Banana 2 (people) + GPT Image 2 (text overlay) |
+
+## Kolbo MCP Routing
+
+For **bundles** (`product-images`, `aplus`, `full-set`): use `generate_creative_director` with `scene_count` = number of assets in the bundle. Pass the product image as `reference_images[0]` so it appears consistently across every asset. Each scene's prompt encodes one asset type.
+
+For **single `main` image** or **custom subset** of ≤ 2 assets: `generate_image` per asset, fired in parallel (single response, multiple tool calls).
+
+For **multi-angle** specifically: this is one image with a 4-up grid composition — use `generate_image` with a prompt describing the 2×2 layout, NOT `generate_creative_director`. (Or alternatively, fire 4 separate `generate_image` calls and composite the grid yourself — depends on user preference.)
+
+**Always pass the product photo** as `reference_images` for every call. `@image1` references it in the prompt. If the user gave a URL instead of a photo, run `workflows/research-first.md` first.
+
+## Main Image Compliance Rules (HARD)
+
+Different marketplaces have different rules. The **strictest is Amazon's**, which most other marketplaces follow:
+
+1. **Pure white background** (`#FFFFFF`, no gradients, no shadow tone).
+2. **Product fills ≥ 85% of the frame** — minimal margin.
+3. **NO text** — no logos baked in, no callouts, no "NEW" stickers, no watermarks.
+4. **NO props** — just the product. No hands, no models, no styling pieces.
+5. **NO multiple products** — single hero (variant grids go in secondary, not main).
+6. **NO color borders / decorative frames**.
+
+Bake these into every `main_image` prompt as explicit prohibitions:
+
+```
+Pure white background (#FFFFFF), seamless studio sweep.
+Product (@image1) centered, fills 85% of frame.
+Tack-sharp focus, no shadows on background, soft contact shadow only.
+NO text, NO logos, NO captions, NO props, NO models, NO decorative borders.
+Photographic, catalog-grade, neutral color.
+```
+
+## Secondary Image Strategy
+
+5-image standard set (when the user says `product-images` scope):
+
+1. **Lifestyle** — product in use, real environment
+2. **Detail / texture** — macro of the key material or feature
+3. **Multi-angle** — 4-up showing all sides
+4. **What's-in-the-box** — flat-lay of components
+5. **Scale / size reference** — product next to a hand or known-size object
+
+Adjust based on category: skincare needs ingredients close-up + texture-on-skin; apparel needs front + back + on-model + detail + size chart; electronics needs ports/buttons close-up + size comparison.
+
+## A+ Content Strategy
+
+A+ modules tell a story below the fold. Standard 7-module flow:
+
+1. `aplus_hero_banner` — brand identity / aspirational hero
+2. `aplus_pain_points` — what problem we solve
+3. `aplus_features` — how we solve it (3–4 differentiators)
+4. `aplus_ingredients` (skincare/food/supplements) OR materials/specs (electronics/apparel)
+5. `aplus_efficacy` — proof (before/after, % stats, third-party data)
+6. `aplus_how_to_use` — usage steps
+7. `aplus_endorsement` — founder story / mission / testimonial
+
+For dense-text modules (`aplus_features`, `aplus_pain_points`, `aplus_efficacy`, `aplus_how_to_use`): always recommend **GPT Image 2** at `resolution: "2K"` or `"4K"` (text needs the higher tier to stay sharp).
+
+## Brand Kit Reuse
+
+Check `.kolbo/brand-kits/<slug>.md` before generating. Pull `primary_color`, `accent_color`, `text_color`, `bg_color`, `fonts`. Bake into every A+ module prompt — marketplace pages live or die on visual consistency across the 13 assets.
+
+## Pre-Generation Interview
+
+Ask 2–3 short labeled questions before firing:
+
+1. **Which marketplace?** `[Amazon US / Amazon EU / Shopify / Etsy / eBay / Walmart / Other]` — affects compliance rules
+2. **Which bundle?** `[main / product-images / aplus / full-set / custom subset]`
+3. **Brand kit?** Auto-detect from `.kolbo/brand-kits/<slug>.md`; otherwise ask if brand colors / fonts should be applied
+
+Skip questions whose answer is obvious from the request.
+
+## Output Discipline
+
+- For bundles: `generate_creative_director` returns N URLs. Present them in chat as a numbered list, one URL per line, with the asset name as label:
+  ```
+  Marketplace cards ready:
+  1. Main image: https://...
+  2. Lifestyle: https://...
+  3. Detail shot: https://...
+  ...
+  ```
+  Do NOT wrap them in an HTML grid artifact — the canvas already shows the gallery.
+- Log all URLs to `.kolbo/production.md` under `## Production: <product name>` → `### Marketplace Cards` subsection.
+- If a `main_image` came back with text / props (compliance failure), surface the issue and re-fire with stronger prompt prohibitions — don't ship a non-compliant main image.
+
+## Existing Main-Image Reuse
+
+If the user already has an approved `main_image` from a prior session and wants to generate only secondary / A+ assets that match it:
+
+1. Look up the main image URL from `.kolbo/production.md`.
+2. Pass it as `reference_images[0]` (in addition to the product photo) so the new assets match the main's exact rendering style — same lighting, same color cast, same product orientation.
+3. Tag it as `@image2` in the prompt: "Match the product rendering from `@image2` exactly — same angle, same lighting, same color cast."
+
+## UX Rules
+
+1. **Always ask which marketplace** — compliance rules vary.
+2. **Strict compliance prompts on main_image** — explicit NO text / NO props / NO models / NO borders.
+3. **Always reuse brand kit** — Read `.kolbo/brand-kits/<slug>.md` first; pass palette + fonts to every A+ module.
+4. **Recommend GPT Image 2 + 2K/4K for dense-text A+ modules** — Nano Banana renders text well but GPT Image 2 wins at multi-line technical layouts.
+5. **For bundles, always use `generate_creative_director`** — never fire 13 parallel `generate_image` calls.
+6. **Log everything to `.kolbo/production.md`** — marketplace listings get updated quarterly; reuse beats regenerate.

package/skill/references/workflows/media-library.md

@@ -0,0 +1,76 @@
+# Media Library
+
+Load this file when the user wants to browse, list, organize, delete, restore, move, favorite, share, or otherwise manage their media library — or when you produce a media file locally and need to surface it back to the user.
+
+The library covers both **uploaded files** and **AI-generated outputs the user has saved**. Tools fall into five groups: ingest, browse, lifecycle (delete/restore/move), folders, and favorites.
+
+## ⚠️ Present locally-produced media to the user
+
+When you produce a media file LOCALLY — `ffmpeg` via the `video-production` skill, Remotion render, manual `Bash` mux of audio + video, `edit_image` outputs saved to disk, any save-to-file flow — make sure the user can actually find and open it. Local files are invisible in the chat / canvas UI by default; only the path string makes it through.
+
+**Rules:**
+
+1. **Surface the file in chat as a clickable thing**, not just a path string. Write the line as a markdown link to a `file://` URL so the user can click to open it in their default app:
+   ```
+   ✅ Final video ready: [zohar_hagai_campaign.mp4](file:///Users/mymac/Documents/test agent 1/zohar_hagai_campaign.mp4) (45s · 1440×1440 · with music)
+   ```
+   The user clicks the link → the desktop app shell hands the path to the system → opens in QuickTime / VLC / Finder reveal, etc.
+
+2. **Always log the local path in `.kolbo/production.md`** under the artifact's entry — that's the durable record:
+   ```md
+   ## Final
+   - **Campaign video (45s)**
+     - local: /Users/mymac/Documents/test agent 1/zohar_hagai_campaign.mp4
+     - resolution: 1440×1440
+     - audio: Gilded Horizon (Track 1 & 2, 3:03)
+     - rendered: 2026-05-16
+   ```
+
+3. **Don't auto-upload to `upload_media`**. The user wants local-only files to stay local; they have the file on disk and can move/share it themselves. Upload only when the user explicitly asks ("upload this", "share publicly", "give me a CDN URL").
+
+4. **Reveal-in-Finder affordance for macOS** when finishing a multi-step production: in addition to the `file://` link, mention the parent directory path so the user can `cd` or open the folder. Many users want to see all the intermediate files (frames, alt cuts, original audio) in one place.
+
+5. **Files served via `file://` won't render inline** in the chat as `<video>` / `<img>` — the desktop WebView blocks file:// for security. Don't try to embed; just link.
+
+## Routing — user says → call
+
+| User says | Call |
+|---|---|
+| "Upload this file" / "host this" / "give me a public URL for this" | `upload_media` |
+| "Show my media" / "list my images/videos" / "what do I have?" | `list_media` (pass `type` / `category` / `project_id` / `folder_id` / `search`) |
+| "Show my favorites" / "list starred items" | `list_media` with `category=favorites` |
+| "List everything in project X" | `list_media` with `project_id=X` |
+| "List all videos in folder X" | `list_media` with `folder_id=X, type=video` |
+| "What was the prompt for [item]?" / "tell me about this generation" | `get_media` |
+| "How many videos do I have?" / "what's my storage usage?" | `get_media_stats` |
+| "Favorite this" / "star this" / "save to favorites" | `favorite_media` |
+| "Unfavorite" / "remove from favorites" / "unstar" | `unfavorite_media` |
+| "Delete this" / "remove this image" | `delete_media` (soft, recoverable for 30 days) |
+| "Restore it" / "undelete" / "bring it back from trash" | `restore_media` |
+| "Permanently delete" / "wipe it forever" / "free up space" | **confirm with user** → `permanently_delete_media` |
+| "Move this to project X" | `move_media` |
+| "Clean up old [type]" / "delete everything from [time period]" | `list_media` (find ids) → **confirm** → `bulk_delete_media` |
+| "Restore all from trash" | `list_media include_deleted=true` → `bulk_restore_media` |
+| "Empty my trash" / "purge deleted items" | `list_media include_deleted=true` → **show count, confirm** → `bulk_permanently_delete_media` |
+| "Move all these to project X" | `bulk_move_media` |
+| "Move everything in folder X to project Y" | `move_folder_contents` |
+| "Make a folder for X" / "create a 'campaigns' folder" | `create_media_folder` |
+| "Rename folder" / "change folder color or icon" | `update_media_folder` |
+| "Delete the [name] folder" | **confirm with user** → `delete_media_folder` (items stay in library) |
+| "Add these to [folder]" / "put these in folder X" | `add_media_to_folder` |
+| "Remove these from [folder]" | `remove_media_from_folder` |
+| "Share [folder] with alice@…" | `share_media_folder` with `user_emails: [...]` |
+| "Revoke [user]'s access to [folder]" | `unshare_media_folder` with `user_id` |
+| "Show my folders" / "what folders do I have?" | `list_media_folders` |
+
+## Rules and gotchas
+
+1. **"Delete" is soft by default.** Use `delete_media` / `bulk_delete_media` for normal "delete" intent — items go to trash for 30 days and are recoverable. Only use `permanently_delete_media` / `bulk_permanently_delete_media` when the user explicitly asks for unrecoverable deletion ("permanently", "forever", "wipe", "free up space"). **Always confirm before either permanent variant.**
+2. **Confirm before destructive folder ops.** `delete_media_folder` detaches items (they stay in the library) but the folder itself is gone — no undo. Confirm with the user.
+3. **`bulk_move_media` is atomic.** If you get a "not all items owned by you" error, do NOT retry partially. Surface the error to the user and let them pick a smaller batch.
+4. **Prefer `list_media` filters over post-filtering.** Pass `project_id` / `folder_id` / `category` / `type` / `search` to the backend; don't fetch the whole library and filter client-side.
+5. **`is_favorited` is per-user.** On shared projects, an item can be favorited by you and not by your teammates — the value reflects the calling user only.
+6. **"Empty trash" flow:** `list_media` with `include_deleted=true` → show the count → confirm → `bulk_permanently_delete_media`. Never call the bulk-permanent endpoint without listing first so the user knows the scope.
+7. **Bulk caps:** 1000 ids for `bulk_delete_media` / `bulk_restore_media` / `bulk_permanently_delete_media` / `bulk_move_media`; 500 ids for `add_media_to_folder` / `remove_media_from_folder`. Split larger jobs into successive calls.
+8. **Folder share resolution:** `share_media_folder` takes emails; users not found come back in `not_found`. Report those to the user — don't assume the share succeeded silently. Members can list/add/remove items but cannot delete the folder or reshare it.
+9. **`get_media` accepts a generation_id as a fallback** for the `media_id` arg, so you can chase down items the user references by their original generation rather than by library id.

package/skill/references/workflows/product-photoshoot.md

@@ -0,0 +1,199 @@
+# Product Photoshoot — Brand Product Imagery
+
+Load this file when the user wants **brand-quality product images** — studio shots, lifestyle scenes, Pinterest pins, hero banners, social carousels, ad packs, virtual try-ons, conceptual / CGI product shots, or seasonal restyles.
+
+For ad **video** see `workflows/marketing-studio.md`. For composed brand ads (brand kit + ad format + avatar) see `workflows/dtc-ads.md`. For marketplace listings (Amazon main + secondary + A+ content) see `workflows/marketplace-cards.md`.
+
+## The 10 Modes
+
+Pick by intent, not surface keyword. When two modes could apply, prefer the more specific one.
+
+| Mode | When user wants… |
+|---|---|
+| `product_shot` | Product on neutral / studio / catalog background (Shopify, white-bg) |
+| `lifestyle_scene` | Product in a real environment — hands, action, atmosphere (kitchen, gym, outdoor) |
+| `closeup_product_with_person` | Tight crop with hands or partial face — beauty application, demonstrating, holding |
+| `moodboard_pin` | Vertical 2:3 Pinterest-native pin, moodboard feel |
+| `hero_banner` | Wide-format website / email / campaign header |
+| `social_carousel` | 3–10 connected slides for IG / LinkedIn / Facebook |
+| `ad_creative_pack` | Coordinated pack of static ad variants for Meta / TikTok / Pinterest / Google Ads |
+| `virtual_model_tryout` | Product worn or used by an AI-rendered model (fashion, accessories) |
+| `conceptual_product` | Surreal / CGI / levitating / splash / sculptural product |
+| `restyle` | Transform an EXISTING image's aesthetic, mood, or seasonal context (without changing the subject) |
+
+### Picking the Mode
+
+| User phrasing | Mode |
+|---|---|
+| neutral / clean / white / studio / catalog / Shopify | `product_shot` |
+| scene / in use / kitchen / outdoor / cafe / gym | `lifestyle_scene` |
+| hands holding / face with product / beauty application / demonstrating | `closeup_product_with_person` |
+| Pinterest / pin / vertical pin | `moodboard_pin` |
+| hero / banner / website header / landing page / email header / wide format | `hero_banner` |
+| carousel / slide post / multi-slide / swipeable | `social_carousel` |
+| ads / ad pack / paid social / Meta / TikTok / Pinterest ads / Google ads | `ad_creative_pack` |
+| model wearing / virtual try-on / on body / fashion shoot / lookbook | `virtual_model_tryout` |
+| levitating / floating / splash / frozen motion / surreal / CGI / sculptural | `conceptual_product` |
+| modify EXISTING image's aesthetic / mood / season — without changing subject | `restyle` |
+
+**Tie-breakers:**
+- "Pinterest pin of my product on a kitchen counter" → `moodboard_pin` (Pinterest is the platform)
+- "Hero banner showing my product in use" → `hero_banner` (banner format wins)
+- "Carousel of my product in different scenes" → `social_carousel` (multi-slide wins)
+- "Closeup of person applying my serum" → `closeup_product_with_person` (specific genre wins)
+
+## Mode → Kolbo MCP Routing
+
+The mode determines which Kolbo MCP tool to call and what defaults to use.
+
+| Mode | Primary tool | Model preference | aspect_ratio | Count default |
+|---|---|---|---|---|
+| `product_shot` | `generate_image` | GPT Image 2 (clean studio look + dense label text) | `1:1` | 1 or `num_images: 3` for variants |
+| `lifestyle_scene` | `generate_image` | Nano Banana 2 (best lifestyle realism) | `1:1` or `4:5` | 1 or `num_images: 3` |
+| `closeup_product_with_person` | `generate_image` | Nano Banana 2 | `1:1` or `4:5` | 1 |
+| `moodboard_pin` | `generate_image` | Nano Banana 2 | **`2:3`** (Pinterest native) | 1 or `num_images: 3` |
+| `hero_banner` | `generate_image` | GPT Image 2 (large format + brand text) | `16:9` or `3:1` | 1 |
+| `social_carousel` | **`generate_creative_director`** with `scene_count: 3–10` | Nano Banana 2 | `1:1` (IG) or `4:5` | `scene_count` |
+| `ad_creative_pack` | **`generate_creative_director`** with `scene_count: 4–8` | GPT Image 2 or Nano Banana 2 | Mixed per ad placement (`1:1`, `9:16`, `1.91:1`) — fire one director call per aspect | `scene_count` |
+| `virtual_model_tryout` | `generate_image_edit` with character Visual DNA + product source | Nano Banana Pro (identity-sensitive edits) | `1:1`, `4:5`, or `9:16` | 1–3 |
+| `conceptual_product` | `generate_image` | Nano Banana 2 or GPT Image 2 | `1:1` or `2:3` | 1–4 |
+| `restyle` | `generate_image_edit` with `source_images: [existing]` | Same model that produced the original (or Nano Banana 2 for safe re-render) | Inherit from source | 1–3 |
+
+**For multi-output modes** (`social_carousel`, `ad_creative_pack`), always use `generate_creative_director` — never fire ≥2 `generate_image` calls in a loop. See `models/creative-director.md`.
+
+**Always validate** `aspect_ratio` and `resolution` against the chosen model's `supported_aspect_ratios` / `supported_resolutions` via `list_models` — see SKILL.md "Resolution / Aspect / Duration — validate against caps".
+
+## Pre-Generation Interview (CRITICAL)
+
+Ask **at most 4 short questions** before submitting, always with **labeled options, never open-ended**. Skip a question whose answer is obvious from context (uploaded image, prior turn, brand memory in `.kolbo/brand-kits/`).
+
+Pick the question stack based on user state:
+
+### Type A — Uploaded a product photo, said "make me images / photoshoots"
+
+1. **How many?** `[1 / 3 / 5]`
+2. **What style/mood?** `[Clean studio / Lifestyle / Conceptual / With a model / Other]`
+3. **Where will you use them?** `[Shopify / Instagram / Pinterest / Paid ads / Website hero]`
+4. **Brand colors to match?** (skip if a brand kit exists at `.kolbo/brand-kits/<slug>.md`)
+
+### Type B — Uploaded a product photo + named a use case
+
+E.g. "make ads for my product", "make a Pinterest pin", "make a hero banner". Mode is obvious. Ask only the gaps:
+
+1. **How many?** (only if multi-output mode)
+2. **What's the offer / mood / hook?**
+3. **Anything in particular to emphasize?**
+
+### Type C — Text only, no product photo
+
+1. **Can you upload a product photo?** (preferred — much higher fidelity)
+2. **If not, describe the product** — category, packaging, color, distinctive features
+3. **What style?** `[Clean studio / Lifestyle / Conceptual / With a model / Other]`
+4. **Where will you use it?** `[Shopify / Instagram / Pinterest / Paid ads / Website hero]`
+
+### Type D — Uploaded existing image, "redo / change vibe / different version"
+
+→ Mode: `restyle`
+
+1. **What aesthetic?** `[Clean girl / Cottagecore / Quiet luxury / Dark academia / Y2K / Other]`
+2. **Seasonal context?** `[Christmas / Valentine's / Halloween / Black Friday / None]`
+3. **What to preserve, what to change?** (only if ambiguous)
+
+### Type E — Model wearing a product (fashion, accessories)
+
+→ Mode: `virtual_model_tryout`
+
+1. **Model archetype?** (suggest 2–3 based on brand audience — don't open-end)
+2. **Environment?** `[Studio clean / Outdoor natural / Street style / Editorial / Home cozy]`
+3. **Framing?** `[Full body / Three-quarter / Waist up / Closeup on product area]`
+
+### Type F — Vague request, unclear subject
+
+E.g. "make me something cool for my brand".
+
+1. **What product or topic?**
+2. **Goal?** `[Sell on a marketplace / Build awareness / Run paid ads / Update website]`
+3. **Upload a reference image?**
+
+After answers → return to the relevant Type A–E.
+
+## Brand Kit Integration
+
+Before any generation, check if `.kolbo/brand-kits/<slug>.md` exists for the brand:
+
+- **Exists** → Read it. Pull `primary_color`, `accent_color`, `fonts`, `logo_url`. Bake hex codes + named fonts into the prompt. Pass the logo as `reference_images[0]` if relevant.
+- **Doesn't exist** but user gave a brand URL → Run `workflows/research-first.md` first to build one.
+- **Doesn't exist** and user gave no URL → Proceed without; ask in Type A's question 4 if relevant.
+
+## Multi-Variant Strategy
+
+For `count > 1` on a single-output mode (`product_shot`, `lifestyle_scene`, `closeup_product_with_person`, `moodboard_pin`, `hero_banner`, `conceptual_product`):
+
+- Use `num_images: N` on `generate_image` — same prompt, different seeds, fast.
+- Variations come from the model's randomness, not intentional direction.
+
+For `social_carousel` / `ad_creative_pack` (multi-output by design):
+
+- Use `generate_creative_director` with `scene_count: N`.
+- Each scene gets its **own intentional prompt** (different angle / framing / mood / palette) — not paraphrased copies of one scene.
+- Pass the same `visual_dna_ids` and `reference_images` across all scenes to lock product identity.
+
+## Output Discipline
+
+- Call the chosen MCP tool — single command, no preamble.
+- For multi-output: `generate_creative_director` returns N URLs; share them as individual lines (do NOT build an HTML grid artifact — the canvas already shows the gallery).
+- For single-output: one image URL.
+- Log every URL + model + resolution + mode into `.kolbo/production.md` under `### <Mode>` subsection.
+
+## UX Rules
+
+1. **Pick the mode by intent**, not surface keyword. The user saying "Pinterest" → `moodboard_pin` regardless of what's IN the image.
+2. **Ask at most 4 labeled-option questions** before generating. Skip any question whose answer is obvious.
+3. **Always confirm aspect ratio + resolution + count** before firing — they materially change output and cost.
+4. **Reuse brand kits** — Read `.kolbo/brand-kits/<slug>.md` before generating.
+5. **Strict NO uninvited additions** — "NO captions, NO subtitles, NO watermarks, NO extra text beyond what's specified" in every prompt.
+6. **No auto-retry on failure** — surface and let the user adjust.
+
+## Prompt Template Seeds
+
+### `product_shot`
+```
+Clean studio product photograph of @image1 (the product),
+centered on a {neutral white | seamless gradient | catalog beige} background.
+Soft front-fill + subtle rim light, no harsh shadows, no reflections.
+Tack-sharp focus on the product, slight depth-of-field falloff on the background.
+{Brand palette: primary #..., accent #...}
+NO captions, NO watermarks, NO extra text.
+```
+
+### `lifestyle_scene`
+```
+@image1 (the product) in a {real-world scene description},
+natural {time-of-day} light, {natural action involving the product}.
+Photographic, editorial style, {iPhone | 35mm film | medium format} feel.
+{Optional: include hands, partial face — never identifiable people}.
+{Brand palette baked into props/clothing}.
+NO captions, NO watermarks.
+```
+
+### `moodboard_pin`
+```
+Vertical 2:3 Pinterest pin, moodboard aesthetic.
+@image1 (the product) integrated into a {seasonal/aesthetic theme} flatlay or scene.
+{Aesthetic anchor: cottagecore / quiet luxury / Y2K / clean girl / dark academia}.
+Soft natural light, low-saturation editorial palette,
+optional textural overlay (paper, linen, marble).
+Centered hero composition, generous negative space at top for pin overlay.
+NO captions, NO text.
+```
+
+### `restyle`
+```
+@image1 — preserve {subject / composition / camera angle / framing} exactly.
+Change ONLY the {aesthetic / season / mood} to {target aesthetic description}.
+Keep product geometry, label legibility, and identifying details unchanged.
+{Specific change list, e.g.: "swap warm tones for cool blue/silver, add subtle snowflake bokeh,
+shift wood prop to ceramic, keep everything else identical"}.
+```
+
+(More seeds belong here as we learn from real Kolbo generations — append, don't replace.)