@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/remotion-ad-video/references/ad-exemplars.md

@@ -1,186 +0,0 @@
-# Ad Exemplars
-
-A swipe file of strong ad ideas, by category. Use it to raise the quality bar
-above the stock template and to borrow *mechanics*, not copy. The default template
-ad (a tidy hook/pain/demo/proof/cta desk lamp) is a baseline, not the target.
-
-Each exemplar names a hook mechanic, a structure, and why it works. Adapt the
-mechanic to the real product; never reuse another brand's specific copy or claims.
-Two warnings about how to use this file:
-
-- **Copy the frame-level exemplars below, not just the names.** A mechanic name
-  ("UI explosion") degrades into a generic card layout; a timed shot list does not.
-- **Do not copy the structures verbatim either.** The category lists below are all
-  4-beat arcs ending in `cta` — that sameness is a known failure mode. Treat the
-  shapes in "Structure-Diverse Shapes" as equally legal.
-
-## Frame-Level Exemplars (copy the craft, swap the product)
-
-### Notification Hijack — 15s, vertical (uses `ui-takeover`)
-
-The bold version, timed at 30fps. The same product done timidly is shown after.
-
-| Time | What happens | Implementation | Audio |
-|---|---|---|---|
-| 0.0–0.1s | Near-black frame, faint brand-color glow top-center. No logo, no headline — nothing reads "ad". | `ui-takeover` block, scene 1 (0–4s) | silence |
-| 0.1s (f3) | A push notification drops from the top edge and lands with a spring. App icon = product logo, app name = brand, title = the hook line ("Your desk called. It wants better light"). | built-in: banner springPop | `sfx-notification` f3 |
-| 0.7–1.7s | Banner hovers with a barely-visible bob. The viewer's muscle memory reads it as *their* notification. | built-in hover | — |
-| 1.8s (f54) | Banner gets pressed: darkens + dips to 0.96. | built-in press beat (45%) | `sfx-tap` f54 |
-| 1.9–2.5s | The banner expands into the full-bleed product hero (shared-element morph, corners un-round as it grows), small flash on press, landing shake when it fills the frame. | built-in FlipMove expand | `sfx-whoosh` f58, `sfx-impact` f76 |
-| 2.5–4.0s | Headline knife-cuts in word-by-word over the hero (`enter="clip"`), proof line spring-pops (when captions are on, the proof rides the caption track instead — that is the template-wide `hasCaptions` behavior). | built-in | `sfx-reveal-hit` |
-| 4.0s | Whip-left into the demo scene — both scenes push as one camera move. | `transitionOut: "whip-left"` | `sfx-whoosh` on the boundary |
-| 4–9s | `device-frame` demo: screen content "switches pages" at 30%, punch-in at 55%, light impact at 90%. | built-in beats | `sfx-swipe`, `sfx-reveal-hit` |
-| 9–12s | `stat-slam` with `colorMode: "inverted"` — the screen floods brand color, the approved number counts up and locks with shake + flash. | `impact` on the lock frame | `sfx-count-tick` ×n, `sfx-impact` |
-| 12s | Luma-wipe into the CTA (panel sweeps, cut hides under cover). | `transitionOut: "luma-wipe"` | `sfx-swipe` |
-| 12–15s | `cta-card`: button winds up, springs past 1, squashes on landing, pulses with a looping sheen; confetti; CTA holds to the end. | built-in | `sfx-bass-drop`, `sfx-success` |
-
-Voiceover (5 beats, word-synced `captions` with `emphasis` on the operative
-words): hook question → pain jab → demo verb line → the number → spoken CTA.
-
-**The timid version of the same product** (what this file exists to prevent):
-fade in a centered title card → screenshot with three bullet points → "4.8/5"
-as static text → logo + button. Every beat is a fade, nothing reacts to
-anything, and the ad could belong to any competitor.
-
-### 99% Squeeze — 12s, vertical (uses `charge-reveal`, scene 1 = 0–4s)
-
-Beats scale to the scene length (rush ends ~26%, slam lands ~63% — use
-`chargeTimings(sceneFrames)` from `src/ChargeBar.tsx` for exact frames,
-including `tickFrames` for the per-tick SFX). For a 4s charge scene at 30fps:
-
-| Time | What happens | Implementation | Audio |
-|---|---|---|---|
-| 0–1.0s | Cold open on the percent counter already RUSHING 0→88 with the bar's glow head streaking. No setup — momentum is the hook. | `charge-reveal` block, rush beat | `sfx-riser` |
-| 1.0–2.5s | The crawl: 88→99 in discrete +1 ticks, bar trembling harder near the top, charging label ("CALIBRATING LIGHT…") cycling its dots. Each tick is a micro-event. | built-in crawl beat | `sfx-count-tick` on each `tickFrames` entry |
-| ~2.5s | Dead stop at 99%. Two frames of nothing — the inhale. | built-in hold | silence (cut the riser) |
-| ~2.55s | SLAM to 100%: fill overshoots, full-frame white flash, screen shake, confetti from the bar tip, and the label flips to the payoff headline popping in word-by-word. | built-in slam | `sfx-impact` + `sfx-success` same frame |
-| 2.6–4s | The payoff line holds while the bar settles — let it be read. | built-in | — |
-| 4s | Zoom-punch into the payoff demo (the thing that is now "ready"). | `transitionOut: "zoom-punch"` | `sfx-bass-drop` |
-| 4–8s | Demo of the unlocked result. | per concept | — |
-| 8–12s | Proof beat and CTA per the concept. | — | — |
-
-Why it works: the 99% stall is loss-aversion — the viewer physically cannot
-scroll away one percent before completion. The payoff line lands *with* the
-release, so the value proposition is welded to a dopamine beat.
-
-## Structure-Diverse Shapes
-
-Legal, encouraged shapes beyond "4 beats ending in cta". If all three concepts
-in `concepts.json` are 4-beat-cta arcs, at least one is not a real alternative.
-
-- **CTA-early echo** — `["ui-takeover", "cta-card", "proof-montage", "cta-echo"]`:
-  the CTA lands at second 4 while attention is at its peak, then proof keeps
-  earning it, and a 1-second CTA echo closes. Works for products with instant
-  comprehension.
-- **Triple escalation** — `["action-1x", "action-10x", "action-100x", "cta"]`:
-  the same core action repeated three times at absurdly increasing scale
-  (surreal-scale ramp). The repetition *is* the structure.
-- **Countdown inversion** — `["charge-reveal", "payoff-blowout", "cta"]`: the
-  meter/countdown is the whole first act; everything after is release.
-- **Single take** — `["one-take-morph"]` ×3 scenes chained with `hero-morph` /
-  match cuts so the spot reads as one continuous camera move through before →
-  during → after. No hard cuts at all is itself a pattern interrupt.
-
-## Ecommerce / Physical Product
-
-- **Cold-open payoff** - open on the after-state (glare gone, stain lifted, knot
-  untangled), then reveal the product that caused it. Structure:
-  `["cold-open-payoff", "cause-reveal", "demo", "cta"]`. Works because it earns the
-  first 2 seconds before asking for attention.
-- **Same-object snap** - hold one object in frame and snap between the old way and
-  the product way on a beat. `["split-before-after", "snap-compare", "proof", "cta"]`.
-- **Oddly-satisfying loop** - a single tactile action (peel, click, pour, fold)
-  shot huge and looped. `["macro-loop", "product-reveal", "benefit", "cta"]`.
-
-## SaaS / Tool / App
-
-- **Impossible demo** - show an end result that looks too fast, then reveal the
-  product doing it. `["impossible-result", "how-reveal", "proof", "cta"]`.
-- **UI explosion** - a real screenshot bursts its capabilities outward as labeled
-  shards. `["screenshot-lock", "feature-explosion", "payoff", "cta"]`.
-- **Chat becomes action** - message bubbles transform into completed work.
-  `["chat-open", "bubbles-to-done", "proof", "cta"]`.
-
-## Game / App Store
-
-- **Gameplay spectacle** - imitate the core loop (merges, swaps, collisions, near-
-  fail rescues, reward cascades) instead of explaining features.
-  `["cold-open-gameplay", "escalation", "reward-burst", "cta"]`.
-- **Score-HUD climb** - a score, combo, or coin counter bursts upward like an
-  in-game HUD. `["gameplay-hook", "score-climb", "level-up", "cta"]`.
-
-## Social / Short-Video App
-
-- **Feed-native imitation** - a phone frame scrolls, swaps, and reacts so the ad
-  feels like the platform itself. `["feed-scroll", "creator-clip", "shop-or-live", "cta"]`.
-- **POV ritual** - first-person hands perform the product's core gesture.
-  `["pov-hands", "one-tap-tune", "settle", "cta"]`.
-
-## Numeric-Proof-Led (any category, only with source-backed numbers)
-
-- **Stat slam** - the strongest approved number lands huge in the first second,
-  then the product earns it. `["stat-slam", "earn-the-number", "proof", "cta"]`.
-  Animate the value (count, snap, roll, meter-fill) toward the exact approved
-  figure; never inflate.
-
-## Spectacle / Exaggeration Mechanics
-
-Reach for these to push a concept past "tasteful" into bold. Dramatize the
-*feeling* — every factual or numeric claim still stays honest and source-backed.
-The token in parentheses is the exact `spectacleMove` value for `concepts.json`.
-
-- **Surreal scale** (`surreal-scale`) - blow one element up past physical sense:
-  a phone the size of a skyscraper, a single feature filling the sky, the
-  product as a planet. `["surreal-scale-hook", "earn-the-scale", "proof", "cta"]`.
-- **Impossible physics** (`impossible-physics`) - gravity flips, time freezes
-  mid-air, the UI shatters into shards, liquid runs upward, the room folds. The
-  product is the cause. `["impossible-physics", "cause-reveal", "payoff", "cta"]`.
-- **World-bending** (`world-bend`) - the product warps the world around it: the
-  room recolors, the street reshapes, the feed bends toward the user.
-  `["world-bend", "ripple", "benefit", "cta"]`.
-- **Hyperbolic before/after** (`hyperbolic-before-after`) - the "before" world
-  is a comic disaster (chaos, clutter, doom-spiral), then it snaps to perfect on
-  a single beat. Lean the contrast to the extreme.
-  `["disaster-before", "snap-fix", "after-bliss", "cta"]`.
-- **Maximal kinetic burst** (`maximal-kinetic-burst`) - whip pans, snap zooms,
-  match cuts, and an impact on every beat so the spot feels overclocked.
-  `["kinetic-cold-open", "escalation", "drop", "cta"]`.
-- **Dramatized stakes** (`dramatized-stakes`) - exaggerate the consequence of
-  *not* using the product to absurd, funny, or epic scale, then the product
-  rescues the moment. `["stakes-blowup", "rescue", "relief", "cta"]`.
-- **UI comes alive** (`ui-comes-alive`) - the interface behaves like a physical
-  being: a notification gets pressed and swallows the screen (`ui-takeover`), a
-  button outgrows its container, chat bubbles do the work.
-  `["ui-takeover", "ui-acts", "payoff", "cta"]`.
-- **Time break** (`time-break`) - the spot manipulates time itself: a freeze
-  with a record-scratch, a countdown that refuses to finish (`charge-reveal`),
-  a rewind that replays the disaster in reverse.
-  `["charge-reveal", "payoff-blowout", "cta"]`.
-
-Rule: one outrageous mechanic carried at full volume beats five timid flourishes.
-If the spot has no "wait, what?" beat, it is not bold enough yet.
-
-## Hook Mechanics To Reach For
-
-Pattern interrupt, bold approved stat, a question the viewer wants answered,
-visual surprise, the after-state first, a negative hook ("stop doing X"), an
-unexpected use, a satisfying loop, format-native imitation, surreal scale,
-impossible physics, hyperbolic before/after.
-
-## Cliche Ban List
-
-Reject these openers and any close paraphrase. They signal template-filler, not an
-idea. `validate-creative.mjs` rejects the worst of them in `hookLine`/`angle`.
-
-- "Meet your / Meet the ..."
-- "Introducing ..."
-- "The future of ..."
-- "Say goodbye to ..."
-- "Game changer" / "game-changing"
-- "Next level" / "take it to the next level"
-- "Revolutionary"
-- "Unleash ..."
-- "Elevate your ..."
-- "World-class"
-
-Prefer concrete, specific, benefit-led lines tied to the product's real moment.

