hyperframes/skills/faceless-explainer/phases/scriptwriting/guide.md

Core Principles

The video narrative is independent from the input text's layout. An article / brief / set of notes is an information dump; a video is a guided act of understanding.

• Scene sequence comes from narrative design, not from the input text's paragraph order.
• A text may run intro -> background -> detail -> detail -> caveat -> conclusion; a video may run hook -> question -> concept -> mechanism -> example -> takeaway, or setup -> tension -> turn -> resolution -> lesson, or promise -> step -> step -> step -> payoff, depending on the structure.
• Reorder, merge, omit, or compress the source text as needed. Strip the asides; surface the spine. The single most common failure is paraphrasing the article in order — do not do that.
• The input text is the source of information, not a story template.

The planning standard: write the emotional beat alongside the structural type, name the specific rhetorical / clarity technique (do not merely write "explain the idea"), and specify a transition for every seam. What carries the viewer's eye from scene N to scene N+1 is part of the story itself, not something to defer to the visual phase.

Pick the Style Preset (you choose it; it sets the whole look)

This workflow does not hardcode a preset. Read the input, pick one of the 5 shipped presets, emit it as the top-level stylePreset in narrator_scripts.json, and match the narration register to it. The deterministic design-system step runs right after you return and builds the entire visual system from your choice — so stylePreset is the single lever that sets the film's look. There is no inference.json to read at this phase (design-system has not run yet); your choice is the register signal. Default to pin-and-paper when nothing clearly fits.

stylePreset	Look	Pick it when the topic is…	Register
pin-and-paper	Yellow field-notebook paper, hard ink offset shadows, hairline ink — warm, handmade, considered (default)	reflective, educational, notes-like, humane — safe for almost any	warm, plain, considered; no hype
block-frame	4px solid ink borders, hard black offset shadows, saturated pastel cycle — bold, poster-like, punchy	confident, energetic, declarative; bold claims, "loud" explainers	crisp, confident, declarative
capsule	Universal pill geometry, soft low shadows, Didone serif + grotesk — rounded, modern-editorial, friendly	approachable, lifestyle, product-adjacent, polished	friendly, polished
scatterbrain	Cork / paper with post-its, hand-placed tilt, soft paper-lift — playful, messy-desk, brainstorm	casual, fun, ideation, list-y, "my scattered notes"	light, conversational
claude	Warm cream editorial surface, hairline elevation, ships a code-window — literary, technical-but-human	technical / dev-ish / thoughtful longform; anything that shows code	warm, plain, considered

The preset tunes the voice, not the structure: scene segmentation is driven by the input text + the structure decision below.

Explainer Structures

Before segmenting scenes, choose one explainer structure (or explicitly name a compound; see "Compound structures" below). Read its overview.md for guidance and study its samples. Do not splice phases from different structures, because each one is a complete, coherent path through understanding.

**Concept Explainer** — "what is X, and why does it matter." Open a curiosity gap, name the core concept, build understanding one layer at a time (definition -> mechanism -> implication), land a takeaway. Best for: a single idea, term, technology, or phenomenon the audience has heard of but does not truly grasp. The concept is usually named early (after the hook) and revisited at the takeaway. **How-To / Process** — "here is how to do X" or "here is how X works," as an ordered sequence of steps / stages. Best for: tutorials, workflows, recipes, pipelines, mechanisms with a clear start→finish. The core is a **3–6 step sequence on a consistent visual stage**, each step advancing one move. When a shared motif (the object being acted on, the position marker, the running tally) carries across several adjacent steps as one continuous shot, group those steps as a `continue` run (one worker, up to 3 scenes) and hint `morph`. **Listicle** — "N things about X" — a hook, then N roughly co-equal items, then a wrap. Best for: tips, mistakes, features-of-a-field, reasons, comparisons where items are parallel rather than sequential. Items are usually `cut`/`slide` between (parallel, not continuous); use `morph` only when a genuine throughline element survives from one item to the next. Rule-of-three is the strongest item count when the source allows compression. **Story Explainer** — teach through narrative: a setup, a tension or turn, a resolution, and the lesson it carries. Best for: case studies, histories, "how this came to be," cautionary tales, anything where a concrete arc makes an abstract point land. The emotional arc has real shape (calm -> tension -> turn -> relief/insight); the takeaway generalizes the story into a transferable idea.

