hatch3r 1.7.1 → 1.7.5

package/dist/cli/index.js

@@ -14,7 +14,7 @@ var HATCH3R_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    HATCH3R_VERSION = "1.7.1";
+    HATCH3R_VERSION = "1.7.5";
   }
 });
 
@@ -79,7 +79,8 @@ function printBox(title, lines, style = "info") {
   const colors = {
     success: "#10b981",
     info: "#06b6d4",
-    error: "#ef4444"
+    error: "#ef4444",
+    warning: "#f59e0b"
   };
   const content = lines.join("\n");
   console.log(
@@ -138,6 +139,15 @@ var init_ui = __esm({
 });
 
 // src/types.ts
+function getMarkersForPath(filePath) {
+  if (filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".yml") || lower.endsWith(".yaml")) {
+      return { start: MANAGED_BLOCK_START_YAML, end: MANAGED_BLOCK_END_YAML };
+    }
+  }
+  return { start: MANAGED_BLOCK_START, end: MANAGED_BLOCK_END };
+}
 function sanitizeId(id) {
   return id.replace(/[^a-zA-Z0-9._-]/g, "");
 }
@@ -145,7 +155,7 @@ function toPrefixedId(id, prefix = HATCH3R_PREFIX) {
   const base = id.replace(new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "");
   return `${prefix}${base}`;
 }
