@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/remotion-ad-video/references/creative-direction.md

@@ -0,0 +1,146 @@
+# Creative Direction
+
+## Principle
+
+The first job of an ad is attention. Do not make a slide deck with fades. Build a thumb-stopping hook, a visual metaphor, and a conversion path.
+
+Run divergent concepts before committing. Write `concepts.json` per
+`references/concept-contract.md`, score them, and pass `validate-creative.mjs`
+before the storyboard. Pull mechanics from `references/ad-exemplars.md` so the bar
+is great ads, not the stock template.
+
+## Insight First
+
+Creativity comes from a sharp insight, not from filling a template. Before hooks
+and layouts, name the one true tension the ad weaponizes: a vivid customer pain, a
+surprising approved fact, a distinctive mechanism, or a cultural/format moment.
+Every concept's `insight` field should make a person say "that's true." Generic
+feature lists produce generic ads; a specific insight produces a specific ad.
+
+## Anti-Template Collapse
+
+The stock hook/pain/demo/proof/cta arc is a fallback, not a default. If every ad
+you ship reuses it, the output is template-filler, not creative.
+
+- Let the chosen concept choose the structure. Plan an arc of scene blocks that
+  fits the idea (cold-open payoff, snap-compare, POV ritual, stat slam, gameplay
+  spectacle, feed-native), not the same five scenes every time.
+- Two concepts that produce the same arc are not real alternatives. Make them
+  diverge in hook mechanic and structure, not just color and copy.
+- Do not reuse the default arc unless the concept records a `forceDefaultReason`.
+- Vary the visual system per concept: layout shock, motion language, pacing, and
+  type treatment should follow the idea and the brand's harvested assets, not a
+  fixed look.
+
+## Bold By Default — Exaggeration & Spectacle
+
+A tasteful, reasonable, presentation-safe ad loses the scroll. The default
+emotional register for this skill is loud, dramatized, and a little too much.
+"Would a brand manager call this restrained?" should be a *no*. Push every idea
+one notch past comfortable before you build it.
+
+What "exaggerate" means here:
+
+- Dramatize the *feeling*, not the facts. Blow up the pain to absurd scale, make
+  the relief euphoric, make the speed look impossible, make the transformation
+  total. Every numeric and factual claim stays honest and source-backed — the
+  exaggeration lives in the visual and emotional register, never in the numbers.
+- Spectacle moves: surreal scale (a phone the size of a building, a single
+  feature filling the sky), impossible physics (gravity flips, time freezes,
+  the UI shatters into a thousand shards), world-bending (the product warps the
+  room around it), and maximal kinetic energy (whip pans, snap zooms, hits on
+  every beat).
+- Hyperbolic before/after: the "before" world is a comic disaster, the "after"
+  snaps to perfect on a single beat. Lean into the contrast hard.
+- One outrageous idea, executed at full volume. Bold is not busy — a single
+  surreal mechanic carried through the whole spot beats five timid flourishes.
+  If you can describe the ad without a "wait, what?" moment, it is not bold yet.
+
+Anti-tameness checklist — revise before storyboard if any is true:
+
+- The boldest description of the ad is still "clean," "modern," or "sleek."
+- A competitor could run the same spot by swapping the logo.
+- The hook is a statement, not a spectacle, surprise, or pattern break.
+- Nothing on screen is dramatically oversized, distorted, or physically impossible.
+- The energy is even throughout instead of building to a peak.
+
+The creative gate enforces this: the chosen concept must score `boldness` >= 4
+(plus `attention` >= 4 and `distinctiveness` >= 4). A merely-acceptable idea
+does not pass. See `references/ad-exemplars.md` for spectacle mechanics to reach for.
+
+## Hook Patterns
+
+- Chat becomes action: message bubbles transform into completed tasks.
+- Before/after split: old workflow breaks, product resolves it.
+- Impossible demo: show the result first, then reveal the product.
+- UI explosion: product capabilities fly out from a real screenshot.
+- Countdown: one urgent command or offer lands in the first 2 seconds.
+- Format-native imitation: for feeds, games, editors, or commerce apps, imitate the product's core interaction instead of explaining it.
+
+## Thumb-Stopping Layouts
+
+Before storyboard, choose a Layout Shock move. A good ad still should look like
+it wants attention even before it moves.
+
+- poster-scale type: one word, number, or CTA is dramatically larger than the rest.
+- one dominant visual: icon, product, phone, screenshot crop, avatar, or game object owns the frame.
+- aggressive crop: zoom into the most recognizable product/app detail instead of showing a tidy full screenshot.
+- asymmetric pressure: place the main visual off-center and let text slam, orbit, stack, or collide around it.
+- reveal stack: hide the payoff behind a wipe, swipe, terminal cursor, door, crate, card, or product layer.
+- kinetic split screen: old/new, before/after, fail/rescue, input/output, or chaos/control.
+
+Keep the first frame to maximum two text groups: a large hook and a short support
+or CTA. Do not fill the viewport with several similarly sized labels.
+
+## Numeric Proof Motion
+
+If the source gives usable numbers, treat them as a motion surface, not a line
+of copy. Ratings, discounts, prices, savings, review counts, download counts,
+scores, speed, or time saved should count, tick, roll, pop, or meter-fill toward
+the exact approved final number.
+
+- Rating examples: `0.0` -> `4.8`, with stars or a badge snapping in at the end.
+- Discount examples: `0%` -> `50%`, with a flash, price slash, or offer sticker.
+- Price examples: `$0` -> `$29`, or old price crossed out while savings count up.
+- Game/app examples: score and coins climb with bursts, combos, or HUD-style pops.
+
+Never invent a higher number for drama. If the number is inferred or blocked,
+animate the product behavior instead and keep the proof claim out of the render.
+
+## Motion Requirements
+
+Use the `src/motion.ts` vocabulary (`tween`, `springPop`, `staggerDelay`, eases)
+and `KineticText` rather than bare linear `interpolate` — see
+`references/motion-language.md`. Apply them (they wrap Remotion's
+`useCurrentFrame()`, `spring()`, and `interpolate()`) for:
+
+- Logo or product reveal.
+- Staggered task/card entrances.
+- Kinetic headline movement.
+- Dynamic numeric counters or meters when the ad uses source-backed proof.
+- At least one continuous background or particle motion.
+- CTA emphasis in the final scene.
+
+Avoid:
+
+- Plain centered title cards.
+- One visual repeated for the whole video.
+- Long body copy.
+- CSS transitions or CSS keyframe animations.
+- Dense equal-weight text blocks.
+- Safe, centered composition in every scene.
+- Static numeric proof where the same number could be animated safely.
+
+## Commercial QA
+
+Before handoff, ask:
+
+- Would the first 2 seconds stop someone scrolling?
+- Is the product visible or visually implied immediately?
+- Is there a clear reason to click?
+- Are source assets used, not just generic placeholders?
+- Does the CTA feel like an action, not a footer note?
+- Does the motion feel native to the product category, not just animated presentation slides?
+- Does the layout feel bold enough for a paid ad rather than a product explainer?
+- Is there at least one "wait, what?" spectacle moment — surreal scale, impossible physics, or a dramatized payoff — rather than a tasteful, restrained execution?
+- Does the voiceover carry energy and dynamics, or does it read like a flat description?

