launchframe 0.2.3 → 0.2.4

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

@@ -45,6 +45,17 @@ Treat these as **first-class deliverables**, not polish at the end.
 - `npm run lint` — ESLint check
 - `npm run typecheck` — TypeScript check
 - `npm run check` — Run lint + typecheck + build
+- **`npm run recon`** — **Playwright** capture: full-page screenshots, `computed-snapshot.json`, `MEDIA_MANIFEST.md` (use when Browser MCP / Chrome DevTools MCP is broken or missing)
+- **`npm run recon:headed`** — Same as `recon` but **headed** Chromium (often better for WAF / “Just a moment…” pages)
+
+**Playwright browser binaries (once per machine):** `npx playwright install chromium`
+
+## When Browser MCP is down
+Prefer **Playwright** for repeatable extraction in-repo — do **not** rely on Chrome DevTools MCP alone.
+
+1. Run **`npm run recon`** (or **`npm run recon:headed`** if headless hits a challenge page).
+2. Read **`docs/research/computed-snapshot.json`**, **`docs/research/MEDIA_MANIFEST.md`**, and **`docs/research/EXTRACTION_LIMITATIONS.md`** before writing specs.
+3. Fill **`scripts/download-assets.mjs`** from `MEDIA_MANIFEST.md` and run it to populate `public/images/` and `public/videos/`.
 
 ## Code Style
 - TypeScript strict mode, no `any`
@@ -89,112 +100,112 @@ scripts/            # Asset download scripts
 - After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
 - After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
 
-# 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.
-
-## Phase 1: Visual Audit
-
-### Screenshots to Capture
-- [ ] Every distinct page — desktop, tablet, mobile
-- [ ] Dark mode variants (if applicable)
-- [ ] Light mode variants (if applicable)
-- [ ] Key interaction states (hover, active, open menus, modals)
-- [ ] 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
-- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
-- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
-- [ ] **Border radius** — buttons, cards, avatars, inputs
-- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
-- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
-- [ ] **Icons** — which icon library? custom SVGs? sizes?
-- [ ] **Avatars** — sizes, shapes, fallback behavior
-- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
-- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
-
-## Phase 2: Component Inventory
-
-For each distinct UI component, document:
-1. **Name** — what would you call this component?
-2. **Structure** — what HTML elements / child components does it contain?
-3. **Variants** — does it have different sizes, colors, or states?
-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, micro-interactions — **`framer-motion` vs CSS** and exact timing
-
-### Common Components to Look For
-- Navigation (top bar, sidebar, bottom bar)
-- Cards / list items
-- Buttons and links
-- Forms and inputs
-- Modals and dialogs
-- Dropdowns and menus
-- Tabs and segmented controls
-- Avatars and user badges
-- Loading skeletons
-- Toast notifications
-- Tooltips and popovers
-- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
-
-## Phase 3: Layout Architecture
-
-- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
-- [ ] **Column layout** — how many columns at each breakpoint?
-- [ ] **Max-width** — main content area max-width
-- [ ] **Sticky elements** — header, sidebar, floating buttons
-- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
-- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
-
-## Phase 4: Technical Stack Analysis
-
-- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
-- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
-- [ ] **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 — **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. **`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)
+# 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.
+
+## Phase 1: Visual Audit
+
+### Screenshots to Capture
+- [ ] Every distinct page — desktop, tablet, mobile
+- [ ] Dark mode variants (if applicable)
+- [ ] Light mode variants (if applicable)
+- [ ] Key interaction states (hover, active, open menus, modals)
+- [ ] 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
+- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
+- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
+- [ ] **Border radius** — buttons, cards, avatars, inputs
+- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
+- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
+- [ ] **Icons** — which icon library? custom SVGs? sizes?
+- [ ] **Avatars** — sizes, shapes, fallback behavior
+- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
+- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
+
+## Phase 2: Component Inventory
+
+For each distinct UI component, document:
+1. **Name** — what would you call this component?
+2. **Structure** — what HTML elements / child components does it contain?
+3. **Variants** — does it have different sizes, colors, or states?
+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, micro-interactions — **`framer-motion` vs CSS** and exact timing
+
+### Common Components to Look For
+- Navigation (top bar, sidebar, bottom bar)
+- Cards / list items
+- Buttons and links
+- Forms and inputs
+- Modals and dialogs
+- Dropdowns and menus
+- Tabs and segmented controls
+- Avatars and user badges
+- Loading skeletons
+- Toast notifications
+- Tooltips and popovers
+- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
+
+## Phase 3: Layout Architecture
+
+- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
+- [ ] **Column layout** — how many columns at each breakpoint?
+- [ ] **Max-width** — main content area max-width
+- [ ] **Sticky elements** — header, sidebar, floating buttons
+- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
+- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
+
+## Phase 4: Technical Stack Analysis
+
+- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
+- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
+- [ ] **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 — **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. **`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

