@nerdev/skillset 0.2.1

package/skills/business/brag/references/step-2-plan.md

@@ -0,0 +1,234 @@
+# Step 2: Write the brag plan
+
+Write `<output-dir>/brag-plan.md`. One focused page. This is the creative north star for the entire video.
+
+The plan should specify what the video must communicate and what project material must be used. It should not prescribe low-level Hyperframes implementation details. Hyperframes will decide the concrete composition structure, animation mechanics, and render workflow from the brief in Step 3.
+
+## Create the output directory
+
+```bash
+mkdir -p <output-dir>
+```
+
+## Structure of brag-plan.md
+
+```markdown
+# Brag Plan: [App Name]
+
+## What is this app?
+[One sentence. What it does, what makes it funny or impressive.]
+
+## The angle
+[The creative premise. The joke, the hook, the claim.
+What makes this video specific to this project and not generic.]
+
+## Hook (first 2-3 seconds)
+[The opening moment. This is the most important decision.
+What word, image, or motion earns the next 20 seconds?]
+
+## Key moments (the middle)
+[2-3 sharp highlights from the product.
+Bullet points. Specific. "The altitude meter counting up." 
+Not "feature callouts."]
+
+## Outro / punchline
+[How does it land? The final line. The beat before the logo.]
+
+## User flow worth showing
+[The 2–3 beats of *using* the product (entry → key action → result), pulled from
+Step 1 question 9. This is the strongest material the video has — the centerpiece
+scenes should show the flow, not just landing-page sections. If the project is
+landing-page-only, write "none — landing-page only" and rely on Key moments instead.]
+
+## Tone
+- Preset: [default / polished / yc-parody / chaotic / deadpan / cinematic / app-store]
+- Creative direction: [freeform phrase, inferred or user-provided]
+- Interpretation: [one sentence on how this affects pacing, writing, visual energy, and restraint]
+
+## Format: [landscape / vertical / square] — [width]x[height]
+## Duration: [target seconds]
+
+## Visual identity (from the project)
+- Background: [exact color value]
+- Accent: [exact color value]
+- Text: [exact color value]
+- Display font: [name]
+- Body font: [name]
+- Strongest visual element: [what from the site to reference]
+
+## Share copy (draft)
+[One sentence for Twitter/X/LinkedIn/Discord. Punchy. Not corporate.]
+
+## Audio direction
+- Role: [warm bed / sparse professional accents / cinematic support / dense rhythmic layer / intentional silence]
+- Music: [candidate track / mood / none only if disabled, missing, or intentionally silent]
+- Music treatment: [start time, volume posture, fade-in/out intent, beat/swell notes]
+- Music cue guidance: [preset cue file read / unavailable; list 1-3 strongCue timestamps for major moments; list beat-grid windows for sequential events]
+- Audio-reactive treatment: [none / subtle / expressive; what visual qualities may respond to music energy]
+- SFX posture: [sparse / moderate / dense; motion-matched; professional restraint]
+- Audio-coupled moments: [visual ideas that should consider sound, e.g. typed text, beat reveal, count-up, card sequence]
+- Restraint rule: [what audio must not do]
+
+## Storyboard
+
+### Scene 1 — [name] — [duration]s
+[What's on screen. What text appears. What product material must be referenced.]
+Sequential/interaction: [yes — describe what appears one by one or what interaction is simulated, e.g. "3 stat cards arrive one by one" or "cursor clicks the match button"; or none]
+Audio intent: [what the sound should do emotionally]
+Audio-coupled idea: [typed text, beat-aligned reveal, counter ticks, card-by-card sequence, simulated tap/swipe/type — or none]
+Music: [mood, or "none" only if disabled / missing / intentionally silent]
+Transition mood: [clean / hard / dramatic / soft / chaotic] → Scene 2
+
+### Scene 2 — [name] — [duration]s
+[...]
+Sequential/interaction: [yes — describe it; or none]
+Audio intent: [what the sound should do emotionally]
+Audio-coupled idea: [type or none]
+Transition mood: [mood] → Scene 3
+
+[... continue for all scenes]
+
+**Music mood for this video:** [upbeat / cinematic / chaotic / deadpan / parody / none only if disabled / missing / intentionally silent]
+**Audio summary:** [one sentence describing the full audio arc]
+```
+
+## Planning the scenes
+
+The default pattern is:
+```
+Hook → Reveal → 2-3 highlights → Punchline/outro
+```
+
+But adapt it. These are the right scene counts for each tone:
+
+| Tone | Scenes | Pacing |
+|---|---|---|
+| `default` | 4-5 | Comfortable. Room for each moment to breathe. |
+| `polished` | 3-4 | Fewer scenes, longer holds. Confidence through restraint. |
+| `yc-parody` | 4-5 | Structured. The joke is how seriously it's delivered. |
+| `chaotic` | 6-8 | Rapid. Some scenes under 2 seconds. |
+| `deadpan` | 3-4 | Long holds. Big empty space. One word at a time. |
+| `cinematic` | 4-5 | Wide shots. Big type. Dramatic reveals. |
+| `app-store` | 4-6 | Feature cards. Clean reveals. No mess. |
+
+## Duration guidance
+
+Scene durations must sum to 15-25 seconds. Count them.
+
+- Under 15 seconds: too thin, add a scene or lengthen holds.
+- Over 25 seconds: cut a scene or tighten timing.
+- 18-22 seconds is the sweet spot for most brag videos.
+
+## Reading time (keep the pace, not at text's expense)
+
+High pace comes from fast motion, fast transitions, and tight cuts ,  NOT from pulling text off screen before it can be read. Every text element a viewer must read needs enough fully-visible, settled time (entered, not yet exiting) to actually read it:
+
+- Short label or 1-3 word line: about 0.8s settled.
+- Headline or full sentence: about 0.3s per word, minimum ~1.2s. The hook line gets the most.
+
+Plan that floor, then keep everything else fast: entrances and transitions stay snappy (0.3-0.6s) and motion stays energetic. A line can SLAM in fast and then HOLD ,  fast-in plus an adequate hold reads as punchy AND legible.
+
+Two failure modes to design out at the plan stage:
+
+- **Too much text for the scene length.** A 4s scene lands maybe 2-3 short reads at the floor, not 6. If a scene carries more text than its duration allows, cut copy or split the scene ,  do not speed it up.
+- **Sequential text snapped onto a fast beat.** Beat-grid reveals can land ~0.5s apart at 110+ BPM (this is what rushed the bicycles spec rows). That spacing is fine for accents (glows, dots, ticks) but too fast for readable lines. For sequential TEXT, hold each item to the floor: snap to every other beat, or reveal them quickly and hold the full set on screen afterward. Flag any sequential text reveal in the storyboard with its intended hold.
+
+## Choosing what to show
+
+Every brag video must show something real from the product. Options, in preferred order:
+
+1. **Recreate a working-app moment** ,  the upload screen, the result view, the dashboard with real-looking content. Use real source from `app/`, `pages/`, or routed components ,  not just the landing page. This is the most compelling option whenever the product has a flow. The product *doing* its thing beats the product *describing* its thing.
+2. **Recreate a UI element in HTML** ,  a hero card, swipe UI, progress meter, stat block. Strong when there is no flow to show.
+3. **Animate the core concept** ,  if the product is "taxis for taxis", animate two taxis where one is in the other. Pure graphic but grounded in the idea.
+4. **Text-forward sequence** ,  if the product is copy-driven (Psychologists for Chatbots), let the copy be the visual. Giant display type, minimal chrome.
+
+Never fill scenes with abstract patterns, color washes, or generic motion graphics that could belong to any video.
+
+## Bias the storyboard toward the user flow
+
+If Step 1 question 9 identified a real user flow, the **centerpiece scenes must show that flow** ,  not just landing-page recreations.
+
+Good (working-app scenes):
+- "Upload screen ,  cursor drops a video file. Filename appears. Progress bar fills 0→100% in 1.2s."
+- "Three result thumbnails pop in: 0:15, 0:23, 0:31. Each shows a vertical clip frame with a real-looking caption."
+- "Inbox row appears, gets a green 'resolved' badge, slides off the top of the list."
+
+Avoid (marketing-only scenes when a flow exists):
+- "16:9 → 9:16 transform diagram" ,  that's a *diagram of what the product does*, not the product doing it.
+- "Three stat cards: 10x faster / 0 cuts / 3 clips" ,  that's the landing page's social-proof row, not the product.
+
+Stat cards, headline blocks, and the landing-page hero still have a place ,  but at most one of them, used as a frame around the flow, not as a substitute. The centerpiece is the working app.
+
+If the project has no app (landing-page-only static site), skip this section and recreate the landing-page strongest visual instead.
+
+## Look for interaction and sequential reveal moments
+
+Before writing the storyboard, ask: **does this product have things that can appear one by one, or actions that can be simulated?**
+
+These are among the most effective moments in a brag video ,  they make the product feel alive and real, not like a slide deck. Look for:
+
+- **Sequential reveals** ,  feature cards, stats, list items, match results, profile cards, menu options, or anything the product shows as a set. Design these to appear one by one so sound and motion reinforce each arrival. This is a storyboard decision, not an audio afterthought.
+- **Simulated interaction** ,  if the product involves swiping, clicking, typing, selecting, or toggling, show it. A cursor clicking a button, a swipe gesture on a card, or text being typed into a field turns a static mockup into a demonstration. Sound matches the action automatically when the gesture is in the storyboard.
+
+If a scene has either of these, commit to it explicitly in the scene description:
+- Good: "3 horse profiles slide in one by one, each with a card sound"
+- Good: "Simulate a right-swipe on Thunder's profile card"
+- Good: "The hook line types out character by character with keyboard sounds"
+- Avoid: leaving it vague and hoping Hyperframes adds rhythm on its own
+
+Hyperframes can implement both patterns well ,  but only if the plan specifies what's appearing, in what order, and that interaction is being simulated. The plan is the contract.
+
+## Audio planning
+
+Choose the music direction in the plan. Leave exact SFX file selection and exact timestamps to Hyperframes during composition, because SFX should match the actual visual implementation.
+
+Default posture: include audio. Pick a music bed and a few tasteful SFX unless the user passed `--no-music` / `--no-sfx`, the assets are missing, or silence is explicitly part of the concept.
+
+For each scene, note the intended audio role and likely audio-coupled opportunities:
+
+Format: `Audio-coupled idea: type the hook with subtle key ticks if Hyperframes uses a typing animation.`
+
+For audio-reactive visuals, say what should respond and how restrained it should be. Example: `Audio-reactive treatment: subtle; use music RMS/bass to make the hero glow and product card presence breathe, not to add waveform bars.`
+
+Do not require exact SFX filenames in `brag-plan.md` unless the user explicitly requested a specific sound or the mapping is unavoidable. Prefer moment types and intent.
+
+Hyperframes has creative freedom to choose exact files, density, and timestamps that make the video feel smooth and professional.
+
+Do not over-specify audio if the tone asks for restraint. For `yc-parody` or `deadpan`, use fewer and quieter cues, but prefer polished restraint over no audio.
+
+## Music cue guidance
+
+Beat/cue sync is available for any track now (see `audio.md` → "Beat and cue sources"): bundled tracks have precomputed presets; custom tracks get cues at composition time via `analyze_music_cues.py` (rich, needs Python) or `npx hyperframes beats` (simple, zero-dep). When the plan chooses music, add a compact `Music cue guidance` section to `brag-plan.md`:
+
+- The track and, if a preset exists, its tempo.
+- 1-3 strong-cue timestamps to target for major visual moments ,  from the preset if bundled, otherwise note "to be detected at composition time."
+- Beat-grid windows for any sequential reveals in the storyboard.
+- A restraint note when the tone is deadpan, yc-parody, or otherwise quiet.
+
+See `audio.md` for the cue sources, JSON schema, and beat-sync tolerances.
+
+If SFX are enabled, note likely sound opportunities but leave exact filenames to Hyperframes. Hyperframes should use the skill's `sfx-analysis.md` during composition.
+
+## Handoff posture
+
+- Good: "Recreate the swipe card with Thunder's profile and hay tags."
+- Good: "Use the source site's amber/dark palette and serif headline feel."
+- Good: "The stat reveal should feel like a deadpan startup metric slide."
+- Avoid: "Use a GSAP timeline with this selector and this easing."
+- Avoid: "Use this exact HTML structure."
+- Avoid: "Load this specific runtime URL."
+
+## Transition vocabulary
+
+Match transitions to tone:
+
+| Tone | Preferred transitions |
+|---|---|
+| `default` | Crossfade, clean wipe |
+| `polished` | Soft crossfade, slide |
+| `yc-parody` | Hard cut, minimal |
+| `chaotic` | Hard cut, flash, zoom |
+| `deadpan` | Slow crossfade, long hold |
+| `cinematic` | Dramatic wipe, crossfade |
+| `app-store` | Slide, smooth wipe |
+

