@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/remotion-ad-video/SKILL.md

@@ -1,252 +0,0 @@
----
-name: remotion-ad-video
-description: "Use when turning product links, app store listings, landing pages, or product briefs into advertising videos with AICUT or Hyperframes projects, storyboards, render-engine props/variables, render QA, and handoff assets. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "leosssvip-dot/remotion-ad-video-skill"
----
-
-# AICUT Ad Video
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-## Overview
-
-Use this skill to make performance-oriented ad videos with an AI agent plus a deterministic code renderer. The agent owns the creative and production workflow. Remotion is the default renderer; Hyperframes is supported when the user asks for HTML-based video authoring or an existing Hyperframes project.
-
-## When To Use
-
-Use for:
-
-- Product link to 15s ad video by default, or 30s/45s only when the user asks for a longer format.
-- Google Play, App Store, SaaS, or landing page to product explainer ad.
-- Batch variants for TikTok, Reels, Shorts, Meta square, or YouTube landscape.
-- Turning a product brief into a script, storyboard, Remotion props or Hyperframes variables, and render QA checklist.
-
-Do not use for:
-
-- Long-form editorial videos where ad conversion is not the goal.
-- Genuinely off-limits assets: licensed/third-party music, celebrity or identifiable-person likeness, or paid stock/fonts you do not have rights to.
-- Regulated medical, financial, legal, or earnings claims unless the user supplies approved copy.
-
-Asset and claim policy (default to pragmatic, not restrictive):
-
-- This skill makes ad creative for advertisers running paid campaigns (performance/UA/affiliate/agency), not the product's internal staff. Treat the product or app's own public assets as standard creative inputs: store icon, screenshots, feature graphic, Open Graph image, logo, and brand colors. Harvest and use them by default. Do not stall the job waiting for "rights confirmation" on public store assets.
-- Public store metrics — rating, downloads, review count — are usable. Use the real numbers, attributed to the store (e.g. "Google Play 4.0★, 10M+ downloads"). Never fabricate or inflate a number.
-- The advertiser owns final trademark, comparative-claim, and licensing decisions for their channel. Flag any residual responsibility in the handoff; do not gate the build on it.
-- Generated placeholders are a fallback for genuine gaps (e.g. you cannot reliably isolate the right screenshots), not the default. Prefer real harvested assets.
-
-## Core Workflow
-
-### 1. Intake
-
-Collect only the source material needed for the ad. For URLs, inspect the live page when tools are available; otherwise ask for product name, target customer, core offer, screenshots, logo, and brand constraints.
-
-Load `references/ad-intake.md` when source quality, claim safety, or asset rights are unclear.
-Load `references/ad-brief-contract.md` for every URL job before storyboard or code. Create or update `ad-brief.json` after source classification and keep preflight answers/defaults there.
-Load `references/asset-harvest.md` for URL-based jobs before writing the storyboard.
-Load `references/fast-test-workflow.md` for skill tests, first-pass iterations, or when the user cares about speed.
-Load `references/hyperframes-output.md` when the user asks for Hyperframes, the target repo already uses Hyperframes, open-source renderer licensing is a priority, or `ad-brief.json` has `renderEngine: "hyperframes"`.
-Load `references/preflight-questionnaire.md` for URL-only jobs before storyboard or code. Ask exactly two required preflight choices first: format and creative route. Only skip questions when the user explicitly asks for no questions, fastest possible defaults, or a benchmark run with inferred defaults. Ask optional follow-ups only after those choices, and only when they materially change the ad.
-Load `references/platform-presets.md` when the user needs to choose vertical, square, or landscape output.
-Load `references/industry-angle-library.md` when the product category is not obviously covered by games or social-feed patterns.
-Load `references/game-ad-patterns.md` for casual games, mobile games, app-store game listings, puzzle games, hypercasual games, or simple gameplay loops.
-Load `references/social-feed-ad-patterns.md` for short-video, social, creator, UGC, live shopping, community, or content-feed apps.
-Load `references/variant-system.md` when the user wants options, batch ads, or a commercial-quality ad rather than a single sample.
-Load `references/motion-language.md` before implementing motion in either engine; it is the ease, stagger, and kinetic-typography vocabulary (Remotion `src/motion.ts` + `KineticText`, or GSAP for Hyperframes) that keeps motion from defaulting to flat linear interpolation.
-
-Language policy:
-
-- Ask user-facing preflight questions in the user's current interaction language. If the user is chatting in Chinese, ask the `format` and `creativeRoute` questions in Chinese even when the source URL is English.
-- Detect the source/link language from the harvested title, description, screenshots/listing copy, or page text. Generate video script, captions, CTA, and on-screen copy in that detected source language by default.
-- Record `interactionLanguage`, `sourceLanguage`, and `outputLanguage` in `ad-brief.json`. Only change `outputLanguage` when the user explicitly asks for a different video language.
-
-Required decisions:
-
-- Product or app name.
-- Target customer and pain point.
-- Size preset and exact dimensions: vertical, square, or landscape unless a platform-specific format is supplied.
-- Duration: default 15s for short-form ads; use 30s or 45s only when the brief needs explanation depth or the user requests it.
-- One primary conversion goal.
-- Usable assets and rights status.
-- Remotion license suitability for the intended commercial use.
-- Render engine: resolve in this order: explicit user/caller choice, existing target project stack, then local renderer availability. If both Remotion and Hyperframes are available, ask which to use. If neither is available, recommend choosing one to install.
-
-Recorded defaults, not required user decisions:
-
-- Audio mode defaults to `sfx-only` for quick URL jobs, fast tests, and first-pass iterations. Commercial-quality, batch, or "make it more creative" requests default to a full soundscape — `music-sfx` plus a scripted voiceover — without asking. A bold ad with no voice and one repeated click sounds thin. Still ask only if the user requests silent-safe, a specific music plan, or a platform-specific sound plan.
-
-Minimum URL jobs must attempt to harvest favicon, touch icon, Open Graph image, visible logo or screenshots, and brand colors. Ecommerce product URLs must also attempt a product main image with `scripts/harvest-ecommerce-assets.mjs` before creative work starts; the linked item is the ad subject, and platform/store context stays secondary. Store usable public assets locally in the generated project `public/<brand>/` folder, create or update an asset manifest when practical, and reference assets with `staticFile()`.
-
-Run `scripts/classify-ad-source.mjs` for URL jobs before creative work, passing `--interaction-language <current-user-language>` when known, `--project-dir <target-project>` when working inside an existing project, and `--render-engine remotion|hyperframes` only when the user explicitly chose one. Otherwise let `--render-engine auto` detect the engine. Write its output to `ad-brief.json` when a project directory exists. The brief is the source of truth for source type, language plan, render engine, render-engine reason, preflight defaults or answers, format, audio mode, blockers, and asset requirements. If `ad-brief.json` has blockers, includes `preflight_answers_required`, `render_engine_choice_required`, `render_engine_install_required`, or `assetPlan.status` is `blocked`/`user_required`, stop and ask for the missing decision or asset. Use `interactionPlan.choiceQuestions` for the first creative preflight step: ask only format and creative route first, in `interactionLanguage`. If the agent supports structured choice UI, present the choices there; otherwise use a text fallback with the same options. Audio defaults to audible synced SFX; ask about audio only when the user requests silent-safe, music, voiceover, or a platform-specific sound plan. Do not front-load the longer open-question list. Use `--preflight-mode defaults` only when the user explicitly approved skipping questions.
-
-### 2. Strategy
-
-Pick one primary ad angle before writing scenes. Load `references/creative-direction.md` before implementation to avoid static slide-deck output. Start from an `insight` (the one true customer tension or surprising approved fact), not from the template.
-
-- Pain-point hook: problem first, product solves it.
-- Demo proof: show the product or app doing the work.
-- Offer conversion: discount, trial, bundle, or deadline.
-- Social proof: rating, review, result, or usage proof.
-- Comparison: before vs after or old way vs new way.
-- Gameplay spectacle: imitate the high-energy core loop for simple games instead of explaining features.
-- Feed-native spectacle: imitate fast swipe, creator clips, live/shop overlays, comment/like rails, and sound-reactive cuts for social or short-video apps.
-
-Tag claims as `observed` (on-page facts plus public store metrics like rating, downloads, and review count), `user_supplied`, `inferred`, or `blocked`. Render `observed` and `user_supplied` freely — including real public store numbers attributed to the store. Do not render `inferred` or `blocked` numbers, and never fabricate or inflate a figure.
-
-Every real commercial sample needs a thumb-stopping visual idea, not just copy. Examples: chat bubbles becoming completed tasks, before/after workflow collapse, a product screenshot exploding into features, or a terminal command triggering visible automation.
-
-Every concept also needs a bold layout idea before storyboard or code: poster-scale type, one dominant visual, asymmetric composition, aggressive crop, oversized product/app frame, kinetic split screen, or a staged reveal. Avoid neat centered slide layouts unless the contrast or motion makes them feel like an ad.
-
-Default to bold. A tasteful, restrained, presentation-safe ad loses the scroll. Push each concept past comfortable: dramatize the feeling with at least one spectacle move (surreal-scale, impossible-physics, world-bend, hyperbolic-before-after, maximal-kinetic-burst, dramatized-stakes, ui-comes-alive, or time-break — the `spectacleMove` enum) so there is a "wait, what?" beat. Exaggeration lives in the visual and emotional register only — every numeric and factual claim stays honest and source-backed. Load `references/creative-direction.md` (Bold By Default) and `references/ad-exemplars.md` (Spectacle / Exaggeration Mechanics) for the mechanics.
-
-When source-backed numeric proof exists, plan it as motion instead of static copy: ratings count up, discounts snap from 0 to the final percent, prices or savings roll into place, download/review counts tick upward, and scores burst like a game HUD. Use the exact approved number as the final value and never animate unsupported or inflated claims.
-
-For simple games, especially app-store listings, the visual idea should usually be a gameplay-style simulation: falling pieces, swaps, merges, collisions, score pops, explosions, level-up moments, near-fail rescues, or reward cascades. Static screenshots alone are proof assets, not the ad.
-
-For short-video, creator, or social-feed apps, the visual idea should usually be a feed-native simulation: a phone frame that scrolls or swaps content, creator imagery, UI rails, sound/effect stickers, LIVE or Shop chips when source-supported, and quick cuts that feel like the platform itself rather than a product explainer.
-
-Write `concepts.json` before implementation for **every** job, unless the user dictated one exact direction. Fast tests and quick URL jobs use a lean version (3 concepts, one-line fields) — lower resolution is allowed, lower creativity is not; the old "only for commercial-quality" carve-out is exactly how default jobs shipped template-filler. Generate at least three distinct concepts (distinct hook mechanic and `structure`, not just color/copy), each with a `signatureMoment` (the frame only this product could own) and a `spectacleMove`, score them with `references/variant-system.md`, and follow `references/concept-contract.md`. Pull mechanics from `references/ad-exemplars.md` so the bar is great ads, not the stock template. Then gate it:
-
-```
-Do not start the storyboard until the gate passes. The chosen concept must score `attention`, `distinctiveness`, and `boldness` at least 4, with `claimSafety` at least 3, and its `structure` must not silently default to the stock hook/pain/demo/proof/cta arc unless it records a `forceDefaultReason`. A merely-acceptable 3 on attention, distinctiveness, or boldness does not ship — pick or revise a bolder concept. Score `boldness` for how exaggerated and dramatized the idea is, never for how truthful a claim is. Implement the strongest or user-selected concept, and make the storyboard reflect its `structure`, `firstFrame`, and `motionIdea`.
-```
-
-### 3. Storyboard
-
-Create a timed storyboard before code. Load `references/storyboard-contract.md` for the scene contract.
-Use `outputLanguage` from `ad-brief.json` for all video-facing copy unless the user explicitly asks for another language.
-
-There is no default structure — derive the scene list from the chosen concept's `structure` (see `references/storyboard-contract.md`, Mapping rules). Hard beat budgets that always apply for 15s:
-
-- The hook must land inside the first 2 seconds, with the product visible.
-- The CTA gets at least 2.5 seconds and holds (no `transitionOut` on the final scene).
-- Everything between hook and CTA belongs to the concept — non-linear shapes (CTA-early echo, triple escalation, countdown inversion, single take) are legal; see `references/ad-exemplars.md` (Structure-Diverse Shapes).
-- No scene runs longer than 2.5 seconds without a secondary beat (impact, metric tick, re-entrance, transition wind-up).
-
-Keep each beat to one visual idea. Avoid paragraphs in video text; prefer short lines that fit mobile. In most scenes, use one headline plus one support line at most; make the dominant word or number much larger instead of spreading many equal-size text blocks. If a scene uses a source-backed numeric claim, include a `metric` plan with `from`, `to`, `prefix`/`suffix`, `decimals`, and a short label so the renderer can animate the value. For games, use fast kinetic shots; cuts are fine, but each shot should contain gameplay, product motion, character/world action, or a visual payoff rather than a static information card.
-For social or short-video apps, cuts are expected. Each shot should feel like a feed moment, creator clip, notification, sound cue, live/shop moment, or action prompt instead of a static feature card.
-Load `references/audio-caption-system.md` when adding music, sound effects, voiceover, captions, or silent-autoplay readability.
-
-### 4. Template
-
-If no project exists and `renderEngine` is `remotion`, copy `assets/remotion-template/` into the target workspace. If a Remotion project exists, adapt its existing package manager, entrypoint, and component style — and install `@remotion/google-fonts` if missing; the template imports it even when `fontPreset` stays on the no-network default.
-
-If `renderEngine` is `hyperframes`, copy `assets/hyperframes-template/` or adapt the existing Hyperframes project. Hyperframes output is native HTML: `index.html` is the composition source, `variables.json` carries approved ad copy and asset paths, and QA uses `npx hyperframes lint`, `inspect`, `preview`, and `render`. Load `references/hyperframes-output.md` before implementation. For a new ad, author native Hyperframes HTML; do not use a Remotion-to-Hyperframes porting workflow unless the user explicitly asks to migrate existing Remotion source.
-
-Remotion template rules:
-
-- Use a Zod schema for input props.
-- Keep scenes data-driven rather than hard-coded.
-- Set each scene's `block` to a scene-block kind (`cold-open-payoff`, `split-before-after`, `device-frame`, `stat-slam`, `hero-morph`, `ui-takeover`, `charge-reveal`, `cta-card`, or `standard`) so the chosen concept's `structure` renders as distinct layouts and motion, not one repeated card. Map the concept's structure scene blocks onto these template blocks; add a new block component instead of forcing every scene through `standard`. `ui-takeover` (fake notification expands into the hero) and `charge-reveal` (progress-bar squeeze→slam) are purpose-built hook blocks — reach for them before inventing a weaker opener.
-- Use Remotion `Composition`, `Sequence`, and `AbsoluteFill`.
-- Parameterize platform, dimensions, duration, brand colors, CTA, offer, disclaimer, and scenes.
-- Map the chosen `format` / `platform` into the actual composition dimensions and scene layout. Square and landscape outputs must not reuse the vertical layout unchanged.
-- Prefer the harvested real product/app/store assets (icon, screenshots, feature graphic, OG image, brand colors). Use generated placeholders only to fill genuine gaps, clearly marked.
-- Use the app/product's public store assets by default when a URL was supplied; they are standard inputs for install/UA ads. Store them under `public/<brand>/` and reference with `staticFile()`.
-- Support animated metric/counter props for ratings, discounts, prices, savings, review counts, and game/app scores when those numbers are source-backed.
-- Add generated synced SFX by default through props. Use a varied generated SFX palette with frame-locked `startFrame`, category, scene/anchor sync metadata, and visible-event cue descriptions, not one repeated click. Treat audio as a default implementation detail, not a required preflight or QA gate. Only plan or verify special audio when the user asks for silent-safe, music, voiceover, or platform-specific sound.
-- Support `music-sfx` with a generated, licensed, or user-supplied music bed plus picture-locked SFX when the user requests music. Keep quick URL jobs and fast tests on default `sfx-only`.
-- For commercial-quality, batch, or "more creative" requests, default to a full soundscape: music bed + dense SFX + a scripted `voiceover`. Write the voiceover as 3-5 spoken beats with varied delivery (energy, pace, tone) per `references/audio-caption-system.md` (Voiceover Scriptcraft), in `outputLanguage`. A generated TTS voice uses `rightsStatus: generated`.
-- Add at least three motion systems: kinetic hook, animated product/asset reveal, and CTA emphasis. Include the concept's declared `spectacleMove` as a real on-screen beat (see `references/ad-exemplars.md` for the mechanics) so the spot has its "wait, what?" moment.
-- Animate with the vocabulary in `references/motion-language.md`, not bare linear `interpolate`. Use `src/motion.ts` eases (`power3Out` entrances, `expoOut` count-ups, `backOut`/`springPop` pops) and `staggerDelay` for multi-element reveals, and reveal headlines/CTAs with `KineticText` (split words/chars) instead of fading whole text blocks. For shared-element reveals (screenshot→hero, before→after) use `FlipMove` (the `hero-morph` block is a ready example); for reward/spectacle/game beats (confetti, coins, score pops, explosions) use `Burst`.
-- Give every scene boundary a directional handoff via `scene.transitionOut` (`whip-left`/`whip-right`/`whip-up`, `zoom-punch`, `luma-wipe`, or a deliberate `cut`). Never ship an all-`fade` spot, never repeat the same kind on consecutive boundaries, and align an SFX (`sfx-whoosh`, `sfx-impact`, `sfx-swipe`) to each boundary frame. Leave the final scene without a transition so the CTA holds.
-- Make at least one landing physical per spot: a `scene.impact: { atFrame, strength }` beat (flash + camera shake) or a block's built-in slam (metric lock, CTA spring), synced to `sfx-impact`/`sfx-sub-boom` on the same frame. Use `scene.celebrate: { preset }` to fire a `Burst` payoff from props when a reward beat needs it.
-- Pick a `fontPreset` that matches the brand register (`bold-geometric`, `condensed-impact`, `editorial-serif`, `rounded-friendly`, `mono-tech`) instead of shipping the default `clean-sans` Inter look; non-default presets load via `@remotion/google-fonts` (network needed once per render). Give exactly one scene (usually `stat-slam` or `cta-card`) `colorMode: "inverted"` so the spot has a color beat.
-- When the audio plan includes a voiceover, also fill `props.captions` with word-synced karaoke captions (same timestamps as the voiceover track, `emphasis: true` on numbers and power words) — most feeds play muted, and an uncaptioned voiceover effectively does not exist. See `references/audio-caption-system.md` (Karaoke captions).
-- Leave the film finish (`finish.grain` / `finish.vignette`, default on) enabled unless the concept's art direction calls for a flat look.
-- For simple games, include at least one custom gameplay-loop animation inspired by the public screenshots or store description.
-- Keep typography readable at mobile sizes; do not rely on dense body text.
-
-For Remotion implementation details, use the Remotion best-practices skill when available, especially composition, parameter, assets, timing, transitions, audio, and subtitle rules.
-
-Hyperframes template rules:
-
-- Use `data-composition-id`, `data-start`, `data-duration`, `data-width`, and `data-height` on the root composition.
-- Use `data-start`, `data-duration`, and `data-track-index` on every clip.
-- Declare editable fields through `data-composition-variables` and pass values with `variables.json` / `--variables-file`.
-- Include `width`, `height`, and `layoutMode` in `variables.json` and write them back to the composition `data-width` / `data-height` before render.
-- Use `window.__hyperframes.getVariables()` for copy, CTA, colors, and local asset paths.
-- Register a paused GSAP timeline in `window.__timelines`. Build it with the ease/stagger vocabulary in `references/motion-language.md` (this path uses GSAP directly): `power3.out` entrances, `expo.out`/`power3.out` count-ups, `back.out(1.7)` pops, and `stagger` for multi-element reveals.
-- Keep product/app visuals local and rights-reviewed. Do not rely on remote URLs in final output.
-
-### 5. Render QA
-
-Load `references/render-qa-checklist.md` before handoff.
-
-Minimum checks:
-
-- Remotion: typecheck/build passes and still frames render for hook, middle, and CTA sections. For tests and iteration, use the fast lab low-resolution stills before full MP4.
-- Hyperframes: `npx hyperframes lint` and `inspect` pass before preview/render.
-- Text does not overflow or overlap.
-- Visuals are present, not blank.
-- Hook, middle, and CTA stills show different visual states.
-- Source-backed numeric proof animates to the exact final value and is not rendered as a flat text-only proof card.
-- Advertising-aesthetic QA passes using `references/ad-aesthetic-qa.md` for every job (a lean pass — scan the scorecard, fix anything obviously failing — is fine for fast tests; a full scored pass for commercial-quality).
-- CTA, offer, and disclaimer match approved copy.
-- Any unsupported claims are removed or rewritten.
-- Output files and commands are reported.
-
-For skill tests, default to half-size draft video output and do not rerender full-size MP4 for non-blocking polish. Use the blocking/non-blocking split in `references/fast-test-workflow.md`.
-
-## Output Contract
-
-Return:
-
-- Source summary with claim confidence.
-- `ad-brief.json` path or inline summary, including source type, `interactionLanguage`, `sourceLanguage`, `outputLanguage`, `renderEngine`, preflight answers/defaults, blockers, format, and audio mode.
-- Preflight assumptions or user answers, including size preset and creative route.
-- Chosen ad angle and target platform.
-- Script and storyboard.
-- Remotion props JSON or Hyperframes `variables.json`.
-- Files changed or template path.
-- Verification evidence.
-- Known rights, license, or asset gaps.
-
-## Common Mistakes
-
-- Making a generic product video instead of an ad with a conversion goal.
-- Starting Remotion code before deciding hook, proof, and CTA.
-- Shipping a PPT-like sequence of text cards with fades.
-- Animating everything with flat linear `interpolate` (no easing, no stagger, whole-block text fades) so motion feels cheap — use the ease/stagger/kinetic-typography vocabulary in `references/motion-language.md`.
-- Ignoring available logo, favicon, OG image, screenshots, or brand colors from the source URL.
-- Treating a game listing like a SaaS explainer instead of showing high-energy play.
-- Rendering inferred or fabricated numbers as facts, or inflating real ones.
-- Over-blocking: defaulting to bland generated placeholders or vague copy when the source's real public store assets (icon, screenshots) and public ratings/downloads were available to use.
-- Referencing remote URLs in the final render instead of localizing assets under `public/<brand>/`.
-- Overloading the screen with text that works in chat but not in video.
-- Ignoring Remotion commercial license requirements.
-
-## Source
-
-Rewritten for AICUT from [`leosssvip-dot/remotion-ad-video-skill`](https://github.com/leosssvip-dot/remotion-ad-video-skill)
-(MIT), skills/remotion-ad-video/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/remotion-ad-video/references/ad-aesthetic-qa.md

@@ -1,60 +0,0 @@
-# Ad Aesthetic QA
-
-Use this after technical still/render checks on every job — a lean pass (scan the scorecard, fix anything obviously failing) for fast tests, a full scored pass for commercial-quality. This is a creative QA pass, not a replacement for typecheck or render verification.
-
-## Scorecard
-
-Score 1-5 and revise anything below 3:
-
-- `firstTwoSeconds`: product visible, hook clear, motion starts immediately.
-- `adNotSlides`: every beat has motion, payoff, or a meaningful cut.
-- `categoryNative`: visuals imitate the product category or platform behavior.
-- `layoutShock`: composition has an attention-grabbing layout move, such as poster-scale type, aggressive crop, kinetic split, oversized product, or asymmetric reveal.
-- `boldness`: at least one exaggerated, dramatized, or physically-impossible spectacle moment — surreal scale, gravity/time break, world-bend, or hyperbolic before/after — not a tasteful, restrained execution. A "clean and modern" spot scores low here on purpose.
-- `voiceoverEnergy`: when voiceover is present, it carries a punchy spoken hook, varied pace/tone across beats, and a landed spoken CTA — not a flat, even description. (Score n/a only for intentionally silent or sfx-only spots.)
-- `captionCarry`: when voiceover is present, word-synced karaoke captions (`props.captions`) carry it visually — emphasis on the numbers and power words, no collision with other copy. A voiceover without captions scores 1.
-- `typeCraft`: the `fontPreset` matches the brand register and the headline face reads designed, not default — an ad left on the stock Inter look when a distinctive preset fits scores low.
-- `colorBeat`: exactly one scene (usually stat or CTA) uses `colorMode: "inverted"` as a color flood beat; zero inverted beats reads flat, more than one dilutes it.
-- `assetPresence`: logo/icon/screenshot/product visual appears early and repeatedly.
-- `paceDensity`: meaningful change every 0.5-1.5 seconds for 15s short-form.
-- `textDensity`: most scenes use maximum two text groups, with one clear hierarchy winner and enough negative space.
-- `numericMotion`: source-backed ratings, discounts, prices, savings, scores, or counts animate toward the exact final value.
-- `readability`: mobile text is short, high contrast, and does not fight source screenshots.
-- `ctaStrength`: final action is obvious and visually emphasized.
-- `claimTrust`: proof is source-backed and not inflated.
-
-## Visual Failure Signs
-
-Revise if any still:
-
-- Could be mistaken for a presentation slide.
-- Reads as tasteful and restrained, with no exaggerated or impossible spectacle beat.
-- Shows only text over a generic background.
-- Uses many similar-size text labels instead of poster-scale hierarchy.
-- Has no one dominant visual to anchor the frame.
-- Uses harvested screenshots only as passive posters.
-- Has a static CTA with no product or motion context.
-- Shows a rating, discount, price, or count as flat text when it could be a counter, meter, badge, or score pop.
-- Places new text over source screenshot text.
-- Keeps the same composition for more than 3 seconds in a 15s ad.
-
-## Revision Moves
-
-- Replace a text card with a product behavior or simulated interaction.
-- Add a match cut, flash cut, swipe, snap zoom, or object burst.
-- Make one hook word poster-scale and remove secondary copy.
-- Replace multiple small labels with one dominant visual plus one short line.
-- Use an aggressive crop, diagonal split, oversized phone/product, or asymmetric layout.
-- Turn proof into stickers, overlays, counters, or side pops.
-- Turn numeric proof into a count-up, rolling price, filling meter, score burst, or animated discount badge.
-- Move dense copy into voiceover or captions.
-- Crop or mask screenshots so source text and new text do not collide.
-- Bring the logo, app icon, or product back into the CTA.
-- Swap the fontPreset to one that matches the brand register (condensed-impact for deals/urgency, editorial-serif for premium, rounded-friendly for casual/family, mono-tech for dev/AI).
-- Give the stat or CTA scene `colorMode: "inverted"` for a color-flood beat.
-- Pair the voiceover with word-synced karaoke captions, emphasis on numbers and power words.
-- Vary the headline `enter` mode across scenes (clip / slam / pop / flip3d / blur) instead of one repeated gesture.
-
-## Minimum Handoff
-
-Report the scorecard only when useful. Always state whether the final stills passed visual inspection for hook, middle, and CTA.

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

@@ -1,235 +0,0 @@
-# Ad Brief Contract
-
-Use `ad-brief.json` as the mandatory handoff artifact between source intake and
-storyboard/code. It keeps the ad from drifting into a generic presentation and
-makes unanswered creative or asset decisions explicit.
-
-## When To Create It
-
-- Create or update `ad-brief.json` after the first URL/source skim and before
-  storyboard, Remotion props, or code.
-- For URL jobs, run the deterministic source classifier first:
-
-```bash
-node scripts/classify-ad-source.mjs "<url>" --interaction-language zh-CN --project-dir examples/<brand>-ad --brief-out examples/<brand>-ad/ad-brief.json
-```
-
-- Use `--render-engine remotion|hyperframes` only when the user explicitly
-  picked one. Otherwise the classifier uses `auto`: explicit choice, existing
-  project stack, then local renderer availability.
-- If the user answers preflight questions, update `mode` to `answered` and move
-  answered items out of `unansweredQuestions`.
-- To write answered choices deterministically, pass `--format` and
-  `--creative-route` with `--preflight-mode answered`.
-- If `--project-dir` is supplied and `--brief-out` is omitted, the classifier
-  writes `<project-dir>/ad-brief.json`.
-- For quick tests, defaults are allowed, but defaults must be recorded in the
-  brief instead of only mentioned in chat.
-- `interactionLanguage` controls user-facing questions. `sourceLanguage` is
-  detected from the URL/source content. `outputLanguage` controls video script,
-  captions, CTA, and on-screen copy, and defaults to `sourceLanguage`.
-
-## Required Fields
-
-```json
-{
-  "schemaVersion": "1.0",
-  "sourceUrl": "https://example.com/product",
-  "generatedAt": "2026-05-19T00:00:00.000Z",
-  "mode": "requires_input",
-  "status": "blocked",
-  "sourceType": "ecommerce_product",
-  "classificationConfidence": 0.85,
-  "classificationReasons": [],
-  "productName": "Product",
-  "interactionLanguage": "zh-CN",
-  "sourceLanguage": "en",
-  "outputLanguage": "en",
-  "languagePlan": {
-    "preflightQuestions": "zh-CN",
-    "videoScriptAndCaptions": "en",
-    "note": "Ask user-facing preflight questions in interactionLanguage. Generate video script, captions, and on-screen copy in outputLanguage unless the user explicitly overrides it."
-  },
-  "goal": "purchase",
-  "cta": "Shop now",
-  "audience": "inferred from source; needs confirmation",
-  "hookFocus": "curiosity",
-  "creativeRoute": "product close-up",
-  "proofPlan": {
-    "allowed": ["public store metrics: rating, downloads, reviews", "observed on-page facts"],
-    "blocked": ["fabricated or inflated numbers", "private/customer data", "regulated claims without approved copy"],
-    "notes": "Render real observed and public store figures, attributed to the store; never invent or inflate."
-  },
-  "assetPlan": {
-    "status": "store_public",
-    "rightsStatus": "store_public_usable",
-    "required": ["product main image", "brand/logo"],
-    "notes": "Use the product/app public store assets (icon, screenshots, OG image) and brand colors by default; harvest before storyboard."
-  },
-  "format": {
-    "preset": "vertical-9x16",
-    "width": 1080,
-    "height": 1920,
-    "renderScale": 0.5,
-    "draftWidth": 540,
-    "draftHeight": 960
-  },
-  "durationSeconds": 15,
-  "audioMode": "sfx-only",
-  "renderEngine": "hyperframes",
-  "renderEngineReason": "Only Hyperframes appears available on this computer.",
-  "renderEngineSelection": {
-    "status": "selected",
-    "source": "local_availability",
-    "requested": "auto",
-    "reason": "Only Hyperframes appears available on this computer.",
-    "projectDir": "/absolute/path/to/project",
-    "projectMarkers": {
-      "remotion": [],
-      "hyperframes": []
-    },
-    "localAvailability": {
-      "remotion": false,
-      "hyperframes": true,
-      "source": "local"
-    },
-    "options": ["remotion", "hyperframes"]
-  },
-  "renderPlan": {
-    "engine": "hyperframes",
-    "format": "vertical-9x16",
-    "width": 1080,
-    "height": 1920,
-    "draftWidth": 540,
-    "draftHeight": 960,
-    "template": "skills/remotion-ad-video/assets/hyperframes-template",
-    "primarySource": "index.html",
-    "validationCommands": [
-      "npm install",
-      "npx hyperframes lint",
-      "npx hyperframes inspect",
-      "npx hyperframes render --variables-file ./variables.json --quality draft"
-    ]
-  },
-  "interactionPlan": {
-    "preferredMode": "structured_choices",
-    "fallbackMode": "text",
-    "language": "zh-CN",
-    "instructions": "先只询问 choiceQuestions。若 agent 支持可选择 UI，就用可选择 UI；否则用同样选项的文本 fallback。Audio 默认 sfx-only，除非用户要求 silent-safe、音乐或旁白，否则不要作为必答预检问题。",
-    "requiredChoiceQuestionIds": ["format", "creativeRoute"],
-    "choiceQuestions": [
-      {
-        "id": "format",
-        "question": "选择输出尺寸。",
-        "options": [
-          {"label": "竖屏 9:16", "value": "vertical-9x16"},
-          {"label": "方形 1:1", "value": "square-1x1"},
-          {"label": "横屏 16:9", "value": "landscape-16x9"}
-        ]
-      },
-      {
-        "id": "creativeRoute",
-        "question": "选择这个电商商品广告的主要创意路线。",
-        "options": [
-          {"label": "产品特写", "value": "product close-up"},
-          {"label": "试用/生活方式", "value": "try-on/lifestyle"},
-          {"label": "优惠促单", "value": "offer push"}
-        ]
-      }
-    ],
-    "openQuestions": []
-  },
-  "unansweredQuestions": [
-    "format: 选择输出尺寸。 选项: 竖屏 9:16=vertical-9x16, 方形 1:1=square-1x1, 横屏 16:9=landscape-16x9.",
-    "creativeRoute: 选择这个电商商品广告的主要创意路线。 选项: 产品特写=product close-up, 试用/生活方式=try-on/lifestyle, 优惠促单=offer push."
-  ],
-  "assumptions": [],
-  "blockers": ["preflight_answers_required"]
-}
-```
-
-## Allowed Values
-
-`status`:
-
-- `draft`: inferred defaults, not user-approved.
-- `answered`: user answered enough questions to proceed.
-- `blocked`: missing assets or decisions prevent a truthful ad.
-- `approved`: user-approved final creative brief.
-
-`sourceType`:
-
-- `ecommerce_product`
-- `mobile_game`
-- `social_content_app`
-- `saas_api`
-- `service_local`
-- `mobile_app`
-- `unknown`
-
-`assetPlan.status`:
-
-- `confirmed`: required visuals are available and usable.
-- `store_public`: the product/app's public store assets (icon, screenshots, OG
-  image) are usable as standard install/UA creative; harvest and use by default.
-- `weak`: visuals are thin; harvest more or supplement with generated placeholders.
-- `blocked`: crawler/browser failed or assets do not match the product.
-- `user_required`: stop and ask the user only when no usable public asset exists
-  and none can be generated.
-
-`renderEngine`:
-
-- `remotion`: React/Remotion project output.
-- `hyperframes`: HTML/data-attribute Hyperframes project output.
-- `needs_selection`: both engines appear available or both project stacks are
-  present; ask the user which engine to use.
-- `install_required`: neither engine appears available; recommend choosing one
-  to install.
-
-## Blocking Rules
-
-- If `blockers` is non-empty, do not storyboard or render. Resolve blockers
-  first.
-- If `blockers` includes `preflight_answers_required`, ask
-  `interactionPlan.choiceQuestions` first using structured choices when
-  supported, or text fallback when not supported. Use
-  `interactionPlan.language` / `interactionLanguage` for those questions. Do
-  not ask the longer optional follow-up questions as the initial required
-  prompt.
-- If `blockers` includes `render_engine_choice_required`, ask which detected
-  engine to use: Remotion or Hyperframes.
-- If `blockers` includes `render_engine_install_required`, recommend choosing
-  one engine to install. Remotion fits React/TS/Zod and the existing Remotion
-  lab; Hyperframes fits HTML/CSS/GSAP and the open-source renderer path.
-- Audio defaults to `sfx-only`; do not ask audio as a required preflight choice
-  unless the user requests silent-safe, music, voiceover, or a specific sound
-  direction.
-- If `assetPlan.status` is `blocked` or `user_required`, stop and ask the user
-  for assets. Do not make a fake product ad.
-- For ecommerce product links, do not proceed without a credible product main
-  image or user-provided product visual.
-- For audio, do not promise sound unless `audioMode` maps to real rights-cleared
-  files or generated cue assets in props.
-- If `renderEngine` is `hyperframes`, load `hyperframes-output.md` before
-  implementation and run the Hyperframes QA commands instead of Remotion still
-  commands.
-
-## Storyboard Traceability
-
-The storyboard and `default-props.json` should cite these brief values:
-
-- `sourceType` drives the category-native creative route.
-- `goal` and `cta` drive the final call-to-action.
-- `hookFocus` drives the first 2 seconds.
-- `creativeRoute` drives motion language and scene structure.
-- `proofPlan.allowed` is the only source for rendered proof claims.
-- `assetPlan.required` drives harvesting and visual QA.
-- `format` and `durationSeconds` drive Remotion composition settings.
-- `renderEngine` and `renderEngineReason` drive whether the implementation
-  writes Remotion TSX props or Hyperframes HTML plus `variables.json`.
-- For Hyperframes, write `format.width`, `format.height`, and the derived
-  orientation into `variables.json` as `width`, `height`, and `layoutMode`.
-- `interactionPlan.choiceQuestions` drives agent-native selectable preflight UI
-  when supported.
-- `interactionLanguage` drives user-facing questions.
-- `outputLanguage` drives script, captions, CTA, and on-screen copy.