@@ -39,7 +39,7 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 ## Pre-Flight
 
 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.
+2. **Browser automation.** Prefer an MCP (Chrome DevTools MCP, Playwright MCP, Browserbase MCP, etc.) when it is healthy. **If MCP is missing or in an error state, run `npm run recon` (Playwright)** — see `scripts/recon-playwright.mjs`. It writes `docs/research/computed-snapshot.json`, `docs/research/MEDIA_MANIFEST.md`, and full-page screenshots under `docs/design-references/`. Use `npm run recon:headed` if headless hits a WAF/challenge page. One-time install: `npx playwright install chromium`. Do not skip extraction — adapt the pipeline to the tools that work.
 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/`. 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>/`.

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

@@ -39,7 +39,7 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 ## Pre-Flight
 
 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.
+2. **Browser automation.** Prefer an MCP (Chrome DevTools MCP, Playwright MCP, Browserbase MCP, etc.) when it is healthy. **If MCP is missing or in an error state, run `npm run recon` (Playwright)** — see `scripts/recon-playwright.mjs`. It writes `docs/research/computed-snapshot.json`, `docs/research/MEDIA_MANIFEST.md`, and full-page screenshots under `docs/design-references/`. Use `npm run recon:headed` if headless hits a WAF/challenge page. One-time install: `npx playwright install chromium`. Do not skip extraction — adapt the pipeline to the tools that work.
 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/`. 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>/`.

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