Choosing the structure

Read the input text once, then ask:

• Is the payload one idea to be understood? → concept-explainer.
• Is the payload an ordered procedure or mechanism with steps? → how-to-process.
• Is the payload a set of parallel, co-equal items? → listicle.
• Is the payload best carried by a concrete narrative / case / history? → story-explainer.

When the text genuinely mixes modes, name a compound (below) rather than splicing. Default tie-breakers: if the text is an argument about one concept that happens to list supporting reasons, prefer concept-explainer with a listicle inner rhythm over a bare listicle. If a process is wrapped in a story (someone learns the steps the hard way), prefer story-explainer with a how-to inner rhythm.

Compound structures

Real explainers often layer structures. Pattern:

• Outer structure = macro arc the viewer rides (concept / process / list / story).
• Inner rhythm = the tactical rhythm inside the body phase. Common inner rhythms: a process rhythm (ordered steps) nested inside a concept-explainer's mechanism phase; a listicle rhythm (parallel items) inside a concept-explainer's "why it matters" phase.

Write narrativeArchetype as "<outer> with <inner>", e.g. "concept-explainer with process" or "story-explainer with how-to". The downstream visual phase reads it for pacing; a process / step inner rhythm means tighter morph / slide seams on a consistent stage and shorter scenes.

The field name is narrativeArchetype (schema-fixed). For FE it names the chosen explainer structure, not a sales archetype.

Narrative Architecture

Define each scene's role in the explanation. Every scene has five narrative fields (type, narrativeRole, keyMessage, persuasion, emotionalBeat), plus a separate transition spec:

• Type — one of the enum values hook / pain_point / product_intro / feature_showcase / benefit_highlight / social_proof / branding / cta. The enum is schema-fixed (validate-narrator.mjs enforces it), so FE repurposes these labels for teaching rather than selling. Use the mapping table below; pick the value whose downstream pacing matches the scene's job.
• Narrative Role — what this scene does in the explanation (its job, e.g. "Concretizes compound interest as a snowball rolling downhill", not "Shows a chart").
• Key Message — the one thing the viewer should walk away understanding (one sentence).
• Persuasion — a named rhetorical / clarity technique (see catalog below). "Explain the idea" / "show benefits" is a failure mode; the standard is "Analogy: tax brackets as a staircase, not a cliff" / "Progressive disclosure: reveal the formula one term at a time" / "Worked example with concrete round numbers."
• Emotional Beat — target feeling (see vocabulary below). One word or a short compound phrase (e.g. "Curiosity and clarity"). Avoid generic "positive" / "interested".
• Transition — { continuity, intent, description, sharedMotif? }, defining how this scene arrives from the previous scene. Every scene must have one, including scene 1 (use continuity: "break" + intent: "cut"). This is a narrative-layer judgment (whether the seam is continuous and what kind of connection it is), not visual implementation detail (specific ease / blur / direction is translated downstream by visual-design according to preset/palette). See Transition taxonomy below.

Type-enum repurposing (schema-fixed enum → explainer roles)

The enum values cannot change (validate-narrator.mjs enforces them; at least one scene must be feature_showcase or product_intro). Map your explainer roles onto them as follows:

Explainer role you want	Use enum type	Why this value
Hook / curiosity gap	hook	Same job: the high-leverage opening 3–5s.
Pain / problem / why-care	pain_point	The friction or gap the explanation resolves ("you've probably wondered…", "this keeps going wrong").
Name the core concept	product_intro	The "introduce the protagonist" beat — here the protagonist is the idea being named/defined.
Mechanism / step / stage	feature_showcase	A unit of the explanation's body — one move of a process, one mechanism, one list item.
Implication / payoff / "so what"	benefit_highlight	The consequence or value of understanding — what it gets you, what now becomes possible.
Evidence / example / data point	social_proof	A concrete grounding: a real number, a worked example, a citation, a comparison that proves the point.
Thesis / takeaway / principle	branding	The philosophical landing beat — the generalizable idea, the rule, the one line to remember.
Call to think / try / act	cta	The closing ask — try it, watch for it, question it, do the thing.

