launchframe 0.2.4 → 0.2.6

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.** 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.
+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 performs **stabilized full-document scrolling** at desktop and mobile, writes merged **`computed-snapshot.json`** + **`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>/`.
@@ -53,7 +53,9 @@ These are the truths that separate a successful clone from a "close enough" mess
 
 **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.
+**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`, **`useReducedMotion`**) 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, **tier A–E coverage** (see `AGENTS.md` production polish table), reduced-motion fallback, and **implementation: CSS | framer-motion**. Prefer CSS only when it matches the target exactly without JS.
+
+**Illustration & pixel art are production inputs.** Where the target (or post-rebrand layout) lacks convincing visuals, specs MUST allocate **idea-tailored SVG scenes** — metaphors drawn from `launchframe.config.json#idea`, documented with **Idea tie-in** per asset — not generic gray placeholders or unrelated clipart. Pixel-art motifs require concept justification plus palette table in the spec.
 
 ### 1. Completeness Beats Speed
 
@@ -140,10 +142,12 @@ Every builder agent must verify `npx tsc --noEmit` passes before finishing. Afte
 
 Navigate to the target URL with browser MCP.
 
-### Screenshots
-- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
-- Save to `docs/design-references/` with descriptive names
-- These are your master reference — builders will receive section-specific crops/screenshots later
+### Screenshots *(entire landing — never “above the fold” only)*
+- Capture the **whole marketing surface**: hero through footer (single-page landings). Do **not** stop after the first viewport — lazy-loaded sections, footer nav, and bottom CTAs are required context.
+- Before **every** full-page capture (MCP or Playwright): **slow scroll top → bottom → top** once or twice until `scrollHeight` stops growing, so lazy images/`srcset`/`data-src` resolve where possible.
+- Take **`fullPage: true`** (or MCP equivalent) screenshots at desktop (**1440px**) and mobile (**390px**); save under `docs/design-references/` with descriptive names.
+- **`npm run recon`** already performs stabilized full-document scrolling + merged desktop/mobile asset inventory — prefer running it when automation must match full-page depth reliably.
+- These masters are references — builders still get section crops later, but those crops must exist because **you** scrolled and documented every band first.
 
 ### Global Extraction
 Extract these from the page before doing anything else:
@@ -367,10 +371,19 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **<Element>:** <property>: <before> → <after>, transition: <value>
 
 ## Motion (Framer Motion vs CSS)
+- **Tiers A–E:** <which tiers apply — load stagger, scroll reveal, ambient loop, interaction lifts, decorative parallax — list triggers>
+- **Reduced motion:** <what disables or simplifies when user prefers reduced motion>
 - **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>
 
+## Illustration & pixel art *(production uplift — idea-native)*
+- **Idea tie-in:** <one sentence — why this asset belongs only to this product>
+- **Metaphor link:** <which keyword from `idea` / metaphor list this illustrates>
+- **SVG components:** <named exports, paths using currentColor vs fixed fills>
+- **Pixel motif:** <palette hex table, grid, scaling — or N/A>
+- **Motif thread:** <how this echoes logo / OG / favicon for this SaaS>
+
 ## Per-State Content (if applicable)
 
 ### State: "Featured"
@@ -451,11 +464,7 @@ For every section, replace:
 3. **Feature/section copy** — rewrite each feature card, callout, stat, and testimonial to fit the SaaS idea. Preserve the count and shape of items (3 feature cards stay 3 feature cards; a 4-column logo bar stays 4 columns). Generate plausible customer-logo names — never use real company names you haven't been authorized to use.
 4. **CTA labels** — adapt button text to the SaaS idea ("Start free", "Get a demo", "Try it free", etc.). Keep the CTA hierarchy (primary/secondary) identical to the original.
 5. **Mock data** — for product UI mockups embedded in marketing screenshots (e.g., a fake dashboard inside a hero), generate mock data shaped for the SaaS idea: realistic-looking but fictional rows, charts, conversation logs, etc.
