flomotion 0.2.0 → 0.4.0

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

@@ -0,0 +1,57 @@
+# Sound rules
+
+You cannot hear audio. You can search, transcribe, measure levels, and place sounds on frames. Every sound choice is a **needs-your-review** item. Never write "sounds good".
+
+## Buses and targets (config/thresholds.md)
+- Buses: `voice`, `music`, `sfx`, `master`.
+- Loudness: master -14 LUFS (+/- 1), true peak <= -1 dBTP.
+- Voice stays >= 12 dB above music during speech (duck music; attack 80 ms, release 400 ms).
+- Starting bus levels: voice -3 dB, music -18 dB, sfx -10 dB.
+
+## Sound palettes by style
+| Style | Palette tags | Music mood |
+|---|---|---|
+| S1 | low-drone, tick, single-impact, air | tense to airy |
+| S2 | pop, click, whoosh-short | upbeat, light |
+| S3 | friction-texture, rise, silence, bright-resolve, short-hit | tension to bright |
+| S4 | soft-tap, pad, swell | warm, calm |
+| S5 | ui-click, ui-tick, resolve-chord | minimal |
+| S6 | ambience, marimba, pop | playful |
+| S7 | pop, clink, thud, pluck | punchy |
+
+## Placement rules
+1. Each impact effect (shake, thud, burst, hard cut on beat) gets a sound whose **peak** lands on that frame (tolerance 2 frames). Use the sound's `peak` time from the ledger.
+2. Word reveals in kinetic text: soft click or pop on the first letter's landing, not every word if > 4 per second (use every other).
+3. Transitions: whoosh starts 3-6 frames before the transition's midpoint.
+4. Product settle: soft click at rest frame.
+5. Silence is a tool: a 0.3-0.6 s drop before a turn increases impact.
+6. Music: start under the hook, rise slightly at the turn, resolve under the CTA; fade out within the last 0.5 s after the final frame's key text.
+
+## Their own sound effects
+If the person has sound files: `sound_import` (a file, or a folder up to 40 files; they state `rights`). For a big library they run `flomotion setup` and point it at the folder; then `sound_search` finds them by file and folder names. Your own sounds are searched first, then Freesound if a key is set. They are used as `local:ID`, with the same measured peak and ledger entry. Their rights are what they told you: nothing checks them, so ask "are these yours or licensed to you?".
+
+## Freesound flow (via the flomotion MCP)
+1. `sound_auto` (dry run) lists impact effects (Shake, Slam, Thud, PunchZoom...) that have no sound on their frame. Apply it, or search by hand: `sound_search` with a job `tag` (`ui/pop ui/tap ui/tick move/whip move/whoosh-deep hit/land hit/punch hit/boom tech/click tech/data tech/glass tech/success tech/glitch`) and your own query words; the server already limits to `CC0` and `CC-BY` (set `soundLicenses` in `flomotion.json` to restrict) and marks allowed results.
+2. Pick 2-3 candidates per slot; `sound_get` downloads the file (with only an API key this is the HQ MP3 preview), measures the **peak** and writes the ledger. Pass `tag` so the peak is named after the job (`hit/land` gives `peak="land"`).
+3. Place `<Sound src="freesound:ID" at="..s" peak="land" />`: `at` is where the peak lands; the clip starts early by the measured offset. The ledger holds `source`, `author`, `license`, `attributionRequired`, `commercialOk`.
+4. Never use `CC-BY-NC` for promos. Never use tracks from commercial ads.
+5. Required attributions go into the license report at G6.
+
+The palette words in the table above (low-drone, whoosh-short, ...) are style guidance for your query words. The tags the tools accept are the job tags in step 1.
+
+## Review list format (show at G5)
+```
+Sounds to audition (I cannot hear them):
+1. t=0:03.2  thud-light on "Notes" — candidate A (CC0), B (CC-BY)
+2. t=0:11.0  whoosh before wipe — candidate A
+Music: "warm-minimal" bed, 92 BPM, starts 0:00 ends 0:29.6
+Mix measured: LUFS -14.2, true peak -1.8 dBTP, voice margin 13 dB (pass)
+```
+
+## Voice
+- Own recording: `voice_import` copies it in from wherever it is. Word times: if they have a transcript or captions, `transcript_import` (SRT, VTT, word-level JSON, lines with times, or plain text). Say how exact it is: **word** (Whisper, ElevenLabs) is exact; **cue** (captions) is line-level, fine for captions, off by up to a line for a word-tied move; **estimated** (plain text) is a rough guide, so ask for captions or run Whisper before you promise sync. Otherwise `transcribe` (Whisper). `align_to_voice` snaps key times to words.
+- Generated voice: `voice_quote` first (cost, duration), wait for the person's confirm, then `voice_generate`. Language and pronunciation of brand names to be confirmed by the person.
+- No voice: captions carry the narration; ensure caption reading speed passes.
+
+## Do not
+- Stack more than 3 sfx within 1 s, place a loud sound under voice, loop obvious music seams, use clipping-level sounds, or use any audio not in the ledger.

package/skills/flomotion-studio/references/story-templates.md

@@ -0,0 +1,52 @@
+# Story templates
+
+Durations are proposals. Totals must land within tolerance of the target (`config/thresholds.md`).
+
+## 15 s (4-5 beats): hook-led
+| # | Role | Block | Seconds | Voice/text role |
+|---|---|---|---|---|
+| 1 | Hook | `Hook` or `TypedQuery` | 2-3 | Claim or question |
+| 2 | Reveal | `ProductReveal` | 3-4 | Name + one line |
+| 3 | Feature | `UIZoom`/`FeatureCallout` | 4-5 | One feature, shown |
+| 4 | CTA | `CtaCard` | 3 | Brand + URL |
+
+## 30 s (7-9 beats): standard
+| # | Role | Block | Seconds |
+|---|---|---|---|
+| 1 | Hook | `Hook`/`TypedQuery` | 2-3 |
+| 2 | Pain | `Problem` or `OldWay` | 4-6 |
+| 3 | Turn | `Bridge`/`WipeMatchCut`/`ShapeMorph` | 0.5-1 |
+| 4 | Promise | `Hook`-style statement | 2-3 |
+| 5 | Product | `ProductReveal` | 3-4 |
+| 6 | Features (2-3) | `UIZoom`/`FeatureCallout` | 8-10 |
+| 7 | Proof | `StatCounter`/`Quote`/`LogoStrip` | 3-4 |
+| 8 | CTA | `CtaCard` | 2.5-3.5 |
+
+## 45 s (10-13 beats): long
+30 s template plus: a comparison or demo beat (`BeforeAfter`/`ChatDemo`, 5-6 s) and a second proof beat (`Quote`/`ProofMosaic`, 3-4 s). Keep total pain share <= 25% unless style S3.
+
+## Variants by style family
+- **S1 Metaphor Contrast (30 s)**: Hook=`MetaphorImage` 3 -> Turn=`WipeMatchCut` 1 -> Promise 2.5 -> Reveal3D 3 -> DeviceMock 5 -> Feature 4 -> ProofCredential 3 -> `LogoCard` 3 = ~24.5 + slack for holds.
+- **S2 Color Blocks (30 s)**: `TypedQuery` 3 -> `QuoteCard` x3 (3 each) -> `LogoSwap` roll call 4 -> `CardCollage` 3 -> `ShapeLogo` 3.
+- **S3 Pain-to-Calm (45 s)**: `OverwhelmDiagram` 3 -> `MotifLine` 1.5 -> `PainFlavor` x3 (4 each = 12) -> thesis `TextSwap` 4 -> resolution 3 -> palette flip + `CardGrid` 6 -> `OrbitCards` 4 -> brand 3 = ~37; extend demo to 45.
+- **S4 Trend-to-Product (30 s)**: `KaraokeLine` 3.5 -> `FramedFootage` 3 -> `ShapePivot` 2 -> `ShapeMorph` 2 -> `CategoryLine` 2.5 -> `GlassUI` 6 -> `ProofMosaic` 3.5 -> `CtaCard` 3.
+- **S5 Real-UI Demo (30 s)**: opening claim 3 -> `BrandPill` 1.5 -> `UIZoom` x2 (4 each) -> `ChatDemo` 5 -> `StatCounter` 2.5 -> `CtaCard` 3.
+- **S6 Human Story (30 s)**: `HumanMoment` 3 -> context 2 -> `CursorTag` 2 -> `PromptUI` 5 -> `ResultReveal` 4 -> `LogoPill` 3.
+- **S7 3D Object (30 s)**: `OldWay` 3 -> `ClaimWith3D` 3 -> `GestureCallout` 3 -> `Object3D` 4 -> `WordBeat` x3 (2 each) -> `Burst` 1 -> `UrlCard` 3.
+
+## Rhythm rules
+- Something new every 2 s (element, color, camera, or text).
+- Scene length varies: never three scenes in a row with the same duration (+/-10%).
+- Put the longest scene on the product beat; shortest on the hook and the turn.
+- Leave 0.3-0.5 s of settled hold on key text so it can be read.
+- Cut on the voice's breath or on beats, not mid-word.
+
+## Format adaptations
+| Format | Layout notes |
+|---|---|
+| 9:16 | Safe areas large (top 250, bottom 380); stack text vertically; max 3 lines per headline; product devices portrait |
+| 16:9 | Horizontal flow, left-aligned text works; two-column product layouts allowed |
+| 1:1 | Center stack; fewer simultaneous elements |
+| 4:5 | Like 9:16 with smaller bottom safe area |
+
+Blocks reflow by reading the format preset; never hard-code pixel positions.

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

