@appsforgood/next-supabase-kit 0.4.2 → 0.4.3

package/dist/index.js

@@ -25,11 +25,12 @@ function findPackageRoot(start = dirname(fileURLToPath(import.meta.url))) {
 }
 
 // src/catalog.ts
-var cached = null;
+var catalogByRoot = /* @__PURE__ */ new Map();
 function loadCatalog(packageRoot = findPackageRoot()) {
-  if (cached && packageRoot === findPackageRoot()) return cached;
+  const existing = catalogByRoot.get(packageRoot);
+  if (existing) return existing;
   const parsed = JSON.parse(readFileSync(join2(packageRoot, "catalog.json"), "utf8"));
-  cached = parsed;
+  catalogByRoot.set(packageRoot, parsed);
   return parsed;
 }
 function agentSourcePath(packageRoot, id) {
@@ -423,8 +424,222 @@ function addSkill(cwd, skillName, options = {}) {
 }
 
 // src/install/adapter-validate.ts
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { join as join7 } from "path";
+
+// src/config/defaults.ts
+var PACKAGE_NAME = "@appsforgood/next-supabase-kit";
+var PACKAGE_VERSION = "0.4.3";
+var ROOT_DOCS = ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"];
+var CURSOR_RULE_FILE = {
+  source: "assistant-adapters/cursor-agent-kit.mdc",
+  target: ".cursor/rules/cursor-agent-kit.mdc"
+};
+var CLAUDE_TEMPLATE = "templates/next-supabase/CLAUDE.md";
+var USER_GUIDE_SOURCE = "USER_GUIDE.md";
+var USER_GUIDE_HTML_SOURCE = "USER_GUIDE.html";
+var AGENTS_DOC_SOURCE = "templates/next-supabase/AGENTS.md";
+
+// src/install/ide-activate.ts
+var IDE_TARGETS = ["cursor", "claude", "codex", "copilot", "antigravity"];
+var ALLOWED = new Set(IDE_TARGETS);
+function isIdeTarget(value) {
+  return ALLOWED.has(value);
+}
+var InvalidActivateTargetError = class extends Error {
+  constructor(invalid) {
+    super(`Unknown --activate target(s): ${invalid.join(", ")}. Allowed: cursor, claude, codex, copilot, antigravity, all.`);
+    this.invalid = invalid;
+    this.name = "InvalidActivateTargetError";
+  }
+  invalid;
+};
+function parseActivateTargets(raw) {
+  if (!raw || raw.length === 0) return [];
+  return normalizeTargets(raw.flatMap((value) => value.split(",")));
+}
+function normalizeTargets(targets) {
+  const normalized = /* @__PURE__ */ new Set();
+  const invalid = [];
+  for (const target of targets) {
+    const value = target.trim().toLowerCase();
+    if (!value) continue;
+    if (value === "all") {
+      for (const item of ALLOWED) normalized.add(item);
+      continue;
+    }
+    if (isIdeTarget(value)) {
+      normalized.add(value);
+    } else {
+      invalid.push(target.trim());
+    }
+  }
+  if (invalid.length > 0) throw new InvalidActivateTargetError(invalid);
+  return [...normalized];
+}
+function activateIdeTargets(options) {
+  const cwd = options.cwd;
+  const packageRoot = findPackageRoot();
+  const targets = normalizeTargets(options.targets);
+  const force = Boolean(options.force);
+  const collector = emptyCollector();
+  const result = { activated: targets, ...collector };
+  if (targets.length === 0) return result;
+  if (targets.includes("cursor")) {
+    copyFromPackage(cwd, packageRoot, CURSOR_RULE_FILE.source, CURSOR_RULE_FILE.target, force, result);
+    generateCursorAgents(cwd, force, result);
+    generateCursorSkills(cwd, force, result);
+  }
+  if (targets.includes("claude")) {
+    copyFromPackage(cwd, packageRoot, CLAUDE_TEMPLATE, "CLAUDE.md", force, result);
+    generateClaudeAgents(cwd, force, result);
+  }
+  if (targets.includes("codex")) {
+    generateCodexAgents(cwd, force, result);
+  }
+  if (targets.includes("copilot")) {
+    generateCopilotInstructions(cwd, force, result);
+  }
+  if (targets.includes("antigravity")) {
+    generateAntigravityCommands(cwd, force, result);
+  }
+  return result;
+}
+
+// src/install/install.ts
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
+
+// src/install/managed-assets.ts
 import { join as join5 } from "path";
+function listManagedAssets(packageRoot, options = {}) {
+  const assets = [
+    { target: "AGENTS.md", sourcePath: join5(packageRoot, AGENTS_DOC_SOURCE), category: "root-doc" },
+    { target: "USER_GUIDE.md", sourcePath: join5(packageRoot, USER_GUIDE_SOURCE), category: "root-doc" },
+    { target: "USER_GUIDE.html", sourcePath: join5(packageRoot, USER_GUIDE_HTML_SOURCE), category: "root-doc" },
+    { target: CURSOR_RULE_FILE.target, sourcePath: join5(packageRoot, CURSOR_RULE_FILE.source), category: "adapter" }
+  ];
+  const activated = new Set(options.activated ?? ["cursor"]);
+  if (activated.has("claude")) {
+    assets.push({
+      target: "CLAUDE.md",
+      sourcePath: join5(packageRoot, "templates/next-supabase/CLAUDE.md"),
+      category: "adapter"
+    });
+  }
+  return assets;
+}
+
+// src/install/install.ts
+function initProject(options) {
+  const cwd = options.cwd;
+  const stack = options.stack ?? "next-supabase";
+  const packageRoot = findPackageRoot();
+  const force = Boolean(options.force);
+  ensureDir(join6(cwd, ".agent-kit", "conflicts"));
+  const result = {
+    ...emptyCollector(),
+    manifestPath: ".agent-kit/manifest.json"
+  };
+  const templateHashes = {};
+  const agentsDoc = readFileSync6(join6(packageRoot, AGENTS_DOC_SOURCE), "utf8");
+  const userGuide = readFileSync6(join6(packageRoot, USER_GUIDE_SOURCE), "utf8");
+  const userGuideHtml = readFileSync6(join6(packageRoot, USER_GUIDE_HTML_SOURCE), "utf8");
+  templateHashes["AGENTS.md"] = sha256(agentsDoc);
+  templateHashes["USER_GUIDE.md"] = sha256(userGuide);
+  templateHashes["USER_GUIDE.html"] = sha256(userGuideHtml);
+  recordCopy(
+    result,
+    copyTextWithConflict(join6(packageRoot, AGENTS_DOC_SOURCE), cwd, "AGENTS.md", {
+      force,
+      conflictRoot: join6(cwd, ".agent-kit", "conflicts")
+    })
+  );
+  recordCopy(
+    result,
+    copyTextWithConflict(join6(packageRoot, USER_GUIDE_SOURCE), cwd, "USER_GUIDE.md", {
+      force,
+      conflictRoot: join6(cwd, ".agent-kit", "conflicts")
+    })
+  );
+  recordCopy(
+    result,
+    copyTextWithConflict(join6(packageRoot, USER_GUIDE_HTML_SOURCE), cwd, "USER_GUIDE.html", {
+      force,
+      conflictRoot: join6(cwd, ".agent-kit", "conflicts")
+    })
+  );
+  if (options.legacyDocs) {
+    const legacyRoot = join6(packageRoot, "templates", stack);
+    const legacyDocs = ["SPEC.md", "DECISIONS.md", "DESIGN.md", "SECURITY.md", "TESTING.md", "QUALITY_GATES.md"];
+    for (const doc of legacyDocs) {
+      const source = join6(legacyRoot, doc);
+      if (!existsSync6(source)) continue;
+      recordCopy(
+        result,
+        copyTextWithConflict(source, cwd, doc, {
+          force,
+          conflictRoot: join6(cwd, ".agent-kit", "conflicts")
+        })
+      );
+    }
+  }
+  const activateTargets = parseActivateTargets(options.activate);
+  const targets = activateTargets.length > 0 ? activateTargets : ["cursor"];
+  result.activation = activateIdeTargets({ cwd, targets, force });
+  generatePortableSkills(cwd, force, result.activation);
+  result.copied.push(...result.activation.copied.filter((path) => !result.copied.includes(path)));
+  result.unchanged.push(...result.activation.unchanged.filter((path) => !result.unchanged.includes(path)));
+  result.conflicts.push(...result.activation.conflicts.filter((path) => !result.conflicts.includes(path)));
+  result.overwritten.push(...result.activation.overwritten.filter((path) => !result.overwritten.includes(path)));
+  const assets = listManagedAssets(packageRoot, { activated: targets });
+  const assetHashes = {};
+  for (const asset of assets) {
+    if (existsSync6(asset.sourcePath)) assetHashes[asset.target] = sha256(readFileSync6(asset.sourcePath, "utf8"));
+  }
+  for (const relative2 of [...result.copied, ...result.unchanged, ...result.overwritten]) {
+    const path = join6(cwd, relative2);
+    if (existsSync6(path) && !assetHashes[relative2]) {
+      assetHashes[relative2] = sha256(readFileSync6(path, "utf8"));
+    }
+  }
+  const catalog = loadCatalog(packageRoot);
+  const manifest = {
+    schemaVersion: 3,
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    stack,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    docs: [...ROOT_DOCS],
+    activated: targets,
+    templateHashes,
+    assetHashes
+  };
+  writeText(join6(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+  writeText(
+    join6(cwd, ".agent-kit", "config.json"),
+    `${JSON.stringify({ stack, catalog: { defaultAgents: catalog.defaultAgents, defaultSkills: catalog.defaultSkills } }, null, 2)}
+`
+  );
+  if (!targets.includes("cursor")) {
+    recordCopy(
+      result,
+      copyTextWithConflict(join6(packageRoot, CURSOR_RULE_FILE.source), cwd, CURSOR_RULE_FILE.target, {
+        force,
+        conflictRoot: join6(cwd, ".agent-kit", "conflicts")
+      })
+    );
+  }
+  return result;
+}
+function readManifest(cwd) {
+  const manifestPath = join6(cwd, ".agent-kit", "manifest.json");
+  if (!existsSync6(manifestPath)) return null;
+  return JSON.parse(readFileSync6(manifestPath, "utf8"));
+}
+
+// src/install/adapter-validate.ts
 function summary(findings) {
   return {
     pass: findings.filter((finding) => finding.level === "pass").length,
@@ -432,14 +647,14 @@ function summary(findings) {
     fail: findings.filter((finding) => finding.level === "fail").length
   };
 }
-function report(target, findings) {
-  return { target, summary: summary(findings), findings };
+function report(target, findings, validated) {
+  return { target, validated, summary: summary(findings), findings };
 }
 function has(cwd, relative2) {
-  return existsSync6(join5(cwd, relative2));
+  return existsSync7(join7(cwd, relative2));
 }
 function text(cwd, relative2) {
-  return readFileSync6(join5(cwd, relative2), "utf8");
+  return readFileSync7(join7(cwd, relative2), "utf8");
 }
 function validateCursor(cwd) {
   const catalog = loadCatalog();
@@ -527,45 +742,55 @@ function validateAntigravity(cwd) {
   }
   return findings;
 }
+var validators = {
+  cursor: validateCursor,
+  claude: validateClaude,
+  codex: validateCodex,
+  copilot: validateCopilot,
+  antigravity: validateAntigravity
+};
+function resolveAdapterTargets(cwd, target) {
+  if (target !== "all") return [target];
+  const activated = (readManifest(cwd)?.activated ?? []).filter(isIdeTarget);
+  return activated.length > 0 ? activated : [...IDE_TARGETS];
+}
 function validateAdapter(cwd, target) {
-  if (target === "cursor") return report("cursor", validateCursor(cwd));
-  if (target === "claude") return report("claude", validateClaude(cwd));
-  if (target === "codex") return report("codex", validateCodex(cwd));
-  if (target === "copilot") return report("copilot", validateCopilot(cwd));
-  if (target === "antigravity") return report("antigravity", validateAntigravity(cwd));
-  return report("all", [...validateCursor(cwd), ...validateClaude(cwd), ...validateCodex(cwd), ...validateCopilot(cwd), ...validateAntigravity(cwd)]);
+  const validated = resolveAdapterTargets(cwd, target);
+  const findings = validated.flatMap((ide) => validators[ide](cwd));
+  const label = target === "all" && validated.length < IDE_TARGETS.length ? `all (${validated.join(", ")})` : target;
+  return report(label, findings, validated);
 }
 function validatePackage() {
   const cwd = process.cwd();
   const findings = [];
-  if (!existsSync6(join5(cwd, "catalog.json"))) {
+  if (!existsSync7(join7(cwd, "catalog.json"))) {
     findings.push({ level: "fail", area: "package", message: "catalog.json is missing." });
   } else {
     findings.push({ level: "pass", area: "package", message: "catalog.json is present." });
   }
-  if (!existsSync6(join5(cwd, "USER_GUIDE.md"))) {
+  if (!existsSync7(join7(cwd, "USER_GUIDE.md"))) {
     findings.push({ level: "fail", area: "package", message: "USER_GUIDE.md is missing." });
-  } else if (!readFileSync6(join5(cwd, "USER_GUIDE.md"), "utf8").includes("Do not review code alone")) {
+  } else if (!readFileSync7(join7(cwd, "USER_GUIDE.md"), "utf8").includes("Do not review code alone")) {
     findings.push({ level: "fail", area: "package", message: "USER_GUIDE.md dropped the screenshot fail-closed sentence." });
   } else {
     findings.push({ level: "pass", area: "package", message: "USER_GUIDE.md includes the screenshot rule." });
   }
-  if (!existsSync6(join5(cwd, "USER_GUIDE.html"))) {
+  if (!existsSync7(join7(cwd, "USER_GUIDE.html"))) {
     findings.push({ level: "fail", area: "package", message: "USER_GUIDE.html is missing." });
-  } else if (!readFileSync6(join5(cwd, "USER_GUIDE.html"), "utf8").includes("Do not review code alone")) {
+  } else if (!readFileSync7(join7(cwd, "USER_GUIDE.html"), "utf8").includes("Do not review code alone")) {
     findings.push({ level: "fail", area: "package", message: "USER_GUIDE.html dropped the screenshot fail-closed sentence." });
   } else {
     findings.push({ level: "pass", area: "package", message: "USER_GUIDE.html includes the screenshot rule." });
   }
-  if (!existsSync6(join5(cwd, "skills/browser-qa/SKILL.md"))) {
+  if (!existsSync7(join7(cwd, "skills/browser-qa/SKILL.md"))) {
     findings.push({ level: "fail", area: "package", message: "skills/browser-qa/SKILL.md is missing." });
   }
-  return report("package", findings);
+  return report("package", findings, []);
 }
 
 // src/install/doctor.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
+import { join as join8 } from "path";
 var LEGACY_LEFTOVER_PATHS = [
   "AGENT_ROSTER.md",
   "COUNCIL.md",
@@ -583,11 +808,11 @@ function summarize(findings) {
   };
 }
 function read(cwd, relative2) {
-  const path = join6(cwd, relative2);
-  return existsSync7(path) ? readFileSync7(path, "utf8") : null;
+  const path = join8(cwd, relative2);
+  return existsSync8(path) ? readFileSync8(path, "utf8") : null;
 }
 function listLegacyLeftovers(cwd) {
-  return LEGACY_LEFTOVER_PATHS.filter((relative2) => existsSync7(join6(cwd, relative2)));
+  return LEGACY_LEFTOVER_PATHS.filter((relative2) => existsSync8(join8(cwd, relative2)));
 }
 function createDoctorReport(cwd) {
   const catalog = loadCatalog();
@@ -637,9 +862,33 @@ function createDoctorReport(cwd) {
     const meta = parseFrontmatter(content);
     if (!meta.tools || meta.tools.length === 0) {
       findings.push({ level: "fail", area: "agents", message: `${id} is missing a tools list.` });
-    } else {
-      findings.push({ level: "pass", area: "agents", message: `${id} declares tools.` });
+      continue;
+    }
+    const expectedRequired = packagedRequiredTools(id);
+    const actualRequired = meta.requiredTools ?? [];
+    const missingRequired = expectedRequired.filter((tool) => !actualRequired.includes(tool));
+    if (missingRequired.length > 0) {
+      findings.push({
+        level: "fail",
+        area: "agents",
+        message: `${id} dropped requiredTools: ${missingRequired.join(", ")}.`
+      });
+      continue;
     }
+    const requiredNotAllowed = actualRequired.filter((tool) => !meta.tools?.includes(tool));
+    if (requiredNotAllowed.length > 0) {
+      findings.push({
+        level: "fail",
+        area: "agents",
+        message: `${id} lists required tools that are not in tools: ${requiredNotAllowed.join(", ")}.`
+      });
+      continue;
+    }
+    findings.push({
+      level: "pass",
+      area: "agents",
+      message: expectedRequired.length > 0 ? `${id} keeps required tools.` : `${id} declares tools.`
+    });
   }
   const leftovers = listLegacyLeftovers(cwd);
   if (leftovers.length > 0) {
@@ -663,225 +912,41 @@ function createDoctorReport(cwd) {
     ok: findings.every((item) => item.level !== "fail")
   };
 }
-
-// src/install/install.ts
-import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
-import { join as join8 } from "path";
-
-// src/config/defaults.ts
-var PACKAGE_NAME = "@appsforgood/next-supabase-kit";
-var PACKAGE_VERSION = "0.4.2";
-var ROOT_DOCS = ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"];
-var CURSOR_RULE_FILE = {
-  source: "assistant-adapters/cursor-agent-kit.mdc",
-  target: ".cursor/rules/cursor-agent-kit.mdc"
-};
-var CLAUDE_TEMPLATE = "templates/next-supabase/CLAUDE.md";
-var USER_GUIDE_SOURCE = "USER_GUIDE.md";
-var USER_GUIDE_HTML_SOURCE = "USER_GUIDE.html";
-var AGENTS_DOC_SOURCE = "templates/next-supabase/AGENTS.md";
-
-// src/install/ide-activate.ts
-var ALLOWED = /* @__PURE__ */ new Set(["cursor", "claude", "codex", "copilot", "antigravity"]);
-var InvalidActivateTargetError = class extends Error {
-  constructor(invalid) {
-    super(`Unknown --activate target(s): ${invalid.join(", ")}. Allowed: cursor, claude, codex, copilot, antigravity, all.`);
-    this.invalid = invalid;
-    this.name = "InvalidActivateTargetError";
-  }
-  invalid;
-};
-function parseActivateTargets(raw) {
-  if (!raw || raw.length === 0) return [];
-  return normalizeTargets(raw.flatMap((value) => value.split(",")));
-}
-function normalizeTargets(targets) {
-  const normalized = /* @__PURE__ */ new Set();
-  const invalid = [];
-  for (const target of targets) {
-    const value = target.trim().toLowerCase();
-    if (!value) continue;
-    if (value === "all") {
-      for (const item of ALLOWED) normalized.add(item);
-      continue;
-    }
-    if (ALLOWED.has(value)) {
-      normalized.add(value);
-    } else {
-      invalid.push(target.trim());
-    }
-  }
-  if (invalid.length > 0) throw new InvalidActivateTargetError(invalid);
-  return [...normalized];
-}
-function activateIdeTargets(options) {
-  const cwd = options.cwd;
-  const packageRoot = findPackageRoot();
-  const targets = normalizeTargets(options.targets);
-  const force = Boolean(options.force);
-  const collector = emptyCollector();
-  const result = { activated: targets, ...collector };
-  if (targets.length === 0) return result;
-  if (targets.includes("cursor")) {
-    copyFromPackage(cwd, packageRoot, CURSOR_RULE_FILE.source, CURSOR_RULE_FILE.target, force, result);
-    generateCursorAgents(cwd, force, result);
-    generateCursorSkills(cwd, force, result);
-  }
-  if (targets.includes("claude")) {
-    copyFromPackage(cwd, packageRoot, CLAUDE_TEMPLATE, "CLAUDE.md", force, result);
-    generateClaudeAgents(cwd, force, result);
-  }
-  if (targets.includes("codex")) {
-    generateCodexAgents(cwd, force, result);
-  }
-  if (targets.includes("copilot")) {
-    generateCopilotInstructions(cwd, force, result);
-  }
-  if (targets.includes("antigravity")) {
-    generateAntigravityCommands(cwd, force, result);
-  }
-  return result;
-}
-
-// src/install/managed-assets.ts
-import { join as join7 } from "path";
-function listManagedAssets(packageRoot, options = {}) {
-  const assets = [
-    { target: "AGENTS.md", sourcePath: join7(packageRoot, AGENTS_DOC_SOURCE), category: "root-doc" },
-    { target: "USER_GUIDE.md", sourcePath: join7(packageRoot, USER_GUIDE_SOURCE), category: "root-doc" },
-    { target: "USER_GUIDE.html", sourcePath: join7(packageRoot, USER_GUIDE_HTML_SOURCE), category: "root-doc" },
-    { target: CURSOR_RULE_FILE.target, sourcePath: join7(packageRoot, CURSOR_RULE_FILE.source), category: "adapter" }
-  ];
-  const activated = new Set(options.activated ?? ["cursor"]);
-  if (activated.has("claude")) {
-    assets.push({
-      target: "CLAUDE.md",
-      sourcePath: join7(packageRoot, "templates/next-supabase/CLAUDE.md"),
-      category: "adapter"
-    });
+function packagedRequiredTools(id) {
+  try {
+    const source = readFileSync8(agentSourcePath(findPackageRoot(), id), "utf8");
+    return parseFrontmatter(source).requiredTools ?? [];
+  } catch {
+    return [];
   }
-  return assets;
 }
 
-// src/install/install.ts
-function initProject(options) {
-  const cwd = options.cwd;
-  const stack = options.stack ?? "next-supabase";
-  const packageRoot = findPackageRoot();
-  const force = Boolean(options.force);
-  ensureDir(join8(cwd, ".agent-kit", "conflicts"));
-  const result = {
-    ...emptyCollector(),
-    manifestPath: ".agent-kit/manifest.json"
-  };
-  const templateHashes = {};
-  const agentsDoc = readFileSync8(join8(packageRoot, AGENTS_DOC_SOURCE), "utf8");
-  const userGuide = readFileSync8(join8(packageRoot, USER_GUIDE_SOURCE), "utf8");
-  const userGuideHtml = readFileSync8(join8(packageRoot, USER_GUIDE_HTML_SOURCE), "utf8");
-  templateHashes["AGENTS.md"] = sha256(agentsDoc);
-  templateHashes["USER_GUIDE.md"] = sha256(userGuide);
-  templateHashes["USER_GUIDE.html"] = sha256(userGuideHtml);
-  recordCopy(
-    result,
-    copyTextWithConflict(join8(packageRoot, AGENTS_DOC_SOURCE), cwd, "AGENTS.md", {
-      force,
-      conflictRoot: join8(cwd, ".agent-kit", "conflicts")
-    })
-  );
-  recordCopy(
-    result,
-    copyTextWithConflict(join8(packageRoot, USER_GUIDE_SOURCE), cwd, "USER_GUIDE.md", {
-      force,
-      conflictRoot: join8(cwd, ".agent-kit", "conflicts")
-    })
-  );
-  recordCopy(
-    result,
-    copyTextWithConflict(join8(packageRoot, USER_GUIDE_HTML_SOURCE), cwd, "USER_GUIDE.html", {
-      force,
-      conflictRoot: join8(cwd, ".agent-kit", "conflicts")
-    })
-  );
-  if (options.legacyDocs) {
-    const legacyRoot = join8(packageRoot, "templates", stack);
-    const legacyDocs = ["SPEC.md", "DECISIONS.md", "DESIGN.md", "SECURITY.md", "TESTING.md", "QUALITY_GATES.md"];
-    for (const doc of legacyDocs) {
-      const source = join8(legacyRoot, doc);
-      if (!existsSync8(source)) continue;
-      recordCopy(
-        result,
-        copyTextWithConflict(source, cwd, doc, {
-          force,
-          conflictRoot: join8(cwd, ".agent-kit", "conflicts")
-        })
-      );
-    }
-  }
-  const activateTargets = parseActivateTargets(options.activate);
-  const targets = activateTargets.length > 0 ? activateTargets : ["cursor"];
-  result.activation = activateIdeTargets({ cwd, targets, force });
-  generatePortableSkills(cwd, force, result.activation);
-  result.copied.push(...result.activation.copied.filter((path) => !result.copied.includes(path)));
-  result.unchanged.push(...result.activation.unchanged.filter((path) => !result.unchanged.includes(path)));
-  result.conflicts.push(...result.activation.conflicts.filter((path) => !result.conflicts.includes(path)));
-  result.overwritten.push(...result.activation.overwritten.filter((path) => !result.overwritten.includes(path)));
-  const assets = listManagedAssets(packageRoot, { activated: targets });
-  const assetHashes = {};
-  for (const asset of assets) {
-    if (existsSync8(asset.sourcePath)) assetHashes[asset.target] = sha256(readFileSync8(asset.sourcePath, "utf8"));
-  }
-  for (const relative2 of [...result.copied, ...result.unchanged, ...result.overwritten]) {
-    const path = join8(cwd, relative2);
-    if (existsSync8(path) && !assetHashes[relative2]) {
-      assetHashes[relative2] = sha256(readFileSync8(path, "utf8"));
-    }
-  }
-  const catalog = loadCatalog(packageRoot);
-  const manifest = {
-    schemaVersion: 3,
-    packageName: PACKAGE_NAME,
-    packageVersion: PACKAGE_VERSION,
-    stack,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    docs: [...ROOT_DOCS],
-    activated: targets,
-    templateHashes,
-    assetHashes
-  };
-  writeText(join8(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(manifest, null, 2)}
-`);
-  writeText(
-    join8(cwd, ".agent-kit", "config.json"),
-    `${JSON.stringify({ stack, catalog: { defaultAgents: catalog.defaultAgents, defaultSkills: catalog.defaultSkills } }, null, 2)}
-`
-  );
-  if (!targets.includes("cursor")) {
-    recordCopy(
-      result,
-      copyTextWithConflict(join8(packageRoot, CURSOR_RULE_FILE.source), cwd, CURSOR_RULE_FILE.target, {
-        force,
-        conflictRoot: join8(cwd, ".agent-kit", "conflicts")
-      })
-    );
-  }
-  return result;
-}
-function readManifest(cwd) {
-  const manifestPath = join8(cwd, ".agent-kit", "manifest.json");
-  if (!existsSync8(manifestPath)) return null;
-  return JSON.parse(readFileSync8(manifestPath, "utf8"));
+// src/install/guide.ts
+import { existsSync as existsSync9 } from "fs";
+import { join as join9, resolve as resolve3 } from "path";
+import { pathToFileURL } from "url";
+function resolveUserGuideHtml(cwd) {
+  const local = join9(cwd, "USER_GUIDE.html");
+  if (existsSync9(local)) return locate(local, "cwd");
+  const packaged = join9(findPackageRoot(), "USER_GUIDE.html");
+  if (existsSync9(packaged)) return locate(packaged, "package");
+  throw new Error("USER_GUIDE.html is missing. Run agent-kit init, then open the file in a browser.");
+}
+function locate(path, source) {
+  const absolute = resolve3(path);
+  return { path: absolute, source, fileUrl: pathToFileURL(absolute).href };
 }
 
 // src/install/update.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { join as join10 } from "path";
 
 // src/install/file-update-plan.ts
-import { existsSync as existsSync9, readFileSync as readFileSync9 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 function planFileUpdate(input) {
   const sourceContent = readFileSync9(input.sourcePath, "utf8");
   const sourceHash = sha256(sourceContent);
-  if (!existsSync9(input.targetPath)) {
+  if (!existsSync10(input.targetPath)) {
     return { target: input.target, action: "created", reason: "File is missing locally.", sourceContent, sourceHash };
   }
   const localContent = readFileSync9(input.targetPath, "utf8");
@@ -1007,7 +1072,7 @@ function updateProject(options) {
   const assets = listManagedAssets(packageRoot, { activated });
   const files = [];
   for (const asset of assets) {
-    if (!existsSync10(asset.sourcePath)) continue;
+    if (!existsSync11(asset.sourcePath)) continue;
     const plan = planFileUpdate({
       target: asset.target,
       sourcePath: asset.sourcePath,
@@ -1041,11 +1106,11 @@ function updateProject(options) {
     files.push(...activationToUpdateFiles(activation));
     const nextHashes = { ...manifest.assetHashes };
     for (const asset of assets) {
-      if (existsSync10(asset.sourcePath)) nextHashes[asset.target] = sha256(readFileSync10(asset.sourcePath, "utf8"));
+      if (existsSync11(asset.sourcePath)) nextHashes[asset.target] = sha256(readFileSync10(asset.sourcePath, "utf8"));
     }
     for (const relative2 of [...activation.copied, ...activation.unchanged, ...activation.overwritten]) {
-      const path = join9(cwd, relative2);
-      if (existsSync10(path)) nextHashes[relative2] = sha256(readFileSync10(path, "utf8"));
+      const path = join10(cwd, relative2);
+      if (existsSync11(path)) nextHashes[relative2] = sha256(readFileSync10(path, "utf8"));
     }
     const next = {
       ...manifest,
@@ -1055,7 +1120,7 @@ function updateProject(options) {
       docs: ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"],
       assetHashes: nextHashes
     };
-    writeText(join9(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(next, null, 2)}
+    writeText(join10(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(next, null, 2)}
 `);
   } else {
     files.push({
@@ -1173,7 +1238,7 @@ add.command("agent <name>").description("Install one agent into .cursor/agents a
   line(`${result.action} ${result.target}`);
   if (!options.dryRun) detail(`Available agents: ${listAgents().join(", ")}`);
 });
-program.command("doctor").description("Check agents, skills, the screenshot QA rule, and leftover 0.3 council files.").option("--json", "Machine-readable output").action((options) => {
+program.command("doctor").description("Check agents, required tools, the screenshot QA rule, and leftover 0.3 council files.").option("--json", "Machine-readable output").action((options) => {
   const report2 = createDoctorReport(process.cwd());
   if (options.json) {
     printJson(report2);
@@ -1187,10 +1252,22 @@ program.command("doctor").description("Check agents, skills, the screenshot QA r
   if (!report2.ok) {
     fail("doctor found failures");
     process.exitCode = 1;
+  } else {
+    detail("Open USER_GUIDE.html in a browser. GitHub shows source, not the layout. Run agent-kit guide for the path.");
+  }
+});
+program.command("guide").description("Print the path to USER_GUIDE.html. Open it in a browser; GitHub shows source.").option("--json", "Machine-readable output").action((options) => {
+  const location = resolveUserGuideHtml(process.cwd());
+  if (options.json) {
+    printJson(location);
+    return;
   }
+  heading("user guide");
+  line(location.path);
+  detail("Open that file in a browser. GitHub shows HTML as source, not the layout.");
 });
 var adapter = program.command("adapter").description("Validate IDE adapter files.");
-adapter.command("validate [target]").description("Validate cursor, claude, codex, copilot, antigravity, or all").option("--json", "Machine-readable output").action((rawTarget, options) => {
+adapter.command("validate [target]").description("Validate activated IDEs, or one of cursor, claude, codex, copilot, antigravity").option("--json", "Machine-readable output").action((rawTarget, options) => {
   const target = rawTarget ?? "all";
   const allowed = ["cursor", "claude", "codex", "copilot", "antigravity", "all"];
   if (!allowed.includes(target)) {