launchframe 0.2.1 → 0.2.3

package/template/.github/copilot-instructions.md

@@ -19,13 +19,26 @@ At the project root there is a `launchframe.config.json` containing:
 
 **Always read this file first** at the start of any cloning or build task. The `/clone-website` skill depends on it.
 
+## What the user says (zero-setup flow)
+Users scaffold with `npx launchframe@latest <url> "<saas idea>"` — `npm install` already ran — then they open this folder and say **Build it** (or **Go**, **Ship it**, **Clone the site**).
+
+When you see that with no other instructions, **start the full clone-website pipeline immediately** using only `launchframe.config.json` for `url` and `idea`. Do not ask them to repeat the URL unless the config is missing or invalid. `/clone-website` is an alias for the same work.
+
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
 - **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
+- **Motion:** **Framer Motion** (`framer-motion`) — **default for non-trivial animation** (scroll reveals, staggers, layout, gestures). Use CSS `transition` / `@keyframes` only when they reproduce the target exactly without JS.
 - **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
 - **Styling:** Tailwind CSS v4 with oklch design tokens
+- **Media:** Real **images & videos** from the target URL, saved under `public/images/` and `public/videos/` (see `.claude/skills/clone-website/SKILL.md` and `docs/research/INSPECTION_GUIDE.md`). Do not ship a “pretty shell” with missing raster/video unless extraction is **blocked** and documented in `docs/research/EXTRACTION_LIMITATIONS.md`.
 - **Deployment:** Vercel
 
+## Priority: images, videos & motion
+Treat these as **first-class deliverables**, not polish at the end.
+
+1. **Raster & video** — Early in recon, inventory every `<img>`, `<picture>` / `<source>`, `<video>`, poster image, and meaningful `background-image` URL. Download into `public/` and reference **local paths** in specs and components. Hero bands and marketing sections often fail visually when a single layer is skipped.
+2. **Motion** — Match the target’s feel: easing, duration, stagger, scroll triggers. Prefer **`motion` from `framer-motion`** for entrance sequences, viewport-driven animations, shared-layout-style transitions, and anything beyond a one-off CSS transition. Note in each component spec whether behavior is **CSS-only** vs **Framer Motion**.
+
 ## Commands
 - `npm run dev` — Start dev server
 - `npm run build` — Production build
@@ -41,6 +54,8 @@ At the project root there is a `launchframe.config.json` containing:
 - Responsive: mobile-first
 
 ## Design Principles
+- **Images & video fidelity** — prefer real downloaded assets; preserve aspect ratio, `object-fit`, layering, and poster frames. Rebrand pass may **swap** URLs for IP-safe alternates but must keep layout identical.
+- **Motion fidelity** — timing and easing matter as much as color; use Framer Motion when CSS alone cannot match staggered or scroll-driven behavior.
 - **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
 - **No personal aesthetic changes during emulation phase** — match 1:1 first, rebrand later
 - **Real content during extraction** — use actual text and assets from the target site so the clone scaffolds against real shapes
@@ -76,6 +91,31 @@ scripts/            # Asset download scripts
 
 # Website Inspection Guide
 
+## Priority (read first): media & motion
+
+Launchframe clones live pages for a **visual** result. Two things most often separate a convincing build from a hollow one:
+
+### 1. Images & video (do this before obsessing over utility classes)
+
+- [ ] **Every `<img>`** — `src` / `srcset` / `currentSrc`, `sizes`, `loading`, `decoding`, `alt`, intrinsic dimensions
+- [ ] **`<picture>` / `<source>`** — resolution switches, art direction, `type` (WebP/AVIF)
+- [ ] **Every `<video>`** — `src` + nested `<source>`, **poster**, `autoplay`, `loop`, `muted`, `playsinline`, `controls`
+- [ ] **Background images** — `background-image` on ancestors (hero stacks are often **layers** of img + gradient + PNG mockup)
+- [ ] **Lazy / below-fold** — scroll the page once before asset discovery so `data-src` / lazy-loaded URLs resolve if the site uses them
+- [ ] **Download** — mirror into `public/images/` and `public/videos/` with stable paths; list failures in `docs/research/EXTRACTION_LIMITATIONS.md`
+
+If automation hits a bot wall, **do not pretend extraction succeeded** — capture what you can from successful fetches and document gaps.
+
+### 2. Motion (prefer Framer Motion in this repo)
+
+- [ ] **Entrance** — fade/slide/scale on mount or on **scroll into view** (note threshold / `margin`)
+- [ ] **Stagger** — children animating in sequence (hero bullets, card grids)
+- [ ] **Scroll-linked** — progress, parallax, pinned sections (may combine with CSS `animation-timeline` or libs)
+- [ ] **Gestures** — drag, pan, hover follow (often Framer Motion)
+- [ ] **Implementation rule** — use **`framer-motion`** for anything beyond trivial single-property CSS `transition`. Record **duration, easing, delay, stagger**, and **trigger** (scroll, hover, tap) in specs.
+
+---
+
 ## How to Reverse-Engineer Any Website
 
 This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
