launchframe 0.3.1 → 0.4.1

package/README.md

@@ -1,56 +1,174 @@
-# Launchframe
+# Launchframe (AI Website Cloner)
 
-> **Scaffold a SaaS-ready Next.js codebase from any URL — in one command.**
+<a href="https://github.com/JCodesMore/ai-website-cloner-template/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a> <a href="https://github.com/JCodesMore/ai-website-cloner-template/stargazers"><img src="https://img.shields.io/github/stars/JCodesMore/ai-website-cloner-template?style=flat" alt="Stars" /></a> <a href="https://discord.gg/hrTSX5yTpB"><img src="https://img.shields.io/discord/1400896964597383279?label=discord" alt="Discord" /></a>
 
-```bash
-npx launchframe@latest <url> "<saas idea>"
-```
+Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy** plus **your SaaS idea** that drives landing-page positioning. Use **`npx launchframe@latest`** or the slash command **`/launchframe <url> "your idea"`** to scaffold, then run **`/clone-website`** so your AI agent reverse-engineers the reference layout while preserving your messaging inputs (`launchframe.context.json`, `docs/research/LAUNCHFRAME.md`, `src/lib/launchframe-config.ts`).
 
-Launchframe drops an [AI-cloner template](https://github.com/JCodesMore/ai-website-cloner-template) into **your current folder (project root)** by default — so **`.cursor`**, **`.claude`**, and the rest of the dotfolders sit where your editor expects them when you open that folder. It **runs `npm install` for you**. Then tell your AI **Build it** (same as `/clone-website`).
+**Recommended: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with Opus 4.7 for best results** — but works with a variety of AI coding agents.
 
-## Why Launchframe
+## Demo
 
-Cloning a website is a solved problem if you have a great AI agent and a great template. What's missing is **a one-command entrypoint that wires those together with your specific intent**.
+[![Watch the demo](docs/design-references/comparison.png)](https://youtu.be/O669pVZ_qr0)
 
-- Pick a real, beautiful, production-tested landing page
-- Pick the SaaS you want to ship
-- Get a buildable Next.js codebase in seconds, ready for your AI agent to clone + rebrand
+> Click the image above to watch the full demo on YouTube.
 
 ## Quick Start
 
-From an **empty** project folder (or after `git init` only):
+### AI agents (slash command)
+
+In Cursor, Claude Code, Continue, and other synced tools:
+
+```text
+/launchframe https://example.com "Your SaaS idea in plain language"
+```
+
+The agent runs **`npx launchframe@latest`** with those arguments (see `.cursor/commands/launchframe.md`). Output must be **outside** the template package directory when developing from a clone of this repo — use `--dir ../my-app` or an absolute path.
+
+### CLI (same as slash command)
+
+From an empty folder (or anywhere you want the project folder created):
 
 ```bash
-mkdir my-saas && cd my-saas
-npx launchframe@latest https://linear.app "AI-powered customer feedback platform"
+npx launchframe@latest https://example.com "Your SaaS idea in plain language"
 ```
 
-Then open **this folder** in [Cursor](https://cursor.com/) and chat: **Build it.**
+Scaffolding copies the full template at the repository root — including **hidden agent config** (for example `.cursor/`, `.claude/`, `.github/`, `.amazonq/`, `.augment/`, and other dotfiles) so tools see the same rules and commands as this template.
+
+Optional flags:
+
+- `--dir my-app` / `-o my-app` — output folder name (default: `<hostname>-launchframe`)
+- `--skip-install` — scaffold files only; run `npm install` yourself
+
+Then:
+
+```bash
+cd <your-project-folder>
+npm run dev
+```
+
+Open your AI agent and run `/clone-website <same-reference-url>` so it rebuilds the reference site into components while aligning hero copy with your SaaS idea files above.
+
+### Git template (advanced)
+
+1. Clone this repository and `npm install`
+2. Replace `src/lib/launchframe-config.ts` or run `npx launchframe@latest ...` into a fresh folder
+3. Run `/clone-website <target-url>` from your agent
+
+> Using a different agent? Open `AGENTS.md` for project instructions — most agents pick it up automatically.
+
+## Supported Platforms
+
+| Agent                                                         | Status                     |
+| ------------------------------------------------------------- | -------------------------- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | **Recommended** — Opus 4.7 |
+| [Codex CLI](https://github.com/openai/codex)                  | Supported                  |
+| [OpenCode](https://opencode.ai/)                              | Supported                  |
+| [GitHub Copilot](https://github.com/features/copilot)         | Supported                  |
+| [Cursor](https://cursor.com/)                                 | Supported                  |
+| [Windsurf](https://codeium.com/windsurf)                      | Supported                  |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli)     | Supported                  |
+| [Cline](https://github.com/cline/cline)                       | Supported                  |
+| [Roo Code](https://github.com/RooCodeInc/Roo-Code)            | Supported                  |
+| [Continue](https://continue.dev/)                             | Supported                  |
+| [Amazon Q](https://aws.amazon.com/q/developer/)               | Supported                  |
+| [Augment Code](https://www.augmentcode.com/)                  | Supported                  |
+| [Aider](https://aider.chat/)                                  | Supported                  |
+
+## Prerequisites
 
-Files land in the **current directory** so workspace rules apply. Prefer a subfolder? Use `--dir launchframe-app`.
+- [Node.js](https://nodejs.org/) 24+
+- An AI coding agent (see [Supported Platforms](#supported-platforms))
 
-## CLI Reference
+## Tech Stack
+
+- **Next.js 16** — App Router, React 19, TypeScript strict
+- **shadcn/ui** — Radix primitives + Tailwind CSS v4
+- **Tailwind CSS v4** — oklch design tokens
+- **Lucide React** — default icons (replaced by extracted SVGs during cloning)
+
+## How It Works
+
+The `/clone-website` skill runs a multi-phase pipeline:
+
+1. **Reconnaissance** — screenshots, design token extraction, interaction sweep (scroll, click, hover, responsive)
+2. **Foundation** — updates fonts, colors, globals, downloads all assets
+3. **Component Specs** — writes detailed spec files (`docs/research/components/`) with exact computed CSS values, states, behaviors, and content
+4. **Parallel Build** — dispatches builder agents in git worktrees, one per section/component
+5. **Assembly & QA** — merges worktrees, wires up the page, runs visual diff against the original
+
+Each builder agent receives the full component specification inline — exact `getComputedStyle()` values, interaction models, multi-state content, responsive breakpoints, and asset paths. No guessing.
+
+## Use Cases
+
+- **Platform migration** — rebuild a site you own from WordPress/Webflow/Squarespace into a modern Next.js codebase
+- **Lost source code** — your site is live but the repo is gone, the developer left, or the stack is legacy. Get the code back in a modern format
+- **Learning** — deconstruct how production sites achieve specific layouts, animations, and responsive behavior by working with real code
+
+## Not Intended For
+
+- **Phishing or impersonation** — this project must not be used for deceptive purposes, impersonation, or any activity that breaks the law.
+- **Passing off someone's design as your own** — logos, brand assets, and original copy belong to their owners.
+- **Violating terms of service** — some sites explicitly prohibit scraping or reproduction. Check first.
+
+## Project Structure
 
 ```
-npx launchframe@latest <url> "<saas idea>" [options]
-
-Options:
-  --dir <path>   Output folder (default: .)
-  --force        Merge into a non-empty directory (use with care)
-  --skip-install Skip npm install (CI / debugging)
-  --help, -h     Help
-  --version, -v  Version
+src/
+  app/              # Next.js routes
+  components/       # React components
+    ui/             # shadcn/ui primitives
+    icons.tsx       # Extracted SVG icons
+  lib/utils.ts      # cn() utility
+  types/            # TypeScript interfaces
+  hooks/            # Custom React hooks
+public/
+  images/           # Downloaded images from target
+  videos/           # Downloaded videos from target
+  seo/              # Favicons, OG images
+docs/
+  research/         # Extraction output & component specs
+  design-references/ # Screenshots
+scripts/
+  sync-agent-rules.sh  # Regenerate agent instruction files
+  sync-skills.mjs      # Regenerate /clone-website for all platforms
+AGENTS.md           # Agent instructions (single source of truth)
+CLAUDE.md           # Claude Code config (imports AGENTS.md)
+GEMINI.md           # Gemini CLI config (imports AGENTS.md)
 ```
 
-## Monorepo (this repository)
+## Commands
+
+```bash
+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
+```
+
+### If using docker
+
+```bash
+docker compose up app --build # build and run the app
+docker compose up dev --build # run the app in dev mode on port 3001
+```
+
+## Updating for Other Platforms
+
+Two source-of-truth files power all platform support. Edit the source, then run the sync script:
+
+| What                   | Source of truth                         | Sync command                       |
+| ---------------------- | --------------------------------------- | ---------------------------------- |
+| Project instructions   | `AGENTS.md`                             | `bash scripts/sync-agent-rules.sh` |
+| `/clone-website` skill | `.claude/skills/clone-website/SKILL.md` | `node scripts/sync-skills.mjs`     |
+
+Each script regenerates the platform-specific copies automatically. Agents that read the source files natively need no regeneration.
 
-- **`template/`** — Next.js app + agent skills (what `npx launchframe` copies).
-- **`bin/launchframe.mjs`** — CLI entrypoint.
 
-To work on the app: `cd template && npm install && npm run dev`.
+## Star History
 
-To verify the npm tarball before publish: `npm pack` at the repo root — the package must include `bin/` and `template/`.
+[![Star History Chart](https://api.star-history.com/svg?repos=JCodesMore/ai-website-cloner-template&type=Date)](https://star-history.com/#JCodesMore/ai-website-cloner-template&Date)
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT