Explainer Storyboard

---
name: explainer-storyboard
description: Turn a confirmed product or feature brief into a shootable 30–120 second explainer storyboard with a consistent entity roster. Use for explanatory product videos, not workflows, pipelines, or finished renders.
---

# Explainer Storyboard → Storyboard Agent

Create a complete, shootable explainer beat sheet as a NodeTool storyboard. Work directly through the storyboard and entity capability modules. Do not build a workflow or run a pipeline. Do not render stills, clips, or assemble a timeline unless the user asks.

## Truthful brief

Collect these facts before creating a board: product or feature, brand and traits, category, audience, core problem, shift, 2–4 concrete mechanism steps, proof assets, CTA, runtime (30, 60, 90, or 120 seconds), platform, tone, mandatory content, and forbidden claims. The core problem, shift, and mechanism are required. Never invent a capability, integration, metric, screen, or customer. Write `[CLIENT INPUT NEEDED]` wherever proof is not confirmed.

## Resolve entities before beats

Every recurring person, location, product UI, device, metaphor object, brand mark, and visual style is an entity. Start with `list_entities`; reuse user-provided references and existing entities before generating anything. A real product screenshot is a `prop` reference and must never be regenerated.

Resolve a style entity first. Generate only missing references, applying that style before generating each other entity. A typical 60-second explainer has 4–7 entities: style, persona, optional location, product UI prop, and metaphor prop. Label generated UI as a mock.

Use `create_entity` with a dense visual descriptor. The descriptor specifies the exact recurring appearance: character features and wardrobe; location materials and lighting; UI layout, palette, typography, and content boundaries; metaphor geometry and material; or style medium, palette, lighting, and lens. An entity id is the asset id supplied to `create_entity`.

## Teaching arc

Compute timecodes from the selected runtime, rounded to 0.5 seconds. Use this arc:

| Beat | Runtime share |
| --- | --- |
| Problem | 0–15% |
| Stakes | 15–25% |
| Shift | 25–40% |
| Mechanism 1 | 40–55% |
| Mechanism 2 | 55–68% |
| Outcome / proof | 68–82% |
| CTA | 82–93% |
| Sign-off | 93–100% |

For 30 seconds, combine problem and stakes and use one mechanism beat. For 90–120 seconds, use at most three mechanism beats. Use one concept and one literal metaphor. Put the visual aha at the shift-to-mechanism boundary and leave a deliberate half-beat of silence after it. Voice-over must be at most `runtime × 2.2` words.

## Deliverables

Produce, in order: three concept directions with a recommendation, the full beat sheet, and an entity roster with id, kind, descriptor summary, and referenced beats. Each direction states its entry problem, metaphor, aha, fit, risk, and referenced entities.

For every beat include timecode, teaching job, framing, visual, action, visible entities, verbatim VO, on-screen text of five words or fewer, exact UI/demo input and output or `NONE`, sound, music, transition, and why it teaches. Mechanism beats must show the real UI or a labelled mock. Brand marks wait until the shift. Use verbs in VO and nouns on screen. The sign-off echoes the opening problem.

## Persist the board

Create the storyboard with `create_storyboard({ name, brief, style, aspect_ratio })`. Use `board.storyboard_id`. Put the complete brief, chosen direction, and entity roster into `brief` so the project can be reconstructed later.

Attach roster ids with `edit_storyboard({ storyboard_id, ops: [{ op: "set_board", entity_ids }] })`. `set_board` is the entity operation; `set_entities` does not exist. Add one shot per beat with `edit_storyboard` and an `add_shot` op. The dense `action` field names the teaching job, visible entity names in brackets, on-screen text, and UI demonstration. Every named entity must exist, and every external generation prompt must apply the ids for every entity visible in that shot.

Stop after the planned board unless the user explicitly requests rendering or a cut. Report the directions, chosen board, and entity roster.