@@ -0,0 +1,62 @@
+# The storyboard board
+
+The live view (`flomotion ui`) has a **Storyboard** tab: a board where the person and you brainstorm, and a timeline of the plan that shows what is built. It reads two plain Markdown files in the project folder. You write them with your normal file tools; there is no MCP tool for it.
+
+| File | Who writes it | What it holds |
+|---|---|---|
+| `ideas.md` | the person (in the tab) and you | Brainstorm notes: one line per idea |
+| `storyboard.md` | you | The plan: one `##` heading per beat |
+
+## ideas.md
+
+```
+# Ideas
+
+- [ ] open on the prompt being typed, then the video builds itself (you)
+- [x] a mascot dot that reacts to each beat (claude)
+```
+
+- `- [ ] text (you)` is an open idea; `- [x]` means used or dropped. The tag is `(you)` or `(claude)`.
+- The person adds ideas from the tab; the line lands in `ideas.md`. Read the file at G1, G2 and G4, answer by adding your own `(claude)` lines (alternatives, questions, risks), and tick the ones you used.
+- Never delete the person's ideas. Tick them and say why in `LOG.md`.
+
+## storyboard.md
+
+```
+# Storyboard: <video name>
+
+Hero: flo (a dot with eyes) · Turn: the two-dots move at 7.0 s · Tempo: 128 bpm
+
+## 1. Hook · 0-3.3 s
+- Block: Hook
+- Scene: hook
+- Voice: "Stop editing videos. Start describing them!"
+- On screen: Stop editing. (struck through) Start describing.
+- Motion: the strike draws on after "videos"; the prompt types in
+- Sound: ui/type x4, hit/boom on "Start"
+- Why it works: contrast hook; the typed prompt is paid off at the end
+
+## 2. Pain · 3.3-7.0 s
+...
+```
+
+Rules:
+
+- Heading: `## <n>. <Title> · <start>-<end> s`. Seconds, on the beat grid when the video has a tempo.
+- Lines: `- Key: value`. Known keys the board shows: `Block`, `Scene` (the scene id or ids in `project.tsx`, comma separated), `Voice`, `On screen`, `Motion`, `Sound`, `Why it works`.
+- Keep one beat per idea. Words on screen: 6 or fewer per headline.
+- Write it at G4, update it when the story changes, and keep it true: the board compares it with `project.tsx`.
+
+## What the tab shows
+
+- A **strip** of the beats along the real timeline: grey = planned, green = built (every scene named in `Scene:` exists in the file), blue = Claude touched it in the last 90 seconds. Click a beat to jump the preview there.
+- A **card** per beat with the fields above; the card under the playhead is outlined.
+- The **ideas** column with an add box; ticking an idea writes `[x]` back to the file.
+- "N of M beats built" so the person sees progress without reading code.
+
+## How to use it in the workflow
+
+1. G0 to G1: the person adds ideas while you interview; read `ideas.md` before proposing directions.
+2. G2: put the script's beats into `storyboard.md` (Voice, On screen) so the person sees the story as cards.
+3. G4: fill `Block`, `Scene`, `Motion`, `Sound`, `Why it works`; the strip turns green as you `scene_write` each scene.
+4. G5: every beat should be green. A grey beat is a gap: say so in "Needs your review".

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