package/skills/remotion-ad-video/references/fast-test-workflow.md

@@ -0,0 +1,86 @@
+# Fast Test Workflow
+
+Use this for skill tests, iteration, and first-pass creative QA. The goal is to make obvious issues cheap and reserve full MP4 render for the final candidate.
+
+## Default Fast Path
+
+1. Run source classification and create or update `ad-brief.json`:
+
+```bash
+node scripts/classify-ad-source.mjs "<url>" --brief-out examples/<brand>-ad/ad-brief.json
+```
+
+2. Harvest assets and create the source summary.
+3. Generate concept cards and choose one direction using the brief.
+4. Run text/claim/asset/secret checks before rendering.
+5. Stage the example into the shared lab:
+
+```bash
+node scripts/fast-ad-lab.mjs stage examples/<brand>-ad
+```
+
+6. Render low-resolution stills. This command uses one Remotion bundle for the
+   requested frames instead of re-bundling per frame:
+
+```bash
+node scripts/fast-ad-lab.mjs stills examples/<brand>-ad --frames 30,150,285,390 --scale 0.5
+```
+
+7. Inspect stills. If motion timing needs review, render a low-resolution preview:
+
+```bash
+node scripts/fast-ad-lab.mjs preview examples/<brand>-ad --scale 0.35 --crf 30
+```
+
+8. Render a half-size draft MP4 only after the stills or preview pass:
+
+```bash
+node scripts/fast-ad-lab.mjs render examples/<brand>-ad --scale 0.5 --crf 24
+```
+
+9. Render full-size production MP4 only when the user explicitly approves the final candidate:
+
+```bash
+node scripts/fast-ad-lab.mjs final examples/<brand>-ad --scale 1 --crf 18
+```
+
+## Blocking vs Non-Blocking
+
+Blocking before full render:
+
+- Blank or broken frame.
+- Product/logo missing from hook.
+- Text overlap that makes copy unreadable.
+- Unsupported or risky claim rendered as fact.
+- Actual secret, token, private URL, or customer data.
+- Wrong product visual that could misrepresent the product.
+- Typecheck or Remotion render failure.
+- Font-load render timeout: non-default `fontPreset` values fetch from Google
+  Fonts at render time. On offline or network-restricted machines keep
+  `fontPreset` unset (`clean-sans`); a font fetch failure aborts the render.
+
+The template depends on `@remotion/google-fonts` — when staging new-template
+projects into an older shared lab or reusing an existing project's
+`node_modules`, install the dependency first or the bundle fails.
+
+Non-blocking for skill tests:
+
+- Placeholder variable names such as `api_key`, `REACHAPI_BASE_URL`, or `PROJECT_KEY` when no real value is present.
+- Minor copy polish that does not change claim meaning.
+- A harvested asset kept in the manifest but not used.
+- Small layout preference that does not impair readability.
+- Dependency audit warnings inherited from the template.
+
+Do not rerender full-size MP4 for non-blocking issues. Record them as notes unless the user asks for production polish.
+Do not render full-size MP4 before low-resolution stills and draft video pass.
+
+## Time Budget
+
+For ordinary skill tests, target:
+
+- 3-6 minutes to source summary, preflight defaults, concept score, and draft stills.
+- 1-3 minutes for a low-resolution preview when motion timing needs review.
+- Half-size draft MP4 is the default video deliverable for skill tests: vertical 540x960, square 540x540, landscape 960x540.
+- Full-size MP4 is the expensive final step; run it only after the draft video is accepted or the user explicitly asks for production output.
+
+If a task exceeds the budget, stop after the draft stills and report the blocker or decision needed.