package/skills/remotion-ad-video/references/ad-intake.md

@@ -1,54 +0,0 @@
-# Ad Intake
-
-## Required Inputs
-
-Use the smallest reliable source set:
-
-- `source_url`: Product page, Google Play link, App Store link, landing page, or brief.
-- `product_name`: Product, app, or service name.
-- `target_customer`: Who the ad is for.
-- `pain_or_desire`: Main problem, outcome, or use case.
-- `conversion_goal`: Install, buy, trial, lead, waitlist, or retargeting.
-- `size_preset`: Vertical, square, landscape, or a platform-specific alias.
-- `duration_seconds`: 15, 30, or 45 unless the user asks otherwise.
-- `assets`: Logo, screenshots, product images, clips, music, SFX, voice, fonts.
-- `rights_status`: User-owned, licensed, generated, public reference only, or unknown.
-
-If the user supplies only a URL, ask the compact questions in `preflight-questionnaire.md` only when the missing choice changes the output. Otherwise infer defaults and record them.
-
-Recorded default:
-
-- `audio_mode`: default `sfx-only`; ask only when the user requests silent-safe,
-  music plus SFX, voiceover, or a specific sound direction.
-
-## Source Confidence Tags
-
-Tag every claim:
-
-- `observed`: Directly visible in supplied or inspected source.
-- `user_supplied`: Provided by the user.
-- `inferred`: Reasonable interpretation, must be phrased softly.
-- `blocked`: Not safe to use until confirmed.
-
-Do not render `blocked` claims.
-
-## Extraction Checklist
-
-For product pages:
-
-- Product name, category, price or offer, main benefit, proof points, images, variants, shipping or guarantee, CTA.
-
-For app store pages:
-
-- App name, category, rating count, screenshots, core features, target user, pricing or trial, privacy-sensitive claims.
-
-For SaaS or landing pages:
-
-- Value proposition, problem, workflow, differentiators, proof, integrations, target segment, CTA.
-
-## Safety Rules
-
-- Do not include secrets, tokens, one-time IDs, personal data, or private customer content in prompts, docs, screenshots, or videos.
-- Do not assume reviews, app screenshots, music, logos, or product photos are commercially reusable.
-- Regulated claims need supplied approved copy.
-- Note whether Remotion commercial licensing needs review for the intended use.

