agentic-web-developer 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# agentic-web-developer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An **agentic skill** that turns an AI coding agent into a complete web-development and website-selling system — distilled from Jack Roberts' two videos:
+
+1. **"How I build $10,000 AI Websites in 17 mins (Google AI Studio 2.0)"** — design DNA extraction (builder brief, scaffold, tokens), outlier competitor research (top-5 vs bottom-5), the conversion blueprint.
+2. **"How I Build & Sell $8,000 AI Websites (AntiGravity + Stitch)"** — the M.O.N.E.Y framework, lead generation, the config-driven cloning system, outreach emails, deployment and monetization.
+
+Plus a **novel-idea / product-launch mode** for websites not covered by the videos (SaaS, products, marketplaces).
+
+## What you get
+
+- **Stage-gated pipeline** (Intake → Niche → Research → Design → Build → QA → Animation handoff → Deploy → Sell) where the agent **asks for your input at every step** — it never runs ahead on assumptions.
+- **Design-tool agnostic** — Figma, Paper, Google Stitch, Google AI Studio, Framer or code-first. You supply the credentials/MCP for your tool of choice.
+- **Framework agnostic** — Next.js, React, Vue, Svelte, Astro, plain HTML, WordPress, GoHighLevel — you pick.
+- **All animation is delegated** to the [AnimotionJS agentic skill](https://skills.animotion.click/checkout) — this skill never writes animation code itself.
+- 10 reference playbooks + 4 ready-to-fill templates (builder brief, scaffold HTML, `siteconfig.ts`, outlier anatomy).
+
+## Install
+
+Full guide (per-agent paths, manual install, uninstall): **[docs/INSTALL.md](docs/INSTALL.md)** — worked examples of both modes: **[docs/EXAMPLES.md](docs/EXAMPLES.md)**.
+
+```bash
+# auto-detect your agent (opencode → claude → any detected agent)
+npx agentic-web-developer install
+
+# or target one of the 15 supported agents
+npx agentic-web-developer install --agent=opencode
+npx agentic-web-developer install --agent=claude
+
+# or install for every detected agent at once
+npx agentic-web-developer install --all
+
+# see what's installed where
+npx agentic-web-developer detect
+```
+
+Other flags: `--force` (overwrite), `--dry-run` (print targets only), `--dir=<path>` (custom destination), `--source=<url|path>` / `--token=<key>` (skill source).
+
+Then **restart your AI agent** so it loads the skill.
+
+> **Where does the skill come from?** Not from npm — the package ships only the installer and docs. The installer fetches the skill from a source you configure (`--source`, `AWD_SOURCE`, or the author's `awd.source` in `package.json`). See [docs/INSTALL.md § Skill source](docs/INSTALL.md#skill-source).
+
+### Supported agents
+
+`opencode` · `claude` · `copilot` · `cursor` · `windsurf` · `codex` · `cline` · `roo` · `cody` · `codium` · `aider` · `continue` · `augment` · `amazonq` · `jetbrains`
+
+The installer writes **each agent's own file format** with the right frontmatter — `SKILL.md` for skill agents, `skill.md` for Windsurf/Codium, `rules/*.mdc` for Cursor, `rules/*.md` for Continue/Augment/Amazon Q, `CONVENTIONS.md` for Aider — and puts the `references/` + `templates/` payload where that agent can read it. Same 15 agents as the AnimotionJS skill.
+
+### Manual install (no CLI)
+
+See **[docs/INSTALL.md](docs/INSTALL.md#manual-install-no-cli)** — per-agent copy instructions for all 15 agents.
+
+## Animations are a separate skill (required to finish a site)
+
+Every website built with this skill gets its **animations and interactions from the AnimotionJS agentic skill** — hero reveals, scroll effects, hover states, counters, parallax, text FX. Install it too:
+
+```bash
+npx animotion-skills install --tier=agentic --agent=<your-agent> --license-key=YOUR_KEY
+# or for all detected agents:
+npx animotion-skills install --tier=agentic --all --license-key=YOUR_KEY
+```
+
+- License key (Studio plan, $15/month): https://skills.animotion.click/checkout
+- Local source on the author's machine: `C:\Users\creat\Projects\Animotionjs\animotion-skills`
+
+Without it, the skill will still design and build — but it will stop at Stage 8 and ask you to install Animotion before any motion work.
+
+## Using the skill
+
+Just talk to your agent:
+
+> "Build me a website that converts for my pool cleaning business"
+> "Launch a product website for my new SaaS idea"
+> "Use the agentic-web-developer skill"
+
+The agent classifies the project (Mode A: build-and-sell, Mode B: novel idea), then walks you through every gate.
+
+## Project layout
+
+```
+agentic-web-developer/
+├── package.json          # npm manifest (bin: agentic-web-developer, awd.source)
+├── bin/install.js        # zero-dependency installer CLI (all 15 agents, per-agent formats)
+├── skill/                # ← the skill itself (source of truth; never published)
+│   ├── SKILL.md
+│   ├── references/       # 10 playbooks
+│   └── templates/        # 4 fill-in templates
+├── docs/                 # ← the only content tracked in Git
+│   ├── INSTALL.md        # install guide for all 15 agents
+│   └── EXAMPLES.md       # worked walkthroughs: Mode A + Mode B
+└── README.md             # ← tracked in Git
+```
+
+> **Git vs npm vs skill source — nothing public carries your source:**
+> - **Git:** only `README.md` and `docs/` are visible (`.gitignore` hides the rest).
+> - **npm:** only the installer + docs are published (npm tarballs are public forever, so `skill/` is excluded) — set `awd.source` in `package.json` before publishing.
+> - **Skill source:** `skill/` is fetched by the installer from the URL/path you configure (`--source`, `AWD_SOURCE`, or `awd.source`), with `--token`/`AWD_TOKEN` for private hosts.
+
+## Development
+
+Edit files under `skill/`, then refresh your local opencode install:
+
+```bash
+node bin/install.js install --agent=opencode --force
+```
+
+Check the package contents before publishing:
+
+```bash
+npm run pack:check
+```
+
+## Publishing to npm
+
+```bash
+# 1. point the installer at your private skill source first (never published to npm)
+#    edit package.json -> "awd": { "source": "https://api.github.com/repos/YOU/REPO/tarball/main" }
+#    (end users pass the token: AWD_TOKEN=... npx agentic-web-developer install)
+
+npm login                # once, with your npm account
+npm publish              # publishes bin + docs only (publishConfig.access = "public")
+```
+
+Bump `version` in `package.json` for every update, then `npm publish` again.
+
+## License
+
+UNLICENSED — all rights reserved by the author. Replace the `license` field in `package.json` and add a LICENSE file if you intend to distribute it under a specific license.

package/bin/install.js

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+/**
+ * agentic-web-developer installer
+ *
+ *   npx agentic-web-developer install [--agent=<key>|all] [--source=<url|path>] [--token=<key>]
+ *                                     [--force] [--dry-run] [--dir=<path>]
+ *   npx agentic-web-developer detect
+ *
+ * The npm package ships only this installer (+ docs). The skill payload is
+ * resolved from the first available source:
+ *
+ *   1. --source=<url|path>        explicit flag (URL of a .tar.gz/.zip, or a local folder/archive)
+ *   2. AWD_SOURCE=<url|path>      environment variable
+ *   3. skill/ next to this file   local development checkout
+ *   4. awd.source in package.json configured by the package author
+ *
+ * Private sources: --token=<key> or AWD_TOKEN=<key> (GITHUB_TOKEN is used
+ * for github.com URLs). Installs each agent with its own file format.
+ * No dependencies. Node 18+.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFileSync } = require("child_process");
+
+const argv = process.argv.slice(2);
+const flags = {};
+for (const arg of argv) {
+  const m = arg.match(/^--([^=]+)(?:=(.*))?$/);
+  if (m) flags[m[1]] = m[2] !== undefined ? m[2] : true;
+}
+const command = argv.find((a) => !a.startsWith("--")) || (flags.detect ? "detect" : "install");
+
+const HOME = flags.home ? path.resolve(flags.home) : os.homedir();
+const APPDATA = flags.home
+  ? path.join(HOME, "AppData", "Roaming")
+  : process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+const LOCALAPPDATA = flags.home
+  ? path.join(HOME, "AppData", "Local")
+  : process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+const PKG_ROOT = path.join(__dirname, "..");
+const BUNDLED_SKILL = path.join(PKG_ROOT, "skill");
+const SKILL_NAME = "agentic-web-developer";
+const MARKER = "<!-- agentic-web-developer | installed by npx agentic-web-developer -->";
+
+// format:
+//   skill        -> <dirs>/<name>/SKILL.md
+//   skill-lower  -> <dirs>/<name>/skill.md
+//   rules-mdc    -> <agentRoot>/rules/<name>.mdc   (Cursor rules)
+//   rules-md     -> <agentRoot>/rules/<name>.md    (Continue / Augment / Amazon Q)
+//   conventions  -> <dirs>/CONVENTIONS.md          (Aider)
+// dirs  = candidate skills directories (first existing one wins, else the first is created)
+// roots = used by `detect` to decide whether the agent is installed on this machine
+const AGENTS = {
+  opencode: {
+    name: "OpenCode",
+    format: "skill",
+    roots: [path.join(HOME, ".config", "opencode"), path.join(HOME, ".opencode")],
+    dirs: [path.join(HOME, ".config", "opencode", "skills"), path.join(HOME, ".opencode", "skills")]
+  },
+  claude: {
+    name: "Claude Code",
+    format: "skill",
+    roots: [path.join(HOME, ".claude"), path.join(APPDATA, "claude")],
+    dirs: [path.join(HOME, ".claude", "skills"), path.join(APPDATA, "claude", "skills")]
+  },
+  copilot: {
+    name: "GitHub Copilot",
+    format: "skill",
+    roots: [path.join(APPDATA, "github-copilot"), path.join(HOME, ".config", "github-copilot")],
+    dirs: [path.join(APPDATA, "github-copilot", "skills"), path.join(HOME, ".config", "github-copilot", "skills")]
+  },
+  cursor: {
+    name: "Cursor",
+    format: "rules-mdc",
+    roots: [path.join(HOME, ".cursor"), path.join(LOCALAPPDATA, "cursor")],
+    dirs: [path.join(HOME, ".cursor", "skills"), path.join(LOCALAPPDATA, "cursor", "skills")]
+  },
+  windsurf: {
+    name: "Windsurf (Codeium)",
+    format: "skill-lower",
+    roots: [path.join(HOME, ".codeium", "windsurf"), path.join(LOCALAPPDATA, "windsurf")],
+    dirs: [path.join(HOME, ".codeium", "windsurf", "skills"), path.join(LOCALAPPDATA, "windsurf", "skills")]
+  },
+  cody: {
+    name: "Cody (Sourcegraph)",
+    format: "skill",
+    roots: [path.join(HOME, ".cody"), path.join(APPDATA, "cody")],
+    dirs: [path.join(HOME, ".cody", "skills"), path.join(APPDATA, "cody", "skills")]
+  },
+  codium: {
+    name: "Codium",
+    format: "skill-lower",
+    roots: [path.join(HOME, ".codium"), path.join(LOCALAPPDATA, "codium")],
+    dirs: [path.join(HOME, ".codium", "skills"), path.join(LOCALAPPDATA, "codium", "skills")]
+  },
+  aider: {
+    name: "Aider",
+    format: "conventions",
+    roots: [path.join(HOME, ".aider")],
+    dirs: [path.join(HOME, ".aider", "skills")]
+  },
+  continue: {
+    name: "Continue",
+    format: "rules-md",
+    roots: [path.join(HOME, ".continue")],
+    dirs: [path.join(HOME, ".continue", "skills")]
+  },
+  codex: {
+    name: "Codex (OpenAI)",
+    format: "skill",
+    roots: [path.join(HOME, ".codex"), path.join(HOME, ".agents")],
+    dirs: [path.join(HOME, ".codex", "skills"), path.join(HOME, ".agents", "skills")]
+  },
+  roo: {
+    name: "Roo Code",
+    format: "skill",
+    roots: [path.join(HOME, ".roo"), path.join(HOME, ".agents")],
+    dirs: [path.join(HOME, ".roo", "skills"), path.join(HOME, ".agents", "skills")]
+  },
+  cline: {
+    name: "Cline",
+    format: "skill",
+    roots: [path.join(HOME, ".cline"), path.join(HOME, ".agents")],
+    dirs: [path.join(HOME, ".cline", "skills"), path.join(HOME, ".agents", "skills")]
+  },
+  augment: {
+    name: "Augment",
+    format: "rules-md",
+    roots: [path.join(HOME, ".augment")],
+    dirs: [path.join(HOME, ".augment", "skills")]
+  },
+  amazonq: {
+    name: "Amazon Q",
+    format: "rules-md",
+    roots: [path.join(HOME, ".amazonq"), path.join(HOME, ".aws", "amazonq")],
+    dirs: [path.join(HOME, ".amazonq", "skills"), path.join(HOME, ".aws", "amazonq", "skills")]
+  },
+  jetbrains: {
+    name: "JetBrains AI",
+    format: "skill",
+    roots: [path.join(HOME, ".junie")],
+    dirs: [path.join(HOME, ".junie", "skills")]
+  }
+};
+
+function readSource(skillDir) {
+  const skillMd = path.join(skillDir, "SKILL.md");
+  if (!fs.existsSync(skillMd)) {
+    throw new Error(`no SKILL.md at ${skillMd}`);
+  }
+  const raw = fs.readFileSync(skillMd, "utf8");
+  const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  const body = fm ? raw.slice(fm[0].length) : raw;
+  const descMatch = fm && fm[1].match(/^description:\s*(.+)$/m);
+  const description = descMatch ? descMatch[1].trim().replace(/^['"]|['"]$/g, "") : SKILL_NAME;
+  return { body, description };
+}
+
+function getFrontmatter(key, description) {
+  const d = description.replace(/'/g, "''");
+  const base = `name: ${SKILL_NAME}\ndescription: '${d}'\nlicense: Proprietary`;
+  switch (key) {
+    case "aider":
+      return ""; // Aider uses plain markdown, no frontmatter
+    case "opencode":
+      return `---\n${base}\ncompatibility: opencode\n---\n\n`;
+    case "cursor":
+      return `---\n${base}\nglobs: ["**/*.{html,css,js,ts,jsx,tsx,vue,svelte,astro,md}"]\nalwaysApply: true\n---\n\n`;
+    case "claude":
+      return `---\n${base}\nversion: 1.0.0\n---\n\n`;
+    case "copilot":
+      return `---\n${base}\napplyTo: "**/*"\n---\n\n`;
+    case "windsurf":
+    case "codium":
+      return `---\n${base}\ntrigger: always_on\n---\n\n`;
+    case "cody":
+      return `---\n${base}\n---\n\n`;
+    case "continue":
+      return `---\n${base}\nglobs: "**/*"\n---\n\n`;
+    case "codex":
+      return `---\n${base}\nmetadata:\n  short-description: Build and sell high-converting websites\n---\n\n`;
+    case "roo":
+    case "cline":
+    case "jetbrains":
+      return `---\n${base}\nversion: 1.0.0\n---\n\n`;
+    case "augment":
+    case "amazonq":
+      return `---\n${base}\n---\n\n`;
+    default:
+      return `---\n${base}\n---\n\n`;
+  }
+}
+
+function pickDir(agent) {
+  for (const d of agent.dirs) {
+    if (fs.existsSync(d)) return d;
+  }
+  return agent.dirs[0];
+}
+
+// agentRoot: the agent's home (dir containing skills/ or rules/), derived from a skills dir
+function agentRootOf(skillsDir) {
+  return path.basename(skillsDir) === "skills" ? path.dirname(skillsDir) : skillsDir;
+}
+
+function destFor(key, agent) {
+  if (flags.dir) {
+    const payloadDir = path.join(path.resolve(flags.dir), SKILL_NAME);
+    return { payloadDir, mainFile: path.join(payloadDir, "SKILL.md") };
+  }
+  const base = pickDir(agent);
+  const payloadDir = path.join(base, SKILL_NAME);
+  const root = agentRootOf(base);
+  switch (agent.format) {
+    case "skill":
+      return { payloadDir, mainFile: path.join(payloadDir, "SKILL.md") };
+    case "skill-lower":
+      return { payloadDir, mainFile: path.join(payloadDir, "skill.md") };
+    case "rules-mdc":
+      return { payloadDir, mainFile: path.join(root, "rules", `${SKILL_NAME}.mdc`) };
+    case "rules-md":
+      return { payloadDir, mainFile: path.join(root, "rules", `${SKILL_NAME}.md`) };
+    case "conventions":
+      return { payloadDir, mainFile: path.join(base, "CONVENTIONS.md") };
+    default:
+      return { payloadDir, mainFile: path.join(payloadDir, "SKILL.md") };
+  }
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function installPayload(payloadDir, skillDir) {
+  copyRecursive(path.join(skillDir, "references"), path.join(payloadDir, "references"));
+  copyRecursive(path.join(skillDir, "templates"), path.join(payloadDir, "templates"));
+}
+
+/* ---------------- skill source resolution (private fetch) ---------------- */
+
+function expandHome(p) {
+  if (p === "~") return HOME;
+  if (p.startsWith("~/") || p.startsWith("~\\")) return path.join(HOME, p.slice(2));
+  return p;
+}
+
+// Find the folder holding SKILL.md inside an extracted/downloaded tree.
+// Accepts: the skill folder itself, a folder containing skill/, or an
+// archive whose repo root is the skill (depth <= 3).
+function findSkillRoot(root, depth) {
+  if (fs.existsSync(path.join(root, "SKILL.md"))) return root;
+  const nested = path.join(root, "skill");
+  if (fs.existsSync(path.join(nested, "SKILL.md"))) return nested;
+  if (depth >= 3) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const found = findSkillRoot(path.join(root, e.name), depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function extractArchive(file) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "awd-src-"));
+  const args = /\.zip$/i.test(file) ? ["-xf", file, "-C", work] : ["-xzf", file, "-C", work];
+  try {
+    execFileSync("tar", args, { stdio: "pipe" });
+  } catch (e) {
+    throw new Error(
+      `could not extract ${path.basename(file)} with tar (tar must be on PATH; use a .tar.gz archive — raw: ${e.message})`
+    );
+  }
+  return work;
+}
+
+async function downloadTo(url, label) {
+  const headers = {
+    "User-Agent": "agentic-web-developer-installer",
+    Accept: "application/octet-stream, */*"
+  };
+  const isGithub = /github\.com|githubusercontent\.com/i.test(url);
+  const token = flags.token || process.env.AWD_TOKEN || (isGithub ? process.env.GITHUB_TOKEN : undefined);
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  let res;
+  try {
+    res = await fetch(url, { headers, redirect: "follow" });
+  } catch (e) {
+    throw new Error(`${label}: network error fetching skill source — ${e.message}`);
+  }
+  if (!res.ok) {
+    const hint =
+      res.status === 404 || res.status === 403 || res.status === 401
+        ? " (private source? add --token=<key> or AWD_TOKEN=<key>)"
+        : "";
+    throw new Error(`${label}: download failed — HTTP ${res.status} ${res.statusText}${hint}`);
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "awd-dl-"));
+  const name = (url.split("?")[0].split("/").pop() || "source").replace(/[^A-Za-z0-9._-]/g, "_");
+  const file = path.join(dir, name.includes(".") ? name : `${name}.tar.gz`);
+  fs.writeFileSync(file, Buffer.from(await res.arrayBuffer()));
+  return file;
+}
+
+async function resolveLocation(loc, label) {
+  if (/^https?:\/\//i.test(loc)) {
+    console.log(`skill source (${label}): ${loc}`);
+    const file = await downloadTo(loc, label);
+    const root = findSkillRoot(extractArchive(file), 0);
+    if (!root) throw new Error(`${label}: the downloaded archive contains no SKILL.md — does the source contain the skill/ folder?`);
+    return root;
+  }
+
+  const p = path.resolve(expandHome(loc));
+  if (!fs.existsSync(p)) return null;
+  if (fs.statSync(p).isDirectory()) {
+    const root = findSkillRoot(p, 0);
+    if (!root) throw new Error(`${label}: no SKILL.md found under ${p}`);
+    return root;
+  }
+  const root = findSkillRoot(extractArchive(p), 0);
+  if (!root) throw new Error(`${label}: the archive contains no SKILL.md`);
+  return root;
+}
+
+function readPkg() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function resolveSource() {
+  // 1. explicit flag
+  if (flags.source) {
+    const r = await resolveLocation(String(flags.source), "--source");
+    if (!r) throw new Error(`--source: no such file or directory: ${flags.source}`);
+    return r;
+  }
+  // 2. environment
+  if (process.env.AWD_SOURCE) {
+    const r = await resolveLocation(process.env.AWD_SOURCE, "AWD_SOURCE");
+    if (!r) throw new Error(`AWD_SOURCE: no such file or directory: ${process.env.AWD_SOURCE}`);
+    return r;
+  }
+  // 3. local development checkout (skill/ next to bin/)
+  if (fs.existsSync(path.join(BUNDLED_SKILL, "SKILL.md"))) return BUNDLED_SKILL;
+  // 4. source configured by the package author
+  const pkg = readPkg();
+  const pkgSource = pkg && pkg.awd && pkg.awd.source;
+  if (pkgSource) {
+    const r = await resolveLocation(String(pkgSource), "package.json awd.source");
+    if (r) return r;
+    throw new Error(`package.json awd.source could not be resolved: ${pkgSource}`);
+  }
+  throw new Error(
+    [
+      "no skill source found — this npm package ships only the installer (+ docs).",
+      "Provide the skill payload with one of:",
+      "  --source=<url|path>        a .tar.gz/.zip URL, or a local skill folder/archive",
+      "  AWD_SOURCE=<url|path>      same, via environment variable",
+      "  awd.source in package.json set by the package author before publishing",
+      "Private sources also need a token: --token=<key> or AWD_TOKEN=<key>",
+      "Local development: keep the skill/ folder next to bin/ — it is used automatically."
+    ].join("\n")
+  );
+}
+
+/* -------------------------------- commands -------------------------------- */
+
+function detect() {
+  console.log(`\nAgents on this machine (and ${SKILL_NAME} install status):\n`);
+  let found = 0;
+  for (const [key, agent] of Object.entries(AGENTS)) {
+    const present = agent.roots.some((r) => fs.existsSync(r));
+    const { mainFile, payloadDir } = destFor(key, agent);
+    let installed = fs.existsSync(mainFile);
+    // Aider's CONVENTIONS.md may belong to another skill — require our marker
+    if (installed && agent.format === "conventions") {
+      installed = fs.readFileSync(mainFile, "utf8").includes(MARKER);
+    }
+    if (installed && !fs.existsSync(payloadDir)) installed = false;
+    if (present) found++;
+    const status = installed ? "INSTALLED" : present ? "not installed" : "agent not found";
+    console.log(
+      `  ${present || installed ? "*" : " "} ${key.padEnd(10)} ${agent.name.padEnd(20)} ${status}` +
+        (installed ? `  -> ${mainFile}` : "")
+    );
+  }
+  console.log(`\n  Install: npx ${SKILL_NAME} install --agent=<key>   (or --all, or omit --agent for auto)\n`);
+  return found;
+}
+
+async function install() {
+  const skillDir = await resolveSource();
+  const { body, description } = readSource(skillDir);
+
+  let keys;
+  if (flags.agent === "all") {
+    keys = Object.keys(AGENTS);
+  } else if (flags.agent) {
+    if (!AGENTS[flags.agent]) {
+      throw new Error(`unknown agent "${flags.agent}". Valid keys: ${Object.keys(AGENTS).join(", ")}, all`);
+    }
+    keys = [flags.agent];
+  } else if (flags.all) {
+    keys = Object.keys(AGENTS);
+  } else {
+    // auto: opencode first, then claude, then any detected agent
+    const detected = Object.entries(AGENTS).filter(([, a]) => a.roots.some((r) => fs.existsSync(r)));
+    const preferred = ["opencode", "claude"].filter((k) => detected.some(([dk]) => dk === k));
+    keys = [preferred[0] || (detected[0] && detected[0][0]) || "opencode"];
+  }
+
+  let done = 0;
+  for (const key of keys) {
+    const agent = AGENTS[key];
+    const { payloadDir, mainFile } = destFor(key, agent);
+    const isRuleFile = ["rules-mdc", "rules-md", "conventions"].includes(agent.format);
+
+    if (flags["dry-run"]) {
+      console.log(`[dry-run] ${agent.name} (${key})`);
+      console.log(`          main: ${mainFile}`);
+      console.log(`          refs: ${payloadDir}{/references, /templates}`);
+      done++;
+      continue;
+    }
+
+    if (fs.existsSync(mainFile) && !flags.force) {
+      if (agent.format === "conventions") {
+        const existing = fs.readFileSync(mainFile, "utf8");
+        if (!existing.includes(MARKER)) {
+          console.log(`skip ${agent.name}: ${mainFile} already exists and was not written by this installer (use --force to overwrite)`);
+          continue;
+        }
+      }
+      console.log(`skip ${agent.name}: already installed at ${mainFile} (use --force to overwrite)`);
+      continue;
+    }
+
+    fs.mkdirSync(payloadDir, { recursive: true });
+    installPayload(payloadDir, skillDir);
+
+    // Frontmatter per agent; rule files get a pointer to the reference payload
+    let content = getFrontmatter(key, description) + body;
+    if (isRuleFile) {
+      const pointer = `> Reference playbooks: ${path.join(payloadDir, "references")} — templates: ${path.join(payloadDir, "templates")}\n\n`;
+      const fm = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n\n/);
+      if (fm) {
+        content = fm[0] + pointer + content.slice(fm[0].length);
+      } else {
+        content = `${MARKER}\n${pointer}${content}`;
+      }
+    }
+    fs.mkdirSync(path.dirname(mainFile), { recursive: true });
+    fs.writeFileSync(mainFile, content);
+    console.log(`installed ${agent.name} (${key})`);
+    console.log(`  main: ${mainFile}`);
+    console.log(`  refs: ${payloadDir}`);
+    done++;
+  }
+
+  if (!done) {
+    console.log("nothing installed — everything already present (use --force to overwrite)");
+  } else if (!flags["dry-run"]) {
+    console.log(`\nDone. Restart your AI agent so it loads ${SKILL_NAME}.`);
+    console.log("Animations for any site built with this skill are handled by the AnimotionJS agentic skill:");
+    console.log("  npx animotion-skills install --tier=agentic --agent=<agent> --license-key=YOUR_KEY");
+  }
+}
+
+switch (command) {
+  case "detect":
+    detect();
+    break;
+  case "install":
+    install().catch((err) => {
+      console.error(`error: ${err.message}`);
+      process.exit(1);
+    });
+    break;
+  case "help":
+  case "--help":
+    usage();
+    break;
+  default:
+    usage();
+    process.exit(1);
+}
+
+function usage() {
+  console.log(`
+${SKILL_NAME} — install the agentic-web-developer skill into your AI agent
+
+Usage:
+  npx ${SKILL_NAME} install [options]
+  npx ${SKILL_NAME} detect
+
+Options:
+  --agent=<key>   Target one agent: ${Object.keys(AGENTS).join(", ")}
+  --agent=all     Target every supported agent
+  --all           Same as --agent=all
+  --source=<s>    Skill source: a .tar.gz/.zip URL or a local folder/archive
+                  (falls back to AWD_SOURCE, then skill/, then awd.source)
+  --token=<key>   Auth token for a private source (or AWD_TOKEN=<key>)
+  --force         Overwrite an existing install
+  --dry-run       Print target paths without copying
+  --dir=<path>    Install into <path>/${SKILL_NAME} (flat, SKILL.md layout)
+  --home=<path>   Use <path> as the home directory (testing)
+
+Skill source order: --source > AWD_SOURCE > ./skill > package.json awd.source
+The npm package ships only this installer (+ docs) — never the skill source.
+
+Each agent gets its own file format:
+  skill agents (opencode, claude, copilot, cody, codex, roo, cline, jetbrains)
+                            -> <skills>/${SKILL_NAME}/SKILL.md
+  windsurf, codium          -> <skills>/${SKILL_NAME}/skill.md
+  cursor                    -> ~/.cursor/rules/${SKILL_NAME}.mdc
+  continue                  -> ~/.continue/rules/${SKILL_NAME}.md
+  augment                   -> ~/.augment/rules/${SKILL_NAME}.md
+  amazonq                   -> ~/.amazonq/rules/${SKILL_NAME}.md
+  aider                     -> ~/.aider/skills/CONVENTIONS.md
+
+Examples:
+  npx ${SKILL_NAME} install                                # auto-detect agent
+  npx ${SKILL_NAME} install --agent=all --source=https://you/server/skill.tar.gz --token=KEY
+  npx ${SKILL_NAME} detect
+`);
+}

package/docs/EXAMPLES.md

@@ -0,0 +1,67 @@
+# Examples — the two scenarios
+
+The skill runs the same 11-stage gated pipeline in both modes. Every stage ends with a question to you; answers are recorded in `build-state.md`. These are two complete walkthroughs.
+
+---
+
+## Scenario A — Mode A: build-and-sell a website for a local business
+
+**You say:**
+
+> "Build me a website that converts for my pool cleaning business in Phoenix."
+
+**Mode:** A (build-and-sell — the video default). Goal: a site you can sell as a product, plus the outreach system to find buyers.
+
+| Stage | What happens | The gate (you answer) |
+|---|---|---|
+| 0 — Intake | Agent records: offer ("pool cleaning, weekly plans"), audience (Phoenix homeowners), mode A, no client list yet, $0/mo tool budget | "Confirm the offer and audience — and do you have any clients/leads yet, or start from zero?" → *"start from zero"* |
+| 1 — Money framework | Runs **M** of M.O.N.E.Y: validates "pool cleaning in Phoenix" — unsexy niche, 20+ businesses, most sites outdated, you know the trade | "Pick the niche: pool cleaning, HVAC, or landscaping in Phoenix?" → *"pool cleaning"* |
+| 2 — Research | **Design Blueprint Extractor** on an inspiration site you name (e.g. a clean SaaS-style home-services site) → `builderbrief.md`, `scaffold.html`, `tokens.json`. **Outlier Research** scrapes 12 pool companies → top 5 / bottom 5 → `outlier-anatomy.md` (winners: price-on-site, booking form, reviews above fold; losers: flash intros, no phone number) | "Approve the inspiration site and the outlier findings?" → *"yes, but keep the blue from the inspiration"* |
+| 3 — Design tool | — | "Which tool: Stitch, AI Studio, Figma, Paper, or code-first?" → *"Stitch"* |
+| 4 — Design | Section plan from the anatomy: hero + phone CTA, stat strip (years, pools serviced), plans grid, how-it-works, reviews, FAQ, quote form | "Review the design — approve before code?" → *"approve"* |
+| 5 — Framework | — | "Framework?" → *"plain HTML/CSS + a bit of JS"* (client wants cheap hosting) |
+| 6 — Build | Page(s) built 1:1 from the design, all content from `siteconfig.ts`; AI-generated hero image iterated until the pool photo leaves room for the headline | "Look at localhost — review before QA?" → *"looks good"* |
+| 7 — QA | Conversion blueprint + UI/UX checklist: H1 "Pool Cleaning That Never Misses a Week" (6 words), AA contrast, form tested, mobile widths checked | "QA passed — approve?" → *"approve"* |
+| 8 — Animation | You're told: **all motion goes to AnimotionJS** (Stage plan): hero reveal, scroll reveals, plan-card hover, counter on the stat strip → motion brief written and handed to the Animotion skill | "Animotion installed? Approve the motion brief?" → *"installed, approved"* |
+| 9 — Deploy | — | "Deploy where: GitHub→Vercel, GoHighLevel, or WordPress?" → *"GitHub → Vercel"* |
+| 10 — Sell | Runs the outreach system: scrapes Phoenix pool companies (Apify, budget-capped), enriches emails, then sends: *free site as the foot in the door* → hosting retainer ($50–150/mo) → SEO/reviews upsells; Day 1/3/7 follow-ups | "Draft the outreach emails for niche 'pool cleaning'?" → *"send to 20 leads"* |
+
+**Result:** a deployed, converting site + a repeatable client-acquisition loop. The same `siteconfig.ts` makes the next local-business site a clone, not a rebuild.
+
+---
+
+## Scenario B — **Mode B — launch your own product (SaaS)**
+
+**You say:**
+
+> "I have a SaaS idea — FocusFlow, a focus timer with team accountability. I want to launch it."
+
+**Mode:** B (novel idea / product launch — no customer list). Re-scopes Stages 1, 2's outliers, 4–7's goal, 3/5's surface, and 10's motion.
+
+| Stage | What happens | The gate (you answer) |
+|---|---|---|
+| 0 — Intake | Agent records: idea ("FocusFlow — team focus timer"), audience (remote teams / ADHD founders), mode B, **brand assets collected**: existing teal logo + palette from your deck; **inspiration sites collected**: linear.app and stripe.com | "Confirm the idea and audience — and what brand assets exist?" → *"teal logo + palette; new type"* |
+| 1 — Idea/audience validation | Re-scoped: who has this problem (r/ADHD, remote-work Discords), alternatives (Float, Motion, plain Pomodoro), demand signals (competitor reviews complaining about pricing) | "Audience confirmed: remote teams of 2–10?" → *"yes"* |
+| 2 — Research | **Design Blueprint Extractor runs exactly like Mode A**: linear.app as inspiration (type scale, density, border language) + **second pass on your brand** (teal palette from the logo/deck) → merged: brand colors win, linear sets the feel → `builderbrief.md`, `scaffold.html`, `tokens.json`. **Outlier Research** re-scoped to rival launch pages (Motion, Forest, Pomodoro apps by traffic/reviews) → `outlier-anatomy.md` | "Approve the inspiration + extracted brand style?" → *"yes, keep #0D9488 as primary"* |
+| 3 — Design tool | — | "Tool?" → *"code-first (Next.js)"* (multi-page app-like site) |
+| 4 — Design | Section plan re-scoped to the product's anatomy: demo/video hero, feature grid, integrations logos, pricing tiers, testimonials, FAQ — single CTA: **Join the waitlist** | "Approve the design?" → *"approve"* |
+| 5 — Framework | — | "Framework?" → *"Next.js"* — multi-page scaffold: `/`, `/pricing`, `/docs` |
+| 6 — Build | Pages built from the outlier anatomy; AI-generated abstract hero matched to the teal palette; conversion goal wired: waitlist form (email only, no password) | "Review on localhost?" → *"approve"* |
+| 7 — QA | Same checklists, goal adjusted: H1 "Focus Together, Finish Faster" (5 words), one CTA everywhere, form → provider tested, responsive pass | "QA passed?" → *"approve"* |
+| 8 — Animation | Motion brief to AnimotionJS: hero mask reveal, feature-card scroll stagger, pricing hover lift, waitlist-button magnetic hover | "Animotion installed? Approve brief?" → *"approved"* |
+| 9 — Deploy | — | "Deploy where?" → *"GitHub → Vercel + custom domain"* |
+| 10 — Launch motion | Re-scoped from cold outreach: waitlist/launch email sequence, founder outreach (remote-work communities, r/SaaS), Product Hunt draft — same email rules (human subject, no hard ask, proof + link); monetization = trial/paid tiers instead of retainers | "Draft the launch emails and PH post?" → *"yes"* |
+
+**Result:** a live multi-page product site with your brand DNA extracted alongside the inspiration, waitlist converting, and a launch sequence ready to send.
+
+---
+
+## What's identical in both modes
+
+- Inspiration-site **design DNA extraction** and **brand-style extraction** (Stage 2)
+- The conversion blueprint and QA checklists (Stage 7)
+- Deployment (Stage 9)
+- **The animation rule:** no motion code is ever written by this skill — Stage 8 hands a motion brief to the **AnimotionJS agentic skill** for all 15 supported agents
+- A question gate at the end of every stage
+
+Install for your agent: [INSTALL.md](./INSTALL.md).

package/docs/INSTALL.md

@@ -0,0 +1,147 @@
+# Installing agentic-web-developer
+
+The skill installs into **15 AI coding agents** — the same 15 the AnimotionJS skill supports. The installer writes each agent's own file format (`SKILL.md`, `skill.md`, a rules file, or `CONVENTIONS.md`) with the right frontmatter, plus the reference playbooks and templates alongside it.
+
+> **The npm package contains only the installer and these docs** — never the skill source. The installer fetches the skill payload from a *skill source* you configure (see [Skill source](#skill-source)).
+
+## Quick start
+
+```bash
+# auto-detect your agent (opencode -> claude -> any detected agent)
+npx agentic-web-developer install
+
+# target one agent by key
+npx agentic-web-developer install --agent=claude
+
+# install for every supported agent at once
+npx agentic-web-developer install --all
+
+# see what's installed, and where
+npx agentic-web-developer detect
+```
+
+Then **restart your AI agent** so it loads the skill.
+
+### All flags
+
+| Flag | Effect |
+|---|---|
+| `--agent=<key>` | Install for one agent (keys in the table below) |
+| `--agent=all` / `--all` | Install for all 15 agents |
+| `--source=<url\|path>` | Skill source: a `.tar.gz`/`.zip` URL, or a local skill folder/archive |
+| `--token=<key>` | Auth token for a private source (else `AWD_TOKEN`) |
+| `--force` | Overwrite an existing install |
+| `--dry-run` | Print the target paths without writing anything |
+| `--dir=<path>` | Install flat into `<path>/agentic-web-developer/` (SKILL.md layout) |
+| `--home=<path>` | Use `<path>` as the home directory (for testing) |
+
+## Skill source
+
+Because the npm tarball ships no `skill/` folder, the installer resolves the payload from the first available source, in this order:
+
+1. `--source=<url|path>` — explicit flag
+2. `AWD_SOURCE=<url|path>` — environment variable
+3. `skill/` next to `bin/` — local development checkout (used automatically)
+4. `awd.source` in `package.json` — set by the package author before publishing
+
+**URL sources** are downloaded and extracted (system `tar`; `.tar.gz` preferred, `.zip` works on Windows/macOS). The archive may be the repo root, a `skill/` folder inside it, or anything containing `SKILL.md` within three levels.
+
+**Private sources** need a token: `--token=<key>` or `AWD_TOKEN=<key>` (`GITHUB_TOKEN` is used automatically for github.com URLs):
+
+```bash
+# private GitHub repo (tarball API)
+npx agentic-web-developer install --source=https://api.github.com/repos/YOU/private-skill/tarball/main --token=ghp_XXXX
+
+# same, via environment (handy for CI or shell profiles)
+export AWD_SOURCE=https://api.github.com/repos/YOU/private-skill/tarball/main
+export AWD_TOKEN=ghp_XXXX
+npx agentic-web-developer install
+
+# your own server / object storage
+npx agentic-web-developer install --source=https://your-server/skill.tar.gz
+
+# local folder or archive (no network)
+npx agentic-web-developer install --source=~/backups/skill
+```
+
+The package author normally sets `awd.source` in `package.json` once, so end users just run `npx agentic-web-developer install` with no configuration.
+
+## Where each agent gets the skill
+
+| Key | Agent | File written | Plus |
+|---|---|---|---|
+| `opencode` | OpenCode | `~/.config/opencode/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `claude` | Claude Code | `~/.claude/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `copilot` | GitHub Copilot | `%APPDATA%\github-copilot\skills\agentic-web-developer\SKILL.md` | `references/`, `templates/` |
+| `cursor` | Cursor | `~/.cursor/rules/agentic-web-developer.mdc` | payload in `~/.cursor/skills/agentic-web-developer/` |
+| `windsurf` | Windsurf (Codeium) | `~/.codeium/windsurf/skills/agentic-web-developer/skill.md` | `references/`, `templates/` |
+| `cody` | Cody (Sourcegraph) | `~/.cody/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `codium` | Codium | `~/.codium/skills/agentic-web-developer/skill.md` | `references/`, `templates/` |
+| `aider` | Aider | `~/.aider/skills/CONVENTIONS.md` | payload in `~/.aider/skills/agentic-web-developer/` |
+| `continue` | Continue | `~/.continue/rules/agentic-web-developer.md` | payload in `~/.continue/skills/agentic-web-developer/` |
+| `codex` | Codex (OpenAI) | `~/.codex/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `roo` | Roo Code | `~/.roo/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `cline` | Cline | `~/.cline/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+| `augment` | Augment | `~/.augment/rules/agentic-web-developer.md` | payload in `~/.augment/skills/agentic-web-developer/` |
+| `amazonq` | Amazon Q | `~/.amazonq/rules/agentic-web-developer.md` | payload in `~/.amazonq/skills/agentic-web-developer/` |
+| `jetbrains` | JetBrains AI | `~/.junie/skills/agentic-web-developer/SKILL.md` | `references/`, `templates/` |
+
+Notes:
+
+- **Rules agents** (cursor, continue, augment, amazonq) receive the full skill body as a rules file with agent-specific frontmatter (`globs`, `alwaysApply`, `trigger`, …). The file starts with a pointer to the installed `references/` and `templates/` payload so the agent can read the playbooks on demand.
+- **Aider** has no skill loader — it reads conventions files. The skill lands at `~/.aider/skills/CONVENTIONS.md`. Point Aider at it with `aider --read ~/.aider/skills/CONVENTIONS.md`, or copy that file into a project as `CONVENTIONS.md`. The installer never overwrites a `CONVENTIONS.md` it didn't write (unless you pass `--force`), so an existing Animotion or other conventions file is safe.
+- Windows paths are shown with `~` for your user home; `%APPDATA%` is your Roaming app-data folder.
+
+## Manual install (no CLI)
+
+Get the skill folder itself (the package doesn't contain it — take it from your configured source, or a copy someone sent you), then place the files as the table above says:
+
+- **SKILL.md agents** — copy the `skill/` folder to `<skills-dir>/agentic-web-developer/` (it must contain `SKILL.md`, `references/`, `templates/`).
+- **Windsurf / Codium** — same, but rename `SKILL.md` to `skill.md`.
+- **Cursor** — copy `skill/SKILL.md` to `~/.cursor/rules/agentic-web-developer.mdc`, keep `references/` + `templates/` in `~/.cursor/skills/agentic-web-developer/`.
+- **Continue / Augment / Amazon Q** — copy `skill/SKILL.md` to the agent's `rules/agentic-web-developer.md` (paths in the table), payload alongside in `skills/agentic-web-developer/`.
+- **Aider** — copy `skill/SKILL.md` (without its `---` frontmatter block) to `~/.aider/skills/CONVENTIONS.md`.
+
+## Verify
+
+```bash
+npx agentic-web-developer detect
+```
+
+`INSTALLED` next to an agent means the skill file and its payload are both in place.
+
+## Uninstall
+
+Delete what the table lists for your agent — the skill file **and** the `agentic-web-developer/` payload folder. For example:
+
+```bash
+# opencode
+rm -rf ~/.config/opencode/skills/agentic-web-developer
+
+# cursor (rule file + payload)
+rm -f ~/.cursor/rules/agentic-web-developer.mdc
+rm -rf ~/.cursor/skills/agentic-web-developer
+```
+
+## Companion: AnimotionJS (required for animation)
+
+Every site built with this skill gets its **animations from the AnimotionJS agentic skill** — this skill never writes motion code. Install Animotion for the same agent:
+
+```bash
+npx animotion-skills install --tier=agentic --agent=<agent> --license-key=YOUR_KEY
+npx animotion-skills install --tier=agentic --all --license-key=YOUR_KEY   # every detected agent
+npx animotion-skills install --detect
+```
+
+- License key (Studio plan, $15/month): https://skills.animotion.click/checkout
+- Without a key the build still works up to Stage 8 (animation handoff), where it stops and asks you to install Animotion.
+
+## Repository vs npm package vs skill source
+
+- **This Git repository** contains **documentation only** (`README.md`, `docs/`) — the `.gitignore` hides everything else.
+- **The npm package** contains **only the installer** (`bin/install.js`) + docs — never `skill/`. Anything in a published tarball is publicly downloadable forever, so the source stays out of it.
+- **The skill source** lives wherever you say: [Skill source](#skill-source) (`--source`, `AWD_SOURCE`, or the author's `awd.source`).
+
+## Examples
+
+Two full scenario walkthroughs — one per mode — are in [EXAMPLES.md](./EXAMPLES.md).

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "agentic-web-developer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Agentic skill for building high-converting websites that sell — design DNA extraction, outlier competitor research, conversion blueprints, the M.O.N.E.Y sales framework, lead generation, cloning, outreach and deployment, with a novel-idea/product-launch mode. All animation work is delegated to the AnimotionJS agentic skill.",
+  "keywords": [
+    "opencode",
+    "skill",
+    "agentic",
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "web-development",
+    "website-builder",
+    "conversion",
+    "landing-page",
+    "money-framework",
+    "animotion",
+    "animotionjs"
+  ],
+  "bin": {
+    "agentic-web-developer": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "detect": "node bin/install.js detect",
+    "install:skill": "node bin/install.js install",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "awd": {
+    "source": "https://4e2zaktqel.ucarecd.net/c3f306d4-38fd-4545-b6ef-e3bef7f9888a/skilltar.gz"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}