package/skills/remotion-ad-video/references/game-ad-patterns.md

@@ -0,0 +1,75 @@
+# Game Ad Patterns
+
+Use this reference for casual games, mobile games, app-store game listings, puzzle games, hypercasual games, idle games, merge games, runners, and simple gameplay loops.
+
+## Core Rule
+
+Simple-game ads should feel like high-energy gameplay. Do not explain the game with feature cards first. Simulate the most satisfying loop immediately, then use store assets as fast proof moments.
+
+Default duration is 15s. A 30s game ad must be explicitly requested or justified by a deeper story.
+
+The common failure mode is making a mini slide deck: gameplay hook, proof card, feature card, CTA card. Avoid that. Shot cuts are allowed and often useful, but each shot should be kinetic: gameplay action, world/character motion, screenshot motion, reward motion, or CTA motion.
+
+## First 2 Seconds
+
+Start with one clear action and payoff:
+
+- Match: swap pieces, trigger a combo, explode the board.
+- Merge: drag two objects together, reveal a better object.
+- Runner: near-miss obstacle, collect chain, speed burst.
+- Puzzle: wrong move tension, one smart move solves it.
+- Idle/reward: tap or unlock triggers a coin/reward cascade.
+
+Use a short command-style headline such as `ONE MOVE. BIG BLAST.`, `MERGE IT. UNLOCK MORE.`, or `TAP. COLLECT. LEVEL UP.` Keep product/app icon visible in the first scene.
+
+## Asset Use
+
+Use app-store assets in this order:
+
+1. Icon: brand anchor, header, CTA.
+2. Screenshots: product proof, stacked cards, swipe carousel, before/after reveal.
+3. Feature image or hero art: mid-video world/character context.
+4. Rating/download/review numbers: proof cards, not the opening hook.
+
+If screenshots are static, recreate the gameplay motion with custom Remotion shapes over or beside them. Do not rely on panning screenshots as the main animation.
+
+Proof numbers, ratings, screenshots, and feature art should enter as fast overlays, stickers, flashes, swipe cards, match cuts, or side pops. They should not become static information screens.
+
+## Motion Systems
+
+Minimum for 15s game ads:
+
+- Gameplay loop: one animated mechanic that resembles the actual game category.
+- Payoff: particles, burst, score pop, reward cascade, or level-up moment.
+- Asset proof: app-store screenshot/icon/feature-art reveal as a kinetic shot or overlay.
+- CTA pulse: button/icon with a reason to install.
+- Tempo: a meaningful visual change every 0.5-1.5 seconds.
+
+Prefer `useCurrentFrame()`, `spring()`, `interpolate()`, and deterministic arrays for pieces, particles, boards, cards, and score pops. See `references/motion-language.md`: use `Burst` (confetti/coins/sparks/debris) for reward cascades, score pops, and explosions, and the `eases`/`staggerDelay` vocabulary so gameplay motion is springy, not linear.
+
+## 15s Storyboard Pattern
+
+- 0-2s: immediate action and payoff.
+- 2-5s: second combo, fail-rescue, or reward cascade.
+- 5-8s: screenshot/feature art proof enters as a kinetic cut, overlay, or match-cut.
+- 8-11s: bigger payoff, level-up, multiplier, or challenge moment.
+- 11-15s: CTA with motion, such as icon pop, reward burst, card swipe, or gameplay background.
+
+Use 30s only when needed:
+
+- 0-3s hook.
+- 3-12s continuous gameplay variations.
+- 12-20s proof and features as kinetic shots or overlays.
+- 20-26s challenge/event/social mechanic.
+- 26-30s CTA with motion.
+
+## QA Checks
+
+- Would the first second still read without sound?
+- Is the core mechanic visible before social proof?
+- Do proof and CTA use kinetic shots or motion instead of static cards?
+- Does the ad include real store assets plus custom motion?
+- Are screenshots supporting the ad rather than replacing animation?
+- Would any still look like a presentation slide? If yes, revise with a cut, motion, or payoff.
+- Are store claims copied accurately and documented in the source summary?
+- Are third-party asset rights called out before commercial handoff?