-6. **Imagery** — placeholder-swap any photography or product screenshots that depict the original brand. Prefer using:
-   - A neutral abstract gradient / shape composition you generate with CSS or SVG
-   - A Lucide icon arrangement
-   - Placeholder service URLs only if explicitly allowed by the user
-   Keep dimensions, aspect ratios, drop shadows, and surrounding spacing identical to the original.
+6. **Imagery** — Replace photography/screenshots that depict the original brand with visuals **authored for this SaaS idea**, not interchangeable decoration. Before designing: derive a **metaphor list** from `idea` (3–6 concrete hooks). Each hero/feature/OG asset gets an **Idea tie-in** sentence in `docs/research/REBRAND.md`. Prefer bespoke SVG scenes (`src/components/marketing/art/`) or raster under `public/images/marketing/` that preserve dimensions/aspect/shadows from the cloned layout. **Avoid:** unrelated filler (e.g. apparel, random lifestyle props when the product is notes/voice), generic gradient-only heroes, Lucide-icon piles unless the reference was already that minimal — those fail the uniqueness bar in `AGENTS.md`.
 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:
@@ -466,6 +475,25 @@ What you must NOT change in this pass:
 
 After the rebrand pass, the codebase should look like the original site visually but read like the user's SaaS at a glance. Save a short `docs/research/REBRAND.md` summarizing the product name you chose, the headline rewrites, and any assets you swapped — so the user can audit what's clone-derived vs. authored.
 
+## Phase 4.6: Production uplift *(sparse references / stronger idea-specific art)*
+
+Run this pass when **any** of the following is true:
+
+- The cloned reference is mostly typography with weak imagery (internal demos, minimalist SaaS shells).
+- The user asks for **more unique images**, **illustration tailored to the idea**, **stronger visuals**, motion, pixel art, or production polish.
+- Visual QA feels “correct but dead” — layout matches but art is generic, unrelated, or repeated stock metaphors.
+
+**Do not contradict pixel-perfect emulation when cloning a rich reference** — this phase *adds* or swaps **idea-native** imagery only where the brief allows uplift or the reference was inherently flat.
+
+Checklist (mirror `AGENTS.md` — **uniqueness first**):
+
+1. **Idea-tailored imagery** — Metaphor list from `idea`; replace any asset that could belong to another vertical. Per-asset **Idea tie-in** in `docs/research/PRODUCTION_UPLIFT.md` alongside SVG/raster paths.
+2. **Density** — Layered hero + distinct scene per feature card in **one shared visual language** (stroke/accent/grid), still idea-specific.
+3. **Motion tiers** — Implement at minimum **A + B + one of C/D**, optionally **E**: staggered hero load, `whileInView` sections + card stagger, looping ambient (marquee / caret / SVG dash loop), hover lifts / nav scroll shrink, optional light parallax. Gate loops with **`useReducedMotion()`**.
+4. **Brand** — Motif thread + accent tokens in `:root`; favicon / OG echo **this** product narrative.
+
+Document deltas in `docs/research/PRODUCTION_UPLIFT.md`.
+
 ## Phase 5: Visual QA Diff
 
 After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
@@ -494,7 +522,8 @@ Before dispatching ANY builder agent, verify you can check every box. If you can
 - [ ] 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
+- [ ] **Motion** subsection filled: tiers **A–E** coverage (see `AGENTS.md`), CSS vs **framer-motion**, durations, easings, stagger, scroll triggers, **reduced-motion** fallback
+- [ ] **Illustration** subsection filled when uplift applies: **Idea tie-in** + metaphor link per asset, SVG/pixel detail — or explicit **N/A** with justification only on strict clone parity jobs
 - [ ] 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
@@ -517,6 +546,7 @@ These are lessons from previous failed clones — each one cost hours of rework:
 - **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.
 - **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
+- **Don't ship interchangeable marketing art.** Random objects, unrelated lifestyle stock, or generic gradients that could match any SaaS violate the **idea-tailored** rule in `AGENTS.md` — every major visual needs a metaphor from `launchframe.config.json#idea`.
 - **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
 
 ## Completion

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.** 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.
+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 performs **stabilized full-document scrolling** at desktop and mobile, writes merged **`computed-snapshot.json`** + **`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>/`.
@@ -50,7 +50,9 @@ These are the truths that separate a successful clone from a "close enough" mess
 
 **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.
+**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`, **`useReducedMotion`**) 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, **tier A–E coverage** (see `AGENTS.md` production polish table), reduced-motion fallback, and **implementation: CSS | framer-motion**. Prefer CSS only when it matches the target exactly without JS.
+
+**Illustration & pixel art are production inputs.** Where the target (or post-rebrand layout) lacks convincing visuals, specs MUST allocate **idea-tailored SVG scenes** — metaphors drawn from `launchframe.config.json#idea`, documented with **Idea tie-in** per asset — not generic gray placeholders or unrelated clipart. Pixel-art motifs require concept justification plus palette table in the spec.
 
 ### 1. Completeness Beats Speed
 
