@kolbo/mcp 1.75.5 → 1.75.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.75.5",
+  "version": "1.75.7",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@d0d959b, the single source of truth.
+This tree is mirrored from kolbo-code@b950100, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -70,6 +70,8 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
 | Generate with **any other model** (Flux, Kling, Sora, Hailuo, ElevenLabs, DeepDub, …) — also covers universal prompt-engineering basics | `references/models/prompt-copilot.md` |
 | Build a **UGC ad / TV spot / branded video / unboxing / product review / virtual try-on** | `references/workflows/marketing-studio.md` |
+| Make anything look **shot on a phone** — UGC, selfie, candid, "authentic", a product photo that must not look like an ad (image OR video) | `references/workflows/ugc-smartphone.md` |
+| Make a **YouTube / Shorts / Reels thumbnail** or video cover | `references/workflows/thumbnails.md` |
 | Compose a **DTC ad image** (brand kit + ad format + avatar + product + reference media) | `references/workflows/dtc-ads.md` |
 | Generate **brand product imagery** (studio shot, lifestyle, Pinterest pin, hero banner, carousel, ad pack, virtual try-on, conceptual, restyle) | `references/workflows/product-photoshoot.md` |
 | Generate **marketplace listing cards** (Amazon main + secondary + A+ content) | `references/workflows/marketplace-cards.md` |

package/skill/references/models/creative-director.md

@@ -104,3 +104,17 @@ For any ad / story / scene-based video **created from scratch** featuring a Visu
 3. **Animate each frame** with `generate_video_from_image`, passing each approved frame as `image_url`.
 
 Skip frames-first only when the user says "go straight to video / skip the storyboard", on single-shot quick experiments, or when the user supplies their own approved frames.
+
+## UGC sets and thumbnail sets
+
+Two batch shapes come up constantly and both have their own craft file:
+
+- **UGC set** — same creator or product, several angles, all pretending to be one camera
+  roll. Put the phone-look line in EVERY scene worded identically (a look written once at
+  the top drifts by scene 4), vary the angle and the moment rather than the look, and never
+  mix a graded scene into the set. See `workflows/ugc-smartphone.md`.
+- **Thumbnail set** — vary the CONCEPT (bold → minimal → saturated → dark moody →
+  typography-forward), never the words; keep the text to 2–4 quoted words and forbid every
+  other word on the image. See `workflows/thumbnails.md`. Kolbo also ships a dedicated
+  **Thumbnail Generator** tool that runs on Creative Director and fans out 4–8 art-directed
+  variations of one topic — name it when the user just wants options.

package/skill/references/models/gpt-image.md