package/skills/remotion-ad-video/references/hyperframes-output.md

@@ -0,0 +1,90 @@
+# Hyperframes Output
+
+Use this reference when `ad-brief.json` resolves `renderEngine` to
+`hyperframes`, the user asks for Hyperframes, the target repo is already a
+Hyperframes project, or open-source licensing matters more than Remotion's
+React-based authoring model.
+
+## Engine Choice
+
+- Render-engine selection order is explicit user/caller choice, existing target
+  project stack, then local renderer availability.
+- Use `renderEngine: "hyperframes"` when selected explicitly, when an existing
+  Hyperframes project is present, or when it is the only locally available
+  renderer.
+- If both engines are available, ask the user. If neither is available, ask the
+  user to choose one to install.
+- Do not use Hyperframes' `remotion-to-hyperframes` workflow for a new ad. That
+  workflow is for porting existing Remotion code; new ads should be native
+  Hyperframes HTML.
+
+## Project Shape
+
+Copy `assets/hyperframes-template/` into the target project, or adapt an
+existing Hyperframes project. Hyperframes requires Node.js 22+ and FFmpeg.
+
+Core files:
+
+- `index.html`: source of truth for the composition.
+- `variables.json`: approved ad copy, CTA, colors, local asset paths, and
+  format fields (`width`, `height`, `layoutMode`).
+- `package.json`: local dev-loop commands.
+
+Composition rules:
+
+- The root composition is an HTML element with `data-composition-id`,
+  `data-start`, `data-duration`, `data-width`, and `data-height`.
+- Every clip has `data-start`, `data-duration`, and `data-track-index`.
+- Declare editable fields on the `<html>` root with
+  `data-composition-variables`.
+- Read variables once in script with `window.__hyperframes.getVariables()`.
+- Write `variables.width` and `variables.height` back to `data-width`,
+  `data-height`, `--stage-width`, and `--stage-height` so square and landscape
+  outputs do not render through the vertical starter layout.
+- Register one paused GSAP timeline with
+  `window.__timelines["<composition-id>"] = tl`.
+- Keep internal ids and enum values in English. Use `outputLanguage` for
+  rendered copy.
+
+## Commands
+
+Run the Hyperframes loop instead of Remotion commands:
+
+```bash
+npm install
+npx hyperframes lint
+npx hyperframes inspect --samples 12
+npx hyperframes preview
+npx hyperframes render --variables-file ./variables.json --quality draft
+```
+
+For handoff, report the Hyperframes Studio URL from `preview`, typically:
+
+```text
+http://localhost:<port>/#project/<project-directory-name>
+```
+
+## Asset And Audio Rules
+
+- Store approved media locally next to the project, for example
+  `assets/<brand>/logo.svg` and `assets/<brand>/hero.png`.
+- Reference local asset paths through `variables.json`; do not hard-code remote
+  URLs in the final composition.
+- If `audioMode` is `sfx-only`, first create or choose a generated or
+  rights-cleared SFX file, then add an explicit `<audio src="./assets/...">`
+  clip in `index.html`. Do not leave empty audio tags or unresolved audio
+  variables; Hyperframes lint requires concrete media `src` values. If no sound
+  file exists yet, report that audio is not implemented in the current
+  Hyperframes draft.
+
+## QA Differences
+
+For Hyperframes, replace Remotion still/typecheck gates with:
+
+- `npx hyperframes lint` for composition and track structure.
+- `npx hyperframes inspect` for timeline layout overflow and clipping.
+- Browser preview for motion review.
+- Draft render with `--quality draft` before full/high quality output.
+
+The same ad QA still applies: product visible early, hook/middle/CTA differ,
+text fits mobile, claims are approved, and rights gaps are reported.

