@kolbo/kolbo-code-linux-arm64-musl 2.2.5 → 2.3.0

package/skills/kolbo/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/skills/kolbo/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.)

package/skills/kolbo/references/workflows/production-log.md

@@ -0,0 +1,155 @@
+# Production Log — `.kolbo/production.md`
+
+Load this file when starting a multi-step production, or before any continuation of prior media work ("edit", "redo", "the same character", `@name` references, "scene N").
+
+## Why It Exists
+
+Every URL, id, and brief produced by a Kolbo MCP tool MUST be recorded in `.kolbo/production.md` in the user's workspace. This file — not chat history — is your source of truth for prior artifacts: URLs scattered across `tool_result` blobs are unreliable to re-scan and disappear entirely on context compaction.
+
+## When to READ it
+
+Read `.kolbo/production.md` **before** acting on any of these signals:
+- "edit", "animate", "combine", "redo", "polish", "fix", "regenerate"
+- "the same character / scene / image / video / sound", "that X", "scene N", "the rainy one", etc.
+- `@name` references for Visual DNA
+- Any continuation of prior media work ("now make scene 3")
+
+If the file is missing and the user is referencing prior media, ask the user — do not guess from chat.
+
+## When to WRITE to it
+
+**Immediately after every successful generation tool call**, before your next tool call or your final reply. The runtime will inject a reminder after generation tool results — treat that as a hard rule, not a suggestion.
+
+Tools that REQUIRE logging:
+- `generate_image`, `generate_image_edit`, `edit_image`
+- `generate_video`, `generate_video_from_image`, `generate_video_from_video`, `edit_video`
+- `generate_elements`, `generate_first_last_frame`, `generate_lipsync`
+- `generate_music`, `generate_sound`, `generate_speech`
+- `generate_3d`, `generate_creative_director`
+- `create_visual_dna`, `upload_media`
+
+Tools that do NOT log: `list_*`, `get_*`, `check_credits`, `chat_*`, `transcribe_audio` (read-only / discovery).
+
+## File creation — pick the right tool to avoid the "must Read first" error
+
+`Edit` refuses to overwrite a file unless you've `Read` it first in the same session. Pick by file state:
+
+| State | Tool |
+|---|---|
+| File **does not exist** (typical first turn) | `Write` with the full stub below |
+| File **exists** | `Read` first, then `Edit` |
+| Not sure | `Read` first; on ENOENT, fall back to `Write` |
+
+Stub for first creation:
+
+```md
+<!-- .kolbo/production.md — agent-managed media artifact registry.
+     User may hand-edit; agent must Read-before-Edit to reconcile. -->
+
+# Production Log
+
+## 🎯 Now
+
+**Brief:** <paraphrase of user's overall goal in 1-3 sentences>
+**Now working on:** <the immediate next step>
+**Last updated:** <ISO date>
+
+---
+
+## Production: <name from user's request, slugified human label>
+
+### Cast
+### Visual DNA
+### Scenes
+### Audio
+### Final
+```
+
+Subsections (`### Cast` etc.) are **suggested defaults**, not required. Adapt: a logo set has `### Logos`, an album has `### Tracks`, a 3D render has `### Models`. Leave empty subsections out of the file when you create entries.
+
+## Entry shape
+
+One bullet per artifact. Write the label **the way the user would reference it next time** ("the rainy one"), not the model's raw output.
+
+```md
+### Cast
+- **Maya** — female, 30, urban photographer, leather jacket
+  - portrait: https://...characters/maya.png  (nano-banana-2, 2026-05-13)
+  - visual DNA: vdna_8f2c  (@maya)
+
+### Scenes
+1. **Coffee shop morning** — Maya at counter, soft light, wide shot
+   - still: https://...scenes/01-coffee.png  (flux-2-pro, 2026-05-13)
+   - video: (pending)
+2. **Rainy street walk** — neon reflections, slow dolly
+   - still: https://...scenes/02-rain.png  (flux-2-pro, 2026-05-13)
+   - video: https://...videos/02-rain.mp4  (kling-2, 2026-05-13)
+```
+
+## Header rewrite rule (Manus pattern — IMPORTANT)
+
+The `## 🎯 Now` block at the top of the file is **rewritten every turn** to keep the brief + current step near the model's recency window. Body sections (everything below the first `---`) are **append-only**.
+
+When a user request supersedes a previous artifact (e.g., "redo scene 2 with more rain"), do not delete the old entry. Mark it `(superseded YYYY-MM-DD)` and place the new entry beneath:
+
+```md
+2. **Rainy street walk** — neon reflections, slow dolly
+   - still: https://...scenes/02-rain.png (superseded 2026-05-13)
+   - still: https://...scenes/02-rain-v2.png  (flux-2-pro, 2026-05-13)
+   - video: https://...videos/02-rain-v2.mp4  (kling-2, 2026-05-13)
+```
+
+## Rules
+
+1. **First touch `Write`, subsequent touches `Read` → `Edit`** (see "File creation" above). If `Edit` fails on exact-match, `Read` again — the user may have hand-edited.
+2. **Plain English labels** — write what the user would call it.
+3. **Append-only body.** Only the `## 🎯 Now` header is rewritten. Never delete artifact entries; mark them `(superseded)` instead.
+4. **Do not log failures.** Only successful generations.
+5. **Resolve user references via the log, not chat history.** If the user says "scene 3," use the URL the log says is scene 3, even if a later tool_result mentioned a different URL.
+6. **One file per workspace.** Multiple concurrent productions go under separate `## Production: <name>` headings inside the same file.
+
+## Bulk Generation Entry Shape
+
+For batch runs (50-item UGC sets, etc.), persist every `generation_id` (even for failures) — required for `get_generation_status` recovery and cross-session dedupe.
+
+```md
+12. ✅ Asian F 24, bedroom, hype POV
+    - generation_id: gen_8a2c…
+    - url: https://…
+    - model: seedance-2 · 720p · 10s · sound-on
+    - generated: 2026-05-14T07:42Z
+13. ❌ Latino M 31, gym
+    - generation_id: gen_ff19…
+    - error: 429 Too many generation requests
+    - retry_after: 2026-05-14T07:43Z
+```
+
+## Always log the resolution / duration / sound choices
+
+Production-log entries should include the resolution and (for video) duration + sound state alongside the URL, so the user can see what they paid for:
+
+```md
+- still: https://...01-coffee.png  (flux-2-pro · 1K, 2026-05-14)
+- video: https://...02-rain.mp4   (kling-2 · 1080p · 5s · sound-off, 2026-05-14)
+```
+
+## Production Log vs TodoWrite
+
+Use both — different jobs:
+
+| | `.kolbo/production.md` | `TodoWrite` |
+|---|---|---|
+| Purpose | Durable artifact registry | Ephemeral step plan |
+| Lifetime | Persists across sessions / compaction | Per turn / per request |
+| Content | URLs, ids, briefs | "Do X, then Y, then Z" |
+| Example | `still: https://...01-coffee.png` | `Generate visual DNA for Maya` |
+
+## Real Cost Quoting
+
+Every generation now returns `credits_used` (multiplier-adjusted total) and `credits_breakdown` (per-model attribution). **Log `credits_used` to `.kolbo/production.md`, not `base × count`.**
+
+```json
+{ "credits_used": 12, "credits_breakdown": [{ "model": "nano-banana-2", "base": 8, "final": 12, ... }], "urls": [...] }
+```
+
+When the user asks "how much did I spend?" → call `get_session_usage` for the real, multiplier-adjusted session total + per-tool + per-model breakdowns (same numbers as the desktop bottom-bar counter).

