flomotion 0.2.0 → 0.4.0

package/skills/flomotion-studio/dataset/annotations/vaylens.md

@@ -0,0 +1,53 @@
+# Reference annotation: Vaylens
+
+Patterns seen in a public ad, annotated from stills. Never reproduce another brand's work (see `SKILL.md` rule 2).
+
+| Field | Value |
+| --- | --- |
+| id | vaylens |
+| brand | Vaylens |
+| source | user-collected stills from a compilation, rank 4 in overlay |
+| url | none |
+| format | 16:9 |
+| duration_s | none |
+| platform | none |
+| style_family | S4 |
+| confidence | M |
+| rating | none |
+| rating_notes | none |
+| pain_share | 0.1 |
+| turn | circles close in; 'we built' |
+| motif | circles and blobs |
+| palette_source | single-accent |
+| palette_notes | one electric blue plus pale lavender; purple-blue gradient |
+| type_notes | light-weight neo-grotesque, generous space |
+| text_emphasis | karaoke highlight, dim to bright |
+| grain | light |
+| blur_on_motion | none |
+| sentence_split | 3 |
+| human_presence | b-roll |
+| ui_fidelity | stylized |
+| transitions | shape close-in, blob morph |
+| proof_type | scale |
+| sound_notes | none |
+| patterns | 2, 4, 5, 11, 12, 13, 14 |
+
+## beats
+
+| n | role | block | text | notes |
+| --- | --- | --- | --- | --- |
+| 1 | hook | KaraokeLine | As the need to use electric cars becomes the norm | flat blue; current word bright, others dim |
+| 2 | pain | FramedFootage | the way we [photo] recharge them | pale bg; photo in a clean rectangle, text flanks it |
+| 3 | turn | ShapePivot | we built | two blue circles close in on the text |
+| 4 | brand | ShapeMorph | vaylens | white blob pinches and morphs into the wordmark |
+| 5 | promise | CategoryLine | It's a charging management software | purple-blue gradient, light type |
+| 6 | product | GlassUI | none | frosted glass dashboard over blurred top-down footage of a team |
+| 7 | proof | ProofMosaic | helping thousands of companies | mosaic of industry footage on dark panel |
+
+## Lessons
+
+- open from an agreeable market fact
+- split one sentence across scenes
+- shapes as punctuation
+- plain category line
+- glass UI over real-world context

package/skills/flomotion-studio/dataset/brief-template.md

@@ -0,0 +1,110 @@
+# Brief template (output of the interview)
+
+Every field is an object {value, source, status}. source: user | asset | assumption. status: confirmed | assumed | unknown.
+
+Write `brief.md` in the project folder with one `##` section per group below and one line per field:
+
+```
+- field: the answer · source: user · status: confirmed · quote: "their words" · note: why
+```
+
+`source` is `user`, `asset` or `assumption`; `status` is `confirmed`, `assumed` or `unknown`. An unknown stays visibly unknown; never invent it.
+
+Required groups: product, audience, goal, message, proof, format, taste, voice, constraints, clarity.
+
+## product
+
+- name: · source: · status:
+- oneLiner: · source: · status:
+- pain: · source: · status:
+- wowFeature: · source: · status:
+- features: · source: · status:
+- competitors: · source: · status:
+
+## audience
+
+- primary: · source: · status:
+- buyerVsUser: · source: · status:
+- awareness: · source: · status:
+- triggerMoment: · source: · status:
+- language: · source: · status:
+
+## goal
+
+- action: · source: · status:
+- cta: · source: · status:
+- destination: · source: · status:
+- offer: · source: · status:
+- deadline: · source: · status:
+
+## message
+
+- promise: · source: · status:
+- oneSentenceToRemember: · source: · status:
+- avoid: · source: · status:
+
+## proof
+
+- items: · source: · status:
+- noProof: · source: · status:
+
+## assets
+
+- logo: · source: · status:
+- brandColors: · source: · status:
+- fonts: · source: · status:
+- screens: · source: · status:
+- footage: · source: · status:
+- music: · source: · status:
+- voice: · source: · status:
+- forbiddenToShow: · source: · status:
+
+## format
+
+- platform: · source: · status:
+- aspect: · source: · status:
+- lengthSeconds: · source: · status:
+- deliverables: · source: · status:
+
+## taste
+
+- adjectivesYes: · source: · status:
+- adjectivesNo: · source: · status:
+- tone: · source: · status:
+- likedRefs: · source: · status:
+- dislikedRefs: · source: · status:
+- styleFamilyRanking: · source: · status:
+- lookChoice: · source: · status:
+- motionTaste: · source: · status:
+- typeTaste: · source: · status:
+
+## voice
+
+- plan: · source: · status:
+- language: · source: · status:
+- pronunciations: · source: · status:
+- musicMood: · source: · status:
+- soundAppetite: · source: · status:
+
+## constraints
+
+- legalLines: · source: · status:
+- platformRules: · source: · status:
+- approver: · source: · status:
+- revisionTolerance: · source: · status:
+- budgetNotes: · source: · status:
+
+## assumptions
+
+- assumptions: · source: · status:
+
+## openItems
+
+- openItems: · source: · status:
+
+## clarity
+
+- mustHaveTotal: · source: · status:
+- confirmed: · source: · status:
+- score: · source: · status:
+- readbackApproved: · source: · status:

package/skills/flomotion-studio/dataset/rating-sheet.md

@@ -0,0 +1,28 @@
+# Rating sheet
+
+Copy one block per reference ad (to fill the dataset) or per generated draft (to tune the system). Rate 1-5. Free text welcome.
+
+## For a reference ad
+
+```
+Ad id:
+Source link:
+Format / platform:
+Duration (s):
+Would this convince a buyer? (1-5):
+What worked (one line):
+What did not (one line):
+Hook (1-5):  Story (1-5):  Polish (1-5):  Motion (1-5):  Typography (1-5):  Sound (1-5):
+Moments to copy as patterns (timestamps + what):
+```
+
+## For a generated draft
+
+```
+Draft id / brief:
+Hook:  Story clarity:  Visual polish:  Motion quality:  Typography:  Sound:  Look consistency:  Would I post this:
+Notes (what feels off, with timestamps):
+```
+
+## Aggregation (evals/README.md)
+Averages per dimension and per look/style; flag a change that lowers any average by >= 0.3 versus the previous run.

package/skills/flomotion-studio/dataset/schema.md

@@ -0,0 +1,44 @@
+# Reference ad annotation
+
+One record per reference ad. Store annotations, never the video or its assets. Unknown values are null.
+
+Required: id, brand, style_family, beats, confidence.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| id | string |  |
+| brand | string |  |
+| source | string |  |
+| url | string (may be none) |  |
+| format | string (may be none) · one of 9:16, 16:9, 1:1, 4:5 |  |
+| duration_s | number (may be none) |  |
+| platform | string (may be none) |  |
+| style_family | string · one of S1, S2, S3, S4, S5, S6, S7, unknown |  |
+| confidence | string · one of H, M, L | confidence of annotation from stills only |
+| rating | integer (may be none) |  |
+| rating_notes | string (may be none) |  |
+| beats | array |  |
+| beats[].n | integer | |
+| beats[].role | string · one of hook, pain, turn, promise, product, proof, brand, cta, bridge, other | |
+| beats[].block | string (may be none) | |
+| beats[].text | string (may be none) | |
+| beats[].t_start_s | number (may be none) | |
+| beats[].t_end_s | number (may be none) | |
+| beats[].notes | string (may be none) | |
+| pain_share | number (may be none) |  |
+| turn | string (may be none) | technique of the problem-to-solution switch |
+| motif | string (may be none) |  |
+| palette_source | string (may be none) · one of brand, single-accent, per-scene-blocks, gradient, mixed |  |
+| palette_notes | string (may be none) |  |
+| type_notes | string (may be none) |  |
+| text_emphasis | array (may be none) |  |
+| grain | string (may be none) · one of none, light, heavy |  |
+| blur_on_motion | boolean (may be none) |  |
+| sentence_split | integer (may be none) | number of scenes one sentence spans |
+| human_presence | string (may be none) · one of none, b-roll, talking-head, story |  |
+| ui_fidelity | string (may be none) · one of skeleton, stylized, real, none |  |
+| transitions | array (may be none) |  |
+| proof_type | string (may be none) |  |
+| sound_notes | string (may be none) |  |
+| patterns | array (may be none) | pattern ids from references/patterns.md |
+| lessons | array (may be none) |  |