@@ -0,0 +1,70 @@
+# Style families (7)
+
+Pick one per video. Each recipe is a constraint: structure, design, motion, sound, blocks, risks.
+
+## S1 Metaphor Contrast
+**Use when**: the product reduces risk, chaos or anxiety (security, compliance, finance, reliability) and the audience is serious.
+**Structure**: pain image (2-3 s) -> match-cut turn (1 s) -> plain promise (2 s) -> reveal (2-3 s) -> product skeleton UI (4-6 s, desktop then phone) -> proof (2 s) -> logo (2 s).
+**Design**: two worlds (dark gritty -> white clean); one accent (lime-like signal color) used only after the turn; big left-aligned grotesque; 3D render for the metaphor object.
+**Motion**: slow push-in on pain, hard split-wipe on a shared geometry, soft settle on the reveal; perspective tilt for devices.
+**Sound**: low drone and tick (pain), single impact on the turn, clean airy bed after.
+**Blocks**: `MetaphorImage`, `WipeMatchCut`, `Promise`, `Reveal3D`, `DeviceMock`, `ProofCredential`, `LogoCard`.
+**Risks**: needs a metaphor object that has matching geometry on both sides; if none, pick S3.
+
+## S2 Typographic Color Blocks
+**Use when**: you have customer quotes or short claims; the tone is confident and human; little product footage.
+**Structure**: curiosity hook (typed query) -> 3 to 5 quote or claim cards (2 s each) -> customer roll call -> UI collage (2 s) -> logo built from shapes.
+**Design**: one flat color per scene from the look palette; giant geometric sans, letters cropped at edges for scale; key word in the contrast color; attribution lockup.
+**Motion**: type-as-UI gestures (cursor selection box, magnifier sweep), fast cuts on beat, hard stops.
+**Sound**: pop/click on word reveals, soft whoosh on cuts, light upbeat bed.
+**Blocks**: `TypedQuery`, `QuoteCard`, `LogoSwap`, `SpotlightWord`, `CardCollage`, `ShapeLogo`.
+**Risks**: quotes must be real and approved; never invent customer names.
+
+## S3 Pain-to-Calm Line Story
+**Use when**: the product consolidates tools or simplifies a mess (workspaces, integrations, ops, analytics).
+**Structure**: overwhelm diagram (2 s) -> motif intro (1 s) -> three pain flavors (3 s each) -> calm thesis (3 s) -> resolution line (2 s) -> palette flip + product card wall (6-8 s) -> brand (2 s).
+**Design**: monochrome thin pain half; saturated grained gradient solution half; one motif (line or thread) present in every scene; grey->black text for emphasis.
+**Motion**: motif sweeps with speed streaks; wedge wipe at the turn; cards fly with motion blur; template reuse "A New Era of ___".
+**Sound**: rising friction texture during pain; silence before the turn; bright resolve and short impacts for cards.
+**Blocks**: `OverwhelmDiagram`, `MotifLine`, `PainFlavor`, `QuestionBubbles`, `TextSwap`, `StrikeText`, `CardGrid`, `OrbitCards`, `VersionBadge`.
+**Risks**: long. Only use at 45 s or when pain is truly central. Motif must be deterministic (spline with fixed seed).
+
+## S4 Trend-to-Product Explainer
+**Use when**: a market shift explains why the product exists; calm, credible B2B; an audience that already knows the trend.
+**Structure**: agreeable fact (word-highlighted sentence, 3 s) -> implication around a framed image (3 s) -> "we built" pivot with shapes (2 s) -> name via morph (2 s) -> plain category line (2 s) -> glass UI over context footage (5 s) -> scale proof mosaic (3 s).
+**Design**: one saturated brand color + pale tint; light-weight type, generous space; footage in clean framed rectangles.
+**Motion**: karaoke word highlight, shapes close in and out as punctuation, blob pinch to wordmark.
+**Sound**: warm pad, soft taps on word highlights, one low swell at "we built".
+**Blocks**: `KaraokeLine`, `FramedFootage`, `ShapePivot`, `ShapeMorph`, `CategoryLine`, `GlassUI`, `ProofMosaic`.
+**Risks**: needs real or licensed footage; a believable trend line you can source.
+
+## S5 Real-UI Demo
+**Use when**: the UI itself is the product's strength and you have good screenshots or a screen recording.
+**Structure**: human voice or bold claim (3 s) -> brand pill (1.5 s) -> UI crop 1 (4 s) -> UI crop 2 or dashboard (4 s) -> AI/automation chat request and result (5 s) -> outcome number (2 s) -> CTA (2 s).
+**Design**: close crops with soft shadows, pastel gradient background, glass pill for brand, saturated status cells as the visual signature.
+**Motion**: empty cells fill via circle-to-cell morph; staggered row reveal with blur-in; zoom to the element that matters; cursor with click ripple.
+**Sound**: soft clicks, UI ticks, a gentle resolve chord on completion.
+**Blocks**: `Spokesperson` (optional), `BrandPill`, `UIZoom`, `CellFill`, `ChatDemo`, `StatCounter`, `CtaCard`.
+**Risks**: UI must be legible at target size; blur out private data.
+
+## S6 Human Story to Prompt
+**Use when**: the product is a creation tool for non-experts; tone playful; relatable moment exists.
+**Structure**: funny human moment (3 s) -> wide context (2 s) -> collaboration cue with cursor tag (2 s) -> product as a simple prompt using the same footage (5 s) -> result (3 s) -> logo + product pill (2 s).
+**Design**: warm real colors in footage; product UI in clean white with one purple-like accent; script or friendly logotype overlay.
+**Motion**: match the footage rhythm; typing animation in the prompt box; footage thumbnails fly into the UI.
+**Sound**: kitchen/room ambience, playful marimba, soft UI pops.
+**Blocks**: `HumanMoment`, `CursorTag`, `PromptUI`, `FootageToUI`, `ResultReveal`, `LogoPill`.
+**Risks**: needs footage with people (license or the person's own). If none, use S2 or S7.
+
+## S7 3D Object Explainer
+**Use when**: the product is abstract or technical and can be made into a friendly object (wallet, vault, hub, pipe).
+**Structure**: old way, small and grey windows (3 s) -> color flip, one big friendly claim with 3D prop (2 s) -> gesture demo (3 s) -> object metaphor with items sliding in (3 s) -> short word beats ("one X", "drag", "a X you'll love") (6 s) -> URL on black (2 s).
+**Design**: saturated brand color alternating with black; big lowercase geometric sans; glossy 3D props; burst graphic.
+**Motion**: object tumbles in with settle; props orbit; burst of dashes on impact; touch ripple on gestures.
+**Sound**: pops and coin-like clinks, bass thud on the burst, bright pluck bed.
+**Blocks**: `OldWay`, `ClaimWith3D`, `GestureCallout`, `Object3D`, `WordBeat`, `Burst`, `UrlCard`.
+**Risks**: 3D must stay deterministic; keep object count low.
+
+## Combination rules
+- Never mix more than two families. If mixing, name a primary (structure) and a secondary (visual flavor).
+- Allowed pairs: S4+S5, S2+S5, S1+S5, S3+S7.

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

@@ -0,0 +1,62 @@
+# Signature transitions
+
+Every cut gets its own transition, placed on a dedicated `wipes` track above the scenes. Times on that track are absolute. The incoming scene's background colour is the wipe colour, so when the wipe has covered the frame the scene underneath changes unseen and the wipe simply ends.
+
+All snippets are from `examples/flomotion-ad/project.tsx` (1080 x 1920, 128 bpm: beat = 0.46875 s).
+
+## Slab wipe (from a side)
+
+```tsx
+<Rect id="w1" start="3.03s" duration="0.3s" width={1080} height={1920} fill="$brand.block3"
+  position={[[3.03, [-1080, 0]], [3.28125, [0, 0], "power4.out"]]} />
+```
+
+Vary the direction per cut (left, bottom, right, top).
+
+## Iris (a circle grows from the centre)
+
+```tsx
+<Circle id="w3" start="4.92s" duration="0.3s" at={[340, 760]} width={400} fill="$brand.block5"
+  scale={[[4.92, 0], [5.15625, 7, "power3.in"]]} />
+```
+
+## Venetian stripes
+
+Five `Rect`s, 220 px wide, each `scale` from `[1, 0]` to `[1, 1]` with its start 0.04 s later than the previous, anchored at the top (`anchor={[50, 0]}`).
+
+## Halves (two panels meet)
+
+Two `Rect`s of 540 px, one sliding in from the left, one from the right, both ending at `[0, 0]` on the cut.
+
+## Diagonal slab
+
+A 3200 px square `Rect` with `rotation={18}` sliding in on `position`; it is bigger than the frame so any rotation covers it.
+
+## Flash
+
+A white `Rect` with `opacity` `[[t-0.06, 0], [t, 1], [t+0.15, 0, "power2.out"]]`.
+
+## The two-dots turn (converge, merge, split, grow)
+
+Two big dots (pink and yellow) slide to the centre while shrinking to one small ringed dot, which then splits into two small pink dots that move apart and grow until they fill the frame in the next scene's colour. Scene-relative times (the scene is 1.875 s = 4 beats):
+
+```tsx
+<Circle id="turn-a" at={[-170, 650]} width={620} fill="$brand.accent"
+  position={[[0, [0, 0]], [0.8, [400, 0], "power3.inOut"]]}
+  scale={[[0, 1], [0.8, 0.16, "power3.inOut"], [0.86, 0]]} />
+{/* turn-b mirrors it from the right; turn-core is the dark ringed dot that appears at 0.78 s */}
+<Circle id="turn-c" at={[490, 910]} width={100} fill="$brand.accent"
+  position={[[1.0, [0, 0]], [1.3, [-170, 0], "back.out(1.8)"]]}
+  scale={[[1.0, 0], [1.06, 1], [1.3, 1], [1.875, 28, "power3.in"]]} />
+{/* turn-d is the same with +170 */}
+```
+
+Silence the music for the breath, hit on the merge (0.8 s), pop on the split (1.0 s), and land the drop on the last frame.
+
+## The vault door (a match cut on the circle)
+
+A `Card` (absolute layout) that holds a body circle, a ring, a plate, eight bolt dots and a four-spoke wheel (a nested `Card` whose `rotation` is animated). It lands after the dots' growth, spins, then shrinks and turns away to reveal a yellow disc and the product name. Scale/rotation of the outer `Card` do the open and close; the same door, smaller, closes over a ledger to say "locked". The geometry is all circles and rounded rectangles, so it stays crisp and deterministic. (The generator that wrote the door's shapes is a 30-line script; the result is plain TSX.)
+
+## The mascot (the hero dot)
+
+A `Card` on its own track: a dark circle with a white ring, two white eye circles that blink with `scale` `[1, 0.1]` keyframes, two pupils whose `position` shifts to look at the product. Spin it (`rotation` to 720) on the sting, scale it to 0 during the turn and pop it back on the drop; a `Pulse` child gives the beat-synced bounce after the drop.

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