@@ -36,7 +36,7 @@ If the user provides additional instructions (specific fidelity level, deeper cu
 ## Pre-Flight
 
 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.
+2. **Browser automation.** Prefer an MCP (Chrome DevTools MCP, Playwright MCP, Browserbase MCP, etc.) when it is healthy. **If MCP is missing or in an error state, run `npm run recon` (Playwright)** — see `scripts/recon-playwright.mjs`. It writes `docs/research/computed-snapshot.json`, `docs/research/MEDIA_MANIFEST.md`, and full-page screenshots under `docs/design-references/`. Use `npm run recon:headed` if headless hits a WAF/challenge page. One-time install: `npx playwright install chromium`. Do not skip extraction — adapt the pipeline to the tools that work.
 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/`. 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>/`.

package/template/AGENTS.md

@@ -1,89 +1,100 @@
-<!-- BEGIN:nextjs-agent-rules -->
-# This is NOT the Next.js you know
-
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
-<!-- END:nextjs-agent-rules -->
-
-# Launchframe Project (AI Website Cloner + SaaS Rebrand)
-
-## What This Is
-This project was scaffolded by [Launchframe](https://github.com/evangruhlkey/launchframe) via `npx launchframe@latest <url> "<saas idea>"`. It is a Next.js + shadcn/ui + Tailwind v4 base wired with an AI-cloner skill (`/clone-website`) that reverse-engineers a real website pixel-perfectly and then re-skins its copy/branding for the user's SaaS idea.
-
-## Single Source of Truth: `launchframe.config.json`
-At the project root there is a `launchframe.config.json` containing:
-- `url` — the visual source-of-truth to clone
-- `idea` — the SaaS idea used as the rebranding directive after the clone
-
-**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
-- `npm run lint` — ESLint check
-- `npm run typecheck` — TypeScript check
-- `npm run check` — Run lint + typecheck + build
-
-## Code Style
-- TypeScript strict mode, no `any`
-- Named exports, PascalCase components, camelCase utils
-- Tailwind utility classes, no inline styles
-- 2-space indentation
-- 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
-- **Rebrand pass swaps copy, not visuals** — once the clone is built, replace product name, headlines, feature copy, and brand marks with content tuned to `launchframe.config.json#idea`. Do NOT alter spacing, color tokens, typography scale, animations, or responsive breakpoints during the rebrand.
-- **Beauty-first** — every pixel matters
-
-## Project Structure
-```
-src/
-  app/              # Next.js routes
-  components/       # React components
-    ui/             # shadcn/ui primitives
-    icons.tsx       # Extracted SVG icons as React components
-  lib/
-    utils.ts        # cn() utility (shadcn)
-  types/            # TypeScript interfaces
-  hooks/            # Custom React hooks
-public/
-  images/           # Downloaded images from target site
-  videos/           # Downloaded videos from target site
-  seo/              # Favicons, OG images, webmanifest
-docs/
-  research/         # Inspection output (design tokens, components, layout)
-  design-references/ # Screenshots and visual references
-scripts/            # Asset download scripts
-```
-
-## MOST IMPORTANT NOTES
-- **Always start by reading `launchframe.config.json`** — that file dictates the URL to clone and the SaaS idea to re-skin for.
-- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
-- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
-- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
-
-@docs/research/INSPECTION_GUIDE.md
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->
+
+# Launchframe Project (AI Website Cloner + SaaS Rebrand)
+
+## What This Is
+This project was scaffolded by [Launchframe](https://github.com/evangruhlkey/launchframe) via `npx launchframe@latest <url> "<saas idea>"`. It is a Next.js + shadcn/ui + Tailwind v4 base wired with an AI-cloner skill (`/clone-website`) that reverse-engineers a real website pixel-perfectly and then re-skins its copy/branding for the user's SaaS idea.
+
+## Single Source of Truth: `launchframe.config.json`
+At the project root there is a `launchframe.config.json` containing:
+- `url` — the visual source-of-truth to clone
+- `idea` — the SaaS idea used as the rebranding directive after the clone
+
+**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
+- `npm run lint` — ESLint check
+- `npm run typecheck` — TypeScript check
+- `npm run check` — Run lint + typecheck + build
+- **`npm run recon`** — **Playwright** capture: full-page screenshots, `computed-snapshot.json`, `MEDIA_MANIFEST.md` (use when Browser MCP / Chrome DevTools MCP is broken or missing)
+- **`npm run recon:headed`** — Same as `recon` but **headed** Chromium (often better for WAF / “Just a moment…” pages)
+
+**Playwright browser binaries (once per machine):** `npx playwright install chromium`
+
+## When Browser MCP is down
+Prefer **Playwright** for repeatable extraction in-repo — do **not** rely on Chrome DevTools MCP alone.
+
+1. Run **`npm run recon`** (or **`npm run recon:headed`** if headless hits a challenge page).
+2. Read **`docs/research/computed-snapshot.json`**, **`docs/research/MEDIA_MANIFEST.md`**, and **`docs/research/EXTRACTION_LIMITATIONS.md`** before writing specs.
+3. Fill **`scripts/download-assets.mjs`** from `MEDIA_MANIFEST.md` and run it to populate `public/images/` and `public/videos/`.
+
+## Code Style
+- TypeScript strict mode, no `any`
+- Named exports, PascalCase components, camelCase utils
+- Tailwind utility classes, no inline styles
+- 2-space indentation
+- 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
+- **Rebrand pass swaps copy, not visuals** — once the clone is built, replace product name, headlines, feature copy, and brand marks with content tuned to `launchframe.config.json#idea`. Do NOT alter spacing, color tokens, typography scale, animations, or responsive breakpoints during the rebrand.
+- **Beauty-first** — every pixel matters
+
+## Project Structure
+```
+src/
+  app/              # Next.js routes
+  components/       # React components
+    ui/             # shadcn/ui primitives
+    icons.tsx       # Extracted SVG icons as React components
+  lib/
+    utils.ts        # cn() utility (shadcn)
+  types/            # TypeScript interfaces
+  hooks/            # Custom React hooks
+public/
+  images/           # Downloaded images from target site
+  videos/           # Downloaded videos from target site
+  seo/              # Favicons, OG images, webmanifest
+docs/
+  research/         # Inspection output (design tokens, components, layout)
+  design-references/ # Screenshots and visual references
+scripts/            # Asset download scripts
+```
+
+## MOST IMPORTANT NOTES
+- **Always start by reading `launchframe.config.json`** — that file dictates the URL to clone and the SaaS idea to re-skin for.
+- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
+- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
+- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
+
+@docs/research/INSPECTION_GUIDE.md