Prompting
You do not write the page alone. You answer five questions and an agent writes the brief, the stills and the page.
Most films are written by agents. You describe the film. An agent asks five questions, writes a brief, shows stills, and then writes page.html. Agents in this repo read AGENTS.md, so they already know the page contract and the house rules. Your job is the vision.
Start from a template
The repo has a template per film type in prompts/. guides/ROUTING.md lists them and maps a request to one.
| Template | Use when |
|---|---|
showreel-one-liner | no brief, a taste probe |
brand-launch-from-url | a real product from a URL, with its own kit and real captures |
ui-morph-loop | one element becomes 8 to 12 UI states and loops |
reference-rebuild | a reference mp4 must be matched |
directors-brief-long-form | over 60 s, or more than one session |
story-explainer | explain a topic with invented visuals |
music-video-beat-synced | a song exists, and every cut lands on a downbeat |
beat-sheet | any film over one beat: the shot table before code |
The full index has twelve templates. Start a film from one:
bin/vawe new my-launch --from prompts/brand-launch-from-url.mdThe command prints the template's five questions, each with its default and its reason. It writes films/my-launch/brief.md with every default filled in and marked [unanswered: default taken]. A skipped answer keeps its default. Nothing blocks.
The brief has six sections
- Inputs. Five questions in the order they change the film, each with a default.
- Direction. A genre or reference anchor first. Then the feel in numbers: hex colours, type as a fraction of frame height, seconds per beat. End with a ban list.
- Structure. The beats as a table: start, length, what the viewer notices, the end state. Cuts fall on a beat or two frames early. The slowest beat is at least 3 times the fastest.
- Build. The page contract. See The page.
- Gotchas. The few things that fail on the first try.
- Start. The stills first, then a draft.
A short prompt can work. What helps most is a reference or a genre anchor, and a ban list. A default you do not exclude is free for the agent to use.
What the agent does next
The agent writes the beat table, then shows three directions as stills in directions.html. You pick one. Then it renders a draft with bin/vawe dev <page>. See the loop in Quickstart.
Inputs that raise quality
- A real product URL, crawled, not invented. See Brand reflection.
- A reference film.
bin/vawe spec <ref.mp4>measures it intoSPEC.md. Mark each line KEEP or CHANGE, then rebuild. - Real data. Numbers and copy are true and looked up, never made up for effect.
- The film type, if you know it. It saves a routing step.
What to avoid
- Do not ask for fake product UI. A screen, logo or photo in the plan must trace to a real capture.
- No em dash in on-screen copy. The validator rejects it.
- Do not name hex codes or easings to fix a weak film. Fix the anchor and the ban list.
What to say when it is wrong
Name the symptom, not the cause. "Beat three reads as a slide, nothing moves but the text" is better than "make it more dynamic". The agent can find the cause. It cannot guess what you saw.
To change direction instead of fixing a detail, change the anchor and the ban list.