@dadado/agent-kit-cli 5.15.0 → 5.16.0

package/dist/chunk-OZ4QV6LM.js

@@ -0,0 +1,1078 @@
+import {
+  NON_INTERACTIVE_ROOT_ARGS,
+  installL0,
+  syncFromManifest
+} from "./chunk-5OXPNVCF.js";
+import {
+  SkippedSymlinkError,
+  formatPersonalizationSkippedSymlinks,
+  logApplyStats
+} from "./chunk-HS7LVVLO.js";
+import {
+  REGISTRY_CLI_ARGS,
+  resolveRegistryFromCli
+} from "./chunk-XWPO3VYQ.js";
+import {
+  executeSafeReadinessFixes
+} from "./chunk-KI6ZHBPV.js";
+import {
+  writeReadinessSnapshot
+} from "./chunk-ZXKZBTXE.js";
+import {
+  writeClaudeSessionStartHook
+} from "./chunk-CGTE7DHN.js";
+import {
+  shouldUseWelcomeColor,
+  withCliProgress
+} from "./chunk-QTON2GQX.js";
+import {
+  createReadinessReport
+} from "./chunk-PNFF6OU3.js";
+import {
+  REPOSITORY_PROFILE_REL,
+  detectIde,
+  runScanner
+} from "./chunk-ZCTSUQRR.js";
+import {
+  GIT_PLATFORM_META
+} from "./chunk-F6C3GFKV.js";
+import {
+  logger
+} from "./chunk-ZB43YMHW.js";
+import {
+  RootRefusedError,
+  classifyInstallError,
+  confirmProjectRoot,
+  isNonInteractive,
+  npxPinned,
+  pathCliStatus,
+  syncPathCliToRuntime
+} from "./chunk-VGZBARQC.js";
+import {
+  assessEnvironment
+} from "./chunk-4IWG5CVE.js";
+import {
+  warnIfRunningCliBehindNpm
+} from "./chunk-XZZAVHH4.js";
+import {
+  DOMAIN_PACK_IDS,
+  allPacks,
+  allSkills,
+  buildManifest,
+  contentHash,
+  emptyStats,
+  installPack,
+  installSkill,
+  isRealWriteTargetContained,
+  loadAgentKitManifest,
+  loadManagedHashLedger,
+  loadPackManifest,
+  loadRegistry,
+  mergeStats,
+  packMemberFileTargets,
+  resolveContained,
+  resolveProtectedGlobs,
+  saveManagedHashLedger,
+  saveManifest,
+  shouldPreserveCustomizedOverlay,
+  skillTargetDir
+} from "./chunk-VS2JD2XC.js";
+import {
+  KIT_VERSION,
+  pinnedCliSpec
+} from "./chunk-7HDQEK6T.js";
+import {
+  ensureDir,
+  fileExists,
+  writeJson
+} from "./chunk-77V75A7O.js";
+
+// src/commands/install.ts
+import path5 from "path";
+import { defineCommand } from "citty";
+import { bold, cyan, green, options as koloristOptions } from "kolorist";
+
+// src/generator/personalization.ts
+import { readFile as readFile2, writeFile as writeFile4 } from "fs/promises";
+import path4 from "path";
+
+// src/generator/claude-command-adapters.ts
+import { readFile, readdir, writeFile } from "fs/promises";
+import path from "path";
+var CURSOR_COMMANDS_DIR_REL = ".cursor/commands";
+var CLAUDE_COMMANDS_DIR_REL = ".claude/commands";
+var RESERVED_ADAPTER_NAMES = /* @__PURE__ */ new Set(["agent-kit"]);
+function parseCommandFrontmatter(name, raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+  if (!match) return null;
+  const body = match[1] ?? "";
+  const descMatch = /^description:\s*(.+)$/m.exec(body);
+  if (!descMatch) return null;
+  const description = (descMatch[1] ?? "").trim();
+  if (!description) return null;
+  return { name, description };
+}
+var CLAUDE_HITL_FALLBACK = `Cursor "Ask questions" is unavailable here: use AskUserQuestion when possible, else print one line \`HITL_GATE: <ask-id> | <label 1> | <label 2> | ...\` immediately followed by the same labels as one numbered list, one list per message, and WAIT for the answer (ask-id and labels: \`.cursor/skills/core/hitl-gates/SKILL.md\`). A headless reply arrives as \`HITL_REPLY: <ask-id> | operator reply <n> | <label>\`; cite that line as the Ask provenance.`;
+var MODEL_INVOCATION_DISABLED = /* @__PURE__ */ new Set([
+  "git-prod",
+  "kit-prod",
+  "backlog-delete",
+  "backlog-cancel",
+  "archive-plan",
+  "hotfix",
+  "run-plan-all"
+]);
+function renderClaudeCommandAdapter(command) {
+  const invocation = MODEL_INVOCATION_DISABLED.has(command.name) ? "disable-model-invocation: true\n" : "";
+  return `---
+description: ${command.description}
+${invocation}---
+
+Read \`.cursor/commands/${command.name}.md\` now and follow that contract exactly \u2014 it is the source of truth for /${command.name}; this file is only a thin adapter for Claude Code.
+
+Adapter rules (Claude Code CLI):
+- ${CLAUDE_HITL_FALLBACK}
+- Skip or cancel means stop.
+- Never \`/git-prod\` without an explicit operator yes.
+- Do not clone Cursor hooks or invent behavior beyond the SoT file.
+`;
+}
+async function discoverInstalledCommands(rootDir) {
+  const dir = path.join(rootDir, CURSOR_COMMANDS_DIR_REL);
+  let entries;
+  try {
+    entries = (await readdir(dir)).filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const commands = [];
+  for (const file of entries.sort()) {
+    const name = file.slice(0, -3);
+    if (RESERVED_ADAPTER_NAMES.has(name)) continue;
+    try {
+      const raw = await readFile(path.join(dir, file), "utf8");
+      const parsed = parseCommandFrontmatter(name, raw);
+      if (parsed) commands.push(parsed);
+    } catch {
+    }
+  }
+  return commands;
+}
+async function generateClaudeCommandAdapters(rootDir) {
+  const commands = await discoverInstalledCommands(rootDir);
+  if (commands.length === 0) return [];
+  const ledger = await loadManagedHashLedger(rootDir);
+  const results = [];
+  let ledgerDirty = false;
+  for (const command of commands) {
+    const relPath = path.posix.join(CLAUDE_COMMANDS_DIR_REL, `${command.name}.md`);
+    const rendered = renderClaudeCommandAdapter(command);
+    const abs = resolveContained(rootDir, relPath);
+    if (!await isRealWriteTargetContained(rootDir, abs)) {
+      results.push({ relativePath: relPath, status: "skipped-symlink" });
+      continue;
+    }
+    if (!await fileExists(abs)) {
+      await ensureDir(path.dirname(abs));
+      await writeFile(abs, rendered, "utf8");
+      ledger.hashes[relPath] = contentHash(rendered);
+      ledgerDirty = true;
+      results.push({ relativePath: relPath, status: "applied" });
+      continue;
+    }
+    const localContent = await readFile(abs, "utf8");
+    if (localContent === rendered) {
+      if (ledger.hashes[relPath] !== contentHash(rendered)) {
+        ledger.hashes[relPath] = contentHash(rendered);
+        ledgerDirty = true;
+      }
+      results.push({ relativePath: relPath, status: "unchanged" });
+      continue;
+    }
+    if (shouldPreserveCustomizedOverlay(localContent, ledger.hashes[relPath])) {
+      results.push({ relativePath: relPath, status: "preserved-customized" });
+      continue;
+    }
+    await writeFile(abs, rendered, "utf8");
+    ledger.hashes[relPath] = contentHash(rendered);
+    ledgerDirty = true;
+    results.push({ relativePath: relPath, status: "refreshed" });
+  }
+  if (ledgerDirty) await saveManagedHashLedger(rootDir, ledger);
+  return results;
+}
+
+// src/generator/claude-kit-load.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import path2 from "path";
+var CLAUDE_MD_REL = "CLAUDE.md";
+var AGENT_KIT_COMMAND_REL = ".claude/commands/agent-kit.md";
+function renderClaudeMd() {
+  return `# Agent Kit (Claude Code)
+
+This repository uses Agent Kit / Mission Control. Before rediscovering the tree, read the shared sources of truth (paths below are pointers; do not treat this file as a second rulebook).
+
+## Read first
+
+1. \`AGENTS.md\` - cross-IDE contract
+2. \`.cursor/project-context.md\` - verified repository facts (derived; prefer code, tests, SHAs when docs conflict)
+3. \`.cursor/HANDOFF.md\` - if present: active plan, next to-do, queue fields
+4. \`.cursor/commands/\` - slash catalog (Cursor). Follow the same HITL contracts here.
+
+Mid-session refresh: \`/agent-kit\`.
+
+## HITL
+
+${CLAUDE_HITL_FALLBACK} Skip or cancel means stop. Never \`/git-prod\` without an explicit operator yes.
+
+## Commit messages
+
+Never append \`Co-Authored-By: Claude ...\` or \`Claude-Session: https://claude.ai/code/...\` (or any session-ID trailer) to commit messages, PR descriptions, or PR bodies in this repo. This overrides the harness's default git-commit template. Plain Conventional Commits messages only.
+
+## Non-goals
+
+Do not clone other Cursor hooks (Claude gets only the SessionStart context and PreToolUse(Bash) guard hooks); never \`/git-prod\` from a headless tick.
+`;
+}
+function renderAgentKitCommand() {
+  return `---
+description: Load Agent Kit session context (HANDOFF, project-context, commands). Manual refresh only.
+disable-model-invocation: true
+---
+
+Read these files if they exist. Prefer a one-shot ASCII Mission Control snapshot over a plain HANDOFF paraphrase.
+
+1. Run \`agent-kit mission-control --once\` (or \`npx @dadado/agent-kit-cli mission-control --once\`) in the project root and paste the stdout frame as the snapshot. Do not start a live loop: Claude Code cannot sustain one across turns.
+2. If that command is missing or fails, fall back to reading:
+   - \`AGENTS.md\`
+   - \`.cursor/project-context.md\`
+   - \`.cursor/HANDOFF.md\`
+   - The plan file named in HANDOFF \`- **Plan:**\` under \`.cursor/plans/\`
+
+If HANDOFF is missing, say so and point at \`/agent-kit-onboard\` or \`/start-project\` rather than inventing a plan.
+
+HITL: numbered-list fallback for Ask questions labels. Never \`/git-prod\` from this skill.
+
+Non-goals: not audits / \`/plan-external-review\`, not a second tick dialect, not Cursor hook clones beyond the SessionStart and PreToolUse(Bash) adapters, not a continuous TUI loop.
+`;
+}
+async function writeUnlessExists(rootDir, relativePath, content) {
+  const target = path2.join(rootDir, relativePath);
+  if (await fileExists(target)) {
+    return { relativePath, status: "skipped-customized" };
+  }
+  await ensureDir(path2.dirname(target));
+  await writeFile2(target, content, "utf8");
+  return { relativePath, status: "applied" };
+}
+async function generateClaudeKitLoadArtifacts(rootDir) {
+  return Promise.all([
+    writeUnlessExists(rootDir, CLAUDE_MD_REL, renderClaudeMd()),
+    writeUnlessExists(rootDir, AGENT_KIT_COMMAND_REL, renderAgentKitCommand())
+  ]);
+}
+
+// src/generator/vscode.ts
+import { writeFile as writeFile3 } from "fs/promises";
+import path3 from "path";
+
+// src/generator/platform.ts
+function gitProviderLabel(profile) {
+  const p = profile.git.provider;
+  if (!p || p === "other") return "Git";
+  const labels = {
+    github: "GitHub",
+    gitlab: "GitLab",
+    bitbucket: "Bitbucket",
+    "azure-devops": "Azure DevOps",
+    gitea: "Gitea"
+  };
+  return labels[p] ?? "Git";
+}
+function prTerminology(profile) {
+  const p = profile.git.provider;
+  if (!p || p === "other") return "PR/MR";
+  return GIT_PLATFORM_META[p]?.prTerm ?? "PR/MR";
+}
+
+// src/generator/vscode.ts
+async function generateVSCodeArtifacts(profile) {
+  const results = [];
+  const vscodeDir = path3.join(profile.rootDir, ".vscode");
+  const githubDir = path3.join(profile.rootDir, ".github");
+  await Promise.all([ensureDir(vscodeDir), ensureDir(githubDir)]);
+  const settingsPath = path3.join(vscodeDir, "settings.json");
+  if (await fileExists(settingsPath)) {
+    results.push({ relativePath: ".vscode/settings.json", status: "skipped-customized" });
+  } else {
+    await writeFile3(
+      settingsPath,
+      `${JSON.stringify(
+        {
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit"
+          },
+          "files.autoSave": "afterDelay"
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+    results.push({ relativePath: ".vscode/settings.json", status: "applied" });
+  }
+  const provider = gitProviderLabel(profile);
+  const prTerm = prTerminology(profile);
+  const copilotPath = path3.join(githubDir, "copilot-instructions.md");
+  if (await fileExists(copilotPath)) {
+    results.push({ relativePath: ".github/copilot-instructions.md", status: "skipped-customized" });
+  } else {
+    await writeFile3(
+      copilotPath,
+      `# Copilot Instructions
+
+- Keep code changes small and testable.
+- Use Conventional Commits (feat:, fix:, docs:, etc.).
+- Prefer security-safe defaults.
+- Git platform: ${provider}. Always create a ${prTerm} for review.
+`,
+      "utf8"
+    );
+    results.push({ relativePath: ".github/copilot-instructions.md", status: "applied" });
+  }
+  if (profile.ide.plan === "vscode-pro") {
+    const securityPath = path3.join(vscodeDir, "security-review.agent.md");
+    if (await fileExists(securityPath)) {
+      results.push({
+        relativePath: ".vscode/security-review.agent.md",
+        status: "skipped-customized"
+      });
+    } else {
+      await writeFile3(
+        securityPath,
+        "# Security Review Agent\n\nSpecialized mode for security review.\n",
+        "utf8"
+      );
+      results.push({ relativePath: ".vscode/security-review.agent.md", status: "applied" });
+    }
+  }
+  return results;
+}
+
+// src/generator/personalization.ts
+var PERSONALIZATION_CONTRACT_VERSION = 1;
+var CONTEXT_PATH = ".cursor/project-context.md";
+var AGENTS_PATH = "AGENTS.md";
+var RESULT_PATH = ".cursor/context/personalization.json";
+function uniqueEvidence(evidence) {
+  const seen = /* @__PURE__ */ new Set();
+  return evidence.filter((item) => {
+    const key = `${item.source}:${item.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function purposeEvidence(profile) {
+  if (profile.purpose.confidence === "low") return [];
+  return profile.purpose.evidence;
+}
+function contextEvidence(profile, pattern) {
+  return profile.context.sources.filter((item) => pattern.test(item.value));
+}
+function readinessEvidence(report, checkId) {
+  return report.pillars.flatMap((pillar) => pillar.checks).filter((check) => check.id === checkId).flatMap((check) => check.evidence);
+}
+function hasPurpose(profile, purposes) {
+  return purposes.some(
+    (purpose) => profile.purpose.value === purpose || profile.purpose.categories.includes(purpose)
+  );
+}
+function candidate(kind, id, evidence, status) {
+  const verified = uniqueEvidence(evidence);
+  return verified.length > 0 ? { kind, id, status, evidence: verified } : null;
+}
+function componentAvailable(index, item) {
+  if (item.kind === "skill") return allSkills(index).some((entry) => entry.id === item.id);
+  if (item.kind === "pack") return allPacks(index).some((entry) => entry.id === item.id);
+  if (item.kind === "agent" || item.kind === "command") {
+    return (index.artifacts ?? []).some(
+      (entry) => entry.kind === item.kind && entry.id === item.id
+    );
+  }
+  return true;
+}
+function buildPersonalizationPlan(profile, report, registry) {
+  const items = [];
+  const purpose = purposeEvidence(profile);
+  const packageEvidence = profile.stack.packageManagerEvidence ?? [];
+  const n8nEvidence = [
+    ...contextEvidence(profile, /(^|[/.-])n8n([/.-]|$)/i),
+    ...purpose.filter((item) => /n8n/i.test(item.value))
+  ];
+  const sqlEvidence = [
+    ...contextEvidence(profile, /(^|[/.-])(sql|schema|migration)([/.-]|$)/i),
+    ...purpose.filter((item) => /\bsql\b/i.test(item.value))
+  ];
+  const promptEvidence = contextEvidence(profile, /(^|[/.-])prompts?([/.-]|$)/i);
+  const ciEvidence = profile.infra.ciFiles.map((value) => ({ source: "file", value }));
+  const infraEvidence = [
+    ...ciEvidence,
+    ...profile.infra.infrastructureFiles.map((value) => ({ source: "file", value })),
+    ...profile.infra.deploymentFiles.map((value) => ({ source: "file", value }))
+  ];
+  if (hasPurpose(profile, ["documentation", "knowledge"])) {
+    items.push(candidate("skill", "docs-repo", purpose, "applied"));
+  }
+  if (profile.stack.language.toLowerCase() === "node" && packageEvidence.length > 0) {
+    items.push(candidate("skill", "cursor-skills-node", packageEvidence, "applied"));
+  }
+  if (n8nEvidence.length > 0) {
+    items.push(candidate("skill", "n8n-workflows", n8nEvidence, "applied"));
+  } else if (hasPurpose(profile, ["automation"])) {
+    items.push(candidate("skill", "n8n-workflows", purpose, "recommended-confirmation"));
+  }
+  if (sqlEvidence.length > 0) {
+    items.push(candidate("skill", "sql-postgres", sqlEvidence, "applied"));
+  } else if (profile.services.database?.toLowerCase().includes("postgres")) {
+    items.push(
+      candidate(
+        "skill",
+        "sql-postgres",
+        [{ source: "configuration", value: `database:${profile.services.database}` }],
+        "recommended-confirmation"
+      )
+    );
+  }
+  if (promptEvidence.length > 0) {
+    items.push(candidate("skill", "prompts-markdown", promptEvidence, "applied"));
+  }
+  if (infraEvidence.length > 0) {
+    items.push(candidate("pack", "devops", infraEvidence, "applied"));
+  }
+  if (profile.stack.testCommands.length > 0 && packageEvidence.length > 0) {
+    items.push(candidate("pack", "quality", packageEvidence, "applied"));
+    items.push(candidate("agent", "test-suites", packageEvidence, "applied"));
+  }
+  const pmTools = (profile.services.projectManagement ?? []).filter((tool) => tool !== "none");
+  if (pmTools.length > 0) {
+    items.push(
+      candidate(
+        "pack",
+        "project-management",
+        pmTools.map((tool) => ({ source: "configuration", value: `projectManagement:${tool}` })),
+        "recommended-confirmation"
+      )
+    );
+  }
+  const safetyEvidence = readinessEvidence(report, "safety.secrets").filter(
+    (item) => item.value.startsWith("tracked:")
+  );
+  if (safetyEvidence.length > 0) {
+    items.push(candidate("pack", "cybersec", safetyEvidence, "recommended-confirmation"));
+  }
+  items.push(
+    candidate(
+      "command",
+      "start-project",
+      readinessEvidence(report, "agent-kit.context"),
+      "applied"
+    )
+  );
+  const availableItems = items.filter((item) => item !== null);
+  return availableItems.map(
+    (item) => componentAvailable(registry, item) ? item : { ...item, status: "unavailable" }
+  ).sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+}
+var INSTALLED_SKILL_STATUSES = /* @__PURE__ */ new Set(["applied", "skipped-customized"]);
+function installedSkillItems(items, installedIds = []) {
+  const rows = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    if (item.kind !== "skill" || !INSTALLED_SKILL_STATUSES.has(item.status)) continue;
+    if (seen.has(item.id)) continue;
+    seen.add(item.id);
+    rows.push(item);
+  }
+  for (const id of installedIds) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    rows.push({
+      kind: "skill",
+      id,
+      status: "applied",
+      evidence: [{ source: "configuration", value: `.cursor/agent-kit.json skills[]:${id}` }]
+    });
+  }
+  return rows.sort((left, right) => left.id.localeCompare(right.id));
+}
+function relevantSkillTableRows(skills) {
+  if (skills.length === 0) {
+    return ["| (none yet) | No installed or project-owned skills detected | \u2014 |"];
+  }
+  return skills.map((skill) => {
+    const label = skill.path ?? skill.id;
+    const role = skill.status === "skipped-customized" ? "Already present (customized)" : "Installed by personalization";
+    const evidence = skill.path ?? skill.evidence[0]?.value ?? "personalization";
+    return `| ${label} | ${role} | ${evidence} |`;
+  });
+}
+function renderProjectContext(profile, skillItems = []) {
+  const sections = ["# Project Context", "", "Verified repository facts:"];
+  const purpose = purposeEvidence(profile);
+  if (purpose.length > 0 && profile.purpose.value !== "unknown") {
+    sections.push(`- Purpose: ${profile.purpose.value}.`);
+  }
+  const packageEvidence = profile.stack.packageManagerEvidence ?? [];
+  if (packageEvidence.length > 0) {
+    sections.push(`- Runtime family: ${profile.stack.language}.`);
+    if (profile.stack.packageManager) {
+      sections.push(`- Package manager: ${profile.stack.packageManager}.`);
+    }
+  }
+  if (profile.git.provider && (profile.git.providerEvidence?.length ?? 0) > 0) {
+    sections.push(`- Git provider: ${profile.git.provider}.`);
+  }
+  if (profile.infra.ci !== "none" && profile.infra.ciFiles.length > 0) {
+    sections.push(`- CI: ${profile.infra.ci}.`);
+  }
+  sections.push(
+    "",
+    "## Relevant skills",
+    "",
+    "Installed and project-owned skills for this repository. Prefer `.cursor/agent-kit.json` `skills[]` as the install index; project-only domain skills may live under `.cursor/skills/domain/`.",
+    "",
+    "| Skill / path | Role | Evidence |",
+    "|--------------|------|----------|",
+    ...relevantSkillTableRows(installedSkillItems(skillItems))
+  );
+  if (profile.context.sources.length > 0) {
+    sections.push("", "## Sources", ...profile.context.sources.map((item) => `- ${item.value}`));
+  }
+  return `${sections.join("\n")}
+`;
+}
+async function createOwnedFile(rootDir, relativePath, content, evidence) {
+  const target = path4.join(rootDir, relativePath);
+  if (await fileExists(target)) {
+    return {
+      kind: "file",
+      id: relativePath,
+      path: relativePath,
+      status: "skipped-customized",
+      evidence
+    };
+  }
+  await ensureDir(path4.dirname(target));
+  await writeFile4(target, content, "utf8");
+  return {
+    kind: "file",
+    id: relativePath,
+    path: relativePath,
+    status: "applied",
+    evidence
+  };
+}
+async function packTargets(registryRoot, packId) {
+  const manifest = await loadPackManifest(registryRoot, packId);
+  const targets = [];
+  for (const member of manifest.members) {
+    for (const { targetRel } of await packMemberFileTargets(registryRoot, member)) {
+      targets.push(targetRel);
+    }
+  }
+  return targets;
+}
+async function existingTargets(projectRoot, targets) {
+  const checks = await Promise.all(
+    targets.map(
+      async (target) => await fileExists(path4.join(projectRoot, target)) ? target : null
+    )
+  );
+  return checks.filter((target) => target !== null);
+}
+async function applyPersonalization(input) {
+  const planned = buildPersonalizationPlan(input.profile, input.report, input.registry);
+  const stats = emptyStats();
+  const componentResults = [];
+  const protectedPaths = new Set(input.manifest.protected ?? []);
+  const packs = new Set(input.manifest.packs ?? []);
+  const skills = new Set(input.manifest.skills ?? []);
+  const notRecorded = [];
+  for (const item of planned) {
+    if (item.status !== "applied") {
+      componentResults.push(item);
+      continue;
+    }
+    if (item.kind === "skill") {
+      const skill = allSkills(input.registry).find((entry) => entry.id === item.id);
+      if (!skill) {
+        componentResults.push({ ...item, status: "unavailable" });
+        continue;
+      }
+      const target = path4.posix.join(skillTargetDir(skill.path, skill.id), "SKILL.md");
+      if (await fileExists(path4.join(input.rootDir, target))) {
+        componentResults.push({ ...item, status: "skipped-customized", path: target });
+        protectedPaths.add(target);
+        continue;
+      }
+      const skillStats = await installSkill(input.registryRoot, input.rootDir, skill);
+      mergeStats(stats, skillStats);
+      if (skillStats.skippedSymlink.length > 0) {
+        notRecorded.push(item.id);
+        componentResults.push({ ...item, status: "unavailable", path: target });
+        continue;
+      }
+      skills.add(item.id);
+      componentResults.push({ ...item, path: target });
+      continue;
+    }
+    if (item.kind === "pack") {
+      const targets = await packTargets(input.registryRoot, item.id);
+      const customizedTargets = await existingTargets(input.rootDir, targets);
+      const packStats = await installPack(input.registryRoot, input.rootDir, item.id, {
+        protectedGlobs: customizedTargets
+      });
+      mergeStats(stats, packStats);
+      for (const target of customizedTargets) protectedPaths.add(target);
+      if (packStats.skippedSymlink.length > 0) {
+        notRecorded.push(item.id);
+        componentResults.push({ ...item, status: "unavailable" });
+        continue;
+      }
+      packs.add(item.id);
+      componentResults.push(
+        customizedTargets.length > 0 ? { ...item, status: "skipped-customized" } : item
+      );
+      continue;
+    }
+    componentResults.push(item);
+  }
+  const profileEvidence = uniqueEvidence([
+    ...purposeEvidence(input.profile),
+    ...input.profile.stack.packageManagerEvidence ?? [],
+    ...input.profile.git.providerEvidence ?? [],
+    ...input.profile.context.sources
+  ]);
+  const fileResults = await Promise.all([
+    createOwnedFile(
+      input.rootDir,
+      CONTEXT_PATH,
+      renderProjectContext(input.profile, installedSkillItems(componentResults, skills)),
+      profileEvidence
+    ),
+    createOwnedFile(
+      input.rootDir,
+      AGENTS_PATH,
+      "# Repository Agent Guidance\n\nUse `.cursor/project-context.md` for verified repository facts. Preserve existing project-owned guidance and request confirmation before adding optional integrations.\n",
+      profileEvidence
+    )
+  ]);
+  protectedPaths.add(CONTEXT_PATH);
+  protectedPaths.add(AGENTS_PATH);
+  const claudeResults = await generateClaudeKitLoadArtifacts(input.rootDir);
+  const claudeItems = claudeResults.map((artifact) => {
+    protectedPaths.add(artifact.relativePath);
+    return {
+      kind: "file",
+      id: artifact.relativePath,
+      path: artifact.relativePath,
+      status: artifact.status,
+      evidence: profileEvidence
+    };
+  });
+  const claudeCommandItems = [];
+  let claudeSessionStartInstructions;
+  if (input.claudeAdapters) {
+    const adapterResults = await generateClaudeCommandAdapters(input.rootDir);
+    for (const artifact of adapterResults) {
+      protectedPaths.add(artifact.relativePath);
+      claudeCommandItems.push({
+        kind: "file",
+        id: artifact.relativePath,
+        path: artifact.relativePath,
+        // Overlay statuses (applied/unchanged/refreshed/preserved-customized)
+        // fold onto the shared PersonalizationStatus union: anything written
+        // or already current reads as "applied"; a hand-edited adapter left
+        // alone reads as "skipped-customized" (same meaning as elsewhere in
+        // this file — never silently clobbered).
+        status: artifact.status === "skipped-symlink" ? "unavailable" : artifact.status === "preserved-customized" ? "skipped-customized" : "applied",
+        evidence: profileEvidence
+      });
+      if (artifact.status === "skipped-symlink") stats.skippedSymlink.push(artifact.relativePath);
+    }
+    const hookResult = await writeClaudeSessionStartHook(input.rootDir);
+    protectedPaths.add(hookResult.relativePath);
+    claudeCommandItems.push({
+      kind: "file",
+      id: hookResult.relativePath,
+      path: hookResult.relativePath,
+      // "unavailable" (existing .claude/settings.json unparseable) is a real
+      // PersonalizationStatus value already; every other hook status folds
+      // onto "applied" the same way the command-adapter statuses do above.
+      status: hookResult.status === "unavailable" || hookResult.status === "skipped-symlink" ? "unavailable" : "applied",
+      evidence: profileEvidence
+    });
+    if (hookResult.status === "skipped-symlink") stats.skippedSymlink.push(hookResult.relativePath);
+    if (hookResult.ledgerPath) {
+      protectedPaths.add(hookResult.ledgerPath);
+      claudeCommandItems.push({
+        kind: "file",
+        id: hookResult.ledgerPath,
+        path: hookResult.ledgerPath,
+        status: "applied",
+        evidence: profileEvidence
+      });
+    }
+    if (hookResult.status === "unavailable" && hookResult.instructions) {
+      claudeSessionStartInstructions = hookResult.instructions;
+    }
+  }
+  const ideDetection = await detectIde(input.rootDir);
+  if (ideDetection.ide === "vscode" || ideDetection.ide === "other") {
+    const git = {
+      providerKind: input.profile.git.providerKind ?? "unknown",
+      providerConfidence: input.profile.git.providerConfidence ?? "low",
+      providerEvidence: input.profile.git.providerEvidence ?? [],
+      remotes: input.profile.git.remotes ?? [],
+      mode: input.profile.git.mode ?? "none",
+      workflow: input.profile.git.workflow ?? "unknown",
+      isDirty: input.profile.git.isDirty ?? false,
+      hasLocalStaging: input.profile.git.hasLocalStaging ?? false,
+      hasRemoteStaging: input.profile.git.hasRemoteStaging ?? false,
+      provider: input.profile.git.provider,
+      remoteUrl: input.profile.git.remoteUrl,
+      remoteName: input.profile.git.remoteName,
+      currentBranch: input.profile.git.currentBranch,
+      defaultBranch: input.profile.git.defaultBranch
+    };
+    const projectProfile = {
+      rootDir: input.rootDir,
+      stack: input.profile.stack,
+      git,
+      ide: ideDetection,
+      infra: input.profile.infra,
+      services: input.profile.services
+    };
+    const vscodeResults = await generateVSCodeArtifacts(projectProfile);
+    const ideEvidence = [
+      { source: "derived", value: `ide:${ideDetection.ide}` }
+    ];
+    for (const artifact of vscodeResults) {
+      protectedPaths.add(artifact.relativePath);
+      componentResults.push({
+        kind: "file",
+        id: artifact.relativePath,
+        path: artifact.relativePath,
+        status: artifact.status,
+        evidence: ideEvidence
+      });
+    }
+  }
+  const result = {
+    contractVersion: PERSONALIZATION_CONTRACT_VERSION,
+    generatorVersion: input.generatorVersion,
+    repositoryFingerprint: input.report.repositoryFingerprint,
+    items: [...fileResults, ...claudeItems, ...claudeCommandItems, ...componentResults],
+    protectedPaths: [...protectedPaths].sort(),
+    ...claudeSessionStartInstructions ? { claudeSessionStartInstructions } : {}
+  };
+  await writeJson(path4.join(input.rootDir, RESULT_PATH), result);
+  return {
+    result,
+    stats,
+    notRecorded,
+    manifest: {
+      ...input.manifest,
+      packs: [...packs].sort(),
+      skills: [...skills].sort(),
+      protected: result.protectedPaths,
+      personalization: {
+        contractVersion: PERSONALIZATION_CONTRACT_VERSION,
+        generatorVersion: input.generatorVersion,
+        origin: "repository-profile",
+        resultPath: RESULT_PATH
+      }
+    }
+  };
+}
+async function readRepositoryProfile(rootDir) {
+  const target = path4.join(rootDir, REPOSITORY_PROFILE_REL);
+  if (!await fileExists(target)) return null;
+  return JSON.parse(await readFile2(target, "utf8"));
+}
+
+// src/commands/install.ts
+function parsePackList(raw) {
+  if (!raw?.trim()) return [];
+  return [
+    ...new Set(
+      raw.split(",").map((s) => s.trim()).filter(Boolean)
+    )
+  ];
+}
+function nextStepAfterInstall(pendingActions) {
+  return pendingActions > 0 ? "Next: run /agent-kit-onboard in Cursor to resolve the first pending action." : "Next: run /start-project in Cursor when you have a deliverable.";
+}
+function printReadinessNarrative(result) {
+  const { summary, pendingActions } = result.readiness;
+  const fixed = result.safeChanges.filter((change) => change.status === "applied").length;
+  console.log("\nRepository readiness");
+  console.log(
+    `  ready: ${summary.ready}, choices: ${summary.needs_choice}, manual: ${summary.manual}, blocked: ${summary.blocked}`
+  );
+  console.log(`  safe fixes applied: ${fixed}`);
+  console.log(`  pending actions: ${pendingActions.length}`);
+  console.log(nextStepAfterInstall(pendingActions.length));
+}
+function paint(fn, text) {
+  const prevEnabled = koloristOptions.enabled;
+  const prevSupportLevel = koloristOptions.supportLevel;
+  koloristOptions.enabled = true;
+  koloristOptions.supportLevel = 3;
+  try {
+    return fn(text);
+  } finally {
+    koloristOptions.enabled = prevEnabled;
+    koloristOptions.supportLevel = prevSupportLevel;
+  }
+}
+function printInstallEpilogue(env, options = {}) {
+  const print = options.print ?? ((line) => console.log(line));
+  const color = options.color ?? shouldUseWelcomeColor();
+  const runtimeVersion = options.runtimeVersion ?? KIT_VERSION;
+  const status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    const line = `PATH \`agent-kit\` is v${env.binVersion ?? runtimeVersion}. Run it directly, e.g. \`agent-kit doctor\`.`;
+    print(color ? paint(green, line) : line);
+    return;
+  }
+  if (status === "behind" || status === "unknown") {
+    const line = `Keep using ${npxPinned(runtimeVersion, "<subcommand>")} until PATH is v${runtimeVersion}.`;
+    print(color ? paint(green, line) : line);
+    return;
+  }
+  const divider = "\u2500".repeat(60);
+  const body = [
+    "You ran this through npx, so a bare `agent-kit` isn't on PATH yet.",
+    'If you try `agent-kit <subcommand>` next, you will see "command not',
+    'found". Pick one:',
+    "",
+    "  1. Keep using npx (works right now, no action needed)",
+    `     ${npxPinned(runtimeVersion, "<subcommand>")}`,
+    "",
+    "  2. Put a bare `agent-kit` on PATH",
+    `     ${npxPinned(runtimeVersion, "setup-global")}`,
+    "     (fixes a root-owned npm prefix if that's the blocker, or just installs)",
+    "",
+    "  3. Manual steps",
+    "     See docs/getting-started.md (Troubleshooting npm failures), or:",
+    "       mkdir -p ~/.npm-global",
+    '       npm config set prefix "~/.npm-global"',
+    '       export PATH="~/.npm-global/bin:$PATH"',
+    `       npm i -g ${pinnedCliSpec(runtimeVersion)}`
+  ];
+  print(color ? paint(cyan, divider) : divider);
+  const heading = "Heads up: a bare `agent-kit` command won't work yet";
+  print(color ? paint(bold, paint(cyan, heading)) : heading);
+  for (const line of body) print(line);
+  print(color ? paint(cyan, divider) : divider);
+}
+async function printPostInstallSummary(result) {
+  printReadinessNarrative(result);
+  const env = await assessEnvironment();
+  const sync = await syncPathCliToRuntime({ runtimeVersion: KIT_VERSION, env });
+  for (const line of sync.lines) console.log(line);
+  printInstallEpilogue(sync.env, { runtimeVersion: KIT_VERSION });
+}
+async function performInstall(options) {
+  const projectRoot = path5.resolve(options.cwd);
+  const packs = parsePackList(options.pack);
+  const existing = await loadAgentKitManifest(projectRoot, { onWarning: logger.warn });
+  const registry = await resolveRegistryFromCli({
+    cwd: projectRoot,
+    registry: options.registry,
+    url: options.url,
+    ref: options.ref,
+    refresh: options.refresh,
+    manifest: existing
+  });
+  try {
+    const draft = buildManifest({
+      version: KIT_VERSION,
+      profile: options.profile ?? existing?.profile ?? "default",
+      packs: packs.length > 0 ? packs : existing?.packs,
+      skills: existing?.skills,
+      protected: existing?.protected,
+      personalization: existing?.personalization,
+      registryUrl: registry.url ?? existing?.registry?.url,
+      registryRef: registry.ref ?? existing?.registry?.ref
+    });
+    if (existing?.unknownFields) draft.unknownFields = existing.unknownFields;
+    const stats = (draft.packs?.length ?? 0) > 0 || (draft.skills?.length ?? 0) > 0 ? await syncFromManifest(registry.root, projectRoot, draft) : await installL0(registry.root, projectRoot, resolveProtectedGlobs(draft));
+    if (stats.skippedSymlink.length > 0) throw new SkippedSymlinkError(stats);
+    const manifestPath = await saveManifest(projectRoot, draft);
+    const readinessExecution = await executeSafeReadinessFixes(projectRoot, {
+      generatorVersion: KIT_VERSION
+    });
+    let readiness = readinessExecution.after;
+    let claudeSessionStartInstructions;
+    const profile = await readRepositoryProfile(projectRoot);
+    if (profile) {
+      const registryIndex = await loadRegistry(registry.root);
+      const personalization = await applyPersonalization({
+        rootDir: projectRoot,
+        registryRoot: registry.root,
+        profile,
+        report: readinessExecution.after,
+        registry: registryIndex,
+        manifest: draft,
+        generatorVersion: KIT_VERSION,
+        claudeAdapters: options.claudeAdapters
+      });
+      await saveManifest(projectRoot, personalization.manifest);
+      claudeSessionStartInstructions = personalization.result.claudeSessionStartInstructions;
+      readiness = createReadinessReport(await runScanner(projectRoot), {
+        generatorVersion: KIT_VERSION
+      });
+      readiness.appliedSafeFixes = readinessExecution.after.appliedSafeFixes;
+      if (personalization.stats.skippedSymlink.length > 0) {
+        await writeReadinessSnapshot(projectRoot, readiness);
+        throw new SkippedSymlinkError(
+          mergeStats(stats, personalization.stats),
+          formatPersonalizationSkippedSymlinks(
+            personalization.stats.skippedSymlink,
+            personalization.notRecorded
+          ),
+          claudeSessionStartInstructions
+        );
+      }
+    }
+    await writeReadinessSnapshot(projectRoot, readiness);
+    return {
+      projectRoot,
+      manifestPath,
+      stats,
+      readiness,
+      safeChanges: readinessExecution.changes,
+      ...claudeSessionStartInstructions ? { claudeSessionStartInstructions } : {}
+    };
+  } finally {
+    await registry.unlock?.();
+  }
+}
+var installCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Bootstrap L0 (+ optional packs) and write .cursor/agent-kit.json."
+  },
+  args: {
+    profile: {
+      type: "positional",
+      description: "Install profile name stored in the manifest (default: default)",
+      required: false
+    },
+    pack: {
+      type: "string",
+      description: `Comma-separated L1 pack ids (e.g. cybersec,devops). Known: ${DOMAIN_PACK_IDS.join(", ")}`
+    },
+    ...NON_INTERACTIVE_ROOT_ARGS,
+    claude: {
+      type: "boolean",
+      description: "Opt-in: generate .claude/commands/*.md thin pointer adapters for the installed .cursor/commands set, and merge a SessionStart context hook into .claude/settings.json (default install behavior is unchanged without this flag)",
+      default: false
+    },
+    cwd: {
+      type: "string",
+      default: process.cwd()
+    },
+    ...REGISTRY_CLI_ARGS
+  },
+  async run({ args }) {
+    const nonInteractive = args.yes || isNonInteractive();
+    if (nonInteractive) {
+      logger.info("Non-interactive mode: skipping prompts, using defaults.");
+    }
+    let projectRoot;
+    try {
+      projectRoot = await confirmProjectRoot(args.cwd, {
+        nonInteractive,
+        command: "install",
+        forceRoot: args["force-root"]
+      });
+    } catch (err) {
+      if (err instanceof RootRefusedError) {
+        logger.error(err.message);
+        if (err.recovery) console.error(`
+${err.recovery}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+    logger.info(`Installing into: ${projectRoot}`);
+    logger.info(`CLI v${KIT_VERSION}`);
+    await warnIfRunningCliBehindNpm(projectRoot, { warn: (message) => logger.warn(message) });
+    const packs = parsePackList(args.pack);
+    for (const id of packs) {
+      if (!DOMAIN_PACK_IDS.includes(id)) {
+        logger.warn(`Pack '${id}' is not in the known L1 list; will still try registry.`);
+      }
+    }
+    try {
+      const result = await withCliProgress(
+        "install",
+        () => performInstall({
+          cwd: projectRoot,
+          profile: args.profile,
+          pack: args.pack,
+          registry: args.registry,
+          url: args.url,
+          ref: args.ref,
+          refresh: args.refresh,
+          claudeAdapters: args.claude
+        })
+      );
+      logApplyStats(result.stats);
+      logger.success(`Manifest written: ${result.manifestPath}`);
+      logger.success("Readiness snapshot written: .cursor/context/readiness.json");
+      await printPostInstallSummary(result);
+      if (result.claudeSessionStartInstructions) {
+        logger.warn("Could not merge the Claude Code SessionStart hook automatically:");
+        console.log(`
+${result.claudeSessionStartInstructions}
+`);
+      }
+    } catch (err) {
+      if (err instanceof SkippedSymlinkError) {
+        logApplyStats(err.stats);
+        logger.error(err.message);
+        if (err.claudeSessionStartInstructions) {
+          logger.warn("Could not merge the Claude Code SessionStart hook automatically:");
+          console.log(`
+${err.claudeSessionStartInstructions}
+`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+      const hint = classifyInstallError(err);
+      logger.error(hint.message);
+      console.error(`
+${hint.recovery}
+`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+});
+
+export {
+  nextStepAfterInstall,
+  printInstallEpilogue,
+  performInstall,
+  installCommand
+};