Use this mapping consistently. The explainer body is usually a run of feature_showcase (steps/mechanisms/items) optionally interleaved with benefit_highlight (implications) and social_proof (examples/data). At least one feature_showcase or product_intro must exist (every explainer has a body and a named idea, so this is automatic).

Hook Strategy Taxonomy

Choose one. The hook is the highest-leverage 3–5 seconds. For explainers it opens a cognitive gap or stakes:

Strategy	When to use it	Example
Shocking statistic	You have a credible data point that quantifies the stakes	"90% of plastic ever made has never been recycled."
Rhetorical question	Create an immediate cognitive gap	"Why does time seem to speed up as you get older?"
Counterintuitive claim	The truth contradicts common belief	"Adding more lanes to a highway makes traffic worse."
Pain validation	The audience already feels the confusion; say it back to them	"Everyone tells you to 'just diversify' — nobody says what that means."
Visceral metaphor	The idea is abstract and needs to become concrete / embodied	"Your attention is a spotlight, and apps are fighting over the switch."
Concept announcement	The term itself is the subject; make it memorable	"There's a word for this: the bystander effect."
Direct address / character hail	Audience is clearly defined	"If you've ever rage-quit a recipe halfway through — this is for you."
Imagine / scenario	A new perspective or thought experiment frames the whole piece	"Imagine money that loses value if you don't spend it."
Stakes / consequence	The "why care now" is a real cost or risk	"Get this one step wrong and the whole batch is ruined."

Rhetorical / Clarity Technique Catalog

Each scene's persuasion field is a named technique, not a vague intent. For explainers, the field carries how this scene makes the idea land or clear — a clarity / rhetoric mechanism, not a sales mechanism. Choose from this catalog (combine when several are active, e.g. "Analogy + progressive disclosure"):

