flomotion 0.2.0 → 0.4.0

package/skills/flomotion-studio/references/copywriting.md

@@ -0,0 +1,64 @@
+# Copywriting rules
+
+Only use facts the person gave you. Every claim needs a source or is removed. Write for the ear and the eye: short, concrete, one idea.
+
+## Hard limits
+- Headline beat: <= 6 words (8 hard max). Captions: <= 12 words per scene. Quote: <= 14 words (trim with ellipsis only if the person approves).
+- One idea per beat. Verbs over adjectives. No jargon the audience would not say.
+- Reading speed: <= 3 words/s for on-screen text.
+- Never write superlatives you cannot prove ("best", "fastest", "#1") unless the person supplies the source.
+
+## Hook types (offer 3 options at G1)
+| Type | Pattern | Example (invented product "Northwind Notes") |
+|---|---|---|
+| Curiosity question | "Is X changing how Y?" typed in a field | "Why do meetings still end with no notes?" |
+| Bold claim | Short declarative | "Notes write themselves." |
+| Number | Concrete figure + unit | "3 hours back every week." (only if sourced) |
+| Pain image | Visual, 0-3 words | A pile of tabs; text "Too many tabs…" |
+| Relatable moment | Human behavior, funny | Someone typing notes with a phone in their mouth |
+| Trend fact | "As X becomes the norm…" | "As meetings move online…" |
+
+## Pain scripts
+- Pain flavors (vary them): too many tools / lost context / wasted time / risk / confusion / cost.
+- Pattern: "Too many ___…" then a second flavor "___ is lost." then the thesis.
+- Keep each pain beat to 3-5 words. The last pain line is calm, not shouting.
+
+## Turn and promise
+- Turn line (<= 6 words): "It's time to ___." or "So we built ___." or "Meet ___."
+- Promise (<= 8 words): "Simple, secure ___." / "One place for ___." / "___ that just works." State the benefit, not the feature.
+
+## Sentence-splitting (pattern 11)
+Write one sentence of 12-20 words, then split it at natural breaths into 3-5 scenes of 2-6 words each. Read it aloud: it must still scan as one sentence. Keep the same baseline or position logic so the eye follows. Example: "As meetings move online, / the way we / take notes / needs to change."
+
+## Template + word swap (pattern 10)
+Choose one frame and swap one word: "A new era of ___" with `speed`, `focus`, `clarity`. Keep timing identical; change only the keyword and the background token.
+
+## Emphasis
+- Key word in the contrast color (the look's `accent` or white on a block).
+- Lead-in lines dimmer than the payoff word.
+- Never emphasize more than one word per beat.
+
+## Proof lines
+| Type | Pattern |
+|---|---|
+| Credential | "First to be [certification]." (only if true and sourced) |
+| Number | "[number] [unit] [outcome]" + `source` |
+| Customer | Quote + name, role, company (permission required) |
+| Scale | "Helping thousands of companies" only with a verified count |
+
+## CTA
+- One action, imperative: "Try it free." / "Book a demo." / "See it live."
+- URL in the look's body font at >= caption min size; hold >= 1 s.
+- No more than one URL and one button.
+
+## Voiceover
+- Aim 2.0-2.8 words/s. Leave breaths at beat boundaries.
+- Voice leads: write the VO, then set on-screen text as keywords from it (not a transcript).
+- Match on-screen emphasis to the stressed word of the VO.
+
+## Checklist before showing a script
+- [ ] Every headline <= 6 words
+- [ ] Every number has a source in the brief
+- [ ] Pain, turn, promise, proof, CTA all present (or flagged missing)
+- [ ] No invented names, quotes, stats
+- [ ] Reads well aloud in the planned duration

package/skills/flomotion-studio/references/decision-tables.md

@@ -0,0 +1,80 @@
+# Decision tables
+
+Go top to bottom. First match wins; then check the "avoid" column.
+
+## 1. Style family
+
+| Brief signals | Pick | Avoid |
+|---|---|---|
+| Security, compliance, risk, trust; serious audience | S1 Metaphor Contrast | Playful looks |
+| Many customer quotes or strong claims; little UI footage | S2 Typographic Color Blocks | If no quote permissions |
+| Product consolidates tools; pain is the story; >= 45 s | S3 Pain-to-Calm Line | Under 30 s |
+| Product exists because of a market shift; calm B2B | S4 Trend-to-Product | No believable trend fact |
+| Strong UI; screenshots or recordings available | S5 Real-UI Demo | UI unreadable at size |
+| Creation tool for non-experts; playful; people footage | S6 Human Story to Prompt | No footage rights |
+| Abstract/technical product that can become an object | S7 3D Object Explainer | No 3D capacity (use S2) |
+| Not sure | S5 if UI exists, otherwise S2 | |
+
+## 2. Look
+
+| Mood/tone | Look |
+|---|---|
+| Calm, credible, light | `clean-light` |
+| Premium, focused, dark/AI | `dark-product` |
+| Energetic, loud, young, creation | `bold-kinetic` |
+| Brand colors given | Build from brand (see `looks.md`) |
+
+## 3. Length / template
+
+| Platform / goal | Length |
+|---|---|
+| Social ad, cold audience | 15 s (hook-led) or 30 s |
+| Landing page, product intro | 30 s |
+| Launch / explainer / pain-heavy | 45 s |
+| Under 15 s | Cut the pain; hook + product + CTA |
+
+## 4. Format
+
+| Platform | Format |
+|---|---|
+| Reels, TikTok, Shorts | 9:16 |
+| YouTube, website hero | 16:9 |
+| Feed (square) | 1:1 |
+| Feed (portrait) | 4:5 |
+
+## 5. Pain strategy
+
+| Situation | Strategy |
+|---|---|
+| Product replaces many tools | S3 (tangle -> calm) |
+| Fear/risk | S1 (image of risk) |
+| Everyday annoyance | S6 (relatable moment) |
+| Outdated way | S7 (old way small and grey) |
+| No clear pain | Trend fact (S4) or UI demo (S5) |
+
+## 6. Proof strategy
+
+| Available | Use |
+|---|---|
+| Certification/credential | `ProofCredential` text card |
+| A metric with a source | `StatCounter` |
+| Named customer quote with permission | `Quote`/`QuoteCard` |
+| Many logos with permission | `LogoStrip`/`ProofMosaic` |
+| Nothing | Skip proof; do not invent. Strengthen demo instead; flag the gap |
+
+## 7. Hook type
+
+| Audience state | Hook |
+|---|---|
+| Problem-aware | Pain image or pain claim |
+| Curious / skeptical | Typed question |
+| Solution-aware | Bold promise or number |
+| Cold | Relatable human moment |
+
+## 8. Voice
+
+| Situation | Voice |
+|---|---|
+| Person supplies recording | Use it; transcribe; align animation |
+| Generated voice wanted | Quote cost first (confirm-gated) |
+| No voice | Captions are the voice; text must pass reading speed check |

package/skills/flomotion-studio/references/interview.md

@@ -0,0 +1,145 @@
+# Interview protocol (Gate 0)
+
+Do not start designing until the interview is complete. A video built on guesses is the main cause of bad output. You interview **extensively and adaptively**: many rounds, short batches, follow-ups on vague answers, a read-back at the end. The person should feel that you understood the product and the audience before a single frame exists.
+
+## Rules
+1. **Batches of 3-5 questions per message.** Never a wall of 20. Prefer multiple-choice (use the ask-user-question tool when available, with 2-4 options and a free-text escape) and open questions where you need their words.
+2. **Adapt.** Each answer decides the next questions. Skip what is already known. Dig where answers are vague ("modern", "clean", "powerful" are not answers: ask "like what? show me one you like").
+3. **Follow up on every vague or surprising answer** at least once. Ask for an example, a number, a source, or a screenshot.
+4. **Quote their own words back** when you summarize. Their phrases become the copy raw material.
+5. **Track state.** Maintain `interview.md` in the project: for every field a `value`, a `source` (`user`, `asset`, `assumption`), and a `status` (`confirmed`, `assumed`, `unknown`). Show the clarity score after each round.
+6. **Never invent.** If they do not know a fact, record `unknown`, never fill it. Claims need sources.
+7. **Offer a way out.** For any question the person can say "skip", "you decide", or "I don't know". Record `assumed` with your proposed default and ask them to confirm it at the read-back.
+8. **Detect contradictions** (e.g. "calm and premium" + "fast cuts, loud") and ask which wins.
+9. **Be respectful of time.** Show progress ("Round 3 of about 6, 82% clear"). Offer a pause point after each round.
+10. **Language**: ask in the person's language and level. No jargon unless they use it.
+
+## Clarity score
+Count must-have fields (below) that are `confirmed` or `assumed-and-approved`. Score = confirmed / total must-haves. **Proceed to G1 only at >= 90% and after the read-back is approved.** Nice-to-have fields never block.
+
+### Must-have fields (28)
+Product name; one-sentence what it does; who uses it (primary audience); job-to-be-done / pain; the single desired action after watching; one-sentence promise (their words); top 1-3 features to show; primary proof (or explicit "no proof"); platform; format (9:16/16:9/1:1/4:5); length; tone (one primary); brand colors (or "free to choose"); fonts (or "free to choose"); logo available (y/n); screen assets available (y/n and what); footage available (y/n); music preference (or "free"); voice plan (own/generated/none); language; CTA text and URL/button; words/claims to avoid; legal lines required; competitors to avoid resembling; at least one liked reference (or explicit "none"); at least one disliked reference (or "none"); deadline/priority; who approves; revision tolerance.
+
+## Rounds (adapt order; skip when known)
+
+### Round 0: What is set up, and what they will supply (before anything else, one short message)
+Call `setup_status`. Tell the person, in plain words, what this machine can do and what is missing (FFmpeg, Chrome, no Freesound key, no ElevenLabs key, no Whisper). Then ask how they want to supply four things; none needs a service key:
+1. **Voiceover:** their own recording, a generated voice (ElevenLabs, paid, always quoted first), or none.
+2. **Word timings:** a transcript or captions file they already have (SRT, VTT or JSON), or Whisper on this computer, or ElevenLabs returns them with the voice.
+3. **Sound effects:** their own sound files (a folder or a few files), Freesound, or both.
+4. **Graphics:** their logo and brand files, screenshots of their product (or a public URL we can capture, with their permission), their website for brand colours and fonts; icons and stock photos can be pulled from open sources.
+If they want a service, tell them to run `flomotion setup` in a terminal (keys are saved on their computer and never pass through the chat). Never ask them to paste a key here. Record the answers in `interview.md`.
+
+### Round 1: The product, in their words
+Ask:
+- What is it, in one sentence, as you'd explain it to a friend who has never heard of it?
+- Who uses it, and what are they doing right before they open it?
+- What painful thing does it replace or fix? What happens if people do nothing?
+- What is the single most impressive thing it does?
+- What do people usually get wrong or doubt about it?
+Follow-ups: "Can you give a real example from a user?" "What number could we put on that?" "What did they use before?"
+
+### Round 2: The audience and the moment
+- Who is the buyer and who is the user (same person?)
+- Where will they watch (feed, website, demo call, event)? On mute?
+- What do they already believe about this category? What are they tired of?
+- How aware are they: do they know they have the problem, or must we show it?
+- What would make them stop scrolling, in their language?
+Probe: a typical day, the trigger event that makes them look for a solution.
+
+### Round 3: The goal and the action
+- After the video, what exactly should happen (sign up, book, share, buy)? One action.
+- Is there a metric or deadline attached (launch date, campaign)?
+- Is this cold traffic or warm (existing leads)?
+- What is the offer (free trial, demo, discount)? Any terms that must show?
+- CTA text and destination (URL, code, button)?
+
+### Round 4: Message, features and proof
+- What is the one sentence you want viewers to remember?
+- Pick up to 3 features to show. For each: what does the user see and do, and what is the result?
+- Which feature is the "wow"? Which should be skipped even if it is great?
+- Proof: numbers (with source and date), certifications, customer names and quotes (with permission), logos you may show, press, awards.
+- Anything you are not allowed to claim?
+Probe: "If a skeptic asked 'prove it', what would you show?"
+
+### Round 5: Assets
+- Logo (vector?), brand guide, colors, fonts, existing videos, screenshots, screen recordings, footage, product photos, voice recordings, music you own.
+- Their website or app URL: may we read its brand (`brand_extract`) and take screenshots of it (`asset_capture`)? Only with their yes. Pages behind a login: they take the screenshots and we import them (`asset_import`).
+- Their own files can be anywhere on their computer: ask for the path and import (`asset_import`, `voice_import`, `sound_import`); the tools state what rights they assert, so ask "are these yours, or licensed to you?".
+- Customer or partner logos ("works with Slack"): brand logos are trademarks. Ask whether they have permission or the brand's guidelines allow it; otherwise use a plain wordmark in text.
+- Anything the viewer should never see (private data, real customers)?
+- Can we show real UI or must it be mocked? Is the UI recent?
+- Language(s) and any non-Latin text? Accessibility needs (captions required)?
+Ask for the files; list what arrived and what is missing.
+
+### Round 6: Taste (the "looks and feels" round)
+- Three adjectives for how it should feel; three for how it must not feel.
+- Show me 1-3 videos or sites you like and tell me what you like about each (specific moments, not "it's nice"). Same for 1-2 you dislike.
+- Light or dark? Quiet or loud? Fast or slow? Minimal or rich?
+- **Style probe**: describe the style families (from `styles.md`) in plain words and show a one-line example of each; ask them to pick top 2 and rank. Use previews where the tool supports them.
+- **Look probe**: offer 3 palette+type directions from `looks/` as short descriptions (or preview frames if rendered); ask for a pick and what to change.
+- Motion taste: smooth and calm, snappy and punchy, playful and bouncy?
+- Typography taste: big and bold, light and elegant, technical and mono?
+Probe on vague words: "modern" -> which brand, which feature of it?
+
+### Round 7: Voice, sound and music
+- Voiceover or text-only? Whose voice (own, generated)? Accent and gender preference, pace. If it is their own recording: where is the file, and do they have a transcript or captions for it (any format)? A line-level caption file is enough for captions; word-level (Whisper, ElevenLabs, a caption tool) is needed to start things exactly on a word.
+- Music mood (examples of artists/tracks for *mood only*), instrumental only?
+- Sound design appetite: subtle clicks, punchy impacts, none?
+- Pronunciation of the brand name and key terms.
+Reminder: say that sounds are chosen from licensed sources and you will ask them to audition.
+
+### Round 8: Constraints, risks, process
+- Words/phrases to avoid; compliance or legal lines; competitor names allowed or not?
+- Required elements (logo placement, disclaimer, URL, hashtag).
+- Platform rules to respect (no flashing, caption requirements, length limits).
+- Who approves and how fast? How many revision rounds are expected?
+- Deadline, delivery format (mp4, webm, social cutdowns), versions needed (extra formats, languages)?
+- Budget notes: paid voice allowed? Stock footage allowed?
+
+### Round 9: Gaps and sanity (adaptive)
+Ask only what the state shows missing or contradictory:
+- Resolve contradictions (calm vs loud, premium vs playful).
+- Fill any must-have still `unknown`.
+- Ask for the **one thing you would regret if the video missed it**.
+- Ask what would make them say "this is exactly it".
+
+## Read-back (mandatory)
+Write a one-page summary in their words and show it:
+1. Product, audience, pain (their phrases quoted)
+2. Goal and CTA
+3. Message and top features
+4. Proof available (with sources) and proof missing
+5. Format, length, platform
+6. Taste: adjectives, do/don't, chosen style family and look direction, references liked/disliked
+7. Voice, sound, language, and how each is supplied (their recording and transcript, their sound files, generated, Freesound)
+8. Constraints and risks
+9. **Assumptions I am making** (each with a default you can accept or change)
+10. **Open items** (what I still do not know and how I will handle it)
+
+Ask: "Is anything wrong, missing, or something you would never say?" Fix and re-confirm. Save as `brief.md` (schema: `dataset/brief-template.md`) and `interview.md` (full log).
+
+## Question quality bank (use these probes when an answer is thin)
+- "Can you give me a concrete example?"
+- "What would a skeptical customer say?"
+- "What is the number behind that, and where does it come from?"
+- "What does the screen show at that moment? Can I see it?"
+- "Who would hate this version, and why?"
+- "If we could only keep one sentence, which one?"
+- "What did the last video you made get wrong?"
+- "What does the competitor do that you do not want to resemble?"
+- "How would your best customer describe this in one line?"
+
+## Do not
+- Ask more than 5 questions at once; ask things you can read from supplied files; ask the same thing twice; lead the person to a style they have not chosen; accept "whatever" for must-haves without recording an explicit assumption and getting it approved at the read-back.
+
+## Unattended or no-answer mode
+If nobody can answer: fill `assumed` values from the decision tables, label every one in the brief, produce a **short** concept (not the full build), and stop at G1 with the list of questions you would ask. Do not run paid steps.
+
+## Interview log format (`interview.md`)
+```
+Round 3 — Goal and action  (clarity 71% -> 79%)
+Q: After the video, what should happen? | A: "Book a demo" | status: confirmed
+Q: Terms of the offer? | A: unknown (they will check) | status: unknown
+Follow-up: ...
+```

package/skills/flomotion-studio/references/looks.md

@@ -0,0 +1,45 @@
+# Looks
+
+A **look** is a data file that fixes every visual decision so scenes cannot drift. Files live in `looks/<name>.md`. Never use colors, fonts or easings that are not in the active look.
+
+## Token spec
+
+Each look file (`looks/<name>.md`) is a set of tables with these sections. Example values are from `clean-light`:
+
+| Section | What it fixes | Example |
+|---|---|---|
+| Palette | `bg`, `surface`, `text`, `textMuted`, `accent`, `signal`, `positive`, `negative`, `blocks` (flat scene colours) | bg #F6F7FB, accent #4B5CFF |
+| Type | `display`, `body`, `mono` (family, weights, tracking, line height), scale (hero, title, body, caption), case | Inter Tight 700-800, tracking -0.02 |
+| Motion | easing (enter, exit, move, spring), speed, stagger, blur on motion, signature transition | enter expo.out, card-slide |
+| Surface | radius, shadow, glass | radius 28, soft shadow |
+| Texture | grain, gradient | grain 0.04 |
+| Sound | palette, music mood, impact style | soft-click, air-whoosh |
+| Do / Don't | the look's rules in plain words | one accent per scene |
+
+Rules:
+- Font families must be from the font ledger (Google Fonts/Fontsource or user-supplied). Check glyph coverage for every character used.
+- `blocks` colors are used for flat scene backgrounds in S2/S7; each scene uses exactly one.
+- Dark looks must pass contrast on `text` vs `bg` at 4.5:1 minimum.
+
+## Starter looks (original palettes; replace after direction notes)
+
+| Look | Mood | Use with styles | Signature |
+|---|---|---|---|
+| `clean-light` | calm, credible | S1 (after turn), S4, S5 | pale bg, white cards, one blue accent, soft shadows, card-slide |
+| `dark-product` | focused, premium | S1 (before turn), S3 (AI half), S7 (black beats) | near-black bg, violet accent, mint signal, glow edges |
+| `bold-kinetic` | energetic, confident | S2, S6, S7 | flat saturated blocks, heavy display type, hard cuts, burst |
+
+## Creating a new look
+
+Do **not** do this unless the person provides direction notes. Ask for:
+1. Three adjectives for the feel.
+2. Colors or fonts they like and dislike (links or screenshots).
+3. Brand colors and fonts if any (they override).
+4. Light or dark, calm or loud.
+5. One reference video they like (for pattern analysis, not copying).
+
+Then: propose palette (with contrast checks), font pairing (from ledger), easing set, signature transition, sound palette. Render 3 style frames (G3). Save as `looks/<name>.md`. Log in `CHANGELOG.md`.
+
+## Brand override
+
+If the person has brand colors/fonts: map them to `accent`, `bg`, `text`, `display` and rebuild the rest of the tokens around them so contrast and scale rules still pass. Note any brand color that fails contrast and propose the nearest passing shade.

package/skills/flomotion-studio/references/mcp-tools.md

@@ -0,0 +1,70 @@
+# flomotion MCP tools
+
+The server (`flomotion mcp --dir <project folder>`) exposes these 39 tools and 4 resources. They are the real list (checked by a test against the server). You call them by bare name; your client may prefix them with the server name you registered.
+
+Every write returns `{ description, patches, undoToken }`. The undo token is a history snapshot id: `history_restore {id}` puts the file back. Every write snapshots first, so you can always go back. Errors come back as `{ error: { code, message, fix } }`: read the `fix` and act on it; do not retry the same call.
+
+## Phase map
+
+| Phase | Tools (in order) | Notes |
+|---|---|---|
+| Setup | `setup_status` | First call of every video. Says which keys are set (never the keys), what is installed, what each job can use, and what is missing. The person adds keys with `flomotion setup` in a terminal; you never ask for a key in the chat. |
+| Project | `project_create {name, size:"1080x1920", fps, template:"blank"\|"saas-promo", look, duration}`, `project_read {path?, depth?}` | `look` is a look id: `clean-light`, `dark-product`, `bold-kinetic` (the skill's looks) or the engine's `kinetic`, `minimal`, `sketch`. `saas-promo` scaffolds six empty beat scenes (30 s); for other lengths use `blank` and write the scenes from the storyboard. `project_read` shows the outline and the `ui` address when the live view is on. |
+| Look and fonts | `font_list`, `font_get {id}` for each look font, `font_check {text, fontId}`, `font_preview {fontId, text, size}`, `font_search` | `font_get` downloads, locks the hash and writes the ledger; a new family name is added as a `<Font>`. Renders never use the network. `font_search` needs `GOOGLE_FONTS_API_KEY`. |
+| Script | (no tool) | Write `brief.md`, `script.md`, `storyboard.md`, `LOG.md` with your normal file tools in the project folder. The live view reads them. |
+| Style frames | `scene_write` (key scenes), `lint`, `frame_render {time, scale?}`, `contact_sheet {times?\|count?}` | G3. Read the PNGs: describe what you see. |
+| Build | `scene_write` per scene (or `element_add` / `element_set` / `element_remove` / `element_move` / `effect_add` / `keyframe_set` / `edit`) | `lint` after each scene. `references/block-recipes.md` has the 13 core blocks as TSX. |
+| Own material | `voice_import {source, transcript?}`, `transcript_import {audio, source\|text}`, `sound_import {source, rights, tag?}`, `asset_import {source, rights}` | The person's own recording, transcript or captions, sound files, logos, images and video, from anywhere on their computer. They state their rights; the tools record them in the ledger. |
+| Assets | `asset_search {query, kind}`, `asset_get {ref, color?, permission?}`, `asset_capture {url, permission}`, `brand_extract {url, permission}` | Icons, brand logos, emoji, photos, illustrations; screenshots of their product; their site's brand. See `assets.md`. |
+| Voice | `voice_quote {provider, text, voice, model?, voiceSettings?}` (energetic read on eleven_multilingual_v2: stability 0.3, similarity 0.8, style 0.55, speed 1.1, speakerBoost true; free ElevenLabs plans cannot use Voice Library voices through the API, only premade ones) then, after the person's yes, `voice_generate {quoteId, confirm:true}`; `transcribe {audio}` for a recording | Providers: `recording` (their file, free), `local-tts` (macOS `say`, a timing draft), `elevenlabs` (paid). ElevenLabs returns word timings itself; for a recording run `transcribe` and read the words against the script. |
+| Align | `align_to_voice {voiceId, mapping:[{id, word, edge?, prop?, offset?}]}` | Starts elements on spoken words. Do this after the voice exists. |
+| Sound | `sound_auto` (dry run, then `apply:true`), `sound_search {tag?, query?}`, `sound_get {id, tag?}`, then `element_add Sound` | Ledger entry per sound; CC0 and CC-BY only unless `flomotion.json` restricts further. |
+| Mix | `mix_preview {range?}` | Measures LUFS, true peak and where each sound's peak lands. It does not play anything. |
+| Review | `lint`, `review {checklist?, deep?}`, `contact_sheet` | Up to 3 rounds. `review` returns pass / fail / warn / manual per check and a contact sheet. |
+| Render | `render {preset:"draft"\|"social"\|"final"}` | Lint errors block it. Writes `<name>.credits.txt` and `<name>.licenses.json` next to the video. Final only after G5 approval. |
+| History | `history_list`, `history_restore {id}` | Note the snapshot id at each gate approval in `LOG.md`. |
+
+Resources: `flomotion://schema/{component}` (props, ranges, docs), `flomotion://project/outline`, `flomotion://ledger`, `flomotion://looks`.
+
+## Calling rules
+
+1. `lint` after every `scene_write`; fix errors before moving on.
+2. Prefer `scene_write` with a block recipe over many small edits; use `element_set` and `keyframe_set` for single changes. A prop written as an expression in the file cannot be changed by `element_set` (`opaque_expression`): rewrite that element with `scene_write`.
+3. Name every element (`hero-line`, `title-1`) so checks and notes can reference them. Ids are stable; `element_set` refuses to rename.
+4. Declare the hero and the turn: put the hero's id in `storyboard.md`, and add `<Marker id="turn" at="..." label="Turn" />` where the story turns. `review` item 2 finds a hero that spans four scenes; the rest of the hero and turn checks are yours.
+5. Render drafts with `preset:"draft"`; use `frame_render` for checking.
+6. Never call `voice_generate` outside the quote and confirm gate, and never `render` with `preset:"final"` before G5 is approved.
+7. When a tool fails: read the code and the fix; retry once with the fix; if it still fails, report the exact error and what you tried. Do not edit thresholds or skip a check to get around it.
+
+## Error codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `schema_violation` | Unknown component or prop, value out of range, TSX does not parse, or a lint error was introduced | Read `fix`; check `flomotion://schema/<Component>` |
+| `opaque_expression` | The target is code in the file, not a literal | `scene_write` the element |
+| `track_locked`, `overlap_rejected` | Timeline rule | Change the plan or ask the person |
+| `duplicate_keyframe`, `invalid_time` | Keyframe times collide or are not literal | Give each key its own time (a frame apart) |
+| `impure_expression` | TSX uses `Math.random`, `Date.now`, timers or fetch | Use `ctx.noise(seed, freq)` and the time `t` |
+| `asset_missing`, `license_blocked` | File missing, or a sound/font licence is not allowed | Fetch another with `sound_get` / `font_get` |
+| `quote_required` | You tried a paid step without the quote and the person's yes | Show the quote, wait, then `confirm:true` |
+| `missing_dependency` | No Freesound key, no Whisper, no ElevenLabs key | Tell the person exactly what to set up (see the manual checklist) |
+| `unknown_element`, `invalid_edit`, `path_outside_project`, `font_error`, `render_failed` | Wrong id, bad operation, path outside the folder, font file problem, render failure | Read `message` and `fix` |
+
+## Files you write (with your own file tools)
+
+`brief.md` (interview), `script.md` (beats), `storyboard.md` (block, params, durations, hero, turn, sound tags), `LOG.md` (decisions, gate approvals with snapshot ids, anything not run), `review/` (reports).
+
+Storyboard beat shape (`storyboard.md`, one `##` heading per beat; the live view's Storyboard tab reads it):
+
+```
+## 3. Turn · 7.1-10.3 s
+- Block: ProductReveal
+- Scene: reveal
+- Voice: "Meet Pulse."
+- On screen: Meet Pulse.
+- Motion: slide in from the south, the hero grows
+- Sound: move/whip peaking at 7.1 s
+- Why it works: the look stays clean-light; one hero carried across the cut
+```
+
+See `references/storyboard.md` for the full format, `ideas.md` and how the board shows what is built.

package/skills/flomotion-studio/references/motion.md

@@ -0,0 +1,68 @@
+# Motion rules
+
+All motion is deterministic: a pure function of time (no `Math.random`, no `Date.now`). Seeded noise only (`ctx.noise(seed, freq)`).
+
+## Principles
+1. **Anticipate, move, settle.** Enter fast, decelerate (ease-out), land with a tiny settle. Exit shorter and softer than enter.
+2. **Weight.** Large objects move slower with longer settles; small objects snap. Impacts add shake or thud scaled to size.
+3. **Overlap.** Stagger children by `staggerMs` (40-120 ms); never animate all at once.
+4. **Hierarchy.** The hero moves most; supporting items move less and later.
+5. **Restraint.** One primary motion per scene; secondary motion is subtle.
+6. **Rhythm.** Tie major moves to beats or voice stresses; vary scene lengths.
+
+## Easing
+- Enter: `expo.out` / `power3.out` (default). Exit: `power3.in`. Move A->B: `power3.inOut`. Playful: `back.out(1.2-1.6)` (overshoot <= 8%).
+- Never `linear` for position or scale (OK for rotation loops, progress bars, color fades).
+- Use the look's easing tokens; do not mix more than 3 easings per video.
+
+## Durations (starting values)
+| Motion | Seconds |
+|---|---|
+| Text word enter | 0.35-0.55 |
+| Card enter | 0.45-0.7 |
+| Transition | 0.25-0.7 |
+| Exit | 0.2-0.4 |
+| Camera push (slow) | 2-4 |
+| Counter | 1-1.8 |
+| Settle hold before next beat | 0.3-0.5 |
+
+## Motion blur
+- Apply by velocity with a 180° shutter, sub-frame samples 4-8. Blur while moving, crisp at rest. Skip blur on text at rest and on tiny UI.
+
+## 8-direction entrance
+Directions: `n, ne, e, se, s, sw, w, nw`. Distance 8-14% of the frame (text) or full off-screen (cards). Alternate directions across items (e.g. from left, then right) for rhythm; keep one dominant direction per scene.
+
+## Impacts (use sparingly, on beats)
+- Shake: `shake = amp * exp(-decay*t) * noise1D(t*freq, seed)`. Typical `amp` 6-18 px, `decay` 8-14, `freq` 14-24.
+- Thud (scale kick): `thud = amp * exp(-damping*t) * cos(2*pi*freq*t)`. `amp` 3-8%, `damping` 9-14, `freq` 5-8.
+- Place at the sound's `peak` frame. Max one impact per 1.5 s.
+
+## Transitions (when to use)
+| Transition | Use for | Notes |
+|---|---|---|
+| Hard cut on beat | Same-color scene lists | Pair with a click |
+| Color-block wipe | S2, S7 | Next scene's bg color wipes in |
+| Match-cut wipe (split) | S1 turn | Align shared geometry centers |
+| Wedge/spike wipe | S3 turn | Follows the motif head |
+| Shape morph | S4, S5 | Blob/circle becomes next element or logo |
+| Card slide | Clean looks | Cards slide + settle |
+| Glow wipe | Dark looks | Soft light sweep |
+| Zoom through | Device to UI | Scale 1 -> 3 with blur then crossfade |
+
+Rules: <= 1 transition type per 3 scenes except hard cuts; duration 0.25-0.7 s; never default crossfade for everything.
+
+## Camera
+Slow push-in (3-8% over the scene) on pain/static shots; perspective tilt for devices (8-18°); parallax between 2-3 depth layers (offsets 4-12%). No handheld shake unless the look defines it.
+
+## Hero continuity
+Declare `hero` in the storyboard (line, circle, object, logo-color). It appears in every scene or every second scene, keeps its shape logic, and transitions (Bridge) carry it. A hero that changes style mid-video is a defect.
+
+## Text animation menu (rotate, do not repeat in a row)
+Per-word slide-up with mask; per-letter stagger (for 1-2 words); scale-in with overshoot; typewriter with caret (for queries); karaoke highlight; strike with scanline; swap (old word slides out, new in); cropped giant type that slides across.
+
+## Do not
+- Animate everything at once.
+- Use the same entrance for more than 3 consecutive elements.
+- Use ease-in for entrances.
+- Let motion cover text that must be read (hold at least 0.4 s).
+- Add motion that is not motivated (explainable in one line).

package/skills/flomotion-studio/references/patterns.md

@@ -0,0 +1,45 @@
+# 21 patterns (distilled rules)
+
+Each pattern: **rule**, **seen in** (ads from `catalogue.md`), **how to apply in flomotion**, **check**. Strength: S strong (3+ ads), M medium (2), W weak (1). Strength is provisional until rated.
+
+| # | Rule | Seen | Str | Apply | Check |
+|---|---|---|---|---|---|
+| 1 | One idea and one color world per scene | A B C D G | S | One block per scene; background token per scene | `look-consistency` |
+| 2 | Text is the hero: large, short, six words or fewer | A B C D G | S | `Title` size >= headline min; words <= 6 | `text-words`, `min-size` |
+| 3 | Include a visible **turn**: look changes when problem becomes solution (dark->light, tangled->calm, question->answer, grey->color) | A C F G | S | `Turn` marker at storyboard; change palette or space at that beat | `turn-present` (warn) |
+| 4 | Product appears in the second half, simplified or stylized | A C D E G | S | Product blocks after the turn; skeleton or stylized UI by default | `product-after-turn` |
+| 5 | Brand arrives late or is built from the motion | A B D G | S | Logo reveal via shape assembly or morph | `logo-late` |
+| 6 | Proof is specific: a number, credential, or a named person | A B D | S | Proof block with real, supplied fact only | `proof-sourced` |
+| 7 | One recurring motif ties the scenes (a line, circle, object, palette) | A C G B | S | Declare `hero` in storyboard; carry it across blocks | `hero-continuity` |
+| 8 | Motion blur while moving, crisp when landed | C D G | S | Blur by velocity (180° shutter); settle sharp | `blur-on-motion` (info) |
+| 9 | Grain on gradients so flat color feels textured | C D | M | `Grain` overlay 3-8% on gradient scenes | `grain-range` |
+| 10 | One template repeated with a word swap | B C | M | Reuse a block, vary only text/color; keep timing identical | `template-reuse` (info) |
+| 11 | Split one sentence across several scenes | C D G | S | `SentenceSplit` helper: one sentence, N scenes, one shared baseline | `sentence-split-ok` |
+| 12 | Glass or frosted UI over real footage for context | D E | M | `GlassUI` over `Footage` with backdrop blur | `contrast` |
+| 13 | Shapes act as transitions and logo births | B D G A | S | `ShapeMorph`, `WipeMatchCut`; logo from shapes | `transition-count` |
+| 14 | Modular cards, not one big screenshot | A B C | S | `CardGrid`, `OrbitCards`; each card one idea | `text-overlap` |
+| 15 | Footage becomes the UI (same clip reused in product) | F | W | `FootageToUI` block | none |
+| 16 | Cursor name tags show collaboration | F | W | `CursorTag` | none |
+| 17 | Gesture callouts with touch ripple and bubble | G | W | `GestureCallout` | `min-size` |
+| 18 | Alternate black and a saturated color for rhythm | G C | M | Alternating bg tokens every 1-2 beats | `look-consistency` |
+| 19 | Glossy 3D props around text (render, keep deterministic) | G C A | M | `Scene3D` props; limit to 3-5 objects | `determinism` |
+| 20 | Burst backgrounds mark impacts | G | W | `Burst` radial dashes on impact frame | `sound-on-impact` |
+| 21 | Show the old way **small and grey**, the new way **big and colored** | G C A | S | `OldWay` block (muted) then product block (saturated) | `turn-present` |
+
+## Pain handling rules (from A, C, G, F)
+- Pain is shown, not described: image (A), tangled motif (C), clutter windows (G), relatable human moment (F).
+- Pain share by style family: metaphor contrast 10-20%, pain-to-calm 40-50%, trend explainer 0-10% (implied), real-UI demo 0%, 3D object 20-30%.
+- When pain takes more than 25% of runtime, vary its flavor each scene (apps, tools, questions) so it never repeats.
+- End pain with a short, calm line (C: "It's time to kill sprawl.").
+
+## Persuasion arc (works with every style family)
+1. **Hook** (0-3 s): curiosity question, bold claim, or pain image. Motion from frame 0.
+2. **Pain / context** (variable): why now or why it hurts.
+3. **Turn** (a moment): the look changes.
+4. **Promise** (one sentence): plain words. ("Simple and secure data rooms.")
+5. **Product** (2-3 features max): show, do not explain.
+6. **Proof**: specific number, credential, or named customer.
+7. **CTA**: brand lock, one line, URL or button.
+
+## What not to copy
+Logos, footage, music, UI screenshots, slogans, the exact color-per-customer palette of any ad, specific icons, names. Build equivalents from the look and the person's own assets.

package/skills/flomotion-studio/references/review.md

@@ -0,0 +1,56 @@
+# Review protocol
+
+Two properties are tracked separately.
+- **Floor**: never broken or amateurish. Mostly automatic (`checks.md`).
+- **Ceiling**: feels designed. Needs the person's taste; you prepare, they judge.
+
+## Your review loop (before showing any draft)
+1. `lint` the project. Fix errors.
+2. `contact_sheet` at: frame 0, hook peak, last pain frame, turn, product, proof, CTA, final frame, plus every 2 s.
+3. **Read the frames as images.** For each: is the text readable, inside the safe area, not overlapping? Is anything cut off? Is the hero visible? Write what you see in one line per frame.
+4. `review` (all checks). Fix every HARD; fix WARN where cheap; explain WARN left.
+5. Scan `anti-patterns.md`.
+6. Repeat up to 3 rounds. If still failing, show the draft with the failure list and your plan. Never hide a failure.
+
+## What to present with a draft
+1. Draft video (reduced size) + contact sheet.
+2. Check table: counts, HARD list (should be empty), WARN list with reasons.
+3. Anti-pattern scan: items found and fixed.
+4. Hero and turn: where they are in time.
+5. **Needs your review** (things only a human can judge): look feel, font pairing, sound choices, music mood, voice tone, any brand-sensitive claim.
+6. The one decision you need.
+
+## Human rating rubric (1-5, the person fills in)
+| Dimension | 1 | 3 | 5 |
+|---|---|---|---|
+| Hook | Ignorable | Fine | Stops me instantly |
+| Story clarity | Confusing | Understandable | Obvious in one watch |
+| Visual polish | Looks templated/broken | Clean | Looks designed by a pro |
+| Motion quality | Jerky or flat | Smooth | Has weight and rhythm |
+| Typography | Hard to read | OK | Confident, readable |
+| Sound | Distracting | Neutral | Adds punch and feel |
+| Look consistency | Drifts | Mostly consistent | One coherent world |
+| Would I post this | No | With edits | Yes as is |
+
+Targets (initial): average >= 4.0 per dimension on >= 8 of 10 test briefs; all HARD checks pass within 3 rounds.
+
+## Using the ratings
+- Any dimension averaging < 3.5: find the cause (see table), change the system at the right level, rerun evals.
+
+| Weak dimension | Likely cause | Fix at |
+|---|---|---|
+| Hook | Static open, weak line | Hook block defaults, `copywriting.md` hook types |
+| Story | Missing turn/promise | Story template, `turn-present` |
+| Polish | Cluttered or default easing | Look tokens, anti-patterns |
+| Motion | Same easing everywhere, no overlap | `motion.md`, stagger, blur |
+| Typography | Small, low contrast | `min-size`, `contrast` thresholds |
+| Sound | Misplaced peaks, mood | Sound palette, placement |
+| Consistency | Mixed tokens | `look-consistency`, tighten looks |
+| Would post | Combined | Look at free-text notes |
+
+- Keep a change only if ratings or pass rates do not get worse across the 10 briefs. Record in `CHANGELOG.md`.
+
+## Honesty rules
+- Say "I measured" or "I saw in frame X"; never "it looks great".
+- If a render, tool or check did not run, say so.
+- If you changed a threshold or skipped a check, say so and why.

package/skills/flomotion-studio/references/script-craft.md

@@ -0,0 +1,59 @@
+# Script craft: an engineered, catchy script
+
+A script that holds attention is built, not inspired. Use these in order; each rule has a reason and a test.
+
+## 1. The hook (0-3 s): pattern interrupt + a promise
+
+- **Contrast:** two short sentences that flip ("Stop editing videos. Start describing them."). The first names what they do now, the second the better way.
+- **Direct address:** "you", imperative verbs. No "welcome to", no brand name yet.
+- **Open a loop** the end will close: the prompt typed in the hook comes back rendered in the CTA.
+- Test: read only the first 2 seconds aloud. Would a stranger scrolling stop?
+
+## 2. The pain (3-7 s): rule of four, staccato
+
+- Four one-word beats on the beat grid ("Timelines. Dragging. Exporting. Again."). Each word is its own hard cut and colour; the last word is the sting.
+- Name the *verbs of the old way*, not feelings. Specific beats generic.
+- Test: could a competitor's ad use the same words? Then they are too generic.
+
+## 3. The turn: a visual metaphor, silent
+
+- A short silent beat with a motion metaphor (two dots merge, split and grow into the next slide). The audio drops out, then lands the product on the drop.
+- Test: remove the voiceover; can you still see the story turn?
+
+## 4. The promise: name + one line
+
+- "Meet <name>. <One concrete line>." The line is a fact about the product, not a benefit adjective ("One TSX file.").
+- Match-cut the turn into it (a vault door opening on the circle the dots grew into).
+
+## 5. The proof: specific, true, checkable
+
+- Numbers only from the repo or the brief, and each one verified before it is on screen (39 tools from `tools/list`, 17 checks from `review`).
+- Rule of three for features ("Licensed. Logged. Locked."); each word lands on its spoken beat.
+- Never claim what you cannot show or measure. If a claim cannot be checked, cut it or rewrite it as something that can ("Diff it like code" instead of "same video every time").
+
+## 6. The reveal and the CTA
+
+- **Reframe:** one line that changes how they saw the film ("This whole ad is one TSX file.").
+- **Callback:** close the loop opened in the hook.
+- **One action, one command:** `npx flomotion`. Hold it for at least 1 s.
+
+## Timing and voice
+
+- 128 bpm: one beat = 0.46875 s, 64 beats = 30 s. Cuts on beats; words start on beats.
+- 2.0-2.8 words per second. A line that needs more than 1.2x speed-up is too long: cut words, do not squeeze.
+- One voice clip per phrase, placed on the beat, so the word times are exact.
+- Say tricky words phonetically in the voice text ("flow-motion", "T S X") and map them back to the display spelling in the captions.
+- Write copy that cannot be misheard: avoid heteronyms (e.g. "live" the adjective vs the verb); pick another word.
+
+## The ten-second audit
+
+1. Hook has a contrast and no brand name.
+2. Pain is four specific words.
+3. Turn works without sound.
+4. Promise is a fact.
+5. Every number is verified.
+6. Three features max, in threes of words.
+7. A reveal and a callback.
+8. One CTA.
+9. No word on screen that is not either spoken or a number.
+10. No claim you could not show.