launchframe 0.2.0 → 0.2.2

package/README.md

@@ -1,183 +1,144 @@
-# Landingfram
-
-A reusable workflow for reverse-engineering live marketing sites into a **shadcn-style token theme**, **reference dumps** (DOM, copy index, media index), and a **layout-mirror** React scaffold — optimized for AI coding agents (same orchestration model as [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)).
-
-**Recommended:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or **Cursor** for multi-phase builds — but Landingfram output works with any agent that can read Markdown and TypeScript.
-
-Point the CLI at a URL, run **`npx launchframe@latest <url> "<SaaS idea>"`**, then drive the same **spec → parallel builders → merge → QA** rhythm. In Cursor, use the **Clone Website** command (`.cursor/commands/clone-website.md`); in Claude Code / Codex, use the **`clone-website`** skill. Those workflows merge [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template) discipline with **automated** Playwright recon. The same npm package also exposes a **`landingfram`** bin shim for older scripts.
-
-## Quick start (any folder)
-
-**One time per machine** (Chromium for Playwright):
-
-```bash
-npx playwright install chromium
-```
-
-**Every extraction** (writes to **`./output/<runId>/`** in the current working directory):
-
-```bash
-cd path/to/your-app-or-empty-folder
-npx launchframe@latest https://example.com "Your SaaS idea"
-```
-
-Pass multiple URLs for a combined token synthesis (see CLI reference below). Your **SaaS idea** string is stored in `run.json`, `FOR_AI.md`, and `docs/research/`.
-
-**Then hand output to your agent:** attach **`FOR_AI.md`**, **`reference/<host>/`** (especially **`dom-structure.json`**), **`mirror/<host>/`**, **`tokens.json`**, and **`docs/design-references/<host-slug>/`**. For the full builder orchestration checklist, open **`AGENTS.md`** or run the **Clone Website** Cursor command.
-
-## Supported platforms
-
-| Agent | Status |
-| ----- | ------ |
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Recommended — align with upstream template |
-| [Codex CLI](https://github.com/openai/codex) | Supported — `.codex/skills/clone-website/` |
-| [OpenCode](https://opencode.ai/) | Supported |
-| [GitHub Copilot](https://github.com/features/copilot) | Supported — `AGENTS.md` → `npm run sync:agents` |
-| [Cursor](https://cursor.com/) | Supported — `.cursor/commands/clone-website.md` |
-| [Windsurf](https://codeium.com/windsurf) | Supported |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported (`GEMINI.md`) |
-| [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 |
-| … | Any agent that reads `AGENTS.md` |
-
-## Prerequisites
-
-- [Node.js](https://nodejs.org/) **20+**
-- Chromium via Playwright (`npx playwright install chromium`)
-- **From a git clone of this monorepo:** initialize the upstream template submodule with `git submodule update --init --recursive` (or clone with `git clone --recurse-submodules …`) so `vendor/ai-website-cloner-template` is available for reference.
-
-## Tech stack
-
-- **Extract:** Node.js, Playwright, TypeScript
-- **Published CLI:** `npx launchframe` → `packages/extract/` (`landingfram` is a bin alias on install)
-- **Studio (optional):** Next.js App Router in `apps/studio/` (**Next.js 16**, **React 19**, Tailwind CSS, **Lucide** via `@framework/blocks` / direct imports — aligned with [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template); studio Tailwind is v3 today while their README cites **v4**; emitted run artifacts remain drop-in CSS/token bundles.)
-- **Mirror output:** React, Framer Motion, Phosphor (generated `page.tsx`)
-- **Tokens:** `tailwind.config.ts`, `globals.css`, `tokens.json`, `REPORT.md`
-
-## Parity with [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
-
-Landingfram mirrors that template’s **phases and artifact roles**, not its single-repo layout:
-
-| Aspect | What they do | What Landingfram does (same intent) |
-| -------- | ------------------ | ------------------------------------- |
-| **Phase 1 recon** | `/clone-website` drives screenshots, tokens, interaction sweep | **`npx launchframe`** performs automated recon (Playwright) into a run folder; optional Browser MCP passes match their sweep discipline (**Clone Website** in Cursor / **`clone-website`** skill elsewhere ≈ orchestration checklist) |
-| **Repo shape** | One Next.js app (`src/app`, `components`, …) | **Monorepo:** CLI (`packages/extract`) + optional **`apps/studio`** + **`packages/blocks`**; published CLI ships separately |
-| **Where artifacts live** | `docs/research/`, `docs/design-references/`, `public/` | Same tree **inside** `./output/<runId>/` (gitignored by default). To match their repo layout, run with **`--out path/to/your-next-app/extraction-<slug>`** or merge **`docs/`** + **`downloaded_assets/`** into your app’s **`docs/`** and **`public/images`** (and **`public/videos`**, **`public/seo`**) when integrating |
-| **Stack** | Next 16, React 19, Tailwind v4, Lucide | **Next 16 + React 19 + Lucide** in studio/blocks; Tailwind **v3** in-studio until upgraded to v4 |
-
-## How it works
-
-Same multi-phase pipeline as [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template) (`vendor/ai-website-cloner-template` in this repo):
-
-1. **Reconnaissance** — screenshots, design token extraction, interaction sweep (scroll, click, hover, responsive). **Launchfram:** run **`npx launchframe@latest <url> "<SaaS idea>"`** first for an automated baseline into **`./output/<runId>/`**; agents still use browser MCP for the mandatory sweep where needed (see **`.cursor/commands/clone-website.md`**).
-2. **Foundation** — updates fonts, colors, globals, downloads all assets (merge emitted `globals.css` / `tailwind.config.ts` / `tokens.json` from the run when present).
-3. **Component specs** — 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. Authority order: **`FOR_AI.md`** and **`AGENTS.md`**.
-
-## Use cases
-
-- Seeding a **design system** from sites you’re allowed to analyze
-- **Layout research** with a typed mirror and DOM reference
-- **Rebuilding** properties you own when only the public site remains
-
-## Not intended for
-
-- **Impersonation or phishing**
-- **Passing off** another brand’s identity, trademarks, or licensed media
-- **Violating robots.txt or site terms** — Landingfram checks robots by default (`--no-robots` is discouraged)
-
-## Output layout
-
-```txt
-output/<runId>/
-├── FOR_AI.md
-├── tokens.json
-├── tailwind.config.ts
-├── globals.css
-├── theme-preview.tsx
-├── REPORT.md
-├── run.json
-├── screenshots/
-├── raw/
-├── reference/
-│   └── <host>/
-│       ├── dom-structure.json
-│       ├── page.html
-│       ├── visible-text.txt / .json
-│       ├── media.json
-│       └── FOR_AI_REFERENCE.md
-├── mirror/
-│   └── <host>/
-│       ├── page.tsx
-│       └── MIRROR_NOTES.md
-├── docs/
-│   ├── design-references/<host-slug>/   # PNGs, probes, hints
-│   └── research/<host-slug>/             # PAGE_TOPOLOGY, BEHAVIORS, components/*.spec.md
-└── downloaded_assets/<host-slug>/        # when enabled
-```
-
-## CLI reference
-
-```bash
-npx launchframe@latest <url> [<url> ...] ["Your SaaS idea"] [options]
-```
-
-| Flag | Default | Notes |
-| ---- | ------- | ----- |
-| `--out <dir>` | `./output/<runId>` | Run directory |
-| `--name <slug>` | _(unset)_ | Appends slug to run id |
-| `--no-robots` | off | Skip robots.txt check |
-| `--rate <n>` | `15` | Per-domain requests per minute |
-| `--width <px>` | `1440` | Viewport width |
-| `--height <px>` | `900` | Viewport height |
-
-```bash
-npx launchframe@latest https://example.com "AI billing copilot" --name acme
-```
-
-## Run inside this repo (contributors)
-
-```bash
-git clone https://github.com/evangruhlkey/launchframe
-cd launchframe
-npm install
-npx playwright install chromium
-npm run extract -- https://example.com "Your SaaS idea"
-```
-
-```bash
-npm run studio           # Next.js studio
-npm run studio:build     # Production build
-npm run typecheck
-npm run sync:agents      # Regenerate Copilot / Cline / Continue / Amazon Q stubs from AGENTS.md
-```
-
-### AI agents in this repo
-
-- **`AGENTS.md`** is the **single source of truth** for agent instructions; **`docs/research/INSPECTION_GUIDE.md`** is inlined when you run **`npm run sync:agents`**.
-- **Cursor:** `.cursor/rules/project.mdc` points at `AGENTS.md`; use **Clone Website** for the full cloner-template-style checklist.
-- Edit **`AGENTS.md`**, then run **`npm run sync:agents`**.
-
-### Updating agent copies (parity with upstream template)
-
-| What | Source of truth (this repo) | Sync / notes |
-| ---- | --------------------------- | ------------ |
-| Project instructions | `AGENTS.md` | `npm run sync:agents` |
-| `/clone-website` skill text | `vendor/ai-website-cloner-template/.claude/skills/clone-website/SKILL.md` | Copy into `.claude/`, `.codex/`, `.github/skills/`; re-apply **Pre-Flight step 0** (Launchfram). Cursor command: `vendor/.../.cursor/commands/clone-website.md` → `.cursor/commands/` (same step 0). |
-| Inspection checklist | `vendor/.../docs/research/INSPECTION_GUIDE.md` | Merged in `docs/research/INSPECTION_GUIDE.md` with a **Landingfram** mapping section. |
-
-## What this is not
-
-- **Not the origin site’s bundle** — output is synthesized tokens, reference artifacts, and a **slot-based mirror**, not a dump of proprietary components.
-- **Not legal clearance** — you are responsible for compliance; see **`FOR_AI.md`** and **`AGENTS.md`**.
-
-## License
-
-MIT. See [`LICENSE`](./LICENSE).
+# Launchframe
+
+> **Scaffold a SaaS-ready Next.js codebase from any URL — in one command.**
+
+```bash
+npx launchframe@latest <url> "<saas idea>"
+```
+
+Launchframe drops an [AI-cloner template](https://github.com/JCodesMore/ai-website-cloner-template) into your filesystem, pre-wired with the URL you want to clone and the SaaS you want to build. It **runs `npm install` for you**. Open the new folder in [Cursor](https://cursor.com/) (or any AI editor) and tell your AI **Build it** — they'll follow `launchframe.config.json` + `AGENTS.md` and run the full clone + rebrand pipeline (same as `/clone-website`).
+
+## Why Launchframe
+
+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**.
+
+- ✅ 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
+
+You spend your time on product, not on translating Figma boxes into Tailwind.
+
+## Quick Start
+
+```bash
+npx launchframe@latest https://linear.app "AI-powered customer feedback platform"
+```
+
+Then open **`launchframe-app`** in Cursor and chat: **Build it.**
+
+That's the whole loop: no manual `npm install`, no pasting the URL again — the CLI installs deps and writes `launchframe.config.json`. Cursor rules treat **Build it** as “run the full clone + rebrand workflow.”
+
+Optional: **`/clone-website`** in Cursor, or **`--skip-install`** if you only want the files (CI / debugging).
+
+```bash
+npx launchframe@latest https://linear.app "My idea" --skip-install
+```
+
+## What gets generated
+
+```
+launchframe-app/
+├─ START_HERE.md             ← "open Cursor, say Build it"
+├─ launchframe.config.json   ← url + saas idea (the directive)
+├─ AGENTS.md                 ← agent instructions (read by every supported agent)
+├─ .claude/                  ← Claude Code skill: /clone-website
+├─ .cursor/                  ← Cursor command: /clone-website
+├─ .codex/ .gemini/ .opencode/ .windsurf/ .github/ .augment/
+│  .continue/ .amazonq/      ← every other agent gets the same skill, format-adapted
+├─ src/                      ← Next.js 16 + shadcn/ui + Tailwind v4 scaffold
+├─ public/                   ← becomes populated by the cloner with real assets
+├─ docs/research/            ← extraction artifacts the cloner writes during the run
+└─ scripts/                  ← asset download + sync scripts
+```
+
+## CLI Reference
+
+```
+npx launchframe@latest <url> "<saas idea>" [options]
+
+Arguments:
+  <url>          URL of the site you want to clone (e.g. https://linear.app)
+  <saas idea>    One-line description of the SaaS you're building
+
+Options:
+  --dir <name>   Target directory (default: launchframe-app)
+  --force        Overwrite the target if it already exists
+  --skip-install Skip npm install (for CI / debugging only)
+  --help, -h     Show this message
+  --version, -v  Show the version
+```
+
+### Examples
+
+```bash
+npx launchframe@latest https://linear.app "AI-powered customer feedback platform"
+
+npx launchframe@latest https://vercel.com "DevOps platform for ML teams" --dir my-startup
+
+# Hostname-only — launchframe will prepend https://
+npx launchframe@latest stripe.com "B2B billing for AI agent companies"
+```
+
+## Supported AI Agents
+
+| Agent                                                         | Status                     |
+| ------------------------------------------------------------- | -------------------------- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | **Recommended** — Opus 4.7 |
+| [Codex CLI](https://github.com/openai/codex)                  | Supported                  |
+| [Cursor](https://cursor.com/)                                 | Supported                  |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli)     | Supported                  |
+| [GitHub Copilot](https://github.com/features/copilot)         | Supported                  |
+| [OpenCode](https://opencode.ai/)                              | Supported                  |
+| [Windsurf](https://codeium.com/windsurf)                      | Supported                  |
+| [Cline](https://github.com/cline/cline) / 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                  |
+
+Every supported agent receives the same `/clone-website` skill — it's auto-synced from a single source-of-truth file in the template.
+
+## How `/clone-website` Works
+
+A multi-phase pipeline runs inside your AI agent. Browser automation MCP (Chrome MCP / Playwright MCP / Browserbase MCP) is required.
+
+1. **Reconnaissance** — full-page screenshots at desktop + mobile, design-token extraction, mandatory scroll/click/hover/responsive sweep
+2. **Foundation** — updates fonts, colors, globals.css; downloads all assets; extracts SVG icons
+3. **Component Specs** — writes detailed `.spec.md` files for every section with exact `getComputedStyle()` values
+4. **Parallel Build** — dispatches builder agents in git worktrees, one per section/component
+5. **SaaS Rebrand Pass** — swaps product name, headlines, feature copy, CTAs, and brand marks to match `launchframe.config.json#idea`. Spacing, color, typography, animations stay 1:1
+6. **Assembly + Visual QA** — merges worktrees, wires `src/app/page.tsx`, runs side-by-side diff against the original
+
+Each builder agent gets the full component spec inline. No guessing.
+
+## Editing the Config Mid-Project
+
+`launchframe.config.json` is the contract between you and the skill. Change either field any time and re-invoke `/clone-website`:
+
+```json
+{
+  "url": "https://stripe.com",
+  "idea": "Usage-based billing for AI agent startups"
+}
+```
+
+## Built On
+
+- The amazing [`ai-website-cloner-template`](https://github.com/JCodesMore/ai-website-cloner-template) by [@JCodesMore](https://github.com/JCodesMore) — Launchframe vendors and extends this as its payload
+- [Next.js 16](https://nextjs.org/), [React 19](https://react.dev/), [shadcn/ui](https://ui.shadcn.com/), [Tailwind CSS v4](https://tailwindcss.com/)
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18+ to run the CLI
+- [Node.js](https://nodejs.org/) 24+ inside the scaffolded project (for Next.js 16)
+- An AI coding agent with browser automation MCP
+
+## Not Intended For
+
+- Phishing or impersonation
+- Passing off someone else's design as your own
+- Violating terms of service (some sites prohibit scraping or reproduction — check first)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/launchframe.mjs

@@ -1,46 +1,279 @@
 #!/usr/bin/env node
+// @ts-check
 /**
- * CLI entry for `npx launchframe@latest` (npm package name) and the `landingfram`
- * bin shim on install. Spawns the TypeScript extract pipeline with the same Node
- * that installed this package. Output defaults to `./output/<runId>/` in the
- * *current* working directory (where the user ran the command), not inside the
- * package install path.
+ * launchframe — scaffold an AI-cloner project pointed at any URL + SaaS idea.
+ *
+ * Usage:
+ *   npx launchframe@latest <url> "<saas idea>" [--dir <name>] [--force]
+ *
+ * Behavior:
+ *   1. Validates the URL and SaaS-idea string.
+ *   2. Copies the bundled `template/` payload (the ai-website-cloner-template
+ *      pre-configured for launchframe) into `./<name>` (default `launchframe-app`).
+ *   3. Writes `launchframe.config.json` into the new project so the bundled
+ *      `/clone-website` skill knows which URL to clone and how to re-skin it
+ *      for your SaaS idea.
+ *   4. Runs `npm install` in the new project (so the user does not have to).
+ *   5. Prints one line: open the folder in Cursor and tell the AI **Build it**.
  */
 
 import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const pkgRoot = join(__dirname, "..");
-const pkgJsonPath = join(pkgRoot, "package.json");
+const pkgRoot = resolve(__dirname, "..");
+const templateDir = join(pkgRoot, "template");
+const require = createRequire(import.meta.url);
+const pkgJson = require(join(pkgRoot, "package.json"));
 
-const require = createRequire(pkgJsonPath);
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+};
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (color, s) => (supportsColor ? COLORS[color] + s + COLORS.reset : s);
 
-let tsxCli;
-try {
-  const tsxPkg = require.resolve("tsx/package.json", { paths: [pkgRoot] });
-  tsxCli = join(dirname(tsxPkg), "dist", "cli.mjs");
-} catch {
-  console.error(
-    "launchframe: could not resolve the `tsx` runtime. Re-install with: npm install -g launchframe",
-  );
-  process.exit(1);
+function printHelp() {
+  console.log(`
+${c("bold", "launchframe")} ${c("dim", `v${pkgJson.version}`)}
+Scaffold an AI-cloner project pointed at any URL + SaaS idea.
+
+${c("bold", "Usage:")}
+  npx launchframe@latest <url> "<saas idea>" [options]
+
+${c("bold", "Arguments:")}
+  <url>          URL of the site you want to clone (e.g. https://linear.app)
+  <saas idea>    One-line description of the SaaS you're building
+                 (used to re-skin copy/branding after the visual clone)
+
+${c("bold", "Options:")}
+  --dir <name>   Target directory name (default: launchframe-app)
+  --force        Overwrite the target directory if it already exists
+  --skip-install Skip npm install after scaffold (faster for CI / debugging)
+  --help, -h     Show this message
+  --version, -v  Show the launchframe version
+
+${c("bold", "Example:")}
+  npx launchframe@latest https://linear.app "AI-powered customer feedback platform"
+  npx launchframe@latest https://vercel.com "DevOps platform for ML teams" --dir my-startup
+  npx launchframe@latest https://stripe.com "Billing for AI agents" --skip-install
+`);
+}
+
+function exitErr(msg, code = 1) {
+  console.error(c("red", `\nlaunchframe: ${msg}`));
+  console.error(c("dim", "Run `npx launchframe --help` for usage.\n"));
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const opts = {
+    dir: "launchframe-app",
+    force: false,
+    skipInstall: false,
+    help: false,
+    version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--version" || a === "-v") opts.version = true;
+    else if (a === "--force" || a === "-f") opts.force = true;
+    else if (a === "--skip-install") opts.skipInstall = true;
+    else if (a === "--dir" || a === "-d") {
+      const next = argv[++i];
+      if (!next || next.startsWith("-")) exitErr("`--dir` requires a value");
+      opts.dir = next;
+    } else if (a.startsWith("--dir=")) {
+      opts.dir = a.slice("--dir=".length);
+    } else if (a.startsWith("-")) {
+      exitErr(`unknown option: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, opts };
+}
+
+function normalizeUrl(raw) {
+  let candidate = raw.trim();
+  if (!/^https?:\/\//i.test(candidate)) candidate = `https://${candidate}`;
+  try {
+    const u = new URL(candidate);
+    if (!u.hostname || !u.hostname.includes(".")) throw new Error("missing hostname");
+    return u.toString();
+  } catch {
+    exitErr(`invalid URL: ${raw}`);
+  }
+}
+
+function isDirEmpty(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return true;
+  }
 }
 
-const extractScript = join(pkgRoot, "packages", "extract", "extract.ts");
+function rewritePackageJson(targetDir, projectName, url, idea) {
+  const pkgPath = join(targetDir, "package.json");
+  if (!existsSync(pkgPath)) return;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return;
+  }
+  pkg.name = projectName.toLowerCase().replace(/[^a-z0-9-_]/g, "-").slice(0, 64) || "launchframe-app";
+  pkg.version = "0.1.0";
+  pkg.private = true;
+  pkg.description = `Launchframe project — clone of ${url} reframed as: ${idea}`;
+  delete pkg.author;
+  delete pkg.homepage;
+  delete pkg.repository;
+  delete pkg.bugs;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+}
 
-const result = spawnSync(
-  process.execPath,
-  [tsxCli, extractScript, ...process.argv.slice(2)],
-  {
-    cwd: process.cwd(),
+function writeLaunchframeConfig(targetDir, url, idea) {
+  const cfg = {
+    $schema: "https://launchframe.dev/schema/launchframe.config.json",
+    url,
+    idea,
+    createdAt: new Date().toISOString(),
+    launchframeVersion: pkgJson.version,
+    notes: [
+      "The /clone-website skill reads this file at the start of every run.",
+      "After scaffold: open this folder in Cursor (or your AI editor) and say **Build it** — same workflow.",
+      "`url` is the visual source-of-truth (clone its layout, spacing, tokens, motion).",
+      "`idea` is the rebranding directive applied AFTER the pixel-perfect clone.",
+      "Edit either field and re-invoke the skill to re-run.",
+    ],
+  };
+  writeFileSync(
+    join(targetDir, "launchframe.config.json"),
+    JSON.stringify(cfg, null, 2) + "\n",
+    "utf8"
+  );
+}
+
+function runNpmInstall(targetDir) {
+  console.log(c("dim", "\nRunning npm install (this may take a minute)...\n"));
+  const result = spawnSync("npm", ["install", "--no-fund", "--no-audit"], {
+    cwd: targetDir,
     stdio: "inherit",
+    shell: true,
     env: process.env,
-    shell: false,
-  },
-);
+  });
+  if (result.status !== 0) {
+    console.error(
+      c("yellow", "\nlaunchframe: npm install exited with an error. ") +
+        c("dim", `Fix the issue and run \`npm install\` inside the project folder, or re-run with \`--force\`.\n`)
+    );
+    process.exit(result.status === null ? 1 : result.status);
+  }
+  console.log(c("green", "\n\u2713 npm install finished.\n"));
+}
 
-process.exit(result.status === null ? 1 : result.status);
+function nextSteps(projectDir, projectName, url, idea) {
+  const rel = `./${projectName}`;
+  console.log(`
+${c("green", "\u2713")} Done — ${c("bold", projectName)} is ready.
+
+  ${c("dim", "Target URL:")}  ${c("cyan", url)}
+  ${c("dim", "SaaS idea:")}   ${c("cyan", idea)}
+  ${c("dim", "Folder:")}      ${projectDir}
+
+${c("bold", "All you do next:")}
+  1. Open ${c("cyan", rel)} in ${c("bold", "Cursor")} ${c("dim", "(File \u2192 Open Folder)")}
+  2. In chat, say: ${c("bold", "Build it")}
+     ${c("dim", "Your AI reads launchframe.config.json + AGENTS.md and runs the full clone + rebrand workflow.")}
+     ${c("dim", "You can also type ") + c("cyan", "/clone-website") + c("dim", " if you prefer.")}
+
+${c("dim", "Other editors: same folder — say Build it, or run the /clone-website skill for your tool.")}
+${c("dim", "Edit launchframe.config.json anytime to change URL or SaaS idea.")}
+`);
+}
+
+function main() {
+  const { positional, opts } = parseArgs(process.argv.slice(2));
+  if (opts.help) return printHelp();
+  if (opts.version) return console.log(pkgJson.version);
+
+  if (positional.length < 2) {
+    if (positional.length === 0) {
+      console.error(c("red", "\nlaunchframe: missing <url> and <saas idea>"));
+    } else {
+      console.error(c("red", '\nlaunchframe: missing <saas idea> (wrap it in quotes: "...")'));
+    }
+    printHelp();
+    process.exit(1);
+  }
+  if (positional.length > 2) {
+    exitErr(
+      `too many positional arguments. Wrap your SaaS idea in quotes: ` +
+        `\`npx launchframe ${positional[0]} "${positional.slice(1).join(" ")}"\``
+    );
+  }
+
+  const url = normalizeUrl(positional[0]);
+  const idea = positional[1].trim();
+  if (!idea) exitErr("SaaS idea cannot be empty");
+
+  const dirName = opts.dir;
+  const targetDir = isAbsolute(dirName) ? dirName : resolve(process.cwd(), dirName);
+
+  if (existsSync(targetDir) && !isDirEmpty(targetDir) && !opts.force) {
+    exitErr(
+      `target directory \`${dirName}\` already exists and is not empty.\n` +
+        `Pass \`--force\` to overwrite, or use \`--dir <name>\` to choose a different folder.`
+    );
+  }
+
+  if (!existsSync(templateDir)) {
+    exitErr(
+      `bundled template not found at \`${templateDir}\`.\n` +
+        `This usually means the launchframe package was installed incompletely. ` +
+        `Try: \`npm install -g launchframe@latest\` or re-run \`npx launchframe@latest ...\`.`
+    );
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+
+  console.log(c("dim", `\nCopying template \u2192 ${targetDir} ...`));
+  cpSync(templateDir, targetDir, {
+    recursive: true,
+    force: opts.force,
+    filter: (src) => {
+      const lower = src.toLowerCase();
+      if (lower.endsWith(`${"\\"}node_modules`) || lower.endsWith("/node_modules")) return false;
+      if (lower.endsWith(`${"\\"}.next`) || lower.endsWith("/.next")) return false;
+      if (lower.endsWith("package-lock.json")) return false;
+      return true;
+    },
+  });
+
+  rewritePackageJson(targetDir, dirName, url, idea);
+  writeLaunchframeConfig(targetDir, url, idea);
+
+  if (!opts.skipInstall) runNpmInstall(targetDir);
+
+  nextSteps(targetDir, dirName, url, idea);
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(c("red", `\nlaunchframe: ${err?.message || err}\n`));
+  process.exit(1);
+}