@@ -137,10 +139,12 @@ Every builder agent must verify `npx tsc --noEmit` passes before finishing. Afte
 
 Navigate to the target URL with browser MCP.
 
-### Screenshots
-- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
-- Save to `docs/design-references/` with descriptive names
-- These are your master reference — builders will receive section-specific crops/screenshots later
+### Screenshots *(entire landing — never “above the fold” only)*
+- Capture the **whole marketing surface**: hero through footer (single-page landings). Do **not** stop after the first viewport — lazy-loaded sections, footer nav, and bottom CTAs are required context.
+- Before **every** full-page capture (MCP or Playwright): **slow scroll top → bottom → top** once or twice until `scrollHeight` stops growing, so lazy images/`srcset`/`data-src` resolve where possible.
+- Take **`fullPage: true`** (or MCP equivalent) screenshots at desktop (**1440px**) and mobile (**390px**); save under `docs/design-references/` with descriptive names.
+- **`npm run recon`** already performs stabilized full-document scrolling + merged desktop/mobile asset inventory — prefer running it when automation must match full-page depth reliably.
+- These masters are references — builders still get section crops later, but those crops must exist because **you** scrolled and documented every band first.
 
 ### Global Extraction
 Extract these from the page before doing anything else:
@@ -364,10 +368,19 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **<Element>:** <property>: <before> → <after>, transition: <value>
 
 ## Motion (Framer Motion vs CSS)
+- **Tiers A–E:** <which tiers apply — load stagger, scroll reveal, ambient loop, interaction lifts, decorative parallax — list triggers>
+- **Reduced motion:** <what disables or simplifies when user prefers reduced motion>
 - **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>
 
+## Illustration & pixel art *(production uplift — idea-native)*
+- **Idea tie-in:** <one sentence — why this asset belongs only to this product>
+- **Metaphor link:** <which keyword from `idea` / metaphor list this illustrates>
+- **SVG components:** <named exports, paths using currentColor vs fixed fills>
+- **Pixel motif:** <palette hex table, grid, scaling — or N/A>
+- **Motif thread:** <how this echoes logo / OG / favicon for this SaaS>
+
 ## Per-State Content (if applicable)
 
 ### State: "Featured"
@@ -448,11 +461,7 @@ For every section, replace:
 3. **Feature/section copy** — rewrite each feature card, callout, stat, and testimonial to fit the SaaS idea. Preserve the count and shape of items (3 feature cards stay 3 feature cards; a 4-column logo bar stays 4 columns). Generate plausible customer-logo names — never use real company names you haven't been authorized to use.
 4. **CTA labels** — adapt button text to the SaaS idea ("Start free", "Get a demo", "Try it free", etc.). Keep the CTA hierarchy (primary/secondary) identical to the original.
 5. **Mock data** — for product UI mockups embedded in marketing screenshots (e.g., a fake dashboard inside a hero), generate mock data shaped for the SaaS idea: realistic-looking but fictional rows, charts, conversation logs, etc.
-6. **Imagery** — placeholder-swap any photography or product screenshots that depict the original brand. Prefer using:
-   - A neutral abstract gradient / shape composition you generate with CSS or SVG
-   - A Lucide icon arrangement
-   - Placeholder service URLs only if explicitly allowed by the user
-   Keep dimensions, aspect ratios, drop shadows, and surrounding spacing identical to the original.
+6. **Imagery** — Replace photography/screenshots that depict the original brand with visuals **authored for this SaaS idea**, not interchangeable decoration. Before designing: derive a **metaphor list** from `idea` (3–6 concrete hooks). Each hero/feature/OG asset gets an **Idea tie-in** sentence in `docs/research/REBRAND.md`. Prefer bespoke SVG scenes (`src/components/marketing/art/`) or raster under `public/images/marketing/` that preserve dimensions/aspect/shadows from the cloned layout. **Avoid:** unrelated filler (e.g. apparel, random lifestyle props when the product is notes/voice), generic gradient-only heroes, Lucide-icon piles unless the reference was already that minimal — those fail the uniqueness bar in `AGENTS.md`.
 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:
@@ -463,6 +472,25 @@ What you must NOT change in this pass:
 
 After the rebrand pass, the codebase should look like the original site visually but read like the user's SaaS at a glance. Save a short `docs/research/REBRAND.md` summarizing the product name you chose, the headline rewrites, and any assets you swapped — so the user can audit what's clone-derived vs. authored.
 
