@kolbo/mcp 1.112.1 → 1.112.2

package/skill/references/workflows/micro-drama/edit-deliver.md

@@ -0,0 +1,99 @@
+# Micro-drama — edit and delivery
+
+The edit is half the film. Build one **tight cut** per episode from the finals (or from Drafts first, then finalize only what the cut uses), get the user's approval, then make the deliverables from it: the platform episode, social cutdowns, the series trailer (after Episode 1) and key art.
+
+## Inputs
+
+- The episode's final clips, in script order.
+- Word timings (if `transcribe_audio` is still processing after a few minutes, outside agents may use a local Whisper for QA and the rough cut, then swap in Kolbo's timings for the final captions): `transcribe_audio` on each clip (or on a quick join) with `generate_srt: true, words_per_line: 1, lines_per_subtitle: 1`; download the word-by-word SRT. Correct mishears against the script's words (keep the timings, replace only the text), and delete any word the script does not have: transcribers invent repeats over quiet stretches (a second "That's me." appeared over silent room tone, one word with zero length).
+- The shot map: every shot's start/end, who is frame-left/right, where each person looks (`shot_map.py`, or one frame per shot in Kobi).
+
+## Cut rules (every one is a QA check)
+
+1. **Cut only at shot changes**, landing on a line end, a look or an action. Trim shot heads and tails, not middles.
+2. **No slivers.** A kept shot is ≥1.5 s or it is dropped whole.
+3. **Exact frames.** In/out points stay 1.5 frames inside a shot change, so no frame of the neighbour flashes in.
+4. **Never cut inside an action.** End before a gesture starts or after it completes (check frames around every out-point).
+5. **No same-angle jump.** If two pieces of the same angle would touch with a position change, put a reaction shot of the other character between them (≥1.5 s, reused footage is fine).
+6. **180-degree line.** Each character keeps their side and looks toward the other across the cut. Mirror a breaking shot only when no one-sided detail of anyone in frame is visible (check the bible's Asymmetry line: scar, parting, ring, watch, text) and the neighbours' gaze still agrees after the flip. Otherwise use a cutaway.
+7. **L-cuts on dialogue.** Where the next shot answers a line, its picture comes in 0.2-0.55 s early over the end of the line; the line finishes underneath. No word may fall in dropped audio.
+8. **Silence is judged, not measured.** Keep 0.4-1.3 s pauses where something happens (a look, a gesture, the beat before a key line). Cut stares that re-establish nothing and exits after the line is done.
+9. **Punch-in only for a dead middle** inside one shot: cut the dead stretch, punch in 1.5x on the rest, framed on the face.
+10. **Sound seams:** about 0.3 s crossfade at every seam so room tone never jumps. Never normalize or re-level Seedance's audio.
+11. **Keep the bones:** the hook frame, every script line, and the last line with its hold.
+
+Edit QA = all eleven, plus: no flash frames, every script line once and in order (transcribe the cut), screen direction consistent, no silence over 1.5 s without a judged beat.
+
+## Kobi: build it in the Kolbo Video Editor
+
+Read `video-editor.md` and `get_video_editor_schema` first. One session per episode, in the series project, format from the kickoff.
+
+- **Picture:** one `video` item per kept piece on a mixed track, laid end to end (`reorder_items`). `trimStart` / `trimEnd` are milliseconds removed from the clip's head and tail. Punch-in = item `scale` + `position` (anchored on the face). Mirror = `flipX`.
+- **L-cuts and seams:** mute the video items and put each piece's sound as an `audio` item (same clip URL, its own trims) on an audio track; extend a line's audio item under the next picture for an L-cut, and give every seam a short `audioEffects` fade in/out. Never change `volume` or `gain` to "even out" levels.
+- **Captions (social cutdowns):** a caption track with `caption` items built from the corrected word timings (absolute timeline ms), `captionStyle.preset: "highlight"`, max 3 words per item, the spoken word in a contrasting colour, sitting just above the bottom 35% of the frame and inside the centre 82% width.
+- **Hook (social cutdowns):** a `text` item for exactly 0-3 s, two short lines, large (about 6-7% of frame width), `backgroundEnabled` with a white background, `backgroundRadius` for rounded corners and generous `backgroundPadding`, black bold text, at waist height right above the captions, never over a face.
+- Read the saved session back, then `export_video_editor_session` only when the user wants the rendered file. Inspect the export (frames + a transcript) before calling it done; renderer support differs for some effects.
+
+## Outside agents: local scripts
+
+`scripts/micro-drama/` (Python 3, numpy, ffmpeg on PATH; run from that folder):
+
+| Step | Command |
+|---|---|
+| Shot map | `python shot_map.py <clip-or-join.mp4> <out_dir>` → `shots.json` + a first/mid/last strip per shot; look at every strip |
+| Pace candidates | `python pace_report.py <join.mp4> <words.srt> pace.json` → dead-air candidates to judge |
+| Build the cut | `python cut.py cut.json` (segments with start/end, `lcut`, `jcut`, `zoom`, `y`, `flip`; snaps to real frames, crossfades seams, never re-levels) |
+| Flash check | `python flash_check.py <tight.mp4>` → must report 0 problems |
+| Platform episode | `python burn.py film <tight.mp4> <words-tight.srt> <ep.mp4>` (plain subtitles, max 4 words per row, 2 rows) or ship the clean master |
+| Social cutdown | `python burn.py social <short.mp4> <words-short.srt> <short-subbed.mp4> --hook "Line one|Line two"` |
+
+Burn at the delivery resolution: if the cut is upscaled, burn captions and hook after the upscale on the clean cut, never upscale burned text.
+
+Re-transcribe the tight cut (and each short) before burning; word timings change after cutting. If the user wants to keep editing in the app, also build the Video Editor session.
+
+## Two products from one tight cut
+
+- **Platform episode** (the full episode page / series feed): the clean tight cut, plain film subtitles, no hook, no word-pop captions.
+- **Social cutdowns** (built from whole shots of the tight cut, each with its own hook, captions and cover frame):
+  - **D - line-open (post first):** start about 0.4 s before the most confrontational line and play on; the hook sets the situation, never repeats the line.
+  - **A - full:** the whole episode with the main hook.
+  - **B - cold-open:** the last line or the cliff (3-5 s) first, then the full episode.
+  - **C - teaser:** 20-30 s of the 2-3 strongest beats, ending on the cliff.
+  - The first frame of every short is a lead in a medium shot, facing camera-ish, eyes open; never a back or an empty room under the hook.
+  - Cover = the best still of that short (tension + the lead + tells the story), a different frame per short, nothing burned in. Save it as `<short>-cover.jpg` for the platform's cover upload.
+- Post caption: episode number, a tease of the next one, the call to action (e.g. "Full episode at the link in bio"). No URL or end card in the video.
+
+## Series trailer (right after Episode 1 is approved)
+
+20-25 s, its own identity from the bible's World + look. Release unit = trailer + Episode 1.
+
+| Section | Length | Content |
+|---|---|---|
+| Hook exchange | ~3 s | the episode's opening exchange, a face with eyes open on frame 1 |
+| Card 1 | 1.4 s | the premise statement ("EVERYTHING / WAS PERFECT.") |
+| World beat | ~1.6 s | the series' signature moment with its object sound |
+| Card 2 | 1.4 s | the crack ("EXCEPT THE / AFTERNOONS.") |
+| Temptation line | ~1.6 s | ONE line that turns the story |
+| Montage | 1.7-2.6 s | unused motion from the episode, alternating characters, each cut shorter |
+| Button exchange | ~4.4 s | the episode's last exchange, in the score's quiet part |
+| Title | ~2.25 s | the series title card on the score's big hit |
+| End card | ~3 s | the creator's / brand's sign-off on the stinger |
+
+- **Title and card lettering:** `nano-banana-pro` (or `gpt-image-2.5-*` with `font_ids` for a brand font), 16:9, "title lettering only, on pure flat black, exactly N centered lines: <text>, <lettering and material from the world>, each word exactly once, nothing else". Check spelling and stray punctuation, then key out the black.
+- **Card background:** a short moving motif from the world, no people, no text (a Veo or Seedance clip, sound off).
+- **Score:** `generate_music` with a structured plan: restrained intro under dialogue → build → one big hit on the first beat (title) → hush (button) → final stinger. Measure where the hit and the stinger really land before cutting; generated scores rarely follow plan timings.
+- **SFX:** one world-native object sound plus one tension sound under the button (`generate_sound`).
+- Cards and title never repeat a spoken line. Dialogue sits above the score; check it on a phone speaker.
+- Kobi assembles it in the Video Editor (picture track, text/image cards, music and SFX tracks); outside agents can use the editor or ffmpeg.
+
+## Key art
+
+- **Poster (3:4) and covers:** `gpt-image-2.5-sunburst` with every character's Visual DNA tagged in the prompt and all typography in the same generation (series title in its lettering, tagline). Name the title exactly or the model swaps it. Leads face the camera, figure in frame, eyes open.
+- **Banners / headers:** generate at the model's widest ratio with the poster as a source image, then fit the platform size with `edit_image` reframe / zoom-out. Never assemble key art in code; code may only crop or resize a finished image.
+- QA: faces match the sheets, every word spelled right, characters clearly adult, no real-person likeness.
+
+## Delivery report (to the user)
+
+Files with links, credits spent against the cap, QA results per gate, known compromises, and what needs their decision. Publishing is the user's action.
+
+Upload finished files into the series project. `upload_media` rejects large files (HTTP 413 on a 257 MB 4K minute); for those, outside agents call `create_upload_ticket` and POST the file with curl (`-F "file=@<path>;type=video/mp4" -F "project_id=<id>"`); retry a 502 after a few seconds (large uploads often succeed on the second try). Deliver at a sane bitrate (about 35 Mbit/s for 4K, 12 Mbit/s for 1080p); platforms recompress anything higher.

package/skill/references/workflows/micro-drama/render-qa.md

@@ -0,0 +1,55 @@
+# Micro-drama — Draft renders, QA, finals
+
+Every part is blocked in **Seedance 2.5 Draft** (`draft: true`; see `models/seedance25.md`). Only parts the user keeps are finalized, at the resolution chosen at kickoff. Never regenerate a kept Draft to "upgrade" it.
+
+## Estimate before the season (and before each episode)
+
+Read live rates from `list_models` (Seedance 2.5 bills per output second; Draft is about 0.44x the 720p rate). Estimate:
+
+```
+episode Draft  = sum(part seconds) x Draft rate x 1.3   (1.3 = typical fix-shot overhead)
+episode final  = kept seconds x finalization rate at the chosen resolution (from edit_video draft_quote)
+assets         = sheets + looks + locations + voices (once per series; looks per season)
+```
+
+Show the totals against the cap. If the season does not fit, cut episodes or parts, never pace inside a part.
+
+Reference run (2026-10-07, "Wrong Number" Ep1): a 60 s episode = 4 parts x 15 s Draft = 1,020 credits, plus about 55 credits of cast, locations and voices (Midjourney looks, Seedream Flash sheets, Seed Audio voices). The cut came to 58.6 s with every line intact.
+
+## Draft loop
+
+1. **Part 1 first** as the test for a new series or look. Review it yourself before firing the rest.
+2. Then submit the remaining approved parts of the episode in one parallel batch (no waiting on each other). A part whose assets already exist goes out at once; only parts waiting on a new location or prop wait for that asset.
+3. **QA every part** (below). FAIL → the smallest fix: re-prompt and re-render only the failed shot as a short part (4-8 s), not the whole part. Max 2 retries per item, then show the user the evidence and options.
+4. Accept small render notes; fix only story, continuity or taste breaks.
+5. Do not poll in a loop; the generation card updates itself. When the next step needs the URL, check status without `wait` every 1-2 minutes (a 15 s Draft took about 5 minutes; long `wait` calls can time out on the client).
+
+## Render QA (per part)
+
+Look at frames, not the prompt. Outside agents: `python scripts/micro-drama/shot_map.py part.mp4 out/` and read every strip. Kobi: extract one frame per shot with ffmpeg on the Act host and view them.
+
+- Faces, hair, wardrobe and props match the sheets in every shot; no extra people; no text or logos.
+- Blocking holds: furniture in the same place, each person where the previous shot left them, screen direction consistent.
+- Eyes never in the lens; face fully in frame on speaking and reacting shots; at least one visible change per close shot.
+- Props physically right (open bottle before pouring, the card in the same hand).
+- Dialogue: `transcribe_audio` the part; every scripted line present once, in order, no invented words, right speaker's lips moving. No music unless requested. An empty transcript on a part with one quiet line (a whisper, "Theo?") is a transcriber miss, not a missing line: re-run without voice-activity filtering or listen before re-rendering.
+- Shot detection also fires on fast micro-cuts Seedance puts inside an insert (three cuts in 0.5 s). Those are slivers for the edit to drop, not a render failure.
+- Pace: no rushed movement, no dead stretch the edit cannot remove.
+
+## Finals (only the keepers)
+
+1. The user picks the keepers (or approves the tight cut built from Drafts; see `edit-deliver.md`).
+2. For each keeper: `edit_video` with `operation: "draft_quote"`, the Draft's `video_url`, `project_id` and a resolution from the catalog's `final_resolutions` (Drafts expire after `lifetime_seconds`, 7 days as of 2026-10, so finalize within that window). Sum the quotes and show them with the cap.
+3. Only after the user explicitly says yes to that exact quoted credit amount: `edit_video` with `operation: "draft_enhance"` and the same source, project and resolution. Never in the same turn as the quote, never covered by the credit cap or any autonomy setting, never as a default step. Finals are expensive (a 1080p finalization costs about 4.4x the Draft of the same length as of 2026-10); say so when quoting. This renders the same Draft at full quality; it is not a new generation.
+4. If a Draft has expired or cannot be finalized, say so before proposing any new paid render.
+5. Re-check each final against its Draft (same shots, same audio); the edit uses finals only.
+
+Cheaper path for long episodes: build and approve the tight cut from Drafts first, then finalize only the clips the cut actually uses.
+
+Budget alternative: upscale the approved Draft cut instead of re-rendering it. `edit_video` `operation: "upscale"` with the Bytedance upscaler and `enhancement_preset: "short_series"` (made for short dramas) costs a small fraction of a Draft finalization (read the live rate from `list_models type="video_upscale"`). It enlarges the 480p Draft rather than re-rendering it, so detail stays closer to the Draft; say that when offering it. Same rule: quote, explicit yes, then run.
+
+## Bookkeeping and learning
+
+- Record every approved gen id, final id and real `credits_used` in the bible's Episodes section. Never state a remaining balance from arithmetic; call `check_credits` when asked.
+- Stop and report when a series reaches its cap or any item fails QA three times.
+- Every note from the user: fix the item, find the root cause (wording, reference, setting), add a rule to the bible's House rules, and apply it to all later prompts of the series.

package/skill/references/workflows/micro-drama/series-bible.md

@@ -0,0 +1,61 @@
+# Micro-drama — series bible
+
+The bible is the single source of truth for a series. It lives as a Kolbo Doc in the series' Kolbo project, so Kobi, outside agents and the user all read and edit the same thing. Record every approved asset the moment it is approved; never record pending takes.
+
+## Template (copy into the Doc)
+
+```
+# <Series title>
+Kickoff: genre | episodes | length | aspect | language | look route | final resolution | credit cap (season / episode)
+Project: <project_id>
+
+## Logline
+One sentence: who, what they want, what stands in the way, why it's charged.
+
+## The edge (theme)
+What the series is really about (power, loyalty, guilt, ambition, belonging). Every episode tests it.
+
+## World + look (LOCKED - pasted into every prompt and every key art)
+Period, place, palette, lens/grade, weather, 2-3 signature props. Must be recognisable from one frame.
+
+## Engine
+Why they shouldn't, why they can't stop / why the mystery can't stay closed.
+Season prop: one object that changes hands and pays off later (a card, a key, a ring, a voicemail).
+Geography premise (if any): the physical relationship the series is built on (facing windows, adjoining offices).
+
+## Characters
+| Name | Age (21+) | Wound | Mask | Want | Need | Secret | Power | Signature habit | Voice notes | Asymmetry |
+Asymmetry = scar side, hair parting, which wrist wears the watch/ring, logos/text on clothes. The editor reads it
+before mirroring any shot.
+
+## Locked assets
+| Character | Look | Sheet URL | Visual DNA id / @tag | Voice sample URL (seconds) | Episodes |
+| Location | Frame URL | Visual DNA id / @tag | Geography (door, window, furniture from camera) |
+| Prop | Sheet URL | Which hand / shoulder, per sheet panel |
+
+## Season outline (one row per episode)
+| Ep | Event | Reversal | Cliff (line or image) | Looks used | Locations | Free/paid |
+
+## Episodes
+Per episode: script link, prompt files, Draft gen ids, approved/finalized gen ids, credits spent, cut link, notes.
+
+## House rules
+Every note from the user, as a rule: date, note, rule. Read before writing the next episode.
+```
+
+## Season engine
+
+- Write the whole season outline, with every Looks table, before producing Episode 2. Episode 1 can be produced first as a pilot.
+- Each episode answers the previous episode's question before it opens a new one.
+- Every episode ends on a cliff that adds a person or a fact (a reveal), not on a line alone.
+- Power shifts between the leads across the season; static power is boring.
+- Plant the season prop by Episode 1 or 2 and pay it off by the finale.
+- Leftover arcs become Season 2; do not cram them in.
+
+## Looks (wardrobe continuity)
+
+A character changes look only when the story says so (new day, new place, new situation). The same scene keeps the same look; looks are reused across episodes. Each look is its own sheet named `<name>-<look>`, listed in the Locked assets table with the episodes it appears in. Make a season's new looks in one batch after the outline is approved.
+
+## Release unit
+
+Each series goes out as trailer + Episode 1 together. The trailer is made right after Episode 1 is approved (`edit-deliver.md`). Number episodes in post captions ("Episode 2") and tease the next one; the call to action lives in the post caption, never in the video.

package/skill/references/workflows/micro-drama/shots-prompts.md

@@ -0,0 +1,76 @@
+# Micro-drama — shots and Seedance 2.5 prompts
+
+One prompt per part, compiled as the Locked Intro in `models/seedance25.md` (read it and `models/seedance.md` first). Acting and blocking depth: `filmmaking/acting-direction.md`, `filmmaking/blocking-continuity.md`. This file adds what micro-drama parts need.
+
+## Before writing a part
+
+**Character brief per person in the part** (one line each, goes into CAST):
+- Who: age, origin, one life fact that colours how they move.
+- Just before: what happened a minute ago.
+- Wants from the other person in this part: one verb, and what they hide.
+The shot list then describes behaviour that follows from it (fixes a sleeve that doesn't need fixing, looks at his hands before his face, starts a line, stops, says it), never state words.
+
+**Banned words in video prompts:** real, realistic, natural acting, not robotic, emotional, sensual, sultry, intimate (as a delivery note). Replace each with what the body or voice does.
+
+## Blocking
+
+1. Look at the location frame first. Name only what is in it, where it is (frame left / centre / right, foreground / back). Anything not in it gets an explicit place relative to what is ("the front door is behind the camera").
+2. `[LOCATION]` carries a **FLOOR PLAN** (fixed positions of furniture and entrances) and an **AXIS** (who stands where, facing which way) for the whole part.
+3. Every shot opens with **start positions**; the start of shot N is the end of shot N-1. Movement says from where to where.
+4. **Eye-lines have targets** on the floor plan, off one side of the camera ("toward Dana, far left of frame"). If the target is behind or in line with the camera, the eyes land in the lens. A line spoken TO someone is shot over that person's shoulder. Nobody looks into the lens, ever.
+5. **Entrances:** put the camera on the character's side of the door (inside the cab, behind her shoulder; the door opens and reveals the room). A camera already inside shows the result, not the reveal.
+6. **Prop state before action:** pre-set it ("the bottle is already open, its cap beside it") and describe visible physics. Never chain "opens and pours" in one beat.
+7. **Carried props** appear in every shot's blocking. Props stay where the last part left them.
+8. **Movement at human pace:** calm walk ≈ 1 m/s, pick up / put down ≈ 1.5 s, turn ≈ 1 s. Budget each move in the part's timing.
+9. **One continuous moment per part.** No time or place jump inside a part; exits and new rooms get their own part, with a cause.
+10. Lying or seated characters: place the camera relative to the FACE.
+
+## Coverage (default)
+
+- Regular drama coverage: eye-level mediums, medium close-ups, over-the-shoulders, two-shots staged in depth (never two profiles across the narrow frame), one wide for movement or geography. 35-50 mm feel.
+- Vertical framing: tightest default is MCU chest-up; one close-up per part for the key beat. Face fully in frame on any speaking or reacting shot.
+- Camera: "shoulder-mounted handheld operated by a real person, gentle organic sway, small natural reframes; never shaky, never locked off".
+- Lens and grade: vertical cannot be anamorphic. "Vintage spherical cinema lenses, round creamy bokeh, gentle halation around practicals, shallow depth of field" + the bible's grade word for word in every prompt.
+- 2-3 shots per 13 s of slow action; dialogue-driven parts can carry more. Cuts are motivated by dialogue (speaker or listener reaction), never to show a new action.
+- Whoever makes a sound (breath, laugh, gasp) is on screen when it happens. Every close shot has one visible change (eyes, breath, a swallow).
+
+## Write for the edit
+
+- Gestures complete inside one shot.
+- Consecutive shots change angle or size (no same-angle neighbours).
+- Each shot holds about 0.5 s after its last line.
+- Plan one listener reaction shot for every key line (cutaway and L-cut material).
+- End each part on an explicit final frame; the next part's first shot starts from it (CONTINUITY line).
+
+## Audio block (Seedance generates the whole soundtrack natively)
+
+```
+[AUDIO - GENERATE THE WHOLE SOUNDTRACK NATIVELY]
+@Audio1 is ONLY <NAME A>'s voice identity; never speak the words heard in it. @Audio2 is ONLY <NAME B>'s voice identity.
+Dialogue in this order, each spoken once, no other words:
+1. ~0.6s NAME A, <what she is doing / wants>, with her <accent>: "<line>"
+2. ~3.1s NAME B, <...>, with his <accent>: "<line>"
+Breathing soft and natural only. Room tone: <space>. Foley: <each named move and prop touch>.
+No music. No musical score. No stingers, no whooshes.
+```
+
+- Name each speaker's accent in CAST and in every one of their lines; the voice sample alone does not hold it.
+- The part ends about 1 s after its last line. Between lines 0.5-1.2 s; one longer beat (≤2 s) only where a line must land.
+- AVOID adds: speaking the words of the reference audio, loud breathing, music.
+- Music is added in the edit only if the user asks (a montage beat can run on a track; see `edit-deliver.md`).
+
+## The call
+
+`generate_elements` (or the tool the core skill routes to) with `model: "seedance-2-5"`, `draft: true`, `duration` = the part's length (4-30 s), `aspect_ratio` from the kickoff, `multi_shots: true`, `enhance_prompt: false`, `reference_images` = [character sheets for the looks in this scene, location frame, prop sheets], `reference_audio_urls` = [voice samples of the speaking characters], Visual DNA ids if used, `project_id`. Tag every reference inside the prompt per the Kolbo prompt conventions; an untagged reference is ignored. AVOID always includes: face morphing, outfit/hair/jewelry changes, extra people, crossing the axis, lips moving on the listener, looking into the camera, text, subtitles, logos, flat video look, oversaturated color.
+
+## Prompt QA gate (before submitting)
+
+- Every character has a brief; no banned words.
+- Every prop is named one way everywhere (a "cordless phone" with a "phone cord" made Seedance pick a corded phone).
+- The first line or hook action lands inside the first 2 s (pre-set the prop in hand rather than spending 2 s on a reach).
+- FLOOR PLAN + AXIS present; furniture named only if it is in the location frame or placed relative to it; each shot's start = previous end.
+- Every eye-line has a target off one side; lines to someone shot over that person's shoulder.
+- Wardrobe in CAST matches the sheet's front panel; no CAST sentence contradicts a reference image.
+- Timecodes sum to `duration`; Total lines and Multishot header present (`models/seedance25.md`).
+- Audio block lists lines in order with accents; timeline ends ≤1 s after the last line; "No music" present unless requested.
+- No famous names or IP; all ages 21+.

package/skill/references/workflows/micro-drama/writing.md

@@ -0,0 +1,50 @@
+# Micro-drama — writing (series, season, episode)
+
+Story craft comes from `filmmaking/scene-engine.md` (Goal → Obstacle → Tactic → Reversal → value shift). This file adds the micro-drama format and the anti-slop rules.
+
+## Format
+
+- Vertical, 45-90 s per episode by default (the user's kickoff answer wins). Length follows the story; never rush a scene to fit a credit number. If budget is tight, cut episodes, not pace.
+- Write the full natural scene first, then split it into parts of about 15-25 s (one Seedance 2.5 generation each, max 30 s), at most four dialogue lines per part, with room for silent beats.
+- **Works with the sound off.** A viewer must follow the episode from the picture: glances, props, geography, reactions. Dialogue is sparse and sharp. Proven serials carry an episode on 4-10 short lines.
+- **Pace:** Episode 1 may breathe (longer takes for the meet or the setup). From Episode 2 the cut settles near 2 s per shot, with emotional beats on face close-ups and shot/reverse.
+
+## Episode beat structure
+
+| Beat | Job |
+|---|---|
+| Hook (0-2 s) | the situation in one image or one line only this character would say |
+| Re-establish | answer last episode's question; show the geography / relationship |
+| Tactic / counter-tactic | 2-4 short exchanges; want vs want; power shifts once |
+| Stakes | someone or something could end it |
+| Cliff | a reveal that adds a person or a fact; the last line implies, never explains |
+
+Per part: name the **value shift** ("she arrives in control → leaves exposed"). If nothing turns, rewrite. Mark 2-3 **trailer moments** per episode (a striking entrance, a look, a one-line punch) that work out of context.
+
+Deliverable per episode: beats table, dialogue timeline (`0.5s - NAME, delivery: "line"`), part split, continuity / final frame per part, trailer moments, value shift.
+
+## Genre templates (starting points, not formulas)
+
+| Genre | Engine | Hook | Cliff pattern | Look |
+|---|---|---|---|---|
+| Romance / revenge | hidden identity, betrayal, second chance, rival | a humiliation or a collision | the rival enters frame / the identity slips | warm glamour, practicals, rain, nostalgia |
+| Thriller / mystery | a secret someone will kill for, a clock | a body, a message, a wrong number | a new fact reverses who we trust | cool night, hard light, reflections |
+| Brand series | a recurring cast whose lives touch the product naturally | a relatable problem in 2 s | a personal stake left open, never a sales line | the brand's palette as the world grade |
+| Comedy / sitcom | a fixed group, a fixed place, escalating misunderstandings | the absurd premise in one line | a callback or a worse misunderstanding | bright, even light, wider shots |
+
+Brand series rules: the product is a prop in the story (it changes access or information), never a feature list; the brand name appears in the caption and key art, sparingly on screen; every claim about the product comes from the client's own material.
+
+## Anti-slop rules
+
+- **Names:** real names people of that origin and era have. Banned AI defaults: Elara, Lyra, Kael, Seraphina, Aria, Nova, Lucien, Orion, Zara, Luna, Kai, "Blackwood"-type surnames.
+- **One odd true detail per character** (she counts stairs when nervous; he keeps a dead colleague's voicemail).
+- **Lines only this character would say.** Kill swappable lines ("We shouldn't be doing this", "You don't know what you do to me").
+- **Specific nouns** ("a 1994 Saab with a cracked tail light", not "a luxury car").
+- **Props change access or information.** A card is thrown away, then retrieved; a key opens the wrong door.
+- **Characters do concrete tasks** while they talk (sorting mail, packing a box), never stand and deliver.
+- **Surprise test:** one moment per episode the viewer did not predict from the logline. A guessable cliff gets rewritten.
+- **Audit before approval:** flag every generic line or name and replace it before production.
+
+## Safety
+
+Every character 21+ and visibly adult; no school or teen framing. Consent explicit in romantic beats. No real people; real companies stay unnamed unless the user owns the brand. Villains are not ethnic or religious stereotypes.

package/skill/references/workflows/micro-drama.md

@@ -0,0 +1,57 @@
+# Micro-Drama Studio
+
+Produce a vertical micro-drama series end to end in Kolbo: series bible, cast, locations, voices, Seedance 2.5 Draft episodes, finals, the edit, a series trailer, social cutdowns and key art. Use when the user wants a micro-drama, a short-form drama series, episodic vertical drama, a branded drama series, or "a show like ReelShort / DramaBox".
+
+This file is the router and the operating contract. Load the stage file when you reach that stage; each one is short and owns its QA gate.
+
+| Stage | Read | Output |
+|---|---|---|
+| 0. Kickoff | this file | answers to the kickoff questions, Kolbo project, bible Doc |
+| 1. Bible + season | `micro-drama/series-bible.md`, `micro-drama/writing.md` | logline, world + look, characters, season outline with every Looks table |
+| 2. Episode script | `micro-drama/writing.md` | beats, dialogue, parts, trailer moments |
+| 3. Cast, looks, locations, voices | `micro-drama/cast-locations-voices.md` | character sheets + Visual DNAs, location frames, locked voice samples |
+| 4. Shots + prompts | `micro-drama/shots-prompts.md` + `models/seedance25.md` | one Seedance 2.5 prompt per part |
+| 5. Draft render, review, finals | `micro-drama/render-qa.md` | approved Draft parts, finalized keepers |
+| 6. Edit + delivery | `micro-drama/edit-deliver.md` | tight cut, platform episode, social cutdowns, trailer, key art |
+
+Craft depth lives in the filmmaking packs; reuse them, do not restate them: `filmmaking.md` (router), `filmmaking/scene-engine.md`, `filmmaking/acting-direction.md`, `filmmaking/blocking-continuity.md`, `filmmaking/audio-dialogue-music.md`, `visual-dna.md`, `video-editor.md`.
+
+## Stage 0 — Kickoff (ask once, in one labeled question card)
+
+Ask these before any paid step, with the suggested default first. Store the answers at the top of the bible.
+
+1. **Idea + genre**: the user's premise, and one of the genre templates in `micro-drama/writing.md` (romance/revenge, thriller/mystery, brand series, comedy) or "other".
+2. **Season shape**: number of episodes (suggest 6), episode length (suggest 45-90 s), aspect (suggest 9:16).
+3. **Language**: English is the reliable default. Seedance 2.5 performs English dialogue natively. For any other language, tell the user before anything is generated: Seedance 2.5 may not speak it (it does not speak Hebrew at all), and the route is either a model that speaks it natively (check `list_models`) or recorded/generated speech with a lip-sync model, both with their own cost and quality trade-offs. Let the user choose.
+4. **Look route**: photoreal drama, or a stylized glamour / nostalgic look (Midjourney stills as the look source). See `cast-locations-voices.md`.
+5. **Finals**: episodes are always blocked in Seedance 2.5 Draft. Read `draft_resolutions[].final_resolutions` for `seedance-2-5` in `list_models` (as of 2026-10 a Draft finalizes to 1080p only). If there is a choice, ask which tier; if not, tell the user the final tier and its cost per 30 s, and ask whether to finalize at all or deliver the Draft cut.
+6. **Credit cap** for the season (and per episode), quoted against the estimate in `render-qa.md`.
+
+Then create one Kolbo project per series (`create_project`) and pass its `project_id` on every call. The bible is a Kolbo Doc in that project (`create_doc`), so Kobi, the user and outside agents read the same source of truth.
+
+## Approval gates (the user decides; the agent runs everything between them)
+
+1. Concept + season outline.
+2. Each new character's sheet, then its voice (picked from 2-4 auditions).
+3. Credit cap. Inside the cap, Draft renders run without asking. Every finalization, and anything over the cap, needs a yes with the quoted cost.
+4. The tight cut of each episode.
+5. Publishing is always the user's action.
+
+In Kobi Act, `submit_plan` is the approval card for each gate; do not add extra confirmation loops between gates. Outside Kobi, follow the Kolbo brief-and-cost confirmation rule at each gate.
+
+## Where it runs
+
+Any agent connected to the Kolbo MCP can run this workflow end to end: Kobi in the Kolbo app, Kolbo Code, Claude Code, Codex / ChatGPT agents, Cursor. Generation, references, project, bible Doc and transcription are all Kolbo tools. The only local part is the optional edit scripts, which need a shell, Python 3, numpy and ffmpeg; agents without a shell build the cut in the Kolbo Video Editor instead.
+
+## Who edits
+
+- **Kobi** builds every cut in the Kolbo Video Editor (`video-editor.md`), so the user can open and tweak it.
+- **Outside agents** (Claude Code, Codex, Kolbo Code) with a shell edit locally with the bundled scripts in `scripts/micro-drama/` (Python 3 + numpy + ffmpeg). They may also hand the user a Video Editor session if asked.
+
+## Hard rules
+
+- Every character is fictional and a clearly adult (21+), stated in every character prompt and visible on screen. No real-person or celebrity likeness. No famous names or IP in any prompt.
+- Consent is explicit in any romantic or intimate beat. No sexual content; heat stays at the level the user's platforms allow.
+- Never spend over the cap. Never finalize without a quote and a yes.
+- Every stage ends in its QA gate. A failed gate gets the smallest fix (one shot, not the episode), at most 2 retries per item, then report to the user with evidence.
+- Every user note becomes a fix plus a rule in the series bible's "House rules" section, so the next episode does not repeat it.

package/skill/references/workflows/transcription.md

@@ -4,19 +4,20 @@ Load this file when the user wants to transcribe audio/video, get SRT subtitles,
 
 ## Decision Tree
 
-You have three routes. The right one depends on the file profile — pick before calling any tool.
+Pick the route from the question and coverage needed. For long recordings or iterative evidence review, first read `video-investigation.md`.
 
 ```
 Image (jpg/png/webp)?                         → Read directly (native vision, up to 10 per pass)
-Any QUESTION about a video (what/when/how many/summarize/describe)? → analyze_video (agentic — the default for video)
+Long recording / cuts / verified content or audiovisual investigation? → prepare_video_inspection → inspect_video → targeted evidence analysis/ASR
+One-off short video or YouTube question?      → analyze_video
 User wants the transcript/SRT as deliverable? → transcribe_audio, return the URLs
-Precise answer about one specific frame?      → ffmpeg that frame → Read
+Precise answer about one specific frame?      → inspect_video kind=frame at a source timestamp
 File is only reachable locally and >100MB?    → split with ffmpeg, or HYBRID below
 ```
 
-## `analyze_video` — Kolbo's official video understanding (use this first)
+## `analyze_video` — one-off video understanding
 
-Agentic Gemini: instead of sampling the video at a fixed frame rate, the model navigates the timeline itself — loading frames, audio, and the transcript only where the question needs them. That removes the two old failure modes below (long-form decay, transcription-dense laziness): a 90-minute lecture is answered from the parts that matter, at a fraction of the tokens.
+Agentic Gemini can navigate selected frames/audio/transcript. It remains bounded by provider limits, timeout and model behavior; do not assume it reviewed an entire recording. For long-form investigation use the prepared-source evidence workflow so the agent controls coverage and can verify or revise findings.
 
 - `video_url` (public https, e.g. the URL returned by `upload_media` / `list_media`) **or** `youtube_url`.
 - `prompt`: the question. Ask directly — "At what timestamp does the logo appear?", "How many people speak, and who says X?", "List every product shown with its time". Omit for a full description + verbatim transcript.

package/skill/references/workflows/troubleshooting.md

@@ -30,6 +30,10 @@ This re-wires the MCP configuration automatically. Then restart the session.
 
 Status semantics, `wait=true` batching, black-card-is-normal and the credit guard live in SKILL.md "⚠️ Generation lifecycle — source of truth, waiting, failures".
 
+## `MODEL_NOT_FOUND` (400)
+
+An explicit `model` the API cannot match is rejected with `400 MODEL_NOT_FOUND` plus "did you mean" suggestions — it no longer falls back to Smart Select. Nothing ran and nothing was billed. Pick the right identifier from the suggestions or `list_models` (with the tool's `type`) and retry. Only an omitted `model` or an auto alias (`auto`, `smart-select`) auto-selects.
+
 ## "Rate limited" (429 errors)
 
 Wait 60s for the window to reset, retry only the failed calls. For batch image work prefer `generate_creative_director` over multiple `generate_image` calls. Full rate-limit details + retry sequence: see SKILL.md "Rate Limiting & Batch Generation".

package/skill/references/workflows/video-investigation.md

@@ -0,0 +1,64 @@
+---
+name: video-investigation
+description: Investigate recordings through adaptive contact sheets, individual frames, cut candidates, transcription, music and sound evidence.
+---
+
+# Adaptive video investigation
+
+Use for understanding content, finding events, reviewing edits, comparing continuity,
+extracting quotes, or studying motion, music and sound. Choose evidence for the question.
+
+1. Define what would answer the request. Inspect duration and streams with
+   `prepare_video_inspection`, then `get_video_inspection`. Preparation is asynchronous;
+   wait before polling again. Reuse the inspection ID, never repeatedly download.
+2. Build a broad visual map with `inspect_video` kind `frames`. Start with 12 sparse
+   frames across the recording, then use additional ranges when the question requires
+   coverage. Read the returned IMAGE blocks. Write hypotheses, uncertainty and source
+   timestamps. A sheet is a navigation aid, not continuous viewing.
+3. Narrow promising or ambiguous intervals. Sample more densely, then request kind
+   `frame` with exactly one timestamp for details. Use kind `cuts` in windows up to
+   120 seconds when transitions matter. Cuts are candidates from an 8 fps proxy;
+   verify nearby full frames. Sparse sampling can miss brief actions or cuts.
+4. For motion, continuity, text over time or audiovisual alignment, extract kind
+   `clip` and call `analyze_video_evidence` focus `video` with a specific question.
+   The interval alone is analyzed. Keep original source offset and clip-relative
+   timestamps separate. Convert returned times by adding source_offset_seconds.
+5. For speech, extract kind `audio`, then `transcribe_video_evidence` for word timings,
+   speakers and SRT. Source times are supplied on every word; SRT remains clip-relative.
+   Verify unclear words before quoting. To cover all speech in a long recording, use
+   explicit consecutive windows with slight overlap, merge by source times and
+   deduplicate overlap. Do not silently transcribe hours when only one event is needed.
+6. For music or sound design, use kind `audio_levels` for measured levels/quiet times,
+   then audio evidence plus `analyze_video_evidence` focus `music` or `sound` for
+   instrumentation, rhythm, mood, sound effects, ambience and speech overlap. Volume
+   measurements do not establish genre, exact BPM, song identity or artist. Request
+   stems only if source separation helps the user's task and spending is authorized.
+7. Revise hypotheses when evidence contradicts them. Stop when the question is answered
+   with sufficient evidence. Save findings in project notes: source_version, inspection
+   ID, question, observed timestamps/ranges, evidence IDs, transcript excerpts, remaining
+   uncertainty and sampled versus continuously analyzed coverage. Generated evidence
+   is not automatically a verified observation. Preserve the distinction after compaction.
+
+Free CPU tools: preparation, status, frames, cut candidates, audio/clip extraction and
+level measurements. Paid tools: evidence analysis and transcription. Follow Act's
+existing plan/spend gate. Each paid evidence call is an explicit step; identical
+successful calls reuse receipts. Do not retry a paid call reported as uncertain.
+For transcription plans set model `elevenlabs/scribe-v2-srt` and duration equal to the
+extracted interval; estimates round up to minutes. Model understanding bills usage.
+
+Limits: source 2 GB and 24 hours, source snapshot two hours, two snapshots per user,
+four per host, 12 frames per call, 120 seconds per decoded interval, 60 evidence
+requests and 100 MB derivatives per snapshot. A three-hour recording is supported
+within the source byte limit; many original high-bitrate recordings require a proxy
+created/uploaded through the approved media workflow. Never download via an unrestricted
+shell URL or run a full-length decode on the Act host. A one-off short source or
+YouTube page can still use `analyze_video`; do not claim that route proves full coverage.
+Cancel unused snapshots with `cancel_video_inspection`. Preparation and extraction
+stop; a provider request already accepted can still finish and incur credits.
+
+Example: a 3-hour recording with a missing graphic. Start sparse, discover candidate
+chapter ranges, inspect those more densely, read individual frames where the graphic
+appears, then verify appearance/disappearance with nearby clip evidence. Analyze audio
+only if needed. Report verified windows and any unexamined gaps; do not say you watched
+all three hours. The same reasoning applies to lectures, screen recordings, podcasts,
+films, generated clips and event footage.