package/skills/remotion-ad-video/references/asset-harvest.md

@@ -1,56 +0,0 @@
-# Asset Harvest
-
-## Minimum URL Harvest
-
-When the user gives a product, app, or landing-page URL, fetch safe public assets before designing the ad:
-
-- HTML metadata: title, description, canonical URL.
-- Open Graph image: `og:image`.
-- Favicon and apple touch icon.
-- Public logo image when clearly linked.
-- Public product/app screenshots when clearly part of the marketing page.
-- CSS color tokens or obvious brand colors.
-
-For ecommerce product URLs, the product page is the source of truth. Run the
-root harvester before writing creative:
-
-```bash
-node scripts/harvest-ecommerce-assets.mjs "<product-url>" --brand "<brand>" --out-dir <public-brand-dir>
-```
-
-Product-link rules:
-
-- Product main image is mandatory for a product-first ad when the page exposes one.
-- Search engines are last-resort fallback only; never use search before trying the supplied product URL.
-- Do not treat platform chrome, category banners, empty-state art, app-store badges, logo files, risk/challenge pages, or generic brand imagery as product photos.
-- If the harvester reports `blocked: true` or exits with `Main image: not harvested`, stop the production path and report the blocker. Do not make a fake product ad from placeholders.
-- If the user's own browser can open the page but headless/curl cannot, use a browser-backed extraction mode or ask for browser access/image URLs instead of switching to search.
-- If crawler plus browser-backed extraction still cannot get the product image, stop and ask the user to provide product images/screenshots. Do not generate or search a substitute for the product main image.
-- Ecommerce copy should introduce the linked item first; platform or store context can be secondary proof only.
-
-Store harvested assets under the generated example or target project `public/<brand>/` folder and reference them with Remotion `staticFile()`.
-
-When practical, create an asset manifest after harvesting:
-
-```bash
-node skills/remotion-ad-video/scripts/build_asset_manifest.mjs <public-brand-dir> --brand <Brand> --source <URL> --out <public-brand-dir>/asset-manifest.json
-```
-
-## Use Rules
-
-- Use the product/app's own logos, icons, screenshots, feature graphic, and OG images as creative assets by default. They are standard inputs for the install/UA/affiliate ads this skill produces; do not stall waiting for "rights confirmation" on the advertised product's public store assets.
-- Keep genuinely off-limits material out unless the user confirms rights: licensed/third-party music, celebrity or identifiable-person likeness, and paid stock/fonts. When a page mixes in other products (e.g. "similar apps"), only use assets that belong to the product being advertised.
-- The advertiser owns final trademark/licensing decisions for their channel; flag residual responsibility in the handoff, do not block the build.
-- Prefer local copies for stable renders.
-- Keep the asset source URL and rights status in the source summary.
-- Keep asset dimensions, inferred type, source URL, and rights status in `asset-manifest.json` when generated.
-- If no product visual is available, create a custom motion graphic instead of leaving an empty placeholder.
-
-## Minimum Visual Bar
-
-Do not ship an ad that is only text panels. Every commercial sample should include at least one of:
-
-- Product screenshot or app screenshot.
-- Logo/icon plus animated product UI reconstruction.
-- OG/hero image.
-- Generated or custom-coded motion scene that visualizes the product outcome.