package/skills/flomotion-studio/evals/README.md

@@ -0,0 +1,33 @@
+# Evaluation procedure
+
+Purpose: make quality measurable and make every change to the skill prove itself.
+
+## Run
+1. For each brief in `briefs/briefs.md`, start a fresh Claude session with the skill and the brief as the intake answers (G0 prefilled).
+2. Let it run through gates with approvals auto-given at G1-G4 (to measure the machine), or manually (to measure the whole loop).
+3. Save to `evals/runs/<YYYY-MM-DD>/<brief-id>/`: `brief.md`, `storyboard.md`, draft video, contact sheet, `review` output, timing, token/cost notes.
+4. Paid or network services (voice generation, sound search) run with test doubles in automated runs; list which steps were doubled.
+
+## Metrics
+| Metric | How |
+|---|---|
+| HARD-check pass after round 1 / round 3 | `review` output |
+| Rounds to clean | count |
+| Anti-pattern hits | scan list |
+| Invented-fact violations | manual check against brief (must be 0) |
+| Human ratings (8 dimensions) | `dataset/rating-sheet.md` |
+| Time to draft | timing |
+
+## Aggregation
+Write `evals/runs/<date>/summary.md`: table per brief (checks, rounds, ratings), per-dimension averages, per-style and per-look averages, and a diff against the previous run (flag changes of >= 0.3 or any new HARD failure).
+
+## Regression rule
+After any change to a look, block, check, threshold or reference, rerun the 10 briefs. Keep the change only if no dimension average drops by >= 0.3 and no new HARD failure appears. Record result in `CHANGELOG.md`.
+
+## Targets (initial)
+- Every draft passes all HARD checks within 3 rounds.
+- Average rating >= 4.0 per dimension on >= 8 of 10 briefs.
+- Zero invented facts.
+
+## What cannot be automated
+Taste (look, font pairing), sound (needs listening), voice tone, and whether it "feels" professional. The person rates; the system learns from the ratings.

package/skills/flomotion-studio/evals/briefs/briefs.md

@@ -0,0 +1,25 @@
+# 10 test briefs (invented products)
+
+Each brief is a complete intake answer. Vary format, tone and assets. Facts below are invented for testing; none are real claims.
+
+| # | Product | Audience | Goal | Format | Length | Tone | Assets | Proof available | Expected style |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | **QueryLens**: traces slow database queries | Backend developers | Sign up | 16:9 | 30 s | Serious | Screenshots | "Finds the slow query in minutes" (own metric, source: internal test) | S5 or S3 |
+| 2 | **LedgerLeaf**: bookkeeping for freelancers | Freelancers | Free trial | 9:16 | 30 s | Calm | None | Quote from a fictional beta user (permission: yes) | S6 or S2 |
+| 3 | **NoteWise**: AI meeting notes | Team leads | Demo booking | 9:16 | 15 s | Energetic | Screen recording | None | S2 or S5 |
+| 4 | **ShiftGrid**: shift planning | Shop managers | Install | 1:1 | 30 s | Playful | Screenshots | "Saves 3 hours a week" (source: pilot) | S7 or S5 |
+| 5 | **MetricBay**: product analytics dashboard | Product managers | Demo | 16:9 | 45 s | Serious | Real dashboard UI | Number: "10,000 teams" (source: sales deck) | S3 or S4 |
+| 6 | **PaperTrail Design**: design collaboration | Designers | Trial | 9:16 | 30 s | Energetic | Logo, brand colors | None | S2 |
+| 7 | **SafeStep**: security awareness training | HR/IT leads | Demo | 16:9 | 30 s | Serious | None | Certification: "SOC 2 Type II" (source: audit letter) | S1 |
+| 8 | **CartCrafter**: store builder for small shops | Small shop owners | Free trial | 9:16 | 15 s | Playful | Screenshots | None | S6 or S7 |
+| 9 | **CalmClinic Booking**: appointment booking | Clinic admins | Demo | 16:9 | 30 s | Calm | UI mock | "Cuts no-shows" must NOT be used (no source) | S5 or S4 |
+| 10 | **FocusFern**: habit and focus tracker | Students | Install | 9:16 | 30 s | Playful | None | None | S6 or S7 |
+
+## What each brief tests
+- 2, 8, 10: no assets, no proof (does the system avoid inventing?).
+- 9: a forbidden claim (does the system refuse and flag it?).
+- 5, 7: proof handling (number with source, credential).
+- 6: brand override.
+- 1, 5: dense UI at 16:9; contrast and min size.
+- 3, 8: 15 s hook-led.
+- Mixed formats: 9:16 (2,3,6,8,10), 16:9 (1,5,7,9), 1:1 (4).

