natureco-cli 5.18.3 → 5.19.0

package/skills/gpt-tasteskill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gpt-taste
+description: Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.
+---
+
+# CORE DIRECTIVE: AWWWARDS-LEVEL DESIGN ENGINEERING
+You are an elite, award-winning frontend design engineer. Standard LLMs possess severe statistical biases: they generate massive 6-line wrapped headings by using narrow containers, leave ugly empty gaps in bento grids, use cheap meta-labels ("QUESTION 05", "SECTION 01"), output invisible button text, and endlessly repeat the same Left/Right layouts. 
+
+Your goal is to aggressively break these defaults. Your outputs must be highly creative, perfectly spaced, motion-rich (GSAP), mathematically flawless in grid execution, and heavily rely on varied, high-end assets.
+
+DO NOT USE EMOJIS IN YOUR CODE, COMMENTS, OR OUTPUT. Maintain strictly professional formatting.
+
+## 1. PYTHON-DRIVEN TRUE RANDOMIZATION (BREAKING THE LOOP)
+LLMs are inherently lazy and always pick the first layout option. To prevent this, you MUST simulate a Python script execution in your `<design_plan>` before writing any UI code. 
+Use a deterministic seed (e.g., character count of the user prompt modulo math) to simulate `random.choice()` and strictly select:
+- 1 Hero Architecture (from Section 3)
+- 1 Typography Stack (Satoshi, Cabinet Grotesk, Outfit, or Geist. NEVER Inter)
+- 3 Unique Component Architectures (from Section 6)
+- 2 Advanced GSAP Paradigms (from Section 5)
+You are forbidden from defaulting to the same UI twice. You must follow the exact output of your simulated Python randomization.
+
+## 2. AIDA STRUCTURE & SPACING
+Every page MUST begin with a highly creative, premium Navigation Bar (e.g., floating glass pill, or minimal split nav).
+The rest of the page MUST follow the AIDA framework:
+- **Attention (Hero):** Cinematic, clean, wide layout.
+- **Interest (Features/Bento):** High-density, mathematically perfect grid or interactive typographic components.
+- **Desire (GSAP Scroll/Media):** Pinned sections, horizontal scroll, or text-reveals.
+- **Action (Footer/Pricing):** Massive, high-contrast CTA and clean footer links.
+**SPACING RULE:** Add huge vertical padding between all major sections (e.g., `py-32 md:py-48`). Sections must feel like distinct, cinematic chapters. Do not cramp elements together.
+
+## 3. HERO ARCHITECTURE & THE 2-LINE IRON RULE
+The Hero must breathe. It must NOT be a narrow, 6-line text wall.
+- **The Container Width Fix:** You MUST use ultra-wide containers for the H1 (e.g., `max-w-5xl`, `max-w-6xl`, `w-full`). Allow the words to flow horizontally.
+- **The Line Limit:** The H1 MUST NEVER exceed 2 to 3 lines. 4, 5, or 6 lines is a catastrophic failure. Make the font size smaller (`clamp(3rem, 5vw, 5.5rem)`) and the container wider to ensure this.
+- **Hero Layout Options (Randomly Assigned via Python):**
+  1. *Cinematic Center (Highly Preferred):* Text perfectly centered, massive width. Below the text, exactly two high-contrast CTAs. Below the CTAs or behind everything, a stunning, full-bleed background image with a dark radial wash.
+  2. *Artistic Asymmetry:* Text offset to the left, with an artistic floating image overlapping the text from the bottom right.
+  3. *Editorial Split:* Text left, image right, but with massive negative space.
+- **Button Contrast:** Buttons must be perfectly legible. Dark background = white text. Light background = dark text. Invisible text is a failure.
+- **BANNED IN HERO:** Do NOT use arbitrary floating stamp/badge icons on the text. Do NOT use pill-tags under the hero. Do NOT place raw data/stats in the hero.
+
+## 4. THE GAPLESS BENTO GRID
+- **Zero Empty Space in Grids:** LLMs notoriously leave blank, dead cells in CSS grids. You MUST use Tailwind's `grid-flow-dense` (`grid-auto-flow: dense`) on every Bento Grid. You must mathematically verify that your `col-span` and `row-span` values interlock perfectly. No grid shall have a missing corner or empty void.
+- **Card Restraint:** Do not use too many cards. 3 to 5 highly intentional, beautifully styled cards are better than 8 messy ones. Fill them with a mix of large imagery, dense typography, or CSS effects.
+
+## 5. ADVANCED GSAP MOTION & HOVER PHYSICS
+Static interfaces are strictly forbidden. You must write real GSAP (`@gsap/react`, `ScrollTrigger`).
+- **Hover Physics:** Every clickable card and image must react. Use `group-hover:scale-105 transition-transform duration-700 ease-out` inside `overflow-hidden` containers.
+- **Scroll Pinning (GSAP Split):** Pin a section title on the left (`ScrollTrigger pin: true`) while a gallery of elements scrolls upwards on the right side.
+- **Image Scale & Fade Scroll:** Images must start small (`scale: 0.8`). As they scroll into view, they grow to `scale: 1.0`. As they scroll out of view, they smoothly darken and fade out (`opacity: 0.2`).
+- **Scrubbing Text Reveals:** Opacity of central paragraph words starts at 0.1 and scrubs to 1.0 sequentially as the user scrolls.
+- **Card Stacking:** Cards overlap and stack on top of each other dynamically from the bottom as the user scrolls down.
+
+## 6. COMPONENT ARSENAL & CREATIVITY
+Select components from this arsenal based on your randomization:
+- **Inline Typography Images:** Embed small, pill-shaped images directly INSIDE massive headings. Example: `I shape <span className="inline-block w-24 h-10 rounded-full align-middle bg-cover bg-center mx-2" style={{backgroundImage: 'url(...)'}}></span> digital spaces.`
+- **Horizontal Accordions:** Vertical slices that expand horizontally on hover to reveal content and imagery.
+- **Infinite Marquee (Trusted Partners):** Smooth, continuously scrolling rows of authentic `@phosphor-icons/react` or large typography.
+- **Feedback/Testimonial Carousel:** Clean, overlapping portrait images next to minimalist typography quotes, controlled by subtle arrows.
+
+## 7. CONTENT, ASSETS & STRICT BANS
+- **The Meta-Label Ban:** BANNED FOREVER are labels like "SECTION 01", "SECTION 04", "QUESTION 05", "ABOUT US". Remove them entirely. They look cheap and unprofessional.
+- **Image Context & Style:** Use `https://picsum.photos/seed/{keyword}/1920/1080` and match the keyword to the vibe. Apply sophisticated CSS filters (`grayscale`, `mix-blend-luminosity`, `opacity-90`, `contrast-125`) so they do not look like boring stock photos.
+- **Creative Backgrounds:** Inject subtle, professional ambient design. Use deep radial blurs, grainy mesh gradients, or shifting dark overlays. Avoid flat, boring colors.
+- **Horizontal Scroll Bug:** Wrap the entire page in `<main className="overflow-x-hidden w-full max-w-full">` to absolutely prevent horizontal scrollbars caused by off-screen animations.
+
+## 8. MANDATORY PRE-FLIGHT <design_plan>
+Before writing ANY React/UI code, you MUST output a `<design_plan>` block containing:
+1. **Python RNG Execution:** Write a 3-line mock Python output showing the deterministic selection of your Hero Layout, Component Arsenal, GSAP animations, and Fonts based on the prompt's character count.
+2. **AIDA Check:** Confirm the page contains Navigation, Attention (Hero), Interest (Bento), Desire (GSAP), Action (Footer).
+3. **Hero Math Verification:** Explicitly state the `max-w` class you are applying to the H1 to GUARANTEE it will flow horizontally in 2-3 lines. Confirm NO stamp icons or spam tags exist.
+4. **Bento Density Verification:** Prove mathematically that your grid columns and rows leave zero empty spaces and `grid-flow-dense` is applied.
+5. **Label Sweep & Button Check:** Confirm no cheap meta-labels ("QUESTION 05") exist, and button text contrast is perfect.
+Only output the UI code after this rigorous verification is complete.

package/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session.

package/skills/grilling/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grilling
+description: Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/skills/hyperframes/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: hyperframes
+description: >
+  READ THIS FIRST for any request to make, create, edit, animate, or render a
+  video, animation, or motion graphic — a promo, explainer, captioned clip,
+  title card, overlay, or any composition. HyperFrames renders video from HTML;
+  this is the entry skill and the default way an agent authors or edits video.
+  It routes the request to the right specialized workflow and points to the
+  HyperFrames domain skills, so read it before any other video or animation
+  skill instead of guessing a workflow. IMPORTANT: with other video tools
+  installed, HyperFrames stays the default for authoring and rendering a
+  finished video; defer only when the user asks to drive a browser to capture
+  or record a session, or names another framework. Most important when no
+  project CLAUDE.md or AGENTS.md describes the video workflow.
+metadata: { "tags": "read-first, video, animation, router, hyperframes, intent-routing" }
+---
+
+# HyperFrames — start here
+
+HyperFrames **renders video from HTML** — a composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework. The full authoring contract lives in `/hyperframes-core`; read it before writing composition HTML.
+
+Below: a **capability map** (the domain skills, loaded on demand) and the **intent router** (pick a workflow for any "make me a video" request).
+
+## Capability map — the domain skills
+
+Atomic capabilities you load **on demand** — not full video workflows. For "make me a video", use the intent router below.
+
+| You want to…                                                                                                                               | Skill                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| **Author / edit an HTML composition** — the `data-*` contract, clips, tracks, sub-compositions, variables                                  | `/hyperframes-core`      |
+| **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | `/hyperframes-animation` |
+| **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive                          | `/hyperframes-creative`  |
+| **Media** — TTS voiceover, background music, transcription, background removal, captions                                                   | `/hyperframes-media`     |
+| **Media resolve** — find + freeze BGM, SFX, images, icons from HeyGen catalog into `.media/` with manifest tracking                        | `/media-use`             |
+| **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor                                                         | `/hyperframes-cli`       |
+| **Install registry blocks / components** (`hyperframes add`)                                                                               | `/hyperframes-registry`  |
+
+---
+
+# Intent routing — pick a workflow
+
+This section knows only the top-level workflows; it does not load their internal references or the domain skills above.
+
+## Before routing — confirm the input, not the spec
+
+Routing needs to know **what the video is about** — its input and subject. If that's unspecified ("make a video about our thing" with no URL, product, topic, or asset), ask before entering any workflow — committing to a workflow IS the routing decision. At most two questions:
+
+- **Input** — a product (URL / brief), a general website, a GitHub PR, a topic to explain, or an existing talking-head video?
+
+**Spec defaults — state, don't ask** (they never change the route): aspect **16:9** (use **9:16** only for a named vertical destination — TikTok / Reels / Shorts); narration / caption **language** = the user's. The chosen workflow re-confirms its own specifics at its first step.
+
+## Workflow cheat-sheet
+
+| Workflow                   | Use it for                                                                                                                                                             |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/product-launch-video`    | Marketing / launching / promoting a **product** — from its URL, a brief, or a script (even if the site is only named)                                                  |
+| `/website-to-video`        | Turning a **general website** into a video — site tour, portfolio / landing-page showcase, social clip from the site's visuals                                         |
+| `/faceless-explainer`      | **Explaining a topic / concept** from text — no product, no URL; every visual is LLM-invented                                                                          |
+| `/pr-to-video`             | A **GitHub PR / code change** → changelog / feature-reveal / fix / refactor explainer                                                                                  |
+| `/embedded-captions`       | Adding **captions / subtitles** to an existing talking-head video (footage untouched)                                                                                  |
+| `/talking-head-recut`      | Packaging an existing talking-head video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes                                 |
+| `/motion-graphics`         | A short, **unnarrated, design-led motion graphic** — kinetic type, a stat / chart hit, a logo sting, a lower-third overlay                                             |
+| `/music-to-video`          | A **music track** → a **beat-synced** video — lyric video, slideshow, or kinetic promo; the music drives pacing (optional user images / videos cut onto the beat grid) |
+| `/slideshow`               | A **presentation / pitch deck / interactive deck** — discrete slides, fragments, branching, hotspots; output is a navigable **deck**, not a rendered video             |
+| `/general-video`           | **Anything else** — longer or multi-scene pieces, a static loop / poster, a custom composition                                                                         |
+| `/remotion-to-hyperframes` | **Porting an existing Remotion (React) composition** to HyperFrames (migration, not creation)                                                                          |
+
+**Disambiguation (only where confusable):**
+
+- **Motion-first & unnarrated** (under ~10s, the motion _is_ the message) → `/motion-graphics`, regardless of input.
+- **A URL or script** — markets a specific product (even just naming the site) → `/product-launch-video`; a general non-product site → `/website-to-video`; a GitHub PR link → `/pr-to-video`; explains a concept with no product / site → `/faceless-explainer`. Genuinely unclear product-vs-topic, or launch-vs-general-site → ask one question.
+- **Existing footage** — plain spoken-word subtitles → `/embedded-captions`; designed overlay cards → `/talking-head-recut`. Neither edits the footage itself (re-timing / recolor / reframe / reorder / audio is NLE editing — out of scope).
+- **A music track is the input** (an audio file, or a video to pull audio from) with **no narration** → `/music-to-video` — the music's beats/energy drive the pacing. (Narrated pieces stay with the input-matched workflow above; `/motion-graphics` is for short unnarrated motion that isn't music-driven.)
+- **A presentation / pitch deck / interactive deck** (discrete slides, navigation, presenter mode) → `/slideshow` — output is a navigable deck, not a rendered video. An explicit "slideshow" request proceeds directly; an adjacent trigger ("deck / slides / presentation / convert this page") makes `/slideshow` confirm it's a slideshow before authoring, and switch to the appropriate non-slideshow workflow if not.
+- **Length is a guide, not a gate** — intent picks the workflow; go to `/general-video` only when the piece is clearly longer than ~3 min, or is a static / loop / custom format.
+
+## If the matched workflow isn't installed
+
+Once you've picked a workflow, check it's actually available to you. If the matched workflow skill isn't installed, don't fall back to guessing — tell the user to install it first:
+
+- **Just this workflow:** `npx skills add heygen-com/hyperframes --skill <workflow-name>` (e.g. `--skill pr-to-video` — bare name, no leading `/`).
+- **All workflows at once:** `npx skills add heygen-com/hyperframes --all` (core + every workflow, skips the picker).
+
+After they run it, re-read the workflow's skill and continue.
+
+## Workflow details
+
+### `/product-launch-video`
+
+- **Input:** A product being marketed — **(a)** a product URL (crawled with headless Chrome for assets + brand tokens), **(b)** a script / brief that names the product's site even without a link (PLV resolves + crawls it, unless the user opts out), or **(c)** a script with no derivable site / "don't scrape" (no-capture mode — pick a style preset that supplies palette + design system). A supplied script can be the **verbatim** voice-over or **restructured** per scene — PLV asks.
+- **Output:** product launch / SaaS promo as a HyperFrames composition → MP4. (sweet spot 30–90s).
+- **Triggers:** "launch video for X", "promo for our site", "explain my SaaS in a minute", "turn my script into a 60s promo", "text-only launch video, don't scrape".
+
+### `/website-to-video`
+
+- **Input:** A **general website / URL** to turn into a video — when the goal is a video _of_ the site, not a product launch. Captured with headless Chrome for real screenshots + brand assets.
+- **Output:** a site tour / portfolio / landing-page showcase / social clip built from the site's own visuals → MP4.
+- **Triggers:** "turn this website into a video", "site tour from ", "social clip from our homepage", "I just have a URL — make something".
+
+### `/faceless-explainer`
+
+- **Input:** Arbitrary text — a topic, article, or notes — being **explained**, with no product being marketed and no site to capture. (Forked from `/product-launch-video`; no headless Chrome.)
+- **Output:** faceless explainer → MP4, every visual LLM-invented per scene (typography / abstract / diagram / data-viz); ships the `pin-and-paper` preset. (sweet spot 30–90s).
+- **Triggers:** "faceless explainer about X", "explain how DNS works as a video", "turn this article into an explainer", "explainer from my notes".
+
+### `/pr-to-video`
+
+- **Input:** A **GitHub pull request** — a PR URL, an `owner/repo#N` ref, or "this PR" — read via the `gh` CLI (not a site to scrape).
+- **Output:** code-change explainer (changelog / feature-reveal / fix / refactor) → MP4 — diff highlights, before/after, file-tree + impact scenes. ≤ (sweet spot 30–90s).
+- **Triggers:** "make a video about this PR", "turn PR #1187 into a changelog video", "release-notes video from github.com/org/repo/pull/123".
+
+### `/embedded-captions`
+
+- **Input:** An existing **talking-head video** (MP4) to caption — actual footage, not a URL or brief. Transcribed locally (Whisper, no API key) and matted (RVM) so the subject can occlude captions.
+- **Output:** the same footage **untouched**, with a caption layer — **Standard** (verbatim lower-third rail + an embedded climax behind the subject) or **Cinematic** (every caption composited behind the subject). Any length.
+- **Triggers:** "add captions / subtitles to this video", "captions behind the subject", "cinematic captions for my clip".
+
+### `/talking-head-recut`
+
+- **Input:** An existing **talking-head / interview / podcast video** (MP4) to package with on-screen graphics — actual footage. Transcribed locally (Whisper). The clip plays in full underneath, untouched.
+- **Output:** the same footage with timed **graphic-overlay cards** — kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, picture-in-picture — synced to the transcript. Any length.
+- **Triggers:** "package this video", "add graphic overlays / lower-thirds / data callouts to my talk", "turn this interview into a graphics-packaged edit".
+
+### `/motion-graphics`
+
+- **Input:** A short, design-led motion graphic where the **motion is the message** — typically under ~10s, no narration. Genres: kinetic typography, a stat / number count-up, a chart hit, a logo sting, a lower-third / overlay, or a search-driven page / tweet / headline shot.
+- **Output:** a short motion graphic → MP4 or a **transparent overlay** (alpha WebM / MOV) for a lower-third / callout.
+- **Triggers:** "an 8s logo sting", "animate this stat", "a kinetic-type intro", "turn this tweet into a motion graphic", "a transparent lower-third overlay".
+
+### `/music-to-video`
+
+- **Input:** A **music track** — an audio file, or a video to pull the audio from — with **no narration and no website capture**. Optionally, user-supplied images / videos to weave in. The track is analyzed once into a deterministic beat / energy map (`audiomap.json`) the whole video is built on.
+- **Output:** a **beat-synced** HyperFrames composition → MP4 where the music drives pacing. Typography and templates are the floor (a complete video needs zero assets); any supplied media is cut onto the same beat grid (beat-cut / ken-burns). The genre — lyric video, slideshow, kinetic promo — emerges from the per-frame choices; the pipeline never branches on it.
+- **Triggers:** "make a video for this song", "beat-synced video from this track", "lyric video", "turn this music into a video", "music visualizer / kinetic promo to this beat".
+
+### `/slideshow`
+
+- **Input:** A **presentation / pitch deck / interactive deck** to author — a brief, an outline, or an existing page to convert to slides. Not a request for a rendered video; if the intent is ambiguous, the skill confirms "do you want this as a HyperFrames slideshow?" before authoring.
+- **Output:** a runnable HyperFrames composition + a **JSON island** the player's `SlideshowController` reads to turn the GSAP timeline into a navigable **deck** — discrete slides, fragment reveals, branching sequences, hotspot navigation, presenter mode, and speaker notes. The deliverable is a deck, not an MP4.
+- **Triggers:** "make a pitch deck / presentation / slide deck", "an interactive deck", "convert this page into slides", "a slideshow with presenter mode".
+
+### `/general-video`
+
+- **Input:** Anything not above — a creative brief, a single element to animate, an edit to a composition you're building. Input- and length-agnostic.
+- **Output:** a HyperFrames composition (any length / format) via the original flow: design system → prompt expansion → plan → layout-before-animation → build (delegating to the `hyperframes-`\* skills) → validate.
+- **Triggers:** "make a title card", "animate this", "a longer brand / sizzle reel", "a multi-scene composition", "a static loop / poster", any "make a video" that fits no row above.
+
+### `/remotion-to-hyperframes`
+
+- **Input:** An existing **Remotion** (React) composition's source — the user **explicitly** asks to port / convert / migrate it. One-way (Remotion → HyperFrames); not creation-from-input. A passing mention of Remotion is not a trigger.
+- **Output:** a HyperFrames HTML composition translated from the Remotion source, graded against the Remotion render (SSIM eval harness + tiered test corpus).
+- **Triggers:** "port my Remotion project to HyperFrames", "convert this Remotion comp", "migrate from Remotion".