+## Phase 4.6: Production uplift *(sparse references / stronger idea-specific art)*
+
+Run this pass when **any** of the following is true:
+
+- The cloned reference is mostly typography with weak imagery (internal demos, minimalist SaaS shells).
+- The user asks for **more unique images**, **illustration tailored to the idea**, **stronger visuals**, motion, pixel art, or production polish.
+- Visual QA feels “correct but dead” — layout matches but art is generic, unrelated, or repeated stock metaphors.
+
+**Do not contradict pixel-perfect emulation when cloning a rich reference** — this phase *adds* or swaps **idea-native** imagery only where the brief allows uplift or the reference was inherently flat.
+
+Checklist (mirror `AGENTS.md` — **uniqueness first**):
+
+1. **Idea-tailored imagery** — Metaphor list from `idea`; replace any asset that could belong to another vertical. Per-asset **Idea tie-in** in `docs/research/PRODUCTION_UPLIFT.md` alongside SVG/raster paths.
+2. **Density** — Layered hero + distinct scene per feature card in **one shared visual language** (stroke/accent/grid), still idea-specific.
+3. **Motion tiers** — Implement at minimum **A + B + one of C/D**, optionally **E**: staggered hero load, `whileInView` sections + card stagger, looping ambient (marquee / caret / SVG dash loop), hover lifts / nav scroll shrink, optional light parallax. Gate loops with **`useReducedMotion()`**.
+4. **Brand** — Motif thread + accent tokens in `:root`; favicon / OG echo **this** product narrative.
+
+Document deltas in `docs/research/PRODUCTION_UPLIFT.md`.
+
 ## Phase 5: Visual QA Diff
 
 After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
@@ -491,7 +519,8 @@ Before dispatching ANY builder agent, verify you can check every box. If you can
 - [ ] 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
+- [ ] **Motion** subsection filled: tiers **A–E** coverage (see `AGENTS.md`), CSS vs **framer-motion**, durations, easings, stagger, scroll triggers, **reduced-motion** fallback
+- [ ] **Illustration** subsection filled when uplift applies: **Idea tie-in** + metaphor link per asset, SVG/pixel detail — or explicit **N/A** with justification only on strict clone parity jobs
 - [ ] 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
@@ -514,6 +543,7 @@ These are lessons from previous failed clones — each one cost hours of rework:
 - **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.
 - **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
+- **Don't ship interchangeable marketing art.** Random objects, unrelated lifestyle stock, or generic gradients that could match any SaaS violate the **idea-tailored** rule in `AGENTS.md` — every major visual needs a metaphor from `launchframe.config.json#idea`.
 - **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
 
 ## Completion

package/template/AGENTS.md

