@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/codex-video-pipeline/references/quality-gates.md

@@ -0,0 +1,44 @@
+# 成片质量门
+
+## 内容
+
+- 前 3 秒说明观众为什么要继续看；
+- 脚本交付了开头承诺的结果；
+- 重要事实有来源，推断没有冒充事实；
+- 结尾给完成标准、判断规则或可以复用的做法；
+- 画面上没有“内部使用、占位、待确认、不要公开”等制作备注。
+
+## 视觉
+
+- 全片有统一主色、正文色和高亮色；
+- 暗色不是硬性要求，但最复杂背景上文字必须可读；
+- 有实拍素材时作为动态底层，遮罩不应把画面完全抹掉；
+- 没有实拍时仍有相关动态层次，不是大片空白；
+- 连续三段不能只靠标题、卡片或相同方向滑入；
+- 文字、数据、线条和图表承担解释任务；
+- 进度条从 0 到 100% 连续增长，不按场景重置。
+
+## 字幕与声音
+
+- 最终旁白与字幕凭据的音频哈希一致；
+- 字幕源是声学对齐，不是字数估时；
+- 英文完整名称没有被拆开；
+- 人声清楚，BGM 不盖住旁白；
+- 结尾没有戛然而止或突兀断音；
+- MP4 中同时存在视频流和音频流。
+- 发布视频使用 H.264 视频与 AAC 音频编码，帧率与 `project.json` 一致；默认约为 30fps。
+
+## 素材与版权
+
+- 用户素材已确认使用范围；
+- Pexels 文件有同名 `.source.json`；
+- 不使用来源不明的短视频、音乐和字体；
+- 可识别人物不被放入负面或冒犯语境；
+- 不暗示素材人物或品牌为内容背书；
+- 发布文案保留实际使用素材的来源说明。
+
+## 产出
+
+两张封面必须分别排版，并检查：标题逐字正确、没有拉伸或异常断行；缩略图仍能读出主问题；主视觉与本期内容直接相关；没有乱码、随机英文或无关标签。
+
+`产出/` 只有：最终中文名 MP4、横版封面、竖版封面和发布文案。运行 `project.py verify` 通过后才能宣布完成。

package/skills/codex-video-pipeline/references/research-and-script.md

@@ -0,0 +1,50 @@
+# 研究与脚本
+
+## 选题判断
+
+一个选题至少满足三项：
+
+- 观众正在遇到，或者近期出现明显变化；
+- 能展示一个真实输入、操作过程或结果；
+- 有可靠资料或可复现实验支撑；
+- 画面能发生变化，不只能播放标题卡；
+- 看完能带走步骤、判断规则、检查清单或避坑点。
+
+不要连续只做同一工具或同一任务。AI 知识、应用工作流、实践经验可以交替出现。
+
+## 研究记录
+
+在 `RESEARCH.md` 中分开写：
+
+- 已核实事实：给原始来源、发布日期和适用范围；
+- 推断与判断：明确这是作者的归纳；
+- 风险与不确定性：不能确定的地方不要包装成结论；
+- 画面证据：哪些事实能用真实操作、界面、数据或对比证明。
+
+技术问题优先官方文档和原项目；医疗、法律、金融、招聘、隐私与版权等高风险主题必须使用权威来源并保留人工复核责任。
+
+## 脚本结构
+
+应用型视频推荐：
+
+1. 开头：观众问题与可见结果；
+2. 起点：原始材料究竟有多乱；
+3. 分工：AI 负责什么，人负责什么；
+4. 执行：3–5 个动作，每步有状态变化；
+5. 验收：如何判断真的完成；
+6. 边界：最常见失败点或风险；
+7. 收束：给观众可直接复用的做法。
+
+旁白写成人会说的话。少用“不是……而是……”“真正的……从来不是……”等模板句；不要用点赞关注替代内容回报。
+
+## 动态叙事图
+
+每段填写：
+
+- 旁白任务；
+- 主要对象；
+- 对象状态变化；
+- 如何继承上一段的运动或视觉锚点；
+- 文字、数据和线条各自为什么出现；
+- 需要的图片、实拍或界面；
+- 最可能退化成 PPT 的地方和修正方法。