@@ -90,6 +130,8 @@ This guide outlines what to capture when inspecting a target website via Chrome
 - [ ] Loading/skeleton states
 - [ ] Empty states
 - [ ] Error states
+- [ ] **Video frames** — capture a frame mid-play for reference if motion is subtle
+- [ ] **Hero / full-bleed** — wide crops where raster layers are easy to miss
 
 ### Design Tokens to Extract
 - [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
@@ -112,7 +154,7 @@ For each distinct UI component, document:
 4. **States** — default, hover, active, disabled, loading, error, empty
 5. **Responsive behavior** — how does it change at different breakpoints?
 6. **Interactions** — click, hover, focus, keyboard navigation
-7. **Animations** — transitions, entrance/exit animations, micro-interactions
+7. **Animations** — transitions, entrance/exit, micro-interactions — **`framer-motion` vs CSS** and exact timing
 
 ### Common Components to Look For
 - Navigation (top bar, sidebar, bottom bar)
@@ -126,6 +168,7 @@ For each distinct UI component, document:
 - Loading skeletons
 - Toast notifications
 - Tooltips and popovers
+- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
 
 ## Phase 3: Layout Architecture
 
@@ -143,14 +186,15 @@ For each distinct UI component, document:
 - [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
 - [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
 - [ ] **Font loading** — Google Fonts, self-hosted, system fonts
-- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
-- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
+- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF — **mirror URLs you are allowed to fetch**
+- [ ] **Animation library** — site may use GSAP, Lottie, Rive, or CSS only — **in the Next.js clone, default to Framer Motion** unless a different lib is required for parity
 
 ## Phase 5: Documentation Output
 
 After inspection, create these files in `docs/research/`:
 1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
 2. `COMPONENT_INVENTORY.md` — Every component with structure notes
-3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
-5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
+3. **`MEDIA_MANIFEST.md`** — (recommended) Table of every image/video/poster URL → local `public/` path or “blocked”
+4. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
+5. `INTERACTION_PATTERNS.md` — Animations: **CSS vs Framer Motion**, transitions, hover states
+6. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents (Framer Motion for React animation)

package/template/.github/skills/clone-website/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clone-website
-description: Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone", "launch a SaaS based on", "build me a clone of". This project was scaffolded by Launchframe — read `launchframe.config.json` for the target URL and the user's SaaS-idea rebranding directive before running. URLs can also be passed inline.
+description: Reverse-engineer and clone one or more websites in one shot — **prioritizes real images/videos** (download to public/) and **motion via Framer Motion** for non-trivial animation. Extracts assets, CSS, and content section-by-section and dispatches parallel builder agents in worktrees. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone", "launch a SaaS based on", "build me a clone of", and Launchframe shorthands **Build it**, **Go**, **Ship it**, **Clone the site** (read `launchframe.config.json` only — no URL in chat). This project was scaffolded by Launchframe — read `launchframe.config.json` for the target URL and the user's SaaS-idea rebranding directive before running. URLs can also be passed inline.
 argument-hint: "[<url1> <url2> ...]  (optional — defaults to launchframe.config.json)"
 user-invocable: true
 ---
@@ -9,6 +9,8 @@ user-invocable: true
 
 You are about to reverse-engineer and rebuild a website as a pixel-perfect clone, then re-skin the copy/branding for the user's SaaS idea.
 
+**Launchframe shorthand:** If the user only says **Build it**, **Go**, **Ship it**, **Clone the site**, or **Run launchframe** with no URL in the message, treat that as an invocation of this skill with empty `$ARGUMENTS` — **`launchframe.config.json` alone** supplies `url` and `idea`. Proceed without asking them to repeat those values unless the file is missing or invalid.
+
 ## Step 0: Read `launchframe.config.json`
 
 **Before doing anything else**, read `launchframe.config.json` at the project root. This file was written by the `launchframe` CLI when the project was scaffolded and is the authoritative source of:
@@ -36,17 +38,23 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 
 ## Pre-Flight
 
-1. **Read `launchframe.config.json`** (see Step 0 above). Echo back the `url` and `idea` to the user so they can confirm before the run starts.
+1. **Read `launchframe.config.json`** (see Step 0 above). After a fresh `npx launchframe` scaffold, proceed immediately — only echo `url`/`idea` for confirmation if the config looks wrong or the user asked to verify.
 2. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
 3. Validate the resolved URL(s). Normalize and verify each is accessible via your browser MCP tool. If any are invalid, ask the user to correct `launchframe.config.json` (or pass an override) before proceeding.
 4. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to run `npm install` first.
-5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
+5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. Plan `docs/research/MEDIA_MANIFEST.md` as soon as media is inventoried. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
 6. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
 
 ## Guiding Principles
 
 These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
 
+### 0. Launchframe priorities: media & motion (do not defer)
+
+**Raster & video are first-class.** Before you treat the page as “mostly typography,” run a dedicated **media inventory** (see `@docs/research/INSPECTION_GUIDE.md` Priority section): every `<img>`, `<picture>` / `<source>`, `<video>` (+ poster), and non-trivial `background-image`. Download to `public/images/` and `public/videos/` and write `docs/research/MEDIA_MANIFEST.md` (URL → local path, or `BLOCKED` + reason). Component specs MUST list concrete `public/...` paths; if you use a placeholder, say why in `docs/research/EXTRACTION_LIMITATIONS.md`. Never silently drop a hero layer, reel, or og visual.
+
+**Motion defaults to Framer Motion.** This template lists `framer-motion` as a dependency. After foundation tokens, ensure `import { motion } from "framer-motion"` (and related APIs: `useScroll`, `useTransform`, `AnimatePresence`, `LayoutGroup`) for: scroll-triggered reveals, staggered children, layout transitions, and gestures — anything beyond a trivial one-property CSS `transition`. In each spec file, add a **Motion** subsection: trigger, duration, easing, delay/stagger, and **implementation: CSS | framer-motion**. Prefer CSS only when it matches the target exactly without JS.
+
 ### 1. Completeness Beats Speed
 
 Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
@@ -191,11 +199,12 @@ Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly bluep
 This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
 
 1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
-2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
-3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
-4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
-5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
-6. Verify: `npm run build` passes
+2. **Confirm Framer Motion** — `framer-motion` should already be in `package.json`. If missing, add it (`npm install framer-motion`) so builders can import `motion` without ad-hoc library drift.
+3. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
+4. **Media inventory + download (early, high priority)** — run the asset discovery script (below) via browser MCP, write `docs/research/MEDIA_MANIFEST.md`, then implement **`scripts/download-assets.mjs`** and execute it so **images** land in `public/images/` and **videos** (+ posters) in `public/videos/` (or a clear subdirectory scheme under `public/`). Batch parallel downloads (4 concurrent) with errors logged — do not claim success if URLs failed. This step should complete **before** most section components are built so builders use real paths.
+5. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
+6. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
+7. Verify: `npm run build` passes
 
 ### Asset Discovery Script Pattern
 
@@ -352,11 +361,16 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
 - **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
 - **Transition:** transition: all 0.3s ease
-- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
+- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | **framer-motion** (`motion`, `whileInView`, stagger container) | etc.>
 
 ### Hover states
 - **<Element>:** <property>: <before> → <after>, transition: <value>
 
+## Motion (Framer Motion vs CSS)
+- **Entrance / scroll reveals:** <e.g. fade+translateY, staggerChildren — specify duration, easing, delay, viewport `once`/`margin`>
+- **Library:** <`framer-motion` | CSS-only — justify if CSS-only>
+- **Keyframes / springs:** <if any — match target curve>
+
 ## Per-State Content (if applicable)
 
 ### State: "Featured"
@@ -368,9 +382,10 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - Title: "..."
 - Cards: [...]
 
-## Assets
-- Background image: `public/images/<file>.webp`
-- Overlay image: `public/images/<file>.png`
+## Assets (images & video — required detail)
+- Raster: `public/images/<file>` — dimensions, `object-fit`, lazy if below fold
+- Video: `public/videos/<file>` — poster `public/images/...` or `public/videos/...`, autoplay/muted/loop, controls
+- Background layers: which div uses `background-image` and resolved URL → local path
 - Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
 
 ## Text Content (verbatim)
@@ -444,7 +459,7 @@ For every section, replace:
 7. **Metadata** — update `<title>`, meta description, OG tags, and favicon manifest in `src/app/layout.tsx` to reflect the new SaaS. Generate a simple favicon (initial letter on a brand-colored square) if no asset is provided.
 
 What you must NOT change in this pass:
-- Spacing, padding, typography scale, color tokens, animations, responsive breakpoints — those are still 1:1 to the original
+- Spacing, padding, typography scale, color tokens, **animation timing & motion choreography** (including Framer Motion `variants` / `transition` props), responsive breakpoints — those are still 1:1 to the original
 - Section order, section count, component structure
 - Interaction models (scroll-driven stays scroll-driven, etc.)
 - Any computed-style value extracted in Phase 3
@@ -478,6 +493,8 @@ Before dispatching ANY builder agent, verify you can check every box. If you can
 - [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
 - [ ] For hover states: before/after values and transition timing are recorded
 - [ ] All images in the section are identified (including overlays and layered compositions)
+- [ ] Any `<video>` (and poster), Lottie, or canvas-driven hero is identified — not approximated as a static div
+- [ ] **Motion** subsection filled: CSS vs **framer-motion**, durations, easings, stagger, scroll triggers
 - [ ] Responsive behavior is documented for at least desktop and mobile
 - [ ] Text content is verbatim from the site, not paraphrased
 - [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
@@ -494,6 +511,8 @@ These are lessons from previous failed clones — each one cost hours of rework:
 - **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
 - **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
 - **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
+- **Don't defer image/video download to the end.** Run `MEDIA_MANIFEST.md` + `download-assets.mjs` during foundation so components reference real `public/` paths from the first build.
+- **Don't fake complex motion with a single CSS `transition` when the target uses staggered, scroll-scrubbed, or layout-driven animation** — use **`framer-motion`** (`motion`, `whileInView`, `variants`, `staggerChildren`) and match duration/easing from extraction.
 - **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
 - **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
 - **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
@@ -508,7 +527,7 @@ When done, report:
 - Total sections built
 - Total components created
 - Total spec files written (should match components)
-- Total assets downloaded (images, videos, SVGs, fonts)
+- Total assets downloaded (images, videos, SVGs, fonts) — path to `docs/research/MEDIA_MANIFEST.md`
 - Rebrand summary (path to `docs/research/REBRAND.md`)
 - Build status (`npm run build` result)
 - Visual QA results (any remaining discrepancies)

package/template/.opencode/commands/clone-website.md

@@ -9,6 +9,8 @@ description: "Reverse-engineer and clone any website as a pixel-perfect replica"
 
 You are about to reverse-engineer and rebuild a website as a pixel-perfect clone, then re-skin the copy/branding for the user's SaaS idea.
 
+**Launchframe shorthand:** If the user only says **Build it**, **Go**, **Ship it**, **Clone the site**, or **Run launchframe** with no URL in the message, treat that as an invocation of this skill with empty `$ARGUMENTS` — **`launchframe.config.json` alone** supplies `url` and `idea`. Proceed without asking them to repeat those values unless the file is missing or invalid.
+
 ## Step 0: Read `launchframe.config.json`
 
 **Before doing anything else**, read `launchframe.config.json` at the project root. This file was written by the `launchframe` CLI when the project was scaffolded and is the authoritative source of:
@@ -36,17 +38,23 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 
 ## Pre-Flight
 
-1. **Read `launchframe.config.json`** (see Step 0 above). Echo back the `url` and `idea` to the user so they can confirm before the run starts.
+1. **Read `launchframe.config.json`** (see Step 0 above). After a fresh `npx launchframe` scaffold, proceed immediately — only echo `url`/`idea` for confirmation if the config looks wrong or the user asked to verify.
 2. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
 3. Validate the resolved URL(s). Normalize and verify each is accessible via your browser MCP tool. If any are invalid, ask the user to correct `launchframe.config.json` (or pass an override) before proceeding.
 4. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to run `npm install` first.
-5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
+5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. Plan `docs/research/MEDIA_MANIFEST.md` as soon as media is inventoried. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
 6. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
 
 ## Guiding Principles
 
 These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
 
+### 0. Launchframe priorities: media & motion (do not defer)
+
+**Raster & video are first-class.** Before you treat the page as “mostly typography,” run a dedicated **media inventory** (see `@docs/research/INSPECTION_GUIDE.md` Priority section): every `<img>`, `<picture>` / `<source>`, `<video>` (+ poster), and non-trivial `background-image`. Download to `public/images/` and `public/videos/` and write `docs/research/MEDIA_MANIFEST.md` (URL → local path, or `BLOCKED` + reason). Component specs MUST list concrete `public/...` paths; if you use a placeholder, say why in `docs/research/EXTRACTION_LIMITATIONS.md`. Never silently drop a hero layer, reel, or og visual.
+
+**Motion defaults to Framer Motion.** This template lists `framer-motion` as a dependency. After foundation tokens, ensure `import { motion } from "framer-motion"` (and related APIs: `useScroll`, `useTransform`, `AnimatePresence`, `LayoutGroup`) for: scroll-triggered reveals, staggered children, layout transitions, and gestures — anything beyond a trivial one-property CSS `transition`. In each spec file, add a **Motion** subsection: trigger, duration, easing, delay/stagger, and **implementation: CSS | framer-motion**. Prefer CSS only when it matches the target exactly without JS.
+
 ### 1. Completeness Beats Speed
 
 Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
@@ -191,11 +199,12 @@ Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly bluep
 This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
 
 1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
-2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
-3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
-4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
-5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
-6. Verify: `npm run build` passes
+2. **Confirm Framer Motion** — `framer-motion` should already be in `package.json`. If missing, add it (`npm install framer-motion`) so builders can import `motion` without ad-hoc library drift.
+3. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
+4. **Media inventory + download (early, high priority)** — run the asset discovery script (below) via browser MCP, write `docs/research/MEDIA_MANIFEST.md`, then implement **`scripts/download-assets.mjs`** and execute it so **images** land in `public/images/` and **videos** (+ posters) in `public/videos/` (or a clear subdirectory scheme under `public/`). Batch parallel downloads (4 concurrent) with errors logged — do not claim success if URLs failed. This step should complete **before** most section components are built so builders use real paths.
+5. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
+6. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
+7. Verify: `npm run build` passes
 
 ### Asset Discovery Script Pattern
 
@@ -352,11 +361,16 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
 - **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
 - **Transition:** transition: all 0.3s ease
-- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
+- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | **framer-motion** (`motion`, `whileInView`, stagger container) | etc.>
 
 ### Hover states
 - **<Element>:** <property>: <before> → <after>, transition: <value>
 
+## Motion (Framer Motion vs CSS)
+- **Entrance / scroll reveals:** <e.g. fade+translateY, staggerChildren — specify duration, easing, delay, viewport `once`/`margin`>
+- **Library:** <`framer-motion` | CSS-only — justify if CSS-only>
+- **Keyframes / springs:** <if any — match target curve>
+
 ## Per-State Content (if applicable)
 
 ### State: "Featured"
@@ -368,9 +382,10 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - Title: "..."
 - Cards: [...]
 
-## Assets
-- Background image: `public/images/<file>.webp`
-- Overlay image: `public/images/<file>.png`
+## Assets (images & video — required detail)
+- Raster: `public/images/<file>` — dimensions, `object-fit`, lazy if below fold
+- Video: `public/videos/<file>` — poster `public/images/...` or `public/videos/...`, autoplay/muted/loop, controls
+- Background layers: which div uses `background-image` and resolved URL → local path
 - Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
 
 ## Text Content (verbatim)
@@ -444,7 +459,7 @@ For every section, replace:
 7. **Metadata** — update `<title>`, meta description, OG tags, and favicon manifest in `src/app/layout.tsx` to reflect the new SaaS. Generate a simple favicon (initial letter on a brand-colored square) if no asset is provided.
 
 What you must NOT change in this pass:
-- Spacing, padding, typography scale, color tokens, animations, responsive breakpoints — those are still 1:1 to the original
+- Spacing, padding, typography scale, color tokens, **animation timing & motion choreography** (including Framer Motion `variants` / `transition` props), responsive breakpoints — those are still 1:1 to the original
 - Section order, section count, component structure
 - Interaction models (scroll-driven stays scroll-driven, etc.)
 - Any computed-style value extracted in Phase 3
@@ -478,6 +493,8 @@ Before dispatching ANY builder agent, verify you can check every box. If you can
 - [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
 - [ ] For hover states: before/after values and transition timing are recorded
 - [ ] All images in the section are identified (including overlays and layered compositions)
+- [ ] Any `<video>` (and poster), Lottie, or canvas-driven hero is identified — not approximated as a static div
+- [ ] **Motion** subsection filled: CSS vs **framer-motion**, durations, easings, stagger, scroll triggers
 - [ ] Responsive behavior is documented for at least desktop and mobile
 - [ ] Text content is verbatim from the site, not paraphrased
 - [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
@@ -494,6 +511,8 @@ These are lessons from previous failed clones — each one cost hours of rework:
 - **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
 - **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
 - **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
+- **Don't defer image/video download to the end.** Run `MEDIA_MANIFEST.md` + `download-assets.mjs` during foundation so components reference real `public/` paths from the first build.
+- **Don't fake complex motion with a single CSS `transition` when the target uses staggered, scroll-scrubbed, or layout-driven animation** — use **`framer-motion`** (`motion`, `whileInView`, `variants`, `staggerChildren`) and match duration/easing from extraction.
 - **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
 - **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
 - **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
@@ -508,7 +527,7 @@ When done, report:
 - Total sections built
 - Total components created
 - Total spec files written (should match components)
-- Total assets downloaded (images, videos, SVGs, fonts)
+- Total assets downloaded (images, videos, SVGs, fonts) — path to `docs/research/MEDIA_MANIFEST.md`
 - Rebrand summary (path to `docs/research/REBRAND.md`)
 - Build status (`npm run build` result)
 - Visual QA results (any remaining discrepancies)

package/template/.windsurf/workflows/clone-website.md

@@ -6,6 +6,8 @@
 
 You are about to reverse-engineer and rebuild a website as a pixel-perfect clone, then re-skin the copy/branding for the user's SaaS idea.
 
+**Launchframe shorthand:** If the user only says **Build it**, **Go**, **Ship it**, **Clone the site**, or **Run launchframe** with no URL in the message, treat that as an invocation of this skill with empty `the target URL provided by the user` — **`launchframe.config.json` alone** supplies `url` and `idea`. Proceed without asking them to repeat those values unless the file is missing or invalid.
+
 ## Step 0: Read `launchframe.config.json`
 
 **Before doing anything else**, read `launchframe.config.json` at the project root. This file was written by the `launchframe` CLI when the project was scaffolded and is the authoritative source of:
@@ -33,17 +35,23 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 
 ## Pre-Flight
 
-1. **Read `launchframe.config.json`** (see Step 0 above). Echo back the `url` and `idea` to the user so they can confirm before the run starts.
+1. **Read `launchframe.config.json`** (see Step 0 above). After a fresh `npx launchframe` scaffold, proceed immediately — only echo `url`/`idea` for confirmation if the config looks wrong or the user asked to verify.
 2. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
 3. Validate the resolved URL(s). Normalize and verify each is accessible via your browser MCP tool. If any are invalid, ask the user to correct `launchframe.config.json` (or pass an override) before proceeding.
 4. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to run `npm install` first.
-5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
+5. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. Plan `docs/research/MEDIA_MANIFEST.md` as soon as media is inventoried. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
 6. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
 
 ## Guiding Principles
 
 These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
 
+### 0. Launchframe priorities: media & motion (do not defer)
+
+**Raster & video are first-class.** Before you treat the page as “mostly typography,” run a dedicated **media inventory** (see `@docs/research/INSPECTION_GUIDE.md` Priority section): every `<img>`, `<picture>` / `<source>`, `<video>` (+ poster), and non-trivial `background-image`. Download to `public/images/` and `public/videos/` and write `docs/research/MEDIA_MANIFEST.md` (URL → local path, or `BLOCKED` + reason). Component specs MUST list concrete `public/...` paths; if you use a placeholder, say why in `docs/research/EXTRACTION_LIMITATIONS.md`. Never silently drop a hero layer, reel, or og visual.
+
+**Motion defaults to Framer Motion.** This template lists `framer-motion` as a dependency. After foundation tokens, ensure `import { motion } from "framer-motion"` (and related APIs: `useScroll`, `useTransform`, `AnimatePresence`, `LayoutGroup`) for: scroll-triggered reveals, staggered children, layout transitions, and gestures — anything beyond a trivial one-property CSS `transition`. In each spec file, add a **Motion** subsection: trigger, duration, easing, delay/stagger, and **implementation: CSS | framer-motion**. Prefer CSS only when it matches the target exactly without JS.
+
 ### 1. Completeness Beats Speed
 
 Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
@@ -188,11 +196,12 @@ Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly bluep
 This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
 
 1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
-2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
-3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
-4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
-5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
-6. Verify: `npm run build` passes
+2. **Confirm Framer Motion** — `framer-motion` should already be in `package.json`. If missing, add it (`npm install framer-motion`) so builders can import `motion` without ad-hoc library drift.
+3. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
+4. **Media inventory + download (early, high priority)** — run the asset discovery script (below) via browser MCP, write `docs/research/MEDIA_MANIFEST.md`, then implement **`scripts/download-assets.mjs`** and execute it so **images** land in `public/images/` and **videos** (+ posters) in `public/videos/` (or a clear subdirectory scheme under `public/`). Batch parallel downloads (4 concurrent) with errors logged — do not claim success if URLs failed. This step should complete **before** most section components are built so builders use real paths.
+5. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
+6. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
+7. Verify: `npm run build` passes
 
 ### Asset Discovery Script Pattern
 
@@ -349,11 +358,16 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
 - **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
 - **Transition:** transition: all 0.3s ease
-- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
+- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | **framer-motion** (`motion`, `whileInView`, stagger container) | etc.>
 
 ### Hover states
 - **<Element>:** <property>: <before> → <after>, transition: <value>
 
+## Motion (Framer Motion vs CSS)
+- **Entrance / scroll reveals:** <e.g. fade+translateY, staggerChildren — specify duration, easing, delay, viewport `once`/`margin`>
+- **Library:** <`framer-motion` | CSS-only — justify if CSS-only>
+- **Keyframes / springs:** <if any — match target curve>
+
 ## Per-State Content (if applicable)
 
 ### State: "Featured"
@@ -365,9 +379,10 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - Title: "..."
 - Cards: [...]
 
-## Assets
-- Background image: `public/images/<file>.webp`
-- Overlay image: `public/images/<file>.png`
+## Assets (images & video — required detail)
+- Raster: `public/images/<file>` — dimensions, `object-fit`, lazy if below fold
+- Video: `public/videos/<file>` — poster `public/images/...` or `public/videos/...`, autoplay/muted/loop, controls
+- Background layers: which div uses `background-image` and resolved URL → local path
 - Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
 
 ## Text Content (verbatim)
@@ -441,7 +456,7 @@ For every section, replace:
 7. **Metadata** — update `<title>`, meta description, OG tags, and favicon manifest in `src/app/layout.tsx` to reflect the new SaaS. Generate a simple favicon (initial letter on a brand-colored square) if no asset is provided.
 
 What you must NOT change in this pass:
-- Spacing, padding, typography scale, color tokens, animations, responsive breakpoints — those are still 1:1 to the original
+- Spacing, padding, typography scale, color tokens, **animation timing & motion choreography** (including Framer Motion `variants` / `transition` props), responsive breakpoints — those are still 1:1 to the original
 - Section order, section count, component structure
 - Interaction models (scroll-driven stays scroll-driven, etc.)
 - Any computed-style value extracted in Phase 3
@@ -475,6 +490,8 @@ Before dispatching ANY builder agent, verify you can check every box. If you can
 - [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
 - [ ] For hover states: before/after values and transition timing are recorded
 - [ ] All images in the section are identified (including overlays and layered compositions)
+- [ ] Any `<video>` (and poster), Lottie, or canvas-driven hero is identified — not approximated as a static div
+- [ ] **Motion** subsection filled: CSS vs **framer-motion**, durations, easings, stagger, scroll triggers
 - [ ] Responsive behavior is documented for at least desktop and mobile
 - [ ] Text content is verbatim from the site, not paraphrased
 - [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
@@ -491,6 +508,8 @@ These are lessons from previous failed clones — each one cost hours of rework:
 - **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
 - **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
 - **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
+- **Don't defer image/video download to the end.** Run `MEDIA_MANIFEST.md` + `download-assets.mjs` during foundation so components reference real `public/` paths from the first build.
+- **Don't fake complex motion with a single CSS `transition` when the target uses staggered, scroll-scrubbed, or layout-driven animation** — use **`framer-motion`** (`motion`, `whileInView`, `variants`, `staggerChildren`) and match duration/easing from extraction.
 - **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
 - **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
 - **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
@@ -505,7 +524,7 @@ When done, report:
 - Total sections built
 - Total components created
 - Total spec files written (should match components)
-- Total assets downloaded (images, videos, SVGs, fonts)
+- Total assets downloaded (images, videos, SVGs, fonts) — path to `docs/research/MEDIA_MANIFEST.md`
 - Rebrand summary (path to `docs/research/REBRAND.md`)
 - Build status (`npm run build` result)
 - Visual QA results (any remaining discrepancies)

package/template/AGENTS.md

@@ -16,13 +16,26 @@ At the project root there is a `launchframe.config.json` containing:
 
 **Always read this file first** at the start of any cloning or build task. The `/clone-website` skill depends on it.
 
+## What the user says (zero-setup flow)
+Users scaffold with `npx launchframe@latest <url> "<saas idea>"` — `npm install` already ran — then they open this folder and say **Build it** (or **Go**, **Ship it**, **Clone the site**).
+
+When you see that with no other instructions, **start the full clone-website pipeline immediately** using only `launchframe.config.json` for `url` and `idea`. Do not ask them to repeat the URL unless the config is missing or invalid. `/clone-website` is an alias for the same work.
+
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
 - **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
+- **Motion:** **Framer Motion** (`framer-motion`) — **default for non-trivial animation** (scroll reveals, staggers, layout, gestures). Use CSS `transition` / `@keyframes` only when they reproduce the target exactly without JS.
 - **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
 - **Styling:** Tailwind CSS v4 with oklch design tokens
+- **Media:** Real **images & videos** from the target URL, saved under `public/images/` and `public/videos/` (see `.claude/skills/clone-website/SKILL.md` and `docs/research/INSPECTION_GUIDE.md`). Do not ship a “pretty shell” with missing raster/video unless extraction is **blocked** and documented in `docs/research/EXTRACTION_LIMITATIONS.md`.
 - **Deployment:** Vercel
 
+## Priority: images, videos & motion
+Treat these as **first-class deliverables**, not polish at the end.
+
+1. **Raster & video** — Early in recon, inventory every `<img>`, `<picture>` / `<source>`, `<video>`, poster image, and meaningful `background-image` URL. Download into `public/` and reference **local paths** in specs and components. Hero bands and marketing sections often fail visually when a single layer is skipped.
+2. **Motion** — Match the target’s feel: easing, duration, stagger, scroll triggers. Prefer **`motion` from `framer-motion`** for entrance sequences, viewport-driven animations, shared-layout-style transitions, and anything beyond a one-off CSS transition. Note in each component spec whether behavior is **CSS-only** vs **Framer Motion**.
+
 ## Commands
 - `npm run dev` — Start dev server
 - `npm run build` — Production build
@@ -38,6 +51,8 @@ At the project root there is a `launchframe.config.json` containing:
 - Responsive: mobile-first
 
 ## Design Principles
+- **Images & video fidelity** — prefer real downloaded assets; preserve aspect ratio, `object-fit`, layering, and poster frames. Rebrand pass may **swap** URLs for IP-safe alternates but must keep layout identical.
+- **Motion fidelity** — timing and easing matter as much as color; use Framer Motion when CSS alone cannot match staggered or scroll-driven behavior.
 - **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
 - **No personal aesthetic changes during emulation phase** — match 1:1 first, rebrand later
 - **Real content during extraction** — use actual text and assets from the target site so the clone scaffolds against real shapes