package/skills/business/brag/references/step-3-compose.md

@@ -0,0 +1,210 @@
+# Step 3: Hand off to Hyperframes
+
+## Create the composition brief
+
+Write `<output-dir>/composition-brief.md` before creating or editing the Hyperframes composition.
+
+```markdown
+# Hyperframes Composition Brief: [App Name]
+
+## Objective
+Create a short launch-style brag video for [App Name].
+
+## Output
+- Composition directory: `<output-dir>/composition/`
+- Rendered video: `<output-dir>/brag.mp4`
+- Format: [landscape / vertical / square] — [width]x[height]
+- Duration: [15-25 seconds]
+
+## Source Material
+- Project root: [path]
+- Primary files read: [index.html, styles.css, README, etc.]
+- Product name: [name]
+- Tagline / strongest claim: [line]
+- Key UI or visual moment to recreate: [specific element]
+- Copy that must appear verbatim:
+  - [line 1]
+  - [line 2]
+
+## Creative Direction
+- Tone preset: [default / polished / yc-parody / chaotic / deadpan / cinematic / app-store]
+- Creative direction: [freeform phrase, inferred or user-provided]
+- Interpretation: [how tone affects pacing, writing, visual energy, and restraint]
+- Angle: [one paragraph from brag-plan.md]
+- Hook: [first 2-3 seconds]
+- Outro / punchline: [final line]
+- Avoid:
+  - Generic SaaS language
+  - Abstract filler visuals
+  - Unrelated visual redesign
+
+## Visual Identity
+- Background: [exact value from project]
+- Text: [exact value from project]
+- Accent: [exact value from project]
+- Display font: [font or fallback decision]
+- Body font: [font or fallback decision]
+- Visual references from the project: [short list]
+
+## Storyboard
+Use the storyboard in `<output-dir>/brag-plan.md` as the creative contract.
+
+Scene summary:
+1. [Scene name] — [duration]s — [what must be seen / read]
+2. [Scene name] — [duration]s — [what must be seen / read]
+3. [...]
+
+## Audio
+- Audio role: [warm bed / sparse professional accents / cinematic support / dense rhythmic layer / intentional silence]
+- Audio arc: [how sound changes across the video]
+- Music: [filename, or none only if disabled, missing, or intentionally silent]
+- Music treatment: [volume posture, fade-in/out intent, beat/swell notes; e.g. fade under final logo]
+- Music cue guidance: [cue source — bundled preset path, or "detect at composition via analyze_music_cues.py / hyperframes beats" — plus concise optional timing hints; or unavailable]
+- Audio-reactive treatment: [none / subtle / expressive; what visual qualities may respond to RMS/frequency energy]
+- Audio-coupled moments:
+  - [scene/moment] — [typing / beat reveal / counter / card sequence / simulated interaction / final logo]
+  - [scene/moment] — [intent]
+- SFX selection guidance: [how sound should match motion and interaction; examples only, not rigid rules]
+- SFX analysis guidance: [path to sfx-analysis.md/json if present; use lower high-frequency-risk sounds for repeated or polished moments]
+- Exact SFX choice: Hyperframes should choose filenames, timestamps, density, and volume based on the implemented animation.
+- Audio files: copy the chosen music and any Hyperframes-selected SFX into `<output-dir>/composition/assets/`
+
+## Hyperframes Instructions
+Load the composition-building Hyperframes domain skills — `hyperframes-core` (composition contract + `data-*` timing), `hyperframes-animation` (motion), `hyperframes-creative` (design spec, beats, audio-reactive), `hyperframes-keyframes` (seek-safe keyframes), and `hyperframes-cli` (lint/check/render). /brag is its own workflow: do not enter the `hyperframes` entry-point intent interview and do not route into its generic promo / launch-video workflow. Prefer native Hyperframes conventions over anything in `/brag`.
+
+Requirements:
+- Show at least one real UI, copy, or visual element from the source project.
+- Keep all text readable in the final render.
+- Keep the video within 15-25 seconds.
+- Include the planned music/SFX layer unless audio was explicitly disabled or documented as intentionally silent.
+- Treat `/brag` audio notes as guidance, not a fixed cue sheet. Choose SFX after the visual animation exists.
+- Treat music cue metadata as optional timing hints. Hyperframes decides exact animation timing and should ignore cues that hurt readability, scene pacing, or the product story.
+- Major reveals may move toward nearby strong cues within about 0.15s. Smaller entrances may align to nearby beat points within about 0.10s. Use only 1-3 strong cue locks in a 15-25s video unless the edit clearly benefits from more.
+- Use SFX to support motion and interaction: card sounds for card-like reveals, short announcement cues for major payoffs, key/click sounds for text or user actions, and restraint when the edit is already busy.
+- Honor planned music treatment such as fade-outs, ducking, beat-aligned reveals, or letting a final SFX ring over the music, using the best Hyperframes-supported implementation.
+- When music is present and the treatment is not `none`, consider Hyperframes audio-reactive workflow: extract audio data and use RMS/frequency bands for subtle, brand-specific motion. Good targets are glow, depth, background warmth, card presence, title emphasis, or other existing visual elements. Avoid waveform/equalizer visuals, musical-note graphics, generic particle systems, strobing, or heavy pulsing.
+- Use local assets for audio and any required runtime/media dependencies when possible.
+- Run `hyperframes check` before render — it is brag's single gate.
+```
+
+The brief is the boundary: if a detail belongs to product positioning, copy, tone, source material, or selection of moments, `/brag` should specify it. If a detail belongs to composition implementation, Hyperframes should decide it.
+
+---
+
+## Audio asset preparation
+
+Read [audio.md](audio.md). Copy the planned music into `<output-dir>/composition/assets/music/` before building the composition.
+
+```bash
+mkdir -p <output-dir>/composition/assets/music
+cp <skill-dir>/assets/music/<track>.mp3 <output-dir>/composition/assets/music/
+```
+
+`<skill-dir>` is this skill's own directory (see "Skill directory" in `SKILL.md`).
+
+Hyperframes copies any SFX it selects into the same `assets/` tree after choosing exact files.
+
+---
+
+## Voiceover (only when the user explicitly asks)
+
+Voiceover is disabled unless the user explicitly requests it, for example
+with `--voice` or "narrate this". Do not offer or enable narration during a
+normal `/brag` run.
+
+When voice is disabled, do not write a voiceover script, generate narration,
+transcribe audio, duck music, add a voice track, or merge narration into the
+video. The normal video export must remain entirely voice-agnostic.
+
+When voice is enabled, write the narration lines into `brag-plan.md` under a
+`## Voiceover script` section, then generate the audio through Kokoro:
+
+```bash
+npx hyperframes tts "<narration text or path to script>" \
+  --voice af_heart \
+  --output <output-dir>/composition/assets/voiceover.wav
+```
+
+If the user wants a different Kokoro voice, run `npx hyperframes tts --list`
+to see the available options. The command above is the voice implementation
+for this PR and should be used directly.
+
+Wire it into the composition on its own track. Music ducks to 0.12-0.15 for the duration of the voiceover, then returns to its normal level:
+
+```html
+<audio id="vo" data-start="0" data-track-index="3" data-volume="1" src="assets/voiceover.wav"></audio>
+```
+
+Scene durations must flex to match the generated audio ,  check the WAV duration after generation and adjust `data-duration` values accordingly. Do not hardcode scene lengths when voiceover is present; let the voice set the pace.
+
+---
+
+## Audio-reactive extraction (when music is present)
+
+When music is present and the treatment is not `none`, the composition can react to per-frame audio data. **Delegate the extraction to the Hyperframes audio-reactive workflow** ,  `/brag` does not ship an extraction script and must not hardcode a path to one.
+
+In the composition step, follow the audio-reactive guidance owned by the `hyperframes-creative` skill (let that skill locate its own files). It owns the data format, the extraction helper (which ships with that skill, not with `/brag`, so don't hardcode a path to it), and the per-frame sampling pattern. Ask Hyperframes to extract the audio data and wire at least one visual element to it.
+
+If extraction is unavailable (no helper, or ffmpeg missing), note it in the brief and skip audio-reactive ,  do not block the render.
+
+---
+
+## Beat sync (when a cue source is available)
+
+Get a cue source first (see `audio.md` → "Beat and cue sources"): a bundled preset, `analyze_music_cues.py` on any track (needs Python; run via `uv`), or `npx hyperframes beats` (no Python; needs Hyperframes ≥ 0.6.99). The rich sources (preset / `analyze_music_cues.py`) give two arrays; `hyperframes beats` gives one.
+
+- **`strongCues`** ,  high-intensity beats (drops, swells, accents). Use for **major moments**: scene transitions, hero reveals, match payoff, logo landing. Lock 1-3 per video. With `hyperframes beats` (no `strongCues`), take the highest-`strength` beats instead.
+- **`beats`** ,  the full beat grid. Use to **snap small sequential events** into the music's pulse: cards arriving one by one, stats popping in, sequenced SFX hits.
+
+### How to implement
+
+**Major moments (strong cues):**
+1. Load the cue source: the preset/analysis JSON (`strongCues` + `beats`), or the beat-grid JSON that `hyperframes beats` writes (a plain beat list; see the current hyperframes-cli skill for its location).
+2. Pick 1-3 strong timestamps near a planned major visual moment ,  `strongCues`, or the highest-`strength` beats.
+3. Shift the reveal's start time to land within ±0.15s of the cue.
+4. Mark it: `// beat-locked: 5.80s`
+
+**Sequential events (beats):**
+1. Decide how many sequential items there are (e.g. 3 stats, 4 profile cards).
+2. Find the nearest beat to your intended start time for the first item.
+3. Use consecutive beats from that point for each subsequent item ,  snap each within ±0.10s of a beat timestamp.
+4. Mark it: `// beat-grid: stat 1 at 12.65s, stat 2 at 13.17s, stat 3 at 13.70s`
+
+**Readable text vs the beat grid:** if the sequential items are text the viewer reads (stat labels, list rows, callouts) and the beats are close (under ~0.6s apart at fast tempos), do not reveal a new line on every beat ,  it outruns reading (this rushed the bicycles spec rows). Snap to every other beat, or reveal them quickly and hold the full set on screen afterward. Non-text accents (glows, dots, ticks) may still hit every beat. See the reading-time floor in `step-2-plan.md`.
+
+This gives you two layers of musicality: the big moments land on the strongest hits, and the small events tick along with the pulse.
+
+Do not force every tween onto a beat ,  readability and scene pacing come first. If snapping a tween to a beat hurts copy legibility or the product story, use the natural timing instead.
+
+If SFX are enabled, also pass `<skill-dir>/assets/sfx/sfx-analysis.md` as selection guidance. Prefer low high-frequency-risk files for repeated or polished moments. SFX on sequential events should fire at the same timestamp as the visual ,  the sound and motion land together.
+
+---
+
+## Call Hyperframes
+
+After `<output-dir>/brag-plan.md`, `<output-dir>/composition-brief.md`, and selected audio assets exist:
+
+1. Load the Hyperframes domain skills (`hyperframes-core`, `hyperframes-animation`, `hyperframes-creative`, `hyperframes-keyframes`, `hyperframes-cli`) to create or update `<output-dir>/composition/`. /brag is its own workflow ,  do not enter the `hyperframes` entry-point intent interview or route into its generic promo / launch-video workflow.
+2. Pass Hyperframes the composition brief, the brag plan, and the source files it should reference.
+3. Let Hyperframes choose the implementation details.
+4. Run Hyperframes check (the single gate before render).
+5. Render to `<output-dir>/brag.mp4`.
+
+Do not manually copy stale composition snippets from this skill into the output. The point of delegating is to benefit from the latest Hyperframes guidance.
+
+---
+
+## Self-review checklist
+
+Before moving to delivery, verify:
+
+- [ ] `<output-dir>/composition-brief.md` exists.
+- [ ] The brief clearly identifies the exact product moments to show.
+- [ ] The composition uses the current Hyperframes workflow, not a hardcoded `/brag` template.
+- [ ] Music file is copied into `<output-dir>/composition/assets/music/`.
+- [ ] At least one visual element subtly reacts to the music (audio-reactive treatment present), or extraction failure is documented.
+- [ ] At least 1 major tween is beat-locked to a strong cue (a `strongCue`, or the highest-`strength` beat from `hyperframes beats`) within ±0.15s, marked `// beat-locked` (or natural timing was chosen for readability).
+- [ ] Sequential events (cards, stats, list items) snap to consecutive `beats[]` timestamps (±0.10s), marked `// beat-grid` (or natural timing was chosen for readability).
+- [ ] The composition shows at least one real UI, copy, or visual element from the project.
+- [ ] Total duration is 15-25 seconds.
+- [ ] Hyperframes check passes, or any blocker is documented for the user.

package/skills/business/brag/references/step-4-deliver.md

@@ -0,0 +1,168 @@
+# Step 4: Validate, render, and deliver
+
+## Validate
+
+```bash
+cd <output-dir>/composition
+npx hyperframes check   # brag's single pre-render gate — fix every error it reports
+```
+
+Fix all errors. `check` is brag's single pre-render gate , run it and fix everything it reports, including WCAG contrast failures (they gate as errors, not warnings). Each contrast finding carries a suggested compliant color, so apply it or adjust within the palette family and re-run `check` , most fixes need no screenshot. There is no per-element contrast escape hatch for real text. the only bypass is `check --no-contrast`, which skips the entire WCAG pass (all-or-nothing), not a way to accept one borderline element. For exact contrast thresholds, layout escape hatches, and reporting details, use the current hyperframes-cli `check` guidance. `check`'s layout pass backstops the "keep all text readable" creative law , fix any reported overflow.
+
+For a visual gut-check before rendering, optionally capture key frames:
+
+```bash
+npx hyperframes snapshot   # PNG key frames
+```
+
+## Preview
+
+```bash
+npx hyperframes preview
+```
+
+Tell the user the preview is running and give them the localhost URL. Invite them to check it before rendering.
+
+If the user approves or asks to render:
+
+## Render
+
+```bash
+npx hyperframes render --output ../brag.mp4
+```
+
+This outputs to `<output-dir>/brag.mp4` (one level up from the composition directory).
+
+For a faster iteration render:
+```bash
+npx hyperframes render --quality draft --output ../brag.mp4
+```
+
+For final delivery:
+```bash
+npx hyperframes render --quality high --output ../brag.mp4
+```
+
+## Pick the poster frame
+
+The poster is the still shown before the video plays , the first thing anyone sees when it is idle or unplayed. Don't leave it to the raw first frame or an arbitrary timestamp. those land on fades, mid-transitions, blank intro backgrounds, or half-rendered text.
+
+You built this composition, so you already know its strongest moment and exactly when it lands , the hook line, the hero reveal, or the final logo. Pick that beat at a **settled** point: text fully animated in, before it exits (the storyboard timings tell you the safe window). Then extract that one frame full-res with ffmpeg. From `<output-dir>/composition`:
+
+```bash
+# use the timestamp of your strongest settled beat, e.g. 3.2s
+ffmpeg -ss 3.2 -i ../brag.mp4 -frames:v 1 -q:v 2 ../brag.jpg
+```
+
+Aim for a frame that is postable on its own (the "show the thing" law , any frozen frame ought to be shareable). If the pulled frame lands on a transition or mid-animation, nudge the timestamp a few tenths of a second and re-extract.
+
+### Bake the poster as frame 0
+
+A bare `.mp4` has no `poster` attribute , every player and platform picks its own idle thumbnail, and almost all of them grab **frame 0**. Slack, Twitter/X,. Discord regenerate thumbnails server-side and ignore embedded cover-art metadata, so the *only* reliable way to control the idle image everywhere is to make frame 0 *be* the poster.
+
+Replace **only** the first frame's pixels with `brag.jpg`, leaving every other frame and all timing untouched , same duration, same frame count, audio copied through. At 30fps the poster shows for 1/30s before the intro rolls, so it is imperceptible on playback but it is what every thumbnail grabber sees. From `<output-dir>`:
+
+```bash
+ffmpeg -y -i brag.mp4 -i brag.jpg \
+  -filter_complex "[0:v][1:v]overlay=0:0:enable='eq(n,0)'[v]" \
+  -map "[v]" -map 0:a? -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p \
+  -c:a copy -movflags +faststart brag.poster.mp4 \
+  && mv brag.poster.mp4 brag.mp4
+```
+
+The poster (`brag.jpg`) matches the video's dimensions because it was pulled from the same render, so the overlay lines up exactly. Keep `brag.jpg` alongside , it is the custom-thumbnail asset for platforms that accept an upload (Instagram, TikTok, YouTube, Facebook, and the LinkedIn post editor) and the `poster="brag.jpg"` image for any `<video>` that embeds the brag (a gallery card, the user's site).
+
+## Write share copy
+
+Write `<output-dir>/share-copy.txt`.
+
+The share copy ought to be:
+- One to three sentences max
+- Postable as-is to Twitter/X, LinkedIn, or Discord
+- Specific to the project , no generic "excited to share" language
+- Tone-matched to the brag video
+
+`share-copy.txt` is the canonical single caption. Do not put multi-platform variants, long launch notes, or Product Hunt copy in this file.
+
+If variants are useful, write them to a separate optional file:
+
+```text
+<output-dir>/share-copy-variants.md
+```
+
+### Share copy by tone
+
+**`default`:**
+```
+Made [App Name]. It's [what it does, in the project's own absurd terms].
+[The best line from the product.]
+```
+
+**`polished`:**
+```
+Introducing [App Name]: [clean one-liner from the site].
+Built with [stack if notable].
+```
+
+**`yc-parody`:**
+```
+We built [App Name] to solve [problem stated completely seriously].
+[Deadpan feature or stat.]
+```
+
+**`chaotic`:**
+```
+[ALL CAPS CLAIM].
+[App Name] is [wildly overstated description].
+Link below.
+```
+
+**`deadpan`:**
+```
+I made [App Name].
+It [what it does].
+```
+
+**`cinematic`:**
+```
+[App Name].
+[Tagline from the site, verbatim or lightly adapted.]
+```
+
+**`app-store`:**
+```
+[App Name] is now live.
+[Feature 1], [Feature 2], and [Feature 3] — all in one place.
+```
+
+### Example: Taxi for Taxis
+
+```
+Every day, taxis carry us. But who carries the taxis?
+Taxi for Taxis: the ride-hailing app for ride-hailing assets.
+Available in 12 metros.
+```
+
+## Final output structure
+
+After this step, `<output-dir>/` ought to contain:
+
+```
+<output-dir>/
+  brag.mp4                — the rendered video
+  brag.jpg                — the poster (best frame, for <video poster>)
+  brag-plan.md            — the plan and storyboard
+  composition-brief.md    — the Hyperframes handoff brief
+  share-copy.txt          — the share caption
+  composition/            — the Hyperframes project
+    index.html
+    ...
+```
+
+## Telling the user
+
+After everything is done, tell the user:
+- Where the video is (`<output-dir>/brag.mp4`)
+- Where the share copy is
+- One sentence on what the video does creatively
+- Optionally: offer to re-roll a scene, change tone, or try a different angle