package/skills/collage-broll-explainers/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: collage-broll-explainers
+description: "Turn a ~5-second voiceover line, opinion sentence, or abstract concept into a premium editorial halftone paper-collage B-roll clip — optionally with a fitted voiceover. Load this skill whenever the user says \"collage b-roll\", \"paper collage b-roll\", \"halftone collage\", \"collage-style visuals\", \"collage explainer\" (or the Chinese triggers 纸拼贴 b-roll / 半调拼贴 / 拼贴风格配画面), or wants a script line turned into a collage visual metaphor. Enforces a mandatory three-gate approval flow — propose visual metaphors only, generate color collage stills only after the user confirms, and only after the stills are confirmed generate the assemble-from-empty animation. Video model is gemini-omni-flash, locked — no other video model is ever used and the choice is never offered to the user. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "MegaTroll222/VOX-COLLAGE-BROLL"
+---
+
+# Collage B-roll Explainers
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Compress a ~5-second voiceover line into one sharp visual idea, then turn it into a premium editorial paper-collage assembly animation.
+
+Default pipeline:
+
+1. Design the visual metaphor only, then wait for the user to confirm
+2. Generate the final still frame only, then wait for the user to confirm
+3. Automatically generate the video with first/last-frame references and run QA
+4. Optionally generate a fitted voiceover and mux it in
+
+The two confirmation gates are part of the workflow, not overhead. They let the user spend their attention on aesthetics and direction, and prevent a wrong metaphor or a wrong still from burning video-generation cost.
+
+## Runtime requirements
+
+- **MaxFusion MCP** connected and authenticated (`https://mcp.maxfusion.ai/mcp`). All image, video, and speech generation runs through it. If it is not connected, stop and walk the user through connecting before doing anything else.
+- **Local file access and ffmpeg** (e.g. Claude Code): frame preparation, video QA, silent delivery, and voiceover fitting download assets and process them locally. A sandboxed agent (no local downloads) can still run all three gates and display results in the MaxFusion widget, but must tell the user that frame preparation falls back to prompt-only color matching and that frame-by-frame self-QA, audio stripping, and voiceover fitting were skipped — the user should judge the clip by eye and mute it in their editor.
+
+## Mandatory approval protocol
+
+### Gate 1: Metaphor confirmation
+
+When you receive the script line(s), propose visual metaphors first. Do not generate any image, do not generate any video, do not call any generation tool.
+
+Deliver, for each line:
+
+- Core meaning
+- Emotion
+- One-sentence visual proposition
+- 3–6 key objects
+- Suggested background color and local accent colors
+- Intended assembly order
+
+Then stop explicitly and wait for the user to reply "approved", "all approved", or give per-item revision notes.
+
+If the user approves only some of the numbered items, only the approved items advance to Gate 2; keep iterating on the metaphors for the rest.
+
+### Gate 2: Still-frame confirmation
+
+Only after the metaphor is confirmed do you write the visual spec and the image prompt, and generate the final still with `maxfusion_generate_image`.
+
+Save the originals into the project directory, build a numbered still contact sheet, display every still to the user (`maxfusion_display_generation`, one call per image, plus the numbered mapping), and stop again. At this stage you still do not generate any video.
+
+If the user approves only some stills, only the approved items advance to Gate 3; regenerate the rejected stills and re-confirm them first.
+
+### Gate 3: Video generation
+
+Once the stills are confirmed, generate immediately. The video model is locked:
+
+```text
+video_model: gemini-omni-flash
+```
+No other video model is ever used. Do not offer a model choice, do not ask the user which model to use, do not fall back to anything else on failure — apply the repair playbook and re-run on gemini-omni-flash.
+```
+
+## Success criteria
+
+- One line expresses exactly one clear metaphor
+- A batch shares one design language, but is not forced onto a single blue background
+- The background is a strong, flat, uniform color field, varied by meaning
+- Subjects are built from black-and-white halftone photographic cut-outs
+- Key cards, buttons, film strips, rulebooks etc. may use red, yellow, teal, orange, purple, or cream colored cardstock
+- Every paper piece has crisp cut edges, a cream keyline, a soft low-opacity shadow, and paper grain
+- Motion is assemble-from-empty — not gentle drift, wobble, or slow zoom
+- No subtitles, no full script text, no logos, no watermark, no UI
+- Default delivery: 9:16, 5 seconds, 720p, silent MP4 (audio track stripped) — or the voiced version when the user wants voiceover
+
+## When NOT to use this skill
+
+- Precise control of layers, occlusion, camera fly-throughs, or an editable timeline is needed: use a layered animation tool instead (e.g. an HTML-rendered layered video approach)
+- The user only wants a video prompt, not a finished clip: just write the prompt, skip this flow
+- The user needs a real-person product ad or an on-camera presenter: do not use this collage flow
+- The user explicitly needs per-layer editable transparent assets: this skill does not deliver separated transparent layers
+
+## Default project directory
+
+Local working folder, named with the user's local date:
+
+```text
+~/collage-broll-projects/YYYY-MM-DD-<title>/
+```
+Recommended structure for batch projects:
+```
+```text
+<project>/
+├── brief.md
+├── visual-spec.json
+├── imagegen-prompts.md
+├── omni-jobs.json
+├── gate2-qa.md
+├── gate3-qa.md
+├── still-contact-sheet.jpg
+├── omni-contact-sheet-all.jpg
+├── video-first-frame-all.jpg
+├── end-frame-comparison-all.jpg
+├── 01-<concept-name>/
+│   ├── omni-prompt.txt
+│   ├── voiceover-raw.mp3            (optional voiceover stage)
+│   ├── voiceover-trim.mp3
+│   ├── frames/
+│   │   ├── last-frame-original.png
+│   │   ├── first-frame.png
+│   │   └── last-frame.png
+│   └── omni/run-v01/
+│       ├── final-5s.mp4
+│       ├── final-5s-noaudio.mp4
+│       ├── final-5s-voiced.mp4      (optional voiceover stage)
+│       ├── contact-sheet.jpg
+│       ├── video-last-frame.jpg
+│       └── end-frame-comparison.jpg
+└── 02-<concept-name>/...
+```
+Also create a MaxFusion project via `maxfusion_create_project` (same name) and pass its id as `project_id` / `project_group_id` on every generation in the batch, so all assets stay grouped in the workspace. Track per item: the confirmed metaphor text, image job id + image id of the confirmed still, uploaded first/last frame `file_id`s, video job id + video id, and the QA verdict — and report these ids to the user with each gate so any item can be referenced or re-run individually.
+```
+
+## Phase 1: Design the visual metaphor
+
+First compress the script line into a single visual proposition.
+
+Extract:
+
+- Core meaning: what must the viewer finally understand
+- Emotion: calm, surprise, urgency, sudden clarity, absurdity, irony
+- Action verbs: open, connect, leak, bind, archive, light up, compress, fork, assemble
+- Visual metaphor candidates: machine, clock, film strip, filing cabinet, console, rulebook, funnel, rail track, chess piece
+
+Do not put the script text verbatim into the frame. Default to one metaphor per line, held to 3–6 key objects; too many elements dilutes the meaning and makes the Omni assembly unstable.
+
+Prefer metaphors a viewer recognizes from everyday life (a kettle, a snowball, a photo booth) over abstract ones — the spoken line does the bridging to the user's actual topic, so the visuals can stay wild without being obscure.
+
+For batches, prefer metaphors that form a before/after narrative — e.g. first manual toil and experience leaking away, then codified process and human–machine division of labor.
+
+### Gate 1 output example
+
+```text
+1. Core meaning: expertise gets consumed from scratch every single time
+   Visual metaphor: a skilled editor circles a giant film-strip clock cutting frame by frame; the clock completes a full revolution yet yields only a short strip of finished film
+   Key objects: film-strip clock, editor figure, scissors, short output strip
+   Colors: burnt-orange field, cream and light-teal accents
+   Assembly order: clock → figure with scissors → film strip → final short output
+```
+Output this and stop; wait for confirmation.
+```
+
+## Phase 2: Generate the color collage stills
+
+After the metaphor is confirmed, first write a self-contained `visual-spec.json`, then the image prompt.
+
+### Visual spec
+
+```json
+{
+  "script_meaning": "",
+  "visual_metaphor": "",
+  "style_signature": "flat bold color field, mixed black-and-white halftone cut-outs and colored cardstock accents, crisp cut edges, cream keylines, soft paper shadows, editorial paper collage",
+  "aspect_ratio": "9:16",
+  "color_field": {
+    "background_hex": "",
+    "accent_colors": [],
+    "paper_grain": "fine uncoated-paper fiber"
+  },
+  "elements": [
+    {
+      "what": "",
+      "role": "",
+      "motion": "",
+      "placement": ""
+    }
+  ],
+  "composition": {
+    "layout": "",
+    "negative_space": "",
+    "final_frame": ""
+  },
+  "motion_plan": "structure first, subject or cards second, action and result last",
+  "avoid": "typography, readable letters, numerals, logos, watermark, UI, subtitles, glossy 3D, photoreal environment"
+}
+
+### Color rules
+
+Do not treat cobalt blue as the one default. Pick a strong color field from the meaning, and across a batch keep "same design language, different field colors":
+
+- Burnt orange / red: time consumption, labor, urgency
+- Mustard yellow: tools, warning, experience leaking away
+- Ink green: cognition, taste, system reset
+- Deep purple: rules, codification, long-term memory
+- Teal: judgment, collaboration, autonomous execution
+
+Subjects stay mostly black-and-white halftone, but every colored cardstock accent must serve the information hierarchy — never color for color's sake.
+
+### Image prompt template
+
+Generate with `maxfusion_generate_image` (default model, `aspect_ratio: "9_16"`, `quality: "high"`):
+
+```text
+Use case: ads-marketing
+Asset type: final still frame for a 9:16 image-to-video B-roll clip
+Primary request: Create a finished editorial paper-collage image expressing [one-sentence visual proposition].
+Scene/backdrop: perfectly flat [color name] paper field [hex] with subtle uncoated paper fiber.
+Style/medium: premium editorial stop-motion paper collage; black-and-white halftone photographic cut-outs mixed with selective [accent colors] colored cardstock.
+Composition/framing: vertical 9:16 locked poster frame; central subject within the middle 70 percent; generous clean color-field negative space; 3–6 large separable paper groups for later assemble-from-empty animation.
+Materials/textures: visible printed halftone dots, crisp machine-cut edges, thin warm-cream paper keylines, soft low-opacity physical drop shadows.
+Constraints: [the one relationship this metaphor must communicate at a glance].
+Avoid: no typography, no readable letters, no numerals, no logos, no watermark, no UI, no subtitles, no glossy 3D, no photoreal environment, no clutter.
+```
+If the scene contains any dial, clock face, gauge, or counter, add an explicit constraint that every mark on it is a plain tick line — never Roman numerals or digits. If the scene contains a sleeping figure, explicitly ban "Zzz" marks. Video models love sneaking these in.
+
+Poll the job with `maxfusion_get_job` (`wait: 60`); download each still from its asset URL into `<item>/frames/last-frame-original.png` and record the image job id + image id.
+```
+
+### Still QA
+
+- Is the metaphor readable at a glance
+- Is the subject concentrated
+- Any fake lettering, logos, watermark, or UI
+- Enough pure color field left to assemble from an empty frame
+- 3–6 clear large groups, not a screen full of confetti
+- Across the batch: unified texture, varied field colors
+
+Copy the passing originals into the project directory, build a numbered still contact sheet, show it to the user (plus `maxfusion_display_generation` per image), and stop for Gate 2 confirmation. Write the still QA verdicts to `<project>/gate2-qa.md`.
+
+If the user asks to regenerate some stills, regenerate only those and produce `still-contact-sheet-v2.jpg` (v3, v4… on later rounds), keeping the old contact sheets for comparison — never overwrite them, and never reuse a rejected still downstream.
+
+## Phase 3: Generate the video with Omni
+
+### 1. Prepare first and last frames
+
+Keep the imagegen original, then normalize the last frame:
+
+```bash
+-vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920" \
+  <item>/frames/last-frame.png
+```
+```
+The first frame is by default a pure empty paper field in the same background color as the last frame:
+```
+```bash
+-frames:v 1 <item>/frames/first-frame.png
+```
+```
+(`<HEX>` is the `background_hex` from the visual spec — the same hex written into the image prompt, which is what keeps the two frames on the same color.)
+
+Only if the user explicitly asks not to start from a fully blank field may the first frame retain one base structural object.
+
+Upload both frames to MaxFusion with `maxfusion_upload_asset` (`purpose: "image_reference"`, `content_type: "image/png"`, exact `size_bytes`, `filename`): the tool returns an upload session — POST a multipart form to `upload.url` with every key/value from `upload.fields` exactly as given plus the file bytes as the final part named `file` (any 2xx = success), then use each returned `file_id`. Record the two `file_id`s per item.
+```
+
+### 2. Write the Omni animation prompt
+
+Default action order:
+
+```text
+base structure → figure or key cards → connectors → action → final result
+```
+Prompt template (save per item as `<item>/omni-prompt.txt`):
+```
+```text
+Paper-collage stop-motion assembly, using Image 1 as the exact empty first frame and Image 2 as the exact completed last frame. In one continuous locked-off vertical shot, open on the empty flat [color] paper field.
+
+Assemble the scene piece by piece with crisp physical stop-motion timing: [describe, in order, how the 3–6 elements slide in, snap into place, connect, and complete the action]. End by holding the supplied completed composition.
+
+Preserve the exact 9:16 framing, [hex] color field, colored cardstock accents, uncoated paper grain, halftone dots, cream keylines, crisp cut edges and soft shadows. Restrained tactile 2D paper craft only.
+
+No scene cuts, no camera movement, no zoom, no morphing, no new objects, no text, no letters, no numbers, no logos, no watermark, no UI, no sound.
+```
+Every prompt must state that Image 1 is the empty first frame and Image 2 is the confirmed completed last frame. The final composition must land on Image 2 — do not let the model redesign it. Carry any anti-lettering constraint from the still prompt (tick-marks-only dials, no Zzz) into the video prompt too.
+```
+
+### 3. Submit the generation
+
+One `maxfusion_generate_video` call per item. The reference-image order carries the frame roles: the empty first frame is the FIRST id, the normalized last frame is the SECOND, matching "Image 1" / "Image 2" in the prompt.
+
+```text
+video_model: gemini-omni-flash
+ref_image_file_ids: [<first-frame file_id>, <last-frame file_id>]
+prompt: <omni animation prompt>
+duration: 5
+aspect_ratio: 9_16
+resolution: 720p
+project_group_id: <batch project id>
+```
+Record the submitted jobs in `<project>/omni-jobs.json` (prompt, frame file_ids, job id, output path per item). Poll each job with `maxfusion_get_job` (`wait: 60`) until terminal, then download each finished video to `<item>/omni/run-v01/final-5s.mp4`. If an individual job fails, re-run only that job — never re-run items that already passed.
+```
+
+### 4. Enforce silent delivery
+
+Even though the prompt says "no sound", still produce a zero-audio-track version with ffmpeg:
+
+```bash
+-map 0:v:0 -c:v copy -an \
+  <run>/final-5s-noaudio.mp4
+```
+```
+Deliver `final-5s-noaudio.mp4` by default; keep the original `final-5s.mp4` as an intermediate.
+```
+
+## Video QA
+
+Do not judge from the end frame alone — check the assembly progression and the final landing.
+
+### Contact sheet
+
+```bash
+-vf "fps=1,scale=270:480,tile=5x1" \
+  -frames:v 1 <run>/contact-sheet.jpg
+```
+```
+Pass criteria:
+
+- First frame is close to a pure empty color field; paper edges peeking in slightly at the borders are acceptable
+- Mid-clip shows structure, figure, or cards entering step by step — not a global fade-in
+- No cuts, no zoom, no 3D-ification, no drift into a photoreal scene
+- No fake lettering, logos, watermark, or UI
+- Final frame matches the confirmed still; minor pose or small-part drift (a slight figure pose change, a small part added or dropped) that does not affect the metaphor's meaning is a PASS — do not re-run for it
+- Output is 9:16, 720p, 5 seconds, zero audio streams (verify with ffprobe)
+
+Also extract the video's last frame and place it side by side with the confirmed still as `<run>/end-frame-comparison.jpg`. For batch projects, additionally merge three overview images:
+
+- `omni-contact-sheet-all.jpg`: per-second frames of every finished clip
+- `video-first-frame-all.jpg`: the actual first frame of every clip, verifying each truly opens on an empty color field
+- `end-frame-comparison-all.jpg`: confirmed stills side by side with video end frames
+
+Write the per-item QA verdicts — including the reasoning for any pass-with-noted-flaw — to `<project>/gate3-qa.md`.
+```
+
+### Repair playbook (common issues)
+
+- Paper edges visible in the first frame: slightly acceptable; if a strictly empty opening is required, prepend the opening beat in a video editor
+- Weak assembly feel: reduce the element count and rewrite the prompt as an explicit piece-by-piece slide-in / snap-into-place order
+- End-frame drift: strengthen "Image 2 is the exact completed last frame" and "End by holding the supplied completed composition"
+- Fake lettering appears (words, digits, Roman numerals on dials, "Zzz" on sleepers): go back and regenerate — a lettered still gets a new still; a lettered video on a clean still gets one video re-run with the explicit ban added to the prompt
+- One video fails: re-run only that job, on gemini-omni-flash, never by switching models
+
+## Phase 4: Voiceover (optional)
+
+When the user wants the spoken line on the clip, generate it through MaxFusion and fit it locally.
+
+### 1. Choose a voice
+
+List voices with `maxfusion_list_platform_voices` (and `maxfusion_list_my_voices` if the user has saved voices) and ask the user to pick one. Do not design a new voice unless the user explicitly asks. Reuse the same voice for every item in a batch.
+
+### 2. Generate and trim
+
+Generate each line with `maxfusion_generate_speech` (the chosen `voice_id`, default `speed: 1.1` for a brisk read), download the mp3, and strip the trailing silence:
+
+```bash
+-af "areverse,silenceremove=start_periods=1:start_threshold=-45dB,areverse" \
+  <item>/voiceover-trim.mp3
+```
+
+### 3. Fit the 4–5 second window
+
+Measure with ffprobe. The trimmed line must land between 4.0 and 5.0 seconds — shorter leaves dead air against the 5-second clip, longer gets cut off. TTS length varies ±1.5s between identical rolls, so always measure, never assume.
+
+Fix ladder, in order:
+
+1. Trim silence (already done above)
+2. Too short → lengthen the copy slightly; too long → tighten it; regenerate at `speed: 1`
+3. Last resort for a slightly-long line: inaudible tempo nudge, `-af "atempo=1.05"` maximum
+
+### 4. Mux
+
+Video stream is copied untouched; audio is padded to exactly 5 seconds:
+
+```bash
+-map 0:v:0 -map 1:a:0 -c:v copy -c:a aac -af apad -t 5 \
+  <run>/final-5s-voiced.mp4
+```
+
+## Default delivery
+
+Deliver to the user:
+
+- Each item's `<item>/omni/run-v01/final-5s-noaudio.mp4` — or `final-5s-voiced.mp4` when the voiceover stage ran (and display the generation in the MaxFusion widget via `maxfusion_display_generation`)
+- Each item's contact sheet
+- The batch overview contact sheet
+- The end-frame comparison images
+- One sentence per item explaining how the script line became its visual metaphor
+- The batch's MaxFusion project name and the per-item ids needed to re-run or reference anything
+
+If a defect stems from Omni's fast-generation limits, say so plainly; only suggest switching to a layered animation tool when precise layer control is genuinely required.
+
+## Credits
+
+The visual language, three-gate flow, prompt templates, color semantics, and QA/repair playbook originate from [gbro-collage-broll](https://github.com/pyang5166/gbro-collage-broll) by [pyang5166](https://github.com/pyang5166), originally written in Chinese for Codex with local Gemini scripts. This version is an English adaptation for Claude Code + MaxFusion MCP, with an added voiceover-fitting stage.
+
+## Source
+
+Rewritten for AICUT from [`MegaTroll222/VOX-COLLAGE-BROLL`](https://github.com/MegaTroll222/VOX-COLLAGE-BROLL)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.