@@ -35,6 +35,59 @@ 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**.
+3. **Illustration & brand marks** — Inline **SVG React components** (not only Lucide) for motifs that repeat across sections: logo glyph variants, dividers, grain/noise overlays, hero “scene” shapes, feature-card mini-compositions. Prefer **`currentColor`** + CSS variables so SVGs inherit theme tokens. For **pixel art**, keep a tight palette (4–8 fills), consistent pixel grid logic, and use `style={{ imageRendering: "pixelated" }}` on upscaled raster OR build pixel SVG paths intentionally — never blurry upscale.
+
+## Production polish for marketing landings *(idea-tailored visuals + motion + brand)*
+
+Use this whenever the page is **authored or minimalist** (internal templates, rebranded clones that still feel flat, or targets that are mostly typography). “Looks OK” is not ship-ready — **production landings** stack multiple visual layers, choreographed motion, and cues that clearly belong to **this** product (`launchframe.config.json#idea`), not any SaaS.
+
+### Idea-tailored imagery *(uniqueness bar)*
+
+Generic decoration fails review. Apply this to **every** hero composition, feature-card illustration, OG image sketch, and major `public/` marketing raster.
+
+1. **Derive metaphors from the idea** — Read `idea` (and product name). List 3–6 concrete nouns/verbs the product owns (e.g. voice → waveform, mic; notes → folded page, margin line; sync → paired arrows). Every bespoke visual must trace back to that list — **not** interchangeable clipart (random apparel, unrelated lifestyle objects, vague “business” silhouettes unless the idea demands them).
+2. **Could this ship on another site unchanged?** If yes, redesign until **no** — different silhouette story, palette accent, or composition so the asset “only fits” this narrative.
+3. **One tie-in sentence per asset** — In specs or `docs/research/REBRAND.md`, each image/SVG scene gets **Idea tie-in:** `<why this belongs to this product>`.
+4. **Prefer authored scenes** — Custom SVG narratives (several shapes telling one moment), optional pixel mascot **on-brand** for the category, or composed raster under `public/images/marketing/` when illustration needs texture. Lucide-only piles and neutral blobs are **last resort**, not default.
+5. **Distinct accents** — Pick accent hues/shapes suggested by the idea’s personality (precise studio vs warm companion vs rugged utility); avoid default gray-only SaaS anonymity unless the brief is explicitly brutalist.
+
+### Imagery density (every fold earns a visual idea)
+
+- **Hero** — Never headline-only on white: add at least two of — soft gradient mesh / radial spotlight, **idea-specific** SVG cluster (metaphors from the list above), notebook/grid lines when the idea is docs, waveform device frame when the idea is capture, masked **purpose-built** raster in `public/images/marketing/`, geometric frame echoing **this** logo shape.
+- **Between sections** — Optional dividers whose pattern/stroke **echoes the product motif** (not a stock wave).
+- **Feature rows** — Each card illustration is a **different** moment in the same visual language (shared stroke weight, accent, or grid) — all still **idea-native** (e.g. capture → transcript lines; workspace → shared cursors; publish → export channels). No unrelated filler.
+- **Social proof** — Logo strip may use grayscale marks; add **slow infinite marquee** or gentle opacity drift — motion sells “living product.” Name recognizable companies where appropriate; use lawful logo marks under `public/images/logos/` (or generate **original** tiles — never counterfeit trademarks). Full workflow: **`.claude/skills/marketing-social-proof-motion/SKILL.md`** · Cursor **`/marketing-social-proof-motion`**.
+
+### Motion choreography *(ship several layers; respect `prefers-reduced-motion`)*
+
+Default minimum bar for authored landings — implement with **`framer-motion`** unless matching CSS-only parity:
+
+| Tier | What users feel | Typical implementation |
+|------|-----------------|-------------------------|
+| **A — Page load** | Hero headline, subcopy, CTAs, and hero art **stagger in** (opacity + `y`, or blur-in for type) | Parent `variants` + `staggerChildren`; durations 0.35–0.7s, ease `[0.22, 1, 0.36, 1]` or springs |
+| **B — Scroll** | Sections **ease up / fade** on first viewport entry; grids **stagger cards** | `whileInView` + `viewport.once`; `margin: "-80px"` tweak so reveals feel early |
+| **C — Looping ambient** | Logo strip marquee; gradient drift; subtle SVG stroke dashoffset loop; “thinking…” **typing caret** | CSS `@keyframes` or Framer `animate` repeat; keep amplitude **low** |
+| **D — Interaction** | Buttons scale/shine on hover; cards **lift** (`translateY`, shadow); nav **backdrop blur / height** past threshold | `whileHover`, `whileTap`; scroll listener or Framer scroll hooks for nav |
+| **E — Decorative depth** | Pointer parallax on hero cluster (2–4 layers at different strengths) OR scroll-linked `useTransform` | Small rotate/translate ranges (≤ 8px / ≤ 2deg) |
+
+Always gate looping motion: **`useReducedMotion()`** from Framer Motion — swap loops for static frames and shorten entrances.
+
+### Brandability checklist *(distinctive, not generic SaaS gray)*
+
+- **Motif thread** — One recurring visual hook (pen stroke, folded page corner, hub spark, pixel creature) reused in hero, favicon, OG image sketch, and one feature illustration.
+- **Accent discipline** — Define **primary + secondary accent** in `:root` (even if mostly monochrome). Use accents on CTAs, SVG highlights, focus rings — not rainbow scatter.
+- **Wordmark lockup** — SVG glyph + tracked type; provide **icon-only** variant for favicon / meta.
+- **OG & SEO assets** — Generate **`public/seo/og.png`** (or route og image) that includes motif + product name — not a bare screenshot.
+
+### Where artifacts live
+
+- **Raster/video** — `public/images/`, `public/videos/` (see `MEDIA_MANIFEST.md`).
+- **SVG React illustrations** — Prefer `src/components/marketing/art/` or co-located `*-scene.tsx` modules; export named components (`HeroBackdrop`, `FeatureCaptureIllustration`).
+- **Pixel art** — Same folder pattern; document palette in file header comment.
+
+### Spec requirement *(hand-off quality)*
+
+When writing `docs/research/components/*.spec.md`, add sections **Illustration** (**Idea tie-in** per asset, layers, SVG components, raster paths) and expand **Motion** with tier **A–E** coverage and reduced-motion fallback. Builders should not invent motion ad hoc — the spec states durations and triggers.
 
 ## Commands
 - `npm run dev` — Start dev server
