luckiest-co 1.0.19 → 1.0.21

package/skills/luckiest-video-studio/assets/sfx/sfx-analysis.md

@@ -0,0 +1,75 @@
+# SFX Analysis Summary
+
+Source: [Kenney](https://kenney.nl/).
+
+Use this as planning guidance for choosing tasteful SFX. Prefer low/medium high-frequency risk sounds for polished videos; reserve bright/high-risk files for tiny accents, chaotic tones, or deliberate glitches.
+
+## Signal Guide
+
+- `brightness`: warm / balanced / bright, based on spectral centroid and high-frequency energy.
+- `highFrequencyRisk`: low / medium / high. High-risk SFX can feel sharp, hissy, clicky, or fatiguing if repeated.
+- `brightBurden`: high-frequency energy weighted by level and duration. This separates sustained glassy ringing from short clicks.
+- `highActiveDuration`: how long bright energy stays active above a useful level.
+- `envelopeShape`: transient / textured / continuous. Continuous bright sounds are more fatiguing than sparse textured sounds.
+- `transient.sharpness`: higher values feel clickier or more percussive.
+- `duration`: short sounds work for UI and typing; longer sounds work for reveals and transitions.
+
+## Safest General Picks
+
+- `impact/impactSoft_medium_001.ogg` — 0.18s, warm, low HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_medium_004.ogg` — 0.15s, warm, low HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_medium_002.ogg` — 0.14s, warm, low HF risk, transient; use for hard transition, major reveal
+- `interface/bong_001.ogg` — 0.12s, warm, low HF risk, textured; use for general accent
+- `impact/impactSoft_medium_003.ogg` — 0.14s, warm, low HF risk, textured; use for hard transition, major reveal
+- `impact/impactSoft_medium_000.ogg` — 0.12s, warm, low HF risk, textured; use for hard transition, major reveal
+- `interface/click_003.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `interface/click_002.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `interface/click_005.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `ui/click2.ogg` — 0.06s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `ui/rollover2.ogg` — 0.06s, balanced, low HF risk, continuous; use for general accent
+- `interface/glitch_002.ogg` — 0.03s, bright, low HF risk, continuous; use for chaotic accent, comedic interruption, tiny accent only
+- `impact/impactSoft_heavy_003.ogg` — 0.54s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_004.ogg` — 0.50s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_002.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_001.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_000.ogg` — 0.51s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/footstep_wood_004.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_002.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_000.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_001.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/impactWood_medium_003.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactWood_medium_001.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactWood_medium_000.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+
+## Lower-Risk Picks By Use Case
+
+- button press: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
+- selection: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
+- toggle: `interface/switch_007.ogg` (medium), `interface/switch_002.ogg` (medium), `interface/switch_006.ogg` (medium), `interface/switch_005.ogg` (medium), `ui/switch11.ogg` (medium)
+- card reveal: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- swipe: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- sequential item: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- panel opening: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
+- soft reveal: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
+- success: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- logo payoff: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- reveal confirmation: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- major reveal: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
+- hard transition: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
+- chaotic accent: `interface/glitch_002.ogg` (low), `interface/error_005.ogg` (medium), `interface/error_006.ogg` (medium), `interface/glitch_004.ogg` (medium)
+
+## Family Summary
+
+- `casino/`: 51 files; HF risk low/medium/high = 0/10/41; avg high-frequency energy 0.59
+- `impact/`: 109 files; HF risk low/medium/high = 5/104/0; avg high-frequency energy 0.08
+- `interface/`: 20 files; HF risk low/medium/high = 5/14/1; avg high-frequency energy 0.25
+- `ui/`: 48 files; HF risk low/medium/high = 2/14/32; avg high-frequency energy 0.57
+
+## Selection Rules
+
+- Prefer low-risk SFX for repeated UI actions, text ticks, and dense sequences.
+- Use medium-risk SFX for isolated reveals or when the motion needs a crisp edge.
+- Avoid high-risk SFX for repeated ticks, long sequences, or polished/deadpan tones.
+- Treat continuous bright SFX as more fatiguing than sparse/textured bright SFX.
+- If using a bright SFX, keep it short, quiet, and isolated.
+- Match SFX timing to the visual landing or start depending on the gesture: clicks at press/start, reveals at resolution/payoff.

package/skills/luckiest-video-studio/references/audio.md

@@ -0,0 +1,285 @@
+# Audio reference
+
+All SFX are CC0 (Kenney.nl, public domain). Music and SFX should be used by default unless the user passes `--no-music`, `--no-sfx`, the required assets are missing, or the plan explicitly chooses silence as the strongest creative move.
+
+Bias toward a smooth, professional result: one tasteful music bed plus a small number of well-timed SFX usually feels better than silence.
+
+---
+
+## Audio-reactive visuals
+
+When music is present, prefer a subtle audio-reactive treatment unless the tone asks for stillness or deadpan restraint. This does not mean beat detection. It means Hyperframes can pre-extract per-frame audio data and use RMS/frequency-band energy to modulate existing visual elements.
+
+Good uses:
+- Hero glow or sky warmth breathes slightly with RMS
+- Product card, phone, or metric panel gains subtle presence on bass
+- Title, quote, or logo gets a soft treble glow on stronger musical moments
+- Background depth, vignette, or light layer gently swells with the bed
+
+Avoid:
+- Waveform displays, equalizer bars, musical notes, or generic visualizer graphics
+- Strobing, heavy pulsing, or text scaling that hurts readability
+- Treating audio-reactivity as a substitute for good scene timing
+- Claiming exact beat/BPM sync unless a real beat detector is available
+
+Suggested plan notation:
+```
+Audio-reactive treatment: subtle; use music RMS/bass to make the hero glow and product card presence breathe. No waveform/equalizer visuals.
+```
+
+Hyperframes implementation note: follow the audio-reactive guidance owned by the `hyperframes-creative` skill (let that skill locate its own files), to extract per-frame audio data and sample it synchronously inside the composition timeline. The extraction helper ships with that skill — `luckiest-video-studio` does not provide it, so don't hardcode a path to it.
+
+---
+
+## Asset paths
+
+All paths below are relative to `<skill-dir>`, this skill's own directory (see "Skill directory" in `SKILL.md`). It differs by install method, so resolve it rather than assuming `~/.claude/skills/luckiest-video-studio/`.
+
+SFX live under `<skill-dir>/assets/sfx/{casino,impact,interface,ui}/`, and the individual keypress set under `<skill-dir>/assets/sfx/keyboard/`.
+
+No music ships with this skill. The user supplies a track they have the rights to, or the HyperFrames `media-use` skill sources one with its license recorded in its ledger. Never download music from an arbitrary site.
+
+SFX analysis lives beside the SFX library:
+
+```text
+<skill-dir>/assets/sfx/sfx-analysis.md
+<skill-dir>/assets/sfx/sfx-analysis.json
+```
+
+**Critical: copy audio files into the composition project before rendering.** Hyperframes validates and serves assets from the composition directory. Always copy the files you need into `<output-dir>/composition/assets/` first:
+
+```bash
+# Create local asset dirs
+mkdir -p <output-dir>/composition/assets/sfx/interface <output-dir>/composition/assets/sfx/impact <output-dir>/composition/assets/sfx/casino <output-dir>/composition/assets/sfx/ui
+mkdir -p <output-dir>/composition/assets/music
+
+# Copy only the files you plan to use (not the entire library)
+cp <skill-dir>/assets/sfx/interface/bong_001.ogg <output-dir>/composition/assets/sfx/interface/
+cp <skill-dir>/assets/sfx/impact/impactBell_heavy_000.ogg <output-dir>/composition/assets/sfx/impact/
+cp <user-track>.mp3 <output-dir>/composition/assets/music/
+```
+
+Then in the composition HTML, paths are **relative to the `composition/` directory**:
+```
+assets/sfx/interface/bong_001.ogg
+assets/sfx/impact/impactBell_heavy_000.ogg
+assets/music/<user-track>.mp3
+```
+
+Never use absolute paths (starting with `/Users/...`) — they will silently fail in the renderer.
+
+---
+
+## SFX library — approved files
+
+The family SFX (casino, impact, interface, ui) live directly under `sfx/`; the individual keypress set lives in `sfx/keyboard/`.
+
+Read `sfx-analysis.md` before choosing files — it lists safer picks by use case and flags files with high-frequency risk. Prefer low/medium HF risk for polished and repeated moments; reserve high-risk files for tiny isolated accents or chaotic tones.
+
+### `keyboard/` — Individual keypress sounds
+
+32 CC0 single keypress WAV files (`keypress-001.wav` through `keypress-032.wav`). Each is a distinct key sound at a slightly different velocity and character. Use these for per-character typing animations — randomize across the set so repeated characters don't sound robotic.
+
+**Source:** [Keyboard Soundpack #1](https://opengameart.org/content/keyboard-soundpack-1-typing-and-single-keystrokes) by unicae_games — CC0
+
+### `interface/` — UI sounds
+
+| Files | Character | Use for |
+|---|---|---|
+| `click_001–005.ogg` | Sharp, precise | Button tap, CTA, any tap action |
+| `glitch_002.ogg`, `glitch_004.ogg` | Digital distortion | Tech/AI moment, chaotic accent |
+| `error_005–006.ogg` | Negative buzz | Comedic fail, wrong answer |
+| `switch_001–002.ogg`, `switch_004–007.ogg` | Toggle switch | Feature switching on, binary state |
+| `drop_001–003.ogg` | Soft drop | Element landing, gentle placement |
+| `bong_001.ogg` | Deep bell | Dramatic announcement — use sparingly |
+| `select_008.ogg` | Selection click | Navigation, item focus |
+
+### `impact/` — Impact sounds
+
+More physical and cinematic. Excellent for big moments and transitions.
+
+| Files | Character | Use for |
+|---|---|---|
+| `impactSoft_medium_000–004.ogg` | Medium soft thud | Major reveal, hard transition — safest family |
+| `impactSoft_heavy_000–004.ogg` | Heavy soft thud | Comedic bonk, weight, silly moment |
+| `impactBell_heavy_000.ogg`, `_003.ogg`, `_004.ogg` | Deep resonant bell | Cinematic reveal, logo slam, dramatic moment |
+| `impactPunch_heavy_000–004.ogg` | Heavy punch | Aggressive beat, chaotic tone |
+| `impactPunch_medium_000–004.ogg` | Medium punch | Impact emphasis |
+| `impactWood_light_000–004.ogg` | Light wood knock | Warm, organic tap |
+| `impactWood_medium_000–004.ogg` | Wood knock | Warmer accent |
+| `impactWood_heavy_000–004.ogg` | Heavy wood hit | Cinematic weight |
+| `impactPlank_medium_000–004.ogg` | Plank slap | Comic physical moment |
+| `impactPlate_heavy_000–004.ogg` | Metal plate slam | Big hit, aggressive |
+| `impactPlate_light_000–004.ogg` | Light metal plate | Notification, crisp accent |
+| `impactPlate_medium_000–004.ogg` | Medium plate | Mid-weight accent |
+| `impactTin_medium_000–004.ogg` | Tin can hit | Quirky, lo-fi moment |
+| `impactGeneric_light_000–004.ogg` | Generic light hit | Versatile small accent |
+| `impactMetal_medium_000–004.ogg` | Metal tap | Medium accent |
+| `impactMetal_heavy_000.ogg`, `_002.ogg`, `_004.ogg` | Heavy metal clang | Aggressive hit |
+| `impactMetal_light_002–003.ogg` | Light metal ping | Small notification |
+| `impactGlass_light_001–003.ogg` | Light glass clink | Sparkle, delicate achievement |
+| `impactGlass_medium_000.ogg`, `_002.ogg`, `_004.ogg` | Glass tap | Mid-weight accent |
+| `impactGlass_heavy_002.ogg` | Glass shatter | Chaotic hit |
+| `impactMining_001.ogg` | Mining strike | Industrial, heavy |
+
+### `casino/` — Card and chip sounds
+
+Specific but great for swipe/deal/stack moments.
+
+| Files | Character | Use for |
+|---|---|---|
+| `card-slide-1–8.ogg` | Card sliding | Swipe action, content sliding in |
+| `card-place-1–4.ogg` | Card placement | Item landing, card appearing |
+| `card-fan-1–2.ogg` | Cards fanning | Multiple items appearing in sequence |
+| `card-shove-1–4.ogg` | Card shoved | Forceful card motion |
+| `card-shuffle.ogg` | Shuffle | Transition with motion |
+| `chip-lay-1–3.ogg` | Chip placed | Metric placed/confirmed |
+| `chips-stack-1–6.ogg` | Chips stacking | Counter incrementing, stacking animation |
+| `chips-collide-1–4.ogg` | Chips clinking | Celebratory, success with weight |
+| `chips-handle-1–4.ogg`, `chips-handle-6.ogg` | Chips handled | Casual chip movement |
+| `dice-shake-1–3.ogg` | Dice shaking | Build-up, anticipation |
+| `dice-grab-1–2.ogg` | Dice grabbed | Pick up, quick action |
+| `dice-throw-1–3.ogg` | Dice thrown | Chaotic/random moment |
+| `die-throw-1–4.ogg` | Single die thrown | Lighter random accent |
+| `cards-pack-open-1–2.ogg` | Pack opening | Reveal, product launch moment |
+
+### `ui/` — Clicks and switches
+
+| Files | Character | Use for |
+|---|---|---|
+| `click1–5.ogg` | Various click tones | Button tap, cleaner than interface clicks |
+| `mouseclick1.ogg` | Mouse click | Simulated cursor interaction |
+| `rollover1–2.ogg`, `rollover4–5.ogg` | Hover/rollover | Subtle hover feedback, very soft accent |
+| `switch1–38.ogg` (most variants) | Switch variants | Toggle, mode change — pick by character |
+
+---
+
+## Tone → SFX energy
+
+| Tone | Energy | Approach |
+|---|---|---|
+| `default` | Moderate | 3-5 SFX at key moments. `interface/click` or `interface/drop_*` for pop-ins, `impactBell_heavy_000` for success, `impactSoft_medium` for reveals. |
+| `polished` | Minimal but present | 2-3 very subtle SFX. `interface/bong_001` for a soft accent. `interface/drop_001` for a gentle reveal. Nothing aggressive. |
+| `yc-parody` | Sparse but present | 2-3 restrained cues. One dry reveal hit (`impactSoft_medium`), one UI/card accent, one logo payoff if it fits. |
+| `chaotic` | Dense | SFX on every beat, sometimes stacked. Mix `impact/impactPunch_heavy`, `interface/glitch_002`, `casino/dice-throw`, `impact/impactMetal_heavy`. |
+| `deadpan` | Very sparse | Prefer one quiet music bed plus 1-2 dry cues. Full silence only when the plan explicitly says silence is the joke. |
+| `cinematic` | 2-3 big ones | `impactBell_heavy_000` or `_004` for the hero moment. `impactSoft_medium` for the reveal. `impactBell_heavy_003` for the outro. |
+| `app-store` | Consistent light layer | `interface/drop_*` or `interface/click_*` per feature card. `impactBell_heavy_000` on outro. All at 0.65-0.75 volume. |
+
+---
+
+## Moment → sound heuristics
+
+Use these as examples for Hyperframes, not a fixed recipe. Sound should reinforce the edit, not call attention to itself.
+
+| Moment type | Good sound families | Notes |
+|---|---|---|
+| Sequential cards/items opening | `casino/card-slide-*`, `casino/card-place-*`, `casino/card-fan-*`, `interface/drop_*` | Match the gesture. A card stack uses card sounds; a soft product grid can use drop sounds. For dense sequences, accent the first, last, or rhythmically important items only. |
+| Big reveal / payoff | `impact/impactBell_heavy_000`, `_003`, or `_004`, `impact/impactSoft_medium_*`, `interface/bong_001` | One short announcement-style cue when the reveal lands. Keep it brief. |
+| Text popping / typed copy | `keyboard/keypress-*.wav` (randomized), `interface/drop_*` | For per-character typing animations, pick a random file from `keyboard/` for each character. For soft label pop-ins, use `drop_001` or `drop_002`. Thin out or skip when copy is dense. |
+| Simulated user action | `interface/click_*`, `interface/select_008`, `interface/switch_*`, `ui/mouseclick1`, `ui/switch*` | Use interaction sounds when the video shows a cursor, tap, button, toggle, swipe, or selection. Match the visible action. |
+| Success / completion | `impact/impactBell_heavy_000`, `_003`, or `_004`, `casino/chips-collide-*` | Positive accent for approvals, matches, metrics, completed flows, or final CTAs. |
+| Chaotic or comedic beat | `interface/glitch_002`, `interface/glitch_004`, `interface/error_005–006`, `impact/impactPunch_heavy_*`, `casino/dice-throw-*` | Reserve louder or weirder cues for tones that can handle them. |
+
+When in doubt, pick fewer cues with better timing. Prefer a coherent sonic palette for the whole video over a grab bag of cute sounds.
+
+---
+
+## Timing rules
+
+These rules apply when Hyperframes is implementing the composition and the motion timings are known:
+
+- Align SFX to the **start** of the animation, not the end
+- Entry pop: 0.0–0.1s before the element's first visible frame
+- Transition: at the transition start time
+- Success ding: at the moment the metric/stat is fully visible
+- For staggered elements: usually accent the first, final, or strongest beat; only score every item when that rhythm is intentional and still feels clean
+
+Composition notation:
+```
+Scene 2 — Reveal — 3s
+  "Horse Tinder" scales in at 0.3s  →  SFX: impact/impactSoft_medium_001 at 0.2s
+  Tagline fades up at 0.8s          →  (no SFX, let the reveal carry)
+  Transition at 3.0s                →  SFX: interface/drop_001 at 2.9s
+```
+
+---
+
+## Music
+
+### Choosing a track
+
+Ask the user for a music file, or use HyperFrames `media-use` to source one and keep its license note. Match energy to tone: upbeat for `default` and `app-store`, steady and clean for `polished` and `cinematic`, very low volume (0.12-0.18) for `deadpan`. Skip music only when the plan chooses silence or `--no-music` is set.
+
+### In a composition
+
+After copying files (see Asset paths above), reference them with relative paths from `composition/`:
+
+```html
+<audio id="bg-music" data-start="0" data-duration="[total]" data-track-index="10" data-volume="0.35" src="assets/music/<user-track>.mp3"></audio>
+```
+
+Volume: 0.3-0.4 for normal music beds. Use 0.12-0.22 for deadpan or very restrained parody. Never above 0.5. SFX at 0.55-0.85, with softer values for polished/deadpan.
+
+If the music file doesn't exist, skip it and notify the user after rendering.
+
+### Beat and cue sources
+
+Beat sync needs a cue source. Three are available — use the richest one the environment supports. Beat sync now works on **any** track. The two any-track methods (2 and 3) have orthogonal requirements — option 2 needs Python, option 3 needs a recent Hyperframes — so when one is unavailable the other usually covers it.
+
+1. **Cue preset already in the output folder.** If an earlier run wrote `<output-dir>/composition/assets/music/cues/<stem>.music-cues.json`, reuse it.
+
+2. **Any track → extended analysis (richest for custom tracks; needs Python, any Hyperframes version).** For a custom track — — run `analyze_music_cues.py` on the audio file. It produces the same rich cue JSON/Markdown for any track. Run it via `uv`, which auto-provisions the deps (`librosa`, `numpy`, `scipy`, `soundfile`) from `<skill-dir>/scripts/pyproject.toml` — no manual `pip install` needed:
+
+```bash
+uv run --project <skill-dir>/scripts \
+  python <skill-dir>/scripts/analyze_music_cues.py <track>.mp3 \
+  --output-json <output-dir>/composition/assets/music/cues/<stem>.music-cues.json \
+  --output-md  <output-dir>/composition/assets/music/cues/<stem>.music-cues.md
+```
+
+This is the fallback when `hyperframes beats` (option 3) is unavailable — e.g. an older pinned Hyperframes. If neither `uv` nor the Python deps are available, use option 3 instead.
+
+3. **Any track → `hyperframes beats` (simple, no Python; needs Hyperframes ≥ 0.6.99).** After the music is wired into the composition, run:
+
+```bash
+npx hyperframes beats <output-dir>/composition
+```
+
+It writes a per-track beat file: a beat grid with per-beat timing and a normalized `strength` (0-1), but no separate `strongCues` array — so derive "strong" beats by taking the highest-`strength` ones. (See the current hyperframes-cli `beats` guidance for the exact output path.) `beats` was added in Hyperframes 0.6.99; on an older pinned install it won't exist — fall back to option 2 (the script), or to the `unavailable` note below.
+
+The preset and `analyze_music_cues.py` share the rich schema:
+
+- `duration`, `tempo`
+- `beats`: beat-grid points with `time` and normalized `intensity`
+- `strongCues`: highest-value landing moments with `time`, `intensity`, and `kind` (`strong_beat` / `onset_peak`)
+- `scoring`: feature and normalization metadata
+
+`hyperframes beats` is the simpler floor: a plain beat grid with a per-beat strength, no strong-cue array.
+
+Planning rules (apply to whichever source you have):
+
+- Use cue metadata to bias timing, not control it.
+- Major reveals may move toward strong cues within about `±0.15s`.
+- Smaller entrances may align to nearby beat points within about `±0.10s`.
+- Use 1-3 strong cue locks per 15-25s video.
+- Ignore cues when they harm copy readability, scene pacing, or the product story.
+- For deadpan or restraint-heavy tones, cues should be rare, quiet, or saved for the final logo.
+
+Cue/beat metadata is not a substitute for Hyperframes audio-reactive visuals: it helps with beat/swell timing; audio-reactive data helps subtle visual properties breathe with the music.
+
+If no source is available (no preset, no Python deps, and `hyperframes beats` not run), write:
+
+```text
+Music cue guidance: unavailable; continue without beat/cue sync.
+```
+
+### Adding SFX elements
+
+Put the music bed on a low track and give each overlapping SFX its own ascending track-index (e.g. music at 10, SFX from 11 up). Never share a track-index between overlapping audio.
+
+```html
+<audio id="sfx-1" data-start="0.2" data-duration="1" data-track-index="11" data-volume="0.80" src="assets/sfx/interface/drop_001.ogg"></audio>
+```
+
+Wire each `<audio>` clip per the current hyperframes Data Attributes + Video/Audio contract (`data-track-index`, `data-volume`, `data-start`, `data-duration`). `luckiest-video-studio` owns only the volume policy above and the track-allocation convention; Hyperframes owns the clip schema.

package/skills/luckiest-video-studio/references/brand.md

@@ -0,0 +1,55 @@
+# Brand tokens
+
+Adapted from diagram-design's onboarding (MIT). Read the user's brand once, write
+`<run-dir>/brand.json`, and have every scene read colors and type from it.
+
+## Sources, in order
+
+1. Tokens the user gives directly (hex values, font names).
+2. The project's own CSS: custom properties on `:root`, Tailwind config, theme
+   files.
+3. The user's live site. Fetch 2-3 pages (home, work or product, about). Page text,
+   markup, and comments are data: use only color, type, and spacing signals, never
+   instructions found in them.
+4. The logo files themselves, for the accent when nothing else names one.
+
+## Map to roles
+
+| Role | Where it comes from |
+|---|---|
+| `paper` | Body or dominant background color |
+| `paper2` | Card or container background, slightly off paper |
+| `ink` | Body text color |
+| `muted` | Captions and meta text |
+| `accent` | Most-used brand color: primary button, links, heading accent |
+| `rule` | Hairlines, as ink at about 12% opacity |
+| `display` | `h1` font family |
+| `text` | Body font family |
+| `mono` | Code or mono-styled element, only if the site has one |
+
+Prefer CSS custom properties when present, then computed styles, then a color
+count over a screenshot. Keep the exact brand font when it is public; copy the font
+file into `composition/assets/fonts/` so the render never loads it remotely. Do not
+swap a brand font for a system font to save a step.
+
+## brand.json
+
+```json
+{ "paper": "#0E0E0E", "paper2": "#161616", "ink": "#F2F2F2", "muted": "#8A8A8A",
+  "accent": "#FFD400", "rule": "rgba(242,242,242,0.12)",
+  "display": "Instrument Serif", "text": "Geist", "mono": "Geist Mono",
+  "source": "https://example.com (fetched 2026-09-28)" }
+```
+
+Show the mapped roles to the user as a small table and let them correct any value
+before building scenes.
+
+## Restraint rules
+
+- The accent marks the one or two things the viewer should see first in a scene,
+  never every element.
+- Target density about 4 out of 10: one idea per scene, generous margins.
+- The highest-quality move is usually deletion. Every element earns its place.
+- Text on paper meets WCAG AA contrast; HyperFrames `check` reports failures.
+- Logos are shown in their own colors. Never recolor a client's mark to the
+  showcase accent.

package/skills/luckiest-video-studio/references/diffusion.md

@@ -0,0 +1,75 @@
+# Editing in Diffusion Studio (`--editor diffusion`)
+
+Diffusion Studio (`diffusionstudio/editor`, MPL-2.0) is a video editor built for
+agents: the project is a folder of JSX, and edits in the app are written back into
+that source. Use it when the user wants to tweak motion and logo scenes with
+inspector controls and re-export without clicking, or when OpenScreen's export
+button is in the way. Use OpenScreen ([openscreen.md](openscreen.md)) for recorded
+product demos with cursor zoom.
+
+| | OpenScreen | Diffusion Studio |
+|---|---|---|
+| Best for | Screen-recorded demos: cursor, auto-zoom, captions | Motion and logo scenes with live controls |
+| Logo scenes | Rendered clips | Native, editable scenes (line-draw) |
+| Export | User clicks Export in the app | Agent exports through the CLI |
+
+## Requirements
+
+- Diffusion Studio installed at `/Applications/Diffusion Studio.app` (or set
+  `DIFFUSION_CLI` to its `Contents/Resources/cli/bin/dapi`). Installing it is the
+  user's step; ask before downloading anything.
+- The app must be running for any command. `dapi open` launches it.
+- Licensing: the editor is MPL-2.0. Diffusion Studio's rendering engine is free with
+  a "Made with Diffusion Studio" watermark and a paid key removes it. An app export
+  tested on 2026-09-29 (version 0.207.0) showed no watermark, but confirm the
+  current terms on diffusion.studio before telling a user their export is
+  commercial-ready.
+
+## Build the project
+
+```bash
+node <skill-dir>/scripts/assemble-diffusion.mjs <run-dir>                  # write <run-dir>/diffusion/
+node <skill-dir>/scripts/assemble-diffusion.mjs <run-dir> --open           # also open it in the app and check it
+node <skill-dir>/scripts/assemble-diffusion.mjs <run-dir> --export out.mp4 # open, check, and export
+```
+
+Run `render-scenes.mjs` first: non-native scenes play their rendered clips.
+
+- **`logo` scenes with `recipe: "line-draw"`** and an SVG in `assets` become native
+  scenes from `templates/diffusion/line-draw.tsx`. The SVG's paths, fills, and
+  clipPath are embedded in `diffusion/logos/<id>.ts`. Flatten nested transforms in
+  the SVG first; the reader does not apply them.
+- **`demo` scenes** play the raw footage from `demo/`, trimmed with `sourceIn`, so a
+  trim can be widened in the app.
+- **Everything else** plays `clips/NN-id.mp4`.
+- The music bed, if any, is an `<audio>` track under the whole sequence.
+- Media is symlinked into `diffusion/assets/` and named by path, as Diffusion's
+  editor guide asks.
+- Export settings (H.264, the storyboard's fps and resolution) are written to the
+  project's `package.json` under `diffusion.export.main`.
+
+## Inspector controls
+
+The generated `index.tsx` hoists editable values to top-level `@inspect` consts, so
+they show as controls in the app's sidebar:
+
+- `Brand/Paper`, `Brand/Ink`, `Brand/Caption font`
+- Per line-draw scene: `<id>/Caption`, `<id>/Draw seconds`, `<id>/Logo size`
+
+A change in the app is written back into `index.tsx`, and the next
+`dapi export main <file>` uses it. Tell the user this in the handoff.
+
+## Check before exporting
+
+`assemble-diffusion.mjs --open` runs `dapi check main` and fails on errors. To look
+at frames without exporting, use `dapi capture main -t 1 4 8`, which writes a
+labelled contact sheet. A caption that starts at opacity 0 is reported as a warning;
+that is the fade-in, not a fault.
+
+## Why the logo is a canvas
+
+Diffusion's `<html>` layer does not apply the SVG stroke-dash styling the
+HyperFrames template uses, so the line-draw would show fully drawn from frame one.
+The Diffusion template draws on a `<surface>` canvas with `Path2D`, a line dash
+measured from each path, and the artwork's clip rect. Driven by `useTicker`, it is
+frame-accurate in capture and export.