@nerdev/skillset 0.2.1

package/skills/business/brag/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/business/brag/references/audio.md

@@ -0,0 +1,307 @@
+# 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 ,  `/brag` 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/brag/`.
+
+SFX live under `<skill-dir>/assets/sfx/{casino,impact,interface,ui}/`, and the individual keypress set under `<skill-dir>/assets/sfx/keyboard/`.
+
+Music lives at `<skill-dir>/assets/music/`.
+
+Bundled music cue presets live beside the music:
+
+```text
+<skill-dir>/assets/music/cues/<track-stem>.music-cues.md
+<skill-dir>/assets/music/cues/<track-stem>.music-cues.json
+```
+
+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 <skill-dir>/assets/music/happy-beats-business-moves-vol-1-by-ende-dot-app.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/happy-beats-business-moves-vol-1-by-ende-dot-app.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
+
+### Available tracks
+
+All tracks are "Happy Beats / Business Moves" by ende.app. Upbeat, clean, corporate-adjacent. Good across multiple tones.
+
+| Filename | Duration | Character | Best for |
+|---|---|---|---|
+| `happy-beats-business-moves-vol-1-by-ende-dot-app.mp3` | 2:44 | Full upbeat track, most energetic | `default`, `app-store` |
+| `happy-beats-business-moves-vol-9-by-ende-dot-app.mp3` | 1:54 | Mid-energy, slightly more laid-back | `default`, `yc-parody` |
+| `happy-beats-business-moves-vol-10-by-ende-dot-app.mp3` | 1:00 | Compact loop, punchy | `default`, `chaotic` |
+| `happy-beats-business-moves-vol-11-by-ende-dot-app.mp3` | 1:28 | Warm and business-y | `yc-parody`, `app-store` |
+| `happy-beats-business-moves-vol-12-by-ende-dot-app.mp3` | 1:58 | Steady and clean | `polished`, `cinematic` |
+
+For `deadpan` tone: prefer vol-12 at very low volume (0.12-0.18). Skip music only if the plan explicitly chooses silence.
+
+### 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/happy-beats-business-moves-vol-1-by-ende-dot-app.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, not just bundled ones. 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. **Bundled track → precomputed preset (richest, instant, no deps).** The bundled tracks ship with cue metadata. Read the matching markdown summary, and pass the JSON path in `composition-brief.md`:
+
+```text
+<skill-dir>/assets/music/cues/<track-stem>.music-cues.md
+<skill-dir>/assets/music/cues/<track-stem>.music-cues.json
+```
+
+2. **Any track → extended analysis (richest for custom tracks; needs Python, any Hyperframes version).** For a custom track ,  or to refresh a bundled one ,  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`). `/brag` owns only the volume policy above and the track-allocation convention; Hyperframes owns the clip schema.

package/skills/business/brag/references/step-1-inspect.md

@@ -0,0 +1,133 @@
+# Step 1: Inspect the project
+
+Read the project directory to understand what you're bragging about.
+
+## What to look for
+
+Read these in priority order:
+
+1. **`index.html`** ,  the primary source. Read the full file. Extract: page title, hero headline, tagline, all section headings, CTA text, testimonial copy, nav items. This is the voice and story of the app.
+
+2. **`styles.css`** or equivalent ,  extract: primary color palette (look for CSS custom properties / `:root` vars), font families, background colors, accent colors. These become the visual identity of the brag video.
+
+3. **`README.md`** ,  if present, extract: project name, one-line description, any listed features.
+
+4. **`package.json`** ,  if present, extract: `name`, `description`.
+
+5. **Subdirectory files** ,  if this is a multi-page app, scan route files, component files, or page files. Extract key feature names and screen descriptions.
+
+6. **The user flow / happy path** ,  scan beyond marketing pages. The brag's strongest material is usually the product *in use*, not the product's marketing of itself. Look at:
+   - **Routes** (`app/`, `pages/`, route files) ,  the screens beyond the landing page.
+   - **Key feature components** ,  the upload form, the editor, the result view, the dashboard.
+   - **State machines, stores, or step components** ,  how a session progresses.
+   - **README "how it works" or "usage" sections** ,  the project's own description of the flow.
+   - **Example or demo folders** ,  sample inputs and outputs the team tested with.
+
+   Identify the 2-3 beats of *using* the product: **entry → key action → result.**
+
+7. **`public/` or `assets/`** ,  note any images, logos, icons. These can be referenced in the composition.
+
+## The 9-question rubric
+
+After reading, answer all nine. Write these down before moving to Step 2.
+
+```
+1. What is the app?
+   One sentence. What does it actually do (or claim to do)?
+
+2. What is the funniest or most impressive claim?
+   The one line from the site that earns a reaction.
+
+3. What is the visual hook?
+   The strongest CSS visual: a color palette moment, a UI element, a diagram, a card.
+
+4. What should be shown from the actual UI?
+   Which section of the site has the most video-worthy content?
+   (Hero? Feature section? Testimonial? The UI mockup?)
+
+5. What is the shortest satisfying video?
+   Would 15 seconds work? 20? What's the minimum to land the joke/claim?
+
+6. What tone fits best?
+   If the user specified a preset, use it.
+   If the user gave freeform direction, preserve it and map it to the nearest preset.
+   If the user did not specify, infer both:
+   - Tone preset: one of the known presets
+   - Creative direction: a short custom phrase for this project
+   Examples:
+   - Absurd product → preset: yc-parody; direction: fake startup launch
+   - Earnest product → preset: polished; direction: quiet premium product film
+   - Chaotic product → preset: chaotic; direction: overproduced social ad
+
+7. What should the audio feel like?
+   Decide the audio role and music direction before picking exact SFX files.
+   Bias toward a polished audio layer: include music and tasteful SFX unless
+   the user disabled them, assets are missing, or silence is clearly the
+   strongest creative choice.
+   Examples:
+   - Warm corporate bed; SFX chosen later to match real UI motion
+   - Low music bed with final fade; one dry logo hit if the composition supports it
+   - Dense chaotic music; Hyperframes may align text/card reveals to beats
+   - Cinematic bed with a low swell, restrained motion-matched accents, and subtle audio-reactive glow/presence if it supports the visual style
+
+8. What should the share caption say?
+   Draft one sentence. This becomes share-copy.txt.
+
+9. What's the user flow worth showing?
+   The 2–3 beats a real user goes through: entry → key action → result.
+   Not the landing page's section list — the working app.
+   Examples:
+   - Upload long video → see it processing with progress → see 3 vertical clips ready
+   - Type a message → assistant types back → user clicks "mark resolved"
+   - Swipe right on Thunder's profile → match animation → chat opens
+   If the project is a landing-page-only static site with no app, write
+   "none — landing-page only" and rely on the strongest visual (Q3) instead.
+```
+
+## Color extraction
+
+When reading CSS, look for custom properties like:
+
+```css
+:root {
+  --primary: oklch(...);
+  --bg: oklch(...);
+  --accent: ...;
+}
+```
+
+If no custom properties exist, scan for the most-used colors in background, color, and border rules.
+
+Write down:
+- Background color (exact value)
+- Primary text color
+- Accent/brand color
+- Any gradient or special treatment
+
+These colors are recorded in `composition-brief.md` and carry into the design spec the current hyperframes-creative workflow scaffolds.
+
+## Font extraction
+
+Look for:
+- `font-family` declarations in `:root` or `body`
+- Google Fonts `<link>` in `<head>` (the font families are in the URL query string)
+- `@import` statements
+
+Write down the display font (used for headings) and the body font separately.
+
+## What to skip
+
+Don't read:
+- Generated build artifacts (`dist/`, `.next/`, `build/`)
+- Lock files (`package-lock.json`, `yarn.lock`)
+- Test files
+- `.git/`
+- Environment and secret files (`.env`, `.env.*`)
+- Credential and key material (`.pem`, `.key`, `id_rsa`, service-account JSON, anything under a `secrets/` or `credentials/` directory)
+- Local config that commonly holds tokens
+- Any file the project's `.gitignore` excludes for the reasons above
+
+## Rule: nothing secret leaves this step
+
+Everything read in this step can end up on screen in a video the user posts publicly. Never carry secrets, API keys, tokens, internal hostnames or URLs, real customer or user names, email addresses, or any personal data into `brag-plan.md`, `composition-brief.md`, the composition, the rendered video, or share copy. If the product's real UI contains such data, substitute plausible fictional stand-ins and say so in the plan.
+