-var TOOLS, VALID_TOOLS, TOOL_CHOICES, WORKTREE_CAPABLE_TOOLS, MANAGED_BLOCK_START, MANAGED_BLOCK_END, HATCH3R_PREFIX, AGENTS_DIR, ARCHIVE_DIR, CUSTOMIZE_DIR, ERROR_CODE_TO_EXIT_CODE, HatchError, MANIFEST_FILE, WORKTREE_INCLUDE_FILE, DEFAULT_FEATURES, ENV_VAR_HELP, AVAILABLE_MCP_SERVERS;
+var TOOLS, VALID_TOOLS, TOOL_CHOICES, WORKTREE_CAPABLE_TOOLS, MANAGED_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START_YAML, MANAGED_BLOCK_END_YAML, MANAGED_BLOCK_VARIANTS, HATCH3R_PREFIX, AGENTS_DIR, ARCHIVE_DIR, CUSTOMIZE_DIR, ERROR_CODE_TO_EXIT_CODE, HatchError, MANIFEST_FILE, WORKTREE_INCLUDE_FILE, DEFAULT_FEATURES, ENV_VAR_HELP, AVAILABLE_MCP_SERVERS;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
@@ -155,6 +165,12 @@ var init_types = __esm({
     WORKTREE_CAPABLE_TOOLS = /* @__PURE__ */ new Set(["claude"]);
     MANAGED_BLOCK_START = "<!-- HATCH3R:BEGIN -->";
     MANAGED_BLOCK_END = "<!-- HATCH3R:END -->";
+    MANAGED_BLOCK_START_YAML = "# HATCH3R:BEGIN";
+    MANAGED_BLOCK_END_YAML = "# HATCH3R:END";
+    MANAGED_BLOCK_VARIANTS = [
+      { start: MANAGED_BLOCK_START, end: MANAGED_BLOCK_END },
+      { start: MANAGED_BLOCK_START_YAML, end: MANAGED_BLOCK_END_YAML }
+    ];
     HATCH3R_PREFIX = "hatch3r-";
     AGENTS_DIR = ".agents";
     ARCHIVE_DIR = ".hatch3r-archive";
@@ -190,7 +206,8 @@ var init_types = __esm({
       commands: true,
       mcp: true,
       githubAgents: true,
-      hooks: true
+      hooks: true,
+      handoffs: true
     };
     ENV_VAR_HELP = {
       GITHUB_PAT: {
@@ -269,21 +286,29 @@ var init_types = __esm({
 });
 
 // src/merge/managedBlocks.ts
-function insertManagedBlock(existingContent, managedContent) {
-  const startIdx = existingContent.indexOf(MANAGED_BLOCK_START);
-  const endIdx = existingContent.indexOf(MANAGED_BLOCK_END);
-  const block = `${MANAGED_BLOCK_START}
-${managedContent.trim()}
-${MANAGED_BLOCK_END}`;
-  if (startIdx === -1 || endIdx === -1) {
+function detectMarkers(content) {
+  for (const variant of MANAGED_BLOCK_VARIANTS) {
+    const startIdx = content.indexOf(variant.start);
+    const endIdx = content.indexOf(variant.end);
+    if (startIdx !== -1 && endIdx !== -1) {
+      return { variant, startIdx, endIdx };
+    }
+  }
+  return null;
+}
+function insertManagedBlock(existingContent, managedContent, filePath) {
+  const outputMarkers = getMarkersForPath(filePath);
+  const detected = detectMarkers(existingContent);
+  if (!detected) {
     throw new HatchError(
       "Content must contain managed block markers (HATCH3R:BEGIN and HATCH3R:END)",
       1,
       "VALIDATION_ERROR"
     );
   }
-  const secondStart = existingContent.indexOf(MANAGED_BLOCK_START, startIdx + 1);
-  const secondEnd = existingContent.indexOf(MANAGED_BLOCK_END, endIdx + 1);
+  const { variant, startIdx, endIdx } = detected;
+  const secondStart = existingContent.indexOf(variant.start, startIdx + 1);
+  const secondEnd = existingContent.indexOf(variant.end, endIdx + 1);
   if (secondStart !== -1) {
     throw new HatchError(
       "Corrupted managed block: duplicate start marker found. Remove the duplicate before syncing.",
@@ -305,37 +330,35 @@ ${MANAGED_BLOCK_END}`;
       "VALIDATION_ERROR"
     );
   }
+  const block = `${outputMarkers.start}
+${managedContent.trim()}
+${outputMarkers.end}`;
   const before = existingContent.substring(0, startIdx);
-  const after = existingContent.substring(endIdx + MANAGED_BLOCK_END.length);
+  const after = existingContent.substring(endIdx + variant.end.length);
   const result = `${before}${block}${after}`;
   return result.endsWith("\n") ? result : result + "\n";
 }
 function extractManagedBlock(content) {
-  const startIdx = content.indexOf(MANAGED_BLOCK_START);
-  const endIdx = content.indexOf(MANAGED_BLOCK_END);
-  if (startIdx === -1 || endIdx === -1) {
-    return null;
-  }
-  return content.substring(startIdx + MANAGED_BLOCK_START.length, endIdx).trim();
+  const detected = detectMarkers(content);
+  if (!detected) return null;
+  return content.substring(detected.startIdx + detected.variant.start.length, detected.endIdx).trim();
 }
 function extractCustomContent(content) {
-  const startIdx = content.indexOf(MANAGED_BLOCK_START);
-  const endIdx = content.indexOf(MANAGED_BLOCK_END);
-  if (startIdx === -1 || endIdx === -1) {
-    return content;
-  }
-  const before = content.substring(0, startIdx).trim();
-  const after = content.substring(endIdx + MANAGED_BLOCK_END.length).trim();
+  const detected = detectMarkers(content);
+  if (!detected) return content;
+  const before = content.substring(0, detected.startIdx).trim();
+  const after = content.substring(detected.endIdx + detected.variant.end.length).trim();
   return [before, after].filter(Boolean).join("\n\n");
 }
-function wrapInManagedBlock(content) {
-  return `${MANAGED_BLOCK_START}
+function wrapInManagedBlock(content, filePath) {
+  const markers = getMarkersForPath(filePath);
+  return `${markers.start}
 ${content.trim()}
-${MANAGED_BLOCK_END}
+${markers.end}
 `;
 }
 function hasManagedBlock(content) {
-  return content.includes(MANAGED_BLOCK_START) && content.includes(MANAGED_BLOCK_END);
+  return detectMarkers(content) !== null;
 }
 var init_managedBlocks = __esm({
   "src/merge/managedBlocks.ts"() {
@@ -1327,7 +1350,7 @@ async function safeWriteFile(filePath, content, options = {}) {
     const deniedFindings = customContent ? scanForDeniedPatterns(customContent) : [];
     let merged;
     try {
-      merged = insertManagedBlock(existingContent, options.managedContent);
+      merged = insertManagedBlock(existingContent, options.managedContent, filePath);
     } catch {
       const bakPath = filePath + ".bak";
       await copyFile(filePath, bakPath);
@@ -1619,8 +1642,8 @@ async function resolvePatterns(rootDir, patterns) {
 }
 function isInsideWorktree(dir) {
   try {
-    const stat11 = statSync(join5(dir, ".git"));
-    return stat11.isFile();
+    const stat13 = statSync(join5(dir, ".git"));
+    return stat13.isFile();
   } catch {
     return false;
   }
@@ -1922,10 +1945,10 @@ async function cleanupWorktree(worktreeRoot) {
   for (const entry of entries) {
     const targetPath = join6(worktreeRoot, entry.pattern.replace(/\/$/, ""));
     try {
-      const stat11 = await lstat(targetPath);
-      if (stat11.isSymbolicLink()) {
+      const stat13 = await lstat(targetPath);
+      if (stat13.isSymbolicLink()) {
         await unlink2(targetPath);
-      } else if (entry.strategy === "copy" && stat11.isFile() && mainRoot) {
+      } else if (entry.strategy === "copy" && stat13.isFile() && mainRoot) {
         const sourcePath = join6(mainRoot, entry.pattern.replace(/\/$/, ""));
         try {
           const sourceContent = await readFile4(sourcePath, "utf-8");
@@ -2327,6 +2350,7 @@ __export(hatchJson_exports, {
   extractPreservedManifestFields: () => extractPreservedManifestFields,
   isValidGitBranchName: () => isValidGitBranchName,
   migrateManifest: () => migrateManifest,
+  readCliToolsConfig: () => readCliToolsConfig,
   readManifest: () => readManifest,
   removeManagedFile: () => removeManagedFile,
   writeManifest: () => writeManifest
@@ -2394,6 +2418,9 @@ function createManifest(options) {
   if (options.customization) {
     manifest.customization = options.customization;
   }
+  if (options.cliTools) {
+    manifest.cliTools = options.cliTools;
+  }
   if (options.languages && options.languages.length > 0 && options.languages[0] !== "unknown") {
     manifest.languages = options.languages;
   }
@@ -2607,6 +2634,7 @@ function extractPreservedManifestFields(manifest) {
   if (manifest.repos) out.repos = manifest.repos;
   if (manifest.packages) out.packages = manifest.packages;
   if (manifest.workspace) out.workspace = manifest.workspace;
+  if (manifest.cliTools) out.cliTools = manifest.cliTools;
   if (manifest.worktree?.extraPatterns !== void 0 || manifest.worktree?.nodeModules !== void 0) {
     out.worktreeExtras = {};
     if (manifest.worktree.extraPatterns !== void 0) {
@@ -2644,6 +2672,9 @@ function applyPreservedManifestFields(manifest, preserved) {
   if (preserved.repos) manifest.repos = preserved.repos;
   if (preserved.packages) manifest.packages = preserved.packages;
   if (preserved.workspace) manifest.workspace = preserved.workspace;
+  if (preserved.cliTools && manifest.cliTools === void 0) {
+    manifest.cliTools = preserved.cliTools;
+  }
   if (preserved.worktreeExtras && manifest.worktree?.enabled) {
     if (preserved.worktreeExtras.extraPatterns !== void 0) {
       manifest.worktree.extraPatterns = preserved.worktreeExtras.extraPatterns;
@@ -2653,6 +2684,9 @@ function applyPreservedManifestFields(manifest, preserved) {
     }
   }
 }
+function readCliToolsConfig(m) {
+  return m.cliTools ?? { enabled: false, selected: [] };
+}
 var init_hatchJson = __esm({
   "src/manifest/hatchJson.ts"() {
     "use strict";
@@ -3101,6 +3135,16 @@ var init_agentToolAllowlist = __esm({
         allowedTools: ["read", "search", "write", "execute"],
         description: "Code implementation: file read/write, code search, command execution (tests, linters). No git, board, or web."
       },
+      {
+        agentId: "hatch3r-handoff-preparer",
+        allowedTools: ["read", "search", "write"],
+        description: "Handoff preparation: read session state, search git/files for context, write canonical handoff to .agents/handoffs/active/. No execute (filesystem-only)."
+      },
+      {
+        agentId: "hatch3r-handoff-loader",
+        allowedTools: ["read", "search"],
+        description: "Session-start loader: read .agents/handoffs/active/ and search git for branch context to surface active handoffs. No write, execute, or external IO."
+      },
       {
         agentId: "hatch3r-reviewer",
         allowedTools: ["read", "search"],
@@ -3332,7 +3376,7 @@ function filterByLanguages(items, projectLanguages) {
     return itemLangTags.some((t) => relevant.has(t));
   });
 }
-var TAG_CORE, TAG_PLANNING, TAG_IMPLEMENTATION, TAG_REVIEW, TAG_DEVOPS, TAG_MAINTENANCE, TAG_BOARD, TAG_SECURITY, TAG_A11Y, TAG_PERFORMANCE, TAG_CUSTOMIZE, TAG_LANG_TYPESCRIPT, TAG_LANG_PYTHON, TAG_LANG_GO, TAG_LANG_RUST, TAG_LANG_JAVA, TAG_LANG_RUBY, WORKFLOW_TAGS, DOMAIN_TAGS, LANGUAGE_TO_TAG;
+var TAG_CORE, TAG_PLANNING, TAG_IMPLEMENTATION, TAG_REVIEW, TAG_DEVOPS, TAG_MAINTENANCE, TAG_BOARD, TAG_SECURITY, TAG_A11Y, TAG_PERFORMANCE, TAG_CUSTOMIZE, TAG_FRONTEND, TAG_UI, TAG_UX, TAG_DESIGN_SYSTEM, TAG_LANG_TYPESCRIPT, TAG_LANG_PYTHON, TAG_LANG_GO, TAG_LANG_RUST, TAG_LANG_JAVA, TAG_LANG_RUBY, WORKFLOW_TAGS, DOMAIN_TAGS, LANGUAGE_TO_TAG;
 var init_tags = __esm({
   "src/content/tags.ts"() {
     "use strict";
@@ -3347,6 +3391,10 @@ var init_tags = __esm({
     TAG_A11Y = "a11y";
     TAG_PERFORMANCE = "performance";
     TAG_CUSTOMIZE = "customize";
+    TAG_FRONTEND = "frontend";
+    TAG_UI = "ui";
+    TAG_UX = "ux";
+    TAG_DESIGN_SYSTEM = "design-system";
     TAG_LANG_TYPESCRIPT = "lang:typescript";
     TAG_LANG_PYTHON = "lang:python";
     TAG_LANG_GO = "lang:go";
@@ -3366,7 +3414,11 @@ var init_tags = __esm({
       TAG_SECURITY,
       TAG_A11Y,
       TAG_PERFORMANCE,
-      TAG_CUSTOMIZE
+      TAG_CUSTOMIZE,
+      TAG_FRONTEND,
+      TAG_UI,
+      TAG_UX,
+      TAG_DESIGN_SYSTEM
     ];
     LANGUAGE_TO_TAG = {
       typescript: TAG_LANG_TYPESCRIPT,
@@ -5249,6 +5301,77 @@ description: ${desc}
 ---`;
           results.push(output(pathFn(skill.id), `${fm}
 
+${wrapInManagedBlock(content)}`, content));
+        }
+        return results;
+      }
+      /**
+       * Read canonical skills with the CLI-tooling pivot filter applied.
+       *
+       * Filter rules (plan §4.6):
+       *  - Skills whose id does NOT start with `hatch3r-cli-` pass through
+       *    unchanged (every adapter still emits the non-CLI skill catalogue).
+       *  - When `manifest.cliTools` is absent or `enabled: false`, drop every
+       *    `hatch3r-cli-*` skill (master switch off).
+       *  - When `cliTools.enabled` is true, keep only those whose suffix
+       *    (after stripping `hatch3r-cli-`) appears in `cliTools.selected`.
+       *
+       * Wave 3 swaps each adapter's `processSkillsWithFm` /
+       * `processSkillsRaw` call to the `*CliFiltered` variants below; the
+       * filter helper is exposed protected so adapters with custom skill
+       * pipelines can reuse it directly.
+       */
+      async readCliFilteredSkills(ctx) {
+        const all = await this.readTrackedCanonicalFiles(ctx.agentsDir, "skills");
+        const cliCfg = ctx.manifest.cliTools ?? { enabled: false, selected: [] };
+        const selected = new Set(cliCfg.selected ?? []);
+        return all.filter((skill) => {
+          if (!skill.id.startsWith("hatch3r-cli-")) return true;
+          if (!cliCfg.enabled) return false;
+          const cliId = skill.id.replace(/^hatch3r-cli-/, "");
+          return selected.has(cliId);
+        });
+      }
+      /**
+       * CLI-filtered twin of {@link processSkillsRaw}. Adapters that emit
+       * skills as raw managed-block files (no YAML frontmatter) call this
+       * after Wave 3 instead of `processSkillsRaw` to honour
+       * `manifest.cliTools.selected`.
+       */
+      async processSkillsRawCliFiltered(ctx, pathFn) {
+        if (!ctx.features.skills) return [];
+        const results = [];
+        const skills = await this.readCliFilteredSkills(ctx);
+        for (const skill of skills) {
+          const { content: raw, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, skill);
+          this.warnings.push(...warnings);
+          if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
+          results.push(output(pathFn(skill.id), wrapInManagedBlock(content), content));
+        }
+        return results;
+      }
+      /**
+       * CLI-filtered twin of {@link processSkillsWithFm}. Adapters that emit
+       * skills as managed-block files prefixed with a `name: + description:`
+       * YAML stub call this after Wave 3 instead of `processSkillsWithFm`.
+       */
+      async processSkillsWithFmCliFiltered(ctx, pathFn) {
+        if (!ctx.features.skills) return [];
+        const results = [];
+        const skills = await this.readCliFilteredSkills(ctx);
+        for (const skill of skills) {
+          const { content: raw, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, skill);
+          this.warnings.push(...warnings);
+          if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
+          const desc = overrides.description ?? skill.description;
+          const fm = `---
+name: ${skill.id}
+description: ${desc}
+---`;
+          results.push(output(pathFn(skill.id), `${fm}
+
 ${wrapInManagedBlock(content)}`, content));
         }
         return results;
@@ -5364,7 +5487,7 @@ var init_aider = __esm({
           output("CONVENTIONS.md", wrapInManagedBlock(inner), inner)
         ];
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.aider/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.aider/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         results.push(output(".aider.conf.yml", [
           "# Managed by hatch3r \u2014 do not edit manually",
@@ -5410,7 +5533,7 @@ var init_amazonq = __esm({
         ].join("\n").trim();
         results.push(output(".amazonq/rules/hatch3r-agents.md", wrapInManagedBlock(inner), inner));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.amazonq/rules/hatch3r-skill-${id}.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.amazonq/rules/hatch3r-skill-${id}.md`)
         );
         const mcp = await this.readFilteredMcp(ctx);
         if (mcp && Object.keys(mcp).length > 0) {
@@ -5538,7 +5661,7 @@ var init_antigravity = __esm({
         ].join("\n").trim();
         results.push(output(".antigravity/rules.md", wrapInManagedBlock(inner), inner));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.agent/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.agent/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         const mcp = await this.readFilteredMcp(ctx);
         if (mcp && Object.keys(mcp).length > 0) {
@@ -5916,7 +6039,7 @@ ${wrapInManagedBlock(body)}`, body));
           results.push(output(".claude/hooks/hatch3r-hooks.json", JSON.stringify(pluginHooksObj, null, 2)));
         }
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.claude/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.claude/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         results.push(
           ...await this.processCommandsRaw(ctx, (id) => `.claude/commands/${toPrefixedId(id)}.md`)
@@ -5986,7 +6109,7 @@ Recommended model: ${model}. Select this model in the Roo Code model dropdown wh
           }, null, 2)));
         }
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.cline/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.cline/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         if (ctx.features.rules) {
           const rules = await readCanonicalFiles(ctx.agentsDir, "rules", this.warnings);
@@ -6229,7 +6352,7 @@ var init_codex = __esm({
         }
         results.push(output(".codex/config.toml", configLines.join("\n")));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.codex/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.codex/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         return results;
       }
@@ -6374,9 +6497,10 @@ jobs:
         run: ${install}
       - name: Build
         run: ${build}`;
+        const copilotSetupStepsPath = ".github/workflows/copilot-setup-steps.yml";
         results.push(output(
-          ".github/workflows/copilot-setup-steps.yml",
-          wrapInManagedBlock(copilotSetupStepsInner),
+          copilotSetupStepsPath,
+          wrapInManagedBlock(copilotSetupStepsInner, copilotSetupStepsPath),
           copilotSetupStepsInner
         ));
         for (const { rule, content, scope } of scopedRules) {
@@ -6443,7 +6567,7 @@ ${wrapInManagedBlock(content)}`, content));
           }
         }
         results.push(
-          ...await this.processSkillsWithFm(ctx, (id) => `.github/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsWithFmCliFiltered(ctx, (id) => `.github/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         const mcp = await this.readFilteredMcp(ctx);
         if (mcp && Object.keys(mcp).length > 0) {
@@ -6529,7 +6653,7 @@ ${lines.join("\n")}
           }
         }
         results.push(
-          ...await this.processSkillsWithFm(ctx, (id) => `.cursor/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsWithFmCliFiltered(ctx, (id) => `.cursor/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         results.push(
           ...await this.processCommandsRaw(ctx, (id) => `.cursor/commands/${toPrefixedId(id)}.md`)
@@ -6682,7 +6806,7 @@ var init_gemini = __esm({
         }
         results.push(output(".gemini/settings.json", JSON.stringify(settings, null, 2)));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.gemini/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.gemini/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         if (ctx.features.commands) {
           const commandsRaw = await readCanonicalFiles(ctx.agentsDir, "commands", this.warnings);
@@ -6714,7 +6838,6 @@ var init_goose = __esm({
     init_types();
     init_managedBlocks();
     init_base();
-    init_canonical();
     init_customization();
     init_mcp_utils();
     GooseAdapter = class extends BaseAdapter {
@@ -6727,7 +6850,7 @@ var init_goose = __esm({
           ...await this.inlineAgents(ctx)
         ];
         if (ctx.features.skills) {
-          const skills = await readCanonicalFiles(ctx.agentsDir, "skills", this.warnings);
+          const skills = await this.readCliFilteredSkills(ctx);
           for (const skill of skills) {
             const { content, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, skill);
             this.warnings.push(...warnings);
@@ -6887,7 +7010,7 @@ ${content}`;
         const inner = lines.join("\n").trim();
         results.push(output(".kiro/steering/hatch3r-agents.md", wrapInManagedBlock(inner), inner));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.kiro/steering/hatch3r-skill-${id}.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.kiro/steering/hatch3r-skill-${id}.md`)
         );
         const hooks = await this.readHooks(ctx);
         for (const hook of hooks) {
@@ -7018,7 +7141,7 @@ ${wrapInManagedBlock(content)}`, content));
           }
         }
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.opencode/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRawCliFiltered(ctx, (id) => `.opencode/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         results.push(
           ...await this.processCommandsRaw(ctx, (id) => `.opencode/commands/${toPrefixedId(id)}.md`)
@@ -7159,7 +7282,7 @@ ${wrapInManagedBlock(body)}`, body));
           }
         }
         results.push(
-          ...await this.processSkillsWithFm(ctx, (id) => `.windsurf/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsWithFmCliFiltered(ctx, (id) => `.windsurf/skills/${toPrefixedId(id)}/SKILL.md`)
         );
         results.push(
           ...await this.processCommandsRaw(ctx, (id) => `.windsurf/workflows/${toPrefixedId(id)}.md`)
@@ -7284,6 +7407,9 @@ function getUnsupportedFeatureWarnings(tool, manifest) {
       unsupported.push(label2);
     }
   }
+  if (manifest.cliTools?.enabled && (manifest.cliTools.selected?.length ?? 0) > 0 && !caps.cliTools) {
+    unsupported.push("CLI tool skills");
+  }
   if (unsupported.length === 0) return [];
   const noun = unsupported.length === 1 ? "feature" : "features";
   return [`${tool}: ${noun} enabled but not supported by this adapter: ${unsupported.join(", ")}`];
@@ -7344,28 +7470,32 @@ var init_adapters = __esm({
     };
     adapterCache = /* @__PURE__ */ new Map();
     ADAPTER_CAPABILITIES = {
-      cursor: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
-      claude: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: true },
-      gemini: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
-      cline: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
-      codex: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      "amazon-q": { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      copilot: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: true, githubAgents: true, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
-      opencode: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      cursor: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      claude: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: true, cliTools: true },
+      gemini: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      cline: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      codex: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      "amazon-q": { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      copilot: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: true, githubAgents: true, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      opencode: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
       // C7.5-W2B2-H31 (D9-SA9.7.1): Windsurf shipped Cascade Hooks in v1.13.12 (2026-01-25).
       // Hatch3r emits `.windsurf/hooks.json` per docs.windsurf.com/windsurf/cascade/hooks.md.
-      windsurf: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
+      windsurf: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
       // Amp reads AGENTS.md natively; the root file is written by generateRootAgentsMd()
       // in init/update, not by this adapter. Amp also reads skills natively from
       // `.agents/skills/` — populated by copyHatch3rFiles, not re-emitted by this
       // adapter (re-emission corrupts SKILL.md frontmatter via managed-block wrap).
-      // doGenerate() emits MCP settings only.
-      amp: { agents: false, skills: false, rules: false, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      kiro: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      aider: { agents: true, skills: true, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      goose: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
-      zed: { agents: true, skills: false, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: false, modelOverride: false, nativeQuestionTool: false },
-      antigravity: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false }
+      // doGenerate() emits MCP settings only. cliTools: false — Amp reads
+      // `hatch3r-cli-*` skills from the canonical `.agents/skills/` tree directly.
+      amp: { agents: false, skills: false, rules: false, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: false },
+      kiro: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      aider: { agents: true, skills: true, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      goose: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true },
+      // Zed has no skills surface (skills: false). cliTools: false — Wave 3 will
+      // emit a one-line "Available CLI tool guides: ..." reference inside the
+      // rules output instead of per-tool skill files.
+      zed: { agents: true, skills: false, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: false, modelOverride: false, nativeQuestionTool: false, cliTools: false },
+      antigravity: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false, cliTools: true }
     };
   }
 });
@@ -7682,13 +7812,8 @@ async function fileIsUserWrapped(absPath) {
     if (!hasManagedBlock(content)) {
       return { wrapped: false };
     }
-    const before = content.slice(0, content.indexOf("<!-- HATCH3R:BEGIN -->"));
-    const endMarker = "<!-- HATCH3R:END -->";
-    const endIdx = content.indexOf(endMarker);
-    const after = endIdx === -1 ? "" : content.slice(endIdx + endMarker.length);
-    const userBefore = before.trim();
-    const userAfter = after.trim();
-    return { wrapped: userBefore.length > 0 || userAfter.length > 0 };
+    const userOutside = extractCustomContent(content).trim();
+    return { wrapped: userOutside.length > 0 };
   } catch (err) {
     return { wrapped: false, error: err instanceof Error ? err.message : String(err) };
   }
@@ -8319,7 +8444,7 @@ var init_retryWithBackoff = __esm({
 
 // src/detect/installContext.ts
 import { execFileSync as execFileSync5 } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync3, lstatSync, readFileSync as readFileSync3 } from "fs";
 import { dirname as dirname14, join as join28, normalize as normalize3, resolve as resolve4, sep as sep3 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 function isNpxPath(p) {
@@ -8365,12 +8490,25 @@ function npmGlobalRoot() {
   }
   return cachedNpmGlobalRoot;
 }
+function isLinkedPackageDir(packageRoot) {
+  try {
+    return lstatSync(packageRoot).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
 function classifyInvocation(binPath, projectRoot) {
   if (isNpxPath(binPath)) return "npx";
   const globalRoot = npmGlobalRoot();
-  if (globalRoot && binPath.startsWith(globalRoot)) return "global";
+  if (globalRoot && binPath.startsWith(globalRoot)) {
+    if (isLinkedPackageDir(join28(globalRoot, "hatch3r"))) return "dev-source";
+    return "global";
+  }
   const projectNodeModules = join28(projectRoot, "node_modules") + sep3;
-  if (binPath.startsWith(projectNodeModules)) return "project-local";
+  if (binPath.startsWith(projectNodeModules)) {
+    if (isLinkedPackageDir(join28(projectRoot, "node_modules", "hatch3r"))) return "dev-source";
+    return "project-local";
+  }
   return "dev-source";
 }
 async function buildLocation(kind, binPath, packageRoot, cwdForPmDetection) {
@@ -8405,7 +8543,7 @@ async function surveyInstalls(rootDir) {
   const alsoPresent = [];
   if (invokedKind !== "project-local") {
     const projectPkgRoot = join28(rootDir, "node_modules", "hatch3r");
-    if (existsSync3(join28(projectPkgRoot, "package.json"))) {
+    if (existsSync3(join28(projectPkgRoot, "package.json")) && !isLinkedPackageDir(projectPkgRoot)) {
       const projectBin = join28(projectPkgRoot, "dist", "cli", "index.js");
       alsoPresent.push(
         await buildLocation("project-local", projectBin, projectPkgRoot, rootDir)
@@ -8416,7 +8554,7 @@ async function surveyInstalls(rootDir) {
     const globalRoot = npmGlobalRoot();
     if (globalRoot) {
       const globalPkgRoot = join28(globalRoot, "hatch3r");
-      if (existsSync3(join28(globalPkgRoot, "package.json"))) {
+      if (existsSync3(join28(globalPkgRoot, "package.json")) && !isLinkedPackageDir(globalPkgRoot)) {
         const globalBin = join28(globalPkgRoot, "dist", "cli", "index.js");
         alsoPresent.push(
           await buildLocation("global", globalBin, globalPkgRoot, rootDir)
@@ -8582,8 +8720,8 @@ import { appendFile as appendFile2, cp as cp4, mkdir as mkdir9, readFile as read
 import { spawnSync as spawnSync2 } from "child_process";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { dirname as dirname15, join as join29, sep as sep4 } from "path";
-import chalk7 from "chalk";
-import inquirer6 from "inquirer";
+import chalk9 from "chalk";
+import inquirer8 from "inquirer";
 function buildReExecPassThroughArgs(opts) {
   const args = [];
   if (opts?.yes) args.push("--yes");
@@ -8894,23 +9032,23 @@ async function runUpdateDryRun(rootDir, manifest, options = {}) {
     }
   }
   const summaryLines = [];
-  summaryLines.push(chalk7.dim(`Offline: ${options.offline ? "yes" : "no"}`));
-  summaryLines.push(chalk7.dim(`Canonical candidate files: ${canonicalCandidates.length}`));
+  summaryLines.push(chalk9.dim(`Offline: ${options.offline ? "yes" : "no"}`));
+  summaryLines.push(chalk9.dim(`Canonical candidate files: ${canonicalCandidates.length}`));
   for (const [tool, bucket] of adapterChanges) {
     if (bucket.error) {
-      summaryLines.push(`${chalk7.red("x")} ${tool}: ${bucket.error}`);
+      summaryLines.push(`${chalk9.red("x")} ${tool}: ${bucket.error}`);
       continue;
     }
     const lines = [
-      ...bucket.added.map((p) => `${chalk7.green("+ added")}    ${p}`),
-      ...bucket.modified.map((p) => `${chalk7.yellow("~ modified")} ${p}`),
-      ...bucket.unchanged.map((p) => `${chalk7.dim("= unchanged")} ${p}`)
+      ...bucket.added.map((p) => `${chalk9.green("+ added")}    ${p}`),
+      ...bucket.modified.map((p) => `${chalk9.yellow("~ modified")} ${p}`),
+      ...bucket.unchanged.map((p) => `${chalk9.dim("= unchanged")} ${p}`)
     ];
-    summaryLines.push(chalk7.bold(tool));
+    summaryLines.push(chalk9.bold(tool));
     summaryLines.push(...lines.map((l) => `  ${l}`));
   }
   console.log();
-  printBox("Update dry run (no writes)", summaryLines.length > 0 ? summaryLines : [chalk7.dim("No adapters configured.")], "info");
+  printBox("Update dry run (no writes)", summaryLines.length > 0 ? summaryLines : [chalk9.dim("No adapters configured.")], "info");
   return { canonicalCandidates, adapterChanges };
 }
 async function enumerateHatch3rFiles(srcDir, insideHatch3rDir, selectedIds) {
@@ -8976,7 +9114,7 @@ async function updateCommand(_opts) {
   const manifest = await readManifest(rootDir);
   if (!manifest) {
     error("No .agents/hatch.json found.");
-    console.log(chalk7.dim("  Run `npx hatch3r init` to set up your project first.\n"));
+    console.log(chalk9.dim("  Run `npx hatch3r init` to set up your project first.\n"));
     throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const headless = !!_opts?.yes;
@@ -9067,14 +9205,14 @@ async function updateCommand(_opts) {
     console.log();
     warn("A clean reinit is recommended for this version update:");
     for (const advisory of reinitAdvisories) {
-      console.log(chalk7.dim(`  - ${advisory.reason}`));
+      console.log(chalk9.dim(`  - ${advisory.reason}`));
       for (const change of advisory.changes ?? []) {
-        console.log(chalk7.dim(`    \u2022 ${change}`));
+        console.log(chalk9.dim(`    \u2022 ${change}`));
       }
     }
     console.log();
-    info(`Run ${chalk7.bold("hatch3r clean")} and choose to reinitialize when prompted.`);
-    console.log(chalk7.dim("  Your customizations and learnings will be preserved.\n"));
+    info(`Run ${chalk9.bold("hatch3r clean")} and choose to reinitialize when prompted.`);
+    console.log(chalk9.dim("  Your customizations and learnings will be preserved.\n"));
   }
   if (_opts?.diff && result.diffBefore && result.diffAfter) {
     const diffLines = [];
@@ -9082,11 +9220,11 @@ async function updateCommand(_opts) {
       const before = result.diffBefore.get(filePath) ?? null;
       const after = result.diffAfter.get(filePath) ?? null;
       if (before === null && after !== null) {
-        diffLines.push(`${chalk7.green("+ added")}    ${filePath}`);
+        diffLines.push(`${chalk9.green("+ added")}    ${filePath}`);
       } else if (before !== null && after !== null && before !== after) {
-        diffLines.push(`${chalk7.yellow("~ modified")} ${filePath}`);
+        diffLines.push(`${chalk9.yellow("~ modified")} ${filePath}`);
       } else if (before !== null && after !== null && before === after) {
-        diffLines.push(`${chalk7.dim("= unchanged")} ${filePath}`);
+        diffLines.push(`${chalk9.dim("= unchanged")} ${filePath}`);
       }
     }
     if (diffLines.length > 0) {
@@ -9106,6 +9244,9 @@ async function updateCommand(_opts) {
     label("Tools", `${compactedResult.syncedTools} tool(s) re-synced`),
     label("Version", `v${compactedResult.version}`)
   ], "success");
+  if (!m.cliTools || m.cliTools.selected.length === 0) {
+    info("CLI tooling available as a token-efficient alternative to MCP \u2014 run `npx hatch3r cli-tools` to opt in.");
+  }
   if (isPipelineTimedOut(pipelineState)) {
     const { report } = terminatePipeline(pipelineState);
     warn(report.summary);
@@ -9153,7 +9294,7 @@ var init_update = __esm({
             content.projectType = "brownfield";
             content.teamSize = "team";
           } else {
-            const { projectType } = await inquirer6.prompt([
+            const { projectType } = await inquirer8.prompt([
               {
                 type: "select",
                 name: "projectType",
@@ -9165,7 +9306,7 @@ var init_update = __esm({
                 default: "brownfield"
               }
             ]);
-            const { teamSize } = await inquirer6.prompt([
+            const { teamSize } = await inquirer8.prompt([
               {
                 type: "select",
                 name: "teamSize",
@@ -9194,7 +9335,7 @@ var init_update = __esm({
           if (headless) {
             platform = "github";
           } else {
-            const answer = await inquirer6.prompt([
+            const answer = await inquirer8.prompt([
               {
                 type: "select",
                 name: "platform",
@@ -9216,7 +9357,7 @@ var init_update = __esm({
             updated.project = updated.project || updated.repo;
             notices.push("Migrated to GitHub platform (auto-detected from existing config)");
           } else {
-            const answers = await inquirer6.prompt([
+            const answers = await inquirer8.prompt([
               { type: "input", name: "namespace", message: platform === "azure-devops" ? "Azure DevOps organization:" : "GitLab namespace (group or username):", default: updated.owner || void 0 },
               { type: "input", name: "project", message: platform === "azure-devops" ? "Azure DevOps project:" : "Project name:", default: updated.repo || void 0 },
               { type: "input", name: "repo", message: "Repository name:", default: updated.repo || void 0 }
@@ -9280,7 +9421,7 @@ var init_update = __esm({
           if (headless) {
             enabled = true;
           } else {
-            const answer = await inquirer6.prompt([{
+            const answer = await inquirer8.prompt([{
               type: "confirm",
               name: "enabled",
               message: "hatch3r now supports worktree file isolation for parallel agent sessions. Enable it?",
@@ -9900,8 +10041,8 @@ async function worktreeCleanupCommand(opts = {}) {
 init_ui();
 init_types();
 import { rm as rm4 } from "fs/promises";
-import chalk6 from "chalk";
-import inquirer5 from "inquirer";
+import chalk8 from "chalk";
+import inquirer7 from "inquirer";
 
 // src/clean/index.ts
 init_archive();
@@ -10281,8 +10422,8 @@ init_types();
 import { access as access9, mkdir as mkdir8 } from "fs/promises";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { basename as basename2, dirname as dirname12, join as join27 } from "path";
-import chalk5 from "chalk";
-import inquirer4 from "inquirer";
+import chalk7 from "chalk";
+import inquirer6 from "inquirer";
 
 // src/detect/repoAnalyzer.ts
 init_packageManager();
@@ -10738,6 +10879,813 @@ function isWSL() {
   }
 }
 
+// src/cli/shared/pickers.ts
+import inquirer4 from "inquirer";
+import chalk5 from "chalk";
+
+// src/cliTools/registry.ts
+var AVAILABLE_CLI_TOOLS = {
+  // ── Tier 1 (10 tools) ───────────────────────────────────────────
+  ripgrep: {
+    id: "ripgrep",
+    probe: "rg",
+    description: "Fast recursive grep with sane defaults and gitignore awareness",
+    category: "search",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install ripgrep" }],
+      linux: [{ manager: "apt", command: "sudo apt install ripgrep" }],
+      win: [{ manager: "scoop", command: "scoop install ripgrep" }]
+    },
+    homepage: "https://github.com/BurntSushi/ripgrep"
+  },
+  fd: {
+    id: "fd",
+    probe: "fd",
+    description: "User-friendly find replacement, gitignore-aware",
+    category: "search",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install fd" }],
+      linux: [{ manager: "apt", command: "sudo apt install fd-find" }],
+      win: [{ manager: "scoop", command: "scoop install fd" }]
+    },
+    homepage: "https://github.com/sharkdp/fd"
+  },
+  jq: {
+    id: "jq",
+    probe: "jq",
+    description: "JSON processor and query language",
+    category: "json",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install jq" }],
+      linux: [{ manager: "apt", command: "sudo apt install jq" }],
+      win: [{ manager: "scoop", command: "scoop install jq" }]
+    },
+    homepage: "https://github.com/jqlang/jq"
+  },
+  yq: {
+    id: "yq",
+    probe: "yq",
+    description: "YAML processor (mikefarah Go implementation)",
+    category: "yaml",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install yq" }],
+      linux: [{ manager: "snap", command: "sudo snap install yq" }],
+      win: [{ manager: "scoop", command: "scoop install yq" }]
+    },
+    homepage: "https://github.com/mikefarah/yq"
+  },
+  gh: {
+    id: "gh",
+    probe: "gh",
+    description: "GitHub CLI \u2014 repos, issues, PRs, releases, gists",
+    category: "forge",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install gh" }],
+      linux: [{ manager: "apt", command: "sudo apt install gh" }],
+      win: [{ manager: "winget", command: "winget install GitHub.cli" }]
+    },
+    requiresEnv: ["GH_TOKEN"],
+    homepage: "https://cli.github.com/"
+  },
+  delta: {
+    id: "delta",
+    probe: "delta",
+    description: "Syntax-highlighting git diff pager",
+    category: "git",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install git-delta" }],
+      linux: [{ manager: "apt", command: "sudo apt install git-delta" }],
+      win: [{ manager: "scoop", command: "scoop install delta" }]
+    },
+    homepage: "https://github.com/dandavison/delta"
+  },
+  bat: {
+    id: "bat",
+    probe: "bat",
+    description: "cat clone with syntax highlighting and git integration",
+    category: "view",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install bat" }],
+      linux: [{ manager: "apt", command: "sudo apt install bat" }],
+      win: [{ manager: "winget", command: "winget install sharkdp.bat" }]
+    },
+    homepage: "https://github.com/sharkdp/bat"
+  },
+  sd: {
+    id: "sd",
+    probe: "sd",
+    description: "Intuitive sed replacement with literal string patterns",
+    category: "edit",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install sd" }],
+      linux: [{ manager: "cargo", command: "cargo install sd" }],
+      win: [{ manager: "scoop", command: "scoop install sd" }]
+    },
+    homepage: "https://github.com/chmln/sd"
+  },
+  "ast-grep": {
+    id: "ast-grep",
+    probe: "sg",
+    description: "Structural search and rewrite for code via AST patterns",
+    category: "search",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install ast-grep" }],
+      linux: [{ manager: "cargo", command: "cargo install ast-grep" }],
+      win: [{ manager: "scoop", command: "scoop install ast-grep" }]
+    },
+    homepage: "https://ast-grep.github.io/"
+  },
+  zstd: {
+    id: "zstd",
+    probe: "zstd",
+    description: "Fast lossless compression with high ratio",
+    category: "archive",
+    tier: 1,
+    install: {
+      mac: [{ manager: "brew", command: "brew install zstd" }],
+      linux: [{ manager: "apt", command: "sudo apt install zstd" }],
+      win: [{ manager: "winget", command: "winget install Facebook.Zstandard" }]
+    },
+    homepage: "https://github.com/facebook/zstd"
+  },
+  // ── Tier 2 (11 tools, conditional) ──────────────────────────────
+  playwright: {
+    id: "playwright",
+    probe: "playwright",
+    description: "Browser automation, web testing, and UI interaction",
+    category: "browser",
+    tier: 2,
+    trigger: "web-project",
+    install: {
+      mac: [{ manager: "npm", command: "npm install -D @playwright/test && npx playwright install" }],
+      linux: [{ manager: "npm", command: "npm install -D @playwright/test && npx playwright install --with-deps" }],
+      win: [{ manager: "npm", command: "npm install -D @playwright/test && npx playwright install" }]
+    },
+    homepage: "https://playwright.dev/"
+  },
+  duckdb: {
+    id: "duckdb",
+    probe: "duckdb",
+    description: "Embedded analytical database with first-class CSV/Parquet support",
+    category: "data",
+    tier: 2,
+    trigger: "data-project",
+    install: {
+      mac: [{ manager: "brew", command: "brew install duckdb" }],
+      linux: [{ manager: "curl", command: "curl https://install.duckdb.org | sh" }],
+      win: [{ manager: "winget", command: "winget install DuckDB.cli" }]
+    },
+    homepage: "https://duckdb.org/"
+  },
+  xsv: {
+    id: "xsv",
+    probe: "xsv",
+    description: "Fast CSV toolkit (slice, search, join, stats)",
+    category: "data",
+    tier: 2,
+    trigger: "data-project",
+    install: {
+      mac: [{ manager: "brew", command: "brew install xsv" }],
+      linux: [{ manager: "cargo", command: "cargo install xsv" }],
+      win: [{ manager: "scoop", command: "scoop install xsv" }]
+    },
+    homepage: "https://github.com/BurntSushi/xsv"
+  },
+  taplo: {
+    id: "taplo",
+    probe: "taplo",
+    description: "TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml",
+    category: "yaml",
+    tier: 2,
+    trigger: "rust-project",
+    install: {
+      mac: [{ manager: "brew", command: "brew install taplo" }],
+      linux: [{ manager: "cargo", command: "cargo install taplo-cli --locked" }],
+      win: [{ manager: "scoop", command: "scoop install taplo" }]
+    },
+    homepage: "https://taplo.tamasfe.dev/"
+  },
+  glab: {
+    id: "glab",
+    probe: "glab",
+    description: "GitLab CLI \u2014 merge requests, issues, pipelines",
+    category: "forge",
+    tier: 2,
+    trigger: "gitlab-remote",
+    install: {
+      mac: [{ manager: "brew", command: "brew install glab" }],
+      linux: [{ manager: "apt", command: "sudo apt install glab" }],
+      win: [{ manager: "winget", command: "winget install GitLab.GLab" }]
+    },
+    requiresEnv: ["GITLAB_TOKEN"],
+    homepage: "https://gitlab.com/gitlab-org/cli"
+  },
+  "az-devops": {
+    id: "az-devops",
+    probe: "az",
+    description: "Azure DevOps work items, repos, pipelines via az CLI extension",
+    category: "forge",
+    tier: 2,
+    trigger: "azure-remote",
+    install: {
+      mac: [{ manager: "brew", command: "brew install azure-cli && az extension add --name azure-devops" }],
+      linux: [{ manager: "curl", command: "curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az extension add --name azure-devops" }],
+      win: [{ manager: "winget", command: "winget install Microsoft.AzureCLI && az extension add --name azure-devops" }]
+    },
+    requiresEnv: ["AZURE_DEVOPS_PAT", "AZURE_DEVOPS_ORG"],
+    homepage: "https://learn.microsoft.com/en-us/cli/azure/azure-devops"
+  },
+  docker: {
+    id: "docker",
+    probe: "docker",
+    description: "Container runtime and CLI",
+    category: "container",
+    tier: 2,
+    trigger: "docker-detected",
+    install: {
+      mac: [{ manager: "brew", command: "brew install --cask docker" }],
+      linux: [{ manager: "curl", command: "curl -fsSL https://get.docker.com | sudo sh" }],
+      win: [{ manager: "winget", command: "winget install Docker.DockerDesktop" }]
+    },
+    homepage: "https://docs.docker.com/get-docker/"
+  },
+  llm: {
+    id: "llm",
+    probe: "llm",
+    description: "simonw/llm \u2014 invoke LLMs from the command line with prompt templates",
+    category: "ai",
+    tier: 2,
+    trigger: "ci-llm-project",
+    install: {
+      mac: [{ manager: "brew", command: "brew install llm" }],
+      linux: [{ manager: "pipx", command: "pipx install llm" }],
+      win: [{ manager: "pipx", command: "pipx install llm" }]
+    },
+    homepage: "https://llm.datasette.io/"
+  },
+  fzf: {
+    id: "fzf",
+    probe: "fzf",
+    description: "Interactive fuzzy finder for TTY pickers",
+    category: "interactive",
+    tier: 2,
+    trigger: "interactive-tty",
+    install: {
+      mac: [{ manager: "brew", command: "brew install fzf" }],
+      linux: [{ manager: "apt", command: "sudo apt install fzf" }],
+      win: [{ manager: "scoop", command: "scoop install fzf" }]
+    },
+    homepage: "https://github.com/junegunn/fzf"
+  },
+  lazygit: {
+    id: "lazygit",
+    probe: "lazygit",
+    description: "Terminal UI for git with keyboard-driven workflows",
+    category: "git",
+    tier: 2,
+    trigger: "interactive-tty",
+    install: {
+      mac: [{ manager: "brew", command: "brew install lazygit" }],
+      linux: [{ manager: "apt", command: "sudo apt install lazygit" }],
+      win: [{ manager: "scoop", command: "scoop install lazygit" }]
+    },
+    homepage: "https://github.com/jesseduffield/lazygit"
+  },
+  difftastic: {
+    id: "difftastic",
+    probe: "difft",
+    description: "Structural diff that understands syntax",
+    category: "git",
+    tier: 2,
+    trigger: "interactive-tty",
+    install: {
+      mac: [{ manager: "brew", command: "brew install difftastic" }],
+      linux: [{ manager: "cargo", command: "cargo install --locked difftastic" }],
+      win: [{ manager: "scoop", command: "scoop install difftastic" }]
+    },
+    homepage: "https://difftastic.wilfred.me.uk/"
+  },
+  // ── Tier 3 (8 tools, opt-in advanced) ───────────────────────────
+  rtk: {
+    id: "rtk",
+    probe: "rtk",
+    description: "CLI output-compression proxy (see \u26A0 caveat)",
+    category: "ai",
+    tier: 3,
+    caveat: "pipe-output-corruption",
+    install: {
+      mac: [{ manager: "brew", command: "brew install rtk-ai/tap/rtk" }],
+      linux: [{ manager: "curl", command: "curl -fsSL https://rtk.dev/install.sh | sh" }],
+      win: [{ manager: "scoop", command: "scoop install rtk" }]
+    },
+    homepage: "https://github.com/rtk-ai/rtk"
+  },
+  stagehand: {
+    id: "stagehand",
+    probe: "stagehand",
+    description: "Browserbase Stagehand \u2014 AI-driven browser automation",
+    category: "browser",
+    tier: 3,
+    install: {
+      mac: [{ manager: "npm", command: "npm install -g @browserbasehq/stagehand" }],
+      linux: [{ manager: "npm", command: "npm install -g @browserbasehq/stagehand" }],
+      win: [{ manager: "npm", command: "npm install -g @browserbasehq/stagehand" }]
+    },
+    homepage: "https://github.com/browserbase/stagehand"
+  },
+  aichat: {
+    id: "aichat",
+    probe: "aichat",
+    description: "Multi-provider LLM chat CLI with RAG and session memory",
+    category: "ai",
+    tier: 3,
+    install: {
+      mac: [{ manager: "brew", command: "brew install aichat" }],
+      linux: [{ manager: "cargo", command: "cargo install aichat" }],
+      win: [{ manager: "scoop", command: "scoop install aichat" }]
+    },
+    homepage: "https://github.com/sigoden/aichat"
+  },
+  mods: {
+    id: "mods",
+    probe: "mods",
+    description: "Charm mods \u2014 Unix-friendly LLM pipeline tool",
+    category: "ai",
+    tier: 3,
+    install: {
+      mac: [{ manager: "brew", command: "brew install charmbracelet/tap/mods" }],
+      linux: [{ manager: "apt", command: "sudo apt install mods" }],
+      win: [{ manager: "scoop", command: "scoop install mods" }]
+    },
+    homepage: "https://github.com/charmbracelet/mods"
+  },
+  comby: {
+    id: "comby",
+    probe: "comby",
+    description: "Structural search and replace across languages with declarative patterns",
+    category: "search",
+    tier: 3,
+    install: {
+      mac: [{ manager: "brew", command: "brew install comby" }],
+      linux: [{ manager: "curl", command: "bash <(curl -sL get.comby.dev)" }],
+      win: [{ manager: "scoop", command: "scoop install comby" }]
+    },
+    homepage: "https://comby.dev/"
+  },
+  miller: {
+    id: "miller",
+    probe: "mlr",
+    description: "awk/sed/cut/join for CSV/TSV/JSON/Parquet streams",
+    category: "data",
+    tier: 3,
+    install: {
+      mac: [{ manager: "brew", command: "brew install miller" }],
+      linux: [{ manager: "apt", command: "sudo apt install miller" }],
+      win: [{ manager: "scoop", command: "scoop install miller" }]
+    },
+    homepage: "https://miller.readthedocs.io/"
+  },
+  csvkit: {
+    id: "csvkit",
+    probe: "csvlook",
+    description: "csvkit \u2014 Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat)",
+    category: "data",
+    tier: 3,
+    install: {
+      mac: [{ manager: "pipx", command: "pipx install csvkit" }],
+      linux: [{ manager: "pipx", command: "pipx install csvkit" }],
+      win: [{ manager: "pipx", command: "pipx install csvkit" }]
+    },
+    homepage: "https://csvkit.readthedocs.io/"
+  },
+  podman: {
+    id: "podman",
+    probe: "podman",
+    description: "Daemonless container engine, rootless by default (Docker alternative)",
+    category: "container",
+    tier: 3,
+    install: {
+      mac: [{ manager: "brew", command: "brew install podman" }],
+      linux: [{ manager: "apt", command: "sudo apt install podman" }],
+      win: [{ manager: "winget", command: "winget install RedHat.Podman" }]
+    },
+    homepage: "https://podman.io/"
+  }
+};
+var TIER1_CLI_TOOLS = [
+  "ripgrep",
+  "fd",
+  "jq",
+  "yq",
+  "gh",
+  "delta",
+  "bat",
+  "sd",
+  "ast-grep",
+  "zstd"
+];
+var TIER2_CLI_TOOLS_BY_TRIGGER = {
+  "web-project": ["playwright"],
+  "data-project": ["duckdb", "xsv"],
+  "rust-project": ["taplo"],
+  "python-project": ["taplo"],
+  "docker-detected": ["docker"],
+  "ci-llm-project": ["llm"],
+  "interactive-tty": ["fzf", "lazygit", "difftastic"],
+  "gitlab-remote": ["glab"],
+  "azure-remote": ["az-devops"]
+};
+var TIER3_CLI_TOOLS = [
+  "rtk",
+  "stagehand",
+  "aichat",
+  "mods",
+  "comby",
+  "miller",
+  "csvkit",
+  "podman"
+];
+var DEFAULT_CLI_TOOLS = TIER1_CLI_TOOLS;
+var CLI_TOOL_SECRET_NOTES = Object.freeze(
+  (() => {
+    const out = {};
+    for (const tool of Object.values(AVAILABLE_CLI_TOOLS)) {
+      const env = tool.requiresEnv;
+      if (env && env.length > 0) {
+        out[tool.id] = [...env];
+      }
+    }
+    return out;
+  })()
+);
+
+// src/cli/shared/pickers.ts
+function tierSeparator(tier) {
+  const label2 = tier === 1 ? "\u2500\u2500 Tier 1 \u2014 default-on \u2500\u2500" : tier === 2 ? "\u2500\u2500 Tier 2 \u2014 conditional \u2500\u2500" : "\u2500\u2500 Tier 3 \u2014 opt-in advanced \u2500\u2500";
+  return new inquirer4.Separator(label2);
+}
+function toolChoice(meta, preChecked) {
+  const caveat = meta.caveat ? `${chalk5.yellow("\u26A0")} ` : "";
+  const description = meta.description;
+  return {
+    name: `${caveat}${meta.id} \u2014 ${description}`,
+    value: meta.id,
+    checked: preChecked
+  };
+}
+async function pickCliTools(opts = {}) {
+  const existingSet = new Set(opts.existing ?? []);
+  const suggestedSet = new Set(opts.tier2Suggested ?? []);
+  const hasExistingSelection = (opts.existing?.length ?? 0) > 0;
+  const tier1Choices = [];
+  const tier2Choices = [];
+  const tier3Choices = [];
+  for (const id of TIER1_CLI_TOOLS) {
+    const meta = AVAILABLE_CLI_TOOLS[id];
+    if (!meta) continue;
+    const checked = hasExistingSelection ? existingSet.has(id) : true;
+    tier1Choices.push(toolChoice(meta, checked));
+  }
+  const seenTier2 = /* @__PURE__ */ new Set();
+  for (const ids of Object.values(TIER2_CLI_TOOLS_BY_TRIGGER)) {
+    for (const id of ids) {
+      if (seenTier2.has(id)) continue;
+      seenTier2.add(id);
+      const meta = AVAILABLE_CLI_TOOLS[id];
+      if (!meta) continue;
+      const checked = hasExistingSelection ? existingSet.has(id) : suggestedSet.has(id);
+      tier2Choices.push(toolChoice(meta, checked));
+    }
+  }
+  for (const id of TIER3_CLI_TOOLS) {
+    const meta = AVAILABLE_CLI_TOOLS[id];
+    if (!meta) continue;
+    const checked = hasExistingSelection && existingSet.has(id);
+    tier3Choices.push(toolChoice(meta, checked));
+  }
+  const choices = [
+    tierSeparator(1),
+    ...tier1Choices,
+    tierSeparator(2),
+    ...tier2Choices,
+    tierSeparator(3),
+    ...tier3Choices
+  ];
+  const themeOption = opts.wslTheme ? { theme: opts.wslTheme } : {};
+  const { tools } = await inquirer4.prompt([
+    {
+      type: "checkbox",
+      name: "tools",
+      message: "Select CLI tools (default tier-1 + project-triggered tier-2):",
+      choices,
+      ...themeOption
+    }
+  ]);
+  return tools ?? [];
+}
+async function pickMcpServers(opts) {
+  const platformMcp = PLATFORM_MCP_SERVER[opts.platform];
+  const defaultSelection = opts.existing && opts.existing.length > 0 ? opts.existing : Array.from(/* @__PURE__ */ new Set([platformMcp, "playwright", "context7"]));
+  const themeOption = opts.wslTheme ? { theme: opts.wslTheme } : {};
+  const { mcp } = await inquirer4.prompt([
+    {
+      type: "checkbox",
+      name: "mcp",
+      message: "Select MCP servers:",
+      choices: MCP_CHOICES,
+      default: defaultSelection,
+      ...themeOption
+    }
+  ]);
+  const servers = mcp ?? [];
+  if (!servers.includes(platformMcp)) {
+    servers.unshift(platformMcp);
+  }
+  return servers;
+}
+async function confirmMcpGate(opts) {
+  const defaultYes = opts.defaultYes ?? opts.hasExisting;
+  const { proceed } = await inquirer4.prompt([
+    {
+      type: "confirm",
+      name: "proceed",
+      message: "Configure MCP servers? (CLI tools are recommended as the default)",
+      default: defaultYes
+    }
+  ]);
+  return proceed;
+}
+
+// src/cliTools/detect.ts
+import { spawn } from "child_process";
+var PROBE_TIMEOUT_MS = 2e3;
+function isSafeProbeName(name) {
+  return /^[A-Za-z0-9._\-+]+$/.test(name);
+}
+async function probeBin(name) {
+  if (!isSafeProbeName(name)) return "";
+  const isWindows = process.platform === "win32";
+  const [cmd, args] = isWindows ? ["where", [name]] : ["/bin/sh", ["-c", `command -v -- "${name}"`]];
+  return new Promise((resolve5) => {
+    let settled = false;
+    let stdout = "";
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true
+    });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      resolve5("");
+    }, PROBE_TIMEOUT_MS);
+    child.stdout?.on("data", (chunk) => {
+      stdout += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve5("");
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve5("");
+        return;
+      }
+      const first = stdout.split(/\r?\n/).map((s) => s.trim()).find((s) => s.length > 0) ?? "";
+      resolve5(first);
+    });
+  });
+}
+async function detectCliTool(id) {
+  const meta = AVAILABLE_CLI_TOOLS[id];
+  const probe = meta?.probe ?? id;
+  const path = await probeBin(probe);
+  return {
+    id,
+    probe,
+    installed: path.length > 0,
+    path
+  };
+}
+async function detectCliTools(ids) {
+  return Promise.all(ids.map((id) => detectCliTool(id)));
+}
+async function findMissingCliTools(ids) {
+  const results = await detectCliTools(ids);
+  return results.filter((r) => !r.installed).map((r) => r.id);
+}
+
+// src/cliTools/install.ts
+init_ui();
+import chalk6 from "chalk";
+import inquirer5 from "inquirer";
+
+// src/cliTools/oneLiner.ts
+var GROUPABLE_MANAGERS = /* @__PURE__ */ new Set([
+  "brew",
+  "apt",
+  "apt-get",
+  "dnf",
+  "yum",
+  "pacman",
+  "scoop",
+  "cargo"
+]);
+var JOIN = " \\\n  && ";
+function parseGroupable(command, manager) {
+  if (!manager || !GROUPABLE_MANAGERS.has(manager)) return null;
+  if (command.includes("&&") || command.includes("|") || command.includes(";")) return null;
+  const re = new RegExp(`^(sudo\\s+)?${manager}\\s+install\\s+(\\S+)$`);
+  const match = command.match(re);
+  if (!match) return null;
+  const sudo = match[1] ?? "";
+  const pkg = match[2];
+  return { prefix: `${sudo}${manager} install`, pkg };
+}
+function buildOneLiner(plans) {
+  if (plans.length === 0) return "";
+  const groupOrder = [];
+  const groups = /* @__PURE__ */ new Map();
+  const standalones = [];
+  for (const plan of plans) {
+    if (!plan.command) {
+      standalones.push(`# install ${plan.id} manually: see ${plan.homepage}`);
+      continue;
+    }
+    const parsed = parseGroupable(plan.command, plan.manager);
+    if (!parsed) {
+      standalones.push(plan.command);
+      continue;
+    }
+    const existing = groups.get(parsed.prefix);
+    if (existing) {
+      existing.push(parsed.pkg);
+    } else {
+      groupOrder.push(parsed.prefix);
+      groups.set(parsed.prefix, [parsed.pkg]);
+    }
+  }
+  const chunks = [];
+  for (const prefix of groupOrder) {
+    const pkgs = groups.get(prefix);
+    if (!pkgs) continue;
+    chunks.push(`${prefix} ${pkgs.join(" ")}`);
+  }
+  for (const cmd of standalones) {
+    chunks.push(cmd);
+  }
+  if (chunks.length === 0) return "";
+  return chunks.join(JOIN);
+}
+
+// src/cliTools/install.ts
+function currentOsKey() {
+  if (process.platform === "win32") return "win";
+  if (process.platform === "linux" || process.platform === "freebsd") return "linux";
+  return "mac";
+}
+function buildInstallPlan(ids, os = currentOsKey()) {
+  const plans = [];
+  for (const id of ids) {
+    const meta = AVAILABLE_CLI_TOOLS[id];
+    if (!meta) continue;
+    const cmd = meta.install[os]?.[0];
+    plans.push({
+      id: meta.id,
+      probe: meta.probe,
+      manager: cmd?.manager,
+      command: cmd?.command,
+      homepage: meta.homepage
+    });
+  }
+  return plans;
+}
+async function offerInstaller(missing, opts = {}) {
+  if (missing.length === 0) return true;
+  const os = opts.os ?? currentOsKey();
+  const interactive = opts.interactive ?? true;
+  const plan = buildInstallPlan(missing, os);
+  const osLabel = os === "mac" ? "macOS" : os === "linux" ? "Linux" : "Windows";
+  console.log("");
+  console.log(chalk6.yellow(`${missing.length} CLI tool${missing.length === 1 ? "" : "s"} not detected on PATH (${osLabel}):`));
+  console.log("");
+  for (const entry of plan) {
+    const header = entry.manager ? `${chalk6.cyan(entry.id)} (${entry.manager})` : chalk6.cyan(entry.id);
+    console.log(`  ${header}`);
+    if (entry.command) {
+      console.log(`    ${chalk6.gray("$")} ${entry.command}`);
+    } else {
+      console.log(`    ${chalk6.gray("see")} ${entry.homepage}`);
+    }
+  }
+  console.log("");
+  console.log(chalk6.gray("hatch3r will not run these commands for you \u2014 copy-paste in your shell."));
+  console.log("");
+  const oneLiner = buildOneLiner(plan);
+  if (oneLiner) {
+    console.log(chalk6.yellow("Or copy-paste this one-liner to install everything at once:"));
+    console.log("");
+    for (const line of oneLiner.split("\n")) {
+      console.log(`  ${chalk6.cyan(line)}`);
+    }
+    console.log("");
+  }
+  if (!interactive) return true;
+  const { proceed } = await inquirer5.prompt([
+    {
+      type: "confirm",
+      name: "proceed",
+      message: "Mark these tools as 'install pending' and continue?",
+      default: true
+    }
+  ]);
+  return proceed;
+}
+function printMissingCliToolsDisclaimer(missing, totalSelected, os = currentOsKey()) {
+  if (missing.length === 0) return;
+  const plan = buildInstallPlan(missing, os);
+  const oneLiner = buildOneLiner(plan);
+  const osLabel = os === "mac" ? "macOS" : os === "linux" ? "Linux" : "Windows";
+  const lines = [
+    `${missing.length} of ${totalSelected} selected CLI tools are missing.`,
+    `hatch3r does NOT install them for you.`,
+    "",
+    `Copy-paste to install everything (${osLabel}):`,
+    "",
+    ...oneLiner.split("\n").map((l) => `  ${l}`)
+  ];
+  printBox("CLI tools not installed", lines, "warning");
+}
+
+// src/cliTools/triggers.ts
+var DATA_LANGUAGES = /* @__PURE__ */ new Set(["python", "r", "sql"]);
+var WEB_FRAMEWORKS = /* @__PURE__ */ new Set([
+  "next",
+  "nuxt",
+  "astro",
+  "sveltekit",
+  "remix",
+  "angular",
+  "vue",
+  "react",
+  "svelte"
+]);
+function evaluateTriggers(repoInfo) {
+  const active = /* @__PURE__ */ new Set();
+  if (repoInfo.frameworks.some((f) => WEB_FRAMEWORKS.has(f))) {
+    active.add("web-project");
+  }
+  if (repoInfo.languages.some((l) => DATA_LANGUAGES.has(l))) {
+    active.add("data-project");
+  }
+  if (repoInfo.languages.includes("rust")) {
+    active.add("rust-project");
+  }
+  if (repoInfo.languages.includes("python")) {
+    active.add("python-project");
+  }
+  if (process.stdout && process.stdout.isTTY) {
+    active.add("interactive-tty");
+  }
+  return active;
+}
+function evaluateTier2Triggers(repoInfo) {
+  const triggers = evaluateTriggers(repoInfo);
+  const ids = /* @__PURE__ */ new Set();
+  for (const trigger of triggers) {
+    for (const id of TIER2_CLI_TOOLS_BY_TRIGGER[trigger]) {
+      ids.add(id);
+    }
+  }
+  return [...ids];
+}
+function applyPlatformTriggers(platform, base) {
+  const out = new Set(base);
+  if (platform === "gitlab") {
+    for (const id of TIER2_CLI_TOOLS_BY_TRIGGER["gitlab-remote"]) out.add(id);
+  } else if (platform === "azure-devops") {
+    for (const id of TIER2_CLI_TOOLS_BY_TRIGGER["azure-remote"]) out.add(id);
+  }
+  return [...out];
+}
+
 // src/cli/commands/init.ts
 init_integrity();
 init_version();
@@ -10819,6 +11767,15 @@ function validateWorkspaceManifest(data) {
     if (typeof content.teamSize !== "string") return false;
     if (!content.items || typeof content.items !== "object") return false;
   }
+  if (defaults.cliTools !== void 0) {
+    if (typeof defaults.cliTools !== "object" || defaults.cliTools === null) return false;
+    const cli = defaults.cliTools;
+    if (typeof cli.enabled !== "boolean") return false;
+    if (!Array.isArray(cli.selected)) return false;
+    for (const id of cli.selected) {
+      if (typeof id !== "string") return false;
+    }
+  }
   for (const repo of obj.repos) {
     if (!repo || typeof repo !== "object") return false;
     const r = repo;
@@ -10933,7 +11890,30 @@ function resolveRepoConfig(defaults, overrides, protectedIds) {
       }
     }
   }
-  return { platform, tools, features, mcp, models, contentIds, excludedContent, addedContent };
+  return {
+    platform,
+    tools,
+    features,
+    mcp,
+    models,
+    contentIds,
+    excludedContent,
+    addedContent,
+    cliTools: defaults.cliTools
+  };
+}
+function applyMemberCliToolsOverrides(workspaceDefault, memberLocal, memberExcluded) {
+  if (!workspaceDefault && (!memberLocal || memberLocal.length === 0)) {
+    return void 0;
+  }
+  const base = new Set(workspaceDefault?.selected ?? []);
+  for (const id of memberLocal ?? []) base.add(id);
+  for (const id of memberExcluded ?? []) base.delete(id);
+  const selected = [...base];
+  return {
+    enabled: selected.length > 0,
+    selected
+  };
 }
 function buildSelectionFromIds(ids, baseSelection, allItems) {
   const items = {
@@ -11163,6 +12143,11 @@ async function syncSingleRepo(workspaceRoot, wsManifest, wsChecksum, repoEntry,
     gitRepo = existingManifest.repo;
   }
   if (!gitBranch) gitBranch = "main";
+  const effectiveCliTools = applyMemberCliToolsOverrides(
+    resolved.cliTools,
+    existingManifest?.workspace?.localCliTools,
+    existingManifest?.workspace?.excludedCliTools
+  );
   const manifest = createManifest({
     platform: gitPlatform ?? resolved.platform,
     owner: gitOwner,
@@ -11174,7 +12159,8 @@ async function syncSingleRepo(workspaceRoot, wsManifest, wsChecksum, repoEntry,
     features: resolved.features,
     mcpServers: resolved.mcp.servers,
     content: effectiveSelection,
-    languages: repoInfo.languages
+    languages: repoInfo.languages,
+    cliTools: effectiveCliTools
   });
   manifest.workspace = {
     rootPath: relative4(repoDir, workspaceRoot),
@@ -11182,7 +12168,9 @@ async function syncSingleRepo(workspaceRoot, wsManifest, wsChecksum, repoEntry,
     syncVersion: HATCH3R_VERSION,
     workspaceChecksum: wsChecksum,
     excludedContent: resolved.excludedContent.length > 0 ? resolved.excludedContent : void 0,
-    localContent: existingManifest?.workspace?.localContent
+    localContent: existingManifest?.workspace?.localContent,
+    localCliTools: existingManifest?.workspace?.localCliTools,
+    excludedCliTools: existingManifest?.workspace?.excludedCliTools
   };
   if (resolved.models) {
     manifest.models = resolved.models;
@@ -11251,6 +12239,82 @@ var CONTENT_ROOT2 = findPackageRoot(__dirname2);
 var DEFAULT_TOOLS = ["claude"];
 var DEFAULT_FEATURE_KEYS = Object.keys(DEFAULT_FEATURES);
 var DEFAULT_MCP = ["playwright", "github", "context7"];
+var HANDOFFS_README_SEED = `# Project Handoffs
+
+This directory holds active and archived handoff documents surfaced by the
+\`hatch3r-handoff-loader\` agent at session start and consumed by
+\`/hatch3r-handoff resume\`.
+
+## Layout
+
+- \`active/<id>.md\` \u2014 handoffs in any non-terminal status (open, in-progress, blocked, handed-off, resumed)
+- \`archived/<id>.md\` \u2014 handoffs in terminal status (completed, expired, superseded)
+
+## ID scheme
+
+\`<YYYY-MM-DD>_T<HHmm>_<5hex>_<kebab-slug>\` \u2014 chronologically sortable, collision-safe.
+
+Example: \`2026-05-17_T1430_a3f2c_issue-42-cache-refactor.md\`.
+
+## Lifecycle
+
+- Created by \`/hatch3r-handoff prepare\` or the \`on-context-switch\` hook.
+- Loaded at session start by \`hatch3r-handoff-loader\`.
+- Resumed via \`/hatch3r-handoff resume [<id>]\` (lists actives if no id given).
+- \`expires_after\`: ISO-8601 timestamp; preparer default stamps \`created + 30 days\`.
+- Archived (never deleted by hatch3r) on completion or expiry.
+
+## Required frontmatter
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| \`id\` | string | Filename without \`.md\` |
+| \`type\` | literal \`handoff\` | |
+| \`created\` | ISO-8601 | Immutable |
+| \`updated\` | ISO-8601 | Re-stamped on status change |
+| \`status\` | enum | open \\| in-progress \\| blocked \\| handed-off \\| resumed \\| completed \\| archived |
+| \`source_agent\` | string | Tool/role that prepared the handoff |
+| \`target_agent\` | string | \`any\` allowed but warned (avoids handoff loops) |
+| \`git_ref\` | string | \`branch@sha7\` \u2014 staleness signal |
+| \`branch\` | string | |
+| \`confidence\` | 0..1 | |
+| \`completeness\` | 0..1 | |
+| \`integrity\` | string | \`sha256:<hex>\` \u2014 SHA-256 of body |
+
+Optional: \`work_item\` (platform-prefixed: \`gh:owner/repo#42\`, \`ado:org/project:work-item/123\`, \`gl:owner/repo!42\`), \`expires_after\`, \`summary\` (\u2264200 chars), \`requirements\`, \`compaction_count\`, \`hatch3r_version\`, \`tags\`, \`superseded_by\`, \`parent_handoff\`.
+
+## Body sections (required, in order)
+
+Wrap the body in user-tier instruction-hierarchy markers:
+
+\`\`\`markdown
+--- BEGIN USER-TIER CONTENT: handoff ---
+
+## Problem            (1-3 paragraphs)
+## Decisions          (bullet list)
+## Work Done          (from end-of-session Iteration Summary)
+## Work Remaining
+## Blockers
+## Next Steps         (ordered list)
+## Build & Test Status (table: Check | Status | Notes)
+## File Manifest      (table: Path | Status | Last action)
+
+--- END USER-TIER CONTENT: handoff ---
+\`\`\`
+
+## Caps and validation
+
+- Body \u2264 50 KB, total file \u2264 60 KB.
+- Soft cap 25 active handoffs per repo (warn at 20, refuse briefing at 50).
+- Injection-pattern scan (P-LEARN-01..05) at write and read; reuses learnings catalog.
+- Integrity hash mismatch downgrades confidence to low; included with warning.
+
+## Cross-tool portability
+
+Handoffs are plain Markdown \u2014 readable by humans and any AI tool. Tool-specific adapters (Cursor, Claude, Copilot, etc.) surface active handoffs in their native context file on session-start so a handoff written from one tool resumes cleanly in another.
+
+See \`agents/hatch3r-handoff-loader.md\`, \`skills/hatch3r-handoff-resume/SKILL.md\`, and \`rules/hatch3r-handoff-readiness.md\` for the full protocols.
+`;
 var LEARNINGS_README_SEED = `# Project Learnings
 
 This directory holds project-specific learnings surfaced by the
@@ -11357,7 +12421,7 @@ function selectionHasBoardContent(selection) {
 function warnBoardPrerequisites(selection) {
   if (!selectionHasBoardContent(selection)) return;
   info(
-    `Board commands selected. Prerequisites: ${chalk5.bold("GitHub Projects V2")} must be enabled and your PAT needs the ${chalk5.bold("project")} scope. See ${chalk5.dim("https://docs.github.com/en/issues/planning-and-tracking-with-projects")}`
+    `Board commands selected. Prerequisites: ${chalk7.bold("GitHub Projects V2")} must be enabled and your PAT needs the ${chalk7.bold("project")} scope. See ${chalk7.dim("https://docs.github.com/en/issues/planning-and-tracking-with-projects")}`
   );
 }
 function languagesForSelection(repoInfo) {
@@ -11396,7 +12460,7 @@ async function runInit(options) {
   }
 }
 async function runInitInner(options) {
-  const { rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection, worktreeEnabled, customization } = options;
+  const { rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection, worktreeEnabled, customization, cliTools } = options;
   const skipInitPrompts = options.yes === true;
   const agentsDir = join27(rootDir, AGENTS_DIR);
   const totalSteps = 4;
@@ -11427,6 +12491,18 @@ async function runInitInner(options) {
       throw err;
     }
   }
+  await mkdir8(join27(agentsDir, "handoffs", "active"), { recursive: true });
+  await mkdir8(join27(agentsDir, "handoffs", "archived"), { recursive: true });
+  const handoffsReadmePath = join27(agentsDir, "handoffs", "README.md");
+  try {
+    await access9(handoffsReadmePath);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      await safeWriteFile(handoffsReadmePath, HANDOFFS_README_SEED);
+    } else {
+      throw err;
+    }
+  }
   const mcpPath = join27(agentsDir, "mcp", "mcp.json");
   await filterMcpJsonOnDisk(mcpPath, new Set(mcpServers));
   const canonicalAgentsMd = await generateCanonicalAgentsMd(agentsDir);
@@ -11435,7 +12511,7 @@ async function runInitInner(options) {
   const s2 = createSpinner(step(2, totalSteps, "Preparing manifest..."));
   s2.start();
   const effectiveCustomization = customization ?? existingManifest?.customization;
-  const manifest = createManifest({ platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, content: contentSelection, languages: repoInfo.languages, worktreeEnabled, customization: effectiveCustomization });
+  const manifest = createManifest({ platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, content: contentSelection, languages: repoInfo.languages, worktreeEnabled, customization: effectiveCustomization, cliTools });
   const preservedFields = options.preservedManifestFields ?? (existingManifest ? extractPreservedManifestFields(existingManifest) : void 0);
   if (preservedFields) {
     applyPreservedManifestFields(manifest, preservedFields);
@@ -11544,18 +12620,22 @@ async function runInitInner(options) {
   const isGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
   summaryLines.push("");
   if (isGreenfield) {
-    summaryLines.push(`${chalk5.cyan("\u2192")} Run ${chalk5.bold(formatCommandHint(tools, "project-spec"))} to define your new project`);
+    summaryLines.push(`${chalk7.cyan("\u2192")} Run ${chalk7.bold(formatCommandHint(tools, "project-spec"))} to define your new project`);
   } else {
-    summaryLines.push(`${chalk5.cyan("\u2192")} Run ${chalk5.bold(formatCommandHint(tools, "codebase-map"))} to map your existing codebase`);
+    summaryLines.push(`${chalk7.cyan("\u2192")} Run ${chalk7.bold(formatCommandHint(tools, "codebase-map"))} to map your existing codebase`);
   }
   if (envResult && envResult.newVars.length > 0) {
     summaryLines.push("");
-    summaryLines.push(`${chalk5.yellow("!")} Add your secrets to ${chalk5.bold(".env.mcp")}: ${envResult.newVars.join(", ")}`);
-    summaryLines.push(`  Then run: ${chalk5.dim(getSourceEnvMcpCommand())}`);
+    summaryLines.push(`${chalk7.yellow("!")} Add your secrets to ${chalk7.bold(".env.mcp")}: ${envResult.newVars.join(", ")}`);
+    summaryLines.push(`  Then run: ${chalk7.dim(getSourceEnvMcpCommand())}`);
   }
   printBox("Hatch complete", summaryLines, "success");
+  if (cliTools && cliTools.selected.length > 0) {
+    const finalMissing = await findMissingCliTools(cliTools.selected);
+    printMissingCliToolsDisclaimer(finalMissing, cliTools.selected.length);
+  }
   if (!skipInitPrompts) {
-    const { create } = await inquirer4.prompt([{
+    const { create } = await inquirer6.prompt([{
       type: "confirm",
       name: "create",
       message: "Would you like to create your first custom artifact now?",
@@ -11590,7 +12670,7 @@ async function checkExisting(rootDir, skipPrompt, newSelection) {
           }
         }
       }
-      const { proceed } = await inquirer4.prompt([
+      const { proceed } = await inquirer6.prompt([
         {
           type: "confirm",
           name: "proceed",
@@ -11599,7 +12679,7 @@ async function checkExisting(rootDir, skipPrompt, newSelection) {
         }
       ]);
       if (!proceed) {
-        console.log(chalk5.dim("\n  Init cancelled.\n"));
+        console.log(chalk7.dim("\n  Init cancelled.\n"));
         throw new HatchError("Init cancelled.", 0);
       }
     }
@@ -11636,10 +12716,10 @@ async function initCommand(opts = {}) {
       const detectedRepos = await detectSubRepos(rootDir);
       if (opts.yes) {
         opts.workspace = true;
-        info(chalk5.dim(`No git repo found. ${detectedRepos.length} git repo(s) detected in subdirectories \u2014 initializing as workspace.`));
+        info(chalk7.dim(`No git repo found. ${detectedRepos.length} git repo(s) detected in subdirectories \u2014 initializing as workspace.`));
       } else {
         info(`No git repo found, but ${detectedRepos.length} git repo(s) detected in subdirectories.`);
-        const { useWorkspace } = await inquirer4.prompt([
+        const { useWorkspace } = await inquirer6.prompt([
           {
             type: "confirm",
             name: "useWorkspace",
@@ -11671,7 +12751,7 @@ async function initCommand(opts = {}) {
   }
   if (repoInfo.isMonorepo) detected.push("monorepo");
   if (detected.length > 0) {
-    info(chalk5.dim(`Detected: ${detected.join(", ")}`));
+    info(chalk7.dim(`Detected: ${detected.join(", ")}`));
   }
   if (opts.yes) {
     const remoteUrl2 = getGitRemoteUrl();
@@ -11686,7 +12766,7 @@ async function initCommand(opts = {}) {
       const invalid = rawTools.filter((t) => !VALID_TOOLS.has(t));
       if (invalid.length > 0) {
         error(`Invalid tool(s): ${invalid.join(", ")}`);
-        console.log(chalk5.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
+        console.log(chalk7.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
         throw new HatchError(`Invalid tool(s): ${invalid.join(", ")}`, 1, "VALIDATION_ERROR");
       }
       tools2 = rawTools;
@@ -11698,7 +12778,18 @@ async function initCommand(opts = {}) {
     const worktreeEnabled2 = opts.worktree ?? tools2.some((t) => WORKTREE_CAPABLE_TOOLS.has(t));
     const features2 = { ...DEFAULT_FEATURES };
     const platformMcp = PLATFORM_MCP_SERVER[platform2];
-    const mcpServers2 = features2.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    const mcpServers2 = features2.mcp && opts.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    let cliToolsConfig2;
+    if (opts.noCliTools) {
+      cliToolsConfig2 = { enabled: false, selected: [] };
+    } else {
+      const explicit = resolveCliToolsFlag(opts.cliTools, repoInfo, platform2);
+      const selected = explicit ?? Array.from(/* @__PURE__ */ new Set([
+        ...DEFAULT_CLI_TOOLS,
+        ...applyPlatformTriggers(platform2, evaluateTier2Triggers(repoInfo))
+      ]));
+      cliToolsConfig2 = { enabled: selected.length > 0, selected };
+    }
     const defaultBranch2 = parseGitDefaultBranch();
     const isGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
     const presetId = validateFlag(opts.preset, ["minimal", "standard", "full"], "full", "preset");
@@ -11714,13 +12805,13 @@ async function initCommand(opts = {}) {
     }
     warnBoardPrerequisites(contentSelection2);
     await checkExisting(rootDir, true, contentSelection2);
-    await runInit({ rootDir, platform: platform2, owner: owner2, repo: repo2, namespace: namespace2, project: project2, defaultBranch: defaultBranch2, tools: tools2, features: features2, mcpServers: mcpServers2, repoInfo, contentSelection: contentSelection2, worktreeEnabled: worktreeEnabled2, yes: true });
+    await runInit({ rootDir, platform: platform2, owner: owner2, repo: repo2, namespace: namespace2, project: project2, defaultBranch: defaultBranch2, tools: tools2, features: features2, mcpServers: mcpServers2, repoInfo, contentSelection: contentSelection2, worktreeEnabled: worktreeEnabled2, cliTools: cliToolsConfig2, yes: true });
     return;
   }
   console.log();
   const remoteUrl = getGitRemoteUrl();
   const detectedPlatform = detectPlatformFromRemote(remoteUrl);
-  const platformAnswer = await inquirer4.prompt([
+  const platformAnswer = await inquirer6.prompt([
     {
       type: "select",
       name: "platform",
@@ -11739,7 +12830,7 @@ async function initCommand(opts = {}) {
   let namespace;
   let project;
   if (platform === "azure-devops") {
-    const adoAnswers = await inquirer4.prompt([
+    const adoAnswers = await inquirer6.prompt([
       { type: "input", name: "org", message: "Azure DevOps organization:", default: remote.owner || void 0 },
       { type: "input", name: "project", message: "Azure DevOps project:" },
       { type: "input", name: "repo", message: "Repository name:", default: remote.repo || void 0 }
@@ -11749,7 +12840,7 @@ async function initCommand(opts = {}) {
     namespace = owner;
     project = sanitizeInput(adoAnswers.project);
   } else if (platform === "gitlab") {
-    const glAnswers = await inquirer4.prompt([
+    const glAnswers = await inquirer6.prompt([
       { type: "input", name: "namespace", message: "GitLab namespace (group or username):", default: remote.owner || void 0 },
       { type: "input", name: "project", message: "Project name:", default: remote.repo || void 0 }
     ]);
@@ -11758,7 +12849,7 @@ async function initCommand(opts = {}) {
     namespace = owner;
     project = repo;
   } else {
-    const repoAnswers = await inquirer4.prompt([
+    const repoAnswers = await inquirer6.prompt([
       { type: "input", name: "owner", message: "GitHub owner (org or username):", default: remote.owner || void 0 },
       { type: "input", name: "repo", message: "Repository name:", default: remote.repo || void 0 }
     ]);
@@ -11768,7 +12859,7 @@ async function initCommand(opts = {}) {
     project = repo;
   }
   const defaultBranchDefault = parseGitDefaultBranch();
-  const defaultBranchAnswers = await inquirer4.prompt([
+  const defaultBranchAnswers = await inquirer6.prompt([
     {
       type: "input",
       name: "defaultBranch",
@@ -11789,7 +12880,7 @@ async function initCommand(opts = {}) {
   const isAutoGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
   const greenfieldExcl = countProjectTypeExclusions("greenfield", filterIndex.items);
   const brownfieldExcl = countProjectTypeExclusions("brownfield", filterIndex.items);
-  const projectTypeAnswer = await inquirer4.prompt([
+  const projectTypeAnswer = await inquirer6.prompt([
     {
       type: "select",
       name: "projectType",
@@ -11803,7 +12894,7 @@ async function initCommand(opts = {}) {
   ]);
   const projectType = projectTypeAnswer.projectType;
   const soloExcl = countTeamSizeExclusions("solo", filterIndex.items);
-  const teamSizeAnswer = await inquirer4.prompt([
+  const teamSizeAnswer = await inquirer6.prompt([
     {
       type: "select",
       name: "teamSize",
@@ -11817,7 +12908,7 @@ async function initCommand(opts = {}) {
   ]);
   const teamSize = teamSizeAnswer.teamSize;
   const totalItems = filterIndex.items.length;
-  const presetAnswer = await inquirer4.prompt([
+  const presetAnswer = await inquirer6.prompt([
     {
       type: "select",
       name: "preset",
@@ -11836,7 +12927,7 @@ async function initCommand(opts = {}) {
     }
   ]);
   const selectedPreset = getPreset(presetAnswer.preset);
-  const wslTheme = isWSL() ? { icon: { checked: chalk5.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+  const wslTheme = isWSL() ? { icon: { checked: chalk7.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
   let customSelections;
   if (selectedPreset.id === "custom") {
     const contentIndex = filterIndex;
@@ -11844,7 +12935,7 @@ async function initCommand(opts = {}) {
       contentIndex.items,
       (item) => item.protected || item.tags.includes("core")
     );
-    const customAnswer = await inquirer4.prompt([
+    const customAnswer = await inquirer6.prompt([
       {
         type: "checkbox",
         name: "items",
@@ -11856,7 +12947,7 @@ async function initCommand(opts = {}) {
     customSelections = customAnswer.items;
   }
   const toolDefaults = repoInfo.existingTools.length > 0 ? repoInfo.existingTools : DEFAULT_TOOLS;
-  const toolAnswers = await inquirer4.prompt([
+  const toolAnswers = await inquirer6.prompt([
     {
       type: "checkbox",
       name: "tools",
@@ -11872,7 +12963,7 @@ async function initCommand(opts = {}) {
   if (opts.worktree !== void 0) {
     worktreeEnabled = opts.worktree;
   } else if (hasWorktreeTool) {
-    const wtAnswer = await inquirer4.prompt([{
+    const wtAnswer = await inquirer6.prompt([{
       type: "confirm",
       name: "enabled",
       message: "Enable worktree file isolation (for parallel agent sessions)?",
@@ -11882,14 +12973,50 @@ async function initCommand(opts = {}) {
   } else {
     worktreeEnabled = false;
   }
+  const tier2Suggested = Array.from(/* @__PURE__ */ new Set([
+    ...evaluateTier2Triggers(repoInfo),
+    ...applyPlatformTriggers(platform, [])
+  ]));
+  const selectedCliTools = await pickCliTools({
+    tier2Suggested,
+    wslTheme
+  });
+  if (selectedCliTools.length > 0) {
+    const detectSpinner2 = createSpinner(`Detecting ${selectedCliTools.length} CLI tool(s)...`);
+    detectSpinner2.start();
+    const missing = await findMissingCliTools(selectedCliTools);
+    if (missing.length === 0) {
+      detectSpinner2.succeed(`All ${selectedCliTools.length} CLI tool(s) detected on PATH`);
+    } else {
+      detectSpinner2.warn(`${selectedCliTools.length - missing.length}/${selectedCliTools.length} CLI tool(s) detected; ${missing.length} missing`);
+      await offerInstaller(missing, { interactive: true });
+    }
+    const cliEnvVars = [];
+    for (const id of selectedCliTools) {
+      const notes = CLI_TOOL_SECRET_NOTES[id];
+      if (notes && notes.length > 0) {
+        cliEnvVars.push(`${id}: ${notes.join(", ")}`);
+      }
+    }
+    if (cliEnvVars.length > 0) {
+      info(chalk7.dim("CLI tool environment variables required:"));
+      for (const note of cliEnvVars) {
+        info(chalk7.dim(`  ${note}`));
+      }
+    }
+  }
+  const cliToolsConfig = {
+    enabled: selectedCliTools.length > 0,
+    selected: selectedCliTools
+  };
   const secretNotes = tools.map((t) => TOOL_SECRET_NOTES[t]).filter(Boolean);
   if (secretNotes.length > 0) {
-    info(chalk5.dim("MCP secret loading by tool:"));
+    info(chalk7.dim("MCP secret loading by tool:"));
     for (const note of secretNotes) {
-      info(chalk5.dim(`  ${note}`));
+      info(chalk7.dim(`  ${note}`));
     }
   }
-  const featureAnswers = await inquirer4.prompt([
+  const featureAnswers = await inquirer6.prompt([
     {
       type: "checkbox",
       name: "features",
@@ -11906,23 +13033,9 @@ async function initCommand(opts = {}) {
   }
   let mcpServers = [];
   if (features.mcp) {
-    const platformMcp = PLATFORM_MCP_SERVER[platform];
-    const defaultMcpForPlatform = Array.from(
-      /* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])
-    );
-    const mcpAnswers = await inquirer4.prompt([
-      {
-        type: "checkbox",
-        name: "mcp",
-        message: "Select MCP servers:",
-        choices: MCP_CHOICES,
-        default: defaultMcpForPlatform,
-        ...wslTheme && { theme: wslTheme }
-      }
-    ]);
-    mcpServers = mcpAnswers.mcp ?? [];
-    if (!mcpServers.includes(platformMcp)) {
-      mcpServers.unshift(platformMcp);
+    const proceedMcp = await confirmMcpGate({ hasExisting: false, defaultYes: false });
+    if (proceedMcp) {
+      mcpServers = await pickMcpServers({ platform, wslTheme });
     }
   }
   const contentSelection = resolveSelection(selectedPreset, projectType, teamSize, filterIndex, customSelections, projectLanguages);
@@ -11932,7 +13045,7 @@ async function initCommand(opts = {}) {
   }
   warnBoardPrerequisites(contentSelection);
   await checkExisting(rootDir, false, contentSelection);
-  await runInit({ rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection, worktreeEnabled, yes: false });
+  await runInit({ rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection, worktreeEnabled, cliTools: cliToolsConfig, yes: false });
 }
 async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
   const headless = !!opts.yes;
@@ -11945,13 +13058,21 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     const tools2 = resolveToolsFromOpts(opts.tools, repoInfo);
     const features2 = { ...DEFAULT_FEATURES };
     const platformMcp = PLATFORM_MCP_SERVER[platform2];
-    const mcpServers2 = features2.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    const mcpServers2 = features2.mcp && opts.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    const cliToolsBase = opts.noCliTools ? { enabled: false, selected: [] } : (() => {
+      const explicit = resolveCliToolsFlag(opts.cliTools, repoInfo, platform2);
+      const selected = explicit ?? Array.from(/* @__PURE__ */ new Set([
+        ...DEFAULT_CLI_TOOLS,
+        ...applyPlatformTriggers(platform2, evaluateTier2Triggers(repoInfo))
+      ]));
+      return { enabled: selected.length > 0, selected };
+    })();
     const index = await buildContentIndex(CONTENT_ROOT2);
     const projectLanguages = languagesForSelection(repoInfo);
     const contentSelection2 = resolveSelection(getPreset("full"), "brownfield", "solo", index, void 0, projectLanguages);
     const wsManifest2 = createWorkspaceManifest(
       basename2(rootDir) || "workspace",
-      { platform: platform2, tools: tools2, features: features2, mcp: { servers: mcpServers2 }, content: contentSelection2 },
+      { platform: platform2, tools: tools2, features: features2, mcp: { servers: mcpServers2 }, cliTools: cliToolsBase, content: contentSelection2 },
       [],
       "manual"
     );
@@ -11964,20 +13085,20 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
   }));
   wsSpinner.succeed(`Workspace: ${detectedRepos.length} repo(s) detected`);
   console.log();
-  console.log(chalk5.dim("  Repo            Platform      Owner/Repo                      Branch"));
+  console.log(chalk7.dim("  Repo            Platform      Owner/Repo                      Branch"));
   for (const r of enriched) {
     const name = (r.name ?? r.path).padEnd(16);
     if (r.owner && r.repo) {
       const platLabel = PLATFORM_DISPLAY_NAMES[r.platform].padEnd(14);
       const identity = `${r.owner}/${r.repo}`.padEnd(32);
-      console.log(`  ${name}${chalk5.dim(platLabel)}${chalk5.dim(identity)}${chalk5.dim(r.defaultBranch)}`);
+      console.log(`  ${name}${chalk7.dim(platLabel)}${chalk7.dim(identity)}${chalk7.dim(r.defaultBranch)}`);
     } else {
-      console.log(`  ${name}${chalk5.dim("(no remote detected)")}`);
+      console.log(`  ${name}${chalk7.dim("(no remote detected)")}`);
     }
   }
   console.log();
   if (!headless) {
-    const { acceptIdentity } = await inquirer4.prompt([
+    const { acceptIdentity } = await inquirer6.prompt([
       {
         type: "confirm",
         name: "acceptIdentity",
@@ -11987,9 +13108,9 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     ]);
     if (!acceptIdentity) {
       for (const r of enriched) {
-        console.log(chalk5.bold(`
+        console.log(chalk7.bold(`
   ${r.name ?? r.path}:`));
-        const identity = await inquirer4.prompt([
+        const identity = await inquirer6.prompt([
           { type: "input", name: "owner", message: "  Owner:", default: r.owner || void 0 },
           { type: "input", name: "repo", message: "  Repo:", default: r.repo || void 0 },
           {
@@ -12018,12 +13139,23 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
   let mcpServers;
   let contentSelection;
   let worktreeEnabled;
+  let wsCliTools;
   if (headless) {
     tools = resolveToolsFromOpts(opts.tools, repoInfo);
     worktreeEnabled = opts.worktree ?? tools.some((t) => WORKTREE_CAPABLE_TOOLS.has(t));
     features = { ...DEFAULT_FEATURES };
     const platformMcp = PLATFORM_MCP_SERVER[platform];
-    mcpServers = features.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    mcpServers = features.mcp && opts.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    if (opts.noCliTools) {
+      wsCliTools = { enabled: false, selected: [] };
+    } else {
+      const explicit = resolveCliToolsFlag(opts.cliTools, repoInfo, platform);
+      const selected = explicit ?? Array.from(/* @__PURE__ */ new Set([
+        ...DEFAULT_CLI_TOOLS,
+        ...applyPlatformTriggers(platform, evaluateTier2Triggers(repoInfo))
+      ]));
+      wsCliTools = { enabled: selected.length > 0, selected };
+    }
     const isGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
     const presetId = validateFlag(opts.preset, ["minimal", "standard", "full"], "full", "preset");
     const projectType = validateFlag(opts.projectType, ["greenfield", "brownfield"], isGreenfield ? "greenfield" : "brownfield", "project-type");
@@ -12033,13 +13165,13 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     const projectLanguages = languagesForSelection(repoInfo);
     contentSelection = resolveSelection(preset, projectType, teamSize, index, void 0, projectLanguages);
   } else {
-    const wslTheme = isWSL() ? { icon: { checked: chalk5.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+    const wslTheme = isWSL() ? { icon: { checked: chalk7.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
     const wsFilterIndex = await buildContentIndex(CONTENT_ROOT2);
     const projectLanguages = languagesForSelection(repoInfo);
     const isAutoGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
     const wsGreenfieldExcl = countProjectTypeExclusions("greenfield", wsFilterIndex.items);
     const wsBrownfieldExcl = countProjectTypeExclusions("brownfield", wsFilterIndex.items);
-    const projectTypeAnswer = await inquirer4.prompt([
+    const projectTypeAnswer = await inquirer6.prompt([
       {
         type: "select",
         name: "projectType",
@@ -12053,7 +13185,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     ]);
     const projectType = projectTypeAnswer.projectType;
     const wsSoloExcl = countTeamSizeExclusions("solo", wsFilterIndex.items);
-    const teamSizeAnswer = await inquirer4.prompt([
+    const teamSizeAnswer = await inquirer6.prompt([
       {
         type: "select",
         name: "teamSize",
@@ -12067,7 +13199,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     ]);
     const teamSize = teamSizeAnswer.teamSize;
     const wsTotalItems = wsFilterIndex.items.length;
-    const presetAnswer = await inquirer4.prompt([
+    const presetAnswer = await inquirer6.prompt([
       {
         type: "select",
         name: "preset",
@@ -12093,7 +13225,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
         contentIndex.items,
         (item) => item.protected || item.tags.includes("core")
       );
-      const customAnswer = await inquirer4.prompt([
+      const customAnswer = await inquirer6.prompt([
         {
           type: "checkbox",
           name: "items",
@@ -12105,7 +13237,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
       customSelections = customAnswer.items;
     }
     const toolDefaults = repoInfo.existingTools.length > 0 ? repoInfo.existingTools : DEFAULT_TOOLS;
-    const toolAnswers = await inquirer4.prompt([
+    const toolAnswers = await inquirer6.prompt([
       {
         type: "checkbox",
         name: "tools",
@@ -12120,7 +13252,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     if (opts.worktree !== void 0) {
       worktreeEnabled = opts.worktree;
     } else if (wsHasWorktreeTool) {
-      const wsWtAnswer = await inquirer4.prompt([{
+      const wsWtAnswer = await inquirer6.prompt([{
         type: "confirm",
         name: "enabled",
         message: "Enable worktree file isolation (for parallel agent sessions)?",
@@ -12130,14 +13262,37 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     } else {
       worktreeEnabled = false;
     }
+    const wsTier2Suggested = Array.from(/* @__PURE__ */ new Set([
+      ...evaluateTier2Triggers(repoInfo),
+      ...applyPlatformTriggers(platform, [])
+    ]));
+    const wsSelectedCliTools = await pickCliTools({
+      tier2Suggested: wsTier2Suggested,
+      wslTheme
+    });
+    if (wsSelectedCliTools.length > 0) {
+      const wsDetectSpinner = createSpinner(`Detecting ${wsSelectedCliTools.length} CLI tool(s)...`);
+      wsDetectSpinner.start();
+      const wsMissing = await findMissingCliTools(wsSelectedCliTools);
+      if (wsMissing.length === 0) {
+        wsDetectSpinner.succeed(`All ${wsSelectedCliTools.length} CLI tool(s) detected on PATH`);
+      } else {
+        wsDetectSpinner.warn(`${wsSelectedCliTools.length - wsMissing.length}/${wsSelectedCliTools.length} CLI tool(s) detected; ${wsMissing.length} missing`);
+        await offerInstaller(wsMissing, { interactive: true });
+      }
+    }
+    wsCliTools = {
+      enabled: wsSelectedCliTools.length > 0,
+      selected: wsSelectedCliTools
+    };
     const wsSecretNotes = tools.map((t) => TOOL_SECRET_NOTES[t]).filter(Boolean);
     if (wsSecretNotes.length > 0) {
-      info(chalk5.dim("MCP secret loading by tool:"));
+      info(chalk7.dim("MCP secret loading by tool:"));
       for (const note of wsSecretNotes) {
-        info(chalk5.dim(`  ${note}`));
+        info(chalk7.dim(`  ${note}`));
       }
     }
-    const featureAnswers = await inquirer4.prompt([
+    const featureAnswers = await inquirer6.prompt([
       {
         type: "checkbox",
         name: "features",
@@ -12154,23 +13309,9 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     }
     mcpServers = [];
     if (features.mcp) {
-      const platformMcp = PLATFORM_MCP_SERVER[platform];
-      const defaultMcpForPlatform = Array.from(
-        /* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])
-      );
-      const mcpAnswers = await inquirer4.prompt([
-        {
-          type: "checkbox",
-          name: "mcp",
-          message: "Select MCP servers:",
-          choices: MCP_CHOICES,
-          default: defaultMcpForPlatform,
-          ...wslTheme && { theme: wslTheme }
-        }
-      ]);
-      mcpServers = mcpAnswers.mcp ?? [];
-      if (!mcpServers.includes(platformMcp)) {
-        mcpServers.unshift(platformMcp);
+      const wsProceedMcp = await confirmMcpGate({ hasExisting: false, defaultYes: false });
+      if (wsProceedMcp) {
+        mcpServers = await pickMcpServers({ platform, wslTheme });
       }
     }
     contentSelection = resolveSelection(selectedPreset, projectType, teamSize, wsFilterIndex, customSelections, projectLanguages);
@@ -12195,6 +13336,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     repoInfo,
     contentSelection,
     worktreeEnabled,
+    cliTools: wsCliTools,
     yes: headless
   });
   let repoEntries;
@@ -12209,14 +13351,14 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
       platform: r.platform || void 0
     }));
   } else {
-    const wslTheme = isWSL() ? { icon: { checked: chalk5.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
-    const { syncRepos } = await inquirer4.prompt([
+    const wslTheme = isWSL() ? { icon: { checked: chalk7.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+    const { syncRepos } = await inquirer6.prompt([
       {
         type: "checkbox",
         name: "syncRepos",
         message: "Select repos to sync workspace content to:",
         choices: enriched.map((r) => ({
-          name: `${r.name}${r.hasHatch3r ? chalk5.dim(" (has existing hatch3r)") : ""}`,
+          name: `${r.name}${r.hasHatch3r ? chalk7.dim(" (has existing hatch3r)") : ""}`,
           value: r.path,
           checked: false
         })),
@@ -12230,9 +13372,9 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
         `${conflictingRepos.length} selected repo(s) already have hatch3r installed; their managed files will be overwritten by workspace content.`
       );
       for (const r of conflictingRepos) {
-        console.log(chalk5.dim(`  - ${r.name ?? r.path}`));
+        console.log(chalk7.dim(`  - ${r.name ?? r.path}`));
       }
-      const { confirmConflict } = await inquirer4.prompt([
+      const { confirmConflict } = await inquirer6.prompt([
         {
           type: "confirm",
           name: "confirmConflict",
@@ -12244,7 +13386,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
         for (const r of conflictingRepos) {
           syncSet.delete(r.path);
         }
-        info(chalk5.dim("  Skipped syncing conflicting repos. They remain registered in the workspace \u2014 run `hatch3r sync --repos <path>` after reviewing their managed files."));
+        info(chalk7.dim("  Skipped syncing conflicting repos. They remain registered in the workspace \u2014 run `hatch3r sync --repos <path>` after reviewing their managed files."));
       }
     }
     repoEntries = enriched.map((r) => ({
@@ -12260,7 +13402,7 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
   const dirName = basename2(rootDir) || "workspace";
   const wsManifest = createWorkspaceManifest(
     dirName,
-    { platform, tools, features, mcp: { servers: mcpServers }, content: contentSelection },
+    { platform, tools, features, mcp: { servers: mcpServers }, cliTools: wsCliTools, content: contentSelection },
     repoEntries,
     "manual"
   );
@@ -12291,6 +13433,10 @@ async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
     label("Manifest", `${AGENTS_DIR}/workspace.json`)
   ];
   printBox("Workspace ready", wsLines, "success");
+  if (wsCliTools.selected.length > 0) {
+    const finalMissing = await findMissingCliTools(wsCliTools.selected);
+    printMissingCliToolsDisclaimer(finalMissing, wsCliTools.selected.length);
+  }
 }
 function resolveToolsFromOpts(toolsFlag, repoInfo) {
   if (toolsFlag) {
@@ -12298,7 +13444,7 @@ function resolveToolsFromOpts(toolsFlag, repoInfo) {
     const invalid = rawTools.filter((t) => !VALID_TOOLS.has(t));
     if (invalid.length > 0) {
       error(`Invalid tool(s): ${invalid.join(", ")}`);
-      console.log(chalk5.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
+      console.log(chalk7.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
       throw new HatchError(`Invalid tool(s): ${invalid.join(", ")}`, 1);
     }
     return rawTools;
@@ -12306,6 +13452,22 @@ function resolveToolsFromOpts(toolsFlag, repoInfo) {
   if (repoInfo.existingTools.length > 0) return repoInfo.existingTools;
   return DEFAULT_TOOLS;
 }
+function resolveCliToolsFlag(flag, _repoInfo, _platform) {
+  if (!flag) return void 0;
+  const trimmed = flag.trim();
+  if (trimmed === "") return void 0;
+  if (trimmed === "tier1") return [...TIER1_CLI_TOOLS];
+  if (trimmed === "all") return Object.keys(AVAILABLE_CLI_TOOLS);
+  const rawIds = trimmed.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+  const valid = new Set(Object.keys(AVAILABLE_CLI_TOOLS));
+  const invalid = rawIds.filter((id) => !valid.has(id));
+  if (invalid.length > 0) {
+    error(`Invalid CLI tool(s): ${invalid.join(", ")}`);
+    console.log(chalk7.dim(`  Valid ids: ${[...valid].join(", ")}`));
+    throw new HatchError(`Invalid CLI tool(s): ${invalid.join(", ")}`, 1, "VALIDATION_ERROR");
+  }
+  return rawIds;
+}
 
 // src/cli/commands/clean.ts
 init_hatchJson();
@@ -12328,44 +13490,45 @@ function captureConfig(manifest) {
     },
     worktreeEnabled: manifest.worktree?.enabled ?? false,
     customization: manifest.customization,
+    cliTools: manifest.cliTools,
     preservedFields: extractPreservedManifestFields(manifest)
   };
 }
 function printInventory(inventory) {
   const sections = [];
   if (inventory.adapterFiles.length > 0) {
-    sections.push(`  ${chalk6.red("\xD7")} ${inventory.adapterFiles.length} adapter output file(s)`);
+    sections.push(`  ${chalk8.red("\xD7")} ${inventory.adapterFiles.length} adapter output file(s)`);
   }
   if (inventory.canonicalDir) {
     if ((inventory.userContentCount ?? 0) > 0) {
-      sections.push(`  ${chalk6.red("\xD7")} .agents/ canonical directory ${chalk6.dim("(.agents/user/ preserved)")}`);
+      sections.push(`  ${chalk8.red("\xD7")} .agents/ canonical directory ${chalk8.dim("(.agents/user/ preserved)")}`);
     } else {
-      sections.push(`  ${chalk6.red("\xD7")} .agents/ canonical directory`);
+      sections.push(`  ${chalk8.red("\xD7")} .agents/ canonical directory`);
     }
   }
   if (inventory.worktreeInclude) {
-    sections.push(`  ${chalk6.red("\xD7")} .worktreeinclude`);
+    sections.push(`  ${chalk8.red("\xD7")} .worktreeinclude`);
   }
   if (inventory.archiveDir) {
-    sections.push(`  ${chalk6.red("\xD7")} .hatch3r-archive/`);
+    sections.push(`  ${chalk8.red("\xD7")} .hatch3r-archive/`);
   }
   if (inventory.envMcp) {
-    sections.push(`  ${chalk6.green("\u2713")} .env.mcp ${chalk6.dim("(kept \u2014 contains secrets)")}`);
+    sections.push(`  ${chalk8.green("\u2713")} .env.mcp ${chalk8.dim("(kept \u2014 contains secrets)")}`);
   }
   if (inventory.customizeDir) {
-    sections.push(`  ${chalk6.green("\u2713")} .hatch3r/ ${chalk6.dim("(kept \u2014 customizations)")}`);
+    sections.push(`  ${chalk8.green("\u2713")} .hatch3r/ ${chalk8.dim("(kept \u2014 customizations)")}`);
   }
   if ((inventory.userContentCount ?? 0) > 0) {
     sections.push(
-      `  ${chalk6.green("\u2713")} .agents/user/ ${chalk6.dim(`(${inventory.userContentCount} user artifact(s) \u2014 kept, user-authored)`)}`
+      `  ${chalk8.green("\u2713")} .agents/user/ ${chalk8.dim(`(${inventory.userContentCount} user artifact(s) \u2014 kept, user-authored)`)}`
     );
   }
   if (inventory.learnings.length > 0) {
-    sections.push(`  ${chalk6.green("\u2713")} ${inventory.learnings.length} learning(s) ${chalk6.dim("(backed up for reinit)")}`);
+    sections.push(`  ${chalk8.green("\u2713")} ${inventory.learnings.length} learning(s) ${chalk8.dim("(backed up for reinit)")}`);
   }
   if (sections.length > 0) {
     console.log("");
-    console.log(chalk6.bold("  Cleanup inventory:"));
+    console.log(chalk8.bold("  Cleanup inventory:"));
     for (const s of sections) {
       console.log(s);
     }
@@ -12389,22 +13552,22 @@ async function cleanCommand(opts = {}) {
   printInventory(inventory);
   if (inventory.isWorkspaceRoot) {
     warn("This is a workspace root. Member repos still reference this workspace.");
-    console.log(chalk6.dim("  Clean member repos individually or reinitialize them.\n"));
+    console.log(chalk8.dim("  Clean member repos individually or reinitialize them.\n"));
   }
   if (inventory.isWorkspaceMember) {
-    warn(`This repo is managed by a workspace at ${chalk6.bold(inventory.workspaceRootPath ?? "..")}.`);
+    warn(`This repo is managed by a workspace at ${chalk8.bold(inventory.workspaceRootPath ?? "..")}.`);
     console.log("");
   }
   if (opts.dryRun) {
     const result2 = await executeClean(rootDir, inventory, true);
-    console.log(chalk6.bold("  Would remove:"));
+    console.log(chalk8.bold("  Would remove:"));
     for (const f of result2.removed) {
-      console.log(`    ${chalk6.red("\xD7")} ${f}`);
+      console.log(`    ${chalk8.red("\xD7")} ${f}`);
     }
     if (result2.kept.length > 0) {
-      console.log(chalk6.bold("\n  Would keep:"));
+      console.log(chalk8.bold("\n  Would keep:"));
       for (const f of result2.kept) {
-        console.log(`    ${chalk6.green("\u2713")} ${f}`);
+        console.log(`    ${chalk8.green("\u2713")} ${f}`);
       }
     }
     console.log("");
@@ -12414,7 +13577,7 @@ async function cleanCommand(opts = {}) {
     return;
   }
   if (!opts.yes) {
-    const { proceed } = await inquirer5.prompt([
+    const { proceed } = await inquirer7.prompt([
       {
         type: "confirm",
         name: "proceed",
@@ -12423,7 +13586,7 @@ async function cleanCommand(opts = {}) {
       }
     ]);
     if (!proceed) {
-      console.log(chalk6.dim("\n  Clean cancelled.\n"));
+      console.log(chalk8.dim("\n  Clean cancelled.\n"));
       if (learningsBackup) {
         const { rm: rm5 } = await import("fs/promises");
         await rm5(learningsBackup, { recursive: true, force: true });
@@ -12445,7 +13608,7 @@ async function cleanCommand(opts = {}) {
   }
   if (!opts.yes && config) {
     console.log("");
-    const { reinit } = await inquirer5.prompt([
+    const { reinit } = await inquirer7.prompt([
       {
         type: "confirm",
         name: "reinit",
@@ -12478,6 +13641,10 @@ async function cleanCommand(opts = {}) {
           // manifest preserves integration config and per-artifact overrides
           // across a clean -> reinit cycle.
           customization: config.customization,
+          // 1.7.5 (CLI-tooling pivot): carry the previous CLI-tools
+          // selection forward so clean -> reinit does not silently
+          // re-pick from the default.
+          cliTools: config.cliTools,
           // 1.7.1: carry full platform/user manifest state (board IDs,
           // costTracking, specs, extension config, worktree extras) forward
           // so a clean -> reinit cycle no longer wipes them.
@@ -12496,13 +13663,13 @@ async function cleanCommand(opts = {}) {
           ""
         ];
         if (learningsBackup) {
-          summaryLines2.push(`${chalk6.green("\u2713")} Learnings restored`);
+          summaryLines2.push(`${chalk8.green("\u2713")} Learnings restored`);
         }
         if (inventory.customizeDir) {
-          summaryLines2.push(`${chalk6.green("\u2713")} Customizations preserved`);
+          summaryLines2.push(`${chalk8.green("\u2713")} Customizations preserved`);
         }
         if (inventory.envMcp) {
-          summaryLines2.push(`${chalk6.green("\u2713")} .env.mcp preserved`);
+          summaryLines2.push(`${chalk8.green("\u2713")} .env.mcp preserved`);
         }
         printBox("Reinit complete", summaryLines2, "success");
       } catch (err) {
@@ -12522,16 +13689,16 @@ async function cleanCommand(opts = {}) {
     await rm4(learningsBackup, { recursive: true, force: true });
   }
   const summaryLines = [
-    `${chalk6.red("\xD7")} ${result.removed.length} artifact(s) removed`
+    `${chalk8.red("\xD7")} ${result.removed.length} artifact(s) removed`
   ];
   if (inventory.envMcp) {
-    summaryLines.push(`${chalk6.green("\u2713")} .env.mcp preserved`);
+    summaryLines.push(`${chalk8.green("\u2713")} .env.mcp preserved`);
   }
   if (inventory.customizeDir) {
-    summaryLines.push(`${chalk6.green("\u2713")} .hatch3r/ customizations preserved`);
+    summaryLines.push(`${chalk8.green("\u2713")} .hatch3r/ customizations preserved`);
   }
   summaryLines.push("");
-  summaryLines.push(`${chalk6.cyan("\u2192")} Run ${chalk6.bold("hatch3r init")} when ready to set up again.`);
+  summaryLines.push(`${chalk8.cyan("\u2192")} Run ${chalk8.bold("hatch3r init")} when ready to set up again.`);
   printBox("Clean complete", summaryLines, "success");
 }
 
@@ -12546,18 +13713,20 @@ init_paths();
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { readFile as readFile21 } from "fs/promises";
 import { dirname as dirname16, join as join30 } from "path";
-import chalk8 from "chalk";
-import inquirer7 from "inquirer";
+import chalk10 from "chalk";
+import inquirer9 from "inquirer";
 init_content();
 init_agentsContent();
 init_safeWrite();
 init_worktree();
 var __dirname4 = dirname16(fileURLToPath6(import.meta.url));
-function computeDiff(oldManifest, newTools, newFeatures, newMcp, newPlatform, newOwner, newRepo, newNamespace, newProject) {
+function computeDiff(oldManifest, newTools, newFeatures, newMcp, newPlatform, newOwner, newRepo, newNamespace, newProject, newCliToolIds) {
   const oldToolSet = new Set(oldManifest.tools);
   const newToolSet = new Set(newTools);
   const oldMcpSet = new Set(oldManifest.mcp.servers);
   const newMcpSet = new Set(newMcp);
+  const oldCliSet = new Set(oldManifest.cliTools?.selected ?? []);
+  const newCliSet = new Set(newCliToolIds);
   const enabledFeatures = [];
   const disabledFeatures = [];
   for (const key of Object.keys(DEFAULT_FEATURES)) {
@@ -12574,11 +13743,13 @@ function computeDiff(oldManifest, newTools, newFeatures, newMcp, newPlatform, ne
     platformChanged: newPlatform !== oldManifest.platform,
     repoChanged: newOwner !== oldManifest.owner || newRepo !== oldManifest.repo || newNamespace !== oldManifest.namespace || newProject !== oldManifest.project,
     addedContent: [],
-    removedContent: []
+    removedContent: [],
+    addedCliTools: newCliToolIds.filter((id) => !oldCliSet.has(id)),
+    removedCliTools: [...oldCliSet].filter((id) => !newCliSet.has(id))
   };
 }
 function isDiffEmpty(diff) {
-  return diff.addedTools.length === 0 && diff.removedTools.length === 0 && diff.addedMcp.length === 0 && diff.removedMcp.length === 0 && diff.enabledFeatures.length === 0 && diff.disabledFeatures.length === 0 && !diff.platformChanged && !diff.repoChanged && diff.addedContent.length === 0 && diff.removedContent.length === 0;
+  return diff.addedTools.length === 0 && diff.removedTools.length === 0 && diff.addedMcp.length === 0 && diff.removedMcp.length === 0 && diff.enabledFeatures.length === 0 && diff.disabledFeatures.length === 0 && !diff.platformChanged && !diff.repoChanged && diff.addedContent.length === 0 && diff.removedContent.length === 0 && diff.addedCliTools.length === 0 && diff.removedCliTools.length === 0;
 }
 function printCurrentConfig(manifest) {
   const platformLabel = manifest.platform ? `${PLATFORM_DISPLAY_NAMES[manifest.platform]} (${manifest.namespace || manifest.owner}/${manifest.project || manifest.repo})` : "Not set";
@@ -12589,9 +13760,13 @@ function printCurrentConfig(manifest) {
     label("Platform", platformLabel),
     label("Branch", branch),
     label("Tools", toolNames),
-    label("Features", enabledFeatures.join(", ")),
-    label("MCP", manifest.mcp.servers.length > 0 ? manifest.mcp.servers.join(", ") : "none")
+    label("Features", enabledFeatures.join(", "))
   ];
+  const cliSelected = manifest.cliTools?.selected ?? [];
+  lines.push(label("CLI tools", cliSelected.length > 0 ? cliSelected.join(", ") : "none"));
+  if (manifest.mcp.servers.length > 0) {
+    lines.push(label("MCP", manifest.mcp.servers.join(", ")));
+  }
   if (manifest.content) {
     const total = countSelectionItems(manifest.content);
     lines.push(label("Content", `${total} items (${selectionSummary(manifest.content)})`));
@@ -12604,7 +13779,7 @@ async function configCommand() {
   const manifest = await readManifest(rootDir);
   if (!manifest) {
     error("No .agents/hatch.json found.");
-    console.log(chalk8.dim("  Run `npx hatch3r init` to set up your project first.\n"));
+    console.log(chalk10.dim("  Run `npx hatch3r init` to set up your project first.\n"));
     throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const wsContext = await detectWorkspaceContext(rootDir);
@@ -12613,7 +13788,7 @@ async function configCommand() {
       `This repo is managed by workspace at ${wsContext.workspaceRoot}. Changes here may be overwritten on next workspace sync.`
     );
     console.log();
-    const { action } = await inquirer7.prompt([
+    const { action } = await inquirer9.prompt([
       {
         type: "select",
         name: "action",
@@ -12644,8 +13819,8 @@ async function configCommand() {
     );
   }
   printCurrentConfig(manifest);
-  const wslTheme = isWSL() ? { icon: { checked: chalk8.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
-  const platformAnswer = await inquirer7.prompt([
+  const wslTheme = isWSL() ? { icon: { checked: chalk10.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+  const platformAnswer = await inquirer9.prompt([
     {
       type: "select",
       name: "platform",
@@ -12664,7 +13839,7 @@ async function configCommand() {
   let namespace;
   let project;
   if (platform === "azure-devops") {
-    const adoAnswers = await inquirer7.prompt([
+    const adoAnswers = await inquirer9.prompt([
       { type: "input", name: "org", message: "Azure DevOps organization:", default: manifest.owner || void 0 },
       { type: "input", name: "project", message: "Azure DevOps project:", default: manifest.project || void 0 },
       { type: "input", name: "repo", message: "Repository name:", default: manifest.repo || void 0 }
@@ -12674,7 +13849,7 @@ async function configCommand() {
     namespace = owner;
     project = sanitizeInput(adoAnswers.project);
   } else if (platform === "gitlab") {
-    const glAnswers = await inquirer7.prompt([
+    const glAnswers = await inquirer9.prompt([
       { type: "input", name: "namespace", message: "GitLab namespace (group or username):", default: manifest.namespace || manifest.owner || void 0 },
       { type: "input", name: "project", message: "Project name:", default: manifest.project || manifest.repo || void 0 }
     ]);
@@ -12683,7 +13858,7 @@ async function configCommand() {
     namespace = owner;
     project = repo;
   } else {
-    const repoAnswers = await inquirer7.prompt([
+    const repoAnswers = await inquirer9.prompt([
       { type: "input", name: "owner", message: "GitHub owner (org or username):", default: manifest.owner || void 0 },
       { type: "input", name: "repo", message: "Repository name:", default: manifest.repo || void 0 }
     ]);
@@ -12693,7 +13868,7 @@ async function configCommand() {
     project = repo;
   }
   const currentBranch = manifest.board?.defaultBranch ?? "main";
-  const branchAnswer = await inquirer7.prompt([
+  const branchAnswer = await inquirer9.prompt([
     {
       type: "input",
       name: "defaultBranch",
@@ -12710,7 +13885,7 @@ async function configCommand() {
     }
   ]);
   const defaultBranch = branchAnswer.defaultBranch.trim() || currentBranch;
-  const toolAnswers = await inquirer7.prompt([
+  const toolAnswers = await inquirer9.prompt([
     {
       type: "checkbox",
       name: "tools",
@@ -12725,8 +13900,28 @@ async function configCommand() {
     error("At least one tool must be selected.");
     throw new HatchError("At least one tool must be selected.", 1, "VALIDATION_ERROR");
   }
+  const existingCliTools = manifest.cliTools?.selected ?? [];
+  const selectedCliTools = await pickCliTools({
+    existing: existingCliTools,
+    wslTheme
+  });
+  if (selectedCliTools.length > 0) {
+    const cliSpinner = createSpinner(`Detecting ${selectedCliTools.length} CLI tool(s)...`);
+    cliSpinner.start();
+    const missing = await findMissingCliTools(selectedCliTools);
+    if (missing.length === 0) {
+      cliSpinner.succeed(`All ${selectedCliTools.length} CLI tool(s) detected on PATH`);
+    } else {
+      cliSpinner.warn(`${selectedCliTools.length - missing.length}/${selectedCliTools.length} CLI tool(s) detected; ${missing.length} missing`);
+      await offerInstaller(missing, { interactive: true });
+    }
+  }
+  const cliToolsConfig = {
+    enabled: selectedCliTools.length > 0,
+    selected: selectedCliTools
+  };
   const currentFeatureKeys = Object.keys(DEFAULT_FEATURES).filter((k) => manifest.features[k]);
-  const featureAnswers = await inquirer7.prompt([
+  const featureAnswers = await inquirer9.prompt([
     {
       type: "checkbox",
       name: "features",
@@ -12741,27 +13936,21 @@ async function configCommand() {
   for (const k of Object.keys(features)) {
     features[k] = selectedFeatures.includes(k);
   }
-  let mcpServers = [];
+  const hasExistingMcp = manifest.mcp.servers.length > 0;
+  let mcpServers = hasExistingMcp ? [...manifest.mcp.servers] : [];
   if (features.mcp) {
-    const platformMcp = PLATFORM_MCP_SERVER[platform];
-    const mcpAnswers = await inquirer7.prompt([
-      {
-        type: "checkbox",
-        name: "mcp",
-        message: "Select MCP servers:",
-        choices: MCP_CHOICES,
-        default: manifest.mcp.servers,
-        ...wslTheme && { theme: wslTheme }
-      }
-    ]);
-    mcpServers = mcpAnswers.mcp ?? [];
-    if (!mcpServers.includes(platformMcp)) {
-      mcpServers.unshift(platformMcp);
+    const proceedMcp = await confirmMcpGate({ hasExisting: hasExistingMcp });
+    if (proceedMcp) {
+      mcpServers = await pickMcpServers({
+        platform,
+        existing: manifest.mcp.servers,
+        wslTheme
+      });
     }
   }
   const hasWorktreeTool = tools.some((t) => WORKTREE_CAPABLE_TOOLS.has(t));
   if (hasWorktreeTool) {
-    const wtAnswer = await inquirer7.prompt([{
+    const wtAnswer = await inquirer9.prompt([{
       type: "confirm",
       name: "enabled",
       message: "Enable worktree file isolation (for parallel agent sessions)?",
@@ -12776,7 +13965,7 @@ async function configCommand() {
   let contentMetadataChanged = false;
   if (manifest.content) {
     info(
-      chalk8.dim("Config adds/removes content items. To customize an item's behavior without ") + chalk8.dim("removing it, use .hatch3r/<type>/<id>.customize.yaml instead.")
+      chalk10.dim("Config adds/removes content items. To customize an item's behavior without ") + chalk10.dim("removing it, use .hatch3r/<type>/<id>.customize.yaml instead.")
     );
     console.log();
     const contentRoot = findPackageRoot(__dirname4);
@@ -12785,7 +13974,7 @@ async function configCommand() {
     const previousContent = manifest.content;
     const { projectType, teamSize } = manifest.content;
     const totalItems = index.items.length;
-    const presetAnswer = await inquirer7.prompt([
+    const presetAnswer = await inquirer9.prompt([
       {
         type: "select",
         name: "preset",
@@ -12808,7 +13997,7 @@ async function configCommand() {
     if (selectedPreset.id === "custom") {
       const currentIds = getAllContentIds(manifest.content);
       const groupedChoices = buildTagGroupedCustomContentChoices(index.items, (item) => currentIds.has(item.id));
-      const customAnswer = await inquirer7.prompt([
+      const customAnswer = await inquirer9.prompt([
         {
           type: "checkbox",
           name: "items",
@@ -12855,7 +14044,7 @@ async function configCommand() {
         console.log();
         warn("Dependency warnings for removed content:");
         for (const w of dependencyWarnings) {
-          console.log(chalk8.dim(`  ${w}`));
+          console.log(chalk10.dim(`  ${w}`));
         }
         console.log();
       }
@@ -12889,7 +14078,7 @@ async function configCommand() {
       });
     }
   }
-  const diff = computeDiff(manifest, tools, features, mcpServers, platform, owner, repo, namespace, project);
+  const diff = computeDiff(manifest, tools, features, mcpServers, platform, owner, repo, namespace, project, selectedCliTools);
   diff.addedContent = contentChanges.added;
   diff.removedContent = contentChanges.removed;
   if (isDiffEmpty(diff) && defaultBranch === currentBranch && !contentMetadataChanged) {
@@ -12926,6 +14115,7 @@ async function configCommand() {
   manifest.tools = tools;
   manifest.features = features;
   manifest.mcp = { servers: mcpServers };
+  manifest.cliTools = cliToolsConfig;
   if (manifest.board) {
     manifest.board.owner = owner;
     manifest.board.repo = repo;
@@ -12973,37 +14163,43 @@ async function configCommand() {
   console.log();
   const summaryLines = [];
   if (diff.addedTools.length > 0) {
-    summaryLines.push(`${chalk8.green("+")} Tools added: ${diff.addedTools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")}`);
+    summaryLines.push(`${chalk10.green("+")} Tools added: ${diff.addedTools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")}`);
   }
   if (diff.removedTools.length > 0) {
-    summaryLines.push(`${chalk8.red("-")} Tools removed: ${diff.removedTools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")}`);
+    summaryLines.push(`${chalk10.red("-")} Tools removed: ${diff.removedTools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")}`);
   }
   if (diff.addedMcp.length > 0) {
-    summaryLines.push(`${chalk8.green("+")} MCP added: ${diff.addedMcp.join(", ")}`);
+    summaryLines.push(`${chalk10.green("+")} MCP added: ${diff.addedMcp.join(", ")}`);
   }
   if (diff.removedMcp.length > 0) {
-    summaryLines.push(`${chalk8.red("-")} MCP removed: ${diff.removedMcp.join(", ")}`);
+    summaryLines.push(`${chalk10.red("-")} MCP removed: ${diff.removedMcp.join(", ")}`);
   }
   if (diff.enabledFeatures.length > 0) {
-    summaryLines.push(`${chalk8.green("+")} Features enabled: ${diff.enabledFeatures.join(", ")}`);
+    summaryLines.push(`${chalk10.green("+")} Features enabled: ${diff.enabledFeatures.join(", ")}`);
   }
   if (diff.disabledFeatures.length > 0) {
-    summaryLines.push(`${chalk8.red("-")} Features disabled: ${diff.disabledFeatures.join(", ")}`);
+    summaryLines.push(`${chalk10.red("-")} Features disabled: ${diff.disabledFeatures.join(", ")}`);
   }
   if (diff.platformChanged) {
-    summaryLines.push(`${chalk8.yellow("~")} Platform: ${PLATFORM_DISPLAY_NAMES[platform]}`);
+    summaryLines.push(`${chalk10.yellow("~")} Platform: ${PLATFORM_DISPLAY_NAMES[platform]}`);
   }
   if (diff.repoChanged) {
-    summaryLines.push(`${chalk8.yellow("~")} Repo: ${namespace}/${project}`);
+    summaryLines.push(`${chalk10.yellow("~")} Repo: ${namespace}/${project}`);
   }
   if (diff.addedContent.length > 0) {
-    summaryLines.push(`${chalk8.green("+")} Content added: ${diff.addedContent.length} item(s)`);
+    summaryLines.push(`${chalk10.green("+")} Content added: ${diff.addedContent.length} item(s)`);
   }
   if (diff.removedContent.length > 0) {
-    summaryLines.push(`${chalk8.red("-")} Content removed: ${diff.removedContent.length} item(s)`);
+    summaryLines.push(`${chalk10.red("-")} Content removed: ${diff.removedContent.length} item(s)`);
+  }
+  if (diff.addedCliTools.length > 0) {
+    summaryLines.push(`${chalk10.green("+")} CLI tools added: ${diff.addedCliTools.join(", ")}`);
+  }
+  if (diff.removedCliTools.length > 0) {
+    summaryLines.push(`${chalk10.red("-")} CLI tools removed: ${diff.removedCliTools.join(", ")}`);
   }
   if (defaultBranch !== currentBranch) {
-    summaryLines.push(`${chalk8.yellow("~")} Default branch: ${defaultBranch}`);
+    summaryLines.push(`${chalk10.yellow("~")} Default branch: ${defaultBranch}`);
   }
   summaryLines.push("");
   summaryLines.push(label("Files", `${updateResult.copiedFiles} canonical files updated`));
@@ -13018,7 +14214,7 @@ async function configCommand() {
     console.log();
     info("Customizations migrated to .hatch3r/ (tool-agnostic):");
     for (const m of allMigrations) {
-      console.log(`  ${chalk8.dim(m.from)} ${chalk8.cyan("\u2192")} ${m.to}`);
+      console.log(`  ${chalk10.dim(m.from)} ${chalk10.cyan("\u2192")} ${m.to}`);
     }
     console.log();
   }
@@ -13026,12 +14222,12 @@ async function configCommand() {
     console.log();
     info("Tool migration notes:");
     if (diff.removedTools.length > 0) {
-      info(chalk8.dim(`  Removed tool output archived to .hatch3r-archive/ (recoverable).`));
-      info(chalk8.dim(`  Customizations in .hatch3r/ are tool-agnostic and carry forward.`));
+      info(chalk10.dim(`  Removed tool output archived to .hatch3r-archive/ (recoverable).`));
+      info(chalk10.dim(`  Customizations in .hatch3r/ are tool-agnostic and carry forward.`));
     }
     if (diff.addedTools.length > 0) {
-      info(chalk8.dim(`  New tool output generated. Restart your editor to pick up changes.`));
-      info(chalk8.dim(`  MCP secrets (.env.mcp) are shared across tools \u2014 no re-entry needed.`));
+      info(chalk10.dim(`  New tool output generated. Restart your editor to pick up changes.`));
+      info(chalk10.dim(`  MCP secrets (.env.mcp) are shared across tools \u2014 no re-entry needed.`));
     }
     console.log();
   }
@@ -13041,6 +14237,7 @@ async function configCommand() {
       wsManifestFinal.defaults.tools = tools;
       wsManifestFinal.defaults.features = features;
       wsManifestFinal.defaults.mcp = { servers: mcpServers };
+      wsManifestFinal.defaults.cliTools = cliToolsConfig;
       if (manifest.content) {
         wsManifestFinal.defaults.content = manifest.content;
       }
@@ -13049,11 +14246,11 @@ async function configCommand() {
       }
     }
     console.log();
-    info(chalk8.bold("Workspace configuration"));
+    info(chalk10.bold("Workspace configuration"));
     const currentRepos = wsManifestFinal.repos.map((r) => r.path);
-    console.log(chalk8.dim(`  Repos: ${currentRepos.join(", ") || "(none)"}`));
-    console.log(chalk8.dim(`  Sync strategy: ${wsManifestFinal.syncStrategy}`));
-    const { manageWorkspace } = await inquirer7.prompt([
+    console.log(chalk10.dim(`  Repos: ${currentRepos.join(", ") || "(none)"}`));
+    console.log(chalk10.dim(`  Sync strategy: ${wsManifestFinal.syncStrategy}`));
+    const { manageWorkspace } = await inquirer9.prompt([
       {
         type: "confirm",
         name: "manageWorkspace",
@@ -13066,7 +14263,7 @@ async function configCommand() {
       const existingPaths = new Set(wsManifestFinal.repos.map((r) => r.path));
       const newRepos = detectedRepos.filter((r) => !existingPaths.has(r.path));
       if (newRepos.length > 0) {
-        const { addRepos } = await inquirer7.prompt([
+        const { addRepos } = await inquirer9.prompt([
           {
             type: "checkbox",
             name: "addRepos",
@@ -13084,7 +14281,7 @@ async function configCommand() {
         }
       }
       if (wsManifestFinal.repos.length > 0) {
-        const { syncRepos } = await inquirer7.prompt([
+        const { syncRepos } = await inquirer9.prompt([
           {
             type: "checkbox",
             name: "syncRepos",
@@ -13103,7 +14300,7 @@ async function configCommand() {
         }
       }
       if (wsManifestFinal.repos.length > 0) {
-        const { editIdentity } = await inquirer7.prompt([
+        const { editIdentity } = await inquirer9.prompt([
           {
             type: "select",
             name: "editIdentity",
@@ -13127,9 +14324,9 @@ async function configCommand() {
           info("Re-detected git identities for all repos.");
         } else if (editIdentity === "edit") {
           for (const repo2 of wsManifestFinal.repos) {
-            console.log(chalk8.bold(`
+            console.log(chalk10.bold(`
   ${repo2.name ?? repo2.path}:`));
-            const identity = await inquirer7.prompt([
+            const identity = await inquirer9.prompt([
               { type: "input", name: "owner", message: "  Owner:", default: repo2.owner || void 0 },
               { type: "input", name: "repo", message: "  Repo:", default: repo2.repo || void 0 },
               {
@@ -13152,7 +14349,7 @@ async function configCommand() {
           }
         }
       }
-      const { strategy } = await inquirer7.prompt([
+      const { strategy } = await inquirer9.prompt([
         {
           type: "select",
           name: "strategy",
@@ -13169,7 +14366,7 @@ async function configCommand() {
       let syncAttempted = false;
       let syncFailed = false;
       if (syncCount > 0) {
-        const { syncNow } = await inquirer7.prompt([
+        const { syncNow } = await inquirer9.prompt([
           {
             type: "confirm",
             name: "syncNow",
@@ -13211,6 +14408,10 @@ async function configCommand() {
       await writeWorkspaceManifest(rootDir, wsManifestFinal);
     }
   }
+  if (selectedCliTools.length > 0) {
+    const finalMissing = await findMissingCliTools(selectedCliTools);
+    printMissingCliToolsDisclaimer(finalMissing, selectedCliTools.length);
+  }
 }
 
 // src/cli/commands/sync.ts
@@ -13219,7 +14420,7 @@ init_adapters();
 import { appendFile as appendFile3, readFile as readFile23, stat as stat8, readdir as readdir13 } from "fs/promises";
 import { join as join32 } from "path";
 import { execFileSync as execFileSync8 } from "child_process";
-import chalk9 from "chalk";
+import chalk11 from "chalk";
 
 // src/adapters/contextBudget.ts
 var CONTEXT_BUDGET_TOKENS = {
@@ -13453,14 +14654,14 @@ async function syncCommand(opts = {}) {
   const wsContext = await detectWorkspaceContext(rootDir);
   if (wsContext.type === "workspace-member") {
     warn(
-      `This repository appears to be managed by a workspace at ${wsContext.workspaceRoot ?? ".."}. Run ${chalk9.cyan("hatch3r sync")} from the workspace root to sync all repos.`
+      `This repository appears to be managed by a workspace at ${wsContext.workspaceRoot ?? ".."}. Run ${chalk11.cyan("hatch3r sync")} from the workspace root to sync all repos.`
     );
   }
   const agentsDir = join32(rootDir, AGENTS_DIR);
   const manifest = await readManifest(rootDir);
   if (!manifest) {
     error("No .agents/hatch.json found.");
-    console.log(chalk9.dim("  Run `npx hatch3r init` to set up your project first.\n"));
+    console.log(chalk11.dim("  Run `npx hatch3r init` to set up your project first.\n"));
     throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const m = manifest;
@@ -13785,23 +14986,23 @@ async function syncCommand(opts = {}) {
   }
   console.log();
   const icons = {
-    created: chalk9.green("+"),
-    updated: chalk9.yellow("~"),
+    created: chalk11.green("+"),
+    updated: chalk11.yellow("~"),
     // G5: "unchanged" is a no-op action returned by safeWriteFile when the
     // computed bytes match the file on disk. We render it the same as
     // "skipped" (dim "=") so the human summary remains readable while still
     // signalling that nothing changed.
-    unchanged: chalk9.dim("="),
-    skipped: chalk9.dim("="),
-    "dry-run": chalk9.cyan("?")
+    unchanged: chalk11.dim("="),
+    skipped: chalk11.dim("="),
+    "dry-run": chalk11.cyan("?")
   };
   const compactedResults = compactPhaseOutput(results);
   const summaryLines = compactedResults.map((r) => {
     if (typeof r === "string") {
-      return chalk9.dim(r);
+      return chalk11.dim(r);
     }
-    const icon = icons[r.action] ?? chalk9.dim(" ");
-    return `${icon} ${r.path} ${chalk9.dim(`(${r.action})`)}`;
+    const icon = icons[r.action] ?? chalk11.dim(" ");
+    return `${icon} ${r.path} ${chalk11.dim(`(${r.action})`)}`;
   });
   if (isPipelineTimedOut(pipelineState)) {
     const { report } = terminatePipeline(pipelineState);
@@ -13813,11 +15014,11 @@ async function syncCommand(opts = {}) {
       const before = diffBefore.get(filePath) ?? null;
       const after = diffAfter.get(filePath) ?? null;
       if (before === null && after !== null) {
-        diffLines.push(`${chalk9.green("+ added")}    ${filePath}`);
+        diffLines.push(`${chalk11.green("+ added")}    ${filePath}`);
       } else if (before !== null && after !== null && before !== after) {
-        diffLines.push(`${chalk9.yellow("~ modified")} ${filePath}`);
+        diffLines.push(`${chalk11.yellow("~ modified")} ${filePath}`);
       } else if (before !== null && after !== null && before === after) {
-        diffLines.push(`${chalk9.dim("= unchanged")} ${filePath}`);
+        diffLines.push(`${chalk11.dim("= unchanged")} ${filePath}`);
       }
     }
     if (diffLines.length > 0) {
@@ -13848,7 +15049,7 @@ async function syncCommand(opts = {}) {
   const syncableCount = wsManifest.repos.filter((r) => r.sync).length;
   if (!syncReposRequested && !syncOnSync) {
     if (syncableCount > 0) {
-      info(`Workspace: ${syncableCount} repo(s) available for sync. Run ${chalk9.bold("hatch3r sync --repos")} to propagate.`);
+      info(`Workspace: ${syncableCount} repo(s) available for sync. Run ${chalk11.bold("hatch3r sync --repos")} to propagate.`);
     }
     return;
   }
@@ -13887,12 +15088,12 @@ init_version();
 init_customization();
 init_content();
 init_paths();
-import { readdir as readdir16, readFile as readFile26, access as access11, stat as stat9 } from "fs/promises";
+import { readdir as readdir18, readFile as readFile28, access as access11, stat as stat11 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
-import { dirname as dirname18, join as join35, posix as posix4 } from "path";
+import { dirname as dirname18, join as join37, posix as posix4 } from "path";
 import { fileURLToPath as fileURLToPath8 } from "url";
-import chalk10 from "chalk";
-import { parse as parseYaml4 } from "yaml";
+import chalk12 from "chalk";
+import { parse as parseYaml6 } from "yaml";
 
 // src/content/learningsValidation.ts
 init_customization();
@@ -14035,6 +15236,306 @@ async function validateLearningsDirectory(learningsDir) {
   };
 }
 
+// src/content/handoffs/index.ts
+init_safeWrite();
+import { mkdir as mkdir10, readdir as readdir16, readFile as readFile26, stat as stat10, unlink as unlink4 } from "fs/promises";
+import { join as join35 } from "path";
+import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+
+// src/content/handoffs/validation.ts
+import { createHash as createHash5, randomBytes as randomBytes3 } from "crypto";
+import { readdir as readdir15, readFile as readFile25, stat as stat9 } from "fs/promises";
+import { join as join34 } from "path";
+import { parse as parseYaml4 } from "yaml";
+
+// src/content/handoffs/schema.ts
+var HANDOFF_STATUSES = [
+  "open",
+  "in-progress",
+  "blocked",
+  "handed-off",
+  "resumed",
+  "completed",
+  "archived"
+];
+function isHandoffStatus(value) {
+  return typeof value === "string" && HANDOFF_STATUSES.includes(value);
+}
+
+// src/content/handoffs/validation.ts
+var MAX_HANDOFF_BODY_BYTES = 51200;
+var MAX_HANDOFF_FILE_BYTES = 61440;
+var MAX_ACTIVE_HANDOFFS_PER_REPO = 25;
+var MAX_SUMMARY_LENGTH = 200;
+var REQUIRED_BODY_SECTIONS = [
+  "Problem",
+  "Decisions",
+  "Work Done",
+  "Work Remaining",
+  "Blockers",
+  "Next Steps",
+  "Build & Test Status",
+  "File Manifest"
+];
+var HANDOFF_ID_PATTERN = /^[12][0-9]{3}-[01][0-9]-[0-3][0-9]_T[0-2][0-9][0-5][0-9]_[0-9a-f]{5}_[a-z0-9][a-z0-9-]{0,59}$/;
+var BINARY_CONTENT_PATTERN2 = /\0/;
+var SECTION_HEADING_PATTERN = /^##\s+(.+?)\s*$/gm;
+var INTEGRITY_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function computeHandoffIntegrity(body) {
+  const trimmed = body.trim();
+  const hash = createHash5("sha256").update(trimmed, "utf-8").digest("hex");
+  return `sha256:${hash}`;
+}
+function isHandoffExpired(handoff, now = /* @__PURE__ */ new Date()) {
+  const expires = handoff.frontmatter.expires_after;
+  if (!expires) return false;
+  const expiresMs = Date.parse(expires);
+  if (Number.isNaN(expiresMs)) return false;
+  return expiresMs <= now.getTime();
+}
+function extractSectionHeadings(body) {
+  const headings = [];
+  SECTION_HEADING_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = SECTION_HEADING_PATTERN.exec(body)) !== null) {
+    headings.push(match[1].trim());
+  }
+  return headings;
+}
+function scanForInjectionPatterns(body) {
+  const hits = [];
+  for (const { patternId, pattern } of LEARNINGS_INJECTION_PATTERNS) {
+    if (pattern.test(body)) hits.push(patternId);
+  }
+  return hits;
+}
+function validateHandoffContent(handoff, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const driftWarnings = [];
+  const fm = handoff.frontmatter;
+  if (typeof handoff.body !== "string" || handoff.body.trim().length === 0) {
+    errors.push("Handoff body is empty.");
+  } else if (BINARY_CONTENT_PATTERN2.test(handoff.body)) {
+    errors.push(
+      "Handoff body contains binary content (null bytes detected). Only UTF-8 text is allowed."
+    );
+  } else {
+    const bodyBytes = Buffer.byteLength(handoff.body, "utf-8");
+    if (bodyBytes > MAX_HANDOFF_BODY_BYTES) {
+      errors.push(
+        `Handoff body exceeds ${MAX_HANDOFF_BODY_BYTES} byte limit (${bodyBytes} bytes). Split or compact the handoff.`
+      );
+    }
+  }
+  if (typeof fm.id !== "string" || !HANDOFF_ID_PATTERN.test(fm.id)) {
+    errors.push(
+      `Handoff id is missing or malformed (expected pattern <YYYY-MM-DD>_T<HHmm>_<5hex>_<slug>, got "${String(fm.id)}").`
+    );
+  }
+  if (fm.type !== "handoff") {
+    errors.push(`Handoff frontmatter.type must be "handoff" (got "${String(fm.type)}").`);
+  }
+  if (typeof fm.created !== "string" || Number.isNaN(Date.parse(fm.created))) {
+    errors.push(`Handoff frontmatter.created must be ISO-8601 (got "${String(fm.created)}").`);
+  }
+  if (typeof fm.updated !== "string" || Number.isNaN(Date.parse(fm.updated))) {
+    errors.push(`Handoff frontmatter.updated must be ISO-8601 (got "${String(fm.updated)}").`);
+  }
+  if (!isHandoffStatus(fm.status)) {
+    errors.push(`Handoff status is invalid: "${String(fm.status)}".`);
+  }
+  if (typeof fm.source_agent !== "string" || fm.source_agent.length === 0) {
+    errors.push("Handoff source_agent is missing.");
+  }
+  if (typeof fm.target_agent !== "string" || fm.target_agent.length === 0) {
+    errors.push("Handoff target_agent is missing.");
+  } else if (fm.target_agent === "any") {
+    warnings.push(
+      'target_agent is "any" \u2014 explicit target_agent recommended to avoid handoff loops.'
+    );
+  }
+  if (typeof fm.git_ref !== "string" || fm.git_ref.length === 0) {
+    errors.push("Handoff git_ref is missing.");
+  }
+  if (typeof fm.branch !== "string" || fm.branch.length === 0) {
+    errors.push("Handoff branch is missing.");
+  }
+  if (typeof fm.confidence !== "number" || Number.isNaN(fm.confidence) || fm.confidence < 0 || fm.confidence > 1) {
+    errors.push(`Handoff confidence must be 0..1 inclusive (got ${String(fm.confidence)}).`);
+  }
+  if (typeof fm.completeness !== "number" || Number.isNaN(fm.completeness) || fm.completeness < 0 || fm.completeness > 1) {
+    errors.push(`Handoff completeness must be 0..1 inclusive (got ${String(fm.completeness)}).`);
+  }
+  if (typeof fm.integrity !== "string" || !INTEGRITY_PATTERN.test(fm.integrity)) {
+    errors.push(
+      `Handoff integrity must be "sha256:<64-hex>" (got "${String(fm.integrity)}").`
+    );
+  } else if (typeof handoff.body === "string" && handoff.body.trim().length > 0) {
+    const computed = computeHandoffIntegrity(handoff.body);
+    if (computed !== fm.integrity) {
+      errors.push(
+        `Handoff integrity hash does not match body content (declared ${fm.integrity}, computed ${computed}).`
+      );
+    }
+  }
+  if (typeof fm.summary === "string" && fm.summary.length > MAX_SUMMARY_LENGTH) {
+    warnings.push(
+      `Handoff summary exceeds ${MAX_SUMMARY_LENGTH} chars (${fm.summary.length} chars). Compact the summary; full context belongs in the body.`
+    );
+  }
+  if (typeof handoff.body === "string" && handoff.body.length > 0) {
+    const present = new Set(extractSectionHeadings(handoff.body));
+    for (const required of REQUIRED_BODY_SECTIONS) {
+      if (!present.has(required)) {
+        errors.push(`Handoff body is missing required section "## ${required}".`);
+      }
+    }
+    if (!options.skipInjectionScan) {
+      const hits = scanForInjectionPatterns(handoff.body);
+      for (const patternId of hits) {
+        errors.push(
+          `Handoff body matches injection pattern ${patternId}. Review and sanitize before consuming.`
+        );
+      }
+    }
+  }
+  if (isHandoffExpired(handoff, options.now)) {
+    driftWarnings.push(
+      `Handoff expired at ${String(fm.expires_after)}. Archive or refresh before resuming.`
+    );
+  }
+  if (typeof options.currentGitRef === "string" && options.currentGitRef.length > 0) {
+    if (fm.git_ref !== options.currentGitRef) {
+      driftWarnings.push(
+        `Handoff git_ref "${fm.git_ref}" differs from current "${options.currentGitRef}". Code has moved since the handoff was authored.`
+      );
+    }
+  }
+  const result = {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+  if (driftWarnings.length > 0) result.driftWarnings = driftWarnings;
+  return result;
+}
+async function loadHandoffFile(filePath) {
+  let raw;
+  let readError = null;
+  try {
+    const fileStat = await stat9(filePath);
+    if (fileStat.size > MAX_HANDOFF_FILE_BYTES) {
+      return {
+        error: `Handoff file "${filePath}" exceeds ${MAX_HANDOFF_FILE_BYTES} byte limit (${fileStat.size} bytes).`
+      };
+    }
+    raw = await readFile25(filePath, "utf-8");
+  } catch (err) {
+    readError = `Failed to read handoff "${filePath}": ${err.message}`;
+    raw = "";
+  }
+  if (readError !== null) {
+    return { error: readError };
+  }
+  if (!raw.startsWith("---")) {
+    return { error: `Handoff "${filePath}" is missing YAML frontmatter delimiter.` };
+  }
+  const afterFirst = raw.slice(3);
+  const newlineAfterFirst = afterFirst.indexOf("\n");
+  if (newlineAfterFirst < 0) {
+    return { error: `Handoff "${filePath}" has malformed frontmatter delimiter.` };
+  }
+  const fmStart = newlineAfterFirst + 1;
+  const closeMatch = afterFirst.slice(fmStart).match(/\n---\s*(?:\r?\n|$)/);
+  if (!closeMatch || typeof closeMatch.index !== "number") {
+    return { error: `Handoff "${filePath}" frontmatter is not closed by "---".` };
+  }
+  const yamlBlock = afterFirst.slice(fmStart, fmStart + closeMatch.index);
+  const bodyStart = fmStart + closeMatch.index + closeMatch[0].length;
+  const body = afterFirst.slice(bodyStart);
+  let parsed;
+  let parseError = null;
+  try {
+    parsed = parseYaml4(yamlBlock);
+  } catch (err) {
+    parseError = `Handoff "${filePath}" has invalid YAML frontmatter: ${err.message}`;
+    parsed = null;
+  }
+  if (parseError !== null) {
+    return { error: parseError };
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return { error: `Handoff "${filePath}" frontmatter is not a YAML mapping.` };
+  }
+  return {
+    handoff: {
+      frontmatter: parsed,
+      body,
+      filePath
+    }
+  };
+}
+async function validateHandoffsDirectory(activeDir, options = {}) {
+  const errors = [];
+  const warnings = [];
+  async function listMdFiles(dir) {
+    try {
+      const entries = await readdir15(dir);
+      return entries.filter((f) => f.endsWith(".md"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return null;
+      warnings.push(`Failed to list handoff dir "${dir}": ${err.message}`);
+      return null;
+    }
+  }
+  const activeFiles = await listMdFiles(activeDir) ?? [];
+  if (activeFiles.length > MAX_ACTIVE_HANDOFFS_PER_REPO) {
+    warnings.push(
+      `Active handoff count (${activeFiles.length}) exceeds soft cap (${MAX_ACTIVE_HANDOFFS_PER_REPO}). Archive completed handoffs to reduce drift surface.`
+    );
+  }
+  for (const file of activeFiles) {
+    const { handoff, error: error2 } = await loadHandoffFile(join34(activeDir, file));
+    if (error2 || !handoff) {
+      errors.push(error2 ?? `Failed to load handoff "${file}".`);
+      continue;
+    }
+    const r = validateHandoffContent(handoff, { currentGitRef: options.currentGitRef });
+    for (const e of r.errors) errors.push(`[${file}] ${e}`);
+    for (const w of r.warnings) warnings.push(`[${file}] ${w}`);
+    if (r.driftWarnings) {
+      for (const dw of r.driftWarnings) warnings.push(`[${file}] ${dw}`);
+    }
+  }
+  let archivedCount = 0;
+  if (options.archivedDir) {
+    const archivedFiles = await listMdFiles(options.archivedDir) ?? [];
+    archivedCount = archivedFiles.length;
+    for (const file of archivedFiles) {
+      const { handoff, error: error2 } = await loadHandoffFile(join34(options.archivedDir, file));
+      if (error2 || !handoff) {
+        errors.push(error2 ?? `Failed to load archived handoff "${file}".`);
+        continue;
+      }
+      const r = validateHandoffContent(handoff);
+      for (const e of r.errors) errors.push(`[archived/${file}] ${e}`);
+      for (const w of r.warnings) warnings.push(`[archived/${file}] ${w}`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    activeCount: activeFiles.length,
+    archivedCount
+  };
+}
+
+// src/content/handoffs/index.ts
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+
 // src/cli/commands/validate.ts
 init_customize();
 init_mcpEnv();
@@ -14171,8 +15672,8 @@ function detectSecrets(envVars) {
 
 // src/pipeline/complianceVerification.ts
 init_agentToolAllowlist();
-import { readFile as readFile25, readdir as readdir15 } from "fs/promises";
-import { dirname as dirname17, join as join34 } from "path";
+import { readFile as readFile27, readdir as readdir17 } from "fs/promises";
+import { dirname as dirname17, join as join36 } from "path";
 import { fileURLToPath as fileURLToPath7 } from "url";
 
 // src/pipeline/reviewLoop.ts
@@ -14211,13 +15712,13 @@ var RESILIENCE_MODULES = [
 var __dirname5 = dirname17(fileURLToPath7(import.meta.url));
 async function resolveCommandsDir() {
   const candidates = [
-    join34(__dirname5, "..", "cli", "commands"),
-    join34(__dirname5, "..", "..", "src", "cli", "commands"),
-    join34(__dirname5, "..", "cli")
+    join36(__dirname5, "..", "cli", "commands"),
+    join36(__dirname5, "..", "..", "src", "cli", "commands"),
+    join36(__dirname5, "..", "cli")
   ];
   for (const candidate of candidates) {
     try {
-      const entries = await readdir15(candidate);
+      const entries = await readdir17(candidate);
       if (entries.length > 0) return candidate;
     } catch {
     }
@@ -14230,11 +15731,11 @@ async function detectResilienceInvocations() {
   if (!commandsDir) return invoked;
   let entries;
   try {
-    entries = await readdir15(commandsDir, { recursive: true });
+    entries = await readdir17(commandsDir, { recursive: true });
   } catch {
     return invoked;
   }
-  const files = entries.filter((e) => typeof e === "string" && (e.endsWith(".ts") || e.endsWith(".js"))).map((e) => join34(commandsDir, e));
+  const files = entries.filter((e) => typeof e === "string" && (e.endsWith(".ts") || e.endsWith(".js"))).map((e) => join36(commandsDir, e));
   const patterns = {};
   for (const mod of RESILIENCE_MODULES) {
     patterns[mod] = new RegExp(`pipeline/${mod}(?:\\.js)?["']`);
@@ -14242,7 +15743,7 @@ async function detectResilienceInvocations() {
   for (const file of files) {
     let contents;
     try {
-      contents = await readFile25(file, "utf-8");
+      contents = await readFile27(file, "utf-8");
     } catch {
       continue;
     }
@@ -14403,6 +15904,8 @@ var DEFAULT_KNOWN_AGENTS = /* @__PURE__ */ new Set([
   "hatch3r-devops",
   "hatch3r-docs-writer",
   "hatch3r-fixer",
+  "hatch3r-handoff-loader",
+  "hatch3r-handoff-preparer",
   "hatch3r-implementer",
   "hatch3r-learnings-loader",
   "hatch3r-lint-fixer",
@@ -14434,7 +15937,7 @@ async function validateManifest2(rootDir, manifest, result) {
   if (!manifest.tools || manifest.tools.length === 0) result.warnings.push("hatch.json: no tools configured");
   for (const managedFile of manifest.managedFiles ?? []) {
     try {
-      await access11(join35(rootDir, managedFile));
+      await access11(join37(rootDir, managedFile));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       result.warnings.push(`Managed file missing from disk: ${managedFile}`);
@@ -14446,7 +15949,7 @@ async function validateDirectories(agentsDir, result) {
   const optionalDirs = ["commands", "prompts", "mcp", "policy", "github-agents"];
   for (const dir of requiredDirs) {
     try {
-      await access11(join35(agentsDir, dir));
+      await access11(join37(agentsDir, dir));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       result.errors.push(`Required directory missing: .agents/${dir}/`);
@@ -14454,7 +15957,7 @@ async function validateDirectories(agentsDir, result) {
   }
   for (const dir of optionalDirs) {
     try {
-      await access11(join35(agentsDir, dir));
+      await access11(join37(agentsDir, dir));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       verboseWarn(result, `Optional directory missing: .agents/${dir}/`);
@@ -14465,13 +15968,13 @@ async function validateFrontmatter(agentsDir, result) {
   const requiredDirs = ["agents", "skills", "rules"];
   const optionalDirs = ["commands", "prompts", "mcp", "policy", "github-agents"];
   for (const dir of [...requiredDirs, ...optionalDirs]) {
-    const dirPath = join35(agentsDir, dir);
+    const dirPath = join37(agentsDir, dir);
     try {
-      const entries = await readdir16(dirPath, { withFileTypes: true });
+      const entries = await readdir18(dirPath, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isFile() && entry.name.endsWith(".md")) {
-          const filePath = join35(dirPath, entry.name);
-          const content = await readFile26(filePath, "utf-8");
+          const filePath = join37(dirPath, entry.name);
+          const content = await readFile28(filePath, "utf-8");
           if (!content.startsWith("---")) {
             result.warnings.push(`Missing frontmatter: .agents/${dir}/${entry.name}`);
           } else {
@@ -14480,7 +15983,7 @@ async function validateFrontmatter(agentsDir, result) {
               result.errors.push(`Invalid frontmatter (no closing ---): .agents/${dir}/${entry.name}`);
             } else {
               const frontmatter = content.slice(3, endIdx).trim();
-              const parsedFm = parseYaml4(frontmatter);
+              const parsedFm = parseYaml6(frontmatter);
               const idField = dir === "github-agents" ? "name" : "id";
               if (!parsedFm || typeof parsedFm !== "object" || !parsedFm[idField]) {
                 result.warnings.push(`Missing '${idField}' in frontmatter: .agents/${dir}/${entry.name}`);
@@ -14498,7 +16001,7 @@ async function validateFrontmatter(agentsDir, result) {
           }
         } else if (entry.isDirectory()) {
           if (dir !== "skills") continue;
-          const skillPath = join35(dirPath, entry.name, "SKILL.md");
+          const skillPath = join37(dirPath, entry.name, "SKILL.md");
           try {
             await access11(skillPath);
           } catch (err) {
@@ -14512,7 +16015,7 @@ async function validateFrontmatter(agentsDir, result) {
     }
   }
   try {
-    await access11(join35(agentsDir, "AGENTS.md"));
+    await access11(join37(agentsDir, "AGENTS.md"));
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     result.warnings.push("Missing .agents/AGENTS.md");
@@ -14634,29 +16137,29 @@ async function validateManagedFilePrefixes(manifest, result) {
 }
 async function validateHooks(agentsDir, manifest, result) {
   if (!manifest.features.hooks) return;
-  const hooksDir = join35(agentsDir, "hooks");
+  const hooksDir = join37(agentsDir, "hooks");
   try {
-    const hookFiles = await readdir16(hooksDir);
+    const hookFiles = await readdir18(hooksDir);
     const mdHooks = hookFiles.filter((f) => f.endsWith(".md"));
     if (mdHooks.length === 0) {
       result.warnings.push("Hooks feature enabled but no hook definitions found in .agents/hooks/");
     }
     let agentFiles;
     try {
-      const agentEntries = await readdir16(join35(agentsDir, "agents"));
+      const agentEntries = await readdir18(join37(agentsDir, "agents"));
       agentFiles = new Set(agentEntries.filter((f) => f.endsWith(".md")));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
     for (const hookFile of mdHooks) {
-      const hookContent = await readFile26(join35(hooksDir, hookFile), "utf-8");
+      const hookContent = await readFile28(join37(hooksDir, hookFile), "utf-8");
       if (!hookContent.startsWith("---")) {
         result.warnings.push(`Hook missing frontmatter: .agents/hooks/${hookFile}`);
         continue;
       }
       const endIdx = hookContent.indexOf("---", 3);
       if (endIdx === -1) continue;
-      const fm = parseYaml4(hookContent.slice(3, endIdx).trim());
+      const fm = parseYaml6(hookContent.slice(3, endIdx).trim());
       if (fm?.event && typeof fm.event === "string") {
         if (!isValidHookEvent(fm.event)) {
           result.errors.push(`Hook "${hookFile}" has invalid event "${fm.event}". Valid events: pre-commit, post-merge, ci-failure, file-save, session-start, pre-push`);
@@ -14681,9 +16184,9 @@ async function validateHooks(agentsDir, manifest, result) {
 }
 async function validateMcp(agentsDir, manifest, result) {
   if (!manifest.features.mcp || manifest.mcp.servers.length === 0) return;
-  const mcpPath = join35(agentsDir, "mcp", "mcp.json");
+  const mcpPath = join37(agentsDir, "mcp", "mcp.json");
   try {
-    const mcpContent = await readFile26(mcpPath, "utf-8");
+    const mcpContent = await readFile28(mcpPath, "utf-8");
     const mcpParsed = JSON.parse(mcpContent);
     if (!mcpParsed.mcpServers || typeof mcpParsed.mcpServers !== "object") {
       result.errors.push("MCP config missing 'mcpServers' key");
@@ -14696,6 +16199,18 @@ async function validateMcp(agentsDir, manifest, result) {
     }
   }
 }
+async function validateCliTools(manifest, result) {
+  const cli = manifest.cliTools;
+  if (!cli?.enabled || cli.selected.length === 0) return;
+  const detection = await detectCliTools(cli.selected);
+  for (const r of detection) {
+    if (!r.installed) {
+      result.warnings.push(
+        `CLI tool '${r.id}' not found on PATH \u2014 run \`npx hatch3r cli-tools install\``
+      );
+    }
+  }
+}
 async function validateModels(manifest, result) {
   if (!manifest.models) return;
   if (manifest.models.default && typeof manifest.models.default !== "string") {
@@ -14738,21 +16253,21 @@ async function validateCustomizeYaml(rootDir, result) {
     enabled: "boolean"
   };
   for (const { dir } of CUSTOMIZATION_TYPES) {
-    const customDir = join35(rootDir, ".hatch3r", dir);
+    const customDir = join37(rootDir, ".hatch3r", dir);
     let files;
     try {
-      files = await readdir16(customDir);
+      files = await readdir18(customDir);
     } catch (err) {
       if (err.code === "ENOENT") continue;
       throw err;
     }
     const yamlFiles = files.filter((f) => f.endsWith(".customize.yaml"));
     for (const file of yamlFiles) {
-      const filePath = join35(customDir, file);
+      const filePath = join37(customDir, file);
       const itemId = file.replace(".customize.yaml", "");
       let raw;
       try {
-        raw = await readFile26(filePath, "utf-8");
+        raw = await readFile28(filePath, "utf-8");
       } catch {
         continue;
       }
@@ -14764,7 +16279,7 @@ async function validateCustomizeYaml(rootDir, result) {
       }
       let parsed;
       try {
-        parsed = parseYaml4(raw);
+        parsed = parseYaml6(raw);
       } catch {
         result.errors.push(
           `Invalid YAML syntax in .hatch3r/${dir}/${file}`
@@ -14815,13 +16330,13 @@ async function validateCustomizeYaml(rootDir, result) {
 }
 async function validateCustomizations(rootDir, agentsDir, manifest, result) {
   for (const { dir, canonical } of CUSTOMIZATION_TYPES) {
-    const customDir = join35(rootDir, ".hatch3r", dir);
+    const customDir = join37(rootDir, ".hatch3r", dir);
     try {
-      const customFiles = await readdir16(customDir);
+      const customFiles = await readdir18(customDir);
       for (const file of customFiles) {
         if (file.endsWith(".customize.yaml")) {
           const itemId = file.replace(".customize.yaml", "");
-          const canonicalPath = canonical === "skills" ? join35(agentsDir, canonical, itemId) : join35(agentsDir, canonical, `${itemId}.md`);
+          const canonicalPath = canonical === "skills" ? join37(agentsDir, canonical, itemId) : join37(agentsDir, canonical, `${itemId}.md`);
           try {
             await access11(canonicalPath);
           } catch (err) {
@@ -14838,7 +16353,7 @@ async function validateCustomizations(rootDir, agentsDir, manifest, result) {
 async function findContentFile(agentsDir, cfg, id) {
   const baseId = id.startsWith("cmd-") ? id.slice(4) : id;
   if (cfg.strategy === "subdir") {
-    const path = join35(agentsDir, cfg.dir, baseId, "SKILL.md");
+    const path = join37(agentsDir, cfg.dir, baseId, "SKILL.md");
     try {
       await access11(path);
       return path;
@@ -14846,19 +16361,19 @@ async function findContentFile(agentsDir, cfg, id) {
       return null;
     }
   }
-  const root = join35(agentsDir, cfg.dir);
+  const root = join37(agentsDir, cfg.dir);
   const stack = [root];
   const mdFiles = [];
   while (stack.length > 0) {
     const dir = stack.pop();
     let entries;
     try {
-      entries = await readdir16(dir, { withFileTypes: true });
+      entries = await readdir18(dir, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
-      const full = join35(dir, entry.name);
+      const full = join37(dir, entry.name);
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -14871,11 +16386,11 @@ async function findContentFile(agentsDir, cfg, id) {
   }
   for (const file of mdFiles) {
     try {
-      const raw = await readFile26(file, "utf-8");
+      const raw = await readFile28(file, "utf-8");
       if (!raw.startsWith("---")) continue;
       const endIdx = raw.indexOf("---", 3);
       if (endIdx === -1) continue;
-      const fm = parseYaml4(raw.slice(3, endIdx).trim());
+      const fm = parseYaml6(raw.slice(3, endIdx).trim());
       const fmId = fm && typeof fm === "object" && typeof fm.id === "string" ? fm.id : null;
       if (fmId && (fmId === id || fmId === baseId)) {
         return file;
@@ -14910,9 +16425,9 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
       for (const id of ids) allContentIds.add(id);
     }
     for (const { dir } of CUSTOMIZATION_TYPES) {
-      const customDir = join35(rootDir, ".hatch3r", dir);
+      const customDir = join37(rootDir, ".hatch3r", dir);
       try {
-        const files = await readdir16(customDir);
+        const files = await readdir18(customDir);
         for (const f of files.filter((f2) => f2.endsWith(".customize.yaml") || f2.endsWith(".customize.md"))) {
           const itemId = f.replace(/\.customize\.(yaml|md)$/, "");
           if (!allContentIds.has(itemId) && !allContentIds.has(`${HATCH3R_PREFIX}${itemId}`) && !allContentIds.has(`cmd-${itemId}`) && !allContentIds.has(`cmd-${HATCH3R_PREFIX}${itemId}`)) {
@@ -14924,7 +16439,7 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
       }
     }
   }
-  const learningsDir = join35(agentsDir, "learnings");
+  const learningsDir = join37(agentsDir, "learnings");
   const learningsResult = await validateLearningsDirectory(learningsDir);
   for (const e of learningsResult.errors) {
     result.errors.push(e);
@@ -14932,6 +16447,17 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
   for (const w of learningsResult.warnings) {
     result.warnings.push(w);
   }
+  const handoffsActiveDir = join37(agentsDir, "handoffs", "active");
+  const handoffsArchivedDir = join37(agentsDir, "handoffs", "archived");
+  const handoffsResult = await validateHandoffsDirectory(handoffsActiveDir, {
+    archivedDir: handoffsArchivedDir
+  });
+  for (const e of handoffsResult.errors) {
+    result.errors.push(e);
+  }
+  for (const w of handoffsResult.warnings) {
+    result.warnings.push(w);
+  }
 }
 var USER_CONTENT_ANTI_SLOP = [
   "best possible",
@@ -14961,7 +16487,7 @@ var USER_CONTENT_TYPE_DIRS = {
 async function validateUserContent(rootDir, agentsDir, result, index) {
   const userRoot = resolveUserContentRoot(rootDir);
   try {
-    await stat9(userRoot);
+    await stat11(userRoot);
   } catch (err) {
     if (err.code === "ENOENT") return;
     throw err;
@@ -14970,10 +16496,10 @@ async function validateUserContent(rootDir, agentsDir, result, index) {
   if (userItems.length === 0) return;
   for (const item of userItems) {
     const fileLabel = `.agents/user/${item.relativePath}`;
-    const absPath = item.type === "skill" ? join35(userRoot, item.relativePath, "SKILL.md") : join35(userRoot, item.relativePath);
+    const absPath = item.type === "skill" ? join37(userRoot, item.relativePath, "SKILL.md") : join37(userRoot, item.relativePath);
     let raw;
     try {
-      raw = await readFile26(absPath, "utf-8");
+      raw = await readFile28(absPath, "utf-8");
     } catch (err) {
       result.errors.push(
         `User content unreadable: ${fileLabel} (${err instanceof Error ? err.message : String(err)})`
@@ -14997,7 +16523,7 @@ async function validateUserContent(rootDir, agentsDir, result, index) {
     const fmRaw = raw.slice(3, fmEnd).trim();
     let fm;
     try {
-      fm = parseYaml4(fmRaw);
+      fm = parseYaml6(fmRaw);
     } catch (err) {
       result.errors.push(
         `${fileLabel}: YAML parse error in frontmatter \u2014 ${err instanceof Error ? err.message : String(err)}`
@@ -15057,7 +16583,7 @@ async function validateUserContent(rootDir, agentsDir, result, index) {
     if (item.type === "rule") {
       const mdcPath = absPath.replace(/\.md$/, ".mdc");
       try {
-        await stat9(mdcPath);
+        await stat11(mdcPath);
       } catch (err) {
         if (err.code === "ENOENT") {
           result.errors.push(
@@ -15225,16 +16751,16 @@ async function validateDocsCounts(rootDir) {
   let checked = 0;
   const actual = {};
   const dirs = [
-    ["adapters", join35(rootDir, "src/adapters"), (e) => e.endsWith(".ts") && !["base.ts", "index.ts", "canonical.ts", "customization.ts", "types.ts", "mcp-utils.ts", "toml-utils.ts", "contextBudget.ts"].includes(e)],
-    ["commands", join35(rootDir, "src/cli/commands"), (e) => e.endsWith(".ts")],
-    ["agents", join35(rootDir, "agents"), (e) => e.endsWith(".md")],
-    ["skills", join35(rootDir, "skills"), (e) => true],
-    ["rules", join35(rootDir, "rules"), (e) => e.endsWith(".md")],
-    ["hooks", join35(rootDir, "hooks"), (e) => e.endsWith(".md")]
+    ["adapters", join37(rootDir, "src/adapters"), (e) => e.endsWith(".ts") && !["base.ts", "index.ts", "canonical.ts", "customization.ts", "types.ts", "mcp-utils.ts", "toml-utils.ts", "contextBudget.ts"].includes(e)],
+    ["commands", join37(rootDir, "src/cli/commands"), (e) => e.endsWith(".ts")],
+    ["agents", join37(rootDir, "agents"), (e) => e.endsWith(".md")],
+    ["skills", join37(rootDir, "skills"), (e) => true],
+    ["rules", join37(rootDir, "rules"), (e) => e.endsWith(".md")],
+    ["hooks", join37(rootDir, "hooks"), (e) => e.endsWith(".md")]
   ];
   for (const [name, dir, filter] of dirs) {
     try {
-      const entries = await readdir16(dir, { withFileTypes: true });
+      const entries = await readdir18(dir, { withFileTypes: true });
       if (name === "skills") {
         actual[name] = entries.filter((e) => e.isDirectory()).length;
       } else {
@@ -15244,9 +16770,9 @@ async function validateDocsCounts(rootDir) {
       actual[name] = 0;
     }
   }
-  const readmePath = join35(rootDir, "README.md");
+  const readmePath = join37(rootDir, "README.md");
   try {
-    const readme = await readFile26(readmePath, "utf-8");
+    const readme = await readFile28(readmePath, "utf-8");
     const countPatterns = [
       ["adapters", /(\d+)\s+Adapters/i],
       ["skills", /(\d+)\s+skills/i],
@@ -15319,11 +16845,11 @@ async function validateCommand(opts) {
     }
     return;
   }
-  const agentsDir = join35(rootDir, AGENTS_DIR);
+  const agentsDir = join37(rootDir, AGENTS_DIR);
   const result = { errors: [], warnings: [] };
   const spinner = jsonMode ? null : createSpinner("Validating .agents/ structure...");
   spinner?.start();
-  const cwdIsFrameworkSource = existsSync4(join35(rootDir, "agents")) && existsSync4(join35(rootDir, "skills")) && existsSync4(join35(rootDir, "rules")) && existsSync4(join35(rootDir, "commands"));
+  const cwdIsFrameworkSource = existsSync4(join37(rootDir, "agents")) && existsSync4(join37(rootDir, "skills")) && existsSync4(join37(rootDir, "rules")) && existsSync4(join37(rootDir, "commands"));
   try {
     await access11(agentsDir);
   } catch (err) {
@@ -15361,9 +16887,9 @@ async function validateCommand(opts) {
         printBox(
           "Canonical content lint failed",
           [
-            `${chalk10.red("\u2716")} ${result.errors.length} error(s)`,
-            `${chalk10.yellow("\u26A0")} ${result.warnings.length} warning(s)`,
-            chalk10.dim("(framework-source mode \u2014 .agents/ not required)")
+            `${chalk12.red("\u2716")} ${result.errors.length} error(s)`,
+            `${chalk12.yellow("\u26A0")} ${result.warnings.length} warning(s)`,
+            chalk12.dim("(framework-source mode \u2014 .agents/ not required)")
           ],
           "error"
         );
@@ -15376,16 +16902,16 @@ async function validateCommand(opts) {
         printBox(
           "Canonical content lint",
           [
-            `${chalk10.green("\u2714")} 0 errors`,
-            `${chalk10.yellow("\u26A0")} ${result.warnings.length} warning(s)`,
-            chalk10.dim("(framework-source mode \u2014 .agents/ not required)")
+            `${chalk12.green("\u2714")} 0 errors`,
+            `${chalk12.yellow("\u26A0")} ${result.warnings.length} warning(s)`,
+            chalk12.dim("(framework-source mode \u2014 .agents/ not required)")
           ],
           "success"
         );
       } else {
         printBox(
           "Canonical content lint",
-          [chalk10.green("All checks passed")],
+          [chalk12.green("All checks passed")],
           "success"
         );
       }
@@ -15426,6 +16952,8 @@ async function validateCommand(opts) {
     await validateHooks(agentsDir, manifest, result);
     verbose("Checking MCP configuration...");
     await validateMcp(agentsDir, manifest, result);
+    verbose("Checking CLI tools...");
+    await validateCliTools(manifest, result);
     verbose("Checking model configuration...");
     await validateModels(manifest, result);
     verbose("Checking cost tracking...");
@@ -15482,7 +17010,7 @@ async function validateCommand(opts) {
   let hasCustomizations = false;
   for (const { dir } of CUSTOMIZATION_TYPES) {
     try {
-      const files = await readdir16(join35(rootDir, ".hatch3r", dir));
+      const files = await readdir18(join37(rootDir, ".hatch3r", dir));
       if (files.some((f) => f.endsWith(".customize.yaml") || f.endsWith(".customize.md"))) {
         hasCustomizations = true;
         break;
@@ -15510,7 +17038,7 @@ async function validateCommand(opts) {
     return;
   }
   if (result.errors.length === 0 && result.warnings.length === 0) {
-    printBox("Validation", [chalk10.green("All checks passed")], "success");
+    printBox("Validation", [chalk12.green("All checks passed")], "success");
     if (hasCustomizations) {
       printCustomizationHint();
     }
@@ -15531,15 +17059,15 @@ async function validateCommand(opts) {
   }
   if (result.errors.length > 0) {
     const summaryLines = [
-      `${chalk10.red("\u2716")} ${result.errors.length} error(s)`,
-      `${chalk10.yellow("\u26A0")} ${result.warnings.length} warning(s)`
+      `${chalk12.red("\u2716")} ${result.errors.length} error(s)`,
+      `${chalk12.yellow("\u26A0")} ${result.warnings.length} warning(s)`
     ];
     printBox("Validation failed", summaryLines, "error");
     throw new HatchError("Validation failed", 1, "VALIDATION_ERROR");
   } else {
     const summaryLines = [
-      `${chalk10.green("\u2714")} 0 errors`,
-      `${chalk10.yellow("\u26A0")} ${result.warnings.length} warning(s)`
+      `${chalk12.green("\u2714")} 0 errors`,
+      `${chalk12.yellow("\u26A0")} ${result.warnings.length} warning(s)`
     ];
     printBox("Validation passed", summaryLines, "success");
   }
@@ -15548,10 +17076,10 @@ async function validateCommand(opts) {
   }
 }
 async function validateEnvMcpSecrets(rootDir, result) {
-  const envMcpPath = join35(rootDir, ".env.mcp");
+  const envMcpPath = join37(rootDir, ".env.mcp");
   if (!existsSync4(envMcpPath)) return;
   try {
-    const raw = await readFile26(envMcpPath, "utf-8");
+    const raw = await readFile28(envMcpPath, "utf-8");
     const vars = parseEnvFile(raw);
     const detection = detectSecrets(vars);
     for (const finding of detection.findings) {
@@ -15568,7 +17096,7 @@ async function validateEnvMcpSecrets(rootDir, result) {
 async function validateCanonicalDescriptionQuality(rootDir, result) {
   const __filename = fileURLToPath8(import.meta.url);
   const packageRoot = findPackageRoot(dirname18(__filename));
-  const canonicalRoot = existsSync4(join35(rootDir, "agents")) && existsSync4(join35(rootDir, "skills")) && existsSync4(join35(rootDir, "rules")) && existsSync4(join35(rootDir, "commands")) ? rootDir : packageRoot;
+  const canonicalRoot = existsSync4(join37(rootDir, "agents")) && existsSync4(join37(rootDir, "skills")) && existsSync4(join37(rootDir, "rules")) && existsSync4(join37(rootDir, "commands")) ? rootDir : packageRoot;
   try {
     const index = await buildContentIndex(canonicalRoot);
     if (index.items.length === 0) return;
@@ -15607,14 +17135,14 @@ async function validateSecurityCompliance(result) {
 }
 function printCustomizationHint() {
   console.log();
-  info(chalk10.bold("Customization mechanisms detected. Quick reference:"));
-  console.log(chalk10.dim("  1. hatch3r- prefix: Files prefixed with hatch3r- are managed by hatch3r and"));
-  console.log(chalk10.dim("     overwritten on update. Do not edit these directly."));
-  console.log(chalk10.dim("  2. Managed blocks: Sections between <!-- HATCH3R:BEGIN --> and"));
-  console.log(chalk10.dim("     <!-- HATCH3R:END --> are auto-updated. Add content outside these markers."));
-  console.log(chalk10.dim("  3. .customize.yaml/.md: Place in .hatch3r/{type}/ to override model, scope,"));
-  console.log(chalk10.dim("     description, or disable items. Use .customize.md for content additions."));
-  console.log(chalk10.dim("  See: https://docs.hatch3r.com/docs/guides/customization"));
+  info(chalk12.bold("Customization mechanisms detected. Quick reference:"));
+  console.log(chalk12.dim("  1. hatch3r- prefix: Files prefixed with hatch3r- are managed by hatch3r and"));
+  console.log(chalk12.dim("     overwritten on update. Do not edit these directly."));
+  console.log(chalk12.dim("  2. Managed blocks: Sections between <!-- HATCH3R:BEGIN --> and"));
+  console.log(chalk12.dim("     <!-- HATCH3R:END --> are auto-updated. Add content outside these markers."));
+  console.log(chalk12.dim("  3. .customize.yaml/.md: Place in .hatch3r/{type}/ to override model, scope,"));
+  console.log(chalk12.dim("     description, or disable items. Use .customize.md for content additions."));
+  console.log(chalk12.dim("  See: https://docs.hatch3r.com/docs/guides/customization"));
 }
 
 // src/cli/commands/verify.ts
@@ -15626,26 +17154,26 @@ init_pipelineTimeout();
 init_phaseOutputSchema();
 init_retryWithBackoff();
 init_ui();
-import { join as join36 } from "path";
-import chalk11 from "chalk";
+import { join as join38 } from "path";
+import chalk13 from "chalk";
 async function runVerifyPass(agentsDir) {
   const results = await verifyIntegrity(agentsDir);
   if (results.length === 0) {
     return { passed: true, counts: { pass: 0 }, hasModifiedOrMissing: false, hasTampered: false };
   }
   const icons = {
-    pass: chalk11.green("\u2714"),
-    modified: chalk11.yellow("\u2716"),
-    missing: chalk11.red("\u2716"),
-    new: chalk11.cyan("+"),
-    tampered: chalk11.red("\u26A0")
+    pass: chalk13.green("\u2714"),
+    modified: chalk13.yellow("\u2716"),
+    missing: chalk13.red("\u2716"),
+    new: chalk13.cyan("+"),
+    tampered: chalk13.red("\u26A0")
   };
   const labels = {
-    pass: chalk11.green("PASS"),
-    modified: chalk11.yellow("MODIFIED"),
-    missing: chalk11.red("MISSING"),
-    new: chalk11.cyan("NEW"),
-    tampered: chalk11.red("TAMPERED")
+    pass: chalk13.green("PASS"),
+    modified: chalk13.yellow("MODIFIED"),
+    missing: chalk13.red("MISSING"),
+    new: chalk13.cyan("NEW"),
+    tampered: chalk13.red("TAMPERED")
   };
   console.log();
   for (const r of results) {
@@ -15665,11 +17193,11 @@ async function runVerifyPass(agentsDir) {
 }
 function printSummary(counts, title, style) {
   const summaryLines = [];
-  if ((counts.pass ?? 0) > 0) summaryLines.push(`${chalk11.green("\u2714")} Passed: ${counts.pass}`);
-  if ((counts.modified ?? 0) > 0) summaryLines.push(`${chalk11.yellow("\u2716")} Modified: ${counts.modified}`);
-  if ((counts.missing ?? 0) > 0) summaryLines.push(`${chalk11.red("\u2716")} Missing: ${counts.missing}`);
-  if ((counts.new ?? 0) > 0) summaryLines.push(`${chalk11.cyan("+")} New: ${counts.new}`);
-  if ((counts.tampered ?? 0) > 0) summaryLines.push(`${chalk11.red("\u26A0")} Tampered: ${counts.tampered}`);
+  if ((counts.pass ?? 0) > 0) summaryLines.push(`${chalk13.green("\u2714")} Passed: ${counts.pass}`);
+  if ((counts.modified ?? 0) > 0) summaryLines.push(`${chalk13.yellow("\u2716")} Modified: ${counts.modified}`);
+  if ((counts.missing ?? 0) > 0) summaryLines.push(`${chalk13.red("\u2716")} Missing: ${counts.missing}`);
+  if ((counts.new ?? 0) > 0) summaryLines.push(`${chalk13.cyan("+")} New: ${counts.new}`);
+  if ((counts.tampered ?? 0) > 0) summaryLines.push(`${chalk13.red("\u26A0")} Tampered: ${counts.tampered}`);
   printBox(title, summaryLines, style);
 }
 var MAX_FIX_ATTEMPTS = 5;
@@ -15680,7 +17208,7 @@ async function verifyCommand(options = {}) {
     DEFAULT_PIPELINE_TIMEOUT_MS
   );
   const rootDir = process.cwd();
-  const agentsDir = join36(rootDir, AGENTS_DIR);
+  const agentsDir = join38(rootDir, AGENTS_DIR);
   const spinner = createSpinner("Verifying file integrity...");
   spinner.start();
   const manifest = await readIntegrityManifest(agentsDir);
@@ -15706,7 +17234,7 @@ async function verifyCommand(options = {}) {
   const compactedCounts = compactPhaseOutput(result.counts);
   if (result.passed) {
     if (compactedCounts.pass === 0) {
-      printBox("Integrity", [chalk11.dim("No files to verify")], "info");
+      printBox("Integrity", [chalk13.dim("No files to verify")], "info");
     } else {
       printSummary(compactedCounts, "Integrity check passed", "success");
     }
@@ -15722,7 +17250,7 @@ async function verifyCommand(options = {}) {
       error("Integrity manifest has been tampered with. Re-run `hatch3r update` to regenerate it.");
     }
     if ((result.counts.modified ?? 0) > 0) {
-      info(`Modified files may have been tampered with. Run ${chalk11.bold("hatch3r update")} to restore originals.`);
+      info(`Modified files may have been tampered with. Run ${chalk13.bold("hatch3r update")} to restore originals.`);
     }
     console.log();
     throw new HatchError("Integrity check failed", 1, "INTEGRITY_ERROR");
@@ -15815,24 +17343,24 @@ init_adapters();
 init_types();
 init_managedBlocks();
 init_integrity();
-import { access as access12, readFile as readFile27, readdir as readdir17, stat as stat10 } from "fs/promises";
-import { join as join37 } from "path";
-import chalk12 from "chalk";
+import { access as access12, readFile as readFile29, readdir as readdir19, stat as stat12 } from "fs/promises";
+import { join as join39 } from "path";
+import chalk14 from "chalk";
 init_ui();
 async function dirCharCount(dir) {
   let total = 0;
   let entries;
   try {
-    entries = await readdir17(dir, { withFileTypes: true });
+    entries = await readdir19(dir, { withFileTypes: true });
   } catch {
     return 0;
   }
   for (const entry of entries) {
-    const fullPath = join37(dir, entry.name);
+    const fullPath = join39(dir, entry.name);
     if (entry.isDirectory()) {
       total += await dirCharCount(fullPath);
     } else if (entry.isFile()) {
-      const info2 = await stat10(fullPath);
+      const info2 = await stat12(fullPath);
       total += info2.size;
     }
   }
@@ -15854,7 +17382,7 @@ async function runFastStatusCheck(rootDir, agentsDir, manifest) {
     const successful = new Set(integrityManifest.successfulAdapters);
     for (const tool of expected) {
       if (!successful.has(tool)) {
-        fileLines.push(chalk12.yellow(`${tool}: last sync did not complete (check hatch3r sync output)`));
+        fileLines.push(chalk14.yellow(`${tool}: last sync did not complete (check hatch3r sync output)`));
       }
     }
   }
@@ -15862,21 +17390,21 @@ async function runFastStatusCheck(rootDir, agentsDir, manifest) {
     const adapter = getAdapter(tool);
     const paths = await adapter.getOutputPaths(agentsDir, manifest);
     verbose(`${tool}: ${paths.length} output path(s) to check (fast path)`);
-    fileLines.push(chalk12.bold(`${tool}:`));
+    fileLines.push(chalk14.bold(`${tool}:`));
     for (const p of paths) {
-      const destPath = join37(rootDir, p);
+      const destPath = join39(rootDir, p);
       try {
-        const fileStat = await stat10(destPath);
+        const fileStat = await stat12(destPath);
         if (fileStat.mtimeMs > sealMs) {
-          fileLines.push(`  ${chalk12.yellow("~")} ${p} ${chalk12.dim("(drifted)")}`);
+          fileLines.push(`  ${chalk14.yellow("~")} ${p} ${chalk14.dim("(drifted)")}`);
           stats.drifted++;
         } else {
-          fileLines.push(`  ${chalk12.green("=")} ${p}`);
+          fileLines.push(`  ${chalk14.green("=")} ${p}`);
           stats.synced++;
         }
       } catch (err) {
         if (err.code !== "ENOENT") throw err;
-        fileLines.push(`  ${chalk12.red("+")} ${p} ${chalk12.dim("(missing)")}`);
+        fileLines.push(`  ${chalk14.red("+")} ${p} ${chalk14.dim("(missing)")}`);
         stats.missing++;
       }
     }
@@ -15890,23 +17418,23 @@ async function runDeepStatusCheck(rootDir, agentsDir, manifest) {
     const adapter = getAdapter(tool);
     const outputs = await adapter.generate(agentsDir, manifest);
     verbose(`${tool}: ${outputs.length} output file(s) to check`);
-    fileLines.push(chalk12.bold(`${tool}:`));
+    fileLines.push(chalk14.bold(`${tool}:`));
     for (const out of outputs) {
-      const destPath = join37(rootDir, out.path);
+      const destPath = join39(rootDir, out.path);
       try {
-        const existing = await readFile27(destPath, "utf-8");
+        const existing = await readFile29(destPath, "utf-8");
         const existingBlock = extractManagedBlock(existing);
         const expectedBlock = out.managedContent ?? extractManagedBlock(out.content);
         if (existingBlock !== null && expectedBlock !== null ? existingBlock === expectedBlock : existing === out.content) {
-          fileLines.push(`  ${chalk12.green("=")} ${out.path}`);
+          fileLines.push(`  ${chalk14.green("=")} ${out.path}`);
           stats.synced++;
         } else {
-          fileLines.push(`  ${chalk12.yellow("~")} ${out.path} ${chalk12.dim("(drifted)")}`);
+          fileLines.push(`  ${chalk14.yellow("~")} ${out.path} ${chalk14.dim("(drifted)")}`);
           stats.drifted++;
         }
       } catch (err) {
         if (err.code !== "ENOENT") throw err;
-        fileLines.push(`  ${chalk12.red("+")} ${out.path} ${chalk12.dim("(missing)")}`);
+        fileLines.push(`  ${chalk14.red("+")} ${out.path} ${chalk14.dim("(missing)")}`);
         stats.missing++;
       }
     }
@@ -15917,11 +17445,11 @@ async function statusCommand(opts) {
   setVerbose(!!opts?.verbose);
   printBanner(true);
   const rootDir = process.cwd();
-  const agentsDir = join37(rootDir, AGENTS_DIR);
+  const agentsDir = join39(rootDir, AGENTS_DIR);
   const manifest = await readManifest(rootDir);
   if (!manifest) {
     error("No .agents/hatch.json found.");
-    console.log(chalk12.dim("  Run `npx hatch3r init` to set up your project first.\n"));
+    console.log(chalk14.dim("  Run `npx hatch3r init` to set up your project first.\n"));
     throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const spinner = createSpinner("Checking sync status...");
@@ -15948,27 +17476,44 @@ async function statusCommand(opts) {
   }
   console.log();
   const summaryLines = [
-    `${chalk12.green("=")} In sync: ${stats.synced}`
+    `${chalk14.green("=")} In sync: ${stats.synced}`
   ];
   if (stats.drifted > 0) {
-    summaryLines.push(`${chalk12.yellow("~")} Drifted: ${stats.drifted}`);
+    summaryLines.push(`${chalk14.yellow("~")} Drifted: ${stats.drifted}`);
   }
   if (stats.missing > 0) {
-    summaryLines.push(`${chalk12.red("+")} Missing: ${stats.missing}`);
+    summaryLines.push(`${chalk14.red("+")} Missing: ${stats.missing}`);
   }
   const totalChars = await dirCharCount(agentsDir);
   const estimatedTokens = Math.round(totalChars / 4);
   const formattedTokens = estimatedTokens.toLocaleString("en-US");
-  summaryLines.push(`${chalk12.dim("~")} Estimated canonical tokens: ~${formattedTokens}`);
+  summaryLines.push(`${chalk14.dim("~")} Estimated canonical tokens: ~${formattedTokens}`);
   if (usedFastPath) {
-    summaryLines.push(chalk12.dim("mode: fast (integrity-manifest). Pass --deep for byte-for-byte regeneration check."));
+    summaryLines.push(chalk14.dim("mode: fast (integrity-manifest). Pass --deep for byte-for-byte regeneration check."));
   }
   const style = stats.drifted > 0 || stats.missing > 0 ? "info" : "success";
   printBox("Status", summaryLines, style);
   if (stats.drifted > 0 || stats.missing > 0) {
-    info(`Run ${chalk12.bold("hatch3r sync")} to regenerate drifted/missing files.`);
+    info(`Run ${chalk14.bold("hatch3r sync")} to regenerate drifted/missing files.`);
     console.log();
   }
+  const cliSelected = manifest.cliTools?.selected ?? [];
+  if (manifest.cliTools?.enabled && cliSelected.length > 0) {
+    const cliResults = await detectCliTools(cliSelected);
+    const installed = cliResults.filter((r) => r.installed).length;
+    const cliLines = [];
+    cliLines.push(label("Installed", `${installed}/${cliResults.length}`));
+    const missing = cliResults.filter((r) => !r.installed);
+    if (missing.length > 0) {
+      cliLines.push("");
+      for (const r of missing) {
+        cliLines.push(`  ${chalk14.yellow("\u2717")} ${r.id} not on PATH`);
+      }
+      cliLines.push("");
+      cliLines.push(chalk14.dim(`Run \`npx hatch3r cli-tools install\` to see install commands.`));
+    }
+    printBox("CLI tools", cliLines, missing.length === 0 ? "success" : "info");
+  }
   let userTypes = null;
   let userTotal = 0;
   let userLastModified = null;
@@ -16006,7 +17551,7 @@ async function statusCommand(opts) {
     printBox("User content", userLines, "info");
   }
   if (manifest.tools.includes("codex")) {
-    const overridePath = join37(rootDir, "AGENTS.override.md");
+    const overridePath = join39(rootDir, "AGENTS.override.md");
     try {
       await access12(overridePath);
       warn(
@@ -16022,34 +17567,341 @@ async function statusCommand(opts) {
   if (wsManifest && wsManifest.repos.length > 0) {
     const wsLines = [];
     for (const repo of wsManifest.repos) {
-      const icon = repo.sync ? chalk12.green("\u2713") : chalk12.dim("\u25CB");
+      const icon = repo.sync ? chalk14.green("\u2713") : chalk14.dim("\u25CB");
       let detail;
       if (!repo.sync) {
-        detail = chalk12.dim("sync disabled");
+        detail = chalk14.dim("sync disabled");
       } else if (repo.lastSync) {
         const elapsed = Math.max(0, Date.now() - new Date(repo.lastSync).getTime());
         const hours = Math.floor(elapsed / (1e3 * 60 * 60));
         const timeAgo = hours < 1 ? "just now" : hours < 24 ? `${hours}h ago` : `${Math.floor(hours / 24)}d ago`;
         detail = `synced ${timeAgo}`;
       } else {
-        detail = chalk12.yellow("never synced");
+        detail = chalk14.yellow("never synced");
       }
-      const identity = repo.owner && repo.repo ? chalk12.dim(`${repo.owner}/${repo.repo}`) : "";
-      const branch = repo.defaultBranch ? chalk12.dim(`[${repo.defaultBranch}]`) : "";
+      const identity = repo.owner && repo.repo ? chalk14.dim(`${repo.owner}/${repo.repo}`) : "";
+      const branch = repo.defaultBranch ? chalk14.dim(`[${repo.defaultBranch}]`) : "";
       const identityPart = identity || branch ? `  ${identity} ${branch}` : "";
-      wsLines.push(`${icon} ${repo.name ?? repo.path}${identityPart}  ${chalk12.dim(`(${detail})`)}`);
+      wsLines.push(`${icon} ${repo.name ?? repo.path}${identityPart}  ${chalk14.dim(`(${detail})`)}`);
     }
     printBox(`Workspace: ${wsManifest.name} (${wsManifest.repos.length} repos)`, wsLines, "info");
   }
   if (manifest.workspace) {
     const wsInfo = [
-      `Managed by workspace at ${chalk12.bold(manifest.workspace.rootPath)}`,
+      `Managed by workspace at ${chalk14.bold(manifest.workspace.rootPath)}`,
       `Last synced: ${manifest.workspace.lastSync ? new Date(manifest.workspace.lastSync).toLocaleString() : "never"}`
     ];
     printBox("Workspace member", wsInfo, "info");
   }
 }
 
+// src/cli/commands/mcp.ts
+init_hatchJson();
+init_types();
+init_mcpEnv();
+init_ui();
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile30 } from "fs/promises";
+import { join as join40 } from "path";
+import chalk15 from "chalk";
+function requireManifest(rootDir, manifest) {
+  if (!manifest) {
+    error("No .agents/hatch.json found.");
+    console.log(chalk15.dim(`  Run \`npx hatch3r init\` to set up your project first.
+`));
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
+  }
+}
+function wslThemeOrUndefined() {
+  return isWSL() ? { icon: { checked: chalk15.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+}
+async function mcpSetupCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest(rootDir, manifest);
+  const platform = manifest.platform ?? "github";
+  const selected = await pickMcpServers({
+    platform,
+    existing: manifest.mcp.servers,
+    wslTheme: wslThemeOrUndefined()
+  });
+  manifest.mcp = { servers: selected };
+  await writeManifest(rootDir, manifest);
+  if (selected.length > 0) {
+    const envResult = await ensureEnvMcp(rootDir, selected);
+    await ensureGitignoreEntry(rootDir);
+    if (envResult.newVars.length > 0) {
+      warn(`Add new secrets to .env.mcp: ${envResult.newVars.join(", ")}`);
+      info(`Run this then start/restart your editor: ${getSourceEnvMcpCommand()}`);
+    }
+  }
+  printBox(
+    "MCP configured",
+    [
+      label("Servers", selected.length > 0 ? selected.join(", ") : "none"),
+      label("Manifest", ".agents/hatch.json"),
+      label("Next", "Run `npx hatch3r sync` to regenerate adapter MCP configs")
+    ],
+    "success"
+  );
+}
+async function mcpListCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest(rootDir, manifest);
+  const servers = manifest.mcp.servers;
+  const envPath = join40(rootDir, ".env.mcp");
+  const hasEnvFile = existsSync5(envPath);
+  const envExisting = hasEnvFile ? parseEnvFile(await readFile30(envPath, "utf-8")) : {};
+  const requiredVars = collectRequiredEnvVars(servers);
+  const missingVars = requiredVars.filter((v) => !(v.name in envExisting) || envExisting[v.name] === "");
+  const lines = [];
+  if (servers.length === 0) {
+    lines.push("(no MCP servers configured)");
+    lines.push("");
+    lines.push("Run `npx hatch3r mcp setup` to open the server picker.");
+  } else {
+    for (const id of servers) {
+      const meta = AVAILABLE_MCP_SERVERS[id];
+      const desc = meta?.description ?? "(unknown server)";
+      lines.push(`  ${chalk15.cyan(id)} \u2014 ${desc}`);
+    }
+    lines.push("");
+    lines.push(label(".env.mcp", hasEnvFile ? "present" : chalk15.yellow("missing")));
+    if (requiredVars.length > 0) {
+      lines.push(label("Required vars", requiredVars.map((v) => v.name).join(", ")));
+      if (missingVars.length > 0) {
+        lines.push(label("Missing", chalk15.yellow(missingVars.map((v) => v.name).join(", "))));
+      } else {
+        lines.push(label("Status", chalk15.green("all required vars set")));
+      }
+    }
+  }
+  printBox("MCP servers", lines, "info");
+}
+async function mcpRemoveCommand(id) {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest(rootDir, manifest);
+  const before = manifest.mcp.servers;
+  if (!before.includes(id)) {
+    error(`MCP server "${id}" is not configured.`);
+    console.log(chalk15.dim(`  Current servers: ${before.length > 0 ? before.join(", ") : "(none)"}
+`));
+    throw new HatchError(`MCP server "${id}" not configured`, 1, "VALIDATION_ERROR");
+  }
+  manifest.mcp = { servers: before.filter((s) => s !== id) };
+  await writeManifest(rootDir, manifest);
+  printBox(
+    "MCP server removed",
+    [
+      label("Removed", id),
+      label("Remaining", manifest.mcp.servers.length > 0 ? manifest.mcp.servers.join(", ") : "none"),
+      label("Next", "Run `npx hatch3r sync` to regenerate adapter MCP configs")
+    ],
+    "success"
+  );
+}
+async function mcpEnvCheckCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest(rootDir, manifest);
+  const servers = manifest.mcp.servers;
+  const envPath = join40(rootDir, ".env.mcp");
+  const hasEnvFile = existsSync5(envPath);
+  const envExisting = hasEnvFile ? parseEnvFile(await readFile30(envPath, "utf-8")) : {};
+  const lines = [];
+  if (servers.length === 0) {
+    lines.push("(no MCP servers configured \u2014 nothing to check)");
+    printBox("MCP env check", lines, "info");
+    return;
+  }
+  let missingTotal = 0;
+  for (const id of servers) {
+    const meta = AVAILABLE_MCP_SERVERS[id];
+    const required = meta?.requiresEnv ?? [];
+    if (required.length === 0) {
+      lines.push(`${chalk15.green("\u2713")} ${id} \u2014 no env vars required`);
+      continue;
+    }
+    const missing = required.filter((name) => !(name in envExisting) || envExisting[name] === "");
+    if (missing.length === 0) {
+      lines.push(`${chalk15.green("\u2713")} ${id} \u2014 ${required.join(", ")}`);
+    } else {
+      lines.push(`${chalk15.yellow("!")} ${id} \u2014 missing: ${missing.join(", ")}`);
+      missingTotal += missing.length;
+    }
+  }
+  lines.push("");
+  lines.push(label(".env.mcp", hasEnvFile ? "present" : chalk15.yellow("missing")));
+  if (missingTotal > 0) {
+    lines.push(label("Action", `Fill ${missingTotal} env var(s) in .env.mcp, then \`${getSourceEnvMcpCommand()}\``));
+  }
+  printBox("MCP env check", lines, missingTotal > 0 ? "info" : "success");
+}
+
+// src/cli/commands/cliTools.ts
+init_hatchJson();
+init_types();
+import chalk16 from "chalk";
+init_ui();
+function requireManifest2(_rootDir, manifest) {
+  if (!manifest) {
+    error("No .agents/hatch.json found.");
+    console.log(chalk16.dim(`  Run \`npx hatch3r init\` to set up your project first.
+`));
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
+  }
+}
+function wslThemeOrUndefined2() {
+  return isWSL() ? { icon: { checked: chalk16.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+}
+async function cliToolsCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest2(rootDir, manifest);
+  const existing = manifest.cliTools?.selected ?? [];
+  const selected = await pickCliTools({
+    existing,
+    wslTheme: wslThemeOrUndefined2()
+  });
+  if (selected.length > 0) {
+    const spinner = createSpinner(`Detecting ${selected.length} CLI tool(s)...`);
+    spinner.start();
+    const missing = await findMissingCliTools(selected);
+    if (missing.length === 0) {
+      spinner.succeed(`All ${selected.length} CLI tool(s) detected on PATH`);
+    } else {
+      spinner.warn(`${selected.length - missing.length}/${selected.length} CLI tool(s) detected; ${missing.length} missing`);
+      await offerInstaller(missing, { interactive: true });
+    }
+    const secretNotes = [];
+    for (const id of selected) {
+      const notes = CLI_TOOL_SECRET_NOTES[id];
+      if (notes && notes.length > 0) {
+        secretNotes.push(`${id}: ${notes.join(", ")}`);
+      }
+    }
+    if (secretNotes.length > 0) {
+      info(chalk16.dim("CLI tool environment variables required:"));
+      for (const note of secretNotes) {
+        info(chalk16.dim(`  ${note}`));
+      }
+    }
+  }
+  const cliToolsConfig = {
+    enabled: selected.length > 0,
+    selected
+  };
+  manifest.cliTools = cliToolsConfig;
+  await writeManifest(rootDir, manifest);
+  printBox(
+    "CLI tools configured",
+    [
+      label("Selected", selected.length > 0 ? selected.join(", ") : "none"),
+      label("Manifest", ".agents/hatch.json"),
+      label("Next", "Run `npx hatch3r sync` so adapters re-emit the filtered skill set")
+    ],
+    "success"
+  );
+  if (selected.length > 0) {
+    const finalMissing = await findMissingCliTools(selected);
+    printMissingCliToolsDisclaimer(finalMissing, selected.length);
+  }
+}
+async function cliToolsListCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest2(rootDir, manifest);
+  const selected = manifest.cliTools?.selected ?? [];
+  if (selected.length === 0) {
+    printBox(
+      "CLI tools",
+      [
+        "(no CLI tools selected)",
+        "",
+        "Run `npx hatch3r cli-tools` to open the picker."
+      ],
+      "info"
+    );
+    return;
+  }
+  const results = await detectCliTools(selected);
+  const lines = [];
+  for (const r of results) {
+    const meta = AVAILABLE_CLI_TOOLS[r.id];
+    const tierLabel = meta ? `tier ${meta.tier}` : "(unknown)";
+    const status = r.installed ? `${chalk16.green("\u2713")} ${r.path}` : `${chalk16.yellow("\u2717")} not on PATH`;
+    lines.push(`  ${chalk16.cyan(r.id)} (${tierLabel}) \u2014 ${status}`);
+  }
+  const installed = results.filter((r) => r.installed).length;
+  lines.push("");
+  lines.push(label("Detected", `${installed}/${results.length} installed`));
+  printBox("CLI tools", lines, installed === results.length ? "success" : "info");
+}
+async function cliToolsInstallCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest2(rootDir, manifest);
+  const selected = manifest.cliTools?.selected ?? [];
+  if (selected.length === 0) {
+    info("No CLI tools selected \u2014 run `npx hatch3r cli-tools` first to opt in.");
+    return;
+  }
+  const spinner = createSpinner(`Detecting ${selected.length} CLI tool(s)...`);
+  spinner.start();
+  const missing = await findMissingCliTools(selected);
+  if (missing.length === 0) {
+    spinner.succeed(`All ${selected.length} CLI tool(s) already installed`);
+    return;
+  }
+  spinner.warn(`${missing.length}/${selected.length} CLI tool(s) missing`);
+  await offerInstaller(missing, { interactive: true });
+  if (selected.length > 0) {
+    const finalMissing = await findMissingCliTools(selected);
+    printMissingCliToolsDisclaimer(finalMissing, selected.length);
+  }
+}
+async function cliToolsDetectCommand() {
+  printBanner(true);
+  const rootDir = process.cwd();
+  const manifest = await readManifest(rootDir);
+  requireManifest2(rootDir, manifest);
+  const selected = manifest.cliTools?.selected ?? [];
+  if (selected.length === 0) {
+    info("No CLI tools selected \u2014 run `npx hatch3r cli-tools` first to opt in.");
+    return;
+  }
+  const results = await detectCliTools(selected);
+  const lines = [];
+  let installed = 0;
+  for (const r of results) {
+    if (r.installed) {
+      lines.push(`  ${chalk16.green("\u2713")} ${r.id} \u2014 ${r.path}`);
+      installed++;
+    } else {
+      lines.push(`  ${chalk16.yellow("\u2717")} ${r.id} \u2014 not on PATH`);
+    }
+  }
+  lines.push("");
+  lines.push(label("Installed", `${installed}/${results.length}`));
+  if (installed < results.length) {
+    lines.push("");
+    lines.push(`Run ${chalk16.bold("npx hatch3r cli-tools install")} to see install commands.`);
+  }
+  printBox("CLI tool detection", lines, installed === results.length ? "success" : "info");
+  if (installed < results.length) {
+    warn(`${results.length - installed} CLI tool(s) not detected`);
+  }
+}
+
 // src/cli/program.ts
 init_version();
 init_types();
@@ -16097,7 +17949,7 @@ function createProgram() {
   program2.command("init").description("Install a complete agent setup into the current repo (first-run: creates .agents/ directory)").option(
     "--tools <tools>",
     `Comma-separated tools (${TOOL_CHOICES})`
-  ).option("--yes", "Skip interactive prompts, use defaults").option("--quick", "Skip all prompts and use smart defaults (alias for --yes)").option("--default", "Skip all prompts and use smart defaults (alias for --yes)").option("--preset <preset>", "Content preset: minimal, standard, full (default: full)").option("--project-type <type>", "Project type: greenfield, brownfield").option("--team-size <size>", "Team size: solo, team").option("--worktree", "Enable git worktree file isolation (overrides tool auto-detect)").option("--no-worktree", "Disable git worktree file isolation").option("--workspace", "Initialize as a multi-repo workspace").action(initCommand);
+  ).option("--yes", "Skip interactive prompts, use defaults").option("--quick", "Skip all prompts and use smart defaults (alias for --yes)").option("--default", "Skip all prompts and use smart defaults (alias for --yes)").option("--preset <preset>", "Content preset: minimal, standard, full (default: full)").option("--project-type <type>", "Project type: greenfield, brownfield").option("--team-size <size>", "Team size: solo, team").option("--worktree", "Enable git worktree file isolation (overrides tool auto-detect)").option("--no-worktree", "Disable git worktree file isolation").option("--workspace", "Initialize as a multi-repo workspace").option("--cli-tools <ids>", "CLI tools to opt in on --yes: 'tier1', 'all', or comma-separated ids (default: tier-1 + triggered tier-2)").option("--no-cli-tools", "Skip the CLI-tools opt-in on --yes").option("--mcp", "Re-opt-in to MCP servers on --yes (MCP is now opt-in by default)").action(initCommand);
   program2.command("sync").description("Re-generate tool outputs from canonical .agents/ state (run after editing .agents/)").option("--repos [paths...]", "Sync workspace content to sub-repos (all opted-in if no paths given)").option("--dry-run", "Show what would change without modifying files").option("--diff", "Show a before/after diff summary for each generated file").option("--force", "Overwrite locally modified files in sub-repos").option("--minimal", "Generate stripped-down output (no comments, minimal formatting) to reduce token usage").option("--strict-budget", "Fail sync if any adapter's generated output exceeds its context budget (default: warn)").option("--verbose", "Show detailed output for each file processed").action(syncCommand);
   program2.command("status").description("Check sync status between canonical .agents/ and generated files").option("--verbose", "Show detailed per-file status information").option("--deep", "Regenerate every adapter's output in-memory to compare byte-for-byte (slower; default uses integrity-manifest fast path)").action(statusCommand);
   program2.command("update").description("Pull latest hatch3r templates with safe merge (preserves customizations)").option("--yes", "Skip interactive prompts, use defaults").option("--diff", "Show a before/after diff summary for each generated file").option("--force", "Override the preflight integrity check and proceed despite drift").option("--offline, --skip-fetch", "Skip the package fetch step; regenerate only from already-installed canonical content").option("--dry-run", "Preview what would change (added/modified/unchanged per adapter) without writing files").action(updateCommand);
@@ -16128,6 +17980,15 @@ function createProgram() {
   ).action(addCommand);
   program2.command("worktree-setup [name]").description("Create a git worktree by name and populate hatch3r files (auto-resolved to .worktrees/<name>)").option("--from <path>", "Main repo path (auto-detected by default)").option("--from-path <path>", "Legacy mode: populate an existing worktree at <path> (skips git worktree add). Used by editor hooks.").option("--dry-run", "Show what would be done without changes").option("--force", "Overwrite existing files in the worktree").option("--yes", "Skip the secret-propagation confirmation prompt").action(worktreeSetupCommand);
   program2.command("worktree-cleanup").description("Discover hatch3r-managed worktrees from the main repo, then clean files and remove the selected worktree(s)").option("--dry-run", "Show what would be done without changes").option("--all", "Skip the all/specific prompt and clean every hatch3r-managed worktree").option("--yes", "Skip selection and confirmation prompts (implies --all unless paths are filtered upstream)").option("--files-only", "Remove hatch3r-managed files only; keep the git worktree and its directory").action(worktreeCleanupCommand);
+  const mcpCmd = program2.command("mcp").description("Manage MCP servers (now opt-in; CLI tools are the default)");
+  mcpCmd.command("setup").description("Open the MCP server picker and update the manifest + .env.mcp").action(mcpSetupCommand);
+  mcpCmd.command("list").description("Show current MCP server configuration plus .env.mcp status").action(mcpListCommand);
+  mcpCmd.command("remove <id>").description("Remove an MCP server by id").action(mcpRemoveCommand);
+  mcpCmd.command("env-check").description("Audit .env.mcp for missing required environment variables").action(mcpEnvCheckCommand);
+  const cliCmd = program2.command("cli-tools").description("Manage CLI tool integrations (ripgrep, jq, gh, \u2026)").action(cliToolsCommand);
+  cliCmd.command("list").description("Show current CLI tool selection plus detection status").action(cliToolsListCommand);
+  cliCmd.command("install").description("Print install commands for any selected CLI tools missing on PATH").action(cliToolsInstallCommand);
+  cliCmd.command("detect").description("Read-only detection report for the current CLI tool selection").action(cliToolsDetectCommand);
   program2.on("command:*", (operands) => {
     const cmd = operands[0];
     if (cmd && AGENT_COMMAND_NAMES.has(cmd)) {
@@ -16177,15 +18038,15 @@ function classifyCliError(err, flags) {
 // src/cli/shared/updateNotifier.ts
 init_version();
 import updateNotifier from "update-notifier";
-import chalk13 from "chalk";
+import chalk17 from "chalk";
 var ONE_DAY_MS = 1e3 * 60 * 60 * 24;
 function buildMessage(update) {
-  const fromTo = `${chalk13.dim(update.current)} \u2192 ${chalk13.green(update.latest)}`;
-  const cyan = chalk13.hex("#06b6d4");
+  const fromTo = `${chalk17.dim(update.current)} \u2192 ${chalk17.green(update.latest)}`;
+  const cyan = chalk17.hex("#06b6d4");
   return [
     `Update available ${fromTo}`,
-    chalk13.dim("Run ") + cyan("npm i -g hatch3r@latest") + chalk13.dim(" to update the CLI"),
-    chalk13.dim("Then run ") + cyan("hatch3r update") + chalk13.dim(" to refresh project content")
+    chalk17.dim("Run ") + cyan("npm i -g hatch3r@latest") + chalk17.dim(" to update the CLI"),
+    chalk17.dim("Then run ") + cyan("hatch3r update") + chalk17.dim(" to refresh project content")
   ].join("\n");
 }
 function checkForUpdates() {