@@ -0,0 +1,46 @@
+# Typography rules
+
+Fonts come from the active look and the font ledger. Load and verify before frame 0; check glyph coverage for every character (including any non-Latin text).
+
+## Scale and sizes
+- Use look scale tokens (`hero`, `title`, `body`, `caption`) relative to frame width.
+- Minimum sizes per format are in `config/thresholds.md` (`text.min_px`). Below minimum = HARD fail for headlines, WARN for captions.
+- Hero text should fill 50-90% of the frame width in S2/S7 and may be cropped at an edge for scale; in S1/S4/S5 keep 35-60% width with generous space.
+
+## Pairing and families
+- Max 2 families (display + body); mono only for code/numbers if the look includes it.
+- Use weight and size for hierarchy before adding a new family.
+- Tracking: tighter for large display (-0.02 to -0.04 em), neutral for body.
+- Line height: display 0.95-1.05; body 1.25-1.4.
+- Line length: <= 22 characters per line for 9:16 headlines; <= 32 for 16:9.
+
+## Case
+- Sentence case for calm looks; lowercase for kinetic/object looks; avoid all-caps except small labels (add tracking +0.06 em).
+
+## Emphasis methods (pick one per beat)
+1. Color: contrast token on the key word.
+2. Weight/size: key word one weight step heavier.
+3. Gesture: selection box, magnifier, strike, underline sweep.
+4. Opacity: lead-in at 40-60%, payoff at 100%.
+5. Karaoke: current word full, others dim.
+
+## Layout
+- Align to a grid; left-align for serious looks, center for kinetic.
+- Respect safe areas (`safe_area_px`). Never place essential text under platform UI zones (9:16 bottom).
+- No text over busy imagery without a scrim or blur backdrop (contrast must pass 4.5:1; large text 3:1).
+- Keep at least 2% of width between text and edges unless intentionally cropped (cropping is a declared effect `cropEdge: true`).
+
+## Lower-thirds and attributions
+- Name 0.5x body size, role 0.35x; logo circle 1.2x name height; slide in from the lower right or left and hold for the quote duration.
+
+## Numbers
+- Tabular figures for counters; unit in smaller size; thousands separators; currency symbols from the person's data.
+
+## Captions
+- Max 2 lines, <= 12 words per caption, >= caption min size, <= 3.5 words/s. Break at phrase boundaries.
+
+## Non-Latin text
+- Choose fonts with coverage (e.g. a Devanagari-capable family); lint `font-glyphs` must pass; tracking 0 for Indic scripts; increase line height by 10-20%.
+
+## Do not
+- Mix more than 2 families, use faux bold/italic, stretch type, letterspace lowercase body, or place light gray on white for body copy.

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