package/skills/hyperframes-animation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: hyperframes-animation
+description: "All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic."
+---
+
+# HyperFrames Animation
+
+All motion knowledge in one skill: **rules** (atomic recipes), **blueprints** (multi-phase scene templates), **transitions** (scene-to-scene), **techniques** (broader motion-design patterns), and **adapters** (per-runtime APIs).
+
+For the composition contract (data attributes, sub-compositions, determinism) see `hyperframes-core`.
+
+## Default: compose atomic rules
+
+Pick 2-4 rules from `rules-index.md`, glue them together with a single paused GSAP timeline, done. This is faster and produces less code than starting from a blueprint.
+
+## Load a blueprint when
+
+- The scene matches an existing pre-designed multi-phase template (brand-reveal, social-proof, demo-page-scroll-spotlight, etc.) and reusing its phase pipeline saves real authoring time
+- You want runnable ground-truth code for a complex 4-5 phase choreography
+
+Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.md` (recipe) and `examples/<id>.html` (runnable sample). Do not read it speculatively; load it when you've already decided you need scene-level orchestration.
+
+## Routing
+
+| Want to…                                                                       | Read                                                |
+| ------------------------------------------------------------------------------ | --------------------------------------------------- |
+| Pick an atomic motion pattern by trigger / tag                                 | `rules-index.md`                                    |
+| Read one rule's full HTML / CSS / GSAP recipe                                  | `rules/<name>.md`                                   |
+| Pick a multi-phase scene template                                              | `blueprints-index.md`                               |
+| Read one blueprint's full recipe                                               | `blueprints/<id>.md` + `examples/<id>.html`         |
+| Author a scene transition (CSS-driven, between two clips)                      | `transitions/overview.md`, `transitions/catalog.md` |
+| Look up a broader motion-design technique                                      | `techniques.md`                                     |
+| Analyze an existing composition's animation map                                | `scripts/animation-map.mjs`                         |
+| GSAP API — timeline / tweens / position parameters                             | `adapters/gsap.md`                                  |
+| GSAP — drop-in effect recipes                                                  | `rules/gsap-effects.md`                             |
+| GSAP — transforms / perf                                                       | `adapters/gsap-transforms-and-perf.md`              |
+| GSAP — eases / stagger                                                         | `adapters/gsap-easing-and-stagger.md`               |
+| GSAP — timeline / labels                                                       | `adapters/gsap-timeline-and-labels.md`              |
+| Lottie / dotLottie (After Effects exports, `window.__hfLottie`)                | `adapters/lottie.md`                                |
+| Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`)                      | `adapters/three.md`                                 |
+| Anime.js (`window.__hfAnime`)                                                  | `adapters/animejs.md`                               |
+| CSS keyframes (`animation-delay` / `play-state` / `fill-mode`)                 | `adapters/css-animations.md`                        |
+| Web Animations API (`element.animate()`, `currentTime` seek)                   | `adapters/waapi.md`                                 |
+| TypeGPU / WebGPU (`navigator.gpu`, WGSL, compute pipelines)                    | `adapters/typegpu.md`                               |
+| HTML-as-texture + WebGL/GLSL post-fx (capture live DOM via `drawElementImage`) | `adapters/html-in-canvas-patterns.md`               |
+| Named text-animation effects (24 IDs via external `animate-text` skill)        | `adapters/animate-text.md`                          |
+
+## Picking a runtime
+
+- **GSAP** is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
+- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports).
+- **Three.js** for 3D scenes, camera motion, shader-driven visuals.
+- **Anime.js** for lightweight tweening when GSAP is overkill.
+- **CSS** for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.
+- **WAAPI** for native browser keyframes without a GSAP dependency.
+- **TypeGPU / WebGPU** for GPU-rendered canvases (particles, liquid glass, custom shaders).
+
+Multiple runtimes can coexist in one composition. Each registers its instances on the runtime-specific global so HyperFrames can seek all of them in one pass.
+
+## Critical Constraints
+
+**Prerequisite: `hyperframes-core` → Non-Negotiable Rules** (single paused timeline, `data-duration` governs length, no `Math.random` / `Date.now` / `performance.now`, no `repeat: -1`, no `gsap.set` on later-scene clips, no `display` / `visibility` animation, no timeline construction inside `async` / `setTimeout` / `Promise`). Don't restate those here.
+
+Animation-craft additions on top of core's contract:
+
+- **Pre-calculated layout constants** — never derive positions from `getBoundingClientRect()` at tween time. Tween-time DOM measurements desync because the renderer samples in parallel; compute coordinates once at composition setup and reuse.
+- **Spatial motion uses GSAP transform aliases only** (`x`, `y`, `scale`, `rotation`). Core's allowlist also permits `opacity` / `color` / `backgroundColor` / `borderRadius` for non-spatial property tweens — but never `width` / `height` / `top` / `left` for layout changes.
+
+## Scripts
+
+```bash
+node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
+  --out <composition-dir>/.hyperframes/anim-map
+```
+
+Reads every GSAP timeline registered on `window.__timelines`, enumerates tweens, samples bboxes, computes flags, outputs `animation-map.json`. Use it to audit choreography (dead zones, stagger consistency, lifecycle warnings) after authoring.
+
+## See Also
+
+- `hyperframes-core` — composition structure, data attributes, sub-compositions, deterministic render contract
+- `hyperframes-creative` — palettes, typography, narration, beat planning (non-animation creative direction)
+- `hyperframes-cli` — `npx hyperframes lint / validate / inspect / preview / render`

package/skills/hyperframes-cli/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: hyperframes-cli
+description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).
+---
+
+# HyperFrames CLI
+
+Everything runs through `npx hyperframes` unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.
+
+## Workflow
+
+1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL)
+2. **Write** — author HTML composition (see the `hyperframes-core` skill)
+3. **Lint** — `npx hyperframes lint`
+4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
+5. **Visual inspect** — `npx hyperframes inspect`
+6. **Preview** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
+7. **Render** — pick the variant:
+   - Iterate: `npx hyperframes render --quality draft`
+   - Deliver: `npx hyperframes render --quality high --output out.mp4`
+   - CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
+   - Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
+
+Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.
+
+For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec.
+
+## Agent Conventions
+
+Cross-cutting rules that hold for every command:
+
+- **`--json` is available on every command except `render`, `preview`, and `play`.** Use it for any agent / CI invocation of the supported commands; output includes a `_meta` envelope (cli version, latest available, update advice). `render` reports status via stdout + exit code only — verify success with the post-render check below; `preview` / `play` are servers, no JSON.
+- **`doctor --json` always exits 0**, even when the environment is broken. Gate on the payload's `ok` field: `npx hyperframes doctor --json | jq -e '.ok' > /dev/null`. This insulates pipelines from CLI release churn.
+- **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
+- **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
+- **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
+- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
+- **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇  <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.
+
+## Routing
+
+| Want to…                                                                                                   | Read                                  |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| Scaffold a project (`init`, `capture`, `skills`)                                                           | `references/init-and-scaffold.md`     |
+| Check correctness (`lint`, `validate`, `inspect`, `snapshot`)                                              | `references/lint-validate-inspect.md` |
+| Preview or render (`preview`, `play`, `render`, `publish`)                                                 | `references/preview-render.md`        |
+| Diagnose the environment (`doctor`, `browser`)                                                             | `references/doctor-browser.md`        |
+| Cloud render on AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`)              | `references/lambda.md`                |
+| Everything else (`info`, `upgrade`, `compositions`, `docs`, `benchmark`, `telemetry`, asset preprocessing) | `references/upgrade-info-misc.md`     |
+
+## Cross-Skill Hand-Offs
+
+- **Tailwind projects** (`init --tailwind`) → use `hyperframes-core` (Tailwind reference) before editing classes or theme tokens.
+- **Registry blocks/components** (`hyperframes add`, `hyperframes catalog`) → use `hyperframes-registry` for install paths, sub-composition wiring, and snippet merging.
+- **Asset preprocessing** (`tts`, `transcribe`, `remove-background`) → use `hyperframes-media` for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
+- **Parametrized renders** (`--variables`) → declared via `data-composition-variables` on `<html>`; see `hyperframes-core` for the full schema.
+
+## Lambda (Cloud Rendering)
+
+`hyperframes lambda` deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:
+
+```bash
+npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
+npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
+npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)
+```
+
+Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local `render`.
+
+See `references/lambda.md` for prerequisites, all 6 subcommands (`deploy`, `sites create`, `render`, `progress`, `destroy`, `policies`), IAM policy validation, state files, and cost / cleanup rules.
+
+## Minimum Completion Gate
+
+### Static gates
+
+```bash
+npx hyperframes lint
+npx hyperframes validate
+```
+
+Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on lint errors.
+
+### Visual smoke test — required when the project uses sub-compositions
+
+`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The only gate that catches them is one that actually loads `index.html` and seeks the timeline.
+
+Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:
+
+```bash
+# Capture one frame at the midpoint of every sub-composition.
+# Midpoints = data-start + data-duration/2 for each host slot in index.html.
+npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
+
+# Or, if you don't need per-scene targeting, an evenly-spaced sample:
+npx hyperframes snapshot --frames 9
+```
+
+Output lands in `snapshots/frame-NN-at-Xs.png`. Eyeball each frame against the scene plan.
+
+Per-frame red flags (each maps to a specific failure mode the static gates miss):
+
+| What you see                                                                       | Root cause                                                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Text shows up tiny + unstyled in the top-left corner                               | `<style>` block left in `<head>` outside `<template>` (Pitfall 1) — no CSS reached live DOM |
+| SVG/icon elements blown up to canvas-size                                          | Same as above — no width/height constraints applied                                         |
+| Hero element of the scene is missing entirely; only background + watermark visible | Host-id ≠ template id (Pitfall 2) — timeline never ran, frame captured at initial state     |
+| Snapshot command logs `Sub-composition timelines not registered after 45000ms`     | Pitfall 2 — direct confirmation                                                             |
+
+`snapshots/` can be deleted after eyeballing; the user-facing final render is a separate pass with `npx hyperframes render`.

