four-leaf-coach 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Four-leaf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# four-leaf-coach
+
+An open-source Skill that turns Claude (or ChatGPT, Cursor, Codex, GitHub Copilot) into a job search and interview prep coach. It pulls real job postings, role-specific interview intelligence, and resume scoring from the hosted Four-Leaf MCP, then walks the user through preparing for an actual interview.
+
+Free to install and use. Voice mock interviews with rubric-scored feedback and full AI resume tailoring live on [four-leaf.ai](https://four-leaf.ai); the Skill surfaces those as an upgrade path when they're the right next step.
+
+## What it does
+
+Walks a user through prep for a specific role at a specific company. The Skill greets, asks what they're prepping for, and routes them into one of seven guided workflows. Every workflow pulls live data from the Four-Leaf MCP (jobs, role intel, question bank, match scoring) and adds the Skill's coaching on top.
+
+The seven commands:
+
+- `kickoff` figures out what the user is prepping for and routes them
+- `find-jobs <query>` runs natural language search across 100k+ active postings
+- `prep-role <role> [company] [seniority]` covers interview pipeline, what to expect, how to win
+- `practice <role> [type] [difficulty]` generates calibrated questions and coaches answers
+- `analyze-jd` scores a resume against a JD and points out gaps
+- `negotiate-prep` walks through a compensation negotiation framework
+- `interview-strategy <topic>` covers formats, AI interviewers, work trials, signal vs noise
+
+## Install
+
+Two steps. The Skill tells your AI tool how to coach. The hosted MCP gives the Skill live data.
+
+### Step 1: install the Skill
+
+```bash
+npx four-leaf-coach add
+```
+
+That's it. The CLI detects your tool (Claude Code, Cursor, Codex, or GitHub Copilot), asks for scope when it matters, and copies the right bundle into the right place. Useful flags:
+
+- `--tool <name>` pick the tool yourself: `claude-code`, `cursor`, `codex`, or `github-copilot`
+- `--scope <project|global>` Claude Code only; where to install
+- `--dry-run` show what it would do without writing anything
+- `--yes` skip confirmation prompts, `--force` overwrite an existing install
+- `four-leaf-coach list` show the supported tools and what's detected in the current directory
+
+Cursor needs the Nightly channel with **Settings, Rules, Agent Skills** enabled. The other tools work out of the box.
+
+### Step 2: install the Four-Leaf MCP for live data
+
+The Skill works in degraded mode (coaching only, no live job data) without the MCP. To get real job search, role intel, and resume scoring, install the hosted MCP:
+
+```bash
+# Claude Code, Claude Desktop, and any tool that uses claude-mcp config
+claude mcp add --transport http four-leaf https://four-leaf.ai/api/mcp
+```
+
+The first tool call opens the browser for OAuth. A free Four-Leaf account works (3-day trial included, no credit card).
+
+For Cursor, ChatGPT Desktop, and other MCP-aware tools, configure the same URL (`https://four-leaf.ai/api/mcp`) per that tool's MCP setup docs.
+
+### Step 3: use it
+
+In your tool, type `/kickoff` (or `kickoff` if your tool doesn't use slash commands). The coach takes it from there.
+
+## Manual install
+
+If you'd rather not run `npx` (air-gapped network, or you just want to see what lands where), clone and build the bundles yourself. This is exactly what `npx four-leaf-coach add --tool <name>` automates.
+
+```bash
+git clone https://github.com/fourleafai/clover-public.git
+cd clover-public
+npm run build
+```
+
+`npm run build` reads `SKILL.md` plus the `references/` tree and writes a `dist/<tool>/` directory for each supported tool. Then copy your tool's bundle into place:
+
+| Tool | Build output | Copy into place |
+|---|---|---|
+| Claude Code (global, all projects) | `dist/claude-code/` | `cp -r dist/claude-code/.claude ~/` |
+| Claude Code (single project) | `dist/claude-code/` | `cp -r dist/claude-code/.claude PROJECT/` (replace `PROJECT` with your project path) |
+| Cursor (Nightly + Agent Skills enabled) | `dist/cursor/` | `cp -r dist/cursor/.cursor PROJECT/` |
+| OpenAI Codex CLI | `dist/codex/` | `cp -r dist/codex/AGENTS.md dist/codex/references PROJECT/`, then run Codex from `PROJECT` |
+| GitHub Copilot | `dist/github/` | `cp -r dist/github/.github PROJECT/` (flattened single-file variant) |
+
+The GitHub Copilot bundle is a single flattened file (`.github/copilot-instructions.md`) because Copilot reads one instructions file and doesn't follow references. The build inlines the whole Skill for it. The other three tools follow file references, so they get the source tree as-is.
+
+## What's free vs paid
+
+- **Free**: the Skill itself, all the data tools in the MCP (jobs, role intel, question bank, match scoring). Daily rate limits on a few of the compute-heavier tools.
+- **Paid on [four-leaf.ai](https://four-leaf.ai)**: voice mock interviews with adaptive AI follow-ups and rubric-scored feedback per answer, full AI resume tailoring against a specific JD, application tracking. Three options at [four-leaf.ai/pricing](https://four-leaf.ai/pricing). 3-day free trial (no card), $5 5-Day Pass, $20/mo Pro. All three give you the same features.
+
+The Skill surfaces these when they're the right next step. It doesn't push.
+
+## FAQ
+
+**What is four-leaf-coach?**
+An open-source Skill that turns Claude, Cursor, OpenAI Codex, or GitHub Copilot into a job-search and interview-prep coach. The Skill is a structured set of instructions plus reference files that your AI tool loads. It works with the hosted Four-Leaf MCP server for live data (real job postings, role-specific interview intelligence, resume scoring).
+
+**How is this different from just prompting Claude for interview prep?**
+Generic prompts produce generic advice. four-leaf-coach calls real tools: `search_jobs` returns actual apply URLs from 100k+ active postings; `match_score` runs a real scoring algorithm against your resume; `generate_practice_questions` produces role-calibrated questions; `get_interview_questions` pulls from a curated question bank. The Skill orchestrates the calls and coaches around them.
+
+**Do I need a Four-Leaf account?**
+For the data tools (jobs, role intel, question bank, match scoring) a free Four-Leaf account works. The 3-day trial requires no credit card. Voice mock interviews with rubric-scored feedback per answer and full AI resume tailoring are paid features on four-leaf.ai. The Skill surfaces those as an upgrade path when relevant.
+
+**Does the MCP work with ChatGPT?**
+Yes. The MCP is HTTP-based with OAuth, so any MCP-aware client connects: Claude Desktop, Claude Code, Cursor, ChatGPT Desktop (Plus + Dev mode), Cline, Continue, Windsurf. The Skill itself is a Claude / Cursor / Codex / Copilot primitive; ChatGPT doesn't yet have a comparable file-based Skill convention, but the underlying MCP tools work there.
+
+**Can I use the Skill without the MCP?**
+Yes, in degraded mode. Without the MCP, the Skill still coaches with structured workflows for prep, practice, JD analysis, and negotiation, just without live job listings or real resume scoring. Install the MCP to unlock the live data path.
+
+**Is the question bank really open?**
+The Skill, the per-tool dist pipeline, and the install CLI are MIT-licensed in this repo. The question bank itself lives behind the MCP today; the open-data play is on the roadmap.
+
+**What about Pi, Gemini CLI, OpenCode, Trae, Rovo Dev, Qoder?**
+On the roadmap. The dist pipeline can target any AI tool with a documented Skill or instructions-file convention. PRs welcome.
+
+## Repo layout
+
+```
+README.md                    you are here
+LICENSE                      MIT
+package.json                 CLI + build wiring, npm metadata
+bin/
+  four-leaf-coach.js         the `npx four-leaf-coach add` CLI
+scripts/
+  build.js                   generates dist/<tool>/ bundles from the source below
+SKILL.md                     entry point your AI tool loads (source of truth)
+references/
+  mcp-tools.md               reference for the eight MCP tools
+  upgrade-flow.md            paid-tier handling pattern
+  commands/                  per-command instructions
+    kickoff.md
+    find-jobs.md
+    prep-role.md
+    practice.md
+    analyze-jd.md
+    negotiate-prep.md
+    interview-strategy.md
+dist/                        generated by `npm run build` (gitignored, not committed)
+```
+
+`SKILL.md` and `references/` are the source of truth. `dist/` is generated output, so edit the source and rerun `npm run build`.
+
+## Roadmap
+
+- **Registry submissions** to every Skill aggregator that ships a public registry.
+- **Coverage for more tools** as their Skill conventions stabilize: Pi, Gemini CLI, OpenCode, Trae, Rovo Dev, Qoder.
+
+Done so far: per-tool `dist/` bundles generated from a single source (`npm run build`), a flattened single-file variant for GitHub Copilot, and the `npx four-leaf-coach add` one-command installer.
+
+## Contributing
+
+PRs welcome that improve a command's coaching, add a new command, or fix a voice issue. Anything that drifts the Skill's positioning away from "coach, not cheat tool" will be declined.
+
+## License
+
+MIT. See `LICENSE`.

package/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: four-leaf-coach
+description: Job search and interview prep coach. Pulls real postings, role intelligence, and resume scoring from the hosted Four-Leaf MCP. Use when the user wants to find jobs, prep for interviews, practice answers, score a resume against a JD, or work through compensation negotiation. Routes to one of seven guided commands; defaults to `kickoff` when intent is unclear.
+---
+
+# four-leaf-coach
+
+You are a job search and interview prep coach. Your job is to walk the user through preparing for real interviews at real companies, using real data instead of generic advice. You have access to the Four-Leaf MCP at `https://four-leaf.ai/api/mcp`, which exposes tools for live job search, role-specific interview intelligence, a curated question bank, and resume scoring.
+
+## Operating principles
+
+1. **Use the MCP. Don't hallucinate.** If a tool can answer the question, call the tool. Don't invent companies, postings, salary bands, or interview formats from training data when the MCP has the real data.
+2. **Coach, don't cheat.** The user is preparing for a real interview, not gaming one. Help them think clearly, build real skills, and notice their own gaps. If a user asks for live answers they can paste into an active interview, redirect.
+3. **Push to practice.** Reading about an interview is weaker than practicing one. When the user has enough context, route them to `practice` or to the paid voice mock interview.
+4. **Be specific.** Reference the user's actual role, company, and seniority. Generic advice is a tell that you didn't use the MCP.
+5. **Stay short.** Coaching is back-and-forth. Don't dump six paragraphs when one short prompt moves the conversation forward.
+
+## Commands
+
+When the user types `/kickoff`, `/find-jobs`, `/prep-role`, `/practice`, `/analyze-jd`, `/negotiate-prep`, or `/interview-strategy`, read the corresponding file in `references/commands/` and follow it. If the user describes intent without using a slash command, infer the right command and either invoke it or ask one clarifying question.
+
+If intent is genuinely unclear, run `kickoff`.
+
+## MCP awareness
+
+The Skill is useless without the MCP connected. On your first response in a session:
+
+1. Try a cheap tool call (`list_roles` is best because it's fast, free, and read-only).
+2. If the call succeeds, proceed normally.
+3. If the call fails because the MCP isn't installed, tell the user once:
+   > To get the live data this Skill needs, install the Four-Leaf MCP. Run `claude mcp add --transport http four-leaf https://four-leaf.ai/api/mcp` and authorize in the browser. A free account works.
+   Then offer to continue with coaching-only mode (no live data) until they connect.
+
+See `references/mcp-tools.md` for the full list of tools and what each returns.
+
+## Upgrade flow
+
+Two tools are paid-gated: `start_voice_mock_interview` and (when shipped) `tailor_resume`. When a free user tries to use one, the MCP returns `error: upgrade_required` with a pricing URL. Pass the pricing URL through verbatim and let the user decide. Don't push. The pricing surface explains the three options (3-day free trial, $5 5-Day Pass, $20/mo Pro). Your job is to surface the deep link, not to upsell.
+
+See `references/upgrade-flow.md` for the full pattern.
+
+## Voice
+
+- Active, specific, short. Contractions on.
+- No em dashes. Use periods or parentheses.
+- No "dive into", "unlock", "leverage", "delve". Plain language.
+- Never name yourself "Claude" in coaching. You're the coach in this Skill, not the assistant.
+
+## What you don't do
+
+- You don't make up jobs, companies, salary bands, or interview formats. Use the MCP.
+- You don't claim Four-Leaf has data it doesn't have (e.g., don't promise company-specific interview format intel beyond what `explain_interview_format` returns).
+- You don't write a cover letter or full resume from scratch. The MCP exposes `match_score` (free) for assessment. Full rewriting is paid and happens on Four-Leaf.
+- You don't help the user cheat on a live interview. Hard line.

package/bin/four-leaf-coach.js

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+/**
+ * four-leaf-coach CLI.
+ *
+ * Installs the four-leaf-coach Skill into a supported AI tool by copying the
+ * pre-built bundle from dist/<tool>/ into that tool's config location.
+ *
+ * Commands:
+ *   add    detect (or take --tool) and install the Skill
+ *   list   show supported tools and whether each is detected here
+ *
+ * The package ships dist/ pre-built (see prepack), so users don't clone or
+ * build. Pure Node stdlib, no dependencies.
+ */
+
+const fs = require("fs/promises");
+const path = require("path");
+const os = require("os");
+const readline = require("readline/promises");
+const { parseArgs } = require("util");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const DIST_DIR = path.join(PKG_ROOT, "dist");
+const SKILL_NAME = "four-leaf-coach";
+const MCP_CMD = "claude mcp add --transport http four-leaf https://four-leaf.ai/api/mcp";
+
+// Read the version straight from package.json so it never drifts.
+const VERSION = require(path.join(PKG_ROOT, "package.json")).version;
+
+const TOOLS = ["claude-code", "cursor", "codex", "github-copilot"];
+
+const TOOL_LABELS = {
+  "claude-code": "Claude Code",
+  cursor: "Cursor",
+  codex: "OpenAI Codex CLI",
+  "github-copilot": "GitHub Copilot",
+};
+
+/* ----------------------------- small helpers ----------------------------- */
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Recursively copy a directory tree. */
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(from, to);
+    } else if (entry.isFile()) {
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+/** Copy a single file, creating parent directories as needed. */
+async function copyFileTo(src, dest) {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+}
+
+function tilde(p) {
+  const home = os.homedir();
+  return p.startsWith(home) ? p.replace(home, "~") : p;
+}
+
+function bail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+/* ------------------------------ detection -------------------------------- */
+
+/**
+ * Inspect cwd and $HOME for signals of each tool. Returns an array of
+ * { tool, scope, reason } candidates, most specific first.
+ */
+async function detectTools(cwd, home) {
+  const candidates = [];
+
+  if (await pathExists(path.join(cwd, ".cursor"))) {
+    candidates.push({ tool: "cursor", scope: "project", reason: ".cursor/ in this directory" });
+  }
+  if (await pathExists(path.join(cwd, ".claude"))) {
+    candidates.push({ tool: "claude-code", scope: "project", reason: ".claude/ in this directory" });
+  }
+  if (await pathExists(path.join(home, ".claude", "skills"))) {
+    candidates.push({ tool: "claude-code", scope: "global", reason: "~/.claude/skills/ exists" });
+  }
+  if (await pathExists(path.join(cwd, "AGENTS.md"))) {
+    candidates.push({ tool: "codex", scope: "project", reason: "AGENTS.md in this directory" });
+  }
+  if (await pathExists(path.join(cwd, ".github"))) {
+    candidates.push({ tool: "github-copilot", scope: "project", reason: ".github/ in this directory" });
+  }
+
+  return candidates;
+}
+
+/* ------------------------------- prompts --------------------------------- */
+
+async function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(question);
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function confirm(question) {
+  const answer = (await ask(`${question} [y/N] `)).toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+/** Present a numbered menu and return the chosen item. */
+async function choose(label, items, renderItem) {
+  console.log(`\n${label}`);
+  items.forEach((item, i) => {
+    console.log(`  ${i + 1}) ${renderItem(item)}`);
+  });
+  while (true) {
+    const raw = await ask(`Choose 1-${items.length}: `);
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 1 && n <= items.length) {
+      return items[n - 1];
+    }
+    console.log("Enter a number from the list.");
+  }
+}
+
+/* ----------------------------- resolve target ---------------------------- */
+
+/**
+ * Given the chosen tool, scope, and base directory, return the install plan:
+ * { tool, scope, source, kind, target, existing }.
+ *   kind: "dir" (copy a tree) or "tree+entry" (codex) or "file" (copilot)
+ */
+async function buildPlan(tool, scope, base) {
+  switch (tool) {
+    case "claude-code": {
+      const source = path.join(DIST_DIR, "claude-code", ".claude", "skills", SKILL_NAME);
+      const target = path.join(base, ".claude", "skills", SKILL_NAME);
+      return { tool, scope, kind: "skill-dir", source, target, existing: await pathExists(target) };
+    }
+    case "cursor": {
+      const source = path.join(DIST_DIR, "cursor", ".cursor", "skills", SKILL_NAME);
+      const target = path.join(base, ".cursor", "skills", SKILL_NAME);
+      return { tool, scope, kind: "skill-dir", source, target, existing: await pathExists(target) };
+    }
+    case "codex": {
+      const source = path.join(DIST_DIR, "codex");
+      const agents = path.join(base, "AGENTS.md");
+      return {
+        tool,
+        scope,
+        kind: "codex",
+        source,
+        target: base,
+        agentsPath: agents,
+        existing: await pathExists(agents),
+      };
+    }
+    case "github-copilot": {
+      const source = path.join(DIST_DIR, "github", ".github", "copilot-instructions.md");
+      const target = path.join(base, ".github", "copilot-instructions.md");
+      return { tool, scope, kind: "file", source, target, existing: await pathExists(target) };
+    }
+    default:
+      bail(`unknown tool "${tool}". Supported: ${TOOLS.join(", ")}`);
+  }
+}
+
+/* -------------------------------- install -------------------------------- */
+
+async function runInstall(plan, { dryRun }) {
+  const tag = dryRun ? "[dry-run] " : "";
+
+  switch (plan.kind) {
+    case "skill-dir": {
+      console.log(`${tag}Write Skill to ${tilde(plan.target)}/`);
+      if (!dryRun) {
+        await fs.rm(plan.target, { recursive: true, force: true });
+        await copyDir(plan.source, plan.target);
+      }
+      break;
+    }
+    case "codex": {
+      console.log(`${tag}Write ${tilde(plan.agentsPath)}`);
+      console.log(`${tag}Write ${tilde(path.join(plan.target, "references"))}/`);
+      if (!dryRun) {
+        await copyFileTo(path.join(plan.source, "AGENTS.md"), plan.agentsPath);
+        await copyDir(path.join(plan.source, "references"), path.join(plan.target, "references"));
+      }
+      break;
+    }
+    case "file": {
+      console.log(`${tag}Write ${tilde(plan.target)}`);
+      if (!dryRun) {
+        await copyFileTo(plan.source, plan.target);
+      }
+      break;
+    }
+    default:
+      bail(`internal error: unknown plan kind "${plan.kind}"`);
+  }
+}
+
+function printNextSteps(plan) {
+  const scopeNote = plan.tool === "claude-code" ? ` (${plan.scope})` : "";
+  console.log(`\nInstalled ${SKILL_NAME} for ${TOOL_LABELS[plan.tool]}${scopeNote}.`);
+
+  console.log("\nNext step: install the Four-Leaf MCP for live data.");
+  console.log(`  ${MCP_CMD}`);
+
+  if (plan.tool === "claude-code") {
+    console.log("\nThen type /kickoff in Claude to start.");
+  } else if (plan.tool === "cursor") {
+    console.log("\nEnable Agent Skills (Settings, Rules, Agent Skills on the Nightly channel), then type /kickoff.");
+  } else if (plan.tool === "codex") {
+    console.log("\nRun Codex from this directory, then type kickoff to start.");
+  } else if (plan.tool === "github-copilot") {
+    console.log("\nCopilot picks up .github/copilot-instructions.md automatically. Ask it to run kickoff.");
+  }
+}
+
+/* --------------------------------- add ----------------------------------- */
+
+async function cmdAdd(opts) {
+  if (!(await pathExists(DIST_DIR))) {
+    bail("dist/ not found. If you're running from a clone, run `npm run build` first.");
+  }
+
+  const cwd = process.cwd();
+  const home = os.homedir();
+
+  if (opts.tool && !TOOLS.includes(opts.tool)) {
+    bail(`unknown --tool "${opts.tool}". Supported: ${TOOLS.join(", ")}`);
+  }
+  if (opts.scope && !["project", "global"].includes(opts.scope)) {
+    bail(`unknown --scope "${opts.scope}". Use project or global.`);
+  }
+
+  // 1. Decide the tool.
+  let tool = opts.tool;
+  let scope = opts.scope;
+
+  if (!tool) {
+    const candidates = await detectTools(cwd, home);
+    if (candidates.length === 1) {
+      tool = candidates[0].tool;
+      scope = scope || candidates[0].scope;
+      console.log(`Detected ${TOOL_LABELS[tool]} (${candidates[0].reason}).`);
+    } else if (candidates.length > 1) {
+      const picked = await choose(
+        "Found more than one tool. Which one?",
+        candidates,
+        (c) => `${TOOL_LABELS[c.tool]} (${c.reason})`
+      );
+      tool = picked.tool;
+      scope = scope || picked.scope;
+    } else {
+      const picked = await choose(
+        "No tool detected here. Which one are you installing for?",
+        TOOLS.map((t) => ({ tool: t })),
+        (c) => TOOL_LABELS[c.tool] + (c.tool === "claude-code" ? " (default)" : "")
+      );
+      tool = picked.tool;
+    }
+  }
+
+  // 2. Decide scope + base directory.
+  let base;
+  if (opts.dir) {
+    // Explicit base directory. The tool's standard subpath is appended.
+    base = path.resolve(opts.dir);
+    scope = scope || (tool === "claude-code" ? "global" : "project");
+  } else if (tool === "claude-code") {
+    if (!scope) {
+      const hasProject = await pathExists(path.join(cwd, ".claude"));
+      const hasGlobal = await pathExists(path.join(home, ".claude"));
+      if (hasProject && hasGlobal) {
+        const picked = await choose(
+          "Install Claude Code Skill where?",
+          [
+            { scope: "global", where: tilde(path.join(home, ".claude", "skills")) },
+            { scope: "project", where: path.join(cwd, ".claude", "skills") },
+          ],
+          (c) => `${c.scope} (${c.where})`
+        );
+        scope = picked.scope;
+      } else if (hasProject) {
+        scope = "project";
+      } else {
+        scope = "global";
+      }
+    }
+    base = scope === "global" ? home : cwd;
+  } else {
+    scope = scope || "project";
+    base = cwd;
+  }
+
+  // 3. Build the plan and handle overwrites.
+  const plan = await buildPlan(tool, scope, base);
+
+  if (plan.existing && !opts.force && !opts.yes && !opts.dryRun) {
+    const what =
+      plan.kind === "skill-dir"
+        ? `${tilde(plan.target)}/`
+        : plan.kind === "codex"
+        ? tilde(plan.agentsPath)
+        : tilde(plan.target);
+    const ok = await confirm(`${what} already exists. Replace?`);
+    if (!ok) {
+      console.log("Cancelled. Nothing was written.");
+      return;
+    }
+  } else if (plan.existing && opts.dryRun) {
+    console.log(`[dry-run] ${tilde(plan.target)} already exists and would be replaced.`);
+  }
+
+  // 4. Install.
+  await runInstall(plan, { dryRun: opts.dryRun });
+  printNextSteps(plan);
+}
+
+/* --------------------------------- list ---------------------------------- */
+
+async function cmdList() {
+  const cwd = process.cwd();
+  const home = os.homedir();
+  const detected = await detectTools(cwd, home);
+  const byTool = new Set(detected.map((c) => c.tool));
+
+  console.log("Supported tools:\n");
+  for (const tool of TOOLS) {
+    const hits = detected.filter((c) => c.tool === tool);
+    const status = byTool.has(tool)
+      ? `detected (${hits.map((h) => h.reason).join(", ")})`
+      : "not detected here";
+    console.log(`  ${TOOL_LABELS[tool].padEnd(18)} ${status}`);
+  }
+  console.log(`\nInstall with: four-leaf-coach add [--tool <name>]`);
+}
+
+/* --------------------------------- usage --------------------------------- */
+
+function printUsage() {
+  console.log(`four-leaf-coach ${VERSION}
+
+Install the four-leaf-coach Skill into your AI tool.
+
+Usage:
+  four-leaf-coach add [options]    Detect your tool and install the Skill
+  four-leaf-coach list             Show supported tools and what's detected here
+
+Options for add:
+  --tool <name>     claude-code | cursor | codex | github-copilot
+  --scope <s>       project | global   (Claude Code only; default global)
+  --dir <path>      Install under this base directory instead of detecting
+  --yes, -y         Skip confirmation prompts
+  --force           Overwrite existing files without asking
+  --dry-run         Print what would happen, write nothing
+
+Other:
+  --help, -h        Show this help
+  --version         Print the version
+
+After installing, add the Four-Leaf MCP for live data:
+  ${MCP_CMD}`);
+}
+
+/* --------------------------------- main ---------------------------------- */
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      tool: { type: "string" },
+      scope: { type: "string" },
+      dir: { type: "string" },
+      yes: { type: "boolean", short: "y", default: false },
+      force: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", default: false },
+    },
+  });
+
+  if (values.version) {
+    console.log(VERSION);
+    return;
+  }
+
+  const command = positionals[0];
+
+  if (values.help || command === "help" || !command) {
+    printUsage();
+    // No command at all is a usage error; explicit --help/help is success.
+    if (!command && !values.help) process.exitCode = 1;
+    return;
+  }
+
+  switch (command) {
+    case "add":
+      await cmdAdd({
+        tool: values.tool,
+        scope: values.scope,
+        dir: values.dir,
+        yes: values.yes,
+        force: values.force,
+        dryRun: values["dry-run"],
+      });
+      break;
+    case "list":
+      await cmdList();
+      break;
+    default:
+      console.error(`Unknown command "${command}".\n`);
+      printUsage();
+      process.exitCode = 1;
+  }
+}
+
+main().catch((err) => bail(err.stack || String(err)));