@@ -0,0 +1,96 @@
+# Workflow and gates
+
+Never skip a gate. At each gate, present the artifact, list what you verified, list "Needs your review" items, and ask one decision question.
+
+## G0 Interview (ask, do not guess)
+
+**Run the full protocol in `references/interview.md`**: about 6 to 9 rounds of 3-5 questions each, adaptive follow-ups, clarity score >= 90%, read-back approved. The list below is only the field checklist the interview must cover; do not dump it as one message.
+
+1. **Product**: name, one sentence of what it does, who uses it.
+2. **Audience and goal**: who watches; what should they do after (sign up, book demo, share).
+3. **Platform and format**: 9:16, 16:9, 1:1 or 4:5; where it will run; target length (15, 30 or 45 s).
+4. **Tone**: calm, energetic, serious, playful (pick one primary).
+5. **Facts you may use**: features (max 3 to feature), proof (numbers, certifications, customer quotes with permission), URL or CTA.
+6. **Assets**: logo, brand colors, fonts, screenshots or screen recordings, footage, music. Say which exist.
+7. **Voice**: voiceover (own recording, generated voice, none) and language. Generated voice is a paid step and needs confirmation.
+8. **Constraints**: words to avoid, legal lines, things to show or never show.
+
+Output: `brief.md` saved to the project. If a field is missing and the person cannot answer, write `"TBD"` and show a visible placeholder in drafts.
+
+## Materials check (part of G0, before G1)
+
+Call `setup_status` and tell the person what is missing and how they can proceed without a service: their own recording (`voice_import`) with a transcript or captions (`transcript_import`), their own sound files (`sound_import`), their logo and screenshots (`asset_import`), or a URL we may capture (`asset_capture`, `brand_extract`). Services (Freesound, ElevenLabs, Pexels) are set up by the person with `flomotion setup`, never by pasting keys into the chat.
+
+## G1 Direction
+
+Use `decision-tables.md`. Present:
+- Style family (name and one-line why).
+- Look (from `looks/`), with the 3 or 4 tokens that define it.
+- Story template (length, beat count).
+- Concept in one sentence ("A tangled line of apps untangles into one calm line").
+- 3 hook options (different hook types from `copywriting.md`).
+- Risks (missing assets, claims needing proof).
+
+Decision needed: approve or change direction.
+
+## G2 Script
+
+Beat table: `#`, role (hook, pain, turn, promise, proof, product, cta), on-screen text (word counts shown), voiceover line, target seconds. Text must obey `copywriting.md`. Run the word-count and reading-speed checks on the script text before showing it.
+
+Decision needed: approve script.
+
+## G3 Style frames
+
+Render 3 to 5 key frames (hook, pain or turn, product, proof, CTA) in the look using `frame_render`, then `contact_sheet`. Run `lint`, contrast, safe-area, and font-glyph checks on them.
+
+Needs-your-review: look feel, font pairing.
+
+Decision needed: approve look or give notes (max 2 revision rounds before proposing a different look).
+
+## G4 Storyboard
+
+Per beat: block id, parameters, duration, in/out motion, transition, sound tags, which element is the **hero** that carries across beats. Check total length, scene durations, and novelty rate on the plan itself.
+
+Add the **asset plan** (see `assets.md`): for each beat, every graphic it needs and where it comes from (icon from Iconify, their logo, a screenshot of their app, a stock photo, or drawn with components), what is still missing from the person, and any logo that needs permission. Missing items are listed, never faked.
+
+Decision needed: approve storyboard.
+
+## G5 Draft
+
+1. Pull the assets in the plan (`assets.md`), look at each one in a frame, then build all scenes with blocks. `lint` after each scene.
+2. Align animation key times to voice words if voice exists (`align_to_voice`).
+3. Place sounds (`sound_search` -> `sound_get` -> place on peak frames). Preview mix (`mix_preview`).
+4. Render draft at reduced size.
+5. Run `review` (all checks). Fix every HARD failure. Repeat up to 3 rounds.
+6. Show: draft, contact sheet, check table (pass/fail with evidence), anti-pattern scan result, Needs-your-review list (sounds to audition, subjective calls).
+
+Decision needed: approve draft or give notes.
+
+## G6 Final
+
+Full-quality render; license report with required attributions; summary of changes since draft. Save the project and render paths. Update the rating sheet template for the person.
+
+## Revision handling
+
+When the person gives notes, classify each:
+- **Content** (words, order) -> script and storyboard change.
+- **Look** (color, font, feel) -> token change in the look, not per-scene hacks.
+- **Motion** (speed, weight) -> motion tokens or block parameters.
+- **Sound** -> sound tags and levels.
+- **Bug** -> fix and add the failure to the check list if it is detectable.
+
+If the same note appears 3 times across videos, propose a new rule in `anti-patterns.md` or a new check.
+
+## Unattended runs
+
+If nobody is present: state the reading of the brief you took at the top of the output, continue through gates using defaults, produce the artifacts for each gate, and stop before: generated voice (paid), final render to a shared place, any claim that has no source. List open decisions at the end.
+
+## Hand-off message at the end of each gate
+
+```
+Gate: G4 Storyboard
+Done: 9 beats, 29.4 s total, hero = the line character.
+Verified: durations, novelty rate, word counts (all pass).
+Needs your review: hook option choice; music mood.
+Decision: approve storyboard, or tell me what to change.
+```