package/skills/hyperframes-core/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: hyperframes-core
+description: The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
+---
+
+# HyperFrames Core
+
+HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.
+
+This skill is the **technical contract** — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in `references/` (index next), read on demand. Other concerns live in the sibling domain skills — `hyperframes-animation`, `hyperframes-creative`, `hyperframes-media`, `hyperframes-cli`, `hyperframes-registry`. The capability map in `/hyperframes` says what each one covers.
+
+## References
+
+| File                                 | Read it to…                                                                                       |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `references/minimal-composition.md`  | start from the smallest renderable composition skeleton                                           |
+| `references/composition-patterns.md` | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype         |
+| `references/data-attributes.md`      | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`           |
+| `references/tracks-and-clips.md`     | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another     |
+| `references/sub-compositions.md`     | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it        |
+| `references/variables-and-media.md`  | declare variables; place `<video>`/`<audio>`, set volume, trim                                    |
+| `references/determinism-rules.md`    | build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit |
+| `references/full-screen-motion.md`   | author full-frame motion with shared backgrounds                                                  |
+| `references/storyboard-format.md`    | author a `STORYBOARD.md` plan (+ the parsed manifest)                                             |
+| `references/script-format.md`        | author the optional `SCRIPT.md` locked narration                                                  |
+| `references/subagent-dispatch.md`    | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness                |
+| `references/tailwind.md`             | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3)      |
+
+For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`.
+
+## Building a composition
+
+### Two root forms (not interchangeable)
+
+- **Standalone** (top-level `index.html`) — root `<div data-composition-id="…">` sits directly in `<body>`, **no `<template>` wrapper** (wrapping it hides all content and breaks rendering).
+- **Sub-composition** (loaded via `data-composition-src`) — root **must** be wrapped in `<template>`.
+
+> ⚠ Transport rule: the runtime **only clones `<template>` contents**; everything outside (incl. `<head>` styles/scripts) is discarded — put `<style>`/`<script>` **inside** the template.
+> ⚠ Host-id rule: the host slot's `data-composition-id` must **exactly equal** the inner template's `data-composition-id` **and** the `window.__timelines["<id>"]` key — no `-mount`/`-slot`/`-host` suffix.
+
+File shape, host wiring, and the pre-render checklist → `references/sub-compositions.md`.
+
+### Root must be sized (silent layout bug)
+
+The standalone root needs an explicit **sized box** (`width`/`height` in px), and every ancestor down to a `height:100%` element must have a resolved height — otherwise a flex/`100%` child collapses to ~0 and content piles into the top-left corner. `lint`/`validate`/`inspect` do **not** catch this. Skeleton → `references/minimal-composition.md`.
+
+### One paused timeline
+
+Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`), built **synchronously** at page load. Render duration = root `data-duration`, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.
+
+### Non-negotiable rules (silent bugs `lint`/`validate`/`inspect` won't catch)
+
+Surfaced here; full rationale in the linked reference. Do not violate:
+
+- No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`
+- Animate only the visual-property allowlist; never `display`/`visibility`; no `gsap.set` on later-scene clips. → `determinism-rules.md`
+- No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`
+- `<video>`/`<audio>` must be a **direct child of the host root** (never inside a sub-comp `<template>`/wrapper); the framework owns playback. → `variables-and-media.md`
+- Every `id` must be unique across the **assembled** page; inside a sub-comp, prefix ids with the composition id (`#<id>-hero`). Duplicate `<video>`/`<img>` ids render **blank** — the producer injects frames by `getElementById`, and cross-file dupes slip past `lint`. → `composition-patterns.md`
+- A full-screen scene fill goes on a full-bleed **child** (`position:absolute; inset:0`), never on the composition root itself — the producer's frame compositing can drop the root element's own `background` (the frame renders **black**) even though preview/`snapshot` show it correctly. → `composition-patterns.md`
+
+## Editing existing compositions
+
+- Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
+- Match existing composition IDs and timeline keys.
+- Adding a clip: pick a non-overlapping `data-track-index` or adjust surrounding timing intentionally.
+- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.
+
+## Validation
+
+Use `hyperframes-cli` for command details
+
+- [ ] `npx hyperframes lint` passes (0 errors)
+- [ ] `npx hyperframes validate` passes (0 console errors)
+- [ ] `npx hyperframes inspect` passes (0 errors)
+- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
+- [ ] `npx hyperframes preview` for review (the user can edit anything in Studio's timeline)
+- [ ] `npx hyperframes render` only after the user approves