@@ -42,7 +95,7 @@ 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`** — **Playwright**: stabilized **full-document** scrolling at **desktop + mobile**, merged **`computed-snapshot.json`** + **`MEDIA_MANIFEST.md`**, **full-page** screenshots under `docs/design-references/` (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`
@@ -50,6 +103,10 @@ Treat these as **first-class deliverables**, not polish at the end.
 ## When Browser MCP is down
 Prefer **Playwright** for repeatable extraction in-repo — do **not** rely on Chrome DevTools MCP alone.
 
+### Full landing coverage (agents + automation)
+
+Whether using MCP or Playwright, extraction must cover the **entire visible landing** (hero → footer): slow-scroll until lazy content settles, then **`fullPage`** screenshots — never treat “what fits in one viewport” as sufficient for inventory or specs.
+
 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/`.
@@ -64,6 +121,8 @@ Prefer **Playwright** for repeatable extraction in-repo — do **not** rely on C
 ## 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.
+- **Idea-specific imagery** — Marketing art (SVG, raster, OG) must be **tailored to `launchframe.config.json#idea`**: explicit metaphors, per-asset **Idea tie-in** notes, and **no interchangeable filler** that could belong to any generic SaaS.
+- **Production landing density** — For authored/minimal pages, deliberately add **idea-specific** illustration (not generic SaaS filler), **pixel-art accents** when they reinforce the metaphor, and **tiered motion (A–E)** per “Production polish” above; static monochrome layouts are incomplete unless the user explicitly wants extreme minimalism.
 - **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 +135,7 @@ src/
   app/              # Next.js routes
   components/       # React components
     ui/             # shadcn/ui primitives
+    marketing/      # Landing sections + authored SVG scenes (`art/` recommended)
     icons.tsx       # Extracted SVG icons as React components
   lib/
     utils.ts        # cn() utility (shadcn)

package/template/docs/research/INSPECTION_GUIDE.md

@@ -23,6 +23,20 @@ If automation hits a bot wall, **do not pretend extraction succeeded** — captu
 - [ ] **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.
 
+### 3. Idea-tailored illustration & motifs *(production landings)*
+
+When the reference page is **sparse** (mostly type + gray boxes) or after a **rebrand** the UI still reads generic, illustration is required — and it must be **unique to the SaaS idea** (`launchframe.config.json#idea`), not reusable wallpaper.
+
+- [ ] **Metaphor list** — 3–6 nouns/verbs derived from `idea`; every bespoke asset maps to ≥ one entry
+- [ ] **Uniqueness check** — If the scene works unchanged for another product category, revise
+- [ ] **Inline SVG** — hero shapes, dividers, card mini-scenes; note `viewBox`, **`currentColor`** vs fixed fills, **Idea tie-in** sentence per asset
+- [ ] **Pixel art / sprites** — only when character reinforces the metaphor; palette hex table; `imageRendering` / grid discipline
+- [ ] **Motif thread** — recurring element echoing hero + OG + favicon **for this product**, not a random geometric pattern
+- [ ] **Accent tokens** — primary/secondary roles aligned with idea personality (extract from reference or define in `:root`)
+- [ ] **Motion tiers A–E** — document with **reduced-motion** fallback (`prefers-reduced-motion`)
+
+See **`AGENTS.md` → Production polish for marketing landings** for tier definitions and folders (`src/components/marketing/art/`, `public/images/marketing/`).
+
 ---
 
 ## How to Reverse-Engineer Any Website
@@ -32,6 +46,7 @@ This guide outlines what to capture when inspecting a target website via Chrome
 ## Phase 1: Visual Audit
 
 ### Screenshots to Capture
+- [ ] **Single-page landing — full scroll depth** — slow-scroll until lazy sections stabilize; **`fullPage`** / stitched capture so footer and below-fold bands are included (not viewport-only hero grabs)
 - [ ] Every distinct page — desktop, tablet, mobile
 - [ ] Dark mode variants (if applicable)
 - [ ] Light mode variants (if applicable)