@fluentcommerce/ai-skills 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,1973 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  mkdirSync,
+  cpSync,
+  rmSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, dirname, basename, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = join(__dirname, "..");
+const CONTENT_ROOT = join(PACKAGE_ROOT, "content");
+
+const CLAUDE_DIR = process.env.FLUENT_AI_SKILLS_HOME || join(homedir(), ".claude");
+const AGENTS_DIR = join(CLAUDE_DIR, "agents");
+const SKILLS_DIR = join(CLAUDE_DIR, "skills");
+
+const pkg = readJson(join(PACKAGE_ROOT, "package.json")) || { version: "0.0.0" };
+const metadata = readJson(join(PACKAGE_ROOT, "metadata.json")) || {};
+
+const GROUP_ALIASES = {
+  mcp: "mcp-extn",
+  extn: "mcp-extn",
+  extension: "mcp-extn",
+  "mcp-core": "mcp-official",
+  official: "mcp-official",
+};
+
+const SUPPORTED_TARGETS = ["claude", "cursor", "copilot", "vscode", "windsurf", "codex", "gemini"];
+const TARGET_ALIASES = {
+  vscode: "copilot",
+};
+
+const GENERATED_MARKER = "<!-- Generated by fluent-ai-skills. -->";
+const MANAGED_BLOCK_START = "<!-- fluent-ai-skills:start -->";
+const MANAGED_BLOCK_END = "<!-- fluent-ai-skills:end -->";
+const DEFAULT_MCP_EXTN_REPO = "https://bitbucket.org/fluentcommerce/fluent-mcp-extn.git";
+const DEFAULT_MCP_EXTN_DIR = "fluent-mcp-extn";
+const DEFAULT_FLOW_REPORT_DIR = ".fluent-ai-skills";
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function log(message = "") {
+  console.log(message);
+}
+
+function logOk(message) {
+  console.log(`  + ${message}`);
+}
+
+function logWarn(message) {
+  console.log(`  ! ${message}`);
+}
+
+function logErr(message) {
+  console.error(`  x ${message}`);
+}
+
+function runCommand(command, args, cwd) {
+  const useWindowsShell = process.platform === "win32";
+  const result = useWindowsShell
+    ? spawnSync(formatCommand(command, args), {
+        cwd,
+        stdio: "inherit",
+        shell: true,
+        env: process.env,
+      })
+    : spawnSync(command, args, {
+        cwd,
+        stdio: "inherit",
+        shell: false,
+        env: process.env,
+      });
+
+  if (result.error) {
+    throw new Error(`Failed to run '${command}': ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`Command failed (${result.status}): ${command} ${args.join(" ")}`);
+  }
+}
+
+function quoteArg(arg) {
+  const value = String(arg ?? "");
+  if (value.length === 0) {
+    return '""';
+  }
+  return /\s/.test(value) ? JSON.stringify(value) : value;
+}
+
+function formatCommand(command, args = []) {
+  return [command, ...args.map((arg) => quoteArg(arg))].join(" ");
+}
+
+function truncateText(text, maxLength = 12000) {
+  if (!text) return "";
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength)}\n...[truncated ${text.length - maxLength} chars]`;
+}
+
+function redactSecrets(text) {
+  if (!text) return "";
+  const rules = [
+    /(client[_-]?secret\s*[:=]\s*)([^\s"']+)/gi,
+    /(password\s*[:=]\s*)([^\s"']+)/gi,
+    /(access[_-]?token\s*[:=]\s*)([^\s"']+)/gi,
+    /(authorization\s*:\s*bearer\s+)([^\s]+)/gi,
+  ];
+
+  let redacted = text;
+  for (const pattern of rules) {
+    redacted = redacted.replace(pattern, "$1***");
+  }
+  return redacted;
+}
+
+function sanitizeOutput(text) {
+  return truncateText(redactSecrets((text || "").trim()));
+}
+
+function runCommandCapture(command, args, cwd) {
+  const startedAt = Date.now();
+  const useWindowsShell = process.platform === "win32";
+  const result = useWindowsShell
+    ? spawnSync(formatCommand(command, args), {
+        cwd,
+        stdio: "pipe",
+        shell: true,
+        env: process.env,
+        encoding: "utf-8",
+      })
+    : spawnSync(command, args, {
+        cwd,
+        stdio: "pipe",
+        shell: false,
+        env: process.env,
+        encoding: "utf-8",
+      });
+
+  const durationMs = Date.now() - startedAt;
+  const errorText = result.error ? result.error.message : "";
+  const stderr = [result.stderr || "", errorText].filter(Boolean).join("\n");
+
+  return {
+    command,
+    args,
+    commandText: formatCommand(command, args),
+    cwd,
+    durationMs,
+    exitCode: Number.isInteger(result.status) ? result.status : -1,
+    stdout: sanitizeOutput(result.stdout || ""),
+    stderr: sanitizeOutput(stderr),
+  };
+}
+
+function ensureDir(path) {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+}
+
+function normalizeNewlines(text) {
+  return text.replace(/\r\n/g, "\n");
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function managedBlockRegex() {
+  return new RegExp(
+    `${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}\\n?`,
+    "g"
+  );
+}
+
+function stripManagedBlocks(text) {
+  const normalized = normalizeNewlines(text);
+  return normalized.replace(managedBlockRegex(), "").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function hasManagedBlock(text) {
+  const normalized = normalizeNewlines(text);
+  return normalized.includes(MANAGED_BLOCK_START) && normalized.includes(MANAGED_BLOCK_END);
+}
+
+function buildManagedBlock(content) {
+  const body = content.trimEnd();
+  return [
+    MANAGED_BLOCK_START,
+    GENERATED_MARKER,
+    "",
+    body,
+    MANAGED_BLOCK_END,
+  ].join("\n");
+}
+
+function writeManagedBlockFile(path, content) {
+  const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  const base = stripManagedBlocks(existing);
+  const managed = buildManagedBlock(content);
+
+  const parts = [];
+  if (base.length > 0) {
+    parts.push(base);
+  }
+  parts.push(managed);
+
+  writeFileSync(path, `${parts.join("\n\n").trimEnd()}\n`);
+}
+
+function removeManagedBlockFile(path) {
+  if (!existsSync(path)) {
+    return "missing";
+  }
+
+  const existing = readFileSync(path, "utf-8");
+  if (!hasManagedBlock(existing)) {
+    return "not-managed";
+  }
+
+  const stripped = stripManagedBlocks(existing);
+  if (stripped.length === 0) {
+    rmSync(path, { force: true });
+    return "removed-file";
+  }
+
+  writeFileSync(path, `${stripped}\n`);
+  return "removed-block";
+}
+
+function listEntries(path) {
+  if (!existsSync(path)) {
+    return [];
+  }
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => !entry.name.startsWith("."))
+    .map((entry) => ({
+      name: entry.name,
+      type: entry.isDirectory() ? "dir" : "file",
+    }));
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: text };
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+    }
+  }
+  return { meta, body: match[2] };
+}
+
+/** Ensure a name has the fluent- prefix exactly once. */
+function fluentName(name) {
+  return name.startsWith("fluent-") ? name : `fluent-${name}`;
+}
+
+/** Convert a logical name into a cross-platform safe filename stem. */
+function safeFileStem(name) {
+  return fluentName(name)
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Walk a group's agents/ and skills/ directories and collect all .md files
+ * with their parsed frontmatter. Skips non-markdown files (.json, .py, etc).
+ */
+function collectMarkdownFiles(group) {
+  const files = [];
+
+  function walkDir(dir, prefix) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".md")) {
+        // In skill directories, only recognize SKILL.md as the skill entry point.
+        // Other .md files (e.g., PLAN_TEMPLATE.md) are supporting content, not skills.
+        if (prefix === "skill" && entry.name !== "SKILL.md") continue;
+        const raw = readFileSync(full, "utf-8");
+        const { meta, body } = parseFrontmatter(raw);
+        // For SKILL.md files without frontmatter name, use parent directory as a stable fallback.
+        const fallbackName = entry.name === "SKILL.md"
+          ? basename(dirname(full))
+          : entry.name.replace(/\.md$/, "");
+        const name = meta.name || fallbackName;
+        files.push({ name, meta, body, path: full, prefix });
+      } else if (entry.isDirectory()) {
+        walkDir(full, prefix);
+      }
+    }
+  }
+
+  walkDir(group.agentsRoot, "agent");
+  walkDir(group.skillsRoot, "skill");
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Group discovery and resolution (shared across all targets)
+// ---------------------------------------------------------------------------
+
+function discoverGroups() {
+  if (!existsSync(CONTENT_ROOT)) {
+    return [];
+  }
+
+  const metadataGroups = new Map();
+  if (Array.isArray(metadata.groups)) {
+    for (const group of metadata.groups) {
+      if (group && group.name) {
+        metadataGroups.set(group.name, group);
+      }
+    }
+  } else if (metadata.groups && typeof metadata.groups === "object") {
+    for (const [name, group] of Object.entries(metadata.groups)) {
+      metadataGroups.set(name, { name, ...group });
+    }
+  }
+
+  const names = readdirSync(CONTENT_ROOT, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+
+  return names.map((name) => {
+    const groupRoot = join(CONTENT_ROOT, name);
+    const agentsRoot = join(groupRoot, "agents");
+    const skillsRoot = join(groupRoot, "skills");
+    const meta = metadataGroups.get(name) || {};
+
+    return {
+      name,
+      description: meta.description || `Fluent skills group '${name}'`,
+      root: groupRoot,
+      agentsRoot,
+      skillsRoot,
+      agents: listEntries(agentsRoot),
+      skills: listEntries(skillsRoot),
+    };
+  });
+}
+
+function resolveGroups(requested, groups) {
+  const allNames = groups.map((group) => group.name);
+  const normalizedRequested = requested.map((name) => GROUP_ALIASES[name] || name);
+
+  if (normalizedRequested.length === 0 || normalizedRequested.includes("all")) {
+    return groups;
+  }
+
+  const requestedUnique = [...new Set(normalizedRequested)];
+  const unknown = requestedUnique.filter((name) => !allNames.includes(name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown group(s): ${unknown.join(", ")}. Available groups: ${allNames.join(", ")}`
+    );
+  }
+
+  return groups.filter((group) => requestedUnique.includes(group.name));
+}
+
+// ---------------------------------------------------------------------------
+// Target: Claude Code (~/.claude/agents + ~/.claude/skills)
+// ---------------------------------------------------------------------------
+
+function copyEntry(src, dest, type) {
+  if (type === "dir") {
+    cpSync(src, dest, { recursive: true, force: true });
+  } else {
+    cpSync(src, dest, { force: true });
+  }
+}
+
+function removeEntry(path, type) {
+  if (type === "dir") {
+    rmSync(path, { recursive: true, force: true });
+  } else {
+    rmSync(path, { force: true });
+  }
+}
+
+function installClaude(groups) {
+  log("");
+  log("Installing for Claude Code...");
+  log("============================");
+  log("");
+
+  ensureDir(AGENTS_DIR);
+  ensureDir(SKILLS_DIR);
+
+  let copiedAgents = 0;
+  let copiedSkills = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+
+    for (const entry of group.agents) {
+      const src = join(group.agentsRoot, entry.name);
+      const dest = join(AGENTS_DIR, entry.name);
+      copyEntry(src, dest, entry.type);
+      copiedAgents += 1;
+      logOk(`agent: ${entry.name}`);
+    }
+
+    for (const entry of group.skills) {
+      const src = join(group.skillsRoot, entry.name);
+      const dest = join(SKILLS_DIR, entry.name);
+      copyEntry(src, dest, entry.type);
+      copiedSkills += 1;
+      logOk(`skill: ${entry.name}`);
+    }
+  }
+
+  log("");
+  log(`Installed to: ${CLAUDE_DIR}`);
+  log(`Components: ${copiedAgents} agent(s), ${copiedSkills} skill(s)`);
+  return copiedAgents + copiedSkills;
+}
+
+function uninstallClaude(groups) {
+  let removed = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+
+    for (const entry of group.agents) {
+      const dest = join(AGENTS_DIR, entry.name);
+      if (existsSync(dest)) {
+        removeEntry(dest, entry.type);
+        removed++;
+        logOk(`removed agent: ${entry.name}`);
+      } else {
+        logWarn(`agent not found: ${entry.name}`);
+      }
+    }
+
+    for (const entry of group.skills) {
+      const dest = join(SKILLS_DIR, entry.name);
+      if (existsSync(dest)) {
+        removeEntry(dest, entry.type);
+        removed++;
+        logOk(`removed skill: ${entry.name}`);
+      } else {
+        logWarn(`skill not found: ${entry.name}`);
+      }
+    }
+  }
+
+  return removed;
+}
+
+function statusClaude(groups) {
+  let fullyInstalled = 0;
+  let partial = 0;
+  let missing = 0;
+
+  for (const group of groups) {
+    const checks = [
+      ...group.agents.map((e) => ({
+        kind: "agent",
+        name: e.name,
+        installed: existsSync(join(AGENTS_DIR, e.name)),
+      })),
+      ...group.skills.map((e) => ({
+        kind: "skill",
+        name: e.name,
+        installed: existsSync(join(SKILLS_DIR, e.name)),
+      })),
+    ];
+    const installedCount = checks.filter((c) => c.installed).length;
+    const total = checks.length;
+
+    let state = "missing";
+    if (installedCount === total && total > 0) {
+      state = "installed";
+      fullyInstalled++;
+    } else if (installedCount > 0) {
+      state = "partial";
+      partial++;
+    } else {
+      missing++;
+    }
+
+    log(`Group: ${group.name} (${state}) ${installedCount}/${total}`);
+    for (const c of checks) {
+      if (c.installed) logOk(`${c.kind}: ${c.name}`);
+      else logWarn(`${c.kind}: ${c.name}`);
+    }
+    log("");
+  }
+
+  log(`Summary: ${fullyInstalled} installed, ${partial} partial, ${missing} missing`);
+  return { fullyInstalled, partial, missing };
+}
+
+// ---------------------------------------------------------------------------
+// Target: Cursor (.cursor/rules/*.mdc)
+// ---------------------------------------------------------------------------
+
+function cursorRulesDir() {
+  return join(process.cwd(), ".cursor", "rules");
+}
+
+function installCursor(groups) {
+  const rulesDir = cursorRulesDir();
+  ensureDir(rulesDir);
+  let count = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      const fileName = `${safeFileStem(f.name)}.mdc`;
+      const mdc = [
+        "---",
+        `description: ${f.meta.description || f.name}`,
+        "alwaysApply: true",
+        "---",
+        "",
+        GENERATED_MARKER,
+        "",
+        f.body,
+      ].join("\n");
+      const dest = join(rulesDir, fileName);
+      writeFileSync(dest, mdc);
+      count++;
+      logOk(`${f.prefix}: ${fileName}`);
+    }
+  }
+
+  log("");
+  log(`Installed to: ${rulesDir}`);
+  log(`Rules created: ${count}`);
+  return count;
+}
+
+function uninstallCursor(groups) {
+  const rulesDir = cursorRulesDir();
+  let removed = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      const fileName = `${safeFileStem(f.name)}.mdc`;
+      const dest = join(rulesDir, fileName);
+      if (existsSync(dest)) {
+        rmSync(dest);
+        removed++;
+        logOk(`removed: ${fileName}`);
+      } else {
+        logWarn(`not found: ${fileName}`);
+      }
+    }
+  }
+
+  return removed;
+}
+
+function statusCursor(groups) {
+  const rulesDir = cursorRulesDir();
+  let installed = 0;
+  let missing = 0;
+
+  for (const group of groups) {
+    const files = collectMarkdownFiles(group);
+    const checks = files.map((f) => ({
+      name: `${safeFileStem(f.name)}.mdc`,
+      exists: existsSync(join(rulesDir, `${safeFileStem(f.name)}.mdc`)),
+    }));
+    const found = checks.filter((c) => c.exists).length;
+    const total = checks.length;
+
+    log(`Group: ${group.name} (${found === total && total > 0 ? "installed" : found > 0 ? "partial" : "missing"}) ${found}/${total}`);
+    for (const c of checks) {
+      if (c.exists) { logOk(c.name); installed++; }
+      else { logWarn(c.name); missing++; }
+    }
+    log("");
+  }
+
+  log(`Summary: ${installed} installed, ${missing} missing`);
+  return { installed, missing };
+}
+
+// ---------------------------------------------------------------------------
+// Target: GitHub Copilot (.github/copilot-instructions.md)
+// ---------------------------------------------------------------------------
+
+function copilotFile() {
+  return join(process.cwd(), ".github", "copilot-instructions.md");
+}
+
+function buildGroupedMarkdown(groups) {
+  const lines = [];
+  let count = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    lines.push(`## Group: ${group.name}`, "");
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      lines.push(`### ${f.meta.name || f.name}`, "", f.body.trim(), "");
+      count++;
+      logOk(`${f.prefix}: ${f.meta.name || f.name}`);
+    }
+  }
+
+  return { content: lines.join("\n").trim(), count };
+}
+
+function installCopilot(groups) {
+  const dest = copilotFile();
+  ensureDir(dirname(dest));
+
+  const { content, count } = buildGroupedMarkdown(groups);
+  writeManagedBlockFile(dest, content);
+
+  log("");
+  log(`Installed to: ${dest}`);
+  log(`Sections written: ${count}`);
+  return count;
+}
+
+function uninstallCopilot() {
+  const dest = copilotFile();
+  const result = removeManagedBlockFile(dest);
+
+  if (result === "missing") {
+    logWarn(".github/copilot-instructions.md not found");
+    return 0;
+  }
+  if (result === "not-managed") {
+    logWarn(".github/copilot-instructions.md exists but has no managed block");
+    return 0;
+  }
+  if (result === "removed-file") {
+    logOk("removed file: .github/copilot-instructions.md");
+    return 1;
+  }
+
+  logOk("removed managed block from: .github/copilot-instructions.md");
+  return 1;
+}
+
+function statusCopilot() {
+  const dest = copilotFile();
+  if (!existsSync(dest)) {
+    log(".github/copilot-instructions.md (missing)");
+    return { installed: 0, missing: 1 };
+  }
+
+  const content = readFileSync(dest, "utf-8");
+  const installed = hasManagedBlock(content);
+  if (installed) {
+    log(".github/copilot-instructions.md (installed)");
+    return { installed: 1, missing: 0 };
+  }
+
+  log(".github/copilot-instructions.md (exists, not managed)");
+  return { installed: 0, missing: 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Target: Windsurf (single .windsurfrules file)
+// ---------------------------------------------------------------------------
+
+function windsurfFile() {
+  return join(process.cwd(), ".windsurfrules");
+}
+
+function installWindsurf(groups) {
+  const sections = [];
+  let count = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      sections.push(`## ${f.meta.name || f.name}`, "", f.body, "");
+      count++;
+      logOk(`${f.prefix}: ${f.name}`);
+    }
+  }
+
+  const dest = windsurfFile();
+  writeManagedBlockFile(dest, sections.join("\n").trim());
+  log("");
+  log(`Installed to: ${dest}`);
+  log(`Sections: ${count}`);
+  return count;
+}
+
+function uninstallWindsurf() {
+  const dest = windsurfFile();
+  const result = removeManagedBlockFile(dest);
+
+  if (result === "missing") {
+    logWarn(".windsurfrules not found");
+    return 0;
+  }
+  if (result === "not-managed") {
+    logWarn(".windsurfrules exists but has no managed block");
+    return 0;
+  }
+  if (result === "removed-file") {
+    logOk("removed file: .windsurfrules");
+    return 1;
+  }
+
+  logOk("removed managed block from: .windsurfrules");
+  return 1;
+}
+
+function statusWindsurf() {
+  const dest = windsurfFile();
+  if (!existsSync(dest)) {
+    log(".windsurfrules (missing)");
+    return { installed: 0, missing: 1 };
+  }
+
+  const content = readFileSync(dest, "utf-8");
+  const installed = hasManagedBlock(content);
+  if (installed) {
+    log(".windsurfrules (installed)");
+    return { installed: 1, missing: 0 };
+  }
+
+  log(".windsurfrules (exists, not managed)");
+  return { installed: 0, missing: 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Target: Codex (single AGENTS.md file)
+// ---------------------------------------------------------------------------
+
+function codexFile() {
+  return join(process.cwd(), "AGENTS.md");
+}
+
+function installCodex(groups) {
+  const sections = ["# Fluent Commerce AI Skills", ""];
+  let count = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      sections.push(`## ${f.meta.name || f.name}`, "", f.body, "");
+      count++;
+      logOk(`${f.prefix}: ${f.name}`);
+    }
+  }
+
+  const dest = codexFile();
+  writeManagedBlockFile(dest, sections.join("\n").trim());
+  log("");
+  log(`Installed to: ${dest}`);
+  log(`Sections: ${count}`);
+  return count;
+}
+
+function uninstallCodex() {
+  const dest = codexFile();
+  const result = removeManagedBlockFile(dest);
+
+  if (result === "missing") {
+    logWarn("AGENTS.md not found");
+    return 0;
+  }
+  if (result === "not-managed") {
+    logWarn("AGENTS.md exists but has no managed block");
+    return 0;
+  }
+  if (result === "removed-file") {
+    logOk("removed file: AGENTS.md");
+    return 1;
+  }
+
+  logOk("removed managed block from: AGENTS.md");
+  return 1;
+}
+
+function statusCodex() {
+  const dest = codexFile();
+  if (!existsSync(dest)) {
+    log("AGENTS.md (missing)");
+    return { installed: 0, missing: 1 };
+  }
+
+  const content = readFileSync(dest, "utf-8");
+  const installed = hasManagedBlock(content);
+  if (installed) {
+    log("AGENTS.md (installed)");
+    return { installed: 1, missing: 0 };
+  }
+
+  log("AGENTS.md (exists, not managed)");
+  return { installed: 0, missing: 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Target: Gemini (single GEMINI.md file)
+// ---------------------------------------------------------------------------
+
+function geminiFile() {
+  return join(process.cwd(), "GEMINI.md");
+}
+
+function installGemini(groups) {
+  const sections = ["# Fluent Commerce AI Skills", ""];
+  let count = 0;
+
+  for (const group of groups) {
+    log(`Group: ${group.name}`);
+    const files = collectMarkdownFiles(group);
+    for (const f of files) {
+      sections.push(`## ${f.meta.name || f.name}`, "", f.body, "");
+      count++;
+      logOk(`${f.prefix}: ${f.name}`);
+    }
+  }
+
+  const dest = geminiFile();
+  writeManagedBlockFile(dest, sections.join("\n").trim());
+  log("");
+  log(`Installed to: ${dest}`);
+  log(`Sections: ${count}`);
+  return count;
+}
+
+function uninstallGemini() {
+  const dest = geminiFile();
+  const result = removeManagedBlockFile(dest);
+
+  if (result === "missing") {
+    logWarn("GEMINI.md not found");
+    return 0;
+  }
+  if (result === "not-managed") {
+    logWarn("GEMINI.md exists but has no managed block");
+    return 0;
+  }
+  if (result === "removed-file") {
+    logOk("removed file: GEMINI.md");
+    return 1;
+  }
+
+  logOk("removed managed block from: GEMINI.md");
+  return 1;
+}
+
+function statusGemini() {
+  const dest = geminiFile();
+  if (!existsSync(dest)) {
+    log("GEMINI.md (missing)");
+    return { installed: 0, missing: 1 };
+  }
+
+  const content = readFileSync(dest, "utf-8");
+  const installed = hasManagedBlock(content);
+  if (installed) {
+    log("GEMINI.md (installed)");
+    return { installed: 1, missing: 0 };
+  }
+
+  log("GEMINI.md (exists, not managed)");
+  return { installed: 0, missing: 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Target dispatch
+// ---------------------------------------------------------------------------
+
+function targetInstall(target, groups) {
+  switch (target) {
+    case "claude":
+      return installClaude(groups);
+    case "cursor":
+      return installCursor(groups);
+    case "copilot":
+      return installCopilot(groups);
+    case "windsurf":
+      return installWindsurf(groups);
+    case "codex":
+      return installCodex(groups);
+    case "gemini":
+      return installGemini(groups);
+    default:
+      throw new Error(`Unknown target: ${target}`);
+  }
+}
+
+function targetUninstall(target, groups) {
+  switch (target) {
+    case "claude":
+      return uninstallClaude(groups);
+    case "cursor":
+      return uninstallCursor(groups);
+    case "copilot":
+      return uninstallCopilot();
+    case "windsurf":
+      return uninstallWindsurf();
+    case "codex":
+      return uninstallCodex();
+    case "gemini":
+      return uninstallGemini();
+    default:
+      throw new Error(`Unknown target: ${target}`);
+  }
+}
+
+function targetStatus(target, groups) {
+  switch (target) {
+    case "claude":
+      return statusClaude(groups);
+    case "cursor":
+      return statusCursor(groups);
+    case "copilot":
+      return statusCopilot();
+    case "windsurf":
+      return statusWindsurf();
+    case "codex":
+      return statusCodex();
+    case "gemini":
+      return statusGemini();
+    default:
+      throw new Error(`Unknown target: ${target}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP bootstrap (.mcp.json + optional extn source download/build)
+// ---------------------------------------------------------------------------
+
+function toPosixPath(path) {
+  return path.replace(/\\/g, "/");
+}
+
+function readJsonObjectOrDefault(path, fallback) {
+  if (!existsSync(path)) {
+    return fallback;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("JSON root must be an object");
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Failed to parse ${path}: ${error.message}`);
+  }
+}
+
+function mergeServerConfig(existing, desired) {
+  const safeExisting = existing && typeof existing === "object" && !Array.isArray(existing)
+    ? existing
+    : {};
+  const existingEnv = safeExisting.env && typeof safeExisting.env === "object" && !Array.isArray(safeExisting.env)
+    ? safeExisting.env
+    : {};
+  const desiredEnv = desired.env && typeof desired.env === "object" ? desired.env : {};
+
+  return {
+    ...safeExisting,
+    ...desired,
+    type: desired.type,
+    command: desired.command,
+    args: desired.args,
+    env: { ...desiredEnv, ...existingEnv },
+  };
+}
+
+function parseMcpSetupArgs(args) {
+  const options = {
+    installExtnSource: false,
+    skipBuild: false,
+    extnDir: DEFAULT_MCP_EXTN_DIR,
+    extnRepo: DEFAULT_MCP_EXTN_REPO,
+    profile: "",
+    profileRetailer: "",
+    officialServerName: "fluent-mcp",
+    extnServerName: "fluent-mcp-extn",
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case "--install-extn-source":
+      case "--with-extn-source":
+      case "--download-extn-source":
+        options.installExtnSource = true;
+        break;
+      case "--skip-build":
+        options.skipBuild = true;
+        break;
+      case "--extn-dir":
+        options.extnDir = args[++i];
+        if (!options.extnDir) {
+          throw new Error("Missing value for --extn-dir");
+        }
+        break;
+      case "--extn-repo":
+        options.extnRepo = args[++i];
+        if (!options.extnRepo) {
+          throw new Error("Missing value for --extn-repo");
+        }
+        break;
+      case "--profile":
+        options.profile = args[++i];
+        if (!options.profile) {
+          throw new Error("Missing value for --profile");
+        }
+        break;
+      case "--profile-retailer":
+        options.profileRetailer = args[++i];
+        if (!options.profileRetailer) {
+          throw new Error("Missing value for --profile-retailer");
+        }
+        break;
+      case "--official-server-name":
+        options.officialServerName = args[++i];
+        if (!options.officialServerName) {
+          throw new Error("Missing value for --official-server-name");
+        }
+        break;
+      case "--extn-server-name":
+        options.extnServerName = args[++i];
+        if (!options.extnServerName) {
+          throw new Error("Missing value for --extn-server-name");
+        }
+        break;
+      default:
+        throw new Error(`Unknown option for mcp-setup: ${arg}`);
+    }
+  }
+
+  if (options.profileRetailer && !options.profile) {
+    throw new Error("--profile-retailer requires --profile");
+  }
+
+  return options;
+}
+
+function installMcpExtnSource(options) {
+  const cwd = process.cwd();
+  const extnDirAbsolute = join(cwd, options.extnDir);
+  const packageJson = join(extnDirAbsolute, "package.json");
+
+  if (!existsSync(extnDirAbsolute)) {
+    log(`Cloning Fluent MCP extension source into ${options.extnDir} ...`);
+    runCommand("git", ["clone", "--depth", "1", options.extnRepo, options.extnDir], cwd);
+    logOk(`cloned: ${options.extnRepo}`);
+  } else {
+    logWarn(`extension directory already exists: ${options.extnDir}`);
+  }
+
+  if (!existsSync(packageJson)) {
+    throw new Error(
+      `Expected ${options.extnDir}/package.json after clone. Check --extn-dir/--extn-repo.`
+    );
+  }
+
+  if (options.skipBuild) {
+    logWarn("Skipping npm install/build due to --skip-build");
+    return;
+  }
+
+  log(`Installing extension dependencies in ${options.extnDir} ...`);
+  runCommand("npm", ["install"], extnDirAbsolute);
+  log(`Building extension runtime in ${options.extnDir} ...`);
+  runCommand("npm", ["run", "build"], extnDirAbsolute);
+  logOk(`built: ${options.extnDir}/dist/index.js`);
+}
+
+function setupMcp(options) {
+  if (options.installExtnSource) {
+    installMcpExtnSource(options);
+  }
+
+  const cwd = process.cwd();
+  const mcpConfigPath = join(cwd, ".mcp.json");
+  const mcpConfig = readJsonObjectOrDefault(mcpConfigPath, {});
+
+  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== "object" || Array.isArray(mcpConfig.mcpServers)) {
+    mcpConfig.mcpServers = {};
+  }
+
+  const officialDesired = {
+    type: "stdio",
+    command: "fluent",
+    args: ["mcp", "server", "--stdio"],
+    env: options.profile ? { FLUENT_PROFILE: options.profile } : {},
+  };
+
+  // When --install-extn-source is used, wire to local dist/index.js.
+  // Otherwise, default to npx @fluentcommerce/fluent-mcp-extn (npm package).
+  let extnDesired;
+  if (options.installExtnSource) {
+    const extnRuntimePath = toPosixPath(join(options.extnDir, "dist", "index.js"));
+    extnDesired = {
+      type: "stdio",
+      command: "node",
+      args: [extnRuntimePath],
+    };
+  } else {
+    extnDesired = {
+      type: "stdio",
+      command: "npx",
+      args: ["@fluentcommerce/fluent-mcp-extn"],
+    };
+  }
+  if (options.profile) {
+    extnDesired.env = {
+      FLUENT_PROFILE: options.profile,
+      ...(options.profileRetailer
+        ? { FLUENT_PROFILE_RETAILER: options.profileRetailer }
+        : {}),
+    };
+  } else {
+    extnDesired.env = {
+      FLUENT_BASE_URL: "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
+      FLUENT_RETAILER_ID: "YOUR_RETAILER",
+      FLUENT_CLIENT_ID: "your-client-id",
+      FLUENT_CLIENT_SECRET: "your-client-secret",
+      FLUENT_USERNAME: "your-username",
+      FLUENT_PASSWORD: "your-password",
+    };
+  }
+
+  const officialExisting = mcpConfig.mcpServers[options.officialServerName];
+  const extnExisting = mcpConfig.mcpServers[options.extnServerName];
+
+  const officialMerged = mergeServerConfig(officialExisting, officialDesired);
+  if (options.profile) {
+    officialMerged.env = { ...(officialMerged.env || {}), FLUENT_PROFILE: options.profile };
+  }
+  const extnMerged = mergeServerConfig(extnExisting, extnDesired);
+  if (options.profile) {
+    extnMerged.env = {
+      ...(extnMerged.env || {}),
+      FLUENT_PROFILE: options.profile,
+      ...(options.profileRetailer
+        ? { FLUENT_PROFILE_RETAILER: options.profileRetailer }
+        : {}),
+    };
+  }
+
+  mcpConfig.mcpServers[options.officialServerName] = officialMerged;
+  mcpConfig.mcpServers[options.extnServerName] = extnMerged;
+
+  writeFileSync(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`);
+
+  log("");
+  log("MCP bootstrap complete.");
+  log(`Updated: ${mcpConfigPath}`);
+  logOk(`official server: ${options.officialServerName}`);
+  logOk(`extension server: ${options.extnServerName}`);
+  log("");
+  log("Next steps:");
+  log("  1) Fill credentials in .mcp.json (or keep your existing values).");
+  if (options.installExtnSource) {
+    if (options.skipBuild) {
+      log(`  2) Build extension runtime: cd ${options.extnDir} && npm run build`);
+    }
+  } else {
+    log("  2) Ensure @fluentcommerce/fluent-mcp-extn is installed:");
+    log("     npm install @fluentcommerce/fluent-mcp-extn");
+    log("     (or use --install-extn-source for local source clone instead)");
+  }
+  log("  3) Restart your IDE/agent session.");
+}
+
+// ---------------------------------------------------------------------------
+// Flow runner (diagnostics + optional guarded deploy)
+// ---------------------------------------------------------------------------
+
+function showFlowRunHelp() {
+  log(`
+flow-run: diagnostics and optional deploy orchestration
+
+USAGE
+  npx @fluentcommerce/ai-skills flow-run [options]
+
+OPTIONS
+  --profile <name>            Fluent profile for list/install checks
+  --retailer <ref>            Retailer ref for workflow checks
+  --module <name-or-path>     Module package name or local zip/path
+  --config <file>             Module config file to validate (and use on deploy)
+  --deploy                    Run fluent module install (write operation)
+  --yes                       Required with --deploy (explicit confirmation)
+  --exclude-workflows         Pass --exclude workflows during deploy
+  --force                     Pass --force during deploy
+  --report <path>             Report output path (default: ./${DEFAULT_FLOW_REPORT_DIR}/flow-run-report-<timestamp>.json)
+  --official-server-name <n>  MCP key for official server (default: fluent-mcp)
+  --extn-server-name <n>      MCP key for extn server (default: fluent-mcp-extn)
+  --skip-mcp-check            Skip .mcp.json validation
+  --help, -h                  Show flow-run help
+
+EXAMPLES
+  npx @fluentcommerce/ai-skills flow-run --profile HMDEV --retailer HM_TEST --module dist/module.zip --config config/module.config.json
+  npx @fluentcommerce/ai-skills flow-run --profile HMDEV --retailer HM_TEST --module dist/module.zip --config config/module.config.json --deploy --yes
+  npx @fluentcommerce/ai-skills flow-run --profile HMDEV --retailer HM_TEST --module @fluentcommerce/fc-module-core --deploy --yes --exclude-workflows
+
+NOTES
+  - By default, flow-run executes read-only diagnostics.
+  - Deploy is opt-in and requires --yes.
+  - A JSON report is always written with step-by-step results.
+`);
+}
+
+function parseFlowRunArgs(args) {
+  const options = {
+    profile: "",
+    retailer: "",
+    module: "",
+    config: "",
+    deploy: false,
+    yes: false,
+    excludeWorkflows: false,
+    force: false,
+    report: "",
+    officialServerName: "fluent-mcp",
+    extnServerName: "fluent-mcp-extn",
+    skipMcpCheck: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--profile":
+        options.profile = args[++i];
+        if (!options.profile) throw new Error("Missing value for --profile");
+        break;
+      case "--retailer":
+        options.retailer = args[++i];
+        if (!options.retailer) throw new Error("Missing value for --retailer");
+        break;
+      case "--module":
+        options.module = args[++i];
+        if (!options.module) throw new Error("Missing value for --module");
+        break;
+      case "--config":
+        options.config = args[++i];
+        if (!options.config) throw new Error("Missing value for --config");
+        break;
+      case "--deploy":
+        options.deploy = true;
+        break;
+      case "--yes":
+      case "--confirm":
+        options.yes = true;
+        break;
+      case "--exclude-workflows":
+        options.excludeWorkflows = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "--report":
+      case "--report-file":
+        options.report = args[++i];
+        if (!options.report) throw new Error("Missing value for --report");
+        break;
+      case "--official-server-name":
+        options.officialServerName = args[++i];
+        if (!options.officialServerName) throw new Error("Missing value for --official-server-name");
+        break;
+      case "--extn-server-name":
+        options.extnServerName = args[++i];
+        if (!options.extnServerName) throw new Error("Missing value for --extn-server-name");
+        break;
+      case "--skip-mcp-check":
+        options.skipMcpCheck = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option for flow-run: ${arg}`);
+    }
+  }
+
+  if (options.deploy && !options.yes) {
+    throw new Error("--deploy is a write operation. Re-run with --yes to confirm.");
+  }
+  if (options.deploy && !options.module) {
+    throw new Error("--deploy requires --module <name-or-path>.");
+  }
+  if (options.deploy && (!options.profile || !options.retailer)) {
+    throw new Error("--deploy requires --profile and --retailer.");
+  }
+
+  return options;
+}
+
+function defaultFlowReportPath() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return join(process.cwd(), DEFAULT_FLOW_REPORT_DIR, `flow-run-report-${stamp}.json`);
+}
+
+function resolveLocalPath(path) {
+  return isAbsolute(path) ? path : join(process.cwd(), path);
+}
+
+function hasPlaceholders(text) {
+  const matches = text.match(/\[\[[^\]]+\]\]/g) || [];
+  return [...new Set(matches)];
+}
+
+function buildFlowCommandCheck(id, title, phase, command, args, blocking = true) {
+  const result = runCommandCapture(command, args, process.cwd());
+  return {
+    id,
+    title,
+    phase,
+    status: result.exitCode === 0 ? "passed" : "failed",
+    blocking,
+    command: result.commandText,
+    exitCode: result.exitCode,
+    durationMs: result.durationMs,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    message: result.exitCode === 0 ? "Command succeeded." : `Command failed with exit code ${result.exitCode}.`,
+  };
+}
+
+function summarizeFlowChecks(checks) {
+  const summary = {
+    passed: 0,
+    failed: 0,
+    warning: 0,
+    skipped: 0,
+  };
+
+  for (const check of checks) {
+    if (Object.prototype.hasOwnProperty.call(summary, check.status)) {
+      summary[check.status] += 1;
+    }
+  }
+
+  const overall =
+    summary.failed > 0 ? "failed" : summary.warning > 0 ? "warning" : "passed";
+
+  return { ...summary, total: checks.length, overall };
+}
+
+function hasBlockingFailures(checks) {
+  return checks.some((check) => check.status === "failed" && check.blocking !== false);
+}
+
+function addFlowCheck(report, check) {
+  report.checks.push(check);
+  const label = `${check.id}: ${check.title}`;
+
+  if (check.status === "passed") {
+    logOk(label);
+  } else if (check.status === "warning") {
+    logWarn(`${label} (${check.message})`);
+  } else if (check.status === "skipped") {
+    logWarn(`${label} (skipped: ${check.message})`);
+  } else {
+    logErr(`${label} (${check.message})`);
+  }
+}
+
+function runFlow(options) {
+  if (options.help) {
+    showFlowRunHelp();
+    return;
+  }
+
+  const reportPath = resolveLocalPath(options.report || defaultFlowReportPath());
+  const configPath = options.config ? resolveLocalPath(options.config) : "";
+  const report = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    package: {
+      name: pkg.name || "@fluentcommerce/ai-skills",
+      version: pkg.version || "0.0.0",
+    },
+    command: "flow-run",
+    cwd: process.cwd(),
+    options: {
+      ...options,
+      report: reportPath,
+      config: configPath,
+    },
+    checks: [],
+    summary: {},
+    recommendations: [],
+  };
+
+  log("");
+  log("Flow run: diagnostics + optional deploy");
+  log("=======================================");
+  log(`Working directory: ${report.cwd}`);
+  log(`Report file: ${reportPath}`);
+  log("");
+
+  if (options.skipMcpCheck) {
+    addFlowCheck(report, {
+      id: "mcp-config",
+      title: "MCP config validation",
+      phase: "local",
+      status: "skipped",
+      blocking: false,
+      message: "Skipped by --skip-mcp-check.",
+    });
+  } else {
+    const mcpPath = join(process.cwd(), ".mcp.json");
+    if (!existsSync(mcpPath)) {
+      addFlowCheck(report, {
+        id: "mcp-config",
+        title: "MCP config validation",
+        phase: "local",
+        status: "warning",
+        blocking: false,
+        message: ".mcp.json was not found in the current directory.",
+        details: { path: mcpPath },
+      });
+    } else {
+      try {
+        const parsed = readJsonObjectOrDefault(mcpPath, {});
+        const servers =
+          parsed.mcpServers && typeof parsed.mcpServers === "object" && !Array.isArray(parsed.mcpServers)
+            ? parsed.mcpServers
+            : {};
+        const missingServers = [];
+        if (!servers[options.officialServerName]) missingServers.push(options.officialServerName);
+        if (!servers[options.extnServerName]) missingServers.push(options.extnServerName);
+
+        const unresolvedEnvKeys = [];
+        for (const serverName of [options.officialServerName, options.extnServerName]) {
+          const env = servers?.[serverName]?.env;
+          if (!env || typeof env !== "object" || Array.isArray(env)) continue;
+
+          for (const [key, value] of Object.entries(env)) {
+            if (typeof value !== "string") continue;
+            const unresolved =
+              /\[\[[^\]]+\]\]/.test(value) ||
+              /YOUR_/i.test(value) ||
+              /your-[a-z0-9-]+/i.test(value);
+            if (unresolved) {
+              unresolvedEnvKeys.push(`${serverName}.${key}`);
+            }
+          }
+        }
+
+        if (missingServers.length > 0) {
+          addFlowCheck(report, {
+            id: "mcp-config",
+            title: "MCP config validation",
+            phase: "local",
+            status: "warning",
+            blocking: false,
+            message: `Missing MCP server entries: ${missingServers.join(", ")}.`,
+            details: { path: mcpPath, missingServers, unresolvedEnvKeys },
+          });
+        } else if (unresolvedEnvKeys.length > 0) {
+          addFlowCheck(report, {
+            id: "mcp-config",
+            title: "MCP config validation",
+            phase: "local",
+            status: "warning",
+            blocking: false,
+            message: "MCP server env contains unresolved placeholder values.",
+            details: { path: mcpPath, unresolvedEnvKeys },
+          });
+        } else {
+          addFlowCheck(report, {
+            id: "mcp-config",
+            title: "MCP config validation",
+            phase: "local",
+            status: "passed",
+            blocking: false,
+            message: "Official and extension MCP server entries look valid.",
+            details: {
+              path: mcpPath,
+              officialServer: options.officialServerName,
+              extensionServer: options.extnServerName,
+            },
+          });
+        }
+      } catch (error) {
+        addFlowCheck(report, {
+          id: "mcp-config",
+          title: "MCP config validation",
+          phase: "local",
+          status: "failed",
+          blocking: false,
+          message: error.message,
+        });
+      }
+    }
+  }
+
+  if (!configPath) {
+    addFlowCheck(report, {
+      id: "config-placeholders",
+      title: "Module config placeholder scan",
+      phase: "local",
+      status: "skipped",
+      blocking: true,
+      message: "No --config provided.",
+    });
+  } else if (!existsSync(configPath)) {
+    addFlowCheck(report, {
+      id: "config-placeholders",
+      title: "Module config placeholder scan",
+      phase: "local",
+      status: "failed",
+      blocking: true,
+      message: `Config file not found: ${configPath}`,
+      details: { configPath },
+    });
+  } else {
+    try {
+      const configText = readFileSync(configPath, "utf-8");
+      const unresolved = hasPlaceholders(configText);
+      if (unresolved.length > 0) {
+        addFlowCheck(report, {
+          id: "config-placeholders",
+          title: "Module config placeholder scan",
+          phase: "local",
+          status: "failed",
+          blocking: true,
+          message: `Found unresolved placeholders in config: ${unresolved.join(", ")}`,
+          details: { configPath, placeholders: unresolved },
+        });
+      } else {
+        addFlowCheck(report, {
+          id: "config-placeholders",
+          title: "Module config placeholder scan",
+          phase: "local",
+          status: "passed",
+          blocking: true,
+          message: "No unresolved [[...]] placeholders found.",
+          details: { configPath },
+        });
+      }
+    } catch (error) {
+      addFlowCheck(report, {
+        id: "config-placeholders",
+        title: "Module config placeholder scan",
+        phase: "local",
+        status: "failed",
+        blocking: true,
+        message: error.message,
+        details: { configPath },
+      });
+    }
+  }
+
+  const diagnostics = [
+    {
+      id: "fluent-version",
+      title: "Fluent CLI version check",
+      phase: "cli-preflight",
+      command: "fluent",
+      args: ["--version"],
+      blocking: true,
+    },
+    {
+      id: "profile-active",
+      title: "Active profile check",
+      phase: "cli-preflight",
+      command: "fluent",
+      args: ["profile", "active"],
+      blocking: true,
+    },
+  ];
+
+  if (options.module) {
+    diagnostics.push({
+      id: "module-describe",
+      title: "Module describe",
+      phase: "cli-read",
+      command: "fluent",
+      args: ["module", "describe", options.module],
+      blocking: true,
+    });
+  }
+  if (options.profile) {
+    diagnostics.push({
+      id: "module-list",
+      title: "Installed modules check",
+      phase: "cli-read",
+      command: "fluent",
+      args: ["module", "list", "-p", options.profile],
+      blocking: false,
+    });
+  }
+  if (options.profile && options.retailer) {
+    diagnostics.push({
+      id: "workflow-list",
+      title: "Workflow list check",
+      phase: "cli-read",
+      command: "fluent",
+      args: ["workflow", "list", "-p", options.profile, "-r", options.retailer],
+      blocking: false,
+    });
+  }
+
+  for (const step of diagnostics) {
+    addFlowCheck(
+      report,
+      buildFlowCommandCheck(step.id, step.title, step.phase, step.command, step.args, step.blocking)
+    );
+  }
+
+  const profileCheck = report.checks.find((check) => check.id === "profile-active");
+  if (options.profile && profileCheck && profileCheck.status === "passed") {
+    const activeMatches = profileCheck.stdout.toLowerCase().includes(options.profile.toLowerCase());
+    if (!activeMatches) {
+      addFlowCheck(report, {
+        id: "profile-match",
+        title: "Requested profile matches active session",
+        phase: "cli-preflight",
+        status: "warning",
+        blocking: false,
+        message: `Active profile output does not clearly mention '${options.profile}'.`,
+      });
+    } else {
+      addFlowCheck(report, {
+        id: "profile-match",
+        title: "Requested profile matches active session",
+        phase: "cli-preflight",
+        status: "passed",
+        blocking: false,
+        message: `Active profile appears to match '${options.profile}'.`,
+      });
+    }
+  }
+
+  if (options.deploy) {
+    if (hasBlockingFailures(report.checks)) {
+      addFlowCheck(report, {
+        id: "module-install",
+        title: "Module deploy",
+        phase: "cli-write",
+        status: "skipped",
+        blocking: true,
+        message: "Skipped because one or more blocking checks failed.",
+      });
+    } else {
+      const installArgs = ["module", "install", options.module, "--profile", options.profile, "--retailer", options.retailer];
+      if (configPath) installArgs.push("--config", configPath);
+      if (options.excludeWorkflows) installArgs.push("--exclude", "workflows");
+      if (options.force) installArgs.push("--force");
+
+      const deployCheck = buildFlowCommandCheck(
+        "module-install",
+        "Module deploy",
+        "cli-write",
+        "fluent",
+        installArgs,
+        true
+      );
+      addFlowCheck(report, deployCheck);
+
+      if (deployCheck.status === "passed") {
+        addFlowCheck(
+          report,
+          buildFlowCommandCheck(
+            "module-list-post",
+            "Post-deploy module verification",
+            "cli-verify",
+            "fluent",
+            ["module", "list", "-p", options.profile],
+            false
+          )
+        );
+
+        addFlowCheck(
+          report,
+          buildFlowCommandCheck(
+            "workflow-list-post",
+            "Post-deploy workflow verification",
+            "cli-verify",
+            "fluent",
+            ["workflow", "list", "-p", options.profile, "-r", options.retailer],
+            false
+          )
+        );
+      } else {
+        addFlowCheck(report, {
+          id: "post-deploy-verify",
+          title: "Post-deploy verification",
+          phase: "cli-verify",
+          status: "skipped",
+          blocking: false,
+          message: "Skipped because deploy step failed.",
+        });
+      }
+    }
+  } else {
+    addFlowCheck(report, {
+      id: "module-install",
+      title: "Module deploy",
+      phase: "cli-write",
+      status: "skipped",
+      blocking: true,
+      message: "Deploy not requested. Re-run with --deploy --yes to install.",
+    });
+  }
+
+  report.summary = summarizeFlowChecks(report.checks);
+
+  if (report.checks.some((check) => check.id === "config-placeholders" && check.status === "failed")) {
+    report.recommendations.push("Resolve all [[...]] placeholders in the module config before deploy.");
+  }
+  if (report.checks.some((check) => check.id === "mcp-config" && check.status === "warning")) {
+    report.recommendations.push("Fix .mcp.json server/env placeholders before relying on MCP-driven validation.");
+  }
+  if (!options.deploy) {
+    report.recommendations.push("When diagnostics are clean, run again with --deploy --yes to install the module.");
+  }
+  if (options.deploy && report.summary.overall === "passed") {
+    report.recommendations.push("Deploy completed successfully. Run environment-specific smoke tests next.");
+  }
+
+  ensureDir(dirname(reportPath));
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+
+  log("");
+  log("Flow run summary:");
+  log(`  passed: ${report.summary.passed}`);
+  log(`  warning: ${report.summary.warning}`);
+  log(`  failed: ${report.summary.failed}`);
+  log(`  skipped: ${report.summary.skipped}`);
+  log(`  overall: ${report.summary.overall}`);
+  log("");
+  log(`Report written: ${reportPath}`);
+
+  if (report.summary.overall === "failed") {
+    throw new Error("flow-run completed with failures. See report for details.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function listGroups(groups) {
+  log("");
+  log("Fluent AI Skills - Available Groups");
+  log("====================================");
+  log("");
+
+  for (const group of groups) {
+    log(`- ${group.name}`);
+    log(`    ${group.description}`);
+    log(`    Agents: ${group.agents.length} | Skills: ${group.skills.length}`);
+  }
+
+  log("");
+}
+
+function showHelp(groups) {
+  const groupNames = groups.map((group) => group.name).join(", ");
+  log(`
+fluent-ai-skills v${pkg.version}
+
+Install Fluent Commerce AI skills for any coding assistant.
+
+USAGE
+  npx @fluentcommerce/ai-skills <command> [--target <target>] [groups...]
+
+COMMANDS
+  install [groups...]      Install all groups (default) or selected groups
+  uninstall [groups...]    Uninstall all groups (default) or selected groups
+  status [groups...]       Show install status for all or selected groups
+  mcp-setup [options]      Bootstrap .mcp.json for official + extn servers
+  flow-run [options]       Run diagnostics and optional guarded module deploy
+  list                     List available groups
+  --version, -v            Show package version
+  --help, -h               Show this help
+
+TARGETS (--target <name>)
+  claude       Claude Code: ~/.claude/agents + ~/.claude/skills  (default, primary)
+  cursor       Cursor: .cursor/rules/*.mdc  (beta)
+  copilot      GitHub Copilot: .github/copilot-instructions.md  (beta)
+  vscode       VS Code (Copilot format): alias of 'copilot'  (beta)
+  windsurf     Windsurf: .windsurfrules  (beta)
+  codex        OpenAI Codex: AGENTS.md  (beta)
+  gemini       Gemini CLI: GEMINI.md  (beta)
+
+GROUPS
+  ${groupNames || "(none discovered)"}
+
+EXAMPLES
+  npx @fluentcommerce/ai-skills install
+  npx @fluentcommerce/ai-skills install --target cursor
+  npx @fluentcommerce/ai-skills install --target copilot cli mcp-extn
+  npx @fluentcommerce/ai-skills mcp-setup --profile HMDEV
+  npx @fluentcommerce/ai-skills mcp-setup --profile HMDEV --profile-retailer HM_TEST
+  npx @fluentcommerce/ai-skills mcp-setup --install-extn-source
+  npx @fluentcommerce/ai-skills flow-run --profile HMDEV --retailer HM_TEST --module dist/module.zip --config config/module.config.json
+  npx @fluentcommerce/ai-skills flow-run --profile HMDEV --retailer HM_TEST --module dist/module.zip --config config/module.config.json --deploy --yes
+  npx @fluentcommerce/ai-skills uninstall --target windsurf
+  npx @fluentcommerce/ai-skills status --target cursor
+
+NOTES
+  - Claude is the primary target.
+  - Other targets are beta adapters and install to cwd.
+  - Claude target installs globally to ~/.claude/. All others install to cwd.
+  - Non-Claude targets use managed blocks and preserve existing file content.
+  - mcp-setup writes/merges .mcp.json in the current project directory.
+  - flow-run writes a JSON execution report in ./.fluent-ai-skills by default.
+  - Set FLUENT_AI_SKILLS_HOME to override the Claude install location.
+  - Aliases: mcp -> mcp-extn, mcp-core -> mcp-official.
+`);
+}
+
+function resolveTarget(target) {
+  return TARGET_ALIASES[target] || target;
+}
+
+function parseArgs(argv) {
+  let target = "claude";
+  const rest = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--target" || argv[i] === "-t") {
+      const requestedTarget = (argv[i + 1] || "").toLowerCase();
+      if (!SUPPORTED_TARGETS.includes(requestedTarget)) {
+        throw new Error(
+          `Unknown target: ${requestedTarget}. Supported: ${SUPPORTED_TARGETS.join(", ")}`
+        );
+      }
+      target = resolveTarget(requestedTarget);
+      i++; // skip the value
+    } else {
+      rest.push(argv[i]);
+    }
+  }
+
+  return {
+    target,
+    command: rest[0],
+    commandArgs: rest.slice(1),
+    groupArgs: rest.slice(1).map((v) => v.toLowerCase()),
+  };
+}
+
+function main() {
+  const groups = discoverGroups();
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    showHelp(groups);
+    process.exit(0);
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (error) {
+    logErr(error.message);
+    process.exit(1);
+  }
+
+  const { target, command, commandArgs, groupArgs } = parsed;
+
+  if (!command) {
+    showHelp(groups);
+    process.exit(0);
+  }
+
+  try {
+    switch (command) {
+      case "install": {
+        const selected = resolveGroups(groupArgs, groups);
+        log("");
+        log(`Target: ${target}`);
+        targetInstall(target, selected);
+        log("");
+        log(`Done. Groups: ${selected.map((g) => g.name).join(", ")}`);
+        log("");
+        break;
+      }
+      case "uninstall":
+      case "remove": {
+        const selected = resolveGroups(groupArgs, groups);
+        log("");
+        log(`Target: ${target}`);
+        log("Uninstalling...");
+        log("");
+        targetUninstall(target, selected);
+        log("");
+        log(`Done. Groups: ${selected.map((g) => g.name).join(", ")}`);
+        log("");
+        break;
+      }
+      case "status":
+      case "check": {
+        const selected = resolveGroups(groupArgs, groups);
+        log("");
+        log(`Target: ${target}`);
+        log("");
+        targetStatus(target, selected);
+        log("");
+        break;
+      }
+      case "mcp-setup":
+      case "setup-mcp":
+      case "init-mcp": {
+        const options = parseMcpSetupArgs(commandArgs);
+        setupMcp(options);
+        break;
+      }
+      case "flow-run":
+      case "run-flow": {
+        const options = parseFlowRunArgs(commandArgs);
+        runFlow(options);
+        break;
+      }
+      case "list":
+        listGroups(groups);
+        break;
+      case "--version":
+      case "-v":
+        log(`fluent-ai-skills v${pkg.version}`);
+        break;
+      case "--help":
+      case "-h":
+      case "help":
+        showHelp(groups);
+        break;
+      default:
+        logErr(`Unknown command: ${command}`);
+        log("");
+        showHelp(groups);
+        process.exit(1);
+    }
+  } catch (error) {
+    logErr(error.message);
+    log("");
+    process.exit(1);
+  }
+}
+
+main();