Family	Techniques
Make-concrete	Analogy / metaphor • Concretization (abstract → tangible object) • Worked example with real numbers • Anchoring on a familiar referent
Reveal-in-order	Progressive disclosure (one term/layer at a time) • Build-up (simple case → general case) • Signposting ("first… then… finally")
Contrast	Before/after contrast • Common-belief vs reality • Comparison of two options • Counterexample (here is when it breaks)
Structure	Rule of three (triplet) • Numbered enumeration • Question→answer pairing • Frame-then-fill (state the shape, then populate it)
Evidence	Statistical proof / hard metric • Citation / source attribution • Demonstration (show the mechanism running) • Causal chain (A → B → C)
Memory & landing	Callback (return to the hook's image) • Distillation (compress to one line) • Mnemonic / coined term • Generalization (specific → principle)

When a scene's technique is not in the catalog, you may name a new one inline, but you must explain its mechanism (e.g. "Subtractive framing: define the concept by what it is not before saying what it is"). Do not write generic "explain the idea" / "show benefits."

Emotional Beat Vocabulary

emotionalBeat should be one word or a short compound phrase (e.g. "Curiosity and clarity", "Tension and recognition"). Avoid generic "positive" / "happy" / "interested." Explainers ride a comprehension arc:

Negative valley — open the gap (hook / pain_point scenes): curiosity • puzzlement • surprise • tension • concern • skepticism • recognition • intrigue

Pivot — orient (product_intro / concept-naming scenes): clarity • orientation • anticipation • focus

Build — build understanding (feature_showcase / benefit_highlight / social_proof scenes): comprehension • "aha" • confidence • fascination • foresight • momentum • conviction • delight • unease (for a caveat) • mastery

Resolution — land (branding / cta / final beats): clarity • satisfaction • resolve • inspiration • inevitability • "now I get it"

The structure pages (structures/*/overview.md) refer to these four groups by their register names — Negative valley, Pivot, Build, Resolution — so a beat-trajectory link from a structure page resolves to the matching group above.

Scenes with compound beats are often strongest, e.g. "Surprise and recognition", "Comprehension and delight". When two feelings are active, write both.

Transition Taxonomy

Every scene's transition describes how it arrives from the previous scene, using two machine fields + prose + (for morph) a shared element name:

continuity — "break" | "continue" (drives worker grouping)

The only machine consequence of continuity is grouping: prep.mjs puts adjacent continue scenes into the same scene worker (cap=3 — a continue run is up to 3 scenes). The one worker that owns a run controls every DOM in it, so it authors the visual continuity across all its scenes itself and the seams read as one continuous shot.

• continue = "same worker as the previous scene." Use it for a run of 2-3 adjacent scenes that should flow as one continuous shot — a growing diagram, a persistent object, a camera that keeps moving, a counter that advances. The worker authors the flow (and any shared-element morph) directly inside one continuous visual stage.
• break = a new worker + an inter-scene Tier-B transition (cut / slide / dissolve / zoom) injected by the harness onto the clip wrappers after assembly.
• Scene 1 is always break (there is no previous scene to continue from).

continuity is decoupled from intent (the old morph⟺continue biconditional was removed). continue no longer requires morph; it just means "keep these scenes on one worker for continuity." A continue run is at most 3 scenes (cap=3): break → continue → continue groups three scenes in one worker; a 4th consecutive scene must start a new run with a break. Use continue only where the scenes genuinely share a continuous stage — a seam that merely "feels continuous" should stay break. Many short runs are welcome: run(1,2,3) → break → run(4,5) → break → 6 → 7.

intent — 5 narrative seam intentions (not visual implementation)

Choose one of these 5. This is "narrative-level" vocabulary — it expresses what kind of connection the seam is, not blur amount / direction / duration (visual-design translates those according to preset/palette):

Intent	Narrative meaning	Pairs with (soft hint)	Downstream translation direction (visual-design decides values)
morph	One shared element transforms across scenes (the shared element is open-ended: a diagram node that becomes a chart bar, a word that becomes an icon — only examples)	continue	worker carries a shared element across the continue run (it owns the shared visual stage)
cut	Clean switch; scenes are not continuous (topic/tone shift, new list item, high-energy beat)	break	hard cut / crossfade
slide	Directional slide / push (matches narrative flow: next step, next point)	break	push-slide (direction set by visual-design)
dissolve	Soft dissolve / focus shift (enter atmosphere, emotional transition, time passing)	break	crossfade / blur-crossfade (when colors clash)
zoom	Camera pushes / scales through to the next focal point (zoom into a detail, pull back to the big picture)	break	zoom-through

continuity is decoupled from intent — intent is a soft hint. morph naturally pairs with continue (same worker carries the element); cut / slide / dissolve / zoom naturally pair with break. Nothing enforces this; choose continuity by whether the scenes share a continuous stage.

sharedMotif — optional hint (names the carried element)

Name the element / motif that carries through this seam (what morphs at the narrative layer), ≤8 words. Examples: "the running tally" / "the central diagram node" / "the timeline marker" / "the key term". Only name what it is; do not describe geometry/implementation — the downstream worker uses this as the persistent subject inside the continue run. Omit this field when intent is not morph.

What makes a good shared element (pass these three tests before choosing morph): do not invent a shared element just to have one; identify which element that already belongs in both scenes can connect them best.

• Load-bearing in both scenes: it is the visual protagonist or key information carrier in both outgoing and incoming scenes (the object the process acts on, the central diagram, the data series, the named concept's icon), not a decorative object inserted temporarily just to enable a morph.
• Naturally co-present: first ask "Is there an element that would naturally appear in both scenes?" If yes, use morph to connect it; if no, use Tier-B.
• The transformation advances the explanation: the element's morph must carry the conceptual jump (the same diagram gains a layer, the same number flows from formula into result, the same shape reorganizes from problem to solution), rather than making the explanation pause for a flashy animation.

Hint morph (with continue) when all three are true; otherwise the scenes don't share a continuous stage — use break + a Tier-B seam (dissolve / slide), which still reads clean.

description — 10–30 word visual direction (keep)

Concrete direction for downstream: what morphs/slides/dissolves, where the eye lands, and what color/shape guides it. For morph, be especially clear about the handoff point (what shape is handed to the next scene).

Why 5 intentions, not visual types: the model lets scriptwriting express only narrative intent + continuity, leaving "which exact transition + blur/direction/duration" to visual-design, which has preset/palette context. morph covers shared-element continuity inside a continue run; the rest are Tier-B between-scene transitions per the table.

Script Voice Quality Bar

Strong explainer scripts have these traits. The failure mode is reading the article aloud, or bullet-point prose.

Strong: Concretization: "Compound interest isn't addition, it's a snowball — every turn picks up the snow from the last turn, then more." — turns an abstract formula into a moving image.

Weak: Article-paraphrase in order: "The study, published in 2019, examined three cohorts and found that…" — that is reading, not explaining. Compress to the one fact that matters and lead with it.

Empty / Silent Scripts Are Allowed

When the visual itself carries the information, set script: "" and keep the scene silent. This is common and good in explainers:

• A diagram assembling itself (each part appearing on beat) — the build is the message; let it breathe.
• A worked-example animation (numbers flowing through a formula) — the motion teaches; narration would only narrate the obvious.
• A beat of held tension before the turn in a story-explainer — silence is the device.

If you set an empty script, narrativeIntent must be especially strong, because narrativeRole and persuasion must carry what the script does not say.

The Explainer Body Is a Sequence, Not a Single Scene

An explainer's core is almost always 3–6 body scenes on a consistent visual stage, each advancing one mechanism / step / item / layer, building understanding cumulatively (for connection rules, see the hard constraint below). The body runs feature_showcase / benefit_highlight / product_intro — these may interleave per the structure (a concept- or story-explainer typically goes product_intro → feature_showcase → benefit_highlight rather than 3 consecutive of one type); the only floor is the schema's ≥1 feature_showcase or product_intro. Patterns by structure:

• concept-explainer: name the concept → reveal mechanism layer by layer → land implications. The body is product_intro then a run of feature_showcase (sometimes interleaved with benefit_highlight for "so what" beats and social_proof for a grounding example).
• how-to-process: feature_showcase per step, ordered, on one stage. The object being acted on is often a genuine shared motif → pair adjacent steps with morph where the throughline carries.
• listicle: feature_showcase per item; items are usually parallel, so default to cut / slide between them. Use morph only when a real element survives item→item.
• story-explainer: scenes follow the narrative beats (setup / tension / turn / resolution / lesson); types map per the table (pain_point for tension, branding for the lesson).

A single isolated body scene rarely teaches anything. Group adjacent scenes that share a continuous stage into a continue run (continuity: "continue") — up to 3 scenes per run, all owned by one worker that authors the flow (and any shared-element morph) directly; between runs, use a break with a Tier-B transition (cut / slide / dissolve / zoom). A run is at most 3 scenes; a 4th consecutive scene starts a new run with a break. Shape: run(s1,s2,s3) -> break -> run(s4,s5) -> break -> .... Use continue only where the scenes genuinely share a continuous stage; a parallel listicle may legitimately use break throughout.

Identify a body sequence by:

• Scene type is feature_showcase, product_intro, or benefit_highlight
• narrativeRole contains words such as "Defines", "Demonstrates", "Reveals", "Walks through", "Concretizes", "Builds on"
• script advances one mechanism / step / item / layer per scene, cumulatively
• Adjacent scenes that share a continuous stage are grouped as a continue run (up to 3); between runs (and across parallel items) is a break + Tier-B (cut / slide / dissolve / zoom)

Faceless Visuals — assetCandidates is [] by Default

FE is a faceless explainer: there are no captured assets, no product screenshots, no asset inventory. Downstream (visual-design + scene workers) invents the visuals — typography, abstract graphics, diagrams, and data-viz — from each scene's narrativeRole / keyMessage / script. Both typographic/abstract treatments and diagram/data-viz treatments are first-class; downstream picks per scene by content. Your job here is the narrative, not the visual asset list.

Therefore:

• assetCandidates is [] for every scene by default. This is the normal, correct value — it tells downstream "this scene is invented from the brief."
• The only exception: the user explicitly provided a real image and placed it in public/. Then add one entry { "path": "public/<basename>", "description": "<≤25 words: what it is + visual notes>" }. Do not invent paths, do not reference capture/, do not fabricate basenames — a path to a nonexistent file is a downstream fatal.
• Do not describe the intended diagram/typography here as if it were an asset. Visual intent belongs in narrativeRole + the transition description; the visual phase reads those.

Validation Checklist

• Does every scene have complete Narrative Intent (all 5 fields)?
• Does every scene have transition — continuity (break/continue), intent (one of the 5, a soft hint), and description (10–30 words)? Is scene 1 continuity: break? Is every continue run at most 3 scenes?
• Is assetCandidates present on every scene as an array? Is it [] everywhere except where the user supplied a real public/<basename>?
• Does the emotional arc have meaningful variation (not monotone)? Does it match the structure (concept = gap → comprehension; story = calm → tension → insight)?
• Is the sequence driven by narrative, not by the input text's paragraph order?
• Is there a coherent body that builds cumulatively (a run of feature_showcase / benefit_highlight / product_intro, interleaving allowed per structure) — not a single isolated body scene? Are continue runs used only where scenes share a continuous stage, each run ≤3 scenes, separated by a break?
• Are Persuasion fields named rhetorical/clarity techniques from the catalog rather than vague "explain the idea"?
• Are Emotional beats specific (word or short compound phrase), not generic "positive"?
• Does the hook use a named strategy from the taxonomy?
• Is there only one outer structure (no splicing top-level frameworks)? Explicitly named inner-rhythm compounds are allowed.
• Is the type-enum used per the repurposing table (so the file stays schema-valid, with at least one feature_showcase/product_intro)?
• Is a top-level stylePreset set to one of the 5 shipped presets (pin-and-paper | block-frame | capsule | scatterbrain | claude)?

narrator_scripts.json: Canonical Schema

Downstream agents expect these exact field names. Wrong names (e.g. scene_id instead of sceneNumber, narration instead of script, or flattened intent fields) are fatal in validate-narrator.mjs.

{
  "project": "Project name",
  "narrativeArchetype": "Explainer structure (concept-explainer | how-to-process | listicle | story-explainer), or compound \"<outer> with <inner>\"",
  "stylePreset": "One of: pin-and-paper | block-frame | capsule | scatterbrain | claude — drives the entire visual system (default pin-and-paper)",
  "orientation": "Canvas aspect, echoed verbatim from the dispatch Orientation line: landscape (16:9, default) | portrait (9:16) | square (1:1). Dictated by the user's aspect, not chosen. prep maps it to group_spec.width/height. Omit → landscape.",
  "emotionalArc": "Comprehension journey description (e.g. 'Puzzlement at why time speeds up shifting to clarity and a small delight as memory density explains it.')",
  "scenes": [
    {
      "sceneNumber": 1,
      "sceneName": "Scene name",
      "transition": {
        "continuity": "break|continue",
        "intent": "morph|cut|slide|dissolve|zoom",
        "sharedMotif": "Only when intent=morph: name of the element carried across scenes (<=8 words, e.g. 'the running tally'); omit this key for other intents",
        "description": "10-30 word concrete visual direction explaining what morphs/slides/dissolves and where the eye should land"
      },
      "narrativeIntent": {
        "type": "hook|pain_point|product_intro|feature_showcase|benefit_highlight|social_proof|branding|cta",
        "narrativeRole": "The scene's job in the explanation (not what appears on screen)",
        "keyMessage": "What the viewer should understand after this scene (one sentence)",
        "persuasion": "Named rhetorical/clarity technique from the catalog (combine if multiple are active)",
        "emotionalBeat": "Word or short compound phrase from the vocabulary"
      },
      "assetCandidates": [],
      "script": "Plain-text narration. May include <em>/<brand>/<emph>/<cta> tags as authoring-time annotations (TTS strips them). Can be an empty string when visuals carry the information.",
      "estimatedDuration": "5-6s"
    }
  ]
}

Field rules (use exact field names above; wrong names are fatal in validate-narrator.mjs):

• Every scene must have a transition field (continuity + intent + description; add sharedMotif for morph), including scene 1 (continuity: "break" + intent: "cut"). Scene 1 has no previous scene, so its transition does not generate any transition downstream (downstream ignores it) — intent: "cut" is just a placeholder.
• continuity is decoupled from intent (a soft hint). continue = same worker (a run of up to 3 scenes); break = new worker. validate-narrator.mjs checks only enum membership + scene 1 = break.
• assetCandidates is a required field and must be an array. For FE it is [] on essentially every scene; only a user-provided public/<basename> image yields a {path, description} entry.
• narrativeArchetype names one of the four explainer structures (or a "<outer> with <inner>" compound). At least one scene must be type: feature_showcase or product_intro.

Captions (not owned by scriptwriting)

Do not write a captions: string[] field. <em>/<brand>/<emph>/<cta> tags inside script are stripped by TTS; whether you include them does not drive downstream visuals.