package/skills/{motion-studio/looks → flomotion-studio/examples/engine-looks}/kinetic.scene.tsx

@@ -14,7 +14,7 @@ import {
   PunchZoom,
   Vignette,
   Grain,
-} from "@codecut/components";
+} from "@flomotion/components";
 
 /**
  * Reference scene for the Kinetic Look: loud, fast, hard contrast.

package/skills/{motion-studio/looks → flomotion-studio/examples/engine-looks}/minimal.scene.tsx

@@ -10,7 +10,7 @@ import {
   Chip,
   ProgressRing,
   DropShadow,
-} from "@codecut/components";
+} from "@flomotion/components";
 
 /**
  * Reference scene for the Minimal Look: calm, precise, lots of air.

package/skills/{motion-studio/looks → flomotion-studio/examples/engine-looks}/sketch.scene.tsx

@@ -12,7 +12,7 @@ import {
   Card,
   Wobble,
   Grain,
-} from "@codecut/components";
+} from "@flomotion/components";
 
 /**
  * Reference scene for the Sketch Look: hand-drawn, playful, bouncy.

package/skills/flomotion-studio/examples/flomotion-ad/LOG.md

@@ -0,0 +1,39 @@
+# LOG: flomotion-ad
+
+## Decisions
+
+- 30 s, 9:16, 128 bpm (one beat = 0.46875 s, 64 beats). Every cut is on a beat and has its own transition (the `wipes` track).
+- Look `bold-kinetic` (energetic): flat colour blocks, heavy type, dark text on every block (it passes the contrast lint).
+- Turn: two big dots converge, merge, split, grow into the next slide. A vault door (circles and rounded rectangles) then opens onto the name, and closes over the ledger later. Both ideas are the person's.
+- Hero: a mascot dot with eyes on its own track; it blinks, looks at the product, spins on "Again.", hides in the turn, and pulses on the beat after the drop.
+- Voice: ElevenLabs "Jessica" (a library voice such as "Zara" cannot be used through the API on a free plan: `paid_plan_required`), `eleven_multilingual_v2`, one clip per phrase placed on its beat (`scripts/build-voice.py`). 14 clips, about 350 characters of the free allowance.
+- Music: three CC0 Freesound loops (Loop 128 Bpm, Electro House drums, Piano arp pitched down 4 semitones into the bed's key), arranged offline with a drop on the turn (`scripts/build-music.py`). Real whooshes, a glitch and a riser-hit from Freesound; small ticks, pops, types and hits are original synthesized sounds.
+- The copy was rewritten with `references/script-craft.md`. "Live" was dropped because it is a heteronym; the line is "come alive". "Same video every time" was cut (see below) and replaced by "Diff it like code."
+- Product shots are real captures of the live view (`asset_capture`) of a demo project a script worked on; the licence panel is this video's own ledger. It is not a recording of a live Claude session.
+
+## What ran
+
+- `lint`: 0 errors, 0 warnings.
+- `review` (several rounds): 17 checks run, 0 failing. Warning 7 (text moving through the edge of the frame while it enters, and wipes covering text at the cuts, both by design). Warning 16: the voice is ElevenLabs output on a free plan and is not cleared for commercial use. Check 9 once failed (white captions on light blocks) and was fixed with dark one-word captions.
+- `mix_preview` / render: -14.9 LUFS, true peak -1.5 dBTP (targets -14 +/-1, <= -1.0).
+- Render `final`: 1080x1920, 30 fps, 30.0 s, H.264 + AAC, 9.6 MB, 17 ledger entries. Frames pulled from the MP4 were checked by eye.
+
+## What I found while making it (engine)
+
+- The audio mix was not repeatable: two renders of the same project differed in the last samples (`sidechaincompress` paired frames in thread order). Fixed in `packages/render/src/audio.ts`, with a regression test that fails without the fix. The mix is now byte-identical.
+- `local:` sounds did not resolve on a fresh checkout (they resolved only through an ignored cache). Fixed; a clean-clone render matched the original at the time.
+- **The video is not byte-identical between renders of this project.** About 1-pixel edge differences appear on elements with animated transforms (the counters, the mascot, rotated cards). Single frames are identical every time, and software GL and one worker do not change it. HyperFrames' own deterministic path is `--docker`. Simple scenes (the engine tests) are identical. I did not trace it to one element. This is why the ad does not claim "same video every time".
+
+## Not run / unverified (read this)
+
+- **Nobody has listened to anything.** The voice, the music and the effects are choices made from measurements. Audition them.
+- The three reference pieces were studied from frames and loudness only; I could not hear their speech or music.
+- The voice is on ElevenLabs' free plan. As I understand its terms, the output needs attribution and is not licensed for commercial use: check them before you publish.
+- A lot of this was written with the file tools, not `scene_write`, so `history_*` holds only the font snapshots.
+- No real Claude Code session, no Whisper (the word times come from ElevenLabs).
+- Keys for Freesound and ElevenLabs were pasted into the chat: regenerate them.
+- Pixabay music was preferred, but the file path was not supplied, so none is used.
+
+## Gate state
+
+G0-G4 done in the files; G5 draft and G6 final rendered; approval is the person's.

package/skills/flomotion-studio/examples/flomotion-ad/brief.md

@@ -0,0 +1,41 @@
+# Brief: flomotion ad
+
+Every line: `value · source · status` (source: user, asset or assumption; status: confirmed, assumed or unknown).
+
+## product
+- name: flomotion · user · confirmed
+- oneLiner: a video is one TSX file; Claude edits it through typed MCP tools while you watch · asset (the repo) · confirmed
+- wowFeature: the live view, and every control is a typed prop · assumption · assumed
+
+## audience
+- primary: developers and creators who use Claude Code · assumption · assumed
+
+## goal
+- action: run `npx flomotion` · assumption · assumed
+- cta: npx flomotion · assumption · assumed
+
+## format
+- size: 1080x1920, 30 fps, 30 s, 128 bpm · user ("a SaaS style ad") + assumption · assumed
+
+## taste
+- look: bold-kinetic, energetic: flat colour blocks, heavy type, hard cuts, a mascot dot · user ("energetic") · confirmed
+- references: three short motion pieces the person collected (see `references/clean-styles.md` in the skill) · user · confirmed
+- turn: two big dots converge into a small dot, split in two, and grow into the next slide · user · confirmed
+- metaphor: a vault door (safe), as in a reference ad for data rooms · user · confirmed
+
+## voice
+- voice: ElevenLabs premade "Jessica", a girl's voice · user ("a girl voice suits better") · confirmed
+- model: eleven_multilingual_v2 (the person's free plan has no expressive model) · user · confirmed
+
+## facts allowed on screen (each verified in the repo)
+- 39 MCP tools: `tools/list` of the packaged server · asset · confirmed
+- 17 automatic review checks: `review` returns 17 · asset · confirmed
+- the ad is one TSX file: `examples/flomotion-ad/project.tsx` · asset · confirmed
+
+## forbidden
+- testimonials, customer logos, user counts, speed claims, superlatives
+- "same video every time": not true byte for byte for this project (see LOG.md)
+
+## constraints
+- music: Freesound CC0 loops, arranged; no paid music · user ("pixabay is better" but could not supply a file) · assumed
+- clarity: unattended run, readings recorded above · assumption

package/skills/flomotion-studio/examples/flomotion-ad/ideas.md

@@ -0,0 +1,12 @@
+# Ideas
+
+One line per idea: `- [ ] text (you)` or `- [x] text (claude)`. Tick it when it is used or dropped.
+
+- [x] two big dots converge into a small dot, split into two, grow into the next slide (you)
+- [x] a vault door like the data-room ad, to say "safe" (you)
+- [x] a girl's voice (you)
+- [x] a mascot dot with eyes that reacts to the story (claude)
+- [x] close the loop: the prompt typed in the hook comes back "rendered" in the CTA (claude)
+- [x] reveal at the end: "This whole ad is one TSX file." (claude)
+- [ ] a second cut for 16:9 with the same script (claude)
+- [ ] a glowing line that threads the scenes together, like the language-app piece (claude)