launchframe 0.1.13 → 0.2.0

package/README.md

@@ -1,10 +1,10 @@
-# Launchframe
+# 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.
+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 Launchframe output works with any agent that can read Markdown and TypeScript.
+**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`**, then drive the same **spec → parallel builders → merge → QA** rhythm popularized by [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template). In Cursor, use the **Clone Website** command (`.cursor/commands/clone-website.md`), which matches that template’s pipeline with Launchframe handling automated recon.
+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)
 
@@ -29,50 +29,57 @@ Pass multiple URLs for a combined token synthesis (see CLI reference below). You
 
 | Agent | Status |
 | ----- | ------ |
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Recommended |
-| [Cursor](https://cursor.com/) | Supported — `.cursor/commands/clone-website.md` |
+| [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/`
+- **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)
 
-Launchframe mirrors that template’s **phases and artifact roles**, not its single-repo layout:
+Landingfram mirrors that template’s **phases and artifact roles**, not its single-repo layout:
 
-| Aspect | What they do | What Launchframe does (same intent) |
+| 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 ≈ orchestration checklist) |
+| **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
 
-This repo combines **Launchframe automated extraction** with the **AI Website Cloner**-style agent workflow:
+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. **Automated recon** — headless Chromium capture, computed-style aggregation, reference dump (`dom-structure.json`, `visible-text.*`, `media.json`), design-reference PNGs and probes under `docs/design-references/`, and starter topology/spec files under `docs/research/`.
-2. **Foundation** — synthesized shadcn-compatible theme files at the run root; merge into your Next app.
-3. **Component specs** — per-section `.spec.md` files (extend Launchframe’s emitted stubs) with behaviors, states, and assets.
-4. **Parallel build** — agents in worktrees/branches per section or subcomponent.
-5. **Assembly & QA** — wire the target route (from mirror structure), visual diff against references.
+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 should receive **inline** spec content, not “go read the repo.” Authority order for structure is in **`FOR_AI.md`** and **`AGENTS.md`**.
+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
 
@@ -84,7 +91,7 @@ Each builder should receive **inline** spec content, not “go read the repo.”
 
 - **Impersonation or phishing**
 - **Passing off** another brand’s identity, trademarks, or licensed media
-- **Violating robots.txt or site terms** — Launchframe checks robots by default (`--no-robots` is discouraged)
+- **Violating robots.txt or site terms** — Landingfram checks robots by default (`--no-robots` is discouraged)
 
 ## Output layout
 
@@ -158,12 +165,13 @@ npm run sync:agents      # Regenerate Copilot / Cline / Continue / Amazon Q stub
 - **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 from one file
+### Updating agent copies (parity with upstream template)
 
-| What | Source of truth | Sync command |
-| ---- | ----------------- | ------------ |
+| What | Source of truth (this repo) | Sync / notes |
+| ---- | --------------------------- | ------------ |
 | Project instructions | `AGENTS.md` | `npm run sync:agents` |
-| Cursor multi-phase pipeline | `.cursor/commands/clone-website.md` | (edit in repo — no codegen) |
+| `/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
 

package/bin/launchframe.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * CLI entry for `npx launchframe` / `npm exec launchframe`.
- * 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
+ * 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.
  */
 
@@ -25,7 +25,7 @@ try {
   tsxCli = join(dirname(tsxPkg), "dist", "cli.mjs");
 } catch {
   console.error(
-    "launchframe: could not resolve the `tsx` runtime. Re-install: npm install -g launchframe",
+    "launchframe: could not resolve the `tsx` runtime. Re-install with: npm install -g launchframe",
   );
   process.exit(1);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "launchframe",
-  "version": "0.1.13",
-  "description": "Point Launchframe at SaaS sites you admire and get back a drop-in shadcn/ui design system (tokens, Tailwind theme, CSS variables, AI handoff) you can build your own UI on top of.",
+  "version": "0.2.0",
+  "description": "Launchframe CLI: point it at SaaS sites you admire and get a drop-in shadcn/ui design system (tokens, Tailwind theme, CSS variables, AI handoff) plus ai-website-cloner-style recon (reference DOM, mirror, design references, research stubs). Primary install: npx launchframe@latest.",
   "license": "MIT",
   "author": "Evan Gruhlkey",
   "homepage": "https://github.com/evangruhlkey/launchframe#readme",
@@ -14,6 +14,7 @@
   },
   "keywords": [
     "launchframe",
+    "landingfram",
     "shadcn",
     "shadcn-ui",
     "tailwind",
@@ -26,6 +27,7 @@
     "cli"
   ],
   "bin": {
+    "landingfram": "bin/launchframe.mjs",
     "launchframe": "bin/launchframe.mjs"
   },
   "files": [

package/packages/extract/automated-clone-pass.ts

@@ -209,7 +209,7 @@ async function captureInteractionHints(page: Page): Promise<unknown> {
 function emitDesignReferencesReadme(host: string, slug: string): string {
   return `# Design references — ${host}
 
-Automated captures (Launchframe \`automated-clone-pass\`), analogous to **ai-website-cloner-template** \`docs/design-references/\`.
+Automated captures (Landingfram \`automated-clone-pass\`), analogous to **ai-website-cloner-template** \`docs/design-references/\`.
 
 | Artifact | Purpose |
 | -------- | ------- |

package/packages/extract/cloner-research-emit.ts

@@ -1,7 +1,7 @@
 /**
  * Emits research artifacts under each extract run, aligned in layout and intent
  * with the AI Website Cloner template (topology, behaviors bible, per-section
- * specs). Values are derived from Launchframe's automated crawl where available;
+ * specs). Values are derived from Landingfram's automated crawl where available;
  * interactive sweeps still require manual Browser MCP work for full fidelity.
  */
 
@@ -123,7 +123,7 @@ function emitTopology(url: string, host: string, layout: SiteLayout | undefined)
     ``,
     `- **URL:** ${url}`,
     `- **Host:** ${host}`,
-    `- **Generated by:** Launchframe automated crawl (primary viewport + optional responsive passes under \`docs/design-references/\`)`,
+    `- **Generated by:** Landingfram automated crawl (primary viewport + optional responsive passes under \`docs/design-references/\`)`,
     ``,
     `## Section order (top → bottom)`,
     ``,
@@ -174,7 +174,7 @@ function emitBehaviors(
 - **URL:** ${url}
 - **Capture viewport:** ${vpLine}
 
-## What Launchframe captured automatically
+## What Landingfram captured automatically
 
 - Single desktop pass in headless Chromium with **reduced motion** forced for deterministic screenshots.
 - **Automated multi-viewport + scroll sweep** PNGs under \`docs/design-references/${hostSlug(host)}/\` (desktop/tablet/mobile + scroll frames).
@@ -203,7 +203,7 @@ Document findings below as you discover them.
 
 ## Operator SaaS idea
 
-${run.saasIdea?.trim() || "_Pass `--idea` or a second positional string when invoking launchframe._"}
+${run.saasIdea?.trim() || "_Pass `--idea` or a second positional string when invoking landingfram._"}
 
 When rebuilding UI, preserve **interaction models** from this table (once filled); rewrite **copy** to match the SaaS idea without impersonating the reference brand.
 `;

package/packages/extract/emit.ts

@@ -44,7 +44,7 @@ function write(dir: string, file: string, contents: string): string {
 
 function emitTailwindConfig(system: DesignSystem): string {
   return `/**
- * Tailwind theme extracted by launchframe.
+ * Tailwind theme extracted by landingfram.
  * Run id: ${system.runId}
  *
  * Sources (inspirational only, no source code or assets reused):
@@ -126,7 +126,7 @@ function heightFor(step: string, system: DesignSystem): string {
 
 function emitGlobalsCss(system: DesignSystem): string {
   return `/**
- * Drop-in CSS variables produced by launchframe.
+ * Drop-in CSS variables produced by landingfram.
  * Compatible with shadcn/ui's --background / --foreground / etc. tokens.
  */
 

package/packages/extract/extract.ts

@@ -46,11 +46,11 @@ import type { ExtractionRun, RawTokens, SiteCapture, SiteLayout } from "./types.
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-/** Writes under the user's cwd so `npx launchframe` from any folder works. */
+/** Writes under the user's cwd so `npx launchframe` / `npx landingfram` from any folder works. */
 const DEFAULT_OUTPUT_ROOT = join(process.cwd(), "output");
 
 const USER_AGENT =
-  "launchframe/0.1 (+https://github.com/evangruhlkey/launchframe; design-token research; respects robots.txt)";
+  "landingfram/0.1 (+https://github.com/evangruhlkey/launchframe; design-token research; respects robots.txt)";
 
 interface CliArgs {
   urls: string[];
@@ -59,7 +59,7 @@ interface CliArgs {
   respectRobots: boolean;
   rateLimitPerMinute: number;
   runName?: string;
-  /** SaaS product narrative from `--idea`, a positional string, or LAUNCHFRAME_SAAS_IDEA. */
+  /** SaaS product narrative from `--idea`, a positional string, or LANDINGFRAM_SAAS_IDEA / LAUNCHFRAME_SAAS_IDEA. */
   saasIdea?: string;
   /** When true, skip HTTP downloads from reference/media.json */
   skipAssetDownload: boolean;
@@ -145,7 +145,8 @@ function parseArgs(argv: string[]): CliArgs {
     args.saasIdea = positional[0];
   }
 
-  const envIdea = process.env.LAUNCHFRAME_SAAS_IDEA?.trim();
+  const envIdea =
+    process.env.LANDINGFRAM_SAAS_IDEA?.trim() || process.env.LAUNCHFRAME_SAAS_IDEA?.trim();
   if (envIdea && !args.saasIdea) {
     args.saasIdea = envIdea;
   }