package/skills/remotion-ad-video/references/industry-angle-library.md

@@ -0,0 +1,71 @@
+# Industry Angle Library
+
+Use this when the product category is not already covered by game or social-feed patterns. Pick one primary angle and one backup angle before storyboarding.
+
+## SaaS and AI Tools
+
+- Hook: show the result first, then collapse the old workflow.
+- Visual: real UI screenshot, task cards completing, agent/chat actions becoming product output.
+- Proof: integration count, time saved, waitlist, customer quote, or user-supplied result.
+- Avoid: abstract glowing dashboards with no product behavior.
+
+## Ecommerce and Physical Products
+
+- Hook: tactile problem, messy before, or satisfying transformation.
+- Visual: product close-up, use-in-context, before/after, bundle reveal, comparison grid.
+- Proof: materials, rating, review, guarantee, shipping/offer when source-backed.
+- Avoid: generic product beauty shots without a use case.
+
+## Local Services
+
+- Hook: urgent local problem or calendar/time pressure.
+- Visual: location cue, booking flow, technician/service moment, map pin, before/after.
+- Proof: review score, response time, service area, license/insurance only if source-backed.
+- Avoid: broad brand film language.
+
+## Education and Courses
+
+- Hook: specific skill gap or outcome preview.
+- Visual: lesson snippet, progress path, project/result reveal, instructor credibility.
+- Proof: curriculum, completion asset, user-supplied student result, certification if verified.
+- Avoid: income or job guarantees unless approved.
+
+## Health, Fitness, and Wellness
+
+- Hook: routine friction or visible form/behavior improvement.
+- Visual: safe movement demo, habit tracker, product-in-use, progress cues.
+- Proof: trainer credential, user-supplied testimonial, app rating.
+- Avoid: medical claims, body-shaming, or guaranteed health outcomes.
+
+## Finance, Legal, Insurance, and Regulated Offers
+
+- Hook: clarity, speed, or control, not fear-mongering.
+- Visual: calculators, document flow, comparison, checklist, secure workflow.
+- Proof: rates, returns, legal outcomes, coverage, or savings only when approved.
+- Avoid: rendering inferred claims. Use disclaimers and conservative copy.
+
+## B2B Operations
+
+- Hook: operational bottleneck, manual handoff, or failed status board.
+- Visual: pipeline, queue, alert, approval, spreadsheet-to-system transformation.
+- Proof: SLA, error reduction, team adoption, integration, or user-supplied metric.
+- Avoid: consumer-style hype that hides the workflow.
+
+## Creative and Productivity Apps
+
+- Hook: blank page becomes finished output.
+- Visual: timeline, canvas, editor controls, asset generation, export moment.
+- Proof: templates, export formats, collaboration, rating, creator quote.
+- Avoid: showing only final art without the creation interaction.
+
+## Fallback Content Checklist
+
+If no category fits, make sure the ad *contains* these five ingredients - this
+is a content checklist, **not** a scene structure; the scene order still comes
+from the chosen concept's `structure` (see `concept-contract.md`):
+
+1. Problem or desire surfaced in the first 2 seconds.
+2. Product visible immediately.
+3. One concrete product behavior.
+4. One source-backed proof point.
+5. CTA with a specific next action.