package/skills/remotion-ad-video/references/audio-caption-system.md

@@ -1,202 +0,0 @@
-# Audio and Caption System
-
-Use this when adding music, sound effects, voiceover, captions, or silent-autoplay readability. Short-form ads should work with sound on and still read with sound off.
-
-## Audio Layers
-
-Prefer three separate layers:
-
-- `musicBed`: beat or loop that defines cut timing.
-- `sfx`: whoosh, pop, snap, coin, click, glitch, riser, impact, or UI sound.
-- `voiceover`: scripted narration that drives the hook, benefit, and spoken CTA.
-
-Do not use copyrighted music, voices, or celebrity likenesses unless the user supplies rights-cleared assets. A generated TTS voice is allowed: mark it `rightsStatus: generated`.
-
-## Audio Posture By Job Type
-
-The soundscape scales with the ambition of the job, not a single global default:
-
-- Quick URL jobs, fast tests, and first-pass iterations: `sfx-only` with short generated interaction sounds (or `silent-safe` if the user asks). Keep it cheap and fast.
-- Commercial-quality requests, batch variants, or any "make it more creative / bolder" ask: default to a full soundscape — `music-sfx` plus a scripted `voiceover` — not bare `sfx-only`. A bold ad with no voice and a single repeated click sounds thin. Plan the music bed, dense SFX, and voiceover together.
-- Always honor an explicit user audio choice over these defaults.
-
-Audio is a default implementation detail, not a required preflight or QA gate. Do not interrogate the user about audio; pick the posture from the job type and proceed.
-
-## Music Bed Decision
-
-- Keep URL jobs on `sfx-only` by default.
-- Use `music-sfx` only when the user asks for music, sound polish, a platform-native sound plan, or supplies a rights-cleared track.
-- A music bed must be generated, licensed, or user-supplied. Never imply commercial reuse of platform music or trending songs from the source page.
-- When using generated music, prefer a short loopable bed with a stable BPM so cuts and SFX can land on beat.
-- When using user-supplied or licensed music, record source, license status, and allowed usage in the asset manifest or handoff.
-
-## Voiceover Scriptcraft
-
-When the job uses voiceover, treat it as a performance, not a flat readout of the
-on-screen text. A rich voiceover is what makes an ad feel alive.
-
-- Write a `voiceover` script with explicit beats, not one run-on sentence. A 15s
-  spot usually has 3-5 spoken beats: a spoken hook, one or two benefit/proof
-  beats, and a landed CTA. Give each beat its own line.
-- The spoken hook should NOT just read the on-screen headline. Let voice and text
-  play off each other — voice asks, text answers; voice teases, text reveals.
-- Vary the delivery across beats. Annotate each line with a short `delivery` note:
-  energy (whisper -> shout), pace (slow burn -> rapid-fire), and tone (deadpan,
-  hyped, conspiratorial, urgent, warm). Flat, even narration is the failure mode.
-- Use punchy fragments and concrete verbs over full grammatical sentences.
-  "Glare? Gone. One tap." beats "This lamp will reduce the glare on your screen."
-- Build to a peak. The energy should rise into the CTA so the spoken close lands
-  the action ("Tap to try it." / "Get it free."), not trail off.
-- Keep it tight: roughly 30-40 spoken words for 15s so the voice has room to
-  breathe and hit beats; never wall-to-wall talk. Leave gaps for SFX and music
-  to punch through.
-- Match `outputLanguage` from `ad-brief.json`. Write the voiceover in the video's
-  language, and caption it exactly if captions are on.
-- A generated TTS voice is fine (`rightsStatus: generated`). Pick a voice persona
-  that fits the brand energy and note it in the track. Never imitate a real,
-  identifiable, or celebrity voice without cleared rights.
-- Each `voiceover` track maps to its beat with `sync.sceneId` / `sync.anchor` and
-  `startFrame` like any other cue, so lines land on the picture.
-
-Voiceover beat example:
-
-```json
-{
-  "kind": "voiceover",
-  "rightsStatus": "generated",
-  "persona": "hyped, fast, confident",
-  "lines": [
-    { "text": "Still squinting at your screen?", "delivery": "conspiratorial, slow", "sync": { "sceneId": "hook", "anchor": "scene-start" } },
-    { "text": "One tap. Glare gone.", "delivery": "snap, punchy", "sync": { "sceneId": "demo", "anchor": "visual-lock" } },
-    { "text": "Your desk, finally calm.", "delivery": "warm, settling", "sync": { "sceneId": "benefit", "anchor": "headline-enter" } },
-    { "text": "Tap to try it free.", "delivery": "rising, urgent CTA", "sync": { "sceneId": "cta", "anchor": "cta-land" } }
-  ]
-}
-```
-
-The `lines` array above is the voiceover *script*. In the Remotion template each
-spoken beat renders as its own audio track carrying the generated clip via `src`
-or `preset` plus its `startFrame`/`sync`; the template audio schema strips unknown
-fields, so do not expect a raw `lines` array in props to produce sound.
-
-## Sync Discipline
-
-- Every SFX track must map to a visible event: tap, click, swipe, card pop, score burst, block placement, CTA button press, transition, or reward.
-- Write a cue sheet with `frame/time -> scene -> visual event -> sound` before final render when SFX are included.
-- Prefer short interactive sounds over a generic music bed for test drafts.
-- For `sfx-only`, generate or include small click/pop/whoosh/impact sounds before rendering; do not downgrade to `silent-safe` just because the user did not provide audio.
-- If a sound does not have a clear on-screen trigger, remove it. A silent-safe ad is better than mismatched audio.
-- Place cues within roughly 2-4 frames of the visual event unless intentionally leading a transition.
-
-## Frame-Locked Cue Sheet
-
-- Use exact `startFrame` for generated template SFX whenever the composition fps is known; keep `startSecond` as a readable mirror of `startFrame / fps`.
-- Use `durationFrames` for short hits that must not smear across cuts. Use `durationSecond` only for external music, voiceover, or clips whose source timing matters more than frame trimming.
-- Each SFX cue should include `sync.sceneId`, `sync.anchor`, and optional `sync.offsetFrames` so the sound can be audited against a visible scene event.
-- Valid anchors should describe the picture event, for example `scene-start`, `scene-cut`, `headline-enter`, `visual-lock`, `metric-count`, `cta-land`, `transition-lead`, or `reward`.
-- Treat a cue without `startFrame` or `sync.anchor` as a draft placeholder, not a final sound pass.
-
-## SFX Palette
-
-Use a varied palette instead of repeating one click or pop:
-
-- Core UI: click, tap, pop, notification, success.
-- Motion: swipe, whoosh, riser, stinger, impact.
-- Game/app reward: coin, combo, burst, level-up, fail-rescue.
-- Ecommerce/product: tactile snap, fabric, pack open, reveal hit, comparison snap.
-- Social/feed: sticker pop, glitch, live ping, shop tap, camera shutter.
-- Physical product: light switch, pack open, camera shutter, tactile snap, reveal hit.
-- Proof/metric: count tick, sparkle, soft chime, notification.
-- Bass/impact: sub boom, bass drop, impact, stinger.
-
-Pick sounds by visual event and audio category. A 15s ad should usually use at least twelve distinct generated or rights-cleared SFX presets across product, transition, impact, UI, metric, reward, and notification categories unless the creative is intentionally restrained.
-
-## Cue Density
-
-- For `sfx-only`, plan roughly 8-14 picture-locked cues in a 15s ad.
-- Use 0.5-1.5s spacing for high-energy social, game, and ecommerce ads; use fewer cues for premium or enterprise SaaS.
-- Reserve risers for lead-ins, impacts for hook/CTA landings, and success sounds for final confirmation.
-- If two visual events happen within 5 frames, use one stronger sound rather than stacking muddy hits.
-
-## Mix Targets
-
-- Generated SFX should be clearly audible but short; start around 0.35-0.75 volume and reduce repeated hits.
-- Music beds should sit under SFX around 0.16-0.35 volume.
-- If voiceover is present, lower music and nonessential SFX under speech.
-- Treat near-silent output as blocking when `audio.enabled=true` and `audio.mode` is `sfx-only`, `music-sfx`, or `voiceover`.
-
-## Implementation Contract
-
-- Store local audio under `public/<brand>/audio/` and reference it with `staticFile()`, or use generated data-URI WAV clips / template presets for small template/test SFX.
-- Set `audio.enabled` to `true` only when at least one track is present.
-- Use one track per music bed, SFX hit, or voiceover clip so cuts can be timed precisely.
-- Each track should include `kind`: `musicBed`, `sfx`, or `voiceover`.
-- Each SFX track should include an audio category such as `product`, `transition`, `impact`, `ui`, `metric`, `reward`, or `notification`.
-- Each generated template track should use a named `preset`; external tracks should use `src`.
-- Each SFX track should include an `event` that names the visible trigger.
-- Each final SFX track should include exact `startFrame`; include `durationFrames` for clipped hits and `sync.sceneId` / `sync.anchor` for reviewable cue timing.
-- Each audio track must include `rightsStatus`: `user_supplied`, `licensed`, `generated`, `public_reference`, or `needs_verification`.
-- A `voiceover` track may carry multiple `lines`, each with its own `text`, `delivery` note, and `sync`, or be split into one track per spoken beat. Either way, every spoken beat needs picture-locked `sync`. Record a `persona` for the voice. A generated TTS voiceover uses `rightsStatus: generated`.
-- For silent-safe drafts, set `audio.enabled` to `false` and keep on-screen copy readable without sound.
-
-## Timing
-
-- Align scene cuts, sticker pops, score bursts, and CTA pulses to beat moments.
-- In 15s ads, use audio events roughly every 0.5-1.5 seconds.
-- Reserve the biggest impact sound for the hook payoff or CTA.
-- Keep voiceover to roughly 30-40 spoken words for 15s across 3-5 beats; leave breathing gaps so SFX and music land. See `Voiceover Scriptcraft`.
-
-## Captions
-
-- Captions should support the ad, not duplicate every on-screen word.
-- Use 1-2 short lines, high contrast, and safe-area margins.
-- Burn in essential CTA or offer text for silent autoplay.
-- If voiceover is present, caption claims exactly and keep source-backed proof separate.
-
-### Karaoke captions (Remotion `CaptionTrack`)
-
-Most feeds play muted — without burned-in, word-synced captions the voiceover
-effectively does not exist. Whenever the ad has a voiceover track, also fill
-`props.captions` (the template renders them via `src/CaptionTrack.tsx` as a
-global layer that survives scene cuts):
-
-```json
-"captions": [
-  { "text": "Your desk deserves better light",
-    "startFrame": 12, "endFrame": 58,
-    "words": [
-      { "w": "Your", "atFrame": 12 },
-      { "w": "desk", "atFrame": 18 },
-      { "w": "deserves", "atFrame": 26 },
-      { "w": "BETTER", "atFrame": 36, "emphasis": true },
-      { "w": "light", "atFrame": 44 }
-    ] }
-]
-```
-
-- One entry per spoken sentence; use the same timestamps as the voiceover
-  audio track so the words land on the voice.
-- Each word pops in on its beat; the word being spoken is lit in the accent
-  color; `emphasis: true` words land bigger, tilted, and stay lit in the
-  accent color — mark the numbers, pain words, and brand names.
-- Omit `words` to spread the words evenly across the window (fine for drafts;
-  per-word beats read better).
-- On `colorMode: "inverted"` scenes the caption accent automatically swaps to
-  the background color for contrast — no extra work needed.
-
-## Platform Notes
-
-- TikTok/Reels/Shorts: punchy SFX, rhythmic cuts, captions low or mid-low.
-- Games: combo, burst, reward, fail-rescue, and level-up sounds.
-- SaaS/productivity: click, complete, send, success, notification, whoosh.
-- Ecommerce: tactile product sounds, reveal hits, comparison snaps.
-
-## Optional Audio Review
-
-Only do this when the user explicitly asks for audio review, music, voiceover,
-silent-safe output, or platform-specific sound polish:
-
-- Sound-on check: audio reinforces cuts instead of feeling pasted on.
-- Rights check: every music, SFX, and voice asset has a rights status.
-- Mix check: voice and key SFX are not buried by music.
-- Stream check: use `ffprobe` only when audio deliverables are part of the ask.

