@lalalic/markcut 2.1.0 → 2.2.1

package/skills/markcut/docs/templates/short-film/TEMPLATE.md

@@ -0,0 +1,387 @@
+---
+name: short-film
+description: Turn a narrative, theme, or script into a 5-10 minute serious dramatic short film with three-act structure, cinematic scenes, sound design, and narrative voiceover.
+when-to-use: dramatic short films, serious documentaries, cinematic mood pieces, narrative storytelling, any 5-10 minute video with dramatic arc and production value
+engine: "@lalalic/markcut — run via `npx @lalalic/markcut`"
+---
+
+# Short Film (严肃短片) Template
+
+Follow this file top to bottom. Read the markcut skill (`SKILL.md` → `docs/markdown-descriptive.md`) first if you have not.
+
+```mermaid
+flowchart LR
+    Input[📥 Concept / Script / Theme] --> Screenplay[✍️ screenplay.md<br/>three-act structure]
+    Screenplay --> Script[📋 acts + scenes + VO lines]
+    Script --> Board[🎬 storyboard.md<br/>shot-by-shot plan]
+    Board --> Film[📄 film.md]
+    BGM["🎵 score + sound design"] --> Film
+    Film --> Render[🎬 npx markcut render]
+    Render --> MP4[📺 final.mp4]
+    MP4 --> Reviewer[🔍 reviewer agent]
+    Reviewer -->|FAIL| Fix[🔧 fix]
+    Fix --> Film
+    Reviewer -->|PASS| Done[✅ Done]
+```
+
+| Path | Runs in | Purpose |
+|---|---|---|
+| `TEMPLATE.md` | your context | everything |
+| `prompts/*.md` | your context | fill-in prompts you execute |
+| `agents/*.md` | separate session | subagent definitions |
+
+## 0. Prerequisites
+
+- `npx @lalalic/markcut` runnable
+- TTS CLI (default: `edge-tts`) — voiceover narration or character voices
+- ITT CLI (for `src:auto` scene generation) — **critical**, every scene is AI-generated
+- `ffmpeg`/`ffprobe` on PATH
+- For reviewer: image-understanding capability, STT CLI
+
+## 1. Inputs — collect before starting
+
+| Input | Required | Default | Notes |
+|---|---|---|---|
+| Concept / logline | **yes** | — | one sentence that captures the film: "A grieving musician finds an old letter that sends him on a journey across the city" |
+| Source material | no | — | optional: existing short story, screenplay, article, or poem to adapt |
+| Film type | no | `dramatic` | `dramatic` (narrative, characters, plot), `documentary` (real-world subject, serious tone), `mood` (atmospheric, minimal plot, sensory) |
+| Tone | no | `serious` | `serious` (somber, weighty), `noir` (dark, mysterious), `melancholic` (sad, reflective), `hopeful` (bittersweet, uplifting) |
+| Language | no | en | narration and on-screen text language |
+| Target duration | no | 7 min | 5–10 min |
+| Voice(s) | no | en: `en-US-GuyNeural` | edge-tts voice(s). For multiple characters, provide a list: {narrator, character1, character2} |
+| Music mood | no | `cinematic` | score style: cinematic, ambient, noir jazz, minimal piano, tense. BGM is **recommended but not mandatory** — silence is a valid cinematic choice |
+| Aspect ratio | no | `16:9` | `16:9` (standard), `2.35:1` (cinemascope — add black bars in stylesheet), `4:3` (vintage) |
+
+**Core principle**: A serious short film is **visual storytelling first**. Every scene should advance the story through image, sound, and performance — not just narration. Voiceover is a tool, not a crutch.
+
+## 2. Scene grammar — three-act narrative architecture
+
+### The dramatic arc
+
+```
+# video                          ← root: width:1920 height:1080 fps:30 layout:series
+│                                  tts:"<edge-tts CLI — narrator voice>"
+│                                  transition:fade(0.5)
+├── - audio isBackground:true foreground:true src:score.mp3 volume:0.12
+├── - audio isBackground:true src:ambient.mp3 volume:0.05  (optional, diegetic ambience)
+│
+├── ## Teaser                    ← 30–90s. Mood establisher, no context yet
+│
+├── ## Act 1 — The Setup         ← 90s–2min. Character, world, inciting incident
+│   ├── ### Scene 1              ← establishing the world
+│   ├── ### Scene 2              ← introducing the protagonist
+│   └── ### Scene 3              ← the inciting incident
+│
+├── ## Act 2 — The Confrontation ← 3–5min. Rising action, complications
+│   ├── ### Scene 4              ← reacting to inciting incident
+│   ├── ### Scene 5              ← rising stakes
+│   ├── ### Scene 6              ← midpoint / turning point
+│   ├── ### Scene 7              ← complications, darkest moment
+│   └── ### Scene 8              ← final push toward climax
+│
+├── ## Act 3 — The Resolution    ← 90s–2min. Climax, denouement
+│   ├── ### Scene 9              ← climax
+│   ├── ### Scene 10             ← falling action
+│   └── ### Scene 11             ← resolution / final image
+│
+└── ## Epilogue                  ← 30–60s. Emotional close, title card
+```
+
+Each `### Scene` is a story beat in a specific location/time. Scenes within an act play sequentially.
+
+### Scene structure (within each scene)
+
+Each scene follows this shape:
+
+```
+### 1.2 — Title (INT/EXT. LOCATION - TIME)
+layout:parallel
+- image src:auto prompt:"<cinematic shot description>" duration:<s>
+  effect:<camera move suggestion>
+- script "<voiceover or dialogue line>" duration:<s>
+```
+
+The scene's `layout:parallel` means the visual and audio play simultaneously. The visual is a generated image (or video) described with cinematic language. The audio is voiceover narration, character dialogue, or ambient sound.
+
+### Scene types
+
+| Type | Purpose | Visual style | Duration |
+|---|---|---|---|
+| **Establishing** | Show location, time, mood | Wide shot, static or slow pan | 8–15s |
+| **Character intro** | Introduce protagonist | Medium shot, shallow DOF | 5–10s |
+| **Dialogue** | Conversation | Shot-reverse-shot or two-shot | 10–30s |
+| **Action** | Movement, event | Dynamic, handheld or tracking | 5–20s |
+| **Montage** | Time passing, emotional build | Series of dissolves, varied shots | 15–45s |
+| **VO/internal** | Voiceover over visuals | Relevant imagery, metaphorical | 5–20s |
+| **Climax** | Peak emotional moment | Intense composition, close-ups | 15–30s |
+| **Resolution** | Calm after storm | Wide, soft lighting, slow | 10–20s |
+| **Transition** | Bridge between acts | Metaphorical, fade to black | 3–5s |
+
+### Timing template (7-minute film)
+
+| Section | Scenes | Total duration | Notes |
+|---|---|---|---|
+| Teaser | 1 scene | 30–60s | No context, pure mood |
+| Act 1 | 3 scenes | 90s | Setup + inciting incident |
+| Act 2 | 4–5 scenes | 3min | Rising action + midpoint + darkest moment |
+| Act 3 | 3 scenes | 90s | Climax + falling action + resolution |
+| Epilogue | 1 scene | 30s | Emotional close |
+| **Total** | **12–13 scenes** | **~7 min** | Adjust proportionally for 5–10 min |
+
+For a 10-minute film, add 1–2 scenes per act. For a 5-minute film, trim 1 scene per act.
+
+### Visual direction prompts
+
+Every image in a short film needs cinematic shot direction. The `src:auto prompt:"..."` must include:
+
+```
+prompt:"[SHOT TYPE] of [SUBJECT], [ACTION/COMPOSITION], [LIGHTING/MOOD], [CAMERA MOVEMENT], [COLOR PALETTE], cinematic, film still, 4K"
+```
+
+| Element | Options |
+|---|---|
+| Shot type | wide shot, medium shot, close-up, extreme close-up, over-the-shoulder, POV, two-shot, establishing shot, aerial shot, Dutch angle |
+| Camera movement | static, slow push-in, slow pull-out, tracking left, pan right, handheld, dolly zoom, crane up |
+| Lighting | golden hour, moonlight, harsh noon sun, soft window light, neon glow, candlelight, low-key, high-key, chiaroscuro, silhouette |
+| Color palette | warm tones, cool blues, desaturated, monochrome, teal and orange, sepia, high contrast |
+| Mood | melancholic, tense, serene, foreboding, intimate, lonely, hopeful |
+
+Example:
+```markdown
+- image src:auto
+  prompt:"WIDE SHOT of a lone figure standing on a rain-soaked platform at dusk, train tracks vanishing into fog, soft amber light from a distant signal, static camera, desaturated cool tones, melancholic mood, cinematic, film still, 4K"
+  duration:12 effect:fadeIn
+```
+
+### Camera effects
+
+| markcut effect | Cinematic equivalent |
+|---|---|
+| `effect:fadeIn` | Dissolve in (soft scene open) |
+| `effect:zoomIn` | Slow push-in (building tension) |
+| `effect:zoomOut` | Slow pull-out (revealing context) |
+| `effect:fadeIn` with long duration | Dissolve (gentle scene transition) |
+| `transition:fade(1.0)` | Fade to black (act break, passage of time) |
+
+### Transitions between scenes
+
+Use the root-level `transition:` for standard scene-to-scene:
+```markdown
+# video
+...
+transition:fade(0.5)
+```
+
+For specific narrative transitions, use a dedicated transition scene:
+```markdown
+### Transition — Fade to Black
+layout:parallel
+- image src:auto prompt:"black frame" duration:2 effect:fadeIn
+```
+
+Or use a metaphorical transition:
+```markdown
+### Transition — The Passing Days
+layout:parallel
+- image src:auto prompt:"EXTREME CLOSE-UP of calendar pages turning in slow motion, warm window light, shallow depth of field, cinematic, film still" duration:4 effect:fadeIn
+- script "Days passed. Weeks. The letter stayed in his pocket."
+```
+
+## 3. Authoring rules — the cinematic bar
+
+### Screenplay structure
+
+Every short film needs:
+
+1. **A protagonist with a desire**: Someone the audience cares about who wants something. The desire drives the plot.
+2. **An inciting incident**: Something that disrupts the protagonist's ordinary world and forces a choice.
+3. **Rising stakes**: Each scene should make the situation more urgent or meaningful.
+4. **A midpoint shift**: Halfway through, the protagonist stops reacting and starts acting.
+5. **A darkest moment**: Just before the climax, all seems lost.
+6. **A climax**: The peak emotional moment where the protagonist confronts the central conflict.
+7. **A resolution**: The new ordinary — how the protagonist is changed.
+
+### Narration / voiceover rules
+
+- **Voiceover is a spice, not the main dish**. The story should be told through images. Use VO only when internal thoughts or context cannot be shown visually.
+- **VO should be poetic but precise**. Short sentences. Concrete imagery. No exposition dumps.
+- **One VO line per scene** (typically). Each line is 10–30 words. 2.5 words/second pace.
+- **If using dialogue between characters**: Use different TTS voices per character. Mark dialogue with character names in the script:
+  ```markdown
+  - script "JOHN: I never thought I'd see this place again.\nMARIA: None of us did."
+  ```
+- **First-person** for personal stories. **Third-person** for documentary-style narration.
+
+### Visual composition rules
+
+- **Every image should tell a story**: A character in a frame should be doing something, feeling something. No empty landscapes unless they serve the mood.
+- **Variety of shot types**: Don't use the same shot type twice in a row. Alternate wide, medium, close-up.
+- **Lighting as storytelling**: A character in shadow = hiding something. Warm light = safety/memory. Cold light = reality/loss.
+- **Color as meaning**: Cool palette for isolation/alienation. Warm for memory/comfort. Desaturated for despair.
+- **Foreground / background**: Use depth (shallow DOF, objects in foreground) to create cinematic depth.
+
+### Sound design
+
+Sound is half the experience of a film. Use:
+
+1. **Score (BGM)**: Root-level audio, `foreground:true` for ducking during VO:
+   ```markdown
+   - audio isBackground:true foreground:true src:score.mp3 volume:0.12
+   ```
+2. **Ambient sound**: Diegetic background — rain, wind, traffic, room tone:
+   ```markdown
+   - audio isBackground:true src:rain-ambient.mp3 volume:0.06
+   ```
+3. **Silence**: For the most dramatic moments, drop ALL audio. A 3–5 second silence before the climax can be more powerful than any music.
+
+### Scene timing rhythm
+
+A 7-minute film ≈ 420 seconds. With ~12 scenes:
+- Average scene: 35 seconds
+- Variation is critical: some scenes 10s (impact), some 60s (breathing room)
+- Act 2 is the longest and should have the widest variation
+- Silence / slow scenes feel longer — use them sparingly
+
+### Multi-language (variants)
+
+- Same `# <lang>` variant block pattern.
+- For translated films: dialogue and VO must preserve the dramatic timing. A line that takes 3s in English should take ~3s in the translation.
+
+## 4. Components & styles
+
+### Optional: Letterbox / Cinemascope overlay
+
+```css
+~~~css stylesheet
+.letterbox {
+  position: absolute;
+  left: 0; right: 0;
+  height: 120px;  /* for 2.35:1 on 16:9 canvas */
+  background: #000;
+  pointer-events: none;
+}
+.letterbox-top { top: 0; }
+.letterbox-bottom { bottom: 0; }
+~~~
+```
+
+```markdown
+- component isBackground:true jsx:"<div className='letterbox letterbox-top' />"
+- component isBackground:true jsx:"<div className='letterbox letterbox-bottom' />"
+```
+
+### Optional: Subtitle styling for film
+
+```markdown
+# video
+... subtitle:{fontSize:"28px",fontFamily:"'Courier New',monospace",style:"text-align:center;text-shadow:0 2px 8px rgba(0,0,0,.8)"}
+```
+
+### Title card component
+
+```jsx
+export function TitleCard({ title, subtitle = '' }) {
+  return (
+    <div style={{
+      width: '100%', height: '100%',
+      display: 'flex', flexDirection: 'column',
+      alignItems: 'center', justifyContent: 'center',
+      background: '#0a0a0a',
+      fontFamily: "'Georgia', serif",
+    }}>
+      <div style={{ fontSize: 64, color: '#f5f5f7', letterSpacing: 4, marginBottom: 20, textAlign: 'center', padding: '0 40px' }}>
+        {title}
+      </div>
+      {subtitle && (
+        <div style={{ fontSize: 24, color: '#888', fontStyle: 'italic', letterSpacing: 2 }}>
+          {subtitle}
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+### Theme knobs
+
+| Knob | Default | Effect |
+|---|---|---|
+| Letterbox height | `0` (none) | `120px` for 2.35:1 cinemascope |
+| Subtitle font | `'Courier New', monospace` | Film subtitle aesthetic |
+| Score volume | `0.12` | Music presence in mix |
+| Transition duration | `0.5s` | Scene-to-scene fade speed |
+
+## 5. Workflow
+
+### Phase 0: Concept
+
+1. **Define the story** — Given the concept/logline, develop:
+   - Protagonist: who, what do they want, what's in their way
+   - Logline expanded into 3-sentence synopsis (beginning, middle, end)
+   - Tone and visual references (films, photographers, color palettes)
+   - VO/narration approach: first-person or third-person, how much
+
+### Phase 1: Screenplay
+
+2. **Write the screenplay** — Fill `prompts/screenplay.md` with the concept. This produces:
+   - Three-act structure with scene-by-scene breakdown
+   - Per-scene: location, time, shot type, VO/dialogue, mood, duration
+   - Visual references for each scene
+
+   The output is a narrative plan, not a technical markcut document.
+
+### Phase 2: Storyboard
+
+3. **Develop shot-by-shot** — For each scene from the screenplay, fill `prompts/storyboard.md`:
+   - Detailed TTI prompt with shot type, lighting, mood, camera movement, color
+   - VO/dialogue text for the scene
+   - Duration and effect
+   - Sound notes (score, ambient, silence)
+
+4. **Generate visuals** — Run ITT CLI for each scene's prompt. Store as `scene-01.jpg`, `scene-02.jpg`, etc. in `.markcut/generated/media/`.
+
+### Phase 3: Assemble
+
+5. **Assemble film.md** — Write the markcut markdown file using §2 grammar:
+   - Root config with TTS voice, optional subtitles
+   - BGM/ambient audio at root level
+   - Teaser → Act 1 → Act 2 → Act 3 → Epilogue
+   - Each scene with cinematic image + VO/dialogue
+   - Transitions between acts (fade to black, metaphorical)
+   - Title card at start, credits at end
+
+6. **Render** — `npx @lalalic/markcut render film.md`. On errors: fix and re-render, max 3 per error.
+
+### Phase 4: Review
+
+7. **Review (quality gate)** — Run `agents/reviewer.md` in a fresh separate session. Pass: `film.md`, rendered MP4, `TEMPLATE.md`, target duration, language, tone, film type. Returns `{verdict, findings[]}`.
+
+8. **Fix loop** — On FAIL: fill `prompts/fix.md` with findings, edit, re-render, re-review. Max 3 iterations, then escalate.
+
+## 6. Quality gate — exit criteria
+
+Done only when ALL hold:
+
+- [ ] reviewer verdict = `PASS` (zero blocker/major findings)
+- [ ] total duration within ±15% of target
+- [ ] structure matches §2 (teaser → act 1 → act 2 → act 3 → epilogue)
+- [ ] protagonist has a clear desire, inciting incident is present, stakes rise through the film
+- [ ] voiceover is minimal — the story is told through images first, VO second
+- [ ] at least 2 shot type transitions in every 3 consecutive scenes (not all wide, not all close-up)
+- [ ] lighting/mood is intentional and consistent within scenes (spot-check 3: does the image match the described tone?)
+- [ ] no blank/black frames; all `src:auto` images rendered with cinematic quality
+- [ ] STT transcript matches script lines (≥85% content match)
+- [ ] BGM (if present) ducked under VO, volume 0.08–0.15
+- [ ] ambient sound (if present) present at low volume (≤0.06)
+- [ ] scene duration variation: at least 2 scenes under 15s AND at least 2 scenes over 40s
+- [ ] transitions between acts are marked (fade to black, transition scene, or clear narrative break)
+- [ ] audio is not uniformly present — at least one moment of silence or near-silence (≤3s of quiet) for dramatic effect
+- [ ] visual prompts include shot type, camera movement, lighting, and color palette (spot-check 3)
+
+## 7. Reference
+
+- Golden example: See `tests/fixtures/templates/courseware.md` for the template format.
+- Screenplay structure: Save the Cat (Blake Snyder) or The Hero's Journey (Joseph Campbell) for scene-by-scene planning.
+- Shot types: See §2 visual direction prompts for the full taxonomy of cinematic shots.
+- Sound design principle: For every minute of film, have at least 5 seconds of silence or near-silence.
+- Effect reference: `fadeIn` (dissolve), `zoomIn` (push-in), `zoomOut` (pull-out), `transition:fade(T)` (scene transition).

package/skills/markcut/docs/templates/short-film/agents/reviewer.md

@@ -0,0 +1,115 @@
+---
+name: short-film-reviewer
+description: Read-only quality gate for serious short films. Checks three-act structure, cinematic visual quality, shot variety, sound design, and narrative arc completeness.
+context: fresh
+mode: read-only
+tools: read file, bash (ffmpeg/ffprobe, STT CLI), image understanding
+---
+
+# System prompt
+
+You are a strict, film-literate QA reviewer for serious short films (5-10 min). You review; you **never edit** any file. Your standards are festival-quality — you judge narrative structure, visual storytelling, shot variety, sound design, and emotional impact.
+
+## Inputs (provided in the task)
+- `film_md` — absolute path to the generated film markdown
+- `mp4` — absolute path to the rendered video
+- `template_md` — absolute path to this `TEMPLATE.md`
+- `duration_min` — target duration
+- `language` — expected language
+- `tone` — serious | noir | melancholic | hopeful
+- `film_type` — dramatic | documentary | mood
+
+## Procedure
+
+### 1. Static review (source vs rulebook)
+
+**Narrative arc** (§2):
+- Teaser present (first section, mood-establisher, 30-90s)
+- Act 1 present with 3 scenes (character intro, world building, inciting incident)
+- Act 2 present with 4-5 scenes (rising action, midpoint, complications, darkest moment)
+- Act 3 present with 3 scenes (climax, falling action, resolution)
+- Epilogue present (emotional close, 30-60s)
+- Total scene count: 11-14 (adjust for 5 vs 10 min)
+- Protagonist has a clear desire (check: does every scene serve that desire?)
+- Inciting incident occurs by end of Act 1
+- Midpoint shift present (protagonist stops reacting, starts acting)
+- Darkest moment present just before climax
+
+**Shot variety**:
+- Scan all `prompt:"..."` values for shot type keywords (wide, medium, close-up, POV, etc.)
+- In every 3 consecutive scenes, at least 2 different shot types.
+- If 3+ consecutive scenes use the same shot type → major finding.
+
+**Visual prompt completeness**:
+- Every `prompt:"..."` should contain: shot type, subject, lighting/mood, and cinematic language.
+- Spot-check 5 prompts. If any is generic ("beautiful landscape" without shot/lighting) → major finding.
+
+**Narration economy**:
+- Count `- script "..."` lines. Check if VO is used sparingly.
+- If there are more VO lines than visual-only scenes, flag as potential over-narration.
+- VO lines should be 10-30 words. If consistently >40 words, minor finding.
+
+**Sound design**:
+- BGM present? Note volume.
+- Ambient sound present? Note.
+- Is there at least one moment of silence or near-silence (≤3s of no audio)? Check for a scene without script and without BGM/ambient, OR a gap between scenes.
+- If audio is uniformly dense (music + VO + ambient in every scene) → major finding.
+
+### 2. Dynamic review
+- `ffprobe`: duration (compare to target ±15%), resolution, audio streams.
+- Extract 12 frames (1 from teaser, 2 from each act, 1 epilogue, +2 key moments).
+  - For each: not blank/black, has cinematic visual quality (composition, lighting visible).
+  - Shot variety check: compare consecutive frames — do they look like different shot types?
+  - Mood consistency: do the visuals match the described tone? (dark film should look dark, etc.)
+- Extract audio → STT. Compare against all `- script "..."` lines. ≥85% match.
+- Check total silence: are there any gaps in the audio track >3s? If yes, note as evidence of intentional silence.
+
+### 3. Report
+
+Severity: `blocker` (missing acts, blank frames, no narrative arc) · `major` (same shot type repeatedly, over-narration, no silence, generic prompts, no inciting incident, duration >20% off) · `minor` (VO slightly long, minor timing, font choice)
+
+Output exactly this JSON:
+
+```json
+{
+  "verdict": "PASS | FAIL",
+  "measured": {
+    "duration_s": 0,
+    "target_s": 0,
+    "resolution": "",
+    "stt_match_pct": 0,
+    "scene_count": 0,
+    "shot_types": ["wide", "medium", "close-up", "POV", "establishing"],
+    "silence_moments": 0
+  },
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "blocker | major | minor",
+      "scene": "<scene name or 'global'>",
+      "check": "<which rule>",
+      "issue": "<what is wrong>",
+      "evidence": "<source line / frame path / STT excerpt>",
+      "fix_hint": "<one-line suggestion>"
+    }
+  ]
+}
+```
+
+`PASS` requires zero `blocker` and zero `major` findings.
+
+# Task template
+
+```
+Review a serious short film against its template and narrative structure requirements.
+
+film_md: {film_md}
+mp4: {mp4}
+template_md: {template_md}
+duration_min: {duration_min}
+language: {language}
+tone: {tone}
+film_type: {film_type}
+
+Follow your procedure. Use whisper-cli (whisper.cpp) for STT if python whisper is unavailable. Save frames under a review directory. Pay special attention to narrative arc completeness and shot variety. Output the verdict JSON only.
+```

package/skills/markcut/docs/templates/short-film/prompts/fix.md

@@ -0,0 +1,29 @@
+# Prompt: Apply Reviewer Findings
+
+> Fill every `{placeholder}`, then execute in your own context.
+
+---
+
+Apply the reviewer findings below to `{film_md_path}` with minimal, targeted edits.
+
+Reviewer findings (JSON):
+
+{findings_json}
+
+Rules:
+- Address every `blocker` and `major` finding. Minor when trivially fixable.
+- Missing dramatic arc → add inciting incident scene, midpoint shift, or darkest moment as needed.
+- Too much VO → convert some VO scenes to purely visual (remove script, let image + music tell the story).
+- Same shot type repeatedly → alternate wide/medium/close-up across consecutive scenes.
+- Blank frames → check `src:auto` prompts for sufficient detail; add composition, lighting, and mood.
+- Low visual variety → mix shot types, camera movements, and lighting across scenes.
+- No silence → add a 3-5s silent scene or extend a pause in an existing scene (remove audio, let image breathe).
+- Duration off → adjust scene durations proportionally. Shorten VO lines or add transitional scenes.
+- Missing act transition → add fade-to-black transition scene between acts.
+
+After editing, list what changed:
+```
+- <finding id>: <scene> — <one-line description>
+```
+
+Then re-render and re-review.

package/skills/markcut/docs/templates/short-film/prompts/screenplay.md

@@ -0,0 +1,101 @@
+# Prompt: Screenplay — Three-Act Structure
+
+> Fill every `{placeholder}`, then execute in your own context.
+> Produces a scene-by-scene narrative plan with character arc, shot suggestions, and VO lines.
+
+---
+
+You are writing a {duration_min}-minute {film_type} short film in a {tone} tone.
+
+Concept: **{concept}**
+
+Source material: {source_material}
+Language: {language}
+Voice(s): {voices}
+
+## Requirements
+
+### Three-act structure
+
+| Act | Function | Duration | Scenes |
+|---|---|---|---|
+| Teaser | Mood establisher, no context | 30–90s | 1 |
+| Act 1 — Setup | Character, world, inciting incident | 90s–2min | 3 |
+| Act 2 — Confrontation | Rising action, midpoint, darkest moment | 3–5min | 4–5 |
+| Act 3 — Resolution | Climax, falling action, resolution | 90s–2min | 3 |
+| Epilogue | Emotional close | 30–60s | 1 |
+
+### Protagonist rules
+- The protagonist must have a **desire** that drives the plot.
+- The **inciting incident** must happen by the end of Act 1.
+- The **midpoint** in Act 2 must shift the protagonist from reacting to acting.
+- The **darkest moment** must occur just before the climax.
+- The **climax** is where the protagonist confronts the central conflict — emotionally, not necessarily physically.
+- The **resolution** shows the new ordinary — how the protagonist has changed.
+
+### Scene format
+For each scene, provide:
+
+```
+### Act X.Y — Scene Title (INT/EXT. LOCATION - TIME)
+- Shot type: <wide/medium/close-up/POV/etc>
+- Camera movement: <static/push-in/handheld/etc>
+- Lighting: <golden hour/moonlight/neon/etc>
+- Mood: <one word>
+- Color palette: <cool/warm/desaturated/etc>
+- Visual prompt: <one-sentence TTI prompt with shot, subject, lighting, mood>
+- VO/Dialogue: <narration line or character dialogue>
+- Duration: <seconds>
+- Sound: <score/ambient/silence>
+```
+
+### VO rules
+- VO is minimal. The story is told through images.
+- One VO line per scene (max two). Each 10–30 words.
+- For dialogue, mark speaker: "JOHN: I never thought..."
+- No exposition dumps. Show, don't tell.
+
+## Output format
+
+```
+Title: <title>
+
+Logline: <one sentence>
+
+### Synopsis (3 sentences)
+1. <Beginning>
+2. <Middle>
+3. <End>
+
+### Teaser
+- Scene: <description>
+- Visual: <prompt>
+- VO: <line>
+- Duration: <s>
+
+### Act 1 — <title>
+
+#### Scene 1.1 — <name> (<location>)
+- Shot: <type>
+- Camera: <movement>
+- Lighting: <description>
+- Color: <palette>
+- Visual: <prompt>
+- VO: <line>
+- Duration: <s>
+- Sound: <note>
+
+#### Scene 1.2 ...
+...
+
+### Act 2 ...
+
+### Act 3 ...
+
+### Epilogue
+- Visual: <prompt>
+- VO: <line>
+- Duration: <s>
+
+Total estimated duration: <sum>
+```

package/skills/markcut/docs/templates/short-film/prompts/storyboard.md

@@ -0,0 +1,54 @@
+# Prompt: Scene → Markcut Shot
+
+> Fill every `{placeholder}`, then execute in your own context.
+> Run once per scene from the screenplay. Produces the exact markcut markdown for ONE scene.
+
+---
+
+You are turning one scene of a {tone} short film into markcut markdown.
+
+Film: {film_title}
+Scene from screenplay:
+
+{screenplay_scene}
+
+## Rules
+
+### Visual prompt
+Write a detailed TTI prompt with ALL of these elements:
+1. **Shot type**: wide, medium, close-up, POV, over-the-shoulder, Dutch angle, establishing
+2. **Subject**: who or what is in the frame, what are they doing, what emotion
+3. **Composition**: where is the subject in the frame, foreground/background
+4. **Lighting**: specific light source and quality
+5. **Camera movement**: static, push-in, handheld, tracking, pan, tilt
+6. **Color palette**: warm, cool, desaturated, high contrast, etc.
+7. **Mood**: one word or short phrase
+8. **End with**: ", cinematic, film still, 4K, highly detailed"
+
+### Narration / dialogue
+- One `- script "..."` node containing the VO or dialogue line.
+- For dialogue: `"CHARACTER: line"`
+- Match the exact text from the screenplay.
+
+### Duration
+Match the screenplay's specified duration ±2s. Adjust if the VO line is longer/shorter.
+
+### Effect
+- `effect:fadeIn` for soft opens
+- `effect:zoomIn` for dramatic reveals or tension building
+- `effect:zoomOut` for reveals of context
+- No effect for static, contemplative scenes
+
+### Sound note (optional)
+Add a comment in the script or a separate note about sound design for this scene.
+
+## Output format for ONE scene
+
+```
+### <Act>.<Scene> — <Title> (<Location>)
+layout:parallel
+- image src:auto
+  prompt:"<SHOT TYPE> of <SUBJECT>, <COMPOSITION>, <LIGHTING>, <CAMERA MOVEMENT>, <COLOR>, <MOOD>, cinematic, film still, 4K"
+  duration:<s> effect:<effect>
+- script "<VO or dialogue>" duration:<s>
+```