package/skills/kolbo/references/workflows/research-first.md

@@ -0,0 +1,174 @@
+# Research-First Creative — Scrape Before Generating
+
+Load this file when the brief involves a real brand, product URL, audience, or market — especially for ads, marketing creative, or anything tied to identity / brand palette / on-image text.
+
+## Why
+
+When the user gives you a **product URL, brand reference, or "make X for Y audience" brief**, don't jump straight to prompts. Spend one turn researching first — the cost of a single research turn is far less than 10 mis-aimed generations.
+
+## When to do research-first
+
+- Any URL appears in the brief (product page, landing page, brand site)
+- The brief names a brand, product, or company you don't already have context on
+- The brief targets a specific audience / language / market with conventions you should respect (Hebrew/Israeli, Japanese, Gen-Z TikTok, B2B SaaS, luxury, etc.)
+- The brief explicitly says "research" / "תחקור" / "look up" / "find examples" / "check best practices"
+
+## How to research (parallel calls in one response)
+
+Fire these IN PARALLEL — they're independent reads:
+
+1. **`WebSearch`** for prompt-engineering patterns specific to the chosen model. **The model name in the search query MUST be the literal model the user named** — never substitute a generic / default / "popular" model. If the user said "nano banana 2", search for `"nano banana 2" prompt …`, NOT `"flux" prompt …` or `"midjourney" prompt …`. The same HARD RULE that applies to *calling* the named model applies to *researching* it. Examples (replace `<model>` with the user's exact wording):
+   - `"<model>" prompt engineering ad image text rendering`
+   - `"<model>" hex color font specification advertising prompt`
+   - `"<model>" hebrew text RTL rendering` (or any user-named language)
+2. **`WebSearch`** for the audience / market design conventions:
+   - `<audience> advertising design trends <year>`
+   - `<language> typography <use case> RTL/LTR best practices`
+3. **`WebFetch`** the product URL with a precise extraction prompt (see below).
+4. (Optional) `WebSearch` for competitor / reference visuals to set bar.
+
+## Extracting the product page (WebFetch prompt template)
+
+Don't ask WebFetch a vague "what is this page" — ask for structured extraction:
+
+```
+Extract from this page, in compact bullets:
+1. Product name + one-line value proposition.
+2. 3–5 concrete capabilities/benefits (user-facing language).
+3. All product hero / screenshot image URLs visible in the page.
+4. Brand color hex codes — pull from inline `style=`, `<style>` tags, or
+   linked CSS, ignoring generic UI defaults (#fff/#000). Identify which
+   color plays which role (primary CTA, headline text, background, accent).
+5. Brand voice signals (tone, target user, formality).
+6. Any explicit fonts named in CSS or visible.
+```
+
+## Re-host every external image via `upload_media`
+
+The bulk-API rule applies: external URLs in `reference_images` / `source_images` / `image_url` cause **400 Bad Request**. Pipeline:
+
+1. `Bash: curl -fsSL "<external-url>" -o /tmp/<name>.<ext>` (or use WebFetch where it returns the binary)
+2. `mcp__kolbo__upload_media` with the local file → returns Kolbo CDN URL
+3. Use the returned CDN URL in any subsequent generation call
+4. Log both URLs in the production log (so the user can trace provenance)
+
+## Synthesizing the research
+
+In the production log create:
+```md
+### Research notes
+- Prompt patterns for <model>: …
+- Audience conventions: …
+
+### Product brief
+- Name: …
+- Value prop: …
+- Capabilities: …, …, …
+
+### Brand palette
+- primary: #...
+- accent: #...
+- text: #...
+- bg: #...
+
+### Re-hosted assets
+- hero_1: <kolbo CDN url>  (from <original url>)
+```
+
+## Persist as a Reusable Brand Kit
+
+After research, **persist the brand-identity bits into a reusable file** at `.kolbo/brand-kits/<slug>.md` so future generations in any session can read it instead of re-scraping. This is the durable, cross-session record (the production log is per-production; brand kits are per-brand).
+
+**Slug rule:** lowercase, single token, derived from the domain (`drinkolipop` from `drinkolipop.com`, `acme_skincare` from `acme-skincare.io`). Strip TLD and hyphens.
+
+**Brand kit file schema** (use `Write` for first creation; `Read → Edit` for updates):
+
+```md
+<!-- .kolbo/brand-kits/<slug>.md — agent-managed brand identity registry.
+     Reusable across all generations for this brand. Read first before scraping. -->
+
+# Brand Kit: <Brand Name>
+
+url: https://...
+fetched: 2026-05-23
+last_refreshed: 2026-05-23
+
+## Identity
+brand_name: ...
+tagline: ...
+business_overview: <1-2 sentences>
+industry: <fashion | beauty | food | beverage | electronics | saas | ...>
+
+## Visuals
+logo_url: <kolbo CDN url, re-hosted via upload_media>
+primary_color: #...
+accent_color: #...
+text_color: #...
+bg_color: #...
+fonts:
+  headline: <font name>
+  body: <font name>
+  mono: <font name, optional>
+
+## Voice & Audience
+tone: <playful | refined | technical | bold | warm | ...>
+target_user: <one-line persona>
+formality: <casual | professional | luxury>
+
+## Hero Assets (re-hosted via upload_media)
+- hero_1: <kolbo CDN url>  (from <original url>)
+- hero_2: <kolbo CDN url>  (from <original url>)
+- product_1: <kolbo CDN url>  (from <original url>)
+
+## Notes
+- Any brand-specific gotchas, design rules, do-not-show items
+```
+
+### When to READ a brand kit
+
+Before any generation tied to a known brand — **always** Read first:
+
+- User mentions a brand by name ("make a Pinterest pin for OliPop")
+- User pastes a brand URL again ("make ads for drinkolipop.com")
+- User says "use the same brand as last time" / "match our brand"
+- Any DTC ad / product photoshoot / marketplace card request where the brand is implicit
+
+If `.kolbo/brand-kits/<slug>.md` exists, **skip the research-first workflow entirely** for the brand-extraction parts (palette, logo, fonts, voice). Still do `WebSearch` for fresh prompt-engineering patterns or audience trends if needed.
+
+If it doesn't exist and there's a URL, run the full research workflow above and **end by persisting the brand kit**.
+
+### When to UPDATE a brand kit
+
+- User explicitly says "the brand updated their colors / logo / fonts"
+- Brand kit is >90 days old AND the user is starting a major campaign (refresh recommended, not mandatory)
+- Generation results look "off-brand" and palette is suspect — refresh to verify
+
+Update by `Read → Edit`. Bump `last_refreshed`. Keep older asset URLs in place (they still work) and append new ones.
+
+### Brand-kit reuse downstream
+
+The other workflow files consume the brand kit:
+
+- `workflows/dtc-ads.md` — pulls palette + fonts + logo into every ad prompt
+- `workflows/product-photoshoot.md` — bakes hex codes into prompts; uses logo as `reference_images[0]`
+- `workflows/marketplace-cards.md` — palette + fonts critical for A+ module consistency
+- `workflows/marketing-studio.md` — voice/tone shapes UGC presenter dialogue; palette shapes any branded overlays
+
+Always cite the brand-kit slug in the production log so reviewers can trace which kit drove a given generation.
+
+## Building prompts informed by the research
+
+When generating ad / marketing creative based on this research:
+
+- **Exact hex codes for every color** — `#FF4D2E` not "orange". Match brand palette.
+- **On-image text in literal double quotes** — `"שלום עולם"` not `Hebrew greeting`. Specify language and direction (RTL/LTR) when non-English.
+- **Per text element**: position, font weight, point size, color hex, alignment.
+- **Forbid uninvited additions** — explicitly tell the model: NO captions, NO subtitles, NO watermarks, NO extra text beyond what's specified. Same rule as UGC defaults.
+- **Use research findings to shape composition** — e.g. if research said "Israeli social ads favor bold contrast and minimal copy", reflect that.
+- Always **approve the concept + sample prompts with the user** before firing the full batch when the batch is ≥4 ads or the user said "approve first".
+
+## Skipping research is OK when…
+
+- User gave no URL, no brand, no audience-specific signal — pure creative ("make a sunset")
+- User said "skip research" / "just generate" / "I have the prompt ready"
+- The brief is for a single quick draft