package/skills/remotion-ad-video/references/concept-contract.md

@@ -1,128 +0,0 @@
-# Concept Contract
-
-`concepts.json` is the mandatory creative artifact between Strategy and Storyboard.
-It exists for the same reason `ad-brief.json` does: to stop the ad from collapsing
-into a reskin of the stock template. The brief captures *what is true*; the concept
-artifact captures *what idea we are betting on*.
-
-## When To Create It
-
-- Create `concepts.json` after `ad-brief.json` and before any storyboard or code —
-  for **every** job, not only commercial-quality requests. Fast tests and quick URL
-  jobs may use a lean version (3 concepts, one-line fields), but they do not skip
-  the gate: lower resolution is allowed, lower creativity is not. Skip only when
-  the user dictated one exact direction.
-- Validate it before building:
-
-```bash
-node scripts/validate-creative.mjs examples/<brand>-ad/concepts.json
-```
-
-- Do not start the storyboard until the gate passes. A failing gate means the
-  concepts are not yet distinct, scored, or chosen.
-
-## Shape
-
-```json
-{
-  "schemaVersion": "1.0",
-  "sourceUrl": "https://example.com/product",
-  "productName": "Product",
-  "defaultArc": ["hook", "pain", "demo", "proof", "cta"],
-  "concepts": [
-    {
-      "id": "glare-kill",
-      "label": "Glare Kill",
-      "angle": "One sentence describing the creative bet.",
-      "insight": "The sharp customer tension or surprising truth this ad weaponizes.",
-      "hookLine": "3 to 8 words",
-      "firstFrame": "What is visible at frame 0-30.",
-      "structure": ["cold-open-payoff", "cause-reveal", "angle-dim-focus", "cta"],
-      "motionIdea": "The main moving system.",
-      "signatureMoment": "The one frame only this product could own - a competitor could not swap their logo in. Reference the product's own element, interaction, or claim.",
-      "spectacleMove": "surreal-scale",
-      "proof": "Source-backed or user-supplied evidence only.",
-      "cta": "One action.",
-      "risk": "Rights, claim, or production concern.",
-      "scores": {
-        "attention": 5,
-        "nativeFit": 4,
-        "productProof": 4,
-        "conversion": 4,
-        "productionFeasibility": 4,
-        "claimSafety": 5,
-        "distinctiveness": 4,
-        "boldness": 5
-      }
-    }
-  ],
-  "chosenId": "glare-kill",
-  "selectionNote": "Why this concept beat the others, plus any beat grafted from a runner-up."
-}
-```
-
-## Gate Rules
-
-The validator enforces the parts that can be checked mechanically:
-
-- 3-6 concepts, each with a unique `id` and a unique `hookLine`.
-- Every concept declares `angle`, `insight`, `hookLine` (3-8 words), `firstFrame`,
-  `structure` (>= 3 scene blocks), `motionIdea`, `signatureMoment`,
-  `spectacleMove`, `proof`, `cta`, and all eight `scores` as integers 1-5.
-- `signatureMoment` is one sentence describing the frame only this product could
-  own — if a competitor could swap their logo in, it fails the spirit of the
-  field (validator floor: >= 10 chars after trim; the spirit is checked by you,
-  not the machine). `spectacleMove` must be one of: `surreal-scale`,
-  `impossible-physics`, `world-bend`, `hyperbolic-before-after`,
-  `maximal-kinetic-burst`, `dramatized-stakes`, `ui-comes-alive`, `time-break` —
-  the tokens match the mechanics in `ad-exemplars.md` (Spectacle / Exaggeration
-  Mechanics); the "wait, what?" beat is a checkable field, not a vibe.
-- `scores` includes `boldness`: how exaggerated, dramatized, and visually loud the
-  concept is. A tasteful, reasonable, "presentation-safe" idea scores low here on
-  purpose. Boldness rates the creative register, never the truth of a claim.
-- Concepts must not all share one `structure`; they must be genuine alternatives.
-- `hookLine`, `angle`, and `label` must avoid banned cliche copy (see
-  `ad-exemplars.md`).
-- `chosenId` must reference a real concept and carry a `selectionNote`.
-- The chosen concept must score `attention` >= 4, `distinctiveness` >= 4, and
-  `boldness` >= 4, with `claimSafety` >= 3. A merely-acceptable 3 on attention,
-  distinctiveness, or boldness no longer ships - pick or revise a bolder concept.
-- The chosen concept's `structure` must not equal `defaultArc` unless it sets a
-  `forceDefaultReason`. The stock hook/pain/demo/proof/cta arc is a fallback, not
-  a default.
-
-## Scene Block Structure
-
-`structure` is an ordered list of scene-block kinds, not the stock five scenes.
-Use it to plan an arc that fits the chosen idea: for example
-`["cold-open-payoff", "cause-reveal", "snap-compare", "cta"]`,
-`["pov-hands", "one-tap-tune", "focus-settle", "cta"]`, or
-`["stat-slam", "rapid-features", "proof-burst", "cta"]`. Map these blocks to the
-actual Remotion scenes during storyboard. If two different concepts produce the
-same arc, at least one of them is not a real alternative.
-
-## Template Blocks
-
-The Remotion template renders each scene by its `block` field, so the chosen
-`structure` becomes distinct layouts and motion instead of one repeated card. Map
-your structure onto these built-in blocks (or add a new block component):
-
-- `cold-open-payoff` - full-bleed visual first; headline slams in late.
-- `split-before-after` - kinetic split; dim "before" half vs colored "after" half.
-- `device-frame` - content inside a phone frame; feed/app-native feel.
-- `stat-slam` - a source-backed number dominates the frame (uses scene `metric`).
-- `hero-morph` - the visual flies in from a thumbnail and arcs into the hero frame (FlipMove shared-element morph).
-- `ui-takeover` - a fake push notification drops in, gets pressed, and expands into the hero — the system-UI hook.
-- `charge-reveal` - progress-bar psychology: rush to 88%, squeeze to 99%, hold, slam to 100% with the payoff line.
-- `cta-card` - centered conversion poster with a pulsing CTA button.
-- `standard` - balanced framed-visual + copy layout; the fallback, not the default.
-
-Set each storyboard scene's `block` accordingly. Do not route every scene through
-`standard` - that is the template-collapse the gate exists to prevent.
-
-## Handoff
-
-- Keep `concepts.json` next to `ad-brief.json` in the project directory.
-- When delivering one built variant, the storyboard and props must reflect the
-  chosen concept's `structure`, `firstFrame`, and `motionIdea`. Note in handoff
-  why the other concepts were not built.