package/skills/motion-studio/SKILL.md

@@ -1,87 +0,0 @@
----
-name: motion-studio
-description: Direct and build a motion-graphics video as code with CodeCut. Use when the user wants a promo, explainer, product video, social clip or title sequence made, edited or reviewed as a video file. Runs a gated workflow (intake, script, look, voice, storyboard, build, sound, review, draft, final) through the CodeCut MCP tools. Not for editing existing camera footage by hand.
----
-
-# Motion Studio: the director
-
-You are the director. The CodeCut MCP tools are your hands. A video is one TSX file; every control is a typed prop. You never write the file blind: you call tools, they validate against schemas, and every write returns a patch and an undo token.
-
-## Ground rules
-
-1. **Stop at every gate marked (OK).** Say what you are asking for, then stop and wait for the user's reply. Do not continue in the same turn. Do not answer for them.
-2. **Use only the user's own answers in the intake.** Never fill in the audience, offer, name, numbers, or claims. If something is missing, ask. Do not invent statistics, customer names, prices or quotes.
-3. **You cannot hear and you cannot judge taste.** Sounds are chosen from tags, descriptions, measured duration and measured peak. Never say a sound "sounds right". Fonts and colours are proposals: show frames and ask. Say what you measured, then ask the user to listen and look.
-4. **Money needs a quote and a yes.** `voice_quote` first, show the price, wait for the user, then `voice_generate` with `confirm:true`. Never confirm on your own.
-5. **Never guess props.** Read `codecut://schema/<Component>` (or `references/components.md`) before using a component you have not used in this project. Unknown props are rejected with a suggestion; read it and fix.
-6. **Lint after every scene.** `lint` must show zero errors before you move on.
-7. **Look at your own work.** Use `frame_render` and `contact_sheet`, open the image, and describe what you actually see before you claim it is right.
-8. **Licences matter.** Sounds and fonts come through `sound_get` and `font_get`, which write the licence ledger. Do not reference files you did not fetch. CC-BY credits are written for you on render; mention them to the user.
-
-## The workflow
-
-### 1. Intake (OK)
-
-Ask, in one message, only what you do not already know: what is being made and the one thing a viewer should do or remember, who it is for, where it plays (platform), format and length, the product or topic facts you may use, and any brand colours, fonts, or logo files. Repeat their answers back as a short brief and ask for OK. If the user gave a one-paragraph brief, still list what is missing and ask.
-
-### 2. Script (OK)
-
-Offer **three hook options** (first 3 seconds), each a different angle. Wait for their pick or edit. Then write the **full script**: spoken-friendly sentences, one idea each, about 2.5 words per second. Show the word count and the length it implies. Do not add facts the user did not give you. Ask for OK.
-
-### 3. Look and style frames (OK)
-
-Read `codecut://looks`. Recommend one Look from kinetic, minimal, sketch with one sentence of reasoning, and name the second choice. Create or open the project (`project_create`, with `template: "saas-promo"` for a product promo and the size from the intake). Fetch the Look's fonts: `font_list`, then `font_get` for each id. Build **two or three style frames** (hook title, a UI or proof moment, the CTA) and render them with `frame_render` at the key times. Show the frames. Font choices and colour are the user's call: ask for OK. Read `references/typography.md` first.
-
-### 4. Voice
-
-Ask whether the user will **record**, **use a generated voice**, or **go without**. Default is their own recording: have them place it in `recordings/` and use provider `recording`. For a generated voice, `voice_quote` (provider `elevenlabs` and a voice id the user gives you), show the characters, credits and any price, and wait. Only then `voice_generate` with `confirm:true`. Local TTS (`local-tts`) is a free draft voice for timing only. After a voice file exists, run `transcribe` unless the provider already returned word timings. Read the words against the script and fix mismatches by editing `<audio>.words.json` with the user. Work that depends on the voice is timed **after** the voice exists.
-
-### 5. Storyboard (OK)
-
-Write the scenes as a table: id, start, duration, what is on screen, what is said, the one motion idea. Use `references/saas-promo.md` for a product promo. Total length must match the script. Ask for OK.
-
-### 6. Build
-
-Scene by scene. For each scene: `scene_write` for the whole scene, or `element_add`, `effect_add`, `keyframe_set` for single changes. Then `lint`, then `frame_render` at the scene's first and last moment, and look. Follow `references/motion.md` for easing, stagger and impact patterns, and `references/typography.md` for sizes and safe areas. After the voice exists, use `align_to_voice` to start key elements on their words and add `<Captions>`. Use `history_list` and `history_restore` (or the undo token) if something goes wrong.
-
-### 7. Sound
-
-`sound_auto` first (dry run) to see every impact that has no sound. Then apply it, or search by hand with `sound_search` (use the tags in `references/sound.md`) and place `<Sound>` with `sound_get`. Add music as `<Audio>` if the user has a track or chose one. `mix_preview` and read the measured loudness. Then say plainly which sounds you chose, from what description, with what licence, and **ask the user to listen** and approve or swap them.
-
-### 8. Review
-
-Call `review`. It lints, mixes, renders a contact sheet and checks the 17 points in `references/review.md`. Then do a **separate second pass**: open the contact sheet image and judge, one by one, every check marked manual or needs-eyes. Fix failures with the edit tools and call `review` again. Do at most **3 rounds**. After round 3 stop and show the user exactly what still fails and why. Never claim a pass you did not see.
-
-### 9. Draft, then final (OK)
-
-`render` with `preset: "draft"` and show the result (path, duration, size, the licence report). Ask the user to watch it. Only after they approve, `render` with `preset: "final"`. Tell them where the file, `<name>.credits.txt` and `<name>.licenses.json` are, and paste the credits if there are any.
-
-## Tool map
-
-| Job       | Tools                                                                                       |
-| --------- | ------------------------------------------------------------------------------------------- |
-| Project   | `project_create`, `project_read`, `history_list`, `history_restore`                         |
-| Structure | `element_add`, `element_set`, `element_remove`, `element_move`, `effect_add`, `scene_write` |
-| Motion    | `keyframe_set`, `edit` (timeline ops: split, trim, move, ripple…, and keyframe ops)         |
-| Check     | `lint`, `frame_render`, `contact_sheet`, `review`                                           |
-| Type      | `font_list`, `font_search`, `font_get`, `font_preview`, `font_check`                        |
-| Sound     | `sound_search`, `sound_get`, `sound_auto`, `mix_preview`                                    |
-| Voice     | `voice_quote`, `voice_generate`, `transcribe`, `align_to_voice`                             |
-| Output    | `render` (presets: draft, social, final)                                                    |
-
-Resources: `codecut://schema/{component}`, `codecut://project/outline`, `codecut://ledger`, `codecut://looks`.
-
-## Errors are instructions
-
-Errors have a code and a fix. `schema_violation`: read the fix and the schema. `opaque_expression`: that prop is code in the file; use `scene_write` to rewrite the element. `track_locked`, `overlap_rejected`: change the plan or ask the user. `asset_missing`, `license_blocked`: fetch a different asset. `quote_required`: you skipped the quote and the user's yes. Do not retry the same call.
-
-## References (read when you need them)
-
-- `references/components.md`: every component and effect, generated from the schemas.
-- `references/motion.md`: easing, stagger, overlap, push-in, impact patterns.
-- `references/typography.md`: sizes, pairing, hierarchy, captions, numerals, per-Look type, how to use `font_preview`.
-- `references/sound.md`: tag meanings, placement, licensing.
-- `references/saas-promo.md`: the six-beat structure with timings.
-- `references/review.md`: the 17 checks and how to fix each.
-- `looks/*.json`: each Look as data; `looks/*.scene.tsx`: one finished reference scene per Look.
-- `examples/saas-promo/`: one finished 30 s project.

