@lalalic/markcut 2.0.0 → 2.2.0

package/AGENTS.md

@@ -188,6 +188,7 @@ node src/render/cli.mjs templates
 - `--label` flag starts a labeling UI for selecting and annotating media
 - `--port` flag sets the server port (default 3001)
 - Unified server: `server.mjs` serves all modes (preview, edit, label). React control components in `components/`.
+- **Persistent AI agent via `pi --mode rpc`** (one cold start, many edits): at boot, `startAgentProcess()` spawns the configured agent CLI (`DEFAULT_AGENT_CLI`) with `--mode rpc` appended (the `-p/--prompt` flag is stripped — prompts arrive over stdin). Each `/api/edit` POST writes `{"id","type":"prompt","message"}` to stdin and resolves on the streamed `agent_settled` event (NOT idle-timeout guessing — pi's default interactive mode is a TUI, not a stdin REPL, so text/stdin mode does not work). Assistant text is collected from `message_end` events (`message.role==="assistant"`, text content blocks). `--session-id` (derived from the file path) resumes conversation history from disk across restarts. Do not revert to one-shot `spawn` per edit — that re-incurs the full cold-start every request.
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"

package/{SKILL.md → skills/markcut/SKILL.md}

@@ -8,10 +8,10 @@ description: use markdown to describe stream trees, provide CLI to render stream
 Everything video is a **stream tree** described with markdown. see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
 
 
-## video design utitlies
+## Video Design Utilities
 
 ### User labels — label media with text, time ranges
-- `uvx @lalalic/markcut preview --label` provides tool to label video and images with text.
+- `npx @lalalic/markcut preview --label` provides tool to label video and images with text.
 
 ### Storyboard — plan video structure with scene nodes
 
@@ -24,6 +24,10 @@ see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full detail
 - define variants for different video configurations, such as different languages, aspects, platforms
 
 
+### Templates
+- Templates in ``docs/templates/`` provide ready-to-use video structures for `orchestrator` agents, use them as starting point to create your own videos.
+
+
 ## 3. CLI
 
 ```bash
@@ -50,6 +54,8 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Markdown descriptive format (primary authoring format) | [docs/markdown-descriptive.md](docs/markdown-descriptive.md) |
 | Label system (browse, label, export labels.json) | [docs/label-mode.md](docs/label-mode.md) |
 | Player servers (label + edit mode) | [docs/edit-mode.md](docs/edit-mode.md) |
+| How to make video template | [docs/template.md](docs/template.md) |
+| Templates | [docs/templates/](docs/templates/) |
 
 
 ## common used components

package/{docs → skills/markcut/docs}/system-prompt-edit.md

@@ -12,5 +12,8 @@ TASKS:
 1. Read the .md file directly using your file tools to see its current content
 2. Edit the .md file directly — change content, add/remove sections, update frontmatter
 3. Save the changes to the .md file using your write/edit tools
-4. Output ONLY a one-line summary of what specific change you made
-5. Do NOT output explanations, reasoning, or extra text
+4. Output ONLY a JSON object on a single line:
+   {"summary":"what specific change you made","fileChanged":true}
+   - `summary`: short description of the change
+   - `fileChanged`: true if you edited the file, false if no change was needed
+5. Do NOT output any other text, explanations, or reasoning — only the JSON line

package/skills/markcut/docs/template.md

@@ -0,0 +1,213 @@
+# Markcut Template System
+
+> How to design and build video templates that agents can follow to produce professional, consistent videos.
+
+## Why templates?
+
+Markcut templates encode **domain expertise + production polish** into a reusable package. An agent reading a template learns not just markcut syntax, but:
+
+- **What** makes a good video of this type (scene structure, pacing, rules)
+- **How** to assemble it (workflow: prompts → agents → render → review)
+- **Why** certain patterns work (production polish: transition timing, overlays, effects)
+
+## Template package structure
+
+```
+templates/<name>/
+  TEMPLATE.md          ← The single entry point. Everything except prompts & agents.
+  prompts/
+    <step>.md          ← Fill-in prompt templates. Run in the orchestrator's context.
+    ...
+  agents/
+    <name>.md          ← Subagent definitions. Run in separate, isolated sessions.
+    ...
+  example.md           ← (optional) A complete worked example.
+  example.mp4          ← (optional) Rendered output for reference.
+```
+
+### File type conventions
+
+| File | Context | Purpose |
+|---|---|---|
+| `TEMPLATE.md` | Orchestrator's context | Complete spec: inputs, structure, rules, workflow, quality gate, components, styles |
+| `prompts/*.md` | Orchestrator's context | Fill-in-the-blank prompt templates; the orchestrator replaces `{placeholder}` values and executes them |
+| `agents/*.md` | **Separate** session | Full agent definitions with system prompt + task template. Each runs in a fresh, isolated subagent session with its own tools and context |
+
+### Why separate prompts/ and agents/?
+
+- **prompts/** — tasks the orchestrator does itself (outline generation, scene writing, fix application). These run in the orchestrator's own session so they have full context of the entire project.
+- **agents/** — tasks that benefit from isolation (review, specialized generation). These run in separate sessions to avoid context pollution and to use specialized system prompts without interference.
+
+## Anatomy of TEMPLATE.md
+
+Every `TEMPLATE.md` follows this section order:
+
+```
+§0  Prerequisites       — tools, skills, environment checks
+§1  Inputs              — what the orchestrator must collect from the user
+§2  Scene grammar       — the canonical tree structure with hard rules
+§3  Authoring rules     — professional-quality bar for content (text, timing, media)
+§4  Components & styles — copy-verbatim code blocks with documented theme knobs
+§5  Workflow            — numbered steps: prompts → agents → render → review
+§6  Quality gate        — measurable exit criteria (the reviewer checks these)
+§7  Reference           — links to golden examples or related docs
+```
+
+### §0 Prerequisites
+
+What tools/skills the agent needs before starting. Always include:
+
+- The engine itself: `npx @lalalic/markcut` runnable
+- Required markcut skill (`SKILL.md` + `docs/markdown-descriptive.md`) — the agent must read these
+- Required CLIs: `edge-tts`, `ffmpeg`/`ffprobe`, whisper, image-understanding (for reviewer)
+- Any domain-specific tools
+
+### §1 Inputs — the contract with the user
+
+A table of what the orchestrator must collect before starting. Each row:
+
+| Input | Required | Default | Notes |
+|---|---|---|---|
+
+**Rule:** never invent content beyond given material + well-established knowledge. Missing or ambiguous inputs → ask the user, never fabricate.
+
+### §2 Scene grammar — the tree shape
+
+The backbone. Show both:
+
+1. **An ASCII tree diagram** of the required structure with layout/transition annotations
+2. **Concrete code blocks** showing the exact node structure for each scene type
+
+Hard rules come here: number of scenes, layouts, transitions, `isBackground` usage, timing rules, etc.
+
+**Crucial design principle:** make the tree as explicit as possible. Show node types, `id:` values, `on:` events, positioning styles. Don't leave structural decisions to the agent.
+
+### §3 Authoring rules — the professional bar
+
+Rules the reviewer checks. Cover:
+
+- Slide/content rules (max bullets, text shape, emoji conventions, table usage)
+- Script/narration rules (pacing, per-sentence structure, example placement, tone)
+- Media rules (positioning, sizing, where media can overlay)
+- Multi-language variant rules
+- Domain-specific rules (e.g. "never fabricate facts" for courseware, "ground every line in clip captions" for vlog)
+
+### §4 Components & styles — copy verbatim
+
+The trickiest section. Two code blocks:
+
+1. **`~~~js imports` block** — all JSX component definitions the video needs. The agent copies this verbatim. Mark which parts are theme knobs (values that can change) vs structural (must stay the same).
+2. **`~~~css stylesheet` block** — all CSS. Same rules: theme knobs documented, structure immutable.
+
+In addition, a **theme knobs table** showing what the user can change (colors, fonts, sizes) and their defaults.
+
+**Best practice:** keep the component block minimal. One reusable `Slide` component is better than ten one-off components. Use standard markcut features (`- image`, `- video`, `- component`, `- effect`) before writing custom JSX.
+
+### §5 Workflow — the orchestrator's playbook
+
+Numbered steps from start to finish. Each step is one of:
+
+- **Fill a prompt** — "Fill `prompts/outline.md` → course outline. Present to user for confirmation."
+- **Run a subagent** — "Run `agents/reviewer.md` in a fresh session. Pass it these absolute paths."
+- **Execute a CLI command** — "`npx @lalalic/markcut render course.md`"
+- **User interaction** — "Get user approval before continuing."
+
+Include fix loops:
+
+> 6. **Fix loop** — on FAIL: fill `prompts/fix.md` with the findings, apply edits, re-render. Max 3 iterations, then escalate to user.
+
+### §6 Quality gate — measurable exit criteria
+
+The checklist the reviewer uses. Each item must be machine-verifiable (by reviewing source, extracting frames, running STT, measuring duration). Examples:
+
+- Total duration within ±15% of target
+- Structure matches §2 (hook, title, N concepts, summary, thanks)
+- No blank/black frames at scene boundaries
+- STT transcript matches scripts (≥90% content match)
+- Each bullet has a narration beat
+
+### §7 Reference — worked examples
+
+Link to golden example files in `tests/fixtures/templates/`. The golden example demonstrates every rule in the template applied correctly.
+
+## Production polish patterns (reusable)
+
+These are design patterns you can include in any template. They're documented in detail in the courseware template (§2.b) but summarized here:
+
+| Pattern | Technique | Use case |
+|---|---|---|
+| **Per-beat media** | `#### Beat` sub-scenes with `layout:parallel` (image + script per beat) | Courseware slides, tutorial demos |
+| **Transition-audio timing** | `start:<T>` on script nodes in `transitionSeries` | Any scripted scene with transitions |
+| **Persistent overlay** | `- image isBackground:true` at root level | Logo, watermark |
+| **Narrator PiP** | `- video/image isBackground:true` with border-radius + name label | Talking-head overlays |
+| **Entrance effects** | `effect:zoomIn` / `effect:fadeIn` on images/components | Reveal animations |
+| **Mermaid diagrams** | ` ```mermaid ` in slide markdown | Flowcharts, architecture, timelines |
+| **TTS expression** | `—` pauses, `*emphasis*`, rate adjustment, phonetic spelling | Natural speech |
+
+## Prompt design principles
+
+### prompts/*.md
+- Use `{placeholder}` values for every input. The orchestrator replaces these before executing.
+- Include constraints from TEMPLATE.md inline so the prompt is self-contained.
+- Output format should be a concrete template the orchestrator can parse and assemble.
+
+### agents/*.md
+- Must include a **system prompt** (top) and a **task template** (bottom, filled by orchestrator).
+- System prompt defines the agent's role, rules, and procedure.
+- Task template uses `{placeholder}` values for paths, params, and inputs.
+- Always mark the agent as `mode: read-only` if it shouldn't edit files.
+- Include an explicit output schema (JSON format) so the orchestrator can parse results reliably.
+- List which tools the agent needs (read, bash, ffmpeg, etc.).
+
+## Choosing prompts vs agents
+
+| Task type | Where | Why |
+|---|---|---|
+| Creative generation (write a scene) | `prompts/` | Needs full context of the project; best done by orchestrator |
+| Factual check (review) | `agents/` | Needs fresh context; strict rubric; no editing |
+| Research (find images, analyze) | `agents/` | Parallelizable; heavy tool use |
+| Outline / planning | `prompts/` | Needs user interaction (confirm outline) |
+| Quality fix | `prompts/` | Orchestrator applies edits, runs tools |
+
+## Testing a template
+
+1. **Generate** — have a model follow the template to produce a video markdown
+2. **Render** — `npx @lalalic/markcut render <output>.md`
+3. **Review** — run the reviewer agent on the rendered output
+4. **Fix** — apply fixes, re-render, re-review
+5. **Verify** — check frames visually, check STT transcript
+
+The courseware template's test loop is the reference:
+
+```
+Agent (deepseek-v4-flash + SKILL.md + markdown spec) → course.md
+└→ npx markcut render → course.mp4
+   └→ Reviewer agent (separate session) → PASS/FAIL + findings
+      └→ Fix → re-render → re-review (max 3x)
+```
+
+## Built-in templates
+All builtin templates are in `templates/` and can be used as-is or forked for your own. Each has a `TEMPLATE.md` with full instructions.
+
+## Cross-cutting concerns
+
+### Multi-language
+- Use variant blocks (`# <lang>` at file end) with per-language TTS voice.
+- Every script node has a `<lang>:"..."` twin; every slide source has a `<lang>-source` twin.
+- The engine resolves variants via `parseMarkdownVariants`.
+
+### Reviewer design
+- Always `mode: read-only` — reviewers report findings, never edit.
+- Two-phase: static (source vs rulebook) + dynamic (rendered artifact via ffprobe/ffmpeg/STT/vision).
+- Output: strict JSON with `{verdict, measured, findings[]}`. Each finding has `id`, `severity`, `scene`, `check`, `issue`, `evidence`, `fix_hint`.
+- PASS requires zero `blocker` and zero `major` findings.
+
+### The "orchestrator" role
+The orchestrator is the agent reading the template. It:
+1. Collects inputs from the user
+2. Executes prompts in its own context
+3. Spawns subagents in separate sessions for isolated tasks
+4. Assembles, renders, fixes, and iterates
+5. Escalates to the human user when stuck
+
+The template is written FOR the orchestrator. Every instruction is an actionable command: "fill this prompt", "run this agent", "render the file", "if FAIL, fix and re-render".

package/{templates → skills/markcut/docs/templates}/courseware/TEMPLATE.md

@@ -80,12 +80,129 @@ Scene rules:
 
 - **Duration is TTS-driven**: never set explicit `duration` on scenes that have a script. Only fixed-visual scenes (Hook, Thanks) get `duration:`.
 
-### make expressful slide
-- use chart to explain when making sense
-- group script and images/videos to make slide more expressful
-- select different transition
-- apply effects
-- control tts with emotion,breaks, speed for natural speech
+### Production polish — optional enhancements
+
+Once the basic structure works, add these to make the video more professional.
+
+#### A. Bullet-level media (image/video/component per bullet)
+
+Each bullet can have its own visual accompaniment that appears only during that beat. Use `#### Beat` sub-scenes inside the concept scene to group the media and script into one transition segment:
+
+```markdown
+### Commits
+layout:transitionSeries transition:fade(0.5)
+- component id:c isBackground:true jsx:"<Slide current={current}>{source}</Slide>"
+  ~~~md source
+  ## Commits
+  - 📸 **Snapshot** — Every commit records changes
+  - 🏷️ **Unique hash** — Each has an ID like a1b2c3d
+  - 🔗 **Real example** — GitHub commit history for a PR
+  ~~~
+
+#### B1-Snapshot
+layout:parallel
+- image src:snapshot.png style:position:absolute;right:60px;top:50%;width:35%;border-radius:12px;transform:translateY(-50%)
+- script "A commit is like a photograph of your project at a moment in time..." start:0.5 on:(start, c.current=1)
+
+#### B2-Hash
+layout:parallel
+- image src:unique-id.png style:position:absolute;right:60px;top:50%;width:35%;border-radius:12px;transform:translateY(-50%)
+- script "Every commit gets a unique hash, like a1b2c3d, so you can always find it later..." start:0.5 on:(start, c.current=2)
+
+#### B3-Example
+layout:parallel
+- image src:pr-history.png style:position:absolute;right:60px;top:50%;width:35%;border-radius:12px;transform:translateY(-50%)
+- script "For example, when reviewing a pull request on GitHub, each commit tells a story..." start:0.5 on:(start, c.current=3)
+```
+
+Rules for bullet-level media:
+- Position the media in the **right third** of the slide (`right:60px;width:35%`) so it doesn't overlap the left-aligned text.
+- Use `border-radius:12px` for images, `border-radius:50%` for circular narrator avatars.
+- The media node and script node are siblings in a `layout:parallel` sub-scene so they play together as one segment.
+- Each beat node name should briefly describe the visual (e.g. `#### B1-Snapshot`).
+- For **video** clips per bullet: use `- video src:...` instead of `- image src:...`. Same positioning.
+- For **component** per bullet: use `- component jsx:"<MyBulletVisual />"` with its own styling.
+
+#### B. Transition-audio timing
+
+In a `transitionSeries`, adjacent segments overlap by the transition duration (default 0.5s). Without adjustment, the next paragraph's TTS audio starts playing during the fade — creating cacophony.
+
+**Fix: add `start:<T>` to every script node in a transitionSeries, where T = your transition time.**
+
+```markdown
+- script "Paragraph..." start:0.5 on:(start, c.current=1)
+```
+
+This delays both the TTS audio AND the bullet-highlight event until after the transition completes. The transition time value must match the `transition:fade(T)` parameter.
+
+> **If using multiple transitionSeries (nested)**: segment overlap compounds. Each script still gets `start:T` relative to its own segment. The engine handles the compound timing.
+
+#### C. Persistent logo overlay
+
+Add a logo that appears throughout the entire video by placing an `- image isBackground:true` at the root level:
+
+```markdown
+# video
+width:1920 height:1080 fps:30 layout:series
+- image isBackground:true src:logo.png style:position:absolute;bottom:24px;right:24px;width:60px;opacity:0.7
+
+## Hook ...
+## Slides ...
+## Thanks ...
+```
+
+The `isBackground:true` flag wraps the image in `<Loop>` so it plays for the full video duration. Position it in a corner so it doesn't cover slide content.
+
+Variations:
+- **Bottom-left**: `bottom:24px;left:24px`
+- **Transparent watermark**: `opacity:0.3;width:160px`
+- **Animated logo**: use `- video loop isBackground:true src:logo-animated.mp4`
+- **Component logo**: use `- component isBackground:true jsx:"<Logo />"` and define `<Logo>` in the imports block for custom styling.
+
+#### D. Narrator overlay (picture-in-picture)
+
+Add a narrator's face or avatar as a persistent overlay in a corner. Two approaches:
+
+**Static image (circular crop):**
+```markdown
+- image isBackground:true src:narrator.png style:position:absolute;bottom:40px;left:40px;width:100px;height:100px;border-radius:50px;border:3px solid #61dafb;object-fit:cover
+```
+
+**Video loop (animated narrator):**
+```markdown
+- video loop isBackground:true src:narrator.mp4 style:position:absolute;bottom:40px;right:40px;width:140px;height:140px;border-radius:70px;object-fit:cover;border:3px solid rgba(255,255,255,.3)
+```
+
+**With name label (using component):**
+```markdown
+- component isBackground:true jsx:"<NarratorBox src='narrator.png' name='Dr. Smith' />"
+```
+
+The `NarratorBox` component is available in the imports block (see §4) and adds a name label + glow effect.
+
+**Placement rules:**
+- Narrator overlay goes in the **opposite corner** from the logo. If logo is bottom-right, narrator goes bottom-left.
+- The overlay should be small enough (≤140px diameter) to not distract from slide content.
+- For video narrators, keep the B-roll simple and well-lit (talking head style).
+
+#### E. Effects (entrance animations)
+
+Apply CSS keyframe animations to images and components for entrance effects:
+```markdown
+- image src:chart.png effect:zoomIn duration:1
+- component jsx:"<Counter />" effect:fadeIn duration:2
+```
+
+See markcut docs for available effect types: `fadeIn`, `zoomIn`, `bounceIn`, `slideInLeft`, `slideInRight`, `flipIn`, or custom keyframes.
+
+#### F. TTS expression control
+
+Guide TTS pronunciation for more natural speech using SSML-style cues in the script text:
+- **Pause**: use `—` (em dash) or `...` for natural breath pauses
+- **Emphasis**: capitalize key terms or use `*asterisks*` (edge-tts interprets these as emphasis)
+- **Rate**: set `tts.rate:+10%` on the root config line for faster pacing, or `tts:{"--rate +10%"}` per scene
+- **Phonetic spelling**: for jargon ("Snyk" = "snik", "Grafana" = "gruh-fah-nuh"), add parenthetical pronunciation on first use: `Snyk (pronounced "snik")` 
+- **Language mix**: for bilingual content, switch edge-tts voice per language using the `# <lang>` variant block
 
 ## 3. Authoring rules — the professional bar
 
@@ -105,6 +222,7 @@ Narration script:
 - The concrete example gets its own bullet and its own script paragraph. Never bury the example in a generic paragraph.
 - Bullet ordering: concepts first (what/why), example last (concrete reinforcement). The example is the final beat before advancing to the next scene.
 - Summary: each row in the comparison table gets one beat. The final beat closes the course ("Thank you for watching…").
+- **Transition-audio timing**: in a `transitionSeries`, add `start:<transitionTime>` to each script node to prevent TTS audio from playing during fade transitions (see §2.b).
 
 Mermaid diagrams:
 
@@ -155,7 +273,7 @@ export function Mermaid({ source }) {
       })
   }, [source])
 
-  return (<divref={ref}style={{ width: '100%', maxWidth: 960, margin: '20px auto' }}/>  )
+  return <div ref={ref} style={{ width: '100%', maxWidth: 960, margin: '20px auto' }} />
 }
 
 /**
@@ -164,6 +282,94 @@ export function Mermaid({ source }) {
  * - Highlights the Nth bullet when `current=N`
  * - Renders mermaid code blocks ( ```mermaid ...``` ) as inline diagrams
  */
+/**
+ * Picture-in-picture narrator overlay with name label.
+ * Place as isBackground:true at root level.
+ */
+export function NarratorBox({ src, name = '', size = 100 }) {
+  return (
+    <div style={{
+      position: 'absolute',
+      bottom: 40,
+      left: 40,
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      gap: 6,
+    }}>
+      <div style={{
+        width: size,
+        height: size,
+        borderRadius: '50%',
+        overflow: 'hidden',
+        border: '3px solid #61dafb',
+        boxShadow: '0 0 20px rgba(97, 218, 251, 0.3)',
+      }}>
+        <img
+          src={src}
+          style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+        />
+      </div>
+      {name && (
+        <span style={{
+          fontSize: 14,
+          color: '#a8dadc',
+          textShadow: '0 2px 8px rgba(0,0,0,.6)',
+          whiteSpace: 'nowrap',
+        }}>{name}</span>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Two-column layout: slide text on left, media on right.
+ * Use inside a parallel layout for per-bullet media (see §2.b).
+ */
+export function SplitSlide({ source, mediaSrc, current = 0, mediaPosition = 'right' }) {
+  const mediaContent = mediaSrc && (
+    <img src={mediaSrc} style={{
+      maxWidth: '100%', maxHeight: '100%', objectFit: 'contain',
+      borderRadius: 12, boxShadow: '0 4px 20px rgba(0,0,0,.4)',
+    }} />
+  )
+  let idx = 1
+  return (
+    <div style={{
+      display: 'flex', flexDirection: mediaPosition === 'right' ? 'row' : 'row-reverse',
+      width: '100%', height: '100%', padding: 40, boxSizing: 'border-box', gap: 32,
+    }}>
+      <div style={{
+        flex: 1, display: 'flex', flexDirection: 'column',
+        justifyContent: 'center', minWidth: 0,
+      }}>
+        <div className="slide" style={{ padding: 0, margin: 0, width: '100%' }}>
+          <ReactMarkdown remarkPlugins={[remarkGfm]}
+            components={{
+              li: ({ children }) => {
+                const highlight = idx === current; idx++
+                return <li className={highlight ? 'highlight' : ''}>{children}</li>
+              },
+              pre: ({ children }) => {
+                const code = React.Children.toArray(children)[0]
+                if (code?.props?.className === 'language-mermaid') {
+                  return <Mermaid source={String(code.props.children)} />
+                }
+                return <pre>{children}</pre>
+              },
+            }}>{source}</ReactMarkdown>
+        </div>
+      </div>
+      <div style={{
+        width: '40%', flexShrink: 0,
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+      }}>
+        {mediaContent}
+      </div>
+    </div>
+  )
+}
+
 export function Slide({ current = 0, children }) {
   let idx = 1
   return (
@@ -293,6 +499,9 @@ Prompts in `prompts/` are fill-in templates: replace every `{placeholder}`, then
 1. **Outline** — fill `prompts/outline.md` → course outline. **Present the outline to the user and get confirmation** before continuing.
 2. **Scenes** — for each outline section, fill `prompts/scene.md` → slide source + narration script (all languages).
 3. **Assemble** — write `course.md`: §2 grammar, §3 rules, §4 blocks verbatim, root config line with the user's width/height/fps/voice.
+   - **Basic**: standard bullet-reveal pattern (one scene, one Slide component, N script nodes per scene).
+   - **With per-bullet media**: use `#### Beat` sub-scenes in `transitionSeries` for each bullet (see §2). Each beat is `layout:parallel` containing the image + script. Add `start:0.5` to each script node.
+   - **Overlays**: add persistent logo/narrator as `- image isBackground:true` at the root level.
 4. **Render** — `npx @lalalic/markcut render course.md`. On engine errors: fix and re-render, max 3 attempts per error, then ask the user.
 5. **Review (quality gate)** — run `agents/reviewer.md` in a fresh separate session. Give it absolute paths to: `course.md`, the rendered MP4, this `TEMPLATE.md`, plus target duration and language(s). It returns `{verdict, findings[]}` and never edits anything.
 6. **Fix loop** — on FAIL: fill `prompts/fix.md` with the findings, apply the edits yourself, go back to step 4. Max **3** review iterations, then escalate to the user with the open findings.
@@ -306,9 +515,10 @@ Done only when ALL hold:
 - [ ] structure matches §2 (hook, title, 3–6 concepts, summary, thanks)
 - [ ] no blank/black frames at scene boundaries; slides legible at target resolution
 - [ ] STT transcript of rendered audio matches scripts (≥90% content match)
-- [ ] each bullet should be narrated
-- [ ] expressful slides applied
-- [ ] 80% slides have charts/image/...
+- [ ] each bullet has a narration beat — beat count = bullet count in every concept scene
+- [ ] ≥80% of slides include a visual element beyond text-only bullets (chart, image, diagram, mermaid)
+- [ ] overlays (logo, narrator) positioned without obstructing slide content
+- [ ] no TTS audio plays during transitions (checked via `start:` offset on transitionSeries scripts)
 
 
 

package/{templates → skills/markcut/docs/templates}/courseware/prompts/outline.md

@@ -24,6 +24,7 @@ Requirements:
   - one concrete example (real product, scenario, or story) — gets its own key point
   - whether the content is comparative → table (if yes, name the columns)
   - whether a mermaid diagram would help (flowchart, architecture, timeline)
+  - per-bullet **image/video suggestion** (a concrete visual that illustrates this point)
   - word budget
 - Summary: one comparison table spanning all concepts (name the columns) + a selection/decision guide ("If X → use Y").
 - Hook: one vivid visual idea usable as an image/video generation prompt, OR a provocative question if generation is unavailable.
@@ -39,6 +40,10 @@ Output format (markdown):
 - points:
   - **<key phrase>** — <elaboration>
   - ... (last point = the concrete example)
+- images:
+  - bullet 1: <description of visual — screenshot, diagram, photo, icon>
+  - bullet 2: <description>
+  - ...
 - table: no | yes (<col1>, <col2>, ...)
 - mermaid: no | yes (<type and description of diagram>)
 - words: <n>

package/{templates → skills/markcut/docs/templates}/courseware/prompts/scene.md

@@ -27,6 +27,7 @@ Produce, for language(s) {languages}:
 - `>` quote block only for a single memorable takeaway line
 - no bullet may exceed one line at 1.3em / 1920px width (~90 chars)
 - Optional mermaid diagram: add a fenced mermaid code block after the bullet list (` ```mermaid ...``` `) for flowcharts or architecture visuals.
+- **For each bullet, suggest a visual** (image, diagram, screenshot, or icon) that could accompany it. The visual should show something concrete: a screenshot, a diagram step, a photo, etc.
 
 **B. Narration script** (per language, **one paragraph per bullet**):
 
@@ -55,6 +56,11 @@ script (en):
 
 <p3: describes bullet 3 — concrete example>
 
+image suggestions:
+<bullet 1: brief description of visual — e.g. GitHub commit diff screenshot>
+<bullet 2: brief description of visual — e.g. unique hash diagram>
+<bullet 3: brief description of visual — e.g. PR timeline graphs>
+
 script (<lang>):
 <p1 translation>