@@ -19,6 +19,7 @@ Load this file when the user wants a **GPT Image 2 / gpt-image-2** image (OpenAI
 - **Structure + goal**: write prompts in a consistent order — background/scene → subject → key details → constraints → declared intended use (ad / UI mock / infographic / poster / logo / etc.). The "intended use" line sets the mode and polish level.
 - **Format**: prefer skimmable templates over clever syntax. Use short labeled segments or line breaks for complex requests. Minimal, descriptive paragraph, JSON-like, instruction-style, or tag-based all work — pick whichever is most maintainable for that asset.
 - **Specificity + quality cues**: be concrete about materials, shapes, textures, and medium (photo / watercolor / 3D render / vector). Add targeted quality levers only when needed (`film grain`, `textured brushstrokes`, `macro detail`).
+- **Phone-shot / UGC / "authentic" realism**: photorealism triggers are not enough — that look needs deep depth of field, computational-HDR flatness, named available light and deliberate imperfection. Read `workflows/ugc-smartphone.md`.
 - **Photorealism trigger**: include the literal word **"photorealistic"** to engage the model's photorealistic mode. Supporting phrases: "real photograph", "taken on a real camera", "professional photography", "iPhone photo", "35mm film". Camera specs (lens mm, aperture) work for high-level look but are loosely interpreted — use for vibe, not physics.
 - **Composition**: specify framing/viewpoint (close-up, wide, top-down), perspective (eye-level, low-angle), lighting/mood (soft diffuse, golden hour, high-contrast). If layout matters, call out placement ("logo top-right", "subject centered, negative space on left").
 - **People, pose, action**: describe scale, body framing, gaze, object interactions ("full body visible, feet included", "looking down at the open book, not at the camera", "hands naturally gripping the handlebar").

package/skill/references/models/nano-banana.md

@@ -72,6 +72,7 @@ Layer these onto any framework to lift good → breathtaking.
 - **Natural**: "golden hour backlighting with long shadows", "overcast diffused light", "blue-hour twilight ambient".
 
 ### Camera, lens, focus (hardware = visual DNA)
+- **`iPhone` is a vibe word, not a look** — for a real phone-capture image (and for a product photo that must not read as an ad) read `workflows/ugc-smartphone.md` and write the optics/processing/light/imperfection stack.
 - **Hardware vibe**: `GoPro` for distorted action immersion · `Fujifilm` for authentic color science · `disposable camera` for raw nostalgic flash · `Hasselblad medium format` for editorial fashion · `iPhone` for everyday realism · `ARRI ALEXA` for cinematic.
 - **Lens / focus**: "low-angle shot, shallow depth of field f/1.8", "wide-angle for vast scale", "macro for intricate detail", "85mm portrait compression", "anamorphic 2.39:1 bokeh".
 

package/skill/references/models/seedance25.md

@@ -33,7 +33,7 @@ then timecoded `SHOT N — 0:00–0:02 — Medium / camera position` beats. Full
 
 2.5 is where this format earns its keep: 15 shots timed to 30s, ~5k characters, one locked look so every cut matches camera / grade / cast. Do not skip the three blocks. Do not restack GLOBAL LOOK inside shots.
 
-UGC / phone vertical: NEVER write "cinematic". GLOBAL LOOK is phone-native. Use `N connected phone shots, Xs total, 9:16, Multishot ON` and restate `9:16 vertical phone frame` inside every shot.
+UGC / phone vertical (full craft: `workflows/ugc-smartphone.md`): NEVER write "cinematic". GLOBAL LOOK is phone-native. Use `N connected phone shots, Xs total, 9:16, Multishot ON` and restate `9:16 vertical phone frame` inside every shot.
 
 ## Prompt length
 

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

@@ -54,6 +54,15 @@ The mode determines which Kolbo MCP tool to call, what defaults to set, and what
 
 **Pick the actual model** with `list_models({ type: "..." })` and validate caps before firing — see SKILL.md "Resolution / Aspect / Duration — validate against caps".
 
+## The Look Itself — read `workflows/ugc-smartphone.md`
+
+The modes and defaults below decide WHAT gets made. The physics that make it read as a
+real phone capture — deep depth of field, computational HDR, named available light,
+imperfect framing — live in `workflows/ugc-smartphone.md`. Read it before writing any
+UGC prompt: **"smartphone" on its own does not produce a smartphone look**, and that file
+is also where the still-image cases live (a user's product photo re-shot as a customer
+snapshot, the to-camera vs observational subject dial).
+
 ## UGC Family Defaults (CRITICAL)
 
 When ANY `ugc*` mode is selected, snap to these unless the user explicitly overrides:

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

@@ -171,6 +171,9 @@ NO captions, NO watermarks, NO extra text.
 @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.
+<!-- "iPhone feel" is not a look on its own — for a genuine phone-shot / UGC product
+     photo (deep focus, computational HDR, named available light, real clutter, and the
+     rules for keeping label identity intact) read workflows/ugc-smartphone.md. -->
 {Optional: include hands, partial face — never identifiable people}.
 {Brand palette baked into props/clothing}.
 NO captions, NO watermarks.

package/skill/references/workflows/thumbnails.md

@@ -0,0 +1,117 @@
+# Thumbnails — YouTube, Shorts, Reels, TikTok covers
+
+Load this file when the user wants a **thumbnail, video cover, first-frame card, or
+channel art**: "thumbnail for my video", "YouTube cover", "Shorts cover", "make it
+clickable", "higher CTR".
+
+A thumbnail is not a nice image at small size. It is a different craft with a different
+success test: **it is judged at ~200px inside a scrolling feed, next to a hundred others.**
+Everything below follows from that.
+
+---
+
+## The four layers
+
+Every thumbnail that works has exactly these, in this order of importance.
+
+### 1. ONE hero subject — 40–70% of the frame
+
+A face with a big, readable emotion (eyes visible, mouth doing something), or a single
+object caught mid-action. Crop tight — chest-up for a person.
+
+Kill on sight: full-body wide shots, three competing focal points, a floating UI panel, an
+abstract gradient, "a person at a desk". If the concept has no surprise, wit, or
+impossibility in it, it will not stop a scroll — write the concept as one sentence first,
+and if that sentence is boring, invent harder before generating.
+
+### 2. Extreme separation
+
+The subject must pop off the background: a dark field behind a bright subject, or one
+saturated accent against its complement. **Mid-tone on mid-tone is the number-one
+unreadable-thumbnail failure.** Muted, tasteful palettes lose in a feed.
+
+### 3. Text — 2 to 4 words, maximum
+
+- Quote the exact words in the prompt: `render only this text: "STOP DOING THIS"`.
+- Topmost layer, above every element and effect.
+- Roughly **35–45% of the canvas width**. Heavy condensed sans.
+- White or a single accent colour with a **thick dark outline or a solid backing bar** —
+  raw text on a busy image is illegible small.
+- Upper or lower third. **Never across the face.**
+- Forbid everything else explicitly: `no other text, no taglines, no watermark, no logo,
+  no captions, no placeholder text`.
+
+Long strings come back mangled from every image model. If the user wrote a sentence, put
+three words on the image and tell them the rest belongs in the video title. For brand
+names, spell them letter-by-letter in the prompt and raise quality when the type is small.
+
+**Depth trick:** let the subject overlap one word slightly (subject in front of one
+letter). Instant production value.
+
+### 4. Platform-safe composition
+
+| Format | Rules |
+|---|---|
+| **16:9 — YouTube** | Centre-weighted. Nothing critical in the outer 15%: the duration chip sits bottom-right and the red progress bar covers the bottom edge on watched videos. |
+| **9:16 — Shorts / Reels / TikTok** | Every critical element must survive a **centre-square crop** (feeds and grids crop vertical media to its middle). Keep the top ~15% and the bottom ~20% clear of the platform's title, avatar, caption and buttons. |
+| **1:1** | Community posts and square feeds. |
+
+**Verification is a release gate, not a suggestion:** view the render at ~200px, and for
+9:16 crop the centre square first. If the words or the face don't survive, iterate.
+
+---
+
+## Model choice
+
+Text fidelity is the entire constraint. Pick the image model that renders type most
+reliably, and raise the quality setting when the words are small or multi-font. If the
+words come back garbled twice, generate the image **text-free** and tell the user to set
+the type in the Canvas tool — a clean plate plus real type beats a third mangled attempt.
+
+## Routing in Kolbo
+
+| Ask | Tool |
+|---|---|
+| One cover | `generate_image` (a single `text_to_image`) |
+| Several options at once | The in-app **Thumbnail Generator** — topic + style + font + aspect, and it fans out 4–8 art-directed variations in one run (it uses Creative Director underneath) |
+| A batch with a locked character or product | `generate_creative_director` with a Visual DNA attached |
+| Cover for a video the user already made | Never crop a frame out of the video — generate a fresh comp. A film frame is exposed for motion, not for a 200px grid |
+
+## Variation ladder
+
+When producing a set, vary the **concept**, never the words. This is the ladder the in-app
+tool uses, and it is a good default order:
+
+1. Bold dynamic — high contrast, dramatic light, scroll-stopping energy
+2. Clean minimal — one focal point, premium negative space
+3. Vibrant saturated — rich colour, maximum visual impact
+4. Cinematic wide — epic scale, movie-poster feeling
+5. Close-up dramatic — intense subject detail, emotional impact
+6. Typography-forward — the text is the hero, graphic art direction
+7. Dark moody — deep shadows, selective highlights
+8. Flat bright illustration — playful shapes, bold outlines
+
+## Faces
+
+If the channel has a host, lock them with a **character Visual DNA**
+(`workflows/visual-dna.md`) so every thumbnail in the series is the same person. Expression
+is the payload: shock, delight, disbelief, triumph. A neutral face is a wasted thumbnail.
+
+## Phone-shot thumbnails
+
+A "raw / authentic" cover is a real style — a phone-shot frame with big type over it beats
+a polished render for vlog and UGC channels. Build the plate from
+`workflows/ugc-smartphone.md`, then apply the text rules above unchanged. The type stays
+graphic and deliberate even when the photo is deliberately casual.
+
+---
+
+## Checklist
+
+- [ ] One subject, 40–70% of frame, tight crop
+- [ ] Subject separates hard from the background
+- [ ] ≤ 4 words, quoted verbatim, everything else forbidden
+- [ ] Text has an outline or backing bar, sits off the face
+- [ ] Correct aspect, critical content inside the safe area
+- [ ] Checked at 200px (and centre-cropped first, for 9:16)
+- [ ] No watermark, no stray words, no gibberish letters

package/skill/references/workflows/ugc-smartphone.md

@@ -0,0 +1,238 @@
+# UGC / Smartphone Look — Images and Video
+
+Load this file whenever the user asks for anything that should look like a real person's
+phone captured it: "UGC", "shot on my phone", "iPhone photo", "selfie", "candid",
+"authentic", "organic", "TikTok / Reels / Shorts", "creator video", "unboxing", "POV",
+"talking head", or a product photo that "shouldn't look like an ad".
+
+For the *campaign* layer around this — ad modes, hooks, avatars, brand kits — see
+`workflows/marketing-studio.md`. This file is the LOOK: the physics that make a
+generation read as a phone capture instead of a commercial.
+
+---
+
+## The one rule everything else follows
+
+**Writing "smartphone photo" does not produce a smartphone photo.**
+
+Image and video models treat "phone" as a subject label, not a rendering instruction.
+The model has already decided what a good picture looks like — shallow depth of field,
+sculpted key light, clean background, retouched skin — and the word "phone" does not
+overrule any of it. You have to specify the *causes*.
+
+Every UGC prompt states four things. Miss one and it drifts back to a commercial.
+
+### 1. Optics — the biggest tell
+
+> `shot on a phone, 24mm-equivalent wide lens, tiny sensor: DEEP depth of field, the
+> background as sharp as the subject`
+
+Deep focus is the single strongest signal. A creamy blurred background instantly reads
+"produced" — it is physically what a phone cannot do without portrait mode. Add:
+
+- mild wide-angle distortion toward the frame edges
+- close-focus perspective: the nearest hand / nose / product reads slightly large
+- the camera stands where a person stands — chest height, arm's length, or above a table
+
+### 2. Processing — what the phone's chip does after the shutter
+
+> `computational HDR: flat contrast, lifted shadows, highlights held right at clipping,
+> over-sharpened micro-detail, heavy noise reduction with faint luminance noise in the shadows`
+
+This is the "digital" texture people recognise without being able to name. It is the
+opposite of a graded image: nothing is crushed, nothing is filmic, edges are a little
+too crisp.
+
+### 3. Light — available only, and NAMED
+
+Never "natural lighting". Name the actual source:
+
+| Source | What it does |
+|---|---|
+| Window daylight | soft from one side, faint pane shadows, cool |
+| One ceiling bulb | top-down, warm, shadowed eye sockets |
+| Phone / laptop screen glow | up-lit face, cool cast, dark room |
+| Supermarket / office fluorescents | flat, green-ish, no modelling |
+| Direct on-camera flash at night | hard shadow thrown on the wall behind, hot falloff, dark background |
+
+**Mixed white balance in one frame is the strongest realism cue that exists** — warm bulb
+inside plus cool daylight through a window, and the model stops rendering a studio.
+
+### 4. Imperfection — the part everyone skips
+
+- framing slightly off-centre, a few degrees of tilt, head near the top edge or lightly cropped
+- caught mid-gesture or mid-blink, not on a posed peak
+- faint motion blur on a moving hand
+- visible pores, flyaway hair, creased clothing, chapped lips — no beauty retouching
+- **a real cluttered background**: cables, a mug, an unmade bed corner, a full dish rack.
+  Empty minimal sets are the AI default and the giveaway.
+
+---
+
+## The subject dial — ask once, then state it
+
+Users often want the subject facing camera. **Often — not always.** Decide it explicitly
+and write it into the prompt:
+
+- **TO-CAMERA** — arm's-length selfie geometry, direct eye contact, talking to the viewer
+  like a friend. Default for a talking head, review, testimonial, or hook.
+- **OBSERVATIONAL** — candid, subject unaware, filmed by someone standing where a person
+  would stand. Default for lifestyle, product-in-use, and "day in the life".
+
+Do not silently assume to-camera for every UGC ask; an observational frame is what makes a
+product shot feel found rather than staged.
+
+---
+
+## Product + UGC (the most common image case)
+
+The user uploads a product and wants a photo a customer could have taken.
+
+**Route first:**
+
+| What they want | Tool |
+|---|---|
+| The SAME uploaded photo re-rendered as a phone shot | `generate_image_edit` (`image_editing`) |
+| The product in a NEW scene — a hand, a counter, a gym bag | `generate_image` with the product image as a reference |
+
+**Then four hard rules:**
+
+1. **Identity is not creative latitude.** `keep the label artwork, typography, colours,
+   proportions and closure exactly as in the reference — do not redesign, re-letter or
+   re-colour the packaging`. Models rewrite label text unless forbidden. If the label
+   carries words, quote them verbatim in the prompt.
+2. **Relight it into the room.** A studio pack-shot dropped into a kitchen is the classic
+   fake. Demand: the same light direction and colour temperature as the scene, a contact
+   shadow where it meets the surface, the room reflected in glossy or laminated faces, a
+   matching noise level, and no leftover white-cyclorama edge glow.
+3. **Human scale.** A real hand holding or using it — unmanicured nails, natural grip,
+   slight motion blur — or set down mid-use (open, half-full, cap beside it). Never
+   centred like a catalogue.
+4. **One product per frame**, label toward camera at least once.
+
+For recurring products, make a **product Visual DNA** (`workflows/visual-dna.md`) so the
+identity survives every generation instead of being re-described each time.
+
+---
+
+## Video
+
+Everything above still applies. On top of it:
+
+- **The word "cinematic" is banned** — not in the header, not in GLOBAL LOOK, not in a
+  shot. It is the single line that turns a phone video back into a commercial.
+- **Frame:** `9:16 vertical phone frame`, restated **inside every shot**. Forbid letterbox,
+  pillarbox and 16:9 inserts — multishot models silently flip a later shot to widescreen
+  when the prompt reads filmic.
+- **Single shot vs multi-shot** — ask, don't assume:
+  - *Single* (default): `single unbroken take, no cuts`. One continuous handheld take is
+    what most UGC actually is.
+  - *Multi*: `N connected phone shots, Xs total, 9:16, Multishot ON`. Every shot must be an
+    angle one person with one phone could actually have grabbed — never crew coverage.
+    Vary the angle and the moment (selfie arm → held out at the product → set down on the
+    counter → mid-use), never the look.
+- **Camera:** the phone is in a hand. Slight sway with constant micro-corrections,
+  reframing a beat late, selfie-arm at arm's length, or propped on a surface. NEVER dolly,
+  crane, gimbal glide, orbit, crash zoom, or a locked tripod master.
+- **Product:** it is HANDLED, not displayed — picked up, opened, used, label turned to the
+  lens at least once, and locked identical across every shot.
+- **Audio:** room tone and the phone's own mic. No score, no SFX layer, no burned-in
+  captions or subtitles unless the user explicitly asked (they add those in CapCut, and
+  baked-in captions kill reuse).
+
+Seedance's phone-vertical exception in `references/models/seedance25.md` is the same rule
+from the model's side — read it before compiling a multi-shot UGC prompt.
+
+---
+
+## The negative list (append it every time)
+
+```
+no cinematic colour grade, no teal-and-orange, no shallow depth of field or bokeh,
+no anamorphic flare, no studio softbox or rim light, no beauty retouching or skin
+smoothing, no film-grain overlay, no perfect symmetry, no watermark, no added text
+```
+
+## Aspect
+
+9:16 for social and Stories. 4:3 / 3:4 for a camera-roll photo. Widescreen only if asked.
+
+## Optional era dials (only when the user wants that vibe)
+
+Direct-flash night party · disposable camera with a burned-in date stamp · front-camera
+selfie with the arm in frame · screenshot of a video call · mirror selfie with the phone
+visible · early-2010s low-light grain.
+
+---
+
+## Parity with the Kolbo app
+
+The web app ships this look as a **Smartphone** cinematic preset, and its wording is the
+house baseline — match it so a prompt written here and a preset clicked in the UI produce
+the same picture:
+
+- **Camera — Smartphone:** *the everyday look of a phone snapshot, deep depth of field with
+  foreground and background both sharp, flat computational-HDR contrast, slightly
+  oversharpened detail, candid realism*
+- **Focal length:** 24mm · **Lighting:** Window Light · **Colour:** Naturalistic Clean
+
+`list_cinematic_presets` returns the live catalog. Related in-app looks worth knowing:
+**Camcorder Tape** (2000s home video), **Reality Show**, **Mockumentary**, and the
+**Handheld** movesets for video.
+
+---
+
+## Copy-ready seeds
+
+**Phone still (person):**
+```
+Candid phone snapshot of {subject} in {real, specific room}, {mid-action}.
+Shot on a phone, 24mm wide, tiny sensor — deep depth of field, background as sharp as
+the subject. Computational HDR: flat contrast, lifted shadows, highlights at clipping,
+over-sharpened detail, faint shadow noise. Lit only by {named source}; {second source}
+mixes a different colour temperature into the frame. Framing slightly off-centre with a
+few degrees of tilt, caught mid-gesture. Visible skin texture and flyaway hair, creased
+clothing, real clutter in the background ({two specific objects}).
+9:16 vertical.
+no cinematic grade, no bokeh, no rim light, no retouching, no watermark, no text
+```
+
+**Product in a real kitchen (new scene, product image as reference):**
+```
+{Product from the reference} held in a real hand over a kitchen counter, mid-use, cap
+beside it. Keep the label artwork, typography, colours and proportions exactly as in the
+reference — do not redesign or re-letter the packaging.
+Shot on a phone, 24mm wide, deep depth of field. Computational HDR, flat contrast,
+over-sharpened detail. Lit by window daylight from the left with a warm ceiling bulb
+mixing in. The product is relit by the room: matching light direction and colour, a
+contact shadow where it meets the counter, the window reflected in its glossy face,
+the same noise level as the rest of the frame.
+Unmanicured nails, natural grip, slight motion blur. Crumbs and a mug in the background.
+4:3.
+no studio background, no rim light, no bokeh, no retouching, no added text
+```
+
+**Single-shot UGC video:**
+```
+Single unbroken take, no cuts, 9:16 vertical phone frame.
+{Presenter or @dna} in {everyday room}, TO-CAMERA, talking to the viewer like a friend
+while {natural action with the product}. Phone held at arm's length with slight sway and
+constant micro-corrections; the frame reframes a beat late.
+Available light only: {named source}. Deep focus, flat computational-HDR contrast,
+over-sharpened detail.
+Audio: room tone and the phone's own mic. No music, no SFX, no captions.
+```
+
+---
+
+## QC — look for these before you ship
+
+| Symptom | Cause |
+|---|---|
+| Background is blurred | you didn't demand deep depth of field |
+| Reads as an ad | the word "cinematic" survived, or a rim/key light is in the prompt |
+| Product looks pasted in | you didn't relight it into the scene |
+| Label text is wrong | you didn't forbid redesigning it / didn't quote the words |
+| Face is plastic | no pores/asymmetry/flyaway hair line, or retouching wasn't forbidden |
+| Set is empty and clean | you didn't name real clutter |
+| A later video shot went widescreen | 9:16 wasn't restated inside every shot |

package/src/apps/widgets/generation.js

@@ -133,9 +133,18 @@ function boot(sc) {
   makeExpandable(el('prompt'));
   renderChips(sc);
   el('credits').textContent = sc.credits_used != null ? fmtCredits(sc.credits_used) : '';
-  if (sc.phase === 'generating') renderGenerating(sc);
-  else if (sc.phase === 'failed') renderError(sc.error || 'Generation failed');
-  else renderResult(sc);
+  // Every legitimate completed payload sets phase:'completed' explicitly
+  // (uiCompleted, completedFromPlain, the visual_dna character-sheet path) —
+  // there is no real case where "no media yet" should render as a result.
+  // A host that sends some OTHER phase string here (e.g. a host-side
+  // pre-flight envelope built before the tool call even ran) used to fall
+  // through straight to renderResult with no urls/scenes, rendering as a
+  // broken/empty "completed" card — indistinguishable from a real failure —
+  // for however long that phase lingered. Default anything unrecognized to
+  // "still working" instead of assuming it's done.
+  if (sc.phase === 'failed') renderError(sc.error || 'Generation failed');
+  else if (sc.phase === 'completed') renderResult(sc);
+  else renderGenerating(sc);
   window.kolbo.notifySize();
 }