package/skills/motion-studio/looks/kinetic.json

@@ -1,89 +0,0 @@
-{
-  "id": "kinetic",
-  "name": "Kinetic",
-  "description": "Loud, fast and punchy. Space Grotesk display, hard colour, expo eases, flash cuts.",
-  "palette": {
-    "bg": "#0b0b12",
-    "fg": "#ffffff",
-    "primary": "#ff3366",
-    "accent": "#ffe14d",
-    "cyan": "#27e0ff",
-    "surface": "#17171f",
-    "muted": "#9aa0b4"
-  },
-  "background": "#0b0b12",
-  "fonts": [
-    {
-      "id": "display",
-      "family": "Space Grotesk",
-      "source": "google",
-      "weights": [500, 700],
-      "variable": true,
-      "axes": {
-        "wght": [300, 700]
-      },
-      "subsets": ["latin"]
-    },
-    {
-      "id": "body",
-      "family": "Inter",
-      "source": "google",
-      "weights": [400, 600],
-      "subsets": ["latin"]
-    },
-    {
-      "id": "mono",
-      "family": "JetBrains Mono",
-      "source": "google",
-      "weights": [500],
-      "subsets": ["latin"]
-    }
-  ],
-  "type": {
-    "display": {
-      "font": "display",
-      "size": 104,
-      "weight": 700,
-      "tracking": -25,
-      "leading": 1.02
-    },
-    "body": {
-      "font": "body",
-      "size": 44,
-      "weight": 500,
-      "tracking": 0,
-      "leading": 1.3
-    },
-    "mono": {
-      "font": "mono",
-      "size": 34,
-      "weight": 500,
-      "tracking": 0,
-      "leading": 1.5
-    },
-    "numerals": {
-      "font": "display",
-      "size": 160,
-      "weight": 700,
-      "tracking": -30,
-      "leading": 1
-    }
-  },
-  "easing": {
-    "in": "expo.out",
-    "out": "expo.in",
-    "pop": "back.out(1.8)",
-    "settle": "power3.out",
-    "spring": "spring(180,18)"
-  },
-  "transition": {
-    "type": "flash",
-    "duration": 0.3
-  },
-  "grain": 0.1,
-  "sound": {
-    "hit/land": "freesound:land",
-    "move/whip": "freesound:whip",
-    "ui/pop": "freesound:pop"
-  }
-}